eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document completed workspace behavior

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-08 03:18:50 +00:00
parent a5bbfea9b9
commit ae65b95374
9 changed files with 178 additions and 623 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/internal/diagnostics.md
View File

@@ -22,6 +22,11 @@ Diagnostics must not expose secrets.
If `workDir` is empty, it defaults to `/tmp/notarius`. Empty retention defaults
to `auto`.
The CLI passes the effective diagnostics root from workspace configuration.
When `workspace.directory` is set and diagnostics are enabled, that root is
`<workspace.directory>/diagnostics`. The legacy diagnostics work directory and
`--diagnostics-dir` still pass a diagnostics-only root to this constructor.
The writer makes the work directory if needed, then attempts to create a unique
run directory. It retries run ID creation a bounded number of times if a
collision occurs.
@@ -93,3 +98,5 @@ manifest before logging the failure.
information needed for recovery.
- Durable output file contracts belong to output modules and integration docs,
not to diagnostics.
- Checkpoint and debug workspace files are separate framework-owned artifacts,
not diagnostics artifacts.

10
docs/internal/pipeline.md
View File

@@ -80,13 +80,17 @@ workspace paths and do not write checkpoint files directly.
For `run --resume`, the CLI also passes a checkpoint loader. The runner consults
the loader in workflow order and reuses only checkpoints whose manifest schema,
status, identity digest, dependency fingerprints, payload files, and payload
digests validate for the current invocation. Missing or invalid checkpoints fall
back to normal execution and are refreshed by the recorder.
digests validate for the current invocation. The identity includes the resolved
pipeline, selected lanes, source/input digest, runtime overrides that affect
execution, and materialized reference digests. Missing or invalid checkpoints
fall back to normal execution and are refreshed by the recorder.
When workspace debug output is enabled, the CLI passes a debug recorder for the
current run ID. The runner writes framework-boundary inputs, outputs,
structured LLM calls, validator calls, timing, and retry attempt metadata
through that interface. Concrete modules still do not receive workspace paths.
through that interface. Debug output is not used for resume and can contain
sensitive source, reference, prompt, and model-output material. Concrete modules
still do not receive workspace paths.
## Registries And Module Specs