the iquant Metal kq catch-up: kernels at llama.cpp speed, sidecars cache-pinned, tune boot hardened

[borisbat]

ABI break: Program gains a moduleCacheDependencies field and the AST serializer moves to version 118 - external module repos must rebuild their shared_modules against this tree.

The nine iquant Metal kq kernels now run at or above llama.cpp speed on both Metal tiers: M5 mean 1.20x (125/144 cells at 1.0 or better), M4 mean 1.11x (133/144), and every iq2/iq3 format clears 1.0 on both boxes and both tiers. The win is the cvt compose - a float-expanded constant grid word with select-built signs replacing the integer decode chains - promoted across the gemv bases, the mvb batch arms, and the iq3 tensor stages, plus f4-slab gemv twins for iq3s, iq3xxs, and iq2xxs behind runtime crowns.

The races that mint those crowns got fidelity rules: different output buffers per dispatch (a shared output serializes on its hazard and once flipped a verdict by 17 points), a bounded burn phase before the first timed round, back-to-back dispatches. The iq2xxs f4 crown is not auto-raced at all - every isolated regime crowns a twin the served graph rejects - so a serving-confirm rail decides it on the real model: two manifests differing only in the crown, tg128 the verdict. The mechanism lives in ARCHITECTURE_MEASUREMENT sec. 2.21.

Three tune-boot traps are fixed. Tune sidecars are now content-hash-pinned into the module cache: a macro that reads a file at compile time registers it with the new add_module_cache_dependency builtin, and a re-minted sidecar invalidates the cached [tuned] stamps that were the silent failure. A sidecar perm outside the grid falls back loudly instead of failing the boot. Class default profiles ship: arm-i8mm (M4/M5 class) minted on M5 and committed; arm-neon re-minted fresh on M1 at this tip, 49 of 49 winners identical to the committed profile.

Where to look: the F4 template class and enc_kq_gemv in dasllama_metal_kernels.das; race_pair_ms in dasllama_metal_common.das; confirm_serving_crown in harness/tune_kernels.das; addModuleCacheDependency in module_builtin_ast.cpp and the record-header validation in ast_parse.cpp.

Validation, claims, ledger

Validation

• Local model suites CI cannot run: the full dasLLAMA chain on M5 (kernels, model-free, decode arm1+arm10, prefill base+kq, support matrix including the new iq2xxs tensor-twin row, coverage) - 0 failed, 0 errors everywhere; an M4 broad-arm sanity sweep at this tip - 11/11 suites, 0 failed; the gemv/gemm kernel-unit suites on both boxes.
• The coverage census cell reports SKIPPED on the default tier by design (partial-zoo honesty); its floors and the declared never-dispatched list reconciliation passed.
• Woodpecker: two rounds, both findings verified and fixed in-branch (the Windows drive-relative dep path, the unbounded burn loops).
• Preflight full tier: 22 gates green; the one red (the race lab on the metal-less lint lane) was fixed and re-validated on all three lint rails with the targeted gate.
• arm-neon class profile: fresh M1 mint at the PR tip, 49/49 winners identical, file unchanged.

Claims - stated, not tested

• Bind numbers and kargs word layout of race_gemv_f4_twin, race_kq_mulmm, and the race lab's time_arm_us were hand-verified against the class declarations, and independently re-verified in review. A break would race the wrong buffer and crown the wrong kernel.
• The Windows arm of test_tuned's env spelling mirrors the proven env_cmd pattern; no Windows box was in this loop. A break would show as the stale-sidecar cell not seeing DAS_TUNE_MANIFEST on Windows CI.
• Seven iquant mulmm crown families are witnessed by kernel-unit gates plus mint METAL_TWIN rows; the matrix suite's twin row covers iq2xxs end to end. A twin serving garbage would fail the unit gate's oracle bar.
• The k2 gemv's rows/8 grid over-dispatches on a d not divisible by 8; every served d is an 8-multiple. A non-multiple shape would fail the kernel-unit gate at that shape.
• The drive-relative Windows dep fix has no direct test; Windows CI exercises the new GetFullPathName path through every relative-path dep. A break would serve stale [tuned] stamps after a re-mint under a drive-relative manifest path.
• The rewritten checklists took two audit rounds each; fresh cold re-reads after the final fixes were skipped by calibration, and the small src/builtin and utils/mcp rule edits were not re-audited.

Not done

• plans/dasllama_review_grooming.md - audit findings on rules this branch never touched, one grooming sitting per document, plus the recommended lint/gate candidates.
• followup_metal sec. 4a (the elementwise _hx lane; measured knockout is +0.65% pp512) and sec. 5 (tall/db tensor stamps for the deep-K w2 column).
• The tests/CLAUDE.md to tests/ARCHITECTURE.md rename (until then the tests checklist's section cites point at a CLAUDE.md).
• k4/k5 f32-activation gemv pockets stay off-board: the served q8-activations path wins end to end.

🤖 Generated with Claude Code

https://claude.ai/code/session_014mq9AKyoAwvD5T1cigTnRw

[Copilot]

Pull request overview

This PR hardens and extends the module-cache invalidation mechanism to account for macro-consumed file inputs (notably tune sidecars), while also advancing the dasLLAMA Metal KQ kernel/race/tune infrastructure and its validation coverage (including new iquant crowns and serving-confirm logic). It introduces an ABI/serialization version bump to support dependency metadata round-tripping through cached AST records.

Changes:

• Add compile-time “macro file dependency” pinning (add_module_cache_dependency) and serialize/validate those dependencies in the module-cache stream (serializer v118, Program::moduleCacheDependencies).
• Update dasLLAMA Metal iquant kernel/twin/race harness and tests (new f4-slab GEMV twins, tensor twin coverage, serving-confirm crown logic, and checklist/doc routing).
• Add targeted tests/fixtures to prove content-hash invalidation behavior (module-cache + tuned-sidecar cases) and document related review/build rules.

Reviewed changes

Copilot reviewed 50 out of 50 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
utils/mcp/REVIEW.md	Adds a checklist rule about keeping formatter “kept comment” pinning tests strong.
tests/module_cache/test_macro_dep_invalidate.das	New module-cache test to ensure macro-registered file deps invalidate by content, not mtime.
tests/module_cache/_fixtures/mc_dep_used.das	Fixture module required into cache to carry the dependency probe.
tests/module_cache/_fixtures/mc_dep_mod.das	Fixture function macro that registers MC_DEP_FILE via add_module_cache_dependency.
tests/module_cache/_fixtures/mc_dep_drv.das	Driver program that prints probe output for the cache invalidation test.
src/builtin/REVIEW.md	Clarifies checklist wording around Inline-module bind registration rules.
src/builtin/module_builtin_ast.cpp	Implements and exposes add_module_cache_dependency builtin (with path absolutization).
src/ast/ast_parse.cpp	Adds dependency header read/validate + writes deps into the module-cache record header; adds file stat+hash helper.
skills/review_md.md	Updates REVIEW.md authoring guidance for “Planned work” pointers into larger ledgers.
skills/internal/build_and_debug.md	Updates module-cache documentation to reflect new invalidation inputs (mtime+size + content-hash deps).
plans/dasllama_review_grooming.md	Adds backlog plan for additional REVIEW.md grooming follow-ups found during dragon pass.
modules/dasLLVM/tests/tuned_stale_perm_client.das	New test client script for stale-sidecar perm fallback behavior.
modules/dasLLVM/tests/test_tuned.das	Adds tests for stale-sidecar perm fallback and for sidecar-driven module-cache invalidation.
modules/dasLLVM/tests/cant_tuned_bad_pin.das	Negative test: explicit perm= outside grid must still hard-fail compilation.
modules/dasLLVM/tests/cant_tuned_bad_fallback.das	Negative test: broken fallback= chain must still hard-fail compilation.
modules/dasLLVM/REVIEW.md	Updates checklist wording; adds rule that compile-time file reads must pin deps with add_module_cache_dependency.
modules/dasLLVM/daslib/llvm_tune.das	Pins tune sidecar as module-cache dependency before staleness checks.
modules/dasLLVM/CMakeLists.txt	Registers arch-extract specs for dasLLVM daslib [arch] citations in bundles.
modules/dasLLVM/ARCHITECTURE.md	Documents tune sidecar as a module-cache dependency and the validation mechanism.
modules/dasLLAMA/tests/test_metal_support_matrix.das	Makes an iquant tensor-twin carrier row optional and extends crowned kernel list.
modules/dasLLAMA/tests/test_metal_gemv_kernels.das	Extends GEMV kernel-unit gates for new f4-slab twin variants + adds poison controls.
modules/dasLLAMA/tests/test_metal_gemm_kernels.das	Extends GEMM kernel-unit gates, adds iquant tensor twin coverage, converts certain skips to test-level skips, adds poison controls.
modules/dasLLAMA/tests/test_kernel_coverage.das	Updates never-dispatched census list to include new crown-gated/tensor twin classes.
modules/dasLLAMA/tests/REVIEW.md	Refactors checklist rules (contract-pinning gates, geometry vs kargs updates, control requirements, etc.).
modules/dasLLAMA/REVIEW.md	Expands routing rules (GPU race code now also routed to GPU checklist) and clarifies reference-build naming rules.
modules/dasLLAMA/REVIEW_GPU.md	Adds routing to new REVIEW_GPU_RACE.md and refines multiple GPU review rules.
modules/dasLLAMA/REVIEW_GPU_RACE.md	New checklist governing GPU race/knockout/hand-binding arms and fidelity requirements.
modules/dasLLAMA/REVIEW_EXCHANGE.md	Adds rule to keep exchange consent notice wording synced across all checked-in copies.
modules/dasLLAMA/performance/REVIEW.md	Simplifies and refocuses performance checklist rules; removes consent-copy rule moved elsewhere.
modules/dasLLAMA/performance/defaults/arm-i8mm.tune-defaults.json	Adds shipped class default profile for arm-i8mm.
modules/dasLLAMA/harness/tune_kernels.das	Adds serving-confirm crown logic and wiring for metal tensor crown confirmation.
modules/dasLLAMA/harness/REVIEW.md	New harness checklist including “benches list order” invariants.
modules/dasLLAMA/harness/backend_ops_kq_race.patch	Patch file documenting/encoding a reference-tool perf-ladder extension for validation.
modules/dasLLAMA/followup_metal.md	Updates metal follow-up ledger with new findings and new planned sections.
modules/dasLLAMA/dasllama/dasllama_tune.das	Makes stale sidecar perms fall back to a safe fallback perm, while preserving hard failure for explicit perm=.
modules/dasLLAMA/dasllama/dasllama_metal_common.das	Adds shared iquant LUT helper + strengthens race_pair_ms burn phase (bounded loop).
modules/dasLLAMA/dasllama/dasllama_env.das	Adds harness env knob for IQ2_XXS confirm vehicle path.
modules/dasLLAMA/benchmarks/REVIEW.md	Updates benchmark checklist wording and tightens race instrument requirements.
modules/dasLLAMA/benchmarks/matmul/bench_metal_kq_race.das	New Metal KQ race rig for per-format synthetic benchmarking vs a pinned reference table.
modules/dasLLAMA/ARCHITECTURE.md	Updates architecture doc index to reflect new/expanded GPU sections.
modules/dasLLAMA/ARCHITECTURE_MEASUREMENT.md	Documents race fidelity requirements and the serving-confirm crown mechanism.
modules/dasLLAMA/ARCHITECTURE_GPU.md	Documents iquant GEMV grid read + f4-slab twin mechanism and shared helper placement.
modules/dasLLAMA/ARCHITECTURE_GPU_PREFILL.md	Documents dense-KQ tensor mul_mm scaffold design and stamp strategy.
include/daScript/ast/ast.h	ABI change: adds Program::moduleCacheDependencies + declares statAndHashFileDependency.
include/daScript/ast/ast_serializer.h	Bumps AST serializer version to 118 for new per-record dependency header content.
doc/source/stdlib/handmade/function-ast-add_module_cache_dependency-0x6bab73893c4ca81f.rst	Adds stdlib documentation entry for add_module_cache_dependency.
daslib/REVIEW.md	Refines daslib checklist wording and consolidates/clarifies lint-related pinning rules.
daslib/builtin.das	Adds doc comment clarifying that get_command_line_arguments returns a locked view.

Suppressed comments (1)

modules/dasLLVM/tests/test_tuned.das:121

• Same quoting issue for DAS_TUNE_MANIFEST here: unquoted temp paths with spaces will break the env prefix and make the module-cache invalidation test flaky (especially on Windows CI).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 50 out of 50 changed files in this pull request and generated 3 comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/ast/ast_parse.cpp:679

• On record-header deserialize failure, trySerialize already sets serializer_read->failed=true, but this code overwrites it with depCount > SER_MAX_MACRO_DEPS. That can clear the failure flag and prevent cache writeback/self-healing, causing the same broken cache record to be re-read and fail every run.

[Copilot]

Pull request overview

Copilot reviewed 50 out of 50 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

modules/dasLLAMA/tests/test_metal_gemm_kernels.das:155

• The poison-control block deep-clones the entire want buffer (:= clone-init) to perturb a single value. For the mul_mm gates want can be tens of thousands of floats, so this adds unnecessary allocation/copy overhead to the test. Prefer temporarily modifying want[0], running the mismatch, then restoring it.

        //! the control: the same compare must RED on a poisoned expectation (one element off by
        //! an env-scaled-plus-absolute delta) - proves the bar can fail for this arm
        var wantp := want
        wantp[0] += env[0] * 0.1 + 1.0
        t |> success(buf_mismatch_env(by, wantp, env, 2e-4, "{tag} CONTROL(expected-red)") != 0, "{tag}: poison control reds")
        delete wantp

modules/dasLLAMA/tests/test_metal_gemv_kernels.das:104

• The poison-control block deep-clones the full want array (:= clone-init) just to perturb one element. This adds avoidable allocation and O(n) copy per gate (and this test iterates many gates). You can get the same control without cloning by temporarily perturbing want[0], running the mismatch, then restoring the original value.

        //! the control: the same compare must RED on a poisoned expectation (one element off by
        //! an env-scaled-plus-absolute delta) - proves the bar can fail for this arm
        var wantp := want
        wantp[0] += env[0] * 0.1 + 1.0
        t |> success(buf_mismatch_env(by, wantp, env, 2e-4, "{tag} CONTROL(expected-red)") != 0, "{tag}: poison control reds")
        delete wantp

[Copilot]

Pull request overview

Copilot reviewed 51 out of 51 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

tests/module_cache/test_macro_dep_invalidate.das:93

• The relative-dependency probe writes/removes depRel in the process CWD (typically the repo root). That can dirty the working tree and leaves debris if the test is interrupted. You can keep the dependency relative while keeping the scratch file under the already-created temp directory by (1) creating/removing the file at an absolute path under tmp, and (2) running the child from tmp so the relative env value resolves there. On POSIX, avoid MC_DEP_FILE=... cd ... && ... (the env only applies to cd) by wrapping the cd && ... sequence in sh -c so the env prefix applies to the whole script.