cognitive-shader-driver: dispatch stops materializing O(rows²); one SPOFC candidate per row

[AdaWorldAPI]

Two changes to one ShaderDriver::dispatch, found in order while tracing it end to end:

1. It no longer materializes O(rows²) to return 8 hits. Output is unchanged.
2. A row supported several ways is now one candidate carrying that support as evidence (a SPOFC record), instead of several candidate slots that cancel each other in the XOR braid. This one intentionally changes the output.

1. Materialization (output digest unchanged)

The module doc claims "no allocations beyond top-k + edges". A counting global allocator (tests/dispatch_trace.rs) measured one dispatch, after a warm-up:

rows	before	after part 1
16	23 KB, 44 allocs	1.2 KB, 5 allocs
256	5.3 MB, 530 allocs	2.2 KB, 5 allocs

• Content pre-pass. It pushed two hits per resonant pair into a Vec (O(rows²)), then sorted it and cut it to 8. TopHits now keeps the best 8 as they arrive, with the same tie order as the stable sort.
• p64-bridge cascade. It returned up to 256 candidates per row, of which the driver read 4. The new cascade_nearest::<K> returns only the K nearest and does not allocate. It shares one candidate walk with cascade, which is unchanged. CascadeHit is now Copy.
• Evidence.
  • A digest over every crystal field (60 configurations × 3 dispatches) is identical before and after: 355d5fccbc424763.
  • Equivalence tests compare each replacement against the collect-sort-truncate it replaces.
  • Disable runs turn the allocation pin red.

2. SPOFC: one candidate per row, support kept

The problem.

• Stage [4] builds cycle_fp = ⊕ R^{cycle_index} · row, and a row's cycle_index is its position.
• Stage [3] offered every supporting relationship as its own slot: each content pair, and each P64 cascade hit.
• So a row supported N ways contributed N identical terms, and XOR cancels them in pairs.
• On empty predicate planes, 36 of 60 dispatches had a repeated row in top-k. In some of them, the strongest row vanished from cycle_fp.

The change. Each surviving row is now one candidate, and its relationships aggregate into a SPOFC record:

field	value
subject	the row
predicates	union of every relationship's bits
object	the best-resonance partner (Row(r) or a P64 Palette(target))
truth	TruthU8 { f = best resonance, c = m·255/(m+k) }
support	the relationship count m

• Ranking uses the best resonance, and cycle_index stays the rotation basis. Each selected row enters the braid exactly once.
• No SPOFC type existed in code, only in docs. The record follows the one code precedent, arm-discovery's CandidateTriple/TruthU8.
• The confidence formula is shared, not copied: evidence_confidence_u8 was extracted from arm_to_truth_u8 and is now used by both.

Effects on what is emitted and cached (60 dispatches each, old vs new):

predicate planes	cycle_fp changed	edges changed	top-k changed	dispatches with a repeated row
non-empty	12	60	60	0 → 0
empty	48	48	48	36 → 0

• With only the predicate union disabled, non-empty-plane edges change in 12/60 instead of 60/60. So 48 of those edge changes are the union adding CausalMask bits (predicates & 7) that the old per-slot emission dropped.
• Anything keyed on cycle_fp or the emitted edges (caching, retrieval, replay) will see different values for these dispatches. That is the intended correction. The part-1 digest therefore no longer matches after part 2.
• Allocation: one more, for the candidate table (6 in total). The count is still constant in rows, and bytes grow by 28 per surviving row (4-byte row id + 24-byte SPOFC record). dispatch_trace pins both.

Tests, each disable-verified red then green:

test	what it covers	disable that turns it red
repeated_support_is_one_candidate_and_survives_the_braid	empty-plane regression: k = 8 distinct rows, cycle_fp equals the one-term-per-row XOR, the strongest row is present	re-offering every relationship
repeated_support_is_retained_as_spofc_evidence	support = n−1 per row, with the matching confidence	not counting support
p64_targets_survive_as_spofc_support	four P64 targets become one candidate with support 4, object a real Palette target	not counting support
spofc_predicates_are_the_union_of_supporting_relationships	predicate union	dropping or overwriting the union

The union test is new because removing the union had left all 111 lib tests green. p64_target_identity_probe is re-pinned from "n > 1 identical edges" to exactly one edge.

Not in this PR (follow-up, draft)

• The SPOFC record currently ends at a debug_assert. CE64 emission still packs s = row%256, p = 0, o = (row/4)%256 and f = c = resonance.
• CE64's 24-bit S/P/O could hold the target as palette256³. The driver just doesn't write it there.
• Writing SPOFC into CE64, and carrying that evidence across cycles without recounting it as fresh support, is the separate follow-up.
• The prefilter row list (passed_rows, 4 bytes per row) is also still open.

Checks

• cognitive-shader-driver: all 9 test binaries pass; clippy -D warnings and fmt are clean.
• lance-graph-arm-discovery: 42 tests plus the new doctest pass.
  • Its --all-targets clippy fails on 14 doc-list lints at translator.rs:28-41, a comment this PR does not touch. The crate is not a workspace member.
• p64-bridge: cascade tests pass.
  • One needless_range_loop clippy error in an existing test fails the same way without this PR.

Board entry: .claude/board/entries/2026-09-25-dispatch-materialization-trace.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_019HnekoM1EidTwQLS3oFVFm

---

Generated by Claude Code

Summary by CodeRabbit

• Performance
  • Cascade searches can retrieve the nearest candidates without generating and sorting every result.
  • Dispatch processing limits downstream work to the top eight ranked hits and keeps allocation growth bounded as rows increase.
• Reliability
  • Multiple supporting relationships for a row are combined into one candidate, with support count and predicate evidence reflected in its ranking and confidence.
  • Equal-distance cascade results retain candidate order.
  • Duplicate target relationships from one source row now produce a single emitted result rather than repeated identical results.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Essentials

Run ID: f8d9ab10-b6f9-4a6d-b493-a0310a969dff

📥 Commits

Reviewing files that changed from the base of the PR and between 8a85595 and ee4e145.

📒 Files selected for processing (6)

• .claude/board/entries/2026-09-25-dispatch-materialization-trace.md
• crates/cognitive-shader-driver/Cargo.toml
• crates/cognitive-shader-driver/src/driver.rs
• crates/cognitive-shader-driver/tests/dispatch_trace.rs
• crates/cognitive-shader-driver/tests/p64_target_identity_probe.rs
• crates/lance-graph-arm-discovery/src/translator.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• .claude/board/entries/2026-09-25-dispatch-materialization-trace.md

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

---

📝 Walkthrough

Walkthrough

Dispatch now aggregates relationship support into one candidate per prefiltered row and retains up to eight ranked hits. Cascade search exposes a fixed-size nearest-hit API. Tests and board entries describe aggregation, allocation measurements, and open trace items.

Changes

Dispatch candidate materialization

Layer / File(s)	Summary
Evidence confidence calculation crates/lance-graph-arm-discovery/src/translator.rs, crates/cognitive-shader-driver/Cargo.toml	evidence_confidence_u8 calculates confidence with integer arithmetic. arm_to_truth_u8 uses the helper, and the driver adds the crate dependency.
Bounded cascade candidate selection crates/p64-bridge/src/lib.rs	cascade_nearest<K> visits candidates through a shared visitor and returns up to K hits in distance order. Tests compare its results with prefixes from cascade, including ties.
Per-row candidate aggregation and dispatch ranking crates/cognitive-shader-driver/src/driver.rs, crates/cognitive-shader-driver/tests/p64_target_identity_probe.rs	Content matches and cascade results add support to one candidate per prefiltered row. The driver ranks candidates by best relationship resonance and retains up to eight hits for downstream processing. Tests cover aggregation, evidence, predicate unions, and emitted CE64 counts.
Allocation checks and trace updates crates/cognitive-shader-driver/tests/dispatch_trace.rs, .claude/board/entries/2026-09-25-dispatch-materialization-trace.md, .claude/board/entries/README.md, .claude/board/SUPERSESSION-INDEX.md	The allocation test updates its per-row allowance. Board entries record aggregation details, allocation observations, open trace items, and index count changes.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant ShaderDriver
  participant CognitiveShader
  participant CandidateTable
  participant TopHits
  ShaderDriver->>CognitiveShader: Request up to four nearest cascade hits
  CognitiveShader-->>ShaderDriver: Return cascade hits
  ShaderDriver->>CandidateTable: Add content and cascade relationship support
  CandidateTable-->>ShaderDriver: Return supported row candidates
  ShaderDriver->>TopHits: Rank candidates and retain up to eight hits
  TopHits-->>ShaderDriver: Return retained hits

Loading

Suggested reviewers: claude

Merge Risk: ⚪ Minimal · up to ee4e1

The dispatch change is mergeable after normal checks; no actionable behavior regression remains identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 40 functions across 5 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: dispatch avoids O(rows²) materialization and creates one SPOFC candidate per row.

Full details: Docstring Coverage

Explanation

Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 40 functions across 5 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

_{A rabbit counts each row with care,
One candidate gathers support to spare.
Four nearby hits hop into view,
Eight ranked results pass onward through.
The tests keep tie order neat,
While board notes track each measured beat.}

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

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b5729680-bfb9-41c0-9a0d-6a1855c17220)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_efd91bf4-40f9-4cf5-abb5-b17e981c4cf1)