diff --git a/docs/consumers/configuration-migration.md b/docs/consumers/configuration-migration.md index 6b9df66..337315b 100644 --- a/docs/consumers/configuration-migration.md +++ b/docs/consumers/configuration-migration.md @@ -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 diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index 7d08612..a7c5ea9 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -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. diff --git a/docs/formats.md b/docs/formats.md index d63fa1f..ef54356 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -6,7 +6,7 @@ This is the canonical reference for Promptkit's backend, profile, prompt, and schema definitions. The [Go consumer guide](consumers/pkg-promptkit.md) shows how to select sources and use an engine; the [OpenAI-compatible integration contract](integrations/openai-compatible-chat.md) -owns outbound wire behavior. [ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md) +owns outbound wire behavior. [ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.1.0/docs/config.md) owns the generic YAML grammar, imports, layering, inheritance, and diagnostics. This reference describes what Promptkit does with the final effective values. @@ -86,9 +86,10 @@ list. It is not a qualified or cross-collection reference. no label; an explicitly empty string is retained. It does not select a resource or change execution. Runtime lookups use the captured effective resource indexes. `InspectConfiguration` is an -explicit operator view of composed settings and provenance. Normalization and -defaults appear in Promptkit's interpreted execution views, not as changes to -that composed tree. Source history is not a second runtime resolver, and the +explicit operator view of resolved settings and provenance. Selected field +normalizations and the derived queue default are recorded in that tree, with +source history retained. Request-time completion remains separate. Source +history is not a second runtime resolver, and the retained effective shape is not flattened or rewritten into those indexes. For examples of explicitly selecting native collection inputs and inspecting @@ -363,7 +364,7 @@ references are exact IDs and use their qualified form when they select a collection resource. There is no Promptkit-specific depth limit or second base-chain resolver. Missing references and cycles fail at construction. For generic inheritance and layer mechanics, consult -[ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md). +[ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.1.0/docs/config.md). ## Schemas diff --git a/docs/internal/sources.md b/docs/internal/sources.md index 6992670..4f66740 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -12,13 +12,12 @@ source semantics. Internal packages are not consumer APIs. `internal/configuration` is the single adapter from ConfigKit's final effective configuration to execution-owned definitions. It performs one -layered load, captures effective presence (including explicit null), builds -detached normalized interpretations during validation, and validates all effective +layered load, captures effective presence (including explicit null), records +field-level normalization and derived defaults during resolution, and validates all effective root and collection backend, profile, and prompt values. Replaced lower-layer domain values are not separately validated. It indexes root resources under their unqualified IDs and collection resources under their full -`namespace/local-key` IDs while retaining ConfigKit's effective tree in its -authored shape. It builds an immutable backend index and presence-aware profile +`namespace/local-key` IDs while retaining ConfigKit's resolved tree. It builds an immutable backend index and presence-aware profile targets, applying final backend defaults only after profile inheritance. Runtime lookups use those final indexes and exact stored references; they do not rewrite or resolve resources from ConfigKit source history. The runtime/domain packages @@ -27,7 +26,7 @@ do not depend on ConfigKit. ConfigKit owns source headers, imports, composition, and source evidence. Promptkit does not preparse contributions: it validates the final effective values once, captures the indexed identities and their original resource -contexts, and retains ConfigKit's composed result for explicit operator inspection. +contexts, and retains ConfigKit's resolved result for explicit operator inspection. Accepted non-main source headers are consumed during composition; the main source declaration remains available in that inspection view. Collection release labels are descriptive metadata, not selection inputs. The @@ -37,12 +36,12 @@ owns the exact source-header and collection contracts. The `ConfigurationInspection.Diff` facade method compares two retained results through a private wrapper and a narrow `internal/configuration.Diff` bridge. The wrapper keeps `Result[document]` inside the adapter; the bridge delegates -once to ConfigKit v1.0.0 and returns its public difference records. Comparison +once to ConfigKit v1.1.0 and returns its public difference records. Comparison uses only frozen effective values and does not reopen sources, resolve runtime credentials, or enter the execution path. ConfigKit applies sensitivity from both results; reports may still contain ordinary application data. See the [consumer comparison guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration) -and ConfigKit's [v1.0.0 comparison contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md#effective-configuration-diffs). +and ConfigKit's [v1.1.0 comparison contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.1.0/docs/config.md#effective-configuration-diffs). After resource materialization and effective-profile snapshot construction, the adapter captures lexically ordered identity inventories for backends, profiles, @@ -85,12 +84,11 @@ returning and retains no source capability for public inspection. Prompt materialization shares a lazy metadata snapshot across root and collection resources during construction, avoiding a full metadata copy per collection. -Normalization and defaults are applied to execution-owned interpretations, -including message roles and cache controls. ConfigKit retains the composed -values and origins, rather than synthetic Promptkit normalization events. List -indexes identify fields for presence, validation, sensitivity, and resource -context; full IDs select captured runtime indexes. Recording a sequence-wide -normalization would replace origins of unchanged content-file fields. +Normalization and defaults are recorded at individual resolved field paths, +including message roles and cache controls. List indexes identify fields for +presence, validation, sensitivity, and resource context; full IDs select +captured runtime indexes. Unchanged content-file fields retain their origins. +Backend-to-profile and request-time completion remain separate runtime work. The runner selects full definitions from this index for preparation and uses captured prompt metadata for `InspectPrompt` and `InspectRequirements`; the diff --git a/docs/releases/v0.18.0.md b/docs/releases/v0.18.0.md new file mode 100644 index 0000000..eee22ba --- /dev/null +++ b/docs/releases/v0.18.0.md @@ -0,0 +1,14 @@ +# Promptkit v0.18.0 + +Configuration inspection now exposes Promptkit's recorded field normalization +and derived queue-capacity defaults. ConfigKit is updated to v1.1.0. Existing +source evidence remains available, and unchanged content-file origins continue +to select their resource context. + +Configuration diffs compare normalized effective values, so spelling-only +changes that normalize identically may no longer appear. Lists remain atomic in +diffs. Inspection does not include backend-to-profile completion or request +overrides; see the [configuration inspection guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration). +No configuration format or public API change is required to upgrade. + +[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.18.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.18.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.18.0/docs/oss/attribution.md) diff --git a/docs/roadmap/field-normalization.md b/docs/roadmap/field-normalization.md index 05f77e9..b44c501 100644 --- a/docs/roadmap/field-normalization.md +++ b/docs/roadmap/field-normalization.md @@ -2,8 +2,8 @@ ## Status And Purpose -Planned; implementation has not started. ConfigKit v1.1.0 is released, while -PromptKit currently depends on v1.0.0. +Implemented: PromptKit uses ConfigKit v1.1.0 and records the selected field +normalizations and queue default in its resolved configuration. Move PromptKit's existing configuration-time normalization and derived defaults into ConfigKit's recorded application resolution. Configuration inspection should @@ -15,13 +15,13 @@ The benefit is a more useful inspection view and removal of the parallel interpreted configuration maintained for execution. This is a focused loading change, not a new configuration format, normalization policy, or execution API. -## Current Baseline +## Historical Baseline PromptKit already uses identified lists for backends, profiles, and prompts at the root and within named collections. Six ConfigKit identity registrations cover those destinations. This roadmap does not repeat that migration. -The configuration adapter's `Definition.Resolve` currently captures input +At the baseline, the configuration adapter's `Definition.Resolve` captured input presence information. During validation, `interpretConfiguration` constructs detached backend, profile, and prompt interpretations and applies normalization and a conditional backend queue default. Runtime construction uses those @@ -34,7 +34,7 @@ ConfigKit v1.0.0. Such a record would replace the effective origins of unchanged fields, including `content_file`, whose origin selects the filesystem and directory used to load message text. -The current behavior is documented in the [format reference](../formats.md) and +The implemented behavior is documented in the [format reference](../formats.md) and [source-loading implementation](../internal/sources.md). The [configuration ownership decision](../adr/0001-configuration-boundary.md) continues to govern the division of responsibility: ConfigKit owns composition; diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 0d5fbdb..78d378b 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -268,3 +268,7 @@ construction; all selected transformations have field-level records; unchanged resource origins and runtime semantics are preserved; tests and documentation cover the intentional inspection change. There are no unresolved product decisions or upstream publication steps required by this plan. + +Completion: current guides and the next release note describe recorded effective +normalization and its limits. The race-enabled full suite, vet, and all three +example commands passed with Go 1.27.0; the full diff and formatting were reviewed.