Files
notarius/docs/operations.md

293 lines
14 KiB
Markdown
Raw Normal View History

# Operations
This guide owns runtime filesystem layout, publication, cache recovery, capture,
provisioning, and retention. [CLI Reference](cli.md) owns invocation and reports;
[Configuration](config.md) owns settings/defaults and source selection.
The [native migration guide](consumers/native-migration.md) maps retired interfaces
to the current workflow.
2026-08-25 02:03:11 +00:00
## Source Deployment
Linux is supported; macOS is best-effort for development and Windows is
unsupported. Install a pinned source tag with the Go version required by
`go.mod`:
2026-08-25 02:03:11 +00:00
~~~sh
GOWORK=off go install \
gitea.maximumdirect.net/eric/notarius/cmd/notarius@vMAJOR.MINOR.PATCH
notarius version
2026-08-25 02:03:11 +00:00
~~~
Dependency acquisition/private-module access is separate from offline validation.
[Source Releases](release.md) owns maintainer publication commands. This workflow
does not prepare or authorize a release.
2026-08-25 02:03:11 +00:00
## State Surfaces
Output, cache, and debug have independent roots and lifecycles.
| Surface | Purpose | Allocation / reuse |
| --- | --- | --- |
| Output | Durable domain artifacts | A successful runner result publishes into a new run directory. |
| Accepted-result cache | Reconstructible artifacts and LLM chunk plans | Eligible model-backed work reads/writes according to its resolved mode. |
| Debug | Explicit run/operation evidence | Explicit capture selection with a nonempty effective destination. |
2026-07-08 03:18:50 +00:00
Directories do not imply one another's enablement or permissions. Configure
separate roots when access or retention needs differ. Notarius performs no
automatic output/debug deletion or cache collection.
## Roots And Permissions
Publication and capture use run-specific directories:
~~~text
<output-root>/<run-id>/
<debug-root>/<run-id>/
<debug-root>/latest -> <run-id>
~~~
The unified cache uses its selected exact root independently of run IDs:
~~~text
<cache-directory>/<opaque-message-content-hash>.json
~~~
Omitted/empty cache selection uses the per-user location defined in
[Configuration](config.md#file-shape-and-defaults), normally under Linux's
`XDG_CACHE_HOME` or `~/.cache`. `/var/cache/notarius` is the convention for
an explicitly configured system-wide installation, not an automatically selected
or provisioned root. Output/debug defaults, empty values, and path origins also
belong in that reference.
Output creation requests directory/file modes `0755`/`0644`; debug requests
`0700`/`0600`. The operating system may restrict effective access. Cache creation
requests conventional maxima `0777`/`0666`, including atomic temporary files,
so deployment umask, setgid inheritance, and default ACLs select effective access.
Notarius does not converge existing ownership or modes.
### Cache Provisioning
A private deployment can use a restrictive process umask. A trusted-group
deployment may provision a setgid root or default ACL. These are deployment
choices, not requirements imposed on every operator:
~~~sh
# Example provisioning by an authorized administrator.
install -d -m 2770 -g notarius-operators /var/cache/notarius
umask 0007
~~~
Configure the cache root to use that directory. Setgid/default ACLs govern
inheritance; Notarius does not copy parent literal mode bits, manage accounts/
groups, or chmod/chown old entries. If existing access is unsuitable, operators
can recreate reconstructible state beneath provisioned parents or deliberately
perform an administrative migration.
Cache, outputs, and evidence excerpts may contain source-derived data. Select
access and retention accordingly; requested modes alone are not a sharing policy.
Existing confined-path, symlink, atomic-write, and validation boundaries do not
promise cross-process transactions or power-loss durability.
## PromptKit Profile Deployment
One selected application load includes bundled provider resources, embedded
Notarius resources, main-relative operator companions, imports, and an optional
overlay. Resource replacement/inheritance and source origins are defined in
[Configuration](config.md#promptkit-profiles).
Preserve the [complete example's](../examples/dnd-complete/config.yml)
declaration-relative layout or deliberately update paths. Its
[companion](../examples/dnd-complete/prompts.yml) adds native profile/backend
variants; minimal needs no operator companion. Select qualified collection IDs.
Supply credential values through the intended environment, not files, arguments,
session IDs, or logs.
2026-08-25 19:31:00 +00:00
Review the deployment before model work:
~~~sh
notarius config validate --config /etc/notarius/config.yml
notarius pipeline validate dnd-session --config /etc/notarius/config.yml
notarius config show --scope promptkit --config /etc/notarius/config.yml
notarius promptkit show profile notarius/dnd-extraction \
--config /etc/notarius/config.yml --format json
~~~
Offline preflight/inspection needs no credential values or provider calls.
Use sources/explain reports for provenance and prepared preview for rendered
request details. Profile inspection describes stored fields, not a completed
execution target. New invocations observe source edits; captured engines do not
reread configuration/message files. Schema/input reads occur during preparation.
Reports can contain ordinary prompt/provider data. Secret-aware inspection and
native credential omissions do not make arbitrary content safe to share.
Operators select destinations, access, and retention when redirecting reports.
## Run Lifecycle
A run loads configuration and obtains its identity. Requested capture allocates
before engine construction/preflight. The run resolves/preflights, materializes
references, prepares modules, parses source, performs chunk/lane work with
eligible reuse, encodes domain files, and publishes into a new run directory.
Requested capture finalizes before successful reporting.
Argument/configuration failures may have no capture. Later failures retain
available evidence. Publication, required capture, and presentation are separate
boundaries: later failure does not undo completed publication.
[CLI Reference](cli.md#completion-report) owns the completion value and outcomes.
### Acceptance And Fallback
PromptKit owns transient retries and structural repair. Application semantic
continuation carries a growing conversation and assesses each usable candidate
through the complete chain, including the final allowed response. No outer
producer/validator retry loop extends native budgets.
Explicit permissive handling may publish a supported qualified fallback, not
ordinary semantic acceptance. Construction still checks intrinsic artifact,
source, and downstream invariants. Failure to construct fallback fails normally;
cancellation never initiates it. D&D scene planning can fall back to one
whole-source chunk, preserving coverage without promising bounded downstream
request size.
Fallback and actually affected consumers skip cache lookup/storage; unrelated
accepted predecessors remain reusable. The report discloses emitting operations
even when warnings are hidden; affected files and validator calls are not extra
fallbacks. A hit does not establish fresh acceptance under changed policy.
Consumers needing new inference/assessment deliberately choose bypass/refresh.
Process warnings retain native visibility; quality advisories are not promoted
to warnings. [Configuration](config.md#producer-controls) owns selected modes,
turn allowances, defaults, and precedence.
## Output Bundles
The encoder defines [logical artifact files](integrations/json-output.md);
the CLI places them beneath the run directory. It checks paths before allocation
and refuses an existing destination without changing it. Individual writes are
atomic, not an all-files transaction. A later write failure can leave a partial
new directory for inspection.
Artifacts are deliverables, not an index, manifest, persisted receipt, or reporting
sidecar. Read configured lane and auxiliary paths beneath the successful report's
directory; do not scan for the newest folder.
Capture/report failure can occur after publication. The command returns nonzero
with available locations; valid artifacts are not removed or regenerated.
Failed stdout can be partial. Do not treat it as a success report or assume a
failed publication directory is complete.
Output is durable user data. Optional [chunk maps](integrations/chunk-map.md)
and [evidence context](integrations/evidence-context.md) are output, not cache/
debug. Evidence can cover every source unit and is not promised smaller or less
sensitive; retain/share it according to consumer needs.
2026-07-26 01:46:23 +00:00
## Accepted-Result Cache And Recovery
The cache stores final accepted typed artifacts, including applied normalization,
and accepted LLM chunk plans, not native responses, conversations, or execution
ledgers. Cheap deterministic work runs normally.
The key is the initial native prepared `MessageContentHash`, unchanged through
correction. Matching ordered roles/text/boundaries can reuse final acceptance.
Model, session, schema metadata, policy, and implementation add no dimensions;
text actually rendered into messages participates. Use refresh/bypass when a
model or policy experiment needs new inference/assessment.
Hits perform ordinary codec/current-source usability checks without semantic
reassessment, provider calls, or historical usage claims. Plans rematerialize
against the current source. Source identity alone no longer selects a canonical
partition; changed initial content can select different boundaries.
| Mode | Recovery behavior |
| --- | --- |
| `auto` | Read accepted entries; execute misses and store final acceptance. |
| `bypass` | Neither read nor write; no cache directory creation. |
| `refresh` | Skip reads and replace only after new acceptance. |
[Configuration](config.md#producer-controls) owns precedence. No mode overrides
eligibility: failure/rejection/incomplete/canceled/fallback results are not stored.
Failed refresh preserves previous acceptance. Fallback incompleteness excludes
actual dependent work, not unrelated siblings.
Missing entries are ordinary misses. Unreadable, malformed, or unusable entries
miss with diagnostics. Cache I/O failures warn without failing otherwise successful
work or repeating model calls. Artifact encoding, required capture, and invalid
configuration remain their own failure boundaries.
After fixing failed work, rerun normally: accepted predecessors and the chunk
plan can be reused while unsuccessful work executes. There is no resume request
or checkpoint barrier. Refresh obtains new acceptance; bypass isolates an
invocation without updating cache state.
### Legacy State
Legacy checkpoints and source-keyed chunk plans remain ignored and untouched,
even below the new root. They do not supply content keys. No automatic import,
conversion, rewrite, permission migration, or deletion occurs. New entries
populate through eligible execution. Operators may retain/clean obsolete data
deliberately; see [migration guidance](consumers/native-migration.md).
## Debug Bundles
Capture needs explicit selection and a nonempty effective destination.
Directory configuration alone does not enable it. Explicit empty disables it;
a nonempty invocation override can re-enable it. [Configuration](config.md#file-shape-and-defaults)
owns defaults/origins; [CLI Reference](cli.md#run) owns mode ordering.
Allocation creates the run directory and updates `latest` to a relative link
at session start. It reflects the last successful start link update, including a
run that later fails. Completion never retargets it. Concurrent starts retain
separate directories; disabled capture leaves the link untouched. This link is
not an output-discovery API.
One recorder writes available evidence incrementally: configuration/composition,
parsed source/fixed inputs, prepared contracts, native events/results/full
exchanges, typed candidates/findings, correction/normalization material, fallbacks,
and cache decisions. Hits can retain prepared/current artifact evidence without
invented executions. Unknown usage stays unknown. Result-less failures retain
available facts; undelivered responses are unassessed.
Exact files, nesting, and serialized shapes are private diagnostic choices,
not public contracts or exhaustive provider transcripts. Debug never prepares
or executes another request just to capture it.
Requested capture is required work. Allocation/link failure stops before model
work, recording errors surface at normal boundaries, and finalization failure
fails the invocation even after publication. Available evidence and primary/
additional causes remain; capture failure never retries a model or deletes data.
Bundles can contain full source, reference, prompt, response, and intermediate
data. Preserve marked-secret/native credential omissions, without assuming
sanitized content: arbitrary application text is not heuristically scrubbed.
Operators own access, sharing, and retention as for other application data.
2026-07-05 14:52:52 +00:00
## Cleanup
Inspect exact targets and coordinate with active writers before administrative
cleanup. Prefer moving evidence aside or recoverable removal where practical.
Target only intended run directories or entries, not globs or broad workspace,
home, or root directories.
Output deletion loses user data. Cache deletion is reconstructible but may repeat
expensive work. Debug deletion loses evidence and retained application data;
account for its `latest` link when managing old sessions. Notarius supplies
no automatic retention, cache migration, or collection command.
## Operational Limits
Choose caller deadlines and native execution settings for the workload.
Cancellation remains authoritative; native timeout/capacity/provider failures
are not interchangeable with caller cancellation. Retry, repair, and continuation
can increase latency/cost without promising old-wrapper attempt parity.
Workers bound ready jobs; native engine/backend admission governs configured
backend capacity independently. There is no global cross-backend scheduler or
second admission queue. Nested assessment does not hold a completed producer's
native permit. Endpoint-only/unlimited backends gain no inferred application
backend limit. Capacity failure follows producer mode without another backoff.
Sessions are provider-visible routing correlations, not secrets. Their default
and override semantics belong in [CLI Reference](cli.md#run-wide-llm-overrides).
State is local filesystem data; remote storage, archival, retention automation,
live model-quality guarantees, and release publication are outside this workflow.