Repository navigation
spec(FIX-2080): A task's filing settings and lifecycle: start, session, result and attempts; order and cascade #3595
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
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
9c018ed
spec(FIX-2080): a task's filing settings and lifecycle
claude 19e2e34
spec(FIX-2080): round 1, cascade debt on FIX-2078's wake; loops and s…
claude f1456ef
spec(FIX-2080): round 2 factual corrections: waitingOn settled, dispa…
claude c68f233
Merge origin/main into spec/FIX-2080
claude 775a4cd
spec(FIX-2080): apply cross-spec audit edits
claude 8b612b0
Merge origin/main into spec/FIX-2080
claude 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,108 @@ | ||
| # FIX-2080 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** | ||
|
|
||
| The concept fixed the four settings and both cascades (rules 4, 5, 6, 16); these two carry them | ||
| out. | ||
|
|
||
| ## The tree | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| I["FIX-2080"] --> D1["D1 · one status, held, for not started"] | ||
| D1 -.->|"rejected"| X1["held beside blocked and the recorded mark · three words for one state"] | ||
| I --> D2["D2 · a cascade is a debt recorded with the ending"] | ||
| D2 -.->|"rejected"| X2["cancel after the ending, as the split does · a crash loses it"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing. Dashed edges lost, and the label says why. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · One status, `held`, replaces `blocked` and recorded-not-started | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Adding `held` beside `blocked` and the recorded-not-started mark, and leaving each to its own tool | | ||
| | **Because** | All three mean "filed, not started, until someone says go". `blocked` has no way out (`unblock` has no caller), and the recorded mark is released only by `dispatchTask`, which FIX-2081 removes. Three words for one state is the incoherence the concept retires; one status is what a screen and a filter can show | | ||
| | **Locks in** | The status `held`, the collection verbs `hold` and `release`, and change kinds `held` and `released`, all public. `blocked`, `block`, `unblock` and `blockTask` are removed outright ([(e)](../../epics/FIX-2056/DECISIONS.md#e)); the board's `counts.blocked` becomes `counts.held`. On a Workforce board, `addTask` files held and `dispatchTask { taskId }` releases, until FIX-2081. Rows of both old shapes in a store read as `held` through the map, entries turned on here | | ||
|
|
||
|  | ||
|
|
||
| It comes down to a screen of unstarted work: one word, or three that mean the same. | ||
|
|
||
| **What would change my mind:** a filer that must tell "held by me" from another not-started reason | ||
| it can act on. Held on questions is FIX-2058's, and the concept makes it pending, so it is not one. | ||
|
|
||
| <a name="d2"></a> | ||
| ## D2 · A cascade is a debt recorded with the ending, paid within seconds | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Cancelling after the ending write, best effort, as the split's piece cancel does today | | ||
| | **Because** | A task's filed work sits on another board in another session, so no one write can end both. Recorded in the ending's own write (the ledger's ending recorder already lands debts that way), a crash between the two leaves the cascade owed, and rule 8 says every debt is paid | | ||
| | **Locks in** | One more debt kind: the gate pays it in-process when the task's own session failed or retried, a dispatch into that session pays a cancel from above, and every touch resends it; FIX-2078's sweeper pays it when due. A cascaded cancel records its cause, the task whose ending caused it, server-written, so FIX-2078 can name a failure's dependents in one notice. Dependents on the same board are cancelled right after the ending, with the claim pass as the backstop, so they need no debt | | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
|
|
||
|  | ||
|
|
||
| It comes down to a crash between the two writes: owed, it is paid on restart; best effort, the work runs on. | ||
|
|
||
| **What would change my mind:** a task and the tasks it filed kept in one store write. Then the | ||
| cancel lands in the ending's write, and no debt is needed. | ||
|
|
||
| ## Decided, not asked | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
|
|
||
| - **The settings are fields of the task row, in orchestration.** `held` (start, beside `deps`), | ||
| `session` (`"new"` default or `"ongoing"`; a follow-up stays `followUpOf`), `resultTo` (`"filer"` | ||
| default or `"conversation"`) and `maxAttempts`. Top level and server-written, never in | ||
| `metadata`, since they decide routing (BP-031); absent reads as the default (BP-030). FIX-2081 | ||
| names them on `createTask`. A board refuses at filing a value it can't honour, naming the | ||
| setting: a plain board takes only the defaults; Workforce's takes `ongoing` and `conversation` | ||
| only from a conversation, never from a task's session. | ||
| - **Editable until start, by one guard.** `held`, `deps` and `maxAttempts` may change while the row | ||
| is pending or held; `session`, `resultTo` and `followUpOf` never change (ER-4). The guard is in the | ||
| collection's patch, so FIX-2081's `updateTask` inherits it. | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| - **The convergence points** (tenet 5). *A dependency on this board:* the collection's add and | ||
| patch, on both backings, so `addTask`, `addTasks`, seeded `initialTasks`, replans and the Workforce | ||
| add all pass it; ids in the same batch count. A dependency already failed or cancelled is refused | ||
| too. *One open task per session:* the Workforce board's one start test, read by every start path. | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| Its key is the session the row runs in: the task's own, its root's for a follow-up, the delegate's | ||
| ongoing one; a started, unfinished row holds it, plan rows never. *Cascades:* the ending detection | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| every write goes through (`endingOf`), for `errored`, `cancelled` and `retried`, whoever wrote it: | ||
| the gate, a cancel, a refused hand-over, an abandoned row's settle. | ||
| - **The cascade reaches every board Workforce keeps for the task's session**: its delegation board | ||
| and FIX-2076's plan board. Those are the only boards a task's session files on in the repo. | ||
| - **Dependents keep the `skipped` label** a pattern's output reads, so plan-and-execute and | ||
| supervisor outputs don't change when their step goes. | ||
| - **The map.** One function at the read boundary, beside the `parked` and `wait` migrations, with a | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| switch per entry and one test per shape. Five entries: blocked to held and recorded to held, | ||
| turned on here; a post to a routed task (FIX-2083), a parked split to running (FIX-2077) and a | ||
| reopened row to pending (FIX-2086), built here, turned on by their owners. The epic's D3 named | ||
| four: the recorded mark is the fifth, because D1 retires it here. FIX-2077's entry needs the hold | ||
| field FIX-2077 adds, so it adds that field to this entry, in this map. Removed no earlier than | ||
| FIX-2071. | ||
| - **A wait on a conversation-result task is refused on today's wait**, so T-32 holds now; it moves | ||
| with the wait to `getTask` (FIX-2082). | ||
| - **No POC and no checker.** The premises are read from code (the gaps file's rows, re-read at | ||
| `96404d25`), and no claim here rests on a count. | ||
|
|
||
| ## Considered and dropped | ||
|
|
||
| | Option | Why it lost | | ||
| |---|---| | ||
| | Keep `createCascadeSkipDependents` and wire it on Workforce's board | Two routes to one job, and every new board would have to remember the step (tenet 3) | | ||
| | Settings in Workforce state only | A plain orchestration board would accept a session it can't honour, silently | | ||
| | Keep refusing a follow-up into a busy session | Rule 5 is the owner's: another stays pending | | ||
| | File a dependent of a dead dependency, then cancel it | A filing that ends at once tells the filer less than a refusal | | ||
| | Leave the recorded mark to FIX-2081 | Two not-started states for one more merge, and a sixth map shape later | | ||
|
|
||
| ## Settled | ||
|
|
||
| None yet. | ||
|
|
||
| ## How it got here | ||
|
|
||
| - **Draft** — framed as the epic's ER-4 and ER-6: the settings stored on the row, readiness that | ||
| holds a busy session, two cascades refined from the pattern step and the split cancel, and the | ||
| epic's one read map, with the recorded mark folded into `held`. | ||
|
|
||
| Open: none. | ||
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,155 @@ | ||
| # FIX-2080 · A task's filing settings and lifecycle: start, session, result and attempts; order and cascade | ||
|
|
||
| **Spec** · [Decisions](DECISIONS.md) | ||
|
|
||
| ## Six people, before and after | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
|
|
||
| | Someone who… | Today | After | | ||
| |---|---|---| | ||
| | **files a follow-up to a worker that is still busy** | Is refused, and has to try again later | The follow-up waits, then starts in that session when the open task ends | | ||
| | **files a task that must wait until they say go** | Moves it to *blocked*, and nothing ever unblocks it | Files it *held*; it starts when they release it, and not before | | ||
| | **names a dependency on another board** | The task stays pending for good | The filing is refused, naming the rule: cross boards with a wait or a held task | | ||
| | **has a dependency fail or get cancelled** | The dependent waits for good, unless a pattern wired a cleanup step | The dependent is cancelled, and so are its own dependents | | ||
| | **cancels, retries or fails a task that filed work** | The filed work keeps running, unless the task was a split | Every open task it filed is cancelled within seconds, after a restart too ([D2](DECISIONS.md#d2)) | | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| | **wants a flaky task tried more often** | Gets 2 tries; a post gets 1 | Sets the attempts at filing; the default stays 2 | | ||
|
|
||
| ## The goal, and how we'll know it's met | ||
|
|
||
| **A delegated task runs where, when and how often its filer chose at filing, and nothing waits on | ||
| work that will never finish: no row stays pending for good, no filed task outlives the task that | ||
| filed it, and no busy session refuses a task.** | ||
|
|
||
| | Is it the right goal? | | | ||
| |---|---| | ||
| | **The real need** | *"Work runs in the order it needs, and nothing waits on work that will never finish"* (the issue). The epic's [ER-4](../../epics/FIX-2056/DECISIONS.md#who-owns-what) and [ER-6](../../epics/FIX-2056/DECISIONS.md#who-owns-what), owned here | | ||
| | **Smaller, and rejected** | "Add the four settings." Settings alone leave a dependent of a failed task, and a filed task under a cancelled one, waiting or running for good, and FIX-2083's routed tasks need both cascades | | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| | **Bigger, and not this issue's** | The settings on `createTask` and `updateTask` (FIX-2081). Delivering a result to the conversation (FIX-2078, used by FIX-2083). A task held on questions (FIX-2058). Due times and the sweeper (FIX-2078) | | ||
| | **Not done if** | A row with a dead or foreign dependency stays pending · a filed task survives its parent's cancel, retry or failure, a restart included · `blocked` or the recorded mark is still written · a retired row is dropped or misread · a cascade needs a step a board wires | | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| A["a real engine · durable store · the Workforce session board · deterministic workers"] --> L1["leg a · start: deps, held, another board"] | ||
| A --> L2["leg b · session and result settings"] | ||
| A --> L3["leg c · attempts 3"] | ||
| A --> L4["leg d · cascades, and a kill before one is paid"] | ||
| A --> L5["leg e · retired rows in the store at upgrade"] | ||
| L1 --> R["rows read through the collection · the session each request ran in"] | ||
| L2 --> R | ||
| L3 --> R | ||
| L4 --> R | ||
| L5 --> R | ||
| R -->|"every row ends or runs as filed · none pending for good"| P["PASS · goal met"] | ||
| R -.->|"control · cascades off"| F["must FAIL leg d"] | ||
| ``` | ||
|
|
||
| The check reads stored rows and which session each request ran in, not the board's calls. The | ||
| dashed path is the same run with both cascades switched off, and it must fail. | ||
|
|
||
| | How we verify | | | ||
| |---|---| | ||
| | **Goal check** | `goals/task-board/runs-by-its-filing-settings/` · no model · run by the implementer at completion · verdict in the implementation PR | | ||
| | **Signal** | a: a dependent starts after its dependency ends; a held task starts only on release; a dependency on another board is refused, filing nothing. b: a follow-up filed while its task runs waits, then runs in that task's session; an ongoing task runs in the delegate's session for this conversation; from a task's session both conversation settings are refused, as is a wait on a conversation-result task. c: attempts 3 fails after the third failure, each retry in the same session. d: a cancel, a retry and a final failure each cancel the open filed task; a failed and a cancelled dependency each cancel a two-deep chain; killed between a cancel and its cascade, the child is cancelled on the next touch. e: a seeded blocked row and recorded row read as held and start on release; the other entries read as today | | ||
| | **Input** | Deterministic workers. Another chain depth, attempt count or kill point must pass too | | ||
| | **Anti-game** | No assertions on cascade calls or a stubbed collection: stored rows, and session ids from the request records | | ||
| | **Control that must fail** | `GOAL_CONTROL=no-cascade` must FAIL leg d on *the open filed task is cancelled* and *the dependent chain is cancelled*. Today's `main` must also FAIL leg a on *refused and files nothing* and leg b on *the follow-up stays unstarted* | | ||
|
|
||
| ## What changes | ||
|
|
||
|  | ||
|
|
||
| The four settings become fields of the task, chosen at filing; two cascades run on every board. | ||
|
|
||
| **A flow that files and orders tasks through the collection:** | ||
|
|
||
| ```diff | ||
| await tasks.addTask({ | ||
| goal: "Chart it", | ||
| - deps: ["pull-csv"], // an id from another board waited for good | ||
| + deps: ["pull-csv"], // on this board, or the add is refused | ||
| + held: true, // starts when released | ||
| maxAttempts: 3, // the attempts setting; Workforce defaults it to 2 | ||
| + session: "ongoing", // Workforce: the delegate's session for this conversation | ||
| + resultTo: "conversation", // Workforce: from a conversation only | ||
| }) | ||
| - await tasks.block(id, "waiting on legal") | ||
| - await tasks.unblock(id) | ||
| + await tasks.hold(id) // before it starts | ||
| + await tasks.release(id) | ||
| const plan = sequencer({ name }) | ||
| .then(board.drain) | ||
| - .tap(createCascadeSkipDependents({ name })) // every board cancels dependents now | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| ``` | ||
|
|
||
| A model's `blockTask` goes; `updateTask({ status: "held" | "pending" })` holds and releases until | ||
| FIX-2081 rewrites the tool list. The other settings reach models with FIX-2081's `createTask`. | ||
|
|
||
| **Docs:** update *Orchestration → Task substrate* (`held`, dependencies, cascades), *Orchestration → | ||
| Task board* (the built-in cascade replaces *Cascade-skipping dep-blocked tasks*), *Workforce → | ||
| Delegating work* (the settings, one task per session), *Patterns → Supervisor* and *Plan and | ||
| execute* (no cascade step), and the orchestration, workforce and patterns READMEs. No new page; | ||
| FIX-2081 publishes the shared story. | ||
|
|
||
| ## How a filed task runs | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| F["filing · deps on this board · held or now · session · result · attempts"] --> Q{"ready? · start met · no other open task in its session"} | ||
| Q -->|"yes"| W["work in the chosen session"] | ||
| Q -->|"no"| Q | ||
| W -->|"done"| D["ending"] | ||
| W -->|"fails · attempts left"| R["retry in the same session"] | ||
| W -->|"fails · none left · or cancelled"| D | ||
| R --> C["cascade owed · paid in seconds"] | ||
| D --> C | ||
| C --> K["its open filed tasks cancelled · a failed or cancelled row's dependents cancelled"] | ||
| ``` | ||
|
|
||
| Each ending records what it owes in the same write, so a crash leaves the cascade owed, not lost. | ||
|
|
||
| ## What stays as it is | ||
|
|
||
| - **Patterns.** Plan boards as they stand; a dependent of a failed step still ends `cancelled` with | ||
| the `skipped` label their outputs read. | ||
| - **Who settles a row.** The claim gate and the drain (ER-1); a cascade's cancel is a cancel, the | ||
| same write a user's is. | ||
| - **Splits, posts, reopen and `dispatchTask`.** Their children retire them and turn on their map | ||
| entries; this issue only builds those entries. | ||
| - **How a retry re-enters its session**, and the attempts' default of 2 on Workforce boards. A plain | ||
| collection's unset `maxAttempts` still means one try. | ||
|
|
||
| ## What's already here, and the debt | ||
|
|
||
| | Already here | What this does with it | | ||
| |---|---| | ||
| | The job, *end what depends on a dead task*: `createCascadeSkipDependents`, a step two patterns tap after a drain, for `errored` only; the split's piece cancel, the only parent cascade. Closest for each half | **Refines.** The first moves into the collection's ending, for failed and cancelled; the second becomes every task's cascade. The step goes | | ||
| | `maxAttempts` on every row: 2 on Workforce boards, 1 for posts | **Builds on.** It is the attempts setting | | ||
| | `followUpOf`, the earlier task's session, refused while its session is busy | **Builds on.** The refusal becomes a wait (rule 5) | | ||
| | `blocked`, and the recorded-not-started mark `dispatchTask` releases | **Replaced** by one status, `held` ([D1](DECISIONS.md#d1)) | | ||
| | The read-boundary migrations for `parked` and `wait` (BP-030) | **Built beside.** The retired-shape map sits at the same boundary | | ||
| | The epic's [D3](../../epics/FIX-2056/DECISIONS.md#d3), [ER-4, ER-6](../../epics/FIX-2056/DECISIONS.md#who-owns-what) | **Kept**, with a fifth map entry ([decided](DECISIONS.md#decided-not-asked)) | | ||
|
|
||
| | The debt | | | ||
| |---|---| | ||
| | **Removes** | `blocked`, `block`, `unblock`, `blockTask` · the recorded-not-started mark · `createCascadeSkipDependents` · the busy-session refusal · the split-only cancel cascade · a dependency id that never resolves | | ||
| | **Adds** | `held`, `hold` and `release` · the `session` and `resultTo` fields · a cascade debt on the ending · the retired-shape map, removed no earlier than FIX-2071 | | ||
| | **Leaves** | A cascade owed after a crash is paid on the next touch until FIX-2078's sweeper pays it on time · the refusal of a wait on a conversation-result task lives on today's wait, and moves with it to `getTask` (FIX-2082) | | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
|
|
||
| **Net: down.** A status, a mark, a cascade step and a refusal go; one status replaces two, and two | ||
| fields arrive. The map is debt by design, with a removal date. | ||
|
|
||
| ## Sign off | ||
|
|
||
| **[The goal](#the-goal-and-how-well-know-its-met), at that size:** every task runs as filed, and | ||
| nothing waits or runs for good. If wrong: FIX-2083's routed tasks orphan their work. | ||
|
|
||
| **[The debt](#whats-already-here-and-the-debt), net down:** two not-started states become one, | ||
| and one cascade replaces two partial ones. If wrong: two fields only Workforce reads. | ||
|
|
||
| 1. **[D1](DECISIONS.md#d1) · One status, `held`, replaces `blocked` and recorded-not-started.** | ||
| If wrong: apps outside the repo reading `blocked` rewrite at upgrade for nothing. | ||
| 2. **[D2](DECISIONS.md#d2) · A cascade is a debt recorded with the ending, paid within seconds.** | ||
| If wrong: for a few seconds a cancelled task's filed work still spends. | ||
|
|
||
| **Open: none.** Number 1 is the one to weigh: it changes a status screens show. | ||
|
|
||
| Feature · `orchestration` + `workforce` + `patterns` · large · epic [FIX-2056](../../epics/FIX-2056/SPEC.md) | ||
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.