notarius/docs/operations.md

# 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, may use the chunk-plan cache, and records checkpoints when
`cache.checkpoints.enabled` is true. It does not create debug state unless its
invocation includes `--debug`.

## Output

Durable logical files are written under:

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

The CLI generates one run ID in the form
`run-<started-at-unix-nanoseconds>-<32-lowercase-hex-characters>` and uses it
for output, manifests, and any requested debug bundle. It validates every
logical output name before exclusively creating the run directory. If that
directory already exists, the invocation fails without changing it.

Each output file is written atomically. A later file-write failure leaves the
newly allocated partial run directory in place for inspection; 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.

## Sequential NPC And Spell Runs

The maintained [sequential configuration](../examples/dnd-npc-spell-sequential.config.yml)
contains two independent pipelines over the same Seriatim input shape. Run the
NPC pipeline first and retain its normalized payload:

```sh
go run ./cmd/notarius run dnd-npcs \
  --config examples/dnd-npc-spell-sequential.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --output-dir ./npc-output
```

Then bind that completed run's `lanes/npcs.json` file to the spell extractor:

```sh
go run ./cmd/notarius run dnd-spells \
  --config examples/dnd-npc-spell-sequential.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference spells.extract.npcs=./npc-output/<run-id>/lanes/npcs.json
```

The NPC file is a reference for canonical caster names and aliases, not spell
evidence. The spell manifest records the bound file's raw reference provenance
and the prepared registry's count and semantic digest separately. The NPC
payload, names, aliases, source references, and file bytes can be sensitive
campaign data; protect both output roots and any checkpoint or debug roots that
retain derived application data. A registry from another session is allowed,
but its source references are never copied into spell output evidence.

## Sequential NPC And Combat Runs

The maintained [sequential NPC and combat configuration](../examples/dnd-npc-combat-sequential.config.yml)
also represents two independent runs. Run `dnd-npcs` first, then bind its
normalized `lanes/npcs.json` payload to both combat stages:

```sh
go run ./cmd/notarius run dnd-npcs \
  --config examples/dnd-npc-combat-sequential.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --output-dir ./npc-output

go run ./cmd/notarius run dnd-combat \
  --config examples/dnd-npc-combat-sequential.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference combat.extract.npcs=./npc-output/<run-id>/lanes/npcs.json \
  --reference combat.normalize.npcs=./npc-output/<run-id>/lanes/npcs.json
```

Extraction and normalization bindings are stage-local and are intentionally
specified separately. Notarius does not discover the NPC run, copy its source
ranges into combat evidence, or compose the two runs into one workflow. The
combat manifest records both reference bindings and the prepared registry's
semantic digest/count. Changing the referenced NPC payload, prompt or schema,
normalization policy, or registry digest makes affected checkpoint state
incompatible; output, checkpoint, and debug roots remain independent sensitive
state surfaces.

## 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 recording is controlled by `cache.checkpoints.enabled`, which
defaults to `false`. When enabled, every run records running, succeeded, and
failed transitions and reusable validator-approved results. Successful,
rejected, and failed runs may therefore all leave checkpoint state. The
`--resume` flag additionally loads compatible completed work before executing
missing or incompatible stages. Without `--resume`, a recording-enabled run
never loads checkpoints. Using `--resume` while recording is disabled is an
error.

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>/...
```

The final identity digest includes stable semantic fingerprints explicitly
contributed by prepared modules and validators. Adding or changing one of
these fingerprints intentionally causes a cold cache miss; old checkpoint
directories are left in place and are never migrated or deleted automatically.

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:
    enabled: true
    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. Every allocated bundle makes one best-effort
attempt to record a terminal `run-report.json`.

## Failures And Warnings

Failures before debug allocation are reported on stderr without a bundle.
Failures after allocation report the bundle path on stderr and make independent
attempts to write a failure `run-report.json` and `error.log`. The report retains
the paths and pipeline outcome fields known at the failure point. If either
terminal write fails, the original command error remains first on stderr,
followed by the persistence error and bundle path. 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-1721300000000000000-0123456789abcdef0123456789abcdef
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-1721300000000000000-0123456789abcdef0123456789abcdef
```

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.