@xemahq/xema 0.26.0 → 0.28.0

package/edition/resolve-distribution.mjs

@@ -0,0 +1,2318 @@
+#!/usr/bin/env node
+// resolve-distribution — resolve a `xema-distribution.json` (one manifest, no
+// `extends`) against the global biome index into a deterministic
+// `distribution.lock.json`. The lock is THE artifact every downstream consumer
+// reads (deploy generator, test-suite mapping, biome-host boot filter,
+// appliance build). No consumer re-applies the distribution rules.
+//
+// Usage:
+//   node resolve-distribution.mjs <root flags> <distribution-id>
+//
+// TWO resolution models, chosen per edition by `resolution` (README, "Declaring
+// an edition"):
+//   - `positive-closure` — roots only; the kernel's ONE closure algorithm
+//     (`resolveBiomeClosure`) over each biome's signed dependency contract and
+//     its required resources, with provenance written to the lock's
+//     `resolution` section. See `selectByPositiveClosure`.
+//   - absent — the selector model below, unchanged.
+//
+// WHAT AN EDITION IS, in both models: its explicit selections + the UNIVERSAL
+// components + their transitive dependencies. Universal means
+// `installationClass: "core"` (the kernel's `BiomeComponentInstallationClass`)
+// and NOTHING ELSE — the tier never decides it, the kernel tier included. That
+// every kernel-tier biome is universal is a VALIDATION of the index (a
+// kernel-tier entry that is not core-class is refused, see
+// `assertIndexDeclaresInstallationClasses`), not a second inclusion rule.
+//
+// Selector-model rules enforced (fail-fast, citing the offending id/edge):
+//   - universal (core-class) biomes are FORCE-INCLUDED as `required` and
+//     `mandatory`, and CANNOT be excluded; an index that carries no
+//     installation classes is REFUSED (never inferred from the tier);
+//   - dependency closure — every `requires` edge is resolved transitively from
+//     biome metadata; unknown or explicitly-excluded dependencies fail closed.
+//     A biome the edition NAMED (or swept by tier/origin) pulls its declared
+//     requirements of any class; what only a CLASS admitted (the universal
+//     floor included) may not reach a class the edition did not ask for;
+//   - trustPolicy.allow (when set) — every included biome's origin must be in
+//     the allow list.
+// Exclusion covers TWO namespaces through the one `exclude` list — a biome id
+// and a composed platform-service name (see the block that partitions them).
+// A core-class platform service cannot be excluded, and a biome whose API
+// declares a service edge onto an excluded platform service fails closed.
+// Selector semantics (mirror DistributionSelector):
+//   - { tier }   → all biomes of that tier, NEVER audience==='operator';
+//   - { origin } → all biomes of that origin, NEVER audience==='operator';
+//   - { installationClass } → all biomes of that installation class (how
+//     ESSENTIAL they are), NEVER audience==='operator'. Matches EXACTLY that
+//     class and does not imply the more essential ones (core is universal
+//     anyway).
+//   - { biome, version? } → that one biome by id (the ONLY way to pull an
+//     operator biome); if `version` is given it must be satisfied by the index
+//     version.
+//
+// The composed platform substrate is narrowed the same way: core-class and
+// unclassified services, the classes the edition names, and any service a
+// shipped biome's API edge requires (narrowPlatformServicesByClass + the
+// closure). A substrate service that declares no class is kept, never dropped —
+// absent is a third answer there exactly as it is on a biome component.
+//
+// Both the loaded distribution manifests AND the emitted lock are validated
+// against the BUILT kernel zod schemas (parseDistribution / parseDistributionLock).
+
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  adoptedFromLock,
+  editionAuthorizationModuleInputs,
+  fgaComposedModelTestRunner,
+  loadKernelAuthorizationComposer,
+  readAuthorizationLock,
+  resolveFgaCli,
+  sealEditionAuthorizationBase,
+  writeAuthorizationLock,
+} from './authorization-base.mjs';
+import { fleetChartSetLockPath, writeEditionChartSet } from './edition-chart-set.mjs';
+import { workspaceSection } from './edition-config.mjs';
+import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule, kernelPackageDir, platformServiceIndexPath } from './edition-workspace.mjs';
+import { walkDeclaredSources } from './external-source-walk.mjs';
+import {
+  biomeTierOrder,
+  assertDeclaredDatabasesUnowned,
+  buildCapabilityDomainOwners,
+  compareIndexEntries,
+  loadKernelBiomeContracts,
+  loadKernelDistributionSchemas,
+  resolveServiceDependencyOwners,
+  serializeJson,
+  sha256Hex,
+  validateImmutableBiomeIndex,
+  validateImmutableDistributionLock,
+  validateServiceDependencyOwnerParity,
+} from './lib.mjs';
+import { PUBLISHED_PIN_SOURCE, pinnedSource } from './pin-source.mjs';
+import { closureBiomeFacts } from './positive-closure.mjs';
+import { assertReleaseContent, assertReleaseEditionTree } from './release-channel-guard.mjs';
+import { commandFor } from './remedy-command.mjs';
+import { soleResourceProvider } from './required-resource-provider.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import { RuntimeSubjectKind } from './workspace-sections.mjs';
+
+/**
+ * `{ workflowSubjects }` for one index entry, or `{}` when it has none: the
+ * kernel's `deriveWorkflowSubjects` over the same `workerTaskQueues` and
+ * `workflowClients` the lock carries.
+ */
+export function lockedWorkflowSubjects(entry, schemas) {
+  const subjects = schemas.deriveWorkflowSubjects({
+    workerTaskQueues: entry.workerTaskQueues,
+    workflowClients: entry.workflowClients,
+  });
+  return subjects.length > 0 ? { workflowSubjects: subjects } : {};
+}
+
+/**
+ * `{ trustCeiling }` for one index entry under the edition's ceiling policy,
+ * or `{}` when the kernel's `deriveTrustCeiling` says it is the biome's
+ * default domain (the writer omits the default).
+ */
+export function lockedTrustCeiling(entry, editionCeiling, schemas) {
+  const ceiling = schemas.deriveTrustCeiling(entry.id, entry.origin, editionCeiling);
+  return ceiling === undefined ? {} : { trustCeiling: ceiling };
+}
+
+/**
+ * The lock's `serviceProcessFacts` for one index entry: exactly one row per
+ * shipped service, no more and no fewer. The index projection writes one per
+ * platform-scheduled image component, which IS `services`; a disagreement is
+ * an index the projection did not produce, and is refused rather than emitted
+ * as a lock that grades some services and silently not others.
+ */
+export function lockedServiceProcessFacts(entry) {
+  const services = Array.isArray(entry.services) ? entry.services : [];
+  const facts = entry.serviceProcessFacts ?? {};
+  const named = Object.keys(facts).sort();
+  if (serializeJson(named) !== serializeJson([...services].sort())) {
+    throw new Error(
+      `biome "${entry.id}" carries process facts for [${named.join(', ')}] but ships ` +
+        `services [${services.join(', ')}] — every shipped service has exactly one ` +
+        'row; regenerate the biome index.',
+    );
+  }
+  return facts;
+}
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.SourceHash]);
+}
+
+/**
+ * Minimal, deterministic, BOUNDED semver compatibility check used when a
+ * `{ biome, version }` selector pins a version. `semver` is not resolvable from
+ * the repo-root tooling context, so we implement the two forms our manifests
+ * actually use: an exact version (`1.2.3`) and a caret/tilde-free comparison.
+ * Supports a leading `^` (compatible-with) and `~` (approximately-equivalent),
+ * and a bare exact version. Anything more exotic fails fast — we do NOT
+ * silently accept a range we cannot reason about.
+ */
+function versionSatisfies(actual, range) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+    if (!m) {return null;}
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+  };
+  const a = parse(actual);
+  if (!a) {
+    throw new Error(`cannot parse actual version "${actual}"`);
+  }
+  const trimmed = range.trim();
+  const op = trimmed[0] === '^' || trimmed[0] === '~' ? trimmed[0] : '=';
+  const bare = op === '=' ? trimmed : trimmed.slice(1);
+  const r = parse(bare);
+  if (!r) {
+    throw new Error(
+      `cannot parse version range "${range}" — only exact / ^ / ~ forms are supported by this bounded checker`,
+    );
+  }
+  const cmp = (x, y) => {
+    for (let i = 0; i < 3; i += 1) {
+      if (x[i] !== y[i]) {return x[i] - y[i];}
+    }
+    return 0;
+  };
+  if (op === '=') {return cmp(a, r) === 0;}
+  if (cmp(a, r) < 0) {return false;} // must be >= the floor
+  if (op === '^') {
+    // compatible-with: same major (or, for 0.x, same minor)
+    if (r[0] > 0) {return a[0] === r[0];}
+    if (r[1] > 0) {return a[0] === 0 && a[1] === r[1];}
+    return cmp(a, r) === 0;
+  }
+  // '~': same major+minor
+  return a[0] === r[0] && a[1] === r[1];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ONE MANIFEST, ONE EDITION
+//
+// An edition states its own selections (a positive definition). There is no
+// parent, no chain and no inheritance: the manifest at
+// `<editions root>/<id>/xema-distribution.json` is the whole definition. A
+// manifest that still carries `extends` is refused before any other work.
+
+/** The field the edition model no longer has; a definition carrying it is refused. */
+const REFUSED_EXTENDS_FIELD = 'extends';
+
+/** An edition definition that breaks the edition model (a refused field); a caller tells it from an I/O or schema error by class. */
+export class EditionModelError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'EditionModelError';
+  }
+}
+
+/**
+ * The substrate candidates come from platform-service-index.json, never from an
+ * edition. A definition that declares them is refused: they would be a second,
+ * driftable copy of the index.
+ */
+const REFUSED_PLATFORM_SERVICES_FIELD = 'platformServices';
+
+/**
+ * A selection or declared dependency the index does not hold. Against a
+ * catalogue it is the catalogue's ceiling: the caller names the catalogue.
+ */
+export class UnknownSelectionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UnknownSelectionError';
+  }
+}
+
+/**
+ * Load, refuse `extends` on, and parse (kernel-validated) the single manifest of
+ * an edition from the editions root.
+ */
+export function loadEditionManifest(parseDistribution, id) {
+  const path = join(editionsRoot(), id, 'xema-distribution.json');
+  if (!existsSync(path)) {
+    throw new Error(`distribution "${id}" not found: ${path} does not exist`);
+  }
+  const raw = readStrictJsonFile(path);
+  if (raw !== null && typeof raw === 'object' && Object.hasOwn(raw, REFUSED_EXTENDS_FIELD)) {
+    throw new EditionModelError(
+      `edition "${id}": "${REFUSED_EXTENDS_FIELD}" is not part of the edition model; ` +
+        "state the edition's own selections (positive definition)",
+    );
+  }
+  if (raw !== null && typeof raw === 'object' && Object.hasOwn(raw, REFUSED_PLATFORM_SERVICES_FIELD)) {
+    throw new Error(
+      `edition "${id}": "${REFUSED_PLATFORM_SERVICES_FIELD}" is not part of the edition definition; ` +
+        'the platform substrate is drawn from platform-service-index.json by installation class ' +
+        "(core class, the classes the edition's include names, and services a shipped biome's API requires)",
+    );
+  }
+  const manifest = parseDistribution(raw);
+  if (manifest.id !== id) {
+    throw new Error(`distribution at ${path} declares id "${manifest.id}", but it was addressed as "${id}"`);
+  }
+  return manifest;
+}
+
+/**
+ * Compose an edition's single manifest into the flat
+ * { include[], exclude, trustPolicy?, trustCeiling?, requiredPlatforms, ... }
+ * the resolver consumes.
+ *
+ * `requiredPlatforms` is REQUIRED on every manifest (the kernel schema enforces
+ * it), so an edition always states its own architecture commitment. See
+ * `Distribution.requiredPlatforms`. Under a snapshot pin source every declared
+ * source's `ref` is the snapshot pin.
+ */
+export function composeEdition(parseDistribution, id, pinSource = PUBLISHED_PIN_SOURCE) {
+  return composeManifest(loadEditionManifest(parseDistribution, id), pinSource);
+}
+
+/** The composition of an already-parsed manifest (a customer definition is composed without an editions-root file). */
+export function composeManifest(manifest, pinSource = PUBLISHED_PIN_SOURCE) {
+  const roots = { product: [], ownerSelected: [], policy: [] };
+  for (const cls of Object.keys(roots)) {
+    roots[cls].push(...(manifest.roots?.[cls] ?? []));
+  }
+  // `sources[]` — external repositories this edition's biomes may additionally
+  // be drawn from, collected as BOTH the declarations (so the walk can
+  // materialise them) and their names (so `entrySourceAdmissible` can scope
+  // what they draw). `external-source-walk.mjs` stamps every entry it draws with
+  // the `source.name` that drew it, and edition scoping keys on that stamp.
+  const sources = manifest.sources ?? [];
+  const { resolution } = manifest;
+
+  return {
+    include: [...(manifest.include ?? [])],
+    exclude: new Set(manifest.exclude ?? []),
+    trustPolicy: manifest.trustPolicy,
+    trustCeiling: manifest.trustCeiling,
+    requiredPlatforms: manifest.requiredPlatforms,
+    // Visibility is a RESTRICTION; the caller (which holds the kernel enum)
+    // reduces the declarations.
+    declaredVisibilities: manifest.visibility === undefined ? [] : [manifest.visibility],
+    declaredSourceNames: new Set(sources.map((source) => source.name)),
+    declaredSources: sources.map((source) => pinnedSource(source, pinSource)),
+    owner: manifest.owner,
+    leaf: manifest,
+    // Present ONLY for a positive-closure edition, so a selector-model
+    // composition carries exactly the keys it always did.
+    ...(resolution === undefined ? {} : { resolution, roots }),
+  };
+}
+
+function readBiomeIndex() {
+  if (!existsSync(biomeIndexPath())) {
+    throw new Error(
+      `${biomeIndexPath()} not found — run \`${commandFor('build-biome-index.mjs')}\` first`,
+    );
+  }
+  return JSON.parse(readFileSync(biomeIndexPath(), 'utf8'));
+}
+
+function readPlatformServiceIndex(parsePlatformServiceSourceIndex) {
+  if (!existsSync(platformServiceIndexPath())) {
+    throw new Error(
+      `${platformServiceIndexPath()} not found — run the trusted platform-service index generator first`,
+    );
+  }
+  return parsePlatformServiceSourceIndex(
+    JSON.parse(readFileSync(platformServiceIndexPath(), 'utf8')),
+  );
+}
+
+/** Unique key for an index/lock entry (id+target+repo distinguishes cultivar/reference + web/server pairs). */
+function entryKey(e) {
+  return JSON.stringify([e.id, e.target, e.repo]);
+}
+
+/**
+ * The only tree a `target: web` biome can be BUILT from: the repository of the
+ * host image, which the data root declares as its one `host`-kind runtime image
+ * source (`runtimeImageSources`). Derived, so it is stated once.
+ *
+ * A web biome ships by being bundled into the single host image: host-web's
+ * `generate-biome-loaders.mjs` builds `WEB_BIOME_LOADERS` by walking
+ * `biomes/<tier>/<id>/xema-biome.json` under its OWN repo, and the SPA imports
+ * a biome only through that map. A web biome whose manifest lives anywhere
+ * else therefore has no producer — the REMOTE_FEDERATED path that would give
+ * it one does not ship yet.
+ */
+function webBiomeProducerRepo() {
+  const hosts = workspaceSection('runtimeImageSources', 'knowing which repository produces web biomes')
+    .supplementalSources.filter((source) => source.kind === RuntimeSubjectKind.Host);
+  if (hosts.length !== 1) {
+    throw new Error(
+      `edition-workspace.json runtimeImageSources must declare exactly one "${RuntimeSubjectKind.Host}" source ` +
+        `(the image web biomes are bundled into); it declares ${hosts.length}`,
+    );
+  }
+  return hosts[0].repo;
+}
+
+/**
+ * Whether this index entry can actually be DELIVERED by some build.
+ *
+ * Server biomes are always deliverable — they are images, and
+ * `check-image-producers` already asserts every lock subject has a producing
+ * workflow. That assertion never covered web biomes, and this is it.
+ *
+ * WHY THIS IS A SELECTOR RULE, exactly like `audience !== 'operator'` above.
+ * A `{ tier: "platform" }` selector states an intent about a DEPENDENCY TIER;
+ * it cannot state that the thing it swept in is buildable. Three web biomes
+ * authored in xema-cultivars and xema-community were swept into `cloud`,
+ * `oss`, `appliance-base` and `xema-internal` that way, and every org received
+ * them as catalog entries the SPA resolves and then drops with
+ * `unavailable_in_build` — measured live on xema.dev at three warnings per page
+ * load.
+ *
+ * That was first fixed by naming the three in `core.exclude`. This replaces
+ * that list, and the difference is the whole point: a list of three names is
+ * silently wrong the day a FOURTH web biome is authored outside host-web,
+ * which is the exact shape this repository calls a gate that cannot fail. The
+ * property — "a web biome must have a producer" — is derivable from the index,
+ * so it is asserted rather than enumerated.
+ *
+ * ── THIS RULE DOES NOT RETIRE ITSELF. SAY SO, BECAUSE IT LOOKS LIKE IT MIGHT ──
+ *
+ * The intended architecture is that a web biome authored in a carved repo ships
+ * as a Module Federation REMOTE, not by being vendored into the host image, and
+ * that path is BUILT: `submodules/xema-host-web/src/lib/biomes/load-remote-biome.ts`
+ * is a complete 488-line loader — origin allowlist, trust-verdict gate,
+ * `registerRemotes` then `loadRemote`. It is inert only because the backend
+ * publishes nothing for it: `next.config.mjs` records that
+ * `listRemoteFederated` returns `[]` today, so no remote is ever registered.
+ *
+ * So the honest reading is that this predicate encodes a PREMISE — bundling is
+ * currently the only path that delivers — and not a permanent truth about where
+ * web biomes belong. It cannot detect the premise changing: the index carries
+ * `repo`/`path`/`sourceCommit` and NO remote coordinate (see `images.lock.json`
+ * `webBiomes`), so there is nothing here to derive MF-readiness from, and a
+ * dormant branch reading a field no producer writes would be machinery shipped
+ * before its second consumer.
+ *
+ * The day `listRemoteFederated` returns rows, this predicate starts excluding
+ * biomes that CAN ship — the same silent wrongness in the opposite direction —
+ * and someone must widen it. That trigger is named here so a grep for
+ * `listRemoteFederated` finds it. Do not restate this rule anywhere else; one
+ * premise, one place to correct.
+ */
+export function isDeliverable(entry, webProducerRepos) {
+  return entry.target !== 'web' || (webProducerRepos ?? [webBiomeProducerRepo()]).includes(entry.repo);
+}
+
+/**
+ * The ONE installation class that is universal: in every edition, `required`,
+ * `mandatory`, never excludable. Read from the kernel enum, never restated.
+ */
+export function universalInstallationClass() {
+  return loadKernelBiomeContracts().BiomeComponentInstallationClass.Core;
+}
+
+/** Is this index entry (or platform service) universal? Its class decides; nothing else. */
+export function isUniversal(entry) {
+  return entry.installationClass === universalInstallationClass();
+}
+
+/**
+ * The resolver's precondition on its index: installation classes are DECLARED,
+ * and the kernel tier is universal.
+ *
+ * AN INDEX THAT CARRIES NO CLASSES CANNOT ANSWER "WHAT IS IN EVERY EDITION",
+ * and it is refused rather than read some other way. Reading the tier instead
+ * would be the coupling this resolver no longer has (essentialness is the
+ * kernel `installationClass`, a separate axis from the tier ladder), and
+ * resolving it as "nothing is universal" would lock an edition with no floor
+ * that reads as deliberate. The index is generated from a pinned source ref, so
+ * an index built before the manifests declared classes produces exactly that.
+ *
+ * A kernel-tier entry that is not core-class is a manifest defect, refused by
+ * name: the kernel tier is the floor everything else loads on, so its biomes
+ * declare `installationClass: "core"` (xema-base
+ * `check-installation-class-declared` holds the same rule at the source). And a
+ * core-class OPERATOR biome is refused because the two answers contradict: an
+ * operator biome ships only where an edition names it, a universal one ships
+ * everywhere.
+ */
+export function assertIndexDeclaresInstallationClasses(id, index) {
+  if (!index.some((entry) => entry.installationClass !== undefined)) {
+    throw new Error(
+      `distribution "${id}": NO entry in the biome index carries an installationClass, so ` +
+        `the index cannot say which components are universal (installationClass core) ` +
+        `and every edition would resolve without its floor. The tier is never read in its ` +
+        `place. Regenerate the index from a ref where the biome manifests declare ` +
+        `xema.components[].installationClass (\`${commandFor('build-biome-index.mjs')}\`).`,
+    );
+  }
+  const universal = universalInstallationClass();
+  for (const entry of [...index].sort(compareIndexEntries)) {
+    if (entry.tier === 'kernel' && entry.installationClass !== universal) {
+      throw new Error(
+        `distribution "${id}": kernel-tier biome "${entry.id}" (${entry.repo}) declares ` +
+          `installationClass ${entry.installationClass === undefined ? '(none)' : `"${entry.installationClass}"`}; ` +
+          `every kernel-tier biome must declare "${universal}" — fix the manifest and regenerate the index.`,
+      );
+    }
+    if (entry.installationClass === universal && entry.audience === 'operator') {
+      throw new Error(
+        `distribution "${id}": operator biome "${entry.id}" (${entry.repo}) declares installationClass ` +
+          `"${universal}" — an operator biome ships only where an edition names it, so it cannot be universal.`,
+      );
+    }
+  }
+}
+
+/** Every installation class an edition's `include[]` explicitly asks for. */
+export function selectedInstallationClasses(include) {
+  const classes = new Set();
+  for (const selector of include) {
+    if ('installationClass' in selector) {classes.add(selector.installationClass);}
+  }
+  return classes;
+}
+
+/**
+ * The classes an edition's substrate and closure may reach WITHOUT a named
+ * root: the universal class plus every class the edition names.
+ */
+export function admittedInstallationClasses(include) {
+  const classes = selectedInstallationClasses(include);
+  classes.add(universalInstallationClass());
+  return classes;
+}
+
+/**
+ * Narrow the composed substrate to the admitted classes
+ * (`admittedInstallationClasses`). Two rules, and the second is the one that is
+ * easy to get wrong:
+ *
+ *   1. a service whose declared class is admitted is KEPT;
+ *   2. a service that declares NO class is KEPT, never dropped. Absent is a
+ *      third answer on the substrate exactly as it is on a component: dropping
+ *      an unclassified service would substitute a class ("not asked for") for
+ *      an absent one, which is precisely what the kernel's docblock forbids.
+ *
+ * Anything else is not shipped HERE — but the closure still adds a service a
+ * shipped biome's API edge requires (see `requirePlatformOwner`), so naming a
+ * biome brings the substrate it needs.
+ */
+export function narrowPlatformServicesByClass(platformServices, classes) {
+  const kept = new Map();
+  for (const [name, service] of platformServices) {
+    if (
+      service.installationClass === undefined ||
+      classes.has(service.installationClass)
+    ) {
+      kept.set(name, service);
+    }
+  }
+  return kept;
+}
+
+/**
+ * Is this index entry drawn from a source the SELECTED EDITION declared?
+ *
+ * This is the one question that keeps one customer's private biome out of
+ * another customer's release, and it is asked at THREE seams below because a
+ * foreign entry has three ways in: a sweep selector, an explicit name, and a
+ * transitive `requires` pull.
+ *
+ * ── ABSENT IS THE IDENTITY, AND THAT IS WHY THIS CHANGES NOTHING TODAY ──
+ *
+ * An entry carries `source` iff some edition's `sources[]` walk drew it in.
+ * All 117 entries in the committed index are drawn from the platform's own
+ * repositories and carry no `source`, so every one of them stays admissible to
+ * every edition and all nine committed locks resolve byte-identically. That
+ * is the whole point of keying on the STAMP rather than on a list of
+ * first-party repository names: a list would be a change-tax that an eighth
+ * first-party repository forces somebody to edit, and it would be silently
+ * wrong until they did.
+ *
+ * ── WHY THIS LANDS BEFORE THE WALK IT FENCES ──
+ *
+ * This predicate landed BEFORE the walk it fences, while `composeChain` still
+ * refused a non-empty `sources[]` and nothing could stamp an entry. That was
+ * deliberate: on the day the refusal was deleted, a `{ tier: "platform" }`
+ * sweep would otherwise have pulled every fetched entry into `oss` — measured,
+ * before this predicate existed, at 5 of 9 editions swept in a synthetic
+ * private biome, `oss` and `cloud` among them. A fence added afterwards is a
+ * fence added in response to a leak.
+ *
+ * THE WALK NOW EXISTS (`external-source-walk.mjs`), so entries CAN be stamped
+ * and this predicate has live subjects. An empty declared set still means no
+ * edition admits a stamped entry, which stays the correct fail-closed reading:
+ * an edition that declares no sources has no business receiving a biome drawn
+ * from one.
+ */
+/**
+ * Merge the entries an edition's source walk drew into the index THIS
+ * RESOLUTION will select from — and never into `biome-index.json`.
+ *
+ * The committed index is the PLATFORM's, shared by every edition. An external
+ * entry written there is visible to all of them, and `{ tier: "platform" }`
+ * matches on tier and audience and never on origin, so the merge has to be
+ * per-resolution or the scoping fence has nothing left to scope.
+ */
+export function mergeExternalSourceEntries(
+  index,
+  externalEntries,
+  platformServiceIndex,
+) {
+  if (externalEntries.length === 0) {return index;}
+
+  // RE-ASSERTED HERE, not merely trusted from the walk. `walkDeclaredSources`
+  // already checks this, and the two checks are separated by a caller — this is
+  // the merge, the one point at which an entry from anywhere joins the shared
+  // index, and an unstamped entry arriving here is admissible to EVERY edition.
+  // A duplicated assertion is the right trade when what it catches is a
+  // customer's private biome shipping inside `oss`.
+  const unstamped = externalEntries.filter((entry) => entry.source === undefined);
+  if (unstamped.length > 0) {
+    throw new Error(
+      `refusing to merge ${unstamped.length} UNSTAMPED external entr(ies) ` +
+        `(${unstamped.map((entry) => entry.id).join(', ')}) into the biome index: an entry ` +
+        'with no source stamp is platform-default and admissible to every edition.',
+    );
+  }
+
+  // Resolve each NEW entry's service-dependency owners against the MERGED
+  // ownership picture — a customer biome may legitimately require a platform
+  // service, and only the merged set knows who owns one.
+  //
+  // The committed entries are passed as THROWAWAY CLONES carrying an empty
+  // `serviceRequirements`, because `resolveServiceDependencyOwners` MUTATES IN
+  // PLACE: it assigns `serviceDependencies` and deletes `serviceRequirements`
+  // on every entry it walks. The committed index ships the RESOLVED projection
+  // and no requirements (measured: 117 of 117 carry `serviceDependencies`, 0
+  // carry `serviceRequirements`), so walking the originals would overwrite all
+  // 117 projections with `[]`. The clones absorb that write; the real external
+  // entries are passed by reference and are the only ones resolved for real.
+  const probe = [
+    ...index.map((entry) => ({ ...entry, serviceRequirements: [] })),
+    ...externalEntries,
+  ];
+  resolveServiceDependencyOwners(probe, platformServiceIndex);
+
+  const merged = [...index, ...externalEntries].sort(compareIndexEntries);
+
+  // A DECLARED database key must name a database nothing else already answers
+  // to. This is the bound on the entitlement `org-database-pool-api` hands out,
+  // and it is the one check that genuinely must see the MERGED set: a customer
+  // manifest declaring `llm-registry` would otherwise be handed another
+  // principal's schema. `buildBiomeIndex` asserts it for the first-party half;
+  // this is where the external half joins.
+  assertDeclaredDatabasesUnowned(merged);
+  return merged;
+}
+
+/**
+ * The pinned source record for a stamped entry, or a refusal.
+ *
+ * A stamped entry whose handle resolves to no record means the walk and the
+ * merge disagree about what was fetched. Emitting the entry without its source
+ * would produce a lock whose member cannot be traced to a revision, and
+ * emitting `source: undefined` would make it read as first-party — so this
+ * fails rather than choosing either.
+ */
+function requireSourceRecord(entry, sourceRecords) {
+  const record = sourceRecords.get(entry.source);
+  if (record === undefined) {
+    throw new Error(
+      `biome "${entry.id}" is stamped with source "${entry.source}", but no pinned source ` +
+        'record was produced for that name. A stamped entry with no record cannot be traced ' +
+        'to a revision, and emitting it unstamped would make it read as first-party.',
+    );
+  }
+  return record;
+}
+
+export function entrySourceAdmissible(entry, declaredSourceNames) {
+  if (entry.source === undefined) {return true;}
+  return declaredSourceNames.has(entry.source);
+}
+
+function applySelectors(index, include, declaredSourceNames = new Set(), webProducerRepos = undefined) {
+  const selected = new Map(); // key → entry
+  // Keys a selector explicitly marked `mandatory: true` — the DISTRIBUTION's
+  // force-on decision. A biome is mandatory iff ANY matching selector flags it
+  // (a universal, core-class biome is mandatory regardless — see the lock). `{ origin }` selectors
+  // cannot carry `mandatory` (provenance is not a force-on axis).
+  const mandatoryKeys = new Set();
+  // Keys a NAME or a tier/origin sweep admitted — an explicit opt-in to the
+  // biome AND to its declared requirements of any class. A key only a class
+  // selector admitted is not in here (see the widening guard in
+  // `selectBySelectors`).
+  const explicitKeys = new Set();
+  // key → { policy, form } — the selector-provided install policy. Most
+  // specific matching selector wins: a `{ biome }` policy beats a SWEEP policy
+  // (`{ tier }` or `{ installationClass }`); two conflicting policies at the
+  // SAME specificity fail fast, INCLUDING one tier sweep against one class
+  // sweep — those are two axes stamping one biome, and arbitrating between
+  // them would be a precedence rule nobody wrote down.
+  // (`{ origin }` selectors cannot carry `installPolicy` — schema-enforced.)
+  const policyByKey = new Map();
+  const recordPolicy = (key, entryId, policy, form) => {
+    const existing = policyByKey.get(key);
+    if (existing === undefined) {
+      policyByKey.set(key, { policy, form });
+      return;
+    }
+    if (existing.form === form) {
+      if (existing.policy !== policy) {
+        throw new Error(
+          `conflicting installPolicy for biome "${entryId}": two ${form}-form selectors ` +
+            `stamp "${existing.policy}" and "${policy}" — resolve the manifest ambiguity`,
+        );
+      }
+      return;
+    }
+    // biome-form (more specific) overrides tier-form.
+    if (form === 'biome') {
+      policyByKey.set(key, { policy, form });
+    }
+  };
+  for (const sel of include) {
+    let matches;
+    if ('tier' in sel) {
+      matches = index.filter(
+        (e) =>
+          e.tier === sel.tier &&
+          e.audience !== 'operator' &&
+          isDeliverable(e, webProducerRepos) &&
+          entrySourceAdmissible(e, declaredSourceNames),
+      );
+    } else if ('origin' in sel) {
+      matches = index.filter(
+        (e) =>
+          e.origin === sel.origin &&
+          e.audience !== 'operator' &&
+          isDeliverable(e, webProducerRepos) &&
+          entrySourceAdmissible(e, declaredSourceNames),
+      );
+    } else if ('installationClass' in sel) {
+      // The index is known to carry classes: `assertIndexDeclaresInstallationClasses`
+      // refused it before selection otherwise.
+      matches = index.filter(
+        (e) =>
+          e.installationClass === sel.installationClass &&
+          e.audience !== 'operator' &&
+          isDeliverable(e, webProducerRepos) &&
+          entrySourceAdmissible(e, declaredSourceNames),
+      );
+      if (matches.length === 0) {
+        throw new Error(
+          `include { installationClass: "${sel.installationClass}" } matches no biome in ` +
+            `the index. An edition that asks for a class nothing declares is asking for ` +
+            `something that cannot be built; name the biomes explicitly or drop the selector.`,
+        );
+      }
+    } else if ('biome' in sel) {
+      const idMatches = index.filter((e) => e.id === sel.biome);
+      if (idMatches.length === 0) {
+        throw new UnknownSelectionError(
+          `include { biome: "${sel.biome}" } matches no biome in the index`,
+        );
+      }
+      // A SWEEP silently skips an inadmissible entry; an explicit NAME must
+      // refuse. Same asymmetry the deliverability rule one branch down already
+      // draws, and for the same reason: a sweep states an intent about a tier
+      // and cannot know what it swept, while a name is a stated intent about
+      // one biome. Dropping a named biome would resolve an edition that is
+      // missing exactly the thing its author asked for, and the lock would read
+      // as deliberate.
+      const inadmissible = idMatches.filter(
+        (e) => !entrySourceAdmissible(e, declaredSourceNames),
+      );
+      if (inadmissible.length > 0 && inadmissible.length === idMatches.length) {
+        const names = [...new Set(inadmissible.map((e) => e.source))].sort();
+        throw new Error(
+          `include { biome: "${sel.biome}" } names a biome drawn from source(s) ` +
+            `${names.map((name) => `"${name}"`).join(', ')}, which this edition does not ` +
+            `declare in sources[]. A biome is reachable only from a source its own ` +
+            `edition named: another edition declaring that source does not make it ` +
+            `visible here. Declare the source on this edition, or drop the include.`,
+        );
+      }
+      // An explicit name is a stated intent, so an undeliverable one FAILS
+      // rather than being dropped the way a selector sweep is. This is the one
+      // place the operator-biome rule and this rule differ, and deliberately:
+      // naming an operator biome is how you force it in, while naming a web
+      // biome with no producer asks for something no build can make.
+      if (idMatches.every((e) => !isDeliverable(e, webProducerRepos))) {
+        throw new Error(
+          `include { biome: "${sel.biome}" } names a target:web biome authored in ` +
+            `"${idMatches[0].repo}". Only web biomes under ` +
+            `"${(webProducerRepos ?? [webBiomeProducerRepo()]).join(', ')}" are bundled into the host image, so nothing ` +
+            `can build this one and every org would receive it as a catalog entry that ` +
+            `fails at boot with unavailable_in_build. Move it there (a thin re-export ` +
+            `wrapper is enough — see biomes/platform/org-databases-web), or drop the ` +
+            `include.`,
+        );
+      }
+      matches = sel.version
+        ? idMatches.filter((e) => {
+            try {
+              return versionSatisfies(e.version, sel.version);
+            } catch (err) {
+              throw new Error(
+                `version check for biome "${sel.biome}" failed: ${err.message}`,
+              );
+            }
+          })
+        : idMatches;
+      if (sel.version && matches.length === 0) {
+        throw new Error(
+          `include { biome: "${sel.biome}", version: "${sel.version}" } matched ids but no index version satisfied the range ` +
+            `(available: ${idMatches.map((m) => m.version).join(', ')})`,
+        );
+      }
+    } else {
+      throw new Error(`unrecognized selector shape: ${JSON.stringify(sel)}`);
+    }
+    for (const e of matches) {
+      const key = entryKey(e);
+      selected.set(key, e);
+      if (!('installationClass' in sel)) {explicitKeys.add(key);}
+      if (sel.mandatory === true) {mandatoryKeys.add(key);}
+      if (sel.installPolicy !== undefined) {
+        recordPolicy(
+          key,
+          e.id,
+          sel.installPolicy,
+          'biome' in sel ? 'biome' : 'sweep',
+        );
+      }
+    }
+  }
+  return { selected, mandatoryKeys, policyByKey, explicitKeys };
+}
+
+/**
+ * POSITIVE-CLOSURE SELECTION — an edition that declared `resolution:
+ * "positive-closure"` is its roots plus what they REQUIRE, computed by the
+ * kernel's one closure algorithm (`resolveBiomeClosure`). This function only
+ * projects the plane's facts onto it and the answer back:
+ *
+ *   * biome roots are validated as the `{ biome }` selector always validated a
+ *     name — it exists, its source is admissible, it is deliverable, a pinned
+ *     version is satisfied — and carry the same `mandatory` / `installPolicy`
+ *     distribution decisions;
+ *   * every universal (core-class) biome is a PLATFORM_INVARIANT root, the
+ *     same rule the selector model applies; the kernel's own
+ *     `platformInvariantRoots` (kernel-tier biomes and platform services) is
+ *     a subset of it for biomes, since a kernel-tier biome that is not
+ *     core-class is refused before selection;
+ *   * a policy root is a PLATFORM_INVARIANT root carrying its written reason;
+ *   * the candidates are every deliverable, source-admissible index entry and
+ *     every platform service the platform-service index knows.
+ *
+ * There is no exclude and no substrate list: a platform service ships iff it is
+ * a root, a kernel invariant, or something in the edition requires it.
+ *
+ * AND THE MANIFEST'S OWN DECLARATIONS MUST AGREE. A biome's `requires` and its
+ * `serviceDependencies` are what the deploy plane and the runtime still read
+ * from the lock. Under positive closure they are no longer an INCLUSION driver
+ * — the contract is — but a closure that ships a biome whose declared hard
+ * requirement it left out would resolve a lock that cannot boot. So each is
+ * checked against the closure and a disagreement is REFUSED, naming the edge:
+ * either the contract is missing a required edge, or the declaration is stale.
+ */
+function selectByPositiveClosure({
+  id,
+  index,
+  schemas,
+  roots,
+  declaredSourceNames,
+  platformSourcesByName,
+}) {
+  const {
+    ClosureEntityKind,
+    ClosureProvenanceKind,
+    BiomeClosureError,
+    DistributionResolutionMode,
+  } = schemas;
+  const biomeRoots = [];
+  const platformServiceRoots = [];
+  const operationRoots = [];
+  for (const [cls, kind] of [
+    ['product', ClosureProvenanceKind.ProductRoot],
+    ['ownerSelected', ClosureProvenanceKind.OwnerSelectedRoot],
+    ['policy', ClosureProvenanceKind.PlatformInvariant],
+  ]) {
+    for (const root of roots[cls] ?? []) {
+      if ('operationId' in root) {
+        // One operation of a service, stated with a reason. The kernel closure
+        // resolves the owning biome and REFUSES an operationId the producer's
+        // contract does not expose.
+        operationRoots.push({
+          provenance: {
+            kind: ClosureProvenanceKind.OperationRoot,
+            reason: root.reason,
+            operation: { serviceName: root.service, operationId: root.operationId },
+          },
+        });
+        continue;
+      }
+      const provenance =
+        kind === ClosureProvenanceKind.PlatformInvariant
+          ? { kind, reason: root.reason }
+          : { kind };
+      if ('platformService' in root) {
+        if (!platformSourcesByName.has(root.platformService)) {
+          throw new Error(
+            `distribution "${id}": ${cls} root names platform service ` +
+              `"${root.platformService}", which platform-service-index.json does not describe`,
+          );
+        }
+        platformServiceRoots.push({
+          entity: {
+            kind: ClosureEntityKind.PlatformService,
+            id: root.platformService,
+          },
+          provenance,
+        });
+      } else {
+        biomeRoots.push({ root, provenance });
+      }
+    }
+  }
+
+  // Biome roots are named selections; reuse the selector's validation of a
+  // name, and its `mandatory` / `installPolicy` bookkeeping, verbatim.
+  const { selected: rootSelection, mandatoryKeys, policyByKey } = applySelectors(
+    index,
+    biomeRoots.map(({ root }) => {
+      const { reason: _reason, ...selector } = root;
+      return selector;
+    }),
+    declaredSourceNames,
+  );
+  const rootIds = new Set([...rootSelection.values()].map((entry) => entry.id));
+
+  const candidateEntries = index.filter(
+    (entry) =>
+      isDeliverable(entry) && entrySourceAdmissible(entry, declaredSourceNames),
+  );
+  for (const entry of rootSelection.values()) {
+    if (!candidateEntries.includes(entry)) {candidateEntries.push(entry);}
+  }
+  const candidates = {
+    biomes: candidateEntries.map(closureBiomeFacts),
+    platformServices: [...platformSourcesByName.values()].map(
+      ({ name, tier, installationClass }) => ({
+        name,
+        tier,
+        ...(installationClass === undefined ? {} : { installationClass }),
+      }),
+    ),
+  };
+
+  // The universal (core-class) biomes are roots of every edition, exactly as
+  // in the selector model: explicit roots + universal + closure.
+  const universalRoots = candidateEntries
+    .filter((entry) => isUniversal(entry) && !rootIds.has(entry.id))
+    .sort(compareIndexEntries)
+    .map((entry) => ({
+      entity: { kind: ClosureEntityKind.Biome, id: entry.id },
+      provenance: {
+        kind: ClosureProvenanceKind.PlatformInvariant,
+        reason: `installationClass "${universalInstallationClass()}": universal, in every edition`,
+      },
+    }));
+
+  let result;
+  try {
+    result = schemas.resolveBiomeClosure({
+      roots: [
+        ...schemas.platformInvariantRoots(candidates),
+        ...universalRoots,
+        ...biomeRoots
+          .filter(({ root }) => rootIds.has(root.biome))
+          .map(({ root, provenance }) => ({
+            entity: { kind: ClosureEntityKind.Biome, id: root.biome },
+            provenance,
+          })),
+        ...platformServiceRoots,
+        ...operationRoots,
+      ],
+      candidates,
+    });
+  } catch (error) {
+    if (error instanceof BiomeClosureError) {
+      throw new Error(`distribution "${id}": ${error.message}`, {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+
+  const entriesById = new Map(candidateEntries.map((entry) => [entry.id, entry]));
+  const selected = new Map();
+  const shippedPlatformServices = new Map();
+  for (const { entity } of result.entries) {
+    if (entity.kind === ClosureEntityKind.Biome) {
+      const entry = entriesById.get(entity.id);
+      selected.set(entryKey(entry), entry);
+    } else {
+      const source = platformSourcesByName.get(entity.id);
+      shippedPlatformServices.set(entity.id, {
+        name: entity.id,
+        tier: source.tier,
+      });
+    }
+  }
+
+  // The manifest's declarations must agree with the closure — see above.
+  const shippedIds = new Set([...selected.values()].map((entry) => entry.id));
+  for (const entry of [...selected.values()].sort(compareIndexEntries)) {
+    for (const required of entry.requires ?? []) {
+      if (!shippedIds.has(required)) {
+        throw new Error(
+          `distribution "${id}": biome "${entry.id}" declares that it requires biome ` +
+            `"${required}", which positive closure did not include — its dependency ` +
+            'contract carries no required edge to it. Either the contract is missing ' +
+            'the edge, or the declaration is stale and belongs deleted from the manifest.',
+        );
+      }
+    }
+    for (const edge of entry.serviceDependencies ?? []) {
+      const satisfied =
+        edge.owner.kind === 'platform'
+          ? shippedPlatformServices.has(edge.requiredService)
+          : shippedIds.has(edge.owner.biomeId);
+      if (!satisfied) {
+        throw new Error(
+          `distribution "${id}": biome "${entry.id}" API "${edge.consumerService}" declares ` +
+            `that it requires service "${edge.requiredService}" (owned by ` +
+            `${edge.owner.kind === 'platform' ? 'platform service' : `biome "${edge.owner.biomeId}"`}), ` +
+            'which positive closure did not include — its dependency contract carries no ' +
+            'required edge to it. Either the contract is missing the edge, or the ' +
+            'declaration is stale.',
+        );
+      }
+    }
+  }
+
+  return {
+    selected,
+    mandatoryKeys,
+    policyByKey,
+    shippedPlatformServices,
+    resolutionSection: {
+      mode: DistributionResolutionMode.PositiveClosure,
+      entries: result.entries,
+    },
+  };
+}
+
+/**
+ * Bind every selected biome's declared resource requirements to providers.
+ *
+ * For each requirement the providers are the SHIPPED components declaring
+ * `providesResources` for its kind, across the edition's resolved set:
+ *
+ *   - exactly one  → a binding row naming it;
+ *   - none, `required` → REFUSE: the consumer cannot function in this edition;
+ *   - none, `optional` → NO row. Optional never pulls a provider in; the
+ *     consumer handles the absence, and nothing is admitted;
+ *   - more than one → REFUSE: no provider-selection policy exists yet, and
+ *     picking one would be a guess made on the consumer's behalf.
+ *
+ * The selector-model closure has already pulled in the sole provider of every
+ * `required` requirement (required-resource-provider.mjs), so a provider is
+ * always among `selectedEntries` here and the `none, required` branch below is
+ * a backstop the closure makes unreachable.
+ *
+ * Returns a function from an index entry to the spread the lock's biome
+ * literal takes: `{ serviceResources }` when that biome has a binding, `{}`
+ * otherwise.
+ */
+export function serviceResourceBinder(distributionId, selectedEntries, schemas) {
+  const providersByKind = new Map();
+  for (const entry of selectedEntries) {
+    for (const provision of entry.providesResources ?? []) {
+      if (!(Array.isArray(entry.services) && entry.services.includes(provision.service))) {
+        throw new Error(
+          `distribution "${distributionId}": biome "${entry.id}" declares that ` +
+            `"${provision.service}" provides ${provision.kind}, but it does not ` +
+            `ship that service`,
+        );
+      }
+      const providers = providersByKind.get(provision.kind) ?? [];
+      providers.push({ biomeId: entry.id, serviceName: provision.service });
+      providersByKind.set(provision.kind, providers);
+    }
+  }
+  return (entry) => {
+    const rows = [];
+    for (const requirement of entry.serviceResources ?? []) {
+      const providers = providersByKind.get(requirement.kind) ?? [];
+      const subject =
+        `biome "${entry.id}" service "${requirement.consumerService}" requires ` +
+        `${requirement.kind} "${requirement.logicalName}" (${requirement.scope}-scoped, ` +
+        `${requirement.inclusion})`;
+      if (providers.length > 1) {
+        throw new Error(
+          `distribution "${distributionId}": ${subject}, and ${providers.length} ` +
+            `shipped services provide that kind: ` +
+            `${providers.map((p) => `${p.biomeId}/${p.serviceName}`).join(', ')}. ` +
+            `No provider-selection policy exists yet, so the resolver refuses ` +
+            `rather than choosing one; ship exactly one provider of the kind.`,
+        );
+      }
+      if (providers.length === 0) {
+        if (requirement.inclusion === 'required') {
+          throw new Error(
+            `distribution "${distributionId}": ${subject}, and no shipped service ` +
+              `provides ${requirement.kind}. Select the biome that provides it, ` +
+              `or exclude the consumer.`,
+          );
+        }
+        // Optional and absent: no binding, nothing admitted. The consumer
+        // handles the provider's absence.
+        continue;
+      }
+      rows.push({
+        consumerService: requirement.consumerService,
+        kind: requirement.kind,
+        logicalName: requirement.logicalName,
+        scope: requirement.scope,
+        inclusion: requirement.inclusion,
+        provider: providers[0],
+      });
+    }
+    if (rows.length === 0) {return {};}
+    return {
+      serviceResources: rows.sort(schemas.compareLockedServiceResources),
+    };
+  };
+}
+
+/**
+ * Bind every Nexus service a shipped worker REQUIRES to the ONE shipped
+ * component that PROVIDES it, and return the lock's `nexusBindings` rows.
+ *
+ * The RULE is the kernel's `resolveNexusBindings` — same service, same major
+ * version, EVERY required operation; absent, ambiguous and missing-operation
+ * refusals; optional-and-absent binds nothing — and the runtime resolver
+ * (`@xemahq/distribution-resolver`) calls the same function, so the two can
+ * never bind one edition two ways. Nothing of the algorithm is restated here.
+ *
+ * What stays here is what only this repository knows: the index projection
+ * (`nexusProvides` / `nexusRequires`, see `componentNexusDeclarations`) and
+ * the check that a provider row names a component its biome SHIPS as a
+ * scheduled image — a binding to anything else would register an endpoint to
+ * a worker that is not deployed.
+ *
+ * Every refusal the kernel returns is reported at once, one line each. Like
+ * `serviceResourceBinder`, this never INCLUDES a provider the edition did not
+ * already select: the kernel only ever sees the selected entries. Returns `[]`
+ * when no shipped worker requires anything, so the producer omits the field
+ * and every such lock stays byte-identical.
+ */
+export function nexusBinder(distributionId, selectedEntries, schemas) {
+  for (const entry of selectedEntries) {
+    for (const provision of entry.nexusProvides ?? []) {
+      if (!(Array.isArray(entry.services) && entry.services.includes(provision.component))) {
+        throw new Error(
+          `distribution "${distributionId}": biome "${entry.id}" declares that ` +
+            `component "${provision.component}" provides nexus service ` +
+            `${provision.service}@${provision.version}, but it does not ship that ` +
+            `component as a scheduled image`,
+        );
+      }
+    }
+  }
+  const result = schemas.resolveNexusBindings(
+    selectedEntries.map((entry) => ({
+      biomeId: entry.id,
+      provides: entry.nexusProvides ?? [],
+      requires: entry.nexusRequires ?? [],
+    })),
+  );
+  if (!result.ok) {
+    throw new Error(
+      `distribution "${distributionId}": ${result.refusals.length} Nexus ` +
+        `requirement(s) cannot be bound:\n` +
+        result.refusals
+          .map((refusal) => `  - ${schemas.describeNexusBindingRefusal(refusal)}`)
+          .join('\n'),
+    );
+  }
+  return result.bindings;
+}
+
+export function resolveDistributionFromInputs(
+  id,
+  index,
+  schemas,
+  composed,
+  resolvedAt = new Date().toISOString(),
+  platformServiceIndex = { schemaVersion: 1, services: [] },
+) {
+  const {
+    parseDistribution,
+    BiomeInstallPolicy,
+    BiomeLaunchMode,
+    DistributionVisibility,
+    DistributionResolutionMode,
+  } = schemas;
+  const {
+    include,
+    exclude,
+    trustPolicy,
+    trustCeiling,
+    declaredVisibilities,
+    owner,
+    leaf,
+    // Absent on a selector-model composition — including every `composed` a
+    // caller built before positive closure existed.
+    resolution: composedResolution,
+    roots: composedRoots,
+  } = composed ?? composeEdition(parseDistribution, id);
+  // A `composed` handed in by a caller (the contract suite drives the resolver
+  // this way) may predate this field; an absent set is the empty set, which is
+  // the fail-closed reading.
+  const declaredSourceNames = composed?.declaredSourceNames ?? new Set();
+  // What is universal is read from the index's installation classes, in BOTH
+  // resolution models — so an index that cannot answer is refused first.
+  assertIndexDeclaresInstallationClasses(id, index);
+  // name → pinned `LockedBiomeSource`, produced by the walk. Absent for every
+  // edition that declares no sources, which is all nine committed ones.
+  const sourceRecords = composed?.sourceRecords ?? new Map();
+
+  // Every selector/dependency/exclude uses a biome id. Until the canonical
+  // schema grows a compound reference, two index entries with the same id are
+  // ambiguous even when target/repo differ. Refuse the index rather than
+  // silently selecting one or treating one selected identity as satisfying
+  // another.
+  const entriesById = new Map();
+  for (const entry of index) {
+    const entries = entriesById.get(entry.id) ?? [];
+    entries.push(entry);
+    entriesById.set(entry.id, entries);
+  }
+  for (const [biomeId, entries] of entriesById) {
+    if (entries.length > 1) {
+      throw new Error(
+        `distribution "${id}": biome id "${biomeId}" resolves to multiple compound identities: ` +
+          entries
+            .map((entry) => `${entry.target}@${entry.repo}/${entry.path}`)
+            .sort()
+            .join(', ') +
+          '. The id-only distribution schema cannot choose safely.',
+      );
+    }
+  }
+  const platformSourcesByName = new Map();
+  for (const source of platformServiceIndex.services) {
+    if (platformSourcesByName.has(source.name)) {
+      throw new Error(
+        `distribution "${id}": platform service "${source.name}" has ambiguous source identities in platform-service-index.json`,
+      );
+    }
+    platformSourcesByName.set(source.name, source);
+  }
+  // The substrate CANDIDATES: every service in the index, with the facts the
+  // selection reads. Selection (class narrowing, edge pulls, `exclude`) runs over
+  // this; the edition contributes none.
+  const platformServices = new Map(
+    [...platformSourcesByName.values()].map(({ name, tier, installationClass }) => [
+      name,
+      { name, tier, installationClass },
+    ]),
+  );
+  // SELECTION — the one step the two resolution models do differently. Each
+  // returns the same four things; everything after (trust policy, resource
+  // bindings, the lock literal) is shared, so a positive-closure lock and a
+  // selector-model lock are built by the same code from the same kind of set.
+  const {
+    selected,
+    mandatoryKeys,
+    policyByKey,
+    shippedPlatformServices,
+    resolutionSection,
+  } =
+    composedResolution === DistributionResolutionMode.PositiveClosure
+      ? selectByPositiveClosure({
+          id,
+          index,
+          schemas,
+          roots: composedRoots,
+          declaredSourceNames,
+          platformSourcesByName,
+        })
+      : selectBySelectors();
+
+  /** The legacy selector model: include selectors, exclude, `requires` closure. */
+  function selectBySelectors() {
+    // `exclude` names what this distribution REMOVES after composition. TWO
+    // namespaces are removable, and they share the one list rather than each
+    // getting a field of its own:
+    //
+    //   - a biome id, resolved against the biome index;
+    //   - a composed platform-service name, resolved against `platformServices`.
+    //
+    // Sharing the list is not a shortcut, it is the only mechanism available
+    // here: `DistributionSchema` is a plain zod object, so it STRIPS unknown keys
+    // silently — a second manifest field (`excludePlatformServices`) would be
+    // dropped by `parseDistribution` before this resolver ever saw it, and the
+    // edition would ship the service it declared it did not want, with no error
+    // anywhere. Adding the field for real means changing the published kernel
+    // contract. `exclude` is already parsed and already means exactly "remove this".
+    //
+    // The two namespaces are disjoint today (no biome id equals a platform
+    // service name) and a name resolving in BOTH is refused rather than
+    // arbitrated, so the shared list can never silently pick one. A name in
+    // NEITHER fails closed, exactly as it did when only biomes were removable.
+    //
+    // Why a platform service must be excludable at all: billing. A fresh
+    // instance — a personal user, an SME, a corporate — may have no billing
+    // plane. `llm-gateway-api` answers 501 BILLING_NOT_CONFIGURED for a metered
+    // request when none is wired, and `llm-registry-api` asks the service
+    // registry whether this deployment declared one. Neither can help while the
+    // packaging plane ships `billing-api` into every edition with no opt-out.
+    const excludedBiomes = new Set();
+    const excludedPlatformServices = new Set();
+    for (const excludedId of exclude) {
+      const isBiome = entriesById.has(excludedId);
+      const platformService = platformServices.get(excludedId);
+      if (isBiome && platformService) {
+        throw new Error(
+          `distribution "${id}" excludes "${excludedId}", which is BOTH a biome id and a ` +
+            `platform service name — the shared exclude namespace cannot choose safely`,
+        );
+      }
+      if (platformService) {
+        // Mirrors the universal-biome rule below: a core-class service is in
+        // every installation, so it can never be opted out of.
+        if (isUniversal(platformService)) {
+          throw new Error(
+            `distribution "${id}" tries to exclude universal (installationClass core) platform ` +
+              `service "${excludedId}" — a universal service is in every edition and cannot be excluded`,
+          );
+        }
+        excludedPlatformServices.add(excludedId);
+        continue;
+      }
+      if (!isBiome) {
+        throw new Error(
+          `distribution "${id}" excludes unknown biome or platform service "${excludedId}"`,
+        );
+      }
+      excludedBiomes.add(excludedId);
+    }
+
+    // The platform substrate this edition actually ships. Derived BEFORE the
+    // dependency closure below, so `requirePlatformOwner` sees the post-exclusion
+    // set: a biome whose API declares a service edge onto an excluded platform
+    // service then fails closed, citing the exact edge, instead of resolving into
+    // a lock that promises a service the edition does not carry. That is what
+    // makes a billing-free edition COHERENT rather than merely smaller.
+    //
+    // A copy, never a mutation of `platformServices`: callers may pass a
+    // pre-built `composed` and reuse it across resolves.
+    //
+    // The class narrowing runs BEFORE the exclusions and AFTER the partition
+    // above, deliberately. `exclude` is resolved against the COMPOSED map, so a
+    // class-drawn edition can still name a service the narrowing already removed
+    // without the exclude failing closed as "unknown"; and narrowing before the
+    // deletion means the two mechanisms compose rather than fight — an edition
+    // may draw a class and still exclude one member of it.
+    const admittedClasses = admittedInstallationClasses(include);
+    const shippedPlatformServices = narrowPlatformServicesByClass(
+      new Map(platformServices),
+      admittedClasses,
+    );
+    for (const name of excludedPlatformServices) {
+      shippedPlatformServices.delete(name);
+    }
+
+    // (1) Apply include selectors (also collecting the distribution's per-biome
+    //     `mandatory` force-on decision + selector-provided install policies).
+    const { selected, mandatoryKeys, policyByKey, explicitKeys } = applySelectors(
+      index,
+      include,
+      declaredSourceNames,
+      composed?.webProducerRepos,
+    );
+
+    // (2) Force-include every UNIVERSAL (core-class) biome; a universal biome
+    //     can NEVER be excluded. Added after exclude resolution below to
+    //     enforce that. A biome drawn from an undeclared source is never
+    //     universal here — it is not admissible to this edition at all.
+    const universalEntries = index.filter(
+      (e) => isUniversal(e) && entrySourceAdmissible(e, declaredSourceNames),
+    );
+
+    // (3) Apply exclude — but a universal biome cannot be excluded.
+    for (const ex of excludedBiomes) {
+      if (universalEntries.some((e) => e.id === ex)) {
+        throw new Error(
+          `distribution "${id}" tries to exclude universal (installationClass core) biome "${ex}" — ` +
+            `a universal biome is in every edition and cannot be excluded`,
+        );
+      }
+      for (const key of [...selected.keys()]) {
+        if (selected.get(key).id === ex) {selected.delete(key);}
+      }
+    }
+
+    // Force-include the universal set after exclude so exclude can never drop it.
+    for (const e of universalEntries) {selected.set(entryKey(e), e);}
+
+    // (4) Dependency closure — selector entries are feature/profile roots, while
+    //     xema-biome dependency metadata is the ONLY composition graph. Resolve
+    //     that graph transitively into the lock; never make a distribution author
+    //     repeat the dependency roster by hand. An excluded or unknown dependency
+    //     fails closed and cites the exact edge.
+    const includedIds = new Set([...selected.values()].map((e) => e.id));
+    const queue = [...selected.values()].sort(compareIndexEntries);
+    const resourceProviderCandidates = index.filter(
+      (e) => isDeliverable(e, composed?.webProducerRepos) && entrySourceAdmissible(e, declaredSourceNames),
+    );
+    const requireBiomeOwner = (consumer, edge) => {
+      const owner = edge.owner;
+      if (owner.target !== 'server') {
+        throw new Error(
+          `distribution "${id}": biome "${consumer.id}" API "${edge.consumerService}" requires service ` +
+            `"${edge.requiredService}" from cross-target ${owner.target} biome "${owner.biomeId}"`,
+        );
+      }
+      const candidates = entriesById.get(owner.biomeId) ?? [];
+      const matches = candidates.filter(
+        (candidate) =>
+          candidate.target === owner.target &&
+          candidate.repo === owner.repo &&
+          candidate.path === owner.path &&
+          candidate.version === owner.version &&
+          candidate.sourceManifestHash === owner.sourceManifestHash &&
+          candidate.services.includes(edge.requiredService),
+      );
+      if (matches.length !== 1) {
+        throw new Error(
+          `distribution "${id}": biome "${consumer.id}" API "${edge.consumerService}" requires service ` +
+            `"${edge.requiredService}", but its exact biome owner ${owner.biomeId} ` +
+            `(${owner.target}@${owner.repo}/${owner.path}, ${owner.version}, ${owner.sourceManifestHash}) ` +
+            `resolved ${matches.length} times`,
+        );
+      }
+      return matches[0];
+    };
+    // Every closure edge, recorded for the widening check after the closure:
+    // consumer key → [{ target key | platform service, how it was declared }].
+    const biomeEdges = new Map();
+    const platformEdges = new Map();
+    const recordEdge = (edges, consumer, target) => {
+      const key = entryKey(consumer);
+      const list = edges.get(key) ?? [];
+      list.push(target);
+      edges.set(key, list);
+    };
+    const requirePlatformOwner = (consumer, edge) => {
+      const source = edge.owner.source;
+      if (source.name !== edge.requiredService) {
+        throw new Error(
+          `distribution "${id}": biome "${consumer.id}" API "${edge.consumerService}" service edge ` +
+            `"${edge.requiredService}" carries mismatched platform owner "${source.name}"`,
+        );
+      }
+      const canonical = platformSourcesByName.get(edge.requiredService);
+      if (!canonical) {
+        throw new UnknownSelectionError(
+          `distribution "${id}": biome "${consumer.id}" API "${edge.consumerService}" requires platform service ` +
+            `"${edge.requiredService}", which the platform-service index does not hold`,
+        );
+      }
+      if (serializeJson(canonical) !== serializeJson(source)) {
+        throw new Error(
+          `distribution "${id}": biome "${consumer.id}" API "${edge.consumerService}" requires platform service ` +
+            `"${edge.requiredService}", but its exact committed source identity is absent or mismatched`,
+        );
+      }
+      // A required service the class narrowing left out is PULLED by the
+      // edge, exactly as a required biome is — unless the edition excluded it,
+      // which fails closed citing the edge.
+      if (
+        !shippedPlatformServices.has(edge.requiredService) &&
+        !excludedPlatformServices.has(edge.requiredService)
+      ) {
+        shippedPlatformServices.set(
+          edge.requiredService,
+          platformServices.get(edge.requiredService),
+        );
+      }
+      const declared = shippedPlatformServices.get(edge.requiredService);
+      if (!declared) {
+        throw new Error(
+          `distribution "${id}": biome "${consumer.id}" API "${edge.consumerService}" requires platform service ` +
+            `"${edge.requiredService}", but the distribution explicitly excludes it`,
+        );
+      }
+      recordEdge(platformEdges, consumer, {
+        service: declared,
+        via: `API "${edge.consumerService}" requires platform service "${edge.requiredService}"`,
+      });
+    };
+    // A web biome is the admin UI of the server biomes it `requires`: it ships
+    // with them unless the edition excludes it by name. The closure edge runs
+    // server -> web, so an edition that draws a server biome cannot silently
+    // lose its UI. A web joins once EVERY server it requires is in the edition
+    // (the last of them to be processed completes it), so a UI is never pulled
+    // in ahead of the capability it administers.
+    const webBiomesByRequiredServer = new Map();
+    for (const candidate of resourceProviderCandidates) {
+      if (
+        candidate.target !== 'web' ||
+        candidate.audience === 'operator' ||
+        excludedBiomes.has(candidate.id)
+      ) {
+        continue;
+      }
+      for (const req of candidate.requires) {
+        const webs = webBiomesByRequiredServer.get(req) ?? [];
+        webs.push(candidate);
+        webBiomesByRequiredServer.set(req, webs);
+      }
+    }
+    const pullWebBiomesOf = (server) => {
+      for (const web of webBiomesByRequiredServer.get(server.id) ?? []) {
+        if (includedIds.has(web.id)) {continue;}
+        if (!web.requires.every((req) => includedIds.has(req))) {continue;}
+        recordEdge(biomeEdges, server, {
+          id: web.id,
+          via: `is administered by web biome "${web.id}"`,
+        });
+        includedIds.add(web.id);
+        const key = entryKey(web);
+        explicitKeys.add(key);
+        selected.set(key, web);
+        queue.push(web);
+      }
+    };
+    for (let cursor = 0; cursor < queue.length; cursor += 1) {
+      const entry = queue[cursor];
+      pullWebBiomesOf(entry);
+      for (const req of [...entry.requires].sort()) {
+        if (excludedBiomes.has(req)) {
+          throw new Error(
+            `distribution "${id}": biome "${entry.id}" (${entry.repo}) requires "${req}", ` +
+              `but the distribution explicitly excludes it`,
+          );
+        }
+        const viaRequires = { id: req, via: `requires biome "${req}"` };
+        if (includedIds.has(req)) {
+          recordEdge(biomeEdges, entry, viaRequires);
+          continue;
+        }
+        const dependencies = entriesById.get(req);
+        if (!dependencies || dependencies.length === 0) {
+          throw new UnknownSelectionError(
+            `distribution "${id}": biome "${entry.id}" (${entry.repo}) requires unknown biome "${req}"`,
+          );
+        }
+        if (
+          dependencies.some((dependency) => dependency.audience === 'operator')
+        ) {
+          throw new Error(
+            `distribution "${id}": biome "${entry.id}" (${entry.repo}) requires operator biome "${req}", ` +
+              `which must be selected explicitly by id`,
+          );
+        }
+        // THE THIRD DOOR, and the one a selector fence alone leaves open: an
+        // admissible biome that `requires` a foreign one would drag it in
+        // transitively, with no selector anywhere naming it. Refuse rather than
+        // pull — a public biome that hard-requires a customer's private biome is
+        // a structural defect in the dependency graph, and satisfying it here
+        // would put that customer's biome into every edition the public one
+        // reaches. Refuse rather than DROP, for the same reason the excluded-
+        // dependency branch above refuses: a biome whose requirement is missing
+        // does not boot, so a quietly smaller closure is a broken installation
+        // that resolved cleanly.
+        const foreignDeps = dependencies.filter(
+          (dependency) => !entrySourceAdmissible(dependency, declaredSourceNames),
+        );
+        if (foreignDeps.length > 0 && foreignDeps.length === dependencies.length) {
+          const names = [...new Set(foreignDeps.map((d) => d.source))].sort();
+          throw new Error(
+            `distribution "${id}": biome "${entry.id}" (${entry.repo}) requires "${req}", ` +
+              `which is drawn from source(s) ${names.map((name) => `"${name}"`).join(', ')} ` +
+              `that this edition does not declare in sources[]. Refusing rather than ` +
+              `pulling a foreign biome in through a dependency edge no selector named.`,
+          );
+        }
+        includedIds.add(req);
+        recordEdge(biomeEdges, entry, viaRequires);
+        for (const dependency of dependencies.sort(compareIndexEntries)) {
+          const key = entryKey(dependency);
+          if (!selected.has(key)) {
+            selected.set(key, dependency);
+            queue.push(dependency);
+          }
+        }
+      }
+      for (const edge of entry.serviceDependencies ?? []) {
+        if (!entry.services.includes(edge.consumerService)) {
+          throw new Error(
+            `distribution "${id}": biome "${entry.id}" service dependency names unknown consumer API ` +
+              `"${edge.consumerService}"`,
+          );
+        }
+        if (edge.owner.kind === 'platform') {
+          requirePlatformOwner(entry, edge);
+          continue;
+        }
+        const dependency = requireBiomeOwner(entry, edge);
+        if (excludedBiomes.has(dependency.id)) {
+          throw new Error(
+            `distribution "${id}": biome "${entry.id}" API "${edge.consumerService}" requires service ` +
+              `"${edge.requiredService}" owned by explicitly excluded biome "${dependency.id}"`,
+          );
+        }
+        if (
+          dependency.audience === 'operator' &&
+          !includedIds.has(dependency.id)
+        ) {
+          throw new Error(
+            `distribution "${id}": biome "${entry.id}" API "${edge.consumerService}" requires service ` +
+              `"${edge.requiredService}" owned by operator biome "${dependency.id}", which must be selected explicitly`,
+          );
+        }
+        recordEdge(biomeEdges, entry, {
+          id: dependency.id,
+          via: `API "${edge.consumerService}" requires service "${edge.requiredService}" owned by biome "${dependency.id}"`,
+        });
+        if (!includedIds.has(dependency.id)) {
+          includedIds.add(dependency.id);
+          const key = entryKey(dependency);
+          selected.set(key, dependency);
+          queue.push(dependency);
+        }
+      }
+      // A required resource requirement is a closure edge to the sole
+      // provider of that kind (required-resource-provider.mjs). The provider
+      // is a necessity of the consumer, not a class widening, so it joins as
+      // an explicit root: its own requirements then follow freely.
+      for (const requirement of entry.serviceResources ?? []) {
+        if (requirement.inclusion !== 'required') {continue;}
+        const provider = soleResourceProvider({
+          distributionId: id,
+          consumer: entry,
+          requirement,
+          candidates: resourceProviderCandidates,
+        });
+        if (provider.id === entry.id) {continue;}
+        if (excludedBiomes.has(provider.id)) {
+          throw new Error(
+            `distribution "${id}": biome "${entry.id}" service "${requirement.consumerService}" requires ` +
+              `${requirement.kind} "${requirement.logicalName}" provided by explicitly excluded biome "${provider.id}"`,
+          );
+        }
+        recordEdge(biomeEdges, entry, {
+          id: provider.id,
+          via: `service "${requirement.consumerService}" requires ${requirement.kind} "${requirement.logicalName}" provided by biome "${provider.id}"`,
+        });
+        includedIds.add(provider.id);
+        const key = entryKey(provider);
+        explicitKeys.add(key);
+        if (!selected.has(key)) {
+          selected.set(key, provider);
+          queue.push(provider);
+        }
+      }
+    }
+
+    // (4b) THE CLOSURE MAY NOT WIDEN WHAT ONLY A CLASS ASKED FOR.
+    //
+    // Two ways into an edition, and they carry different intent. A biome the
+    // edition NAMES, or sweeps by tier/origin, is an explicit opt-in to that
+    // biome AND to everything it declares it requires, of any class: naming
+    // `agent-runtime` brings the executor, the release plane and the LLM
+    // gateway it cannot run without, and no edition has to name the class.
+    // What only a CLASS admitted — the universal (core) floor included — is a
+    // statement about that class, so its closure must stay inside the
+    // admitted classes; otherwise the edition quietly grows (a universal biome
+    // with an edge into a family would put that family into every
+    // installation). Unclassified entries pass: absent is a third answer, and
+    // the only one a web or adapter entry can give.
+    //
+    // Computed AFTER the closure, from the recorded edges, so the verdict does
+    // not depend on the order the queue happened to visit things: an entry is
+    // FREE iff it is reachable from an explicitly admitted root.
+    const selectedByEntryId = new Map(
+      [...selected.values()].map((e) => [e.id, e]),
+    );
+    const free = new Set();
+    const walk = [...explicitKeys].filter((key) => selected.has(key));
+    for (const key of walk) {free.add(key);}
+    for (let cursor = 0; cursor < walk.length; cursor += 1) {
+      for (const target of biomeEdges.get(walk[cursor]) ?? []) {
+        const targetEntry = selectedByEntryId.get(target.id);
+        const targetKey = entryKey(targetEntry);
+        if (!free.has(targetKey)) {
+          free.add(targetKey);
+          walk.push(targetKey);
+        }
+      }
+    }
+    // A platform service a FREE consumer requires is in the edition by that
+    // consumer's right, whoever else also requires it.
+    const freePlatformServices = new Set();
+    for (const key of free) {
+      for (const target of platformEdges.get(key) ?? []) {
+        freePlatformServices.add(target.service.name);
+      }
+    }
+    const refuseWidening = (consumer, via, pulledClass) => {
+      throw new Error(
+        `distribution "${id}": biome "${consumer.id}" ${via}, which declares ` +
+          `installationClass "${pulledClass}" — "${consumer.id}" is in this edition only ` +
+          `through the class selector(s) [${[...admittedClasses].sort().join(', ')}], and what a ` +
+          `class admitted may not widen through the dependency closure. Name the biome that ` +
+          `needs it (a named biome pulls its requirements of any class), or — if the edge is ` +
+          `stale or one of the two classifications is wrong — fix the declaring manifest.`,
+      );
+    };
+    for (const consumer of [...selected.values()].sort(compareIndexEntries)) {
+      const consumerKey = entryKey(consumer);
+      if (free.has(consumerKey)) {continue;}
+      for (const target of biomeEdges.get(consumerKey) ?? []) {
+        const targetEntry = selectedByEntryId.get(target.id);
+        if (free.has(entryKey(targetEntry))) {continue;}
+        const pulledClass = targetEntry.installationClass;
+        if (pulledClass !== undefined && !admittedClasses.has(pulledClass)) {
+          refuseWidening(consumer, target.via, pulledClass);
+        }
+      }
+      for (const target of platformEdges.get(consumerKey) ?? []) {
+        if (freePlatformServices.has(target.service.name)) {continue;}
+        const pulledClass = target.service.installationClass;
+        if (pulledClass !== undefined && !admittedClasses.has(pulledClass)) {
+          refuseWidening(consumer, target.via, pulledClass);
+        }
+      }
+    }
+
+    return {
+      selected,
+      mandatoryKeys,
+      policyByKey,
+      shippedPlatformServices,
+      resolutionSection: undefined,
+    };
+  }
+
+  // (5) Trust policy — every included biome's origin must be allowed.
+  if (trustPolicy?.allow) {
+    const allow = new Set(trustPolicy.allow);
+    for (const e of selected.values()) {
+      if (!allow.has(e.origin)) {
+        throw new Error(
+          `distribution "${id}": biome "${e.id}" (${e.repo}) has origin "${e.origin}", not in trustPolicy.allow [${[...allow].join(', ')}]`,
+        );
+      }
+    }
+  }
+
+  // Launch placement is a DISTRIBUTION decision applied at resolve time — like
+  // `mandatory`, it is NEVER sourced from the biome manifest (WHERE/HOW a biome
+  // runs varies per installation: static service, per-installation sidecar,
+  // remote, on our infra or a client's — the biome only declares WHAT it is).
+  // `per-installation` means the biome is a sidecar-host template instantiated
+  // dynamically by biome-host-api once a biome is installed — it is NOT a
+  // statically-launched service, so the static roster (dev launcher + prod
+  // services.yaml) must not boot it standalone. Default (absent) = statically
+  // launched. This is the minimal, edition-overridable default; a future
+  // xema-distribution.json `launch` section can override it per edition.
+  const PER_INSTALLATION_LAUNCH = new Set(['biome-adapter-host']);
+
+  // (5b) Resource bindings — each shipped requirement bound to the ONE shipped
+  // provider of its kind. See `bindServiceResources`.
+  const bindServiceResourcesFor = serviceResourceBinder(
+    id,
+    [...selected.values()],
+    schemas,
+  );
+
+  // (5c) Nexus bindings — each required (service, version) bound to the ONE
+  // shipped provider. See `nexusBinder`.
+  const nexusBindings = nexusBinder(id, [...selected.values()], schemas);
+
+  // (6) Build the lock — sort by (tier order, id, target, repo).
+  const biomes = [...selected.values()]
+    .map((e) => ({
+      id: e.id,
+      version: e.version,
+      tier: e.tier,
+      target: e.target,
+      origin: e.origin,
+      // `mandatory`: a universal (core-class) biome is always mandatory — it is
+      // in every installation and cannot be opted out of; otherwise a matching
+      // include selector flagged it. The tier never decides it.
+      mandatory: isUniversal(e) || mandatoryKeys.has(entryKey(e)),
+      // Package-model install policy: a universal (core-class) biome is ALWAYS
+      // required; otherwise the most specific selector-provided policy wins
+      // (collected in applySelectors); else default-selected. The tier never
+      // decides it, and it is never sourced from the biome manifest.
+      installPolicy:
+        isUniversal(e)
+          ? BiomeInstallPolicy.Required
+          : (policyByKey.get(entryKey(e))?.policy ??
+            BiomeInstallPolicy.DefaultSelected),
+      repo: e.repo,
+      path: e.path,
+      services: Array.isArray(e.services) ? e.services : [],
+      // `service → shared-cluster database key`, forwarded verbatim from the
+      // index for the few services whose key is neither the biome id nor their
+      // own name minus `-api`. org-database-pool-api's ownership fence reads
+      // THIS — it is the only place the platform can learn that
+      // `scm-connector-api` opens schema `scm-integration`, and reading it from
+      // the resolved lock is what makes it a distribution-time fact rather than
+      // something a booting service asserts about itself.
+      //
+      // STATED UNCONDITIONALLY, including when empty. The index omits the key
+      // for the ~110 biomes that declare nothing (it keeps the index
+      // byte-stable), but the LOCK is a contract every consumer parses: schema
+      // v2 makes this field required precisely so a reader never has to decide
+      // whether an absent key means "no declaration" or "produced by a builder
+      // that predates the field".
+      serviceDatabases: e.serviceDatabases ?? {},
+      // `service → PostgreSQL extensions its database must carry`, forwarded
+      // verbatim from the index (`protocol.databaseExtensions`, validated and
+      // sorted at index build). The deployment's privileged database bootstrap
+      // reads THIS to create every extension a physical database's biomes need
+      // before any migration runs; the runtime only verifies.
+      //
+      // OMITTED when the entry carries none — the OPPOSITE of the rule one key
+      // up, and deliberately so. The kernel lock schema marks this field
+      // OPTIONAL so every sealed lock keeps parsing, and its reading of an
+      // absent map is "this lock predates the declaration". Two things decide
+      // omission over `{}`:
+      //   1. BYTE-STABILITY. `serializeJson` is insertion-order
+      //      `JSON.stringify`, and at `origin/main` no manifest declares an
+      //      extension, so `{}` here would move every biome of all nine
+      //      committed locks — and `inputHash` with them — for a fact none of
+      //      their entries carries. Asserted by `dist-check`: the committed
+      //      locks must equal a fresh resolve byte for byte.
+      //   2. THE BRIDGE. A deployment whose lock cannot yet say what its
+      //      databases need carries the requirement in its own inputs, and the
+      //      deploy plane refuses that bridge the moment ANY biome in the lock
+      //      carries this key. Emitting `{}` for a biome that declares nothing
+      //      would flip that refusal on a lock that still says nothing about
+      //      the one extension the deployment actually needs.
+      // So per biome, absent means "declares none" exactly as it does on the
+      // index entry, and a lock in which no biome declares one is byte-identical
+      // to one minted before the field existed — which is the correct reading,
+      // because it carries the same information.
+      //
+      // WITHHELD FROM THE LOCK UNTIL THE PINNED CONSUMERS CAN PARSE IT.
+      //
+      // The comment above is right that the KERNEL schema marks this optional
+      // "so every sealed lock keeps parsing" — and that is true of
+      // `@xemahq/contracts` 0.12.0, which learned the key. It is no help at all
+      // to a 0.9.2 parser, which is `.strict()` and does not know it exists:
+      // `Unrecognized key: "serviceDatabaseExtensions"`, thrown before Nest
+      // starts. Optional-in-the-new-schema and absent-from-the-old are different
+      // facts, and only the second one governs a deployed image.
+      //
+      // MEASURED 2026-09-17. Emitting it took presenca-dev's three
+      // distribution-lock consumers — biome-host-api, capability-registry-api,
+      // xema-capability-router — into CrashLoopBackOff on a sealed, signed,
+      // platform-verified edition. The seal was green; the lock was unparseable
+      // by the images the same lock pins.
+      //
+      // ── THE REASON THIS GIVES FOR THE BLOCK IS STALE. CORRECTED 2026-09-19 ──
+      //
+      // This comment used to continue: "xema-base `main` declares
+      // `'@xemahq/contracts': ^0.9.2`, and A CARET ON A 0.x LINE IS MINOR-LOCKED
+      // (`>=0.9.2 <0.10.0`), so no rebuild from `main` can ever resolve 0.12.0."
+      //
+      // The CONCLUSION still holds and the REASON does not, which is the worse
+      // half: a premise stating that something is STRUCTURALLY IMPOSSIBLE is the
+      // one a reader never re-derives, and this one stopped being true when
+      // somebody raised the pin. Re-measured against the refs, not the comment:
+      //   xema-base origin/main    `'@xemahq/contracts': ^0.15.0`
+      //   xema-base origin/develop `'@xemahq/contracts': ^0.16.0`
+      //   xema-base 2ef54a1 (the `sourceCommit` presenca-dev's images.lock.json
+      //     names) resolves `@xemahq/contracts@0.15.0`, sole resolution.
+      // and against the published tarballs, two-sided, `npm pack` + grep:
+      //   0.9.2 -> 0 files name this key; 0.12.0 / 0.15.0 / 0.17.0 -> 2 each.
+      // So 0.12.0 learned it, ^0.15.0 admits it, and the pin has ALREADY moved
+      // past the deletion condition this comment states below.
+      //
+      // WHAT ACTUALLY BLOCKS IT IS THE ROLLOUT, and a pin is not a rollout.
+      // Measured 2026-09-19 inside the running containers in `presenca-dev`:
+      //   `cat /app/node_modules/@xemahq/contracts/package.json` -> "0.9.2",
+      //   one resolution each (`ls -d /app/node_modules/.pnpm/@xemahq+contracts@*`),
+      //   and `dist/distribution/lib/distribution-lock.js` carries `.strict()`
+      //   on 11 schema objects while `grep -oE 'service[A-Za-z]+'` over it yields
+      //   only serviceDatabases / serviceDependencies / services.
+      //   POSITIVE CONTROL, same tree, same probe: `grep -rl distribution` -> 64.
+      //   So the zero is an absence, not a broken probe.
+      // And the three running digests are NOT the digests
+      // `deployments/presenca-dev/images.lock.json` designates — the cluster is
+      // roughly one build behind its own lock, which is why a pin raised on the
+      // branch has not reached the parser.
+      //
+      // The block therefore moved from STRUCTURALLY IMPOSSIBLE to ONE ROLLOUT
+      // AWAY, and nothing in the tree would have said so.
+      //
+      // This is still the fleet's producer->consumer ordering law, and
+      // withholding is still the law rather than a retreat: publish the
+      // producer, ADOPT IT IN THE CONSUMERS, then emit the new shape. Step one
+      // is done, step two is now a deploy rather than a version bump, step
+      // three is the flip below.
+      //
+      // DELETION CONDITION — as a PROBE you can run, not a claim to believe.
+      // A version range in a manifest is a declaration; only the container
+      // answers this. For each of biome-host-api, capability-registry-api and
+      // xema-capability-router:
+      //
+      //   kubectl -n presenca-dev exec deploy/<svc> -- \
+      //     cat /app/node_modules/@xemahq/contracts/package.json
+      //
+      // must report >= 0.12.0 for ALL THREE. When it does, in ONE change:
+      //   1. flip this to the commented-out spread below;
+      //   2. retire case (d) of `distribution-contract-tests.mjs`, which pins
+      //      the withholding and will correctly go red;
+      //   3. re-seal the affected locks;
+      //   4. delete the `postgres.extensions` BRIDGE blocks from
+      //      `deployments/presenca-dev/secret-inputs.yaml` and
+      //      `deployments/owl-xema-prod/secret-inputs.yaml` in xema-deploy —
+      //      the deploy plane REFUSES that bridge by name the moment any biome
+      //      in the lock carries this key, so 3 and 4 cannot be separated.
+      //
+      // Until then the field is still PARSED and still travels into the biome
+      // INDEX — nothing rejects it there — so the declaration is validated and
+      // only the LOCK, the one artifact a strict consumer parses, omits it.
+      //
+      // ...(e.serviceDatabaseExtensions === undefined
+      //   ? {}
+      //   : { serviceDatabaseExtensions: e.serviceDatabaseExtensions }),
+      // Images the biome ships that are never scheduled — another workload
+      // launches them one-per-allocation, prepulls them, or consumes them.
+      // Carried SEPARATELY from `services` so the deploy plane cannot roster a
+      // release for something that has no standing workload, while the image
+      // plane still builds, addresses, signs and mirrors it.
+      runtimeComponents: Array.isArray(e.runtimeComponents)
+        ? e.runtimeComponents
+        : [],
+      // Executable modules the distribution mounts into a platform-owned host
+      // (the connector adapters loaded by `biome-adapter-host`). Projected
+      // verbatim from the index, which resolved each component's bundle source
+      // against the biome manifest.
+      hostModules: Array.isArray(e.hostModules) ? e.hostModules : [],
+      // The BIOME-LEVEL bundle source, for a biome whose bundle no host module
+      // above names — the field a `installPolicy: required` service-only
+      // biome needs for the runtime's required-biome reconciler to fetch,
+      // verify and admit it from the mounted lock. Projected verbatim from the
+      // index, which validated it against the kernel's one bundle-source
+      // shape (`manifestToIndexEntry`, which also says why a host-module
+      // biome gains no second copy here).
+      //
+      // SPREAD CONDITIONALLY, for the reason `source` and `owner` are: an
+      // unconditional key would move the bytes of every committed lock for a
+      // fact none of their entries carries. A lock in which SOME biome carries
+      // it still is the one v5 grammar once sealed.
+      ...(e.bundleSource === undefined ? {} : { bundleSource: e.bundleSource }),
+      serviceDependencies: Array.isArray(e.serviceDependencies)
+        ? e.serviceDependencies
+        : [],
+      // Resolved resource BINDINGS — an AUTHORIZATION input the provider
+      // enforces against the caller's verified service identity, as
+      // `serviceDatabases` is for the database pool.
+      //
+      // SPREAD CONDITIONALLY, for the reason `bundleSource` is: no committed
+      // manifest declares `protocol.resources`, so an unconditional `[]` would
+      // move the bytes of every committed lock. It is an ADDITIVE, optional
+      // field of the v4 grammar — no version bump — so a lock in which some
+      // biome carries a binding is stamped 4, and a consumer reading it
+      // through the kernel's tolerant reader schema needs no upgrade to parse
+      // it. A consumer still on the strict writer schema refuses the key; that
+      // one-time switch is sequenced separately, before an edition carries one.
+      ...bindServiceResourcesFor(e),
+      // `service → { componentKind, scalingMode, processFacts? }` — the facts
+      // the deploy plane grades a composed process on (kernel
+      // `LockedServiceProcessFactsSchema`), forwarded from the index, where
+      // `componentProcessFacts` derived them from each platform-scheduled
+      // image component. One row per name in `services`, so a service that
+      // declares nothing still carries its derived kind and scaling class.
+      //
+      // Emitted for every biome that ships a platform-scheduled service; a
+      // lock carrying it is stamped v4 by the kernel. The edition carries the
+      // FACTS; which members share a process is the DEPLOYMENT's topology.
+      // Every lock reader the fleet pins parses it: `repos/xema-base` resolves
+      // `@xemahq/contracts` 0.31.0 and `repos/xema-operator` 0.30.0 at their
+      // pins (the key exists with `componentKind` from 0.29.0), and the seal
+      // refuses an edition whose own images cannot parse its lock
+      // (platform-lock-readability.mjs).
+      ...(e.serviceProcessFacts !== undefined
+        ? { serviceProcessFacts: lockedServiceProcessFacts(e) }
+        : {}),
+      // The biome's worker Nexus FACTS — what it provides and requires — copied
+      // from the index in the kernel's canonical form. The lock carries them
+      // beside the `nexusBindings` they derive (the kernel writer requires the
+      // two to agree), so a composition or proposal re-resolving from this lock
+      // re-checks every requirement without the index. Omitted when empty, so
+      // every edition declaring none is byte-identical. Because every lock is
+      // re-resolved from the index and compared byte for byte (dist:check's lock
+      // parity), a lock's facts that disagree with the index fail that check.
+      ...schemas.canonicalNexusFacts({
+        nexusProvides: e.nexusProvides,
+        nexusRequires: e.nexusRequires,
+      }),
+      // The protocol worker/v2 components and the queues each polls — what the
+      // deploy plane renders under a Worker Controller (W3.4 / U14). Omitted
+      // when empty, so an edition shipping no v2 worker is byte-identical.
+      ...(e.workerTaskQueues !== undefined && Object.keys(e.workerTaskQueues).length > 0
+        ? { workerTaskQueues: e.workerTaskQueues }
+        : {}),
+      // The queues each http service starts workflows on, by the same service
+      // name `workerTaskQueues` keys by. Omitted when empty.
+      ...(e.workflowClients !== undefined && Object.keys(e.workflowClients).length > 0
+        ? { workflowClients: e.workflowClients }
+        : {}),
+      // The workflow SUBJECTS among those components (every v2 worker and every
+      // workflow-starting service) — derived by the kernel, whose lock schema
+      // requires the stated list to equal the same derivation. Omitted when
+      // empty, as the kernel requires.
+      ...lockedWorkflowSubjects(e, schemas),
+      // The biome's trust CEILING under the edition's `trustCeiling` policy,
+      // by the kernel's one derivation; omitted when it is the biome's default
+      // domain, so an edition that groups nothing seals the bytes it always did.
+      ...lockedTrustCeiling(e, trustCeiling, schemas),
+      // The workers that run a sibling service's sealed image with their own
+      // entry module — what the deploy plane pins and renders as
+      // `node <entry>`. STATED ON EVERY BIOME, `{}` when it has none: the
+      // kernel writer requires it, and the deploy plane refuses a lock that
+      // does not state it, because an omitted field read as "no workers" is
+      // how a customer edition 0.0.41 shipped two declared workers and
+      // deployed neither. The INDEX keeps omitting an empty map (it is
+      // byte-stable and re-derived from the manifests by dist:check, and
+      // `manifestToIndexEntry` projects EVERY shared-oci-image worker or
+      // throws), so an entry without the key is one whose manifest declares
+      // no such worker.
+      workerImages: e.workerImages ?? {},
+      // --- Catalog projection (consumed by biome-host's DistributionCatalogSource) ---
+      // Forwarded verbatim from the index so the lock is the SELF-CONTAINED
+      // single source of truth for the biome catalog: biome-host builds the
+      // web/server registry DTOs from these without re-reading any manifest.
+      displayName: e.displayName,
+      packageName: e.packageName ?? null,
+      requiresServerBiomes: Array.isArray(e.requires) ? e.requires : [],
+      optionalServerBiomes: Array.isArray(e.optionalServerBiomes)
+        ? e.optionalServerBiomes
+        : [],
+      audience: e.audience ?? 'org',
+      storeListed: typeof e.storeListed === 'boolean' ? e.storeListed : true,
+      sourceManifestHash: e.sourceManifestHash,
+      ...(e.display ? { display: e.display } : {}),
+      // Absent in the index means the manifest declared no `systemSurface`,
+      // which IS `false` — the biome is store-listed rather than rail-mounted.
+      // Stated here rather than omitted for the same reason as
+      // `serviceDatabases`: the lock is the contract, not the index.
+      systemSurface: e.systemSurface ?? false,
+      // Distribution launch-placement decision (see PER_INSTALLATION_LAUNCH).
+      // Always stated: `static` is a DECISION this resolver made, not an
+      // absence, and a reader that had to infer it would be re-deciding
+      // placement at boot from a missing key.
+      launch: PER_INSTALLATION_LAUNCH.has(e.id)
+        ? BiomeLaunchMode.PerInstallation
+        : BiomeLaunchMode.Static,
+      // The pinned external source this biome was drawn from, when one was.
+      //
+      // LAST IN THE LITERAL AND SPREAD CONDITIONALLY, for the reason `owner`
+      // and `visibility` are appended after `inputHash` below: `serializeJson`
+      // is insertion-order `JSON.stringify`, so an unconditional key would
+      // change the bytes of every one of the nine committed locks for a fact
+      // none of their 117 entries carries (measured: 0 of 117 carry `source`).
+      //
+      // `e.source` is the source NAME — that is what `entrySourceAdmissible`
+      // scopes on — and the lock records the full pinned `LockedBiomeSource`,
+      // so a reader of the artifact never has to resolve a handle against a
+      // manifest it does not have.
+      ...(e.source === undefined
+        ? {}
+        : { source: requireSourceRecord(e, sourceRecords) }),
+    }))
+    .sort(compareIndexEntries);
+
+  // Platform substrate services (non-biome), tier-ordered then by name.
+  // The kernel already derives exactly this as `PLATFORM_SERVICE_TIER_RANK`
+  // (`@xemahq/kernel-contracts/distribution`) — `'infra'` below the biome
+  // ladder, `'edge'` above it. It is still spelled here because that subpath
+  // loads through the ASYNC `loadKernelDistributionSchemas` and is a rank MAP,
+  // not an array used with `indexOf`. The biome ladder itself is no longer a
+  // local literal: `biomeTierOrder()` reads the kernel's.
+  const TIER_WITH_EDGE = ['infra', ...biomeTierOrder(), 'edge'];
+  const platformServiceList = [...shippedPlatformServices.values()]
+    .map((service) => {
+      const source = platformSourcesByName.get(service.name);
+      // `installationClass` is a RESOLVE-TIME INPUT and is deliberately NOT
+      // carried into the lock. It answers "should this edition contain the
+      // service", which the resolver has already answered by the time this
+      // list exists; no lock consumer — the deploy roster generator, the
+      // bring-up plan, the appliance build — asks it. Emitting it would ship a
+      // field with no reader AND would change the bytes of every committed
+      // lock for a fact none of them uses.
+      //
+      // The strip is EXPLICIT rather than implied by the destructure order,
+      // because `LockedPlatformServiceSchema` is `.strict()`: a spread that
+      // carried the field would fail the lock parse rather than silently
+      // widening it. That refusal is the right posture and this is the right
+      // side of it.
+      const { installationClass: _installationClass, ...locked } = service;
+      return { ...locked, source };
+    })
+    .sort((a, b) => {
+      const ta = TIER_WITH_EDGE.indexOf(a.tier);
+      const tb = TIER_WITH_EDGE.indexOf(b.tier);
+      if (ta !== tb) {return ta - tb;}
+      return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+    });
+
+  // Capability-domain reservation table -- built from the FULL index, so it is
+  // IDENTICAL in every edition regardless of which biomes this one selects.
+  // Deriving it from the SELECTED set would be fail-open: a trimmed edition
+  // would leave `kb`/`agent`/... unowned, and an org admin could install the
+  // owning biome from the store and then bind its refs to a URL they control.
+  // See `buildCapabilityDomainOwners`. Throws on a duplicate claim.
+  const capabilityDomainOwners = buildCapabilityDomainOwners(index);
+
+  // inputHash: deterministic over the index SUBSET that fed the lock + the
+  // reservation table + the leaf manifest, so drift in any input is detectable.
+  const subset = serializeJson(biomes);
+  const platform = serializeJson(platformServiceList);
+  const owners = serializeJson(capabilityDomainOwners);
+  const manifestImg = serializeJson(leaf);
+  const inputHash = sha256Hex(
+    `${subset}\0${platform}\0${owners}\0${manifestImg}`,
+  );
+
+  const lock = {
+    // The resolver writes the UNSEALED document: it has no schemaVersion and no
+    // biomeContentHash. The seal mints each hash and the kernel's
+    // `sealDistributionLock` produces the one v5 grammar; the CLI never
+    // assembles a sealed lock itself.
+    unsealedSchema: schemas.UNSEALED_DISTRIBUTION_LOCK_SCHEMA,
+    distributionId: id,
+    biomes,
+    platformServices: platformServiceList,
+    capabilityDomainOwners,
+    resolvedAt,
+    inputHash,
+  };
+
+  // Owner and visibility are written ONLY when something declared them, and
+  // they are appended AFTER `inputHash` rather than woven into the literal
+  // above. Both halves matter for the nine committed locks: `serializeJson`
+  // is insertion-order `JSON.stringify`, so an unconditional key would change
+  // every lock's bytes, and a key inserted mid-literal would reorder them even
+  // when absent-valued. Neither field is in the inputHash — the hash covers
+  // the leaf manifest, which already carries both declarations.
+  if (owner !== undefined) {lock.owner = owner;}
+  // Tighten-only: one `private` anywhere in the edition's declarations makes the edition
+  // private, whatever a descendant says. Absent everywhere stays absent, which
+  // is what keeps all eight existing locks byte-identical.
+  const visibility = (declaredVisibilities ?? []).includes(
+    DistributionVisibility.Private,
+  )
+    ? DistributionVisibility.Private
+    : (declaredVisibilities ?? [])[(declaredVisibilities ?? []).length - 1];
+  if (visibility !== undefined) {lock.visibility = visibility;}
+  // Provenance — written ONLY by a positive-closure edition, appended last for
+  // the reason owner and visibility are: a selector-model lock carries exactly
+  // the bytes it always did. Not in `inputHash`: it is DERIVED from the inputs
+  // the hash already covers (the leaf manifest's roots and the index subset).
+  if (resolutionSection !== undefined) {lock.resolution = resolutionSection;}
+  // Nexus bindings — written ONLY when some shipped worker requires a Nexus
+  // service, appended last for the same reason, so every lock that binds none
+  // carries exactly the bytes it always did. Not in `inputHash`: derived from
+  // the selected biomes, whose `sourceManifestHash` the hash already covers.
+  if (nexusBindings.length > 0) {lock.nexusBindings = nexusBindings;}
+
+  // (7) Re-derive the ownership index through the KERNEL so the table this
+  //     resolver emits is validated by the exact code every consumer will read
+  //     it with (`capability-registry-api`, `xema-capability-router`). Catches
+  //     a domain whose grammar the kernel rejects, and any collision that
+  //     survived `buildCapabilityDomainOwners`. Run BEFORE the schema parse so
+  //     the message names the offending domain rather than surfacing as a
+  //     generic shape error, and so the failure lands at BUILD time — the
+  //     boot-time throw is only the backstop. No try/catch: it must propagate.
+  schemas.resolveFirstPartyCapabilityDomains(lock);
+
+  // (8) Validate against the BUILT kernel schema — fail-fast.
+  schemas.parseUnsealedDistributionLock(lock);
+  return validateImmutableDistributionLock(lock);
+}
+
+/**
+ * Produce a lock object for a distribution id (used by both the CLI and
+ * dist-check). `resolvedAt` is freshly stamped each call; callers that diff
+ * against a committed lock must normalize it out.
+ */
+export async function resolveDistribution(id) {
+  return (await resolveDistributionWithIndex(id)).lock;
+}
+
+/**
+ * The lock TOGETHER WITH the index it was resolved from: the committed
+ * platform index plus this edition's source-walked entries, each carrying its
+ * `source` stamp.
+ *
+ * Anything that must look a lock biome up again — the authorization seal, and
+ * dist-check's currency check of it — reads THIS index. `biome-index.json`
+ * alone is the platform's and never holds a source-walked biome, so a second
+ * lookup against it refuses every edition that declares `sources[]` right
+ * after resolving it correctly. One walk, one merged index, handed on.
+ *
+ * `materialize` is the walk's one network seam, injectable for the contract
+ * suite exactly as it is on `walkDeclaredSources`.
+ */
+export async function resolveDistributionWithIndex(id, { materialize, inputs } = {}) {
+  const schemas = await loadKernelDistributionSchemas();
+  // THE RELEASE READS THESE FROM DISK; A DEVELOP SNAPSHOT INJECTS THEM
+  // (`develop-snapshot-inputs.mjs`). Either way they pass through the one
+  // validation below, so there is a single resolve path and two sources.
+  const platformServiceIndex =
+    inputs?.platformServiceIndex ?? readPlatformServiceIndex(schemas.parsePlatformServiceSourceIndex);
+  const platformIndex = validateServiceDependencyOwnerParity(
+    validateImmutableBiomeIndex(inputs?.biomeIndex ?? readBiomeIndex()),
+    platformServiceIndex,
+  );
+  // The manifest is composed FIRST, because it is what declares the sources. The
+  // walk then runs once per resolve and its entries are merged into a
+  // per-resolution index — never into `biome-index.json`, which is the
+  // platform's and is read by every edition.
+  const composed = inputs?.composed ?? composeEdition(schemas.parseDistribution, id);
+  const { entries, sourceRecords } = await walkDeclaredSources({
+    sources: composed.declaredSources,
+    ...(materialize === undefined ? {} : { materialize }),
+  });
+  const index = mergeExternalSourceEntries(platformIndex, entries, platformServiceIndex);
+  const lock = resolveDistributionFromInputs(
+    id,
+    index,
+    schemas,
+    { ...composed, sourceRecords },
+    new Date().toISOString(),
+    platformServiceIndex,
+  );
+  return { lock, index };
+}
+
+/**
+ * Resolve and persist one distribution lock. The CLI and the plane refresh use
+ * this exact writer so an in-process refresh cannot drift from the standalone
+ * command's serialization or diagnostics.
+ */
+export async function writeResolvedDistribution(id, { log = true, materialize } = {}) {
+  const { lock, index } = await resolveDistributionWithIndex(id, { materialize });
+  const outPath = join(editionsRoot(), id, 'distribution.lock.json');
+  assertReleaseContent(lock, `the distribution lock for "${id}"`);
+  assertReleaseEditionTree(join(editionsRoot(), id));
+  mkdirSync(join(editionsRoot(), id), { recursive: true });
+  writeFileSync(outPath, serializeJson(lock));
+  await sealAuthorizationBase(id, lock, index, { log });
+  // The chart generation this edition is rendered with: the fleet pin, copied
+  // byte-identically (edition-chart-set.mjs). A resolve always yields a whole
+  // edition; resolve-chart-set.mjs keeps every copy on the pin thereafter.
+  const pinPath = fleetChartSetLockPath();
+  if (!existsSync(pinPath)) {
+    throw new Error(`${pinPath} is missing — run resolve-chart-set.mjs; an edition is not resolved without its chart set`);
+  }
+  const pinText = readFileSync(pinPath, 'utf8');
+  writeEditionChartSet(join(editionsRoot(), id), pinText);
+  if (log) {
+    const byTier = biomeTierOrder().map(
+      (t) => `${t}=${lock.biomes.filter((b) => b.tier === t).length}`,
+    ).join(' ');
+    console.log(
+      `[dist:resolve] wrote ${outPath} — ${lock.biomes.length} biomes (${byTier}), ` +
+        `${lock.platformServices.length} platform service(s).`,
+    );
+  }
+  return lock;
+}
+
+/**
+ * Compose the edition's authorization base with the PINNED kernel's composer
+ * (platform modules + every selected biome's module), run every composed
+ * `.fga.yaml` with the pinned `fga model test`, and seal
+ * `authorization.lock.json` beside the lock. The committed lock, when present,
+ * is the `adopted` base the composition must stay compatible with. A pinned
+ * kernel without the composer seals nothing and retires a stale lock.
+ *
+ * `index` is the index THIS lock was resolved from
+ * (`resolveDistributionWithIndex`), required: it carries the edition's
+ * source-walked biomes, which the committed platform index never does.
+ */
+export async function sealAuthorizationBase(id, lock, index, { log = true } = {}) {
+  const sealed = await composeAuthorizationBase(id, lock, index);
+  assertReleaseContent(sealed, `the authorization lock for "${id}"`);
+  const editionDir = join(editionsRoot(), id);
+  const path = writeAuthorizationLock(editionDir, sealed, serializeJson);
+  if (!log) {return sealed;}
+  console.log(
+    sealed === null
+      ? `[dist:resolve] ${id}: the pinned kernel ships no authorization composer — no authorization base sealed.`
+      : `[dist:resolve] wrote ${path} — generation ${sealed.platformGeneration}, ` +
+          `${sealed.modules.length} biome module(s), model ${sealed.modelHash}.`,
+  );
+  return sealed;
+}
+
+/**
+ * The PURE half of {@link sealAuthorizationBase}: compose and test the
+ * authorization base, return it (or `null` under a kernel without a composer),
+ * write nothing. The committed lock of the editions root is the `adopted` base.
+ * A develop edition calls only this; the release calls it and then writes.
+ */
+export async function composeAuthorizationBase(id, lock, index) {
+  if (!Array.isArray(index)) {
+    throw new Error(
+      `${id}: sealAuthorizationBase needs the index the lock was resolved from ` +
+        '(resolveDistributionWithIndex). The committed platform index alone does not hold a source-walked biome.',
+    );
+  }
+  const editionDir = join(editionsRoot(), id);
+  const kernel = await loadKernelAuthorizationComposer({ kernelPackageDir: kernelPackageDir() });
+  // Refuses an edition that carries a module under a pin with no composer.
+  const inputs = editionAuthorizationModuleInputs(lock.biomes, new Map(index.map((e) => [e.id, e])), kernel);
+  let sealed = null;
+  if (kernel !== null) {
+    sealed = sealEditionAuthorizationBase({
+      distributionId: id,
+      inputs,
+      kernel,
+      adopted: adoptedFromLock(readAuthorizationLock(editionDir)),
+      runTests: fgaComposedModelTestRunner(resolveFgaCli()),
+    });
+  }
+  return sealed;
+}
+
+async function main() {
+  const id = process.argv[2];
+  if (!id) {
+    console.error(
+      'usage: node resolve-distribution.mjs <root flags> <distribution-id>',
+    );
+    process.exit(1);
+  }
+  await writeResolvedDistribution(id);
+}
+
+// Only run main() when invoked directly, not when imported by dist-check.
+if (isEntryModule(import.meta.url)) {
+  main().catch((err) => {
+    console.error(`[dist:resolve] ${err.message}`);
+    process.exit(1);
+  });
+}