@xemahq/xema 0.41.0 → 0.42.0

package/edition/README.md

@@ -100,7 +100,9 @@ The edition library builds, validates and verifies evidence statements; it never
 
 ## Kernel protocol and pins
 
-The CLI is coupled to the kernel's edition protocol, not to the kernel package. `@xemahq/contracts` exports the protocol identity as data (`dist/edition-protocol/edition-protocol.json`: `{contentDigest, provisional, version}`). This CLI supports exactly protocol v8 (a data root whose pinned kernel speaks v5 stays on CLI 0.33.x) and REFUSES an identity with `provisional: true`; every loader that executes the kernel, `xema edition check` first, and the evidence verifier compare only that identity and refuse an unsupported one, naming the supported and the declared versions. A protocol change needs a CLI release first; only then does the data root repin its kernel authority.
+The CLI is coupled to the kernel's edition protocol, not to the kernel package. `@xemahq/contracts` exports the protocol identity as data (`dist/edition-protocol/edition-protocol.json`: `{contentDigest, provisional, version}`). This CLI supports protocols v9 to v14, each pinned to its digest and vendored (v10 to v14 grow the kernel source closure only; a data root whose pinned kernel speaks v8 stays on CLI 0.41.x, v5 on 0.33.x) and REFUSES an identity with `provisional: true`; every loader that executes the kernel, `xema edition check` first, and the evidence verifier compare only that identity and refuse an unsupported one, naming the supported and the declared versions. A protocol change needs a CLI release first; only then does the data root repin its kernel authority.
+
+A develop edition does not take the kernel's develop head blindly: `xema edition develop choose-kernel --kernel <package dir> [--kernel-pin <40-hex>] --out <file>` reads the declared protocol of each commit on the checkout's first-parent history (from source, unbuilt) and chooses the newest one this CLI supports. It writes `{chosenSha, headSha, held, reason}` (`reason`: `head-supported` | `head-ahead` | `explicit-pin`; `held` is `head-ahead`), and when held prints `kernel held at v<N> (<sha12>), head at v<M> (<sha12>): raise the CLI` (stdout only, never persisted). The head is the checkout's `refs/remotes/origin/develop` (a full-history checkout). An explicit pin wins but is still checked, and must be on that head's first-parent history (`not-on-develop` otherwise); when no commit is supported it refuses (`EditionProtocolMismatchError`, `no-supported-commit`; the walk ends at the first commit with no declaration file) and never falls back to the head; a declaration that exists but does not parse, at the head or any walked commit, is refused by name (`unparseable`), never skipped. `freeze-graph` applies the same check to `--kernel-sha`.
 
 - `xema edition evidence statement entitlement stage` writes entitlement predicate v2 (`lockDigest`, `catalogueDigest`, read from the edition's committed locks), so it takes `--editions-root` besides `--data-root` and `--kernel`.
 - A source repository JOINS a data root that has committed pins with one command: `xema edition index runtime-image-source --trusted-write --repo <repository> [--at <40-hex>] [--kernel-root <checkout>]`. The repository is resolved once and the runtime image source, biome and platform-service indexes are all written from the committed pins plus that one pin; every committed pin is kept field for field (a differing one is refused by name), a second declared repository with no pin is refused, and the summary names each pin added, moved and dropped. Then `xema edition index biome --check`, `xema edition index runtime-image-source --check` and `pnpm check`. The biome builder takes no `--repo`: it would resolve the repository a second time.

package/edition/biome-content.mjs

@@ -22,8 +22,10 @@ import { relative, sep } from 'node:path';
 import { assertCustomerLockWithinCatalogueCeiling } from './catalogue.mjs';
 import { readGitJsonAtCommit } from './lib.mjs';
 import {
+  assertInstalledOperationCeilingAdmitted,
   assertOperationGrantsAdmitted,
   assertOrganizationSweepsAdmitted,
+  assertStoreWorkloadCeilingAdmitted,
 } from './operation-grant-admission.mjs';
 
 /** A biome whose recomputed content hash is not the lock's, or whose inputs cannot be recomputed. */
@@ -289,6 +291,8 @@ export async function sealLock({ schemas, unsealed, imageLock, locate, vendoredC
   const hashes = await computeBiomeContentHashes({ schemas, lock: unsealed, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, sourceFactsById });
   assertOperationGrantsAdmitted(schemas, unsealed);
   assertOrganizationSweepsAdmitted(schemas, unsealed);
+  assertInstalledOperationCeilingAdmitted(schemas, unsealed);
+  assertStoreWorkloadCeilingAdmitted(schemas, unsealed);
   return schemas.sealDistributionLock(unsealed, hashes);
 }
 

package/edition/customer-edition-verbs.mjs

@@ -214,6 +214,7 @@ const COMMANDS = Object.freeze({
     required: ['--pins', '--cosign'],
   },
   'check-overrides': { positional: false, values: ['--overrides'], switches: [], required: ['--overrides'] },
+  'choose-kernel': { positional: false, values: ['--kernel-pin', '--out'], switches: [], required: ['--out'] },
   'check-existing': {
     positional: true,
     values: ['--pins', '--artifact', '--engine-image'],

package/edition/develop-edition.mjs

@@ -30,7 +30,8 @@
 //                [--overrides <json>] --out <file>
 //       resolve refs/heads/develop once per graph repository (and the editions
 //       root) from this checkout's runtime-image-source-index.json; the three checked-out
-//       repositories are pinned at what the workflow checked out; write the pins.
+//       repositories are pinned at what the workflow checked out; write the pins. --kernel-sha is refused
+//       unless its declared edition protocol is one this CLI supports (the check choose-kernel applies to a pin).
 //   check-existing <id> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
 //       refuse to reuse a pulled artifact whose descriptor disagrees with this snapshot.
 //   check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
@@ -44,6 +45,13 @@
 //       annotations-missing | annotation-mismatch | not-built). Prints a table grouped by producer repo
 //       and `covered N/M` (--json: the same as data). Exit 0 only when every subject is covered, 1 when
 //       not, 2 on an operational error. Takes the roots `resolve` takes; writes nothing.
+//   choose-kernel [--kernel-pin <40-hex>] --out <file>
+//       choose the develop kernel commit in the --kernel checkout (full history; its refs/remotes/origin/develop is the develop head):
+//       the newest first-parent commit whose declared edition protocol this CLI supports
+//       (kernel-protocol-choice.mjs). Writes {chosenSha, headSha, held, reason} (reason: head-supported |
+//       head-ahead | explicit-pin); when held, prints `kernel held at v<N> (<sha12>), head at v<M> (<sha12>):
+//       raise the CLI` to stdout (never persisted). A pin wins and is still checked; nothing supported is refused.
+//       Takes only --kernel (the checkout need not be built).
 //   check-overrides --overrides <json>
 //       refuse a pins override that would select the tooling this run executes
 //       (the edition tooling's own repository); the workflow runs it before any other checkout.
@@ -68,8 +76,9 @@ import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
 import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
 import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
 import { EditionChannel } from './edition-constants.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, kernelRepoDir, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
 import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { assertKernelCommitSupported, chooseKernelCommit } from './kernel-protocol-choice.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
 import { snapshotPinSource } from './pin-source.mjs';
 import { composeEdition } from './resolve-distribution.mjs';
@@ -85,11 +94,15 @@ const VENDOR_ROOTS = Object.freeze([WorkspaceRoot.Data, WorkspaceRoot.Editions,
 const COVERAGE_COMMAND = 'coverage';
 const COVERAGE_OPERATIONAL_EXIT = CoverageExit.Operational;
 const DATA_ROOT_ONLY_COMMANDS = Object.freeze(['check-overrides']);
+// `choose-kernel` reads the kernel checkout's git history only, before the kernel is built.
+const KERNEL_ROOT_ONLY_COMMANDS = Object.freeze(['choose-kernel']);
 
 if (isEntryModule(import.meta.url)) {
   const [command] = process.argv.slice(2);
   if (DATA_ROOT_ONLY_COMMANDS.includes(command)) {
     configureEditionWorkspaceFromProcess([WorkspaceRoot.Data], { refuseOthers: true });
+  } else if (KERNEL_ROOT_ONLY_COMMANDS.includes(command)) {
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Kernel], { refuseOthers: true });
   } else {
     const customerForm = process.argv.includes(DEFINITION_FLAG);
     configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, {
@@ -165,7 +178,14 @@ async function run(argv, env) {
       assertNoToolingOverride(parseOverrides(options['--overrides']));
       return;
     }
+    case 'choose-kernel': {
+      const { choice, notice } = chooseKernelCommit({ repoDir: kernelRepoDir(), pin: options['--kernel-pin'] });
+      writeOnce(options['--out'], choice);
+      if (notice !== undefined) {console.log(notice);}
+      return;
+    }
     case 'freeze-graph': {
+      assertKernelCommitSupported({ repoDir: kernelRepoDir(), commit: options['--kernel-sha'], label: `--kernel-sha ${options['--kernel-sha']}` });
       const pins = freezeGraph({
         runtimeSourceIndex: readStrictJsonFile(runtimeImageSourceIndexPath()),
         dataSha: options['--data-sha'],

package/edition/dispatched-runtime-components.mjs

@@ -1,5 +1,71 @@
 import { compareStrings } from './string-order.mjs';
 
+/** A `runtime-image` edge target that is neither `{biomeId, componentKey}` nor `{supplementalRuntimeComponentId}`, or is both. */
+export class DispatchedEdgeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DispatchedEdgeError';
+  }
+}
+
+/** A dispatched `supplemental:<id>` the runtime-image source index does not declare as a supplemental subject. */
+export class UndeclaredSupplementalRuntimeComponentError extends Error {
+  constructor(supplementalRuntimeComponentId, dispatchingBiomes, context) {
+    super(
+      `${context}: supplemental runtime component "${supplementalRuntimeComponentId}", dispatched by biome ` +
+        `${dispatchingBiomes.map((id) => `"${id}"`).join(', ')}, is not declared as a runtime-component subject ` +
+        'by the runtime image source index — refusing rather than shipping the dispatcher without the image it launches.',
+    );
+    this.name = 'UndeclaredSupplementalRuntimeComponentError';
+    this.supplementalRuntimeComponentId = supplementalRuntimeComponentId;
+    this.dispatchingBiomes = dispatchingBiomes;
+  }
+}
+
+// The `supplementalRuntimeComponentId` field is read as plain data. Since edition
+// protocol v10 the kernel types it (`DispatchedRuntimeComponentSchema`, a union of
+// two strict objects); this projection keeps reading it as data and refuses a target
+// that is neither form, or both.
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+
+/** True for the supplemental form of a projected edge. */
+export const isSupplementalEdge = (edge) => edge.supplementalRuntimeComponentId !== undefined;
+
+/** The identity of a projected edge: `supplemental:<id>` or `<biomeId>\0<componentKey>`. */
+export const dispatchedEdgeIdentity = (edge) =>
+  isSupplementalEdge(edge)
+    ? `supplemental:${edge.supplementalRuntimeComponentId}`
+    : `${edge.biomeId}\0${edge.componentKey}`;
+
+/**
+ * Project one generated-index `runtime-image` edge target into the typed union
+ * the index entry carries. A target that is neither form, or both, is refused
+ * naming the dispatching biome; no `undefined` identity can form.
+ */
+export function projectDispatchedTarget(dispatchingBiomeId, target) {
+  const supplemental = target?.supplementalRuntimeComponentId;
+  const biomeForm = target?.biomeId !== undefined || target?.componentKey !== undefined;
+  if (supplemental !== undefined) {
+    if (biomeForm || !isNonEmptyString(supplemental)) {
+      throw new DispatchedEdgeError(
+        `biome "${dispatchingBiomeId}" has a runtime-image edge target that mixes supplementalRuntimeComponentId with ` +
+          'biomeId/componentKey, or names an empty id — a target is exactly one form',
+      );
+    }
+    return { supplementalRuntimeComponentId: supplemental };
+  }
+  if (!isNonEmptyString(target?.biomeId) || !isNonEmptyString(target?.componentKey)) {
+    throw new DispatchedEdgeError(
+      `biome "${dispatchingBiomeId}" has a runtime-image edge target that is neither { biomeId, componentKey } nor ` +
+        '{ supplementalRuntimeComponentId }',
+    );
+  }
+  return { biomeId: target.biomeId, componentKey: target.componentKey };
+}
+
+const edgeLabel = (edge) =>
+  isSupplementalEdge(edge) ? `supplemental:${edge.supplementalRuntimeComponentId}` : `${edge.biomeId}/${edge.componentKey}`;
+
 /**
  * The runtime components an edition must carry because a biome it rosters
  * DISPATCHES them: the kernel's `runtime-image` edges, projected per biome into
@@ -21,6 +87,10 @@ import { compareStrings } from './string-order.mjs';
  * no biome drawn from a declared source. A biome drawn from a declared source
  * that dispatches is refused for the same reason.
  *
+ * A supplemental edge (`{supplementalRuntimeComponentId}`) names no biome: it
+ * is carried as a row `{ supplementalRuntimeComponentId, consumers }` without
+ * a biome lookup.
+ *
  * Returns one row per distinct (target biome, component key), sorted, with the
  * rostered biomes that dispatch it. Every unresolvable edge is refused, naming
  * the consumer and the target.
@@ -37,12 +107,24 @@ export function resolveDispatchedRuntimeComponents(context, consumers, index) {
     if (consumer.source !== undefined) {
       throw new Error(
         `${context}: biome "${consumer.id}", drawn from declared source "${consumer.source}", dispatches ` +
-          `runtime components (${edges.map((edge) => `${edge.biomeId}/${edge.componentKey}`).join(', ')}). ` +
+          `runtime components (${edges.map(edgeLabel).join(', ')}). ` +
           'A dispatched image is resolved from the first-party biome index, which carries no biome from a ' +
           'declared source — refusing rather than shipping the dispatcher without the images it launches.',
       );
     }
     for (const edge of edges) {
+      if (isSupplementalEdge(edge)) {
+        // Carried as a requirement owned by the dispatching biome. Whether the
+        // runtime image source index declares it is the image plane's refusal.
+        const supplementalKey = dispatchedEdgeIdentity(edge);
+        const row = rows.get(supplementalKey) ?? {
+          supplementalRuntimeComponentId: edge.supplementalRuntimeComponentId,
+          consumers: [],
+        };
+        if (!row.consumers.includes(consumer.id)) {row.consumers.push(consumer.id);}
+        rows.set(supplementalKey, row);
+        continue;
+      }
       const edgeText = `biome "${consumer.id}" dispatches runtime component "${edge.componentKey}" of biome "${edge.biomeId}"`;
       const candidates = index.filter(
         (entry) => entry.id === edge.biomeId && entry.target === 'server' && entry.source === undefined,
@@ -80,3 +162,11 @@ export function resolveDispatchedRuntimeComponents(context, consumers, index) {
     .sort(([a], [b]) => compareStrings(a, b))
     .map(([, row]) => row);
 }
+
+/** Sort order of projected edges: biome edges by (biomeId, componentKey), then supplemental edges by id. */
+export function compareDispatchedEdges(a, b) {
+  if (isSupplementalEdge(a) !== isSupplementalEdge(b)) {return isSupplementalEdge(a) ? 1 : -1;}
+  return isSupplementalEdge(a)
+    ? compareStrings(a.supplementalRuntimeComponentId, b.supplementalRuntimeComponentId)
+    : compareStrings(a.biomeId, b.biomeId) || compareStrings(a.componentKey, b.componentKey);
+}

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.`,
+  );
+}