Interface Specification

Phase 1 — Setup

**Interface**: [name]
**Owning component**: [...]
**Language**: [TypeScript / Go / Python / ...]
**Stability target**: [stable / experimental / deprecated]
**Consumers**: [internal team / library users / plugin authors]
**Concurrency model**: [single-threaded / thread-safe / fiber]
**Async model**: [sync / Promise / async iterator / ...]

Ask render mode per diagram-rendering mixin and output path (default: /documentation/[case]/interface-specification/[name]/).

Phase 2 — Interface surface

For each operation:

Signature

interface OrderRepository {
  /**
   * Persist or update an order aggregate.
   *
   * Preconditions:
   *   - `order.id` is non-empty
   *   - `order.version` equals the version this caller last loaded
   *
   * Postconditions:
   *   - On success, a subsequent `findById(order.id)` returns the saved order
   *     with `version + 1`
   *   - On conflict, throws `OptimisticLockError`; no state change
   *
   * Errors:
   *   - `OptimisticLockError` — version mismatch
   *   - `PersistenceError` — transient; retry may succeed
   *
   * Complexity: O(1) calls to the store; uses a single transaction.
   * Concurrency: safe across goroutines / threads.
   * Idempotent: yes, by (id, version).
   */
  save(order: Order): Promise<Order>;

  /**
   * Load an order by id.
   *
   * Preconditions: `id` non-empty.
   * Postconditions: returns the aggregate or null if not found.
   * Errors: `PersistenceError` on transient store issues.
   * Complexity: O(1) amortized.
   */
  findById(id: OrderId): Promise<Order | null>;
}

Parameter + return semantics

• Parameter ownership: passed by reference vs ownership transferred
• Return ownership: caller owns / may not mutate / must dispose
• Nullability + absence: null vs not-found vs error

Invariants

Invariants that hold across operations:

• save never returns an Order with a smaller version than the input
• findById(x) is a pure read — no state mutation anywhere

Phase 3 — Error taxonomy

Errors are part of the contract, not implementation detail.

Hand off broader strategy to system-error-handling-strategy.

Phase 4 — Concurrency + threading

• Thread safety per operation (safe / unsafe / serialize externally)
• Re-entrancy (can it call itself?)
• Cancellation model (context / signal / Promise cancel)
• Blocking vs non-blocking

Phase 5 — Performance + complexity

• Time complexity per operation
• Space complexity
• Bounded vs unbounded memory
• I/O amplification
• Latency class (CPU-bound / I/O-bound / network)

Phase 6 — Lifetime + ownership

• Instance lifetime (per-request / per-connection / singleton)
• Who creates, who disposes
• Resource cleanup — explicit close() or RAII / using
• Cancellation + partial-failure cleanup

Phase 7 — Stability guarantees

Version bump rules tied to the interface's owning component. Hand off to api-versioning-strategy (for external network counterparts) or internal versioning policy.

Phase 8 — Examples

Happy path

const order = await repo.findById(id);
if (!order) throw new NotFoundError(id);
order.markPaid();
const saved = await repo.save(order);
assert(saved.version === order.version + 1);

Concurrent modify (conflict)

try {
  await repo.save(staleOrder);
} catch (e) {
  if (e instanceof OptimisticLockError) {
    const fresh = await repo.findById(staleOrder.id);
    // merge, retry
  } else throw e;
}

Not found

const order = await repo.findById('unknown');
assert(order === null); // not an error

At least one happy path + one edge + one failure example per non-trivial operation.

Phase 9 — Testability

• Can this interface be mocked / stubbed? What's the test double shape?
• Behavior tests vs. state tests preferred?
• Fixtures needed
• Any nondeterminism requiring clocks / randomness ports?

Phase 10 — Alternative designs considered

Short list, with one-line reject rationale:

• Returning Result<T, E> union instead of throwing — rejected: language idiom is exceptions; throwing keeps callers cleaner
• Passing tx handle explicitly — rejected: infra concern, hidden behind repo

Phase 11 — Diagrams

Collaboration

sequenceDiagram
    Handler->>Repo: findById(id)
    Repo-->>Handler: Order
    Handler->>Handler: mutate aggregate
    Handler->>Repo: save(order)
    Repo-->>Handler: savedOrder (version+1)

State / lifetime

stateDiagram-v2
    [*] --> Instantiated
    Instantiated --> Active : ready
    Active --> Closed : close()
    Closed --> [*]

Phase 12 — Diagram rendering

Per diagram-rendering mixin.

Phase 13 — Report assembly and approval

# Interface Specification: [Name]

**Date**: [date]
**Owning component**: [...]
**Language**: [...]
**Stability**: [stable / experimental / deprecated]

## Scope
## Interface Surface
[Per operation: signature, pre/post, errors, complexity, concurrency]

## Invariants
## Error Taxonomy
## Concurrency + Threading
## Performance + Complexity
## Lifetime + Ownership
## Stability Guarantees
## Examples
## Testability
## Alternative Designs
## Diagrams
## Hand-offs
## Assumptions & Limitations

Present for user approval. Save only after confirmation.

Assessment + planning rules

• Signatures + semantics, not types alone
• Errors documented as contract
• Stability label stated
• Examples: happy + edge + failure
• Concurrency + lifetime explicit
• No fabricated semantics

Failure behavior

Self-check

[] Signatures + pre/post per operation
[] Invariants
[] Error taxonomy in contract
[] Concurrency + lifetime
[] Complexity bounds
[] Stability guarantee
[] Examples for happy / edge / failure
[] Testability notes
[] Alternatives considered
[] Diagrams valid
[] No fabricated semantics
[] Report follows output contract