@xemahq/xema 0.28.0 → 0.29.1

package/edition/resolve-images.mjs

@@ -68,7 +68,7 @@ import { composeEdition } from './resolve-distribution.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
 if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache]);
 }
 
 const firstPartyImageRegistry = () => editionWorkspaceConfig().imageRegistry;
@@ -1383,7 +1383,15 @@ function snapshotImageInputs(schemas, { inputs, lock }) {
   };
 }
 
-export async function resolveImages(id, { inputs, lock } = {}) {
+/**
+ * The image ROWS of one edition: its subjects (hashed at the commits the lock
+ * pins), its platform-service bindings and its bundled web biomes, after every
+ * check that needs no parsed lock. Rows are not a lock: the kernel's image-lock
+ * grammar is the grammar of a COMPLETE lock, and a caller that holds only part
+ * of one (a customer's own rows, merged with the catalogue's) parses the lock
+ * it completes. `resolveImages` is these rows parsed as the whole lock.
+ */
+export async function resolveImageRows(id, { inputs, lock } = {}) {
   assertCanonicalDistributionId(id);
   if ((inputs === undefined) !== (lock === undefined)) {
     throw new Error('resolveImages takes the snapshot `inputs` and its distribution `lock` together, or neither');
@@ -1509,18 +1517,6 @@ export async function resolveImages(id, { inputs, lock } = {}) {
     ...biome,
     sourceCommit: commitsBefore.get(biome.repo),
   }));
-  const imageLock = validateImmutableImageLock(
-    schemas.parseImageLock({
-      schemaVersion: 3,
-      sourceHashAlgorithm: schemas.ImageSourceHashAlgorithm.ImageInputV2,
-      distributionId: id,
-      contractAuthority: runtimeSourceIndex.contractAuthority,
-      subjects,
-      platformServiceBindings: structure.platformServiceBindings,
-      webBiomes,
-    }),
-    schemas,
-  );
   // The SAME locator the hash used. The default locator resolves every repo
   // handle to a first-party tree under the aggregator root, so for an edition
   // with an external source it looked for `<sourcesRoot()>/<source name>`, found no
@@ -1533,7 +1529,32 @@ export async function resolveImages(id, { inputs, lock } = {}) {
       'refusing image-lock write: a source repository commit changed while hashing',
     );
   }
-  return { imageLock, commits: [...commitsBefore] };
+  return {
+    subjects,
+    platformServiceBindings: structure.platformServiceBindings,
+    webBiomes,
+    contractAuthority: runtimeSourceIndex.contractAuthority,
+    commits: [...commitsBefore],
+  };
+}
+
+/** One edition's COMPLETE image lock: its rows, parsed and validated as the kernel's image lock. */
+export async function resolveImages(id, { inputs, lock } = {}) {
+  const { subjects, platformServiceBindings, webBiomes, contractAuthority, commits } = await resolveImageRows(id, { inputs, lock });
+  const schemas = await loadKernelDistributionSchemas();
+  const imageLock = validateImmutableImageLock(
+    schemas.parseImageLock({
+      schemaVersion: 3,
+      sourceHashAlgorithm: schemas.ImageSourceHashAlgorithm.ImageInputV2,
+      distributionId: id,
+      contractAuthority,
+      subjects,
+      platformServiceBindings,
+      webBiomes,
+    }),
+    schemas,
+  );
+  return { imageLock, commits };
 }
 
 /**

package/edition/seal-image-digests.mjs

@@ -114,7 +114,9 @@ import { join } from 'node:path';
 
 import { sealLock, verifyBiomeContentHashes } from './biome-content.mjs';
 import { fetchCatalogue } from './catalogue-fetch.mjs';
-import { CATALOGUE_FLAG, CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG } from './customer-flags.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 {
   assertCoordinatesFinal,
@@ -134,7 +136,20 @@ import {
 } from './verify-image-platforms.mjs';
 
 if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+  // 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.
+  let namesDefinition;
+  try {
+    namesDefinition = parseSealArgs(process.argv.slice(2)).catalogueFlags.has(DEFINITION_FLAG);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+  configureEditionWorkspaceFromProcess(
+    [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache],
+    { refuseOthers: namesDefinition },
+  );
 }
 
 const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/u;
@@ -393,12 +408,19 @@ export function isNotPublishedYet(error) {
  */
 export function parseSealArgs(args) {
   const MODES = new Set(['--check', '--if-published', '--publication-verdict']);
-  const CATALOGUE_VALUE_FLAGS = new Set([CATALOGUE_FLAG, CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG]);
+  const CATALOGUE_VALUE_FLAGS = new Set([DEFINITION_FLAG, CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG]);
   const positional = [];
   const catalogueFlags = new Map();
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (MODES.has(arg)) {continue;}
+    const eq = arg.indexOf('=');
+    if (eq > 0 && CATALOGUE_VALUE_FLAGS.has(arg.slice(0, eq))) {
+      const value = arg.slice(eq + 1);
+      if (value === '' || value.startsWith('--')) {throw new Error(`${arg.slice(0, eq)} takes a value`);}
+      catalogueFlags.set(arg.slice(0, eq), value);
+      continue;
+    }
     if (CATALOGUE_VALUE_FLAGS.has(arg)) {
       if (args[i + 1] === undefined || args[i + 1].startsWith('--')) {throw new Error(`${arg} takes a value`);}
       catalogueFlags.set(arg, args[i + 1]);
@@ -530,7 +552,7 @@ async function main() {
     throw new Error(
       'usage: xema edition seal <distributionId> ' +
         `[--check | --if-published | --publication-verdict] ` +
-        `[--catalogue oci://<repository>@sha256:<digest> [--catalogue-username <name> --catalogue-token-env <VAR>]]`,
+        `[--definition <file> [--catalogue-username <name> --catalogue-token-env <VAR>]]`,
     );
   }
   // The modes answer different questions and combining them would make the
@@ -621,12 +643,14 @@ async function main() {
   // `authTokenEnv` and the test reads which variable the refusal names, because
   // no structural check can tell a threaded argument from an omitted one.
   const root = editionsRoot();
-  // CUSTOMER MODE: the digest-pinned catalogue the edition was resolved against.
+  // CUSTOMER MODE (`--definition`): the digest-pinned RELEASE catalogue of catalogue.pin.json beside the
+  // definition, the one the edition was resolved against.
   // Its vendor biomes' tree ids are inputs on ITS authority (biome-content.mjs).
   const fetched =
-    catalogueFlags.has(CATALOGUE_FLAG)
+    catalogueFlags.has(DEFINITION_FLAG)
       ? await fetchCatalogue({
-          ref: catalogueFlags.get(CATALOGUE_FLAG),
+          ref: readCataloguePin({ definitionFile: catalogueFlags.get(DEFINITION_FLAG), channel: EditionChannel.Release }),
+          channel: EditionChannel.Release,
           username: catalogueFlags.get(CATALOGUE_USERNAME_FLAG),
           tokenEnv: catalogueFlags.get(CATALOGUE_TOKEN_ENV_FLAG),
         })

package/edition/source-closure.mjs

@@ -2,7 +2,7 @@
 // `xema edition source-closure`: the source tree hash of one directory of a
 // source repository at an exact commit, with its workspace-package closure.
 //
-// usage: xema edition source-closure --repo <repo> --path <dir> --commit <40 hex> --sources-root <dir> --source-hash <dir> --kernel <dir>
+// usage: xema edition source-closure --repo <repo> --path <dir> --commit <40 hex> --sources-root <dir> --kernel <dir>
 //
 // These are the facts a content coordinate is derived from. A consumer frames
 // them into its own coordinate; it never reads a git tree, a workspace graph
@@ -85,7 +85,6 @@ export function readSourceClosure({ repoDir, repo, directory, commit }) {
 function main() {
   const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
     WorkspaceRoot.Sources,
-    WorkspaceRoot.SourceHash,
     // The hash implementation is held to the kernel it was built for.
     WorkspaceRoot.Kernel,
   ]);

package/edition/trust-policy-arming-verb.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// `xema edition arming`: is the data root's declared evidence trust policy ARMED
+// on one channel?
+//
+// usage: xema edition arming --channel <release|develop> --data-root <dir> --kernel <dir>
+// stdout: {"channel":"<channel>","state":"armed|unarmed|partial","unmet":["…"]}
+// exit:   0 only when the state is armed; 1 for any other state (each unmet
+//         entry on stderr) or a policy that does not hold to its pin; 2 for a
+//         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 {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { assessDeclaredTrustPolicyArming } from './evidence-trust-policy.mjs';
+import { TrustPolicyArmingState } from './trust-policy-arming.mjs';
+
+export const ARMING_USAGE = `usage: xema edition arming --channel <${Object.values(EditionChannel).join('|')}> --data-root <dir> --kernel <dir>`;
+
+/** 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.
+ */
+export async function runArming({ channel, locateVerifier, stdout = process.stdout, stderr = process.stderr }) {
+  let verdict;
+  try {
+    verdict = await assessDeclaredTrustPolicyArming({ channel, locateVerifier });
+  } catch (error) {
+    stderr.write(`arming: ${error.message}\n`);
+    return ArmingExit.NotArmed;
+  }
+  const { state, unmet } = verdict;
+  stdout.write(`${JSON.stringify({ channel, state, unmet })}\n`);
+  if (state === TrustPolicyArmingState.ARMED) {return ArmingExit.Armed;}
+  for (const entry of unmet) {stderr.write(`${entry}\n`);}
+  return ArmingExit.NotArmed;
+}
+
+async function main() {
+  let channel;
+  try {
+    const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Data, WorkspaceRoot.Kernel]);
+    ({ channel } = parseArmingArgs(rest));
+  } catch (error) {
+    process.stderr.write(`arming: ${error.message}\n${ARMING_USAGE}\n`);
+    process.exitCode = ArmingExit.Usage;
+    return;
+  }
+  process.exitCode = await runArming({ channel });
+}
+
+if (isEntryModule(import.meta.url)) {
+  await main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -51,6 +51,7 @@
     "@nestjs/platform-express": "^11.1.28",
     "@xemahq/biome-sdk": "^18.1.0",
     "@xemahq/biome-supply-chain": "^0.5.0",
+    "@xemahq/distribution-source-hash": "^0.3.0",
     "@xemahq/dsl": "^0.23.0",
     "@xemahq/identity-client": "^0.16.0",
     "@xemahq/contracts": "^0.76.0",
@@ -68,7 +69,6 @@
     "@types/jest": "^30.0.0",
     "@types/node": "25.2.3",
     "@xemahq/biome-host-api-client": "^0.3.31",
-    "@xemahq/distribution-source-hash": "^0.3.0",
     "@xemahq/eslint-config": "^0.9.2",
     "esbuild": "0.28.2",
     "eslint": "^9.39.4",
@@ -92,6 +92,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:c33104cb26add433525e6447c931da38c0fc51a552b7f61f59b293734aeeb23c"
+    "sourceDigest": "sha256:82760f14feea4fe0626220e0f71344375964f15d36201d1e7000ebfb6b2e4ecd"
   }
 }