@xemahq/xema 0.59.1 → 0.60.1

package/edition/candidate-edition.mjs

@@ -1,697 +0,0 @@
-// 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 { carriedDevelopGitBundles } from './develop-git-bundles.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 { GitSourcedBundle, 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 });
-  // A git-sourced biome's OCI bundle is carried from the pinned edition for the same source commit, never re-fetched.
-  const pinnedLock = JSON.parse(pinned.bytes[EditionLockFile.Distribution].toString('utf8'));
-  const { lock, index } = await prepareDistributionWithIndex(id, { inputs: { ...inputs, developGitBundles: carriedDevelopGitBundles(pinnedLock) } });
-  assertLockBundleSigners({ lock, schemas, gitSourcedBundle: GitSourcedBundle.DevelopVerified });
-  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,
-    gitSourcedBundle: GitSourcedBundle.DevelopVerified,
-  });
-  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 }),
-        gitSourcedBundle: GitSourcedBundle.DevelopVerified,
-      });
-    });
-  } finally {
-    rmSync(scratch, { recursive: true, force: true });
-  }
-}