Repository navigation
The J5 ledger keys on projects, and every thread has a home (migration 030) #459
Description
Part of #412. Milestone: Squadron fold.
Outcome
A thread's home is its project. Every J5 table that keys on squadron_id keys on the project instead, through one J5 ledger migration (030). Every thread gets a home when it's created, with no separate registration step.
Scope (one slice, end to end on the server)
- Migration 030 (
apps/server/src/j5/a2a/migrations/). Re-keycomm_event,epic_membership/squadron_membership,j5_a2a_exchange,j5_a2a_delivery(receiver_squadron_id,origin_squadron_id), human inbox, placement, machine participants, and Crew instances and proposals from Squadron to project. Dropj5_a2a_squadron_project_referenceand the Squadron table once nothing reads them. - Snapshot. 030 is the migration that feat(server): the database is copied before a risky J5 ledger migration runs #429's
J5_LEDGER_SNAPSHOT_MIGRATIONS = [30]guards. Its fixtures cover the snapshot path. - Every thread has a home. The Registrar answers with the thread's
projectId. The native cohorts inSquadronLaunchPolicygo away: mobile-created threads, system bootstrap, legacy plan children, and imported conversations all register into their project. Backfill threads that have none today. - Services re-keyed:
LedgerService,SendService/DeliveryWorker(cross-Squadron double entry becomes cross-project),HumanInboxService,PlacementService,MachineParticipantService,LifecycleService, Crew services,SpawnCompositionService. Peer Agents and Crews inherit their spawner's project.
Migration rules (from #412)
| Case | Rule |
|---|---|
| One Squadron, one project | Its ledger, memberships, placement and Crews move to the project. |
| Several Squadrons on one project | Refuse by name. The error names the project and the Squadrons, and gives the repair (archive their agents, then POST /api/j5/squadrons/<id>/delete). The snapshot is untouched. |
| One Squadron, several projects | Refuse by name with the same repair. The UI never allowed it, but the create route did. |
| Squadron whose project was deleted | Decide in the PR, and record why. |
| Name differs from the project title | Keep the project title. The Squadron name is dropped. |
| Threads with no home | Backfill membership from projectId. |
Done when
- 030 runs on a
VACUUM INTOcopy of real data, and A2A send, Exchanges, the inbox, placement and Crews all work afterwards. - Each refusal case has a focused test, and a refused migration leaves the database unmigrated.
- Restoring the snapshot gets back to the previous version (the runbook from feat(server): the database is copied before a risky J5 ledger migration runs #429).
- Draft PR refactor(web): onboarding goes back to upstream's three stages #457 (onboarding back to upstream) merges with this one, because imported conversations now get a home.
Closes
Notes
This is the largest slice. It can land as a stack, but the migration and the services that read the new keys have to ship together.
Activity
Jacksondr5 commentedon Oct 18, 2026
Done. Landed 2026-10-08 in #482 (migration 031: 030 was already taken), together with #457. #484 and #489 followed with the internal and peer-wire renames.
thread.createdevent. Threads without a home are backfilled at startup.docs/j5/runbooks/dogfood-runtime.md.Known gap, not fixed: one Squadron with several projects is still refused and rolled back, but by the retired-table primary key rather than a named error with the repair. Only an install still before 031 that built that shape through the create route can hit it.
— Claude Opus 5.5, on Jackson's behalf