weft
ir 2.6.0 · warp 1.8.0

Intents: the only thing that writes

A render cannot write. Mutations are intents, addressed by an opaque id, with their writes declared.

a form postsno JavaScript anywhere on thepageINTENT · 0x05the same intent, over the channelinput()an intent cannot trust anattributerun()the only place a write may happenwrites: [ … ]the tags it declared, and onlythose303, back where it camethe answer a browser getsACK · 0x22the answer a channel client getsDELTA · 0x16every region under those tagsrefreshes
One dispatch, two callers. A form post and a channel frame reach the same input() and the same run(); only the answer differs — a 303 for the browser that submitted, an ACK for the client that dispatched. The tags in writes are what become refreshes.
✓ Valid writes, declared up front

The framework drops exactly the tags you named and nothing else. Naming nothing is legitimate for an intent that owns no cached state — and the client never names your code: an intent is addressed by an opaque id derived from its module and export, so renaming the export does not change the wire.

✕ Refused invalidating a tag outside writes
what you wrote→the tag is checked against the declaration→E_UNDECLARED_WRITE · 500

An undeclared write is an invalidation nobody could predict by reading the code, and predicting it by reading the code is the whole value of the effect graph. Unlike the read guard, this one is not dev-only.

In plain terms

Nothing but an intent may write. It declares four things — a name, the tags it invalidates, a validator for its input, and a body — and that is the whole surface. Post it from a plain form and the page works with JavaScript switched off; dispatch it from the channel and the same four things run.

A render cannot write. That is enforced by the type of the context a render receives, not by a convention — so every mutation is an intent, and intents are the only thing in this framework allowed to change anything.

sketch — not compiled
// app/intents/cart.ts
import { defineIntent } from '@weftjs/core'

export const add = defineIntent<{ sku: string; qty: number }>({
  name: 'cart.add',                       // for logs and `weft why`. Never on the wire
  writes: ['cart'],                       // the complete set this may invalidate
  input: (raw) => parse(raw),             // throwing here is a 422, not a 500
  async run(ctx, { sku, qty }) {
    await db.cart.add(ctx.session, sku, qty)
    await ctx.revalidate('cart')          // an undeclared tag throws
  },
})

A form, a hidden field and a POST to the route the intent manifest generated. This one is live: pressing it dispatches a real intent in this process.

output
0
app/fragments/examples/helpful.tsx
import { fragment } from '@weftjs/core'

/**
 * A mutation with no JavaScript on the page at all.
 *
 * The form posts to `/_weft/i/docs.helpful`, which is the route the intent manifest generated from
 * `app/intents/feedback.ts`. Phase A dispatch means a real status code, a cookie the server may set
 * `HttpOnly`, and a 303 back here — the three things a `fetch` handler cannot give you and the
 * reason the no-JavaScript path is the *first* path rather than the fallback.
 *
 * The same intent, unchanged, is what a client would dispatch over the channel. There is no second
 * endpoint and no second handler.
 */
export default fragment(({ page, count }: { page: string; count: number }) => (
  <form class="vote" method="post" action="/_weft/i/docs.helpful">
    <input type="hidden" name="page" value={page} />
    <button type="submit">Useful</button>
    <span class="count">{count}</span>
  </form>
))
What the compiler knows
Holes2
Escape elided0
Effect setnone — static
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
pageattrescape
counttextproven-safe

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
951dcf634875ff1de1098eb7eb26b16b

Phase A dispatch is what makes a real status, an HttpOnly cookie and a 303 available — the three things a fetch handler cannot give you. The count is real, it is this process’s, and it moves when you press the button — which took three declarations agreeing. The intent names docs.votes in writes, so ctx.revalidate may fire it. The body is a live region tagged with the same name, so the write drops it. And the route carries that tag too: a document held for an hour under no tag is a second cache the invalidation cannot reach, and while it was missing every layer here worked perfectly and the number stayed at zero. W_DOCUMENT_OUTLIVES_INVALIDATION exists so the next person is told instead of guessing. The cost is named too: this page is L0_LIVE rather than a file, which is the trade a page about writing has a reason to make and the other twenty-one guide pages do not.

That form is not an illustration: app/intents/feedback.ts is a real module in this application, so the manifest generated from it has a route and pressing the button dispatches the intent. Its id is c2d722 — the first six characters of a hash of the module path and the export name, which is what the client would carry if this page had any JavaScript. The tally is in this process’s memory, because a documentation site has no reason to bind a store.

Two rules

A write is declared, and an undeclared one throws. ctx.revalidate('orders') from an intent that did not declare orders is E_UNDECLARED_WRITE, naming the tag and the field to add it to. Unlike the plugin read guard this is not dev-only: an undeclared read is a missed optimisation, and an undeclared write is a cache invalidation nobody can predict by reading the code.

The client never names server code. An intent is addressed by an opaque id derived from its module and export, so renaming the function does not change the wire and the wire does not disclose a function name.

The same intent, three ways in

CallerWhat happens
A form post, no JavaScriptDispatched in phase A, so a real status, an HttpOnly cookie and a 303 are all available.
fetchThe same dispatch, outcome as JSON, chosen by Accept rather than a second endpoint.
Over the channelThe client stages its guess in an epoch; success replaces it with the truth in one paint, failure discards it.

Every field an intent may declare — reads, capabilities, signed, limit, invalidatesAll — is on the defineIntent reference, along with defineRenderable, which is the same shape for the other thing a client may ask this deployment to do.

Who may run one

An intent may declare capabilities, and an intent declaring one with nothing bound to check it is refused rather than allowed — E_NO_CAPABILITY_CHECK. A signed intent carries a token this deployment issued, and a token may be narrowed once into a leaf that authorises less. Minting is uncacheable by construction, which is why a signed intent has no no-JavaScript path.