diff --git a/specs/issues/FIX-1788/BUSINESS-RULES.md b/specs/issues/FIX-1788/BUSINESS-RULES.md new file mode 100644 index 0000000000..a43cc3ff1e --- /dev/null +++ b/specs/issues/FIX-1788/BUSINESS-RULES.md @@ -0,0 +1,85 @@ +# FIX-1788 · Business rules + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +The cases, written as rules. Alice and Bob are two users of one org. The +*proved by* column is the check the plan runs. A human reviews this page; the plan turns it into +work. + +## Holding a worker + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-1 | Alice hires a worker | One row is written in her user scope, in this org. Nothing is registered. Her next turn on any process can use it | CI · VG leg a, second host | +| BR-2 | Alice forks a standard worker | A new worker of hers, starting from its configuration, under a new id ([Q1](DECISIONS.md#q1) decides the shared instructions). The standard worker is unchanged for everyone | CI · VG leg a | +| BR-3 | Anyone writes, edits or deletes a standard worker, by any path | Refused, naming it as standard and suggesting a fork | CI | +| BR-4 | Alice hires or forks with an id already on her roster, or a standard worker's id | Refused, naming the id. Bob's roster is not consulted | CI | +| BR-5 | Alice and Bob each hire `researcher` | Two workers. Neither sees the other's in any listing | CI · VG leg b | +| BR-6 | A hire's configuration names a flow that isn't a registered worker flow, or one kept for standard workers ([FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) BR-14), or fails the flow's schema | Refused when saved, with the flow's own reason. Nothing written | CI | +| BR-6a | A hire or fork grants a document or collection its flow doesn't declare | Refused when saved, naming it. Only a standard worker, in files, brings a collection its flow declares for it (the concept's "resources are declared on flows") | CI | +| BR-7 | Alice fires a worker | Its row is deleted. Its sessions stay readable to her, and a new turn on one is refused, naming the worker as fired. Every process sees it on the next turn | CI · two hosts | +| BR-8 | A hire, fork or fire finishes a turn | The turn names the worker collection it wrote, so a view reloads it ([FIX-1761](https://linear.app/fixpoint-labs/issue/FIX-1761)). No tool name is special-cased | CI | +| BR-9 | Alice lists her roster | Her own workers and every standard worker, each marked standard or hers. Nothing of Bob's, nothing from another org | CI · VG | + +## A session's worker + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-10 | Alice's first turn in a session names her worker, on the flow it names | The server links the session to it and runs the turn as it | CI · VG leg a | +| BR-11 | A first turn names a worker of Bob's | Refused with the same answer as a worker that doesn't exist. Nothing linked | CI · VG leg b | +| BR-12 | A first turn names a worker of Alice's on another flow | Refused, naming both flows. Nothing linked | CI · VG leg b | +| BR-13 | A later turn names a different worker | Refused. The link never changes. A later turn may omit the worker | CI | +| BR-13a | Two first turns on one unlinked session arrive together, naming different workers | One links and runs. The other is refused as BR-13, and its worker never runs | CI | +| BR-14 | A turn arrives on a session with no link and names no worker | Refused, saying a worker must be named | CI | +| BR-15 | A session is created with caller state for the link | 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 has no link | 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 | 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-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 | + +## 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-21 | A stored configuration from an older version loads | It reads (BP-030), or the turn is refused naming the field. Never silently dropped | CI | +| 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 (BP-030) | 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-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 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 | + +## One copy per flow + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-26 | The app starts with workers on several flows | Each flow a worker names is registered once. No copy per worker, no owner pin | CI · V0 · VG leg a | +| BR-27 | Code calls `register(flow, { pin })` or declares collection cardinality | It works as before, with a deprecation note naming FIX-1798 | CI | + +## Coming across from today + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-28 | The new code boots on a store with old hires, before the step | Old hires don't run. The boot reports how many wait for the step. Nothing is read across users or orgs | CI · VG leg c | +| BR-29 | The step meets a hire owned by Alice | It becomes her worker under its id. Its private cells move to the worker's key, and its sessions link to it | CI · VG leg c | +| BR-30 | The step meets an org-wide hire | A private copy for each member with a session on it ([D2](DECISIONS.md#d2)), each with that member's sessions and a copy of the hire's memory. Members without one get none | CI · VG leg c | +| BR-31 | A moved worker's id is already on that member's roster, or is a standard worker's id | It takes a new id, derived the same way on every run, and the report names both. Its sessions and memory move with it. Nothing overwritten, nothing skipped | CI | +| BR-32 | The step runs twice, or stops halfway | The second run finishes the first and changes nothing done. The old rows stay | CI | +| BR-33 | An old hire names a flow that's gone | Reported, not moved | CI | +| BR-33a | An old hire names a flow now kept for standard workers | Moved and reported. Its turns are refused as BR-22a until the installation changes that | CI | + +## Failure taxonomy + +A refused link, a refused turn and a refused write change nothing and name why. A configuration +that fails on load refuses that turn only; the row and the session survive for a fix. A missing +step is not an error: old hires wait, reported. Nothing 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 +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 new file mode 100644 index 0000000000..338cdc0485 --- /dev/null +++ b/specs/issues/FIX-1788/DECISIONS.md @@ -0,0 +1,142 @@ +# FIX-1788 · Decisions + +[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +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 the people already using hired workers, and one it asks. + +## The tree + +```mermaid +flowchart TD + I["FIX-1788"] --> D1["D1 · old hires move in one operator step"] + D1 -.->|"rejected · keeps every copy's machinery alive"| X1["read the old shape at run time"] + D1 -.->|"rejected · users lose their workers"| X1b["start fresh"] + I --> D2["D2 · an org-wide hire goes to each member who used it"] + D2 -.->|"rejected · breaks a worker people use"| X2["nobody, until an operator names one"] + D2 -.->|"rejected · workers nobody asked for"| X2b["every member"] + I --> Q1["Q1 · open · a fork copies the shared instructions"] + Q1 -.->|"not recommended · an edit to the files changes your fork"| X3["a fork follows them"] +``` + +Solid edges are what you're signing. Q1 is the one open ask. + + +## D1 · Old hires, their memory and their conversations move to the new shape in one operator step + +| | | +|---|---| +| **Instead of** | Reading the old rows, cells and sessions at run time beside the new path · or starting fresh | +| **Because** | A hire's memory sits in its own copy's private cell, and its conversations are recorded against its own copy's address. The shared copy can reach neither unless the per-copy machinery stays alive, and that machinery is what [FIX-1798](https://linear.app/fixpoint-labs/issue/FIX-1798) removes. The same upgrade already has an operator step ([FIX-1790](https://linear.app/fixpoint-labs/issue/FIX-1790)), and [FIX-1538 D2](../FIX-1538/DECISIONS.md#d2) moved pinned cells the same way | +| **Locks in** | Between the deploy and the step, a user's old hires don't run, and the boot says how many wait for it. Every deployment with hires runs one documented step, beside FIX-1790's. Nothing is deleted, and running the step twice changes nothing | + +![D1: how hires made before the upgrade come across. One operator step, chosen, beside reading the old shape at run time. Decides it: the shared copy can't reach a copy's cells or conversations without keeping every copy's machinery alive. Price: old hires wait for the operator. Locks in one step beside FIX-1790's; flips if a deployment has no operator](figures/d1-upgrade-step.svg) + +It comes down to the old copies: reading them at run time keeps them alive forever. + +**What would change my mind:** a hosted deployment with no operator to run a step. Then the move +runs on a user's first load instead, with the old machinery kept until every user has loaded. + + +## D2 · A worker hired for the whole org goes, as a private copy, to each member who talked to it + +| | | +|---|---| +| **Instead of** | Nobody's, until an operator names an owner · or a copy for every member of the org | +| **Because** | An org-wide hire is the hole this epic closes, so it can't stay shared. Each member who talked to it already has conversations and memory with it that only they can read. A private copy each keeps exactly what each person had and gives nobody anything new. Nobody's breaks a worker a team uses daily; every member's adds workers people never asked for | +| **Locks in** | One worker becomes several independent ones: a change one member makes reaches no other. What the worker remembered for the whole org is copied into each, and every one of them could already read it. A copy whose id the member already uses takes a derived id, reported. The old row stays, reported, so it can become a library template once [FIX-1795](https://linear.app/fixpoint-labs/issue/FIX-1795) ships | + +![D2: where a worker hired for the whole org goes. A copy for each member who used it, chosen, beside nobody until an operator names one. Decides it: what each person already had. Price: one worker becomes several that drift apart. Flips if teams relied on one shared memory changing together](figures/d2-org-wide-hire.svg) + +It comes down to what each person already had: nobody loses a worker, nobody gains one. + +**What would change my mind:** teams that rely on one org-wide worker's memory changing for +everyone at once. Then the right home is the library or a shared resource, and the step should +hold the hire for the operator instead. Or: no deployment uses an org-wide hire today beyond the +chief-of-staff seat. Then nobody's costs no one a worker, and the step only reports them. + +## Decided, not asked + +- **The link lives in server-owned session state** (the epic's D3, change 3), set by the worker + flow on a session's first turn after one check: the worker is the session user's own or a + standard one, it names this flow, and the session has no link yet. Every path that opens a + session passes that check: a person's turn, a task, a mailbox post. It never changes. +- **The link is set on the first turn, not at create.** Create runs no flow code; the epic's D3 + names admission only if flow code can't do it. The door refuses a turn with no link. +- **A worker's configuration is read on every turn**, from its row or its file, with names + resolved against what the installation registers ([ER-2](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). + A non-standard one is checked when it is saved and again when it loads. +- **A worker's private state is keyed by the worker** on every worker flow, the skills drawer + first. The skills library takes its key per run, a Layer 2 change; if a capability can't, it + goes back to the epic (ER-22). +- **A worker's document and reference grants hold on every turn**, over what its model can + reach: tools and context. The flow's own code is the app's and is not narrowed per worker. +- **Ids.** A worker's id is unique on its owner's roster and can't be a standard worker's id. A + fork gets a new one. +- **The upgrade step ships as code the operator runs**, not a SQL procedure like FIX-1538's: it + relinks sessions and copies rows per member, which a hand procedure gets wrong. FIX-1538's own + *what would change my mind* named this. +- **Fork and the library's copy share one write path.** FIX-1788 owns it; FIX-1795 calls it + for a template (the epic's coordination seams). No library work is pulled in here. +- **A fire deletes the row.** Sessions linked to it stay readable and refuse new turns. +- **A standard worker has no write path.** It is a read-only collection projected from the files. +- **Every deprecation marker** on collection cardinality and owner pins names FIX-1798. +- **The org-wide seat inventory stops listing hired workers**, which it showed to every member. +- **Four PRs, a stack:** server-owned session state; the worker model beside today's; the + upgrade step; then the switch, every flow at once. Nothing existing changes shape before the + step is on `main`, so no single PR strands a hire ([PLAN.md](PLAN.md#sequence--the-pr-plan)). +- **No worker-flow declaration shape is named.** The epic's [Q1](../../epics/FIX-1786/DECISIONS.md#q1) + is chosen at FIX-1789's gate. The `agent` flow change takes either. + +## Considered and dropped + +| 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) | +| A worker noun in the engine | No consumer outside Workforce (epic [D3](../../epics/FIX-1786/DECISIONS.md#d3)) | + + +## Q1 · open · When a user forks a standard worker, does the fork copy its shared instructions, or keep following them? + +**The fork.** Standard workers in model variants (a Codex, a Claude and a Cursor researcher) +share core instructions, per the 2026-10-04 lock. A fork can **copy** them, so it never changes +unless its owner edits it, or **follow** them, so it picks up the installation's later edits. + +**In plain terms.** Alice forks the researcher to change its model. Next month the installation +improves the researcher's instructions. Under copy, Alice's fork keeps last month's text until +she forks again. Under follow, it gets the new text, with her model change kept. + +**The trade-off.** Copy is what a library copy does (ER-10): nothing changes under its owner. +Its cost is forks that go stale. Follow keeps forks current, at the cost of a layered +configuration: the file, then the user's changes on top, merged on every turn. An edit to the +files then changes what runs with every forker's access. + +**My recommendation: copy.** One rule for every copy a user holds, fork or library. A fork is +the user saying they want something different. Follow can be added later as an option on a +fork; taking it away later would change running workers. + +**What would change my mind:** users who fork mostly to change one setting, while the core +instructions change every week. Then forks stale at once, and follow earns its layering. + +**If wrong:** forks drift until users re-fork, which costs their edits. Small to reverse: +follow is additive. + +![Q1: when a user forks a standard worker, does the fork copy its shared instructions or follow them? Copy, recommended, beside follow. Decides it: nothing changes under the owner, the library's rule. Price: forks go stale until re-forked. Locks in one rule for every copy; flips if users fork to change one setting while the core changes weekly](figures/open-fork.svg) + +It comes down to the library's rule: nothing changes under its owner, so forks go stale. + +## Settled + +- **Which flows a worker names, and where each is defined:** 23 flows over 94 `WORKER.md` + files, every file classified, the control failing. [`poc/flow-inventory/`](poc/flow-inventory/README.md). + +## How it got here + +- **Draft** — framed as the epic's privacy spine: workers as user-scoped rows, one copy per flow, + a server-owned link set once on the first turn; old hires carried by one operator step, an + org-wide hire copied to the members who used it; four PRs, engine first. + +**Open:** Q1. diff --git a/specs/issues/FIX-1788/DOCS.md b/specs/issues/FIX-1788/DOCS.md new file mode 100644 index 0000000000..61225fde5f --- /dev/null +++ b/specs/issues/FIX-1788/DOCS.md @@ -0,0 +1,151 @@ +# FIX-1788 · Documentation draft + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs** · [Evolution](EVOLUTION.md) + +FIX-1788 publishes the specifics the epic's [ownership table](../../epics/FIX-1786/DOCS.md#ownership) +gives it: standard and non-standard workers, forking, and a session's worker. The shared +opening is the epic's, published by FIX-1796. Quoted prose follows the outsider rule +([`user-docs.md`](../../../docs/contributing/user-docs.md)). Names in it that `PLAN.md` doesn't +pin (the session-state option, the upgrade command, `fork`) are reconciled with the shipped +code before publishing. Q1's answer sets one sentence, marked below. + +## UPDATE · `apps/docs/docs/configuration/flow.md` · the `session` table, a new row after `client` + +> | `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 anything that decides what a session may do, such as which worker 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. +> Declare such fields in `serverOwned`. The create then refuses a value for them, and only a +> block in your flow can set them, from something it checked. + +## REPLACE · `apps/docs/docs/workforce/durable-hire.md` · the whole page + +Title *Hiring, forking and firing workers*, sidebar label *Hiring and forking*. Everything from +"What the framework gives you" to "Limits" is replaced by: + +> # Hiring, forking and firing workers +> +> A worker your installation's files declare is a **standard worker**: every user has it, and +> nobody can change it while the app runs. Everything else a user adds is a worker of their +> own, stored in their data, and nobody else can see it. +> +> ## Hiring a worker +> +> A hire writes one row to the user's roster, in the organization they're signed in to. Nothing +> is registered and nothing restarts: the next turn on any of your processes can use it. +> +> ```ts +> import { createSeatHireBlocks } from "@flow-state-dev/workforce" +> +> const { hire, fork, fire } = createSeatHireBlocks({ kinds }) +> +> defineFlow({ +> kind: "roster-admin", +> actions: { hire: { block: hire }, fork: { block: fork }, fire: { block: fire } }, +> }) +> ``` +> +> `hire` takes an id, the flow the worker runs on, and its settings, the same keys a +> `WORKER.md` accepts. The worker's flow checks the settings when the row is saved. A bad +> value, a flow your installation doesn't run workers on or keeps for standard workers, or an id +> already on the user's roster +> is refused, and nothing is written. An id can't be a standard worker's: fork it instead. +> +> ## Forking a standard worker +> +> `fork` starts a new worker of the user's own from a standard worker's configuration, under a +> new id. The standard worker doesn't change, for this user or anyone else. *(Q1: the fork +> keeps a copy of the standard worker's instructions, and doesn't change when your +> installation's files do. Fork again to pick up a change.)* +> +> ## Firing a worker +> +> `fire` deletes the row. Its past sessions stay readable to their owner. A new message to one +> is refused with the worker named as fired. Every process sees the fire on the next turn. +> +> ## Who can reach a worker +> +> Only its owner. A worker belongs to one user in one organization: another member can't list +> it, open its sessions, send it a message or name it in a session of their own. A user who +> belongs to two organizations has a separate roster in each. +> +> ## What is stored +> +> 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. +> +> ## After a hire, refresh the roster +> +> A turn that hires, forks or fires names the roster as a collection it wrote, so a view that +> listens for written collections reloads it. You don't need to watch for a tool's name. + +## UPDATE · `apps/docs/docs/workforce/workers-on-disk.md` · "Hiring the roster", opening paragraphs + +> Every `WORKER.md` is a **standard worker**. Every user of every organization in the +> installation has it, configured exactly as the file says, and nobody can edit it while the app +> runs. To change one for yourself, [fork it](./durable-hire.md#forking-a-standard-worker). +> +> 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. + +## UPDATE · `apps/docs/docs/workforce/workers-on-disk.md` · a new section "Talking to a worker", before "What this does not do" + +> ## Talking to a worker +> +> Send to the flow the worker runs on, and name the worker: +> +> ```ts +> await client.actions("agent").sendAction("run", { message, worker: "researcher" }, { sessionId }) +> ``` +> +> The first message links the session to that worker. The server checks the worker is yours or +> a standard one and that it runs on this flow, then records the link where callers can't write +> it. Later messages can leave `worker` out. Naming a different worker on a linked session is +> refused: start a new session instead. A worker that isn't yours is refused with the same answer +> as one that doesn't exist. +> +> Tasks and messages your other workers hand to this one open sessions the same way, through +> the same check. + +## UPDATE · `apps/docs/docs/persistence/overview.md` · after "Upgrading: moving hired seats' stored data", a new section + +> ## Upgrading: hired workers become worker rows +> +> Run this once after deploying a version where workers are stored per user, together with the +> step in [Which organization a record belongs to](#which-organization-a-record-belongs-to). +> Until it runs, hires made on the earlier version don't run, and the app's start reports how +> many are waiting. +> +> ```bash +> fsdev workforce upgrade-workers --store "$DATABASE_URL" +> ``` +> +> - A worker one user hired becomes that user's worker, with its memory and its conversations. +> - A worker hired for a whole organization becomes a private copy for each member who has a +> conversation with it, with that member's conversations and a copy of its memory. Members +> who never used it get none. +> Each copy then changes on its own. +> - A worker whose id its new owner already uses comes across under a new id, and the report +> names both. +> - A worker whose flow your app no longer runs is reported and left where it is. +> +> Nothing is deleted. The earlier rows stay, and running the step again changes nothing it +> already moved. + +## UPDATE · `packages/workforce/README.md` and `packages/engine/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 on its first message. +> +> **engine:** `session.serverOwned` names session-state fields the session create refuses. + +## Publication ownership + +FIX-1788 publishes these with P4, after its checks pass. `built-in-worker.md` is FIX-1789's; +the overview opening and the glossary are FIX-1796's. FIX-1790 owns the persistence page's org +section; the new section above sits beside it and links to it. diff --git a/specs/issues/FIX-1788/EVOLUTION.md b/specs/issues/FIX-1788/EVOLUTION.md new file mode 100644 index 0000000000..dc228cdacd --- /dev/null +++ b/specs/issues/FIX-1788/EVOLUTION.md @@ -0,0 +1,22 @@ +# FIX-1788 · Evolution + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · **Evolution** + +Child-specific lineage. The epic's [EVOLUTION.md](../../epics/FIX-1786/EVOLUTION.md) already +supersedes INST-5 (hires as collection instances with pins) and the hired roster collection; +this record covers the shipped designs FIX-1788 changes in detail. + +| Prior intent and precise source | Treatment | Why / evidence | Replacement | Compatibility | +|---|---|---|---|---| +| A hire is durable at once and process-wide only at the next boot, for a fire as much as a hire; one public `register` / `unregister` door; [`../FIX-1475/DECISIONS.md#d1`](../FIX-1475/DECISIONS.md#d1) | **Superseded** | A hire is a row read per turn, so no process registers it; the restart window it documented closes | BR-1, BR-7, BR-20 | The engine's `register` stays for flows; Workforce stops calling it per worker (S14) | +| A stored row that fails at boot is skipped, named and served around; [`../FIX-1475/DECISIONS.md#d2`](../FIX-1475/DECISIONS.md#d2) | **Amended** | Validation moves to save and load: a bad row refuses its own turn, not the boot. The "fail fast on this deploy, degrade on a past one" rule is kept | BR-6, BR-19, BR-22 | `brokenSeats` and `rehire` retire with the boot reload (S14); a refused turn names the cause | +| The durable row is org-scoped, and a hired seat's address carries its org; [`../FIX-1475/DECISIONS.md#d3`](../FIX-1475/DECISIONS.md#d3) | **Superseded** | The row is the owner's, in their per-org user scope; the address is the flow, and the worker is named on the session | ER-1, S3, BR-10 | Old rows are read once, by the upgrade step ([D1](DECISIONS.md#d1)) | +| A hired seat keeps a person's data in one cell per (org, person), keyed off its owner pin; [`../FIX-1538/DECISIONS.md#d1`](../FIX-1538/DECISIONS.md#d1) | **Superseded** | FIX-1790 keys every flow's user data per (user, org); no worker carries a pin | Epic ER-3, FIX-1790 | FIX-1790's step moves those cells; this step moves only per-copy private cells | +| Seat data moves only by an operator step, and only data that provably belonged to a seat; [`../FIX-1538/DECISIONS.md#d2`](../FIX-1538/DECISIONS.md#d2) | **Retained**, extended | Same rule for per-copy cells and sessions: a copy's own cell and its sessions provably belong to it | [D1](DECISIONS.md#d1), S13 | The step ships as code (that card's *what would change my mind*) | +| A worker's `resources:` grant narrows the resource map its copy is minted with, so a block nested in its action resolves only granted documents; FIX-1381, `packages/workforce/src/seat-resources.ts` header and `goals/workforce-seats/a-seat-reaches-the-documents-its-file-names/goal.md` (no retained spec) | **Amended** | A shared copy has one resource map. The grant now narrows what the worker's model reaches on each turn; the flow's own code is the app's | BR-24, S8 | The grants goal is rewritten to grade what the model reaches (V7). The `resources:` key and its `ro`/`rw` words are unchanged | +| Each seat gets its own skills drawer, keyed by its flow-instance id under `flowIsolation`; `packages/workforce/src/agent-worker-flow.ts` (the `collectionConfig` comment) | **Superseded** | On a shared copy the instance id is the flow's, so every worker shares one drawer ([epic POC](../../epics/FIX-1786/poc/singleton-worker-link/README.md), I1, I2) | BR-23, S7 | The step moves each copy's drawer to its worker's key; nothing is orphaned | +| CoS is one org admin seat whose hires belong to the org; [`../../epics/FIX-1650/DECISIONS.md#q2`](../../epics/FIX-1650/DECISIONS.md#q2), already superseded in part by the epic's EVOLUTION | **Superseded in part**, as the epic recorded | Workers are always private: a CoS hire is the hiring user's row | Epic ER-1, S9 | FIX-1719's shipped seat keeps hiring through S9, as the user's, until FIX-1791 replaces it | + +None of these is wholly overturned in intent: each kept its permission boundary, and the +boundary moved from a registered copy to a row and a link. Re-check each against current code +before implementing; FIX-1789 and FIX-1790 may have moved two of them first. diff --git a/specs/issues/FIX-1788/PLAN.md b/specs/issues/FIX-1788/PLAN.md new file mode 100644 index 0000000000..1ed975f2b6 --- /dev/null +++ b/specs/issues/FIX-1788/PLAN.md @@ -0,0 +1,159 @@ +# FIX-1788 · Plan + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +Written for the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSINESS-RULES.md) +(BR-n) and [DECISIONS.md](DECISIONS.md). `tdd`. Four PRs, a GitHub stack (epic ER-26). Builds +start only after FIX-1789 and FIX-1790 merge and FIX-1787's merge-first rows land (epic D4, ER-23). + +## Surfaces + +| ID | Package · role | Change | Rules | +|---|---|---|---| +| S1 | `engine` + `core` · session state declaration, the session create route | A flow can declare session-state fields server-owned. The create route refuses caller state for them with 400, naming the field; only flow code writes them. Unset means today. FIX-1791 keeps delegates here too | BR-15 BR-16 | +| S2 | `core` + `engine` · collection cardinality, `register(flow, { pin })` | Deprecation markers (JSDoc and one boot note per process), each naming FIX-1798. Behaviour unchanged | BR-27 | +| 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; old shapes read (BP-030) | BR-1 BR-4–6a BR-21 | +| 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 check (the session user's own worker or a standard one · names this flow · no link yet) and the server-owned write, atomic per session: two racing first turns link one worker. The door's per-session concurrency or a versioned write, your pick; no Layer 1 change. The door, the task entry and the mailbox wake all call it | BR-10–14 BR-13a BR-18 BR-19 BR-19a | +| 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 names don't resolve, or whose flow is now standard-only. Every read of a worker setting moves off `ctx.flow.config` to it | BR-20–22a | +| S7 | `orchestration` + `workforce` · private state by worker | The skills library takes its key per run; every flow-isolated resource on a worker flow is keyed by the worker. The `agent` drawer first | BR-23 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 existing hire blocks and tool; fork is new beside them. Each turn names the collection it wrote | BR-1 BR-2 BR-4 BR-7 BR-8 | +| 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, in whichever declaration shape the epic recorded | BR-26 | +| S11 | `workforce` · consumers | Worker lookup, task hand-off and the mailbox wake address (flow, worker) through S5. The shared-write stamp (FIX-1789 BR-20) takes its worker from the link. The org-wide seat inventory stops listing hired workers | BR-18 BR-25a | +| S12 | `shift-manager` · Roster and talk | Lists S3 and S4 for the signed-in user; sends with the worker named; reloads on BR-8 | BR-9 | +| S13 | `workforce` · the upgrade step | An operator command: owned rows to workers, per-copy cells to worker keys, sessions relinked onto the shared copy; org-wide rows per D2, memory copied to each member; a taken id gets a derived one; a report. Old rows stay | BR-28–33a | +| S14 | `workforce` · **removals** | The boot reload of hired seats, per-worker minting, `registerHiredSeat`, every owner pin Workforce sets, `brokenSeats`/`rehire` (a broken worker now refuses at load, BR-19 BR-22). The old roster collections stay defined for S13 only | — | +| S15 | goals, apps | Every goal asserting a copy per worker is rewritten to the new shape or retired with a line saying which rule replaces it; kitchen-sink and Shift Manager labs move | BR-26 | +| S16 | Docs | [DOCS.md](DOCS.md); README entries; `minor` changesets for `engine`, `core`, `workforce`, `orchestration` | — | + +## Sequence · the PR plan + +| PR | Delivers | Depends on | +|---|---|---| +| P1 · server-owned session state | S1 S2 | — | +| P2 · the worker model, beside today's | S3–S9, proved on a fixture worker flow registered once; every existing flow, `agent` included, still mints per worker | P1 | +| P3 · the upgrade step | S13 | P2 | +| P4 · the switch | S10 for every flow, `agent` first; S7 on `agent`'s drawer; S11, S12, S14, S15, S16, VG | P2, P3 | + +```mermaid +flowchart TD + S1["S1 · server-owned state"] --> S5["S5 · the link"] + S2["S2 · deprecations"] --> S10 + S3["S3 · worker rows"] --> S5 + S4["S4 · standard projection"] --> S5 + S5 --> S6["S6 · per-turn configuration"] + S6 --> S7["S7 · private state by worker"] + S6 --> S8["S8 · grants per turn"] + S3 --> S9["S9 · hire, fork, fire"] + S9 --> S13["S13 · upgrade step"] + S7 --> S13 + S7 --> S10["S10 · one copy per flow"] + S8 --> S10 + S13 --> S10 + S10 --> S11["S11 · consumers"] + S11 --> S12["S12 · Shift Manager"] + S11 --> S14["S14 · removals"] + S14 --> S15["S15 · goals and apps"] + S15 --> S16["S16 · docs"] +``` + +Nothing existing changes shape until P4, and the step it needs is already on `main` by then, +so no deploy of any one PR strands a hire. + +## Checks + +| 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; a create without the field, and a flow that declares none, behave as today; flow code writes the field | +| V2 | S2 | BR-27: markers present, existing instance and pin tests unchanged | +| V3 | S3 S4 | BR-1, BR-3–6a (BR-6 on a standard-only flow too), BR-9, BR-21 on the real engine; BR-5 with two users | +| V4 | S5 | BR-10–14 through the door; BR-13a with two first turns in flight at once; BR-18 through the task entry and the mailbox wake; BR-19, BR-19a | +| V5 | S6 | 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 | +| 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 (fork content per Q1's answer), BR-7 across two hosts, BR-8 | +| V9 | S10 | BR-26: the registry holds one entry per flow, none per worker, no pin set by Workforce | +| V10 | S13 | BR-28–33a on a store written by today's `main` (a fixture writer committed beside the check, run at `fbecfe6f2` or later); BR-30 asserts each member's copied memory; BR-31 with an owned and an org-wide `researcher` on one member | +| 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` | + +One check per decision: D1 and D2 by V10, Q1 by V8. The second path (BP-035): a second host +(V5, V8), stored rows from today (V10), the off state of S1 (V1), a fired or broken worker (V4). + +## Pinned names · the only three + +| Where | Name | Why pinned | +|---|---|---| +| The door's input | `worker` | Public; an app sends it | +| The worker collection | `workforce/workers/*`, user scope | Persisted; FIX-1791 and FIX-1795 read and write it | +| The session's link | `workerId`, server-owned session state | Persisted; S13 writes it into old sessions | + +Everything else is yours to name, in the new terms (worker, worker flow; not seat or kind). + +## Guardrails + +| Rule | Because | +|---|---| +| Every path that opens a session for a worker goes through S5's one check | A link checked at the door alone is open at the task entry (tenet 5) | +| Access is read at the session user'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 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 | +| S13 never rewrites or deletes an old row; it reports what it can't move (BP-030) | An upgrade must not lose a user's worker | +| No Layer 1 change beyond S1 (ER-22) | If S7 or S8 needs one, stop and take it to the epic | +| No `seat*` renames | FIX-1796 sweeps them with the docs | + +## Docs + +Reconcile and publish [DOCS.md](DOCS.md) in P4, after V4 to V10 pass, against the shipped +refusal wording and the upgrade command's real name. + +## Sketch · pseudocode, illustrative, react to the shape + +``` +on a turn at a worker flow's door, task entry or mailbox entry: + if the session has no link: + name ← the turn's worker (door) or the dispatcher's (task, mailbox) + w ← read name at the session user's scope, else the standard projection ← the whole check + refuse unless w, w.flow = this flow + write link to server-owned session state ← once + else refuse if the turn names a different worker + w ← load the linked worker; resolve its names; refuse if any don't + run the turn with w's configuration, private state keyed by w +``` + +**POC:** the epic's [`singleton-worker-link`](../../epics/FIX-1786/poc/singleton-worker-link/README.md) +proved the premise and why S1 is needed (O1, R1, I1). This spec's +[`poc/flow-inventory/`](poc/flow-inventory/README.md) re-derives which flows S10 converts: 23 +flows over 94 files, PASS, the control failing. No new premise needed a POC. + +## At implement time + +- **Read the epic's Q1 on `main`.** If a shape is recorded, the `agent` flow moves onto it. If + not, build to ER-2 and name neither. +- 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. +- 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`, `HireOptions.kinds`, `seatDoorOf`, + `SeatDoor`, `createSeatHireBlocks`, `createSeatHireCapability`, the `seat*` keys of + `workerConfigSchema()`, `HIRED_ROSTER_*` (read by S13 only). + +## Notes from review + +Recorded verbatim for the implementer to weigh against real code; not folded into the design. + +- **S5 + S6 as one module** (PR #2812, review comment): "Make S5 + S6 one deep module with one interface. [...] Callers (the door, the task entry, the mailbox wake, and each setting read inside a turn) should reach one narrow interface, roughly `resolveWorker(ctx) → { worker, resolved config }` plus `link(...)`. They should not touch the worker row, the name resolution, or the refusal rules. [...] add one line to S5/S6 so the implementer treats it as one module, and keep the `ctx.flow.config` migration behind it." +- **S6–S8 as one surface** (Cursor, PLAN.md): "S6–S8 are three rows for one idea (“per-worker execution slice on the shared copy”). A single surface with sub-bullets (config load · worker-keyed resources · grants) might read cleaner without changing the four-PR stack." +- **Parallel prose** (Cursor, DECISIONS.md): "This block largely restates `PLAN.md` surfaces, guardrails, and sequence. Consider keeping only what is *not* elsewhere (D1/D2 consequences, fork/library seam) and linking to Plan §Surfaces / §Sketch for the procedural contract — reduces five-way drift when link semantics change." +- **Shipped names in DOCS.md** (Cursor, DOCS.md): "Draft still uses `createSeatHireBlocks` / `roster-admin` while Plan defers `seat*` to FIX-1796 and pins only `worker`, `workforce/workers/*`, `workerId`. Worth a one-line “shipped names” box at the top of this file so P4 docs work does not re-litigate exports." +- **V0's second half** (Cursor, PLAN.md): "V0’s second clause (`hireWorkforce` enumeration) is still manual `rg` — not wrong, but unlike the `WORKER.md` totality proof. *Optional follow-up:* small census sibling under `poc/` if you want symmetric evidence before P4." +- **One owner for the check mapping** (Cursor review): "BR “Proved by” and PLAN V-ids duplicate the same mapping (pick one owner)." +- **Reuse, don't re-derive** (Cursor review): "Production implementation should reuse existing workforce/orchestration paths (`readDeclaredFlow`, `discoverWorkforceCode` per root) rather than re-deriving heuristics from the POC." + +## Follow-ups + +- FIX-1798 removes collection cardinality and owner pins once P4 lands. +- If a host ever needs a session linked before any flow code runs, a server-only field on the + session record (the epic's D3, *what would change my mind*). diff --git a/specs/issues/FIX-1788/SPEC.md b/specs/issues/FIX-1788/SPEC.md new file mode 100644 index 0000000000..b2d013d21b --- /dev/null +++ b/specs/issues/FIX-1788/SPEC.md @@ -0,0 +1,111 @@ +# FIX-1788 · A worker is a private resource its owner holds, run by the shared flow it names + +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +## Six people, before and after + +| 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 | +| **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 that starts from 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`) | Sends to the flow the worker names (`agent`) and names the worker. The server links the session to it once | +| **runs several workers on one flow** | Each copy keeps its own private memory | Each worker still keeps its own, on the one shared copy | +| **upgrades a deployment that has hired workers** | n/a | One operator step carries each hire, its memory and its conversations to its owner. Nothing is deleted ([D1](DECISIONS.md#d1), [D2](DECISIONS.md#d2)) | + +This is the epic's spine ([FIX-1786](../../epics/FIX-1786/SPEC.md), ER-1): privacy by +construction, so the coordinator, the library and projects build on workers that are already +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. Every +hire made before the upgrade comes across to its owner.** + +| 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 | +| **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's link can be seeded, changed, or set to a worker on another flow · two of Alice's workers share a memory cell · a second process needed a restart to see a hire · the upgrade ran on a store this branch wrote, not one today's `main` wrote · Workforce still registers a copy per worker or sets a pin | + +```mermaid +flowchart LR + S["one app · two users of one org · two processes on one store"] --> A["leg a · Alice forks, hires, talks"] + S --> B["leg b · Bob reaches for Alice's workers"] + O["a store today's main wrote"] --> C["leg c · the upgrade step"] + A -->|"one copy per flow · own memory · seen without restart"| P["PASS · the goal is met"] + B -->|"refused every time"| P + C -->|"each hire with its owner, nothing deleted"| P + X["control · workers at org scope"] -.-> B + B -.->|"under the control"| F["must FAIL · Bob reads Alice's worker"] +``` + +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. + +| 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's fork, her own hire and a standard worker each answer as their 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 opening her session, reading her worker, naming it on a turn, and seeding a link through the session create are each refused; Alice linking a session to her worker on another flow, or relinking one, is refused. c: on a store today's `main` wrote, her owned hire, its note and its conversation continue; an org-wide hire she used is hers and Bob, who never used it, has none | +| **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. Leg c's store is written by today's code, not this branch's | +| **Control that must fail** | `GOAL_CONTROL=org-scoped-workers`: leg b FAILS on *Bob reads Alice's worker*. `GOAL_CONTROL=caller-link`: leg b FAILS on *a seeded link runs her other worker*. Today's `main`: legs a and b FAIL | + +## What changes + +![Two panels, today and after. Today each hire registers its own copy of a flow, carrying a pin and its configuration, and a session runs on that copy. After, one copy per flow; each worker is a row its owner holds, or a standard worker read from the files; a session names its worker once and loads it on every turn](figures/what-changes.svg) + +On the left, a worker is a registered copy. On the right, it is data, and the copy is shared. + +**What an app writes to talk to a worker:** + +```diff +- clients.actions("acme.~alice.researcher").sendAction("run", { message }, { sessionId }) ++ clients.actions("agent").sendAction("run", { message, worker: "researcher" }, { sessionId }) ++ // the first turn links the session to the caller's researcher; the server checks and sets it once +``` + +**What a person writes in `WORKER.md`:** nothing changes. A file is a standard worker. + +## How a turn finds its worker + +```mermaid +flowchart LR + T["a turn · names a worker"] --> L["the link · set once"] + L -->|"readable by the session's user · on this flow"| K["server-owned session state"] + K --> 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"] +``` + +The link is the one place a session meets a worker, and every path that opens a session passes +it: a person's turn, a task, a mailbox post. + +## What stays as it is + +- A worker's `flow:` and its default to `agent`. `WORKER.md` files are unchanged. +- Sessions stay private to one user; engine session ownership is unchanged. +- Flow instances and owner pins stay in the engine, deprecated; [FIX-1798](https://linear.app/fixpoint-labs/issue/FIX-1798) removes them. +- `seat*` names and `hireWorkforce`. FIX-1796 renames them with the docs. +- Mailboxes keep working until FIX-1792 replaces them. + +## Sign off + +**[The goal](#the-goal-and-how-well-know-its-met), at that size:** private workers, one copy per +flow, hires without a restart, and every old hire carried to its owner. If wrong: we close the +privacy hole and leave a deployment's existing workers behind. + +1. **[D1](DECISIONS.md#d1) · Old hires, their memory and their conversations move in one operator + step.** If wrong: users wait on an operator after an upgrade. +2. **[D2](DECISIONS.md#d2) · A hire made for the whole org goes to each member who used it.** If + wrong: copies a team didn't expect, or a worker someone relied on gone. + +**Open, the one to weigh** (full ask in [DECISIONS.md](DECISIONS.md#q1)): + +- **[Q1](DECISIONS.md#q1) · Does a fork copy a standard worker's shared instructions, or keep + following them?** I recommend a copy. If wrong: forks drift from the standard as it improves. + +Feature · `engine`, `workforce`, `orchestration`, `shift-manager` · large · 4 PRs · epic [FIX-1786](../../epics/FIX-1786/SPEC.md) diff --git a/specs/issues/FIX-1788/figures/d1-upgrade-step.svg b/specs/issues/FIX-1788/figures/d1-upgrade-step.svg new file mode 100644 index 0000000000..077377f7a6 --- /dev/null +++ b/specs/issues/FIX-1788/figures/d1-upgrade-step.svg @@ -0,0 +1,95 @@ + + + + + + D1 · THE CALL + How do hires made before the upgrade come across? + + + + CHOSEN + One operator step + + INSTEAD OF + Read the old shape at run time + + + + + THE OLD + PER-WORKER COPIES + ▸ DECIDES IT + + + They go, after one run + the shared copy is all that's left + − + Kept alive for good + the machinery FIX-1798 removes + + + UNTIL IT RUNS + − + Old hires wait + the boot says how many + + + Old hires work at once + no wait + + + + WHAT AN OPERATOR + DOES + − + Runs one step + beside FIX-1790's, same upgrade + + + Nothing + no step to run + + + + + LOCKS IN + One step per deployment with hires + nothing deleted; safe to run twice + + + + FLIPS IF + A deployment has no operator + then the move runs on a user's first load + + diff --git a/specs/issues/FIX-1788/figures/d2-org-wide-hire.svg b/specs/issues/FIX-1788/figures/d2-org-wide-hire.svg new file mode 100644 index 0000000000..fbaf72a18c --- /dev/null +++ b/specs/issues/FIX-1788/figures/d2-org-wide-hire.svg @@ -0,0 +1,96 @@ + + + + + + D2 · THE CALL + Where does a worker hired for the whole org go? + + + + CHOSEN + A copy for each member who used it + + INSTEAD OF + Nobody's, until an operator names one + + + + + WHAT EACH PERSON + ALREADY HAD + ▸ DECIDES IT + + + Kept, and nothing new + their conversations and memory + − + Stops for everyone + until an operator acts + + + HOW MANY + WORKERS + − + One per member who used it + each changes on its own + + + One, kept whole + under its named owner + + + + OPERATOR + WORK + + + None + the step reads the sessions + − + Name an owner, per hire + by hand + + + + + LOCKS IN + One worker becomes several + the old row stays, for the library later + + + + FLIPS IF + Teams relied on one shared memory + then hold the hire for the operator + + diff --git a/specs/issues/FIX-1788/figures/open-fork.svg b/specs/issues/FIX-1788/figures/open-fork.svg new file mode 100644 index 0000000000..b46f5a3687 --- /dev/null +++ b/specs/issues/FIX-1788/figures/open-fork.svg @@ -0,0 +1,96 @@ + + + + + + Q1 · OPEN + When a user forks a standard worker, does the fork copy its instructions or follow them? + + + + RECOMMENDED + A copy + + INSTEAD OF + Follow the standard worker + + + + + WHAT CHANGES + UNDER THE OWNER + ▸ DECIDES IT + + + Nothing they didn't edit + the library's rule + − + Every fork, on a file edit + with the forker's access + + + AFTER THE STANDARD + IMPROVES + − + Stale until re-forked + the owner forks again + + + Picked up at once + edits kept on top + + + + HOW A TURN + READS IT + + + One configuration + the row + − + The file plus the user's changes + merged each turn + + + + + LOCKS IN + One rule for every copy a user holds + follow can be added later + + + + FLIPS IF + Users fork to change one setting + while the core changes every week + + diff --git a/specs/issues/FIX-1788/figures/what-changes.svg b/specs/issues/FIX-1788/figures/what-changes.svg new file mode 100644 index 0000000000..f077d188aa --- /dev/null +++ b/specs/issues/FIX-1788/figures/what-changes.svg @@ -0,0 +1,85 @@ + + + + + + + TODAY + AFTER + + + + Each hire registers its own copy of a flow + with a pin and its configuration, in every process + + + + A session runs on that copy + at acme.~alice.researcher + + + + A worker is data + the owner's row, or a file + + One copy per flow + agent, coordinator, … + + + + A session names its worker once + the server links it; every turn loads the worker + + + A WORKER HIRED FOR THE WHOLE ORG + Every member can reach it + Belongs to one user; nobody else reaches it + + + + A HIRE OR FIRE, SEEN BY ANOTHER PROCESS + After that process restarts + On its next turn + + + + A USER WANTS THEIR OWN VERSION OF A STANDARD WORKER + Edit the file and restart, for everyone + Fork it into a worker of their own + + + + WHICH WORKER A SESSION RUNS + Fixed by the copy's address + Set once by the server; a caller can't seed it + + + + TWO WORKERS ON ONE FLOW, EACH WITH PRIVATE NOTES + Each reads only its own + Each reads only its own, on the one copy + kept per worker, not per copy + + diff --git a/specs/issues/FIX-1788/poc/flow-inventory/README.md b/specs/issues/FIX-1788/poc/flow-inventory/README.md new file mode 100644 index 0000000000..6c629a2c19 --- /dev/null +++ b/specs/issues/FIX-1788/poc/flow-inventory/README.md @@ -0,0 +1,63 @@ +# POC · which flows the repo's workers name + +Retained evidence for [FIX-1788](../../SPEC.md). Not production code: nothing imports it, it +has no package manifest, and it is outside default build, test, lint and knip discovery +([specs/README.md](../../../../README.md)). + +## The question + +FIX-1788 makes every flow a worker can name one shared copy. Which flows is that, across the +repo's `WORKER.md` files, and where is each one defined? The epic asked the spec to list them +rather than say "about two dozen". + +## How to run it + +```bash +node specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs # PASS, the table +CONTROL=drop-one node specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs # must FAIL, exit 1 +``` + +No install needed. It reads `git ls-files`, so it sees tracked files only. + +## What it checks + +- **Totality.** Every tracked `WORKER.md` outside `specs/` is classified exactly once: under the + flow its `flow:` names, or under `agent` when it names none. The count is checked against + `git ls-files`. The control drops one file from classification, and the check must fail. +- **Where each flow is defined.** Three static rules: `kind: ""` in a source file, a + `*KIND = ""` constant, or the file-per-flow convention + `workforce/flows/workers/.{ts,mts,tsx}`. Test files and `specs/` are excluded. + +## What was observed + +On `fbecfe6f2`: **94 files, 23 flows, PASS**. The control exits 1 with `classified 93 of 94`. + +| Flow | Files | Flow | Files | +|---|---|---|---| +| `agent` (built in; 20 files name no flow) | 23 | `intake` | 3 | +| `probe` | 10 | `lead` | 3 | +| `seat` | 9 | `audit` | 2 | +| `asker` | 7 | `desk-clerk` | 2 | +| `builder` | 5 | `em` | 2 | +| `request-triage` | 5 | `worker` | 2 | +| `custom-agent` | 4 | `legacy-desk` · `note` · `planner` · `request-triage-legacy` | 1 each | +| `desk` | 4 | `ghost` · `note-taker` · `reviewer` | 1 each | +| `coder` | 3 | `coordinator` | 3 | + +Four names have no static definition. Three are refusal fixtures that name a flow nobody +registers on purpose (`ghost`, `note-taker`, `reviewer`), and they stay refusals. `lead` is +defined at run time from its own file's `flow:` value +(`goals/shift-manager/it-shows-who-is-on-shift/lab/lab.mts`). + +## What it means + +Every defined name above is a flow that FIX-1788 registers once, as a shared copy, in place of +one copy per worker. The conversion is one change at the hire, not 23 changes: each flow is +already defined once and handed to the hire by name. `legacy-desk` and +`request-triage-legacy` are the "no contract" fixtures and stay refused. + +## What it doesn't cover + +Flows an app hands the hire with no `WORKER.md` naming them (a runtime hire's kinds, say). +`PLAN.md` → V0 finds those at implement time from every `hireWorkforce` call. Files under +`specs/` are retained POC evidence and are not converted. diff --git a/specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs b/specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs new file mode 100644 index 0000000000..1f7af67bb6 --- /dev/null +++ b/specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs @@ -0,0 +1,98 @@ +// FIX-1788 · flow inventory — retained spec evidence, not production code. +// +// Re-derives the factual base the spec rests on: which flows the repo's +// WORKER.md files name, how many files name each, and where each flow is +// defined. Every flow listed here becomes one shared copy under FIX-1788. +// +// Totality: every tracked WORKER.md outside specs/ is classified exactly once, +// checked against an independent count from `git ls-files`. +// Negative control: CONTROL=drop-one leaves one file unclassified, and the +// totality assertion must fail. +// +// Run: node specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs + +import { execFileSync } from "node:child_process"; +import { readFileSync } from "node:fs"; + +const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim(); +const tracked = (pattern) => + execFileSync("git", ["ls-files", "--", pattern], { cwd: root, encoding: "utf8" }) + .split("\n") + .filter(Boolean); + +// Retained specs are design evidence; their fixtures are not converted. +const inScope = (path) => !path.startsWith("specs/"); + +const workerFiles = tracked("**/WORKER.md").filter(inScope); +const sources = tracked("*.ts") + .concat(tracked("*.mts"), tracked("*.tsx")) + .filter(inScope) + .filter((path) => !/\.(test|spec)\.tsx?$/.test(path)); + +// A file that names no flow runs on the built-in agent flow. +const DEFAULT_FLOW = "agent"; + +function flowOf(path) { + const text = readFileSync(`${root}/${path}`, "utf8"); + const front = /^---\n([\s\S]*?)\n---/.exec(text); + const line = front?.[1].split("\n").find((l) => /^flow:\s*/.test(l)); + if (line === undefined) return DEFAULT_FLOW; + return line.replace(/^flow:\s*/, "").replace(/^["']|["']$/g, "").trim(); +} + +const byFlow = new Map(); +let classified = 0; +const files = process.env.CONTROL === "drop-one" ? workerFiles.slice(1) : workerFiles; +for (const path of files) { + const flow = flowOf(path); + if (!byFlow.has(flow)) byFlow.set(flow, []); + byFlow.get(flow).push(path); + classified += 1; +} + +// Where a flow is defined: a source file declaring `kind: ""`; a file +// under the convention `workforce/flows/workers/.{ts,mts,tsx}`, whose +// basename is the flow's name; or, for the built-in, the AGENT_KIND constant. +const sourceText = new Map(sources.map((path) => [path, readFileSync(`${root}/${path}`, "utf8")])); +function definedIn(flow) { + const quoted = new RegExp(`kind:\\s*["'\`]${flow.replace(/[-]/g, "\\-")}["'\`]`); + const byConvention = new RegExp(`/flows/workers/${flow.replace(/[-]/g, "\\-")}\\.(ts|mts|tsx)$`); + const byConstant = new RegExp(`[A-Z_]*KIND\\s*=\\s*["'\`]${flow.replace(/[-]/g, "\\-")}["'\`]`); + const hits = []; + for (const [path, text] of sourceText) { + if (quoted.test(text) || byConstant.test(text) || byConvention.test(path)) hits.push(path); + } + if (flow === DEFAULT_FLOW) { + for (const [path, text] of sourceText) { + if (/export const AGENT_KIND = "agent"/.test(text)) hits.push(path); + } + } + return hits; +} + +const rows = [...byFlow.entries()] + .map(([flow, paths]) => ({ flow, files: paths.length, defined: definedIn(flow), paths })) + .sort((a, b) => b.files - a.files || a.flow.localeCompare(b.flow)); + +console.log(`WORKER.md files in scope: ${workerFiles.length} (specs/ excluded)`); +console.log(`Distinct flows named: ${rows.length}\n`); +console.log("| Flow | Files | Defined in |"); +console.log("|---|---|---|"); +for (const row of rows) { + const where = row.defined.length === 0 ? "**no definition found**" : row.defined.slice(0, 3).join("
"); + const more = row.defined.length > 3 ? ` (+${row.defined.length - 3})` : ""; + console.log(`| \`${row.flow}\` | ${row.files} | ${where}${more} |`); +} + +const undefinedFlows = rows.filter((row) => row.defined.length === 0); +if (undefinedFlows.length > 0) { + console.log("\nFlows with no definition (each WORKER.md that names one):"); + for (const row of undefinedFlows) for (const path of row.paths) console.log(` ${row.flow}: ${path}`); +} + +// Totality: classified must equal the independent count. +if (classified !== workerFiles.length) { + console.error(`\nFAIL · totality: classified ${classified} of ${workerFiles.length} WORKER.md files`); + process.exit(1); +} +console.log(`\nPASS · totality: ${classified} of ${workerFiles.length} WORKER.md files classified`);