weft
ir 2.6.0 · warp 1.8.0

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.

header2 ms
prices6 ms
feed81 ms
related78 ms
the next generation plans delivery from it feed: buffer feed: stream
A slow region streams; a uniformly fast page buffers, so the 329-byte filler stays off the wire. A slot with fewer than eight renders decides nothing.
✓ Valid A recording changing delivery

A slow region streams; a uniformly fast page buffers, so the 329-byte filler stays off the wire.

✕ Refused a profile moving placement or a key
what you wrote→a recording has no standing over inferred effects→not offered

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

sketch — not compiled
weft dev --profile      # or profile: true in weft.config.ts
# .weft/profile.json is written every 30s, and again on the way out

What 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:

sketch — not compiled
{
  "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.

RecordedWhy that and not a total
Samples, per slotBelow MIN_SAMPLES nothing is decided. A decision from four requests is a coin toss with a log line.
p50 and p95, renders onlyThe tail is what decides whether a region should arrive separately; the median hides it.
Hits, counted apartA region that is nearly always a cache hit does not need to stream, however slow the miss is.
Age of the recordingA 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 changeA profile may never change
Whether a slot streamsWhich fragment fills a hole
The priority it streams atWhat a fragment reads, or its cache class
Whether the page is in-order or out-of-orderA key, a TTL, or a Vary header
Which routes are worth prefetchingWhether a page is static

Read what it decided

sketch — not compiled
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 from

weft 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.