Files
pipelines/app/notes/R4-attention.md
T

63 lines
4.0 KiB
Markdown

# Attention model (pure domain)
The `Needs you` model exists as reusable, widget-free Dart under
`lib/features/attention/domain/`. The list, identity, wording and local-day
window mirror the browser's `src/attention.js`; no UI, storage plugin,
notification permission or API request is added here.
`attention_transitions.dart` is an attention transition ledger, not a port of
`src/notify.js`: notification permission, tray alerts, `notify_mode` suppression
and success alerts are deliberately outside this slice.
- `attention_models.dart` owns the two kinds (`Decision` rank 0, `Failed` rank 1),
qualification, ordered entries, labels/detail wording, `{runId}:{kind}`
identities, dismissal/snapshot bookkeeping and the JSON string-array
serialisation under this app's own `pipelines.next.attention.v1` (deliberately
not the legacy web key, so neither client rewrites the other's local state).
- Only `waiting` and `failed` statuses qualify, after trimming/lowercasing. A
waiting run with a session audit/export handoff (`export_pending_sequence > 0`)
asks no person and is excluded; a failed run stays failed. `resource_wait` is
deliberately not consulted, matching `web/src/attention.js` and `Attention.kt`
(the server retired the field, and a stale value must not hide a decision).
- The surface is today's work: `attentionEntries` accepts an optional `since`
cutoff and drops an entry when its recency parses and is before it, keeping a
blank or unreadable recency, exactly as the browser does. No cutoff (or an
epoch-zero one) shows everything. Callers pass `startOfLocalDay()` to the bell,
the sheet and the Clear-all snapshot, so yesterday's failures become history.
Stored dismissals themselves still never expire.
- `startOfLocalDay({now})` returns local midnight and takes an injectable `now`
so the UI does not re-derive it and tests stay deterministic.
- Ordering is kind rank, then `finished_at` else `created_at` descending using the
server's timestamp text, then run id descending. The label is the trimmed title
else pipeline name; the detail is `Waiting for your decision`, or the trimmed
diagnostic else `Run failed`.
- Entries retain the whole source summary map, so fields this model does not read
(and unknown future fields) are preserved. `AttentionEntry` is constructed only
by `attentionEntryFor`, so its `runId` is always a validated positive id.
- `attention_transitions.dart` is a pure detector: a seed/first-seen run,
duplicate frame, nonqualifying status, export wait, reconnect reseed or a
snapshot bracketed with `beginSeed`/`endSeed` never emits. It emits once when a
known run enters `failed` or a human `waiting`, forgets the key when the run
leaves that state, and keeps the emitted set across `resetForReconnect`/`reseed`
so a gap cannot replay a transition. A reseed keeps the key of a run that still
qualifies (or that is absent from the read) and prunes one whose run no longer
asks. Dismissed identities are marked seen but suppressed.
Focused tests in `test/features/attention/` cover qualification and exclusions,
ordering and tie-breaks, the local-day cutoff (older/newer, unparseable/blank
recency, no cutoff, decisions, dismissal composition), wording/labels, identity,
dismissal filtering, the clear-all snapshot, defensive copying, malformed/blank
storage, unknown-field preservation, and transition dedupe/first-seen/
nonqualifying/reconnect reseed/emitted-key retention.
Verification: `flutter test test/features/attention` passed all 44 tests;
`flutter analyze` reported no issues. No browser capture applies to this
nonvisual domain slice.
Not done here: no `Needs you` screen/sheet, badge, storage write, store/controller
wiring or notification permission was added, and `PARITY.md` remains `Missing`
until those land. The older `orderAttention` helper in
`lib/features/runs/domain/run_models.dart` was left untouched for lane ownership;
the runs UI must delegate to this model when it is wired, so the two authorities
cannot diverge. Mobile is unverified.