feat(contract): 6×(8:8) FacetCascade + V3 (part_of:is_a) fold + OSINT-V3 (custom:canon split)

[AdaWorldAPI]

What (P-A)

Extends the canonical classid → ReadMode registry with the tail_variant axis — which KEY shape (V1 / V2 / V3) a classid mints, resolved by the same classid_read_mode(c) lookup that already resolves value_schema and edge_codec. This is the reusable mechanism for the SoA value-tenant migration: migrating a class's identity to V3 = flip tail_variant on its ReadMode const; later migrating its tenants = flip value_schema on the same const. Two field-flips on one registry entry, no consumer rewrite either time.

Companion to #612 (the §2.2 doc correction); this is the code that §2.2 describes.

Changes (crates/lance-graph-contract)

• New TailVariant { V1=0 (default), V2, V3 } enum (+ is_layout_preserving).
• ReadMode gains tail_variant as its first field; all five existing consts pinned to TailVariant::V1 → zero re-mint of the V1/V2 corpus (RESERVE-DON'T-RECLAIM; DEFAULT.tail_variant = V1).
• is_layout_preserving extended to the three-axis form.
• Structural parity fuse (compile-time const _): asserts ReadMode's field set == the three canon axes {tail_variant, value_schema, edge_codec} from OGAR feat: Phase 3 BF16 wiring + φ-spiral reconstruction theory #128 — structural-against-canon, not runtime (OGAR's tail_variant is to-wire too).
• guid-v3-tail feature gates the first V3 entry: CLASSID_OSINT_V3 = 0x1000_0700 + ReadMode::OSINT_V3 {V3, Cognitive, CoarseOnly} + BUILTIN_READ_MODES insert.

Tests

• read_mode_osint_v3_routes_v3_tail_and_osint_domain asserts classid_read_mode(0x1000_0700).tail_variant == V3 and classid_concept_domain(0x1000_0700) == Osint — proving the high-u16 marker routes V3 without touching the canon domain byte.
• Green: 736 lib (default) / 737 (guid-v3-tail), clippy -D warnings clean.

FMA-V3 (0x1000_0A01) and Genetics-V3 (domain TBD) are deferred ("rest later").

🤖 Generated with Claude Code

https://claude.ai/code/session_01TzqvDqbFRzyx17EkLKBoZF

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added support for an additional routing variant for certain graph identities, improving path selection for newer data layouts.
  • Introduced richer facet-based metadata handling for reading and interpreting graph nodes.

• Bug Fixes

  • Fixed a routing edge case where some identities could be incorrectly folded into an empty path.
  • Clarified and corrected how routing behaves across older and newer layout variants.

• Documentation

  • Updated internal release documentation to describe the new routing and facet behavior more clearly.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR adds a guid-v3-tail feature flag, expands ReadMode with a TailVariant axis, introduces FacetTier and FacetCascade, adds V3 HHTL prefix folding, and routes soa_graph::hhtl_path through the V3 path when enabled.

Changes

V3 tail routing and facet substrate

Layer / File(s)	Summary
Public contract and routing axis crates/lance-graph-contract/Cargo.toml, crates/lance-graph-contract/src/canonical_node.rs	Adds the guid-v3-tail feature, NodeGuid::CLASSID_OSINT_V3, TailVariant, expanded ReadMode constants, conditional built-in routing, and the ReadMode tail-axis tests.
Facet cascade types crates/lance-graph-contract/src/canonical_node.rs, .claude/board/LATEST_STATE.md	Adds FacetTier and FacetCascade with byte serialization, tier projections, chain accessors, distance metrics, validation tests, and the inventory note for the facet substrate.
V3 HHTL prefix folding crates/lance-graph-contract/src/hhtl.rs, .claude/board/EPIPHANIES.md	Clarifies the v1 folding rule, adds from_guid_prefix_v3, and verifies v1 rejection, V3 path construction, and byte-sensitive routing in tests.
SoA graph V3 routing crates/lance-graph-contract/src/soa_graph.rs	Selects NiblePath::from_guid_prefix_v3 for V3 tail variants and keeps the existing fallback for other modes.

Sequence Diagram(s)

sequenceDiagram
  participant H as soa_graph::hhtl_path
  participant R as classid_read_mode
  participant V3 as NiblePath::from_guid_prefix_v3
  participant V1 as NiblePath::from_guid_prefix
  H->>R: guid.classid()
  R-->>H: tail_variant
  alt tail_variant == V3
    H->>V3: guid
  else
    H->>V1: guid
  end

Loading

sequenceDiagram
  participant G as NodeGuid
  participant P as NiblePath::from_guid_prefix_v3
  participant F as from_packed
  G->>P: raw GUID bytes
  P->>F: full-depth HEEL·HIP·TWIG·LEAF path
  F-->>P: NiblePath or EMPTY

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• AdaWorldAPI/lance-graph#489 — Defines the NodeGuid classid/family/identity layout that this PR extends with CLASSID_OSINT_V3.
• AdaWorldAPI/lance-graph#498 — Introduces ReadMode and classid_read_mode, which this PR extends with TailVariant and V3 tail routing.
• AdaWorldAPI/lance-graph#557 — Adds the SoA graph pathing foundation that this PR updates to branch on V3 tail routing.

Poem

🐰 I hopped through bytes with jaunty grace,
and found the V3 rabbit place.
Facets twinkled, paths stayed bright,
one nibble left, one nibble right.
A carrot toast to routes anew!

🚥 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 reflects the main changes: FacetCascade, V3 folding, and OSINT-V3 routing.
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.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fd1302fcca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid using a high-u16 V3 class marker

With guid-v3-tail enabled, this high-u16 marker makes every OSINT-V3 NodeGuid fail the existing HHTL lowering: NiblePath::from_guid_prefix returns None whenever classid >> 16 != 0 (crates/lance-graph-contract/src/hhtl.rs:291-299), and soa_graph::hhtl_path turns that into NiblePath::EMPTY (crates/lance-graph-contract/src/soa_graph.rs:143-149). Any OSINT-V3 domain projected through the existing graph surface will therefore render hhtl_depth = 0 and nearest_anchor will compare empty paths rather than the node's HEEL/HIP/TWIG prefix; either reserve a marker that the prefix fold can carry or add a V3-aware path lowering before registering this classid.

Useful? React with 👍 / 👎.