86 lines
4.6 KiB
Markdown
86 lines
4.6 KiB
Markdown
# 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.
|