base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Document recorded configuration normalization

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-03 03:32:59 +00:00
parent 43abbcb414
commit 855aae6daa
7 changed files with 52 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/consumers/configuration-migration.md
View File

@@ -134,9 +134,9 @@ Replace former maps passed to `BackendSource` in the same way, setting each
`BackendConfig.ID`. Duplicates are retained for loading to reject. Resource
inspection paths now address list indexes, for example
`configkit.Keys("profiles").Index(0).Key("model")`. Configuration inspection
and diffs expose composed values and provenance, while `InspectProfile` and
other interpreted views expose Promptkit normalization and defaults; the views
are not promised to be identical.
and diffs expose resolved values, recorded normalization and provenance.
`InspectProfile` additionally applies backend completion; request preparation
can apply further overrides, so the views are not promised to be identical.
Remove `PromptVersion` and `PromptIdentity.Version` uses and the corresponding
`prompt_version` JSON members. Prompt hashes are opaque equality values and may

15
docs/consumers/pkg-promptkit.md
View File

@@ -18,7 +18,7 @@ import "go.maximumdirect.net/promptkit"
For migration from the former module path, see
[Update Go Imports](configuration-migration.md#update-go-imports).
Configuration APIs use `go.maximumdirect.net/configkit` v1.0.0. Its types are
Configuration APIs use `go.maximumdirect.net/configkit` v1.1.0. Its types are
not interchangeable with the old ConfigKit module path.
The maintained [offline preparation example](../../examples/go-library/prepare/main.go)
@@ -211,7 +211,7 @@ sensitive application data.
## Inspect The Captured Configuration
Use [`Engine.InspectConfiguration`](../../configuration_inspection.go) for an
operator-selected report of composed configuration, source descriptions,
operator-selected report of resolved configuration, source descriptions,
diagnostics, and path history. Configuration inspection uses list indexes in
the collection's nested path rather than qualified runtime IDs. For a profile
at index `i` in collection `team`, construct the path with `configkit.Keys`:
@@ -230,8 +230,9 @@ if found && explanation.Effective.Redacted {
the application decides whether those reports may be disclosed. Credential-
shaped provider keys are redacted, but arbitrary prompt and provider content
is not necessarily safe to share. Inspection uses the engine's captured result
and does not reopen sources or resolve credentials. It retains composed values
and provenance rather than Promptkit's normalized/defaulted interpretation.
and does not reopen sources or resolve credentials. It retains effective values,
including recorded field normalization and queue defaulting, alongside source
provenance.
`InspectProfile` instead shows backend-completed execution settings for one profile, and `Prepare` or
`PreparedExecution.Details` shows request-specific rendered messages, inputs,
and validation resources. None of those views is a substitute for the others.
@@ -263,11 +264,13 @@ for _, difference := range differences {
```
See the [`ConfigurationInspection.Diff` GoDoc](../../configuration_inspection.go)
and ConfigKit's [v1.0.0 effective-configuration diff guidance](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md#effective-configuration-diffs)
and ConfigKit's [v1.1.0 effective-configuration diff guidance](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.1.0/docs/config.md#effective-configuration-diffs)
for the exact comparison contract. The operation compares only frozen effective
configuration values: it does not reread external files or compare their
contents, resolved credential contents, later execution preparation, or
request-specific overrides. An empty diff is not proof of equivalent execution.
request-specific overrides. Inputs normalizing to the same effective value do
not create a value diff; lists are compared atomically. An empty diff is not
proof of equivalent execution.
Records can contain ordinary application data, so use the application's
disclosure policy when presenting them.