@xemahq/xema 0.29.0 → 0.30.0

package/edition/resolve-customer-edition.mjs

@@ -18,6 +18,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
+import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest } from './adapter-bundled-versions.mjs';
 import { AUTHORIZATION_LOCK_FILENAME, writeAuthorizationLock } from './authorization-base.mjs';
 import { CATALOGUE_FILE, CatalogueError } from './catalogue.mjs';
 import {
@@ -29,8 +30,8 @@ import {
 import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
 import { EditionLockFile } from './edition-constants.mjs';
 import { editionsRoot } from './edition-workspace.mjs';
-import { validateKernelContractAuthorityFromGit } from './kernel-contract-authority.mjs';
-import { compareStrings, loadKernelDistributionSchemas, serializeJson, validateImmutableImageLock } from './lib.mjs';
+import { adoptCatalogueKernel } from './kernel-package.mjs';
+import { compareStrings, 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';
@@ -63,11 +64,22 @@ function catalogueCeiling(catalogue, schemas) {
   return { trustPolicy: read('trustPolicy', schemas.DistributionTrustPolicySchema), trustCeiling: read('trustCeiling', schemas.ProcessTrustPolicySchema) };
 }
 
+/** A catalogue whose ceiling states no trust-domain assignments reserves no domain: the kernel's required ceiling argument is the empty policy. */
+const NO_CATALOGUE_TRUST_CEILING = Object.freeze({ assignments: [] });
+
+/** The kernel's `customerLockCeilingIssues` is the one check of a customer lock against the catalogue's ceiling. */
+function assertLockWithinCatalogueCeiling({ catalogue, definition, lock, schemas }) {
+  const issues = schemas.customerLockCeilingIssues(catalogueCeiling(catalogue, schemas).trustCeiling, lock.biomes);
+  if (issues.length > 0) {
+    throw new CatalogueCeilingError(`catalogue "${catalogue.offeringId}" (${catalogue.channel}): "${definition.id}" is outside the catalogue's trustCeiling: ${issues.join('; ')}`);
+  }
+}
+
 /**
  * The ceiling policy the customer's lock is written under: the catalogue's assignments, then
  * the definition's for what the catalogue leaves open. An assignment of the definition that
  * names a domain the catalogue assigns, or a biome the catalogue places, is not carried: the
- * catalogue's reading stands, and `assertWithinCatalogueCeiling` refuses the difference.
+ * catalogue's reading stands, and the kernel's `customerLockCeilingIssues` refuses the difference in the lock.
  */
 function ceilingUnderCatalogue(catalogueTrustCeiling, definitionTrustCeiling) {
   if (catalogueTrustCeiling === undefined) {return definitionTrustCeiling;}
@@ -80,25 +92,6 @@ function ceilingUnderCatalogue(catalogueTrustCeiling, definitionTrustCeiling) {
   return { assignments: [...catalogueTrustCeiling.assignments, ...open] };
 }
 
-/**
- * Every customer-source biome sits in the domain its definition names, and that is the domain
- * the catalogue's ceiling admits for it: the lock row carries the kernel's derivation
- * (`deriveTrustCeiling`) under `ceilingUnderCatalogue`, so a definition that reaches into a
- * domain the catalogue assigns, or moves a biome the catalogue places, differs from it here.
- */
-function assertWithinCatalogueCeiling({ catalogue, definition, lock, schemas }) {
-  const stated = new Map((definition.trustCeiling?.assignments ?? []).flatMap((assignment) => assignment.biomes.map((biome) => [biome, assignment.domain])));
-  for (const biome of lock.biomes.filter((candidate) => candidate.source !== undefined)) {
-    const admitted = biome.trustCeiling ?? schemas.defaultTrustDomain(biome.id, biome.origin);
-    if (stated.get(biome.id) !== admitted) {
-      throw new CatalogueCeilingError(
-        `catalogue "${catalogue.offeringId}" (${catalogue.channel}): "${definition.id}" assigns biome "${biome.id}" to trust domain ` +
-          `"${stated.get(biome.id)}", and the catalogue's trustCeiling admits "${admitted}" for it`,
-      );
-    }
-  }
-}
-
 /** `{name -> {imageRegistry, imageNamePrefix}}` from repeated `<source>=<registry>/<prefix>` values; the prefix is the text after the last "/". */
 export function parseSourceImages(values) {
   const byName = new Map();
@@ -247,8 +240,10 @@ export async function resolveCustomerImages({ id, catalogue, lock, composed, sch
   if (ownBiomes.length > 0) {
     const ownLock = { ...lock, biomes: ownBiomes, platformServices: [] };
     const runtimeImageSourceIndex = {
+      schemaVersion: 2,
       contractAuthority: catalogue.contractAuthority,
       repositoryPins: [],
+      producerWorkflowPins: [],
       platformServiceBindings: [],
       supplementalSubjects: [],
       crossRepoBuildInputs: [],
@@ -278,14 +273,9 @@ export async function resolveCustomerImages({ id, catalogue, lock, composed, sch
   return merged;
 }
 
-/** The kernel at --kernel must carry the contract the catalogue's offering was resolved under. */
-export async function assertKernelAtCatalogueAuthority(catalogue, schemas) {
-  await validateKernelContractAuthorityFromGit({ authority: catalogue.contractAuthority, schemas, requireHeadMatch: false });
-}
-
 /**
  * The distribution and authorization locks of the customer edition `rawDefinition`
- * against `catalogue`. `catalogueDigest` is the digest of `catalogue`, written into the lock. `verifyAuthority` and `materialize` are injectable for the test suites.
+ * against `catalogue`. `catalogueDigest` is the digest of `catalogue`, written into the lock. `adoptKernel` (the catalogue's kernel from npm, proved its contract authority; returns the kernel schemas) and `materialize` are injectable for the test suites.
  */
 export async function resolveCustomerDistribution({
   rawDefinition,
@@ -294,10 +284,11 @@ export async function resolveCustomerDistribution({
   sourceImages,
   pins,
   materialize,
-  verifyAuthority = assertKernelAtCatalogueAuthority,
+  adoptKernel = adoptCatalogueKernel,
+  fetchManifest = fetchRegistryManifest,
 }) {
   if (catalogueDigest === undefined) {throw new CatalogueError('a customer resolve names the digest of its catalogue');}
-  const schemas = await loadKernelDistributionSchemas();
+  const schemas = await adoptKernel(catalogue);
   const { definition, mirror } = parseCustomerDefinition(schemas, rawDefinition);
   const composed = composeCustomerEdition({ schemas, definition, mirror, catalogue, sourceImages, pins });
   const id = composed.leaf.id;
@@ -312,9 +303,14 @@ export async function resolveCustomerDistribution({
     throw error;
   }
   const { lock, index } = resolved;
-  assertTrustCeilingAssignsCustomerBiomes(schemas, definition, lock.biomes.filter((biome) => biome.source !== undefined).map((biome) => biome.id));
-  assertWithinCatalogueCeiling({ catalogue, definition, lock, schemas });
-  await verifyAuthority(catalogue, schemas);
+  assertTrustCeilingAssignsCustomerBiomes(
+    schemas,
+    definition,
+    lock.biomes.filter((biome) => biome.source !== undefined).map((biome) => biome.id),
+    catalogueCeiling(catalogue, schemas).trustCeiling ?? NO_CATALOGUE_TRUST_CEILING,
+  );
+  assertLockWithinCatalogueCeiling({ catalogue, definition, lock, schemas });
+  await assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(catalogue.biomes), fetchManifest });
   const authorizationLock = await composeAuthorizationBase(id, lock, index);
   // A customer lock names the catalogue it was resolved against; seal and verify refuse any other.
   return { id, schemas, composed, inputs, lock: { ...lock, catalogueDigest }, authorizationLock };

package/edition/resolve-distribution.mjs

@@ -63,6 +63,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest } from './adapter-bundled-versions.mjs';
 import {
   adoptedFromLock,
   editionAuthorizationModuleInputs,
@@ -2212,8 +2213,9 @@ export async function resolveDistributionWithIndex(id, { materialize, inputs } =
  * this exact writer so an in-process refresh cannot drift from the standalone
  * command's serialization or diagnostics.
  */
-export async function writeResolvedDistribution(id, { log = true, materialize } = {}) {
+export async function writeResolvedDistribution(id, { log = true, materialize, fetchManifest = fetchRegistryManifest } = {}) {
   const { lock, index } = await resolveDistributionWithIndex(id, { materialize });
+  await assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest });
   const outPath = join(editionsRoot(), id, 'distribution.lock.json');
   assertReleaseContent(lock, `the distribution lock for "${id}"`);
   assertReleaseEditionTree(join(editionsRoot(), id));
@@ -2285,12 +2287,14 @@ export async function composeAuthorizationBase(id, lock, index) {
   const kernel = await loadKernelAuthorizationComposer({ kernelPackageDir: kernelPackageDir() });
   // Refuses an edition that carries a module under a pin with no composer.
   const inputs = editionAuthorizationModuleInputs(lock.biomes, new Map(index.map((e) => [e.id, e])), kernel);
+  const { biomeOriginsOfLock } = await loadKernelDistributionSchemas();
   let sealed = null;
   if (kernel !== null) {
     sealed = sealEditionAuthorizationBase({
       distributionId: id,
       inputs,
       kernel,
+      biomeOrigins: biomeOriginsOfLock(lock),
       adopted: adoptedFromLock(readAuthorizationLock(editionDir)),
       runTests: fgaComposedModelTestRunner(resolveFgaCli()),
     });

package/edition/resolve-edition.mjs

@@ -50,14 +50,15 @@ import { withoutSealedDigests } from './seal-image-digests.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
 // A customer resolve (`--definition`) has no vendor editions root: `--out` IS its
-// editions root, the directory its `<id>/` locks are written under.
+// editions root, the directory its `<id>/` locks are written under. It takes no kernel root:
+// the kernel is the catalogue's, downloaded from npm into the cache root.
 if (isEntryModule(import.meta.url)) {
   if (process.argv.includes(DEFINITION_FLAG)) {
     const at = process.argv.indexOf('--out');
     if (at < 0 || process.argv[at + 1] === undefined) {throw new Error(`--out <dir> is required with ${DEFINITION_FLAG}`);}
     mkdirSync(process.argv[at + 1], { recursive: true });
     process.argv.splice(at, 1, '--editions-root');
-    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache], { refuseOthers: true });
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Cache], { refuseOthers: true });
   } else {
     configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache]);
   }

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

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,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -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.78.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:a0dc6a3fdb7cce15b031dcd04476f19924d13d36924070b1527af1fa613b258e"
+    "sourceDigest": "sha256:d594a2838a0fbee09de46b9b6637afd9f9437a2989a2bfe30f2336ddc20f0523"
   }
 }