docs(state-store): rev.2c resolves third-pass contradictions
Address the third-pass review of the State Store ratification doc: - service-decomposition.md Q3 generic migration wording no longer contradicts the ratified design: the compile-time assertion example is now var _ workflow.Store = (*Client)(nil) (store.WorkflowStore is superseded), and composition selection is described as presence-based [services.<name>].target (empty=local, set=dial remote) instead of the dropped mode = "inproc" | "remote" enum. Defaults differ per service (State Store local, gateway remote-on-localhost). Points to state-store-contract.md section 10. - State Store listener topology is now a single explicit rule: one in-process listener, bound to the host-gateway bridge address with mandatory bearer-token auth when agent containers consume it (the Phase 2 default), or loopback-only for a daemon-local-only consumer. Removed the contradictory "default loopback-only" wording (a container cannot reach the host's 127.0.0.1) and the dual-listener ambiguity across sections 6, 9, and 13.
This commit is contained in:
1 parent
ee42cebd97
commit
29e4ccf6eb
2 files changed
+58
-34
No files matched your search
@@ -157,17 +157,26 @@ Verified couplings that this decomposition must eliminate:
|
||||
default -- this is `docs/architecture/organisation.md`'s standing
|
||||
"Process boundaries" rule, not a new lean. Mechanism: one wire-safe Go
|
||||
contract interface per service; a local adapter and a generated gRPC
|
||||
client adapter, both satisfying the interface via a compile-time
|
||||
assertion in the existing `var _ store.WorkflowStore = (*Client)(nil)`
|
||||
idiom; composition (not `ServiceRegistry`, which stays network-only)
|
||||
picks `mode = "inproc" | "remote"`, default `inproc`; a per-contract
|
||||
conformance suite runs against both adapters over `bufconn`; the flip
|
||||
to a real process is a same-commit deletion of the in-process path, no
|
||||
dual-live window. Consequence: Gateway's Phase 0 (`ChatContract` seam)
|
||||
ships in-process first, with the network protocol staying out of the
|
||||
production path until Phase 1 -- no amendment to Q1's phase list
|
||||
needed. Full mechanism and evidence:
|
||||
`docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#3`.
|
||||
client adapter, both satisfying the same interface via a compile-time
|
||||
assertion (the `var _ workflow.Store = (*Client)(nil)` idiom;
|
||||
`store.WorkflowStore` is superseded by the consumer-owned
|
||||
`workflow.Store`); composition (not `ServiceRegistry`, which stays
|
||||
network-only) picks the adapter by the presence of a
|
||||
`[services.<name>].target` address -- empty = local (in-process) adapter,
|
||||
set = dial the remote gRPC client. This replaced the earlier
|
||||
`mode = "inproc" | "remote"` enum, which was dropped (see the gateway's
|
||||
`services.gateway.target`). Defaults differ per service: the State Store
|
||||
defaults **local** (not yet extracted); the gateway defaults
|
||||
**remote-on-localhost** because it is already a separate process. A
|
||||
per-contract conformance suite runs against both adapters over
|
||||
`bufconn`; the flip to a real process is a same-commit deletion of the
|
||||
in-process path, no dual-live window. Consequence: Gateway's Phase 0
|
||||
(`ChatContract` seam) ships in-process first, with the network protocol
|
||||
staying out of the production path until Phase 1 -- no amendment to Q1's
|
||||
phase list needed. Full mechanism and evidence:
|
||||
`docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#3`
|
||||
(the State Store's concrete ratified config shape is
|
||||
`docs/prds/state-store-contract.md` §10).
|
||||
4. **State Store's contract shape.** Whether every service gets its own
|
||||
storage (true microservice isolation) or several services share the
|
||||
State Store service's contract (less isolation, less migration risk).
|
||||
|
||||
@@ -1,13 +1,15 @@
|
||||
# State Store — contract boundary & transport (ratification)
|
||||
|
||||
**Status:** Ratified (rev. 2). Rev. 1 was marked *conditionally ratified*; the three
|
||||
reviewer conditions it raised are resolved here:
|
||||
**(1)** the domain-dependency contradiction (producer-owned contract vs. the Phase 2
|
||||
acceptance criterion that `internal/domain/workflow` no longer imports `internal/store`),
|
||||
**(2)** agent State Store gRPC endpoint propagation, and **(3)** the transport-security
|
||||
boundary plus error-detail sanitisation. This is the pre-implementation design document that
|
||||
Phase 2 subtasks `.4.2` (generalize `storerpc` as the State Store gRPC contract) and `.4.3`
|
||||
(stand up `archie-state-store`) implement against.
|
||||
**Status:** Ratified (rev. 2c). Rev. 1 was marked *conditionally ratified*; the three
|
||||
reviewer conditions it raised are resolved (rev. 2), and the two third-pass findings are
|
||||
resolved here: (a) the stale Q3 migration wording in `service-decomposition.md`
|
||||
(`store.WorkflowStore`, `mode = "inproc" | "remote"`) now matches the ratified ownership split
|
||||
and presence-based `[services.<name>].target`; (b) the State Store listener topology is a
|
||||
single explicit rule (bridge address + token when agent containers consume it, loopback-only
|
||||
for a daemon-local-only consumer) instead of the contradictory loopback-vs-bridge wording.
|
||||
This is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalize
|
||||
`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)
|
||||
implement against.
|
||||
**Date:** 2026-09-06 (rev. 2)
|
||||
**Beads milestone:** archie-core-8cda.4.1
|
||||
**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)
|
||||
@@ -333,9 +335,10 @@ across a single agent process, which is either NATS-backed or gRPC-backed, never
|
||||
`ctx.Done()`.
|
||||
- **Address selection (Docker-bridge reachable):** reuse the host-gateway resolution already used
|
||||
for embedded NATS (`internal/container/network.go` `RequireHostGateway` /
|
||||
`resolveHostGateway`). The in-process listener binds either loopback (for the daemon's own
|
||||
client) or the host-gateway bridge IP (for agent containers). The chosen address is stored on
|
||||
the daemon as `d.ConnectedStateStore.URL` (analogous to `d.ConnectedNATS.URL`).
|
||||
`resolveHostGateway`). Per §9's single listener-topology rule, the listener binds the
|
||||
**host-gateway bridge address** when agent containers consume it (the Phase 2 default), or
|
||||
loopback-only when the daemon is the sole consumer. The chosen address is stored on the daemon
|
||||
as `d.ConnectedStateStore.URL` (analogous to `d.ConnectedNATS.URL`).
|
||||
- **Per-task injection:** `containerEnv(task)` (`internal/daemon/daemon.go`) appends
|
||||
`STATE_STORE_URL=<d.ConnectedStateStore.URL>` and `STATE_STORE_TOKEN=<token>` alongside the
|
||||
existing `NATS_URL`/`NATS_TOKEN`. The agent reads them via env (`-state-store-url` /
|
||||
@@ -430,15 +433,23 @@ stated explicitly rather than left implicit.
|
||||
|
||||
**The State Store's equivalent boundary (rev. 2):**
|
||||
|
||||
- **Default listener:** loopback-only, `--listen 127.0.0.1` (mirrors the gateway). On the
|
||||
loopback path it uses **`insecure`** gRPC, consistent with the discovery decision (grpc-go
|
||||
insecure dial for loopback) and the gateway.
|
||||
- **Listener topology — single rule (rev. 2c).** One in-process listener; its bind address is
|
||||
chosen by the consumer set, never both at once:
|
||||
- *Agent containers consume it* (the Phase 2 driver during multiplexed serving) → bind to the
|
||||
**host-gateway bridge address** so containers can reach it, and **token auth is mandatory**
|
||||
(a bridge host is reachable by any process on that bridge). A container **cannot reach the
|
||||
host's `127.0.0.1`**, so loopback-only is NOT usable for the agent-consumed path.
|
||||
- *Only the daemon consumes it* (no agent) → bind **loopback-only** (`--listen 127.0.0.1`),
|
||||
`insecure` is fine because it is not network-reachable; no token required.
|
||||
- There is **no dual-listener** design. The practical default during `.4.2` (the reason
|
||||
in-process serving exists is to give the agent a gRPC target) is the **bridge address +
|
||||
token**. `127.0.0.1` is reserved for the daemon-local-only case.
|
||||
- **Agent access → the container bridge.** The agent runs in a task-scoped container on the
|
||||
host and reaches the State Store over the Docker bridge gateway, exactly as it reaches the
|
||||
daemon's NATS today. To close the "any host process could reach the store" gap, the agent
|
||||
**authenticates with a per-task bearer token** carried in gRPC metadata by a client interceptor
|
||||
(`StateStoreToken`, §6). Network reachability + the token is the trust boundary for the
|
||||
default loopback/bridge topology.
|
||||
host and reaches the State Store over the Docker bridge gateway (the bind address from the
|
||||
topology rule above), exactly as it reaches the daemon's NATS today. To close the "any host
|
||||
process could reach the store" gap, the agent **authenticates with a per-task bearer token**
|
||||
carried in gRPC metadata by a client interceptor (`StateStoreToken`, §6). Network
|
||||
reachability + the token is the trust boundary for the default bridge topology.
|
||||
- **The daemon** uses the local adapter (`*store.Store`) in-process by default, so no network
|
||||
boundary exists until `[services.state].target` is set; when it is set, the daemon client
|
||||
authenticates with a token supplied alongside the target.
|
||||
@@ -576,8 +587,10 @@ an explicit operator decision.
|
||||
`internal/infrastructure/store`), not the final infrastructure boundary. The producer-owned
|
||||
daemon/webui store surfaces live there now but may relocate with the implementation.
|
||||
- **In-process listener + token lifecycle:** the daemon binds the in-process State Store
|
||||
listener, selects the Docker-bridge host-gateway address (reusing the embedded-NATS
|
||||
host-gateway resolution), and injects `STATE_STORE_URL`/`STATE_STORE_TOKEN` per task via
|
||||
listener to the **host-gateway bridge address** when agent containers consume it (the Phase 2
|
||||
default) or loopback-only when the daemon is the sole consumer — one listener, one address
|
||||
rule, never both (rev. 2c). It selects the bridge address by reusing the embedded-NATS
|
||||
host-gateway resolution and injects `STATE_STORE_URL`/`STATE_STORE_TOKEN` per task via
|
||||
`containerEnv`. Token is per-incumbence (task + container grace period) and validated by a
|
||||
gRPC interceptor → `codes.Unauthenticated` on missing/unknown/expired. Non-loopback targets
|
||||
fail closed without TLS or a token.
|
||||
@@ -603,8 +616,10 @@ an explicit operator decision.
|
||||
- **Agent handoff:** `agentworker.Settings` gains `StateStoreTarget`/`StateStoreToken`/
|
||||
`StoreTimeout`, injected as `STATE_STORE_URL`/`STATE_STORE_TOKEN` env (mirrors the NATS
|
||||
handoff); `Transport.Store` returns a long-lived gRPC `workflow.Store` client.
|
||||
- **Transport security:** loopback-only + `insecure` by default; agent authenticates over the
|
||||
container bridge with a per-task bearer token; TLS/mTLS is an operator choice for any
|
||||
- **Transport security + listener topology (rev. 2c):** one in-process listener, bound to the
|
||||
host-gateway bridge address when agent containers consume it (the Phase 2 default) or
|
||||
loopback-only for a daemon-local-only consumer. `insecure` only on loopback; mandatory
|
||||
per-task bearer-token auth on the bridge; TLS/mTLS is an operator choice for any
|
||||
non-loopback/k8s topology.
|
||||
- **Mode = presence-based `[services.state].target`**, default **local** (not yet extracted);
|
||||
add `[services.state]` to `config.example.toml`.
|
||||
|
||||
Reference in new issue
Block a user