@xemahq/xema 0.30.0 → 0.31.0

package/edition/resolve-distribution.mjs

@@ -74,6 +74,7 @@ import {
   sealEditionAuthorizationBase,
   writeAuthorizationLock,
 } from './authorization-base.mjs';
+import { resolveDispatchedRuntimeComponents } from './dispatched-runtime-components.mjs';
 import { fleetChartSetLockPath, writeEditionChartSet } from './edition-chart-set.mjs';
 import { workspaceSection } from './edition-config.mjs';
 import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule, kernelPackageDir, platformServiceIndexPath } from './edition-workspace.mjs';
@@ -92,7 +93,12 @@ import {
   validateImmutableDistributionLock,
   validateServiceDependencyOwnerParity,
 } from './lib.mjs';
+import {
+  assertOperationGrantsAdmitted,
+  assertOrganizationSweepsAdmitted,
+} from './operation-grant-admission.mjs';
 import { PUBLISHED_PIN_SOURCE, pinnedSource } from './pin-source.mjs';
+import { verifiedPlatformServiceIndex } from './platform-service-ownership.mjs';
 import { closureBiomeFacts } from './positive-closure.mjs';
 import { assertReleaseContent, assertReleaseEditionTree } from './release-channel-guard.mjs';
 import { commandFor } from './remedy-command.mjs';
@@ -1745,6 +1751,13 @@ export function resolveDistributionFromInputs(
   // shipped provider. See `nexusBinder`.
   const nexusBindings = nexusBinder(id, [...selected.values()], schemas);
 
+  // (5d) Dispatched runtime components — every `runtime-image` edge of a
+  // shipped biome must resolve to a runtime component of a biome in the index.
+  // The target biome is not rostered (it enters no `biomes[]`, `requires` or
+  // install set); the image plane adds its image row. Resolved here so an
+  // unresolvable edge refuses the edition, not only its image lock.
+  resolveDispatchedRuntimeComponents(`distribution "${id}"`, [...selected.values()], index);
+
   // (6) Build the lock — sort by (tier order, id, target, repo).
   const biomes = [...selected.values()]
     .map((e) => ({
@@ -1822,7 +1835,7 @@ export function resolveDistributionFromInputs(
       // starts. Optional-in-the-new-schema and absent-from-the-old are different
       // facts, and only the second one governs a deployed image.
       //
-      // MEASURED 2026-09-17. Emitting it took presenca-dev's three
+      // MEASURED 2026-09-17. Emitting it took a customer environment's three
       // distribution-lock consumers — biome-host-api, capability-registry-api,
       // xema-capability-router — into CrashLoopBackOff on a sealed, signed,
       // platform-verified edition. The seal was green; the lock was unparseable
@@ -1840,7 +1853,7 @@ export function resolveDistributionFromInputs(
       // somebody raised the pin. Re-measured against the refs, not the comment:
       //   xema-base origin/main    `'@xemahq/contracts': ^0.15.0`
       //   xema-base origin/develop `'@xemahq/contracts': ^0.16.0`
-      //   xema-base 2ef54a1 (the `sourceCommit` presenca-dev's images.lock.json
+      //   xema-base 2ef54a1 (the `sourceCommit` a customer environment's images.lock.json
       //     names) resolves `@xemahq/contracts@0.15.0`, sole resolution.
       // and against the published tarballs, two-sided, `npm pack` + grep:
       //   0.9.2 -> 0 files name this key; 0.12.0 / 0.15.0 / 0.17.0 -> 2 each.
@@ -1848,7 +1861,7 @@ export function resolveDistributionFromInputs(
       // past the deletion condition this comment states below.
       //
       // WHAT ACTUALLY BLOCKS IT IS THE ROLLOUT, and a pin is not a rollout.
-      // Measured 2026-09-19 inside the running containers in `presenca-dev`:
+      // Measured 2026-09-19 inside the running containers in `a customer environment`:
       //   `cat /app/node_modules/@xemahq/contracts/package.json` -> "0.9.2",
       //   one resolution each (`ls -d /app/node_modules/.pnpm/@xemahq+contracts@*`),
       //   and `dist/distribution/lib/distribution-lock.js` carries `.strict()`
@@ -1857,7 +1870,7 @@ export function resolveDistributionFromInputs(
       //   POSITIVE CONTROL, same tree, same probe: `grep -rl distribution` -> 64.
       //   So the zero is an absence, not a broken probe.
       // And the three running digests are NOT the digests
-      // `deployments/presenca-dev/images.lock.json` designates — the cluster is
+      // `deployments/<customer>-dev/images.lock.json` designates — the cluster is
       // roughly one build behind its own lock, which is why a pin raised on the
       // branch has not reached the parser.
       //
@@ -1875,7 +1888,7 @@ export function resolveDistributionFromInputs(
       // answers this. For each of biome-host-api, capability-registry-api and
       // xema-capability-router:
       //
-      //   kubectl -n presenca-dev exec deploy/<svc> -- \
+      //   kubectl -n <customer>-dev exec deploy/<svc> -- \
       //     cat /app/node_modules/@xemahq/contracts/package.json
       //
       // must report >= 0.12.0 for ALL THREE. When it does, in ONE change:
@@ -1884,7 +1897,7 @@ export function resolveDistributionFromInputs(
       //      the withholding and will correctly go red;
       //   3. re-seal the affected locks;
       //   4. delete the `postgres.extensions` BRIDGE blocks from
-      //      `deployments/presenca-dev/secret-inputs.yaml` and
+      //      `deployments/<customer>-dev/secret-inputs.yaml` and
       //      `deployments/owl-xema-prod/secret-inputs.yaml` in xema-deploy —
       //      the deploy plane REFUSES that bridge by name the moment any biome
       //      in the lock carries this key, so 3 and 4 cannot be separated.
@@ -2000,6 +2013,20 @@ export function resolveDistributionFromInputs(
       // throws), so an entry without the key is one whose manifest declares
       // no such worker.
       workerImages: e.workerImages ?? {},
+      // The service-to-service operations each workload component requires,
+      // forwarded verbatim from the index (already sorted and non-empty). The
+      // seal admits them (`admitOperationGrants`). Omitted when none, so an
+      // edition declaring none is byte-identical.
+      ...(e.operationRequirements !== undefined &&
+      Object.keys(e.operationRequirements).length > 0
+        ? { operationRequirements: e.operationRequirements }
+        : {}),
+      // The organization sweeps each workload component may hold, forwarded
+      // verbatim; the seal admits them (`admitOrganizationSweeps`).
+      ...(e.organizationSweepRequirements !== undefined &&
+      Object.keys(e.organizationSweepRequirements).length > 0
+        ? { organizationSweepRequirements: e.organizationSweepRequirements }
+        : {}),
       // --- Catalog projection (consumed by biome-host's DistributionCatalogSource) ---
       // Forwarded verbatim from the index so the lock is the SELF-CONTAINED
       // single source of truth for the biome catalog: biome-host builds the
@@ -2069,7 +2096,15 @@ export function resolveDistributionFromInputs(
       // widening it. That refusal is the right posture and this is the right
       // side of it.
       const { installationClass: _installationClass, ...locked } = service;
-      return { ...locked, source };
+      return {
+        ...locked,
+        // Copied verbatim from the index entry (sorted, unique, non-empty by
+        // its schema); the grant admission reads it from the lock.
+        ...(source.ownsCapabilityDomains === undefined
+          ? {}
+          : { ownsCapabilityDomains: source.ownsCapabilityDomains }),
+        source,
+      };
     })
     .sort((a, b) => {
       const ta = TIER_WITH_EDGE.indexOf(a.tier);
@@ -2149,7 +2184,11 @@ export function resolveDistributionFromInputs(
   schemas.resolveFirstPartyCapabilityDomains(lock);
 
   // (8) Validate against the BUILT kernel schema — fail-fast.
-  schemas.parseUnsealedDistributionLock(lock);
+  const parsed = schemas.parseUnsealedDistributionLock(lock);
+  // (9) Admit every declared service-to-service operation requirement; a
+  //     refusal throws, so a lock with one is never returned to be written.
+  assertOperationGrantsAdmitted(schemas, parsed);
+  assertOrganizationSweepsAdmitted(schemas, parsed);
   return validateImmutableDistributionLock(lock);
 }
 
@@ -2176,22 +2215,33 @@ export async function resolveDistribution(id) {
  * `materialize` is the walk's one network seam, injectable for the contract
  * suite exactly as it is on `walkDeclaredSources`.
  */
-export async function resolveDistributionWithIndex(id, { materialize, inputs } = {}) {
+export async function resolveDistributionWithIndex(id, { materialize, inputs, readManifest } = {}) {
   const schemas = await loadKernelDistributionSchemas();
+  // The manifest is composed FIRST, because it is what declares the sources and
+  // what refuses a malformed definition before any other work. The walk then
+  // runs once per resolve and its entries are merged into a per-resolution
+  // index — never into `biome-index.json`, which is the platform's and is read
+  // by every edition.
+  const composed = inputs?.composed ?? composeEdition(schemas.parseDistribution, id);
   // THE RELEASE READS THESE FROM DISK; A DEVELOP SNAPSHOT INJECTS THEM
   // (`develop-snapshot-inputs.mjs`). Either way they pass through the one
   // validation below, so there is a single resolve path and two sources.
-  const platformServiceIndex =
+  const claimedPlatformServiceIndex =
     inputs?.platformServiceIndex ?? readPlatformServiceIndex(schemas.parsePlatformServiceSourceIndex);
+  // OWNERSHIP IS THE SERVICE'S OWN STATEMENT: each entry's capability domains
+  // are re-derived from its pinned source manifest (hash-verified), so a
+  // hand-edited index cannot move where grants land. Only the customer resolve
+  // sets `sourcesAvailable: false` -- it has no vendor checkouts and trusts the
+  // signed catalogue, which `buildCatalogue` verified where it was produced.
+  // Any other caller without the sources is refused, never skipped.
+  const platformServiceIndex =
+    inputs?.sourcesAvailable === false
+      ? claimedPlatformServiceIndex
+      : verifiedPlatformServiceIndex(claimedPlatformServiceIndex, { readManifest });
   const platformIndex = validateServiceDependencyOwnerParity(
     validateImmutableBiomeIndex(inputs?.biomeIndex ?? readBiomeIndex()),
     platformServiceIndex,
   );
-  // The manifest is composed FIRST, because it is what declares the sources. The
-  // walk then runs once per resolve and its entries are merged into a
-  // per-resolution index — never into `biome-index.json`, which is the
-  // platform's and is read by every edition.
-  const composed = inputs?.composed ?? composeEdition(schemas.parseDistribution, id);
   const { entries, sourceRecords } = await walkDeclaredSources({
     sources: composed.declaredSources,
     ...(materialize === undefined ? {} : { materialize }),

package/edition/resolve-images.mjs

@@ -36,6 +36,7 @@ import { execFileSync } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 
+import { resolveDispatchedRuntimeComponents } from './dispatched-runtime-components.mjs';
 import {
   assertCanonicalDistributionId,
   distributionOutputPath,
@@ -281,7 +282,7 @@ export function resolveDistributionRequiredPlatforms(schemas, id) {
  * the fully-qualified `imageRef`. It cannot travel in the lock to reach the
  * resolver — `DistributionLockSchema` is `.strict()` and learned that key only
  * in `@xemahq/contracts` 0.10.0, so a pinned image resolving `^0.9.x` refuses
- * the whole lock at boot. Persisting it took presenca-dev's three lock
+ * the whole lock at boot. Persisting it took a customer environment's three lock
  * consumers into CrashLoopBackOff on 2026-09-17.
  *
  * So the producer reads its OWN declaration, and `requiredPlatforms` one
@@ -396,8 +397,11 @@ function missingArtifactDependencyMessage(lock, serviceName, binding, biomeIndex
  * refuse. What DOES refuse is a SELECTED service whose declared artifact
  * dependency is absent from the closure (see `missingArtifactDependencyMessage`).
  *
- * `options.biomeIndex` is optional and used ONLY to name, in a refusal, which
- * biome declares the missing artifact. It never changes a resolved roster.
+ * `options.biomeIndex` is the first-party biome index. It names, in a refusal,
+ * which biome declares a missing artifact, and it carries each rostered biome's
+ * `dispatchesRuntimeComponents`: the runtime components that biome launches,
+ * whose images enter this roster as runtime-component rows although their
+ * biomes are not rostered (see `dispatched-runtime-components.mjs`).
  */
 export function resolveImageStructure(
   lock,
@@ -414,6 +418,12 @@ export function resolveImageStructure(
         `and there is no default; a silent default is the bug this replaced`,
     );
   }
+  if (!Array.isArray(biomeIndex)) {
+    throw new Error(
+      `distribution "${lock.distributionId}" resolved its images without the biome index — the index carries ` +
+        'the runtime components a rostered biome dispatches, so a roster without it can omit images',
+    );
+  }
   const subjects = new Map();
   const webBiomes = [];
   const platformServiceBindings = [];
@@ -505,7 +515,7 @@ export function resolveImageStructure(
       // is `.strict()` and learned the key only in 0.10.0.
       //
       // Removing it from the lock WITHOUT moving this read is what composed
-      // `<customer-registry>/pai-core-api` instead of `<customer-registry>/presenca-pai-core-api`:
+      // `<customer-registry>/pai-core-api` instead of `<customer-registry>/<customer>-pai-core-api`:
       // the `?? ''` swallowed the absence, so an unqualified name in a shared
       // organisation namespace resolved silently. That is worse than a 404 —
       // the first collision overwrites another product's tags.
@@ -604,6 +614,57 @@ export function resolveImageStructure(
     }
   }
 
+  // Runtime components a rostered biome DISPATCHES enter the roster as
+  // runtime-component rows built from the TARGET biome's index entry, at its
+  // repository pin, exactly like a rostered biome's own runtime component. The
+  // owner is the rostered biome that dispatches it: the selection that brings
+  // the image into this edition. The target biome stays unrostered.
+  //
+  // A rostered biome's edges are read from ITS index entry, which must describe
+  // the very biome the lock pins; one from a declared source is refused at
+  // distribution resolve if it dispatches, and the first-party index carries
+  // none, so it is not looked up here.
+  const dispatchers = lock.biomes
+    .filter((biome) => biome.source === undefined && biome.target === 'server')
+    .map((biome) => {
+      const entries = biomeIndex.filter(
+        (entry) =>
+          entry.id === biome.id &&
+          entry.target === biome.target &&
+          entry.repo === biome.repo &&
+          entry.source === undefined,
+      );
+      if (entries.length !== 1 || entries[0].sourceManifestHash !== biome.sourceManifestHash) {
+        throw new Error(
+          `distribution "${lock.distributionId}" biome "${biome.id}" (${biome.repo}, ${biome.sourceManifestHash}) ` +
+            `has ${entries.length === 1 ? 'a stale' : `${entries.length}`} biome index ${entries.length === 1 ? 'entry' : 'entries'}, ` +
+            'so the runtime components it dispatches cannot be read — re-resolve the edition from the current index',
+        );
+      }
+      return entries[0];
+    });
+  for (const dispatched of resolveDispatchedRuntimeComponents(
+    `distribution "${lock.distributionId}"`,
+    dispatchers,
+    biomeIndex,
+  )) {
+    const { target } = dispatched;
+    addSubject(subjects, {
+      kind: enums.RuntimeImageSubjectKind.RuntimeComponent,
+      id: dispatched.image,
+      imageRef: imageRefForSubject(dispatched.image, firstPartyImageRegistry(), ''),
+      repo: target.repo,
+      path: target.path,
+      sourceCommit: requireRepositoryPin(target.repo).sourceCommit,
+      sourceManifestHash: target.sourceManifestHash,
+      requiredPlatforms,
+      owners: dispatched.consumers.map((biomeId) => ({
+        kind: enums.RuntimeImageOwnerKind.Biome,
+        biomeId,
+      })),
+    });
+  }
+
   const runtimeBindings = new Map(
     runtimeSourceIndex.platformServiceBindings.map((binding) => [
       binding.platformService,

package/edition/seal-image-digests.mjs

@@ -703,7 +703,7 @@ async function main() {
   // `DistributionLockSchema` is `.strict()` — so a key the plane knows and a
   // pinned repository does not makes the whole artifact unreadable AT BOOT.
   // That is not hypothetical: on 2026-09-17 `imageNamePrefix` did exactly this
-  // to three presenca-dev services at once, and the edition had sealed,
+  // to three a customer environment services at once, and the edition had sealed,
   // published and installed perfectly first.
   //
   // It is asked of every pinned repository that SHIPS AN IMAGE INTO THIS

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
     "directory": "apps/xema-cli"
   },
   "license": "Apache-2.0",
-  "description": "Xema OS global CLI (plan v4.3 §6 Phase J). Single binary day-0 onboarding: `npm i -g @xemahq/xema && xema dev` boots the whole stack; `xema biome scaffold` / `install` / `publish` / `lint` author and ship biomes; `xema run <capability>` invokes through the local capability-router. Multi-platform: works without pnpm or any monorepo clone.",
+  "description": "Xema global CLI. Single binary day-0 onboarding: `npm i -g @xemahq/xema && xema dev` boots the whole stack; `xema biome scaffold` / `install` / `publish` / `lint` author and ship biomes; `xema run <capability>` invokes through the local capability-router. Multi-platform: works without pnpm or any monorepo clone.",
   "type": "commonjs",
   "main": "dist/cli.js",
   "exports": {
@@ -54,7 +54,7 @@
     "@xemahq/distribution-source-hash": "^0.3.0",
     "@xemahq/dsl": "^0.23.0",
     "@xemahq/identity-client": "^0.16.0",
-    "@xemahq/contracts": "^0.78.0",
+    "@xemahq/contracts": "^0.80.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:d594a2838a0fbee09de46b9b6637afd9f9437a2989a2bfe30f2336ddc20f0523"
+    "sourceDigest": "sha256:2fc7a76e728752cf14eeb410921fb5c89cbffc9c3c398116a3c37dcd740587ea"
   }
 }