2026-07-26 17:22:27 +00:00
|
|
|
# Using Notarius As A Subprocess
|
|
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
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
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
## Prepare And Run
|
2026-08-09 20:57:28 +00:00
|
|
|
|
2026-11-22 06:32:22 +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
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
Validate the application and pipeline offline:
|
2026-07-26 17:22:27 +00:00
|
|
|
|
2026-11-22 06:32:22 +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
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
Omit the overlay for the composed base. Pipeline validation needs no transcript,
|
|
|
|
|
reference bytes, credentials, provider call, or state directory.
|
2026-09-13 17:12:56 +00:00
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
Then run with first-class source and output inputs:
|
2026-07-26 17:22:27 +00:00
|
|
|
|
2026-11-22 06:32:22 +00:00
|
|
|
~~~sh
|
2026-07-26 17:22:27 +00:00
|
|
|
notarius run pipeline-id \
|
2026-11-22 06:32:22 +00:00
|
|
|
--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.
|