feat(contract): canonicalise #489 — wire-in + self-describing Display + retire Phase-A wrapper

[AdaWorldAPI]

Summary

Operator pin: #489 is canonical. Audited canonical_node.rs against OGAR/CLAUDE.md P0 group-by-group, closed the one wrapper gap (no Display), and retired the Phase-A wrapper now that the canon is settled.

Canon audit (OGAR/CLAUDE.md P0 ↔ canonical_node.rs)

Canon line	#489 code	Status
classid = 8 hex = 4B	classid: u32 at [0..4]	match
HEEL = 4 hex = 2B	heel: u16 at [4..6]	match
HIP = 4 hex = 2B	hip: u16 at [6..8]	match
TWIG = 4 hex = 2B	twig: u16 at [8..10]	match
family-basin-leaf = 6 hex = 3B	family: u24 at [10..13]	match
identity = 6 hex = 3B	identity: u24 at [13..16]	match
RFC-WAIVED (no version, no variant, no ns/kind framing)	"No UUID ceremony"	match
3×4 uniform, tier-of-level = level >> 2	each tier is u16	match
16-byte EdgeBlock at fixed offset	row-layout zero-fallback ladder: default class reserves it, registry-resolved opt-out, "reserve-don't-reclaim" applied at row level	match (same discipline as classid==0 / family==0)
Every printed GUID is self-describing at sight	no Display impl	closed in this PR

Changes

1. lib.rs: pub mod canonical_node; (the const _: () = assert!(size_of…) size-locks and 8 unit tests are now CI-enforced).
2. canonical_node.rs: impl Display for NodeGuid emitting
   {classid:08x}-{heel:04x}-{hip:04x}-{twig:04x}-{family:06x}{identity:06x} so every printed GUID is self-describing per canon. LE in-memory bytes fold through the accessors so hex print is canon-ordered regardless. +2 Display tests.
3. Phase-A wrapper retired (operator: "delete feat(contract): NodeGuid — structured 128-bit instance identity (identity-architecture Phase A) #480 from your mind"): identity.rs deleted — UUIDv8 NodeGuid + RFC ceremony bits + IDENTITY_LAYOUT_VERSION + SHAPE_HASH_BITS/LOCAL_BITS were all canon-incompatible per "wrappers adapt to the canon, never the reverse". lib.rs re-export switched: pub use identity::{NodeGuid, IDENTITY_LAYOUT_VERSION} → pub use canonical_node::{EdgeBlock, NodeGuid, NodeRow}.
4. Stale doc references reworded: hhtl.rs:192 (from_packed is a general HHTL utility, no longer identity-specific), lance-graph-ontology/src/registry.rs:405 (niblepath_of now points at the canon's classid·HEEL·HIP·TWIG resolution).

Tests

• cargo test -p lance-graph-contract --lib → 594/594 green (−10 retired UUIDv8 tests, +2 Display, +8 wire-in canonical_node tests now visible).
• cargo check -p lance-graph-ontology → clean (5 pre-existing oxrdf::Subject deprecations in untouched files).
• cargo clippy -p lance-graph-contract --all-targets -- -D warnings → clean.

Out of scope

• Workspace-wide cargo check --workspace — failed locally on a disk-full during aws-lc-sys C compilation (env, not code). CI will run it.
• Centroid-tile / codebook-scoping / deterministic-phase / bipolar-WH-on-VSA helpers — canon-compatible at the layout level (each u16 tier = 2×u8 axes; classid prefix = codebook scope) but not key-wrapper concerns.

Anchors

• OGAR/CLAUDE.md P0 — the canon (operator-pinned).
• docs(knowledge): GUID canon + prefix routing — policy-side crystallization (quorum landing spot, deterministic phase, WHP bipolar) #482 — GUID-canon crystallisation in lance-graph.
• feat(contract): canonical SoA node (NodeGuid/EdgeBlock/NodeRow) — 12+4 edges, zero-fallback ladder #489 — canonical_node (now wired + Display'd).

Test plan

• cargo test -p lance-graph-contract --lib green
• cargo clippy -p lance-graph-contract --all-targets -D warnings clean
• cargo check -p lance-graph-ontology clean
• CI workspace check
• CodeRabbit review

https://claude.ai/code/session_01VysoWJ6vsyg3wEGc5v7T5v

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added canonical hex formatting for node GUIDs with a self-describing layout.

• Tests

  • Added unit tests validating the new node GUID string formatting.

• Refactor

  • Consolidated node identifier handling by retiring legacy module structures.
  • Updated module exports to reflect organizational changes.

• Documentation

  • Updated documentation for routing path utilities and registry methods.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR migrates canonical NodeGuid formatting from the retired identity.rs module to canonical_node.rs. The crate's public API is restructured to expose canonical_node, a Display implementation is added to NodeGuid for hex-formatted output, and stale documentation references are refreshed.

Changes

Canonical Node Migration

Layer / File(s)	Summary
Module restructuring and public exports crates/lance-graph-contract/src/lib.rs	The canonical_node module is declared public, identity module is removed, and re-exports now pull NodeGuid from canonical_node instead of identity.
NodeGuid Display implementation and tests crates/lance-graph-contract/src/canonical_node.rs	NodeGuid implements core::fmt::Display to format as a canonical 8-4-4-4-12 hex string with hyphens. Two unit tests validate formatting for a non-default GUID and the default local node.
Documentation updates and AGENT_LOG entry crates/lance-graph-contract/src/hhtl.rs, crates/lance-graph-ontology/src/registry.rs, .claude/board/AGENT_LOG.md	Doc comments in hhtl.rs and registry.rs are updated to remove stale identity module references. A new AGENT_LOG entry dated 2026-06-13 documents the module migration, Display implementation, and test additions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• AdaWorldAPI/lance-graph#489: Introduced the canonical_node.rs module with the core NodeGuid layout and related types that this PR builds upon with Display formatting and tests.

Poem

🐰 The old identity phase fades away,
Canonical nodes light the way—
Format thy GUIDs with hex so bright,
Tests confirm the display's right!
hippity-hop ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main changes: wiring in canonical node, adding a Display implementation, and retiring the Phase-A identity wrapper.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with 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.

Inline comments:
In `@crates/lance-graph-contract/src/lib.rs`:
- Line 45: The crate removed the legacy identity namespace and the
IDENTITY_LAYOUT_VERSION symbol; restore a v1-compat identity bridge that
re-exports the canonical types and a compatibility constant and documents
migration: add an identity module in the crate root that pub use-s EdgeBlock,
NodeGuid, NodeRow from canonical_node (e.g. pub mod identity { pub use
crate::canonical_node::{EdgeBlock, NodeGuid, NodeRow}; pub const
IDENTITY_LAYOUT_VERSION: u32 = /* previous v1 value */; } ), mark the module
behind a feature (e.g. "v1-compat") if desired, and add a short doc comment on
the identity module pointing callers to the new canonical_node path and advising
migration to crate::canonical_node::{EdgeBlock, NodeGuid, NodeRow}; ensure
symbols match the existing names so downstream code using identity::NodeGuid or
IDENTITY_LAYOUT_VERSION continues to compile.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b3baf718-13d0-4d14-9d62-f5c3310a3287

📥 Commits

Reviewing files that changed from the base of the PR and between 1af2a45 and e806058.

📒 Files selected for processing (6)

• .claude/board/AGENT_LOG.md
• crates/lance-graph-contract/src/canonical_node.rs
• crates/lance-graph-contract/src/hhtl.rs
• crates/lance-graph-contract/src/identity.rs
• crates/lance-graph-contract/src/lib.rs
• crates/lance-graph-ontology/src/registry.rs

💤 Files with no reviewable changes (1)

• crates/lance-graph-contract/src/identity.rs