Caching: the map and home

What /map and / cache, what each entry is keyed by, which writes make it stale, and how old it may get. Written before any of it is built (#2715). #2716 builds the map half, #2717 the home half, and #2718 does ETag/immutable for static assets, which this doc does not cover. A cache that is not described here is a bug. So is a write that changes a cached answer and is missing from the tables below.

The rules every entry here keeps

  1. Access is never cached. Which repositories a viewer may read

(listReposVisibleTo), whether they may see sealed issues (sealedScope), and whether they are an admin are worked out on every request, before any cache is read. Then that answer goes into the key. A grant, a team change, a suspension or a visibility flip changes the next request's key. There is nothing to invalidate, so no event can arrive too late and no listener can be forgotten.

  1. The key carries what the viewer may see. Two viewers share an entry

only when their access computes to the same scope. One person's sealed report, private repository or spend never reaches another person's page through a shared entry.

  1. Data is cached, not finished HTML. Entries hold ids, numbers,

positions and rows. The page is still rendered for each request, so escaping, the CSP nonce, relative times ("3 min ago") and the viewer's own name are always the current request's.

  1. Validated, not trusted. An entry is used only after its key's

head has been read from the database again: the repository's latest event (MAX(event.seq), from the event_repo_seq index). That works across processes. During a roll, two processes write to one database (#875), and the in-process bus (core/events.ts) cannot wake the other process's listeners. The sequence still moves, so the bus is only a way to evict early, never the thing correctness depends on.

  1. Everything is droppable. Git is the truth and the database is

derived from it (CLAUDE.md, invariant 4). A cache sits one step further from the truth than that. Each cache is a per-process Map with an entry cap, LRU like src/view/cache.ts. A restart, an eviction or a miss costs one rebuild and is never wrong.

  1. A cache does not hide a per-row query. The N+1 reads named under

"Where the time goes" get fixed (grouped helpers, the CLAUDE.md recipe) whether or not a cache is put in front of them. Otherwise a cold miss and the first view after every write stay slow, and test/counts.test.ts stays right to complain.

Today's numbers

bun run bench/map-home.ts seeds a fixture shaped like this forge as the API reported it on 2026-10-19:

5 agent runs in flight. Its graph is 926 issues and 1,699 edges (the real trevato/forge map: 926 / 1,699).

of them are private to the owner.

The bench then times each case 30 times over HTTP, after one warm hit. The SQL counter is bench/run.ts's countStatements, which counts every statement that runs, not every statement that is prepared.

sign in; / shows them the door.

Measured on an 80-thread Xeon Gold 6230 (shared), Bun 1.3.14, with no cache anywhere:

requestp50 msp95 msSQL / requestbytes
GET /map owner810.6854.42684.71046463
GET /map stranger766.1805.32636.71034267
GET /map anonymous0.30.40(303)
GET / owner92.096.61974.3103473
GET / stranger70.675.51784.288149
GET / anonymous1.52.910.014369

The machine is shared, so latency varies from run to run: an earlier run of 20 hits gave /map p50 527 / 491 ms and / p50 98 / 80 ms. The SQL counts were the same in both runs. Treat latency as an order of magnitude and the statement count as the exact figure.

After #2716 (same fixture, same machine, --n 30, warm; / unchanged):

requestp50 msp95 msSQL / request
GET /map owner26.734.525.0
GET /map stranger25.227.633.0

What is left is rendering the ~1 MB of SVG (25 ms), which rule 3 keeps per request.

/:owner/:name/commits names session, repo, log, refs and render the same way (#3392).

/map's Server-Timing names where that goes (#3159): app is the total, then session, lanes (the cache lookups, and the build on a miss, less the layout inside it), layout (graph layout on a miss) and render. Their sum is never more than app; the rest is routing and sending. One bun run bench/map-home.ts run (--n 30, warm, so layout is a cache hit and rounds to 0.0):

GET /map phaseowner p50owner p95stranger p50stranger p95
total (app)27.831.227.229.6
session0.20.30.20.3
lanes1.82.21.71.9
layout0.00.00.00.0
render17.720.117.419.1

Where the time goes

globalLanes spends on all ten lanes** (timed one stage at a time on the same fixture). The big lane's other stages are readyNow at 27 ms, marksFor at 27 ms and repoGraph at 12 ms. Rendering every lane's SVG takes 19 ms. layout is a pure function of the graph's issue ids, numbers and edges (crossing reduction in order), so it is the first thing to cache. Its key is its own input.

SELECT raised_at FROM issue_raise WHERE issue_id = ?1, run once per issue by raisedAt (core/thought_links.ts) inside repoGraph. That is a per-row read, and it gets a grouped IN (…) read. Next come the crew role lookups (42 per request) and SELECT * FROM user (34–40).

takes 77 ms of /'s 111 ms). It runs 840 issue reads (SELECT issue.*, … WHERE …, one per candidate) and 600 SELECT sealed, author_id FROM issue WHERE repo_id = ?1 AND number = ?2 (mayViewId, one per item) on each request. Both get grouped reads. The shelf (/live/apps, 2 ms) and the "On you" card (/live/on-you, 13 ms) are not worth a cache.

The map (/map, /:owner/:name/map, /api/v1/map)

1. The layout: content-addressed

(level, slot, island, routes, levels, width, islandFrom). Titles, states and assignees are never in the entry. They are put back from the request's own graph, so an edited title shows on the next view.

and its edges (blockedById>issueId). A viewer can only produce the key of a graph they were allowed to read, and the entry only says where those same ids sit. Two viewers with the same visible graph share the entry. A viewer who sees one more sealed issue gets a different key, so sharing can never place a card someone may not see.

write that changes the graph (the lane table below) misses the old entry, and the LRU evicts it.

after 1 hour, with a cap of 256 entries.

2. The lane: one repository's map for one scope

Marks, ready list, critical path, word counts, the runs in flight that the scope may see, the workers' usernames, idle, and the autonomy status. The per-repository map page and the API read the same entry.

- head is the repository's MAX(event.seq). One grouped read covers every lane on the page: SELECT repo.id, (SELECT MAX(seq) FROM event WHERE repo_id = repo.id) FROM repo WHERE repo.id IN (…). (A grouped MAX … GROUP BY scans every event of every listed repository, 17 ms on the fixture; the correlated form is one index seek each, 0.3 ms.) - scope comes from sealedScope(db, repo, viewer), worked out fresh: all for a writer or the crew, own:{userId} for any other signed-in active account, none for no one. Every part of a lane that reads issues must respect it, including the reads outside repoGraph (the runs filtered by mayViewId, parkedTwice, proposedWork). #2716's test warms a lane as the owner and reads it as a stranger to show that it does. - utcDay is part of the key because the spend bar and its ceiling reset at UTC midnight.

viewer, worked out on every request), the order of the lanes, and the HTML.

appends an event on the repository and so moves head. The bus listener may also delete lane:{repoId}:* as soon as it sees such an event. That frees memory sooner, but correctness never depends on it.

event on the repository (see "Gaps") and spend reported by another process.

2b. The API map: the finished answer, by the write clock (#3321)

GET /api/v1/repos/:owner/:name/map keeps its whole answer in web/map_snapshot.ts, keyed by repository, the viewer's sealed scope and the UTC minute (the week's merge window slides with time) and valid only under the forge's write clock, so a plan, or any write, drops it before the next read. A hit still names the five phases, flagged as hits. Test: test/map-seed-timing.test.ts.

Home (/)

3. The feed's first page: per viewer

access filter and before ranking. Ranking decays with time (feed/affinity.ts), so it is redone on every request, and so is rendering.

MAX(event.seq), because any event may be a feed item.

table below does not list them one by one: the rule is "any event". When the forge is busy, the hit rate is the rate at which a person reloads faster than events arrive. That is why the grouped reads under "Where the time goes" come first and this cache comes second.

true now, not from events.

4. The KPI row (after #2665): forge-wide, admin only

landings per hour (24 h sparkline), the live version and when it went live, the median check time, crew builders active out of slots, today's spend against the ceiling, and the age of the last good off-box backup. Numbers only, rendered for each request. The visitors tile also carries 30 days of distinct visitors per day (#3186), part of the same entry and so admin-only by the same gate.

the request has established viewer.isAdmin. The figures add up private repositories, so the entry is admin-scoped by its gate, and a viewer who is not an admin never reaches the read. #2717's test says the owner's KPIs never render for another viewer.

forge-wide head.

clock, not with events.

5. Pinned board panels (after #2665): admin only, per panel

same rows /boards shows for it.

an admin's (actions/boards.ts refuses everyone else), and a panel runs with every repository in scope. So, like the KPI row, the entry is read only after the isAdmin check. boardOid is the board file's blob id in the boards repository, so an edited board is a new key.

the table below (a push to the boards repository is one of them).

Where a code page's time goes (#3194)

A repository's tree and blob pages (/:owner/:name/tree/…, /blob/…) name each phase once, after app; the phases never add up to more than app.

or blob, the ref set and the explorer's listing.

Markdown file and a binary or oversized file send none.

README read, which happens while the page is built. On a blob it is the pane plus the page; the ?fragment=1 preview sends the pane alone, and the explorer fragment of a tree sends no render.

Where home's time goes (#3160)

/'s Server-Timing names feed, kpis and panels for a signed-in viewer, and shelf on the anonymous door. A phase is written only for a region the viewer is shown: a non-admin gets feed and no kpis or panels. A phase whose cache answered carries desc="hit" (kpis;dur=0.2;desc="hit"); the hit is read off the cache's counters, so under concurrent requests it can be credited to the neighbour. feed is the whole region, ranking and rendering, with the candidate cache inside it. One bun run bench/home-phases.ts run (owner, --n 30 warm, the snappy fixture; all three caches hit):

GET / phaseowner p50owner p95
total (app)15.319.7
kpis0.20.3
panels0.10.1
feed7.110.0

6. The waiting line: per viewer (#5806)

waitingOn scan over up to 200 repositories); the words are made fresh for each request.

one reads another's count. waiting in Server-Timing carries desc="hit".

assignments, pulls, holds), as the KPI row is.

owner, second look): the miss cost waiting 7.5 ms, the largest read after feed; a hit is under 0.1 ms. Every phase over 20 ms is named in the test's output; none is over 20 ms in the sandbox.

Not cached on home

The anonymous door (1.5 ms, 10 statements), the app shelf, and the "On you" card. Each costs less than its cache's key would.

Pictures: one rule (src/flow/keep.ts)

The home's lanes (src/flow/lanes.ts) and /boards, /flow, a board and a repository's front page (src/flow/pages.ts) draw from a picture: plain data a worker reads on a read-only handle of its own. All of them keep one rule:

behind them.** A page waits for a reading only when there has never been a picture, when a board was changed here since (boardsChanged), or when the person asking wrote something from their own browser after the last one was read (noteOwnWrite: the server notes a signed-in browser's form whose handling moved the write clock; a token's writes are nobody looking at a page). A lane or region that redraws after an event still awaits the reading after the write.

the pictures job, a look every 5 s that starts readings and reads nothing itself): after the write clock moved, at most every 15 s while somebody asked for the picture in the last ten minutes and every 60 s after that; once every 60 s when nothing was written, because windows and ages move with time. A reading never takes more than a twentieth of its worker (a picture that costs c ms is read at most every 20 × c).

lanes, /boards, /flow for each of the people who run the forge, and the front page of the forge's own repository and of the repositories they pinned (4 at most). Any other of these pictures for 8 hours after it was last asked for, the 12 asked for last. A query of the data page is never kept by the keeper.

about; 60 s plus one reading on the first page after a pause, which starts the next reading; never more than twice the keeper's gap (120 s), past which the page waits as if there were no picture, so readings that keep failing cannot pin an old one.

pulls, see the owner's facts or read the statement is established on the request and names the picture (app:{repoId}:{scope}:{ownerFacts}{money}).

A repository's front page used to read its week (shipped, runs, spend, decisions, preview latency), whether it has a past, its milestones and its month on the request, each behind a 5-second memo (app_cache.ts), a 60-second plan cache or the month's minute: 300 ms together on production's copy for every first look after a pause. They are its picture now (readAppPicture). app_cache.ts keeps only what a worker cannot read (the governor's reason) and the home's milestone lines.

Guard: test/pages-budget.test.ts lets a minute pass under the keeper's timer, then lets no reading answer while each of the four pages is asked, and holds that first request under 150 ms (a page that waits for its reading waits out the handler's bound, seconds); test/picture-keep.test.ts proves the rule on both keepers.

Telemetry does not invalidate (#7896)

The write clock counts every row the connection changes, and a signed-in visit itself writes: route timings a second after the request, usage counts, flag reads, the session's last-seen time, the home visit, page vitals, machine and memory samples. Counted, they kept every cache cold for the next visitor. These writers run inside quietly (core/write_clock.ts), which leaves their rows out of the stamp. Wrap only a write to a table no cached page is built from; a page that shows telemetry is bounded by the 30 seconds a cache entry lives. test/write-clock-quiet.test.ts proves it.

The writes that invalidate

Each row is an action (or, for a push, the post-receive hook, the one bus.append outside src/actions/), and the event it appends. The event is what moves the cached entry's head. test/caching-doc.test.ts reads these tables and checks that each named function exists in its file and that the file appends the event named beside it. If an action is renamed, or stops saying what it did, this doc goes red before the cache goes stale.

Lane writes (cache 2; every event here has the repository's id)

writeeventchanges
actions/issues#openIssueissue.openeda card appears
actions/issues#openIssueThroughissue.openeda card appears (a mirror)
actions/issues#editIssueissue.editeda card's title
actions/issues#setIssueStateissue.closeda card goes, a blocker frees
actions/issues#setIssueStateissue.reopeneda card comes back
actions/issues#setIssueStateThroughissue.closedthe same, on a mirror
actions/issues#setIssueSealedissue.sealedwho may see a card
actions/issues#setIssueSealedissue.unsealedwho may see a card
actions/sealed#unsealReleasedissue.unsealedwho may see a card
actions/issues#assignIssueissue.assignedwho is on a card
actions/issues#setIssueLabelsissue.labeledpillars, the Later gate
actions/issues#addCommentissue.commentedparks (struckOut, parkedTwice)
actions/dependencies#linkIssueissue.blockedan edge
actions/dependencies#unlinkIssueissue.unblockedan edge
actions/dependencies#confirmIssueissue.confirmeda held edge
actions/plan#openPlanissue.openedcards and edges at once
actions/pillars#followLinkissue.blockedan umbrella's edge
actions/pillars#inheritPillarissue.labeleda card's pillar
actions/pulls#openPullpull.opened"waiting" (proposedWork)
actions/pulls#mergePullpull.mergeda card closes
actions/holds#holdPullpull.held"on hold" (holdsFor)
actions/holds#releasePullpull.released"on hold"
actions/runs#announceRunrun.queueda ringed card, the lane's crew
actions/runs#announceRunrun.starteda ringed card, the lane's crew
actions/runs#announceRunrun.finisheda ringed card, the lane's crew
actions/crew#addToCrewcrew.addedwho speaks for the crew
actions/crew#removeFromCrewcrew.removedwho speaks for the crew
actions/repos#updateRepoSettingsrepo.settings_updatedautonomy, slots
actions/repos#setCrewOutsidersrepo.crew_outsidersunadopted cards
actions/returns#reportSpendspend.reportedthe spend bar

KPI writes (cache 4)

writeeventchanges
http/server#handleHookpushlandings per hour
actions/pulls#mergePullpull.mergedlandings per hour
actions/runs#announceRunrun.finishedmedian check time, builders
actions/runs#announceRunrun.startedbuilders active
actions/capacity#changeCapacitycapacity.changedbuilders' slots
actions/returns#reportSpendspend.reportedtoday's spend
actions/model_grant#setAccountCeilingsaccount.ceiling_setthe ceiling

Panel writes (cache 5)

writeeventchanges
actions/boards#writeBoardboard.saveda panel's query
actions/boards#changeBoardboard.saveda panel's query
actions/boards#deleteBoardboard.deleteda pinned panel goes
http/server#handleHookpusha board edited in git

Gaps: writes that change a lane without an event on its repository

Closed by #2716, except the clock:

crew/triage now appends issue.raised with the repository's id beside it, so head moves.

already appends limb.moved with the repository's id.

workers' ids, never their names. The names are read on every request in one grouped read.

utcDay in the key covers the spend; the 60 s max age covers the rest.

Budgets

These are what #2716 and #2717 test against, on the forge-sized fixture, warm:

grow with the plan.** Measured warm (#2716): 25 statements for the owner (10 lanes) and 33 for a stranger (8 lanes), against 2,685 and 2,637. About 25 of them are the page around the lanes (session, settings, the repository lists the chrome reads); each lane adds at most two (its head is one grouped read for all of them, and canWrite's owner lookup is one per lane for a viewer who is not an admin). The first draft of this budget, 2 + 2 × lanes, left the page's own chrome out. The test (test/map-cache.test.ts) asserts 26 + 2 × lanes, which does not depend on the machine. Its wall-clock bound is 200 ms p95, the floor test/flake.test.ts allows a request; the 50 ms is read off the bench.

grow with the feed's candidates** (the test/counts.test.ts pattern). The 50 ms is read off the bench, end to end. test/home-cache.test.ts bounds what the KPI and panel caches spend, not the page's wall clock: it first records the statements a miss of both runs that a warm page does not (the KPI reads and the pinned panel's query), then requires that in 30 warm requests every kpis and panels phase is a desc="hit" and runs none of them. A request that a write came near (the route-timing flush, a session's last-seen) misses rightly and is not judged; at least 20 of the 30 must be. Its earlier bound, 200 ms p95 on /, timed the feed (most of the page) and the machine's load, and went red on loaded check machines (#5237). The two phases take about 1.5 ms warm, but under load a hit and a miss both take from under a millisecond to tens of milliseconds, so no time bound can tell them apart.

Max ages, at a glance

entrykey carriesmax age
map layoutthe graph's own ids and edges1 h idle (LRU)
map lanerepository head, sealed scope, UTC day60 s
home feed pageviewer, forge head30 s
home KPI rowforge head, UTC hour; admin-gated30 s
home pinned panelboard blob, panel, forge head; admin-gated30 s
a page's picture (home lanes, /boards, /flow, a board, a repository's front page)the page; for a front page the repository and what its reader may count15 s + one reading while asked for, 60 s + one after a pause; 120 s at most

Raw files at a full commit id (#3381)

GET /:owner/:name/raw/:ref/path and /media/:ref/path tell browsers to keep bytes at a full commit for a year and a shared cache (a CDN, a proxy) for a day: a repository can turn private, and there is no purge. Tree, blob and commit pages use the same rule (http/addressed.ts).

ref isrepositoryCache-Control
40 hex digits (a commit), no cookie or identitypublicpublic, max-age=31536000, s-maxage=86400, immutable
40 hex digits (a commit), any cookie or identitypublicprivate, max-age=31536000, immutable
40 hex digits (a commit)not publicprivate, max-age=31536000, immutable
a branch, tag or anything elseanyprivate, max-age=0 (revalidates)

at a path under it can never change. A branch name moves, so it always revalidates.

rawBlob) allows public. Any other repository is private: the browser may keep it, a shared cache may not.

ETag. If-None-Match naming it (weak or strong, a list, or *) gets a bodiless 304 that keeps the same Cache-Control, nosniff and sandbox CSP. A branch read changes oid only when the file changes, so it costs one round trip and no body.

carries the viewer's name, a CSP nonce and links that change with the repository, so it is not a function of the commit alone. Only the raw bytes are. The origin-browse raw route (browseRaw) is also left alone: its source is another host, whose bytes this forge cannot vouch for.

year-long public copies in whatever shared caches already fetched them; the forge cannot recall them. Anyone who needs that undone must purge those caches. A commit id is also not secret once public.

What is built (#2675)

The map half is #2716's (web/map_cache.ts, numbers above). #2675 adds the grouped reads under both pages and the home half.

Grouped reads (rule 6), which serve a cold miss as well as a warm hit:

It was the 2,348-statement query on /map.

(getIssuesByNumbers + joinMany in feed/items.ts). It was 840 issue reads.

has the window (eventRows in core/sealed.ts). It was 600 reads.

Cache 3, the feed, is viewerCandidates in feed/feed.ts, built with one difference from the design. The key is viewer and chips, the max age is 30 s, and the bound is 200 entries (kernel/stamped.ts). The stamp is not the forge-wide MAX(event.seq) but writeStamp (core/write_clock.ts): SQLite's total_changes() and PRAGMA data_version, read in one statement.

what is true now, not from events (the design says so under cache 3). A clock that moves on every row written catches those writes at once, rather than at the max age. data_version moves when another process commits, as rule 4 asks.

event already does under the design, the hit rate barely changes.

nothing is cached: a rolled-back write leaves total_changes moved.

break bun's changes, which counts a trigger's rows, and every changes === 1 compare-and-swap in the codebase with it.

Measured on bench/snappy.ts's smaller fixture (12 apps of 24 issues), 100 requests, before the map half landed:

requestbefore p50 / p95before SQLafter p50 / p95after SQL
/ owner73.1 / 97.7 ms189219.5 / 29.9 ms135
/ member31.8 / 35.9 ms7439.4 / 11.7 ms113
/ owner, cold73.1 / 97.7 ms189226.5 / 34.7 ms192

The asks' per-pull reads that remained after this (#2772) are grouped by #2780, and home now reads its asks once. The feed cache's key says whether asks are in, because home asks for the feed without them.

test/snappy.test.ts holds both pages' budgets on that fixture, warm and cold (a write before each request). It also checks:

whichever order warmed the cache;

moves it.

Caches 4 and 5, the KPI row and pinned panels (#2717) are web/studio/home_cache.ts, read only after viewer.isAdmin (home calls them for no one else, and test/home-cache.test.ts warms them as the owner and reads home as a member and as a stranger). Like the feed they are stamped with writeStamp, not the forge-wide MAX(event.seq): the KPI figures read run, pull, usage and page_vital rows, some of which append no event, and a clock that moves on every row catches all of them. The KPI entry is keyed by UTC hour, ceiling and data directory; a panel by its board's slug and its own definition (an edited board is a new key, as the blob id would make it). The 60 s rule (#7624): the KPIs, panels and vitals are kept 60 s from when they were computed, whatever is written since (the forge writes every second, so the write stamp never hit). Past 60 s the old answer is still served at once, counted a hit, and one refresh per key runs with setTimeout(0) after the response (#7625). A refresh that throws is logged (home.refresh_failed), keeps the old answer and frees the key for the next request. Only a cold start, or an answer past the 10 min ceiling (HOME_STALE_CEILING_MS, ten TTLs), computes inline, so refreshes that keep failing cannot pin an old answer forever. The refresh is off the request, not off the event loop: it runs on the same thread, so a request that lands while it runs waits for it, as it would have waited for an inline recompute. The waiting line stays on the write stamp, 30 s at most, so the asks count is exact. The builders figure is read fresh on every request (one query), so it agrees with the idle reason beside it; the terminal's dashboard reads readKpis uncached. Tests age these entries with setHomeClock, the one test seam in home_cache.ts. Measured on bench/snappy.ts (--n 50), / owner: 105.7 → 90.1 statements, p50 16.0 → 15.5 ms, p95 22.5 → 20.7 ms; the fixture pins no panel, and a pin adds one query per panel on a miss and none on a hit.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs