docs: correct the withdrawn State Store topology and the authority revision

Two of the three findings from review. The third had already been fixed by the
version of the service-registry PRD that landed on main.

1. docs/prds/state-store-contract.md §10 still prescribed the topology that was
   deleted when the State Store was extracted. It said an empty `Target` opens a
   local `*store.Store` adapter, and that the daemon's base path is that local
   store "already opened by openProductionTaskStore". Neither holds: the
   standalone archie-state-store process exclusively owns archie.db, and both
   archied and archie-gateway reject an empty target (bootstrap.go,
   state_store_client.go: "services.state.target is required").
   openProductionTaskStore still exists, but only inside that standalone process.
   Following the ratified section would have reinstated the deleted in-process
   ownership path. The config.example.toml bullet (which still advised adding the
   section with a COMMENTED target -- impossible to boot) and the "opposite
   default (local, not remote)" blockquote are corrected with it; the section is
   already present with the target uncommented and marked REQUIRED.

2. CLAUDE.md named the State Store authority rev. 2c while the contract itself is
   ratified at rev. 2d. AGENTS.md is a symlink to CLAUDE.md, so one edit covers
   both guides.

Not changed: the typo-visibility finding is already addressed by the PRD on main.
Its tracking name, unregisteredServiceKeys, is unimplemented in Go, so the runtime
diagnostic is still missing -- filed as archie-core-jp4g.
This commit is contained in:
sam committed 2026-09-19 03:07:38 +10:00
1 parent ea7a054a45
commit 95c4d66504
2 files changed
+23 -15

No files matched your search

+1 -1
View File
@@ -183,7 +183,7 @@ structures found in legacy packages.
`providerRegistry.RegisterOptional`. Missing or failed providers log warnings
and degrade health without terminating the process.
- **`internal/infrastructure/staterpc/` (State Store gRPC contract):**
Authority is `docs/prds/state-store-contract.md` (rev. 2c) -- read it before
Authority is `docs/prds/state-store-contract.md` (rev. 2d) -- read it before
changing this package or its callers.
- The proto (`proto/state/v1/state.proto`, service `StateStoreService`,
package `statev1` in `internal/contracts/state/v1/`) is one gRPC service
+22 -14
View File
@@ -549,22 +549,30 @@ an explicit operator decision.
registered once via `RegisterService(context, name, target, listen, tokenEnv)`. The TOML
shape below is unchanged, so nothing else in this section is affected; read
`cfg.Services.Get("state")` wherever it says `cfg.Services.State`.
- **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`); if `cfg.Services.State.Target != ""`, dial gRPC
and assign `b.stateStore = staterpc.NewClient(conn)` (with the token from config/secret).
- **Empty `Target` → startup error** (corrected in rev. 2d). This bullet previously said an
empty `Target` opens a local `*store.Store` adapter. That default was withdrawn when the
State Store was extracted (§12 step 7): the standalone `archie-state-store` process
exclusively owns `archie.db`, so both `archied` and `archie-gateway` now reject an empty
target (`internal/app/archied/bootstrap.go` and `state_store_client.go`: `services.state.target
is required`). **Set `Target` → dial gRPC** with `*staterpc.Client`; no client opens the
database itself. This differs from the gateway, where `Target` is defaulted to
`127.0.0.1:8585` because `archie-gateway` is already a separate process whose client and
server share one default.
- `[services.state]` is present and **uncommented** in `config.example.toml`, with `target`
marked REQUIRED, because the value is now load-bearing for every client. (This bullet
previously instructed adding the section with a commented-out `target`; that advice is
withdrawn, since a commented target cannot boot.)
- Composition root: `internal/app/archied/bootstrap.go` (the daemon) and
`internal/app/archieui/config.go` (the UI process) both read `cfg.Services.Get("state")` and
dial the remote State Store. `openProductionTaskStore` is **not** called from the daemon: it
lives in the standalone `archie-state-store` process (`internal/app/archied/state_store.go`),
which is the only path that opens `archie.db`.
> **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. A companion
> `STATE_STORE_TOKEN` secret (or a `[services.state] target_token` key) carries authentication.
> boundary uses the same seam for symmetry, and **both now require a non-empty `target`**: the
> State Store's local-store default was withdrawn when the process was extracted (§12 step 7).
> No `mode` field is added. A companion `STATE_STORE_TOKEN` secret (or a
> `[services.state] target_token` key) carries authentication.
---