notarius/docs/consumers/subprocess.md

Using Notarius As A Subprocess

Use this workflow when an orchestrator runs Notarius and consumes its published artifacts. The CLI reference owns invocation syntax and exit statuses, while the run-result receipt and Published JSON Output contract own the durable result formats.

Run And Check The Process

Optionally preflight a selected configuration and pipeline before work starts:

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.

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.