@xemahq/xema 0.25.1 → 0.27.0

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

@@ -0,0 +1,821 @@
+#!/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 { connectorCrossRepoBuildInputs } from './connector-source-authority.mjs';
+import { editionWorkspaceConfig, workspaceSection } from './edition-config.mjs';
+import { biomeIndexPath, dataRoot, runtimeImageSourceIndexPath, WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath } from './edition-workspace.mjs';
+import {
+  buildTrustedKernelContractAuthority,
+  describeKernelContractAuthorityDrift,
+  validateKernelContractAuthorityFromGit,
+} from './kernel-contract-authority.mjs';
+import {
+  canonicalPublicHttpsRepositoryUrl,
+  compareStrings,
+  loadKernelDistributionSchemas,
+  readGitJsonAtCommit,
+  serializeJson,
+  sha256Hex,
+} from './lib.mjs';
+import {
+  platformServiceRuntimeBindings,
+} from './platform-service-source-authority.mjs';
+import {
+  createExactCommitSourceAuthority,
+  createSourceAuthority,
+  parseSourceModeArgs,
+} from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.SourceHash]);
+}
+
+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.
+ */
+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  ')}`,
+    );
+  }
+}
+
+/**
+ * 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 where local HEAD is the honest source: there is
+ * no committed index to preserve, so there is no prior decision to respect.
+ */
+async function resolveContractAuthority(schemas, kernelRoot) {
+  const repositoryDirectory = kernelRoot ?? undefined;
+  if (!existsSync(runtimeImageSourceIndexPath())) {
+    return buildTrustedKernelContractAuthority({ schemas });
+  }
+  const committed = readJson(runtimeImageSourceIndexPath());
+  if (!committed?.contractAuthority) {
+    return buildTrustedKernelContractAuthority({ schemas });
+  }
+  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".
+ */
+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',
+    );
+  }
+  if (!pins.some((pin) => pin.repo === repoScope)) {
+    throw new Error(
+      `--repo "${repoScope}" has no committed pin to refresh. A repository ` +
+        `joining this index is a full --trusted-write, not a scoped refresh.`,
+    );
+  }
+  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(),
+  );
+}
+
+/**
+ * `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 },
+) {
+  const contractAuthority = await resolveContractAuthority(schemas, kernelRoot);
+  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) {
+      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 crossRepoBuildInputs = [...crossRepoBuildInputs()].sort(
+    (left, right) =>
+      compareStrings(
+        [left.consumerRepo, left.consumerService, left.destinationPath].join(
+          '\u0000',
+        ),
+        [right.consumerRepo, right.consumerService, right.destinationPath].join(
+          '\u0000',
+        ),
+      ),
+  );
+  assertVendoredSourcesResolve(crossRepoBuildInputs, 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 crossRepoBuildInputs) {
+    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: 1,
+    contractAuthority,
+    supplementalSubjects,
+    crossRepoBuildInputs,
+    buildStepContextDirectories,
+    repositoryPins,
+    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)
+  );
+}
+
+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`);
+    }
+  }
+  // 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, and write it back.
+ *
+ * The document is read as raw strict JSON and the field replaced BEFORE it is
+ * parsed: the kernel's schema refuses an index whose authority `sourcePaths`
+ * differ from the bundled constant, so a stale index cannot be parsed first.
+ * 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) {
+  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,
+  });
+  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)],
+  };
+}
+
+const REPIN_FLAG = '--repin-contract-authority';
+
+async function main() {
+  const { kernelRoot, remaining: afterKernelRoot } = parseKernelRoot(
+    process.argv.slice(2),
+  );
+  const { repoScope, remaining: afterRepoScope } = parseRepoScope(afterKernelRoot);
+  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', '--check-sources', '--trusted-write', REPIN_FLAG].includes(flag)
+  ) {
+    throw new Error(
+      'usage: build-runtime-image-source-index.mjs (--check | --check-sources | --trusted-write | --repin-contract-authority) ' +
+        '[--source published|workspace] [--kernel-root <absolute-checkout>] ' +
+        '[--repo <repository> [--at <40-hex-commit>]]',
+    );
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  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`);
+    }
+    const { path, previous, current } = await repinContractAuthority(schemas, kernelRoot);
+    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 candidate = schemas.parseRuntimeImageSourceIndex(
+    await buildTrustedIndex(
+      schemas,
+      exactCommit === undefined
+        ? createSourceAuthority({
+            mode,
+            knownRepositories: declaredSourceRepositories(),
+          })
+        : createExactCommitSourceAuthority({
+            delegate: createSourceAuthority({
+              mode,
+              knownRepositories: declaredSourceRepositories(),
+            }),
+            repo: repoScope,
+            commit: exactCommit,
+          }),
+      kernelRoot,
+      repoScope,
+      {
+        biomeIndex: readJson(biomeIndexPath()),
+        platformServiceIndex: readJson(join(dataRoot(), 'platform-service-index.json')),
+      },
+    ),
+  );
+  await validateRuntimeImageSourceIndex(candidate, schemas, { kernelRoot });
+  if (flag === '--check-sources') {
+    if (
+      readFileSync(runtimeImageSourceIndexPath(), 'utf8') !==
+      serializeJson(candidate)
+    ) {
+      throw new Error(
+        'runtime-image-source-index.json does not match exact trusted sources',
+      );
+    }
+    console.log('[runtime-image-source-index] trusted source check passed');
+    return;
+  }
+  writeFileSync(runtimeImageSourceIndexPath(), serializeJson(candidate));
+  console.log(
+    `[runtime-image-source-index] wrote ${runtimeImageSourceIndexPath()}` +
+      (repoScope === undefined
+        ? ' (all repository pins re-resolved)'
+        : ` (${
+            exactCommit === undefined
+              ? `re-resolved ${repoScope}`
+              : `pinned ${repoScope} at the exact commit ${exactCommit}`
+          }; ${candidate.repositoryPins.length - 1} other pin(s) preserved)`),
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[runtime-image-source-index] ${error.message}`);
+    process.exitCode = 1;
+  });
+}