chainlesschain 0.166.17 → 0.166.18

package/src/lib/evolution/skill-release-registry.js

@@ -5,7 +5,11 @@ import path from "node:path";
 import { types as utilTypes } from "node:util";
 import { getHomeDir } from "../paths.js";
 import { ensurePrivateDirectory, ensurePrivateFile } from "../secure-fs.js";
-import { verifySkillCandidateDraft } from "./skill-candidate-registry.js";
+import {
+  SKILL_CANDIDATE_MIGRATION_RECEIPT_SCHEMA,
+  SKILL_CANDIDATE_MIGRATION_RECORD_SCHEMA,
+  verifySkillCandidateDraft,
+} from "./skill-candidate-registry.js";
 import {
   SKILL_MUTATION_OPERATIONS,
   SKILL_MUTATION_RECEIPT_KINDS,
@@ -17,7 +21,7 @@ import {
   verifySkillMutationConsumptionReceipt,
   verifySkillMutationRequest,
 } from "./skill-mutation-authority.js";
-import { consumeRegistryTransitionCapability } from "./skill-promotion-controller.js";
+import { consumeRegistryTransitionCapability } from "./skill-registry-transition-capability.js";
 
 export const SKILL_RELEASE_SCHEMA = "chainlesschain.skill-release/v4";
 export const SKILL_RELEASE_STATE_SCHEMA =
@@ -30,6 +34,30 @@ export const SKILL_RELEASE_TENANT_MARKER_SCHEMA =
   "chainlesschain.skill-release-tenant-marker/v1";
 export const SKILL_RELEASE_MIGRATION_REQUIRED_CODE =
   "SKILL_RELEASE_MIGRATION_REQUIRED";
+export const SKILL_RELEASE_MIGRATION_RECORD_SCHEMA =
+  "chainlesschain.skill-release-migration/v1";
+export const SKILL_RELEASE_MIGRATION_AUTHORITY_SCHEMA =
+  "chainlesschain.skill-release-migration-authority/v1";
+export const SKILL_RELEASE_MIGRATION_RECEIPT_SCHEMA =
+  "chainlesschain.skill-release-migration-receipt/v1";
+export const SKILL_RELEASE_STATE_MIGRATION_PLAN_SCHEMA =
+  "chainlesschain.skill-release-state-migration-plan/v1";
+export const SKILL_RELEASE_STATE_MIGRATION_AUTHORITY_SCHEMA =
+  "chainlesschain.skill-release-state-migration-authority/v1";
+export const SKILL_RELEASE_STATE_MIGRATION_RECEIPT_SCHEMA =
+  "chainlesschain.skill-release-state-migration-receipt/v1";
+export const SKILL_RELEASE_STATE_LEDGER_MIGRATION_SCHEMA =
+  "chainlesschain.skill-release-state-ledger-migration/v1";
+export const SKILL_RELEASE_STATE_MIGRATION_JOURNAL_SCHEMA =
+  "chainlesschain.skill-release-state-migration-journal/v1";
+export const SKILL_RELEASE_JOURNAL_RESOLUTION_RECEIPT_SCHEMA =
+  "chainlesschain.skill-release-journal-resolution-receipt/v1";
+export const SKILL_RELEASE_JOURNAL_RESOLUTION_AUTHORITY_SCHEMA =
+  "chainlesschain.skill-release-journal-resolution-authority/v1";
+export const SKILL_RELEASE_JOURNAL_DISPOSITION_PLAN_SCHEMA =
+  "chainlesschain.skill-release-journal-disposition-plan/v1";
+export const SKILL_RELEASE_JOURNAL_ARCHIVE_SCHEMA =
+  "chainlesschain.skill-release-journal-archive/v1";
 
 const JOURNAL_SCHEMA = "chainlesschain.skill-release-journal/v4";
 const INTENT_SCHEMA = "chainlesschain.skill-release-transition-intent/v2";
@@ -60,10 +88,19 @@ const TENANT_MARKER_DIGEST_DOMAIN =
 const TENANT_MARKER_COMPONENT = "skill-release-registry";
 const TENANT_MARKER_FILE = "_tenant.json";
 const LEGACY_RELEASE_SCHEMA = "chainlesschain.skill-release/v3";
+const LEGACY_RELEASE_DOMAIN = `${LEGACY_RELEASE_SCHEMA}\0`;
 const LEGACY_STATE_SCHEMA = "chainlesschain.skill-release-state/v2";
+const LEGACY_STATE_DOMAIN = `${LEGACY_STATE_SCHEMA}\0`;
 const LEGACY_JOURNAL_SCHEMA = "chainlesschain.skill-release-journal/v3";
+const LEGACY_JOURNAL_DOMAIN = `${LEGACY_JOURNAL_SCHEMA}\0`;
 const LEGACY_LOCK_OWNER_SCHEMA = "chainlesschain.skill-release-lock-owner/v1";
 const LOCK_OWNER_SCHEMA = "chainlesschain.skill-release-lock-owner/v2";
+const RELEASE_MIGRATION_DOMAIN = `${SKILL_RELEASE_MIGRATION_RECORD_SCHEMA}\0`;
+const STATE_MIGRATION_PLAN_DOMAIN = `${SKILL_RELEASE_STATE_MIGRATION_PLAN_SCHEMA}\0`;
+const JOURNAL_RESOLUTION_RECEIPT_DOMAIN = `${SKILL_RELEASE_JOURNAL_RESOLUTION_RECEIPT_SCHEMA}\0`;
+const JOURNAL_DISPOSITION_PLAN_DOMAIN = `${SKILL_RELEASE_JOURNAL_DISPOSITION_PLAN_SCHEMA}\0`;
+const STATE_MIGRATION_JOURNAL_DOMAIN = `${SKILL_RELEASE_STATE_MIGRATION_JOURNAL_SCHEMA}\0`;
+const JOURNAL_ARCHIVE_DOMAIN = `${SKILL_RELEASE_JOURNAL_ARCHIVE_SCHEMA}\0`;
 
 export const EMPTY_SKILL_ACTIVE_DIGEST = sha256(
   Buffer.from(EMPTY_ACTIVE_DOMAIN, "utf8"),
@@ -426,6 +463,253 @@ const RELEASE_KEYS = new Set([
   "tenantId",
   "transitionSubjectDigest",
 ]);
+const LEGACY_RELEASE_KEYS = new Set([
+  "authorityReceiptDigest",
+  "candidateId",
+  "content",
+  "contentDigest",
+  "dependencyLock",
+  "dependencyLockDigest",
+  "mutationRequestDigest",
+  "parentDigest",
+  "receiptDigests",
+  "releaseDigest",
+  "requestedCapabilities",
+  "schema",
+  "skillName",
+  "targetRuntimes",
+  "transitionSubjectDigest",
+]);
+const RELEASE_MIGRATION_INPUT_KEYS = new Set([
+  "candidateMigration",
+  "legacyRelease",
+]);
+const CANDIDATE_MIGRATION_RESULT_KEYS = new Set([
+  "candidate",
+  "created",
+  "migration",
+  "receipt",
+]);
+const CANDIDATE_MIGRATION_RECORD_KEYS = new Set([
+  "authorityId",
+  "candidateId",
+  "contentDigest",
+  "dependencyLockDigest",
+  "handlerArtifactDigest",
+  "legacyArtifactDigest",
+  "legacyCandidateId",
+  "migrationDigest",
+  "runtimeManifestDigest",
+  "schema",
+  "targetMatrixRoot",
+  "tenantId",
+  "trust",
+]);
+const CANDIDATE_MIGRATION_RECEIPT_KEYS = new Set([
+  "authenticated",
+  "authorityId",
+  "durable",
+  "handlerArtifactDigest",
+  "migrationDigest",
+  "receiptDigest",
+  "schema",
+  "trust",
+]);
+const RELEASE_MIGRATION_AUTHORITY_KEYS = new Set([
+  "audit",
+  "authorityId",
+  "handlerArtifactDigest",
+  "schema",
+  "trust",
+]);
+const RELEASE_MIGRATION_RECEIPT_KEYS = new Set([
+  "authenticated",
+  "authorityId",
+  "durable",
+  "handlerArtifactDigest",
+  "migrationDigest",
+  "receiptDigest",
+  "schema",
+  "trust",
+]);
+const RELEASE_MIGRATION_RECORD_KEYS = new Set([
+  "authorityId",
+  "candidateMigrationDigest",
+  "candidateMigrationReceiptDigest",
+  "handlerArtifactDigest",
+  "legacyCandidateId",
+  "legacyReleaseDigest",
+  "migrationDigest",
+  "releaseDigest",
+  "schema",
+  "skillName",
+  "tenantId",
+  "trust",
+]);
+const RELEASE_MIGRATION_RESULT_KEYS = new Set([
+  "created",
+  "migration",
+  "receipt",
+  "release",
+]);
+const LEGACY_STATE_KEYS = new Set([
+  "activeReleaseDigest",
+  "authorityReceiptDigest",
+  "dependencyLockDigest",
+  "fence",
+  "lastKnownGoodReleaseDigest",
+  "revision",
+  "schema",
+  "skillName",
+  "stateDigest",
+  "transactionId",
+]);
+const LEGACY_JOURNAL_KEYS = new Set([
+  "intent",
+  "journalDigest",
+  "leaseToken",
+  "nextState",
+  "phase",
+  "prepareReceipt",
+  "previousState",
+  "schema",
+  "skillName",
+  "stagedFile",
+  "transactionId",
+]);
+const LEGACY_INTENT_KEYS = new Set([
+  "authorityReceiptDigest",
+  "authorityReceipt",
+  "candidateId",
+  "dependencyLockDigest",
+  "expectedParentDigest",
+  "expectedRevision",
+  "mutationRequest",
+  "intentDigest",
+  "nextStateDigest",
+  "operation",
+  "operationId",
+  "pointerDigest",
+  "previousStateDigest",
+  "receiptDigests",
+  "requestDigest",
+  "schema",
+  "skillName",
+  "targetReleaseDigest",
+  "transactionId",
+  "transitionSubjectDigest",
+]);
+const JOURNAL_RESOLUTION_RECEIPT_KEYS = new Set([
+  "authenticated",
+  "authorityId",
+  "durable",
+  "handlerArtifactDigest",
+  "journalDigest",
+  "ledgerProjection",
+  "receiptDigest",
+  "schema",
+  "tenantId",
+  "transactionId",
+  "trust",
+]);
+const JOURNAL_DISPOSITION_INPUT_KEYS = new Set([
+  "legacyJournal",
+  "resolutionAuthority",
+  "stateMigrationPlan",
+  "tenantId",
+]);
+const JOURNAL_RESOLUTION_AUTHORITY_OPTION_KEYS = new Set([
+  "authorityId",
+  "handlerArtifactDigest",
+  "resolve",
+  "trust",
+]);
+const JOURNAL_DISPOSITION_PLAN_KEYS = new Set([
+  "action",
+  "journalDigest",
+  "ledgerCurrent",
+  "ledgerStatus",
+  "legacyNextStateDigest",
+  "planDigest",
+  "resolutionReceipt",
+  "resolutionReceiptDigest",
+  "schema",
+  "skillName",
+  "stateMigrationDigest",
+  "tenantId",
+  "transactionId",
+]);
+const JOURNAL_ARCHIVE_INPUT_KEYS = new Set([
+  "archiveDir",
+  "crashHook",
+  "dispositionPlan",
+  "fsImpl",
+  "legacyJournal",
+  "secure",
+  "sourcePath",
+  "stateMigrationResult",
+]);
+const JOURNAL_ARCHIVE_KEYS = new Set([
+  "action",
+  "archiveDigest",
+  "dispositionPlan",
+  "legacyJournal",
+  "schema",
+  "stateMigrationStateDigest",
+]);
+const STATE_MIGRATION_PLAN_INPUT_KEYS = new Set([
+  "activeReleaseMigration",
+  "lastKnownGoodReleaseMigration",
+  "legacyState",
+]);
+const STATE_MIGRATION_PLAN_KEYS = new Set([
+  "activeReleaseDigest",
+  "activeReleaseMigrationDigest",
+  "activeReleaseMigrationReceiptDigest",
+  "dependencyLockDigest",
+  "lastKnownGoodReleaseDigest",
+  "lastKnownGoodReleaseMigrationDigest",
+  "lastKnownGoodReleaseMigrationReceiptDigest",
+  "legacyActiveReleaseDigest",
+  "legacyFence",
+  "legacyLastKnownGoodReleaseDigest",
+  "legacyRevision",
+  "legacyStateDigest",
+  "legacyTransactionId",
+  "requiresAuthenticatedLedgerMigration",
+  "schema",
+  "skillName",
+  "stateMigrationDigest",
+  "tenantId",
+]);
+const STATE_MIGRATION_AUTHORITY_KEYS = new Set([
+  "audit",
+  "authorityId",
+  "handlerArtifactDigest",
+  "schema",
+  "trust",
+]);
+const STATE_MIGRATION_RECEIPT_KEYS = new Set([
+  "authenticated",
+  "authorityId",
+  "durable",
+  "handlerArtifactDigest",
+  "receiptDigest",
+  "schema",
+  "stateMigrationDigest",
+  "trust",
+]);
+const STATE_MIGRATION_JOURNAL_KEYS = new Set([
+  "journalDigest",
+  "leaseToken",
+  "plan",
+  "receipt",
+  "schema",
+  "skillName",
+  "state",
+  "tenantId",
+  "transactionId",
+]);
 const BUILD_RELEASE_INPUT_KEYS = new Set([
   "candidate",
   "consumptionReceipt",
@@ -502,10 +786,1327 @@ export function buildSkillRelease(input) {
     tenantId: verifiedCandidate.tenantId,
     transitionSubjectDigest,
   };
-  return deepFreeze({
+  return deepFreeze({
+    ...core,
+    releaseDigest: domainDigest(RELEASE_DOMAIN, core),
+  });
+}
+
+/** Verify the exact pre-tenant v3 release before explicit migration. */
+export function verifyLegacySkillRelease(value) {
+  assertExactKeys(
+    value,
+    LEGACY_RELEASE_KEYS,
+    "legacy release",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  if (
+    value.schema !== LEGACY_RELEASE_SCHEMA ||
+    typeof value.content !== "string"
+  ) {
+    throw migrationRequired("legacy release schema or content is invalid");
+  }
+  const core = {
+    authorityReceiptDigest: digest(
+      value.authorityReceiptDigest,
+      "authorityReceiptDigest",
+    ),
+    candidateId: digest(value.candidateId, "candidateId"),
+    content: value.content,
+    contentDigest: digest(value.contentDigest, "contentDigest"),
+    dependencyLock: normalizeJson(value.dependencyLock, "dependencyLock"),
+    dependencyLockDigest: digest(
+      value.dependencyLockDigest,
+      "dependencyLockDigest",
+    ),
+    mutationRequestDigest: digest(
+      value.mutationRequestDigest,
+      "mutationRequestDigest",
+    ),
+    parentDigest: digest(value.parentDigest, "parentDigest", {
+      nullable: true,
+    }),
+    receiptDigests: normalizeReceiptDigests(value.receiptDigests),
+    requestedCapabilities: normalizeJson(
+      value.requestedCapabilities,
+      "requestedCapabilities",
+    ),
+    schema: LEGACY_RELEASE_SCHEMA,
+    skillName: skillName(value.skillName),
+    targetRuntimes: normalizeJson(value.targetRuntimes, "targetRuntimes"),
+    transitionSubjectDigest: digest(
+      value.transitionSubjectDigest,
+      "transitionSubjectDigest",
+    ),
+  };
+  if (
+    !Array.isArray(core.requestedCapabilities) ||
+    !Array.isArray(core.targetRuntimes) ||
+    sha256(Buffer.from(core.content, "utf8")) !== core.contentDigest ||
+    digestDependencyLock(core.dependencyLock) !== core.dependencyLockDigest ||
+    digest(value.releaseDigest, "releaseDigest") !==
+      domainDigest(LEGACY_RELEASE_DOMAIN, core) ||
+    canonicalJson(value) !==
+      canonicalJson({ ...core, releaseDigest: value.releaseDigest })
+  ) {
+    throw migrationRequired("legacy release bytes or digests are invalid", {
+      legacyReleaseDigest: value.releaseDigest,
+    });
+  }
+  return deepFreeze({ ...core, releaseDigest: value.releaseDigest });
+}
+
+export function buildMigratedSkillRelease(input) {
+  assertExactKeys(
+    input,
+    RELEASE_MIGRATION_INPUT_KEYS,
+    "release migration input",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const legacy = verifyLegacySkillRelease(input.legacyRelease);
+  assertExactKeys(
+    input.candidateMigration,
+    CANDIDATE_MIGRATION_RESULT_KEYS,
+    "candidate migration result",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  if (typeof input.candidateMigration.created !== "boolean") {
+    throw migrationRequired(
+      "candidate migration result created flag is invalid",
+    );
+  }
+  const candidate = verifySkillCandidateDraft(
+    input.candidateMigration.candidate,
+  );
+  const migration = input.candidateMigration.migration;
+  const migrationReceipt = input.candidateMigration.receipt;
+  assertExactKeys(
+    migration,
+    CANDIDATE_MIGRATION_RECORD_KEYS,
+    "candidate migration record",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  assertExactKeys(
+    migrationReceipt,
+    CANDIDATE_MIGRATION_RECEIPT_KEYS,
+    "candidate migration receipt",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const migrationCore = { ...migration };
+  delete migrationCore.migrationDigest;
+  if (
+    migration.schema !== SKILL_CANDIDATE_MIGRATION_RECORD_SCHEMA ||
+    migration.trust !== "trusted" ||
+    migration.migrationDigest !==
+      domainDigest(
+        `${SKILL_CANDIDATE_MIGRATION_RECORD_SCHEMA}\0`,
+        migrationCore,
+      ) ||
+    migrationReceipt.schema !== SKILL_CANDIDATE_MIGRATION_RECEIPT_SCHEMA ||
+    migrationReceipt.authenticated !== true ||
+    migrationReceipt.durable !== true ||
+    migrationReceipt.trust !== "trusted" ||
+    migrationReceipt.migrationDigest !== migration.migrationDigest ||
+    migrationReceipt.authorityId !== migration.authorityId ||
+    migrationReceipt.handlerArtifactDigest !==
+      migration.handlerArtifactDigest ||
+    migration.legacyCandidateId !== legacy.candidateId ||
+    migration.candidateId !== candidate.candidateId ||
+    migration.tenantId !== candidate.tenantId ||
+    migration.contentDigest !== candidate.contentDigest ||
+    migration.dependencyLockDigest !== candidate.dependencyLockDigest ||
+    migration.runtimeManifestDigest !== candidate.runtimeManifestDigest ||
+    migration.targetMatrixRoot !== candidate.targetMatrixRoot ||
+    legacy.skillName !== candidate.skillName ||
+    legacy.parentDigest !== candidate.parentDigest ||
+    legacy.contentDigest !== candidate.contentDigest ||
+    legacy.content !== candidate.content ||
+    legacy.dependencyLockDigest !== candidate.dependencyLock.lockDigest ||
+    canonicalJson(legacy.dependencyLock) !==
+      canonicalJson(candidate.dependencyLock.lock) ||
+    canonicalJson(legacy.requestedCapabilities) !==
+      canonicalJson(candidate.requestedCapabilities) ||
+    canonicalJson(legacy.targetRuntimes) !==
+      canonicalJson(candidate.targetRuntimes)
+  ) {
+    throw migrationRequired(
+      "legacy release is not exactly bound to its audited candidate migration",
+      { legacyReleaseDigest: legacy.releaseDigest },
+    );
+  }
+  const core = {
+    authorityReceiptDigest: legacy.authorityReceiptDigest,
+    candidate,
+    candidateId: candidate.candidateId,
+    contentDigest: candidate.contentDigest,
+    dependencyLock: candidate.dependencyLock,
+    dependencyLockDigest: candidate.dependencyLockDigest,
+    mutationRequestDigest: legacy.mutationRequestDigest,
+    parentDigest: candidate.parentDigest,
+    receiptDigests: legacy.receiptDigests,
+    runtimeManifest: candidate.runtimeManifest,
+    runtimeManifestDigest: candidate.runtimeManifestDigest,
+    schema: SKILL_RELEASE_SCHEMA,
+    skillName: candidate.skillName,
+    targetMatrix: candidate.targetMatrix,
+    targetMatrixRoot: candidate.targetMatrixRoot,
+    targetRuntimes: candidate.targetRuntimes,
+    tenantId: candidate.tenantId,
+    transitionSubjectDigest: legacy.transitionSubjectDigest,
+  };
+  return verifySkillRelease({
+    ...core,
+    releaseDigest: domainDigest(RELEASE_DOMAIN, core),
+  });
+}
+
+export function verifySkillReleaseMigrationResult(value) {
+  assertExactKeys(
+    value,
+    RELEASE_MIGRATION_RESULT_KEYS,
+    "release migration result",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  if (typeof value.created !== "boolean") {
+    throw migrationRequired("release migration created flag is invalid");
+  }
+  const release = verifySkillRelease(value.release);
+  assertExactKeys(
+    value.migration,
+    RELEASE_MIGRATION_RECORD_KEYS,
+    "release migration record",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const migrationCore = {
+    authorityId: boundedString(
+      value.migration.authorityId,
+      "releaseMigration.authorityId",
+      256,
+    ),
+    candidateMigrationDigest: digest(
+      value.migration.candidateMigrationDigest,
+      "releaseMigration.candidateMigrationDigest",
+    ),
+    candidateMigrationReceiptDigest: digest(
+      value.migration.candidateMigrationReceiptDigest,
+      "releaseMigration.candidateMigrationReceiptDigest",
+    ),
+    handlerArtifactDigest: digest(
+      value.migration.handlerArtifactDigest,
+      "releaseMigration.handlerArtifactDigest",
+    ),
+    legacyCandidateId: digest(
+      value.migration.legacyCandidateId,
+      "releaseMigration.legacyCandidateId",
+    ),
+    legacyReleaseDigest: digest(
+      value.migration.legacyReleaseDigest,
+      "releaseMigration.legacyReleaseDigest",
+    ),
+    releaseDigest: digest(
+      value.migration.releaseDigest,
+      "releaseMigration.releaseDigest",
+    ),
+    schema: value.migration.schema,
+    skillName: skillName(value.migration.skillName),
+    tenantId: tenantId(value.migration.tenantId),
+    trust: value.migration.trust,
+  };
+  const migration = deepFreeze({
+    ...migrationCore,
+    migrationDigest: digest(
+      value.migration.migrationDigest,
+      "releaseMigration.migrationDigest",
+    ),
+  });
+  assertExactKeys(
+    value.receipt,
+    RELEASE_MIGRATION_RECEIPT_KEYS,
+    "release migration receipt",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const receipt = deepFreeze({
+    authenticated: value.receipt.authenticated,
+    authorityId: boundedString(
+      value.receipt.authorityId,
+      "releaseMigrationReceipt.authorityId",
+      256,
+    ),
+    durable: value.receipt.durable,
+    handlerArtifactDigest: digest(
+      value.receipt.handlerArtifactDigest,
+      "releaseMigrationReceipt.handlerArtifactDigest",
+    ),
+    migrationDigest: digest(
+      value.receipt.migrationDigest,
+      "releaseMigrationReceipt.migrationDigest",
+    ),
+    receiptDigest: digest(
+      value.receipt.receiptDigest,
+      "releaseMigrationReceipt.receiptDigest",
+    ),
+    schema: value.receipt.schema,
+    trust: value.receipt.trust,
+  });
+  if (
+    migration.schema !== SKILL_RELEASE_MIGRATION_RECORD_SCHEMA ||
+    migration.trust !== "trusted" ||
+    migration.migrationDigest !==
+      domainDigest(RELEASE_MIGRATION_DOMAIN, migrationCore) ||
+    migration.releaseDigest !== release.releaseDigest ||
+    migration.skillName !== release.skillName ||
+    migration.tenantId !== release.tenantId ||
+    receipt.schema !== SKILL_RELEASE_MIGRATION_RECEIPT_SCHEMA ||
+    receipt.authenticated !== true ||
+    receipt.durable !== true ||
+    receipt.trust !== "trusted" ||
+    receipt.authorityId !== migration.authorityId ||
+    receipt.handlerArtifactDigest !== migration.handlerArtifactDigest ||
+    receipt.migrationDigest !== migration.migrationDigest
+  ) {
+    throw migrationRequired(
+      "release migration result is not exactly bound and durable",
+      { legacyReleaseDigest: migration.legacyReleaseDigest },
+    );
+  }
+  return deepFreeze({
+    created: value.created,
+    migration,
+    receipt,
+    release,
+  });
+}
+
+/** Verify the exact pre-tenant v2 active-state pointer. */
+export function verifyLegacySkillReleaseState(value) {
+  assertExactKeys(
+    value,
+    LEGACY_STATE_KEYS,
+    "legacy release state",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  if (value.schema !== LEGACY_STATE_SCHEMA) {
+    throw migrationRequired("legacy release state schema is invalid");
+  }
+  const core = {
+    activeReleaseDigest: digest(
+      value.activeReleaseDigest,
+      "legacyState.activeReleaseDigest",
+    ),
+    authorityReceiptDigest: digest(
+      value.authorityReceiptDigest,
+      "legacyState.authorityReceiptDigest",
+    ),
+    dependencyLockDigest: digest(
+      value.dependencyLockDigest,
+      "legacyState.dependencyLockDigest",
+    ),
+    fence: safeInteger(value.fence, "legacyState.fence", { minimum: 1 }),
+    lastKnownGoodReleaseDigest: digest(
+      value.lastKnownGoodReleaseDigest,
+      "legacyState.lastKnownGoodReleaseDigest",
+    ),
+    revision: safeInteger(value.revision, "legacyState.revision", {
+      minimum: 1,
+    }),
+    schema: LEGACY_STATE_SCHEMA,
+    skillName: skillName(value.skillName),
+    transactionId: digest(value.transactionId, "legacyState.transactionId"),
+  };
+  const state = deepFreeze({
+    ...core,
+    stateDigest: digest(value.stateDigest, "legacyState.stateDigest"),
+  });
+  if (
+    state.stateDigest !== domainDigest(LEGACY_STATE_DOMAIN, core) ||
+    canonicalJson(value) !== canonicalJson(state)
+  ) {
+    throw migrationRequired(
+      "legacy release state bytes or digest are invalid",
+      {
+        legacyStateDigest: value.stateDigest,
+      },
+    );
+  }
+  return state;
+}
+
+function verifyLegacySkillReleaseIntent(value) {
+  assertExactKeys(
+    value,
+    LEGACY_INTENT_KEYS,
+    "legacy release transition intent",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const core = { ...value };
+  delete core.intentDigest;
+  if (
+    core.schema !== INTENT_SCHEMA ||
+    !["promote", "rollback"].includes(core.operation) ||
+    domainDigest(INTENT_DOMAIN, core) !== value.intentDigest
+  ) {
+    throw migrationRequired("legacy journal intent digest is invalid");
+  }
+  for (const field of [
+    "authorityReceiptDigest",
+    "dependencyLockDigest",
+    "expectedParentDigest",
+    "nextStateDigest",
+    "pointerDigest",
+    "requestDigest",
+    "targetReleaseDigest",
+    "transactionId",
+    "transitionSubjectDigest",
+    "intentDigest",
+  ]) {
+    digest(value[field], `legacyIntent.${field}`);
+  }
+  digest(value.previousStateDigest, "legacyIntent.previousStateDigest", {
+    nullable: true,
+  });
+  digest(value.candidateId, "legacyIntent.candidateId", { nullable: true });
+  safeInteger(value.expectedRevision, "legacyIntent.expectedRevision");
+  skillName(value.skillName);
+  boundedString(value.operationId, "legacyIntent.operationId");
+  normalizeReceiptDigests(value.receiptDigests);
+  const authorityReceipt = verifySkillMutationConsumptionReceipt(
+    value.authorityReceipt,
+  );
+  const mutationRequest = verifySkillMutationRequest(value.mutationRequest);
+  if (
+    authorityReceipt.receiptDigest !== value.authorityReceiptDigest ||
+    authorityReceipt.requestDigest !== value.requestDigest ||
+    authorityReceipt.operationId !== value.operationId ||
+    authorityReceipt.operation !== value.operation ||
+    authorityReceipt.transitionSubjectDigest !==
+      value.transitionSubjectDigest ||
+    authorityReceipt.skillName !== value.skillName ||
+    authorityReceipt.expectedTargetDigest !== value.expectedParentDigest ||
+    authorityReceipt.expectedTargetRevision !== value.expectedRevision
+  ) {
+    throw migrationRequired(
+      "legacy journal intent authority bindings are invalid",
+    );
+  }
+  verifyRequestReceiptBinding(mutationRequest, authorityReceipt);
+  const expectedTransitionSubjectDigest = digestSkillMutationTransitionSubject({
+    tenantId: mutationRequest.tenantId,
+    skillName: value.skillName,
+    operation: value.operation,
+    candidateId: value.candidateId,
+    rollbackTargetReleaseDigest:
+      value.operation === SKILL_MUTATION_OPERATIONS.ROLLBACK
+        ? value.targetReleaseDigest
+        : null,
+    dependencyLockDigest: value.dependencyLockDigest,
+    expectedActiveContentDigest: value.expectedParentDigest,
+    expectedActiveRevision: value.expectedRevision,
+  });
+  if (
+    mutationRequest.requestDigest !== value.requestDigest ||
+    mutationRequest.operation !== value.operation ||
+    mutationRequest.transitionSubjectDigest !== value.transitionSubjectDigest ||
+    canonicalJson(receiptDigestsFromRequest(mutationRequest)) !==
+      canonicalJson(value.receiptDigests) ||
+    value.transitionSubjectDigest !== expectedTransitionSubjectDigest ||
+    canonicalJson(value) !==
+      canonicalJson({ ...core, intentDigest: value.intentDigest })
+  ) {
+    throw migrationRequired("legacy journal intent is not exactly bound");
+  }
+  return deepFreeze({ ...value });
+}
+
+/** Verify the exact pre-tenant v3 crash-recovery journal without recovering it. */
+export function verifyLegacySkillReleaseJournal(value) {
+  assertExactKeys(
+    value,
+    LEGACY_JOURNAL_KEYS,
+    "legacy release journal",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const core = { ...value };
+  delete core.journalDigest;
+  if (
+    core.schema !== LEGACY_JOURNAL_SCHEMA ||
+    !["journaled", "prepared", "pointer-written"].includes(core.phase) ||
+    typeof core.leaseToken !== "string" ||
+    !TOKEN_PATTERN.test(core.leaseToken) ||
+    typeof core.stagedFile !== "string" ||
+    !TEMP_PATTERN.test(core.stagedFile) ||
+    domainDigest(LEGACY_JOURNAL_DOMAIN, core) !== value.journalDigest
+  ) {
+    throw migrationRequired("legacy release journal digest is invalid");
+  }
+  const intent = verifyLegacySkillReleaseIntent(core.intent);
+  const nextState = verifyLegacySkillReleaseState(core.nextState);
+  const previousState =
+    core.previousState === null
+      ? null
+      : verifyLegacySkillReleaseState(core.previousState);
+  if (
+    intent.transactionId !== core.transactionId ||
+    nextState.transactionId !== core.transactionId ||
+    nextState.skillName !== core.skillName ||
+    intent.skillName !== core.skillName ||
+    nextState.stateDigest !== intent.nextStateDigest ||
+    nextState.stateDigest !== intent.pointerDigest ||
+    nextState.activeReleaseDigest !== intent.targetReleaseDigest ||
+    nextState.authorityReceiptDigest !== intent.authorityReceiptDigest ||
+    nextState.dependencyLockDigest !== intent.dependencyLockDigest ||
+    nextState.revision !== intent.expectedRevision + 1 ||
+    (previousState === null
+      ? intent.previousStateDigest !== null || intent.expectedRevision !== 0
+      : previousState.skillName !== core.skillName ||
+        previousState.stateDigest !== intent.previousStateDigest ||
+        previousState.revision !== intent.expectedRevision)
+  ) {
+    throw migrationRequired(
+      "legacy release journal transition bindings are invalid",
+    );
+  }
+  if (core.prepareReceipt !== null) {
+    const prepared = verifyLedgerProjection(core.prepareReceipt, {
+      authorityReceiptDigest: intent.authorityReceiptDigest,
+      intentDigest: intent.intentDigest,
+      transactionId: intent.transactionId,
+    });
+    if (prepared.status !== "prepared") {
+      throw migrationRequired(
+        "legacy journal prepare receipt has the wrong status",
+      );
+    }
+  } else if (core.phase !== "journaled") {
+    throw migrationRequired(
+      "legacy prepared journal is missing its projection",
+    );
+  }
+  const journal = deepFreeze({
+    ...core,
+    intent,
+    journalDigest: value.journalDigest,
+    nextState,
+    previousState,
+  });
+  if (canonicalJson(journal) !== canonicalJson(value)) {
+    throw migrationRequired("legacy release journal is not canonical");
+  }
+  return journal;
+}
+
+const journalResolutionAuthorities = new WeakMap();
+const completedStateMigrations = new WeakSet();
+
+function completedStateMigration(value) {
+  const result = deepFreeze(value);
+  completedStateMigrations.add(result);
+  return result;
+}
+
+export function createSkillReleaseJournalResolutionAuthority(options) {
+  assertExactKeys(
+    options,
+    JOURNAL_RESOLUTION_AUTHORITY_OPTION_KEYS,
+    "legacy journal resolution authority options",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  if (options.trust !== "trusted" || typeof options.resolve !== "function") {
+    throw migrationRequired("legacy journal resolution authority is invalid");
+  }
+  const descriptor = Object.freeze({
+    authorityId: boundedString(
+      options.authorityId,
+      "journalResolutionAuthority.authorityId",
+      256,
+    ),
+    handlerArtifactDigest: digest(
+      options.handlerArtifactDigest,
+      "journalResolutionAuthority.handlerArtifactDigest",
+    ),
+    schema: SKILL_RELEASE_JOURNAL_RESOLUTION_AUTHORITY_SCHEMA,
+    trust: "trusted",
+  });
+  journalResolutionAuthorities.set(descriptor, options.resolve);
+  return descriptor;
+}
+
+function verifyLegacyJournalResolutionReceipt(
+  value,
+  journal,
+  ownerTenantId,
+  authority,
+) {
+  assertExactKeys(
+    value,
+    JOURNAL_RESOLUTION_RECEIPT_KEYS,
+    "legacy journal resolution receipt",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const projection = verifyLedgerProjection(value.ledgerProjection, {
+    authorityReceiptDigest: journal.intent.authorityReceiptDigest,
+    intentDigest: journal.intent.intentDigest,
+    pointerDigest: journal.nextState.stateDigest,
+    prepareReceiptDigest: journal.prepareReceipt?.receiptDigest,
+    revision: journal.nextState.revision,
+    skillName: journal.skillName,
+    stateDigest: journal.nextState.stateDigest,
+    transactionId: journal.transactionId,
+  });
+  if (
+    projection.status === "prepared" &&
+    journal.prepareReceipt !== null &&
+    canonicalJson(projection) !== canonicalJson(journal.prepareReceipt)
+  ) {
+    throw migrationRequired(
+      "legacy journal resolution differs from its stored prepare projection",
+    );
+  }
+  const core = {
+    authenticated: value.authenticated,
+    authorityId: boundedString(
+      value.authorityId,
+      "journalResolution.authorityId",
+      256,
+    ),
+    durable: value.durable,
+    handlerArtifactDigest: digest(
+      value.handlerArtifactDigest,
+      "journalResolution.handlerArtifactDigest",
+    ),
+    journalDigest: digest(
+      value.journalDigest,
+      "journalResolution.journalDigest",
+    ),
+    ledgerProjection: projection,
+    schema: value.schema,
+    tenantId: tenantId(value.tenantId, "journalResolution.tenantId"),
+    transactionId: digest(
+      value.transactionId,
+      "journalResolution.transactionId",
+    ),
+    trust: value.trust,
+  };
+  const receipt = deepFreeze({
+    ...core,
+    receiptDigest: digest(
+      value.receiptDigest,
+      "journalResolution.receiptDigest",
+    ),
+  });
+  if (
+    receipt.schema !== SKILL_RELEASE_JOURNAL_RESOLUTION_RECEIPT_SCHEMA ||
+    receipt.authenticated !== true ||
+    receipt.durable !== true ||
+    receipt.trust !== "trusted" ||
+    receipt.authorityId !== authority.authorityId ||
+    receipt.handlerArtifactDigest !== authority.handlerArtifactDigest ||
+    receipt.tenantId !== ownerTenantId ||
+    receipt.journalDigest !== journal.journalDigest ||
+    receipt.transactionId !== journal.transactionId ||
+    receipt.receiptDigest !==
+      domainDigest(JOURNAL_RESOLUTION_RECEIPT_DOMAIN, core) ||
+    canonicalJson(receipt) !== canonicalJson(value)
+  ) {
+    throw migrationRequired(
+      "legacy journal resolution receipt is not exactly bound and durable",
+    );
+  }
+  return receipt;
+}
+
+export function buildLegacySkillReleaseJournalDisposition(input) {
+  assertExactKeys(
+    input,
+    JOURNAL_DISPOSITION_INPUT_KEYS,
+    "legacy journal disposition input",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const journal = verifyLegacySkillReleaseJournal(input.legacyJournal);
+  const ownerTenantId = tenantId(input.tenantId, "journalDisposition.tenantId");
+  if (journal.intent.mutationRequest.tenantId !== ownerTenantId) {
+    throw migrationRequired(
+      "legacy journal mutation authority belongs to another tenant",
+    );
+  }
+  const resolver = journalResolutionAuthorities.get(input.resolutionAuthority);
+  if (!resolver) {
+    throw migrationRequired(
+      "legacy journal disposition requires a branded resolution authority",
+    );
+  }
+  let rawReceipt;
+  try {
+    rawReceipt = resolver(
+      deepFreeze({
+        journalDigest: journal.journalDigest,
+        skillName: journal.skillName,
+        tenantId: ownerTenantId,
+        transactionId: journal.transactionId,
+      }),
+    );
+  } catch (cause) {
+    throw failure(
+      "SKILL_RELEASE_JOURNAL_RESOLUTION_FAILED",
+      "legacy journal resolution authority failed closed",
+      { cause, journalDigest: journal.journalDigest },
+    );
+  }
+  if (utilTypes.isPromise(rawReceipt)) {
+    throw failure(
+      "SKILL_RELEASE_JOURNAL_RESOLUTION_FAILED",
+      "legacy journal resolution authority must be synchronous",
+    );
+  }
+  const receipt = verifyLegacyJournalResolutionReceipt(
+    rawReceipt,
+    journal,
+    ownerTenantId,
+    input.resolutionAuthority,
+  );
+  const projection = receipt.ledgerProjection;
+  const action =
+    projection.status === "absent"
+      ? "abort"
+      : projection.status === "committed" && projection.current === true
+        ? "migrate-committed-state"
+        : "quarantine";
+  let stateMigrationPlan = null;
+  if (action === "migrate-committed-state") {
+    stateMigrationPlan = verifySkillReleaseStateMigrationPlan(
+      input.stateMigrationPlan,
+    );
+    if (
+      stateMigrationPlan.tenantId !== ownerTenantId ||
+      stateMigrationPlan.skillName !== journal.skillName ||
+      stateMigrationPlan.legacyStateDigest !== journal.nextState.stateDigest ||
+      stateMigrationPlan.legacyTransactionId !== journal.transactionId ||
+      stateMigrationPlan.legacyRevision !== journal.nextState.revision ||
+      stateMigrationPlan.legacyFence !== journal.nextState.fence ||
+      stateMigrationPlan.legacyActiveReleaseDigest !==
+        journal.nextState.activeReleaseDigest ||
+      stateMigrationPlan.legacyLastKnownGoodReleaseDigest !==
+        journal.nextState.lastKnownGoodReleaseDigest
+    ) {
+      throw migrationRequired(
+        "committed legacy journal is not bound to its state migration plan",
+      );
+    }
+  } else if (input.stateMigrationPlan !== null) {
+    throw migrationRequired(
+      "non-committed legacy journal disposition must not carry a state migration plan",
+    );
+  }
+  const core = {
+    action,
+    journalDigest: journal.journalDigest,
+    ledgerCurrent:
+      projection.status === "committed" ? projection.current : null,
+    ledgerStatus: projection.status,
+    legacyNextStateDigest: journal.nextState.stateDigest,
+    resolutionReceipt: receipt,
+    resolutionReceiptDigest: receipt.receiptDigest,
+    schema: SKILL_RELEASE_JOURNAL_DISPOSITION_PLAN_SCHEMA,
+    skillName: journal.skillName,
+    stateMigrationDigest: stateMigrationPlan?.stateMigrationDigest ?? null,
+    tenantId: ownerTenantId,
+    transactionId: journal.transactionId,
+  };
+  return deepFreeze({
+    ...core,
+    planDigest: domainDigest(JOURNAL_DISPOSITION_PLAN_DOMAIN, core),
+  });
+}
+
+export function verifyLegacySkillReleaseJournalDisposition(value) {
+  assertExactKeys(
+    value,
+    JOURNAL_DISPOSITION_PLAN_KEYS,
+    "legacy journal disposition plan",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  assertExactKeys(
+    value.resolutionReceipt,
+    JOURNAL_RESOLUTION_RECEIPT_KEYS,
+    "journal disposition resolution receipt",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const resolutionCore = { ...value.resolutionReceipt };
+  delete resolutionCore.receiptDigest;
+  const resolutionReceipt = deepFreeze({
+    ...resolutionCore,
+    receiptDigest: digest(
+      value.resolutionReceipt.receiptDigest,
+      "journalDisposition.resolutionReceipt.receiptDigest",
+    ),
+  });
+  boundedString(
+    resolutionReceipt.authorityId,
+    "journalDisposition.resolutionReceipt.authorityId",
+    256,
+  );
+  digest(
+    resolutionReceipt.handlerArtifactDigest,
+    "journalDisposition.resolutionReceipt.handlerArtifactDigest",
+  );
+  digest(
+    resolutionReceipt.journalDigest,
+    "journalDisposition.resolutionReceipt.journalDigest",
+  );
+  tenantId(
+    resolutionReceipt.tenantId,
+    "journalDisposition.resolutionReceipt.tenantId",
+  );
+  digest(
+    resolutionReceipt.transactionId,
+    "journalDisposition.resolutionReceipt.transactionId",
+  );
+  if (
+    resolutionReceipt.schema !==
+      SKILL_RELEASE_JOURNAL_RESOLUTION_RECEIPT_SCHEMA ||
+    resolutionReceipt.authenticated !== true ||
+    resolutionReceipt.durable !== true ||
+    resolutionReceipt.trust !== "trusted" ||
+    !isPlainObject(resolutionReceipt.ledgerProjection) ||
+    resolutionReceipt.receiptDigest !==
+      domainDigest(JOURNAL_RESOLUTION_RECEIPT_DOMAIN, resolutionCore)
+  ) {
+    throw migrationRequired(
+      "journal disposition resolution receipt is invalid",
+    );
+  }
+  const core = {
+    action: value.action,
+    journalDigest: digest(
+      value.journalDigest,
+      "journalDisposition.journalDigest",
+    ),
+    ledgerCurrent: value.ledgerCurrent,
+    ledgerStatus: value.ledgerStatus,
+    legacyNextStateDigest: digest(
+      value.legacyNextStateDigest,
+      "journalDisposition.legacyNextStateDigest",
+    ),
+    resolutionReceipt,
+    resolutionReceiptDigest: digest(
+      value.resolutionReceiptDigest,
+      "journalDisposition.resolutionReceiptDigest",
+    ),
+    schema: value.schema,
+    skillName: skillName(value.skillName),
+    stateMigrationDigest: digest(
+      value.stateMigrationDigest,
+      "journalDisposition.stateMigrationDigest",
+      { nullable: true },
+    ),
+    tenantId: tenantId(value.tenantId, "journalDisposition.tenantId"),
+    transactionId: digest(
+      value.transactionId,
+      "journalDisposition.transactionId",
+    ),
+  };
+  const plan = deepFreeze({
+    ...core,
+    planDigest: digest(value.planDigest, "journalDisposition.planDigest"),
+  });
+  const shapeValid =
+    (plan.action === "abort" &&
+      plan.ledgerStatus === "absent" &&
+      plan.ledgerCurrent === null &&
+      plan.stateMigrationDigest === null) ||
+    (plan.action === "migrate-committed-state" &&
+      plan.ledgerStatus === "committed" &&
+      plan.ledgerCurrent === true &&
+      plan.stateMigrationDigest !== null) ||
+    (plan.action === "quarantine" &&
+      ((plan.ledgerStatus === "prepared" && plan.ledgerCurrent === null) ||
+        (plan.ledgerStatus === "committed" && plan.ledgerCurrent === false)) &&
+      plan.stateMigrationDigest === null);
+  if (
+    plan.schema !== SKILL_RELEASE_JOURNAL_DISPOSITION_PLAN_SCHEMA ||
+    !shapeValid ||
+    resolutionReceipt.receiptDigest !== plan.resolutionReceiptDigest ||
+    resolutionReceipt.journalDigest !== plan.journalDigest ||
+    resolutionReceipt.transactionId !== plan.transactionId ||
+    resolutionReceipt.tenantId !== plan.tenantId ||
+    resolutionReceipt.ledgerProjection.status !== plan.ledgerStatus ||
+    (plan.ledgerStatus === "committed"
+      ? resolutionReceipt.ledgerProjection.current !== plan.ledgerCurrent
+      : plan.ledgerCurrent !== null) ||
+    plan.planDigest !== domainDigest(JOURNAL_DISPOSITION_PLAN_DOMAIN, core) ||
+    canonicalJson(plan) !== canonicalJson(value)
+  ) {
+    throw migrationRequired("legacy journal disposition plan is invalid");
+  }
+  return plan;
+}
+
+function verifyCompletedStateMigration(result, disposition) {
+  if (!completedStateMigrations.has(result)) {
+    throw migrationRequired(
+      "committed journal retirement requires a branded completed state migration",
+    );
+  }
+  const plan = verifySkillReleaseStateMigrationPlan(result.plan);
+  const state = verifySkillReleaseState(result.state);
+  if (
+    typeof result.created !== "boolean" ||
+    result.receipt?.schema !== SKILL_RELEASE_STATE_MIGRATION_RECEIPT_SCHEMA ||
+    result.receipt.authenticated !== true ||
+    result.receipt.durable !== true ||
+    result.receipt.trust !== "trusted" ||
+    result.receipt.stateMigrationDigest !== plan.stateMigrationDigest ||
+    disposition.stateMigrationDigest !== plan.stateMigrationDigest ||
+    state.transactionId !== plan.stateMigrationDigest ||
+    state.tenantId !== disposition.tenantId ||
+    state.skillName !== disposition.skillName ||
+    state.revision !== plan.legacyRevision ||
+    state.fence !== plan.legacyFence ||
+    state.activeReleaseDigest !== plan.activeReleaseDigest ||
+    state.lastKnownGoodReleaseDigest !== plan.lastKnownGoodReleaseDigest ||
+    state.dependencyLockDigest !== plan.dependencyLockDigest
+  ) {
+    throw migrationRequired(
+      "completed state migration differs from the journal disposition",
+    );
+  }
+  return result;
+}
+
+export function verifySkillReleaseJournalArchive(value) {
+  assertExactKeys(
+    value,
+    JOURNAL_ARCHIVE_KEYS,
+    "legacy journal archive",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const journal = verifyLegacySkillReleaseJournal(value.legacyJournal);
+  const disposition = verifyLegacySkillReleaseJournalDisposition(
+    value.dispositionPlan,
+  );
+  verifyLegacyJournalResolutionReceipt(
+    disposition.resolutionReceipt,
+    journal,
+    disposition.tenantId,
+    {
+      authorityId: disposition.resolutionReceipt.authorityId,
+      handlerArtifactDigest:
+        disposition.resolutionReceipt.handlerArtifactDigest,
+    },
+  );
+  const core = {
+    action: value.action,
+    dispositionPlan: disposition,
+    legacyJournal: journal,
+    schema: value.schema,
+    stateMigrationStateDigest: digest(
+      value.stateMigrationStateDigest,
+      "journalArchive.stateMigrationStateDigest",
+      { nullable: true },
+    ),
+  };
+  const archive = deepFreeze({
+    ...core,
+    archiveDigest: digest(value.archiveDigest, "journalArchive.archiveDigest"),
+  });
+  if (
+    archive.schema !== SKILL_RELEASE_JOURNAL_ARCHIVE_SCHEMA ||
+    archive.action !== disposition.action ||
+    disposition.journalDigest !== journal.journalDigest ||
+    disposition.transactionId !== journal.transactionId ||
+    disposition.skillName !== journal.skillName ||
+    (archive.action === "migrate-committed-state") !==
+      (archive.stateMigrationStateDigest !== null) ||
+    archive.archiveDigest !== domainDigest(JOURNAL_ARCHIVE_DOMAIN, core) ||
+    canonicalJson(archive) !== canonicalJson(value)
+  ) {
+    throw migrationRequired("legacy journal archive is invalid");
+  }
+  return archive;
+}
+
+export function archiveLegacySkillReleaseJournal(input) {
+  assertExactKeys(
+    input,
+    JOURNAL_ARCHIVE_INPUT_KEYS,
+    "legacy journal archive input",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const journal = verifyLegacySkillReleaseJournal(input.legacyJournal);
+  const fsImpl = input.fsImpl;
+  const crashHook = input.crashHook;
+  if (
+    !fsImpl ||
+    typeof fsImpl !== "object" ||
+    utilTypes.isProxy(fsImpl) ||
+    (crashHook !== null && typeof crashHook !== "function")
+  ) {
+    throw migrationRequired("legacy journal archive runtime is invalid");
+  }
+  const checkpoint = (phase, details) => {
+    if (crashHook === null) return;
+    const result = crashHook(phase, deepFreeze({ ...details }));
+    if (utilTypes.isPromise(result)) {
+      throw migrationRequired(
+        "legacy journal archive crash hook must be synchronous",
+      );
+    }
+  };
+  if (input.secure !== true && input.secure !== false) {
+    throw migrationRequired("legacy journal archive secure mode is invalid");
+  }
+  const disposition = verifyLegacySkillReleaseJournalDisposition(
+    input.dispositionPlan,
+  );
+  if (
+    disposition.journalDigest !== journal.journalDigest ||
+    disposition.transactionId !== journal.transactionId ||
+    disposition.skillName !== journal.skillName
+  ) {
+    throw migrationRequired(
+      "legacy journal differs from its authenticated disposition",
+    );
+  }
+  let stateMigrationStateDigest = null;
+  if (disposition.action === "migrate-committed-state") {
+    const migration = verifyCompletedStateMigration(
+      input.stateMigrationResult,
+      disposition,
+    );
+    stateMigrationStateDigest = migration.state.stateDigest;
+  } else if (input.stateMigrationResult !== null) {
+    throw migrationRequired(
+      "abort and quarantine retirement must not carry state migration proof",
+    );
+  }
+  const archiveCore = {
+    action: disposition.action,
+    dispositionPlan: disposition,
+    legacyJournal: journal,
+    schema: SKILL_RELEASE_JOURNAL_ARCHIVE_SCHEMA,
+    stateMigrationStateDigest,
+  };
+  const archive = deepFreeze({
+    ...archiveCore,
+    archiveDigest: domainDigest(JOURNAL_ARCHIVE_DOMAIN, archiveCore),
+  });
+  const requestedSourcePath = path.resolve(
+    boundedString(input.sourcePath, "journalArchive.sourcePath", 4096),
+  );
+  const requestedSourceDirectory = path.dirname(requestedSourcePath);
+  const requestedArchiveDirectory = path.resolve(
+    boundedString(input.archiveDir, "journalArchive.archiveDir", 4096),
+  );
+  if (
+    path.basename(requestedSourcePath) !== `${journal.skillName}.json` ||
+    path.basename(requestedSourceDirectory) !== "journals"
+  ) {
+    throw migrationRequired("legacy journal archive paths are invalid");
+  }
+  const canonicalDirectories = [
+    requestedSourceDirectory,
+    requestedArchiveDirectory,
+  ].map((directory) => {
+    const requestedStat = fsImpl.lstatSync(directory);
+    const canonical = realpath(fsImpl, directory);
+    const canonicalStat = fsImpl.lstatSync(canonical);
+    const canonicalParent = realpath(fsImpl, path.dirname(directory));
+    const expectedCanonical = path.join(
+      canonicalParent,
+      path.basename(directory),
+    );
+    if (
+      !requestedStat.isDirectory() ||
+      requestedStat.isSymbolicLink() ||
+      !canonicalStat.isDirectory() ||
+      canonicalStat.isSymbolicLink() ||
+      identity(canonicalStat) !== identity(requestedStat) ||
+      !samePath(canonical, expectedCanonical) ||
+      !samePath(realpath(fsImpl, canonical), canonical)
+    ) {
+      throw migrationRequired("legacy journal archive directory is unsafe");
+    }
+    return canonical;
+  });
+  const [sourceDirectory, archiveDirectory] = canonicalDirectories;
+  if (
+    samePath(sourceDirectory, archiveDirectory) ||
+    isContained(sourceDirectory, archiveDirectory) ||
+    isContained(archiveDirectory, sourceDirectory)
+  ) {
+    throw migrationRequired("legacy journal archive paths are invalid");
+  }
+  const sourcePath = path.join(
+    sourceDirectory,
+    path.basename(requestedSourcePath),
+  );
+  if (input.secure) {
+    ensurePrivateDirectory(archiveDirectory, {
+      applyWindowsAcl: true,
+      failIfUnavailable: true,
+    });
+  }
+  const archivePath = path.join(
+    archiveDirectory,
+    `${disposition.planDigest.slice("sha256:".length)}.json`,
+  );
+  const expectedBytes = serialize(archive);
+  let created = false;
+  if (lstatOrNull(fsImpl, archivePath) === null) {
+    const source = readBoundedSingleLinkFile(
+      fsImpl,
+      sourcePath,
+      MAX_FILE_BYTES,
+      SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+      "legacy release journal source",
+    );
+    if (!source.bytes.equals(serialize(journal))) {
+      throw migrationRequired(
+        "legacy release journal source bytes differ from the verified input",
+      );
+    }
+    const temporaryPath = path.join(
+      archiveDirectory,
+      `.journal-${process.pid}-${crypto.randomBytes(16).toString("hex")}.tmp`,
+    );
+    let descriptor = null;
+    try {
+      descriptor = fsImpl.openSync(temporaryPath, "wx", 0o600);
+      fsImpl.writeFileSync(descriptor, expectedBytes);
+      fsImpl.fsyncSync(descriptor);
+      fsImpl.closeSync(descriptor);
+      descriptor = null;
+      if (input.secure) {
+        ensurePrivateFile(temporaryPath, {
+          applyWindowsAcl: true,
+          failIfUnavailable: true,
+        });
+      }
+      const staged = readBoundedSingleLinkFile(
+        fsImpl,
+        temporaryPath,
+        MAX_FILE_BYTES,
+        SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+        "legacy journal archive temporary",
+      );
+      if (!staged.bytes.equals(expectedBytes)) {
+        throw migrationRequired("legacy journal archive write was incomplete");
+      }
+      checkpoint("after-archive-fsync", {
+        archiveDigest: archive.archiveDigest,
+        dispositionPlanDigest: disposition.planDigest,
+      });
+      try {
+        fsImpl.linkSync(temporaryPath, archivePath);
+        created = true;
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+      }
+      fsImpl.unlinkSync(temporaryPath);
+      fsyncDirectory(fsImpl, archiveDirectory);
+      checkpoint("after-archive-publish", {
+        archiveDigest: archive.archiveDigest,
+        dispositionPlanDigest: disposition.planDigest,
+      });
+    } finally {
+      if (descriptor !== null) fsImpl.closeSync(descriptor);
+      if (lstatOrNull(fsImpl, temporaryPath) !== null)
+        fsImpl.unlinkSync(temporaryPath);
+    }
+  }
+  const persisted = readBoundedSingleLinkFile(
+    fsImpl,
+    archivePath,
+    MAX_FILE_BYTES,
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+    "legacy journal archive",
+  );
+  if (
+    !persisted.bytes.equals(expectedBytes) ||
+    canonicalJson(
+      verifySkillReleaseJournalArchive(
+        JSON.parse(
+          new TextDecoder("utf-8", { fatal: true }).decode(persisted.bytes),
+        ),
+      ),
+    ) !== canonicalJson(archive)
+  ) {
+    throw migrationRequired("legacy journal archive readback differs");
+  }
+  checkpoint("after-archive-readback", {
+    archiveDigest: archive.archiveDigest,
+    dispositionPlanDigest: disposition.planDigest,
+  });
+  if (lstatOrNull(fsImpl, sourcePath) !== null) {
+    const source = readBoundedSingleLinkFile(
+      fsImpl,
+      sourcePath,
+      MAX_FILE_BYTES,
+      SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+      "legacy release journal source",
+    );
+    if (!source.bytes.equals(serialize(journal))) {
+      throw migrationRequired(
+        "legacy release journal changed before retirement",
+      );
+    }
+    fsImpl.unlinkSync(sourcePath);
+    fsyncDirectory(fsImpl, sourceDirectory);
+    checkpoint("after-source-retire", {
+      archiveDigest: archive.archiveDigest,
+      dispositionPlanDigest: disposition.planDigest,
+    });
+  }
+  return deepFreeze({ archive, archivePath, created, sourceRetired: true });
+}
+
+/**
+ * Build the immutable input for a future authenticated ledger migration.
+ * This never writes an active pointer: only a ledger adapter that can retain
+ * this exact plan and return an authenticated current projection may do so.
+ */
+export function buildSkillReleaseStateMigrationPlan(input) {
+  assertExactKeys(
+    input,
+    STATE_MIGRATION_PLAN_INPUT_KEYS,
+    "release state migration plan input",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const legacyState = verifyLegacySkillReleaseState(input.legacyState);
+  const active = verifySkillReleaseMigrationResult(
+    input.activeReleaseMigration,
+  );
+  const lastKnownGood = verifySkillReleaseMigrationResult(
+    input.lastKnownGoodReleaseMigration,
+  );
+  if (
+    active.migration.legacyReleaseDigest !== legacyState.activeReleaseDigest ||
+    lastKnownGood.migration.legacyReleaseDigest !==
+      legacyState.lastKnownGoodReleaseDigest ||
+    active.release.skillName !== legacyState.skillName ||
+    lastKnownGood.release.skillName !== legacyState.skillName ||
+    active.release.tenantId !== lastKnownGood.release.tenantId ||
+    active.release.authorityReceiptDigest !==
+      legacyState.authorityReceiptDigest ||
+    active.release.dependencyLock.lockDigest !==
+      legacyState.dependencyLockDigest
+  ) {
+    throw migrationRequired(
+      "legacy state is not exactly bound to its migrated releases",
+      { legacyStateDigest: legacyState.stateDigest },
+    );
+  }
+  const core = {
+    activeReleaseDigest: active.release.releaseDigest,
+    activeReleaseMigrationDigest: active.migration.migrationDigest,
+    activeReleaseMigrationReceiptDigest: active.receipt.receiptDigest,
+    dependencyLockDigest: active.release.dependencyLockDigest,
+    lastKnownGoodReleaseDigest: lastKnownGood.release.releaseDigest,
+    lastKnownGoodReleaseMigrationDigest:
+      lastKnownGood.migration.migrationDigest,
+    lastKnownGoodReleaseMigrationReceiptDigest:
+      lastKnownGood.receipt.receiptDigest,
+    legacyActiveReleaseDigest: legacyState.activeReleaseDigest,
+    legacyFence: legacyState.fence,
+    legacyLastKnownGoodReleaseDigest: legacyState.lastKnownGoodReleaseDigest,
+    legacyRevision: legacyState.revision,
+    legacyStateDigest: legacyState.stateDigest,
+    legacyTransactionId: legacyState.transactionId,
+    requiresAuthenticatedLedgerMigration: true,
+    schema: SKILL_RELEASE_STATE_MIGRATION_PLAN_SCHEMA,
+    skillName: legacyState.skillName,
+    tenantId: active.release.tenantId,
+  };
+  return deepFreeze({
+    ...core,
+    stateMigrationDigest: domainDigest(STATE_MIGRATION_PLAN_DOMAIN, core),
+  });
+}
+
+export function verifySkillReleaseStateMigrationPlan(value) {
+  assertExactKeys(
+    value,
+    STATE_MIGRATION_PLAN_KEYS,
+    "release state migration plan",
+    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+  );
+  const core = {
+    activeReleaseDigest: digest(
+      value.activeReleaseDigest,
+      "stateMigration.activeReleaseDigest",
+    ),
+    activeReleaseMigrationDigest: digest(
+      value.activeReleaseMigrationDigest,
+      "stateMigration.activeReleaseMigrationDigest",
+    ),
+    activeReleaseMigrationReceiptDigest: digest(
+      value.activeReleaseMigrationReceiptDigest,
+      "stateMigration.activeReleaseMigrationReceiptDigest",
+    ),
+    dependencyLockDigest: digest(
+      value.dependencyLockDigest,
+      "stateMigration.dependencyLockDigest",
+    ),
+    lastKnownGoodReleaseDigest: digest(
+      value.lastKnownGoodReleaseDigest,
+      "stateMigration.lastKnownGoodReleaseDigest",
+    ),
+    lastKnownGoodReleaseMigrationDigest: digest(
+      value.lastKnownGoodReleaseMigrationDigest,
+      "stateMigration.lastKnownGoodReleaseMigrationDigest",
+    ),
+    lastKnownGoodReleaseMigrationReceiptDigest: digest(
+      value.lastKnownGoodReleaseMigrationReceiptDigest,
+      "stateMigration.lastKnownGoodReleaseMigrationReceiptDigest",
+    ),
+    legacyActiveReleaseDigest: digest(
+      value.legacyActiveReleaseDigest,
+      "stateMigration.legacyActiveReleaseDigest",
+    ),
+    legacyFence: safeInteger(value.legacyFence, "stateMigration.legacyFence", {
+      minimum: 1,
+    }),
+    legacyLastKnownGoodReleaseDigest: digest(
+      value.legacyLastKnownGoodReleaseDigest,
+      "stateMigration.legacyLastKnownGoodReleaseDigest",
+    ),
+    legacyRevision: safeInteger(
+      value.legacyRevision,
+      "stateMigration.legacyRevision",
+      { minimum: 1 },
+    ),
+    legacyStateDigest: digest(
+      value.legacyStateDigest,
+      "stateMigration.legacyStateDigest",
+    ),
+    legacyTransactionId: digest(
+      value.legacyTransactionId,
+      "stateMigration.legacyTransactionId",
+    ),
+    requiresAuthenticatedLedgerMigration:
+      value.requiresAuthenticatedLedgerMigration,
+    schema: value.schema,
+    skillName: skillName(value.skillName),
+    tenantId: tenantId(value.tenantId),
+  };
+  const plan = deepFreeze({
     ...core,
-    releaseDigest: domainDigest(RELEASE_DOMAIN, core),
+    stateMigrationDigest: digest(
+      value.stateMigrationDigest,
+      "stateMigration.stateMigrationDigest",
+    ),
   });
+  if (
+    plan.schema !== SKILL_RELEASE_STATE_MIGRATION_PLAN_SCHEMA ||
+    plan.requiresAuthenticatedLedgerMigration !== true ||
+    plan.stateMigrationDigest !==
+      domainDigest(STATE_MIGRATION_PLAN_DOMAIN, core) ||
+    canonicalJson(plan) !== canonicalJson(value)
+  ) {
+    throw migrationRequired("release state migration plan is invalid", {
+      stateMigrationDigest: value.stateMigrationDigest,
+    });
+  }
+  return plan;
 }
 
 export function verifySkillRelease(value) {
@@ -635,7 +2236,7 @@ function initialState(name, ownerTenantId) {
   });
 }
 
-function verifyState(value) {
+export function verifySkillReleaseState(value) {
   if (
     value &&
     typeof value === "object" &&
@@ -1055,6 +2656,8 @@ export class SkillReleaseRegistry {
 
   #ledgerFinalize;
 
+  #ledgerMigrate;
+
   #ledgerQuery;
 
   #pins = new WeakMap();
@@ -1106,6 +2709,10 @@ export class SkillReleaseRegistry {
     this.#crashHook = crashHook;
     this.#ledgerPrepare = transactionLedger.prepare.bind(transactionLedger);
     this.#ledgerFinalize = transactionLedger.finalize.bind(transactionLedger);
+    this.#ledgerMigrate =
+      typeof transactionLedger.migrate === "function"
+        ? transactionLedger.migrate.bind(transactionLedger)
+        : null;
     this.#ledgerQuery = transactionLedger.query.bind(transactionLedger);
     Object.freeze(transactionLedger);
 
@@ -1137,6 +2744,7 @@ export class SkillReleaseRegistry {
         "active",
         "journals",
         "locks",
+        "state-migrations",
         "staging",
       ]) {
         const directory = path.join(this.rootDir, name);
@@ -1530,6 +3138,13 @@ export class SkillReleaseRegistry {
     return this.#path("journals", `${skillName(name)}.json`);
   }
 
+  #stateMigrationJournalPath(transactionIdValue) {
+    return this.#path(
+      "state-migrations",
+      `${digest(transactionIdValue, "stateMigration.transactionId").slice("sha256:".length)}.json`,
+    );
+  }
+
   #leasePath(name) {
     return this.#path("locks", `${skillName(name)}.lock`);
   }
@@ -1758,6 +3373,355 @@ export class SkillReleaseRegistry {
     return deepFreeze({ release, created });
   }
 
+  migrateLegacyRelease(input, migrationAuthority) {
+    if (arguments.length !== 2) {
+      throw migrationRequired(
+        "legacy release migration requires input and a durable audit authority",
+      );
+    }
+    assertExactKeys(
+      migrationAuthority,
+      RELEASE_MIGRATION_AUTHORITY_KEYS,
+      "release migration authority",
+      SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+    );
+    if (
+      migrationAuthority.schema !== SKILL_RELEASE_MIGRATION_AUTHORITY_SCHEMA ||
+      migrationAuthority.trust !== "trusted" ||
+      typeof migrationAuthority.audit !== "function"
+    ) {
+      throw migrationRequired(
+        "release migration authority is not a trusted synchronous auditor",
+      );
+    }
+    const authorityId = boundedString(
+      migrationAuthority.authorityId,
+      "migrationAuthority.authorityId",
+      256,
+    );
+    const handlerArtifactDigest = digest(
+      migrationAuthority.handlerArtifactDigest,
+      "migrationAuthority.handlerArtifactDigest",
+    );
+    const audit = migrationAuthority.audit;
+    const release = buildMigratedSkillRelease(input);
+    if (release.tenantId !== this.tenantId) {
+      throw migrationRequired("migrated release belongs to another tenant", {
+        candidateTenantId: release.tenantId,
+        tenantId: this.tenantId,
+      });
+    }
+    const legacy = verifyLegacySkillRelease(input.legacyRelease);
+    const created = this.#publishRelease(release);
+    const migrationCore = deepFreeze({
+      authorityId,
+      candidateMigrationDigest:
+        input.candidateMigration.migration.migrationDigest,
+      candidateMigrationReceiptDigest:
+        input.candidateMigration.receipt.receiptDigest,
+      handlerArtifactDigest,
+      legacyCandidateId: legacy.candidateId,
+      legacyReleaseDigest: legacy.releaseDigest,
+      releaseDigest: release.releaseDigest,
+      schema: SKILL_RELEASE_MIGRATION_RECORD_SCHEMA,
+      skillName: release.skillName,
+      tenantId: this.tenantId,
+      trust: "trusted",
+    });
+    const migration = deepFreeze({
+      ...migrationCore,
+      migrationDigest: domainDigest(RELEASE_MIGRATION_DOMAIN, migrationCore),
+    });
+    let receipt;
+    try {
+      receipt = audit(migration);
+    } catch (cause) {
+      throw failure(
+        "SKILL_RELEASE_MIGRATION_AUDIT_FAILED",
+        "release migration audit failed after inactive release publication",
+        {
+          cause,
+          commitState: "inactive-release-only",
+          migrationDigest: migration.migrationDigest,
+          releaseDigest: release.releaseDigest,
+        },
+      );
+    }
+    if (utilTypes.isPromise(receipt)) {
+      throw failure(
+        "SKILL_RELEASE_MIGRATION_AUDIT_FAILED",
+        "release migration audit authority must be synchronous",
+        {
+          commitState: "inactive-release-only",
+          migrationDigest: migration.migrationDigest,
+          releaseDigest: release.releaseDigest,
+        },
+      );
+    }
+    assertExactKeys(
+      receipt,
+      RELEASE_MIGRATION_RECEIPT_KEYS,
+      "release migration receipt",
+      "SKILL_RELEASE_MIGRATION_AUDIT_FAILED",
+    );
+    const normalizedReceipt = deepFreeze({
+      authenticated: receipt.authenticated,
+      authorityId: boundedString(
+        receipt.authorityId,
+        "migrationReceipt.authorityId",
+        256,
+      ),
+      durable: receipt.durable,
+      handlerArtifactDigest: digest(
+        receipt.handlerArtifactDigest,
+        "migrationReceipt.handlerArtifactDigest",
+      ),
+      migrationDigest: digest(
+        receipt.migrationDigest,
+        "migrationReceipt.migrationDigest",
+      ),
+      receiptDigest: digest(
+        receipt.receiptDigest,
+        "migrationReceipt.receiptDigest",
+      ),
+      schema: receipt.schema,
+      trust: receipt.trust,
+    });
+    if (
+      normalizedReceipt.schema !== SKILL_RELEASE_MIGRATION_RECEIPT_SCHEMA ||
+      normalizedReceipt.authenticated !== true ||
+      normalizedReceipt.durable !== true ||
+      normalizedReceipt.trust !== "trusted" ||
+      normalizedReceipt.authorityId !== authorityId ||
+      normalizedReceipt.handlerArtifactDigest !== handlerArtifactDigest ||
+      normalizedReceipt.migrationDigest !== migration.migrationDigest
+    ) {
+      throw failure(
+        "SKILL_RELEASE_MIGRATION_AUDIT_FAILED",
+        "release migration receipt is not exactly bound and durable",
+        {
+          commitState: "inactive-release-only",
+          migrationDigest: migration.migrationDigest,
+          releaseDigest: release.releaseDigest,
+        },
+      );
+    }
+    return deepFreeze({
+      created,
+      migration,
+      receipt: normalizedReceipt,
+      release,
+    });
+  }
+
+  migrateLegacyState(planInput, migrationAuthority) {
+    if (arguments.length !== 2 || this.#ledgerMigrate === null) {
+      throw migrationRequired(
+        "legacy state migration requires a plan, durable authority, and authenticated ledger migration port",
+      );
+    }
+    const plan = verifySkillReleaseStateMigrationPlan(planInput);
+    if (plan.tenantId !== this.tenantId) {
+      throw migrationRequired("state migration plan belongs to another tenant");
+    }
+    assertExactKeys(
+      migrationAuthority,
+      STATE_MIGRATION_AUTHORITY_KEYS,
+      "state migration authority",
+      SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+    );
+    if (
+      migrationAuthority.schema !==
+        SKILL_RELEASE_STATE_MIGRATION_AUTHORITY_SCHEMA ||
+      migrationAuthority.trust !== "trusted" ||
+      typeof migrationAuthority.audit !== "function"
+    ) {
+      throw migrationRequired("state migration authority is not trusted");
+    }
+    const authorityId = boundedString(
+      migrationAuthority.authorityId,
+      "stateMigrationAuthority.authorityId",
+      256,
+    );
+    const handlerArtifactDigest = digest(
+      migrationAuthority.handlerArtifactDigest,
+      "stateMigrationAuthority.handlerArtifactDigest",
+    );
+    const active = this.readRelease(plan.activeReleaseDigest);
+    const lastKnownGood = this.readRelease(plan.lastKnownGoodReleaseDigest);
+    if (
+      active.skillName !== plan.skillName ||
+      lastKnownGood.skillName !== plan.skillName ||
+      active.tenantId !== this.tenantId ||
+      lastKnownGood.tenantId !== this.tenantId ||
+      active.dependencyLockDigest !== plan.dependencyLockDigest
+    ) {
+      throw migrationRequired(
+        "state migration plan release bindings are unavailable or changed",
+      );
+    }
+    let rawReceipt;
+    try {
+      rawReceipt = migrationAuthority.audit(plan);
+    } catch (cause) {
+      throw failure(
+        "SKILL_RELEASE_STATE_MIGRATION_AUDIT_FAILED",
+        "state migration audit authority failed before ledger commit",
+        { cause, stateMigrationDigest: plan.stateMigrationDigest },
+      );
+    }
+    if (utilTypes.isPromise(rawReceipt)) {
+      throw failure(
+        "SKILL_RELEASE_STATE_MIGRATION_AUDIT_FAILED",
+        "state migration audit authority must be synchronous",
+        { stateMigrationDigest: plan.stateMigrationDigest },
+      );
+    }
+    assertExactKeys(
+      rawReceipt,
+      STATE_MIGRATION_RECEIPT_KEYS,
+      "state migration receipt",
+      "SKILL_RELEASE_STATE_MIGRATION_AUDIT_FAILED",
+    );
+    const receipt = deepFreeze({
+      authenticated: rawReceipt.authenticated,
+      authorityId: boundedString(
+        rawReceipt.authorityId,
+        "stateMigrationReceipt.authorityId",
+        256,
+      ),
+      durable: rawReceipt.durable,
+      handlerArtifactDigest: digest(
+        rawReceipt.handlerArtifactDigest,
+        "stateMigrationReceipt.handlerArtifactDigest",
+      ),
+      receiptDigest: digest(
+        rawReceipt.receiptDigest,
+        "stateMigrationReceipt.receiptDigest",
+      ),
+      schema: rawReceipt.schema,
+      stateMigrationDigest: digest(
+        rawReceipt.stateMigrationDigest,
+        "stateMigrationReceipt.stateMigrationDigest",
+      ),
+      trust: rawReceipt.trust,
+    });
+    if (
+      receipt.schema !== SKILL_RELEASE_STATE_MIGRATION_RECEIPT_SCHEMA ||
+      receipt.authenticated !== true ||
+      receipt.durable !== true ||
+      receipt.trust !== "trusted" ||
+      receipt.authorityId !== authorityId ||
+      receipt.handlerArtifactDigest !== handlerArtifactDigest ||
+      receipt.stateMigrationDigest !== plan.stateMigrationDigest
+    ) {
+      throw failure(
+        "SKILL_RELEASE_STATE_MIGRATION_AUDIT_FAILED",
+        "state migration receipt is not exactly bound and durable",
+        { stateMigrationDigest: plan.stateMigrationDigest },
+      );
+    }
+    const existing = this.readState(plan.skillName);
+    if (existing.revision > 0) {
+      if (
+        existing.transactionId !== plan.stateMigrationDigest ||
+        existing.activeReleaseDigest !== plan.activeReleaseDigest ||
+        existing.lastKnownGoodReleaseDigest !==
+          plan.lastKnownGoodReleaseDigest ||
+        existing.dependencyLockDigest !== plan.dependencyLockDigest ||
+        existing.revision !== plan.legacyRevision ||
+        existing.fence !== plan.legacyFence
+      ) {
+        throw failure(
+          "SKILL_RELEASE_STATE_MIGRATION_CONFLICT",
+          "active state is not the exact result of this migration plan",
+        );
+      }
+      return completedStateMigration({
+        created: false,
+        plan,
+        receipt,
+        state: existing,
+      });
+    }
+    const acquired = this.#acquireLease(
+      plan.skillName,
+      plan.stateMigrationDigest,
+      0,
+      EMPTY_SKILL_ACTIVE_DIGEST,
+    );
+    const { heartbeat, lease } = acquired;
+    try {
+      const state = buildState({
+        activeReleaseDigest: plan.activeReleaseDigest,
+        authorityReceiptDigest: active.authorityReceiptDigest,
+        dependencyLockDigest: plan.dependencyLockDigest,
+        fence: plan.legacyFence,
+        lastKnownGoodReleaseDigest: plan.lastKnownGoodReleaseDigest,
+        revision: plan.legacyRevision,
+        skillName: plan.skillName,
+        tenantId: this.tenantId,
+        transactionId: plan.stateMigrationDigest,
+      });
+      const request = deepFreeze({
+        plan,
+        receipt,
+        schema: SKILL_RELEASE_STATE_LEDGER_MIGRATION_SCHEMA,
+        state,
+      });
+      const journal = this.#persistStateMigrationJournal({
+        leaseToken: lease.token,
+        plan,
+        receipt,
+        state,
+      });
+      let projection;
+      try {
+        projection = this.#ledgerMigrate(request);
+      } catch (cause) {
+        throw failure(
+          "SKILL_RELEASE_STATE_MIGRATION_LEDGER_FAILED",
+          "state migration ledger commit failed closed",
+          { cause, stateMigrationDigest: plan.stateMigrationDigest },
+        );
+      }
+      if (utilTypes.isPromise(projection)) {
+        throw failure(
+          "SKILL_RELEASE_LEDGER_INVALID",
+          "state migration ledger port must be synchronous",
+        );
+      }
+      const committed = verifyLedgerProjection(projection, {
+        authorityReceiptDigest: state.authorityReceiptDigest,
+        intentDigest: plan.stateMigrationDigest,
+        pointerDigest: state.stateDigest,
+        prepareReceiptDigest: receipt.receiptDigest,
+        revision: state.revision,
+        skillName: state.skillName,
+        stateDigest: state.stateDigest,
+        transactionId: state.transactionId,
+      });
+      if (committed.status !== "committed" || committed.current !== true) {
+        throw failure(
+          "SKILL_RELEASE_LEDGER_INVALID",
+          "state migration did not produce a current committed projection",
+        );
+      }
+      if (
+        this.#recoverStateMigration(journal, { force: true }) !== "committed"
+      ) {
+        throw failure(
+          "SKILL_RELEASE_STATE_MIGRATION_RECOVERY_FAILED",
+          "state migration did not converge after ledger commit",
+        );
+      }
+      return completedStateMigration({ created: true, plan, receipt, state });
+    } finally {
+      clearInterval(heartbeat);
+      this.#releaseLease(lease);
+    }
+  }
+
   readRelease(releaseDigest) {
     const expected = digest(releaseDigest, "releaseDigest");
     let value;
@@ -1796,7 +3760,7 @@ export class SkillReleaseRegistry {
   #readStateRaw(name) {
     const normalizedName = skillName(name);
     try {
-      const state = verifyState(
+      const state = verifySkillReleaseState(
         this.#readJson(
           this.#statePath(normalizedName),
           "SKILL_RELEASE_STATE_CORRUPT",
@@ -2392,6 +4356,133 @@ export class SkillReleaseRegistry {
     return deepFreeze({ ...value });
   }
 
+  #stateMigrationJournal(value) {
+    const core = { ...value };
+    delete core.journalDigest;
+    return deepFreeze({
+      ...core,
+      journalDigest: domainDigest(STATE_MIGRATION_JOURNAL_DOMAIN, core),
+    });
+  }
+
+  #verifyStateMigrationJournal(value) {
+    assertExactKeys(
+      value,
+      STATE_MIGRATION_JOURNAL_KEYS,
+      "state migration journal",
+      "SKILL_RELEASE_STATE_MIGRATION_JOURNAL_CORRUPT",
+    );
+    const core = { ...value };
+    delete core.journalDigest;
+    if (
+      core.schema !== SKILL_RELEASE_STATE_MIGRATION_JOURNAL_SCHEMA ||
+      tenantId(core.tenantId, "stateMigrationJournal.tenantId") !==
+        this.tenantId ||
+      !TOKEN_PATTERN.test(core.leaseToken) ||
+      domainDigest(STATE_MIGRATION_JOURNAL_DOMAIN, core) !== value.journalDigest
+    ) {
+      throw failure(
+        "SKILL_RELEASE_STATE_MIGRATION_JOURNAL_CORRUPT",
+        "state migration journal digest is invalid",
+      );
+    }
+    const plan = verifySkillReleaseStateMigrationPlan(core.plan);
+    const state = verifySkillReleaseState(core.state);
+    assertExactKeys(
+      core.receipt,
+      STATE_MIGRATION_RECEIPT_KEYS,
+      "state migration journal receipt",
+      "SKILL_RELEASE_STATE_MIGRATION_JOURNAL_CORRUPT",
+    );
+    const receipt = deepFreeze({
+      authenticated: core.receipt.authenticated,
+      authorityId: boundedString(
+        core.receipt.authorityId,
+        "stateMigrationJournal.receipt.authorityId",
+        256,
+      ),
+      durable: core.receipt.durable,
+      handlerArtifactDigest: digest(
+        core.receipt.handlerArtifactDigest,
+        "stateMigrationJournal.receipt.handlerArtifactDigest",
+      ),
+      receiptDigest: digest(
+        core.receipt.receiptDigest,
+        "stateMigrationJournal.receipt.receiptDigest",
+      ),
+      schema: core.receipt.schema,
+      stateMigrationDigest: digest(
+        core.receipt.stateMigrationDigest,
+        "stateMigrationJournal.receipt.stateMigrationDigest",
+      ),
+      trust: core.receipt.trust,
+    });
+    if (
+      receipt.schema !== SKILL_RELEASE_STATE_MIGRATION_RECEIPT_SCHEMA ||
+      receipt.authenticated !== true ||
+      receipt.durable !== true ||
+      receipt.trust !== "trusted" ||
+      receipt.stateMigrationDigest !== plan.stateMigrationDigest ||
+      core.transactionId !== plan.stateMigrationDigest ||
+      core.skillName !== plan.skillName ||
+      state.transactionId !== plan.stateMigrationDigest ||
+      state.tenantId !== this.tenantId ||
+      state.skillName !== plan.skillName ||
+      state.activeReleaseDigest !== plan.activeReleaseDigest ||
+      state.lastKnownGoodReleaseDigest !== plan.lastKnownGoodReleaseDigest ||
+      state.dependencyLockDigest !== plan.dependencyLockDigest ||
+      state.revision !== plan.legacyRevision ||
+      state.fence !== plan.legacyFence
+    ) {
+      throw failure(
+        "SKILL_RELEASE_STATE_MIGRATION_JOURNAL_CORRUPT",
+        "state migration journal bindings are invalid",
+      );
+    }
+    const journal = deepFreeze({
+      ...core,
+      journalDigest: value.journalDigest,
+      plan,
+      receipt,
+      state,
+    });
+    if (canonicalJson(journal) !== canonicalJson(value)) {
+      throw failure(
+        "SKILL_RELEASE_STATE_MIGRATION_JOURNAL_CORRUPT",
+        "state migration journal is not canonical",
+      );
+    }
+    return journal;
+  }
+
+  #persistStateMigrationJournal({ leaseToken, plan, receipt, state }) {
+    const journal = this.#stateMigrationJournal({
+      leaseToken,
+      plan,
+      receipt,
+      schema: SKILL_RELEASE_STATE_MIGRATION_JOURNAL_SCHEMA,
+      skillName: plan.skillName,
+      state,
+      tenantId: this.tenantId,
+      transactionId: plan.stateMigrationDigest,
+    });
+    this.#atomicWrite(
+      "state-migrations",
+      this.#stateMigrationJournalPath(plan.stateMigrationDigest),
+      journal,
+    );
+    return journal;
+  }
+
+  #readStateMigrationJournal(transactionIdValue) {
+    return this.#verifyStateMigrationJournal(
+      this.#readJson(
+        this.#stateMigrationJournalPath(transactionIdValue),
+        "SKILL_RELEASE_STATE_MIGRATION_JOURNAL_CORRUPT",
+      ),
+    );
+  }
+
   #journal(value) {
     const core = { ...value };
     delete core.journalDigest;
@@ -2459,9 +4550,11 @@ export class SkillReleaseRegistry {
       );
     }
     const intent = this.#verifyIntent(core.intent);
-    const nextState = verifyState(core.nextState);
+    const nextState = verifySkillReleaseState(core.nextState);
     const previousState =
-      core.previousState === null ? null : verifyState(core.previousState);
+      core.previousState === null
+        ? null
+        : verifySkillReleaseState(core.previousState);
     if (
       intent.transactionId !== core.transactionId ||
       nextState.transactionId !== core.transactionId ||
@@ -2600,7 +4693,7 @@ export class SkillReleaseRegistry {
     );
     let verifiedStaged;
     try {
-      verifiedStaged = verifyState(
+      verifiedStaged = verifySkillReleaseState(
         this.#parseCanonical(stagedBytes, "SKILL_RELEASE_STATE_CORRUPT"),
       );
     } catch (cause) {
@@ -2654,7 +4747,7 @@ export class SkillReleaseRegistry {
     );
     let verifiedPublished;
     try {
-      verifiedPublished = verifyState(
+      verifiedPublished = verifySkillReleaseState(
         this.#parseCanonical(publishedBytes, "SKILL_RELEASE_STATE_CORRUPT"),
       );
     } catch (cause) {
@@ -2686,7 +4779,7 @@ export class SkillReleaseRegistry {
         this.#statePath(state.skillName),
         "SKILL_RELEASE_STATE_CORRUPT",
       );
-      const verifiedState = verifyState(
+      const verifiedState = verifySkillReleaseState(
         this.#parseCanonical(stateBytes, "SKILL_RELEASE_STATE_CORRUPT"),
       );
       if (
@@ -2869,8 +4962,95 @@ export class SkillReleaseRegistry {
     this.#recoverJournal(journal);
   }
 
+  #cleanupStateMigration(journal) {
+    const lockPath = this.#leasePath(journal.skillName);
+    try {
+      this.#removeLock(lockPath, journal.leaseToken);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    this.#unlink(
+      this.#stateMigrationJournalPath(journal.transactionId),
+      this.#directories["state-migrations"].path,
+    );
+  }
+
+  #recoverStateMigration(journal, { force = false } = {}) {
+    const lockPath = this.#leasePath(journal.skillName);
+    if (this.#exists(lockPath)) {
+      const owner = this.#readOwner(lockPath);
+      if (
+        owner.token !== journal.leaseToken ||
+        owner.transactionId !== journal.transactionId
+      ) {
+        throw failure(
+          "SKILL_RELEASE_RECOVERY_CONFLICT",
+          "state migration journal and lease owner differ",
+        );
+      }
+      if (!force && !this.#ownerStale(owner)) return "pending";
+    }
+    const expected = {
+      authorityReceiptDigest: journal.state.authorityReceiptDigest,
+      intentDigest: journal.plan.stateMigrationDigest,
+      pointerDigest: journal.state.stateDigest,
+      prepareReceiptDigest: journal.receipt.receiptDigest,
+      revision: journal.state.revision,
+      skillName: journal.state.skillName,
+      stateDigest: journal.state.stateDigest,
+    };
+    const projection = this.#query(journal.transactionId, expected);
+    if (projection.status === "absent") {
+      this.#cleanupStateMigration(journal);
+      return "aborted";
+    }
+    if (projection.status !== "committed" || projection.current !== true) {
+      throw failure(
+        "SKILL_RELEASE_RECOVERY_CONFLICT",
+        "state migration ledger projection is not current and committed",
+      );
+    }
+    const current = this.#readStateRaw(journal.skillName);
+    if (current.stateDigest !== journal.state.stateDigest) {
+      if (current.revision !== 0) {
+        throw failure(
+          "SKILL_RELEASE_RECOVERY_CONFLICT",
+          "state migration recovery found an unrelated active pointer",
+        );
+      }
+      this.#atomicWrite(
+        "active",
+        this.#statePath(journal.skillName),
+        journal.state,
+      );
+    }
+    const release = this.readRelease(journal.state.activeReleaseDigest);
+    this.#assertFinalizationArtifacts(journal.state, release);
+    this.#cleanupStateMigration(journal);
+    return "committed";
+  }
+
   #recoverAll() {
     this.#withRecoveryLock(() => {
+      for (const name of this.#fs.readdirSync(
+        this.#directories["state-migrations"].path,
+      )) {
+        if (!/^[a-f0-9]{64}\.json$/u.test(name)) {
+          throw failure(
+            "SKILL_RELEASE_STATE_MIGRATION_JOURNAL_CORRUPT",
+            "unexpected state migration journal entry",
+          );
+        }
+        const transactionId = `sha256:${name.slice(0, -5)}`;
+        const journal = this.#readStateMigrationJournal(transactionId);
+        if (journal.transactionId !== transactionId) {
+          throw failure(
+            "SKILL_RELEASE_STATE_MIGRATION_JOURNAL_CORRUPT",
+            "state migration journal path differs from its transaction",
+          );
+        }
+        this.#recoverStateMigration(journal);
+      }
       const names = this.#fs.readdirSync(this.#directories.journals.path);
       for (const name of names) {
         if (!name.endsWith(".json")) {