@xemahq/xema 0.25.1 → 0.27.0

package/edition/remedy-command.mjs

@@ -0,0 +1,89 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// 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`, and closure-ledger A25).
+//
+//   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. Closure-ledger A26 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

@@ -0,0 +1,101 @@
+#!/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, and the oras binaries that may
+// read a registry. 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,
+  readEvidenceTrustPin,
+  readStatedKernelContractAuthority,
+  requireOrasDigests,
+  writeEvidenceTrustPin,
+} from './evidence-trust-pin.mjs';
+import { loadKernelDistributionSchemas } from './lib.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;
+  }
+  return writeEvidenceTrustPin({
+    dataRoot: root,
+    declaration,
+    policyDigest,
+    verifier,
+    kernelContractAuthority: readStatedKernelContractAuthority({ dataRoot: root, schemas }),
+    trustedOrasBinaryDigests: orasDigests,
+  });
+}
+
+/** `--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}, ` +
+        `kernel contract authority ${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

@@ -0,0 +1,58 @@
+// 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];
+}

package/edition/resolve-chart-set.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+// resolve-chart-set — pin the Helm chart-set version an install resolves, so
+// that no human has to.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// WHY THIS EXISTS
+//
+//   `xema-appliance provision` pulls charts from the configured chart registry
+//   at an explicitly pinned `XEMA_CHART_VERSION`, and REFUSES to run without
+//   one ("refusing to pull a floating chart version"). Nothing set it. The
+//   value was typed by an operator, which made every platform update a step
+//   somebody had to remember and get right — exactly the maintenance surface
+//   the images plane already removed for itself with images.lock.json.
+//
+//   This resolves it instead, and writes the answer to a lock the appliance
+//   reads. The env var survives as an override, never as the only source.
+//
+// WHY IT IS RESOLVED AND NOT COMPUTED
+//
+//   The version cannot be derived from this repository: it is minted by the two
+//   publish-charts workflows (xema-deploy and xema-infra-services) at publish
+//   time. So the only truthful way to pin it is to ask the registry which
+//   versions actually exist, and that is what this does.
+//
+// EACH PUBLISHER IS PINNED INDEPENDENTLY
+//
+//   One OCI namespace, two publishers, and an install resolves charts from
+//   BOTH — a deployments/*/infra-plan.json names components from each in the
+//   same list. Each closes its own half with an index chart, written only after
+//   every chart of that half is pushed, signed and proved served.
+//
+//   They used to be pinned by ONE shared version, which meant both had to mint
+//   the same string, which meant deriving it from the only input they could both
+//   reproduce — the UTC date — which capped publishing at once a day. The shared
+//   pin was the coupling and the day of latency was its price. Each half is now
+//   pinned separately: a publisher that has not run does not hold the other back.
+//
+// WHICH VERSION IS CURRENT, WHEN COORDINATES DO NOT SORT
+//
+//   Index versions are content-derived (`0.0.0-h<hash>`), so semver precedence
+//   says nothing about which is newest — hashes have no order. The registry
+//   does: `helm push` stamps `org.opencontainers.image.created` into the
+//   manifest, so the current index is the one most recently pushed, read from
+//   the registry rather than guessed from the tag.
+//
+//   Deliberately NOT a moving `latest` tag. Helm derives the OCI tag from the
+//   chart version and will not push a non-semver one, and a moving pointer is
+//   exactly what this plane's image rules refuse — a late run can reach it after
+//   a newer one moved it. Every coordinate here stays immutable.
+//
+// FAIL-CLOSED
+//
+//   No eligible version is an ERROR, never an empty or stale pin. A lock that
+//   silently kept yesterday's value because today's read failed is the exact
+//   shape this plane has been bitten by: a claim that outlives its evidence.
+
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { EditionChannel } from './edition-channel.mjs';
+import {
+  EDITION_CHART_SET_FILE,
+  EditionChartSetCheck,
+  assertRosteredChartSetLock,
+  checkEditionChartSet,
+  writeEditionChartSet,
+} from './edition-chart-set.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, dataRoot, editionsRoot, isEntryModule } from './edition-workspace.mjs';
+import { serializeJson } from './lib.mjs';
+import { OrasRegistry } from './oras.mjs';
+import { deployPinKey } from './pin-source.mjs';
+import {
+  loadRegistryCredentialDeclarations,
+  resolveRegistryCredential,
+} from './registry-credentials.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Deploy, WorkspaceRoot.Kernel]);
+}
+
+export const CHART_SET_LOCK_FILE = 'chart-set.lock.json';
+export const chartSetLockPath = () => join(dataRoot(), CHART_SET_LOCK_FILE);
+
+/**
+ * The chart registry and its publishers.
+ *
+ * ONE PIN for every edition, and EVERY EDITION CARRIES IT. The set that
+ * satisfies the widest edition satisfies the narrowest, so there is one answer
+ * to "which chart set do editions take now" — this lock. But the chart
+ * generation a deployment renders is part of its edition (owner ruling
+ * 2026-10-04), so each edition holds a byte-identical copy as
+ * `<id>/chart-set.lock.json`, hashed into its coordinate and published with it.
+ * This script is the one writer of the pin AND every copy, and dist-check
+ * refuses a copy that differs — so the copies cannot disagree
+ * (edition-chart-set.mjs).
+ */
+const chartRegistry = () => editionWorkspaceConfig().chartRegistry;
+const chartSetPublishers = () => editionWorkspaceConfig().chartPublishers;
+
+/** `<host>/<path>` -> the repository path the registry API addresses. */
+function registryRepository(indexName) {
+  return `${chartRegistry().replace(/^oci:\/\/[^/]+\//, '')}/${indexName}`;
+}
+
+function registryAuthority() {
+  return chartRegistry().replace(/^oci:\/\//, '').split('/')[0];
+}
+
+/**
+ * cosign publishes a signature as a TAG (`sha256-<digest>.sig`) beside the
+ * artifact it signs. Those are not versions and must never be pinned.
+ */
+export function isVersionTag(tag) {
+  return !tag.startsWith('sha256-');
+}
+
+/**
+ * The newest index version for ONE publisher, by registry creation time.
+ * `candidates` is `[{ tag, createdAt }]`; returns the tag or null.
+ *
+ * A tag whose manifest carries no creation stamp is REFUSED rather than sorted
+ * last: guessing an order for a coordinate whose age is unknown is how a stale
+ * set gets pinned as current.
+ */
+export function selectNewestIndex(allCandidates) {
+  if (!Array.isArray(allCandidates)) {return null;}
+  // A develop chart version (`0.0.0-dev.<sha12>`) is a frozen xema-deploy
+  // snapshot, never a release index: it is not a candidate for the release pin.
+  const candidates = allCandidates.filter((c) => !c.tag.startsWith(DEVELOP_CHART_VERSION_PREFIX));
+  if (candidates.length === 0) {return null;}
+  const undated = candidates.filter((c) => !c.createdAt);
+  if (undated.length > 0) {
+    throw new Error(
+      `index version(s) ${undated.map((c) => c.tag).join(', ')} carry no ` +
+        'org.opencontainers.image.created stamp, so "which is current" cannot be answered. ' +
+        'Refusing to guess.',
+    );
+  }
+  return [...candidates].sort(
+    (a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt),
+  )[0].tag;
+}
+
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+/** The index chart annotation listing the charts the publisher closed the set with. */
+export const INDEX_ROSTER_ANNOTATION = 'xema.dev/chart-set-charts';
+
+export function buildLock(versionsByIndex, rostersByIndex, publishers = chartSetPublishers()) {
+  // Every publisher's VERSION first: a pin that resolved nothing for one half is
+  // the more fundamental refusal, whatever its roster.
+  for (const publisher of publishers) {
+    if (!versionsByIndex[publisher.index]) {
+      throw new Error(`no index version was resolved for '${publisher.index}'`);
+    }
+  }
+  return {
+    // 3: every member is `{version, digest}` (its OCI manifest digest), so the
+    // lock itself is the trust anchor. 2 added `publishers[].version` (one each)
+    // in place of one shared version, which would couple the two halves.
+    schemaVersion: 3,
+    registry: chartRegistry(),
+    publishers: publishers.map((publisher) => {
+      const version = versionsByIndex[publisher.index];
+      if (!version) {
+        throw new Error(`no index version was resolved for '${publisher.index}'`);
+      }
+      // THE ROSTER, sealed: chart name → {version, digest}, so an edition that
+      // copies this lock selects and verifies every chart without the registry.
+      const roster = rostersByIndex?.[publisher.index];
+      if (!roster || Object.keys(roster).length === 0) {
+        throw new Error(`no roster was read for '${publisher.index}@${version}'`);
+      }
+      const charts = {};
+      for (const name of Object.keys(roster).sort()) {
+        const member = roster[name];
+        if (!DIGEST_PATTERN.test(String(member?.digest))) {
+          throw new Error(`${publisher.index}@${version}: ${name} has no sha256 manifest digest`);
+        }
+        charts[name] = { version: member.version, digest: member.digest };
+      }
+      return { ...publisher, version, charts };
+    }),
+  };
+}
+
+/**
+ * The roster an index chart carries: its `xema.dev/chart-set-charts`
+ * annotation, one `{"name","version"[,"digest"]}` JSON object per line, read from the
+ * chart's OCI config blob (helm stores Chart.yaml's metadata there). The blob is
+ * fetched by digest and hash-checked by the client. Returns name → {version,
+ * digest?}; `digest` is present only when the index carries one.
+ */
+export function parseIndexRoster(annotation, label) {
+  if (typeof annotation !== 'string' || annotation.trim().length === 0) {
+    throw new Error(`${label} carries no xema.dev/chart-set-charts roster`);
+  }
+  const charts = {};
+  for (const line of annotation.split('\n').map((l) => l.trim()).filter(Boolean)) {
+    const member = JSON.parse(line);
+    if (typeof member?.name !== 'string' || typeof member?.version !== 'string') {
+      throw new Error(`${label}: roster line is not {name, version}: ${line}`);
+    }
+    if (Object.hasOwn(charts, member.name)) {throw new Error(`${label}: roster names ${member.name} twice`);}
+    if (member.digest !== undefined && !DIGEST_PATTERN.test(String(member.digest))) {
+      throw new Error(`${label}: ${member.name} carries a malformed digest: ${member.digest}`);
+    }
+    charts[member.name] = member.digest === undefined
+      ? { version: member.version }
+      : { version: member.version, digest: member.digest };
+  }
+  return Object.fromEntries(Object.entries(charts).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+/**
+ * Give every member a manifest digest: the index's own when it carries one,
+ * else the registry's for `<name>:<version>` (`lookup`). Both present and
+ * different is refused.
+ */
+export async function sealRoster(roster, lookup, label) {
+  const sealed = {};
+  for (const [name, member] of Object.entries(roster)) {
+    const registryDigest = await lookup(name, member.version);
+    if (!DIGEST_PATTERN.test(String(registryDigest))) {
+      throw new Error(`${label}: registry returned no sha256 manifest digest for ${name}:${member.version}`);
+    }
+    if (member.digest !== undefined && member.digest !== registryDigest) {
+      throw new Error(
+        `${label}: ${name}:${member.version} index digest ${member.digest} != registry ${registryDigest}`,
+      );
+    }
+    sealed[name] = { version: member.version, digest: member.digest ?? registryDigest };
+  }
+  return sealed;
+}
+
+/** The annotations of the index chart `<indexName>:<version>`, read from its OCI config blob (helm stores Chart.yaml's metadata there). */
+export async function indexAnnotations(client, indexName, version) {
+  const repository = registryRepository(indexName);
+  const manifest = JSON.parse((await client.getManifestByTag(repository, version)).bytes.toString('utf8'));
+  const configDigest = manifest?.config?.digest;
+  if (typeof configDigest !== 'string') {throw new Error(`${indexName}@${version}: manifest names no config blob`);}
+  const config = JSON.parse((await client.getBlob(repository, configDigest)).toString('utf8'));
+  return config?.annotations ?? {};
+}
+
+async function indexRoster(client, indexName, version) {
+  const annotations = await indexAnnotations(client, indexName, version);
+  return parseIndexRoster(annotations[INDEX_ROSTER_ANNOTATION], `${indexName}@${version}`);
+}
+
+/** Every edition directory (one holding a distribution.lock.json) under the editions root. */
+function editionDirs() {
+  return readdirSync(editionsRoot(), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(editionsRoot(), entry.name, 'distribution.lock.json')))
+    .map((entry) => join(editionsRoot(), entry.name))
+    .sort();
+}
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const DEVELOP_CHART_VERSION_PREFIX = '0.0.0-dev.';
+const DEVELOP_SHA_LENGTH = 12;
+
+/** The develop chart version xema-deploy publishes for a frozen SHA: `0.0.0-dev.<sha12>`, also the OCI tag. */
+export const developChartVersion = (sha) => `${DEVELOP_CHART_VERSION_PREFIX}${sha.slice(0, DEVELOP_SHA_LENGTH)}`;
+
+/** Every chart (a directory with a Chart.yaml, library charts included) of an xema-deploy checkout, sorted. */
+function deployChartNames(xemaDeployDir) {
+  const chartsDir = join(xemaDeployDir, 'charts');
+  if (!existsSync(chartsDir)) {throw new Error(`${xemaDeployDir} has no charts/ directory`);}
+  return readdirSync(chartsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(chartsDir, entry.name, 'Chart.yaml')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/** The registry client for the chart registry, with the data root's declared credential. */
+export function chartRegistryClient() {
+  const credential = resolveRegistryCredential({ authority: registryAuthority(), declarations: loadRegistryCredentialDeclarations() });
+  return new OrasRegistry({ credential });
+}
+
+/** The manifest digest the chart registry serves for `<chart>:<version>`. */
+const registryManifestDigest = (client) => async (name, version) =>
+  (await client.getManifestByTag(registryRepository(name), version)).digest;
+
+/**
+ * The develop chart-set lock: the SAME rostered lock a release pins, over the
+ * charts xema-deploy publishes for the frozen SHA. The deploy publisher (the
+ * workspace publisher whose repository is the deploy pin role's) publishes every
+ * chart directory of its tree at `0.0.0-dev.<sha12>`; the roster records each
+ * chart's registry manifest digest, so a consumer pulls by digest exactly as it
+ * does for a release. A chart the registry does not serve is refused by name.
+ * `lookup(name, version)` defaults to the chart registry and returns the digest.
+ */
+export async function resolveDevelopChartSet({ xemaDeployDir, xemaDeploySha, lookup }) {
+  if (!SHA_PATTERN.test(xemaDeploySha ?? '')) {
+    throw new Error(`the deploy checkout SHA is not a 40-hex commit: ${JSON.stringify(xemaDeploySha)}`);
+  }
+  const names = deployChartNames(xemaDeployDir);
+  if (names.length === 0) {throw new Error(`the deploy checkout at ${xemaDeploySha} has no chart (charts/<name>/Chart.yaml)`);}
+  const deployRepo = basename(deployPinKey());
+  const publishers = chartSetPublishers().filter((publisher) => basename(publisher.repo) === deployRepo);
+  if (publishers.length !== 1) {
+    throw new Error(
+      `${publishers.length} chart publishers have repository ${deployRepo} (the deploy pin role); exactly one must, ` +
+        'since it is the publisher whose develop charts this lock pins',
+    );
+  }
+  const version = developChartVersion(xemaDeploySha);
+  const digestOf = lookup ?? registryManifestDigest(chartRegistryClient());
+  const roster = Object.fromEntries(names.map((name) => [name, { version }]));
+  const sealed = await sealRoster(roster, digestOf, `${publishers[0].index}@${version}`);
+  const lock = buildLock({ [publishers[0].index]: version }, { [publishers[0].index]: sealed }, publishers);
+  return assertRosteredChartSetLock(lock, EDITION_CHART_SET_FILE, EditionChannel.Develop);
+}
+
+export function readLock(path = chartSetLockPath()) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every index tag of one publisher, with the creation stamp the registry
+ * recorded for it.
+ */
+async function indexCandidates(client, indexName) {
+  const repository = registryRepository(indexName);
+  const tags = (await client.listTags(repository)).filter(isVersionTag);
+  const candidates = [];
+  for (const tag of tags) {
+    const manifest = await client.getManifestByTag(repository, tag);
+    const document = JSON.parse(manifest.bytes.toString('utf8'));
+    candidates.push({
+      tag,
+      createdAt: document?.annotations?.['org.opencontainers.image.created'] ?? null,
+    });
+  }
+  return candidates;
+}
+
+async function resolveFromRegistry() {
+  const client = chartRegistryClient();
+
+  const versionsByIndex = {};
+  const rostersByIndex = {};
+  for (const { index, repo } of chartSetPublishers()) {
+    const candidates = await indexCandidates(client, index);
+    const version = selectNewestIndex(candidates);
+    if (!version) {
+      throw new Error(
+        `${index} has no published version, so ${repo} has never closed a chart set. ` +
+          'An index is written only after its publisher pushes, signs and proves served every ' +
+          'chart of its half — its absence means that half has never completed.',
+      );
+    }
+    versionsByIndex[index] = version;
+    const roster = await indexRoster(client, index, version);
+    // The registry is asked for every member, so an index digest is checked
+    // against it and a member without one still gets sealed.
+    rostersByIndex[index] = await sealRoster(
+      roster,
+      async (name, memberVersion) => (await client.getManifestByTag(registryRepository(name), memberVersion)).digest,
+      `${index}@${version}`,
+    );
+  }
+  return { versionsByIndex, rostersByIndex };
+}
+
+async function main(argv) {
+  const check = argv.includes('--check');
+  const { versionsByIndex, rostersByIndex } = await resolveFromRegistry();
+  const next = buildLock(versionsByIndex, rostersByIndex);
+  assertRosteredChartSetLock(next, CHART_SET_LOCK_FILE, EditionChannel.Release);
+  const pinText = serializeJson(next);
+  const current = readLock();
+  // The pin AND every edition's copy of it: one writer, one run, so the N copies
+  // of one fact cannot disagree (edition-chart-set.mjs).
+  const staleEditions = editionDirs().filter((dir) => checkEditionChartSet(dir, pinText) !== EditionChartSetCheck.GREEN);
+  const changed = serializeJson(current) !== pinText || staleEditions.length > 0;
+
+  const describe = next.publishers
+    .map((publisher) => `${publisher.index}=${publisher.version}`)
+    .join(' ');
+
+  if (check) {
+    if (changed) {
+      throw new Error(
+        `${CHART_SET_LOCK_FILE} is stale${staleEditions.length ? ` (and ${staleEditions.length} edition copy/copies differ from it)` : ''}. The registry's current indexes are ${describe}. ` +
+          "Run 'node resolve-chart-set.mjs' and commit the result.",
+      );
+    }
+    process.stdout.write(`chart-set: ${describe} (lock is current)\n`);
+    return;
+  }
+
+  if (!changed) {
+    process.stdout.write(`chart-set: ${describe} (unchanged)\n`);
+    return;
+  }
+  writeFileSync(chartSetLockPath(), pinText);
+  for (const dir of editionDirs()) {writeEditionChartSet(dir, pinText);}
+  process.stdout.write(`chart-set: ${describe} (pin + ${editionDirs().length} edition ${EDITION_CHART_SET_FILE})\n`);
+}
+
+if (isEntryModule(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`resolve-chart-set: ${error.message}\n`);
+    process.exit(1);
+  });
+}