Skip to content

feat(scoring): report planning ids in constraint matches - #267

Merged
blackopsrepl merged 1 commit into
mainfrom
feat/entity-ref-planning-id
Nov 14, 2026
Merged

blackopsrepl merged 1 commit into
mainfrom
feat/entity-ref-planning-id

Conversation

@blackopsrepl

Copy link
Copy Markdown
Collaborator

Closes #265.

What

  • EntityRef::planning_id: Option<String>: the record's #[planning_id] rendered with Display when the id type implements it (7, anna), otherwise with Debug (a tuple-struct id renders as ShiftId(7)), and None for an id type with neither. Set for entities from planning-model entity and fact collections; None for list elements and hand-built sources. No new bound on stream elements.
  • The macros implement a hidden AnalysisPlanningId for every #[planning_entity] / #[problem_fact] type. Generated entity/fact accessors return SourceExtract<_, ModelPlanningIds> (zero-sized type parameter) via hidden model_source; CollectionExtract gains a provided planning_id method (default None).
  • Explanation moves from the row view (ExplainRow) to the operator (ExplainOperator + RowOrigin), because the operator owns the source that renders the id. Each operator maps a retained handle or an evaluation to its input rows, the same way its provenance already does.
  • Projected rows are now justified by the entities they were projected from (previously none).

Cold path only

Ids are read only in get_matches / detailed analysis. No scoring code reads them, and nothing is allocated in scoring. The one scoring-side layout change: GroupView drops two pointer fields (input, solution) that only explanation used. The zero-regression gate result will be posted below.

Tests

  • Facade: tests/planning_id_constraint_analysis.rs, macro-derived entity and facts across filter, join, group_by, complement and projection, plus a fact without a planning id; before and after initialization; match scores sum to each constraint score.
  • Scoring: constraint/tests/planning_id_analysis.rs covers filter, plain source (None), self-join, cross join, existence, flatten, group+complement, on the evaluation path, the retained path and after a move. grouped_analysis.rs adds shared-terminal ids. Projected analysis now asserts owners. Rendering unit tests cover Display / Debug / neither.

Found along the way

#266: uni group_by(..).complement(..) drops the stream's filter. It is a separate bug and gets its own fix.

Verification

  • cargo test --workspace --all-features --no-fail-fast: 69 suites, 0 failures
  • cargo clippy --workspace --all-targets --all-features -- -D warnings: clean
  • make pre-release, make examples: see the chain log

Every entity in a constraint match now carries its planning id when its
type has one, so callers can look the blamed record up by id instead of
parsing its Debug rendering.

EntityRef gains `planning_id: Option<String>`: the `#[planning_id]` field
rendered with Display when the id type implements it, otherwise with
Debug, and None for an id type with neither. Entities streamed from
planning-model entity and fact collections report it; list elements and
hand-built sources report None, and stream elements need no new bound.

Generated entity and fact accessors return SourceExtract<_,
ModelPlanningIds> through the hidden `model_source`, which reads the
AnalysisPlanningId the macros implement for every annotated type.
CollectionExtract gains a provided `planning_id` method.

Explanation moves from the row view to the operator (ExplainOperator
with a RowOrigin), because the operator owns the source that renders the
id. Projected rows are now justified by the entities they were projected
from. Ids are read only in get_matches and detailed analysis, never
while scoring; the group view drops two fields only explanation used.

Closes #265

BREAKING CHANGE: EntityRef has a new public field `planning_id`, so
struct literals must set it (or use EntityRef::new(..).with_planning_id).
@blackopsrepl

Copy link
Copy Markdown
Collaborator Author

Zero-regression gate — f7f1d2dd vs d8acec76 (main = v0.28.0): passed (EXIT 0)

14 cases, 5 layouts, 51 trials. semantic_match on every case: True.

  • wall: -0.77% … +0.37%
  • instructions: -0.00% … +0.01%
  • allocations: +0.00% … +0.00%
  • allocated bytes: +0.00% … +0.00%
  • simulated D1 misses: -0.54% … +0.00%
  • simulated LL misses: -0.02% … +0.03%

Evidence: zr-pr265-f7f1d2dd-vs-d8acec76/report.json.

@blackopsrepl
blackopsrepl merged commit cdbd83a into main Nov 14, 2026
7 checks passed
@blackopsrepl
blackopsrepl deleted the feat/entity-ref-planning-id branch November 14, 2026 21:37
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.

Constraint matches identify entities only by their Debug text, not their planning id

1 participant