@driftengine/core 3.62.0 → 4.0.0

package/dist/render/fog.js

@@ -0,0 +1,138 @@
+/**
+ * The medium between the camera and everything it can see, as arithmetic.
+ *
+ * **`shaders/fog.ts` was the only copy and it is GLSL**, which two things now make a problem. The
+ * GPU-driven pipeline is written in WGSL and cannot include it, so the second pipeline drew no fog
+ * at all; and a term that exists only as a shader is a term nothing can disagree with, which is the
+ * argument `gpudriven/lit.ts` and `gpudriven/alphaTest.ts` were both written under.
+ *
+ * So this is the expression in TypeScript, and both shaders are checked against it:
+ * `scripts/gpu-parity.mjs` runs the WGSL over generated cases, and `shaders/fog.ts` stays exactly
+ * as it is. **This is a second reader of one decision rather than a second decision** — every
+ * guard, every constant and the order of the two mixes are the GLSL's, and where a line looks odd
+ * that file's header is the long version of why.
+ *
+ * **What it does not carry** is the uniform block. `shaders/fog.ts` declares ten uniforms because a
+ * block that declares everything it uses can be pasted into any program; a function takes them as
+ * one argument instead, and the backends keep their own packing.
+ */
+import { resolveAtmosphere } from './atmosphere.js';
+/** Beer-Lambert through a haze layer that thins with height. `uFogMode` 0. */
+export const MEDIUM_FOG = 0;
+/** A ramp between two distances, which is a look rather than a medium. `uFogMode` 1. */
+export const LINEAR_FOG = 1;
+/**
+ * Linear interpolation **written the way `mix` is defined**, which is not the same arithmetic as
+ * the fused form.
+ *
+ * GLSL and WGSL both define `mix(x, y, a)` as `x * (1 - a) + y * a`. Written `x + (y - x) * a` the
+ * two agree to within rounding everywhere except the endpoints, where the fused form is off by an
+ * ulp — `0.82 + (0.2 - 0.82) * 1` is 0.20000000000000007 rather than 0.2. That is invisible in a
+ * picture and fatal in a parity check, and it is what the first run of this file's tests found: the
+ * reference and the device have to be the same *expression*, not the same function.
+ */
+function mix(x, y, a) {
+    return x * (1 - a) + y * a;
+}
+/** What distance converges toward: the day's haze, or the water column. */
+export function mediumColour(fog) {
+    const t = fog.underwaterFactor;
+    return [
+        mix(fog.colour[0], fog.underwaterColour[0], t),
+        mix(fog.colour[1], fog.underwaterColour[1], t),
+        mix(fog.colour[2], fog.underwaterColour[2], t),
+    ];
+}
+/**
+ * How much of a surface standing at `pointY`, `dist` metres away, is lost to the medium between.
+ * 0 is perfectly clear, 1 is the medium's own colour.
+ */
+export function mediumFog(fog, dist, pointY) {
+    /*
+     * **A depth ramp rather than a medium, for worlds authored against one.** Before `near` the air
+     * is perfectly clear, which Beer-Lambert can never be, and height falloff has no meaning here
+     * because a ramp is defined on distance alone. `shaders/fog.ts` argues the whole of it.
+     */
+    if (fog.mode === LINEAR_FOG) {
+        /* A consumer asking for a hard cut writes `far === near`; the guard is why that is a cut. */
+        const span = Math.max(fog.far - fog.near, 1e-4);
+        const ramp = Math.min(1, Math.max(0, (dist - fog.near) / span));
+        if (fog.underwaterFactor <= 0)
+            return ramp;
+        const wetLinear = fog.underwaterDensity * dist;
+        return mix(ramp, 1 - Math.pow(2, -wetLinear * wetLinear * 1.442695), fog.underwaterFactor);
+    }
+    const t = (pointY - fog.eyeY) * fog.heightFalloff;
+    /*
+     * `(1 - e^-t)/t`, which tends to 1 as the ray levels out. **Guarded rather than branched**: at
+     * `t = 0` the quotient is 0/0, and 1e-4 of a scale height is 8 mm.
+     */
+    const denom = Math.abs(t) < 1e-4 ? 1e-4 : t;
+    const air = 1 - Math.exp((-fog.density * dist * (1 - Math.exp(-denom))) / denom);
+    if (fog.underwaterFactor <= 0)
+        return air;
+    /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing
+       about how the water column reads. */
+    const wet = fog.underwaterDensity * dist;
+    return mix(air, 1 - Math.pow(2, -wet * wet * 1.442695), fog.underwaterFactor);
+}
+/** A target for `atmosphereFog`, allocated once, outside the frame loop. */
+export function createFogTarget() {
+    return {
+        colour: [0, 0, 0],
+        density: 0,
+        heightFalloff: 0,
+        eyeY: 0,
+        underwaterColour: [0, 0, 0],
+        underwaterDensity: 0,
+        underwaterFactor: 0,
+        mode: MEDIUM_FOG,
+        near: 0,
+        far: 1,
+    };
+}
+/** `resolveAtmosphere`'s own target, reused, because this runs a frame at a time. */
+const RESOLVED = {
+    fogColor: new Float32Array(3),
+    underwaterColor: new Float32Array(3),
+    fogDensity: 0,
+    fogHeightFalloff: 0,
+    fogEyeY: 0,
+    fogMode: 0,
+    fogNear: 0,
+    fogFar: 1,
+    underwaterFogDensity: 0,
+    underwaterFactor: 0,
+};
+/**
+ * The haze an `Environment` makes at a camera's height, as `GpuDrivenView.fog` takes it.
+ *
+ * **The forward path's own decision, handed over rather than made again.** A consumer drawing
+ * both pipelines in one frame has one environment and needs one haze from it, and
+ * `resolveAtmosphere` is where the forward path decides which medium the camera is in and what it
+ * looks like — the density at the eye, the linear ramp's two radii, how far under water the eye
+ * is. This calls it and copies the answer across field for field, so the two pipelines cannot
+ * disagree about where the fog begins or whether the camera is submerged. Both mode numbers are
+ * the shaders' `uFogMode`, which is why no mapping stands between them.
+ *
+ * @param underwater The renderer's `underwaterAtmosphere` quality, which gates the second medium
+ * on the forward path; pass the same.
+ */
+export function atmosphereFog(atmosphere, eyeY, underwater, out) {
+    const medium = resolveAtmosphere(atmosphere, eyeY, underwater, RESOLVED);
+    out.colour[0] = medium.fogColor[0];
+    out.colour[1] = medium.fogColor[1];
+    out.colour[2] = medium.fogColor[2];
+    out.density = medium.fogDensity;
+    out.heightFalloff = medium.fogHeightFalloff;
+    out.eyeY = medium.fogEyeY;
+    out.underwaterColour[0] = medium.underwaterColor[0];
+    out.underwaterColour[1] = medium.underwaterColor[1];
+    out.underwaterColour[2] = medium.underwaterColor[2];
+    out.underwaterDensity = medium.underwaterFogDensity;
+    out.underwaterFactor = medium.underwaterFactor;
+    out.mode = medium.fogMode;
+    out.near = medium.fogNear;
+    out.far = medium.fogFar;
+    return out;
+}

package/dist/render/frame/alias.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where each transient resource lives in the frame's arena, so that two which are never alive
+ * together share the memory.
+ *
+ * **First fit over slots, in declaration order.** Not best fit and not a bin-packing search:
+ * the input is tens of resources whose order is already meaningful, the packing runs once per
+ * frame composition rather than per frame, and a first-fit result is stable — which matters far
+ * more than a few saved bytes, because an allocator whose output moves between frames moves
+ * every binding with it.
+ *
+ * A slot records the widest resource it has held and the node at which its current occupant
+ * dies. A later resource may take the slot when it is born strictly after that node.
+ */
+import type { Lifetimes } from './lifetime.ts';
+import type { VirtualTable } from './virtual.ts';
+export interface AliasPlan {
+    /** Byte offset into the arena per identifier, or -1 when nothing writes it. */
+    offsets: Int32Array;
+    /** Byte offset of each slot, parallel to `slotEnd` and `slotSize`. */
+    slotAt: Int32Array;
+    /** Node at which each slot's current occupant is last read. */
+    slotEnd: Int32Array;
+    /** Widest resource each slot has held. */
+    slotSize: Int32Array;
+    /** How many slots are in use. */
+    slots: number;
+}
+export declare function createAliasPlan(capacity: number): AliasPlan;
+export declare function planAliases(table: VirtualTable, lifetimes: Lifetimes, out: AliasPlan): number;
+export declare function offsetOf(plan: AliasPlan, id: number): number;

package/dist/render/frame/alias.js

@@ -0,0 +1,61 @@
+import { firstWrite, lastRead } from './lifetime.js';
+import { virtualBytes } from './virtual.js';
+export function createAliasPlan(capacity) {
+    return {
+        offsets: new Int32Array(capacity),
+        slotAt: new Int32Array(capacity),
+        slotEnd: new Int32Array(capacity),
+        slotSize: new Int32Array(capacity),
+        slots: 0,
+    };
+}
+/** Alignment every slot starts on. 256 is the widest uniform-buffer alignment WebGPU requires. */
+const ALIGN = 256;
+function aligned(bytes) {
+    return Math.ceil(bytes / ALIGN) * ALIGN;
+}
+export function planAliases(table, lifetimes, out) {
+    out.offsets.fill(-1);
+    out.slots = 0;
+    let total = 0;
+    for (let id = 0; id < table.count; id += 1) {
+        const born = firstWrite(lifetimes, id);
+        if (born === -1)
+            continue;
+        const dies = lastRead(lifetimes, id);
+        const size = aligned(virtualBytes(table, id));
+        let placed = -1;
+        for (let slot = 0; slot < out.slots; slot += 1) {
+            if ((out.slotEnd[slot] ?? 0) < born) {
+                placed = slot;
+                break;
+            }
+        }
+        if (placed === -1) {
+            placed = out.slots;
+            out.slotAt[placed] = total;
+            out.slotSize[placed] = size;
+            total += size;
+            out.slots = placed + 1;
+        }
+        else if (size > (out.slotSize[placed] ?? 0)) {
+            /*
+             * The slot has to widen, and widening in place would overlap whatever follows it. Retiring
+             * the slot and opening a new one is correct and costs one wasted slot; compacting would
+             * move every offset after it, which is the stability the header refuses to give up.
+             */
+            out.slotEnd[placed] = Number.MAX_SAFE_INTEGER;
+            placed = out.slots;
+            out.slotAt[placed] = total;
+            out.slotSize[placed] = size;
+            total += size;
+            out.slots = placed + 1;
+        }
+        out.offsets[id] = out.slotAt[placed] ?? 0;
+        out.slotEnd[placed] = dies;
+    }
+    return total;
+}
+export function offsetOf(plan, id) {
+    return plan.offsets[id] ?? -1;
+}

package/dist/render/frame/deps.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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;
+}
+export declare function createDeps(nodeCapacity: number, edgeCapacity: number): Deps;
+export declare function resetDeps(deps: Deps): void;
+export declare function depsNodeCount(deps: Deps): number;
+export declare function recordDeps(deps: Deps, reads: readonly number[], writes: readonly number[]): number;
+/**
+ * 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 declare function recordMaskDeps(deps: Deps, reads: number, writes: number): number;
+export declare function readsOf(deps: Deps, node: number): Int32Array;
+export declare function writesOf(deps: Deps, node: number): Int32Array;

package/dist/render/frame/deps.js

@@ -0,0 +1,122 @@
+const SPAN_STRIDE = 4;
+export function createDeps(nodeCapacity, edgeCapacity) {
+    return {
+        edges: new Int32Array(edgeCapacity),
+        spans: new Int32Array(nodeCapacity * SPAN_STRIDE),
+        used: 0,
+        count: 0,
+    };
+}
+export function resetDeps(deps) {
+    deps.used = 0;
+    deps.count = 0;
+}
+export function depsNodeCount(deps) {
+    return deps.count;
+}
+function growEdges(deps, need) {
+    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) {
+    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, reads, writes) {
+    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) {
+    let count = 0;
+    for (let rest = mask >>> 0; rest !== 0; rest &= rest - 1)
+        count += 1;
+    return count;
+}
+function writeBits(deps, mask, at) {
+    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, reads, writes) {
+    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, node) {
+    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, node) {
+    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/dist/render/frame/flushGraph.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 type { Deps } from './deps.ts';
+import type { GraphPass, GraphScratch } from './graphSchedule.ts';
+import type { Lifetimes } from './lifetime.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 declare function createFlushSchedule(capacity: number): FlushSchedule;
+/**
+ * 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 declare function scheduleFlush(arena: Arena, clearMask: number, liveOut: number, state: FlushSchedule, out: ScheduledPass[]): number;

package/dist/render/frame/flushGraph.js

@@ -0,0 +1,84 @@
+import { nodeCount, nodeReads, nodeWrites } from './arena.js';
+import { createDeps, recordMaskDeps, resetDeps } from './deps.js';
+import { createGraphPasses, createGraphScratch, scheduleGraph } from './graphSchedule.js';
+import { computeLifetimes, createLifetimes, lastRead } from './lifetime.js';
+import { RESOURCE_COUNT } from './resources.js';
+export function createFlushSchedule(capacity) {
+    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, nodes) {
+    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, clearMask, liveOut, state, out) {
+    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];
+        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/dist/render/frame/graphSchedule.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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';
+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 declare function createGraphPasses(capacity: number): GraphPass[];
+/**
+ * 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 declare function createGraphScratch(nodes: number, identifiers: number): GraphScratch;
+/**
+ * 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 declare function scheduleGraph(deps: Deps, count: number, live: ArrayLike<number>, ordered: Uint8Array, out: GraphPass[], scratch?: GraphScratch, liveCount?: number): number;