@xemahq/xema 0.26.0 → 0.28.0

package/edition/check-committed-image-evidence.mjs

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// IS THE COMMITTED EVIDENCE BUNDLE FOR THIS EXACT PRODUCER INPUT STILL USABLE?
+//
+//   node check-committed-image-evidence.mjs \
+//     --input <producer-input.json> \
+//     --repository-root <absolute-directory> \
+//     [--github-output <path>] [--now <epoch-millis>]
+//
+// WHY THIS EXISTS
+//
+//   Every producing workflow guarded its expensive signing step with
+//
+//       if [ -d "${EVIDENCE_DIR}" ]; then exists=true; fi
+//
+//   and then reported `::notice::… already produced; reusing it`. That step
+//   verified NOTHING about what is on disk — this repository's most-repeated
+//   defect, a check that reports green while executing nothing. Concretely it
+//   let three separate broken states read as "covered":
+//
+//     * a bundle from a PREVIOUS, half-committed run (statement present,
+//       bundle truncated, descriptor index absent);
+//     * a bundle whose statement describes a DIFFERENT subject or a different
+//       source coordinate than the input about to be signed;
+//     * an EXPIRED bundle. Producer evidence carries a hard `expiresAt` that
+//       `image-evidence.mjs assertTimeWindow` enforces at verification, and the
+//       directory-exists guard made expiry UNRECOVERABLE: every re-run of the
+//       producing workflow saw the directory, skipped production, and the
+//       distribution simply stayed undeliverable with a green CI.
+//
+//   So the reuse decision is made HERE, by actually reading the bundle:
+//   reusable ⇔ well-formed AND bound to this exact input AND unexpired with
+//   enough remaining life to be worth keeping. Anything else re-produces.
+//
+// WHAT "BOUND TO THIS INPUT" MEANS (each is a real substitution this catches)
+//
+//   * the descriptor index names exactly the input's subject set;
+//   * every statement parses under the kernel's own
+//     `parseImageProducerStatement` at the input's contract authority;
+//   * statement digests match the descriptor, and the DSSE payload inside the
+//     bundle is byte-identical to the statement (`validateProducedBundle`);
+//   * the statement's artifact digest is the digest this run is evidencing —
+//     the directory is NAMED after that digest, so a mismatch means the tree
+//     was hand-edited or the naming convention moved;
+//   * source identity (repo/path/commit/tree hash) equals the input's.
+//
+// EXIT CODES — the distinction is deliberate
+//
+//   0  a verdict was reached: `reusable=true|false` on stdout / --github-output.
+//      An unusable or absent bundle is a NORMAL outcome; it means "produce".
+//   1  no verdict could be reached: bad arguments, an unreadable repository
+//      root, kernel schemas that will not load. A tool that cannot decide must
+//      never answer "reuse".
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { appendFileSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  dataRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import {
+  evidenceDirectoryForDigest,
+  sha256Digest,
+} from './image-evidence.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import {
+  assertProducerInput,
+  buildImageSourceStatements,
+  readPinnedContractAuthority,
+  validateProducedBundle,
+} from './produce-image-source-evidence.mjs';
+import { producerStatementMatchesInput } from './producer-evidence-bundle.mjs';
+
+/**
+ * Remaining life below which a technically-valid bundle is re-produced anyway.
+ *
+ * A bundle that expires in ten minutes is not reusable in any meaningful sense:
+ * the release, delivery or appliance install that will read it happens after
+ * this workflow, not during it. Refusing to hand one forward is what makes the
+ * refresh path actually reachable instead of theoretically reachable.
+ *
+ * Six hours is the smallest window that survives a full re-run of the slowest
+ * producing lane (emulated arm64 build + merge + attest) plus the release step
+ * that consumes the result, with room to spare.
+ */
+export const MIN_REMAINING_TTL_SECONDS = 6 * 60 * 60;
+
+const MAX_EVIDENCE_FILE_BYTES = 4 * 1024 * 1024;
+
+function readBoundedFile(path) {
+  const stat = statSync(path);
+  if (!stat.isFile()) {
+    throw new Error(`${path} is not a regular file`);
+  }
+  if (stat.size > MAX_EVIDENCE_FILE_BYTES) {
+    throw new Error(
+      `${path} is ${stat.size} bytes, over the ${MAX_EVIDENCE_FILE_BYTES}-byte evidence file bound`,
+    );
+  }
+  return readFileSync(path);
+}
+
+/** A descriptor path is repository-relative, without traversal or absolutes. */
+function assertContainedRelativePath(value, label) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.startsWith('/') ||
+    value
+      .split('/')
+      .some((segment) => segment === '' || segment === '.' || segment === '..')
+  ) {
+    throw new Error(`${label} is not a contained repository-relative path`);
+  }
+  return value;
+}
+
+/**
+ * The reuse verdict for one producer input.
+ *
+ * @returns {{ evidenceDirectory: string, reusable: boolean, reason: string }}
+ */
+export async function assessCommittedEvidence({
+  input,
+  repositoryRoot,
+  schemas,
+  expectedContractAuthority,
+  now = Date.now(),
+}) {
+  // The input is validated FIRST and unconditionally: a verdict about the
+  // committed tree is meaningless if the thing it is compared against is not
+  // itself a well-formed producer input.
+  assertProducerInput(input, expectedContractAuthority);
+  const subjects = input.subjects;
+  const digests = new Set(subjects.map((subject) => subject.manifestDigest));
+  if (digests.size !== 1) {
+    throw new Error(
+      'a producer input must evidence exactly one manifest digest; the ' +
+        `committed evidence tree is keyed by it (got ${[...digests].join(', ')})`,
+    );
+  }
+  const evidenceDirectory = evidenceDirectoryForDigest([...digests][0]);
+  const absoluteDirectory = join(repositoryRoot, evidenceDirectory);
+
+  const unusable = (reason) => ({ evidenceDirectory, reusable: false, reason });
+
+  let stat;
+  try {
+    stat = statSync(absoluteDirectory);
+  } catch {
+    return unusable('no evidence has been committed for this digest yet');
+  }
+  if (!stat.isDirectory()) {
+    return unusable(`${evidenceDirectory} exists but is not a directory`);
+  }
+
+  let indexDocument;
+  try {
+    indexDocument = JSON.parse(
+      readBoundedFile(join(absoluteDirectory, 'producer-evidence.json')).toString(
+        'utf8',
+      ),
+    );
+  } catch (error) {
+    return unusable(
+      `producer-evidence.json is missing or unreadable: ${error.message}`,
+    );
+  }
+  if (
+    indexDocument?.schemaVersion !== 1 ||
+    !Array.isArray(indexDocument.producerEvidence)
+  ) {
+    return unusable('producer-evidence.json is not a schemaVersion 1 index');
+  }
+
+  // The expected statements are REBUILT from the input, so the comparison is
+  // against exactly what a fresh production would sign — not against a
+  // hand-written expectation that could drift from the producer.
+  let expectedStatements;
+  try {
+    expectedStatements = buildImageSourceStatements(input, schemas, expectedContractAuthority);
+  } catch (error) {
+    throw new Error(
+      `the producer input does not build a valid statement set: ${error.message}`,
+    );
+  }
+  const expectedByKey = new Map(
+    expectedStatements.map((statement) => [
+      `${statement.predicate.source.kind}:${statement.predicate.source.id}`,
+      statement,
+    ]),
+  );
+
+  const seen = new Set();
+  for (const entry of indexDocument.producerEvidence) {
+    if (entry === null || typeof entry !== 'object') {
+      return unusable('producer-evidence.json carries a non-object entry');
+    }
+    const key = `${entry.subjectKind}:${entry.subjectId}`;
+    if (seen.has(key)) {
+      return unusable(`producer-evidence.json duplicates subject ${key}`);
+    }
+    seen.add(key);
+    const expected = expectedByKey.get(key);
+    if (expected === undefined) {
+      return unusable(
+        `committed evidence carries subject ${key}, which this input does not evidence`,
+      );
+    }
+    const descriptor = entry.evidence;
+    if (descriptor === null || typeof descriptor !== 'object') {
+      return unusable(`subject ${key} has no evidence descriptor`);
+    }
+    let statementBytes;
+    let bundleBytes;
+    try {
+      statementBytes = readBoundedFile(
+        join(
+          absoluteDirectory,
+          assertContainedRelativePath(
+            descriptor.statementPath,
+            `subject ${key} statementPath`,
+          ),
+        ),
+      );
+      bundleBytes = readBoundedFile(
+        join(
+          absoluteDirectory,
+          assertContainedRelativePath(
+            descriptor.bundlePath,
+            `subject ${key} bundlePath`,
+          ),
+        ),
+      );
+    } catch (error) {
+      return unusable(`subject ${key} artifacts are unreadable: ${error.message}`);
+    }
+    if (
+      sha256Digest(statementBytes) !== descriptor.statementDigest ||
+      sha256Digest(bundleBytes) !== descriptor.bundleDigest
+    ) {
+      return unusable(
+        `subject ${key} artifacts do not match the digests producer-evidence.json records`,
+      );
+    }
+    try {
+      validateProducedBundle(statementBytes, bundleBytes);
+    } catch (error) {
+      return unusable(`subject ${key} bundle is malformed: ${error.message}`);
+    }
+    let committed;
+    try {
+      committed = schemas.parseImageProducerStatement(
+        JSON.parse(statementBytes.toString('utf8')),
+      );
+    } catch (error) {
+      return unusable(
+        `subject ${key} statement does not parse under the kernel schema: ${error.message}`,
+      );
+    }
+    // producerRun is deliberately fresh on every execution (run id, attempt,
+    // nonce and validity window). Requiring byte equality with a freshly built
+    // statement made every retry look stale and caused the evidence commit
+    // storm. Compare the immutable authority/source/build/artifact binding;
+    // validate the existing run's own signature and lifetime independently.
+    if (!producerStatementMatchesInput(committed, expected)) {
+      return unusable(
+        `subject ${key} committed statement is not bound to this producer input ` +
+          '(authority, source, build, artifact or platform set changed)',
+      );
+    }
+    const expiresAt = Date.parse(committed.predicate.producerRun.expiresAt);
+    if (!Number.isFinite(expiresAt)) {
+      return unusable(`subject ${key} statement has an unreadable expiresAt`);
+    }
+    const remainingSeconds = Math.floor((expiresAt - now) / 1000);
+    if (remainingSeconds <= 0) {
+      return unusable(
+        `subject ${key} evidence EXPIRED at ${committed.predicate.producerRun.expiresAt} — ` +
+          'it can never verify again and must be re-produced',
+      );
+    }
+    if (remainingSeconds < MIN_REMAINING_TTL_SECONDS) {
+      return unusable(
+        `subject ${key} evidence expires in ${remainingSeconds}s, under the ` +
+          `${MIN_REMAINING_TTL_SECONDS}s reuse floor — refreshing it now`,
+      );
+    }
+  }
+
+  const missing = [...expectedByKey.keys()].filter((key) => !seen.has(key));
+  if (missing.length > 0) {
+    return unusable(
+      `committed evidence omits subject(s) ${missing.join(', ')} that this input evidences`,
+    );
+  }
+
+  return {
+    evidenceDirectory,
+    reusable: true,
+    reason:
+      `verified ${seen.size} committed subject bundle(s): well-formed, bound to ` +
+      'this exact producer input, and unexpired',
+  };
+}
+
+function requireValue(flags, name) {
+  const value = flags.get(name);
+  if (value === undefined) {
+    throw new Error(`--${name} is required`);
+  }
+  return value;
+}
+
+async function main() {
+  const args = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
+    WorkspaceRoot.Data,
+    WorkspaceRoot.Kernel,
+  ]);
+  const flags = new Map();
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    if (!flag.startsWith('--')) {
+      throw new Error(`unexpected argument "${flag}"`);
+    }
+    const name = flag.slice(2);
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new Error(`--${name} requires a value`);
+    }
+    if (flags.has(name)) {
+      throw new Error(`--${name} was given twice`);
+    }
+    flags.set(name, value);
+  }
+  for (const name of flags.keys()) {
+    if (!['input', 'repository-root', 'github-output', 'now'].includes(name)) {
+      throw new Error(`unknown option "--${name}"`);
+    }
+  }
+  const repositoryRoot = resolve(requireValue(flags, 'repository-root'));
+  if (!isAbsolute(repositoryRoot) || !statSync(repositoryRoot).isDirectory()) {
+    throw new Error('--repository-root must be an absolute directory');
+  }
+  const input = JSON.parse(readFileSync(resolve(requireValue(flags, 'input')), 'utf8'));
+  const now = flags.has('now') ? Number(flags.get('now')) : Date.now();
+  if (!Number.isSafeInteger(now) || now <= 0) {
+    throw new Error('--now must be a positive epoch-millisecond integer');
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  const verdict = await assessCommittedEvidence({
+    input,
+    repositoryRoot,
+    schemas,
+    expectedContractAuthority: readPinnedContractAuthority({ dataRoot: dataRoot(), schemas }),
+    now,
+  });
+  const line = verdict.reusable
+    ? `[check-committed-image-evidence] REUSE ${verdict.evidenceDirectory}: ${verdict.reason}`
+    : `[check-committed-image-evidence] PRODUCE ${verdict.evidenceDirectory}: ${verdict.reason}`;
+  console.log(line);
+  const githubOutput = flags.get('github-output');
+  if (githubOutput !== undefined) {
+    appendFileSync(
+      githubOutput,
+      `reusable=${verdict.reusable}\n` +
+        `evidence-directory=${verdict.evidenceDirectory}\n` +
+        `reason=${verdict.reason.replaceAll('\n', ' ')}\n`,
+      'utf8',
+    );
+  }
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[check-committed-image-evidence] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/edition/checkout-indexed-source-repositories.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, runtimeImageSourceIndexPath, sourcesRoot } from './edition-workspace.mjs';
+import { gitAuthEnv } from './git-source-auth.mjs';
+import { applyPinSource, snapshotPinSource } from './pin-source.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+const REPO_PATH = /^(repos|submodules)\/([a-z0-9][a-z0-9-]*)$/;
+const SHA = /^[a-f0-9]{40}$/;
+
+export function sourceCheckoutPlan(index, { sourceRepositoryUrlPrefix }) {
+  if (!Array.isArray(index?.repositoryPins) || index.repositoryPins.length === 0) {
+    throw new Error('runtime image source index declares no repositoryPins');
+  }
+  const seen = new Set();
+  return index.repositoryPins.map((pin) => {
+    const match = REPO_PATH.exec(String(pin?.repo ?? ''));
+    if (!match) {throw new Error(`invalid repository checkout path ${JSON.stringify(pin?.repo)}`);}
+    if (seen.has(pin.repo)) {throw new Error(`duplicate repository pin ${pin.repo}`);}
+    seen.add(pin.repo);
+    const expectedUrl = `${sourceRepositoryUrlPrefix}${match[2]}.git`;
+    const suffixlessExpectedUrl = expectedUrl.slice(0, -4);
+    if (pin.repositoryUrl !== expectedUrl && pin.repositoryUrl !== suffixlessExpectedUrl) {
+      throw new Error(
+        `${pin.repo} repositoryUrl must be ${expectedUrl} (the equivalent suffixless GitHub URL is also accepted); got ${pin.repositoryUrl}`,
+      );
+    }
+    if (!SHA.test(String(pin.sourceCommit ?? ''))) {
+      throw new Error(`${pin.repo} sourceCommit is not exact lowercase 40-hex`);
+    }
+    return Object.freeze({
+      repo: pin.repo,
+      repositoryUrl: pin.repositoryUrl,
+      sourceCommit: pin.sourceCommit,
+    });
+  });
+}
+
+function git(args, env) {
+  execFileSync('git', args, { env, stdio: 'inherit' });
+}
+
+export function checkoutIndexedSources({ workspaceRoot, token, index }) {
+  if (!workspaceRoot) {throw new Error('workspaceRoot is required');}
+  if (!token) {throw new Error('EVIDENCE_REPOSITORIES_TOKEN is required');}
+  const workspace = editionWorkspaceConfig();
+  const env = gitAuthEnv(workspace.sourceRepositoryUrlPrefix, workspace.sourceAuthUsername, token);
+  const plan = sourceCheckoutPlan(index, workspace);
+  for (const entry of plan) {
+    const target = resolve(workspaceRoot, entry.repo);
+    if (existsSync(target)) {
+      throw new Error(`${entry.repo} target already exists; refusing to reuse an unverified checkout`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    git(['init', '--quiet', target], env);
+    git(['-C', target, 'remote', 'add', 'origin', entry.repositoryUrl], env);
+    git(['-C', target, 'fetch', '--quiet', '--depth=1', 'origin', entry.sourceCommit], env);
+    git(['-C', target, 'checkout', '--quiet', '--detach', entry.sourceCommit], env);
+    const actual = execFileSync('git', ['-C', target, 'rev-parse', 'HEAD'], {
+      env,
+      encoding: 'utf8',
+    }).trim();
+    if (actual !== entry.sourceCommit) {
+      throw new Error(`${entry.repo} resolved ${actual}, expected ${entry.sourceCommit}`);
+    }
+    console.log(`[source-checkout] ${entry.repo} @ ${entry.sourceCommit}`);
+  }
+  return plan.length;
+}
+
+const SNAPSHOT_PINS_FLAG = '--snapshot-pins';
+
+/**
+ * `--snapshot-pins <file>` is the only argument: with it, the plan is the
+ * committed index applied to that snapshot (the develop edition's frozen pins);
+ * without it, the committed index untouched.
+ */
+export function indexForCheckout(committedIndex, argv) {
+  if (argv.length === 0) {return committedIndex;}
+  if (argv[0] !== SNAPSHOT_PINS_FLAG || argv.length !== 2 || argv[1].startsWith('--')) {
+    throw new Error(`usage: checkout-indexed-source-repositories.mjs [${SNAPSHOT_PINS_FLAG} <pins.json>]`);
+  }
+  return applyPinSource(committedIndex, snapshotPinSource(readStrictJsonFile(argv[1])));
+}
+
+if (isEntryModule(import.meta.url)) {
+  try {
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources]);
+    const index = indexForCheckout(JSON.parse(readFileSync(runtimeImageSourceIndexPath(), 'utf8')), process.argv.slice(2));
+    const count = checkoutIndexedSources({
+      workspaceRoot: sourcesRoot(),
+      token: process.env.EVIDENCE_REPOSITORIES_TOKEN,
+      index,
+    });
+    console.log(`[source-checkout] materialized ${count} indexed repositories at exact commits`);
+  } catch (error) {
+    console.error(`[source-checkout] ${error.message}`);
+    process.exit(1);
+  }
+}

package/edition/comment-blanker.mjs

@@ -0,0 +1,75 @@
+// Blank comments before asking a source file "what does this file DO?".
+//
+// A structural assertion that greps RAW source text cannot tell a CALL from a
+// MENTION, so it can be satisfied by — or tripped by — the scanned file's own
+// prose. That is not a hypothetical here: the call sites this repository
+// asserts on carry twenty-line docblocks explaining the very invariant being
+// asserted, so a raw `includes()` passes on a file whose call has been deleted
+// and whose comment survives. It is the mutation an ordinary mutation test
+// misses, because the usual mutation removes the code and its comment
+// together.
+//
+// SHARED BECAUSE THERE ARE NOW TWO CONSUMERS, and a second private copy is
+// what the fleet's own rule forbids: `seal-image-digests.test.mjs` (the
+// fleet-finality call) and `editions-root-platform-verification.test.mjs` (the
+// two `verifyDistributionPlatforms` call sites). Both previously would have
+// needed the same fourteen lines.
+//
+// DELIBERATELY NARROW: `/* */` blocks, and `//` only where it STARTS a line. A
+// trailing `//` is left alone because `'file://'` occurs in executable code in
+// these very files, and blanking it would delete a real line. A line that
+// BEGINS with `//` is unambiguously a comment.
+//
+// LINE COUNT IS PRESERVED — every blanked character becomes a space rather
+// than being dropped — so a caller may still report a line number derived from
+// a match without it silently shifting.
+//
+// It is NOT a parser and must not grow into one: a `//` inside a string
+// literal at the start of a line would be blanked wrongly. No such line exists
+// in either consumer, and each consumer's two-sided control is what proves the
+// blanker discriminated on ITS file rather than trusting this note.
+export function blankComments(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//gu, (match) => match.replace(/[^\n]/gu, ' '))
+    .replace(/^[ \t]*\/\/.*$/gmu, (match) => match.replace(/[^\n]/gu, ' '));
+}
+
+// ── AND THE TRAILING `//`, FOR THE ONE CALLER THAT CANNOT LEAVE IT ──────────
+//
+// `blankComments` above deliberately leaves a trailing `//` alone, and the
+// reason it gives is exact: `'file://'` occurs in executable code in its two
+// consumers, and blanking from there would delete a real line.
+//
+// `platform-lock-readability.mjs` asks a question those two do not — "does
+// this repository CALL the lock parser?" — over source it did not write, in
+// seven other repositories. There, prose naming the parser is the NORM rather
+// than the exception, and it is not hypothetical: measured 2026-09-27 at the
+// committed pins, `submodules/xema-host-web`'s `src/lib/nav-registry.ts:1135`
+// and `repos/xema-cultivars`'s `decision-api.client.ts:53` each name
+// `distribution.lock.json` in a comment and neither parses one.
+//
+// So this variant blanks a `//` to end of line UNLESS it is immediately
+// preceded by `:`. That single guard is what keeps `'file://'`,
+// `'https://…'` and every other scheme intact, which is the whole objection
+// the narrow version was written around.
+//
+// THE FAILURE DIRECTION IS THE POINT, and it decides why the guard is this
+// shape rather than a smarter one. Under-blanking makes a MENTION read as a
+// call — the caller then grades a repository it need not, which is merely
+// over-strict. OVER-blanking makes a CALL disappear — the caller then skips a
+// real reader, which is the 2026-09-17 incident itself. A real call cannot
+// follow a `//` on a line that is not a comment except inside a string,
+// template or regex, and none of those is a call; so the only way this hides
+// one is a call interpolated after a literal `//` inside a template on the
+// same line. Its caller reports RAW-vs-EXECUTABLE file counts for exactly that
+// reason: an over-blank shows up as a difference a human can see, rather than
+// as a silently smaller corpus.
+//
+// It is NOT a parser, for the same reason its sibling is not, and the guard
+// above is the whole of its cleverness.
+export function blankAllComments(source) {
+  return blankComments(source).replace(
+    /(^|[^:])\/\/.*$/gmu,
+    (match, before) => before + ' '.repeat(match.length - before.length),
+  );
+}

package/edition/connector-source-authority.mjs

@@ -0,0 +1,60 @@
+import { editionWorkspaceConfig } from './edition-config.mjs';
+
+// The connector repository, its production connector biomes and the ids that are
+// deliberately not production are the data root's (`connectorSources` in
+// edition-workspace.json); this module is the rule over them.
+
+// A data root with no connector repository declares no `connectorSources`:
+// there is then nothing to exclude and nothing to vendor, which is a stated
+// absence of the thing, not a skipped check. `undefined` below means exactly that.
+const connectorSources = () => editionWorkspaceConfig().connectorSources;
+
+/** The production connector biomes: id, repo, repo-relative path and aggregate path. */
+export const productionConnectorSourceBindings = () => {
+  const sources = connectorSources();
+  if (sources === undefined) {return [];}
+  const { repository, bindings } = sources;
+  return bindings.map(({ id, path }) =>
+    Object.freeze({ id, repo: repository, repoPath: path, path: `${repository}/${path}` }),
+  );
+};
+
+/** The cross-repo build inputs that vendor each production connector into the consuming image. */
+export const connectorCrossRepoBuildInputs = () => {
+  const sources = connectorSources();
+  if (sources === undefined) {return [];}
+  const { buildInput } = sources;
+  return productionConnectorSourceBindings().map(({ id, repo, repoPath }) => ({
+    consumerRepo: buildInput.consumerRepo,
+    consumerService: buildInput.consumerService,
+    sourceRepo: repo,
+    sourcePath: repoPath,
+    destinationPath: `${buildInput.destinationRoot}/${id}`,
+  }));
+};
+
+/**
+ * Decide whether a discovered manifest is an authoritative production source.
+ *
+ * The old community connector trees are intentionally ignored, not used as a
+ * fallback. The connector repository's `examples/` tree is also never a
+ * production source, even when an example carries a valid biome manifest.
+ */
+export function isAuthoritativeProductionBiomeSource({ id, repo, path }) {
+  const sources = connectorSources();
+  if (sources === undefined) {return true;}
+  const { nonProductionIds, repository } = sources;
+  if (nonProductionIds.includes(id)) {return false;}
+
+  const binding = productionConnectorSourceBindings().find((candidate) => candidate.id === id);
+  if (binding) {return repo === binding.repo && path === binding.path;}
+
+  if (repo !== repository) {return true;}
+  if (path.startsWith(`${repository}/examples/`)) {return false;}
+  if (path.startsWith(`${repository}/connectors/`)) {
+    throw new Error(
+      `${path}/xema-biome.json declares unrecognized production connector id "${String(id)}"`,
+    );
+  }
+  return false;
+}