65 lines
3.2 KiB
Markdown
65 lines
3.2 KiB
Markdown
# ADR-0012: Resolve opaque entity identifiers deterministically
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-08-08
|
|
|
|
## Context
|
|
|
|
Entity IDs in durable Notarius artifacts are application-owned, deterministic
|
|
identifiers. They are useful to artifact consumers, but their hash-based form
|
|
does not help a model distinguish entities and would make the model reproduce
|
|
an opaque implementation detail. A plain name is likewise insufficient where
|
|
multiple supplied records share that name.
|
|
|
|
The LLM boundary must preserve the typed artifact and durable-schema ownership
|
|
of [ADR-0003](0003-strongly-typed-stage-interfaces.md) and the distinction
|
|
between disambiguating references and source evidence in
|
|
[ADR-0009](0009-prefer-minimal-evidence-grounded-extraction-artifacts.md).
|
|
|
|
## Decision
|
|
|
|
Callers present a model with semantic selections: a canonical name when it is
|
|
unique in the request, or a contextual descriptor containing the name and
|
|
source coordinates when that context is needed to distinguish supplied
|
|
records. The model returns only those supplied selections. The caller resolves
|
|
each accepted selection against the request-local supplied records and attaches
|
|
the opaque application ID deterministically.
|
|
|
|
Source coordinates are permitted in a selection solely as identity context.
|
|
They neither establish an occurrence fact nor replace that occurrence's
|
|
current-transcript evidence. A selector must resolve exactly; unknown,
|
|
ambiguous, partial, reordered, or otherwise unsafe selections are not mapped.
|
|
Where an operation requires a complete grounded artifact, that failure rejects
|
|
the complete artifact rather than accepting a partially mapped result.
|
|
|
|
An explicitly scoped request-local short label is permitted only when a
|
|
contextual descriptor would be impractical and the caller can deterministically
|
|
map the label within that one request. Such a label is not a durable ID, must
|
|
not escape the request boundary, and requires a concrete justification in its
|
|
own module contract.
|
|
|
|
## Alternatives considered
|
|
|
|
- Ask the model to return durable IDs. This exposes opaque implementation
|
|
state, does not improve semantic disambiguation, and makes model output
|
|
depend on hash formatting.
|
|
- Select by name alone. This cannot safely distinguish same-name records.
|
|
- Make request-local labels durable identifiers. This would turn prompt
|
|
presentation into a public identity contract and create avoidable migration
|
|
pressure.
|
|
- Let the model invent identifiers or resolve ambiguity. This makes identity
|
|
assignment non-deterministic and weakens validation.
|
|
|
|
## Consequences
|
|
|
|
Durable integration contracts retain their exact ID/name pairs while models
|
|
operate on readable contextual selections. Calling modules must own selector
|
|
construction, exact resolution, ambiguity handling, and conversion into their
|
|
durable artifact type; PromptKit and its adapter remain transport-only.
|
|
|
|
Some ambiguous or invalid proposals are deliberately omitted, retried, or
|
|
rejected according to the caller's existing failure policy. Internal candidate
|
|
keys may support deterministic request-local mapping, but they are not
|
|
model-visible selectors or durable data. This adds local validation work while
|
|
keeping identity assignment auditable and stable.
|