Files
notarius/docs/consumers/subprocess.md

97 lines
4.5 KiB
Markdown
Raw Normal View History

2026-07-26 17:22:27 +00:00
# Using Notarius As A Subprocess
Use this workflow to run Notarius and consume domain files. [CLI Reference](../cli.md)
owns commands, reports, and statuses; [Published JSON Output](../integrations/json-output.md)
owns logical paths and payload links; [Operations](../operations.md) owns state
and recovery. See the [complete D&D workflow](dnd-pipeline.md) for its inventory
or [migration guidance](native-migration.md) for older callers.
2026-07-26 17:22:27 +00:00
## Prepare And Run
2026-08-09 20:57:28 +00:00
Use an argument vector with explicit paths appropriate to the deployment.
Absolute paths avoid dependence on a service's working directory. Keep stdout
and stderr separate, and choose caller cancellation/deadline behavior.
2026-07-26 17:22:27 +00:00
Validate the application and pipeline offline:
2026-07-26 17:22:27 +00:00
~~~sh
notarius config validate --config /absolute/path/to/notarius.yml
notarius pipeline validate pipeline-id \
--config /absolute/path/to/notarius.yml --overlay production
~~~
2026-07-26 17:22:27 +00:00
Omit the overlay for the composed base. Pipeline validation needs no transcript,
reference bytes, credentials, provider call, or state directory.
Then run with first-class source and output inputs:
2026-07-26 17:22:27 +00:00
~~~sh
2026-07-26 17:22:27 +00:00
notarius run pipeline-id \
--config /absolute/path/to/notarius.yml --overlay production \
--input-file /absolute/path/to/source.json \
--output-dir /absolute/path/to/output-root --format json
~~~
Pass external references as separate arguments, for example
`--reference party=/absolute/path/to/party.txt`. Unqualified selectors reach
compatible selected targets; narrower selectors are exceptional overrides.
Generated same-run handoffs stay configured, not CLI files. The
[reference selector contract](../cli.md#reference-selectors) owns matching and
precedence.
Supply credentials through the intended process environment, not arguments,
session IDs, generated files, or logs. Omitted session selection uses the
input-based default; use the [native override](../cli.md#run-wide-llm-overrides)
only when intentionally changing it.
## Check Completion Before Parsing
Wait for completion. Only successful status permits interpreting stdout as a
successful native report. Failed delivery can leave partial bytes; retain stderr
and available locations rather than parsing a structured error envelope.
Optionally decode the [small completion report](../cli.md#completion-report).
Its `output_directory` is the exact run root; do not scan for the newest folder
or guess a run ID. The report is not a persisted receipt, schema-version envelope,
index, or validation/execution ledger.
A completed run may contain supported fallback. The caller decides whether that
is acceptable; inspect positive `fallback_count` when relevant. It counts
emitting operations, not affected files. Reuse performs ordinary usability checks,
not fresh semantic assessment. Callers needing new inference/assessment after
policy changes deliberately select bypass/refresh under the
[cache controls](../config.md#producer-controls).
## Read Required Domain Files
Define required/optional lanes from the selected pipeline. Read their
[documented paths](../integrations/json-output.md#bundle-layout) beneath the
report directory and decode using the configured artifact contracts. For custom
lane IDs, apply the unchanged filename mapping; collisions are command failures.
No receipt/index traversal, manifest descriptors, or reporting sidecars are needed.
Optional chunk-map/evidence files use their documented paths when enabled and
available. Decode supported payload schemas. Evidence is a reading excerpt, not
authoritative lane attribution or a widened citation; normalized lane payloads
retain those contracts.
Process completion, required artifact availability/compatibility, and caller
acceptance requirements are separate checks. A count alone cannot identify
which files were produced.
## Preserve Useful Evidence
Keep domain files and caller-owned invocation/report records useful for provenance.
Reports can be explicitly redirected; Notarius does not automatically persist a
second report or require a metadata bundle. Debug is optional private evidence,
not a consumer protocol.
Post-publication capture/report failure can return nonzero while leaving valid
artifacts. Preserve available files for deliberate recovery, but do not promote
partial stdout or incomplete publication to ordinary consumer success.
[Operations](../operations.md#output-bundles) explains those boundaries.
Inputs, artifacts, evidence, cache, debug, and streams may contain sensitive data.
Apply intended access, sharing, and retention controls. Evidence can cover the
whole source and is not inherently less sensitive.