@xemahq/xema 0.59.1 → 0.60.1

package/edition/README.md

@@ -1,293 +0,0 @@
-# edition library
-
-Resolves, checks, seals and develop-snapshots an edition: a named, positive set
-of biomes and platform services, from its definition (`<id>/xema-distribution.json`)
-to its locks (`distribution`, `authorization`, `images`, `chart-set`). Plain ESM
-`.mjs`, run with `node`; tests run with `node --test`.
-
-The library derives nothing from where it sits. Every directory is stated by the
-caller, once, and a root that was not stated throws, naming its flag. There are
-no defaults.
-
-## Roots
-
-| Flag | Meaning |
-| --- | --- |
-| `--data-root` | catalogue indices (`biome-index.json`, `platform-service-index.json`, `runtime-image-source-index.json`), `chart-set.lock.json`, and `edition-workspace.json` |
-| `--editions-root` | the `<edition-id>/` definitions and locks |
-| `--sources-root` | source checkouts at `repos/<r>` and `submodules/<r>` |
-| `--kernel` | the BUILT `kernel-contracts` package directory (vendor verbs only; a customer verb takes none) |
-| `--deploy-root` | the `xema-deploy` checkout |
-| `--cache-dir` | a writable directory for fetched artifacts |
-
-## Entry scripts
-
-Each takes the roots below plus its own arguments (`--check`, an edition id, ...).
-
-| Script | Roots |
-| --- | --- |
-| `resolve-distribution.mjs` | data, editions, sources, kernel |
-| `resolve-images.mjs` | data, editions, sources, kernel, cache |
-| `resolve-chart-set.mjs` | data, editions, kernel |
-| `edition-biome-manifests.mjs` | data, editions, sources, kernel |
-| `seal-image-digests.mjs` | data, editions, kernel |
-| `verify-image-platforms.mjs` | data, editions, kernel |
-| `dist-check.mjs` | data, editions, sources, kernel, deploy, cache |
-| `authored-source-check.mjs` (`xema edition check-authored`) | data, editions, sources, kernel |
-| `develop-edition.mjs` | data, editions, sources, kernel, deploy, cache |
-| `release-edition.mjs` (`xema edition release`) | per verb: `freeze-sources` data; `target` none; `check-existing` data, cache; `resolve` data, editions, sources, cache |
-| `release-edition-artifact.mjs` (`xema edition artifact`) | data, editions, kernel |
-| `trust-policy-arming-verb.mjs` (`xema edition arming`) | data, kernel |
-| `contract-authority.mjs` (`xema edition contract-authority`) | none (the `@xemahq/contracts` this CLI ships) |
-| `build-biome-index.mjs`, `build-platform-service-index.mjs`, `build-runtime-image-source-index.mjs` | data, sources, kernel |
-| `checkout-indexed-source-repositories.mjs` | data, sources |
-| `why.mjs` | editions, kernel |
-| `repin-evidence-trust.mjs` | data, kernel |
-| `verify-image-evidence.mjs` (run as the BUILT bundle, `xema edition verify-evidence`) | data, editions, kernel |
-
-## `<data-root>/edition-workspace.json`
-
-The deployment's coordinates, so the library names no organisation or registry.
-Read strictly: every key is required, an unknown key or a duplicate key is refused.
-
-```json
-{
-  "schemaVersion": 1,
-  "imageRegistry": "registry.example.com/acme",
-  "chartRegistry": "oci://registry.example.com/acme/charts",
-  "chartPublishers": [{ "index": "<chart-set-index-name>", "repo": "<owner>/<repo>" }],
-  "sourceRepositoryUrlPrefix": "https://git.example.com/acme/",
-  "sourceAuthUsername": "x-access-token",
-  "evidenceTrustPolicy": { "policy": "image-evidence-trust-policy.json", "pin": "image-evidence-trust-policy.pin.json" }
-}
-```
-
-- `imageRegistry`: `<host>/<namespace>` where first-party images are addressed.
-- `chartRegistry`, `chartPublishers`: where chart-set indexes and charts are published. Vendor only; declare both or neither.
-- `sourceRepositoryUrlPrefix`, `sourceAuthUsername`: the prefix every first-party source URL must match and the git username source tokens authenticate as. The token is read from `EVIDENCE_REPOSITORIES_TOKEN` and sent only to repositories under the prefix.
-- `evidenceTrustPolicy`: `{policy, pin}` (data-root-relative paths) or `null` for a data root that declares no policy. A `null` data root serves develop editions only.
-
-## Common commands
-
-```bash
-xema edition resolve <id> [--check]     # write or verify the lock set
-xema edition resolve-digests <id>       # write the published image digests into the locks
-xema edition seal --resolved <repo>@sha256:<d> --manifest <file> --artifact <dir> --out <dir> --cosign <abs> --resolve-workflow-sha <40-hex>  # seal one pulled resolved RELEASE edition: cosign-verified offline (contract issuer; publisher only from edition-workspace.json editionPublishers.resolved.release, in the repository its provenance records), kind sealed, sealOf; armed only
-xema edition check                      # committed locks and indices are current
-xema edition check-authored             # the authored source, offline: definitions, indexes, policies, chart-set pin
-xema edition why <id> <biome>           # why a biome is in an edition
-xema edition list --editions-root <dir>
-xema edition locks <id> --channel <release|develop>  # validated locks as JSON; an unsealed distribution lock is read on develop only
-xema edition artifact <id> --channel release --registry <ns> --coordinate <tag> --engine-image <repo>@sha256:<digest> --out <dir>
-xema edition develop <freeze-sources|resolve|target|check-existing> ...
-# develop tag = sha256 of { cli, engine, pins, sourceImages }; target and check-existing take --engine-image, and a customer's --source-image
-xema edition develop coverage <id> --pins <file> --cosign <abs path> [--json]   # read-only forecast (policy held to its pin, this CLI's own verifier code): is each develop image producer-signed? exit 0 covered, 1 not, 2 error
-xema edition develop select-records --branch develop --registry <root> --cosign <abs path> --out <file> [--at <ISO-8601 UTC>] [--published-pins <file>]   # newest signed build record per graph member (the newest COMMIT on develop, every record verified; --published-pins keeps a published commit the records are not ahead of, part 07 passes it) -> { pins, snapshot, behind, images, currentResolution }, written once (a member whose firstPartySources entry declares `currentResolution: "<ticket>"`, xema-docs until XEMA-2373, is skipped with no registry read, listed in currentResolution and printed as `xema-docs: current resolution (leaves the edition, XEMA-2373)`) (behind = { <repo>: { head, commits } }: develop's head and the commits the pinned one trails it by; stdout gets one `<short name>: record <commit>, <N> commits behind HEAD` line per member, always `commits`, short name = the repo's last path segment and unambiguous; images[] entries carry `member`); any bad record refuses the run (needs dataRootRepositoryUrl in edition-workspace.json; anyone who can delete registry tags can remove newer records and this then pins the newest remaining valid one, and the guard is part 07's: deploy-latest's owner refuses a snapshot that goes backwards)
-xema edition develop follow --definition-at <owner>/<repo>,<path>,<dataRoot> --data-sha <sha> --kernel-sha <sha> --deploy-sha <upper bound> --engine-repository <registry>/<path> --registry <root> --cosign <abs path> (--first | --current-pins <file>) --out <file> --seals-out <dir> --previous-seal-signer <identity> (--previous-lock <lock> --previous-lock-sha256 <hex> | --first-seal)   # the COMPLETE frozen pins a dev deployment's follow policy selects, written once: members by select-records' newest-commit rule over their signed build records with the current pins as the published pins (a diverged member is refused by name), pinned as freeze-graph --member-pins pins them; the deploy root the newest first-parent commit at or below --deploy-sha whose engine sha-<12 hex> is published (unpublished skipped, none within the walk refused by name); the data/kernel/deploy roots by freeze-graph's rules and, from current pins, never behind or beside them (ancestry in each root's own checkout, which needs full history); declared sources at their develop heads, newer-wins against the current pin by the same ancestry rule. The data root checkout is the definition (its declared repository, clean at --data-sha, data root and distribution directory as named); the kernel checkout is at --kernel-sha. Beside the pins, --seals-out (written once) freezes both previous seals: the offering's newest signed develop edition's images lock, read once under --previous-seal-signer, and the customer's own previous lock (or first seal), passed through; seals.json names each file and its sha256. Prints the summary; --first says it is a first follow
-xema edition develop resolve --definition-at <owner>/<repo>,<path>,<dataRoot> --offering <owner>/<repo>,<path>,<dataRoot> --pins <file> --out <dir> --registry <root> --engine-repository <registry>/<path> --engine-signer <identity> --cosign <abs path> --offering-previous-lock <lock> --offering-previous-lock-sha256 <hex> (--previous-lock <lock> --previous-lock-sha256 <hex> | --first-seal) [--source-image ...]   # catalogue-free customer resolve: --pins is follow's frozen pins plus "definition-repository" (the definition's commit); the vendor step resolves the offering at the vendor pins under the offering's id and previous seal (the frozen offering lock), the customer step reads the definition at its commit and seals its own composed rows against the customer's previous lock. Reads no heads, pushes nothing; the same frozen inputs give the same bytes
-xema edition develop image-record <id> --selection <file> --pins <file> --out <file>   # the edition's image build record (what `resolve --images-from` reads) from a select-records selection: subjects are the checked-out snapshot's first-party image subjects; a current-resolution member's (xema-docs) is probed and goes in `images`, every other takes the selection's image of its develop repository (selected commit must equal the snapshot's) and goes in `satellites`; platforms read by digest; any gap refuses and writes nothing; written once
-xema edition develop verify-image-record --image <name>@sha256:<digest> --producer <owner/repo> --registry <root> --cosign <abs path>   # is the digest bound to the producer by an authenticated develop build record (shared verify core with select-records). Records are read newest run first (listBuildRecordRuns sorts by compareBuildRecordRuns: run, then attempt, highest first), a verified record of a workflow other than the producer's `.github/workflows/ci.yaml` is skipped, and the answer is the newest ci.yaml record listing the exact image -> { image, digest, producer, commit }. `commit` is the commit of the newest verified ci.yaml record (by run number, then attempt) that lists the digest; it can be an older commit when a later run targeted it, and for an image the producer reused by content hash it is NOT the commit that built it. This is safe because the digest is what binds the bytes. Refuses when no ci.yaml record lists the image, the record names another producer, or cosign refuses the identity
-xema edition develop check-overrides --overrides <json> --data-root <dir>   # data root only
-xema edition ceiling --distribution <id> --at <distributions sha> --producer-commit <owner/repo>=<sha> [...] --data-root <dir> --sources-root <dir> --kernel <dir>   # the dev ceiling (DevelopCeilingSchema from @xemahq/contracts/develop-ceiling): selection, origin, repo and trustCeiling from the definition and indexes at --at; version, services, runtimeComponents and serviceProcessFacts from each producer's xema-biome.json and xema-biome.index.json at its --producer-commit; a missing commit or manifest refuses, with no fallback
-xema edition chart-set <resolve|source-commit> ...
-xema edition arming --channel <release|develop> --data-root <dir> --kernel <dir>
-xema edition verify-evidence <id> --descriptor <abs path> [--json]
-xema edition evidence <assemble-input|check-committed|plan-refresh|statement|assemble-set|oci> ...
-xema edition contract-authority > contract-authority.json   # the full kernel contract authority of the @xemahq/contracts this CLI ships, canonical JSON: the --contract-authority <file> of a publisher's public-input run, no root flags (see Third-party sources)
-xema edition evidence assemble-third-party-input --bundle <oci repository>@sha256:<hex> --contract-authority <file> --image <image repository>@sha256:<hex> --subject-id <component image name> --provenance <absolute exported SLSA v1 predicate> --registry-credentials <file> --output <path> [--ttl-seconds <n>]   # a third-party publisher's producer input, no root flags (see Third-party sources)
-```
-
-Results are JSON on stdout and diagnostics on stderr. Exit 0 is success and 1 is a refusal. `xema edition <verb> --help` names the roots and flags each verb takes.
-
-## Authored-source check
-
-`xema edition check-authored` grades what is authored, offline, and reads no release state. `xema edition check` is the full release-path check; the authored check is a separate entry, not that check with parts turned off. It resolves no edition.
-
-It refuses on:
-
-- the kernel's edition protocol;
-- `biome-index.json`: immutable entries, deterministic order, no duplicate source identity;
-- `platform-service-index.json` and `runtime-image-source-index.json`, validated offline;
-- the evidence trust policy, its pin and its arming (an unarmed policy counts the editions that hold a release lock, by presence only);
-- the data-root readers (store source repositories, publisher trust);
-- the fleet chart-set pin and the pinned kernel's authorization composer;
-- the ownership self-tests: the kernel's capability-domain reader refuses two owners of one domain and an invalid domain, and counts no unlisted domain as first-party;
-- every edition definition's structure: the kernel parses it, `sourcePins` included, and it composes.
-
-It reads no lock content (the committed `distribution`, `images`, `authorization` and per-edition `chart-set` locks; the trust-arming rule counts lock files by presence) and no source checkout at a pinned commit. The sources root is read only for the kernel contract checkout the runtime-image-source index check verifies its authority against. `--check-sources` is refused: it is the release check's source audit.
-
-## Develop graph
-
-The develop graph is the data root's first-party repositories, declared in `edition-workspace.json`:
-
-```json
-"firstPartySources": {
-  "repos/xema-base": { "sourceId": "xema-base", "repositoryUrl": "https://git.example.com/acme/xema-base.git", "imageOrigin": "workspace" },
-  "submodules/xema-host-web": { "sourceId": "xema-host-web", "repositoryUrl": "https://git.example.com/acme/xema-host-web.git", "imageOrigin": "satellite" }
-}
-```
-
-- Each key is a repository handle (`repos/<x>` or `submodules/<x>`); `sourceId` is its kebab-case source id; `repositoryUrl` is canonical HTTPS under `sourceRepositoryUrlPrefix`. Both are unique. The retired string form (`"repos/x": "x"`) is refused with `RetiredFirstPartySourceShapeError`.
-- `imageOrigin` says where the source's images come from on the everyday lane: `workspace` (built by the job in the aggregator workspace) or `satellite` (a producer outside it, such as `submodules/xema-host-web`, that publishes its own signed develop digest). The parse accepts a source without it and fills in no default; `--images-from` refuses such a source (see below).
-- `xema edition develop freeze-graph` pins every declared repository at the `develop` head of its declared URL; overrides may name any of them. With `--member-pins <selection file>` (a select-records selection; only `.pins`, 40-hex, is read) each member is pinned at its selected record commit instead: the selection must pin exactly the graph minus its `currentResolution` members (equal to the graph members' declared `currentResolution`; a missing or extra member is refused by name), a `currentResolution` member (xema-docs, XEMA-2373) is pinned at its develop head, and `--member-pins` with `--overrides` is refused. The snapshot's `repositoryPins` (`develop resolve`, `checkout-indexed-source-repositories.mjs --snapshot-pins`) are exactly these repositories. The runtime image source index's `repositoryPins` are release pins and are not read on develop.
-- A first-party repository is in the develop graph before any release pins it. The converse is checked offline: every `repositoryPins` entry must be declared first-party at the same `repositoryUrl`.
-
-## Develop images from a build record
-
-`xema edition develop resolve <id> ... --images-from <file>` takes every first-party image of the edition from the everyday job's build record instead of the registry probe: no probe, no rehash, and no digest read from the registry. The record (`images-from-record.mjs`, schema version 1, strict: unknown keys refused, each list sorted by `subject`, a subject in at most one entry):
-
-```json
-{
-  "schemaVersion": 1,
-  "images": [
-    {
-      "subject": "service:biome-host-api",
-      "repository": "registry.example.com/acme/dev/biome-host-api",
-      "contentHash": "<64 hex: the image-input hash, the tag>",
-      "digest": "sha256:<64 hex: the manifest or index digest>",
-      "platforms": [{ "os": "linux", "architecture": "amd64" }],
-      "sourceSha": "<40 hex>"
-    }
-  ],
-  "satellites": [ { "subject": "host:xema-host-web", "...": "the same six fields" } ]
-}
-```
-
-- `subject` is `<kind>:<id>`, the key of the subject in `images.lock.json`. `repository` is the subject's develop repository. `platforms` must include every platform the edition requires. `sourceSha` must be the commit the snapshot pins for the subject's repository.
-- `images` are the images the job built or reused by content-hash tag. `satellites` are digests of first-party sources the job does not build (for example `submodules/xema-host-web`): each is admitted only when the producer's own develop `.github/workflows/ci.yaml` build record, cosign-verified as `select-records` verifies it (the data root's `record-build.yaml` at `refs/heads/develop`, called by the producer, issuer `https://token.actions.githubusercontent.com`), is at `sourceSha` and lists the exact `repository`, `digest` and `contentHash`. The producer is the subject repository's declared `firstPartySources` URL, never a record field. The records live under `--registry`'s `build-records/<repo>`.
-- Coverage is exact: a subject missing from the record, an entry that is not a first-party subject of the edition, or any contradicted field refuses the resolve, all named at once, with no probe fallback. `contentHash` and `sourceSha` are written to the lock as given; the lock's `imageRef` and `imageDigest` are the record's `repository` and `digest`. A third-party subject is not recorded and keeps its pinned seal.
-- Which list an entry sits in is not the record's choice. Each entry must be in the list its source's declared `imageOrigin` names: `workspace` sources in `images`, `satellite` sources in `satellites`. An entry in the other list (for example a satellite listed under `images`, which would skip the cosign verify), or an entry whose source declares no `imageOrigin`, refuses the resolve, with every problem named at once.
-- The develop target tag takes the record's digest (sha256 of its canonical JSON, entries by subject and platforms sorted) as one more input, `imageBuildRecord`, so the same pins with another satellite digest are another artifact. `develop target --images-from <file>` prints the same target the resolve does.
-- Without `--images-from` the resolve probes the registry and seals from it as before, and the tag inputs are unchanged. A customer resolve or target refuses the flag.
-
-## Develop plane invariants
-
-`xema edition develop resolve` asserts the capability-domain reservation table and biome confinement on the candidate it resolves, against the develop graph it froze, before any later phase. On develop they are asserted only there; `xema edition check` asserts them over the committed locks.
-
-- Reservation: the candidate's `capabilityDomainOwners` is non-empty, accepted by the kernel's reader, and exactly the table the frozen graph's full biome index builds, so every candidate over one graph carries the same table.
-- Confinement: each `confinedBiomes` declaration names a biome the frozen index carries and a substantive `consequence`; the candidate ships a confined biome only when admitted, and an admission of the candidate for a biome it does not ship is refused as stale.
-
-A violation throws `DevelopEditionInvariantError`, whose `violations` carry a `DevelopEditionInvariantReason` each.
-
-## Evidence trust
-
-The edition library builds, validates and verifies evidence statements; it never signs. Signing is done by the caller with `cosign`.
-
-- An edition descriptor records `evidenceTrustPolicy` as `armed` or `not-armed`. A release edition requires `armed`; writing one otherwise is refused.
-- A policy is armed on a channel when it authorizes a signer for each predicate on that channel and pins `cosign` and `git`. The develop channel admits `not-armed`.
-- The pin file (`image-evidence-trust-policy.pin.json`) binds the policy, the built verifier bundle, the kernel contract authority and the trusted `oras` binaries. Write it with `xema edition repin-evidence-trust [--trusted-oras-digest sha256:<64 hex>]`.
-- A customer edition (one resolved against a catalogue) also needs the edition-catalogue (E4) row on the release channel: one arming rule, `assessTrustPolicyArming(policy, schemas, channel, {consumesCatalogue})`.
-- `xema edition evidence statement catalogue stage|accept` (vendor) derives the E4 statement from `--artifact oci://<repository>@sha256:<digest>` and `--offering <id>`, and `accept` attaches the signed statement and bundle to the artifact as a referrer. A release catalogue is verified before it is read, by the data root's pinned built verifier (`catalogue-evidence arming|verify` mode of the bundle, which uses its own embedded kernel because the catalogue's kernel is not adopted yet); `xema edition release resolve` and `check-existing` take `--cosign <absolute path>` for it.
-- `oras` is located with `XEMA_ORAS_BIN` or `PATH` and must hash to a pinned digest. It runs with a scrubbed environment, so proxy and CA variables do not reach it.
-
-## Previous seal
-
-A write of `images.lock.json` (`resolve-images`, `xema edition develop resolve`) takes exactly one previous seal, whose composed artifacts' generations carry forward:
-
-- `--previous-seal-signer <certificate identity>` (develop resolve, vendor form): the CLI lists the edition's own repository (`<registry root>/develop-editions/xema-edition-<id>`), reads every snapshot tag, and takes the newest edition by its `org.opencontainers.image.created` annotation (inside the signed manifest). An edition with no signature was never published and is passed over; the newest signed one must verify, offline through the pinned cosign, for exactly that identity and the GitHub OIDC issuer, or the resolve is refused (it never steps back to an older edition). Its images.lock layer is fetched by digest. The run must be under the per-edition concurrency group, so the edition read is the one the previous run pushed.
-- `--previous-lock <lock> --previous-lock-sha256 <hex>`: the same layer, taken by the caller; the CLI refuses unless the bytes hash to the digest.
-
-A customer develop resolve (`--definition`, or the catalogue-free form) takes `--previous-lock`/`--previous-lock-sha256` or `--first-seal` (never `--previous-seal-signer`), under the customer's id, and it feeds only the customer's own composed rows; the catalogue rows are the catalogue's. In the catalogue-free form the vendor rows carry forward from the offering's own seal, `--offering-previous-lock`/`--offering-previous-lock-sha256` (frozen by `develop follow`), under the offering's id. A release customer resolve takes none.
-- `--first-seal`: generation 1, only for a distribution that has never had an edition. The CLI never infers it: a 404 for the repository (a registry may hide a repository from a credential) and a repository with no signed edition (retention) are refused, naming `--first-seal`.
-
-The in-repo resolve and pin/unpin take the committed `images.lock.json` at the target path as the previous lock (first seal when absent).
-
-## Kernel protocol and pins
-
-The CLI is coupled to the kernel's edition protocol, not to the kernel package. `@xemahq/contracts` exports the protocol identity as data (`dist/edition-protocol/edition-protocol.json`: `{contentDigest, provisional, version}`). This CLI supports protocols v28, v30, v31, v32, v33, v34, v35, v36, v37, v38, v39, v40 and v41 (no published kernel declares v29; a CLI lists a protocol only while every kernel published under it exports what the CLI imports; v27 and older kernels lack `serviceImageSubjects`, so a data root whose pinned kernel speaks v27 or older stays on an earlier CLI), pinned to its digest and vendored, and REFUSES an identity with `provisional: true`; every loader that executes the kernel, `xema edition check` first, and the evidence verifier compare only that identity and refuse an unsupported one, naming the supported and the declared versions. A protocol change needs a CLI release first; only then does the data root repin its kernel authority.
-
-A develop edition does not take the kernel's develop head blindly: `xema edition develop choose-kernel --kernel <package dir> [--kernel-pin <40-hex>] --out <file>` reads the declared protocol of each commit on the checkout's first-parent history (from source, unbuilt) and chooses the newest one this CLI supports. It writes `{chosenSha, headSha, held, reason}` (`reason`: `head-supported` | `head-ahead` | `explicit-pin`; `held` is `head-ahead`), and when held prints `kernel held at v<N> (<sha12>), head at v<M> (<sha12>): raise the CLI` (stdout only, never persisted). The head is the checkout's `refs/remotes/origin/develop` (a full-history checkout). An explicit pin wins but is still checked, and must be on that head's first-parent history (`not-on-develop` otherwise); when no commit is supported it refuses (`EditionProtocolMismatchError`, `no-supported-commit`; the walk ends at the first commit with no declaration file) and never falls back to the head; a declaration that exists but does not parse, at the head or any walked commit, is refused by name (`unparseable`), never skipped. `freeze-graph` applies the same check to `--kernel-sha`.
-
-- `xema edition evidence statement entitlement stage` writes entitlement predicate v2 (`lockDigest`, `catalogueDigest`, read from the edition's committed locks), so it takes `--editions-root` besides `--data-root` and `--kernel`.
-- A source repository JOINS a data root that has committed pins with one command: `xema edition index runtime-image-source --trusted-write --repo <repository> [--at <40-hex>] [--kernel-root <checkout>]`. The repository is resolved once and the runtime image source, biome and platform-service indexes are all written from the committed pins plus that one pin; every committed pin is kept field for field (a differing one is refused by name), a second declared repository with no pin is refused, and the summary names each pin added, moved and dropped. Then `xema edition index biome --check`, `xema edition index runtime-image-source --check` and `pnpm check`. The biome builder takes no `--repo`: it would resolve the repository a second time.
-- A THIRD-PARTY source (a biome published from an organisation outside the first-party fleet) joins with `build-runtime-image-source-index.mjs --trusted-write --third-party <name>` plus the flags `--help` of that script lists (the repository, its numeric repository and owner ids, the bundle and image references, the signer policy ids, the biome id, the source commit). The writer clones nothing: it verifies the bundle (`cosign verify` and `verify-attestation --type slsaprovenance1`, offline, the pinned trusted root, exactly the bundle-signer row's identity and issuer, never `--insecure-ignore-tlog`) and each image's image-source/v2 statement (an OCI referrer) against the trusted cosign; holds one repository, commit and workflow, the `sourceManifestHash` and the pinned contract authority; reads the Fulcio extensions .15, .17 and .11 of every certificate; and checks uniqueness and the first-party exclusions. It then writes `third-party-source-pins.json` (canonical JSON), the evidence under `evidence/sha256-*/`, and the index with the repository's `producerWorkflowPins` entry through the generator's own merge. It does not repin the evidence trust pin: `xema edition repin-evidence-trust` must follow. `build-runtime-image-source-index.mjs --check-third-party [--cosign <path>]` (or `XEMA_COSIGN_BIN`) re-verifies every pin offline; `dist-check` runs it next to `--check`, and it passes trivially when the data root has no pin file (zero-config).
-  A distribution declares such a source as `{kind: oci, name, registry}`; the source walk (`external-source-walk.mjs`) holds it to the pin of that name (no pin file, an empty one or an unknown name refuses with the loader's reason), re-verifies the committed evidence offline with the same verifier (cosign from `XEMA_COSIGN_BIN`), pulls the bundle BY DIGEST, and writes a lock row with origin `third-party`, an OCI `bundleSource` and NO lock `source`. `resolve-images` takes the row's image subjects from the pin (`imageRef`, `sourceCommit`, `contentHash` = the publisher's `sourceTreeHash`, never built or hashed here) and prints that hash as `contentHash (publisher-attested)`; admission derives the repository pin from the pin file, refuses a repository under `repos/` or `submodules/` or one that collides with an index pin or git source, and for these subjects asserts the signing row's repository, the subject `repo` and the predicate's `source.repositoryUrl` are one repository.
-
-- The runtime image source index is v2 and carries operator-stated `producerWorkflowPins` (the workflow commit a producer certificate must be signed from, per repository). `xema edition index runtime-image-source [--producer-workflow-pin <owner/repo>=<40-hex>]...` preserves the committed pins exactly; each flag sets one repository's pin (repeatable; a repeated or non-GitHub `owner/repo` is refused; only `--trusted-write` writes an index, so the flag with any other mode, `--check-sources` included, is refused); a bootstrap index with none writes `[]`. A v1 index is refused, never migrated: delete it and bootstrap a new one with `--kernel-commit`.
-
-## Third-party sources
-
-- **Zero-config.** A data root with no `third-party-source-pins.json`, an empty one or an unparsable one has NO third-party source: every `kind: oci` declared source and every third-party image subject is refused, naming the loader's reason. The pin file is the explicit grant; a trust-policy row alone grants nothing. When the file exists, its sha256 is part of the evidence trust pin, so it moves only together with `xema edition repin-evidence-trust`.
-- **Publisher input.** The publisher's own GitHub-hosted workflow, on `refs/heads/main`, assembles the producer input of each image with `xema edition evidence assemble-third-party-input` (usage above), one run per image. It runs on public inputs only: this CLI and the `@xemahq/contracts` it ships (both from npm), the publisher's checkout at `GITHUB_WORKSPACE` (holding `GITHUB_SHA`), its own registry credential declaration (`--registry-credentials`, the `image-registry-credentials.json` format, naming environment variables, never a secret) and the `GITHUB_*` context. It takes no root flag and reads no data root. `--contract-authority` is the kernel contract authority object the vendor's evidence trust pin names; it must be the kernel this CLI ships, so the publisher installs the matching CLI version. The subject is the bundle's (`--bundle`, read by digest) `oci-image` service or worker component named `--subject-id`; `path` is the directory of the one `xema-biome.json` at `GITHUB_SHA` whose hash is the bundle's; `sourceTreeHash` is hashed over the checkout with no cross-repo inputs (publisher-attested); the image is read by digest (`--image`) and must carry its cosign SLSA v1 and SBOM attestations; the builder digests come from the exported predicate (`--provenance`, VCS revision `GITHUB_SHA`). The lifetime is `--ttl-seconds` or the first-party default (72h); the trust policy's `maxProducerTtlSeconds` ceiling is enforced by the vendor's third-party pin writer (`index runtime-image-source --trusted-write --third-party`) and by `verify-evidence`, and the signer rows and image ownership are checked by the pin writer. It refuses unless `RUNNER_ENVIRONMENT` is `github-hosted` and `GITHUB_REF` is `refs/heads/main`. The output is the exact input `xema edition evidence statement producer` accepts.
-- **Publisher contract authority.** The `--contract-authority <file>` comes from `xema edition contract-authority`, also on public inputs only: it prints the full `KernelContractAuthority` of the `@xemahq/contracts` this CLI ships, read from that package's own export `@xemahq/contracts/edition-protocol/contract-authority.json` (the kernel's release derives it at publish time; `sourceCommit` is the commit as the kernel release states it, carried, not proven, while the digest and `sourcePaths` are proven against the package). It is parsed with `KernelContractAuthoritySchema`, refused unless its `contentDigest` is the bundled edition protocol digest and the bundled kernel is that authority, and printed as canonical JSON. A kernel without the file (a dev build, or a release older than the file) is refused by name; there is no fallback.
-- **Publisher evidence (public-input mode).** The rest of the publisher's run uses the same verbs as first party with `--contract-authority <file>` in place of `--data-root`/`--kernel`: `xema edition evidence statement producer stage` (no OIDC), a keyless `cosign attest-blob --new-bundle-format` of each staged statement in an `id-token: write` job, `statement producer accept --cosign <abs path>` (no OIDC), then `oci attach-plan`, `oras attach` and `oci validate`. Passing both modes, or neither, is refused by name. The authority and schemas come from the file and the `@xemahq/contracts` this CLI bundles, through the one resolution `assemble-third-party-input` uses. Accept verifies every bundle's signature but holds cosign to no version: the vendor's admission re-verifies with its pinned cosign. The publisher installs the xema CLI whose bundled `@xemahq/contracts` matches the authority; an authority whose contracts digest is not the bundled one is refused, naming both digests.
-- **Seal.** A third-party image subject is sealed BY DIGEST from its pin: it keeps the publisher's `imageRef`, its platforms are read at `<imageRef>@<manifestDigest>`, and its `contentHash` (the publisher's `sourceTreeHash`) is never used as a tag, a develop coordinate, a cache key or a build-ledger key. It is not a develop-coverage subject and is excluded from the first-party fleet-coordinate verdict. Its producer evidence in the edition's evidence set is the committed evidence the pin records, checked byte for byte against the pin's digests.
-- **Revocation.** A sealed lock keeps its seal-time verdict; there is no expiry machinery. To revoke a source: remove its pin and its trust-policy rows, regenerate the runtime image source index, run `xema edition repin-evidence-trust`, and reseal every edition that includes the biome. An edition already delivered is not recalled.
-- **What this does not prove.**
-  - `sourceTreeHash`/`contentHash` are publisher-attested and never recomputed: the image is proven to come from repository@commit through that organisation's GitHub-hosted workflow, not from these exact inputs.
-  - Nothing about the CONTENT of the repository or the workflow at that commit: the certificate identity proves who built, not what was built.
-  - The bundle and the images share one commit, but the bundle's files are not proven to be the images' build input.
-  - No revocation after sealing (above). A private registry needs a read credential at mirror and install time.
-
-## Build ledger completeness
-
-`build-ledger.json` schema 2 records, per repository, the commits that published images and each `imageRef:contentHash` with its platforms and digest (schema 1, a bare commit list, is still read and is removed once the data root is re-projected). With a v2 ledger, `resolve-images` (and so `dist:check` and an exact-commit `--at` pin) refuses an edition when any resolved subject lacks its contentHash or one of that edition's required platforms in the ledger, listing every missing coordinate with the repository pin that produced it. There is no override; a v1 ledger gets no check.
-
-## Per-edition source pins
-
-A vendor edition's `xema-distribution.json` may carry the CLI-owned key `sourcePins: [{ "repo": "repos/<name>", "ref": "<40-hex commit>", "until": "<exit condition>" }]`: the edition resolves that repository at the exact commit instead of the data root's shared `repositoryPins`. The key is strict (non-empty array, exactly `{repo, ref, until}`, a graph repository, an exact lowercase commit, a non-empty `until`, no repository twice), is removed before the kernel parse, and is refused in a customer definition. The kernel contract repository cannot be held: its authority stays data-root-wide.
-
-Holds are sparse overrides: an entry exists only for a repository the edition holds back, so an entry equal to the shared `repositoryPin` is refused ("not a hold"). Each entry carries its exit condition in `until`, and the parser refuses an entry without one. Do not edit `sourcePins` by hand; the verbs are the supported way:
-
-```bash
-xema edition pin <edition> <repo> <ref> --until "<exit condition>" --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>
-xema edition unpin <edition> [<repo>] --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>
-```
-
-`pin` applies the checks below (and the graph, kernel and not-a-hold rules) before it writes, adds or replaces the entry in the edition's `xema-distribution.json` keeping the file's formatting and key order, and re-resolves the edition; a failed re-resolve restores the edition directory (definition and locks) byte for byte and rethrows. `unpin` removes one hold (or all of the edition's), drops the key when none is left, and re-resolves. `xema edition check` prints every active hold, informationally: `[dist:check] hold: <edition> <repo> @<ref12> until: <exit condition>`, then `N hold(s) active` or `no holds`.
-
-A held commit is authorized, never trusted, and nothing overrides it: the commit exists in the source checkout; it is contained in `refs/remotes/origin/main` (a missing ref refuses); and it is a built commit (in the build ledger or the repository's evidence tree; a repository neither knows publishes no images and needs containment only). Every refusal is listed at once.
-
-`edition-pinned-inputs.mjs` is the one per-edition source of the three indexes and the pins: an edition holding nothing reads the committed data-root files unchanged; a holding edition has them rebuilt at its effective pins by the release builders (`indexes-at-pins.mjs`, the builders a develop snapshot uses). Resolve, images, check, seal, catalogue, artifact and biome manifests all read through it, so `images.lock.json` `sourceCommit`, the content hashes and the catalogue rows carry the held commit and `xema edition check` reports a held edition stale exactly when a fresh resolve at its own pins differs. Index currency checks and the index builders stay on the shared pins. The evidence reader (`xema edition locks`, the verifier) grades each subject against the edition's effective pins, so the evidence verifier bundle changes and the data root repins evidence trust when it adopts this CLI. No lock schema changes.
-
-`sourcePins` are not inherited and do not apply on the develop channel: a snapshot replaces every pin. `checkout-indexed-source-repositories.mjs --editions-root <dir>` additionally fetches every edition's held commits and the main history of the held repositories, so containment can be checked in CI.
-
-## Customer editions
-
-A customer edition is resolved against a catalogue pinned in `catalogue.pin.json` beside the definition file. The catalogue is the ceiling: it supplies availability, pins and digests and never adds a component. It also names the kernel: `kernel` is `{name, version, integrity}` (`@xemahq/contracts`, an exact `x.y.z`, the npm `sha512-` integrity of that tarball), and a catalogue without it is refused. Its `ceiling.storePublisherTrust` is the offering lock's Store publishers (or `null`); a definition selects among them with `storePublisherAnchorKeys`, the resolve copies the selected entries into the customer lock, and the kernel's `customerLockCeilingIssues` refuses, at resolve, seal and verify, an entry the definition does not select, a key the catalogue does not vouch for, or an entry that differs from the catalogue's.
-
-```bash
-xema edition resolve --definition <file> --channel release \
-  --data-root <dir> --sources-root <dir> --cache-dir <dir> --out <dir> \
-  --source-image <source>=<registry>/<prefix> [--catalogue-username <u> --catalogue-token-env <VAR>]
-xema edition release resolve --definition <file> --cosign <abs path> ... # release: E4 evidence verified before the catalogue is read
-xema edition resolve-digests <id> --definition <file> --data-root <dir> --editions-root <dir> --sources-root <dir> --cache-dir <dir>
-```
-
-`--channel develop` is refused on this verb: it takes no previous seal, so a customer's own composed rows would restart at generation 1. Resolve a develop customer edition with `xema edition develop resolve --definition <file> (--previous-lock <file> --previous-lock-sha256 <hex> | --first-seal) ...`.
-
-To use a customer's own registry, copy the catalogue artifact and vendor images by digest with `oras cp`, pin the mirrored catalogue in `catalogue.pin.json`, and declare `imageRegistryMirror: {complete: true, map: [{source, target}]}` in the definition.
-
-A customer verb takes no `--kernel` (it is refused) and needs no kernel checkout and no credential for the kernel. After it fetches its catalogue it downloads `@xemahq/contracts@<catalogue.kernel.version>` from registry.npmjs.org into `<--cache-dir>/kernel-npm/`, holds the tarball to the catalogue's npm integrity before extracting it, and proves the package is the catalogue's contract authority (final protocol identity carrying `contractAuthority.contentDigest`) before it loads any schema.
-
-
-### Adapter bundles against the adapter host
-
-The adapter host refuses at mount an adapter whose packed `package.json` `xemaBundled` entry for `@xemahq/contracts` or `@xemahq/biome-sdk` is missing or not caret-compatible with the host's own resolved copy (same major; same minor too while the major is 0; an unparsable version is incompatible). The edition build refuses the same first, in `adapter-bundled-versions.mjs`: every lock biome host module of the `xema-adapter-host` ABI must carry an npm bundle source, whose published manifest is read from `https://registry.npmjs.org/<name>/<version>` without a credential. The host's versions are the `hostPackageVersions` of the `biome-adapter-host` row of the biome index (read from the host source's `pnpm-lock.yaml` when the index is built; the distribution lock never carries it) and, for a customer, of the same row in the catalogue. Resolve (vendor, develop, customer) and seal (vendor and `--definition`) run the check and report all refusals together, each with one of `adapter-bundle-version-mismatch`, `adapter-host-unpinned` (no host row or no `hostPackageVersions`), `adapter-not-published` (the registry answers 404) or `unsupported-bundle-source` (not npm).
-
-## Candidate editions (a boot test, never a deploy)
-
-`@xemahq/xema/candidate-edition` re-seals a pinned develop edition with ONE repository's candidate commit, so that repository's CI can boot the composed member set through the production path against locks that match the candidate. Two calls:
-
-```js
-import { fetchPinnedEditionCheckouts, resealCandidateEdition } from '@xemahq/xema/candidate-edition';
-const candidate = { repo: 'repos/xema-base', checkoutDir: '/abs/xema-base' };
-const checkouts = await fetchPinnedEditionCheckouts({ tripleDir, cacheDir, dataRootDir, candidate, env });
-await resealCandidateEdition({ tripleDir, checkouts, candidate, outDir, deployment: { id, runtimeNamespace } });
-```
-
-- `tripleDir` is a pulled develop edition artifact (`xema-edition.json` plus its locks); its `provenance.pins` are the pins. A customer or release edition is refused.
-- `fetchPinnedEditionCheckouts` is the ONLY network step. A cached checkout is built in a staging directory and renamed into place only once it is complete (the kernel once its build succeeded), so a failed run never leaves a partial checkout to be reused. Local git commands run with PATH and HOME only. It clones every checkout the develop resolve reads at its pin (the kernel, built as `develop-edition.yaml` builds it, and every develop-graph repository but the candidate, with the extra commits the resolve reads) into `cacheDir/checkouts/<pin key>/<commit>`, and every declared source into the external-source cache. The data root is cloned locally from `dataRootDir`, the caller's checkout of it at its pin, because the data root declares every other repository and the credential that reads them. Credentials are read only from the `env` the caller passes. A warm cache runs no network command and no build. Every cached checkout must be at its pin and clean.
-- The calls configure the process-global edition workspace while they run: run one at a time in a process.
-- `resealCandidateEdition` runs OFFLINE. The candidate checkout must be clean (tracked files at HEAD), and the candidate commit replaces its pin. It reruns the develop resolve's distribution steps (snapshot inputs, resolve, bundle signers, plane invariants, operation admission) and `composeAuthorizationBase` (`XEMA_FGA_CLI`). It seals the distribution lock with the kernel's `sealDistributionLock` and carries `images.lock.json` byte for byte. It does not run the steps that read a registry: the images resolve and seal, the adapter-bundle check and the chart set.
-- The output directory holds `distribution.lock.json`, `images.lock.json`, `authorization.lock.json`, `resolved-deployment.json` and `candidate-content.json`. The resolved deployment is the kernel's `resolveUnsplitDeployment` over exactly those lock bytes. It names the registry `candidate.invalid` and the version `0.0.0-candidate`.
-- **Unsigned and not deployable.** The output is a plain directory, never an edition. It has no `xema-edition.json`, is never pushed as an OCI artifact and is never signed, and admission needs the cosign-signed edition artifact. Its resolved deployment is the UNSPLIT variant, which `verifyResolvedDeployment` refuses (`unsplit-not-accepted`) unless the caller opts in with `{ accept: 'unsplit' }`.
-- **The candidate content record.** A biome that ships images from its own repository has its content read where its images were built. The carried images were built at the pinned commit, so `candidate-content.json` records `{ <repo>: <candidate commit> }`, bound to the distribution lock bytes by `distributionLockSha256`, to the edition by `distributionId`, and to the candidate: it holds exactly one entry, the candidate repository at its checkout's HEAD, and any other record is refused. The seal and `verifyCandidateContentHashes` pass the record to biome-content.mjs as `contentCommits`. A record that names a commit whose content is not the lock's is refused. A triple without a record is verified exactly as any lock is. The record is a file beside the locks, because the kernel's lock schema is strict and has no field for it.
-
-## Tests
-
-```bash
-pnpm run test:edition     # node --test "edition/*.test.mjs" "edition/*-contract-tests.mjs"
-```
-
-The sealing tests run the real `openfga` CLI and fail, naming `XEMA_FGA_CLI`, when it is unset.

package/edition/adapter-bundled-versions.mjs

@@ -1,108 +0,0 @@
-// adapter-bundled-versions — the edition build refuses what the adapter host
-// would refuse at mount, before it ships.
-//
-// The adapter host (xema-base `biome-adapter-host`) refuses at mount an adapter
-// whose packed package.json `xemaBundled` entry for `@xemahq/contracts` or
-// `@xemahq/biome-sdk` is missing or not caret-compatible with the host's own
-// resolved copy. The mount check stays the last line; this is the first.
-
-import { ADAPTER_HOST_BIOME_ID, BUNDLED_PACKAGES, isCaretCompatible } from './adapter-host-versions.mjs';
-import { RefusalError } from './collected-refusals.mjs';
-import { loadKernelBiomeContracts } from './lib.mjs';
-import { compareStrings } from './string-order.mjs';
-
-export const AdapterBundleVersionErrorCode = Object.freeze({
-  VersionMismatch: 'adapter-bundle-version-mismatch',
-  Unpinned: 'adapter-host-unpinned',
-  NotPublished: 'adapter-not-published',
-  UnsupportedSource: 'unsupported-bundle-source',
-});
-
-export class AdapterBundleVersionError extends RefusalError {
-  constructor({ code, biomeId, packageName, bundled, host }) {
-    super(
-      `${code}: biome "${biomeId}" package "${packageName}" bundled ${JSON.stringify(bundled)} ` +
-        `against host ${JSON.stringify(host)}`,
-    );
-    this.name = 'AdapterBundleVersionError';
-    this.code = code;
-    this.biomeId = biomeId;
-    this.packageName = packageName;
-    this.bundled = bundled;
-    this.host = host;
-  }
-}
-
-/** The adapter host's row of a biome index or catalogue (undefined when the edition does not carry it). */
-export function adapterHostRow(rows) {
-  return rows.find((row) => row.id === ADAPTER_HOST_BIOME_ID);
-}
-
-/** Does the lock mount any adapter host module? */
-export function lockMountsAdapters(lock) {
-  const adapterAbi = loadKernelBiomeContracts().BiomeComponentHostAbi.AdapterHost;
-  return (lock.biomes ?? []).some((biome) => (biome.hostModules ?? []).some((hostModule) => hostModule.hostAbi?.name === adapterAbi));
-}
-
-/** Fetch a package version's manifest from the public registry (no credential); null when unpublished. */
-export async function fetchRegistryManifest(name, version, fetchImpl = fetch) {
-  const response = await fetchImpl(
-    `https://registry.npmjs.org/${name.replace('/', '%2F')}/${encodeURIComponent(version)}`,
-    { headers: { accept: 'application/json' } },
-  );
-  if (response.status === 404) {return null;}
-  if (!response.ok) {
-    throw new Error(`npm registry answered ${response.status} for ${name}@${version}`);
-  }
-  return response.json();
-}
-
-/**
- * Refuse every adapter host module whose packed bundle the host would refuse at
- * mount. `fetchManifest(name, version)` resolves the manifest or null (unpublished).
- * All refusals are collected and thrown together, sorted.
- */
-export async function assertAdapterBundlesMatchHost({ lock, hostRow, fetchManifest }) {
-  const adapterAbi = loadKernelBiomeContracts().BiomeComponentHostAbi.AdapterHost;
-  const refusals = [];
-  const manifests = new Map();
-  const hostVersions = hostRow?.hostPackageVersions;
-  for (const biome of lock.biomes ?? []) {
-    for (const hostModule of biome.hostModules ?? []) {
-      if (hostModule.hostAbi?.name !== adapterAbi) {continue;}
-      const base = { biomeId: biome.id, bundled: null, host: null };
-      if (hostVersions === undefined) {
-        refusals.push({ ...base, code: AdapterBundleVersionErrorCode.Unpinned, packageName: ADAPTER_HOST_BIOME_ID });
-        continue;
-      }
-      const source = hostModule.bundleSource;
-      if (source?.kind !== 'npm') {
-        refusals.push({ ...base, code: AdapterBundleVersionErrorCode.UnsupportedSource, packageName: String(source?.kind) });
-        continue;
-      }
-      const key = `${source.name}@${source.version}`;
-      if (!manifests.has(key)) {
-        manifests.set(key, fetchManifest(source.name, source.version));
-      }
-      const manifest = await manifests.get(key);
-      if (manifest === null) {
-        refusals.push({ ...base, code: AdapterBundleVersionErrorCode.NotPublished, packageName: key });
-        continue;
-      }
-      for (const name of BUNDLED_PACKAGES) {
-        const bundled = manifest.xemaBundled?.[name] ?? null;
-        if (!isCaretCompatible(bundled, hostVersions[name])) {
-          refusals.push({ ...base, code: AdapterBundleVersionErrorCode.VersionMismatch, packageName: name, bundled, host: hostVersions[name] });
-        }
-      }
-    }
-  }
-  if (refusals.length === 0) {return;}
-  const errors = refusals
-    .map((fields) => new AdapterBundleVersionError(fields))
-    .sort((a, b) => compareStrings(a.message, b.message));
-  const thrown = new AdapterBundleVersionError(errors[0]);
-  thrown.message = errors.map((error) => error.message).join('\n');
-  thrown.refusals = errors;
-  throw thrown;
-}

package/edition/adapter-host-versions.mjs

@@ -1,41 +0,0 @@
-// adapter-host-versions — what the edition knows of the adapter host's own copies of the packages an adapter
-// bundles: the packages compared, the host's caret rule (copied exactly from xema-base
-// biomes/biome-adapter-host/api/biome-adapter-host/src/loader/caret-compatibility.ts), and the lockfile read that
-// yields the host's versions when the biome index is built. No kernel load, so the index build can import it.
-
-/** The id of the biome that ships the adapter host (the service of BiomeComponentHostAbi.AdapterHost). */
-export const ADAPTER_HOST_BIOME_ID = 'biome-adapter-host';
-
-/** Exactly the packages xema-connectors tooling/bundle REQUIRED_BUNDLED_PACKAGES names. */
-export const BUNDLED_PACKAGES = Object.freeze(['@xemahq/contracts', '@xemahq/biome-sdk']);
-
-const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
-
-/** The host's rule, copied: same major; when major is 0, same minor too; unparsable is incompatible. */
-export function isCaretCompatible(bundled, host) {
-  const left = typeof bundled === 'string' ? VERSION_PATTERN.exec(bundled) : null;
-  const right = typeof host === 'string' ? VERSION_PATTERN.exec(host) : null;
-  if (left === null || right === null) {return false;}
-  if (left[1] !== right[1]) {return false;}
-  return left[1] !== '0' || left[2] === right[2];
-}
-
-/** The host component's resolved versions, read from the repository's pnpm-lock.yaml importer. */
-export function readHostPackageVersions({ lockfileText, importer, lockfilePath, parseYaml }) {
-  if (lockfileText === null) {
-    throw new Error(`host package versions: ${lockfilePath} does not exist`);
-  }
-  const dependencies = parseYaml(lockfileText)?.importers?.[importer]?.dependencies;
-  if (dependencies === undefined) {
-    throw new Error(`host package versions: ${lockfilePath} has no importer "${importer}" with dependencies`);
-  }
-  const versions = {};
-  for (const name of BUNDLED_PACKAGES) {
-    const raw = dependencies[name]?.version;
-    if (typeof raw !== 'string') {
-      throw new Error(`host package versions: ${lockfilePath} importer "${importer}" has no ${name} entry`);
-    }
-    versions[name] = raw.split('(')[0];
-  }
-  return versions;
-}