@xemahq/xema 0.45.1 → 0.46.0

package/edition/distribution-evidence-set.mjs

@@ -61,8 +61,9 @@ import { compareStrings } from './lib.mjs';
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 import {
   createRegistryClientResolver,
+  describeInvalidReferrer,
   resolveImageSourceEvidenceReferrer,
-  writeForeignAuthorityReferrerReport,
+  writeInvalidReferrerReport,
 } 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';
@@ -495,14 +496,25 @@ export async function resolveProducerEvidence({
     const { authority, repository } = splitImageRef(subject.imageRef);
     const client = clientFor(authority);
     const image = await client.getManifestByTag(repository, subject.contentHash);
+    const invalidReferrers = [];
     const ociEvidence = await resolveImageSourceEvidenceReferrer({
       client,
       imageRepository: subject.imageRef,
       subjectDigest: image.digest,
       schemas,
       expectedContractAuthority,
-      onForeignAuthorityReferrer: writeForeignAuthorityReferrerReport,
+      onInvalidReferrer: (skipped) => {
+        invalidReferrers.push(skipped);
+        writeInvalidReferrerReport(skipped);
+      },
     });
+    if (ociEvidence === null && invalidReferrers.length > 0) {
+      throw new Error(
+        `no valid OCI image-source evidence referrer exists for "${subject.kind}:${subject.id}" ` +
+          `at ${subject.imageRef}@${image.digest}: ` +
+          invalidReferrers.map(describeInvalidReferrer).join('; '),
+      );
+    }
     if (ociEvidence === null) {
       throw new Error(
         `no OCI image-source evidence referrer exists for "${subject.kind}:${subject.id}" ` +

package/edition/edition-config.mjs

@@ -7,7 +7,7 @@
 
 import { join } from 'node:path';
 
-import { canonicalPublicHttpsRepositoryUrl } from './canonical-repository-url.mjs';
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
 import { dataRoot } from './edition-workspace.mjs';
 import { isUnderSourcePrefix } from './git-source-auth.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
@@ -49,6 +49,7 @@ const KEYS = Object.freeze([
   'chartRegistry',
   'chartPublishers',
   'sourceRepositoryUrlPrefix',
+  'dataRootRepositoryUrl',
   'sourceAuthUsername',
   'evidenceTrustPolicy',
   ...Object.keys(SECTIONS),
@@ -187,6 +188,30 @@ function assertFirstPartyUrls(firstPartySources, prefix) {
   }
 }
 
+/**
+ * The OPTIONAL `dataRootRepositoryUrl`: where the data root itself lives, in the canonical public HTTPS form
+ * and under `sourceRepositoryUrlPrefix` like a first-party repository. It names the record signer
+ * (the data root's reusable workflows); a data root that does not declare it simply cannot be named as one.
+ */
+function optionalDataRootRepositoryUrl(document, prefix) {
+  if (document.dataRootRepositoryUrl === undefined) {return {};}
+  const where = `${EDITION_WORKSPACE_CONFIG_FILE}: "dataRootRepositoryUrl"`;
+  let canonical;
+  try {
+    canonical = canonicalPublicHttpsRepositoryUrl(document.dataRootRepositoryUrl, where);
+    repositoryOwnerName(canonical, where);
+  } catch (err) {
+    throw new EditionWorkspaceConfigError(err.message);
+  }
+  if (canonical !== document.dataRootRepositoryUrl) {
+    throw new EditionWorkspaceConfigError(`${where} ${JSON.stringify(document.dataRootRepositoryUrl)} is not in its canonical form (${canonical})`);
+  }
+  if (!isUnderSourcePrefix(canonical, prefix)) {
+    throw new EditionWorkspaceConfigError(`${where} ${JSON.stringify(canonical)} is not under sourceRepositoryUrlPrefix ${prefix}`);
+  }
+  return { dataRootRepositoryUrl: canonical };
+}
+
 /** Validate a parsed config document; returns the frozen, typed config. */
 export function parseEditionWorkspaceConfig(document) {
   if (document === null || typeof document !== 'object' || Array.isArray(document)) {
@@ -210,6 +235,7 @@ export function parseEditionWorkspaceConfig(document) {
     imageRegistry: requireString(document, 'imageRegistry', IMAGE_REGISTRY, '<host>/<namespace> with no scheme or trailing slash'),
     ...optionalChartSet(document),
     sourceRepositoryUrlPrefix,
+    ...optionalDataRootRepositoryUrl(document, sourceRepositoryUrlPrefix),
     sourceAuthUsername: requireSourceAuthUsername(document),
     evidenceTrustPolicy: requireEvidenceTrustPolicy(document),
   });

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..v20 grow the kernel
+/** The edition protocols this library interprets: version -> content digest. v10..v27 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' }),
@@ -41,6 +41,13 @@ export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   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' }),
 ]);
 
 /** Where a kernel package publishes its identity and its contract, package-relative. */

package/edition/image-evidence.mjs

@@ -17,6 +17,7 @@ import {
 } from 'node:path';
 import { TextDecoder } from 'node:util';
 
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
 import { assertCanonicalDistributionId } from './distribution-paths.mjs';
 import { effectiveRepositoryPins, manifestSourcePins } from './edition-source-pins.mjs';
 import { SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
@@ -804,21 +805,10 @@ export function verifySigstoreEvidenceDescriptor({
         verifiedTrustedRootPath,
         '--bundle',
         verifiedBundlePath,
-        '--certificate-identity',
-        candidate.certificateIdentity,
-        '--certificate-oidc-issuer',
-        candidate.oidcIssuer,
+        ...certificateConstraintArgs(candidate, verifiedWorkflowSha),
         '--type',
         predicateType,
       ];
-      args.push(
-        '--certificate-github-workflow-repository',
-        candidate.githubWorkflow.repository,
-        '--certificate-github-workflow-ref',
-        candidate.githubWorkflow.ref,
-        '--certificate-github-workflow-sha',
-        verifiedWorkflowSha,
-      );
       execFileSync(trustedCosignPath, args, {
         env: COSIGN_ENV,
         stdio: ['ignore', 'ignore', 'pipe'],

package/edition/kernel-signer-kind.mjs

@@ -0,0 +1,23 @@
+import { createRequire } from 'node:module';
+
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
+import { kernelDistPath, kernelPackageDir } from './edition-workspace.mjs';
+
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * The kind of signer this library produces and verifies: a keyless OIDC
+ * certificate, `SignerKind.OidcCertificate` of the built kernel. The producer
+ * inputs and the trust-policy rows the evidence verbs handle carry it.
+ */
+export function oidcCertificateSignerKind() {
+  assertKernelEditionProtocol(kernelPackageDir());
+  const { SignerKind } = requireFromHere(kernelDistPath('distribution', 'index.js'));
+  const kind = SignerKind?.OidcCertificate;
+  if (typeof kind !== 'string' || kind.length === 0) {
+    throw new Error(
+      `The built kernel distribution module at ${kernelDistPath('distribution', 'index.js')} does not export SignerKind.OidcCertificate; rebuild the kernel checkout.`,
+    );
+  }
+  return kind;
+}

package/edition/lib.mjs

@@ -40,9 +40,13 @@ import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
 import {
   PRINCIPAL_PRIVILEGE_FIELDS,
   assertPrivilegesHavePrincipals,
+  componentAudienceRequirements,
   componentInstalledOperationRequests,
+  componentEventSubscriptionRequirements,
+  componentRelaysOrgContext,
   componentOperationRequirements,
   componentOptionalOperationRequirements,
+  componentOwnedAudienceNamespaces,
   componentOrganizationSweepRequirements,
 } from './operation-requirements.mjs';
 import {
@@ -849,9 +853,12 @@ export async function loadKernelDistributionSchemas() {
     distributionImagesPredicateChannelRefusal,
     admitOperationGrants,
     admitOrganizationSweeps,
+    admitExactAudiences,
     contractRequiredServiceTargets,
     admitInstalledOperationCeiling,
     admitStoreWorkloadCeiling,
+    admitOrgContextRelays,
+    admitEventSubscriptions,
   } = mod;
   let topology;
   try {
@@ -948,12 +955,15 @@ export async function loadKernelDistributionSchemas() {
     // the resolve refuse through it (`assertOperationGrantsAdmitted`).
     typeof admitOperationGrants !== 'function' ||
     typeof admitOrganizationSweeps !== 'function' ||
+    typeof admitExactAudiences !== 'function' ||
     typeof contractRequiredServiceTargets !== 'function' ||
     // The installed-operation ceiling and the edition's store-workload ceiling,
     // both admitted at the lock (`assertInstalledOperationCeilingAdmitted`,
     // `assertStoreWorkloadCeilingAdmitted`).
     typeof admitInstalledOperationCeiling !== 'function' ||
     typeof admitStoreWorkloadCeiling !== 'function' ||
+    typeof admitOrgContextRelays !== 'function' ||
+    typeof admitEventSubscriptions !== 'function' ||
     typeof distributionImagesPredicateLockRefusal !== 'function' ||
     typeof distributionLockDigest !== 'function' ||
     typeof imageDeliveryEntitlementRefusal !== 'function' ||
@@ -975,14 +985,23 @@ export async function loadKernelDistributionSchemas() {
         `resolveRuntimeImagePlatforms/RuntimeImagePlatformKey/` +
         `kernel contract-authority digest SSOT/compareLockedServiceResources/resolveNexusBindings/describeNexusBindingRefusal/canonicalNexusFacts/` +
         `positive closure (resolveBiomeClosure/platformInvariantRoots/DistributionResolutionMode/provenance)/` +
-        `deriveWorkflowSubjects/deriveTrustCeiling (>= 0.71.0)/admitOperationGrants/admitOrganizationSweeps/admitInstalledOperationCeiling/admitStoreWorkloadCeiling/` +
+        `deriveWorkflowSubjects/deriveTrustCeiling (>= 0.71.0)/admitOperationGrants/admitOrganizationSweeps/admitExactAudiences/admitInstalledOperationCeiling/admitStoreWorkloadCeiling/admitOrgContextRelays/admitEventSubscriptions/` +
         `defaultTrustDomain/FIRST_PARTY_TRUST_DOMAIN/ProcessTrustPolicySchema/DistributionTrustPolicySchema/LockedStorePublisherSchema/` +
         `resolveFirstPartyCapabilityDomains/DistributionVisibility/` +
         `BiomeInstallPolicy/BiomeLaunchMode/ImageSourceHashAlgorithm/runtime-image enums — ` +
         `the dist is stale; rebuild kernel-contracts.`,
     );
   }
+  // The build-record exports (absent from a kernel before the build-record contract): carried as-is, NOT required
+  // here, so every other verb still loads an older kernel. `select-records` refuses a kernel that lacks them.
+  const { BUILD_RECORD_MEDIA_TYPE, BuildRecordSchema, buildRecordTag, parseBuildRecordTag, compareBuildRecordRuns, parseBuildRecord } = mod;
   return {
+    BUILD_RECORD_MEDIA_TYPE,
+    BuildRecordSchema,
+    buildRecordTag,
+    parseBuildRecordTag,
+    compareBuildRecordRuns,
+    parseBuildRecord,
     parseDistribution,
     parseDistributionLock,
     parseDistributionLockForReading,
@@ -1061,9 +1080,12 @@ export async function loadKernelDistributionSchemas() {
     distributionImagesPredicateChannelRefusal,
     admitOperationGrants,
     admitOrganizationSweeps,
+    admitExactAudiences,
     contractRequiredServiceTargets,
     admitInstalledOperationCeiling,
     admitStoreWorkloadCeiling,
+    admitOrgContextRelays,
+    admitEventSubscriptions,
     distributionImagesPredicateLockRefusal,
     imageDeliveryEntitlementRefusal,
     producerWorkflowPinRefusal,
@@ -1695,7 +1717,7 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
         'resolve no worker image: a worker declares artifact.kind "oci-image" or "shared-oci-image"',
     );
   }
-  // A privilege (`requiresOperations`, `optionalOperations`, `requestsInstalledOperations`, `requiresOrganizationSweeps`) is admitted for a lock workload
+  // A privilege (`requiresOperations`, `optionalOperations`, `requestsInstalledOperations`, `requiresOrganizationSweeps`, `requiresAudiences`, `ownsAudienceNamespaces`) is admitted for a lock workload
   // principal only; on any other component it is refused, never dropped.
   assertPrivilegesHavePrincipals(components, imageComponents, rel);
   // A biome must declare its images in EXACTLY ONE shape. Declaring both a
@@ -1750,10 +1772,22 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
   // organization` (`requestsInstalledOperations`), keyed like
   // `operationRequirements`. Declared intent only: the lock admits the ceiling.
   const installedOperationRequests = {};
+  // The workload components that declare `relaysOrgContext`, in manifest order
+  // (sorted at the write). Declared intent only: the lock admits it.
+  const orgContextRelayers = [];
+  // `component → the event subscription clauses it declares` (`subscribesEvents`),
+  // keyed like `operationRequirements`. Declared intent only: the lock admits them.
+  const eventSubscriptionRequirements = {};
   // `component → the organization sweeps it may hold`
   // (`requiresOrganizationSweeps`), keyed like `operationRequirements`.
   // Declared intent only: the seal admits or refuses each one.
   const organizationSweepRequirements = {};
+  // `component → the exact audiences it requires` (`requiresAudiences`), keyed
+  // like `operationRequirements`. Declared intent only: `admitExactAudiences`.
+  const audienceRequirements = {};
+  // The audience namespaces the biome's components own (`ownsAudienceNamespaces`),
+  // ONE entry per namespace however many components list it.
+  const ownedAudienceNamespaces = new Set();
   // Nexus services this biome's workers PROVIDE and REQUIRE (worker protocol
   // v2). Declared intent only, exactly like resources: the edition resolver
   // binds each requirement to the ONE shipped provider of the same
@@ -1945,8 +1979,16 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
       if (optionalOperations !== null) {optionalOperationRequirements[name] = optionalOperations;}
       const installed = componentInstalledOperationRequests(component, where);
       if (installed !== null) {installedOperationRequests[name] = installed;}
+      if (componentRelaysOrgContext(component, where)) {orgContextRelayers.push(name);}
+      const subscriptions = componentEventSubscriptionRequirements(component, where);
+      if (subscriptions !== null) {eventSubscriptionRequirements[name] = subscriptions;}
       const sweeps = componentOrganizationSweepRequirements(component, where);
       if (sweeps !== null) {organizationSweepRequirements[name] = sweeps;}
+      const audiences = componentAudienceRequirements(component, where);
+      if (audiences !== null) {audienceRequirements[name] = audiences;}
+      for (const namespace of componentOwnedAudienceNamespaces(component, where) ?? []) {
+        ownedAudienceNamespaces.add(namespace);
+      }
       const queues = componentWorkerTaskQueues(component, protocol, where);
       if (queues !== null) {workerTaskQueues[name] = queues;}
       const clients = componentWorkflowClients(protocol, where);
@@ -2400,6 +2442,22 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
           ),
         }
       : {}),
+    // The workload components that relay an organization context; omitted when
+    // none does.
+    ...(orgContextRelayers.length > 0
+      ? { orgContextRelayers: [...orgContextRelayers].sort(compareStrings) }
+      : {}),
+    // The event subscription clauses each workload component declares, in the
+    // kernel's canonical order; omitted when none declares any.
+    ...(Object.keys(eventSubscriptionRequirements).length > 0
+      ? {
+          eventSubscriptionRequirements: Object.fromEntries(
+            Object.entries(eventSubscriptionRequirements).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
     // The organization sweeps each workload component may hold; omitted when
     // none declares any.
     ...(Object.keys(organizationSweepRequirements).length > 0
@@ -2411,6 +2469,21 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
           ),
         }
       : {}),
+    // The exact audiences each workload component requires; omitted when none
+    // declares any.
+    ...(Object.keys(audienceRequirements).length > 0
+      ? {
+          audienceRequirements: Object.fromEntries(
+            Object.entries(audienceRequirements).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
+    // The audience namespaces this biome owns; omitted when it owns none.
+    ...(ownedAudienceNamespaces.size > 0
+      ? { ownsAudienceNamespaces: [...ownedAudienceNamespaces].sort(compareStrings) }
+      : {}),
     // The biome's signed dependency contract — DERIVED by the builder from the
     // SDK seams its code calls, read from the committed generated index and
     // validated there by the kernel schema. The edge set positive closure
@@ -2695,6 +2768,35 @@ export function buildCapabilityDomainOwners(index) {
     .sort((a, b) => compareStrings(a.domain, b.domain));
 }
 
+/**
+ * The audience-namespace ownership table of the lock: namespace -> owning
+ * biome, from every index entry's `ownsAudienceNamespaces`, like
+ * {@link buildCapabilityDomainOwners} (the whole index, so a trimmed edition
+ * names an unserved owner rather than an unowned audience). One row per
+ * (namespace, biome): an entry repeated for one biome id (server and web
+ * targets) adds nothing. Sorted by namespace.
+ *
+ * @throws when two biomes claim the same namespace.
+ */
+export function buildAudienceNamespaceOwners(index) {
+  const owners = new Map();
+  for (const entry of index) {
+    for (const namespace of entry.ownsAudienceNamespaces ?? []) {
+      const incumbent = owners.get(namespace);
+      if (incumbent !== undefined && incumbent !== entry.id) {
+        throw new Error(
+          `audience namespace "${namespace}" is claimed by BOTH biome "${incumbent}" and biome "${entry.id}". ` +
+            'A namespace has exactly one owner, so an ambiguous claim is refused.',
+        );
+      }
+      owners.set(namespace, entry.id);
+    }
+  }
+  return [...owners.entries()]
+    .map(([namespace, biomeId]) => ({ namespace, biomeId }))
+    .sort((a, b) => compareStrings(a.namespace, b.namespace));
+}
+
 /** Deterministic ordering used for both the index and the lock. */
 export function compareIndexEntries(a, b) {
   const order = biomeTierOrder();

package/edition/oci-evidence-verbs.mjs

@@ -39,7 +39,7 @@ import {
   createRegistryClientResolver,
   resolveImageSourceEvidenceReferrer,
   validateMaterializedImageSourceEvidence,
-  writeForeignAuthorityReferrerReport,
+  writeInvalidReferrerReport,
 } 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';
@@ -284,7 +284,7 @@ export async function planOciEvidenceBackfill({
       subjectDigest: item.subjectDigest,
       schemas,
       expectedContractAuthority,
-      onForeignAuthorityReferrer: writeForeignAuthorityReferrerReport,
+      onInvalidReferrer: writeInvalidReferrerReport,
     });
     const reported = {
       subjectKind: item.subject.kind,

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

@@ -8,6 +8,7 @@ import { compareStrings } from './lib.mjs';
 import { OrasRegistry } from './oras.mjs';
 import { BUNDLE_MEDIA_TYPE } from './produce-image-source-evidence.mjs';
 import {
+  EvidenceIntegrityError,
   PRODUCER_EVIDENCE_INDEX_FILE,
   PRODUCER_EVIDENCE_INDEX_MEDIA_TYPE,
   PRODUCER_STATEMENT_MEDIA_TYPE,
@@ -163,33 +164,49 @@ function assertExpectedAuthorityCommit(value) {
   }
 }
 
-/** 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';
+/** The referrer is not usable evidence under the expected authority: it is skipped for its subject and reported, never thrown past the resolver. */
+export class InvalidEvidenceReferrerError extends Error {
+  constructor({ artifactDigest, reason, sourceCommit = null, cause }) {
+    super(`evidence referrer ${artifactDigest} is invalid: ${reason}`, { cause });
+    this.name = 'InvalidEvidenceReferrerError';
     this.artifactDigest = artifactDigest;
+    this.reason = reason;
     this.sourceCommit = sourceCommit;
   }
 }
 
-/** The one stderr line that names a skipped foreign-authority referrer. */
-export function writeForeignAuthorityReferrerReport(skipped) {
+/** The artifact states a kernel contract authority other than the one evidence is read under. */
+export class ForeignAuthorityReferrerError extends InvalidEvidenceReferrerError {
+  constructor({ artifactDigest, sourceCommit, expectedAuthorityCommit }) {
+    super({
+      artifactDigest,
+      sourceCommit,
+      reason: `stated under kernel contract authority ${sourceCommit}, not ${expectedAuthorityCommit}`,
+    });
+    this.name = 'ForeignAuthorityReferrerError';
+  }
+}
+
+/** What a skipped referrer is reported as: the one sentence naming it and why it is not evidence. */
+export function describeInvalidReferrer(skipped) {
+  return `referrer ${skipped.artifactDigest}: ${skipped.reason}`;
+}
+
+/** The one stderr line that names a skipped invalid referrer. */
+export function writeInvalidReferrerReport(skipped) {
   process.stderr.write(
-    `[evidence] skipped ${skipped.imageRepository}@${skipped.subjectDigest} referrer ${skipped.artifactDigest}: ` +
-      `stated under kernel contract authority ${skipped.sourceCommit}, ` +
-      `not ${skipped.expectedAuthorityCommit}\n`,
+    `[evidence] skipped ${skipped.imageRepository}@${skipped.subjectDigest} ${describeInvalidReferrer(skipped)}\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.
+ * 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
+ * registry that cannot answer, or bytes that do not match their digests
+ * (`EvidenceIntegrityError`, a tampering signal), still throw.
  */
 export async function readImageSourceEvidenceArtifact({
   client,
@@ -201,44 +218,71 @@ export async function readImageSourceEvidenceArtifact({
 }) {
   assertExpectedAuthorityCommit(expectedAuthorityCommit);
   const fetched = await client.getManifestByDigest(repository, artifactDigest);
-  const { created, layers } = validateImageSourceEvidenceManifest({
-    manifest: fetched.document,
-    subjectDigest,
-  });
+  const invalid = (error) =>
+    new InvalidEvidenceReferrerError({
+      artifactDigest,
+      reason: error instanceof Error ? error.message : String(error),
+      cause: error,
+    });
+  let validated;
+  try {
+    validated = validateImageSourceEvidenceManifest({
+      manifest: fetched.document,
+      subjectDigest,
+    });
+  } catch (error) {
+    throw invalid(error);
+  }
+  const { created, layers } = validated;
   const directory = mkdtempSync(join(tmpdir(), 'xema-oci-evidence-'));
   try {
     for (const layer of layers) {
       const title = layer.annotations[OCI_TITLE_ANNOTATION];
       const bytes = await client.getBlob(repository, layer.digest);
       if (bytes.length !== layer.size || sha256Digest(bytes) !== layer.digest) {
-        throw new Error(`OCI evidence layer "${title}" does not match its descriptor`);
+        throw new EvidenceIntegrityError(
+          `OCI evidence layer "${title}" does not match its descriptor`,
+        );
       }
       const path = join(directory, title);
       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 });
+    try {
+      for (const sourceCommit of readRawStatementAuthorityCommits({ directory })) {
+        if (sourceCommit !== expectedAuthorityCommit) {
+          throw new ForeignAuthorityReferrerError({
+            artifactDigest,
+            sourceCommit,
+            expectedAuthorityCommit,
+          });
+        }
       }
+      const evidence = validateMaterializedImageSourceEvidence({
+        directory,
+        manifest: fetched.document,
+        subjectDigest,
+        schemas,
+      });
+      return { ...evidence, artifactDigest, created };
+    } catch (error) {
+      if (error instanceof InvalidEvidenceReferrerError || error instanceof EvidenceIntegrityError) {
+        throw error;
+      }
+      throw invalid(error);
     }
-    const evidence = validateMaterializedImageSourceEvidence({
-      directory,
-      manifest: fetched.document,
-      subjectDigest,
-      schemas,
-    });
-    return { ...evidence, artifactDigest, created };
   } finally {
     rmSync(directory, { recursive: true, force: true });
   }
 }
 
 /**
- * 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.
+ * Resolve the newest valid evidence referrer deterministically. Every
+ * referrer of the subject is evaluated; one that is not valid evidence under
+ * `expectedContractAuthority` (foreign authority, bad statement, bad layers)
+ * is reported to `onInvalidReferrer` and skipped. It is never a fallback: an
+ * invalid referrer is not read as evidence, however old or new. Returns null
+ * when no referrer is valid; the handler has then named each invalid one.
  */
 export async function resolveImageSourceEvidenceReferrer({
   client,
@@ -246,12 +290,12 @@ export async function resolveImageSourceEvidenceReferrer({
   subjectDigest,
   schemas,
   expectedContractAuthority,
-  onForeignAuthorityReferrer,
+  onInvalidReferrer,
 }) {
   const expectedAuthorityCommit = expectedContractAuthority?.sourceCommit;
   assertExpectedAuthorityCommit(expectedAuthorityCommit);
-  if (typeof onForeignAuthorityReferrer !== 'function') {
-    throw new Error('a foreign-authority referrer report handler is required');
+  if (typeof onInvalidReferrer !== 'function') {
+    throw new Error('an invalid-referrer report handler is required');
   }
   const { authority, repository } = splitImageRef(imageRepository);
   if (client.authority !== authority) {
@@ -286,11 +330,12 @@ export async function resolveImageSourceEvidenceReferrer({
         }),
       );
     } catch (error) {
-      if (!(error instanceof ForeignAuthorityReferrerError)) {throw error;}
-      onForeignAuthorityReferrer({
+      if (!(error instanceof InvalidEvidenceReferrerError)) {throw error;}
+      onInvalidReferrer({
         imageRepository,
         subjectDigest,
         artifactDigest: error.artifactDigest,
+        reason: error.reason,
         sourceCommit: error.sourceCommit,
         expectedAuthorityCommit,
       });