14 KiB
Operations
This guide owns runtime filesystem layout, publication, cache recovery, capture, provisioning, and retention. CLI Reference owns invocation and reports; Configuration owns settings/defaults and source selection. The native migration guide maps retired interfaces to the current workflow.
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:
GOWORK=off go install \
gitea.maximumdirect.net/eric/notarius/cmd/notarius@vMAJOR.MINOR.PATCH
notarius version
Dependency acquisition/private-module access is separate from offline validation. Source Releases owns maintainer publication commands. This workflow does not prepare or authorize a release.
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. |
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:
<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:
<cache-directory>/<opaque-message-content-hash>.json
Omitted/empty cache selection uses the per-user location defined in
Configuration, 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:
# 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.
Preserve the complete example's declaration-relative layout or deliberately update paths. Its companion 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.
Review the deployment before model work:
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 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 owns selected modes, turn allowances, defaults, and precedence.
Output Bundles
The encoder defines logical artifact files; 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 and evidence context 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.
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 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.
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 owns defaults/origins; CLI Reference 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.
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. State is local filesystem data; remote storage, archival, retention automation, live model-quality guarantees, and release publication are outside this workflow.