# 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

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

## Milestone 2 - exact DB reconciliation

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

## Milestone 3 - revisioned Redis and workers

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

## Milestone 4 - command and lifecycle workflows

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

## Milestone 5 - test-branch release gate

- [x] Full typecheck, architecture, lint, unit, build, and non-conditional
      integration suites.
- [x] Dedicated PostgreSQL/Redis conditional integration suite with skip count
      recorded.
- [x] Recovery runbook exercised from each incomplete status.
- [x] Admin status/readiness exposes revision, phase, participant checksums, and
      incomplete outbox state.
- [ ] User-test deployment evidence is recorded separately from Git push.
- [x] 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.
