@xemahq/xema 0.47.0 → 0.48.0

package/edition/README.md

@@ -143,7 +143,7 @@ The edition library builds, validates and verifies evidence statements; it never
 
 ## Kernel protocol and pins
 
-The CLI is coupled to the kernel's edition protocol, not to the kernel package. `@xemahq/contracts` exports the protocol identity as data (`dist/edition-protocol/edition-protocol.json`: `{contentDigest, provisional, version}`). This CLI supports protocols v9 to v16 and v19 to v26 (the versions the kernel declared and contracts published), each pinned to its digest and vendored (v10 to v26 grow the kernel source closure only; a data root whose pinned kernel speaks v8 stays on CLI 0.41.x, v5 on 0.33.x) and REFUSES an identity with `provisional: true`; every loader that executes the kernel, `xema edition check` first, and the evidence verifier compare only that identity and refuse an unsupported one, naming the supported and the declared versions. A protocol change needs a CLI release first; only then does the data root repin its kernel authority.
+The CLI is coupled to the kernel's edition protocol, not to the kernel package. `@xemahq/contracts` exports the protocol identity as data (`dist/edition-protocol/edition-protocol.json`: `{contentDigest, provisional, version}`). This CLI supports protocols v28, v30 and v31 (no published kernel declares v29; a CLI lists a protocol only while every kernel published under it exports what the CLI imports; v27 and older kernels lack `serviceImageSubjects`, so a data root whose pinned kernel speaks v27 or older stays on an earlier CLI), pinned to its digest and vendored, and REFUSES an identity with `provisional: true`; every loader that executes the kernel, `xema edition check` first, and the evidence verifier compare only that identity and refuse an unsupported one, naming the supported and the declared versions. A protocol change needs a CLI release first; only then does the data root repin its kernel authority.
 
 A develop edition does not take the kernel's develop head blindly: `xema edition develop choose-kernel --kernel <package dir> [--kernel-pin <40-hex>] --out <file>` reads the declared protocol of each commit on the checkout's first-parent history (from source, unbuilt) and chooses the newest one this CLI supports. It writes `{chosenSha, headSha, held, reason}` (`reason`: `head-supported` | `head-ahead` | `explicit-pin`; `held` is `head-ahead`), and when held prints `kernel held at v<N> (<sha12>), head at v<M> (<sha12>): raise the CLI` (stdout only, never persisted). The head is the checkout's `refs/remotes/origin/develop` (a full-history checkout). An explicit pin wins but is still checked, and must be on that head's first-parent history (`not-on-develop` otherwise); when no commit is supported it refuses (`EditionProtocolMismatchError`, `no-supported-commit`; the walk ends at the first commit with no declaration file) and never falls back to the head; a declaration that exists but does not parse, at the head or any walked commit, is refused by name (`unparseable`), never skipped. `freeze-graph` applies the same check to `--kernel-sha`.
 

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

@@ -758,8 +758,11 @@ export const REPIN_CONTRACT_AUTHORITY_FOLLOW_UPS = Object.freeze([
  * states (`kernelCommit`, required; HEAD must equal it), and write it back.
  *
  * The document is read as raw strict JSON and the field replaced BEFORE it is
- * parsed: the kernel's schema refuses an index whose authority `sourcePaths`
- * differ from the bundled constant, so a stale index cannot be parsed first.
+ * parsed, so a stale index cannot block its own repair (the wire schema
+ * checks the shape of `sourcePaths` only, from contracts 0.110.3).
+ * The new authority's `sourcePaths` are the set the stated commit declares,
+ * and `buildTrustedKernelContractAuthority` requires this CLI's bundled set to
+ * equal it: a repin is trusted generation at HEAD.
  * Every repository pin and subject is kept byte for byte. Repository coverage
  * is not asserted: this repin produces no pin, and requiring coverage would
  * make a stale index unrepairable.

package/edition/edition-protocol.mjs

@@ -28,27 +28,14 @@ import { realpathSync } from 'node:fs';
 
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 
-/** The edition protocols this library interprets: version -> content digest. v10..v28 grow the kernel
- * source closure only (entry subpaths and hashing unchanged), so one library speaks every row. */
+/** The edition protocols this library interprets: version -> content digest. A protocol is listed only
+ * while every kernel published under it exports what this library imports (`kernel-export-coverage.test.mjs`):
+ * v27 and older kernels lack `serviceImageSubjects` (first exported by the v28 kernel), so they are not listed.
+ * No published kernel declares v29 (0.110.2 is v28, 0.110.3 is v30, 0.111.0 is v31), so v29 is not listed either. */
 export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
-  Object.freeze({ version: 9, contentDigest: '7cd6d760e7e7caaec3634a08c739debbdeeeaac4f1bad6791246a12f4f248e37' }),
-  Object.freeze({ version: 10, contentDigest: '660129065650a8300f7c0ad54f957b4d43507e1a44e093c9812d2b1bbf143104' }),
-  Object.freeze({ version: 11, contentDigest: '600451d2253c470c7d21bafe87260dfc3bfd43b6ad3eee2ef4d8b1f7ad08eb6e' }),
-  Object.freeze({ version: 12, contentDigest: 'cff51ea06b6ba7d95d02dcd6305b6a55061b428da48ae74dcbff8a5c8107ce41' }),
-  Object.freeze({ version: 13, contentDigest: '5f69fe73d1dea1650ef1757204a53ccd4030ade78bfa91959c2d01c937fc0e16' }),
-  Object.freeze({ version: 14, contentDigest: '403b6a491b5922df1a423ba8a2d6ae3d3900bb1caff4e8c0caa48de90a47eb9b' }),
-  Object.freeze({ version: 15, contentDigest: 'c66191703abfd9b532d8b6c15476bede2a5752af5bea5032e839fb9d6303a2d1' }),
-  Object.freeze({ version: 16, contentDigest: '2e65c280a399304ebb438e4e9829bcb4688f36a3c6a5e8b35b679cf69c689f55' }),
-  Object.freeze({ version: 19, contentDigest: '66dab3dcf18c3a587f073808cc91165cc513eabb237b35439ff6cfe2b312b127' }),
-  Object.freeze({ version: 20, contentDigest: '22c0e4ba6ee2771e91516ea78806117b5e3e60b76e085b9a9b98e993c1de79f8' }),
-  Object.freeze({ version: 21, contentDigest: 'f6364cf4830dcd15f82fb316ec9c0f0c11ffbe45262d97d8621242117d02f2b8' }),
-  Object.freeze({ version: 22, contentDigest: '566a0c37ee8b25c22bb9a5979190508e479c87593790b4a9e481ab1db8f7bcd1' }),
-  Object.freeze({ version: 23, contentDigest: '96735bd71236b4d0a2cef8a59c4a8d4f6919c6b5e54654c4b2b01e22b9880e04' }),
-  Object.freeze({ version: 24, contentDigest: '6ae70f55db789f95e194f623525b30ffedc21478ec17d246336b9a2783b6c0db' }),
-  Object.freeze({ version: 25, contentDigest: '79916e652836c7f6c31a7284c083c4f11249c6f21ef0b1bf79efc9dc23684d4a' }),
-  Object.freeze({ version: 26, contentDigest: '8d1dcfca5c59ff7b5eee6ea84fec3d9d62a48f3260f4ddb27b6665c25056f968' }),
-  Object.freeze({ version: 27, contentDigest: 'd4807f6464508c1abb32f7de9754f2e1f12cd7f2be5fbf939b6a5175c01dd90b' }),
   Object.freeze({ version: 28, contentDigest: 'f7795478b1bfe9a41bcbea9efe496011fcd209a56c90294029a08801e84cf92c' }),
+  Object.freeze({ version: 30, contentDigest: '91e3cdff255778b5aa94b64ca9316d031be549ead2267a9a9311ff06d4f1db2c' }),
+  Object.freeze({ version: 31, contentDigest: 'b2026847fdd202e7b9e05815cdc2c9819b60be7007c789cc5b5f291c9c682fdd' }),
 ]);
 
 /** Where a kernel package publishes its identity and its contract, package-relative. */

package/edition/kernel-contract-authority.mjs

@@ -4,6 +4,11 @@ import { join } from 'node:path';
 
 import { kernelRepoDir } from './edition-workspace.mjs';
 import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import {
+  assertSourcePathsEqualSet,
+  KERNEL_CONTRACT_SOURCE_PATH_SET_FILE,
+  parseKernelContractSourcePathSet,
+} from './kernel-contract-source-path-set.mjs';
 
 const GIT_ENV = Object.freeze({
   GIT_CONFIG_NOSYSTEM: '1',
@@ -171,6 +176,28 @@ function gitBlobsAtCommit(repositoryDirectory, sourceCommit, paths) {
   return sources;
 }
 
+/**
+ * The source-path set the kernel declares AT `sourceCommit`, read from that
+ * commit's own declaration blob: the same tree the digest is recomputed from,
+ * never the list of the contracts version this CLI bundles.
+ */
+export function sourcePathSetAtCommit(repositoryDirectory, sourceCommit) {
+  const [declaration] = gitBlobsAtCommit(repositoryDirectory, sourceCommit, [
+    KERNEL_CONTRACT_SOURCE_PATH_SET_FILE,
+  ]);
+  return parseKernelContractSourcePathSet(declaration.blob.toString('utf8'), sourceCommit);
+}
+
+/**
+ * Refuses `sourcePaths` unless they equal the source-path set at `sourceCommit`
+ * (KernelContractSourcePathSetMismatchError names the missing and extra paths).
+ * The wire schema checks shape only; this is the check that the set means
+ * something.
+ */
+export function assertSourcePathsMatchCommit(repositoryDirectory, sourceCommit, sourcePaths) {
+  assertSourcePathsEqualSet(sourcePaths, sourcePathSetAtCommit(repositoryDirectory, sourceCommit), sourceCommit);
+}
+
 function exactAuthorityJson(value) {
   return JSON.stringify(value);
 }
@@ -194,11 +221,12 @@ export async function readKernelContractAuthorityAtCommit({
   }
   exactOrigin(repositoryDirectory, schemas);
   assertCommitExists(repositoryDirectory, sourceCommit);
-  const sources = gitBlobsAtCommit(
-    repositoryDirectory,
-    sourceCommit,
-    schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS,
-  );
+  // The set is the commit's own (XEMA-2010): an authority at a commit whose
+  // contracts declare 446 paths is read, digested and stamped over those 446,
+  // whatever this CLI bundles. The digest's validateSources checks shape only
+  // (contracts 0.110.3 and later).
+  const sourcePaths = sourcePathSetAtCommit(repositoryDirectory, sourceCommit);
+  const sources = gitBlobsAtCommit(repositoryDirectory, sourceCommit, sourcePaths);
   const contentDigest =
     await schemas.computeKernelContractAuthorityContentDigest(sources);
   return {
@@ -206,7 +234,7 @@ export async function readKernelContractAuthorityAtCommit({
     generatorIdentity: schemas.XEMA_KERNEL_CONTRACT_AUTHORITY_GENERATOR,
     repositoryUrl: schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL,
     sourceCommit,
-    sourcePaths: [...schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS],
+    sourcePaths,
     contentHashAlgorithm:
       schemas.KernelContractContentHashAlgorithm.LengthFramedGitPathModeBlobV1,
     contentDigest,
@@ -254,14 +282,11 @@ export function assertExactCleanKernelContractCheckout({
     const path = record.slice(record.indexOf('\t') + 1);
     indexByPath.set(path, [...(indexByPath.get(path) ?? []), record]);
   }
+  const sourcePaths = sourcePathSetAtCommit(repositoryDirectory, sourceCommit);
   const committed = new Map(
-    gitBlobsAtCommit(
-      repositoryDirectory,
-      sourceCommit,
-      schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS,
-    ).map((source) => [source.path, source]),
+    gitBlobsAtCommit(repositoryDirectory, sourceCommit, sourcePaths).map((source) => [source.path, source]),
   );
-  for (const path of schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS) {
+  for (const path of sourcePaths) {
     const indexRecords = indexByPath.get(path) ?? [];
     const indexMatch =
       indexRecords.length === 1
@@ -323,6 +348,16 @@ export async function buildTrustedKernelContractAuthority({
     sourceCommit,
     schemas,
   });
+  // Trusted generation at HEAD ONLY: a NEW pin is minted by a CLI whose bundled
+  // contracts declare exactly the set at that commit, so the CLI that writes
+  // the pin understands every source it binds. Reading or validating an
+  // existing pin never makes this comparison.
+  assertSourcePathsEqualSet(
+    schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS,
+    sourcePathSetAtCommit(repositoryDirectory, sourceCommit),
+    sourceCommit,
+    "this CLI's bundled kernel contract source paths",
+  );
   const authority = await readKernelContractAuthorityAtCommit({
     repositoryDirectory,
     sourceCommit,
@@ -401,12 +436,19 @@ async function assessAuthorityLineage({ authority, repositoryDirectory, schemas
     return { head, changedPaths: [] };
   }
 
-  const changedPaths = [];
-  const pinned = gitBlobRecordsAtCommit(repositoryDirectory, authority.sourceCommit, authority.sourcePaths);
-  const current = gitBlobRecordsAtCommit(repositoryDirectory, head, authority.sourcePaths);
-  for (const [index, path] of authority.sourcePaths.entries()) {
-    if (pinned[index].objectId !== current[index].objectId) {changedPaths.push(path);}
-  }
+  // The two commits may declare different sets: a path added or dropped since
+  // the pin has moved as surely as one whose blob changed.
+  const pinnedTree = gitTreeAtCommit(repositoryDirectory, authority.sourceCommit);
+  const currentTree = gitTreeAtCommit(repositoryDirectory, head);
+  const pinnedSet = new Set(authority.sourcePaths);
+  const currentSet = new Set(atHead.sourcePaths);
+  const changedPaths = [...new Set([...pinnedSet, ...currentSet])]
+    .sort()
+    .filter(
+      (path) =>
+        pinnedSet.has(path) !== currentSet.has(path) ||
+        pinnedTree.get(path)?.objectId !== currentTree.get(path)?.objectId,
+    );
   return { head, changedPaths };
 }
 
@@ -451,6 +493,8 @@ export async function validateKernelContractAuthorityFromGit({
       schemas,
     });
   }
+  assertCommitExists(repositoryDirectory, authority.sourceCommit);
+  assertSourcePathsMatchCommit(repositoryDirectory, authority.sourceCommit, authority.sourcePaths);
   const expected = await readKernelContractAuthorityAtCommit({
     repositoryDirectory,
     sourceCommit: authority.sourceCommit,

package/edition/kernel-contract-source-path-set.mjs

@@ -0,0 +1,94 @@
+/**
+ * The kernel contract authority's source-path set, as the kernel commit itself
+ * declares it. The set belongs to the commit an authority is pinned at, never
+ * to the contracts package the CLI happens to bundle: a bundled constant is the
+ * set of ONE contracts version, and comparing a pin made under another version
+ * against it is the cross-version defect this check replaces.
+ */
+
+/** The file in the kernel repository that declares the source-path set. */
+export const KERNEL_CONTRACT_SOURCE_PATH_SET_FILE =
+  'packages/kernel/kernel-contracts/src/distribution/lib/kernel-contract-source-paths.ts';
+
+const DECLARATION_START = 'export const XEMA_KERNEL_CONTRACT_SOURCE_PATHS = Object.freeze([';
+const DECLARATION_END = '] as const);';
+const PATH_LINE_PATTERN = /^ {2}'([^'\\\s]+)',$/;
+
+/**
+ * A source-path list is not the source-path set at `sourceCommit`. `subject`
+ * names the list that was compared: a pinned authority's `sourcePaths`, or the
+ * set the CLI's bundled contracts declare (trusted generation only).
+ */
+export class KernelContractSourcePathSetMismatchError extends Error {
+  constructor({ sourceCommit, missing, extra, subject = 'kernel contract authority sourcePaths' }) {
+    super(
+      `${subject} are not the source-path set at ${sourceCommit}: ` +
+        `${missing.length} missing (${missing.join(', ') || 'none'}), ` +
+        `${extra.length} extra (${extra.join(', ') || 'none'})`,
+    );
+    this.name = 'KernelContractSourcePathSetMismatchError';
+    this.sourceCommit = sourceCommit;
+    this.missing = missing;
+    this.extra = extra;
+  }
+}
+
+/**
+ * The ordered path list declared by the text of
+ * {@link KERNEL_CONTRACT_SOURCE_PATH_SET_FILE}. Refuses any other shape, a list
+ * that is empty, not strictly ascending (which also makes it unique), or that
+ * does not name the declaration file itself: the declaration is one of the
+ * digested sources, so the digest commits to the set it was taken over.
+ */
+export function parseKernelContractSourcePathSet(text, sourceCommit) {
+  const lines = text.split('\n');
+  const start = lines.indexOf(DECLARATION_START);
+  const end = lines.indexOf(DECLARATION_END, start + 1);
+  if (start === -1 || end === -1) {
+    throw new Error(
+      `${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} does not declare XEMA_KERNEL_CONTRACT_SOURCE_PATHS in the expected form`,
+    );
+  }
+  const paths = lines.slice(start + 1, end).map((line) => {
+    const match = PATH_LINE_PATTERN.exec(line);
+    if (!match || match[1].split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+      throw new Error(
+        `${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} has a line that is not one quoted relative path: ${JSON.stringify(line)}`,
+      );
+    }
+    return match[1];
+  });
+  if (paths.length === 0) {
+    throw new Error(`${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} declares no source paths`);
+  }
+  for (let index = 1; index < paths.length; index += 1) {
+    if (!(paths[index - 1] < paths[index])) {
+      throw new Error(
+        `${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} is not in strictly ascending order at ${JSON.stringify(paths[index])}`,
+      );
+    }
+  }
+  if (!paths.includes(KERNEL_CONTRACT_SOURCE_PATH_SET_FILE)) {
+    throw new Error(
+      `${KERNEL_CONTRACT_SOURCE_PATH_SET_FILE} at ${sourceCommit} does not declare itself, so the digest would not commit to the set`,
+    );
+  }
+  return paths;
+}
+
+/**
+ * Refuses `sourcePaths` unless it equals `expected`, the set at `sourceCommit`
+ * (same paths, same order); names the paths `sourcePaths` lacks (missing) and
+ * the ones it has beyond the set (extra).
+ */
+export function assertSourcePathsEqualSet(sourcePaths, expected, sourceCommit, subject = undefined) {
+  const have = new Set(sourcePaths);
+  const want = new Set(expected);
+  const missing = expected.filter((path) => !have.has(path));
+  const extra = sourcePaths.filter((path) => !want.has(path));
+  const sameOrder =
+    sourcePaths.length === expected.length && sourcePaths.every((path, index) => path === expected[index]);
+  if (missing.length > 0 || extra.length > 0 || !sameOrder) {
+    throw new KernelContractSourcePathSetMismatchError({ sourceCommit, missing, extra, subject });
+  }
+}

package/edition/oci-image-source-evidence.mjs

@@ -204,7 +204,8 @@ export function writeInvalidReferrerReport(skipped) {
  * `getBlob` verifies every digest again, independently of the manifest.
  * An artifact that is not valid evidence under `expectedAuthorityCommit`
  * (a manifest that is not the exact subject's, RAW statements stating another authority commit, a
- * failed strict parse) is refused with `InvalidEvidenceReferrerError`; a
+ * failed strict parse, a statement whose contract authority is not exactly
+ * `expectedContractAuthority`, which is required) is refused with `InvalidEvidenceReferrerError`; a
  * registry that cannot answer, or bytes that do not match their digests
  * (`EvidenceIntegrityError`, a tampering signal), still throw.
  */
@@ -215,8 +216,12 @@ export async function readImageSourceEvidenceArtifact({
   artifactDigest,
   schemas,
   expectedAuthorityCommit,
+  expectedContractAuthority,
 }) {
   assertExpectedAuthorityCommit(expectedAuthorityCommit);
+  if (!expectedContractAuthority) {
+    throw new Error('the expected kernel contract authority is required');
+  }
   const fetched = await client.getManifestByDigest(repository, artifactDigest);
   const invalid = (error) =>
     new InvalidEvidenceReferrerError({
@@ -264,6 +269,14 @@ export async function readImageSourceEvidenceArtifact({
         subjectDigest,
         schemas,
       });
+      // The wire schema checks the shape of an authority's sourcePaths only
+      // (contracts 0.110.3), so a statement naming the expected commit with
+      // another path set or digest parses: it is not evidence under the pin.
+      for (const record of evidence.records) {
+        if (canonicalJson(record.statement.predicate.contractAuthority) !== canonicalJson(expectedContractAuthority)) {
+          throw new Error(`${record.key} statement's kernel contract authority is not exactly the expected one at ${expectedAuthorityCommit}`);
+        }
+      }
       return { ...evidence, artifactDigest, created };
     } catch (error) {
       if (error instanceof InvalidEvidenceReferrerError || error instanceof EvidenceIntegrityError) {
@@ -327,6 +340,7 @@ export async function resolveImageSourceEvidenceReferrer({
           artifactDigest: descriptor.digest,
           schemas,
           expectedAuthorityCommit,
+          expectedContractAuthority,
         }),
       );
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -54,7 +54,7 @@
     "@xemahq/distribution-source-hash": "^0.2.2",
     "@xemahq/dsl": "^0.24.0",
     "@xemahq/identity-client": "^0.16.0",
-    "@xemahq/contracts": "^0.110.2",
+    "@xemahq/contracts": "^0.111.0",
     "@xemahq/kernel-state-runtime": "^0.8.0",
     "@xemahq/license-verifier": "^0.2.0",
     "@xemahq/service-registry-nest": "^0.12.2",
@@ -92,6 +92,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:7c50b1499876697b28ff4a9c5cc2d1517bc1cfca2a9ccf9c019411b6e3b0edcd"
+    "sourceDigest": "sha256:5f6bd75aa0d1bdc9a141a6f9f31be0957f7a8e5aa967695362db0ced936cac5a"
   }
 }