From 6a965ecbd53dbe86ceabe885c207ae1b43a2b0c7 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 18 Sep 2026 19:53:56 +1000 Subject: [PATCH] docs(prds): design the service registry and revise the state store contract A service is already one Go type (config.ServiceConnection); what is duplicated is its name, across the struct fields in internal/config/services.go, the default branches in infrastructure/configuration/defaults.go, and every consumer's field access. The drift that permits is already in the tree: the two token resolvers are identical apart from their env var name, and gateway.Target is defaulted while state.Target is a startup error with nothing stating that asymmetry in one place. Key services by name and carry the asymmetry as registration data, so a new service is one RegisterService line rather than an edit in three layers. An empty target default means the operator must supply one, which replaces the required/defaulted split without a branch. The TOML shape is unchanged. state-store-contract.md section 10 mandated the opposite, so it is revised to rev. 2d in the same change rather than left contradicting the design; its own summary already described the seam as [services.]. Also records the open [chat.*] section naming question in the migration decision register, where it is blocked on a decision rather than on evidence. --- docs/architecture/migration-decisions.md | 16 ++++ docs/prds/service-registry.md | 101 +++++++++++++++++++++++ docs/prds/state-store-contract.md | 22 +++-- 3 files changed, 130 insertions(+), 9 deletions(-) create mode 100644 docs/prds/service-registry.md diff --git a/docs/architecture/migration-decisions.md b/docs/architecture/migration-decisions.md index 6c1e84825..43733161a 100644 --- a/docs/architecture/migration-decisions.md +++ b/docs/architecture/migration-decisions.md @@ -529,3 +529,19 @@ config DTO translation will land, so it unblocks the dissolution above. per area when the decisions are already dictated by `dependencies-and-contracts.md`. That is the ceremony pattern this project deliberately avoids. + +## OPEN — `[chat.*]` config section naming + +`configuration.md:160` already states the position: `ChatConfig` holds "separate +channel instance settings... there is no chat-wide settings owner". The config +section name has not followed, so a settings block named for a product surface +owns what the architecture calls channel state. + +Two candidates, neither settled: `[channel.*]` and `[messaging.channel.*]`. The +second reads as a domain path, and no config section in this repo is currently +named after a domain package, so adopting it sets a precedent for every other +section rather than fixing one name. + +Blocked on a maintainer decision, not on evidence. This is a rename with an +operator-visible TOML break, so it should land with the `internal/config` +dissolution recorded above rather than on its own. diff --git a/docs/prds/service-registry.md b/docs/prds/service-registry.md new file mode 100644 index 000000000..f62a957ba --- /dev/null +++ b/docs/prds/service-registry.md @@ -0,0 +1,101 @@ +# Service registry — one declaration per service + +**Status:** Design, pre-implementation. Supersedes `state-store-contract.md` §10's +`State ServiceConnection` struct-field instruction (revised to rev. 2d in the same change). + +## Problem + +A service is already one Go type, `config.ServiceConnection`. What is duplicated is its +**name**, in three layers: + +| Layer | Location | What is hard-coded | +|---|---|---| +| Declaration | `internal/config/services.go:4-14` | `Gateway` and `State` as struct fields | +| Defaulting | `internal/infrastructure/configuration/defaults.go:74-82` | three `if cfg.Services.X.Y == ""` branches | +| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go:80-81` | `cfg.Services.State` / `cfg.Services.Gateway` field access | + +Adding a service means editing all three. The drift this permits is already visible: +`stateStoreResolvedToken` (`state_store_client.go:17-23`) and `gatewayResolvedToken` +(`chat_service.go:20-26`) are byte-identical apart from the env var name, and +`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing +stating that asymmetry in one place. + +`resolveServiceListen(service, flagValue, configured)` (`listen.go:24-34`) is already +name-parameterised. It is the shape the rest should follow. + +## Decision + +**Key services by name, and carry per-service asymmetry as registration data.** + +### 1. Declaration collapses to a map + +```go +// internal/config/services.go +type Services map[string]ServiceConnection +``` + +`ServiceConnection` is unchanged. The TOML shape is unchanged, so no deployment profile, +`config.example.toml`, or `install.sh` edit is required. An unrecognised `[services.foo]` +decodes without a code edit, satisfying criterion 5. + +### 2. Registration is the single entry point + +```go +// internal/config/servicespec.go +func RegisterService(context, name, target, listen, tokenEnv string) +``` + +registered once per service, at package init in `internal/config`: + +```go +RegisterService("both", "gateway", "127.0.0.1:8585", "127.0.0.1:8585", "GATEWAY_TOKEN") +RegisterService("client", "state", "", "127.0.0.1:9090", "STATE_STORE_TOKEN") +``` + +Positional, five strings, as the story specifies. Each argument is data the current code +states in prose or in a branch: + +- `context` is `client`, `server`, or `both`, and decides which fields must resolve + non-empty. A `server` or `both` service must end with a `listen`; a `client` or `both` + service must end with a `target`. +- `target` is the **default**, and an empty default means the operator must supply one. + That single convention replaces the `state.target` required / `gateway.target` defaulted + asymmetry with no branch: `state` registers `""`, `gateway` registers an address. +- `listen` is the default listen address, feeding the existing + flag → `[services.].listen` → default precedence unchanged. +- `tokenEnv` names the fallback env var, replacing the two copied resolvers with one. + +### 3. Defaulting and consumption become loops and lookups + +`applyDefaults` iterates the registry instead of naming services. Consumers read +`cfg.Services.Get("state")`, returning a `ServiceConnection` plus the spec, so +`stateStoreResolvedToken` and `gatewayResolvedToken` collapse into +`Services.ResolvedToken(name, secrets)`. + +## Criteria satisfied + +1. Declared once, in the `RegisterService` call. +2. No second location can contradict it; the map has no per-service fields to disagree with. +3. Registration is the entry point, with the five fields a service has. +4. A new service is one `RegisterService` line: no field, no default branch, no consumer edit. +5. The set of services is registry data, not a struct definition. + +## Scope and risk + +- `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts + its own ratified authority. Its summary (`:7`) already says `[services.]`. +- A typo'd `[services.gatway]` currently fails to decode into a known field and is silently + ignored either way. The registry makes strict rejection of unregistered names possible, + but that is **not** in scope here; it would break criterion 5's open extensibility. +- Existing tests reference `cfg.Services.State` directly (`state_store_client_test.go:82`, + `setup_test.go:278`, and others). They move to `Get`, mechanically. +- No wire contract, no RPC, and no persisted format is touched. The 42-RPC State Store + contract is unaffected. + +## Acceptance + +- Adding a third service is a one-line diff plus its consumer, proven by a test that + registers a throwaway service and asserts its defaults and token fallback resolve. +- `grep -rn 'Services\.\(State\|Gateway\)' --include='*.go'` returns nothing. +- The existing `services_test.go` default and precedence assertions pass unchanged in + behaviour, rewritten only to the new accessor. diff --git a/docs/prds/state-store-contract.md b/docs/prds/state-store-contract.md index b9ec56e97..f51cd95d3 100644 --- a/docs/prds/state-store-contract.md +++ b/docs/prds/state-store-contract.md @@ -1,6 +1,9 @@ # State Store — contract boundary & transport (ratification) -**Status:** Ratified (rev. 2c). Rev. 1 was marked *conditionally ratified*; the three +**Status:** Ratified (rev. 2d). Rev. 2d revises §10 only: the `State ServiceConnection` +struct-field instruction is withdrawn in favour of name-keyed services +(`docs/prds/service-registry.md`). The contract, its 42 RPCs, and the listener topology are +unchanged. 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 @@ -535,16 +538,17 @@ an explicit operator decision. **Follow the gateway's presence-based `target` seam, not the NATS `mode` enum.** -- `internal/config/services.go` gains a `State ServiceConnection` field: +- **Revised (rev. 2d).** This section previously instructed that + `internal/config/services.go` gain a `State ServiceConnection` *struct field*. That + instruction is withdrawn: naming each service as a field is the duplication + `docs/prds/service-registry.md` removes, and this document's own summary (`:7`) already + describes the seam as `[services.]`. Services are keyed by name: ```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"` - } + type Services map[string]ServiceConnection ``` + 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