deep-modules

name	deep-modules
description	Apply Ousterhout's "deep modules" principle (narrow interface, deep implementation) when designing or refactoring classes and modules. Use when adding new methods to a class, extracting shared logic, or reviewing repository / service code.

Deep Modules — Narrow Interface, Deep Implementation

A deep module hides a lot of complexity behind a small public surface. Cost of a module ≈ interface_complexity / functionality. Optimize for fewer public methods, stable signatures, and policy concentrated in one place — not for fewer lines per file.

This skill is language- and project-agnostic design guidance. Moca-specific conventions live in coding-style (e.g. nanoid vs uuid, ESM .js extensions). Use both together.

When to Apply

• DO: repositories, services, data-access layers, reusable utilities, tool definitions.
• DO NOT (blindly):
  • Express route handlers — declarative, thin handlers are easier to read than "deep" ones.
  • React components — prop count is a separate concern (split with hooks, not by hiding state).
  • Test files — explicitness usually beats deduplication.

Decision Heuristics

Use this table during design and code review. If two or more rows match, the module is probably too shallow.

Smell	Diagnostic Question	Likely Fix
Method names enumerate fields (updateXxxAndYyy, setStatus, setTitle)	Does the caller need to know the storage schema to pick a method?	Collapse to update(id, patch) with an optional-fields object
Same try / catch + error-name branch repeated 3+ times	Is this a policy (e.g. "tolerate missing") or a per-call decision?	Extract a private wrapper; each public method becomes one line
Public method takes 4+ args, several optional	Do callers pass undefined to skip args?	Take an options object; drop unused fields entirely
Return value exposes internal identifiers (partition key, sequence number, marshalled item)	Does any caller actually use them?	Return a DTO; do not leak storage shape
Each method calls marshall / unmarshall (or equivalent serialization) directly	Is the conversion the same in every method?	Extract toItem / fromItem private mappers
fromItem deletes a denylist of storage keys (PK / SK / GSI*) before returning	Is the strip-list maintained separately from the list of keys toItem adds?	Project onto a domain-field allowlist instead — anything not named is dropped by construction, so a new index key can never leak
Module has 6+ public methods that share one noun	Can you describe what the module does in one sentence?	Merge methods, or split into two modules with different nouns

The 4 Pillars

A deep module has all four:

1. Small surface area. Field-level partial updates collapse into one update(id, patch).
2. Stable signature under change. Adding a new updatable field or option must not break existing callers — favor patch / options objects over positional args.
3. No leaking internals. Storage keys, SDK types, SQL columns, and partition keys stay private. Public types describe the domain, not the table. The storage→domain mapper should select the domain fields (allowlist), not strip known storage keys (denylist): a denylist must be kept in sync with whatever the write path adds, and the day they drift an internal key leaks silently.
4. Single locus for cross-cutting policy. Logging, retry, idempotency, "tolerate missing", and error-mapping live in one private helper, not duplicated per method.

Anti-Patterns

• Pass-through method — service.updateTitle() only delegates to repo.updateTitle(). If the wrapper adds nothing, lift the call to the next layer up.
• Method-per-field — setName / setStatus / setDescription siblings. Use one update(id, patch).
• Over-decomposed helpers — splitting a 30-line module across 5 files. Depth is measured by narrowness of public API, not by file count. (Distinct from splitting to narrow the public surface — separating contract from implementation behind one entry point is fine; what's discouraged is fragmenting the logic.)
• Premature interface extraction — declaring a TypeScript interface for a class with one implementation and one caller. Wait for the second caller.
• Leaky DTOs — returning the storage row (with PK / SK / GSI columns) from a public method "for convenience". Once exposed, removal becomes a breaking change.

If You Do Extract an Interface

The default is still "don't" — wait for the second implementation or a mocking seam (see the anti-pattern above). But when you extract one deliberately (e.g. to publish a reference contract ahead of need), keep the interface narrow by separating contract from implementation:

• The contract — the interface plus the types its methods take and return — is the only thing a caller reads. Place the method input/output types with the interface, not in the shared model file: they only mean something next to the method they feed.
• The data model (what the entity is) stays separate from the operation types (how you act on it). Dependencies point one way: implementation → contract → model.
• Expose one entry point (a barrel) and let only the composition root construct the concrete implementation. Callers depend on the interface; nobody else names the class.
• This is the one case where adding files reduces interface complexity — it is not the over-decomposition the anti-pattern warns about, because it narrows the public surface rather than fragmenting logic.

Self-Check Before Adding a Public Method

Ask, in order:

1. Can an existing method absorb this with one extra option / patch field?
2. Does the proposed method name encode internal schema (field names, table columns, SDK verbs)?
3. If the next similar requirement arrives, will it add a 7th, 8th, 9th method?
4. What can be made private to keep the public surface stable across the next change?

If any answer is "yes" to (1)–(3), redesign before adding the method.

Example (Moca)

packages/agent/src/repositories/sessions-repository.ts originally exposed 6 public methods, three of which are partial-update variants:

exists / get / create
updateSessionTimestamp / updateSessionAgentAndStorage / updateSessionTitle

Caller has to pick the right method based on which DynamoDB attributes are being touched — i.e. the public API encodes the storage schema.

A deep version:

exists / get / create / update(sessionId, patch)

with private helpers concentrating cross-cutting concerns:

• key(sessionId) — single source of { userId: pk, sessionId } marshalling.
• tolerateMissing(label, fn) — one place that maps ConditionalCheckFailedException to a warn-and-skip.
• buildUpdate(patch) — pure function turning a SessionPatch into UpdateExpression + ExpressionAttributeValues, always stamping updatedAt.
• toItem / fromItem — the only places that touch marshall / unmarshall.

The composition layer (sessions-service.ts) keeps its userId-first public contract; only its internal calls switch from repo.updateSessionTitle(...) to repo.update(id, { title }). Surface for downstream callers is unchanged.