Recover the OAuth storage slice from f6079e9d and the missing workflow persistence error handling from f07c314e, adapted to the current step contract. Require encryption for OAuth token storage and verify RPC round trips and task-grant denial.
3.0 KiB
State Store
Authority: docs/prds/state-store-contract.md and the State Store section of
CLAUDE.md. All persistence is PostgreSQL behind the standalone State Store
process; nothing else opens the database.
Adding a column
- Write the next migration in
internal/infrastructure/postgres/migrations/(00NN_name.sql, goose Up and Down). Give the column aNOT NULL DEFAULTthat is correct for existing rows. - Update the queries in
internal/infrastructure/postgres/queries/and regenerate with sqlc. A query that lists columns (ListTaskSummaries, the binding selects) does not pick the new one up;SELECT *queries do. - Map it in the store (
taskFromRow,bindingValueand friends). If the column holds encoded data, the package that owns the type owns the encoding (task.EncodeInputs), and the store and the wire both use it. - Carry it over the wire (next section) if any process other than the State Store reads it.
Adding a field to a wire message
- Add it to
proto/state/v1/state.protowith a new field number. Never reuse a number; retire one withdeprecated = true. task proto:generate, then map it both ways ininternal/infrastructure/staterpc/values.go.TestTaskProtoCarriesEveryDomainFieldfills everytask.Taskfield and fails on one the mapping forgets. If it cannot fill the field's kind, extend it. Other messages have no such test, so add a round trip toconformance_test.go.
Adding an RPC or a store method
- Put the Go method on the narrow consumer interface in
internal/domain/storecontract(keep each at eight methods or fewer) and add the matching RPC. A Go method without an RPC does not cross the process. - Implement it in the Postgres store, in
staterpc.Client(with itsvar _assertion) and instaterpc.server. A missing dependency answerscodes.Unavailable, never a fabricated default. - Wire the dependency in every composition that serves or consumes it:
stateStoreDepsininternal/app/archied/state_store.go, the daemon's assertions inbootstrap.go, andinternal/app/archieui/compose.gofor the dashboard process. - Task-scoped tokens may call only
Update,TransitionandInsertEventon their own task (staterpc.TaskGrants). A new RPC is admin-only unless it is added there deliberately. - Add it to
conformance_test.go, which runs every surface over a real gRPC connection.
Adding an error sentinel
Add the sentinel to storecontract, a row to wireErrors in values.go, and
a case to error_test.go. The canonical message is part of the wire contract:
changing it breaks errors.Is on the client silently.
Harness OAuth secrets
HarnessSecretStore stores token sets by org and credential service through
admin-only State Store RPCs. The EDA store seals them with the binding cipher's
keyring and a separate HarnessSecretDomain. OAuth writes require a configured
binding encryption key; the legacy binding plaintext fallback does not apply.
The proxy interception and setup terminal are separate harness slices.