Update native operations, consumer migration, and version checks
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user