@xemahq/xema 0.59.1 → 0.60.1

package/edition/external-source-walk.mjs

@@ -1,485 +0,0 @@
-/**
- * The EDITION-SCOPED external source walk.
- *
- * A distribution may declare `sources[]` — external repositories holding biomes
- * that are not in the platform's own index. This module fetches one, PINS the
- * exact commit it read, projects its biomes into index entries, and STAMPS each
- * entry with the declaring source's name.
- *
- * ── THE STAMP IS THE WHOLE SECURITY PROPERTY ──
- *
- * `entrySourceAdmissible` (resolve-distribution.mjs) keys edition scoping on
- * `entry.source`, and ABSENT IS THE IDENTITY: an unstamped entry is
- * platform-default and admissible to EVERY edition. That is deliberate — it is
- * what keeps the nine committed locks byte-identical — so an unstamped entry
- * drawn from a customer repository is a DISCLOSURE, not a packaging slip: a
- * `{ tier: "platform" }` selector matches on tier and audience and never on
- * origin, so it would sweep one customer's private product into `oss` and
- * `cloud`. Measured before the fence existed, on this corpus: 5 of 9 editions.
- *
- * Every entry this module emits is therefore stamped in ONE place —
- * `stampEntry` below — and `walkDeclaredSources` asserts it before returning.
- * That assertion is not decoration: it is the last point at which an unstamped
- * entry can be caught before it reaches the shared index.
- *
- * ── WHY THIS IS A SIBLING OF `checkout-indexed-source-repositories.mjs` AND
- *    NOT A GENERALISATION OF IT ──
- *
- * That file looks like this fetcher and is not, in four ways, and the last one
- * is why generalising it would REMOVE a fence rather than widen one:
- *
- *   1. DIFFERENT PLANE. It materialises the repositories named by
- *      `runtime-image-source-index.json` so image SOURCE EVIDENCE can be
- *      produced. This walk resolves an EDITION. Neither needs the other.
- *   2. DIFFERENT COMMIT AUTHORITY. Its commit arrives already pinned, in the
- *      index (`pin.sourceCommit`); it only verifies. Here the commit is
- *      DERIVED, by resolving a declared ref at the remote — a different
- *      question with a different failure mode.
- *   3. DIFFERENT REUSE POSTURE. It refuses an existing target outright
- *      ("refusing to reuse an unverified checkout"), which is right for a
- *      one-shot CI materialisation and wrong here: `dist:resolve` and
- *      `dist:check` run repeatedly over many editions, so a checkout is reused
- *      and re-verified BY COMMIT instead.
- *   4. ITS FIRST-PARTY LOCK IS LOAD-BEARING WHERE IT SITS. It derives
- *      `<sourceRepositoryUrlPrefix><name>.git` and compares for EQUALITY, so
- *      an evidence pin cannot name a repository outside the vendor org. That is
- *      a real fence for the evidence plane. Widening it to admit a customer org
- *      would delete it for evidence at the same time — the same shape as
- *      widening `validateRepository` in `source-authority.mjs` to admit a path
- *      outside the aggregator. A customer's repository is not in the first-party organisation and
- *      must not have to be, so this walk carries its own URL from the
- *      declaration and never derives one.
- *
- * ── WHAT THIS MODULE DELIBERATELY DOES NOT DO ──
- *
- * It does not INTERPRET `source.imageRegistry` or `source.imageNamePrefix`; it
- * CARRIES them, and the two travel together because both are facts about WHERE
- * this source's artifacts are published rather than about where its source is
- * fetched. The declaration
- * is copied verbatim onto the lock's `LockedBiomeSource` and no image
- * coordinate is derived from it here, because deriving one is the image plane's
- * question and this is the source plane. `resolve-images.mjs` is the reader: a
- * source-stamped biome composes its refs under its own source's registry, and a
- * source that declares none is REFUSED there rather than falling back to the
- * vendor namespace. The kernel says why on the field itself: *"a plane that
- * needs one and finds it absent must REFUSE rather than substitute the
- * first-party registry, which would publish a customer's build into the vendor
- * org."*
- *
- * This paragraph said `resolve-images.mjs` "REFUSES a source-stamped biome"
- * flatly, and that was true only while reading the field was unimplemented. It
- * is corrected rather than deleted because the sentence it turned into is the
- * one that matters and is easy to lose: the refusal did not go away when the
- * reader landed — it NARROWED, to an external source that declares no registry
- * at all. A carrier that silently dropped the field would be the same defect
- * the `sources[]` refusal in resolve-distribution.mjs exists to prevent, one
- * plane over, which is why the copy is verbatim and the lock schema is
- * `.strict()`.
- */
-
-import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { readBiomeAuthorizationModuleAt } from './authorization-base.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import { cacheDir } from './edition-workspace.mjs';
-import { holdSource, withSourceGitEnv } from './git-source-auth.mjs';
-import {
-  BIOME_GENERATED_INDEX_FILENAME,
-  loadKernelBiomeContracts,
-  manifestToIndexEntry,
-  readGitJsonAtCommit,
-  readGitTextAtCommitOrNull,
-} from './lib.mjs';
-import { walkOciSources } from './third-party-source-walk.mjs';
-
-/** Where fetched sources are cached: a directory under the configured cache root. Never an input to a lock. */
-export const externalSourceCacheDir = () => join(cacheDir(), 'external-sources');
-
-const EXACT_COMMIT = /^[a-f0-9]{40}$/;
-
-/** The declared source kind that names a third-party pin instead of a git repository. */
-const OCI_SOURCE_KIND = 'oci';
-
-/**
- * Directory names never walked for biome manifests in an EXTERNAL source.
- *
- * This is deliberately a SEPARATE list from `lib.mjs`'s `SKIP_DIR_NAMES`, and
- * the separation is the point rather than an oversight. That one encodes the
- * VENDOR MONOREPO's layout — `templates` is `tooling/templates`,
- * `openapi-fixture` is an `xema-base` test convention — and those are facts
- * about this repository's neighbours, not facts about biome discovery. A
- * customer's repository has its own layout and must not be graded against the
- * vendor's; equally, a future vendor-layout skip must not silently start
- * excluding directories inside a customer's tree.
- *
- * What is left is the intersection that is true of any git repository: build
- * output and vendored dependencies are not authored biomes.
- */
-const EXTERNAL_SKIP_DIR_NAMES = new Set(['node_modules', '.git', 'dist']);
-
-function git(directory, args, env = process.env, exec = execFileSync) {
-  return exec('git', ['-C', directory, ...args], {
-    encoding: 'utf8',
-    env,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  }).trim();
-}
-
-/**
- * Resolve a declared ref to an exact commit AT THE REMOTE.
- *
- * A moving branch may DISCOVER an upgrade candidate; it must never be the
- * IDENTITY of a released member. This is the only place a ref becomes a commit,
- * and everything downstream — the checkout, the manifest reads, the lock —
- * carries the commit. `gitEnv` is the environment `withSourceGitEnv` computed for
- * this source; `exec` is the spawn seam.
- */
-function resolveRemoteCommit(source, gitEnv, exec = execFileSync) {
-  const ref = source.ref ?? 'HEAD';
-  // AN EXACT COMMIT IS ALREADY THE ANSWER, and it must not be sent to
-  // `ls-remote`, which matches REFS and would find nothing for a raw sha —
-  // reporting "resolves to nothing" for the one form that needs no resolving.
-  //
-  // This is the form a RELEASED edition should declare. A branch is DISCOVERY:
-  // measured on this repository during one session, `main` moved
-  // 92edf2cf -> ab87ee09 between two calls twenty minutes apart, so an edition
-  // declaring a branch re-pins on every resolve and its committed lock drifts
-  // whenever the source's owner pushes. The artifact stays deterministic
-  // either way — the lock records the commit, never the ref — but only an
-  // exact ref makes the RESOLVE reproducible.
-  if (EXACT_COMMIT.test(ref)) {return ref;}
-  let out;
-  try {
-    out = exec('git', ['ls-remote', '--exit-code', source.url, ref], {
-      encoding: 'utf8',
-      env: gitEnv,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    }).trim();
-  } catch (error) {
-    throw new Error(
-      `source "${source.name}": cannot resolve ref "${ref}" at ${source.url}. ` +
-        'Source resolution never falls back to another ref or another remote. ' +
-        `Underlying error: ${error.message}`,
-    );
-  }
-  const lines = out.split('\n').filter(Boolean);
-  if (lines.length === 0) {
-    throw new Error(
-      `source "${source.name}": ref "${ref}" resolves to nothing at ${source.url}`,
-    );
-  }
-  const commit = lines[0].split('\t')[0].trim();
-  if (!EXACT_COMMIT.test(commit)) {
-    throw new Error(
-      `source "${source.name}": ref "${ref}" resolved to "${commit}", which is not an ` +
-        'exact lowercase 40-hex commit',
-    );
-  }
-  return commit;
-}
-
-/** Fetch `commit` by id, depth 1, into the checkout at `directory` unless it already holds it. */
-function fetchCommitUnlessHeld(directory, commit, gitEnv, exec) {
-  const have = (() => {
-    try {
-      return git(directory, ['cat-file', '-e', `${commit}^{commit}`], gitEnv, exec) === '';
-    } catch {
-      return false;
-    }
-  })();
-  if (!have) {
-    exec(
-      'git',
-      ['-C', directory, 'fetch', '--quiet', '--depth=1', 'origin', commit],
-      { env: gitEnv, stdio: ['ignore', 'pipe', 'pipe'] },
-    );
-  }
-}
-
-/**
- * Fetch a declared git source and return the directory + the EXACT commit its
- * manifests will be read at.
- *
- * The checkout is reused across calls and re-verified BY COMMIT, because
- * `dist:check` resolves every edition in one process and a per-edition clone of
- * a customer repository would be both slow and pointless. `rev-parse HEAD` is
- * the authority for what was actually materialised — never the ref, and never
- * what we asked for.
- */
-export function materializeGitSource({
-  source,
-  cacheRoot = externalSourceCacheDir(),
-  env = process.env,
-  workspace = editionWorkspaceConfig(),
-  exec = execFileSync,
-}) {
-  return withSourceGitEnv(source, { workspace, env }, (gitEnv) => {
-    const commit = resolveRemoteCommit(source, gitEnv, exec);
-    const directory = join(cacheRoot, source.name);
-    if (!existsSync(join(directory, '.git'))) {
-      mkdirSync(directory, { recursive: true });
-      exec('git', ['init', '--quiet', directory], { env: gitEnv });
-      git(directory, ['remote', 'add', 'origin', source.url], gitEnv, exec);
-    } else {
-      // The cache is keyed by the DECLARED name, so a renamed or moved source
-      // reuses it: fetch from where the declaration says the source lives NOW.
-      git(directory, ['remote', 'set-url', 'origin', source.url], gitEnv, exec);
-    }
-    fetchCommitUnlessHeld(directory, commit, gitEnv, exec);
-    git(directory, ['checkout', '--quiet', '--detach', commit], gitEnv, exec);
-    return { directory, commit: pinExternalSourceCommit({ name: source.name, directory, commit }) };
-  });
-}
-
-/**
- * The EXTERNAL source authority: what commit was actually read.
- *
- * `source-authority.mjs` is the FIRST-PARTY authority and must not be widened
- * into this. Its `validateRepository` refuses any repository resolving outside
- * the aggregator, and that containment protects every first-party repository at
- * once — admitting one external path would remove it for all of them. Its
- * `published` mode also derives a commit from `refs/remotes/origin/main` plus
- * PUBLISHED IMAGE EVIDENCE, which a customer source cannot have and should not
- * need in order to resolve.
- *
- * So this is a second, NARROWER derivation with the same shape: the commit is
- * whatever the checkout is actually at. `LockedBiomeSource.commit` is the exact
- * 40-hex commit the manifest was read at, never the declared ref.
- */
-export function pinExternalSourceCommit({ name, directory, commit }) {
-  const head = git(directory, ['rev-parse', 'HEAD']);
-  if (!EXACT_COMMIT.test(head)) {
-    throw new Error(
-      `source "${name}": checkout at ${directory} reports HEAD "${head}", which is not an ` +
-        'exact lowercase 40-hex commit',
-    );
-  }
-  if (commit !== undefined && head !== commit) {
-    throw new Error(
-      `source "${name}": checkout at ${directory} is at ${head}, expected ${commit}`,
-    );
-  }
-  const dirty = git(directory, ['status', '--porcelain', '--untracked-files=no']);
-  if (dirty.length > 0) {
-    throw new Error(
-      `source "${name}": checkout at ${directory} has uncommitted changes. An external source ` +
-        'is pinned by commit, so a dirty checkout would lock a revision that exists nowhere.',
-    );
-  }
-  return head;
-}
-
-/**
- * Every biome manifest in an external checkout at an exact commit.
- *
- * Read from the COMMIT rather than the worktree, for the reason the first-party
- * walk reads from a commit: the manifest and its generated index must describe
- * the same revision, and a worktree read cannot promise that.
- */
-export function listExternalBiomeManifests({ source, directory, commit }) {
-  const raw = execFileSync(
-    'git',
-    ['-C', directory, 'ls-tree', '-r', '-z', '--name-only', commit],
-    { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 },
-  );
-  const found = [];
-  for (const repoPath of raw.split('\0').filter(Boolean)) {
-    if (!repoPath.endsWith(`/${'xema-biome.json'}`)) {continue;}
-    if (repoPath.split('/').some((seg) => EXTERNAL_SKIP_DIR_NAMES.has(seg))) {continue;}
-    const manifestDirectory = repoPath.slice(0, -'/xema-biome.json'.length);
-    const rel = `${source.name}/${repoPath}`;
-    const manifest = readGitJsonAtCommit(directory, repoPath, commit);
-    const indexRepoPath = `${manifestDirectory}/${BIOME_GENERATED_INDEX_FILENAME}`;
-    let generatedIndex;
-    try {
-      generatedIndex = readGitJsonAtCommit(directory, indexRepoPath, commit);
-    } catch (error) {
-      throw new Error(
-        `${rel}: ${BIOME_GENERATED_INDEX_FILENAME} is missing at ${commit}: ${error.message}. ` +
-          'Every biome carries a committed generated index beside its manifest — it is the ' +
-          'authority for which biomes this one requires, and it is read at the SAME commit so ' +
-          'it cannot describe a different revision of the biome than the one being locked.',
-      );
-    }
-    // The biome's authorization module, read at the SAME commit as the
-    // manifest and by the SAME reader the first-party index uses, so a
-    // source-walked biome contributes its module to the edition's
-    // authorization base exactly like a platform biome. Absent ⇒ no module.
-    const authorizationModule = readBiomeAuthorizationModuleAt(
-      manifestDirectory,
-      (repoRelativePath) => readGitTextAtCommitOrNull(directory, repoRelativePath, commit),
-      rel,
-    );
-    found.push({
-      raw: manifest,
-      generatedIndex,
-      rel,
-      ...(authorizationModule === null ? {} : { authorizationModule }),
-      // The LOGICAL source identity, not the physical repository. The URL is a
-      // source-management fact and lives in exactly one place, the lock's
-      // `LockedBiomeSource.url`; `repo` stays a stable handle so renaming the
-      // hosting repository does not move a biome's provenance.
-      repo: source.name,
-      path: `${source.name}/${manifestDirectory}`,
-    });
-  }
-  return found.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
-}
-
-/**
- * THE STAMP. One place, so there is one thing to audit and one thing to mutate
- * when proving the fence works.
- */
-function stampEntry(entry, sourceName) {
-  return { ...entry, source: sourceName };
-}
-
-/**
- * A biome drawn from a declared source is THIRD-PARTY, and its manifest cannot
- * say otherwise. `xema.trustTier` is the author's own statement; in the vendor's
- * graph the vendor is the author, so the index build reads it. Here the author
- * is whoever owns the declared repository, and a manifest that names the
- * vendor's origin would place itself in the vendor's trust domain by default.
- * The refusal is on this path and not in the manifest reader, which serves both.
- */
-function assertSourceWalkedOrigin(entry, sourceName) {
-  const { BiomeOrigin } = loadKernelBiomeContracts();
-  if (entry.origin !== BiomeOrigin.ThirdParty) {
-    throw new Error(
-      `source "${sourceName}": biome "${entry.id}" declares xema.trustTier "${entry.origin}". A biome drawn from a ` +
-        `declared source is "${BiomeOrigin.ThirdParty}" and cannot declare another origin: "${BiomeOrigin.FirstParty}" ` +
-        'is the vendor\'s, and is never self-declared by a source the edition names.',
-    );
-  }
-  return entry;
-}
-
-/**
- * The `LockedBiomeSource` record for a declared source, pinned to a commit.
- * Only the kernel's declared fields are carried, and `.strict()` on the lock
- * schema is what keeps that honest.
- */
-function lockedSourceRecord(source, commit) {
-  const record = {
-    kind: source.kind,
-    name: source.name,
-    url: source.url,
-    commit,
-  };
-  if (source.ref !== undefined) {record.ref = source.ref;}
-  if (source.imageRegistry !== undefined) {record.imageRegistry = source.imageRegistry;}
-  // `imageNamePrefix` IS DELIBERATELY NOT PERSISTED, and this is the producer
-  // fix for a defect that was previously repaired in the ARTIFACT.
-  //
-  // It is RESOLVER INPUT: `resolve-images.mjs` composes an image name from the
-  // DECLARED source (`<imageRegistry>/<imageNamePrefix><subject>`) and the lock
-  // then carries the fully-qualified `imageRef`, so the prefix is already spent
-  // by the time a lock exists. Measured across all 28 repositories with comment
-  // lines stripped: ZERO executable readers of `biomes[].source.imageNamePrefix`
-  // — xema-deploy's three mentions are two comments and two self-test fixtures
-  // (control, same probe: `imageRepository` returns 4 executable). Write-only.
-  //
-  // And carrying it is not merely useless, it is BREAKING. `@xemahq/contracts`'
-  // DistributionLockSchema is `.strict()` and only learned this key in 0.10.0,
-  // so any pinned image resolving `^0.9.x` REFUSES THE WHOLE LOCK at boot —
-  // `Unrecognized key: "imageNamePrefix"`, before Nest starts. That took
-  // a customer environment's three lock consumers down on 2026-09-17 and was fixed by
-  // removing the key from the SEALED LOCK, leaving this line to re-emit it on
-  // the next resolve. A workaround standing where a fix belongs removes the
-  // signal; this is the fix.
-  return record;
-}
-
-/**
- * Walk every declared source for one edition.
- *
- * Returns the stamped index entries and the `LockedBiomeSource` record per
- * source name. `workspace` (default: the configured data root) supplies the one source credential.
- * `materialize` is injectable so the contract suite can drive a
- * real local git repository instead of reaching the network — the walk under
- * test is then the real one, not a fixture of it.
- */
-export async function walkDeclaredSources({
-  sources = [],
-  materialize = materializeGitSource,
-  env = process.env,
-  workspace = undefined,
-  thirdParty = undefined,
-} = {}) {
-  const entries = [];
-  const sourceRecords = new Map();
-  const checkouts = new Map();
-  // Every source is held (kind, then credential and URL) before the first is materialised.
-  const heldWorkspace = sources.length === 0 ? undefined : (workspace ?? editionWorkspaceConfig());
-  for (const source of sources) {
-    if (source.kind === OCI_SOURCE_KIND) {continue;}
-    if (source.kind !== 'git') {
-      throw new Error(
-        `source "${source.name}" declares kind "${source.kind}", which this walk does not ` +
-          'resolve. The kernel\'s LockedBiomeSourceSchema can only record a GIT source ' +
-          '(kind is z.literal(Git)), so an npm source has nowhere to be pinned in the ' +
-          'lock — resolving it would produce an edition whose members cannot be traced to a ' +
-          'revision. Refusing rather than resolving. (An oci source is a third-party pin: it ' +
-          'is held to the data root\'s third-party-source-pins.json and records no lock source.)',
-      );
-    }
-    holdSource(source, heldWorkspace, env);
-  }
-  const ociSources = sources.filter((source) => source.kind === OCI_SOURCE_KIND);
-  if (ociSources.length > 0) {
-    for (const { source, entry } of await walkOciSources(ociSources, { env, ...(thirdParty === undefined ? {} : { thirdParty }) })) {
-      entries.push(stampEntry(assertSourceWalkedOrigin(entry, source.name), source.name));
-    }
-  }
-  for (const source of sources.filter((candidate) => candidate.kind !== OCI_SOURCE_KIND)) {
-    const { directory, commit } = materialize({ source, env, workspace: heldWorkspace });
-    if (!EXACT_COMMIT.test(String(commit))) {
-      throw new Error(
-        `source "${source.name}": walk produced commit "${commit}", which is not exact 40-hex`,
-      );
-    }
-    const manifests = listExternalBiomeManifests({ source, directory, commit });
-    if (manifests.length === 0) {
-      throw new Error(
-        `source "${source.name}" at ${commit} carries no biome manifests. A declared source ` +
-          'that contributes nothing is a broken declaration, not an empty one: the edition ' +
-          'naming it would lock without the biomes the declaration was for.',
-      );
-    }
-    for (const manifest of manifests) {
-      entries.push(stampEntry(assertSourceWalkedOrigin(await manifestToIndexEntry(manifest), source.name), source.name));
-    }
-    sourceRecords.set(source.name, lockedSourceRecord(source, commit));
-    checkouts.set(source.name, { source, directory });
-  }
-  // The last point at which an unstamped entry can be caught before it reaches
-  // the shared index, where absent-is-the-identity makes it admissible
-  // everywhere. See this file's header.
-  const unstamped = entries.filter((entry) => entry.source === undefined);
-  if (unstamped.length > 0) {
-    throw new Error(
-      `the source walk produced ${unstamped.length} UNSTAMPED entr(ies) ` +
-        `(${unstamped.map((e) => e.id).join(', ')}). An unstamped entry is platform-default ` +
-        'and admissible to every edition, so this would publish a private biome into the ' +
-        'open-source edition. Refusing.',
-    );
-  }
-  return { entries, sourceRecords, checkouts };
-}
-
-/**
- * The git tree id of `path` (repository-relative, `.` for the root) of a declared git source at `commit`, read in the
- * walk's checkout of that source (`checkouts` of `walkDeclaredSources`). A commit the checkout does not hold is fetched
- * by id, depth 1, from the declared URL under the source's own credential hold: no history is needed.
- */
-export function sourceTreeIdAt({ checkout, commit, path, env = process.env, workspace = editionWorkspaceConfig(), exec = execFileSync }) {
-  if (!EXACT_COMMIT.test(String(commit))) {
-    throw new Error(`source "${checkout.source.name}": tree of ${JSON.stringify(commit)} asked, which is not an exact 40-hex commit`);
-  }
-  return withSourceGitEnv(checkout.source, { workspace, env }, (gitEnv) => {
-    fetchCommitUnlessHeld(checkout.directory, commit, gitEnv, exec);
-    return git(checkout.directory, ['rev-parse', '--verify', path === '.' ? `${commit}^{tree}` : `${commit}:${path}`], gitEnv, exec);
-  });
-}

package/edition/first-party-source-ids.mjs

@@ -1,62 +0,0 @@
-import { workspaceSection } from './edition-config.mjs';
-
-// THE DECLARED SOURCE ID OF EACH FIRST-PARTY REPOSITORY THAT NAMES A RUNTIME
-// SUBJECT AFTER ITS SOURCE.
-//
-// An identifier is stable iff it survives a re-implementation of what is behind
-// it. A runtime subject named after its source (today: the composed-process
-// image, `<source id>-composed-process`) must therefore take that name from a
-// DECLARED id, never from where the repository happens to be hosted: a rename
-// or a host move changes `repositoryUrl` — provenance — and must change no
-// runtime identity.
-//
-// An external source declares its id in the edition (`sources[].name`, which
-// the walk also stamps as the biome's `repo`). A first-party repository has no
-// `sources[]` entry, so its id is declared in the data root's
-// `edition-workspace.json` (`firstPartySources`), keyed by the `repo` handle the
-// runtime image source index pins it under. The key is a lookup handle and may
-// move with the aggregator layout; the entry's `sourceId` is the identity and
-// must not. The entry's `repositoryUrl` is where the repository lives
-// (provenance, never identity): the develop graph resolves heads there.
-//
-// EVERY repository `runtime-image-source-index.json` pins is declared there, at
-// the same URL (the offline index check refuses otherwise), so a newly pinned
-// repository is refused at once rather than the day it first declares a
-// composed image. A declared repository need not be pinned yet: the develop
-// graph carries it before any release does. A lookup of an undeclared
-// repository is refused (`firstPartySourceId`), never named by a fallback.
-
-/** The kernel's source-handle grammar (`BiomeSourceNameSchema`): lowercase kebab-case. */
-export const DECLARED_SOURCE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
-
-/** The data root's first-party repositories (`firstPartySources`): repo handle -> { sourceId, repositoryUrl }. */
-export const firstPartySources = (needed = 'naming a runtime subject after its first-party source') =>
-  workspaceSection('firstPartySources', needed);
-
-export class UndeclaredSourceIdError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'UndeclaredSourceIdError';
-  }
-}
-
-export function assertDeclaredSourceId(sourceId, where) {
-  if (typeof sourceId !== 'string' || !DECLARED_SOURCE_ID_PATTERN.test(sourceId)) {
-    throw new UndeclaredSourceIdError(
-      `${where}: declared source id ${JSON.stringify(sourceId)} is not lowercase kebab-case ` +
-        `(${DECLARED_SOURCE_ID_PATTERN})`,
-    );
-  }
-  return sourceId;
-}
-
-export function firstPartySourceId(repo) {
-  const sources = firstPartySources();
-  if (!Object.hasOwn(sources, repo)) {
-    throw new UndeclaredSourceIdError(
-      `first-party repository "${repo}" has no declared source id — declare it in ` +
-        'edition-workspace.json under "firstPartySources"; a runtime identity is never derived from a repository name or URL',
-    );
-  }
-  return assertDeclaredSourceId(sources[repo].sourceId, `first-party repository "${repo}"`);
-}