@xemahq/xema 0.41.1 → 0.43.0

package/edition/dist-check.mjs

@@ -370,7 +370,7 @@ export async function checkImagesLock(id, checkSourceEvidence) {
   }
 }
 
-async function checkCommittedRuntimeImageSourceIndex(checkSources) {
+export async function checkCommittedRuntimeImageSourceIndex(checkSources) {
   try {
     const schemas = await loadKernelDistributionSchemas();
     schemas.parseRuntimeImageSourceIndex(
@@ -394,7 +394,7 @@ async function checkCommittedRuntimeImageSourceIndex(checkSources) {
   }
 }
 
-function checkCommittedIndex() {
+export function checkCommittedIndex() {
   try {
     const index = validateImmutableBiomeIndex(
       JSON.parse(readFileSync(biomeIndexPath(), 'utf8')),
@@ -464,7 +464,7 @@ export function checkCommittedDataRootReaders() {
   return green;
 }
 
-async function checkCommittedPlatformServiceIndex() {
+export async function checkCommittedPlatformServiceIndex() {
   try {
     const schemas = await loadKernelDistributionSchemas();
     const index = schemas.parsePlatformServiceSourceIndex(
@@ -493,7 +493,7 @@ async function checkCommittedPlatformServiceIndex() {
   }
 }
 
-function discoverDistributionIds() {
+export function discoverDistributionIds() {
   if (!existsSync(editionsRoot())) {
     console.error(`[dist:check] ${editionsRoot()} does not exist.`);
     process.exit(1);
@@ -514,37 +514,16 @@ function discoverDistributionIds() {
 }
 
 /**
- * Guard for the capability-domain OWNERSHIP (reservation) table.
- *
- * This repo has no test runner (no package.json, no CI workflow of its own) —
- * `dist:check` IS its gate — so the invariant is asserted here, where it
- * actually runs, rather than in a spec file nothing would execute.
- *
- * THE INVARIANT THAT MATTERS: **every edition carries the IDENTICAL table.**
+ * The lock-free half of the ownership guard: the kernel's reader, exercised
+ * against synthetic tables. (a) two biomes claiming one domain is refused,
+ * naming it; (b) a listed domain resolves to its owner and an unlisted one is
+ * not first-party; (c) an invalid domain is refused. Reads no lock, so the
+ * authored check runs it too.
  *
- *   Ownership is a property of the platform, not of what an edition preloads.
- *   An earlier design put the claim on each `LockedBiome`, which made a trimmed
- *   edition (`appliance-lean`) leave `kb`/`agent`/… unowned — so an
- *   org admin could install the owning biome from the store and THEN bind
- *   `kb:page.read@1` to a URL they control, silently shadowing the platform
- *   data plane. The table is now built from the FULL biome index and reserves
- *   the domain even when its owning biome is absent from that edition — which
- *   is exactly the case the reservation exists to cover.
- *
- * Also re-asserts the two structural rules, through the KERNEL's own reader:
- *   (a) two biomes claiming the SAME domain is refused (ambiguous ownership has
- *       no safe resolution — fail the build, never pick a winner);
- *   (b) a domain in NO table entry is not first-party (so a claim that never
- *       made it into a resolved, committed, drift-checked lock carries no
- *       weight), and an invalid domain is refused rather than silently carried.
- *
- * @param {string[]} ids every distribution id discovered in this repo.
- * @returns {Promise<boolean>} true when green.
+ * @param {(lock: object) => Map<string, string>} resolveFirstPartyCapabilityDomains the kernel's reader
+ * @returns {string[]} the failures, empty when green
  */
-async function checkOwnershipInvariant(ids) {
-  const { resolveFirstPartyCapabilityDomains } =
-    await loadKernelDistributionSchemas();
-
+export function ownershipSelfTestFailures(resolveFirstPartyCapabilityDomains) {
   const lockOf = (capabilityDomainOwners) => ({
     schemaVersion: 1,
     distributionId: 'dist-check-selftest',
@@ -599,6 +578,43 @@ async function checkOwnershipInvariant(ids) {
     /* expected */
   }
 
+  return failures;
+}
+
+/**
+ * Guard for the capability-domain OWNERSHIP (reservation) table.
+ *
+ * This repo has no test runner (no package.json, no CI workflow of its own) —
+ * `dist:check` IS its gate — so the invariant is asserted here, where it
+ * actually runs, rather than in a spec file nothing would execute.
+ *
+ * THE INVARIANT THAT MATTERS: **every edition carries the IDENTICAL table.**
+ *
+ *   Ownership is a property of the platform, not of what an edition preloads.
+ *   An earlier design put the claim on each `LockedBiome`, which made a trimmed
+ *   edition (`appliance-lean`) leave `kb`/`agent`/… unowned — so an
+ *   org admin could install the owning biome from the store and THEN bind
+ *   `kb:page.read@1` to a URL they control, silently shadowing the platform
+ *   data plane. The table is now built from the FULL biome index and reserves
+ *   the domain even when its owning biome is absent from that edition — which
+ *   is exactly the case the reservation exists to cover.
+ *
+ * Also re-asserts the two structural rules, through the KERNEL's own reader:
+ *   (a) two biomes claiming the SAME domain is refused (ambiguous ownership has
+ *       no safe resolution — fail the build, never pick a winner);
+ *   (b) a domain in NO table entry is not first-party (so a claim that never
+ *       made it into a resolved, committed, drift-checked lock carries no
+ *       weight), and an invalid domain is refused rather than silently carried.
+ *
+ * @param {string[]} ids every distribution id discovered in this repo.
+ * @returns {Promise<boolean>} true when green.
+ */
+async function checkOwnershipInvariant(ids) {
+  const { resolveFirstPartyCapabilityDomains } =
+    await loadKernelDistributionSchemas();
+
+  const failures = ownershipSelfTestFailures(resolveFirstPartyCapabilityDomains);
+
   // (d) THE headline invariant — every committed edition carries the same,
   //     non-empty table. An edition-specific table is the fail-open bug.
   let reference;
@@ -919,13 +935,16 @@ export async function checkBiomeContentHashes(id) {
   }
 }
 
-async function main() {
-  let failed = false;
-  // The tests spawned below resolve the editions root from THEIR OWN argv and
-  // env; a root stated here by --editions-root must reach them, or they
-  // would grade the vendor's editions under a customer's dist-check.
-  const checkSources = process.argv.includes('--check-sources');
-
+/**
+ * The data-root plane both checks grade before any edition: the kernel speaks
+ * a supported edition protocol (a refusal throws), the committed biome,
+ * platform-service and runtime-image-source indexes validate offline, the
+ * evidence trust policy and the data-root readers are sound. `checkSources`
+ * adds the trusted live-source audit of the indexes (release path only).
+ * Returns true when green.
+ */
+export async function checkDataRootPlane({ checkSources }) {
+  let green = true;
   // 0. The pinned kernel speaks an edition protocol this CLI supports. This is
   // the ONE comparison between the CLI and the kernel; a refusal throws
   // EditionProtocolMismatchError and stops the check before anything is read.
@@ -938,13 +957,13 @@ async function main() {
   // A live sibling-source scan is an explicit trusted regeneration audit only;
   // CI/shared working trees must not make unrelated uncommitted sources into
   // packaging inputs.
-  if (!checkCommittedIndex()) {failed = true;}
-  if (!(await checkCommittedPlatformServiceIndex())) {failed = true;}
+  if (!checkCommittedIndex()) {green = false;}
+  if (!(await checkCommittedPlatformServiceIndex())) {green = false;}
   if (!(await checkCommittedRuntimeImageSourceIndex(checkSources))) {
-    failed = true;
+    green = false;
   }
-  if (!(await checkEvidenceTrustPolicy())) {failed = true;}
-  if (!checkCommittedDataRootReaders()) {failed = true;}
+  if (!(await checkEvidenceTrustPolicy())) {green = false;}
+  if (!checkCommittedDataRootReaders()) {green = false;}
   if (checkSources) {
     try {
       execFileSync(
@@ -958,9 +977,48 @@ async function main() {
         { stdio: 'inherit' },
       );
     } catch {
-      failed = true;
+      green = false;
     }
   }
+  return green;
+}
+
+/**
+ * The pinned kernel's authorization composer (`kernel` null when the pin
+ * predates it). `green` is false when the composer could not be loaded.
+ */
+export async function loadPlaneAuthorizationKernel() {
+  try {
+    return { green: true, kernel: await loadKernelAuthorizationComposer({ kernelPackageDir: kernelPackageDir() }) };
+  } catch (err) {
+    console.error(`[dist:check] ${err.message}`);
+    return { green: false, kernel: undefined };
+  }
+}
+
+/**
+ * The fleet chart-set pin every edition must carry (edition-chart-set.mjs), as
+ * committed text, or null when it is absent or not a rostered chart-set lock.
+ */
+export function readFleetChartSetPin() {
+  try {
+    const text = readFileSync(fleetChartSetLockPath(), 'utf8');
+    assertRosteredChartSetLock(JSON.parse(text), EDITION_CHART_SET_FILE);
+    return text;
+  } catch (err) {
+    console.error(`[dist:check] chart-set pin: ${err.message}. Run \`${commandFor('resolve-chart-set.mjs')}\`.`);
+    return null;
+  }
+}
+
+async function main() {
+  let failed = false;
+  // The tests spawned below resolve the editions root from THEIR OWN argv and
+  // env; a root stated here by --editions-root must reach them, or they
+  // would grade the vendor's editions under a customer's dist-check.
+  const checkSources = process.argv.includes('--check-sources');
+
+  if (!(await checkDataRootPlane({ checkSources }))) {failed = true;}
 
   const distributionIds = discoverDistributionIds();
 
@@ -972,25 +1030,12 @@ async function main() {
   if (!(await checkOwnershipInvariant(distributionIds))) {failed = true;}
 
   // The pinned kernel's authorization composer (null when the pin predates it).
-  let authorizationKernel;
-  try {
-    authorizationKernel = await loadKernelAuthorizationComposer({
-      kernelPackageDir: kernelPackageDir(),
-    });
-  } catch (err) {
-    console.error(`[dist:check] ${err.message}`);
-    failed = true;
-  }
+  const { green: authorizationKernelGreen, kernel: authorizationKernel } = await loadPlaneAuthorizationKernel();
+  if (!authorizationKernelGreen) {failed = true;}
 
   // The fleet chart-set pin every edition must carry (edition-chart-set.mjs).
-  let chartSetPinText = null;
-  try {
-    chartSetPinText = readFileSync(fleetChartSetLockPath(), 'utf8');
-    assertRosteredChartSetLock(JSON.parse(chartSetPinText), EDITION_CHART_SET_FILE);
-  } catch (err) {
-    console.error(`[dist:check] chart-set pin: ${err.message}. Run \`${commandFor('resolve-chart-set.mjs')}\`.`);
-    failed = true;
-  }
+  const chartSetPinText = readFleetChartSetPin();
+  if (chartSetPinText === null) {failed = true;}
 
   // 3 + 4 + 5 + 6 + 7. Every distribution: distribution.lock, images.lock,
   // authorization.lock, chart-set.lock.

package/edition/edition-protocol.mjs

@@ -28,12 +28,15 @@ import { realpathSync } from 'node:fs';
 
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 
-/** The edition protocols this library interprets: version -> content digest. */
+/** The edition protocols this library interprets: version -> content digest. v10..v14 grow the kernel
+ * source closure only (entry subpaths and hashing unchanged), so one library speaks every row. */
 export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
-  Object.freeze({
-    version: 8,
-    contentDigest: '5f878e9eaa2cd0ab39b645e4a67259b1e39383e4931e9849c4cc746f7ae43047',
-  }),
+  Object.freeze({ version: 9, contentDigest: '7cd6d760e7e7caaec3634a08c739debbdeeeaac4f1bad6791246a12f4f248e37' }),
+  Object.freeze({ version: 10, contentDigest: '660129065650a8300f7c0ad54f957b4d43507e1a44e093c9812d2b1bbf143104' }),
+  Object.freeze({ version: 11, contentDigest: '600451d2253c470c7d21bafe87260dfc3bfd43b6ad3eee2ef4d8b1f7ad08eb6e' }),
+  Object.freeze({ version: 12, contentDigest: 'cff51ea06b6ba7d95d02dcd6305b6a55061b428da48ae74dcbff8a5c8107ce41' }),
+  Object.freeze({ version: 13, contentDigest: '5f69fe73d1dea1650ef1757204a53ccd4030ade78bfa91959c2d01c937fc0e16' }),
+  Object.freeze({ version: 14, contentDigest: '403b6a491b5922df1a423ba8a2d6ae3d3900bb1caff4e8c0caa48de90a47eb9b' }),
 ]);
 
 /** Where a kernel package publishes its identity and its contract, package-relative. */
@@ -64,6 +67,12 @@ export const EditionProtocolMismatchReason = Object.freeze({
   ContractMismatch: 'contract-mismatch',
   /** The kernel's protocol is not the one compiled into the running verifier. */
   BundleMismatch: 'bundle-mismatch',
+  /** No commit on the kernel checkout's first-parent history declares a protocol this library supports. */
+  NoSupportedCommit: 'no-supported-commit',
+  /** A kernel commit's protocol declaration source exists but does not parse; refused, never skipped. */
+  Unparseable: 'unparseable',
+  /** An explicit kernel commit is not on the first-parent history of the checkout's develop head. */
+  NotOnDevelop: 'not-on-develop',
 });
 
 export class EditionProtocolMismatchError extends Error {
@@ -76,7 +85,8 @@ export class EditionProtocolMismatchError extends Error {
 
 const describe = ({ version, contentDigest }) => `edition protocol v${version} (${contentDigest})`;
 
-const supportedList = () =>
+/** `v<N>, v<M>`: the versions this library supports, as every refusal names them. */
+export const supportedList = () =>
   SUPPORTED_EDITION_PROTOCOLS.map((protocol) => `v${protocol.version}`).join(', ');
 
 /** Refuse an identity that states `provisional: true`; nothing provisional is ever read as a protocol. */
@@ -147,10 +157,11 @@ function contractIdentity(contractBytes) {
 }
 
 /**
- * Refuse an identity this library does not support, and a contract file that
- * does not state that identity. Returns the identity.
+ * Refuse an identity this library does not support: a provisional one, an
+ * unsupported version, or a supported version at another digest. Returns it.
  */
-export function assertSupportedEditionProtocol({ identity, contractBytes, source }) {
+export function assertSupportedEditionIdentity(identity, source) {
+  assertFinalIdentity(identity, source);
   const supported = SUPPORTED_EDITION_PROTOCOLS.find(
     (protocol) => protocol.version === identity.version,
   );
@@ -169,6 +180,22 @@ export function assertSupportedEditionProtocol({ identity, contractBytes, source
         'contract without a new protocol version.',
     );
   }
+  return identity;
+}
+
+/** True when `identity` is final and is a row of the supported table (version and digest). */
+export const isSupportedEditionIdentity = (identity) =>
+  identity?.provisional === false &&
+  SUPPORTED_EDITION_PROTOCOLS.some(
+    (protocol) => protocol.version === identity.version && protocol.contentDigest === identity.contentDigest,
+  );
+
+/**
+ * Refuse an identity this library does not support, and a contract file that
+ * does not state that identity. Returns the identity.
+ */
+export function assertSupportedEditionProtocol({ identity, contractBytes, source }) {
+  assertSupportedEditionIdentity(identity, source);
   const stated = contractIdentity(contractBytes);
   if (stated?.version !== identity.version || stated?.contentDigest !== identity.contentDigest) {
     throw new EditionProtocolMismatchError(

package/edition/edition-workspace.mjs

@@ -38,6 +38,8 @@ const ROOT_MEANING = Object.freeze({
 });
 
 const KERNEL_PACKAGE_SUBPATH = ['packages', 'kernel', 'kernel-contracts'];
+/** The kernel package's path inside the kernel-contracts repository, `/`-separated (a git tree path). */
+export const KERNEL_PACKAGE_REPO_PATH = KERNEL_PACKAGE_SUBPATH.join('/');
 
 let configured = Object.freeze({});
 

package/edition/kernel-protocol-choice.mjs

@@ -0,0 +1,239 @@
+// kernel-protocol-choice — which kernel commit a develop edition runs.
+//
+// The CLI runs the kernel's code and refuses a protocol it does not support
+// (edition-protocol.mjs), so a develop edition that always took the kernel's
+// develop HEAD would break on every kernel protocol bump until a CLI release
+// caught up. Commits that declare the same protocol identity (version AND
+// digest) are interchangeable by the digest contract, so the develop kernel is
+// the NEWEST commit on the checkout's first-parent history whose declared
+// identity is in this CLI's supported set: a deterministic choice, never a
+// fallback.
+//
+//   - head supported          -> the head              (reason head-supported)
+//   - head ahead of the CLI   -> the newest supported  (reason head-ahead, held)
+//   - an explicit 40-hex pin  -> the pin, still checked (reason explicit-pin); it must be on the first-parent
+//                                history of the develop head (refs/remotes/origin/develop), else not-on-develop
+//   - nothing supported       -> refused (EditionProtocolMismatchError, no-supported-commit); never the head.
+//                                The walk ends at the first commit with no declaration file (it predates the protocol).
+//   - a declaration that exists but does not parse, at the head or any walked commit
+//                             -> refused (EditionProtocolMismatchError, unparseable) naming the commit; never skipped
+//
+// The declared identity is read from each commit's SOURCE
+// (`<kernel package>/src/edition-protocol/lib/edition-protocol.ts`, the literal
+// `EDITION_PROTOCOL = Object.freeze({ version, provisional, contentDigest })`),
+// because the history is not built; the built kernel is checked again from its
+// dist files by every loader. Reads git objects only; writes nothing.
+
+import { execFileSync } from 'node:child_process';
+
+import {
+  EditionProtocolMismatchError,
+  EditionProtocolMismatchReason,
+  assertSupportedEditionIdentity,
+  isSupportedEditionIdentity,
+  supportedList,
+} from './edition-protocol.mjs';
+import { KERNEL_PACKAGE_REPO_PATH } from './edition-workspace.mjs';
+
+/** The kernel source file that declares the edition protocol identity, repository-relative. */
+export const KERNEL_EDITION_PROTOCOL_SOURCE = `${KERNEL_PACKAGE_REPO_PATH}/src/edition-protocol/lib/edition-protocol.ts`;
+
+/**
+ * The kernel checkout's develop head: the remote-tracking ref a full-history checkout (`fetch-depth: 0`)
+ * always has. Every choice and every explicit commit is judged against its first-parent history.
+ */
+export const KERNEL_DEVELOP_REF = 'refs/remotes/origin/develop';
+
+/** Why a kernel commit was chosen. A closed set; `held` is exactly `head-ahead`. */
+export const KernelChoiceReason = Object.freeze({
+  HeadSupported: 'head-supported',
+  HeadAhead: 'head-ahead',
+  ExplicitPin: 'explicit-pin',
+});
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const MAX_GIT_OUTPUT = 256 * 1024 * 1024;
+const DECLARATION = /export const EDITION_PROTOCOL\b[^=]*=\s*Object\.freeze\(\{([^}]*)\}\)/g;
+const FIELDS = Object.freeze([
+  ['version', /\bversion:\s*([1-9][0-9]*)\s*(?:,|$)/],
+  ['provisional', /\bprovisional:\s*(true|false)\s*(?:,|$)/],
+  ['contentDigest', /\bcontentDigest:\s*'([a-f0-9]{64})'\s*(?:,|$)/],
+]);
+
+/** A declaration source that exists but whose `EDITION_PROTOCOL` literal is absent or not exactly the three fields. */
+const malformed = (label) =>
+  new EditionProtocolMismatchError(
+    EditionProtocolMismatchReason.Unparseable,
+    `${label} does not parse: it must declare exactly one EDITION_PROTOCOL = Object.freeze({ version: <positive integer>, ` +
+      "provisional: <boolean>, contentDigest: '<64 lowercase hex>' })",
+  );
+
+/**
+ * The identity `{contentDigest, provisional, version}` the source text declares. Strict: exactly one
+ * declaration, each field exactly once, nothing else in the literal. Throws Unparseable otherwise.
+ */
+export function parseDeclaredEditionProtocol(text, label) {
+  const declarations = [...text.matchAll(DECLARATION)];
+  if (declarations.length !== 1) {throw malformed(label);}
+  let rest = declarations[0][1];
+  const fields = {};
+  for (const [name, pattern] of FIELDS) {
+    const all = rest.match(new RegExp(pattern.source, 'g')) ?? [];
+    if (all.length !== 1) {throw malformed(label);}
+    fields[name] = all[0].match(pattern)[1];
+    rest = rest.replace(all[0], '');
+  }
+  if (rest.replace(/\/\/[^\n]*/g, '').trim() !== '') {throw malformed(label);}
+  return Object.freeze({
+    contentDigest: fields.contentDigest,
+    provisional: fields.provisional === 'true',
+    version: Number(fields.version),
+  });
+}
+
+const describeShort = (identity) =>
+  identity === undefined ? 'no declared protocol' : `v${identity.version}${identity.provisional ? '-provisional' : ''}`;
+
+/** Git against one checkout; `runGit(args, input?)` returns stdout as a string. */
+function gitIn(repoDir, runGit) {
+  return (args, input) =>
+    runGit('git', ['-C', repoDir, ...args], {
+      encoding: 'utf8',
+      maxBuffer: MAX_GIT_OUTPUT,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      ...(input === undefined ? {} : { input }),
+    });
+}
+
+function assertCommit(git, sha, label) {
+  if (typeof sha !== 'string' || !SHA_PATTERN.test(sha)) {
+    throw new Error(`${label} is not a 40-hex commit SHA: ${JSON.stringify(sha)}`);
+  }
+  let resolved;
+  try {
+    resolved = git(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`]).trim();
+  } catch {
+    resolved = '';
+  }
+  if (resolved !== sha) {throw new Error(`${label} is not a commit in the kernel checkout`);}
+}
+
+/** The commit {@link KERNEL_DEVELOP_REF} names; refused when the checkout has no such ref. */
+function readDevelopHead(git) {
+  let head;
+  try {
+    head = git(['rev-parse', '--verify', '--quiet', `${KERNEL_DEVELOP_REF}^{commit}`]).trim();
+  } catch {
+    head = '';
+  }
+  if (!SHA_PATTERN.test(head)) {
+    throw new Error(`the kernel checkout has no ${KERNEL_DEVELOP_REF}; check it out with full history (fetch-depth: 0)`);
+  }
+  return head;
+}
+
+/** The first-parent history of `head`, newest first. */
+const firstParentHistory = (git, head) =>
+  git(['rev-list', '--first-parent', head]).split('\n').filter((line) => line.length > 0);
+
+/**
+ * The declaring blob of every commit, by one `git cat-file --batch-check`: a Map commit -> blob sha, or
+ * undefined when the commit has no such file.
+ */
+function declaringBlobs(git, commits) {
+  const input = commits.map((commit) => `${commit}:${KERNEL_EDITION_PROTOCOL_SOURCE}\n`).join('');
+  const lines = git(['cat-file', '--batch-check'], input).split('\n').filter((line) => line.length > 0);
+  if (lines.length !== commits.length) {
+    throw new Error(`git cat-file answered ${lines.length} lines for ${commits.length} kernel commits`);
+  }
+  return new Map(
+    commits.map((commit, index) => {
+      const [sha, type] = lines[index].split(' ');
+      return [commit, type === 'blob' && SHA_PATTERN.test(sha) ? sha : undefined];
+    }),
+  );
+}
+
+/** A reader of the declared identity per blob (memoized); `undefined` for an absent file. Throws Unparseable. */
+function identityReader(git) {
+  const byBlob = new Map();
+  return (commit, blob) => {
+    if (blob === undefined) {return undefined;}
+    if (!byBlob.has(blob)) {
+      const label = `the kernel commit ${commit}: ${KERNEL_EDITION_PROTOCOL_SOURCE}`;
+      byBlob.set(blob, parseDeclaredEditionProtocol(git(['cat-file', 'blob', blob]), label));
+    }
+    return byBlob.get(blob);
+  };
+}
+
+/**
+ * Refuse a kernel commit whose declared identity this CLI does not support (absent, provisional, another
+ * version, or a supported version at another digest), naming `label`. The one check behind an explicit pin
+ * and `freeze-graph --kernel-sha`. Returns the identity.
+ */
+export function assertKernelCommitSupported({ repoDir, commit, label = `the kernel commit ${commit}`, runGit = execFileSync }) {
+  const git = gitIn(repoDir, runGit);
+  assertCommit(git, commit, label);
+  const developHead = readDevelopHead(git);
+  if (!firstParentHistory(git, developHead).includes(commit)) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.NotOnDevelop,
+      `${label} is not on the first-parent history of the kernel develop head ${developHead} (${KERNEL_DEVELOP_REF}); ` +
+        'an explicit kernel commit must be one that kernel develop actually passed through.',
+    );
+  }
+  const identity = identityReader(git)(commit, declaringBlobs(git, [commit]).get(commit));
+  if (identity === undefined) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.Undeclared,
+      `${label} declares no edition protocol (${KERNEL_EDITION_PROTOCOL_SOURCE} is absent); this CLI supports ${supportedList()}.`,
+    );
+  }
+  return assertSupportedEditionIdentity(identity, `${label} (${KERNEL_EDITION_PROTOCOL_SOURCE})`);
+}
+
+/**
+ * Choose the develop kernel commit in the checkout at `repoDir` (fetched with full history).
+ *
+ * @param {object} request
+ * @param {string} request.repoDir the kernel-contracts checkout
+ * @param {string} [request.pin] an explicit 40-hex commit; it wins, and is still checked
+ * @returns {{ choice: {chosenSha: string, headSha: string, held: boolean, reason: string}, notice?: string }}
+ *   `choice` is what is recorded; `notice` (only when held) is the run-summary line, never persisted.
+ */
+export function chooseKernelCommit({ repoDir, pin, runGit = execFileSync }) {
+  const git = gitIn(repoDir, runGit);
+  const headSha = readDevelopHead(git);
+  if (pin !== undefined) {
+    assertKernelCommitSupported({ repoDir, commit: pin, label: `the kernel pin ${pin}`, runGit });
+    return { choice: { chosenSha: pin, headSha, held: false, reason: KernelChoiceReason.ExplicitPin } };
+  }
+  const commits = firstParentHistory(git, headSha);
+  const blobs = declaringBlobs(git, commits);
+  const identityAt = identityReader(git);
+  // Fail closed: an unparseable declaration (head or walked) is refused by name, never skipped; a commit
+  // with no declaration file predates the protocol, so the walk ends there.
+  const headIdentity = identityAt(headSha, blobs.get(headSha));
+  if (isSupportedEditionIdentity(headIdentity)) {
+    return { choice: { chosenSha: headSha, headSha, held: false, reason: KernelChoiceReason.HeadSupported } };
+  }
+  for (const commit of headIdentity === undefined ? [] : commits.slice(1)) {
+    const identity = identityAt(commit, blobs.get(commit));
+    if (identity === undefined) {break;}
+    if (isSupportedEditionIdentity(identity)) {
+      return {
+        choice: { chosenSha: commit, headSha, held: true, reason: KernelChoiceReason.HeadAhead },
+        notice:
+          `kernel held at ${describeShort(identity)} (${commit.slice(0, 12)}), ` +
+          `head at ${describeShort(headIdentity)} (${headSha.slice(0, 12)}): raise the CLI`,
+      };
+    }
+  }
+  throw new EditionProtocolMismatchError(
+    EditionProtocolMismatchReason.NoSupportedCommit,
+    `no commit on the first-parent history of the kernel head ${headSha} declares an edition protocol this CLI ` +
+      `supports (this CLI supports ${supportedList()}; the head declares ${describeShort(headIdentity)}` +
+      `${headIdentity === undefined ? '' : ` at ${headIdentity.contentDigest}`}). Raise the CLI; the head is never taken instead.`,
+  );
+}