@xemahq/xema 0.32.0 → 0.33.0

package/edition/edition-pin-verbs.mjs

@@ -0,0 +1,183 @@
+// edition-pin-verbs — `xema edition pin` and `xema edition unpin`: the only
+// supported way to change a vendor edition's `sourcePins` (edition-source-pins.mjs).
+//
+// `pin` validates the hold with the SAME checks a resolve applies
+// (`effectiveRepositoryPins`: graph repository, not the kernel, not equal to the
+// shared pin; `assertEditionPinsAuthorized`: commit present, contained in
+// origin/main, built), writes the entry into the edition's definition keeping
+// its formatting and key order, and re-resolves the edition. `unpin` removes one
+// entry (or all), drops the key when empty, and re-resolves. Both are all or
+// nothing: a failed re-resolve restores the edition directory byte for byte.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import {
+  assertEditionPinsAuthorized,
+  effectiveRepositoryPins,
+  parseEditionSourcePins,
+  SOURCE_PINS_KEY,
+} from './edition-source-pins.mjs';
+import { editionsRoot, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { writeResolvedLockSet } from './resolve-edition.mjs';
+import { loadBuildLedger } from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+export const PIN_USAGE =
+  'usage: xema edition pin <edition> <repo> <ref> --until "<exit condition>" --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>';
+export const UNPIN_USAGE =
+  'usage: xema edition unpin <edition> [<repo>] --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>';
+
+const UNTIL_FLAG = '--until';
+
+/** `{ positional, until }` from the arguments after the root flags. */
+export function parsePinArgs(args) {
+  const positional = [];
+  let until;
+  for (let i = 0; i < args.length; i += 1) {
+    const argument = args[i];
+    if (argument === UNTIL_FLAG || argument.startsWith(`${UNTIL_FLAG}=`)) {
+      if (until !== undefined) {throw new Error(`${UNTIL_FLAG} given twice\n${PIN_USAGE}`);}
+      until = argument === UNTIL_FLAG ? args[(i += 1)] : argument.slice(UNTIL_FLAG.length + 1);
+    } else if (argument.startsWith('--')) {
+      throw new Error(`unexpected argument ${JSON.stringify(argument)}\n${PIN_USAGE}`);
+    } else {
+      positional.push(argument);
+    }
+  }
+  return { positional, until };
+}
+
+const definitionPath = (id) => join(editionsRoot(), id, 'xema-distribution.json');
+
+/** The file text and its parsed document; the text is what a rewrite preserves. */
+function readDefinition(id) {
+  assertCanonicalDistributionId(id);
+  const path = definitionPath(id);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    throw new Error(`edition "${id}" not found: ${path} does not exist`);
+  }
+  return { path, text, document: readStrictJsonFile(path) };
+}
+
+/** The indent unit (a tab or the spaces of the first indented line) and the trailing newline of `text`. */
+function formatOf(text) {
+  const indent = /^([ \t]+)\S/mu.exec(text)?.[1] ?? '  ';
+  return { indent, trailingNewline: text.endsWith('\n') };
+}
+
+/** `document` serialized in the format of the file it was read from. */
+function render(document, text) {
+  const { indent, trailingNewline } = formatOf(text);
+  return `${JSON.stringify(document, null, indent)}${trailingNewline ? '\n' : ''}`;
+}
+
+/** The document with `sourcePins` set (appended last when new, in place when present) or, for none, removed. */
+function withSourcePins(document, sourcePins) {
+  if (sourcePins.length === 0) {
+    const { [SOURCE_PINS_KEY]: _removed, ...rest } = document;
+    return rest;
+  }
+  return { ...document, [SOURCE_PINS_KEY]: sourcePins };
+}
+
+/** Every file under `directory` (relative path to bytes), the pre-command state a failed command returns to. */
+function snapshotDirectory(directory) {
+  const files = new Map();
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {walk(path);} else {files.set(path, readFileSync(path));}
+    }
+  };
+  walk(directory);
+  return files;
+}
+
+/** Return `directory` to `snapshot` byte for byte: rewrite what changed, delete what the command added. */
+function restoreDirectory(directory, snapshot) {
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {walk(path);} else if (!snapshot.has(path)) {rmSync(path);}
+    }
+  };
+  walk(directory);
+  for (const [path, bytes] of snapshot) {
+    if (!existsSync(path) || !readFileSync(path).equals(bytes)) {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, bytes);
+    }
+  }
+}
+
+/**
+ * Write the definition and re-resolve, all or nothing: on any failure the
+ * edition directory (definition and every lock the resolve wrote) is restored
+ * to its exact prior bytes and the original error is rethrown.
+ */
+async function writeAndReresolve({ id, path, rendered }) {
+  const directory = dirname(path);
+  const snapshot = snapshotDirectory(directory);
+  try {
+    writeFileSync(path, rendered);
+    await writeResolvedLockSet(id);
+  } catch (error) {
+    restoreDirectory(directory, snapshot);
+    throw error;
+  }
+}
+
+/**
+ * Hold `repo` of edition `id` at `ref` until `until`, then re-resolve it. An
+ * existing hold of the same repository is replaced.
+ */
+export async function pinEdition({ id, repo, ref, until, schemas, log = console.log }) {
+  const { path, text, document } = readDefinition(id);
+  const current = parseEditionSourcePins(document[SOURCE_PINS_KEY], id);
+  const entry = parseEditionSourcePins([{ repo, ref, until }], id)[0];
+  const sourcePins = current.some((pin) => pin.repo === repo)
+    ? current.map((pin) => (pin.repo === repo ? entry : pin))
+    : [...current, entry];
+  const committed = schemas.parseRuntimeImageSourceIndex(readStrictJsonFile(runtimeImageSourceIndexPath()));
+  effectiveRepositoryPins(committed.repositoryPins, sourcePins, { id, contractAuthority: committed.contractAuthority });
+  assertEditionPinsAuthorized({ id, sourcePins: [entry], ledger: loadBuildLedger() });
+  await writeAndReresolve({ id, path, rendered: render(withSourcePins(document, sourcePins), text) });
+  log(`[edition:pin] ${id}: holding ${repo} @${ref.slice(0, 12)} until: ${until}`);
+  return sourcePins;
+}
+
+/** Remove the hold on `repo` (or every hold) of edition `id`, then re-resolve it. */
+export async function unpinEdition({ id, repo, log = console.log }) {
+  const { path, text, document } = readDefinition(id);
+  const current = parseEditionSourcePins(document[SOURCE_PINS_KEY], id);
+  if (current.length === 0) {
+    log(`[edition:unpin] ${id}: holds nothing`);
+    return current;
+  }
+  if (repo !== undefined && !current.some((pin) => pin.repo === repo)) {
+    throw new Error(`edition "${id}" does not hold ${repo} (it holds: ${current.map((pin) => pin.repo).join(', ')})`);
+  }
+  const sourcePins = repo === undefined ? [] : current.filter((pin) => pin.repo !== repo);
+  await writeAndReresolve({ id, path, rendered: render(withSourcePins(document, sourcePins), text) });
+  log(`[edition:unpin] ${id}: released ${repo ?? current.map((pin) => pin.repo).join(', ')}`);
+  return sourcePins;
+}
+
+export async function runPin(args) {
+  const { positional, until } = parsePinArgs(args);
+  if (positional.length !== 3 || until === undefined) {throw new Error(PIN_USAGE);}
+  const [id, repo, ref] = positional;
+  await pinEdition({ id, repo, ref, until, schemas: await loadKernelDistributionSchemas() });
+}
+
+export async function runUnpin(args) {
+  const { positional, until } = parsePinArgs(args);
+  if (positional.length < 1 || positional.length > 2 || until !== undefined) {throw new Error(UNPIN_USAGE);}
+  await unpinEdition({ id: positional[0], repo: positional[1] });
+}

package/edition/edition-pin.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// `xema edition pin <edition> <repo> <ref> --until "<exit condition>"`: hold one
+// repository of a vendor edition at an exact commit, then re-resolve the edition.
+// The logic is edition-pin-verbs.mjs; see edition-source-pins.mjs for the trust it applies.
+//
+// usage: xema edition pin <edition> <repo> <ref> --until "<exit condition>" --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>
+
+import { runPin } from './edition-pin-verbs.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
+  runPin(process.argv.slice(2)).catch((error) => {
+    console.error(`[edition:pin] ${error.message}`);
+    process.exit(1);
+  });
+}

package/edition/edition-pinned-inputs.mjs

@@ -0,0 +1,116 @@
+// edition-pinned-inputs — the ONE per-edition source of the indexes an edition
+// resolves from, and of the repository pins it resolves at.
+//
+// An edition that holds no repository (no `sourcePins`, edition-source-pins.mjs)
+// reads the committed data-root files exactly as before: nothing is rebuilt.
+// An edition that holds repositories has its three indexes rebuilt at ITS
+// effective pins by the release builders (indexes-at-pins.mjs), after every
+// held commit is authorized. Every per-edition reader (resolve, images, check,
+// seal, catalogue, biome manifests) takes its indexes and pins from here, so a
+// held edition carries the held commit everywhere and none can read the shared
+// pin by the back door.
+//
+// A develop snapshot replaces ALL pins and does not come through here:
+// `sourcePins` do not apply on the develop channel.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+
+import { assertEditionPinsAuthorized, effectiveRepositoryPins, EditionSourcePinsError, readEditionSourcePins } from './edition-source-pins.mjs';
+import { biomeIndexPath, dataRoot, editionsRoot, platformServiceIndexPath, runtimeImageSourceIndexPath, sourcesRoot } from './edition-workspace.mjs';
+import { buildIndexesAtPins } from './indexes-at-pins.mjs';
+import { commandFor } from './remedy-command.mjs';
+import { committedRepositoryPins, loadBuildLedger } from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+function readCommitted(path, remedy) {
+  if (!existsSync(path)) {
+    throw new Error(`${path} not found — ${remedy}`);
+  }
+  return readStrictJsonFile(path);
+}
+
+/**
+ * The bypass guard: the rebuilt runtime index must carry exactly the effective
+ * pins on both axes. A builder that re-decided a held repository would
+ * otherwise resolve it at a commit nobody authorized.
+ */
+function assertRebuiltPinsAreEffective({ id, runtimeImageSourceIndex, repositoryPins }) {
+  const rebuilt = new Map(runtimeImageSourceIndex.repositoryPins.map((pin) => [pin.repo, pin]));
+  const mismatches = repositoryPins.filter((pin) => {
+    const actual = rebuilt.get(pin.repo);
+    return actual === undefined || actual.sourceCommit !== pin.sourceCommit || actual.vendoredSourceCommit !== pin.vendoredSourceCommit;
+  });
+  if (mismatches.length > 0 || rebuilt.size !== repositoryPins.length) {
+    throw new EditionSourcePinsError(
+      `edition "${id}": the indexes rebuilt at its held pins do not carry the effective repository pins ` +
+        `(${mismatches.map((pin) => pin.repo).join(', ') || 'repository set differs'}); refusing to resolve`,
+    );
+  }
+}
+
+const memo = new Map();
+
+async function heldInputs({ id, sourcePins, committed, schemas }) {
+  const repositoryPins = effectiveRepositoryPins(committed.repositoryPins, sourcePins, { id, contractAuthority: committed.contractAuthority });
+  assertEditionPinsAuthorized({ id, sourcePins, ledger: loadBuildLedger() });
+  const built = await buildIndexesAtPins({ schemas, repositoryPins });
+  assertRebuiltPinsAreEffective({ id, runtimeImageSourceIndex: built.runtimeImageSourceIndex, repositoryPins });
+  return { ...built, repositoryPins, held: true, sourcePins };
+}
+
+/**
+ * An edition that holds nothing reads the committed data-root files, each ONLY
+ * when a reader asks for it, as each reader read its own file before: a
+ * resolve needs no runtime image source index, a seal needs no platform-service
+ * index. A missing file refuses at the point of use, naming itself.
+ */
+function committedInputs({ schemas, sourcePins }) {
+  const cache = new Map();
+  const once = (name, read) => {
+    if (!cache.has(name)) {cache.set(name, read());}
+    return cache.get(name);
+  };
+  return {
+    get runtimeImageSourceIndex() {
+      return once('runtime', () => schemas.parseRuntimeImageSourceIndex(readStrictJsonFile(runtimeImageSourceIndexPath())));
+    },
+    get biomeIndex() {
+      return once('biome', () => readCommitted(biomeIndexPath(), `run \`${commandFor('build-biome-index.mjs')}\` first`));
+    },
+    get platformServiceIndex() {
+      return once('platform', () =>
+        schemas.parsePlatformServiceSourceIndex(
+          readCommitted(platformServiceIndexPath(), 'run the trusted platform-service index generator first'),
+        ),
+      );
+    },
+    get repositoryPins() {
+      return effectiveRepositoryPins(committedRepositoryPins(), sourcePins);
+    },
+    held: false,
+    sourcePins,
+  };
+}
+
+/**
+ * @param {string} id the edition
+ * @param {{ schemas: object }} kernel the loaded kernel distribution schemas
+ * @returns {Promise<{ runtimeImageSourceIndex, biomeIndex, platformServiceIndex, repositoryPins, held: boolean, sourcePins }>}
+ *
+ * The held (rebuilt) result is memoized per configured roots, edition, declared
+ * pins and committed runtime index, so one process pays the rebuild once.
+ */
+export async function editionPinnedInputs(id, { schemas }) {
+  const sourcePins = readEditionSourcePins(id);
+  if (sourcePins.length === 0) {return committedInputs({ schemas, sourcePins });}
+  const indexText = readFileSync(runtimeImageSourceIndexPath(), 'utf8');
+  const committed = schemas.parseRuntimeImageSourceIndex(readStrictJsonFile(runtimeImageSourceIndexPath()));
+  const key = JSON.stringify([dataRoot(), editionsRoot(), sourcesRoot(), id, sourcePins, createHash('sha256').update(indexText).digest('hex')]);
+  if (!memo.has(key)) {
+    const pending = heldInputs({ id, sourcePins, committed, schemas });
+    memo.set(key, pending);
+    pending.catch(() => memo.delete(key));
+  }
+  return memo.get(key);
+}

package/edition/edition-source-pins.mjs

@@ -0,0 +1,209 @@
+// edition-source-pins — a vendor edition's per-edition source pins: the one
+// place that parses the declaration, computes the effective repository pins and
+// authorizes a held commit.
+//
+// A vendor edition's `xema-distribution.json` MAY carry the CLI-owned top-level
+// key `sourcePins`, `[{ repo, ref, until }]`: this edition resolves `repo` at the
+// exact commit `ref` instead of at the data root's shared `repositoryPins`, and
+// `until` states the condition under which the hold ends. Entries are sparse:
+// one exists only for a repository the edition holds back, so an entry equal to
+// the shared pin is refused (it is not a hold). `xema edition pin|unpin` are the
+// only supported way to change them. It is a
+// CLI key, not a kernel one: the kernel's `parseDistribution` is strict, so the
+// key is REMOVED before the kernel parse (the precedent is a customer
+// definition's `imageRegistryMirror`, customer-definition.mjs), by the one
+// splitter below. Every reader of an edition definition goes through it.
+//
+// `effectiveRepositoryPins` is the ONLY computation of an edition's pins: the
+// committed pins untouched (the same array) when the edition holds nothing,
+// else a copy whose held repositories carry the ref on BOTH axes (`sourceCommit`
+// and `vendoredSourceCommit`), as `createExactCommitSourceAuthority` does.
+//
+// A held commit is authorized, never trusted (`assertEditionPinsAuthorized`):
+// the commit object exists, it is contained in the published ref, and it is a
+// BUILT commit (the same predicate `publishedSourceCommit` uses). No flag or
+// path overrides any of the three.
+//
+// This module is pure of the index builders on purpose: the evidence verifier
+// reads the declaration through it and must not bundle the release builders
+// (edition-pinned-inputs.mjs owns those).
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { editionsRoot, sourcesRoot } from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import { builtCommits, PUBLISHED_SOURCE_REF } from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+export const SOURCE_PINS_KEY = 'sourcePins';
+
+const SOURCE_PIN_KEYS = Object.freeze(['ref', 'repo', 'until']);
+const GRAPH_REPO = /^(repos|submodules)\/[a-z0-9][a-z0-9-]*$/;
+
+/** A refusal of an edition's `sourcePins` declaration or of a held commit. */
+export class EditionSourcePinsError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'EditionSourcePinsError';
+  }
+}
+
+const label = (id) => (id === undefined ? '' : `edition "${id}": `);
+
+/**
+ * Strictly parse the value of `sourcePins`. Absent (`undefined`) is no pins.
+ * Present, it is a non-empty array of exactly `{repo, ref, until}` objects,
+ * `repo` a graph repository path, `ref` an exact lowercase 40-hex commit (never
+ * a branch, which would move under a lock), `until` the non-empty exit
+ * condition of the hold, no repository twice.
+ */
+export function parseEditionSourcePins(raw, id) {
+  if (raw === undefined) {return [];}
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new EditionSourcePinsError(`${label(id)}"${SOURCE_PINS_KEY}" must be a non-empty array of {repo, ref, until}; got ${JSON.stringify(raw)}`);
+  }
+  const seen = new Set();
+  return raw.map((entry, index) => {
+    const where = `${label(id)}${SOURCE_PINS_KEY}[${index}] ${JSON.stringify(entry)}`;
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).sort().join() !== SOURCE_PIN_KEYS.join()) {
+      throw new EditionSourcePinsError(`${where} must be exactly {repo, ref, until}; \`until\` (the exit condition of the hold) is required`);
+    }
+    if (typeof entry.repo !== 'string' || !GRAPH_REPO.test(entry.repo)) {
+      throw new EditionSourcePinsError(`${where}: repo must be a repository path (repos/<name> or submodules/<name>)`);
+    }
+    if (typeof entry.ref !== 'string' || !COMMIT_PATTERN.test(entry.ref)) {
+      throw new EditionSourcePinsError(`${where}: ref must be an exact lowercase 40-hex commit, not a branch, tag or abbreviation`);
+    }
+    if (typeof entry.until !== 'string' || entry.until.trim().length === 0) {
+      throw new EditionSourcePinsError(`${where}: until must be non-empty text stating when the hold ends`);
+    }
+    if (seen.has(entry.repo)) {
+      throw new EditionSourcePinsError(`${where}: repo ${entry.repo} is pinned twice`);
+    }
+    seen.add(entry.repo);
+    return Object.freeze({ repo: entry.repo, ref: entry.ref, until: entry.until });
+  });
+}
+
+/**
+ * Split a raw edition definition into the document the kernel parses (without
+ * the CLI key) and the parsed `sourcePins`. A value that is not an object is
+ * returned as it is for the kernel to refuse.
+ */
+export function splitEditionDefinition(raw, id) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw) || !Object.hasOwn(raw, SOURCE_PINS_KEY)) {
+    return { document: raw, sourcePins: [] };
+  }
+  const { [SOURCE_PINS_KEY]: declared, ...document } = raw;
+  return { document, sourcePins: parseEditionSourcePins(declared, id) };
+}
+
+/** The `sourcePins` of edition `id`, read from the configured editions root. */
+export function readEditionSourcePins(id) {
+  const path = join(editionsRoot(), id, 'xema-distribution.json');
+  if (!existsSync(path)) {
+    throw new Error(`distribution "${id}" not found: ${path} does not exist`);
+  }
+  return splitEditionDefinition(readStrictJsonFile(path), id).sourcePins;
+}
+
+/** A repository URL without a trailing `.git`, so the two forms a pin may carry compare equal. */
+const canonicalRepositoryUrl = (url) => String(url).replace(/\.git$/u, '');
+
+/**
+ * The repository pins edition `id` resolves at. With nothing held, the
+ * committed array itself. A held repository must be in the graph (committed
+ * pins) and must not be the kernel contract repository, read from the index's
+ * own `contractAuthority.repositoryUrl` (data, so the evidence verifier applies
+ * the same rule): the kernel contract authority stays data-root-wide.
+ */
+export function effectiveRepositoryPins(committedRepositoryPins, sourcePins, { id, contractAuthority } = {}) {
+  if (sourcePins === undefined || sourcePins.length === 0) {return committedRepositoryPins;}
+  if (typeof contractAuthority?.repositoryUrl !== 'string') {
+    throw new EditionSourcePinsError(`${label(id)}held pins are computed against the index's contractAuthority, and none was given`);
+  }
+  const kernelUrl = canonicalRepositoryUrl(contractAuthority.repositoryUrl);
+  const held = new Map(sourcePins.map((pin) => [pin.repo, pin.ref]));
+  for (const repo of held.keys()) {
+    const committed = committedRepositoryPins.find((pin) => pin.repo === repo);
+    if (committed === undefined) {
+      throw new EditionSourcePinsError(
+        `${label(id)}${SOURCE_PINS_KEY} holds ${repo}, which has no repository pin in runtime-image-source-index.json (not an image source repository)`,
+      );
+    }
+    const ref = held.get(repo);
+    if (committed.sourceCommit === ref && committed.vendoredSourceCommit === ref) {
+      throw new EditionSourcePinsError(
+        `${label(id)}${SOURCE_PINS_KEY} entry for ${repo} is not a hold: ${ref} is the shared repository pin; remove it (xema edition unpin)`,
+      );
+    }
+    if (canonicalRepositoryUrl(committed.repositoryUrl) === kernelUrl) {
+      throw new EditionSourcePinsError(
+        `${label(id)}${SOURCE_PINS_KEY} may not hold ${repo}: it is the kernel contract repository, whose authority is the data root's alone`,
+      );
+    }
+  }
+  return committedRepositoryPins.map((pin) =>
+    held.has(pin.repo) ? { ...pin, sourceCommit: held.get(pin.repo), vendoredSourceCommit: held.get(pin.repo) } : pin,
+  );
+}
+
+function git(directory, args) {
+  return execFileSync('git', ['-C', directory, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function refusalsOf({ pin, directory, ledger }) {
+  const { repo, ref } = pin;
+  let resolved;
+  try {
+    resolved = git(directory, ['rev-parse', '--verify', `${ref}^{commit}`]);
+  } catch {
+    return [`${repo}@${ref}: no such commit in ${directory}; fetch it before holding it`];
+  }
+  if (resolved !== ref) {return [`${repo}@${ref}: resolves to ${resolved}; name the commit itself`];}
+  try {
+    git(directory, ['rev-parse', '--verify', `${PUBLISHED_SOURCE_REF}^{commit}`]);
+  } catch {
+    return [`${repo}@${ref}: ${repo} has no ${PUBLISHED_SOURCE_REF}, so containment cannot be shown; a held commit must be published`];
+  }
+  try {
+    git(directory, ['merge-base', '--is-ancestor', ref, PUBLISHED_SOURCE_REF]);
+  } catch {
+    return [`${repo}@${ref}: not contained in ${PUBLISHED_SOURCE_REF}; a held commit must be published, or a consumer cannot fetch it`];
+  }
+  const built = builtCommits(directory, PUBLISHED_SOURCE_REF, repo, ledger);
+  // A held repository always has a runtime-image-source pin, so `null` (neither record knows it) means the build evidence is missing.
+  if (built === null) {return [`${repo}@${ref}: no build record for ${repo}; a held commit must be one an image was built from`];}
+  if (built.has(ref)) {return [];}
+  return [`${repo}@${ref}: not a built commit (in neither the build ledger nor the evidence tree); a held commit must be one an image was built from`];
+}
+
+/**
+ * Authorize every held commit of edition `id` against its source checkout
+ * under `repoRoot`: present, contained in the published ref (a missing ref
+ * refuses, never skips) and built. Throws once, listing every refusal.
+ */
+export function assertEditionPinsAuthorized({ id, sourcePins, repoRoot = sourcesRoot(), ledger }) {
+  const refusals = sourcePins.flatMap((pin) => refusalsOf({ pin, directory: resolve(repoRoot, pin.repo), ledger }));
+  if (refusals.length > 0) {
+    throw new EditionSourcePinsError(
+      `${label(id)}${refusals.length} held source pin(s) refused:\n  ${refusals.join('\n  ')}`,
+    );
+  }
+}
+
+/**
+ * The report `xema edition check` prints: one line per active hold of the given
+ * editions, then a count line. Informational, never a failure.
+ */
+export function describeEditionHolds(ids, read = readEditionSourcePins) {
+  const lines = ids.flatMap((id) =>
+    read(id).map((pin) => `[dist:check] hold: ${id} ${pin.repo} @${pin.ref.slice(0, 12)} until: ${pin.until}`),
+  );
+  return [...lines, lines.length === 0 ? '[dist:check] no holds' : `[dist:check] ${lines.length} hold(s) active`];
+}

package/edition/edition-unpin.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// `xema edition unpin <edition> [<repo>]`: release one hold (or all) of a vendor
+// edition, then re-resolve the edition. The logic is edition-pin-verbs.mjs.
+//
+// usage: xema edition unpin <edition> [<repo>] --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>
+
+import { runUnpin } from './edition-pin-verbs.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
+  runUnpin(process.argv.slice(2)).catch((error) => {
+    console.error(`[edition:unpin] ${error.message}`);
+    process.exit(1);
+  });
+}

package/edition/image-evidence.mjs

@@ -18,6 +18,7 @@ import {
 import { TextDecoder } from 'node:util';
 
 import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { effectiveRepositoryPins, splitEditionDefinition } from './edition-source-pins.mjs';
 import { SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
 import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
 import {
@@ -1316,19 +1317,24 @@ export async function loadValidatedImageLocks(
       'images.lock.json kernel contract authority does not exactly match runtime-image-source-index.json',
     );
   }
-  const repositoryPins = new Map(
-    runtimeSourceIndex.repositoryPins.map((repository) => [
-      repository.repo,
-      repository,
-    ]),
-  );
-  const distribution = schemas.parseDistribution(
+  // The definition carries the CLI-owned `sourcePins` (the repositories this edition holds at an exact
+  // commit); the kernel parses the document without it. Each subject is graded against the EFFECTIVE pin
+  // of THIS edition. Pure: no git, no sources root (this runs inside the built verifier).
+  const { document, sourcePins } = splitEditionDefinition(
     JSON.parse(
       readFileSync(
         join(editionsRoot, distributionId, 'xema-distribution.json'),
         'utf8',
       ),
     ),
+    distributionId,
+  );
+  const distribution = schemas.parseDistribution(document);
+  const repositoryPins = new Map(
+    effectiveRepositoryPins(runtimeSourceIndex.repositoryPins, sourcePins, { id: distributionId, contractAuthority: runtimeSourceIndex.contractAuthority }).map((repository) => [
+      repository.repo,
+      repository,
+    ]),
   );
   if (distribution.id !== distributionId) {
     throw new Error(

package/edition/indexes-at-pins.mjs

@@ -0,0 +1,29 @@
+// indexes-at-pins — the platform-service, biome and runtime-image-source
+// indexes of a source universe pinned at ARBITRARY repository pins.
+//
+// The release builders regenerate the committed indexes over a pinned source
+// authority; this runs the same builders, in memory, over any pin set. A develop
+// snapshot (develop-snapshot-inputs.mjs) and a vendor edition that holds
+// repositories (edition-pinned-inputs.mjs) both derive their indexes here, so
+// there is no second builder. No fallback: the authority has no delegate, so a
+// repository the pins do not name refuses by name instead of resolving to a tip.
+
+import { buildValidatedPlatformServiceIndex } from './build-platform-service-index.mjs';
+import { buildTrustedIndex, validateRuntimeImageSourceIndex } from './build-runtime-image-source-index.mjs';
+import { buildBiomeIndex, distributionBiomeSourceRepositories } from './lib.mjs';
+import { createPinnedSourceAuthority } from './source-authority.mjs';
+
+/**
+ * @param {{ schemas: object, repositoryPins: object[] }} request
+ * @returns {{ platformServiceIndex, biomeIndex, runtimeImageSourceIndex }}
+ */
+export async function buildIndexesAtPins({ schemas, repositoryPins }) {
+  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, undefined, undefined, { biomeIndex, platformServiceIndex }),
+  );
+  await validateRuntimeImageSourceIndex(runtimeImageSourceIndex, schemas, { biomeIndex, platformServiceIndex });
+  return { platformServiceIndex, biomeIndex, runtimeImageSourceIndex };
+}

package/edition/release-catalogue.mjs

@@ -1,21 +1,22 @@
 // release-catalogue — the catalogue of a RELEASE offering, from its committed, sealed locks.
 
-import { readFileSync } from 'node:fs';
-
 import { biomeSourceTreeIds } from './biome-content.mjs';
 import { buildCatalogue } from './catalogue.mjs';
 import { EditionChannel } from './edition-constants.mjs';
-import { biomeIndexPath, kernelPackageDir, platformServiceIndexPath, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import { editionPinnedInputs } from './edition-pinned-inputs.mjs';
+import { kernelPackageDir } from './edition-workspace.mjs';
 import { kernelPackageOfAuthority } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
 import { loadEditionManifest } from './resolve-distribution.mjs';
 import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
-import { committedRepositoryPins, createPinnedSourceAuthority } from './source-authority.mjs';
+import { createPinnedSourceAuthority } from './source-authority.mjs';
 
 /** The catalogue of release offering `id`, from the committed locks (`locks` as `readCommittedEdition` returns them). */
 export async function releaseCatalogue(id, locks, { fetchKernelTarball } = {}) {
   const schemas = await loadKernelDistributionSchemas();
-  const authority = createPinnedSourceAuthority({ pins: committedRepositoryPins() });
+  // The EDITION's indexes and pins: a held repository is catalogued at the held commit.
+  const pinned = await editionPinnedInputs(id, { schemas });
+  const authority = createPinnedSourceAuthority({ pins: pinned.repositoryPins });
   // The WRITER of the catalogue's tree ids: the real `git rev-parse <commit>:<path>` of every biome.
   const sourceTreeIds = await biomeSourceTreeIds({
     schemas,
@@ -24,7 +25,7 @@ export async function releaseCatalogue(id, locks, { fetchKernelTarball } = {}) {
     locate: sourceTreeLocator(externalSourceTrees(locks.distributionLock)),
     vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
   });
-  const contractAuthority = schemas.parseRuntimeImageSourceIndex(JSON.parse(readFileSync(runtimeImageSourceIndexPath(), 'utf8'))).contractAuthority;
+  const { contractAuthority } = pinned.runtimeImageSourceIndex;
   return buildCatalogue({
     sourceTreeIds,
     offeringId: id,
@@ -32,8 +33,8 @@ export async function releaseCatalogue(id, locks, { fetchKernelTarball } = {}) {
     distributionLock: locks.distributionLock,
     imageLock: locks.imageLock,
     chartSetLock: locks.chartSetLock,
-    biomeIndex: JSON.parse(readFileSync(biomeIndexPath(), 'utf8')),
-    platformServiceIndex: schemas.parsePlatformServiceSourceIndex(JSON.parse(readFileSync(platformServiceIndexPath(), 'utf8'))),
+    biomeIndex: pinned.biomeIndex,
+    platformServiceIndex: pinned.platformServiceIndex,
     contractAuthority,
     kernel: await kernelPackageOfAuthority({
       kernelPackageDir: kernelPackageDir(),