Files
notarius/docs/consumers/native-migration.md

144 lines
8.6 KiB
Markdown
Raw Normal View History

# 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](../config.md), [CLI Reference](../cli.md), and
[Operations](../operations.md) 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](../../examples/dnd-minimal/config.yml) or
[complete](../../examples/dnd-complete/config.yml) configuration as a starting point.
- Replace `promptkit.profile_file`, `profile_dir`, and `local_backend` wrappers
with native settings beneath the main file's `promptkit`, or wrapperless
`prompts.yml` / recursive `prompts/` companions beside that selected main file.
Companion files form strict peers, not filename-priority layers.
- Use identified `backends`, `profiles`, and `prompts` lists with literal `id`
values and collections. The embedded profile is
`notarius/dnd-extraction`; initial/correction prompt IDs are also qualified,
for example `notarius/dnd.spells` and `notarius/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 `config` imports and preserve declaration-relative paths.
Remove old per-prompt resource-version wrappers such as `v1`; 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-root `schema_path` are native alternatives. Replacing a collection
schema root does not retain missing-file fallback to embedded resources.
Review [native resource and schema rules](../config.md#promptkit-profiles) before
reusing an old profile file. The complete example's
[companion](../../examples/dnd-complete/prompts.yml) 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](../config.md#concurrency-output-cache-and-debug)
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](../operations.md#accepted-result-cache-and-recovery) 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](../cli.md#completion-report), then read configured
lane/auxiliary [domain paths](../integrations/json-output.md).
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](subprocess.md) or
[complete D&D workflow](dnd-pipeline.md). These changes do not publish a new release
or rewrite historical release notes.