notarius/docs/releases/v0.5.0.md

Notarius v0.5.0

This release separates actionable process warnings from extraction-quality advisories and routine normalization observations, giving operators a quiet warning channel without discarding durable diagnostic detail.

Summary

Notarius now carries one validated, origin-aware diagnostic contract from producers and validators through retries, reusable state, output publication, debug summaries, run receipts, and CLI presentation. Warnings are reserved for process degradation or incomplete configured work. Data-quality findings are advisories, and successful deterministic cleanup is recorded as observations. An ordinary successful run therefore reports zero warnings while retaining bounded diagnostic provenance for later review.

The framework aggregates findings deterministically by their stable identity and complete pipeline origin, preserves exact occurrence counts, and retains bounded representative samples. Warning groups fail rather than truncate; advisory and observation representation is bounded with explicit truncation metadata and exact unrepresented-occurrence counts.

Compatibility

• warnings.json now uses the incompatible grouped notarius.warnings.v2 envelope and contains process warnings only. Consumers of the former flat warning payload must migrate to the current JSON output contract.
• The new diagnostics.json file uses notarius.diagnostics.v1 and contains advisory and observation groups. Production index.json files always expose both warnings_file and diagnostics_file.
• The machine-readable run receipt is now notarius.run-result.v2. It replaces warning_count with exact warning group and occurrence counts and adds advisory/observation group, occurrence, and truncation fields. See the current run-result receipt.
• Custom output modules must return their complete logical file set or an error. The former OutputResult.Warnings field has been removed; an output module cannot report a warning after serializing its output.
• Reusable state now uses notarius.workspace.v4 and chunk-plan records use notarius.chunk-plan.v3 so they can preserve structured diagnostics. Older pre-release reusable state is not reused under these contracts; start with clean state when deterministic continuity with an older workspace is not required.
• Validation acceptance, semantic retry budgets, rejection policy, and D&D artifact schema identities are unchanged by this release.

Upgrade

1. Update subprocess consumers to require notarius.run-result.v2 and read warning_group_count, warning_occurrence_count, diagnostic_group_count, diagnostic_occurrence_count, and diagnostics_truncated.
2. Update output-bundle consumers to decode notarius.warnings.v2, discover diagnostics.json through index.json, and treat diagnostics as review information rather than process warnings.
3. Update any custom output module for the removal of OutputResult.Warnings; return an error when encoding cannot complete.
4. Clear pre-release reusable state before the first upgraded production run when deterministic continuity with an older workspace is not required.
5. Run notarius config validate --config <path> --pipeline <id> and perform one representative run before promoting the release in an automated pipeline.

Changes

• Added validated diagnostic dispositions, categories, origins, stable reason codes, exact occurrence counts, and bounded representative samples.
• Added deterministic run-level aggregation with separate limits for actionable warning groups and advisory/observation groups.
• Reclassified D&D source-relatedness and unresolved-identity findings as data-quality advisories and routine normalization changes as observations.
• Preserved structured diagnostics across producer retries, validation, generated-reference handoff, checkpoints, chunk-plan reuse, and debug summaries while discarding superseded-attempt findings.
• Added grouped warnings.json, a new grouped diagnostics.json, and the corresponding production index entries.
• Upgraded the machine-readable run receipt and human CLI summary to report exact warning and diagnostic counts without allowing advisory volume to create warning output.
• Removed post-encoding output warnings and hardened diagnostic validation, overflow handling, aggregate memory bounds, and warning-file path presentation.
• Documented diagnostic ownership, classification, operator interpretation, durable contracts, and architectural invariants in ADR-0015 and the canonical CLI, operations, integration, and internal documentation.