@xemahq/xema 0.27.0 → 0.29.0

package/edition/resolve-chart-set.mjs

@@ -60,12 +60,18 @@ import { basename, join } from 'node:path';
 import { EditionChannel } from './edition-channel.mjs';
 import {
   EDITION_CHART_SET_FILE,
+  CHART_SET_LOCK_SCHEMA_VERSION,
+  DEVELOP_CHART_VERSION_PREFIX,
   EditionChartSetCheck,
+  OCI_DIGEST_PATTERN,
   assertRosteredChartSetLock,
   checkEditionChartSet,
+  DEVELOP_CHART_SHA_LENGTH,
+  hasDevelopChartVersionPrefix,
+  isDevelopChartVersion,
   writeEditionChartSet,
 } from './edition-chart-set.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
+import { vendorChartSetConfig } from './edition-config.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, dataRoot, editionsRoot, isEntryModule } from './edition-workspace.mjs';
 import { serializeJson } from './lib.mjs';
 import { OrasRegistry } from './oras.mjs';
@@ -95,11 +101,11 @@ export const chartSetLockPath = () => join(dataRoot(), CHART_SET_LOCK_FILE);
  * refuses a copy that differs — so the copies cannot disagree
  * (edition-chart-set.mjs).
  */
-const chartRegistry = () => editionWorkspaceConfig().chartRegistry;
-const chartSetPublishers = () => editionWorkspaceConfig().chartPublishers;
+const chartRegistry = () => vendorChartSetConfig().chartRegistry;
+const chartSetPublishers = () => vendorChartSetConfig().chartPublishers;
 
 /** `<host>/<path>` -> the repository path the registry API addresses. */
-function registryRepository(indexName) {
+export function registryRepository(indexName) {
   return `${chartRegistry().replace(/^oci:\/\/[^/]+\//, '')}/${indexName}`;
 }
 
@@ -125,9 +131,9 @@ export function isVersionTag(tag) {
  */
 export function selectNewestIndex(allCandidates) {
   if (!Array.isArray(allCandidates)) {return null;}
-  // A develop chart version (`0.0.0-dev.<sha12>`) is a frozen xema-deploy
-  // snapshot, never a release index: it is not a candidate for the release pin.
-  const candidates = allCandidates.filter((c) => !c.tag.startsWith(DEVELOP_CHART_VERSION_PREFIX));
+  // Anything with the develop prefix (`0.0.0-dev.`) is a frozen xema-deploy
+  // snapshot or a malformed develop version, never a release index: it is not a candidate for the release pin.
+  const candidates = allCandidates.filter((c) => !hasDevelopChartVersionPrefix(c.tag));
   if (candidates.length === 0) {return null;}
   const undated = candidates.filter((c) => !c.createdAt);
   if (undated.length > 0) {
@@ -142,12 +148,17 @@ export function selectNewestIndex(allCandidates) {
   )[0].tag;
 }
 
-const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const DIGEST_PATTERN = OCI_DIGEST_PATTERN;
 
 /** The index chart annotation listing the charts the publisher closed the set with. */
 export const INDEX_ROSTER_ANNOTATION = 'xema.dev/chart-set-charts';
 
-export function buildLock(versionsByIndex, rostersByIndex, publishers = chartSetPublishers()) {
+/**
+ * The lock for `publishers`: each publisher's index version, the manifest digest
+ * the registry served for that index (`indexDigestsByIndex`, null for a develop
+ * snapshot, which has no index chart), and its sealed roster.
+ */
+export function buildLock(versionsByIndex, rostersByIndex, indexDigestsByIndex, publishers = chartSetPublishers()) {
   // Every publisher's VERSION first: a pin that resolved nothing for one half is
   // the more fundamental refusal, whatever its roster.
   for (const publisher of publishers) {
@@ -156,10 +167,10 @@ export function buildLock(versionsByIndex, rostersByIndex, publishers = chartSet
     }
   }
   return {
-    // 3: every member is `{version, digest}` (its OCI manifest digest), so the
-    // lock itself is the trust anchor. 2 added `publishers[].version` (one each)
-    // in place of one shared version, which would couple the two halves.
-    schemaVersion: 3,
+    // Every member is `{version, digest}` (its OCI manifest digest) and each
+    // publisher pins its index chart by `indexDigest`, so the lock itself is the
+    // trust anchor; `publishers[].version` is per publisher, not one shared version.
+    schemaVersion: CHART_SET_LOCK_SCHEMA_VERSION,
     registry: chartRegistry(),
     publishers: publishers.map((publisher) => {
       const version = versionsByIndex[publisher.index];
@@ -180,7 +191,13 @@ export function buildLock(versionsByIndex, rostersByIndex, publishers = chartSet
         }
         charts[name] = { version: member.version, digest: member.digest };
       }
-      return { ...publisher, version, charts };
+      // The digest the registry served for the index manifest the roster was read from.
+      const indexDigest = indexDigestsByIndex?.[publisher.index];
+      const wellFormed = isDevelopChartVersion(version) ? indexDigest === null : DIGEST_PATTERN.test(String(indexDigest));
+      if (!wellFormed) {
+        throw new Error(`no index manifest digest was read for '${publisher.index}@${version}' (got ${JSON.stringify(indexDigest ?? null)}; a release index needs sha256:<64 hex>, a develop snapshot null)`);
+      }
+      return { ...publisher, version, indexDigest, charts };
     }),
   };
 }
@@ -235,19 +252,21 @@ export async function sealRoster(roster, lookup, label) {
   return sealed;
 }
 
-/** The annotations of the index chart `<indexName>:<version>`, read from its OCI config blob (helm stores Chart.yaml's metadata there). */
-export async function indexAnnotations(client, indexName, version) {
+/** The annotations of an index chart's served manifest `served` ({digest, bytes}), read from its OCI config blob (helm stores Chart.yaml's metadata there). */
+export async function manifestAnnotations(client, indexName, version, served) {
   const repository = registryRepository(indexName);
-  const manifest = JSON.parse((await client.getManifestByTag(repository, version)).bytes.toString('utf8'));
+  const manifest = JSON.parse(served.bytes.toString('utf8'));
   const configDigest = manifest?.config?.digest;
   if (typeof configDigest !== 'string') {throw new Error(`${indexName}@${version}: manifest names no config blob`);}
   const config = JSON.parse((await client.getBlob(repository, configDigest)).toString('utf8'));
   return config?.annotations ?? {};
 }
 
-async function indexRoster(client, indexName, version) {
-  const annotations = await indexAnnotations(client, indexName, version);
-  return parseIndexRoster(annotations[INDEX_ROSTER_ANNOTATION], `${indexName}@${version}`);
+/** The roster and the served manifest digest of the index chart `<indexName>:<version>`, from ONE manifest read. */
+async function indexRosterAndDigest(client, indexName, version) {
+  const served = await client.getManifestByTag(registryRepository(indexName), version);
+  const annotations = await manifestAnnotations(client, indexName, version, served);
+  return { roster: parseIndexRoster(annotations[INDEX_ROSTER_ANNOTATION], `${indexName}@${version}`), indexDigest: served.digest };
 }
 
 /** Every edition directory (one holding a distribution.lock.json) under the editions root. */
@@ -259,11 +278,9 @@ function editionDirs() {
 }
 
 const SHA_PATTERN = /^[0-9a-f]{40}$/;
-const DEVELOP_CHART_VERSION_PREFIX = '0.0.0-dev.';
-const DEVELOP_SHA_LENGTH = 12;
 
 /** The develop chart version xema-deploy publishes for a frozen SHA: `0.0.0-dev.<sha12>`, also the OCI tag. */
-export const developChartVersion = (sha) => `${DEVELOP_CHART_VERSION_PREFIX}${sha.slice(0, DEVELOP_SHA_LENGTH)}`;
+export const developChartVersion = (sha) => `${DEVELOP_CHART_VERSION_PREFIX}${sha.slice(0, DEVELOP_CHART_SHA_LENGTH)}`;
 
 /** Every chart (a directory with a Chart.yaml, library charts included) of an xema-deploy checkout, sorted. */
 function deployChartNames(xemaDeployDir) {
@@ -312,7 +329,8 @@ export async function resolveDevelopChartSet({ xemaDeployDir, xemaDeploySha, loo
   const digestOf = lookup ?? registryManifestDigest(chartRegistryClient());
   const roster = Object.fromEntries(names.map((name) => [name, { version }]));
   const sealed = await sealRoster(roster, digestOf, `${publishers[0].index}@${version}`);
-  const lock = buildLock({ [publishers[0].index]: version }, { [publishers[0].index]: sealed }, publishers);
+  // A develop snapshot has no index chart: its roster is the deploy checkout's chart directories.
+  const lock = buildLock({ [publishers[0].index]: version }, { [publishers[0].index]: sealed }, { [publishers[0].index]: null }, publishers);
   return assertRosteredChartSetLock(lock, EDITION_CHART_SET_FILE, EditionChannel.Develop);
 }
 
@@ -343,11 +361,12 @@ async function indexCandidates(client, indexName) {
   return candidates;
 }
 
-async function resolveFromRegistry() {
-  const client = chartRegistryClient();
+/** Read every publisher's newest index through `client`: its version, its roster, and the manifest digest the registry served for it. */
+export async function resolveFromRegistry(client = chartRegistryClient()) {
 
   const versionsByIndex = {};
   const rostersByIndex = {};
+  const indexDigestsByIndex = {};
   for (const { index, repo } of chartSetPublishers()) {
     const candidates = await indexCandidates(client, index);
     const version = selectNewestIndex(candidates);
@@ -359,7 +378,8 @@ async function resolveFromRegistry() {
       );
     }
     versionsByIndex[index] = version;
-    const roster = await indexRoster(client, index, version);
+    const { roster, indexDigest } = await indexRosterAndDigest(client, index, version);
+    indexDigestsByIndex[index] = indexDigest;
     // The registry is asked for every member, so an index digest is checked
     // against it and a member without one still gets sealed.
     rostersByIndex[index] = await sealRoster(
@@ -368,13 +388,13 @@ async function resolveFromRegistry() {
       `${index}@${version}`,
     );
   }
-  return { versionsByIndex, rostersByIndex };
+  return { versionsByIndex, rostersByIndex, indexDigestsByIndex };
 }
 
 async function main(argv) {
   const check = argv.includes('--check');
-  const { versionsByIndex, rostersByIndex } = await resolveFromRegistry();
-  const next = buildLock(versionsByIndex, rostersByIndex);
+  const { versionsByIndex, rostersByIndex, indexDigestsByIndex } = await resolveFromRegistry();
+  const next = buildLock(versionsByIndex, rostersByIndex, indexDigestsByIndex);
   assertRosteredChartSetLock(next, CHART_SET_LOCK_FILE, EditionChannel.Release);
   const pinText = serializeJson(next);
   const current = readLock();

package/edition/resolve-customer-edition.mjs

@@ -1,10 +1,11 @@
 // resolve-customer-edition — resolve a CUSTOMER edition against a catalogue.
 //
-//   resolve-edition.mjs <root flags> --definition <file> --catalogue oci://<repo>@sha256:<digest>
+//   resolve-edition.mjs <root flags> --definition <file>
 //       --channel release|develop --out <dir> [--source-image <source>=<registry>/<prefix>]...
 //       [--catalogue-username <name> --catalogue-token-env <VAR>]
 //
-// The catalogue (catalogue.mjs) is the CEILING: it supplies availability, pins,
+// The catalogue of the channel is the one pinned in catalogue.pin.json beside the definition
+// (catalogue-pin.mjs). The catalogue (catalogue.mjs) is the CEILING: it supplies availability, pins,
 // image digests, chart-set rows and the contract authority, and never adds a
 // component. The resolved set is the customer's positive selections, every
 // installationClass core entry of the catalogue and the transitive declared
@@ -15,6 +16,7 @@
 
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 
 import { AUTHORIZATION_LOCK_FILENAME, writeAuthorizationLock } from './authorization-base.mjs';
 import { CATALOGUE_FILE, CatalogueError } from './catalogue.mjs';
@@ -31,7 +33,7 @@ import { validateKernelContractAuthorityFromGit } from './kernel-contract-author
 import { compareStrings, loadKernelDistributionSchemas, serializeJson, validateImmutableImageLock } from './lib.mjs';
 import { pinnedSource, snapshotPinSource } from './pin-source.mjs';
 import { composeAuthorizationBase, composeManifest, resolveDistributionWithIndex, UnknownSelectionError } from './resolve-distribution.mjs';
-import { resolveImages } from './resolve-images.mjs';
+import { resolveImageRows } from './resolve-images.mjs';
 
 /** A selection or dependency the catalogue does not offer: the catalogue is the ceiling. */
 export class CatalogueCeilingError extends Error {
@@ -186,7 +188,57 @@ export function projectVendorImages(catalogue, lock, enums) {
   };
 }
 
-/** The customer's image lock: vendor rows copied (and mirrored), own rows resolved. */
+/** The first field in which two rows differ (compared by canonical deep equality, key by key), or undefined when they are equal. */
+function firstDifferingField(expected, actual) {
+  for (const field of [...new Set([...Object.keys(expected), ...Object.keys(actual)])].sort(compareStrings)) {
+    if (!isDeepStrictEqual(expected[field], actual[field])) {return field;}
+  }
+  return undefined;
+}
+
+/**
+ * The vendor rows of the merged images lock ARE the catalogue's rows: every subject, platform-service binding and web
+ * biome that is not the customer's own deep-equals the catalogue's row (owners narrowed to the selection by
+ * `projectVendorImages`, imageRef re-homed by the declared mirror through `mirrorVendorSubjects`), and every projected
+ * catalogue row is present. A difference throws `CatalogueCeilingError`, naming the row and the first differing field.
+ */
+export function assertVendorRowsAreCatalogueRows({ catalogue, imageLock, lock, mirror, enums }) {
+  const ownBiomes = new Set(lock.biomes.filter((biome) => biome.source !== undefined).map((biome) => biome.id));
+  const projected = projectVendorImages(catalogue, lock, enums);
+  const expected = {
+    subjects: new Map(mirrorVendorSubjects(projected.subjects, mirror).map((subject) => [subjectKey(subject), subject])),
+    platformServiceBindings: new Map(projected.platformServiceBindings.map((binding) => [binding.platformService, binding])),
+    webBiomes: new Map(projected.webBiomes.map((biome) => [biome.biomeId, biome])),
+  };
+  const isOwnSubject = (subject) => subject.owners.length > 0 && subject.owners.every((owner) => owner.kind === enums.RuntimeImageOwnerKind.Biome && ownBiomes.has(owner.biomeId));
+  const compare = (label, name, want, got) => {
+    if (want === undefined) {
+      throw new CatalogueCeilingError(`the merged images lock carries ${label} ${name}, which is neither the customer's own nor the catalogue's`);
+    }
+    const field = firstDifferingField(want, got);
+    if (field !== undefined) {
+      throw new CatalogueCeilingError(`the merged images lock's ${label} ${name} differs from the catalogue's row at ${field}`);
+    }
+  };
+  const kinds = [
+    ['image', 'subjects', (row) => subjectKey(row), (row) => `${row.kind}:${row.id}`, (row) => isOwnSubject(row)],
+    ['platform-service binding', 'platformServiceBindings', (row) => row.platformService, (row) => row.platformService, () => false],
+    ['web biome', 'webBiomes', (row) => row.biomeId, (row) => row.biomeId, (row) => ownBiomes.has(row.biomeId)],
+  ];
+  for (const [label, field, keyOf, nameOf, isOwn] of kinds) {
+    const present = new Set();
+    for (const row of imageLock[field]) {
+      if (isOwn(row)) {continue;}
+      present.add(keyOf(row));
+      compare(label, nameOf(row), expected[field].get(keyOf(row)), row);
+    }
+    for (const [key, want] of expected[field]) {
+      if (!present.has(key)) {throw new CatalogueCeilingError(`the merged images lock lacks the catalogue's ${label} ${nameOf(want)}`);}
+    }
+  }
+}
+
+/** The customer's image lock: vendor rows copied (and mirrored), own rows resolved (and sealed by `sealOwn`, which takes and returns subjects), the merged lock parsed once. */
 export async function resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn }) {
   const vendor = projectVendorImages(catalogue, lock, schemas);
   const vendorSubjects = mirrorVendorSubjects(vendor.subjects, composed.mirror);
@@ -202,13 +254,15 @@ export async function resolveCustomerImages({ id, catalogue, lock, composed, sch
       crossRepoBuildInputs: [],
       buildStepContextDirectories: [],
     };
-    own = (await resolveImages(id, { inputs: { ...inputs, runtimeImageSourceIndex, composed }, lock: ownLock })).imageLock;
-    if (sealOwn !== undefined) {own = await sealOwn(own);}
+    // The own rows are ROWS, not a lock: the one parse is of the merged lock below.
+    own = await resolveImageRows(id, { inputs: { ...inputs, runtimeImageSourceIndex, composed }, lock: ownLock });
+    // A source that builds no image (a web biome) has no row to seal.
+    if (sealOwn !== undefined && own.subjects.length > 0) {own = { ...own, subjects: await sealOwn({ distributionId: id, subjects: own.subjects }) };}
   }
   const seen = new Set(vendorSubjects.map(subjectKey));
   const clash = own.subjects.find((subject) => seen.has(subjectKey(subject)));
   if (clash !== undefined) {throw new Error(`the customer's own image ${clash.kind}:${clash.id} collides with a catalogue image of the same identity`);}
-  return validateImmutableImageLock(
+  const merged = validateImmutableImageLock(
     schemas.parseImageLock({
       schemaVersion: 3,
       sourceHashAlgorithm: catalogue.images.sourceHashAlgorithm,
@@ -220,6 +274,8 @@ export async function resolveCustomerImages({ id, catalogue, lock, composed, sch
     }),
     schemas,
   );
+  assertVendorRowsAreCatalogueRows({ catalogue, imageLock: merged, lock, mirror: composed.mirror, enums: schemas });
+  return merged;
 }
 
 /** The kernel at --kernel must carry the contract the catalogue's offering was resolved under. */

package/edition/resolve-distribution.mjs

@@ -144,7 +144,7 @@ export function lockedServiceProcessFacts(entry) {
 }
 
 if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.SourceHash]);
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
 }
 
 /**

package/edition/resolve-edition.mjs

@@ -24,8 +24,8 @@ import { join } from 'node:path';
 
 import { AUTHORIZATION_LOCK_FILENAME } from './authorization-base.mjs';
 import { fetchCatalogue } from './catalogue-fetch.mjs';
+import { readCataloguePin } from './catalogue-pin.mjs';
 import {
-  CATALOGUE_FLAG,
   CATALOGUE_TOKEN_ENV_FLAG,
   CATALOGUE_USERNAME_FLAG,
   CHANNEL_FLAG,
@@ -49,17 +49,17 @@ import { writeResolvedImages } from './resolve-images.mjs';
 import { withoutSealedDigests } from './seal-image-digests.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
-// A customer resolve (`--catalogue`) has no vendor editions root: `--out` IS its
+// A customer resolve (`--definition`) has no vendor editions root: `--out` IS its
 // editions root, the directory its `<id>/` locks are written under.
 if (isEntryModule(import.meta.url)) {
-  if (process.argv.includes(CATALOGUE_FLAG)) {
+  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 ${CATALOGUE_FLAG}`);}
+    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, WorkspaceRoot.SourceHash]);
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache], { refuseOthers: true });
   } else {
-    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache]);
   }
 }
 
@@ -135,7 +135,7 @@ export async function checkResolvedLockSet(id) {
   }
 }
 
-const CUSTOMER_VALUE_FLAGS = [DEFINITION_FLAG, CATALOGUE_FLAG, CHANNEL_FLAG, CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG];
+const CUSTOMER_VALUE_FLAGS = [DEFINITION_FLAG, CHANNEL_FLAG, CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG];
 
 /** The arguments of a customer resolve (the root flags and `--out` are already consumed). */
 export function parseCustomerResolveArgs(args) {
@@ -145,12 +145,12 @@ export function parseCustomerResolveArgs(args) {
     const flag = args[i];
     const value = args[i + 1];
     if (![...CUSTOMER_VALUE_FLAGS, SOURCE_IMAGE_FLAG].includes(flag) || value === undefined || value.startsWith('--')) {
-      throw new Error(`unexpected argument ${JSON.stringify(flag)} in a customer resolve (${DEFINITION_FLAG}, ${CATALOGUE_FLAG}, ${CHANNEL_FLAG}, ${SOURCE_IMAGE_FLAG} take a value)`);
+      throw new Error(`unexpected argument ${JSON.stringify(flag)} in a customer resolve (${DEFINITION_FLAG}, ${CHANNEL_FLAG}, ${SOURCE_IMAGE_FLAG} take a value)`);
     }
     i += 1;
     if (flag === SOURCE_IMAGE_FLAG) {sourceImages.push(value);} else if (values.has(flag)) {throw new Error(`${flag} given twice`);} else {values.set(flag, value);}
   }
-  for (const required of [DEFINITION_FLAG, CATALOGUE_FLAG, CHANNEL_FLAG]) {
+  for (const required of [DEFINITION_FLAG, CHANNEL_FLAG]) {
     if (!values.has(required)) {throw new Error(`a customer resolve requires ${required}`);}
   }
   if (!Object.values(EditionChannel).includes(values.get(CHANNEL_FLAG))) {
@@ -162,7 +162,8 @@ export function parseCustomerResolveArgs(args) {
 async function mainCustomer() {
   const { values, sourceImages } = parseCustomerResolveArgs(process.argv.slice(2));
   const { catalogue, digest } = await fetchCatalogue({
-    ref: values.get(CATALOGUE_FLAG),
+    ref: readCataloguePin({ definitionFile: values.get(DEFINITION_FLAG), channel: values.get(CHANNEL_FLAG) }),
+    channel: values.get(CHANNEL_FLAG),
     username: values.get(CATALOGUE_USERNAME_FLAG),
     tokenEnv: values.get(CATALOGUE_TOKEN_ENV_FLAG),
   });
@@ -172,7 +173,7 @@ async function mainCustomer() {
 }
 
 async function main() {
-  if (process.argv.includes(CATALOGUE_FLAG)) {return mainCustomer();}
+  if (process.argv.includes(DEFINITION_FLAG)) {return mainCustomer();}
   const { id, check } = parseResolveEditionArgs(process.argv.slice(2));
   assertCanonicalDistributionId(id);
   await (check ? checkResolvedLockSet(id) : writeResolvedLockSet(id));

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();
+}