fix(schema): bootstrap missing legacy ontology archives
What does this MR do and why?
Upgrades from v0.115.0 fail when the archive catalog is empty. The dispatcher now publishes the exact bundled schema93 archive before migration, so supported installations need neither manual seeding nor an intermediate release.
How an upgrade works
Yellow marks the fix; the remaining steps show migration through normal operation.
%%{init: {"themeVariables": {"fontSize": "13px"}, "flowchart": {"nodeSpacing": 20, "rankSpacing": 22, "padding": 8}}}%%
flowchart TD
Start[New release starts] --> Publish[Publish this version's archive]
Publish --> Archive{Is the active schema's<br/>archive usable?}
Publish -->|Cannot publish| Blocked[Stop startup<br/>Keep the active schema unchanged]
Archive -->|Missing| Restore[NEW: publish the exact archive<br/>from the release bundle]
Restore -->|Published| Archive
Restore -->|Unsupported version or failure| Blocked
Archive -->|Corrupt or unreadable| Blocked
Archive -->|Yes| Tables[Prepare target tables<br/>Reuse unchanged data where possible]
Tables --> Backfill[Indexers rebuild affected data<br/>Current schema stays active]
Backfill --> Complete{Required backfill complete<br/>and target archive valid?}
Complete -->|Not yet: wait and recheck| Complete
Complete -->|Yes| Promote[Make target schema active<br/>Retire the previous schema]
Promote --> Running[Serve queries and keep indexing]
Running -.-> Retention[Keep older tables for rollback<br/>Clean up according to retention policy]
classDef recovery fill:#fff2cc,stroke:#b8860b,color:#333;
class Restore recovery;Fresh installs create initial tables; unchanged schemas skip rebuilding. Rollback can reuse retained tables. Code indexing can continue after promotion.
Related Issues
Relates to #184 (closed). Prerequisite for !2459 (merged).
Testing
2,592 workspace unit tests and 306 schema tests passed, along with Clippy and build-validation checks. The original fix also passed the real GDK schema93-to96 upgrade, fault recovery, concurrent dispatchers, fresh installation, authenticated CDC, and documentation checks.
Performance Analysis
- This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
No request-path changes; not benchmarked.
Agent context
Missing unbundled versions still stop migration. The validation report covers provenance, injected faults, test results, and harness limitations. Serving and locking are unchanged. Rebase !2459 (merged) and rerun its combined E2E suite after this prerequisite merges.
Cleanup validation covers the dispatcher regression, mutation test, build guards, and rerun suites at 14837d441. The shutdown cancellation race is tracked separately in #1285.