Add atomic release readiness contract - #332
Conversation
mira-2026
added
priority: high
|
Warning Review limit reached
Next review available in: 40 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe PR adds checksummed release manifests and schema compatibility validation, replaces legacy health reporting with live, ready, and diagnostics endpoints, adds release-aware worker readiness, updates frontend indicators, and aligns startup, deployment, tests, and documentation with the new runtime contract. ChangesRuntime readiness and release activation
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant DeployPrepare
participant ReleaseManifest
participant Dashboard
participant HealthAPI
participant Frontend
DeployPrepare->>ReleaseManifest: build artifacts and write release-manifest.json
Dashboard->>HealthAPI: GET /api/health/ready
HealthAPI->>ReleaseManifest: load and verify runtime identity
HealthAPI-->>Dashboard: isReady or notReady
Frontend->>HealthAPI: GET /api/health/diagnostics
HealthAPI-->>Frontend: checks, release details, and session count
Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 98ee0aae20
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@backend/src/health.ts`:
- Around line 52-75: Update databaseReadiness() to capture the caught error and
log its details before returning the existing not-ready response, matching the
diagnostic behavior of isWorkerReady(). Preserve the current readiness fields
and fallback behavior while ensuring failures such as locking, corruption, or
missing files are observable.
In `@backend/src/services/pullRequests.ts`:
- Line 1476: Update the readiness probe curl command in the deployment script to
include an explicit, bounded timeout so a stalled server cannot block
indefinitely. Preserve the existing failure-silent behavior and health endpoint
check while ensuring the deployment job proceeds to record failure or release
its lock when the timeout is reached.
In `@backend/test/httpApiBehavior.test.ts`:
- Line 313: Remove the duplicated live declarations in the test blocks: in
backend/test/httpApiBehavior.test.ts at lines 313-313 and
backend/test/bunNativeServerBehavior.test.ts at lines 327-327, retain only one
const live = await api(...) declaration per block.
In `@docs/api/overview.md`:
- Around line 52-53: Update the status-code documentation for GET
/api/health/ready to state that it returns 503 whenever any required readiness
check fails, rather than limiting the condition to a missing frontend build;
leave the liveness endpoint documentation unchanged.
In `@docs/operations/troubleshooting.md`:
- Line 108: Update the troubleshooting restart flow to use the manifest-aware
production preparation command deploy:prepare instead of plain bun run build,
matching the documented preflight and checksummed manifest generation required
by readiness. Preserve the existing restart and readiness-check steps.
In `@docs/security/auth-and-trust-boundaries.md`:
- Around line 17-18: Update the two health-route bullets in the authentication
and trust-boundaries documentation to use the accurate GET|HEAD method notation,
matching the allowances in requestPolicy.ts and the convention in README.md.
In `@docs/setup/new-vps.md`:
- Around line 193-197: Update the “Healthy response shape” example in the
readiness documentation to either include all actual readiness snapshot
fields—database, frontend, release, worker, gateway dependency, and status—or
explicitly label the current JSON as abbreviated. Ensure the example does not
imply that only the worker check is reported.
In `@docs/setup/production-deploy.md`:
- Around line 301-305: Update the health endpoint documentation near the
liveness and readiness descriptions so the HTTP 503 behavior is explicitly
scoped to /api/health/ready when activation checks fail. Keep /api/health/live
described solely as the process-liveness probe that confirms the web process can
answer requests.
- Line 191: Update the rollback sequence in the production deployment
documentation to use deploy:prepare, or an equivalent rollback-specific step,
before restarting services. Ensure it regenerates the ignored release manifest
and validates the declared SQLite compatibility window, while preserving the
readiness check afterward.
- Line 107: Replace the single readiness request in
docs/setup/production-deploy.md:107-107 with bounded polling that retries until
the endpoint succeeds or a finite retry limit is reached. Apply the same bounded
readiness retries in docs/operations/runbooks.md:27-27 after restarting
Dashboard and docs/operations/runbooks.md:234-234 after restoring and starting
both services; preserve failure after retries are exhausted.
In `@src/components/layout/AppHeader.tsx`:
- Around line 29-31: Update the status derivation around isWorkerReady in
AppHeader to preserve three states: ready, offline, and unknown when health
diagnostics or worker telemetry are unavailable or failed. Distinguish unknown
from an explicit worker readiness value of false, and update the badge rendering
near the worker status UI to use a neutral style and “Worker status unavailable”
label for unknown while retaining existing ready/offline behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 693ce3a0-8628-486c-9c8a-3bb9253f857f
📒 Files selected for processing (35)
.github/ISSUE_TEMPLATE/ops_deploy.yml.gitignoreREADME.mdbackend/src/databaseMigrationRunner.tsbackend/src/databaseSchemaCompatibility.tsbackend/src/frontendAssets.tsbackend/src/health.tsbackend/src/releaseManifest.tsbackend/src/requestPolicy.tsbackend/src/routes.tsbackend/src/server.tsbackend/src/services/pullRequests.tsbackend/test/bunNativeServerBehavior.test.tsbackend/test/databaseLifecycle.test.tsbackend/test/healthReadiness.test.tsbackend/test/httpApiBehavior.test.tsbackend/test/releaseManifest.test.tsbackend/test/serverStartupPolicy.test.tsbackend/test/serviceBehavior.test.tsbackend/test/utilityBehavior.test.tsdocs/api/endpoints.mddocs/api/overview.mddocs/architecture/gateway-and-chat.mddocs/architecture/overview.mddocs/operations/runbooks.mddocs/operations/troubleshooting.mddocs/security/auth-and-trust-boundaries.mddocs/setup/new-vps.mddocs/setup/production-deploy.mdpackage.jsonscripts/frontendBuild.tsscripts/writeReleaseManifest.tssrc/components/layout/AppHeader.tsxsrc/hooks/useHealth.tssrc/test/frontendBehavior.test.tsx
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: frontend-checks
- GitHub Check: backend-checks
- GitHub Check: Analyze JavaScript and TypeScript
🔇 Additional comments (31)
src/hooks/useHealth.ts (1)
7-26: LGTM!Also applies to: 29-30
src/test/frontendBehavior.test.tsx (1)
755-771: LGTM!Also applies to: 897-898, 1538-1538, 1563-1570, 3240-3256, 3316-3316
README.md (1)
106-124: LGTM!docs/setup/new-vps.md (1)
186-188: LGTM!Also applies to: 199-203
.github/ISSUE_TEMPLATE/ops_deploy.yml (1)
50-50: LGTM!docs/setup/production-deploy.md (3)
55-59: LGTM!
137-140: LGTM!
269-295: LGTM!Also applies to: 297-300, 306-318
docs/architecture/gateway-and-chat.md (1)
50-61: LGTM!Also applies to: 609-610
docs/architecture/overview.md (1)
99-100: LGTM!docs/operations/runbooks.md (1)
9-9: LGTM!Also applies to: 19-20, 22-26, 28-28, 32-32
backend/src/databaseMigrationRunner.ts (1)
7-7: LGTM!Also applies to: 80-110, 174-174, 183-183
backend/src/databaseSchemaCompatibility.ts (1)
1-41: LGTM!backend/test/databaseLifecycle.test.ts (1)
511-548: LGTM!backend/test/healthReadiness.test.ts (1)
1-88: LGTM!backend/src/releaseManifest.ts (1)
1-573: LGTM!.gitignore (1)
14-14: LGTM!scripts/frontendBuild.ts (1)
32-32: LGTM!scripts/writeReleaseManifest.ts (1)
1-16: LGTM!package.json (1)
15-16: LGTM!backend/test/releaseManifest.test.ts (1)
1-282: LGTM!backend/src/health.ts (2)
1-51: LGTM!Also applies to: 77-137
139-146: 🔒 Security & PrivacyNo change needed for
diagnosticsSnapshotauthorization.
GET /api/health/diagnosticsis wrapped bywithRequestPolicy(routeTable), andrequestPolicy.tsrejects non-public API routes unless a valid HTTP session or automation credential is present.backend/src/frontendAssets.ts (1)
1-20: LGTM!backend/src/routes.ts (1)
2-2: LGTM!Also applies to: 34-59
backend/src/requestPolicy.ts (1)
86-87: LGTM!backend/src/server.ts (1)
15-15: LGTM!backend/test/utilityBehavior.test.ts (1)
717-736: LGTM!Also applies to: 793-922
backend/test/serverStartupPolicy.test.ts (1)
609-614: LGTM!backend/test/serviceBehavior.test.ts (1)
1974-1975: LGTM!docs/api/endpoints.md (1)
8-13: LGTM!
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5594198fe2
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eda80c0120
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6b975a78a9
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6b975a78a9
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e8453cac3e
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e8453cac3e
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 23169b489a
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b378ed0aaa
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d33a8bb592
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f0a1c009cb
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@backend/src/serverStart.ts`:
- Around line 86-95: Update startBackendServer to store its in-flight startup
promise and return that same promise when another caller arrives while startup
is already running. Ensure concurrent callers observe the first startup’s
success or failure, and clear the stored promise after completion while
preserving the active-server guard.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: b9a07a8f-4194-463b-96d9-2efa15198e8b
📒 Files selected for processing (17)
backend/scripts/build.tsbackend/scripts/buildSourceIdentity.tsbackend/src/releaseManifest.tsbackend/src/requestPolicy.tsbackend/src/routes.tsbackend/src/serverStart.tsbackend/src/services/logRotation.tsbackend/src/workerStart.tsbackend/test/buildSourceIdentity.test.tsbackend/test/httpApiBehavior.test.tsbackend/test/releaseManifest.test.tsbackend/test/serverStartupPolicy.test.tsbackend/test/utilityBehavior.test.tsdocs/setup/new-vps.mddocs/setup/production-deploy.mddocs/setup/secrets-and-env.mdscripts/frontendBuild.ts
💤 Files with no reviewable changes (1)
- docs/setup/secrets-and-env.md
🚧 Files skipped from review as they are similar to previous changes (7)
- backend/src/requestPolicy.ts
- docs/setup/new-vps.md
- backend/src/routes.ts
- backend/test/httpApiBehavior.test.ts
- docs/setup/production-deploy.md
- backend/test/utilityBehavior.test.ts
- backend/test/releaseManifest.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: backend-checks
- GitHub Check: frontend-checks
🔇 Additional comments (14)
backend/src/releaseManifest.ts (1)
39-39: LGTM!Also applies to: 79-96
backend/scripts/buildSourceIdentity.ts (1)
1-42: LGTM!backend/test/buildSourceIdentity.test.ts (1)
1-74: LGTM!backend/scripts/build.ts (1)
4-9: LGTM!Also applies to: 28-28, 38-50
scripts/frontendBuild.ts (1)
6-9: LGTM!Also applies to: 39-50, 78-90
backend/src/workerStart.ts (1)
2-5: LGTM!Also applies to: 22-23, 32-32
backend/test/serverStartupPolicy.test.ts (1)
1-8: LGTM!Also applies to: 229-231, 241-315, 451-451, 474-492, 539-539, 599-601, 652-653
backend/src/serverStart.ts (5)
3-6: LGTM!
49-64: LGTM!
133-133: LGTM!
149-149: LGTM!
174-174: LGTM!backend/src/services/logRotation.ts (2)
110-110: LGTM!
2034-2036: LGTM!Also applies to: 2045-2049
2 participants
Summary
Part 1 of 3 for #378.
WKstatus badge besideWSandBE/healthand/api/healthcontractsCompatibility
6..6compatibility window/api/health/readyVerification
git diff --checkpassFollow-up
PR 2 will add immutable release directories, atomic
current/previousactivation, and automatic rollback. PR 3 will connect that model to the Dashboard deploy flow, retention, and the controlled production cutover.