From 65e5d65d14655039247424197e6b11f0b2172704 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 9 Aug 2026 15:43:05 +0000 Subject: [PATCH] Record semantic reconciliation architecture decision --- ...ate-handles-for-semantic-reconciliation.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/adr/0013-use-request-local-candidate-handles-for-semantic-reconciliation.md diff --git a/docs/adr/0013-use-request-local-candidate-handles-for-semantic-reconciliation.md b/docs/adr/0013-use-request-local-candidate-handles-for-semantic-reconciliation.md new file mode 100644 index 0000000..4d07fdc --- /dev/null +++ b/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.