@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/kernel-contract-authority.mjs

@@ -0,0 +1,526 @@
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { canonicalJson } from './canonical-evidence-json.mjs';
+import { sameRepository } from './canonical-repository-url.mjs';
+import { kernelRepoDir } from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import {
+  assertSourcePathsEqualSet,
+  KERNEL_CONTRACT_SOURCE_PATH_SET_FILE,
+  parseKernelContractSourcePathSet,
+} from './kernel-contract-source-path-set.mjs';
+
+const GIT_ENV = Object.freeze({
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_CONFIG_GLOBAL: '/dev/null',
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_NO_REPLACE_OBJECTS: '1',
+  GIT_OPTIONAL_LOCKS: '0',
+  GIT_PAGER: 'cat',
+  LC_ALL: 'C',
+  PATH: '/usr/bin:/bin',
+});
+const GIT_SAFE_CONFIG = Object.freeze([
+  '-c',
+  'core.fsmonitor=false',
+  '-c',
+  'core.hooksPath=/dev/null',
+  '-c',
+  'core.attributesFile=/dev/null',
+  '--no-pager',
+]);
+const GIT_TREE_RECORD_PATTERN =
+  /^(100644|100755|120000|160000) (blob|commit) ([a-f0-9]{40,64})\t(.+)$/;
+
+/** The kernel authority repository may be the whole of xema-base: `ls-files` of its tree exceeds the 1 MiB default. */
+const GIT_MAX_BUFFER = 1024 * 1024 * 1024;
+
+function git(repositoryDirectory, args, encoding = 'utf8') {
+  return execFileSync(
+    '/usr/bin/git',
+    [...GIT_SAFE_CONFIG, '-C', repositoryDirectory, ...args],
+    {
+      encoding,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: GIT_ENV,
+      maxBuffer: GIT_MAX_BUFFER,
+    },
+  );
+}
+
+function exactHeadCommit(repositoryDirectory) {
+  const commit = git(repositoryDirectory, [
+    'rev-parse',
+    '--verify',
+    'HEAD^{commit}',
+  ]).trim();
+  if (!COMMIT_PATTERN.test(commit)) {
+    throw new Error('kernel contract repository HEAD is not an exact commit');
+  }
+  return commit;
+}
+
+/** True when `ancestor` is reachable from `descendant`. Never throws. */
+function isAncestor(repositoryDirectory, ancestor, descendant) {
+  try {
+    git(repositoryDirectory, ['merge-base', '--is-ancestor', ancestor, descendant]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function assertCommitExists(repositoryDirectory, sourceCommit) {
+  if (!COMMIT_PATTERN.test(sourceCommit)) {
+    throw new Error(
+      `kernel contract authority has invalid source commit "${String(sourceCommit)}"`,
+    );
+  }
+  try {
+    git(repositoryDirectory, ['cat-file', '-e', `${sourceCommit}^{commit}`]);
+  } catch {
+    throw new Error(
+      `kernel contract authority commit ${sourceCommit} is absent from the local Git object database`,
+    );
+  }
+}
+
+function sameRepositoryOrigin(repositoryDirectory, schemas) {
+  const origin = git(repositoryDirectory, [
+    'remote',
+    'get-url',
+    'origin',
+  ]).trim();
+  if (
+    !sameRepository(
+      origin,
+      schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL,
+      'kernel contract repository origin',
+    )
+  ) {
+    throw new Error(
+      `kernel contract repository origin must be the repository ${schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL}`,
+    );
+  }
+  return origin;
+}
+
+/**
+ * The blob record of every tree entry at `sourceCommit`, by path: ONE
+ * `ls-tree -r`, however many authority sources there are. A path absent from
+ * the map is absent from the commit or is not a blob.
+ */
+function gitTreeAtCommit(repositoryDirectory, sourceCommit) {
+  const records = execFileSync(
+    '/usr/bin/git',
+    [...GIT_SAFE_CONFIG, '-C', repositoryDirectory, 'ls-tree', '-r', '-z', sourceCommit],
+    { encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], env: GIT_ENV, maxBuffer: GIT_MAX_BUFFER },
+  )
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean);
+  const tree = new Map();
+  for (const record of records) {
+    const match = GIT_TREE_RECORD_PATTERN.exec(record);
+    if (match) {tree.set(match[4], { mode: match[1], type: match[2], objectId: match[3] });}
+  }
+  return tree;
+}
+
+function missingSource(expectedPath) {
+  return new Error(
+    `kernel contract authority source "${expectedPath}" is missing or is not an exact Git blob`,
+  );
+}
+
+/**
+ * `{path, mode, objectId}` of each of `paths` at `sourceCommit`, in order.
+ * Refuses a path that is missing or is not a blob.
+ */
+function gitBlobRecordsAtCommit(repositoryDirectory, sourceCommit, paths) {
+  const tree = gitTreeAtCommit(repositoryDirectory, sourceCommit);
+  return paths.map((path) => {
+    const entry = tree.get(path);
+    if (entry === undefined || entry.type !== 'blob') {throw missingSource(path);}
+    return { path, mode: entry.mode, objectId: entry.objectId };
+  });
+}
+
+/**
+ * {@link gitBlobRecordsAtCommit} with each blob's exact bytes, read by ONE
+ * `cat-file --batch` and matched to the object id it was asked for.
+ */
+function gitBlobsAtCommit(repositoryDirectory, sourceCommit, paths) {
+  const records = gitBlobRecordsAtCommit(repositoryDirectory, sourceCommit, paths);
+  if (records.length === 0) {return [];}
+  const output = execFileSync(
+    '/usr/bin/git',
+    [...GIT_SAFE_CONFIG, '-C', repositoryDirectory, 'cat-file', '--batch'],
+    {
+      input: Buffer.from(records.map((record) => `${record.objectId}\n`).join(''), 'utf8'),
+      encoding: 'buffer',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: GIT_ENV,
+      maxBuffer: GIT_MAX_BUFFER,
+    },
+  );
+  let offset = 0;
+  const sources = records.map((record) => {
+    const headerEnd = output.indexOf(0x0a, offset);
+    const header = headerEnd === -1 ? '' : output.subarray(offset, headerEnd).toString('utf8');
+    const match = /^([a-f0-9]{40,64}) blob (0|[1-9][0-9]*)$/.exec(header);
+    if (!match || match[1] !== record.objectId) {throw missingSource(record.path);}
+    const size = Number(match[2]);
+    const start = headerEnd + 1;
+    if (!Number.isSafeInteger(size) || start + size >= output.length || output[start + size] !== 0x0a) {
+      throw missingSource(record.path);
+    }
+    offset = start + size + 1;
+    return { ...record, blob: Buffer.from(output.subarray(start, start + size)) };
+  });
+  if (offset !== output.length) {
+    throw new Error('kernel contract authority sources: git returned more than was asked for');
+  }
+  return sources;
+}
+
+/**
+ * The source-path set the kernel declares AT `sourceCommit`, read from that
+ * commit's own declaration blob: the same tree the digest is recomputed from,
+ * never the list of the contracts version this CLI bundles.
+ */
+export function sourcePathSetAtCommit(repositoryDirectory, sourceCommit) {
+  const [declaration] = gitBlobsAtCommit(repositoryDirectory, sourceCommit, [
+    KERNEL_CONTRACT_SOURCE_PATH_SET_FILE,
+  ]);
+  return parseKernelContractSourcePathSet(declaration.blob.toString('utf8'), sourceCommit);
+}
+
+/**
+ * Refuses `sourcePaths` unless they equal the source-path set at `sourceCommit`
+ * (KernelContractSourcePathSetMismatchError names the missing and extra paths).
+ * The wire schema checks shape only; this is the check that the set means
+ * something.
+ */
+export function assertSourcePathsMatchCommit(repositoryDirectory, sourceCommit, sourcePaths) {
+  assertSourcePathsEqualSet(sourcePaths, sourcePathSetAtCommit(repositoryDirectory, sourceCommit), sourceCommit);
+}
+
+/** The canonical JSON of an authority (sorted keys), or null for a value canonical evidence JSON cannot hold. */
+function exactAuthorityJson(value) {
+  try {
+    return canonicalJson(value);
+  } catch {
+    return null;
+  }
+}
+
+/** `actual` is exactly `expected`, field for field and value for value; key order is not part of an authority. */
+export function assertKernelContractAuthorityEqual(actual, expected, label) {
+  const canonical = exactAuthorityJson(actual);
+  if (canonical === null || canonical !== exactAuthorityJson(expected)) {
+    throw new Error(
+      `${label} does not exactly match kernel contract authority`,
+    );
+  }
+  return actual;
+}
+
+export async function readKernelContractAuthorityAtCommit({
+  repositoryDirectory = kernelRepoDir(),
+  sourceCommit,
+  schemas,
+}) {
+  if (!schemas) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  sameRepositoryOrigin(repositoryDirectory, schemas);
+  assertCommitExists(repositoryDirectory, sourceCommit);
+  // The set is the commit's own (XEMA-2010): an authority at a commit whose
+  // contracts declare 446 paths is read, digested and stamped over those 446,
+  // whatever this CLI bundles. The digest's validateSources checks shape only
+  // (contracts 0.110.3 and later).
+  const sourcePaths = sourcePathSetAtCommit(repositoryDirectory, sourceCommit);
+  const sources = gitBlobsAtCommit(repositoryDirectory, sourceCommit, sourcePaths);
+  const contentDigest =
+    await schemas.computeKernelContractAuthorityContentDigest(sources);
+  return {
+    schemaVersion: 1,
+    generatorIdentity: schemas.XEMA_KERNEL_CONTRACT_AUTHORITY_GENERATOR,
+    repositoryUrl: schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL,
+    sourceCommit,
+    sourcePaths,
+    contentHashAlgorithm:
+      schemas.KernelContractContentHashAlgorithm.LengthFramedGitPathModeBlobV1,
+    contentDigest,
+  };
+}
+
+export function assertExactCleanKernelContractCheckout({
+  repositoryDirectory = kernelRepoDir(),
+  sourceCommit,
+  schemas,
+}) {
+  sameRepositoryOrigin(repositoryDirectory, schemas);
+  const head = exactHeadCommit(repositoryDirectory);
+  if (head !== sourceCommit) {
+    throw new Error(
+      `kernel contract repository HEAD ${head} does not match authority commit ${sourceCommit}`,
+    );
+  }
+  const status = git(
+    repositoryDirectory,
+    ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+    'buffer',
+  );
+  if (status.byteLength !== 0) {
+    throw new Error(
+      'kernel contract repository must be exactly clean for trusted generation',
+    );
+  }
+  const tracked = git(repositoryDirectory, ['ls-files', '-v', '-z'], 'buffer')
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean);
+  const hidden = tracked.find((record) => !record.startsWith('H '));
+  if (hidden) {
+    throw new Error(
+      `kernel contract repository has skip-worktree, assume-unchanged, or unexpected index state: ${hidden.slice(2)}`,
+    );
+  }
+  // ONE index listing and ONE batched blob read for the whole source set.
+  const indexByPath = new Map();
+  for (const record of git(repositoryDirectory, ['ls-files', '--stage', '-v', '-z'], 'buffer')
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean)) {
+    const path = record.slice(record.indexOf('\t') + 1);
+    indexByPath.set(path, [...(indexByPath.get(path) ?? []), record]);
+  }
+  const sourcePaths = sourcePathSetAtCommit(repositoryDirectory, sourceCommit);
+  const committed = new Map(
+    gitBlobsAtCommit(repositoryDirectory, sourceCommit, sourcePaths).map((source) => [source.path, source]),
+  );
+  for (const path of sourcePaths) {
+    const indexRecords = indexByPath.get(path) ?? [];
+    const indexMatch =
+      indexRecords.length === 1
+        ? /^H (100644) ([a-f0-9]{40,64}) 0\t(.+)$/.exec(indexRecords[0])
+        : null;
+    if (!indexMatch || indexMatch[3] !== path) {
+      throw new Error(
+        `kernel contract source has hidden flags or unexpected index state: ${path}`,
+      );
+    }
+    const source = committed.get(path);
+    const worktreePath = join(repositoryDirectory, path);
+    const stats = lstatSync(worktreePath);
+    if (
+      source.mode !== schemas.XEMA_KERNEL_CONTRACT_SOURCE_MODE ||
+      source.objectId !== indexMatch[2] ||
+      !stats.isFile() ||
+      stats.isSymbolicLink() ||
+      (stats.mode & 0o777) !== 0o644 ||
+      !readFileSync(worktreePath).equals(source.blob)
+    ) {
+      throw new Error(
+        `kernel contract source does not exactly match its committed Git mode/blob: ${path}`,
+      );
+    }
+  }
+  return head;
+}
+
+/** The flag by which a caller STATES the kernel commit a new contract authority is taken from. */
+export const KERNEL_COMMIT_FLAG = '--kernel-commit';
+
+/**
+ * The contract authority of the kernel checkout, held to the commit the caller
+ * STATES. A clean checkout at the kernel's origin URL proves only which
+ * repository the directory claims to be, never which commit somebody meant to
+ * pin: `kernelCommit` is that decision, it is required, and the checkout's HEAD
+ * must equal it. It is the `sourceCommit` the authority records.
+ */
+export async function buildTrustedKernelContractAuthority({
+  repositoryDirectory = kernelRepoDir(),
+  schemas,
+  kernelCommit,
+}) {
+  if (typeof kernelCommit !== 'string' || !COMMIT_PATTERN.test(kernelCommit)) {
+    throw new Error(
+      `${KERNEL_COMMIT_FLAG} <40-hex> is required: a new kernel contract authority is pinned to the commit the caller states, never to whatever the checkout happens to hold`,
+    );
+  }
+  const head = exactHeadCommit(repositoryDirectory);
+  if (head !== kernelCommit) {
+    throw new Error(
+      `kernel contract repository HEAD ${head} is not the stated ${KERNEL_COMMIT_FLAG} ${kernelCommit}: check out the stated commit, or state the commit you mean to pin`,
+    );
+  }
+  const sourceCommit = kernelCommit;
+  assertExactCleanKernelContractCheckout({
+    repositoryDirectory,
+    sourceCommit,
+    schemas,
+  });
+  // Trusted generation at HEAD ONLY: a NEW pin is minted by a CLI whose bundled
+  // contracts declare exactly the set at that commit, so the CLI that writes
+  // the pin understands every source it binds. Reading or validating an
+  // existing pin never makes this comparison.
+  assertSourcePathsEqualSet(
+    schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS,
+    sourcePathSetAtCommit(repositoryDirectory, sourceCommit),
+    sourceCommit,
+    "this CLI's bundled kernel contract source paths",
+  );
+  const authority = await readKernelContractAuthorityAtCommit({
+    repositoryDirectory,
+    sourceCommit,
+    schemas,
+  });
+  assertExactCleanKernelContractCheckout({
+    repositoryDirectory,
+    sourceCommit,
+    schemas,
+  });
+  return authority;
+}
+
+/**
+ * Is the pinned authority on the kernel history we ship — and has the kernel's
+ * contract surface moved since it?
+ *
+ * THIS USED TO REFUSE ON ANY CONTENT DRIFT, and that made the image-contract
+ * pin an input every kernel commit could invalidate. Measured 2026-10-01:
+ * `dist-check` was red with "the kernel contract surface CHANGED" because
+ * kernel `a348e71` added one member, `ComposedProcess`, to
+ * `RuntimeImageSubjectKind` — a kind no committed image lock carries and this
+ * repository never mints. The printed remedy, `xema-edition index runtime-image-source
+ * --repin-contract-authority`, rewrites `contractAuthority` in EVERY `images.lock.json`,
+ * which changes each lock's `normalizedImageLockDigest` (bound by the signed
+ * completeness statement) and orphans every signed producer statement (whose
+ * `predicate.contractAuthority` must equal the pin). Nine sealed editions, plus
+ * every customer edition minted under the same pin, would have lost their
+ * evidence for a change that altered no image. The same would follow from a
+ * new export in `distribution/index.ts`, which is one of the authority's
+ * source paths and is touched by every distribution-contract addition.
+ *
+ * Owner ruling, 2026-10-01: an unrelated change must not force historical
+ * editions to re-resolve or re-seal their image lists unless IMAGE SEMANTICS
+ * changed. The pin is a DELIBERATE image-contract version, advanced by the
+ * repin transaction when an edition needs semantics the pinned contract cannot
+ * describe — never by kernel HEAD moving underneath it.
+ *
+ * So this now REFUSES only what is a defect:
+ *   - a pin that is not an ancestor of kernel HEAD (a different history — see
+ *     below), and
+ *   - (in the caller) a pin whose recorded digest does not re-derive from its
+ *     own commit's blobs.
+ * Drift is RETURNED as the list of moved source paths, and the caller reports
+ * it. It is not silent: it is printed on every check, naming each path.
+ *
+ * What keeps a stale pin from LYING about an image lock: the standalone
+ * verifier is built from kernel source that descends from the pin and strict-
+ * parses every image lock and producer statement, and producer evidence is
+ * refused unless its signed `contractAuthority` equals the pin. A lock that
+ * used semantics newer than the pin therefore fails closed at verification,
+ * loudly — and that is the moment a repin is genuinely owed.
+ *
+ * The pin must still be an ancestor of HEAD. A pin on a different history is
+ * not "behind", it is unrelated, and recomputing a digest across a fork would
+ * compare content from a branch nobody is shipping.
+ */
+async function assessAuthorityLineage({ authority, repositoryDirectory, schemas }) {
+  const head = exactHeadCommit(repositoryDirectory);
+  if (head === authority.sourceCommit) {return { head, changedPaths: [] };}
+
+  if (!isAncestor(repositoryDirectory, authority.sourceCommit, head)) {
+    throw new Error(
+      `kernel contract authority commit ${authority.sourceCommit} is not an ancestor of kernel HEAD ` +
+        `${head}. The pin is on a different history (a force push, or a checkout of another branch), ` +
+        'so it cannot be compared by content — repin deliberately against the history you intend to ship.',
+    );
+  }
+
+  const atHead = await readKernelContractAuthorityAtCommit({
+    repositoryDirectory,
+    sourceCommit: head,
+    schemas,
+  });
+  if (atHead.contentDigest === authority.contentDigest) {
+    return { head, changedPaths: [] };
+  }
+
+  // The two commits may declare different sets: a path added or dropped since
+  // the pin has moved as surely as one whose blob changed.
+  const pinnedTree = gitTreeAtCommit(repositoryDirectory, authority.sourceCommit);
+  const currentTree = gitTreeAtCommit(repositoryDirectory, head);
+  const pinnedSet = new Set(authority.sourcePaths);
+  const currentSet = new Set(atHead.sourcePaths);
+  const changedPaths = [...new Set([...pinnedSet, ...currentSet])]
+    .sort()
+    .filter(
+      (path) =>
+        pinnedSet.has(path) !== currentSet.has(path) ||
+        pinnedTree.get(path)?.objectId !== currentTree.get(path)?.objectId,
+    );
+  return { head, changedPaths };
+}
+
+/** One line naming the drift, for callers that report it. */
+export function describeKernelContractAuthorityDrift({ authority, head, changedPaths }) {
+  return (
+    `kernel contract authority ${authority.sourceCommit} is behind kernel HEAD ${head}: ` +
+    `${changedPaths.length} contract source path(s) moved (${changedPaths.join(', ')}). ` +
+    'This is NOT a refusal — image locks stay pinned to the contract they were minted ' +
+    'under. Repin (`xema-edition index runtime-image-source --repin-contract-authority`) only ' +
+    'when an edition needs image semantics the pinned contract cannot describe; that ' +
+    'repin re-binds every edition\'s image evidence.'
+  );
+}
+
+export async function validateKernelContractAuthorityFromGit({
+  authority,
+  repositoryDirectory = kernelRepoDir(),
+  schemas,
+  requireHeadMatch = true,
+  requireCleanCheckout = false,
+  // Called with `{ authority, head, changedPaths }` when the pin is an ancestor
+  // of HEAD but the contract surface has moved since it. Reporting, never
+  // refusing — see `assessAuthorityLineage`.
+  onDrift = () => {},
+}) {
+  if (!authority || typeof authority !== 'object') {
+    throw new Error('kernel contract authority is required');
+  }
+  if (requireHeadMatch) {
+    const { head, changedPaths } = await assessAuthorityLineage({
+      authority,
+      repositoryDirectory,
+      schemas,
+    });
+    if (changedPaths.length > 0) {onDrift({ authority, head, changedPaths });}
+  }
+  if (requireCleanCheckout) {
+    assertExactCleanKernelContractCheckout({
+      repositoryDirectory,
+      sourceCommit: authority.sourceCommit,
+      schemas,
+    });
+  }
+  assertCommitExists(repositoryDirectory, authority.sourceCommit);
+  assertSourcePathsMatchCommit(repositoryDirectory, authority.sourceCommit, authority.sourcePaths);
+  const expected = await readKernelContractAuthorityAtCommit({
+    repositoryDirectory,
+    sourceCommit: authority.sourceCommit,
+    schemas,
+  });
+  assertKernelContractAuthorityEqual(
+    authority,
+    expected,
+    'runtime image source index',
+  );
+  return authority;
+}

package/edition/kernel-contract-source-path-set.mjs

@@ -0,0 +1,96 @@
+/**
+ * The kernel contract authority's source-path set, as the kernel commit itself
+ * declares it. The set belongs to the commit an authority is pinned at, never
+ * to the contracts package the CLI happens to bundle: a bundled constant is the
+ * set of ONE contracts version, and comparing a pin made under another version
+ * against it is the cross-version defect this check replaces.
+ */
+
+import { KERNEL_PACKAGE_REPO_PATH } from './edition-workspace.mjs';
+
+/** The file in the kernel repository that declares the source-path set. */
+export const KERNEL_CONTRACT_SOURCE_PATH_SET_FILE =
+  `${KERNEL_PACKAGE_REPO_PATH}/src/distribution/lib/kernel-contract-source-paths.ts`;
+
+const DECLARATION_START = 'export const XEMA_KERNEL_CONTRACT_SOURCE_PATHS = Object.freeze([';
+const DECLARATION_END = '] as const);';
+const PATH_LINE_PATTERN = /^ {2}'([^'\\\s]+)',$/;
+
+/**
+ * A source-path list is not the source-path set at `sourceCommit`. `subject`
+ * names the list that was compared: a pinned authority's `sourcePaths`, or the
+ * set the CLI's bundled contracts declare (trusted generation only).
+ */
+export class KernelContractSourcePathSetMismatchError extends Error {
+  constructor({ sourceCommit, missing, extra, subject = 'kernel contract authority sourcePaths' }) {
+    super(
+      `${subject} are not the source-path set at ${sourceCommit}: ` +
+        `${missing.length} missing (${missing.join(', ') || 'none'}), ` +
+        `${extra.length} extra (${extra.join(', ') || 'none'})`,
+    );
+    this.name = 'KernelContractSourcePathSetMismatchError';
+    this.sourceCommit = sourceCommit;
+    this.missing = missing;
+    this.extra = extra;
+  }
+}
+
+/**
+ * The ordered path list declared by the text of
+ * {@link KERNEL_CONTRACT_SOURCE_PATH_SET_FILE}. Refuses any other shape, a list
+ * that is empty, not strictly ascending (which also makes it unique), or that
+ * does not name the declaration file itself: the declaration is one of the
+ * digested sources, so the digest commits to the set it was taken over.
+ */
+export function parseKernelContractSourcePathSet(text, sourceCommit) {
+  const lines = text.split('\n');
+  const start = lines.indexOf(DECLARATION_START);
+  const end = lines.indexOf(DECLARATION_END, start + 1);
+  if (start === -1 || end === -1) {
+    throw new Error(
+      `${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} does not declare XEMA_KERNEL_CONTRACT_SOURCE_PATHS in the expected form`,
+    );
+  }
+  const paths = lines.slice(start + 1, end).map((line) => {
+    const match = PATH_LINE_PATTERN.exec(line);
+    if (!match || match[1].split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+      throw new Error(
+        `${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} has a line that is not one quoted relative path: ${JSON.stringify(line)}`,
+      );
+    }
+    return match[1];
+  });
+  if (paths.length === 0) {
+    throw new Error(`${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} declares no source paths`);
+  }
+  for (let index = 1; index < paths.length; index += 1) {
+    if (!(paths[index - 1] < paths[index])) {
+      throw new Error(
+        `${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} is not in strictly ascending order at ${JSON.stringify(paths[index])}`,
+      );
+    }
+  }
+  if (!paths.includes(KERNEL_CONTRACT_SOURCE_PATH_SET_FILE)) {
+    throw new Error(
+      `${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} does not declare itself, so the digest would not commit to the set`,
+    );
+  }
+  return paths;
+}
+
+/**
+ * Refuses `sourcePaths` unless it equals `expected`, the set at `sourceCommit`
+ * (same paths, same order); names the paths `sourcePaths` lacks (missing) and
+ * the ones it has beyond the set (extra).
+ */
+export function assertSourcePathsEqualSet(sourcePaths, expected, sourceCommit, subject = undefined) {
+  const have = new Set(sourcePaths);
+  const want = new Set(expected);
+  const missing = expected.filter((path) => !have.has(path));
+  const extra = sourcePaths.filter((path) => !want.has(path));
+  const sameOrder =
+    sourcePaths.length === expected.length && sourcePaths.every((path, index) => path === expected[index]);
+  if (missing.length > 0 || extra.length > 0 || !sameOrder) {
+    throw new KernelContractSourcePathSetMismatchError({ sourceCommit, missing, extra, subject });
+  }
+}