Offline Snapshot Initialization — Step 4 Implementation Summary

Feature plan: Step 1 · Step 2 · Step 3 · Step 4

Stage 1 - Bootstrap missing snapshots

• Changes:

  • Added OfflineSnapshotBootstrap, which publishes only when no valid served snapshot exists and reports published, already-available, or unavailable.

  • Added focused coverage for first publication, preservation of an existing snapshot, and intentional non-publication.

• Verification:

  • Ran the three OfflineSnapshotBootstrapTest cases through the local test harness; all passed.

  • Ran PHP syntax checks for the new class and test, plus git diff --check.

• Notes:

  • The bootstrap uses the existing locator and atomic publisher; public-mode eligibility is supplied by the caller in Stage 2.

Stage 2 - Integrate bootstrap into rebuild

• Changes:

  • Extended the canonical read-model rebuild to ensure a first snapshot after promotion, reporting published, existing, or intentionally unavailable.

  • Made an eligible bootstrap failure exit clearly after promotion and direct recovery to ./v3 offline publish.

  • Added rebuild-command coverage for public publication, approved-members-only skip behavior, and post-promotion failure reporting.

• Verification:

  • Ran all three OfflineSnapshotBootstrapCommandTest cases through the local test harness; all passed.

  • Ran PHP syntax checks for the rebuild script and command test, plus git diff --check.

• Notes:

  • The normal update-driven task queue is unchanged; an existing served snapshot is detected before any bootstrap publication is attempted.

Stage 3 - Document and validate the first-time flow

• Changes:

  • Registered the bootstrap unit and rebuild-command tests in the standard test runner.

  • Updated first-time setup, pre-launch, launch-sequence, and offline-reading guidance to make automatic rebuild bootstrap canonical and manual publish recovery-only.

• Verification:

  • Ran php tests/run.php OfflineSnapshotBootstrapTest OfflineSnapshotBootstrapCommandTest TaskQueueWorkerTest TaskQueueCommandTest: 26 passed, 0 failed.

  • Ran git diff --check and reviewed the plan-navigation links and changed runbook commands.

  • Live public-endpoint verification is not applicable in this local checkout; the runbook now requires it before a public launch.

• Notes:

  • Approved-members-only mode remains explicitly exempt from public snapshot readiness and endpoint expectations.

Final Verification

• ./v3 test completed with 823 passing tests, including the new bootstrap service and rebuild-command coverage.

• git diff --check passes; only the pre-existing qdb_todo.txt and todo.txt working-tree edits remain outside these commits.

• A live public endpoint was not available in this checkout; operators must run the documented ./v3 offline diagnose --url=https://your-public-domain check before launch.

Stage 4 - Repair a missing snapshot on request

• Changes:

  • The public snapshot route now uses the existing bootstrap service under a short exclusive lock when no valid snapshot is served.

  • Both eligible anonymous GET and HEAD requests can create the first snapshot; approved-members-only handling and all other route eligibility rules are unchanged.

• Verification:

  • Ran php tests/run.php LocalAppSmokeTest::testFrontControllerBootstrapsMissingPublicOfflineSnapshotForHeadAndGet OfflineSnapshotBootstrapTest OfflineSnapshotBootstrapCommandTest: 7 passed, 0 failed.

  • Ran PHP syntax checks for the controller and smoke test.

• Notes:

  • Full-tree git diff --check still reports the pre-existing trailing blank line in todo.txt; scoped checks for this stage pass.