Document and validate Notarius extraction workflows
This commit is contained in:
@@ -1,68 +1,81 @@
|
||||
# Integration: Notarius
|
||||
# Notarius Integration Contract
|
||||
|
||||
## Purpose
|
||||
## Boundary
|
||||
|
||||
Define the implemented Notarius subprocess and published-bundle discovery
|
||||
boundary. Extract-stage orchestration and required-lane policy are not yet
|
||||
implemented.
|
||||
Narratio uses Notarius as a subprocess to extract configured structured JSON
|
||||
lanes from the final trimmed Seriatim transcript. Narratio owns invocation,
|
||||
safe bundle discovery, lane selection, and its own artifact metadata. Notarius
|
||||
owns pipeline definitions, lane schemas, the receipt, and bundle formats.
|
||||
|
||||
## Invocation Contract
|
||||
Canonical Notarius references:
|
||||
|
||||
The adapter invokes one complete pipeline with separate argument elements:
|
||||
- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/subprocess.md)
|
||||
- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/dnd-pipeline.md)
|
||||
- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/run-result.md)
|
||||
- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/json-output.md)
|
||||
|
||||
The [complete Narratio example](../../examples/pipeline.full.annotated.yml)
|
||||
records the exact current constraints for all ten D&D lanes. Treat the linked
|
||||
Notarius documents as canonical when changing those values; Narratio does not
|
||||
duplicate the complete schemas.
|
||||
|
||||
## Invocation
|
||||
|
||||
When `pipeline.notarius.enabled` is true, Narratio resolves the executable,
|
||||
configuration path, input path, output directory, and working directory to
|
||||
absolute paths and invokes:
|
||||
|
||||
```text
|
||||
notarius run <pipeline-id> --config <absolute-path> --input <absolute-path> --output-dir <absolute-path> --json
|
||||
notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> --json
|
||||
```
|
||||
|
||||
It does not pass `--session-id` or automatically execute
|
||||
`notarius config validate`. The configured working directory and inherited
|
||||
parent environment apply to the process. Narratio's shared subprocess timeout
|
||||
and cancellation handling bounds execution.
|
||||
Standard output is reserved for the JSON receipt. Standard error is captured
|
||||
separately as diagnostic output. Narratio applies the configured timeout and
|
||||
does not interpret stdout as a receipt unless the subprocess exits successfully.
|
||||
It does not pass a Narratio session ID or run `notarius config validate`
|
||||
automatically; the configured working directory and inherited environment
|
||||
apply to the subprocess.
|
||||
|
||||
Standard output is written directly to the configured receipt path and
|
||||
standard error to a separate log path. A nonzero exit, cancellation, or timeout
|
||||
returns the subprocess failure without interpreting receipt bytes.
|
||||
## Accepted Result
|
||||
|
||||
## Receipt Contract
|
||||
Narratio currently accepts receipt schema `notarius.run-result.v1`. The receipt
|
||||
must identify the configured pipeline and a bundle root containing a confined
|
||||
`index.json`. All receipt, index, and lane paths must stay inside that bundle;
|
||||
symlinks and non-regular lane payloads are rejected.
|
||||
|
||||
After exit status zero, the adapter accepts the tolerant
|
||||
`notarius.run-result.v1` receipt. It requires run and pipeline identity, an
|
||||
absolute run-specific output directory, the relative production index path,
|
||||
non-negative output counts, and validation status. The receipt pipeline must
|
||||
match the requested pipeline.
|
||||
Supported receipt and index shapes tolerate unknown fields for forward
|
||||
compatibility, while required identity, validation, count, manifest,
|
||||
rejection, warning, and lane-list fields remain mandatory. Narratio applies
|
||||
bounded reads to the receipt, index, rejection, and warning documents. Optional
|
||||
chunk-map and evidence-context descriptors must carry their complete generic
|
||||
contract metadata when present.
|
||||
|
||||
Receipt, index, rejection, and warning files have explicit read limits.
|
||||
Unknown fields are tolerated within supported document shapes.
|
||||
For every entry in `pipeline.notarius.outputs`, Narratio requires exactly one
|
||||
index descriptor with the configured lane ID, media type, schema ID, schema
|
||||
version, and, when configured, module key. Missing, duplicate, rejected, or
|
||||
incompatible required lanes fail extraction even if Notarius exited zero.
|
||||
Unconfigured lanes may remain in the preserved bundle but do not become
|
||||
selectable Narratio sources.
|
||||
|
||||
## Bundle Discovery
|
||||
Each accepted configured lane is registered as
|
||||
`narratio.extraction.<output_key>`. The bundle index is retained for audit and
|
||||
resume validation but is not selectable. Scriptorium and publish rules consume
|
||||
only explicitly named lane sources; `--artifacts` never selects Notarius lanes.
|
||||
|
||||
The receipt's output directory must be strictly beneath the absolute output
|
||||
root supplied by Narratio. The adapter resolves the receipt index and every
|
||||
index path beneath that bundle root.
|
||||
## Failure And Compatibility Behavior
|
||||
|
||||
The production index must provide manifest, rejection, warning, and lane-list
|
||||
fields. Lane descriptors require unique non-empty lane IDs and relative file
|
||||
paths. Optional chunk-map and evidence-context descriptors require their full
|
||||
generic contract metadata when present.
|
||||
- Startup and nonzero-exit errors fail extraction and retain captured diagnostics.
|
||||
- Invalid receipt JSON or an unsupported receipt schema fails before bundle use.
|
||||
- Unsafe or incompatible index data and required-lane rejection fail before the
|
||||
staged bundle is promoted to durable storage.
|
||||
- Contract and external provenance metadata are preserved on lane artifact
|
||||
records and through explicit publication.
|
||||
|
||||
Every consumed path must remain lexically confined and identify a regular file
|
||||
through directory components that are not symlinks. Absolute logical paths,
|
||||
traversal, prefix-confusion escapes, symlinks, directories, and special files
|
||||
are rejected.
|
||||
Rejection and warning summaries retain structured stage, scope, lane, and
|
||||
reason-code fields for diagnostics without exposing free-form external messages
|
||||
or reading lane payload bodies.
|
||||
|
||||
The adapter returns lane and pipeline-wide descriptors without deciding which
|
||||
lanes a caller requires or comparing their contracts to campaign policy. It
|
||||
does not read lane payload bodies or interpret D&D data.
|
||||
|
||||
## Diagnostic Summaries
|
||||
|
||||
`rejected.json` and `warnings.json` are decoded tolerantly after bounded reads.
|
||||
The result retains structured fields such as stage, scope, lane ID, and reason
|
||||
code. Free-form external messages are validated as required by the upstream
|
||||
shape but are not returned in the summaries.
|
||||
|
||||
## Internal Implementation
|
||||
|
||||
The transport-neutral interface, production runner, and configurable fake live
|
||||
in `internal/adapters/notarius`. Composition and adapter ownership are
|
||||
documented in [Adapter Internals](../internal/adapters.md).
|
||||
Configuration fields and defaults are in [Configuration](../config.md).
|
||||
Operator paths, rerun procedures, and bundle retention are in
|
||||
[Operations](../operations.md). See [Troubleshooting](../troubleshooting.md)
|
||||
for failure recovery.
|
||||
|
||||
Reference in New Issue
Block a user