@xemahq/xema 0.41.0 → 0.42.0

package/edition/resolve-images.mjs

@@ -40,7 +40,10 @@ import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { assertBuildLedgerComplete } from './build-ledger-completeness.mjs';
 import { BUILD_LEDGER_FILE, readBuildLedger } from './build-ledger.mjs';
 import { CROSS_REPO_BUILD_INPUTS_PATH, crossRepoInputKey, resolveCrossRepoVendoredInputs } from './cross-repo-build-inputs.mjs';
-import { resolveDispatchedRuntimeComponents } from './dispatched-runtime-components.mjs';
+import {
+  resolveDispatchedRuntimeComponents,
+  UndeclaredSupplementalRuntimeComponentError,
+} from './dispatched-runtime-components.mjs';
 import {
   assertCanonicalDistributionId,
   distributionOutputPath,
@@ -58,6 +61,7 @@ import {
   compareStrings,
   hashImageBuildInputs,
   imageInputSourceHashAlgorithm,
+  imageLockWriteSchemaVersion,
   loadKernelDistributionSchemas,
   parseResolvedDistributionLock,
   readGitJsonAtCommit,
@@ -681,6 +685,28 @@ export function resolveImageStructure(
     dispatchers,
     biomeIndex,
   )) {
+    if (dispatched.supplementalRuntimeComponentId !== undefined) {
+      // THE REFUSAL: a dispatched supplemental runtime component must be one the
+      // runtime image source index declares as a runtime-component subject.
+      // Every image lock is produced here, so this is the one place it is checked.
+      const declared = runtimeSourceIndex.supplementalSubjects.find(
+        (subject) =>
+          subject.kind === enums.RuntimeImageSubjectKind.RuntimeComponent &&
+          subject.id === dispatched.supplementalRuntimeComponentId,
+      );
+      if (declared === undefined) {
+        throw new UndeclaredSupplementalRuntimeComponentError(
+          dispatched.supplementalRuntimeComponentId,
+          dispatched.consumers,
+          `distribution "${lock.distributionId}"`,
+        );
+      }
+      addSupplementalSubject(
+        declared,
+        dispatched.consumers.map((biomeId) => ({ kind: enums.RuntimeImageOwnerKind.Biome, biomeId })),
+      );
+      continue;
+    }
     const { target } = dispatched;
     addSubject(subjects, {
       kind: enums.RuntimeImageSubjectKind.RuntimeComponent,
@@ -717,6 +743,16 @@ export function resolveImageStructure(
   const boundSubjects = new Set(
     runtimeSourceIndex.platformServiceBindings.map((binding) => bindingKey(binding)),
   );
+  // A biome's `supplemental:<id>` dispatch edge also carries the subject: the
+  // catalogue check reads the whole first-party index, not this roster, so a
+  // subject reached only by a dispatch is not "unreachable" in any edition.
+  const dispatchedSubjects = new Set(
+    biomeIndex
+      .filter((entry) => entry.source === undefined)
+      .flatMap((entry) => entry.dispatchesRuntimeComponents ?? [])
+      .filter((edge) => edge.supplementalRuntimeComponentId !== undefined)
+      .map((edge) => `${enums.RuntimeImageSubjectKind.RuntimeComponent}\0${edge.supplementalRuntimeComponentId}`),
+  );
   const launchers = new Map(
     supplementalSources
       .filter((source) => source.launchedBy !== undefined)
@@ -733,11 +769,11 @@ export function resolveImageStructure(
   for (const [key, supplemental] of supplementalSubjects) {
     const launcher = launchers.get(key);
     if (launcher === undefined) {
-      if (!boundSubjects.has(key)) {
+      if (!boundSubjects.has(key) && !dispatchedSubjects.has(key)) {
         throw new Error(
-          `supplemental subject "${supplemental.kind}:${supplemental.id}" has neither a launchedBy nor a ` +
-            'platform-service binding, so no edition could ever carry it — declare what launches it ' +
-            '(runtimeImageSources.supplementalSources[].launchedBy) or bind it to a platform service',
+          `supplemental subject "${supplemental.kind}:${supplemental.id}" has neither a launchedBy, a ` +
+            'platform-service binding nor a biome dispatching it, so no edition could ever carry it — declare what launches it ' +
+            '(runtimeImageSources.supplementalSources[].launchedBy), bind it to a platform service or dispatch it from a biome',
         );
       }
       continue;
@@ -935,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);
@@ -974,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));
 }
 
@@ -1052,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,
@@ -1064,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) =>
@@ -1075,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',
+        );
+      }
+      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`,
         );
-        continue;
       }
+      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(
@@ -1127,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,
@@ -1139,6 +1270,7 @@ export function withComposedProcessSubjects(
       sourceManifestPath: declaration.sourceManifestPath,
       requiredPlatforms,
       owners: biomeOwners,
+      members: memberRows,
     });
   }
   return {
@@ -1240,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 =
@@ -1282,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
@@ -1305,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(
@@ -1322,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) {
@@ -1780,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.0",
+  "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:322929ee2999d155d5d612f17bb786adef52f44c46cee82b9bc9b11ecc792758"
+    "sourceDigest": "sha256:ae545509930a5b6f1215c413f3e7121b15a29d5fd3e14ab373f0910ceaa9063d"
   }
 }