Skip to content

feat(contract): GUID decode→read-mode keystone + helix Signed360 right-size + OCR→NodeRow transcode#498

Merged
AdaWorldAPI merged 9 commits into
mainfrom
claude/wonderful-hawking-lodtql
Jun 16, 2026
Merged

feat(contract): GUID decode→read-mode keystone + helix Signed360 right-size + OCR→NodeRow transcode#498
AdaWorldAPI merged 9 commits into
mainfrom
claude/wonderful-hawking-lodtql

Conversation

@AdaWorldAPI

@AdaWorldAPI AdaWorldAPI commented Jun 15, 2026

Copy link
Copy Markdown
Owner

Post-#496 branch work. Three pieces + a standing-red fix, all on the single canon canonical_node::NodeGuid (no second GUID type — identity::NodeGuid was retired in #490).

Keystone — GUID decode + classid→read-mode (eef7e5f9)

The "read the GUID as a GUID, but resolve a class" surface:

  • NodeGuid::{heel(), hip(), twig()} HHT accessors + decode() -> GuidParts (all six canon groups in one read: classid · HEEL · HIP · TWIG · family · identity).
  • ReadMode { value_schema, edge_codec } — bundles the two already-existing read-mode axes (ValueSchema + EdgeCodecFlavor). Not a new node property, not a SoA column — the resolution lens only (§0 anti-invention).
  • classid_read_mode(u32) -> ReadMode — a LazyLock<HashMap> registry, the single source both the consumer and OGAR inherit; zero-fallback to ReadMode::DEFAULT for unconfigured classids. NodeGuid::read_mode() is the carrier-method form.
  • Display deduped onto the new HHT accessors.

ReadMode::DEFAULT = {Full, CoarseOnly} mirrors the ClassView::value_schema POC default; the two sites revert together (TD-VALUESCHEMA-FULL-POC-DEFAULT, guard test read_mode_default_is_full_poc).

OCR LayoutBlock → NodeRow transcode POC (2fa7fcb0)

Reference transcode any OcrProvider reuses, exercising the keystone end-to-end: classid → read_mode → ValueSchema gates which tenants land; BlockKind::entity_type()EntityType, confidenceEnergy, written at canon slab offsets via new ValueTenant::{value_offset, byte_len}. text/bbox stay in an external content store (I-VSA-IDENTITIES). Engine-agnostic — not Tesseract-coupled.

helix Signed360 + HelixResidue 48 B → 6 B (66989691)

Right-sizes a slab over-allocation (48 bytes → the intended 48 bit = 6 B) and gives the tenant real math: helix::Signed360 signed full-sphere codec (HemispherePoint::signed_lift, Sign{Pos,Neg}). Downstream tenant offsets shifted; budgets re-locked (Full 154→112, Compressed 98→56).

causal-edge red fix (2106be29)

test_build_fast boundary <<= (the c_levels=1 floor is exactly 256 KB) — resolves a standing red on main.

Tests

  • contract: 623 lib green
  • helix: 72 lib + 7 doctests green
  • causal-edge: green
  • clippy -D warnings + fmt clean across touched crates

Note

The tesseract-rs cross-repo wiring explored mid-session was reverted (board reflects it) — hand-wrapping the original Tesseract C engine is the wrong direction. Pure-Rust OCR via ocrs + rten (ONNX-adjacent) is the chosen path, parked pending scope.

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo


Generated by Claude Code

Summary by CodeRabbit

  • New Features

    • Added signed full-sphere geometric support with hemisphere sign tracking and directional lift computation.
    • Implemented OCR-to-graph node transcoding for entity classification and energy encoding.
    • Extended node identifier decoding with read-mode resolution and hierarchical tier accessors.
  • Bug Fixes

    • Relaxed test boundary condition for memory size validation.
  • Documentation

    • Updated architectural ledger documenting OCR-agnostic transcoding strategy and dependency hierarchy.
    • Recorded merged contract additions for value schema and full-POC defaults.
    • Updated technical debt tracking.

claude added 8 commits June 15, 2026 15:37
#496 merged (merge 2e58e03, CI 5/5 green, CodeRabbit resolved, codex P2
dispositioned). Post-merge hygiene per the Mandatory Board-Hygiene rule:
- PR_ARC_INVENTORY: prepend #496 (Added/Locked/Deferred/Docs/Confidence) —
  ValueSchema/ValueTenant/VALUE_TENANTS + FULL POC default + the reference plan
  + §0 guardrail + §9 hardening; the keystone is the next unblock.
- LATEST_STATE: prepend the #496 shipped note + the keystone convergence
  (from_guid_prefix + classid->ClassView read-mode on registry.rs).

Capture (operator "yes"): TD-LAZY-IMPORT-VERSION-PIN — the OGIT-as-lazy-import
drift-control finding (immutable-address + evolvable-shape + versioned-namespace
+ StructuralSignature-detector; lock version-pin + reserve-don't-reclaim sibling
nibbles before the OGAR-identity migration runs a real load). EPIPHANY candidate
flagged for the council.

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo
… HelixResidue 48B->6B

Operator caught the slab over-allocation: HelixResidue reserved 48 BYTES but the
intent was a 24-bit equal-area hemisphere DOUBLED = 48 BIT = 6 bytes (a
bits->bytes slip; 42 dead bytes), and the tenant used NONE of the helix crate.

helix crate (the math, where it belongs):
- HemispherePoint::signed_lift(n,N,sign) -- y = sign*sqrt(1-u), the full sphere
  (y in [-1,1]); r^2+y^2=1 preserved; Sign{Pos,Neg}.
- Signed360 -- 6-byte signed full-sphere residue {rim: ResidueEdge (unsigned
  hemisphere), polar: signed lift centred@128 (sign recoverable via .sign()),
  azimuth: u16 over the full 360deg (n*phi mod 2pi)}; ResidueEncoder::encode_signed.
- +9 tests; helix 72 lib + 7 doctests green; lib clippy -D warnings + fmt clean.

contract (right-size only, NO new type):
- HelixResidue elems_per_row 48 -> 6; downstream tenants shifted (Turbovec 118 /
  Energy 134 / Plasticity 138 / EntityType 142); budgets re-locked (Full 154->112,
  Compressed 98->56). 613 contract lib green; clippy/fmt clean.
- NO HelixFlavour enum: one canonical encoding, one tenant size (the fixed-offset
  SoA can't vary width per-class; Hemisphere = degenerate sign=+). Contract stays
  zero-dep; the producer writes helix::Signed360::to_bytes into the reserved 6 B.

Cheap now (POC FULL default, no persisted real instances); after instances
persist it is a version bump. Board: LATEST_STATE note + TD-HELIX-PROBE-CLIPPY
(pre-existing probe_mantissa_fill clippy/fmt debt, NOT introduced here).

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo
…perator) + ractor note

Operator ground truth 2026-06-15: surrealdb "just needed 7.0.0 / lancedb 0.30
pin" — kv-lance is implemented, only the version pin remains (no deep work). The
fix is the 3-pin bump in AdaWorldAPI/surrealdb surrealdb/core/Cargo.toml, a FORK
write outside this session's scope (add_repo unavailable). Once it lands ->
unblocks D-PG-6 / D-MBX-9 OUT / identity Phase H. Companion: the --features
supervisor blocker is the AdaWorldAPI/ractor fork's MessagingErr::Saturated
match (fork lags upstream); sync the fork — also out of scope. Default builds
unaffected (ractor optional, off by default).

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo
…oor) — red on main resolved

The standing 47/1 red (flagged by 4 parallel sessions, ridden through ~46 PRs):
test_build_fast asserted byte_size() < 256*1024, but the c_levels=1 fast path is
EXACTLY 256 KB (1 revision table + 1 deduction table, 256·256·2 = 128 KB each).
`262144 < 262144` is false → impossible to satisfy. Fix: `<=` (the floor is 256
KB, not under it). causal-edge now 48/48 lib green.

Scoped to the test bound (tables.rs, fmt-clean). The crate's separate pre-existing
crate-wide clippy (15) + fmt debt (edge.rs, v2_layout_tests.rs) is NOT from this
fix and is CI-invisible (causal-edge is not a workspace member) — tracked as
TD-CAUSAL-EDGE-LINT for a follow-up `cargo fmt`+`clippy --fix` pass.

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo
…single source)

NodeGuid gains HHT accessors (heel/hip/twig), a one-shot decode() -> GuidParts
(classid + HEEL/HIP/TWIG + family + identity in canon print order), and a
carrier read_mode() method. ReadMode bundles the two already-existing read-mode
axes (ValueSchema + EdgeCodecFlavor) — not a new node property, not a SoA column,
just the resolution lens (§0 anti-invention). classid_read_mode(u32) is the
single source both the consumer and OGAR inherit: a LazyLock<HashMap> builtin
registry, zero-fallback to ReadMode::DEFAULT for unconfigured classids.

ReadMode::DEFAULT = {Full, CoarseOnly} mirrors the ClassView::value_schema POC
default; the two sites revert together (TD-VALUESCHEMA-FULL-POC-DEFAULT paired,
guard test read_mode_default_is_full_poc). Display deduped onto the new HHT
accessors. +6 tests; 619 contract lib green; clippy -D warnings + fmt clean.

Delivers the contract-side half of the #496 keystone; the ontology-side
NiblePath::from_guid_prefix meets it at the classid (follow-up).

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo
…off)

LayoutBlock::to_node_row(classid, identity) is the reference OCR→SoA transcode
any OcrProvider (tesseract-rs + others) reuses, exercising the keystone end to
end: classid → classid_read_mode → ValueSchema gates which tenants materialise.
BlockKind::entity_type() → ValueTenant::EntityType; confidence → ValueTenant::
Energy; each written at its canon slab offset via new ValueTenant::{value_offset,
byte_len} (derived accessors over the locked carve, not new properties).

text/bbox are NOT bundled into the node (I-VSA-IDENTITIES: node = identity +
typed scalars; string + geometry live in an external content store keyed by
identity). Schema-gated writes; transcoded rows ride the SoaEnvelope zero-copy.
§0 anti-invention: reuses existing EntityType/Energy tenants, no ocr_kind field.

Lives in the contract (next to the ocr types, zero-dep, testable with no OCR
C-lib and no fork); tesseract-rs adds the contract dep + calls it. +4 tests;
623 contract lib green; clippy -D warnings + fmt clean.

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo
@coderabbitai

coderabbitai Bot commented Jun 15, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@AdaWorldAPI, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 13 minutes and 17 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fa2ee798-7a6c-4fd3-8cd3-e9b92c892d7e

📥 Commits

Reviewing files that changed from the base of the PR and between f880141 and ef5a362.

📒 Files selected for processing (4)
  • .claude/board/PR_ARC_INVENTORY.md
  • crates/helix/src/residue.rs
  • crates/helix/tests/probe_mantissa_fill.rs
  • crates/lance-graph-contract/src/soa_envelope.rs
📝 Walkthrough

Walkthrough

Adds a signed full-sphere helix encoding layer (Sign, Signed360, ResidueEncoder::encode_signed), extends NodeGuid with HHT-tier accessors and a GuidParts decode, corrects HelixResidue tenant sizing from 48 bytes to 6 bytes in VALUE_TENANTS, introduces a ReadMode/classid_read_mode registry, and implements OCR-engine-agnostic LayoutBlock::to_node_row transcoding. Board documentation and a causal-edge test boundary fix are included.

Changes

Helix Signed Sphere Codec, Canonical-Node Keystone Contracts, and OCR Transcode

Layer / File(s) Summary
Sign enum and signed hemisphere lift
crates/helix/src/placement.rs, crates/helix/src/residue.rs, crates/helix/src/lib.rs
Introduces Sign enum with as_f64/of helpers, HemispherePoint::signed_lift, the new Signed360 6-byte type with byte codec and sign() recovery, and ResidueEncoder::encode_signed. Re-exports Sign and Signed360 from the helix crate root. Tests cover unit-sphere invariants, round-trip codec, rim equivalence, and determinism.
NodeGuid HHT accessors, GuidParts, VALUE_TENANTS sizing fix, ReadMode registry
crates/lance-graph-contract/src/canonical_node.rs, crates/lance-graph-contract/src/lib.rs
Adds NodeGuid::heel/hip/twig accessors and decode()->GuidParts; corrects HelixResidue in VALUE_TENANTS to 6 bytes (shifting all downstream offsets), updating Full budget to 112 B and Compressed to 56 B; adds ValueTenant::value_offset/byte_len helpers; introduces ReadMode struct with DEFAULT constant, lazy BUILTIN_READ_MODES registry, and classid_read_mode resolver. Re-exports new types from crate root. Tests cover accessor/Display consistency, read-mode defaults, fallback, delegation, and slab byte budget.
OCR block-to-NodeRow transcode
crates/lance-graph-contract/src/ocr.rs
Adds BlockKind::entity_type() stable u16 discriminator and LayoutBlock::to_node_row(classid, identity) that resolves a ReadMode, allocates a zeroed 480-byte slab, writes EntityType and Energy tenants at schema-derived offsets, and constructs a NodeRow with the encoded NodeGuid. Tests validate entity-type stability, slab writes, NodeRowPacket zero-copy packing, and schema-gated population.
causal-edge test boundary fix
crates/causal-edge/src/tables.rs
Relaxes test_build_fast byte-size assertion from < to <= for the c_levels=1 fast path, with an updated comment explaining the boundary condition.
Board documentation updates
.claude/board/LATEST_STATE.md, .claude/board/PR_ARC_INVENTORY.md, .claude/board/TECH_DEBT.md
Appends a 2026-06-15 revert/replacement note to LATEST_STATE; prepends PR #496 record to PR_ARC_INVENTORY; updates TECH_DEBT with new clippy/fmt/version-pin debt entries, TD-VALUESCHEMA-FULL-POC-DEFAULT revert instructions, and TD-SURREALDB-KVLANCE-LANCE7 pin details.

Sequence Diagram(s)

sequenceDiagram
  participant OCRPipeline
  participant LayoutBlock
  participant classid_read_mode
  participant BUILTIN_READ_MODES
  participant ValueTenant
  participant ResidueEncoder
  participant NodeRow

  OCRPipeline->>LayoutBlock: to_node_row(classid, identity)
  LayoutBlock->>classid_read_mode: classid_read_mode(classid)
  classid_read_mode->>BUILTIN_READ_MODES: lookup(classid)
  BUILTIN_READ_MODES-->>classid_read_mode: ReadMode or DEFAULT
  classid_read_mode-->>LayoutBlock: ReadMode { value_schema, edge_codec }
  LayoutBlock->>ValueTenant: EntityType.value_offset() + byte_len()
  LayoutBlock->>ValueTenant: Energy.value_offset() + byte_len()
  LayoutBlock->>LayoutBlock: write entity_type() + confidence into 480B slab
  Note over LayoutBlock,ResidueEncoder: HelixResidue tenant now 6B (Signed360)
  LayoutBlock-->>NodeRow: NodeRow { guid: NodeGuid(identity, classid), value_slab }
  NodeRow-->>OCRPipeline: canonical NodeRow
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

  • AdaWorldAPI/lance-graph#492: The OCR transcode tests in this PR verify zero-copy packing through NodeRowPacket and SoaEnvelope, directly exercising the envelope binding introduced in PR #492.
  • AdaWorldAPI/lance-graph#489: This PR extends the same canonical_node.rs NodeGuid/NodeRow SoA model from PR #489 with the new HHT accessors, GuidParts, and ReadMode resolution that LayoutBlock::to_node_row depends on.
  • AdaWorldAPI/lance-graph#496: Both PRs modify the ValueTenant/VALUE_TENANTS/ValueSchema substrate in canonical_node.rs; this PR corrects the HelixResidue tenant sizing and adds the ReadMode default that PR #496's FULL POC default guard test is paired against.

Poem

🐇 Hop, hop across the sphere I go,
Signing each point with a positive glow—
Six bytes for the helix, tight and right,
The NodeGuid decoded in the moonlight.
OCR blocks now find their row,
And every tenant knows where bytes should flow! ✨

🚥 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 PR title accurately summarizes the three main feature additions (GUID decode→read-mode keystone, helix Signed360 right-size, OCR→NodeRow transcode) and the bug fix mentioned in the objectives.
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.


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

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f880141261

ℹ️ 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".

Comment thread crates/lance-graph-contract/src/canonical_node.rs
Comment thread crates/helix/src/residue.rs Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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 @.claude/board/PR_ARC_INVENTORY.md:
- Around line 38-50: The PR_ARC_INVENTORY.md entry for PR `#496` (lines 42-43, the
"Added" section) is incomplete—it documents only
ValueSchema/ValueTenant/VALUE_TENANTS and the ClassView default flip, but the
single merge commit 2e58e034 also shipped: Helix Signed360 codec (Sign enum,
Signed360 residue type, HemispherePoint::signed_lift,
ResidueEncoder::encode_signed), NodeGuid keystone with HHT-tier accessors
(HEEL/HIP/TWIG) and GuidParts decode with classid_read_mode registry support,
VALUE_TENANTS HelixResidue sizing correction from 48 bytes to 6 bytes, OCR
transcode implementation (BlockKind::entity_type, LayoutBlock::to_node_row), and
causal-edge test_build_fast boundary assertion fix. Expand lines 42-43 of the
"Added" bullet to document all five contribution categories as child items under
the single PR `#496` entry, so the PR_ARC entry fully reflects what was shipped in
merge commit 2e58e034.
🪄 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: 0c40d388-e4ac-459c-b4c9-03d187ba82ca

📥 Commits

Reviewing files that changed from the base of the PR and between 2e58e03 and f880141.

📒 Files selected for processing (10)
  • .claude/board/LATEST_STATE.md
  • .claude/board/PR_ARC_INVENTORY.md
  • .claude/board/TECH_DEBT.md
  • crates/causal-edge/src/tables.rs
  • crates/helix/src/lib.rs
  • crates/helix/src/placement.rs
  • crates/helix/src/residue.rs
  • crates/lance-graph-contract/src/canonical_node.rs
  • crates/lance-graph-contract/src/lib.rs
  • crates/lance-graph-contract/src/ocr.rs

Comment thread .claude/board/PR_ARC_INVENTORY.md
…gn-partition

Two codex P2s on #498:
- ENVELOPE_LAYOUT_VERSION 1→2 — the HelixResidue 48→6 B right-size shifted every
  downstream value-tenant offset; bump gates it so a v1 blob refuses to decode
  rather than read tenants from the wrong bytes (safe: nothing persisted under
  v1, FULL is POC-only).
- Signed360: encode |y| in 7 bits + sign in the partition (Pos⇒[128,255],
  Neg⇒[0,127]) so a near-rim negative lift (|y|≈0) can't round to 128 and read
  back as Pos. Regression test signed360_neg_sign_survives_near_rim_at_high_total.

Also adds the #498 PR_ARC_INVENTORY entry (CodeRabbit mis-attributed this PR's
helix/keystone/OCR/causal-edge work to #496 — corrected: it's #498's).

contract 623 lib, helix 73 lib + 7 doc green; clippy -D warnings + fmt clean.

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo
@AdaWorldAPI AdaWorldAPI merged commit 4acea26 into main Jun 16, 2026
6 checks passed
AdaWorldAPI pushed a commit that referenced this pull request Jun 16, 2026
…5-specialist framing)

Five specialists (cascade / family-codec / palette / dto-soa / truth-architect)
framed the merged #497 OCR-transcode plans against the post-#498 substrate. Two
showstoppers + 6-way drift; all 7 plans corrected:

- HelixResidue 48 B → 6 B everywhere (a stored Signed360 index, not a 48-byte field);
  budgets/carve rebaselined (Full 112, [32,144)); headers #496#498.
- "Morton-tile stacked-pyramid perturbation-shader" purged (does not exist; Morton
  rejected for Hilbert) → real primitives (mipmap pyramid / HHTL depth-cascade / CAKES).
- "reversible without a hash" reframed: no residue→rank inverse exists; node =
  identity → content-store lookup, codebook = repair signal (I-VSA-IDENTITIES).
- §0 tripwires: no ValueSchema::Ocr variant (ride Full/Compressed); Meta de-overloaded
  (confidence→Energy, provenance→Plasticity, OOV→content-store); TurbovecResidue is the
  edge codec, glyph→word uses DeepNSM CamCodes.
- master critical path 42→53 becomes 42→{50,51}→53 (resolves the open #497 CodeRabbit Major).

New ocr-probes-v1.md specs the 4 gating probes (OCR-RT/DET/POST/SCHEMA) for the
unmeasured claims (int8-exact LSTM, bit-reproducible diff, 200k-LOC 1:1 layout).
OCR-SCHEMA shipped as a contract test proving OCR rides an existing preset.
EPIPHANIES E-OCR-PLAN-DRIFT-1 + AGENT_LOG entry.

contract lib green; fmt clean.

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo
AdaWorldAPI added a commit that referenced this pull request Jun 16, 2026
docs(plans)+test: rebaseline #497 OCR plans to #498 + gating probes (5-specialist framing)
AdaWorldAPI pushed a commit that referenced this pull request Jun 16, 2026
…oaOwner cherry-pick + LanceVersionScheduler + SurrealMailboxView (D-PG-6)

Lands four tasks from the shortest-unblocking-path list surfaced after
PR #497-#501 + the AdaWorldAPI/surrealdb fork bump (lance/lance-index =7.0.0,
lancedb =0.30.0, ndarray exact-rev). All four meet at the single contract
trait `MailboxSoaView`, closing the cascade in one commit (E-UNBLOCK-CASCADE-1).

## Task 3 — `NiblePath::{from_guid_prefix, prefix}` (zero-dep, foundational)

Ontology-side keystone follow-up of PR #498's `classid → ReadMode` LE contract.
The 20-nibble `classid(8) | HEEL(4) | HIP(4) | TWIG(4)` prefix overflows the
16-nibble MAX_DEPTH: the deterministic fold drops the canon-reserved high u16
of classid (root-first pack: `classid_lo(4) | HEEL(4) | HIP(4) | TWIG(4)`),
returning None when the fold would be lossy. `prefix(d)` is the O(1) ancestor
view; `prefix(d).is_ancestor_of(self)` holds for every d ≤ self.depth (the
routing-cache view of a deeper class path).

  +7 tests in `hhtl::tests`; contract lib 619 → 632 green.

## Task 2 — `impl MailboxSoaView + MailboxSoaOwner for MailboxSoA<N>`

Cherry-pick of jolly-cori-clnf9 commit 463d71b (integrated-cognitive-planner-v1
§2 Seam #3, +149 LOC). Adds `pub phase: KanbanColumn` field + zero-copy
repr(transparent) slice impls (edges_raw, meta_raw) + the in-RAM Rubicon
driving-loop test (`test_in_ram_driving_loop_walks_rubicon_to_commit`). The
contract spine (#437/#439) now drives an actual loop end-to-end — no surreal,
no ractor bus needed for the in-process case.

  +1 driving-loop test; cognitive-shader-driver lib 85 → 86 green.

## Task 1 — `LanceVersionScheduler` over `VersionedGraph::versions()`

D-MBX-9-IN core impl (the CI-gated twin of the contract slice shipped 2026-05-31).
Lives in `crates/lance-graph/src/graph/scheduler.rs`. Wraps a `VersionedGraph` +
inner `VersionScheduler<S = NextPhaseScheduler>` and exposes:

- `drive_once(view, exec)`           — read current Lance version, lower to a move
- `drive_at_latest(view, exec)`      — fold `versions().last()` into a move
- `current_dataset_version()`        — typed `DatasetVersion` over nodes head

Closes `E-SUBSTRATE-IS-THE-SCHEDULER`'s OUT-direction end-to-end. The OUT
direction stays propose-not-dispose (R1): returned `KanbanMove` is for the
caller's `MailboxSoaOwner::try_advance_phase` to apply.

  +5 tests with real on-disk tempdir Lance (no mocks).

## Task 4 — `SurrealMailboxView<'a>` (D-PG-6 contract slice)

Read-only `MailboxSoaView` adapter the SurrealQL projection populates via
`from_columns(...)` — pure zero-copy borrow over the kv-lance scan's byte
buffers. Imports `MailboxSoaView` but NOT `MailboxSoaOwner` (compile-time
enforcement of `kanban.rs:1-21` "surreal=project-read-only, callcenter=commit").

`read_via_kv_lance()` returns the new typed `SurrealContainerError::BlockedColdBuild`
until the surrealdb fork dep in `Cargo.toml` is uncommented — kept off by default
to avoid the ~10 min cold surrealdb build for contributors who don't need it.
The contract surface is available today; the integration is one Cargo.toml edit
+ a SurrealQL projection body in `view.rs`.

  +4 tests; new `lance-graph-contract` dep in surreal_container/Cargo.toml;
  BLOCKED(C) marker flipped to RESOLVED.

## What this unblocks

- **D-MBX-9-IN-impl** — SHIPPED (the contract trait now has a Lance-backed implementor).
- **D-MBX-A6-P3** — still queued, BUT Seam #3 (the in-RAM loop) is now in-tree;
  a downstream session can wire the emit-side without depending on the unmerged
  jolly branch.
- **D-PG-6 (Rubicon kanban VIEW)** — contract slice SHIPPED; impl-side gated on
  `BlockedColdBuild` flip-on (one Cargo.toml uncomment + projection body).
- **Identity-architecture v1 §3 P-SCOPE-CLASSIFY** — solved (the bijection-width
  fix is deterministic + ancestor-preserving + falsifiable by tests).

## Tests + clippy

- lance-graph-contract:   **632** (+7 hhtl)
- cognitive-shader-driver: **86** (+1 driving-loop)
- lance-graph::scheduler:  **5** (new module, real Lance tempdir)
- surreal_container::view: **4** (new module)

All clippy `-D warnings` clean on the new files. Pre-existing lints in
lance-graph-ontology / lance-graph-planner / ndarray_bridge.rs are out of
session scope.

## Board hygiene (mandatory rule)

- LATEST_STATE.md — Contract Inventory PREPEND for the new types.
- EPIPHANIES.md — E-UNBLOCK-CASCADE-1: three independent landings converge on
  one trait surface, closing four queued deliverables in one commit.
- AGENT_LOG.md — task-by-task summary with test counts.

https://claude.ai/code/session_01Xzyc27Nx3f8WC5KzwfWfjx
AdaWorldAPI pushed a commit that referenced this pull request Jun 16, 2026
…oaOwner cherry-pick + LanceVersionScheduler + SurrealMailboxView (D-PG-6)

Lands four tasks from the shortest-unblocking-path list surfaced after
PR #497-#501 + the AdaWorldAPI/surrealdb fork bump (lance/lance-index =7.0.0,
lancedb =0.30.0, ndarray exact-rev). All four meet at the single contract
trait `MailboxSoaView`, closing the cascade in one commit (E-UNBLOCK-CASCADE-1).

## Task 3 — `NiblePath::{from_guid_prefix, prefix}` (zero-dep, foundational)

Ontology-side keystone follow-up of PR #498's `classid → ReadMode` LE contract.
The 20-nibble `classid(8) | HEEL(4) | HIP(4) | TWIG(4)` prefix overflows the
16-nibble MAX_DEPTH: the deterministic fold drops the canon-reserved high u16
of classid (root-first pack: `classid_lo(4) | HEEL(4) | HIP(4) | TWIG(4)`),
returning None when the fold would be lossy. `prefix(d)` is the O(1) ancestor
view; `prefix(d).is_ancestor_of(self)` holds for every d ≤ self.depth (the
routing-cache view of a deeper class path).

  +7 tests in `hhtl::tests`; contract lib 619 → 632 green.

## Task 2 — `impl MailboxSoaView + MailboxSoaOwner for MailboxSoA<N>`

Cherry-pick of jolly-cori-clnf9 commit 463d71b (integrated-cognitive-planner-v1
§2 Seam #3, +149 LOC). Adds `pub phase: KanbanColumn` field + zero-copy
repr(transparent) slice impls (edges_raw, meta_raw) + the in-RAM Rubicon
driving-loop test (`test_in_ram_driving_loop_walks_rubicon_to_commit`). The
contract spine (#437/#439) now drives an actual loop end-to-end — no surreal,
no ractor bus needed for the in-process case.

  +1 driving-loop test; cognitive-shader-driver lib 85 → 86 green.

## Task 1 — `LanceVersionScheduler` over `VersionedGraph::versions()`

D-MBX-9-IN core impl (the CI-gated twin of the contract slice shipped 2026-05-31).
Lives in `crates/lance-graph/src/graph/scheduler.rs`. Wraps a `VersionedGraph` +
inner `VersionScheduler<S = NextPhaseScheduler>` and exposes:

- `drive_once(view, exec)`           — read current Lance version, lower to a move
- `drive_at_latest(view, exec)`      — fold `versions().last()` into a move
- `current_dataset_version()`        — typed `DatasetVersion` over nodes head

Closes `E-SUBSTRATE-IS-THE-SCHEDULER`'s OUT-direction end-to-end. The OUT
direction stays propose-not-dispose (R1): returned `KanbanMove` is for the
caller's `MailboxSoaOwner::try_advance_phase` to apply.

  +5 tests with real on-disk tempdir Lance (no mocks).

## Task 4 — `SurrealMailboxView<'a>` (D-PG-6 contract slice)

Read-only `MailboxSoaView` adapter the SurrealQL projection populates via
`from_columns(...)` — pure zero-copy borrow over the kv-lance scan's byte
buffers. Imports `MailboxSoaView` but NOT `MailboxSoaOwner` (compile-time
enforcement of `kanban.rs:1-21` "surreal=project-read-only, callcenter=commit").

`read_via_kv_lance()` returns the new typed `SurrealContainerError::BlockedColdBuild`
until the surrealdb fork dep in `Cargo.toml` is uncommented — kept off by default
to avoid the ~10 min cold surrealdb build for contributors who don't need it.
The contract surface is available today; the integration is one Cargo.toml edit
+ a SurrealQL projection body in `view.rs`.

  +4 tests; new `lance-graph-contract` dep in surreal_container/Cargo.toml;
  BLOCKED(C) marker flipped to RESOLVED.

## What this unblocks

- **D-MBX-9-IN-impl** — SHIPPED (the contract trait now has a Lance-backed implementor).
- **D-MBX-A6-P3** — still queued, BUT Seam #3 (the in-RAM loop) is now in-tree;
  a downstream session can wire the emit-side without depending on the unmerged
  jolly branch.
- **D-PG-6 (Rubicon kanban VIEW)** — contract slice SHIPPED; impl-side gated on
  `BlockedColdBuild` flip-on (one Cargo.toml uncomment + projection body).
- **Identity-architecture v1 §3 P-SCOPE-CLASSIFY** — solved (the bijection-width
  fix is deterministic + ancestor-preserving + falsifiable by tests).

## Tests + clippy

- lance-graph-contract:   **632** (+7 hhtl)
- cognitive-shader-driver: **86** (+1 driving-loop)
- lance-graph::scheduler:  **5** (new module, real Lance tempdir)
- surreal_container::view: **4** (new module)

All clippy `-D warnings` clean on the new files. Pre-existing lints in
lance-graph-ontology / lance-graph-planner / ndarray_bridge.rs are out of
session scope.

## Board hygiene (mandatory rule)

- LATEST_STATE.md — Contract Inventory PREPEND for the new types.
- EPIPHANIES.md — E-UNBLOCK-CASCADE-1: three independent landings converge on
  one trait surface, closing four queued deliverables in one commit.
- AGENT_LOG.md — task-by-task summary with test counts.

https://claude.ai/code/session_01Xzyc27Nx3f8WC5KzwfWfjx
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants