Add additive detailed evaluation APIs

[staplen]

Adds an additive way for a caller to learn which segment IDs an expression references, alongside the verdict.

What changes

compileDetailed(source) and makeDetailedPredicate(compiled) return predicates whose result is an extensible object carrying at least:

• matched — Boolean
• referencedSegmentIds — array of safe integers
• metadataComplete — Boolean

compile and makePredicate are untouched. Their predicates still evaluate to primitive Booleans, so existing callers are unaffected.

A reference is collected only from the exact form $user.segments CONTAINS <integer literal>, across the complete expression including under NOT, AND and OR, and independently of evaluation order, short-circuiting and environment values. Any other use of $user.segments, including a dynamic right operand, sets metadataComplete: false for the whole expression rather than reporting a partial set.

The reference metadata is embedded in the generated expression, so the compiled form stays a string.

Version

1.9.0. master is at 1.8.10, so this is the next minor.

Tests

1,124 pass on Node 24.11.1, including the version-replay suite, which replays every stored historical compiled string through the current runtime and asserts behavior rather than output shape.

One qualification on that. .gitignore ignores test-data/, while nine corpora from 1.6.0 to 1.8.8 are tracked from before that rule existed. Each run writes test-data/{version}.json locally and it is never committed, so compiled output from 1.8.9 and 1.8.10 is absent from the corpus. Closing that gap would mean force-adding test-data/1.9.0.json, regenerating the missing corpora from their tags, and narrowing the ignore rule. Not done here.

Compatibility

Old compiled expressions run unchanged on the new runtime, which is what the replay suite covers.

A newly compiled expression will not run on an older runtime, because the metadata capture helper does not exist there. The runtime therefore has to be deployed everywhere before any newly compiled expression reaches it, and a rollback cannot restore an older runtime afterwards.

Draft

Draft deliberately, pending review by a maintainer.