Every install serves from Postgres, so the legacyread/legacyimport packages, the archie-state-store import command, the boot gate that refused to serve over unimported SQLite files, and db_path (which only located those files) go. Migration 0010 drops the import_completion table.
2.6 KiB
2.6 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.