D-MAR-1: FieldMask/WideFieldMask difference + is_subset_of (re-derived from plan)

[AdaWorldAPI]

Re-derives D-MAR-1 from mask-algebra-revision-read-v1 and from source on current main. The reverted #1088 diff was not consulted — per the #1093 arc entry, the six reverted commits are not citable inputs.

What lands

FieldMask gains difference (self & !other) and is_subset_of, both #[inline] pub const fn, mirroring the existing intersect/union/is_disjoint exactly — Copy preserved, no existing signature touched. WideFieldMask gains the same pair with the (Small, Small) fast path plus the tier-agnostic fold, whose trim-and-demote normalization is load-bearing for the canonical PartialEq/Hash contract from #651.

Why they're on the critical path, per plan §0 F4 (substrate-first STOP): a provenance surface is built from set difference and containment, and the rejected external draft hand-rolled an entire EvidenceMask trait because these two methods were absent. The fix is the methods, not the trait.

Also removes chunks_view, which cloned both operands into fresh Vecs on every wide op. zip_fold now reads operands in place via chunk_at; the only allocation is the owned result, which an owned-result operator must produce anyway. It was private with exactly two call sites, both inside zip_fold, so there is no external surface — and intersect/union inherit the fix. Its materialization role is superseded by the separate stencil arena (operator-ruled: arena separate, masks stay values), which is its own change and is not in this PR.

Gates

G1–G4 from plan §3, each with the anti-half the plan requires — G1 alone is satisfied by difference ≡ EMPTY, G2 alone by is_subset_of ≡ true. All four disable-runs verified red-then-green:

sabotage	result
difference returns EMPTY	G1-anti red, G1 still green
is_subset_of returns true	G2-anti red
zip_fold length max → min	G3 red (cross-width, both argument orders)
trim/demote bypassed	G4 red — plus two pre-existing canonical-form tests red, so the rewritten fold is covered by the existing regression suite too

Gate correction, measured. The plan's stated G4 disable-run — bypass trim/demote, expect the Small-equivalent comparison to fail — is unfalsifiable as written. Since #651 gave WideFieldMask a representation-independent PartialEq/Hash, equality survives the bypass by design; that assertion cannot fail. G4 therefore asserts max_fields() == 64 on the demoted result, an observable that can fail, and the disable-run confirms it does. The plan needs a dated ⊘ on that gate line.

Verification

contract lib 1251 passed / 0 failed; clippy --all-targets -D warnings clean; fmt clean.

Not here: D-MAR-2 (RevisionKind) is gated on the plan's §5 Q1 module-home ruling, per its own ordering rule F6.

Below this, AdaWorldAPI/ndarray now carries the masking primitives these compose with — U64x8/U32x16 andnot + ternlog, the latter lowering to a single vpternlogq on AVX-512 (fd5c66f, fbe2d36). Nothing here depends on that landing first.

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added field-mask difference operations for removing selected fields.
  • Added subset checks to determine whether one field mask is contained within another.
  • These operations now work consistently across mask sizes while preserving normalized results.

• Quality Improvements

  • Expanded validation coverage for mask algebra, cross-size behavior, and equivalent mask representations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 467e637d-e4e4-4cdd-afe2-be3ac67798af

📥 Commits

Reviewing files that changed from the base of the PR and between e4db066 and 29a0902.

📒 Files selected for processing (1)

• crates/lance-graph-contract/src/class_view.rs

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

---

📝 Walkthrough

Walkthrough

FieldMask and WideFieldMask now provide set difference and subset checks. Wide-mask folding and canonical normalization were updated. Tests cover identities, cross-width behavior, equality, hashing, and empty masks.

Changes

Field mask algebra

Layer / File(s)	Summary
Mask difference and subset operations crates/lance-graph-contract/src/class_view.rs	FieldMask and WideFieldMask now support difference and subset predicates.
Wide-mask normalization and tests crates/lance-graph-contract/src/class_view.rs	Wide-mask folding uses raw chunk access. Canonical length handling remains normalized. Tests cover cross-width operations and canonical equality and hashing.

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

Merge Risk: ⚪ Minimal · up to 29a09

This PR adds localized mask difference and subset operations and removes an internal allocation path; no actionable merge-blocking risk remains.

Suggested reviewers: claude

Poem

I’m a rabbit with masks in a row
Difference and subsets now flow
Wide chunks fold neat
Canonical forms meet
And empty masks rest down below

🚥 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 identifies the main change: adding difference and is_subset_of operations to FieldMask and WideFieldMask. The plan reference is extra but does not make the title misleading.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 1 files.
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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