3.3 KiB
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.