# 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](../integrations/json-output.md).
- 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](../integrations/run-result.md).
- 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.
