@xemahq/xema 0.59.0 → 0.60.1

package/edition/check-committed-image-evidence.mjs

@@ -1,412 +0,0 @@
-#!/usr/bin/env node
-// ═══════════════════════════════════════════════════════════════════════════
-// IS THE COMMITTED EVIDENCE BUNDLE FOR THIS EXACT PRODUCER INPUT STILL USABLE?
-//
-//   node check-committed-image-evidence.mjs \
-//     --input <producer-input.json> \
-//     --repository-root <absolute-directory> \
-//     [--github-output <path>] [--now <epoch-millis>]
-//
-// WHY THIS EXISTS
-//
-//   Every producing workflow guarded its expensive signing step with
-//
-//       if [ -d "${EVIDENCE_DIR}" ]; then exists=true; fi
-//
-//   and then reported `::notice::… already produced; reusing it`. That step
-//   verified NOTHING about what is on disk — this repository's most-repeated
-//   defect, a check that reports green while executing nothing. Concretely it
-//   let three separate broken states read as "covered":
-//
-//     * a bundle from a PREVIOUS, half-committed run (statement present,
-//       bundle truncated, descriptor index absent);
-//     * a bundle whose statement describes a DIFFERENT subject or a different
-//       source coordinate than the input about to be signed;
-//     * an EXPIRED bundle. Producer evidence carries a hard `expiresAt` that
-//       `image-evidence.mjs assertTimeWindow` enforces at verification, and the
-//       directory-exists guard made expiry UNRECOVERABLE: every re-run of the
-//       producing workflow saw the directory, skipped production, and the
-//       distribution simply stayed undeliverable with a green CI.
-//
-//   So the reuse decision is made HERE, by actually reading the bundle:
-//   reusable ⇔ well-formed AND bound to this exact input AND unexpired with
-//   enough remaining life to be worth keeping. Anything else re-produces.
-//
-// WHAT "BOUND TO THIS INPUT" MEANS (each is a real substitution this catches)
-//
-//   * the descriptor index names exactly the input's subject set;
-//   * every statement parses under the kernel's own
-//     `parseImageProducerStatement` at the input's contract authority;
-//   * statement digests match the descriptor, and the DSSE payload inside the
-//     bundle is byte-identical to the statement (`validateProducedBundle`);
-//   * the statement's artifact digest is the digest this run is evidencing —
-//     the directory is NAMED after that digest, so a mismatch means the tree
-//     was hand-edited or the naming convention moved;
-//   * source identity (repo/path/commit/tree hash) equals the input's.
-//
-// EXIT CODES — the distinction is deliberate
-//
-//   0  a verdict was reached: `reusable=true|false` on stdout / --github-output.
-//      An unusable or absent bundle is a NORMAL outcome; it means "produce".
-//   1  no verdict could be reached: bad arguments, an unreadable repository
-//      root, kernel schemas that will not load. A tool that cannot decide must
-//      never answer "reuse".
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { appendFileSync, readFileSync, statSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
-
-import {
-  WorkspaceRoot,
-  configureEditionWorkspaceFromArgv,
-  dataRoot,
-  isEntryModule,
-} from './edition-workspace.mjs';
-import {
-  evidenceDirectoryForDigest,
-  sha256Digest,
-} from './image-evidence.mjs';
-import { evidenceSubjectKey } from './image-subject-identity.mjs';
-import { loadKernelDistributionSchemas } from './lib.mjs';
-import {
-  assertProducerInput,
-  buildImageSourceStatements,
-  readPinnedContractAuthority,
-  validateProducedBundle,
-} from './produce-image-source-evidence.mjs';
-import { producerStatementMatchesInput } from './producer-evidence-bundle.mjs';
-
-/**
- * Remaining life below which a technically-valid bundle is re-produced anyway.
- *
- * A bundle that expires in ten minutes is not reusable in any meaningful sense:
- * the release, delivery or appliance install that will read it happens after
- * this workflow, not during it. Refusing to hand one forward is what makes the
- * refresh path actually reachable instead of theoretically reachable.
- *
- * Six hours is the smallest window that survives a full re-run of the slowest
- * producing lane (emulated arm64 build + merge + attest) plus the release step
- * that consumes the result, with room to spare.
- */
-export const MIN_REMAINING_TTL_SECONDS = 6 * 60 * 60;
-
-const MAX_EVIDENCE_FILE_BYTES = 4 * 1024 * 1024;
-
-function readBoundedFile(path) {
-  const stat = statSync(path);
-  if (!stat.isFile()) {
-    throw new Error(`${path} is not a regular file`);
-  }
-  if (stat.size > MAX_EVIDENCE_FILE_BYTES) {
-    throw new Error(
-      `${path} is ${stat.size} bytes, over the ${MAX_EVIDENCE_FILE_BYTES}-byte evidence file bound`,
-    );
-  }
-  return readFileSync(path);
-}
-
-/** A descriptor path is repository-relative, without traversal or absolutes. */
-function assertContainedRelativePath(value, label) {
-  if (
-    typeof value !== 'string' ||
-    value.length === 0 ||
-    value.startsWith('/') ||
-    value
-      .split('/')
-      .some((segment) => segment === '' || segment === '.' || segment === '..')
-  ) {
-    throw new Error(`${label} is not a contained repository-relative path`);
-  }
-  return value;
-}
-
-/**
- * The reuse verdict for one producer input.
- *
- * @returns {{ evidenceDirectory: string, reusable: boolean, reason: string }}
- */
-/**
- * The key of an index entry: its subject's evidence identity, which for a composed artifact names the generation, so it is read
- * from the statement the entry points at (the index states only kind and id). An entry whose statement cannot be read keeps
- * `kind\0id`; the unusable statement is reported below.
- */
-export function entryKey(entry, absoluteDirectory) {
-  try {
-    const { predicate } = JSON.parse(
-      readBoundedFile(join(absoluteDirectory, assertContainedRelativePath(entry.evidence.statementPath, 'statementPath'))).toString('utf8'),
-    );
-    return evidenceSubjectKey({
-      kind: entry.subjectKind,
-      id: entry.subjectId,
-      imageRef: predicate.artifact.imageRepository,
-      contentHash: predicate.source.sourceTreeHash,
-    });
-  } catch {
-    return `${entry.subjectKind}\0${entry.subjectId}`;
-  }
-}
-
-const printable = (key) => key.replaceAll('\0', ':');
-
-export async function assessCommittedEvidence({
-  input,
-  repositoryRoot,
-  schemas,
-  expectedContractAuthority,
-  now = Date.now(),
-}) {
-  // The input is validated FIRST and unconditionally: a verdict about the
-  // committed tree is meaningless if the thing it is compared against is not
-  // itself a well-formed producer input.
-  assertProducerInput(input, expectedContractAuthority);
-  const subjects = input.subjects;
-  const digests = new Set(subjects.map((subject) => subject.manifestDigest));
-  if (digests.size !== 1) {
-    throw new Error(
-      'a producer input must evidence exactly one manifest digest; the ' +
-        `committed evidence tree is keyed by it (got ${[...digests].join(', ')})`,
-    );
-  }
-  const evidenceDirectory = evidenceDirectoryForDigest([...digests][0]);
-  const absoluteDirectory = join(repositoryRoot, evidenceDirectory);
-
-  const unusable = (reason) => ({ evidenceDirectory, reusable: false, reason });
-
-  let stat;
-  try {
-    stat = statSync(absoluteDirectory);
-  } catch {
-    return unusable('no evidence has been committed for this digest yet');
-  }
-  if (!stat.isDirectory()) {
-    return unusable(`${evidenceDirectory} exists but is not a directory`);
-  }
-
-  let indexDocument;
-  try {
-    indexDocument = JSON.parse(
-      readBoundedFile(join(absoluteDirectory, 'producer-evidence.json')).toString(
-        'utf8',
-      ),
-    );
-  } catch (error) {
-    return unusable(
-      `producer-evidence.json is missing or unreadable: ${error.message}`,
-    );
-  }
-  if (
-    indexDocument?.schemaVersion !== 1 ||
-    !Array.isArray(indexDocument.producerEvidence)
-  ) {
-    return unusable('producer-evidence.json is not a schemaVersion 1 index');
-  }
-
-  // The expected statements are REBUILT from the input, so the comparison is
-  // against exactly what a fresh production would sign — not against a
-  // hand-written expectation that could drift from the producer.
-  let expectedStatements;
-  try {
-    expectedStatements = buildImageSourceStatements(input, schemas, expectedContractAuthority);
-  } catch (error) {
-    throw new Error(
-      `the producer input does not build a valid statement set: ${error.message}`,
-    );
-  }
-  const expectedByKey = new Map(
-    expectedStatements.map((statement) => [
-      evidenceSubjectKey({
-        kind: statement.predicate.source.kind,
-        id: statement.predicate.source.id,
-        imageRef: statement.predicate.artifact.imageRepository,
-        contentHash: statement.predicate.source.sourceTreeHash,
-      }),
-      statement,
-    ]),
-  );
-
-  const seen = new Set();
-  for (const entry of indexDocument.producerEvidence) {
-    if (entry === null || typeof entry !== 'object') {
-      return unusable('producer-evidence.json carries a non-object entry');
-    }
-    const key = entryKey(entry, absoluteDirectory);
-    if (seen.has(key)) {
-      return unusable(`producer-evidence.json duplicates subject ${printable(key)}`);
-    }
-    seen.add(key);
-    const expected = expectedByKey.get(key);
-    if (expected === undefined) {
-      return unusable(
-        `committed evidence carries subject ${printable(key)}, which this input does not evidence`,
-      );
-    }
-    const descriptor = entry.evidence;
-    if (descriptor === null || typeof descriptor !== 'object') {
-      return unusable(`subject ${printable(key)} has no evidence descriptor`);
-    }
-    let statementBytes;
-    let bundleBytes;
-    try {
-      statementBytes = readBoundedFile(
-        join(
-          absoluteDirectory,
-          assertContainedRelativePath(
-            descriptor.statementPath,
-            `subject ${printable(key)} statementPath`,
-          ),
-        ),
-      );
-      bundleBytes = readBoundedFile(
-        join(
-          absoluteDirectory,
-          assertContainedRelativePath(
-            descriptor.bundlePath,
-            `subject ${printable(key)} bundlePath`,
-          ),
-        ),
-      );
-    } catch (error) {
-      return unusable(`subject ${printable(key)} artifacts are unreadable: ${error.message}`);
-    }
-    if (
-      sha256Digest(statementBytes) !== descriptor.statementDigest ||
-      sha256Digest(bundleBytes) !== descriptor.bundleDigest
-    ) {
-      return unusable(
-        `subject ${printable(key)} artifacts do not match the digests producer-evidence.json records`,
-      );
-    }
-    try {
-      validateProducedBundle(statementBytes, bundleBytes);
-    } catch (error) {
-      return unusable(`subject ${printable(key)} bundle is malformed: ${error.message}`);
-    }
-    let committed;
-    try {
-      committed = schemas.parseImageProducerStatement(
-        JSON.parse(statementBytes.toString('utf8')),
-      );
-    } catch (error) {
-      return unusable(
-        `subject ${printable(key)} statement does not parse under the kernel schema: ${error.message}`,
-      );
-    }
-    // producerRun is deliberately fresh on every execution (run id, attempt,
-    // nonce and validity window). Requiring byte equality with a freshly built
-    // statement made every retry look stale and caused the evidence commit
-    // storm. Compare the immutable authority/source/build/artifact binding;
-    // validate the existing run's own signature and lifetime independently.
-    if (!producerStatementMatchesInput(committed, expected)) {
-      return unusable(
-        `subject ${printable(key)} committed statement is not bound to this producer input ` +
-          '(authority, source, build, artifact or platform set changed)',
-      );
-    }
-    const expiresAt = Date.parse(committed.predicate.producerRun.expiresAt);
-    if (!Number.isFinite(expiresAt)) {
-      return unusable(`subject ${printable(key)} statement has an unreadable expiresAt`);
-    }
-    const remainingSeconds = Math.floor((expiresAt - now) / 1000);
-    if (remainingSeconds <= 0) {
-      return unusable(
-        `subject ${printable(key)} evidence EXPIRED at ${committed.predicate.producerRun.expiresAt} — ` +
-          'it can never verify again and must be re-produced',
-      );
-    }
-    if (remainingSeconds < MIN_REMAINING_TTL_SECONDS) {
-      return unusable(
-        `subject ${printable(key)} evidence expires in ${remainingSeconds}s, under the ` +
-          `${MIN_REMAINING_TTL_SECONDS}s reuse floor — refreshing it now`,
-      );
-    }
-  }
-
-  const missing = [...expectedByKey.keys()].filter((key) => !seen.has(key));
-  if (missing.length > 0) {
-    return unusable(
-      `committed evidence omits subject(s) ${missing.join(', ')} that this input evidences`,
-    );
-  }
-
-  return {
-    evidenceDirectory,
-    reusable: true,
-    reason:
-      `verified ${seen.size} committed subject bundle(s): well-formed, bound to ` +
-      'this exact producer input, and unexpired',
-  };
-}
-
-function requireValue(flags, name) {
-  const value = flags.get(name);
-  if (value === undefined) {
-    throw new Error(`--${name} is required`);
-  }
-  return value;
-}
-
-async function main() {
-  const args = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
-    WorkspaceRoot.Data,
-    WorkspaceRoot.Kernel,
-  ]);
-  const flags = new Map();
-  for (let index = 0; index < args.length; index += 2) {
-    const flag = args[index];
-    if (!flag.startsWith('--')) {
-      throw new Error(`unexpected argument "${flag}"`);
-    }
-    const name = flag.slice(2);
-    const value = args[index + 1];
-    if (value === undefined || value.startsWith('--')) {
-      throw new Error(`--${name} requires a value`);
-    }
-    if (flags.has(name)) {
-      throw new Error(`--${name} was given twice`);
-    }
-    flags.set(name, value);
-  }
-  for (const name of flags.keys()) {
-    if (!['input', 'repository-root', 'github-output', 'now'].includes(name)) {
-      throw new Error(`unknown option "--${name}"`);
-    }
-  }
-  const repositoryRoot = resolve(requireValue(flags, 'repository-root'));
-  if (!isAbsolute(repositoryRoot) || !statSync(repositoryRoot).isDirectory()) {
-    throw new Error('--repository-root must be an absolute directory');
-  }
-  const input = JSON.parse(readFileSync(resolve(requireValue(flags, 'input')), 'utf8'));
-  const now = flags.has('now') ? Number(flags.get('now')) : Date.now();
-  if (!Number.isSafeInteger(now) || now <= 0) {
-    throw new Error('--now must be a positive epoch-millisecond integer');
-  }
-  const schemas = await loadKernelDistributionSchemas();
-  const verdict = await assessCommittedEvidence({
-    input,
-    repositoryRoot,
-    schemas,
-    expectedContractAuthority: readPinnedContractAuthority({ dataRoot: dataRoot(), schemas }),
-    now,
-  });
-  const line = verdict.reusable
-    ? `[check-committed-image-evidence] REUSE ${verdict.evidenceDirectory}: ${verdict.reason}`
-    : `[check-committed-image-evidence] PRODUCE ${verdict.evidenceDirectory}: ${verdict.reason}`;
-  console.log(line);
-  const githubOutput = flags.get('github-output');
-  if (githubOutput !== undefined) {
-    appendFileSync(
-      githubOutput,
-      `reusable=${verdict.reusable}\n` +
-        `evidence-directory=${verdict.evidenceDirectory}\n` +
-        `reason=${verdict.reason.replaceAll('\n', ' ')}\n`,
-      'utf8',
-    );
-  }
-}
-
-if (isEntryModule(import.meta.url)) {
-  main().catch((error) => {
-    console.error(`[check-committed-image-evidence] ${error.message}`);
-    process.exitCode = 1;
-  });
-}

package/edition/checkout-indexed-source-repositories.mjs

@@ -1,283 +0,0 @@
-#!/usr/bin/env node
-
-import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-
-import { readCrossRepoBuildInputsRecord, splitCrossRepoInputKey } from './cross-repo-build-inputs.mjs';
-import { discoverDistributionIds } from './distribution-paths.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import { readEditionSourcePins } from './edition-source-pins.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromProcess, configuredWorkspace, editionsRoot, isEntryModule, platformServiceIndexPath, runtimeImageSourceIndexPath, sourcesRoot } from './edition-workspace.mjs';
-import { holdSource, withSourceGitEnv } from './git-source-auth.mjs';
-import { applyPinSource, snapshotPinSource } from './pin-source.mjs';
-import { shallowCheckout, shallowFetch } from './shallow-checkout.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
-
-const REPO_PATH = /^(repos|submodules)\/([a-z0-9][a-z0-9-]*)$/;
-const SHA = /^[a-f0-9]{40}$/;
-
-export function sourceCheckoutPlan(index, { sourceRepositoryUrlPrefix }) {
-  if (!Array.isArray(index?.repositoryPins) || index.repositoryPins.length === 0) {
-    throw new Error('runtime image source index declares no repositoryPins');
-  }
-  const seen = new Set();
-  return index.repositoryPins.map((pin) => {
-    const match = REPO_PATH.exec(String(pin?.repo ?? ''));
-    if (!match) {throw new Error(`invalid repository checkout path ${JSON.stringify(pin?.repo)}`);}
-    if (seen.has(pin.repo)) {throw new Error(`duplicate repository pin ${pin.repo}`);}
-    seen.add(pin.repo);
-    const expectedUrl = `${sourceRepositoryUrlPrefix}${match[2]}.git`;
-    const suffixlessExpectedUrl = expectedUrl.slice(0, -4);
-    if (pin.repositoryUrl !== expectedUrl && pin.repositoryUrl !== suffixlessExpectedUrl) {
-      throw new Error(
-        `${pin.repo} repositoryUrl must be ${expectedUrl} (the equivalent suffixless GitHub URL is also accepted); got ${pin.repositoryUrl}`,
-      );
-    }
-    if (!SHA.test(String(pin.sourceCommit ?? ''))) {
-      throw new Error(`${pin.repo} sourceCommit is not exact lowercase 40-hex`);
-    }
-    if (!SHA.test(String(pin.vendoredSourceCommit ?? ''))) {
-      throw new Error(`${pin.repo} vendoredSourceCommit is not exact lowercase 40-hex`);
-    }
-    return Object.freeze({
-      repo: pin.repo,
-      repositoryUrl: pin.repositoryUrl,
-      sourceCommit: pin.sourceCommit,
-      vendoredSourceCommit: pin.vendoredSourceCommit,
-    });
-  });
-}
-
-function git(args, env) {
-  execFileSync('git', args, { env, stdio: 'inherit' });
-}
-
-/**
- * The SOURCE-axis commit a checkout must also hold when it differs from the
- * image-axis `sourceCommit`: dist-check, publish-editions, seal-image-digests and
- * store-publish read vendored and content-only bytes at `vendoredSourceCommit`.
- * Maps repo to that commit; repositories whose axes are equal are absent.
- */
-export function sourceAxisExtraCommits(plan) {
-  return new Map(
-    plan.filter((entry) => entry.vendoredSourceCommit !== entry.sourceCommit).map((entry) => [entry.repo, entry.vendoredSourceCommit]),
-  );
-}
-
-/**
- * The extra commits each checkout must also hold: resolve reads every platform
- * service's manifest at the `sourceCommit` platform-service-index.json pins, and
- * that commit may differ from the repository's own pin. Maps repo to the
- * distinct such commits (excluding the pinned one). A platform service whose
- * repository has no pin is refused: there is no checkout to fetch into.
- */
-export function platformServiceExtraCommits(plan, platformServiceIndex) {
-  if (!Array.isArray(platformServiceIndex?.services)) {
-    throw new Error('platform-service-index.json declares no services array');
-  }
-  const pinned = new Map(plan.map((entry) => [entry.repo, entry.sourceCommit]));
-  const extra = new Map();
-  for (const service of platformServiceIndex.services) {
-    if (!pinned.has(service?.repo)) {
-      throw new Error(
-        `platform service "${service?.name}" names repository ${JSON.stringify(service?.repo)}, which has no repository pin in the runtime image source index`,
-      );
-    }
-    if (!SHA.test(String(service.sourceCommit ?? ''))) {
-      throw new Error(`platform service "${service.name}" sourceCommit is not exact lowercase 40-hex`);
-    }
-    if (service.sourceCommit === pinned.get(service.repo)) {continue;}
-    if (!extra.has(service.repo)) {extra.set(service.repo, new Set());}
-    extra.get(service.repo).add(service.sourceCommit);
-  }
-  return new Map([...extra].map(([repo, commits]) => [repo, [...commits]]));
-}
-
-/**
- * The commits each checkout must also hold for the editions that hold a
- * repository (`sourcePins`): per repository, the distinct held commits other
- * than the repository's own pin. A held repository is also one whose published
- * history is needed, so containment in `origin/main` can be shown: those repos
- * are in the returned map even when every held commit is the pin itself.
- * A held repository without a repository pin is refused: there is no checkout
- * to fetch into.
- *
- * @param {{ repo: string, sourceCommit: string }[]} plan
- * @param {Map<string, { repo: string, ref: string }[]>} sourcePinsByEdition
- * @returns {Map<string, string[]>}
- */
-export function editionHeldCommits(plan, sourcePinsByEdition) {
-  const pinned = new Map(plan.map((entry) => [entry.repo, entry.sourceCommit]));
-  const held = new Map();
-  for (const [id, sourcePins] of sourcePinsByEdition) {
-    for (const { repo, ref } of sourcePins) {
-      if (!pinned.has(repo)) {
-        throw new Error(`edition "${id}" holds ${repo}, which has no repository pin in the runtime image source index`);
-      }
-      if (!held.has(repo)) {held.set(repo, new Set());}
-      if (ref !== pinned.get(repo)) {held.get(repo).add(ref);}
-    }
-  }
-  return new Map([...held].map(([repo, commits]) => [repo, [...commits]]));
-}
-
-/**
- * The commits each checkout must also hold because a consumer's cross-repo
- * build-input record vendors bytes from them. The resolve hashes those paths at
- * the record's commit (`resolveCrossRepoVendoredInputs`), and that commit lags
- * or leads the source repository's own pin. The record is read AT THE
- * CONSUMER'S PIN, by the same reader the resolve uses, from the consumer's
- * checkout under `workspaceRoot` (so every repository must already be checked
- * out). Maps source repo to the distinct such commits, excluding the commits
- * the checkout already holds. A consumer or source repository without a
- * repository pin is refused: there is no checkout to read or fetch into.
- *
- * @param {{ repo: string, sourceCommit: string, vendoredSourceCommit: string }[]} plan
- * @returns {Map<string, string[]>}
- */
-export function crossRepoVendoredCommits(plan, index, workspaceRoot) {
-  const pins = new Map(plan.map((entry) => [entry.repo, entry]));
-  const consumers = [...new Set((index.crossRepoBuildInputs ?? []).map((input) => input.consumerRepo))].sort();
-  const extra = new Map();
-  for (const consumerRepo of consumers) {
-    const consumer = pins.get(consumerRepo);
-    if (!consumer) {
-      throw new Error(`cross-repo build inputs name consumer ${JSON.stringify(consumerRepo)}, which has no repository pin in the runtime image source index`);
-    }
-    const record = readCrossRepoBuildInputsRecord({
-      consumerRepo,
-      consumerRepoDir: resolve(workspaceRoot, consumerRepo),
-      consumerCommit: consumer.sourceCommit,
-    });
-    for (const [key, commit] of record) {
-      const [sourceRepo] = splitCrossRepoInputKey(key);
-      const source = pins.get(sourceRepo);
-      if (!source) {
-        throw new Error(
-          `${consumerRepo} at ${consumer.sourceCommit} vendors from ${JSON.stringify(sourceRepo)}, which has no repository pin in the runtime image source index`,
-        );
-      }
-      if (!SHA.test(String(commit ?? ''))) {
-        throw new Error(`${consumerRepo} at ${consumer.sourceCommit} vendors from ${sourceRepo} at a sourceCommit that is not exact lowercase 40-hex`);
-      }
-      if (commit === source.sourceCommit || commit === source.vendoredSourceCommit) {continue;}
-      if (!extra.has(sourceRepo)) {extra.set(sourceRepo, new Set());}
-      extra.get(sourceRepo).add(commit);
-    }
-  }
-  return new Map([...extra].map(([repo, commits]) => [repo, [...commits].sort()]));
-}
-
-/** The `sourcePins` of every edition under the configured editions root. */
-export function readEditionsSourcePins() {
-  return new Map(
-    discoverDistributionIds(editionsRoot())
-      .map((id) => [id, readEditionSourcePins(id)])
-      .filter(([, sourcePins]) => sourcePins.length > 0),
-  );
-}
-
-/**
- * Second pass, once every repository sits at its pin: fetch the commits the
- * consumers' cross-repo build-input records vendor from.
- */
-export function fetchCrossRepoVendoredCommits({ workspaceRoot, plan, index, workspace, env, runGit }) {
-  const vendored = crossRepoVendoredCommits(plan, index, workspaceRoot);
-  for (const entry of plan) {
-    const commits = vendored.get(entry.repo);
-    if (!commits) {continue;}
-    withSourceGitEnv({ name: entry.repo, url: entry.repositoryUrl }, { workspace, env }, (gitEnv) => {
-      for (const commit of commits) {
-        shallowFetch({ runGit, gitEnv, target: resolve(workspaceRoot, entry.repo), commit });
-        console.log(`[source-checkout] ${entry.repo} also holds cross-repo vendored commit ${commit}`);
-      }
-    });
-  }
-}
-
-export function checkoutIndexedSources({ workspaceRoot, index, platformServiceIndex, editionSourcePins = new Map(), env = process.env, runGit = git }) {
-  if (!workspaceRoot) {throw new Error('workspaceRoot is required');}
-  const workspace = editionWorkspaceConfig();
-  const plan = sourceCheckoutPlan(index, workspace);
-  const extraCommits = platformServiceExtraCommits(plan, platformServiceIndex);
-  const sourceAxisCommits = sourceAxisExtraCommits(plan);
-  const heldCommits = editionHeldCommits(plan, editionSourcePins);
-  for (const entry of plan) {holdSource({ name: entry.repo, url: entry.repositoryUrl }, workspace, env);}
-  for (const entry of plan) {
-    const target = resolve(workspaceRoot, entry.repo);
-    if (existsSync(target)) {
-      throw new Error(`${entry.repo} target already exists; refusing to reuse an unverified checkout`);
-    }
-    withSourceGitEnv({ name: entry.repo, url: entry.repositoryUrl }, { workspace, env }, (gitEnv) => {
-      mkdirSync(dirname(target), { recursive: true });
-      shallowCheckout({ runGit, gitEnv, target, url: entry.repositoryUrl, commit: entry.sourceCommit });
-      const actual = execFileSync('git', ['-C', target, 'rev-parse', 'HEAD'], {
-        env: gitEnv,
-        encoding: 'utf8',
-      }).trim();
-      if (actual !== entry.sourceCommit) {
-        throw new Error(`${entry.repo} resolved ${actual}, expected ${entry.sourceCommit}`);
-      }
-      if (sourceAxisCommits.has(entry.repo)) {
-        const commit = sourceAxisCommits.get(entry.repo);
-        shallowFetch({ runGit, gitEnv, target, commit });
-        console.log(`[source-checkout] ${entry.repo} also holds source-axis commit ${commit}`);
-      }
-      for (const commit of extraCommits.get(entry.repo) ?? []) {
-        shallowFetch({ runGit, gitEnv, target, commit });
-        console.log(`[source-checkout] ${entry.repo} also holds platform-service commit ${commit}`);
-      }
-      // A repository an edition holds: its main history (containment in origin/main is checked from it,
-      // with no depth), then each held commit.
-      if (heldCommits.has(entry.repo)) {
-        runGit(['-C', target, 'fetch', '--quiet', 'origin', '+refs/heads/main:refs/remotes/origin/main'], gitEnv);
-        for (const commit of heldCommits.get(entry.repo)) {
-          shallowFetch({ runGit, gitEnv, target, commit });
-          console.log(`[source-checkout] ${entry.repo} also holds edition-held commit ${commit}`);
-        }
-      }
-    });
-    console.log(`[source-checkout] ${entry.repo} @ ${entry.sourceCommit}`);
-  }
-  fetchCrossRepoVendoredCommits({ workspaceRoot, plan, index, workspace, env, runGit });
-  return plan.length;
-}
-
-const SNAPSHOT_PINS_FLAG = '--snapshot-pins';
-
-/**
- * `--snapshot-pins <file>` is the only argument: with it, the plan is the
- * develop graph (the data root's firstPartySources) at that snapshot (the
- * develop edition's frozen pins), never the committed index's repositoryPins;
- * without it, the committed index untouched.
- */
-export function indexForCheckout(committedIndex, argv) {
-  if (argv.length === 0) {return committedIndex;}
-  if (argv[0] !== SNAPSHOT_PINS_FLAG || argv.length !== 2 || argv[1].startsWith('--')) {
-    throw new Error(`usage: checkout-indexed-source-repositories.mjs [${SNAPSHOT_PINS_FLAG} <pins.json>]`);
-  }
-  return applyPinSource(committedIndex, snapshotPinSource(readStrictJsonFile(argv[1])));
-}
-
-if (isEntryModule(import.meta.url)) {
-  try {
-    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources]);
-    // `--editions-root` is optional: given, the plan also holds every edition's held commits.
-    const withEditions = configuredWorkspace()[WorkspaceRoot.Editions] !== undefined;
-    if (withEditions && process.argv.length > 2) {
-      throw new Error('--editions-root and --snapshot-pins do not combine: a snapshot replaces every pin, so no edition holds a repository');
-    }
-    const index = indexForCheckout(JSON.parse(readFileSync(runtimeImageSourceIndexPath(), 'utf8')), process.argv.slice(2));
-    const count = checkoutIndexedSources({
-      workspaceRoot: sourcesRoot(),
-      index,
-      editionSourcePins: withEditions ? readEditionsSourcePins() : new Map(),
-      platformServiceIndex: JSON.parse(readFileSync(platformServiceIndexPath(), 'utf8')),
-    });
-    console.log(`[source-checkout] materialized ${count} indexed repositories at exact commits`);
-  } catch (error) {
-    console.error(`[source-checkout] ${error.message}`);
-    process.exit(1);
-  }
-}