@xemahq/xema 0.29.1 → 0.31.0

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

@@ -112,18 +112,20 @@
 import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest, lockMountsAdapters } from './adapter-bundled-versions.mjs';
 import { sealLock, verifyBiomeContentHashes } from './biome-content.mjs';
 import { fetchCatalogue } from './catalogue-fetch.mjs';
 import { readCataloguePin } from './catalogue-pin.mjs';
 import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG } from './customer-flags.mjs';
 import { EditionChannel } from './edition-constants.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
 import {
   assertCoordinatesFinal,
   collectFleetPlatformRequirements,
   isNotFinalYet,
   readFleetImageLocks,
 } from './fleet-coordinate-finality.mjs';
+import { adoptCatalogueKernel } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
 import { assertPlatformCanParseLock } from './platform-lock-readability.mjs';
 import { assertReleaseEditionTree } from './release-channel-guard.mjs';
@@ -138,7 +140,8 @@ import {
 if (isEntryModule(import.meta.url)) {
   // The customer form (it names --definition) reads exactly these roots - the data root (the vendor's
   // runtime-image-source-index.json), the editions root, the sources root (the readability check of the
-  // vendor repositories), the kernel and the cache (external source trees) - and refuses any other.
+  // vendor repositories) and the cache (external source trees, and the catalogue's kernel from npm) - and
+  // refuses any other, the kernel root included. A vendor seal takes the kernel root too.
   let namesDefinition;
   try {
     namesDefinition = parseSealArgs(process.argv.slice(2)).catalogueFlags.has(DEFINITION_FLAG);
@@ -147,7 +150,9 @@ if (isEntryModule(import.meta.url)) {
     process.exit(1);
   }
   configureEditionWorkspaceFromProcess(
-    [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache],
+    namesDefinition
+      ? [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Cache]
+      : [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache],
     { refuseOthers: namesDefinition },
   );
 }
@@ -479,7 +484,7 @@ function replaceLocksTogether(documents) {
  * can leave (images sealed, distribution unsealed) is refused by every reader of
  * a sealed edition.
  */
-export async function sealEditionLocks({ distributionId, root, digests = new Map(), check = false, label = 'dist:seal-digests', vendoredCommit, catalogue, catalogueDigest }) {
+export async function sealEditionLocks({ distributionId, root, digests = new Map(), check = false, label = 'dist:seal-digests', vendoredCommit, catalogue, catalogueDigest, fetchManifest = fetchRegistryManifest }) {
   const schemas = await loadKernelDistributionSchemas();
   const lockPath = join(root, distributionId, 'distribution.lock.json');
   const imagesPath = join(root, distributionId, 'images.lock.json');
@@ -505,6 +510,11 @@ export async function sealEditionLocks({ distributionId, root, digests = new Map
   const imageLock = schemas.parseImageLock(rawImages);
   const pinned = vendoredCommit ?? ((repo) => createPinnedSourceAuthority({ pins: committedRepositoryPins() }).vendoredSourceCommitForRepository(repo));
   const lockDocument = raw !== null && typeof raw === 'object' && 'unsealedSchema' in raw ? schemas.parseUnsealedDistributionLock(raw) : schemas.parseDistributionLock(raw);
+  if (lockMountsAdapters(lockDocument)) {
+    // The adapter host's row: the verified catalogue's for a customer, the data root's biome index for the vendor.
+    const rows = catalogue === undefined ? JSON.parse(readFileSync(biomeIndexPath(), 'utf8')) : catalogue.biomes;
+    await assertAdapterBundlesMatchHost({ lock: lockDocument, hostRow: adapterHostRow(rows), fetchManifest });
+  }
   const result = await sealOrVerifyLock({
     schemas,
     lock: lockDocument,
@@ -657,6 +667,8 @@ async function main() {
       : undefined;
   const catalogue = fetched?.catalogue;
   const catalogueDigest = fetched?.digest;
+  // A customer seal reads the kernel of its catalogue (from npm), proved its contract authority, before any kernel schema is loaded.
+  if (catalogue !== undefined) {await adoptCatalogueKernel(catalogue);}
   const imageLock = await loadImageLockForVerification(distributionId, root);
 
   // Throws on ANY unresolvable subject or missing required platform, before a
@@ -691,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/edition/trust-policy-arming-verb.mjs

@@ -9,7 +9,7 @@
 //         usage error. A data root that declares no policy is `unarmed`.
 // It reads the policy the way `xema edition check` does and never writes.
 
-import { EditionChannel } from './edition-channel.mjs';
+import { EditionChannel, parseChannelArgs } from './edition-channel.mjs';
 import {
   WorkspaceRoot,
   configureEditionWorkspaceFromArgv,
@@ -23,14 +23,6 @@ export const ARMING_USAGE = `usage: xema edition arming --channel <${Object.valu
 /** The process exit codes of the verb. */
 export const ArmingExit = Object.freeze({ Armed: 0, NotArmed: 1, Usage: 2 });
 
-/** The channel of `--channel <channel>` among `rest`; anything else is a usage error. */
-export function parseArmingArgs(rest) {
-  if (rest.length !== 2 || rest[0] !== '--channel' || !Object.values(EditionChannel).includes(rest[1])) {
-    throw new Error(`--channel <${Object.values(EditionChannel).join('|')}> is required and nothing else is accepted (got ${rest.length === 0 ? 'nothing' : JSON.stringify(rest.join(' '))})`);
-  }
-  return { channel: rest[1] };
-}
-
 /**
  * Judge the configured data root's policy on `channel`, writing the one JSON
  * line to `stdout` and each unmet entry to `stderr`. Returns the exit code.
@@ -54,7 +46,7 @@ async function main() {
   let channel;
   try {
     const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Data, WorkspaceRoot.Kernel]);
-    ({ channel } = parseArmingArgs(rest));
+    ({ channel } = parseChannelArgs(rest));
   } catch (error) {
     process.stderr.write(`arming: ${error.message}\n${ARMING_USAGE}\n`);
     process.exitCode = ArmingExit.Usage;

package/edition/verify-image-evidence.mjs

@@ -397,6 +397,7 @@ export async function verifyEvidence({ argv, env, bundlePath }) {
                 completenessStatementDigest: result.completenessStatementDigest,
                 customerId: options.customerId,
                 distributionId: options.distributionId,
+                distributionLock: result.distributionLock,
                 channel,
                 mode: options.mode,
                 targetRegistry: options.targetRegistry,

package/examples/README.md

@@ -1,5 +1,6 @@
 # `xema.config.yaml` examples
 
+
 Copy one of these to `xema.config.yaml` (or `~/.xema/config.yaml`) and edit:
 
 ```bash
@@ -14,6 +15,6 @@ xema up
 | [`03-byo-infra.yaml`](./03-byo-infra.yaml) | Bring-your-own Postgres / Keycloak / object store; launcher runs only the rest. |
 | [`04-subset-knowledge.yaml`](./04-subset-knowledge.yaml) | Run only a slice (tiers / services) to save resources. |
 | [`05-appliance-helm.yaml`](./05-appliance-helm.yaml) | Deploy to Kubernetes / an appliance via Helm. |
+| [`06-biome-sources.yaml`](./06-biome-sources.yaml) | Pull biomes from workspace, distribution and git sources. |
 
-Precedence: `--config <path>` → `./xema.config.yaml` → `~/.xema/config.yaml` →
-built-in defaults. Every value shown is the default unless noted.
+Config precedence: `--config <path>`, then `./xema.config.yaml`, then `~/.xema/config.yaml`, then built-in defaults.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.29.1",
+  "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.76.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:82760f14feea4fe0626220e0f71344375964f15d36201d1e7000ebfb6b2e4ecd"
+    "sourceDigest": "sha256:2fc7a76e728752cf14eeb410921fb5c89cbffc9c3c398116a3c37dcd740587ea"
   }
 }