vidya/design-plans/rendergraph-transient-aliasing.md

Plan: Correct Transient-Resource Aliasing in renderer_rendergraph

Status: proposed — rev 3 (code-verified; rev-2 review + follow-up comments applied) Date: 2026-10-26 Scope: crates/renderer_rendergraph, crates/renderer_resources, crates/renderer_device

Goal

Fix the broken transient-resource aliasing in the rendergraph: lifetimes must be derived from the graph's real ordering (dependency DAG + batches, not command indices), alias reuse must be synchronized with barriers, and the resources crate must gain the infrastructure to compute correct memory requirements so correctly sized pools can be allocated and bound to graph-created resources.

Diagnosis (verified against code)

#	Defect	Evidence
1	Lifetimes are command-index intervals (first_command/last_command), but commands within a topo_batches batch are conceptually concurrent — two resources used by different commands of the same batch are wrongly treated as non-overlapping	graph.rs:66-79, 862-877
2	Batch index is not a happens-before proof: the DAG only contains edges for conflicting same-resource accesses and is discarded after topo_batches; e.g. test independent_commands_share_a_batch... produces batches [0,2],[1] with no edge 2→1	graph.rs:643-657, 683-697, 699-714
3	Queue transfers unmodeled: QueueTransfer exists but every barrier sets None; no command→queue assignment exists anywhere (derive_queue_capabilities is a resource-wide stage union, not a per-command queue)	graph.rs:41-58, 792, 822, 1461-1541
4	No alias-safety barriers: build_barriers only tracks prior uses of the same resource; nothing orders last use of alias A before first use of alias B sharing memory	graph.rs:728-835
5	Packing uses texture_size_estimate/desc.size, ignoring real VkMemoryRequirements, alignment, memory-type bits, bufferImageGranularity, and dedicated-allocation requirements; offsets are never bound to resources	graph.rs:888-919, 1543-1588
6	No offset-aware bind path: bind_buffer_memory/bind_image_memory bind whole VMA allocations; Allocation::Shared(Arc<DeviceObject<GpuAllocation>>) exists but is unused for pooling	device.rs:209-214, 766-778

Design decisions (post-review)

D1 — Happens-before, not batch numbers

Retain the dependency adjacency from GraphCompiler::dependencies() in CompiledGraph and add an explicit happens_before(a, b) reachability query. Alias A→B is permitted only if every terminal use of A happens-before every initial use of B. Batch intervals are computed (for reporting/limits) but never used as the safety criterion. Same-batch uses always interfere.

happens_before is computed as a transitive closure at compile time: one bitset per command (Vec<FixedBitSet>-style reachability rows, or bitset columns if that packs better), built once in compile() from the Kahn adjacency. Queries are then O(1) and deterministic. Rationale: the command count is bounded by the recorded command list (thousands at most), closure is O(V·E/64) once, and per-query BFS would be re-run per alias-candidate pair during placement for no benefit. Note the closure's semantics: edges encode only conflicting same-resource accesses, so reachability means exactly "provably ordered via a resource-hazard chain" — precisely the aliasing-safety criterion. Commands mutually unreachable (including same-batch pairs) interfere.

D2 — Phase split

compile() stays device-free: dependency order, batch lifetimes, interference. A new device-dependent plan_placements(device) (called from resolve) does requirements queries, pool placement, alias-barrier construction, and binding. Tests that call bind_lifetimes() directly are updated.

D3 — Conservative queue policy

There is no command→queue assignment today and all commands record into one command buffer. Aliasing is restricted to the single-queue case; any pair whose accesses can't be proven ordered on one queue interferes. Cross-queue aliasing (with ownership transfers/semaphores) is explicitly out of scope and documented as a follow-up — no fake QueueTransfer support.

D4 — Alias synchronization done correctly

• For aliased buffers: emit a VkMemoryBarrier2 (new MemoryBarrier + PipelineBarrier.memory_barriers) before the new occupant's first-use command (a concrete command, not "batch start"), with src = old occupant's aggregated terminal stage/access (writes; execution-only if read-only), dst = new occupant's aggregated first-use scope.
• For aliased images: fold the old occupant's terminal scope into the new image's first-use image barrier (srcStageMask/srcAccessMask = old scope, oldLayout = UNDEFINED) — a bare memory barrier does not chain with a following srcStageMask=NONE layout transition.
• Aggregate multi-scope accesses per command (OR all stage/access for the resource at that command).
• Placement is range-based: a new resource's [offset, offset+size) is tested against all occupied ranges; barriers include every old occupant intersecting the range.

D5 — Vulkan aliasing correctness details

• bufferImageGranularity: separate pools per class (linear-only and optimal-only) is the primary strategy — first-fit stays simple and no padding logic is needed. Intra-pool offsets are rounded only to each resource's alignment. (Intra-pool interleaving with granularity-driven offset rounding is a deliberate non-goal; revisit only if pool-class split waste ever shows up in practice.)
• Set VK_IMAGE_CREATE_ALIAS_BIT on pooled images.
• Exclude from pools: requiresDedicatedAllocation resources, explicit AllocationStrategy::Dedicated (incl. the 64 MiB heuristic), and host-visible (CpuToGpu/GpuToCpu) resources — Buffer::map() returns slices from the allocation base and would silently map wrong bytes unless suballocation offsets are tracked.
• Created-but-unused resources: skip creation entirely (or allocate outside the pool) — decided as "skip unused transients", with a test.
• Pooled images must have GraphTextureDesc.layout == UNDEFINED: plan_placements rejects non-UNDEFINED declared initial layouts on pooled images with a graph error (a created image's declared initial layout cannot be honored by reused memory, whose contents are always undefined at first use). Non-pooled images keep today's behavior.

D6 — Device/resources infra (new APIs, not existing ones)

• renderer_device: allocate_memory(requirements, …) via vk_mem::Alloc::allocate_memory with CAN_ALIAS; find_memory_type_index; bind_buffer_at_offset/bind_image_at_offset via bind_*_memory2 with allocation_local_offset; require API ≥1.1 or enable the full get_memory_requirements2/bind_memory2/dedicated_allocation extension set with a clear error otherwise (same guard pattern as the existing dedicated-allocation check in device.rs); define shared-allocation ownership/cleanup: at bind time the group transfers the Arc<DeviceObject<GpuAllocation>> into each bound resource's Allocation::Shared and drops its own reference — the underlying memory is freed when the last bound resource drops (via DeviceObject drop), matching the existing Owned/Shared semantics. The group never retains a post-bind handle.
• renderer_resources: symmetric Buffer::new_unallocated / Image::new_unallocated, memory_requirements() (incl. VkMemoryDedicatedRequirements), bind_allocation(alloc, offset) with alignment/type-bits/bounds validation; a memory module with MemoryRequirements + MemoryGroup (bind → Allocation::Shared). Pool groups are keyed by a memory type that is in every member's memoryTypeBits (intersection), not by any single member's individually best type; a member whose bits exclude the group's type moves to another group or its own allocation. New renderer_resources::Error variants for failed requirement queries / bind-time validation (alignment, type-bits, bounds); renderer_rendergraph maps these into new GraphError variants (e.g. PlacementFailed(ResourceId), BindFailed(ResourceId)) — bind/placement failures surface through resolve/plan_placements's existing renderer_resources::Result boundary and map at the call site. No graph types leak into this crate.

Task breakdown (ordered, dependency-explicit)

1. renderer_device: memory-type query, aliasable shared allocation, offset-aware bind, API/extension guards, error variants, ownership docs. Tests with TestVulkan (--features testing).
2. renderer_resources: unbound create + requirements + bind APIs for buffer and image; memory module (MemoryRequirements, MemoryGroup); update crate AGENTS.md. Existing Buffer::new/Image::new unchanged.
3. renderer_rendergraph (analysis): retain dependency DAG in CompiledGraph; happens_before query; batch-mapped ResourceLifetime {first_batch, last_batch}; replace memory_offset: u64 with a typed Placement {offset, size, alignment, pool, aliased}; imported resources tracked but excluded from packing; queue-conservatism rule per D3.
4. renderer_rendergraph (synchronization): MemoryBarrier + PipelineBarrier.memory_barriers; recorder emits vk::MemoryBarrier2 in DependencyInfo (anchored via the existing recording_steps before_command mechanism, like today's image/barrier steps); alias-barrier construction per D4 (buffer and image variants, aggregation, first-use-command anchoring); new GraphError variants for placement/bind failures per D6, mapped from renderer_resources::Error at the resolve boundary.
5. renderer_rendergraph (placement): plan_placements(device) replaces resolve()'s current eager create+allocate loop (graph.rs:1218-1276) for pooled resources — create unbound, query requirements, group by a memory type common to every member's memoryTypeBits, granularity-aware first-fit over ranges (D4/D5, pool-per-class), allocate groups, bind, store placements in CompiledGraph. Non-poolable resources (dedicated, host-visible, imports) keep an allocate-and-bind-whole path equivalent to today's. "Skip unused transients" lands here: created resources absent from lifetimes are never created (no behavior change needed in record_commands, which already skips ids absent from lifetimes at graph.rs:1290). Transactional and idempotent; remove texture_size_estimate from allocation decisions.
6. Docs/tests: update stale TODOs (graph.rs:882, 1315-1319), document the single-queue submission contract and the future multi-queue invariant (alias transitions become semaphore edges).

Verification

• Device-free unit tests: same-batch interference; unordered-but-distinct-batch interference; proven-ordered reuse succeeds; granularity boundary (buffer next to optimal image); range-overlap first-fit; dedicated/host-visible exclusion; unused-transient skip; pooled-image non-UNDEFINED initial layout rejected; alias-barrier scope correctness incl. read-only old occupant and image UNDEFINED transition chaining.
• GPU-gated (tests/graph_validation.rs): buffer-buffer and image-image alias reuse through the real barrier path, submit, device_wait_idle, assert_no_validation_errors; teardown of shared allocation after all resources drop.
• Commands: cargo check --workspace, cargo test -p renderer_rendergraph, cargo test -p renderer_resources --features testing, cargo test -p renderer_device --features testing (from workspace root, pinned toolchain).

Review history

• Drafted independently by deepseek/planner and luna/planner; cross-reviewed by deepseek/reviewer and luna/reviewer (both verdicts: CHANGES REQUIRED).
• Blockers folded into this revision: batch-index ≠ happens-before (D1), compile/resolve phase split (D2), bufferImageGranularity handling (D5), alias-barrier/layout-transition chaining (D4), offset-aware bind APIs are new work not existing capability (D6), queue model restricted to single-queue (D3).
• Rev 3: diagnosis re-verified against code and vk-mem 0.5.0 sources (all six rows and the D6 API names confirmed). Follow-up comments folded in: happens_before = compile-time transitive closure (D1), pool-per-class granularity strategy picked (D5), pooled-image UNDEFINED initial-layout rule (D5), pool groups keyed by intersecting memoryTypeBits (D6), MemoryGroup transfers the Arc at bind time instead of retaining it (D6), placement/bind error surfacing through GraphError (D6/task 4), plan_placements explicitly replaces resolve's eager loop (task 5).