3.2 KiB
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 and the distinction between disambiguating references and source evidence in ADR-0009.
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.