Add the Notarius subprocess adapter
This commit is contained in:
68
docs/integrations/notarius.md
Normal file
68
docs/integrations/notarius.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Integration: Notarius
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the implemented Notarius subprocess and published-bundle discovery
|
||||
boundary. Extract-stage orchestration and required-lane policy are not yet
|
||||
implemented.
|
||||
|
||||
## Invocation Contract
|
||||
|
||||
The adapter invokes one complete pipeline with separate argument elements:
|
||||
|
||||
```text
|
||||
notarius run <pipeline-id> --config <absolute-path> --input <absolute-path> --output-dir <absolute-path> --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 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.
|
||||
|
||||
## Receipt Contract
|
||||
|
||||
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.
|
||||
|
||||
Receipt, index, rejection, and warning files have explicit read limits.
|
||||
Unknown fields are tolerated within supported document shapes.
|
||||
|
||||
## Bundle Discovery
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
Reference in New Issue
Block a user