lance-graph-report: CoordSpec::MaskSet, a set coordinate over resident masks

[AdaWorldAPI]

Why

A report coordinate held one value per row, so there was no way to put a many-to-many axis on it, such as a document's tags in the paperless-ngx sense. tesseract-paperless::axes names this gap: "count per tag" ran as one scalar report per tag instead of one pivot.

What

• The new coordinate. CoordSpec::MaskSet { base, count }: member m is the resident mask base + m.
  • A row lands in every member whose mask contains it: none, one, or several.
  • As a result, this dimension's cells do not sum to the selected population. A row with two tags counts once under each tag.
• Planning. It is planned as Provider::MaskPlanes: each member is one mask plane, read where it already sits. It is always a partition and never the fold key.
• Errors.
  • A member mask missing from the batch is refused with UnknownMask.
  • count == 0 is refused with the new ReportError::EmptyMaskSet.
• API change. CoordSpec::field() now returns Option<FieldId>, because a mask set reads no lane. explain and render name the set.
• Test oracle. The per-row oracle (tests/common) now puts each row into the cartesian product of its memberships across the dimensions.

Tests

tests/mask_set.rs has 6 tests. Each is checked against the per-row oracle:

• a tag set on its own;
• a tag set crossed with an ordinal fold key, both dense and sparse;
• a tag set under a selection;
• the per-tag counts equal the number of (row, tag) memberships and exceed the number of tagged rows;
• a missing mask is refused;
• an empty set is refused;
• explain output names the set.

The test fixture asserts that it contains both untagged rows and rows with at least two tags. Without both, the tests would say nothing about set behaviour.

Disable runs. For each of three guards, I removed it, confirmed the test failed, then restored it:

• the member filter reading the validity plane instead (three tests fail);
• the empty-set guard;
• a missing mask read as the validity plane.

Other checks. The crate passes 29 tests. lance-graph-report-ogar still passes. clippy -D warnings and fmt are clean.

Open

The cost is still one population pass per member, the same as before. What this PR adds is one plan, one result space and one rendered report, not fewer passes. A single-pass fold over all members would need a keyed multi-membership aggregation in mask-RISC, which does not exist yet.

Board entry: entries/2026-09-25-report-mask-set-coordinate.md; the entries index is regenerated and the supersession index is unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DCEP2fZdHYdMCtcEVcTpS2

---

Generated by Claude Code

Summary by CodeRabbit

• New Features
  • Reports can now use a set of consecutive masks as a coordinate. A row may contribute to multiple mask members or none, enabling multi-membership counts and cross-tabulations with other coordinates.
  • Mask-set reports are supported in dense and sparse plans, with clearer labels for the set and its members.
• Bug Fixes
  • Mask lookups now report missing masks and empty sets explicitly. Plane positions beyond the supported range are rejected instead of wrapping to an incorrect plane.

[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: 7c97c885-3490-4839-af9b-eff080d9c245

📥 Commits

Reviewing files that changed from the base of the PR and between 73ed543 and 53c820f.

📒 Files selected for processing (11)

• .claude/board/entries/2026-09-25-report-mask-set-coordinate.md
• .claude/board/entries/README.md
• crates/lance-graph-report/src/batch.rs
• crates/lance-graph-report/src/exec.rs
• crates/lance-graph-report/src/explain.rs
• crates/lance-graph-report/src/lib.rs
• crates/lance-graph-report/src/plan.rs
• crates/lance-graph-report/src/render.rs
• crates/lance-graph-report/src/selection.rs
• crates/lance-graph-report/tests/common/mod.rs
• crates/lance-graph-report/tests/mask_set.rs

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

The report planner and executor now support coordinates over consecutive resident masks. Rows can belong to multiple mask-set members or none. Checked plane resolution, member filtering, plan explanations, rendering, and test-oracle coverage are updated.

Changes

Mask-Set Coordinates

Layer / File(s)	Summary
Coordinate contract and resolution crates/lance-graph-report/src/plan.rs, crates/lance-graph-report/src/lib.rs, crates/lance-graph-report/src/batch.rs, crates/lance-graph-report/src/exec.rs, crates/lance-graph-report/src/selection.rs	Adds CoordSpec::MaskSet, checked member-mask lookup, and error handling for empty sets, unknown masks, and plane indexes beyond u16. Mask selections use checked plane resolution.
Mask-plane execution crates/lance-graph-report/src/exec.rs	Adds mask-plane providers and member filters. Fold keys remain ordinal lanes, and sparse partition discovery uses the full domain for mask-plane coordinates.
Plan and member reporting crates/lance-graph-report/src/explain.rs, crates/lance-graph-report/src/render.rs	Plan explanations identify mask-plane providers and display mask-set ranges. Member labels use the mask ID when available.
Multi-membership validation crates/lance-graph-report/tests/common/mod.rs, crates/lance-graph-report/tests/mask_set.rs, .claude/board/entries/2026-09-25-report-mask-set-coordinate.md, .claude/board/entries/README.md	The test oracle assigns rows to every matching cell. Tests cover dense and sparse plans, selection, errors, and explanations. The board report and index record the change and its test evidence.

Priority: ➖ Normal

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CoordSpec
  participant resolve
  participant AbiBatch
  participant execute
  participant member_filter
  CoordSpec->>resolve: Supply MaskSet base and count
  resolve->>AbiBatch: Build mask-position lookup
  AbiBatch-->>resolve: Return resident plane positions
  resolve-->>execute: Return Provider::MaskPlanes
  execute->>member_filter: Select a mask-set member
  member_filter->>AbiBatch: Read the resident mask plane

Loading

Suggested reviewers: claude

Merge Risk: ⚪ Minimal · up to 53c82

The mask-set change is ready for normal merge checks; no actionable issue remains identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding CoordSpec::MaskSet as a set coordinate over resident masks.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 75.76% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 33 functions across 9 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 the masks in rows,
Then hops through each place membership grows.
Some rows choose none, some choose a few,
The oracle checks each matching view.
“The planes resolve,” the rabbit sings,
And leaves soft prints beside the strings.}

_{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_f2ae84ba-e636-43ca-9688-193e72a39754)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9e3a00656a

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