Files
notarius/docs/adr/0022-use-native-continuation-and-application-assessment.md

83 lines
4.6 KiB
Markdown

# ADR-0022: Use native continuation and application assessment
**Status:** Accepted
**Date:** 2026-11-22
## Context
Private retry machinery conflated transient failures, structural repair,
semantic defects, and validator availability. Latest-response replacement also
discarded conversation history while requiring an application replay protocol.
Native execution can own those mechanics without owning domain acceptance.
## Decision
One small typed producer helper connects native execution to module functions
for fixed input preparation, interpretation, correction requests, and supported
fallback construction. The pipeline supplies the operation's typed assessor.
PromptKit owns transient retries, structural repair, growing conversation history,
and semantic turn iteration. Notarius selects the semantic-turn allowance but
does not pin omitted native repair/retry counts or extend exhausted native work
with an outer retry loop. Deterministic operations have no generic retry budget.
Each correctable producer has initial and correction prompts using the same
response schema and bundled default profile. Preserve explicit request selections
and run overrides. Enduring principles and source/reference material are supplied
initially; the correction template adds current findings and a new assignment.
Native coordination carries the exchange, without manual assistant replay or
rerendering original inputs. Each response is a complete replacement, not a patch.
Normalization applies each proposal afresh to fixed originals and candidate
handles; never union groups across turns.
Check native errors and structural validation status before interpretation,
including failed validation returned with nil Go error. A usable typed candidate
receives the complete applicable validator chain once, in configured order.
Earlier rejection does not suppress later guidance. Revisions, unchanged
candidates, and the final permitted response receive the whole chain; there is
no duplicate assessment after the helper returns.
The detecting validator or module authors actionable guidance separately from
reason codes and operator messages. Unavailable assessment is not a semantic
defect; provider failures do not become instructions. LLM validators execute
once per assessment, without their own semantic continuation loop. Native
success, stopped, and exhausted statuses do not imply application acceptance.
Strict is the application default. Explicit permissive mode may construct a
module-supported fallback after terminal nonacceptance. A fallback satisfies
intrinsic artifact and downstream invariants without ordinary semantic approval
or rerunning the normal validator chain. Failure to construct it fails normally.
Caller cancellation and undelivered responses never initiate fallback. A
result-less failed continuation cannot recover an earlier candidate. Reuse
exclusions and disclosure follow ADRs 0023 and 0024. Exact configuration precedence
and defaults belong in [Configuration](../config.md).
This supersedes [ADR-0014](0014-feedback-aware-validation-retries.md) and
[ADR-0016](0016-feedback-aware-module-requested-retries.md)'s budgets, private
candidate transport, latest-only replay, and terminal policies. It retains their
useful separation of actionable guidance from diagnostic prose and of execution
failure from detected defects. Diagnostic persistence is governed by
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md).
Contextual identity and request-local reconciliation safety under ADRs
[0012](0012-resolve-opaque-entity-identifiers-deterministically.md) and
[0013](0013-use-request-local-candidate-handles-for-semantic-reconciliation.md)
remain in force.
## Alternatives considered
- Retain blanket producer/validator retries. These can extend native budgets
and repeat deterministic work without information capable of fixing it.
- Keep latest-only manual replay. This duplicates conversation mechanics and
discards earlier application-visible turns.
- Let validators decide terminal disposition or revalidate every fallback.
That distributes acceptance policy and confuses qualified recovery with
ordinary validation.
## Consequences
Native execution and application acceptance are separate facts. Accumulated
history uses more context, bounded by the selected allowance. Not every failure
has a supported fallback: an empty scene description, for example, cannot meet
its required artifact shape. Permissive output is explicitly qualified and
reuse-ineligible rather than silently accepted. Paid-model quality and exact
provider-attempt parity with the retired loops are not promised.