@xemahq/xema 0.53.0 → 0.54.0

package/edition/candidate-edition.mjs

@@ -0,0 +1,692 @@
+// candidate-edition — re-seal a pinned develop edition with ONE repository's candidate commit, for a boot test.
+//
+// A repository's candidate CI boots the composed member set through the production path, and that needs
+// a lock triple that matches its candidate commit: a pinned develop edition is stale against it the moment
+// the candidate changes a biome. This module produces that triple, in two steps:
+//
+//   fetchPinnedEditionCheckouts   the ONE network step: every checkout the develop resolve reads, at the
+//                                 pinned edition's own pins (xema-edition.json provenance.pins), cached
+//                                 under the caller's cacheDir by pin key + commit. A warm cache does no network.
+//   resealCandidateEdition        OFFLINE: the develop resolve's distribution and authorization steps rerun
+//                                 over those frozen checkouts with the candidate repository at its HEAD, the
+//                                 images lock carried byte for byte, and the unsplit resolved deployment the
+//                                 kernel computes from exactly the bytes written.
+//
+// THE OUTPUT IS A PLAIN DIRECTORY, NEVER AN EDITION. It carries no xema-edition.json descriptor, it is never
+// an OCI artifact and it is never signed, so no deploy admits it: admission rests on the cosign signature of
+// a pushed edition artifact's digest (edition-artifact.mjs), and the resolved deployment written here is the
+// kernel's UNSPLIT variant, which `verifyResolvedDeployment` refuses unless its caller opts into it.
+//
+// THE CANDIDATE CONTENT RECORD. The images lock is carried, so for a biome that ships images from the
+// candidate repository it still says the images were built at the PINNED commit, and the content-hash rule
+// (biome-content.mjs `pinnedCommit`) reads a biome's content where its images were built. The candidate's
+// content is at another commit, so the output records that fact in `candidate-content.json`
+// ({ repo -> commit }, bound to the distribution lock bytes by digest) and the seal and the verifier read it
+// through biome-content.mjs `contentCommits`: a record naming a commit whose content is not the lock's is
+// refused by the same comparison every seal makes, and a triple without a record verifies exactly as before.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+import { sealLock, verifyBiomeContentHashes } from './biome-content.mjs';
+import {
+  crossRepoVendoredCommits,
+  platformServiceExtraCommits,
+  sourceAxisExtraCommits,
+  sourceCheckoutPlan,
+} from './checkout-indexed-source-repositories.mjs';
+import { assertDevelopEditionInvariants } from './develop-edition-invariants.mjs';
+import { buildSnapshotInputs } from './develop-snapshot-inputs.mjs';
+import { parseEditionDescriptor } from './edition-artifact.mjs';
+import { resetEditionWorkspaceConfig, editionWorkspaceConfig } from './edition-config.mjs';
+import { DIGEST_PIN_KEYS, EDITION_DESCRIPTOR_FILE, EditionChannel, EditionLockFile } from './edition-constants.mjs';
+import {
+  KERNEL_PACKAGE_REPO_PATH,
+  WorkspaceRoot,
+  configureEditionWorkspace,
+  configuredWorkspace,
+  kernelDistPath,
+  kernelPackageDir,
+  platformServiceIndexPath,
+  runtimeImageSourceIndexPath,
+} from './edition-workspace.mjs';
+import { materializeGitSource, externalSourceCacheDir } from './external-source-walk.mjs';
+import { withSourceGitEnv } from './git-source-auth.mjs';
+import { loadKernelDistributionSchemas, serializeJson, sha256Hex } from './lib.mjs';
+import { assertLockBundleSigners } from './locked-bundle-signer.mjs';
+import { admitDistributionLock } from './operation-grant-admission.mjs';
+import {
+  EDITIONS_ROOT_PIN_KEY,
+  SnapshotPinNamespace,
+  applyPinSource,
+  dataPinKey,
+  kernelPinKey,
+  pinnedSource,
+  snapshotPinNamespace,
+  snapshotPinSource,
+} from './pin-source.mjs';
+import { composeAuthorizationBase, composeEdition, prepareDistributionWithIndex } from './resolve-distribution.mjs';
+import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
+import { shallowCheckout, shallowFetch } from './shallow-checkout.mjs';
+import { createPinnedSourceAuthority } from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+/** The candidate content record: which repository's first-party biomes have their content at which commit. */
+export const CANDIDATE_CONTENT_FILE = 'candidate-content.json';
+export const CANDIDATE_CONTENT_SCHEMA = 'xema.candidate-content/v1';
+/** The kernel's unsplit resolved deployment, computed from exactly the lock bytes written beside it. */
+export const RESOLVED_DEPLOYMENT_FILE = 'resolved-deployment.json';
+/** The coordinate a candidate triple names: a reserved `.invalid` registry, so it can never be read as a published edition's. */
+export const CANDIDATE_EDITION_REGISTRY = 'candidate.invalid';
+export const CANDIDATE_EDITION_VERSION = '0.0.0-candidate';
+/** Every file of a candidate triple, in the order it is written. */
+export const CANDIDATE_FILES = Object.freeze([
+  EditionLockFile.Distribution,
+  EditionLockFile.Images,
+  EditionLockFile.Authorization,
+  RESOLVED_DEPLOYMENT_FILE,
+  CANDIDATE_CONTENT_FILE,
+]);
+
+/** A refusal of the candidate re-seal: the pinned edition, a checkout or the candidate is not what it must be. */
+export class CandidateEditionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CandidateEditionError';
+  }
+}
+
+
+function defaultRunGit(args, env) {
+  return execFileSync('git', args, { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+/**
+ * The environment of a LOCAL git command: PATH and HOME only. No GIT_* variable (GIT_DIR, GIT_WORK_TREE,
+ * GIT_INDEX_FILE, a hook's environment) reaches it, so it reads exactly the directory it names; it needs no credential.
+ */
+function localGitEnv() {
+  const env = {};
+  for (const name of ['PATH', 'HOME']) {
+    if (process.env[name] !== undefined) {env[name] = process.env[name];}
+  }
+  return env;
+}
+
+function runLocalGit(args) {
+  return execFileSync('git', args, { encoding: 'utf8', env: localGitEnv(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+/** A LOCAL git read; the reseal runs only these. */
+function localGit(dir, args) {
+  return runLocalGit(['-C', dir, ...args]);
+}
+
+function hasCommit(dir, commit) {
+  try {
+    localGit(dir, ['cat-file', '-e', `${commit}^{commit}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The develop build of the kernel: the same two commands develop-edition.yaml runs in its kernel checkout. */
+function defaultBuildKernel(repoDir) {
+  for (const args of [['pnpm', 'install', '--frozen-lockfile'], ['pnpm', 'run', 'build']]) {
+    execFileSync('corepack', args, { cwd: repoDir, stdio: ['ignore', 'inherit', 'inherit'] });
+  }
+}
+
+function absoluteDir(name, value) {
+  if (typeof value !== 'string' || !isAbsolute(value)) {
+    throw new CandidateEditionError(`${name} must be an absolute directory path, got ${JSON.stringify(value)}`);
+  }
+  return resolve(value);
+}
+
+/**
+ * The pinned develop edition: its descriptor (strict parse), its pins, and the three lock files. A customer
+ * edition (digest pins), an edition of another channel, or a missing lock is refused.
+ */
+export function readPinnedEdition(tripleDir) {
+  const dir = absoluteDir('tripleDir', tripleDir);
+  const descriptorPath = join(dir, EDITION_DESCRIPTOR_FILE);
+  if (!existsSync(descriptorPath)) {
+    throw new CandidateEditionError(`${dir} holds no ${EDITION_DESCRIPTOR_FILE}: the pinned edition's pins are read from its descriptor`);
+  }
+  const descriptor = parseEditionDescriptor(readStrictJsonFile(descriptorPath));
+  if (descriptor.provenance.channel !== EditionChannel.Develop) {
+    throw new CandidateEditionError(
+      `${descriptorPath}: "${descriptor.distributionId}" is a ${descriptor.provenance.channel} edition; a candidate is re-sealed only from a develop edition`,
+    );
+  }
+  const digestPins = DIGEST_PIN_KEYS.filter((key) => key in descriptor.provenance.pins);
+  if (digestPins.length > 0) {
+    throw new CandidateEditionError(
+      `${descriptorPath}: "${descriptor.distributionId}" pins ${digestPins.join(', ')}: a customer edition is resolved against a catalogue, not from checkouts`,
+    );
+  }
+  const bytes = {};
+  for (const file of [EditionLockFile.Distribution, EditionLockFile.Images, EditionLockFile.Authorization]) {
+    const path = join(dir, file);
+    if (!existsSync(path)) {throw new CandidateEditionError(`${dir} holds no ${file}`);}
+    bytes[file] = readFileSync(path);
+  }
+  for (const file of Object.keys(bytes)) {
+    const { distributionId } = JSON.parse(bytes[file].toString('utf8'));
+    if (distributionId !== descriptor.distributionId) {
+      throw new CandidateEditionError(`${join(dir, file)} is for "${distributionId}", but the descriptor names "${descriptor.distributionId}"`);
+    }
+  }
+  return { dir, id: descriptor.distributionId, pins: { ...descriptor.provenance.pins }, bytes };
+}
+
+/** Where a pin key's checkout at `commit` is cached. */
+function cachedCheckoutDir(cacheDir, key, commit) {
+  return join(cacheDir, 'checkouts', key.replaceAll('/', '__'), commit);
+}
+
+/**
+ * A checkout that IS the frozen commit: HEAD is the pin and the tree is clean. `trackedOnly` ignores
+ * untracked files (the candidate, whose tracked files are what is read); a cached checkout is held to all.
+ */
+function assertCheckoutAt({ dir, commit, what, trackedOnly = false }) {
+  if (!existsSync(join(dir, '.git'))) {
+    throw new CandidateEditionError(`${what}: ${dir} is not a git checkout`);
+  }
+  const head = localGit(dir, ['rev-parse', 'HEAD']);
+  if (commit !== undefined && head !== commit) {
+    throw new CandidateEditionError(`${what}: ${dir} is at ${head}, not the pinned ${commit}`);
+  }
+  const dirty = localGit(dir, ['status', '--porcelain', ...(trackedOnly ? ['--untracked-files=no'] : [])]);
+  if (dirty.length > 0) {
+    throw new CandidateEditionError(`${what}: ${dir} is not clean, so it is not the commit ${head}:\n${dirty}`);
+  }
+  return head;
+}
+
+/** The candidate: a pin key of the edition's develop graph, and a clean checkout whose HEAD is the candidate commit. */
+function readCandidate(candidate, pins) {
+  const repo = candidate?.repo;
+  if (typeof repo !== 'string' || !(repo in pins)) {
+    throw new CandidateEditionError(`candidate repository ${JSON.stringify(repo)} is not pinned by the edition; it pins ${Object.keys(pins).sort().join(', ')}`);
+  }
+  if (snapshotPinNamespace(repo) !== SnapshotPinNamespace.Graph) {
+    throw new CandidateEditionError(
+      `candidate repository "${repo}" is not a develop-graph repository (repos/<x> or submodules/<x>); the data root, the kernel and the chart tree are not candidates`,
+    );
+  }
+  const checkoutDir = absoluteDir('candidate.checkoutDir', candidate.checkoutDir);
+  const commit = assertCheckoutAt({ dir: checkoutDir, what: `candidate ${repo}`, trackedOnly: true });
+  return { repo, checkoutDir, commit };
+}
+
+/**
+ * Run `fn` with the edition workspace configured on `roots`, and put the previous configuration back after it.
+ * The edition workspace is PROCESS-GLOBAL configuration (edition-workspace.mjs): this swaps it for the duration
+ * of `fn`, async `fn` included. Two calls in flight in one process (two concurrent re-seals, fetches or
+ * verifications) would read each other's roots, so it is not safe to run two at once in one process.
+ */
+function withWorkspace(roots, fn) {
+  const previous = configuredWorkspace();
+  configureEditionWorkspace(roots);
+  resetEditionWorkspaceConfig();
+  const restore = () => {
+    configureEditionWorkspace(previous);
+    resetEditionWorkspaceConfig();
+  };
+  let result;
+  try {
+    result = fn();
+  } catch (error) {
+    restore();
+    throw error;
+  }
+  if (result instanceof Promise) {return result.finally(restore);}
+  restore();
+  return result;
+}
+
+/**
+ * The checkouts of the pinned edition with the candidate in place: a sources root under `scratch` whose
+ * `<pin key>` entries link the cached checkouts (and the candidate's own), each held to its pin first.
+ * Returns the workspace roots the develop resolve reads.
+ */
+function stageWorkspace({ cacheDir, dataKey, pins, candidate, scratch }) {
+  const dataDir = cachedDataRoot(cacheDir, dataKey, pins);
+  return withWorkspace({ [WorkspaceRoot.Data]: dataDir }, () => {
+    if (EDITIONS_ROOT_PIN_KEY in pins) {
+      throw new CandidateEditionError(`the edition pins "${EDITIONS_ROOT_PIN_KEY}": an editions root apart from the data root is not supported by the candidate re-seal`);
+    }
+    const kernelKey = kernelPinKey();
+    const kernelRepo = cachedCheckoutDir(cacheDir, kernelKey, pins[kernelKey]);
+    const sources = join(scratch, 'sources');
+    mkdirSync(sources, { recursive: true });
+    const graph = Object.keys(pins).filter((key) => snapshotPinNamespace(key) === SnapshotPinNamespace.Graph);
+    for (const key of graph) {
+      const target = key === candidate.repo ? candidate.checkoutDir : cachedCheckoutDir(cacheDir, key, pins[key]);
+      if (key !== candidate.repo) {
+        if (!existsSync(target)) {
+          throw new CandidateEditionError(`no cached checkout of ${key} at ${pins[key]} under ${cacheDir}: run fetchPinnedEditionCheckouts first`);
+        }
+        assertCheckoutAt({ dir: target, commit: pins[key], what: `cached ${key}` });
+      }
+      mkdirSync(dirname(join(sources, key)), { recursive: true });
+      symlinkSync(target, join(sources, key));
+    }
+    return {
+      roots: {
+        [WorkspaceRoot.Data]: dataDir,
+        [WorkspaceRoot.Editions]: dataDir,
+        [WorkspaceRoot.Sources]: sources,
+        [WorkspaceRoot.Kernel]: join(kernelRepo, ...KERNEL_PACKAGE_REPO_PATH.split('/')),
+        [WorkspaceRoot.Cache]: join(cacheDir, 'work'),
+      },
+      kernelRepo,
+      kernelKey,
+    };
+  });
+}
+
+/**
+ * The cached data root at the edition's data pin, held to it: its HEAD is the pin, it is clean, and its own
+ * pinRoles name `dataKey` as the data role (so a handle cannot point the resolve at another repository).
+ */
+function cachedDataRoot(cacheDir, dataKey, pins) {
+  if (typeof dataKey !== 'string' || pins[dataKey] === undefined) {
+    throw new CandidateEditionError(`the edition does not pin a data root ${JSON.stringify(dataKey)}; run fetchPinnedEditionCheckouts first`);
+  }
+  const dir = cachedCheckoutDir(cacheDir, dataKey, pins[dataKey]);
+  if (!existsSync(dir)) {
+    throw new CandidateEditionError(`no cached data root ${dataKey} at ${pins[dataKey]} under ${cacheDir}: run fetchPinnedEditionCheckouts first`);
+  }
+  assertCheckoutAt({ dir, commit: pins[dataKey], what: `cached ${dataKey}` });
+  const declared = withWorkspace({ [WorkspaceRoot.Data]: dir }, () => dataPinKey());
+  if (declared !== dataKey) {
+    throw new CandidateEditionError(`the cached data root ${dir} declares its data role as "${declared}", not "${dataKey}"`);
+  }
+  return dir;
+}
+
+/**
+ * Build `dir` in a staging directory beside it and rename it into place only once `build(staging)` succeeded,
+ * so a cached checkout that exists is a complete one: a failed or interrupted run leaves only a staging
+ * directory, which the next run discards.
+ */
+function stageThenRename(dir, build) {
+  const staging = `${dir}.partial-${process.pid}`;
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(dirname(staging), { recursive: true });
+  try {
+    build(staging);
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+  renameSync(staging, dir);
+}
+
+/**
+ * A clone at `commit` under the cache, or the cached one held to it. Network only when absent. `prepare`
+ * (the kernel build) runs in the staging directory, before the rename, so a cached clone is never half-prepared.
+ */
+function ensureCachedClone({ cacheDir, key, commit, url, workspace, env, runGit, prepare }) {
+  const dir = cachedCheckoutDir(cacheDir, key, commit);
+  if (existsSync(dir)) {
+    assertCheckoutAt({ dir, commit, what: `cached ${key}` });
+    return { dir, fetched: false };
+  }
+  stageThenRename(dir, (staging) => {
+    withSourceGitEnv({ name: key, url }, { workspace, env }, (gitEnv) => {
+      shallowCheckout({ runGit, gitEnv, target: staging, url, commit });
+    });
+    assertCheckoutAt({ dir: staging, commit, what: `fetched ${key}` });
+    if (prepare !== undefined) {
+      prepare(staging);
+      assertCheckoutAt({ dir: staging, commit, what: `prepared ${key}` });
+    }
+  });
+  return { dir, fetched: true };
+}
+
+/** Fetch `commits` into a cached checkout, only the ones it does not hold. */
+function ensureCommits({ dir, key, url, commits, workspace, env, runGit }) {
+  const absent = commits.filter((commit) => !hasCommit(dir, commit));
+  if (absent.length === 0) {return 0;}
+  withSourceGitEnv({ name: key, url }, { workspace, env }, (gitEnv) => {
+    for (const commit of absent) {shallowFetch({ runGit, gitEnv, target: dir, commit });}
+  });
+  return absent.length;
+}
+
+/**
+ * THE ONE NETWORK STEP. Every checkout the develop resolve of the pinned edition reads, at the edition's
+ * pins, cached under `cacheDir/checkouts/<pin key>/<commit>`:
+ *
+ *   - the data root, cloned LOCALLY from `dataRootDir` (the caller's own checkout of it at its pin: the data
+ *     root is what declares every other repository and the credential that reads them);
+ *   - the kernel, at its pin, built the way develop-edition.yaml builds it (`buildKernel`);
+ *   - every develop-graph repository but the candidate, plus the extra commits the resolve reads in them
+ *     (platform-service and cross-repo vendored commits, computed with the candidate in place);
+ *   - every declared `sources[]` entry at its pin (external-source-walk.mjs's own cache).
+ *
+ * A warm cache spawns no network git command and no build. Every cached checkout is held to its pin and
+ * must be clean, or the fetch refuses. Credentials follow the data root's `sourceRepositoryUrlPrefix` rule
+ * (git-source-auth.mjs) and are read only from `env`, which the caller passes. Local git commands (the data-root
+ * clone, every HEAD and status check) run with PATH and HOME alone; `buildKernel`'s default inherits the process
+ * environment, as `corepack pnpm` needs it.
+ *
+ * @param {object} request
+ * @param {string} request.tripleDir the pinned develop edition: xema-edition.json and its lock files
+ * @param {string} request.cacheDir absolute, writable; reused across runs
+ * @param {string} request.dataRootDir a checkout of the data root at the edition's data pin
+ * @param {{ repo: string, checkoutDir: string }} request.candidate the candidate repository's pin key and checkout
+ * @param {Record<string, string>} [request.env] the environment credentials are read from (default: none)
+ * @returns {Promise<{ cacheDir: string, dataKey: string, distributionId: string, fetched: string[] }>} the handle
+ *   `resealCandidateEdition` takes; every checkout it names is re-held to its pin when it is used, never trusted
+ */
+export async function fetchPinnedEditionCheckouts({ tripleDir, cacheDir, dataRootDir, candidate, env = {}, runGit = defaultRunGit, buildKernel = defaultBuildKernel }) {
+  const edition = readPinnedEdition(tripleDir);
+  const cache = absoluteDir('cacheDir', cacheDir);
+  mkdirSync(join(cache, 'work'), { recursive: true });
+  const dataSource = absoluteDir('dataRootDir', dataRootDir);
+  const fetched = [];
+  // The data root first: it names the pin roles, the graph and the credential.
+  const dataKey = withWorkspace({ [WorkspaceRoot.Data]: dataSource }, () => dataPinKey());
+  const dataCommit = edition.pins[dataKey];
+  if (dataCommit === undefined) {throw new CandidateEditionError(`the edition does not pin its data root "${dataKey}"`);}
+  const dataDir = cachedCheckoutDir(cache, dataKey, dataCommit);
+  if (existsSync(dataDir)) {
+    assertCheckoutAt({ dir: dataDir, commit: dataCommit, what: `cached ${dataKey}` });
+  } else {
+    assertCheckoutAt({ dir: dataSource, commit: dataCommit, what: `dataRootDir ${dataKey}` });
+    stageThenRename(dataDir, (staging) => {
+      runLocalGit(['clone', '--quiet', '--no-checkout', dataSource, staging]);
+      localGit(staging, ['-c', 'advice.detachedHead=false', 'checkout', '--quiet', '--detach', dataCommit]);
+      assertCheckoutAt({ dir: staging, commit: dataCommit, what: `cloned ${dataKey}` });
+    });
+    fetched.push(dataKey);
+  }
+  const workspace = withWorkspace({ [WorkspaceRoot.Data]: dataDir }, () => {
+    readCandidate(candidate, edition.pins);
+    return editionWorkspaceConfig();
+  });
+  const committedIndex = readStrictJsonFile(join(dataDir, 'runtime-image-source-index.json'));
+  // The kernel, at its pin, from the repository its contract authority names, built once.
+  const kernelKey = withWorkspace({ [WorkspaceRoot.Data]: dataDir }, () => kernelPinKey());
+  const kernelUrl = committedIndex?.contractAuthority?.repositoryUrl;
+  if (typeof kernelUrl !== 'string') {throw new CandidateEditionError(`${dataKey}: runtime-image-source-index.json names no contractAuthority.repositoryUrl`);}
+  const builtKernel = (repoDir) => join(repoDir, ...KERNEL_PACKAGE_REPO_PATH.split('/'), 'dist', 'distribution', 'index.js');
+  const kernel = ensureCachedClone({
+    cacheDir: cache, key: kernelKey, commit: edition.pins[kernelKey], url: kernelUrl, workspace, env, runGit,
+    prepare: (staging) => {
+      buildKernel(staging);
+      if (!existsSync(builtKernel(staging))) {throw new CandidateEditionError(`the ${kernelKey} build produced no ${KERNEL_PACKAGE_REPO_PATH}/dist`);}
+    },
+  });
+  // A cached kernel exists only once its build succeeded (built in staging, renamed after); one without its
+  // build output is not this code's, and is refused rather than rebuilt in place.
+  if (!existsSync(builtKernel(kernel.dir))) {
+    throw new CandidateEditionError(`the cached ${kernelKey} at ${kernel.dir} holds no build output; remove it and fetch again`);
+  }
+  if (kernel.fetched) {fetched.push(kernelKey);}
+  // The graph, with the candidate in place: the plan is the develop graph at the candidate's pins.
+  const read = readCandidate(candidate, edition.pins);
+  const candidatePins = { ...edition.pins, [read.repo]: read.commit };
+  const index = withWorkspace({ [WorkspaceRoot.Data]: dataDir }, () => applyPinSource(committedIndex, snapshotPinSource(candidatePins)));
+  const plan = sourceCheckoutPlan(index, workspace);
+  for (const entry of plan) {
+    if (entry.repo === read.repo) {continue;}
+    if (ensureCachedClone({ cacheDir: cache, key: entry.repo, commit: entry.sourceCommit, url: entry.repositoryUrl, workspace, env, runGit }).fetched) {
+      fetched.push(entry.repo);
+    }
+  }
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-candidate-fetch-'));
+  try {
+    const staged = stageWorkspace({ cacheDir: cache, dataKey, pins: candidatePins, candidate: read, scratch });
+    await withWorkspace(staged.roots, async () => {
+      const extra = new Map();
+      const add = (map) => {
+        for (const [repo, commits] of map) {extra.set(repo, [...new Set([...(extra.get(repo) ?? []), ...[commits].flat()])]);}
+      };
+      add(sourceAxisExtraCommits(plan));
+      add(platformServiceExtraCommits(plan, readStrictJsonFile(platformServiceIndexPath())));
+      const crossRepoOnly = crossRepoVendoredCommits(plan, index, staged.roots[WorkspaceRoot.Sources]);
+      add(crossRepoOnly);
+      for (const entry of plan) {
+        const commits = extra.get(entry.repo) ?? [];
+        if (commits.length === 0) {continue;}
+        if (entry.repo === read.repo) {
+          // The snapshot resolve rebuilds the platform service index AT the candidate commit, so a platform
+          // service's committed commit is never read in the candidate; a cross-repo vendored commit is.
+          const absent = (crossRepoOnly.get(entry.repo) ?? []).filter((commit) => !hasCommit(read.checkoutDir, commit));
+          if (absent.length > 0) {
+            throw new CandidateEditionError(`candidate ${read.repo}: the resolve also reads ${absent.join(', ')}, which its checkout does not hold; fetch them into it`);
+          }
+          continue;
+        }
+        const dir = cachedCheckoutDir(cache, entry.repo, entry.sourceCommit);
+        if (ensureCommits({ dir, key: entry.repo, url: entry.repositoryUrl, commits, workspace, env, runGit }) > 0) {fetched.push(`${entry.repo} (extra commits)`);}
+      }
+      // Every declared source at its pin, in the cache external-source-walk reads (an exact commit is never resolved remotely).
+      const schemas = await loadKernelDistributionSchemas();
+      const pinSource = snapshotPinSource(candidatePins);
+      const composed = composeEdition(schemas.parseDistribution, edition.id, pinSource);
+      for (const source of composed.declaredSources.filter((declared) => declared.kind !== 'oci')) {
+        materializeGitSource({ source: pinnedSource(source, pinSource), cacheRoot: externalSourceCacheDir(), env, workspace });
+      }
+    });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+  return { cacheDir: cache, dataKey, distributionId: edition.id, fetched };
+}
+
+/**
+ * The candidate content record, held to the distribution lock bytes it was written beside AND to the
+ * candidate it records: exactly one entry, `candidate.repo` at `candidate.commit` (the candidate checkout's
+ * HEAD), for the edition `distributionId`. A record for another commit (one in the candidate's history
+ * included), another or a second repository, or another edition is refused.
+ */
+export function parseCandidateContentRecord(value, { distributionLockBytes, distributionId, candidate }) {
+  const keys = ['schema', 'distributionId', 'distributionLockSha256', 'contentCommits'];
+  if (value === null || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join() !== [...keys].sort().join()) {
+    throw new CandidateEditionError(`${CANDIDATE_CONTENT_FILE} must be exactly {${keys.join(', ')}}`);
+  }
+  if (value.schema !== CANDIDATE_CONTENT_SCHEMA) {
+    throw new CandidateEditionError(`${CANDIDATE_CONTENT_FILE}: schema is ${JSON.stringify(value.schema)}, expected ${CANDIDATE_CONTENT_SCHEMA}`);
+  }
+  const digest = sha256Hex(distributionLockBytes);
+  if (value.distributionLockSha256 !== digest) {
+    throw new CandidateEditionError(
+      `${CANDIDATE_CONTENT_FILE} is bound to the distribution lock ${value.distributionLockSha256}, but the lock beside it hashes to ${digest}`,
+    );
+  }
+  if (value.distributionId !== distributionId) {
+    throw new CandidateEditionError(
+      `${CANDIDATE_CONTENT_FILE} records the edition ${JSON.stringify(value.distributionId)}, not ${JSON.stringify(distributionId)}`,
+    );
+  }
+  const commits = value.contentCommits;
+  const entries = commits !== null && typeof commits === 'object' && !Array.isArray(commits) ? Object.entries(commits) : [];
+  if (entries.length !== 1) {
+    throw new CandidateEditionError(
+      `${CANDIDATE_CONTENT_FILE}: contentCommits must hold exactly one entry, the candidate ${candidate.repo}; it holds ${entries.length}`,
+    );
+  }
+  const [[repo, commit]] = entries;
+  if (repo !== candidate.repo) {
+    throw new CandidateEditionError(`${CANDIDATE_CONTENT_FILE} records ${JSON.stringify(repo)}, not the candidate ${candidate.repo}`);
+  }
+  if (commit !== candidate.commit) {
+    throw new CandidateEditionError(
+      `${CANDIDATE_CONTENT_FILE} records ${repo} at ${JSON.stringify(commit)}, but the candidate checkout is at ${candidate.commit}`,
+    );
+  }
+  return new Map(entries);
+}
+
+/**
+ * OFFLINE. Re-seal the pinned develop edition with `candidate.repo` at its checkout's HEAD:
+ *
+ *   distribution lock   the develop resolve's own steps (buildSnapshotInputs, prepareDistributionWithIndex,
+ *                       the bundle-signer, plane-invariant and operation admissions), sealed by the kernel's
+ *                       sealDistributionLock through biome-content.mjs `sealLock`, with the candidate content
+ *                       record as `contentCommits`;
+ *   authorization lock  the develop resolve's composeAuthorizationBase (`fga model test`, XEMA_FGA_CLI);
+ *   images lock         the pinned edition's bytes, unchanged;
+ *   resolved deployment the kernel's resolveUnsplitDeployment over exactly the three lock bytes written.
+ *
+ * Not run, because each reads a registry: the images resolve and seal, the adapter-bundle check and the chart
+ * set. Every refusal throws; nothing is written unless everything passed. `outDir` must not exist yet.
+ *
+ * @param {object} request
+ * @param {string} request.tripleDir the pinned develop edition (as for fetchPinnedEditionCheckouts)
+ * @param {{ cacheDir: string, dataKey: string }} request.checkouts what fetchPinnedEditionCheckouts returned
+ * @param {{ repo: string, checkoutDir: string }} request.candidate
+ * @param {string} request.outDir absolute, absent
+ * @param {{ id: string, runtimeNamespace: string }} request.deployment the deployment the resolved deployment names
+ * @returns {Promise<{ outDir: string, distributionId: string, candidateCommit: string, files: readonly string[] }>}
+ */
+export async function resealCandidateEdition({ tripleDir, checkouts, candidate, outDir, deployment }) {
+  const edition = readPinnedEdition(tripleDir);
+  const cacheDir = absoluteDir('checkouts.cacheDir', checkouts?.cacheDir);
+  const out = absoluteDir('outDir', outDir);
+  if (existsSync(out)) {throw new CandidateEditionError(`outDir ${out} already exists; a candidate triple is written to a fresh directory`);}
+  if (typeof deployment?.id !== 'string' || typeof deployment?.runtimeNamespace !== 'string') {
+    throw new CandidateEditionError('deployment must be { id, runtimeNamespace }: the resolved deployment names both');
+  }
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-candidate-reseal-'));
+  try {
+    const dataDir = cachedDataRoot(cacheDir, checkouts.dataKey, edition.pins);
+    const read = withWorkspace({ [WorkspaceRoot.Data]: dataDir }, () => readCandidate(candidate, edition.pins));
+    const pins = { ...edition.pins, [read.repo]: read.commit };
+    const staged = stageWorkspace({ cacheDir, dataKey: checkouts.dataKey, pins, candidate: read, scratch });
+    assertCheckoutAt({ dir: staged.kernelRepo, commit: pins[staged.kernelKey], what: `cached ${staged.kernelKey}` });
+    const written = await withWorkspace(staged.roots, () => resealStaged({ edition, pins, read, deployment }));
+    mkdirSync(out, { recursive: true });
+    for (const file of CANDIDATE_FILES) {writeFileSync(join(out, file), written[file]);}
+    return { outDir: out, distributionId: edition.id, candidateCommit: read.commit, files: CANDIDATE_FILES };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+
+}
+
+/** The re-seal proper, inside the staged workspace: every step of the develop resolve that reads no registry. */
+async function resealStaged({ edition: pinned, pins, read, deployment }) {
+  const id = pinned.id;
+  const schemas = await loadKernelDistributionSchemas();
+  const inputs = await buildSnapshotInputs({ id, pins, schemas });
+  const { lock, index } = await prepareDistributionWithIndex(id, { inputs });
+  assertLockBundleSigners({ lock, schemas });
+  assertDevelopEditionInvariants({ id, lock, biomeIndex: inputs.biomeIndex, schemas });
+  admitDistributionLock(schemas, lock);
+  const authorizationLock = await composeAuthorizationBase(id, lock, index);
+  if (authorizationLock === null) {
+    throw new CandidateEditionError(`${id}: the pinned kernel ships no authorization composer, but the pinned edition carries an authorization lock`);
+  }
+  const imagesLockBytes = pinned.bytes[EditionLockFile.Images];
+  const imageLock = schemas.parseImageLock(JSON.parse(imagesLockBytes.toString('utf8')));
+  const contentCommits = new Map([[read.repo, read.commit]]);
+  const authority = createPinnedSourceAuthority({ pins: inputs.runtimeImageSourceIndex.repositoryPins });
+  const sealed = await sealLock({
+    schemas,
+    unsealed: lock,
+    imageLock,
+    locate: sourceTreeLocator(externalSourceTrees(lock)),
+    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
+    contentCommits,
+  });
+  const lockBytes = Buffer.from(serializeJson(sealed), 'utf8');
+  const authorizationLockBytes = Buffer.from(serializeJson(authorizationLock), 'utf8');
+  const resolvedBytes = await resolvedDeploymentBytes({ id, deployment, lockBytes, imagesLockBytes, authorizationLockBytes });
+  const record = {
+    schema: CANDIDATE_CONTENT_SCHEMA,
+    distributionId: id,
+    distributionLockSha256: sha256Hex(lockBytes),
+    contentCommits: Object.fromEntries(contentCommits),
+  };
+  return {
+    [EditionLockFile.Distribution]: lockBytes,
+    [EditionLockFile.Images]: imagesLockBytes,
+    [EditionLockFile.Authorization]: authorizationLockBytes,
+    [RESOLVED_DEPLOYMENT_FILE]: resolvedBytes,
+    [CANDIDATE_CONTENT_FILE]: Buffer.from(serializeJson(record), 'utf8'),
+  };
+}
+
+/**
+ * The kernel's unsplit resolved deployment of the three lock bytes. It is written with the library's `serializeJson`:
+ * the kernel's canonical-JSON module is outside the edition protocol's entry modules, and no verifier hashes this file
+ * (verifyResolvedDeployment reads its fields and checks the lock digests it names).
+ */
+async function resolvedDeploymentBytes({ id, deployment, lockBytes, imagesLockBytes, authorizationLockBytes }) {
+  const distribution = await import(`file://${kernelDistPath('distribution', 'index.js')}`);
+  if (typeof distribution.resolveUnsplitDeployment !== 'function') {
+    throw new CandidateEditionError(`${id}: the pinned kernel exports no resolveUnsplitDeployment; it cannot resolve a deployment`);
+  }
+  const { version } = readStrictJsonFile(join(kernelPackageDir(), 'package.json'));
+  const lockSha256 = sha256Hex(lockBytes);
+  const resolved = await distribution.resolveUnsplitDeployment({
+    lockBytes,
+    imagesLockBytes,
+    authorizationLockBytes,
+    deployment: deployment.id,
+    runtimeNamespace: deployment.runtimeNamespace,
+    edition: {
+      version: CANDIDATE_EDITION_VERSION,
+      registry: CANDIDATE_EDITION_REGISTRY,
+      ref: `${CANDIDATE_EDITION_REGISTRY}/candidate-${id}@sha256:${lockSha256}`,
+    },
+    resolverVersion: version,
+  });
+  return Buffer.from(serializeJson(resolved), 'utf8');
+}
+
+/**
+ * OFFLINE. Recompute every biomeContentHash of a candidate triple from the cached checkouts and the candidate,
+ * reading the candidate content record as `contentCommits` when the triple carries one, and refuse a mismatch
+ * (biome-content.mjs `verifyBiomeContentHashes`). A triple without a record is verified as any lock is.
+ */
+export async function verifyCandidateContentHashes({ tripleDir, checkouts, candidate, candidateDir }) {
+  const edition = readPinnedEdition(tripleDir);
+  const cacheDir = absoluteDir('checkouts.cacheDir', checkouts?.cacheDir);
+  const dir = absoluteDir('candidateDir', candidateDir);
+  const lockBytes = readFileSync(join(dir, EditionLockFile.Distribution));
+  const recordPath = join(dir, CANDIDATE_CONTENT_FILE);
+  const dataDir = cachedDataRoot(cacheDir, checkouts.dataKey, edition.pins);
+  const read = withWorkspace({ [WorkspaceRoot.Data]: dataDir }, () => readCandidate(candidate, edition.pins));
+  const contentCommits = existsSync(recordPath)
+    ? parseCandidateContentRecord(readStrictJsonFile(recordPath), {
+      distributionLockBytes: lockBytes,
+      distributionId: edition.id,
+      candidate: { repo: read.repo, commit: read.commit },
+    })
+    : undefined;
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-candidate-verify-'));
+  try {
+    const pins = { ...edition.pins, [read.repo]: read.commit };
+    const staged = stageWorkspace({ cacheDir, dataKey: checkouts.dataKey, pins, candidate: read, scratch });
+    return await withWorkspace(staged.roots, async () => {
+      const schemas = await loadKernelDistributionSchemas();
+      const lock = schemas.parseDistributionLock(JSON.parse(lockBytes.toString('utf8')));
+      const imageLock = schemas.parseImageLock(JSON.parse(readFileSync(join(dir, EditionLockFile.Images), 'utf8')));
+      const index = applyPinSource(readStrictJsonFile(runtimeImageSourceIndexPath()), snapshotPinSource(pins));
+      const authority = createPinnedSourceAuthority({ pins: index.repositoryPins });
+      return verifyBiomeContentHashes({
+        schemas,
+        lock,
+        imageLock,
+        locate: sourceTreeLocator(externalSourceTrees(lock)),
+        vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
+        ...(contentCommits === undefined ? {} : { contentCommits }),
+      });
+    });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}