promptkit/docs/releases/v0.6.0.md

Promptkit v0.6.0

This supplemental changelog and migration guide summarizes the consumer-facing changes from v0.5.0 to v0.6.0. The annotated v0.6.0 tag is the authoritative release record. Exact current contracts belong to the linked GoDoc and durable documentation.

Summary

v0.6.0 is a broad correctness, safety, efficiency, and maintainability release. It does not add or remove public declarations. The release:

• centralizes shared execution-setting, output-contract, endpoint, and JSON-compatible-value rules;
• unifies prompt repository behavior and avoids unnecessary prompt and profile decoding;
• bounds consumer-controlled JSON trees and successful provider responses;
• hardens prompt content paths, artifact files, provider URLs, JSON framing, and error propagation;
• reuses compiled schema plans and rendered artifact text within an operation; and
• improves cancellation behavior, prepared-value ownership, deterministic transport testing, and maintainer validation.

Compatibility

No public declaration was added, removed, or changed. Ordinary valid v0.5.0 configurations and requests should continue to compile and behave as before.

The release intentionally rejects or reports several inputs that were previously accepted, altered, or misclassified:

• execution settings must be finite, within their documented ranges, and safe to convert to Go durations;
• output formats, validation modes, repair counts, and JSON Schema dependencies are validated consistently;
• file-backed prompt and profile identity comes from normalized YAML metadata, not filenames;
• prompt content_file values must be exact relative paths contained by their configured source root;
• built-in file artifacts must resolve to regular files;
• selected provider endpoints must be absolute HTTP or HTTPS URLs without user information, query strings, or fragments;
• JSON documents and successful provider responses must contain exactly one value, and successful provider bodies are limited to 16 MiB; and
• excessively deep or expansive JSON-compatible values fail with ordinary validation errors.

These are compatibility corrections and safety boundaries rather than new consumer configuration requirements. Consumers relying on an invalid or ambiguous input should correct that input before upgrading.

Upgrade

Update the module dependency with:

go get gitea.maximumdirect.net/eric/promptkit@v0.6.0
go mod tidy

Run the consuming project's ordinary and race-enabled tests after upgrading. Applications with custom prompt/profile sources, local provider endpoints, unusual artifact paths, or assertions over provider error identities should pay particular attention to the compatibility notes below.

Source Loading And Identity

Prompt definitions now share one source-neutral selection and normalization flow across operating-system and fs.FS sources. YAML id and version metadata are authoritative; filenames do not create a second identity system. Only selected content bodies are loaded, malformed unrelated definitions do not shadow valid exact matches, and per-file read failures are reported as prompt-load failures rather than false absence.

File-backed profiles likewise use normalized YAML IDs, reuse their metadata read for selected strict decoding, and avoid fully decoding unrelated files. Selected malformed definitions remain authoritative and do not silently fall through to a lower-precedence source.

Prompt content_file paths are opened exactly as declared after a separate blank check. They must remain relative to and contained by the configured prompt source root, including across operating-system symlinks.

See the framework source and identity reference and internal source overview for the current contracts.

Validation, Cancellation, And Efficiency

JSON Schema documents preserve exact JSON-number representations. Schema resource URLs safely escape legal filesystem names, and each operation loads and compiles its schema graph once. Run and prepared execution reuse that operation-local plan; Promptkit does not introduce a cross-operation cache.

Artifact reading, rendering, schema loading, compilation, and validation now check cancellation at the synchronous boundaries Promptkit controls. Rendering memoizes each artifact's text within one render operation, while plain JSON validation avoids materializing an unnecessary generic tree.

The shared JSON-compatible-value owner now limits nesting and produced work so unsafe consumer-controlled structures return errors instead of risking unbounded recursion or allocation. See the architecture policy for invariant ownership and the format reference for validation behavior.

Provider Transport Hardening

OpenAI-compatible endpoints are parsed and composed structurally, including nested base paths. Underlying transport cancellation and deadline errors remain discoverable with errors.Is through Promptkit's generation error category.

Successful provider bodies are read with a fixed 16 MiB bound and must contain exactly one JSON response object followed only by whitespace. Oversized, truncated, malformed, or multiply framed responses fail without returning a partial result. See the OpenAI-compatible integration contract for the canonical request, endpoint, error, and response behavior.

Public API Changes

None.

Consumer Action

• Correct any configuration or request that depends on the formerly permissive cases described under Compatibility.
• Confirm custom local provider endpoints are absolute HTTP or HTTPS base URLs without credentials, queries, or fragments.
• Confirm prompt content paths remain within their configured source root and file artifacts resolve to regular files.
• Run ordinary and race-enabled consumer tests after updating the dependency.