Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AdaWorldAPI merged 3 commits into from
Jun 9, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
030b3f3
plans: cognitive-write = round-trip substrate-hardening spec (v1)
claude Jun 9, 2026
cbd99e4
plans: identity architecture exists-vs-needs map + integration plan (v1)
claude Jun 9, 2026
947c1e4
feat(contract): NodeGuid — structured 128-bit identity (Phase A, D-ID…
claude Jun 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .claude/board/AGENT_LOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +1 to +8

@coderabbitai coderabbitai Bot Jun 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add the commit SHA to the new AGENT_LOG entry for traceability.

The new run entry captures D-id/tests/outcome, but it should also include the commit identifier so the shipped scope is audit-linkable from this log entry.

As per coding guidelines, “Every agent run gets one append-only entry in AGENT_LOG.md (D-ids, commit, tests, outcome).”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/board/AGENT_LOG.md around lines 1 - 8, Update the new AGENT_LOG.md
entry for "2026-06-09 — D-IDENTITY-1 (Phase A) + 2 cross-repo sweeps —
identity-architecture" to include the commit SHA used for this run; locate the
header line and append the short or full commit identifier after the date or
outcome (so the entry contains D-ids, commit, tests, outcome as required),
ensuring the commit SHA is recorded in the same sentence that describes the
orchestration/outcome for traceability.

Source: Coding guidelines


## [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).
Expand Down
36 changes: 36 additions & 0 deletions .claude/board/EPIPHANIES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand Down
2 changes: 2 additions & 0 deletions .claude/board/LATEST_STATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@coderabbitai coderabbitai Bot Jun 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove the blank blockquote break that triggers MD028.

Line 58 is a blank line inside a blockquote (MD028). Keep the quote block continuous (or use > on the separator line) to avoid markdown lint warnings.

Proposed fix 
-
+>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
>
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 58-58: Blank line inside blockquote

(MD028, no-blanks-blockquote)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/board/LATEST_STATE.md at line 58, A blank line inside a blockquote
is triggering MD028; fix the blockquote continuity in
.claude/board/LATEST_STATE.md by removing the empty line inside the quoted block
or ensuring the separator line also starts with '>' so the quote remains
continuous; locate the broken blockquote (the paragraph break around the
"Proposed fix" area) and either delete the blank line or prefix it with '>' to
preserve a single continuous blockquote.

Source: Linters/SAST tools

> **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.
Expand Down
Loading
Loading