Update native operations, consumer migration, and version checks

This commit is contained in:
2026-11-22 06:32:22 +00:00
parent 5e58327032
commit 2c27695df9
18 changed files with 675 additions and 967 deletions

View File

@@ -1,115 +1,96 @@
# 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.
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.
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).
## Prepare And Run
## Run And Check The Process
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.
Optionally preflight a selected configuration and pipeline before work starts:
Validate the application and pipeline offline:
```sh
notarius config validate --config /path/to/notarius.yml --config-overlay production --pipeline pipeline-id
```
~~~sh
notarius config validate --config /absolute/path/to/notarius.yml
notarius pipeline validate pipeline-id \
--config /absolute/path/to/notarius.yml --overlay production
~~~
Omit `--config-overlay` when the composed base configuration is the intended
selection; it is independent from any `--llm-profile` run override.
Omit the overlay for the composed base. Pipeline validation needs no transcript,
reference bytes, credentials, provider call, or state directory.
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.
Then run with first-class source and output inputs:
```sh
~~~sh
notarius run pipeline-id \
--config /path/to/notarius.yml \
--config-overlay production \
--input /path/to/source.json \
--output-dir /path/to/output-root \
--json
```
--config /absolute/path/to/notarius.yml --overlay production \
--input-file /absolute/path/to/source.json \
--output-dir /absolute/path/to/output-root --format 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.
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.
The maintained D&D subprocess workflow uses this facility for campaign context:
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.
```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
```
## Check Completion Before Parsing
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 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.
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.
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.
## Discover Required Artifacts
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).
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 Required Domain Files
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.
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.
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.
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.
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.
Process completion, required artifact availability/compatibility, and caller
acceptance requirements are separate checks. A count alone cannot identify
which files were produced.
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 Useful Evidence
## Preserve Provenance And Handle Data Carefully
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.
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.
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.