@xemahq/xema 0.41.1 → 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

@@ -22,9 +22,10 @@ export class UndeclaredSupplementalRuntimeComponentError extends Error {
   }
 }
 
-// The `supplementalRuntimeComponentId` field is read as plain data: this CLI is on
-// @xemahq/contracts 0.83, which does not type it. XEMA-171 (CLI edition protocol
-// v9) adopts the typed field from @xemahq/contracts >= 0.91.
+// 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. */

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

package/edition/lib.mjs

@@ -40,6 +40,7 @@ import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
 import {
   PRINCIPAL_PRIVILEGE_FIELDS,
   assertPrivilegesHavePrincipals,
+  componentInstalledOperationRequests,
   componentOperationRequirements,
   componentOptionalOperationRequirements,
   componentOrganizationSweepRequirements,
@@ -686,6 +687,64 @@ const kernelDistributionDist = () => kernelDistPath('distribution', 'index.js');
 // through. A sibling of the distribution dist, loaded beside it.
 const kernelProcessTopologyDist = () => kernelDistPath('process-topology', 'index.js');
 
+/** A composed-process subject, on a kernel that cannot write image-lock schemaVersion 4. */
+export class ComposedProcessNeedsLockV4Error extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ComposedProcessNeedsLockV4Error';
+  }
+}
+
+/** The image-lock revision of a kernel that predates `IMAGE_LOCK_WRITE_SCHEMA_VERSION` (edition protocol < v14). */
+const PRE_V14_IMAGE_LOCK_SCHEMA_VERSION = 3;
+
+/**
+ * Refuse a composed-process subject when the loaded kernel predates image-lock
+ * schemaVersion 4 (it exports no `IMAGE_LOCK_WRITE_SCHEMA_VERSION`): such a
+ * kernel has no `members[]`, so it cannot say which services the composed
+ * image carries. There is no fallback.
+ */
+export function assertKernelSealsComposedMembership(schemas, subjects, label) {
+  if (Number.isInteger(schemas.IMAGE_LOCK_WRITE_SCHEMA_VERSION)) {return;}
+  const composed = (subjects ?? []).find((subject) => subject.kind === 'composed-process');
+  if (composed === undefined) {return;}
+  throw new ComposedProcessNeedsLockV4Error(
+    `${label}: composed-process subject "${composed.id}" — a composed-process subject needs a kernel that ` +
+      'writes image-lock schemaVersion 4 (edition protocol >= v14); the loaded kernel ' +
+      `(${kernelRepoDir()}) exports no IMAGE_LOCK_WRITE_SCHEMA_VERSION`,
+  );
+}
+
+/**
+ * The READ side of the same rule, for a kernel before image-lock
+ * schemaVersion 4 (no `ImageLockSchemaVersion`): it reads only schemaVersion
+ * 3, which names no composed members, so a v3 lock carrying a composed-process
+ * subject cannot say which services run from it and is refused (worded as the
+ * kernel's own `LegacyComposedImageLockError`).
+ */
+export function assertLegacyLockHasNoComposedSubject(lock) {
+  const composed = (lock.subjects ?? []).find((subject) => subject.kind === 'composed-process');
+  if (composed === undefined) {return;}
+  throw new ComposedProcessNeedsLockV4Error(
+    `distribution "${lock.distributionId}": subjects "${composed.id}" is a schemaVersion ` +
+      `${String(lock.schemaVersion)} composed-process subject, which names no members: regenerate with a CLI ` +
+      'that writes image-lock schemaVersion 4, against a kernel at edition protocol >= v14',
+  );
+}
+
+/**
+ * The image-lock schemaVersion a writer emits for `subjects`: the loaded
+ * kernel's `IMAGE_LOCK_WRITE_SCHEMA_VERSION`. A kernel before edition protocol
+ * v14 exports none and writes only schemaVersion 3, which is allowed only when
+ * there is NO composed-process subject
+ * ({@link ComposedProcessNeedsLockV4Error} otherwise).
+ */
+export function imageLockWriteSchemaVersion(schemas, subjects, label = 'images.lock.json') {
+  assertKernelSealsComposedMembership(schemas, subjects, label);
+  const version = schemas.IMAGE_LOCK_WRITE_SCHEMA_VERSION;
+  return Number.isInteger(version) ? version : PRE_V14_IMAGE_LOCK_SCHEMA_VERSION;
+}
+
 /**
  * Dynamically import the BUILT kernel distribution schemas. The kernel package
  * is NOT linked into the repo-root node_modules (it lives in its own sub-
@@ -737,6 +796,8 @@ export async function loadKernelDistributionSchemas() {
     parseOciDigest,
     parseGitTreeId,
     parseImageLock,
+    IMAGE_LOCK_WRITE_SCHEMA_VERSION,
+    ImageLockSchemaVersion,
     parseImageProducerStatement,
     parseDistributionImagesStatement,
     parseImageDeliveryEntitlementStatement,
@@ -789,6 +850,8 @@ export async function loadKernelDistributionSchemas() {
     admitOperationGrants,
     admitOrganizationSweeps,
     contractRequiredServiceTargets,
+    admitInstalledOperationCeiling,
+    admitStoreWorkloadCeiling,
   } = mod;
   let topology;
   try {
@@ -886,6 +949,11 @@ export async function loadKernelDistributionSchemas() {
     typeof admitOperationGrants !== 'function' ||
     typeof admitOrganizationSweeps !== 'function' ||
     typeof contractRequiredServiceTargets !== 'function' ||
+    // The installed-operation ceiling and the edition's store-workload ceiling,
+    // both admitted at the lock (`assertInstalledOperationCeilingAdmitted`,
+    // `assertStoreWorkloadCeilingAdmitted`).
+    typeof admitInstalledOperationCeiling !== 'function' ||
+    typeof admitStoreWorkloadCeiling !== 'function' ||
     typeof distributionImagesPredicateLockRefusal !== 'function' ||
     typeof distributionLockDigest !== 'function' ||
     typeof imageDeliveryEntitlementRefusal !== 'function' ||
@@ -907,7 +975,7 @@ export async function loadKernelDistributionSchemas() {
         `resolveRuntimeImagePlatforms/RuntimeImagePlatformKey/` +
         `kernel contract-authority digest SSOT/compareLockedServiceResources/resolveNexusBindings/describeNexusBindingRefusal/canonicalNexusFacts/` +
         `positive closure (resolveBiomeClosure/platformInvariantRoots/DistributionResolutionMode/provenance)/` +
-        `deriveWorkflowSubjects/deriveTrustCeiling (>= 0.71.0)/admitOperationGrants/admitOrganizationSweeps/` +
+        `deriveWorkflowSubjects/deriveTrustCeiling (>= 0.71.0)/admitOperationGrants/admitOrganizationSweeps/admitInstalledOperationCeiling/admitStoreWorkloadCeiling/` +
         `defaultTrustDomain/FIRST_PARTY_TRUST_DOMAIN/ProcessTrustPolicySchema/DistributionTrustPolicySchema/LockedStorePublisherSchema/` +
         `resolveFirstPartyCapabilityDomains/DistributionVisibility/` +
         `BiomeInstallPolicy/BiomeLaunchMode/ImageSourceHashAlgorithm/runtime-image enums — ` +
@@ -933,6 +1001,8 @@ export async function loadKernelDistributionSchemas() {
     parseOciDigest,
     parseGitTreeId,
     parseImageLock,
+    IMAGE_LOCK_WRITE_SCHEMA_VERSION,
+    ImageLockSchemaVersion,
     parseImageProducerStatement,
     parseDistributionImagesStatement,
     parseImageDeliveryEntitlementStatement,
@@ -992,6 +1062,8 @@ export async function loadKernelDistributionSchemas() {
     admitOperationGrants,
     admitOrganizationSweeps,
     contractRequiredServiceTargets,
+    admitInstalledOperationCeiling,
+    admitStoreWorkloadCeiling,
     distributionImagesPredicateLockRefusal,
     imageDeliveryEntitlementRefusal,
     producerWorkflowPinRefusal,
@@ -1623,7 +1695,7 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
         'resolve no worker image: a worker declares artifact.kind "oci-image" or "shared-oci-image"',
     );
   }
-  // A privilege (`requiresOperations`, `optionalOperations`, `requiresOrganizationSweeps`) is admitted for a lock workload
+  // A privilege (`requiresOperations`, `optionalOperations`, `requestsInstalledOperations`, `requiresOrganizationSweeps`) is admitted for a lock workload
   // principal only; on any other component it is refused, never dropped.
   assertPrivilegesHavePrincipals(components, imageComponents, rel);
   // A biome must declare its images in EXACTLY ONE shape. Declaring both a
@@ -1674,6 +1746,10 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
   // (`optionalOperations`), keyed like `operationRequirements`. Declared
   // intent only: the seal grants, leaves ungranted or refuses each one.
   const optionalOperationRequirements = {};
+  // `component → the operations it asks to exercise for the installing
+  // organization` (`requestsInstalledOperations`), keyed like
+  // `operationRequirements`. Declared intent only: the lock admits the ceiling.
+  const installedOperationRequests = {};
   // `component → the organization sweeps it may hold`
   // (`requiresOrganizationSweeps`), keyed like `operationRequirements`.
   // Declared intent only: the seal admits or refuses each one.
@@ -1867,6 +1943,8 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
       if (operations !== null) {operationRequirements[name] = operations;}
       const optionalOperations = componentOptionalOperationRequirements(component, where);
       if (optionalOperations !== null) {optionalOperationRequirements[name] = optionalOperations;}
+      const installed = componentInstalledOperationRequests(component, where);
+      if (installed !== null) {installedOperationRequests[name] = installed;}
       const sweeps = componentOrganizationSweepRequirements(component, where);
       if (sweeps !== null) {organizationSweepRequirements[name] = sweeps;}
       const queues = componentWorkerTaskQueues(component, protocol, where);
@@ -2311,6 +2389,17 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
           ),
         }
       : {}),
+    // The operations each workload component asks to exercise for the
+    // installing organization; omitted when none declares any.
+    ...(Object.keys(installedOperationRequests).length > 0
+      ? {
+          installedOperationRequests: Object.fromEntries(
+            Object.entries(installedOperationRequests).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
     // The organization sweeps each workload component may hold; omitted when
     // none declares any.
     ...(Object.keys(organizationSweepRequirements).length > 0
@@ -2920,8 +3009,16 @@ export function validateImmutableImageLock(lock, schemas) {
   if (!schemas) {
     throw new Error('trusted kernel distribution schemas are required');
   }
+  assertKernelSealsComposedMembership(schemas, lock.subjects, `distribution "${lock.distributionId}"`);
+  // The revisions the loaded kernel reads (`ImageLockSchemaVersion`: 3 without
+  // composed membership, 4 with it); a kernel before image-lock v4 reads only 3.
+  if (schemas.ImageLockSchemaVersion === undefined) {assertLegacyLockHasNoComposedSubject(lock);}
+  const readableVersions =
+    schemas.ImageLockSchemaVersion === undefined
+      ? [PRE_V14_IMAGE_LOCK_SCHEMA_VERSION]
+      : Object.values(schemas.ImageLockSchemaVersion).filter((version) => Number.isInteger(version));
   if (
-    lock.schemaVersion !== 3 ||
+    !readableVersions.includes(lock.schemaVersion) ||
     lock.sourceHashAlgorithm !== schemas.ImageSourceHashAlgorithm.ImageInputV2
   ) {
     throw new Error(