4.5 KiB
Using Notarius As A Subprocess
Use this workflow to run Notarius and consume domain files. CLI Reference owns commands, reports, and statuses; Published JSON Output owns logical paths and payload links; Operations owns state and recovery. See the complete D&D workflow for its inventory or migration guidance for older callers.
Prepare And Run
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.
Validate the application and pipeline offline:
notarius config validate --config /absolute/path/to/notarius.yml
notarius pipeline validate pipeline-id \
--config /absolute/path/to/notarius.yml --overlay production
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:
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 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 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.
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.
Read Required Domain Files
Define required/optional lanes from the selected pipeline. Read their documented paths 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 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.