diff --git a/specs/issues/FIX-1788/BUSINESS-RULES.md b/specs/issues/FIX-1788/BUSINESS-RULES.md index c87053a521..2dea897771 100644 --- a/specs/issues/FIX-1788/BUSINESS-RULES.md +++ b/specs/issues/FIX-1788/BUSINESS-RULES.md @@ -25,36 +25,38 @@ work. | # | When | Then | Proved by | |---|---|---|---| -| BR-10 | Alice creates a session naming her worker, on the flow it names | The server checks it at create and links the session to it, in a field only the server writes. Every turn runs as that worker | CI · VG leg a | +| BR-10 | Alice creates a session naming her worker, on the flow it names | The worker is named in the session's starting state, as its readonly `workerId` ([D5](DECISIONS.md#d5)). The server checks it at create. Every turn runs as that worker | CI · VG leg a | | BR-11 | A create names a worker of Bob's | Refused with the same answer as a worker that doesn't exist. No session written | CI · VG leg b | | BR-12 | A create names a worker of Alice's on another flow | Refused, naming both flows. No session written | CI · VG leg b | -| BR-13 | A turn's input carries `worker`, or any route tries to change a session's link | Refused, naming the field. The link never changes: another worker is another session | CI · VG leg b | +| BR-13 | A turn's input carries `worker`, or anything tries to change a session's `workerId`: a block, a tool, an action, `fsdev run --seed-session` on an existing session | Refused, naming the field. The worker never changes: another worker is another session | CI · VG leg b | | BR-13a | Two `ensureWorkerSession` calls with the same criteria race | One session is created and both return it. Two plain creates make two sessions, each checked | CI | | BR-13b | A create uses a derived worker-session id that belongs to another user | Refused. Nobody can take Alice's id before her first `ensureWorkerSession` | CI | -| BR-14 | A session on a worker flow is created with no worker, by the create, by an action on a session id that doesn't exist, or by `fsdev run` without `--worker` | Refused at the door, saying a worker must be named. No session written | CI · VG leg b | -| BR-14a | Alice calls `findWorkerSession({ worker })`, or lists with a `worker` filter | Her sessions linked to that worker, most recent first for the helper; none if there are none. Never another user's. The helper matches on the key set (S5a): it returns only sessions that carry no criteria key it did not name, so plain talk never lands in a delegate, task or workstream session. The list filter is not narrowed | CI · VG leg b | -| BR-15 | A session is created with caller state for the link or a server-written field | Refused with 400, naming the field. Nothing written | CI · VG control `caller-link` | -| BR-16 | A session is deleted and its id created again | The new session's link is what its own create named and passed. Nothing carries over | CI | +| BR-14 | A session on a worker flow is created with no worker, by the create, by an action on a session id that doesn't exist, or by `fsdev run` without a `workerId` in `--seed-session` | Refused with 400, naming `workerId`. No session written | CI · VG leg b | +| BR-14a | Alice calls `findWorkerSession({ worker })`, or lists with `state: { workerId }` | Her sessions with that worker, most recent first for the helper; none if there are none. Never another user's. The helper matches on the key set (S5a): it returns only sessions that carry no criteria key it did not name, so plain talk never lands in a delegate, task or workstream session. The list filter is not narrowed | CI · VG leg b | +| BR-15 | A session is created with caller state for a server-written field | Refused with 400, naming the field. Nothing written. Naming the worker in the create's state is not this case: it is how a session is created (BR-10), and the create check confirms it | CI | +| BR-16 | A session is deleted and its id created again | The new session's worker is what its own create named and the check passed. Nothing carries over | CI | | BR-17 | Bob opens, reads or sends to a session of Alice's | Refused, as today (engine ownership) | Existing suite · VG leg b | | BR-18 | A task or a mailbox post opens a session for a worker | It names the worker at create, through the same check as BR-10 to BR-12, on the session's user. The worker comes from the dispatching flow's code, never the post's fields | CI | -| BR-18a | A coordinator's session records its delegates after create | Held in server-written session state: flow code writes it, a caller can't (BR-15), and the link beside it stays fixed. FIX-1791 consumes it. Its delivery opens each delegate's session through `ensureWorkerSession`, with the worker and FIX-1791's coordinator-conversation key named; it can't post to a fresh id and rely on the turn (BR-14) | CI, on a fixture flow | -| BR-19 | A linked worker is fired | The turn is refused, naming it as fired. The session stays readable | CI | -| BR-19a | A linked worker's flow is no longer registered | The turn is refused. The session reads as a session of any unregistered flow reads today: this issue adds no engine read path (ER-22) | CI | -| BR-19b | Alice edits a worker to name a different flow | The link holds. A turn on a session created before the edit is refused, naming both flows. New sessions are created on the new flow: `ensureWorkerSession` finds none there and creates one at a new id | CI | +| BR-18a | A coordinator's session records its delegates after create | Held in server-written session state: flow code writes it, a caller can't (BR-15), and the worker beside it stays fixed. FIX-1791 consumes it. Its delivery opens each delegate's session through `ensureWorkerSession`, with the worker and FIX-1791's coordinator-conversation key named; it can't post to a fresh id and rely on the turn (BR-14) | CI, on a fixture flow | +| BR-18b | A task, a mailbox post or a coordinator's delivery reaches a child session that already exists, asking for another value of one of its readonly fields, such as another worker | Refused, naming the field. Nothing is written and nothing runs in that session, which keeps its worker. The mailbox wake keys each member's conversation by worker as well as by mailbox, so two workers woken by one post never ask for one session | CI | +| BR-19 | A session's worker is fired | The turn is refused, naming it as fired. The session stays readable | CI | +| BR-19a | A session's worker's flow is no longer registered | The turn is refused. The session reads as a session of any unregistered flow reads today: this issue adds no engine read path (ER-22) | CI | +| BR-19b | Alice edits a worker to name a different flow | The session keeps its worker. A turn on a session created before the edit is refused, naming both flows. New sessions are created on the new flow: `ensureWorkerSession` finds none there and creates one at a new id | CI | | BR-19c | Alice forks a worker she already has sessions with | The fork is a new worker with no sessions. Those sessions stay with the original | CI | ## What a worker runs with | # | When | Then | Proved by | |---|---|---|---| -| BR-20 | Alice edits her worker | Her next turn on any session linked to it runs the edit. No restart | CI · two hosts | +| BR-20 | Alice edits her worker | Her next turn on any session of it runs the edit. No restart | CI · two hosts | | ~~BR-21~~ | A stored configuration from an older version loads | Removed by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9): nothing reads a configuration stored before this release | — | | BR-22 | A configuration names a tool, skill or package the installation no longer registers | That turn is refused, naming it. The row is untouched | CI | | BR-22a | A user's own worker names a flow that has since become kept for standard workers | That turn is refused with [FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) BR-15's sentence. The row is untouched: a flag flip must not lose a user's worker | CI | -| BR-23 | Two of Alice's workers on `agent` keep private notes | Each reads only its own. Same for every flow-isolated resource on every worker flow | CI · VG leg a | +| BR-23 | Two of Alice's workers on `agent` keep private notes | Each reads only its own. The same on every built-in worker flow | CI · VG leg a | +| BR-23a | Two of Alice's workers on a custom worker flow use data it keeps per user | Shared by both, and never another user's. Keeping it per worker is the flow's author's job; the docs show how ([D6](DECISIONS.md#d6)) | The docs example; FIX-1790 for another user | | BR-24 | A worker's file grants it one document, read-only | Its model reaches that document and no other, and can't write it, on every turn | CI · the grants goal, rewritten | | BR-25 | A worker reaches a resource another of Alice's workers wrote at user scope | Allowed: user scope is Alice's, shared by her workers (the concept's memory table) | CI | -| BR-25a | Two of Alice's workers on one flow write a shared resource | Each entry's `writtenBy` names Alice and, as `workerId`, the worker its session is linked to: two workers, two ids. The worker comes from the link, never the input ([FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) BR-20, D1) | CI | +| BR-25a | Two of Alice's workers on one flow write a shared resource | Each entry's `writtenBy` names Alice and, as `workerId`, her session's worker as the turn loaded it: two workers, two ids. The worker comes from the session, never the input or a setting ([FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) BR-20, D1) | CI | ## One copy per flow @@ -87,6 +89,6 @@ retries, and nothing is deleted except by a fire. ## Acceptance criteria this issue owns [The goal](SPEC.md#the-goal-and-how-well-know-its-met) passes on a scripted model with two users -and two hosts, after the same run fails under `org-scoped-workers` and `caller-link`. The epic's +and two hosts, after the same run fails under `org-scoped-workers` and `no-create-check`. The epic's early leg-c run ([ER-30](../../epics/FIX-1786/BUSINESS-RULES.md#the-closure)) then runs on the merge commit, in Shift Manager; that run is FIX-1797's. diff --git a/specs/issues/FIX-1788/DECISIONS.md b/specs/issues/FIX-1788/DECISIONS.md index 6329751821..f01b602032 100644 --- a/specs/issues/FIX-1788/DECISIONS.md +++ b/specs/issues/FIX-1788/DECISIONS.md @@ -4,8 +4,9 @@ What the model already decided is the epic's ([ER-1](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt), [D3](../../epics/FIX-1786/DECISIONS.md#d3)) and is not reopened here. These are the calls this -issue makes about forks and about where a session learns its worker. D1 and D2, on hires made -before this release, were withdrawn by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9). +issue makes about forks, about where a session learns its worker, and about how private a +custom worker flow is. D1 and D2, on hires made before this release, were withdrawn by +[epic D9](../../epics/FIX-1786/DECISIONS.md#d9). ## The tree @@ -15,10 +16,17 @@ flowchart TD D3 -.->|"rejected · an edit to the files changes your fork"| X3["a fork follows them"] I --> D4["D4 · a session's worker is named at create"] D4 -.->|"rejected · every message carries the worker"| X4["named on the first turn"] + D4 --> D5["D5 · named in a readonly field of the session's starting state"] + D5 -.->|"rejected · a second name for what state can carry"| X5["a separate server-only link"] + I --> D6["D6 · a custom worker flow's per-worker privacy is its author's"] + D6 -.->|"rejected · repeats FIX-1789's introspection holes"| X6["refuse at hire"] + D6 -.->|"rejected · an engine change beyond the epic's six"| X7["the engine partitions"] ``` -Solid edges are what was chosen. D3 is decided, and D4 is this amendment's ask. D1 and D2 were -signed, then withdrawn by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9), so the tree leaves them out. +Solid edges are what was chosen. D3 and D4 are decided. D5 and D6 were approved by the product +owner on 2026-10-07 and recorded after merge ([EVOLUTION.md](EVOLUTION.md#amendment-binding)). +D1 and D2 were signed, then withdrawn by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9), so the +tree leaves them out. ## D1 · Removed by epic D9 · old hires, their memory and their conversations moved by one operator step @@ -63,13 +71,18 @@ instructions change every week. Then forks stale at once, and the opt-in earns i Jake, on #2812's review (SPEC.md, the app example): the worker belongs to the session, not to a message. The epic records this as D3 change 3's session-record form (#2813). +*Amended after merge (2026-10-07):* where the session holds its worker is now [D5](#d5), a +readonly field of the session's starting state, not a server-only field beside it. The call +itself, named once at create, stands. The card as signed is at +[the commit before the amendment](https://github.com/fixpoint-labs/flow-state-dev/blob/fcfefd47ec0cbb04687e98b1844e97e0ef58ae73/specs/issues/FIX-1788/DECISIONS.md#d4). + | | | |---|---| -| **Instead of** | The worker flow linking the session on its first turn, from a `worker` field in that turn's input (this spec as merged in #2812) | -| **Because** | A session can't change its worker, so a message is the wrong place to name one. First-turn linking was an implementation convenience (create ran no flow code), and it leaked into every app call. At create, the server checks the worker once and nothing after it can touch the link | -| **Locks in** | The engine runs a flow-declared check on every path that writes a new session (S1), and Workforce declares it for every worker flow. No session on a worker flow exists without a worker. The client gains `worker` on `createSession` and on `listSessions`, and Workforce gains `findWorkerSession` and `ensureWorkerSession` | +| **Instead of** | The worker flow naming the session's worker on its first turn, from a `worker` field in that turn's input (this spec as merged in #2812) | +| **Because** | A session can't change its worker, so a message is the wrong place to name one. Naming it on the first turn was an implementation convenience (create ran no flow code), and it leaked into every app call. At create, the server checks the worker once, and nothing after it can change it | +| **Locks in** | The engine runs a flow-declared check on every path that writes a new session (S1), and Workforce declares it for every worker flow. No session on a worker flow exists without a worker. An app names the worker in the create's starting state and lists by it ([D5](#d5)), and Workforce gains `findWorkerSession` and `ensureWorkerSession` | -![D4: where a session learns its worker. At create, in a server-only field on the session record, chosen, beside on the first turn in server-owned state. Decides it: what carries the worker, the session once, so messages never name one. Price: an engine check on every way a session is made. Locks in a create check and worker on create and list; flips if an app must open a session before it knows its worker](figures/d4-link-at-create.svg) +![D4: where a session learns its worker. At create, named once, chosen, beside on the first turn in server-owned state. Decides it: what carries the worker, the session once, so messages never name one. Price: an engine check on every way a session is made. Locks in a create check and the worker named in the create's state; flips if an app must open a session before it knows its worker](figures/d4-named-at-create.svg) It comes down to what carries the worker: the session, once, at create, so messages never name one. @@ -77,12 +90,60 @@ It comes down to what carries the worker: the session, once, at create, so messa run it, such as a triage chat that hands off later. That is a new session per worker today, and would stay one. + +## D5 · A session holds its worker in a readonly field of its starting state; there is no separate link + +Approved by the product owner on 2026-10-07, who rejected a separate link concept, after P1 +([#2850](https://github.com/fixpoint-labs/flow-state-dev/pull/2850)) built the mechanism. Recorded +after merge. It replaces D4's mechanism and reverses the reasoning of the *considered and dropped* +row on plain session state. + +| | | +|---|---| +| **Instead of** | D4 as signed: a server-only field on the session record, outside its state, set from a `worker` option on `createSession` and filtered by one on `listSessions` | +| **Because** | A link is a second name for a value the session's state can already carry. D4 dropped plain state for three reasons, and each now has an answer in the engine. It was writable: a top-level `.readonly()` field is refused on any later change, on every path. It was set by the caller with nothing checking it: the create check sees the parsed state and the caller before anything is written. It wasn't listable: the listing filters on readonly fields inside the store's query. The engine stays generic: it knows readonly fields, not workers | +| **Locks in** | Every worker flow declares `workerId` readonly on its session `stateSchema`, with Workforce's create check. An app names the worker with `createSession({ state: { workerId } })` and lists by it with `listSessions({ state: { workerId } })`. `createWorkforceClient` keeps `worker` as its criteria key. `session.createCheck` stays optional: a flow declares one only for a rule that depends on the caller or the store, such as "this project is yours or shared with you". A flow that binds its sessions (a readonly field or a create check) refuses at create a starting state its schema rejects. Three engine changes beyond the epic's D3 item (3) as written ([EVOLUTION.md](EVOLUTION.md#amendment-binding)) | + +![D5: what binds a session to its worker, a readonly field of its starting state, chosen, beside a separate server-only link. Decides it: names to learn, one, session state, against two, state and a link. Tie: both are checked at create. Price: the engine gains a readonly guard, a store-level filter and a binding refusal. Locks in workerId readonly on every worker flow; flips if a binding must stay hidden from the flow's own code](figures/d5-readonly-starting-state.svg) + +It comes down to names: a link is a second place for a value state already holds. + +**What would change my mind:** a binding the flow's own blocks must not read. State is visible to +every block of the flow, and a server-only field is not. + + +## D6 · On a custom worker flow, keeping one user's workers apart is the flow's author's job + +Formerly Q6, asked on P2 ([#2856](https://github.com/fixpoint-labs/flow-state-dev/pull/2856)). +Answered A by the product owner on 2026-10-07. Recorded after merge. + +| | | +|---|---| +| **Instead of** | B: refuse at hire a custom worker flow that keeps data per user without keying it by worker · C: the engine keeps every flow-isolated resource on a worker flow apart per worker, by itself | +| **Because** | The risk stays inside one user. Two of Alice's workers on one custom flow can read what it stores for her; nothing reaches Bob, whose data is keyed apart ([FIX-1790](https://linear.app/fixpoint-labs/issue/FIX-1790)). The epic already says a custom worker flow's privacy is its author's, not a registration check ([epic SPEC](../../epics/FIX-1786/SPEC.md), [ER-2](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). B repeats [FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789)'s schema-introspection holes: a check that reads a flow's declarations can't see what its code writes. C is an engine change beyond the epic's six ([epic D3](../../epics/FIX-1786/DECISIONS.md#d3)) | +| **Locks in** | BR-23 covers the built-in worker flows: `agent`'s skills drawer is kept per worker from P4, through the skills library's per-run key (S7), which fails closed when a run names no worker. Data a custom worker flow keeps per user is shared by that user's workers on it, and never crosses users. The docs show an author how to keep it per worker ([DOCS.md](DOCS.md)) | + +![D6: on a custom worker flow, who keeps one user's workers apart. The flow's author, chosen, beside refusing at hire and the engine partitioning. Decides it: what it costs to build, a docs section, against a check with FIX-1789's holes, and an engine change beyond the epic's six. Price: two of one user's workers share what the flow stores, unless its author keys it. Tie: another user is never reached. Locks in BR-23 on the built-in flows; flips if one user's workers must never mix and authors won't key it themselves](figures/d6-custom-flow-privacy.svg) + +It comes down to cost: the other two each buy a check the epic already declined. + +**What would change my mind:** custom worker flows whose workers of one user must never see each +other, such as one worker per client of a consultant, built by authors who won't key it +themselves. Then B or C earns its cost. + ## Decided, not asked The mechanism lives in [PLAN.md](PLAN.md#surfaces) and is not restated here. S1 covers the one -session-birth function, the create check and the server-written state. S5 covers the link and -the derived id, and S5a the app helpers and racing calls. BR-10 to BR-19c rule the sessions. -What PLAN doesn't hold: +session-birth function, readonly fields, the create check and the server-written state. S5 +covers the worker's create check and the derived id, and S5a the app helpers and racing calls. +BR-10 to BR-19c rule the sessions. What PLAN doesn't hold: + +- **Only a flow that binds its sessions refuses a starting state its schema rejects.** A flow + binds them when it declares a readonly field or a create check. Every other flow keeps today's + create, which stores a failing starting state as sent. Refusing on every flow would break the + mailbox and the project rooms, which create half-filled sessions on purpose and fill them on + their first turn. Follow-up: widen the refusal to every flow once + [FIX-1792](https://linear.app/fixpoint-labs/issue/FIX-1792) removes the mailbox. - **Server-written session state ships here, not with FIX-1791.** Epic D3 *Locks in* (3) has FIX-1788 pick and build the mechanism and FIX-1791 consume it. The create must also refuse those @@ -105,11 +166,13 @@ What PLAN doesn't hold: | Alternative | Why not | |---|---| | Keep a copy per worker and narrow the pins | Keeps registration per process: a hire or fire waits for a restart elsewhere, and FIX-1798 can never remove pins | -| The link in plain session state, checked on read | A caller seeds a link to their own other worker through the session create ([epic POC](../../epics/FIX-1786/poc/singleton-worker-link/README.md), O1) | -| The link in a row only flow code writes, keyed by session id | Outlives a deleted session: a new session at the same id inherits it (POC, R1) | -| The link set by flow code on the first turn | Puts the worker in a message ([D4](#d4)) | +| The worker in plain session state, checked on read | A caller seeds their own other worker through the session create ([epic POC](../../epics/FIX-1786/poc/singleton-worker-link/README.md), O1). Still dropped as stated: [D5](#d5) keeps the worker in state, but checked at create and readonly after, which answers O1 | +| The worker in a row only flow code writes, keyed by session id | Outlives a deleted session: a new session at the same id inherits it (POC, R1). State lives on the session record and goes with it | +| The worker set by flow code on the first turn | Puts the worker in a message ([D4](#d4)) | +| A server-only field on the session record, beside its state | [D5](#d5): a second name for a value state can carry. It was D4's mechanism as signed | | A `getWorkerSession` helper returning a session-bound handle | Today's client already creates, lists and sends; two lookup helpers are all an app needs (Jake, #2812) | -| A worker noun in the engine | No consumer outside Workforce (epic [D3](../../epics/FIX-1786/DECISIONS.md#d3)); the client's `worker` maps onto a generic field | +| A worker noun in the engine | No consumer outside Workforce (epic [D3](../../epics/FIX-1786/DECISIONS.md#d3)); the worker is a readonly state field, which the engine knows only as readonly | +| On a custom worker flow, refuse at hire · or partition in the engine | [D6](#d6): the first repeats FIX-1789's introspection holes, the second is an engine change beyond the epic's six | ## Settled @@ -140,5 +203,10 @@ What PLAN doesn't hold: reload the view after every turn instead of naming written collections; S7's per-run key is a function the composing layer supplies, and the epic's D3 counts it; the Layer 1 guardrail names orchestration; BR-22a stands without BP-030. ([EVOLUTION.md](EVOLUTION.md#amendment-cross-spec)) +- **Amended after merge, binding through readonly state (2026-10-07)** — the product owner + rejected a separate link: a session holds its worker in a readonly field of its starting state, + checked at create ([D5](#d5)). The product owner answered Q6 as A: on a custom worker flow, + keeping one user's workers apart is its author's job ([D6](#d6)). P1 shipped three engine changes + beyond the epic's D3 item (3) as written. ([EVOLUTION.md](EVOLUTION.md#amendment-binding)) **Open:** none. diff --git a/specs/issues/FIX-1788/DOCS.md b/specs/issues/FIX-1788/DOCS.md index bf3d8ae668..2c83cb7aac 100644 --- a/specs/issues/FIX-1788/DOCS.md +++ b/specs/issues/FIX-1788/DOCS.md @@ -10,22 +10,18 @@ worker flow, user. | Shipped names | | |---|---| -| **Pinned** ([PLAN.md](PLAN.md#pinned-names)) | `worker` on `createSession` · `worker` on `listSessions` · the roster's `flow` · `createWorkforceClient` and its methods `findWorkerSession` and `ensureWorkerSession` · `workerFlows` (FIX-1789's) | -| **Drafts**, reconciled with the shipped code before publishing | `createCheck` and its `link` input · `serverOwned` · `createWorkerHireBlocks` · `fork` · the React hook `useWorkforce` · `useFlow`'s `worker` · `fsdev run --worker` | +| **Pinned** ([PLAN.md](PLAN.md#pinned-names)) | a worker flow's readonly `workerId`, set with `createSession({ state })` and listed with `listSessions({ state })` · the roster's `flow` · `createWorkforceClient` and its methods `findWorkerSession` and `ensureWorkerSession`, with the criteria key `worker` · `workerFlows` (FIX-1789's) | +| **Published with P1** ([#2850](https://github.com/fixpoint-labs/flow-state-dev/pull/2850)) | `session.createCheck` · `session.serverOwned` · readonly `stateSchema` fields · `listSessions({ state })` · `fsdev run --seed-session` on a flow that binds its sessions | +| **Drafts**, reconciled with the shipped code before publishing | `createWorkerHireBlocks` · `fork` · the React hook `useWorkforce` | -## UPDATE · `apps/docs/docs/configuration/flow.md` · the `session` table, two new rows after `client` +## Published with P1 · the session's starting state, readonly fields and the create check -> | `createCheck` | function | none | Runs before a session of this flow is written, on every path that creates one: the create request, an action sent to a session id that doesn't exist yet, and a transport that opens sessions. It receives the verified caller and the create's `link` input. It refuses the create, or returns a value stored on the session that nothing can change afterwards. A create with no `link` input is refused. | -> | `serverOwned` | `string[]` | none | Session-state fields only your flow's code writes. Creating a session with a value for one is refused with a 400 that names the field. Use it for state that decides what a session may do and changes as it runs. | - -## UPDATE · `apps/docs/docs/fundamentals/state-and-scopes.md` · "Creating sessions", a new last paragraph - -> A caller can pass initial `state` when it creates a session. That suits preferences and -> drafts, and it is the wrong place for a value that grants anything: the caller wrote it. A -> value fixed for the session's life, such as which worker it runs, belongs to `createCheck`, -> which checks it before the session exists. A value your flow changes as it runs belongs in a -> `serverOwned` field: the create refuses a value for it, and only a block in your flow can set -> it. +P1 ([#2850](https://github.com/fixpoint-labs/flow-state-dev/pull/2850)) published these, so they +are no longer drafts here: the `session` table in `apps/docs/docs/configuration/flow.md` +(`stateSchema`'s readonly fields, `createCheck`, `serverOwned`), "Creating sessions" and +"Example: one session per project" in `apps/docs/docs/fundamentals/state-and-scopes.md`, and the +`state` option and filter in `apps/docs/docs/api/client.md`. A worker flow is that example with a +worker in place of a project; the pages below link to it rather than repeat it. ## REPLACE · `apps/docs/docs/workforce/durable-hire.md` · the whole page @@ -89,8 +85,9 @@ Title *Hiring, forking and firing workers*, sidebar label *Hiring and forking*. > > Each worker the user hires or forks is one row in their user scope at `workforce/workers/`. > A standard worker isn't stored: it is read from your files each time, so a deploy that changes -> a file changes it for everyone. What a worker remembers is kept per worker, so two of one -> user's workers never read each other's notes. +> a file changes it for everyone. On the built-in `agent` flow, what a worker remembers is kept per +> worker, so two of one user's workers never read each other's notes. On a flow you write, that is +> up to you: see [Where a worker's data lives](./workers-on-disk.md#where-a-workers-data-lives). > > ## After a hire, refresh the roster > @@ -105,7 +102,8 @@ Title *Hiring, forking and firing workers*, sidebar label *Hiring and forking*. > > Each flow a worker names runs as one copy, shared by every worker that names it. A hundred > workers on `agent` are one registered flow, not a hundred. What makes them different is their -> configuration, which the flow reads on each turn, and their memory, which is kept per worker. +> configuration, which the flow reads on each turn, and, on `agent`, their memory, which is kept +> per worker. ## UPDATE · `apps/docs/docs/workforce/workers-on-disk.md` · a new section "Talking to a worker", before "What this does not do" @@ -140,14 +138,15 @@ Title *Hiring, forking and firing workers*, sidebar label *Hiring and forking*. > import { createSessionClient } from "@flow-state-dev/client" > > const sessions = createSessionClient({ baseUrl }) -> const mine = await sessions.listSessions({ flowKind: "agent", userId, worker: "researcher" }) -> const fresh = await sessions.createSession({ flowKind: "agent", userId, worker: "researcher" }) +> const mine = await sessions.listSessions({ flowKind: "agent", userId, state: { workerId: "researcher" } }) +> const fresh = await sessions.createSession({ flowKind: "agent", userId, state: { workerId: "researcher" } }) > ``` > > The server checks the worker when the session is created: it must be yours or a standard > one, and it must run on this flow. A worker that isn't yours is refused with the same answer -> as one that doesn't exist. A session created without a worker is refused. The link is stored -> where callers can't write it, and it never changes. +> as one that doesn't exist. A session created without a worker is refused. `workerId` is a +> readonly field of the session's state: nothing can change it after the create. It works the way +> a project does in [Example: one session per project](../fundamentals/state-and-scopes.md#example-one-session-per-project). > > **3. Talk to it.** An ordinary action on that session: > @@ -158,27 +157,60 @@ Title *Hiring, forking and firing workers*, sidebar label *Hiring and forking*. > await agent.sendAction("run", { message }, { sessionId: session.id }) > ``` > -> In React, `useWorkforce` gives you the same client, and `useFlow` takes the worker, so it lists -> and creates only that worker's sessions: +> In React, `useWorkforce` gives you the same client. `useFlow` creates sessions with no starting +> state, so a worker's flow refuses them: find or start the session with the client, then make it +> the hook's active session. > > ```tsx > const workforce = useWorkforce() -> const flow = useFlow({ flowKind: "agent", worker: "researcher", autoCreateSession: true }) +> const flow = useFlow({ flowKind: "agent" }) +> +> const session = await workforce.ensureWorkerSession({ worker: "researcher" }) +> flow.selectSession(session.id) > ``` > > Tasks and messages your other workers hand to this one open sessions the same way, naming the > worker when the session is created. +## UPDATE · `apps/docs/docs/workforce/workers-on-disk.md` · "Where a worker's data lives", a new last part + +> On one flow, a user's workers share that user's scope. The built-in `agent` keeps each worker's +> skills apart for you, with a skills library partitioned by worker. A worker flow you write doesn't: anything it keeps at user scope is shared +> by every one of that user's workers on the flow. It never reaches another user, whose data is +> kept apart. +> +> If each worker should keep its own, put the worker in the key. Load the worker at the start of +> the turn, then use its id: +> +> ```ts +> import { defineResourceCollection } from "@flow-state-dev/core" +> import { z } from "zod" +> +> // One row per worker, in the user's scope. +> const notes = defineResourceCollection({ +> pattern: "worker-notes/*", +> scope: "user", +> stateSchema: z.object({ text: z.string().default("") }), +> }) +> +> // inside your flow's block, which declares `resources: { notes, ...installation.resources }` +> const worker = await installation.resolveWorker(ctx, "research") +> await ctx.resources.notes.upsert(worker.id, { text: "Prefers short answers." }) +> ``` +> +> Use the id `resolveWorker` returns rather than reading the session's state yourself: it is the +> worker the session was created with, checked on this turn. For skills, give your skills library a +> `partitionBy` that returns the session's `workerId`. A run it returns nothing for gets an empty +> catalog it can't write to, so a session with no worker never reads every worker's skills. + ## UPDATE · `packages/workforce/README.md`, `packages/engine/README.md`, `packages/client/README.md` > **workforce:** A worker is a row in its owner's data, run by one shared copy of the flow it > names. `hire`, `fork` and `fire` write it. A session names its worker when it is created; > `createWorkforceClient(...).ensureWorkerSession` and `findWorkerSession` find or start one. > -> **engine:** `session.createCheck` checks a value at session create and stores it where nothing -> changes it; `session.serverOwned` names session-state fields the session create refuses. -> -> **client:** `createSession` takes `worker`, and `listSessions` filters by it. +> **engine** and **client** were documented with P1: readonly session-state fields, the optional +> `session.createCheck`, `session.serverOwned`, and `listSessions({ state })`. Nothing more here. ## Publication ownership diff --git a/specs/issues/FIX-1788/EVOLUTION.md b/specs/issues/FIX-1788/EVOLUTION.md index 6394613027..185a108daa 100644 --- a/specs/issues/FIX-1788/EVOLUTION.md +++ b/specs/issues/FIX-1788/EVOLUTION.md @@ -24,7 +24,9 @@ before implementing; FIX-1789 and FIX-1790 may have moved two of them first. Forward lineage: the criteria object of `findWorkerSession` and `ensureWorkerSession` (PLAN S5a) is extended later by FIX-1794 (`taskId`), FIX-1793 (`workstreamId`) and FIX-1791 (the coordinator conversation a delegate's session belongs to; FIX-1791 names the key). Each later key -is added to the same lookup path, not to a second helper. +is added to the same lookup path, not to a second helper. Since the binding amendment +([below](#amendment-binding)), each later key is a readonly field of the worker flow's session +state, because the listing filters on readonly fields only. Amended after merge (epic amendment #2831): the lookup matches on the key set, not only on values (S5a, BR-14a, V4). Without it, a narrower lookup returned a wider session: plain talk @@ -70,3 +72,56 @@ spec changed: | The guardrail "no Layer 1 change beyond S1" | **Amended**: S1 and S7's per-run key, with orchestration named as Layer 1 | Follows from S7 | — | | BR-22a's BP-030 citation | **Amended**: the rule gives its own reason | Epic D9: BP-030 doesn't apply to this epic | The rule: the row is untouched | | DOCS, "After a hire, refresh the roster" | **Amended** | Follows from BR-8 | — | + + +## Amended after merge: binding through readonly state, and privacy on a custom worker flow (2026-10-07) + +**The problem.** This spec said a session's worker sat in a server-only field on the session +record, beside its state, set from a `worker` option on `createSession` and filtered by one on +`listSessions`. P1 ([#2850](https://github.com/fixpoint-labs/flow-state-dev/pull/2850)) built a +different mechanism instead: the worker is a readonly field of the session's starting state, +checked at create. The product owner approved that on 2026-10-07 and rejected a separate link +concept. The same day, the product owner answered Q6, raised on P2 +([#2856](https://github.com/fixpoint-labs/flow-state-dev/pull/2856)), as A: on a custom worker +flow, keeping one user's workers apart is the flow's author's job. The spec still described the +link and promised per-worker privacy on every worker flow. Original review: +[#2812](https://github.com/fixpoint-labs/flow-state-dev/pull/2812), amended by +[#2818](https://github.com/fixpoint-labs/flow-state-dev/pull/2818). + +| What | Treatment | Why | What is retained | +|---|---|---|---| +| [D4](DECISIONS.md#d4)'s mechanism: a server-only field on the session record, a `worker` option on create and list, and a create check that returned the value the engine stored | **Superseded** by [D5](DECISIONS.md#d5) | The product owner rejected a separate link. A readonly field, the optional create check and the store-level filter answer each reason D4 gave for keeping the worker out of state: writable, set unchecked by the caller, not listable | D4's call, named once at create; its card as signed is linked from it, and its figure is renamed `d4-named-at-create.svg` | +| *Considered and dropped*: the worker in plain session state (O1) | **Kept as dropped, reasoning answered** | "Checked on read" is still wrong. Checked at create and readonly after is D5 | The R1 row: state is deleted with its record, so nothing outlives a deleted session | +| S1: a create field outside `state`, `useFlow` passing `worker`, `fsdev run --worker` | **Amended** to what P1 shipped | Readonly fields, an optional `createCheck`, `serverOwned`, a listing filter on readonly fields, a schema refusal on flows that bind their sessions, and a dispatcher's child `state`. `fsdev run` takes the worker through `--seed-session`; `useFlow` is unchanged | The one birth function on all five paths, the lost-race behaviour, `serverOwned` for FIX-1791 | +| The schema refusal at create | **Narrowed**, an engineering call | Refusing on every flow would break the mailbox and the project rooms, which create half-filled sessions on purpose | Follow-up: widen it to every flow once FIX-1792 removes the mailbox | +| BR-15: caller state for "the link or a server-written field" | **Narrowed** to server-written fields | Naming the worker in the create's state is how a session is created (BR-10) | The 400 naming the field | +| BR-23, S7 and V6: "every flow-isolated resource on every worker flow", "and on one app flow" | **Narrowed** by [D6](DECISIONS.md#d6) | The risk stays inside one user; B repeats FIX-1789's introspection holes; C is an engine change beyond the epic's six | BR-23 on the built-in worker flows, the skills library's per-run key, which fails closed for a run with no partition, and `agent`'s drawer, per worker from P4 (S7). New: BR-23a and a DOCS.md section showing an author how to key data by worker | +| The goal's `GOAL_CONTROL=caller-link` | **Replaced** by `no-create-check` | The old control read the worker from the create's state instead of a server-only field, and that field no longer exists. Removing the create check is what now lets Bob's create name Alice's worker | `org-scoped-workers`, unchanged. Renamed in FIX-1797's PLAN (P3.3) by the same amendment | +| Pinned names: `worker` on `createSession` and `listSessions`; `workerId` in a generic create field | **Removed** | No link | `workerId`, now a readonly session-state field; `createWorkforceClient` keeps `worker` as its criteria key | +| DOCS: the `flow.md` session rows and the "Creating sessions" paragraph, both with a `link` input; `useFlow`'s `worker`; `fsdev run --worker` | **Removed**; P1 published the real pages | They described the link | A pointer to the published pages; the React path now selects a session the client found | + +### Engine changes beyond the epic's D3 item (3) + +The epic's [D3](../../epics/FIX-1786/DECISIONS.md#d3) item (3) reads "a server-only field on the +session record, set and checked when the session is created". P1 shipped it as three engine +changes, which the product owner approved on 2026-10-07: + +- **A readonly guard on session state.** A top-level `.readonly()` field of a flow's session + `stateSchema` is refused on any change after create, on every path that writes session state: + a block, a tool, an action, and `fsdev run --seed-session` on an existing session. +- **A state filter on listing, inside the store.** `listSessions({ state })` and the route's + `?state.=` filter on readonly fields only, in the SQLite, Postgres, memory and filesystem + stores' own queries. Any other field is refused with 400. +- **A schema refusal at create, on flows that bind their sessions.** A flow with a readonly field + or a create check refuses a starting state its schema rejects. Other flows keep today's create. + +P4 carries the readonly guard onto one more path: a dispatch that reaches an existing child +session asking for another value of a readonly field is refused rather than adopted (BR-18b). +Today that adoption compares identity fields only, which is harmless while each worker has its +own copy and wrong once workers share one. + +Beside them, as planned under item (3): the optional `session.createCheck`, whose only store read +is one collection row at the creating caller's own scope; `session.serverOwned`; a dispatcher's +child `state`; and `ensureSessionRecord` taking the create request. The epic's D3 card text may +need a matching amendment. That is the epic's to make, and this amendment leaves +`specs/epics/FIX-1786/` untouched. diff --git a/specs/issues/FIX-1788/PLAN.md b/specs/issues/FIX-1788/PLAN.md index c10048c5df..99def16841 100644 --- a/specs/issues/FIX-1788/PLAN.md +++ b/specs/issues/FIX-1788/PLAN.md @@ -10,18 +10,18 @@ start only after FIX-1789 and FIX-1790 merge and FIX-1787's merge-first rows lan | ID | Package · role | Change | Rules | |---|---|---|---| -| S1 | `engine` + `core` + `client` + `react` · server-owned session data, at create | One declaration, two parts, behind **one session-birth function**. **Birth:** it owns the stale-state purge, the flow's create check and the insert-if-absent write. `handleCreateSession`, `ensureSessionRecord` and the dispatched-child writer become thin callers, so every `SessionRecord` insert goes through it by construction. There are five paths today: the create route, an action's write for a missing session id (`createExecutionContext`), the webhook session resolver, `fsdev run` (`packages/cli/src/commands/run.ts`, through the exported `ensureSessionRecord`), and a task dispatched to another flow (`engine/src/context/create-request-host.ts`, which writes the child record before the target's task entry runs, so it carries the worker from the dispatching flow's code into the birth). Each caller keeps its choice over a lost race: the route answers 409, and the action and dispatch paths adopt the winner's record without re-checking the loser's input, as intended. **A create field:** the check gets the verified principal and the create's input. It refuses, or returns a value the engine stores under a generic key on the record, outside `state`. No route writes the field afterwards. A birth with no input is refused. The async check runs on a miss only, never on a turn of an existing session. **Server-written state:** session-state fields the birth refuses from a caller (400, naming the field) and only flow code writes. They ship here because epic D3 *Locks in* (3) has FIX-1788 build the mechanism and FIX-1791 consume it, and the refusal must exist before any app can seed those fields. FIX-1791's delegates ([#2815](https://github.com/fixpoint-labs/flow-state-dev/pull/2815)) are the consumer; BR-18a and V4 drive it until FIX-1791's goal covers it. The list route filters on the create field. `fsdev run` takes `--worker ` for a new session on a worker flow, and refuses a new one without it; `--seed-session` refuses server-written fields. The client's `createSession` takes `worker` and `listSessions` a `worker` filter, mapped onto that field; `useFlow` passes `worker` to both. The engine knows no worker. Undeclared means today | BR-13 BR-14 BR-15 BR-16 BR-18a | +| S1 | `engine` + `core` + `client` · binding a session at create (shipped in P1, [#2850](https://github.com/fixpoint-labs/flow-state-dev/pull/2850)) | **One session-birth function** every `SessionRecord` insert goes through: the create route, an action's write for a missing session id (`createExecutionContext`), the webhook session resolver, `fsdev run`, and a task dispatched to another flow (`engine/src/context/create-request-host.ts`). It owns the stale-state purge, the checks below and the insert-if-absent write; it runs on a miss only, never on a turn of an existing session. Each caller keeps its choice over a lost race: the route answers 409, and the action and dispatch paths adopt the winner's record without re-checking the loser's input. **What a flow declares on `session`** ([D5](DECISIONS.md#d5)): *a readonly field*, a top-level `.readonly()` field of `stateSchema`, set from the create's starting `state` and refused on any later change by every path that writes session state (a block, a tool, an action, `fsdev run --seed-session` on an existing session); *`createCheck`*, optional, which gets the starting state as the schema parsed it, the verified caller and a read of one collection row at the caller's own scope, and accepts or refuses, for a rule that depends on the caller or the store; *`serverOwned`*, state fields a caller's create may not seed (400, naming the field) and only flow code writes. `serverOwned` ships here because epic D3 *Locks in* (3) has FIX-1788 build the mechanism and FIX-1791 consume it; FIX-1791's delegates ([#2815](https://github.com/fixpoint-labs/flow-state-dev/pull/2815)) are the consumer, and BR-18a and V4 drive it until FIX-1791's goal covers it. **A flow binds its sessions** when it declares a readonly field or a create check: its create refuses a starting state its schema rejects (400, naming the field). Every other flow keeps today's create, which stores a failing state as sent ([DECISIONS.md](DECISIONS.md#decided-not-asked)). **Listing:** `listSessions({ state })` and the route's `?state.=` filter on readonly fields only, by exact string match, inside the store's query; any other field is refused with 400. **Dispatch:** a dispatcher's `session: { key, state }` and a task dispatcher's `state` give a child session its starting state, from the dispatching flow's code. `fsdev run` names the worker through `--seed-session`, and a new session on a binding flow without it is refused. `useFlow` is unchanged: it sends no starting state, so on a binding flow an app creates the session through the client and selects it. The engine knows no worker. Undeclared means today | BR-13 BR-14 BR-15 BR-16 BR-18a | | ~~S2~~ | `core` + `engine` · collection cardinality, `register(flow, { pin })` | Removed by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9): no deprecation markers. Both stay untouched until FIX-1798 deletes them | — | | S3 | `workforce` · the worker collection | User scope (per org, FIX-1790), one row per worker: `flow`, `description`, the configuration as names (ER-2), flow-owned settings. Checked by the flow's schema and FIX-1789's standard-only flag when saved | BR-1 BR-4–6a | | S4 | `workforce` · standard workers | A read-only collection projected from the loaded files, the same for every user; no write path | BR-3 BR-9 | -| S5 | `workforce` · the link, one module | The create check every worker flow declares through S1: a worker is named; it is the principal's own (read at their scope) or a standard one; it names this flow; a derived worker-session id is the caller's. It returns `workerId`, the value Workforce stores in S1's generic key. The id derivation is one exported function, used by both this check and `ensureWorkerSession`, and it runs on the tenant-resolved key. The task entry and the mailbox wake open sessions through it, naming the worker from the dispatching flow's code. No turn sets or changes a link. **S5 and S6 are one module**, with one interface: `resolveWorker` returns the worker plus its resolved configuration, beside the create check. The PR stack is the same | BR-10–14 BR-13b BR-18 | -| S5a | `workforce` · `createWorkforceClient`, with `findWorkerSession` and `ensureWorkerSession` | A bound client: `createWorkforceClient({ userId, baseUrl?, apiPath?, fetcher? })`, the same transport options as `createSessionClient`, with the two helpers as its methods. React gets them from a hook over the same client. No ambient state and no new endpoint: the methods use the roster read and the session client. One lookup path over `listSessions({ …, worker })`, taking one criteria object. FIX-1788 ships `worker`; leave the object open for later keys and define none: FIX-1794's `taskId`, FIX-1793's `workstreamId`, and FIX-1791's key for the coordinator conversation a delegate's session belongs to (FIX-1791 names it), so `ensureWorkerSession({ worker, })` gives one delegate session per coordinator conversation. A coordinator's delivery opens the delegate's session through `ensureWorkerSession` with the worker named: an action on a missing id names no worker and is refused (BR-14). Both resolve the worker's current flow from the roster first. The lookup and the derived id both include that resolved flow, not just the criteria. `find` returns the caller's most recent matching session on that flow, or none. **A match is on the key set, not only on values:** a criteria key the lookup does not name matches only sessions that do not carry that key, so `{ worker }` never returns a delegate, task or workstream session, and `{ worker, }` never returns a task session. Every later key inherits this rule; no consumer restates it (epic amendment #2831). `ensure` returns what `find` returns, so with several matching sessions it is the most recent, not necessarily the derived one. Only when there is none does it create, on that flow, at an id derived (S5's function) from the caller's user, org, resolved flow and criteria. So after BR-19b's edit, `ensure` finds nothing on the new flow and creates a fresh session at a new id, and the old sessions keep refusing. It creates through the create route, which owns the 409 contract: a 409 means a racing call won, so it reads that id and returns it (the store's own create guarantee: SQLite, Postgres, one filesystem store instance) | BR-13a BR-14a BR-19b | -| S6 | `workforce` · per-turn configuration | Load the linked worker each turn; resolve tool, skill, package, capability and worker-folder names against what the installation registers; refuse a turn whose worker is fired, now names another flow, has names that don't resolve, or runs on a flow now standard-only. Every read of a worker setting moves off `ctx.flow.config` to it | BR-19–22a | -| S7 | `orchestration` + `workforce` · private state by worker | The skills library takes its key per run: a function of the running context that the composing layer supplies, the shape of epic D6's partition, naming no worker. Workforce supplies the worker. Every flow-isolated resource on a worker flow is keyed by the worker. The `agent` drawer first. The library's half is a Layer 1 mechanism change, the sixth the epic's D3 counts | BR-23 BR-25 | +| S5 | `workforce` · the worker's create check, one module | Every worker flow declares a readonly `workerId` on its session `stateSchema` and this create check through S1: a worker is named; it is the principal's own (read at their scope) or a standard one; it names this flow; a derived worker-session id is the caller's. It accepts or refuses; the worker is the session's `workerId`. The id derivation is one exported function, used by both this check and `ensureWorkerSession`, and it runs on the tenant-resolved key. The task entry and the mailbox wake open sessions through it, naming the worker in the child's starting state from the dispatching flow's code. No turn changes `workerId`: S1's readonly guard refuses it. **S5 and S6 are one module**, with one interface: `resolveWorker` returns the worker plus its resolved configuration, beside the create check. The PR stack is the same | BR-10–14 BR-13b BR-18 | +| S5a | `workforce` · `createWorkforceClient`, with `findWorkerSession` and `ensureWorkerSession` | A bound client: `createWorkforceClient({ userId, baseUrl?, apiPath?, fetcher? })`, the same transport options as `createSessionClient`, with the two helpers as its methods. React gets them from a hook over the same client. No ambient state and no new endpoint: the methods use the roster read and the session client. One lookup path over `listSessions({ …, state: { workerId } })`, taking one criteria object. Each criteria key maps to a readonly session-state field of the worker flow, since only readonly fields are listable (S1). FIX-1788 ships `worker`; leave the object open for later keys and define none: FIX-1794's `taskId`, FIX-1793's `workstreamId`, and FIX-1791's key for the coordinator conversation a delegate's session belongs to (FIX-1791 names it), so `ensureWorkerSession({ worker, })` gives one delegate session per coordinator conversation. A coordinator's delivery opens the delegate's session through `ensureWorkerSession` with the worker named: an action on a missing id names no worker and is refused (BR-14). Both resolve the worker's current flow from the roster first. The lookup and the derived id both include that resolved flow, not just the criteria. `find` returns the caller's most recent matching session on that flow, or none. **A match is on the key set, not only on values:** a criteria key the lookup does not name matches only sessions that do not carry that key, so `{ worker }` never returns a delegate, task or workstream session, and `{ worker, }` never returns a task session. Every later key inherits this rule; no consumer restates it (epic amendment #2831). `ensure` returns what `find` returns, so with several matching sessions it is the most recent, not necessarily the derived one. Only when there is none does it create, on that flow, at an id derived (S5's function) from the caller's user, org, resolved flow and criteria. So after BR-19b's edit, `ensure` finds nothing on the new flow and creates a fresh session at a new id, and the old sessions keep refusing. It creates through the create route, which owns the 409 contract: a 409 means a racing call won, so it reads that id and returns it (the store's own create guarantee: SQLite, Postgres, one filesystem store instance) | BR-13a BR-14a BR-19b | +| S6 | `workforce` · per-turn configuration | Load the session's worker each turn; resolve tool, skill, package, capability and worker-folder names against what the installation registers; refuse a turn whose worker is fired, now names another flow, has names that don't resolve, or runs on a flow now standard-only. Every read of a worker setting moves off `ctx.flow.config` to it | BR-19–22a | +| S7 | `orchestration` + `workforce` · private state by worker, on the built-in worker flows | The skills library takes its key per run: a function of the running context that the composing layer supplies, the shape of epic D6's partition, naming no worker. A run its function names no partition for reads an empty catalog and can't write to it: the library fails closed rather than read every partition at once (shipped in P2). Workforce supplies the worker from the installation's session, and `agent`'s skills drawer is kept per worker through it in P4, when `agent` declares that session; until then each worker's copy keeps its own drawer, as today. The library's half is a Layer 1 mechanism change, the sixth the epic's D3 counts. Data a custom worker flow keeps per user is shared by that user's workers on it; keeping it per worker is the flow's author's job, and DOCS.md shows how ([D6](DECISIONS.md#d6)) | BR-23 BR-23a BR-25 | | S8 | `workforce` · grants per turn | A worker's document grants and reference wall narrow what its model reaches on each turn: tools and context. Replaces the per-copy narrowed resource map | BR-24 | | S9 | `workforce` · hire, fork, fire | Writes to S3, through the hire blocks and tool; fork is new beside them and copies per D3. The hire blocks take `workerFlows` (FIX-1789) and, since they change here, take a worker name (the docs draft `createWorkerHireBlocks`; not pinned). A view reloads after each turn (BR-8) | BR-1 BR-2 BR-4 BR-7 BR-8 BR-19c | | S10 | `workforce` · registration | The hire registers one copy per flow, `agent` and every flow handed to it, with no per-worker copy and no pin. The `agent` flow becomes a singleton and registers on the installation's `workerFlows` list (epic Q1) | BR-26 | -| S11 | `workforce` · consumers | Worker lookup, task hand-off and the mailbox wake open sessions naming (flow, worker) at create, through S5. The shared-write stamp's `writtenBy.workerId` (FIX-1789 BR-20) comes from the link. The org-wide worker inventory stops listing hired workers | BR-18 BR-25a | +| S11 | `workforce` · consumers | Worker lookup, task hand-off and the mailbox wake open sessions on the worker's flow, naming the worker in the child's starting state, checked by S5. The engine refuses to adopt an existing child whose readonly fields differ from the `state` the dispatch asks for (BR-18b), and the mailbox wake keys its child by worker as well as by mailbox. The shared-write stamp's `writtenBy.workerId` (FIX-1789 BR-20) comes from the worker the turn loaded, never from state a caller wrote. The org-wide worker inventory stops listing hired workers | BR-18 BR-18b BR-25a | | S12 | `shift-manager` · Roster and talk | Lists S3 and S4 for the signed-in user, each with its `flow`; opens sessions with `ensureWorkerSession`; reloads on BR-8 | BR-9 | | ~~S13~~ | `workforce` · the upgrade step | Removed by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9): no operator command. Old hires, their cells and their sessions are dropped | — | | S14 | `workforce` · **removals** | The boot reload of hired workers, per-worker minting, `registerHiredSeat`, every owner pin Workforce sets, `brokenSeats`/`rehire` (a broken worker now refuses at load, BR-19 BR-22), and the old roster collections: nothing reads their rows ([epic D9](../../epics/FIX-1786/DECISIONS.md#d9)) | — | @@ -39,7 +39,7 @@ start only after FIX-1789 and FIX-1790 merge and FIX-1787's merge-first rows lan ```mermaid flowchart TD - S1["S1 · server-owned data at create"] --> S5["S5 · the link"] + S1["S1 · binding at create"] --> S5["S5 · the worker's create check"] S3["S3 · worker rows"] --> S5 S4["S4 · standard projection"] --> S5 S5 --> S5a["S5a · find and ensure"] @@ -66,46 +66,45 @@ Nothing existing changes shape until P4. P4 drops the hires made before it: noth | ID | Runs after | Passes when | |---|---|---| | V0 | before P4 | Rerun [`poc/flow-inventory/`](poc/flow-inventory/README.md) and list every flow handed to a `hireWorkforce` call (kitchen-sink, Shift Manager labs, `goals/*`). Each is in the PR as converted, or a refusal fixture that stays one | -| V1 | S1 | BR-15, BR-16; the create check runs, through the one birth function, on the create route, an action's write for a missing session id, the webhook resolver, `fsdev run` (with `--worker`, and refused without it on a worker flow) and a task dispatched to a worker flow (the child is born linked to the named worker), and each refuses with no input; a grep for `session.set(…, "absent")` on session records finds no writer outside the birth function; a turn on an existing session makes no check call; a lost race answers 409 on the route and adopts on the action path; no route (state patch, metadata patch, action) writes the create field after create; flow code writes server-written state; the list filters on the create field; a flow that declares none behaves as today | +| V1 | S1 | BR-15, BR-16; through the one birth function, the binding schema and the create check run on the create route, an action's write for a missing session id, the webhook resolver, `fsdev run` (with `--seed-session`, and refused without it on a binding flow) and a task dispatched to another flow (the child is born with the state its dispatcher names), and each refuses a starting state the schema rejects on a binding flow; a flow that binds nothing keeps a failing state as sent; a grep for `session.set(…, "absent")` on session records finds no writer outside the birth function; a turn on an existing session makes no check call; a lost race answers 409 on the route and adopts on the action path; a change to a readonly field is refused from a block, a tool, an action and `fsdev run --seed-session`; flow code writes `serverOwned` state and a caller's create can't; the list filters on readonly fields inside the store's query and refuses any other field; a flow that declares none behaves as today | | ~~V2~~ | ~~S2~~ | Removed by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9), with S2 | | V3 | S3 S4 | BR-1, BR-3–6a (BR-6 on a standard-only flow too), BR-9 on the real engine; BR-5 with two users | -| V4 | S5 S5a | BR-10–14a through `createSession` and the helpers; BR-13a with two `ensureWorkerSession` calls in flight at once; BR-13b with Bob creating at Alice's derived id first; BR-16 through the helper: delete the derived session, `ensureWorkerSession` again, and the new session's link is set fresh by its own create, nothing inherited; BR-19b through the helper: edit the worker to another flow, `ensureWorkerSession` returns a new session on the new flow at a new id, and the old session still refuses; BR-18 through the task entry, a task dispatched to a worker flow (the child is born linked) and the mailbox wake; BR-18a on a fixture coordinator flow; BR-14a's key-set match: with a more recent session of that worker carrying an extra fixture criteria key, `ensureWorkerSession({ worker })` (S12's plain talk) still returns the plain session, and with a more recent session carrying two fixture keys, a lookup naming only one of them returns the session carrying exactly that one (the strict-subset case: a coordinator's `{ worker, filingSessionId }` never lands in a task session; *amended after merge*, #2839) | +| V4 | S5 S5a | BR-10–14a through `createSession({ state: { workerId } })` and the helpers; BR-13a with two `ensureWorkerSession` calls in flight at once; BR-13b with Bob creating at Alice's derived id first; BR-16 through the helper: delete the derived session, `ensureWorkerSession` again, and the new session's worker is what its own create named, nothing inherited; BR-19b through the helper: edit the worker to another flow, `ensureWorkerSession` returns a new session on the new flow at a new id, and the old session still refuses; BR-18 through the task entry, a task dispatched to a worker flow (the child is born naming the worker) and the mailbox wake; BR-18b: a dispatch reaching an existing child with another `workerId` is refused and writes nothing, and one mailbox post waking two workers on one `agent` copy opens two sessions; BR-18a on a fixture coordinator flow; BR-14a's key-set match: with a more recent session of that worker carrying an extra fixture criteria key, `ensureWorkerSession({ worker })` (S12's plain talk) still returns the plain session, and with a more recent session carrying two fixture keys, a lookup naming only one of them returns the session carrying exactly that one (the strict-subset case: a coordinator's `{ worker, filingSessionId }` never lands in a task session; *amended after merge*, #2839) | | V5 | S6 | BR-19–19b; BR-20, BR-22 and BR-22a (a flag flipped after the row was saved) across two hosts on one store | -| V6 | S7 S11 | BR-23 on `agent` and on one app flow; BR-25; BR-25a, two workers on one flow stamping two ids | +| V6 | S7 S11 | BR-23 on `agent`; BR-25; BR-25a, two workers on one flow stamping two ids | | V7 | S8 | BR-24: `goals/workforce-seats/a-seat-reaches-the-documents-its-file-names/` rewritten to grade what the model reaches | | V8 | S9 | BR-2 (a fork keeps its copy after the file changes, D3), BR-7 across two hosts, BR-8, BR-19c | | V9 | S10 | BR-26: the registry holds one entry per flow, none per worker, no pin set by Workforce | | ~~V10~~ | ~~S13~~ | Removed by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9), with S13 | -| VG | P4 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met): `goals/workers-as-resources/keeps-each-users-workers-their-own/run.mts` PASSES, after the same run FAILED leg b under `GOAL_CONTROL=org-scoped-workers` and `GOAL_CONTROL=caller-link`, and legs a and b on today's `main` | +| VG | P4 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met): `goals/workers-as-resources/keeps-each-users-workers-their-own/run.mts` PASSES, after the same run FAILED leg b under `GOAL_CONTROL=org-scoped-workers` and `GOAL_CONTROL=no-create-check`, and legs a and b on today's `main` | -One check per decision: D3 by V8, D4 by V1 and V4. The second path (BP-035): a second host (V5, +One check per decision: D3 by V8, D4 and D5 by V1 and V4, D6 by V6 (BR-23 on `agent`) and the DOCS.md example. The second path (BP-035): a second host (V5, V8), the off state of S1 (V1), racing creates (V4), a fired, moved or broken worker (V5). ## Pinned names | Where | Name | Why pinned | |---|---|---| -| Session create | `worker`, an option on `createSessionClient().createSession` | Public; an app sends it | -| Session list | `worker`, a filter on `createSessionClient().listSessions` | Public | +| A worker flow's session | `workerId`, a readonly field of its session `stateSchema`, set with `createSession({ state: { workerId } })` and listed with `listSessions({ state: { workerId } })` | Public and persisted; an app sends it, and FIX-1789's `writtenBy.workerId` names the same worker | +| The engine's binding (shipped in P1) | `session.createCheck`, `session.serverOwned`, a `.readonly()` field of `session.stateSchema`, and `listSessions({ state })` | Public | | The roster read | each worker's `flow` | Public; an app creates the session on it | -| Workforce | `createWorkforceClient(options)` and its methods `findWorkerSession(criteria)`, `ensureWorkerSession(criteria)` | Public; FIX-1794, FIX-1793 and FIX-1791 add criteria keys, each pinned by its own issue | +| Workforce | `createWorkforceClient(options)` and its methods `findWorkerSession(criteria)`, `ensureWorkerSession(criteria)`; the criteria's `worker` key | Public; FIX-1794, FIX-1793 and FIX-1791 add criteria keys, each pinned by its own issue | | The worker collection | `workforce/workers/*`, user scope | Persisted; FIX-1791 and FIX-1795 read and write it | -| The session's link | `workerId`, the value Workforce stores in the record's generic server-only create field (the engine's key is yours to name) | Persisted; FIX-1789's `writtenBy.workerId` reads it | Everything else is yours to name, in the new terms (worker, worker flow, user; not seat, kind or -person). The engine container for the create field and the create check's name are yours. +person). ## Guardrails | Rule | Because | |---|---| | Every `SessionRecord` insert goes through S1's one birth function, which runs S5's check; V1's grep finds no other `"absent"` writer | A check wired per call site is open at the next path someone adds, as `fsdev run` and the dispatched-child writer already are (tenet 5) | -| No action input names a worker; no route but create writes the link | The worker belongs to the session ([D4](DECISIONS.md#d4)) | -| Access is read at the principal's own scope, never from the link or the input (ER-17, BP-031) | That is why pins aren't needed: a forged link reads nothing | +| No action input names a worker; nothing changes `workerId` after create | The worker belongs to the session ([D4](DECISIONS.md#d4), [D5](DECISIONS.md#d5)) | +| Access is read at the principal's own scope, never trusted from `workerId` or the input (ER-17, BP-031) | That is why pins aren't needed: naming a worker that isn't yours reads nothing | | No worker setting is read from `ctx.flow.config` (ER-2) | The shared copy holds one bag for every worker | | The worker collection is the one worker store; standard workers project the loaded files (ER-14) | A second registry is the drift the WorkerConfig lock forbids | | No worker read without an org; the user key is FIX-1790's (ER-13) | A user in two orgs has two rosters | -| No Layer 1 change beyond S1 and S7's per-run key in orchestration's skills library, both counted by the epic's D3 (ER-22). Orchestration is Layer 1, as `core` and `engine` are | If S7 needs more, or S8 needs one, stop and take it to the epic | +| No Layer 1 change beyond S1 as shipped, S11's adoption refusal and S7's per-run key in orchestration's skills library, all counted by the epic's D3 (ER-22). S1 shipped three engine changes beyond D3 item (3)'s wording, approved by the product owner; the adoption refusal carries S1's readonly guard onto the dispatch path ([EVOLUTION.md](EVOLUTION.md#amendment-binding)). Orchestration is Layer 1, as `core` and `engine` are | If S7 needs more, or S8 needs one, stop and take it to the epic | | Rename only the hire blocks this issue changes; FIX-1789 renames `kinds` to `workerFlows` | FIX-1796 sweeps the other `seat*` names with the docs | ## Docs @@ -116,13 +115,15 @@ refusal wording. ## Sketch · pseudocode, illustrative, react to the shape ``` -birth(record, input), the one function every new record goes through; misses only: - name ← the create's worker (createSession / ensureWorkerSession / fsdev run --worker) or the dispatcher's (task, dispatched child, mailbox) - refuse if no name ← no session without a worker - w ← read name at the principal's scope, else the standard projection ← the whole check - refuse unless w, w.flow = this flow - refuse if the id is a derived worker-session id that isn't this caller's - purge stale state; write the record insert-if-absent, workerId under the generic key ← once +birth(record, request), the one function every new record goes through; misses only: + state ← the create's starting state (createSession / ensureWorkerSession / fsdev run --seed-session) or the dispatcher's (task, dispatched child, mailbox) + refuse if a caller's state seeds a serverOwned field + state ← parse through stateSchema; on a binding flow, refuse if it fails ← no session without a worker + createCheck(state, principal), Workforce's: ← the whole check + w ← read state.workerId at the principal's scope, else the standard projection + refuse unless w, w.flow = this flow + refuse if the id is a derived worker-session id that isn't this caller's + purge stale state; write the record insert-if-absent, with the parsed state ← once on a lost race: the route answers 409, the action path adopts the winner workforce.ensureWorkerSession(criteria): ← workforce = createWorkforceClient({ userId, baseUrl }) @@ -131,8 +132,8 @@ workforce.ensureWorkerSession(criteria): ← workforce = createWorkforc create via the route at derive(user, org, flow, criteria); on 409 return the session at that id on every turn: - refuse if the input carries worker - w ← load the linked worker; refuse if fired, if w.flow ≠ this flow, or if its names don't resolve + refuse if the input carries worker; refuse any write that changes workerId (S1's readonly guard) + w ← load the session's worker; refuse if fired, if w.flow ≠ this flow, or if its names don't resolve run the turn with w's configuration, private state keyed by w ``` @@ -152,6 +153,14 @@ flows over 94 files, PASS, the control failing. No new premise needed a POC. - FIX-1789 S6 may have moved the `agent` drawer to user scope; S7 keys it by worker on top. - S7: if the skills library can't take a per-run key without a `core` or `engine` change, stop and take it to the epic. The same for S8. +- S11, before P4 moves `agent` onto one copy: today a dispatch whose derived child already exists + adopts it without comparing the starting state it asked for (`evaluateAdoption` in + `engine/src/context/dispatch-run.ts` compares identity fields only), and the wake keys a member's + conversation by mailbox alone. On one `agent` copy, two workers would share one child and the + second would run as the first. P4 does both: the engine refuses to adopt an existing child whose + readonly fields differ from the requested `state`, naming the field (BR-18b), and the wake keys + its child by worker too. Found while writing the binding amendment; not reproduced on today's + copies, where each worker's flow differs. - The real `agent` flow reads `ctx.flow.config` at 16 code sites on `fbecfe6f2` (`grep -n "ctx\.flow\.config" packages/workforce/src/agent-worker-flow.ts`, less one comment); S6 reaches each, and the other worker flows' reads too. - Old-term exports left for FIX-1796: `hireWorkforce`, `seatDoorOf`, `SeatDoor`, `createSeatHireCapability`, the `seat*` keys of `workerConfigSchema()`. `HIRED_ROSTER_*` goes @@ -176,3 +185,5 @@ Recorded verbatim for the implementer to weigh against real code; not folded int - FIX-1794 adds `taskId`, FIX-1793 adds `workstreamId`, and FIX-1791 adds and names its filing session's key (`filingSessionId`, amended by #2839) to the helpers' criteria (S5a). - FIX-1791 writes a coordinator's delegates into S1's server-written state (BR-18a). +- Widen S1's create-time schema refusal to every flow once FIX-1792 removes the mailbox + ([DECISIONS.md](DECISIONS.md#decided-not-asked)). diff --git a/specs/issues/FIX-1788/SPEC.md b/specs/issues/FIX-1788/SPEC.md index 426fa6169f..b1a53c5cfa 100644 --- a/specs/issues/FIX-1788/SPEC.md +++ b/specs/issues/FIX-1788/SPEC.md @@ -6,11 +6,11 @@ | Someone who… | Today | After | |---|---|---| -| **shares an org with other users** | A worker hired for the org alone is reachable by every member, and any of them can open a session on it | Every worker belongs to one user. Nobody else can open its sessions, read it, run it or link a session to it | +| **shares an org with other users** | A worker hired for the org alone is reachable by every member, and any of them can open a session on it | Every worker belongs to one user. Nobody else can open its sessions, read it, run it or create a session with it | | **hires or fires a worker while the app runs** | The hire registers a new copy of a flow in this process. Other processes see the hire, or keep answering for a fired worker, until they restart | A hire, fork or fire is a write to the owner's data. Every process sees it on the next turn | | **wants their own version of a standard worker** | Edits its `WORKER.md` and restarts, or hires an org-wide copy | Forks it: a worker of their own with a copy of its configuration. Nobody changes a standard worker at run time | -| **builds an app that talks to a worker** | Sends to the worker's own copy, at an address that carries its org and owner (`acme.~alice.researcher`) | Finds or starts a session with the worker. The server checks the worker and links it when the session is created. Messages go to the flow the worker names (`agent`) and never name a worker | -| **runs several workers on one flow** | Each copy keeps its own private memory | Each worker still keeps its own, on the one shared copy | +| **builds an app that talks to a worker** | Sends to the worker's own copy, at an address that carries its org and owner (`acme.~alice.researcher`) | Finds or starts a session with the worker, named once in the session's starting state. The server checks it when the session is created, and nothing changes it after. Messages go to the flow the worker names (`agent`) and never name a worker | +| **runs several workers on one flow** | Each copy keeps its own private memory | On a built-in worker flow such as `agent`, each worker still keeps its own, on the one shared copy. On a custom worker flow, the flow's author decides ([D6](DECISIONS.md#d6)) | | **hired workers before this release** | Each hire is its own registered copy, with its memory and conversations | Dropped: nothing reads an old hire, its memory or its conversations ([epic D9](../../epics/FIX-1786/DECISIONS.md#d9)) | This is the epic's spine ([FIX-1786](../../epics/FIX-1786/SPEC.md), ER-1): privacy by @@ -19,16 +19,17 @@ private. ## The goal, and how we'll know it's met -**In one org, each user's workers are theirs alone: another user can't open, read, run or link -a session to them. Every worker runs on one shared copy of the flow it names, with its own -memory. A user hires or forks a worker without a restart and can't change a standard one.** +**In one org, each user's workers are theirs alone: another user can't open, read, run or create +a session with them. Every worker runs on one shared copy of the flow it names, with its own +memory on the built-in worker flows. A user hires or forks a worker without a restart and can't +change a standard one.** | Is it the right goal? | | |---|---| -| **The real need** | The [PRD](https://linear.app/fixpoint-labs/issue/FIX-1788): a worker is a configuration plus an owner, run by one copy of the flow it names; the server sets a session's link; standard workers come from files and are forked, not changed. The epic's [security model](../../epics/FIX-1786/concept/CONCEPT.md#the-security-model), rules 2 to 4 | -| **Smaller, and rejected** | "Bob can't reach Alice's worker." Met by narrowing today's pins, while each hire still registers a copy per process and a fire waits for a restart. Or "workers are rows": met while a caller seeds its session's link, which the [epic POC](../../epics/FIX-1786/poc/singleton-worker-link/README.md) (O1) showed it can | +| **The real need** | The [PRD](https://linear.app/fixpoint-labs/issue/FIX-1788): a worker is a configuration plus an owner, run by one copy of the flow it names; the server checks which worker a session runs; standard workers come from files and are forked, not changed. The epic's [security model](../../epics/FIX-1786/concept/CONCEPT.md#the-security-model), rules 2 to 4 | +| **Smaller, and rejected** | "Bob can't reach Alice's worker." Met by narrowing today's pins, while each hire still registers a copy per process and a fire waits for a restart. Or "workers are rows": met while a caller seeds its session's worker with nothing checking it, which the [epic POC](../../epics/FIX-1786/poc/singleton-worker-link/README.md) (O1) showed it can | | **Bigger, and not this issue's** | Which flows can run workers ([FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789)) · user data per org ([FIX-1790](https://linear.app/fixpoint-labs/issue/FIX-1790)) · coordinators ([FIX-1791](https://linear.app/fixpoint-labs/issue/FIX-1791)) · the library ([FIX-1795](https://linear.app/fixpoint-labs/issue/FIX-1795)) · removing instances and pins ([FIX-1798](https://linear.app/fixpoint-labs/issue/FIX-1798)) | -| **Not done if** | The check ran with one user · only on `agent` · a session can exist without a worker · a session's link can be seeded, changed, or set to a worker on another flow · two racing `ensureWorkerSession` calls make two sessions · two of Alice's workers share a memory cell · a second process needed a restart to see a hire · Workforce still registers a copy per worker or sets a pin | +| **Not done if** | The check ran with one user · only on `agent` · a session can exist without a worker · a session's worker can be changed after create, or set to another user's worker or to one on another flow · two racing `ensureWorkerSession` calls make two sessions · two of Alice's workers on `agent` share a memory cell · a second process needed a restart to see a hire · Workforce still registers a copy per worker or sets a pin | ```mermaid flowchart LR @@ -41,15 +42,15 @@ flowchart LR ``` The check reads what each caller gets back over HTTP and what the registry holds, never the -link's value. Under the dashed control, Bob must read Alice's worker. +session's stored `workerId`. Under the dashed control, Bob must read Alice's worker. | How we verify | | |---|---| | **Goal check** | `goals/workers-as-resources/keeps-each-users-workers-their-own/` · model n/a, a scripted model (access is under test, not answers) · real HTTP router, SQLite, two hosts on one store · run by the implementer at completion · verdict in the last implementation PR | -| **Signal** | a: Alice reaches her fork, her own hire and a standard worker through `ensureWorkerSession`, and each answers as its own configuration on `agent`'s one copy; the registry gains no entry; her second worker reads none of the first's notes; the second host sees the hire with no restart. b: Bob finds none of her sessions; Bob opening her session, reading her worker, and creating a session that names it are each refused; a session created with no worker, a message naming a worker, and a link seeded through the create's state are refused; Alice creating a session for her worker on another flow is refused | +| **Signal** | a: Alice reaches her fork, her own hire and a standard worker through `ensureWorkerSession`, and each answers as its own configuration on `agent`'s one copy; the registry gains no entry; her second worker on `agent` reads none of the first's notes; the second host sees the hire with no restart. b: Bob finds none of her sessions; Bob opening her session, reading her worker, and creating a session that names it are each refused; a session created with no worker, a message naming a worker, and a turn that changes a session's worker are refused; Alice creating a session for her worker on another flow is refused | | **Input** | Two `WORKER.md` standard workers on two flows, two users. A different worker id or flow must pass too | -| **Anti-game** | No assertion on a link's stored value or a key string. No fixture writes a worker the users didn't make through the app | -| **Control that must fail** | `GOAL_CONTROL=org-scoped-workers`: leg b FAILS on *Bob reads Alice's worker*. `GOAL_CONTROL=caller-link` accepts the create's caller state and reads the link from it instead of the server-only field: leg b FAILS on *a seeded link runs her other worker*. Today's `main`: legs a and b FAIL | +| **Anti-game** | No assertion on a session's stored `workerId` or a key string. No fixture writes a worker the users didn't make through the app | +| **Control that must fail** | `GOAL_CONTROL=org-scoped-workers`: leg b FAILS on *Bob reads Alice's worker*. `GOAL_CONTROL=no-create-check` removes the worker flow's create check: leg b FAILS on *Bob's create naming Alice's worker writes a session*. Today's `main`: legs a and b FAIL | ## What changes @@ -66,15 +67,17 @@ On the left, a worker is a registered copy. On the right, it is data, and the co - const researcher = createClient({ flowKind: "acme.~alice.researcher", userId }) - await researcher.sendAction("run", { message }, { sessionId }) + const workforce = createWorkforceClient({ userId, baseUrl }) // same options as createSessionClient -+ const session = await workforce.ensureWorkerSession({ worker: "researcher" }) // finds hers, or creates one linked to it ++ const session = await workforce.ensureWorkerSession({ worker: "researcher" }) // finds hers, or creates one for it + const agent = createClient({ flowKind: session.flowKind, userId, baseUrl }) // the flow the worker names + await agent.sendAction("run", { message }, { sessionId: session.id }) // no worker in the message ``` -Underneath, the helper is today's session client with two new options: -`createSessionClient().listSessions({ flowKind, userId, worker })` and -`createSessionClient().createSession({ flowKind, userId, worker })`. The roster gives each -worker's `flow`. `findWorkerSession` checks without creating. +Underneath, the helper is today's session client: +`createSessionClient().listSessions({ flowKind, userId, state: { workerId } })` and +`createSessionClient().createSession({ flowKind, userId, state: { workerId } })`. The worker is +a readonly field of the session's state ([D5](DECISIONS.md#d5)): the server checks it when the +session is created and refuses any later change. The roster gives each worker's `flow`. +`findWorkerSession` checks without creating. **What an installation writes in `WORKER.md`:** nothing changes. A file is a standard worker. @@ -83,11 +86,11 @@ worker's `flow`. `findWorkerSession` checks without creating. ```mermaid flowchart LR C["a session create · names a worker"] --> K["the create check · own or standard · on this flow"] - K --> L["the link · a server-only field on the session record · never changes"] + K --> L["workerId · a readonly field of the session's state · never changes"] L --> T["each turn · names no worker"] T --> W["the worker · the owner's row, or a standard file"] W -->|"names resolved per turn"| R["the flow's one copy runs it"] - R --> M["memory keyed by the worker"] + R --> M["on agent · memory kept per worker"] ``` The create is the one place a session meets a worker. Every path that opens a session names its @@ -115,6 +118,18 @@ copy per worker, so a hire still waits for a restart elsewhere. wrong: every way of opening a session must know its worker up front, and an app that wanted to pick one after opening can't. +**Approved by the product owner on 2026-10-07, recorded after merge** ([EVOLUTION.md](EVOLUTION.md#amendment-binding)): + +2. **[D5](DECISIONS.md#d5) · The worker is a readonly field of the session's starting state; + there is no separate link.** The create check confirms it, and nothing changes it after. If + wrong: a binding the flow's own blocks must not see has nowhere to live. +3. **[D6](DECISIONS.md#d6) · On a custom worker flow, keeping one user's workers apart is the + flow's author's job.** If wrong: two of one user's workers on a custom flow read each other's + data until its author keys it by worker. Nothing crosses users. +4. **Engine scope.** The binding ships as three engine changes beyond the epic's D3 item (3) as + written: a readonly guard on session state, a state filter on listing inside the store, and a + create-time schema refusal on flows that bind their sessions. + **Signed on 2026-10-06, withdrawn on 2026-10-07 by [epic D9](../../epics/FIX-1786/DECISIONS.md#d9):** [D1](DECISIONS.md#d1) and [D2](DECISIONS.md#d2), the operator step for old hires. **Decided:** [D3](DECISIONS.md#d3), formerly Q1: a fork copies the standard worker's shared instructions. diff --git a/specs/issues/FIX-1788/figures/d4-link-at-create.svg b/specs/issues/FIX-1788/figures/d4-named-at-create.svg similarity index 85% rename from specs/issues/FIX-1788/figures/d4-link-at-create.svg rename to specs/issues/FIX-1788/figures/d4-named-at-create.svg index cf370a25e1..87132182e7 100644 --- a/specs/issues/FIX-1788/figures/d4-link-at-create.svg +++ b/specs/issues/FIX-1788/figures/d4-named-at-create.svg @@ -1,5 +1,5 @@ + aria-label="D4, the call: where does a session learn which worker it runs, when it is created or on its first message? Chosen: at create, named once in the session's starting state. Instead of: on the first turn, in server-owned session state. The row that decides it, what carries the worker: the session, once, so messages never name a worker, against the first message, so every app call carries it. Second row, where it is checked: an engine check on every way a session is made, against flow code on a turn with no create hook. Third row, a session with no worker: never written, refused at create, against existing until its first turn and refused only then. Locks in a create check on every path that opens a session, the worker named in the create's starting state, and two lookup helpers. Flips if an app must open a session before it knows which worker it runs.">