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. Notarius generates a stable prompt session for the resolved input module and exact input bytes. Pass --session-id only when intentionally grouping different invocations under a different session. Supply credentials through Notarius's documented configuration and environment mechanisms, never as command-line arguments or generated secret-bearing configuration. In particular, a session identifier is provider-visible and is not a credential mechanism.

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.

If index.json has an evidence_context descriptor, treat it as a pipeline-wide artifact rather than a lane entry. Verify its six descriptor fields before decoding the linked file according to the Published Evidence Context contract. Use each evidence_refs entry as the citation to source material. Its surrounding context range and included units explain the citation, but do not widen or replace the cited source reference.

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. An evidence-context artifact contains source-unit text and metadata, and selected lanes can cover most of an input; preserve and share it only when that source content is authorized for the recipient.