Add the Notarius subprocess adapter
This commit is contained in:
@@ -19,6 +19,8 @@ focused stage documents.
|
||||
## Integration Contracts
|
||||
|
||||
- [Audita](./audita.md): transcript polishing (`audita process`).
|
||||
- [Notarius](./notarius.md): complete pipeline execution and safe JSON bundle
|
||||
discovery (`notarius run`).
|
||||
- [Seriatim](./seriatim.md): merge, normalize, trim, and render operations.
|
||||
- [Scriptorium](./scriptorium.md): artifact generation and debug rendering
|
||||
(`scriptorium run|render`).
|
||||
|
||||
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).
|
||||
@@ -16,6 +16,7 @@ Primary adapters:
|
||||
- `seriatim.Runner`
|
||||
- `audita.Runner`
|
||||
- `scriptorium.Runner`
|
||||
- `notarius.Runner`
|
||||
- `storage.ObjectStore`
|
||||
- `notify.Sender`
|
||||
|
||||
@@ -43,6 +44,9 @@ Adapters do not own:
|
||||
- Noop notifier (`notify.NoopSender`).
|
||||
- Object store only when required by selected stages/config.
|
||||
|
||||
The Notarius subprocess adapter is implemented independently of stage policy;
|
||||
application composition and extract-stage wiring are not yet implemented.
|
||||
|
||||
Object-store construction goes through `newCommandObjectStore`, which loads
|
||||
configured filesystem secrets before adapter initialization.
|
||||
|
||||
@@ -56,16 +60,18 @@ configured filesystem secrets before adapter initialization.
|
||||
|
||||
- Composition: `internal/app/runner.go`, `internal/app/object_store.go`
|
||||
- Shared subprocess mechanics: `internal/adapters/subprocess`
|
||||
- Focused adapters: `internal/adapters/{whisperx,seriatim,audita,scriptorium,storage,notify}`
|
||||
- Focused adapters: `internal/adapters/{whisperx,seriatim,audita,scriptorium,notarius,storage,notify}`
|
||||
- `internal/adapters/whisperx/http_test.go`
|
||||
- `internal/adapters/seriatim/subprocess_test.go`
|
||||
- `internal/adapters/audita/subprocess_test.go`
|
||||
- `internal/adapters/scriptorium/subprocess_test.go`
|
||||
- `internal/adapters/notarius/subprocess_test.go`
|
||||
- `internal/adapters/storage/*_test.go`
|
||||
- `internal/app/runner_test.go`
|
||||
|
||||
See the [WhisperX](../integrations/whisperx.md),
|
||||
[Seriatim](../integrations/seriatim.md), [Audita](../integrations/audita.md),
|
||||
and [Scriptorium](../integrations/scriptorium.md) contracts before changing an
|
||||
[Scriptorium](../integrations/scriptorium.md), and
|
||||
[Notarius](../integrations/notarius.md) contracts before changing an
|
||||
externally visible boundary. Operator-selected values belong in
|
||||
[Configuration](../config.md).
|
||||
|
||||
@@ -19,7 +19,7 @@ implementation sequence.
|
||||
| Stage 1 | Complete |
|
||||
| Stage 2 | Complete |
|
||||
| Stage 3 | Complete |
|
||||
| Stage 4 | Not started |
|
||||
| Stage 4 | Complete |
|
||||
| Stage 5 | Not started |
|
||||
| Stage 6 | Not started |
|
||||
| Stage 7 | Not started |
|
||||
|
||||
Reference in New Issue
Block a user