Current native-performance constraints

As of: 2026-08-27
Authority: generated from internal/nativeperf.BuildCurrentSnapshot; immutable receipts remain the measurement evidence.
Refresh: fak native-performance --current-md

An active constraint is the presently evidenced condition limiting a named performance outcome. Its type, horizon, owner, next action, and exit condition make it actionable; review_by prevents a stale observation from silently remaining current.

Current constraints

Constraint	Type / horizon / state	Envelope and driver	Evidence and authority	Next action / exit
active-native-lane-collision — Live model/compute lane collision	coordination / transient / waiting-coordination Observed 2026-08-27; review by 2026-08-28	portfolio The live DOS lease set still assigns model and compute paths to cache-weight-residency issue #9420 after its implementation landed. Those paths overlap CUDA decode #8635, so commit closure and graph readiness do not authorize another source worker until the lease is released.	[live-readback] The current lease WAL names issue-9420-cache-weight-residency as owner of internal/model and internal/compute paths. (dos lease-lane live (2026-08-27T16:24:05Z readback)) [issue] The Mac umbrella records a worker-tree harvest/lease prerequisite rather than treating open work as runnable. (https://github.com/anthony-chaudhary/fak/issues/9430) Owner: DOS lease WAL; issue #9420	Next: Read back landed #9420, safely release its completed source leases, then arbitrate #8635 by exact paths; do not infer lease ownership from commit or issue state. Exit when: The authoritative live lease readback no longer overlaps each selected packet, and every dispatched packet has its own assignment and disjoint lease.
measurement-control-loop — Real profiling and regression control loop	evidence / semi-durable / waiting-evidence Observed 2026-08-25; review by 2026-09-01	portfolio The classifier and receipt gates are built, but only synthetic Metal/CUDA profile bundles are committed and the scheduled workflow does not consume a returned campaign receipt.	[contract] Profile schema, classification, and one-lever selection are implemented. (docs/benchmarks/NATIVE-PERFORMANCE-HILLCLIMB.md#phaseprofile-bundles-and-bottleneck-selected-work) [open] The current acceptance table names both real profiler bundles OPEN. (docs/benchmarks/NATIVE-PERFORMANCE-HILLCLIMB.md#acceptance-status) [control-loop] The public workflow currently prints the private handoff and validator command; it does not fetch or gate a returned artifact. (.github/workflows/native-performance-regression.yml) Owner: real-profile leaves #9495/#9497 and returned-receipt gate #9498	Next: Capture one real scrubbed Metal bundle and one real scrubbed CUDA bundle, then make the scheduled/manual workflow validate a returned request instead of only printing the handoff. Exit when: Both native envelopes have accepted real profile bundles and one scheduled/manual run consumes a scrubbed request and records the gate verdict.
metal-startup-capacity — Metal current-runtime startup capacity	capacity / semi-durable / capacity-bound Observed 2026-08-26; review by 2026-09-02	qwen38-27b-q4km-m3pro-p32-t64-serve The exact current fak-native serve path estimates a 55.73 GiB startup peak and refuses admission on the sanctioned 36 GiB M3 Pro, so a fresh matched native row cannot be captured there before allocation reduction or larger placement.	[witnessed-refusal] Current fak-native serve refused with METAL_GGUF_PEAK_TOO_BIG at a 55.73 GiB startup estimate on 36 GiB. (https://github.com/anthony-chaudhary/fak/issues/8972#issuecomment-5428177527) Owner: M1 keep/reject parent #8325; landed mechanism #9073; closed hold evidence #8972	Next: Run the exact #8325 startup/steady-memory measurement from trunk containing #9073. If the bound remains above 36 GiB, reserve a sanctioned >=64 GiB Apple-Silicon node for the replacement M5 receipt. Exit when: The exact current-runtime campaign reaches readiness without positive swap on an admitted Mac, either after a witnessed allocation reduction or on a node satisfying the measured bound.
metal-resident-decode — Metal resident decode	dependency / structural / waiting-dependency Observed 2026-08-23; review by 2026-08-27	qwen38-27b-q4km-m3pro-p32-t64 The near-matched native point is about 47% of the diagnostic llama.cpp comparison; repeated synchronous Q4_K submissions and an incomplete coarse hybrid token graph remain the issue-backed driver, pending a real profiler bundle. Ready: metal.command-buffer-amortization	[accepted] The frozen full-run Metal envelope remains 2.3-2.9 decode tok/s with functional PASS. (docs/_witnesses/qwen38-27b-2026-08-20/metal-native-run-summary.json) [approximate] The later observation is 3.3 vs 6.966061 tok/s, P31/T64 vs P32/T64, without a joint quality-complete receipt. (https://github.com/anthony-chaudhary/fak/issues/8697) Owner: issue #8324	Next: Measure landed M1, then run the exact #9230 A/B for landed M2 commit 8a423b8a5 before M3/M4. M4 owns the command-buffer-amortization and coarse resident graph receipt. Exit when: A same-envelope quality-passing receipt proves the default fak-native path owns the coarse token submission and meets the issue’s >=5 tok/s promotion floor, or a real profile selects a different driver.
cuda-cold-decode — CUDA cold decode	dependency / structural / waiting-coordination Observed 2026-08-25; review by 2026-09-01	q38-q4km-native-cuda-a100-cold-decode The exact Q4_K_M A100 cold arm is correct at 11.8-12.1 tok/s. A distinct P=1 optimization envelope still uses scalar f32 activation products before the proposed Q8_1/DP4A path; its A/B must retain that separate identity. Ready: cuda.q8_1-activation-quant	[accepted] Five cold unique runs were 5/5 exact at 11.8-12.1 decode tok/s on A100-SXM4-40GB. (docs/_witnesses/issue-8819-qwen38-cache-attribution/summary.json) [hypothesis] Q8_1 activation quantization followed by signed DP4A Q4_K MMVQ is the issue-owned P=1 sequence; no gain is assumed. (https://github.com/anthony-chaudhary/fak/issues/8635) Owner: issue #8635	Next: After #9420 releases the overlapping compute/model lease, run the strict Q8_1 OFF/ON numerical gate; only then run the DP4A MMVQ end-to-end A/B with Q8_1 fixed ON. Exit when: The default fak-native CUDA decode path passes full-model quality with zero fallback and a repeated same-artifact end-to-end gain, or the measured profile selects another driver.
cuda-cache-correctness — CUDA cache restore correctness	correctness / structural / held-correctness Observed 2026-08-25; review by 2026-09-01	q38-q4km-cuda-a100-cache-restore The identical-prompt cache arm restored the wrong output in 5/5 attempts; its approximately 0.2 tok/s is diagnostic and cannot be optimized or promoted as parity.	[diagnostic] The cache arm was 0/5 exact; four confirmed hits were about 0.2 tok/s. (docs/_witnesses/issue-8819-qwen38-cache-attribution/summary.json) Owner: active issue #9420; closed attribution issue #8819	Next: Finish #9420’s model-lifetime immutable weight residency, then rerun five cold and five identical cache-hit requests with exact output, cache identity, state, upload, clone, and first-step accounting. Exit when: The identical-prompt arm is exact in every gated repetition with cache identity, restored state, zero fallback, and end-to-end timing in the same receipt.
laptop-placement — 36 GiB laptop placement	capacity / structural / capacity-bound Observed 2026-08-26; review by 2026-09-09	q38-q4km-native-metal-m3pro-capacity The canonical no-FAK_Q4K_FREE_CPU control reached readiness and one native Metal token, but peak swap grew by 7,681,930,690 bytes; the fail-closed derived minimum is 44 GiB.	[witnessed-refusal] The 36 GiB control derived a 44 GiB minimum after positive swap growth and restored the prior service. (docs/_witnesses/issue-8971-streamed-q4k-capacity/canonical-no-free-cpu.json) Owner: capacity receipt for closed issue #8971	Next: Place this exact no-free-CPU serving envelope on hardware meeting the 44 GiB derived bound; keep the 36 GiB laptop as control/orchestration or use only a separately named supported envelope. Exit when: A same-artifact, same-environment native receipt proves zero positive swap on admitted hardware, or a newer measured bound supersedes 44 GiB.
native-serving-stack — Native serving stack	dependency / structural / waiting-dependency Observed 2026-08-25; review by 2026-09-03	qwen38-27b-q4km-m3pro-p32-t64 Paged KV, exact-prefix reuse, chunked prefill, and continuous batching lack isolated real Qwen3.8 receipts; combining them before isolated arms would hide attribution. Ready: metal.paged-kv, metal.chunked-prefill	[contract] The graph records each serving mechanism as a separate absent lever with an exact witness requirement. (docs/benchmarks/NATIVE-PERFORMANCE-HILLCLIMB.md#metal-raw-decode-and-serving-levers) Owner: issue #8395	Next: Keep graph-ready serving arms visible but do not dispatch them as Mac-current work until M1-M5 in #9430 clear; then run M6-M9 as isolated serving arms. Exit when: Each mechanism has a quality-passing isolated receipt and the composed serving campaign reports TTFT/ITL p50/p95, aggregate throughput, peak memory, prefix-hit rate, and fallback count.

Divide-and-conquer execution

The hierarchy is constraint -> execution program -> work packet. Packet state is the dispatch truth: running and ready may run; waiting-coordination needs a fresh lease readback; other waiting/hold states do not consume a worker. An open or graph-ready issue is not automatically runnable.

Program	Authority	Hero metric / current	Sequence rule
mac-top10 — Qwen3.8 Mac next ten	#9430	10 / 10 quality-clean, net-positive KEEP receipts Current: 0 / 10 KEEP; M1 and M2 mechanisms landed at 58fc89e29 and 8a423b8a5 but await exact keep/reject measurements	M1-M4 are the memory/submission spine; M5 is the exact receipt gate; M6-M9 are isolated serving arms; M10 is matched close-out. Same-device experiments are serial.
cuda-cache-hit — CUDA exact-cache-hit setup and correctness	#9420	5/5 cold and 5/5 identical-hit exact with one immutable-weight upload and zero fallback Current: implementation landed at b12f23f04; hardware receipt pending; source lease still live	Release the landed source work cleanly, then accept performance only from the matched exact-output A100 receipt.
cuda-cold-decode — CUDA P=1 decode hill climb	#8635	quality-clean repeated default-path end-to-end gain Current: Q8_1 and DP4A unwitnessed	Q8_1 numerical gate, then DP4A A/B, then default routing; never combine the first two arms.
profile-control-loop — Real profile and regression return loop	#8922	real Metal and CUDA profiles consumed by one scheduled/manual gate verdict Current: synthetic profiles only; exact owners are #9495, #9497, and #9498	Capture scrubbed real profiles independently; wire workflow consumption only after both validate.

# / packet	Program	State / owner / lane	Hard dependencies / current blockers	Next / exit
1 / cuda.cache-weight-residency — Model-lifetime immutable CUDA weight residency #9420	cuda-cache-hit	running Owner: anthony-chaudhary / live DOS lease Lane: model+compute	—	Next: Read back landed commit b12f23f04, release the completed source leases, then run the matched A100 receipt; do not count the implementation commit as a performance result. Exit when: One upload survives sequential/concurrent sessions, teardown frees once, and the matched cache-hit receipt is exact with zero fallback.
1 / mac.m1-streamed-q4k-no-copy — M1 no-copy streamed Q4_K keep/reject receipt #8325	mac-top10	ready Owner: unassigned Lane: hardware+docs	—	Next: Assign #8325’s exact-model measurement and run it from trunk containing #9073 commit 58fc89e29; record startup, steady memory, swap, identity, quality, and fallback. Exit when: The landed no-copy mechanism earns M1 KEEP from a safe exact end-to-end memory/performance receipt, or is rejected and replaced without KEEP credit.
2 / mac.m2-whole-sequence-prefill — M2 backend-nil sequence keep/reject receipt #9230	mac-top10	waiting-dependency Owner: unassigned Lane: hardware+docs	Depends: mac.m1-streamed-q4k-no-copy	Next: After M1 establishes a safe exact envelope, run #9230’s P32 A/B from trunk containing #9456 commit 8a423b8a5; #9444 remains rejected as an invalid compute-HAL premise. Exit when: The exact resident sequence arm passes #9230 quality/accounting with zero fallback and every clean repetition improves with median prefill >=15%, or is retained as REJECT with no KEEP credit.
3 / mac.m3-q8-gdn-handoff — M3 Q8 projection-to-GDN device handoff #9216	mac-top10	waiting-dependency Owner: unassigned Lane: metal	Depends: mac.m2-whole-sequence-prefill	Next: Dispatch only after M2 establishes the sequence owner; isolate the Q8-to-GDN handoff in that submission. Exit when: The exact P32 arm preserves parity and shows positive end-to-end movement with one terminal core readback.
4 / mac.m4-coarse-resident-decode — M4 coarse resident hybrid decode graph #8324	mac-top10	waiting-dependency Owner: unassigned Lane: model+metal	Depends: mac.m3-q8-gdn-handoff	Next: Run command-buffer amortization and fused graph coverage as separately attributed OFF/ON arms. Exit when: The exact default fak-native path is quality-clean and meets the >=5 tok/s promotion floor, or a real profile selects a different driver.
5 / mac.m5-exact-p32t64-receipt — M5 quality-clean exact P32/T64 receipt #9430	mac-top10	capacity-hold Owner: unassigned Lane: hardware+docs	Depends: mac.m1-streamed-q4k-no-copy, mac.m2-whole-sequence-prefill, mac.m3-q8-gdn-handoff, mac.m4-coarse-resident-decode	Next: After M1-M4, #9430 must create/reconcile a replacement ship-alone receipt leaf because #8972 was closed without meeting its gate; use >=64 GiB Apple Silicon if admission still exceeds 36 GiB. Exit when: The replacement leaf accepts three quality-complete exact native/control repetitions with zero fallback and safe memory.
6 / mac.m6-paged-hybrid-state — M6 paged Qwen hybrid state live arm #8395	mac-top10	waiting-dependency Owner: unassigned Lane: modelengine	Depends: mac.m5-exact-p32t64-receipt	Next: Run the shipped paging primitive on the exact serving trace as its own arm. Exit when: Occupancy, memory, TTFT/ITL, throughput, state parity, and fallback evidence pass in one receipt.
7 / mac.m7-prefix-reuse — M7 exact-prefix block reuse #8395	mac-top10	waiting-dependency Owner: unassigned Lane: modelengine	Depends: mac.m6-paged-hybrid-state	Next: Reconcile and file one ship-alone child, then run prefix reuse with paged state fixed ON. Exit when: The child has a complete isolated quality, latency, throughput, cache-identity, and fallback receipt.
8 / mac.m8-chunked-prefill — M8 bounded chunked-prefill scheduling #8395	mac-top10	waiting-dependency Owner: unassigned Lane: agent+modelengine	Depends: mac.m5-exact-p32t64-receipt	Next: Reconcile one current child for live scheduling/interleaving, preserving landed append-capable prefill. Exit when: Identical outputs and positive net TTFT/ITL movement are accepted without unsafe memory growth.
9 / mac.m9-resident-cobatching — M9 resident hybrid co-batching #8395	mac-top10	waiting-dependency Owner: unassigned Lane: agent+model	Depends: mac.m5-exact-p32t64-receipt	Next: Reconcile one current child and exercise the live coalescer with per-session hybrid state parity. Exit when: Non-serial execution and positive aggregate throughput are accepted with exact per-session state.
10 / mac.m10-parity-reconvergence — M10 matched parity reconvergence #9430	mac-top10	waiting-dependency Owner: unassigned Lane: hardware+docs	Depends: mac.m6-paged-hybrid-state, mac.m7-prefix-reuse, mac.m8-chunked-prefill, mac.m9-resident-cobatching	Next: Create the close-out leaf only after M6-M9 have isolated keep/reject receipts. Exit when: A same-artifact fak-native versus pinned comparator campaign publishes the exact current result without mixed envelopes.
1 / cuda.q8_1-numerical-gate — Q8_1 activation numerical gate #8635	cuda-cold-decode	waiting-coordination Owner: unassigned Lane: compute	Blocked now: cuda.cache-weight-residency	Next: After #9420 releases compute paths, run the strict Q8_1 OFF/ON numerical gate with the scalar arm explicitly OFF in the candidate. Exit when: Cosine, exact argmax, maxAbs, artifact identity, and raw output pass the issue gate.
2 / cuda.dp4a-q4k-mmvq — DP4A Q4_K MMVQ A/B #8635	cuda-cold-decode	waiting-dependency Owner: unassigned Lane: compute	Depends: cuda.q8_1-numerical-gate	Next: With Q8_1 fixed ON, run the signed DP4A OFF/ON full-model A/B. Exit when: Repeated same-artifact end-to-end gain passes quality and zero-fallback gates.
3 / cuda.default-decode-routing — Default P=1 decode routing #8635	cuda-cold-decode	waiting-dependency Owner: unassigned Lane: compute+model	Depends: cuda.dp4a-q4k-mmvq	Next: Promote only after the full-model A/B proves the fak-native default path. Exit when: Default routing is quality-clean, faster end to end, and reports zero fallback.
1 / profile.real-metal — Real scrubbed Metal profile #9495	profile-control-loop	waiting-dependency Owner: unassigned Lane: hardware+docs	Depends: mac.m1-streamed-q4k-no-copy	Next: After the M1 exact run establishes a runnable envelope, dispatch #9495 to capture and validate the real Metal profile before revising the driver. Exit when: The profile schema accepts a scrubbed real bundle and selects or revises one driver.
2 / profile.real-cuda — Real scrubbed CUDA profile #9497	profile-control-loop	ready Owner: unassigned Lane: hardware+docs	—	Next: Assign #9497, acquire a sanctioned A100 window, and capture the current cold-decode profile independently of #9420’s source-path lease. Exit when: The profile schema accepts a scrubbed real bundle and selects or revises one driver.
3 / profile.returned-receipt-gate — Scheduled/manual returned-receipt gate #9498	profile-control-loop	waiting-evidence Owner: unassigned Lane: ci+nativeperf	Depends: profile.real-metal, profile.real-cuda	Next: After #9495/#9497 validate, dispatch #9498 to consume the returned scrubbed request instead of only printing the handoff. Exit when: One scheduled/manual run records the returned request’s gate verdict and fails closed on an unavailable source.

Graph-dependency-ready arms and collisions

This is the semantic lever view, not a dispatch queue. Every dependency-ready graph arm is shown even when its execution packet is waiting on program order, capacity, hardware, or a live lane. Metal and CUDA are device-independent waves once current cross-cutting leases clear; arms inside a matched envelope remain serial one-lever experiments.

Wave	Envelope	Ready arms	Parallel with	Within-wave rule
metal	qwen38-27b-q4km-m3pro-p32-t64	metal.command-buffer-amortization, metal.paged-kv, metal.chunked-prefill	cuda	Every arm shares one matched Metal envelope and must retain one-lever attribution without device contention.
cuda	qwen38-27b-q4k-a100-p1-decode	cuda.q8_1-activation-quant	metal	The Q8_1 candidate explicitly toggles the conflicting scalar-f32 baseline OFF inside one matched A/B.

Collision	Kind	Members	Why
live-model-compute-lease	live-coordination	cuda.cache-weight-residency, cuda.q8_1-numerical-gate	The current #9420 DOS leases overlap the CUDA source packet after #9420’s implementation landed. #8635 requires a fresh live readback and its own lease.
mac-program-paths	shared-paths-and-device	mac.m1-streamed-q4k-no-copy, mac.m2-whole-sequence-prefill, mac.m3-q8-gdn-handoff, mac.m4-coarse-resident-decode	M1 and M2 are now ordered hardware/docs measurements on one Mac. M3-M4 later overlap model/Metal paths; serialize their edits and all same-device receipts.
metal-envelope	shared-envelope	metal.command-buffer-amortization, metal.paged-kv, metal.chunked-prefill	These arms share the exact M3 Pro envelope; benchmark them serially and never combine them before each isolated receipt exists.
cuda-activation-arm	experiment-toggle	cuda.scalar-f32-activation-baseline, cuda.q8_1-activation-quant	The two activation-product arms conflict; Q8_1 evidence must name the scalar baseline as OFF, not enable both.

OSS-to-performance walk

The closed walk is source -> seam -> measured constraint -> deduped issue -> matched A/B -> keep/reject. An exhaustive source list is discovery input, not permission to create or implement every idea.

State	Meaning	Required evidence
watch	Pinned source identity retained without active implementation work.	repository, revision, license, and why it may matter
candidate	A plausible source seam is named, but the exhaustive study or measured constraint binding is incomplete.	pinned source plus proposed seam; no performance issue inferred
studied	A bounded study and candidate matrix are recorded; incomplete source classes remain explicit and block mapping.	study note, inventory map, completeness critic, explicit coverage limits, and dedupe readback
mapped	One exact source seam is bound to a measured current constraint and a deduped issue.	path/line@revision, FAK seam, constraint ID, and issue readback
mapped-needs-limiter	The exhaustive join found mapped backlog, but no measured limiter has selected which mapped seam should consume the next performance slot.	complete/qualified study, disposition counts, mapped issue evidence, and an explicit limiter-selection gap
experimenting	A one-lever matched A/B is running or captured without a keep decision yet.	baseline/candidate receipts with quality, identity, memory, and end-to-end outcome
kept	The adapted native path passed the A/B and is selected for the default or next composition.	accepted receipt, attribution/license, default-path witness, and rollback
rejected	The source seam failed the A/B or no longer addresses the measured constraint.	negative receipt or superseding profile plus retained reason

#	Gate	Requirement	Exit
1	source	Pin repository revision and license; inventory is discovery evidence, not a FAK gap.	candidate or watch
2	seam	Complete the exhaustive study and name one exact source path/algorithm and one exact fak-native seam.	studied
3	measured constraint	Bind the seam to a current constraint whose profiler/receipt evidence names that driver; otherwise return to watch.	mapped or watch
4	deduped issue	Read back open and closed issues, then attach the route to one owner with a one-lever done condition.	mapped with issue
5	A/B	Implement inside fak-native and capture a matched baseline/candidate with quality, identity, memory, fallback, and end-to-end accounting.	experimenting
6	keep/reject	Keep only a quality-passing end-to-end gain; otherwise retain the negative result and reject or re-profile.	kept or rejected

Current source queue projection

The complete discovery registry remains docs/research/monitored-repositories.json. These rows show only sources currently adjacent to a named performance constraint. candidate, studied, and mapped-needs-limiter are not implementation authorization; mapped backlog is not performance-closed.

Source @ revision	State	Seam	Proposed constraint / deduped issue	Next
vllm-project/vllm@f18d0ba90d972a852a351c98be3f42b31372cfe4	mapped-needs-limiter	193 joined mechanism clusters: 183 actionable, including 168 partial and 13 conflict rows	measurement-control-loop, native-serving-stack / —	Select from the 172 actionable partial/conflict rows using the measured limiter; the current prioritizer walking only five uncovered rows is backlog visibility, not performance closure.
sgl-project/sglang@536f570e6692eec0656ef9689db7591ca1d0e0a7	studied	12 serving and compatibility candidates; forge-history coverage remains explicitly partial	native-serving-stack / #8395	Resolve the partial forge fence, then promote only a candidate selected by the serving limiter and existing issue dedupe.
flashinfer-ai/flashinfer@39b484f1ce2fff086c66f9a899a0a58ba7f0ec3e	mapped-needs-limiter	22 decision-changing CUDA/kernel candidates, all deduped to existing FAK work or dependency-boundary rejection	measurement-control-loop, cuda-cold-decode / —	Use the real CUDA profile to select one already-deduped seam; complete source accounting does not itself choose or close performance work.
llm-d/llm-d@bc20f73bd344b5a0faad5afca93831088aeee957	mapped-needs-limiter	20 serving-control candidates; two unduplicated gaps filed after complete dedupe	native-serving-stack / #9385, #9386	Keep #9385/#9386 visible, but schedule them only when measured serving control or recovery is the active limiter.

Update contract

Update the typed snapshot in the same change that accepts, rejects, or reclassifies evidence. Re-read live issue assignment and dos lease-lane live before changing any running, ready, or waiting-coordination packet; prose comments are not lease evidence. Preserve immutable receipts; change a driver only from a compatible real profile or end-to-end receipt. Run go test ./internal/nativeperf and the focused cmd/fak native-performance tests, then regenerate this page with fak native-performance --current-md.