Skip to content

fix(scoring): report matches for grouped and complemented constraints - #262

Merged
blackopsrepl merged 1 commit into
mainfrom
fix/grouped-constraint-matches
Nov 13, 2026
Merged

blackopsrepl merged 1 commit into
mainfrom
fix/grouped-constraint-matches

Conversation

@blackopsrepl

Copy link
Copy Markdown
Collaborator

Closes #261.

Cause

There were two defects. The issue names the first.

  1. Seven of the eight grouped/complemented builders never set an explainer on their SharedOperatorTerminal. Without one, get_matches returns nothing.
  2. OperatorScorer::evaluate_detailed always returned an empty match list. Every terminal on a compiler-shared grouped node therefore had no matches, even in the one builder (joined_grouped_stream) that did set an explainer. #[solverforge_constraints] creates such a node whenever a grouped stream has more than one terminal.

Fix

The shared terminal now requires its rows to implement ExplainRow. This replaces the per-builder optional explainer: SharedOperatorBuilder::with_explainer is removed, and matches come from the rows themselves. In operator_scorer/matches.rs:

  • One match per row with a non-zero coded weight, scored at the terminal's multiplier.
  • Justification is the row's contributors:
    • for a group, its entities;
    • for a complement row, its target plus the group's contributors;
    • for a defaulted complement key, its target alone.
  • Match scores sum to the terminal's score. Before initialization they come from a full evaluation, afterwards from the retained rows, the same as OperatorTerminal.
  • match_count still counts every row. The existing complement, projected and weight contracts pin that.

API changes:

  • Grouped and complemented named() now require Clone + Debug entities, which every ungrouped constraint already required. The projected complement target gains the same bound.
  • OperatorScorerSet::score_for had no callers left and is removed.
  • public-api.txt is blessed with these removals.

Projected streams: projected rows carry no entity, as in every projected constraint today. Projected groups report correct matches and scores, and are justified by their complement target where they have one.

Verification

  • Tests that fail before the fix and pass after it:
    • constraint/tests/grouped_analysis.rs, one test per builder: grouped, grouped join, complemented, cross grouped, cross complemented grouped. Each checks expected matches and justifications, and that the match sum equals the score before initialization, after it, through a retract/insert move and after restoring.
    • The same file adds a shared-node test with two terminals. It covers weighted analysis ([3, 2]) and a disabled terminal.
    • constraint/tests/projected/analysis.rs: projected grouped and projected complemented grouped.
    • tests/group_by_joined.rs: self-join tri group_by matches.
    • crates/solverforge/tests/grouped_constraint_analysis.rs: the issue's reproduction through #[solverforge_constraints] and ScoreDirector::constraint_analyses(). On main the grouped analysis shows score -1hard with no matches (assertion left: 0hard/0soft, right: -1hard/0soft).
  • make pre-release and make examples pass.
  • trybuild passes after Employee in solverforge_constraints_projected_complemented.rs gained Clone + Debug.
  • Docs: scoring wireframe (shared grouped terminals, file map) and docs/constraints.md (score analysis).
  • Zero-regression gate: result posted below. The analysis path is cold, but the shared terminal struct shrinks by 8 bytes.

Grouped and complemented constraints scored correctly but listed no matches
in constraint analysis, so nothing named the entities behind a group's cost.
Two defects caused it:
- seven of the eight grouped builders never gave their shared terminal an
  explainer, and SharedOperatorTerminal::get_matches returned nothing
  without one;
- OperatorScorer::evaluate_detailed always returned an empty match list, so
  every terminal on a compiler-shared grouped node (what
  #[solverforge_constraints] emits whenever a grouped stream has several
  terminals) had no matches even where an explainer existed.

The shared terminal now requires its rows to implement ExplainRow, which
replaces the optional per-builder explainer (SharedOperatorBuilder::
with_explainer is removed) and lets matches come from the rows themselves:
- each terminal reports one match per row whose coded weight is not zero,
  scored at its multiplier and justified by the row's contributors: a
  group's entities, a complement row's target plus its group, a defaulted
  complement key by its target alone;
- match scores sum to the terminal's score, from a full evaluation before
  initialization and from the retained rows afterwards; match_count still
  counts every row.

Grouped and complemented builders therefore require Clone + Debug entities,
as every ungrouped constraint already did; the projected complement target
gains Clone + Debug. OperatorScorerSet::score_for had no caller left and is
removed.

Closes #261
@blackopsrepl
blackopsrepl force-pushed the fix/grouped-constraint-matches branch from 1f8f60f to 4d32fb3 Compare November 13, 2026 20:00
@blackopsrepl

Copy link
Copy Markdown
Collaborator Author

Zero-regression gate — 4d32fb3a (rebased on main dc34520a) vs dc34520a: passed (EXIT 0)

14 cases, 5 layouts, 51 trials. Every case semantic_match, allocations identical.

  • wall −0.62% … +0.85%
  • instructions −0.00% … +0.02%
  • simulated D1 misses −0.21% … +1.33% (construction_first_fit)
  • simulated LL misses −0.02% … +0.06%

The shared terminal lost its Option<fn> explainer field (8 bytes), which shifts layout. The run shows no cache cost from that change.

Pre-release: one solver test, construction_lifecycle_wraps_the_kernel_with_structured_events, failed once in the parallel run. This branch changes no solverforge-solver file, and the same tree then passed 3/3 alone and 3/3 full --lib runs. The flake is filed as #263. A full rerun of clippy, make pre-release and make examples then passed (EXIT 0).

Evidence: zr-pr262-4d32fb3a-vs-dc34520a/report.json.

@blackopsrepl
blackopsrepl merged commit ac41c31 into main Nov 13, 2026
13 of 14 checks passed
@blackopsrepl
blackopsrepl deleted the fix/grouped-constraint-matches branch November 13, 2026 22:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Grouped and complemented constraints report their score but no matches in constraint_analyses()

1 participant