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.<name>].

Also records the open [chat.*] section naming question in the migration
decision register, where it is blocked on a decision rather than on evidence.
This commit is contained in:
sam committed 2026-09-18 23:23:35 +10:00
1 parent 095284678a
commit 6a965ecbd5
3 files changed
+130 -9

No files matched your search

+16
View File
@@ -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.
+101
View File
@@ -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.<name>].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.<name>]`.
- 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.
+13 -9
View File
@@ -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.<name>]`. 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