@xemahq/xema 0.25.1 → 0.27.0

package/edition/edition-config.mjs

@@ -0,0 +1,207 @@
+// The deployment-specific coordinates the edition library needs and must not
+// carry: which image registry, chart registry and source
+// organisation a workspace belongs to. They are DATA, read from
+// `<dataRoot>/edition-workspace.json`; there is no default for any of them, and
+// a file with a missing, unknown or malformed key is refused. `evidenceTrustPolicy`
+// declares the data root's evidence gating; its `required` flag has no default.
+
+import { join } from 'node:path';
+
+import { dataRoot } from './edition-workspace.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import {
+  parseConfinedBiomes,
+  parseConnectorSources,
+  parseFirstPartySources,
+  parsePinRoles,
+  parsePlatformServiceSources,
+  parseRuntimeImageSources,
+} from './workspace-sections.mjs';
+
+/** A refusal of edition-workspace.json itself. */
+export class EditionWorkspaceConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'EditionWorkspaceConfigError';
+  }
+}
+
+export const EDITION_WORKSPACE_CONFIG_FILE = 'edition-workspace.json';
+export const EDITION_WORKSPACE_CONFIG_SCHEMA_VERSION = 1;
+
+// The product-data sections. Each is optional in the file (a customer data root
+// legitimately has none of some), and each is REQUIRED at the moment an
+// operation reads it: `workspaceSection` refuses a missing one by name.
+const SECTIONS = Object.freeze({
+  firstPartySources: parseFirstPartySources,
+  platformServiceSources: parsePlatformServiceSources,
+  connectorSources: parseConnectorSources,
+  runtimeImageSources: parseRuntimeImageSources,
+  pinRoles: parsePinRoles,
+  confinedBiomes: parseConfinedBiomes,
+});
+
+const KEYS = Object.freeze([
+  'schemaVersion',
+  'imageRegistry',
+  'chartRegistry',
+  'chartPublishers',
+  'sourceRepositoryUrlPrefix',
+  'sourceAuthUsername',
+  'evidenceTrustPolicy',
+  ...Object.keys(SECTIONS),
+]);
+
+const IMAGE_REGISTRY = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
+const CHART_REGISTRY = /^oci:\/\/[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
+// A data-root-relative POSIX path: no leading slash, no empty, `.` or `..` segment.
+const DATA_ROOT_RELATIVE_PATH = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+const SOURCE_URL_PREFIX = /^https:\/\/[a-z0-9.-]+(\/[A-Za-z0-9._-]+)+\/$/;
+
+function requireString(config, key, pattern, shape) {
+  const value = config[key];
+  if (typeof value !== 'string' || !pattern.test(value)) {
+    throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: "${key}" must be ${shape}; got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+/** The git username first-party sources authenticate as: declared, never defaulted (GitHub says `x-access-token`, other forges differ). */
+function requireSourceAuthUsername(config) {
+  const value = config.sourceAuthUsername;
+  if (typeof value !== 'string' || value.length === 0 || /[\s:]/.test(value)) {
+    throw new EditionWorkspaceConfigError(
+      `${EDITION_WORKSPACE_CONFIG_FILE}: "sourceAuthUsername" is required: the non-empty git username (no whitespace or ":") ` +
+        `that first-party source tokens authenticate as; got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}
+
+function requirePublishers(config) {
+  const value = config.chartPublishers;
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: "chartPublishers" must be a non-empty array of {index, repo}`);
+  }
+  const seen = new Set();
+  return Object.freeze(
+    value.map((entry) => {
+      const keys = entry !== null && typeof entry === 'object' ? Object.keys(entry).sort() : [];
+      if (keys.join() !== 'index,repo' || typeof entry.index !== 'string' || typeof entry.repo !== 'string' || !entry.index || !entry.repo) {
+        throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: every "chartPublishers" entry is exactly {index, repo}, both non-empty strings`);
+      }
+      if (seen.has(entry.index)) {
+        throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: duplicate chart publisher index "${entry.index}"`);
+      }
+      seen.add(entry.index);
+      return Object.freeze({ index: entry.index, repo: entry.repo });
+    }),
+  );
+}
+
+const EVIDENCE_TRUST_POLICY_KEYS = Object.freeze(['pin', 'policy', 'required']);
+
+function isDataRootRelativePath(value) {
+  return (
+    typeof value === 'string' &&
+    DATA_ROOT_RELATIVE_PATH.test(value) &&
+    value.split('/').every((segment) => segment !== '.' && segment !== '..')
+  );
+}
+
+/**
+ * The MANDATORY `evidenceTrustPolicy` declaration. `required` is a boolean with
+ * no default: whether this data root's editions MUST be evidence-gated. The
+ * policy is either declared (`policy` and `pin`, two data-root-relative paths)
+ * or absent (both null); a declared policy is enforced whether or not it is
+ * required. `required: true` with no policy is a state the shape allows and
+ * `xema edition check` refuses (EvidenceTrustRequiredError), so the refusal
+ * names the missing policy rather than a malformed file.
+ */
+function requireEvidenceTrustPolicy(config) {
+  if (!Object.hasOwn(config, 'evidenceTrustPolicy')) {
+    throw new EditionWorkspaceConfigError(
+      `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy" is required: {"required": true, "policy": ..., "pin": ...} ` +
+        'or {"required": false} (no default: say whether this data root\'s editions must be evidence-gated)',
+    );
+  }
+  const value = config.evidenceTrustPolicy;
+  const shapeError = () =>
+    new EditionWorkspaceConfigError(
+      `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy" is exactly {required: boolean} or {required, policy, pin} with both paths data-root-relative`,
+    );
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {throw shapeError();}
+  const keys = Object.keys(value).sort();
+  if (!keys.every((key) => EVIDENCE_TRUST_POLICY_KEYS.includes(key)) || typeof value.required !== 'boolean') {throw shapeError();}
+  const declared = keys.length > 1;
+  if (declared && keys.join() !== EVIDENCE_TRUST_POLICY_KEYS.join()) {throw shapeError();}
+  if (!declared) {return Object.freeze({ required: value.required, policy: null, pin: null });}
+  for (const key of ['policy', 'pin']) {
+    if (!isDataRootRelativePath(value[key])) {
+      throw new EditionWorkspaceConfigError(
+        `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy.${key}" must be a data-root-relative POSIX path without "." or ".." segments; got ${JSON.stringify(value[key])}`,
+      );
+    }
+  }
+  if (value.policy === value.pin) {
+    throw new EditionWorkspaceConfigError(`${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy.policy" and ".pin" must be different files`);
+  }
+  return Object.freeze({ required: value.required, policy: value.policy, pin: value.pin });
+}
+
+/** Validate a parsed config document; returns the frozen, typed config. */
+export function parseEditionWorkspaceConfig(document) {
+  if (document === null || typeof document !== 'object' || Array.isArray(document)) {
+    throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE} must be a JSON object`);
+  }
+  for (const key of Object.keys(document)) {
+    if (!KEYS.includes(key)) {throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: unknown key "${key}"`);}
+  }
+  if (document.schemaVersion !== EDITION_WORKSPACE_CONFIG_SCHEMA_VERSION) {
+    throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: schemaVersion must be ${EDITION_WORKSPACE_CONFIG_SCHEMA_VERSION}`);
+  }
+  const sections = Object.fromEntries(
+    Object.entries(SECTIONS)
+      .filter(([key]) => document[key] !== undefined)
+      .map(([key, parse]) => [key, parse(document[key])]),
+  );
+  return Object.freeze({
+    ...sections,
+    imageRegistry: requireString(document, 'imageRegistry', IMAGE_REGISTRY, '<host>/<namespace> with no scheme or trailing slash'),
+    chartRegistry: requireString(document, 'chartRegistry', CHART_REGISTRY, 'oci://<host>/<path>'),
+    chartPublishers: requirePublishers(document),
+    sourceRepositoryUrlPrefix: requireString(document, 'sourceRepositoryUrlPrefix', SOURCE_URL_PREFIX, 'https://<host>/<organisation>/ with a trailing slash'),
+    sourceAuthUsername: requireSourceAuthUsername(document),
+    evidenceTrustPolicy: requireEvidenceTrustPolicy(document),
+  });
+}
+
+let cached;
+
+/** The workspace config, read once per data root. */
+export function editionWorkspaceConfig() {
+  const root = dataRoot();
+  if (cached?.root !== root) {
+    cached = { root, config: parseEditionWorkspaceConfig(readStrictJsonFile(join(root, EDITION_WORKSPACE_CONFIG_FILE))) };
+  }
+  return cached.config;
+}
+
+/** Forget the cached config (a test that rewrites the file in place). */
+export function resetEditionWorkspaceConfig() {
+  cached = undefined;
+}
+
+/**
+ * One product-data section, refused by name when the data root does not carry
+ * it. `needed` says which operation wanted it, so the refusal is actionable.
+ */
+export function workspaceSection(name, needed) {
+  const section = editionWorkspaceConfig()[name];
+  if (section === undefined) {
+    throw new Error(
+      `${EDITION_WORKSPACE_CONFIG_FILE} in ${dataRoot()} has no "${name}" section, which ${needed} needs`,
+    );
+  }
+  return section;
+}

package/edition/edition-constants.mjs

@@ -0,0 +1,57 @@
+// edition-constants — the closed vocabulary of the edition OCI artifact, in one
+// place so the writer, the guards and the workflow cannot disagree about what an
+// edition IS. ONE layout serves both channels: an artifact at
+// `<registry>/xema-edition-<id>`, addressed by digest, carrying a titled
+// descriptor layer plus the lock layers.
+
+import { EditionChannel } from './edition-channel.mjs';
+import { EDITION_CHART_SET_FILE } from './edition-chart-set.mjs';
+import editionContract from './edition-contract.json' with { type: 'json' };
+
+/**
+ * The vocabulary itself lives in edition-contract.json, the ONE source:
+ * xema-deploy vendors that file byte for byte and builds its constants from it,
+ * so the producer and the consumer of an edition cannot disagree about its names.
+ * It is a JSON import, not a read at run time, so a bundle (the evidence
+ * verifier) carries it.
+ */
+export const EDITION_CONTRACT = Object.freeze(structuredClone(editionContract));
+
+/** The descriptor layer's file name; its `org.opencontainers.image.title`. */
+export const EDITION_DESCRIPTOR_FILE = EDITION_CONTRACT.descriptorFile;
+export const EDITION_DESCRIPTOR_SCHEMA = EDITION_CONTRACT.descriptorSchema;
+/** The ONE artifactType of every edition artifact, develop or release. */
+export const EDITION_ARTIFACT_TYPE = EDITION_CONTRACT.artifactType;
+/** The repository name prefix: `<registry>/<prefix><id>`. */
+export const EDITION_REPOSITORY_PREFIX = EDITION_CONTRACT.repositoryPrefix;
+
+export { EditionChannel };
+
+/** Whether the data root's editions are evidence-gated, as the descriptor records it. */
+export const EvidenceTrustState = Object.freeze({ Armed: 'armed', NotArmed: 'not-armed' });
+
+/** The owner-relative segment of a develop image repository: `<host>/<owner>/<segment>/<name>`. */
+export const DEVELOP_IMAGE_NAMESPACE_SEGMENT = EDITION_CONTRACT.imageNamespaceSegment;
+
+/** The titled layers only an OFFERING artifact carries (not locks): the catalogue a customer edition resolves against. */
+export const EDITION_OFFERING_LAYERS = Object.freeze({ ...EDITION_CONTRACT.offeringLayers });
+
+/** The one provenance pin that is not a commit: the digest of the catalogue artifact a customer edition was resolved against. */
+export const CATALOGUE_PIN_KEY = 'catalogue';
+if (!(CATALOGUE_PIN_KEY in EDITION_CONTRACT.provenancePins)) {
+  throw new Error('edition-contract.json provenancePins does not declare the catalogue pin');
+}
+
+/** The lock files an edition can carry. */
+export const EditionLockFile = Object.freeze({
+  Distribution: 'distribution.lock.json',
+  Images: 'images.lock.json',
+  Authorization: 'authorization.lock.json',
+  ChartSet: EDITION_CHART_SET_FILE,
+});
+
+/** The locks of an edition, in the order the descriptor lists them and the artifact pushes them; the same for both channels. */
+export const EDITION_LOCKS = Object.freeze([...EDITION_CONTRACT.locks]);
+
+/** Every file of the artifact, in the order it is pushed. */
+export const EDITION_FILES = Object.freeze([EDITION_DESCRIPTOR_FILE, ...EDITION_LOCKS]);

package/edition/edition-contract.json

@@ -0,0 +1,23 @@
+{
+  "schema": "xema.edition-contract/v1",
+  "artifactType": "application/vnd.xema.edition.v1+json",
+  "repositoryPrefix": "xema-edition-",
+  "descriptorFile": "xema-edition.json",
+  "descriptorSchema": "xema.edition/v1",
+  "locks": ["distribution.lock.json", "images.lock.json", "authorization.lock.json", "chart-set.lock.json"],
+  "offeringLayers": { "catalogue": "catalogue.json" },
+  "provenancePins": {
+    "catalogue": "the sha256 digest (sha256:<64 hex>) of the offering artifact a customer edition was resolved against; every other pin is a 40-hex commit"
+  },
+  "imageNamespaceSegment": "dev",
+  "evidenceTrust": {
+    "states": {
+      "armed": "the data root declares an evidence trust policy that is pinned and ARMED on the channel of the edition",
+      "not-armed": "a release edition: exactly, the data root's evidenceTrustPolicy.required is false and it has no policy armed on the release channel; a develop edition: its policy is not armed on the develop channel, whatever required says"
+    },
+    "refusal": {
+      "code": "EVIDENCE_TRUST_REQUIRED_UNARMED",
+      "when": "evidenceTrustPolicy.required is true while the policy is not armed on the release channel (none declared, or declared but UNARMED or PARTIALLY ARMED there): `xema edition check` fails, no release edition is sealed and no release artifact is written, so a release descriptor never records not-armed for a required data root. Arming is judged per channel: a develop edition admits not-armed"
+    }
+  }
+}

package/edition/edition-list.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// `xema edition list`: the offering ids of an editions root, as JSON.
+//
+// usage: xema edition list --editions-root <dir>
+// stdout: {"schemaVersion":1,"editions":["<id>",…]} in canonical id order.
+
+import { discoverDistributionIds } from './distribution-paths.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  editionsRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { serializeJson } from './lib.mjs';
+
+export function listEditions({ editionsRoot: root }) {
+  return { schemaVersion: 1, editions: discoverDistributionIds(root) };
+}
+
+function main() {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Editions]);
+  if (rest.length > 0) {
+    throw new Error('usage: xema edition list --editions-root <dir>');
+  }
+  process.stdout.write(serializeJson(listEditions({ editionsRoot: editionsRoot() })));
+}
+
+if (isEntryModule(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`[edition-list] ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/edition/edition-locks.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// `xema edition locks <id>`: one edition's validated locks, as JSON.
+//
+// usage: xema edition locks <id> --data-root <dir> --editions-root <dir> --kernel <dir>
+//
+// The locks are read and validated exactly as the evidence verifier reads
+// them: `images.lock.json` and `distribution.lock.json` under the kernel
+// schema, immutable coordinates only, and the image lock's kernel contract
+// authority equal to the data root's runtime image source index. A consumer
+// reads this output instead of parsing or validating a lock itself.
+
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  dataRoot,
+  editionsRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { loadValidatedLocks } from './image-evidence.mjs';
+import { compareStrings, loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+
+const USAGE =
+  'usage: xema edition locks <id> --data-root <dir> --editions-root <dir> --kernel <dir>';
+
+export async function readEditionLocks({ distributionId, dataRoot: data, editionsRoot: editions, schemas }) {
+  assertCanonicalDistributionId(distributionId);
+  const { distributionLock, imageLock, repositoryPins, runtimeSourceIndex } =
+    await loadValidatedLocks(distributionId, data, schemas, { editionsRoot: editions });
+  return {
+    schemaVersion: 1,
+    distributionId,
+    contractAuthority: runtimeSourceIndex.contractAuthority,
+    distributionLock,
+    imageLock,
+    repositoryPins: [...repositoryPins.values()].sort((left, right) =>
+      compareStrings(left.repo, right.repo),
+    ),
+  };
+}
+
+async function main() {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
+    WorkspaceRoot.Data,
+    WorkspaceRoot.Editions,
+    WorkspaceRoot.Kernel,
+  ]);
+  if (rest.length !== 1) {
+    throw new Error(USAGE);
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  process.stdout.write(
+    serializeJson(
+      await readEditionLocks({
+        distributionId: rest[0],
+        dataRoot: dataRoot(),
+        editionsRoot: editionsRoot(),
+        schemas,
+      }),
+    ),
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[edition-locks] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/edition/edition-protocol.mjs

@@ -0,0 +1,228 @@
+// The edition protocol this library speaks, and the check that a kernel speaks
+// it too.
+//
+// The kernel (`@xemahq/contracts/edition-protocol`) exports the identity of the
+// code this library executes as DATA: `{contentDigest, 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
+// kernel source file those subpaths load at runtime). `contentDigest` is the
+// kernel contract authority digest over the exact bytes of those files.
+//
+// The digest is a CONSERVATIVE, deterministic stand-in for protocol semantics.
+// Any change to accepted or refused edition semantics MUST change it; a
+// behaviour-preserving refactor MAY change it too, and the cost is a repin,
+// which is accepted. Semantic equivalence isn't computable, so it is never
+// detected.
+//
+// This library declares the versions it supports, each pinned to one digest,
+// and vendors a copy of each supported contract (`vendored/`, held to its pin
+// by `edition-protocol.test.mjs`). A kernel is accepted only when its identity
+// names a supported version, its digest is the one this library pins for that
+// version, and its contract file states that same identity. Nothing else about
+// the kernel is compared: a kernel change outside the protocol's source closure
+// needs no CLI release; a change inside it needs the CLI to add support.
+// Checking a kernel reads two files and executes nothing from it.
+
+import { realpathSync } from 'node:fs';
+
+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',
+  }),
+]);
+
+/** Where a kernel package publishes its identity and its contract, package-relative. */
+export const KERNEL_EDITION_PROTOCOL_FILE = 'dist/edition-protocol/edition-protocol.json';
+export const KERNEL_EDITION_CONTRACT_FILE = 'dist/edition-protocol/edition-contract.schema.json';
+
+/** This package's vendored copy of a supported contract, package-relative. */
+export const vendoredEditionContractFile = (version) =>
+  `edition/vendored/edition-contract-v${version}.schema.json`;
+
+const MAX_IDENTITY_BYTES = 4 * 1024;
+const MAX_CONTRACT_BYTES = 8 * 1024 * 1024;
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+
+/** Why a kernel's edition protocol was refused. A closed set. */
+export const EditionProtocolMismatchReason = Object.freeze({
+  /** The kernel publishes no edition protocol identity. */
+  Undeclared: 'undeclared',
+  /** The identity file is not exactly `{contentDigest, version}`. */
+  Malformed: 'malformed',
+  /** This library supports no protocol of that version. */
+  UnsupportedVersion: 'unsupported-version',
+  /** The version is supported, but pinned to a different digest. */
+  DigestMismatch: 'digest-mismatch',
+  /** The kernel's contract file does not state its own identity. */
+  ContractMismatch: 'contract-mismatch',
+  /** The kernel's protocol is not the one compiled into the running verifier. */
+  BundleMismatch: 'bundle-mismatch',
+});
+
+export class EditionProtocolMismatchError extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.name = 'EditionProtocolMismatchError';
+    this.reason = reason;
+  }
+}
+
+const describe = ({ version, contentDigest }) => `edition protocol v${version} (${contentDigest})`;
+
+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. */
+export function parseEditionProtocolIdentity(bytes, label) {
+  let identity;
+  try {
+    identity = JSON.parse(bytes.toString('utf8'));
+  } catch (error) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.Malformed,
+      `${label} is not JSON: ${error.message}`,
+    );
+  }
+  if (
+    identity === null ||
+    typeof identity !== 'object' ||
+    Array.isArray(identity) ||
+    Object.keys(identity).sort().join() !== 'contentDigest,version' ||
+    !Number.isSafeInteger(identity.version) ||
+    identity.version < 1 ||
+    typeof identity.contentDigest !== 'string' ||
+    !SHA256_HEX.test(identity.contentDigest)
+  ) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.Malformed,
+      `${label} must be exactly {"contentDigest":"<64 lowercase hex>","version":<positive integer>}`,
+    );
+  }
+  return Object.freeze({ contentDigest: identity.contentDigest, version: identity.version });
+}
+
+/** The `{version, contentDigest}` a contract file states, or undefined. */
+function contractIdentity(contractBytes) {
+  let contract;
+  try {
+    contract = JSON.parse(contractBytes.toString('utf8'));
+  } catch {
+    return undefined;
+  }
+  if (
+    contract === null ||
+    typeof contract !== 'object' ||
+    !Number.isSafeInteger(contract.version) ||
+    typeof contract.contentDigest !== 'string'
+  ) {
+    return undefined;
+  }
+  return { version: contract.version, contentDigest: contract.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 }) {
+  const supported = SUPPORTED_EDITION_PROTOCOLS.find(
+    (protocol) => protocol.version === identity.version,
+  );
+  if (supported === undefined) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.UnsupportedVersion,
+      `${source} declares ${describe(identity)}; this CLI supports ${supportedList()}. ` +
+        'Use a CLI release that supports it, or pin a kernel that speaks a supported protocol.',
+    );
+  }
+  if (supported.contentDigest !== identity.contentDigest) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.DigestMismatch,
+      `${source} declares ${describe(identity)}; this CLI pins v${supported.version} to ` +
+        `${supported.contentDigest} (this CLI supports ${supportedList()}). The kernel changed the edition ` +
+        'contract without a new protocol version.',
+    );
+  }
+  const stated = contractIdentity(contractBytes);
+  if (stated?.version !== identity.version || stated?.contentDigest !== identity.contentDigest) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.ContractMismatch,
+      `${source} declares ${describe(identity)}, but its edition contract file states ` +
+        `${stated === undefined ? 'no identity' : describe(stated)}`,
+    );
+  }
+  return identity;
+}
+
+/**
+ * Read and check the edition protocol of the built kernel package at
+ * `kernelPackageDir`. Reads two files, no-follow and bounded; executes nothing.
+ */
+export function readKernelEditionProtocol(kernelPackageDir) {
+  const source = `the kernel at ${kernelPackageDir}`;
+  let identityBytes;
+  try {
+    ({ bytes: identityBytes } = readBoundedNoFollowFile(
+      kernelPackageDir,
+      KERNEL_EDITION_PROTOCOL_FILE,
+      `${source}: ${KERNEL_EDITION_PROTOCOL_FILE}`,
+      MAX_IDENTITY_BYTES,
+    ));
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {throw error;}
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.Undeclared,
+      `${source} publishes no edition protocol (${KERNEL_EDITION_PROTOCOL_FILE} is absent); ` +
+        `this CLI supports ${supportedList()}. Pin a kernel that publishes its edition protocol identity.`,
+    );
+  }
+  const identity = parseEditionProtocolIdentity(
+    identityBytes,
+    `${source}: ${KERNEL_EDITION_PROTOCOL_FILE}`,
+  );
+  const { bytes: contractBytes } = readBoundedNoFollowFile(
+    kernelPackageDir,
+    KERNEL_EDITION_CONTRACT_FILE,
+    `${source}: ${KERNEL_EDITION_CONTRACT_FILE}`,
+    MAX_CONTRACT_BYTES,
+  );
+  return assertSupportedEditionProtocol({ identity, contractBytes, source });
+}
+
+const checkedKernels = new Map();
+
+/**
+ * {@link readKernelEditionProtocol}, once per kernel directory. Every loader
+ * that executes kernel code calls it first, so no code path interprets a
+ * kernel whose protocol this library does not support.
+ */
+export function assertKernelEditionProtocol(kernelPackageDir) {
+  const key = realpathSync(kernelPackageDir);
+  let identity = checkedKernels.get(key);
+  if (identity === undefined) {
+    identity = readKernelEditionProtocol(key);
+    checkedKernels.set(key, identity);
+  }
+  return identity;
+}
+
+/**
+ * The running verifier interprets evidence with the contracts compiled into
+ * it, so the kernel the workspace states must speak exactly that protocol.
+ */
+export function assertKernelSpeaksBundledProtocol({ kernelPackageDir, bundled }) {
+  const stated = readKernelEditionProtocol(kernelPackageDir);
+  if (stated.version !== bundled.version || stated.contentDigest !== bundled.contentDigest) {
+    throw new EditionProtocolMismatchError(
+      EditionProtocolMismatchReason.BundleMismatch,
+      `the kernel at ${kernelPackageDir} declares ${describe(stated)}, but this verifier was built ` +
+        `with ${describe(bundled)}`,
+    );
+  }
+  return stated;
+}