notarius/docs/integrations/run-result.md

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; logical files within the bundle are defined in the Published JSON Output contract.

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.

{
  "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": "rejected"
}

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 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.