Count plan-ledger refs as citable, not delivered

[realtonyyoung]

AI-3090 (no GitHub issue)

What & why

A plan_ledger row shows only part of a lane entry (one task of a snapshot, a document's key and path without its text), yet the renderer recorded every ref it printed as a delivered event, so coverage could read complete while canonical content was withheld. Ledger refs now go to a separate Citable set: a handle or literal ref still expands for citation, but only an events page or body read delivers the entry.

Where to look

• JudgeLedger.TryExpand consults delivered and citable events; IsDelivered and coverage read delivered only.
• The page persists the refs as citable, written only when non-empty.

Verification

• EvidenceCoverageMeasureTests 12/12, EvidencePageRendererTests 8/8, EvidenceFirstViewReaderTests 5/5, JudgeLedgerTests 5/5.
• A lane shown only through the ledger reports unread_ranges while consulted, and is complete once read_events delivers it; with the renderer marking ledger refs delivered again, that test fails.

🤖 Generated with Claude Code

[linear-code]

AI-3090

[qodo-code-review]

PR Summary by Qodo

Keep plan-ledger refs citable without counting them as delivered

🐞 Bug fix 🧪 Tests 🕐 20-40 Minutes

AI Description

• Separate plan-ledger citations from delivered events so partial rows cannot falsely complete
 coverage.
• Preserve citation expansion while reporting ledger-only lanes as unread until their events are
 served.
• Persist citable refs and add regression tests for rendering, coverage, and ledger round-trips.

Diagram

graph TD
  PL["Plan ledger"] --> R["Page renderer"] --> P["JSONL pages"] --> L["Judge ledger"] -->|"citable or delivered"| X["Citation expansion"]
  EV["Events read"] --> R
  L -->|"delivered only"| C["Coverage check"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Derive citable refs from stored citations

• ➕ Avoids a new JSONL page field.
• ➖ Requires identifying plan-ledger citations after reading pages.
• ➖ Couples citation eligibility to page-text or page-type reconstruction.

Recommendation: Keep the explicit citable ranges. They preserve the distinction at rendering time and make replayed ledgers unambiguous; deriving them later saves a field but adds fragile reconstruction logic.

Files changed (10) +71 / -30

Bug fix (6) +42 / -19

EvidenceCoverageMeasure.csClarify that plan-ledger lanes remain unread +1/-1

Clarify that plan-ledger lanes remain unread

• Updates the coverage comment to reflect that a plan-ledger page consults a lane without delivering its entries. The existing unread-range check now receives only genuinely delivered events from the ledger.

src/Capacitor.Cli.Core/Eval/Evidence/EvidenceCoverageMeasure.cs

EvidencePageRenderer.csRecord plan-ledger refs as citable instead of delivered +10/-7

Record plan-ledger refs as citable instead of delivered

• Routes document and task refs on plan-ledger pages into citable ranges while leaving their delivered revision ranges empty. Events-page rendering continues to record delivered revisions.

src/Capacitor.Cli.Core/Eval/Evidence/EvidencePageRenderer.cs

JudgeLedger.csSeparate citation eligibility from event delivery +18/-8

Separate citation eligibility from event delivery

• Builds a CitableEvents set from page data. Literal citation expansion accepts citable or delivered refs, while IsDelivered and coverage remain restricted to delivered events.

src/Capacitor.Cli.Core/Eval/Evidence/JudgeLedger.cs

JudgeLedgerPage.csAdd citable ranges to ledger pages +6/-2

Add citable ranges to ledger pages

• Adds a Citable property for plan-ledger refs and includes it in page equality. Clarifies that ledger sources are consulted but their entries are not delivered.

src/Capacitor.Cli.Core/Eval/Evidence/JudgeLedgerPage.cs

JudgeLedgerReader.csRead optional citable ranges from ledger pages +2/-1

Read optional citable ranges from ledger pages

• Parses persisted citable ranges into JudgeLedgerPage, defaulting to an empty list when the field is absent.

src/Capacitor.Cli.Core/Eval/Evidence/JudgeLedgerReader.cs

JudgeLedgerWriter.csPersist non-empty citable ranges +5/-0

Persist non-empty citable ranges

• Writes a citable array on pages that contain citation-only refs, omitting the field on other pages.

src/Capacitor.Cli.Core/Eval/Evidence/JudgeLedgerWriter.cs

Tests (4) +29 / -11

EvidenceCoverageMeasureTests.csVerify ledger-only lanes remain unread +17/-6

Verify ledger-only lanes remain unread

• Changes the regression case to require an unread-ranges omission when a lane appears only in the plan ledger. It also verifies that its refs remain citable but undelivered until an events page serves the entries.

test/Capacitor.Cli.Core.Tests.Unit/Eval/Evidence/EvidenceCoverageMeasureTests.cs

EvidenceFirstViewReaderTests.csExpect citation-only refs in the seeded first view +2/-1

Expect citation-only refs in the seeded first view

• Checks that the server plan-ledger page stores its shown refs in Citable rather than Revisions.

test/Capacitor.Cli.Core.Tests.Unit/Eval/Evidence/EvidenceFirstViewReaderTests.cs

EvidencePageRendererTests.csVerify plan-ledger rendering delivers no events +3/-2

Verify plan-ledger rendering delivers no events

• Retains assertions for document and task citation handles while requiring citable ranges and no delivered revisions.

test/Capacitor.Cli.Core.Tests.Unit/Eval/Evidence/EvidencePageRendererTests.cs

JudgeLedgerTests.csRound-trip citable refs without marking them delivered +7/-2

Round-trip citable refs without marking them delivered

• Tests JSONL persistence and reconstruction of citable ranges, citation expansion, and the absence of delivered lane events. It also checks that pages without citable refs omit the field.

test/Capacitor.Cli.Core.Tests.Unit/Eval/Evidence/JudgeLedgerTests.cs

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Coverage misses unread plan lanes ✓ Resolved

Description

EvidencePageRenderer.Render no longer puts plan-ledger refs in Revisions, but ForRetrieval
checks for their unread entries only when no other undelivered omission exists. If the judge sees
every ledger row for one lane but never opens an unrelated source, coverage reports the unconsulted
source and omits the unread range for the ledger lane.

Code

src/Capacitor.Cli.Core/Eval/Evidence/EvidencePageRenderer.cs[122]

+        var runs = planLedger || source is null ? [] : Runs(source, revisions);

Relevance

●●● Strong

Accepted evidence fixes correctness gaps in this area; the finding exposes an uncovered interaction
in the same coverage behavior.

PR-#1287

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changed renderer leaves ledger refs out of delivered revisions. The ledger still marks their
lanes consulted, so they avoid SourcesNotConsulted; an unrelated unconsulted source then makes the
guard false before the only unread-range count runs.

src/Capacitor.Cli.Core/Eval/Evidence/EvidencePageRenderer.cs[119-125]
src/Capacitor.Cli.Core/Eval/Evidence/JudgeLedger.cs[17-26]
src/Capacitor.Cli.Core/Eval/Evidence/EvidenceCoverageMeasure.cs[19-31]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Plan-ledger refs are now citable rather than delivered, but retrieval coverage skips its unread-range check whenever another source already has an undelivered omission.
## Fix Focus Areas
- src/Capacitor.Cli.Core/Eval/Evidence/EvidenceCoverageMeasure.cs[23-31]
- test/Capacitor.Cli.Core.Tests.Unit/Eval/Evidence/EvidenceCoverageMeasureTests.cs[243-266]
## Recommended Fix
Calculate unread ranges for consulted plan-ledger lanes even when another undelivered omission exists, without duplicating omissions already accounting for the same unread events. Add a test with a ledger-only lane and a separate unconsulted source that expects both gaps.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 64 rules

✅ Cross-repo context — repo relationships

  Explored: repo: kurrent-io/kcap-server (sha: 834110ac) — View relationship

Review mode: ⚖️ Balanced: This push changes runtime evidence-coverage semantics across multiple omission paths, with meaningful correctness impact, but is localized enough that one careful review pass should suffice.

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit 17a2720

Results up to commit ae23540 ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Coverage misses unread plan lanes ✓ Resolved

Description

EvidencePageRenderer.Render no longer puts plan-ledger refs in Revisions, but ForRetrieval
checks for their unread entries only when no other undelivered omission exists. If the judge sees
every ledger row for one lane but never opens an unrelated source, coverage reports the unconsulted
source and omits the unread range for the ledger lane.

Code

src/Capacitor.Cli.Core/Eval/Evidence/EvidencePageRenderer.cs[122]

+        var runs = planLedger || source is null ? [] : Runs(source, revisions);

Relevance

●●● Strong

Accepted evidence fixes correctness gaps in this area; the finding exposes an uncovered interaction
in the same coverage behavior.

PR-#1287

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changed renderer leaves ledger refs out of delivered revisions. The ledger still marks their
lanes consulted, so they avoid SourcesNotConsulted; an unrelated unconsulted source then makes the
guard false before the only unread-range count runs.

src/Capacitor.Cli.Core/Eval/Evidence/EvidencePageRenderer.cs[119-125]
src/Capacitor.Cli.Core/Eval/Evidence/JudgeLedger.cs[17-26]
src/Capacitor.Cli.Core/Eval/Evidence/EvidenceCoverageMeasure.cs[19-31]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Plan-ledger refs are now citable rather than delivered, but retrieval coverage skips its unread-range check whenever another source already has an undelivered omission.
## Fix Focus Areas
- src/Capacitor.Cli.Core/Eval/Evidence/EvidenceCoverageMeasure.cs[23-31]
- test/Capacitor.Cli.Core.Tests.Unit/Eval/Evidence/EvidenceCoverageMeasureTests.cs[243-266]
## Recommended Fix
Calculate unread ranges for consulted plan-ledger lanes even when another undelivered omission exists, without duplicating omissions already accounting for the same unread events. Add a test with a ledger-only lane and a separate unconsulted source that expects both gaps.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[realtonyyoung]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 17a2720