65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# 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.
|