stack/agents/darkwing/work/queue-58/BUILD.md

# Row 58 (#1547): bus read, task priority and requirement

Brief: `docs/plans/2026-10-10_design-implementation.md`, section "Bus read:
task priority and requirement" (blob `a360554c`). Owner Darkwing; reviewers
Dewey and Filbert.

The candidate is `build.patch` against the base in `base.txt`, 8 files in
`files.txt`. `candidate-manifest.sha256` holds the sha256 of each file after
the patch.

I built it on `72b16a5b`. Row 57 (#1546) then landed as `f78ba57d` and
changed four of these files: `broker.mjs`, both READMEs and the webui
`bus.test.mjs`. `git apply --3way` put the patch on `ae428a54` with no
conflict. Row 57 adds the decisions reads and this row changes the
`tasks` rows, so the hunks sit in different places; I read the merged
`broker.mjs` and both changes are intact. `build.patch`, the manifest and
the mutants are on `ae428a54`. The gate ran on `f2f2861b`, after row 62
landed; no candidate file changed between the two.

## The problem

The brief says priority isn't in `task_current.fields`. It is:
`taskFields()` in `packages/tasks/src/digest.mjs` puts `priority` in every
live snapshot, `checkTask()` refuses a task without an integer priority, and
the Tasks table already showed it from the fields. What the read model
lacked was a named priority field, and the requirement, which sat only in
the `task.created` body (`packages/tasks/src/verbs.mjs`). The list never
reads that body, since the list has no trail. So for priority this row
lifts an existing value to a top-level key; the requirement is new data in
the list. The brief asks for both fields in the task read model, a
projection rebuild test, and the two columns in the Tasks view.

## What changed

### The bus `tasks` rows

`Broker.#taskRows()` in `packages/bus/src/broker.mjs` builds the rows the
`tasks` verb returns. Each is `task_current`'s row as before, with two keys
added:

- `priority` is the current row's `fields.priority`. It is null for a
  tombstone, whose fields are only `gone` (and `project` on a move), and for
  a read with no priority. Vikunja's 0 stays 0.
- `requirement` is the requirement in the first `task.created` for the same
  Vikunja task id in the business. A move to another project changes the
  project in the ref but not the task id, so the moved task keeps the
  requirement it was created with. It is null for a task the stack didn't
  create.

Both are computed from append-only rows at each read; nothing new is stored.
I chose that over a schema change. `store.mjs` checks the DDL against
`SCHEMA_SHA256` and an open bus against the reference digest, so a new
column or a changed `task_current` view needs a schema version and a
migration of every existing `bus.sqlite`. A read-time projection needs
neither, and a reopened bus gives the same rows by construction.

`taskView()`, the trusted S3 read, is unchanged and still returns
`task_current`'s rows only. Its comment now names `#taskRows` as the verb's
read.

The requirement read is one query per `tasks` call over the business's
`task.created` events. It isn't indexed by kind; a business with many
thousands of created tasks would make each Tasks refresh scan them. That is
fine at slice 1 sizes, and a later row can add an index if a real business
needs one.

### The Tasks view

`packages/webui/src/public/bus.js`:

- `task()` takes `requirement` from the bus row first, then from the trail's
  `task.created`, so the list, which reads no trail, now has it. Priority is
  the row's, then the last snapshot that read the task (a tombstone's page),
  then null. Before, a missing priority became 0 and showed "unset". A
  poller read always has one, so "none" shows only for a row written without
  it, like the browser test's #9.
- The Tasks table gains a Requirement column after Task. Requirement and
  Priority show a muted "none" when the row has none, in the list and on the
  task page.
- `bus.css`: the tasks table's minimum width goes from 900px to 1020px for
  the extra column. The browser test's overflow checks still pass.

For a live row the bus `priority` and the fields' `priority` are the same
value, so preferring the row's changes nothing visible today. I kept it so
the view reads the field the brief puts in the read model; the mutant that
drops it survives for that reason (below).

### Docs

`packages/bus/README.md` describes the two keys under "Shared reads and
adapter boundary". `packages/webui/README.md` adds one bullet on the
columns to the S5 section.

## Scope

The brief owns `packages/bus/`, `packages/tasks/`, the webui Tasks endpoint
and tests. The webui `bus.js`, `bus.css` and README edits are the Tasks view
the brief asks for. Nothing in `packages/tasks/` changed: the poller already
writes `priority` in each snapshot's fields, and `task.create` writes
`requirement` in `task.created`. Field writers are row 61.

## Tests

New `packages/bus/tests/task-read.test.mjs`, 3 tests. The seed has six demo
tasks: created by the stack, changed outside it since, never seen by the
stack, created then gone, created then moved to another project, and a
second `task.created` for the moved task's new ref. A second business reuses
one task id with its own requirement.

1. "tasks rows carry priority and requirement for every session that reads
   tasks": the human, a reader and a role session get the same rows. A later
   poll's priority wins over the stack's write, 0 stays 0, tombstones have
   none, the moved task keeps its first requirement, and the other business
   sees only its own. Each row minus the two keys equals `taskView(...,
   'current')`'s row, and `taskView` has neither key.
2. "the read model rebuilds from the ledger": the rows after a close and
   reopen equal the rows before. Each row's priority equals its current
   snapshot's in `trail`, and its requirement equals the first `task.created`
   for its task id in `events`. A read writes nothing.
3. "an empty business and one with snapshots but no task.created read
   cleanly".

All three fail on the base broker (`out/task-read-on-base.log`).

`packages/webui/tests/bus.test.mjs`: the endpoint test asserts the row's
`priority` and `requirement` reach `/api/bus/tasks` as null, not missing.

`packages/webui/tests/bus-browser.test.mjs`:

- The done task (#9) is now written with no priority.
- The Tasks list check reads each table's header and each row's Requirement
  and Priority cells: #8 `none`/`high`, #7 `REQ-SLICE-1`/`high`, #9
  `none`/`none`. It replaces the `/high/` match.
- #7's page shows `Priorityhigh`. The moved task's page (#10, a tombstone)
  shows `Priorityhigh` from its last snapshot.
- #9's page shows `Requirementnone` and `Prioritynone`. This visit comes
  after the "never read" failure check, which needs #9's trail unread; an
  earlier visit made that check fail.

## Mutants

`out/mutants.sh` edits one source file per mutant, runs the one test file
meant to fail it, and restores the file from the build worktree's index,
which holds the candidate. Output: `out/mutants.txt`, from the run on `ae428a54` at 22:22 UTC on
2026-10-11. 16 of 17 fail, as they did on `72b16a5b`; each webui kill
failed on the intended assertion.

| Mutant | Fails |
|---|---|
| `tasks-verb-unchanged`: the verb returns `task_current` as before | task-read 1, 2, 3 |
| `no-priority`: priority always null | task-read 1, 2 |
| `zero-priority-null`: `\|\| null`, so 0 becomes null | task-read 1, 2 |
| `tombstone-priority-zero`: `?? 0` | task-read 1, 2, 3 |
| `requirement-by-ref`: keyed by the whole ref | task-read 1, 2 |
| `requirement-last-wins`: the last `task.created` wins | task-read 1, 2 |
| `requirement-any-business`: events from every business | task-read 1 |
| `requirement-undefined`: no `?? null` | task-read 1, 2, 3 |
| `task-view-adds-keys`: `taskView` grows the keys too | task-read 1 |
| `endpoint-drops-keys`: the rows lose both keys | webui bus endpoint test |
| `list-requirement-from-trail`: requirement only from the trail | browser |
| `no-requirement-column` | browser |
| `priority-default-zero`: `?? 0` in the view | browser |
| `tombstone-no-fallback`: no snapshot fallback | browser |
| `detail-priority-raw`: the task page prints the raw value | browser |
| `list-priority-raw`: the list prints the raw value | browser |
| `ignore-row-priority`: the view reads only the fields' priority | survives |

`ignore-row-priority` is equivalent today, as said above.

## Gate

`out/gate/gate.sh` ran on 2026-10-11 from 21:57 to 22:02 UTC. Its worktree
was at `f2f2861b` with `build.patch` applied (`out/gate/apply.txt`) and
`node_modules` linked to the main checkout's. It ran each suite in turn and
wrote each log to `out/gate/`. The brief names bus, tasks and webui plus
every `scripts/test-*.sh`.

| Suite | Result |
|---|---|
| packages/bus | 83 pass, 0 fail |
| packages/tasks | 71 pass, 0 fail |
| packages/webui | 40 pass, 0 fail, the browser tests included |
| test-auth | 15 passed |
| test-conductor | 17 passed |
| test-config | 24 passed |
| test-discord | 66 passed |
| test-extension-package | 18 passed |
| test-foundation | 44 passed |
| test-queue | 27 passed |
| test-release | 14 passed |
| test-task | 26 passed |

`test-task` ran with `DOCKER_HOST` set to a missing socket and skipped its
live recall pair. `test-queue` skipped its canonical-root check, since the
gate worktree isn't the queue's root. Sage's gate rerun covers both.
After the gate a `gate_default` Docker network was left with no
containers, and I removed it.

Candidate manifest sha256:
`e63e4c4f756229a9e5bba276c908e272fae0a71ae4f0a1c47e7e47b630bc63e6`.