68 lines
3.3 KiB
Markdown
68 lines
3.3 KiB
Markdown
# ADR-0015: Separate process warnings from quality diagnostics
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-08-27
|
|
|
|
## Context
|
|
|
|
Notarius currently represents process degradation, incomplete validation,
|
|
extraction-quality doubt, and routine normalization with one flat warning
|
|
record. That makes ordinary successful runs noisy, loses the framework context
|
|
needed to explain a finding, and gives `warning_count` no stable operational
|
|
meaning. It also permits output encoders to add a warning after the durable
|
|
warning file has already been written.
|
|
|
|
The application needs one bounded diagnostic model that preserves exact
|
|
occurrence counts while retaining only safe, representative samples. Fresh and
|
|
resumed logical runs must present the same groups. The model must not alter
|
|
validation decisions, retry budgets, rejected-output behavior, or process exit
|
|
policy.
|
|
|
|
## Decision
|
|
|
|
Warnings are reserved for a completed run that advanced under an allowed
|
|
process-level degradation or incomplete-work policy. Extraction-quality signals
|
|
are advisories, and routine accepted transformations are observations. A
|
|
non-degraded successful run therefore has zero actionable warnings.
|
|
|
|
Modules and validators own a diagnostic's disposition, category, reason code,
|
|
scope, and safe message. The framework adds pipeline origin, including stage,
|
|
step, lane, module, validator, and chunk context where applicable. It then
|
|
aggregates deterministically by disposition, category, reason code, and full
|
|
origin. Chunk context remains on representative samples so equivalent findings
|
|
across chunks aggregate together.
|
|
|
|
Diagnostics carry exact occurrence counts, at most three distinct samples, and
|
|
numeric omitted-sample metadata. Producers and validators are bounded to 64
|
|
local groups. Final actionable warning groups are bounded without truncation;
|
|
the non-warning collection may truncate represented groups while preserving an
|
|
exact total occurrence count and explicit truncation metadata.
|
|
|
|
The public contracts will be versioned: grouped actionable warnings use
|
|
`notarius.warnings.v2`, grouped advisories and observations use
|
|
`notarius.diagnostics.v1`, and the run receipt uses
|
|
`notarius.run-result.v2`. Successful output encoders return logical files or
|
|
an error; they do not add post-encoding warnings.
|
|
|
|
## Alternatives considered
|
|
|
|
- Keep one warning list and filter only CLI output. This would leave durable
|
|
consumers with the same semantically mixed, unbounded contract.
|
|
- Map reason codes to severity in a central framework registry. This would
|
|
split module-owned meaning between synchronized policy tables and make new
|
|
diagnostic meaning implicit.
|
|
- Preserve local omission warning records. They inflate visible group counts
|
|
and lose exact occurrence semantics.
|
|
- Keep output-encoder warnings. A one-pass encoder cannot include those
|
|
records consistently in files it has already serialized; a two-phase encoder
|
|
protocol is deferred until a demonstrated need exists.
|
|
|
|
## Consequences
|
|
|
|
The framework gains validated diagnostic primitives, local collection,
|
|
origin-aware aggregation, and versioned durable presentation. Existing warning
|
|
transport remains temporarily while producers migrate. Current architecture,
|
|
operator, integration, and internal documentation will describe the behavior
|
|
only as each implementation step lands; this accepted decision does not claim
|
|
that the migration is complete.
|