Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
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
33 changes: 19 additions & 14 deletions specs/issues/FIX-1788/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,32 +11,37 @@ work.
| # | 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-2 | Alice forks a standard worker | A new worker of hers, with a copy of its configuration and shared instructions, under a new id ([D3](DECISIONS.md#d3)). A later edit to the files doesn't change it. 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 |
| BR-9 | Alice lists her roster | Her own workers and every standard worker, each marked standard or hers and naming the flow it runs on (`flow`). Nothing of Bob's, nothing from another org | CI · VG |

## A session's worker

| # | When | Then | Proved by |
|---|---|---|---|
| BR-10 | Alice's first turn in a session names her worker, on the flow it names | The server links the session to it and runs the turn as it | CI · VG leg a |
| BR-11 | A first turn names a worker of Bob's | Refused with the same answer as a worker that doesn't exist. Nothing linked | CI · VG leg b |
| BR-12 | A first turn names a worker of Alice's on another flow | Refused, naming both flows. Nothing linked | CI · VG leg b |
| BR-13 | A later turn names a different worker | Refused. The link never changes. A later turn may omit the worker | CI |
| BR-13a | Two first turns on one unlinked session arrive together, naming different workers | One links and runs. The other is refused as BR-13, and its worker never runs | CI |
| BR-14 | A turn arrives on a session with no link and names no worker | Refused, saying a worker must be named | CI |
| BR-15 | A session is created with caller state for the link | Refused with 400, naming the field. Nothing written | CI · VG control `caller-link` |
| BR-16 | A session is deleted and its id created again | The new session has no link | CI |
| BR-10 | Alice creates a session naming her worker, on the flow it names | The server checks it at create and links the session to it, in a field only the server writes. Every turn runs as that worker | CI · VG leg a |
| BR-11 | A create names a worker of Bob's | Refused with the same answer as a worker that doesn't exist. No session written | CI · VG leg b |
| BR-12 | A create names a worker of Alice's on another flow | Refused, naming both flows. No session written | CI · VG leg b |
| BR-13 | A turn's input carries `worker`, or any route tries to change a session's link | Refused, naming the field. The link never changes: another worker is another session | CI · VG leg b |
| BR-13a | Two `ensureWorkerSession` calls with the same criteria race | One session is created and both return it. Two plain creates make two sessions, each checked | CI |
| BR-13b | A create uses a derived worker-session id that belongs to another user | Refused. Nobody can take Alice's id before her first `ensureWorkerSession` | CI |
| BR-14 | A session on a worker flow is created with no worker, by the create, by an action on a session id that doesn't exist, or by `fsdev run` without `--worker` | Refused at the door, saying a worker must be named. No session written | CI · VG leg b |
| BR-14a | Alice calls `findWorkerSession({ worker })`, or lists with a `worker` filter | Her sessions linked to that worker, most recent first for the helper; none if there are none. Never another user's | CI · VG leg b |
| BR-15 | A session is created with caller state for the link or a server-written field | Refused with 400, naming the field. Nothing written | CI · VG control `caller-link` |
| BR-16 | A session is deleted and its id created again | The new session's link is what its own create named and passed. Nothing carries over | CI |
| BR-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-18 | A task or a mailbox post opens a session for a worker | It names the worker at create, through the same check as BR-10 to BR-12, on the session's user. The worker comes from the dispatching flow's code, never the post's fields | CI |
| BR-18a | A coordinator's session records its delegates after create | Held in server-written session state: flow code writes it, a caller can't (BR-15), and the link beside it stays fixed. FIX-1791 consumes it. Its delivery opens each delegate's session through `ensureWorkerSession`, with the worker and FIX-1791's coordinator-conversation key named; it can't post to a fresh id and rely on the turn (BR-14) | CI, on a fixture flow |
| BR-19 | A linked worker is fired | The turn is refused, naming it as fired. The session stays readable | CI |
| BR-19a | A linked worker's flow is no longer registered | The turn is refused. The session reads as a session of any unregistered flow reads today: this issue adds no engine read path (ER-22) | CI |
| BR-19b | Alice edits a worker to name a different flow | The link holds. A turn on a session created before the edit is refused, naming both flows. New sessions are created on the new flow: `ensureWorkerSession` finds none there and creates one at a new id | CI |
| BR-19c | Alice forks a worker she already has sessions with | The fork is a new worker with no sessions. Those sessions stay with the original | CI |

## What a worker runs with

Expand All @@ -49,7 +54,7 @@ work.
| 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 |
| BR-25a | Two of Alice's workers on one flow write a shared resource | Each entry's `writtenBy` names Alice and, as `workerId`, the worker its session is linked to: two workers, two ids. The worker comes from the link, never the input ([FIX-1789](https://linear.app/fixpoint-labs/issue/FIX-1789) BR-20, D1) | CI |

## One copy per flow

Expand All @@ -63,7 +68,7 @@ work.
| # | 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-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 the step sets each of its sessions' link, the one write besides a create | 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 |
Expand All @@ -72,7 +77,7 @@ work.

## Failure taxonomy

A refused link, a refused turn and a refused write change nothing and name why. A configuration
A refused create, 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.
Expand Down
Loading
Loading