293 lines
14 KiB
Markdown
293 lines
14 KiB
Markdown
# 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.
|
|
|
|
## 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`:
|
|
|
|
~~~sh
|
|
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](release.md) 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:
|
|
|
|
~~~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.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|