@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/README.md

@@ -0,0 +1,291 @@
+# 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 select-records --branch develop --channel <tag> [--registry <root>, accepted and unused] --out <file>   # the build record per graph member that the registry channel tag points at (`build-records/<repo>:<channel>`, read by digest, never signature-verified: the registry write ACL is the trust) -> { pins, snapshot, channel, 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)`); images[] entries carry `member`; a missing or unreadable record refuses the run by member
+xema-edition develop resolve <id> --pins <file> --out <dir> --registry <root> --engine-image <repo>@sha256:<64 hex> --images-from <record> --channel <tag> --selection <file> (--previous-lock <lock> --previous-lock-sha256 <hex> | --first-seal) <roots>   # the channel (dev/prod) vendor resolve: the engine is the caller's digest, every first-party image the record's digest, satellites checked only for consistency with the producer records the selection pinned; no cosign, no rehash, no bundle attestation, no evidence-trust policy (descriptor records not-armed). --engine-repository, --engine-signer and --cosign are refused by name
+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 (official lane, verified: the vendor step is an internal entry, develop-catalogue-free-vendor.mjs, that finds and cosign-verifies the engine, probes and attests every image and bundle): --pins is the frozen vendor 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> --channel <tag> [--registry <root>, accepted and unused]   # the edition's image build record (what `resolve --images-from` reads) from a select-records selection: subjects are enumerated with no hash computed; each takes the digest AND contentHash its develop repository's selected record states (selected commit must equal the snapshot's) and goes in `satellites`. Declared exception (XEMA-2373): a current-resolution member (xema-docs) has no build record, so its subjects are hashed and probed and go in `images`. Platforms read by digest; any gap refuses and writes nothing; written once
+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`.
+- `developImageRegistry` (required) is the source's develop store root, a lowercase `<host[:port]>/<path>` with no scheme, tag, digest, trailing slash or trailing `/dev` (e.g. `registry.example.com/acme-dev`). It replaces `<host>/<owner>` in every develop ref of the source: the develop image of a subject whose release ref is `<host>/<owner>/<name...>` is `<root>/dev/<name...>` (`developImageRefFor`), and the build records of member `<name>` are `<root>/build-records/<name>` (`select-records` and `image-record`'s satellite verifier read them there; `--registry` is still accepted on both for one release, so a workflow can drop it first, and is unused). A source whose develop images still live beside its release images declares that owner root explicitly; a missing key is refused naming the source. Structurally a develop ref is any ref with a `dev` segment after the root.
+- `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`), taken from the producer's build record that the channel tag points at. With `--channel` each satellite is checked only for consistency: its producer's build record must list the exact `repository` and `digest` at `sourceSha`. The record is the one `select-records` pinned (the selection's `snapshot` run), read by its own record tag `build-records/<repo>:<branch>-<run>-<attempt>`, so the channel tag moving after selection (a newer green build) does not affect the run. `image-record` and `resolve` both take the selection (`--selection <file>`, required) and never read the channel tag for it. No signature is verified: on the channel lane the registry write ACL is the trust. 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 channel consistency check), 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.
+- The vendor `develop resolve` requires `--images-from` and `--channel` (refused by name without them). Only the catalogue-free customer resolve's internal vendor step probes the registry. 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-lock <lock> --previous-lock-sha256 <hex>`: the previous edition's images.lock 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`, 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`, 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.
+
+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 the kernel pin, which on develop is the pin of the xema-base member whose checkout `--kernel` sits in (the kernel contracts at the folded path); `--kernel-sha` is refused on develop.
+
+- `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`), takes the bundle's SLSA provenance statement from the envelope `verify-attestation` verified (its predicate type and its subject, the bundle digest, held again) and commits it with the classic `.att` layer's certificate and Rekor entry as a Sigstore bundle v0.1, and each image's image-source/v2 statement (an OCI referrer) against the trusted cosign; holds every artifact to its OWN exact trust row (the bundle to its one bundle-signer row, each image to the one release image-source row listing its repository), all rows of the one repository, signed from `refs/heads/main` at the one source commit, while the workflows may differ (one signs the bundle, another builds the images; the pin records each, `bundle.signerWorkflow` and each image's `producerWorkflow`), the `sourceManifestHash` and the pinned contract authority; reads the Fulcio extensions .15, .17 and .11 of every certificate and holds .11 (Runner Environment) to the source's declared runner environment (`--runner-environment self-hosted`, recorded as the pin's `runnerEnvironment`; absent means `github-hosted`), and for a self-hosted source also holds .9 (Build Signer URI) and .18 (Build Config URI) to the signing row's exact workflow identity (the declared workflow ran as the top-level workflow). Fulcio carries no runner label and no code reads the workflow's `runs-on`: whoever passes `--runner-environment self-hosted` must verify BY HAND that the signer workflows pin `runs-on: signing` (the dedicated signing runner label) at the pinned source commit, and the writer's summary prints the declaration so the `repin-evidence-trust` reviewer sees it; 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 workflow (GitHub-hosted, or self-hosted when its pin declares so), 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 the declared runner environment (`--runner-environment self-hosted` when the vendor's pin declares it, else `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 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 checks at mount an adapter's packed `package.json` `peerDependencies` against its own installed copies of the packages it provides (`@xemahq/contracts`, `@xemahq/biome-sdk`): a declared peer must be a package the host provides, with a valid semver range that has an upper bound, which the host's version satisfies (prerelease-aware, so a range can admit a develop build). An adapter that declares no peers carries its own inlined copies and gets no version check; its `xemaBundled` is provenance, not compared. The edition build applies the same rule first, by the same implementation (`checkAdapterPeers` of `@xemahq/biome-sdk/adapter-peers`), 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-peer-unsatisfied` (the host's version does not satisfy a declared range), `adapter-peer-declaration` (a peer the host does not provide, not a semver range, no upper bound, or `peerDependencies` not an object), `adapter-host-unpinned` (no host row, no `hostPackageVersions`, or no host version of a declared peer), `adapter-not-published` (the registry answers 404) or `unsupported-bundle-source` (not npm).
+
+## Candidate editions (a boot test, never a deploy)
+
+`@xemahq/edition-tooling/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/edition-tooling/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

@@ -0,0 +1,128 @@
+// 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`) checks at mount the adapter's
+// packed package.json `peerDependencies` against its own installed copies of the
+// packages it provides. The edition applies the same rule, the one shared
+// implementation `checkAdapterPeers` of `@xemahq/biome-sdk/adapter-peers`, to the
+// package.json the registry serves for the pinned bundle version. An adapter that
+// declares no peers inlines its own copies (`xemaBundled` is provenance, not
+// compared) and passes, exactly as it mounts. The mount check stays the last
+// line; this is the first.
+
+import { AdapterPeerProblemKind, checkAdapterPeers } from '@xemahq/biome-sdk/adapter-peers';
+
+import { ADAPTER_HOST_BIOME_ID, HOST_PROVIDED_PACKAGES } 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({
+  /** The host's version does not satisfy a declared peer range (the host's AdapterPeerUnsatisfiedError). */
+  PeerUnsatisfied: 'adapter-peer-unsatisfied',
+  /** A peer declaration the host cannot honour (the host's AdapterPeerDeclarationError). */
+  PeerDeclaration: 'adapter-peer-declaration',
+  Unpinned: 'adapter-host-unpinned',
+  NotPublished: 'adapter-not-published',
+  UnsupportedSource: 'unsupported-bundle-source',
+});
+
+export class AdapterBundleVersionError extends RefusalError {
+  constructor({ code, biomeId, packageName, detail, range = null, host = null }) {
+    super(`${code}: biome "${biomeId}" package "${packageName}": ${detail}`);
+    this.name = 'AdapterBundleVersionError';
+    this.code = code;
+    this.biomeId = biomeId;
+    this.packageName = packageName;
+    this.detail = detail;
+    this.range = range;
+    this.host = host;
+  }
+}
+
+/** The refusal fields for a shared-rule problem. */
+function peerRefusal(problem) {
+  const fields = { packageName: problem.packageName ?? 'peerDependencies', detail: problem.detail, range: problem.range ?? null };
+  switch (problem.kind) {
+    case AdapterPeerProblemKind.Unsatisfied:
+      return { ...fields, code: AdapterBundleVersionErrorCode.PeerUnsatisfied, host: problem.hostVersion };
+    case AdapterPeerProblemKind.HostVersionMissing:
+      return { ...fields, code: AdapterBundleVersionErrorCode.Unpinned, detail: 'the biome index pins no host version of it' };
+    default:
+      return { ...fields, code: AdapterBundleVersionErrorCode.PeerDeclaration };
+  }
+}
+
+/** 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 the host would refuse at mount: its pinned
+ * bundle's package.json `peerDependencies` fail the host's rule against the
+ * host versions the biome index pins. `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 };
+      if (hostVersions === undefined) {
+        refusals.push({ ...base, code: AdapterBundleVersionErrorCode.Unpinned, packageName: ADAPTER_HOST_BIOME_ID, detail: 'the biome index pins no host package versions' });
+        continue;
+      }
+      const source = hostModule.bundleSource;
+      if (source?.kind !== 'npm') {
+        refusals.push({ ...base, code: AdapterBundleVersionErrorCode.UnsupportedSource, packageName: String(source?.kind), detail: 'the bundle source is not npm' });
+        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, detail: 'the registry has no such version' });
+        continue;
+      }
+      const verdict = checkAdapterPeers({ peerDependencies: manifest.peerDependencies, hostProvided: HOST_PROVIDED_PACKAGES, hostVersions });
+      if (!verdict.ok) {
+        refusals.push({ ...base, ...peerRefusal(verdict.problem) });
+      }
+    }
+  }
+  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

@@ -0,0 +1,76 @@
+// adapter-host-versions — what the edition knows of the adapter host's own copies of the packages it provides to
+// adapter bundles: the package names, and the lockfile read that yields the host's versions when the biome index is
+// built. The version rule itself is shared with the host (@xemahq/biome-sdk/adapter-peers). No kernel load, so the
+// index build can import it.
+
+import { posix } from 'node:path';
+
+/** 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 the adapter host provides to adapter bundles (xema-base biomes/biome-adapter-host/api/
+ * biome-adapter-host/src/loader/adapter-peer-preload.json `hostProvidedPackages`; a test holds the two equal).
+ */
+export const HOST_PROVIDED_PACKAGES = Object.freeze(['@xemahq/contracts', '@xemahq/biome-sdk']);
+
+const LINK_PREFIX = 'link:';
+
+/**
+ * The version of a workspace package the importer links (`link:<rel>`): the `version` of `<importer>/<rel>/package.json`
+ * in the same repository at the same commit (`readRepositoryText`). Refused by name when the link leaves the
+ * repository, or the package.json is missing or declares no version.
+ */
+function linkedPackageVersion({ name, link, importer, lockfilePath, readRepositoryText }) {
+  const where = `${lockfilePath} importer "${importer}" links ${name} at ${link}`;
+  const target = posix.normalize(posix.join(importer, link.slice(LINK_PREFIX.length)));
+  if (posix.isAbsolute(link.slice(LINK_PREFIX.length)) || target === '..' || target.startsWith('../')) {
+    throw new Error(`host package versions: ${where}, which leaves the repository`);
+  }
+  if (typeof readRepositoryText !== 'function') {
+    throw new Error(`host package versions: ${where}, and no repository reader was given to read its package.json`);
+  }
+  const manifestPath = posix.join(target, 'package.json');
+  const text = readRepositoryText(manifestPath);
+  if (text === null || text === undefined) {
+    throw new Error(`host package versions: ${where}, but ${manifestPath} does not exist at the pinned commit`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`host package versions: ${where}, but ${manifestPath} is not JSON: ${error.message}`, { cause: error });
+  }
+  if (typeof manifest?.version !== 'string' || manifest.version === '') {
+    throw new Error(`host package versions: ${where}, but ${manifestPath} declares no version`);
+  }
+  if (manifest.name !== name) {
+    throw new Error(`host package versions: ${where}, but ${manifestPath} is ${JSON.stringify(manifest.name)}, not ${name}`);
+  }
+  return manifest.version;
+}
+
+/**
+ * The host component's resolved versions, read from the repository's pnpm-lock.yaml importer. A workspace link
+ * (`link:<rel>`) is read from the linked package's own package.json at the same commit (`readRepositoryText`).
+ */
+export function readHostPackageVersions({ lockfileText, importer, lockfilePath, parseYaml, readRepositoryText }) {
+  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 HOST_PROVIDED_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.startsWith(LINK_PREFIX)
+      ? linkedPackageVersion({ name, link: raw, importer, lockfilePath, readRepositoryText })
+      : raw.split('(')[0];
+  }
+  return versions;
+}