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
108 changes: 108 additions & 0 deletions specs/issues/FIX-2080/DECISIONS.md
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 |

![D1: one status for not started. Held replaces blocked and the recorded mark, chosen, beside held added beside them. Decides it: a screen listing work that has not started. The price: apps outside reading blocked rewrite at upgrade](figures/d1-one-held.svg)

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 |
Comment thread
jhoffner marked this conversation as resolved.
Resolved
Comment thread
jhoffner marked this conversation as resolved.
Resolved

![D2: how a task's filed work is cancelled. A debt recorded with the ending, chosen, beside cancelling after it. Decides it: a crash between the ending and the cancel. The price: a few seconds in which the filed work still runs](figures/d2-cascade-debt.svg)

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
Comment thread
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.
Comment thread
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.
Comment thread
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
Comment thread
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
Comment thread
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.
155 changes: 155 additions & 0 deletions specs/issues/FIX-2080/SPEC.md
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
Comment thread
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)) |
Comment thread
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 |
Comment thread
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

![Today against after, for start, session, result, attempts, endings and upgrade: blocked, refusals and opt-in cleanup become held, a waiting session, two cascades on every board and one read map](figures/what-changes.svg)

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
Comment thread
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) |
Comment thread
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)
Loading
Loading