Files
notarius/docs/adr/0024-publish-artifacts-with-native-reports-and-debug-evidence.md

5.2 KiB

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 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's required output records and summary/trace split while retaining its three surfaces and explicit debug selection. It supersedes durable reporting in ADR-0015, retaining module-owned diagnostic classification and bounded framework aggregation. It also replaces the private attempt-record restrictions of ADRs 0014 and 0016 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.