statecraft.
Catalog/rahi

036-manifest-and-schema-evolution

Manifest and schema evolution: a ledgered manifest transition, a checked migration history, and a restore that refuses what it cannot serve

Lifecycle approvedImplementation completeVerification unknownQualification unknown

Today a cell's manifest is frozen at its first boot: the manifest hash is the chain's genesis parent, Ledger::open checks the first record against the booted manifest on every open, and any change to the manifest (one added grant, otel switched on) makes serve exit 1 with an integrity error on the existing volume. Spec 015 B-8 names the missing step, "a deploy genesis record", and nothing defines it. Migrations have the mirror problems: serve accepts a store ahead of the binary, a changed migration under an applied version is skipped silently, and restore checks no compatibility. This spec makes a manifest change a signed transition record appended at deploy, checks the booted manifest against the chain's current manifest, records a checksum per migration, lets an older binary serve a newer schema only across migrations declared additive, and makes restore refuse an archive it cannot serve. It carries the worked consumer example for an upgrade, a rollback, and a restore.

Read the full pinned specification ↗

Relationships

Claimed units

  • establishes
    {
  "kind": "file",
  "path": "crates/rahi-ledger/src/transition.rs"
}
  • establishes
    {
  "kind": "file",
  "path": "crates/rahi-ledger/tests/transition.rs"
}
  • establishes
    {
  "kind": "file",
  "path": "crates/rahi-cli/tests/evolution.rs"
}
  • establishes
    {
  "kind": "file",
  "path": "crates/rahi-ops/tests/evolution.rs"
}
  • extends
    {
  "nature": "additive",
  "spec": "013-ledger-decision-chain",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ledger/src/chain.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "013-ledger-decision-chain",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ledger/src/verify.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "013-ledger-decision-chain",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ledger/src/lib.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "014-ledger-sealing-and-archive",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ledger/src/segment.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "014-ledger-sealing-and-archive",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ledger/src/seal.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "013-ledger-decision-chain",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ledger/tests/append.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "015-kernel-manifest-and-adjudication",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-kernel/src/lib.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "015-kernel-manifest-and-adjudication",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-kernel/src/manifest.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "015-kernel-manifest-and-adjudication",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-kernel/tests/adjudicate.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "011-store-hiqlite",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-store/src/migrate.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "011-store-hiqlite",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-store/src/lib.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "011-store-hiqlite",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-store/Cargo.toml"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "011-store-hiqlite",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-store/tests/migrate.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/src/migrate.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/src/restore.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/src/archive.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-cli/src/lib.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-cli/src/serve.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-cli/tests/cli.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-cli/src/verbs.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/src/backup.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/Cargo.toml"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "010-workspace-and-core-types",
  "unit": {
    "kind": "file",
    "path": "Cargo.toml"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/tests/common/mod.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/tests/restore.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "030-operational-verbs",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/tests/backup.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "037-identity-recovery-and-live-proof",
  "unit": {
    "kind": "file",
    "path": "crates/rahi-ops/tests/rauthy_restore.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "032-cluster-topology",
  "unit": {
    "kind": "file",
    "path": "deploy/README.md"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "039-release-and-out-of-tree-packaging",
  "unit": {
    "kind": "file",
    "path": "CHANGELOG.md"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "031-single-container-packaging",
  "unit": {
    "kind": "file",
    "path": "docker/entrypoint.sh"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "032-cluster-topology",
  "unit": {
    "kind": "file",
    "path": "deploy/k8s/migrate-job.yaml"
  }
}

Source headings

  1. 036: Manifest and schema evolution
  2. 1. Purpose
  3. 2. Territory
  4. 3. Behavior
  5. Manifests
  6. Migrations
  7. Restore
  8. Rolling updates at N=3
  9. 4. Functional requirements
  10. 5. Acceptance criteria
  11. The worked consumer example
  12. 6. Out of scope
  13. 7. Resolved decisions
  14. 8. Status
  15. Verification

Frozen anchors

No frozen anchors declared.