69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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": "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](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.
|