From 08deeb57a7b291acef35e7223cafd2f206a940dd Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 26 Sep 2026 13:27:12 +1000 Subject: [PATCH] docs(prds): record the workflow-caller pair and grant widening in the State Store contract (archie-core-t2db.41) --- docs/prds/state-store-contract.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/prds/state-store-contract.md b/docs/prds/state-store-contract.md index 50f6b518a..55e53d565 100644 --- a/docs/prds/state-store-contract.md +++ b/docs/prds/state-store-contract.md @@ -265,13 +265,14 @@ _view_, not new RPCs — `Update`/`Transition`/`InsertEvent` are shared with | Binding | `InsertBinding`, `GetBinding`, `ListBindings`, `UpdateBinding`, `DeleteBinding`, `ApproveBinding` | | Dispatch | `ArmedBindingsForSource`, `RecordDispatch`, `ListUndispatchedCaptures` | | Playbook | `RecordPlaybookDispatch`, `DeletePlaybookDispatches` | +| WorkflowCaller | `EnqueueCallTask`, `WorkflowCallStatus` | | BindingTaskCreator | `EnqueueBindingTask` | | Config snapshot | `PutConfigSnapshot`, `GetConfigSnapshot` | | Apply status | `PutApplyStatus`, `ListApplyStatus` | | Channel status | `PutChannelStatus`, `ListChannelStatus` | | Task log | `ReadTaskLog`, `StreamTaskLogContent` | -That is **51 unique contract RPCs** across one service (the `TaskEvents.Close` method is dropped). +That is **53 unique contract RPCs** across one service (the `TaskEvents.Close` method is dropped). `Close()` is **excluded** from the wire (it is server lifecycle, not a client call) — see §11. The channel-status pair follows the config snapshot's split for the same reason: the writer is the process that HOSTS the channels -- the Messaging Service, which alone observes whether a channel is starting, running or failed -- and the reader is the UI process. Both RPCs are administrative, so a task-scoped grant reaches neither. A channel's state is runtime state rather than a settings document, which is why it is not a `ControlPlaneService` resource kind: a failed channel is not a document anybody edits. Asking for a reload travels on its own surface rather than through this one; see `docs/architecture/migration-decisions.md`, "Channel state to the dashboard". @@ -306,6 +307,19 @@ condition, and the panel that collapsed them told operators task logging was swi it was not. The Go facade is `storecontract.TaskLogStore` (2 methods), carried by `*staterpc.Client` alongside the rest. +The workflow-caller pair was added by `archie-core-t2db.41` (see +`docs/prds/workflow-calls.md`). It is the one surface a task-scoped grant +reaches beyond the three task.Store RPCs: a `workflow.call` step must start +its callee and, with `wait: true`, read it back, and the callee is the +caller's child. Both requests carry the caller's task ID, which the grant +check verifies; `EnqueueCallTask` derives everything else from the caller's +row and refuses a caller that is not running or a call past the depth limit +(`ErrCallCallerNotRunning` / `ErrCallDepthExceeded`), and `WorkflowCallStatus` +re-checks the parent-child relation against the row before answering +(`ErrCallNotYours`), so the interceptor itself never reads the database. The +facade is `workflow/task.Caller` (2 methods), carried by `*staterpc.Client` +and the PostgreSQL store alike. + The playbook pair was added by `archie-core-t2db.17`'s implementation (see `docs/prds/eda-playbook-engine.md`, execution-time gap 2). It is administrative for the same reason as the config-snapshot and apply-status pairs, and @@ -551,9 +565,12 @@ stated explicitly rather than left implicit. cannot leave a grant valid indefinitely. - **Validation and scope (`.4.7`):** a gRPC interceptor (`staterpc.TaskGrants.UnaryInterceptor`) validates the token against the State Store's own issued-grant set; missing/unknown/expired → - `codes.Unauthenticated`. Unlike the daemon's own administrative token (full access to all ~40 - RPCs), a task-scoped grant additionally authorises only `Update`/`Transition`/`InsertEvent` on - its own task ID — every other RPC, including the streaming capture surface and + `codes.Unauthenticated`. Unlike the daemon's own administrative token (full access to all RPCs), + a task-scoped grant additionally authorises only `Update`/`Transition`/`InsertEvent` on + its own task ID, plus the two workflow-caller RPCs naming that same task ID + (`EnqueueCallTask`/`WorkflowCallStatus`, `docs/prds/workflow-calls.md` — the one + sanctioned widening: the callee is the caller's child). Every other RPC, including the + streaming capture surface and `RegisterTaskGrant`/`RevokeTaskGrant` themselves, is `codes.PermissionDenied` for a task-scoped caller. The token is carried in gRPC metadata, never in a URL.