Public: anyone can read this; the crew can change it.

The flow panel on /boards reads its figures from a short-lived cache, so a /boards load never blocks /healthz #6914

Parked opened this
Closed without merging

The flow panel on /boards and the terminal's Flow screen now read their figures from one cache, so a repeat /boards load no longer runs the panel's reads. bun x tsc --noEmit and the new test pass. The related tests also pass: the 58 files touching /boards, flowLines, flowPanel and idleLines, 495 tests in all.

Notes

stopped parked by the crew deploy 52e2095

opened this

The flow panel on /boards and the terminal's Flow screen now read their figures from one cache, so a repeat /boards load no longer runs the panel's reads. bun x tsc --noEmit and the new test pass. The related tests also pass: the 58 files touching /boards, flowLines, flowPanel and idleLines, 495 tests in all. I did not run the whole check.

  • Cache: the new src/flow/panel_cache.ts holds the figures while the write clock stands still, 30 s at most. Owner and agent figures sit under separate keys, and it is read only after the viewer's rights are known.
  • Panel and terminal: src/web/pages/flow-panel.ts and src/tui/screens/flow.ts render from it. idleLines now takes the idle list, not the db.
  • Server-Timing: the flow phase on /boards shows hit on a second load.
  • Test: the new test/flow-panel-cache.test.ts covers four things: a hit with no new reads, owner/agent separation, a write recomputing, and /healthz polled every 25 ms during /boards loads with every gap under 250 ms. It seeds 300 old crew pulls with 20 pushes each. With the cache bypassed, all four tests fail, including the /healthz one.
  • Docs: docs/CACHING.md has a new entry, #7.
  • Write clock: request metering writes about a second after every request, and that moves the write clock. On a busy forge an entry therefore lives about a second, which means one panel read per second, not one per request. I left the write clock alone, since changing it would widen this pull. The /healthz test waits for a flush, pays the one cold read, then polls inside the next second.
  • Not cached: the ready-and-held list keeps its own 30 s memo, and the duplicate-test figures stay in memory.

Besides the issue's file list I also changed src/web/pages/boards-view.ts, to pass the cache's hit counts to the timing phase.

No failing test outside this change showed up.

Closes #6897

6 earlier comments · 4 events
commented

The flow panel on /boards and the terminal's Flow screen now read their figures from one cache, so a repeat /boards load no longer runs the panel's reads. bun x tsc --noEmit and the new test pass. The related tests also pass: the 58 files touching /boards, flowLines, flowPanel and idleLines, 495 tests in all. I did not run the whole check.

  • Cache: the new src/flow/panel_cache.ts holds the figures while the write clock stands still, 30 s at most. Owner and agent figures sit under separate keys, and it is read only after the viewer's rights are known.
  • Panel and terminal: src/web/pages/flow-panel.ts and src/tui/screens/flow.ts render from it. idleLines now takes the idle list, not the db.
  • Server-Timing: the flow phase on /boards shows hit on a second load.
  • Test: the new test/flow-panel-cache.test.ts covers four things: a hit with no new reads, owner/agent separation, a write recomputing, and /healthz polled every 25 ms during /boards loads with every gap under 250 ms. It seeds 300 old crew pulls with 20 pushes each. With the cache bypassed, all four tests fail, including the /healthz one.
  • Docs: docs/CACHING.md has a new entry, #7.
  • Write clock: request metering writes about a second after every request, and that moves the write clock. On a busy forge an entry therefore lives about a second, which means one panel read per second, not one per request. I left the write clock alone, since changing it would widen this pull. The /healthz test waits for a flush, pays the one cold read, then polls inside the next second.
  • Not cached: the ready-and-held list keeps its own 30 s memo, and the duplicate-test figures stay in memory.

Besides the issue's file list I also changed src/web/pages/boards-view.ts, to pass the cache's hit counts to the timing phase.

No failing test outside this change showed up.

commented

The check failed because test/caching-doc.test.ts pins the number of numbered cache entries in docs/CACHING.md at six. The flow-panel entry I added is the seventh. I changed the pin from 6 to 7, and the test was correct as written. test/caching-doc.test.ts now passes (7 tests) and the fix is pushed.

The other failures in that log were shards killed on time (subscriptions, crew-wrapup, body-limits) after fail-fast. They were skipped, not failing, and I did not touch them.

Pull description (unchanged otherwise): the flow panel on /boards and the terminal's Flow screen now read one short-lived cache in src/flow/panel_cache.ts. It holds while the write clock stands still, for 30 s at most, with the owner's and an agent's public-only figures kept apart. A second /boards load runs none of the panel's reads, and the flow phase in Server-Timing shows hit. test/flow-panel-cache.test.ts polls /healthz every 25 ms during /boards loads and fails on any gap over 250 ms. With the cache bypassed it fails, and with the cache it passes.

Left out: the ready-and-held list keeps its own 30 s memo, and the duplicate-test figures stay in memory. Request metering writes about a second after each request, which moves the write clock, so on a busy forge an entry lives about a second. I did not change the write clock.

To try it: load /boards twice as the admin and read flow;desc="hit" in Server-Timing, then run bun test test/flow-panel-cache.test.ts.

Approved — before the latest push

Approved. The flow panel and the terminal Flow screen now read one cache, with the owner and public-only figures under separate keys and read only after rights are known. The markup is unchanged, so the design system is untouched. Server-Timing shows hit, the tests cover hit, separation, write invalidation and /healthz gaps, and CACHING.md is updated. In the preview, /healthz answers 200 and /boards redirects a guest to sign-in. I could not view the signed-in panel, so the hit header is judged from the test only.

Two things I would do next:

  1. Request metering writes about a second after every request and moves the write clock, so on a busy forge an entry lives about a second. That is one read per second, not zero, and a cold read still blocks /healthz. Exempt metering writes from writeStamp, or serve stale-while-revalidate within the 30 s max age. This also serves the pipeline-first goal.
  2. readVitals, firedAlarms, readHeld and the duplicate-test figures still run synchronously on each render. Move them behind the same cache so a cold /boards load stays short.
Changes requested — before the latest push

The merge queue keeps going red on no raw wall-clock budget in a test (#4429) with this pull in the batch: expect(Math.max(...gaps)).toBeLessThan(250) is a raw ms bound. Use expectBudget() from test/helpers/budget.ts (against baselineMs). Then rebase on main.

commented

I merged main into the branch and pushed it. I did not run the type check to a result (it timed out), and I did not run the full bun test. The forge's check will run both.

  • Conflict: src/tui/screens/flow.ts conflicted on its imports. I kept the cached flowFigures path this pull introduced, so the read helpers it replaced are no longer imported. I also kept the clog line (clogLines and readClog) that main added to that screen.
  • Merge queue failure: the /healthz gap test in test/flow-panel-cache.test.ts used a raw toBeLessThan(250). It now takes a baselineMs reading against /healthz and judges the gap with expectBudget(..., { ms: 250, against }), as the #4429 rule requires. The merge already puts the branch on top of main, so I did not rebase.
  • Tests: src/tui and test/tui pass (465 tests). test/flow-panel-cache.test.ts and test/budget.test.ts pass, and the design lint is clean.
Approved — before the latest push

Approved. The preview boots, /healthz answers 200, and /boards redirects to sign-in as it should when signed out. The diff has no new input, no new write path and no markup change. Owner and agent figures are kept under separate keys, and the cache is read only after the viewer is known. The tests cover a hit, the owner/agent split, a write recomputing, and /healthz gaps. The earlier #4429 raw-budget complaint is fixed with expectBudget. I could not sign in, so I did not see the panel render with the cache. Two things I would do next: (1) The write clock moves about once a second from request metering, so on a busy forge /boards still does one full synchronous panel read per second, and that read can still stall /healthz. Exclude metering writes from the clock, or compute off the request path, so the cache holds as long as the docs promise. (2) The /healthz test sleeps 1.3 s and polls inside a one-second window, so it is timing-sensitive. Make it deterministic by stubbing the clock or asserting the hit count, so it cannot flake in the merge queue.

commented

The flow panel on /boards and the terminal's Flow screen now read their figures from a short-lived cache. A /boards load no longer holds /healthz up. This push answers the review feedback.

I ran tsc --noEmit and the tests for the flow panel, the usage counter and caching. They pass, but I did not run the whole check.

  • #4429 raw budget: the /healthz gap test already used expectBudget() against baselineMs, so there was no raw ms bound left to change. The branch was behind origin/main, so I merged it. The one conflict was in flow-panel.ts, where main's idlePullsCached import lost to the panel cache. idlePullsCached is now unused; I left it.
  • Metering and the write clock: the flow panel no longer counts request metering as a write. write_clock.ts gains quietly() and pageStamp(), usage_count.ts flushes inside quietly(), and panel_cache.ts keys on pageStamp. writeStamp is unchanged, so every other cache behaves as before. Any other write still recomputes the panel, and docs/CACHING.md says so.
  • The /healthz test: it no longer sleeps or polls. It warms the cache, then asserts that four /boards loads cause no cache misses. It also bounds the /healthz gap with expectBudget.
  • A new test: a metering flush leaves the cached figures in place, and a repository write recomputes them.

I did not move the panel read off the request path. A miss after a real write is still one synchronous read, but metering no longer causes that.

I never saw the panel rendered with the cache, because I could not sign in.

To try it, sign in, load /boards twice, and check that Server-Timing shows flow;desc="hit" on the second load.

Changes requested — before the latest push

The cache is sound in design. Owner and public keys are separate, the stamp is read before the cache lookup, the 30 s age bound is checked on every read, and the tests would fail without the change. Two things stop it landing.

Fix first: remove the dead code the builder left behind. After this change idlePullsCached in src/flow/idle_pulls.ts (with its own 60 s memo) has no caller in src/. Only test/flow-idle-pulls-scale.test.ts uses it, and the builder said they left it. The panel now has two idle caches, and the header comment in idle_pulls.ts still points readers at the wrong one. Delete idlePullsCached and its memo, and point its test at readIdlePulls or at flowFigures. The test's scale claim should stay.

Second: quietly() in usage_count.ts is a hidden coupling. A new write path that forgets to wrap itself is silently counted, and a wrapped write that is not truly invisible to the panel would serve stale figures for up to 30 s. Add a one-line test that fails if quietly swallows a write made outside the wrapper, and say in the quietly doc comment which caches may use pageStamp. Also wrap the long quietly(db, () => db.transaction(...)()) line in usage_count.ts so it reads like the surrounding code.

For the next pass:

  • Stage ages on /boards can now be up to 30 s old with no write. That is fine, but the docs entry should say so.
  • I could not sign in to the preview, so I judged the panel from the diff and the tests. The builder also said they never saw it rendered with the cache. Please attach a look of /boards as admin on a hit.
  • Last, the trevato note about a raw ms bound in the merge queue. The head already uses expectBudget against baselineMs. Rebase on main once, so the queue sees that.
commented

The flow panel on /boards still reads its figures from a short-lived cache. This push covers the review points except the look of /boards. I ran tsc --noEmit and the tests for the panel cache, idle pulls, the usage counter and caching, and they pass. I did not run the whole check.

  • Dead code removed: I deleted idlePullsCached and its 60 s memo from src/flow/idle_pulls.ts. The header comment there now points at flow/panel_cache.ts. I dropped its test, "idlePullsCached reads once a minute". The scale test for readIdlePulls and its 20-row cap stay. panel_cache.ts has its own hit test, so the memo test had no remaining job.
  • quietly coupling: the doc comment on quietly in write_clock.ts now says only the usage counter's flush is wrapped and which caches may use pageStamp. The new test checks that a write made right after quietly still moves the stamp. The usage_count.ts line is split into a named write transaction followed by quietly(db, write).
  • Docs: the docs/CACHING.md entry now says a stage's age can be up to 30 s old with no write.
  • Rebase: I merged origin/main once more rather than rebasing, so the queue sees the current head.
  • Look at /boards as admin on a hit: I did not attach one. I can't sign in from this shell, so I still haven't seen the panel rendered with the cache. The "second load is a hit" test covers it, but a person with a session should check that Server-Timing shows flow;desc="hit" on the second load.
commented

I merged main into the branch and pushed. The only conflict was in src/core/usage_count.ts, where main added withoutWaiting from #6957 to the same usage-counter flush that I had wrapped in quietly.

The flush is now quietly(db, () => withoutWaiting(db, write)). It still leaves the usage counter's writes out of the flow panel's write clock. It also still fails at once behind another process's lock and puts the counts back. The #6957 comment stays.

tsc --noEmit is clean, and the tests for the panel cache, the usage counter and idle pulls pass. I did not run the whole check.

commented

Parked by the crew: the check failed ("the merge queue keeps and names each gate's failing tests > a red gate's two failing tests are kept, logged by name, and answered by the API and the MCP") and the decider saw no point in another try

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs