Skip to content

fix(scoring)!: describe matched entities without copying them - #264

Merged
blackopsrepl merged 1 commit into
mainfrom
fix/entity-ref-without-copy
Nov 14, 2026
Merged

blackopsrepl merged 1 commit into
mainfrom
fix/entity-ref-without-copy

Conversation

@blackopsrepl

Copy link
Copy Markdown
Collaborator

What

EntityRef, the entity entry in constraint analysis, no longer keeps a copy of the entity. It is now { type_name, display }: the entity's type name and Debug rendering, taken when a match is explained.

Why

  • The copy was Arc::new(entity.clone()) behind a dyn Any, there only so as_entity::<T>() could downcast it.
  • Nothing outside two tests read it. Equality, hashing and display already used only the two strings.
  • It was the only reason explanation required Clone on entities.
  • It put an Arc behind a rule that forbids Arc, and cost an allocation plus a deep clone per entity per match on every analysis call.

Result

  • No scoring stream requires Clone on an entity type. The bound is gone from all 130 entity type parameters, and the scoring crate compiles without it. Generic scoring code can no longer clone an entity: a .clone() on one does not compile.
  • Explaining a match needs only Debug, works for borrowed, non-'static types, and allocates no entity copies.
  • CollectedVec::to_vec keeps its own T: Clone requirement, asked for only when that method is called.

Breaking

EntityRef::as_entity and EntityRef::with_display are removed, and EntityRef::new takes any T: Debug + ?Sized. Read the entity from your solution instead of from the match. The commit carries the BREAKING CHANGE footer, so the next release is 0.28.0 and its changelog says so.

Verification

  • Scoring suite: 330 lib tests plus doctests pass. The grouped analysis fixtures are now Debug-only, and a new test explains a borrowed, non-'static entity.
  • make pre-release and make examples pass. public-api.txt is blessed.
  • AGENTS.md drops the EntityRef type-erasure exception and states that scoring streams do not require Clone on entities.
  • Wireframe, docs/constraints.md and docs/extend-scoring.md are updated.
  • Zero-regression gate: this head against v0.27.0, which also qualifies the 0.28.0 release. Result below.

Constraint analysis stored every matched entity as a type-erased copy,
`Arc::new(entity.clone())` inside `EntityRef`, so that `as_entity::<T>()`
could downcast it later. Nothing outside two tests ever read that copy:
equality, hashing and display used only the type name and `Debug`
rendering. The copy was the only reason explanation needed `Clone`, it put
an `Arc` behind a rule that forbids one, and it cost an allocation and a
deep clone per entity per match on every analysis call.

`EntityRef` is now just `{ type_name, display }`, built from any
`T: Debug + ?Sized`. With the copy gone, no scoring stream needs `Clone` on
an entity type: the `Clone` bound is removed from all 130 entity type
parameters across the stream builders, joins, groups, complements,
projections and terminals, and the scoring crate compiles without it. Generic
scoring code therefore cannot clone an entity; a `.clone()` on one no longer
compiles. Collector payloads keep their own contract (`CollectedVec::to_vec`
still asks for `T: Clone` when called).

Tests: matches justify `Debug`-only entities (the grouped analysis fixtures
no longer derive `Clone`), and an `EntityRef` describes a borrowed,
non-`'static` entity. The type-erasure exception for `EntityRef` payloads is
removed from AGENTS.md, which now states that scoring streams do not require
`Clone` on entities.

BREAKING CHANGE: Constraint analysis describes entities by type name and `Debug` rendering only. `EntityRef::as_entity` and `EntityRef::with_display` are removed and `EntityRef::new` takes any `T: Debug + ?Sized`; read the entity from your solution instead of from the match. Grouped and complemented constraints, which now report their matches (#261), require `Debug` on their entities like every other constraint. `SharedOperatorBuilder::with_explainer` and `OperatorScorerSet::score_for` are removed. Scoring streams no longer require `Clone` on entity types.
@blackopsrepl
blackopsrepl force-pushed the fix/entity-ref-without-copy branch from 5012784 to 821a841 Compare November 14, 2026 08:43
@blackopsrepl

Copy link
Copy Markdown
Collaborator Author

Zero-regression gate — 821a841d vs v0.27.0: passed (EXIT 0)

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

  • wall: -0.75% … +2.26%
  • instructions: -0.00% … +0.01%
  • allocations: +0.00% … +0.00%
  • allocated bytes: +0.00% … +0.00%
  • simulated D1 misses: -1.05% … +4.80%
  • simulated LL misses: -0.01% … +0.70%

The baseline is v0.27.0, so this run also qualifies the 0.28.0 release (#260, #262 and this PR). It measured 5012784c; the PR head 821a841d differs only in its commit message (identical tree). Evidence: zr-entityref-5012784c-vs-v0.27.0/report.json.

@blackopsrepl
blackopsrepl merged commit 19188ac into main Nov 14, 2026
7 checks passed
@blackopsrepl
blackopsrepl deleted the fix/entity-ref-without-copy branch November 14, 2026 10:21
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.

1 participant