Skip to content

fix(server): the update preflight refuses a database whose J5 ledgers a newer build migrated - #1076

Merged
Jacksondr5 merged 1 commit into
j5/mainfrom
j5code/518-preflight-j5-ledgers
Nov 17, 2026
Merged

Jacksondr5 merged 1 commit into
j5/mainfrom
j5code/518-preflight-j5-ledgers

Conversation

@Jacksondr5

Copy link
Copy Markdown
Owner

Problem

Before a background service moves to a staged build, upstream's service preflight refuses a database that records upstream migrations the build doesn't know. It reads only upstream's ledger. J5 keeps two more, and J5-only migrations are common between J5 releases: v0.0.51 and v0.0.52-nightly.20261029.12 differ only in the J5 ledger (46 against 47). So the preflight let an older build onto a database it can't read.

Part of #518 (step 1). Step 2, update running the preflight, waits for upstream.

What changed

  • New J5-owned apps/server/src/j5/persistence/newerJ5Migrations.ts reads j5_a2a_migrations and j5_run_observability_migrations read-only, as upstream's recordedMigrations does, and lists ids above this build's heads.
    • A missing ledger counts as empty.
    • An unreadable database blocks.
  • runServicePreflight adds that list to upstream's with one call.
  • The run-observability migrator exports its table name and ids, without changing how it runs.

The check runs inside the staged build, so it protects a downgrade only to builds that contain it. Builds before this one, including stable v0.0.51, can't be checked. Covering those needs release metadata (#927).

Live testing

Pass at 7d62485039. The head (209fdd5d48) is that commit rebased onto one docs-only commit (#1075), so it was not re-tested. Tester: GPT-6.1 Sol in its own worktree, test home from setup-agent-live-test.ts, then --fresh. All checks ran __service-preflight live, against copies of a database a real server had migrated, with the server stopped:

  • Accepted: the migrated database (heads J5 ledger 57, run-observability 1, upstream 79), a missing path, and a fresh home's database.
  • Refused: a newer row in j5_a2a_migrations, in j5_run_observability_migrations, and in upstream's ledger. Each reason names the table and the migration.
  • The way back: deleting the added row made each copy pass again.
  • One real Claude Haiku turn through the UI completed, checked in the stored turn record.

Not exercised live: the in-app server update that stages a release and runs this preflight, because exercising it would touch the machine's real background service. The unit test covers the hook through runServicePreflight.

Upstream impact

  • apps/server/src/cloud/servicePreflight.ts: one import and one call, recorded as FORK.md case 117. The ledger row now reads B, 50, 117.
  • No change to what upstream's product does: its preflight refuses the same way, and now also counts J5's own data. No register entry.

Council review

Rounds: 1

Delegate Round 1
Claude Opus 5.5 9/10
GPT Sol 6.1 10/10
Grok not run (provider disabled on this server)

Opus's points:

  • The test's database handle stays open if an early assertion fails. Kept, to match upstream's own preflight test.
  • Builds before this one aren't covered. Noted above.
  • A second read-only open per preflight. It fails closed, and the live database's journal mode never makes a reader wait.

No code changed after review.

Checklist

  • One concern: the description has no "also"
  • Tests cover the changed behavior: newerJ5Migrations.test.ts fails on j5/main for both ledgers
  • UI changes: not applicable, no UI
  • Live testing: the section above says what ran live and what did not
  • Upstream-owned files: each one is recorded in FORK.md (case text and file-table row) in this PR
  • Upstream product: no change to what upstream's product does
  • Surfaces: server-only. Web, desktop and mobile follow, since the preflight answer already reaches them. No provider, contract, or connection-mode change.
  • Docs: no definition or user doc changes. The runbooks' "no downgrade guard" still holds for j5 update until step 2.

Claude Opus 5.5 via Claude Code in J5 Code.

🤖 Generated with Claude Code

… a newer build migrated

Upstream's service preflight only reads effect_sql_migrations, so a staged
older build passed it when the database held J5-only migrations, which are
common between J5 releases. The preflight now also checks j5_a2a_migrations
and j5_run_observability_migrations (#518, FORK.md case 117).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
j5-code Ready Ready Preview Nov 17, 2026 12:24am UTC

Request Review

@github-actions github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:M 30-99 effective changed lines (test files excluded in mixed PRs). labels Nov 17, 2026
@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Service preflight now checks newer records in the J5 A2A and run-observability migration ledgers alongside upstream migrations. The helper reads the ledgers without writing to the database. Tests cover ready and blocked outcomes.

Changes: J5 migration preflight

Layer / File(s) Summary
Expose run-observability migration metadata
apps/server/src/j5/run-observability/Migrations.ts
The migration table name and numeric migration IDs are exported. runMigrations uses the exported table name and module-level migration record.
Read and combine newer J5 migration records
apps/server/src/j5/persistence/newerJ5Migrations.ts
The helper reads records beyond the current heads in the J5 A2A and run-observability ledgers. It combines those records with upstream migrations, or returns null when the history cannot be determined.
Use J5 migration records in service preflight
apps/server/src/cloud/servicePreflight.ts, apps/server/src/j5/persistence/newerJ5Migrations.test.ts, FORK.md
Service preflight passes the database path and upstream migrations to the helper. Tests check ready and blocked results for newer ledger IDs. FORK.md documents case 117.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant runServicePreflight
  participant withNewerJ5Migrations
  participant SQLiteDatabase
  runServicePreflight->>withNewerJ5Migrations: Pass database path and upstream migrations
  withNewerJ5Migrations->>SQLiteDatabase: Read J5 migration ledgers
  SQLiteDatabase-->>withNewerJ5Migrations: Return newer records or a read failure
  withNewerJ5Migrations-->>runServicePreflight: Return combined migrations or null
Loading

Possibly related issues

Possibly related PRs

  • Jacksondr5/j5code#720: This PR adds an A2A migration that updates the migration list used to determine the ledger head.
  • Jacksondr5/j5code#660: This PR adds an A2A migration that updates the migration list used to determine the ledger head.

Suggested reviewers: bryantderosier, tyler-barton-horizon

Merge Risk: Minimal · up to 209fd

The server update preflight now also blocks when the database holds newer J5 migrations than the build knows about. The change is read-only and is covered by a unit test through the preflight entry point. No merge-blocking risk was found. The rebased head was not re-tested live, and builds that predate this change are not covered.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: the update preflight now also checks J5 migration ledgers (a newer build's J5 migrations block a downgrade). It is specific, single-sentence, and matches the changeset…
Description check Passed The description follows the repository template: Problem, What changed, Live testing, Upstream impact, and Checklist are present. The UI changes section is omitted, which is allowed because the change…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: the update preflight now also checks J5 migration ledgers (a newer build's J5 migrations block a downgrade). It is specific, single-sentence, and matches the changeset (servicePreflight.ts, newerJ5Migrations.ts, FORK.md case 117). The 'fix(server):' prefix is a conventional-commit style, which is acceptable.

Full details: Description check

Explanation

The description follows the repository template: Problem, What changed, Live testing, Upstream impact, and Checklist are present. The UI changes section is omitted, which is allowed because the change has no UI. The Upstream impact section names the upstream-owned file, its FORK.md case (117), and the ledger row. The Live testing section gives the commit tested, the head, what ran live, and what did not. The description does not include a 'Closes #' issue link. It links Part of #518 instead, which is a partial tracking reference. The 'Council review' section is extra but does not conflict with the template. The description is mostly complete.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

LanguageTool

FORK.md

LanguageTool checks are incomplete because the per-file request limit of 5 was reached. Remaining text was skipped; findings from completed checks are retained.

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between cafe6d5 and 209fdd5.

Files selected for processing: 5

  • FORK.md
  • apps/server/src/cloud/servicePreflight.ts
  • apps/server/src/j5/persistence/newerJ5Migrations.test.ts
  • apps/server/src/j5/persistence/newerJ5Migrations.ts
  • apps/server/src/j5/run-observability/Migrations.ts

Included review availability: This review used your included allowance. 3 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour.

@Jacksondr5
Jacksondr5 merged commit 5cb114d into j5/main Nov 17, 2026
31 checks passed
@Jacksondr5
Jacksondr5 deleted the j5code/518-preflight-j5-ledgers branch November 17, 2026 00:40

This branch was successfully deployed

1 active deployment
Preview — 209fdd5d Deployed Nov 17, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:M 30-99 effective changed lines (test files excluded in mixed PRs). vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant