Exact occurrence resolution#

Decision#

Traverse resolves provenance locators from exact excerpt matches in the provider-visible prepared-text slice. It also enumerates the complete prepared artifact to assign stable global occurrence indices and counts, but chars:<start>-<end> is assigned only to a match inside the originating slice.

A provider can supply occurrenceHint, a one-based hint on a proposal. It is untrusted and local to that provider-visible slice: Traverse uses it only if it is an integer within the slice's exact-match count, then maps the selected span to its global occurrence metadata. An absent, malformed, zero, or out-of-range hint follows bounded source-order allocation among visible matches instead. Allocation is performed after provider work has been folded by original chunk and proposal order, so replay, batching, and concurrency cannot change the result.

Every retained proposal exposes provenance.occurrence with the resolver version, full exact-match count, selected index/span, selection mode, hint use, and ambiguity. More than one exact span is an ambiguity signal for a reviewer; it does not claim that any source occurrence is true.

The resolved occurrence is resolverVersion, count and selected. selection and hintUsed record how it was reached and are not part of its identity: the hint is optional, so a model can send it in one run and omit it in the next and resolve the same span (issue #199). A consumer comparing proposals between runs uses sameResolvedOccurrence(a, b), which ignores both, rather than deep equality. The two fields are kept as written because whether a hint was honoured is a fact about the run.

Deduplication occurs after resolution and collapses only matching field path, path indices, canonical candidate value, and selected span. This preserves both different fields grounded by one span and the same value grounded by distinct spans.

Boundaries#

• Exact occurrence resolution grounds excerpts, not candidate values and not review decisions.
• Fuzzy, semantic, normalized, translated, and paraphrased matching may be used by a caller as diagnostic information, but never creates a chars: locator in Traverse.
• A valid hint selects an existing exact match; it cannot manufacture a span or bypass excerpt verification against provider-visible prepared content.
• Overlap windows can propose the same visible span more than once; they dedupe at that span and never consume an unseen occurrence elsewhere in full text.