Repository navigation
spec(FIX-1788): A worker is a private resource its owner holds, run by the shared flow it names #2812
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
spec(FIX-1788): A worker is a private resource its owner holds, run by the shared flow it names #2812
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| # FIX-1788 · Business rules | ||
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| The cases, written as rules. Alice and Bob are two users of one org. The | ||
| *proved by* column is the check the plan runs. A human reviews this page; the plan turns it into | ||
| work. | ||
|
|
||
| ## Holding a worker | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-1 | Alice hires a worker | One row is written in her user scope, in this org. Nothing is registered. Her next turn on any process can use it | CI · VG leg a, second host | | ||
| | BR-2 | Alice forks a standard worker | A new worker of hers, starting from its configuration, under a new id ([Q1](DECISIONS.md#q1) decides the shared instructions). The standard worker is unchanged for everyone | CI · VG leg a | | ||
| | BR-3 | Anyone writes, edits or deletes a standard worker, by any path | Refused, naming it as standard and suggesting a fork | CI | | ||
| | BR-4 | Alice hires or forks with an id already on her roster, or a standard worker's id | Refused, naming the id. Bob's roster is not consulted | CI | | ||
| | BR-5 | Alice and Bob each hire `researcher` | Two workers. Neither sees the other's in any listing | CI · VG leg b | | ||
| | BR-6 | A hire's configuration names a flow that isn't a registered worker flow, or one kept for standard workers ([FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) BR-14), or fails the flow's schema | Refused when saved, with the flow's own reason. Nothing written | CI | | ||
| | BR-6a | A hire or fork grants a document or collection its flow doesn't declare | Refused when saved, naming it. Only a standard worker, in files, brings a collection its flow declares for it (the concept's "resources are declared on flows") | CI | | ||
| | BR-7 | Alice fires a worker | Its row is deleted. Its sessions stay readable to her, and a new turn on one is refused, naming the worker as fired. Every process sees it on the next turn | CI · two hosts | | ||
| | BR-8 | A hire, fork or fire finishes a turn | The turn names the worker collection it wrote, so a view reloads it ([FIX-1761](https://linear.app/fixpoint-labs/issue/FIX-1761)). No tool name is special-cased | CI | | ||
| | BR-9 | Alice lists her roster | Her own workers and every standard worker, each marked standard or hers. Nothing of Bob's, nothing from another org | CI · VG | | ||
|
|
||
| ## A session's worker | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-10 | Alice's first turn in a session names her worker, on the flow it names | The server links the session to it and runs the turn as it | CI · VG leg a | | ||
| | BR-11 | A first turn names a worker of Bob's | Refused with the same answer as a worker that doesn't exist. Nothing linked | CI · VG leg b | | ||
| | BR-12 | A first turn names a worker of Alice's on another flow | Refused, naming both flows. Nothing linked | CI · VG leg b | | ||
| | BR-13 | A later turn names a different worker | Refused. The link never changes. A later turn may omit the worker | CI | | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| | BR-13a | Two first turns on one unlinked session arrive together, naming different workers | One links and runs. The other is refused as BR-13, and its worker never runs | CI | | ||
| | BR-14 | A turn arrives on a session with no link and names no worker | Refused, saying a worker must be named | CI | | ||
| | BR-15 | A session is created with caller state for the link | Refused with 400, naming the field. Nothing written | CI · VG control `caller-link` | | ||
| | BR-16 | A session is deleted and its id created again | The new session has no link | CI | | ||
| | BR-17 | Bob opens, reads or sends to a session of Alice's | Refused, as today (engine ownership) | Existing suite · VG leg b | | ||
| | BR-18 | A task or a mailbox post opens a session for a worker | The same check as BR-10 to BR-12, on the session's user. The worker comes from the dispatching flow's code, never the post's fields | CI | | ||
| | BR-19 | A linked worker is fired | The turn is refused, naming it as fired. The session stays readable | CI | | ||
| | BR-19a | A linked worker's flow is no longer registered | The turn is refused. The session reads as a session of any unregistered flow reads today: this issue adds no engine read path (ER-22) | CI | | ||
|
|
||
| ## What a worker runs with | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-20 | Alice edits her worker | Her next turn on any session linked to it runs the edit. No restart | CI · two hosts | | ||
| | BR-21 | A stored configuration from an older version loads | It reads (BP-030), or the turn is refused naming the field. Never silently dropped | CI | | ||
| | BR-22 | A configuration names a tool, skill or package the installation no longer registers | That turn is refused, naming it. The row is untouched | CI | | ||
| | BR-22a | A user's own worker names a flow that has since become kept for standard workers | That turn is refused with [FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) BR-15's sentence. The row is untouched (BP-030) | CI | | ||
| | BR-23 | Two of Alice's workers on `agent` keep private notes | Each reads only its own. Same for every flow-isolated resource on every worker flow | CI · VG leg a | | ||
| | BR-24 | A worker's file grants it one document, read-only | Its model reaches that document and no other, and can't write it, on every turn | CI · the grants goal, rewritten | | ||
| | BR-25 | A worker reaches a resource another of Alice's workers wrote at user scope | Allowed: user scope is Alice's, shared by her workers (the concept's memory table) | CI | | ||
| | BR-25a | Two of Alice's workers on one flow write a shared resource | Each entry's `writtenBy` names Alice and the worker its session is linked to: two workers, two ids. The worker comes from the link, never the input ([FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) BR-20, D1) | CI | | ||
|
|
||
| ## One copy per flow | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-26 | The app starts with workers on several flows | Each flow a worker names is registered once. No copy per worker, no owner pin | CI · V0 · VG leg a | | ||
| | BR-27 | Code calls `register(flow, { pin })` or declares collection cardinality | It works as before, with a deprecation note naming FIX-1798 | CI | | ||
|
|
||
| ## Coming across from today | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-28 | The new code boots on a store with old hires, before the step | Old hires don't run. The boot reports how many wait for the step. Nothing is read across users or orgs | CI · VG leg c | | ||
| | BR-29 | The step meets a hire owned by Alice | It becomes her worker under its id. Its private cells move to the worker's key, and its sessions link to it | CI · VG leg c | | ||
| | BR-30 | The step meets an org-wide hire | A private copy for each member with a session on it ([D2](DECISIONS.md#d2)), each with that member's sessions and a copy of the hire's memory. Members without one get none | CI · VG leg c | | ||
| | BR-31 | A moved worker's id is already on that member's roster, or is a standard worker's id | It takes a new id, derived the same way on every run, and the report names both. Its sessions and memory move with it. Nothing overwritten, nothing skipped | CI | | ||
| | BR-32 | The step runs twice, or stops halfway | The second run finishes the first and changes nothing done. The old rows stay | CI | | ||
| | BR-33 | An old hire names a flow that's gone | Reported, not moved | CI | | ||
| | BR-33a | An old hire names a flow now kept for standard workers | Moved and reported. Its turns are refused as BR-22a until the installation changes that | CI | | ||
|
|
||
| ## Failure taxonomy | ||
|
|
||
| A refused link, a refused turn and a refused write change nothing and name why. A configuration | ||
| that fails on load refuses that turn only; the row and the session survive for a fix. A missing | ||
| step is not an error: old hires wait, reported. Nothing retries, and nothing is deleted except | ||
| by a fire. | ||
|
|
||
| ## Acceptance criteria this issue owns | ||
|
|
||
| [The goal](SPEC.md#the-goal-and-how-well-know-its-met) passes on a scripted model with two users | ||
| and two hosts, after the same run fails under `org-scoped-workers` and `caller-link`. The epic's | ||
| early leg-c run ([ER-30](../../epics/FIX-1786/BUSINESS-RULES.md#the-closure)) then runs on the | ||
| merge commit, in Shift Manager; that run is FIX-1797's. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,142 @@ | ||
| # FIX-1788 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| What the model already decided is the epic's ([ER-1](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt), | ||
| [D3](../../epics/FIX-1786/DECISIONS.md#d3)) and is not reopened here. These are the calls this | ||
| issue makes about the people already using hired workers, and one it asks. | ||
|
|
||
| ## The tree | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| I["FIX-1788"] --> D1["D1 · old hires move in one operator step"] | ||
| D1 -.->|"rejected · keeps every copy's machinery alive"| X1["read the old shape at run time"] | ||
| D1 -.->|"rejected · users lose their workers"| X1b["start fresh"] | ||
| I --> D2["D2 · an org-wide hire goes to each member who used it"] | ||
| D2 -.->|"rejected · breaks a worker people use"| X2["nobody, until an operator names one"] | ||
| D2 -.->|"rejected · workers nobody asked for"| X2b["every member"] | ||
| I --> Q1["Q1 · open · a fork copies the shared instructions"] | ||
| Q1 -.->|"not recommended · an edit to the files changes your fork"| X3["a fork follows them"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing. Q1 is the one open ask. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · Old hires, their memory and their conversations move to the new shape in one operator step | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Reading the old rows, cells and sessions at run time beside the new path · or starting fresh | | ||
| | **Because** | A hire's memory sits in its own copy's private cell, and its conversations are recorded against its own copy's address. The shared copy can reach neither unless the per-copy machinery stays alive, and that machinery is what [FIX-1798](https://linear.app/fixpoint-labs/issue/FIX-1798) removes. The same upgrade already has an operator step ([FIX-1790](https://linear.app/fixpoint-labs/issue/FIX-1790)), and [FIX-1538 D2](../FIX-1538/DECISIONS.md#d2) moved pinned cells the same way | | ||
| | **Locks in** | Between the deploy and the step, a user's old hires don't run, and the boot says how many wait for it. Every deployment with hires runs one documented step, beside FIX-1790's. Nothing is deleted, and running the step twice changes nothing | | ||
|
|
||
|  | ||
|
|
||
| It comes down to the old copies: reading them at run time keeps them alive forever. | ||
|
|
||
| **What would change my mind:** a hosted deployment with no operator to run a step. Then the move | ||
| runs on a user's first load instead, with the old machinery kept until every user has loaded. | ||
|
|
||
| <a name="d2"></a> | ||
| ## D2 · A worker hired for the whole org goes, as a private copy, to each member who talked to it | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Nobody's, until an operator names an owner · or a copy for every member of the org | | ||
| | **Because** | An org-wide hire is the hole this epic closes, so it can't stay shared. Each member who talked to it already has conversations and memory with it that only they can read. A private copy each keeps exactly what each person had and gives nobody anything new. Nobody's breaks a worker a team uses daily; every member's adds workers people never asked for | | ||
| | **Locks in** | One worker becomes several independent ones: a change one member makes reaches no other. What the worker remembered for the whole org is copied into each, and every one of them could already read it. A copy whose id the member already uses takes a derived id, reported. The old row stays, reported, so it can become a library template once [FIX-1795](https://linear.app/fixpoint-labs/issue/FIX-1795) ships | | ||
|
|
||
|  | ||
|
|
||
| It comes down to what each person already had: nobody loses a worker, nobody gains one. | ||
|
|
||
| **What would change my mind:** teams that rely on one org-wide worker's memory changing for | ||
| everyone at once. Then the right home is the library or a shared resource, and the step should | ||
| hold the hire for the operator instead. Or: no deployment uses an org-wide hire today beyond the | ||
| chief-of-staff seat. Then nobody's costs no one a worker, and the step only reports them. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **The link lives in server-owned session state** (the epic's D3, change 3), set by the worker | ||
| flow on a session's first turn after one check: the worker is the session user's own or a | ||
| standard one, it names this flow, and the session has no link yet. Every path that opens a | ||
| session passes that check: a person's turn, a task, a mailbox post. It never changes. | ||
| - **The link is set on the first turn, not at create.** Create runs no flow code; the epic's D3 | ||
| names admission only if flow code can't do it. The door refuses a turn with no link. | ||
| - **A worker's configuration is read on every turn**, from its row or its file, with names | ||
| resolved against what the installation registers ([ER-2](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). | ||
| A non-standard one is checked when it is saved and again when it loads. | ||
| - **A worker's private state is keyed by the worker** on every worker flow, the skills drawer | ||
| first. The skills library takes its key per run, a Layer 2 change; if a capability can't, it | ||
| goes back to the epic (ER-22). | ||
| - **A worker's document and reference grants hold on every turn**, over what its model can | ||
| reach: tools and context. The flow's own code is the app's and is not narrowed per worker. | ||
| - **Ids.** A worker's id is unique on its owner's roster and can't be a standard worker's id. A | ||
| fork gets a new one. | ||
| - **The upgrade step ships as code the operator runs**, not a SQL procedure like FIX-1538's: it | ||
| relinks sessions and copies rows per member, which a hand procedure gets wrong. FIX-1538's own | ||
| *what would change my mind* named this. | ||
| - **Fork and the library's copy share one write path.** FIX-1788 owns it; FIX-1795 calls it | ||
| for a template (the epic's coordination seams). No library work is pulled in here. | ||
| - **A fire deletes the row.** Sessions linked to it stay readable and refuse new turns. | ||
| - **A standard worker has no write path.** It is a read-only collection projected from the files. | ||
| - **Every deprecation marker** on collection cardinality and owner pins names FIX-1798. | ||
| - **The org-wide seat inventory stops listing hired workers**, which it showed to every member. | ||
| - **Four PRs, a stack:** server-owned session state; the worker model beside today's; the | ||
| upgrade step; then the switch, every flow at once. Nothing existing changes shape before the | ||
| step is on `main`, so no single PR strands a hire ([PLAN.md](PLAN.md#sequence--the-pr-plan)). | ||
| - **No worker-flow declaration shape is named.** The epic's [Q1](../../epics/FIX-1786/DECISIONS.md#q1) | ||
| is chosen at FIX-1789's gate. The `agent` flow change takes either. | ||
|
|
||
| ## Considered and dropped | ||
|
|
||
| | Alternative | Why not | | ||
| |---|---| | ||
| | Keep a copy per worker and narrow the pins | Keeps registration per process: a hire or fire waits for a restart elsewhere, and FIX-1798 can never remove pins | | ||
| | The link in plain session state, checked on read | A caller seeds a link to their own other worker through the session create ([epic POC](../../epics/FIX-1786/poc/singleton-worker-link/README.md), O1) | | ||
| | The link in a row only flow code writes, keyed by session id | Outlives a deleted session: a new session at the same id inherits it (POC, R1) | | ||
| | A worker noun in the engine | No consumer outside Workforce (epic [D3](../../epics/FIX-1786/DECISIONS.md#d3)) | | ||
|
|
||
| <a name="q1"></a> | ||
| ## Q1 · open · When a user forks a standard worker, does the fork copy its shared instructions, or keep following them? | ||
|
|
||
| **The fork.** Standard workers in model variants (a Codex, a Claude and a Cursor researcher) | ||
| share core instructions, per the 2026-10-04 lock. A fork can **copy** them, so it never changes | ||
| unless its owner edits it, or **follow** them, so it picks up the installation's later edits. | ||
|
|
||
| **In plain terms.** Alice forks the researcher to change its model. Next month the installation | ||
| improves the researcher's instructions. Under copy, Alice's fork keeps last month's text until | ||
| she forks again. Under follow, it gets the new text, with her model change kept. | ||
|
|
||
| **The trade-off.** Copy is what a library copy does (ER-10): nothing changes under its owner. | ||
| Its cost is forks that go stale. Follow keeps forks current, at the cost of a layered | ||
| configuration: the file, then the user's changes on top, merged on every turn. An edit to the | ||
| files then changes what runs with every forker's access. | ||
|
|
||
| **My recommendation: copy.** One rule for every copy a user holds, fork or library. A fork is | ||
| the user saying they want something different. Follow can be added later as an option on a | ||
| fork; taking it away later would change running workers. | ||
|
|
||
| **What would change my mind:** users who fork mostly to change one setting, while the core | ||
| instructions change every week. Then forks stale at once, and follow earns its layering. | ||
|
|
||
| **If wrong:** forks drift until users re-fork, which costs their edits. Small to reverse: | ||
| follow is additive. | ||
|
|
||
|  | ||
|
|
||
| It comes down to the library's rule: nothing changes under its owner, so forks go stale. | ||
|
|
||
| ## Settled | ||
|
|
||
| - **Which flows a worker names, and where each is defined:** 23 flows over 94 `WORKER.md` | ||
| files, every file classified, the control failing. [`poc/flow-inventory/`](poc/flow-inventory/README.md). | ||
|
|
||
| ## How it got here | ||
|
|
||
| - **Draft** — framed as the epic's privacy spine: workers as user-scoped rows, one copy per flow, | ||
| a server-owned link set once on the first turn; old hires carried by one operator step, an | ||
| org-wide hire copied to the members who used it; four PRs, engine first. | ||
|
|
||
| **Open:** Q1. | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.