[jowens]

Follow-up from the declared-buffers work: WriteGPUBuffer and AllocateBuffer's populateWith.

The trap, now documented

Both are queue writes (queue.writeBuffer). They happen while execute() is still recording the encoder, so they land before any of that execute()'s GPU work, wherever they appear in the action list:

[ new Kernel(A), new WriteGPUBuffer({ label: "x", cpuSource }), new Kernel(B) ]
// runs as: write x, then A, then B

Kernel, ClearBuffer, CopyBufferToBuffer and ExecutePrimitive, by contrast, are encoder commands and run in list order. None of this was written down anywhere. It's now in primitive.mjs (one note, plus doc comments on each action class) and in a new "Actions, and when they take effect" section of docs/architecture.md.

Changes

• One upload path for both, BasePrimitive.__writeBuffer(label, data, offset). This settles the todo in __allocateBuffer.
  • WriteGPUBuffer now also skips uploading unchanged data into a uniform buffer, tracked per offset.
  • Writing to an unknown buffer is now an error. It used to be a warning followed by a crash.
• test_wgsl_functions: the input is now written with real data, once whole and then at an offset, and a new test reads it back. Before, it wrote zeros into an already-zero buffer.
• Types: WriteGPUBuffer's offset is now in the type declarations.

Checked

• WGSL function tests: the new test passes with and without subgroups. The same three subgroup tests fail as on main (lavapipe's 8 lanes).
• Regression suite on lavapipe: everything passes except the existing 8-lane sort failures.
• Package test: passes.

Independent of #84.

---

Generated by Claude Code