Plan: Implement repository contracts and Alembic migrations (2.6.2)

[leynos]

Summary

This is a planning PR. It carries the execution plan for roadmap item
2.6.2 — Implement repository contracts and Alembic migrations and is
intended for review of the plan before any implementation begins. The plan is
in DRAFT status and must be approved before code is written.

The execplan lives at
docs/execplans/2-6-2-repository-contracts-and-alembic-migrations.md.

It supersedes the initial draft on this branch, which was written without
inspecting the codebase (it invented port signatures and a module path that do
not exist, and cited a stale base migration revision). The replacement is
grounded in the real 2.6.1 contracts, prior art, and a community-of-experts
design review.

What the slice will deliver

2.6.1 already defined the generation-run domain model and the composite
GenerationRunPort (in episodic/canonical/generation_run_ports.py) with an
in-memory reference adapter. This slice adds the durable layer behind that port:

• A PostgreSQL-backed SqlAlchemyGenerationRunStore implementing the existing
  composite port, wired into SqlAlchemyUnitOfWork as uow.generation_runs.
• An Alembic migration creating generation_runs, generation_events, and
  generation_checkpoints, chained off the current head 20260601_000009.
• Integration tests validating event ordering, plus parametrised port-contract
  tests run against both the in-memory and PostgreSQL adapters.

Key design decisions (see the execplan Decision Log)

• Per-run event seq allocated as MAX(seq)+1 under
  UNIQUE(generation_run_id, seq) with a bounded retry inside a savepoint and a
  conflict metric — mirroring the established history-table revision pattern;
  a global Postgres sequence is rejected (gap/visibility problems).
• seq stored as BIGINT; composite indexes for list_runs; explicit FK
  ON DELETE semantics (events/checkpoints CASCADE, episode RESTRICT); an
  updated_at trigger matching the workflow_checkpoints precedent.
• create_run idempotency via a unique idempotency_key column (first-write-wins).
• Behavioural equivalence with the in-memory adapter is claimed only under the
  single-writer-per-run assumption; the py-pglite single-connection limitation
  and a follow-up real-PostgreSQL concurrency test are documented.

Testing approach

Red-Green-Refactor with pytest unit tests, py-pglite integration tests for event
ordering, and bounded Hypothesis property coverage for the sequence invariant.
vidai-mock is out of scope: this slice performs no inference. All gates
(make check-fmt, make typecheck, make lint, make test,
make check-migrations, make markdownlint) must pass, followed by a
coderabbit review --agent pass, at each milestone.

References

• Roadmap item: 2.6.2 (Generation runs and checkpoints), docs/roadmap.md.
• Execplan: docs/execplans/2-6-2-repository-contracts-and-alembic-migrations.md.
• Lody session: https://lody.ai/leynos/sessions/dddb44f8-8c58-4e00-bc69-ac97035df7d1

[sourcery-ai]

Sorry @leynos, 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: 80121c31-a4ac-4010-bf03-2fb834208295

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 2-6-2-repository-contracts-and-alembic-migrations

---

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