Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
spec(FIX-1788): review round 1 — standard-only, writtenBy, racing lin…
…ks, upgrade collisions

Folds: BR-6/22a/33a apply FIX-1789's standard-only flag on save, load and
the step; BR-25a stamps writtenBy from the link (FIX-1789 BR-20/D1);
BR-13a makes the first-turn link atomic; BR-19a narrows readability of a
session whose flow is gone to today's engine behaviour; BR-30/31 copy
org-wide memory and rename on id collision instead of skipping (D2).
Below-the-bar feedback recorded verbatim in PLAN.md -> Notes from review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
  • Loading branch information
claude committed Oct 6, 2026
commit de74ddeab9bb476be157e03271a6a22bbefd3684
15 changes: 10 additions & 5 deletions specs/issues/FIX-1788/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[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; Carol is in another. The
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.

Expand All @@ -15,7 +15,7 @@ work.
| 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 fails the flow's schema | Refused when saved, with the flow's own reason. Nothing written | CI |
| 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 |
Expand All @@ -29,12 +29,14 @@ work.
| 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 |
Comment thread
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, or its flow is no longer registered | The turn is refused, naming why. The session stays readable | 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

Expand All @@ -43,9 +45,11 @@ work.
| 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

Expand All @@ -60,10 +64,11 @@ work.
|---|---|---|---|
| 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. Members without one get none | CI · VG leg c |
| BR-31 | A copy's id is already on that member's roster | That member's copy is skipped and reported. Nothing overwritten | CI |
| 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

Expand Down
5 changes: 3 additions & 2 deletions specs/issues/FIX-1788/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,15 +45,16 @@ runs on a user's first load instead, with the old machinery kept until every use
|---|---|
| **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. The old row stays, reported, so it can become a library template once [FIX-1795](https://linear.app/fixpoint-labs/issue/FIX-1795) ships |
| **Locks in** | One worker becomes several independent ones: a change one member makes reaches no other. What the worker remembered for the whole org is copied into each, and every one of them could already read it. A copy whose id the member already uses takes a derived id, reported. The old row stays, reported, so it can become a library template once [FIX-1795](https://linear.app/fixpoint-labs/issue/FIX-1795) ships |

![D2: where a worker hired for the whole org goes. A copy for each member who used it, chosen, beside nobody until an operator names one. Decides it: what each person already had. Price: one worker becomes several that drift apart. Flips if teams relied on one shared memory changing together](figures/d2-org-wide-hire.svg)

It comes down to what each person already had: nobody loses a worker, nobody gains one.

**What would change my mind:** teams that rely on one org-wide worker's memory changing for
everyone at once. Then the right home is the library or a shared resource, and the step should
hold the hire for the operator instead.
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

Expand Down
11 changes: 7 additions & 4 deletions specs/issues/FIX-1788/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ Title *Hiring, forking and firing workers*, sidebar label *Hiring and forking*.
>
> `hire` takes an id, the flow the worker runs on, and its settings, the same keys a
> `WORKER.md` accepts. The worker's flow checks the settings when the row is saved. A bad
> value, a flow your installation doesn't run workers on, or an id already on the user's roster
> value, a flow your installation doesn't run workers on or keeps for standard workers, or an id
> already on the user's roster
> is refused, and nothing is written. An id can't be a standard worker's: fork it instead.
>
> ## Forking a standard worker
Expand Down Expand Up @@ -126,10 +127,12 @@ Title *Hiring, forking and firing workers*, sidebar label *Hiring and forking*.
>
> - A worker one user hired becomes that user's worker, with its memory and its conversations.
> - A worker hired for a whole organization becomes a private copy for each member who has a
> conversation with it, with that member's conversations. Members who never used it get none.
> conversation with it, with that member's conversations and a copy of its memory. Members
> who never used it get none.
> Each copy then changes on its own.
> - A worker whose flow your app no longer runs, or whose id a member already uses, is
> reported and left where it is.
> - A worker whose id its new owner already uses comes across under a new id, and the report
> names both.
> - A worker whose flow your app no longer runs is reported and left where it is.
>
> Nothing is deleted. The earlier rows stay, and running the step again changes nothing it
> already moved.
Expand Down
Loading
Loading