@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/catalogue.mjs

@@ -0,0 +1,237 @@
+// catalogue — what an offering's edition artifact offers to a customer edition.
+//
+// `catalogue.json` is one more titled layer of an offering's edition artifact
+// (edition-artifact.mjs): the availability, pins, image digests, chart-set and
+// declared ceiling of the offering, and NOTHING that can add a component. A
+// customer edition is resolved against it (resolve-customer-edition.mjs) by the
+// digest of the artifact that carries it.
+//
+// `channel` selects the `kernel` row's shape and nothing else (kernel-pin-source.mjs): a release row names the published
+// package (name, version, integrity); a develop row names the member checkout (repositoryUrl, sourceCommit, contentDigest).
+
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { EDITION_OFFERING_LAYERS, EditionChannel } from './edition-constants.mjs';
+import { isKernelFromMember } from './kernel-pin-source.mjs';
+import { serializeJson } from './lib.mjs';
+import { verifiedPlatformServiceIndex } from './platform-service-ownership.mjs';
+
+export const CATALOGUE_FILE = EDITION_OFFERING_LAYERS.catalogue;
+// v2 (edition protocol v8): `ceiling.storePublisherTrust`, the Store publishers the offering
+// vouches for, from which a customer definition selects (`storePublisherAnchorKeys`).
+export const CATALOGUE_SCHEMA = 'xema.edition-catalogue/v2';
+
+const TOP_KEYS = ['schema', 'offeringId', 'channel', 'biomes', 'sourceTreeIds', 'platformServices', 'images', 'chartSet', 'contractAuthority', 'kernel', 'ceiling'];
+const IMAGES_KEYS = ['sourceHashAlgorithm', 'subjects', 'platformServiceBindings', 'webBiomes'];
+const CEILING_KEYS = ['trustPolicy', 'trustCeiling', 'storePublisherTrust'];
+const KERNEL_KEYS = ['name', 'version', 'integrity'];
+// A develop catalogue's kernel is the pinned member checkout, not a published package: its identity, no version.
+const DEVELOP_KERNEL_KEYS = ['repositoryUrl', 'sourceCommit', 'contentDigest'];
+const KERNEL_PACKAGE = '@xemahq/contracts';
+const EXACT_SEMVER = /^\d+\.\d+\.\d+$/;
+const NPM_INTEGRITY = /^sha512-[A-Za-z0-9+/]{86}==$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const GIT_TREE_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
+export class CatalogueError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CatalogueError';
+  }
+}
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function exactKeys(value, keys, where) {
+  if (!isObject(value) || Object.keys(value).sort().join() !== [...keys].sort().join()) {
+    throw new CatalogueError(`${where} must be exactly {${keys.join(', ')}}`);
+  }
+}
+
+/** The strict parse of a catalogue: exact keys, closed vocabularies, every image row sealed. Returns it unchanged. */
+export function parseCatalogue(value) {
+  exactKeys(value, TOP_KEYS, CATALOGUE_FILE);
+  if (value.schema !== CATALOGUE_SCHEMA) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: schema is ${JSON.stringify(value.schema)}, expected ${JSON.stringify(CATALOGUE_SCHEMA)}`);
+  }
+  assertCanonicalDistributionId(value.offeringId);
+  if (!Object.values(EditionChannel).includes(value.channel)) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: channel must be one of ${Object.values(EditionChannel).join(' | ')}`);
+  }
+  if (!Array.isArray(value.biomes) || value.biomes.some((row) => !isObject(row) || typeof row.id !== 'string')) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: biomes must be an array of biome-index rows`);
+  }
+  // `sourceTreeIds` is the vendor's git tree id of each biome at its pinned commit. A customer holds no
+  // checkout of the vendor source, so it takes these ON THIS CATALOGUE'S AUTHORITY (biome-content.mjs).
+  if (!isObject(value.sourceTreeIds)) {throw new CatalogueError(`${CATALOGUE_FILE}: sourceTreeIds must map each biome id to its git tree id`);}
+  const rowIds = value.biomes.map((row) => row.id).sort();
+  const treeIdKeys = Object.keys(value.sourceTreeIds).sort();
+  if (JSON.stringify(rowIds) !== JSON.stringify(treeIdKeys)) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: sourceTreeIds must name exactly the biomes of \`biomes\` (biomes: ${rowIds.join(',')}; tree ids: ${treeIdKeys.join(',')})`);
+  }
+  for (const [biomeId, treeId] of Object.entries(value.sourceTreeIds)) {
+    if (!GIT_TREE_ID.test(String(treeId))) {throw new CatalogueError(`${CATALOGUE_FILE}: sourceTreeIds.${biomeId} is not a git tree id (40 or 64 lowercase hex)`);}
+  }
+  if (!Array.isArray(value.platformServices) || value.platformServices.some((row) => !isObject(row) || typeof row.name !== 'string')) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: platformServices must be an array of platform-service-index rows`);
+  }
+  exactKeys(value.images, IMAGES_KEYS, `${CATALOGUE_FILE} images`);
+  for (const key of IMAGES_KEYS.slice(1)) {
+    if (!Array.isArray(value.images[key])) {throw new CatalogueError(`${CATALOGUE_FILE}: images.${key} must be an array`);}
+  }
+  const unsealed = value.images.subjects.filter((subject) => !DIGEST.test(String(subject?.imageDigest)));
+  if (unsealed.length > 0) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: ${unsealed.length} image rows carry no imageDigest (first: ${unsealed[0]?.kind}:${unsealed[0]?.id}); a catalogue offers sealed images only`);
+  }
+  if (!isObject(value.chartSet)) {throw new CatalogueError(`${CATALOGUE_FILE}: chartSet must be the offering's chart-set lock`);}
+  if (!isObject(value.contractAuthority)) {throw new CatalogueError(`${CATALOGUE_FILE}: contractAuthority must be the runtime image source index's authority`);}
+  if (isKernelFromMember(value.channel)) {
+    // develop: the row is the contract authority's own checkout identity; it never names a version or an integrity.
+    exactKeys(value.kernel, DEVELOP_KERNEL_KEYS, `${CATALOGUE_FILE} kernel (develop)`);
+    for (const key of DEVELOP_KERNEL_KEYS) {
+      if (typeof value.kernel[key] !== 'string' || value.kernel[key] !== value.contractAuthority[key]) {
+        throw new CatalogueError(`${CATALOGUE_FILE}: a develop catalogue's kernel.${key} must equal its contractAuthority.${key}`);
+      }
+    }
+  } else {
+    exactKeys(value.kernel, KERNEL_KEYS, `${CATALOGUE_FILE} kernel`);
+    if (value.kernel.name !== KERNEL_PACKAGE) {throw new CatalogueError(`${CATALOGUE_FILE}: kernel.name must be ${KERNEL_PACKAGE}, not ${JSON.stringify(value.kernel.name)}`);}
+    if (typeof value.kernel.version !== 'string' || !EXACT_SEMVER.test(value.kernel.version)) {
+      throw new CatalogueError(`${CATALOGUE_FILE}: kernel.version must be an exact x.y.z version, not ${JSON.stringify(value.kernel.version)}`);
+    }
+    if (typeof value.kernel.integrity !== 'string' || !NPM_INTEGRITY.test(value.kernel.integrity)) {
+      throw new CatalogueError(`${CATALOGUE_FILE}: kernel.integrity must be an npm sha512 integrity (sha512-<base64>)`);
+    }
+  }
+  exactKeys(value.ceiling, CEILING_KEYS, `${CATALOGUE_FILE} ceiling`);
+  return value;
+}
+
+/**
+ * The catalogue of one resolved offering. Biome and platform-service rows are
+ * exactly those the offering's distribution lock ships (an offering that draws
+ * from a declared source is not a vendor offering and is refused).
+ */
+export function buildCatalogue({
+  offeringId,
+  channel,
+  distributionLock,
+  imageLock,
+  chartSetLock,
+  biomeIndex,
+  platformServiceIndex,
+  contractAuthority,
+  kernel,
+  leaf,
+  sourceTreeIds,
+  readManifest,
+}) {
+  const sourced = distributionLock.biomes.filter((biome) => biome.source !== undefined);
+  if (sourced.length > 0) {
+    throw new CatalogueError(`offering "${offeringId}" draws ${sourced.map((b) => b.id).join(', ')} from a declared source; only a vendor offering publishes a catalogue`);
+  }
+  const shippedBiomes = new Set(distributionLock.biomes.map((biome) => biome.id));
+  const shippedServices = new Set(distributionLock.platformServices.map((service) => service.name));
+  const biomes = biomeIndex.filter((row) => shippedBiomes.has(row.id));
+  const missing = [...shippedBiomes].filter((id) => !biomes.some((row) => row.id === id));
+  if (missing.length > 0) {throw new CatalogueError(`offering "${offeringId}": the biome index has no row for ${missing.join(', ')}`);}
+  // The customer trusts this catalogue's ownership rows without sources, so they are
+  // re-derived from the pinned manifests here, before the catalogue seals.
+  const platformServices = verifiedPlatformServiceIndex(platformServiceIndex, { names: shippedServices, readManifest }).services.filter((row) => shippedServices.has(row.name));
+  return parseCatalogue({
+    schema: CATALOGUE_SCHEMA,
+    offeringId,
+    channel,
+    biomes: [...biomes].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+    sourceTreeIds,
+    platformServices: [...platformServices].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+    images: {
+      sourceHashAlgorithm: imageLock.sourceHashAlgorithm,
+      subjects: imageLock.subjects,
+      platformServiceBindings: imageLock.platformServiceBindings,
+      webBiomes: imageLock.webBiomes,
+    },
+    chartSet: chartSetLock,
+    contractAuthority,
+    kernel,
+    ceiling: {
+      trustPolicy: leaf?.trustPolicy ?? null,
+      trustCeiling: leaf?.trustCeiling ?? null,
+      // The Store publishers the offering's lock vouches for: a customer edition copies only those it selects.
+      storePublisherTrust: distributionLock.storePublisherTrust ?? null,
+    },
+  });
+}
+
+/** A customer lock outside its catalogue's ceiling, or a selection or dependency the catalogue does not offer. */
+export class CatalogueCeilingError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CatalogueCeilingError';
+  }
+}
+
+/**
+ * The catalogue's declared ceiling, read by the kernel's grammars: `trustPolicy` is the offering's
+ * origin allow list, `trustCeiling` its trust-domain assignments, `storePublisherTrust` the Store
+ * publishers the offering vouches for (each a kernel `LockedStorePublisher`). `null` states none.
+ */
+export function catalogueCeiling(catalogue, schemas) {
+  const read = (key, schema) => {
+    const value = catalogue.ceiling[key];
+    if (value === null) {return undefined;}
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+      throw new CatalogueError(
+        `${CATALOGUE_FILE}: ceiling.${key} of "${catalogue.offeringId}" is not the kernel's shape: ` +
+          parsed.error.issues.map((issue) => `[${issue.path.join('.')}] ${issue.message}`).join('; '),
+      );
+    }
+    return parsed.data;
+  };
+  return {
+    trustPolicy: read('trustPolicy', schemas.DistributionTrustPolicySchema),
+    trustCeiling: read('trustCeiling', schemas.ProcessTrustPolicySchema),
+    storePublisherTrust: read('storePublisherTrust', schemas.LockedStorePublisherSchema.array()),
+  };
+}
+
+/**
+ * The Store publishers a customer lock carries: the entries of the catalogue's parsed ceiling
+ * (`catalogueCeiling(...).storePublisherTrust`) whose anchorKey the definition selects
+ * (`storePublisherAnchorKeys`), copied as they are. No selection, or none of it offered, is no
+ * field; a key the catalogue does not vouch for is refused by the kernel's ceiling check, not here.
+ */
+export function selectedStorePublisherTrust(base, storePublisherAnchorKeys) {
+  if (storePublisherAnchorKeys === undefined) {return undefined;}
+  const selected = new Set(storePublisherAnchorKeys);
+  const rows = (base ?? []).filter((row) => selected.has(row.anchorKey));
+  return rows.length > 0 ? rows : undefined;
+}
+
+/**
+ * The kernel's `customerLockCeilingIssues` is the one check of a customer lock against its catalogue:
+ * the biomes' trust ceilings, and the Store publishers (base = the catalogue's, selected = the
+ * definition's `storePublisherAnchorKeys`, customer = the lock's).
+ */
+export function assertCustomerLockWithinCatalogueCeiling({ schemas, catalogue, lock, storePublisherAnchorKeys }) {
+  const ceiling = catalogueCeiling(catalogue, schemas);
+  const issues = schemas.customerLockCeilingIssues(ceiling.trustCeiling, lock.biomes, {
+    base: ceiling.storePublisherTrust,
+    selected: storePublisherAnchorKeys,
+    customer: lock.storePublisherTrust,
+  });
+  if (issues.length > 0) {
+    throw new CatalogueCeilingError(`catalogue "${catalogue.offeringId}" (${catalogue.channel}): "${lock.distributionId}" is outside the catalogue's ceiling: ${issues.join('; ')}`);
+  }
+}
+
+/** Write `catalogue.json` into an artifact directory (deterministic serialization); returns its path. */
+export function writeCatalogue(outDir, catalogue) {
+  parseCatalogue(catalogue);
+  const path = join(outDir, CATALOGUE_FILE);
+  writeFileSync(path, serializeJson(catalogue));
+  return path;
+}

package/edition/chart-set-source-commit.mjs

@@ -0,0 +1,97 @@
+// `xema-edition chart-set source-commit` - the commit each chart-set publisher
+// closed its LOCKED set at.
+//
+// The publisher stamps its index chart with `xema.dev/chart-set-source-sha`
+// next to `xema.dev/chart-set-charts`. This verb reads that stamp from the index
+// chart at the digest the committed fleet `chart-set.lock.json` pins and prints one JSON document. It refuses,
+// printing nothing, when the stamp is absent or is not a 40-hex commit, when the
+// registry does not serve the locked digest, or when the index's roster is not
+// the one the lock records for that publisher: the commit it would name would then be
+// the commit of a different set than the locked one.
+
+import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import { serializeJson } from './lib.mjs';
+import {
+  CHART_SET_LOCK_FILE,
+  INDEX_ROSTER_ANNOTATION,
+  chartRegistryClient,
+  chartSetLockPath,
+  manifestAnnotations,
+  parseIndexRoster,
+  readLock,
+  registryRepository,
+} from './resolve-chart-set.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Kernel]);
+}
+
+export const CHART_SET_SOURCE_SCHEMA = 'xema.edition-chart-set-source/v1';
+export const INDEX_SOURCE_ANNOTATION = 'xema.dev/chart-set-source-sha';
+
+/** Why the index's roster is not the lock's roster for the publisher, or null when they are the same set. */
+function rosterDifference(lockCharts, indexRoster) {
+  const names = [...new Set([...Object.keys(lockCharts), ...Object.keys(indexRoster)])].sort();
+  for (const name of names) {
+    const locked = lockCharts[name];
+    const indexed = indexRoster[name];
+    if (locked === undefined) {return `the index carries ${name}, which the lock does not`;}
+    if (indexed === undefined) {return `the lock records ${name}, which the index does not carry`;}
+    if (locked.version !== indexed.version) {
+      return `${name} is ${indexed.version} in the index and ${locked.version} in the lock`;
+    }
+    if (indexed.digest !== undefined && indexed.digest !== locked.digest) {
+      return `${name}:${locked.version} is ${indexed.digest} in the index and ${locked.digest} in the lock`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The source-commit document for every publisher of `lock`, read through
+ * `client` (the chart registry client). Throws on the first refusal.
+ */
+export async function chartSetSourceCommits({ client, lock }) {
+  const publishers = [];
+  for (const { index, repo, version, indexDigest, charts } of lock.publishers) {
+    const label = `${index}@${version}`;
+    // The index is read BY the digest the lock pins, so a re-pushed tag cannot answer.
+    const served = await client.getManifestByDigest(registryRepository(index), indexDigest);
+    if (served.digest !== indexDigest) {
+      throw new Error(`${label}: the registry served index manifest ${served.digest} but ${CHART_SET_LOCK_FILE} pins ${indexDigest}`);
+    }
+    const annotations = await manifestAnnotations(client, index, version, served);
+    const difference = rosterDifference(charts, parseIndexRoster(annotations[INDEX_ROSTER_ANNOTATION], label));
+    if (difference !== null) {
+      throw new Error(`${label}: the index roster is not the set ${CHART_SET_LOCK_FILE} locks (${difference}), so its source commit is not the locked set's`);
+    }
+    const sourceCommit = annotations[INDEX_SOURCE_ANNOTATION];
+    if (typeof sourceCommit !== 'string' || !COMMIT_PATTERN.test(sourceCommit)) {
+      throw new Error(`${label} carries no ${INDEX_SOURCE_ANNOTATION} that is a 40 lowercase hex commit (got ${JSON.stringify(sourceCommit)})`);
+    }
+    publishers.push({ index, repo, version, sourceCommit });
+  }
+  return { schema: CHART_SET_SOURCE_SCHEMA, publishers };
+}
+
+async function main(argv) {
+  if (argv.length > 0) {
+    throw new Error(`unexpected argument "${argv[0]}"; usage: xema-edition chart-set source-commit --data-root <dir> --kernel <dir>`);
+  }
+  const lock = readLock();
+  if (lock === null) {
+    throw new Error(`${chartSetLockPath()} is missing or is not JSON: run 'xema-edition chart-set resolve' first`);
+  }
+  assertRosteredChartSetLock(lock, CHART_SET_LOCK_FILE);
+  const document = await chartSetSourceCommits({ client: chartRegistryClient(), lock });
+  process.stdout.write(serializeJson(document));
+}
+
+if (isEntryModule(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`chart-set source-commit: ${error.message}\n`);
+    process.exit(1);
+  });
+}