atelier/examples/bad/leaky-abstraction.md

# Bad Example: Leaky Abstraction

> An abstraction that leaks its implementation details, violating Atelier principles. Each violation is cited.

## The Code

```typescript
// UserRepository — "abstracts" the database
class UserRepository {
  async findAll(): Promise<UserRow[]> {
    // Leaks: returns the raw DB row type, not a domain User
    return db.query('SELECT id, email, password_hash, created_at, deleted_at FROM users');
  }

  async findByEmail(email: string): Promise<UserRow | null> {
    // Leaks: the caller must know to filter deleted_at
    const rows = await db.query('SELECT * FROM users WHERE email = $1', [email]);
    return rows[0] || null;
  }

  async save(user: UserRow): Promise<void> {
    // Leaks: the caller must know the column names and the SQL
    await db.query(
      'UPDATE users SET email = $1, password_hash = $2, updated_at = now() WHERE id = $3',
      [user.email, user.password_hash, user.id]
    );
  }
}

// Usage — the leak is visible
const repo = new UserRepository();
const user = await repo.findByEmail('jane@example.com');
if (user && !user.deleted_at) {  // caller must know about soft delete
  user.password_hash = await hash(newPassword);  // caller must know the column
  await repo.save(user);  // caller must know it's an UPDATE
}
```

## Violations

### C6 Composability (Core)
- The abstraction is supposed to hide the database. It does not.
- The caller must know: the row type (`UserRow`), the soft-delete column (`deleted_at`), the password column (`password_hash`), the SQL operation (`UPDATE`).
- The abstraction is a thin wrapper. It composes nothing; it leaks everything.
- **Fix:** Return a domain `User` (no `password_hash`, no `deleted_at`). Hide soft delete (the repo filters it). Hide persistence (the caller calls `save`, not `UPDATE`).

### C2 Clarity (Core)
- The caller's code is unclear: `if (user && !user.deleted_at)` — what is `deleted_at`? Why does the caller check it?
- The abstraction was supposed to clarify. It muddied.
- **Fix:** `repo.findByEmail()` returns `User | null` (already filtered). The caller does not know soft delete exists.

### API P2 Clarity (API, by analogy)
- The repo's API exposes the DB schema in its return types. `UserRow` is a DB concept, not a domain concept.
- The public contract (return type) leaks the private implementation (the table).
- **Fix:** The return type is `User`, a domain type. `UserRow` is internal.

### Data P8 Lifecycle Awareness (Data)
- The soft-delete lifecycle (`deleted_at`) is the repo's concern. The caller should not manage it.
- By exposing `deleted_at`, the repo forces every caller to remember the filter. A forgotten filter is a soft-delete leak.
- **Fix:** The repo filters `deleted_at IS NULL` in every query. The caller never sees `deleted_at`.

### Security P9 Secret Hygiene (Security)
- `password_hash` is in the returned `UserRow`. The caller now has access to the password hash.
- A caller that logs `user` logs the hash. A caller that serializes `user` serializes the hash.
- **Fix:** `User` does not include `password_hash`. Only `UserRepository` and `AuthService` (internal) see it.

### C4 Locality (Core)
- The SQL is in the repo, but the column knowledge (`password_hash`, `deleted_at`) is in the caller.
- A column rename touches the repo AND every caller. Locality is violated.
- **Fix:** Column names are local to the repo. The caller knows only the domain `User`.

### C5 Reversibility (Core)
- Changing the database (e.g., from SQL to NoSQL, or renaming a column) requires touching every caller.
- The abstraction was supposed to make the change local. It does not.
- **Fix:** The repo's interface (`findByEmail`, `save`) is stable. The implementation changes; the callers do not.

## What This Example Reveals

The leaky abstraction is the false promise of encapsulation. The class is named `UserRepository` (suggesting it abstracts persistence), but it returns raw DB rows, exposes lifecycle columns, and leaks secret fields. The abstraction exists in name only.

The cost:
- Every caller must know the DB schema (C6 violated).
- A schema change touches every caller (C5 violated, C4 violated).
- Secret fields leak to callers (Security P9 violated).
- The lifecycle is the caller's burden (Data P8 violated).

The fix is always the same: **the abstraction's public type is the domain type, not the implementation type**. `UserRepository.findByEmail()` returns `User | null`, where `User` has `id`, `email`, `name` — and nothing else. `password_hash`, `deleted_at`, `UserRow` are internal. The caller knows nothing about the database.