Game clock reconciliation implementation plan

Baseline: main@b91dcbcaaac5acd4c7349cd3ed0996c547f58756

Branch: test/game-clock-reconciliation-20260903

This plan is the status source for the long-running user test branch. A checked item means code and focused automated evidence exist on this branch; it does not mean deployment or production validation.

Milestone 1 - authority and inventory

Branded GameTick, ObservedGameInstant, ScheduleInstant, WallInstant, and ClockRevision boundaries.
Explicit clock phase and monotonic RUNNING projection.
Exact alignment arithmetic preserving millisecond/sub-turn remainder.
Opening tick zero and PREOPEN executable floor in the shared seeder.
Schema columns for phase, revision, and deadline generation.
Suspension, participant-checksum, and Redis projection outbox tables.
Machine-readable DB/Redis/JSON participant inventory and architecture gate.
Turn flush lock prefix and phase/revision/generation fence.
Empty and upgraded database migration execution evidence.

Milestone 2 - exact DB reconciliation

Suspension start command with DB wall time and idempotent source revision.
Exact resume plan transaction with deterministic participant lock order.
SHIFT adapters for cursor, generals, active auctions, message expiry, vote end, select pool, and NPC selection windows.
KEEP checksum adapters for occurrences and accepted command coordinates.
Explicit LEGACY_COMPLETE_TURNS and bounded CATCH_UP policies.
Property tests for remaining distance, ordering, and history invariants.
24-hour and 65m17.250s PostgreSQL integration evidence.

Milestone 3 - revisioned Redis and workers

Projection outbox claimer/retry/recovery state machine.
Redis active revision and atomic due-pop script.
Auction OPEN/FINALIZING revision and generation fence.
Tournament durable tick dual-write and projection rebuild.
DB-commit/Redis-failure crash-restart test.
Readiness integration in Gateway/API process health.

Milestone 4 - command and lifecycle workflows

All durable input events record accepted tick and accepted revision.
Processing converts accepted coordinates across revisions or fails closed.
Gateway pause/resume/open orchestration writes the DB clock phase.
Unification wait becomes a durable UNIFICATION_WAIT suspension.
Alignment, optional rate change, invader IDs/RNG, creation, first schedule, outbox, verification, and RUNNING transition form one retry-safe workflow.
Multi-host drift and general-access/clock-operation deadlock tests.

Milestone 5 - test-branch release gate

Full typecheck, architecture, lint, unit, build, and non-conditional integration suites.
Dedicated PostgreSQL/Redis conditional integration suite with skip count recorded.
Recovery runbook exercised from each incomplete status.
Admin status/readiness exposes revision, phase, participant checksums, and incomplete outbox state.
User-test deployment evidence is recorded separately from Git push.
All FORBID inventory entries are removed by typed migrations or proven inactive preconditions.

Evidence log

2026-09-03 - authority foundation

pnpm test:bootstrap: dependency installation, Prisma generation, and package preparation passed in the dedicated worktree.
CI=1 TURBO_CONCURRENCY=1 pnpm typecheck: 21/21 tasks passed.
CI=1 TURBO_CONCURRENCY=1 pnpm test: 12/12 package tasks passed. Conditional suites remain classified separately and are not integration evidence.
CI=1 TURBO_CONCURRENCY=1 pnpm build: 26/26 tasks passed.
TURBO_CONCURRENCY=1 pnpm lint: passed with 36 pre-existing frontend warnings and no errors.
pnpm check:architecture: package boundaries passed; 21 authoritative clock fields and 18 participants were registered.
Migration SQL was generated, formatted, validated, and registered as the release manifest head. All 43 migrations applied to the empty dedicated PostgreSQL instance. A second schema upgraded from the previous head with an existing manual world_state row and verified MANUAL:1:1 plus all three reconciliation tables.
Dedicated PostgreSQL/Redis fixtures proved exact 24-hour and 65m17.250s gaps, schedule distance/order preservation, occurrence checksums, live-lease fencing, a single durable outbox, Redis target revision, and recovery after a crash between Redis commit and DB finalization.

2026-09-03 - revisioned workers and input coordinates

CI=1 TURBO_CONCURRENCY=1 pnpm typecheck: 21/21 tasks passed after the worker/input contract changes.
CI=1 TURBO_CONCURRENCY=1 pnpm test: 12/12 package tasks passed.
Dedicated PostgreSQL runs passed databaseCommandQueue.integration.test.ts 6/6 and runtimeClockShiftPersistence.integration.test.ts 3/3 when executed sequentially; the latter now clears each single-world fixture before the next case. Dedicated Redis passed tournament source revision 4/4, including an atomic stale-clock rejection. API input-event integration passed 13/13.
The 24-hour/65m17.250s reconciliation suite passed 2/2 after the other DB suites. Conditional files share a deliberately dedicated schema and are run sequentially to prevent their fixture cleanup from racing another file.

2026-09-03 - Gateway lifecycle authority

Runtime PAUSE/STOP starts a durable maintenance suspension before the Gateway status and process reconciliation change. RESUME completes the DB reconciliation and Redis outbox before the profile becomes RUNNING.
Both an already-built overdue RESERVED profile and an overdue PREOPEN profile promote the game DB from PREOPEN@0 before the Gateway status changes to RUNNING; the Redis clock phase is revision/generation fenced.
pnpm --filter @sammo-ts/gateway-api test passed 313 tests with 35 environment-conditional skips. Gateway typecheck and target lint passed.

2026-09-03 - atomic unification wait

A unification flush now commits the finalization, actionable prompts, and one deterministic UNIFICATION_WAIT suspension together. A late archive failure rolls the whole boundary back; retry creates one ledger.
The suspended command queue admits only an invader decision tied to the active ledger. The daemon-authorized command transaction applies a 36-hour exact gap, preserves participant positions, changes the fixture rate from 10 to 20 minutes, creates one invader nation and ten deterministic generals with future first turns, and writes one final-rate projection outbox.
The dedicated PostgreSQL/Redis fixture reached RUNNING@2/2 only after the Redis projection. DB-wall versus a mocked 12-hour host drift and concurrent general-access lock acquisition completed without drift or deadlock.
CI=1 TURBO_CONCURRENCY=1 pnpm typecheck passed 21/21 tasks, CI=1 TURBO_CONCURRENCY=1 pnpm test passed 12/12 package tasks, CI=1 TURBO_CONCURRENCY=1 pnpm build passed 26/26 tasks, and workspace lint passed. pnpm check:architecture registered 22 authoritative clock fields and 18 participants.
Dedicated sequential PostgreSQL/Redis runs passed clock reconciliation 3/3, atomic unification 1/1, command queue 7/7, runtime clock persistence 3/3, API input-event boundary 13/13, and tournament revision 4/4: 31/31 enabled tests with zero skips. The queue and API suites now create and remove their own clock fixtures so a completed file cannot leak phase or initialization state into the next file.
User-test deployment and public runtime evidence remain deliberately open: Git push is not deployment, and no deployment was authorized in this work.

2026-09-03 - completion audit

The invader response now reads the exact post-alignment world snapshot even when the turn rate is unchanged. The HWE-shaped regression asserts all ten first turns are in the aligned next-month window rather than already due.
The ordinary flush fence now uses the same incomplete-row dual-read rule as worldLoader: a legacy row is MANUAL until all four clock snapshot fields exist. Input-event acceptance remains fail-closed until initialization.
Auction OPEN/FINALIZING recovery fixtures and direct PROCESSING input-event fixtures now carry explicit phase/revision/generation coordinates. The optional Ref-only troop parity suite is registered only in Ref mode, so the Core conditional gate reports only tests it actually ran.
pnpm check:architecture passed with 22 authoritative fields and all 18 required DB/JSON participants. The gate now rejects duplicate or FORBID participants, missing required participants, and unimplemented/duplicate Redis participants.
CI=1 TURBO_CONCURRENCY=1 pnpm test:integration:conditional passed 79 files and 234 tests against isolated PostgreSQL/Redis schemas with zero skipped and zero failed files.
On the audited diff, pnpm check:architecture passed, full typecheck passed 21/21 tasks, workspace test passed 12/12 tasks, build passed 26/26 tasks, and workspace lint completed without errors.

The required acceptance cases map to automated evidence as follows:

Contract	Automated evidence
PREOPEN signed tick, tick-zero opening, executable floor; RUNNING rewind monotonicity	`packages/common/test/gameClock.test.ts`, `app/game-engine/test/scenarioSeeder.test.ts`, `app/gateway-api/test/orchestratorOperations.test.ts`
Exact 24-hour and 65m17.250s gaps; ordering, remaining distance, occurrence history	`app/game-engine/test/clockReconciliation.integration.test.ts`, `packages/common/test/gameClock.test.ts`
DB commit/Redis failure and incomplete-status recovery	`app/game-engine/test/clockReconciliation.integration.test.ts`, `app/game-engine/test/unificationFinalization.integration.test.ts`
Auction OPEN/FINALIZING and tournament revision races	`app/game-api/test/auctionWorker.integration.test.ts`, `app/game-api/test/tournamentStoreRevision.integration.test.ts`
Pending commands crossing a clock revision	`app/game-engine/test/databaseCommandQueue.integration.test.ts`, `app/game-api/test/inputEventBoundary.integration.test.ts`
Delayed opening	`app/gateway-api/test/orchestratorOperations.test.ts`, `app/game-engine/test/scenarioSeeder.test.ts`
36-hour unification wait, rate change, deterministic retry, future invader turns	`app/game-engine/test/unificationFinalization.integration.test.ts`, `app/game-engine/test/unificationInvaderResume.test.ts`
DB wall despite host drift; general-access lock ordering	`app/game-engine/test/clockReconciliation.integration.test.ts`, `app/game-engine/test/profileSchemaAdvisoryLock.integration.test.ts`
Generated exact-gap ordering/remaining/history invariants	`packages/common/test/gameClock.test.ts`

Deployment and public-runtime evidence remain outside this audit and are still open pending explicit user-test deployment authorization.

12 KiB Raw Blame History