@xemahq/xema 0.29.1 → 0.31.0

package/edition/edition-protocol.mjs

@@ -2,7 +2,7 @@
 // it too.
 //
 // The kernel (`@xemahq/contracts/edition-protocol`) exports the identity of the
-// code this library executes as DATA: `{contentDigest, version}` in
+// code this library executes as DATA: `{contentDigest, provisional, version}` in
 // `dist/edition-protocol/edition-protocol.json`, and the edition contract in
 // `dist/edition-protocol/edition-contract.schema.json` (the identity, the
 // hashing convention, the entry subpaths this library may load, and every
@@ -31,8 +31,8 @@ import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 /** The edition protocols this library interprets: version -> content digest. */
 export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   Object.freeze({
-    version: 1,
-    contentDigest: 'd5b7ce85aa6596730527da64a7f6682684039398a88fd168429f6e4a3f0438bd',
+    version: 5,
+    contentDigest: '326d8b62ba87073fa91cf726eb596f9371904f056db688729d8800cc94c2d646',
   }),
 ]);
 
@@ -52,8 +52,10 @@ const SHA256_HEX = /^[a-f0-9]{64}$/;
 export const EditionProtocolMismatchReason = Object.freeze({
   /** The kernel publishes no edition protocol identity. */
   Undeclared: 'undeclared',
-  /** The identity file is not exactly `{contentDigest, version}`. */
+  /** The identity file is not exactly `{contentDigest, provisional, version}`. */
   Malformed: 'malformed',
+  /** The identity states `provisional: true`: a branch-local working identity, never pinned. */
+  Provisional: 'provisional',
   /** This library supports no protocol of that version. */
   UnsupportedVersion: 'unsupported-version',
   /** The version is supported, but pinned to a different digest. */
@@ -77,7 +79,20 @@ const describe = ({ version, contentDigest }) => `edition protocol v${version} (
 const supportedList = () =>
   SUPPORTED_EDITION_PROTOCOLS.map((protocol) => `v${protocol.version}`).join(', ');
 
-/** Parse identity bytes strictly: exactly a positive integer version and a lowercase SHA-256 hex digest. */
+/** Refuse an identity that states `provisional: true`; nothing provisional is ever read as a protocol. */
+function assertFinalIdentity(identity, label) {
+  if (identity.provisional !== false) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.Provisional,
+      `${label} declares ${describe(identity)} as provisional (a branch-local working identity); a provisional edition protocol is never pinned`,
+    );
+  }
+}
+
+/**
+ * Parse identity bytes strictly: exactly `{contentDigest, provisional, version}`, a positive integer version, a
+ * lowercase SHA-256 hex digest and a boolean `provisional`. An identity stating `provisional: true` is refused.
+ */
 export function parseEditionProtocolIdentity(bytes, label) {
   let identity;
   try {
@@ -92,7 +107,8 @@ export function parseEditionProtocolIdentity(bytes, label) {
     identity === null ||
     typeof identity !== 'object' ||
     Array.isArray(identity) ||
-    Object.keys(identity).sort().join() !== 'contentDigest,version' ||
+    Object.keys(identity).sort().join() !== 'contentDigest,provisional,version' ||
+    typeof identity.provisional !== 'boolean' ||
     !Number.isSafeInteger(identity.version) ||
     identity.version < 1 ||
     typeof identity.contentDigest !== 'string' ||
@@ -100,10 +116,15 @@ export function parseEditionProtocolIdentity(bytes, label) {
   ) {
     throw new EditionProtocolMismatchError(
       EditionProtocolMismatchReason.Malformed,
-      `${label} must be exactly {"contentDigest":"<64 lowercase hex>","version":<positive integer>}`,
+      `${label} must be exactly {"contentDigest":"<64 lowercase hex>","provisional":<boolean>,"version":<positive integer>}`,
     );
   }
-  return Object.freeze({ contentDigest: identity.contentDigest, version: identity.version });
+  assertFinalIdentity(identity, label);
+  return Object.freeze({
+    contentDigest: identity.contentDigest,
+    provisional: identity.provisional,
+    version: identity.version,
+  });
 }
 
 /** The `{version, contentDigest}` a contract file states, or undefined. */
@@ -216,6 +237,7 @@ export function assertKernelEditionProtocol(kernelPackageDir) {
  * it, so the kernel the workspace states must speak exactly that protocol.
  */
 export function assertKernelSpeaksBundledProtocol({ kernelPackageDir, bundled }) {
+  assertFinalIdentity(bundled, 'the edition protocol compiled into this verifier');
   const stated = readKernelEditionProtocol(kernelPackageDir);
   if (stated.version !== bundled.version || stated.contentDigest !== bundled.contentDigest) {
     throw new EditionProtocolMismatchError(

package/edition/edition-workspace.mjs

@@ -70,6 +70,14 @@ export function configureEditionWorkspace(roots) {
   return configured;
 }
 
+/**
+ * State the Kernel root AFTER configuration, for a customer verb that takes its kernel from the catalogue
+ * (kernel-package.mjs) rather than from a flag. Every other configured root is kept; there is still no default.
+ */
+export function stateKernelPackageDir(dir) {
+  configured = Object.freeze({ ...configured, [WorkspaceRoot.Kernel]: assertDirectory(WorkspaceRoot.Kernel, dir) });
+}
+
 function root(name) {
   const value = configured[name];
   if (value === undefined) {

package/edition/external-source-walk.mjs

@@ -376,7 +376,7 @@ function lockedSourceRecord(source, commit) {
   // DistributionLockSchema is `.strict()` and only learned this key in 0.10.0,
   // so any pinned image resolving `^0.9.x` REFUSES THE WHOLE LOCK at boot —
   // `Unrecognized key: "imageNamePrefix"`, before Nest starts. That took
-  // presenca-dev's three lock consumers down on 2026-09-17 and was fixed by
+  // a customer environment's three lock consumers down on 2026-09-17 and was fixed by
   // removing the key from the SEALED LOCK, leaving this line to re-emit it on
   // the next resolve. A workaround standing where a fix belongs removes the
   // signal; this is the fix.

package/edition/image-evidence.mjs

@@ -593,6 +593,13 @@ export function validateEntitlementStatementBinding({
   return statement;
 }
 
+/** Throw the kernel's refusal code, verbatim, when a kernel predicate check returned one. */
+function assertKernelPredicateAccepted(label, refusal) {
+  if (refusal !== undefined) {
+    throw new Error(`${label} is refused: ${refusal}`);
+  }
+}
+
 function assertEvidenceChannel(channel) {
   if (typeof channel !== 'string' || channel === '') {
     throw new Error('evidence verification requires the channel of the edition being verified');
@@ -670,6 +677,7 @@ export function verifySigstoreEvidenceDescriptor({
   parseStatement,
   policyRoot = evidenceRoot,
   trustedCosign,
+  holdProducerWorkflow,
 }) {
   assertEvidenceChannel(channel);
   const statementFile = readExactDescriptorFile(
@@ -744,6 +752,7 @@ export function verifySigstoreEvidenceDescriptor({
     statement.predicate?.producerRun?.producerWorkflowSha;
   let verified = false;
   let verifiedIdentityPolicy;
+  let verifiedCandidateWorkflowSha;
   const verificationErrors = [];
   for (const candidate of candidates) {
     if (!verifiedWorkflowSha) {
@@ -806,6 +815,7 @@ export function verifySigstoreEvidenceDescriptor({
       });
       verified = true;
       verifiedIdentityPolicy = candidate;
+      verifiedCandidateWorkflowSha = verifiedWorkflowSha;
       break;
     } catch (error) {
       verificationErrors.push(
@@ -826,6 +836,16 @@ export function verifySigstoreEvidenceDescriptor({
         verificationErrors.join('; '),
     );
   }
+  // The certificate's workflow commit is held to the data root's operator-stated pin for that workflow's repository.
+  if (holdProducerWorkflow !== undefined) {
+    assertKernelPredicateAccepted(
+      `${predicateType} signer ${verifiedIdentityPolicy.githubWorkflow.repository}`,
+      holdProducerWorkflow({
+        repository: verifiedIdentityPolicy.githubWorkflow.repository,
+        workflowCommit: verifiedCandidateWorkflowSha,
+      }),
+    );
+  }
   return {
     statement,
     statementPath: statementFile.path,
@@ -874,10 +894,12 @@ async function verifyDistributionImageEvidenceSetWithCosign({
     distributionLock,
     imageLock,
     repositoryPins,
-    runtimeSourceIndex: { contractAuthority: expectedContractAuthority },
+    runtimeSourceIndex,
   } = await loadValidatedLocks(distributionId, dataRoot, schemas, {
     editionsRoot,
+    channel,
   });
+  const expectedContractAuthority = runtimeSourceIndex.contractAuthority;
   if (evidenceSet.distributionId !== distributionId) {
     throw new Error(
       `evidence set "${evidenceSet.distributionId}" does not match requested distribution "${distributionId}"`,
@@ -922,6 +944,7 @@ async function verifyDistributionImageEvidenceSetWithCosign({
       parseStatement: schemas.parseImageProducerStatement,
       policyRoot,
       trustedCosign,
+      holdProducerWorkflow: (producer) => schemas.producerWorkflowPinRefusal(runtimeSourceIndex, producer),
     });
     validateProducerStatementBinding({
       statement,
@@ -943,7 +966,7 @@ async function verifyDistributionImageEvidenceSetWithCosign({
     }
   }
 
-  const { statement: completenessStatement } = verifySigstoreEvidenceDescriptor(
+  const { statement: completenessStatement, identityPolicy: completenessPolicy } = verifySigstoreEvidenceDescriptor(
     {
       evidenceRoot,
       descriptor: evidenceSet.completeness,
@@ -956,6 +979,16 @@ async function verifyDistributionImageEvidenceSetWithCosign({
       trustedCosign,
     },
   );
+  // After the signature verified: the channel the predicate states is the verifying policy row's, and the
+  // predicate completes THIS lock. A kernel refusal is terminal and is surfaced by its code.
+  assertKernelPredicateAccepted(
+    `distribution completeness for ${imageLock.distributionId}`,
+    schemas.distributionImagesPredicateChannelRefusal(completenessStatement.predicate, completenessPolicy),
+  );
+  assertKernelPredicateAccepted(
+    `distribution completeness for ${imageLock.distributionId}`,
+    schemas.distributionImagesPredicateLockRefusal(completenessStatement.predicate, distributionLock),
+  );
   validateCompletenessStatementBinding({
     statement: completenessStatement,
     distributionLock,
@@ -1002,6 +1035,7 @@ async function verifyImageDeliveryEntitlementWithCosign({
   completenessStatementDigest,
   customerId,
   distributionId,
+  distributionLock,
   channel,
   mode,
   targetRegistry,
@@ -1023,6 +1057,10 @@ async function verifyImageDeliveryEntitlementWithCosign({
     policyRoot,
     trustedCosign,
   });
+  assertKernelPredicateAccepted(
+    `delivery entitlement for ${customerId}`,
+    schemas.imageDeliveryEntitlementRefusal(statement.predicate, distributionLock),
+  );
   validateEntitlementStatementBinding({
     statement,
     completenessStatementDigest,
@@ -1044,7 +1082,7 @@ async function verifyImageDeliveryEntitlementWithCosign({
  * `submodules/…` repository the vendor builds images from. A customer edition
  * additionally draws biomes from sources declared in its own manifest
  * (`sources[]`, `kind: git`), and the images built from those have a `repo`
- * the index has never heard of and never will: `presenca-biomes`, not
+ * the index has never heard of and never will: `<customer>-biomes`, not
  * `repos/xema-base`. Without a pin for it every such subject is refused as
  * "has no committed repository pin", so a customer could verify the vendor's
  * images in its edition and never its own.
@@ -1124,20 +1162,57 @@ export function externalSourceRepositoryPins({
  * tolerant read-only posture `parseDistributionLockForReading` gives a
  * runtime, without depending on which kernel the bundle was built from.
  *
- * `schemaVersion` must be 5, the one grammar there is (the kernel's
- * `DISTRIBUTION_LOCK_SCHEMA_VERSIONS`): a pre-v5 lock is refused, with no
- * compatibility path.
+ * Two grammars exist, and which one is accepted is decided by `channel`, the
+ * kernel evidence channel (`EVIDENCE_CHANNELS`) the caller operates on; it is
+ * required and has no default. An UNSEALED lock (it carries `unsealedSchema`;
+ * every edition lock on develop is one by design) is accepted ONLY on the
+ * develop channel, read through the kernel's `parseUnsealedDistributionLock`.
+ * Every other channel requires a SEALED lock: images sealed over an unsealed
+ * lock is the crash state every sealed reader refuses, and a release statement
+ * must never verify over it. A SEALED lock must have `schemaVersion` 5 (the
+ * kernel's `DISTRIBUTION_LOCK_SCHEMA_VERSIONS`): a pre-v5 lock is refused, with
+ * no compatibility path. Both carry `distributionId` and `inputHash`, and
+ * sealing preserves them, so either way the binding is the same two fields.
  */
-export function readDistributionLockBinding(raw) {
+/** The one evidence channel an unsealed distribution lock is read on. */
+const UNSEALED_LOCK_CHANNEL = 'develop';
+
+/**
+ * The channel a distribution lock is read for: one of the kernel's
+ * `EVIDENCE_CHANNELS`, stated by the caller. Missing or unknown is refused.
+ */
+function assertLockReadingChannel(channel, schemas) {
+  if (!schemas) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  if (!schemas.EVIDENCE_CHANNELS.includes(channel)) {
+    throw new Error(
+      `a distribution lock is read for one evidence channel (${schemas.EVIDENCE_CHANNELS.join(' | ')}); got ${JSON.stringify(channel)}`,
+    );
+  }
+}
+
+export function readDistributionLockBinding(raw, schemas, channel) {
+  assertLockReadingChannel(channel, schemas);
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
     throw new Error('distribution.lock.json is not a JSON object');
   }
-  const { schemaVersion, distributionId, inputHash } = raw;
-  if (schemaVersion !== 5) {
+  let source = raw;
+  if ('unsealedSchema' in raw) {
+    if (channel !== UNSEALED_LOCK_CHANNEL) {
+      throw new Error(
+        `distribution.lock.json is unsealed; the ${channel} channel accepts only a sealed lock (schemaVersion 5) — ` +
+          `an unsealed lock is read on the ${UNSEALED_LOCK_CHANNEL} channel only`,
+      );
+    }
+    source = schemas.parseUnsealedDistributionLock(raw);
+  } else if (raw.schemaVersion !== 5) {
     throw new Error(
-      `distribution.lock.json has schemaVersion ${String(schemaVersion)}; the only accepted grammar is 5 (regenerate the lock)`,
+      `distribution.lock.json is neither an unsealed lock (carrying unsealedSchema) ` +
+        `nor a sealed lock (schemaVersion 5); it has schemaVersion ${String(raw.schemaVersion)} (regenerate the lock)`,
     );
   }
+  const { distributionId, inputHash } = source;
   // The id is format-checked only. Which edition it must equal is decided by
   // the bindings that USE it — the completeness predicate and the evidence set
   // compare it to the image lock and the signed statement — exactly as before
@@ -1149,21 +1224,63 @@ export function readDistributionLockBinding(raw) {
         'expected 64 lowercase sha256 hex characters',
     );
   }
-  return Object.freeze({ schemaVersion, distributionId, inputHash });
+  return Object.freeze({ distributionId, inputHash });
+}
+
+/**
+ * The edition's sealed `distribution.lock.json`, parsed by the kernel's strict lock parser: the document the
+ * predicates' `lockDigest` is computed over. Held to the binding rules of {@link readDistributionLockBinding} first.
+ */
+export function readEditionDistributionLock(editionsRoot, distributionId, schemas, channel) {
+  assertLockReadingChannel(channel, schemas);
+  const raw = JSON.parse(
+    readFileSync(join(editionsRoot, distributionId, 'distribution.lock.json'), 'utf8'),
+  );
+  readDistributionLockBinding(raw, schemas, channel);
+  // The WHOLE lock in its own grammar, never the two-field binding: the
+  // predicate and entitlement refusals recompute distributionLockDigest over
+  // what this returns, so an unsealed develop lock is digested as itself.
+  return 'unsealedSchema' in raw ? schemas.parseUnsealedDistributionLock(raw) : schemas.parseDistributionLock(raw);
 }
 
 /**
  * Read and validate an edition's two locks plus the runtime image source index
- * they must agree with.
+ * they must agree with. The distribution lock is read for `channel`
+ * ({@link readDistributionLockBinding}); the rest is {@link loadValidatedImageLocks}.
+ */
+export async function loadValidatedLocks(
+  distributionId,
+  dataRoot,
+  schemas,
+  { editionsRoot, channel },
+) {
+  if (!schemas) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  const distributionLock = readEditionDistributionLock(
+    editionsRoot,
+    distributionId,
+    schemas,
+    channel,
+  );
+  return {
+    distributionLock,
+    ...(await loadValidatedImageLocks(distributionId, dataRoot, schemas, { editionsRoot })),
+  };
+}
+
+/**
+ * Read and validate an edition's image lock plus the runtime image source index
+ * it must agree with; the distribution lock is not read.
  *
  * `dataRoot` holds the runtime image source index, read from it always.
- * `editionsRoot` is where `<id>/distribution.lock.json`,
- * `<id>/images.lock.json` and `<id>/xema-distribution.json` are read from. The
- * manifest extends the repository pins with the edition's own declared sources
+ * `editionsRoot` is where `<id>/images.lock.json` and
+ * `<id>/xema-distribution.json` are read from. The manifest extends the
+ * repository pins with the edition's own declared sources
  * ({@link externalSourceRepositoryPins}); the verifier grades the editions
- * checkout so all three files are HEAD-bound.
+ * checkout so the files it reads are HEAD-bound.
  */
-export async function loadValidatedLocks(
+export async function loadValidatedImageLocks(
   distributionId,
   dataRoot,
   schemas,
@@ -1172,14 +1289,6 @@ export async function loadValidatedLocks(
   if (!schemas) {
     throw new Error('trusted kernel distribution schemas are required');
   }
-  const distributionLock = readDistributionLockBinding(
-    JSON.parse(
-      readFileSync(
-        join(editionsRoot, distributionId, 'distribution.lock.json'),
-        'utf8',
-      ),
-    ),
-  );
   const imageLock = validateImmutableImageLock(
     schemas.parseImageLock(
       JSON.parse(
@@ -1235,7 +1344,6 @@ export async function loadValidatedLocks(
   }
   return {
     schemas,
-    distributionLock,
     imageLock,
     runtimeSourceIndex,
     repositoryPins,

package/edition/kernel-capability-domain.mjs

@@ -0,0 +1,30 @@
+import { createRequire } from 'node:module';
+
+import { kernelDistPath } from './edition-workspace.mjs';
+
+const requireFromHere = createRequire(import.meta.url);
+
+let schema;
+
+/**
+ * Is `value` a capability domain? The kernel's `CapabilityDomainSchema` is the
+ * ONE grammar; it is read from the distribution subpath, the only plane the
+ * edition protocol exposes to this library. Nothing here restates the pattern.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isKernelCapabilityDomain(value) {
+  if (schema === undefined) {
+    const path = kernelDistPath('distribution', 'index.js');
+    const mod = requireFromHere(path);
+    if (typeof mod.CapabilityDomainSchema?.safeParse !== 'function') {
+      throw new Error(
+        `Built kernel distribution module at ${path} does not export CapabilityDomainSchema — ` +
+          'the dist is stale; rebuild kernel-contracts at a commit that carries it.',
+      );
+    }
+    schema = mod.CapabilityDomainSchema;
+  }
+  return schema.safeParse(value).success;
+}

package/edition/kernel-package.mjs

@@ -0,0 +1,193 @@
+// kernel-package — the customer edition's kernel: `@xemahq/contracts` taken from public npm.
+//
+// A catalogue names its kernel package (`kernel: {name, version, integrity}`, catalogue.mjs). This module is
+// the ONE place that touches npm: it downloads that exact tarball (public, no credential, no .npmrc, no
+// npm/pnpm process), holds it by the catalogue's integrity BEFORE anything is extracted, extracts it with the
+// system `tar`, links its runtime dependencies to the copies this CLI itself ships, and proves the package is
+// the contract authority the catalogue was resolved under: first by its edition protocol identity (data, no
+// code executed), and only then, by loading its schemas, by the constants the authority was derived with.
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+import { readKernelEditionProtocol } from './edition-protocol.mjs';
+import { cacheDir, stateKernelPackageDir } from './edition-workspace.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+
+export const KERNEL_PACKAGE_NAME = '@xemahq/contracts';
+const MAX_TARBALL_BYTES = 64 * 1024 * 1024;
+const DEPENDENCY_NAME = /^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/;
+const EXACT = /^(\d+)\.(\d+)\.(\d+)$/;
+const CARET = /^\^(\d+)\.(\d+)\.(\d+)$/;
+
+export class KernelPackageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'KernelPackageError';
+  }
+}
+
+export const kernelTarballUrl = (version) => `https://registry.npmjs.org/${KERNEL_PACKAGE_NAME}/-/contracts-${version}.tgz`;
+
+/** The npm integrity string of `bytes`: `sha512-<base64>`. */
+export const integrityOf = (bytes) => `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
+
+/** The published tarball of `@xemahq/contracts@version`, bounded in size. */
+export async function fetchKernelTarball(version, { fetch = globalThis.fetch } = {}) {
+  const url = kernelTarballUrl(version);
+  const response = await fetch(url);
+  if (response.status === 404) {
+    throw new KernelPackageError(`${KERNEL_PACKAGE_NAME}@${version} is not published on npm (${url}): a catalogue names a published kernel`);
+  }
+  if (!response.ok) {throw new KernelPackageError(`${url} answered HTTP ${response.status}`);}
+  const declared = Number(response.headers.get('content-length') ?? 0);
+  if (declared > MAX_TARBALL_BYTES) {throw new KernelPackageError(`${url} declares ${declared} bytes, over the ${MAX_TARBALL_BYTES} byte bound`);}
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.length;
+    if (size > MAX_TARBALL_BYTES) {throw new KernelPackageError(`${url} is over the ${MAX_TARBALL_BYTES} byte bound`);}
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Does `version` (exactly x.y.z) satisfy `range`? Exactly two range forms are supported: `x.y.z`, and
+ * `^x.y.z` (x > 0: >=x.y.z <(x+1).0.0; 0.y.z: >=0.y.z <0.(y+1).0). Any other form is refused.
+ */
+export function satisfiesDeclaredRange(version, range) {
+  const have = EXACT.exec(version)?.slice(1).map(Number);
+  if (have === undefined) {throw new KernelPackageError(`version ${JSON.stringify(version)} is not an exact x.y.z version`);}
+  const exact = EXACT.exec(range)?.slice(1).map(Number);
+  if (exact !== undefined) {return isDeepStrictEqual(have, exact);}
+  const caret = CARET.exec(range)?.slice(1).map(Number);
+  if (caret === undefined) {throw new KernelPackageError(`range ${JSON.stringify(range)} is not x.y.z or ^x.y.z, the only forms a kernel dependency may declare`);}
+  const compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+  const upper = caret[0] > 0 ? [caret[0] + 1, 0, 0] : [0, caret[1] + 1, 0];
+  return compare(have, caret) >= 0 && compare(have, upper) < 0;
+}
+
+/** The directory of `name` as this CLI itself ships it: its own resolution first, then its installed kernel's. */
+function shippedPackageDir(name) {
+  const own = createRequire(import.meta.url);
+  const attempts = [() => own, () => createRequire(realpathSync(own.resolve(`${KERNEL_PACKAGE_NAME}/package.json`)))];
+  for (const requireFrom of attempts) {
+    try {
+      return dirname(realpathSync(requireFrom().resolve(`${name}/package.json`)));
+    } catch (error) {
+      if (error?.code !== 'MODULE_NOT_FOUND' && error?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') {throw error;}
+    }
+  }
+  return undefined;
+}
+
+function linkRuntimeDependencies(packageDir) {
+  const manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+  const nodeModules = dirname(manifest.name.startsWith('@') ? dirname(packageDir) : packageDir);
+  for (const [name, range] of Object.entries(manifest.dependencies ?? {})) {
+    if (!DEPENDENCY_NAME.test(name)) {throw new KernelPackageError(`${KERNEL_PACKAGE_NAME} declares a dependency named ${JSON.stringify(name)}, which is not a package name`);}
+    const shipped = shippedPackageDir(name);
+    if (shipped === undefined) {throw new KernelPackageError(`${KERNEL_PACKAGE_NAME} depends on ${name}@${range}, which this CLI does not ship`);}
+    const version = JSON.parse(readFileSync(join(shipped, 'package.json'), 'utf8')).version;
+    let ok;
+    try {
+      ok = satisfiesDeclaredRange(version, range);
+    } catch (error) {
+      throw new KernelPackageError(`${KERNEL_PACKAGE_NAME} dependency ${name}: ${error.message} (this CLI ships ${version})`);
+    }
+    if (!ok) {throw new KernelPackageError(`${KERNEL_PACKAGE_NAME} depends on ${name}@${range}, but this CLI ships ${name}@${version}`);}
+    const link = join(nodeModules, name);
+    mkdirSync(dirname(link), { recursive: true });
+    symlinkSync(shipped, link, 'dir');
+  }
+}
+
+/**
+ * Download the catalogue's kernel, hold it to `kernel.integrity` (refused before anything is written), extract it
+ * under `<cacheDir>/kernel-npm/<version>-<16 hex of the sha512>/node_modules/@xemahq/contracts` (fresh every run)
+ * and link its runtime dependencies. Returns the package directory.
+ */
+export async function materializeKernelPackage({ kernel, cacheDir, fetchTarball = fetchKernelTarball }) {
+  const bytes = await fetchTarball(kernel.version);
+  const actual = integrityOf(bytes);
+  if (actual !== kernel.integrity) {
+    throw new KernelPackageError(`${KERNEL_PACKAGE_NAME}@${kernel.version} integrity ${actual} is not the catalogue's kernel.integrity ${kernel.integrity}`);
+  }
+  const hex = createHash('sha512').update(bytes).digest('hex').slice(0, 16);
+  const root = join(cacheDir, 'kernel-npm', `${kernel.version}-${hex}`);
+  const packageDir = join(root, 'node_modules', ...KERNEL_PACKAGE_NAME.split('/'));
+  rmSync(root, { recursive: true, force: true });
+  mkdirSync(packageDir, { recursive: true });
+  const extracted = spawnSync('tar', ['-xzf', '-', '-C', packageDir, '--strip-components', '1'], { input: bytes, stdio: ['pipe', 'ignore', 'pipe'] });
+  if (extracted.error !== undefined) {throw new KernelPackageError(`tar could not run: ${extracted.error.message}`);}
+  if (extracted.status !== 0) {throw new KernelPackageError(`tar failed extracting ${KERNEL_PACKAGE_NAME}@${kernel.version}: ${extracted.stderr.toString().trim()}`);}
+  const manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+  if (manifest.name !== KERNEL_PACKAGE_NAME || manifest.version !== kernel.version) {
+    throw new KernelPackageError(`the tarball holds ${manifest.name}@${manifest.version}, not ${KERNEL_PACKAGE_NAME}@${kernel.version}`);
+  }
+  linkRuntimeDependencies(packageDir);
+  return packageDir;
+}
+
+const refuse = (field, wanted, got) => new KernelPackageError(`the kernel package is not the catalogue's contract authority: ${field} is ${JSON.stringify(got)}, the catalogue states ${JSON.stringify(wanted)}`);
+
+/**
+ * The kernel package at `kernelPackageDir` is the contract authority of `catalogue`. First its identity, read as
+ * data (final, which the protocol read refuses otherwise, and the catalogue's digest); only then are its schemas loaded and held to the authority's constants.
+ * `sourceCommit` is provenance and is not compared. Returns the loaded schemas.
+ */
+export async function assertKernelPackageIsCatalogueAuthority({ catalogue, kernelPackageDir, loadSchemas }) {
+  const authority = catalogue.contractAuthority;
+  const identity = readKernelEditionProtocol(kernelPackageDir);
+  if (identity.contentDigest !== authority.contentDigest) {throw refuse('contentDigest', authority.contentDigest, identity.contentDigest);}
+  const schemas = await loadSchemas();
+  if (!isDeepStrictEqual(authority.sourcePaths, schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS)) {
+    throw refuse('sourcePaths', authority.sourcePaths, schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS);
+  }
+  const constants = [
+    ['generatorIdentity', schemas.XEMA_KERNEL_CONTRACT_AUTHORITY_GENERATOR],
+    ['repositoryUrl', schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL],
+    ['contentHashAlgorithm', schemas.KernelContractContentHashAlgorithm.LengthFramedGitPathModeBlobV1],
+  ];
+  for (const [field, kernelValue] of constants) {
+    if (authority[field] !== kernelValue) {throw refuse(field, authority[field], kernelValue);}
+  }
+  return schemas;
+}
+
+/**
+ * The `kernel` row a VENDOR catalogue carries: the published `@xemahq/contracts` the vendor's own kernel
+ * (`kernelPackageDir`) is, taken from npm, proved to be `contractAuthority` and held by its integrity.
+ * An unpublished version is refused. The downloaded package is extracted to a temporary directory and removed.
+ */
+export async function kernelPackageOfAuthority({ kernelPackageDir, contractAuthority, fetchTarball = fetchKernelTarball, loadSchemas = loadKernelDistributionSchemas }) {
+  const manifest = JSON.parse(readFileSync(join(kernelPackageDir, 'package.json'), 'utf8'));
+  if (manifest.name !== KERNEL_PACKAGE_NAME) {throw new KernelPackageError(`the vendor kernel is ${manifest.name}, not ${KERNEL_PACKAGE_NAME}`);}
+  const bytes = await fetchTarball(manifest.version);
+  const kernel = { name: KERNEL_PACKAGE_NAME, version: manifest.version, integrity: integrityOf(bytes) };
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-kernel-npm-'));
+  try {
+    const packageDir = await materializeKernelPackage({ kernel, cacheDir: scratch, fetchTarball: async () => bytes });
+    await assertKernelPackageIsCatalogueAuthority({ catalogue: { contractAuthority }, kernelPackageDir: packageDir, loadSchemas });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+  return kernel;
+}
+
+/**
+ * A customer verb's one step between fetching its catalogue and using any kernel schema: the catalogue's kernel is
+ * downloaded into the cache root, stated as the workspace's Kernel root, and proved to be the catalogue's contract
+ * authority. Returns the kernel's distribution schemas.
+ */
+export async function adoptCatalogueKernel(catalogue) {
+  const kernelPackageDir = await materializeKernelPackage({ kernel: catalogue.kernel, cacheDir: cacheDir() });
+  stateKernelPackageDir(kernelPackageDir);
+  return assertKernelPackageIsCatalogueAuthority({ catalogue, kernelPackageDir, loadSchemas: loadKernelDistributionSchemas });
+}