90 lines
4.9 KiB
Markdown
90 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
The shared mechanism and its initial D&D registry consumers are now
|
|
implemented. Current behavior is documented in
|
|
[Module Internals](../internal/modules.md#semantic-reconciliation) and
|
|
[D&D Module Internals](../internal/dnd.md#semantic-registry-reconciliation).
|