@xemahq/xema 0.28.0 → 0.29.0

package/edition/lib.mjs

@@ -24,7 +24,6 @@ import {
   kernelDistPath,
   kernelPackageDir,
   kernelRepoDir,
-  sourceHashPackageDir,
   sourcePath,
 } from './edition-workspace.mjs';
 import { SHA256_HEX_PATTERN } from './evidence-grammars.mjs';
@@ -149,38 +148,28 @@ export const BIOME_WORKLOAD_KINDS = new Set(['service', 'runtime-component']);
 export const DEFAULT_BIOME_WORKLOAD_KIND = 'service';
 
 /**
- * The BUILT `@xemahq/distribution-source-hash` package (CJS dist), loaded from
- * the directory the entry states with `--source-hash`.
+ * The `@xemahq/distribution-source-hash` package (CJS dist), a caret (0.x minor-locked)
+ * dependency of the CLI, loaded by name on first use.
  *
  * That package is the SINGLE owner of `xema-source-tree-sha256-v2` — the same
  * implementation every producing repository's CI uses to derive the
  * `<contentHash>` release tag. This tooling must never carry a second copy: a
  * divergence would put a lock and its images at coordinates that silently
- * disagree. It is NOT an npm dependency of the CLI: the evidence verifier never
- * hashes a source tree, so its bundle must not reach this package; only the
- * entries that resolve, build, index or seal state the root.
+ * disagree. The evidence verifier never hashes a source tree, so its bundle
+ * does not reach this package; only the entries that resolve, build, index or
+ * seal load it.
  */
 const requireFromLib = createRequire(import.meta.url);
 
-const loadedSourceHash = new Map();
+let loadedSourceHash;
 
 function distributionSourceHash() {
-  const directory = sourceHashPackageDir();
-  const known = loadedSourceHash.get(directory);
-  if (known) {return known;}
-  let mod;
-  try {
-    mod = createRequire(join(directory, 'package.json'))(directory);
-  } catch (err) {
-    throw new Error(
-      `Cannot load the built distribution-source-hash package from ${directory}. ` +
-        `Build it first (\`pnpm install --frozen-lockfile && pnpm run build\` in its workspace). ` +
-        `Underlying error: ${err.message}`,
-    );
+  if (loadedSourceHash === undefined) {
+    const mod = requireFromLib('@xemahq/distribution-source-hash');
+    assertSourceHashMatchesKernel(mod);
+    loadedSourceHash = mod;
   }
-  assertSourceHashMatchesKernel(mod);
-  loadedSourceHash.set(directory, mod);
-  return mod;
+  return loadedSourceHash;
 }
 
 /**
@@ -214,9 +203,9 @@ function requireAlgorithmMember(enumObject, enumName, member) {
   const value = enumObject?.[member];
   if (typeof value !== 'string' || value.length === 0) {
     throw new Error(
-      `Built @xemahq/distribution-source-hash does not declare ` +
+      `@xemahq/distribution-source-hash does not declare ` +
         `${enumName}.${member}. The installed package is `+
-        `stale or the member was renamed; raise the @xemahq/distribution-source-hash range and, if the `+
+        `stale or the member was renamed; change the pinned @xemahq/distribution-source-hash version and, if the `+
         `rename was deliberate, move every reader in the same change.`,
     );
   }

package/edition/pin-source.mjs

@@ -65,13 +65,18 @@ export function sourceNameOfPinKey(key) {
   return key.slice(SOURCE_PIN_PREFIX.length);
 }
 
+/** Whether `key` is the snapshot key of a declared source (`sources/<name>`); pure, it reads no workspace section. */
+export function isSourcePinKey(key) {
+  return key.startsWith(SOURCE_PIN_PREFIX) && key.length > SOURCE_PIN_PREFIX.length;
+}
+
 /** Which closed namespace a snapshot key belongs to; refuses a key in none. */
 export function snapshotPinNamespace(key) {
   if (key === dataPinKey()) {return SnapshotPinNamespace.Distributions;}
   if (key === kernelPinKey()) {return SnapshotPinNamespace.Kernel;}
   if (key === deployPinKey()) {return SnapshotPinNamespace.ChartSource;}
   if (key === EDITIONS_ROOT_PIN_KEY) {return SnapshotPinNamespace.EditionsRoot;}
-  if (key.startsWith(SOURCE_PIN_PREFIX) && key.length > SOURCE_PIN_PREFIX.length) {
+  if (isSourcePinKey(key)) {
     return SnapshotPinNamespace.Source;
   }
   if (GRAPH_PIN_PATTERN.test(key)) {return SnapshotPinNamespace.Graph;}

package/edition/registry-credentials.mjs

@@ -117,7 +117,17 @@ export function loadRegistryCredentialDeclarations(
   distributionsRoot = dataRoot(),
 ) {
   const path = join(distributionsRoot, REGISTRY_CREDENTIALS_FILE);
-  const raw = JSON.parse(readFileSync(path, 'utf8'));
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {throw error;}
+    throw new Error(
+      `${REGISTRY_CREDENTIALS_FILE} does not exist in ${distributionsRoot}: the editions root declares the registry credentials its images are verified with`,
+      { cause: error },
+    );
+  }
+  const raw = JSON.parse(text);
   const keys = Object.keys(raw ?? {}).sort().join(',');
   if (
     typeof raw !== 'object' ||

package/edition/release-edition-artifact.mjs

@@ -2,12 +2,12 @@
 // release-edition-artifact — write the OCI artifact of a RELEASE edition from
 // the committed, sealed locks of the editions root.
 //
-//   artifact <id> --channel release --registry <namespace> --coordinate <tag>
+//   artifact <id> --channel release --registry <root> --coordinate <tag>
 //            --engine-image <repository>@sha256:<digest> --out <dir> [--local]
 //
 // The artifact has the layout of every edition (edition-artifact.mjs): the
 // descriptor plus the four locks and the offering's catalogue.json, written to <dir>, and the target
-// `<registry>/xema-edition-<id>:<coordinate>` is printed. The workflow pushes
+// `<root>/<release namespace segment>/xema-edition-<id>:<coordinate>` is printed. The workflow pushes
 // <dir> with oras and signs the manifest DIGEST with cosign; the tag is for
 // humans. A lock set that is not sealed is refused: an unsealed images lock names
 // no image digests, so nothing could be admitted against it.
@@ -128,7 +128,7 @@ export async function readCommittedEdition(id, root = editionsRoot()) {
 
 async function run(argv, env) {
   const { id, options } = parseReleaseArtifactArgs(argv);
-  const target = editionTarget(id, options['--registry'], options['--coordinate']);
+  const target = editionTarget(id, options['--registry'], EditionChannel.Release, options['--coordinate']);
   const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
   const locks = await readCommittedEdition(id);
   // Refuses (EvidenceTrustRequiredError) unless the policy is ARMED on the

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 };
 }
 
 /**