docs: document mock API module boundaries and consumer contract (Clos…

[soma-enyi]

Document mock API module boundaries and consumer contract

Summary

Add comprehensive documentation (docs/mock-api-boundaries.md) for the in-memory mock API module architecture, explicitly defining module responsibilities, public boundaries, and consumer contracts.

Changes

• Created docs/mock-api-boundaries.md with:
  • Module structure and responsibilities (lib/api/index.ts, mock-boundary.ts, mock.ts, mock-storage.ts, types.ts, live.ts)
  • Clear distinction between fixtures (static data) and behavior (simulation logic)
  • Public application entry point contract: all consumers import from @/lib/api only
  • Stable boundary definition: developer controls exposed via mock-boundary.ts and re-exported from index.ts
  • Complete developer control reference (resetMockData, applyMockScenario, replayMockEvent, setMockRoleMutationFailure, setMockMetaVersion)
  • Fixture maintenance rules and behavior implementation guidelines
  • Safe vs. risky changes guidance for refactoring
  • Example data flow tracing and migration guidance

Acceptance Criteria ✅

• Public mock API boundary identification
• Clear distinction between fixture and behavior responsibilities
• Documentation of relationship between lib/api/index.ts and internal mock modules
• Documentation reflecting actual implementation (grounded, not speculative)

Testing

No code changes; documentation-only PR. Verify that docs/mock-api-boundaries.md:

• Correctly describes module layout
• Accurately reflects current exports from lib/api/index.ts and mock-boundary.ts
• Matches implementation in lib/api/mock.ts

Closes #390