Merge pull request #480 from AdaWorldAPI/claude/nice-edison-g4rhhl

feat(contract): NodeGuid — structured 128-bit instance identity (identity-architecture Phase A)

Author: AdaWorldAPI

.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.