Record native architecture decisions and align ownership policy

This commit is contained in:
2026-11-22 06:11:57 +00:00
parent 5b6854e975
commit 3cf389db78
18 changed files with 678 additions and 300 deletions

View File

@@ -1,6 +1,10 @@
# ADR-0004: Package modules by domain, not by stage
**Status:** Accepted — its asset-co-location rule is superseded by [ADR-0011](0011-centralize-llm-assets.md); its domain-first module packaging decision remains accepted.
**Status:** Accepted in part. Asset co-location is superseded by
[ADR-0011](0011-centralize-llm-assets.md), and prompt/schema registration by
[ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md).
Domain-first packaging, typed domain ownership, and registrar dependency direction
remain accepted.
**Date:** 2026-07-13
## Context

View File

@@ -1,6 +1,9 @@
# ADR-0005: Cache one canonical chunk plan per source
**Status:** Accepted
**Status:** Superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md). Source-addressed plan
semantics and deterministic materialization remain; source-only canonical reuse
and its separate store do not.
**Date:** 2026-07-17
## Context

View File

@@ -1,6 +1,12 @@
# ADR-0006: Separate output, cache, and debug state
**Status:** Superseded by [ADR-0007](0007-separate-checkpoint-recording-from-reuse.md)
**Status:** Accepted in part. The checkpoint invocation policy was superseded by
[ADR-0007](0007-separate-checkpoint-recording-from-reuse.md); the two-cache model
is now superseded by [ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md),
and required output records and the debug summary/trace split by
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md).
Independent output/cache/debug surfaces, explicit debug selection, and
operator-owned retention remain accepted.
**Date:** 2026-07-17
## Context

View File

@@ -1,6 +1,8 @@
# ADR-0007: Separate checkpoint recording from reuse
**Status:** Accepted
**Status:** Superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md), which replaces
checkpoint recording/resume with unified accepted-result reuse.
**Date:** 2026-07-19
## Context

View File

@@ -1,7 +1,13 @@
# ADR-0010: Use workload-oriented LLM profile defaults
**Status:** Accepted; profile source replacement behavior superseded by
[ADR-0019](0019-adopt-native-promptkit-configuration.md)
**Status:** Accepted in part. Profile source replacement was superseded by
[ADR-0019](0019-adopt-native-promptkit-configuration.md), whose native source
boundary is now superseded by
[ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md).
Checkpoint identity is superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md).
Workload-oriented defaults, D&D-owned profile policy, binding exceptions, and
run-wide profile precedence remain accepted.
**Date:** 2026-08-03
## Context

View File

@@ -1,6 +1,11 @@
# ADR-0011: Centralize LLM-facing assets in a content-only package
**Status:** Accepted
**Status:** Accepted in part. Asset manifests, module schema registration, and
scoped source assembly are superseded by
[ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md);
checkpoint fingerprints are superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md).
The content-only root assets leaf and domain semantic ownership remain accepted.
**Date:** 2026-08-05
## Context

View File

@@ -1,6 +1,9 @@
# ADR-0013: Use request-local candidate handles for semantic reconciliation
**Status:** Accepted
**Status:** Accepted; only the checkpoint-fingerprint requirement is superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md).
Request-local handles, fixed mapping, domain ownership, and safe typed application
remain accepted.
**Date:** 2026-08-09
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0014: Use feedback-aware validation retries
**Status:** Accepted
**Status:** Superseded by
[ADR-0022](0022-use-native-continuation-and-application-assessment.md) for execution,
assessment, and disposition, and
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md) for
diagnostic persistence. Guidance remains separate from operator diagnostics.
**Date:** 2026-08-26
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0015: Separate process warnings from quality diagnostics
**Status:** Accepted
**Status:** Accepted in part. Durable warning/diagnostic files and receipt
presentation are superseded by
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md).
Process-warning classification, module-owned meaning, and bounded origin-aware
aggregation remain accepted.
**Date:** 2026-08-27
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0016: Use feedback-aware module-requested retries
**Status:** Accepted
**Status:** Superseded by
[ADR-0022](0022-use-native-continuation-and-application-assessment.md) for execution,
assessment, and fallback, and
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md) for
diagnostic persistence. Module-authored guidance remains distinct from diagnostics.
**Date:** 2026-08-28
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0018: Adopt ConfigKit for configuration loading
**Status:** Accepted
**Status:** Accepted in part. The version 5 and dependency API selection is
superseded by [ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md).
ConfigKit adoption, application semantic ownership, and discovery-only environment
selection remain, as clarified by
[ADR-0020](0020-delegate-configuration-mechanics-to-configkit.md).
**Date:** 2026-09-13
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0019: Adopt native PromptKit configuration sources
**Status:** Accepted
**Status:** Superseded by
[ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md) for native
composition, resource ownership, and execution types, and
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md) for cache identity.
ConfigKit-owned mechanics and captured source contexts remain in force.
**Date:** 2026-10-04
## Context

View File

@@ -0,0 +1,75 @@
# ADR-0021: Compose native kits and prompt-declared resources
**Status:** Accepted
**Date:** 2026-11-22
## Context
Notarius duplicated configuration assembly, resource registration, completion
types, inspection, CLI parsing, and provider scheduling that the adopted kits
now supply. Keeping those wrappers would preserve competing ownership rather
than protect the application's typed artifact boundary.
## Decision
Use ConfigKit, PromptKit, CommandKit, ckconfig, and ckprompt directly at their
respective application boundaries. The composition root owns one application
load per selected configuration and constructs one shared native engine for
all selected model roles from that original result. Runtime and whole-app or
focused inspection share captured sources and native provenance, not a settings
reserialization or a second loader. ConfigKit retains ownership of composition
mechanics under [ADR-0020](0020-delegate-configuration-mechanics-to-configkit.md).
Version 6 replaces version 5 without a compatibility parser.
Assemble bundled provider resources, embedded application resources, and optional
operator companions beside the selected main source through native contexts and
precedence. Native declarations own qualified resources, inheritance, default
output contracts, and schema selections. PromptKit prepares schemas and owns
structural validation and repair. Application modules retain prompt meaning,
interpretation, and static resource-ID dependencies, not manifests, response-schema
registries, asset fingerprints, virtual mounts, or fallback-profile registration.
The root assets package remains an ordinary content-only embedded leaf.
Model-executing code uses native requests, results, exchanges, errors, and
observations. Pure domain models, codecs, source resolution, and deterministic
helpers remain independent. CommandKit and its integrations own standard command
declarations, parsing, inspection, and presentation; Notarius supplies loaders,
pipeline commands, request inputs, and report content. Shared loaders and offline
preflight do not allocate run storage or perform implicit provider probes.
One ready-job worker pool bounds extraction and merge/normalize continuations
together. Prerequisite waits occupy no worker; nested validation and correction
stay inside the current job. Native engine/backend admission is independent.
Inject no backend concurrency/queue defaults, cross-backend ceiling, extra queue,
or application capacity retries. Preserve stable scope ordering and cancellation
draining. A completed turn releases admission before nested assessment.
This supersedes [ADR-0019](0019-adopt-native-promptkit-configuration.md)'s old
source adapter and private-type boundary; its fingerprint policy is replaced by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md). It replaces the asset
registration portions of [ADR-0004](0004-package-modules-by-domain.md) and
[ADR-0011](0011-centralize-llm-assets.md), retaining domain-first packaging,
semantic ownership, and the content-only leaf. It replaces ADR-0018's version 5
selection, not [ConfigKit adoption](0018-adopt-configkit.md) or ADR-0020's ownership.
[ADR-0010](0010-workload-oriented-llm-profile-defaults.md)'s workload-oriented
profile intent remains; native qualified resources replace its older source form.
## Alternatives considered
- Keep private completion, loader, and inspection adapters. This duplicates kit
behavior and obscures the actual execution contract.
- Adopt only PromptKit and defer CommandKit. Temporary command/report wrappers
would need another cutover and could select different configuration.
- Retain a global LLM scheduler above native admission. This adds a second queue
and couples independent backends without a selected product requirement.
## Consequences
The kits are deliberate dependencies at execution and composition boundaries;
typed application assessment and durable domain artifacts remain distinct.
Upstream changes require review of the public APIs actually consumed, rather
than preservation of old wrappers. Workers do not promise a global provider-call
ceiling or backend saturation. CLI and configuration compatibility is intentionally
broken; artifact schemas are not redesigned. Exact public syntax and dependency
integration details belong in the canonical configuration, CLI, and integration
references, not copied library manuals here.

View File

@@ -0,0 +1,82 @@
# 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.

View File

@@ -0,0 +1,82 @@
# ADR-0023: Unify accepted artifact and plan caching
**Status:** Accepted
**Date:** 2026-11-22
## Context
Source-keyed plans and fingerprinted checkpoints imposed two recovery models
and substantial identity/provenance machinery. The selected need is narrower:
reuse successful model-backed predecessors after downstream failure without
repeating their complete production and assessment.
## Decision
Use one best-effort filesystem cache for final accepted typed artifacts and
LLM-generated chunk plans. Prepare the initial native request once and use its
opaque MessageContentHash unchanged, with no additional identity dimensions.
Execute that same prepared handle on a miss and discard it on a hit. Corrections
do not change the key. Store the final accepted codec artifact, including applied
normalization, rather than a native response, exchange, or reconciliation proposal.
Message roles, exact text, boundaries, and order select reuse. Model/settings,
session, schema metadata, policy, library versions, and implementation changes
add no key dimensions. Text rendered into the messages participates as content.
Changed policy may therefore reuse old acceptance; operators deliberately choose
bypass or refresh when they want re-execution.
Hits receive ordinary codec and current-source usability checks, not renewed
semantic assessment, replayed exchanges, fabricated execution, or historical
usage. Cached plans are rematerialized against the current source. Unusable
entries miss. Deterministic operations remain uncached without synthetic requests.
Store only final ordinary acceptance. Failed, rejected, incomplete, canceled,
and fallback results cannot be stored. Fallback and actually affected dependent
work skip lookup as well as storage; unrelated accepted predecessors remain
reusable. Eligibility is a small handoff fact, not a dependency fingerprint graph.
Auto reads and stores acceptance; bypass does neither; refresh skips lookup and
replaces only after new acceptance. Failed refresh preserves earlier accepted
bytes. Cache I/O failures produce diagnostics without failing otherwise successful
work or repeating model calls. Records are plain accepted JSON, not envelopes,
manifests, acceptance ledgers, or copied source/execution histories. Exact root,
layout, and control precedence belong in configuration and operations references.
Ignore legacy checkpoint and source-plan records without importing, rewriting,
or deleting them. Remove explicit resume, recomputation barriers, and the separate
canonical-partition guarantee. Matching initial messages may reuse a plan; changed
prompt/reference/input content may select another partition. Retain plan range,
annotation, source-order, and deterministic materialization correctness.
This supersedes [ADR-0005](0005-cache-canonical-chunk-plans-by-source.md) and
[ADR-0007](0007-separate-checkpoint-recording-from-reuse.md), and the two-cache
model in [ADR-0006](0006-separate-output-cache-and-debug-state.md). It replaces
checkpoint/fingerprint clauses in ADRs
[0010](0010-workload-oriented-llm-profile-defaults.md),
[0011](0011-centralize-llm-assets.md),
[0013](0013-use-request-local-candidate-handles-for-semantic-reconciliation.md), and
[0019](0019-adopt-native-promptkit-configuration.md), not their retained domain,
content, or identity boundaries.
Apply [ADR-0017](0017-defer-cache-access-policy-to-deployment.md)'s permission
ownership to this unified cache: deployment umask, setgid, and default ACLs govern
effective access. Retain confined paths, symlink rejection, validation, atomic
publication, and recovery without permission convergence or automatic migration.
Output and debug retain independent roots and lifecycles.
## Alternatives considered
- Keep one canonical partition per source. This ignores changed initial task
content and retains a second lookup/publication mechanism.
- Use comprehensive execution or policy fingerprints. That changes the selected
reuse semantics and restores the removed compatibility bookkeeping.
- Cache native responses or restore conversations. Neither is the accepted typed
application result, and each requires replay or renewed interpretation.
## Consequences
Ordinary reruns recover reusable accepted predecessors without a resume request.
Acceptance under changed model or validation policy is not implied by a hit.
Cache is reconstructible and best effort, not an execution history or a storage
durability guarantee. Legacy data stays available for operator-managed cleanup;
no automatic conversion, expiry service, or garbage collector is introduced.

View File

@@ -0,0 +1,90 @@
# ADR-0024: Publish artifacts with native reports and debug evidence
**Status:** Accepted
**Date:** 2026-11-22
## Context
Required manifests, receipts, indexes, reporting sidecars, and copied execution
ledgers made consumers depend on accounting rather than the domain artifacts.
Split sanitized-summary/detailed-trace machinery also duplicated native evidence
and conflated useful inspection with a stable reporting protocol.
## Decision
Domain artifacts are the primary deliverables, including supported qualified
fallbacks. Preserve intrinsic schemas and existing run-specific logical paths,
including selected chunk-map/evidence auxiliaries. Consumers need no index,
manifest, persisted receipt, warnings/diagnostics sidecars, or execution ledger.
Publish artifacts, finalize requested capture, then submit one small native
completion value and human template through CommandKit. Native formats render
that same value; no separate encoder or universal envelope is introduced.
The completion report identifies the pipeline, deliverable count, publication
directory, available debug directory, and positive fallback count. Count each
operation that emits fallback once, not its affected artifacts or attempts.
Disclose fallback independently of diagnostic verbosity. Standard commands keep
their native values. [CLI Reference](../cli.md) owns exact report fields,
stdout/stderr behavior, and outcome codes.
Preserve native operation causes separately from rendering and delivery failures.
Post-publication capture/report failure returns nonzero with available locations
while retaining valid artifacts and evidence. Failed stdout can be partial;
consumers check status before decoding a successful report. Do not rerun model
work, rewrite history, or remove published files to compensate for delivery failure.
Use one native invocation ExecutionGroup, enrolling actual initial, continuation,
and nested validator executions once. Preserve native IDs, terminal coverage,
and unknown usage without parallel totals, synthetic IDs, or a profile ledger.
Cache hits contribute no execution or historical usage.
Explicit debug selection and a nonempty effective destination enable one run
recorder. A directory alone does not enable it; explicit empty disables capture.
Allocate after configuration/run identity but before engine construction/preflight.
Update the relative latest link at start, never completion. Persist convenient
run/operation evidence incrementally and finalize once before successful reporting.
Requested allocation, recording, or finalization failures fail the invocation,
retaining primary causes and whatever evidence/publication is available.
Capture fixed inputs, configuration/composition, prepared contracts, native events,
available results and full application-visible exchanges, typed candidates,
findings/guidance, correction/normalization material, fallbacks, deterministic
results, and cache decisions. Reuse prepared evidence without another preparation
or provider call. Label undelivered responses unassessed and result-less failures
with available evidence; do not fabricate missing provider bodies. Exact filenames
and serialization remain private diagnostic choices, not a public format.
Use ConfigKit secret-aware inspection and native credential omissions. Do not
directly serialize marked secrets or collect unrelated environment/filesystem
content. Do not heuristically scrub or rewrite selected source, prompts, responses,
or arbitrary strings. A debug bundle may retain sensitive application data; it
is not promised sanitized. Operators own access and retention. Do not automatically
delete output or requested bundles. Output, cache, and debug remain independent.
This replaces [ADR-0006](0006-separate-output-cache-and-debug-state.md)'s required
output records and summary/trace split while retaining its three surfaces and
explicit debug selection. It supersedes durable reporting in
[ADR-0015](0015-separate-process-warnings-from-quality-diagnostics.md), retaining
module-owned diagnostic classification and bounded framework aggregation. It
also replaces the private attempt-record restrictions of ADRs
[0014](0014-feedback-aware-validation-retries.md) and
[0016](0016-feedback-aware-module-requested-retries.md) without moving conversation
state into ordinary artifacts or cache entries.
## Alternatives considered
- Rebuild manifests and receipts with native execution data. This preserves an
unnecessary consumer dependency and another reporting model.
- Retain sanitized summaries beside sensitive traces. Heuristic content rewriting
can alter evidence without establishing a selected sanitized-bundle guarantee.
- Treat capture failures as harmless warnings or retry model work. Requested
capture is required work, but its failure cannot repair model output.
## Consequences
Consumers use configured lane/auxiliary paths and optional native reports rather
than receipt traversal. Diagnostic files can change independently of artifacts.
Debug may duplicate evidence for convenient inspection without a complete provider
transcript guarantee. Quiet presentation does not erase fallback qualification
from the report value or turn delivery failure into success. No new access policy,
automatic retention service, release gate, or release authorization is created.