@xemahq/xema 0.29.1 → 0.30.0

package/edition/authorization-base.mjs

@@ -38,7 +38,6 @@ import { assertKernelEditionProtocol } from './edition-protocol.mjs';
 export const AUTHORIZATION_MODULE_DIRECTORY = 'authorization';
 export const AUTHORIZATION_ENVELOPE_FILENAME = 'envelope.json';
 export const AUTHORIZATION_LOCK_FILENAME = 'authorization.lock.json';
-export const AUTHORIZATION_LOCK_SCHEMA_VERSION = 1;
 
 /**
  * The OpenFGA CLI the sealer tests with, EXACTLY. 0.8.1 embeds
@@ -142,10 +141,12 @@ export async function loadKernelAuthorizationComposer({ kernelPackageDir }) {
   let server;
   let contribution;
   let generation;
+  let distribution;
   try {
     server = await import(`file://${serverDist}`);
     contribution = await import(`file://${join(kernelPackageDir, 'dist', 'authorization-module', 'index.js')}`);
     generation = await import(`file://${join(kernelPackageDir, 'dist', 'platform-generation', 'index.js')}`);
+    distribution = await import(`file://${join(kernelPackageDir, 'dist', 'distribution', 'index.js')}`);
   } catch (err) {
     throw new Error(`Cannot load the pinned kernel's authorization composer from ${serverDist}: ${err.message}`);
   }
@@ -153,6 +154,7 @@ export async function loadKernelAuthorizationComposer({ kernelPackageDir }) {
     [server, 'composeAuthorizationBase'],
     [server, 'authorizationModuleInputFromContribution'],
     [contribution, 'stampAuthorizationModuleContribution'],
+    [distribution, 'parseAuthorizationLockReadView'],
   ]) {
     if (typeof mod[name] !== 'function') {
       throw new Error(`the pinned kernel's authorization-module subpaths do not export ${name}.`);
@@ -169,6 +171,8 @@ export async function loadKernelAuthorizationComposer({ kernelPackageDir }) {
     composeAuthorizationBase: server.composeAuthorizationBase,
     authorizationModuleInputFromContribution: server.authorizationModuleInputFromContribution,
     stampAuthorizationModuleContribution: contribution.stampAuthorizationModuleContribution,
+    parseAuthorizationLockReadView: distribution.parseAuthorizationLockReadView,
+    authorizationLockSchemaVersion: distribution.AUTHORIZATION_LOCK_SCHEMA_VERSION,
     currentPlatformGeneration: parsed.data,
     kernelPackageDir,
   };
@@ -186,10 +190,11 @@ export function adoptedFromLock(lock) {
 }
 
 /** Compose an edition's base; a refusal names the edition and every violation. */
-export function composeEditionAuthorizationBase({ distributionId, inputs, kernel, adopted }) {
+export function composeEditionAuthorizationBase({ distributionId, inputs, kernel, adopted, biomeOrigins }) {
   try {
     return kernel.composeAuthorizationBase({
       modules: inputs,
+      biomeOrigins,
       currentPlatformGeneration: kernel.currentPlatformGeneration,
       ...(adopted ? { adopted } : {}),
     });
@@ -201,10 +206,10 @@ export function composeEditionAuthorizationBase({ distributionId, inputs, kernel
   }
 }
 
-/** The lock body for a composed base. Deterministic: no timestamp. */
+/** The lock body for a composed base. Deterministic: no timestamp. It is read through the kernel's `parseAuthorizationLockReadView` before it is returned. */
 export function authorizationLockOf(distributionId, kernel, composed) {
-  return {
-    schemaVersion: AUTHORIZATION_LOCK_SCHEMA_VERSION,
+  const lock = {
+    schemaVersion: kernel.authorizationLockSchemaVersion,
     distributionId,
     platformGeneration: kernel.currentPlatformGeneration,
     modelHash: composed.modelHash,
@@ -219,6 +224,8 @@ export function authorizationLockOf(distributionId, kernel, composed) {
     parentImplementers: [...composed.parentImplementers],
     model: composed.model,
   };
+  kernel.parseAuthorizationLockReadView(lock);
+  return lock;
 }
 
 /** Resolve and verify the pinned `fga` CLI. */
@@ -272,8 +279,8 @@ export function fgaComposedModelTestRunner(bin) {
 }
 
 /** Compose, test, describe. `runTests` is the `fga model test` runner. */
-export function sealEditionAuthorizationBase({ distributionId, inputs, kernel, adopted, runTests }) {
-  const composed = composeEditionAuthorizationBase({ distributionId, inputs, kernel, adopted });
+export function sealEditionAuthorizationBase({ distributionId, inputs, kernel, adopted, biomeOrigins, runTests }) {
+  const composed = composeEditionAuthorizationBase({ distributionId, inputs, kernel, adopted, biomeOrigins });
   runTests(composed);
   return authorizationLockOf(distributionId, kernel, composed);
 }
@@ -293,7 +300,7 @@ export const AuthorizationLockCheck = Object.freeze({
  * exactly as the sealer would refuse it) and compares the whole lock. The
  * tests are not re-run: an equal `modelHash` is the model the sealer tested.
  */
-export function checkAuthorizationLockCurrent({ distributionId, committed, inputs, kernel, serialize }) {
+export function checkAuthorizationLockCurrent({ distributionId, committed, inputs, kernel, biomeOrigins, serialize }) {
   if (kernel === null) {
     return committed === null ? AuthorizationLockCheck.GREEN : AuthorizationLockCheck.NOT_SEALABLE;
   }
@@ -302,6 +309,7 @@ export function checkAuthorizationLockCurrent({ distributionId, committed, input
     distributionId,
     inputs,
     kernel,
+    biomeOrigins,
     adopted: adoptedFromLock(committed),
   });
   return serialize(authorizationLockOf(distributionId, kernel, composed)) === serialize(committed)
@@ -316,7 +324,7 @@ export function checkAuthorizationLockCurrent({ distributionId, committed, input
  * entries plus the edition's source-walked ones). Returns an
  * `AuthorizationLockCheck` member; throws on a refusal.
  */
-export function checkEditionAuthorizationLock({ distributionId, editionDir, lockBiomes, index, kernel, serialize }) {
+export function checkEditionAuthorizationLock({ distributionId, editionDir, lockBiomes, biomeOrigins, index, kernel, serialize }) {
   if (!Array.isArray(index)) {
     throw new Error(`${distributionId}: the authorization check needs the index the lock was resolved from.`);
   }
@@ -325,6 +333,7 @@ export function checkEditionAuthorizationLock({ distributionId, editionDir, lock
     committed: readAuthorizationLock(editionDir),
     inputs: editionAuthorizationModuleInputs(lockBiomes, new Map(index.map((e) => [e.id, e])), kernel),
     kernel,
+    biomeOrigins,
     serialize,
   });
 }

package/edition/build-runtime-image-source-index.mjs

@@ -360,6 +360,72 @@ function committedRepositoryPinsToPreserve(repoScope) {
   );
 }
 
+/**
+ * `producerWorkflowPins` are operator-stated TRUST DATA: which commit of a
+ * producer repository's workflow the verifier believes. Nothing is derived (not
+ * from `repositoryPins`, not from a policy row); the committed pins are kept
+ * exactly, and `--producer-workflow-pin <owner/repo>=<40-hex>` sets or updates
+ * one. A bootstrap index with none committed writes `[]`, which the kernel allows.
+ */
+export function mergeProducerWorkflowPins(committedPins, statedPins) {
+  const merged = new Map(
+    (Array.isArray(committedPins) ? committedPins : []).map((pin) => [
+      pin.repository,
+      { repository: pin.repository, workflowCommit: pin.workflowCommit },
+    ]),
+  );
+  for (const pin of statedPins) {
+    merged.set(pin.repository, { repository: pin.repository, workflowCommit: pin.workflowCommit });
+  }
+  return [...merged.values()].sort((left, right) => compareStrings(left.repository, right.repository));
+}
+
+const PRODUCER_WORKFLOW_PIN_FLAG = '--producer-workflow-pin';
+
+/**
+ * Every `--producer-workflow-pin <owner/repo>=<40-hex>` of the argv. A malformed
+ * value, or a repository stated twice, is refused here; the repository and
+ * commit grammar is the kernel's, applied by the index parse.
+ */
+export function parseProducerWorkflowPinFlags(argv) {
+  const pins = [];
+  const remaining = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== PRODUCER_WORKFLOW_PIN_FLAG) {
+      remaining.push(argv[index]);
+      continue;
+    }
+    const value = argv[index + 1];
+    const separator = value?.indexOf('=') ?? -1;
+    if (separator < 1 || value.startsWith('--')) {
+      throw new Error(`${PRODUCER_WORKFLOW_PIN_FLAG} requires <owner/repo>=<40-hex-commit>`);
+    }
+    const repository = value.slice(0, separator);
+    const workflowCommit = value.slice(separator + 1);
+    if (pins.some((pin) => pin.repository === repository)) {
+      throw new Error(`${PRODUCER_WORKFLOW_PIN_FLAG} names ${repository} more than once`);
+    }
+    if (!COMMIT_PATTERN.test(workflowCommit)) {
+      throw new Error(`${PRODUCER_WORKFLOW_PIN_FLAG} ${repository}: the commit must be a full 40-hex sha`);
+    }
+    pins.push({ repository, workflowCommit });
+    index += 1;
+  }
+  return { producerWorkflowPins: pins, remaining };
+}
+
+/**
+ * A `--producer-workflow-pin` is trust data for the index `--trusted-write`
+ * writes, and only there. Every other mode writes nothing, so a pin stated to
+ * one would be silently ignored; `--check-sources` included: it grades the
+ * committed index against the sources, and a pin is not a source.
+ */
+export function assertProducerWorkflowPinsWritten(producerWorkflowPins, flag, usage) {
+  if (producerWorkflowPins.length > 0 && flag !== '--trusted-write') {
+    throw new Error(`${PRODUCER_WORKFLOW_PIN_FLAG} states trust data for a written index: ${flag} writes none\n${usage}`);
+  }
+}
+
 /**
  * `biomeIndex` and `platformServiceIndex` are the indexes this one is built
  * over, INJECTED: the release CLI passes the committed ones read from disk
@@ -371,7 +437,7 @@ export async function buildTrustedIndex(
   sourceAuthority,
   kernelRoot,
   repoScope,
-  { biomeIndex, platformServiceIndex, kernelCommit },
+  { biomeIndex, platformServiceIndex, kernelCommit, producerWorkflowPins = [] },
 ) {
   const contractAuthority = await resolveContractAuthority(schemas, kernelRoot, kernelCommit);
   const repositoryIdentities = new Map();
@@ -459,12 +525,16 @@ export async function buildTrustedIndex(
     }
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     contractAuthority,
     supplementalSubjects,
     crossRepoBuildInputs,
     buildStepContextDirectories,
     repositoryPins,
+    producerWorkflowPins: mergeProducerWorkflowPins(
+      existsSync(runtimeImageSourceIndexPath()) ? readJson(runtimeImageSourceIndexPath()).producerWorkflowPins : [],
+      producerWorkflowPins,
+    ),
     platformServiceBindings: [...platformServiceRuntimeBindings()].sort(
       (left, right) =>
         compareStrings(left.platformService, right.platformService),
@@ -749,7 +819,7 @@ const USAGE =
   'usage: build-runtime-image-source-index.mjs (--check | --check-sources | --trusted-write | ' +
   '--repin-contract-authority --kernel-commit <40-hex-commit>) ' +
   '[--source published|workspace] [--kernel-root <absolute-checkout>] ' +
-  '[--repo <repository> [--at <40-hex-commit>]] ' +
+  '[--repo <repository> [--at <40-hex-commit>]] [--producer-workflow-pin <owner/repo>=<40-hex-commit> ...] ' +
   '(--trusted-write on a data root with no committed contract authority also requires --kernel-commit)';
 
 async function main() {
@@ -757,7 +827,8 @@ async function main() {
     process.argv.slice(2),
   );
   const { kernelCommit, remaining: afterKernelRoot } = parseKernelCommit(afterKernelRootFlag);
-  const { repoScope, remaining: afterRepoScope } = parseRepoScope(afterKernelRoot);
+  const { producerWorkflowPins, remaining: afterWorkflowPins } = parseProducerWorkflowPinFlags(afterKernelRoot);
+  const { repoScope, remaining: afterRepoScope } = parseRepoScope(afterWorkflowPins);
   const { exactCommit, remaining: argv } = parseExactCommit(afterRepoScope);
   const { mode, remaining } = parseSourceModeArgs(argv);
   if (exactCommit !== undefined && repoScope === undefined) {
@@ -773,6 +844,7 @@ async function main() {
   if (kernelCommit !== undefined && ![REPIN_FLAG, '--trusted-write'].includes(flag)) {
     throw new Error(`${KERNEL_COMMIT_FLAG} states the commit of a new contract authority: ${flag} chooses none\n${USAGE}`);
   }
+  assertProducerWorkflowPinsWritten(producerWorkflowPins, flag, USAGE);
   const schemas = await loadKernelDistributionSchemas();
   if (flag === REPIN_FLAG) {
     if (repoScope !== undefined || exactCommit !== undefined) {
@@ -828,6 +900,7 @@ async function main() {
         biomeIndex: readJson(biomeIndexPath()),
         platformServiceIndex: readJson(join(dataRoot(), 'platform-service-index.json')),
         kernelCommit,
+        producerWorkflowPins,
       },
     ),
   );

package/edition/catalogue.mjs

@@ -18,9 +18,13 @@ import { serializeJson } from './lib.mjs';
 export const CATALOGUE_FILE = EDITION_OFFERING_LAYERS.catalogue;
 export const CATALOGUE_SCHEMA = 'xema.edition-catalogue/v1';
 
-const TOP_KEYS = ['schema', 'offeringId', 'channel', 'biomes', 'sourceTreeIds', 'platformServices', 'images', 'chartSet', 'contractAuthority', 'ceiling'];
+const TOP_KEYS = ['schema', 'offeringId', 'channel', 'biomes', 'sourceTreeIds', 'platformServices', 'images', 'chartSet', 'contractAuthority', 'kernel', 'ceiling'];
 const IMAGES_KEYS = ['sourceHashAlgorithm', 'subjects', 'platformServiceBindings', 'webBiomes'];
 const CEILING_KEYS = ['trustPolicy', 'trustCeiling'];
+const KERNEL_KEYS = ['name', 'version', 'integrity'];
+const KERNEL_PACKAGE = '@xemahq/contracts';
+const EXACT_SEMVER = /^\d+\.\d+\.\d+$/;
+const NPM_INTEGRITY = /^sha512-[A-Za-z0-9+/]{86}==$/;
 const DIGEST = /^sha256:[a-f0-9]{64}$/;
 const GIT_TREE_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 
@@ -76,6 +80,14 @@ export function parseCatalogue(value) {
   }
   if (!isObject(value.chartSet)) {throw new CatalogueError(`${CATALOGUE_FILE}: chartSet must be the offering's chart-set lock`);}
   if (!isObject(value.contractAuthority)) {throw new CatalogueError(`${CATALOGUE_FILE}: contractAuthority must be the runtime image source index's authority`);}
+  exactKeys(value.kernel, KERNEL_KEYS, `${CATALOGUE_FILE} kernel`);
+  if (value.kernel.name !== KERNEL_PACKAGE) {throw new CatalogueError(`${CATALOGUE_FILE}: kernel.name must be ${KERNEL_PACKAGE}, not ${JSON.stringify(value.kernel.name)}`);}
+  if (typeof value.kernel.version !== 'string' || !EXACT_SEMVER.test(value.kernel.version)) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: kernel.version must be an exact x.y.z version, not ${JSON.stringify(value.kernel.version)}`);
+  }
+  if (typeof value.kernel.integrity !== 'string' || !NPM_INTEGRITY.test(value.kernel.integrity)) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: kernel.integrity must be an npm sha512 integrity (sha512-<base64>)`);
+  }
   exactKeys(value.ceiling, CEILING_KEYS, `${CATALOGUE_FILE} ceiling`);
   return value;
 }
@@ -94,6 +106,7 @@ export function buildCatalogue({
   biomeIndex,
   platformServiceIndex,
   contractAuthority,
+  kernel,
   leaf,
   sourceTreeIds,
 }) {
@@ -122,6 +135,7 @@ export function buildCatalogue({
     },
     chartSet: chartSetLock,
     contractAuthority,
+    kernel,
     ceiling: { trustPolicy: leaf?.trustPolicy ?? null, trustCeiling: leaf?.trustCeiling ?? null },
   });
 }
@@ -133,14 +147,3 @@ export function writeCatalogue(outDir, catalogue) {
   writeFileSync(path, serializeJson(catalogue));
   return path;
 }
-
-const KERNEL_COMMIT = /^[0-9a-f]{40}$/;
-
-/** The commit the catalogue's contract authority was taken at (40 hex); read without the kernel schemas, which are not checked out yet where this is used. */
-export function contractAuthoritySourceCommit(catalogue) {
-  const commit = catalogue.contractAuthority.sourceCommit;
-  if (typeof commit !== 'string' || !KERNEL_COMMIT.test(commit)) {
-    throw new CatalogueError(`${CATALOGUE_FILE}: contractAuthority.sourceCommit is not a 40-hex commit: ${JSON.stringify(commit)}`);
-  }
-  return commit;
-}

package/edition/customer-definition.mjs

@@ -57,32 +57,15 @@ export function parseCustomerDefinition(schemas, raw) {
   } catch (error) {
     throw new CustomerDefinitionError(error.message, { cause: error });
   }
-  assertNoVendorReservedDomain(schemas, definition);
   return { definition, mirror };
 }
 
-/** The trust domains only the vendor places a biome in: the kernel's first-party domain. */
-export const vendorReservedTrustDomains = (schemas) => [schemas.FIRST_PARTY_TRUST_DOMAIN];
-
-/** A customer's `trustCeiling` assigns its own biomes and never into a vendor-reserved domain. */
-function assertNoVendorReservedDomain(schemas, definition) {
-  const reserved = new Set(vendorReservedTrustDomains(schemas));
-  for (const assignment of definition.trustCeiling?.assignments ?? []) {
-    if (reserved.has(assignment.domain)) {
-      throw new CustomerDefinitionError(
-        `customer definition "${definition.id}": \`trustCeiling\` assigns ${assignment.biomes.map((biome) => `biome "${biome}"`).join(', ')} ` +
-          `to trust domain "${assignment.domain}", which is reserved to the vendor; a customer's biomes are assigned a domain of the customer's own`,
-      );
-    }
-  }
-}
-
 /**
  * The trustCeiling must assign every customer-source biome (a biome the resolved lock draws
- * from the definition's own `sources[]`) and no other: the kernel's `customerTrustCeilingIssues`.
+ * from the definition's own `sources[]`) and no other, and none in a domain the catalogue's ceiling reserves: the kernel's `customerTrustCeilingIssues`.
  */
-export function assertTrustCeilingAssignsCustomerBiomes(schemas, definition, customerBiomeIds) {
-  const issues = schemas.customerTrustCeilingIssues(definition, customerBiomeIds);
+export function assertTrustCeilingAssignsCustomerBiomes(schemas, definition, customerBiomeIds, catalogueTrustCeiling) {
+  const issues = schemas.customerTrustCeilingIssues(definition, customerBiomeIds, catalogueTrustCeiling);
   if (issues.length > 0) {
     throw new CustomerDefinitionError(`customer definition "${definition.id}": ${issues.join('; ')}`);
   }

package/edition/develop-customer-edition.mjs

@@ -72,7 +72,7 @@ export function declaredSourceNamesOf(rawDefinition) {
 }
 
 /** Resolve and seal the develop customer edition; returns the four locks and the frozen provenance pins. */
-export async function resolveCustomerDevelopEdition({ rawDefinition, catalogue, catalogueDigest, pins, sourceImages, env = process.env, sealOptions = {}, verifyAuthority, materialize }) {
+export async function resolveCustomerDevelopEdition({ rawDefinition, catalogue, catalogueDigest, pins, sourceImages, env = process.env, sealOptions = {}, adoptKernel, materialize }) {
   const frozen = customerDevelopPins({ pins, declaredSourceNames: declaredSourceNamesOf(rawDefinition), catalogueDigest });
   const resolved = await resolveCustomerEdition({
     rawDefinition,
@@ -81,7 +81,7 @@ export async function resolveCustomerDevelopEdition({ rawDefinition, catalogue,
     sourceImages,
     pins: frozen,
     catalogueDigest,
-    ...(verifyAuthority === undefined ? {} : { verifyAuthority }),
+    ...(adoptKernel === undefined ? {} : { adoptKernel }),
     ...(materialize === undefined ? {} : { materialize }),
     sealOwn: ({ distributionId, subjects }) => sealDevelopImageSubjects({ distributionId, subjects, env, ...sealOptions }),
   });

package/edition/develop-edition-resolve.mjs

@@ -6,12 +6,14 @@
 // xema-deploy charts' registry manifest digests, in the release roster shape. Nothing here writes to the editions
 // trees; the caller writes the artifact (edition-artifact.mjs).
 
+import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest } from './adapter-bundled-versions.mjs';
 import { biomeSourceTreeIds, sealLock } from './biome-content.mjs';
 import { buildCatalogue } from './catalogue.mjs';
 import { sealDevelopImages } from './develop-seal.mjs';
 import { assertFrozenCheckouts, buildSnapshotInputs } from './develop-snapshot-inputs.mjs';
 import { EditionChannel } from './edition-constants.mjs';
-import { deployRoot } from './edition-workspace.mjs';
+import { deployRoot, kernelPackageDir } from './edition-workspace.mjs';
+import { kernelPackageOfAuthority } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
 import { deployPinKey } from './pin-source.mjs';
 import { resolveDevelopChartSet } from './resolve-chart-set.mjs';
@@ -19,11 +21,12 @@ import { composeAuthorizationBase, resolveDistributionWithIndex } from './resolv
 import { externalSourceTrees, resolveImages, sourceTreeLocator } from './resolve-images.mjs';
 import { createPinnedSourceAuthority } from './source-authority.mjs';
 
-export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, chartDigestLookup }) {
+export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, chartDigestLookup, fetchKernelTarball, fetchManifest = fetchRegistryManifest }) {
   const schemas = await loadKernelDistributionSchemas();
   assertFrozenCheckouts(pins);
   const inputs = await buildSnapshotInputs({ id, pins, schemas });
   const { lock, index } = await resolveDistributionWithIndex(id, { inputs });
+  await assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest });
   const authorizationLock = await composeAuthorizationBase(id, lock, index);
   const { imageLock } = await resolveImages(id, { inputs, lock });
   const sealedImageLock = await sealDevelopImages({ imageLock, env, ...sealOptions });
@@ -59,6 +62,11 @@ export async function resolveDevelopEdition({ id, pins, env = process.env, sealO
     biomeIndex: inputs.biomeIndex,
     platformServiceIndex: inputs.platformServiceIndex,
     contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
+    kernel: await kernelPackageOfAuthority({
+      kernelPackageDir: kernelPackageDir(),
+      contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
+      ...(fetchKernelTarball === undefined ? {} : { fetchTarball: fetchKernelTarball }),
+    }),
     leaf: inputs.composed.leaf,
   });
   return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue };

package/edition/develop-edition.mjs

@@ -15,7 +15,7 @@
 //       customer's own pins. --pins holds exactly one `sources/<name>` commit per source the definition
 //       declares (`freeze-sources --definition` writes it); the catalogue digest is frozen into the descriptor's
 //       provenance pins as `catalogue`. The id is the definition's. Takes --data-root, --editions-root,
-//       --sources-root, --kernel, --cache-dir (no --deploy-root).
+//       --sources-root, --cache-dir (no --deploy-root, no --kernel: the kernel is the catalogue's, from npm).
 //   target  <id> --pins <file> --registry <root>
 //       print <root>/<develop segment>/xema-edition-<id>:<snapshot hash>. The root is always the caller's
 //       registry root (e.g. registry.example.com/acme); the develop namespace segment and the repository
@@ -31,8 +31,10 @@
 //   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>
+//                  [--catalogue-username <name> --catalogue-token-env <VAR>]
 //       the same for a customer artifact; its descriptor's catalogue provenance pin must also equal the
-//       pinned develop catalogue digest.
+//       pinned develop catalogue digest. It fetches that catalogue (as `resolve --definition` does) to take the
+//       kernel from it. Takes --data-root, --cache-dir.
 //   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.
@@ -42,9 +44,6 @@
 //   freeze-sources --definition <file> --out <file>
 //       a CUSTOMER edition: one `sources/<name>` pin per source the definition declares, each the head of
 //       refs/heads/develop of that source's repository, resolved once; written exclusively (wx).
-//   kernel-commit --definition <file> [--catalogue-username <name> --catalogue-token-env <VAR>]
-//       fetch the pinned develop catalogue and print its contractAuthority.sourceCommit (one 40-hex line):
-//       the commit the kernel contracts are checked out at. Takes --data-root only (no --kernel).
 //
 // Tokens come from the environment (EVIDENCE_REPOSITORIES_TOKEN, XEMA_GHCR_PULL_TOKEN),
 // never argv. Nothing here writes git or publishes a release edition.
@@ -54,7 +53,7 @@ import { resolve } from 'node:path';
 
 import { fetchCatalogue } from './catalogue-fetch.mjs';
 import { readCataloguePin } from './catalogue-pin.mjs';
-import { contractAuthoritySourceCommit, writeCatalogue } from './catalogue.mjs';
+import { writeCatalogue } from './catalogue.mjs';
 import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
 import { customerDevelopFrame, resolveCustomerDevelopEdition } from './develop-customer-edition.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
@@ -65,28 +64,36 @@ import { editionWorkspaceConfig } from './edition-config.mjs';
 import { EditionChannel } from './edition-constants.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
 import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { holdSource } from './git-source-auth.mjs';
+import { adoptCatalogueKernel } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
 import { snapshotPinSource } from './pin-source.mjs';
 import { parseSourceImages } from './resolve-customer-edition.mjs';
 import { composeEdition } from './resolve-distribution.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
-// The roots a verb takes. A customer form (it names --definition) takes fewer: `target` none, `check-existing`
-// the data root and the kernel, `freeze-sources` and `kernel-commit` the data root only (`kernel-commit` runs
-// before the kernel is checked out), `resolve` all but the deploy root.
+// The roots a verb takes. A customer form (it names --definition) takes fewer, and never the kernel (the
+// catalogue's kernel is downloaded from npm into the cache root): `target` none, `check-existing` the data
+// root and the cache, `freeze-sources` the data root only, `resolve` all but the deploy root. `check-overrides`
+// takes only the data root in either form: it judges its --overrides JSON against the pin roles the data
+// root declares, so it reads nothing else and refuses every other root flag.
 const VENDOR_ROOTS = Object.freeze([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache]);
 const CUSTOMER_ROOTS = Object.freeze({
-  resolve: [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache],
+  resolve: [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Cache],
   target: [],
-  'check-existing': [WorkspaceRoot.Data, WorkspaceRoot.Kernel],
+  'check-existing': [WorkspaceRoot.Data, WorkspaceRoot.Cache],
   'freeze-sources': [WorkspaceRoot.Data],
-  'kernel-commit': [WorkspaceRoot.Data],
 });
+const DATA_ROOT_ONLY_COMMANDS = Object.freeze(['check-overrides']);
 
 if (isEntryModule(import.meta.url)) {
   const [command] = process.argv.slice(2);
-  const customerForm = process.argv.includes(DEFINITION_FLAG) || command === 'kernel-commit';
-  configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, { refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined });
+  if (DATA_ROOT_ONLY_COMMANDS.includes(command)) {
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data], { refuseOthers: true });
+  } else {
+    const customerForm = process.argv.includes(DEFINITION_FLAG);
+    configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, { refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined });
+  }
 }
 
 // Per verb: the vendor form (`positional` id, `values`, `switches`) and, where the verb has one, the customer
@@ -128,15 +135,7 @@ const COMMANDS = Object.freeze({
     values: ['--pins', '--artifact', '--engine-image'],
     switches: [],
     required: ['--pins', '--artifact', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG], required: ['--pins', '--artifact', '--engine-image'], refused: [] },
-  },
-  'kernel-commit': {
-    positional: false,
-    values: [],
-    switches: [],
-    required: [],
-    customerOnly: true,
-    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS], required: [], refused: [] },
+    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS], required: ['--pins', '--artifact', '--engine-image'], refused: [] },
   },
 });
 
@@ -173,7 +172,7 @@ export function parseDevelopEditionArgs(argv) {
       positional.push(arg);
     }
   }
-  const customer = spec.customer !== undefined && (spec.customerOnly === true || customerValues.some((flag) => options[flag] !== undefined));
+  const customer = spec.customer !== undefined && customerValues.some((flag) => options[flag] !== undefined);
   if (customer) {
     if (options[DEFINITION_FLAG] === undefined) {throw new Error(`a customer ${command} requires ${DEFINITION_FLAG}`);}
     for (const refused of spec.customer.refused) {
@@ -205,21 +204,27 @@ function writeOnce(path, value) {
 }
 
 function headResolver(env) {
-  return (source) => lsRemoteDevelopHead(source, { workspace: editionWorkspaceConfig(), env });
+  const workspace = editionWorkspaceConfig();
+  return { resolveHead: (source) => lsRemoteDevelopHead(source, { workspace, env }), holdSource: (source) => holdSource(source, workspace, env) };
 }
 
-/** A customer develop resolve: the artifact (descriptor and four locks, no catalogue: it is not an offering) goes to --out. */
-async function resolveCustomer(options, env) {
-  const ref = readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop });
-  const { catalogue, digest } = await fetchCatalogue({
-    ref,
+/** The pinned develop catalogue of a customer definition: fetched by its digest, as every customer develop verb does. */
+function fetchPinnedDevelopCatalogue(options, env) {
+  return fetchCatalogue({
+    ref: readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop }),
     channel: EditionChannel.Develop,
     username: options[CATALOGUE_USERNAME_FLAG],
     tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
     env,
   });
+}
+
+/** A customer develop resolve: the artifact (descriptor and four locks, no catalogue: it is not an offering) goes to --out. */
+async function resolveCustomer(options, env) {
+  const { catalogue, digest } = await fetchPinnedDevelopCatalogue(options, env);
   const rawDefinition = readStrictJsonFile(options[DEFINITION_FLAG]);
-  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
+  // The catalogue's kernel is adopted inside the resolve, before any kernel schema is loaded; the evidence trust
+  // state loads kernel schemas, so it is read after.
   const { id, pins, ...resolved } = await resolveCustomerDevelopEdition({
     rawDefinition,
     catalogue,
@@ -228,6 +233,7 @@ async function resolveCustomer(options, env) {
     sourceImages: parseSourceImages(options[SOURCE_IMAGE_FLAG] ?? []),
     env,
   });
+  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
   const target = developEditionTarget(id, pins, { registry: options['--registry'] });
   writeEditionArtifact({
     outDir: resolve(options['--out']),
@@ -245,21 +251,23 @@ async function resolveCustomer(options, env) {
   console.log(target);
 }
 
-/**
- * The commit the pinned develop catalogue's contract authority was taken at. The kernel contracts are
- * not checked out yet when this runs, so nothing here validates against kernel schemas: the catalogue
- * parser is kernel-free, and the one field read is `contractAuthority.sourceCommit`, held to 40 hex.
- */
-async function customerKernelCommit(options, env) {
-  const ref = readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop });
-  const { catalogue } = await fetchCatalogue({
-    ref,
+/** A customer check-existing: the pinned catalogue is fetched to take its kernel; the digest fetched is the digest the artifact is compared with. */
+export async function checkExistingCustomer(options, env, { adopt = adoptCatalogueKernel } = {}) {
+  const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
+  const { catalogue, digest } = await fetchPinnedDevelopCatalogue(options, env);
+  if (digest !== frame.catalogueDigest) {
+    throw new Error(`the fetched catalogue is ${digest}, not the pinned ${frame.catalogueDigest}`);
+  }
+  await adopt(catalogue);
+  assertExistingArtifactMatches({
+    artifactDir: resolve(options['--artifact']),
+    distributionId: frame.id,
     channel: EditionChannel.Develop,
-    username: options[CATALOGUE_USERNAME_FLAG],
-    tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
-    env,
+    evidenceTrustPolicy: await descriptorEvidenceTrust({ channel: EditionChannel.Develop }),
+    pins: frame.pins,
+    engineImage: options['--engine-image'],
+    catalogueDigest: frame.catalogueDigest,
   });
-  console.log(contractAuthoritySourceCommit(catalogue));
 }
 
 async function run(argv, env) {
@@ -297,19 +305,7 @@ async function run(argv, env) {
       return;
     }
     case 'check-existing': {
-      if (customer) {
-        const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
-        assertExistingArtifactMatches({
-          artifactDir: resolve(options['--artifact']),
-          distributionId: frame.id,
-          channel: EditionChannel.Develop,
-          evidenceTrustPolicy: await descriptorEvidenceTrust({ channel: EditionChannel.Develop }),
-          pins: frame.pins,
-          engineImage: options['--engine-image'],
-          catalogueDigest: frame.catalogueDigest,
-        });
-        return;
-      }
+      if (customer) {return checkExistingCustomer(options, env);}
       assertExistingArtifactMatches({
         artifactDir: resolve(options['--artifact']),
         distributionId: id,
@@ -332,7 +328,7 @@ async function run(argv, env) {
         deploySha: options['--deploy-sha'],
         editionsRootUrl: options['--editions-root-url'],
         overrides: parseOverrides(options['--overrides']),
-        resolveHead: headResolver(env),
+        ...headResolver(env),
       });
       writeOnce(options['--out'], pins);
       return;
@@ -343,7 +339,7 @@ async function run(argv, env) {
           options['--out'],
           freezeCustomerSources({
             definition: readStrictJsonFile(options[DEFINITION_FLAG]),
-            resolveHead: headResolver(env),
+            ...headResolver(env),
             sourceRepositoryUrlPrefix: editionWorkspaceConfig().sourceRepositoryUrlPrefix,
           }),
         );
@@ -354,12 +350,10 @@ async function run(argv, env) {
       const declaredSources = composeEdition(parseDistribution, id, snapshotPinSource(pins)).declaredSources;
       writeOnce(
         options['--out'],
-        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), resolveHead: headResolver(env) }),
+        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), ...headResolver(env) }),
       );
       return;
     }
-    case 'kernel-commit':
-      return customerKernelCommit(options, env);
     default:
       throw new Error(`unhandled command ${command}`);
   }