@xemahq/xema 0.45.0 → 0.46.0

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,6 +39,7 @@ import {
   createRegistryClientResolver,
   resolveImageSourceEvidenceReferrer,
   validateMaterializedImageSourceEvidence,
+  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';
@@ -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,
+      onInvalidReferrer: writeInvalidReferrerReport,
     });
     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

@@ -8,11 +8,13 @@ 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,
   producerEvidenceLayerFiles,
   readProducerEvidenceDirectory,
+  readRawStatementAuthorityCommits,
 } from './producer-evidence-bundle.mjs';
 import {
   loadRegistryCredentialDeclarations,
@@ -156,9 +158,55 @@ 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 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 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} ${describeInvalidReferrer(skipped)}\n`,
+  );
+}
+
 /**
  * Fetch, content-address validate and decode one OCI evidence artifact.
  * `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
+ * registry that cannot answer, or bytes that do not match their digests
+ * (`EvidenceIntegrityError`, a tampering signal), still throw.
  */
 export async function readImageSourceEvidenceArtifact({
   client,
@@ -166,43 +214,89 @@ export async function readImageSourceEvidenceArtifact({
   subjectDigest,
   artifactDigest,
   schemas,
+  expectedAuthorityCommit,
 }) {
+  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 });
     }
-    const evidence = validateMaterializedImageSourceEvidence({
-      directory,
-      manifest: fetched.document,
-      subjectDigest,
-      schemas,
-    });
-    return { ...evidence, artifactDigest, created };
+    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);
+    }
   } finally {
     rmSync(directory, { recursive: true, force: true });
   }
 }
 
-/** Resolve the newest valid evidence referrer deterministically. */
+/**
+ * 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,
   imageRepository,
   subjectDigest,
   schemas,
+  expectedContractAuthority,
+  onInvalidReferrer,
 }) {
+  const expectedAuthorityCommit = expectedContractAuthority?.sourceCommit;
+  assertExpectedAuthorityCommit(expectedAuthorityCommit);
+  if (typeof onInvalidReferrer !== 'function') {
+    throw new Error('an invalid-referrer report handler is required');
+  }
   const { authority, repository } = splitImageRef(imageRepository);
   if (client.authority !== authority) {
     throw new Error(
@@ -224,16 +318,30 @@ 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 InvalidEvidenceReferrerError)) {throw error;}
+      onInvalidReferrer({
+        imageRepository,
         subjectDigest,
-        artifactDigest: descriptor.digest,
-        schemas,
-      }),
-    );
+        artifactDigest: error.artifactDigest,
+        reason: error.reason,
+        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/operation-grant-admission.mjs

@@ -14,7 +14,7 @@
 export class OperationGrantAdmissionError extends Error {
   /**
    * @param {string} distributionId
-   * @param {ReadonlyArray<{code: string, biome: string, component: string, operation: string, message: string}>} refusals
+   * @param {ReadonlyArray<{code: string, operation: string, message: string}>} refusals
    */
   constructor(distributionId, refusals) {
     super(
@@ -45,9 +45,11 @@ export function ungrantedOptionalOperationLines(distributionId, ungrantedOptiona
  * {@link ungrantedOptionalOperationLines}; an ungranted optional operation never fails.
  */
 export function assertOperationGrantsAdmitted(schemas, lock, { report } = {}) {
-  const { grants, refusals, ungrantedOptional } = schemas.admitOperationGrants(lock);
-  if (refusals.length > 0) {
-    throw new OperationGrantAdmissionError(lock.distributionId, refusals);
+  const { grants, refusals, ungrantedOptional, platformServiceRefusals } = schemas.admitOperationGrants(lock);
+  // A platform service's refused requirement fails exactly like a biome component's, through the same error.
+  const allRefusals = [...refusals, ...platformServiceRefusals];
+  if (allRefusals.length > 0) {
+    throw new OperationGrantAdmissionError(lock.distributionId, allRefusals);
   }
   if (report !== undefined) {
     for (const line of ungrantedOptionalOperationLines(lock.distributionId, ungrantedOptional)) {report(line);}
@@ -86,6 +88,37 @@ export function assertOrganizationSweepsAdmitted(schemas, lock) {
   return grants;
 }
 
+/** Thrown when one or more declared exact audiences are not admitted. */
+export class ExactAudienceAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares audience requirements that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'ExactAudienceAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every exact-audience requirement of `lock` through the kernel
+ * (`admitExactAudiences`), or throw {@link ExactAudienceAdmissionError} listing
+ * every refusal. Returns the admitted grants. The resolve and the seal call it
+ * beside {@link assertOperationGrantsAdmitted}.
+ */
+export function assertExactAudiencesAdmitted(schemas, lock) {
+  const { grants, refusals } = schemas.admitExactAudiences(lock);
+  if (refusals.length > 0) {
+    throw new ExactAudienceAdmissionError(lock.distributionId, refusals);
+  }
+  return grants;
+}
+
 /** Thrown when one or more requested installed operations are not admitted into the ceiling. */
 export class InstalledOperationCeilingAdmissionError extends Error {
   /**
@@ -147,3 +180,64 @@ export function assertStoreWorkloadCeilingAdmitted(schemas, lock) {
   }
   return ceiling;
 }
+
+/** Thrown when one or more declared organization-context relays are not admitted. */
+export class OrgContextRelayAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, biome: string, component: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares organization-context relays that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'OrgContextRelayAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every `orgContextRelayers` entry of `lock` through the kernel
+ * (`admitOrgContextRelays`), or throw {@link OrgContextRelayAdmissionError}
+ * listing every refusal. Returns the admitted relay rows.
+ */
+export function assertOrgContextRelaysAdmitted(schemas, lock) {
+  const { relays, refusals } = schemas.admitOrgContextRelays(lock);
+  if (refusals.length > 0) {
+    throw new OrgContextRelayAdmissionError(lock.distributionId, refusals);
+  }
+  return relays;
+}
+
+/** Thrown when one or more declared event subscription clauses are not admitted. */
+export class EventSubscriptionAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, biome: string, component: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares event subscriptions that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'EventSubscriptionAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every `eventSubscriptionRequirements` clause of `lock` through the
+ * kernel (`admitEventSubscriptions`), or throw
+ * {@link EventSubscriptionAdmissionError} listing every refusal. Returns the
+ * admission: the first-party grants and the installed ceilings.
+ */
+export function assertEventSubscriptionsAdmitted(schemas, lock) {
+  const admission = schemas.admitEventSubscriptions(lock);
+  if (admission.refusals.length > 0) {
+    throw new EventSubscriptionAdmissionError(lock.distributionId, admission.refusals);
+  }
+  return admission;
+}