Update native operations, consumer migration, and version checks
This commit is contained in:
143
docs/consumers/native-migration.md
Normal file
143
docs/consumers/native-migration.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user