@xemahq/xema 0.59.0 → 0.60.1

package/edition/source-authority.mjs

@@ -1,713 +0,0 @@
-import { execFileSync } from 'node:child_process';
-import {
-  existsSync,
-  mkdtempSync,
-  readFileSync,
-  realpathSync,
-  rmSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, relative, resolve, sep } from 'node:path';
-
-import { BUILD_LEDGER_FILE, readBuildLedger } from './build-ledger.mjs';
-import { dataRoot, sourcesRoot } from './edition-workspace.mjs';
-
-export const PUBLISHED_SOURCE_REF = 'refs/remotes/origin/main';
-
-export const DistributionSourceMode = Object.freeze({
-  Published: 'published',
-  Workspace: 'workspace',
-});
-
-function git(directory, args, options = {}) {
-  return execFileSync('git', ['-C', directory, ...args], {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    ...options,
-  }).trim();
-}
-
-function exactCommit(directory, ref, label) {
-  try {
-    return git(directory, ['rev-parse', '--verify', `${ref}^{commit}`]);
-  } catch {
-    throw new Error(`${label} has no exact Git commit at ${ref}`);
-  }
-}
-
-/**
- * How far back to look for a built commit before refusing. Generous on purpose:
- * the fleet commits 150-353 times a day and builds 4-12 times, so the newest
- * built commit is routinely dozens of commits behind the tip.
- */
-const BUILT_COMMIT_SEARCH_LIMIT = 500;
-
-/**
- * Every commit this repository has PUBLISHED AN IMAGE FROM, read out of the
- * committed evidence tree.
- *
- * `predicate.source.sourceCommit` in each signed in-toto statement records the
- * exact commit its image was built from. That is a fact in git, at the ref being
- * resolved — no network, no registry credential, no clock. Keeping this resolver
- * pure-git is deliberate: it decides what every distribution lock names, so a
- * network dependency here would make the whole release plane fail differently
- * depending on whether ghcr answered.
- *
- * A repository with NO evidence tree publishes no images (it contributes
- * vendored content only, like xema-connectors). For those the tip is the right
- * answer and always was.
- */
-/**
- * The committed projection of "which commits of this repository have a
- * published image", written by `project-build-ledger.mjs` from the registry's
- * own tags.
- *
- * WHY A LEDGER AND NOT THE REGISTRY DIRECTLY. This resolver decides what every
- * distribution lock names, and the README states the property that depends on
- * it: locks contain only immutable inputs, so two runs over the same sources
- * produce byte-identical CONTENT and an identical `inputHash`.
- *
- * That sentence used to read "byte-identical files", and measured over two full
- * producer runs on 2026-09-06 it is false by exactly one field: every
- * `distribution.lock.json` carries a wall-clock `resolvedAt`, so all eight
- * differ on every run while their content and `inputHash` are stable, and
- * `images.lock.json` and the three indexes are byte-identical. The property
- * this paragraph is defending is unaffected — `resolvedAt` is provenance and
- * feeds no hash — but a determinism claim that a single `diff` disproves is
- * one nobody trusts the second time, so it is stated precisely instead.
- *
- * A live registry read would make lock
- * generation depend on registry state at that instant and on the token's
- * package visibility — the same sources would resolve differently on Tuesday
- * and Thursday, and differently again for a different credential. A committed
- * ledger is addressed by a ref, so it is part of "the same sources". It also
- * keeps this path pure-git, which is what lets it run with no network at all.
- *
- * WHY NOT THE EVIDENCE TREE ALONE. It was the only source until 2026-09-02, and
- * four of the five producing repositories had stopped writing it on 2026-08-25
- * when they moved to publishing OCI referrers — a change whose commit message
- * says nothing about evidence. So the reader and the producers spoke different
- * media, silently: measured that day, `xema-cultivars` resolved to an 2026-08-25
- * commit 153 behind its tip, and the tip WAS built and tagged in the registry.
- * A pin frozen eight days in the past is what kept a fix for a production
- * crashloop out of every image built from it.
- */
-export { BUILD_LEDGER_FILE };
-
-/**
- * Read the committed ledger. A caller that resolves many repositories should
- * read it ONCE and pass it in — the parameter exists for that, not for tests.
- *
- * A malformed ledger THROWS rather than degrading to "no builds recorded":
- * degrading would silently re-pin every repository to its bare tip, which is
- * precisely the defect the ledger exists to prevent. An ABSENT ledger is a
- * different fact and is allowed — it means this checkout has not projected one
- * yet, and the evidence tree still answers.
- */
-export function loadBuildLedger(
-  distributionsDir = dataRoot(),
-) {
-  const ledger = readBuildLedger(distributionsDir);
-  if (ledger === null) {return null;}
-  return Object.fromEntries(
-    Object.entries(ledger.repositories).map(([repo, entry]) => [repo, entry.commits]),
-  );
-}
-
-/**
- * The committed record of which commit each source repository is pinned at.
- *
- * WHY THIS IS THE AUTHORITY AND NOT A CACHE — the argument is
- * {@link createPinnedSourceAuthority}'s and is not repeated here. What this
- * function adds is that the record is reachable WITHOUT `lib.mjs`, so a builder
- * can read it before anything that needs the kernel dist or the aggregator
- * layout, and so this module keeps its one dependency rule: `node:` builtins
- * only, resolvable from a bare checkout with no install.
- *
- * `runtime-image-source-index.json` OWNS these pins — it is the one artifact
- * whose job is to decide them. Every other derived artifact READS them. That is
- * the whole of "one authority": the decider resolves the world, and the
- * consumers resolve the decider.
- *
- * A MISSING or MALFORMED index THROWS rather than degrading to "no pins
- * recorded". Degrading would silently re-resolve every repository from its tip,
- * which is precisely the defect the pins exist to prevent — and it would do it
- * in the one situation nobody is watching, a checkout where the file failed to
- * read. `loadBuildLedger` takes the same posture for the same reason, and
- * differs on the ABSENT case only because an absent ledger is a real state
- * (this checkout has not projected one) while an absent pin index is not: no
- * edition can resolve without it.
- */
-export const RUNTIME_IMAGE_SOURCE_INDEX_FILE = 'runtime-image-source-index.json';
-
-export function committedRepositoryPins(
-  distributionsDir = dataRoot(),
-) {
-  const path = join(distributionsDir, RUNTIME_IMAGE_SOURCE_INDEX_FILE);
-  let raw;
-  try {
-    raw = JSON.parse(readFileSync(path, 'utf8'));
-  } catch (error) {
-    throw new Error(
-      `Cannot read the committed source pins from ${path}: ${error.message}. ` +
-        `Every derived artifact in this plane resolves each repository's commit ` +
-        `through that record; there is no fallback to a live resolution, because ` +
-        `falling back is how one repository's refresh silently re-pins every other.`,
-    );
-  }
-  const pins = raw?.repositoryPins;
-  if (!Array.isArray(pins) || pins.length === 0) {
-    throw new Error(
-      `${RUNTIME_IMAGE_SOURCE_INDEX_FILE} declares no repositoryPins`,
-    );
-  }
-  return pins;
-}
-
-let defaultLedger;
-
-function ledgerCommits(repo, ledger) {
-  let repositories = ledger;
-  if (repositories === undefined) {
-    if (defaultLedger === undefined) {defaultLedger = loadBuildLedger();}
-    repositories = defaultLedger;
-  }
-  if (repositories === null) {return null;}
-  const commits = repositories[repo];
-  return Array.isArray(commits) && commits.length > 0 ? commits : null;
-}
-
-/**
- * Every commit this repository has published an image from, as the UNION of the
- * two records of that one fact: the committed evidence tree and the build
- * ledger. Union rather than precedence, because neither can produce a false
- * positive — each is a record that a build actually happened — while either
- * alone has been measured missing whole repositories.
- */
-export function builtCommits(directory, ref, repo, ledger) {
-  const fromTree = evidenceTreeCommits(directory, ref);
-  const fromLedger = ledgerCommits(repo, ledger);
-  // Null from BOTH means neither record has ever heard of this repository, so
-  // it publishes no images and its tip is right. An EMPTY union is a different
-  // fact — something recorded this repository and named no usable commit — and
-  // it must reach the refusal below rather than be read as "publishes nothing".
-  // Collapsing the two would silently re-pin to the bare tip, which is the one
-  // outcome this whole function exists to prevent.
-  if (fromTree === null && fromLedger === null) {return null;}
-  const union = new Set(fromTree ?? []);
-  for (const commit of fromLedger ?? []) {
-    if (/^[0-9a-f]{40}$/u.test(commit)) {union.add(commit);}
-  }
-  return union;
-}
-
-function evidenceTreeCommits(directory, ref) {
-  let listing;
-  try {
-    listing = git(directory, ['ls-tree', '-r', '--name-only', ref, 'evidence/'], {
-      maxBuffer: 64 * 1024 * 1024,
-    });
-  } catch {
-    return null;
-  }
-  const statements = listing
-    .split('\n')
-    .filter((file) => /statements\/[^/]+\.json$/u.test(file));
-  if (statements.length === 0) {return null;}
-
-  const commits = new Set();
-  for (const file of statements) {
-    let statement;
-    try {
-      statement = JSON.parse(
-        git(directory, ['show', `${ref}:${file}`], { maxBuffer: 16 * 1024 * 1024 }),
-      );
-    } catch {
-      continue;
-    }
-    const commit = statement?.predicate?.source?.sourceCommit;
-    if (typeof commit === 'string' && /^[0-9a-f]{40}$/u.test(commit)) {
-      commits.add(commit);
-    }
-  }
-  return commits.size > 0 ? commits : null;
-}
-
-/**
- * Resolve the immutable release source without consulting local HEAD.
- *
- * THIS RETURNS THE NEWEST *BUILT* COMMIT, NOT THE TIP, and the difference is the
- * whole point.
- *
- * It returned `refs/remotes/origin/main` verbatim until 2026-09-01, with nothing
- * checking that anything had ever been built there. Measured that day against
- * the last twelve `xema-base` commits, probing ghcr for a published `:<sha>`
- * tag: ONE had an image, and that one only because it had been hand-dispatched.
- * Builds run 4-12 a day against 150-353 commits, so an arbitrary tip is almost
- * never buildable — most of `main` is `evidence(base)` receipts, which are
- * authored by `github-actions[bot]` and therefore get no CI run under GitHub's
- * anti-recursion rule, hence no `workflow_run`, hence no build.
- *
- * The consequence was not subtle. A re-pin that landed on an unbuilt commit made
- * every distribution lock declare coordinates the registry answers
- * MANIFEST_UNKNOWN for — 41 of 43 after one such re-pin — and `Verify image
- * platforms` went red across every edition. The producer and the resolver held
- * two different definitions of "the release commit": a commit that was BUILT,
- * versus whatever is at the tip.
- *
- * Building the missing coordinate by hand clears the symptom at one commit and
- * leaves this mechanism intact, so the next re-pin reproduces it. This is the
- * mechanism.
- */
-/**
- * The published TIP of a source repository — the SOURCE-provenance axis.
- *
- * ── TWO AXES, ONE PUBLISHED FACT ──
- *
- * This and {@link publishedSourceCommit} read the SAME ref and differ only in
- * what they are allowed to SELECT from it, which is the whole distinction:
- *
- *  - **image provenance** asks *"which commit did we actually build an image
- *    from?"* and must therefore walk back to published image evidence;
- *  - **source provenance** asks *"where do these vendored bytes come from?"*
- *    and needs only a commit that is published and immutable.
- *
- * Answering the second question with the first answer is not conservative, it
- * is WRONG, and the way it fails is structural rather than occasional:
- *
- *   a CONTENT-ONLY component — one with no `api/` directory, shipping no
- *   service — can never produce an image, therefore never earns image
- *   evidence, therefore can never be named by the image axis, therefore its
- *   source changes CANNOT REACH A CONSUMER'S IMAGE AT ALL.
- *
- * Measured 2026-09-14: `biomes/platform/memory-maintenance` in `xema-cultivars`
- * is exactly that shape. Its agent frontmatter had migrated `modelClass` ->
- * `modelLane`; the fix sat on that repository's `main`, and the image-evidence
- * pin could only name a commit 130 behind it that still carried the retired
- * key. `biome-host-api` baked the stale file, its own strict parser refused it,
- * and the new ReplicaSet crashlooped in production while the previous one kept
- * serving — so the defect was invisible to every health signal.
- *
- * `publishedSourceCommit` already contained half of this distinction and could
- * not express it: its `built === null` arm returns the tip for a repository
- * that publishes no images at all. That arm is right, and it was keyed on the
- * REPOSITORY when the question belongs to the SUBJECT — a repository that
- * publishes some images still vendors content-only source out of it.
- *
- * ── THIS IS NOT A RETURN TO "WHATEVER HEAD HAPPENED TO BE" ──
- *
- * Nothing here reads local `HEAD` or a working tree, and the value is resolved
- * ONCE into a committed pin that the build then reads. The revision stays
- * DECLARED; only the menu it is declared from stops being restricted to
- * commits that happen to have shipped an image.
- */
-export function publishedSourceTip(directory, repo) {
-  try {
-    return exactCommit(
-      directory,
-      PUBLISHED_SOURCE_REF,
-      `source repository "${repo}"`,
-    );
-  } catch {
-    throw new Error(
-      `source repository "${repo}" has no ${PUBLISHED_SOURCE_REF} — a distribution ` +
-        `pin must name a published commit. Fetch the repository before regenerating.`,
-    );
-  }
-}
-
-export function publishedSourceCommit(directory, repo, { ledger } = {}) {
-  const tip = publishedSourceTip(directory, repo);
-
-  const built = builtCommits(directory, PUBLISHED_SOURCE_REF, repo, ledger);
-  // Neither record knows this repository, so it publishes no images at all
-  // (xema-connectors contributes vendored content only). Nothing about it can
-  // be unbuildable and the tip is exactly right — as it always was.
-  if (built === null) {return tip;}
-
-  let walked;
-  try {
-    walked = git(directory, [
-      'rev-list',
-      `--max-count=${BUILT_COMMIT_SEARCH_LIMIT}`,
-      tip,
-    ]).split('\n');
-  } catch {
-    throw new Error(
-      `source repository "${repo}" could not be walked back from ${PUBLISHED_SOURCE_REF}`,
-    );
-  }
-
-  for (const commit of walked) {
-    if (built.has(commit)) {return commit;}
-  }
-
-  // Fail fast and loudly. Silently falling back to the tip is the defect this
-  // function exists to remove, and a pin nobody can build is worse than a
-  // refusal somebody can read.
-  throw new Error(
-    `source repository "${repo}" has no commit with published image evidence within ` +
-      `${BUILT_COMMIT_SEARCH_LIMIT} commits of ${PUBLISHED_SOURCE_REF}. A distribution ` +
-      `pin must name a commit an image was actually built from — pinning the bare tip ` +
-      `is what made every lock declare coordinates the registry answers ` +
-      `MANIFEST_UNKNOWN for. Build that repository at a recent commit, or widen ` +
-      `BUILT_COMMIT_SEARCH_LIMIT if its release cadence is genuinely slower than that.`,
-  );
-}
-
-function validateRepository(repoRoot, repo, knownRepositories) {
-  if (!knownRepositories.has(repo)) {
-    throw new Error(
-      `source repository "${repo}" is not in the explicit distribution source repository set`,
-    );
-  }
-  const directory = resolve(repoRoot, repo);
-  const rel = relative(repoRoot, directory);
-  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`)) {
-    throw new Error(`source repository "${repo}" resolves outside the aggregator`);
-  }
-  if (!existsSync(directory)) {
-    throw new Error(
-      `source repository "${repo}" is missing at ${directory}; source resolution never falls back to another authority`,
-    );
-  }
-  const actualTopLevel = realpathSync(
-    git(directory, ['rev-parse', '--show-toplevel']),
-  );
-  if (actualTopLevel !== realpathSync(directory)) {
-    throw new Error(
-      `source repository "${repo}" resolves to ${directory}, but Git reports top-level ${actualTopLevel}`,
-    );
-  }
-  return directory;
-}
-
-function workspaceSnapshotCommit(directory, repo) {
-  const head = exactCommit(directory, 'HEAD', `workspace repository "${repo}"`);
-  const temporary = mkdtempSync(join(tmpdir(), 'xema-distribution-source-'));
-  const indexPath = join(temporary, 'index');
-  const env = { ...process.env, GIT_INDEX_FILE: indexPath };
-  try {
-    git(directory, ['read-tree', head], { env });
-    git(directory, ['add', '-A', '--', '.'], { env });
-    const tree = git(directory, ['write-tree'], { env });
-    const headTree = git(directory, ['rev-parse', `${head}^{tree}`]);
-    if (tree === headTree) {return { commit: head, head, dirty: false };}
-    const commit = execFileSync(
-      'git',
-      ['-C', directory, 'commit-tree', tree, '-p', head],
-      {
-        encoding: 'utf8',
-        input: 'xema local workspace source snapshot\n',
-        stdio: ['pipe', 'pipe', 'pipe'],
-        env: {
-          ...process.env,
-          GIT_AUTHOR_NAME: 'Xema Workspace Source',
-          GIT_AUTHOR_EMAIL: 'workspace-source@xema.invalid',
-          GIT_AUTHOR_DATE: '2000-01-01T00:00:00Z',
-          GIT_COMMITTER_NAME: 'Xema Workspace Source',
-          GIT_COMMITTER_EMAIL: 'workspace-source@xema.invalid',
-          GIT_COMMITTER_DATE: '2000-01-01T00:00:00Z',
-        },
-      },
-    ).trim();
-    return { commit, head, dirty: true };
-  } finally {
-    rmSync(temporary, { recursive: true, force: true });
-  }
-}
-
-export function parseSourceModeArgs(argv) {
-  const remaining = [];
-  let mode = DistributionSourceMode.Published;
-  let declared = false;
-  for (let index = 0; index < argv.length; index += 1) {
-    if (argv[index] !== '--source') {
-      remaining.push(argv[index]);
-      continue;
-    }
-    if (declared) {throw new Error('--source may be declared only once');}
-    const value = argv[index + 1];
-    if (!Object.values(DistributionSourceMode).includes(value)) {
-      throw new Error('--source requires exactly "published" or "workspace"');
-    }
-    mode = value;
-    declared = true;
-    index += 1;
-  }
-  return { mode, remaining };
-}
-
-/**
- * The delegate a pure-record authority is given: one that cannot answer.
- *
- * Its message names the repository AND says what asking would have cost, so a
- * reader meeting it in a stack trace does not have to find this file to learn
- * why a resolution that works everywhere else is refused here.
- */
-function refusingDelegate() {
-  const refuse = (repo) => {
-    throw new Error(
-      `source repository "${repo}" reached a LIVE resolution from an artifact ` +
-        `whose commits are decided by the committed pins. Nothing downstream of ` +
-        `runtime-image-source-index.json may ask the world what a repository's ` +
-        `commit is: that is a second authority, and it moves pins nobody asked ` +
-        `to move. Refresh the pin itself (build-runtime-image-source-index.mjs ` +
-        `--trusted-write --repo ${repo}), or declare the live resolution ` +
-        `explicitly with --unpinned.`,
-    );
-  };
-  return Object.freeze({
-    mode: DistributionSourceMode.Published,
-    commitForRepository: refuse,
-    vendoredSourceCommitForRepository: refuse,
-  });
-}
-
-/**
- * A source authority that RESOLVES exactly one repository and answers every
- * other from a set of pins already decided.
- *
- * ── WHY THE PIN SET IS THE AUTHORITY AND NOT A CACHE ──
- *
- * `commitForRepository` asks the world a live question — "what is the newest
- * commit of this repository with published image evidence?" — and the answer
- * moves whenever a build lands. Every derived artifact that calls it therefore
- * re-decides every repository's pin on every run, and two artifacts derived
- * minutes apart can disagree. `resolve-images` already refuses that
- * disagreement: it re-reads each biome manifest at the RUNTIME INDEX's pin and
- * fails when the biome index was built from a different commit.
- *
- * So the pins are not an optimisation. They are the DECISION, and a refresh
- * that means to move one of them must leave the rest exactly where they are —
- * otherwise shipping a fix in one repository silently re-pins every other,
- * and every subject derived from a moved pin becomes a coordinate the registry
- * must already be serving.
- *
- * A repository with neither a pin nor the refresh scope is a REFUSAL. Falling
- * through to a live resolution would reintroduce the drift by the back door,
- * in the one case nobody is looking at — a repository that JOINED the index
- * since the pins were written.
- */
-export function createPinnedSourceAuthority({
-  delegate,
-  refreshRepository,
-  pins,
-}) {
-  // A refresh scope is the ONLY thing that can reach the live resolver, so it is
-  // the only thing that needs one. Omitting the delegate is the ordinary case
-  // for a CONSUMER artifact — one whose commits are all decided already — and it
-  // is substituted with a delegate that THROWS rather than left undefined.
-  //
-  // That substitution is the point rather than a convenience. "No repository was
-  // resolved live" is otherwise a property of the CALL SITE, provable only by
-  // reading it and re-provable after every edit; with a refusing delegate it is
-  // a property of the OBJECT, and a future edit that reaches for a live answer
-  // fails loudly at the moment it does. It is the positive control that proved
-  // `biome-index.json` is already pin-derived, kept rather than thrown away.
-  if (refreshRepository !== undefined && !delegate) {
-    throw new Error(
-      'a pinned source authority with a refresh scope needs a delegate to resolve it',
-    );
-  }
-  const live = delegate ?? refusingDelegate();
-  const byRepo = new Map();
-  for (const pin of pins ?? []) {byRepo.set(pin.repo, pin);}
-  if (byRepo.size === 0) {
-    throw new Error('a pinned source authority needs at least one pin');
-  }
-  if (refreshRepository !== undefined && !byRepo.has(refreshRepository)) {
-    throw new Error(
-      `refresh scope "${refreshRepository}" has no pin to refresh. A repository ` +
-        `joining the index joins through build-runtime-image-source-index.mjs ` +
-        `--trusted-write --repo ${refreshRepository}, which writes every index.`,
-    );
-  }
-  const pinned = (repo, field) => {
-    const pin = byRepo.get(repo);
-    if (!pin) {
-      throw new Error(
-        `source repository "${repo}" has no committed pin and is not the ` +
-          `refresh scope. Refusing to resolve it live: that is how a scoped ` +
-          `refresh silently re-pins a repository nobody asked about.`,
-      );
-    }
-    return pin[field];
-  };
-  return Object.freeze({
-    // A record of pins carries no mode of its own, and only PUBLISHED mode can
-    // have produced one: a workspace snapshot is local-only and unpublishable by
-    // construction, so it is never written to this index. Stated rather than
-    // defaulted — a reader asking a pure-record authority for its mode is asking
-    // what produced the pins, and the answer is not "whatever the caller had".
-    mode: delegate?.mode ?? DistributionSourceMode.Published,
-    commitForRepository(repo) {
-      if (repo === refreshRepository) {return live.commitForRepository(repo);}
-      return pinned(repo, 'sourceCommit');
-    },
-    vendoredSourceCommitForRepository(repo) {
-      if (repo === refreshRepository) {
-        return live.vendoredSourceCommitForRepository(repo);
-      }
-      return pinned(repo, 'vendoredSourceCommit');
-    },
-  });
-}
-
-/**
- * Pin ONE repository at an EXACT named commit, and answer every other from the
- * delegate.
- *
- * WHY A NAMED COMMIT AND NOT "THE NEWEST BUILT ONE". `publishedSourceCommit`
- * asks the world a question whose answer moves whenever a build lands, so a
- * refresh that means to ship a SPECIFIC fix is a race against the fleet: the
- * operator names the commit that carries the fix, the resolver picks whatever is
- * newest at the instant it runs, and the two are the same value only until they
- * are not. The ruling this plane now follows says the pin is an EXACT SOURCE
- * REF; this is how an operator states one.
- *
- * It is a NARROWING, never a widening. The commit must exist, must be a real
- * commit object, and must be CONTAINED IN the published ref — so this cannot pin
- * a topic branch, a commit that was force-pushed away, or anything a consumer
- * could not fetch. What it can do is name a commit OLDER than the newest built
- * one, which is the whole point: that is a deliberate hold-back or a deliberate
- * choice of the commit that carries a fix.
- *
- * It does NOT verify the commit was built. `publishedSourceCommit` exists to
- * stop an ARBITRARY tip being pinned, and its refusal text explains what that
- * cost; an operator naming a commit by hand has taken that decision explicitly,
- * and the coordinate is proven by `dist:verify-platforms` against the real
- * registry either way. Substituting the resolver's judgement for the operator's
- * here would make the flag a suggestion.
- */
-export function createExactCommitSourceAuthority({
-  delegate,
-  repo,
-  commit,
-  repoRoot = sourcesRoot(),
-}) {
-  if (!delegate) {throw new Error('an exact-commit authority needs a delegate');}
-  if (!/^[0-9a-f]{40}$/u.test(String(commit ?? ''))) {
-    throw new Error(
-      `--at requires a full 40-character commit sha, not "${String(commit)}". ` +
-        `An abbreviation is ambiguous across repositories and a ref is not exact.`,
-    );
-  }
-  const directory = resolve(repoRoot, repo);
-  let resolved;
-  try {
-    resolved = git(directory, ['rev-parse', '--verify', `${commit}^{commit}`]);
-  } catch {
-    throw new Error(
-      `source repository "${repo}" has no commit ${commit}. Fetch it before pinning.`,
-    );
-  }
-  if (resolved !== commit) {
-    throw new Error(
-      `${commit} resolves to ${resolved} in "${repo}" — pass the commit itself.`,
-    );
-  }
-  try {
-    git(directory, [
-      'merge-base',
-      '--is-ancestor',
-      commit,
-      PUBLISHED_SOURCE_REF,
-    ]);
-  } catch {
-    throw new Error(
-      `${commit} is not contained in ${PUBLISHED_SOURCE_REF} of "${repo}". A ` +
-        `distribution pin must name a PUBLISHED commit: anything else cannot be ` +
-        `fetched by a consumer and can be force-pushed away under the lock.`,
-    );
-  }
-  return Object.freeze({
-    mode: delegate.mode,
-    commitForRepository(target) {
-      return target === repo ? commit : delegate.commitForRepository(target);
-    },
-    vendoredSourceCommitForRepository(target) {
-      // BOTH axes. The two-axis split exists because a content-only biome can
-      // never earn image evidence and so must be read at the SOURCE tip rather
-      // than at a possibly-much-older image commit. An operator naming an exact
-      // commit has answered both questions at once, and leaving the source axis
-      // on the live tip would put a moving value back into a pin the operator
-      // asked to be exact — half a race is still a race.
-      return target === repo
-        ? commit
-        : delegate.vendoredSourceCommitForRepository(target);
-    },
-  });
-}
-
-export function createSourceAuthority({
-  mode = DistributionSourceMode.Published,
-  repoRoot = sourcesRoot(),
-  knownRepositories,
-  log = console.log,
-} = {}) {
-  if (!Object.values(DistributionSourceMode).includes(mode)) {
-    throw new Error(`unknown distribution source mode "${String(mode)}"`);
-  }
-  if (
-    !knownRepositories ||
-    typeof knownRepositories === 'string' ||
-    typeof knownRepositories[Symbol.iterator] !== 'function'
-  ) {
-    throw new Error(
-      'source authority requires the caller to declare its source repositories',
-    );
-  }
-  const known = new Set(knownRepositories);
-  if (known.size === 0) {
-    throw new Error('source authority repository declaration must not be empty');
-  }
-  const resolvedRoot = realpathSync(repoRoot);
-  const identities = new Map();
-  const vendored = new Map();
-  return Object.freeze({
-    mode,
-    /**
-     * The SOURCE-provenance revision — see {@link publishedSourceTip} for why
-     * this is a different question from `commitForRepository`.
-     *
-     * In WORKSPACE mode the two deliberately coincide: a workspace snapshot is
-     * local-only and unpublishable by construction, so there is no image-
-     * evidence constraint to diverge from and no second fact to resolve.
-     */
-    vendoredSourceCommitForRepository(repo) {
-      const cached = vendored.get(repo);
-      if (cached) {return cached;}
-      const directory = validateRepository(resolvedRoot, repo, known);
-      if (mode !== DistributionSourceMode.Published) {
-        return this.commitForRepository(repo);
-      }
-      const commit = publishedSourceTip(directory, repo);
-      vendored.set(repo, commit);
-      log(
-        `[source-authority] vendored-source ${repo}@${commit} (${PUBLISHED_SOURCE_REF} tip)`,
-      );
-      return commit;
-    },
-    commitForRepository(repo) {
-      const cached = identities.get(repo);
-      if (cached) {return cached.commit;}
-      const directory = validateRepository(resolvedRoot, repo, known);
-      if (mode === DistributionSourceMode.Published) {
-        const commit = publishedSourceCommit(directory, repo);
-        identities.set(repo, { commit });
-        log(
-          `[source-authority] published ${repo}@${commit} (${PUBLISHED_SOURCE_REF})`,
-        );
-        return commit;
-      }
-      const snapshot = workspaceSnapshotCommit(directory, repo);
-      identities.set(repo, snapshot);
-      log(
-        `[source-authority] workspace ${repo}@${snapshot.commit} ` +
-          `(HEAD ${snapshot.head}; ${snapshot.dirty ? 'dirty snapshot — local only, do not publish' : 'clean'})`,
-      );
-      return snapshot.commit;
-    },
-  });
-}