notarius/docs/releases/v0.4.0.md

Notarius v0.4.0

This release strengthens LLM reliability and validation throughout the configured pipeline, upgrades the PromptKit integration, and establishes the source-release and downstream-consumer workflows needed for broader D&D pipeline integration.

Summary

Notarius now distinguishes PromptKit structural-output repair from application-owned semantic validation retries. Producer candidates can run through complete deterministic validator chains, receive bounded semantic correction guidance, and retry under explicit stage policies. Final run receipts and manifests preserve bounded validation provenance, while outputs that advance with incomplete validation remain available to the current run without entering reusable checkpoint state.

The release also adds a maintained complete D&D subprocess-consumer workflow, diagnostic build versions, and the source-only release procedure used to publish this version.

Compatibility

• Configuration files must use schema version 4. Version 3 is not decoded or rewritten; rename the top-level scriptorium section to promptkit when migrating. See Configuration.
• PromptKit is pinned to v0.9.0. Operator profile files use PromptKit's v0.9.0 format and may use its profile-inheritance support. Notarius continues to resolve operator profiles before embedded fallbacks.
• Structural-output repair and semantic stage retries are separate bounded mechanisms. Maintained production prompts request one structural repair by default; explicit configuration can override the supported repair count.
• Validation policy can now fail a run, reject an output, or permit an otherwise valid candidate to advance with incomplete-validation provenance. The application defaults are documented in Configuration.
• The notarius.run-result.v1 receipt remains at schema version 1 and adds optional validation summaries plus a required validation-status field. Consumers of this pre-release contract should follow the current run-result receipt.
• Existing D&D artifact schema identities remain unchanged. Validation and producer-policy changes can nevertheless cause previously accepted weak candidates to retry, reject, or fail instead.

Upgrade

1. Migrate every Notarius configuration to version 4 and rename scriptorium to promptkit.
2. Review deployed PromptKit profiles against the pinned v0.9.0 profile format and ensure their credential environment variables are available at run time.
3. Run notarius config validate --config <path> --pipeline <id> before the first production invocation.
4. Review structured_output_repair_attempts, producer retry counts, and validation_policy wherever the deployment needs behavior different from the documented defaults.
5. Update subprocess consumers to inspect receipt validation_status and to tolerate the optional bounded validation_summaries field. A consumer that requires fully validated artifacts should require approved.

Changes

• Upgraded PromptKit from v0.5.0 through v0.9.0 and adopted profile inheritance, structured-output repair, typed error classification, and the correction-aware completion protocol.
• Added pipeline and binding configuration for structural repair and terminal validation policy, with strict startup validation and effective-setting provenance.
• Added feedback-aware retries for chunking, extraction, merge, normalize, and semantic reconciliation producers. Retry prompts contain the exact defective response and actionable semantic correction guidance without exposing internal reason codes or opaque entity identifiers.
• Added complete validator-chain execution, validator retry handling, bounded warnings, terminal dispositions, and durable validation summaries.
• Prevented validation-incomplete artifacts and all derived lineage from loading or publishing reusable checkpoints while preserving same-run generated-reference handoff.
• Tightened cached chunk-plan validation so only completely validated plans are reused or replace stored plans.
• Added a machine-readable subprocess receipt workflow and complete D&D consumer documentation covering all maintained artifacts.
• Added source-release checks, immutable lightweight-tag guidance, Linux and Darwin build verification, and diagnostic notarius --version output.