Skip to content

Commit efa9ba4

Browse files
committed
knowledge: audit h3-metal FastH3 semantic contracts
Add a bounded source-derived procedure and offline declaration preflight for effective configuration, checkpoint transformations and VSA fallback. Preserve native and model validation gaps; integrate packaged discovery and assertion-backed cases. Agent-assisted-by: Codex / gpt-6.1-sol [effort=xhigh] (author) Signed-off-by: Codex <codex@openai.com>
1 parent 1cd516b commit efa9ba4

35 files changed

Lines changed: 1765 additions & 17 deletions

‎docs/knowledge-base.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ separate work, not an implemented capability of this knowledge base.
1414
```text
1515
src/inferrsi/data/skill_library/
1616
README.md Library navigation
17-
skill-index.json Stable IDs → categorized paths/backend (71 skills)
17+
skill-index.json Stable IDs → categorized paths/backend (72 skills)
1818
hardware/{ascend,cuda,host}/<id>/ Hardware/platform-specific complete skills
1919
frameworks/<framework>/<id>/ Framework-owned complete skills
2020
repositories/<repo>/ Engine entry, sub-skills and focused complete skills
@@ -171,18 +171,18 @@ Complete procedures, sidecars, references and cases are packaged, with 13 Ascend
171171
repositories, methods or workflows. The 21 engine and research-router skills
172172
use the same ownership layout under `repositories/<engine>/` and
173173
`workflows/inference-engine-research/`, including their sub-skills and references.
174-
The library contains 115 `SKILL.md` files, all in English.
174+
The library contains 116 `SKILL.md` files, all in English.
175175
The collection overview, import notes and source manifest belong to the research
176176
workflow's references; Strata design-space analysis belongs to Strata. The library
177177
root contains only navigation and the registry.
178178

179179
The [generated catalog](../src/inferrsi/data/repo_packs/inferrsi/knowledge/README.md)
180-
projects the 71 registered skills into the contribution catalog. Its records
180+
projects the 72 registered skills into the contribution catalog. Its records
181181
use `inferrsi.<backend>.skills.<name_with_underscores>` IDs, with `ascend` and
182182
`cuda` for scopes that depend on those backends and `common` for the remaining skills.
183183
Each `skill_documents.original` points to the full packaged procedure. The
184184
`skills` CLI retains the original hyphenated skill IDs and defaults to this
185-
71-ID registry; engine procedures remain available through library navigation
185+
72-ID registry; engine procedures remain available through library navigation
186186
and catalog document pointers.
187187

188188
The registered [h3.c runtime audit](../src/inferrsi/data/skill_library/repositories/h3-c/audit-h3-runtime-residency/SKILL.md)
@@ -271,3 +271,5 @@ The registered [mistral-rs candidate](../src/inferrsi/data/skill_library/reposit
271271
The [mlx-swift-lm candidate](../src/inferrsi/data/skill_library/repositories/mlx-swift-lm/SKILL.md) owns selected Swift generation-lifetime and recurrent native/ops contracts, with source/observation limits preserved. No Swift compile, original native/host-control test, actual Metal/model/quality/service run is implied by its helpers or packaged discovery.
272272

273273
The [mlc-llm candidate](../src/inferrsi/data/skill_library/repositories/mlc-llm/SKILL.md) separates artifact metadata, supported consumers, Apple targets, pinned TVM runnable/runtime boundaries and compiled/runtime KV configuration. Canonical hashes, serializable fallback or estimated limits are not native/model/quality/fit/service evidence.
274+
275+
The registered [h3-metal FastH3 audit](../src/inferrsi/data/skill_library/repositories/h3-metal/audit-h3-metal-fasth3-semantics/SKILL.md) supplements earlier h3.c residency with fork-specific effective configuration, tensor/schedule semantics and VSA eligibility/fallback. Its offline declaration arithmetic and label probes do not qualify native conversion, sparse attention, media, memory fit or performance; required Apple/model evidence remains blocked/not_run.

‎docs/reference-matrix.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ Reading rules:
4444
|---|---|---|---|---|---|---|
4545
| NVlabs/kda @ `acdd79343c5e9d0c7cb96289f26fd3f1051ce785` → mit-han-lab/KernelWiki gitlink @ `76d27b56f804e7e7295d4c570e1e5d7eef4b0a75` | Direct bounded distillation, 2026-10-23; cutoff 2026-04-27. All 48 synthesis headers and 2,217 source headers screened; 171 SM90 source headers retained, selected bodies and independently matched DeepGEMM/CUTLASS code plus versioned NVIDIA sections inspected. [Readset/coverage/license qualifications](../src/inferrsi/data/skill_library/hardware/cuda/reason-hopper-kernels/references/sources.md); remaining PR bodies/algorithms unmined; KW pin has no root LICENSE, KDA MIT/sanitization assertions qualified | mined (conditional) — Hopper TMA/mbarrier/WGMMA ownership, resource/layout/pipeline/software scheduling and selected FP8 scaling → [reason-hopper-kernels](../src/inferrsi/data/skill_library/hardware/cuda/reason-hopper-kernels/SKILL.md); SM100 recipes and unsafe snippet generalizations excluded; native/precision/performance not_run | out-of-scope — device registers/SMEM/HBM are not host RAM | out-of-scope — no storage implementation extracted | out-of-scope — CTA/cluster synchronization is not network transport | out-of-scope — tile scheduling is not OS scheduling |
4646
| antirez/h3.c @ `8974cc055ea9c02fcd14cc27dfda3e1027c05153` (MIT; retained ccv BSD-3-Clause notice) | Direct bounded source distillation, 2026-10-23; 34 selected file bytes matched to pinned Git blobs; [readset/architecture](../src/inferrsi/data/skill_library/repositories/h3-c/audit-h3-runtime-residency/references/source-notes.md). Loader, generation/cache, TE/vision/input-output VAEs, AdaLN, selected Metal/int8/SSD paths and native test assertions; full kernels/driver/media internals unread. Prior model-header observations reused, not rerun | mined — joint audio/video schedule and row-map dependencies, BF16 rounding/fusion versus numerical approximation, actual TensorOps dispatch → [audit-h3-runtime-residency](../src/inferrsi/data/skill_library/repositories/h3-c/audit-h3-runtime-residency/SKILL.md); native/quality/performance not_run | mined — shared/file-backed weights, Qwen prefetch ring, phase/cache/preview overlap and complete host output; tensor counters are not physical footprint or 64 GiB qualification | mined — exact raw BF16/F32 schema, direct/mapped reads and two-slot BF16 matrix streaming with completion/join boundaries; uncached-read request is not measured cache bypass or useful overlap | out-of-scope — local GPU/I/O ordering is not network transport | out-of-scope — no OS scheduling/control implementation extracted |
47+
| zuiho-kai/h3-metal @ `4ba47a3eabdbebf801ac6664b31f8ec168bc57a8` (inspected MIT; retained BSD-3-Clause notice; machine resolver unavailable) | Bounded source distillation, 2026-10-28; 21 identity-checked files with selected ranges; [scope/readset](../src/inferrsi/data/skill_library/repositories/h3-metal/audit-h3-metal-fasth3-semantics/references/source-notes.md). Fork-specific FastH3 params, tensor/schedule/RoPE and VSA dispatch, test/script limits; full engine/external FastVideo/model surface not mined | mined — requested versus effective controls, ambient conflicts, head-interleaved QKV/FC1 swap/BF16 schedule, real partial VSA tiles/double top-k and dense-plus-coarse fallback → [audit-h3-metal-fasth3-semantics](../src/inferrsi/data/skill_library/repositories/h3-metal/audit-h3-metal-fasth3-semantics/SKILL.md); native/numerical/quality/performance not_run | out-of-scope — tile arithmetic is not measured host footprint or memory-fit qualification | out-of-scope — FastH3 disables requested SSD parameter; no new storage optimization or payload validation | out-of-scope — local attention/dispatch is not network transport | out-of-scope — runtime selection is not OS scheduling |
4748
| Comfy-Org/ComfyUI @ `b1a247c9cf9dbfda4b2c0a0c1d50950667eeaa0c` (GNU GPL v3) | Source-reading archive, inspected 2026-10-21; bounded execution/cache/graph/model-management/static-dynamic-patcher/sampler paths and selected tests; [readset](../src/inferrsi/data/skill_library/repositories/comfy-ui/references/repo-provenance.md); not full-model/custom-node/provider-native coverage | mined — managed weight/patch identity, partial unload versus detach and dynamic-backend boundary → [comfy-ui](../src/inferrsi/data/skill_library/repositories/comfy-ui/SKILL.md); device behavior unverified | mined — output versus object identity, ancestor fingerprints, lazy consumer references and retention versus validity; host/pin ownership | out-of-scope — no storage implementation extracted | out-of-scope — no transport implementation extracted | out-of-scope — workflow scheduling is not OS scheduling |
4849
| leejet/stable-diffusion.cpp @ `b13a48219d5cdf408edcb93da6cd69b612ed03d3` (MIT) | Supplied archive, inspected 2026-10-22: 18 bounded paths plus separately identity-checked README (19 blobs); historical receipt preserved. 2026-10-23 extension: 12 selected C++ blobs plus retained MIT text identity-checked, with line-scoped catalog/non-ZIP safetensors read/staging/mapping and immediate consumer cleanup; [readsets](../src/inferrsi/data/skill_library/repositories/stable-diffusion-cpp/audit-sd-cpp-residency/references/source-notes.md). File identity is not full-file review; archive/submodules, model kernels and other-format implementations remain outside the bounded audit | mined — native weight/runtime capacity, protected segment/prefetch lifetime → [audit-sd-cpp-residency](../src/inferrsi/data/skill_library/repositories/stable-diffusion-cpp/audit-sd-cpp-residency/SKILL.md); native/backend behavior unverified | mined — parameter storage versus compute staging and retained runtime ownership; loader host read/conversion buffers versus mapped owners; host peaks unmeasured | mined — bounded catalog stamps versus content identity, range admission versus actual reads, mapping/shared-owner and newly created block cleanup → [loader/storage boundaries](../src/inferrsi/data/skill_library/repositories/stable-diffusion-cpp/audit-sd-cpp-residency/references/loader-storage-boundaries.md); full other-format parsing, native failure/SSD/performance qualification remain open | out-of-scope — device copies are not network transport | out-of-scope — runner scheduling is not OS scheduling |
4950
| NVIDIA/TensorRT-LLM @ f33e0e5fd | skill-doc-only (`.claude/skills/`) | mined — evidence taxonomy, kernel writing, casebook, roofline refs → `dense-performance-evidence`, `kernel-writing-guide`, `inference-optimization-casebook`, `performance-ceiling-analysis` | mined — host overhead verdict + line-profiling loop → `host-overhead-profiling`, `host-overhead-optimization` | mined — weight-movement/overlap + KV host-cache patterns → `weight-loading-optimization`; disk-level: negative (see below) | out-of-scope — host/device weight-movement overlap remains in RAM/Storage, not network coverage | mined — CPU affinity rule + env preflight → `os-process-placement` |

‎docs/searchspace-matrix.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ The primary compute and HBM resource. Most current work lives here.
2828
|---|---|---|---|---|---|
2929
| **Diagnose / Configure / Verify** | CUDA eager dense-FFN Attention/FFN rank namespaces and per-stage/per-peer hidden-state ownership | [audit-afd-p2p-exchanges](../src/inferrsi/data/skill_library/repositories/afd-plugin/audit-afd-p2p-exchanges/SKILL.md) | A=3,F=2 control sender differs from data peer; matching total tokens does not preserve peer rows | afd-plugin @ df8d6a0c403c3ca1b4ed9cf1687e7204908bebec; [source ledger](../src/inferrsi/data/skill_library/repositories/afd-plugin/audit-afd-p2p-exchanges/references/source-notes.md), [proposed cases](reviews/issue91-afd-p2p.md) | 🟢 (source-derived candidate; native/model/efficacy not_run; no Network qualification) |
3030
| **Observe / Diagnose / Verify** | MiniMax-H3 joint audio/video AdaLN schedule/row-map validity, Metal BF16 rounding and actual int8 dispatch versus approximate controls | [audit-h3-runtime-residency](../src/inferrsi/data/skill_library/repositories/h3-c/audit-h3-runtime-residency/SKILL.md) | Fifty layers/reuse 1 does not disable M5 int8 or BF16 head; test-source parity is not full media quality | h3.c @ 8974cc055ea9c02fcd14cc27dfda3e1027c05153; [precision contracts](../src/inferrsi/data/skill_library/repositories/h3-c/audit-h3-runtime-residency/references/precision-and-streaming.md) | 🟢 (source-derived candidate; native/quality/performance not_run) |
31+
| **Observe / Diagnose / Verify** | FastH3 effective parameters/ambient override, semantic checkpoint transformations, partial/prefix VSA membership and sparse eligibility/fallback | [audit-h3-metal-fasth3-semantics](../src/inferrsi/data/skill_library/repositories/h3-metal/audit-h3-metal-fasth3-semantics/SKILL.md) | Shape agreement is not conversion; sparse-disabled remains dense fine+coarse; parameter normalization does not erase ambient token enable | h3-metal @ 4ba47a3eabdbebf801ac6664b31f8ec168bc57a8; [semantic counterchecks](../src/inferrsi/data/skill_library/repositories/h3-metal/audit-h3-metal-fasth3-semantics/references/semantic-contracts.md) | 🟢 (source-derived candidate; native/sparse/schedule/media/performance not_run) |
3132
| **Diagnose / Configure / Verify** | Workflow model-weight residency, partial unload versus wrapper removal, patch identity and static/dynamic backend dispatch | [comfy-ui](../src/inferrsi/data/skill_library/repositories/comfy-ui/SKILL.md) | CPU dynamic construction reroutes to the static patcher; wrapper/free-byte bookkeeping is not physical allocator release | ComfyUI @ b1a247c9cf9dbfda4b2c0a0c1d50950667eeaa0c; [model ownership](../src/inferrsi/data/skill_library/repositories/comfy-ui/references/model-residency.md) | 🟢 (source-derived audit; device/native allocator unverified) |
3233
| **Observe / Diagnose / Verify** | Native diffusion managed budget versus device headroom, graph-segment weight protection and optional prefetch completion | [audit-sd-cpp-residency](../src/inferrsi/data/skill_library/repositories/stable-diffusion-cpp/audit-sd-cpp-residency/SKILL.md) | CPU bypasses accelerator capacity and segmentation gates; pin release is not physical free; backend capability does not prove overlap | stable-diffusion.cpp @ b13a48219d5cdf408edcb93da6cd69b612ed03d3; [phase residency](../src/inferrsi/data/skill_library/repositories/stable-diffusion-cpp/audit-sd-cpp-residency/references/phase-residency.md) | 🟢 (source-derived audit; native/device/model unverified) |
3334
| **Observe / Profile** | System-level GPU/NPU timeline, per-kernel stats, SOL%, AI Core utilization ratios, step-trace four-tuple | `ascend-performance-analysis`, `dense-performance-evidence` (L2) | CANN CSV pipeline, MindIE-SD profiling-analyze lessons | MindIE-SD @ 8481d39b; TRT-LLM nsys/ncu @ f33e0e5f | 🟢 |

‎src/inferrsi/data/skill_library/README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# InferRSI skill library
22

3-
The English-only library contains **115 skill documents**: 71 registered roots,
3+
The English-only library contains **116 skill documents**: 72 registered roots,
44
21 separately indexed engine/router documents and 23 AREX graph sub-skills.
55
Complete procedures, metadata, references, cases and source notices ship with the package.
66

@@ -20,7 +20,7 @@ existing resource directory.
2020

2121
## Read registered skills
2222

23-
[`skill-index.json`](skill-index.json) maps 71 stable skill IDs to their canonical
23+
[`skill-index.json`](skill-index.json) maps 72 stable skill IDs to their canonical
2424
paths and backend scopes. Install the optional `skills` extra for these commands:
2525

2626
```bash
@@ -125,7 +125,7 @@ guidance; it establishes no cross-pin implementation compatibility.
125125

126126
Five repository entry skills, 15 focused sub-skills and one research router
127127
provide source-grounded procedures. These 21 documents are available through
128-
the links and catalog records below, separately from the 71-ID registry.
128+
the links and catalog records below, separately from the 72-ID registry.
129129
The registered ComfyUI and stable-diffusion.cpp audits are listed alongside
130130
these imports and use generated abstracts rather than runtime repository packs.
131131

@@ -134,6 +134,7 @@ these imports and use generated abstracts rather than runtime repository packs.
134134
| ComfyUI source audit | Workflow-output cache validity and model-weight residency; source-derived candidate | [Skill](repositories/comfy-ui/SKILL.md) | [Record](../repo_packs/inferrsi/knowledge/common/skills/comfy-ui.json) |
135135
| stable-diffusion.cpp source audit | Native image weight/runtime capacity and protected segment prefetch; source-derived candidate | [Skill](repositories/stable-diffusion-cpp/audit-sd-cpp-residency/SKILL.md) | [Record](../repo_packs/inferrsi/knowledge/common/skills/audit-sd-cpp-residency.json) |
136136
| h3.c / MiniMax-H3 source audit | Conditioning, AdaLN precompute, phased/cached residency, precision and BF16 SSD streaming; source-derived candidate | [Skill](repositories/h3-c/audit-h3-runtime-residency/SKILL.md) | [Record](../repo_packs/inferrsi/knowledge/common/skills/audit-h3-runtime-residency.json) |
137+
| h3-metal / FastH3 semantic audit | Effective parameters and ambient overrides, tensor/schedule transformations, VSA prefix/partial tiles and fallback; source-derived candidate | [Skill](repositories/h3-metal/audit-h3-metal-fasth3-semantics/SKILL.md) | [Record](../repo_packs/inferrsi/knowledge/common/skills/audit-h3-metal-fasth3-semantics.json) |
137138
| AFD plugin P2pNccl audit | CUDA eager dense-FFN rank namespaces and per-stage/per-peer payload ownership; source-derived candidate | [Skill](repositories/afd-plugin/audit-afd-p2p-exchanges/SKILL.md) | `inferrsi.cuda.skills.audit_afd_p2p_exchanges` |
138139
| vLLM-RLT source audit | Synchronous early-exit KV propagation, later deeper attention and normal storage retirement; source-derived candidate | [Skill](repositories/vllm-rlt/audit-recurrent-kv-finalization/SKILL.md) | [Record](../repo_packs/inferrsi/knowledge/common/skills/audit-recurrent-kv-finalization.json) |
139140
| Strata | Heterogeneous MoE, placement, memory and speculative execution | [Skill](repositories/strata/SKILL.md) | [Records](../repo_packs/strata/knowledge/README.md) |
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Salvatore Sanfilippo
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)