argand-site-registry/docs/MIGRATING-0.4.md

Migrating from 0.3 to 0.4

Back up the writer database, source cache, generations, approvals, and trust files before upgrading. Do not edit a complete generation in place.

1. Install the 0.4 binary and run verify against every retained 0.3 generation using their existing trusted pins.
2. Open the writer with 0.4. Migrations add authenticated votes and immutable observation batches, moving PRAGMA user_version from 3 to 5 without removing source or legacy review history.
3. Keep existing v1 source manifests as isolated legacy scopes. Use v2 manifests with explicit full/partition/delta coverage for new replacement chains.
4. Use the strict reference policy or supply a reviewed policy JSON. Create an independent OpenSSH reviewer allowed-signers file. Strict build requires --reviewer-trust; its exact bytes are bound into the receipt.
5. Use review-queue and evidence to find each name, edge, and equivalence that needs votes. Prepare, sign, verify, and append votes, then rebuild.
6. Expect resolve to abstain until the selected name and destination edge each satisfy the new quorum. Audit lookup remains available throughout migration.
7. Compare stats, diff, export, and export-audit; replay evaluation; then sign and activate with a publisher identity and key that did not approve.

The legacy compatibility policy exists for controlled replay and transition. It is not the CLI default and does not provide the reference two-reviewer guarantee. Legacy approvals remain auditable. A publisher should collect new votes rather than silently translating old reviews into quorum votes.

Behavior changes

• Name bindings and website edges now have separate review identities. A new alias needs its own name votes and cannot inherit a route. An accepted alias update does not invalidate an unchanged website edge.
• Votes bind the exact review policy. Changing thresholds or reviewer groups makes earlier votes stale under the new policy; the source evidence is unchanged.
• Reviewer time is advisory. Effective validity starts at the later of signed reviewed_at and writer accepted_at, and ends no later than 90 days after acceptance.
• One retained authenticated revocation is sticky across policy epochs. Ordinary later approvals do not clear it. Every approval in a fresh quorum must explicitly supersede every active revocation ID.
• Publisher-signed cumulative feeds can apply new blocks to an older compatible pinned registry before the complete replacement arrives. Their policy, rules, reviewer trust, and prior-feed continuity are verified.
• Active export omits superseded and rejected facts. export-audit retains them with explicit state.
• A strict receipt binds selected coverage, review policy, reviewer trust bytes, and the decision-time contract. Consumers reject unknown contracts.
• Observation imports and observer caches are evidence only. New or changed observations make existing edge evidence stale and return the item to review.

The 0.4 reader accepts current v2 receipts. Rollback validation can open pinned v1 receipts using rules v1-v3 only to compare retained revocations. Preserve old generation directories and pins until every consumer has moved successfully.