Skip to content

feat: acknowledge any attention item, and browse catalog folders as a tree - #1589

Merged
kvlonge merged 20 commits into
mainfrom
feat/overview-attention
Nov 19, 2026
Merged

kvlonge merged 20 commits into
mainfrom
feat/overview-attention

Conversation

@kvlonge

@kvlonge kvlonge commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Why

The Overview lists attention items (failed runs, failing checks, stale sources, server problems) but people could only acknowledge failed runs, so an ongoing condition someone was already handling stayed on everyone's Overview. The catalog's folders were also a flat list, and a project with many folders crowded the Overview.

Changes

  • Acknowledge any attention item. Ongoing conditions are recorded as audit events; an acknowledgement lapses after [server] attention_snooze (default "24h"), when the condition gets worse, and is withdrawn automatically once the condition has cleared.
  • The catalog shows folders as an expandable tree, and the Overview's folder card shows at most eight.
  • Store migration 0003 adds the audit-log index the acknowledgement listing reads.
  • Browser work budgets for the Overview and the folder view on a 10,000-node project.
  • Merged with main: the only conflict was in the UI HTTP client, where both sides are kept.

Release note: on PostgreSQL with a large audit log, migration 0003 holds up audit writes, including sign-ins, while it builds its index. Pre-build it before upgrading with CREATE INDEX CONCURRENTLY IF NOT EXISTS sqb_security_audit_attention ... as the server docs show; the migration then skips it.

Verification

  • make check-ci on the merge head.
  • UI: vitest run src/lib (581 passed), svelte-check with no errors, and the Playwright layout project (122 passed).
  • cargo check -p sqlbuild-orchestration --all-targets after the merge.
  • One read-only review of the merge's conflict resolutions and the files both sides changed found no problems.

The Overview's attention list could only acknowledge runs, so a known
condition that couldn't be fixed today, such as a late source, an overdue
schedule or nodes out of date, stayed at the top for everyone.

- POST /api/control/locations/{location}/targets/{target}/attention-acknowledgements
  marks a condition handled as it looks now: a key (its kind and subject)
  and a shape (counts, members, error codes; never message text, which can
  hold relative times), or withdraws the mark. GET lists each condition's
  latest acknowledgement from the last two days, with who, when and until
  when.
- An acknowledgement holds for 24 hours. Acknowledging the same shape again
  while it holds changes nothing; a new shape, or a lapsed acknowledgement,
  is recorded again. Comparing a later state with the shape is left to the
  client, which knows what makes each condition worse.
- Same permission and retries as acknowledging a run: anyone who can see
  the target's runs, and an event ID applies once. Each change is an
  `attention.acknowledged` or `attention.acknowledgement_withdrawn`
  audit event, so there is no new table, and it signals the target's runs
  topic, so open Overviews reload.
…hey change

- Every item on the Overview's attention list has an "Ack" button: short
  muted text with a bell, always visible, stronger while its row is
  hovered. Its accessible name is "Acknowledge" and its tooltip says what
  it does.
- A run is acknowledged for good, as before. An ongoing condition (nodes
  out of date, late sources, a location or schedule event, a blocked
  queue, a low calendar) is acknowledged as it looks now, through the new
  attention-acknowledgements endpoint, and comes back on the list, saying
  why, when it gets worse:
  - more nodes changed or behind;
  - a new late source, or one passing its error threshold;
  - a higher severity;
  - a blocked run waiting on something new;
  - it resolved and came back, as a new event;
  - its 24 hours end.
  Shapes hold kinds, subjects, severities and counts, never message text,
  which holds relative times. Large ones stay small: nodes out of date
  compare by counts, and more than 50 late sources by counts.
- "Acknowledged (N)" lists both kinds with who and when, "for good" or
  "hidden until it changes", and Undo.
- An acknowledged location outage no longer takes its overdue schedules
  along: they stand on their own.
It was declared an empty object, which the TypeScript client generated as
an object that may hold no properties.
…ard shows at most eight

- The catalog gains "By folder" beside Nodes (kept in `?view=folders`):
  every folder with Current, Changed, Behind and Failed, its subfolders'
  nodes included, as a tree.
  - Each folder opens in place, onto its subfolders and then its own
    nodes (stale and failed first, the first 20, then "N more in <folder>
    →"). Expand all and Collapse all.
  - Sorting by any column applies within each level. "Needs attention
    only" leaves out fully current folders and nodes.
  - A folder's name, or one of its counts, opens those nodes (of that
    status) in the list. The catalog now reads `?status=` for such links.
  - Clicking anywhere else on a folder's label (its chevron, icon,
    "N subfolders" or empty space) opens or closes it. A click on a link,
    or one that selects text, never does. The chevron stays a button with
    aria-expanded, so the keyboard works it.
  - Full width, like the node list: the name takes the spare room, the bar
    a fixed 160 px before fixed count columns, so all four counts show
    from 1280 px up. The shared DataTable draws only the rows in view.
- The Overview's Build status card shows at most eight folders, most
  urgent first, and links to "All N folders (M need attention) →".
  Before, every folder needing attention also showed, so on a project
  where most need attention the cap did nothing.
- The large mock project answers `path:` selections from its own nodes.
…roject

- `?mock&huge`: about 10,000 nodes in 40 top-level folders, each with
  nested subfolders and most needing attention, for the Overview's
  folder card and attention list and the catalog's folder view.
- A performance test, with the CPU slowed 6×, times:
  - opening the folder view from the Overview's link (2 s list budget);
  - Expand all and opening one folder (rows on screen within 1 s);
  - going back to the Overview (2 s);
  - acknowledging an item (1 s).
  It also reports scrolling the fully opened tree beside the node list of
  the same project. PERF.md sets no budget for scrolling a list, and the
  tree's rows are lighter than the list's.
- Acknowledging or undoing moves the item at once, once saved, instead
  of after the Overview has been read again, which takes a while on a
  large project.
`crypto.randomUUID` and `navigator.clipboard` exist only in secure
contexts (HTTPS or localhost). Served over plain HTTP behind a proxy,
every action that makes an ID failed with "crypto.randomUUID is not a
function": starting, cancelling and rerunning runs, acknowledging, and
changing triggers. Copy buttons either threw or said "Copied" without
copying.

- `newRequestId()` uses `crypto.randomUUID` where it exists, and
  otherwise builds an RFC 4122 version 4 UUID from
  `crypto.getRandomValues`, which every context has.
- `copyText()` uses the Clipboard API where it exists and works, and
  otherwise copies from a hidden textarea. Copy buttons say "Copied"
  only when the text was copied.
- A unit check keeps `crypto.randomUUID` and `navigator.clipboard` out
  of everything but these two helpers.
- Tests: the fallback's format, version and variant bits, and
  uniqueness; in a browser with both APIs removed before the app loads,
  a plan (which makes a request ID) opens, and Copy as sqb build copies.

Cherry-picked from fe4a0bb; here it also covers acknowledging an
attention condition.
…nd help copy a secret by hand

- The fallback copy puts back the person's own selection and focus,
  without scrolling, after copying from its hidden textarea.
- When a one-time secret can't be copied, it is selected, with a hint to
  copy it with Ctrl+C (⌘C on a Mac).
…d select folders exactly

Review fixes for acknowledging attention items and the folder tree.

- Problems the server reports have fixed event IDs (a stopped scheduler,
  each broken location, a location's late schedules or low calendars),
  so comparing IDs never brought an acknowledged one back before its
  24 hours were up. Now:
  - late schedules and low calendars list their schedules' trigger IDs,
    so another one late or running low counts as worse;
  - a stopped scheduler is told apart by the lease that ran out, and a
    broken location by its last check-in, so a later outage comes back.
- Keys stay within the server's 256 characters (a long one is cut, with
  a hash of the whole), and shapes within its 8 KiB: members that
  don't fit are left out, comparing by counts.
- A folder's `path:` link selected more than its counts showed when a
  source, or another folder's node, sat in it. It now uses `path:` only
  when that selects exactly what is counted, and names the nodes
  otherwise, with the rule shared with the Overview card.
- Folders outside models/ and python/, such as seeds, are selected by
  name: a path selector rejects any other root.
- Acknowledging no longer clears its immediate move before the Overview
  has been read again, so the item doesn't flash back.
- The Ack tooltip says it hides the item for everyone viewing this
  target.
… projection

Both read a target's acknowledgement events from the audit log and keep
each subject's latest; they now share that, and differ only in their
actions, subject field and window.
…cknowledgements

- Constants hold only constants, internal structs live in models.rs, and
  entry modules hold only their operation.
- Reading what is already stored for a condition (a retried request or
  its latest event) is a helper of its own, with explicit errors.
- One-line doc summaries; the server test runs its cases through
  test_cases with expected_ values.
… conditions that cleared

- `[server] attention_snooze` sets how long an acknowledged condition
  stays hidden while it doesn't change: a duration such as "24h" (the
  default), "90m" or "1d12h", or "0" for no time limit, so it stays
  hidden until it gets worse or clears. Years and months are refused,
  and an invalid value stops the server, naming the key.
- The condition listing follows it: acknowledgements from the last two
  snoozes, or every one the audit log keeps without a time limit. It
  now returns the snooze with them, and `until` is absent without a
  limit. The Overview's tooltip and "hidden until" use it.
- When the Overview finds that an acknowledged condition has cleared,
  it withdraws the acknowledgement, so the condition shows as new if it
  comes back, even smaller.
  - Only conditions the read sees in full are judged. Late sources,
    which it doesn't check, never are, and nodes out of date only with
    build state known.
  - Nothing is withdrawn after a failed read. Nodes out of date wait
    while node state syncs or after a failed sync.
  - Every viewer sends the same event ID, derived from the
    acknowledgement, so the server records the withdrawal once. The
    audit log gives its reason, "automatic: the condition cleared".
  - Runs are acknowledged for good and never withdrawn.
- Documented under "Acknowledge attention items" in the server
  reference.
…shows, and only that one

Review fixes for withdrawing acknowledgements of conditions that cleared.

- A viewer sees a broken location, late schedules and low calendars
  only for targets they may view, so their absence proved nothing about
  other targets. Now only this target's problems, and the scheduler,
  which every viewer sees, are judged.
- Each Overview read is noted with the target it was read for, and
  whether node state had settled (no sync running, the last one
  succeeded) when it began. Only the page's own latest read is judged,
  while it is shown and for the selected target.
  - The previous target's data, still shown after a switch, is never
    judged; nor is remembered data from an earlier visit.
  - Neither is a read taken during a sync, even once the sync has
    finished.
  - The read also waits until the shared node listing is the selected
    target's.
- An automatic withdrawal names the acknowledgement it withdraws, and
  the server applies it only while that is still the latest, so a late
  withdrawal can't remove a newer acknowledgement. Its event ID is
  derived from that acknowledgement. Undo is unchanged.
- An index serves the condition listing and the latest-event lookup by
  location, target and key. It is created on open, outside the schema
  checksum, so a listing without a time limit no longer scans the audit
  log.
- `attention_snooze` is at most 365 days.
- Long keys are cut between characters, never inside a surrogate pair.
- The Overview card's folder links leave out sources, as its counts and
  the folder tree do.
…e state is known

- The page holds the Overview in reactive state, which wraps it in a
  proxy, so comparing the shown data with the read by identity never
  matched and nothing was withdrawn. Each read now carries an ID of its
  own, which the shown data keeps.
- The first read on opening the page begins before the sync status
  arrives, so it could not judge nodes out of date. Once the status
  says node state has settled, that read is taken again once.
…t a faked server

The page's wiring had only unit tests, which compared reads by identity
and so missed that the page holds its data in a proxy. These browser
tests run the real page and server client against a control server
faked inside the test through Playwright's routing. Nothing in the app
changes, so there is no hook to reach in a production build.

- A cleared condition is withdrawn once, naming its acknowledgement;
  when it recurs, smaller, it shows as new.
- A first read made before the sync status arrives is taken again once
  it does.
- A read taken during a sync withdraws nothing; a read after the sync
  settles does.
- A failed read withdraws nothing, even after a withdrawal that failed.
- Switching target while a withdrawal is held back sends nothing to the
  new target.
- A slow read that saw a condition clear withdraws nothing once a newer
  read shows it back.

Removing each guard fails its test: the read-ID comparison, the scope,
the failed-read check, the sync state captured at read time, and the
read again once sync is known. Going back to comparing reads by identity
fails four of them.
… auto-withdraw tests bite

- The condition listing looks up the actor's name with a scalar subquery
  instead of a join, so the audit log is read through its attention
  index whatever the planner makes of the join. A test runs EXPLAIN on
  the server's own connection, on the bundled SQLite and on PostgreSQL,
  and fails if the listing reads the audit log another way.
- The server docs say that building a new index on PostgreSQL at
  start-up holds up writes to a large audit log, such as sign-ins, and
  how to build it beforehand with CREATE INDEX CONCURRENTLY. They also
  say that nodes out of date are withdrawn automatically only once the
  target's warehouse sync has reported.
- Browser tests:
  - The faked server answers a read as things stood when it arrived,
    however long the reply takes, so the overtaken slow read really
    saw the condition cleared.
  - The sync test has the read after the sync show the condition back,
    slowly: in that gap the read taken during the sync must not be
    judged.
  - The target-switch test checks the switch happened.
  - Waits follow the faked server's reads, not fixed sleeps.
… migration 0003

Main's numbered migrations pin each schema version's checksum, which covers
indexes.sql, so the audit-log index the acknowledgement listing reads needs
its own migration. 0003 only creates sqb_security_audit_attention, with
IF NOT EXISTS so an index an operator pre-built CONCURRENTLY on PostgreSQL is
skipped. Version 3's SQLite and PostgreSQL checksums are pinned, and the
upgrade tests now expect the latest version.

The server docs say how to pre-build the index before upgrading, since on a
large audit log the migration holds up audit writes, including sign-ins.

Coordination: the observed-runs server half adds its own migration
(sqb_warehouse_runs) later; whichever lands first takes 0003, and the other
renumbers to 0004 and pins its checksums again.
…rk budgets

The 10K wall-time checks for Ack and going back to the Overview sat at their
budgets and failed under ordinary load. Following #1569, the required budgets
project now counts layouts, style recalculations, DOM changes, nodes, rows
drawn and mock reads for each interaction the timing test covers: opening the
folder view, expand all, opening one folder, scrolling the opened tree, going
back to the Overview and acknowledging nodes out of date. The wall-time test
stays as it was, in the non-required UI timings job, which reports it.

Acknowledging holds back the Overview's read that follows (the mock client's
reply timer) and requires the item to have left the list already, so the
settling that moves it at once is checked without timing it.

Budgets come from 10 runs each at 1x and 6x CPU, with #1569's headroom. Both
regressions tried are caught: with the folder tree's windowing off, expand all
draws 4,480 rows against 28; with settling off, the item stays listed while the
read is held, and styles go over budget.
@kvlonge
kvlonge enabled auto-merge November 18, 2026 23:23
@kvlonge
kvlonge added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit 9c0e0e5 Nov 19, 2026
35 checks passed
@kvlonge
kvlonge deleted the feat/overview-attention branch November 19, 2026 00:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant