eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Document the latest library updates and adoption work

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-11 01:25:53 +00:00
parent 6debe7e641
commit 07fab5586b
1 changed files with 245 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

245
docs/roadmap/imports.md Normal file
View File

@@ -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.