69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# 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).
|