@xemahq/xema 0.41.1 → 0.42.0

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);
 }
 

package/edition/resolve-images.mjs

@@ -61,6 +61,7 @@ import {
   compareStrings,
   hashImageBuildInputs,
   imageInputSourceHashAlgorithm,
+  imageLockWriteSchemaVersion,
   loadKernelDistributionSchemas,
   parseResolvedDistributionLock,
   readGitJsonAtCommit,
@@ -970,6 +971,13 @@ export function editionSourceIds(lock) {
  * caller can tell "this image's inputs are unknown" from any other refusal:
  * the carried set is evidence, and with none there is no owner to derive.
  */
+export class ComposedProcessWorkerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ComposedProcessWorkerError';
+  }
+}
+
 export class ComposedProcessInputsError extends Error {
   constructor(message) {
     super(message);
@@ -1009,16 +1017,31 @@ function composedProcessCarriage(structure, enums, repo, sourceCommit, locate) {
   const byBiome = new Map();
   for (const subject of structure.subjects) {
     if (subject.kind !== enums.RuntimeImageSubjectKind.Service || subject.repo !== repo) {continue;}
-    const servicePath = subjectServicePath(subject, sourceCommit, locate);
+    const { path: servicePath, componentKind } = subjectServiceSource(subject, sourceCommit, locate);
     for (const owner of subject.owners) {
       if (owner.kind !== enums.RuntimeImageOwnerKind.Biome) {continue;}
-      const row = byBiome.get(owner.biomeId) ?? { biomeId: owner.biomeId, carried: [], uncarried: [] };
-      (carried.has(servicePath) ? row.carried : row.uncarried).push(subject.id);
+      const row = byBiome.get(owner.biomeId) ??
+        { biomeId: owner.biomeId, carried: [], uncarried: [], carriedWorkers: [], packageDirs: {} };
+      if (!carried.has(servicePath)) {
+        row.uncarried.push(subject.id);
+      } else if (componentKind === 'worker') {
+        // A worker is never a member: it runs as its own Deployment.
+        row.carriedWorkers.push(subject.id);
+      } else {
+        row.carried.push(subject.id);
+        // The member's package directory IS the composed build's own input entry.
+        row.packageDirs[subject.id] = servicePath;
+      }
       byBiome.set(owner.biomeId, row);
     }
   }
   return [...byBiome.values()]
-    .map((row) => ({ ...row, carried: row.carried.sort(compareStrings), uncarried: row.uncarried.sort(compareStrings) }))
+    .map((row) => ({
+      ...row,
+      carried: row.carried.sort(compareStrings),
+      uncarried: row.uncarried.sort(compareStrings),
+      carriedWorkers: row.carriedWorkers.sort(compareStrings),
+    }))
     .sort((a, b) => compareStrings(a.biomeId, b.biomeId));
 }
 
@@ -1087,8 +1110,15 @@ export function readComposedProcessDeclarations(
  * resolve derive the same subject from the same declarations.
  *
  * Owners are the biomes the image CARRIES, derived from the composed build's
- * inputs at the sealed commit (`declaration.carriage`): the biomes all of whose
- * services are members, never every biome with a service in the repository.
+ * inputs at the sealed commit (`declaration.carriage`): every biome at least one
+ * of whose services is a member, never every biome with a service in the
+ * repository. The members leave the structure and are sealed on the subject
+ * as `members[{ service, packageDir }]` — the per-service membership truth: a
+ * service runs from the composed digest if and only if it is a row (owners
+ * never resolve a service). The edition carries the composed subject plus the
+ * services that are no row (the specials, which keep their own subjects even
+ * inside an owner biome), and nothing addresses a member's own image. A worker
+ * is never a row; an own-image worker the composed build carries is refused.
  */
 export function withComposedProcessSubjects(
   structure,
@@ -1099,6 +1129,9 @@ export function withComposedProcessSubjects(
 ) {
   if (declarations.length === 0) {return structure;}
   const subjects = new Map(structure.subjects.map((subject) => [subjectKey(subject), subject]));
+  // A biome's members run from ONE composed image: a biome owning two composed
+  // subjects would leave its pods two images to choose between.
+  const composedOwnerOf = new Map();
   for (const declaration of declarations) {
     const services = structure.subjects.filter(
       (subject) =>
@@ -1110,21 +1143,47 @@ export function withComposedProcessSubjects(
           'biomes the image carries — refusing to guess its owners',
       );
     }
-    // Owners are the biomes ALL of whose services the image carries. A biome
-    // with only some carried deploys dedicated, so it is no owner (and is
-    // named); a biome with none carried is simply not one.
+    // Owners are the biomes ANY of whose services the image carries. A biome
+    // with only some carried is an owner too; its services the image does not
+    // carry are specials and keep their own subjects (named here). A biome with
+    // none carried is simply not one.
     const biomeOwners = [];
+    const members = new Set();
+    const packageDirOf = new Map();
     for (const row of declaration.carriage) {
+      // A worker is never a member. One the composed build carries must run
+      // from a carried sibling's image (`workerImages`, declared in the
+      // manifest), never be dropped into the composed process or fall back.
+      for (const worker of row.carriedWorkers ?? []) {
+        throw new ComposedProcessWorkerError(
+          row.carried.length === 0
+            ? `composed-process "${declaration.repo}" carries worker "${worker}" of biome "${row.biomeId}", ` +
+                'and that biome has no carried service whose image it could run — a worker is never a ' +
+                'composed member; carry a service of its biome or take the worker out of the composed inputs'
+            : `composed-process "${declaration.repo}" carries worker "${worker}" of biome "${row.biomeId}" as ` +
+                'its own oci-image — a worker is never a composed member; declare it `artifact.kind: ' +
+                `shared-oci-image\` of a carried service (${row.carried.join(', ')}) or take it out of the composed inputs`,
+        );
+      }
       if (row.carried.length === 0) {continue;}
       if (row.uncarried.length > 0) {
         onNotice(
-          `composed-process "${declaration.repo}": biome "${row.biomeId}" is only partly carried ` +
+          `composed-process "${declaration.repo}": biome "${row.biomeId}" is partly carried ` +
             `(carried: ${row.carried.join(', ')}; not carried: ${row.uncarried.join(', ')}) — ` +
-            'it is not an owner and deploys dedicated',
+            'its uncarried services keep their own subjects',
         );
-        continue;
       }
+      const other = composedOwnerOf.get(row.biomeId);
+      if (other !== undefined) {
+        throw new Error(
+          `biome "${row.biomeId}" is carried by the composed-process images of both "${other}" and ` +
+            `"${declaration.repo}" — a biome is owned by exactly one composed subject`,
+        );
+      }
+      composedOwnerOf.set(row.biomeId, declaration.repo);
       biomeOwners.push({ kind: enums.RuntimeImageOwnerKind.Biome, biomeId: row.biomeId });
+      for (const id of row.carried) {members.add(id);}
+      for (const [id, packageDir] of Object.entries(row.packageDirs ?? {})) {packageDirOf.set(id, packageDir);}
     }
     if (biomeOwners.length === 0) {
       throw new Error(
@@ -1162,6 +1221,43 @@ export function withComposedProcessSubjects(
           `(${[...namespaces].join(', ')}) — a composed image of one build has one`,
       );
     }
+    // A MEMBER reaches its pods through this one subject (every member runs as a
+    // group-of-one of the composed image), so it carries no subject of its own:
+    // no `<imageRef>:<contentHash>` of its own is probed, verified or sealed. A
+    // member is a service of this build the composed build's inputs carry
+    // (`declaration.carriage`), every owner of which is a biome owning the
+    // composed image. Any other service (not carried, or owned by anything but
+    // a biome, e.g. shared with a platform service) keeps its own.
+    const composedOwners = new Set(biomeOwners.map((owner) => owner.biomeId));
+    const memberRows = [];
+    for (const subject of services) {
+      if (
+        members.has(subject.id) &&
+        subject.owners.length > 0 &&
+        subject.owners.every(
+          (owner) => owner.kind === enums.RuntimeImageOwnerKind.Biome && composedOwners.has(owner.biomeId),
+        )
+      ) {
+        subjects.delete(subjectKey(subject));
+        const packageDir = packageDirOf.get(subject.id);
+        if (packageDir === undefined) {
+          throw new ComposedProcessInputsError(
+            `composed-process "${declaration.repo}": member "${subject.id}" has no package directory in ` +
+              'the composed build inputs — its shared-image workers would have nowhere to run from',
+          );
+        }
+        memberRows.push({ service: subject.id, packageDir });
+      }
+    }
+    if (memberRows.length === 0) {
+      throw new ComposedProcessInputsError(
+        `composed-process "${declaration.repo}" has no member: every service its build carries ` +
+          `(${[...members].sort(compareStrings).join(', ')}) is also owned by something other than a biome ` +
+          'it owns (e.g. a platform service), so each keeps its own subject — a composed image with no ' +
+          'member runs nothing; take it out of the edition or carry a biome-owned service',
+      );
+    }
+    memberRows.sort((a, b) => compareStrings(a.service, b.service));
     const id = composedProcessSubjectId(declaration.sourceId);
     addSubject(subjects, {
       kind: enums.RuntimeImageSubjectKind.ComposedProcess,
@@ -1174,6 +1270,7 @@ export function withComposedProcessSubjects(
       sourceManifestPath: declaration.sourceManifestPath,
       requiredPlatforms,
       owners: biomeOwners,
+      members: memberRows,
     });
   }
   return {
@@ -1275,11 +1372,21 @@ function sourceCommitMap(structure, locate = FIRST_PARTY_TREES) {
  * service directory to hash the SAME build-input closure the lock names.
  */
 export function subjectServicePath(subject, sourceCommit, locate = FIRST_PARTY_TREES) {
+  return subjectServiceSource(subject, sourceCommit, locate).path;
+}
+
+/**
+ * The repository-relative source directory of a subject and the kind of the
+ * manifest component it is built from (`worker` for a worker component,
+ * `service` otherwise — a legacy `ships.apis[]` entry or a subject with its own
+ * source manifest is not a worker).
+ */
+function subjectServiceSource(subject, sourceCommit, locate = FIRST_PARTY_TREES) {
   const { dir: repoDirectory, base } = locate(subject.repo);
   const toRepoRelative = (absolute) =>
     relative(repoDirectory, absolute).split(sep).join('/') || '.';
   if (subject.sourceManifestPath) {
-    return toRepoRelative(join(base, subject.path));
+    return { path: toRepoRelative(join(base, subject.path)), componentKind: 'service' };
   }
   const biomePath = toRepoRelative(join(base, subject.path));
   const manifestPath =
@@ -1317,6 +1424,7 @@ export function subjectServicePath(subject, sourceCommit, locate = FIRST_PARTY_T
     );
   }
   let servicePath;
+  let componentKind = 'service';
   if (v4ServiceComponents.length > 0) {
     // A SERVICE is identified by `protocol.serviceName`; a WORKER has no
     // service protocol and is identified by its component `key`. Matching only
@@ -1340,6 +1448,7 @@ export function subjectServicePath(subject, sourceCommit, locate = FIRST_PARTY_T
       );
     }
     servicePath = component.artifact.path;
+    componentKind = component.kind;
   } else {
     if (legacyApis.length === 0) {
       throw new Error(
@@ -1357,7 +1466,7 @@ export function subjectServicePath(subject, sourceCommit, locate = FIRST_PARTY_T
     }
     servicePath = api.path;
   }
-  return toRepoRelative(join(base, subject.path, servicePath));
+  return { path: toRepoRelative(join(base, subject.path, servicePath)), componentKind };
 }
 
 function assertSourceManifestParity(structure, commitByRepo, locate = FIRST_PARTY_TREES) {
@@ -1815,7 +1924,7 @@ export async function resolveImages(id, { inputs, lock, onSubjectHashed } = {})
   const schemas = await loadKernelDistributionSchemas();
   const imageLock = validateImmutableImageLock(
     schemas.parseImageLock({
-      schemaVersion: 3,
+      schemaVersion: imageLockWriteSchemaVersion(schemas, subjects, `distribution "${id}"`),
       sourceHashAlgorithm: schemas.ImageSourceHashAlgorithm.ImageInputV2,
       distributionId: id,
       contractAuthority,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -49,12 +49,12 @@
     "@nestjs/common": "^11.1.18",
     "@nestjs/core": "^11.1.18",
     "@nestjs/platform-express": "^11.1.28",
-    "@xemahq/biome-sdk": "^18.1.0",
+    "@xemahq/biome-sdk": "^22.0.0",
     "@xemahq/biome-supply-chain": "^0.5.0",
     "@xemahq/distribution-source-hash": "^0.2.2",
     "@xemahq/dsl": "^0.24.0",
     "@xemahq/identity-client": "^0.16.0",
-    "@xemahq/contracts": "^0.83.0",
+    "@xemahq/contracts": "^0.94.0",
     "@xemahq/kernel-state-runtime": "^0.8.0",
     "@xemahq/license-verifier": "^0.2.0",
     "@xemahq/service-registry-nest": "^0.12.2",
@@ -92,6 +92,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:7e8af916b8cd5c8de331d7e274a7022071e6b6ac0d9d54042c2e55461ad46bab"
+    "sourceDigest": "sha256:ae545509930a5b6f1215c413f3e7121b15a29d5fd3e14ab373f0910ceaa9063d"
   }
 }