Operate / Platform maintainers

Compatibility and migration

Move versions and integrations while preserving artifact verification, stable failures, and stronger historical truth.

artifact continuity and compatibilityversioned package, schema, and release migrationComplete production checklist

Implementation rail · versioned package, schema, and release migration

Exact execution and operator checks

01
Operator check
Freeze migration inventory
Record source version, target version, exact repository root, artifact digests, schema revisions, incompatibilities, and rollback head.
Substantive records: /reference/compatibility · /reference/releases
Expected: The migration boundary is immutable and reversible.
02
Exact mechanic
Dry-run the installed migration
```
pnpm exec receiz migrate v105-v106 --dry-run --root .
```
Mechanic
receiz migrate v105-v106 --dry-run
Authentication and account boundary
Local repository and filesystem custody; no Receiz account is implied.
Exact source
node_modules/@receiz/sdk/dist/cli.js · SHA-256 a0e99f2429ccaf2a2a4adc31bb19b9ecb7bffbcaba03a9439c99310b200e0232
Expected: The installed CLI returns a migration plan without changing the repository.
03
Exact mechanic
Run test:interoperability-conformance
```
pnpm test:interoperability-conformance
```
Mechanic
pnpm test:interoperability-conformance
Authentication and account boundary
Authorized local repository checkout; the command proves only the checked repository boundary.
Exact source
package.json · SHA-256 132f99232dfaf26f7186b73752938d1377042808f42d60d374fe7b2e57c7646b
Expected: Transport, wrapper, and version compatibility contracts pass.
04
Operator check
Verify preserved artifacts
Compare every pre-migration artifact digest and verification result with the migrated projection; rollback on any proof-identity change.
Substantive records: /reference/schemas-test-vectors
Expected: Artifact truth is preserved and only compatible projections change.

Complete operating anatomy

Every boundary required to ship.

Solved outcome: The migration names source and target versions, preserved primitives, incompatibilities, transformed projections, verification, and rollback.
Prerequisites: Hold source and target versions, exact inventory, migration plan digest, artifact digests, schema revisions, incompatibility list, adapter version, and rollback head.
Exact primitive: artifact continuity and compatibility
Governing law: Compatibility and migration is governed by interoperability-conformance: A passing execution confirms the checked cross-system proof invariants for the exact repository state exercised. release-attestation-verify: A passing command verifies every bound attestation field for the supplied artifact. canonical-artifact-verifier: The verifier classifies the supplied artifact. Embedded subpayloads and remote responses remain subordinate.
Source-of-truth order: Receiz law → sealed artifact truth → deterministic proof object state → verified durable local or register truth → authenticated snapshot → server distribution, synchronization, indexing, and publication → database, session, observability, and interface projections.
Expected artifact, receipt, or state: A migration record that binds source version, target version, exact inputs, preserved artifact digests, outputs, failures, and rollback head.
Inspection: Inspect the compatibility matrix, schema revision, artifact digest continuity, and release record. Inspection exposes structure and receipt fields; inspection never establishes verification.
Independent verification: Independent verification for compatibility-migration: pnpm test:interoperability-conformance. This establishes only the artifact continuity and compatibility boundary named by the bound sources; The implementation rail remains beneath proof authority: versioned package, schema, and release migration.
Offline behavior: Previously admitted artifacts remain independently verifiable with their declared version mechanics; migration cannot make them untrue.
Identity and account boundary: Public Record Moment, Seal File, Verify, Export, and public proof reading are account-free. Identity is optional and adds continuity, custody, recovery, and governed private controls after proof admission.
Security boundary: Never migrate credentials through payload transformations; rotate compromised credentials as a separate controlled operation.
Conformance command: pnpm test:interoperability-conformance
Deployment checks: Dry-run against a production-equivalent inventory, verify the plan digest, migrate a bounded cohort, reverify every artifact and stable failure, observe compatibility, and retain immediate rollback to the prior proof head.
Production checklist: Dry-run; review transformations; verify plan digest; test unsupported schemas; migrate a bounded cohort; compare artifact digests and statuses; run interoperability conformance; rollback on any proof-identity change.
Rollback and containment: Containment for compatibility-migration: Apply is forbidden. Regenerate, review, and approve the new plan as a distinct operation. The migration violates artifact continuity. Rollback to the preserved source head and isolate the transformation. Compatibility is unproven. Pin the prior version or add an explicit compatible adapter and rerun conformance. Preserve every stronger held artifact and admitted state while the named boundary is corrected.

Fail closed

Mutation and failure matrix

The migration plan digest changes between review and apply.

Effect: Apply is forbidden.
Retry: Never confirm the changed plan implicitly.
Recovery: Regenerate, review, and approve the new plan as a distinct operation.

An artifact digest or verification status changes.

Effect: The migration violates artifact continuity.
Retry: Stop the cohort immediately.
Recovery: Rollback to the preserved source head and isolate the transformation.

The destination rejects a declared compatible schema or stable failure.

Effect: Compatibility is unproven.
Retry: Do not coerce or silently drop fields.
Recovery: Pin the prior version or add an explicit compatible adapter and rerun conformance.

Exact authority

Claim-to-source bindings

A passing execution confirms the checked cross-system proof invariants for the exact repository state exercised.
scripts/test_interoperability_conformance.tsexecutable-conformance · SHA-256 c09d81f36305004f7ee02c40070b3c9cd64d8f5572ce12d211c022f3e75dbf4e
A passing command verifies every bound attestation field for the supplied artifact.
scripts/verify_release_attestation.tssigned-evidence-verifier · SHA-256 f04e07009107c30a2c41a2f237ed08a581b4773caef3771d8167b762e23d6606
The verifier classifies the supplied artifact. Embedded subpayloads and remote responses remain subordinate.
packages/receiz-sdk/src/artifactVerification.tsimplementation-verifier · SHA-256 c10cdba92568fea273e1d9e7a3321083d52945378ab0cc83aee9720d44f0bba3

One complete system

Exact execution and operator checks

Freeze migration inventory

Dry-run the installed migration

Run test:interoperability-conformance

Verify preserved artifacts