A plan generated from measurement
The file tree cannot say what anything costs, and delivery is a decision about cost. So record it, and let the recording decide.
A slow region streams; a uniformly fast page buffers, so the 329-byte filler stays off the wire.
And a slot with fewer than eight renders decides nothing at all.
In plain terms
Run the dev server with --profile and it records what each render actually cost. The next build uses that recording to decide what streams and what buffers. It never touches placement, cache classes or keys — a recording of last Tuesday has no standing over what the compiler inferred.
The convention generates a plan from the file tree. What the file tree cannot say is what any of it costs — and delivery is a decision about cost. Whether a region should arrive separately depends on how long it takes, on this deployment, with this data.
An author asked to guess that guesses stream: true on everything, which buys the out-of-order filler for a page whose regions all arrive together. So: record what happened, and let the recording decide the part of the plan that is about time.
Record it
weft dev --profile # or profile: true in weft.config.ts
# .weft/profile.json is written every 30s, and again on the way outWhat is recorded is per route and per slot, and renders are kept separately from cache hits — a p95 that averaged a 2 ms hit with a 300 ms render describes neither.
This is the file, with the fields a recording actually writes:
{
"version": "2",
"recordedAt": 1756000000000,
"forMs": 1800000,
"routes": {
"/": {
"requests": 4812,
"slots": {
"panel": {
"renders": 12,
"p50": 0.4,
"p95": 0.9,
"bytes": 318,
"hits": 4800
},
"body": {
"renders": 4812,
"p50": 6.1,
"p95": 11.4,
"bytes": 7344,
"hits": 0
}
},
"from": {},
"described": 3950,
"followed": 2411
},
"/app/cart": {
"requests": 1204,
"slots": {
"panel": {
"renders": 9,
"p50": 0.3,
"p95": 0.7,
"bytes": 318,
"hits": 1195
},
"body": {
"renders": 1204,
"p50": 48.2,
"p95": 96.7,
"bytes": 1582,
"hits": 0
},
"readout": {
"renders": 1204,
"p50": 1.8,
"p95": 3.2,
"bytes": 96,
"hits": 0
}
},
"from": {
"/": 812,
"/app/feed": 331
},
"described": 0,
"followed": 0
},
"/app/feed": {
"requests": 906,
"slots": {
"panel": {
"renders": 7,
"p50": 0.3,
"p95": 0.6,
"bytes": 318,
"hits": 899
},
"body": {
"renders": 41,
"p50": 62.5,
"p95": 121,
"bytes": 6289,
"hits": 865
}
},
"from": {
"/": 574
},
"described": 1120,
"followed": 88
}
}
}Three things in it are worth reading twice. /app/feed is slow and almost always a cache hit, which is the case a single total would have got wrong. /app/cart has the one slot past both SLOW_MS and MIN_STREAM_BYTES, so it is the one a recording would decide to stream. And described against followed on / is the pair that says whether describing a route to a client that had not been there ever paid for its bytes.
| Recorded | Why that and not a total |
|---|---|
| Samples, per slot | Below MIN_SAMPLES nothing is decided. A decision from four requests is a coin toss with a log line. |
| p50 and p95, renders only | The tail is what decides whether a region should arrive separately; the median hides it. |
| Hits, counted apart | A region that is nearly always a cache hit does not need to stream, however slow the miss is. |
| Age of the recording | A profile from last month is reported as old rather than used quietly. |
What it is allowed to decide
Delivery, and nothing else. Placement, cache classes, keys and effect sets are the compiler’s, and a recording of last Tuesday has no standing over what the compiler proved. This is the boundary that keeps a profile from becoming a second source of truth about correctness.
| A profile may change | A profile may never change |
|---|---|
| Whether a slot streams | Which fragment fills a hole |
| The priority it streams at | What a fragment reads, or its cache class |
| Whether the page is in-order or out-of-order | A key, a TTL, or a Vary header |
| Which routes are worth prefetching | Whether a page is static |
Read what it decided
weft profile # what the recording decided, and what it refuses to decide
weft why /cart # the plan for one route, and where each fact came fromweft profile prints the refusals as prominently as the decisions, which is the property worth having: "not enough samples for recs" is the useful output, and a tool that quietly decided anyway would be a tool you could not run twice.