0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00

feat(factory): count the new session page's starters and activity on the server (#30097)

**─────── TLDR ───────**
> The new session page now gets its starter counts and activity dates
from two small server reads instead of downloading every card of the
project.

To show a handful of numbers, the page read the whole board: 1,505 KB
gzipped on the 8,078-card board measured in #28915. The rules that
decide which cards a starter counts now run on the server, and the
browser keeps the wording and the layout.

Since #30099 a tab that already holds the board only reads the cards
that moved. What this PR removes is the first download, and the board
the tab had to keep to count on it.

Fifth step of removing whole-board reads, after #30080, #30083, #30087
and #30081 (⌘K). The board page comes next.

### Behavior changed

opening a new session page
  ├─ **was** — every card of the project downloaded, then
counted in the browser
  └─ **now** — two reads: the starter counts, and the instants
of the period

a card changes while the page is open
  ├─ **was** — the cards that moved, merged into the board the
tab kept
  └─ **now** — the two reads asked again; the instants come
back only when one was added or removed, a `304` otherwise

choosing "This month" in the activity band
  ├─ **was** — recounted at once on the board the tab kept
  └─ **now** — one more read; the band stays up on the week's
instants until it answers

the live session counts in the activity band
  ├─ **was** — read off the whole board
  └─ **now** — read off the sidebar's cards holding a session,
already loaded

a pull request card whose source reports no state
  ├─ **was** — finished only in a phase named `done` or
`canceled`
  └─ **now** — finished in any terminal phase of the default
board

the page served by a Factory server without the two routes
  └─ **new** — starters and activity band stay hidden, the
rest of the page works; feed frames do not ask the two routes again

### Shape changed

| | | |
|---|---|---|
| **+** | `routes/work-item-starters.ts` | the starter rules, moved here
from the browser; they read the cards as storage holds them |
| **+** | `routes/work-item-activity.ts` | the instants one period needs
|
| **+** | `hashedBody()` in `routes/board-snapshot.ts` | a computed
answer and the `ETag` naming it |
| **~** | `starterPrompts.ts` | words the counts, no longer reads cards
|
| **+** | `queryKeys.boardFacts(id)` | answers computed from the board,
refreshed with it |
| **+** | `activityDepth(period)` | one home for "Today reads the week's
answer" |
| **−** | draft page in `pageLoadsBoard` | it no longer reads the board
|
| **−** | `doneAt` in `boardItems.ts` | its only caller moved to the
server |

what callers can now ask
    `GET …/work-items/starters` · `GET
…/work-items/activity?since=<instant>` (answers `304` to
`If-None-Match`) · `mastra api factory work-item starters` · `mastra api
factory work-item activity`

### Decisions

- **counted on the server, not from a smaller card list** — the page
needs eight numbers, not cards; a new starter now takes a server rule
plus its wording
- **instants, not buckets** — the browser buckets in the viewer's time
zone and Today reuses the week's answer; bucket on the server if the
list ever weighs
- **no whole-board fallback on an older server** — the two blocks hide
until the server is deployed; one `catch` away if you disagree
- **counted on stored cards, not on their wire copy** — copying every
card per request was three quarters of the read's time; the rules merge
the work item's facts with the card's where they read them
- **recounted on every request, no memo per board** — a memo would have
to expire with the clock (stale pull requests), the board registry and
the decisions; the count costs 1 to 5 ms
- **`ETag` on the instants, none on the counts** — the counts weigh
about 150 bytes; the page asks the instants from the top of the hour so
the address repeats and the browser can revalidate
- **the other depth stands in while a period loads** — two observers,
one enabled; a placeholder would set the band's clock to zero

### Gain

Opening the page on 2,500 cards with ~2 KB descriptions: the whole
board, 1.2 MB gzipped, becomes about 150 bytes of counts plus 27 bytes
per card created or completed in the period. That is 1.9 KB when the
cards were filed over 400 days, 67.9 KB when all 2,500 fall in the week
(sent uncompressed: instants gzip about 3.5×).

Once the page is open, this branch does not beat `main`, it costs a
little more. One refresh of one open tab, at most every 5 s:

| one refresh of an open tab | 2,500 cards | 10,000 cards |
|---|---|---|
| `main`, nothing changed | 0.5 ms · 124 B | 1.4 ms · 122 B |
| here, nothing changed | 2.4 ms · 154 B | 7.7 ms · 156 B |
| `main`, one card filed | 860 B | 868 B |
| here, one card filed | 2,030 B | 5,921 B |

"here" adds up the three reads the page makes: cards holding a session
(`304`), starters, instants. Cards filed over 400 days, medians of 10
rounds in the in-memory route harness. When every card falls in the week
the two counts take 0.98 + 1.15 ms at 2,500 cards and 4.27 + 4.60 ms at
10,000. Counting on stored cards took the starters function from 1.11 to
0.29 ms at 2,500 cards and from 4.61 to 1.15 ms at 10,000.

### Watch

> [!WARNING]
> The starter rules moved from the browser to the server together with
their scenario tests. <mark>A porting mistake would show as a wrong
number on a starter button</mark> and nowhere else, so compare a few
buttons with the board after deploy.

on merge: nothing to do. `main` with #30153 is merged into this branch
and the CLI route metadata check passes.

### Not verified

- [ ] against a real board or Postgres — the timings come from the
in-memory route harness
- [ ] the `304` in the signed-in app — the route is tested, and headless
Chromium revalidated a stand-in answer with the same headers, but the
real page was not watched against a real server

---

> ████████████████████ **tests** `+1077 −431` — 58% of the additions
> ███████████ **source** `+572 −222`
> ███ **generated** `+177`
> █ **changeset** `+24`
> █ **docs** `+2`

---------

Co-authored-by: Damien Schneider <damienschneider@damiens-MacBook-Pro.local>
This commit is contained in:
Damien Schneider 2026-11-11 21:49:28 -08:00 • committed by GitHub
commit 1fbc69aa9a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
38 changed files with 1852 additions and 653 deletions