cortiq
cmf
infosave commited on
Commit
1a0c6c0
·
verified ·
1 Parent(s): 01afbe6

spec: LOOP_MASKS (bit 5) + SKILL_FILE (bit 6) + §9.1 standalone skill files

Browse files
Files changed (1) hide show
  1. SPEC.md +40 -3
SPEC.md CHANGED
@@ -79,6 +79,8 @@ no "read as best we can").
79
  | 2 | `QUANT_2F` | directory contains `q8_2f`/`vbit` tensors (two-field 𝒲×θ quant) |
80
  | 3 | `DELTA_MASKS` | reserved: XOR mask deltas from a parent |
81
  | 4 | `HOT_PACKS` | reserved: materialized dense slices |
 
 
82
 
83
  Unknown **header-JSON** fields are ignored (additive evolution);
84
  breaking changes go only through feature bits or a `version` bump.
@@ -572,6 +574,41 @@ offsets of previously written tensors never change; old dir/header bytes
572
  become dead section tails (compatible: readers navigate only through the
573
  envelope). Compaction (`converter/cmf_compact.py`) = a plain rewrite.
574
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
575
  Status: fully implemented and gated (container + indirection,
576
  production recipes, recon-argmin routing, append-only + compaction,
577
  soft-blend); claim 16 met by measurement (−24.9% task-PPL in the
@@ -615,7 +652,7 @@ file. Errors: opening a non-first shard directly, a missing sibling, a
615
  Gate (Qwen3.5-0.8B q8_2f, 5 shards ≤ 0.6 GB): sharded PPL == unsharded
616
  byte-exactly on the same binary; `verify` green on every shard alone.
617
 
618
- ## 11. Defragmentation — physical pruning (USPTO App. 19/452,464, claims 9/10 — [PATENTS.md](https://github.com/infosave2007/cmf/blob/master/PATENTS.md))
619
 
620
  A mask (§5) is **virtual sparsity**: pruned neurons are flagged but still
621
  stored in full (all tasks share one backbone — you cannot physically cut
@@ -766,7 +803,7 @@ discrete cards and phones).
766
 
767
  ---
768
 
769
- *Related: [COMPARISON.md](https://github.com/infosave2007/cmf/blob/master/docs/COMPARISON.md) (CMF vs. other model formats),
770
- [project README](https://github.com/infosave2007/cmf/blob/master/README.md) (overview and quick start),
771
  `python/cmf_reader.py` (standalone reader: stdlib + numpy, reads every
772
  dtype, shards, skills, verify).*
 
79
  | 2 | `QUANT_2F` | directory contains `q8_2f`/`vbit` tensors (two-field 𝒲×θ quant) |
80
  | 3 | `DELTA_MASKS` | reserved: XOR mask deltas from a parent |
81
  | 4 | `HOT_PACKS` | reserved: materialized dense slices |
82
+ | 5 | `LOOP_MASKS` | mask rows are per VISIT (physical layers × loops, pass-major) — a Looped Transformer's two passes carry independent masks (§5.1) |
83
+ | 6 | `SKILL_FILE` | the file is a STANDALONE SKILL: a partial tensor set cut against a specific base, bound by `SkillRecord.base_dir_hash` (§9.1). Not runnable — attach with `cortiq skill apply` |
84
 
85
  Unknown **header-JSON** fields are ignored (additive evolution);
86
  breaking changes go only through feature bits or a `version` bump.
 
574
  become dead section tails (compatible: readers navigate only through the
575
  envelope). Compaction (`converter/cmf_compact.py`) = a plain rewrite.
576
 
577
+ ### 9.1 Standalone skill files (`SKILL_FILE`, bit 6)
578
+
579
+ A skill can also travel WITHOUT its backbone: a `.cmf` whose tensor set
580
+ is only what a bake changed (plus the mask catalog), bound to the base
581
+ it was cut against by identity keys in the registry record:
582
+
583
+ ```json
584
+ "skills": [{
585
+ "id": "gfx-html",
586
+ "layers": [0, 1, "...", 21],
587
+ "base_dir_hash": "9f22593eb458bc6f",
588
+ "base_arch": "nanbeige",
589
+ "task": "specialist",
590
+ "provenance": {"corpus": "…", "tensors": 30}
591
+ }]
592
+ ```
593
+
594
+ - `base_dir_hash` — hex `hash64` of the BASE file's tensor-directory
595
+ bytes (the same value the envelope carries at `[0x78]`). A skill is a
596
+ delta against exact bytes, not against an architecture: `apply` MUST
597
+ refuse a base whose directory hash differs (an explicit `--force`
598
+ may override; the result is out of spec).
599
+ - `base_arch`, `task`, `provenance` — informative keys: the human check,
600
+ the mask-catalog task the skill activates, and where it came from.
601
+
602
+ Any record with `base_dir_hash` present raises feature bit 6, so a
603
+ pre-bit reader refuses the file loudly and a runtime that knows the bit
604
+ refuses to RUN it (a partial tensor set is not a model) and points to
605
+ `cortiq skill apply <base> <skill> -o out.cmf`, which verifies the key,
606
+ overlays tensors and masks over the base, and writes a complete file —
607
+ byte-equivalent to the specialist the skill was cut from.
608
+
609
+ Lifecycle: `skill bake` (specialist) → `skill export --base` (delta +
610
+ keys) → publish the small file → `skill apply` on any copy of the base.
611
+
612
  Status: fully implemented and gated (container + indirection,
613
  production recipes, recon-argmin routing, append-only + compaction,
614
  soft-blend); claim 16 met by measurement (−24.9% task-PPL in the
 
652
  Gate (Qwen3.5-0.8B q8_2f, 5 shards ≤ 0.6 GB): sharded PPL == unsharded
653
  byte-exactly on the same binary; `verify` green on every shard alone.
654
 
655
+ ## 11. Defragmentation — physical pruning (USPTO App. 19/452,464, claims 9/10 — [PATENTS.md](../PATENTS.md))
656
 
657
  A mask (§5) is **virtual sparsity**: pruned neurons are flagged but still
658
  stored in full (all tasks share one backbone — you cannot physically cut
 
803
 
804
  ---
805
 
806
+ *Related: [COMPARISON.md](COMPARISON.md) (CMF vs. other model formats),
807
+ [project README](../README.md) (overview and quick start),
808
  `python/cmf_reader.py` (standalone reader: stdlib + numpy, reads every
809
  dtype, shards, skills, verify).*