@xemahq/xema 0.59.1 → 0.60.1

package/edition/release-edition-artifact.mjs

@@ -1,152 +0,0 @@
-#!/usr/bin/env node
-// release-edition-artifact — write the OCI artifact of a RELEASE edition from
-// the committed, sealed locks of the editions root.
-//
-//   <id> --channel release --registry <root> --coordinate <tag>
-//            --engine-image <repository>@sha256:<digest> --out <dir> [--local]
-//
-// The artifact has the layout of every edition (edition-artifact.mjs): the
-// descriptor plus the four locks and the offering's catalogue.json, written to <dir>, and the target
-// `<root>/<release namespace segment>/xema-edition-<id>:<coordinate>` is printed. The workflow pushes
-// <dir> with oras and signs the manifest DIGEST with cosign; the tag is for
-// humans. A lock set that is not sealed is refused: an unsealed images lock names
-// no image digests, so nothing could be admitted against it.
-
-import { readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-import { verifyBiomeContentHashes } from './biome-content.mjs';
-import { writeCatalogue } from './catalogue.mjs';
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import { LOCAL_WORKFLOW, assertEngineImage, editionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
-import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
-import { EditionChannel, EditionKind, EditionLockFile } from './edition-constants.mjs';
-import { editionPinnedInputs } from './edition-pinned-inputs.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule } from './edition-workspace.mjs';
-import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
-import { loadKernelDistributionSchemas, validateImmutableImageLock } from './lib.mjs';
-import { releaseCatalogue } from './release-catalogue.mjs';
-import { assertReleaseEditionTree } from './release-channel-guard.mjs';
-import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
-import { readSealedDistributionLock } from './sealed-distribution-lock.mjs';
-import { createPinnedSourceAuthority } from './source-authority.mjs';
-
-if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
-}
-
-const VALUE_FLAGS = Object.freeze(['--channel', '--registry', '--coordinate', '--engine-image', '--out']);
-const REQUIRED_FLAGS = VALUE_FLAGS;
-const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
-
-/** Parse `<id> --flag value ...` (the argv AFTER the `artifact` verb, which the edition dispatcher has already stripped); only the release channel is written by this verb. */
-export function parseReleaseArtifactArgs(argv) {
-  const rest = argv;
-  const options = {};
-  const positional = [];
-  for (let i = 0; i < rest.length; i += 1) {
-    const arg = rest[i];
-    if (arg === '--local') {
-      options[arg] = true;
-    } else if (VALUE_FLAGS.includes(arg)) {
-      const value = rest[i + 1];
-      if (value === undefined || (value.startsWith('--') && value.length > 2)) {throw new Error(`${arg} requires a value`);}
-      options[arg] = value;
-      i += 1;
-    } else if (arg.startsWith('--')) {
-      throw new Error(`unknown argument ${arg} for artifact`);
-    } else {
-      positional.push(arg);
-    }
-  }
-  if (positional.length !== 1) {throw new Error('artifact takes exactly one <distribution-id>');}
-  for (const required of REQUIRED_FLAGS) {
-    if (options[required] === undefined) {throw new Error(`artifact requires ${required}`);}
-  }
-  if (options['--channel'] !== EditionChannel.Release) {
-    throw new Error(
-      `--channel ${JSON.stringify(options['--channel'])}: this verb writes ${EditionChannel.Release} editions from the committed locks; ` +
-        'a develop edition is resolved from a snapshot by `xema edition develop resolve`',
-    );
-  }
-  assertCanonicalDistributionId(positional[0]);
-  assertEngineImage(options['--engine-image']);
-  return { id: positional[0], options };
-}
-
-/** The images lock must be sealed: every subject names the registry digest of its image. */
-export function assertSealedImageLock(lock, label) {
-  const subjects = lock?.subjects ?? [];
-  if (subjects.length === 0) {throw new Error(`${label} carries no subjects, so it seals nothing`);}
-  const unsealed = subjects.filter((subject) => !DIGEST_PATTERN.test(String(subject?.imageDigest)));
-  if (unsealed.length > 0) {
-    throw new Error(
-      `${label} is not sealed: ${unsealed.length} of ${subjects.length} subjects carry no imageDigest ` +
-        `(first: ${unsealed[0].kind}:${unsealed[0].id}). Run \`xema edition resolve-digests\` first.`,
-    );
-  }
-}
-
-/**
- * The four committed locks of a release edition, validated. Nothing is published from a set
- * that is not sealed and intact: the images lock names every digest, the distribution lock is
- * the SEALED grammar (an unsealed one is refused), and every `biomeContentHash` is recomputed
- * from its inputs and compared, so a lock edited after its seal is refused, naming the biome.
- */
-export async function readCommittedEdition(id, root = editionsRoot()) {
-  const dir = join(root, id);
-  assertReleaseEditionTree(dir);
-  const read = (file) => JSON.parse(readFileSync(join(dir, file), 'utf8'));
-  const schemas = await loadKernelDistributionSchemas();
-  const imageLock = validateImmutableImageLock(schemas.parseImageLock(read(EditionLockFile.Images)), schemas);
-  assertSealedImageLock(imageLock, join(dir, EditionLockFile.Images));
-  const { raw: distributionLock, sealed } = readSealedDistributionLock({
-    schemas,
-    lockPath: join(dir, EditionLockFile.Distribution),
-    distributionId: id,
-  });
-  const authority = createPinnedSourceAuthority({ pins: (await editionPinnedInputs(id, { schemas })).repositoryPins });
-  await verifyBiomeContentHashes({
-    schemas,
-    lock: sealed,
-    imageLock,
-    locate: sourceTreeLocator(externalSourceTrees(sealed)),
-    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
-  });
-  return {
-    distributionLock,
-    imageLock: read(EditionLockFile.Images),
-    authorizationLock: read(EditionLockFile.Authorization),
-    chartSetLock: assertRosteredChartSetLock(read(EditionLockFile.ChartSet), join(dir, EditionLockFile.ChartSet)),
-  };
-}
-
-async function run(argv, env) {
-  const { id, options } = parseReleaseArtifactArgs(argv);
-  const target = editionTarget(id, options['--registry'], EditionChannel.Release, options['--coordinate']);
-  const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
-  const locks = await readCommittedEdition(id);
-  // Refuses (EvidenceTrustRequiredError) unless the policy is ARMED on the
-  // release channel: a release artifact is never written not-armed.
-  const evidenceTrustPolicy = await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Release });
-  const outDir = resolve(options['--out']);
-  writeEditionArtifact({
-    outDir,
-    channel: EditionChannel.Release,
-    distributionId: id,
-    pins: {},
-    workflow,
-    evidenceTrustPolicy,
-    engineImage: options['--engine-image'],
-    ...locks,
-  });
-  writeCatalogue(outDir, await releaseCatalogue(id, locks));
-  console.log(target);
-}
-
-if (isEntryModule(import.meta.url)) {
-  run(process.argv.slice(2), process.env).catch((error) => {
-    console.error(`[edition-artifact] ${error.message}`);
-    process.exit(1);
-  });
-}

package/edition/release-edition.mjs

@@ -1,54 +0,0 @@
-#!/usr/bin/env node
-// release-edition — the customer RELEASE edition's command line: `xema edition release <verb> --definition <file>`.
-//
-// It is `xema edition develop <verb> --definition <file>` on the release channel: the same parser, the same frame
-// and the same verbs (customer-edition-verbs.mjs); only the inputs differ. The id is the definition's, and the
-// catalogue is the one pinned for `release` in catalogue.pin.json beside the definition.
-//
-//   freeze-sources --definition <file> --out <file>
-//       one `sources/<name>` pin per source the definition declares, each at the source's DECLARED ref (a branch,
-//       or a tag taken at its peeled commit); a ref that is both a branch and a tag, or missing, is refused.
-//       Written exclusively (wx).
-//   target --definition <file> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest>
-//          [--source-image <source>=<registry>/<prefix>]...
-//       print <root>/<release segment>/xema-edition-<id>:<tag>, the tag being snapshotEditionTag of the CLI
-//       version, the engine image, the pins and the source-image map (as on develop).
-//   check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
-//                  [--catalogue-username <name> --catalogue-token-env <VAR>] [--source-image <source>=<registry>/<prefix>]...
-//       refuse to reuse a pulled artifact whose descriptor disagrees with this snapshot.
-//   resolve --definition <file> --pins <file> --out <dir> --registry <root> --engine-image <repository>@sha256:<digest>
-//           [--source-image <source>=<registry>/<prefix>]... [--catalogue-username <name> --catalogue-token-env <VAR>] [--local]
-//       resolve the edition against the pinned release catalogue, seal the customer's own image rows at the digests
-//       the registry serves for `<repository>:<contentHash>` (it never builds an image), and write the descriptor and
-//       the four locks to <dir>.
-//
-// `resolve` and `check-existing` read the release catalogue only after its signed E4 evidence verified against the
-// CUSTOMER's own evidence trust policy (catalogue-evidence.mjs), and require that policy armed on the release channel.
-// Until the E4 referrer layout lands, no catalogue verifies and both refuse. Takes the roots of the
-// develop customer form (--data-root, --editions-root, --sources-root, --cache-dir per verb), never the kernel.
-
-import { customerRootsOf, parseEditionVerbArgs, runCustomerVerb } from './customer-edition-verbs.mjs';
-import { EditionChannel } from './edition-constants.mjs';
-import { configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
-
-if (isEntryModule(import.meta.url)) {
-  const [command] = process.argv.slice(2);
-  try {
-    configureEditionWorkspaceFromProcess(customerRootsOf(command), { refuseOthers: true });
-  } catch (error) {
-    console.error(`[release-edition] ${error.message}`);
-    process.exit(1);
-  }
-}
-
-async function run(argv, env) {
-  const { command, options } = parseEditionVerbArgs(EditionChannel.Release, argv);
-  await runCustomerVerb({ channel: EditionChannel.Release, command, options, env });
-}
-
-if (isEntryModule(import.meta.url)) {
-  run(process.argv.slice(2), process.env).catch((error) => {
-    console.error(`[release-edition] ${error.message}`);
-    process.exit(1);
-  });
-}

package/edition/remedy-command.mjs

@@ -1,89 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// A REMEDY THIS REPOSITORY CAN ACTUALLY RUN.
-//
-// WHY THIS EXISTS
-//
-//   This repository's `package.json` has NO `scripts` block. Every `pnpm
-//   dist:*` command is declared one directory up, in the AGGREGATOR's
-//   `package.json`, as a bare `node repos-infra/xema-distributions/<file>.mjs`.
-//   So a diagnostic printing `pnpm dist:images <id>` names a command its reader
-//   cannot run — and the reader of a dist-check failure is standing in a FLAT
-//   checkout of this repository, which is exactly where the pnpm spelling does
-//   not resolve. A remedy that cannot be run where it is printed is a dead end
-//   (`.claude/rules/writing-boundary-checks.md`).
-//
-//   Measured 2026-09-28 at `origin/develop`: 52 `pnpm dist:*` references in
-//   this repository, 19 such scripts declared in the aggregator, and ZERO
-//   declared here.
-//
-// WHY NOT A SECOND `scripts` BLOCK
-//
-//   That was the obvious fix and it is the wrong one: it would put 19 name→file
-//   mappings in two places, free to drift, and drift between them is invisible
-//   — a new script reachable from one side and not the other, with nothing able
-//   to say so short of a new gate. The rule forbids buying a fix with
-//   a permanent check.
-//
-//   Deriving the command from the script's REAL PATH has one authority — the
-//   file system — and cannot go stale: rename the file and the command follows,
-//   because it IS the file. This is the treatment `seal-image-digests.mjs`
-//   already chose for itself and argued for in its own words; it is extracted
-//   here so the other ten diagnostics get it too rather than each re-deriving
-//   it, and so `sealCommandFor` stops being the only site that is right.
-//
-// WHAT IT DOES NOT DO
-//
-//   It does not replace the aggregator's `pnpm dist:*` spelling, which is real,
-//   is what CI invokes, and is correct FROM THE AGGREGATOR. Documentation may
-//   name either; a RUNTIME diagnostic names this one, because the process
-//   printing it already knows where it is standing and the reader does not.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { dirname, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-/** This module's directory — the distributions root in both layouts the fleet runs. */
-const ROOT = dirname(fileURLToPath(import.meta.url));
-
-/**
- * Render an absolute script path as the SHORTEST form that still resolves from
- * the caller's current directory.
- *
- * A relative path is preferred when the script is at or below `process.cwd()`
- * — that is the form an operator can paste — and the absolute path is used
- * otherwise, because a `../../..` chain is longer, harder to read, and no more
- * runnable. Escaping to a parent (`..`) is never shown for that reason.
- */
-function shortestRunnablePath(script) {
-  const fromCwd = relative(process.cwd(), script);
-  return !fromCwd.startsWith('..') && fromCwd.length < script.length
-    ? fromCwd
-    : script;
-}
-
-/**
- * The command that runs `scriptFileName` — a sibling of this module — with
- * `args`, spelled so the reader can run it from wherever they are standing.
- *
- * Takes a FILE NAME rather than a script name on purpose: a file name is
- * checked by the file system the moment anybody runs the remedy, whereas a
- * `dist:*` name is checked by nothing and is what went wrong here.
- *
- * @param {string} scriptFileName e.g. `'resolve-distribution.mjs'`
- * @param {...string} args positional arguments, appended verbatim
- */
-export function commandFor(scriptFileName, ...args) {
-  const shown = shortestRunnablePath(resolve(ROOT, scriptFileName));
-  return ['node', shown, ...args].join(' ');
-}
-
-/**
- * The command that runs the CALLING module itself.
- *
- * @param {string} importMetaUrl the caller's `import.meta.url`
- * @param {...string} args positional arguments, appended verbatim
- */
-export function commandForSelf(importMetaUrl, ...args) {
-  const shown = shortestRunnablePath(fileURLToPath(importMetaUrl));
-  return ['node', shown, ...args].join(' ');
-}

package/edition/repin-evidence-trust.mjs

@@ -1,109 +0,0 @@
-#!/usr/bin/env node
-// `xema edition repin-evidence-trust` - write the data root's evidence trust
-// pin: the digest of the declared policy, the digests of THIS CLI's built
-// verifier bundle and provenance, the kernel contract authority the data
-// root's runtime image source index states (a customer data root has no such
-// index: the pin then records none and pins only what exists), and the oras
-// binaries that may read a registry, and (only when the data root holds `third-party-source-pins.json`) that
-// file's sha256. The result is a data-root change to review; nothing here is
-// generated into the library.
-//
-//   [--trusted-oras-digest sha256:<64 hex>]…   the oras binaries to trust. Without
-//       the flag the list of the existing pin is kept; a first pin requires it.
-//
-// Refuses when the data root declares no evidenceTrustPolicy.
-
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { locateBuiltVerifier, readBuiltVerifierDigests } from './built-verifier.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import {
-  WorkspaceRoot,
-  configureEditionWorkspaceFromProcess,
-  dataRoot,
-  isEntryModule,
-} from './edition-workspace.mjs';
-import {
-  loadDeclaredTrustPolicy,
-  hasRuntimeImageSourceIndex,
-  readEvidenceTrustPin,
-  readStatedKernelContractAuthority,
-  requireOrasDigests,
-  writeEvidenceTrustPin,
-} from './evidence-trust-pin.mjs';
-import { loadKernelDistributionSchemas } from './lib.mjs';
-import { loadThirdPartySourcePins, thirdPartySourcePinsDigest } from './third-party-source-pins.mjs';
-
-/**
- * Write the pin for the configured data root and return it.
- * `locateVerifier` is a parameter so a test can supply a fixture bundle.
- */
-export async function repinEvidenceTrust({
-  locateVerifier = locateBuiltVerifier,
-  trustedOrasBinaryDigests = undefined,
-} = {}) {
-  const root = dataRoot();
-  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
-  if (declaration.policy === null) {
-    throw new Error(
-      `${root} declares no evidenceTrustPolicy in edition-workspace.json; there is nothing to pin`,
-    );
-  }
-  const schemas = await loadKernelDistributionSchemas();
-  const { policyDigest } = loadDeclaredTrustPolicy({ dataRoot: root, declaration, schemas });
-  const verifier = readBuiltVerifierDigests(locateVerifier);
-  let orasDigests = trustedOrasBinaryDigests;
-  if (orasDigests === undefined) {
-    if (!existsSync(join(root, declaration.pin))) {
-      // Names the flag: a first pin has no list to keep.
-      requireOrasDigests([]);
-    }
-    orasDigests = readEvidenceTrustPin({ dataRoot: root, declaration }).trustedOrasBinaryDigests;
-  }
-  // A present file is a reviewed record: a schema-invalid one is refused here, never pinned.
-  loadThirdPartySourcePins(root);
-  return writeEvidenceTrustPin({
-    dataRoot: root,
-    declaration,
-    policyDigest,
-    verifier,
-    kernelContractAuthority: hasRuntimeImageSourceIndex(root) ? readStatedKernelContractAuthority({ dataRoot: root, schemas }) : null,
-    trustedOrasBinaryDigests: orasDigests,
-    thirdPartySourcePinsDigest: thirdPartySourcePinsDigest(root),
-  });
-}
-
-/** `--trusted-oras-digest <digest>` and `--trusted-oras-digest=<digest>`, repeated; nothing else is an argument. */
-export function parseRepinArguments(argv) {
-  const digests = [];
-  for (let index = 0; index < argv.length; index += 1) {
-    const argument = argv[index];
-    if (argument === '--trusted-oras-digest') {
-      index += 1;
-      if (argv[index] === undefined) {throw new Error('--trusted-oras-digest needs a value');}
-      digests.push(argv[index]);
-    } else if (argument.startsWith('--trusted-oras-digest=')) {
-      digests.push(argument.slice('--trusted-oras-digest='.length));
-    } else {
-      throw new Error(`unknown argument "${argument}"; usage: xema edition repin-evidence-trust [--trusted-oras-digest sha256:<64 hex>]…`);
-    }
-  }
-  return { trustedOrasBinaryDigests: digests.length === 0 ? undefined : digests };
-}
-
-if (isEntryModule(import.meta.url)) {
-  try {
-    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Kernel]);
-    const pin = await repinEvidenceTrust(parseRepinArguments(process.argv.slice(2)));
-    console.log(
-      `[repin-evidence-trust] pinned policy ${pin.policyDigest}, verifier ${pin.verifier.bundleDigest}, ` +
-        // A customer data root states no kernel contract authority: its pin records none.
-        `kernel contract authority ${pin.kernelContractAuthority === null ? 'none' : pin.kernelContractAuthority.sourceCommit} and ` +
-        `${pin.trustedOrasBinaryDigests.length} oras binary digest(s)`,
-    );
-  } catch (error) {
-    console.error(`[repin-evidence-trust] ${error.message}`);
-    process.exitCode = 1;
-  }
-}

package/edition/required-resource-provider.mjs

@@ -1,58 +0,0 @@
-// A required resource requirement is a closure edge.
-//
-// A biome service that declares `inclusion: required` for a resource kind
-// (postgres.schema, redis.namespace, ...) cannot run without a provider of that
-// kind, exactly as it cannot run without a biome it `requires`. So the
-// resolver follows the edge to the provider and ships it; naming the consumer
-// is enough, no edition lists a provider by hand.
-//
-// The edge resolves only when exactly one deliverable biome provides the kind.
-// Zero providers or several are refused with a typed error: with none the
-// consumer can never boot, and with several no provider-selection policy
-// exists, so choosing one would be a guess made on the consumer's behalf.
-
-export const RequiredResourceProviderFailure = Object.freeze({
-  NoProvider: 'no-provider',
-  AmbiguousProvider: 'ambiguous-provider',
-});
-
-export class RequiredResourceProviderError extends Error {
-  constructor(failure, { distributionId, consumerId, requirement, providerIds }) {
-    const subject =
-      `biome "${consumerId}" service "${requirement.consumerService}" requires ` +
-      `${requirement.kind} "${requirement.logicalName}" (${requirement.inclusion})`;
-    super(
-      failure === RequiredResourceProviderFailure.NoProvider
-        ? `distribution "${distributionId}": ${subject}, and no biome in the index provides ` +
-            `${requirement.kind}, so the consumer cannot run in any edition.`
-        : `distribution "${distributionId}": ${subject}, and ${providerIds.length} biomes provide ` +
-            `that kind: ${providerIds.join(', ')}. No provider-selection policy exists, so the ` +
-            `resolver refuses rather than choosing one.`,
-    );
-    this.name = 'RequiredResourceProviderError';
-    this.failure = failure;
-    this.distributionId = distributionId;
-    this.consumerId = consumerId;
-    this.requirement = requirement;
-    this.providerIds = providerIds;
-  }
-}
-
-/**
- * The biome entry that is the sole provider of the requirement's kind among
- * `candidates` (the deliverable, source-admissible index entries).
- */
-export function soleResourceProvider({ distributionId, consumer, requirement, candidates }) {
-  const providers = candidates.filter((entry) =>
-    (entry.providesResources ?? []).some((provision) => provision.kind === requirement.kind),
-  );
-  const providerIds = [...new Set(providers.map((entry) => entry.id))].sort();
-  const context = { distributionId, consumerId: consumer.id, requirement, providerIds };
-  if (providers.length === 0) {
-    throw new RequiredResourceProviderError(RequiredResourceProviderFailure.NoProvider, context);
-  }
-  if (providerIds.length > 1) {
-    throw new RequiredResourceProviderError(RequiredResourceProviderFailure.AmbiguousProvider, context);
-  }
-  return providers[0];
-}