@xemahq/xema 0.25.1 → 0.27.0

package/edition/source-authority.mjs

@@ -0,0 +1,725 @@
+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 { 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 const BUILD_LEDGER_FILE = 'build-ledger.json';
+
+/**
+ * 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 path = join(distributionsDir, BUILD_LEDGER_FILE);
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') {return null;}
+    throw error;
+  }
+  if (
+    raw === null ||
+    typeof raw !== 'object' ||
+    raw.schemaVersion !== 1 ||
+    typeof raw.repositories !== 'object' ||
+    raw.repositories === null ||
+    Array.isArray(raw.repositories)
+  ) {
+    throw new Error(`${BUILD_LEDGER_FILE} is not strict schema v1`);
+  }
+  return raw.repositories;
+}
+
+/**
+ * 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.
+ */
+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 is a full rebuild, not a scoped refresh.`,
+    );
+  }
+  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;
+    },
+  });
+}