Update native operations, consumer migration, and version checks

This commit is contained in:
2026-11-22 06:32:22 +00:00
parent 5e58327032
commit 2c27695df9
18 changed files with 675 additions and 967 deletions

View File

@@ -1,475 +1,292 @@
# Operations
This is the canonical guide for operating Notarius runtime state. The
[CLI reference](cli.md) owns command syntax and exit statuses, while
[Configuration](config.md) owns fields, defaults, and precedence. Maintainers
who need implementation mechanics should read [Run State Internals](internal/state.md).
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 the supported deployment platform. Install a pinned source release
with the Go version declared in `go.mod` (currently Go 1.27.0):
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
~~~
Pin the exact tag in deployment automation rather than following a branch.
Use [`notarius --version`](cli.md#command-summary) as a diagnostic after
installation; its syntax and semantics are owned by the [CLI reference](cli.md).
The maintainer publication process, including tag guards and verification,
belongs to [Source Releases](release.md). macOS builds are best-effort for
development, and Windows is unsupported.
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
Each run can use independent roots with different retention and access-control
needs.
Output, cache, and debug have independent roots and lifecycles.
| Surface | Purpose | Created when | Retention |
| --- | --- | --- | --- |
| Output | Durable user-facing result bundle | A pipeline completes and returns logical output files | Keep until consumers no longer need it. |
| Chunk-plan cache | Reconstructible source-addressed plan | The configured cache mode permits cache I/O | Keep while reuse is useful. |
| Checkpoint cache | Reconstructible execution and recovery state | Checkpoint recording is enabled | Keep only while recovery or reuse is useful. |
| Debug bundle | Explicit diagnostic record | A run requests debug collection | Keep only under an intentional sensitive-data retention policy. |
| 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. |
Output, cache, and debug roots are never merged or cleaned automatically. Use
separate locations and permissions for operators or services that must not
share application data.
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
The configured output and debug directories are exact roots. An empty cache
directory selects a per-user root:
Publication and capture use run-specific directories:
~~~
<os.UserCacheDir>/notarius/chunk-plans
<os.UserCacheDir>/notarius/checkpoints
~~~text
<output-root>/<run-id>/
<debug-root>/<run-id>/
<debug-root>/latest -> <run-id>
~~~
The field definitions and configuration examples are in [Configuration](config.md).
On supported Unix systems, output directories and files are created with
requested modes **0755** and **0644**; debug directories and files use
**0700** and **0600**. The operating system's umask may impose stricter output
or debug modes. Chunk-plan and checkpoint caches instead request maximum modes
of **0777** for new directories and **0666** for new files, including atomic
temporary files. The kernel applies the service's umask and applicable default
ACLs when those entries are created.
The unified cache uses its selected exact root independently of run IDs:
## Cache Provisioning
~~~text
<cache-directory>/<opaque-message-content-hash>.json
~~~
Cache locations select where Notarius writes, not who can access them. A
private service can use a restrictive umask:
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
umask 0077
notarius run example --config /etc/notarius/config.yml --input /srv/input.txt
~~~
A trusted-group deployment can provision a setgid cache root and use a
group-oriented umask (or an equivalent default ACL):
~~~sh
install -d -m 2770 -g notarius-operators /srv/notarius/chunk-plans /srv/notarius/checkpoints
# Example provisioning by an authorized administrator.
install -d -m 2770 -g notarius-operators /var/cache/notarius
umask 0007
notarius run example --config /etc/notarius/config.yml --input /srv/input.txt
~~~
Setgid and default ACLs control inherited group ownership and access policy;
Notarius does not copy a parent directory's literal mode bits. Cache state is
reconstructible but can contain source-derived data, so operators own its
access and retention policy. Existing cache inodes retain their prior modes
after an upgrade. Recreate a cache beneath correctly provisioned parents, or
stop writers and perform a deliberate administrative migration when a
whole-tree change is required.
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 publication remains atomic and stored records remain validated. Those
guarantees do not add cross-process locking or transactional coordination for
simultaneous writers to one checkpoint identity.
Output bundles can also contain source content when JSON output enables
evidence publication. Apply an appropriate umask and output-root access policy
before enabling that option; the requested output modes alone may not be
suitable for transcript-bearing bundles.
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
Profile deployment has four distinct layers:
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).
| Layer | Owner | Operational role |
| --- | --- | --- |
| Prompts and schemas | Notarius module families, with optional operator prompt overlays | Embedded request and structured-output definitions; operator configuration may recursively overlay prompt fields. Schemas remain application assets. |
| Fallback profiles | Notarius module families | Embedded application defaults, including D&D's `dnd-extraction` profile. |
| Built-in profiles | PromptKit | Upstream catalog entries available when no higher-precedence source defines an ID. |
| Operator configuration | Deployment filesystem | Native profile/backend definitions and prompt overlays selected by `promptkit.profile_file` or `promptkit.profile_dir`. |
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.
The maintained D&D pipeline uses the workload ID `dnd-extraction`. The
embedded fallback makes that ID usable without an operator file. Production,
development, and local deployments can each overlay settings for the same ID,
retaining inherited values they do not change. Notarius's registered fallback
configuration precedes the selected operator source, and groups compose by
native recursive overlays; a configured Notarius local backend is applied
after the operator source. The configuration fields and source precedence are
owned by [Configuration](config.md#promptkit-profiles).
Use a profile source owned by the service account, keep it readable only by
the intended operator, and supply provider credentials through the service
environment—not in the Notarius configuration or profile YAML. The maintained
[LLM profiles](../examples/llm-profiles/dnd-extraction.yml) are secret-free
and can be copied as a format starting point. Validate a deployment without a
provider call or credentials:
Review the deployment before model work:
~~~sh
notarius config validate --config /etc/notarius/config.yml --pipeline dnd-session
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
~~~
An unset optional `api_key_env` reaches the provider without authorization and
may receive a 401 or 403 response.
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.
Configured PromptKit profile paths resolve from the file that supplies their
surviving declaration. The complete example's
`./llm-profiles/dnd-extraction.yml` path is therefore relative to that example.
Use absolute paths such as `/etc/notarius/profiles/dnd-extraction.yml` for
services and containers when that is clearer for the deployment.
### Inspect Before Deployment
Use the three configuration reports together when reviewing an operator
source:
~~~sh
notarius config effective --scope promptkit --config /etc/notarius/config.yml
notarius config explain --scope promptkit --config /etc/notarius/config.yml \
/profiles/dnd-extraction/model
notarius config profile --config /etc/notarius/config.yml dnd-extraction
~~~
Each report command constructs an inspection engine from the selected
configuration and registered application assets. Construction validates and
captures the effective definitions; after editing a source, run the command
again to inspect a newly constructed engine. These commands do not resolve
credential values, call a provider, or prepare a request. `config profile`
reports the named profile's resolved target and effective credential metadata,
not whether a credential is available or which profile a particular prompt or
run will select.
Effective and explanation reports can include ordinary inline prompt and
provider-parameter data. Credential-shaped provider parameter keys are
redacted, but the rest of the content is not treated as secret-free. Reports
are written only when requested; Notarius does not automatically persist them
in run output or debug bundles. Operators own their destination, access, and
retention when redirecting or storing reports.
Configuration reports are distinct from a prepared execution or a requested
debug trace. They describe captured definitions and source history, not
rendered request messages, runtime credential values, or an individual
provider interaction. The [CLI reference](cli.md#config-effective) documents
the report syntax and output contracts.
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
Use the [run command](cli.md#run) to start a pipeline. A valid invocation loads
and resolves configuration before module preparation and source parsing. It
then performs any permitted cache lookup, executes the pipeline, and publishes
logical output files only after a successful runner result.
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.
On success, the command reports the output bundle path. A run with actionable
process warnings still succeeds and reports warning-group and occurrence counts
on standard error; advisory and observation findings do not produce a warning
line. Errors and
their exit classes are defined in the [CLI reference](cli.md#output-streams-and-exit-statuses).
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.
## Validation Retries And Terminal Outcomes
### Acceptance And Fallback
When debug recording is enabled, per-call response artifacts include the
terminal execution summary for retry, repair, timing, and presence-aware usage
diagnosis. Normal output, receipts, and warnings do not aggregate or publish
this diagnostic metadata.
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.
Each producer binding has one outer **retries** budget. It covers complete
producer attempts for operational failures, invalid structured output,
normalizer fallback retry, and semantic correction. It is independent from
PromptKit's structural-repair calls inside one completion, its configured
`promptkit.transient_retries` built-in HTTP attempts, and an LLM-backed
validator's own retry budget. The transient setting defaults to two additional
attempts for eligible provider statuses; set it explicitly to zero when an
operator needs one HTTP attempt per generation. A semantic correction rebuilds
the ordinary producer request and supplies only the latest rejected model
response plus aggregated validator guidance; it is not a conversation replay.
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.
These budgets multiply only by their declared scopes. With two outer producer
retries, two transient retries, and one structural repair, a single producer
can issue up to 18 HTTP attempts: three producer attempts, each with an initial
generation and one repair generation, each allowing three HTTP attempts. This
is an illustration, not a total-deadline or exactly-once guarantee. Every
built-in HTTP attempt has its own generation timeout; caller cancellation
remains the overall authority and interrupts Retry-After waiting. The shared
Notarius scheduler keeps its permit through those waits, so retry budgets can
increase latency and provider cost. Observed usage can remain incomplete when
providers omit accounting fields.
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.
After the applicable budgets are exhausted, the resolved
[`validation_policy`](config.md#pipelines) determines the result. Structural
failure and semantic rejection normally fail the run; an explicit
`reject_output` records a rejection and allows unrelated work to finish. A
validator execution failure normally uses `warn_continue`, which keeps an
otherwise accepted result in the current run with `incomplete` validation
provenance. It emits one bounded warning for every validator whose execution
budget was exhausted. A corrected result that later passes validation does not
retain diagnostics from abandoned attempts.
Treat a successful process exit as a completed run, not as proof that every
candidate was fully validated. Inspect the receipt's `validation_status`,
`validation_summaries`, rejection count, and warning group and occurrence
counts when an orchestrator requires complete validation. The durable fields
and their meanings are owned by the
[run-result receipt](integrations/run-result.md) and
[published JSON output contract](integrations/json-output.md).
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
Each successful run receives a generated safe run identifier and writes beneath:
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.
~~~
<output-root>/<run-id>/
~~~
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.
The [JSON output contract](integrations/json-output.md) owns the logical files
and their schemas. Before creating the run directory, Notarius validates every
logical output path. It refuses an existing run directory without changing it.
Files are written atomically; if a later write fails, the newly created partial
run directory remains for inspection and is never removed automatically.
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.
Treat an output bundle as durable user data. Do not use cache-cleanup policy to
remove it. An optional accepted chunk map is also durable output and can carry
source- or model-derived annotations; its content and compatibility contract
are defined in [Accepted Chunk Map](integrations/chunk-map.md). An optional
[evidence context](integrations/evidence-context.md) contains source-unit text
and metadata. It is not a cache or debug artifact: retain it with the output
bundle only for as long as consumers need it, and apply source-content access
controls to the entire bundle. Its selected source-unit excerpt may include
every source unit once when coverage is broad or its configured window is
large, so do not assume a byte or token reduction or reduced sensitivity.
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.
## Chunk-Plan Cache
## Accepted-Result Cache And Recovery
Chunk plans live beneath the selected chunk-plan root:
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.
~~~
<chunk-plan-root>/<source-sha256-hex>/plan.json
~~~
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.
One validated canonical plan is active for each source digest. The plan stores
boundaries and provenance, not a second copy of the entire source. This
source-addressed policy is recorded in [ADR-0005](adr/0005-cache-canonical-chunk-plans-by-source.md).
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.
The configured cache mode controls one invocation:
- **auto** looks for a valid active plan. Missing or invalid state causes a new
plan to be generated; an accepted new plan is atomically published.
- **refresh** skips lookup, generates a plan with the configured chunker, and
atomically replaces the active plan after it is accepted.
- **bypass** performs no chunk-plan cache I/O. It does not resolve or create a
chunk-plan root.
A reused plan is still materialized and validated against the current source.
If a prior plan no longer gives acceptable results, use a refresh run rather
than editing cache files. Deleting a plan is recoverable but can repeat costly
chunking work. A plan accepted only under incomplete validation is not
published, and a rejected cache hit falls through to ordinary generation rather
than becoming a correction candidate.
## Checkpoint Recording, Resume, And Recompute
Checkpoint recording is an explicit configuration choice and is disabled by
default. When enabled, each run records stage transitions and the state needed
for compatible recovery. A run records checkpoints even when it does not ask
to reuse them. Checkpoint payloads can contain source-derived and intermediate
application data, so treat the entire root as sensitive.
Checkpoint loading is separate: [**--resume**](cli.md#run) asks a run to reuse
compatible recorded work. A resume request fails when checkpoint recording is
disabled. Without **--resume**, a recording-enabled run executes normally and
does not load checkpoint state. Compatibility includes the resolved pipeline,
input, selected lanes, runtime overrides, reference provenance, LLM-profile
provenance, the effective PromptKit profile-source fingerprint, and
prepared-component fingerprints. When a local PromptKit backend is configured,
compatibility also includes a non-secret fingerprint of its endpoint. Changing
profile content or the local endpoint causes a cold miss; changing only the
local concurrency limit does not. A changed identity produces a cold miss;
Notarius does not migrate, rewrite, or delete older checkpoint directories.
Reasoning-effort inheritance, replacement, and explicit clearing are distinct
runtime identities, so checkpoints created under one state are not reused by
either of the others.
Only accepted, completely validated chunk, extract, merge, and normalize
results are checkpointed for reuse. Rejected, structurally invalid, and
validation-incomplete producer results remain non-reusable, even when a
`warn_continue` result advanced during its original run. A resumed invocation
therefore reruns that producer rather than treating degraded state as accepted.
Checkpoint state is confined below an identity-specific path:
~~~
<checkpoint-root>/<pipeline-id>/<input-key>-<source-or-input-digest-prefix>/<pipeline-digest-prefix>/<identity-digest-prefix>/
~~~
### Selective Recompute
[**--recompute-step**](cli.md#run) requires both **--resume** and enabled
checkpoint recording. It forces the selected ordered step and every lane that
depends on it through generated artifact references. Unrelated lanes remain
eligible for reuse.
For an earlier producer required by a forced consumer, Notarius requires a
compatible accepted normalized artifact. It validates that artifact before
hydrating it and does not silently rerun the producer. If that state is
missing, rejected, corrupt, non-canonical, or incompatible, the run stops
before its dependent starts. Rerun the required producer deliberately instead
of copying or editing checkpoint files.
## Checkpoint Decisions And Recovery
Checkpoint events classify work as **executed**, **reused**,
**forced_recompute**, or **dependency_invalidated**. Their stable reason codes
are written to run diagnostics and provenance. Use the code, not a copied
error message, to decide what to repair.
| Reason code | Recovery meaning |
| Mode | Recovery behavior |
| --- | --- |
| **loading_disabled** | This invocation did not permit checkpoint loading. |
| **checkpoint_missing**, **checkpoint_path_invalid**, **checkpoint_read_failed**, **checkpoint_decode_failed** | The stored checkpoint could not be located or read safely; normal resume work can execute again. |
| **workspace_schema_incompatible**, **identity_mismatch**, **stage_mismatch**, **step_mismatch**, **lane_mismatch**, **module_mismatch** | Stored state belongs to a different compatible scope or identity; allow a fresh run to create new state. |
| **status_not_reusable** | The recorded operation did not end in reusable state. |
| **dependency_mismatch** | A dependency changed; dependent work is invalidated rather than reused. |
| **artifact_payload_invalid**, **artifact_digest_mismatch**, **artifact_codec_incompatible**, **artifact_not_canonical** | A stored artifact cannot safely be hydrated; rerun the producer instead of modifying the cache. |
| **checkpoint_reused** | A normal checkpoint passed compatibility checks. |
| **accepted_artifact_reused** | A required predecessor's accepted normalized artifact was safely hydrated. |
| **recompute_step** | Selective recomputation deliberately forced this work. |
| `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. |
Reason detail is bounded code-owned text. It is diagnostic information, not a
path-discovery or data-recovery mechanism, and does not contain checkpoint,
source, reference, credential, or environment content.
[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
Only a [debug-enabled run](cli.md#run) creates a bundle:
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.
~~~
<debug-root>/<run-id>/
summary/
trace/
~~~
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.
The summary contains redacted invocation and resolution information, including
`effective-config.yml` and the separately redacted resolved pipeline, plus run,
final grouped diagnostic, checkpoint, chunk-plan, and terminal reporting artifacts. Attempt
terminal records contain bounded attempt kinds, validator outcomes, policy,
decision, PromptKit repair count, and usage; they do not contain assistant
responses or complete correction messages. The trace contains allowlisted
application diagnostic records and can include source, model, and correction
content. Neither surface is a cache input. Do not treat a debug bundle as safe
to share merely because its configuration summary is redacted. Invocation
metadata omits reasoning effort when it is inherited, records the replacement
value when one is supplied, and records an empty value when inherited reasoning
was explicitly cleared. It records `config_overlay` only when a non-base
configuration overlay was selected.
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.
Notarius never creates debug state without an explicit request and never
automatically deletes a requested bundle. If allocation succeeds, the command
reports its path on both success and later failure. A summary, trace, or
terminal-report persistence failure fails the command while preserving any
already-written diagnostic data for inspection.
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
Cleanup is manual and destructive. First inspect the exact leaf directory,
then remove only that leaf; do not use a glob or a parent root as the target.
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.
~~~
rm -rf -- /srv/notarius/output/run-1721300000000000000-0123456789abcdef0123456789abcdef
rm -rf -- /srv/notarius/chunk-plans/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
rm -rf -- /srv/notarius/checkpoints/example/seriatim-0123456789abcdef/0123456789abcdef/0123456789abcdef
rm -rf -- /srv/notarius/debug/run-1721300000000000000-0123456789abcdef0123456789abcdef
~~~
Deleting output permanently removes user data. Deleting chunk plans or
checkpoints is recoverable but may repeat expensive provider or pipeline work.
Deleting a debug bundle removes troubleshooting evidence and a retained copy of
application data. Notarius has no cache garbage collector, rollback operation,
or automatic cleanup command.
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
Provider execution settings and the generation timeout come from the selected
PromptKit profile. The invocation-only **--reasoning-effort** and
**--clear-reasoning-effort** controls may replace or clear that profile setting
for all LLM-backed calls in one run without changing the profile. PromptKit
also retries eligible transient HTTP failures with its built-in default
of two additional attempts per generation. This retry work is separate from
structural output repair, which happens within one structured-completion call. Its
effective `structured_output_repair_attempts` limit is resolved from the
selected binding, then the pipeline, then the prompt declaration; see
[module bindings](config.md#module-bindings-and-validators). This is distinct
from Notarius binding **retries**, which rerun the complete module operation
and validation chain and do not consume or replenish the structural-repair
limit. The maintained production prompts declare one repair attempt, paid only
after a structural failure. One structured completion with repair budget **R**
contains at most **R + 1** serial generations. Each generation can now contain
more than one provider call when PromptKit retries an eligible transient
failure. LLM-backed validators have their own corresponding invocation and
repair budgets. These are bounds on attempted work, not a promise that every
call reaches a provider.
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.
Timeouts are layered. Caller cancellation is the outer authority. A positive
effective generation timeout adds an inner request deadline to each built-in
generation attempt, while zero disables only that generation deadline. The HTTP
client timeout remains a transport-wide cap. Notarius does not add another
timeout around PromptKit. Retries and repairs are serial within the same caller
context, so their worst-case latency and cost can exceed the structural-repair
bound above; provision run deadlines and provider budgets accordingly.
Credentials remain optional unless the selected
PromptKit profile requires one, in which case preparation fails before a
provider call when its configured credential is unavailable.
The pinned upstream boundary and profile-format links are in
[PromptKit Integration](integrations/pkg-promptkit.md).
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.
Concurrency has two independent layers. Notarius **total_llm** defaults to 16
and is the application-wide provider-call limit shared by all backends,
modules, retries, and validators. PromptKit may impose a narrower admission
limit for the selected backend. The effective active-generation bound is the
intersection of the Notarius limit, any PromptKit backend limit, and work made
available by the pipeline. Built-in OpenRouter profiles use PromptKit's
upstream backend limit; endpoint-only profiles have no PromptKit backend limit
and remain bounded by Notarius. For the configured local backend, a zero
**concurrency_limit** leaves only the Notarius scheduler as a call limit. A
positive value makes the effective active local-generation bound the smaller
of **total_llm** and that local limit, so a local limit of four permits no more
than four active local generations.
The Notarius scheduler admits one logical structured completion and holds that
permit while PromptKit performs its serial corrective calls. PromptKit applies
its selected-backend admission to each provider call; Notarius does not
reacquire a permit or add another scheduler for a repair.
For a positive local limit, PromptKit owns its default waiting capacity and
admission behavior. When a PromptKit backend has admitted all active and queued
work, a new call fails as capacity exhaustion before generation. The adapter
maps that failure to Notarius's existing provider-neutral capacity error and
does not retry it. The calling stage's configured retry policy applies
normally, and the run fails if those attempts are exhausted. Caller
cancellation remains authoritative. Configuration contracts are documented
under [PromptKit profiles](config.md#promptkit-profiles) and
[concurrency](config.md#concurrency-output-cache-and-debug). Extract-worker
limits and actual provider-call limits are independent. Notarius writes local
filesystem state only; remote storage, archival, and retention automation are
outside the implemented CLI.
Every run has an effective prompt session used for provider routing and run
provenance. The generated default is stable for the same input module and raw
input bytes; use [**--session-id**](cli.md#run) only when intentionally grouping
different invocations. Both generated and explicit values can be visible to
providers, manifests, checkpoints, and requested debug bundles. Do not put
credentials or other secrets in an explicit session identifier; command-line
values are not a credential mechanism.
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.