From aabcbcbb528f4b16ba035e6ed988ce5662d7c4e3 Mon Sep 17 00:00:00 2001 From: Jonathan Fontanez Date: Sat, 22 Aug 2026 16:06:32 -0400 Subject: [PATCH] =?UTF-8?q?docs(plan):=20ship=20kernel-kind-parity-bar=20?= =?UTF-8?q?=E2=80=94=20the=20bar=20is=20every=20kernel=20kind?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The change's one ticket is #1777, merged 2026-08-18 by PR #1896, and it declares no REMOVED bullets, so the gate has nothing to verify. Both obligations the owner ruling created are already discharged: #1758 was widened 2026-08-18 to cover CPU write into an acquired texture, and #1898 is filed post-MVP on Graphics Kernel Buildout for gap 1. The fold was entirely outstanding. The change file records that "the narrowed prose and the ADR annotation ride #1777 / PR #1896"; neither did. PR #1896 touched only the python-kernel-surface change file, and PR #1897 landed this change file plus one header line. So until this commit the plan's own decision source promised Python "reaches every GPU capability Rust authoring reaches" — five days after the owner narrowed it — and the ADR that owns the decision read unannotated. Applied as the change wrote them, paste-ready: - §Graphics' parity entry narrows to every kernel *kind*, with the two gaps a Python processor cannot reach named inside the entry where the claim is read: vertex and index buffers with indexed draws, and storage- and uniform-buffer bindings. Both undesigned. - §Graphics' trailing OPEN entry names gaps 2 and 4 — depth attachments and MSAA — which are unbuilt in every language rather than Python-reach gaps, so they land in OPEN and not in the DECIDED entry. - The ADR's decision 1 is annotated in place, not overwritten, per the docs-policy supersession form. Its differentiator claim survives unnarrowed: being a proxy to Rust-powered GPU work claims a relationship, not a surface area. The two markers the change commissions are CI-runnable and were run: both pass in 0.02s with no GPU. §Graphics stays IN-FLIGHT with no arrow — no live change drives it, and it cannot flip while its last [python-kernel-api] entry, the Rust bindings-at-dispatch convergence, is unbuilt and has no change file. No diagram edit is owed, re-verified rather than assumed: system.mmd's kernel references are neither kind- nor capability-scoped. Refs #1777 Co-Authored-By: Claude Opus 5 (1M context) --- docs/decisions/python-kernel-api.md | 12 +++++++++- docs/plan/ARCHITECTURE.md | 24 +++++++++++++++---- .../2026-08-18-kernel-kind-parity-bar.md} | 0 3 files changed, 30 insertions(+), 6 deletions(-) rename docs/plan/changes/{kernel-kind-parity-bar.md => archive/2026-08-18-kernel-kind-parity-bar.md} (100%) diff --git a/docs/decisions/python-kernel-api.md b/docs/decisions/python-kernel-api.md index ea5104b3e..145b7e599 100644 --- a/docs/decisions/python-kernel-api.md +++ b/docs/decisions/python-kernel-api.md @@ -12,7 +12,17 @@ SPIR-V, or when someone asks why the four GPU bridge traits were deleted. ## Decision -1. **Parity is the bar.** Python reaches every GPU capability Rust authoring reaches — +1. **Parity is the bar.** + > ~~Parity is the bar. Python reaches every GPU capability Rust authoring reaches~~ + > — Superseded 2026-08-17 by owner ruling. The bar is every kernel *kind*, which is + > what the enumeration in this same sentence already names. Pipeline state and buffer + > resources inside a kind are a narrower claim, and the ones Python cannot reach are + > named in the plan rather than promised here. The rest of (1) stands unnarrowed: + > Python still names and drives every kind, and being "a proxy to Rust-powered GPU + > work — not a lesser scripting surface beside it" claims a relationship, not a + > surface area. + + Python reaches every kernel kind Rust authoring reaches — compute, graphics and ray-tracing kernels, acceleration structures, CPU readback. Python names and drives; the engine allocates, compiles, binds, and dispatches. Being a proxy to Rust-powered GPU work — not a lesser scripting surface beside it — is the differentiator diff --git a/docs/plan/ARCHITECTURE.md b/docs/plan/ARCHITECTURE.md index 8b5501f47..a861e87fa 100644 --- a/docs/plan/ARCHITECTURE.md +++ b/docs/plan/ARCHITECTURE.md @@ -222,7 +222,7 @@ Legend: **DECIDED** — build exactly this. **OPEN** — do not build; needs an green-thread style): intended, do not build until designed; hard constraint — no new configuration dials. [execution-model] -## Graphics (RHI / GPU) — IN-FLIGHT (→ kernel-kind-parity-bar) +## Graphics (RHI / GPU) — IN-FLIGHT - **DECIDED** — All Vulkan lives in the RHI (`vulkan/rhi/` + `streamlib-consumer-rhi`); one kernel abstraction per pipeline kind; consumers go through `GpuContext` only. @@ -230,15 +230,24 @@ Legend: **DECIDED** — build exactly this. **OPEN** — do not build; needs an blocks: shader/compute source and binding config passed from Python, compiled and executed by the engine on its device — no user-side Vulkan, ever. [importable-python-library] -- **DECIDED** — Python reaches every GPU capability Rust authoring reaches: compute, +- **DECIDED** — Python reaches every kernel kind Rust authoring reaches: compute, graphics and ray-tracing kernels, acceleration structures, and CPU readback. Python names and drives; the engine allocates, compiles, binds, and dispatches. No kernel - capability is Rust-only. [python-kernel-api; python-kernel-surface — SHIPPED #1773, - #1774, #1777] + kind is Rust-only. Pipeline state and buffer resources inside a kind are a narrower + claim, and the two a Python processor cannot reach are named rather than left silent: + vertex and index buffers with indexed draws — no escalate op mints either buffer, and + no consumer in either language binds one; and storage- and uniform-buffer bindings — + Rust consumers in the engine tree hold them, and the only by-surface-id resolution the + escalate path has is texture-shaped, so a Python processor is refused by name. Both + are undesigned. + [python-kernel-api; python-kernel-surface — SHIPPED #1773, #1774, #1777; + kernel-kind-parity-bar — the parity claim narrowed to kernel kinds] + + - **DECIDED** — A kernel's output is an engine-owned texture that Python names by surface id and passes downstream in a bag, and that a third-party GPU library in its own Python package reaches through a scope: entering blits the texture to a linear @@ -315,7 +324,12 @@ Legend: **DECIDED** — build exactly this. **OPEN** — do not build; needs an go; the command-recorder flow keeps its seam by carrying bindings to the recorder rather than stashing them on the kernel. The Rust convergence is its own change, sequenced after the Python surface. [python-kernel-api] -- **OPEN** — Everything else. +- **OPEN** — Everything else, including the two graphics capabilities no language can + render: depth attachments — Rust constructs a depth-testing pipeline that Python cannot + name, and no pass in either language renders against one — and MSAA, refused for every + caller in every language with the pipeline hardcoded to a single sample. Both are + unbuilt engine capabilities rather than Python-reach gaps; equalising the construction + surface with no pass to render against would buy nothing. ## Media I/O — camera, display, audio — IN-FLIGHT (→ importable-python-library, one-monotonic-clock) diff --git a/docs/plan/changes/kernel-kind-parity-bar.md b/docs/plan/changes/archive/2026-08-18-kernel-kind-parity-bar.md similarity index 100% rename from docs/plan/changes/kernel-kind-parity-bar.md rename to docs/plan/changes/archive/2026-08-18-kernel-kind-parity-bar.md