@xemahq/xema 0.25.1 → 0.27.0

package/README.md

@@ -87,7 +87,7 @@ The wizard walks you through:
   **external** (paste your connection URL), and each external URL is
   **connection-tested** (reachability),
 - **your own biomes** — add git repo(s) as sources (composed with the edition at
-  launch), or use `xema dist build` for a full custom distribution.
+  launch).
 
 Every generated config is validated against the schema before it's written, so it
 can never be one `xema up` would reject.
@@ -256,6 +256,39 @@ sources must be regular, non-symlink files with no group/other permissions
 `xema.config.yaml`. The Helm substrate does not accept launcher-resolved
 secrets: configure Kubernetes Secrets through each service chart instead.
 
+### Credential custody — the local OpenBao
+
+The credential broker (`credential-broker-api`) refuses to boot without a
+deployment-selected custody provider. On the container and native substrates
+`xema up` therefore runs its own single-node OpenBao (`xema-openbao`, the
+official `openbao/openbao` image pinned by digest, integrated raft storage on the
+`xema-openbao-data` volume, published on `127.0.0.1:8200` only) whenever the
+roster contains the broker. On the first launch the CLI initialises it with a
+single unseal share and stores the unseal key and root token, encrypted, in
+`~/.xema/installations/<installation-id>/openbao-custody.json` (directory
+`0700`, file `0600`); they are never printed. Every later launch only unseals
+from the stored key, so `xema up` is idempotent. The CLI mounts a KV v2 engine
+at `xema-local`, writes a policy limited to `xema-local/{data,metadata}/xema/*`,
+and mints a scoped (non-root) token for the broker on each launch. The broker
+alone receives:
+
+| Variable | Value |
+| --- | --- |
+| `CUSTODY_PROVIDER_REF` | `openbao` |
+| `OPENBAO_ADDRESS` | `http://xema-openbao:8200` (container) or `http://127.0.0.1:8200` (native) |
+| `OPENBAO_AUTH_METHOD` | `token` |
+| `OPENBAO_TOKEN` | the scoped broker token |
+| `OPENBAO_MOUNT_PATH` | `xema-local` |
+
+`xema down` keeps the vault and its keys; `xema down --purge` removes both
+together. A vault whose keys are missing (or keys whose vault is gone) is
+reported with that instruction rather than re-initialised. The Helm substrate
+does not start a vault: the chart selects the provider.
+
+`xema dev` does not start a vault. It expects an OpenBao on `127.0.0.1:8200`
+(pre-flight checks the port) and an `OPENBAO_TOKEN` in your environment; it
+defaults the rest of the contract above.
+
 ### Realtime dev
 
 Xema always runs the `distributed` model: every service is its own process and
@@ -327,46 +360,46 @@ What a biome _does_ (services, skills, capabilities, agents) is wholly open —
 only the bundle _shape_ is standardized, so every author builds the same way and
 any source resolves the same way.
 
-## Compose a distribution — `xema dist build`
-
-Build **your own platform**: take a base edition's first-party biomes and add
-the ones you bring (your git repos / workspace dirs). The composition is
-validated by the real distribution resolver (dependency closure + trust +
-operator rules), then written as a distribution + a launch config:
-
-```bash
-xema dist build --id acme-platform --base oss \
-  --platform linux/amd64 \
-  --git acme=https://github.com/acme/xema-biomes.git \
-  --source local=./my-biomes \
-  --config-out acme.config.yaml
-#   or read sources from an existing config:  --config xema.config.yaml
-#   --no-allow-third-party rejects non-first-party biomes (default: allowed)
-```
-
-`--platform` is **required and has no default**. It declares the OCI platform(s)
-every runtime image of your distribution must be published for — the value
-delivery verifies against the real registry manifest. Pass it repeatedly or
-comma-separated (`--platform linux/amd64 --platform linux/arm64`, or
-`--platform linux/amd64,linux/arm64`); the closed set is `linux/amd64` and
-`linux/arm64`. It is not inherited from `--base`: a base edition's
-`distribution.lock.json` does not carry the platform set, and guessing one would
-silently commit an appliance composition to an architecture its hardware cannot
-run. State what your images are actually built for.
-
-It writes `~/.xema/distributions/<id>/{xema-distribution.json,distribution.lock.json}`
-(the composed recipe + resolved record) and, with `--config-out`, a
-`xema.config.yaml` (base edition + your sources). Then:
+## Resolve and check an edition — `xema edition`
 
 ```bash
-xema dev --config acme.config.yaml   # native — your biomes run from source
-xema up  --edition acme-platform     # first-party biomes by edition (your composition)
+xema edition resolve <id> [--check]      # the release lock set (distribution, authorization, chart-set, images)
+xema edition seal <id>                   # seal the image digests
+xema edition develop <subcommand> ...    # develop editions: resolve a snapshot into the edition artifact files
+xema edition artifact <id> --channel release --registry <ns> --coordinate <tag> --engine-image <repo>@sha256:<digest> --out <dir>
+                                         # the release edition artifact files, from the committed sealed locks
+xema edition index biome|platform-service|runtime-image-source [--check]
+xema edition check                       # the committed locks and indices are current
+xema edition why <id> <biome>            # why a biome is in an edition
+xema edition verify-platforms <id>       # the registry serves every required platform
+xema edition checkout-sources            # check out the sources the image index pins
 ```
 
-Your composed distribution also shows up as an edition in `xema init` and
-`xema up --edition <id>`. User biomes are `third-party` by origin and launch via
-the source registry (which resolves their source roots); building container
-images for your own biomes is a separate step.
+Every verb takes the six roots (`--data-root`, `--editions-root`, `--sources-root`, `--kernel`,
+`--deploy-root`, `--cache-dir`); see `edition/README.md` for which verb needs which.
+
+### The edition protocol — what ties this CLI to a kernel
+
+The CLI is coupled to the kernel's **edition protocol**, not to the whole kernel package.
+`@xemahq/contracts` exports the protocol's identity as data
+(`@xemahq/contracts/edition-protocol/edition-protocol.json`): a version and a content digest over
+the exact bytes of every kernel source file the protocol's entry subpaths load at runtime (the
+schemas and every refinement, parser, resolver and composer behind them), derived from the
+kernel's import graph. This CLI declares the protocol versions it supports, each pinned to one
+digest, and vendors each supported contract (the identity, the entry subpaths and the source
+paths); it loads no kernel subpath outside those entry subpaths. `xema edition check` and every
+other verb compare only that identity with the `--kernel` they are given, and refuse any other,
+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 keeps the identity, so it needs no CLI
+release. An edition protocol change needs a CLI that supports it, so the order is: **the CLI
+release that supports the new protocol goes first, then the data root repins its kernel
+authority** to a kernel that speaks it.
 
 ## Author biomes & run capabilities