@xemahq/xema 0.59.1 → 0.60.1

package/edition/catalogue.mjs

@@ -1,223 +0,0 @@
-// 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` is provenance only: no reader branches on it.
-
-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 { 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'];
-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`);}
-  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

@@ -1,97 +0,0 @@
-// `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);
-  });
-}