Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Release contract records and upgrade navigation
These are release facts, not an automatic promise to migrate every recorded release. The first supported upgrade baseline is 0.2.0 once it is published and its snapshot is merged. Historical 0.1.0 remains recorded but is outside the supported migration scope.
Upgrade and manual recovery
Supported upgrade readers accept the released sources declared by the support policy. This does not promise that an older binary can read data written by a newer release. Do not downgrade an initialized data directory in place. Manual recovery requires a complete pre-upgrade backup and the corresponding binary verified to read it; restore the whole store group, not selected tables or files.
Observation format 5 changes the physical protocol carriers. On a supported format 1–4 upgrade, startup preserves the original three-store group, keys, auxiliary state and matching old package, then seals the stopped Observation DB/WAL/SHM/object/staging directory with a same-filesystem rename. It starts a fresh format-5 store with current configuration, credentials and routing. Old observations are not converted or merged into current queries; history and statistics begin at cutover. Current-format stores and their capacity policy are preserved on ordinary restart.
Desktop reuses the verified previous package from its installation handoff. A
headless operator must retain the old package and provide its absolute directory
through HIROUTE_RECOVERY_PACKAGE on the first sealing startup. Missing keys or
recovery material stop startup without clearing data. Interrupted publication
resumes the original batch; missing or replaced archive material is not permission
to initialize an empty store. Unfinished older conversion generations remain
preserved for whole-group recovery.
Installers retain the matching old program/resources through a protected handoff bound to the storage root and target daemon image. Linux managed services and Windows Tasks consume that record without relying on the shell's environment. New candidate preflight checks observable prerequisites before replacement; startup repeats admission under its writer barrier. The actual updater shipped by the supported source must be tested. In particular, v0.3.1 runs its own helper: a new helper does not retrofit its precommit checks. A format-changing release requires a verified source/transition route before publication; documentation or a rebuilt same-version updater is not that evidence.
On startup refusal, the storage-owned cause/action is available through the native failure
page and hiroute service recovery --output json. Current production recovery does
not offer program-only original-version reinstallation. A changed/mixed/unknown group
cannot authorize an old-service launch, including during Windows installer rollback.
Recognized batches may resume with the current version; complete restoration uses the
correct verified batch, retaining newer data and program separately. Missing essential
material requires preservation and diagnosis, not blind retries or empty initialization.
Startup does not enumerate, hash, copy or normalize historical Observation contents. The source manifest verifies copied recovery material and binds the sealed directory's native identity; it does not claim eager full-content integrity verification. This local recovery point still occupies disk and is not an independent disaster-recovery copy. Protected sources/packages are excluded from the active Observation threshold and are never deleted by its capacity policy.
For manual recovery, stop the daemon, preserve later new-format data separately,
check the old source offline, and restore its complete original storage group
and auxiliary state at the recorded original locations with the matching old
package, following the generated recovery guide. Never mix old business stores
with newer Observation data or restore only activity.db. An independent copy
and full-content check can be made offline, outside service startup.
Branch-route publications may contain source_binding_id in the persisted active,
prepared or last-known-good Gateway aggregate. Version 0.3.1 and earlier strict readers
reject this field, even though the enclosing contract remains
hiroute.gateway-publication/v3. After such a publication, using an old binary against
the updated directory is unsupported. The current reader authenticates and rebuilds
older aggregates from their sealed Plans; the reverse path is not supported. Keep the
pre-upgrade backup if reverting to an earlier release may be necessary.
Read the recorded release
The version is data, not a skill constant. From the repository root run:
python3 scripts/release-contracts.py check
python3 scripts/release-contracts.py current
PR CI also compares every historical snapshot byte-for-byte with the actual PR base; editing
or deleting its evidence fails even if the index is recomputed. An explicitly superseded
unpromoted snapshot is retained byte-for-byte in archive/<tag>.<full-revision>.json.
Locally use check --base BASE_REF for
the same check. The index itself is regenerated as new snapshots are appended.
The index selects the highest recorded stable
semantic version. Each adjacent <tag>.json snapshot freezes the exact published commit,
repository/tag/channel, publication time, installer names/sizes/SHA-256, released SQL schema,
compatibility register and CLI contract-set descriptor. The register and descriptor retain
both their original source-byte digest and parsed content. Read other affected types, schemas
and producer behavior with git show REVISION:path; the current file is not the old contract.
The snapshot is evidence, not another current contract producer or a promise of migration support.
Fetch missing source objects/tags from the configured public remote without replacing an existing tag. A missing/moved tag or index/hash mismatch must be resolved, not regenerated into agreement. Never use a branch tip or a same-version development package as the released source. Archived snapshots verify their original commit and contract bytes without requiring the superseded tag to continue pointing at that commit; active snapshots still require the exact tag.
Before compatibility work and release handoff, compare the index with the observed public stable
Release channel (use the repository in the snapshot). A newly published Release may have its
snapshot PR pending. Resolve that gap through the release workflow/PR before treating the recorded
baseline as current. Retain all older sources still declared supported; latest_stable is not an
end-of-support rule. The retired schema22 trial recovery catalog is no longer an upgrade entry;
published 0.1.0 records remain immutable historical facts, while 0.2.0 is the first supported baseline.
Publication and retry
Prepare the macOS ARM64/Intel and Linux x86_64/ARM64 assets with the release candidate builder. It supplies measured website artifact rows; this workflow consumes the reviewed catalog and published bytes.
Release workflow verifies the published assets and
package identities, then publishes the installers/site. Only after those jobs succeed does
record-contracts call the PR publisher.
It reads the verified manifest revision and exact released source, cross-checks published asset
sizes/digests, and proposes only contracts/releases/ changes on chore/release-contracts-<tag>.
Normal review/checks and merge into main advance the repository's baseline. The workflow never
approves or merges its own PR. Existing snapshots are immutable; older reruns and previews retain
the highest stable baseline. A repeat reuses the same open PR; after merge it is a no-op. Failed
PR creation leaves a retryable branch. A closed PR, conflicting histories or unrelated edits on
that branch require review rather than force-pushing over them. With two pending release PRs,
merging one may cause an index conflict in the other; retain both snapshots, take the merged
main's index, and rerun record for the latter release with its verified inputs, then run check.
The job needs contents: write and pull-requests: write, plus the repository Actions setting
that allows GitHub Actions to create pull requests. GitHub exposes that setting together with
permission to approve; this workflow contains no approval action. PR checks must run through
the ordinary pull-request event and repository review policy. If GitHub marks the bot-created
workflow run as awaiting approval, an authorized reviewer must approve that run; a manual
workflow_dispatch run is not a substitute for required PR checks. See the
GitHub event-trigger rules.
If publication succeeds but recording fails, fix the reported cause and rerun the failed job.
This does not undo the published release. Initial backfill uses gh release view TAG --repo REPO --json tagName,isDraft,isPrerelease,publishedAt,assets saved to a local file, followed by:
python3 scripts/release-contracts.py record --release-json /path/to/release.json \
--manifest /path/to/verified-releases.json --revision FULL_SOURCE_SHA --repository OWNER/REPO
python3 scripts/release-contracts.py check
The manifest must be the one verified against the published package bytes and source identity. Generate twice and confirm the second run has no diff. Commit the snapshot/index through a normal PR. Do not edit historical snapshots or overwrite a collision to get a green check. Publication records and contract-source checks do not establish real old-package upgrade/manual restoration; supported-source acceptance remains a separate release obligation after the first 0.2.0 baseline.
Explicit replacement before promotion
An owner may authorize replacing a same-version release before public promotion. This is an
exceptional publication decision, never inferred from the version number or a moved tag. Build
and verify the new exact source and package identities first; retain the old source and artifact
identities. Then manually dispatch publish-release with the tag and
supersede_unpromoted_revision set to the exact previous 40-character source SHA. The ordinary
release event and default dispatch cannot replace an existing record.
After package/site publication, recording archives the previous snapshot without changing any
byte and updates only the active same-tag record and index. The repository and channel must
remain unchanged and the new source revision must differ. The replacement PR uses
chore/release-contracts-<tag>-<new-revision-prefix> so a previously merged snapshot PR cannot
block the replacement. Review and merge it normally. Local recovery uses
record --supersede-unpromoted-revision OLD_FULL_SHA with the same verified publication inputs;
repeating it is idempotent, including recovery after the active record was written but its index
was not. check --base BASE_REF protects both prior archives and the newly archived old record.
Archived trial records do not introduce another supported migration baseline. For the authorized 0.2.0 replacement before promotion, the active verified 0.2.0 record establishes that baseline; the earlier package identities remain historical evidence.
Find the current storage and upgrade boundaries
Inspect the current support register, dispatch and affected tests; this navigation does not fix any particular product or SQL version as the target.
| Responsibility | Existing entry |
|---|---|
| Current contracts, retained readers and fixtures | compatibility support register |
| First supported baseline | 0.2.0; the schema22 trial recovery catalog and package-selection entry have been retired |
| Startup, backup batches and SQL/payload dispatch | crates/local-storage/src/lib.rs, crates/local-storage/src/migrations/mod.rs and its dispatched modules, daemon startup |
| Startup format admission and current integrity | crates/local-storage/src/migrations/startup_format.rs, current_storage.rs; unsupported old stores are preserved and refused |
| Stable facts and execution projection | crates/domain/src/routing/stored.rs, stored_capability.rs, capability_compiler.rs; publication/Operation stored codecs |
| Operation, secret and native recovery | crates/domain/src/operation/, crates/local-storage/src/secrets/, crates/local-storage/src/agents/ |
| Public CLI | Frozen CLI descriptor in the release snapshot; schemas and consumer/application-api code at its revision |
| Gateway semantics | Affected ingress/serializer/response code at the released revision and production listener tests |
| Current source fixtures and restart regressions | Registered fixtures, stable-codec tests and production publication/recovery scenarios |
Trace concrete format markers, complete-source backup rules and the three-store coordinator as well as SQL dispatch. A future migration is not implemented merely because its number appears in documentation. Users need not install intermediate binaries when the current startup actually implements and validates the complete supported source-to-current chain.