# ADR — Soul Stack Architecture Decision Index The ADR (Architecture Decision Records) catalog. The source of truth for high-level architecture is [`docs/architecture.md`](../architecture.md); ADRs are gradually being split out of it into separate files (one ADR = one file, `NNNN-.md`). Not all of them have been split out yet — for the ones that haven't, the link points to an anchor inside `architecture.md`. Statuses: **active** — a decision in effect; **amended** — in effect, but supplemented by Amendment block(s); **superseded** — replaced by a newer ADR. **Numbering — a new ADR is written WITHOUT a number (decided 2026-09-01).** It is authored as `docs/adr/draft-.md` and cited by that path for as long as its ticket is in flight; the number is stamped **in the release worktree, at squash-merge** — the one point where the release tip is known and tickets land one at a time — by renaming the file to `NNNN-.md` and writing its index row with that number. The `NNNN-.md` filename format and the `ADR-062` citation form are **unchanged**; only the moment of allocation moved. What it fixes: two parallel sessions each read the same "highest number" from their own worktree and both take the next one, and the clash surfaces only at rebase — in the filename and in the index row at once, which is the one place a merge cannot silently pick a side. That is not hypothetical: the reservations below were the workaround for it. Renumbering the existing ADRs is **not** decided and is not proposed here. **83 files** `NNNN-.md` in total, the highest number is **0087**. Numbering **has gaps**: numbers 0034, 0036, 0037 are unused, and 0071 is reserved for in-flight design work (see the note at the end of the index). In other words, "0001...0087" is not a contiguous range. A reservation is now the exception rather than the mechanism: under the convention above an in-flight ADR holds no number at all, and any `draft-.md` awaiting one is listed in [Drafts — no number yet](#drafts--no-number-yet) after the table. | ADR | Title | Status | Summary | |---|---|---|---| | [001](0001-language-go.md#adr-001-implementation-language--go) | Implementation Language — Go | active | Go as the language for all binaries of the system. **Split into its own file.** | | [002](0002-transport-grpc-ha.md#adr-002-transport-keeper--souls--grpc-bidirectional-stream-over-mtls-ha-keeper-cluster) | Transport Keeper ↔ Souls — gRPC bidi over mTLS, HA cluster | amended | Bidirectional stream over mTLS, initiated by Soul; Keeper is a stateless cluster (presence/shedding are amendments). **Split into its own file.** | | [003](0003-destiny-format.md#adr-003-destiny-format--yaml-with-a-typed-schema-cuejson-schema) | Destiny Format — YAML with a typed schema | amended | YAML + JSON Schema/CUE, templating as a separate phase. **Split into its own file.** **Amendment 2026-09-01 (NIM-741, [One schema dialect](0086-one-schema-dialect.md)): the "JSON Schema" half no longer describes `state_schema`.** It still describes the destiny format; `state_schema` in `service.yml` moves to the **same dialect as `input:`** — a map `` → schema, no root `type: object`/`properties:` wrapper, `required: true` on the field, snake_case vocabulary. This closes the divergence [ADR-062](0062-input-types.md) rejected `$ref` over ("a second schema DSL alongside our own input DSL") in the last place it was still shipping. Design only, not implemented: NIM-742/743/744. | | [004](0004-binaries.md#adr-004-binary-layout--keeper-soul-soul-lint-push-mode-as-a-module-inside-keeper) | Binary Layout — keeper / soul / soul-lint | active | Three (later five) artifacts; push is a module inside keeper. Amended 2026-07-26: `soul-legion` ships. **Split into its own file.** | | [005](0005-storage-postgres.md#adr-005-keeper-state-storage--postgres) | Keeper State Storage — Postgres | active | Postgres — the sole cold-state storage. **Split into its own file.** | | [006](0006-cache-redis.md#adr-006-cache-and-coordination--redis) | Cache and Coordination — Redis | amended | Redis — heartbeat, lease, pub/sub, the Reaper leader; Souls presence + Conclave; cluster-mode SSE/apply-events routing with a sharded channel `events:shard:` K=256 (amendments). **Split into its own file.** | | [007](0007-versioning-git-ref.md#adr-007-artifact-versioning--via-git-ref-not-a-manifest-field) | Artifact Versioning — via git ref | amended | An artifact's version = git ref, not a field in the manifest. **Split into its own file.** **Amendment 2026-09-01 (NIM-735): the `state_schema_version` exception is RETIRED** — the manifest key leaves `service.yml` and the number is derived instead, as the top of the migration ladder (`migrations/_/`; an empty `migrations/` = version 1). It removes an exception rather than adding one, restoring this ADR's own one-source-of-truth rule to the state schema. ⚠ Only the **manifest key** goes: the `incarnation.state_schema_version` column and the API/MCP field of the same name stay. | | [008](0008-coven-stable-tags.md#adr-008-coven--stable-logical-tags-only) | Coven — stable logical tags only | amended | Coven = stable tags; role is NOT coven; environment = a special case of coven (amendments). **2026-07-17 (NIM-124): `incarnation.name` is NO LONGER a Coven — membership is a first-class relation (`incarnation_membership`); the `on:` resolver / RBAC / bulk-select decouple from `coven==name`.** **2026-07-28 (NIM-209): membership gets an OPERATOR path** — `POST`/`DELETE`/`GET /v1/incarnations/{id}/members` + MCP twins, rights `incarnation.bind-member` / `.unbind-member` (read rides on `incarnation.get`). NIM-124 named exactly one writer — the in-run bind act `core.soul.registered` — so an already-onboarded host could not be put into an incarnation from outside a run, and a create scenario over a ready roster (`create_from_souls`) was unreachable through the API (the e2e harness seeded the row with direct SQL). ★ **Authorization is TWO gates:** the incarnation selector by path-`{name}` AND every target SID inside the caller's soul visibility (`soul.list` purview) — an `incarnation=`-scoped predicate is satisfied without looking at the host, so gate (a) alone would let a holder pull ANY host into their incarnation and reach it with `incarnation.run`; all-or-nothing, never a silent partial bind. Operators may bind only a `connected` host; the keeper-internal act is exempt (it binds `pending` hosts it just created). Both directions idempotent (`bound` vs `already_member`; unbind of a non-member → `removed:false`). **2026-07-30 (NIM-330): the declared role is a Voice, not a spec field** — `incarnation.spec.hosts[]` is REMOVED (the "Decision" line naming `spec.hosts[].role` as its home is superseded); the declared/actual split is untouched, only the storage moves to `incarnation_choir_voices.role`. **Split into its own file.** **2026-08-03 (NIM-410, [ADR-0082](0082-service-vars.md)): the assembly order collapses to one lexical layer** — `default → os → coven → incarnation.spec` is replaced by every `*.yaml` directly inside `/vars/`, sorted lexically from `00-base.yaml`; the `os/`/`coven/` directory layers are deleted (implemented, used by zero shipped examples) and conditionality moves into `vars/_stack.yaml`, while `incarnation.spec.essence` is removed outright (two readers, no writer — a fleet forks the service repo instead). "essence is role-agnostic" stands. The coven axis of service vars is NOT weakened: it selects layers of the incarnation's OWN config by `incarnation.covens` through a `foreach:`, and the NIM-248 guard is retargeted onto that step rather than dropped — it never read a host label, which is why [NIM-281](0008-coven-stable-tags.md#amendment-2026-08-05-nim-281-a-label-is-never-inherited) leaves it alone. **2026-08-05 ([NIM-280](0008-coven-stable-tags.md#amendment-2026-08-05-nim-280-a-rules-subject-reads-both-levels--targeting-only)): a rule's SUBJECT reads both levels — targeting only.** A Vigil / Decree / Rite subject became one of four dimensions (`sid` / `incarnation` / `coven` / `trait`), and its two label dimensions match over the host's labels ∪ those of every incarnation it belongs to, for the duration of one match. `souls.coven[]` / `souls.traits` are unchanged, no other reader sees the union, and the RBAC scope predicate still reads the row's own column — ★ targeting expands, authorization never does. ⚠ Consequently labelling an incarnation widens existing `coven`-subject rules, and unbinding a host withdraws the rules that reached it that way. | | [009](0009-scenario-dsl.md#adr-009-scenario--the-full-destiny-task-dsl-the-boundary-with-destiny-is-a-recommendation) | Scenario — the full destiny task DSL + orchestration | amended | Scenario = all destiny blocks + the orchestration delta; cross-incarnation at the Voyage layer + an optional task field `id:` + the destiny-pass CEL env sees read-only `soulprint.self.*` (hosts/where are scenario-only); per-task granularity `serial:`/§8 — via the staged-render Passage ([ADR-056](0056-staged-render-passage.md)); the `state_changes` grammar (§7.1 `sets`/`appends`/`modifies` map) extended to an ordered list of CRUD verbs ([ADR-057](0057-state-changes-crud-verbs.md)); top-level `compute:` — computed run vars (host-invariant, visible in `apply: input:` and `state_changes`); var→var within the `vars.*` layer — eager-topological resolve (a cycle/unknown-ref → an error, YAML order doesn't matter, file↔task cross-layer isolation preserved); conditional `when:` on an include-task — conditional-include = a render-phase group-drop (a real exclusion of the group from the plan, only a static `input.`/`essence.`/`incarnation.`/`vars.` predicate; dynamic → `include_when_dynamic_unsupported`; coexists with block-static-skip); a mechanism for several named create scenarios (a per-scenario `create: true` declaration, the hardcoded `create` default removed, choosing `create_scenario` is mandatory when the set is non-empty, a bare incarnation when it's empty — `created_scenario` NULLABLE, migration 090); `extends: ` — inheriting a shared service-level contract of sections (`input`/`compute`/`state_changes`/`validate`) from the `covenant.yml` at the service-repo root: add-only shallow merge, fail-closed `section_key_conflict` (deep merge/last-wins rejected), `form:` is not merged, covenant is appended first, resolution in `LoadScenarioManifestResolved` BEFORE consumers (isomorphic to `$type`/`include`), one extends / no recursion / only 4 sections, forward-compat (optional), removes the create↔create_from_souls drift (amendments); **destiny-input parity (amendment 2026-07-26)** — `validate:` becomes a top-level `destiny.yml` key and the destiny render pass runs the SAME input contract as scenario (defaults → `required`/`required_when` → value validation → `validate:` rules) via one shared composition, enforced strictly from the first release (breaking for callers that were silently out of contract); **within-block `include:` (amendment 2026-07-26)** — the block pilot restriction is lifted: `ExpandIncludes` recurses into `block:`, so an include child splices in place at any nesting depth (cycle/depth detection and the conditional-include conjunction cascade through the block unchanged), in BOTH layers at once since the expander is shared; a conditional include inside a block composes with the block's `when:` as two ordered axes (group-drop first — physical removal, then static-when skip — placeholder keeping index/`register:`), decided once per pass via `keepIncludeGroup`; the render guards stay as defense-in-depth `ErrUnexpandedInclude`; **intra-host concurrency (amendment 2026-07-27)** — the task core's concurrency key is `async:` (fire-and-forget, not a grouping mechanism) and `parallel:` becomes reserved/unrecognized for a future group-with-join, with the barrier model and the two Passage-related boundaries fixed in [ADR-0075](0075-intra-host-async-tasks.md); **a roster-reading assert has no pre-flight point at create (amendment 2026-07-28)** — the gate stands before `incarnation.Create` and NIM-124 made membership FK that row, so `soulprint.*` there is not empty but impossible and every create carrying a topology guard answered 422 unconditionally; such asserts are deferred to the render fail-safe (single-point, not two-point), asserts over `input.`/`essence.`/`incarnation.` keep their 422; **the pre-flight gate moves to where the roster IS real (amendment 2026-07-28, NIM-270)** — it now also runs on the explicit-run path (`POST .../scenarios/{scenario}` + the MCP twin), the one place a topology assert can be answered, with ONE predicate (`planBuildsRoster`, shared with the `no_hosts` bypass) deciding when the roster in front of the gate is not the assert's subject; a contract change on that endpoint (202 → possibly 422), plus pre-flight now resolving the RUN's own essence rather than a synthetic incarnation (NIM-271) and a `soul-lint` WARNING naming the create-path deferral at authoring time (NIM-272, `assert_roster_deferred_on_create`); **a group construct's requisites compose as OR and widen (amendment 2026-07-30, NIM-287)** — `block:` and `apply:` merge their `onchanges:`/`onfail:`/`require:` into every task of the group as a union of names, which the runner reads as OR, so a descendant that already had a requisite runs when EITHER source changed, while `when:` on the same construct merges by AND and narrows; the asymmetry is stated rather than removed, since AND is only definable between inheritance levels (a name resolves to several indices after NIM-246) and would need a grouped wire field, a capability gate and a rule for an all-filtered bracket — deferred to NIM-351, against a corpus with zero uses of the combination. **Split into its own file.** **Amendment 2026-08-03 (NIM-410, [ADR-0082](0082-service-vars.md)): the scenario context loses the `essence` root** — a service's defaults move into `vars/` and read as `vars.*`, giving one flat ladder `vars/*.yaml` → scenario `vars:` → `block:` → task with **no operator rung** (`incarnation.spec.essence` removed, no successor); `essence` leaves the reserved-name lists for `loop:`/`compute:`/task-`vars:` (`vars` was already reserved there, so nothing that validated starts failing), a static `when:` keeps `input.`/`vars.`/`incarnation.`, and the `apply:` boundary asymmetry becomes visible rather than camouflaged — the same one that already forced `apply_when_dynamic_unsupported`. New soul-lint WARNING `vars_shadows_service_var` for a local taking over a service var's name; **NIM-694: `include:`/`extends:` take one subdirectory level** (a shared segment alphabet `[a-z_][a-z0-9_-]*`, `.` deliberately outside it so `..`/absolute/hidden are unrepresentable, securejoin kept as the second line), a `_`- or `.`-prefixed directory under `scenario/`/`upgrade/` is **not a scenario** and is skipped silently even with a `main.yml` (both walkers), and soul-lint resolves the service-level tier offline — an unresolvable include is now an ERROR instead of the `stage_include_unresolved` hint (**amend 2026-09-02 / NIM-716**: outside a service tree the kept hint covers a target that was not FOUND and nothing else — an error out of a body that resolved locally and was read is that body's own, at its own coordinates). **NIM-699 ([ADR-0084](0084-explicit-state-capture.md)): `state_changes:` leaves the orchestration delta** — a state write is a keeper-side task `module: core.state.` + `on: keeper` standing at its own position in `tasks:` and landing at that step; the verb grammar survives, the block does not, the cross-host barrier is unchanged, ordering becomes the author's (soul-lint `state_store_after_use` / `state_stale_same_passage_read` ERRORs, `state_wide_match` WARN), a capture sees the keeper register bucket only, and `foreach` is dropped because a step has `loop:`. **Amendment 2026-09-01 (NIM-741, [One schema dialect](0086-one-schema-dialect.md)): `state_schema` is written in the input DSL, so the 2026-08-19 secret declaration changes spelling.** A map `` → schema — no root `type: object`/`properties:` wrapper, `required: true` on the field, snake_case vocabulary; the secret declaration's substance (two shapes, `key:` sibling, derived path, closed node grammar) is untouched, every corpus site that spells it moves. ★ **The wrapper is refused at the ROOT only** — a nested object field still declares `type: object` with fields under `properties:` — while the list form `required: [names]` leaves the **whole** dialect, `types.yml` included (28 flow-form sites across both dialects; the block form is authored nowhere). Breaking with **no transition window**, and the old envelope is refused **by name** (`state_schema_legacy_json_schema_form`) rather than left to parse: read as the new dialect it is two state fields called `type` and `properties`, which moves every real field a level down and loses every declared secret with no error raised. Design only — NIM-742 (engine), NIM-743 (`soul-lint list-secret-paths`), NIM-744 (`examples/` + WB redis). | | [010](0010-templating.md#adr-010-templating-engine-cel-for-yaml-expressions-go-texttemplate-for-files) | Templating engine: CEL + Go text/template | amended | CEL — YAML expressions, text/template — files; the boundary is by file; the destiny-pass CEL env additionally registers read-only `soulprint.self.*` (amendment 2026-06-18); var→var within the `vars.*` layer via the CEL-AST `Engine.VarRefs` (eager-topological, amendment 2026-06-24). **Split into its own file.** **Amendment 2026-08-03 (NIM-410, [ADR-0082](0082-service-vars.md)): the CEL root `essence.*` merges into `vars.*`** — removed from the env rather than renamed beside it; `core.file.rendered`'s `render_context` root becomes `{vars, self, role}` (+ the conditional `input` of 2026-06-26), which costs nothing at the seam since **no `.tmpl` in `examples/` reads `.essence`**; `default(x, y)`'s anchor roots lose `essence` and keep `input`/`vars`/`incarnation`/`register`/`soulprint`. Masking, seal and `injectInput` untouched. **Amendment 2026-09-01 (NIM-741, [One schema dialect](0086-one-schema-dialect.md)): all three key literals of the §7.4 masking walk are wrong after `state_schema` moves to the input DSL, and the failure is fail-OPEN.** Layer 1 (schema) recurses *"through `properties`/`items` and nested `properties` under `additionalProperties`"* — at the root there is no longer a `properties` key (the root IS the field map), `additionalProperties` is now `additional_properties`, and `items` survives only inside a subtree nothing reaches. ⚠ `keeper/internal/incarnation.CollectStateSchemaSecrets` hardcodes the three strings (`secret_schema.go:82`,`:89`,`:92`) and returns an **empty** `SecretPathSet`, which is byte-identical to the honest *"this service declares no secrets"* — and the read path is built to tolerate exactly that (`keeper/internal/api/handlers/incarnation_secret_schema.go:26-29`: best-effort assembly, degrade to vault+regex, GET deliberately does not fail). So a `secret: true` state field stops being masked on `GET /v1/incarnations/…` with **no error raised anywhere**, and `isSecretNode` (`:116-122`) matches `type: secret` too, so ADR-0083 §1's deliberate defensive entry goes with it. **The walk therefore migrates in the same commit as the parser (NIM-742), not after it** — a declarative masking layer that fails open is worse than an absent one. A third reader fails the other way and is recorded for contrast: `stateop.schemaFieldType` (`keeper/internal/stateop/ops.go:489-504`) also reads the root `properties`, but `collectionKind` consults the schema only for a field ABSENT from state, so the first `add` into an unmaterialized collection **fails closed and loudly** with a message blaming the schema's content rather than its dialect. ⚠ **`append` on the same reader fails OPEN** — `applyAppendOp`'s `:351` guard (`ops.go:343-357`) exists only to reject a map field, never fires once `schemaFieldType` returns `""`, and `:354` materializes a **list** where the schema declares a map with no diagnostic: the one silent state-corruption path in the verb engine, and it moves with the walk (NIM-742). Its declared twin `trial.collectionKind`/`schemaFieldType` (`keeper/internal/trial/diff.go:28-58`) is **dead code — called by nothing**, so L0 neither reproduces nor catches it. The 2026-06-24 `additional_properties`-node limitation carries over unchanged; `input_schema` and the manifest `InputParamDef.Secret` do not move. | | [011](0011-go-layout.md#adr-011-go-code-layout-gowork-with-per-side-modules) | Go code layout: go.work with per-side modules | amended | go.work with seven per-side modules. **Split into its own file.** **Amendment 2026-09-01 (NIM-757): `proto/plugin/` loses a service contract and `sdk/` loses a subpackage.** The separate CloudDriver contract is removed — a cloud driver becomes an ordinary SoulModule plugin declaring `side: keeper` ([ADR-017](0017-keeper-side-core.md) / [ADR-020](0020-plugin-infrastructure.md)) — so `clouddriver.proto` + its committed generated Go go, `sdk/`'s subpackage list drops `clouddriver/` (a whole module directory, a separate breakage for plugin authors from the proto one), and `keeper/internal/` sheds `provider/` / `profile/` / `coremod/cloud/` / `pluginhost/clouddriver.go`. `go.work`, the module count and the Soul-isolation invariant do NOT move. ⚠ Carries a **factual correction** rather than propagating the drift: `proto/plugin/v1/` holds **four** services today, not the three this ADR names — `SoulBeacon` arrived as V5-2 with the [ADR-030 amendment 2026-05-26](0030-vigil-oracle.md#amendment-2026-05-26-s5-closure) and was never absorbed here — so the count after the cut is **three**. ⚠ `make check-gen` does NOT catch an orphaned `.pb.go`: `Makefile:22` enumerates the `.proto` sources with `find` and protoc never deletes stale outputs, so the generated files go by hand in the same commit. Implemented in NIM-761 (2026-09-04). **Amendment 2026-09-05 (NIM-776): the Operator API wire types live in `shared/api/wire`, not in `keeper/internal/`.** `internal/` is a compiler-enforced wall, so every consumer outside the keeper module — `soulctl` and the four test-harness modules — was FORCED to declare its own struct with hand-written json tags, and `encoding/json` makes that second description diverge in silence (NIM-729 renamed `name` → `id` across ten registries and left `soulctl push-provider create` dead against `additionalProperties:false` with nothing failing). The bodies and the contract enums move to `shared/api/wire`, which the Consequences already permit in as many words (*"Allowed in `shared/`: … data types and enums"*); keeper keeps the whole server half and names them through aliases. ⚠ **NOT `sdk/api`**, which this ADR names for a future external client SDK: `sdk/*` is Apache 2.0 under [ADR-016(o)](0016-parity-license.md) while the core is BSL 1.1, so putting the contract there would relicense it — a licensing decision on its own merits, not a side effect of a refactor. The package imports **nothing outside the standard library**, so no dependency reaches `soul` through `shared`. The three enums the UI references by `$ref` keep their `huma.SchemaProvider` on a keeper-local shim, because that interface is a METHOD and Go allows one only in the declaring package; `docs/keeper/openapi.yaml` does not move. Guard: `shared/api/wire/single_source_test.go`. | | [012](0012-keeper-soul-grpc.md#adr-012-keepersoul-grpc-contract-one-eventstream-with-oneof-keeper-side-render-forward-compat-only-add) | Keeper↔Soul gRPC contract | amended | One EventStream with oneof, Keeper-side render, forward-compat only-add; a back-link apply_run; the dispatch model "one ApplyRequest per host" → "N per host by Passage" ([ADR-056](0056-staged-render-passage.md)) (amendments). **Amendment 2026-07-27 (NIM-188, [ADR-0074](0074-interactive-console-pty.md)):** a fourth RPC `ConsoleStream(stream ConsoleFromSoul) returns (stream ConsoleToSoul)` — the console plane moves off EventStream onto its own bidi stream per session (same mTLS listener, same connection, the `FetchModule` precedent), because on EventStream pty output shares one write mutex with `TaskEvent`/`RunResult` and keystrokes share the per-SID outbound queue with apply dispatch; `ConsoleOpen` stays on EventStream (only a client may dial); only-add, both compat directions live (an old Soul is served over EventStream, a new Soul against an old Keeper falls back on `Unimplemented`). **Split into its own file.** **Amendment 2026-08-03 (NIM-410, [ADR-0082](0082-service-vars.md)): `flow_context` loses its `essence` key** — `{input, vars, essence, incarnation, self}` becomes `{input, vars, incarnation, self}`. **Only-add (c) is intact and it is still breaking:** `flow_context` is a `Struct`, so a map key changed where the wire schema cannot see it, and an older Soul reads `flow_context["essence"]` against a new Keeper and silently gets nothing. Recorded here precisely because the compat rule cannot catch this class; a mixed-version fleet across this boundary is unsupported. | | [0013](0013-bootstrap-archon.md) | Bootstrap of the first Archon | amended | `keeper init --archon`, an advisory lock, the first Archon is cluster-admin; the bootstrap invariant is expressed via `created_via='bootstrap'` (amendment 2026-06-23); the registry-emptiness check ignores the system `archon-system` — "empty" = no operators with `created_via != 'system'` (amendment 2026-07-01). **Split into its own file.** | | [0014](0014-operator-identity.md) | Operator identity model (Archon) | amended | Registry `operators`, a JWT credential; AID charset extended, near-instant revocation, a `created_via` field + moving the bootstrap invariant (amendments). **Revocation made route-independent and immediate on the revoking node (amendment 2026-08-07, NIM-421):** one `RejectRevoked` link after `RequireJWT` → `401 operator-revoked-token` everywhere (the existence-gate routes used to say 403, four ungated ones 200), and the invalidator refreshes its own snapshot before publishing (the origin node used to wait out its 10s TTL). Federated login answers 401 for revoked too. **Split into its own file.** | | [0015](0015-core-modules-mvp.md) | Core modules MVP: exact list | amended | 18 Soul-side core (12 original MVP + post-MVP `url`/`line`/`repo`/`firewall`/`http` + `directory` split from `core.file` 2026-07-17). The current registry fact is 18 Soul-side (+`core.augur` per ADR-025) and 4 Keeper-side (`core.soul`/`core.cloud`/`core.vault` per ADR-017 + `core.choir` per ADR-044); the factual summary is [module/README.md](../module/README.md#catalog-status). Amendment 2026-06-18: `core.service` (systemd) does a gated `daemon-reload` before mutating actions (param `daemon_reload` auto/always/never, default auto); a new state `core.file.directory` (params path/owner/group/mode/parents; idempotent, fixes owner/mode drift, supports Scry). Amendment 2026-07-17: `core.file.directory` split out into a new top-level `core.directory` (`present`/`absent`; hard rename, no back-compat; `absent` removes a non-empty dir only with `recursive: true`, else errors — a deliberate divergence from silent `rm -rf`); `core.service` gains `disabled` and `masked` (systemd-only, disable-before-mask). Soul-side core count 20 → 21. **Amendment 2026-08-14 (NIM-687): a non-zero exit now FAILS the verb-shell modules by default** — `core.exec.run` / `core.cmd.shell` take an optional `exit_codes` (exact integers and/or inclusive `"lo-hi"` ranges, default `[0]`); a contract change, not an addition, since both used to report `changed=true, failed=false` for ANY code the process returned. The rejected code travels as `failed=true` **with** `{stdout, stderr, exit_code}` (`util.SendFailedWithOutput`), so a `failed_when:` predicate over `register.self.exit_code` stays evaluable; the guards (`creates`/`unless`/`onlyif`) and `res.Err != nil` are unchanged, and `failed_when: false` is the documented way back — at the price of the task ending OK, not CHANGED. Reaches the Errand surface with the same modules (`POST /v1/souls/{sid}/exec`, `keeper.soul.run-command`). **Split into its own file.** | | [0016](0016-parity-license.md) | Parity strategy + license | amended | **BSL 1.1** (core+web, fair-code; Additional Use Grant = **Internal Use only**, each version turns Apache 2.0 two years after its own release) / Apache 2.0 (`sdk/`, `proto/plugin/`, `examples/`, plugins); a hybrid of a core rewrite + community plugins; SDK Phase 2. ★ The original decision (a) "Apache 2.0 for everything" is **superseded** — the amendment of 2026-07-09 is the licensing decision in effect. ★ Part **(g) reserved namespace `official` is retired** (amendment 2026-09-02 / NIM-765): the artifact carries no name since NIM-377, `official` is in neither `shared/plugin/reserved.go` nor the reserved list, and the origin-grouping address level is removed — origin is answered by the catalog `source` and the Sigil allow-list. The trademark protection of "official"/"certified" under (q) is unaffected. **Split into its own file.** | | [0017](0017-keeper-side-core.md) | Keeper-side core expanded | amended | `core.cloud` (the address `core.cloud.created`/`core.cloud.destroyed`, base+state — the form `core.cloud.provisioned` is historical, as an address it does NOT exist, amendment 2026-06-26) / `core.vault.kv-read`; a cloud credentials-flow + 6 providers (amendments). **Amendment 2026-07-01 (self-onboard "Variant T"):** a third bootstrap-delivery mode — per-VM tokens are baked into userdata BEFORE create (keeper predicts the FQDN: opt-param `name` + `providers.fqdn_suffix`, migration 094; `self_onboard: true` on `core.cloud.created`; orphan-cleanup of souls/tokens on a failed create); a deliberate departure from the B-flat floor "userdata without tokens" (single-use tokens, opt-in). **Amendment 2026-07-01 (cert-rotation via Warrant, Keeper-centric):** the **Warrant** registry of service TLS certs (migration 092, one active per `(incarnation, kind)`) + the Reaper rule `rotate_due_certs` (a scan of `not_after`+jitter → CAS → keeper-side genkey+CSR (★an R2 exception, the service cert's private key goes through Keeper→Vault — the SoulSeed identity invariant is not weakened) → Vault PKI `SignCSR` → `WriteKV` → spawn a Voyage(`rotate_tls`); default OFF+dry_run) + the keeper-side core `core.cert.registered` (E1) + `purge_old_certs` (093). **Amendment 2026-07-09 (cert-rotation config-driven):** a new top-level manifest section `certificate_rotation` (`enable`/`scenario`/`threshold`/`pki_role`) — the Reaper reads the rotation scenario name and Vault PKI role from the manifest (Path B, version = pinned `service_version`, cache ~60s), **no section = rotation off** with no fallback to the hardcoded `rotate_tls`; a second state `core.cert.issued` (mint+enroll: keeper-side genkey+CSR → Vault PKI role from the manifest → Vault → Warrant, the R2 private key never leaves); three gates (`enable` × per-cert `auto_rotate` × keeper.yml `rotate_due_certs.enabled`); `threshold` is still global (keeper.yml), the `warrant` schema unchanged. **Split into its own file.** **Amendment 2026-07-26 (re-create over hosts that are already up converges; NIM-189):** completes the (mm) boundary of the 2026-07-24 amendment — the driver already reuses live VMs, so `EnsureProvisionable` gains a third outcome **`existing`** (a `connected`/`disconnected` row of THIS incarnation is read and left untouched, NO bootstrap token issued) instead of refusing; `core.cloud.created` flags such hosts `onboarded: true` in `hosts[]` and counts them in a new `existing` output, `core.bootstrap.delivered` skips them; `vm_ids`/`hosts[].sid` still cover the WHOLE roster (day-2 `provisioned_vm_ids`/`provisioned_sids`); `revoked`/`expired` and foreign incarnations are still refused. **Amendment 2026-07-26 (a teardown is not done until the provider confirms; NIM-191):** provider delete calls are async — an accepted RPC is not a deletion, and a VM deleted mid-create stays alive (WB parks it in `DELETE_FAILED`) while the driver reported success, so the cascade ran `souls→destroyed`/seeds-orphaned/tokens-burned over live, billed machines. SDK skeleton (f) gains **`ConfirmDestroy`** (delete → poll until gone → **re-issue the delete** whenever the probe reports the deletion itself failed; same `SOUL_CLOUD_WAIT_BUDGET`; per-provider part = `GoneProbe`/`GoneResult`, rendering = `ReportDestroy`); an unconfirmed teardown is `failed=true` with the `vm_id`, never a success; Keeper's `PluginAdapter.Destroy` stops counting failed events as deletions and fails the whole call, leaving the registry untouched (delete is idempotent, so a re-run is safe). **Amendment 2026-08-17 (a second source for the driver tuple — the step itself; NIM-668):** additive first step of "a cloud is just a plugin" — `core.cloud.created`/`destroyed`/`resized` can take the whole tuple from step params instead of a registry row: `driver` (plugin alias, was `providers.type`), `credentials` (a **literal** `vault:` ref — resolved by the render's vault phase, so A-flow holds and the key name is caught by `sensitiveKeyRe`; a ref built by `${ … }` is never resolved and is refused), `region` (merged under the same `regionKey`), `fqdn_suffix` (was the `providers` column, for self-onboard FQDN prediction) and **`profile` as an OBJECT** — reversing the 2026-06-29 "NOT an inline object" on new grounds (a topology × size matrix has no expressible registry name, and a service repo cannot ship rows). `provider` XOR the inline set, enforced in `Validate`; audit `cloud.provisioned` carries the driver alias where the row name would go, never the credentials. Registry path unchanged and still supported (removal — NIM-669); `CloudDriver.Schema()` validation and alias defaults — NIM-670. **Amendment 2026-09-01 (NIM-757): the CloudDriver contract is removed — a cloud driver is an ordinary plugin.** Every CloudDriver already *is* a plugin, so the separate service contract was a duplicated abstraction; it becomes an ordinary SoulModule plugin declaring `side: keeper`. Credentials stay Variant A (the plugin never talks to Vault) but arrive as **ordinary step params**, which is what makes the excision complete: **no cloud-specific credentials channel remains in keeper at all** — `coremod/cloud/credentials.go`'s `ResolvedProvider{Driver, Credentials, FQDNSuffix}` with `region` folded under `regionKey` is exactly the thing that goes. Named losses, as an accepted price: `core.cloud` and all **three** states (`created`/`destroyed`/**`resized`** — `resized` is missing from this ADR's own framing), the Provider + Profile registries (migrations 019/020/094 + the FK `ON DELETE RESTRICT`), **8** RBAC permissions, **7** audit events, **10** MCP tools, **10** Operator-API operations over 6 path items, `shared/coremanifest/mod_cloud.go`, `keeper/internal/{provider,profile,coremod/cloud,pluginhost/clouddriver.go}`, `sdk/clouddriver/`, the six `examples/module/soul-cloud-*`, and the web Provider/Profile screens (NIM-762). ★ **Removing a permission is breaking, and worse than "a lost grant":** the catalog is a closed enum and the enforcer fail-closed, so ONE surviving row takes the whole cluster's authorization down at the next keeper start with no in-band remedy (and `holder.go` hides it on a running cluster until then) — catalog entries and the data migration ship in the SAME change, matching **both** the bare and the ` on `-scoped form, per the `109_drop_permission_update_hosts` template. ⚠ `catalog.go`'s "names are never removed" prose states the opposite policy; its reason is dead (grants are in Postgres, not `keeper.yml` — [ADR-028(g)](0028-rbac-storage.md)) and NIM-330 already broke it once — flagged, not a blocker. `proto/plugin` — **Option A, no backcompat**: `clouddriver.proto` + generated Go + `sdk/clouddriver/` deleted, `KIND_CLOUD_DRIVER = 2` becomes `reserved` (never-reuse per ADR-020(c), **not** backward compatibility); `proto/plugin/v2` rejected — nothing is changing shape, it is going away. **The 2026-08-17 NIM-668 amendment is ANNULLED** (no `core.cloud` step left to parametrise). Order is forced: **NIM-758** (keeper learns to execute a keeper-side plugin — today `applyKeeperTask` answers `unknown keeper-side module`) → **NIM-760** (`soul-cloud-wb` moves, VM creation verified live) → **NIM-761** (removal); removal first would leave the platform unable to create a machine at all. All three shipped; removal landed 2026-09-04. **Amendment 2026-09-03 (NIM-745): the manifest section `certificate_rotation` becomes `certificate:` with the rotation policy nested under `rotate:`, and `pki_role` lifted out of it** — the role is what a cert is ISSUED with (`core.cert.issued` mints the first one with it), so tying it to a rotation switch made "signed by role X, do not auto-rotate" inexpressible; `certificate: { pki_role: X }` with no `rotate:` block is now a complete section. Gates, Warrant schema and the `rotate_tls` contract key unchanged; `Present`/`Enabled` now read the `rotate:` block, so a role-only section is excluded from the scan exactly as no section was. The old key is refused with a hint — no transition window, because the three manifests carrying it were all ours. `core.cert.issued` still requires rotation enabled (follow-up). | | [0018](0018-soulprint-typed.md) | Soulprint typed-schema MVP | amended | `SoulprintFacts` instead of a Struct stub; `choirs` as a fact, typed_facts byte-passthrough (amendments). **Split into its own file.** | | [0019](0019-state-migration-dsl.md) | State_schema migration DSL | amended | A flat DSL + CEL + foreach, forward-only, an atomic PG tx; upgrade → drift (amendment). **Split into its own file.** **Amendment 2026-09-01 (NIM-735): a step states its place once.** A step becomes a directory `migrations/_/` holding `main.yml` and its `tests/`; the number is the version the step leads to and the "from" is derived, so `from_version:`/`to_version:` leave the file and `state_schema_version:` leaves `service.yml` ([ADR-007](0007-versioning-git-ref.md) amendment) — the version is the top of the ladder, an empty `migrations/` = 1. A generated `schema.lock` (`version` + a fingerprint of the **parsed and canonicalized** `state_schema`, never the file text) catches the one failure nothing else does — a schema edit with no step behind it — because the structure is described twice, declaratively and imperatively, and nothing reconciles the two, not even the upgrade tx (which never loads the target schema). ★ The fingerprint proves a step was ADDED, not that it is correct; the stamp bypass is closed **procedurally** (a re-stamp with no new directory is visible in the diff, `atlas migrate hash`-style) and the mechanical ban was explicitly rejected — it would force empty steps for harmless schema edits. The engine — the layout, the derived version, dropping the manifest key and the `soul-lint` ladder check — landed with NIM-736 together with the `examples/` relocation; `schema.lock`, the `soul-lint schema-stamp` command and the lock check landed with NIM-737. | | [0020](0020-plugin-infrastructure.md) | Plugin infrastructure | amended | manifest / handshake / lifecycle for three plugin types; SDK Phase 2, the SshProvider set; the catalog `plugins.soul_modules[]` ([ADR-065](0065-core-module-installed.md)); separating Teleport paths — the bootstrap-delivery `transport: teleport` goes through a keeper-side Dialer over an identity file BYPASSING the `soul-ssh-teleport` plugin, the `proxy_jump` limitation (m) remains only for push runs of Destiny (amendments). **Split into its own file.** **Amendment 2026-08-06 (NIM-377): the schema is generated from Go and stamped into the artifact; the artifact carries NO self-name.** (a)/(e) superseded — no hand-written `manifest.yaml`, the source of truth is a `module.Def` in Go, the generated canonical-JSON schema is stamped as a trailer (`soul-mod stamp`) and written to `dist/schema.json`, with `soul-mod verify` as the CI gate; `namespace:`/`name:` are gone, `Manifest.BinaryName()` and the binary-name convention go with them (NIM-423 closed as moot), and address level 1 comes entirely from the registration alias. (d) amended: dispatch is a subcommand (`soul-mod-redis acl`), no proto change. ★ **(f)/(g) CORRECTED — `required_capabilities` and `side_effects` are disclosure to the operator before approval, NOT controls.** There is no sandbox at spawn (no `SysProcAttr`/seccomp/`Setuid`/rlimit anywhere in `shared/pluginhost`); `SideEffects` is read only by the grammar validator; no production code emits `policy_violation`; `conflict_policy` is parsed and read by nothing; `soul-lint` does not check capabilities at all. The one real control is unchanged: the operator approves a specific sha256 and the host refuses to exec a differing digest. (s) adds the reserved-namespace list (absorbs NIM-375). **Amendment 2026-09-01 (NIM-757): `cloud_driver` is removed, and `side: keeper` is what replaces it.** Continues the NIM-748 `side:` block rather than opening a second story: that block added the field and warned it was accepted-and-inert on a plugin; this decision makes it load-bearing. ⚠ The Context's "three categories with different service contracts" was **already wrong** before this ticket — `soul_beacon` (V5-2, 2026-05-26) is a fourth and was never absorbed — so the cut leaves **three**, not two; the amendment records the stale count rather than silently correcting it. (e)'s `spec.profile_schema` / `CloudDriverSpec` arm / `soul-cloud-*` convention go with the cloud arm — while the infrastructure this ADR actually fixes (one handshake, one socket, one one-shot lifecycle, one stamped schema document, one Sigil gate) is untouched, which is precisely why the separate contract was redundant. ⚠ **The closed `kind:` enum is in `sdk/schema/schema.go`, NOT in proto** — `pluginv1.Manifest` and its `*Spec` sub-messages have zero non-test Go references, so `manifest.proto` is a hand-synced dead document and (f)/(g)'s "extend via PR to `proto/plugin/vN/manifest.proto`" is stale; removing a kind is an `sdk/` change with `reserved 2` as a footnote, and an old artifact then fails at **schema-document validation** — `kind_invalid` from `sdk/schema/validate.go`, refused by `keeper/internal/pluginhost/slot.go:100-102` before the plugin is spawned, so the handshake kind-drift check is never reached. The 2026-08-06 open item "the authoring form for `cloud_driver` / `ssh_provider` / `soul_beacon`" is **half-closed** — the cloud half by removal, the other two untouched. Implemented: NIM-758, NIM-760, NIM-761 (2026-09-04). **Amendment 2026-09-02 (NIM-764 / NIM-765): a plugin address is `.