Merge pull request #151 from AdaWorldAPI/claude/v3-substrate-migration-review-o0yoxv

canon: retire the V1 u24+u24 GUID tail — migration mandatory

Author: AdaWorldAPI

CLAUDE.md

@@ -6,9 +6,27 @@
 
 ## P0 — THE CANONICAL GUID (operator-pinned; counted in HEX, not bits)
 
+> **⊘ SUPERSEDED — MIGRATION MANDATORY (operator, 2026-07-04).** The flat
+> `family-basin-leaf(6) + identity(6)` tail below — two contiguous **u24**
+> bit-groupings (`family:u24 ++ identity:u24`) — is **V1-LEGACY and forbidden
+> for new units.** Every new unit is the V3 **content-blind 4+12 facet**
+> (`E-V3-FACET-4-PLUS-12`, lance-graph `soa_layout/le-contract.md` §3,
+> operator-locked 2026-07-02): `classid(4) + 12-byte payload`, the 12 bytes an
+> **axis-grouped byte register** — `6×(u8:u8)` / `4×(u8:u8:u8)` / `3×(u8:u8:u8:u8)`
+> — whose reading (`part_of:is_a` / `X:Y` / `palette256:palette256` /
+> `segment:taxonomy` / typed content) the **classid's ClassView holds all at once**
+> and picks per read. `u8:u8` stays two separate bytes — **never widened to u16
+> or u24.** A flat u24 has **no axis** and cannot carry a rail; that is why it is
+> retired. Append-only: the pin is NOT deleted — the u24 tail stays **read-only for
+> pre-flip GUIDs**, regraded V1-legacy in place. Producer already V3 in code:
+> `ruff_spo_address::Facet` (`facet_classid:u32 + 6×FacetTier{lo:u8,hi:u8}`) via
+> `ogar-from-ruff` mint/emit. Paired follow-ups (mandatory): promote
+> `docs/V3-TRANSPILER-ADR.md` RFC→adopted; reconcile `ogar-fma-skeleton::Guid`
+> classid 2→4 (F-2); invert `docs/NODEGUID-CANON-AUDIT.md` F-3 (see its dated note).
+
 ```
 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-classid    HEEL   HIP    TWIG   family-basin-leaf(6) + identity(6)
+classid    HEEL   HIP    TWIG   family-basin-leaf(6) + identity(6)  ← V1-LEGACY tail (read-only; new units use the V3 4+12 facet, above)
 8 hex      4 hex  4 hex  4 hex  12 hex
 ```
 

docs/DISCOVERY-MAP.md

@@ -130,6 +130,7 @@ two halves of a cell. ADR‑026 names the cascade that ties them.
 | D‑FMA‑SKELETON | FMA skeleton = the **clamped convergence anchor**: ~206 bones as immutable **16×8‑bit Morton‑tile family‑node** addresses derived from rest‑pose centroids ⟹ prefix = partonomy = spatial containment (D‑BOTHCASC realized); bones are non‑negotiable Dirichlet anchors, the cross‑modal frame ViT / X‑ray / ultrasound × Doppler register onto. Address structure CODED; splat‑fit convergence CONJECTURE. | G (structure) / H (convergence) | CODED | `crates/ogar-fma-skeleton` + `docs/FMA-SKELETON-CONVERGENCE-ANCHOR.md` | D‑MORTON; `SPLAT-NATIVE-CUSTOMER.md` §6 |
 | D‑GUID‑TIER | The brutal uniform **`[256:256]` `[container:member]`** GUID (scale‑free: galaxy:planet … residue:atom); HhtlMode **Located** (Cesium 3D‑octree CRS) vs **Cascade** (self‑speaking ontology path); leaf = familyNode:identity. 3D‑octree HEEL/HIP (`morton3`), the ModalityProjection contract (ViT/X‑ray/US×Doppler `register`+`project` by Guid). 12+4 EdgeBlock removed (superseded by family nodes). | G | CODED | `crates/ogar-fma-skeleton/{guid,morton,projection}.rs` | D‑FMA‑SKELETON, D‑MORTON |
 | D‑NODEGUID‑AUDIT | Group‑by‑group audit of the FMA tier `Guid` vs lance‑graph `NodeGuid` (canon rule: wrappers audited against OGAR). **Caught F‑1: lance‑graph `CLASSID_FMA=0x0901` aliases OGAR `patient`** — this session's `0x0A` Anatomy domain resolves it. Also: classid/family/identity width + endianness + EdgeBlock divergences, each with a reconciliation. | G | CODED | `docs/NODEGUID-CANON-AUDIT.md` | D‑GUID‑TIER; lance‑graph `canonical_node.rs` |
+| D‑V1‑TAIL‑RETIRED | **MIGRATION MANDATORY (operator, 2026‑07‑04):** the flat `family:u24 ++ identity:u24` V1 tail is **FORBIDDEN for new units.** V3 is the content‑blind `classid(4) + 12B` facet — 12B an axis‑grouped register (`6×(u8:u8)` / `4×(u8:u8:u8)` / `3×(u8:u8:u8:u8)`), the ClassView holds every reading at once (`part_of:is_a` / `X:Y` / `palette256²` / `segment:taxonomy` / typed) and `u8:u8` is **never widened** (u16 = the deprecated V2 flat read; u24 = V1). A flat u24 has no axis → cannot carry a rail. Append‑only: u24 stays read‑only for pre‑flip GUIDs. Producer already V3: `ruff_spo_address::Facet` via `ogar‑from‑ruff`. Regrades D‑NODEGUID‑AUDIT F‑3; pin superseded in `CLAUDE.md` P0. | G | RULING | `CLAUDE.md` P0 (regraded) + `docs/NODEGUID-CANON-AUDIT.md` F‑3 (inverted) + `docs/V3-TRANSPILER-ADR.md` | D‑NODEGUID‑AUDIT; D‑GUID‑TIER; lance‑graph `E‑V3‑FACET‑4‑PLUS‑12` |
 
 ### 2.2 Selection & bounds
 

docs/NODEGUID-CANON-AUDIT.md

@@ -78,6 +78,26 @@ byte), not the *shape*. **Reconciliation:** make the family:identity split a
 ratified, the FMA `Guid` is a constrained projection of the canon, not a
 replacement.
 
+> **⊘ REGRADE — MIGRATION MANDATORY (operator, 2026-07-04). F-3 inverts.** The
+> framing above — "the u24 tail is the canon; the byte-direct is a constrained
+> projection, not a replacement" — is **superseded**. Per the operator ruling and
+> `E-V3-FACET-4-PLUS-12` (operator-locked 2026-07-02), the **byte-grouped facet IS
+> the canon and the flat `u24 ++ u24` tail is V1-LEGACY, forbidden for new units.**
+> V3 is content-blind: `classid(4) + 12-byte payload` as an axis-grouped register —
+> `6×(u8:u8)` / `4×(u8:u8:u8)` / `3×(u8:u8:u8:u8)`, the ClassView holds every
+> reading at once (`part_of:is_a` / `X:Y` / `palette256²` / `segment:taxonomy` /
+> typed) and `u8:u8` is **never widened**. So the "gap is only per-field width
+> (u16 vs byte)" reading is wrong twice over: (a) the go-forward width is the
+> **byte** (u8:u8 pair), not u16 (u16 is the deprecated V2 flat read); (b) a flat
+> u24 has **no axis** and cannot carry a rail — it is not a width variant of the
+> facet, it is a different (retired) shape. The class-local carve intuition (F-3
+> "make the split a per-classid property") survives and is *exactly right* — but it
+> is the **ClassView projecting the content-blind (u8:u8) register per classid**,
+> not a u24 width knob. Reconciliation is now MANDATORY, not "until ratified":
+> `ogar-from-ruff` already mints the V3 facet (`ruff_spo_address::Facet`);
+> `ogar-fma-skeleton::Guid` classid 2→4 (F-2) is the remaining code delta. Canon
+> pin regraded in `CLAUDE.md` P0 (dated 2026-07-04, append-only).
+
 ### F-4 — `[G]` **endianness: FMA tiers are container-first (big-endian); canon is LE throughout.**
 
 `Guid::classid()` reads `(bytes[0] << 8) | bytes[1]`, so `0x0A03` stores as