@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/develop-channel-record.mjs

@@ -0,0 +1,49 @@
+// develop-channel-record — a member's build record read through a CHANNEL TAG (`<records repository>:<tag>`, e.g.
+// `:develop`), the tag the producer's CI moves forward to its newest green record.
+//
+// The dev lane trusts the channel tag, not a signature: records are not signed there. One manifest is read by tag
+// (never a tag listing: the pull-through proxy serves single tags only), the record is parsed against the kernel's
+// schema and held to the member (its producer repository, its branch). There is no git ancestry: the tag only moves
+// forward. A tag that does not exist, or a record that does not hold, is a `RecordRefused` naming the member.
+
+import { assertRecordBranch, memberOwnerName, producerClaims, readRecord, recordsClientOf } from './develop-build-record.mjs';
+import { RecordRefused } from './record-refused.mjs';
+
+/**
+ * @param {object} request
+ * @param {object} request.kernel the kernel's distribution exports (requireBuildRecordKernel)
+ * @param {(authority: string) => object} request.clientFor
+ * @param {{repo: string, repositoryUrl: string}} request.member
+ * @param {string} request.branch
+ * @param {string} request.channel the tag
+ * @returns {Promise<{record: object, snapshot: string, repository: string}>} `snapshot` is `<run>.<attempt>`
+ */
+export async function loadChannelRecord({ kernel, clientFor, member, branch, channel }) {
+  const { repo } = member;
+  const { ref, repository, client } = recordsClientOf({ clientFor, member });
+  const { record } = await readRecord({ kernel, client, repository, repo, tag: channel, absentIsRefusal: true });
+  const { snapshot } = producerClaims({ record, repo, memberRepository: memberOwnerName(member.repositoryUrl) });
+  assertRecordBranch({ record, repo, tag: channel, branch });
+  return { record, snapshot, repository: ref };
+}
+
+/**
+ * The record a selection PINNED for a member, read by its own immutable record tag (`buildRecordTag`, e.g.
+ * `develop-3038-1`), never through the moving channel tag: `snapshot` is the `<run>.<attempt>` the selection wrote.
+ * The record must be that run's (its producer claims the same snapshot) and of the branch. A channel that moved after
+ * selection does not touch this read.
+ *
+ * @returns {Promise<{record: object, repository: string, tag: string}>}
+ */
+export async function loadSelectedRecord({ kernel, clientFor, member, branch, snapshot }) {
+  const { repo } = member;
+  const run = /^(\d+)\.(\d+)$/.exec(String(snapshot));
+  if (run === null) {throw new RecordRefused(repo, `the selection's snapshot ${JSON.stringify(snapshot)} is not <run>.<attempt>`);}
+  const tag = kernel.buildRecordTag({ branch, producer: { kind: 'github-actions', runNumber: Number(run[1]), runAttempt: Number(run[2]) } });
+  const { ref, repository, client } = recordsClientOf({ clientFor, member });
+  const { record } = await readRecord({ kernel, client, repository, repo, tag, absentIsRefusal: true });
+  const claims = producerClaims({ record, repo, memberRepository: memberOwnerName(member.repositoryUrl) });
+  if (claims.snapshot !== snapshot) {throw new RecordRefused(repo, `record ${ref}:${tag} is run ${claims.snapshot}, not the selected ${snapshot}`);}
+  assertRecordBranch({ record, repo, tag, branch });
+  return { record, repository: ref, tag };
+}

package/edition/develop-channel-satellites.mjs

@@ -0,0 +1,65 @@
+// develop-channel-satellites — the satellite check of the dev lane (`--channel <tag>`), a consistency check, not a
+// signature check.
+//
+// It requires a satellite entry's {name, digest} to be listed in the producer build record the selection PINNED, read
+// by that record's own tag (develop-channel-record.mjs `loadSelectedRecord`), at the commit the snapshot pins for the
+// producer. The channel tag is never read here: a channel that moved after selection (a newer green build) does not
+// affect the run. Every refused claim is named at once; a registry that could not answer is a plain Error.
+
+import { withChannelReader } from './develop-build-record.mjs';
+import { loadSelectedRecord } from './develop-channel-record.mjs';
+import { firstPartySources } from './first-party-source-ids.mjs';
+import { ImageBuildRecordError, satelliteProducerOf, subjectKeyOf } from './images-from-record.mjs';
+import { RecordRefused } from './record-refused.mjs';
+
+const CHANNEL_BRANCH = 'develop';
+
+/**
+ * The producer as a record member: its `owner/name`, the URL its record's producer repository is held to and, when
+ * its declared source declares a develop store, the root its records live under.
+ */
+const producerMember = (producer, { developImageRegistry }) => ({
+  repo: producer,
+  repositoryUrl: `https://github.com/${producer}.git`,
+  ...(developImageRegistry === undefined ? {} : { developImageRegistry }),
+});
+
+/**
+ * @param {object} request
+ * @param {object} [request.declaredSources] `firstPartySources` (tests pass it): a producer's declared `developImageRegistry` holds its records
+ * @param {string} request.channel the tag
+ * @param {object} request.selection the parsed selection (`snapshot`: source repo -> `<run>.<attempt>`): each satellite
+ *   is checked against the record it pinned, never the channel's current tip
+ * @param {Function} [request.withReader] the kernel and registry client scope (tests replace it)
+ * @returns {(claims: {subject: object, entry: object}[]) => Promise<void>}
+ */
+export function createChannelSatelliteVerifier({ channel, selection, env = process.env, withReader = withChannelReader, declaredSources = firstPartySources('locating a satellite producer\'s build records'), ...readerInjections }) {
+  return async (claims) => {
+    if (claims.length === 0) {return;}
+    await withReader({ env, ...readerInjections }, async ({ kernel, clientFor }) => {
+      const refused = [];
+      for (const { subject, entry } of claims) {
+        try {
+          const producer = satelliteProducerOf(subject);
+          const member = producerMember(producer, declaredSources[subject.repo]);
+          const snapshot = selection.snapshot?.[subject.repo];
+          if (snapshot === undefined) {throw new RecordRefused(producer, `the selection pins no record of ${subject.repo}`);}
+          const { record, repository, tag } = await loadSelectedRecord({ kernel, clientFor, member, branch: CHANNEL_BRANCH, snapshot });
+          const named = `the selected record ${repository}:${tag}`;
+          if (record.commit !== entry.sourceSha) {
+            throw new RecordRefused(producer, `${named} is at ${record.commit}, but the snapshot pins ${entry.sourceSha}`);
+          }
+          if (!record.images.some((listed) => listed.name === entry.repository && listed.digest === entry.digest)) {
+            throw new RecordRefused(producer, `${named} does not list ${entry.repository}@${entry.digest}`);
+          }
+        } catch (error) {
+          if (!(error instanceof RecordRefused)) {throw error;}
+          refused.push(`${subjectKeyOf(subject)}: ${error.message}`);
+        }
+      }
+      if (refused.length > 0) {
+        throw new ImageBuildRecordError(`${refused.length} satellite image(s) of the build record are not verified against channel ${channel}:\n  ${refused.join('\n  ')}`);
+      }
+    });
+  };
+}

package/edition/develop-chart-roster.mjs

@@ -0,0 +1,96 @@
+// develop-chart-roster — the develop chart roster of a deploy checkout, as the
+// deploy repository itself computes it.
+//
+// A develop chart's version is `0.0.0-h<16 hex>`, the first 16 hex of its full
+// content digest (xema-deploy scripts/lib/chart-content-digest.mjs,
+// developChartVersionFromDigest). That function belongs to the deploy
+// repository, and so does the index version derived from the roster: publish-
+// charts on refs/heads/develop runs the same code to publish the charts and
+// close the set with its `xema-chart-set` index. So the CLI never reimplements
+// or vendors it: it runs the entry point of the frozen deploy checkout
+// (`scripts/chart-content-digest.mjs --develop-roster --json`), which is the
+// code the publisher ran for that commit, and validates the one document it
+// prints. A vendored copy would pin the CLI to one revision of a hash whose
+// owner is the deploy commit being resolved.
+
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+
+import { parseStrictJson } from './strict-json.mjs';
+
+/** The schema string the deploy entry point stamps on its develop roster. */
+export const DEVELOP_CHART_ROSTER_SCHEMA = 'xema-develop-chart-roster/1';
+
+/** The entry point, relative to the deploy checkout, and its arguments. */
+export const DEVELOP_CHART_ROSTER_ENTRY = 'scripts/chart-content-digest.mjs';
+export const DEVELOP_CHART_ROSTER_ARGS = Object.freeze(['--develop-roster', '--json']);
+
+/** A develop channel coordinate: revision 0 and the content digest's first 16 hex. */
+export const DEVELOP_CHART_VERSION_PATTERN = /^0\.0\.0-h[0-9a-f]{16}$/;
+
+/** A chart name as Helm and the registry address it. */
+const CHART_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+const ROSTER_KEYS = 'indexVersion,members,schema';
+const MEMBER_KEYS = 'name,version';
+
+/**
+ * Validate the develop roster document `document` (from `source`) and return
+ * `{indexVersion, members: [{name, version}]}`. Every rule is strict: the exact
+ * schema string and keys, develop coordinates only, and members sorted by name
+ * with no name twice.
+ */
+export function parseDevelopChartRoster(document, source) {
+  const fail = (why) => {
+    throw new Error(`${source} is not a ${DEVELOP_CHART_ROSTER_SCHEMA} roster: ${why}`);
+  };
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {fail('it is not a JSON object');}
+  if (document.schema !== DEVELOP_CHART_ROSTER_SCHEMA) {fail(`schema must be "${DEVELOP_CHART_ROSTER_SCHEMA}" (got ${JSON.stringify(document.schema)})`);}
+  const keys = Object.keys(document).sort().join(',');
+  if (keys !== ROSTER_KEYS) {fail(`it must carry exactly ${ROSTER_KEYS} (got ${keys})`);}
+  if (!DEVELOP_CHART_VERSION_PATTERN.test(String(document.indexVersion))) {
+    fail(`indexVersion must be a develop coordinate 0.0.0-h<16 hex> (got ${JSON.stringify(document.indexVersion)})`);
+  }
+  if (!Array.isArray(document.members) || document.members.length === 0) {fail('members must be a non-empty array');}
+  let previous = '';
+  const members = document.members.map((member, position) => {
+    if (!member || typeof member !== 'object' || Array.isArray(member) || Object.keys(member).sort().join(',') !== MEMBER_KEYS) {
+      fail(`member ${position} must be exactly {name, version}`);
+    }
+    if (!CHART_NAME_PATTERN.test(String(member.name))) {fail(`member ${position} has a malformed chart name ${JSON.stringify(member.name)}`);}
+    if (!DEVELOP_CHART_VERSION_PATTERN.test(String(member.version))) {
+      fail(`${member.name} has no develop coordinate 0.0.0-h<16 hex> (got ${JSON.stringify(member.version)})`);
+    }
+    if (member.name <= previous) {fail(`members must be sorted by name with no name twice (${member.name} follows ${previous})`);}
+    previous = member.name;
+    return { name: member.name, version: member.version };
+  });
+  return { indexVersion: document.indexVersion, members };
+}
+
+/**
+ * The develop roster of the deploy checkout at `deployDir`: its own entry point
+ * run with this node, in that checkout, with only PATH from the environment (the
+ * entry point needs git and nothing else; no credential reaches it).
+ */
+export function readDevelopChartRoster(deployDir) {
+  const entry = join(deployDir, DEVELOP_CHART_ROSTER_ENTRY);
+  let stdout;
+  try {
+    stdout = execFileSync(process.execPath, [entry, ...DEVELOP_CHART_ROSTER_ARGS], {
+      cwd: deployDir,
+      encoding: 'utf8',
+      env: { PATH: process.env.PATH ?? '' },
+      maxBuffer: 16 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    const stderr = typeof error?.stderr === 'string' ? error.stderr.trim() : '';
+    throw new Error(
+      `the deploy checkout's develop roster failed (node ${DEVELOP_CHART_ROSTER_ENTRY} ${DEVELOP_CHART_ROSTER_ARGS.join(' ')} in ${deployDir}): ${stderr || error.message}`,
+      { cause: error },
+    );
+  }
+  const source = `${DEVELOP_CHART_ROSTER_ENTRY} ${DEVELOP_CHART_ROSTER_ARGS.join(' ')}`;
+  return parseDevelopChartRoster(parseStrictJson(stdout, source), source);
+}

package/edition/develop-chart-set.mjs

@@ -0,0 +1,147 @@
+// develop-chart-set — the chart-set lock of a develop edition.
+//
+// A develop edition renders the charts of its frozen deploy commit. The deploy
+// checkout computes its own develop roster (develop-chart-roster.mjs: every
+// chart at `0.0.0-h<16 hex>` and the set's index version), and xema-deploy
+// publish-charts on refs/heads/develop publishes those charts and closes the
+// set with a `xema-chart-set` index at that index version, the same artifact
+// a release closes its set with. So a develop lock is resolved exactly as a
+// release one is (resolve-chart-set.mjs), only at a version the deploy commit
+// names instead of the newest the registry holds: read the index at the
+// roster's index version, require its members to be the roster, seal every
+// member against the registry, and build the same schemaVersion 4 lock. The
+// committed release lock is never read.
+//
+// TWO PUBLISHERS. A develop lock lists the publisher whose repository is the
+// deploy pin role's (this resolution) followed by the release infra publisher,
+// taken verbatim from the data root's committed chart-set.lock.json. Infra
+// charts have no develop channel: the committed release entry is the only
+// published infra set, and the deploy engine plans and applies scope infra on
+// every channel, so a develop deployment needs it to move infra (pgbouncer,
+// openfga) through the pipeline. The data root pin is already in the
+// develop tag, so a moved infra entry moves the tag. A committed lock that is
+// absent, or lacks exactly one infra publisher, is refused: no fallback, no
+// develop-without-infra mode.
+//
+// NOT PUBLISHED IS A REFUSAL. An index or member the registry does not serve
+// (404) is refused by name and version: publish-charts for the deploy commit
+// has not finished green. There is no fallback to any other set.
+
+import { basename } from 'node:path';
+
+import { RefusalError } from './collected-refusals.mjs';
+import { readDevelopChartRoster } from './develop-chart-roster.mjs';
+import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
+import { deployRoot } from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import { deployPinKey } from './pin-source.mjs';
+import {
+  CHART_SET_LOCK_FILE,
+  buildLock,
+  chartSetLockPath,
+  chartRegistryClient,
+  chartSetPublishers,
+  indexRosterAndDigest,
+  readLock,
+  registryChartDigest,
+  sealRoster,
+} from './resolve-chart-set.mjs';
+
+const NOT_FOUND = 404;
+
+/** The publisher whose repository is the deploy pin role's; exactly one must be configured. */
+function deployPublisher() {
+  const deployRepo = basename(deployPinKey());
+  const publishers = chartSetPublishers().filter((publisher) => basename(publisher.repo) === deployRepo);
+  if (publishers.length !== 1) {
+    throw new RefusalError(
+      `${publishers.length} configured chart publishers have repository ${deployRepo} (the deploy pin role); exactly one must, ` +
+        'since a develop chart set is that publisher\'s set at the deploy commit',
+    );
+  }
+  return publishers[0];
+}
+
+/** The configured publishers that are not the deploy pin role's: the infra publisher(s) a release lock carries. */
+function infraPublisherIndexes() {
+  const deployRepo = basename(deployPinKey());
+  return chartSetPublishers().filter((publisher) => basename(publisher.repo) !== deployRepo).map((publisher) => publisher.index);
+}
+
+/** The ONE infra publisher entry of the data root's committed release lock, unchanged. */
+function committedInfraPublisher() {
+  const path = chartSetLockPath();
+  const committed = readLock(path);
+  if (committed === null) {
+    throw new RefusalError(`${path} is absent or unreadable; a develop edition carries the release infra chart set from it`);
+  }
+  assertRosteredChartSetLock(committed, path);
+  const indexes = infraPublisherIndexes();
+  const found = committed.publishers.filter((publisher) => indexes.includes(publisher.index));
+  if (indexes.length !== 1 || found.length !== 1) {
+    throw new RefusalError(
+      `${path} carries ${found.length} infra publisher entries (${indexes.length} infra publishers configured); exactly one is required`,
+    );
+  }
+  return found[0];
+}
+
+/** Run `read`; a registry 404 becomes the "not published yet" refusal naming `what` and the publisher's run for the deploy commit. */
+async function published(read, what, { publisher, xemaDeploySha }) {
+  try {
+    return await read();
+  } catch (error) {
+    if (error?.status !== NOT_FOUND) {throw error;}
+    throw new RefusalError(`${what} is not published yet; ${publisher.repo} publish-charts for ${xemaDeploySha} not green`, { cause: error });
+  }
+}
+
+/** Refuse an index whose members are not exactly the roster's names at the roster's versions. */
+function assertIndexIsRoster(indexRoster, members, label) {
+  const expected = members.map(({ name, version }) => `${name} ${version}`);
+  const actual = Object.entries(indexRoster).map(([name, member]) => `${name} ${member.version}`);
+  const missing = expected.filter((line) => !actual.includes(line));
+  const extra = actual.filter((line) => !expected.includes(line));
+  if (missing.length > 0 || extra.length > 0) {
+    throw new RefusalError(
+      `${label} does not carry the deploy checkout's develop roster: ` +
+        `missing [${missing.join(', ')}], unexpected [${extra.join(', ')}]`,
+    );
+  }
+}
+
+/**
+ * The develop chart-set lock for the deploy commit `xemaDeploySha`, whose frozen
+ * checkout is `deployDir`. `readRoster(deployDir)` returns `{indexVersion, members}`;
+ * `client` is the chart registry client the release resolver uses.
+ */
+export async function resolveDevelopChartSet({ xemaDeploySha, deployDir = deployRoot(), readRoster = readDevelopChartRoster, client }) {
+  if (!COMMIT_PATTERN.test(xemaDeploySha ?? '')) {
+    throw new RefusalError(`the deploy checkout SHA is not a 40-hex commit: ${JSON.stringify(xemaDeploySha)}`);
+  }
+  const publisher = deployPublisher();
+  const infraPublisher = committedInfraPublisher();
+  const { indexVersion, members } = readRoster(deployDir);
+  const registry = client ?? chartRegistryClient();
+  const label = `${publisher.index}@${indexVersion}`;
+  const { roster, indexDigest } = await published(
+    () => indexRosterAndDigest(registry, publisher.index, indexVersion),
+    `the chart-set index ${label}`,
+    { publisher, xemaDeploySha },
+  );
+  assertIndexIsRoster(roster, members, label);
+  const lookup = registryChartDigest(registry);
+  const charts = await sealRoster(
+    roster,
+    (name, version) => published(() => lookup(name, version), `chart ${name}:${version}`, { publisher, xemaDeploySha }),
+    label,
+  );
+  const lock = buildLock(
+    { [publisher.index]: indexVersion },
+    { [publisher.index]: charts },
+    { [publisher.index]: indexDigest },
+    [publisher],
+  );
+  lock.publishers.push(infraPublisher);
+  return assertRosteredChartSetLock(lock, CHART_SET_LOCK_FILE);
+}

package/edition/develop-current-resolution.mjs

@@ -0,0 +1,29 @@
+// develop-current-resolution — the members that keep the CURRENT develop resolution instead of a signed build record.
+//
+// A member keeps its current resolution (develop HEAD freeze plus the registry probe) only when the data root declares
+// it: `currentResolution: "<ticket>"` on its `firstPartySources` entry in edition-workspace.json, the ticket that
+// removes the exception (today xema-docs, whose develop lane is unsigned by owner decision and which leaves the
+// edition). It is a declared exception, not a fallback: absent means none, and every other member without a record
+// still refuses.
+
+import { compareStrings } from './lib.mjs';
+
+/** Whether a member (or its `firstPartySources` entry) keeps its current resolution. */
+export const keepsCurrentResolution = (member) => Object.hasOwn(member, 'currentResolution');
+
+/** The graph `members` that declare a current resolution, repo -> ticket, keys sorted: what a selection records. */
+export function currentResolutionOf(members) {
+  return Object.fromEntries(
+    members
+      .filter(keepsCurrentResolution)
+      .map(({ repo, currentResolution }) => [repo, currentResolution])
+      .sort(([a], [b]) => compareStrings(a, b)),
+  );
+}
+
+/** Why a selection's `currentResolution` (absent = none) is not exactly the one the graph `members` declare; null when it is. */
+export function currentResolutionProblem(declared, members) {
+  const expected = currentResolutionOf(members);
+  if (JSON.stringify(declared ?? {}) === JSON.stringify(expected)) {return null;}
+  return `"currentResolution" is ${JSON.stringify(declared)}, not ${JSON.stringify(expected)}, the members the data root declares keep their current resolution`;
+}

package/edition/develop-edition-invariants.mjs

@@ -0,0 +1,142 @@
+// develop-edition-invariants — the plane invariants a DEVELOP candidate asserts
+// itself, against the develop graph it froze: the capability-domain
+// reservation table and biome confinement.
+//
+// On develop these live ONLY here. `xema-edition check-authored` reads no
+// resolved edition, and `xema-edition check` (the release path) grades the
+// same two invariants over the committed locks.
+//
+// RESERVATION. Ownership is a property of the platform, not of what an edition
+// preloads (see `buildCapabilityDomainOwners`): every edition carries the table
+// built from the FULL index. The release check proves it by comparing the
+// committed locks with each other. A single candidate proves the same thing
+// alone: its table must be exactly the one the frozen graph's full biome index
+// builds, so any two candidates over one graph carry the identical table. It
+// must also be non-empty (an empty table makes nothing first-party), and the
+// kernel's reader must accept it (one owner per domain, valid domains).
+//
+// CONFINEMENT. The data root's `confinedBiomes` name biomes whose contents must
+// not reach an unadmitted installation. The candidate is one graded edition:
+// a declaration naming a biome the frozen index does not carry guards nothing
+// and is refused; shipping a confined biome without an admission is refused; an
+// admission of this edition for a biome it does not ship is a stale permission
+// and is refused; a declaration without a substantive consequence is refused.
+
+import { RefusalError } from './collected-refusals.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { buildCapabilityDomainOwners, serializeJson } from './lib.mjs';
+
+/** Why a develop candidate was refused. */
+export const DevelopEditionInvariantReason = Object.freeze({
+  RESERVATION_TABLE_EMPTY: 'reservation-table-empty',
+  RESERVATION_TABLE_NOT_PLATFORM_TABLE: 'reservation-table-not-platform-table',
+  RESERVATION_TABLE_REFUSED_BY_KERNEL: 'reservation-table-refused-by-kernel',
+  CONFINED_BIOME_UNKNOWN: 'confined-biome-unknown',
+  CONFINED_BIOME_UNADMITTED: 'confined-biome-unadmitted',
+  CONFINEMENT_ADMISSION_STALE: 'confinement-admission-stale',
+  CONFINEMENT_CONSEQUENCE_MISSING: 'confinement-consequence-missing',
+});
+
+/** The shortest `consequence` that can name what a confinement protects. */
+const MIN_CONSEQUENCE_LENGTH = 40;
+
+/** A develop candidate broke a plane invariant. `violations` carries every one, each with its reason. */
+export class DevelopEditionInvariantError extends RefusalError {
+  /** @param {string} id @param {{ reason: string, detail: string }[]} violations */
+  constructor(id, violations) {
+    super(
+      `develop edition "${id}" breaks ${violations.length} plane invariant(s):\n` +
+        violations.map(({ reason, detail }) => `  - [${reason}] ${detail}`).join('\n'),
+    );
+    this.name = 'DevelopEditionInvariantError';
+    this.distributionId = id;
+    this.violations = violations;
+  }
+}
+
+/**
+ * The reservation violations of `lock`, whose graph's full biome index is
+ * `biomeIndex`. `resolveFirstPartyCapabilityDomains` is the kernel's reader.
+ */
+export function reservationViolations({ lock, biomeIndex, resolveFirstPartyCapabilityDomains }) {
+  const R = DevelopEditionInvariantReason;
+  const table = lock.capabilityDomainOwners;
+  if (!Array.isArray(table) || table.length === 0) {
+    return [{
+      reason: R.RESERVATION_TABLE_EMPTY,
+      detail: 'capabilityDomainOwners is missing or empty: an empty reservation table makes NOTHING first-party (fail-open)',
+    }];
+  }
+  const violations = [];
+  try {
+    resolveFirstPartyCapabilityDomains(lock);
+  } catch (err) {
+    violations.push({ reason: R.RESERVATION_TABLE_REFUSED_BY_KERNEL, detail: err.message });
+  }
+  if (serializeJson(table) !== serializeJson(buildCapabilityDomainOwners(biomeIndex))) {
+    violations.push({
+      reason: R.RESERVATION_TABLE_NOT_PLATFORM_TABLE,
+      detail:
+        'capabilityDomainOwners is not the table the frozen graph\'s full biome index builds. Ownership must not vary ' +
+        'by edition, or a trimmed edition leaves domains org-bindable',
+    });
+  }
+  return violations;
+}
+
+/**
+ * The confinement violations of edition `id` shipping `lock`, under the data
+ * root's `declarations`, with `knownBiomeIds` the frozen index's biome ids.
+ */
+export function confinementViolations({ id, lock, declarations, knownBiomeIds }) {
+  const R = DevelopEditionInvariantReason;
+  const shipped = new Set(lock.biomes.map((biome) => biome.id));
+  const violations = [];
+  for (const decl of declarations) {
+    if (typeof decl.consequence !== 'string' || decl.consequence.trim().length < MIN_CONSEQUENCE_LENGTH) {
+      violations.push({
+        reason: R.CONFINEMENT_CONSEQUENCE_MISSING,
+        detail: `confinement declaration "${decl.biomeId}" carries no substantive \`consequence\`; a refusal would name a rule without naming what it protects`,
+      });
+    }
+    if (!knownBiomeIds.has(decl.biomeId)) {
+      violations.push({
+        reason: R.CONFINED_BIOME_UNKNOWN,
+        detail:
+          `confinement declaration names biome "${decl.biomeId}", which the frozen biome index does not carry: it would ` +
+          'guard nothing. Repoint it to the renamed biome, or delete it if the biome is gone',
+      });
+      continue;
+    }
+    const admitted = decl.admittedEditions.includes(id);
+    if (shipped.has(decl.biomeId) && !admitted) {
+      violations.push({
+        reason: R.CONFINED_BIOME_UNADMITTED,
+        detail:
+          `ships biome "${decl.biomeId}", which holds ${decl.holds}. That is a CONFINEMENT decision, not a packaging one: ` +
+          `${decl.consequence}. If intended, add "${id}" to its admittedEditions in edition-workspace.json in its own commit, naming who agreed`,
+      });
+    }
+    if (!shipped.has(decl.biomeId) && admitted) {
+      violations.push({
+        reason: R.CONFINEMENT_ADMISSION_STALE,
+        detail: `the admission "${decl.biomeId}" -> "${id}" suppresses NOTHING: the edition does not ship the biome. Delete it`,
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Assert both invariants on develop candidate `id`. Throws
+ * {@link DevelopEditionInvariantError} naming every violation; returns the
+ * counts it graded otherwise.
+ */
+export function assertDevelopEditionInvariants({ id, lock, biomeIndex, schemas, declarations = editionWorkspaceConfig().confinedBiomes ?? [] }) {
+  const violations = [
+    ...reservationViolations({ lock, biomeIndex, resolveFirstPartyCapabilityDomains: schemas.resolveFirstPartyCapabilityDomains }),
+    ...confinementViolations({ id, lock, declarations, knownBiomeIds: new Set(biomeIndex.map((entry) => entry.id)) }),
+  ];
+  if (violations.length > 0) {throw new DevelopEditionInvariantError(id, violations);}
+  return { reservedDomains: lock.capabilityDomainOwners.length, confinedBiomes: declarations.length };
+}