@xemahq/xema 0.25.1 → 0.27.0

package/edition/platform-service-class.mjs

@@ -0,0 +1,18 @@
+/**
+ * A platform service's installation class, as the index carries it.
+ *
+ * The class is the service's OWN declaration (`core/xema-distribution.json`
+ * `platformServices[].installationClass`). There is no default and no list of
+ * names here: a service that declares none has none in the index, and the
+ * resolver refuses it by name rather than reading a guessed class.
+ */
+export function declaredInstallationClass(declaration) {
+  return declaration.installationClass === undefined
+    ? {}
+    : { installationClass: declaration.installationClass };
+}
+
+/** The (name, tier, declared class) a declaration and an index entry must agree on. */
+export function comparablePlatformService(entry) {
+  return { name: entry.name, tier: entry.tier, ...declaredInstallationClass(entry) };
+}

package/edition/platform-service-source-authority.mjs

@@ -0,0 +1,105 @@
+import { workspaceSection } from './edition-config.mjs';
+
+/**
+ * The ONE authority for what a declared platform service IS, source-wise.
+ *
+ * the data root's `edition-workspace.json#platformServiceSources` declares the
+ * platform services, their tier and installation class, and where their source
+ * lives. The library owns the SCHEMA of that section (workspace-sections.mjs) and
+ * this module reads it; for every declared platform service it names
+ *
+ *   - `repo` + `manifestPath` — the exact source manifest whose `name`/`version`
+ *     are the service's identity, read at the repository's published commit;
+ *   - `manifestName` — the name that manifest MUST declare, which is what stops
+ *     a name-only substitution from silently re-pointing a service;
+ *   - `imageKey` — the join to the independent images.lock authority;
+ *   - `runtimeBinding` — the actual runtime image subject that CARRIES this
+ *     service, or `null` when the service is its own repository-root image.
+ *
+ * That last field is the partition the whole image plane turns on, and it is
+ * declared exactly once, here:
+ *
+ *   - `runtimeBinding === null` — an INDEPENDENTLY SOURCED service. Its image is
+ *     built from its repository root, and `resolve-images.mjs` mints a
+ *     `platform`-kind subject for it whose id is `imageKey`. These are the five
+ *     generic submodules.
+ *   - `runtimeBinding !== null` — the service's image is a subject something ELSE
+ *     produces: a supplemental subject declared by
+ *     `build-runtime-image-source-index.mjs`, or a component of a selected biome.
+ *     No `platform`-kind subject is minted; the binding names the real one.
+ *
+ * Both halves still carry an exact source identity, because
+ * `LockedPlatformService.source` is REQUIRED by the kernel distribution-lock
+ * schema at schemaVersion 2. Before this module existed, the index generator
+ * resolved every service to a hardcoded `submodules/<name>`, so it could only
+ * ever describe the five submodules, and every edition failed to resolve on
+ * `xema-kernel-server` — declared since bc8d5c6 and never resolvable.
+ *
+ * Adding a platform service is therefore ONE data entry in the data root and no
+ * code change: the platform service index is derived from these rows, so there
+ * is no second list to forget.
+ *
+ * A row is a hand-declared fact only where nothing can derive it. It cannot be
+ * derived: `docs-api` is sourced from a package named `xema-docs`,
+ * `xema-kernel-server` sits at a sub-path of a carved repository, and
+ * `opencode-image-prepuller` ships no package of its own at all — it is a
+ * DaemonSet whose sole purpose is to keep the `opencode-worker` image warm, so
+ * its identity is exactly the identity of the biome that declares that image.
+ */
+
+const declarations = () =>
+  workspaceSection('platformServiceSources', 'resolving a platform service to its source');
+
+/** Every declared platform service, sorted by name. */
+export const platformServiceSourceDeclarations = () =>
+  declarations()
+    .map((declaration) =>
+      Object.freeze({
+        ...declaration,
+        /** Aggregate-workspace-relative manifest path, the lock's `source.path`. */
+        path: `${declaration.repo}/${declaration.manifestPath}`,
+      }),
+    )
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+
+/**
+ * The declaration for one platform service. Fails fast and names the service —
+ * source resolution never falls back to a guessed location.
+ */
+export function platformServiceSourceDeclaration(name) {
+  const declaration = platformServiceSourceDeclarations().find((entry) => entry.name === name);
+  if (!declaration) {
+    throw new Error(
+      `platform service "${name}" has no source declaration in the "platformServiceSources" ` +
+        'section of edition-workspace.json; declare its repo, manifest path, ' +
+        'manifest name, image key and runtime binding there',
+    );
+  }
+  return declaration;
+}
+
+/** Every source repository a platform service is read from, deduplicated. */
+export const platformServiceSourceRepositories = () => [
+  ...new Set(platformServiceSourceDeclarations().map((declaration) => declaration.repo)),
+];
+
+/**
+ * The logical-platform-service → actual-runtime-subject bindings, in the exact
+ * shape `runtime-image-source-index.json#platformServiceBindings` carries.
+ * DERIVED from the declarations above so the partition has one definition.
+ */
+export const platformServiceRuntimeBindings = () =>
+  platformServiceSourceDeclarations()
+    .filter((declaration) => declaration.runtimeBinding !== null)
+    .map((declaration) =>
+      Object.freeze({
+        platformService: declaration.name,
+        subjectKind: declaration.runtimeBinding.subjectKind,
+        subjectId: declaration.runtimeBinding.subjectId,
+      }),
+    );
+
+/** True when the service's image is produced by some other subject. */
+export function platformServiceHasRuntimeBinding(name) {
+  return platformServiceSourceDeclaration(name).runtimeBinding !== null;
+}

package/edition/positive-closure.mjs

@@ -0,0 +1,162 @@
+// positive-closure — the packaging plane's projection onto the kernel's ONE
+// closure algorithm (`resolveBiomeClosure`, `@xemahq/contracts/distribution`).
+//
+// The KERNEL owns the rule; this module owns only the projection of THIS
+// plane's facts onto it — biome-index entries and lock entries become
+// `ClosureBiomeFacts`, and a lock's `resolution` section becomes a `why`
+// answer. Two callers use the rule:
+//
+//   * an EDITION (`resolve-distribution.mjs`, `selectByPositiveClosure`) — its
+//     declared roots against the biome catalogue, starting from nothing;
+//   * a RUNTIME INSTALLATION (`runtimeInstallationClosure` below) — one
+//     org-installed biome against what its base edition already PROVIDES (the
+//     sealed lock's roster) and PERMITS (the candidates the caller admits).
+//
+// Neither re-implements any part of the closure; a second closure here would be
+// a rival answer to the question the kernel exists to answer once.
+
+/** Project one biome-index entry onto the facts the closure reads. */
+export function closureBiomeFacts(entry) {
+  return {
+    id: entry.id,
+    tier: entry.tier,
+    ...(entry.installationClass === undefined
+      ? {}
+      : { installationClass: entry.installationClass }),
+    ...(entry.audience === undefined ? {} : { audience: entry.audience }),
+    services: Array.isArray(entry.services) ? entry.services : [],
+    ...(entry.dependencyContract === undefined
+      ? {}
+      : { dependencyContract: entry.dependencyContract }),
+    ...(entry.serviceResources === undefined
+      ? {}
+      : { serviceResources: entry.serviceResources }),
+    ...(entry.providesResources === undefined
+      ? {}
+      : { providesResources: entry.providesResources }),
+  };
+}
+
+/**
+ * The closure of ONE runtime-installed biome against a sealed base edition.
+ *
+ * - `baseLock` is the base edition's distribution lock (read with the kernel's
+ *   tolerant reader by the caller). Its roster is what the base PROVIDES; each
+ *   rostered biome's facts are taken from `index` by id, because a lock entry
+ *   carries no dependency contract or resource provisions.
+ * - `permitted` is the catalogue the base edition PERMITS an installation to
+ *   draw on — the caller decides it (store visibility, trust policy, sources);
+ *   it defaults to every `index` entry the base does not already ship.
+ * - The installed biome is a `runtime-installation-root`. A biome the base
+ *   already ships is never re-added and never traversed.
+ *
+ * Returns the kernel result unchanged: the entities the installation ADDS, with
+ * provenance, and every resource binding of an added biome against added ∪
+ * present. Refusals are the kernel's, prefixed with the installation subject.
+ */
+export function runtimeInstallationClosure({
+  schemas,
+  baseLock,
+  index,
+  biomeId,
+  permitted,
+}) {
+  const indexById = new Map(index.map((entry) => [entry.id, entry]));
+  const presentIds = new Set(baseLock.biomes.map((biome) => biome.id));
+  const presentBiomes = baseLock.biomes.map((biome) => {
+    const entry = indexById.get(biome.id);
+    if (entry === undefined) {
+      throw new Error(
+        `runtime installation of "${biomeId}": base edition "${baseLock.distributionId}" ships ` +
+          `biome "${biome.id}", which the catalogue does not describe — the base's provisions ` +
+          'cannot be read, so its satisfaction of an edge cannot be decided',
+      );
+    }
+    return closureBiomeFacts(entry);
+  });
+  const candidates = (permitted ?? index.filter((entry) => !presentIds.has(entry.id))).map(
+    closureBiomeFacts,
+  );
+  try {
+    return schemas.resolveBiomeClosure({
+      roots: [
+        {
+          entity: { kind: schemas.ClosureEntityKind.Biome, id: biomeId },
+          provenance: {
+            kind: schemas.ClosureProvenanceKind.RuntimeInstallationRoot,
+          },
+        },
+      ],
+      candidates: { biomes: candidates, platformServices: [] },
+      present: {
+        biomes: presentBiomes,
+        platformServices: baseLock.platformServices.map(({ name, tier }) => ({
+          name,
+          tier,
+        })),
+      },
+    });
+  } catch (error) {
+    if (error instanceof schemas.BiomeClosureError) {
+      throw new Error(
+        `runtime installation of "${biomeId}" into base edition "${baseLock.distributionId}": ${error.message}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * `why <name>` — the deterministic explanation of one entity's presence in a
+ * lock, rendered from the lock's `resolution` section alone. Returns the lines
+ * to print. A biome id is looked up first, then a platform-service name; a
+ * selector-model lock records no provenance and says so rather than guessing.
+ */
+export function explainInclusion(schemas, lock, name) {
+  if (lock.resolution === undefined) {
+    return {
+      found: false,
+      lines: [
+        `${lock.distributionId}: this edition resolves by the selector model ` +
+          '(include/exclude); its lock records no provenance. Opt the edition into ' +
+          '`resolution: "positive-closure"` to make `why` answerable.',
+      ],
+    };
+  }
+  const entry =
+    lock.resolution.entries.find(
+      (candidate) =>
+        candidate.entity.kind === schemas.ClosureEntityKind.Biome &&
+        candidate.entity.id === name,
+    ) ??
+    lock.resolution.entries.find(
+      (candidate) =>
+        candidate.entity.kind === schemas.ClosureEntityKind.PlatformService &&
+        candidate.entity.id === name,
+    );
+  if (entry === undefined) {
+    return {
+      found: false,
+      lines: [
+        `${lock.distributionId}: "${name}" is not in this edition — it is not a root, no ` +
+          'operation root names it, and no dependency or reached operation of anything in ' +
+          'the edition requires it.',
+      ],
+    };
+  }
+  const lines = [`${lock.distributionId}: ${entry.entity.kind} "${entry.entity.id}" is in because:`];
+  for (const provenance of entry.provenance) {
+    if (provenance.chain === undefined) {
+      lines.push(`  - ${schemas.describeProvenance(provenance)}`);
+      continue;
+    }
+    lines.push(
+      `  - ${provenance.kind}, from root ${provenance.root.kind} "${provenance.root.id}":`,
+    );
+    provenance.chain.forEach((hop, step) => {
+      lines.push(`      ${step + 1}. ${schemas.describeHop(hop)}`);
+    });
+  }
+  return { found: true, lines };
+}

package/edition/produce-distribution-completeness-evidence.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+// The distribution completeness statement and the evidence set it seals.
+//
+//   xema edition evidence statement completeness stage …   (the bytes to sign)
+//   xema edition evidence assemble-set …                    (evidence-set.json)
+//
+// `stage` resolves the edition's producer evidence into a NEW staging
+// directory, writes the canonical completeness statement there and prints the
+// signing plan. The caller signs it (`cosign attest-blob`). `assemble-set`
+// re-derives everything from the same flags, refuses staged bytes that differ,
+// verifies the signed bundle with cosign against the declared signer, writes
+// `evidence-set.json` and seals the evidence root (built from the re-derived
+// files, never renamed from the staging).
+// This module never signs and never requests an OIDC token.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+import {
+  acceptSignedEvidenceStatement,
+  assertPinnedCosignVersion,
+  buildDistributionImageEvidenceSet,
+  buildDistributionImagesStatement,
+  loadPinnedTrustPolicy,
+  parseEvidenceCliFlags,
+  resolveProducerEvidence,
+  stageEvidenceStatement,
+  stageProducerEvidence,
+  stagedProducerFiles,
+} from './distribution-evidence-set.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  dataRoot,
+  editionsRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { canonicalJsonBytes } from './image-evidence.mjs';
+import { serializeJson } from './lib.mjs';
+import {
+  assertGitHubProducerContext,
+  createCosignVerifier,
+  loadProducerKernelSchemas,
+} from './produce-image-source-evidence.mjs';
+import { assertStagedExactly, discardStaging, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
+
+const EVIDENCE_SET_FILE = 'evidence-set.json';
+const COMPLETENESS_STATEMENT_PATH = 'completeness/statement.json';
+const COMPLETENESS_BUNDLE_PATH = 'completeness/bundle.sigstore.json';
+
+/** The keyless signer a GitHub workflow is: its certificate identity and issuer. */
+export function githubWorkflowSigner({ repository, ref, path }) {
+  return {
+    certificateIdentity: `https://github.com/${repository}/${path}@${ref}`,
+    oidcIssuer: 'https://token.actions.githubusercontent.com',
+    githubWorkflow: { repository, ref, path },
+  };
+}
+
+/** The producer evidence and the completeness statement these inputs resolve to; deterministic. */
+async function deriveCompleteness(options, { outputRoot }) {
+  const resolution = {
+    distributionId: options.distributionId,
+    dataRoot: options.dataRoot,
+    editionsRoot: options.editionsRoot,
+    schemas: options.schemas,
+    expectedContractAuthority: options.expectedContractAuthority,
+    registryClientFactory: options.registryClientFactory,
+  };
+  const staged = outputRoot === null
+    ? await resolveProducerEvidence(resolution)
+    : await stageProducerEvidence({ ...resolution, outputRoot });
+  const completenessStatement = buildDistributionImagesStatement({
+    distributionLock: staged.distributionLock,
+    imageLock: staged.imageLock,
+    images: staged.images,
+    releaseSequence: options.releaseSequence,
+    releaseSourceCommit: options.releaseSourceCommit,
+    runId: options.runId,
+    runAttempt: options.runAttempt,
+    issuedAt: options.issuedAt,
+    expiresAt: options.expiresAt,
+    maxTtlSeconds: options.policy.maxCompletenessTtlSeconds,
+    schemas: options.schemas,
+  });
+  return { staged, completenessStatement };
+}
+
+function signingArguments(options, statement) {
+  return {
+    statement,
+    root: options.stagingDirectory,
+    statementPath: COMPLETENESS_STATEMENT_PATH,
+    bundlePath: COMPLETENESS_BUNDLE_PATH,
+    signer: options.signer,
+    certificateWorkflowSha: options.releaseSourceCommit,
+    predicateType: options.schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE,
+  };
+}
+
+/**
+ * Stage the producer evidence of one edition and its completeness statement
+ * for signing. Returns the signing plan and the statement.
+ */
+export async function stageDistributionCompletenessEvidence(options) {
+  const { stagingDirectory } = options;
+  if (typeof stagingDirectory !== 'string' || !isAbsolute(stagingDirectory)) {
+    throw new Error('the staging directory must be an absolute path');
+  }
+  if (existsSync(stagingDirectory)) {
+    throw new Error(`evidence staging directory already exists: ${stagingDirectory}`);
+  }
+  assertGitHubProducerContext(
+    { signer: options.signer, producerWorkflowSha: options.releaseSourceCommit },
+    options.githubContext,
+  );
+  mkdirSync(stagingDirectory, { recursive: true, mode: 0o700 });
+  try {
+    const { completenessStatement } = await deriveCompleteness(options, { outputRoot: options.stagingDirectory });
+    const plan = stageEvidenceStatement(signingArguments(options, completenessStatement));
+    return {
+      plan: { ...plan, kind: 'completeness', distributionId: options.distributionId },
+      completenessStatement,
+    };
+  } catch (error) {
+    rmSync(stagingDirectory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/**
+ * Accept the signed completeness bundle of a staged directory, write
+ * `evidence-set.json` and seal `evidenceRoot`.
+ *
+ * `evidenceRoot` is BUILT, never renamed from the staging: the producer
+ * evidence is re-resolved from the registry and must be byte-identical to what
+ * was staged, the completeness statement is re-derived and the signed bundle
+ * canonicalized and verified, and only those derived files are written. The
+ * staging must hold exactly what stage recorded and does not outlive the
+ * accept (see `sealed-evidence-accept.mjs`).
+ */
+export async function assembleDistributionEvidenceSet(options) {
+  const { evidenceRoot, stagingDirectory, readCosignVersion, runCosign } = options;
+  if (
+    typeof evidenceRoot !== 'string' ||
+    !isAbsolute(evidenceRoot) ||
+    typeof stagingDirectory !== 'string' ||
+    !isAbsolute(stagingDirectory)
+  ) {
+    throw new Error('the evidence root and the staging directory must be absolute paths');
+  }
+  if (typeof readCosignVersion !== 'function' || typeof runCosign !== 'function') {
+    throw new Error('cosign seams are required');
+  }
+  const sealing = reserveSealing(evidenceRoot, 'evidence');
+  let derived;
+  try {
+    assertGitHubProducerContext(
+      { signer: options.signer, producerWorkflowSha: options.releaseSourceCommit },
+      options.githubContext,
+    );
+    assertPinnedCosignVersion(readCosignVersion(), options.policy?.cosignVersion);
+    derived = await deriveCompleteness(options, { outputRoot: null });
+  } catch (error) {
+    discardStaging(stagingDirectory);
+    throw error;
+  }
+  const { staged, completenessStatement } = derived;
+  return sealAccepted({
+    stagingDirectory,
+    sealing,
+    outputDirectory: evidenceRoot,
+    build: () => {
+      assertStagedExactly(stagingDirectory, [
+        ...staged.producers.flatMap((producer) => stagedProducerFiles(producer).map(([path]) => path)),
+        COMPLETENESS_STATEMENT_PATH,
+        COMPLETENESS_BUNDLE_PATH,
+      ]);
+      for (const producer of staged.producers) {
+        for (const [path, bytes] of stagedProducerFiles(producer)) {
+          if (!readFileSync(join(stagingDirectory, path)).equals(bytes)) {
+            throw new Error(`staged ${path} is not the producer evidence this edition resolves to`);
+          }
+          mkdirSync(dirname(join(sealing, path)), { recursive: true, mode: 0o755 });
+          writeFileSync(join(sealing, path), bytes, { flag: 'wx', mode: 0o644 });
+        }
+      }
+      const completeness = acceptSignedEvidenceStatement({
+        ...signingArguments(options, completenessStatement),
+        sealingRoot: sealing,
+        runCosign,
+      });
+      const evidenceSet = buildDistributionImageEvidenceSet({
+        distributionId: options.distributionId,
+        producerEvidence: staged.producerEvidence,
+        completeness,
+        schemas: options.schemas,
+      });
+      writeFileSync(join(sealing, EVIDENCE_SET_FILE), canonicalJsonBytes(evidenceSet), {
+        flag: 'wx',
+        mode: 0o644,
+      });
+      return {
+        evidenceRoot,
+        evidenceSet,
+        completeness,
+        completenessStatement,
+        completenessStatementDigest: completeness.statementDigest,
+      };
+    },
+  });
+}
+
+function requireInteger(raw, label, { positive }) {
+  const value = Number(raw);
+  if (!/^\d+$/.test(String(raw)) || !Number.isSafeInteger(value) || (positive && value <= 0)) {
+    throw new Error(`--${label} must be a ${positive ? 'positive' : 'non-negative'} integer`);
+  }
+  return value;
+}
+
+const SHARED_FLAGS = Object.freeze([
+  'distribution',
+  'staging',
+  'release-sequence',
+  'release-source-commit',
+  'run-id',
+  'run-attempt',
+  'issued-at',
+  'expires-at',
+  'signer-repository',
+  'signer-ref',
+  'signer-workflow-path',
+  'github-repository',
+  'github-ref',
+  'github-sha',
+  'github-workflow-ref',
+]);
+
+async function main() {
+  const [phase, ...args] = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
+    WorkspaceRoot.Data,
+    WorkspaceRoot.Editions,
+    WorkspaceRoot.Kernel,
+  ]);
+  if (phase !== 'stage' && phase !== 'accept') {
+    throw new Error(
+      'usage: xema edition evidence statement completeness stage … | xema edition evidence assemble-set …',
+    );
+  }
+  const flags = parseEvidenceCliFlags(args, {
+    single: phase === 'stage' ? SHARED_FLAGS : [...SHARED_FLAGS, 'evidence-root', 'cosign'],
+  });
+  const { schemas, contractAuthority } = await loadProducerKernelSchemas({ dataRoot: dataRoot() });
+  const options = {
+    distributionId: flags.require('distribution'),
+    dataRoot: dataRoot(),
+    editionsRoot: editionsRoot(),
+    stagingDirectory: resolve(flags.require('staging')),
+    schemas,
+    expectedContractAuthority: contractAuthority,
+    policy: loadPinnedTrustPolicy({ dataRoot: dataRoot(), schemas }),
+    signer: githubWorkflowSigner({
+      repository: flags.require('signer-repository'),
+      ref: flags.require('signer-ref'),
+      path: flags.require('signer-workflow-path'),
+    }),
+    githubContext: {
+      repository: flags.require('github-repository'),
+      ref: flags.require('github-ref'),
+      sha: flags.require('github-sha'),
+      workflowRef: flags.require('github-workflow-ref'),
+    },
+    releaseSequence: requireInteger(flags.require('release-sequence'), 'release-sequence', {
+      positive: false,
+    }),
+    releaseSourceCommit: flags.require('release-source-commit'),
+    runId: flags.require('run-id'),
+    runAttempt: requireInteger(flags.require('run-attempt'), 'run-attempt', { positive: false }),
+    issuedAt: flags.require('issued-at'),
+    expiresAt: flags.require('expires-at'),
+  };
+  if (phase === 'stage') {
+    const { plan } = await stageDistributionCompletenessEvidence(options);
+    process.stdout.write(serializeJson(plan));
+    return;
+  }
+  const result = await assembleDistributionEvidenceSet({
+    ...options,
+    evidenceRoot: resolve(flags.require('evidence-root')),
+    ...createCosignVerifier(resolve(flags.require('cosign'))),
+  });
+  process.stdout.write(
+    serializeJson({
+      schemaVersion: 1,
+      kind: 'evidence-set',
+      distributionId: options.distributionId,
+      evidenceRoot: result.evidenceRoot,
+      evidenceSetPath: EVIDENCE_SET_FILE,
+      producerBundles: result.evidenceSet.producerEvidence.length,
+      completenessStatementDigest: result.completenessStatementDigest,
+    }),
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[distribution-completeness-evidence] ${error.message}`);
+    process.exitCode = 1;
+  });
+}