@xemahq/xema 0.29.0 → 0.30.0

package/edition/README.md

@@ -16,7 +16,7 @@ no defaults.
 | `--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 |
+| `--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 |
 
@@ -28,7 +28,7 @@ Each takes the roots below plus its own arguments (`--check`, an edition id, ...
 | --- | --- |
 | `resolve-distribution.mjs` | data, editions, sources, kernel |
 | `resolve-images.mjs` | data, editions, sources, kernel, cache |
-| `resolve-chart-set.mjs` | data, editions, deploy, kernel |
+| `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 |
@@ -59,292 +59,72 @@ Read strictly: every key is required, an unknown key or a duplicate key is refus
 }
 ```
 
-- `imageRegistry`: `<host>/<namespace>`, where first-party images are addressed (`<imageRegistry>/<subject-id>`).
-- `chartRegistry`: `oci://<host>/<path>`, where chart-set indexes and charts are published. VENDOR-ONLY, paired with `chartPublishers`: both declared or both absent (one alone is refused); a customer data root declares neither, and vendor chart-set code on such a root is refused naming the file and both keys.
-- `chartPublishers`: the chart-set indexes the pin covers; `repo` is recorded in `chart-set.lock.json`. VENDOR-ONLY (see `chartRegistry`).
-- `sourceRepositoryUrlPrefix`: `https://<host>/<organisation>/`, the prefix every first-party `repositoryUrl` must equal (with `<repo>.git`).
-- `sourceAuthUsername`: the non-empty git username source tokens authenticate as (GitHub: `x-access-token`; other forges differ). Required, no default. With `sourceRepositoryUrlPrefix` it is the only declaration of source credentials: the token is read from the environment variable `EVIDENCE_REPOSITORIES_TOKEN`, and it is sent only to repositories under the prefix. A definition source carrying `authTokenEnv` or `authUsername` is refused; a source outside the prefix is fetched with no credential (environment-injected git config and credential helpers are disabled for it). When the definition and `edition-workspace.json` live in the same repository, a pull request can edit both, so the file is no control against the pull request's author: the control is that resolves triggered by pull requests run without secrets.
-- `evidenceTrustPolicy` (mandatory): `{policy, pin}`, two data-root-relative POSIX paths (no `..`, regular no-follow files), or `null`, the explicit statement that this data root declares no policy. Any other key is refused as unknown (the former `required` switch included): no configuration admits a release edition without an armed policy. A data root that declares `null` serves develop editions only. See below.
-
-## Operating notes
+- `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 seal <id>                  # seal image digests
+xema edition check                      # committed locks and indices are current
+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> ...
+
+`check-overrides --overrides <json> --data-root <dir>` takes the data root only (the pin roles it judges against) and refuses every other root flag.
+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> ...
+```
 
-- **Release order (edition protocol coupling).** The CLI is coupled to the kernel's edition protocol, not to the whole kernel package. `@xemahq/contracts` exports the protocol identity as data (`dist/edition-protocol/edition-protocol.json`: `{contentDigest, version}`, the kernel contract authority digest over every kernel source file the protocol's entry subpaths load at runtime, derived from the import graph; `edition-contract.schema.json` states that identity, the entry subpaths and the source paths). `edition-protocol.mjs` declares the versions this CLI supports, each pinned to one digest and vendored under `vendored/`; the library loads no kernel subpath outside the vendored entry subpaths (`edition-protocol.test.mjs`). 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 versions this CLI supports and the version the kernel declares. The digest is a CONSERVATIVE, deterministic stand-in for protocol semantics. Any change to accepted or refused edition semantics MUST change it; a behaviour-preserving refactor MAY change it too, and the cost is a repin, which is accepted. Semantic equivalence isn't computable, so it is never detected. A kernel change outside the protocol's source files needs no CLI release. An edition protocol change does: the CLI release that supports it goes FIRST; only then does the data root repin its kernel authority to a kernel that speaks it.
-- **`xema edition resolve <id> --trusted-write-v3`** writes the lock set, and the flag is the operator's explicit acknowledgement that the images lock is rewritten unsealed (`xema edition seal` writes the digests afterwards). **`xema edition resolve <id> --check`** writes nothing committed (it resolves into a scratch copy) and compares like with like: the resolve timestamp is ignored and the committed images lock is read without its sealed `imageDigest`s, so a sealed lock is not drift.
-- **Git credentials.** `git-source-auth.mjs` is the one place a token becomes git authentication (Basic `<username>:<token>`, `GIT_CONFIG_*`, never argv; the username is a required declared argument with no default). Only the data root declares source credentials: `sourceRepositoryUrlPrefix` and `sourceAuthUsername` in `edition-workspace.json`, with the token in `EVIDENCE_REPOSITORIES_TOKEN`. `holdSource` and `withSourceGitEnv` are the hold and the git environment every network git call on a source passes (the develop freeze's `ls-remote`, the source walk, the indexed checkout), before anything is spawned: a source carrying `authTokenEnv` or `authUsername` is refused, a URL that is not a canonical public https URL is refused, a source under the prefix gets the header scoped to the prefix's origin (an unset token is refused; there is no ambient-credential fallback), and any other source is fetched with no credential: environment-injected git config (`GIT_CONFIG_*`) and askpass programs are removed and the credential helper list is reset. Git runs isolated from the user's own configuration (`GIT_CONFIG_GLOBAL=/dev/null`, `GIT_CONFIG_NOSYSTEM=1`, `HOME` and `XDG_CONFIG_HOME` an empty directory that exists only for the call) and does not follow redirects for a credentialed fetch. The CLI's runtime has its own TypeScript implementation (`src/runtime/sources/kinds/git.ts`) of the same shape, because this library is plain ESM that cannot import compiled TypeScript.
-- **Edition artifacts (one layout for develop and release).** An edition is an OCI artifact at `<registry root>/<channel segment>/xema-edition-<id>` (release: `<root>/editions/xema-edition-<id>`, develop: `<root>/develop-editions/xema-edition-<id>`; both segments and the prefix come from `edition-contract.json` `repositories`), addressed by DIGEST, with artifactType `application/vnd.xema.edition.v1+json` and titled layers (`org.opencontainers.image.title` = file name): `xema-edition.json` (the descriptor) plus `distribution.lock.json`, `images.lock.json`, `authorization.lock.json` and the chart-set lock. `--registry` is the registry ROOT (`<host>[:port]/<namespace>[/...]`, e.g. `registry.example.com/acme`); the CLI appends the channel segment AND `xema-edition-<id>` itself and refuses a root whose last segment is either channel segment or starts with `xema-edition-`. `parseEditionRepository` is the one parser of `<root>/<segment>/xema-edition-<id>`; every reader that fetches an edition or offering artifact by reference refuses a reference whose repository channel is not the channel being resolved, and an artifact whose own stated channel (the catalogue's `channel`) differs from the channel of the repository it was fetched from, before using any content. Tags are for humans only: develop `<snapshot hash>`, release `<coordinate>`. The CLI writes the files to a scratch directory and prints the target; the workflow does `oras push` and `cosign sign` on the digest. Develop: `xema edition develop resolve <id> --pins <file> --out <dir> --registry <root> --engine-image <repo>@sha256:<digest> [--local]`. Release: `xema edition artifact <id> --channel release --registry <root> --coordinate <tag> --engine-image <repo>@sha256:<digest> --out <dir> [--local]`, written from the committed locks and refused when the images lock is not sealed.
-- **The descriptor** (`xema.edition/v1`, strict parse, no other key): `{schema, distributionId, locks[], provenance: {channel: "develop" | "release", pins, workflow: {repository, runId}}, evidenceTrustPolicy: "armed" | "not-armed", engine: {image: "<repository>@sha256:<64 hex>"}}`. `engine.image` is required, digest form only, filled from `--engine-image` (the producer workflow resolves the engine tag with oras; the CLI never resolves tags). `evidenceTrustPolicy` records `armed` when the data root declares a policy and it is armed, `not-armed` otherwise. A release edition's `provenance.pins` is empty (its sources are recorded in its locks). Admission rests on the cosign signature of the manifest digest: readers never branch on `provenance.channel`, and no tool refuses an edition for a channel label, schema name or file name.
-- **Contract.** `edition-contract.json` (`xema.edition-contract/v2`) holds the artifactType, the repository prefix, `repositories` (the namespace segment of each channel: `release` and `develop`), the descriptor file and schema, the lock list, the develop image namespace segment and a `vendoring` statement; it ships in the package. A consumer (xema-deploy, nexus) vendors it BYTE-IDENTICAL from a stated xema-cli commit, never edits it, reads both namespace segments and the prefix only from it, and refuses a contract without `repositories`.
-- **Chart set.** ONE `chart-set.lock.json` (rostered, `schemaVersion: 4`: `publishers[]` with each publisher's `indexDigest`, the registry manifest digest of its index chart, and each chart's version and registry manifest digest; `indexDigest` is `null` exactly for a develop snapshot version `0.0.0-dev.<sha12>`, which has no index chart, and a release lock refuses `null`; a lock of another schema is refused by every reader: re-resolve the chart set with `xema edition chart-set resolve`) serves both channels. A develop edition pins the charts xema-deploy publishes as OCI for the frozen deploy SHA, at version `0.0.0-dev.<first 12 hex of the SHA>` (also the OCI tag). Each producer validates the chart coordinates of its own channel: a release chart set accepts only `-h<16 hex>` versions, a develop one only `-dev.<12 hex>`; a develop chart-set lock copied into a release is refused by `assertReleaseContent`, and `0.0.0-dev.*` index tags are never release candidates; the resolver reads each chart's manifest digest from the chart registry, exactly as a release does, and the lock lists only the publisher whose repository is the deploy pin role's. The CLI computes no chart content digest.
-- **Release lock set.** `assertReleaseEditionTree` checks that the companion chart-set lock is PRESENT beside the distribution and authorization locks. It does not bind the set by a digest, and is not described as hash-bound.
+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.
 
 ## Evidence trust
 
-The descriptor's `evidenceTrustPolicy` has exactly two states, and sealing fails closed (also documented in `edition-contract.json` under `evidenceTrust`, which xema-deploy vendors):
+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>]`.
+- `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.
 
-- `armed`: the data root declares a policy, the policy hashes to its data-root pin, this CLI's verifier is the pinned one, and the policy is ARMED on the channel of the edition.
-- `not-armed`: a develop edition only, whose data root declares no policy or one that is not armed on the develop channel. A release edition never records `not-armed`.
+## Kernel protocol and pins
 
-Arming is judged for ONE channel, the channel of the edition being checked, sealed or written: a channel is ARMED when the policy authorizes a signer for each of the three predicates on that channel and pins the cosign and the git binary. The signers of the other channel count for nothing, so a policy with release signers only is ARMED for a release edition. The develop channel admits not-armed: a develop edition is written when its channel has no signer, and prints one line on stderr (`develop channel: trust policy not armed, evidence is not signature-verified`). A verification of signed develop evidence is satisfied by develop signers only.
+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 exactly protocol v3 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 release edition requires an armed evidence trust policy, with no switch: while the policy is not armed on the release channel (none declared, or declared but UNARMED or PARTIALLY ARMED there), writing a release descriptor or artifact (`xema edition artifact`) is REFUSED with `EvidenceTrustRequiredError`, code `EVIDENCE_TRUST_REQUIRED_UNARMED`, message "a release edition requires an armed evidence trust policy". The descriptor builder itself refuses a release descriptor that is not `armed`, so no route writes one. A channel that is PARTIALLY ARMED is refused on either channel. Both `artifact` and `develop resolve` (and `develop check-existing`) hold the policy to its pin and the verifier to the pinned one before recording a state: a policy edited after pinning or a drifted verifier is refused.
+- `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`.
+- 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 not read: re-index the data root.
 
-`xema edition check` runs one evidence-trust gate, and it FAILS when the editions tree holds a release edition while the policy is not ARMED on the release channel (none declared, UNARMED or PARTIAL): the refusal names the release editions and the repair, and states that no release edition of the data root can be published as an artifact (written by `xema edition artifact`) until the policy is armed on the release channel. A release edition is an edition directory (one holding `xema-distribution.json`) that holds a release lock (`distribution.lock.json` or `authorization.lock.json`); a develop resolve writes nothing into an editions tree. A tree holding no release edition passes for develop-only use with the same statement as a notice. `xema edition seal` is not gated by the policy: nothing sealed leaves without `xema edition artifact`. With no policy declared the gate also refuses a data root that holds an
-undeclared policy (a top-level `*.json` the kernel parses as an offline trust policy, or a
-`trust/` directory). With one declared it parses the policy with the kernel schema, checks the
-Sigstore trusted root the policy itself names (`trustedRootPath`, resolved against the data root,
-and `trustedRootDigest`), checks the pin file, and classifies the authority configuration of each channel: no
-signer on the channel is UNARMED (on the release channel it fails when the tree holds a release edition and otherwise passes with the notice; on the develop channel it passes with the not-armed line), mixed is PARTIAL (refused on either channel, with
-what is unmet), complete is ARMED.
+## Customer editions
 
-The pin file (strict JSON, exact keys) is reviewed data:
+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.
 
-```json
-{ "schemaVersion": 2,
-  "policyDigest": "sha256:<canonical-json digest of the parsed policy>",
-  "verifier": { "bundleDigest": "sha256:<bytes>", "provenanceDigest": "sha256:<bytes>" },
-  "kernelContractAuthority": { "sourceCommit": "<40 hex>", "digest": "sha256:<canonical-json digest of the whole authority>" },
-  "trustedOrasBinaryDigests": ["sha256:<bytes of an oras binary>"] }
+```bash
+xema edition resolve --definition <file> --channel <release|develop> \
+  --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 seal <id> --definition <file> --data-root <dir> --editions-root <dir> --sources-root <dir> --cache-dir <dir>
 ```
 
-`xema edition repin-evidence-trust [--trusted-oras-digest sha256:<64 hex>]…` writes it from the
-declared policy, THIS CLI's built verifier and the kernel contract authority the data root's
-`runtime-image-source-index.json` states. A drifted policy or a verifier that is not the pinned
-one is refused by the check, and a missing built bundle is refused, never skipped.
-
-- **Kernel contract authority.** Evidence is held to the authority the PIN records. The index
-  states it; an index that states another authority is refused
-  (`KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE`), and a data root that declares no evidence trust
-  has no authority to hold evidence to (`KERNEL_CONTRACT_AUTHORITY_UNPINNED`): no evidence verb
-  runs there. The verifier checks the same pin before it reads a statement.
-- **oras is a trusted executable.** On a data root that declares evidence trust, the `oras`
-  binary (`XEMA_ORAS_BIN`, else the first on `PATH`, symbolic links resolved) must hash to one of
-  `trustedOrasBinaryDigests`; a private copy of exactly those bytes is what runs, re-checked on
-  every use. Without the flag a re-pin keeps the reviewed list; a first pin requires it. A data
-  root that declares no evidence trust has no pin: there oras is held to its version only, and
-  the run says so. oras always runs under a scrubbed environment (`HOME` an empty temporary
-  directory, `PATH=/usr/bin:/bin`, `LANG`, `LC_ALL`, `TZ`).
-- **Known limits of the registry reader.** (1) A registry whose Bearer token realm is on another
-  host than the registry itself is refused with the coded error
-  `REGISTRY_TOKEN_REALM_CROSS_HOST` (`RegistryTokenRealmError`), so the pull credential is never
-  sent to a third host. Customer registries that delegate tokens to a separate auth host (for
-  example Docker Hub, or a Harbor or GitLab registry with an external token service) cannot be
-  read; there is no setting that allows it. (2) Because the environment is scrubbed, a proxy or
-  a private CA stated only in environment variables (`HTTPS_PROXY`, `SSL_CERT_FILE`) does not
-  reach oras.
-- **Registry status.** A registry status (404, 401, 403, …) is read only from oras's own error
-  line; any other failure of the run is undecided and is thrown, never read as "absent".
-
-### Why the verifier can be trusted (the binding)
-
-The code under review must be the code that runs. The verifier is ONE file, the bundle
-`dist/edition/verify-image-evidence.bundle.mjs`, built at CLI build time (`scripts/build-evidence-verifier.mjs`,
-exact-pinned esbuild) from the CLI's own sources and its locked `@xemahq/contracts` and `zod`.
-It ships in the npm tarball, which is immutable and integrity-addressed, so anyone can recompute
-its digest from `@xemahq/xema@<version>`; `...bundle.provenance.json` lists every bundled input as
-`{package, version, path in that package, sha256}` and is deterministic (building twice gives
-identical bytes). The reviewed data root PINS the bundle's and the provenance's digests, so
-changing the verifier needs a reviewed data-root commit. At run (`xema edition verify-evidence`,
-which launches the built bundle with a reduced environment) the bundle refuses unless:
-
-1. its own file (realpath of `argv[1]`) and its provenance hash to the data-root pin;
-2. its install path and every ancestor are not group/world writable nor foreign-owned;
-3. the environment carries no `NODE_OPTIONS`, `NODE_PATH`, `DYLD_*`, `LD_*`, `GIT_*`;
-4. the `--kernel` it is given (the built kernel `xema edition check` proves against the authority
-   in `runtime-image-source-index.json`) declares exactly the edition protocol compiled into the
-   bundle, and this CLI supports that protocol (`edition-protocol.mjs`); nothing else about the
-   kernel is compared;
-5. the data root and the editions root are clean git checkouts at an exact HEAD, every file read
-   from them bound to its HEAD blob, graded with a digest-pinned git binary (the completeness
-   signature is bound to the editions checkout's HEAD).
-
-Not here, vendor-side: `require-verified-image-evidence.mjs`, `deliver-images.mjs`,
-`delta-build-plan.mjs`, the evidence producers, and `edition-pin.mjs` (publish plane).
-
-### Product-data sections
-
-The library owns the protocol (the edition schema, the resolution algorithm, the closed
-`installationClass` vocabulary, lock and seal rules, the digest format, the trust-policy
-schema) and never product data. Every product fact below is the data root's, in the same
-file, strictly parsed (unknown, missing or mistyped keys are refused, naming the section).
-A section may be absent where a data root legitimately has none; the operation that needs
-it refuses by name when it runs, and never skips.
-
-| Section | Holds | Needed by |
-| --- | --- | --- |
-| `firstPartySources` | `{ "<repos/\|submodules/ handle>": "<declared source id>" }` | naming a composed-process subject after its source |
-| `platformServiceSources` | per platform service: `name`, `tier`, `installationClass?`, `repo`, `manifestPath`, `manifestName`, `imageKey`, `runtimeBinding` (`null` or `{subjectKind, subjectId}`) | the platform service index (derived from these rows; no edition is read), image subjects, the runtime image source index |
-| `connectorSources` | `repository`, `bindings[{id, path}]`, `nonProductionIds`, `buildInput{consumerRepo, consumerService, destinationRoot}` | biome discovery and the connector cross-repo inputs; absent means no connector repository |
-| `runtimeImageSources` | `supplementalSources` (the host image, standing services, runtime components), `crossRepoBuildInputs`, `buildStepContextDirectories`; the `host`-kind source's repo is the one repo web biomes are delivered from | the runtime image source index, web-biome deliverability |
-| `pinRoles` | the snapshot pin key of the `data`, `kernel` and `deploy` roles | develop snapshots |
-| `confinedBiomes` | `[{biomeId, holds, consequence, admittedEditions}]` | the confinement check; absent means nothing is confined |
-
-`schemaVersion` stays 1: the sections are additive, and a file written for this library is
-refused by a library that predates them (unknown key), never mis-read.
-
-The `develop` freeze flags name roles, not repositories: `--data-sha`, `--kernel-sha`,
-`--deploy-sha` (they were `--distributions-sha`, `--kernel-contracts-sha`,
-`--xema-deploy-sha`; no aliases).
-
-## Evidence verbs (consumed by vendor-ops)
-
-The edition library builds, validates and verifies evidence statements. It NEVER signs: it holds no key, requests no OIDC token, and its cosign runner refuses every subcommand except `verify-blob-attestation`. A caller (vendor-ops) runs `cosign attest-blob`, `oras`, `git` and writes its own step outputs; it reads the JSON these verbs print and never parses a lock, a statement or a policy itself.
-
-Common to all verbs: root flags `--data-root`, `--editions-root`, `--sources-root`, `--kernel` (each verb names the ones it needs); JSON results go to stdout, diagnostics to stderr; exit 0 on success, 1 on any refusal (plus 2 for `plan-refresh` when a refresh is due). The kernel contract authority every statement binds is the one the data root's evidence-trust pin records (see Evidence trust); the trust policy is the one `edition-workspace.json` declares, held to its pin.
-
-| Verb | Arguments | Result |
-|---|---|---|
-| `xema edition chart-set resolve [--check]` | roots `--data-root --editions-root --deploy-root --kernel` | what `node resolve-chart-set.mjs` did: pins `chart-set.lock.json` and every edition's copy to the charts the registry serves; `--check` writes nothing and fails when the pin is stale. The index chart is pinned by the manifest digest the registry served at resolve, and every later read is by that digest; WHO signed the index is not verified by the CLI (the control is the reviewed lock commit) |
-| `xema edition chart-set source-commit` | roots `--data-root --kernel`, env the registry credential variables the data root declares | read-only: for each publisher of the committed `chart-set.lock.json` it fetches the index chart by the LOCKED `indexDigest` (a develop publisher, `indexDigest: null`, is refused) and prints `{"schema":"xema.edition-chart-set-source/v1","publishers":[{"index","repo","version","sourceCommit"}]}` (the `xema.dev/chart-set-source-sha` annotation). It prints nothing and exits non-zero when the registry serves another digest, when the annotation is absent or not 40 lowercase hex, or when the index's roster differs from the charts the lock records for that publisher |
-| `xema edition biome-manifests <id> --json` | `--data-root --editions-root --sources-root --kernel` | `{"schema":"xema.edition-biome-manifests/v1","distributionId","biomes":[{"id","repo","sourceCommit","manifest"}]}` sorted by id: each biome's `xema-biome.json` read at the commit its lock pins; an absent lock or an unreadable manifest is refused with nothing on stdout |
-| `xema edition arming --channel <release\|develop>` | `--data-root --kernel` | read-only: `{"channel","state":"armed\|unarmed\|partial","unmet":[…]}` on one stdout line; exits 0 only when the declared evidence trust policy is `armed` on that channel, 1 otherwise (each unmet entry on stderr; a data root declaring no policy is `unarmed`), 2 for a usage error |
-| `xema edition list` | `--editions-root` | `{"schemaVersion":1,"editions":["<id>",…]}`; an empty root is refused |
-| `xema edition locks <id>` | `--data-root --editions-root --kernel` | `{"schemaVersion":1,"distributionId","contractAuthority","distributionLock","imageLock","repositoryPins":[…]}`, validated as the verifier validates them |
-| `xema edition evidence assemble-input` | `--output <file> --image-repository --manifest-digest --subject-kind --subject-id --source-repo --source-path --source-commit --provenance <file> [--source-manifest-hash] [--source-tree-hash] [--ttl-seconds]`, roots `--data-root --sources-root --kernel`, env `GITHUB_*` workflow context and the registry credential variables the data root declares | writes the producer-input JSON (mode 0600, never overwrites); reads the registry with the pinned oras |
-| `xema edition evidence check-committed` | `--input <file> --repository-root <dir> [--github-output <file>] [--now <epoch-ms>]`, roots `--data-root --kernel` | prints `REUSE`/`PRODUCE <directory>: <reason>`; with `--github-output` appends `reusable`, `evidence-directory`, `reason` |
-| `xema edition evidence plan-refresh` | `--distribution <id>… [--horizon-seconds] [--now] [--github-output <file>] [--kernel-checkout exact\|preview]`, roots `--data-root --editions-root --kernel` | prints the plan; exit 2 when a refresh is due; `--github-output` appends `refresh-due`, `due-subjects`, `total-subjects`, `due-repositories`; producer evidence is read only from the OCI referrers of each locked image. `--kernel-checkout exact` (default) loads the kernel from a clean checkout at the pinned authority commit; `preview` uses the kernel built at `--kernel`, held to no commit: it prints `LOCAL PREVIEW` and refuses `--github-output` |
-| `xema edition evidence statement producer stage` | `--input <file> --staging <abs dir> --github-repository --github-ref --github-sha --github-workflow-ref`, roots `--data-root --kernel` | creates the staging directory with `statements/<stem>.json`; prints the signing plan |
-| `xema edition evidence statement producer accept` | the `stage` flags plus `--output <abs dir> --cosign <abs path>` | verifies each bundle, builds the output from the statements the input derives and the canonical verified bundles ONLY (the staging must hold exactly what `stage` recorded), writes `producer-evidence.json`, and removes the staging whether it succeeds or refuses; the cosign version is the trust policy's `cosignVersion`; prints `{"schemaVersion":1,"kind":"producer","outputDirectory","producerEvidence":[…]}` |
-| `xema edition evidence statement completeness stage` | `--distribution --staging <abs dir> --release-sequence --release-source-commit --run-id --run-attempt --issued-at --expires-at --signer-repository --signer-ref --signer-workflow-path --github-repository --github-ref --github-sha --github-workflow-ref `, roots `--data-root --editions-root --kernel` | stages the edition's producer evidence under `producers/` and `completeness/statement.json`; prints the signing plan |
-| `xema edition evidence assemble-set` | the completeness `stage` flags plus `--evidence-root <abs dir> --cosign <abs path>` | re-resolves the producer evidence (it must equal the staged copy), verifies the signed completeness bundle, writes `evidence-set.json`, builds the evidence root from the derived files ONLY (the staging must hold exactly what `stage` recorded) and removes the staging whether it succeeds or refuses; prints `{"schemaVersion":1,"kind":"evidence-set","distributionId","evidenceRoot","evidenceSetPath","producerBundles","completenessStatementDigest"}` |
-| `xema edition evidence statement entitlement stage` | `--distribution --evidence-root <dir> --staging <abs dir> --customer --mode [--target-registry] --idempotency-key --run-id --run-attempt --issued-at --expires-at --signer-repository --signer-ref --signer-workflow-path --github-repository --github-ref --github-sha --github-workflow-ref`, roots `--data-root --kernel` | writes `entitlement/statement.json`; prints the signing plan |
-| `xema edition evidence statement entitlement accept` | the `stage` flags plus `--output <abs dir> --cosign <abs path>` | verifies the bundle, writes `entitlement.json`, builds the output from the derived files ONLY (the staging must hold exactly what `stage` recorded) and removes the staging whether it succeeds or refuses; prints `{"schemaVersion":1,"kind":"entitlement",…,"evidence":{…}}` |
-| `xema edition evidence oci attach-plan` | `--evidence-directory <abs dir> [--input <file>]`, roots `--data-root --kernel` | validates a produced evidence directory (with `--input`, against the statements that input builds) and prints `{"schemaVersion":1,"kind":"oci-attach-plan","evidenceDirectory","imageRepository","subjectDigest","subject","artifactType","distributionSpec","annotations":{…},"files":[{"path","mediaType"}]}`: the operands of `oras attach`, run from the evidence directory |
-| `xema edition evidence oci validate` | `--evidence-directory <abs dir> --manifest <file> --subject-digest <digest> [--input <file> --cosign <abs path> [--now <epoch-ms>]]`, roots `--data-root --kernel` | holds a pulled artifact (`oras pull`) to its manifest (`oras manifest fetch`); prints `{"schemaVersion":1,"kind":"oci-evidence","subjectDigest","created","subjects":[…],"matchesInput","remainingSeconds","reusable"}`. The last three are `null` without `--input`; with it every bundle is verified against the input's signer and a bundle that does not verify is a refusal |
-| `xema edition evidence oci backfill-plan` | `--distribution <id>… --producer-repository-root <abs dir>…`, roots `--data-root --editions-root --kernel`, env the registry credential variables the data root declares | prints `{"schemaVersion":1,"kind":"oci-backfill-plan","items":[{"status":"missing-git\|present\|missing","subjectKind","subjectId","imageRepository","subjectDigest","artifactDigest","attach"?}]}`; a `missing` item carries its attach plan; exit 2 unless every item is `present` |
-| `xema edition index runtime-image-source --repin-contract-authority --kernel-commit <40-hex>` | roots `--data-root --sources-root --kernel`; `--kernel-commit` REQUIRED (the kernel commit the authority moves to; refused with the usage when absent); `[--kernel-root <absolute-checkout>]` | replaces ONLY `contractAuthority` of the committed `runtime-image-source-index.json` with the authority read from the kernel checkout AT THE STATED COMMIT: the checkout must be clean, at the expected origin, and its HEAD must equal `--kernel-commit` (else refused, naming both commits), and that commit is what `contractAuthority.sourceCommit` records and what `xema edition repin-evidence-trust` then pins as `kernelContractAuthority.sourceCommit`. A bootstrap `--trusted-write` (no committed contract authority) chooses a commit the same way and takes the same required flag; every other mode refuses it. It validates and rewrites the index; every repository pin and subject is identical before and after. It writes the move on stdout and the owed follow-ups on stderr: `xema edition repin-evidence-trust`, re-resolving every edition (each `images.lock.json` carries the authority), and that signed producer statements made under the old authority no longer verify. `--kernel-commit` holds the checkout's HEAD to the stated commit and nothing more: there is NO ancestry or remote check, so a never-pushed local commit passes if its SHA is stated; the control is the reviewed data-root diff that carries the new `sourceCommit` |
-| `xema edition source-closure` | `--repo <repo> --path <dir> --commit <40 hex>`, roots `--sources-root --kernel` (the hash implementation is held to the kernel) | `{"schemaVersion":1,"repo","directory","commit","treeAlgorithm","treeHash","buildable","lockfileBlobId","closure":[{"directory","treeHash"}]}`: the facts a content coordinate is framed from |
-| `xema edition verify-evidence <id>` | see Evidence trust; `--descriptor <absolute path of the edition descriptor being verified>` (required: its `distributionId` must be the requested id and its `provenance.channel` is the channel whose signers may vouch for the evidence; it is held outside the graded checkouts like `--state`); plus `[--json]` (stdout is then exactly one `{"schema":"xema.edition-evidence-verification/v1","distributionId","channel","releaseSequence","statements":[{"predicateType","subject","statementDigest"}]}` document, where `statementDigest` is the digest of the verified statement, not of the image; the human text goes to stderr, and a failed verification prints no JSON); plus, given together or not at all, `--entitlement <evidence-root-relative path of an entitlement.json> --entitlement-workflow-sha <40-hex git sha> --customer <id> --mode <mode>` and optionally `--target-registry <registry>`: the delivery entitlement `accept` wrote is verified with the release (`--entitlement-workflow-sha` is the exact commit of the workflow run that signed the entitlement, the one its certificate is held to; it is stated by the caller and never read from the evidence; the statement and bundle are read from the directory holding `entitlement.json`), and the verification document then ends with the entitlement statement | the in-repository gate and the release-checkout grading are this verifier; there is no second one. Its result is its exit status, the advanced replay state and, with `--json`, the verification document on stdout: it writes no "already verified" file and has no file-output flag. A delivery entitlement verifies only as part of this run: a refused entitlement refuses the whole verification and the replay state does not advance. `entitlement.json` is `{schemaVersion: 2, distributionId, customerId, mode, targetRegistry, idempotencyKey, distributionStatementDigest, evidence}` with exactly those keys (`evidence` is the Sigstore evidence descriptor); every field but `evidence` is an unauthenticated convenience that must agree with the flags and the verified completeness statement, and the signed statement stays the authority |
-
-The signing plan (stdout of every `stage`):
+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.
 
-```json
-{"schemaVersion":1,"kind":"producer|completeness|entitlement","root":"<staging dir>","predicateType":"<uri>",
- "signer":{"certificateIdentity":"…","oidcIssuer":"…","githubWorkflow":{"repository":"…","ref":"…","path":"…"}},
- "certificateWorkflowSha":"<40 hex>","statements":[{"statementPath":"<relative>","bundlePath":"<relative>"}]}
-```
+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.
 
-For each entry the caller runs `cosign attest-blob --yes --statement <root>/<statementPath> --bundle <root>/<bundlePath> --new-bundle-format <root>/<statementPath>` and then the matching `accept` (or `assemble-set`) with the SAME flags it staged with. `accept` re-derives every statement from those flags and refuses staged bytes that differ, so nothing but what the library built can be accepted; it rewrites the bundle as canonical JSON, requires its payload to be exactly the statement bytes, and runs `cosign verify-blob-attestation` against the plan's signer at `certificateWorkflowSha`. The staging directory must not exist before `stage`; the output is built in a private sibling `<output>.accepting-<pid>` on the output's filesystem and renamed into place. `accept` removes the staging whether it succeeds or refuses (a refusal of its arguments before the first read leaves it), so a signed-but-unaccepted bundle is never left behind; stage and sign again after a refusal.
 
-## Tests
+### Adapter bundles against the adapter host
 
-`node --test "edition/*.test.mjs" "edition/*-contract-tests.mjs"` (`pnpm run test:edition`).
-Tests build throwaway roots with `test-fixtures/workspace.mjs`. The kernel is the
-CLI's own installed `@xemahq/contracts`; nothing is supplied from outside and no test
-skips. The two sealing cases run the real openfga/cli v0.8.1 and FAIL, naming
-`XEMA_FGA_CLI`, when it is unset (CI installs it by checksum). `no-vendor-literals.test.mjs` fails on any organisation or
-registry literal in a shipped file.
+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).
 
-## Customer editions
+## Tests
+
+```bash
+pnpm run test:edition     # node --test "edition/*.test.mjs" "edition/*-contract-tests.mjs"
+```
 
-A customer edition is resolved against a CATALOGUE: `catalogue.json`, a titled layer of an offering's edition artifact
-(`xema.edition-catalogue/v1`: `offeringId`, `channel` (provenance only), `biomes`, `platformServices`, `images`,
-`chartSet`, `contractAuthority`, `ceiling`). The catalogue is the ceiling: it supplies availability, pins, digests and
-the chart-set, and never adds a component. The resolved set is the customer's `{biome}` selections, every
-`installationClass: core` entry and the transitive declared dependencies.
-
-    xema edition resolve --definition <file> --channel <release|develop> \
-      --data-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir> --out <dir> \
-      --source-image <source>=<registry>/<prefix> [--catalogue-username <u> --catalogue-token-env <VAR>]
-
-The catalogue is the one pinned for the channel in `catalogue.pin.json`, in the SAME directory as the definition file:
-`{"schemaVersion": 1, "develop": "oci://<repository>@sha256:<64 hex>" | null, "release": "oci://<repository>@sha256:<64 hex>" | null}`
-(exact keys, both channel keys present, null = not produced on that channel; the repository of the reference under a key must be
-that channel's repository). A null pin for the requested channel is refused. There is no `--catalogue` flag; passing one is an unknown-flag error.
-`catalogue.pin.json` is written by the customer (or for it, by a commit to its repository), and until the kernel repin the
-catalogue it names carries no vendor signature and no identity check: the digest in the pin is the only thing that binds it.
-`develop freeze-sources --definition` asks only source URLs that are canonical HTTPS repository URLs under the data root's
-`sourceRepositoryUrlPrefix`; a definition naming any other origin is refused before a network call, so the source token is never sent there.
-A definition source carrying `authTokenEnv` or `authUsername` is refused on every path that fetches it: source credentials are declared only by the data root (`sourceRepositoryUrlPrefix` + `sourceAuthUsername`, token `EVIDENCE_REPOSITORIES_TOKEN`), and `resolve` fetches a source outside the prefix with no credential.
-`--registry` refuses a root with a `.` or `..` path segment.
-
-`--out` is the customer's editions root (`<out>/<id>/` receives the four locks). `--data-root` holds the customer's
-`edition-workspace.json`. The definition allows `{biome}` selectors (the same per-biome options a vendor offering's selector takes in the kernel
-schema, `installPolicy` and `mandatory`, and nothing else), `sources[]` (no registry), `trustCeiling` and
-`imageRegistryMirror`; `extends`, `exclude`, tier/origin/class selectors, `platformServices`, `visibility` and a source
-registry are refused.
-
-Ownership rules of the definition (the kernel's `parseCustomerEditionDefinition` and `customerTrustCeilingIssues`; `customer-definition.mjs` only calls them):
-`sources[].ref` is required and names a branch or a tag; a commit id (any full 40- or 64-hex git object id) is refused,
-because the seal records the resolved commit in the lock (the develop `--pins` file still supplies commits). `trustCeiling`
-is required when the definition declares `sources[]` and refused when it does not. It must assign every customer-source
-biome (a biome drawn from the definition's own `sources[]`) exactly once: a missing biome, a biome assigned twice and an
-extra biome that is not customer-sourced are refused.
-
-The vendor's trust domain is closed to a customer edition, by three refusals the CLI makes:
-- a `trustCeiling` assignment whose domain is the kernel's first-party domain is refused when the definition is parsed, naming the biomes and the domain;
-- a biome drawn from a declared `sources[]` entry (of any edition) whose manifest declares an origin other than third-party (`xema.trustTier`) is refused, naming the source and the biome;
-- the catalogue's `ceiling` bounds the resolve. Its `trustPolicy` (origin allow list), when stated, is the one the resolve applies to every biome of the lock.
-  Its `trustCeiling`, when stated, is written onto the vendor's rows of the customer lock, and for a customer-source biome it admits one domain: the domain the catalogue
-  assigns that biome when it names it, otherwise any domain the catalogue assigns to nothing. A definition that names another domain is refused, naming the biome and both domains.
-  A `null` member of `ceiling` bounds nothing.
-
-Handoff to the customer's registry: `oras cp` the catalogue artifact and the vendor images by digest, pin the mirrored
-catalogue in `catalogue.pin.json`, and declare `imageRegistryMirror: {complete: true, map: [{source, target}]}`. Prefixes match whole
-path segments; the digest never changes and no signature is re-verified at the mirrored ref (the customer's seal is the
-trust anchor and deploy is digest-anchored).
-
-The chart-set is copied whole from the catalogue: it states which deploy charts are available, not which components are
-selected, so it adds no component. `trustCeiling` has the kernel shape `{assignments: [{domain, biomes}]}`.
-
-### Locks, sealing and the catalogue's tree ids
-
-`resolve` writes the UNSEALED lock (`unsealedSchema`); `seal` attaches each biome's `biomeContentHash` and stamps
-`schemaVersion` 5, the only grammar. The hash is recomputed by `seal` AND by the verify step from the biome's
-`sourceManifestHash`, its git tree id at the pinned commit and the sorted image subject digests, through the kernel's
-`computeBiomeContentHash`; a mismatch (a tampered hash, 64 arbitrary hex digits, a changed manifest, tree id or image
-digest) is refused, naming the biome. `resolve --check` compares the unsealed projection byte for byte.
-
-A customer holds no checkout of the vendor's sources. `catalogue.json` therefore carries `sourceTreeIds` (each vendor
-biome's tree id at its pinned commit, written from the real tree by `edition catalogue` / `edition artifact`), and the
-customer's seal takes that tree id as an INPUT ON THE CATALOGUE'S AUTHORITY: it is not source verification, and the
-refusal text says so. A vendor biome absent from the catalogue is refused, not skipped.
-
-    xema edition seal <id> [--definition <file> [--catalogue-username <u> --catalogue-token-env <VAR>]] \
-      --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir>
-
-Mirror runbook (`imageRegistryMirror`): 1. `oras cp` the catalogue artifact and every vendor image BY DIGEST into the
-customer's registry. 2. Pin the mirrored catalogue digest in `catalogue.pin.json`. 3. Declare
-`imageRegistryMirror: {complete: true, map: [{source, target}]}` (whole path segments; `complete: true` refuses a vendor row no
-entry covers). 4. Resolve and seal: digests are unchanged, so the seal's hashes are unchanged; no signature is
-re-verified at the mirrored ref.
-
-### Develop customer edition
-
-A customer-owned develop edition is produced with CLI verbs only. Each takes `--definition <file>`; the develop catalogue is the
-`develop` pin of `catalogue.pin.json` beside it.
-
-    xema edition develop freeze-sources --definition <file> --out <file>
-    xema edition develop kernel-commit --definition <file> [--catalogue-username <u> --catalogue-token-env <VAR>] --data-root <dir>
-    xema edition develop resolve --definition <file> --pins <file> --out <dir> --registry <root> --engine-image <repository>@sha256:<digest> \
-      --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir> --cache-dir <dir> \
-      [--source-image <source>=<registry>/<prefix>]... [--catalogue-username <u> --catalogue-token-env <VAR>] [--local]
-    xema edition develop target --definition <file> --pins <file> --registry <root>
-    xema edition develop check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest> \
-      --data-root <dir> --kernel <dir>
-
-`freeze-sources` writes (exclusively) the `--pins` file: exactly one `sources/<name>` commit per source the definition declares,
-the head of `refs/heads/develop` of each source repository, resolved once (token from `EVIDENCE_REPOSITORIES_TOKEN`).
-`kernel-commit` fetches the pinned develop catalogue and prints its `contractAuthority.sourceCommit` (one 40-hex line): the commit
-a workflow checks the kernel contracts out at; it needs no `--kernel` and no `--sources-root`. `target` prints the develop target
-(the tag covers the pinned catalogue digest). `check-existing` does for a customer artifact what it does for a vendor one, and
-additionally refuses a descriptor whose `catalogue` provenance pin is not the pinned develop catalogue digest.
-
-Every customer DEVELOP verb works on a data root holding only `edition-workspace.json`, and none reads the vendor's indices,
-pins or pin roles. The release seal of a customer edition (`xema edition seal <id> --definition ...`) still reads the vendor's
-`runtime-image-source-index.json` from the data root and is not supported before the kernel repin. It takes `--data-root`,
-`--editions-root`, `--sources-root`, `--kernel` and `--cache-dir`, and refuses any other root flag (for example `--deploy-root`),
-naming the roots it takes. A customer whose sources build images also commits `image-registry-credentials.json` in its editions root
-(the registries its own images are verified against); when its own image rows are sealed and that file is absent, the resolve
-is refused naming the file and the root. A customer with no sources, or whose sources build no image, needs no file in its
-editions root. A customer verb refuses a root flag it does not take, naming the roots it takes (`target` takes none).
-
-The id is the definition's (no positional id). `--pins` holds exactly one `sources/<name>` commit per source the
-definition declares (the customer's own repositories; the vendor's pins are the catalogue's). The digest of the catalogue
-artifact is frozen into the descriptor's `provenance.pins` as `catalogue: "sha256:<64 hex>"` (typed per key: every other
-pin is a 40-hex commit), so the snapshot-hash tag covers it. The artifact is the one edition layout (`xema.edition/v1`,
-the descriptor plus the four locks) at `<root>/<develop segment>/xema-edition-<id>`. Vendor image rows arrive sealed from the
-catalogue and are neither re-homed nor re-verified; only the customer's own rows are re-homed to the develop image repositories,
-verified there for their required platforms and sealed with the digest the registry served. The images lock is parsed once, as
-the merged lock (vendor rows plus own rows). On the release channel the own rows stay unsealed in the merged lock. A customer artifact is not an
-offering and carries no `catalogue.json`. `edition-contract.json` lists `catalogue.json` under `offeringLayers` (a layer
-of an offering artifact, not a lock) and the `catalogue` pin under `provenancePins`.
+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,107 @@
+// 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 { 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 Error {
+  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

@@ -0,0 +1,41 @@
+// 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;
+}