Plan: Driven port interfaces (1.2.2)

[lodyai]

Summary

Adds the execution plan docs/execplans/1-2-2-define-driven-port-interfaces.md for roadmap item 1.2.2 — defining the six driven-port interfaces (GameStateRepository, Clock, RandomSource, AudioEventSink, AssetCatalogue, TelemetrySink) in src/domain/ports/.

This PR contains the plan only. No interfaces are implemented yet — the execplans approval gate requires sign-off before implementation begins. Please review the plan and approve (or request revisions).

How the plan was produced

• Grounded in docs/roadmap.md (1.2.2), the HLD §"Module layout"/§"Domain model", and ADR-002/004/005/006/007/008/009/010, plus the existing 1.2.1 boundary tooling (scripts/import-boundaries.ts, tools/path-aliases.ts, strict tsconfig).
• Open gaps on prior art resolved via Firecrawl: pure-rand's immutable generator shape (inspiration only — not a dependency) and the Result-vs-Promise convention for ports.
• Stress-tested by a Logisphere community-of-experts design review (contracts, structural boundaries, alternatives, failure-mode pre-mortem). Verdict: proceed with conditions; every condition is folded into the plan's Decision Log and Interfaces sections.

Key design decisions captured

• Opaque branded placeholders for the not-yet-built 1.3.1 aggregates (not permissive unknown/Record), so premature coupling is a compile error.
• GameStateRepository segregated into RunIndex / SnapshotStore / EventLog, composed via an intersection alias (ADR-004 access patterns/evolution rates).
• RandomSource as a pure, immutable, snapshot-serialisable port (sfc32 per ADR-005); the snapshot value the pure tick consumes lives in domain/model.
• A new placeholder-honesty CI guard (lint:domain-placeholders) plus an import-hygiene rule closing the boundary guard's npm allow-list gap.
• Dropped sync AssetCatalogue.has; documented the "a sink never throws" invariant with an optional Flushable; property-style members throughout; the no-Result divergence from the ADR-002 sketch and the deferred seventh (self-play report) seam are recorded.

Scope note for the approver

This is a types-only slice — it renders no DOM and carries no user-visible strings — so localisation, card-model data, WCAG 2.2 markup, and Playwright/css-view visual validation are recorded as not applicable. bun ff (including the a11y and e2e suites) must still pass green during implementation to prove no regression. Please confirm you agree with this scoping.

References

• Execplan: docs/execplans/1-2-2-define-driven-port-interfaces.md
• Roadmap item: 1.2.2 (Foundational contracts and build spine → hexagonal source-tree skeleton)
• Lody session: https://lody.ai/leynos/sessions/33c9d4a7-4db5-44ae-b100-b77e6e17c23c

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d31d548f-98ec-4d02-80d0-6933bb5f7422

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 1-2-2-define-driven-port-interfaces

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}