@driftengine/core 3.63.0 → 4.1.0

package/src/render/frame/deps.ts

@@ -0,0 +1,155 @@
+/**
+ * What each node reads and writes, when there are too many resources for a mask.
+ *
+ * One flat identifier store with a span per node, which is the same shape `nav/navGraph.ts` uses
+ * for adjacency and for the same reason: the spans are written once in order and read many
+ * times, so an offset and a length beat an array per node by every measure that matters here.
+ *
+ * `readsOf` and `writesOf` return **views into the store**, not copies. A caller that keeps one
+ * past the next `resetDeps` is reading somebody else's edges, which is why neither is exposed
+ * outside `render/`.
+ */
+export interface Deps {
+  /** Every read identifier then every write identifier, node by node. */
+  edges: Int32Array;
+  /** Four entries per node: read offset, read length, write offset, write length. */
+  spans: Int32Array;
+  /** How many identifiers of `edges` are in use. */
+  used: number;
+  /** How many nodes have been recorded. */
+  count: number;
+}
+
+const SPAN_STRIDE = 4;
+
+export function createDeps(nodeCapacity: number, edgeCapacity: number): Deps {
+  return {
+    edges: new Int32Array(edgeCapacity),
+    spans: new Int32Array(nodeCapacity * SPAN_STRIDE),
+    used: 0,
+    count: 0,
+  };
+}
+
+export function resetDeps(deps: Deps): void {
+  deps.used = 0;
+  deps.count = 0;
+}
+
+export function depsNodeCount(deps: Deps): number {
+  return deps.count;
+}
+
+function growEdges(deps: Deps, need: number): void {
+  let size = deps.edges.length === 0 ? 16 : deps.edges.length;
+  while (size < need) size *= 2;
+  const edges = new Int32Array(size);
+  edges.set(deps.edges);
+  deps.edges = edges;
+}
+
+function growSpans(deps: Deps): void {
+  const size = deps.spans.length === 0 ? SPAN_STRIDE * 8 : deps.spans.length * 2;
+  const spans = new Int32Array(size);
+  spans.set(deps.spans);
+  deps.spans = spans;
+}
+
+/*
+ * Both stores are grown before either span is written. Growing between the read span and the
+ * write span would copy a half-written node and silently drop its writes, which is the defect
+ * the growth test in this module's suite exists to catch.
+ */
+export function recordDeps(
+  deps: Deps,
+  reads: readonly number[],
+  writes: readonly number[],
+): number {
+  const need = deps.used + reads.length + writes.length;
+  if (need > deps.edges.length) growEdges(deps, need);
+  if ((deps.count + 1) * SPAN_STRIDE > deps.spans.length) growSpans(deps);
+
+  const readAt = deps.used;
+  for (let i = 0; i < reads.length; i += 1) deps.edges[deps.used + i] = reads[i] ?? 0;
+  deps.used += reads.length;
+
+  const writeAt = deps.used;
+  for (let i = 0; i < writes.length; i += 1) deps.edges[deps.used + i] = writes[i] ?? 0;
+  deps.used += writes.length;
+
+  const node = deps.count;
+  const base = node * SPAN_STRIDE;
+  deps.spans[base] = readAt;
+  deps.spans[base + 1] = reads.length;
+  deps.spans[base + 2] = writeAt;
+  deps.spans[base + 3] = writes.length;
+  deps.count = node + 1;
+  return node;
+}
+
+/*
+ * Count the bits of a mask, which is how many identifiers it becomes.
+ *
+ * Kernighan's loop rather than a table: a mask here has at most `RESOURCE_COUNT` bits and usually
+ * two, so this runs once or twice.
+ */
+function bitCount(mask: number): number {
+  let count = 0;
+  for (let rest = mask >>> 0; rest !== 0; rest &= rest - 1) count += 1;
+  return count;
+}
+
+function writeBits(deps: Deps, mask: number, at: number): void {
+  let offset = at;
+  for (let bit = 0, rest = mask >>> 0; rest !== 0; bit += 1, rest >>>= 1) {
+    if ((rest & 1) === 0) continue;
+    deps.edges[offset] = bit;
+    offset += 1;
+  }
+}
+
+/**
+ * Record a node whose reads and writes are masks, one identifier per set bit, lowest first.
+ *
+ * **What lets a fixed-composition flush be scheduled by identifiers without building a list.** The
+ * forward renderer records masks, and `recordDeps` takes arrays; a flush converting one to the
+ * other through arrays would allocate per node, on the path `AGENTS.md` forbids it on. Bit `n`
+ * is identifier `n`, so `FRAME_RESOURCES` is the first `RESOURCE_COUNT` identifiers of any frame
+ * that mixes the two.
+ */
+export function recordMaskDeps(deps: Deps, reads: number, writes: number): number {
+  const readCount = bitCount(reads);
+  const writeCount = bitCount(writes);
+  const need = deps.used + readCount + writeCount;
+  if (need > deps.edges.length) growEdges(deps, need);
+  if ((deps.count + 1) * SPAN_STRIDE > deps.spans.length) growSpans(deps);
+
+  const readAt = deps.used;
+  writeBits(deps, reads, readAt);
+  const writeAt = readAt + readCount;
+  writeBits(deps, writes, writeAt);
+  deps.used = writeAt + writeCount;
+
+  const node = deps.count;
+  const base = node * SPAN_STRIDE;
+  deps.spans[base] = readAt;
+  deps.spans[base + 1] = readCount;
+  deps.spans[base + 2] = writeAt;
+  deps.spans[base + 3] = writeCount;
+  deps.count = node + 1;
+  return node;
+}
+
+export function readsOf(deps: Deps, node: number): Int32Array {
+  const base = node * SPAN_STRIDE;
+  const at = deps.spans[base] ?? 0;
+  const length = deps.spans[base + 1] ?? 0;
+  return deps.edges.subarray(at, at + length);
+}
+
+export function writesOf(deps: Deps, node: number): Int32Array {
+  const base = node * SPAN_STRIDE;
+  const at = deps.spans[base + 2] ?? 0;
+  const length = deps.spans[base + 3] ?? 0;
+  return deps.edges.subarray(at, at + length);
+}

package/src/render/frame/flushGraph.ts

@@ -0,0 +1,135 @@
+/**
+ * A forward flush, scheduled by the identifier graph instead of by masks.
+ *
+ * **Wave 1A's exit criterion is that both pipelines are expressible in one graph and today's frames
+ * are pixel-identical through it.** The second pipeline records its stages into a `Deps` table
+ * (`gpudriven/pipeline.ts`); this is the forward renderer's half. A flush's arena is recorded as
+ * identifier nodes — bit `n` of a mask is identifier `n` — scheduled by `scheduleGraph`, and the
+ * load and store each attachment gets are derived from `lifetime.ts`. What comes out is the same
+ * `ScheduledPass` the mask scheduler writes, so the executor reading it does not know which ran.
+ *
+ * **One difference, and the renderer never reaches it.** Culling here is transitive: a pass whose
+ * only reader was dropped is dropped too, where `schedule.ts` keeps it. Every node the renderer
+ * records writes something its live set holds, so no flush it makes has a dropped reader —
+ * `flushGraph.test.ts` holds a random corpus of its own shapes to exact agreement and names the
+ * frame where the two part.
+ *
+ * Allocates nothing once warm. The state is the caller's and grows only when a flush outgrows it,
+ * the way the arena does.
+ */
+import type { Arena } from './arena.ts';
+import { nodeCount, nodeReads, nodeWrites } from './arena.ts';
+import type { Deps } from './deps.ts';
+import { createDeps, recordMaskDeps, resetDeps } from './deps.ts';
+import type { GraphPass, GraphScratch } from './graphSchedule.ts';
+import { createGraphPasses, createGraphScratch, scheduleGraph } from './graphSchedule.ts';
+import type { Lifetimes } from './lifetime.ts';
+import { computeLifetimes, createLifetimes, lastRead } from './lifetime.ts';
+import { RESOURCE_COUNT } from './resources.ts';
+import type { ScheduledPass } from './schedule.ts';
+
+export interface FlushSchedule {
+  deps: Deps;
+  scratch: GraphScratch;
+  passes: GraphPass[];
+  lifetimes: Lifetimes;
+  /** Every node ordered: a forward draw's position is its meaning. Grown with the arena. */
+  ordered: Uint8Array;
+  /** The live identifiers of this flush, and how many of them there are. */
+  live: Int32Array;
+  liveCount: number;
+}
+
+export function createFlushSchedule(capacity: number): FlushSchedule {
+  const nodes = Math.max(1, capacity);
+  return {
+    deps: createDeps(nodes, nodes * 4),
+    scratch: createGraphScratch(nodes, RESOURCE_COUNT),
+    passes: createGraphPasses(nodes),
+    lifetimes: createLifetimes(RESOURCE_COUNT),
+    ordered: new Uint8Array(nodes).fill(1),
+    live: new Int32Array(RESOURCE_COUNT),
+    liveCount: 0,
+  };
+}
+
+/* Grown where allocation is allowed: a flush larger than any before it, once. */
+function fit(state: FlushSchedule, nodes: number): void {
+  if (state.ordered.length < nodes) {
+    const size = Math.max(nodes, state.ordered.length * 2);
+    state.ordered = new Uint8Array(size).fill(1);
+    while (state.passes.length < size) state.passes.push({ first: 0, count: 0, ordered: true });
+  }
+}
+
+/**
+ * Schedule an arena's nodes through the identifier graph, into the mask scheduler's records.
+ *
+ * `clearMask` and `liveOut` mean what they mean to `schedule`: what this flush still owes a clear,
+ * and what must survive it. Returns how many of `out` were filled.
+ */
+export function scheduleFlush(
+  arena: Arena,
+  clearMask: number,
+  liveOut: number,
+  state: FlushSchedule,
+  out: ScheduledPass[],
+): number {
+  const total = nodeCount(arena);
+  if (total === 0) return 0;
+  fit(state, total);
+
+  const deps = state.deps;
+  resetDeps(deps);
+  for (let node = 0; node < total; node += 1) {
+    recordMaskDeps(deps, nodeReads(arena, node), nodeWrites(arena, node));
+  }
+
+  state.liveCount = 0;
+  for (let bit = 0; bit < RESOURCE_COUNT; bit += 1) {
+    if ((liveOut & (1 << bit)) === 0) continue;
+    state.live[state.liveCount] = bit;
+    state.liveCount += 1;
+  }
+
+  const scheduled = scheduleGraph(
+    deps,
+    total,
+    state.live,
+    state.ordered,
+    state.passes,
+    state.scratch,
+    state.liveCount,
+  );
+  computeLifetimes(deps, total, state.lifetimes);
+
+  let filled = 0;
+  let cleared = 0;
+  for (let p = 0; p < scheduled; p += 1) {
+    const pass = state.passes[p] as GraphPass;
+    const record = out[filled];
+    if (record === undefined) return filled;
+    /* An ordered run shares one write set, so its first node's mask is the run's. */
+    const writes = nodeWrites(arena, pass.first);
+    const end = pass.first + pass.count;
+    /*
+     * Discardable where nothing at or after the run's end reads it and nothing outside the flush
+     * does either. `lastRead` is the last reader anywhere in the flush, culled or not, which is the
+     * mask scheduler's rule: a dropped pass's read still happened as far as a store op knows.
+     */
+    let discard = 0;
+    for (let bit = 0; bit < RESOURCE_COUNT; bit += 1) {
+      const mask = 1 << bit;
+      if ((writes & mask) === 0 || (liveOut & mask) !== 0) continue;
+      if (lastRead(state.lifetimes, bit) < end) discard |= mask;
+    }
+    record.writes = writes;
+    record.first = pass.first;
+    record.count = pass.count;
+    record.clear = clearMask & writes & ~cleared;
+    record.discard = discard;
+    cleared |= writes;
+    filled += 1;
+  }
+  return filled;
+}

package/src/render/frame/graphSchedule.ts

@@ -0,0 +1,170 @@
+/**
+ * Grouping and culling for a frame whose composition is not fixed.
+ *
+ * **`schedule.ts` is not replaced.** It schedules the forward path, where the composition is
+ * fixed and a mask is exactly right, and it stays. This is its counterpart for the other path,
+ * and the two differences are the whole reason it exists.
+ *
+ * **Culling is transitive here and is not there.** The mask scheduler drops a pass whose writes
+ * nothing later reads. Once it has, the pass whose only reader was the dropped one has become
+ * dead too — and a single backward scan over masks never revisits it. A GPU-driven frame makes
+ * that ordinary rather than exotic, because turning off one quality flag kills a consumer
+ * several passes downstream. So liveness is propagated backwards to a fixed point first, and
+ * grouping runs over what survives.
+ *
+ * **Some nodes may be reordered and most may not.** A node marked ordered carries meaning in its
+ * position — blending and depth make *after* different from *before*, which is the rule
+ * `schedule.ts` states and this does not weaken. An unordered node is a compute dispatch whose
+ * result depends only on its declared reads, and two adjacent ones may merge whatever they write.
+ */
+import type { Deps } from './deps.ts';
+import { readsOf, writesOf } from './deps.ts';
+
+export interface GraphPass {
+  /** Index of the first node in the run. */
+  first: number;
+  /** How many nodes the run holds. */
+  count: number;
+  /** Whether this pass's position carries meaning. */
+  ordered: boolean;
+}
+
+export function createGraphPasses(capacity: number): GraphPass[] {
+  return Array.from({ length: capacity }, () => ({ first: 0, count: 0, ordered: true }));
+}
+
+/**
+ * What a schedule works in, owned by the caller so a flush allocates nothing.
+ *
+ * `keep` is a flag a node and `wanted` a flag an identifier. Both are cleared at the start of every
+ * call, so a scratch carried from one frame to the next answers exactly as a fresh one would.
+ */
+export interface GraphScratch {
+  keep: Uint8Array;
+  wanted: Uint8Array;
+}
+
+export function createGraphScratch(nodes: number, identifiers: number): GraphScratch {
+  return {
+    keep: new Uint8Array(Math.max(1, nodes)),
+    wanted: new Uint8Array(Math.max(1, identifiers)),
+  };
+}
+
+/*
+ * Make the scratch big enough for this frame, which is the one place it may allocate.
+ *
+ * A frame that outgrows it has to be scheduled somehow, and growing here once is what the arena
+ * does too; the scratch the caller keeps is then large enough for every frame like it. Doubled, so
+ * a frame that grows by one node at a time does not reallocate every frame.
+ */
+function fitScratch(scratch: GraphScratch, deps: Deps, count: number): void {
+  if (scratch.keep.length < count) {
+    scratch.keep = new Uint8Array(Math.max(count, scratch.keep.length * 2));
+  }
+  let ceiling = 0;
+  for (let i = 0; i < deps.used; i += 1) ceiling = Math.max(ceiling, (deps.edges[i] ?? 0) + 1);
+  if (scratch.wanted.length < ceiling) {
+    scratch.wanted = new Uint8Array(Math.max(ceiling, scratch.wanted.length * 2));
+  }
+}
+
+/*
+ * Mark every node that contributes to something in `live`, to a fixed point.
+ *
+ * Backwards, because a node is needed exactly when something after it reads what it writes. One
+ * backward sweep suffices for a chain; the outer repeat covers a node that writes a resource
+ * read by an earlier-indexed node, which cannot happen in a well-formed frame but costs one
+ * comparison to be safe about rather than one silently wrong picture to discover.
+ *
+ * `fitScratch` sized both flags for everything recorded, and this relies on it: a keep flag past
+ * the end of `keep` would read 0 after being set, and the sweep would never settle.
+ */
+function markLive(
+  deps: Deps,
+  count: number,
+  live: ArrayLike<number>,
+  liveCount: number,
+  scratch: GraphScratch,
+): void {
+  const { keep, wanted } = scratch;
+  keep.fill(0, 0, count);
+  wanted.fill(0);
+  /* A live identifier past the end is one no node writes, and a typed array ignores the write. */
+  for (let i = 0; i < liveCount; i += 1) wanted[live[i] ?? -1] = 1;
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (let node = count - 1; node >= 0; node -= 1) {
+      if (keep[node] === 1) continue;
+      const writes = writesOf(deps, node);
+      let needed = false;
+      for (let i = 0; i < writes.length; i += 1) {
+        if (wanted[writes[i] ?? 0] === 1) {
+          needed = true;
+          break;
+        }
+      }
+      if (!needed) continue;
+      keep[node] = 1;
+      changed = true;
+      const reads = readsOf(deps, node);
+      for (let i = 0; i < reads.length; i += 1) wanted[reads[i] ?? 0] = 1;
+    }
+  }
+}
+
+function sameWrites(deps: Deps, a: number, b: number): boolean {
+  const left = writesOf(deps, a);
+  const right = writesOf(deps, b);
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i += 1) if (left[i] !== right[i]) return false;
+  return true;
+}
+
+/**
+ * Group the live nodes of a frame into passes, and answer how many of `out` were filled.
+ *
+ * `live` is what must survive the frame, and only its first `liveCount` entries are read — so a
+ * caller can keep one typed array and a count rather than build a list. `scratch` is the working
+ * set; a caller that passes none gets one made for the call, which is what a test wants and what a
+ * frame must not do.
+ */
+export function scheduleGraph(
+  deps: Deps,
+  count: number,
+  live: ArrayLike<number>,
+  ordered: Uint8Array,
+  out: GraphPass[],
+  scratch: GraphScratch = createGraphScratch(count, 1),
+  liveCount: number = live.length,
+): number {
+  fitScratch(scratch, deps, count);
+  markLive(deps, count, live, liveCount, scratch);
+  const keep = scratch.keep;
+
+  let passes = 0;
+  let at = 0;
+  while (at < count) {
+    if (keep[at] === 0) {
+      at += 1;
+      continue;
+    }
+    const isOrdered = ordered[at] === 1;
+    let end = at + 1;
+    while (end < count && keep[end] === 1) {
+      const nextOrdered = ordered[end] === 1;
+      if (isOrdered !== nextOrdered) break;
+      if (isOrdered && !sameWrites(deps, at, end)) break;
+      end += 1;
+    }
+    const pass = out[passes];
+    if (pass === undefined) return passes;
+    pass.first = at;
+    pass.count = end - at;
+    pass.ordered = isOrdered;
+    passes += 1;
+    at = end;
+  }
+  return passes;
+}

package/src/render/frame/index.ts

@@ -27,3 +27,55 @@ export {
 export type { ScheduledPass } from './schedule.ts';
 export { schedule } from './schedule.ts';
 export { keptNodes, scratchFor } from './replay.ts';
+
+/*
+ * The identifier-addressed half, for a frame whose composition is not fixed. See `virtual.ts`
+ * for why there are two representations and why neither converts into the other.
+ */
+export type {
+  VirtualBufferDesc,
+  VirtualDesc,
+  VirtualTable,
+  VirtualTextureDesc,
+} from './virtual.ts';
+export {
+  createVirtualTable,
+  declareVirtual,
+  resetVirtualTable,
+  virtualBytes,
+  virtualCount,
+  virtualKind,
+} from './virtual.ts';
+export type { Deps } from './deps.ts';
+export {
+  createDeps,
+  depsNodeCount,
+  readsOf,
+  recordDeps,
+  recordMaskDeps,
+  resetDeps,
+  writesOf,
+} from './deps.ts';
+export type { Lifetimes } from './lifetime.ts';
+export { computeLifetimes, createLifetimes, firstWrite, lastRead } from './lifetime.ts';
+export type { AliasPlan } from './alias.ts';
+export { createAliasPlan, offsetOf, planAliases } from './alias.ts';
+export type { GraphPass, GraphScratch } from './graphSchedule.ts';
+export { createGraphPasses, createGraphScratch, scheduleGraph } from './graphSchedule.ts';
+export type { FlushSchedule } from './flushGraph.ts';
+export { createFlushSchedule, scheduleFlush } from './flushGraph.ts';
+export { validateGraph } from './validate.ts';
+
+/*
+ * Per-pass timings, which are the one thing here that *is* on the package barrel — see the note
+ * beside its export in `src/index.ts`. A readout is not the graph.
+ */
+export type { PassTimings } from './passTimings.ts';
+export {
+  createPassTimings,
+  passLabel,
+  passMs,
+  recordPassLabel,
+  recordPassSample,
+  resetPassTimings,
+} from './passTimings.ts';

package/src/render/frame/lifetime.ts

@@ -0,0 +1,61 @@
+/**
+ * When each transient resource is first written and last read.
+ *
+ * Two numbers per identifier and one pass over the nodes, which is all the aliasing allocator
+ * needs and is deliberately less than a general dependency graph would compute. There is no
+ * topological sort here because there is no reordering here: the node order is the caller's,
+ * exactly as `schedule.ts` requires for the fixed path and for the same reason — blending and
+ * depth make *after* different from *before*.
+ *
+ * **A resource written and never read still has a lifetime**, ending at the node that writes
+ * it. It has to: memory it is being written into cannot be handed to something else at the same
+ * moment. Reporting an empty lifetime there is the bug this module's third test exists to catch.
+ */
+import type { Deps } from './deps.ts';
+import { readsOf, writesOf } from './deps.ts';
+
+export interface Lifetimes {
+  /** Node index of the first write per identifier, or -1. */
+  first: Int32Array;
+  /** Node index of the last read per identifier, or the first write when nothing reads it. */
+  last: Int32Array;
+}
+
+export function createLifetimes(capacity: number): Lifetimes {
+  return { first: new Int32Array(capacity), last: new Int32Array(capacity) };
+}
+
+export function computeLifetimes(deps: Deps, count: number, out: Lifetimes): void {
+  out.first.fill(-1);
+  out.last.fill(-1);
+
+  for (let node = 0; node < count; node += 1) {
+    const writes = writesOf(deps, node);
+    for (let i = 0; i < writes.length; i += 1) {
+      const id = writes[i] ?? 0;
+      if (out.first[id] === -1) {
+        out.first[id] = node;
+        out.last[id] = node;
+      }
+    }
+    /*
+     * Reads are folded in after this node's writes, so a node that reads and writes the same
+     * identifier extends the lifetime rather than starting a second one. A read of something
+     * nothing has written is ignored here and refused by `validate.ts`, which is where a
+     * malformed frame belongs.
+     */
+    const reads = readsOf(deps, node);
+    for (let i = 0; i < reads.length; i += 1) {
+      const id = reads[i] ?? 0;
+      if (out.first[id] !== -1) out.last[id] = node;
+    }
+  }
+}
+
+export function firstWrite(out: Lifetimes, id: number): number {
+  return out.first[id] ?? -1;
+}
+
+export function lastRead(out: Lifetimes, id: number): number {
+  return out.last[id] ?? -1;
+}

package/src/render/frame/passTimings.ts

@@ -0,0 +1,69 @@
+/**
+ * Where a frame's milliseconds went, one row per graph pass.
+ *
+ * **Not a widening of `gpuTimer.ts`, and that is deliberate.** That class is a WebGL2 query pool
+ * over `TIME_ELAPSED_EXT`, partitioning a frame into three fixed brackets — shadows, reflection,
+ * rest — and it is right for what it measures. A graph pass is not one of three brackets: there
+ * are as many as the frame composes, they are named at record time, and on WebGPU the sample
+ * comes from a timestamp query rather than an elapsed-time extension. Two different measurements
+ * with two different shapes; widening one into the other would leave a class that does neither
+ * well.
+ *
+ * **What it does inherit from that class is its best rule: unmeasured is not zero.** A device
+ * without timestamp queries, or a pass that ran no work, must not read as "took no time" — a
+ * profiler that cannot distinguish those two is a profiler that sends somebody optimising a pass
+ * that never ran. `passMs` returns null for unmeasured and a number for measured, including zero.
+ *
+ * **Labels persist and timings reset.** A pass that did nothing this frame keeps its name and
+ * reports unmeasured, so the profiler's rows stop jumping about as quality settings toggle
+ * passes on and off — which is exactly when somebody is reading it.
+ */
+export interface PassTimings {
+  /** Accumulated milliseconds per pass for the current frame. */
+  ms: Float64Array;
+  /** Whether each pass received a sample this frame. */
+  measured: Uint8Array;
+  /** Name per pass, kept across frames. */
+  labels: string[];
+}
+
+export function createPassTimings(capacity: number): PassTimings {
+  return {
+    ms: new Float64Array(capacity),
+    measured: new Uint8Array(capacity),
+    labels: Array.from({ length: capacity }, () => ''),
+  };
+}
+
+/** Start a frame: timings go, labels stay. See the header for why they are treated differently. */
+export function resetPassTimings(timings: PassTimings): void {
+  timings.ms.fill(0);
+  timings.measured.fill(0);
+}
+
+/**
+ * Add one sample to a pass.
+ *
+ * Accumulates rather than replaces, because a pass may be sampled more than once in a frame — a
+ * shadow pass runs per cascade — and the row a reader wants is what that pass cost altogether.
+ */
+export function recordPassSample(timings: PassTimings, pass: number, ms: number): void {
+  if (pass < 0 || pass >= timings.ms.length) return;
+  timings.ms[pass] = (timings.ms[pass] ?? 0) + ms;
+  timings.measured[pass] = 1;
+}
+
+export function recordPassLabel(timings: PassTimings, pass: number, label: string): void {
+  if (pass < 0 || pass >= timings.labels.length) return;
+  timings.labels[pass] = label;
+}
+
+/** Milliseconds this pass cost, or null where nothing measured it. Null is not zero. */
+export function passMs(timings: PassTimings, pass: number): number | null {
+  if (pass < 0 || pass >= timings.ms.length) return null;
+  return timings.measured[pass] === 1 ? (timings.ms[pass] ?? 0) : null;
+}
+
+export function passLabel(timings: PassTimings, pass: number): string {
+  return timings.labels[pass] ?? '';
+}

package/src/render/frame/validate.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether a recorded frame is one that can be executed.
+ *
+ * One rule: a node may read an identifier only if something wrote it earlier in this frame, or
+ * it was imported into the frame from outside. That catches the whole family of defects a fixed
+ * resource table caught by construction — a pass sampling an attachment the quality settings
+ * disabled, a pass reading a mip chain built only when a different feature is on — and which
+ * identifiers do not catch by construction, because any integer is a plausible identifier.
+ *
+ * Returns a message rather than throwing. The renderer decides whether a malformed frame is a
+ * developer-time assertion or a dropped frame, and a validator that throws has made that
+ * decision for it.
+ */
+import type { Deps } from './deps.ts';
+import { readsOf, writesOf } from './deps.ts';
+
+export function validateGraph(
+  deps: Deps,
+  count: number,
+  imported: readonly number[],
+): string | null {
+  const written = new Set<number>(imported);
+  for (let node = 0; node < count; node += 1) {
+    /*
+     * Reads are checked before this node's writes join the set, which is what makes a read of
+     * something written only later a refusal and a read-modify-write legal — the latter is
+     * reading contents something earlier put there.
+     */
+    const reads = readsOf(deps, node);
+    for (let i = 0; i < reads.length; i += 1) {
+      const id = reads[i] ?? 0;
+      if (!written.has(id)) {
+        return `node ${node} reads resource ${id}, which nothing wrote and nothing imported`;
+      }
+    }
+    const writes = writesOf(deps, node);
+    for (let i = 0; i < writes.length; i += 1) written.add(writes[i] ?? 0);
+  }
+  return null;
+}