chainlesschain 0.166.16 → 0.166.18

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

@@ -9,12 +9,21 @@ import {
   verifySkillRuntimeManifest,
   verifySkillTargetMatrix,
 } from "./skill-execution-manifest.js";
+import { assertEvolutionContentContainsNoKnownSecrets } from "./evolution-evidence-projector.js";
 
 export const SKILL_CANDIDATE_SCHEMA = "chainlesschain.skill-candidate/v2";
 export const SKILL_CANDIDATE_TENANT_MARKER_SCHEMA =
   "chainlesschain.skill-candidate-tenant-marker/v1";
 export const SKILL_CANDIDATE_MIGRATION_REQUIRED_CODE =
   "SKILL_CANDIDATE_MIGRATION_REQUIRED";
+export const SKILL_CANDIDATE_MIGRATION_RECORD_SCHEMA =
+  "chainlesschain.skill-candidate-migration/v1";
+export const SKILL_CANDIDATE_MIGRATION_AUTHORITY_SCHEMA =
+  "chainlesschain.skill-candidate-migration-authority/v1";
+export const SKILL_CANDIDATE_MIGRATION_RECEIPT_SCHEMA =
+  "chainlesschain.skill-candidate-migration-receipt/v1";
+export const SKILL_CANDIDATE_STORE_MIGRATION_SCHEMA =
+  "chainlesschain.skill-candidate-store-migration/v1";
 export const SKILL_CANDIDATE_STORE_LIMIT_CODE = "SKILL_CANDIDATE_STORE_LIMIT";
 export const SKILL_CANDIDATE_STATUS = "draft";
 export const SKILL_CANDIDATE_CONTENT_TYPE =
@@ -46,7 +55,9 @@ const NAMESPACED_ID_PATTERN = /^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$/u;
 const TENANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u;
 const EVIDENCE_REF_PATTERN = /^[a-z][a-z0-9+.-]{1,31}:[^\s\\]+$/u;
 const LEGACY_SKILL_CANDIDATE_SCHEMA = "chainlesschain.skill-candidate/v1";
+const LEGACY_CANDIDATE_DIGEST_DOMAIN = LEGACY_SKILL_CANDIDATE_SCHEMA;
 const CANDIDATE_DIGEST_DOMAIN = "chainlesschain.skill-candidate/v2";
+const CANDIDATE_MIGRATION_DOMAIN = SKILL_CANDIDATE_MIGRATION_RECORD_SCHEMA;
 const TENANT_KEY_DOMAIN = "chainlesschain.skill-candidate-tenant-key/v1";
 const TENANT_MARKER_DIGEST_DOMAIN =
   "chainlesschain.skill-candidate-tenant-marker/v1";
@@ -77,6 +88,23 @@ const CANDIDATE_KEYS = new Set([
   "tenantId",
   "wikiRevision",
 ]);
+const LEGACY_CANDIDATE_KEYS = new Set([
+  "candidateId",
+  "content",
+  "contentDigest",
+  "contentType",
+  "derivationMode",
+  "evalRunId",
+  "parentDigest",
+  "proposerModel",
+  "requestedCapabilities",
+  "schema",
+  "skillName",
+  "sourceEvidenceRefs",
+  "status",
+  "targetRuntimes",
+  "wikiRevision",
+]);
 
 const CREATE_INPUT_KEYS = new Set([
   "content",
@@ -146,6 +174,28 @@ const REGISTRY_OPTION_KEYS = new Set([
   "targetMatrixAdmissionAuthority",
 ]);
 const LIST_OPTION_KEYS = new Set(["limit"]);
+const MIGRATION_EXECUTION_KEYS = new Set([
+  "dependencyLock",
+  "runtimeManifest",
+  "targetMatrix",
+]);
+const MIGRATION_AUTHORITY_KEYS = new Set([
+  "audit",
+  "authorityId",
+  "handlerArtifactDigest",
+  "schema",
+  "trust",
+]);
+const MIGRATION_RECEIPT_KEYS = new Set([
+  "authenticated",
+  "authorityId",
+  "durable",
+  "handlerArtifactDigest",
+  "migrationDigest",
+  "receiptDigest",
+  "schema",
+  "trust",
+]);
 const PROPOSER_MODEL_KEYS = new Set(["model", "provider", "version"]);
 const SOURCE_EVIDENCE_KEYS = new Set(["digest", "ref"]);
 const DERIVATION_MODES = new Set(["wiki", "record-replay", "manual-import"]);
@@ -405,9 +455,22 @@ function normalizeContent(value) {
       `content exceeds ${SKILL_CANDIDATE_MAX_CONTENT_BYTES} bytes`,
     );
   }
+  assertCandidatePlaintextSafe(value, "content");
   return value;
 }
 
+function assertCandidatePlaintextSafe(value, label) {
+  try {
+    assertEvolutionContentContainsNoKnownSecrets(value);
+  } catch (cause) {
+    throw registryError(
+      "SKILL_CANDIDATE_SECRET_LEAK",
+      `candidate ${label} contains secret or PII plaintext`,
+      { cause },
+    );
+  }
+}
+
 function normalizeNamespacedId(value, label) {
   const normalized = normalizeBoundedString(value, label, 128);
   if (!NAMESPACED_ID_PATTERN.test(normalized)) {
@@ -496,6 +559,7 @@ function normalizeSourceEvidenceRefs(value) {
         `sourceEvidenceRefs[${index}].ref must be an absolute opaque URI`,
       );
     }
+    assertCandidatePlaintextSafe(ref, `sourceEvidenceRefs[${index}].ref`);
     return {
       digest: normalizeDigest(
         ownData(entry, "digest", `sourceEvidenceRefs[${index}]`),
@@ -1002,6 +1066,112 @@ function candidateCore(input, verificationContext) {
   };
 }
 
+/** Verify the exact historical v1 draft before any tenant-scoped migration. */
+export function verifyLegacySkillCandidateDraft(candidate) {
+  assertDataRecord(candidate, LEGACY_CANDIDATE_KEYS, "legacy candidate", {
+    exact: true,
+  });
+  if (
+    ownData(candidate, "schema", "legacy candidate") !==
+      LEGACY_SKILL_CANDIDATE_SCHEMA ||
+    ownData(candidate, "status", "legacy candidate") !==
+      SKILL_CANDIDATE_STATUS ||
+    ownData(candidate, "contentType", "legacy candidate") !==
+      SKILL_CANDIDATE_CONTENT_TYPE
+  ) {
+    throw migrationRequired(
+      "legacy candidate schema, status, or content type is invalid",
+    );
+  }
+  const evalRunId = ownData(candidate, "evalRunId", "legacy candidate");
+  if (evalRunId !== null) {
+    throw migrationRequired("legacy draft candidate cannot carry evalRunId");
+  }
+  const content = normalizeContent(
+    ownData(candidate, "content", "legacy candidate"),
+  );
+  const sourceEvidenceRefs = normalizeSourceEvidenceRefs(
+    ownData(candidate, "sourceEvidenceRefs", "legacy candidate"),
+  );
+  const derivationMode = normalizeDerivationMode(
+    ownData(candidate, "derivationMode", "legacy candidate"),
+  );
+  const wikiRevision = normalizeNullableReference(
+    ownData(candidate, "wikiRevision", "legacy candidate"),
+    "wikiRevision",
+  );
+  const proposerModel = normalizeProposerModel(
+    ownData(candidate, "proposerModel", "legacy candidate"),
+  );
+  if (sourceEvidenceRefs.length === 0) {
+    throw migrationRequired("legacy candidate has no source evidence");
+  }
+  if (
+    derivationMode === "wiki" &&
+    (wikiRevision === null || proposerModel === null)
+  ) {
+    throw migrationRequired(
+      "legacy wiki candidate is missing its revision or proposer",
+    );
+  }
+  if (derivationMode !== "wiki" && wikiRevision !== null) {
+    throw migrationRequired("legacy non-wiki candidate claims a wiki revision");
+  }
+  const core = {
+    schema: LEGACY_SKILL_CANDIDATE_SCHEMA,
+    status: SKILL_CANDIDATE_STATUS,
+    skillName: normalizeSkillName(
+      ownData(candidate, "skillName", "legacy candidate"),
+    ),
+    parentDigest: normalizeDigest(
+      ownData(candidate, "parentDigest", "legacy candidate"),
+      "parentDigest",
+      { nullable: true },
+    ),
+    contentDigest: contentDigest(content),
+    sourceEvidenceRefs,
+    derivationMode,
+    wikiRevision,
+    proposerModel,
+    targetRuntimes: normalizeUniqueStringList(
+      ownData(candidate, "targetRuntimes", "legacy candidate"),
+      "targetRuntimes",
+      MAX_TARGET_RUNTIMES,
+    ),
+    requestedCapabilities: normalizeUniqueStringList(
+      ownData(candidate, "requestedCapabilities", "legacy candidate"),
+      "requestedCapabilities",
+      MAX_REQUESTED_CAPABILITIES,
+    ),
+    evalRunId: null,
+    contentType: SKILL_CANDIDATE_CONTENT_TYPE,
+    content,
+  };
+  const normalized = deepFreeze({
+    candidateId: domainDigest(LEGACY_CANDIDATE_DIGEST_DOMAIN, core),
+    ...core,
+  });
+  if (
+    ownData(candidate, "candidateId", "legacy candidate") !==
+      normalized.candidateId ||
+    ownData(candidate, "contentDigest", "legacy candidate") !==
+      normalized.contentDigest ||
+    canonicalJson(candidate) !== canonicalJson(normalized)
+  ) {
+    throw migrationRequired(
+      "legacy candidate bytes or digests are not canonical",
+      {
+        legacyCandidateId: ownData(
+          candidate,
+          "candidateId",
+          "legacy candidate",
+        ),
+      },
+    );
+  }
+  return normalized;
+}
+
 /** Build the only artifact shape accepted by the candidate registry. */
 export function buildSkillCandidateDraft(input, verificationContext) {
   const core = candidateCore(input, verificationContext);
@@ -1958,6 +2128,485 @@ export class SkillCandidateRegistry {
     );
   }
 
+  migrateLegacy(legacyCandidate, executionArtifacts, migrationAuthority) {
+    if (arguments.length !== 3) {
+      throw migrationRequired(
+        "legacy migration requires candidate, execution artifacts, and a durable audit authority",
+      );
+    }
+    const legacy = verifyLegacySkillCandidateDraft(legacyCandidate);
+    assertDataRecord(
+      executionArtifacts,
+      MIGRATION_EXECUTION_KEYS,
+      "candidate migration execution artifacts",
+      { exact: true },
+    );
+    assertDataRecord(
+      migrationAuthority,
+      MIGRATION_AUTHORITY_KEYS,
+      "candidate migration authority",
+      { exact: true },
+    );
+    if (
+      ownData(migrationAuthority, "schema", "candidate migration authority") !==
+        SKILL_CANDIDATE_MIGRATION_AUTHORITY_SCHEMA ||
+      ownData(migrationAuthority, "trust", "candidate migration authority") !==
+        "trusted"
+    ) {
+      throw migrationRequired(
+        "candidate migration authority is not trusted or has an unsupported schema",
+      );
+    }
+    const authorityId = normalizeNamespacedId(
+      ownData(
+        migrationAuthority,
+        "authorityId",
+        "candidate migration authority",
+      ),
+      "migrationAuthority.authorityId",
+    );
+    const handlerArtifactDigest = normalizeDigest(
+      ownData(
+        migrationAuthority,
+        "handlerArtifactDigest",
+        "candidate migration authority",
+      ),
+      "migrationAuthority.handlerArtifactDigest",
+    );
+    const audit = ownData(
+      migrationAuthority,
+      "audit",
+      "candidate migration authority",
+    );
+    if (typeof audit !== "function") {
+      throw migrationRequired(
+        "candidate migration audit port must be a function",
+      );
+    }
+
+    const dependencyLock = ownData(
+      executionArtifacts,
+      "dependencyLock",
+      "candidate migration execution artifacts",
+    );
+    const runtimeManifest = ownData(
+      executionArtifacts,
+      "runtimeManifest",
+      "candidate migration execution artifacts",
+    );
+    const targetMatrix = ownData(
+      executionArtifacts,
+      "targetMatrix",
+      "candidate migration execution artifacts",
+    );
+    assertPlainObject(targetMatrix, "candidate migration targetMatrix");
+    const targetRuntimes = normalizeUniqueStringList(
+      ownData(
+        targetMatrix,
+        "targetRuntimes",
+        "candidate migration targetMatrix",
+      ),
+      "targetMatrix.targetRuntimes",
+      MAX_TARGET_RUNTIMES,
+    );
+    if (
+      canonicalJson(targetRuntimes) !== canonicalJson(legacy.targetRuntimes)
+    ) {
+      throw migrationRequired(
+        "candidate migration target matrix changes the legacy runtime scope",
+        { legacyCandidateId: legacy.candidateId },
+      );
+    }
+
+    const publication = this.create({
+      tenantId: this.tenantId,
+      skillName: legacy.skillName,
+      parentDigest: legacy.parentDigest,
+      sourceEvidenceRefs: legacy.sourceEvidenceRefs,
+      derivationMode: legacy.derivationMode,
+      wikiRevision: legacy.wikiRevision,
+      proposerModel: legacy.proposerModel,
+      requestedCapabilities: legacy.requestedCapabilities,
+      evalRunId: null,
+      content: legacy.content,
+      dependencyLock,
+      runtimeManifest,
+      targetMatrix,
+    });
+    const candidate = publication.candidate;
+    const migrationCore = deepFreeze({
+      authorityId,
+      candidateId: candidate.candidateId,
+      contentDigest: candidate.contentDigest,
+      dependencyLockDigest: candidate.dependencyLockDigest,
+      handlerArtifactDigest,
+      legacyArtifactDigest: sha256(
+        Buffer.from(`${canonicalJson(legacy)}\n`, "utf8"),
+      ),
+      legacyCandidateId: legacy.candidateId,
+      runtimeManifestDigest: candidate.runtimeManifestDigest,
+      schema: SKILL_CANDIDATE_MIGRATION_RECORD_SCHEMA,
+      targetMatrixRoot: candidate.targetMatrixRoot,
+      tenantId: this.tenantId,
+      trust: "trusted",
+    });
+    const missingBindings = Object.entries(migrationCore)
+      .filter(([, value]) => value === undefined)
+      .map(([key]) => key);
+    if (missingBindings.length > 0) {
+      throw migrationRequired(
+        "candidate migration could not derive a complete audit binding",
+        { legacyCandidateId: legacy.candidateId, missingBindings },
+      );
+    }
+    const migration = deepFreeze({
+      ...migrationCore,
+      migrationDigest: domainDigest(CANDIDATE_MIGRATION_DOMAIN, migrationCore),
+    });
+    let receipt;
+    try {
+      receipt = audit(migration);
+    } catch (cause) {
+      throw registryError(
+        "SKILL_CANDIDATE_MIGRATION_AUDIT_FAILED",
+        "candidate migration audit authority failed after draft publication",
+        {
+          candidateId: candidate.candidateId,
+          cause,
+          commitState: "candidate-only",
+          migrationDigest: migration.migrationDigest,
+        },
+      );
+    }
+    if (utilTypes.isPromise(receipt)) {
+      throw registryError(
+        "SKILL_CANDIDATE_MIGRATION_AUDIT_FAILED",
+        "candidate migration audit authority must be synchronous",
+        {
+          candidateId: candidate.candidateId,
+          commitState: "candidate-only",
+          migrationDigest: migration.migrationDigest,
+        },
+      );
+    }
+    assertDataRecord(
+      receipt,
+      MIGRATION_RECEIPT_KEYS,
+      "candidate migration receipt",
+      { exact: true },
+    );
+    const normalizedReceipt = deepFreeze({
+      authenticated: ownData(
+        receipt,
+        "authenticated",
+        "candidate migration receipt",
+      ),
+      authorityId: normalizeNamespacedId(
+        ownData(receipt, "authorityId", "candidate migration receipt"),
+        "migrationReceipt.authorityId",
+      ),
+      durable: ownData(receipt, "durable", "candidate migration receipt"),
+      handlerArtifactDigest: normalizeDigest(
+        ownData(
+          receipt,
+          "handlerArtifactDigest",
+          "candidate migration receipt",
+        ),
+        "migrationReceipt.handlerArtifactDigest",
+      ),
+      migrationDigest: normalizeDigest(
+        ownData(receipt, "migrationDigest", "candidate migration receipt"),
+        "migrationReceipt.migrationDigest",
+      ),
+      receiptDigest: normalizeDigest(
+        ownData(receipt, "receiptDigest", "candidate migration receipt"),
+        "migrationReceipt.receiptDigest",
+      ),
+      schema: ownData(receipt, "schema", "candidate migration receipt"),
+      trust: ownData(receipt, "trust", "candidate migration receipt"),
+    });
+    if (
+      normalizedReceipt.schema !== SKILL_CANDIDATE_MIGRATION_RECEIPT_SCHEMA ||
+      normalizedReceipt.authenticated !== true ||
+      normalizedReceipt.durable !== true ||
+      normalizedReceipt.trust !== "trusted" ||
+      normalizedReceipt.authorityId !== authorityId ||
+      normalizedReceipt.handlerArtifactDigest !== handlerArtifactDigest ||
+      normalizedReceipt.migrationDigest !== migration.migrationDigest
+    ) {
+      throw registryError(
+        "SKILL_CANDIDATE_MIGRATION_AUDIT_FAILED",
+        "candidate migration receipt is not exactly bound and durable",
+        {
+          candidateId: candidate.candidateId,
+          commitState: "candidate-only",
+          migrationDigest: migration.migrationDigest,
+        },
+      );
+    }
+    return deepFreeze({
+      candidate,
+      created: publication.created,
+      migration,
+      receipt: normalizedReceipt,
+    });
+  }
+
+  migrateLegacyStore(
+    sourceRootDir,
+    resolveExecutionArtifacts,
+    migrationAuthority,
+  ) {
+    if (
+      arguments.length !== 3 ||
+      typeof resolveExecutionArtifacts !== "function"
+    ) {
+      throw migrationRequired(
+        "legacy store migration requires one source root, one execution resolver, and one audit authority",
+      );
+    }
+    assertDataRecord(
+      migrationAuthority,
+      MIGRATION_AUTHORITY_KEYS,
+      "candidate migration authority",
+      { exact: true },
+    );
+    const capturedMigrationAuthority = Object.freeze(
+      Object.fromEntries(
+        [...MIGRATION_AUTHORITY_KEYS].map((key) => [
+          key,
+          ownData(migrationAuthority, key, "candidate migration authority"),
+        ]),
+      ),
+    );
+    const requestedSource = path.resolve(
+      normalizeBoundedString(
+        sourceRootDir,
+        "legacy candidate source root",
+        32_768,
+      ),
+    );
+    let sourceRoot;
+    let sourceIdentity;
+    try {
+      const stat = this._fs.lstatSync(requestedSource);
+      sourceRoot = realpath(this._fs, requestedSource);
+      const canonicalStat = this._fs.lstatSync(sourceRoot);
+      const canonicalParent = realpath(this._fs, path.dirname(requestedSource));
+      const expectedCanonical = path.join(
+        canonicalParent,
+        path.basename(requestedSource),
+      );
+      if (
+        !stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        !canonicalStat.isDirectory() ||
+        canonicalStat.isSymbolicLink() ||
+        entryIdentity(canonicalStat) !== entryIdentity(stat) ||
+        !samePath(sourceRoot, expectedCanonical) ||
+        !samePath(realpath(this._fs, sourceRoot), sourceRoot) ||
+        isContained(sourceRoot, this.baseDir) ||
+        isContained(this.baseDir, sourceRoot)
+      ) {
+        throw registryError(
+          "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+          "legacy source must be a canonical directory independent from the tenant registry",
+        );
+      }
+      sourceIdentity = entryIdentity(stat);
+    } catch (cause) {
+      if (cause instanceof SkillCandidateRegistryError) throw cause;
+      throw registryError(
+        "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+        "legacy candidate source root is unavailable or unsafe",
+        { cause },
+      );
+    }
+    const assertSourceBoundary = () => {
+      const stat = this._fs.lstatSync(sourceRoot);
+      if (
+        !stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        entryIdentity(stat) !== sourceIdentity ||
+        !samePath(realpath(this._fs, sourceRoot), sourceRoot)
+      ) {
+        throw registryError(
+          "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+          "legacy candidate source root changed during migration",
+        );
+      }
+    };
+
+    this._assertBoundary();
+    assertSourceBoundary();
+    const names = this._readDirectoryEntryNamesBounded(
+      sourceRoot,
+      "legacy candidate source",
+    ).sort(compareStrings);
+    const sources = [];
+    let totalBytes = 0;
+    for (const name of names) {
+      assertSourceBoundary();
+      const match = CANDIDATE_FILE_PATTERN.exec(name);
+      if (!match) {
+        throw migrationRequired(
+          "legacy candidate source contains a non-candidate entry",
+          { path: path.join(sourceRoot, name) },
+        );
+      }
+      const sourcePath = path.resolve(sourceRoot, name);
+      if (
+        !isContained(sourceRoot, sourcePath) ||
+        !samePath(path.dirname(sourcePath), sourceRoot)
+      ) {
+        throw registryError(
+          "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+          "legacy candidate source path escaped its root",
+        );
+      }
+      const stored = this._readBoundedRegularFile(
+        sourcePath,
+        SKILL_CANDIDATE_MAX_ARTIFACT_BYTES,
+        "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+        "legacy candidate artifact",
+      );
+      totalBytes += stored.bytes.length;
+      if (totalBytes > SKILL_CANDIDATE_TENANT_SCAN_MAX_BYTES) {
+        throw tenantScanLimit(
+          "legacy candidate migration exceeded its aggregate byte budget",
+          { path: sourcePath },
+        );
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(
+          new TextDecoder("utf-8", { fatal: true }).decode(stored.bytes),
+        );
+      } catch (cause) {
+        throw registryError(
+          "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+          "legacy candidate is not bounded UTF-8 JSON",
+          { cause, path: sourcePath },
+        );
+      }
+      const legacy = verifyLegacySkillCandidateDraft(parsed);
+      const canonicalBytes = Buffer.from(`${canonicalJson(legacy)}\n`, "utf8");
+      if (
+        legacy.candidateId.slice("sha256:".length) !== match[1] ||
+        !stored.bytes.equals(canonicalBytes)
+      ) {
+        throw registryError(
+          "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+          "legacy candidate filename or bytes are not content-addressed and canonical",
+          { path: sourcePath },
+        );
+      }
+      sources.push(
+        Object.freeze({
+          bytesDigest: sha256(stored.bytes),
+          identity: stored.identity,
+          legacy,
+          name,
+          sourcePath,
+        }),
+      );
+      assertSourceBoundary();
+    }
+
+    const entries = [];
+    let createdCount = 0;
+    for (const source of sources) {
+      assertSourceBoundary();
+      let executionArtifacts;
+      try {
+        executionArtifacts = resolveExecutionArtifacts(
+          deepFreeze({
+            legacyCandidateId: source.legacy.candidateId,
+            schema: SKILL_CANDIDATE_STORE_MIGRATION_SCHEMA,
+            skillName: source.legacy.skillName,
+            targetRuntimes: source.legacy.targetRuntimes,
+            tenantId: this.tenantId,
+          }),
+        );
+      } catch (cause) {
+        throw registryError(
+          "SKILL_CANDIDATE_MIGRATION_EXECUTION_UNAVAILABLE",
+          "legacy candidate execution artifacts could not be resolved",
+          {
+            cause,
+            legacyCandidateId: source.legacy.candidateId,
+            migratedCount: entries.length,
+          },
+        );
+      }
+      if (utilTypes.isPromise(executionArtifacts)) {
+        throw registryError(
+          "SKILL_CANDIDATE_MIGRATION_EXECUTION_UNAVAILABLE",
+          "legacy candidate execution resolver must be synchronous",
+          {
+            legacyCandidateId: source.legacy.candidateId,
+            migratedCount: entries.length,
+          },
+        );
+      }
+      const migrated = this.migrateLegacy(
+        source.legacy,
+        executionArtifacts,
+        capturedMigrationAuthority,
+      );
+      if (migrated.created) createdCount += 1;
+      entries.push(
+        deepFreeze({
+          candidateId: migrated.candidate.candidateId,
+          legacyArtifactDigest: migrated.migration.legacyArtifactDigest,
+          legacyCandidateId: source.legacy.candidateId,
+          migrationDigest: migrated.migration.migrationDigest,
+          receiptDigest: migrated.receipt.receiptDigest,
+        }),
+      );
+    }
+
+    for (const source of sources) {
+      assertSourceBoundary();
+      const current = this._readBoundedRegularFile(
+        source.sourcePath,
+        SKILL_CANDIDATE_MAX_ARTIFACT_BYTES,
+        "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+        "legacy candidate artifact",
+      );
+      if (
+        current.identity !== source.identity ||
+        sha256(current.bytes) !== source.bytesDigest
+      ) {
+        throw registryError(
+          "SKILL_CANDIDATE_MIGRATION_SOURCE_UNSAFE",
+          "legacy candidate source changed before migration completion",
+          {
+            legacyCandidateId: source.legacy.candidateId,
+            migratedCount: entries.length,
+          },
+        );
+      }
+    }
+    this._assertBoundary();
+    assertSourceBoundary();
+    const core = deepFreeze({
+      entries,
+      migratedCount: entries.length,
+      schema: SKILL_CANDIDATE_STORE_MIGRATION_SCHEMA,
+      sourceArtifactCount: sources.length,
+      tenantId: this.tenantId,
+    });
+    return deepFreeze({
+      ...core,
+      createdCount,
+      migrationDigest: domainDigest(
+        SKILL_CANDIDATE_STORE_MIGRATION_SCHEMA,
+        core,
+      ),
+    });
+  }
+
   create(input) {
     if (arguments.length !== 1) {
       throw registryError(