notarius/docs/adr/0013-use-request-local-candidate-handles-for-semantic-reconciliation.md

ADR-0013: Use request-local candidate handles for semantic reconciliation

Status: Accepted Date: 2026-08-09

Context

Several typed normalize stage modules need semantic reconciliation after deterministic preprocessing: a model can judge whether source-backed candidates refer to the same underlying entity, while application code remains responsible for constructing the normalized artifact. Requiring the model to reproduce a candidate's full contextual selector makes the response larger and introduces avoidable formatting, ordering, and transcription failure modes.

Reconciliation must preserve the exact typed artifact boundary established by ADR-0003, the domain-neutral framework and concrete-domain dependency direction established by ADR-0004, and the distinction in ADR-0009 between source evidence and auxiliary identity context. It also needs a concrete, narrowly scoped application of the request-local-label exception allowed by ADR-0012.

Decision

Semantic reconciliation will be a domain-neutral framework mechanism used by typed normalize stage modules. A consuming artifact family will retain ownership of its typed records, identity rules, consolidation policy, durable IDs, and domain warnings; the framework mechanism will not infer those rules from arbitrary data.

For each reconciliation request, deterministic code will assign every eligible model-visible candidate a contiguous, one-based integer handle. The model may receive the candidate's contextual label, source references, and bounded source context needed to judge identity, but its structured response will identify candidates only by those supplied handles. A handle is local to one request, does not represent entity identity, and must never enter a durable artifact or be used to derive a durable ID.

The model will propose duplicate groups and select one supplied member of each group as canonical. Deterministic code will resolve the handles through the retained request mapping, validate the complete proposal, discard unsafe groups, and apply only validated groups through typed domain-owned policy. The model will not synthesize replacement records or directly mutate an artifact.

Every reconciliation prompt will combine a mandatory framework-owned protocol and safety policy with an explicitly selected semantic policy. The semantic policy may be the conservative generic policy or a domain-owned policy, but it cannot replace the shared response protocol or deterministic safety boundary.

Alternatives considered

• Return durable application IDs. Opaque IDs do not help semantic judgment, expose application identity mechanics, and make model output reproduce data that deterministic code already owns.
• Return names alone or copied contextual selectors. Names can be ambiguous, while reproducing labels and source ranges adds response complexity and creates mismatches without adding semantic information. Request-local handles preserve exact selection without either failure mode.
• Ask the model to return synthesized canonical replacement records. This would transfer typed artifact construction, provenance consolidation, and durable identity policy to a probabilistic boundary.
• Reconcile reflection-discovered fields or arbitrary JSON. This would weaken the typed artifact contract and move domain semantics into generic code.
• Hide reconciliation inside extraction or another stage. This would obscure stage ownership and create cross-stage behavior outside the fixed pipeline; reconciliation remains explicit normalize-stage behavior.
• Let each domain replace the complete prompt protocol. This would duplicate safety mechanics and allow domain policy to bypass the common response and validation contract.

Consequences

Model responses become smaller and easier to validate, while deterministic application code retains authority over identity, provenance, ordering, and typed artifact construction. The framework requires a request-local mapping, bounded context preparation, a private integer response contract, proposal assessment, and shared prompt assets. Each consuming artifact family still requires a typed adapter for its irreducibly domain-specific rules.

Request-local handles are deliberately unsuitable for persistence, logging as entity identity, checkpoint contracts, or cross-request correlation. Changes to shared protocol and policy assets must participate in the normal prompt, schema, and checkpoint fingerprint mechanisms.

Acceptance of this decision does not imply that the shared mechanism or its consumer migrations are implemented. The feature roadmap owns target behavior and status, and the implementation plan owns delivery sequence until the work is complete.