diff --git a/docs/roadmap/imports.md b/docs/roadmap/imports.md new file mode 100644 index 0000000..0f2b32a --- /dev/null +++ b/docs/roadmap/imports.md @@ -0,0 +1,245 @@ +# Library Updates: ConfigKit, ReleaseKit, and PromptKit + +**Reviewed:** 2026-10-11. +**Status:** Reviewed and recommended; dependency upgrades and optional feature +adoption are not implemented by this document. + +## Scope and Reviewed Baseline + +Review the released library changes since Audita's current imports and identify +the work needed to adopt them. Audita's baseline is commit +`6debe7e`, with the versions declared in [go.mod](../../go.mod). +The local library checkouts were clean and matched the released source commits; +the remote annotated tags were checked against their peeled commits. + +| Library | Current import | Recommended import | Full reviewed upstream commit | +| --- | --- | --- | --- | +| ConfigKit | v0.5.0 | v0.7.1 | `6fffde4af8f31f99d3ee295c426eb3234cb0fb77` | +| ReleaseKit | v0.3.0 | v0.4.1 | `2d5a8110c61e31daf8698766114ae305d0e0e469` | +| PromptKit | v0.12.0 | v0.14.0 | `143c6e9b3a675872117b0471e2ff8bcb25055a54` | + +The review covers intervening releases, not just each latest patch. Evidence +includes release notes, consumer documentation, public API implementations, +Audita's integration code, and a disposable compatibility exercise using the +released modules. Public web rendering was unavailable; local tagged sources +and remote Git tag checks supplied the evidence. + +## Target State and Recommendation + +Upgrade all three libraries together to the versions above, retaining Audita's +current configuration format, CLI, processing, diagnostics, and release model. +No application-code migration was needed in the compatibility exercise. +ConfigKit and PromptKit improvements become available through existing calls; +new operator-facing discovery and comparison features remain separate choices. + +All selected libraries declare Go 1.26.0. Audita already declares that minimum +and uses Go 1.26.8 for release validation, so this adoption requires no minimum, +CI image, or distributed Go-runtime notice change. PromptKit v0.14.0 requires +ConfigKit v0.7.1; both library module graphs also select ReleaseKit v0.4.1 as a +maintainer tool dependency. Go module selection therefore couples these updates, +even though ReleaseKit's orchestration is not part of their runtime imports. + +Keep the ownership boundaries in the [architecture policy](../policy/architecture.md): +ConfigKit owns loading and provenance, PromptKit owns LLM execution and captured +definitions, ReleaseKit owns release mechanics, and Audita owns transcript +behavior and application meaning. This review does not select CommandKit +adoption or introduce new release gates. + +## ConfigKit: New Capabilities and Adoption Work + +### Changes Since v0.5.0 + +- **v0.6.0:** Reduces loading and inspection work through fewer path allocations, + combined metadata traversal, indexed resolution and sensitivity processing, + lightweight presence queries, and prepared immutable inspection lookups. + Existing composition, inheritance, presence/null, provenance, and secret + contracts remain unchanged. It raises the consumer minimum to Go 1.26.0 and + adopts ReleaseKit for its own publication. +- **v0.7.0:** Adds `configkit.Diff[T](left, right *Result[T])`, comparing frozen + effective inspection values from two successful loads. Results contain a + semantic `Path`, left/right `ValueSnapshot` values, and `HiddenChanged`. + Mappings compare recursively, sequences are atomic changed regions, and + presence distinguishes missing values from explicit null. Combined sensitivity + from both loads protects the paired snapshots, including historical and + dependency-derived sensitivity. +- **v0.7.1:** Updates the maintainer ReleaseKit dependency to v0.4.1. Runtime + behavior and public APIs are unchanged from v0.7.0. + +References: [v0.6.0 notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.6.0/docs/releases/v0.6.0.md), +[v0.7.0 notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/docs/releases/v0.7.0.md), +[v0.7.1 notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/releases/v0.7.1.md), +and [comparison guidance](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/consumers/README.md#effective-configuration-diffs). + +### Work Needed + +The dependency update needs module/checksum and attribution changes. Existing +`internal/core/config` callers need no signature or configuration migration. +Retain coverage for application resolution, explicit CLI overrides, overlays, +inheritance, provenance, and redaction; these are the boundaries affected by +upstream internal optimizations. No fixed performance gain is promised or +required for adoption. + +If configuration comparison is selected later, load two complete selections +through Audita's normal application definition and call the public diff API. +Audita would own selection syntax and presentation. Use presence and +`HiddenChanged` directly rather than interpreting redaction-marker strings. +Do not add separately rendered full configurations as purportedly cross-protected +context: protection applies to the returned changed regions. Reference names, +not resolved credential bytes, participate in typed secret-reference comparison. +Equal values with different provenance do not produce differences; later +mutations of `Result.Config` are outside the captured comparison. + +## ReleaseKit: New Capabilities and Adoption Work + +### Changes Since v0.3.0 + +- **v0.4.0:** Adds individual-module releases with `ModuleDir`, module identity, + complete module-prefixed tags, module-local validation/builds, separate Gitea + pages, and mapped multi-module launchers. Root-module defaults retain ordinary + tags and note locations. +- Adds explicit shared-file selection for optional file checks, module-bound + versioned build receipts, expected-module checks, and `ci-deliver --prepared` + for an already verified detached checkout. +- Improves checkout-root and symlink resolution, offline committed-source + inspection, available build-failure evidence, and reuse of Go discovery and + asset verification. Independent nested modules are excluded from automatic + parent-module file inspection; product tests can still use nested fixtures. +- Introduces an API/receipt cutover: `TaggedCheckoutRequest.Version` becomes + `Tag`; `PrepareBuildDependencies` takes `DependencyPreparationRequest`; old + prebuilt receipts need regeneration with the new builder. +- **v0.4.1:** Fixes concurrency in delivery test fixtures. Production behavior + and public APIs are unchanged from v0.4.0. + +References: [v0.4.0 notes and migration guidance](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/releases/v0.4.0.md), +[v0.4.1 notes](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/releases/v0.4.1.md), +and [current delivery contract](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/cli.md). + +### Work Needed + +Audita uses the Go tool CLI and lightweight `buildinfo` facade. It has no callers +of the changed preparation APIs and does not need module maps, prefixed tags, +new shared-file settings, or a multi-module layout. Its root-module +[release profile](../../releasekit.json) and [launcher](../../scripts/release.sh) +can retain their current configuration. Runtime version access is unchanged. + +Update the selected dependency, checksums, attribution, and v0.3.0-pinned +consumer links in [the release runbook](../release.md). Recommend adding +`--prepared` to [.woodpecker/release.yml](../../.woodpecker/release.yml): bootstrap +already verifies and checks out the event tag before reading module metadata, +so the new mode avoids repeating fetch/checkout while retaining ReleaseKit's +verification. Update the runbook and focused workflow coverage for that deliberate +change. Keeping the current default preparation mode is also supported and is +not an adoption blocker. + +Keep historical delivery retries paired with their tagged tool selection and +workflow. Existing v0.3.0 retained artifacts should use that version's delivery +path; regenerate receipts with the new builder when intentionally using v0.4.1 +prebuilt delivery. Do not imply that historical receipts are portable across the +cutover or replace already published contents. + +Use existing launcher/profile/CI tests, verify the two production builds and +injected version behavior during implementation, and keep source publication +separate from asynchronous delivery. This upgrade requires no real tag push, +hosted upload, CI wait, expanded platform matrix, or new approval gate. + +## PromptKit: New Capabilities and Adoption Work + +### Changes Since v0.12.0 + +- **v0.13.0:** Adds `Engine.InspectRequirements` for recognizable input and + caller-variable dependencies before artifacts exist. It distinguishes + required, conditional, and optional dependencies and reports incomplete + discovery with structured issues. It analyzes selected prompt/template and + caller context without preparing artifacts or executing a model request. +- Adds `Engine.ListProfiles` and `Engine.ListPrompts`, exposing lexically ordered, + caller-owned effective profile IDs and exact prompt ID/version pairs from the + captured engine configuration, without provider calls. +- Reduces avoidable response/rendering copies, repeated parameter encoding, + artifact-file allocation, prepared-snapshot copying, and inspection lookup + work. ConfigKit v0.6.0 improves engine construction and configuration inspection. + The Go minimum becomes 1.26.0, and maintainer publication adopts ReleaseKit. +- **v0.14.0:** Adds `ConfigurationInspection.Diff`, delegating paired captured + configuration comparison to ConfigKit. It also selects ConfigKit v0.7.1 and + ReleaseKit v0.4.1. + +References: [v0.13.0 notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.13.0/docs/releases/v0.13.0.md), +[v0.14.0 notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.14.0/docs/releases/v0.14.0.md), +and [consumer inspection guidance](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.14.0/docs/consumers/pkg-promptkit.md). + +### Work Needed + +Existing runtime construction, keyed prompt/profile assets, schema preparation, +execution, retry/repair, and backend admission calls remain supported. Upgrade +the module and checksums, update attribution and affected pinned integration +references, and reuse Audita's offline adapter/runtime and subprocess tests. +Preserve its selected-profile completeness checks, direct backend credentials, +capacity sharing, schema/domain validation, partial success, and redaction. +No prompt rewrite, profile conversion, or new validation gate is needed. + +Optional adoption opportunities are: + +- **Definition discovery:** Use listing APIs for operator discovery or better + unknown-profile diagnostics. Keep returned membership separate from readiness + to execute. Define the user surface before adding CLI commands; coordinate + shared inspection syntax with any separately selected CommandKit adoption. +- **Prompt requirement analysis:** Use `InspectRequirements` as a development + diagnostic for embedded or operator-overridden prompts. Partial discovery is + useful evidence, not proof of a broken prompt. Do not turn incomplete analysis + into a startup prohibition or treat complete discovery as execution validation. + Existing `InspectPrompt`, preparation, schemas, and domain checks retain their + different roles. This API is unrelated to guided response recovery. +- **Engine configuration comparison:** Compare two successful engines through + their captured configuration inspections. A future Audita comparison feature + should distinguish application settings from the PromptKit scope; engine + inspection alone does not represent every application setting or execution + effect. An empty diff does not prove identical behavior: referenced file + contents, resolved credentials, preparation, and request overrides are outside + the comparison. Ordinary public values may still be sensitive application data. + +These APIs are useful foundations, but exposing them is additional product work, +not necessary to obtain the dependency updates and efficiency improvements. + +## Common Adoption Work and Verification + +Update `go.mod` and `go.sum` together, retaining the registered ReleaseKit tool. +The reviewed module graphs retain existing catalog versions, YAML dependency, +and other selected dependency versions; the disposable tidy changed only the +three direct versions in `go.mod`. + +Update the three entries in [attribution](../oss/attribution.md) to the exact +reviewed commits under the [OSS policy](../policy/oss.md). Their root `COPYRIGHT` +and `LICENSE` files are unchanged relative to Audita's current selected versions; +retain existing LGPL/GPL texts. Check actual resulting dependency selection +before finalizing notices. Audita's application grant remains unchanged. + +Recommend one bounded dependency-and-documentation update, with the small CI +prepared-mode adjustment if selected. Do not introduce compatibility shims or +implement new comparison/discovery commands merely to exercise optional APIs. +Any selected user-facing feature should get its own defined scope and roadmap. + +The review used a temporary archive of Audita's baseline, selected the actual +released modules with `go get`, and ran `go mod tidy`. On Go 1.26.8 Linux amd64: + +- The complete Audita suite passed with `GOWORK=off`, `GOTOOLCHAIN=local`, + `GOPROXY=off`, and `GOSUMDB=off` after dependency preparation. +- Both Linux targets built, and the native executable's version command ran. +- The ReleaseKit v0.4.1 CLI built and displayed `ci-deliver` help. +- Local, inheritance, service, and service-testing-overlay configuration examples + validated with a synthetic credential and no inference calls. + +This evidence supports compatibility; it does not certify real source +publication, version injection through the new release builder, hosted delivery, +performance gains, or operator-facing optional features. Actual implementation +should validate its final changed candidate and selected CI behavior. Live +delivery remains separate from release completion under the existing policy. + +## Open Decisions + +No decision blocks the basic dependency upgrade. Whether to expose configuration +comparison, definition listings, or requirement diagnostics remains optional. +Recommend upgrading first and designing the chosen operator features separately: +the current API additions are independently useful, and a dependency refresh +need not define a new CLI. A viable alternative is one combined feature effort +that upgrades dependencies and adds selected inspection commands; that can reduce +repeat integration work, but requires decisions about selection syntax, report +scope, disclosure, and command ownership before implementation.