From 98cdf2ec13bc8d7a5a3720bdfab2c082f8cac849 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 19:53:44 +0000 Subject: [PATCH 1/5] spec(FIX-1786): record Q1 (the list), no engine rule on org scope, link set at create Post-merge amendment to the retained epic set, from Jake's answers at FIX-1789's spec gate (#2811) and on FIX-1788's spec (#2812): - Q1 decided: a worker flow is declared on the list the installation keeps, checked at registration by exported checks, standard-only per entry. Not a defineWorkerFlow() wrapper. New decided figure q1-worker-flow-list.svg replaces open-worker-contract.svg. ER-24 met for Q1. - FIX-1789's Q2: no engine rule on org-scope writes; D3 stays three. ER-2, ER-11, SPEC and the concept callout say the privacy promise covers a worker's own state and user-scoped data; writtenBy is as trustworthy as the registered flow's code. - D3 change 3: the worker link is a server-only field set and checked at session create; no action names a worker. Still the third change. - "seat" removed from prose (Jake, #2810); code identifiers kept. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV --- specs/epics/FIX-1786/BUSINESS-RULES.md | 10 +- specs/epics/FIX-1786/DECISIONS.md | 109 +++++++++-------- specs/epics/FIX-1786/EVOLUTION.md | 2 +- specs/epics/FIX-1786/PLAN.md | 16 +-- specs/epics/FIX-1786/SPEC.md | 23 ++-- specs/epics/FIX-1786/concept/CONCEPT.md | 2 +- .../FIX-1786/figures/open-worker-contract.svg | 95 --------------- .../FIX-1786/figures/q1-worker-flow-list.svg | 114 ++++++++++++++++++ .../poc/singleton-worker-link/README.md | 4 +- 9 files changed, 204 insertions(+), 171 deletions(-) delete mode 100644 specs/epics/FIX-1786/figures/open-worker-contract.svg create mode 100644 specs/epics/FIX-1786/figures/q1-worker-flow-list.svg diff --git a/specs/epics/FIX-1786/BUSINESS-RULES.md b/specs/epics/FIX-1786/BUSINESS-RULES.md index a55e56f754..9102f6b937 100644 --- a/specs/epics/FIX-1786/BUSINESS-RULES.md +++ b/specs/epics/FIX-1786/BUSINESS-RULES.md @@ -11,8 +11,8 @@ seven rules explains is a bug in the model. | # | Rule | Owner | Checked at | |---|---|---|---| -| ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's link to its worker is set by trusted code, never by a caller, in session state the public create can't seed ([D3](DECISIONS.md#d3)), and a forged link reads nothing. A worker's private state is keyed by the worker, not the flow, and today's per-seat cells move to it (BP-030) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure | -| ER-2 | A flow runs workers only when it is a registered worker flow that meets the contract: it composes `workerConfigSchema()`, has a door, and keeps a worker's state private. A flow can be standard-only. Where an author declares it, a list the installation keeps or a `defineWorkerFlow()` wrapper, is chosen at FIX-1789's spec gate and binds once this epic records it ([Q1](DECISIONS.md#q1)); until then no other child names a shape. A worker's configuration is stored data: its tools, skills and packages are names, resolved against what the installation registers when a session loads the worker. A flow reads the running worker's configuration per run, never from `ctx.flow.config`, which a singleton holds once for every worker and keeps for the flow's own settings | FIX-1789 decides · FIX-1788, FIX-1791 consume | FIX-1788's spec review · the closure | +| ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's link to its worker is set and checked by the server when the session is created, held where only the server writes, and never changes; no caller and no action names a worker ([D3](DECISIONS.md#d3)), and a forged link reads nothing. A worker's private state is keyed by the worker, not the flow, and today's per-worker cells move to it (BP-030) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure | +| ER-2 | A flow runs workers only when it is a registered worker flow that meets the contract: it composes `workerConfigSchema()`, has a door, and keeps a worker's own state private. That promise covers a worker's own state and user-scoped data, not org scope: org scope is shared with the org by design, and a flow that writes there does so by its author's choice, which the framework doesn't refuse ([D3](DECISIONS.md#d3)); the built-in worker flows keep a worker's own state out of it. A flow is declared on a list the installation keeps, checked at registration by checks a library can call in its own tests, and the installation can keep an entry for standard workers only ([Q1](DECISIONS.md#q1)). A worker's configuration is stored data: its tools, skills and packages are names, resolved against what the installation registers when a session loads the worker. A flow reads the running worker's configuration per run, never from `ctx.flow.config`, which a singleton holds once for every worker and keeps for the flow's own settings | FIX-1789 decides · FIX-1788, FIX-1791 consume | FIX-1788's spec review · the closure | | ER-3 | User-scoped data is kept per (user, org) for every flow. A record stored before reads in one org at most: an operator step moves it to the one org it can be attributed to, and stops with `migration-required` on one it can't. No per-org cell falls back to the cross-org cell, which is the read this rule closes (the owner-pinned cell's rule, [`state-and-scopes.md`](../../../docs/architecture/state-and-scopes.md#the-owner-pinned-cell)). How a record is attributed is FIX-1790's first spec question | FIX-1790 builds · FIX-1788, FIX-1793 consume | FIX-1790's tests · the closure's second-org step | | ER-4 | A coordinator's delegates live in its session state and start from its configuration's defaults. Both paths that change them, the app and the coordinator's own tool, pass one check: a delegate is on the same user's roster. The public create can't seed them ([D3](DECISIONS.md#d3)) | FIX-1791 decides · FIX-1793, FIX-1794, FIX-1792 consume | FIX-1791's tests · the closure | | ER-5 | An answer doesn't trigger routing again, except for a set number of rounds. One answer per delegate per post. Every routing decision is recorded | FIX-1791 builds | FIX-1791's tests · the closure | @@ -21,7 +21,7 @@ seven rules explains is a bug in the model. | ER-8 | A user talks to a project through their own project coordinator session, one per user per project. Rooms are removed | FIX-1793 builds | The closure | | ER-9 | Every session in a chain belongs to the owner of the work. A board drains as its owner, never as whoever triggers it, and only its own drains claim, wake on or settle its rows: two of one owner's sessions never share a ledger. A lineage stops at a flow, so a board whose rows a worker on another flow settles can't be shared down it, and an unpartitioned user-scoped ledger doesn't hold either, since it spans every session its owner has. How such a board stays its own is FIX-1794's first spec question; an answer that changes the task board comes back to this epic ([ER-22](#what-no-child-may-do)) | FIX-1794 decides · FIX-1793 consumes | FIX-1794's tests · the closure's leg b | | ER-10 | Adding a library template copies it into the user's scope. The copy never changes under them; taking an update is their choice | FIX-1795 decides | FIX-1795's tests | -| ER-11 | Everything written to a shared resource names the user, and the worker when one wrote it | FIX-1789 decides · FIX-1793, FIX-1795 consume | FIX-1793's and FIX-1795's spec review | +| ER-11 | Everything written to a shared resource names the user, and the worker when one wrote it. The name is stamped from the session's identity, so a caller can't forge it; it is as trustworthy as the registered worker flow's code, and no doc promises more ([D3](DECISIONS.md#d3)) | FIX-1789 decides · FIX-1793, FIX-1795 consume | FIX-1793's and FIX-1795's spec review | | ER-12 | No retired term is left in a package export, a published page or the glossary. Channel-kind paths and the engine's dispatch "target" stay | FIX-1796 builds · every child consumes | The closure's gap sweep | ## What no child may do @@ -29,7 +29,7 @@ seven rules explains is a bug in the model. | # | Rule | Because | |---|---|---| | ER-13 | Make org optional or loosen org identity | FIX-1442. Per-org user data composes with it | -| ER-14 | Accept a worker flow that doesn't compose `workerConfigSchema()`, or add free-form config, a second registry of workers or a parallel worker store. [Q1](DECISIONS.md#q1)'s worker-flow declaration, a list or a wrapper, registers flows, not workers, and isn't one | The FIX-1367 WorkerConfig lock | +| ER-14 | Accept a worker flow that doesn't compose `workerConfigSchema()`, or add free-form config, a second registry of workers or a parallel worker store. [Q1](DECISIONS.md#q1)'s worker-flow declaration, the list, registers flows, not workers, and isn't one | The FIX-1367 WorkerConfig lock | | ER-15 | Add an agent-memory field or a parallel memory graph, or document a memory layer a flow doesn't keep | Memory layers reuse resource scopes (2026-09-07 lock); FIX-1364's honesty rule. Long-lived session memory is FIX-1775's | | ER-16 | Rely on "owner writes, org reads" before FIX-1793 builds it | It doesn't exist; the 2026-09-23 security lock left it for later | | ER-17 | Grant access from session state or any field a caller supplies: a worker link, a project, a delegate | Retains FIX-1650's ER-23. Access is the engine-recorded owner checked against the resource | @@ -44,7 +44,7 @@ seven rules explains is a bug in the model. | # | Rule | Because | |---|---|---| | ER-23 | No refactor child starts implementation before FIX-1787's merge-first rows land or close; #2759 lands first of them. FIX-1787 blocks each child in Linear | The refactor starts from a known base ([D1](DECISIONS.md#d1)) | -| ER-24 | A cross-cutting question goes to the epic coordinator, never decided in one child. Where a child's gate produces the evidence, as FIX-1789's does for [Q1](DECISIONS.md#q1), the answer binds the set only once a follow-up epic PR records it. After merge, a change is a follow-up PR from `main` | The retained decisions are canonical | +| ER-24 | A cross-cutting question goes to the epic coordinator, never decided in one child. Where a child's gate produces the evidence, the answer binds the set only once a follow-up epic PR records it; met for [Q1](DECISIONS.md#q1), recorded after FIX-1789's gate. After merge, a change is a follow-up PR from `main` | The retained decisions are canonical | | ER-25 | Each child documents its own behaviour, in the new terms, in the same change. FIX-1796 publishes the glossary and removes what is left | Docs move with code (Jake, 2026-10-03; [D4](DECISIONS.md#d4)) | | ER-26 | A PR that depends on another is a GitHub stack, as [`orchestration.md`](../../../docs/contributing/orchestration.md#worktree-branching-base-every-issue-branch-on-fresh-originmain) sets out. Agents never merge implementation PRs | The orchestration contract | | ER-27 | A child that joins the set blocks FIX-1797 from the wake that first sees it | Otherwise the closure could pass before it lands | diff --git a/specs/epics/FIX-1786/DECISIONS.md b/specs/epics/FIX-1786/DECISIONS.md index c56761ac20..dda34978e9 100644 --- a/specs/epics/FIX-1786/DECISIONS.md +++ b/specs/epics/FIX-1786/DECISIONS.md @@ -4,8 +4,8 @@ The calls above any single issue. D1 is the sign-off surface. This epic runs under `epic-em`: D2 to D5 are engineering calls I made and record here, with what would reverse each. Jake -answered Q1 to Q3 on 2026-10-06, and no child reopens them. Q2 and Q3 are decided. Q1's answer -decides who chooses its shape and on what evidence; the shape itself is recorded here once chosen. The +answered Q1 to Q3 on 2026-10-06, and no child reopens them. All three are decided: Q1's shape, +the list, was chosen at FIX-1789's spec gate on its POC and is recorded here. The model itself (workers as resources, delegates in session state, rooms removed, the vocabulary) is decided in the PRD and the [concept](concept/CONCEPT.md), and is not reopened here. @@ -18,9 +18,11 @@ flowchart TD E --> D2["D2 · one coordinator flow, a routing setting"] D2 -.->|"rejected"| X2["coordinator and relay"] E --> D3["D3 · three Layer 1 changes, the rest Layer 2"] + D3 -.->|"rejected"| X3["a fourth · an engine rule on org-scope writes"] E --> D4["D4 · contract and org keys first, terms last"] E --> D5["D5 · a board is a session board unless people track it"] - E --> Q1["Q1 · answered · chosen at FIX-1789's gate, recorded here"] + E --> Q1["Q1 · decided · the list the installation keeps"] + Q1 -.->|"rejected"| XQ1["a defineWorkerFlow wrapper"] E --> Q2["Q2 · decided · private projects are in"] E --> Q3["Q3 · decided · FIX-1774 and FIX-1777 closed into children"] ``` @@ -30,9 +32,9 @@ flowchart TD | | | |---|---| -| **Instead of** | Rename only (FIX-1796 alone) · or fix privacy in place: keep seats, mailboxes and rooms, and narrow the org-locked hire and the boards | +| **Instead of** | Rename only (FIX-1796 alone) · or fix privacy in place: keep hires, mailboxes and rooms, and narrow the org-locked hire and the boards | | **Because** | A rename keeps the hole: an org-locked hire still reaches every member, and a drain still runs as whoever triggers it. A fix in place keeps six parts and three meanings of "shared", and each fix is a special case on a part the target model deletes. The inventory comes first because FIX-1763's mailbox children are in flight; starting under them makes each one a rebase | -| **Locks in** | A refactor across Workforce, the engine (three changes, [D3](#d3)), Shift Manager and the docs. Implementation waits on FIX-1787's merge-first rows. Work built on seats, mailboxes and rooms merges first and is refactored here, or closes | +| **Locks in** | A refactor across Workforce, the engine (three changes, [D3](#d3)), Shift Manager and the docs. Implementation waits on FIX-1787's merge-first rows. Work built on hires, mailboxes and rooms merges first and is refactored here, or closes | **What would change my mind:** no app needing a second user or a worker of its own this year. Then fix the hole in place and rename later. @@ -59,13 +61,14 @@ answer record in one shared module. | | | |---|---| -| **Instead of** | A Layer 1 worker noun with its own store · or per-org user keys faked inside Workforce | -| **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Three things Workforce cannot fake: a scope key, a row rule, session state a caller can't write. [The end-state POC](#what-the-end-state-poc-showed) settled the third: the public create persists a caller's session state, so a link held there accepts the caller's own other worker, and a row only flow code writes outlives a deleted session id | -| **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change whose old records move to one org by an operator step, never read in two ([ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)); (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) session state a flow declares server-owned: the public create refuses caller state for it, and only flow code writes it. The worker link lives there, and so do a coordinator's delegates. FIX-1788 builds it, FIX-1791 consumes it. Flow instances and owner pins get deprecation markers, nothing more. A worker's own key for its private state is Layer 2, FIX-1788's, and so is reading a worker's configuration per run: a generator already resolves its tools per call ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). Any other Layer 1 change comes back to this epic | +| **Instead of** | A Layer 1 worker noun with its own store · or per-org user keys faked inside Workforce · or a fourth change, an engine rule refusing a worker flow's writes to org scope (FIX-1789's Q2) | +| **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Three things Workforce cannot fake: a scope key, a row rule, session state a caller can't write. [The end-state POC](#what-the-end-state-poc-showed) settled the third: the public create persists a caller's session state, so a link held there accepts the caller's own other worker, and a row only flow code writes outlives a deleted session id. No fourth (Jake, 2026-10-06): org scope is shared with the org by design, a worker flow may write there if that is how it is built to work, and the framework can't know when org data is relevant. The built-in worker flows, `agent` and the coordinator, keep a worker's own state out of it | +| **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change whose old records move to one org by an operator step, never read in two ([ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)); (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) session data only the server writes. The worker link takes the form this card's *what would change my mind* anticipated: a server-only field on the session record, set and checked when the session is created, never on a turn; a session's worker can't change, and no action names a worker (Jake, 2026-10-06, on FIX-1788's spec). A coordinator's delegates are held where only the server writes too, and the public create can't seed them. FIX-1788 picks the mechanism and builds it, FIX-1791 consumes it. Flow instances and owner pins get deprecation markers, nothing more. A worker's own key for its private state is Layer 2, FIX-1788's, and so is reading a worker's configuration per run: a generator already resolves its tools per call ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). Any other Layer 1 change comes back to this epic | **What would change my mind:** a second consumer of a worker outside Workforce. Then a worker noun in core earns its place. For (3), FIX-1788's spec needing the link before any flow code -runs, at admission: then a server-only field on the session record instead. +runs, at admission: then a server-only field on the session record instead. That is the form +the link now takes, set at create; it is still the third change, not a fourth. ## D4 · engineering · The contract and per-org keys first; the terms last, with docs moving with code @@ -86,40 +89,36 @@ runs, at admission: then a server-only field on the session record instead. | **Locks in** | FIX-1792 waits on FIX-1793 for the workstream option. The per-board table is FIX-1792's spec. A session board that hands rows to a delegate on another flow can't be shared down the lineage, which stops at a flow, and still stays its own board: never one ledger for all its owner's sessions. FIX-1794 decides how ([ER-9](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) | -## Q1 · answered, shape open · Where an author says "this flow runs workers" is chosen at FIX-1789's spec gate, on a POC of both, and recorded here - -**Decided:** who chooses and on what evidence. **Not yet decided:** list or wrapper. - -**Jake, 2026-10-06:** not decided at epic level. FIX-1789's spec builds both shapes side by side -in a spec-poc, a list the installation keeps and a `defineWorkerFlow()` wrapper, and the call is -made on that evidence at FIX-1789's spec gate. Jake leans to the wrapper for contract integrity: -it makes a flow account for every requirement a worker flow has. Seeing how the list keeps code -and holds the contract may change that. The epic recommended the list before this answer; it no -longer recommends either. - -- **What both shapes must hold.** [ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)'s - contract: the flow composes `workerConfigSchema()`, has a door, keeps a worker's state private, - and can be kept for standard workers only. [ER-14](BUSINESS-RULES.md#what-no-child-may-do): - whichever shape wins registers flows, not workers. -- **What the POC compares.** The figure's rows. Contract integrity: is every requirement checked - where the author writes the flow, or only when the installation registers its list? Authorities: - the wrapper is a marker `worker-config.ts` rejects on purpose today, a second authority over the - schema's rule. Existing flows: the built-in `agent` flow is unchanged under the list and migrates - under the wrapper. Under both: can the private-state rule be checked from what a flow declares, - or does it need a gate around resource writes at run time? -- **How the choice binds the set.** The shape is cross-cutting: FIX-1788's `agent` flow and - FIX-1791's coordinator flow both declare themselves with it. So the winner at FIX-1789's gate - comes back here as a follow-up epic PR that records it in this card - ([ER-24](BUSINESS-RULES.md#how-the-set-is-run)), and it binds once that PR merges. Until then, - FIX-1788's and FIX-1791's specs build to ER-2's contract and name neither shape. Their builds - already wait on FIX-1789 ([D4](#d4)), so nothing re-sequences. -- **What it moves.** If the list wins and is small, FIX-1789 may fold into FIX-1788 - ([D1](#d1)'s collapse trigger). If the wrapper wins, it is a new public export, and FIX-1788 - moves the `agent` flow onto it. - -![Q1, chosen at FIX-1789's spec gate on a POC of both and recorded here: a defineWorkerFlow wrapper, which Jake leans to, beside a list the installation keeps. His reason: contract integrity, every requirement checked where the flow is written. The wrapper's price: a second authority over the schema's rule, and existing flows migrate. The lean flips if the list catches every requirement as surely](figures/open-worker-contract.svg) - -It comes down to contract integrity, Jake's reason for the wrapper, weighed against the second authority it adds. +## Q1 · decided · An author says "this flow runs workers" in a list the installation keeps, not a `defineWorkerFlow()` wrapper + +**Jake, 2026-10-06**, at FIX-1789's spec gate +([#2811](https://github.com/fixpoint-labs/flow-state-dev/pull/2811)), on its POC of both shapes +([`two-shapes`](../../issues/FIX-1789/poc/two-shapes/README.md#what-was-observed)), as this +card had asked. He had leaned to the wrapper for contract integrity; the POC showed the list +holds it as surely. + +- **What it is.** Today's map of flows the installation passes to the hire. Each flow on it is + checked when the installation registers it, against + [ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)'s contract, by checks exported so + a library can call them in its own tests. Standard-only is carried per entry, set by the + installation. +- **What decided it.** Both shapes refused the same flows before any worker ran (S1–S4), so + contract integrity was a tie. The wrapper lost an installation's standard-only setting when it + swapped in a library's `agent`, and needed two definitions of one flow for two installations + (F3, F4). It also refused a flow that meets every requirement but was written by hand: the + second authority `worker-config.ts` rejects on purpose (H1). +- **How it binds the set.** From this record's merge + ([ER-24](BUSINESS-RULES.md#how-the-set-is-run)): FIX-1788's `agent` flow and FIX-1791's + coordinator flow register on the list, and neither moves onto a new export. + [ER-14](BUSINESS-RULES.md#what-no-child-may-do) holds: the list registers flows, not workers. +- **What it leaves.** A wrapper may come later as sugar over the list, with no mark. + [D1](#d1)'s collapse trigger doesn't fire: FIX-1789's spec found the contract is more than a + registration list (three checks, attribution, moving `agent`'s skills drawer off org scope), so + it keeps its own issue. + +![Q1, decided at FIX-1789's spec gate on a POC of both: a list the installation keeps, chosen, beside a defineWorkerFlow wrapper. Decides it: who sets standard-only, kept by the installation per entry and lost under the wrapper when an installation swaps in a library's agent. Contract integrity is a tie. The list's price: a library catches a broken flow only if it calls the exported check. Flips if standard-only is a property of the flow](figures/q1-worker-flow-list.svg) + +It comes down to who sets standard-only: under the wrapper, an installation can't keep its own policy. ## Q2 · decided · Private projects are in, and FIX-1763's "projects stay org-level" fence is lifted @@ -189,8 +188,13 @@ engine rule. The closure only checks. library from merging ([ER-30](BUSINESS-RULES.md#the-closure)). From review (Jake). - **Private projects are proved.** Leg b makes one and Bob can't reach it; otherwise ER-7's private half would ship unchecked. From review (Jake, Cursor); unconditional since Q2. -- **ER-14 forbids a second registry of workers**, not Q1's worker-flow declaration, whether a - list or a wrapper. From review. +- **ER-14 forbids a second registry of workers**, not Q1's worker-flow declaration, the list. + From review. +- **A shared entry's `writtenBy` is as trustworthy as the worker flow that wrote it.** With no + engine rule ([D3](#d3)), FIX-1789's shared-write helper stamps it from the session's identity; + a caller can't forge it, but the registered flow's own code could, and no doc may promise + otherwise ([ER-11](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). From FIX-1789's + gate, an engineering call. - **A worker names the flow that runs it.** An installation has many worker flows (the built-in agent, the coordinator, the app's own), each one singleton copy that every worker naming it shares. Making flows singletons doesn't put every worker on `agent` ([ER-1](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). @@ -223,7 +227,7 @@ engine rule. The closure only checks. through the public create, and a flow-owned row outlives a deleted session id. A user's workers share every `flowIsolation` cell. A lineage board can't reach a worker on another flow. - **Changed:** [D3](#d3)'s third Layer 1 change is definite, as server-owned session state. - FIX-1788 also keys a worker's private state by the worker and moves the per-seat cells + FIX-1788 also keys a worker's private state by the worker and moves today's per-worker cells ([ER-1](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). A board whose rows cross a flow can't use its lineage ([ER-9](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt), FIX-1794; [D5](#d5)); the POC's answer, the owner's user scope, was struck in review round 2. The FIX-1788 @@ -256,7 +260,12 @@ engine rule. The closure only checks. FIX-1788 or FIX-1791 names a shape, because both declare their flows with it (Codex); the "fast follow" Jake expects for the shared half is asked at FIX-1793's spec gate, so it has an owner (the second look); ER-26 points at the orchestration contract's GitHub stacks. - -**Open: none needing an answer now.** Two asks have a set place. Q1's shape is chosen at -FIX-1789's spec gate and recorded here before FIX-1788 or FIX-1791 names one. Whether the shared -half stays in the MVP is asked at FIX-1793's spec gate ([Q2](#q2)). +- **FIX-1789's gate (Oct 6)**, in a third follow-up PR: Q1 is the list, on FIX-1789's POC (#2811), + and ER-24 is met for it. FIX-1789's open call on an engine rule for org-scope writes is no: D3 + stays three, and ER-2 and ER-11 say the privacy promise covers a worker's own state and + user-scoped data, not org scope. From FIX-1788's spec (#2812): D3's third change holds the worker +link in a server-only field set at create, so no action names a worker. "Seat" left the prose +here, one name for one thing (Jake, #2810). + +**Open: none needing an answer now.** Whether the shared half stays in the MVP is asked at +FIX-1793's spec gate ([Q2](#q2)). diff --git a/specs/epics/FIX-1786/EVOLUTION.md b/specs/epics/FIX-1786/EVOLUTION.md index 13b6686ffc..fc0614ed83 100644 --- a/specs/epics/FIX-1786/EVOLUTION.md +++ b/specs/epics/FIX-1786/EVOLUTION.md @@ -33,7 +33,7 @@ because the Architect named them. | **A project room is a members' conversation on the mailbox flow**: `join`, `post`, `read` and `answer` entries on every mailbox kind, through each member's talk session; stored in `room-lines`, `room-seq`, `room-answers` and `room-deliveries` (`packages/workforce/src/projects/talk.ts`, `collections.ts`). It is not a passive shared record | **Removed** | The project coordinator session, FIX-1793 | | **Runtime mailbox boards are org-scoped task ledgers**: one per declared board, minted `.` (usually `.tasks`), scope hardcoded to `org` in `mailboxBoardLedger` and read together through `mailboxTaskLists` (`packages/workforce/src/mailbox/mailbox-board.ts`). The session's `userId` doesn't narrow them | **Superseded** | Session boards or workstreams, FIX-1792 and FIX-1794 ([D5](DECISIONS.md#d5)) | | User data sits in the person's cross-org cell, except an owner-pinned instance's, keyed `:~org:` (`sharedUserKey` in `packages/engine/src/stores/scope-keys.ts`) | **Amended** | Per (user, org) for every flow, FIX-1790. Old records move to one org by an operator step or stop with `migration-required`, as the owner-pinned cell's do; none falls back to the cross-org cell (ER-3) | -| A worker names its flow, and each hire mints its own copy of that flow, registered under the worker's id (`HireOptions.kinds`, `hire.ts`). The `agent` flow does it as one kind with many instances (`cardinality: "collection"`, `agent-worker-flow.ts`), each with an owner pin. Its per-seat skills drawer is `flowIsolation: true`, so each seat's cell is keyed by its instance id | **Superseded** | Every worker flow a worker can name becomes one singleton copy; workers that name `agent` become worker resources on its one copy, FIX-1788. On a singleton those cells would be one per user ([the POC](poc/singleton-worker-link/README.md), I1–I2), so FIX-1788 keys them by worker and moves the per-seat cells | +| A worker names its flow, and each hire mints its own copy of that flow, registered under the worker's id (`HireOptions.kinds`, `hire.ts`). The `agent` flow does it as one kind with many instances (`cardinality: "collection"`, `agent-worker-flow.ts`), each with an owner pin. Its per-worker skills drawer is `flowIsolation: true`, so each worker's cell is keyed by its instance id | **Superseded** | Every worker flow a worker can name becomes one singleton copy; workers that name `agent` become worker resources on its one copy, FIX-1788. On a singleton those cells would be one per user ([the POC](poc/singleton-worker-link/README.md), I1–I2), so FIX-1788 keys them by worker and moves today's per-worker cells | | A worker's own post wakes nobody (`seatAuthored`, `mailbox/wake-member-seats.ts`) | **Amended** | Bounded rounds, ER-5, FIX-1791 | | The hired roster is `defineHiredRosterCollection` under `workforce/roster/*` | **Superseded** | The user's worker resources, FIX-1788 | | A fixed turn window, `historyWindow` (`packages/core/src/types/flow.ts`) | **Untouched here** | FIX-1775 | diff --git a/specs/epics/FIX-1786/PLAN.md b/specs/epics/FIX-1786/PLAN.md index f10acf827f..11623aeb72 100644 --- a/specs/epics/FIX-1786/PLAN.md +++ b/specs/epics/FIX-1786/PLAN.md @@ -20,10 +20,10 @@ privacy fix is checked when workers merges, not only at the end (ER-30). The gra | Issue | Route | Consumes | Delivers | Releases | Size | |---|---|---|---|---|---| | **FIX-1787** inventory | inventory, no spec | Every open PR and active issue in the areas | 38 calls: 13 merge first, 13 close, 12 untouched | Every refactor child | Done as a table; its merges are the work | -| **FIX-1789** contract | spec → impl PR | `workerConfigSchema()`, the door · Q1, chosen at its spec gate on a POC of both shapes | Registered worker flows, the private-state rule, standard-only, attribution; a worker's configuration as stored data read per run (ER-2, ER-11) | FIX-1788 | Small, plus the two-shape POC | +| **FIX-1789** contract | spec → impl PR | `workerConfigSchema()`, the door · Q1, decided at its spec gate on its POC of both shapes: the list | Worker flows on the installation's list, checked at registration by exported checks; the private-state rule, standard-only per entry, attribution; a worker's configuration as stored data read per run (ER-2, ER-11) | FIX-1788 | Small, plus the two-shape POC | | **FIX-1790** per-org data | spec → impl PR | The engine's user key | User data per (user, org); old records moved to the one org they belong to by an operator step, or refused, never read in two (ER-3) | FIX-1788 | Medium: a persisted key every flow uses, and its migration | -| **FIX-1788** workers | spec → impl PRs | ER-2 · ER-3 · projected collections · Q1's shape, once recorded | Worker resources on singleton flows, standard projection, fork, deprecations; the session link in server-owned session state (D3's third change); a worker's own key for its private state, with today's per-seat cells moved (ER-1) | FIX-1791 · FIX-1795 | Large | -| **FIX-1791** coordinator | spec → impl PRs | ER-1 · FIX-1779's join and leave · FIX-1774's legs · Q1's shape, once recorded | The coordinator flow, delegates, four policies, the records (ER-4, ER-5); the chief of staff as a standard coordinator | FIX-1793 · FIX-1794 · FIX-1792 | Medium to large | +| **FIX-1788** workers | spec → impl PRs | ER-2 · ER-3 · projected collections · Q1's list | Worker resources on singleton flows, standard projection, fork, deprecations; the session link, set and checked at create where only the server writes (D3's third change); a worker's own key for its private state, with today's per-worker cells moved (ER-1) | FIX-1791 · FIX-1795 | Large | +| **FIX-1791** coordinator | spec → impl PRs | ER-1 · FIX-1779's join and leave · FIX-1774's legs · Q1's list | The coordinator flow, delegates, four policies, the records (ER-4, ER-5); the chief of staff as a standard coordinator | FIX-1793 · FIX-1794 · FIX-1792 | Medium to large | | **FIX-1795** library | spec → impl PR | ER-1's write path | Templates and copies, model variants (ER-10) | FIX-1796 | Medium | | **FIX-1793** projects | spec → impl PRs | ER-4 · ER-3 · FIX-1762's locks · Q2 | Private and shared projects (Q2); workstream resources, the row rule, the project coordinator; rooms and Shift Manager's Stream tab removed (ER-7, ER-8) | FIX-1792 | Large: about 2,200 lines out, one engine rule in | | **FIX-1794** chain | spec → impl PR | ER-4's delegates · FIX-1778 · FIX-1780's hand-off rule · FIX-1777's rule | Tasks down the owner's boards, drained as the owner; a board whose rows cross a flow stays its own board, never one ledger for the owner's sessions (ER-9) | FIX-1796 | Medium; larger if that needs a task-board change | @@ -40,9 +40,9 @@ moves to `packages/shift-manager` with #2759, and every reference here means tha ## What unblocks what, from here -1. **This spec merges** → every child's spec can start. Builds still wait on step 2. FIX-1788's - and FIX-1791's specs name a worker-flow declaration only after FIX-1789's gate chooses one and - a follow-up here records it (Q1). +1. **This spec merges** → every child's spec can start. Builds still wait on step 2. FIX-1789's gate + chose the list, recorded here (Q1), so FIX-1788's and FIX-1791's specs register their flows on + it. 2. **The inventory's merge-first rows land or close**, #2759 first, then the PRs that rebase on it → FIX-1789 and FIX-1790 builds start. 3. **Both merge** → FIX-1788 builds. It merges → FIX-1791 and FIX-1795 build, and FIX-1797 runs @@ -63,10 +63,10 @@ moves to `packages/shift-manager` with #2759, and every reference here means tha |---|---|---| | The `agent` flow (`agent-worker-flow.ts`) | FIX-1788, FIX-1791, FIX-1794 | FIX-1788 lands the singleton shape first; the others build on it | | The hire and roster write path | FIX-1788, FIX-1795 | FIX-1788 owns the write; the library calls it | -| The worker-flow declaration | FIX-1789, FIX-1788, FIX-1791 | FIX-1789's gate chooses it (Q1); the epic records it; the other two name it only after | +| The worker-flow declaration | FIX-1789, FIX-1788, FIX-1791 | The installation's list (Q1, decided). FIX-1789 builds it and its checks; the other two register on it | | The user scope key | FIX-1790, FIX-1788, FIX-1793 | FIX-1790 merges first; nothing user-scoped ships before it | | A board whose rows cross a flow | FIX-1794, FIX-1791, FIX-1792, FIX-1793 | FIX-1794 decides how it stays its own board (ER-9); the others build their boards on that answer | -| Server-owned session state | FIX-1788, FIX-1791 | FIX-1788 lands it with the link; the coordinator keeps its delegates there | +| Session data only the server writes | FIX-1788, FIX-1791 | FIX-1788 lands it with the link, set at create; the coordinator keeps its delegates where only the server writes | | The mailbox flow and its files | FIX-1791, FIX-1792 | FIX-1791 ships the coordinator beside the mailbox flow; FIX-1792 converts every file and removes the mailbox flow in one change | | `packages/shift-manager` | FIX-1788, FIX-1793, FIX-1796 | The second lander adapts; the TEAMS view reads worker resources, the Project view the coordinator session | | `apps/docs/docs/workforce/` | Every child | Each child its own page ([DOCS.md](DOCS.md#ownership)); FIX-1796 the overview and glossary | diff --git a/specs/epics/FIX-1786/SPEC.md b/specs/epics/FIX-1786/SPEC.md index 0b017ffdcd..faaf61dbf7 100644 --- a/specs/epics/FIX-1786/SPEC.md +++ b/specs/epics/FIX-1786/SPEC.md @@ -6,7 +6,7 @@ | A team that… | Today | After this epic | |---|---|---| -| **builds an app on Workforce** | Learns seats, mailboxes, rooms, talk sessions, flow instances and owner pins, and three meanings of "shared" | Learns one rule: everything is private to one user, and only shared resources are shared. Then workers, each naming the flow that runs it, coordinators and workstreams | +| **builds an app on Workforce** | Learns hires, mailboxes, rooms, talk sessions, flow instances and owner pins, and three meanings of "shared" | Learns one rule: everything is private to one user, and only shared resources are shared. Then workers, each naming the flow that runs it, coordinators and workstreams | | **runs an org with more than one user** | A hire locked to the org alone is reachable by every member. Mailbox boards are org rows no session narrows, and a drain runs as whoever triggers it | A worker belongs to one user and acts as them. Shared work enters a roster only through its owner | | **wants a worker of their own** | Edits a `WORKER.md` and restarts, or gets an org hire every member can reach | Forks a standard worker, or copies a template from the org's library. The copy is theirs alone | | **hands work between workers** | A mailbox's members are fixed when it opens, and workers can't answer each other | A coordinator routes by judgment, best fit, round robin or everyone, to delegates it can add and remove | @@ -14,7 +14,7 @@ **Why now.** The model is hard to hold in your head, even for the person who designed it, and explaining it better won't fix that ([concept](concept/CONCEPT.md#why-this-doc)). Every child -built on seats, mailboxes and rooms adds to the bill: four of FIX-1763's children build on +built on hires, mailboxes and rooms adds to the bill: four of FIX-1763's children build on mailboxes right now, and the inventory found 38 items on the refactor's ground. The framework is pre-1.0 and every `MAILBOX.md` lives in this repo, so a loud refusal costs less today than two formats later. The inventory (FIX-1787) runs first, so the refactor starts from a known base. @@ -26,6 +26,10 @@ a coordinator) on shared singleton flows, and work one shared project through wo each own, with every task running as its owner and nothing of one user's reachable by the other except what was written to a shared resource.** +Org scope counts as shared. A worker flow may write there if that is how it is built to work, +and the framework doesn't refuse it; the built-in worker flows keep a worker's own state out of +it ([D3](DECISIONS.md#d3), [ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). + | Is it the right goal? | | |---|---| | **The real need** | Jake's PRD: one rule set, where everything is private to one user and the only shared things are shared resources. The model is the problem, not its docs. Under it sits a hole: an org-locked hire reaches every member | @@ -74,7 +78,7 @@ blocked by FIX-1787 ([ER-23](BUSINESS-RULES.md#how-the-set-is-run)). | Issue | What it delivers | Why the set needs it | Status | |---|---|---|---| | [FIX-1787](https://linear.app/fixpoint-labs/issue/FIX-1787) · inventory | A merge, close or untouched call for every open PR and active issue in the areas the refactor changes | The refactor starts from its result. Route: inventory, no spec, user-approved outside this gate | In Review · posted 2026-10-06 [on FIX-1786](https://linear.app/fixpoint-labs/issue/FIX-1786#comment-9e837aa5): 38 items, 13 merge first, 13 close, 12 untouched; its two owner calls answered 2026-10-06 ([Q2](DECISIONS.md#q2), [Q3](DECISIONS.md#q3)) | -| [FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) · worker contract | Registered worker flows, the private-state rule, a standard-only flag | A worker's configuration must name a flow that keeps its state private | Backlog · spec route · [Q1](DECISIONS.md#q1)'s shape is chosen at its spec gate on a POC of both, then recorded in the epic | +| [FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) · worker contract | Registered worker flows on the installation's list, the private-state rule, a standard-only flag per entry | A worker's configuration must name a flow that keeps its state private | Spec merged ([#2811](https://github.com/fixpoint-labs/flow-state-dev/pull/2811)) · [Q1](DECISIONS.md#q1) decided at its gate: the list | | [FIX-1790](https://linear.app/fixpoint-labs/issue/FIX-1790) · user data per org | User-scoped data kept per (user, org), for every flow; records stored before moved to one org or refused | Without it a user's private workers show in every org they belong to | Backlog · spec route | | [FIX-1788](https://linear.app/fixpoint-labs/issue/FIX-1788) · workers as resources | A worker as a user-scoped resource, run by the singleton flow it names; standard workers projected from files; fork; a session link callers can't seed; instances and pins deprecated | The spine: privacy by construction | Backlog · spec route | | [FIX-1791](https://linear.app/fixpoint-labs/issue/FIX-1791) · coordinator flow | Delegates in session state, four routing policies, one answer per delegate, a routing record | Replaces the mailbox with a worker, and fixes its fixed membership | Backlog · spec route · carries FIX-1774's dogfood legs and *not done if* list | @@ -88,8 +92,9 @@ blocked by FIX-1787 ([ER-23](BUSINESS-RULES.md#how-the-set-is-run)). The inventory, nine refactor children and a closure; none of the nine started, and none of the inventory's merge-first PRs has landed. Whether nine is really eight: FIX-1790 could ride in FIX-1788, but it changes a persisted key every flow uses and moves what was stored before by an -operator step, so it keeps its own review. Collapse trigger: if FIX-1789's spec finds the contract -needs only a registration list, it folds into FIX-1788 ([D1](DECISIONS.md#d1)). +operator step, so it keeps its own review. The collapse trigger, FIX-1789's contract needing only +a registration list, didn't fire: its spec found three checks, attribution and a drawer move +([Q1](DECISIONS.md#q1)). ## How the issues flow into each other @@ -136,12 +141,12 @@ resources. If wrong: we rename the parts while a hire still reaches every member If wrong: a refactor that rebuilds under in-flight work, or one nobody needed this year. **Answered by Jake, 2026-10-06.** [Q1](DECISIONS.md#q1) · where an author says a flow runs -workers: chosen at FIX-1789's spec gate on a POC that builds both a list the installation keeps -and a `defineWorkerFlow()` wrapper, then recorded in the epic before FIX-1788 or FIX-1791 names -one; Jake leans to the wrapper. [Q2](DECISIONS.md#q2) · private projects are in and FIX-1763's +workers: a list the installation keeps, not a `defineWorkerFlow()` wrapper, chosen at +FIX-1789's spec gate on a POC of both. [Q2](DECISIONS.md#q2) · private projects are in and FIX-1763's "projects stay org-level" is lifted; FIX-1762's stack merged first. Whether the shared half stays in the MVP is asked at FIX-1793's spec gate. -[Q3](DECISIONS.md#q3) · FIX-1774 and FIX-1777 are closed into FIX-1791 and FIX-1794. Engineering calls I +[Q3](DECISIONS.md#q3) · FIX-1774 and FIX-1777 are closed into FIX-1791 and FIX-1794. At FIX-1789's +gate, no engine rule on org-scope writes: [D3](DECISIONS.md#d3) stays three. Engineering calls I made as EM, for the record: [D2](DECISIONS.md#d2) to [D5](DECISIONS.md#d5). Rules: [BUSINESS-RULES.md](BUSINESS-RULES.md). Order: [PLAN.md](PLAN.md). diff --git a/specs/epics/FIX-1786/concept/CONCEPT.md b/specs/epics/FIX-1786/concept/CONCEPT.md index a96563d8fd..22a5c30598 100644 --- a/specs/epics/FIX-1786/concept/CONCEPT.md +++ b/specs/epics/FIX-1786/concept/CONCEPT.md @@ -10,7 +10,7 @@ > **Where this differs from the epic, the epic binds.** This is the PRD as Jake wrote it; the > epic's [decisions](../DECISIONS.md) and [rules](../BUSINESS-RULES.md) settle what it leaves > open. One coordinator flow with a routing setting ([D2](../DECISIONS.md#d2)). Where an author -> declares a worker flow is [Q1](../DECISIONS.md#q1), whose shape is chosen at FIX-1789's spec gate on a POC of both and recorded in the epic. A workstream is a project entry plus its +> declares a worker flow is [Q1](../DECISIONS.md#q1): a list the installation keeps, chosen at FIX-1789's spec gate on a POC of both. "Keeps a worker's state private" covers a worker's own state and user-scoped data; org scope is shared with the org by design, and the framework doesn't refuse a flow's writes there ([D3](../DECISIONS.md#d3)). A workstream is a project entry plus its > lead's session; `MAILBOX.md` becomes `WORKER.md`; no transcript resource is built, so the > `transcript:` key below isn't either ([decided in review](../DECISIONS.md#decided-in-review-recorded-so-no-child-reopens-them)). > The boards are per [D5](../DECISIONS.md#d5) and [ER-9](../BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt). A worker's diff --git a/specs/epics/FIX-1786/figures/open-worker-contract.svg b/specs/epics/FIX-1786/figures/open-worker-contract.svg deleted file mode 100644 index d7a1204f11..0000000000 --- a/specs/epics/FIX-1786/figures/open-worker-contract.svg +++ /dev/null @@ -1,95 +0,0 @@ - - - - - - Q1 · CHOSEN AT FIX-1789'S SPEC GATE, ON A POC OF BOTH · THE CALL - Where does an author say “this flow runs workers”? - - - - JAKE LEANS - A defineWorkerFlow() wrapper - - ALSO BUILT - A list the installation keeps - - - - - CONTRACT - INTEGRITY - ▸ HIS REASON - + - Checked where the flow is written - a flow can't leave a requirement out - − - Checked apart from the flow - when the installation registers its list - - - AUTHORITIES OVER - THE RULE - − - Two: the schema and a marker - worker-config.ts rejects one today - + - One: today's schema - the list adds flags, not a marker - - - - EXISTING FLOWS - − - The agent flow migrates - a new public export - + - Unchanged - the built-in agent flow keeps working - - - - - SETTLED BY - FIX-1789's spec-poc builds both, side by side - chosen at that gate, recorded in the epic before others use it - - - - THE LEAN FLIPS IF - The list catches every requirement as surely - or the wrapper only duplicates the schema's rule - - diff --git a/specs/epics/FIX-1786/figures/q1-worker-flow-list.svg b/specs/epics/FIX-1786/figures/q1-worker-flow-list.svg new file mode 100644 index 0000000000..d92e8a612f --- /dev/null +++ b/specs/epics/FIX-1786/figures/q1-worker-flow-list.svg @@ -0,0 +1,114 @@ + + + + + + + Q1 · DECIDED AT FIX-1789'S SPEC GATE, ON A POC OF BOTH · THE CALL + Where does an author say “this flow runs workers”? + + + + + CHOSEN + A list the installation keeps + + INSTEAD OF + A defineWorkerFlow() wrapper + + + + + + WHO SETS + STANDARD-ONLY + ▸ DECIDES IT + + + The installation, per entry + kept when it swaps in a library's agent + − + The flow's author + an installation that swaps agent loses its policy + + + + CONTRACT + INTEGRITY + = + The same flows refused + every one before any worker runs + = + The same flows refused + the POC's seven flows, the same verdicts + + + + + A BROKEN FLOW + IN A LIBRARY + − + Caught if the library calls the check + an exported check, in its own tests + + + Caught as its file loads + no installation needed + + + + + AUTHORITIES OVER + THE RULE + + + One: today's schema + a compliant hand-built flow registers + − + Two: the schema and a mark + refuses that flow for lacking the mark + + + + + + LOCKS IN + The list is the declaration, checked at registration + a wrapper may come later as sugar over it, with no mark + + + + + FLIPS IF + Standard-only is a property of the flow + the same in every installation that runs it + + diff --git a/specs/epics/FIX-1786/poc/singleton-worker-link/README.md b/specs/epics/FIX-1786/poc/singleton-worker-link/README.md index 373480e831..1d571640f4 100644 --- a/specs/epics/FIX-1786/poc/singleton-worker-link/README.md +++ b/specs/epics/FIX-1786/poc/singleton-worker-link/README.md @@ -56,7 +56,7 @@ engine shows up here as a red test. | R1 | `record`: delete the session and recreate its id | The new session inherits the old link: `open` to `w2` is refused with `bound to "w1"`. Flow code sees `id`, `userId` and `orgId` on the session, not its lineage or creation time, so it can't tell the two apart | | B1 | Bob in alice's session; the task entry over HTTP | `Session s_a belongs to another user`. The `work` entry isn't a public action (`does not define action "work"`, a 500 today rather than a 404) | | I1 | Two of alice's workers write `flowIsolation: true` memory | **One cell.** It is keyed `(alice, agent-poc)` because a singleton's instance id is its kind; `w2` reads `w1`'s notes | -| I2 | A per-seat cell from today's hire, `(alice, w1)` | Not what the singleton reads. Moving to the singleton strands it | +| I2 | A per-worker cell from today's hire, `(alice, w1)` | Not what the singleton reads. Moving to the singleton strands it | | C1 | A coordinator flow's lineage board hands a row to the agent flow | The child roots its **own** lineage (cross-flow), resolves an empty ledger, runs nothing, and completes. The parent's row stays `in_progress`. A user-scoped ledger crosses flows today (`hand-off-cross-flow.test.ts`) | ## What it means @@ -65,7 +65,7 @@ engine shows up here as a red test. users (X1) but accepts a caller-seeded link to the caller's own other worker (O1). A row only flow code writes refuses that (O2) but outlives the session (R1). Neither holds ER-1. - **A worker's private state needs its own key.** On a singleton, flow isolation separates flows, - not workers (I1), and today's per-seat cells need a move (I2). + not workers (I1), and today's per-worker cells need a move (I2). - **A lineage board stops at a flow boundary** (C1). A coordinator handing a row to an agent-flow worker crosses one every time, so that board can't use its lineage. The owner's user scope, suggested here, was struck in review: that ledger spans every session its owner has. ER-9 keeps From 117516e035af5983dabc38e997639234762c0f28 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 19:59:53 +0000 Subject: [PATCH 2/5] spec(FIX-1786): goal lets org scope cross users; Q1 checklist decided; D3 trigger trimmed Folds review on #2813: - Codex P1: the goal, its leg-c signal, control and sign-off now say org scope may cross users by a flow author's choice; a worker's own state and user-scoped data never do, so no leg fails on a legitimate org write. - Codex P2: CONCEPT's worker-contract checklist item is decided (the list, standard-only per entry, Q1). - Cursor: D3's "what would change my mind" keeps only the real reversal trigger; the singleton-worker-link POC conclusions point at D3/FIX-1788; a broken line break in the history list is fixed. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV --- specs/epics/FIX-1786/DECISIONS.md | 10 ++++------ specs/epics/FIX-1786/SPEC.md | 15 ++++++++------- specs/epics/FIX-1786/concept/CONCEPT.md | 2 +- .../FIX-1786/poc/singleton-worker-link/README.md | 2 ++ 4 files changed, 15 insertions(+), 14 deletions(-) diff --git a/specs/epics/FIX-1786/DECISIONS.md b/specs/epics/FIX-1786/DECISIONS.md index dda34978e9..fa0d436cb0 100644 --- a/specs/epics/FIX-1786/DECISIONS.md +++ b/specs/epics/FIX-1786/DECISIONS.md @@ -66,9 +66,7 @@ answer record in one shared module. | **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change whose old records move to one org by an operator step, never read in two ([ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)); (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) session data only the server writes. The worker link takes the form this card's *what would change my mind* anticipated: a server-only field on the session record, set and checked when the session is created, never on a turn; a session's worker can't change, and no action names a worker (Jake, 2026-10-06, on FIX-1788's spec). A coordinator's delegates are held where only the server writes too, and the public create can't seed them. FIX-1788 picks the mechanism and builds it, FIX-1791 consumes it. Flow instances and owner pins get deprecation markers, nothing more. A worker's own key for its private state is Layer 2, FIX-1788's, and so is reading a worker's configuration per run: a generator already resolves its tools per call ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). Any other Layer 1 change comes back to this epic | **What would change my mind:** a second consumer of a worker outside Workforce. Then a worker -noun in core earns its place. For (3), FIX-1788's spec needing the link before any flow code -runs, at admission: then a server-only field on the session record instead. That is the form -the link now takes, set at create; it is still the third change, not a fourth. +noun in core earns its place. ## D4 · engineering · The contract and per-org keys first; the terms last, with docs moving with code @@ -263,9 +261,9 @@ engine rule. The closure only checks. - **FIX-1789's gate (Oct 6)**, in a third follow-up PR: Q1 is the list, on FIX-1789's POC (#2811), and ER-24 is met for it. FIX-1789's open call on an engine rule for org-scope writes is no: D3 stays three, and ER-2 and ER-11 say the privacy promise covers a worker's own state and - user-scoped data, not org scope. From FIX-1788's spec (#2812): D3's third change holds the worker -link in a server-only field set at create, so no action names a worker. "Seat" left the prose -here, one name for one thing (Jake, #2810). + user-scoped data, not org scope. From FIX-1788's spec (#2812): D3's third change holds the + worker link in a server-only field set at create, so no action names a worker. "Seat" left the + prose here, one name for one thing (Jake, #2810). **Open: none needing an answer now.** Whether the shared half stays in the MVP is asked at FIX-1793's spec gate ([Q2](#q2)). diff --git a/specs/epics/FIX-1786/SPEC.md b/specs/epics/FIX-1786/SPEC.md index faaf61dbf7..e498659a98 100644 --- a/specs/epics/FIX-1786/SPEC.md +++ b/specs/epics/FIX-1786/SPEC.md @@ -24,11 +24,12 @@ the refactor starts from a known base. **Two users in one org each run a private roster (a standard worker, a fork, a library copy and a coordinator) on shared singleton flows, and work one shared project through workstreams they each own, with every task running as its owner and nothing of one user's reachable by the other -except what was written to a shared resource.** +except what was written to a shared resource or to org scope.** -Org scope counts as shared. A worker flow may write there if that is how it is built to work, -and the framework doesn't refuse it; the built-in worker flows keep a worker's own state out of -it ([D3](DECISIONS.md#d3), [ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). +A worker's own state and user-scoped data never cross users. Org scope is shared with the org by +design: a worker flow may write there if that is how its author built it, the framework doesn't +refuse it, and other members' runs read it. The built-in worker flows keep a worker's own state +out of it ([D3](DECISIONS.md#d3), [ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). | Is it the right goal? | | |---|---| @@ -56,10 +57,10 @@ makes leg c's PASS mean something. | How we verify | | |---|---| | **Goal check** | The closure issue's goal check ([FIX-1797](https://linear.app/fixpoint-labs/issue/FIX-1797)), in Shift Manager over HTTP and a browser, on one `main` commit after every other child merges ([ER-28](BUSINESS-RULES.md#the-closure)) | -| **Signal** | Leg a: Alice forks a standard worker, copies a template, and posts to a best-fit coordinator whose delegates she adds; her delegate answers, the routing is recorded, every session is hers. Leg b: Alice and Bob each own a workstream in one shared project; every session in each chain belongs to its owner, two of Alice's boards that hand rows to another flow each drain only their own, and the project view computes both. Leg c: Bob opens Alice's session, names her worker as a delegate, writes her entry, links a session to her worker: each refused. Alice in a second org sees none of her first org's workers, nor anything stored before FIX-1790. In leg b, Alice also makes a private project, and Bob can't list, open or read it ([Q2](DECISIONS.md#q2)) | +| **Signal** | Leg a: Alice forks a standard worker, copies a template, and posts to a best-fit coordinator whose delegates she adds; her delegate answers, the routing is recorded, every session is hers. Leg b: Alice and Bob each own a workstream in one shared project; every session in each chain belongs to its owner, two of Alice's boards that hand rows to another flow each drain only their own, and the project view computes both. Leg c: Bob opens Alice's session, names her worker as a delegate, writes her entry, links a session to her worker: each refused. Leg c reaches only for a worker's own state and user-scoped data; a member reading what a worker flow wrote to org scope is not a failure. Alice in a second org sees none of her first org's workers, nor anything stored before FIX-1790. In leg b, Alice also makes a private project, and Bob can't list, open or read it ([Q2](DECISIONS.md#q2)) | | **Input** | Shift Manager (`packages/shift-manager`) on its standard install, converted to `WORKER.md`; two users of one org through the app's sign-in; a real model; a held-out post for the coordinator | | **Anti-game** | No asserting on a child's own tests. No worker, project or delegate seeded by a fixture: the users make each one through the app. No run with one user, and no request of Bob's sent under Alice's identity | -| **Control that must fail** | The worker collection at org scope: leg c must FAIL. Today's `main`: all three legs FAIL | +| **Control that must fail** | The worker collection at org scope, which puts a worker itself where every member reads it: leg c must FAIL. Today's `main`: all three legs FAIL | | **Milestone** | Leg c's worker steps and the control run early, on the commit FIX-1788 merges on, so the privacy fix is proved before the coordinator builds on it rather than last ([ER-30](BUSINESS-RULES.md#the-closure)) | ## What's in the box @@ -135,7 +136,7 @@ widest window is three at once: projects, the chain and the library. **[The goal](#the-goal-and-how-well-know-its-met), at that size:** two users, a private roster each, one shared project with an owner per workstream, and nothing crossing except shared -resources. If wrong: we rename the parts while a hire still reaches every member. +resources and org scope. If wrong: we rename the parts while a hire still reaches every member. 1. **[D1](DECISIONS.md#d1) · Nine refactor children after the inventory, and a closure, now.** If wrong: a refactor that rebuilds under in-flight work, or one nobody needed this year. diff --git a/specs/epics/FIX-1786/concept/CONCEPT.md b/specs/epics/FIX-1786/concept/CONCEPT.md index 22a5c30598..e1809c3635 100644 --- a/specs/epics/FIX-1786/concept/CONCEPT.md +++ b/specs/epics/FIX-1786/concept/CONCEPT.md @@ -438,7 +438,7 @@ These terms are in today's code and docs, and go away in the refactor. Counts ar - [ ] **One coordinator** flow or two? Open. One flow if the styles share most of the flow, two if they diverge. - [X] **Where do a coordinator's delegates live?** Decided: in session state. Each session starts from the defaults in the coordinator's configuration and manages them from there, so the lock on standard workers never gets in the way. - [X] **Can the coordinator change its own delegates?** Decided: yes, in its session's state. -- [ ] **The worker contract.** Recommend building on today's admission contract and door, and adding the private-state rule and a standard-only flag per flow. +- [X] **The worker contract.** Decided ([Q1](../DECISIONS.md#q1)): today's admission contract and door, plus the private-state rule, on a list of worker flows the installation keeps, with standard-only set per entry on that list. - [ ] **Is a workstream a project entry plus its lead's workstream session?** Recommend yes. It needs no new flow, and its board is an ordinary session board. Store each workstream as its own resource under its project, and compute project progress from them. - [X] **How do long-lived sessions manage memory?** Moved to the memory epic, [FIX-1775](https://linear.app/fixpoint-labs/issue/FIX-1775/epic-memory-and-session-context-management), updated with what this doc found: what's kept word for word, when it summarizes, and what moves to the memory layers, configurable per flow and per worker. - [ ] **User-to-user communication.** Punted until we know we want it, and whether it belongs to the framework or the app. diff --git a/specs/epics/FIX-1786/poc/singleton-worker-link/README.md b/specs/epics/FIX-1786/poc/singleton-worker-link/README.md index 1d571640f4..f88758c6fc 100644 --- a/specs/epics/FIX-1786/poc/singleton-worker-link/README.md +++ b/specs/epics/FIX-1786/poc/singleton-worker-link/README.md @@ -61,6 +61,8 @@ engine shows up here as a red test. ## What it means +Superseded by [D3](../../DECISIONS.md#d3) and FIX-1788: the link is a server-only session field set at create. + - **The third Layer 1 change is needed.** Session state plus a user-scoped read stops other users (X1) but accepts a caller-seeded link to the caller's own other worker (O1). A row only flow code writes refuses that (O2) but outlives the session (R1). Neither holds ER-1. From 3aee05db0ecaab2ea35da0b710fc40d48ff17fb1 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 20:01:30 +0000 Subject: [PATCH 3/5] spec(FIX-1786): every statement of the sharing rule names org scope The teams table, the real-need row, the concept's rule line and figure title, and DOCS.md's proposed overview now say the same thing as the goal: a worker's own state and user-scoped data are private; shared resources and org scope are shared, and a flow writes to org scope by its author's choice. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV --- specs/epics/FIX-1786/DOCS.md | 5 +++-- specs/epics/FIX-1786/SPEC.md | 4 ++-- specs/epics/FIX-1786/concept/CONCEPT.md | 2 +- .../epics/FIX-1786/figures/concept-1-private-and-shared.svg | 4 ++-- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/specs/epics/FIX-1786/DOCS.md b/specs/epics/FIX-1786/DOCS.md index 9cf8af5dc7..898047ce93 100644 --- a/specs/epics/FIX-1786/DOCS.md +++ b/specs/epics/FIX-1786/DOCS.md @@ -13,8 +13,9 @@ what Workforce does, never what it used to do. Each child's own `DOCS.md` carrie > `@flow-state-dev/workforce` gives each user a roster of workers: agents, or deterministic > workflows, that work for that user and act as them. > -> One rule covers who sees what. Everything is private to one user, and the only shared -> things are shared resources. Your workers, your private projects and every session +> One rule covers who sees what: a worker's own state and your user data are private to you, +> while shared resources and org-scope data are shared with your org, and a flow writes to org +> scope only when its author built it to. Your workers, your private projects and every session > are yours alone. A shared project, its workstream entries and the org's worker library are > shared, and each line written there names the user and the worker that wrote it. > diff --git a/specs/epics/FIX-1786/SPEC.md b/specs/epics/FIX-1786/SPEC.md index e498659a98..5b532e092e 100644 --- a/specs/epics/FIX-1786/SPEC.md +++ b/specs/epics/FIX-1786/SPEC.md @@ -6,7 +6,7 @@ | A team that… | Today | After this epic | |---|---|---| -| **builds an app on Workforce** | Learns hires, mailboxes, rooms, talk sessions, flow instances and owner pins, and three meanings of "shared" | Learns one rule: everything is private to one user, and only shared resources are shared. Then workers, each naming the flow that runs it, coordinators and workstreams | +| **builds an app on Workforce** | Learns hires, mailboxes, rooms, talk sessions, flow instances and owner pins, and three meanings of "shared" | Learns one rule: a worker's own state and user-scoped data are private to one user, while shared resources and org scope are shared, and a flow writes to org scope by its author's choice. Then workers, each naming the flow that runs it, coordinators and workstreams | | **runs an org with more than one user** | A hire locked to the org alone is reachable by every member. Mailbox boards are org rows no session narrows, and a drain runs as whoever triggers it | A worker belongs to one user and acts as them. Shared work enters a roster only through its owner | | **wants a worker of their own** | Edits a `WORKER.md` and restarts, or gets an org hire every member can reach | Forks a standard worker, or copies a template from the org's library. The copy is theirs alone | | **hands work between workers** | A mailbox's members are fixed when it opens, and workers can't answer each other | A coordinator routes by judgment, best fit, round robin or everyone, to delegates it can add and remove | @@ -33,7 +33,7 @@ out of it ([D3](DECISIONS.md#d3), [ER-2](BUSINESS-RULES.md#what-a-team-gets-and- | Is it the right goal? | | |---|---| -| **The real need** | Jake's PRD: one rule set, where everything is private to one user and the only shared things are shared resources. The model is the problem, not its docs. Under it sits a hole: an org-locked hire reaches every member | +| **The real need** | Jake's PRD: one rule set, where a worker's own state and user-scoped data are private to one user, while shared resources and org scope, which a flow writes by its author's choice, are shared (Jake, 2026-10-06). The model is the problem, not its docs. Under it sits a hole: an org-locked hire reaches every member | | **Smaller, and rejected** | "The terms are renamed." FIX-1796 alone meets it, and the org-locked hire still reaches everyone. Or "workers are private": FIX-1788 alone, while boards and projects stay org rows any member's session drains | | **Bigger, and not this epic's** | Channels · user-to-user communication · transcript resources · files as migrations · long-lived session memory (FIX-1775) · removing flow instances and owner pins from the engine ([FIX-1798](https://linear.app/fixpoint-labs/issue/FIX-1798), after FIX-1788) | | **Not done if** | Every child is Done and the closure check hasn't run · it ran with one user · Bob opens, names or writes any of Alice's workers, sessions, boards or workstream sessions · a task in Alice's chain runs as anyone else · one of Alice's boards claims another's rows · a user changes a standard worker · leg b never made a private project · a record stored before FIX-1790 reads in two orgs · a `MAILBOX.md` loads · Workforce still registers a flow instance or sets an owner pin · a retired term is left in an export or a published page ([ER-12](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) · a bug the closure run found is open | diff --git a/specs/epics/FIX-1786/concept/CONCEPT.md b/specs/epics/FIX-1786/concept/CONCEPT.md index e1809c3635..925c6c3f0f 100644 --- a/specs/epics/FIX-1786/concept/CONCEPT.md +++ b/specs/epics/FIX-1786/concept/CONCEPT.md @@ -29,7 +29,7 @@ This doc describes how Workforce should work, from first principles, in terms a **A user is always a person.** The framework doesn't own identity and has no system users. An app can create a "system user" of its own, and to the framework it's just another user. -**Everything is private to one user. The only shared things are shared resources.** Every session belongs to one user, and nobody else can open it. Something is shared only when it's written to a shared resource, such as a channel's conversation or a shared project. +**A worker's own state and user data are private to one user. Shared resources and org scope are shared, and a flow writes to org scope by its author's choice.** Every session belongs to one user, and nobody else can open it. Something is shared only when it's written to a shared resource, such as a channel's conversation or a shared project. The engine already works this way. What changes is that Workforce stops describing anything else as shared. diff --git a/specs/epics/FIX-1786/figures/concept-1-private-and-shared.svg b/specs/epics/FIX-1786/figures/concept-1-private-and-shared.svg index 4a88178e15..2b5401e51e 100644 --- a/specs/epics/FIX-1786/figures/concept-1-private-and-shared.svg +++ b/specs/epics/FIX-1786/figures/concept-1-private-and-shared.svg @@ -1,5 +1,5 @@ + aria-label="Workers are private; sharing happens in shared resources and org scope. Above the org, the product files: the standard install every user starts with. Inside org acme, a shared area holds a channel whose lines name user and worker, a shared project whose workstreams have one owner each, and the worker library of templates to copy. Below it, Alice's private area holds her standard researcher, a private project with workstreams and tasks, a coordinator and an analyst; Bob's holds his own standard researcher, a writer he copied, a coordinator and a private project. Alice's researcher answers in the channel as Alice; Alice owns a workstream of the shared project; Bob copied the writer from the library by choice."> - Workers are private; sharing happens only in shared resources + Workers are private; sharing happens in shared resources and org scope Product files: the standard install every user starts with From 4251a4bab6993317906eaa7c5ec994799b5f049e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 20:06:18 +0000 Subject: [PATCH 4/5] spec(FIX-1786): writtenBy can't be forged from input, and is never an auth input ER-11 and the Decided-in-review line now say the stamp can't be forged from input, while flow code writing the resource directly can set any value (FIX-1789's BR-22, its K3 leg); writtenBy is for display and audit only, and who may write is FIX-1793's. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV --- specs/epics/FIX-1786/BUSINESS-RULES.md | 2 +- specs/epics/FIX-1786/DECISIONS.md | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/specs/epics/FIX-1786/BUSINESS-RULES.md b/specs/epics/FIX-1786/BUSINESS-RULES.md index 9102f6b937..69b3ba1dab 100644 --- a/specs/epics/FIX-1786/BUSINESS-RULES.md +++ b/specs/epics/FIX-1786/BUSINESS-RULES.md @@ -21,7 +21,7 @@ seven rules explains is a bug in the model. | ER-8 | A user talks to a project through their own project coordinator session, one per user per project. Rooms are removed | FIX-1793 builds | The closure | | ER-9 | Every session in a chain belongs to the owner of the work. A board drains as its owner, never as whoever triggers it, and only its own drains claim, wake on or settle its rows: two of one owner's sessions never share a ledger. A lineage stops at a flow, so a board whose rows a worker on another flow settles can't be shared down it, and an unpartitioned user-scoped ledger doesn't hold either, since it spans every session its owner has. How such a board stays its own is FIX-1794's first spec question; an answer that changes the task board comes back to this epic ([ER-22](#what-no-child-may-do)) | FIX-1794 decides · FIX-1793 consumes | FIX-1794's tests · the closure's leg b | | ER-10 | Adding a library template copies it into the user's scope. The copy never changes under them; taking an update is their choice | FIX-1795 decides | FIX-1795's tests | -| ER-11 | Everything written to a shared resource names the user, and the worker when one wrote it. The name is stamped from the session's identity, so a caller can't forge it; it is as trustworthy as the registered worker flow's code, and no doc promises more ([D3](DECISIONS.md#d3)) | FIX-1789 decides · FIX-1793, FIX-1795 consume | FIX-1793's and FIX-1795's spec review | +| ER-11 | Everything written to a shared resource names the user, and the worker when one wrote it. The name is stamped from the session's identity, so it can't be forged from input; flow code that writes the resource directly can set any value, so it is only as trustworthy as the registered worker flow's code, and no doc promises more (FIX-1789's BR-22, whose K3 leg pins the bypass; [D3](DECISIONS.md#d3)). `writtenBy` is for display and audit only, never an authorization input; who may write is FIX-1793's | FIX-1789 decides · FIX-1793, FIX-1795 consume | FIX-1793's and FIX-1795's spec review | | ER-12 | No retired term is left in a package export, a published page or the glossary. Channel-kind paths and the engine's dispatch "target" stay | FIX-1796 builds · every child consumes | The closure's gap sweep | ## What no child may do diff --git a/specs/epics/FIX-1786/DECISIONS.md b/specs/epics/FIX-1786/DECISIONS.md index fa0d436cb0..5d88431e2b 100644 --- a/specs/epics/FIX-1786/DECISIONS.md +++ b/specs/epics/FIX-1786/DECISIONS.md @@ -190,9 +190,11 @@ engine rule. The closure only checks. From review. - **A shared entry's `writtenBy` is as trustworthy as the worker flow that wrote it.** With no engine rule ([D3](#d3)), FIX-1789's shared-write helper stamps it from the session's identity; - a caller can't forge it, but the registered flow's own code could, and no doc may promise - otherwise ([ER-11](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). From FIX-1789's - gate, an engineering call. + it can't be forged from input, but flow code that writes the resource directly can set any + value (FIX-1789's BR-22; its K3 leg pins the bypass), and no doc may promise otherwise + ([ER-11](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). It is for display and audit + only, never an authorization input; who may write is FIX-1793's. From FIX-1789's gate, an + engineering call. - **A worker names the flow that runs it.** An installation has many worker flows (the built-in agent, the coordinator, the app's own), each one singleton copy that every worker naming it shares. Making flows singletons doesn't put every worker on `agent` ([ER-1](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). From ea19d5b523617b360f1c90a8c2a4f8d7888d5ce9 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 20:07:21 +0000 Subject: [PATCH 5/5] spec(FIX-1786): privacy is not a registration check; ER-2's checks are three Per the architect's note on #2813 and #2814's recommended Q2 reading: ER-2's contract checks are workerConfigSchema() by value, a door, and a full writtenBy shape on anything it declares. The built-in worker flows keep a worker's own state out of org scope; a custom worker flow's privacy is its author's, as writtenBy's trust is. D3, SPEC, PLAN and CONCEPT restatements follow. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV --- specs/epics/FIX-1786/BUSINESS-RULES.md | 2 +- specs/epics/FIX-1786/DECISIONS.md | 6 +++--- specs/epics/FIX-1786/PLAN.md | 2 +- specs/epics/FIX-1786/SPEC.md | 5 +++-- specs/epics/FIX-1786/concept/CONCEPT.md | 10 +++++----- 5 files changed, 13 insertions(+), 12 deletions(-) diff --git a/specs/epics/FIX-1786/BUSINESS-RULES.md b/specs/epics/FIX-1786/BUSINESS-RULES.md index 69b3ba1dab..9ef4c2188c 100644 --- a/specs/epics/FIX-1786/BUSINESS-RULES.md +++ b/specs/epics/FIX-1786/BUSINESS-RULES.md @@ -12,7 +12,7 @@ seven rules explains is a bug in the model. | # | Rule | Owner | Checked at | |---|---|---|---| | ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's link to its worker is set and checked by the server when the session is created, held where only the server writes, and never changes; no caller and no action names a worker ([D3](DECISIONS.md#d3)), and a forged link reads nothing. A worker's private state is keyed by the worker, not the flow, and today's per-worker cells move to it (BP-030) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure | -| ER-2 | A flow runs workers only when it is a registered worker flow that meets the contract: it composes `workerConfigSchema()`, has a door, and keeps a worker's own state private. That promise covers a worker's own state and user-scoped data, not org scope: org scope is shared with the org by design, and a flow that writes there does so by its author's choice, which the framework doesn't refuse ([D3](DECISIONS.md#d3)); the built-in worker flows keep a worker's own state out of it. A flow is declared on a list the installation keeps, checked at registration by checks a library can call in its own tests, and the installation can keep an entry for standard workers only ([Q1](DECISIONS.md#q1)). A worker's configuration is stored data: its tools, skills and packages are names, resolved against what the installation registers when a session loads the worker. A flow reads the running worker's configuration per run, never from `ctx.flow.config`, which a singleton holds once for every worker and keeps for the flow's own settings | FIX-1789 decides · FIX-1788, FIX-1791 consume | FIX-1788's spec review · the closure | +| ER-2 | A flow runs workers only when it is a registered worker flow that meets the contract: it composes `workerConfigSchema()` (checked by value), has a door, and gives any `writtenBy` it declares the full shape. Privacy is not a registration check. The built-in worker flows (`agent`, the coordinator) keep a worker's own state out of org scope; a custom worker flow's privacy is its author's, the way `writtenBy` is ([ER-11](#what-a-team-gets-and-what-it-doesnt)). Org scope is shared with the org by design, and the framework doesn't refuse a flow's writes there ([D3](DECISIONS.md#d3)). A flow is declared on a list the installation keeps, checked at registration by checks a library can call in its own tests, and the installation can keep an entry for standard workers only ([Q1](DECISIONS.md#q1)). A worker's configuration is stored data: its tools, skills and packages are names, resolved against what the installation registers when a session loads the worker. A flow reads the running worker's configuration per run, never from `ctx.flow.config`, which a singleton holds once for every worker and keeps for the flow's own settings | FIX-1789 decides · FIX-1788, FIX-1791 consume | FIX-1788's spec review · the closure | | ER-3 | User-scoped data is kept per (user, org) for every flow. A record stored before reads in one org at most: an operator step moves it to the one org it can be attributed to, and stops with `migration-required` on one it can't. No per-org cell falls back to the cross-org cell, which is the read this rule closes (the owner-pinned cell's rule, [`state-and-scopes.md`](../../../docs/architecture/state-and-scopes.md#the-owner-pinned-cell)). How a record is attributed is FIX-1790's first spec question | FIX-1790 builds · FIX-1788, FIX-1793 consume | FIX-1790's tests · the closure's second-org step | | ER-4 | A coordinator's delegates live in its session state and start from its configuration's defaults. Both paths that change them, the app and the coordinator's own tool, pass one check: a delegate is on the same user's roster. The public create can't seed them ([D3](DECISIONS.md#d3)) | FIX-1791 decides · FIX-1793, FIX-1794, FIX-1792 consume | FIX-1791's tests · the closure | | ER-5 | An answer doesn't trigger routing again, except for a set number of rounds. One answer per delegate per post. Every routing decision is recorded | FIX-1791 builds | FIX-1791's tests · the closure | diff --git a/specs/epics/FIX-1786/DECISIONS.md b/specs/epics/FIX-1786/DECISIONS.md index 5d88431e2b..e7fad5885d 100644 --- a/specs/epics/FIX-1786/DECISIONS.md +++ b/specs/epics/FIX-1786/DECISIONS.md @@ -62,7 +62,7 @@ answer record in one shared module. | | | |---|---| | **Instead of** | A Layer 1 worker noun with its own store · or per-org user keys faked inside Workforce · or a fourth change, an engine rule refusing a worker flow's writes to org scope (FIX-1789's Q2) | -| **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Three things Workforce cannot fake: a scope key, a row rule, session state a caller can't write. [The end-state POC](#what-the-end-state-poc-showed) settled the third: the public create persists a caller's session state, so a link held there accepts the caller's own other worker, and a row only flow code writes outlives a deleted session id. No fourth (Jake, 2026-10-06): org scope is shared with the org by design, a worker flow may write there if that is how it is built to work, and the framework can't know when org data is relevant. The built-in worker flows, `agent` and the coordinator, keep a worker's own state out of it | +| **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Three things Workforce cannot fake: a scope key, a row rule, session state a caller can't write. [The end-state POC](#what-the-end-state-poc-showed) settled the third: the public create persists a caller's session state, so a link held there accepts the caller's own other worker, and a row only flow code writes outlives a deleted session id. No fourth (Jake, 2026-10-06): org scope is shared with the org by design, a worker flow may write there if that is how it is built to work, and the framework can't know when org data is relevant. The built-in worker flows, `agent` and the coordinator, keep a worker's own state out of it; a custom worker flow's privacy is its author's, and the contract doesn't check it ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) | | **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change whose old records move to one org by an operator step, never read in two ([ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)); (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) session data only the server writes. The worker link takes the form this card's *what would change my mind* anticipated: a server-only field on the session record, set and checked when the session is created, never on a turn; a session's worker can't change, and no action names a worker (Jake, 2026-10-06, on FIX-1788's spec). A coordinator's delegates are held where only the server writes too, and the public create can't seed them. FIX-1788 picks the mechanism and builds it, FIX-1791 consumes it. Flow instances and owner pins get deprecation markers, nothing more. A worker's own key for its private state is Layer 2, FIX-1788's, and so is reading a worker's configuration per run: a generator already resolves its tools per call ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). Any other Layer 1 change comes back to this epic | **What would change my mind:** a second consumer of a worker outside Workforce. Then a worker @@ -158,8 +158,8 @@ rule, both restated on the new model. The matrix holds ER-1 to ER-12; ER-13 onward are fences and process that bind every child alike. FIX-1788 decides what a worker is, so the coordinator, the library and the conversion -consume it rather than define their own. FIX-1789 owns attribution on shared writes, because it -is the contract's private-state rule seen from the shared side. FIX-1793 owns the one new +consume it rather than define their own. FIX-1789 owns attribution on shared writes, because a +full `writtenBy` shape is one of the contract's registration checks. FIX-1793 owns the one new engine rule. The closure only checks. ## Decided in review, recorded so no child reopens them diff --git a/specs/epics/FIX-1786/PLAN.md b/specs/epics/FIX-1786/PLAN.md index 11623aeb72..e7d8671f4c 100644 --- a/specs/epics/FIX-1786/PLAN.md +++ b/specs/epics/FIX-1786/PLAN.md @@ -20,7 +20,7 @@ privacy fix is checked when workers merges, not only at the end (ER-30). The gra | Issue | Route | Consumes | Delivers | Releases | Size | |---|---|---|---|---|---| | **FIX-1787** inventory | inventory, no spec | Every open PR and active issue in the areas | 38 calls: 13 merge first, 13 close, 12 untouched | Every refactor child | Done as a table; its merges are the work | -| **FIX-1789** contract | spec → impl PR | `workerConfigSchema()`, the door · Q1, decided at its spec gate on its POC of both shapes: the list | Worker flows on the installation's list, checked at registration by exported checks; the private-state rule, standard-only per entry, attribution; a worker's configuration as stored data read per run (ER-2, ER-11) | FIX-1788 | Small, plus the two-shape POC | +| **FIX-1789** contract | spec → impl PR | `workerConfigSchema()`, the door · Q1, decided at its spec gate on its POC of both shapes: the list | Worker flows on the installation's list, checked at registration by exported checks (configuration by value, a door, a full `writtenBy` shape); standard-only per entry, attribution; a worker's configuration as stored data read per run (ER-2, ER-11) | FIX-1788 | Small, plus the two-shape POC | | **FIX-1790** per-org data | spec → impl PR | The engine's user key | User data per (user, org); old records moved to the one org they belong to by an operator step, or refused, never read in two (ER-3) | FIX-1788 | Medium: a persisted key every flow uses, and its migration | | **FIX-1788** workers | spec → impl PRs | ER-2 · ER-3 · projected collections · Q1's list | Worker resources on singleton flows, standard projection, fork, deprecations; the session link, set and checked at create where only the server writes (D3's third change); a worker's own key for its private state, with today's per-worker cells moved (ER-1) | FIX-1791 · FIX-1795 | Large | | **FIX-1791** coordinator | spec → impl PRs | ER-1 · FIX-1779's join and leave · FIX-1774's legs · Q1's list | The coordinator flow, delegates, four policies, the records (ER-4, ER-5); the chief of staff as a standard coordinator | FIX-1793 · FIX-1794 · FIX-1792 | Medium to large | diff --git a/specs/epics/FIX-1786/SPEC.md b/specs/epics/FIX-1786/SPEC.md index 5b532e092e..d53da37095 100644 --- a/specs/epics/FIX-1786/SPEC.md +++ b/specs/epics/FIX-1786/SPEC.md @@ -29,7 +29,8 @@ except what was written to a shared resource or to org scope.** A worker's own state and user-scoped data never cross users. Org scope is shared with the org by design: a worker flow may write there if that is how its author built it, the framework doesn't refuse it, and other members' runs read it. The built-in worker flows keep a worker's own state -out of it ([D3](DECISIONS.md#d3), [ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). +out of it; a custom worker flow's privacy is its author's, not a registration check +([D3](DECISIONS.md#d3), [ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). | Is it the right goal? | | |---|---| @@ -79,7 +80,7 @@ blocked by FIX-1787 ([ER-23](BUSINESS-RULES.md#how-the-set-is-run)). | Issue | What it delivers | Why the set needs it | Status | |---|---|---|---| | [FIX-1787](https://linear.app/fixpoint-labs/issue/FIX-1787) · inventory | A merge, close or untouched call for every open PR and active issue in the areas the refactor changes | The refactor starts from its result. Route: inventory, no spec, user-approved outside this gate | In Review · posted 2026-10-06 [on FIX-1786](https://linear.app/fixpoint-labs/issue/FIX-1786#comment-9e837aa5): 38 items, 13 merge first, 13 close, 12 untouched; its two owner calls answered 2026-10-06 ([Q2](DECISIONS.md#q2), [Q3](DECISIONS.md#q3)) | -| [FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) · worker contract | Registered worker flows on the installation's list, the private-state rule, a standard-only flag per entry | A worker's configuration must name a flow that keeps its state private | Spec merged ([#2811](https://github.com/fixpoint-labs/flow-state-dev/pull/2811)) · [Q1](DECISIONS.md#q1) decided at its gate: the list | +| [FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) · worker contract | Registered worker flows on the installation's list, their registration checks, a standard-only flag per entry | A worker's configuration must name a flow the installation registered and checked | Spec merged ([#2811](https://github.com/fixpoint-labs/flow-state-dev/pull/2811)) · [Q1](DECISIONS.md#q1) decided at its gate: the list | | [FIX-1790](https://linear.app/fixpoint-labs/issue/FIX-1790) · user data per org | User-scoped data kept per (user, org), for every flow; records stored before moved to one org or refused | Without it a user's private workers show in every org they belong to | Backlog · spec route | | [FIX-1788](https://linear.app/fixpoint-labs/issue/FIX-1788) · workers as resources | A worker as a user-scoped resource, run by the singleton flow it names; standard workers projected from files; fork; a session link callers can't seed; instances and pins deprecated | The spine: privacy by construction | Backlog · spec route | | [FIX-1791](https://linear.app/fixpoint-labs/issue/FIX-1791) · coordinator flow | Delegates in session state, four routing policies, one answer per delegate, a routing record | Replaces the mailbox with a worker, and fixes its fixed membership | Backlog · spec route · carries FIX-1774's dogfood legs and *not done if* list | diff --git a/specs/epics/FIX-1786/concept/CONCEPT.md b/specs/epics/FIX-1786/concept/CONCEPT.md index 925c6c3f0f..1a9b75a201 100644 --- a/specs/epics/FIX-1786/concept/CONCEPT.md +++ b/specs/epics/FIX-1786/concept/CONCEPT.md @@ -10,7 +10,7 @@ > **Where this differs from the epic, the epic binds.** This is the PRD as Jake wrote it; the > epic's [decisions](../DECISIONS.md) and [rules](../BUSINESS-RULES.md) settle what it leaves > open. One coordinator flow with a routing setting ([D2](../DECISIONS.md#d2)). Where an author -> declares a worker flow is [Q1](../DECISIONS.md#q1): a list the installation keeps, chosen at FIX-1789's spec gate on a POC of both. "Keeps a worker's state private" covers a worker's own state and user-scoped data; org scope is shared with the org by design, and the framework doesn't refuse a flow's writes there ([D3](../DECISIONS.md#d3)). A workstream is a project entry plus its +> declares a worker flow is [Q1](../DECISIONS.md#q1): a list the installation keeps, chosen at FIX-1789's spec gate on a POC of both. The contract's registration checks are the standard configuration, a door and a full `writtenBy` shape on shared writes; privacy is not one of them. The built-in worker flows keep a worker's own state out of org scope, and a custom worker flow's privacy is its author's. Org scope is shared with the org by design, and the framework doesn't refuse a flow's writes there ([ER-2](../BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt), [D3](../DECISIONS.md#d3)). A workstream is a project entry plus its > lead's session; `MAILBOX.md` becomes `WORKER.md`; no transcript resource is built, so the > `transcript:` key below isn't either ([decided in review](../DECISIONS.md#decided-in-review-recorded-so-no-child-reopens-them)). > The boards are per [D5](../DECISIONS.md#d5) and [ER-9](../BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt). A worker's @@ -85,7 +85,7 @@ Not every flow can run a worker. A flow becomes available to workers only when i * **It accepts a worker's standard configuration:** instructions, skills, tools, packages and the worker's id, plus its own settings beside them. * **It has a door:** one public action that takes a message, so an app can talk to any worker without knowing its flow. -* **It keeps a worker's state private.** Anything shared goes through a shared resource, with attribution. +* **It signs what it shares.** Anything written to a shared resource carries attribution in full. The built-in worker flows keep a worker's own state out of org scope; a custom flow's privacy is its author's. The installation registers which flows are worker flows. A worker's configuration can only name a registered worker flow, and the installation can keep some flows for standard workers only, so a user can't hire a non-standard worker onto them. @@ -402,7 +402,7 @@ One term, one thing. Retired: person (say user), seat, hired seat, hired roster | Task | A unit of work assigned to a worker, worked in its own task session | Private | | Board | A list of tasks, belonging to a session | Private | | Standard install | What every user starts with, defined by files | Installation-level | -| Worker contract | What a flow must meet to run workers: standard configuration, a door, private state | Installation-level | +| Worker contract | What a flow must meet to run workers: standard configuration, a door, attribution on shared writes | Installation-level | | Door | The one public action that takes a message to a worker | Private | | Delegate | A worker a coordinator can hand posts to. Always on the same user's roster | Private | | Routing policy | How a coordinator picks delegates: judgment, best fit, round robin, or everyone | Private | @@ -438,7 +438,7 @@ These terms are in today's code and docs, and go away in the refactor. Counts ar - [ ] **One coordinator** flow or two? Open. One flow if the styles share most of the flow, two if they diverge. - [X] **Where do a coordinator's delegates live?** Decided: in session state. Each session starts from the defaults in the coordinator's configuration and manages them from there, so the lock on standard workers never gets in the way. - [X] **Can the coordinator change its own delegates?** Decided: yes, in its session's state. -- [X] **The worker contract.** Decided ([Q1](../DECISIONS.md#q1)): today's admission contract and door, plus the private-state rule, on a list of worker flows the installation keeps, with standard-only set per entry on that list. +- [X] **The worker contract.** Decided ([Q1](../DECISIONS.md#q1)): today's admission contract and door, plus a full `writtenBy` shape on shared writes, on a list of worker flows the installation keeps, with standard-only set per entry on that list. - [ ] **Is a workstream a project entry plus its lead's workstream session?** Recommend yes. It needs no new flow, and its board is an ordinary session board. Store each workstream as its own resource under its project, and compute project progress from them. - [X] **How do long-lived sessions manage memory?** Moved to the memory epic, [FIX-1775](https://linear.app/fixpoint-labs/issue/FIX-1775/epic-memory-and-session-context-management), updated with what this doc found: what's kept word for word, when it summarizes, and what moves to the memory layers, configurable per flow and per worker. - [ ] **User-to-user communication.** Punted until we know we want it, and whether it belongs to the framework or the app. @@ -458,7 +458,7 @@ These terms are in today's code and docs, and go away in the refactor. Counts ar | A worker is a resource, and sessions load its configuration | Each worker is a flow instance with its configuration in code, rebuilt at every start from roster rows | | Every flow is a singleton, and a worker names the one it runs on | A worker already names its flow, but each hire mints its own copy of that flow, registered under the worker's id (`hire.ts`). The `agent` flow does it as one kind with many instances (`cardinality: "collection"`) | | Access to a worker is access to its resource | Instances carry pins, and only Workforce uses them | -| A worker contract decides which flows can run workers | Mostly there: a hireable flow's config schema accepts `workerConfigSchema()`, its door is found from its actions, and the flows passed to the hire are the allowlist. No standard-only flag, and no private-state rule. The configuration arrives as the flow copy's frozen `ctx.flow.config`, with `seatTools` as live blocks, so a stored worker can't carry it as is | +| A worker contract decides which flows can run workers | Mostly there: a hireable flow's config schema accepts `workerConfigSchema()`, its door is found from its actions, and the flows passed to the hire are the allowlist. No standard-only flag, and no attribution check. The configuration arrives as the flow copy's frozen `ctx.flow.config`, with `seatTools` as live blocks, so a stored worker can't carry it as is | | Standard workers are a projected collection read from files | `WORKER.md` files become flow instances. Projected collections exist (`defineProjectedResourceCollection`), read-only | | Workers are always private | A hire locked to the org alone is reachable by every member | | Library templates are copied into your scope | There is no library |