8.6 KiB
Migrating To Native Configuration And Commands
This guide maps retired Notarius interfaces to the implemented native workflow. It is migration material: the old spellings below are not accepted aliases. Configuration, CLI Reference, and Operations own the current contracts. Domain artifact schemas and lane filename mapping are unchanged.
Update Caller Arguments
| Former interface | Current equivalent / intent |
|---|---|
notarius --version |
notarius version. |
pipelines list |
pipeline list. |
config validate --pipeline ID |
pipeline validate ID; native config validate checks the application document. |
config effective |
config show; scopes are app and promptkit. |
Positional config explain POINTER |
config explain --path POINTER; use native list/history options for discovery. |
config profile ID |
promptkit show profile QUALIFIED_ID; this reports stored fields, not a copied completed target. |
--config-overlay NAME |
--overlay NAME. |
Run --input PATH |
--input-file PATH. |
--only a,b |
Repeat literal --lane a --lane b; commas are no longer separators. |
--json |
--format json; YAML/text are also native report formats. |
--session-id ID |
--llm-session-id ID. |
--reasoning-effort VALUE |
--llm-reasoning-effort VALUE. |
--clear-reasoning-effort |
Explicit --llm-reasoning-effort=; omission retains native inheritance. |
--resume, --recompute-step, separate --chunk_cache/--chunk-cache |
Ordinary accepted-result reuse, with invocation-wide --cache auto|bypass|refresh. No explicit resume or selective checkpoint barrier. |
run and pipeline run are two native routes to the same command. Put flags
after the complete command path. Singleton occurrences are all parsed, with the
last successfully parsed value retained. False/zero/empty supplied values are not
omission. Canonical --llm-* execution overrides reach producers, correction,
and validators; shorter ckprompt aliases apply only to their installed PromptKit
commands. Help works offline on subcommands.
Migrate Configuration And Resources
Version 6 is the sole application version; bumping the header alone does not translate old fields. Use the maintained minimal or complete configuration as a starting point.
- Replace
promptkit.profile_file,profile_dir, andlocal_backendwrappers with native settings beneath the main file'spromptkit, or wrapperlessprompts.yml/ recursiveprompts/companions beside that selected main file. Companion files form strict peers, not filename-priority layers. - Use identified
backends,profiles, andpromptslists with literalidvalues and collections. The embedded profile isnotarius/dnd-extraction; initial/correction prompt IDs are also qualified, for examplenotarius/dnd.spellsandnotarius/dnd.spells.repair. - The root bundled backend is
openrouter. Retired external provider catalogs are not loaded as parallel sources; declare needed backends/profiles through native resources. Do not infer backend identity from an endpoint or model. - Use native root
configimports and preserve declaration-relative paths. Remove old per-prompt resource-version wrappers such asv1; resource IDs no longer select those versions. - A later same-ID resource replaces the whole earlier record. Use a distinct
sibling with
extends: {id: parent}to retain fields, not a partial same-ID replacement or self-inheritance. Profile/backend references to collection resources use qualified IDs; sibling inheritance is local to its list. - Preserve deliberate null/empty/zero choices under native semantics. Null endpoint/key-environment values can allow backend fallback; empty strings can clear those sources. Inspect native effective values/history rather than assuming old wrapper null behavior.
- Keep prompt-declared schemas. Inline schemas, source-relative
schema_file, and explicit-rootschema_pathare native alternatives. Replacing a collection schema root does not retain missing-file fallback to embedded resources.
Review native resource and schema rules before reusing an old profile file. The complete example's companion demonstrates current inheritance.
Separate Retry Intent, Mode, And Capacity
Producer retries intended for semantic correction becomes
max_additional_turns, excluding the initial response. Binding overrides pipeline;
omission inherits and explicit zero disables semantic correction. Native growing
continuation replaces latest-only manual replay, and each revised candidate gets
the full applicable assessment chain, including its final permitted turn.
Remove validator retries, generic deterministic retries,
structured_output_repair_attempts, and the application promptkit.transient_retries
wrapper. PromptKit owns transient failures and structural repair. Run-wide
transient customization uses --llm-transient-retries; structural customization
belongs in native prompt output contracts. Bundled prompts leave repair counts
unspecified. Former total provider-attempt parity is not promised.
Replace failure-category validation_policy and its fail_run, reject_output,
and warn_continue choices with producer mode: strict|permissive. Strict is
the default, including normalization. Permissive explicitly requests a supported
module fallback, not incomplete ordinary acceptance. Cancellation does not fall
back; unsupported fallback construction fails. Completion discloses actual
fallback emitters independently of warning visibility.
Replace concurrency.total_llm and concurrency.stage_workers.extract with
concurrency.workers, covering ready extraction and lane completion together.
Choose native backend capacity independently. There is no cross-backend global
LLM ceiling, inferred per-backend translation, or extra capacity queue/retry.
The configuration reference
owns current defaults and controls.
Replace Both Legacy Caches
Replace nested cache.chunk_plans / cache.checkpoints directories and recording
switches with root cache_directory and pipeline/binding cache. An explicit
invocation --cache overrides every binding. Auto reads/stores acceptance;
bypass does neither; refresh skips reads and replaces only after new acceptance.
The initial prepared native message-content hash selects final accepted artifacts and LLM plans. A hit is decoded/usability-checked, not semantically revalidated. Model/settings/policy changes can still hit; use refresh/bypass for experiments requiring fresh work. Source identity alone no longer fixes chunk boundaries. Fallback and actually affected consumers skip reuse; unaffected predecessors remain reusable after downstream failure. Failed refresh preserves old acceptance.
Do not copy, convert, or delete legacy records as an upgrade prerequisite. They remain ignored and untouched, and the new cache populates through ordinary work. Operations owns recovery and deployment-permission guidance.
Replace Receipt And Sidecar Traversal
Stop expecting notarius.run-result.v2, index_file, validation histories,
warning counts, index.json, manifest.json, or reporting-only rejection/
warning/diagnostic files. Check process status, optionally decode the
native completion report, then read configured
lane/auxiliary domain paths.
Use the report's absolute run directory, not a guessed run ID or newest-folder scan. Count actual deliverables rather than old normalized-output totals. The report does not establish fresh validation or model quality; decide whether positive fallback qualification is acceptable. Failed stdout can be partial, and post-publication failure can leave valid artifacts with a nonzero status.
Debug remains explicitly selected and independent of native visibility modes.
Directory-only configuration does not enable it; explicit empty disables it.
The relative latest link updates at start, not completion. Full selected
evidence replaces the old summary/trace hierarchy; filenames/JSON shapes remain
private and arbitrary application content is not heuristically sanitized.
Do not replace receipt traversal with a debug-layout dependency or a new manifest.
Update callers using the subprocess guide or complete D&D workflow. These changes do not publish a new release or rewrite historical release notes.