82 lines
3.8 KiB
Markdown
82 lines
3.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.
|
|
|
|
For the maintained complete D&D workflow, including its transcript input,
|
|
configured lane inventory, and downstream acceptance checklist, see
|
|
[Consuming The Complete D&D Pipeline](dnd-pipeline.md).
|
|
|
|
## 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. 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](../integrations/evidence-context.md). Decode its top-level
|
|
source-unit array as a reading excerpt. Obtain authoritative citations and lane
|
|
provenance from the normalized lane artifacts; the excerpt has neither and its
|
|
nearby units do not widen a lane artifact's 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 can cover most of an input; preserve and share it only when that
|
|
source content is authorized for the recipient.
|