@xemahq/xema 0.13.0 → 0.14.0

package/README.md

@@ -86,6 +86,23 @@ xema status                # show launcher-owned workloads + health
 xema logs <service> -f     # stream a service's logs
 ```
 
+The launcher and automation use the same compiled desired state. The
+installation command group exposes that lifecycle directly:
+
+```bash
+xema installation plan                    # deterministic redacted change plan
+xema installation apply --detach           # reconcile through the same launcher as `xema up`
+xema installation status                  # desired vs applied vs observed drift
+xema installation support-bundle          # redacted JSON + SHA-256 integrity manifest
+```
+
+Destructive transitions are refused unless explicitly reviewed and authorized
+with `--allow-destructive`; rejected identity/schema transitions and currently
+unsupported profiles remain fail-fast. Last-applied state is atomically stored
+under `~/.xema/installations/<installation-id>/`, while secret values are
+resolved before source or deployment side effects and are never persisted in
+plans or support bundles.
+
 ### Topology — `xema.config.yaml`
 
 The launcher reads an optional `xema.config.yaml` (or `~/.xema/config.yaml`)
@@ -96,17 +113,24 @@ provide the URL), or `disabled`:
 ```yaml
 edition: oss
 infra:
-  postgres:    { mode: managed }
-  redis:       { mode: managed }
-  etcd:        { mode: managed }
-  keycloak:    { mode: external, url: https://sso.corp/realms/xema, realm: xema }
+  postgres:
+    {
+      mode: external,
+      url: postgresql://xema@db.corp:5432,
+      secretRef: postgres-password,
+    }
+  redis: { mode: managed }
+  etcd: { mode: managed }
+  keycloak: { mode: external, url: https://sso.corp/realms/xema, realm: xema }
   objectStore: { mode: external, url: https://s3.corp }
-  search:      { mode: managed }
-  temporal:    { mode: managed }
+  search: { mode: managed }
+  temporal: { mode: managed }
+secrets:
+  postgres-password: { from: env, env: XEMA_POSTGRES_PASSWORD }
 app:
-  substrate: container        # container | native
-  include: [ all ]            # all | <tier> | [service ...]
-  features: []                # curated capability bundles
+  substrate: container # container | native
+  include: [all] # all | default | minimal | <tier> | [service ...]
+  features: [] # curated capability bundles
   web: { enabled: true }
 ```
 
@@ -114,14 +138,38 @@ app:
   (`imageRef:contentHash`) and runs them on a shared network, after bringing up
   and bootstrapping managed infra — works without a monorepo checkout.
 - **`native`**: runs services as host processes against a built monorepo (the
-  contributor inner loop). Equivalent: `xema serve --profile single-instance`.
+  contributor inner loop). Equivalent: `xema serve --substrate single-instance`.
 - **`helm`**: deploys to Kubernetes via `helm upgrade --install` (the appliance /
-  cluster target). Equivalent: `xema serve --profile appliance`.
+  cluster target). Equivalent: `xema serve --substrate appliance`.
 
 `xema up` fails fast on a missing required secret, an unreachable `external`
 dependency, or a disabled-but-mandatory infra component — never a silent
 degradation.
 
+Managed local PostgreSQL and object-store credentials are generated uniquely
+per installation and retained under
+`~/.xema/installations/<installation-id>/managed-local-credentials.json` with
+directory mode `0700` and file mode `0600`. Repeated and concurrent launches
+reuse the same credentials; values are not written to config or command
+arguments. `xema down` preserves them with the data volumes, while
+`xema down --purge` removes both. A named volume created by an older CLI with
+fixed development credentials fails fast and requires that explicit purge
+before its first launch with credential custody.
+
+External PostgreSQL credentials are never defaulted or persisted in the
+endpoint URL. Put the username in the URL and source the password through
+`secretRef`. A referenced secret must be declared under
+`secrets` and resolve from `env`, `file`, or an interactive masked `prompt`
+before Xema creates any deployment resources.
+
+Secret names that are valid environment-variable names are intentionally
+injected into every native/container service in the launch. Use a non-environment
+name such as `postgres-password` for launcher-only `secretRef` values. File
+sources must be regular, non-symlink files with no group/other permissions
+(`0600` or stricter); relative paths resolve from the directory containing
+`xema.config.yaml`. The Helm substrate does not accept launcher-resolved
+secrets: configure Kubernetes Secrets through each service chart instead.
+
 ### Realtime dev
 
 Xema always runs the `distributed` model: every service is its own process and
@@ -143,8 +191,8 @@ lone service still boots a correct graph:
 
 ```bash
 xema dev agent-session-api memory-api     # native: just these two (+ prerequisites)
-xema up   --only app-runtime-api          # container: one service (+ prerequisites)
-xema serve --profile cluster --only audit-log-api
+xema up   --only app-platform-api          # container: one service (+ prerequisites)
+xema serve --substrate cluster --only audit-log-api
 ```
 
 ### Biome sources — pull biomes from many origins
@@ -155,22 +203,22 @@ each with its own auth — declared in a `sources:` block:
 
 ```yaml
 sources:
-  - name: workspace                       # local working tree (monorepo): always wins
+  - name: workspace # local working tree (monorepo): always wins
     kind: workspace
-  - name: cultivars                       # a pinned edition lock
+  - name: cultivars # a pinned edition lock
     kind: distribution
     edition: cultivars
-  - name: acme                            # a client's OWN biome git repo (private)
+  - name: acme # a client's OWN biome git repo (private)
     kind: git
     url: https://github.com/acme/xema-biomes.git
     ref: v2.1.0
-    authTokenEnv: GIT_TOKEN_ACME          # env-var NAME, never the secret
+    authTokenEnv: GIT_TOKEN_ACME # env-var NAME, never the secret
 ```
 
 Precedence: **`workspace` > other sources (declared order) > base distribution**.
 In a monorepo checkout the workspace source always wins, so `xema dev` runs your
 local edits with **no publish** and **no token** required. Tokens for private
-sources are referenced by env-var *name* (the `biome-fetcher` convention) and
+sources are referenced by env-var _name_ (the `biome-fetcher` convention) and
 resolved from the environment or a git-ignored `~/.xema/credentials.env` — never
 inlined in config. `npm`/`oci` sources are install-time (the `xema biome install`
 path); `workspace`/`distribution`/`git` boot directly from `xema up`/`dev`.
@@ -189,8 +237,8 @@ Sources discover biomes by walking for `xema-biome.json` — a repo may hold ONE
 biome at its root or MANY nested; both are valid layouts of the **same
 standard**. A biome is a directory with a manifest at its root; its services
 live at the manifest-declared `ships.apis[].path` (convention `./api/<name>`).
-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
+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`

package/dist/assets/boot-graph.json

@@ -1,12 +1,12 @@
 {
-  "$comment": "Declarative source of truth for system-authority STARTUP dependencies (Gate A, plan .claude/plans/federated-crunching-thompson.md Phase 1.5). Consumed by tooling/boundaries/check-boot-graph.mjs. Human-prose rationale + degraded behavior lives in docs/architecture/system-boot-graph.md — keep the two in lockstep. INVARIANT: no service may HARD-REQUIRE a higher- or same-boot-tier service at startup; the hard-require graph must be acyclic. 'startupRequires' lists ONLY hard boot-blocking deps (the service refuses to come up / crash-loops until each is reachable). Lazy/at-request-time deps are NOT listed here — they are captured as 'degraded' prose in the doc. Boot tiers (lower boots first): infra(-1) < kernel(0) < system(1) < base(2) < platform(3) < third-party(4). 'infra' = submodules + external generic plane (identity-api, event-hub, secrets, llm-gateway, keycloak, postgres, valkey, kernel-state/etcd) which always boot before the Xema service mesh and can never participate in a service-mesh cycle.",
+  "$comment": "Declarative source of truth for system-authority STARTUP dependencies (Gate A, plan .claude/plans/federated-crunching-thompson.md Phase 1.5). Consumed by tooling/boundaries/check-boot-graph.mjs. Human-prose rationale + degraded behavior lives in docs/architecture/system-boot-graph.md \u2014 keep the two in lockstep. INVARIANT: no service may HARD-REQUIRE a higher- or same-boot-tier service at startup; the hard-require graph must be acyclic. 'startupRequires' lists ONLY hard boot-blocking deps (the service refuses to come up / crash-loops until each is reachable). Lazy/at-request-time deps are NOT listed here \u2014 they are captured as 'degraded' prose in the doc. Boot tiers (lower boots first): infra(-1) < kernel(0) < system(1) < base(2) < platform(3) < edge(4). 'infra' = submodules + external generic plane (identity-api, event-hub, secrets, llm-gateway, keycloak, postgres, valkey, kernel-state/etcd) which always boot before the Xema service mesh and can never participate in a service-mesh cycle.",
   "tiers": {
     "infra": -1,
     "kernel": 0,
     "system": 1,
     "base": 2,
     "platform": 3,
-    "third-party": 4
+    "edge": 4
   },
   "infraServices": [
     "identity-api",
@@ -18,27 +18,49 @@
   "services": {
     "authorization-api": {
       "tier": "system",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api",
+        "org-database-pool-api"
+      ]
+    },
+    "canopy-api": {
+      "tier": "base",
+      "startupRequires": [
+        "identity-api",
+        "org-database-pool-api"
+      ]
     },
     "object-registry-api": {
       "tier": "system",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api"
+      ]
     },
     "capability-registry-api": {
       "tier": "system",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api",
+        "org-database-pool-api"
+      ]
     },
     "user-hub-api": {
-      "tier": "system",
-      "startupRequires": ["identity-api"]
+      "tier": "base",
+      "startupRequires": [
+        "identity-api",
+        "org-database-pool-api"
+      ]
     },
     "public-gateway-api": {
       "tier": "system",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api"
+      ]
     },
     "xema-shell-api": {
       "tier": "system",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api"
+      ]
     },
     "xema-capability-router": {
       "tier": "system",
@@ -46,27 +68,47 @@
     },
     "biome-host-api": {
       "tier": "system",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api",
+        "org-database-pool-api"
+      ]
     },
     "workload-runtime-api": {
       "tier": "system",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api",
+        "org-database-pool-api"
+      ]
     },
     "xema-biome-runner": {
-      "tier": "system",
-      "startupRequires": ["identity-api"]
+      "tier": "base",
+      "startupRequires": [
+        "identity-api"
+      ]
     },
     "project-registry-api": {
       "tier": "base",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api",
+        "org-database-pool-api"
+      ]
     },
     "space-registry-api": {
       "tier": "system",
-      "startupRequires": ["identity-api"]
+      "startupRequires": [
+        "identity-api",
+        "org-database-pool-api"
+      ]
     },
     "xema-kernel-server": {
       "tier": "kernel",
       "startupRequires": []
+    },
+    "org-database-pool-api": {
+      "tier": "kernel",
+      "startupRequires": [
+        "identity-api"
+      ]
     }
   }
 }