From 4116deecfc67eed44e1c64c17b9fc23e02c2a9c9 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 16:22:04 +0000 Subject: [PATCH 01/10] spec(FIX-2129): a stop for a person holds its task waitForUser on ctx.suspend, the person mark keyed on one predicate with the stop recorded on the row, four endings through one fence, and one trusted answer route. FIX-2130 folded in, as the epic decided. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Vdxnv28JumHyq2za2ybqz6 --- specs/issues/FIX-2129/DECISIONS.md | 107 +++++++++++++ specs/issues/FIX-2129/SPEC.md | 145 ++++++++++++++++++ .../FIX-2129/figures/d1-deadline-throws.svg | 101 ++++++++++++ .../FIX-2129/figures/d2-answer-route.svg | 100 ++++++++++++ .../issues/FIX-2129/figures/what-changes.svg | 90 +++++++++++ 5 files changed, 543 insertions(+) create mode 100644 specs/issues/FIX-2129/DECISIONS.md create mode 100644 specs/issues/FIX-2129/SPEC.md create mode 100644 specs/issues/FIX-2129/figures/d1-deadline-throws.svg create mode 100644 specs/issues/FIX-2129/figures/d2-answer-route.svg create mode 100644 specs/issues/FIX-2129/figures/what-changes.svg diff --git a/specs/issues/FIX-2129/DECISIONS.md b/specs/issues/FIX-2129/DECISIONS.md new file mode 100644 index 0000000000..31ef2d7669 --- /dev/null +++ b/specs/issues/FIX-2129/DECISIONS.md @@ -0,0 +1,107 @@ +# FIX-2129 · Decisions + +[Spec](SPEC.md) · **Decisions** + +Most of this issue was decided above it: the concept's rule 12, and the epic's ER-1, ER-2, ER-3, +ER-7 and D3. Two calls are left, both about the surface the later children write against. + +## The tree + +```mermaid +flowchart TD + I["FIX-2129"] --> D1["D1 · at the deadline a question or review throws, an approval is a no"] + D1 -.->|"rejected · a flow that never checks carries on with no answer"| X1["always return a no-answer outcome"] + I --> D2["D2 · an answer route that takes only the stop's id and the answer"] + D2 -.->|"rejected · caller gate data re-enters a task's handler"| X2["open the resume route to task runs behind a check"] +``` + +Solid edges are what you're signing. Dashed edges lost, and the label says why. + + +## D1 · At its deadline, a question or review throws an error the block may catch; an approval reads as a no + +| | | +|---|---| +| **Instead of** | Always returning a "no answer by the deadline" outcome, as a wait on a task does, for the block to branch on | +| **Because** | The concept says an unhandled deadline fails a question's or review's try, using an attempt. With a returned outcome nothing can tell a block that handled it from one that forgot, so the forgetful one carries on with an empty answer and nobody sees it. A thrown error is unhandled exactly when nobody catches it. An approval needs neither: a no is a safe default, so it returns `answer: false` with a deadline flag | +| **Locks in** | `ctx.waitForUser` returns the answer or `cancelled`, and throws a deadline error a block tells apart with one exported check. FIX-2131 to FIX-2133 and every app that asks a person write against this; changing it later changes every asking block. The wait gate keeps its returned deadline: it carries on by default, which a person's question must not | + +![D1: a question throws and an approval is a no, chosen, beside always returning a no-answer outcome. Decides it: a flow that never checks. Price: a catch around the call](figures/d1-deadline-throws.svg) + +It comes down to a flow that never checks: a returned outcome lets it carry on with no answer. + +**What would change my mind:** evidence that most asking flows go ahead without the answer. Then +returning it is the common path, and the throw is ceremony. + + +## D2 · A screen answers a person's stop through a route that takes only the stop's id and the answer + +*An engineering call, decided; recorded because it fixes a public route.* + +| | | +|---|---| +| **Instead of** | Opening the resume route to runs a task started, with an exception for a person's stop | +| **Because** | The resume route takes a request id, an action and gate data from the caller, and re-entering a task's handler with them is what its source allow-list refuses (BP-031, FIX-999). The answer route reads the request, flow, session and user from the stored stop, checks the stop is a person's and the caller is its user, and validates the answer against the stop's own schema. Only the answer comes from the caller | +| **Locks in** | A public route and a client call, which the implementer names, beside resume. Every screen answers a person's stop through it, and no child builds another (ER-7). The resume route keeps serving a user's own runs, unchanged | + +![D2: an answer route that takes the stop's id and answer, chosen, beside the resume route opened behind a check. Decides it: what the caller sends. Price: two routes to keep](figures/d2-answer-route.svg) + +It comes down to what the caller sends: through resume, caller data re-enters a task's handler. + +## Decided, not asked + +- **"Resumes once" has one convergence point:** the stop's single pending state, the fence every + resume already shares (FIX-1816 BR-16b). Every writer resolves through it: the answer route, the + sweeper at the deadline, the cancel's payment, the user's stop, and FIX-2131's steer. The loser + is told `already-resolved`. Nothing resolves a person's stop another way. +- **One predicate says whether a suspension is a person's**, in `contracts` beside the reasons + (ER-1). The claim gate and the answer route read it here; FIX-2131 moves the Inbox and the send. + `ctx.suspend` with `human_approval` or `human_input` passes it too, so a raw person's stop gets the + mark, the cancel and the stop; resumed `cancelled`, it throws as a reject does. +- **The kind is a field on the suspension**, with the reasons unchanged, so every renderer that + knows the two reasons keeps working. A record without it reads its kind from its reason (BP-030). +- **The row copies the stop** (its id, kind, prompt and deadline) in the write that sets the mark + and drops the lease (ER-2), from the request's ending. `listTasks` reads no suspension store per + row (BP-033), and a stop's prompt never changes. Admission and every ending clear it. +- **`waitingFor`** is the public name on `getTask` and `listTasks`, beside `waitingOn`, which they + now show. The park's `question` string stays until FIX-2131 removes it. +- **The cancel is a debt with a due time** (rule 8), written in the cancel's own write: the + cancelling side pays it at once through the request host, and a board touch or the sweeper + resends it. It never goes over HTTP. +- **A cancelled block's writes to the task are refused** by the claim fence already there, and + nothing it returns is recorded. A task it files after the cancel never starts; whether it is + refused or filed cancelled is the implementer's. +- **A user's stop of a person's stop cancels the task.** The request's ending tells the gate the + stop was a person's, and the gate cancels where it would have failed the try. A stop of a running + request, or of a wait, is unchanged. +- **The deadline** rides the stop's existing expiry, which FIX-2063's sweeper fires. The host + setting has its own bounds beside `waitDeadlines`; its name is the implementer's. A question's and + a review's expiry now resume the block, as an approval's already does (FIX-1846). +- **The model's `waitForUser` tool is FIX-2131's**, which swaps it for `parkOnQuestion` in one + change, so a model never has two ways to ask. +- **Messages:** a send or call to a session waiting on a person queues (rule 10, epic D2). A test + pins it so FIX-2070's change is seen. + +## Considered and dropped + +| Alternative | Why not | +|---|---| +| Always return the deadline outcome (simpler: one result shape) | D1: a forgotten check carries on with no answer | +| Read the stop's text from the suspension store at `getTask` time | A store read per row in `listTasks`, and a second read path for the same fact | +| Cancel the run's stop synchronously in `updateTask`, with no debt | A crash between the row's cancel and the resume leaves the run parked for good, which is today's bug | +| Keep failing the try on a user's stop | Rule 12, and it asks the person the same question again | +| Hold the session's key while waiting | The epic's D2 rejected it: `onTaskSettled` must still run | + +## Settled + +- **No POC.** The kept claim and the same-try resume are shipped and tested (FIX-2077, + `settles-when-its-work-is-over.test.ts`), and the fence is FIX-1816's. The new parts are wiring + on those. No counted fact carries the approach, so there is no checker either. + +## How it got here + +- **Draft** — framed as the base every later stop builds on: `waitForUser` on `ctx.suspend`, the + mark keyed on one predicate with the stop recorded on the row, four endings through one fence, + and one trusted answer route; FIX-2130 folded in as the epic decided. + +**Open: none.** diff --git a/specs/issues/FIX-2129/SPEC.md b/specs/issues/FIX-2129/SPEC.md new file mode 100644 index 0000000000..1cbcfe3c9f --- /dev/null +++ b/specs/issues/FIX-2129/SPEC.md @@ -0,0 +1,145 @@ +# FIX-2129 · A stop for a person holds its task + +**Spec** · [Decisions](DECISIONS.md) + +## Six people, before and after + +| Someone who… | Today | After | +|---|---|---| +| **answers a worker's question in the Inbox** | Sees "can't be answered from Shift Manager" for any stop in a run a task started | Answers it there; the same try carries on, still holding its claim | +| **reads a task, as its filer or on a screen** | Sees *in progress*, with no sign it waits on a person or on what | Sees it waiting on a person, with the stop's kind, prompt and deadline, in `getTask` and `listTasks` | +| **writes a block that asks a person** | Calls `ctx.suspend` with a reason. An approval past its expiry reads as a rejection; a question past it stays parked for good | Calls `ctx.waitForUser({ kind, prompt, deadline? })`, 7 days by default. At the deadline an approval is a no, and a question or review fails the try unless the block catches it | +| **cancels a task waiting on a person** | The row cancels, but its run stays parked and its Inbox item stays open | The block resumes `cancelled` and runs to its end. Nothing it writes or returns lands; the item closes | +| **stops a run waiting on them** | The try fails and the task runs again, asking again | The run ends, its item closes, and the task is cancelled | +| **answers and cancels at the same moment** | n/a | One wins; the other is told the stop is already resolved | + +Every other stop for a person rests on this one: FIX-2131, FIX-2132 and FIX-2133 test against +`waitForUser`, its mark on the row and its answer route. + +## The goal, and how we'll know it's met + +**A task whose run stops to ask a person shows what it waits for, is answered from the Inbox on the +same try, and ends exactly once, whether it is answered, runs out of time, is cancelled or is +stopped.** + +| Is it the right goal? | | +|---|---| +| **The real need** | Rule 12 of [the concept](../../../docs/internal/design/workforce-coordination-concept.md#the-rules): "A stop for a person resumes once: answered, deadline or cancelled … Its task keeps its claim." The epic's legs b and c ([FIX-2058](../../epics/FIX-2058/SPEC.md#the-goal-and-how-well-know-its-met)) and its rules ER-1, ER-2, ER-3 and ER-7 | +| **Smaller, and rejected** | "The row records the question, so `getTask` shows it" (the issue before FIX-2130 folded in). Met while the Inbox still can't answer a task's stop, a cancel leaves the run parked, and a stop runs the work again | +| **Bigger, and not this issue's** | Every kind of stop in the Inbox: questions and reviews listed (FIX-2131), a coding run's question (FIX-2132), a held task (FIX-2133), proved together by FIX-2134 | +| **Not done if** | The check ran only in memory · the answer goes through the resume route opened to task runs · a cancel closes the item but the run never resumes, or its write lands · only an approval acts on its deadline | + +```mermaid +flowchart LR + H["durable SQLite host · a task-board worker"] --> S["its run asks with waitForUser"] + S --> W["wait past three lease periods"] + W --> E["leg a · answer · b · deadline · c · cancel · d · stop"] + E -->|"one ending each · same try · item closed · work ran once"| P["PASS · goal met"] + C["control · a stop fails the try, as today"] -.-> E + E -.->|"under the control"| F["must FAIL · leg d, task cancelled on try 1"] +``` + +The check reads the task through its public actions and answers through the route a screen uses, +never through the store. + +| How we verify | | +|---|---| +| **Goal check** | `goals/task-board/holds-a-task-waiting-on-a-person/` · model-free (`n/a`) · run by the implementer at completion · verdict in the implementation PR | +| **Signal** | a: past three lease periods, `getTask` shows `waitingOn: "person"` and the prompt, a second worker claims nothing, and the answer completes try 1 with the work counter at 1. b: an unhandled question fails try 1, a caught one completes it, an approval reads as a no. c: the block runs on once, its progress write is refused, a task it files never starts, the row stays `cancelled` with no output. d: `cancelled` on try 1. Every leg: the item leaves the pending list. An answer and a cancel together resume once | +| **Input** | A question, "Which region?", and an approval. Another prompt or kind must pass too | +| **Anti-game** | Don't assert on the store's writes or the suspension record; read through `getTask` and the Inbox's pending read. The work counter is a real row, not item counts | +| **Control that must fail** | `GOAL_CONTROL=stop-fails-attempt` fails leg d on *cancelled on try 1*; `GOAL_CONTROL=public-resume` fails leg a on *answered through the route*. Today's `main` fails legs a to c: it has no `waitForUser` | + +## What changes + +![A grid of five moments of a task whose run asks a person, today and after: reading the task, answering in the Inbox, no answer by the deadline, the task cancelled, the user stopping it](figures/what-changes.svg) + +Read down each column: every red cell today is a stop a person can't see, can't answer, or that +runs the work twice. + +**A block that asks:** + +```diff +- const region = (await ctx.suspend!({ reason: "human_input", message: "Which region?" })) as string; ++ const asked = await ctx.waitForUser({ kind: "question", prompt: "Which region?", deadline: 2 * DAY }); ++ if (asked.cancelled) return { skipped: true }; // the task was cancelled: nothing here is recorded ++ const region = asked.answer; ++ // At the deadline this throws; catch isPersonDeadline(error) to go ahead, end, or ask again (D1). +``` + +**What a reader of the task sees:** + +```diff + { id: "t1", status: "in_progress", attempts: 1, ++ waitingOn: "person", ++ waitingFor: { kind: "question", prompt: "Which region?", deadline: 1761868800000 } } +``` + +**Docs:** update the `core`, `engine`, `client` and `orchestration` READMEs; +`apps/docs/docs/configuration/runtime.md` (the deadline setting), `apps/docs/docs/api/client.md` +(the answer call) and `apps/docs/docs/orchestration/task-board.md` (a task waiting on a person: its +reads, cancel and stop). No new page; the one-way-to-stop story is FIX-2131's (the epic's docs line). + +## How a stop reaches the row, and how it ends + +```mermaid +flowchart LR + B["block · waitForUser"] --> G["engine · the stop, with kind and deadline"] + G -->|"request ends suspended"| T["claim gate · mark and record, lease dropped, one write"] + T --> R["task row"] + A["answer route"] --> X["the stop's one pending state"] + K["cancel · its debt"] --> X + D["sweeper · deadline"] --> X + U["user stop"] --> X + X -->|"first resolution wins"| B +``` + +All four endings resolve the same pending state, the fence FIX-1816 built, so the first one wins. +The resumed run is admitted on its claim as today. + +## What stays as it is + +- **The person mark and the kept claim** (FIX-2077 D1). This keys them on one predicate and records which stop holds the task. +- **`ctx.suspend`** for every other suspension, and for a person's stop it can't express (a form, a selection, a skip). +- **The resume route** and its source allow-list (FIX-999). +- **Waits on work** (`getTask` with `wait`, FIX-2082): their deadline, wake and stop are untouched. +- **What the Inbox lists:** approvals and input, until FIX-2131. A message to a session waiting on a person still queues (rule 10); a test pins it. + +## What's already here, and the debt + +| Already here | What this does with it | +|---|---| +| Ways to ask a person and wait, across `packages/`: `ctx.suspend` with `human_approval` or `human_input` (the closest), the question park (`parkOnQuestion`, `answerTask`), the review park (`awaitReview`, `unparkAndDrain`), harness-manager's question inbox. Searched `suspend(`, `park`, `awaitReview`, `answer`, `ask` | **Builds on** the closest: `waitForUser` is `ctx.suspend` with a kind, a deadline and a cancel. FIX-2131 and FIX-2132 retire the other three onto it | +| [FIX-2077 D1](../FIX-2077/DECISIONS.md#d1) and [its person-stop line](../FIX-2077/DECISIONS.md#person-stop): a person's stop records `waitingOn: "person"`, drops the lease, and its resume is admitted on the same try | **Kept.** The mark comes from the shared predicate, and the same write records which stop holds the task | +| FIX-2077's rule that a stopped request fails its try (`task-request.ts` header) | **Amended** for a stop of a person's stop: the task is cancelled instead (rule 12) | +| [FIX-1816](../FIX-1816/BUSINESS-RULES.md) BR-16a and BR-16b: a stop of a person's gate ends the turn; whichever resolves the gate first wins | **Kept and extended:** the fence also takes the cancel and the deadline, and the stop also cancels the task | +| FIX-1846: an expired approval continues as a rejection marked expired | **Builds on:** an approval's deadline reads as a no. A question's and a review's now resume too | +| Three copies of "is it a person's stop": the gate's `stopOf`, `PERSON_REASONS` and the Lab send's `stopOf` | **Replaces** the gate's with one predicate in `contracts` ([ER-1](../../epics/FIX-2058/DECISIONS.md#who-owns-what)); FIX-2131 moves the other two | +| The Inbox's `REOPENED_SOURCES` check: a person's stop in a task's run is unanswerable | **Removes** it for a person's stop: every listed item answers through the answer route ([ER-7](../../epics/FIX-2058/DECISIONS.md#who-owns-what)) | + +| The debt | | +|---|---| +| **Removes** | The gate's own person check; the Inbox's unanswerable task stops; a stop that runs a person's work twice; a cancelled task's run left parked | +| **Adds** | `ctx.waitForUser`, the answer route and client call, a person-deadline host setting ([D3](../../epics/FIX-2058/DECISIONS.md#d3)), a `cancelled` suspension status, the row's record of its stop, the cancel's debt. All permanent by design. `ctx.suspend` with a person's reason stays the lower-level form of the same stop, as it is under the wait gate | +| **Leaves** | `PERSON_REASONS` and the send's `stopOf` until FIX-2131; the parks until FIX-2131 and FIX-2132; the error reporter's own `ctx.suspend` question, which works as before | + +**Net: flat here, down across the epic.** One call is added and one check replaced; the three +paths it lets FIX-2131 and FIX-2132 remove are what bring the net down. + +## Sign off + +**[The goal](#the-goal-and-how-well-know-its-met), at that size:** shown, answered on the same +try, ended once by any of four. If wrong: three children build on a stop that can still run work +twice or leave an item open. + +**[The debt](#whats-already-here-and-the-debt), flat:** one call and one route added, one check +replaced. If wrong: `ctx.suspend` and `waitForUser` drift into two ways to ask. + +1. **[D1](DECISIONS.md#d1) · At its deadline, a question or review throws an error the block may + catch; an approval reads as a no.** If wrong: every asking flow wraps a catch it didn't need. +2. **[D2](DECISIONS.md#d2) · A screen answers a person's stop through a route that takes only the + stop's id and the answer.** Engineering, decided. If wrong: two answer paths to keep in step. + +**Open: none.** D1 is the one to weigh: it is the contract every later child and app writes against. + +Feature · `contracts`, `core`, `engine`, `client`, `orchestration`, `shift-manager` · large · epic FIX-2058 · blocked by FIX-2063 and FIX-2056 diff --git a/specs/issues/FIX-2129/figures/d1-deadline-throws.svg b/specs/issues/FIX-2129/figures/d1-deadline-throws.svg new file mode 100644 index 0000000000..9d7f145aab --- /dev/null +++ b/specs/issues/FIX-2129/figures/d1-deadline-throws.svg @@ -0,0 +1,101 @@ + + + + + + + D1 · THE CALL + What does a flow get when nobody answers by the deadline? + + + + + CHOSEN + A question throws; an approval is a no + + INSTEAD OF + Always a returned "no answer" + + + + + + A FLOW THAT + NEVER CHECKS + ▸ DECIDES IT + + + Fails the try, as rule 12 says + the item closes; a retry asks again + − + Carries on with no answer + an empty answer reaches the work, quietly + + + + A FLOW THAT + HANDLES IT + − + A catch around the call + two shapes: a result and an error + + + One branch on the result + the shape a wait on a task has + + + + + AN APPROVAL + = + Reads as a no + answer false, with a deadline flag + = + Reads as a no + the same + + + + + + LOCKS IN + A deadline error every asking flow catches + the contract FIX-2131 to FIX-2133 and apps test against + + + + + FLIPS IF + Most flows carry on without the answer + then returning it is the common path, and wins + + diff --git a/specs/issues/FIX-2129/figures/d2-answer-route.svg b/specs/issues/FIX-2129/figures/d2-answer-route.svg new file mode 100644 index 0000000000..6413f0bc94 --- /dev/null +++ b/specs/issues/FIX-2129/figures/d2-answer-route.svg @@ -0,0 +1,100 @@ + + + + + + + D2 · THE CALL + How does a screen answer a person's stop in a run a task started? + + + + + CHOSEN + An answer route: the stop's id and answer + + INSTEAD OF + The resume route, opened behind a check + + + + + + WHAT THE + CALLER SENDS + ▸ DECIDES IT + + + Only the answer reaches the run + request, flow, user read from the stored stop + − + Gate data re-enters a task + caller data in a task's handler (BP-031) + + + + ROUTES TO KEEP + − + Two: resume and answer + resume stays for a user's own runs + + + One route + with an exception for task runs inside it + + + + + WHO MAY ANSWER + = + The stop's own user + rule 11 + = + The stop's own user + the same + + + + + + LOCKS IN + A public answer route and client call + every screen answers a person's stop this way + + + + + FLIPS IF + The resume route takes only an answer + then it is the trusted route already + + diff --git a/specs/issues/FIX-2129/figures/what-changes.svg b/specs/issues/FIX-2129/figures/what-changes.svg new file mode 100644 index 0000000000..e5ee48697c --- /dev/null +++ b/specs/issues/FIX-2129/figures/what-changes.svg @@ -0,0 +1,90 @@ + + + + + + READING THE TASK + ANSWERED IN THE INBOX + NO ANSWER BY DEADLINE + THE TASK IS CANCELLED + THE USER STOPS IT + + + + + TODAY + + Shows running + nothing says it waits + on a person, or for + what question + + Can't be answered + the Inbox never + reopens a run that + a task started + + Only an approval acts + it reads as a rejection; + a question stays + parked for good + + Item stays open + the row cancels, but + the run stays parked + on the question + + The try fails + and the task runs + again in a new try, + asking again + + + + + AFTER + + Waiting on a person + getTask and listTasks + show the kind, the + prompt and the deadline + + Answered there + through one trusted + route; the same try + carries on, claim kept + + The flow decides + 7 days by default; + unhandled, approval is no, + a question fails the try + + Resumes cancelled + the block runs to its + end, nothing it does + lands; the item closes + + The task is cancelled + the request ends and + its item closes; no + second try + + From da893b55d34c31679890288109c8703c6ce6e9dd Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 16:30:12 +0000 Subject: [PATCH 02/10] =?UTF-8?q?spec(FIX-2129):=20review=20round=201=20?= =?UTF-8?q?=E2=80=94=20the=20deadline=20error=20is=20SuspensionTimeoutErro?= =?UTF-8?q?r,=20a=20stop=20holds=20back=20no=20notice?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit D1 names the error core already exports and nothing throws, and says plainly that an approval keeps FIX-1846's no. The deadline is one clock (expiresAt); the 7-day default is waitForUser's only. A person's stop never holds back a notice (ER-2). A cancelled block's effects outside the task land; the 'filed after cancel never starts' guarantee is cut. Docs line gains the concept amendment and a changeset. Review notes recorded. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Vdxnv28JumHyq2za2ybqz6 --- specs/issues/FIX-2129/DECISIONS.md | 44 +++++++++++++++---- specs/issues/FIX-2129/SPEC.md | 23 ++++++---- .../issues/FIX-2129/figures/what-changes.svg | 6 +-- 3 files changed, 52 insertions(+), 21 deletions(-) diff --git a/specs/issues/FIX-2129/DECISIONS.md b/specs/issues/FIX-2129/DECISIONS.md index 31ef2d7669..3b325b4f09 100644 --- a/specs/issues/FIX-2129/DECISIONS.md +++ b/specs/issues/FIX-2129/DECISIONS.md @@ -9,7 +9,7 @@ ER-7 and D3. Two calls are left, both about the surface the later children write ```mermaid flowchart TD - I["FIX-2129"] --> D1["D1 · at the deadline a question or review throws, an approval is a no"] + I["FIX-2129"] --> D1["D1 · at the deadline a question or review throws SuspensionTimeoutError, an approval is a no"] D1 -.->|"rejected · a flow that never checks carries on with no answer"| X1["always return a no-answer outcome"] I --> D2["D2 · an answer route that takes only the stop's id and the answer"] D2 -.->|"rejected · caller gate data re-enters a task's handler"| X2["open the resume route to task runs behind a check"] @@ -18,13 +18,13 @@ flowchart TD Solid edges are what you're signing. Dashed edges lost, and the label says why. -## D1 · At its deadline, a question or review throws an error the block may catch; an approval reads as a no +## D1 · At its deadline, a question or review throws `SuspensionTimeoutError`, which the block may catch; an approval reads as a no | | | |---|---| | **Instead of** | Always returning a "no answer by the deadline" outcome, as a wait on a task does, for the block to branch on | -| **Because** | The concept says an unhandled deadline fails a question's or review's try, using an attempt. With a returned outcome nothing can tell a block that handled it from one that forgot, so the forgetful one carries on with an empty answer and nobody sees it. A thrown error is unhandled exactly when nobody catches it. An approval needs neither: a no is a safe default, so it returns `answer: false` with a deadline flag | -| **Locks in** | `ctx.waitForUser` returns the answer or `cancelled`, and throws a deadline error a block tells apart with one exported check. FIX-2131 to FIX-2133 and every app that asks a person write against this; changing it later changes every asking block. The wait gate keeps its returned deadline: it carries on by default, which a person's question must not | +| **Because** | The concept says an unhandled deadline fails a question's or review's try, using an attempt. With a returned outcome nothing can tell a block that handled it from one that forgot, so the forgetful one carries on with an empty answer and nobody sees it. A thrown error is unhandled exactly when nobody catches it. An approval keeps what FIX-1846 shipped, a no marked as the deadline's: that is a choice, not the same rule. A no leaves undone the one thing that waited for a yes, and a question's empty answer has no value that is safe to carry on with | +| **Locks in** | `ctx.waitForUser` returns the answer or `cancelled`, and at a question's or review's deadline throws `SuspensionTimeoutError`, which `core` already exports and nothing throws today: one timeout error for one suspension mechanism. The throw is a block's contract; FIX-2131's model tool returns a deadline result instead, since a model can't catch. ER-1's "share answered and deadline" means the same words, not the same shape: a wait returns `{ answered: false, deadline: true }`. FIX-2131 to FIX-2133 and every app that asks a person write against this; changing it later changes every asking block. The wait gate keeps its returned deadline: it carries on by default, which a person's question must not | ![D1: a question throws and an approval is a no, chosen, beside always returning a no-answer outcome. Decides it: a flow that never checks. Price: a catch around the call](figures/d1-deadline-throws.svg) @@ -69,14 +69,24 @@ It comes down to what the caller sends: through resume, caller data re-enters a cancelling side pays it at once through the request host, and a board touch or the sweeper resends it. It never goes over HTTP. - **A cancelled block's writes to the task are refused** by the claim fence already there, and - nothing it returns is recorded. A task it files after the cancel never starts; whether it is - refused or filed cancelled is the implementer's. + nothing it returns is recorded. What it does outside the task (a call, another scope's resource) + lands, as any block's does. A stop it asks after the cancel resolves `cancelled` at once and opens + no item. - **A user's stop of a person's stop cancels the task.** The request's ending tells the gate the stop was a person's, and the gate cancels where it would have failed the try. A stop of a running request, or of a wait, is unchanged. -- **The deadline** rides the stop's existing expiry, which FIX-2063's sweeper fires. The host - setting has its own bounds beside `waitDeadlines`; its name is the implementer's. A question's and - a review's expiry now resume the block, as an approval's already does (FIX-1846). +- **The deadline** is the call's `deadline`, else the host's person-stop default, written to the + stop's existing `expiresAt` (the field `timeoutMs` sets), which FIX-2063's sweeper fires: one + clock. The host setting has its own bounds beside `waitDeadlines`; its name is the implementer's. + The default applies to `waitForUser` only: a raw `ctx.suspend` keeps its own `timeoutMs`, none + meaning no deadline, so an approval that waits today doesn't start expiring. A question's and a + review's expiry now resume the block, as an approval's already does (FIX-1846). A question that + fails its try at the deadline is asked again on the next try, so it can stay open a deadline per + try. +- **A person's stop never holds back a notice.** A task the stopped request filed ends during the + stop, and its `onTaskSettled` runs then (ER-2). A filing request parked on a person's stop counts + as ended for holding notices back; a wait after the resume that finds the notice taken says it is + arriving as a notice, the mechanism #3733 adds. - **The model's `waitForUser` tool is FIX-2131's**, which swaps it for `parkOnQuestion` in one change, so a model never has two ways to ask. - **Messages:** a send or call to a session waiting on a person queues (rule 10, epic D2). A test @@ -87,6 +97,8 @@ It comes down to what the caller sends: through resume, caller data re-enters a | Alternative | Why not | |---|---| | Always return the deadline outcome (simpler: one result shape) | D1: a forgotten check carries on with no answer | +| Return a typed result with a `deadline` variant the block must narrow | No runtime signal: a block can still read past it (`asked.answer ?? ""`), and plain JavaScript has no narrowing. An unhandled deadline must fail the try, which only a throw does | +| A new deadline error with its own check | `SuspensionTimeoutError` already exists for this and nothing throws it: two timeout errors for one mechanism | | Read the stop's text from the suspension store at `getTask` time | A store read per row in `listTasks`, and a second read path for the same fact | | Cancel the run's stop synchronously in `updateTask`, with no debt | A crash between the row's cancel and the resume leaves the run parked for good, which is today's bug | | Keep failing the try on a user's stop | Rule 12, and it asks the person the same question again | @@ -98,6 +110,20 @@ It comes down to what the caller sends: through resume, caller data re-enters a `settles-when-its-work-is-over.test.ts`), and the fence is FIX-1816's. The new parts are wiring on those. No counted fact carries the approach, so there is no checker either. +## Notes from review + +Recorded for the implementer, not folded into the design. + +- **Cursor (PR #3735, review):** "Cancel debt + sweeper resend … reusing existing `cancelOwed` / `payOwedResumes` shape (if semantically identical) would avoid a second debt sweep path at implementation time." And: "If cancel debt uses filtered `list({ … })` like `payOwedResumes`, say so in implementer notes to avoid full-board scan amplification." +- **Cursor:** "All four writers through `resumeUnderLease` / `expireUnderLease` only — no second resolve path in shift-manager." "Predicate only in `contracts`; gate switches off inline `stopOf` list." "Cancel debt paid via a **host seam** like `resumeWait`, not orchestration importing engine routes (package boundary)." +- **Cursor:** "Residuals are sweeper O(pending) and more post-expiry continuations once questions gain deadlines … Optional: cap/limit on `waitingFor.prompt` size in list payloads (BP-042-adjacent)." +- **Cursor:** "Six-people table + `what-changes.svg` largely duplicate"; "'Decided, not asked' re-states several FIX-2058 ER bullets"; "Two mermaid 'four endings → fence' diagrams (SPEC + DECISIONS) could be one with a link." +- **Second look:** "Moving `PERSON_REASONS` is a three-line import swap, and leaving it creates a window where `contracts` and `shift-manager` can disagree on a custom reason. Suggest moving all three in this PR, or adding a test that fails if they diverge. Also note `SuspensionReason` has an open `string & {}` arm, so the predicate must say what a custom reason is." (The epic gives the move to FIX-2131; a divergence test is the implementer's call.) +- **Second look:** "The `REOPENED_SOURCES` removal (`reads.ts:240`, used at `:837`) is only for a person's stop. Please confirm the implementer deletes the set and not only that branch, so it isn't left as dead config." +- **Second look:** "What happens if the suspension is superseded (replayed block, re-driven turn) while the row still points at the old id? … A crash-recovery path is worth one line." +- **Second look:** "The goal check relies on a 'wait past three lease periods'. Please give the check a way to fake time. Without it the check is slow and flaky." +- **Second look:** on approval: "make the deadline flag part of the type so the narrowed `answer` can't be read without it." + ## How it got here - **Draft** — framed as the base every later stop builds on: `waitForUser` on `ctx.suspend`, the diff --git a/specs/issues/FIX-2129/SPEC.md b/specs/issues/FIX-2129/SPEC.md index 1cbcfe3c9f..10d0fe6bf3 100644 --- a/specs/issues/FIX-2129/SPEC.md +++ b/specs/issues/FIX-2129/SPEC.md @@ -9,7 +9,7 @@ | **answers a worker's question in the Inbox** | Sees "can't be answered from Shift Manager" for any stop in a run a task started | Answers it there; the same try carries on, still holding its claim | | **reads a task, as its filer or on a screen** | Sees *in progress*, with no sign it waits on a person or on what | Sees it waiting on a person, with the stop's kind, prompt and deadline, in `getTask` and `listTasks` | | **writes a block that asks a person** | Calls `ctx.suspend` with a reason. An approval past its expiry reads as a rejection; a question past it stays parked for good | Calls `ctx.waitForUser({ kind, prompt, deadline? })`, 7 days by default. At the deadline an approval is a no, and a question or review fails the try unless the block catches it | -| **cancels a task waiting on a person** | The row cancels, but its run stays parked and its Inbox item stays open | The block resumes `cancelled` and runs to its end. Nothing it writes or returns lands; the item closes | +| **cancels a task waiting on a person** | The row cancels, but its run stays parked and its Inbox item stays open | The block resumes `cancelled` and runs to its end. Nothing it writes to the task or returns is kept; what it does elsewhere lands, as any block's does. The item closes | | **stops a run waiting on them** | The try fails and the task runs again, asking again | The run ends, its item closes, and the task is cancelled | | **answers and cancels at the same moment** | n/a | One wins; the other is told the stop is already resolved | @@ -45,8 +45,8 @@ never through the store. | How we verify | | |---|---| | **Goal check** | `goals/task-board/holds-a-task-waiting-on-a-person/` · model-free (`n/a`) · run by the implementer at completion · verdict in the implementation PR | -| **Signal** | a: past three lease periods, `getTask` shows `waitingOn: "person"` and the prompt, a second worker claims nothing, and the answer completes try 1 with the work counter at 1. b: an unhandled question fails try 1, a caught one completes it, an approval reads as a no. c: the block runs on once, its progress write is refused, a task it files never starts, the row stays `cancelled` with no output. d: `cancelled` on try 1. Every leg: the item leaves the pending list. An answer and a cancel together resume once | -| **Input** | A question, "Which region?", and an approval. Another prompt or kind must pass too | +| **Signal** | a: past three lease periods, `getTask` shows `waitingOn: "person"` and the prompt, a second worker claims nothing, and the answer completes try 1 with the work counter at 1; a task the request filed before it stopped ends during the stop, and its `onTaskSettled` runs then, not after the answer. b: an unhandled question fails try 1, a caught one completes it, an approval reads as a no. c: the block runs on once, its progress write is refused, the row stays `cancelled` with no output. d: `cancelled` on try 1. Every leg: the item leaves the pending list. An answer and a cancel together resume once | +| **Input** | A question, "Which region?", an approval, and a review | | **Anti-game** | Don't assert on the store's writes or the suspension record; read through `getTask` and the Inbox's pending read. The work counter is a real row, not item counts | | **Control that must fail** | `GOAL_CONTROL=stop-fails-attempt` fails leg d on *cancelled on try 1*; `GOAL_CONTROL=public-resume` fails leg a on *answered through the route*. Today's `main` fails legs a to c: it has no `waitForUser` | @@ -64,7 +64,7 @@ runs the work twice. + const asked = await ctx.waitForUser({ kind: "question", prompt: "Which region?", deadline: 2 * DAY }); + if (asked.cancelled) return { skipped: true }; // the task was cancelled: nothing here is recorded + const region = asked.answer; -+ // At the deadline this throws; catch isPersonDeadline(error) to go ahead, end, or ask again (D1). ++ // At the deadline a question throws SuspensionTimeoutError; catch it to go ahead, end, or ask again (D1). ``` **What a reader of the task sees:** @@ -78,7 +78,11 @@ runs the work twice. **Docs:** update the `core`, `engine`, `client` and `orchestration` READMEs; `apps/docs/docs/configuration/runtime.md` (the deadline setting), `apps/docs/docs/api/client.md` (the answer call) and `apps/docs/docs/orchestration/task-board.md` (a task waiting on a person: its -reads, cancel and stop). No new page; the one-way-to-stop story is FIX-2131's (the epic's docs line). +reads, cancel and stop). Amend the concept's "defaulting to the host's" (`workforce-coordination-concept.md`, +*Inbox items*) to name the person-stop default ([epic D3](../../epics/FIX-2058/DECISIONS.md#d3)). A +changeset with a migration note: a raw `ctx.suspend` person's stop now gets the mark, the cancel and +the stop, a question's expiry now resumes its block, and `contracts` gains a `cancelled` status. No +new page; the one-way-to-stop story is FIX-2131's (the epic's docs line). ## How a stop reaches the row, and how it ends @@ -114,13 +118,14 @@ The resumed run is admitted on its claim as today. | FIX-2077's rule that a stopped request fails its try (`task-request.ts` header) | **Amended** for a stop of a person's stop: the task is cancelled instead (rule 12) | | [FIX-1816](../FIX-1816/BUSINESS-RULES.md) BR-16a and BR-16b: a stop of a person's gate ends the turn; whichever resolves the gate first wins | **Kept and extended:** the fence also takes the cancel and the deadline, and the stop also cancels the task | | FIX-1846: an expired approval continues as a rejection marked expired | **Builds on:** an approval's deadline reads as a no. A question's and a review's now resume too | +| `SuspensionTimeoutError` in `core`: exported, documented as thrown on a timed-out resume, recognized by the generator and the tool executor, and thrown by nothing. `SuspendOptions.timeoutMs`, which sets the stop's `expiresAt` | **Reused:** it is the deadline error ([D1](DECISIONS.md#d1)). `waitForUser`'s `deadline` is written to the same `expiresAt`, so a stop has one clock | | Three copies of "is it a person's stop": the gate's `stopOf`, `PERSON_REASONS` and the Lab send's `stopOf` | **Replaces** the gate's with one predicate in `contracts` ([ER-1](../../epics/FIX-2058/DECISIONS.md#who-owns-what)); FIX-2131 moves the other two | | The Inbox's `REOPENED_SOURCES` check: a person's stop in a task's run is unanswerable | **Removes** it for a person's stop: every listed item answers through the answer route ([ER-7](../../epics/FIX-2058/DECISIONS.md#who-owns-what)) | | The debt | | |---|---| -| **Removes** | The gate's own person check; the Inbox's unanswerable task stops; a stop that runs a person's work twice; a cancelled task's run left parked | -| **Adds** | `ctx.waitForUser`, the answer route and client call, a person-deadline host setting ([D3](../../epics/FIX-2058/DECISIONS.md#d3)), a `cancelled` suspension status, the row's record of its stop, the cancel's debt. All permanent by design. `ctx.suspend` with a person's reason stays the lower-level form of the same stop, as it is under the wait gate | +| **Removes** | The gate's own person check; a declared error nothing throws; the Inbox's unanswerable task stops; a stop that runs a person's work twice; a cancelled task's run left parked | +| **Adds** | `ctx.waitForUser`, the answer route and client call, a person-deadline host setting ([D3](../../epics/FIX-2058/DECISIONS.md#d3)), a `cancelled` suspension status, the row's record of its stop, the cancel's debt. All permanent by design. `ctx.suspend` with a person's reason stays the lower-level form of the same stop, as it is under the wait gate; new code asks with `waitForUser` | | **Leaves** | `PERSON_REASONS` and the send's `stopOf` until FIX-2131; the parks until FIX-2131 and FIX-2132; the error reporter's own `ctx.suspend` question, which works as before | **Net: flat here, down across the epic.** One call is added and one check replaced; the three @@ -135,8 +140,8 @@ twice or leave an item open. **[The debt](#whats-already-here-and-the-debt), flat:** one call and one route added, one check replaced. If wrong: `ctx.suspend` and `waitForUser` drift into two ways to ask. -1. **[D1](DECISIONS.md#d1) · At its deadline, a question or review throws an error the block may - catch; an approval reads as a no.** If wrong: every asking flow wraps a catch it didn't need. +1. **[D1](DECISIONS.md#d1) · At its deadline, a question or review throws `SuspensionTimeoutError`, + which the block may catch; an approval reads as a no.** If wrong: every asking flow wraps a catch it didn't need. 2. **[D2](DECISIONS.md#d2) · A screen answers a person's stop through a route that takes only the stop's id and the answer.** Engineering, decided. If wrong: two answer paths to keep in step. diff --git a/specs/issues/FIX-2129/figures/what-changes.svg b/specs/issues/FIX-2129/figures/what-changes.svg index e5ee48697c..7c5c3bfbea 100644 --- a/specs/issues/FIX-2129/figures/what-changes.svg +++ b/specs/issues/FIX-2129/figures/what-changes.svg @@ -1,4 +1,4 @@ -