docs(witness): B2 — document the two-witness-arc boundary (no WitnessArcEvaluator trait)

[AdaWorldAPI]

Summary

Resolves the parked B2 item — "wire the perturbation-sim witness arc into the contract WitnessTable" — which was deferred because it appeared to need a new WitnessArcEvaluator trait (crossing the no-new-trait iron rule). Put through the 5+3 critical-decision council (5 analyst agents + 3 brutal critics, all reading both files in full). Unanimous verdict: do NOT build the trait. The resolution is documentation, not code.

The finding

"witness arc" names two genuinely different objects:

	perturbation-sim::witness	lance-graph-contract::witness_table
arc is	a signed &[f64] weight vector	a chain of 6-bit W-slot indices
operation	inner product ∑ field·arc (particle == wave via Parseval/FWHT)	index → WitnessEntry { mailbox_ref:u32, spo_fact_ref:Option<u64> } identity resolution
value category	real field magnitude	opaque identity handle

They share only the word and the Markov-reference-chain shape. Welding them under a WitnessArcEvaluator trait would be:

• AP6 (one-impl trait, zero call-sites) + AGI-as-glove "never a new trait" violation;
• a dependency-direction inversion — the zero-dep contract crate would gain a perturbation-sim dep / f64 field semantics (baton-handoff-auditor: CATCH-CRITICAL);
• a register-loss / Frankenstein conflation (I-VSA-IDENTITIES).

integration-lead confirmed the genuine wiring is the downstream deliverable D-MBX-A3, gated on D-MBX-A2 (the plan's current gating gap) + OQ-11.2 + a §0 dependency-direction ruling — i.e. not unblocked yet.

Council (unanimous)

convergence-architect DROP · iron-rule-savant REJECT-trait · dto-soa-savant FITS-COLUMN-as-free-fn · dilution-collapse-sentinel KEEP-SEPARATE · truth-architect PROVEN-math · brutally-honest-tester Option-B-LAND · baton-handoff-auditor CATCH-CRITICAL · integration-lead DEFER.

What changed (doc + board only — no type or dependency change)

• crates/perturbation-sim/src/witness.rs — added a "NOT the same witness arc as contract::witness_table" section; corrected a doc overclaim that truth-architect + brutally-honest-tester both caught: per-arc cost was stated q·O(N) but witness_from_spectrum re-transforms each arc, so the honest figure is q·O(N log N) (narrows to q·O(N) only for precomputed/structured arc spectra). The amortized quantity is the field transform.
• crates/lance-graph-contract/src/witness_table.rs — reciprocal "different object" section; states any future wiring is a consumer-side free function over a borrowed &[f64] column, never a trait on the zero-dep crate.
• Board: E-WITNESS-ARC-TWO-OBJECTS-1 (EPIPHANIES), TD-WITNESS-EVAL-WIRING-1 (TECH_DEBT, with the three gating prerequisites + paid-when), AGENT_LOG run entry.

Math validated (reviewer-only, no behavior change)

truth-architect independently re-proved the Parseval particle == wave identity (FWHT is the symmetric involution-up-to-N the identity requires; tested to 1e-9) and the NaN/degenerate safety as PROVEN-in-code. Only the asymptotic doc bookkeeping was off; now fixed. No code or test behavior changed.

Tests

• cargo test -p lance-graph-contract --lib witness_table — 3/3
• cargo test --manifest-path crates/perturbation-sim/Cargo.toml witness — 4/4
• cargo fmt --check (both crates) — clean

🤖 Generated with Claude Code

https://claude.ai/code/session_01CcpLeEC3XK8Eye53GKBVvi

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Updated architecture and design documentation to clarify relationships between internal components.
  • Documented important distinctions between related architectural concepts to prevent future confusion.
  • Added technical debt entries detailing deferred integration work with specified gating requirements and implementation constraints.
  • Expanded module-level documentation with cost analysis and architectural decision rationale.

[coderabbitai]

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 45 minutes and 48 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.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

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: 70e239cf-f2d3-4dc6-9eac-936f128c87f2

📥 Commits

Reviewing files that changed from the base of the PR and between bb3cd5c and df5159c.

📒 Files selected for processing (1)

• crates/perturbation-sim/examples/witness.rs

📝 Walkthrough

Walkthrough

Documentation-only PR on the claude/witness-arc-boundary-doc branch. It clarifies that perturbation-sim::witness (numeric inner-product over &[f64]) and lance-graph-contract::witness_table (W-slot → identity tuple resolution) are distinct objects, records a council decision against creating a unifying WitnessArcEvaluator trait, corrects an overstated per-arc complexity claim, and logs an open tech-debt item for the deferred wiring step.

Changes

Witness Arc Boundary Documentation

Layer / File(s)	Summary
In-source doc clarifications for both witness arc types crates/perturbation-sim/src/witness.rs, crates/lance-graph-contract/src/witness_table.rs	perturbation-sim::witness module docs are rewritten to elaborate the standing-wave/Parseval interpretation, reframe amortization around field_spectrum + witness_from_spectrum, correct the per-arc cost from q·O(N) to O(N log N)-shaped, and add a "NOT the same witness arc" section. lance-graph-contract::witness_table gains a parallel comment block distinguishing its W-slot identity-tuple arc from the numeric evaluator.
Board logs: decision record, epiphany, and tech-debt entry .claude/board/AGENT_LOG.md, .claude/board/EPIPHANIES.md, .claude/board/TECH_DEBT.md	AGENT_LOG.md prepends a B2-resolved entry documenting the no-WitnessArcEvaluator-trait decision. EPIPHANIES.md formalizes the two-object distinction and the corrected complexity claim. TECH_DEBT.md opens item TD-WITNESS-EVAL-WIRING-1 with the downstream wiring deliverable (D-MBX-A3) and its gating requirements (D-MBX-A2, OQ-11.2, dependency-direction constraint).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• AdaWorldAPI/lance-graph#427: Introduced lance-graph-contract::witness_table's W-slot identity arc; this PR directly extends that work by clarifying how it differs from perturbation-sim::witness and records the decision not to bridge them.

Poem

🐇 Two arcs stood apart in the field,
One numeric, one W-slot sealed.
No trait shall bind what must stay free —
The seam is the doc, plain to see.
Hop on, the debt log marks the way! ✨

🚥 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 summarizes the main change: documenting the boundary between two distinct witness-arc concepts and the decision not to create a unifying trait.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

• 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/perturbation-sim/src/witness.rs`:
- Around line 18-23: The documentation comment in witness.rs now describes the
asymptotic cost as O(N log N) per arc, but the example file
crates/perturbation-sim/examples/witness.rs still documents the old cost model
as O(N) per arc. Update the cost model description in the example file to match
the corrected documentation, ensuring both explain that each arc transformation
costs O(N log N) and the total for q arcs is O(N log N) + q·O(N log N), or O(N
log N) + q·O(N) when optimized with precomputed arc spectrum or
structured/sparse patterns.

🪄 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: 1cf32eea-0efc-4cea-ba37-af95c2f204bf

📥 Commits

Reviewing files that changed from the base of the PR and between ca810e5 and bb3cd5c.

📒 Files selected for processing (5)

• .claude/board/AGENT_LOG.md
• .claude/board/EPIPHANIES.md
• .claude/board/TECH_DEBT.md
• crates/lance-graph-contract/src/witness_table.rs
• crates/perturbation-sim/src/witness.rs