Repository navigation
spec(FIX-2159): a person's running turn hears the tasks that finished while it ran #3799
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 2 commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
42a1ce7
spec(FIX-2159): a person's running turn hears the tasks that finished…
claude f5efeb9
spec(FIX-2159): at-most-once stated in the goal; hook placed after th…
claude 4148914
spec(FIX-2159): POC case 5 automates read-without-take; review notes …
claude 74b5efa
spec(FIX-2159): POC follows ack-then-line, proves at most once; take …
claude 53b8593
spec(FIX-2159): take touches only the take record; shared handling, e…
claude a8c0d7f
spec(FIX-2159): the answer-again hook and the take are blocks
claude c073036
spec(FIX-2159): one answer-again step shared with planned; the app's …
claude da22b8c
spec(FIX-2159): at-most-once boundary is the dedupe write, not the ac…
claude dacb532
spec(FIX-2159): answerAgain: true uses a pre-built block; a block ove…
claude 39066bc
spec(FIX-2159): people table matches answerAgain: true
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,140 @@ | ||
| # FIX-2159 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** | ||
|
|
||
| The epic already decided *that* a result reaches the running turn ([FIX-2152 D2](../../epics/FIX-2152/DECISIONS.md#d2)), | ||
| and its merge approved the amendment to rule 7. These three decide *how*, and each has a | ||
| consequence a person can see. | ||
|
|
||
| ## The tree | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| I["FIX-2159"] --> D3["D3 · the app's flow answers again through a hook · the package only takes"] | ||
| D3 -.->|"rejected"| X3a["all in the lab · every result heard twice"] | ||
| D3 -.->|"rejected"| X3b["the package reads results before every model call · a loop the app can't see"] | ||
| I --> D1["D1 · the take is FIX-2123's take record, in the turn's name"] | ||
| D1 -.->|"rejected"| X1["a new taken-in-R list · a second mark to keep in step"] | ||
| I --> D2["D2 · only a turn a person's message started takes one"] | ||
| D2 -.->|"rejected"| X2["any running request · skips a task's own ending work"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing. Dashed edges lost, and the label says why. | ||
|
|
||
| <a name="d3"></a> | ||
| ## D3 · The app's flow decides to answer again, through one hook; the package only takes | ||
|
|
||
| *From the build Jake prefers, relayed on the epic's handle: the end-of-turn loop lives in the | ||
| lab's flow. Tested against the lab bar before it was drafted.* | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | (a) All of it in the lab, on public entries only. (b) The package reading results before every model call, through a context entry like the steer one, and answering once more itself | | ||
| | **Because** | (a) fails on public entries: nothing public takes a notice, and the agent flow has no step that may answer again (`afterAnswer` is a side step that can't change the answer). A lab that only *reads* finished rows leaves the notice owed, so the queued `onTaskSettled` says the line and wakes a second turn after the reply: heard twice ([POC](poc/take-in-turn/README.md), control). A lab that takes them itself must also report a failure, dedupe and free the delegate's session, which is package work in the lab (ER-4). (b) works, but the loop is package code no app can see or change, and the before-each-call read is a second mechanism step 4 doesn't need | | ||
| | **Locks in** | Two public entries: a hook on the agent worker flow, on the door a person's message comes through, that runs after the whole turn (its plan's answer included) in the same request and may hand the worker a message to answer again, at most three times per request; and a take on the workforce package that hands over what finished, once. An app that sets no hook behaves as today. A result that lands during a long tool loop waits for that answer to end, and one that lands after the last look waits for the turn to end, as today | | ||
|
|
||
|  | ||
|
|
||
| It comes down to hearing each result once: the lab alone can read a result but can't take it. | ||
|
|
||
| **What would change my mind:** the lab bar allowing a lab to call the package's notice handling | ||
| directly. Then the take could be lab code, and the package adds only the hook. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · The take is FIX-2123's take record, written in the turn's name, with the queued handling's order | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | A new "taken in request R" list on the conversation, kept like `steersTakenIn` on a task | | ||
| | **Because** | `onTaskSettled` already takes a notice in one conditional write that names its request, keeps that record after the clear, and takes a notice over once its taker ended without clearing it (FIX-2123). A turn that takes in its own name gets all three for nothing. The [POC](poc/take-in-turn/README.md) runs it on the real engine: taken in the turn and skipped by the queued copy; refused when the copy took it first; taken over after a turn that failed before clearing it | | ||
| | **Locks in** | A result taken in the turn has exactly the guarantees of one after the turn: never twice, and taken over if the turn dies before acknowledging it. The order is the queued handling's: take, report a failure, dedupe, free the session, acknowledge, then the line. A process death between the acknowledgement and the line drops the line, as it does today | | ||
|
|
||
|  | ||
|
|
||
| It comes down to one mark: a second one is a second rule the queued entry would have to learn. | ||
|
|
||
| **What would change my mind:** a store that can't keep the take record after the clear. Then | ||
| the turn needs its own list, and this card becomes the rejected one. | ||
|
|
||
| <a name="d2"></a> | ||
| ## D2 · Only a turn a person's own message started can take a result | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Any running request of the filer's session: a turn a notice woke, a message from another worker (`receive`), a task's turn | | ||
| | **Because** | In a task session the queued handling also does the task's own ending work (`admitOwnTask`), and the entry refuses a notice once it is cleared, so a take there would skip it (epic D2). A `receive` is talk between workers, and its turn order is FIX-1989's. `isUserTurn` already marks exactly a person's turn in a conversation, and skips task and delegate sessions | | ||
| | **Locks in** | The take hands over nothing outside a person's turn, whatever the app's hook asks. A coordinator's woken turn, a worker answering another worker, and a worker on a task hear results after the turn, as today. Widening it later is a new decision, not a flag | | ||
|
|
||
|  | ||
|
|
||
| It comes down to the task's own ending work: a take outside a person's turn can skip it. | ||
|
|
||
| **What would change my mind:** a lab script that needs a worker on a task to hear a result | ||
| mid-turn. Then a task session's take has to carry `admitOwnTask` with it, which is a larger change. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **Which notices the take hands over:** the ones the queued handling says as a line or a woken | ||
| turn, for a task whose result goes to the filer: a completion, a final failure, a cancel someone | ||
| else made, a park that asks. Not a routed result, a retried marker, a held marker or a waited-on row. | ||
| - **The visible item is the queued handling's own line**, under the delegate's name, said in the | ||
| turn's request by the take. FIX-2153 draws it; no new item kind. The take returns each line's | ||
| words so the app can put them in its message. | ||
| - **One ending path.** The take runs Workforce's existing handling for a notice, with "say the line | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| here and hand it back" in place of "say the line and wake a turn". Shared, never copied. | ||
| - **A failure the Error Reporter didn't take** stops the take before the acknowledgement. The take | ||
| stays with the turn, the result isn't handed back, and the queued copy hears it after the turn. | ||
| - **The take reads committed rows**: a turn's snapshot of the board never shows an ending written | ||
| after it started (POC, case 1). Only open rows this conversation filed are read. | ||
|
jhoffner marked this conversation as resolved.
Resolved
jhoffner marked this conversation as resolved.
Resolved
|
||
| - **The bound is the package's.** At most three answers again per request, so a hook that always | ||
| returns a message can't loop a turn forever. | ||
| - **Where the hook sits.** On the person's door (`agent-user-turn`), after `run`, so after the | ||
| plan's own answer (FIX-2076): once per request, never in a task or notice turn, and an app's | ||
| hook never runs where D2 says nothing changes. An answer again is one more turn of `run`, so | ||
| a result can make the worker plan again. | ||
| - **At most once, as today.** The take acknowledges before it says the line, the queued | ||
| handling's order. A death before the acknowledgement: the queued copy takes it over and says | ||
| it after the turn. A death after it: the line is dropped. No idempotency key on the line. | ||
|
|
||
| ## Considered and dropped | ||
|
|
||
| | Alternative | Why not | | ||
| |---|---| | ||
| | Condition 2 in the issue text: a request holding the filer task's claim may take | Superseded by epic D2 at `a070af58`: the queued handling's `admitOwnTask` would be skipped | | ||
| | Run the queued `onTaskSettled` block from inside the turn | A handler doesn't call blocks (BP-011), and the woken-turn half has no place in a running turn | | ||
| | Stop the model loop from ending while a notice is owed | Needs a core change; the epic keeps this out of core and engine | | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| | One flag on the flow that turns the behaviour on: the package owns the take and the answer again, the app only opts in | The smallest public surface, one option instead of a hook and a take. It loses on where the loop lives: the app can't see or change it, and Jake asked for the loop in the lab's flow as a showcase | | ||
|
|
||
| ## Settled | ||
|
|
||
| - **The existing take record is crash-safe enough to carry a take in the turn** — **CONFIRMED** by | ||
| [`poc/take-in-turn/`](poc/take-in-turn/README.md) on `main` at `3d131544`: three cases green, | ||
| and red with the turn's clear removed. | ||
| - **A lab can do the end-of-turn loop on public entries alone** — **REFUTED**. The public surface | ||
| has no take and no answer-again step (`AgentWorkerFlowOptions` on `main` offers `afterAnswer`, | ||
| a side step). Reading without taking is heard twice: the POC's control shows the queued copy | ||
| delivering a notice the turn didn't clear, and the agent flow's default notice policy | ||
| (`judgment`) wakes a second turn on it. | ||
|
|
||
| ## How it got here | ||
|
|
||
| - **Draft** — the epic's "one durable mark like `steersTakenIn`" turned out to exist as FIX-2123's | ||
| take record; the POC confirmed it, so D1 reuses it. | ||
| - **Before review** — Jake's preferred build (relayed on the epic's handle) put the end-of-turn | ||
| loop in the lab's flow. Tested against the lab bar: the loop fits, the take doesn't. D3 replaced | ||
| a package-run answer and a before-each-call context entry with a hook and a public take. | ||
| - **Review round 1** — the crash guarantee stated as at most once in the goal (it had read as | ||
| no loss); the hook placed on the person's door after the plan's answer; one-flag shape named | ||
| as dropped. | ||
|
|
||
| ## Notes from review | ||
|
|
||
| - "Have the implementer look at whether `planned`'s loop and the new hook can share one bounded | ||
| 'answer again' step (hook supplies the message, `planned` supplies its own). If they can't | ||
| share, say why." — second-look review ([review](https://github.com/fixpoint-labs/flow-state-dev/pull/3799#pullrequestreview-5634917017)) | ||
| - "The implementer's tests should own the interaction with `planned` explicitly, with the | ||
| Error Reporter stop-before-ack and the answer-again bound." — same review | ||
|
|
||
| These are inputs, not instructions. Adopt, adapt, or discard. | ||
|
|
||
| **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.
Uh oh!
There was an error while loading. Please reload this page.