Publish grouped warning and diagnostic files

docs/integrations/json-output.md

@@ -9,7 +9,7 @@ Output configuration, including chunk-map and evidence-context publication, belo
 ## Bundle Layout
 
 All paths below are logical, relative, slash-separated bundle paths. The
-encoder always emits the first four JSON files below and adds lane or
+encoder always emits the first five JSON files below and adds lane or
 pipeline-wide artifact files when their corresponding artifacts are available:
 
 A subprocess caller first obtains the physical bundle root from the
@@ -21,7 +21,8 @@ root for the logical discovery described here.
 | `index.json` | Entry point that names the other published files and lane payloads. |
 | `manifest.json` | Run provenance and result summaries. |
 | `rejected.json` | Rejected pipeline outputs. |
-| `warnings.json` | Accepted-output and run warnings. |
+| `warnings.json` | Actionable process-degradation warnings. |
+| `diagnostics.json` | Accepted-artifact quality advisories and normalization observations. |
 | `lanes/<safe-lane-id>.json` | One normalized artifact payload for each lane. |
 | `chunk-map.json` | Optional accepted chunk map, when its export is enabled and available. |
 | `evidence-context.json` | Optional selected source-unit excerpt, when evidence publication is enabled. |
@@ -39,7 +40,8 @@ normalized lanes has this valid minimal index:
   "manifest_file": "manifest.json",
   "output_files": [],
   "rejected_file": "rejected.json",
-  "warnings_file": "warnings.json"
+  "warnings_file": "warnings.json",
+  "diagnostics_file": "diagnostics.json"
 }
 ```
 
@@ -49,6 +51,7 @@ normalized lanes has this valid minimal index:
 | `output_files` | Yes | Lane descriptors sorted by `lane_id`. |
 | `rejected_file` | Yes | Always `rejected.json`. |
 | `warnings_file` | Yes | Always `warnings.json`. |
+| `diagnostics_file` | Yes | Always `diagnostics.json`. |
 | `chunk_map` | No | Descriptor for the pipeline-wide `chunk-map.json`; never a lane descriptor. |
 | `evidence_context` | No | Descriptor for the pipeline-wide `evidence-context.json`; never a lane descriptor. |
 
@@ -132,7 +135,7 @@ These values describe observed execution; they are not a backend-registration
 interface. Entries that differ by backend or effective reasoning remain
 distinct even when their profile, provider, and model are otherwise equal.
 
-## Rejections And Warnings
+## Rejections, Warnings, And Diagnostics
 
 `rejected.json` is always an object with a `rejected` array. Each entry has
 required `stage` and `message`; `step_id`, `lane_id`, `module_key`, `chunk_id`,
@@ -142,9 +145,47 @@ contain the bounded `validation` summary described above; the existing singular
 validator and reason fields remain the first configured rejection for
 compatibility.
 
-`warnings.json` is always an object with a `warnings` array. Each warning has
-`reason_code` and `message`; `scope` is optional. Both arrays are empty when
-there is nothing to report.
+`warnings.json` is always the `notarius.warnings.v2` envelope:
+
+```json
+{
+  "schema_version": "notarius.warnings.v2",
+  "group_count": 0,
+  "occurrence_count": 0,
+  "groups": []
+}
+```
+
+It contains only process warnings. `group_count` is exact, and
+`occurrence_count` is the exact sum of its group occurrence counts.
+
+`diagnostics.json` is always the `notarius.diagnostics.v1` envelope:
+
+```json
+{
+  "schema_version": "notarius.diagnostics.v1",
+  "group_count": 0,
+  "occurrence_count": 0,
+  "truncated": false,
+  "unrepresented_occurrence_count": 0,
+  "groups": []
+}
+```
+
+It contains only advisory and observation groups. `group_count` counts groups
+represented in `groups`; `occurrence_count` includes both represented and
+unrepresented occurrences. When `truncated` is true,
+`unrepresented_occurrence_count` is the exact number omitted from group
+representation.
+
+Each group has `disposition`, `category`, `reason_code`, framework-owned
+`origin`, exact `occurrence_count`, bounded `samples`, and
+`omitted_sample_count`. Samples carry safe `scope` and `message`, plus a chunk
+ID and zero-based chunk index when applicable. A group retains at most three
+distinct samples. The framework fails rather than truncating actionable
+warnings beyond 128 groups; it represents at most 256 advisory/observation
+groups and records further occurrences through the diagnostic truncation
+fields above.
 
 ## Compatibility