@xemahq/xema 0.29.1 → 0.31.0

package/edition/lib.mjs

@@ -14,6 +14,9 @@ import { createRequire } from 'node:module';
 import { isIP } from 'node:net';
 import { join } from 'node:path';
 
+import { parse as parseYaml } from 'yaml';
+
+import { ADAPTER_HOST_BIOME_ID, readHostPackageVersions } from './adapter-host-versions.mjs';
 import { readBiomeAuthorizationModuleAt } from './authorization-base.mjs';
 import {
   isAuthoritativeProductionBiomeSource,
@@ -27,6 +30,12 @@ import {
   sourcePath,
 } from './edition-workspace.mjs';
 import { SHA256_HEX_PATTERN } from './evidence-grammars.mjs';
+import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
+import {
+  assertPrivilegesHavePrincipals,
+  componentOperationRequirements,
+  componentOrganizationSweepRequirements,
+} from './operation-requirements.mjs';
 import {
   createSourceAuthority,
   DistributionSourceMode,
@@ -688,6 +697,18 @@ export async function loadKernelDistributionSchemas() {
         `Underlying error: ${err.message}`,
     );
   }
+  // The Node-only half of the distribution contracts (`distribution/server`): the lock digest and the
+  // predicate checks that recompute it.
+  let server;
+  try {
+    server = await import(`file://${kernelDistPath('distribution', 'server', 'index.js')}`);
+  } catch (err) {
+    throw new Error(
+      `Cannot load the built kernel distribution/server module from ${kernelDistPath('distribution', 'server', 'index.js')}. ` +
+        `Rebuild the kernel checkout (${kernelRepoDir()}). Underlying error: ${err.message}`,
+    );
+  }
+  const { distributionLockDigest, distributionImagesPredicateLockRefusal, imageDeliveryEntitlementRefusal } = server;
   const {
     parseDistribution,
     parseDistributionLock,
@@ -695,6 +716,8 @@ export async function loadKernelDistributionSchemas() {
     parseUnsealedDistributionLock,
     parseCustomerEditionDefinition,
     customerTrustCeilingIssues,
+    customerLockCeilingIssues,
+    biomeOriginsOfLock,
     sealDistributionLock,
     unsealedProjection,
     UNSEALED_DISTRIBUTION_LOCK_SCHEMA,
@@ -714,6 +737,7 @@ export async function loadKernelDistributionSchemas() {
     SigstoreEvidenceDescriptorSchema,
     parsePlatformServiceSourceIndex,
     parseRuntimeImageSourceIndex,
+    producerWorkflowPinRefusal,
     resolveRuntimeImagePlatforms,
     BiomeInstallPolicy,
     BiomeLaunchMode,
@@ -749,6 +773,9 @@ export async function loadKernelDistributionSchemas() {
     describeProvenance,
     describeHop,
     deriveWorkflowSubjects,
+    distributionImagesPredicateChannelRefusal,
+    admitOperationGrants,
+    admitOrganizationSweeps,
   } = mod;
   let topology;
   try {
@@ -791,6 +818,7 @@ export async function loadKernelDistributionSchemas() {
     typeof SigstoreEvidenceDescriptorSchema?.parse !== 'function' ||
     typeof parsePlatformServiceSourceIndex !== 'function' ||
     typeof parseRuntimeImageSourceIndex !== 'function' ||
+    typeof producerWorkflowPinRefusal !== 'function' ||
     typeof resolveRuntimeImagePlatforms !== 'function' ||
     typeof resolveFirstPartyCapabilityDomains !== 'function' ||
     typeof DistributionVisibility !== 'object' ||
@@ -837,6 +865,16 @@ export async function loadKernelDistributionSchemas() {
     // A biome's workflow subjects and its edition trust ceiling, each written
     // through the kernel's one derivation (`@xemahq/contracts` >= 0.71.0).
     typeof deriveWorkflowSubjects !== 'function' ||
+    // Predicate v2 checks (`@xemahq/contracts` >= 0.78.0): the channel the verifying policy row states and
+    // the lock digest the predicates bind.
+    typeof distributionImagesPredicateChannelRefusal !== 'function' ||
+    // The ONE admission of service-to-service operation grants; the seal and
+    // the resolve refuse through it (`assertOperationGrantsAdmitted`).
+    typeof admitOperationGrants !== 'function' ||
+    typeof admitOrganizationSweeps !== 'function' ||
+    typeof distributionImagesPredicateLockRefusal !== 'function' ||
+    typeof distributionLockDigest !== 'function' ||
+    typeof imageDeliveryEntitlementRefusal !== 'function' ||
     typeof deriveTrustCeiling !== 'function' ||
     // The trust-domain vocabulary a customer edition is bounded by: the vendor's
     // own domain, a biome's default domain, and the two ceiling grammars a
@@ -853,7 +891,7 @@ 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)/` +
+        `deriveWorkflowSubjects/deriveTrustCeiling (>= 0.71.0)/admitOperationGrants/admitOrganizationSweeps/` +
         `defaultTrustDomain/FIRST_PARTY_TRUST_DOMAIN/ProcessTrustPolicySchema/DistributionTrustPolicySchema/` +
         `resolveFirstPartyCapabilityDomains/DistributionVisibility/` +
         `BiomeInstallPolicy/BiomeLaunchMode/ImageSourceHashAlgorithm/runtime-image enums — ` +
@@ -867,6 +905,8 @@ export async function loadKernelDistributionSchemas() {
     parseUnsealedDistributionLock,
     parseCustomerEditionDefinition,
     customerTrustCeilingIssues,
+    customerLockCeilingIssues,
+    biomeOriginsOfLock,
     sealDistributionLock,
     unsealedProjection,
     UNSEALED_DISTRIBUTION_LOCK_SCHEMA,
@@ -926,6 +966,13 @@ export async function loadKernelDistributionSchemas() {
     FIRST_PARTY_TRUST_DOMAIN,
     ProcessTrustPolicySchema,
     DistributionTrustPolicySchema,
+    distributionLockDigest,
+    distributionImagesPredicateChannelRefusal,
+    admitOperationGrants,
+    admitOrganizationSweeps,
+    distributionImagesPredicateLockRefusal,
+    imageDeliveryEntitlementRefusal,
+    producerWorkflowPinRefusal,
   };
 }
 
@@ -1086,6 +1133,10 @@ function listBiomeManifestsAt(directory, repo, commit) {
       rel,
       repo,
       path,
+      // The manifest's directory in its repository, and a reader of any file of
+      // that repository at the SAME pinned commit (the host's pnpm-lock.yaml).
+      manifestDirectory,
+      readRepositoryText: (repoRelativePath) => readGitTextAtCommitOrNull(directory, repoRelativePath, commit),
       ...(authorizationModule === null ? {} : { authorizationModule }),
     });
   }
@@ -1520,6 +1571,9 @@ 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`, `requiresOrganizationSweeps`) 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
   // legacy `ships.apis[]` entry and a v5 image component is ambiguous during
   // the staged migration — fail fast instead of guessing.
@@ -1543,6 +1597,12 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
   // roster a release for them — so they are carried in a SEPARATE array and
   // contribute NO service-dependency edge and NO service owner.
   const runtimeComponents = [];
+  // `component key → image name` for every runtime component declared through
+  // `xema.components[]`. A `runtime-image` edge names its target by component
+  // KEY, and the image lock by image NAME, so the edition resolver reads this
+  // to follow another biome's edge to this one. The legacy `ships.apis[]`
+  // shape declares no component key, so no edge can name its components.
+  const runtimeComponentKeys = {};
   // Infrastructure resources each rostered component NEEDS
   // (`protocol.resources`) and the resource kinds it PROVIDES
   // (`protocol.providesResources`). Declared INTENT only: the resolver binds
@@ -1554,6 +1614,14 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
   // `service → what sharing a process needs to know about it`, for EVERY
   // platform-scheduled image component — see `componentProcessFacts`.
   const serviceProcessFacts = {};
+  // `component → the service-to-service operations it requires`
+  // (`requiresOperations`), keyed by the SAME name the lock uses. Declared
+  // intent only: the seal admits or refuses each one.
+  const operationRequirements = {};
+  // `component → the organization sweeps it may hold`
+  // (`requiresOrganizationSweeps`), keyed like `operationRequirements`.
+  // Declared intent only: the seal admits or refuses each one.
+  const organizationSweepRequirements = {};
   // 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
@@ -1645,7 +1713,19 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
               `cannot carry a service-dependency edge`,
           );
         }
+        // An operation grant is admitted for a rostered workload caller, and a
+        // runtime component is not one. Refused rather than dropped.
+        for (const field of ['requiresOperations', 'requiresOrganizationSweeps']) {
+          if (component[field] !== undefined) {
+            throw new Error(
+              `${where} declares scheduler "runtime" and ${field} — a ` +
+                `privilege names a rostered workload, and a component that is ` +
+                `never scheduled is not one`,
+            );
+          }
+        }
         runtimeComponents.push(name);
+        runtimeComponentKeys[component.key] = name;
         continue;
       }
       if (component.scheduler !== 'platform') {
@@ -1727,6 +1807,10 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
       nexusRequires.push(...nexus.requires);
       services.push(name);
       serviceProcessFacts[name] = componentProcessFacts(component, where);
+      const operations = componentOperationRequirements(component, where);
+      if (operations !== null) {operationRequirements[name] = operations;}
+      const sweeps = componentOrganizationSweepRequirements(component, where);
+      if (sweeps !== null) {organizationSweepRequirements[name] = sweeps;}
       const queues = componentWorkerTaskQueues(component, protocol, where);
       if (queues !== null) {workerTaskQueues[name] = queues;}
       const clients = componentWorkflowClients(protocol, where);
@@ -1892,6 +1976,25 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
   }
   // Already de-duplicated and sorted by the kernel helper.
   const requiresUnique = [...kernelBiome.requiredBiomeDependencyIds(parsedIndex.biome)];
+  // The runtime components this biome's components dispatch: the kernel's
+  // `runtime-image` edges, reduced to their distinct targets. "Needs that
+  // image" and nothing else — the kernel keeps them out of
+  // `requiredBiomeDependencyIds`, and they never enter `requires`: the edition
+  // resolver carries the target's image without installing its biome.
+  const dispatchesRuntimeComponents = [
+    ...new Map(
+      parsedIndex.biome.edges
+        .filter((edge) => edge.kind === kernelBiome.BiomeGeneratedEdgeKind.RuntimeImage)
+        .map((edge) => [
+          `${edge.target.biomeId}\0${edge.target.componentKey}`,
+          { biomeId: edge.target.biomeId, componentKey: edge.target.componentKey },
+        ]),
+    ).values(),
+  ].sort(
+    (a, b) =>
+      compareStrings(a.biomeId, b.biomeId) ||
+      compareStrings(a.componentKey, b.componentKey),
+  );
 
   // Optional server biomes a web biome can integrate with but does not require
   // (never cause an ORPHANED resolution). Carried separately from `requires`.
@@ -1914,10 +2017,10 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
     ? [...new Set(xema.ownsCapabilityDomains)].sort(compareStrings)
     : [];
   for (const domain of ownsCapabilityDomains) {
-    if (typeof domain !== 'string' || !/^[a-z][a-z0-9-]*$/.test(domain)) {
+    if (!isKernelCapabilityDomain(domain)) {
       throw new Error(
         `${rel}: xema.ownsCapabilityDomains contains ${JSON.stringify(domain)}, ` +
-          `which is not a valid capability domain (^[a-z][a-z0-9-]*$)`,
+          `which is not a valid capability domain`,
       );
     }
   }
@@ -2032,6 +2135,17 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
         }
       : {}),
     runtimeComponents,
+    // Omitted when the biome has no runtime component (almost every biome),
+    // so the index stays byte-stable for everything that declares none.
+    ...(Object.keys(runtimeComponentKeys).length > 0
+      ? {
+          runtimeComponentKeys: Object.fromEntries(
+            Object.entries(runtimeComponentKeys).sort(([a], [b]) => compareStrings(a, b)),
+          ),
+        }
+      : {}),
+    // Omitted when the biome dispatches nothing, for the same reason.
+    ...(dispatchesRuntimeComponents.length > 0 ? { dispatchesRuntimeComponents } : {}),
     hostModules,
     // Omitted when the biome declares none, or when its host modules already
     // carry it — see the projection above. At `origin/develop` that is every
@@ -2058,6 +2172,16 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
                     .filter((name) => typeof name === 'string' && name.length > 0),
                 ),
               ].sort(compareStrings),
+              // The capabilities the signed biome declares (a delegation
+              // origination may lend only these): the manifest's
+              // `xema.exposesCapabilities`; `requires*` are what it asks for.
+              declaredCapabilities: [
+                ...new Set(
+                  (Array.isArray(xema.exposesCapabilities) ? xema.exposesCapabilities : []).filter(
+                    (ref) => typeof ref === 'string' && ref.length > 0,
+                  ),
+                ),
+              ].sort(compareStrings),
             },
           },
         }
@@ -2114,6 +2238,28 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
           ),
         }
       : {}),
+    // The service-to-service operations each workload component requires;
+    // omitted when none declares any, so the index stays byte-stable.
+    ...(Object.keys(operationRequirements).length > 0
+      ? {
+          operationRequirements: Object.fromEntries(
+            Object.entries(operationRequirements).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
+    // The organization sweeps each workload component may hold; omitted when
+    // none declares any.
+    ...(Object.keys(organizationSweepRequirements).length > 0
+      ? {
+          organizationSweepRequirements: Object.fromEntries(
+            Object.entries(organizationSweepRequirements).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
     // 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
@@ -2263,6 +2409,26 @@ export function validateServiceDependencyOwnerParity(
   return entries;
 }
 
+/**
+ * The adapter host's resolved `@xemahq/contracts` / `@xemahq/biome-sdk` versions, read from its source
+ * repository's pnpm-lock.yaml at the pinned commit. An INDEX field only: the distribution lock never carries it.
+ */
+function adapterHostPackageVersions(manifest) {
+  const services = (manifest.raw.xema.components ?? []).filter(
+    (component) => component?.kind === 'service' && component.artifact?.kind === 'oci-image',
+  );
+  if (services.length !== 1) {
+    throw new Error(`${manifest.rel}: the adapter host declares ${services.length} oci-image service components; exactly one carries its package`);
+  }
+  const lockfilePath = 'pnpm-lock.yaml';
+  return readHostPackageVersions({
+    lockfileText: manifest.readRepositoryText(lockfilePath),
+    importer: `${manifest.manifestDirectory}/${services[0].artifact.path}`,
+    lockfilePath: `${manifest.repo}/${lockfilePath}`,
+    parseYaml,
+  });
+}
+
 export async function buildBiomeIndex(
   platformServiceIndex,
   sourceRepositories = distributionBiomeSourceRepositories(),
@@ -2275,7 +2441,12 @@ export async function buildBiomeIndex(
     });
   const entries = [];
   for (const manifest of await committedBiomeManifests(sourceRepositories, authority)) {
-    entries.push(await manifestToIndexEntry(manifest));
+    const entry = await manifestToIndexEntry(manifest);
+    entries.push(
+      entry.id === ADAPTER_HOST_BIOME_ID
+        ? { ...entry, hostPackageVersions: adapterHostPackageVersions(manifest) }
+        : entry,
+    );
   }
   resolveServiceDependencyOwners(entries, platformServiceIndex);
   assertDeclaredDatabasesUnowned(entries);
@@ -2553,6 +2724,23 @@ export function validateImmutableBiomeIndex(index) {
       }
       runtimeComponents.add(component);
     }
+    for (const [key, image] of Object.entries(biome.runtimeComponentKeys ?? {})) {
+      if (!runtimeComponents.has(image)) {
+        throw new Error(
+          `biome "${biome.id}" keys runtime component "${key}" to "${String(image)}", which is not one of its runtime components`,
+        );
+      }
+    }
+    const dispatched = new Set();
+    for (const edge of biome.dispatchesRuntimeComponents ?? []) {
+      const edgeKey = `${edge.biomeId}\0${edge.componentKey}`;
+      if (dispatched.has(edgeKey)) {
+        throw new Error(
+          `biome "${biome.id}" dispatches runtime component "${edge.componentKey}" of biome "${edge.biomeId}" more than once`,
+        );
+      }
+      dispatched.add(edgeKey);
+    }
     const edges = new Set();
     for (const edge of biome.serviceDependencies ?? []) {
       if (!services.has(edge.consumerService)) {

package/edition/oci-evidence-verbs.mjs

@@ -32,7 +32,7 @@ import {
   isEntryModule,
 } from './edition-workspace.mjs';
 import { SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
-import { canonicalJson, loadValidatedLocks } from './image-evidence.mjs';
+import { canonicalJson, loadValidatedImageLocks } from './image-evidence.mjs';
 import { compareStrings, loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
 import {
   IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE,
@@ -230,7 +230,7 @@ export async function planOciEvidenceBackfill({
   const missingGit = new Map();
   for (const distributionId of distributionIds) {
     assertCanonicalDistributionId(distributionId);
-    const { imageLock, repositoryPins } = await loadValidatedLocks(distributionId, data, schemas, {
+    const { imageLock, repositoryPins } = await loadValidatedImageLocks(distributionId, data, schemas, {
       editionsRoot: editions,
     });
     for (const subject of imageLock.subjects) {

package/edition/operation-grant-admission.mjs

@@ -0,0 +1,70 @@
+/**
+ * Admission of service-to-service operation grants at the lock.
+ *
+ * A manifest declares intent (`requiresOperations`, carried in the lock as
+ * `operationRequirements`); the kernel's `admitOperationGrants` admits or
+ * refuses every requirement, and a refusal is never a warning. The resolve
+ * and the seal both call {@link assertOperationGrantsAdmitted}, so a lock with
+ * a refused requirement is neither written nor sealed.
+ */
+
+/** Thrown when one or more declared operation requirements are not admitted. */
+export class OperationGrantAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, biome: string, component: string, operation: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares operation requirements that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'OperationGrantAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every operation requirement of `lock` through the kernel, or throw
+ * {@link OperationGrantAdmissionError} listing every refusal. Returns the
+ * admitted grants.
+ */
+export function assertOperationGrantsAdmitted(schemas, lock) {
+  const { grants, refusals } = schemas.admitOperationGrants(lock);
+  if (refusals.length > 0) {
+    throw new OperationGrantAdmissionError(lock.distributionId, refusals);
+  }
+  return grants;
+}
+
+/** Thrown when one or more declared organization sweeps are not admitted. */
+export class OrganizationSweepAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, biome: string, component: string, sweep: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares organization sweeps that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'OrganizationSweepAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every organization sweep requirement of `lock` through the kernel
+ * (`admitOrganizationSweeps`), or throw {@link OrganizationSweepAdmissionError}
+ * listing every refusal. Returns the admitted rows. The resolve and the seal
+ * call it beside {@link assertOperationGrantsAdmitted}.
+ */
+export function assertOrganizationSweepsAdmitted(schemas, lock) {
+  const { grants, refusals } = schemas.admitOrganizationSweeps(lock);
+  if (refusals.length > 0) {
+    throw new OrganizationSweepAdmissionError(lock.distributionId, refusals);
+  }
+  return grants;
+}

package/edition/operation-requirements.mjs

@@ -0,0 +1,128 @@
+import { createRequire } from 'node:module';
+
+import { kernelDistPath } from './edition-workspace.mjs';
+import { compareStrings } from './string-order.mjs';
+
+const requireFromHere = createRequire(import.meta.url);
+
+let kernelPrivilegeGrammars;
+
+/**
+ * The kernel's ONE operation-id grammar (`OperationIdSchema`) and closed
+ * `PlatformSweep` vocabulary, from the distribution subpath: the only plane
+ * the edition protocol exposes to this library.
+ */
+function loadKernelPrivilegeGrammars() {
+  if (kernelPrivilegeGrammars) {return kernelPrivilegeGrammars;}
+  const mod = requireFromHere(kernelDistPath('distribution', 'index.js'));
+  if (typeof mod.OperationIdSchema?.safeParse !== 'function' || typeof mod.PlatformSweepSchema?.safeParse !== 'function') {
+    throw new Error(
+      `Built kernel distribution module at ${kernelDistPath('distribution', 'index.js')} does not export ` +
+        'OperationIdSchema and PlatformSweepSchema — the dist is stale; rebuild kernel-contracts at a commit that carries them.',
+    );
+  }
+  kernelPrivilegeGrammars = mod;
+  return mod;
+}
+
+/**
+ * One component's declared privilege list, as the index carries it: sorted,
+ * unique, every entry graded by the kernel schema. `null` when undeclared. An
+ * empty list, a repeat or an invalid entry REFUSES naming the manifest: this
+ * reads the RAW manifest, and the kernel's component schema is not applied on
+ * this path.
+ */
+function declaredPrivilegeList(component, where, field, schema, what) {
+  const declared = component[field];
+  if (declared === undefined) {return null;}
+  if (!Array.isArray(declared) || declared.length === 0) {
+    throw new Error(
+      `${where} declares ${field} that is not a non-empty array of ${what}s — ` +
+        'a list that names nothing states nothing, so omit the field',
+    );
+  }
+  const values = declared.map((value, position) => {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+      throw new Error(
+        `${where} ${field}[${position}] ${JSON.stringify(value)} is not ${what === 'operation id' ? 'an' : 'a'} ${what}: ` +
+          parsed.error.issues.map((issue) => issue.message).join('; '),
+      );
+    }
+    return parsed.data;
+  });
+  const unique = [...new Set(values)];
+  if (unique.length !== values.length) {
+    const repeated = values.find((value, position) => values.indexOf(value) !== position);
+    throw new Error(`${where} ${field} names ${repeated} more than once`);
+  }
+  return unique.sort(compareStrings);
+}
+
+/**
+ * The service-to-service operations one workload component declares it needs
+ * (`requiresOperations`), graded by the kernel's one operation-id grammar.
+ * Declared INTENT only; the seal admits or refuses each (`admitOperationGrants`).
+ */
+export function componentOperationRequirements(component, where) {
+  const { OperationIdSchema } = loadKernelPrivilegeGrammars();
+  return declaredPrivilegeList(component, where, 'requiresOperations', OperationIdSchema, 'operation id');
+}
+
+/**
+ * The organization sweeps one workload component declares it may hold
+ * (`requiresOrganizationSweeps`), each a member of the kernel's closed
+ * `PlatformSweep`. A sweep's reach is fixed by the kernel, never declared.
+ * Declared INTENT only; the seal admits or refuses each (`admitOrganizationSweeps`).
+ */
+export function componentOrganizationSweepRequirements(component, where) {
+  const { PlatformSweepSchema } = loadKernelPrivilegeGrammars();
+  return declaredPrivilegeList(component, where, 'requiresOrganizationSweeps', PlatformSweepSchema, 'platform sweep');
+}
+
+/**
+ * The privilege declarations a component may carry only if it is a workload
+ * principal in the lock.
+ */
+export const PRINCIPAL_PRIVILEGE_FIELDS = Object.freeze(['requiresOperations', 'requiresOrganizationSweeps']);
+
+/**
+ * Thrown when a component that has no workload principal in the lock declares
+ * a privilege. A principal is a rostered image component: a service (under its
+ * `protocol.serviceName`) or a worker (under its key). A job, an imageless
+ * component or a content/web/adapter component is never one, so its
+ * declaration could never be admitted; it is refused rather than dropped.
+ */
+export class PrivilegeWithoutPrincipalError extends Error {
+  /**
+   * @param {string} manifest the manifest path
+   * @param {string} component the component key
+   * @param {string} field the privilege field it declares
+   */
+  constructor(manifest, component, field) {
+    super(
+      `${manifest}: xema.components[] "${component}" declares ${field}, but it has no ` +
+        'workload principal in the lock (only a service or worker image component is one), ' +
+        'so the declaration could never be admitted',
+    );
+    this.name = 'PrivilegeWithoutPrincipalError';
+    this.manifest = manifest;
+    this.component = component;
+    this.field = field;
+  }
+}
+
+/**
+ * Refuse every privilege declaration on a component outside `principals`
+ * (the components that become lock workloads). Never drops one silently.
+ */
+export function assertPrivilegesHavePrincipals(components, principals, manifest) {
+  for (const component of components) {
+    if (component === null || typeof component !== 'object' || principals.includes(component)) {continue;}
+    for (const field of PRINCIPAL_PRIVILEGE_FIELDS) {
+      if (component[field] !== undefined) {
+        throw new PrivilegeWithoutPrincipalError(manifest, String(component.key ?? component.name ?? '?'), field);
+      }
+    }
+  }
+}

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

@@ -66,7 +66,7 @@ import {
 } from './edition-workspace.mjs';
 import {
   canonicalJson,
-  loadValidatedLocks,
+  loadValidatedImageLocks,
 } from './image-evidence.mjs';
 import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
 import { compareStrings, loadKernelDistributionSchemas } from './lib.mjs';
@@ -142,7 +142,7 @@ export async function planImageEvidenceRefresh({
 
   const subjects = [];
   for (const distributionId of [...distributionIds].sort(compareStrings)) {
-    const { imageLock, repositoryPins, runtimeSourceIndex } = await loadValidatedLocks(
+    const { imageLock, repositoryPins, runtimeSourceIndex } = await loadValidatedImageLocks(
       distributionId,
       dataRootDirectory,
       schemas,

package/edition/platform-lock-readability.mjs

@@ -5,7 +5,7 @@
 //
 // An edition's sealed lock must be PARSEABLE BY THE CONTRACTS VERSION THE
 // IMAGES OF THAT EDITION ACTUALLY RESOLVE. Nothing asserted that, and on
-// 2026-09-17 the gap took out three presenca-dev services at once:
+// 2026-09-17 the gap took out three a customer environment services at once:
 //
 //     Invalid distribution.lock.json: [biomes.87.source] Unrecognized key:
 //     "imageNamePrefix"
@@ -92,7 +92,7 @@
 // KNOWN LIMIT, stated rather than discovered: a subject whose `repo` has NO
 // entry in `repositoryPins` is outside this check, because the pin index is
 // where a commit to read the declaration AT comes from. A customer edition
-// has one today — `presenca-biomes`, a customer repository pinned elsewhere.
+// has one today — `<customer>-biomes`, a customer repository pinned elsewhere.
 // It was outside this gate before the narrowing too, so nothing was lost here;
 // it is named so nobody reads the corpus line as covering it.
 //

package/edition/platform-service-class.mjs

@@ -1,3 +1,6 @@
+import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
+import { compareStrings } from './string-order.mjs';
+
 /**
  * A platform service's installation class, as the index carries it.
  *
@@ -12,6 +15,45 @@ export function declaredInstallationClass(declaration) {
     : { installationClass: declaration.installationClass };
 }
 
+/**
+ * The capability domains a platform service OWNS, as the index carries them:
+ * sorted and non-empty, or no key at all.
+ *
+ * Ownership is the SERVICE's own statement, read from its source manifest
+ * (`xema.ownsCapabilityDomains` in the manifest `platformServiceSources` names,
+ * at the pinned commit), the same field a biome manifest uses. An edition or
+ * the data root never asserts it. The manifest is bound into the index by
+ * `sourceManifestHash`, so the claim cannot drift from the source. Uniqueness
+ * across the index is the kernel's index schema's to grade.
+ *
+ * @param {unknown} sourceManifest the parsed source manifest
+ * @param {string} where names the manifest in a refusal
+ */
+export function sourceOwnedCapabilityDomains(sourceManifest, where) {
+  const domains = sourceManifest?.xema?.ownsCapabilityDomains;
+  if (domains === undefined) {return {};}
+  if (!Array.isArray(domains) || domains.length === 0) {
+    throw new Error(
+      `${where}: xema.ownsCapabilityDomains must be a non-empty array of capability domains; ` +
+        'omit it to own none',
+    );
+  }
+  for (const domain of domains) {
+    if (!isKernelCapabilityDomain(domain)) {
+      throw new Error(
+        `${where}: xema.ownsCapabilityDomains contains ${JSON.stringify(domain)}, ` +
+          'which is not a valid capability domain',
+      );
+    }
+  }
+  const sorted = [...domains].sort(compareStrings);
+  const repeated = sorted.find((domain, index) => sorted[index - 1] === domain);
+  if (repeated !== undefined) {
+    throw new Error(`${where}: xema.ownsCapabilityDomains names "${repeated}" more than once`);
+  }
+  return { ownsCapabilityDomains: sorted };
+}
+
 /** The (name, tier, declared class) a declaration and an index entry must agree on. */
 export function comparablePlatformService(entry) {
   return { name: entry.name, tier: entry.tier, ...declaredInstallationClass(entry) };