112 lines
5.4 KiB
Markdown
112 lines
5.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.
|
|
|
|
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. Pass each external reference as its own argument-vector pair;
|
|
do not construct and invoke a shell command. An unqualified reference selector
|
|
supplies that file to every compatible selected target. Lane and stage
|
|
qualification are available for exceptional overrides, while generated
|
|
same-run references remain part of configured pipeline composition. The
|
|
[CLI reference](../cli.md#reference-selectors) owns the exact selector and
|
|
precedence contract.
|
|
|
|
The maintained D&D subprocess workflow uses this facility for campaign context:
|
|
|
|
```sh
|
|
notarius run dnd-session \
|
|
--config /absolute/path/to/notarius.yml \
|
|
--input /absolute/path/to/transcripts/final.trimmed.json \
|
|
--output-dir /absolute/path/to/notarius-output \
|
|
--reference party=/absolute/path/to/references/party.txt \
|
|
--reference players=/absolute/path/to/references/players.txt \
|
|
--reference glossary=/absolute/path/to/references/glossary.txt \
|
|
--reference spell_catalog=/absolute/path/to/references/spells.json \
|
|
--json
|
|
```
|
|
|
|
Only pass the external references available to and desired by the deployment.
|
|
Notarius generates a stable prompt session for the resolved input module and
|
|
exact input bytes; reference changes do not change it. 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.
|
|
|
|
When complete validation is required, also require receipt
|
|
`validation_status: approved` and inspect `validation_summaries`. A successful
|
|
run with `validation_status: incomplete` contains a structurally valid result
|
|
that advanced after validator execution could not complete under the configured
|
|
`warn_continue` policy. It is not reusable checkpoint state and should not be
|
|
silently treated as fully reviewed by the caller.
|
|
|
|
## Preserve Provenance And Handle Data Carefully
|
|
|
|
Keep the receipt with the published `manifest.json`, and retain
|
|
`rejected.json`, `warnings.json`, and `diagnostics.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.
|