notarius/docs/operations.md

Operations

This is the canonical guide to operating Notarius filesystem state. Command syntax is in the CLI reference; field definitions and precedence are in Configuration.

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:

<output-root>/<run-id>/

Each output file is written atomically. Notarius never automatically removes output. The JSON output contract 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:

<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:

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:

<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:

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:

<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:

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. Extract worker concurrency and actual provider-call concurrency are separate limits; their fields and validation are defined in Configuration. Notarius writes local files only; remote storage and archive management are outside the implemented CLI.