Document subprocess run results

docs/integrations/run-result.md

@@ -0,0 +1,68 @@
+# Run Result Receipt
+
+`notarius run --json` writes this receipt to standard output when a run
+completes successfully. It lets a subprocess caller discover the physical root
+of the published output bundle without parsing interactive command output.
+Command syntax, streams, and exit statuses are defined in the
+[CLI reference](../cli.md); logical files within the bundle are defined in the
+[Published JSON Output contract](json-output.md).
+
+## Schema
+
+The current schema version is `notarius.run-result.v1`.
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `schema_version` | Yes | Exactly `notarius.run-result.v1`. |
+| `run_id` | Yes | The finalized Notarius run identifier. |
+| `pipeline_id` | Yes | The effective pipeline identifier. |
+| `output_directory` | Yes | Absolute path to the published, run-specific output bundle. |
+| `index_file` | For the production JSON output | Logical path `index.json`; omitted for other output modules. |
+| `normalized_output_count` | Yes | Number of final normalized outputs. |
+| `rejected_output_count` | Yes | Number of recorded rejected outputs. |
+| `warning_count` | Yes | Number of final run warnings. |
+| `validation_status` | Yes | The final run manifest validation status. |
+| `debug_directory` | No | Absolute path to the run-specific debug bundle when requested debug capture completed. |
+
+For the production `json` output module, `index_file` is present only when the
+completed run returned exactly one logical output file named `index.json`.
+For another output module, its absence does not indicate a failed run.
+
+```json
+{
+  "schema_version": "notarius.run-result.v1",
+  "run_id": "run-1770000000000000000-0123456789abcdef0123456789abcdef",
+  "pipeline_id": "dnd-session",
+  "output_directory": "/work/results/run-1770000000000000000-0123456789abcdef0123456789abcdef",
+  "index_file": "index.json",
+  "normalized_output_count": 6,
+  "rejected_output_count": 2,
+  "warning_count": 1,
+  "validation_status": "approved"
+}
+```
+
+## Paths And Bundle Discovery
+
+`output_directory` and `debug_directory`, when present, are lexical absolute
+paths. They identify the paths used by Notarius and do not resolve symlinks.
+`output_directory` is the run-specific bundle, not the configured output root.
+
+The receipt is a summary and discovery document. It does not contain lane
+descriptors, payloads, manifest data, rejections, warnings, or file contents.
+For the production JSON output, resolve `index_file` beneath
+`output_directory`, reject path escapes, and use the
+[Published JSON Output contract](json-output.md) to discover logical files and
+lane payloads.
+
+## Delivery And Compatibility
+
+Notarius writes the receipt only after the output bundle has been published and
+any requested debug terminal reporting has completed. Standard output is not
+transactional: a result-write failure returns a nonzero status and can leave
+partial bytes. Consumers must ignore standard output unless the process exits
+with status 0.
+
+Future versions may add optional fields to this schema. Consumers must tolerate
+unknown fields. An incompatible field or semantic change requires a new
+`schema_version` value.