75 lines
3.4 KiB
Markdown
75 lines
3.4 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.
|
|
|
|
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](../integrations/evidence-context.md). 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.
|