diff --git a/README.md b/README.md index f1dcd1b..d139570 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,8 @@ demonstrates all implemented D&D lanes and the supporting campaign references. handling. - [Integration contracts](docs/integrations/) — Seriatim input and published artifact formats. +- [Subprocess consumer guide](docs/consumers/subprocess.md) — invoke Notarius + from an orchestrator and consume a published result. - [Internal overview](docs/internal/overview.md) — implemented component map for maintainers. - [Developer guide](docs/development.md) — contributor orientation and diff --git a/docs/cli.md b/docs/cli.md index 8090525..40d0644 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -10,7 +10,7 @@ defined in [Operations](operations.md). ~~~ notarius help -notarius run --input path/to/source.json [flags] +notarius run --input path/to/source.json [--json] [flags] notarius config validate [--config path/to/config.yml] [--pipeline pipeline-id] [--only lane-a,lane-b] notarius pipelines list [--config path/to/config.yml] [--json] ~~~ @@ -21,7 +21,7 @@ writes the command summary to standard output and exits with status 0. ## run ~~~ -notarius run --input path/to/source.json [flags] +notarius run --input path/to/source.json [--json] [flags] ~~~ The **run** command executes the named pipeline for one input file. The @@ -32,6 +32,7 @@ pipeline ID and **--input** are required. | **--config path** | Use this configuration file. When omitted, configuration discovery applies; see [Configuration](config.md). | | **--input path** | Source input file to process. Required. | | **--output-dir path** | Override the configured output root for this run. | +| **--json** | Write the successful run-result receipt as JSON to standard output. | | **--chunk_cache auto\|bypass\|refresh** | Override chunk-plan cache handling for this run. | | **--resume** | Reuse compatible recorded checkpoints when checkpoint recording is enabled. | | **--recompute-step step-id** | With **--resume**, recompute the selected ordered step and its dependent lanes. It cannot be combined with **--only**. | @@ -70,11 +71,18 @@ names, requiredness, and configured bindings are part of the ### Run output -On success, standard output contains the completed pipeline ID, counts of -normalized and rejected outputs, and the output directory. A debug-enabled run -also prints its debug-bundle path to standard output. A successful run with -warnings reports the warning count to standard error. The published JSON -envelope is defined by the [JSON output contract](integrations/json-output.md). +Without **--json**, standard output contains the completed pipeline ID, counts +of normalized and rejected outputs, and the output directory. A debug-enabled +run also prints its debug-bundle path to standard output. A successful run with +warnings reports the warning count to standard error. The published JSON bundle +is defined by the [JSON output contract](integrations/json-output.md). + +With **--json**, successful standard output is exactly one +`notarius.run-result.v1` JSON document followed by a newline, with no +human-oriented status or debug-path line. Its fields and compatibility policy +are defined by the [run-result contract](integrations/run-result.md). A caller +must check for exit status 0 before decoding this output; a failed write can +leave incomplete standard-output bytes that are not a result document. Example: @@ -134,6 +142,10 @@ go run ./cmd/notarius pipelines list \ Successful commands write their primary result to standard output. Warnings and errors are written to standard error. +For **run --json**, warnings remain on standard error and standard output is a +machine-readable success result only. Syntax and runtime diagnostics remain on +standard error. Parse the result only after the process exits with status 0. + | Status | Meaning | | --- | --- | | 0 | The command completed successfully, including root help. | diff --git a/docs/consumers/subprocess.md b/docs/consumers/subprocess.md new file mode 100644 index 0000000..7d17827 --- /dev/null +++ b/docs/consumers/subprocess.md @@ -0,0 +1,64 @@ +# 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. + +## Run And Check The Process + +Optionally preflight a selected configuration and pipeline before work starts: + +```sh +notarius config validate --config /path/to/notarius.yml --pipeline pipeline-id +``` + +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. + +```sh +notarius run pipeline-id \ + --config /path/to/notarius.yml \ + --input /path/to/source.json \ + --output-dir /path/to/output-root \ + --json +``` + +Use absolute paths for supplied input, configuration, output-root, and +reference files. When a stable prompt session identifier or references are +needed, pass the supported CLI flags. Supply credentials through Notarius's +documented configuration and environment mechanisms, never as command-line +arguments or generated secret-bearing configuration. + +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. + +## Discover Required Artifacts + +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 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. + +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. + +## Preserve Provenance And Handle Data Carefully + +Keep the receipt with the published `manifest.json`, and retain +`rejected.json` and `warnings.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. diff --git a/docs/development.md b/docs/development.md index c90d64e..03296b6 100644 --- a/docs/development.md +++ b/docs/development.md @@ -18,6 +18,7 @@ implemented component map. | Any documentation addition or revision | [Documentation Policy](policy/documentation.md) | It defines canonical homes, audiences, current-behavior rules, and maintenance requirements. | | Adding, changing, reviewing, or deleting tests | [Testing Policy](policy/testing.md) | It defines risk-based sufficiency, durable test boundaries, test-double guidance, and criteria for retaining tests. | | CLI composition or command behavior | [CLI Internals](internal/cli.md) and [CLI Reference](cli.md) | The internal guide owns composition and command flow; the reference owns public syntax. | +| Building a subprocess caller or changing its result protocol | [Subprocess Consumer Guide](consumers/subprocess.md), [Run Result Receipt](integrations/run-result.md), and [CLI Internals](internal/cli.md) | These separate caller workflow, durable receipt contract, and CLI implementation behavior. | | Configuration loading, resolution, or user-visible configuration behavior | [Configuration Internals](internal/configuration.md) and [Configuration](config.md) | The internal guide owns loading and resolution mechanics; the reference owns the configuration contract. | | Pipeline resolution or execution | [Pipeline Internals](internal/pipeline.md) | It documents profiles, references, validation, retries, checkpoints, and runner behavior. | | Production modules or validators | [Module Internals](internal/modules.md), [D&D Module Internals](internal/dnd.md), and [D&D integration contracts](integrations/) | The generic guide owns extension mechanics, the D&D guide owns shared family conventions, and the contracts own durable output shapes. | diff --git a/docs/integrations/json-output.md b/docs/integrations/json-output.md index b451b9e..fd187e0 100644 --- a/docs/integrations/json-output.md +++ b/docs/integrations/json-output.md @@ -12,6 +12,10 @@ All paths below are logical, relative, slash-separated bundle paths. The encoder always emits the first four JSON files below and adds lane or chunk-map files when their corresponding artifacts are available: +A subprocess caller first obtains the physical bundle root from the +[run-result receipt](run-result.md), then resolves `index.json` beneath that +root for the logical discovery described here. + | Path | Purpose | | --- | --- | | `index.json` | Entry point that names the other published files and lane payloads. | diff --git a/docs/integrations/run-result.md b/docs/integrations/run-result.md new file mode 100644 index 0000000..5ac3b6c --- /dev/null +++ b/docs/integrations/run-result.md @@ -0,0 +1,68 @@ +# Run Result Receipt + +`notarius run --json` writes this receipt to standard output when a run +completes successfully. It lets a subprocess caller discover the physical root +of the published output bundle without parsing interactive command output. +Command syntax, streams, and exit statuses are defined in the +[CLI reference](../cli.md); logical files within the bundle are defined in the +[Published JSON Output contract](json-output.md). + +## Schema + +The current schema version is `notarius.run-result.v1`. + +| Field | Required | Meaning | +| --- | --- | --- | +| `schema_version` | Yes | Exactly `notarius.run-result.v1`. | +| `run_id` | Yes | The finalized Notarius run identifier. | +| `pipeline_id` | Yes | The effective pipeline identifier. | +| `output_directory` | Yes | Absolute path to the published, run-specific output bundle. | +| `index_file` | For the production JSON output | Logical path `index.json`; omitted for other output modules. | +| `normalized_output_count` | Yes | Number of final normalized outputs. | +| `rejected_output_count` | Yes | Number of recorded rejected outputs. | +| `warning_count` | Yes | Number of final run warnings. | +| `validation_status` | Yes | The final run manifest validation status. | +| `debug_directory` | No | Absolute path to the run-specific debug bundle when requested debug capture completed. | + +For the production `json` output module, `index_file` is present only when the +completed run returned exactly one logical output file named `index.json`. +For another output module, its absence does not indicate a failed run. + +```json +{ + "schema_version": "notarius.run-result.v1", + "run_id": "run-1770000000000000000-0123456789abcdef0123456789abcdef", + "pipeline_id": "dnd-session", + "output_directory": "/work/results/run-1770000000000000000-0123456789abcdef0123456789abcdef", + "index_file": "index.json", + "normalized_output_count": 6, + "rejected_output_count": 2, + "warning_count": 1, + "validation_status": "approved" +} +``` + +## Paths And Bundle Discovery + +`output_directory` and `debug_directory`, when present, are lexical absolute +paths. They identify the paths used by Notarius and do not resolve symlinks. +`output_directory` is the run-specific bundle, not the configured output root. + +The receipt is a summary and discovery document. It does not contain lane +descriptors, payloads, manifest data, rejections, warnings, or file contents. +For the production JSON output, resolve `index_file` beneath +`output_directory`, reject path escapes, and use the +[Published JSON Output contract](json-output.md) to discover logical files and +lane payloads. + +## Delivery And Compatibility + +Notarius writes the receipt only after the output bundle has been published and +any requested debug terminal reporting has completed. Standard output is not +transactional: a result-write failure returns a nonzero status and can leave +partial bytes. Consumers must ignore standard output unless the process exits +with status 0. + +Future versions may add optional fields to this schema. Consumers must tolerate +unknown fields. An incompatible field or semantic change requires a new +`schema_version` value. diff --git a/docs/internal/cli.md b/docs/internal/cli.md index 242d686..bfec91e 100644 --- a/docs/internal/cli.md +++ b/docs/internal/cli.md @@ -84,6 +84,16 @@ final command result. Detailed state lifecycle, resume handling, and physical path confinement are maintained in [Run State Internals](state.md) and [Operations](../operations.md). +For `run --json`, the CLI constructs and encodes its private run-result receipt +after a successful runner result is available, before it publishes logical +output files. It writes the prepared receipt to standard output only after +output publication and requested debug terminalization succeed. A receipt-write +failure is a runtime command failure; output may be partial, the CLI reports a +bounded command-owned error, and it does not repeat terminal reporting. The +receipt remains a CLI reporting concern rather than a framework or output-module +responsibility; its public contract is the +[run-result receipt](../integrations/run-result.md). + ## Failure Mapping And Terminal Reporting Argument, flag, and invocation-combination failures are reported to standard diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index b2dcdf2..8b11e07 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -2,7 +2,7 @@ ## Status -Ready for implementation. +Completed. ## Objective diff --git a/docs/roadmap/subprocess.md b/docs/roadmap/subprocess.md index 403ed4b..7cb8b3d 100644 --- a/docs/roadmap/subprocess.md +++ b/docs/roadmap/subprocess.md @@ -2,7 +2,7 @@ ## Status -Accepted for implementation. +Implemented. ## Purpose