feat(contract): NodeGuid — structured 128-bit identity (Phase A, D-IDENTITY-1)

The workspace's first stable binary instance identity: a UUIDv8 (RFC 9562)
that formalizes + namespaces the HHTL nibble-address. Composed entirely from
existing committed scalars (the 128-bit id space was empty per the Agent A
sweep): SchemaPtr.packed convention (ns8|entity_type16|kind8) + a truncated
NiblePath routing prefix + a 22-bit shape_hash + a 24-bit local, with the
UUIDv8 version/variant at their RFC-fixed positions and a layout-version stamp.

Eineindeutigkeit (ratified): entity_type:u16 is the canonical exact class
identity; the NiblePath prefix is the bijective DERIVED view (a truncated
prefix can't be the identity -- deep classes collide past it; the prefix
is_ancestor_of the full path, tested). Five readings: resolve / route /
witness / ground-truth / dispatch-to-store (as_bytes -> EntityKey).

- new: identity.rs (NodeGuid + 15 tests: field-isolation matrix, UUIDv8
  version/variant gates, ancestor-prefix invariant, canonical-UUID Display).
- new: NiblePath::from_packed (inverse of packed()).
- 599 contract lib tests (+15), clippy -D warnings clean, fmt clean.
- board: LATEST_STATE inventory, EPIPHANIES E-IDENTITY-WHITEBOX-1, AGENT_LOG,
  decision-1 RESOLVED in the exists-vs-needs plan.

https://claude.ai/code/session_014A4JuRCqKP2yNENrQ9Ha7H

Author: claude

.claude/board/AGENT_LOG.md

@@ -1,3 +1,12 @@
+## 2026-06-09 — D-IDENTITY-1 (Phase A) + 2 cross-repo sweeps — identity-architecture
+
+**Orchestrator:** Opus main thread (autoattended). **Outcome:** Shipped Phase A.
+- **Sweep A** (Opus general-purpose): lance-graph + ndarray identity-type inventory → the 128-bit identity space is EMPTY (only `[u8;16]` is `atoms::I4x32`, a style vector); every GUID field already exists as a committed scalar → compose-don't-reinvent.
+- **Sweep B** (Opus general-purpose): MedCare-rs + smb-office-rs store keys → `EntityKey(&[u8])` already carries any-length keys (smb-bridge `key_to_filter` length-branches on Mongo+Lance); transport solved. MedCare needs one `external_ref` (or reuse DMS `sha256`); smb maps directly.
+- **Phase A:** `lance_graph_contract::identity::NodeGuid` (UUIDv8, composed from SchemaPtr⊕NiblePath⊕StructuralSignature⊕local) + `NiblePath::from_packed`. 599 contract lib tests (+15), clippy `-D` clean, fmt clean.
+
+Plans: `identity-architecture-exists-vs-needs-v1.md`, `cognitive-write-roundtrip-substrate-v1.md`. Epiphany: E-IDENTITY-WHITEBOX-1.
+
 ## [Opus 4.8, main thread] cesium-osm-substrate-v1 review fix — D-OSM-2 crate boundary (codex P2 on merged #473)
 
 **Branch:** `claude/osm-pbf-consumer-boundary-fix` (off `main`). **New follow-up PR** (merged #473 review-fix, surfaced for visibility per user request; the other session owns the OGAR-side fixes).

.claude/board/EPIPHANIES.md

@@ -1,3 +1,39 @@
+## 2026-06-09 — E-IDENTITY-WHITEBOX-1 — structured identity + round-trip converts the substrate from black-box to CI-falsifiable
+
+**Status:** FINDING (Phase A landed: `identity::NodeGuid` composed, 15 tests green)
+**Confidence:** High
+
+**The synthesis:** a structured 128-bit immutable identity (UUIDv8 = the HHTL
+nibble-address formalized + namespaced) PLUS the `roundtrip_eq` guarantee turn the
+substrate from a black box into a CI-falsifiable surface. Two structural witnesses:
+the **bijection** (`entity_type ↔ NiblePath`, proven eineindeutig at build time)
+and **`roundtrip_eq`** (a lossy projection fails CI, not code review). The
+round-trip whitens the PLUMBING (identity / LE byte-contract / member-vs-container)
+— the darkest, most-expensive-bug layer; it does NOT whiten semantics (needs
+ground-truth corpora) or the lossy codec (needs ρ-certification). Those keep their
+own witnesses; the trade is "vigilance over the substrate" → "a test over the substrate".
+
+**Compose, don't re-invent (Agent A sweep):** the 128-bit identity space is empty
+(no committed `u128`/`Uuid`/`[u8;16]`-as-id), but every GUID field already exists as
+a committed scalar — `SchemaPtr.packed` (ns8|entity_type16|kind8) ⊕ `NiblePath`
+prefix ⊕ truncated `StructuralSignature` ⊕ local. `NodeGuid` is their composition.
+
+**Eineindeutigkeit (ratified):** `entity_type:u16` is the canonical exact class
+identity; `NiblePath` is the bijective DERIVED view (a *truncated* prefix can't be
+the identity — deep classes collide past it, `hhtl.rs`). The registry mints the
+pair 1:1; a build-time bijection round-trip proves it; the GUID prefix-consistency
+invariant (`prefix == niblepath_of(entity_type)[..N]`) catches drift.
+
+**Free side-effects:** the structured GUID is also (a) a KV key via the existing
+`EntityKey(&[u8])` (smb-bridge already length-branches it), and (b) a **quadkey** —
+Lance ORDER BY the NiblePath gives subtree range-scans = zone-map-pruned byte
+ranges, no index (ADR-024 "HHTL prefix establishes a frame").
+
+**Landed:** `lance_graph_contract::identity::NodeGuid` (D-IDENTITY-1 / Phase A) +
+`NiblePath::from_packed`. 599 contract lib tests (+15), clippy `-D` clean, fmt clean.
+Plans: `identity-architecture-exists-vs-needs-v1.md` (exists-vs-needs map),
+`cognitive-write-roundtrip-substrate-v1.md` (the round-trip mechanism).
+
 ## 2026-06-06 — E-DEINTERLACE-TWO-SCALES — deinterlace is one operation at two scales; no-cross-cycle-lag = byte-scale deinterlace
 
 **Status:** FINDING (source-grounded; `temporal.rs` PR #468 confirms row-scale; byte-scale is a documented gap)

.claude/board/LATEST_STATE.md

@@ -54,6 +54,8 @@
 
 ## Current Contract Inventory (lance-graph-contract)
 
+> **2026-06-09 — ADDED (D-IDENTITY-1, Phase A of identity-architecture)**: `lance_graph_contract::identity::{NodeGuid([u8;16]), IDENTITY_LAYOUT_VERSION}` — the workspace's first **stable binary instance identity**: a structured 128-bit UUIDv8 (RFC 9562) = the HHTL nibble-address **formalized + namespaced**. **Composed from existing committed scalars, never re-invented** (Agent A sweep confirmed the 128-bit id space was empty): octets carry `namespace:u8 | entity_type:u16 | kind:u8` (the `SchemaPtr.packed` convention) ⊕ a truncated `NiblePath` routing prefix (`PREFIX_NIBBLES=4`) ⊕ a 22-bit `shape_hash` (truncated `StructuralSignature`) ⊕ a 24-bit `local`, with UUIDv8 version(=8)/variant(=0b10) at their RFC-fixed positions + an `IDENTITY_LAYOUT_VERSION` stamp. **Eineindeutigkeit**: `entity_type` is the canonical exact class identity; the `NiblePath` prefix is the bijective DERIVED view (a *truncated* prefix can't be the identity — deep classes collide past it; the prefix `is_ancestor_of` the full path). Five readings: resolve (`entity_type`) / route (`niblepath`) / witness (frozen bytes + merkle) / ground-truth (`shape_hash` drift) / dispatch-to-store (`as_bytes` → `EntityKey`). Also added `hhtl::NiblePath::from_packed` (inverse of `packed`). Zero-dep; 599 contract lib tests (+15: field-isolation matrix, UUIDv8 gates, ancestor-prefix invariant, Display=canonical-UUID); clippy `-D warnings` clean; fmt clean. Plans: `identity-architecture-exists-vs-needs-v1.md` (exists-vs-needs map + phases A→H), `cognitive-write-roundtrip-substrate-v1.md`. Epiphany: E-IDENTITY-WHITEBOX-1.
+
 > **2026-05-31 — ADDED (D-EW64-1 + D-VIEW-1, episodic-RISC-spine)**: `episodic_edges::{EpisodicEdges64(u64), EdgeRef{family:u8,local:u16}}` — AriGraph episodic edges, 4x[4-bit family | 12-bit local]: family 0 = intra-basin (inherited, ~98.6% per #444), 1..=15 = cross-family index into the OGIT-class-inherited palette (~1.4%; identities inherited, never on the edge — I-VSA-IDENTITIES). Plus `view_angle::ViewAngle` (4-bit view-schema selector; presence bitmask doubles as attention mask, inherited). Zero-dep; 527 contract lib tests; clippy pedantic+nursery clean. Plan: episodic-risc-spine-v1.md.
 
 > **2026-05-31 — ADDED (D-H2H-1, head2head superposition winner-select)**: `lance_graph_contract::head2head::{Head2Head (judge), WinnerCriterion (DissonanceMin≈infight / SupportSpread≈Raumgewinn / ConfidenceMax / Tempered=default), CompetitionOutcome}`. `Head2Head::select(&Blackboard) -> Option<CompetitionOutcome>` picks the winning competing-expert bid over the existing `a2a_blackboard` (confidence/dissonance/support) — pure read + arg-extremum, **no new identity, copies nothing** (select-don't-duplicate, `I-VSA-IDENTITIES`); `margin` = the dark-horse signal. The *selection* half of head2head superposition; parallel-mailbox *execution* is the CI-gated consumer side. Zero-dep; 516 contract lib tests (+7); clippy pedantic+nursery clean.

.claude/plans/identity-architecture-exists-vs-needs-v1.md

@@ -155,11 +155,13 @@ lineage id, re-resolved from the address for free; the GUID is write-once; drift
 mutation. `I-VSA-IDENTITIES` Test 0: the GUID is a register key (points to
 content), never VSA-bundled.
 
-### ⚠ One open DECISION (yours to pin — both grounded, bijective)
-The class can be carried two ways; pick the **stored** form, resolve the other:
-- **(D1) `SchemaPtr.entity_type:u16`** — reuse the existing dense pointer (Agent A "compose existing"). Compact, exact.
-- **(D2) `NiblePath` prefix** — identity-IS-address (ADR-1374, your "nibble = the GUID class"). O(1) ancestry-routing without a cache hit.
-- **Recommendation:** store **SchemaPtr (exact) + a truncated NiblePath prefix (for routing)** — SchemaPtr resolves deep paths exactly; the prefix gives branchless `is_ancestor_of`. Costs ~42 bits for the prefix; worth it for probe-free routing.
+### ✅ DECISION — RESOLVED (eineindeutig / bijective, ratified 2026-06-09; Phase A landed)
+**Carry BOTH, bound by an enforced bijection** (`entity_type ↔ NiblePath`), pre-production so it's baked in with zero migration debt:
+- **Canonical, exact, in the GUID:** `entity_type:u16` — fixed-width, no truncation. A *truncated* NiblePath prefix CANNOT be bijective (two distinct deep paths collide past the prefix, `hhtl.rs`), so the exact identity MUST be the dense `entity_type`.
+- **Derived view:** `NiblePath` — the bijective radix encoding of the SAME class; full depth resolves from the registry; the GUID carries a coarse prefix (`PREFIX_NIBBLES = 4`) as a *derived routing cache* = `niblepath_of(entity_type)` truncated (the prefix `is_ancestor_of` the full path — tested).
+- **identity-IS-address holds:** `entity_type` IS the dense encoding of the address; bijective with `NiblePath` (ADR-1374 satisfied).
+- **Eineindeutigkeit enforced 3 ways:** (a) the registry mints `(entity_type, NiblePath)` as a unique pair [Phase B]; (b) a build-time bijection round-trip test proves it [Phase B]; (c) the GUID prefix-consistency invariant. (c) + the byte-layout field-isolation matrix landed in Phase A (`identity.rs`, 15 tests); (a)/(b) are Phase B (ontology, needs the registry).
+- **Landed (Phase A, D-IDENTITY-1):** `lance_graph_contract::identity::NodeGuid` + `NiblePath::from_packed`. Byte layout, UUIDv8 version/variant gates, field-isolation matrix, `prefix is_ancestor_of full` invariant — all green (599 contract tests, +15; clippy -D clean).
 
 ## Phased integration plan (A→H; each phase = one landable PR)
 

crates/lance-graph-contract/examples/cognitive_cycle.rs

@@ -22,7 +22,13 @@ use lance_graph_contract::recipes::recipe_by_code;
 const DEEP_THINK: [&str; 8] = ["RTE", "HTD", "TCP", "CR", "CDT", "MCP", "TCF", "CUR"];
 
 fn gate_state(sd: f32) -> GateState {
-    if sd < SD_FLOW { GateState::Flow } else if sd <= 0.35 { GateState::Hold } else { GateState::Block }
+    if sd < SD_FLOW {
+        GateState::Flow
+    } else if sd <= 0.35 {
+        GateState::Hold
+    } else {
+        GateState::Block
+    }
 }
 
 fn main() {
@@ -35,14 +41,23 @@ fn main() {
     ctx.beliefs = vec![(7, 0.90, 0.8), (7, 0.10, 0.7)]; // topic 7 asserted true AND false
 
     println!("== cognitive cycle: one Think, run to rest ==\n");
-    println!("start: gate={:?} F={:.2} conf={:.2} candidates={} beliefs={}\n",
-        gate_state(ctx.sd), ctx.free_energy, ctx.confidence, ctx.candidates.len(), ctx.beliefs.len());
+    println!(
+        "start: gate={:?} F={:.2} conf={:.2} candidates={} beliefs={}\n",
+        gate_state(ctx.sd),
+        ctx.free_energy,
+        ctx.confidence,
+        ctx.candidates.len(),
+        ctx.beliefs.len()
+    );
 
     // The active-inference loop: keep thinking while there is surprise (gate != FLOW).
     let mut round = 0;
     while gate_state(ctx.sd) != GateState::Flow && round < 5 {
         round += 1;
-        println!("── round {round} (gate {:?}) ───────────────────────", gate_state(ctx.sd));
+        println!(
+            "── round {round} (gate {:?}) ───────────────────────",
+            gate_state(ctx.sd)
+        );
 
         // Pipe the context through the recipe. Each step is `ctx |> tactic`.
         for code in DEEP_THINK {
@@ -54,7 +69,11 @@ fn main() {
                 code,
                 format!("{:?}", rec.bucket),
                 rec.name,
-                if out.fired { out.note } else { "· gated off (FLOW)" },
+                if out.fired {
+                    out.note
+                } else {
+                    "· gated off (FLOW)"
+                },
                 out.delta_conf,
             );
         }
@@ -63,18 +82,35 @@ fn main() {
         // (In the wired system this falls out of the codec sweep; here we make it explicit.)
         ctx.sd *= 0.55;
         ctx.free_energy *= 0.5;
-        println!("  → after round: gate={:?} SD={:.3} F={:.3} conf={:.2}\n",
-            gate_state(ctx.sd), ctx.sd, ctx.free_energy, ctx.confidence);
+        println!(
+            "  → after round: gate={:?} SD={:.3} F={:.3} conf={:.2}\n",
+            gate_state(ctx.sd),
+            ctx.sd,
+            ctx.free_energy,
+            ctx.confidence
+        );
     }
 
     if gate_state(ctx.sd) == GateState::Flow {
-        println!("== rest ==  the shader stopped because gate reached Flow (SD={:.3} < FLOW {SD_FLOW}).", ctx.sd);
+        println!(
+            "== rest ==  the shader stopped because gate reached Flow (SD={:.3} < FLOW {SD_FLOW}).",
+            ctx.sd
+        );
     } else {
-        println!("== rest ==  round cap reached ({round} rounds) before FLOW; gate={:?}, SD={:.3}.",
-            gate_state(ctx.sd), ctx.sd);
+        println!(
+            "== rest ==  round cap reached ({round} rounds) before FLOW; gate={:?}, SD={:.3}.",
+            gate_state(ctx.sd),
+            ctx.sd
+        );
     }
-    println!("final: conf={:.2}, {} candidate(s) survived pruning, {} beliefs.",
-        ctx.confidence, ctx.candidates.len(), ctx.beliefs.len());
+    println!(
+        "final: conf={:.2}, {} candidate(s) survived pruning, {} beliefs.",
+        ctx.confidence,
+        ctx.candidates.len(),
+        ctx.beliefs.len()
+    );
     println!("\nKey: Gate-bucket tactics (TCP/CDT/TCF/CUR) skip while in FLOW — the markers,");
-    println!("not a scheduler, decide what fires. Same `Tactic` behaviour, 34 hot-swappable units.");
+    println!(
+        "not a scheduler, decide what fires. Same `Tactic` behaviour, 34 hot-swappable units."
+    );
 }

crates/lance-graph-contract/examples/savant_dispatch.rs

@@ -26,7 +26,9 @@ struct Situation {
 /// Pattern-match the kind → the reasoning approach (the Elixir multi-clause `case`).
 fn approach(kind: ReasoningKind) -> &'static str {
     match kind {
-        ReasoningKind::CustomerCategory => "classify against the family codebook (deductive lookup)",
+        ReasoningKind::CustomerCategory => {
+            "classify against the family codebook (deductive lookup)"
+        }
         ReasoningKind::PostingAnomaly => "abduce the most likely cause from the evidence trail",
         ReasoningKind::NextBestAction => "induce the action with the highest expected value",
         ReasoningKind::InvoiceCompleteness => "check required-field coverage, score the gaps",
@@ -40,10 +42,21 @@ fn approach(kind: ReasoningKind) -> &'static str {
 
 fn dispatch(s: &Savant) {
     println!("  savant     {} (#{}, lane {})", s.name, s.id, s.lane);
-    println!("  family     {}", s.family.map(|f| format!("0x{f:02X}")).unwrap_or_else(|| "None (needs alignment axiom)".into()));
-    println!("  tuple      kind={:?} · infer={:?} · semiring={:?} · style={:?}", s.kind, s.inference, s.semiring, s.style);
+    println!(
+        "  family     {}",
+        s.family
+            .map(|f| format!("0x{f:02X}"))
+            .unwrap_or_else(|| "None (needs alignment axiom)".into())
+    );
+    println!(
+        "  tuple      kind={:?} · infer={:?} · semiring={:?} · style={:?}",
+        s.kind, s.inference, s.semiring, s.style
+    );
     // The InferenceType resolves O(1) to the runtime query strategy.
-    println!("  → strategy {:?}   (InferenceType::default_strategy)", s.query_strategy());
+    println!(
+        "  → strategy {:?}   (InferenceType::default_strategy)",
+        s.query_strategy()
+    );
     println!("  → approach {}", approach(s.kind));
     println!("  → output   NARS (frequency, confidence) suggestion — woa-rs applies it behind its AXIS-A guard\n");
 }
@@ -52,11 +65,32 @@ fn main() {
     println!("== Odoo savant delegation: AXIS-A guard (woa-rs) → AXIS-B reason (lance-graph) ==\n");
 
     let inbox = [
-        Situation { headline: "€1,200 payment arrived — does it fully reconcile the partner's open invoices?", ambiguous: true, savant: "PaymentToInvoiceMatcher" },
-        Situation { headline: "3rd identical bill from this vendor, unmodified — auto-post it?",              ambiguous: true, savant: "AutopostRecommender" },
-        Situation { headline: "new B2B partner in AT — which fiscal position (tax mapping)?",                 ambiguous: true, savant: "FiscalPositionResolver" },
-        Situation { headline: "journal sequence jumps 1042 → 1044 — is 1043 a deleted posted entry?",         ambiguous: true, savant: "SequenceGapAnomalyDetector" },
-        Situation { headline: "invoice with a perfectly matching single open item",                           ambiguous: false, savant: "ReconcileMatchSelector" },
+        Situation {
+            headline:
+                "€1,200 payment arrived — does it fully reconcile the partner's open invoices?",
+            ambiguous: true,
+            savant: "PaymentToInvoiceMatcher",
+        },
+        Situation {
+            headline: "3rd identical bill from this vendor, unmodified — auto-post it?",
+            ambiguous: true,
+            savant: "AutopostRecommender",
+        },
+        Situation {
+            headline: "new B2B partner in AT — which fiscal position (tax mapping)?",
+            ambiguous: true,
+            savant: "FiscalPositionResolver",
+        },
+        Situation {
+            headline: "journal sequence jumps 1042 → 1044 — is 1043 a deleted posted entry?",
+            ambiguous: true,
+            savant: "SequenceGapAnomalyDetector",
+        },
+        Situation {
+            headline: "invoice with a perfectly matching single open item",
+            ambiguous: false,
+            savant: "ReconcileMatchSelector",
+        },
     ];
 
     for s in &inbox {
@@ -70,5 +104,7 @@ fn main() {
     }
 
     println!("Same delegation tuple for all 25 savants; dispatch is data, not branches.");
-    println!("Pattern-match on ReasoningKind picks the approach; the family's StyleCluster colours it.");
+    println!(
+        "Pattern-match on ReasoningKind picks the approach; the family's StyleCluster colours it."
+    );
 }

crates/lance-graph-contract/src/atoms.rs

@@ -277,7 +277,10 @@ mod tests {
     fn catalogue_is_locked_33_in_order() {
         assert_eq!(CANONICAL_ATOMS.len(), 33);
         for (i, a) in CANONICAL_ATOMS.iter().enumerate() {
-            assert_eq!(a.dim as usize, i, "lane dim must equal its index (locked order)");
+            assert_eq!(
+                a.dim as usize, i,
+                "lane dim must equal its index (locked order)"
+            );
             assert!(!a.name.is_empty());
         }
     }

crates/lance-graph-contract/src/callcenter/mod.rs

@@ -26,9 +26,7 @@
 pub mod ogit_uris;
 pub mod role_keys;
 
-pub use ogit_uris::{
-    savant_ogit_uri, savant_ogit_uri_by_name, SAVANT_OGIT_BASE, SAVANT_OGIT_URIS,
-};
+pub use ogit_uris::{savant_ogit_uri, savant_ogit_uri_by_name, SAVANT_OGIT_BASE, SAVANT_OGIT_URIS};
 pub use role_keys::{
     savant_role_key, savant_role_key_by_name, SAVANT_ROLE_KEYS, SAVANT_SLICE_END,
     SAVANT_SLICE_START, SAVANT_SLICE_WIDTH,