@xemahq/xema 0.44.1 → 0.45.1

package/dist/runtime/infra/infra-catalog.js

@@ -189,7 +189,7 @@ exports.INFRA_CATALOG = Object.freeze({
 exports.INFRA_COMPONENTS = Object.freeze(Object.values(schema_1.InfraComponent));
 exports.OBJECT_STORE_BUCKETS = Object.freeze([
     'session-session-attachments',
-    'session-opencode-sessions',
+    'session-session-snapshots',
     'kb-knowledge-base-pages',
     'plugin-bundles',
     'artifact-store',

package/edition/README.md

@@ -142,7 +142,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 v14, each pinned to its digest and vendored (v10 to v14 grow the kernel source closure only; a data root whose pinned kernel speaks v8 stays on CLI 0.41.x, v5 on 0.33.x) and REFUSES an identity with `provisional: true`; every loader that executes the kernel, `xema edition check` first, and the evidence verifier compare only that identity and refuse an unsupported one, naming the supported and the declared versions. A protocol change needs a CLI release first; only then does the data root repin its kernel authority.
+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 v20 (the versions the kernel declared and contracts published), each pinned to its digest and vendored (v10 to v20 grow the kernel source closure only; a data root whose pinned kernel speaks v8 stays on CLI 0.41.x, v5 on 0.33.x) and REFUSES an identity with `provisional: true`; every loader that executes the kernel, `xema edition check` first, and the evidence verifier compare only that identity and refuse an unsupported one, naming the supported and the declared versions. A protocol change needs a CLI release first; only then does the data root repin its kernel authority.
 
 A develop edition does not take the kernel's develop head blindly: `xema edition develop choose-kernel --kernel <package dir> [--kernel-pin <40-hex>] --out <file>` reads the declared protocol of each commit on the checkout's first-parent history (from source, unbuilt) and chooses the newest one this CLI supports. It writes `{chosenSha, headSha, held, reason}` (`reason`: `head-supported` | `head-ahead` | `explicit-pin`; `held` is `head-ahead`), and when held prints `kernel held at v<N> (<sha12>), head at v<M> (<sha12>): raise the CLI` (stdout only, never persisted). The head is the checkout's `refs/remotes/origin/develop` (a full-history checkout). An explicit pin wins but is still checked, and must be on that head's first-parent history (`not-on-develop` otherwise); when no commit is supported it refuses (`EditionProtocolMismatchError`, `no-supported-commit`; the walk ends at the first commit with no declaration file) and never falls back to the head; a declaration that exists but does not parse, at the head or any walked commit, is refused by name (`unparseable`), never skipped. `freeze-graph` applies the same check to `--kernel-sha`.
 

package/edition/develop-coverage-readers.mjs

@@ -12,7 +12,7 @@ import { promisify } from 'node:util';
 
 import { AttestationStatus, DEVELOP_EVIDENCE_CHANNEL } from './develop-coverage-verdict.mjs';
 import { COSIGN_ENV, policyCandidates, sha256Digest, validatePinnedTrustedRoot, verifySigstoreEvidenceDescriptor } from './image-evidence.mjs';
-import { resolveImageSourceEvidenceReferrer } from './oci-image-source-evidence.mjs';
+import { resolveImageSourceEvidenceReferrer, writeForeignAuthorityReferrerReport } from './oci-image-source-evidence.mjs';
 import { BUNDLE_MEDIA_TYPE } from './produce-image-source-evidence.mjs';
 import { loadRegistryCredentialDeclarations, resolveRegistryCredential, splitImageRef } from './registry-credentials.mjs';
 import { isNotPublishedYet } from './seal-image-digests.mjs';
@@ -81,13 +81,14 @@ function basicAuthParts(credential) {
  * @param {string} request.policyRoot the directory the policy's trusted root is read from (the data root)
  * @param {object} request.trustedCosign the digest-pinned cosign handle (prepareTrustedCosignBinary)
  * @param {object} request.schemas kernel distribution schemas
+ * @param {object} request.expectedContractAuthority the kernel contract authority the data root pins
  * @param {string} request.dataRoot declares how each registry is read
  * @param {object} request.env environment the registry credentials are named in
  * @param {Function} [request.runCosign] (path, args, env) => { code, stdout, stderr }; replaced by tests
  * @param {Function} [request.fetchImpl] @param {Function} [request.run] oras runner, replaced by tests
  * @param {Function} [request.clientFor] (authority) => registry client, replaced by tests
  */
-export function createCoverageReaders({ policy, policyRoot, trustedCosign, schemas, dataRoot, env, runCosign = defaultRunCosign, fetchImpl, run, clientFor: injectedClientFor }) {
+export function createCoverageReaders({ policy, policyRoot, trustedCosign, schemas, expectedContractAuthority, dataRoot, env, runCosign = defaultRunCosign, fetchImpl, run, clientFor: injectedClientFor }) {
   const cosignPath = assertPreparedExecutable(trustedCosign, 'cosign');
   const declarations = injectedClientFor === undefined ? loadRegistryCredentialDeclarations(dataRoot) : null;
   const scratch = mkdtempSync(join(tmpdir(), 'xema-coverage-'));
@@ -141,6 +142,8 @@ export function createCoverageReaders({ policy, policyRoot, trustedCosign, schem
       imageRepository: subject.imageRef,
       subjectDigest: digest,
       schemas,
+      expectedContractAuthority,
+      onForeignAuthorityReferrer: writeForeignAuthorityReferrerReport,
     });
     if (evidence === null) {return { status: AttestationStatus.None };}
     if (rows.length === 0) {return { status: AttestationStatus.NoRow };}

package/edition/develop-coverage-run.mjs

@@ -8,6 +8,7 @@ import { collectCoverage, coverageExitCode, renderCoverageTable } from './develo
 import { DEVELOP_EDITION_STEPS, resolveDevelopSnapshot } from './develop-edition-resolve.mjs';
 import { loadDeclaredPinnedPolicy } from './evidence-trust-policy.mjs';
 import { prepareTrustedCosignBinary } from './image-evidence.mjs';
+import { readPinnedContractAuthority } from './produce-image-source-evidence.mjs';
 
 const stderrProgress = (line) => process.stderr.write(`${line}\n`);
 
@@ -34,7 +35,7 @@ export async function runDevelopCoverage({
     const { schemas, inputs, lock } = await resolveDevelopSnapshot({ id, pins, steps, phase: (name) => progress(`[coverage] ${name}`) });
     const { imageLock } = await steps.resolveImages(id, { inputs, lock });
     progress(`[coverage] image content hashes computed (${imageLock.subjects.length} subjects)`);
-    const readers = createCoverageReaders({ policy, policyRoot: dataRoot, trustedCosign, schemas, dataRoot, env, ...readerOptions });
+    const readers = createCoverageReaders({ policy, policyRoot: dataRoot, trustedCosign, schemas, expectedContractAuthority: readPinnedContractAuthority({ dataRoot, schemas }), dataRoot, env, ...readerOptions });
     try {
       const report = await collectCoverage({ distributionId: id, subjects: imageLock.subjects, policy, readers, progress });
       write(json ? `${JSON.stringify(report, null, 2)}\n` : renderCoverageTable(report));

package/edition/distribution-evidence-set.mjs

@@ -62,6 +62,7 @@ import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 import {
   createRegistryClientResolver,
   resolveImageSourceEvidenceReferrer,
+  writeForeignAuthorityReferrerReport,
 } from './oci-image-source-evidence.mjs';
 import { BUNDLE_MEDIA_TYPE, canonicalSignedBundleBytes, cosignVerifyAttestationArgs, validateProducedBundle } from './produce-image-source-evidence.mjs';
 import { splitImageRef } from './registry-credentials.mjs';
@@ -499,6 +500,8 @@ export async function resolveProducerEvidence({
       imageRepository: subject.imageRef,
       subjectDigest: image.digest,
       schemas,
+      expectedContractAuthority,
+      onForeignAuthorityReferrer: writeForeignAuthorityReferrerReport,
     });
     if (ociEvidence === null) {
       throw new Error(

package/edition/edition-protocol.mjs

@@ -28,7 +28,7 @@ import { realpathSync } from 'node:fs';
 
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 
-/** The edition protocols this library interprets: version -> content digest. v10..v14 grow the kernel
+/** The edition protocols this library interprets: version -> content digest. v10..v20 grow the kernel
  * source closure only (entry subpaths and hashing unchanged), so one library speaks every row. */
 export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   Object.freeze({ version: 9, contentDigest: '7cd6d760e7e7caaec3634a08c739debbdeeeaac4f1bad6791246a12f4f248e37' }),
@@ -37,6 +37,10 @@ export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   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' }),
 ]);
 
 /** Where a kernel package publishes its identity and its contract, package-relative. */

package/edition/oci-evidence-verbs.mjs

@@ -39,6 +39,7 @@ import {
   createRegistryClientResolver,
   resolveImageSourceEvidenceReferrer,
   validateMaterializedImageSourceEvidence,
+  writeForeignAuthorityReferrerReport,
 } from './oci-image-source-evidence.mjs';
 import { REFERRERS_DISTRIBUTION_SPEC } from './oras.mjs';
 import { assertProducerInput, buildImageSourceStatements, cosignVerifyAttestationArgs, createCosignVerifier, readPinnedContractAuthority } from './produce-image-source-evidence.mjs';
@@ -216,6 +217,7 @@ export async function planOciEvidenceBackfill({
   editionsRoot: editions,
   producerRepositoryRoots,
   schemas,
+  expectedContractAuthority,
   registryClientFactory,
 }) {
   const gitIndex = indexCommittedProducerEvidence({
@@ -281,6 +283,8 @@ export async function planOciEvidenceBackfill({
       imageRepository: item.imageRepository,
       subjectDigest: item.subjectDigest,
       schemas,
+      expectedContractAuthority,
+      onForeignAuthorityReferrer: writeForeignAuthorityReferrerReport,
     });
     const reported = {
       subjectKind: item.subject.kind,
@@ -367,12 +371,14 @@ async function main() {
       WorkspaceRoot.Kernel,
     ]);
     const flags = parseEvidenceCliFlags(rest, { repeated: ['distribution', 'producer-repository-root'] });
+    const schemas = await loadKernelDistributionSchemas();
     const plan = await planOciEvidenceBackfill({
       distributionIds: flags.requireMany('distribution'),
       dataRoot: dataRoot(),
       editionsRoot: editionsRoot(),
       producerRepositoryRoots: flags.requireMany('producer-repository-root').map((root) => resolve(root)),
-      schemas: await loadKernelDistributionSchemas(),
+      schemas,
+      expectedContractAuthority: readPinnedContractAuthority({ dataRoot: dataRoot(), schemas }),
     });
     process.stdout.write(serializeJson(plan));
     // 2: something is still to be produced or attached.

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

@@ -13,6 +13,7 @@ import {
   PRODUCER_STATEMENT_MEDIA_TYPE,
   producerEvidenceLayerFiles,
   readProducerEvidenceDirectory,
+  readRawStatementAuthorityCommits,
 } from './producer-evidence-bundle.mjs';
 import {
   loadRegistryCredentialDeclarations,
@@ -156,9 +157,39 @@ export function validateMaterializedImageSourceEvidence({
   return { ...evidence, created };
 }
 
+function assertExpectedAuthorityCommit(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error('the expected kernel contract authority commit is required');
+  }
+}
+
+/** The artifact states a kernel contract authority other than the one evidence is read under. */
+export class ForeignAuthorityReferrerError extends Error {
+  constructor({ artifactDigest, sourceCommit }) {
+    super(
+      `evidence referrer ${artifactDigest} is stated under kernel contract authority ${sourceCommit}`,
+    );
+    this.name = 'ForeignAuthorityReferrerError';
+    this.artifactDigest = artifactDigest;
+    this.sourceCommit = sourceCommit;
+  }
+}
+
+/** The one stderr line that names a skipped foreign-authority referrer. */
+export function writeForeignAuthorityReferrerReport(skipped) {
+  process.stderr.write(
+    `[evidence] skipped ${skipped.imageRepository}@${skipped.subjectDigest} referrer ${skipped.artifactDigest}: ` +
+      `stated under kernel contract authority ${skipped.sourceCommit}, ` +
+      `not ${skipped.expectedAuthorityCommit}\n`,
+  );
+}
+
 /**
  * Fetch, content-address validate and decode one OCI evidence artifact.
  * `getBlob` verifies every digest again, independently of the manifest.
+ * An artifact whose RAW statements state another authority commit than
+ * `expectedAuthorityCommit` is refused with `ForeignAuthorityReferrerError`
+ * before the strict parse, which is bound to the expected authority.
  */
 export async function readImageSourceEvidenceArtifact({
   client,
@@ -166,7 +197,9 @@ export async function readImageSourceEvidenceArtifact({
   subjectDigest,
   artifactDigest,
   schemas,
+  expectedAuthorityCommit,
 }) {
+  assertExpectedAuthorityCommit(expectedAuthorityCommit);
   const fetched = await client.getManifestByDigest(repository, artifactDigest);
   const { created, layers } = validateImageSourceEvidenceManifest({
     manifest: fetched.document,
@@ -184,6 +217,11 @@ export async function readImageSourceEvidenceArtifact({
       mkdirSync(dirname(path), { recursive: true });
       writeFileSync(path, bytes, { flag: 'wx', mode: 0o600 });
     }
+    for (const sourceCommit of readRawStatementAuthorityCommits({ directory })) {
+      if (sourceCommit !== expectedAuthorityCommit) {
+        throw new ForeignAuthorityReferrerError({ artifactDigest, sourceCommit });
+      }
+    }
     const evidence = validateMaterializedImageSourceEvidence({
       directory,
       manifest: fetched.document,
@@ -196,13 +234,25 @@ export async function readImageSourceEvidenceArtifact({
   }
 }
 
-/** Resolve the newest valid evidence referrer deterministically. */
+/**
+ * Resolve the newest valid evidence referrer deterministically. A referrer
+ * stated under a different kernel contract authority is not evidence under
+ * `expectedContractAuthority`: it is reported to `onForeignAuthorityReferrer`
+ * and skipped. Every other defect of a referrer still throws.
+ */
 export async function resolveImageSourceEvidenceReferrer({
   client,
   imageRepository,
   subjectDigest,
   schemas,
+  expectedContractAuthority,
+  onForeignAuthorityReferrer,
 }) {
+  const expectedAuthorityCommit = expectedContractAuthority?.sourceCommit;
+  assertExpectedAuthorityCommit(expectedAuthorityCommit);
+  if (typeof onForeignAuthorityReferrer !== 'function') {
+    throw new Error('a foreign-authority referrer report handler is required');
+  }
   const { authority, repository } = splitImageRef(imageRepository);
   if (client.authority !== authority) {
     throw new Error(
@@ -224,16 +274,29 @@ export async function resolveImageSourceEvidenceReferrer({
     if (!SHA256_DIGEST_PATTERN.test(descriptor.digest ?? '')) {
       throw new Error('registry returned a non-canonical evidence referrer digest');
     }
-    candidates.push(
-      await readImageSourceEvidenceArtifact({
-        client,
-        repository,
+    try {
+      candidates.push(
+        await readImageSourceEvidenceArtifact({
+          client,
+          repository,
+          subjectDigest,
+          artifactDigest: descriptor.digest,
+          schemas,
+          expectedAuthorityCommit,
+        }),
+      );
+    } catch (error) {
+      if (!(error instanceof ForeignAuthorityReferrerError)) {throw error;}
+      onForeignAuthorityReferrer({
+        imageRepository,
         subjectDigest,
-        artifactDigest: descriptor.digest,
-        schemas,
-      }),
-    );
+        artifactDigest: error.artifactDigest,
+        sourceCommit: error.sourceCommit,
+        expectedAuthorityCommit,
+      });
+    }
   }
+  if (candidates.length === 0) {return null;}
   candidates.sort((left, right) => {
     const byCreated = compareStrings(right.created, left.created);
     return byCreated || compareStrings(left.artifactDigest, right.artifactDigest);

package/edition/plan-image-evidence-refresh.mjs

@@ -73,6 +73,7 @@ import { compareStrings, loadKernelDistributionSchemas } from './lib.mjs';
 import {
   createRegistryClientResolver,
   resolveImageSourceEvidenceReferrer,
+  writeForeignAuthorityReferrerReport,
 } from './oci-image-source-evidence.mjs';
 import {
   loadProducerKernelSchemas,
@@ -193,6 +194,8 @@ export async function planImageEvidenceRefresh({
             imageRepository: subject.imageRef,
             subjectDigest: image.digest,
             schemas,
+            expectedContractAuthority,
+            onForeignAuthorityReferrer: writeForeignAuthorityReferrerReport,
           });
           if (artifact !== null) {
             matches = artifact.records.filter(

package/edition/producer-evidence-bundle.mjs

@@ -62,6 +62,37 @@ export function producerStatementMatchesInput(statement, expectedStatement) {
   );
 }
 
+/**
+ * The RAW `predicate.contractAuthority.sourceCommit` of every statement a
+ * producer evidence directory carries, read BEFORE any schema parse: the parse
+ * is bound to one kernel authority, so deciding whose authority a statement
+ * speaks under cannot go through it. A statement that states no string commit
+ * contributes nothing here; the strict parse refuses it later.
+ */
+export function readRawStatementAuthorityCommits({ directory }) {
+  const index = JSON.parse(
+    decodeExactUtf8(
+      readBounded(directory, PRODUCER_EVIDENCE_INDEX_FILE, 'producer evidence index'),
+      'producer evidence index',
+    ),
+  );
+  if (!Array.isArray(index?.producerEvidence)) {
+    throw new Error('producer evidence index is not non-empty schemaVersion 1');
+  }
+  const commits = new Set();
+  for (const entry of index.producerEvidence) {
+    const statement = JSON.parse(
+      decodeExactUtf8(
+        readBounded(directory, entry?.evidence?.statementPath, 'producer statement'),
+        'producer statement',
+      ),
+    );
+    const commit = statement?.predicate?.contractAuthority?.sourceCommit;
+    if (typeof commit === 'string') {commits.add(commit);}
+  }
+  return commits;
+}
+
 /** Read and structurally validate one producer evidence directory. */
 export function readProducerEvidenceDirectory({ directory, schemas }) {
   if (!isAbsolute(directory)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.44.1",
+  "version": "0.45.1",
   "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.94.0",
+    "@xemahq/contracts": "^0.102.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:68b1703a9457c36f912b5d8e3793d727b2e90e84034007bdadb6bbacbedd04e3"
+    "sourceDigest": "sha256:04abcd3c081c6cd50d0133c543310f75801357071b18834ec4b15af587760461"
   }
 }