@xemahq/xema 0.59.0 → 0.60.1

package/edition/resolve-customer-edition.mjs

@@ -1,374 +0,0 @@
-// resolve-customer-edition — resolve a CUSTOMER edition against a catalogue.
-//
-//   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 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
-// dependencies; a component the offering gains later stays out unless selected.
-// Vendor image rows are COPIED from the catalogue (re-homed under the declared
-// imageRegistryMirror, digests untouched); the customer's own sources resolve
-// as they always have.
-
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { isDeepStrictEqual } from 'node:util';
-
-import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest } from './adapter-bundled-versions.mjs';
-import { AUTHORIZATION_LOCK_FILENAME, writeAuthorizationLock } from './authorization-base.mjs';
-import { catalogueLockFieldOf } from './catalogue-lock-field.mjs';
-import {
-  assertCustomerLockWithinCatalogueCeiling,
-  CatalogueCeilingError,
-  CatalogueError,
-  catalogueCeiling,
-  selectedStorePublisherTrust,
-} from './catalogue.mjs';
-import {
-  assertTrustCeilingAssignsCustomerBiomes,
-  mirrorVendorSubjects,
-  parseCustomerDefinition,
-  parseImageRegistryMirror,
-} from './customer-definition.mjs';
-import { assertNoUnverifiedRequiredGitBundles } from './develop-git-bundles.mjs';
-import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
-import { EditionChannel, EditionLockFile } from './edition-constants.mjs';
-import { editionsRoot } from './edition-workspace.mjs';
-import { subjectServingBiome } from './image-lock-service-rows.mjs';
-import { adoptCatalogueKernel } from './kernel-package.mjs';
-import { compareStrings, imageLockWriteSchemaVersion, serializeJson, validateImmutableImageLock } from './lib.mjs';
-import { pinnedSource, snapshotPinSource } from './pin-source.mjs';
-import { composeAuthorizationBase, composeManifest, resolveDistributionWithIndex, UnknownSelectionError } from './resolve-distribution.mjs';
-import { resolveImageRows } from './resolve-images.mjs';
-
-export { CatalogueCeilingError };
-
-/** A catalogue whose ceiling states no trust-domain assignments reserves no domain: the kernel's required ceiling argument is the empty policy. */
-const NO_CATALOGUE_TRUST_CEILING = Object.freeze({ assignments: [] });
-
-/**
- * The ceiling policy the customer's lock is written under: the catalogue's assignments, then
- * the definition's for what the catalogue leaves open. An assignment of the definition that
- * names a domain the catalogue assigns, or a biome the catalogue places, is not carried: the
- * catalogue's reading stands, and the kernel's `customerLockCeilingIssues` refuses the difference in the lock.
- */
-function ceilingUnderCatalogue(catalogueTrustCeiling, definitionTrustCeiling) {
-  if (catalogueTrustCeiling === undefined) {return definitionTrustCeiling;}
-  const domains = new Set(catalogueTrustCeiling.assignments.map((assignment) => assignment.domain));
-  const placed = new Set(catalogueTrustCeiling.assignments.flatMap((assignment) => assignment.biomes));
-  const open = (definitionTrustCeiling?.assignments ?? [])
-    .filter((assignment) => !domains.has(assignment.domain))
-    .map((assignment) => ({ domain: assignment.domain, biomes: assignment.biomes.filter((biome) => !placed.has(biome)) }))
-    .filter((assignment) => assignment.biomes.length > 0);
-  return { assignments: [...catalogueTrustCeiling.assignments, ...open] };
-}
-
-/** `{name -> {imageRegistry, imageNamePrefix}}` from repeated `<source>=<registry>/<prefix>` values; the prefix is the text after the last "/". */
-export function parseSourceImages(values) {
-  const byName = new Map();
-  for (const value of values) {
-    const eq = value.indexOf('=');
-    const slash = value.lastIndexOf('/');
-    if (eq <= 0 || slash < eq + 2) {
-      throw new Error(`--source-image ${JSON.stringify(value)} is not <source>=<registry>/<prefix> (the prefix may be empty: "<source>=<registry>/")`);
-    }
-    const name = value.slice(0, eq);
-    if (byName.has(name)) {throw new Error(`--source-image names source "${name}" twice`);}
-    byName.set(name, { imageRegistry: value.slice(eq + 1, slash), imageNamePrefix: value.slice(slash + 1) });
-  }
-  return byName;
-}
-
-/**
- * The definition's sources with the configured registry/prefix injected; every declared source needs its --source-image.
- * With `pins` (a develop customer edition) each source's ref is the frozen commit of its `sources/<name>` pin.
- */
-/** Every --source-image names a declared source, and every declared source has one: the registry is configuration and has no default. */
-export function assertSourceImagesCoverDefinition(definition, sourceImages) {
-  const declared = new Set((definition.sources ?? []).map((source) => source.name));
-  for (const name of sourceImages.keys()) {
-    if (!declared.has(name)) {throw new Error(`--source-image names source "${name}", which the definition does not declare (declared: ${[...declared].join(', ') || 'none'})`);}
-  }
-  for (const name of declared) {
-    if (!sourceImages.has(name)) {throw new Error(`source "${name}" has no --source-image ${name}=<registry>/<prefix>: the registry is configuration and has no default`);}
-  }
-}
-
-function withSourceImages(definition, sourceImages, pins) {
-  assertSourceImagesCoverDefinition(definition, sourceImages);
-  return (definition.sources ?? []).map((source) => {
-    const image = sourceImages.get(source.name);
-    const pinned = pins === undefined ? source : pinnedSource(source, snapshotPinSource(pins));
-    return { ...pinned, ...image };
-  });
-}
-
-/** The composition of a customer definition over the catalogue. */
-export function composeCustomerEdition({ schemas, definition, mirror, catalogue, sourceImages, pins }) {
-  const ceiling = catalogueCeiling(catalogue, schemas);
-  // `storePublisherAnchorKeys` selects from the catalogue (`selectedStorePublisherTrust`); the Distribution manifest is strict and has no such key.
-  const { storePublisherAnchorKeys: _selection, ...document } = definition;
-  const manifest = schemas.parseDistribution({ ...document, ...(definition.sources === undefined ? {} : { sources: withSourceImages(definition, sourceImages, pins) }) });
-  if (definition.sources === undefined && sourceImages.size > 0) {
-    throw new Error('--source-image given, but the definition declares no sources');
-  }
-  const composed = composeManifest(manifest);
-  return {
-    ...composed,
-    // The catalogue is the ceiling: its origin allow list is the one this resolve applies
-    // (a definition states none), and its domain assignments come before the definition's.
-    trustPolicy: ceiling.trustPolicy,
-    trustCeiling: ceilingUnderCatalogue(ceiling.trustCeiling, composed.trustCeiling),
-    platformServices: new Map(
-      catalogue.platformServices.map((row) => [row.name, { name: row.name, tier: row.tier, installationClass: row.installationClass }]),
-    ),
-    webProducerRepos: [...new Set(catalogue.images.webBiomes.map((biome) => biome.repo))],
-    mirror: parseImageRegistryMirror(mirror),
-  };
-}
-
-const subjectKey = (subject) => `${subject.kind}\0${subject.id}`;
-const compareSubjects = (a, b) => compareStrings(a.kind, b.kind) || compareStrings(a.id, b.id);
-
-/** The vendor image rows of the customer's lock: copied from the catalogue, owners narrowed to the selection. */
-export function projectVendorImages(catalogue, lock, enums) {
-  const biomes = new Set(lock.biomes.filter((biome) => biome.source === undefined).map((biome) => biome.id));
-  const services = new Set(lock.platformServices.map((service) => service.name));
-  const subjects = [];
-  for (const subject of catalogue.images.subjects) {
-    const owners = subject.owners.filter((owner) =>
-      owner.kind === enums.RuntimeImageOwnerKind.Biome ? biomes.has(owner.biomeId) : services.has(owner.platformService),
-    );
-    if (owners.length > 0) {subjects.push({ ...subject, owners });}
-  }
-  for (const biome of lock.biomes.filter((b) => b.source === undefined && b.target !== 'web')) {
-    const shared = new Set(Object.keys(biome.workerImages ?? {}));
-    const wanted = [
-      ...(biome.services ?? []).filter((id) => !shared.has(id)).map((id) => [enums.RuntimeImageSubjectKind.Service, id]),
-      ...(biome.runtimeComponents ?? []).map((id) => [enums.RuntimeImageSubjectKind.RuntimeComponent, id]),
-    ];
-    for (const [kind, id] of wanted) {
-      if (subjectServingBiome(catalogue.images.schemaVersion, subjects, biome.id, kind, id, enums) === undefined) {
-        throw new CatalogueCeilingError(`the catalogue carries no image row for ${kind}:${id} of selected biome "${biome.id}"`);
-      }
-    }
-  }
-  return {
-    subjects,
-    platformServiceBindings: catalogue.images.platformServiceBindings.filter((binding) => services.has(binding.platformService)),
-    webBiomes: catalogue.images.webBiomes.filter((biome) => biomes.has(biome.biomeId)),
-  };
-}
-
-/** 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 OWN lineage of a previous images lock: `previousLock` (the customer edition's own last images lock, its
- * id already held to this edition's) narrowed to the composed-process rows every owner of which is one of this lock's
- * own (customer-sourced) biomes. The vendor rows of a customer lock are the catalogue's (assertVendorRowsAreCatalogueRows)
- * and carry the vendor's generations, never the customer's, so they never enter the customer's own carry-forward.
- * Null (a first seal) stays null.
- */
-export function ownComposedPreviousLock(previousLock, lock, enums) {
-  if (previousLock === null) {return null;}
-  const ownBiomes = new Set(lock.biomes.filter((biome) => biome.source !== undefined).map((biome) => biome.id));
-  const own = (subject) =>
-    subject.kind === enums.RuntimeImageSubjectKind.ComposedProcess &&
-    subject.owners.length > 0 &&
-    subject.owners.every((owner) => owner.kind === enums.RuntimeImageOwnerKind.Biome && ownBiomes.has(owner.biomeId));
-  return { ...previousLock, subjects: previousLock.subjects.filter(own) };
-}
-
-/**
- * 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. `previousLock` (the customer's own previous seal, null for a first
- * seal) carries the own composed artifacts' generations forward (ownComposedPreviousLock).
- */
-export async function resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn, previousLock = null }) {
-  const vendor = projectVendorImages(catalogue, lock, schemas);
-  const vendorSubjects = mirrorVendorSubjects(vendor.subjects, composed.mirror);
-  const ownBiomes = lock.biomes.filter((biome) => biome.source !== undefined);
-  let own = { subjects: [], platformServiceBindings: [], webBiomes: [] };
-  if (ownBiomes.length > 0) {
-    const ownLock = { ...lock, biomes: ownBiomes, platformServices: [] };
-    const runtimeImageSourceIndex = {
-      schemaVersion: 2,
-      contractAuthority: catalogue.contractAuthority,
-      repositoryPins: [],
-      producerWorkflowPins: [],
-      platformServiceBindings: [],
-      supplementalSubjects: [],
-      crossRepoBuildInputs: [],
-      buildStepContextDirectories: [],
-    };
-    // 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, previousLock: ownComposedPreviousLock(previousLock, lock, schemas) });
-    // 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`);}
-  const mergedSubjects = [...vendorSubjects, ...own.subjects].sort(compareSubjects);
-  const merged = validateImmutableImageLock(
-    schemas.parseImageLock({
-      schemaVersion: imageLockWriteSchemaVersion(schemas, mergedSubjects, `distribution "${id}"`),
-      sourceHashAlgorithm: catalogue.images.sourceHashAlgorithm,
-      distributionId: id,
-      contractAuthority: catalogue.contractAuthority,
-      subjects: mergedSubjects,
-      platformServiceBindings: [...vendor.platformServiceBindings, ...own.platformServiceBindings].sort((a, b) => compareStrings(a.platformService, b.platformService)),
-      webBiomes: [...vendor.webBiomes, ...own.webBiomes].sort((a, b) => compareStrings(a.biomeId, b.biomeId)),
-    }),
-    schemas,
-  );
-  assertVendorRowsAreCatalogueRows({ catalogue, imageLock: merged, lock, mirror: composed.mirror, enums: schemas });
-  return merged;
-}
-
-/**
- * The distribution and authorization locks of the customer edition `rawDefinition`
- * against `catalogue`. Exactly one of `catalogueDigest` (a published catalogue artifact) and `catalogueContentDigest` (the
- * catalogue bytes of a catalogue-free resolve) names `catalogue`; it is written into the lock under its own key. `adoptKernel` (the catalogue's kernel from npm, proved its contract authority; returns the kernel schemas) and `materialize` are injectable for the test suites.
- */
-export async function resolveCustomerDistribution({
-  rawDefinition,
-  catalogue,
-  catalogueDigest,
-  catalogueContentDigest,
-  sourceImages,
-  pins,
-  materialize,
-  adoptKernel = adoptCatalogueKernel,
-  fetchManifest = fetchRegistryManifest,
-  developGitBundles,
-}) {
-  const catalogueField = catalogueLockFieldOf({ catalogueDigest, catalogueContentDigest }, { what: 'a customer resolve', ErrorType: CatalogueError });
-  // Only a develop edition carries a git-sourced OCI bundle (develop-git-bundles.mjs); a release never verifies one.
-  if (developGitBundles !== undefined && catalogue.channel !== EditionChannel.Develop) {
-    throw new Error(`a git-sourced bundle verifier is a develop resolve's; the catalogue "${catalogue.offeringId}" is ${catalogue.channel}`);
-  }
-  const schemas = await adoptKernel(catalogue);
-  const { definition, mirror } = parseCustomerDefinition(schemas, rawDefinition);
-  const composed = composeCustomerEdition({ schemas, definition, mirror, catalogue, sourceImages, pins });
-  const id = composed.leaf.id;
-  // `sourcesAvailable: false`: a customer machine holds no vendor source checkouts, so the platform
-  // services' ownership cannot be re-derived here. It is verified where the catalogue is produced
-  // (`buildCatalogue`), and the catalogue is digest-pinned.
-  // A customer edition carries only the catalogue's Store publishers its definition selects, copied (`storePublisherTrust`).
-  const inputs = {
-    composed,
-    biomeIndex: catalogue.biomes,
-    platformServiceIndex: { schemaVersion: 1, services: catalogue.platformServices },
-    sourcesAvailable: false,
-    storePublisherTrust: selectedStorePublisherTrust(catalogueCeiling(catalogue, schemas).storePublisherTrust, definition.storePublisherAnchorKeys),
-    // A develop resolve under a declared customer policy verifies its git-sourced OCI bundles and keeps them (by digest, with the signer).
-    ...(developGitBundles === undefined ? {} : { developGitBundles }),
-  };
-  let resolved;
-  try {
-    resolved = await resolveDistributionWithIndex(id, { inputs, ...(materialize === undefined ? {} : { materialize }) });
-  } catch (error) {
-    if (error instanceof UnknownSelectionError) {
-      throw new CatalogueCeilingError(`catalogue "${catalogue.offeringId}" (${catalogue.channel}) does not offer what "${id}" needs: ${error.message}`);
-    }
-    throw error;
-  }
-  const { lock, index } = resolved;
-  // Without a verifier no git-sourced OCI bundle is verified, so a required row that declares one is refused, never stripped.
-  // With one, resolve-distribution already refuses every such row it did not verify.
-  if (developGitBundles === undefined) {assertNoUnverifiedRequiredGitBundles({ lock, index, required: schemas.BiomeInstallPolicy.Required });}
-  assertTrustCeilingAssignsCustomerBiomes(
-    schemas,
-    definition,
-    lock.biomes.filter((biome) => biome.source !== undefined).map((biome) => biome.id),
-    catalogueCeiling(catalogue, schemas).trustCeiling ?? NO_CATALOGUE_TRUST_CEILING,
-  );
-  const { storePublisherAnchorKeys } = definition;
-  assertCustomerLockWithinCatalogueCeiling({ schemas, catalogue, lock, storePublisherAnchorKeys });
-  await assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(catalogue.biomes), fetchManifest });
-  const authorizationLock = await composeAuthorizationBase(id, lock, index);
-  // A customer lock names the catalogue it was resolved against; seal and verify refuse any other.
-  return { id, schemas, composed, inputs, lock: { ...lock, [catalogueField.key]: catalogueField.digest }, authorizationLock, storePublisherAnchorKeys };
-}
-
-/**
- * Resolve the customer edition of `channel` against `catalogue`; returns the four locks. `sealOwn` seals the customer's OWN
- * image rows only (a develop edition); vendor rows arrive sealed. `previousSeal` answers the customer's own previous seal
- * (resolvePreviousSeal under this edition's id: null for a first seal), read only after the catalogue's kernel is adopted
- * (it parses with that kernel); its own composed artifacts carry their generation forward. Absent: a first seal.
- */
-export async function resolveCustomerEdition(request) {
-  const { id, schemas, composed, inputs, lock, authorizationLock, storePublisherAnchorKeys } = await resolveCustomerDistribution(request);
-  const { catalogue } = request;
-  const imageLock = await resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn: request.sealOwn, previousLock: request.previousSeal === undefined ? null : await request.previousSeal(id) });
-  // The chart-set is copied whole, so it carries the coordinates of the channel it was published on:
-  // the edition being written states its channel, and a chart-set of the other one is refused here.
-  const chartSetLock = assertRosteredChartSetLock(catalogue.chartSet, `the catalogue's chart-set of "${catalogue.offeringId}"`);
-  // `storePublisherAnchorKeys` (the definition's selection) is what the seal checks the lock's Store publishers against.
-  return { id, distributionLock: lock, imageLock, authorizationLock, chartSetLock, storePublisherAnchorKeys };
-}
-
-/** Write the four locks to `<out>/<id>/` (the layout of an editions root). */
-export function writeCustomerEdition(out, { id, distributionLock, imageLock, authorizationLock, chartSetLock }) {
-  if (out !== editionsRoot()) {throw new CatalogueError(`the customer edition is written into the editions root (${editionsRoot()}), not ${out}`);}
-  const dir = join(out, id);
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, EditionLockFile.Distribution), serializeJson(distributionLock));
-  writeFileSync(join(dir, EditionLockFile.Images), serializeJson(imageLock));
-  writeFileSync(join(dir, EditionLockFile.ChartSet), serializeJson(chartSetLock));
-  writeAuthorizationLock(dir, authorizationLock, serializeJson);
-  return { dir, authorization: AUTHORIZATION_LOCK_FILENAME };
-}