Document subprocess run results

README.md

@@ -36,6 +36,8 @@ demonstrates all implemented D&D lanes and the supporting campaign references.
   handling.
 - [Integration contracts](docs/integrations/) — Seriatim input and published
   artifact formats.
+- [Subprocess consumer guide](docs/consumers/subprocess.md) — invoke Notarius
+  from an orchestrator and consume a published result.
 - [Internal overview](docs/internal/overview.md) — implemented component map
   for maintainers.
 - [Developer guide](docs/development.md) — contributor orientation and

docs/cli.md

@@ -10,7 +10,7 @@ defined in [Operations](operations.md).
 
 ~~~
 notarius help
-notarius run <pipeline-id> --input path/to/source.json [flags]
+notarius run <pipeline-id> --input path/to/source.json [--json] [flags]
 notarius config validate [--config path/to/config.yml] [--pipeline pipeline-id] [--only lane-a,lane-b]
 notarius pipelines list [--config path/to/config.yml] [--json]
 ~~~
@@ -21,7 +21,7 @@ writes the command summary to standard output and exits with status 0.
 ## run
 
 ~~~
-notarius run <pipeline-id> --input path/to/source.json [flags]
+notarius run <pipeline-id> --input path/to/source.json [--json] [flags]
 ~~~
 
 The **run** command executes the named pipeline for one input file. The
@@ -32,6 +32,7 @@ pipeline ID and **--input** are required.
 | **--config path** | Use this configuration file. When omitted, configuration discovery applies; see [Configuration](config.md). |
 | **--input path** | Source input file to process. Required. |
 | **--output-dir path** | Override the configured output root for this run. |
+| **--json** | Write the successful run-result receipt as JSON to standard output. |
 | **--chunk_cache auto\|bypass\|refresh** | Override chunk-plan cache handling for this run. |
 | **--resume** | Reuse compatible recorded checkpoints when checkpoint recording is enabled. |
 | **--recompute-step step-id** | With **--resume**, recompute the selected ordered step and its dependent lanes. It cannot be combined with **--only**. |
@@ -70,11 +71,18 @@ names, requiredness, and configured bindings are part of the
 
 ### Run output
 
-On success, standard output contains the completed pipeline ID, counts of
+Without **--json**, standard output contains the completed pipeline ID, counts
-normalized and rejected outputs, and the output directory. A debug-enabled run
+of normalized and rejected outputs, and the output directory. A debug-enabled
-also prints its debug-bundle path to standard output. A successful run with
+run also prints its debug-bundle path to standard output. A successful run with
-warnings reports the warning count to standard error. The published JSON
+warnings reports the warning count to standard error. The published JSON bundle
-envelope is defined by the [JSON output contract](integrations/json-output.md).
+is defined by the [JSON output contract](integrations/json-output.md).
+
+With **--json**, successful standard output is exactly one
+`notarius.run-result.v1` JSON document followed by a newline, with no
+human-oriented status or debug-path line. Its fields and compatibility policy
+are defined by the [run-result contract](integrations/run-result.md). A caller
+must check for exit status 0 before decoding this output; a failed write can
+leave incomplete standard-output bytes that are not a result document.
 
 Example:
 
@@ -134,6 +142,10 @@ go run ./cmd/notarius pipelines list \
 Successful commands write their primary result to standard output. Warnings and
 errors are written to standard error.
 
+For **run --json**, warnings remain on standard error and standard output is a
+machine-readable success result only. Syntax and runtime diagnostics remain on
+standard error. Parse the result only after the process exits with status 0.
+
 | Status | Meaning |
 | --- | --- |
 | 0 | The command completed successfully, including root help. |

docs/consumers/subprocess.md

@@ -0,0 +1,64 @@
+# Using Notarius As A Subprocess
+
+Use this workflow when an orchestrator runs Notarius and consumes its published
+artifacts. The [CLI reference](../cli.md) owns invocation syntax and exit
+statuses, while the [run-result receipt](../integrations/run-result.md) and
+[Published JSON Output contract](../integrations/json-output.md) own the
+durable result formats.
+
+## Run And Check The Process
+
+Optionally preflight a selected configuration and pipeline before work starts:
+
+```sh
+notarius config validate --config /path/to/notarius.yml --pipeline pipeline-id
+```
+
+Invoke the run with explicit paths and machine-readable output. Capture
+standard output and standard error separately; do not combine them before
+processing the result.
+
+```sh
+notarius run pipeline-id \
+  --config /path/to/notarius.yml \
+  --input /path/to/source.json \
+  --output-dir /path/to/output-root \
+  --json
+```
+
+Use absolute paths for supplied input, configuration, output-root, and
+reference files. When a stable prompt session identifier or references are
+needed, pass the supported CLI flags. Supply credentials through Notarius's
+documented configuration and environment mechanisms, never as command-line
+arguments or generated secret-bearing configuration.
+
+Wait for the process before interpreting standard output. Only an exit status
+of 0 permits decoding the receipt. On a nonzero exit, retain standard error for
+diagnosis and ignore all standard-output bytes: a failed receipt write may have
+left a partial document.
+
+## Discover Required Artifacts
+
+Decode the successful receipt and accept the schema versions supported by the
+caller. Use its `output_directory` as the bundle root. For the production JSON
+output, resolve `index_file` under that root with a confinement check and reject
+an absolute path or a result that escapes the root.
+
+Read the resulting `index.json` and locate each artifact by `lane_id`, not by a
+guessed filename. Before decoding a selected payload, verify its descriptor's
+media type and schema identity against the relevant published artifact
+contract. The JSON bundle contract links to the available lane contracts.
+
+A zero exit status may still report rejected outputs, warnings, or absent
+lanes. The caller decides which lane IDs are required for its own work and
+which are optional; it should make that decision explicitly rather than infer
+failure from the receipt counts alone.
+
+## Preserve Provenance And Handle Data Carefully
+
+Keep the receipt with the published `manifest.json`, and retain
+`rejected.json` and `warnings.json` when review or later provenance requires
+them. Treat the input, output bundle, cache, debug bundle, and captured process
+logs as potentially sensitive data. Apply the caller's access controls and
+retention policy, and avoid copying secrets into arguments, logs, or
+provenance records.

docs/development.md

@@ -18,6 +18,7 @@ implemented component map.
 | Any documentation addition or revision | [Documentation Policy](policy/documentation.md) | It defines canonical homes, audiences, current-behavior rules, and maintenance requirements. |
 | Adding, changing, reviewing, or deleting tests | [Testing Policy](policy/testing.md) | It defines risk-based sufficiency, durable test boundaries, test-double guidance, and criteria for retaining tests. |
 | CLI composition or command behavior | [CLI Internals](internal/cli.md) and [CLI Reference](cli.md) | The internal guide owns composition and command flow; the reference owns public syntax. |
+| Building a subprocess caller or changing its result protocol | [Subprocess Consumer Guide](consumers/subprocess.md), [Run Result Receipt](integrations/run-result.md), and [CLI Internals](internal/cli.md) | These separate caller workflow, durable receipt contract, and CLI implementation behavior. |
 | Configuration loading, resolution, or user-visible configuration behavior | [Configuration Internals](internal/configuration.md) and [Configuration](config.md) | The internal guide owns loading and resolution mechanics; the reference owns the configuration contract. |
 | Pipeline resolution or execution | [Pipeline Internals](internal/pipeline.md) | It documents profiles, references, validation, retries, checkpoints, and runner behavior. |
 | Production modules or validators | [Module Internals](internal/modules.md), [D&D Module Internals](internal/dnd.md), and [D&D integration contracts](integrations/) | The generic guide owns extension mechanics, the D&D guide owns shared family conventions, and the contracts own durable output shapes. |

docs/integrations/json-output.md

@@ -12,6 +12,10 @@ All paths below are logical, relative, slash-separated bundle paths. The
 encoder always emits the first four JSON files below and adds lane or chunk-map
 files when their corresponding artifacts are available:
 
+A subprocess caller first obtains the physical bundle root from the
+[run-result receipt](run-result.md), then resolves `index.json` beneath that
+root for the logical discovery described here.
+
 | Path | Purpose |
 | --- | --- |
 | `index.json` | Entry point that names the other published files and lane payloads. |

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.

docs/internal/cli.md

@@ -84,6 +84,16 @@ final command result. Detailed state lifecycle, resume handling, and physical
 path confinement are maintained in [Run State Internals](state.md) and
 [Operations](../operations.md).
 
+For `run --json`, the CLI constructs and encodes its private run-result receipt
+after a successful runner result is available, before it publishes logical
+output files. It writes the prepared receipt to standard output only after
+output publication and requested debug terminalization succeed. A receipt-write
+failure is a runtime command failure; output may be partial, the CLI reports a
+bounded command-owned error, and it does not repeat terminal reporting. The
+receipt remains a CLI reporting concern rather than a framework or output-module
+responsibility; its public contract is the
+[run-result receipt](../integrations/run-result.md).
+
 ## Failure Mapping And Terminal Reporting
 
 Argument, flag, and invocation-combination failures are reported to standard

docs/roadmap/implementation.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Ready for implementation.
+Completed.
 
 ## Objective
 

docs/roadmap/subprocess.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Accepted for implementation.
+Implemented.
 
 ## Purpose