From 3c51400d0230ed2746a5523b907c89164b21a09e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 19 Sep 2026 03:36:29 +0000 Subject: [PATCH 1/3] =?UTF-8?q?spec(FIX-1430):=20manager-queue=20lab=20?= =?UTF-8?q?=E2=80=94=20the=20proof=20that=20work=20reaches=20a=20seat?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four documents and two figures at spec/FIX-1430/. The fifth and last first-cut child of FIX-1407 (W4), and the owner of ER-20 — the epic's behavioural exit gate. A lab under goals/, not a surface: a coordinator seat files rows on a channel's board and assigns them to three declared worker seats, with queue columns derived at read time over rows that already exist. Three decisions: the lab ships no package code; the proof is a queue rather than a hand-off; what a busy seat does is shown, not chosen. One open question, on how much realism the exit gate closes on. Written against landed code at d8e4c99 and against the board surface FIX-1385 is specifying. Consumes FIX-1394's ER-2 only as a fence — neither its contract nor its implementation is a build input. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T --- spec/FIX-1430/BUSINESS-RULES.md | 65 +++++++++++++ spec/FIX-1430/DECISIONS.md | 86 ++++++++++++++++++ spec/FIX-1430/PLAN.md | 121 +++++++++++++++++++++++++ spec/FIX-1430/SPEC.md | 75 +++++++++++++++ spec/FIX-1430/figures/the-view.svg | 83 +++++++++++++++++ spec/FIX-1430/figures/what-changes.svg | 108 ++++++++++++++++++++++ 6 files changed, 538 insertions(+) create mode 100644 spec/FIX-1430/BUSINESS-RULES.md create mode 100644 spec/FIX-1430/DECISIONS.md create mode 100644 spec/FIX-1430/PLAN.md create mode 100644 spec/FIX-1430/SPEC.md create mode 100644 spec/FIX-1430/figures/the-view.svg create mode 100644 spec/FIX-1430/figures/what-changes.svg diff --git a/spec/FIX-1430/BUSINESS-RULES.md b/spec/FIX-1430/BUSINESS-RULES.md new file mode 100644 index 0000000000..8ee6ade31e --- /dev/null +++ b/spec/FIX-1430/BUSINESS-RULES.md @@ -0,0 +1,65 @@ +# FIX-1430 · Business rules + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) + +The cases as rules: what someone does, what happens, and which check proves it. A human reviews this page; the plan turns it into work. *Contract gate* is the model-free check; *goal check* is the model-backed run of the same host. + +## Declaring the team + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-1 | The lab's tree is read and hired | Exactly four seats — one coordinator, three workers — on the kinds their own files name, one channel, and one ledger minted from the channel at `org` scope. No id is written in any file | Contract gate | +| BR-2 | The coordinator's own file names the task tools | It can file and assign. A twin tree that omits them hires cleanly and cannot file: the names resolve, the grant does not | Contract gate · a refusal tree and its corrected twin | +| BR-3 | A seat's own folder holds a block that declares a board, or anything org-scoped | The whole roster is refused at hire, naming the block. The lab does not widen the seat-tool fence to get a board tool into a folder | Contract gate · refusal tree | + +## Filing and assigning + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-4 | The coordinator files four rows across three named assignees | Each row runs on the seat that assignee addresses, and on no other. **Negative control:** re-point one assignee at a different declared seat and watch this go red | Goal check | +| BR-5 | A row runs | It runs in its own session, whose parent is the session the row was filed from. Nothing carries the coordinator's transcript with it | Goal check · read off the session record | +| BR-6 | Two rows name the same assignee | The second stays `pending`, still holding that assignee, and runs when the seat frees. Nothing re-routes it to a free seat and nothing drops it | Goal check | +| BR-7 | A row is filed naming no assignee | Refused by name where it would have run. The lab declares no default worker, so a row for nobody is loud rather than quiet | Goal check · asserted on the refusal | +| BR-8 | Someone who is not a member of the channel files a row | Refused with the channel's own author-not-a-member reason, in the same words a refused post gets | Contract gate | +| BR-9 | The coordinator settles a row it never claimed | Allowed, exactly as the task tools allow it today. Recorded as observed behaviour rather than defended as a design | Contract gate | + +## The queue the coordinator sees + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-10 | The queue is read | Four columns — queued, running, waiting on you, done — each a grouping of rows that already exist. No field is written to produce one | Contract gate · the ledger compared before and after a read | +| BR-11 | A seat holds a live claim | It reads busy; a seat holding none reads idle. Idle is the absence of a claim, never a stamp somebody writes | Contract gate | +| BR-12 | A row is parked or blocked | It appears under *waiting on you*, carrying the reason already on the row | Contract gate | +| BR-13 | The queue is read at any moment | The task status set has exactly the members it had before this issue | CI · asserted on the enum, not on a reading of it | + +![A matrix of four queue columns against the row facts each is computed from. Queued reads status pending and the assignee. Running reads status in progress and a live claim. Waiting on you reads status parked or blocked and the reason already on the row. Done reads the terminal statuses. A fifth strip beneath shows seat idle derived from the absence of a live claim against the seats the lab hired. A heavy fence runs under the whole matrix, labelled nothing below this line is written, with the task status enum and the row fields drawn underneath it untouched.](figures/the-view.svg) + +Read down a column to see every fact it is allowed to touch. Everything below the fence is read and never written, which is the whole content of BR-10 and [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). The mermaid below names the same four paths. + +```mermaid +flowchart LR + R["the board's rows"] -->|"pending, with an assignee"| Q["queued"] + R -->|"in progress, live claim"| N["running"] + R -->|"parked or blocked, with its reason"| W["waiting on you"] + R -->|"terminal"| D["done"] + S["the seats the lab hired"] -.->|"no live claim"| I["idle"] +``` + +## What does not move + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-14 | This issue's diff is inspected | It touches `goals/` and nothing else. No published package gains a file, an export or a changeset ([D1](DECISIONS.md#d1)) | CI · a check over the diff, run rather than read | +| BR-15 | `goals/devforce-lab/` is run after this lands | Byte for byte as before. Its interim board shape and its two ledger declarations are untouched | Existing suite | +| BR-16 | Someone looks here for the nested cascade | It is not here. One hop: the channel's board, then the seat | Documented, not checked | +| BR-17 | The lab is run twice at two drain widths | Both runs are recorded, and neither is presented as the recommended setting ([D3](DECISIONS.md#d3)) | The comparison the lab writes out | + +## Failure taxonomy + +Everything about the **tree** is fatal at hire and collected: a bad seat folder, a missing tool grant or an undeclared board refuses the whole roster and names every problem, because a lab that boots short proves something other than what it claims. Everything about a **row** is a per-row outcome that leaves the ledger readable — an unroutable row refuses at the drain, a non-member's filing refuses at the channel, a failed row settles `errored` and stays visible in the queue. Nothing retries, because a retry would hide the thing the queue exists to show. + +## Acceptance criteria this issue owns + +A team declared entirely in files — one channel holding one board, one coordinator seat and three worker seats — takes in more work than it has seats. The coordinator files every row through the tools its own file grants it, names who each is for, and the rows run on those seats and no others, each in its own session parented to the coordinator's. The row that could not start immediately runs when a seat frees, without being re-routed. Throughout, the coordinator can say what is queued, what is running, what is waiting on a person, and what is done — every one of those read off rows that already existed. + +That is [ER-20](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) and [ER-21](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) together, and it is the epic's exit gate. Nothing else in the set makes this sentence true or false. diff --git a/spec/FIX-1430/DECISIONS.md b/spec/FIX-1430/DECISIONS.md new file mode 100644 index 0000000000..429ad72cd6 --- /dev/null +++ b/spec/FIX-1430/DECISIONS.md @@ -0,0 +1,86 @@ +# FIX-1430 · Decisions + +[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + +What was chosen, what lost, what each locks in. Three decisions are the sign-off surface. Calls this issue may not take — where a board lives, what an assignee is, which package format a capability arrives in — belong to [FIX-1385](https://github.com/fixpoint-labs/flow-state-dev/pull/1917), [FIX-1394](https://github.com/fixpoint-labs/flow-state-dev/pull/1915) and the epic. + +## The tree + +```mermaid +flowchart TD + I["FIX-1430"] --> D1["D1 · the lab ships no package code"] + D1 -.->|"rejected"| X1["export the queue view
a surface designed from one consumer"] + I --> D2["D2 · a queue, not a hand-off"] + D2 -.->|"rejected"| X2["FIX-1385's check with a third seat
proves the half nobody doubted"] + I --> D3["D3 · a busy seat's behaviour is shown"] + D3 -.->|"rejected"| X3["pick a drain width and move on
settles an epic wall in a goals folder"] +``` + +Solid edges are what you're signing. Dashed edges lost, and the label says why. + + +## D1 · The lab ships no package code; the queue columns stay lab-local + +| | | +|---|---| +| **Instead of** | Exporting the columns from `orchestration` or `workforce` as the Layer 2 view surface | +| **Because** | This issue owns one epic rule and no surface. [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) calls a queue column a *view* rather than a status — a fence on where it may not live, not a commission to build a view package. One consumer is not a design input, and this lab is the only one. An export would also put the issue behind the W3 ship fence for no gain in evidence | +| **Locks in** | The next consumer that wants columns derives them again, and this lab's shape is a suggestion rather than a contract. If the view turns out to be the product we pay a second design pass — on two examples instead of one, which is the cheaper mistake | + + +## D2 · The proof is a queue, not a hand-off: more rows than seats, and the coordinator assigns through the tools it declared + +| | | +|---|---| +| **Instead of** | Re-running FIX-1385's own goal check with a third seat and calling it the exit gate | +| **Because** | That check already shows a row filed by one seat and claimed by another — [ER-20](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)'s first half, the half nobody doubted. Its second half is a coordinator *assigning* to named seats, and routing to the only seat on a board is indistinguishable from not routing. [ER-21](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)'s columns say nothing until a row waits. Hence: several candidate seats, more rows than seats, and a coordinator filing through the model's door | +| **Locks in** | A slower check with more moving parts, and a flaky queue is a flaky exit gate. Worker seats therefore do small deterministic work and the model appears at one place only — how far that goes is [Q1](#q1) | + + +## D3 · What a busy seat does is shown, not chosen + +| | | +|---|---| +| **Instead of** | Picking a drain width for the lab and letting that choice read as the recommended shape | +| **Because** | Whether a busy seat gets a second copy or work queues behind it is one of four session-policy walls the epic took back from FIX-1408 — and the epic named *this lab, running a queue deep enough to matter*, as what would settle it. Deciding it inside `goals/` settles an epic wall where nobody reads decisions ([ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)) | +| **Locks in** | Two runs of one queue where one would do, and a reader looking for the recommended setting gets a comparison instead. When the epic rules, the lab is revisited to keep the ruled shape — the evidence costs a second visit, on purpose | + +## Decided, not asked + +- **No third `LabRoster`.** The lab reads its tree through whatever the package exports when it is built. FIX-1405 deletes the two copies that exist; a third while that is in flight is how a fourth appears. +- **Seat idle comes off the board's rows and the seats the lab hired**, not the live inventory — keeping blocking prerequisites at exactly one sibling. +- **No `defaultWorker`.** An unassigned row throws at the drain today. The lab shows that refusal rather than papering it, because "a row for nobody" is a case a queue meets. +- **The coordinator does not claim the rows it settles.** `taskTools` leaves an unclaimed settle unguarded on purpose; the lab records that rather than working around it. +- **Two checks over one host, differing by one block** — a model-free contract gate and a model-backed run. The devforce lab's shape, reused. +- **The channel's membership fence is consumed, not re-implemented.** A non-member filing is refused by the path a post already meets. + +## Considered and dropped + +| Alternative | Why not | +|---|---| +| **Grow `goals/devforce-lab` instead** | It is the epic's other evidence and carries a board shape labelled interim. Rewriting it mid-epic destroys the before/after that makes a one-line board legible | +| **A harness-backed coding run per row** | The devforce lab already owns row → supervised coding run. Re-proving it buys no new fact and buys a slow, flaky exit gate ([Q1](#q1)) | +| **Build the nested cascade here too** | Phase-2 inside W4, off the gate by the epic's D1. A gate has to be reachable on a schedule | +| **Read seat liveness from the live inventory** | A second blocking sibling for a fact the board already carries | +| **Let the coordinator dispatch seats directly, skipping the board** | That is today, and it is what the epic exists to replace | + + +## Open · one + +### Does the exit gate close on routing proved, or on routing proved all the way into real work? + +**In plain terms.** Either the demo ends at *the right worker picked up the right job and reported done*, or it ends at *the right worker picked up the right job, and here is the file it changed.* + +**The trade-off.** The narrow reading makes the gate fast, deterministic and rerunnable on every change — but an outsider reading *work reaches a seat that runs it* may reasonably hear the wider one. The wide reading is closer to the words and costs a check that takes minutes, needs a scratch repository and a live harness, and fails for reasons unrelated to routing. A gate that goes red for unrelated reasons stops being one. + +**My recommendation: the narrow one**, with worker seats doing small real work — writing a file the check reads back — rather than nothing. The wide claim is evidenced next door: `goals/devforce-lab/` shows a board row becoming a supervised coding run. What has never been shown is a *queue* crossing from a declared coordinator to declared seats, and that is the gap this issue was adopted to close. + +**What would change my mind.** If the promise will be read publicly as *declare a team in Markdown and it ships code*, the two halves have to meet in one run at least once, and this is the cheapest place to make them meet. + +**What being wrong costs.** Narrow when it was wide: the epic wraps on a claim narrower than it reads, and someone builds the wide check afterwards — a few days, nothing already built thrown away. Wide when it was narrow: the gate is slow and intermittently red from the day it lands, which is worse because it is permanent. + +**Settled: none.** No claim here has been argued twice. + +## How it got here + +- **Draft** — framed as evidence rather than surface: owns one rule, builds no export, consumes four. The delta against FIX-1385's goal check was made explicit early, because repeating a sibling's check is the obvious way this issue fails quietly. diff --git a/spec/FIX-1430/PLAN.md b/spec/FIX-1430/PLAN.md new file mode 100644 index 0000000000..be00e34034 --- /dev/null +++ b/spec/FIX-1430/PLAN.md @@ -0,0 +1,121 @@ +# FIX-1430 · Plan + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** + +For the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSINESS-RULES.md) (BR-n) and [DECISIONS.md](DECISIONS.md) (D-n). `tdd`. One PR. Written against `d8e4c99`. + +## What this consumes, and what it waits for + +**From FIX-1394: neither the contract nor the implementation as a build input — only [ER-2](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) as a fence.** The lab's seats carry instructions, skills and tools on surfaces that already shipped, and FIX-1394 changes none of them: its own spec ships no format and leaves today's behaviour byte for byte. Nothing to write against, nothing to wait for. What ER-2 binds is *authoring* — this lab invents no package shape — so all four of FIX-1394's possible answers, *don't collapse* included, leave it compatible. The worry that a ratify might not satisfy a proof needing the package to **exist** does not reach here: the proof needs no package. + +**From FIX-1385: the implementation, landed.** `boards:` in a channel file, the minted ledger id, the channel's file and read actions, the task-tools resolver on the kind, the seat-side helper. A real blocking edge, not a contract one. + +**Which side of [ER-14](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) this sits on.** The one PR is on the **evidence** side: it adds no file to a published package (BR-14), so it is no W4 ship PR and the fence does not hold it. It still cannot go green until FIX-1385's board PRs have landed, and those *are* ship PRs the fence holds. Unfenced, and behind the fence in practice — spec now, build when the board surface exists. + +## Surfaces + +| ID | Role | Change | Rules | +|---|---|---|---| +| S1 | `goals/manager-queue-lab/lab/workforce/` · the tree | One team: a channel declaring one board, a coordinator seat naming the task tools in its own file, three worker seats | BR-1 BR-2 | +| S2 | The kinds, under `flows/workers/` | The coordinator's installs the task tools against the channel's ledger; the worker's declares the same ledger and drains it, one assignee key per worker seat, no default worker | BR-4 BR-5 BR-7 | +| S3 | `lab/host.mts` | Read the tree, build the kinds, hire, register, open the channel, hand back handles — through the package's own roster reader, **no third `LabRoster`** | BR-1 | +| S4 | `lab/queue.mts` | A pure read: rows plus the hired seats to four columns and per-seat idle. Writes nothing | BR-10 BR-11 BR-12 | +| S5 | `lab/refusal-trees/` | Two twins and their corrected pairs: a coordinator naming no task tools, a seat folder holding a block that declares the board | BR-2 BR-3 | +| S6 | The contract gate, model-free | The tree, both refusals, the columns, the enum, the diff check | BR-1–BR-3 BR-8–BR-14 | +| S7 | The goal check, model-backed | The coordinator decides who gets what: four rows across three assignees, so one assignee holds two | BR-4–BR-7 | +| S8 | The drain-width comparison | The same queue at two widths, written out as the epic's [ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) evidence. Neither recommended | BR-17 | +| S9 | `lab/README.md` and the diff check | What the lab proves, what it does not, the check keeping it inside `goals/` | BR-14 BR-16 | + +## Sequence + +```mermaid +flowchart TD + S1["S1 · the tree"] --> S2["S2 · the two kinds"] + S2 --> S3["S3 · the host"] + S3 --> S4["S4 · the queue read"] + S3 --> S5["S5 · the refusal trees"] + S4 --> S6["S6 · the contract gate"] + S5 --> S6 + S6 --> S7["S7 · the goal check"] + S7 --> S8["S8 · the drain-width comparison"] + S7 --> S9["S9 · README and the diff check"] +``` + +## Checks + +| ID | After | Passes when | +|---|---|---| +| V1 | S3 | BR-1. **Negative control:** rename one seat's kind to an unregistered one, watch the whole roster refuse, restore it | +| V2 | S5 | BR-2 and BR-3, each against its corrected twin. Both asserted on the seat or block **named**, never on message text | +| V3 | S4 | BR-10, BR-11, BR-12. BR-10 by comparing the ledger before and after a queue read — a view that wrote something fails here | +| V4 | S6 | BR-13 on the enum itself; BR-14 as a check over this issue's diff, run rather than read; BR-8 and BR-9 through the channel | +| VG | S7 | **Goal, real path:** four rows, three assignees, three worker seats. Every row lands where its assignee points (BR-4), each in a session parented to the coordinator's (BR-5); the fourth waits, then runs (BR-6); a row naming nobody refuses loudly (BR-7). **Negative control:** re-point one assignee at a different declared seat and watch BR-4 go red | +| V5 | S8 | Both runs complete and both are recorded, with what each did to the waiting row (BR-17) | + +**Every held-out fact is read out of the tree at run time**, as both existing labs do: a token that decides a check lives in one convention file and in none of the lab's code, so a different valid tree still passes a correct implementation. + +## Pinned names · the only three + +| Where | Name | Why pinned | +|---|---|---| +| The channel | `eng.queue`, holding `boards: [work]` | The ledger id is minted from it, and the checks address that id | +| The board's assignee keys | Deliberately **not** the seat ids — a distinct spelling for each | [ER-5](https://github.com/fixpoint-labs/flow-state-dev/pull/1905): an assignee is a routing key, not a seat. Identical spellings would let a check that conflates them pass | +| The lab root | `goals/manager-queue-lab/` | Cited from the epic, and by BR-14's diff check | + +Everything else is yours, the column names included. + +## Guardrails + +| Rule | Because | +|---|---| +| The seat-tool fence is not widened, anywhere | It landed stricter than its own spec read, and a board tool in a seat folder is the shape that tempts a loosening. BR-3 is that temptation, as a refusal | +| Nothing under `goals/` is imported by anything under `packages/` | D1. A lab that becomes a dependency has stopped being evidence | +| Every column is derived on read, and the queue module holds no state | BR-10, and [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). A cached column is a second copy of the board | +| The assignee-to-seat map lives in the host, supplied by the caller, never read from the tree | It is the app's — and a supplied map is the only way VG's negative control can point an assignee at the wrong seat | +| No epic wall is answered in a comment in this folder | [ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). Evidence goes up to the epic PR; decisions come back down | + +## Docs + +- **CREATE** `goals/manager-queue-lab/lab/README.md` — what the tree declares, what each check grades, what the drain-width comparison is for, and one paragraph on what this lab does **not** prove. *Voice risk:* writing it as a tutorial. It is evidence. +- **No `apps/docs` page and no package README change.** Teaching routing as something a team gets by attaching a board is [ER-22](https://github.com/fixpoint-labs/flow-state-dev/pull/1905), the epic's docs pass; FIX-1385 already carries the channels-page edit. +- **No changeset** (BP-022): `goals/` is private and no published package changes. + +## Sketch · pseudocode, illustrative, react to the shape + +``` +the tree: one channel declaring one board; a coordinator seat whose own + file names the task tools; three worker seats + +the host: read the tree through the package's reader + build the coordinator kind: task tools -> this channel's ledger + build the worker kind: the same ledger, drained, + one assignee key per worker seat + hire, register, open the channel + +the queue: rows, and the seats we hired -> + queued = pending, grouped by assignee + running = in progress with a live claim + waiting-on-you = parked or blocked, with the row's own reason + done = terminal + idle = a hired seat holding no live claim + reads only; writes nothing + +the check: coordinator files four rows across three assignees + each row runs where its assignee points, and nowhere else + the fourth waits, then runs + a row naming nobody refuses at the drain +``` + +**POC: none.** The two premises underneath this — that a channel can hold a ledger a seat drains, and that a seat's declared task tools can be pointed at it — are FIX-1385's, and its plan records reading them in the code rather than running them. A POC here would re-derive a sibling's premise against a surface that does not exist yet. The premise this issue owns is the queue, and a queue POC over an unbuilt board is this lab, early. + +## At implement time + +- **Re-read the board surface as it actually landed**, not as [PR #1917](https://github.com/fixpoint-labs/flow-state-dev/pull/1917) specified it. The minted id, the seat-side helper's shape and where the task-tools resolver is installed are what move. +- **Check whether `readDeclaredRoster` has landed** (FIX-1405). If so, read the tree through it; if not, use the three readers directly, and still hand-roll nothing reusable. +- **Check the four returned session-policy walls** on the epic before wiring the dispatcher. Two are visible at this queue depth: whether a seat already running has its session reused, and what a busy seat does. If either has been ruled, follow it; otherwise show it and report up. +- **`goals/devforce-lab/` declares one ledger twice on purpose.** Interim, and not the shape to copy. + +## Follow-ups + +- **Whether a channel board should carry a default worker** is FIX-1385's surface, not this lab's. BR-7 shows what happens without one; file the question there. +- If the queue columns survive a second consumer, they are a candidate export. Not before ([D1](DECISIONS.md#d1)). diff --git a/spec/FIX-1430/SPEC.md b/spec/FIX-1430/SPEC.md new file mode 100644 index 0000000000..4d14f28ba5 --- /dev/null +++ b/spec/FIX-1430/SPEC.md @@ -0,0 +1,75 @@ +# FIX-1430 · Manager-queue lab — the proof that work reaches a seat + +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + +Feature (evidence) · `goals/` only · medium · 1 PR · epic [FIX-1407 · W4](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) + +## Five people, before and after + +| Someone who… | Today | After | +|---|---|---| +| **has a declared team and work to hand out** | Hands it out one dispatch at a time, from code. Nothing shows what waits or who holds it | Files rows on the team's channel board, names who each is for, watches a queue | +| **asks whether routing actually works** | Two halves, proved alone and never together: a post reaching seats declared in Markdown, and a board row becoming a real run over a board written in TypeScript | One run, one tree of Markdown: a coordinator files, the board routes, three seats work | +| **wants to see what the team is waiting on** | Reads raw rows and counts them | Four columns — queued, running, waiting on you, done — each computed at read time, none stored | +| **files more work than the team has seats** | No shared queue to file it on | Rows wait, holding the seat they were filed for. Nothing is lost, nothing is re-routed | +| **wires a board for a team today** | Forty-odd lines of TypeScript per team, the ledger declared twice so the claim gate passes | One line in the channel's file. The old shape stays next door, so the two stand side by side | + +**Why this one.** The epic's claim is one sentence: *work filed for a team reaches a seat that runs it.* Four of its five issues build surface for that sentence; none makes it true or false. We can ship a declarable board, a runtime roster and a package format and still never watch a row cross from the person who filed it to the seat that finished it — and a claim nobody has watched is an intention, not a result. This is where it gets run. It owns [ER-20](https://github.com/fixpoint-labs/flow-state-dev/pull/1905), the epic's exit gate, and nothing else. + +It is a **lab**, the way `goals/pentest-lab/` is: a small tree of Markdown, a host that reads it, checks that grade what happened. Nothing it adds is importable. Written against landed code at `d8e4c99` and against the board surface [FIX-1385](https://github.com/fixpoint-labs/flow-state-dev/pull/1917) is specifying, which must merge before this can run. + +## What changes + +![Today and after, side by side. Today a team's board is about forty lines of TypeScript declared twice, once on the coordinator flow and once on the recipient so the claim gate passes, with one assignee key, one row, one hand-off and no queue. After, one boards line in the channel's own file mints the ledger, a coordinator seat files four rows through the task tools its own file grants it, and rows route by assignee to three declared seats while a fourth waits behind a busy seat; four queue columns sit below as a read-time view over rows that already exist.](figures/what-changes.svg) + +Left is what a team writes today, and it is code. Right is the same team written as files, with one more row in flight than there are seats to run it — the case the columns exist for. + +**What the team's channel declares:** + +```diff + --- + description: Where this team takes in work. + members: [eng.manager, eng.builder-a, eng.builder-b, eng.builder-c] ++ boards: [work] + --- +``` + +**What the coordinator's own file grants it:** + +```diff + --- + description: Takes work in, decides who does it, says where it stands. ++ tools: [addTask, assignTask, listTasks, completeTask] + --- +``` + +The seat names the tools; its flow points them at the channel's ledger. Registration makes a name resolvable, declaration grants its use — the fence that landed with FIX-1416, unwidened here. + +## How a row reaches a seat + +```mermaid +flowchart LR + M["the coordinator seat"] -->|"a row, carrying an assignee"| L["eng.queue.work · the channel's ledger"] + L -->|"same id, seat side"| D["the drain"] + D -->|"routes on assignee"| S["builder-a · its own linked session"] + D -.->|"that seat is busy"| Q["the row waits, assignee kept"] + L -->|"read, never written"| V["the queue columns"] +``` + +One hop. The coordinator names no session, flow or seat instance — only an assignee on a row. The address map the app holds does the rest. + +## What stays as it is + +- **Every published package.** A folder under `goals/`, and nothing a consumer installs. +- **`goals/devforce-lab/`.** Its hand-rolled ledger stays, labelled interim where it lives. Editing evidence while it is being cited is a bad trade. +- **The task status set.** No new member, no new Layer 1 type: a column groups rows that already exist ([ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)). +- **The nested cascade** — personal boards, request boards, a row that fans into rows. This issue's *other* half, phase-2 inside W4 and off this gate. +- **Which package format a capability arrives in.** FIX-1394 settles it; this lab authors no new one ([ER-2](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)). + +## Sign off + +1. **[D1](DECISIONS.md#d1) · The lab ships no package code — the queue columns stay lab-local.** *If wrong:* a view surface is designed from one example, exported, then redesigned when a second consumer disagrees. +2. **[D2](DECISIONS.md#d2) · The proof is a queue, not a hand-off: more rows than seats, the coordinator assigning through the tools it declared.** *If wrong:* we re-run FIX-1385's own check with an extra seat, call it the exit gate, and prove the half of ER-20 nobody doubted. +3. **[D3](DECISIONS.md#d3) · What a busy seat does is shown, not chosen: the same queue runs twice and the comparison goes to the epic.** *If wrong:* a lab settles a policy the epic owns, in a folder nobody reads as a decision. + +**Open: one** — how much realism ER-20 closes on ([Q1](DECISIONS.md#q1)). Number 2 is the one to weigh: it is what separates this from a second copy of a check that already exists. Reasoning and what lost: [DECISIONS.md](DECISIONS.md). The cases: [BUSINESS-RULES.md](BUSINESS-RULES.md). diff --git a/spec/FIX-1430/figures/the-view.svg b/spec/FIX-1430/figures/the-view.svg new file mode 100644 index 0000000000..120567e062 --- /dev/null +++ b/spec/FIX-1430/figures/the-view.svg @@ -0,0 +1,83 @@ + + + + WHAT THE COORDINATOR SEES · EACH COLUMN, AND EVERY FACT IT READS + + + + queued + + running + + waiting on you + + done + + + + + status: pending + + assignee + + + status: in_progress + + a live claim + + + status: parked · blocked + + the reason on the row + + + completed · errored · cancelled + + nothing else + + + + + seat idle + + a hired seat holding no live claim — absence, not a stamp + + the seats the lab hired + + + + + NOTHING BELOW THIS LINE IS WRITTEN + + + + + THE STATUS SET · UNCHANGED + pending · in_progress · blocked · parked + completed · errored · cancelled + + + THE ROW · UNCHANGED + assignee · claimedBy · leaseUntil · feedback + no field added, no field written by a read + + diff --git a/spec/FIX-1430/figures/what-changes.svg b/spec/FIX-1430/figures/what-changes.svg new file mode 100644 index 0000000000..4a2306dba1 --- /dev/null +++ b/spec/FIX-1430/figures/what-changes.svg @@ -0,0 +1,108 @@ + + + + + + + + + + + + + TODAY + the board is code + + + lab/board.mts + coordinatorBoard() — hands the row across + recipientBoard() — interim, drains nobody + one ledger id, spelled twice · about forty lines per team + + + one row + + + assignee + coder + + + the seat + + No queue. One row, one hand-off, and nothing the + team itself can read. + + + + AFTER + the board is one line in a file + + + channels/queue/CHANNEL.md + boards: [work] + + + eng.queue.work + minted from the channel + + + workers/manager + files four rows + + + + + + + + + builder-a + running + + builder-b + running + + builder-c + running + + + row 4 · waiting + + + + + THE QUEUE · READ, NEVER WRITTEN + + queued + + running + + waiting on you + + done + + From 50af21c04d8da495cbbae535a474cafcdf3deea8 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 19 Sep 2026 03:53:44 +0000 Subject: [PATCH 2/3] =?UTF-8?q?spec(FIX-1430):=20round=201=20=E2=80=94=20r?= =?UTF-8?q?outing=20claim=20gets=20an=20oracle,=20BR-6=20goes=20observatio?= =?UTF-8?q?nal?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Folds spec-level findings from Cursor, Greptile and Codex. - BR-4's negative control could not fail: it mutated the caller-supplied assignee-to-seat map, which PLAN declared the sole authority, so repointing it moved the correct destination along with the routing. The expected association is now held out in the tree (each worker seat's file names the assignee it answers for) while the host's map stays the implementation under test, and VG states the red state it produces. - BR-6 required a busy seat's second row to read `pending`. A hand-off claims a row before its child starts and leaves it `in_progress` (docs/architecture/dispatched-work.md, "The claim gate and the fence ticket"), so that reading is not guaranteed — and requiring it also settled the busy-seat policy D3 says this lab must only show. BR-6 now requires what holds at every drain width (nothing re-routes, nothing drops, the assignee is held) and records the status instead. - D3 dissolved: "shown, not chosen" means the lab is wired to run at either width from one switch, not that this issue's CI runs the queue twice. S8/V5 come off the merge bar; the two-width comparison lands when the epic asks. - PLAN pins assignee `eligibility` on every drain's claim. ClaimOptions narrows candidates before the CAS flip; omit it and a drain claims a row addressed to another seat, keyedRouter misses, and recordError settles the row `errored`. - Queued is the substrate's admission predicate, not `pending` alone, so an in_progress row with a lapsed lease is no longer in no column at all. The claim gate refuses adoption past the lease, so queued is where it belongs. Figure and alt text redrawn to match. - A missing tool grant is not hire-fatal: `tools:` grants use, so a seat that omits it hires cleanly and fails at filing. Taxonomy corrected, BR-2 kept. - The diff gate now rejects goals/devforce-lab/ — a behavioural suite cannot prove a tree unchanged. Q1 stays open and stays the owner's. The narrow shape it would pick is now a hard requirement of the plan so the gate cannot widen while it is open. Two SPEC-layout findings refuted and left open: spec-template.md governs a spec document's headings, and writing-for-humans.md exempts structural navigation from "nothing precedes the problem". Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T --- spec/FIX-1430/BUSINESS-RULES.md | 29 +++++++++--------------- spec/FIX-1430/DECISIONS.md | 9 +++++++- spec/FIX-1430/PLAN.md | 36 +++++++++++++++++++++--------- spec/FIX-1430/SPEC.md | 2 +- spec/FIX-1430/figures/the-view.svg | 4 ++-- 5 files changed, 47 insertions(+), 33 deletions(-) diff --git a/spec/FIX-1430/BUSINESS-RULES.md b/spec/FIX-1430/BUSINESS-RULES.md index 8ee6ade31e..8162971f60 100644 --- a/spec/FIX-1430/BUSINESS-RULES.md +++ b/spec/FIX-1430/BUSINESS-RULES.md @@ -16,9 +16,9 @@ The cases as rules: what someone does, what happens, and which check proves it. | # | When | Then | Proved by | |---|---|---|---| -| BR-4 | The coordinator files four rows across three named assignees | Each row runs on the seat that assignee addresses, and on no other. **Negative control:** re-point one assignee at a different declared seat and watch this go red | Goal check | +| BR-4 | The coordinator files four rows across three named assignees | Each row runs on the seat that assignee addresses, and on no other. The expected assignee-to-seat association is held out **in the tree** — each worker seat's own file names the assignee it answers for — and never read from the host's map, which is the routing implementation under test. **Negative control:** re-point one assignee in the host's map at a different declared seat. The tree still says where the row should have gone, the run says where it went, and the two now disagree: the row is observed on a seat whose own file claims a different assignee, and BR-4 goes red | Goal check | | BR-5 | A row runs | It runs in its own session, whose parent is the session the row was filed from. Nothing carries the coordinator's transcript with it | Goal check · read off the session record | -| BR-6 | Two rows name the same assignee | The second stays `pending`, still holding that assignee, and runs when the seat frees. Nothing re-routes it to a free seat and nothing drops it | Goal check | +| BR-6 | Two rows name the same assignee, and there is no free seat for the second | Neither row is re-routed and neither is dropped: both are observed reaching the seat their assignee names, and the second runs once that seat frees. **What the waiting row's status reads is recorded, not required** — a hand-off claims a row before its child starts and leaves it `in_progress` (`docs/architecture/dispatched-work.md` -> "The claim gate and the fence ticket"), so `pending` is not the only honest reading of a row that is waiting. Which reading each drain width produces is [D3](DECISIONS.md#d3)'s comparison, not this issue's assertion | Goal check · the status recorded per run | | BR-7 | A row is filed naming no assignee | Refused by name where it would have run. The lab declares no default worker, so a row for nobody is loud rather than quiet | Goal check · asserted on the refusal | | BR-8 | Someone who is not a member of the channel files a row | Refused with the channel's own author-not-a-member reason, in the same words a refused post gets | Contract gate | | BR-9 | The coordinator settles a row it never claimed | Allowed, exactly as the task tools allow it today. Recorded as observed behaviour rather than defended as a design | Contract gate | @@ -27,36 +27,27 @@ The cases as rules: what someone does, what happens, and which check proves it. | # | When | Then | Proved by | |---|---|---|---| -| BR-10 | The queue is read | Four columns — queued, running, waiting on you, done — each a grouping of rows that already exist. No field is written to produce one | Contract gate · the ledger compared before and after a read | -| BR-11 | A seat holds a live claim | It reads busy; a seat holding none reads idle. Idle is the absence of a claim, never a stamp somebody writes | Contract gate | +| BR-10 | The queue is read | Four columns — queued, running, waiting on you, done — each a grouping of rows that already exist. No field is written to produce one. **Queued is the substrate's own admission predicate, not `pending` alone:** a row whose worker died — `in_progress` with a lapsed lease — is claimable, so it reads queued, because the next drain is what takes it back (`isClaimable`, `packages/orchestration/src/tasks/collection/internal.ts`). Every row lands in exactly one column; a row in none of them is a bug in the view | Contract gate · the ledger compared before and after a read, and a lapsed-lease row asserted into queued | +| BR-11 | A seat holds a live claim | It reads busy; a seat holding none reads idle. Idle is the absence of a claim, never a stamp somebody writes. **A seat whose claimed row has a lapsed lease reads idle, and that row reads queued** — nobody is on it, and nobody can quietly resume it either: the claim gate refuses an adoption once the lease has lapsed (`StaleTaskClaimError`), so the row is genuinely back in the queue rather than in flight | Contract gate | | BR-12 | A row is parked or blocked | It appears under *waiting on you*, carrying the reason already on the row | Contract gate | | BR-13 | The queue is read at any moment | The task status set has exactly the members it had before this issue | CI · asserted on the enum, not on a reading of it | -![A matrix of four queue columns against the row facts each is computed from. Queued reads status pending and the assignee. Running reads status in progress and a live claim. Waiting on you reads status parked or blocked and the reason already on the row. Done reads the terminal statuses. A fifth strip beneath shows seat idle derived from the absence of a live claim against the seats the lab hired. A heavy fence runs under the whole matrix, labelled nothing below this line is written, with the task status enum and the row fields drawn underneath it untouched.](figures/the-view.svg) +![A matrix of four queue columns against the row facts each is computed from. Queued reads the rows the claim path would admit — status pending, or in progress with a lapsed lease, which is a row whose worker died — grouped by assignee. Running reads status in progress and a live claim. Waiting on you reads status parked or blocked and the reason already on the row. Done reads the terminal statuses. A fifth strip beneath shows seat idle derived from the absence of a live claim against the seats the lab hired. A heavy fence runs under the whole matrix, labelled nothing below this line is written, with the task status enum and the row fields drawn underneath it untouched.](figures/the-view.svg) -Read down a column to see every fact it is allowed to touch. Everything below the fence is read and never written, which is the whole content of BR-10 and [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). The mermaid below names the same four paths. - -```mermaid -flowchart LR - R["the board's rows"] -->|"pending, with an assignee"| Q["queued"] - R -->|"in progress, live claim"| N["running"] - R -->|"parked or blocked, with its reason"| W["waiting on you"] - R -->|"terminal"| D["done"] - S["the seats the lab hired"] -.->|"no live claim"| I["idle"] -``` +Read down a column to see every fact it is allowed to touch. Everything below the fence is read and never written, which is the whole content of BR-10 and [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). This figure is the one picture of the columns; the rules above are their text. ## What does not move | # | When | Then | Proved by | |---|---|---|---| -| BR-14 | This issue's diff is inspected | It touches `goals/` and nothing else. No published package gains a file, an export or a changeset ([D1](DECISIONS.md#d1)) | CI · a check over the diff, run rather than read | -| BR-15 | `goals/devforce-lab/` is run after this lands | Byte for byte as before. Its interim board shape and its two ledger declarations are untouched | Existing suite | +| BR-14 | This issue's diff is inspected | It touches `goals/` and nothing else, **and nothing under `goals/devforce-lab/`** — the one subtree inside the fence this issue must also leave alone. No published package gains a file, an export or a changeset ([D1](DECISIONS.md#d1)) | CI · a check over the diff, run rather than read | +| BR-15 | `goals/devforce-lab/` is run after this lands | Byte for byte as before. Its interim board shape and its two ledger declarations are untouched | BR-14's diff gate, which rejects that subtree — a behavioural suite cannot prove a tree unchanged · its existing suite still green | | BR-16 | Someone looks here for the nested cascade | It is not here. One hop: the channel's board, then the seat | Documented, not checked | -| BR-17 | The lab is run twice at two drain widths | Both runs are recorded, and neither is presented as the recommended setting ([D3](DECISIONS.md#d3)) | The comparison the lab writes out | +| BR-17 | The epic asks what a busy seat does | The lab runs at either drain width from one documented switch, with no edit to the tree and none to the checks. Running both and writing out the comparison is [ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) evidence the epic calls for, and neither width is presented as the recommended setting ([D3](DECISIONS.md#d3)) | Contract gate · the switch exercised at both values · the comparison when the epic asks | ## Failure taxonomy -Everything about the **tree** is fatal at hire and collected: a bad seat folder, a missing tool grant or an undeclared board refuses the whole roster and names every problem, because a lab that boots short proves something other than what it claims. Everything about a **row** is a per-row outcome that leaves the ledger readable — an unroutable row refuses at the drain, a non-member's filing refuses at the channel, a failed row settles `errored` and stays visible in the queue. Nothing retries, because a retry would hide the thing the queue exists to show. +A malformed or forbidden **declaration** is fatal at hire and collected: a bad seat folder, a `seatTools:` key in a worker file, a block declaring a board or anything org-scoped — each refuses the whole roster and names every problem, because a lab that boots short proves something other than what it claims. **A missing tool grant is not in that class.** `tools:` is what grants a registered name's use, so a seat that omits it has nothing to refuse at hire: it hires cleanly and the tool is simply absent from its catalog. That is why BR-2's twin fails where it does — at filing, not at hire. Everything about a **row** is a per-row outcome that leaves the ledger readable — an unroutable row refuses at the drain, a non-member's filing refuses at the channel, a failed row settles `errored` and stays visible in the queue. Nothing retries, because a retry would hide the thing the queue exists to show. ## Acceptance criteria this issue owns diff --git a/spec/FIX-1430/DECISIONS.md b/spec/FIX-1430/DECISIONS.md index 429ad72cd6..d11e0cd08f 100644 --- a/spec/FIX-1430/DECISIONS.md +++ b/spec/FIX-1430/DECISIONS.md @@ -14,6 +14,7 @@ flowchart TD D2 -.->|"rejected"| X2["FIX-1385's check with a third seat
proves the half nobody doubted"] I --> D3["D3 · a busy seat's behaviour is shown"] D3 -.->|"rejected"| X3["pick a drain width and move on
settles an epic wall in a goals folder"] + D3 -.->|"rejected"| X4["run both widths in this issue's CI
a second deliverable on the exit gate"] ``` Solid edges are what you're signing. Dashed edges lost, and the label says why. @@ -43,7 +44,9 @@ Solid edges are what you're signing. Dashed edges lost, and the label says why. |---|---| | **Instead of** | Picking a drain width for the lab and letting that choice read as the recommended shape | | **Because** | Whether a busy seat gets a second copy or work queues behind it is one of four session-policy walls the epic took back from FIX-1408 — and the epic named *this lab, running a queue deep enough to matter*, as what would settle it. Deciding it inside `goals/` settles an epic wall where nobody reads decisions ([ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)) | -| **Locks in** | Two runs of one queue where one would do, and a reader looking for the recommended setting gets a comparison instead. When the epic rules, the lab is revisited to keep the ruled shape — the evidence costs a second visit, on purpose | +| **What "shown" means, exactly** | The lab is **wired so either width runs from one documented switch** — no edit to the tree, none to the checks. It does **not** mean this issue's CI runs the whole queue twice. Running both and writing out the comparison is evidence the epic asks for when it wants to rule, and it is off this issue's merge bar (BR-17). The decision is unchanged; only the work it implies moved | +| **And what the lab may therefore not assert** | If the lab must not choose the busy-seat policy, it cannot require the waiting row to read `pending` either — that reading *is* one of the two candidate policies. BR-6 keeps what holds at every width (nothing re-routes, nothing drops, the assignee is held) and records the status rather than requiring it. A hand-off leaves a claimed row `in_progress` while its child is still queued (`docs/architecture/dispatched-work.md` -> "The claim gate and the fence ticket"), so requiring `pending` would have pinned the gate to a state the landed path need not produce | +| **Locks in** | A reader looking for the recommended setting gets a comparison instead, and the epic owes a ruling before anyone can copy this lab as a shape. When it rules, the lab is revisited to keep the ruled width — the evidence costs a second visit, on purpose | ## Decided, not asked @@ -79,6 +82,10 @@ Solid edges are what you're signing. Dashed edges lost, and the label says why. **What being wrong costs.** Narrow when it was wide: the epic wraps on a claim narrower than it reads, and someone builds the wide check afterwards — a few days, nothing already built thrown away. Wide when it was narrow: the gate is slow and intermittently red from the day it lands, which is worse because it is permanent. +**Still open, and not settled here.** This is the product owner's call and it is with them. + +**What is fenced while they decide.** Both reviewers asked for the same thing underneath the question, and it costs nothing to give: the *narrow* shape is now a hard requirement of the plan rather than a recommendation waiting on an answer — stub worker handlers doing small deterministic work, one model surface (the coordinator, and nothing else), and pentest-style poll and timeout fixtures ([PLAN](PLAN.md) -> Guardrails, and V-G). So the gate cannot widen toward devforce economics while the question is open. If the answer comes back wide, that is a change to make then, with the cost visible — not a door left open now. + **Settled: none.** No claim here has been argued twice. ## How it got here diff --git a/spec/FIX-1430/PLAN.md b/spec/FIX-1430/PLAN.md index be00e34034..8435dad9c6 100644 --- a/spec/FIX-1430/PLAN.md +++ b/spec/FIX-1430/PLAN.md @@ -17,14 +17,14 @@ For the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSINESS-RUL | ID | Role | Change | Rules | |---|---|---|---| | S1 | `goals/manager-queue-lab/lab/workforce/` · the tree | One team: a channel declaring one board, a coordinator seat naming the task tools in its own file, three worker seats | BR-1 BR-2 | -| S2 | The kinds, under `flows/workers/` | The coordinator's installs the task tools against the channel's ledger; the worker's declares the same ledger and drains it, one assignee key per worker seat, no default worker | BR-4 BR-5 BR-7 | +| S2 | The kinds, under `flows/workers/` | The coordinator's installs the task tools against the channel's ledger; the worker's declares the same ledger and drains it, one assignee key per worker seat, no default worker. **Each drain narrows its own claim to its assignee** — see the guardrail below, which is the difference between BR-4 holding and the lab eating its own rows | BR-4 BR-5 BR-7 | | S3 | `lab/host.mts` | Read the tree, build the kinds, hire, register, open the channel, hand back handles — through the package's own roster reader, **no third `LabRoster`** | BR-1 | | S4 | `lab/queue.mts` | A pure read: rows plus the hired seats to four columns and per-seat idle. Writes nothing | BR-10 BR-11 BR-12 | -| S5 | `lab/refusal-trees/` | Two twins and their corrected pairs: a coordinator naming no task tools, a seat folder holding a block that declares the board | BR-2 BR-3 | +| S5 | `lab/refusal-trees/` | Two twins and their corrected pairs: a coordinator naming no task tools (**hires, then refuses at filing** — not a hire-time refusal, so do not file it under the refusal trees without saying so), a seat folder holding a block that declares the board (refused at hire) | BR-2 BR-3 | | S6 | The contract gate, model-free | The tree, both refusals, the columns, the enum, the diff check | BR-1–BR-3 BR-8–BR-14 | | S7 | The goal check, model-backed | The coordinator decides who gets what: four rows across three assignees, so one assignee holds two | BR-4–BR-7 | -| S8 | The drain-width comparison | The same queue at two widths, written out as the epic's [ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) evidence. Neither recommended | BR-17 | -| S9 | `lab/README.md` and the diff check | What the lab proves, what it does not, the check keeping it inside `goals/` | BR-14 BR-16 | +| S8 | The drain-width **switch** | One documented knob that runs the lab at either width with no edit to the tree and none to the checks. **The comparison itself is not on this issue's merge bar** ([D3](DECISIONS.md#d3)): what ships here is the wiring plus a stated way to run it, and the two-width evidence lands when the epic asks for it | BR-17 | +| S9 | `lab/README.md` and the diff check | What the lab proves, what it does not, the check keeping it inside `goals/` **and out of `goals/devforce-lab/`** — the diff gate rejects that subtree too, because BR-15's "byte for byte" is not something a behavioural suite can prove | BR-14 BR-15 BR-16 | ## Sequence @@ -46,11 +46,11 @@ flowchart TD | ID | After | Passes when | |---|---|---| | V1 | S3 | BR-1. **Negative control:** rename one seat's kind to an unregistered one, watch the whole roster refuse, restore it | -| V2 | S5 | BR-2 and BR-3, each against its corrected twin. Both asserted on the seat or block **named**, never on message text | +| V2 | S5 | BR-2 and BR-3, each against its corrected twin. **They fail at different moments, and the checks must not be written alike:** BR-3's tree is refused at hire and is asserted on the block **named**; BR-2's twin *hires cleanly* — omitting `tools:` leaves nothing to refuse — and is asserted on the refusal it gets **at filing**, naming the tool. Neither asserts on message text | | V3 | S4 | BR-10, BR-11, BR-12. BR-10 by comparing the ledger before and after a queue read — a view that wrote something fails here | | V4 | S6 | BR-13 on the enum itself; BR-14 as a check over this issue's diff, run rather than read; BR-8 and BR-9 through the channel | -| VG | S7 | **Goal, real path:** four rows, three assignees, three worker seats. Every row lands where its assignee points (BR-4), each in a session parented to the coordinator's (BR-5); the fourth waits, then runs (BR-6); a row naming nobody refuses loudly (BR-7). **Negative control:** re-point one assignee at a different declared seat and watch BR-4 go red | -| V5 | S8 | Both runs complete and both are recorded, with what each did to the waiting row (BR-17) | +| VG | S7 | **Goal, real path:** four rows, three assignees, three worker seats. Every row lands where its assignee points (BR-4), each in a session parented to the coordinator's (BR-5); the fourth is not re-routed and not dropped, and runs once its seat frees (BR-6); a row naming nobody refuses loudly (BR-7). **Negative control, and the red state it actually produces:** re-point one assignee in the host's map at a different declared seat, leaving the tree alone. The row is then observed running on a seat whose own file claims a different assignee — implementation and oracle disagree — and BR-4 fails on that mismatch. The control moves only the thing under test, which is why it can fail | +| V5 | S8 | The switch is exercised at both values and the lab boots at each — cheap, model-free, and the whole of what this issue owes. **Not on the merge bar:** the full two-width comparison, run and written out for [ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) when the epic asks. Record what each run did to the waiting row *then* | **Every held-out fact is read out of the tree at run time**, as both existing labs do: a token that decides a check lives in one convention file and in none of the lab's code, so a different valid tree still passes a correct implementation. @@ -71,8 +71,10 @@ Everything else is yours, the column names included. | The seat-tool fence is not widened, anywhere | It landed stricter than its own spec read, and a board tool in a seat folder is the shape that tempts a loosening. BR-3 is that temptation, as a refusal | | Nothing under `goals/` is imported by anything under `packages/` | D1. A lab that becomes a dependency has stopped being evidence | | Every column is derived on read, and the queue module holds no state | BR-10, and [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). A cached column is a second copy of the board | -| The assignee-to-seat map lives in the host, supplied by the caller, never read from the tree | It is the app's — and a supplied map is the only way VG's negative control can point an assignee at the wrong seat | +| The assignee-to-seat map lives in the host, supplied by the caller, never read from the tree. **The expected association is held out separately, in the tree** — each worker seat's own file names the assignee it answers for | The map is the app's, and a supplied map is the only way VG's negative control can point an assignee at the wrong seat. But the check may not grade the map against itself: repointing it would move the oracle along with the implementation and the control would stay green. The tree is the oracle, the map is what is under test (BR-4) | +| **Every drain passes an assignee `eligibility` predicate into `collection.claim`** — `eligibility: (t) => t.assignee === ""`. Never a bare `claim`, and never a status arm in that predicate | This is the one place a seat-per-drain layout goes wrong, and it goes wrong loudly. `ClaimOptions.eligibility` **narrows the candidate set before the CAS flip** (`packages/orchestration/src/tasks/collection/types.ts`), and both backings compose it with `isClaimable` rather than replacing it. Omit it and the drain claims whatever is next — including a row addressed to another seat — and then `keyedRouter` misses, throws out of the router, and `.rescue()` routes to `recordError`, which writes `collection.fail` against that row (`blocks/worker-step.ts`). The row does not merely mis-route: it settles `errored`. Do not add `t.status === "pending"` to the predicate either — that silently opts this drain out of lapsed-lease recovery, which the substrate calls out by name | | No epic wall is answered in a comment in this folder | [ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). Evidence goes up to the epic PR; decisions come back down | +| **The narrow shape is required while [Q1](DECISIONS.md#q1) is open, not preferred:** worker handlers are stubs doing small deterministic work (write a file the check reads back), the model appears at **one** surface only — the coordinator deciding who gets what — and waiting is driven by pentest-style poll and timeout fixtures rather than sleeps | VG is the epic's exit gate, and a gate that goes red for reasons unrelated to routing stops being one ([D2](DECISIONS.md#d2)). Writing this as a guardrail rather than a recommendation is what stops the gate drifting toward devforce economics (a harness per row, ×4) while the question is still with the owner. If Q1 comes back wide, widen it deliberately and price it then | ## Docs @@ -93,7 +95,9 @@ the host: read the tree through the package's reader hire, register, open the channel the queue: rows, and the seats we hired -> - queued = pending, grouped by assignee + queued = claimable, grouped by assignee + (pending, OR in_progress with a lapsed + lease -- a row whose worker died) running = in progress with a live claim waiting-on-you = parked or blocked, with the row's own reason done = terminal @@ -102,8 +106,12 @@ the queue: rows, and the seats we hired -> the check: coordinator files four rows across three assignees each row runs where its assignee points, and nowhere else - the fourth waits, then runs + the fourth is not re-routed and not dropped, and runs + once its seat frees -- its status while waiting is + recorded, not asserted (BR-6) a row naming nobody refuses at the drain + each drain claims with eligibility narrowed to its own + assignee -- never a bare claim (see Guardrails) ``` **POC: none.** The two premises underneath this — that a channel can hold a ledger a seat drains, and that a seat's declared task tools can be pointed at it — are FIX-1385's, and its plan records reading them in the code rather than running them. A POC here would re-derive a sibling's premise against a surface that does not exist yet. The premise this issue owns is the queue, and a queue POC over an unbuilt board is this lab, early. @@ -115,6 +123,14 @@ the check: coordinator files four rows across three assignees - **Check the four returned session-policy walls** on the epic before wiring the dispatcher. Two are visible at this queue depth: whether a seat already running has its session reused, and what a busy seat does. If either has been ruled, follow it; otherwise show it and report up. - **`goals/devforce-lab/` declares one ledger twice on purpose.** Interim, and not the shape to copy. +## Notes from review + +Round 1. Below the spec-review bar — recorded for the implementer rather than folded into the approach ([BP-040](../../docs/contributing/best-practices.md)). + +- **Contract-gate scope may be trimmed if schedule bites** (Cursor). S6 covers refusals, the enum, the goals-only diff, the channel's BR-8/BR-9 and the column checks — a lot of fence before VG runs. A thinner first cut is BR-1 plus BR-10 via the ledger compare, with the full refusal trees kept only where the pentest lab already proved the pattern (BR-3). **BR-9 as a graded rule is optional hygiene** — it records observed behaviour and grades nothing anyone chose. Implementer's call; the rules stay as written. +- **Column semantics still appear in three places** (Cursor): `the-view.svg`, the BR-10 to BR-12 rows, and this plan's sketch. The duplicate mermaid in `BUSINESS-RULES.md` was cut in round 1. The remaining three have different readers — the figure is the picture, the rules are the contract, the sketch is the shape — so they stay. If the sketch drifts from the rules while you build, the rules win. +- **Two findings were refuted, not folded, and the threads are left open** for anyone who wants to push back: that `SPEC.md` must lead with the problem ahead of its nav and header lines, and that its sign-off section must use the `Need your sign-off` heading with the open question first. Both are measured against `AGENTS.md`, which governs asks **in conversation**; `docs/contributing/spec-template.md` is canonical for a spec document's own headings and prescribes exactly the shape this spec has. `writing-for-humans.md` also exempts structural navigation from "nothing precedes the problem" in as many words. Don't re-file these. + ## Follow-ups - **Whether a channel board should carry a default worker** is FIX-1385's surface, not this lab's. BR-7 shows what happens without one; file the question there. diff --git a/spec/FIX-1430/SPEC.md b/spec/FIX-1430/SPEC.md index 4d14f28ba5..1cb2cbf9e1 100644 --- a/spec/FIX-1430/SPEC.md +++ b/spec/FIX-1430/SPEC.md @@ -70,6 +70,6 @@ One hop. The coordinator names no session, flow or seat instance — only an ass 1. **[D1](DECISIONS.md#d1) · The lab ships no package code — the queue columns stay lab-local.** *If wrong:* a view surface is designed from one example, exported, then redesigned when a second consumer disagrees. 2. **[D2](DECISIONS.md#d2) · The proof is a queue, not a hand-off: more rows than seats, the coordinator assigning through the tools it declared.** *If wrong:* we re-run FIX-1385's own check with an extra seat, call it the exit gate, and prove the half of ER-20 nobody doubted. -3. **[D3](DECISIONS.md#d3) · What a busy seat does is shown, not chosen: the same queue runs twice and the comparison goes to the epic.** *If wrong:* a lab settles a policy the epic owns, in a folder nobody reads as a decision. +3. **[D3](DECISIONS.md#d3) · What a busy seat does is shown, not chosen: the lab is wired to run at either drain width, and the comparison goes to the epic when it asks for it.** *If wrong:* a lab settles a policy the epic owns, in a folder nobody reads as a decision. **Open: one** — how much realism ER-20 closes on ([Q1](DECISIONS.md#q1)). Number 2 is the one to weigh: it is what separates this from a second copy of a check that already exists. Reasoning and what lost: [DECISIONS.md](DECISIONS.md). The cases: [BUSINESS-RULES.md](BUSINESS-RULES.md). diff --git a/spec/FIX-1430/figures/the-view.svg b/spec/FIX-1430/figures/the-view.svg index 120567e062..2f1718fce3 100644 --- a/spec/FIX-1430/figures/the-view.svg +++ b/spec/FIX-1430/figures/the-view.svg @@ -1,5 +1,5 @@