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

daslib/REVIEW.md

@@ -1,8 +1,8 @@
 # daslib Code Review Checklist
 
-**Read `REVIEW_COMMON.md` (repo root) first - its contract binds this checklist.** Architecture doc:
-`daslib/ARCHITECTURE.md` and its companions `ARCHITECTURE_LINT.md`, `ARCHITECTURE_EMIT.md`,
-`ARCHITECTURE_LINQ.md`. Planned work: `plans/daslib_comment_sweep.md` (repo root).
+**Read `REVIEW_COMMON.md` (repo root) first - its contract binds this checklist.** Architecture
+docs: `ARCHITECTURE.md`, `ARCHITECTURE_LINT.md`, `ARCHITECTURE_EMIT.md`, `ARCHITECTURE_LINQ.md`.
+Planned work: `plans/daslib_comment_sweep.md` (repo root).
 A diff touching the linq family - `linq*.das`, `sql_*.das` - applies `REVIEW_LINQ.md` too.
 
 **A diff that adds or changes a lint report path (`perf_warning` / `style_warning` /
@@ -20,8 +20,9 @@ the actionable line is an intermediate call site.
 inside a lint visitor method is a defect.** The guard's position decides which rules apply
 inside a lambda; the per-rule policy is in `ARCHITECTURE_LINT.md` sec. 1.
 
-**Never move `add_ptr_ref`'s depth tracking behind the `in_closure` gate.** The rules block
-is itself a closure, so a gated tracker never sees the splice.
+**Never move PERF023's `add_ptr_ref` splice-depth tracking (`perf_lint.das`) behind the
+`in_closure` gate.** The rules block is itself a closure, so a gated tracker never sees the
+splice.
 
 **A lint warning that anchors anywhere but the code its fix rewrites is a defect.** A remedy
 that deletes a statement reports the statement; a remedy that edits one variable's
@@ -34,23 +35,21 @@ construct's visit.
 **Never keep per-loop visitor state in a bare scalar - keep it in a stack.** A scalar
 survives into the sibling loop's exit path and unbalances its counter.
 
-**A diff that makes a daslib predicate or emitted identifier depend on a C++-side
-definition records the pair in the architecture doc, in its module's section, naming both
-sides.** Nothing catches it when one side later moves alone.
+**A diff that adds or changes a daslib fact - code or a `//!` contract - whose truth is
+decided by a C++-side definition records the pair in the architecture doc, in its module's
+section, naming both sides.** Nothing catches it when one side later moves alone.
 
-**When a diff changes one side of a recorded daslib/C++ pair so the two no longer match,
-it changes the other side and updates the pair's architecture-doc entry in the same
-diff.**
+**When a diff changes one side of a recorded daslib/C++ pair so the two no longer match, it
+changes the other side and updates the pair's architecture-doc entry in the same diff.**
 
 **A diff that adds an architecture-doc entry adds it only where no name, shape, or test can
 carry the fact.**
 
-**Weakening `tests/lint/test_nolint_suppression.das` is a defect** - it pins that a string
+**A diff that changes daslib's nolint scanning - suppression parsing, staleness detection, or
+the header window - keeps `tests/lint/test_nolint_suppression.das` and
+`tests/lint/test_stale_nolint.das` green without weakening them.** They pin that a string
 literal, a URL, and a mid-comment `nolint:` do not suppress while a first-token directive
-after `//` or `//!` does.
-
-**Weakening `tests/lint/test_stale_nolint.das` is a defect** - it pins that a
-`lint-skip-file` past the header window is prose.
+after `//` or `//!` does, and that a `lint-skip-file` past the header window is prose.
 
 **A diff that changes `build_lint_macro_disabled` keeps its four sources layered in this
 order: defaults, repo `off`, repo `on`, environment.** Env last lets a one-run
@@ -60,12 +59,10 @@ order: defaults, repo `off`, repo `on`, environment.** Env last lets a one-run
 seeding and the repo `off` directives.** Repo policy must not silence the rule a fixture
 exists to exercise.
 
-**Weakening `tests/lint/test_lint_config.das` is a defect** - it pins that each `[format]`
-key resolves nearest-wins independently up to the `.git` root, so a nearer `.lint_config`
-declaring one key does not reset the other.
-
-**Weakening the kept-comment cases in `utils/mcp/test_tools.das` is a defect** - they pin
-the formatter's kept set.
+**A diff that changes daslib's `.lint_config` resolution keeps `tests/lint/test_lint_config.das`
+green without weakening it** - it pins that each `[format]` key resolves nearest-wins
+independently up to the `.git` root, so a nearer `.lint_config` declaring one key does not
+reset the other.
 
 **A daslib module that emits a lint rule id joins `RULE_MODULES` in `utils/lint/REVIEW.das`
 in the same change.** An unlisted module's ids are never scanned, so its fixture-and-rst
@@ -115,11 +112,10 @@ set without the cap is a silently missed finding; raising a cap without the over
 suggestion that does not compile.
 
 **A diff that adds or changes an emit entry point - a function that runs the emit visitor
-(`CppAot` or any subclass of it - the visitors that write C++) and then
-returns or writes the generated C++ - keeps the error check ahead of that return
-or write.** The error check is the program's `macroException`/`failToCompile` state, read
-directly or through `log_aot_emit_errors`; a codegen exception mid-visit leaves partial
-C++.
+(`CppAot` or any subclass of it) and then returns or writes the generated C++ - keeps the
+error check ahead of that return or write.** The error check is the program's
+`macroException`/`failToCompile` state, read directly or through `log_aot_emit_errors`; a
+codegen exception mid-visit leaves partial C++.
 
 **Never gate a visitor override in `CppAot` or any subclass of it on
 `macroException`/`failToCompile` - the function that runs the visitor owns that check.** An

daslib/builtin.das

@@ -2123,6 +2123,8 @@ def add_ptr_ref(src : smart_ptr<auto(TT)>) : smart_ptr<TT> {
     }
 }
 
+//! The process argv as an array of strings. The result is a LOCKED VIEW over the host's own
+//! argv storage - keep it in a `let` and never `delete` it or move elements out of it.
 [generic]
 def get_command_line_arguments : array<string> {
     var args : array<string>

doc/source/stdlib/handmade/function-ast-add_module_cache_dependency-0x6bab73893c4ca81f.rst

@@ -0,0 +1 @@
+Registers the file at ``path`` as a compile-time dependency of the module being compiled, so the module cache re-parses the module when that file's size or content hash changes. A macro that reads a file at compile time (a tune sidecar, a config, a generated table) calls this before acting on the contents; outside compilation the call is a no-op.

include/daScript/ast/ast.h

@@ -1691,8 +1691,16 @@ namespace das
         CodeOfPolicies              policies;
         vector<tuple<Module *,string,string,bool,LineInfo>> allRequireDecl;
         das_hash_map<uint64_t,TypeDecl *> astTypeInfo;
+        // compile-time file inputs a macro pinned via add_module_cache_dependency: (path, byte
+        // size, content hash). The module cache stores and re-validates them, so a changed input
+        // invalidates the cached record instead of serving stamps minted against the old file.
+        vector<tuple<string,int64_t,uint64_t>> moduleCacheDependencies;
     };
 
+    // the shared capture/validate stat for Program::moduleCacheDependencies: size -1 + hash 0
+    // when the file is absent or unreadable, else (byte size, hash_block64 of the content)
+    DAS_API void statAndHashFileDependency ( const string & path, int64_t & size, uint64_t & hash );
+
     // access function from class adapter
     DAS_API int adapt_field_offset ( const char * fName, const StructInfo * info );
     DAS_API int adapt_field_offset_ex ( const char * fName, const StructInfo * info, uint32_t & i );

include/daScript/ast/ast_serializer.h

@@ -252,7 +252,7 @@ namespace das {
         AstSerializer & serializeModule ( Module & module, bool already_exists );
 
         static constexpr uint32_t getVersion () {
-            return 117;   // 117: Function::fromGeneric round-trips (generic-instance origin)
+            return 118;   // 118: per-record macro file dependencies (module cache re-validates them)
         }
 
         void serializeProgram ( ProgramPtr program, ModuleGroup & libGroup ) noexcept;

modules/dasLLAMA/ARCHITECTURE.md

@@ -38,11 +38,12 @@ re-transcoding `$LCPP/src/unicode-data.cpp`).
 
 - `ARCHITECTURE_IMAGE.md` - sec.2.1-2.1i: the prepared-image rail, the baked dev-W f16 plane,
   and the baked tower twin-W plane.
-- `ARCHITECTURE_GPU.md` - sec.2.2b, 2.2w-2.2y: the tensor-GEMM and fused-attention shapes that
-  measured out, the tower attention routes, and the tower driver's encode chains.
-- `ARCHITECTURE_GPU_PREFILL.md` - sec.2.2c-2.2i, 2.2u-2.2v: the Metal prefill driver's GEMM form
-  ladder, dev-W knee map, attention slab, MoE bucket rail, chunked submission, the f16 twin
-  dual-store, and the last-layer FFN tail.
+- `ARCHITECTURE_GPU.md` - sec.2.2b, 2.2w-2.2z: the tensor-GEMM and fused-attention shapes that
+  measured out, the tower attention routes, the tower driver's encode chains, and the iquant
+  GEMV grid read with its f4-slab twin.
+- `ARCHITECTURE_GPU_PREFILL.md` - sec.2.2c-2.2i, 2.2u-2.2v, 2.2aa: the Metal prefill driver's
+  GEMM form ladder, dev-W knee map, attention slab, MoE bucket rail, chunked submission, the
+  f16 twin dual-store, the last-layer FFN tail, and the dense-KQ tensor mul_mm scaffold.
 - `ARCHITECTURE_GPU_VULKAN.md` - sec.2.2j-2.2q: the Vulkan resident driver - the prefill window
   chain, the cm2 decode lanes and tile pick, the class-pipeline build seat, the residency plan,
   the GPU-slot marks swap, the Q8 requant byte store, and the MoE expert chain on the cm2 tiles.

modules/dasLLAMA/ARCHITECTURE_GPU.md

@@ -10,7 +10,7 @@ that a question answered for one backend has an obvious address in the other. Th
 | role | holds | must not hold |
 |---|---|---|
 | the kernel home<br>`dasllama_metal_kernels`, `dasllama_vulkan_classes` | kernel source, the derived-access/PSO census | device state, engine types |
-| `dasllama_<gpu>_common`<br>`dasllama_metal_common`, `dasllama_vulkan_common` | device state, buffer/command plumbing, hazard + capture rail, profiler | driver policy |
+| `dasllama_<gpu>_common`<br>`dasllama_metal_common`, `dasllama_vulkan_common` | device state, buffer/command plumbing, hazard + capture rail, profiler, shared quant-decode helpers (`iq4_lut`) | driver policy |
 | `dasllama_<gpu>_decode`<br>`dasllama_metal_decode`, `dasllama_vulkan_decode` | the resident token-step driver + decode-time arms | kernel bodies |
 | `dasllama_<gpu>_prefill`<br>`dasllama_metal_prefill`, `dasllama_vulkan_prefill` | the batched prefill driver + batch arms | kernel bodies |
 | `dasllama_<gpu>_shapes`<br>`dasllama_metal_shapes` | PORTABLE servability gates - no GPU C++ require, so any box can bake | device calls |
@@ -272,3 +272,22 @@ a region's bind offset must be a multiple of 512 elements - the `(off/256)*2` d-
 the exception: it reuses q40's 16-byte plane of eight f16 d per superblock, binds once, and
 ignores `doff`. The Vulkan tier does not use this form - it binds the decoded 20-byte row as five
 uints per superblock.
+
+### 2.2z The iquant GEMV grid read and its f4-slab twin {#metal-iquant-gemv-grid}
+
+Every iquant Metal GEMV - iq3s, iq3xxs, iq2s, iq2xs, iq2xxs - reads its codebook grid DIRECT
+off the module's hoisted constant tables and float-expands each word in place. That is the base
+form and the one that ships everywhere.
+
+Three of them carry a second form, the f4-slab twin (`MetalKqGemvIq3sF4`,
+`MetalKqGemvIq3xxsF4`, `MetalKqGemvIq2xxsF4`): the whole grid staged into threadgroup memory
+once per threadgroup, pre-expanded to `float4` magnitudes, signs applied by select, so the
+inner loop does no byte extraction. The twin is a PER-BOX CROWN, never a heuristic and never a
+default - it wins on M5-class GPUs and REGRESSES on M1/M4-class, which have less threadgroup
+bandwidth to trade for the byte work. Its PSO compiles only when the box's tune manifest
+carries the crown (`metal_tensor_crowned("kq_gemv_<fmt>_f4")`), and `enc_kq_gemv` picks the
+twin exactly when that PSO is non-null, so a box with no crown never compiles it.
+
+The `kq_gemv_iq3s_f4` and `kq_gemv_iq3xxs_f4` crowns are raced (`race_gemv_f4_twin`).
+`kq_gemv_iq2xxs_f4` cannot be settled by an isolated race at all and is minted from a serving
+A/B instead - `ARCHITECTURE_MEASUREMENT.md` sec.2.21.

modules/dasLLAMA/ARCHITECTURE_GPU_PREFILL.md

@@ -263,3 +263,32 @@ takes it. `DASLLAMA_METAL_LASTROW=0` pins the full-panel tail.
 A caller that consumes the whole `x_b` plane afterwards - embedding pooling, a plane-compare
 probe - sets `Session.keep_hidden` and the prefill keeps every row; the flag is zero-init, so
 narrowing is the default.
+
+### 2.2aa The dense-KQ tensor mul_mm scaffold {#prefill-kq-tensor-scaffold}
+
+Nine iquant and split-scale formats - iq4xs, iq4nl, k3, iq3s, iq3xxs, k2, iq2s, iq2xs, iq2xxs -
+share ONE tensor mul_mm body, `MetalKqMulMmSplitTensorBase`. The base holds the k6 tensor
+shell: the `tmm2d_tg_*` accumulate loop, the 6144-half `twb` W chunk, the store. It exposes
+exactly one overridable stage, `stage16` - 16 elements per work item, decoded into `twb`. A
+format derives, binds its own weight views, and overrides `stage16` alone. 16 is not an
+arbitrary granularity: it is the base GEMV arm's own granularity, so each format's decode ports
+into its `stage16` verbatim, the arm's `va[]` store becoming a `twb` store. This is the shape
+sec.2.2g's MoE tensor twins ride, applied to the dense sites; as there, the q8 twin stays its
+own template because its body is a different staging mechanism.
+
+Each format's `stage16` takes one of three forms, inherited from that format's base GEMV arm:
+
+- **byte-parallel compose** (k3, k2, and the q5 arm of k45) - masked uint-wide shifts produce
+  one `qv` per four elements, with the byte-position shift folded into exact power-of-two
+  pre-scales. It replaced a per-element bit compose and measures 1.4x it
+  (`benchmarks/matmul/bench_metal_kq_race.das --tiers mm`, m5).
+- **staged-grid slab** (iq3s, iq3xxs) - the 2 KB / 1 KB grid staged into threadgroup memory
+  once per threadgroup.
+- **direct constant-table gather** (iq2s, iq2xs, iq2xxs) - the u64 grid pair read straight off
+  the hoisted tables, no slab.
+
+Each format stamps two instances, `T` (`XT = float`) and `TH` (`XT = float16`); this family has
+no tall or double-buffered twins. Every stamp compiles only behind its own crown
+(`metal_tensor_crowned("kq_mulmm_<fmt>")`) in `pf_compile_kq_iquant_tensor_twins`, and
+`pf_enc_kq_site_mm` dispatches a twin only when both the crown flag and the PSO are live, so a
+box with no tensor toolchain never leaves the base kernels.

modules/dasLLAMA/ARCHITECTURE_MEASUREMENT.md

@@ -117,3 +117,42 @@ commit (the remedy `performance/REVIEW.md` allows when the measured `modules/das
 byte-identical) therefore re-hashes and renames the file, and every `records/<box>.json` row
 whose `tune_sha` named the old file is repointed in the same change - a row left on the old
 name points at a file that no longer exists.
+
+### 2.21 An isolated kernel race is only as good as the graph it imitates {#kernel-race-fidelity}
+
+A kernel A/B race times two spellings of one compute on a synthetic fixture. Three conditions
+decide whether its winner is the winner the served graph would pick, and a race missing any of
+them crowns confidently and wrongly:
+
+- **Overlap.** The served graph's consecutive GEMVs write DIFFERENT output buffers, so the
+  scheduler overlaps them. A race chaining every dispatch through one output buffer serializes
+  on the write-after-read hazard; on the iq2xxs f4-slab twin that one difference read +9% for
+  an arm the served graph rejects at -8.6%.
+- **A warmed clock.** An Apple GPU's clock governor ramps under load, and `race_pair_ms` runs
+  base-then-twin per round, so the first side pays the ramp the second rides. About 150 ms of
+  GPU work before the first timed round removes the bias; back-to-back dispatches inside each
+  timed encoder hold the clock there. A sparse invocation without the burn reads idle-clock
+  times and can flip a verdict outright.
+- **A real site shape.** `REVIEW_GPU.md` binds this one.
+
+Even a race meeting all three can be structurally blind. `kq_gemv_iq2xxs_f4` is the standing
+case: every isolated regime crowns the twin and the served decode graph loses 8.6% with it,
+because the effect is mixed-stream occupancy - it exists only when the GEMV runs beside the
+rest of the token step. That crown is therefore NOT auto-raced. It is minted on the real shapes
+by `harness/tune_kernels.das`'s serving confirm: two temporary manifests differing only in
+`runtime.metal_tensor` membership, each served to
+`benchmarks/lcpp_bench.das --for-debug-purposes --ngl 99 -p 32 -n 128 -r 3` under
+`DAS_TUNE_MANIFEST`, the tg128 line the verdict. Both arms carry an EMPTY `kernels` section, so
+they stamp identical fallbacks and the tg delta isolates the crown under test. The margin is
+`CONFIRM_TG_MARGIN` = 1.005, best-of-3: the crown's serving win where it wins is +0.6% (m5) and
+its serving loss where it loses is -8.6% (m4), so the margin only has to clear run noise, and a
+spuriously minted crown costs a re-mint rather than a board row. No IQ2_XXS vehicle on the box
+means no crown - the base kernel is the safe side - and the run says so with a provisioning
+hint.
+
+The per-format isolated rig is `benchmarks/matmul/bench_metal_kq_race.das`: synthetic planes,
+no model, no tuner, every arm gated against a CPU plane-dequant oracle before it is timed, and
+`--burn-ms` (default 150) spent on GPU work before each cell's first timed round. Its cells
+chain every dispatch through ONE shared output buffer on purpose - the serialized regime is
+the instrument's probe shape, imitating the reference tool it is compared against - and its
+numbers reach the engine only through a human porting decision, never a minted crown.

modules/dasLLAMA/ENVIRONMENT.md

@@ -168,6 +168,7 @@ Apple Accelerate / AMX float lane. `DASLLAMA_ACCEL` arms the whole group.
 |---|---|---|---|
 | `DASLLAMA_MODELS_DIR` | path | unset | Directory holding the .gguf models the probes, benches and tests load. dasllama-server's model catalog downloads here too when set. |
 | `DASLLAMA_CONFIRM_MODEL` | path | auto-resolved from the models dir | Model used by the tuner's confirm gate (FULL path, not a bare filename). Unset: the gate auto-resolves from the models dir - the preferred confirm carrier, else the largest present q8 gguf; the fallback pins only when the box has no q8 model at all. |
+| `DASLLAMA_CONFIRM_IQ2XXS` | path | auto-resolved from the models dir | IQ2_XXS vehicle for the tuner's serving-crown confirm (FULL path). Unset: the confirm auto-resolves the first *IQ2_XXS*.gguf in the models dir; none found = no crown (the base kernel serves). |
 | `DASLLAMA_BATCH_CHUNKS` | text | unset | Override the batched-dispatch chunk count in the 1-core GEMM probe. |
 | `DASLLAMA_PROBE_MODEL` | text | Qwen3VL-8B-Instruct-Q8_0.gguf | Model filename (inside the models dir) the image-turn attribution probe loads. |
 | `DASLLAMA_BATCH_GRID_2D` | number | unset | Use the 2D batch grid in the parity probe. |