@xemahq/xema 0.59.0 → 0.60.1

package/edition/edition-config.mjs

@@ -1,374 +0,0 @@
-// The deployment-specific coordinates the edition library needs and must not
-// carry: which image registry, chart registry and source
-// organisation a workspace belongs to. They are DATA, read from
-// `<dataRoot>/edition-workspace.json`; there is no default for any of them, and
-// a file with a missing, unknown or malformed key is refused. `evidenceTrustPolicy`
-// declares the data root's evidence gating; its `required` flag has no default.
-// `editionPublishers` names the exact workflow that publishes an edition of each
-// kind on each channel (the shape is edition-contract.json signers.publishers): a
-// customer data root declares its own; a publisher it does not declare is refused
-// when an operation needs it, with no default.
-
-import { join } from 'node:path';
-
-import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
-import { EDITION_PUBLISHER_CHANNELS } from './edition-constants.mjs';
-import { assertPublisher } from './edition-publisher.mjs';
-import { dataRoot } from './edition-workspace.mjs';
-import { CANONICAL_IDENTIFIER } from './evidence-grammars.mjs';
-import { isUnderSourcePrefix } from './git-source-auth.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
-import {
-  parseConfinedBiomes,
-  parseConnectorSources,
-  parseFirstPartySources,
-  parsePinRoles,
-  parsePlatformServiceSources,
-  parseRuntimeImageSources,
-} from './workspace-sections.mjs';
-
-/** A refusal of edition-workspace.json itself. */
-export class EditionWorkspaceConfigError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'EditionWorkspaceConfigError';
-  }
-}
-
-export const EDITION_WORKSPACE_CONFIG_FILE = 'edition-workspace.json';
-export const EDITION_WORKSPACE_CONFIG_SCHEMA_VERSION = 1;
-
-// The product-data sections. Each is optional in the file (a customer data root
-// legitimately has none of some), and each is REQUIRED at the moment an
-// operation reads it: `workspaceSection` refuses a missing one by name.
-const SECTIONS = Object.freeze({
-  firstPartySources: parseFirstPartySources,
-  platformServiceSources: parsePlatformServiceSources,
-  connectorSources: parseConnectorSources,
-  runtimeImageSources: parseRuntimeImageSources,
-  pinRoles: parsePinRoles,
-  confinedBiomes: parseConfinedBiomes,
-});
-
-const KEYS = Object.freeze([
-  'schemaVersion',
-  'imageRegistry',
-  'chartRegistry',
-  'chartPublishers',
-  'sourceRepositoryUrlPrefix',
-  'dataRootRepositoryUrl',
-  'sourceAuthUsername',
-  'evidenceTrustPolicy',
-  'firstPartyBundleSigner',
-  'editionPublishers',
-  ...Object.keys(SECTIONS),
-]);
-
-const IMAGE_REGISTRY = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
-const CHART_REGISTRY = /^oci:\/\/[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
-// A data-root-relative POSIX path: no leading slash, no empty, `.` or `..` segment.
-const DATA_ROOT_RELATIVE_PATH = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
-const SOURCE_URL_PREFIX = /^https:\/\/[a-z0-9.-]+(\/[A-Za-z0-9._-]+)+\/$/;
-
-function requireString(config, key, pattern, shape) {
-  const value = config[key];
-  if (typeof value !== 'string' || !pattern.test(value)) {
-    throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: "${key}" must be ${shape}; got ${JSON.stringify(value)}`);
-  }
-  return value;
-}
-
-/** The git username first-party sources authenticate as: declared, never defaulted (GitHub says `x-access-token`, other forges differ). */
-function requireSourceAuthUsername(config) {
-  const value = config.sourceAuthUsername;
-  if (typeof value !== 'string' || value.length === 0 || /[\s:]/.test(value)) {
-    throw new EditionWorkspaceConfigError(
-      `${EDITION_WORKSPACE_CONFIG_FILE}: "sourceAuthUsername" is required: the non-empty git username (no whitespace or ":") ` +
-        `that first-party source tokens authenticate as; got ${JSON.stringify(value)}`,
-    );
-  }
-  return value;
-}
-
-/** `chartRegistry` and `chartPublishers` are a vendor-only pair: both declared or both absent. */
-function optionalChartSet(document) {
-  const registry = document.chartRegistry !== undefined;
-  const publishers = document.chartPublishers !== undefined;
-  if (registry !== publishers) {
-    throw new EditionWorkspaceConfigError(
-      `${EDITION_WORKSPACE_CONFIG_FILE}: "chartRegistry" and "chartPublishers" are a vendor-only pair, both declared or both absent; only "${registry ? 'chartRegistry' : 'chartPublishers'}" is`,
-    );
-  }
-  if (!registry) {return {};}
-  return {
-    chartRegistry: requireString(document, 'chartRegistry', CHART_REGISTRY, 'oci://<host>/<path>'),
-    chartPublishers: requirePublishers(document),
-  };
-}
-
-function requirePublishers(config) {
-  const value = config.chartPublishers;
-  if (!Array.isArray(value) || value.length === 0) {
-    throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: "chartPublishers" must be a non-empty array of {index, repo}`);
-  }
-  const seen = new Set();
-  return Object.freeze(
-    value.map((entry) => {
-      const keys = entry !== null && typeof entry === 'object' ? Object.keys(entry).sort() : [];
-      if (keys.join() !== 'index,repo' || typeof entry.index !== 'string' || typeof entry.repo !== 'string' || !entry.index || !entry.repo) {
-        throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: every "chartPublishers" entry is exactly {index, repo}, both non-empty strings`);
-      }
-      if (seen.has(entry.index)) {
-        throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: duplicate chart publisher index "${entry.index}"`);
-      }
-      seen.add(entry.index);
-      return Object.freeze({ index: entry.index, repo: entry.repo });
-    }),
-  );
-}
-
-const EVIDENCE_TRUST_POLICY_KEYS = Object.freeze(['pin', 'policy']);
-
-function isDataRootRelativePath(value) {
-  return (
-    typeof value === 'string' &&
-    DATA_ROOT_RELATIVE_PATH.test(value) &&
-    value.split('/').every((segment) => segment !== '.' && segment !== '..')
-  );
-}
-
-/**
- * The MANDATORY `evidenceTrustPolicy` declaration: `{policy, pin}` (two
- * data-root-relative paths) or `null`, the explicit statement that this data
- * root declares no policy. There is no switch that admits an ungated release:
- * a release edition is written only against a policy ARMED on the release
- * channel, so a data root that declares none serves develop editions only.
- */
-function requireEvidenceTrustPolicy(config) {
-  if (!Object.hasOwn(config, 'evidenceTrustPolicy')) {
-    throw new EditionWorkspaceConfigError(
-      `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy" is required: {"policy": ..., "pin": ...}, ` +
-        'or null to state that this data root declares no policy (no release edition can then be sealed from it)',
-    );
-  }
-  const value = config.evidenceTrustPolicy;
-  if (value === null) {return Object.freeze({ policy: null, pin: null });}
-  const shapeError = (detail) =>
-    new EditionWorkspaceConfigError(
-      `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy" is exactly null or {policy, pin} with both paths data-root-relative${detail}`,
-    );
-  if (typeof value !== 'object' || Array.isArray(value)) {throw shapeError('');}
-  const keys = Object.keys(value).sort();
-  const unknown = keys.filter((key) => !EVIDENCE_TRUST_POLICY_KEYS.includes(key));
-  if (unknown.length > 0) {throw shapeError(`; unknown key ${unknown.map((key) => `"${key}"`).join(', ')}`);}
-  if (keys.join() !== EVIDENCE_TRUST_POLICY_KEYS.join()) {throw shapeError('');}
-  for (const key of EVIDENCE_TRUST_POLICY_KEYS) {
-    if (!isDataRootRelativePath(value[key])) {
-      throw new EditionWorkspaceConfigError(
-        `${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy.${key}" must be a data-root-relative POSIX path without "." or ".." segments; got ${JSON.stringify(value[key])}`,
-      );
-    }
-  }
-  if (value.policy === value.pin) {
-    throw new EditionWorkspaceConfigError(`${EDITION_WORKSPACE_CONFIG_FILE}: "evidenceTrustPolicy.policy" and ".pin" must be different files`);
-  }
-  return Object.freeze({ policy: value.policy, pin: value.pin });
-}
-
-/**
- * The OPTIONAL `firstPartyBundleSigner` declaration: exactly `{policyId}`, naming the one `public-key` row of the
- * evidence trust policy that signs the data root's first-party OCI bundles. No default: a data root that does not
- * declare it cannot seal a first-party OCI bundle row.
- */
-function optionalFirstPartyBundleSigner(document) {
-  if (document.firstPartyBundleSigner === undefined) {return {};}
-  const value = document.firstPartyBundleSigner;
-  const where = `${EDITION_WORKSPACE_CONFIG_FILE}: "firstPartyBundleSigner"`;
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    throw new EditionWorkspaceConfigError(`${where} must be exactly {"policyId": "<canonical id>"}; got ${JSON.stringify(value)}`);
-  }
-  const keys = Object.keys(value);
-  const unknown = keys.filter((key) => key !== 'policyId');
-  if (unknown.length > 0) {
-    throw new EditionWorkspaceConfigError(`${where} has unknown key ${unknown.map((key) => `"${key}"`).join(', ')}; it is exactly {"policyId": "<canonical id>"}`);
-  }
-  if (!Object.hasOwn(value, 'policyId')) {
-    throw new EditionWorkspaceConfigError(`${where} is missing "policyId"; it is exactly {"policyId": "<canonical id>"}`);
-  }
-  if (typeof value.policyId !== 'string' || !CANONICAL_IDENTIFIER.test(value.policyId)) {
-    throw new EditionWorkspaceConfigError(`${where}.policyId must be a canonical policy id; got ${JSON.stringify(value.policyId)}`);
-  }
-  return { firstPartyBundleSigner: Object.freeze({ policyId: value.policyId }) };
-}
-
-/**
- * Every first-party repository URL is canonical and under the workspace's
- * `sourceRepositoryUrlPrefix`: the develop graph sends the source token there.
- */
-function assertFirstPartyUrls(firstPartySources, prefix) {
-  for (const [repo, { repositoryUrl }] of Object.entries(firstPartySources)) {
-    const where = `${EDITION_WORKSPACE_CONFIG_FILE}: "firstPartySources"["${repo}"].repositoryUrl`;
-    let canonical;
-    try {
-      canonical = canonicalPublicHttpsRepositoryUrl(repositoryUrl, where);
-    } catch (err) {
-      throw new EditionWorkspaceConfigError(err.message);
-    }
-    if (canonical !== repositoryUrl) {
-      throw new EditionWorkspaceConfigError(`${where} ${JSON.stringify(repositoryUrl)} is not in its canonical form (${canonical})`);
-    }
-    if (!isUnderSourcePrefix(canonical, prefix)) {
-      throw new EditionWorkspaceConfigError(`${where} ${JSON.stringify(repositoryUrl)} is not under sourceRepositoryUrlPrefix ${prefix}`);
-    }
-  }
-}
-
-/**
- * The OPTIONAL `dataRootRepositoryUrl`: where the data root itself lives, in the canonical public HTTPS form
- * and under `sourceRepositoryUrlPrefix` like a first-party repository. It names the record signer
- * (the data root's reusable workflows); a data root that does not declare it simply cannot be named as one.
- */
-function optionalDataRootRepositoryUrl(document, prefix) {
-  if (document.dataRootRepositoryUrl === undefined) {return {};}
-  const where = `${EDITION_WORKSPACE_CONFIG_FILE}: "dataRootRepositoryUrl"`;
-  let canonical;
-  try {
-    canonical = canonicalPublicHttpsRepositoryUrl(document.dataRootRepositoryUrl, where);
-    repositoryOwnerName(canonical, where);
-  } catch (err) {
-    throw new EditionWorkspaceConfigError(err.message);
-  }
-  if (canonical !== document.dataRootRepositoryUrl) {
-    throw new EditionWorkspaceConfigError(`${where} ${JSON.stringify(document.dataRootRepositoryUrl)} is not in its canonical form (${canonical})`);
-  }
-  if (!isUnderSourcePrefix(canonical, prefix)) {
-    throw new EditionWorkspaceConfigError(`${where} ${JSON.stringify(canonical)} is not under sourceRepositoryUrlPrefix ${prefix}`);
-  }
-  return { dataRootRepositoryUrl: canonical };
-}
-
-/**
- * The OPTIONAL `editionPublishers`: `{<kind>: {<channel>: {repository, workflow, ref}}}`, only the kinds and channels
- * edition-contract.json signers.publishers.channelsByKind names, each publisher in the contract's shape. A data root
- * may declare a subset; an empty kind, an unknown kind or channel, or a malformed publisher is refused.
- */
-function optionalEditionPublishers(document) {
-  const value = document.editionPublishers;
-  if (value === undefined) {return {};}
-  const where = `${EDITION_WORKSPACE_CONFIG_FILE}: "editionPublishers"`;
-  const isObject = (entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry);
-  if (!isObject(value) || Object.keys(value).length === 0) {
-    throw new EditionWorkspaceConfigError(`${where} must be a non-empty {<kind>: {<channel>: {repository, workflow, ref}}}`);
-  }
-  const parsed = {};
-  for (const [kind, byChannel] of Object.entries(value)) {
-    const channels = EDITION_PUBLISHER_CHANNELS[kind];
-    if (channels === undefined) {
-      throw new EditionWorkspaceConfigError(`${where} names kind "${kind}"; edition-contract.json signers.publishers.channelsByKind names ${Object.keys(EDITION_PUBLISHER_CHANNELS).join(' | ')}`);
-    }
-    if (!isObject(byChannel) || Object.keys(byChannel).length === 0) {
-      throw new EditionWorkspaceConfigError(`${where}.${kind} must be a non-empty {<channel>: {repository, workflow, ref}}`);
-    }
-    parsed[kind] = {};
-    for (const [channel, publisher] of Object.entries(byChannel)) {
-      if (!channels.includes(channel)) {
-        throw new EditionWorkspaceConfigError(`${where}.${kind} names channel "${channel}"; a ${kind} edition has a publisher on ${channels.join(' | ')} only`);
-      }
-      try {
-        parsed[kind][channel] = Object.freeze({ ...assertPublisher(publisher, `${where}.${kind}.${channel}`) });
-      } catch (error) {
-        throw new EditionWorkspaceConfigError(error.message);
-      }
-    }
-    Object.freeze(parsed[kind]);
-  }
-  return { editionPublishers: Object.freeze(parsed) };
-}
-
-/** Validate a parsed config document; returns the frozen, typed config. */
-export function parseEditionWorkspaceConfig(document) {
-  if (document === null || typeof document !== 'object' || Array.isArray(document)) {
-    throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE} must be a JSON object`);
-  }
-  for (const key of Object.keys(document)) {
-    if (!KEYS.includes(key)) {throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: unknown key "${key}"`);}
-  }
-  if (document.schemaVersion !== EDITION_WORKSPACE_CONFIG_SCHEMA_VERSION) {
-    throw new Error(`${EDITION_WORKSPACE_CONFIG_FILE}: schemaVersion must be ${EDITION_WORKSPACE_CONFIG_SCHEMA_VERSION}`);
-  }
-  const sections = Object.fromEntries(
-    Object.entries(SECTIONS)
-      .filter(([key]) => document[key] !== undefined)
-      .map(([key, parse]) => [key, parse(document[key])]),
-  );
-  const sourceRepositoryUrlPrefix = requireString(document, 'sourceRepositoryUrlPrefix', SOURCE_URL_PREFIX, 'https://<host>/<organisation>/ with a trailing slash');
-  if (sections.firstPartySources !== undefined) {assertFirstPartyUrls(sections.firstPartySources, sourceRepositoryUrlPrefix);}
-  return Object.freeze({
-    ...sections,
-    imageRegistry: requireString(document, 'imageRegistry', IMAGE_REGISTRY, '<host>/<namespace> with no scheme or trailing slash'),
-    ...optionalChartSet(document),
-    sourceRepositoryUrlPrefix,
-    ...optionalDataRootRepositoryUrl(document, sourceRepositoryUrlPrefix),
-    sourceAuthUsername: requireSourceAuthUsername(document),
-    evidenceTrustPolicy: requireEvidenceTrustPolicy(document),
-    ...optionalFirstPartyBundleSigner(document),
-    ...optionalEditionPublishers(document),
-  });
-}
-
-let cached;
-
-/** The workspace config, read once per data root. */
-export function editionWorkspaceConfig() {
-  const root = dataRoot();
-  if (cached?.root !== root) {
-    cached = { root, config: parseEditionWorkspaceConfig(readStrictJsonFile(join(root, EDITION_WORKSPACE_CONFIG_FILE))) };
-  }
-  return cached.config;
-}
-
-/** Forget the cached config (a test that rewrites the file in place). */
-export function resetEditionWorkspaceConfig() {
-  cached = undefined;
-}
-
-/** The vendor chart set's coordinates `{chartRegistry, chartPublishers}`; a data root that declares neither (a customer's) is refused, naming the file and both keys. */
-export function vendorChartSetConfig() {
-  const { chartRegistry, chartPublishers } = editionWorkspaceConfig();
-  if (chartRegistry === undefined) {
-    throw new EditionWorkspaceConfigError(
-      `${EDITION_WORKSPACE_CONFIG_FILE} in ${dataRoot()} declares no "chartRegistry" and "chartPublishers", which vendor chart-set code needs`,
-    );
-  }
-  return { chartRegistry, chartPublishers };
-}
-
-/**
- * One product-data section, refused by name when the data root does not carry
- * it. `needed` says which operation wanted it, so the refusal is actionable.
- */
-export function workspaceSection(name, needed) {
-  const section = editionWorkspaceConfig()[name];
-  if (section === undefined) {
-    throw new Error(
-      `${EDITION_WORKSPACE_CONFIG_FILE} in ${dataRoot()} has no "${name}" section, which ${needed} needs`,
-    );
-  }
-  return section;
-}
-
-/**
- * The publisher `{repository, workflow, ref}` of an edition of `kind` on `channel`, as this data root declares it
- * (edition-workspace.json editionPublishers.<kind>.<channel>). One it does not declare is refused by name; there is
- * no default publisher and no fallback.
- */
-export function editionPublisher(kind, channel) {
-  const publisher = editionWorkspaceConfig().editionPublishers?.[kind]?.[channel];
-  if (publisher === undefined) {
-    throw new EditionWorkspaceConfigError(
-      `${EDITION_WORKSPACE_CONFIG_FILE} in ${dataRoot()} declares no "editionPublishers"."${kind}"."${channel}": the exact workflow ` +
-        `{repository, workflow, ref} that publishes a ${kind} ${channel} edition; there is no default publisher`,
-    );
-  }
-  return publisher;
-}

package/edition/edition-constants.mjs

@@ -1,110 +0,0 @@
-// edition-constants — the closed vocabulary of the edition OCI artifact, in one
-// place so the writer, the guards and the workflow cannot disagree about what an
-// edition IS. ONE layout serves both channels: an artifact at
-// `<registry root>/<channel segment>/xema-edition-<id>`, addressed by digest,
-// carrying a titled descriptor layer plus the lock layers.
-
-import { EditionChannel } from './edition-channel.mjs';
-import { EDITION_CHART_SET_FILE } from './edition-chart-set.mjs';
-import { CustomerPinForm, parseEditionContract } from './edition-contract-parse.mjs';
-import editionContract from './edition-contract.json' with { type: 'json' };
-import { EditionKind, EvidenceTrustState } from './edition-kind.mjs';
-
-/**
- * The vocabulary itself lives in edition-contract.json, the ONE source:
- * xema-deploy vendors that file byte for byte and builds its constants from it,
- * so the producer and the consumer of an edition cannot disagree about its names.
- * It is a JSON import, not a read at run time, so a bundle (the evidence
- * verifier) carries it.
- */
-export const EDITION_CONTRACT = Object.freeze(structuredClone(parseEditionContract(editionContract)));
-
-/** The descriptor layer's file name; its `org.opencontainers.image.title`. */
-export const EDITION_DESCRIPTOR_FILE = EDITION_CONTRACT.descriptorFile;
-export const EDITION_DESCRIPTOR_SCHEMA = EDITION_CONTRACT.descriptorSchema;
-/** The form of a sealed edition's `sealOf` (`<registry>/<path>@sha256:<64 hex>`): the contract's pattern, never restated. */
-export const SEAL_OF_PATTERN = new RegExp(EDITION_CONTRACT.sealOf.pattern);
-/** The one channel a seal is of (contract sealOf.channel, D99: release-only): the channel of the resolved edition it seals and of the sealed edition. */
-export const SEALED_EDITION_CHANNEL = EDITION_CONTRACT.sealOf.channel;
-/** The OIDC issuer of every edition publisher's keyless certificate (contract signers.oidcIssuer); never overridden. */
-export const EDITION_SIGNER_OIDC_ISSUER = EDITION_CONTRACT.signers.oidcIssuer;
-/** The channels on which an edition of `kind` has a publisher (contract signers.publishers.channelsByKind); its values are the data root's. */
-export const EDITION_PUBLISHER_CHANNELS = EDITION_CONTRACT.signers.publishers.channelsByKind;
-/** The ONE artifactType of every edition artifact, develop or release. */
-export const EDITION_ARTIFACT_TYPE = EDITION_CONTRACT.artifactType;
-/** The repository name prefix: `<registry root>/<channel segment>/<prefix><id>`. */
-export const EDITION_REPOSITORY_PREFIX = EDITION_CONTRACT.repositoryPrefix;
-
-/** The namespace segment of each channel's edition repositories, keyed by channel: `<registry root>/<segment>/<prefix><id>`. */
-export const EDITION_REPOSITORY_SEGMENTS = Object.freeze(
-  Object.fromEntries(Object.values(EditionChannel).map((channel) => [channel, EDITION_CONTRACT.repositories[channel].namespaceSegment])),
-);
-
-export { CustomerPinForm, EditionChannel, EditionKind, EvidenceTrustState };
-
-/**
- * The evidence trust states an edition of `kind` on `channel` may record (contract `evidenceTrust.statesByKind`):
- * `not-armed` only for a resolved develop edition; every other edition is armed or is not written.
- */
-export function admittedEvidenceTrustStates(kind, channel) {
-  const states = EDITION_CONTRACT.evidenceTrust.statesByKind[kind]?.[channel];
-  if (states === undefined) {
-    throw new Error(`edition kind ${JSON.stringify(kind)} on channel ${JSON.stringify(channel)} is not one edition-contract.json names`);
-  }
-  return states;
-}
-
-/** The owner-relative segment of a develop image repository: `<host>/<owner>/<segment>/<name>`. */
-export const DEVELOP_IMAGE_NAMESPACE_SEGMENT = EDITION_CONTRACT.imageNamespaceSegment;
-
-/** The titled layers only an OFFERING artifact carries (not locks): the catalogue a customer edition resolves against. */
-export const EDITION_OFFERING_LAYERS = Object.freeze({ ...EDITION_CONTRACT.offeringLayers });
-
-/** The one provenance pin that is not a commit: the digest of the catalogue artifact a customer edition was resolved against. */
-export const CATALOGUE_PIN_KEY = 'catalogue';
-if (!(CATALOGUE_PIN_KEY in EDITION_CONTRACT.provenancePins)) {
-  throw new Error('edition-contract.json provenancePins does not declare the catalogue pin');
-}
-
-/** The digest of the canonical customer definition a customer edition was resolved from: every input the pins of its sources and catalogue do not fix. */
-export const DEFINITION_PIN_KEY = 'definition';
-if (!(DEFINITION_PIN_KEY in EDITION_CONTRACT.provenancePins)) {
-  throw new Error('edition-contract.json provenancePins does not declare the definition pin');
-}
-
-/**
- * The commit of the customer definition repository a catalogue-free customer edition's definition was read at: a pin of
- * the catalogue-free form only (provenancePins.customerForms["catalogue-free"].pins names it), a 40-hex commit.
- */
-export const DEFINITION_REPOSITORY_PIN_KEY = 'definition-repository';
-if (!EDITION_CONTRACT.provenancePins.customerForms['catalogue-free'].pins.includes(`"${DEFINITION_REPOSITORY_PIN_KEY}"`)) {
-  throw new Error(`edition-contract.json provenancePins.customerForms["catalogue-free"].pins does not name the "${DEFINITION_REPOSITORY_PIN_KEY}" pin`);
-}
-
-/** The provenance pins that are sha256 digests, not commits. */
-export const DIGEST_PIN_KEYS = Object.freeze([CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY]);
-
-/**
- * The key of a vendor member (develop graph repository) pin, `repos/<x>` or `submodules/<x>`: the one statement is the
- * contract's (provenancePins.customerForms.vendorMemberPinPattern); the snapshot pin namespaces read it from here.
- */
-export const VENDOR_MEMBER_PIN_PATTERN = new RegExp(EDITION_CONTRACT.provenancePins.customerForms.vendorMemberPinPattern);
-
-/** Whether the contract admits customer pin form `form` (CustomerPinForm) on an edition of `kind` and `channel`. */
-export function customerPinFormAdmitted(form, kind, channel) {
-  return EDITION_CONTRACT.provenancePins.customerForms[form].kinds[kind]?.includes(channel) === true;
-}
-
-/** The lock files an edition can carry. */
-export const EditionLockFile = Object.freeze({
-  Distribution: 'distribution.lock.json',
-  Images: 'images.lock.json',
-  Authorization: 'authorization.lock.json',
-  ChartSet: EDITION_CHART_SET_FILE,
-});
-
-/** The locks of an edition, in the order the descriptor lists them and the artifact pushes them; the same for both channels. */
-export const EDITION_LOCKS = Object.freeze([...EDITION_CONTRACT.locks]);
-
-/** Every file of the artifact, in the order it is pushed. */
-export const EDITION_FILES = Object.freeze([EDITION_DESCRIPTOR_FILE, ...EDITION_LOCKS]);

package/edition/edition-contract-parse.mjs

@@ -1,179 +0,0 @@
-// edition-contract-parse — the strict parse of edition-contract.json. A consumer
-// that vendors the contract holds it to this same shape: a contract that is not
-// v3, or lacks `repositories`, or names a channel, kind or evidence trust state
-// this CLI does not know, is refused rather than read with a default.
-
-import { EditionChannel } from './edition-channel.mjs';
-import { EditionKind, EvidenceTrustState } from './edition-kind.mjs';
-
-export const EDITION_CONTRACT_SCHEMA = 'xema.edition-contract/v3';
-
-const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
-const sameSet = (left, right) => Array.isArray(left) && left.length === right.length && right.every((name) => left.includes(name));
-
-/**
- * The descriptor vocabulary: the descriptor schema (read from the contract, never restated), the closed kind enum,
- * `sealOf` (its pattern, its repository rule and the one channel a seal is of), the signers (the issuer, and the SHAPE of
- * a publisher: which kinds and channels have one and its {repository, workflow, ref} grammar; the publisher VALUES are
- * the data root's edition-workspace.json, never the contract's) and the evidence trust states each kind may record per
- * channel. A kind's channels are the same in `signers.publishers.channelsByKind` and `evidenceTrust.statesByKind`: every
- * channel for a resolved edition, exactly `sealOf.channel` for a sealed one (a seal is release-only).
- */
-/** `source` is an anchored (^...$) regular expression source that compiles. */
-function assertAnchoredPattern(source, where) {
-  if (typeof source !== 'string' || !source.startsWith('^') || !source.endsWith('$')) {
-    throw new Error(`edition-contract.json: ${where} must be an anchored (^...$) regular expression source`);
-  }
-  try {
-    new RegExp(source);
-  } catch (error) {
-    throw new Error(`edition-contract.json: ${where} is not a regular expression: ${error.message}`);
-  }
-}
-
-function assertDescriptorVocabulary(contract) {
-  if (typeof contract.descriptorSchema !== 'string' || contract.descriptorSchema === '') {
-    throw new Error('edition-contract.json: "descriptorSchema" must be a non-empty string');
-  }
-  const kinds = Object.values(EditionKind);
-  const channels = Object.values(EditionChannel);
-  if (!sameSet(contract.descriptorKinds, kinds)) {
-    throw new Error(`edition-contract.json: descriptorKinds must be exactly ${kinds.join(' | ')} (got ${JSON.stringify(contract.descriptorKinds)})`);
-  }
-  const sealOf = contract.sealOf;
-  const texts = ['names', 'repository', 'sealedEdition'];
-  if (!isObject(sealOf) || !sameSet(Object.keys(sealOf), ['pattern', 'channel', ...texts]) || !texts.every((key) => typeof sealOf[key] === 'string' && sealOf[key] !== '')) {
-    throw new Error('edition-contract.json: "sealOf" must be exactly {pattern, names, repository, channel, sealedEdition}: the one statement of a sealed edition\'s sealOf');
-  }
-  assertAnchoredPattern(sealOf.pattern, 'sealOf.pattern');
-  if (!channels.includes(sealOf.channel)) {
-    throw new Error(`edition-contract.json: sealOf.channel must be one of ${channels.join(' | ')}`);
-  }
-  const channelsOf = { [EditionKind.Resolved]: channels, [EditionKind.Sealed]: [sealOf.channel] };
-  const signers = contract.signers;
-  if (!isObject(signers) || !sameSet(Object.keys(signers), ['oidcIssuer', 'identity', 'publishers']) || !/^https:\/\/\S+$/.test(signers.oidcIssuer ?? '') || typeof signers.identity !== 'string' || signers.identity === '') {
-    throw new Error('edition-contract.json: "signers" must be exactly {oidcIssuer: <https URL>, identity, publishers}');
-  }
-  const publishers = signers.publishers;
-  if (!isObject(publishers) || !sameSet(Object.keys(publishers), ['values', 'channelsByKind', 'shape']) || typeof publishers.values !== 'string' || publishers.values === '') {
-    throw new Error('edition-contract.json: signers.publishers must be exactly {values, channelsByKind, shape}');
-  }
-  const fields = ['repository', 'workflow', 'ref'];
-  if (!isObject(publishers.shape) || !sameSet(Object.keys(publishers.shape), fields)) {
-    throw new Error(`edition-contract.json: signers.publishers.shape must be exactly {${fields.join(', ')}}`);
-  }
-  for (const field of fields) {
-    assertAnchoredPattern(publishers.shape[field], `signers.publishers.shape.${field}`);
-  }
-  const trust = contract.evidenceTrust;
-  const states = Object.values(EvidenceTrustState);
-  if (!isObject(trust) || !isObject(trust.states) || !sameSet(Object.keys(trust.states), states)) {
-    throw new Error(`edition-contract.json: evidenceTrust.states must name exactly ${states.join(' | ')}`);
-  }
-  for (const [where, byKind] of [['signers.publishers.channelsByKind', publishers.channelsByKind], ['evidenceTrust.statesByKind', trust.statesByKind]]) {
-    if (!isObject(byKind) || !sameSet(Object.keys(byKind), kinds)) {
-      throw new Error(`edition-contract.json: ${where} must have exactly one entry per kind (${kinds.join(' | ')})`);
-    }
-    for (const kind of kinds) {
-      const named = Array.isArray(byKind[kind]) ? byKind[kind] : isObject(byKind[kind]) ? Object.keys(byKind[kind]) : undefined;
-      if (!sameSet(named, channelsOf[kind]) || new Set(named).size !== named.length) {
-        throw new Error(`edition-contract.json: ${where}.${kind} must have exactly one entry per channel of a ${kind} edition (${channelsOf[kind].join(' | ')})`);
-      }
-    }
-  }
-  for (const kind of kinds) {
-    for (const channel of channelsOf[kind]) {
-      const admitted = trust.statesByKind[kind][channel];
-      if (!Array.isArray(admitted) || admitted.length === 0 || new Set(admitted).size !== admitted.length || !admitted.every((state) => states.includes(state))) {
-        throw new Error(`edition-contract.json: evidenceTrust.statesByKind.${kind}.${channel} must be a non-empty set of ${states.join(' | ')}`);
-      }
-    }
-  }
-}
-
-/** The customer pin forms (provenancePins.customerForms), one key per form. */
-export const CustomerPinForm = Object.freeze({ Catalogue: 'catalogue', CatalogueFree: 'catalogue-free' });
-
-/**
- * `provenancePins`: exactly the catalogue and definition pin statements and `customerForms`, the closed statement of how a
- * customer edition records its vendor side. The catalogue form is admitted on every kind and channel a kind has (a customer
- * edition that is not catalogue-free still requires the catalogue pin), the catalogue-free form on a subset of them; the
- * vendor member pin pattern is an anchored regular expression.
- */
-function assertProvenancePins(contract) {
-  const pins = contract.provenancePins;
-  const texts = ['catalogue', 'definition'];
-  if (!isObject(pins) || !sameSet(Object.keys(pins), [...texts, 'customerForms']) || !texts.every((key) => typeof pins[key] === 'string' && pins[key] !== '')) {
-    throw new Error('edition-contract.json: "provenancePins" must be exactly {catalogue, definition, customerForms}');
-  }
-  const forms = pins.customerForms;
-  const formNames = Object.values(CustomerPinForm);
-  if (!isObject(forms) || !sameSet(Object.keys(forms), ['names', 'vendorMemberPinPattern', ...formNames]) || typeof forms.names !== 'string' || forms.names === '') {
-    throw new Error(`edition-contract.json: provenancePins.customerForms must be exactly {names, vendorMemberPinPattern, ${formNames.join(', ')}}`);
-  }
-  assertAnchoredPattern(forms.vendorMemberPinPattern, 'provenancePins.customerForms.vendorMemberPinPattern');
-  const channelsOf = { [EditionKind.Resolved]: Object.values(EditionChannel), [EditionKind.Sealed]: [contract.sealOf.channel] };
-  for (const name of formNames) {
-    const form = forms[name];
-    if (!isObject(form) || !sameSet(Object.keys(form), ['pins', 'kinds']) || typeof form.pins !== 'string' || form.pins === '' || !isObject(form.kinds)) {
-      throw new Error(`edition-contract.json: provenancePins.customerForms.${name} must be exactly {pins, kinds}`);
-    }
-    for (const [kind, channels] of Object.entries(form.kinds)) {
-      const own = channelsOf[kind];
-      if (own === undefined || !Array.isArray(channels) || channels.length === 0 || new Set(channels).size !== channels.length || !channels.every((channel) => own.includes(channel))) {
-        throw new Error(`edition-contract.json: provenancePins.customerForms.${name}.kinds.${kind} must be a non-empty set of the channels of a ${kind} edition`);
-      }
-    }
-  }
-  for (const [kind, own] of Object.entries(channelsOf)) {
-    if (!sameSet(forms[CustomerPinForm.Catalogue].kinds[kind], own)) {
-      throw new Error(`edition-contract.json: provenancePins.customerForms.catalogue.kinds.${kind} must name every channel of a ${kind} edition (${own.join(' | ')}): the catalogue form is the default form`);
-    }
-  }
-}
-
-const SEGMENT = /^[a-z0-9][a-z0-9.-]*$/;
-
-/** The strict parse of the contract; returns it unchanged. */
-export function parseEditionContract(contract) {
-  if (contract === null || typeof contract !== 'object' || Array.isArray(contract)) {
-    throw new Error('edition-contract.json must be a JSON object');
-  }
-  if (contract.schema !== EDITION_CONTRACT_SCHEMA) {
-    throw new Error(`edition-contract.json: schema is ${JSON.stringify(contract.schema)}, expected ${JSON.stringify(EDITION_CONTRACT_SCHEMA)}`);
-  }
-  if (typeof contract.vendoring !== 'string' || contract.vendoring === '') {
-    throw new Error('edition-contract.json: "vendoring" must be the non-empty statement of how a consumer vendors this file');
-  }
-  if (typeof contract.repositoryPrefix !== 'string' || contract.repositoryPrefix === '') {
-    throw new Error('edition-contract.json: "repositoryPrefix" must be a non-empty string');
-  }
-  const repositories = contract.repositories;
-  if (repositories === null || typeof repositories !== 'object' || Array.isArray(repositories)) {
-    throw new Error('edition-contract.json has no "repositories": the namespace segment of each channel is read from it and nowhere else');
-  }
-  const channels = Object.values(EditionChannel);
-  const keys = Object.keys(repositories);
-  const unknown = keys.filter((key) => !channels.includes(key));
-  if (unknown.length > 0 || keys.length !== channels.length) {
-    throw new Error(
-      `edition-contract.json: "repositories" is exactly one entry per channel (${channels.join(' | ')}); ` +
-        (unknown.length > 0 ? `unknown channel ${unknown.map((key) => JSON.stringify(key)).join(', ')}` : `got ${keys.join(', ') || 'none'}`),
-    );
-  }
-  const segments = new Set();
-  for (const channel of channels) {
-    const entry = repositories[channel];
-    const entryKeys = entry !== null && typeof entry === 'object' && !Array.isArray(entry) ? Object.keys(entry) : [];
-    if (entryKeys.join() !== 'namespaceSegment' || typeof entry.namespaceSegment !== 'string' || !SEGMENT.test(entry.namespaceSegment)) {
-      throw new Error(`edition-contract.json: repositories.${channel} is exactly {namespaceSegment}, one lowercase path segment`);
-    }
-    segments.add(entry.namespaceSegment);
-  }
-  if (segments.size !== channels.length) {
-    throw new Error('edition-contract.json: the channels\' namespace segments must differ');
-  }
-  assertDescriptorVocabulary(contract);
-  assertProvenancePins(contract);
-  return contract;
-}