@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/build-runtime-image-source-index.mjs

@@ -0,0 +1,1197 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+import { buildValidatedPlatformServiceIndex } from './build-platform-service-index.mjs';
+import { canonicalPublicHttpsRepositoryUrl, sameRepository } from './canonical-repository-url.mjs';
+import { connectorCrossRepoBuildInputs } from './connector-source-authority.mjs';
+import { EditionChannel } from './edition-channel.mjs';
+import { editionWorkspaceConfig, workspaceSection } from './edition-config.mjs';
+import { biomeIndexPath, dataRoot, platformServiceIndexPath, runtimeImageSourceIndexPath, WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath } from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import { firstPartySources } from './first-party-source-ids.mjs';
+import {
+  buildTrustedKernelContractAuthority,
+  KERNEL_COMMIT_FLAG,
+  describeKernelContractAuthorityDrift,
+  validateKernelContractAuthorityFromGit,
+} from './kernel-contract-authority.mjs';
+import {
+  buildBiomeIndex,
+  compareStrings,
+  distributionBiomeSourceRepositories,
+  loadKernelDistributionSchemas,
+  readGitJsonAtCommit,
+  serializeJson,
+  sha256Hex,
+} from './lib.mjs';
+import { createRegistryClientResolver } from './oci-image-source-evidence.mjs';
+import { disposeRegistrySessions } from './oras.mjs';
+import {
+  platformServiceRuntimeBindings,
+} from './platform-service-source-authority.mjs';
+import {
+  createExactCommitSourceAuthority,
+  createPinnedSourceAuthority,
+  createSourceAuthority,
+  parseSourceModeArgs,
+} from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import { checkThirdPartySourcePins } from './third-party-source-check.mjs';
+import { loadThirdPartySourceContext } from './third-party-source-context.mjs';
+import {
+  CHANNEL_FLAG,
+  CHECK_THIRD_PARTY_FLAG,
+  THIRD_PARTY_FLAG,
+  THIRD_PARTY_WRITER_USAGE,
+  takeThirdPartyFlags,
+} from './third-party-source-flags.mjs';
+import { commitThirdPartySourceWrite, planThirdPartySourceWrite } from './third-party-source-writer.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
+}
+
+const runtimeImageSources = () =>
+  workspaceSection('runtimeImageSources', 'building or validating the runtime image source index');
+
+const sourceDeclarations = () => runtimeImageSources().supplementalSources;
+
+/**
+ * Content a producing repository copies OUT OF ANOTHER repository into its build
+ * context before the image build.
+ *
+ * This is the ONLY image build input that is not derivable from the consuming
+ * repository at its own commit — nothing inside `xema-base@<sha>` names the
+ * bytes of `xema-cultivars/biomes/platform/mailops`. Every other input (the
+ * resolved Dockerfile, its `COPY` sources, the `workspace:` graph) is read
+ * straight out of the consuming commit, so this list is the whole hand-declared
+ * surface and stays small by construction.
+ *
+ * The list is the data root's (`runtimeImageSources.crossRepoBuildInputs`), plus
+ * one input per production connector derived from `connectorSources`; the
+ * history of why each entry is there lives with the data. Each entry pins the vendored bytes to the SOURCE repository's own
+ * `repositoryPins` commit — the revision this distribution has resolved, and
+ * therefore the revision the producing build must clone.
+ *
+ * CLOSED (was a KNOWN GAP): the producing workflows used to clone with
+ * `git clone --depth 1` and no ref — the source repository's default-branch HEAD
+ * at build time — so a built image was not a function of any commit pair and its
+ * published tag could describe bytes it did not contain. They now vendor through
+ * `tooling/release/vendor-cross-repo-inputs.mjs`, driven by a per-repository
+ * record the aggregator generates FROM THIS TABLE joined to `repositoryPins`
+ * (`tooling/release/generate-cross-repo-build-inputs.mjs`). The same record
+ * supplies `compute-image-tag.mjs`'s `--vendored` pins, so the bytes in the image
+ * and the bytes in the hash come from one place. The gate
+ * `cross-repo-build-inputs` fails on a stale record, and on a workflow that
+ * hand-rolls a clone or a copy instead of reading it.
+ *
+ * Consequence worth knowing: a change to a source repository's vendored content
+ * does NOT reach a consumer's image until this index is regenerated and the
+ * emitted record re-committed. That is the point — the vendored revision is
+ * declared, not whatever HEAD happened to be.
+ */
+export const crossRepoBuildInputs = () => [
+  ...runtimeImageSources().crossRepoBuildInputs,
+  ...connectorCrossRepoBuildInputs(),
+];
+
+/**
+ * Context directories a build step creates, which exist in no commit. Declared
+ * (`runtimeImageSources.buildStepContextDirectories`) so a Dockerfile COPY of
+ * one is a REVIEWED absence rather than a silent miss.
+ */
+const buildStepContextDirectoriesDeclared = () => runtimeImageSources().buildStepContextDirectories;
+
+/**
+ * The logical-platform-service → actual-runtime-subject bindings that cannot be
+ * inferred. DERIVED from `platform-service-source-authority.mjs`, which is the
+ * one place the partition — own repository-root image vs. carried by another
+ * subject — is declared. It used to be a second copy here, and the two could
+ * only agree by hand.
+ */
+
+function readJson(path) {
+  return readStrictJsonFile(path);
+}
+
+function git(repo, args) {
+  return execFileSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function declaredSourceRepositories() {
+  return [
+    ...new Set([
+      ...readJson(biomeIndexPath()).map(({ repo }) => repo),
+      ...readJson(
+        join(dataRoot(), 'platform-service-index.json'),
+      ).services.map(({ repo }) => repo),
+      ...sourceDeclarations().map(({ repo }) => repo),
+      ...crossRepoBuildInputs().flatMap(({ consumerRepo, sourceRepo }) => [
+        consumerRepo,
+        sourceRepo,
+      ]),
+    ]),
+  ];
+}
+
+/**
+ * One repository, BOTH provenance axes, in ONE record.
+ *
+ * `sourceCommit` is the IMAGE axis and its meaning is unchanged: every image
+ * subject from this repository must carry exactly this commit, and
+ * `expectedProducerSource` throws when one does not. It is therefore
+ * constrained to commits with published image evidence.
+ *
+ * `vendoredSourceCommit` is the SOURCE axis — where vendored bytes come from.
+ * It is the published tip, because a vendored path needs its content to exist
+ * at a published immutable commit and does NOT need an image to have been
+ * built there. See `publishedSourceTip` in `source-authority.mjs` for the
+ * measured production failure that fusing the two produced.
+ *
+ * They are emitted together, from one resolution, deliberately: the release has
+ * ONE authority that answers both questions about a component, never two
+ * competing ones that can disagree about which commit a component is at.
+ */
+export function repositoryIdentity(repo, sourceAuthority) {
+  const repoDirectory = sourcePath(repo);
+  const sourceCommit = sourceAuthority.commitForRepository(repo);
+  const vendoredSourceCommit =
+    sourceAuthority.vendoredSourceCommitForRepository(repo);
+  const repositoryUrl = canonicalPublicHttpsRepositoryUrl(
+    git(repoDirectory, ['remote', 'get-url', 'origin']),
+    `${repo} origin`,
+  );
+  return { repo, repositoryUrl, sourceCommit, vendoredSourceCommit };
+}
+
+/**
+ * Refuse to WRITE an index whose declared vendored source paths do not exist at
+ * the commit whose bytes the build will actually fetch.
+ *
+ * This assertion landed on `main` in `0dfbba7` and was removed by `a416f1e`
+ * ("Revert the develop merge on main — the CONSUMER landed before its
+ * PRODUCER") as COLLATERAL of reverting an unrelated cross-repo ordering
+ * failure — 93 lines of this file among 62 reverted files. It is re-landed here
+ * on its own merits, and on the SOURCE axis.
+ *
+ * Nothing reads the declared cross-repo build inputs at declaration time, so a path that
+ * has moved fails SILENTLY where it is written and LOUDLY somewhere else
+ * entirely: the consuming image build dies at "Fetch pinned cross-repo build
+ * inputs", in another repository, for a declaration nobody was editing. The
+ * defect belongs where it is authored, and an index that cannot be written is
+ * strictly better than one that can be written and cannot be built from.
+ */
+function assertVendoredSourcesResolve(crossRepoBuildInputs, resolveIdentity) {
+  const unresolved = [];
+  for (const input of crossRepoBuildInputs) {
+    // The SOURCE axis, not the image pin. A vendored path is a fact about the
+    // commit whose BYTES are vendored, and `vendor-cross-repo-inputs.mjs`
+    // fetches exactly that commit — so asking the image-evidence pin whether a
+    // source path exists answers about a commit the build never reads.
+    const { vendoredSourceCommit } = resolveIdentity(input.sourceRepo);
+    const found = git(sourcePath(input.sourceRepo), [
+      'ls-tree',
+      '--name-only',
+      vendoredSourceCommit,
+      '--',
+      input.sourcePath,
+    ]);
+    if (found.length === 0) {
+      unresolved.push(
+        `${input.sourceRepo}@${vendoredSourceCommit}:${input.sourcePath} does not ` +
+          `exist (vendored into ${input.consumerRepo}` +
+          `${input.consumerService ? ` service "${input.consumerService}"` : ''} ` +
+          `at ${input.destinationPath})`,
+      );
+    }
+  }
+  if (unresolved.length > 0) {
+    throw new Error(
+      `the declared crossRepoBuildInputs name ${unresolved.length} source path(s) that do ` +
+        `not exist at the vendored source commit this index pins. A vendored path ` +
+        `is a fact about that PINNED commit, not about anybody's working tree or ` +
+        `develop branch — fix the declaration, or pin a commit that carries it:` +
+        `\n  ${unresolved.join('\n  ')}`,
+    );
+  }
+}
+
+const CURRENT_INDEX_SCHEMA_VERSION = 2;
+
+/**
+ * The kernel-contract authority for a pin regeneration.
+ *
+ * ── WHY THIS IS NOT `buildTrustedKernelContractAuthority` ──
+ *
+ * This function regenerates `repositoryPins` — a PROJECTION of immutable
+ * remote facts. Every one of those pins is read from
+ * `refs/remotes/origin/main` of its repository, which is exactly right: a
+ * production composition must resolve from durable, published state.
+ *
+ * The kernel-contract authority was the ONE exception, and it was the wrong
+ * kind of exception. `buildTrustedKernelContractAuthority` takes its commit
+ * from the LOCAL HEAD of `repos/xema-kernel-contracts` and requires that
+ * checkout to be EXACTLY CLEAN — so regenerating thirteen pins that have
+ * nothing to do with the kernel contract failed outright whenever somebody
+ * had an uncommitted file in that one repository. Measured 2026-09-14: ten of
+ * twenty-eight repositories in a shared checkout held another agent's
+ * in-flight work, and the pins could not be regenerated at all.
+ *
+ * That is a development-state fact deciding a release-composition question,
+ * and it is the boundary this change moves. Whether a colleague's working
+ * tree is dirty must never determine whether we can resolve what production
+ * ships.
+ *
+ * ── WHAT IS PRESERVED, AND WHY IT IS NOT WEAKER ──
+ *
+ * The authority is read from the COMMITTED index and re-verified from git AT
+ * ITS OWN PINNED COMMIT: `validateKernelContractAuthorityFromGit` recomputes
+ * the content digest from `ls-tree` + `cat-file` blobs at `sourceCommit` and
+ * refuses anything that does not match byte for byte. No worktree file is
+ * read on that path — it never was — so the provenance guarantee is identical
+ * and the clean-checkout assertion was buying nothing for it.
+ *
+ * `requireHeadMatch: false` because MOVING the authority is a different
+ * operation with its own tool: `xema-edition index runtime-image-source
+ * --repin-contract-authority`, which
+ * legitimately demands a deliberate clean checkout because it is CHOOSING a
+ * new commit. Re-deriving it here made pin regeneration silently re-pin the
+ * contract as a side effect — two operations behind one command, and the one
+ * nobody asked for is the one that took the lock.
+ *
+ * BOOTSTRAP is the single case with no committed authority to preserve: it
+ * CHOOSES a commit exactly as the re-pin does, so it obeys the re-pin's one
+ * rule — the caller states the commit (`--kernel-commit`) and the checkout's
+ * HEAD must equal it. Stating a commit when a committed authority exists is
+ * refused: it would be read by nobody.
+ *
+ * A committed index of any schemaVersion but the current one is refused by name,
+ * never migrated: a schemaVersion 1 index is re-indexed by deleting it and
+ * running bootstrap. Any other
+ * schemaVersion is refused by name, never read as one of these.
+ */
+async function resolveContractAuthority(schemas, kernelRoot, kernelCommit) {
+  const repositoryDirectory = kernelRoot ?? undefined;
+  const committed = existsSync(runtimeImageSourceIndexPath())
+    ? readJson(runtimeImageSourceIndexPath())
+    : undefined;
+  if (committed !== undefined && committed.schemaVersion !== CURRENT_INDEX_SCHEMA_VERSION) {
+    throw new Error(
+      `${runtimeImageSourceIndexPath()} has schemaVersion ${JSON.stringify(committed.schemaVersion)}; ` +
+        `this command reads only schemaVersion ${CURRENT_INDEX_SCHEMA_VERSION} and does not migrate older indexes: ` +
+        `delete the index and re-run with ${KERNEL_COMMIT_FLAG} <40-hex> to bootstrap a new one`,
+    );
+  }
+  if (committed === undefined || !committed.contractAuthority) {
+    return buildTrustedKernelContractAuthority({
+      ...(repositoryDirectory === undefined ? {} : { repositoryDirectory }),
+      schemas,
+      kernelCommit,
+    });
+  }
+  if (kernelCommit !== undefined) {
+    throw new Error(
+      `${KERNEL_COMMIT_FLAG} states the commit of a NEW contract authority, and the committed index already pins ` +
+        `${committed.contractAuthority.sourceCommit}: this command preserves it. Move it with ${REPIN_FLAG} ${KERNEL_COMMIT_FLAG} <40-hex>.`,
+    );
+  }
+  return validateKernelContractAuthorityFromGit({
+    authority: committed.contractAuthority,
+    ...(repositoryDirectory === undefined ? {} : { repositoryDirectory }),
+    schemas,
+    requireHeadMatch: false,
+  });
+}
+
+/**
+ * Re-resolve ONE repository pin and PRESERVE every other one byte for byte.
+ *
+ * ── WHY A WHOLE-INDEX REBUILD IS THE WRONG TOOL FOR A ONE-REPOSITORY FIX ──
+ *
+ * `--trusted-write` re-resolves all thirteen pins against each repository's
+ * `refs/remotes/origin/main`. That is exactly right when the question is "what
+ * does the fleet look like now", and exactly wrong when the question is "ship
+ * the fix that is already built in ONE repository": every other pin moves to
+ * whatever that repository has published since, and every subject whose
+ * identity depends on a moved pin is recomputed. Measured 2026-09-18 on this
+ * index, a full rebuild moves 5 of 13 pins and recomputes 54 of 62 subjects,
+ * 53 of them collateral — so a one-line fix arrives as a fleet-wide re-pin
+ * nobody asked for, and every one of those 53 subjects is a coordinate the
+ * registry must already be serving or delivery fails.
+ *
+ * The scope is a CHOICE somebody states, and it narrows: `--repo <repository>`
+ * says "this repository has moved; nothing else has". Every pin outside it is
+ * taken verbatim from the committed index, so it cannot drift by accident, and
+ * every subject derived from an unmoved pin is recomputed at the SAME commit
+ * and therefore lands byte-identical. Only the subjects whose identity actually
+ * depends on the named repository change.
+ *
+ * It is deliberately NOT a separate code path: the scope seeds the memo map
+ * `getRepositoryIdentity` already uses, so the index is produced by the one
+ * builder, passes the one validator, and is byte-comparable with a full
+ * rebuild's output for the parts that did not move. A second writer for
+ * "narrow" indexes would be a second answer to what an index IS.
+ *
+ * A repository this index does not source is a REFUSAL, never a silent no-op —
+ * a typo that quietly rewrote nothing would read in review as "the refresh ran".
+ *
+ * A declared source repository with NO committed pin JOINS the index through the
+ * same scope: every committed pin is preserved verbatim and only the named
+ * repository is resolved (at `--at`, which must be published). It needs no
+ * full `--trusted-write`, which would re-derive and drift every other pin.
+ */
+export function preserveOtherRepositoryPins(
+  repoScope,
+  committedIndex,
+  declaredRepositories,
+) {
+  const declared = new Set(declaredRepositories);
+  if (!declared.has(repoScope)) {
+    throw new Error(
+      `--repo "${repoScope}" is not a source repository of this index. ` +
+        `Known repositories: ${[...declared].sort(compareStrings).join(', ')}`,
+    );
+  }
+  const pins = Array.isArray(committedIndex?.repositoryPins)
+    ? committedIndex.repositoryPins
+    : [];
+  if (pins.length === 0) {
+    throw new Error(
+      'the committed runtime image source index declares no repositoryPins to preserve',
+    );
+  }
+  return pins
+    .filter((pin) => pin.repo !== repoScope)
+    .map((pin) => ({
+      repo: pin.repo,
+      repositoryUrl: pin.repositoryUrl,
+      sourceCommit: pin.sourceCommit,
+      vendoredSourceCommit: pin.vendoredSourceCommit,
+    }));
+}
+
+function committedRepositoryPinsToPreserve(repoScope) {
+  if (!existsSync(runtimeImageSourceIndexPath())) {
+    throw new Error(
+      `--repo requires ${runtimeImageSourceIndexPath()} to exist: there is no ` +
+        `committed index whose other pins could be preserved. Bootstrap with ` +
+        `--trusted-write and no --repo.`,
+    );
+  }
+  return preserveOtherRepositoryPins(
+    repoScope,
+    readJson(runtimeImageSourceIndexPath()),
+    declaredSourceRepositories(),
+  );
+}
+
+/**
+ * `producerWorkflowPins` are operator-stated TRUST DATA: which commit of a
+ * producer repository's workflow the verifier believes. Nothing is derived (not
+ * from `repositoryPins`, not from a policy row); the committed pins are kept
+ * exactly, and `--producer-workflow-pin <owner/repo>=<40-hex>` sets or updates
+ * one. A bootstrap index with none committed writes `[]`, which the kernel allows.
+ */
+export function mergeProducerWorkflowPins(committedPins, statedPins) {
+  const merged = new Map(
+    (Array.isArray(committedPins) ? committedPins : []).map((pin) => [
+      pin.repository,
+      { repository: pin.repository, workflowCommit: pin.workflowCommit },
+    ]),
+  );
+  for (const pin of statedPins) {
+    merged.set(pin.repository, { repository: pin.repository, workflowCommit: pin.workflowCommit });
+  }
+  return [...merged.values()].sort((left, right) => compareStrings(left.repository, right.repository));
+}
+
+/**
+ * The committed index with one producer workflow pin merged in by `mergeProducerWorkflowPins`: what the third-party
+ * writer adds (`{repository, workflowCommit: sourceCommit}`). Every repository pin and subject is kept exactly: a
+ * third-party repository is not an index repository, so nothing about it can be re-resolved.
+ */
+export function indexWithProducerWorkflowPin({ committedIndex, pin }) {
+  return {
+    ...committedIndex,
+    producerWorkflowPins: mergeProducerWorkflowPins(committedIndex.producerWorkflowPins, [pin]),
+  };
+}
+
+const PRODUCER_WORKFLOW_PIN_FLAG = '--producer-workflow-pin';
+
+/**
+ * Every `--producer-workflow-pin <owner/repo>=<40-hex>` of the argv. A malformed
+ * value, or a repository stated twice, is refused here; the repository and
+ * commit grammar is the kernel's, applied by the index parse.
+ */
+export function parseProducerWorkflowPinFlags(argv) {
+  const pins = [];
+  const remaining = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== PRODUCER_WORKFLOW_PIN_FLAG) {
+      remaining.push(argv[index]);
+      continue;
+    }
+    const value = argv[index + 1];
+    const separator = value?.indexOf('=') ?? -1;
+    if (separator < 1 || value.startsWith('--')) {
+      throw new Error(`${PRODUCER_WORKFLOW_PIN_FLAG} requires <owner/repo>=<40-hex-commit>`);
+    }
+    const repository = value.slice(0, separator);
+    const workflowCommit = value.slice(separator + 1);
+    if (pins.some((pin) => pin.repository === repository)) {
+      throw new Error(`${PRODUCER_WORKFLOW_PIN_FLAG} names ${repository} more than once`);
+    }
+    if (!COMMIT_PATTERN.test(workflowCommit)) {
+      throw new Error(`${PRODUCER_WORKFLOW_PIN_FLAG} ${repository}: the commit must be a full 40-hex sha`);
+    }
+    pins.push({ repository, workflowCommit });
+    index += 1;
+  }
+  return { producerWorkflowPins: pins, remaining };
+}
+
+/**
+ * A `--producer-workflow-pin` is trust data for the index `--trusted-write`
+ * writes, and only there. Every other mode writes nothing, so a pin stated to
+ * one would be silently ignored; `--check-sources` included: it grades the
+ * committed index against the sources, and a pin is not a source.
+ */
+export function assertProducerWorkflowPinsWritten(producerWorkflowPins, flag, usage) {
+  if (producerWorkflowPins.length > 0 && flag !== '--trusted-write') {
+    throw new Error(`${PRODUCER_WORKFLOW_PIN_FLAG} states trust data for a written index: ${flag} writes none\n${usage}`);
+  }
+}
+
+/**
+ * `biomeIndex` and `platformServiceIndex` are the indexes this one is built
+ * over, INJECTED: the release CLI passes the committed ones read from disk
+ * (byte-identical to reading them here), a develop snapshot passes the ones it
+ * built at its own pins.
+ */
+export async function buildTrustedIndex(
+  schemas,
+  sourceAuthority,
+  kernelRoot,
+  repoScope,
+  { biomeIndex, platformServiceIndex, kernelCommit, producerWorkflowPins = [], contractAuthority: statedAuthority },
+) {
+  const contractAuthority = statedAuthority ?? (await resolveContractAuthority(schemas, kernelRoot, kernelCommit));
+  const repositoryIdentities = new Map();
+  if (repoScope !== undefined) {
+    for (const pin of committedRepositoryPinsToPreserve(repoScope)) {
+      repositoryIdentities.set(pin.repo, pin);
+    }
+  }
+  const getRepositoryIdentity = (repo) => {
+    let identity = repositoryIdentities.get(repo);
+    if (!identity) {
+      if (repoScope !== undefined && repo !== repoScope) {
+        throw new Error(
+          `source repository "${repo}" has no committed pin and is not the --repo scope ` +
+            `"${repoScope}". A scoped write adds one repository; resolving "${repo}" live ` +
+            `would re-pin a repository nobody asked about. Add it with its own --repo ${repo} --at <sha>.`,
+        );
+      }
+      identity = repositoryIdentity(repo, sourceAuthority);
+      repositoryIdentities.set(repo, identity);
+    }
+    return identity;
+  };
+  const supplementalSubjects = sourceDeclarations().map((declaration) => {
+    const repoDirectory = sourcePath(declaration.repo);
+    const { sourceCommit, repositoryUrl } = getRepositoryIdentity(
+      declaration.repo,
+    );
+    const sourceManifestJson = readGitJsonAtCommit(
+      repoDirectory,
+      declaration.sourceManifestPath,
+      sourceCommit,
+    );
+    return {
+      kind: declaration.kind,
+      id: declaration.id,
+      imageRef: `${editionWorkspaceConfig().imageRegistry}/${declaration.id}`,
+      repositoryUrl,
+      repo: declaration.repo,
+      path:
+        declaration.path === '.'
+          ? declaration.repo
+          : `${declaration.repo}/${declaration.path}`,
+      sourceManifestPath: `${declaration.repo}/${declaration.sourceManifestPath}`,
+      sourceCommit,
+      sourceManifestHash: sha256Hex(serializeJson(sourceManifestJson)),
+    };
+  }).sort(compareSubject);
+  const sourceRepos = new Set([
+    ...biomeIndex.map((biome) => biome.repo),
+    ...platformServiceIndex.services.map((service) => service.repo),
+    ...supplementalSubjects.map((subject) => subject.repo),
+  ]);
+  const repositoryPins = [...sourceRepos]
+    .sort(compareStrings)
+    .map(getRepositoryIdentity);
+  const sortedCrossRepoBuildInputs = [...crossRepoBuildInputs()].sort(
+    (left, right) =>
+      compareStrings(
+        [left.consumerRepo, left.consumerService, left.destinationPath].join(
+          '\u0000',
+        ),
+        [right.consumerRepo, right.consumerService, right.destinationPath].join(
+          '\u0000',
+        ),
+      ),
+  );
+  assertVendoredSourcesResolve(sortedCrossRepoBuildInputs, getRepositoryIdentity);
+  const buildStepContextDirectories = [...buildStepContextDirectoriesDeclared()].sort(
+    (left, right) =>
+      compareStrings(
+        `${left.repo}\u0000${left.path}`,
+        `${right.repo}\u0000${right.path}`,
+      ),
+  );
+  for (const directory of buildStepContextDirectories) {
+    if (!sourceRepos.has(directory.repo)) {
+      throw new Error(
+        `build-step context directory "${directory.path}" names repository ` +
+          `"${directory.repo}", which is not an image source repository`,
+      );
+    }
+  }
+  for (const input of sortedCrossRepoBuildInputs) {
+    for (const repo of [input.consumerRepo, input.sourceRepo]) {
+      if (!sourceRepos.has(repo)) {
+        throw new Error(
+          `cross-repo build input for "${input.consumerService}" names repository ` +
+            `"${repo}", which is not an image source repository`,
+        );
+      }
+    }
+  }
+  return {
+    schemaVersion: CURRENT_INDEX_SCHEMA_VERSION,
+    contractAuthority,
+    supplementalSubjects,
+    crossRepoBuildInputs: sortedCrossRepoBuildInputs,
+    buildStepContextDirectories,
+    repositoryPins,
+    producerWorkflowPins: mergeProducerWorkflowPins(
+      existsSync(runtimeImageSourceIndexPath()) ? readJson(runtimeImageSourceIndexPath()).producerWorkflowPins : [],
+      producerWorkflowPins,
+    ),
+    platformServiceBindings: [...platformServiceRuntimeBindings()].sort(
+      (left, right) =>
+        compareStrings(left.platformService, right.platformService),
+    ),
+  };
+}
+
+function compareSubject(left, right) {
+  return (
+    compareStrings(left.kind, right.kind) || compareStrings(left.id, right.id)
+  );
+}
+
+/**
+ * Every release pin names a first-party repository (`firstPartySources`) at
+ * the URL declared there. The converse is not required: a first-party
+ * repository is in the develop graph before any release pins it.
+ */
+function assertPinsAreFirstParty(repositoryPins) {
+  const declared = firstPartySources('checking that every release pin is a first-party repository');
+  for (const pin of repositoryPins) {
+    const source = declared[pin.repo];
+    if (source === undefined) {
+      throw new Error(
+        `runtime-image-source-index pins ${JSON.stringify(pin.repo)}, which edition-workspace.json does not declare under "firstPartySources"`,
+      );
+    }
+    if (!sameRepository(source.repositoryUrl, pin.repositoryUrl, `${pin.repo} repositoryUrl`)) {
+      throw new Error(
+        `runtime-image-source-index pins ${pin.repo} at ${pin.repositoryUrl}, but "firstPartySources" declares it at ${source.repositoryUrl}`,
+      );
+    }
+  }
+}
+
+export async function validateRuntimeImageSourceIndex(
+  index,
+  schemas,
+  {
+    // Whether `repositoryPins` must already cover every image source repository.
+    // TRUE by default, and true for everyone who PRODUCES this index — that is
+    // this module's own contract and the assertion below is where it lives.
+    //
+    // The kernel-authority repin passes false, because it produces nothing here:
+    // it rewrites ONE field, `contractAuthority`, on an index somebody else
+    // built. Requiring coverage of it makes onboarding a new source repository
+    // impossible by construction — the repin refuses the stale index, and the
+    // rebuild that would add the missing pin refuses the un-repinned authority.
+    // Measured 2026-08-26 when `repos/xema-connectors` was carved out: the
+    // documented six-step chain deadlocked at its own first step.
+    assertRepositoryCoverage = true,
+    // WHICH kernel checkout the committed authority is re-verified against.
+    // Undefined keeps the default in-aggregator checkout; see `parseKernelRoot`
+    // for why a shared working tree must not decide this.
+    kernelRoot = undefined,
+    // The indexes this one is validated against: the committed ones by default,
+    // a develop snapshot's own when it injects them.
+    biomeIndex = readJson(biomeIndexPath()),
+    platformServiceIndex = readJson(
+      join(dataRoot(), 'platform-service-index.json'),
+    ),
+  } = {},
+) {
+  await validateKernelContractAuthorityFromGit({
+    authority: index.contractAuthority,
+    ...(kernelRoot === undefined ? {} : { repositoryDirectory: kernelRoot }),
+    schemas,
+    onDrift: (drift) =>
+      console.log(`[runtime-image-source-index] ${describeKernelContractAuthorityDrift(drift)}`),
+  });
+  // Every platform service carries an exact source identity (the kernel lock
+  // schema requires it), so "is it in platform-service-index.json" no longer
+  // separates the two kinds — it is now true of all of them. The partition is
+  // the declared runtime binding, read from the one authority that owns it.
+  const expectedBindings = platformServiceRuntimeBindings()
+    .map((binding) => binding.platformService)
+    .sort(compareStrings);
+  const actualBindings = index.platformServiceBindings.map(
+    (binding) => binding.platformService,
+  );
+  if (serializeJson(actualBindings) !== serializeJson(expectedBindings)) {
+    throw new Error(
+      'runtime-image-source-index platform bindings do not exactly cover every declared platform service that another subject carries',
+    );
+  }
+  const supplemental = new Set(
+    index.supplementalSubjects.map(
+      (subject) => `${subject.kind}\0${subject.id}`,
+    ),
+  );
+  const expectedRepositories = [
+    ...new Set([
+      ...biomeIndex.map((biome) => biome.repo),
+      ...platformServiceIndex.services.map((service) => service.repo),
+      ...index.supplementalSubjects.map((subject) => subject.repo),
+    ]),
+  ].sort(compareStrings);
+  const actualRepositories = index.repositoryPins.map(
+    (repository) => repository.repo,
+  );
+  if (
+    assertRepositoryCoverage &&
+    serializeJson(actualRepositories) !== serializeJson(expectedRepositories)
+  ) {
+    throw new Error(
+      'runtime-image-source-index repository pins do not exactly cover every image source repository',
+    );
+  }
+  const repositoryPins = new Map(
+    index.repositoryPins.map((repository) => [repository.repo, repository]),
+  );
+  for (const repository of index.repositoryPins) {
+    if (
+      canonicalPublicHttpsRepositoryUrl(
+        repository.repositoryUrl,
+        `${repository.repo} repositoryUrl`,
+      ) !== repository.repositoryUrl
+    ) {
+      throw new Error(`${repository.repo} repositoryUrl is not canonical`);
+    }
+  }
+  assertPinsAreFirstParty(index.repositoryPins);
+  // Every subject a biome contributes to the image plane — BOTH the standing
+  // services and the runtime components. A runtime component is a full image
+  // subject (built, signed, mirrored) that simply is never scheduled, so a
+  // platform service may legitimately bind to one: `opencode-image-prepuller`
+  // is a standing service whose whole job is to keep the `opencode-worker`
+  // runtime-component image warm on every node.
+  const biomeImageSubjects = new Set(
+    biomeIndex.flatMap((biome) => [
+      // A worker running a sibling service's image is not a subject of its own.
+      ...(biome.services ?? [])
+        .filter((service) => !Object.hasOwn(biome.workerImages ?? {}, service))
+        .map((service) => `service\0${service}`),
+      ...(biome.runtimeComponents ?? []).map(
+        (component) => `runtime-component\0${component}`,
+      ),
+    ]),
+  );
+  for (const binding of index.platformServiceBindings) {
+    const key = `${binding.subjectKind}\0${binding.subjectId}`;
+    if (!supplemental.has(key) && !biomeImageSubjects.has(key)) {
+      throw new Error(
+        `platform service "${binding.platformService}" binds unknown runtime subject "${binding.subjectKind}:${binding.subjectId}"`,
+      );
+    }
+  }
+  for (const subject of index.supplementalSubjects) {
+    if (
+      canonicalPublicHttpsRepositoryUrl(
+        subject.repositoryUrl,
+        `${subject.kind}:${subject.id} repositoryUrl`,
+      ) !== subject.repositoryUrl
+    ) {
+      throw new Error(
+        `${subject.kind}:${subject.id} repositoryUrl is not canonical`,
+      );
+    }
+    if (
+      !subject.path.startsWith(`${subject.repo}/`) &&
+      subject.path !== subject.repo
+    ) {
+      throw new Error(
+        `${subject.kind}:${subject.id} source path escapes ${subject.repo}`,
+      );
+    }
+    if (!subject.sourceManifestPath.startsWith(`${subject.repo}/`)) {
+      throw new Error(
+        `${subject.kind}:${subject.id} source manifest escapes ${subject.repo}`,
+      );
+    }
+    const repository = repositoryPins.get(subject.repo);
+    if (
+      !repository ||
+      repository.repositoryUrl !== subject.repositoryUrl ||
+      repository.sourceCommit !== subject.sourceCommit
+    ) {
+      throw new Error(
+        `${subject.kind}:${subject.id} does not match its repository pin`,
+      );
+    }
+  }
+  return index;
+}
+
+/** The follow-ups a re-pin owes; printed on stderr, because the repin itself changes only one field. */
+export const REPIN_CONTRACT_AUTHORITY_FOLLOW_UPS = Object.freeze([
+  'xema-edition repin-evidence-trust (with the data-root and kernel flags): the evidence trust pin binds the authority; re-pin it.',
+  'Re-resolve every edition (xema-edition resolve): each images.lock.json carries the contract authority, so its normalizedImageLockDigest changes.',
+  'Signed producer statements made under the old authority no longer verify: a statement binds the authority it was signed under, so they must be re-signed.',
+]);
+
+/**
+ * Replace ONLY `contractAuthority` of the committed runtime image source index
+ * with the one trusted from the kernel checkout at the commit the caller
+ * states (`kernelCommit`, required; HEAD must equal it), and write it back.
+ *
+ * The document is read as raw strict JSON and the field replaced BEFORE it is
+ * parsed, so a stale index cannot block its own repair (the wire schema
+ * checks the shape of `sourcePaths` only, from contracts 0.110.3).
+ * The new authority's `sourcePaths` are the set the stated commit declares,
+ * and `buildTrustedKernelContractAuthority` requires this CLI's bundled set to
+ * equal it: a repin is trusted generation at HEAD.
+ * Every repository pin and subject is kept byte for byte. Repository coverage
+ * is not asserted: this repin produces no pin, and requiring coverage would
+ * make a stale index unrepairable.
+ */
+export async function repinContractAuthority(schemas, kernelRoot, kernelCommit) {
+  const path = runtimeImageSourceIndexPath();
+  if (!existsSync(path)) {
+    throw new Error(`${path} does not exist: there is no index whose contract authority could be re-pinned`);
+  }
+  const raw = readJson(path);
+  const contractAuthority = await buildTrustedKernelContractAuthority({
+    ...(kernelRoot === undefined ? {} : { repositoryDirectory: kernelRoot }),
+    schemas,
+    kernelCommit,
+  });
+  const candidate = schemas.parseRuntimeImageSourceIndex({ ...raw, contractAuthority });
+  await validateRuntimeImageSourceIndex(candidate, schemas, {
+    assertRepositoryCoverage: false,
+    kernelRoot,
+  });
+  writeFileSync(path, serializeJson(candidate));
+  return { path, previous: raw.contractAuthority, current: contractAuthority };
+}
+
+/**
+ * `--kernel-root` names WHICH checkout of the kernel repository the committed
+ * contract authority is re-verified against. It relaxes NOTHING: the digest is
+ * still recomputed from `ls-tree` + `cat-file` blobs at the authority's own
+ * pinned commit and must match byte for byte.
+ *
+ * It exists for the reason this file already argues one function down — a
+ * development-state fact must not decide a release-composition question. The
+ * default checkout is SHARED, so it routinely sits on a stale or unrelated
+ * history, and the authority pin then fails an ancestry test that says nothing
+ * about the pin and everything about whose branch that directory is on.
+ * Measured 2026-09-14: the pin was refused as "not an ancestor of kernel HEAD"
+ * by a checkout 39 commits behind, while being a perfectly ordinary ancestor of
+ * the published history.
+ */
+function parseRepoScope(argv) {
+  const index = argv.indexOf('--repo');
+  if (index === -1) {return { repoScope: undefined, remaining: argv };}
+  const value = argv[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error('--repo requires a repository path, e.g. repos/<name>');
+  }
+  return {
+    repoScope: value,
+    remaining: [...argv.slice(0, index), ...argv.slice(index + 2)],
+  };
+}
+
+/**
+ * `--at <sha>` — pin the `--repo` repository at an EXACT commit instead of at
+ * whatever the live resolver judges newest-built. Only meaningful with `--repo`,
+ * and refused without it: "pin everything at this one commit" is not a thing.
+ */
+function parseExactCommit(argv) {
+  const index = argv.indexOf('--at');
+  if (index === -1) {return { exactCommit: undefined, remaining: argv };}
+  const value = argv[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error('--at requires a full 40-character commit sha');
+  }
+  return {
+    exactCommit: value,
+    remaining: [...argv.slice(0, index), ...argv.slice(index + 2)],
+  };
+}
+
+function parseKernelRoot(argv) {
+  const index = argv.indexOf('--kernel-root');
+  if (index === -1) {return { kernelRoot: undefined, remaining: argv };}
+  const value = argv[index + 1];
+  if (!value) {throw new Error('--kernel-root requires a directory');}
+  if (!isAbsolute(value)) {
+    throw new Error('--kernel-root requires an ABSOLUTE directory');
+  }
+  return {
+    kernelRoot: realpathSync(value),
+    remaining: [...argv.slice(0, index), ...argv.slice(index + 2)],
+  };
+}
+
+/**
+ * `--kernel-commit <40-hex>`: the kernel commit a NEW contract authority is
+ * taken from. Required wherever one is chosen (the re-pin, and a bootstrap
+ * `--trusted-write`), refused everywhere else.
+ */
+function parseKernelCommit(argv) {
+  const index = argv.indexOf(KERNEL_COMMIT_FLAG);
+  if (index === -1) {return { kernelCommit: undefined, remaining: argv };}
+  const value = argv[index + 1];
+  if (!value || !COMMIT_PATTERN.test(value)) {
+    throw new Error(`${KERNEL_COMMIT_FLAG} requires a full 40-character commit sha`);
+  }
+  return {
+    kernelCommit: value,
+    remaining: [...argv.slice(0, index), ...argv.slice(index + 2)],
+  };
+}
+
+/**
+ * @param {{ schemas: object, repositoryPins: object[], kernelRoot?: string, producerWorkflowPins?: object[], contractAuthority?: object }} request
+ * `contractAuthority`, when given, IS the index's authority (a candidate that is the kernel authority states its own,
+ * built by `buildTrustedKernelContractAuthority` as the repin does); it is then not resolved from the committed index.
+ * `kernelRoot` is the kernel checkout the committed contract authority is re-verified against
+ * (the default checkout when omitted); `producerWorkflowPins` are the operator-stated ones a
+ * trusted write merges over the committed ones.
+ * @returns {{ platformServiceIndex, biomeIndex, runtimeImageSourceIndex }}
+ */
+export async function buildIndexesAtPins({ schemas, repositoryPins, kernelRoot, producerWorkflowPins = [], contractAuthority }) {
+  const sourceAuthority = createPinnedSourceAuthority({ pins: repositoryPins });
+  const platformServiceIndex = buildValidatedPlatformServiceIndex(schemas, sourceAuthority);
+  const biomeIndex = await buildBiomeIndex(platformServiceIndex, distributionBiomeSourceRepositories(), sourceAuthority);
+  const runtimeImageSourceIndex = schemas.parseRuntimeImageSourceIndex(
+    await buildTrustedIndex(schemas, sourceAuthority, kernelRoot, undefined, {
+      biomeIndex,
+      platformServiceIndex,
+      producerWorkflowPins,
+      contractAuthority,
+    }),
+  );
+  await validateRuntimeImageSourceIndex(runtimeImageSourceIndex, schemas, { biomeIndex, platformServiceIndex, kernelRoot });
+  return { platformServiceIndex, biomeIndex, runtimeImageSourceIndex };
+}
+
+/**
+ * A repository JOINING the index (`--repo <repository>` with no committed pin): all three indexes,
+ * from ONE resolution of the joining repository, with every committed pin kept.
+ *
+ * WHY HERE AND NOT A `--repo` ON THE BIOME BUILDER. The biome builder's `--repo` was removed
+ * because it resolved the scoped repository LIVE a second time, so a build landing between the two
+ * commands split the two artifacts on exactly that repository (see `build-biome-index.mjs`). A
+ * joining repository has the same shape: the runtime index cannot take it until the biome index
+ * names its biomes, and the biome index cannot take it until a pin exists. So the joining
+ * repository is resolved ONCE here (`sourceAuthority`, live or `--at`), appended to the committed
+ * pins, and every index is derived from that one pin set by the same builders a develop snapshot
+ * uses; nothing else is resolved live.
+ *
+ * Every committed pin that survives must come back field for field; one that differs is refused by
+ * name. A committed pin whose repository is no longer a source repository is DROPPED, and the caller
+ * names it (`describeRepositoryPinChanges`). A second declared repository with no pin is refused by
+ * the pinned authority: one joining repository per write.
+ */
+export async function buildIndexesWithJoiningRepository({
+  schemas,
+  sourceAuthority,
+  repoScope,
+  committedPins,
+  kernelRoot,
+  producerWorkflowPins = [],
+}) {
+  if (committedPins.some((pin) => pin.repo === repoScope)) {
+    throw new Error(`--repo "${repoScope}" already has a committed pin: it is a refresh, not a join`);
+  }
+  const kept = committedPins.map(({ repo, repositoryUrl, sourceCommit, vendoredSourceCommit }) => ({
+    repo,
+    repositoryUrl,
+    sourceCommit,
+    vendoredSourceCommit,
+  }));
+  const repositoryPins = [...kept, repositoryIdentity(repoScope, sourceAuthority)];
+  const built = await buildIndexesAtPins({ schemas, repositoryPins, kernelRoot, producerWorkflowPins });
+  const written = new Map(built.runtimeImageSourceIndex.repositoryPins.map((pin) => [pin.repo, pin]));
+  const moved = kept.filter((pin) => written.has(pin.repo) && serializeJson(written.get(pin.repo)) !== serializeJson(pin));
+  if (moved.length > 0) {
+    throw new Error(
+      `a join must keep every committed pin, and ${moved.map((pin) => pin.repo).join(', ')} came back different ` +
+        '(its repositoryUrl no longer matches its origin remote?)',
+    );
+  }
+  if (!written.has(repoScope)) {
+    throw new Error(
+      `--repo "${repoScope}" contributes no biome, platform service or supplemental subject at ` +
+        `${repositoryPins.at(-1).sourceCommit}: there is nothing for it to join`,
+    );
+  }
+  return built;
+}
+
+/**
+ * What a write did to the committed `repositoryPins`, by NAME: the repositories added, the ones
+ * dropped (a committed pin whose repository no longer sources any subject), the ones moved, and
+ * how many were kept unchanged. A count alone hid a dropped pin inside "N other pin(s)
+ * preserved", which is the one change a reviewer must see.
+ */
+export function describeRepositoryPinChanges(committedPins, writtenPins) {
+  const committed = new Map((committedPins ?? []).map((pin) => [pin.repo, pin]));
+  const written = new Map(writtenPins.map((pin) => [pin.repo, pin]));
+  const added = [...written.keys()].filter((repo) => !committed.has(repo)).sort(compareStrings);
+  const dropped = [...committed.keys()].filter((repo) => !written.has(repo)).sort(compareStrings);
+  const moved = [...written.keys()]
+    .filter((repo) => committed.has(repo) && serializeJson(committed.get(repo)) !== serializeJson(written.get(repo)))
+    .sort(compareStrings);
+  const kept = written.size - added.length - moved.length;
+  const named = (label, repos) => `${label} ${repos.length}${repos.length > 0 ? ` (${repos.join(', ')})` : ''}`;
+  return {
+    added,
+    dropped,
+    moved,
+    kept,
+    summary: `${named('added', added)}; ${named('moved', moved)}; ${named('dropped', dropped)}; kept ${kept} unchanged`,
+  };
+}
+
+const REPIN_FLAG = '--repin-contract-authority';
+const USAGE =
+  'usage: build-runtime-image-source-index.mjs (--check | --check-sources | --trusted-write | ' +
+  '--repin-contract-authority --kernel-commit <40-hex-commit>) ' +
+  '[--source published|workspace] [--kernel-root <absolute-checkout>] ' +
+  '[--repo <repository> [--at <40-hex-commit>]] [--producer-workflow-pin <owner/repo>=<40-hex-commit> ...] ' +
+  '(--trusted-write on a data root with no committed contract authority also requires --kernel-commit)\n' +
+  `       build-runtime-image-source-index.mjs --trusted-write ${THIRD_PARTY_WRITER_USAGE}\n` +
+  `       build-runtime-image-source-index.mjs ${CHECK_THIRD_PARTY_FLAG} [--cosign <absolute cosign path>] [${CHANNEL_FLAG} <develop|release>]`;
+
+/** `--trusted-write --third-party <name>`: verify one third-party source and commit its pin, evidence and producer workflow pin. */
+async function writeThirdPartySource({ schemas, writer, cosignBinary, kernelRoot, channel }) {
+  const context = loadThirdPartySourceContext({ dataRoot: dataRoot(), schemas, cosignBinary });
+  try {
+    const plan = await planThirdPartySourceWrite({
+      request: writer,
+      context,
+      clientFor: createRegistryClientResolver({ dataRoot: dataRoot() }),
+      dataRoot: dataRoot(),
+      withProducerWorkflowPin: indexWithProducerWorkflowPin,
+      channel,
+    });
+    await validateRuntimeImageSourceIndex(plan.candidateIndex, schemas, { kernelRoot });
+    const next = commitThirdPartySourceWrite({
+      dataRoot: dataRoot(),
+      plan,
+      indexPath: runtimeImageSourceIndexPath(),
+      indexText: serializeJson(plan.candidateIndex),
+    });
+    console.log(`[runtime-image-source-index] ${next}`);
+  } finally {
+    context.dispose();
+    disposeRegistrySessions();
+  }
+}
+
+async function main() {
+  const { writer, cosignBinary, channel: statedChannel, remaining: afterThirdPartyFlags } = takeThirdPartyFlags(process.argv.slice(2));
+  const { kernelRoot, remaining: afterKernelRootFlag } = parseKernelRoot(afterThirdPartyFlags);
+  const { kernelCommit, remaining: afterKernelRoot } = parseKernelCommit(afterKernelRootFlag);
+  const { producerWorkflowPins, remaining: afterWorkflowPins } = parseProducerWorkflowPinFlags(afterKernelRoot);
+  const { repoScope, remaining: afterRepoScope } = parseRepoScope(afterWorkflowPins);
+  const { exactCommit, remaining: argv } = parseExactCommit(afterRepoScope);
+  const { mode, remaining } = parseSourceModeArgs(argv);
+  if (exactCommit !== undefined && repoScope === undefined) {
+    throw new Error('--at requires --repo: it pins ONE repository at an exact commit');
+  }
+  const [flag] = remaining;
+  if (
+    remaining.length !== 1 ||
+    ![CHECK_THIRD_PARTY_FLAG, '--check', '--check-sources', '--trusted-write', REPIN_FLAG].includes(flag)
+  ) {
+    throw new Error(USAGE);
+  }
+  if (cosignBinary !== undefined && writer === undefined && flag !== CHECK_THIRD_PARTY_FLAG) {
+    throw new Error(`--cosign belongs to ${THIRD_PARTY_FLAG} or ${CHECK_THIRD_PARTY_FLAG}: ${flag} runs no cosign\n${USAGE}`);
+  }
+  if (kernelCommit !== undefined && ![REPIN_FLAG, '--trusted-write'].includes(flag)) {
+    throw new Error(`${KERNEL_COMMIT_FLAG} states the commit of a new contract authority: ${flag} chooses none\n${USAGE}`);
+  }
+  if (statedChannel !== undefined && flag !== CHECK_THIRD_PARTY_FLAG && writer === undefined) {
+    throw new Error(`${CHANNEL_FLAG} belongs to ${THIRD_PARTY_FLAG} or ${CHECK_THIRD_PARTY_FLAG}: ${flag} takes no channel\n${USAGE}`);
+  }
+  const channel = statedChannel ?? EditionChannel.Release;
+  assertProducerWorkflowPinsWritten(producerWorkflowPins, flag, USAGE);
+  const schemas = await loadKernelDistributionSchemas();
+  if (flag === CHECK_THIRD_PARTY_FLAG) {
+    if (repoScope !== undefined || exactCommit !== undefined || kernelCommit !== undefined) {
+      throw new Error(`${CHECK_THIRD_PARTY_FLAG} re-verifies the committed third-party pins only: it takes no --repo, --at or ${KERNEL_COMMIT_FLAG}`);
+    }
+    const { checked } = await checkThirdPartySourcePins({ dataRoot: dataRoot(), schemas, cosignBinary, channel });
+    console.log(
+      checked === 0
+        ? '[runtime-image-source-index] no third-party source is pinned in this data root'
+        : `[runtime-image-source-index] third-party source check passed for ${checked} pinned source(s)`,
+    );
+    return;
+  }
+  if (writer !== undefined) {
+    if (flag !== '--trusted-write') {
+      throw new Error(`${THIRD_PARTY_FLAG} writes a pin: it takes --trusted-write\n${USAGE}`);
+    }
+    if (repoScope !== undefined || exactCommit !== undefined || kernelCommit !== undefined || producerWorkflowPins.length > 0) {
+      throw new Error(`${THIRD_PARTY_FLAG} writes one third-party pin: it takes no --repo, --at, ${KERNEL_COMMIT_FLAG} or ${PRODUCER_WORKFLOW_PIN_FLAG}`);
+    }
+    await writeThirdPartySource({ schemas, writer, cosignBinary, kernelRoot, channel });
+    return;
+  }
+  if (flag === REPIN_FLAG) {
+    if (repoScope !== undefined || exactCommit !== undefined) {
+      throw new Error(`${REPIN_FLAG} replaces the contract authority only: it takes no --repo or --at`);
+    }
+    if (kernelCommit === undefined) {
+      throw new Error(`${REPIN_FLAG} requires ${KERNEL_COMMIT_FLAG} <40-hex-commit>: the commit the authority moves to is stated, never read from the checkout\n${USAGE}`);
+    }
+    const { path, previous, current } = await repinContractAuthority(schemas, kernelRoot, kernelCommit);
+    console.log(
+      `[runtime-image-source-index] wrote ${path} (contract authority ${previous?.sourceCommit ?? 'absent'} -> ${current.sourceCommit}; every repository pin and subject preserved)`,
+    );
+    for (const followUp of REPIN_CONTRACT_AUTHORITY_FOLLOW_UPS) {
+      console.error(`[runtime-image-source-index] owed after the re-pin: ${followUp}`);
+    }
+    return;
+  }
+  if (
+    !existsSync(runtimeImageSourceIndexPath()) &&
+    flag !== '--trusted-write'
+  ) {
+    throw new Error(`${runtimeImageSourceIndexPath()} does not exist`);
+  }
+  if (flag === '--check') {
+    const parsed = schemas.parseRuntimeImageSourceIndex(
+      readJson(runtimeImageSourceIndexPath()),
+    );
+    await validateRuntimeImageSourceIndex(parsed, schemas, { kernelRoot });
+    console.log(
+      `[runtime-image-source-index] offline check passed for ${parsed.supplementalSubjects.length} supplemental subjects and ${parsed.platformServiceBindings.length} bindings`,
+    );
+    return;
+  }
+  const committedPins = existsSync(runtimeImageSourceIndexPath())
+    ? readJson(runtimeImageSourceIndexPath()).repositoryPins ?? []
+    : [];
+  const liveAuthority = () => createSourceAuthority({ mode, knownRepositories: declaredSourceRepositories() });
+  const sourceAuthority =
+    exactCommit === undefined
+      ? liveAuthority()
+      : createExactCommitSourceAuthority({ delegate: liveAuthority(), repo: repoScope, commit: exactCommit });
+  // A `--repo` with no committed pin JOINS the index, and the biome and platform-service indexes
+  // must take it in the same write: see `buildIndexesWithJoiningRepository`.
+  const joining = repoScope !== undefined && !committedPins.some((pin) => pin.repo === repoScope);
+  let candidate;
+  let joined;
+  if (joining) {
+    if (committedPins.length === 0) {
+      throw new Error(
+        `--repo requires ${runtimeImageSourceIndexPath()} with committed repositoryPins: there are none to keep. ` +
+          'Bootstrap with --trusted-write and no --repo.',
+      );
+    }
+    if (kernelCommit !== undefined) {
+      throw new Error(`${KERNEL_COMMIT_FLAG} chooses a new contract authority; a join keeps the committed one`);
+    }
+    joined = await buildIndexesWithJoiningRepository({
+      schemas,
+      sourceAuthority,
+      repoScope,
+      committedPins,
+      kernelRoot,
+      producerWorkflowPins,
+    });
+    candidate = joined.runtimeImageSourceIndex;
+  } else {
+    candidate = schemas.parseRuntimeImageSourceIndex(
+      await buildTrustedIndex(schemas, sourceAuthority, kernelRoot, repoScope, {
+        biomeIndex: readJson(biomeIndexPath()),
+        platformServiceIndex: readJson(join(dataRoot(), 'platform-service-index.json')),
+        kernelCommit,
+        producerWorkflowPins,
+      }),
+    );
+    await validateRuntimeImageSourceIndex(candidate, schemas, { kernelRoot });
+  }
+  const outputs = [
+    [runtimeImageSourceIndexPath(), serializeJson(candidate)],
+    ...(joined === undefined
+      ? []
+      : [
+          [biomeIndexPath(), serializeJson(joined.biomeIndex)],
+          [platformServiceIndexPath(), serializeJson(joined.platformServiceIndex)],
+        ]),
+  ];
+  if (flag === '--check-sources') {
+    const stale = outputs.filter(([path, text]) => !existsSync(path) || readFileSync(path, 'utf8') !== text);
+    if (stale.length > 0) {
+      throw new Error(
+        `${stale.map(([path]) => path).join(', ')} does not match exact trusted sources`,
+      );
+    }
+    console.log('[runtime-image-source-index] trusted source check passed');
+    return;
+  }
+  for (const [path, text] of outputs) {writeFileSync(path, text);}
+  const changes = describeRepositoryPinChanges(committedPins, candidate.repositoryPins);
+  console.log(
+    `[runtime-image-source-index] wrote ${outputs.map(([path]) => path).join(', ')} (${
+      repoScope === undefined
+        ? 'all repository pins re-resolved'
+        : `${joining ? 'joined' : 're-resolved'} ${repoScope}${
+            exactCommit === undefined ? '' : ` at the exact commit ${exactCommit}`
+          }`
+    }; ${changes.summary})`,
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[runtime-image-source-index] ${error.message}`);
+    process.exitCode = 1;
+  });
+}