@xemahq/xema 0.41.0 → 0.42.0

package/edition/lib.mjs

@@ -20,6 +20,12 @@ import { readBiomeAuthorizationModuleAt } from './authorization-base.mjs';
 import {
   isAuthoritativeProductionBiomeSource,
 } from './connector-source-authority.mjs';
+import {
+  compareDispatchedEdges,
+  dispatchedEdgeIdentity,
+  isSupplementalEdge,
+  projectDispatchedTarget,
+} from './dispatched-runtime-components.mjs';
 import { assertKernelEditionProtocol } from './edition-protocol.mjs';
 import {
   kernelDistPath,
@@ -34,6 +40,7 @@ import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
 import {
   PRINCIPAL_PRIVILEGE_FIELDS,
   assertPrivilegesHavePrincipals,
+  componentInstalledOperationRequests,
   componentOperationRequirements,
   componentOptionalOperationRequirements,
   componentOrganizationSweepRequirements,
@@ -680,6 +687,64 @@ const kernelDistributionDist = () => kernelDistPath('distribution', 'index.js');
 // through. A sibling of the distribution dist, loaded beside it.
 const kernelProcessTopologyDist = () => kernelDistPath('process-topology', 'index.js');
 
+/** A composed-process subject, on a kernel that cannot write image-lock schemaVersion 4. */
+export class ComposedProcessNeedsLockV4Error extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ComposedProcessNeedsLockV4Error';
+  }
+}
+
+/** The image-lock revision of a kernel that predates `IMAGE_LOCK_WRITE_SCHEMA_VERSION` (edition protocol < v14). */
+const PRE_V14_IMAGE_LOCK_SCHEMA_VERSION = 3;
+
+/**
+ * Refuse a composed-process subject when the loaded kernel predates image-lock
+ * schemaVersion 4 (it exports no `IMAGE_LOCK_WRITE_SCHEMA_VERSION`): such a
+ * kernel has no `members[]`, so it cannot say which services the composed
+ * image carries. There is no fallback.
+ */
+export function assertKernelSealsComposedMembership(schemas, subjects, label) {
+  if (Number.isInteger(schemas.IMAGE_LOCK_WRITE_SCHEMA_VERSION)) {return;}
+  const composed = (subjects ?? []).find((subject) => subject.kind === 'composed-process');
+  if (composed === undefined) {return;}
+  throw new ComposedProcessNeedsLockV4Error(
+    `${label}: composed-process subject "${composed.id}" — a composed-process subject needs a kernel that ` +
+      'writes image-lock schemaVersion 4 (edition protocol >= v14); the loaded kernel ' +
+      `(${kernelRepoDir()}) exports no IMAGE_LOCK_WRITE_SCHEMA_VERSION`,
+  );
+}
+
+/**
+ * The READ side of the same rule, for a kernel before image-lock
+ * schemaVersion 4 (no `ImageLockSchemaVersion`): it reads only schemaVersion
+ * 3, which names no composed members, so a v3 lock carrying a composed-process
+ * subject cannot say which services run from it and is refused (worded as the
+ * kernel's own `LegacyComposedImageLockError`).
+ */
+export function assertLegacyLockHasNoComposedSubject(lock) {
+  const composed = (lock.subjects ?? []).find((subject) => subject.kind === 'composed-process');
+  if (composed === undefined) {return;}
+  throw new ComposedProcessNeedsLockV4Error(
+    `distribution "${lock.distributionId}": subjects "${composed.id}" is a schemaVersion ` +
+      `${String(lock.schemaVersion)} composed-process subject, which names no members: regenerate with a CLI ` +
+      'that writes image-lock schemaVersion 4, against a kernel at edition protocol >= v14',
+  );
+}
+
+/**
+ * The image-lock schemaVersion a writer emits for `subjects`: the loaded
+ * kernel's `IMAGE_LOCK_WRITE_SCHEMA_VERSION`. A kernel before edition protocol
+ * v14 exports none and writes only schemaVersion 3, which is allowed only when
+ * there is NO composed-process subject
+ * ({@link ComposedProcessNeedsLockV4Error} otherwise).
+ */
+export function imageLockWriteSchemaVersion(schemas, subjects, label = 'images.lock.json') {
+  assertKernelSealsComposedMembership(schemas, subjects, label);
+  const version = schemas.IMAGE_LOCK_WRITE_SCHEMA_VERSION;
+  return Number.isInteger(version) ? version : PRE_V14_IMAGE_LOCK_SCHEMA_VERSION;
+}
+
 /**
  * Dynamically import the BUILT kernel distribution schemas. The kernel package
  * is NOT linked into the repo-root node_modules (it lives in its own sub-
@@ -731,6 +796,8 @@ export async function loadKernelDistributionSchemas() {
     parseOciDigest,
     parseGitTreeId,
     parseImageLock,
+    IMAGE_LOCK_WRITE_SCHEMA_VERSION,
+    ImageLockSchemaVersion,
     parseImageProducerStatement,
     parseDistributionImagesStatement,
     parseImageDeliveryEntitlementStatement,
@@ -783,6 +850,8 @@ export async function loadKernelDistributionSchemas() {
     admitOperationGrants,
     admitOrganizationSweeps,
     contractRequiredServiceTargets,
+    admitInstalledOperationCeiling,
+    admitStoreWorkloadCeiling,
   } = mod;
   let topology;
   try {
@@ -880,6 +949,11 @@ export async function loadKernelDistributionSchemas() {
     typeof admitOperationGrants !== 'function' ||
     typeof admitOrganizationSweeps !== '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 distributionImagesPredicateLockRefusal !== 'function' ||
     typeof distributionLockDigest !== 'function' ||
     typeof imageDeliveryEntitlementRefusal !== 'function' ||
@@ -901,7 +975,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)/admitOperationGrants/admitOrganizationSweeps/` +
+        `deriveWorkflowSubjects/deriveTrustCeiling (>= 0.71.0)/admitOperationGrants/admitOrganizationSweeps/admitInstalledOperationCeiling/admitStoreWorkloadCeiling/` +
         `defaultTrustDomain/FIRST_PARTY_TRUST_DOMAIN/ProcessTrustPolicySchema/DistributionTrustPolicySchema/LockedStorePublisherSchema/` +
         `resolveFirstPartyCapabilityDomains/DistributionVisibility/` +
         `BiomeInstallPolicy/BiomeLaunchMode/ImageSourceHashAlgorithm/runtime-image enums — ` +
@@ -927,6 +1001,8 @@ export async function loadKernelDistributionSchemas() {
     parseOciDigest,
     parseGitTreeId,
     parseImageLock,
+    IMAGE_LOCK_WRITE_SCHEMA_VERSION,
+    ImageLockSchemaVersion,
     parseImageProducerStatement,
     parseDistributionImagesStatement,
     parseImageDeliveryEntitlementStatement,
@@ -986,6 +1062,8 @@ export async function loadKernelDistributionSchemas() {
     admitOperationGrants,
     admitOrganizationSweeps,
     contractRequiredServiceTargets,
+    admitInstalledOperationCeiling,
+    admitStoreWorkloadCeiling,
     distributionImagesPredicateLockRefusal,
     imageDeliveryEntitlementRefusal,
     producerWorkflowPinRefusal,
@@ -1617,7 +1695,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`, `requiresOrganizationSweeps`) is admitted for a lock workload
+  // A privilege (`requiresOperations`, `optionalOperations`, `requestsInstalledOperations`, `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
@@ -1668,6 +1746,10 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
   // (`optionalOperations`), keyed like `operationRequirements`. Declared
   // intent only: the seal grants, leaves ungranted or refuses each one.
   const optionalOperationRequirements = {};
+  // `component → the operations it asks to exercise for the installing
+  // organization` (`requestsInstalledOperations`), keyed like
+  // `operationRequirements`. Declared intent only: the lock admits the ceiling.
+  const installedOperationRequests = {};
   // `component → the organization sweeps it may hold`
   // (`requiresOrganizationSweeps`), keyed like `operationRequirements`.
   // Declared intent only: the seal admits or refuses each one.
@@ -1861,6 +1943,8 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
       if (operations !== null) {operationRequirements[name] = operations;}
       const optionalOperations = componentOptionalOperationRequirements(component, where);
       if (optionalOperations !== null) {optionalOperationRequirements[name] = optionalOperations;}
+      const installed = componentInstalledOperationRequests(component, where);
+      if (installed !== null) {installedOperationRequests[name] = installed;}
       const sweeps = componentOrganizationSweepRequirements(component, where);
       if (sweeps !== null) {organizationSweepRequirements[name] = sweeps;}
       const queues = componentWorkerTaskQueues(component, protocol, where);
@@ -2037,16 +2121,10 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
     ...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 },
-        ]),
+        .map((edge) => projectDispatchedTarget(id, edge.target))
+        .map((target) => [dispatchedEdgeIdentity(target), target]),
     ).values(),
-  ].sort(
-    (a, b) =>
-      compareStrings(a.biomeId, b.biomeId) ||
-      compareStrings(a.componentKey, b.componentKey),
-  );
+  ].sort(compareDispatchedEdges);
 
   // Optional server biomes a web biome can integrate with but does not require
   // (never cause an ORPHANED resolution). Carried separately from `requires`.
@@ -2311,6 +2389,17 @@ export async function manifestToIndexEntry({ raw, generatedIndex, rel, repo, pat
           ),
         }
       : {}),
+    // The operations each workload component asks to exercise for the
+    // installing organization; omitted when none declares any.
+    ...(Object.keys(installedOperationRequests).length > 0
+      ? {
+          installedOperationRequests: Object.fromEntries(
+            Object.entries(installedOperationRequests).sort(([a], [b]) =>
+              compareStrings(a, b),
+            ),
+          ),
+        }
+      : {}),
     // The organization sweeps each workload component may hold; omitted when
     // none declares any.
     ...(Object.keys(organizationSweepRequirements).length > 0
@@ -2795,10 +2884,12 @@ export function validateImmutableBiomeIndex(index) {
     }
     const dispatched = new Set();
     for (const edge of biome.dispatchesRuntimeComponents ?? []) {
-      const edgeKey = `${edge.biomeId}\0${edge.componentKey}`;
+      const edgeKey = dispatchedEdgeIdentity(projectDispatchedTarget(biome.id, edge));
       if (dispatched.has(edgeKey)) {
         throw new Error(
-          `biome "${biome.id}" dispatches runtime component "${edge.componentKey}" of biome "${edge.biomeId}" more than once`,
+          isSupplementalEdge(edge)
+            ? `biome "${biome.id}" dispatches ${edgeKey} more than once`
+            : `biome "${biome.id}" dispatches runtime component "${edge.componentKey}" of biome "${edge.biomeId}" more than once`,
         );
       }
       dispatched.add(edgeKey);
@@ -2918,8 +3009,16 @@ export function validateImmutableImageLock(lock, schemas) {
   if (!schemas) {
     throw new Error('trusted kernel distribution schemas are required');
   }
+  assertKernelSealsComposedMembership(schemas, lock.subjects, `distribution "${lock.distributionId}"`);
+  // The revisions the loaded kernel reads (`ImageLockSchemaVersion`: 3 without
+  // composed membership, 4 with it); a kernel before image-lock v4 reads only 3.
+  if (schemas.ImageLockSchemaVersion === undefined) {assertLegacyLockHasNoComposedSubject(lock);}
+  const readableVersions =
+    schemas.ImageLockSchemaVersion === undefined
+      ? [PRE_V14_IMAGE_LOCK_SCHEMA_VERSION]
+      : Object.values(schemas.ImageLockSchemaVersion).filter((version) => Number.isInteger(version));
   if (
-    lock.schemaVersion !== 3 ||
+    !readableVersions.includes(lock.schemaVersion) ||
     lock.sourceHashAlgorithm !== schemas.ImageSourceHashAlgorithm.ImageInputV2
   ) {
     throw new Error(

package/edition/operation-grant-admission.mjs

@@ -5,7 +5,9 @@
  * `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.
+ * a refused requirement is neither written nor sealed. The installed-operation
+ * ceiling (`requestsInstalledOperations`, carried as `installedOperationRequests`)
+ * and the edition's store-workload ceiling are admitted the same way.
  */
 
 /** Thrown when one or more declared operation requirements are not admitted. */
@@ -83,3 +85,65 @@ export function assertOrganizationSweepsAdmitted(schemas, lock) {
   }
   return grants;
 }
+
+/** Thrown when one or more requested installed operations are not admitted into the ceiling. */
+export class InstalledOperationCeilingAdmissionError 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 installed operation requests that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'InstalledOperationCeilingAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every installed-operation request of `lock` through the kernel
+ * (`admitInstalledOperationCeiling`), or throw
+ * {@link InstalledOperationCeilingAdmissionError} listing every refusal.
+ * Returns the admitted ceiling rows.
+ */
+export function assertInstalledOperationCeilingAdmitted(schemas, lock) {
+  const { ceilings, refusals } = schemas.admitInstalledOperationCeiling(lock);
+  if (refusals.length > 0) {
+    throw new InstalledOperationCeilingAdmissionError(lock.distributionId, refusals);
+  }
+  return ceilings;
+}
+
+/** Thrown when one or more domains of the edition's store-workload ceiling are not admitted. */
+export class StoreWorkloadCeilingAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, domain: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares a store-workload ceiling that is not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'StoreWorkloadCeilingAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit the store-workload ceiling of `lock` through the kernel
+ * (`admitStoreWorkloadCeiling`), or throw
+ * {@link StoreWorkloadCeilingAdmissionError} listing every refusal. Returns the
+ * resolved ceiling.
+ */
+export function assertStoreWorkloadCeilingAdmitted(schemas, lock) {
+  const { ceiling, refusals } = schemas.admitStoreWorkloadCeiling(lock);
+  if (refusals.length > 0) {
+    throw new StoreWorkloadCeilingAdmissionError(lock.distributionId, refusals);
+  }
+  return ceiling;
+}

package/edition/operation-requirements.mjs

@@ -81,6 +81,18 @@ export function componentOptionalOperationRequirements(component, where) {
   return declaredPrivilegeList(component, where, 'optionalOperations', OperationIdSchema, 'operation id');
 }
 
+/**
+ * The operations one workload component asks to exercise for the organization
+ * that installs its biome (`requestsInstalledOperations`), graded by the same
+ * operation-id grammar. Declared INTENT only; the lock admits the ceiling of
+ * the request (`admitInstalledOperationCeiling`), and an installed operation is
+ * never a deployment grant.
+ */
+export function componentInstalledOperationRequests(component, where) {
+  const { OperationIdSchema } = loadKernelPrivilegeGrammars();
+  return declaredPrivilegeList(component, where, 'requestsInstalledOperations', OperationIdSchema, 'operation id');
+}
+
 /**
  * The organization sweeps one workload component declares it may hold
  * (`requiresOrganizationSweeps`), each a member of the kernel's closed
@@ -96,7 +108,12 @@ export function componentOrganizationSweepRequirements(component, where) {
  * 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', 'optionalOperations', 'requiresOrganizationSweeps']);
+export const PRINCIPAL_PRIVILEGE_FIELDS = Object.freeze([
+  'requiresOperations',
+  'optionalOperations',
+  'requestsInstalledOperations',
+  'requiresOrganizationSweeps',
+]);
 
 /**
  * Thrown when a component that has no workload principal in the lock declares

package/edition/resolve-customer-edition.mjs

@@ -37,7 +37,7 @@ import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
 import { EditionLockFile } from './edition-constants.mjs';
 import { editionsRoot } from './edition-workspace.mjs';
 import { adoptCatalogueKernel } from './kernel-package.mjs';
-import { compareStrings, serializeJson, validateImmutableImageLock } from './lib.mjs';
+import { compareStrings, imageLockWriteSchemaVersion, serializeJson, validateImmutableImageLock } from './lib.mjs';
 import { pinnedSource, snapshotPinSource } from './pin-source.mjs';
 import { composeAuthorizationBase, composeManifest, resolveDistributionWithIndex, UnknownSelectionError } from './resolve-distribution.mjs';
 import { resolveImageRows } from './resolve-images.mjs';
@@ -238,13 +238,14 @@ export async function resolveCustomerImages({ id, catalogue, lock, composed, sch
   const seen = new Set(vendorSubjects.map(subjectKey));
   const clash = own.subjects.find((subject) => seen.has(subjectKey(subject)));
   if (clash !== undefined) {throw new Error(`the customer's own image ${clash.kind}:${clash.id} collides with a catalogue image of the same identity`);}
+  const mergedSubjects = [...vendorSubjects, ...own.subjects].sort(compareSubjects);
   const merged = validateImmutableImageLock(
     schemas.parseImageLock({
-      schemaVersion: 3,
+      schemaVersion: imageLockWriteSchemaVersion(schemas, mergedSubjects, `distribution "${id}"`),
       sourceHashAlgorithm: catalogue.images.sourceHashAlgorithm,
       distributionId: id,
       contractAuthority: catalogue.contractAuthority,
-      subjects: [...vendorSubjects, ...own.subjects].sort(compareSubjects),
+      subjects: mergedSubjects,
       platformServiceBindings: [...vendor.platformServiceBindings, ...own.platformServiceBindings].sort((a, b) => compareStrings(a.platformService, b.platformService)),
       webBiomes: [...vendor.webBiomes, ...own.webBiomes].sort((a, b) => compareStrings(a.biomeId, b.biomeId)),
     }),

package/edition/resolve-distribution.mjs

@@ -95,8 +95,10 @@ import {
   validateServiceDependencyOwnerParity,
 } from './lib.mjs';
 import {
+  assertInstalledOperationCeilingAdmitted,
   assertOperationGrantsAdmitted,
   assertOrganizationSweepsAdmitted,
+  assertStoreWorkloadCeilingAdmitted,
 } from './operation-grant-admission.mjs';
 import { PUBLISHED_PIN_SOURCE, pinnedSource } from './pin-source.mjs';
 import { verifiedPlatformServiceIndex } from './platform-service-ownership.mjs';
@@ -307,6 +309,7 @@ export function composeManifest(manifest, pinSource = PUBLISHED_PIN_SOURCE) {
     // Visibility is a RESTRICTION; the caller (which holds the kernel enum)
     // reduces the declarations.
     declaredVisibilities: manifest.visibility === undefined ? [] : [manifest.visibility],
+    storeWorkloadCeiling: manifest.storeWorkloadCeiling,
     declaredSourceNames: new Set(sources.map((source) => source.name)),
     declaredSources: sources.map((source) => pinnedSource(source, pinSource)),
     owner: manifest.owner,
@@ -1159,6 +1162,7 @@ export function resolveDistributionFromInputs(
     trustPolicy,
     trustCeiling,
     declaredVisibilities,
+    storeWorkloadCeiling,
     owner,
     leaf,
     // Absent on a selector-model composition — including every `composed` a
@@ -2047,6 +2051,13 @@ export function resolveDistributionFromInputs(
       Object.keys(e.optionalOperationRequirements).length > 0
         ? { optionalOperationRequirements: e.optionalOperationRequirements }
         : {}),
+      // The operations each workload component asks to exercise for the
+      // installing organization, forwarded verbatim; the lock admits their
+      // ceiling (`admitInstalledOperationCeiling`).
+      ...(e.installedOperationRequests !== undefined &&
+      Object.keys(e.installedOperationRequests).length > 0
+        ? { installedOperationRequests: e.installedOperationRequests }
+        : {}),
       // The organization sweeps each workload component may hold, forwarded
       // verbatim; the seal admits them (`admitOrganizationSweeps`).
       ...(e.organizationSweepRequirements !== undefined &&
@@ -2202,6 +2213,9 @@ export function resolveDistributionFromInputs(
   // last for the same reason: an edition without it carries exactly the bytes it
   // always did. Not in `inputHash`; the kernel lock schema validates it.
   if (composed?.storePublisherTrust !== undefined) {lock.storePublisherTrust = composed.storePublisherTrust;}
+  // The edition's store-workload ceiling — written ONLY when the edition
+  // declares one (the kernel refuses an empty list), carried unchanged.
+  if (storeWorkloadCeiling !== undefined) {lock.storeWorkloadCeiling = storeWorkloadCeiling;}
 
   // (7) Re-derive the ownership index through the KERNEL so the table this
   //     resolver emits is validated by the exact code every consumer will read
@@ -2221,6 +2235,8 @@ export function resolveDistributionFromInputs(
   //     never fails (the resolve and `edition check` both run through here).
   assertOperationGrantsAdmitted(schemas, parsed, { report: (line) => console.log(`[operations] ${line}`) });
   assertOrganizationSweepsAdmitted(schemas, parsed);
+  assertInstalledOperationCeilingAdmitted(schemas, parsed);
+  assertStoreWorkloadCeilingAdmitted(schemas, parsed);
   return validateImmutableDistributionLock(lock);
 }