weft
ir 2.6.0 · warp 1.8.0

What a fragment reads decides everything

The cache key, the class and the Vary header are derived from the reads the compiler saw. None of them can be declared.

const u = ctx.identity() // a read, inferred
taint: identity
→
class: private
→
key: identity + route:page
The key is what the compiler saw the fragment read. There is no setter in the kernel, the plan DSL or the plugin surface, and that absence is the enforcement.
✓ Valid A class derived from the reads

Read nothing and the page is a file. Read the locale and it is one shared entry per value. Read identity and it is private — all three decided for you.

✕ Refused .cache(’public’) on a fragment that read identity
what you wrote→the declaration disagrees with the inferred effects→build failure

The failure names identity, so you know which read contradicted you.

In plain terms

You never write a cache key. The compiler notes every read a fragment makes — the user, a cookie, the locale, a query parameter — and that set of reads is the key. Read nothing and your page is a file; read identity and it is private to one person.

Nothing about cacheability is declared here. The compiler records what each fragment read, and the cache key, the class and the Vary header are all derived from that set. A cache class that can be asserted can be asserted wrongly, and the failure is one reader’s bytes in another reader’s cache.

A read becomes a key component

examples/greeting

One ctx.cookie call. The facts below show cookie:currency in the read set, which is where the cache key and Vary come from.

output

Prices shown in .

app/fragments/examples/greeting.tsx
import { fragment, type Ctx } from '@weftjs/core'

/**
 * A fragment that reads the request, and therefore keys on it.
 *
 * `ctx.cookie('currency')` taints `cookie:currency`, so this fragment's cache entry is per currency
 * and the response says `Vary: Cookie`. Nothing declares that. Every read here is a call the
 * compiler can name statically, which is why a read it cannot name is a build error rather than a
 * cache key with a hole in it.
 */
export default fragment(async (ctx: Ctx) => {
  const currency = ctx.cookie('currency') ?? 'USD'
  return <p class="greeting">Prices shown in {currency}.</p>
})
What the compiler knows
Holes1
Escape elided0
Effect setcookie:currency
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
currencytextescape

What the client wires on adoption

No wiring: nothing on this template changes after it is painted, so the client attaches nothing to it.

Sealed templates
1
Version
45122ec2139bdfe756602f978ec0fcea

A read the compiler cannot name statically is E_UNTRACKED_EFFECT — a build error rather than a key with a hole in it.

The classes, and what forces them

ReadsClassWhat follows
nothingstaticThe key is the content address. It can be resolved at build time and served as a file.
a cookie, a header, a locale, a flagsharedKeyed by value, and the response says Vary so a CDN cannot serve it to everyone.
identityprivateNever shared, never a CDN entry.
timeforces a TTLA policy with no TTL would never expire, so declaring one is a build error.

Identity contains itself

examples/private

One ctx.user() read makes this region private. Because it is a slot rather than part of the document, the document stays shared.

output

Signed in as

app/fragments/examples/private.tsx
import { fragment, type Ctx } from '@weftjs/core'

/**
 * One identity read, and the region can never be a shared cache entry.
 *
 * Because it is a *slot* rather than part of the document, the document stays shared and only this
 * region is per-user. That containment is the whole reason a page with a signed-in corner is not a
 * page that has to be private.
 */
export default fragment(async (ctx: Ctx) => {
  const user = await ctx.user()
  return <p class="private">Signed in as {user}</p>
})
What the compiler knows
Holes1
Escape elided0
Effect setidentity
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
usertextescape

What the client wires on adoption

No wiring: nothing on this template changes after it is painted, so the client attaches nothing to it.

Sealed templates
1
Version
6eec7f5c8738807d4f75fa53191d73b1

The plan is checked against the compiler, never the reverse

A route may declare a cache policy. It cannot declare one that contradicts what its fragments read: .cache('public') on a fragment that reads identity fails the build, naming identity as the read that caused it. That is the strongest promise in the design and it is a build error rather than a runtime check.

sketch — not compiled
export default defineRoute({
  // Refused: the fragment filling this slot reads identity.
  cache: { class: 'public', ttl: '1h' },
  slots: { body: { fragment: 'cart' } },
})