Repository navigation
spec(FIX-1875): dispatchTask, one tool that starts a task on another worker now, and can wait for it #3140
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-1875): dispatchTask, one tool that starts a task on another worker now, and can wait for it #3140
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
dd26055
spec(FIX-1875): dispatchTask, one tool that starts a task on another …
jhoffner 95f5663
spec(FIX-1875): review round 1 — undispatched mark, post form, reader…
jhoffner 6f3d4dc
spec(FIX-1875): restraint pass — docs and changeset in P2 only, goal …
jhoffner 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,78 @@ | ||
| # FIX-1875 · Business rules | ||
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| The cases, written as rules. Each says what a person or the system does and what happens. The | ||
| *proved by* column is the check the plan runs. "The board" means a conversation's board unless a | ||
| row says otherwise. Epic rules this issue owns are ER-1 to ER-4; every row below serves one. | ||
|
|
||
| ## Recording work | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-1 | `addTask` (tool or action) records a row with an assignee | The row is pending and not dispatched. No run, no task session, however often the board is touched | CI · goal `rec:not-started` | | ||
| | BR-2 | `addTask` records a row with no assignee, in a conversation with one delegate | It is given that delegate, as today, and is still not dispatched | CI | | ||
| | BR-3 | `assignTask` names a new owner for a recorded row | The owner changes; the row stays recorded | CI | | ||
| | BR-4 | `assignTask` moves a row that was already dispatched and not yet claimed | It moves and starts, as today: the dispatch already happened | CI | | ||
| | BR-5 | A row filed before this change has an assignee and no mark | It starts as it does today (BP-030) | CI, a row written in the old shape | | ||
| | BR-6 | Flow code writes the board directly | Today's behaviour: an assigned row starts | Existing suite | | ||
| | BR-7 | `addTask` runs on a board a drain runs (`taskBoard()`, a pattern) | Exactly as today. No mark, no `dispatchTask` in the tool list | Existing suite | | ||
|
|
||
| ## Dispatching work | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-8 | `dispatchTask({ goal, … })` | A row is filed ready and the board starts it now. The call returns its id at once | CI · goal `disp:new-runs` | | ||
| | BR-9 | `dispatchTask({ taskId })` names a recorded row | The mark clears and the row starts. With `assignee`, the owner is set in the same write | CI · goal `disp:ref-runs` | | ||
| | BR-10 | `dispatchTask({ taskId })` names a row that is claimed, running, ended, or already dispatched | Refused, naming its state. Nothing changes | CI | | ||
| | BR-11 | `dispatchTask({ taskId })` names a row not on the caller's own board | `task_not_found`. Nothing changes | CI · goal `lineage:refused` | | ||
| | BR-12 | More than one of `goal`, `taskId` and `post`, or none | Refused before anything is written | CI | | ||
| | BR-13 | `taskId` with a field that only a new row takes (`deps`, `input`, `followUpOf`, …) | Refused before anything is written. To change a recorded row, `updateTask` first | CI | | ||
| | BR-14 | Every check `addTask` runs (assignee on the roster, follow-up rules, chain depth and breadth, caps) | `dispatchTask` runs the same checks, in the same order, with the same errors | CI, one test per check | | ||
| | BR-15 | The same `dispatchTask` call replays after a crash or a resume | One row, one start. For `taskId` too: the ready write records the call that made it, so a replay finds its own write and answers as the first call did, not with BR-10's refusal | CI, a crash between the ready write and the step's record · the FIX-1820 rerun | | ||
| | BR-24 | `dispatchTask` with no `assignee`, where the conversation has no single delegate to default to (or a `taskId` row that has no owner) | Refused, `assignee_required`, nothing written. It never reports a start the board can't make | CI | | ||
| | BR-25 | `assignTask` and a `dispatchTask({ taskId })` race on the same recorded row | Both writes are conditional, so they apply one after the other: the later write's owner stands, and the row starts once | CI, the two writes interleaved both ways | | ||
| | BR-26 | `post: true`, on a coordinator turn that is routing a post | The routed post is the task, filled from the server; only `assignee` and `target` are taken. `post: true` is the only discriminator; the call carries no `goal` (with one, BR-12 refuses it). Off such a turn, `post` isn't in the schema. FIX-1872 builds it; this issue keeps the schema open to it | FIX-1872's checks | | ||
|
|
||
| ## Waiting for the result | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-16 | `dispatchTask({ …, wait: true })` | Today's ask, unchanged: one row per call, one wait per step, the turn parks, the row's output is the result, or an error naming how it ended (`wait_*`) | The FIX-1816 rerun · existing ask suite, renamed | | ||
| | BR-17 | `wait` on a recorded row (`taskId`) that is pending, unclaimed and not waited on | It is marked waited-on and dispatched in one write, then the turn parks as in BR-16 | CI | | ||
| | BR-18 | `wait` where the host or board can't hold one, or from a task turn | `wait` and `timeoutMs` aren't in the schema; a direct caller that sends them anyway gets `wait_unavailable`, nothing written. The refusal reads the call's input before the schema would strip an unknown field | CI, a direct call with `wait: true` | | ||
| | BR-19 | `timeoutMs` without `wait`, or outside 30 seconds to an hour | Refused, nothing written, never clamped | CI | | ||
| | BR-20 | The `dispatchTask_<board>` action | Never waits; it has no `wait` field | CI | | ||
|
|
||
| ## The old surface | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-21 | `addTask` gets `waitForResponse` or `timeoutMs` | Refused by name, the message points at `dispatchTask`, nothing filed. Read before the schema would strip it, as in BR-18 | CI (V6) · the epic closure's sweep | | ||
| | BR-22 | Code imports a retired name | It fails to compile. The changeset gives each new name | Typecheck · the sweep's `--assert` | | ||
| | BR-23 | The model reads `addTask`'s description | It says `addTask` records and doesn't start, and points at `dispatchTask` | CI on the description · the FIX-1816 rerun | | ||
| | BR-27 | `addTask` (tool or action) records a row on a board that dispatches | Its result carries `status: "recorded"` and a one-line note that the task starts on `dispatchTask`. A model that skipped the description, or a script that logs the result, sees it | CI on the result | | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| A["addTask · assignTask"] -->|"recorded · not dispatched"| R["the row"] | ||
| D["dispatchTask"] -->|"ready"| R | ||
| O["a row filed before this"] -->|"no mark · ready"| R | ||
| R -->|"the board's one test · ready rows only"| S["start"] | ||
| ``` | ||
|
|
||
| Every path into a row ends at one test for "can start". A second test anywhere (a claim's | ||
| eligibility, the drain's exit, `addTask`'s own wake, the `setAssignee` and `unpark` wakes) that | ||
| doesn't read the mark starts a recorded row. | ||
|
|
||
| ## Failure taxonomy | ||
|
|
||
| Every refusal is a soft `{ ok: false, error }` the model can act on, written before anything is | ||
| stored. A failed wake leaves a ready row ready, for the next touch, as today. Nothing retries | ||
| inside the tool. A wait that ends without an answer is today's `wait_*` set, unchanged. | ||
|
|
||
| ## Acceptance criteria this issue owns | ||
|
|
||
| [The goal](SPEC.md#the-goal-and-how-well-know-its-met): its check passes on the FIX-1817 lab | ||
| after `GOAL_CONTROL=add-starts` and today's `main` fail it; the three regression checks pass with | ||
| diffs the rename map explains; and the sweep's `--assert` exits 0. |
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,126 @@ | ||
| # FIX-1875 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| What was considered, what was chosen, why, and what each choice locks in. Two decisions are the | ||
| sign-off surface. The epic already decided the tool exists, that waiting moves onto it, and that | ||
| the board tools only record ([FIX-1870 D1](../../epics/FIX-1870/DECISIONS.md#d1), ER-1 to ER-4); | ||
| these two are what that costs on the real code. | ||
|
|
||
| ## The tree | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| I["FIX-1875"] --> D1["D1 · a recorded task doesn't start until dispatched"] | ||
| D1 -.->|"rejected · two tools still start work"| X1["addTask keeps starting work on a conversation's board"] | ||
| I --> D2["D2 · addTask's fields plus wait, flat · goal, taskId or post"] | ||
| D2 -.->|"rejected · every changed call stops being a rename"| X2["a nested task new-or-ref envelope"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing. Dashed edges lost, and the label says why. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · On a conversation's board, `addTask` and `assignTask` stop starting work; a recorded task doesn't start until `dispatchTask` | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Keeping today's start: on a conversation's board, a row with an assignee starts at once, so `dispatchTask` without `wait` is a second name for `addTask` with an assignee | | ||
| | **Because** | A conversation's board starts every row that is pending and assigned, on any touch ([`board.ts`](../../../packages/workforce/src/conversation-board/board.ts), the guarded `addTask` and the resolver's wake). So "the board decides when it runs" is false there unless a row can be recorded *without* being ready. Without that, two tools start work, and the model still has to pick: the problem the epic exists to remove (tenet 2: one primitive per job). Every other board is drained by its owner and already only records | | ||
| | **Locks in** | A recorded row carries a persisted mark, *not dispatched* (`undispatched`, never "waiting": FIX-1876 keeps *wait* for a turn parked on a task), written only by the task tools and actions on a board that dispatches. A row without the mark (every row filed before this) still starts as today. Code that writes the board directly is untouched. `addTask`'s result says `status: "recorded"`, so the change is visible on the first call, not only in the changeset. Every caller that relied on `addTask` or `assignTask` starting work moves to `dispatchTask` in this issue: the [sweep](PLAN.md#the-sketch-and-the-poc) lists 14 goal checks (26 files, plus 3 shared lab helpers), 3 worker files, 2 published pages and the workforce README. An app that sends `addTask_tasks` to start work must switch, and the changeset says so | | ||
|
|
||
|  | ||
|
|
||
| It comes down to the tool choice: keep start-on-assign and the model still picks between two tools. | ||
|
|
||
| **What would change my mind:** one of the three regression checks can't pass with a rename-only | ||
| diff once `addTask` stops starting work. That is the epic's kill line, and it goes back to the | ||
| epic (ER-14). | ||
|
|
||
| <a name="d2"></a> | ||
| ## D2 · `dispatchTask` takes `addTask`'s fields plus `wait` and `timeoutMs`, flat, with `taskId` for a recorded row and `post: true` for a routed post | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | The issue's sketch: `dispatchTask({ task: { new } \| { ref }, to, wait: true \| { timeoutMs } })`. For FIX-1872's post form, also instead of a second tool, or a routing turn that can only post | | ||
| | **Because** | The epic's proof is that the three regression checks change only by a rename map ([ER-11](../../epics/FIX-1870/BUSINESS-RULES.md#what-no-child-may-do)). With a flat shape, `addTask_tasks` → `dispatchTask_tasks` and `waitForResponse` → `wait` are the whole map. A nested envelope rewrites every call, so no changed line is a rename, and a reviewer can't tell a reshaped call from a changed assertion. A flat object is also what a model fills most reliably, and what OpenAI strict mode accepts without a union (BP-016) | | ||
| | **Locks in** | A public tool and action shape. Exactly one of three says what starts, checked when the call runs, not by the schema: `goal` (a new row, in the caller's words), `taskId` (a recorded row), or `post: true` (the post a coordinator turn is routing, filled from the server). The model tells the forms apart by which one it sets, the same rule for all three. `post: true` is the single discriminator for the post form, never a missing `goal`: the routed post is the task, so a post-form call carries no `goal`, and `goal` with `post` is refused (BR-12). That reserves the post form for FIX-1872 without overloading `goal`'s absence, which `taskId` already uses. `post` and `target` are in the schema only on a coordinator turn that is routing a post; with `post`, only `assignee` and `target` are taken. The recipient is `assignee` in every form, with its default (the conversation's only delegate), so FIX-1872's `to` reads as `assignee`. FIX-1872 builds the post form; this issue leaves the schema open to it. A second tool was rejected because two starting tools is what the epic removes; a post-only routing turn because FIX-1872 D2 keeps a coordinator able to file an ordinary task on that turn | | ||
|
|
||
|  | ||
|
|
||
| It comes down to the proof: a flat shape keeps the regression diffs a rename map; the envelope | ||
| rewrites every call. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **`dispatchTask` is offered only on a board that can start work now** (a conversation's board | ||
| today). A drained board has nothing to start a row with, so the tool would lie there. | ||
| - **`wait` is offered exactly where `waitForResponse` was:** a board that resumes waits, on a host | ||
| that can hold and bound one. Elsewhere the fields are absent from the schema, as today. | ||
| - **The action form never waits**, as the `addTask_<board>` action never did. | ||
| - **`waitForResponse` and `timeoutMs` on `addTask` are refused by name**, with a message naming | ||
| `dispatchTask`, never stripped by the schema (BP-030). A silent strip would file the task and | ||
| return at once to a model that thinks it waited. | ||
| - **Waiting on a recorded row is allowed** when the row is pending, unclaimed and not already | ||
| waited on. The mark and the wait are written in one write. | ||
| - **A recorded row is reachable only on the caller's own board.** The board resolver already | ||
| reads the running session's own partition, so a row elsewhere is `task_not_found` (ER-4 holds by | ||
| construction; the goal check's `lineage:refused` proves it). | ||
| - **The public ask names go with no alias** ([pinned map](PLAN.md#pinned-names)): the closure | ||
| fails while a retired name is exported, and the packages are pre-1.0. **Where the line falls | ||
| with FIX-1876:** this issue renames every exported name a caller of the waiting surface imports | ||
| (the map, `canHoldAsk` and the `Ask*Error`s included). The host seam's names (`resumeAsk`, | ||
| `hasAskSweeper`, `parkOnAsk`, `resumesAsks`, `row.ask`) are not imported by callers and stay for | ||
| FIX-1876, which starts after this merges and keeps what this renamed (its WR-22). Where both | ||
| maps name a symbol they agree (`AskEndedError` → `WaitEndedError`). | ||
| - **`assignTask` on a recorded row keeps it recorded.** `answerTask` still re-queues a row that | ||
| was already started, as today: that row was dispatched once. | ||
| - **`dispatchTask` refuses a row with no owner.** With no `assignee` and no single delegate to | ||
| default to, it answers `assignee_required` and writes nothing, so it never reports a start the | ||
| board can't make (BR-24). | ||
| - **`onTimeout: "continue"` is not built** (the epic dropped it: new behaviour no rerun proves). | ||
| - **The coordinator's `handOff` is left alone.** FIX-1872 retires it with the ledger | ||
| ([EM call](https://linear.app/fixpoint-labs/issue/FIX-1875), 2026-10-12). | ||
| - **The issue's open questions** — rows per delegate on the everyone policy, and whether `to` may | ||
| be a coordinator — are FIX-1872's ([epic D2](../../epics/FIX-1870/DECISIONS.md#d2)) and the | ||
| roster's: `assignee` is checked against the board's roster, unchanged. | ||
|
|
||
| ## Which methods already do this job | ||
|
|
||
| The job: *start work on another worker now, optionally waiting for it.* Searched `packages/` for | ||
| `addTask`, `assignTask`, `handOff`, `createHandOff`, `dispatcher`, `waitForResponse`, `park`, | ||
| `resume`, `wake`: | ||
|
|
||
| | Entry | Does the job how | After this issue | | ||
| |---|---|---| | ||
| | `addTask` with an assignee, on a conversation's board | Records, and the board's wake starts it | Records only (D1) | | ||
| | `assignTask`, on a conversation's board | Moves, and the wake starts it | Records only (D1) | | ||
| | `addTask({ waitForResponse })` / `addTaskAndWait` | Records, starts, parks the turn | **Closest entry.** Becomes `dispatchTask({ wait })`; differs only by a flag, so it is that parameter (D2) | | ||
| | The coordinator's `handOff` tool | Delivers a post through the delivery ledger | FIX-1872 | | ||
| | `createHandOff` (a `taskBoard()` worker) | A drain hands a claimed row to another session | Unchanged: the drain's own start, not a model tool | | ||
| | `dispatcher()` | Flow-code transport, no row | Unchanged ([ER-12](../../epics/FIX-1870/BUSINESS-RULES.md#what-no-child-may-do)) | | ||
|
|
||
| ## Considered and dropped | ||
|
|
||
| | Alternative | Why not | | ||
| |---|---| | ||
| | A new conversation-board scheduler that starts recorded rows later by itself | Nothing needs it. "Later" today means a person or a worker deciding, which is a dispatch | | ||
| | Mark ready rows instead of waiting ones | Every row filed before this lacks the mark and would stop starting on upgrade. Marking the waiting ones leaves old rows as they are (BP-030) | | ||
| | Hold rows in `addTask` at the ledger, not in the tools | Flow code that writes the ledger directly (DevTeam's EM row filing) would stop starting work, a change ER-2 doesn't ask for | | ||
| | A wrapper tool over `addTask` | The implementer note from the epic review: build dispatch into the task tools and the board, so there is one filing path | | ||
| | Alias the old names for a release | The closure's sweep fails while one is exported; pre-1.0 patch notes carry the map instead | | ||
| | Use the existing `blocked` status for a recorded row, so no new field | `blocked` means a row can't proceed: its reason is stored in `error`, it emits a `blocked` change event, and it returns to pending only through `unblock`. A recorded row is healthy and ready to go on request, so an app reading `blocked` would show it as stuck | | ||
| | Drop `taskId`: "record for later" is an unassigned `addTask`, and `dispatchTask({ goal })` is the only start | Once `assignTask` stops starting work, a recorded row has no way to start except by id; the only other move files a duplicate and orphans the original. The DevTool's row actions also work on an existing row (`works-a-task-from-its-row`) | | ||
|
|
||
| ## How it got here | ||
|
|
||
| - **Draft** — framed as the epic's substance: one starting tool, and board tools that only | ||
| record. Found that a conversation's board starts any assigned row, so ER-2 needs a persisted | ||
| waiting-for-dispatch mark (D1), and that the regression proof needs a flat input shape (D2). | ||
| Built as two PRs: the tool and the callers' move, then the switch-off. | ||
| - **Review round 1** — the mark is `undispatched`, not `awaitingDispatch`, because FIX-1876 | ||
| makes *wait* mean only a parked turn and a stored name is costly to change later. D2 gained | ||
| the post form, because FIX-1872 gives `dispatchTask` a second meaning on routing turns and the | ||
| two specs drew it differently. Every start test now reads the mark in P1, before anything writes | ||
| it in P2, because a rolling deploy would otherwise run P1 processes that start a P2 recorded row. | ||
|
|
||
| **Open: none.** | ||
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This bullet says host seam names are FIX-1876’s, but the pinned map still retires
canHoldAskand ask-prefixed errors/constants in this issue. Worth reconciling so reviewers aren’t left guessing whether P2 removes those symbols or only renames them in docs.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same fold as the PLAN thread (95f5663): the bullet now states the boundary explicitly, exported names here, internal seam in FIX-1876.