Graphden documentation

ADR: once-semantics for ref thunks, and the identity-keyed call-cache

Status: ACCEPTED (once-thunks shipped, commit 3c38e090). The residual-window section is a documented NON-decision — revisit only with evidence.

Context

The compiled executor defers every :ref argument behind a 0-arity thunk (rt/thunk) and memoises child invocations in a per-execute call-cache keyed by [ref-id (select-keys fa projection-frees)] (compile-eager/call-with-cache, fa-key-for-cache). Two facts interact:

  1. Values inside fa are largely thunks and callables, so the projected key compares them by object identity.
  2. A thunk may wrap an effectful subtree — :_call-base-handler is the entire app handler chain.

Before this ADR, rt/thunk ran its body on every force. The only thing standing between a second force and a second run of an effectful subtree was a cache hit — i.e. identity equality of thunk instances across call sites. That is not an invariant anyone maintains: env-bindings (env-arg-builder) mint a fresh thunk per parent run, and an unrelated graph edit can change how many parent runs happen.

Observed failure: an inline-anon :cond added in app/branches shifted thunk identities in the response-cache/encode wrap chain of web/http; a projected key diverged, :response was re-forced, and the candidates POST handler executed twice inside one HTTP request — the second run against an already-drained body stream returned an internal 400 whose passthrough headers overwrote the encoded ones (gzip body, no Content-Encoding). Full ledger in the session memory inline-anon-cond-breaks-encode-2026-08-24.

Decision

rt/thunk is once (delay-backed): the wrapped fn runs at most once per thunk instance; later forces return the first result. The 0-arity fn shape is kept so impls reading args raw (((:x args))) still work; the delay inside provides thread-safe run-at-most-once.

Why this is the model and not a patch:

Explicitly NOT changed:

Audit of the wider pattern

Every deferred-construction site in the executor was reviewed after the fix:

Site Verdict
arg-builder :ref (plain + renames), :resolved-value, all env-arg-builder :ref arms rt/thunk → once ✓
:seq non-lazy Clojure lazy-seq — realized cells memoised ✓
:seq lazy-seq? delay per item ✓
resolve-arg IDeref arm delay ✓
hof-wrap / make-shape-callable / HOF env arm callables, invoke-per-call by design ✓
run-with-timeout plain fn param, submitted once ✓
public boundary (execute, make-single-arg-callable) plain caller values in fa ✓

A graph-wide scan then looked for the residual window: an effectful fn (root base-fn declares non-:time/:random effects) with >1 incoming executable ref whose cache-projection-frees intersect env-binding names — the combination where per-parent-run env thunks could diverge keys and re-run the effect. 29 candidates matched (scan sources in the session ledger). Review outcome:

Conclusion: no live instance of the pattern remains. What remains is a constructive gap: nothing guarantees an effectful node is reached under a single env-thunk generation. Closing it for good means moving the call-cache off identity keys (semantic value keys, or a per-execute env scope) — a redesign of the cache-key model, not a local fix.

Consequences / revisit triggers

Consumer note 2026-09-02 — a long-lived render must CALL, not capture

Once-thunks have one consumer-visible consequence that took nine days to surface: a callable that a base-fn keeps and invokes repeatedly (the SSE stream’s :render, re-run on every tick) sees its CAPTURED args resolve exactly once — so a fragment passed as a hiccup VALUE renders its first tree forever, every tick hashes equal, and the stream pushes nothing after its first frame. The Tests panel and the demo clock were dead like that from 2026-08-24 until 2026-09-02; the tutorial’s lesson-16 e2e still passed because the auto-run usually beat the panel’s first fetch.

The fix is graph-side and keeps the ADR’s model: :sse-fragment-handler’s :fragment is a [:fn {} :hiccup-node] slot and :_sse-fragment-rendered CALLS it (:call-noargs) on every render — a callable’s body runs per call (its own bindings are minted per run); only what the WRAPPER captured is once. Rule for any base-fn that re-invokes a callable over time: the thing that must be fresh has to be a fn it calls, never a value it was handed. packages.app.sse-fragment-live-test pins it against the real graph handler over a live socket.