171 lines
6.5 KiB
Markdown
171 lines
6.5 KiB
Markdown
# Operations
|
|
|
|
This is the canonical guide to operating Notarius filesystem state. Command
|
|
syntax is in the [CLI reference](cli.md); field definitions and precedence are
|
|
in [Configuration](config.md).
|
|
|
|
## State Model
|
|
|
|
Notarius uses three independent filesystem surfaces:
|
|
|
|
- output is durable user data;
|
|
- cache is reconstructible chunk-plan and checkpoint state; and
|
|
- debug is explicitly requested inspection data.
|
|
|
|
Choose separate roots and access controls for each surface. A normal run writes
|
|
durable output and may use the chunk-plan cache. It does not create checkpoint
|
|
or debug state unless its invocation includes `--resume` or `--debug`.
|
|
|
|
## Output
|
|
|
|
Durable logical files are written under:
|
|
|
|
```text
|
|
<output-root>/<run-id>/
|
|
```
|
|
|
|
Each output file is written atomically. Notarius never automatically removes
|
|
output. The [JSON output contract](integrations/json-output.md) owns the
|
|
logical file names, schemas, and media types inside a run directory.
|
|
|
|
Remove an output run directory only after its consumer data is no longer
|
|
needed. This is data deletion, not cache cleanup.
|
|
|
|
## Chunk-Plan Cache
|
|
|
|
Chunk plans are stored at:
|
|
|
|
```text
|
|
<chunk-plan-root>/<source-sha256-hex>/plan.json
|
|
```
|
|
|
|
`auto` reuses a complete valid plan or regenerates missing or invalid state.
|
|
`refresh` regenerates and atomically replaces a plan after chunk validation.
|
|
`bypass` performs no plan-cache I/O and does not resolve or create the root.
|
|
Plan selection is source-addressed and independent of checkpoint and debug
|
|
roots.
|
|
|
|
When its directory is empty in configuration, the root is
|
|
`<os.UserCacheDir>/notarius/chunk-plans`. A configured directory is the exact
|
|
root; no suffix is appended. Directories and files created by the store use
|
|
`0700` and `0600` permissions on supported Unix systems. The configured root
|
|
is a trust boundary: do not share it among mutually untrusted users.
|
|
|
|
Remove an exact digest directory or the configured root only when accepting the
|
|
cost of recomputing plans and any chunk-stage work. Cache publication is atomic;
|
|
there is no history, locking, garbage collection, or rollback facility.
|
|
|
|
For a Linux service account, provision a dedicated restrictive root such as:
|
|
|
|
```yaml
|
|
cache:
|
|
chunk_plans:
|
|
directory: /var/cache/notarius/chunk-plans
|
|
```
|
|
|
|
## Checkpoint Cache
|
|
|
|
Checkpoint state is used only by an invocation with `--resume`. That invocation
|
|
loads compatible completed work and records checkpoints for work it executes.
|
|
Without `--resume`, Notarius neither resolves nor creates the checkpoint root,
|
|
and neither loads nor records checkpoints.
|
|
|
|
Checkpoints use the selected root and the existing identity hierarchy:
|
|
|
|
```text
|
|
<checkpoint-root>/<pipeline-id>/<input-key>-<source-or-input-digest>/<pipeline-digest>/<identity-digest>/...
|
|
```
|
|
|
|
An empty configured directory selects
|
|
`<os.UserCacheDir>/notarius/checkpoints`. The root is exact when configured.
|
|
Created directories and files use `0700` and `0600` permissions on supported
|
|
Unix systems.
|
|
|
|
Checkpoint payloads can contain source text, intermediate artifacts, metadata,
|
|
warnings, and content digests. Treat them as sensitive derived application
|
|
data. Compatible files from a former checkpoint root remain reusable when
|
|
`cache.checkpoints.directory` names that exact existing root. They are not
|
|
moved, migrated, or deleted automatically. The frozen serialized identifier
|
|
`workspace_schema_version` remains part of checkpoint compatibility; it is not
|
|
a configuration setting.
|
|
|
|
For a Linux service account, independently provision:
|
|
|
|
```yaml
|
|
cache:
|
|
checkpoints:
|
|
directory: /var/cache/notarius/checkpoints
|
|
```
|
|
|
|
Remove an exact checkpoint identity directory or the configured root only when
|
|
recomputation is acceptable.
|
|
|
|
## Debug Bundles
|
|
|
|
Only `notarius run --debug` enables debug collection. The selected root contains
|
|
one retained bundle per invocation:
|
|
|
|
```text
|
|
<debug-root>/<run-id>/
|
|
summary/
|
|
trace/
|
|
```
|
|
|
|
`summary/` contains redacted invocation, effective-configuration, resolved
|
|
pipeline and reference provenance, checkpoint and chunk-plan decisions, run
|
|
manifest, warnings, report, and any available error text. It excludes raw
|
|
source, references, annotations, prompts, model responses, credentials, and
|
|
malformed cache bytes.
|
|
|
|
`trace/` contains application-owned execution detail, including source and
|
|
stage material, plans, chunks, validator attempts, prompts, model responses,
|
|
timing, and serialized artifacts. It may retain application data omitted from
|
|
output. Credentials, credential-shaped values, sensitive metadata, unrelated
|
|
environment values, and unrelated filesystem content are not captured.
|
|
|
|
Bundles inherit the sensitivity of the application data they capture. Their
|
|
additional risk comes from copying and aggregating that data, so restrict
|
|
access, avoid shared roots between untrusted users, and define retention outside
|
|
Notarius. Created bundle directories use `0700` and files use `0600` on
|
|
supported Unix systems.
|
|
|
|
Notarius never automatically deletes a requested bundle. If allocation
|
|
succeeds, its path is reported on success and failure. A requested summary or
|
|
trace write failure makes the command fail, preserving whatever bundle data was
|
|
already written for inspection.
|
|
|
|
## Failures And Warnings
|
|
|
|
Failures before debug allocation are reported on stderr without a bundle.
|
|
Failures after allocation report the bundle path on stderr and write `error.log`
|
|
when that summary write succeeds. An output-write failure leaves the allocated
|
|
bundle in place. A successful run with warnings exits `0`, reports a warning
|
|
count on stderr, and records warnings in durable output and any requested debug
|
|
summary.
|
|
|
|
## Cleanup
|
|
|
|
Use exact paths for manual cleanup. Examples:
|
|
|
|
```sh
|
|
rm -rf ./notarius-output/run-1234567890
|
|
rm -rf /var/cache/notarius/chunk-plans/0123abcd
|
|
rm -rf /var/cache/notarius/checkpoints/pipeline/input-0123/pipeline-4567/identity-89ab
|
|
rm -rf ./notarius-debug/run-1234567890
|
|
```
|
|
|
|
Avoid broad recursive cleanup against a parent root unless it is an explicit
|
|
operator policy. Output deletion is permanent user-data loss. Cache deletion is
|
|
recoverable but can repeat expensive work. Debug deletion removes troubleshooting
|
|
evidence and any retained application-data copy.
|
|
|
|
## Operational Limits
|
|
|
|
Provider retries and timeouts are handled by Scriptorium according to the
|
|
selected execution profile. Pipeline module retry settings are defined in
|
|
[Configuration](config.md#module-bindings). Extract worker concurrency and
|
|
actual provider-call concurrency are separate limits; their fields and
|
|
validation are defined in [Configuration](config.md#concurrency). Notarius
|
|
writes local files only; remote storage and archive management are outside the
|
|
implemented CLI.
|