State Update Guard: main release preparation

Release: 0.0.38.0. Prepared 2026-09-19. Implementation, review fixes, and local verification are complete. Remote CI, final merge approval, and production deployment remain release gates.

Scope and compatibility

• Main baseline: c7c8f4659e6c2f46d851f730e26c52c6078e1f21.
• Integrated subsequent main billing-ledger change: f52b5c76c5779a4281b360c006f22fabf8917b40.
• Final integrated main baseline: 92225de3a (Studio recovery and image-generation controls retained).
• Preparation branch: codex/state-update-guard-main-prep.
• Only State Update Guard is promoted, not the testing branch's unrelated work.
• The extension is optional. It validates existing gameplay update formats and makes at most one correction request when needed. It does not replace the engine, rewrite lore, or introduce mandatory post-narrative state resolution.
• Main's asynchronous history construction, provider fallback, stopped-generation billing, speaker tags, JSON-write protection, and regeneration behavior are retained.

Installation and per-chat enablement gate validation before receipt enforcement, correction provider resolution, or correction billing. Missing installation, uninstall with saved settings, and Off all retain normal gameplay. Cards without active AI-writable variables need no receipt even when On.

Compatibility tests cover send/regenerate/continue labels through validation and commit helpers, trap unexpected provider/database work, and check unchanged balances. These are not full HTTP or browser end-to-end tests.

Production schema preparation

Production preparation completed and was verified on 2026-09-19:

• messages.state_validation: nullable jsonb.
• play_sessions.state_guard_enabled: non-null boolean, default true.
• play_sessions.state_guard_model: nullable text.

The default does not install the extension. No saved story values, balances, or installation records were changed. No Railway CLI was used. Both hosted startup and existing embedded databases also prepare the columns. Predeploy preserves main's existing preparations and runs both additive Guard migrations before new code selects the fields.

Billing and editions

Hosted default: official::google/gemini-2.5-flash-lite, matching Memory. The free-model action selects official::openrouter/free. Official/BYOK correction routing is independent of the story provider.

A successful committed paid official correction debits mushies, including explicit no-update corrections and BYOK stories. Audit, state, correction debit, and eligible story debit commit atomically. Insufficient funds, cancellation, stale attempts, and duplicate commits must not create correction debits. Checks without model calls, BYOK corrections, and explicitly free models are intentionally exempt.

The local/open-source edition hides official controls and forces private routing, including imported hosted settings. No hosted credential/billing fallback is allowed.

Evidence

• Engine: 47 files, 1,174 tests passed.
• Shared on final baseline: 55 passed, 1 expected skip.
• Focused server after review fixes: 139/139 passed, including 39 compatibility checks, migrations, routing, billing, validation, and failure classification.
• Latest-main ledger compatibility: 70/70 passed, including paid correction/story debits, rollbacks, and a negative test proving the real deferred constraint rejects unrecorded debits.
• Focused Guard UI: 34 tests passed; fullscreen menu: 2 passed.
• Real testing PostgreSQL: 11/11 passed with rolled-back fixtures; no fixture users remained.
• Workspace typecheck: all 8 tasks passed.
• Final production build passed: 5/5 tasks after latest-main integration.
• App edition-boundary check passed.
• Full app on final baseline: 1,181/1,181 passed after fixing integration assertions and the eight stale navigation/layout/theme tests also reproduced on clean main. Product UI was not changed to satisfy stale tests. Final run used concurrency two after an over-parallel run exhausted local memory; no assertions were disabled.
• Full server: 2,302 passed, 9 skipped, zero failures/cancellations across all 311 test files. Final verification used four disjoint, exhaustive sorted-file partitions through the same isolated test launcher (78/78/78/77 files). The earlier failed usage audit incorrectly scanned test fixture inserts; it now verifies production writers and has explicit file-classification regressions. No production durability check was removed.
• Open-source export verification passed on the ledger-integrated baseline: install, typecheck, build, and all test tasks. Server: 1,420 passed, 4 skipped, no failures; app: 752 passed; engine: 1,174 passed; shared: 49 passed. The export includes main's ledger SQL constraint and tests it. Remote CI must verify the final combined tree before merge.

No live paid model call or browser verification was performed. Automated billing tests establish transaction behavior, not a production charge or model accuracy guarantee.

Remaining gates

1. Push a main-targeted PR and pass CI.
2. Present readiness evidence and obtain final merge confirmation.
3. Merge and verify the deployed revision and non-browser health checks.

No remote main merge or production code deployment has been performed by this preparation.

Rollout and rollback checks

After merge, require a successful deployment for the exact merged SHA and green /health and /health/live responses. Check for new Guard schema/validation errors before calling the deployment verified. Non-browser health checks do not replace authenticated gameplay acceptance.

If rollback is required, restore the previous application revision using the normal release process. Leave the additive columns and existing audit/ledger rows intact; dropping them is unnecessary and would lose history. Turning Guard Off or uninstalling restores ordinary future turns. The emergency environment switch intentionally fails protected turns closed rather than silently accepting invalid updates.