JS-replay trace (DG_TRACE_JS=<outdir>)

Dumps everything a thin JS+WebGPU replayer needs to re-execute a decode step of the DiffusionGemma engine (the Campaign-3 trace-replay pattern, aimed at Chrome instead of Metal):

• k<hash>.wgsl — every template-expanded kernel, written once at first pipeline compile (per-process pipeline cache guarantees the source is in hand exactly then).
• ops.jsonl — the event stream while ARMED: {"t":"d","k":H,"n":name,"g":[x,y,z],"b":[[bufName,uid],…]} dispatch {"t":"w","u":uid,"o":off,"s":size,"hex":"…"?} writeBuffer {"t":"r","u":uid,"o":off,"s":size} readback {"t":"f"} queue flush {"t":"m","tag":str} marker
• buffers.json — uid → byte size for every buffer created while enabled.
• tensors.json — uid → GGUF tensor name (weight provenance: the JS side loads the GGUF itself and uploads each tensor into its replay slot).

Buffer identity = getBufferId (the raw WGPUBuffer handle), already used by the bind-group cache. Write contents are recorded as hex for writes ≤ 64 KB (params, canvases, norms); larger writes (weights) are size-only — their provenance comes from tensors.json.

opaque Hesper.WGSL.JSTrace.dirRef : IO.Ref (Option String)

opaque Hesper.WGSL.JSTrace.armedRef : IO.Ref Bool

opaque Hesper.WGSL.JSTrace.seenKernelsRef : IO.Ref (Std.HashMap UInt64 Bool)

opaque Hesper.WGSL.JSTrace.opsRef : IO.Ref (Array String)

opaque Hesper.WGSL.JSTrace.bufSizesRef : IO.Ref (Array (UInt64 × Nat))

opaque Hesper.WGSL.JSTrace.tensorsRef : IO.Ref (Array (UInt64 × String))

opaque Hesper.WGSL.JSTrace.untracedRef : IO.Ref Nat

opaque Hesper.WGSL.JSTrace.refUidsRef : IO.Ref (Std.HashMap UInt64 Bool)

opaque Hesper.WGSL.JSTrace.hexUidsRef : IO.Ref (Std.HashMap UInt64 Bool)

@[inline]

def Hesper.WGSL.JSTrace.enabled : IO Bool

Equations

• Hesper.WGSL.JSTrace.enabled = do let __do_lift ← ST.Ref.get Hesper.WGSL.JSTrace.dirRef pure __do_lift.isSome

def Hesper.WGSL.JSTrace.arm : IO Unit

Equations

• Hesper.WGSL.JSTrace.arm = do let __do_lift ← Hesper.WGSL.JSTrace.enabled if __do_lift = true then ST.Ref.set Hesper.WGSL.JSTrace.armedRef true else pure PUnit.unit

def Hesper.WGSL.JSTrace.disarm : IO Unit

Equations

• Hesper.WGSL.JSTrace.disarm = ST.Ref.set Hesper.WGSL.JSTrace.armedRef false

@[inline]

def Hesper.WGSL.JSTrace.armed : IO Bool

Equations

• Hesper.WGSL.JSTrace.armed = ST.Ref.get Hesper.WGSL.JSTrace.armedRef

def Hesper.WGSL.JSTrace.toHex (b : ByteArray) : String

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.emit (line : String) : IO Unit

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.kernel (sourceHash : UInt64) (wgsl : String) : IO Unit

record a kernel's WGSL at first compile (independent of arming: the pipeline cache means compile happens once, possibly before the traced step).

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.dispatch (sourceHash : UInt64) (name : String) (grid : Nat × Nat × Nat) (bufs : Array (String × UInt64)) : IO Unit

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.write (uid : UInt64) (offset : Nat) (data : ByteArray) : IO Unit

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.read (uid : UInt64) (offset size : Nat) (data : ByteArray) : IO Unit

readback event; contents ≤ 2MB are recorded so a replayer can gate on bit-equality without porting the CPU logic that consumes them.

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.flush : IO Unit

Equations

• Hesper.WGSL.JSTrace.flush = Hesper.WGSL.JSTrace.emit "{\"t\":\"f\"}"

def Hesper.WGSL.JSTrace.mark (tag : String) : IO Unit

Equations

• Hesper.WGSL.JSTrace.mark tag = Hesper.WGSL.JSTrace.emit (toString "{\"t\":\"m\",\"tag\":\"" ++ toString tag ++ toString "\"}")

def Hesper.WGSL.JSTrace.bufCreated (uid : UInt64) (size : Nat) : IO Unit

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.tensor (uid : UInt64) (name : String) : IO Unit

Equations

• One or more equations did not get rendered due to their size.

opaque Hesper.WGSL.JSTrace.cksumRef : IO.Ref Bool

opaque Hesper.WGSL.JSTrace.dispCntRef : IO.Ref Nat

@[inline]

def Hesper.WGSL.JSTrace.cksumOn : IO Bool

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.fnv32 (b : ByteArray) (n : Nat := 4096) : UInt32

FNV-1a 32-bit over the first n bytes (mirrored by the JS replayer).

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.cksum (hs : Array UInt32) : IO Unit

Equations

• One or more equations did not get rendered due to their size.

def Hesper.WGSL.JSTrace.outDirGet : IO (Option String)

Equations

• Hesper.WGSL.JSTrace.outDirGet = ST.Ref.get Hesper.WGSL.JSTrace.dirRef

def Hesper.WGSL.JSTrace.clearOps : IO Unit

drop accumulated ops (used between the ref-collection step and the recorded replay step).

Equations

• Hesper.WGSL.JSTrace.clearOps = ST.Ref.set Hesper.WGSL.JSTrace.opsRef #[]

def Hesper.WGSL.JSTrace.missingUids : IO (Array UInt64)

uids referenced by traced dispatches that have NEITHER GGUF tensor provenance NOR recorded write contents — the derived buffers a replayer must load from .bin dumps.

Equations

• Hesper.WGSL.JSTrace.missingUids = do let refs ← ST.Ref.get Hesper.WGSL.JSTrace.refUidsRef pure (Array.map (fun (x : UInt64 × Bool) => x.fst) refs.toList.toArray)

def Hesper.WGSL.JSTrace.untraced : IO Unit

Equations

• Hesper.WGSL.JSTrace.untraced = do let __do_lift ← Hesper.WGSL.JSTrace.armed if __do_lift = true then ST.Ref.modify Hesper.WGSL.JSTrace.untracedRef fun (x : Nat) => x + 1 else pure PUnit.unit

def Hesper.WGSL.JSTrace.save : IO Unit

write ops.jsonl / buffers.json / tensors.json and report.

Equations

• One or more equations did not get rendered due to their size.