docs(state-store): ratify Phase 2 State Store contract boundary and transport

Define the authoritative Phase 2 State Store contract boundary and
transport design (beads archie-core-8cda.4.1): one StateStore gRPC
service (40 RPCs) behind the narrow typed store contracts, producer-owned
in internal/store, with a staterpc.Client remote adapter that satisfies
the same interfaces via explicit compile-time assertions. Records method
ownership, DTO/wire representation, error semantics (structured gRPC codes
rehydrated to store sentinels so errors.Is survives), limits, mode/config
shape (presence-based [services.state].target, default local), local-
adapter compatibility, and cutover/deletion rules. Fixes the RecordDispatch
wire blocker (*sql.Tx dropped; production passes nil) and keeps Close()
off the wire. References the new doc from the service-decomposition PRD.
This commit is contained in:
sam committed 2026-09-06 23:36:52 +10:00
1 parent 703f09cf51
commit bcde4ae69a
2 files changed
+372

No files matched your search

+9
View File
@@ -184,6 +184,15 @@ Verified couplings that this decomposition must eliminate:
contract at a time, stand up the store service, split the file only on
evidence):
`docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#4`.
**RATIFIED (2026-09-06, beads archie-core-8cda.4.1).** The authoritative
contract boundary & transport design for this is now fixed in
`docs/prds/state-store-contract.md` (one `StateStore` gRPC service, 40
RPCs, producer-owned contracts, `RecordDispatch` drops `*sql.Tx`, `Close`
off-wire, structured gRPC error codes, presence-based
`[services.state].target` defaulting local, migration order
`WorkflowStore -> archie-state-store -> Capture -> Mapping -> Binding ->
TaskStore`). `.4.2` and `.4.3` implement against that doc.
5. **Helm chart / Operator ownership.** Net-new work with no existing
analog in this repository (`deployments/` currently holds TOML profiles
and a `docker-compose.yml`, not Kubernetes manifests). Scoping not yet
+363
View File
@@ -0,0 +1,363 @@
# State Store — contract boundary & transport (ratification)
**Status:** Ratified — 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
**Beads milestone:** archie-core-8cda.4.1
**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)
This document fixes the **contract boundary** and **transport** for the State Store
service. It does not redesign Archie's domain model, does not invent a second store,
and does **not** split `archie.db`. It records method ownership, DTO/wire
representation, error semantics, 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.
---
## 1. Decision (the invariant everything follows)
Archie is composed such that a single **`archie-state-store`** service owns the one
existing SQLite file (`archie.db`) and exposes it over **gRPC behind the narrow typed
contracts already defined in `internal/store/interface.go`**. There is exactly one
store, one file, one service. No database-per-service, no distributed transactions, no
second store abstraction.
The store contracts remain **producer-owned** (they live in `internal/store`, not in a
consumer package). Two adapters satisfy the *same* interfaces:
- **Local adapter** — `*store.Store` (the in-process SQLite implementation).
- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).
Each adapter carries an explicit compile-time assertion against the store interfaces it
serves. Composition picks local vs. remote by the presence of `[services.state].target`
(empty = local; set = dial the gRPC service). Default is **local** (the State Store is
not yet extracted), which is the PRD §3 posture; it differs from the gateway's
remote-default only because the gateway is already a separate deployment and the State
Store is not.
> **Contract-ownership fork, decided.** The gateway precedent is consumer-owned
> (`gateway.SessionStore`, `gateway.ChatContract` live beside the consumer, both
> adapters live outside). The store precedent is producer-owned (`store.WorkflowStore`
> lives in `internal/store`, both adapters live outside). The State Store keeps the
> **producer-owned** shape: the contracts are the domain store's native interface, and
> they must not be re-declared in a consumer package. This is what `.4.2`/`.4.3` assume.
---
## 2. Contract boundary
`internal/store/interface.go` is the authoritative source. `TaskStore` is the only
composite; every other interface is flat. Narrow slices are split along consumer-capability
lines so no consumer acquires a surface it does not need (`interfacebloat` cap = 8).
| Interface | Embeds | Methods | Local impl | Remote impl |
|---|---|---|---|---|
| `TaskStore` | `TaskLifecycle`, `TaskEvents`, `TaskQueries`, `TaskArchiver`, `TaskRetryer` | 24 (union) | `*Store` | `*staterpc.Client` |
| `TaskLifecycle` | — | 8 | `*Store` | `*staterpc.Client` |
| `TaskEvents` | — | 7 | `*Store` | `*staterpc.Client` |
| `TaskQueries` | — | 7 | `*Store` | `*staterpc.Client` |
| `TaskArchiver` | — | 1 | `*Store` | `*staterpc.Client` |
| `TaskRetryer` | — | 1 | `*Store` | `*staterpc.Client` |
| `WorkflowStore` | — | 3 | `*Store` | `*staterpc.Client` |
| `CaptureStore` | — | 2 | `*Store` | `*staterpc.Client` |
| `MappingStore` | — | 5 | `*Store` | `*staterpc.Client` |
| `BindingStore` | — | 6 | `*Store` | `*staterpc.Client` |
| `BindingDispatcher` | — | 3 | `*Store` | `*staterpc.Client` |
| `BindingTaskCreator` | — | 1 | `*Store` | `*staterpc.Client` |
**Key property of the remote client:** `*staterpc.Client` is a *single* adapter that wraps
one `StateStoreClient` and is asserted against **whichever narrow Go interfaces its
caller needs** (exactly as `gatewayrpc.Client` asserts both `gateway.ChatContract` and
`gateway.SessionStore`). The Go contracts stay narrow (≤8, the `interfacebloat` cap);
the wire is one service. `WorkflowStore` introduces **no new RPCs** — it is a narrow
consumer face over the same `Update`/`Transition`/`InsertEvent` RPCs.
---
## 3. Method ownership
`*Store` remains the single implementation of all eleven interfaces. Ownership below is
about which **process** is the primary consumer of each method today, and therefore
which methods are genuinely cross-process on the wire today vs. daemon-internal.
Process legend: **DAEMON** = `archied` (incl. in-process webui + gateway runtime +
`storerpc.Server`); **AGENT** = `archie-agent` worker (no DB connection); **GATEWAY**
= store access through daemon-side narrow adapter interfaces.
| Contract | Primary consumers (process) | Remote on the wire? |
|---|---|---|
| `TaskLifecycle` (8) | DAEMON (dispatch, claim, action) + **AGENT** (`Transition`, `Update` via storerpc) | `Transition`/`Update` = **YES** (agent); rest DAEMON |
| `TaskArchiver` (1) | DAEMON (`taskactions` archive) | not yet |
| `TaskRetryer` (1) | DAEMON (`taskactions` retry) | not yet |
| `TaskQueries` (7) | DAEMON + GATEWAY (status/list adapters) | not yet (`OpenPRs`/`Tasks`/`StatusCounts` do cross to gateway adapters in-process) |
| `TaskEvents` (7) | DAEMON + **AGENT** (`InsertEvent` via storerpc) | `InsertEvent` = **YES** (agent); rest DAEMON |
| `WorkflowStore` (3) | **AGENT** only | **YES** (the sole genuinely remote consumer today) |
| `CaptureStore` (2) | DAEMON (webhook intake + mapping editor) | not yet |
| `MappingStore` (5) | DAEMON (dashboard editor + dispatch loop) | not yet |
| `BindingStore` (6) | DAEMON (dashboard editor + dispatch loop) | not yet |
| `BindingDispatcher` (3) | DAEMON (dispatch loop) | not yet |
| `BindingTaskCreator` (1) | DAEMON (dispatch loop) | not yet |
**Consequence for migration order:** the **agent's `WorkflowStore` is already
cross-process today** (via the NATS `storerpc` surrogate), so it is the first contract
to move to gRPC. The daemon-internal surfaces (`Capture`/`Mapping`/`Binding`) stay
in-process until the daemon itself points at `archie-state-store`. `TaskStore` (the
large composite) moves last.
**Two orphan methods** — `TaskQueries.ClearTerminalTasks` and
`TaskQueries.IncrementRetryCount` have **no production consumer** (only `*Store` tests).
They remain part of the Go `TaskQueries`/`TaskStore` surface, and therefore part of the
wire contract, but are flagged for deletion: they must **not** gain dedicated consumers
or wire methods in this work. Do not add the rest of the codebase to them.
---
## 4. DTO / wire representation
### Proto layout
- **Service:** `proto/state/v1/state.proto`, `package state.v1`, **one** `StateStore`
service (mirrors the gateway's single `ChatService`; proto bypasses the Go
`interfacebloat` cap, as `ChatContract` does via `//nolint:interfacebloat`).
- **Codegen:** the existing buf v2 pipeline. `proto/buf.yaml` (module, lint STANDARD,
breaking FILE against `main`), `proto/buf.gen.yaml` **managed mode** with
`go_package_prefix → github.com/samcharles93/archie-core/internal/contracts`, plugins
`protoc-gen-go` + `protoc-gen-go-grpc`, `out: ../internal/contracts`,
`opt: paths=source_relative`. **No `go_package` in source** — managed mode owns it.
Generated Go lands in `internal/contracts/state/v1/` (package `statev1`), committed
(`proto:check` fails on uncommitted/unmodified generated files).
- **Adapter package:** `internal/infrastructure/staterpc/` with `server.go` (registers
the generated server over a `store.TaskStore`), `client.go` (wraps the generated
client into `store.*` facades), `values.go` (proto ⇄ domain mappers), and
`conformance_test.go` (bufconn local-vs-grpc dual-adapter suite), mirroring
`internal/infrastructure/gatewayrpc/`.
- **Binary:** `cmd/archie-state-store/main.go`, mirroring `cmd/archie-gateway/main.go`
and the serve pattern in `internal/app/archied/gateway.go` (`serveGateway`).
### The `StateStore` RPC set (union of the contracts, grouped)
Methods are named after the store methods so the mapping is unambiguous. `WorkflowStore`
is a *view*, not new RPCs — `Update`/`Transition`/`InsertEvent` are shared with
`TaskLifecycle`/`TaskEvents` and appear once.
| Group | RPCs |
|---|---|
| Lifecycle | `EnqueueIssue`, `EnqueueChatTask`, `ClaimNext`, `ClaimByIssue`, `Transition`, `Update`, `Requeue`, `RecoverStale` |
| Archive / Retry | `ArchiveTask`, `RetryTask` |
| Queries | `TaskByIssue`, `TaskByID`, `OpenPRs`, `ClearTerminalTasks`, `Tasks`, `StatusCounts`, `IncrementRetryCount` |
| Events | `InsertEvent`, `EventsSince`, `TaskEvents`, `WorkflowStats`, `StageStats`, `TokensByDay` |
| Capture | `InsertCapture`, `ListCaptures` |
| Mapping | `InsertMapping`, `GetMapping`, `ListMappings`, `UpdateMapping`, `DeleteMapping` |
| Binding | `InsertBinding`, `GetBinding`, `ListBindings`, `UpdateBinding`, `DeleteBinding`, `ApproveBinding` |
| Dispatch | `ArmedBindingsForSource`, `RecordDispatch`, `ListUndispatchedCaptures` |
| BindingTaskCreator | `EnqueueBindingTask` |
That is **40 unique RPCs** across one service (the `TaskEvents`.Close method is dropped).
`Close()` is **excluded** from the wire (it is server lifecycle, not a client call) — see §8.
### Domain types and `values.go` mapping
`values.go` maps proto ⇄ these types (all already cross boundaries today via JSON):
| Domain type | Package | Notes for `values.go` |
|---|---|---|
| `store.Task` | `internal/store` | time fields stored as layout strings; convert to/from `google.protobuf.Timestamp` |
| `events.Event` | `internal/events` | `Timestamp` → `google.protobuf.Timestamp` |
| `store.CapturedEvent` | `internal/store` | headers/body/remote_addr; body capped 256 KiB |
| `mapping.Mapping` | `internal/domain/mapping` | JSON-path field bindings |
| `binding.Binding` | `internal/domain/binding` | secret is **already decrypted** before returning; keep decrypted form out of any durable/logged representation |
| `store.WorkflowStat` | `internal/store` | aggregate row |
| `store.StageStat` | `internal/store` | aggregate row |
| `store.DayTokens` | `internal/store` | aggregate row |
### Wire-contract blocker fixed here: `RecordDispatch`
`store.BindingDispatcher.RecordDispatch(ctx context.Context, tx *sql.Tx, bindingID,
bindingVersion int64, captureID int64, taskID int64) error` takes a **`*sql.Tx`** that
cannot cross a gRPC boundary.
**Evidence that the `*sql.Tx` is removable:** the dispatch loop calls
`RecordDispatch(ctx, nil, ...)` (`internal/daemon/daemon.go:591`). The implementation
falls back to the store's own `*sql.DB` when `tx == nil` ("best-effort, not atomic"; the
comment and the `TestRecordDispatchViaExplicitTx` test are the only consumers of the
non-nil `tx` path). Production never opens the explicit transaction.
**Decision:** the contract drops `*sql.Tx` from `RecordDispatch` (the method becomes
`RecordDispatch(ctx, bindingID, bindingVersion, captureID, taskID) error`). The store
service owns any transaction boundary internally when atomicity is wanted; today the
at-most-once guarantee is the `INSERT OR IGNORE` dedup row, which is already
transactionless in production. `TestRecordDispatchViaExplicitTx` is superseded by the
store service's own internal-transaction test.
---
## 5. Error semantics
### Current state (both boundaries lose error identity)
- **NATS `natsrpc.Envelope`** (`internal/natsrpc/natsrpc.go`) serialises any error to a
single `err.Error()` string and rehydrates a fresh `errors.New(string)`. The original
type, `%w` chain, and sentinel identity are lost → `errors.Is(err, store.ErrStaleTransition)`
is **false** across the boundary.
- **gRPC `gatewayrpc`** currently returns raw `err` from handlers; gRPC-Go converts to
`codes.Unknown` with only the message. The **only** explicit code in the repo is
`codes.Unavailable` for a missing session store (`server.go:31`). No status-code
mapping for store errors exists.
### Decision — structured mapping so `errors.Is` survives
The `StateStore` service must map the store's sentinel errors to canonical gRPC codes and
rehydrate them to the *same* sentinels on the client, so consumer `errors.Is` checks keep
working — an improvement over today's flattening, not a regression.
| Store sentinel / outcome | gRPC code | Client rehydrates to |
|---|---|---|
| `store.ErrStaleTransition` | `FailedPrecondition` | `store.ErrStaleTransition` |
| `store.ErrBindingNotFound` | `NotFound` | `store.ErrBindingNotFound` |
| `store.ErrMappingNotFound` | `NotFound` | `store.ErrMappingNotFound` |
| `store.ErrBindingOverlap` | `FailedPrecondition` | `store.ErrBindingOverlap` |
| `store.ErrBindingTransition` | `FailedPrecondition` | `store.ErrBindingTransition` |
| `store.ErrAlreadyDispatched` | `AlreadyExists` | `store.ErrAlreadyDispatched` |
| not-found-as-`(nil,nil)` (`TaskByID`, `GetBinding`, `GetMapping`, `ClaimNext`, `ClaimByIssue`, …) | `NotFound` with a `found=false` field (NOT an error) | `(nil, nil)` |
| infra / wrapped error | `Internal` (full message in details) | wrapped `fmt.Errorf(...%w)` |
| capability absent | `Unavailable` | context/typed error |
The `found=false`-not-error convention matters: the repo deliberately returns
`(nil, nil)` for not-found in reads and a sentinel for not-found in writes. The wire must
preserve **both** conventions (a `GoogleRPCStatus` with `NotFound` is an *error*, which
would wrongly surface to callers that expect `(nil, nil)`). Implement `found` as an
explicit boolean field on read responses, and map `(nil,nil)` ⇄ `found=false` + `OK`.
---
## 6. Limits
**Interface bloat (`interfacebloat` cap = 8)** — `.golangci.yml:89` `interfacebloat: max: 8`,
which overrides the upstream default of 10. The Go consumer facades must stay ≤8 methods.
`TaskLifecycle` is exactly 8 (at the cap); `TaskStore` is the 24-method composite that the
cap is why it is decomposed; proto services bypass the cap (like `ChatContract`).
**Payload caps:**
- Capture body: `defaultCaptureMaxBodyBytes = 256 KiB` (may reduce further; wire message
must not exceed gRPC's default 4 MiB receive limit for a single capture).
- Task `detail`/`park_reason`/event `Detail`: 4000-char hard cap (`clip(s, 4000)`).
**Retention (stays server-side in the store; the wire does not carry pruning decisions):**
- `events` table: **no prune, unbounded growth** — a known risk to revisit, not changed here.
- `captured_events`: prune-on-write, default 7 days / 5000 events.
**Pagination/arity:** store read methods take a raw `int limit` (no store-side cap); the
caller-side caps (task list 100, log 2000, captures 100, capture scan window 5000, binding
dispatch batch 100, session list 20) remain caller-side. The wire passes `limit int` and
returns `[]*` slices, mirroring the existing Go signatures — **no cursor/paging protocol is
introduced** in this work (the current `EventsSince(sinceID, limit)` offset cursor is the
only one, and it stays as-is).
---
## 7. Mode / config shape
**Follow the gateway's presence-based `target` seam, not the NATS `mode` enum.**
- `internal/config/services.go` gains a `State ServiceConnection` field:
```go
type Services struct {
Gateway ServiceConnection `toml:"gateway" yaml:"gateway"`
State ServiceConnection `toml:"state" yaml:"state"`
}
type ServiceConnection struct {
Target string `toml:"target" yaml:"target"`
}
```
- **Empty `Target` → local** `*store.Store` adapter (the default; State Store not yet
extracted). **Set `Target` → dial gRPC** and use `*staterpc.Client`. This differs from
the gateway, where `Target` is always defaulted to `127.0.0.1:8585` because the gateway
is already a separate process.
- Because `[services.state]` is **not** in `config.example.toml` today (the gateway's own
section is also missing — documentation debt), **add `[services.state]`** with a
commented `target` to `config.example.toml` in the same change that introduces the
config field, so the seam is visible to operators.
- Composition root: `internal/app/archied/bootstrap.go`. Base path = the local
`*store.Store` (already opened by `openProductionTaskStore` / the store service owns
`openStores`); if `cfg.Services.State.Target != ""`, dial gRPC and assign
`b.stateStore = staterpc.NewClient(conn)`.
> **Mode fork, decided.** The gateway uses a single `target` address (no enum). The State
> Store boundary uses the same seam for symmetry, but with the opposite default
> (local, not remote) because the State Store is not yet extracted. No `mode` field is
> added.
---
## 8. Local-adapter compatibility + conformance
- `*store.Store` (local) and `*staterpc.Client` (remote) satisfy the **same** store
interfaces. Use **explicit** `var _ store.X = (*Client)(nil)` assertions on **both**
adapters (the gateway's local adapters use only structural/return-type assertions; the
store precedent's explicit `var _` style is stronger and should be adopted on both sides).
```go
var _ store.WorkflowStore = (*staterpc.Client)(nil) // first contract to move
// then progressively CaptureStore, MappingStore, BindingStore,
// BindingDispatcher, BindingTaskCreator, and finally TaskStore.
var _ store.WorkflowStore = (*Store)(nil) // local, already present in store
```
- **Conformance suite:** a `staterpc/conformance_test.go` bufconn suite runs the **same**
contract through both `"local"` and `"grpc"` adapters (mirroring
`gatewayrpc/conformance_test.go`), asserting error-sentinel fidelity and the
not-found-as-`(nil,nil)` convention both ways.
- **`Close()`:** stays on the Go store interfaces (so `TaskStore`/`TaskEvents` remain
fully satisfiable) but is **not** a `StateStore` RPC. The remote `staterpc.Client`
implements `Close()` as a **no-op**; the store service owns its own DB lifecycle. When
the daemon hands the store to `archie-state-store`, `b.cleanup()` no longer calls
`store.Close()` on a remote client (it is the daemon's own lifecycle only when it owns
the store in-process).
---
## 9. Cutover / deletion rules
1. **Ratify the contract (this document).** No code.
2. **`.4.2` — generalize `storerpc` to the gRPC contract.** Move the agent's
`WorkflowStore` (`Update`/`Transition`/`InsertEvent`) from NATS JSON `storerpc` to
`staterpc.Client` over gRPC. 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").
3. **`clear NATS storerpc` only after the agent is fully on gRPC** — delete
`internal/storerpc` (Server, Client, subjects `archie.store.update|transition|insert_event`)
and the `natsrpc.RegisterAll` registration in one commit, and remove the now-unused
`store.WorkflowStore` NATS path in `internal/infrastructure/agenttransport/nats`.
4. **`[services.state].target` stays empty (inproc)** through `.4.2`; `archie-state-store`
`cmd/` binary is **`.4.3`** and hosts the same `StateStore` gRPC service.
5. **Swap daemon-internal contracts one at a time** (only once the daemon points at
`archie-state-store`): `Capture → Mapping → Binding → TaskStore`. Each swap is
independent — add the remote-client composition path, run the per-contract conformance
suite, flip `[services.state].target`, delete the local use. A consumer mixes in-process and
remote contracts for a contract-code (no dual-live *window*; each contract is either
local or remote at a time).
6. **Final flip / deletion of the in-process serving path:** when the daemon no longer
owns the store (i.e. `TaskStore` has moved), delete the in-process `openProductionTaskStore` /
`wireWebStoreSurfaces` path in the daemon in a **same-commit** deletion — no dual-store
ownership. The single SQLite file remains owned by `archie-state-store`.
7. **Never** split `archie.db` or add a second store. The gateway keeps its own
already-separate session SQLite; that is unchanged and out of state-store scope.
---
## 10. Decisions recorded (for the review trail)
- **Producer-owned contract** (contracts stay in `internal/store`), not consumer-owned.
- **One `StateStore` gRPC service** (40 RPCs, grouped by contract) + narrow Go consumer
facades (≤8) on `staterpc.Client` — mirrors the single-`ChatService` precedent.
- **`RecordDispatch` drops `*sql.Tx`** (wire-blocker; production passes `nil` today).
- **`Close()` not on the wire**; remote client `Close()` is a no-op.
- **Structured gRPC error codes** with client rehydration to store sentinels (preserves
`errors.Is`), and a `found=false` + `OK` convention for read not-found.
- **Mode = presence-based `[services.state].target`**, default **local** (not yet
extracted); add the `[services.state]` section to `config.example.toml`.
- **Explicit `var _` assertions on both adapters**; per-contract bufconn conformance.
- **Migration order:** `WorkflowStore` (agent) → stand up `archie-state-store` →
`Capture` → `Mapping` → `Binding` → `TaskStore`; NATS `storerpc` deleted once the agent
is on gRPC; in-process store path deleted in a same-commit flip.
- **Orphans `ClearTerminalTasks`/`IncrementRetryCount`** retained but not built upon.