Record semantic reconciliation architecture decision

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

@@ -0,0 +1,91 @@
+# 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](0003-typed-interfaces-with-two-zone-data-model.md), the domain-neutral
+framework and concrete-domain dependency direction established by
+[ADR-0004](0004-package-modules-by-domain.md), and the distinction in
+[ADR-0009](0009-minimal-evidence-grounded-extraction-artifacts.md) 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](0012-resolve-opaque-entity-identifiers-deterministically.md).
+
+## 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](../roadmap/semantic-reconciliation.md) owns target behavior
+and status, and the
+[implementation plan](../roadmap/implementation.md) owns delivery sequence
+until the work is complete.