notarius/docs/releases/v0.7.0.md

Notarius v0.7.0

This release simplifies configuration management with ConfigKit and makes cache access permissions a deployment responsibility.

Summary

Notarius adopts ConfigKit v0.3.0 for strict configuration loading, imports, configuration profiles, provenance, and redacted inspection. Operators can compose whole pipeline definitions from separate files and select development overlays without duplicating the base configuration.

Configured relative filesystem paths now resolve against their declaring files, including imported definitions and profile replacements. The effective configuration and its explanation reflect the paths used at runtime.

Compatibility

• Configuration version 5 replaces version 4; there is no compatibility loader. Numeric version: 5 is the canonical spelling; quoted "5" also works.
• Module and validator bindings require objects with module:; external references require objects with path:. Lane-level reference aliases are removed; use binding-local references instead.
• Strict ConfigKit YAML parsing rejects aliases, merge keys, and unsupported scalar forms. See the configuration reference for the complete contract and migration guidance.
• The seven operational environment overrides are removed: NOTARIUS_TOTAL_LLM_CONCURRENCY, NOTARIUS_STAGE_WORKERS_EXTRACT, NOTARIUS_OUTPUT_DIR, NOTARIUS_CACHE_CHUNK_PLANS_MODE, NOTARIUS_CACHE_CHUNK_PLANS_DIR, NOTARIUS_CACHE_CHECKPOINTS_DIR, and NOTARIUS_DEBUG_DIR. NOTARIUS_CONFIG still selects the configuration file; PromptKit credential environment variables remain supported.
• Configured relative reference, PromptKit profile, output, cache, and debug paths use the canonical declaring file's directory. Built-in relative defaults use the main configuration directory. CLI-relative paths still use the invocation directory; absolute paths are unchanged.
• Requested debug bundles now contain effective-config.yml instead of effective-config.json. Inspection output is redacted and is not promised to be reloadable configuration.
• Chunk-plan and checkpoint cache writers respect deployment permissions through ordinary creation modes, umask, setgid inheritance, and default ACLs; they no longer impose private permissions. Existing entries are not chmodded or migrated. Output and debug access contracts are unchanged.
• Durable extraction artifact schemas and subprocess receipt formats are unchanged by this release.

Upgrade

1. Migrate deployed configurations to version 5 using the configuration migration guide. Expand shorthand bindings and references, and move retired environment settings into YAML or supported CLI overrides.
2. Review relative paths, particularly output/cache/debug directories and PromptKit profile sources. Use absolute paths when preserving an existing deployment location is important.
3. Review deployment access settings for cache directories. Provision umask, groups, and ACLs as appropriate; Notarius does not choose the installation's access policy. See Operations.
4. Use config validate --config <path> --pipeline <id> for each pipeline, including selected configuration profiles. Inspect resolved settings with config effective and their provenance with config explain; see the CLI reference.
5. Update any debug-bundle tooling that consumes the former effective JSON file. Subprocess callers may optionally select an overlay through --config-profile; this is separate from PromptKit's --llm-profile.

The maintained minimal and complete D&D examples demonstrate self-contained configuration and composed pipelines with a development profile. Build from the source tag using the source-release procedure.

Changes

• Replaced custom YAML parsing and environment-overlay machinery with a ConfigKit-backed typed document boundary and detached runtime conversion.
• Added imports, configuration profiles, source-aware normalization, safe effective/explanation commands, and source-file legends for load errors.
• Preserved explicit zeroes and empty validator overrides at supported stages, rejected invalid reference branches before conversion, and retained whitespace normalization for worker identifiers.
• Corrected normalization recording for ordered steps and validator sequences, with regression coverage for runtime values and provenance.
• Accepted ConfigKit's integer representation at module-option boundaries through checked shared conversion.
• Updated examples, configuration and subprocess guidance, and debug rendering.
• Reworked cache creation to respect deployment-selected permissions while retaining confined paths, symlink rejection, atomic publication, validation, and recovery.