docs(state-store): rev.2b resolves second-pass review inconsistencies

Address the second-pass review of the State Store ratification doc (beads archie-core-8cda.4.1):

- State migration-decisions.md section 4 remains authoritative and open; this PRD
  does not replace it. The Task/Status/Source + interface relocation is flagged as
  a minimal, pulled-forward Phase 2 prerequisite only.
- Fix stale WorkflowStore reference in service-decomposition.md Q4: the workflow
  contract is the domain-owned workflow.Store, which supersedes internal/store's
  WorkflowStore.
- Label internal/store as a TRANSITIONAL compatibility location (target
  internal/infrastructure/store), matching dependencies-and-contracts.md.
- Call out the current-state outliers explicitly: workflow files/tests still import
  internal/store, store.WorkflowStore is still in TaskContext, and the NATS storerpc
  path is still wired -- the acceptance criterion is NOT yet met.
- Operationalize the agent gRPC handoff: who binds the in-process State Store
  listener (daemon, mirroring serveGateway), Docker-bridge host-gateway address
  selection (reuses the embedded-NATS container/network.go resolution), per-task
  injection via containerEnv beside NATS_URL, per-incumbence bearer token lifecycle
  + gRPC-interceptor validation -> codes.Unauthenticated, and fail-closed on
  non-loopback targets without TLS/token.
- Update beads archie-core-8cda.4.2/.4.5 descriptions to match the ratified scope
  (type/interface relocation, RecordDispatch *sql.Tx drop, in-process serving,
  agent gRPC handoff).
This commit is contained in:
sam committed 2026-09-06 23:58:17 +10:00
1 parent a43a2e1cc0
commit 8cb6410fc4
2 files changed
+89 -3

No files matched your search

+5 -1
View File
@@ -176,7 +176,11 @@ Verified couplings that this decomposition must eliminate:
**RESOLVED (2026-09-05).** One State Store service owns the existing
single SQLite file behind narrow typed contracts (`TaskStore`,
`CaptureStore`, `MappingStore`, `BindingStore`, `WorkflowStore`) over
gRPC. No physical database-per-service: the solo-maintainer / team-
gRPC. *(Ratified 2026-09-06: the workflow contract is now the
domain-owned `workflow.Store`, which supersedes
`internal/store`'s `WorkflowStore`. See note below and
`docs/prds/state-store-contract.md`.)*
No physical database-per-service: the solo-maintainer / team-
topology rule of thumb plus the low value of per-service autonomy for
one person rule it out, and one store means no distributed-transactions
problem. The Gateway keeps its own already-separate session SQLite.
+84 -2
View File
@@ -18,6 +18,23 @@ split `archie.db`. It records method ownership, DTO/wire representation, error s
limits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that
`.4.2` and `.4.3` have exactly one authoritative surface to build against.
> **Current state (before implementation) — read before `.4.2` starts.** The acceptance
> criterion ("`internal/domain/workflow` … no longer import `internal/store`") is **not yet
> met** and is **not implied to be met by this document**. Today, production workflow files
> and tests import `internal/store` (`internal/domain/workflow/{workflow,steps,triage,review,
> feasibility,implement}.go`), `store.WorkflowStore` remains in `TaskContext`, and the NATS
> `storerpc` path is still wired. Those are the **current, pre-implementation outliers** that §12
> step 2 (relocation) and `.4.2` remove. Nothing in this document describes code that already
> exists; it describes what `.4.2`/`.4.3` build and what the prerequisite changes are.
> **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/
> migration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →
> StepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)
> **remains the authoritative, open document for the long-term Workflow migration.** This PRD
> does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface
> relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);
> the rest of §4 stays its own migration and stays open.
---
## 1. Decision (the invariant everything follows)
@@ -62,6 +79,16 @@ contract is consumer-owned (in the domain), while the daemon/webui store surface
implementation satisfies `workflow.Store`. This is the single decision that makes the whole
Phase 2 acceptance criterion and the architecture's rules simultaneously satisfiable.
> **`internal/store` is a TRANSITIONAL compatibility location (rev. 2).** The repository's target
> architecture (`docs/architecture/dependencies-and-contracts.md`, `organisation.md`) places
> persistence implementations under `internal/infrastructure/<capability>`. `internal/store`
> holding the task/capture/mapping/binding implementation and ALSO being the home of the
> producer-owned daemon/webui interfaces is acceptable **only as a transitional location**. The
> long-term home for the store implementation is `internal/infrastructure/store`; the
> producer-owned interfaces may move to the same infrastructure package (or an approved
> contract location) when the store implementation relocates. Agents must not treat
> `internal/store` as the final infrastructure boundary.
---
## 2. Contract boundary
@@ -159,7 +186,9 @@ The Phase 2 acceptance criterion ("`internal/domain/workflow` … no longer impo
criterion is satisfied. It consumes `store.Task`'s replacement as `workflow.Task`, uses
`workflow.Status*`/`workflow.Source*`, and depends on its own `workflow.Store` interface.
- `internal/store` imports `internal/domain/workflow` for the `Task`/`Status`/`Source` types it
reads and writes (infrastructure → domain).
reads and writes (infrastructure → domain). **NOTE: `internal/store` is a transitional
compatibility location only** — its long-term home is `internal/infrastructure/store` (see
the callout in §1). Do not treat `internal/store` as the final infrastructure boundary.
- `TestRecordDispatchViaExplicitTx` and every store test that constructs `store.Task{…}` are
updated to the relocated type as part of this prerequisite. This is a mechanical rename
across ~6 workflow production files (`workflow.go`, `steps.go`, `triage.go`, `review.go`,
@@ -296,6 +325,24 @@ moved to gRPC and the container env carries `STATE_STORE_URL`. Until then both p
(agent flips when the daemon starts injecting `STATE_STORE_URL`); there is no dual-live window
across a single agent process, which is either NATS-backed or gRPC-backed, never both.
### Operational specifics (in-process listener → address → per-task injection)
- **Who binds the in-process State Store listener:** the daemon (`archied`), at bootstrap, when
the State Store is served in-process/multiplexed (mirroring `serveGateway` in
`internal/app/archied/gateway.go`): a `grpc.NewServer()` + `RegisterServer` + graceful stop on
`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`).
- **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` /
`STATE_STORE_URL`, `-state-store-token` / `STATE_STORE_TOKEN`), the same seam as `NATS_URL`. A
reloaded `[services.state]` must not point new containers at a store the daemon is not serving
— the same immutability rule as NATS.
---
## 7. Error semantics
@@ -401,6 +448,26 @@ stated explicitly rather than left implicit.
confirmation caveat. The NATS-KV discovery fallback supplies endpoints but does not add
transport security; that stays the operator's responsibility.
### Token lifecycle (rev. 2)
- **Generation:** the daemon generates a per-task bearer token when it acquires the container
(or per incumbence) and injects it via `containerEnv` as `STATE_STORE_TOKEN`. A single token
may cover a task's container lifetime.
- **Lifetime:** tied to the task + container grace period; rotated on a new container acquisition
for the same task; a token for a released container is invalidated.
- **Validation:** a gRPC interceptor on the State Store server validates the token against the
daemon's issued-token set; missing/unknown/expired → `codes.Unauthenticated`. The token is
carried in gRPC metadata, never in a URL.
### Fail-closed on non-loopback (rev. 2)
If `[services.state].target` points to a non-loopback address and **neither** TLS **nor** a token
is configured, the State Store client (daemon or agent) **fails closed** — it refuses to
start/dial rather than fall back to a plaintext, unauthenticated remote connection. This mirrors
the gateway's `--listen`/`--enable-cors-header` confinement caveat and prevents a silent
unauthenticated remote store. The loopback + token default is the only path that starts without
an explicit operator decision.
---
## 10. Mode / config shape
@@ -478,7 +545,9 @@ stated explicitly rather than left implicit.
(`Update`/`Transition`/`InsertEvent`) from NATS JSON `storerpc` to `staterpc.Client` over
gRPC, using the §6 handoff. The daemon serves the gRPC `StateStore` server **in-process
(multiplexed)** first so the agent has a gRPC target before the standalone binary exists
(PRD §3 "multiplexed in-process is the migration default"). Flip the agent's
(PRD §3 "multiplexed in-process is the migration default"). Bind the in-process listener and
inject `STATE_STORE_URL`/`STATE_STORE_TOKEN` per task (see §6 "Operational specifics"). Also
land the `RecordDispatch` `*sql.Tx` drop (see §5) in the same span. Flip the agent's
`Transport.Store` to a gRPC client once `STATE_STORE_URL` is injected.
4. **Delete NATS `storerpc` only after the agent is fully on gRPC** — delete `internal/storerpc`
(Server, Client, subjects `archie.store.update|transition|insert_event`), the
@@ -503,6 +572,19 @@ stated explicitly rather than left implicit.
## 13. Decisions recorded (for the review trail)
- **`internal/store` is a transitional compatibility location** (target
`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
`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.
- **Acceptance criterion is NOT yet met.** `internal/domain/workflow` still imports
`internal/store` (workflow files + tests), `store.WorkflowStore` is still in `TaskContext`,
and the NATS `storerpc` path is still wired. §12 step 2 and `.4.2` remove these; this
document does not imply the criterion is already satisfied.
- **Ownership split:** domain-facing workflow contract is **consumer-owned** in the domain
(`workflow.Store` + `workflow.Task`/`Status`/`Source`, per dependency rules #2 and #7);
daemon/webui store surfaces stay **producer-owned** in `internal/store`. `store.WorkflowStore`