Revise configuration plans to preserve source provenance
This commit is contained in:
@@ -1,7 +1,8 @@
|
|||||||
# ConfigKit v1 Adoption And Identified Resource Collections
|
# ConfigKit v1 Adoption And Identified Resource Collections
|
||||||
|
|
||||||
Status: accepted direction; implementation pending. This roadmap describes
|
Status: accepted direction; implementation in progress. The target below includes
|
||||||
future behavior, not the currently supported configuration format.
|
the agreed execution-owned normalization adjustment for ConfigKit v1.0.0.
|
||||||
|
Current consumer documentation remains authoritative for supported behavior.
|
||||||
|
|
||||||
The companion [implementation plan](implementation.md) owns the ordered sprint
|
The companion [implementation plan](implementation.md) owns the ordered sprint
|
||||||
steps and validation assignments.
|
steps and validation assignments.
|
||||||
@@ -20,9 +21,9 @@ authoring guidance, not a prohibition on deliberate same-ID replacement across
|
|||||||
configuration layers. Keep ConfigKit responsible for composition and inheritance;
|
configuration layers. Keep ConfigKit responsible for composition and inheritance;
|
||||||
PromptKit interprets the final effective configuration and owns resource meaning.
|
PromptKit interprets the final effective configuration and owns resource meaning.
|
||||||
|
|
||||||
## Current Baseline
|
## Pre-Migration Baseline
|
||||||
|
|
||||||
The repository currently declares Go 1.26.0 and depends on
|
Before this migration, the repository declared Go 1.26.0 and depended on
|
||||||
`gitea.maximumdirect.net/eric/ConfigKit` v0.8.0. The
|
`gitea.maximumdirect.net/eric/ConfigKit` v0.8.0. The
|
||||||
[format reference](../formats.md) and [source adapter overview](../internal/sources.md)
|
[format reference](../formats.md) and [source adapter overview](../internal/sources.md)
|
||||||
describe the implemented behavior:
|
describe the implemented behavior:
|
||||||
@@ -59,7 +60,10 @@ Update PromptKit's existing uses of:
|
|||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `Definition.Secret` | `Definition.Sensitive` |
|
| `Definition.Secret` | `Definition.Sensitive` |
|
||||||
| `Resolution.InputInfo` | `Resolution.EntryInfo` |
|
| `Resolution.InputInfo` | `Resolution.EntryInfo` |
|
||||||
| `Resolution.Record(..., ChangeNormalization, ...)` | `Resolution.RecordNormalization(...)` |
|
|
||||||
|
Migrate recording API names where still used; PromptKit's normalization and
|
||||||
|
defaults follow the execution-owned interpretation described below rather than
|
||||||
|
requiring ConfigKit resolution records for fields within resource lists.
|
||||||
|
|
||||||
Audit the remaining exposed inspection types and diagnostic consumers against
|
Audit the remaining exposed inspection types and diagnostic consumers against
|
||||||
the complete [ConfigKit v1.0.0 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/releases/v1.0.0.md).
|
the complete [ConfigKit v1.0.0 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/releases/v1.0.0.md).
|
||||||
@@ -132,6 +136,34 @@ in the assembled list shape, including its index-based paths and provenance.
|
|||||||
Do not impose a new execution-order meaning on list position or change the
|
Do not impose a new execution-order meaning on list position or change the
|
||||||
existing inventory sorting solely because source resources become lists.
|
existing inventory sorting solely because source resources become lists.
|
||||||
|
|
||||||
|
### Composed Configuration And Execution Interpretation
|
||||||
|
|
||||||
|
Accommodate ConfigKit v1.0.0's atomic sequence-mutation auditing. Retain the
|
||||||
|
composed typed configuration, field presence, and provenance supplied by
|
||||||
|
ConfigKit. Apply PromptKit's domain normalization and defaults to owned
|
||||||
|
interpretations of those final records during engine construction, preserving
|
||||||
|
existing execution behavior and domain validation.
|
||||||
|
|
||||||
|
Configuration inspection, explanations, and diffs describe ConfigKit's composed
|
||||||
|
values and provenance. They do not include PromptKit-side trimming, endpoint
|
||||||
|
normalization, or execution defaults as ConfigKit resolution history. Existing
|
||||||
|
prompt/profile inspection and preparation expose their respective interpreted
|
||||||
|
metadata or effective execution settings. These views have distinct purposes;
|
||||||
|
an authored whitespace difference can remain visible in a configuration diff
|
||||||
|
even when it has no effect on the interpreted setting.
|
||||||
|
|
||||||
|
Interpretation preserves exact identities, references, presence/null semantics,
|
||||||
|
and the association between records and effective index paths. Relative resources
|
||||||
|
such as `content_file` resolve through the contributing field's ConfigKit origin
|
||||||
|
and source context. Normalization does not replace that attribution with an
|
||||||
|
application-generated whole-list origin.
|
||||||
|
|
||||||
|
This remains interpretation of the final handoff, not source prevalidation or
|
||||||
|
another composition pass. It requires no upstream change or new public API.
|
||||||
|
Field-granular normalization within ConfigKit itself is a separate
|
||||||
|
[future idea](future.md#field-level-normalization-with-preserved-list-provenance)
|
||||||
|
to reevaluate after upstream support is available.
|
||||||
|
|
||||||
### Go Source-Builder Inputs
|
### Go Source-Builder Inputs
|
||||||
|
|
||||||
Add an `ID string` field to `ProfileConfig` and `BackendConfig`. Change
|
Add an `ID string` field to `ProfileConfig` and `BackendConfig`. Change
|
||||||
@@ -244,6 +276,8 @@ in arbitrarily named collections. Equal local IDs in separate namespaces remain
|
|||||||
independent. Registered identities govern strict composition, inheritance,
|
independent. Registered identities govern strict composition, inheritance,
|
||||||
layering, and final typed values through ConfigKit. PromptKit retains its domain
|
layering, and final typed values through ConfigKit. PromptKit retains its domain
|
||||||
validation, presence-aware settings, partial profiles, and exact runtime lookup.
|
validation, presence-aware settings, partial profiles, and exact runtime lookup.
|
||||||
|
Domain checks use PromptKit's interpreted values without mutating ConfigKit's
|
||||||
|
retained configuration or replaying source history.
|
||||||
|
|
||||||
Inherited and replaced prompt fields retain their contributing resource context.
|
Inherited and replaced prompt fields retain their contributing resource context.
|
||||||
Sensitive provider values remain protected in inspection at index-based paths.
|
Sensitive provider values remain protected in inspection at index-based paths.
|
||||||
@@ -259,6 +293,9 @@ GoDoc, and maintained examples describe the integrated target when it lands.
|
|||||||
Migration guidance covers the new module/types, Go minimum, controls, import
|
Migration guidance covers the new module/types, Go minimum, controls, import
|
||||||
requiredness, identified lists, explicit-ID source builders, sibling inheritance,
|
requiredness, identified lists, explicit-ID source builders, sibling inheritance,
|
||||||
removed prompt labels, specification headers, and index-based inspection paths.
|
removed prompt labels, specification headers, and index-based inspection paths.
|
||||||
|
It also explains composed configuration inspection versus PromptKit's normalized
|
||||||
|
metadata and execution settings, including the absence of ConfigKit history for
|
||||||
|
PromptKit-side normalization/defaults.
|
||||||
Attribution identifies the selected ConfigKit revision and applicable notices.
|
Attribution identifies the selected ConfigKit revision and applicable notices.
|
||||||
|
|
||||||
Deliver this as one coordinated breaking pre-v1 minor upgrade under the existing
|
Deliver this as one coordinated breaking pre-v1 minor upgrade under the existing
|
||||||
|
|||||||
@@ -1,14 +1,30 @@
|
|||||||
# ConfigKit v1 And Identified Resources Implementation Plan
|
# ConfigKit v1 And Identified Resources Implementation Plan
|
||||||
|
|
||||||
Status: ready for implementation.
|
Status: implementation in progress; resume with Stage 11's normalization recovery.
|
||||||
|
|
||||||
Implement the accepted [feature roadmap](configkit.md) as one end-to-end sprint.
|
Implement the accepted [feature roadmap](configkit.md) as one end-to-end sprint.
|
||||||
Each sequentially numbered stage is one prompt-sized assignment for a Luna
|
Each sequentially numbered stage is one prompt-sized assignment for a Luna
|
||||||
coding agent. The roadmap owns intent and policy; this plan owns delivery steps.
|
coding agent. The roadmap owns intent and policy; this plan owns delivery steps.
|
||||||
|
|
||||||
|
## Resume Point And Contract Correction
|
||||||
|
|
||||||
|
Stages 1–10 have recorded implementation commits through `e01b232`. Testing in
|
||||||
|
the former Stage 11 exposed an incompatible assumption in this plan: ConfigKit
|
||||||
|
v1.0.0 audits a changed sequence as one atomic value, so a field-level record does
|
||||||
|
not cover that change. Recording the whole list would replace descendant origins
|
||||||
|
needed for relative resources and inspection.
|
||||||
|
|
||||||
|
Resume at the new Stage 11, then Stage 12, which implement the approved
|
||||||
|
execution-owned interpretation instead. The former unfinished Stages 11–20 are
|
||||||
|
now Stages 13–22. Preserve the existing uncommitted Stage 11 work and integrate
|
||||||
|
it into its corresponding assignments; do not reset or restart completed work.
|
||||||
|
Earlier completion records remain historical evidence, not proof that the revised
|
||||||
|
normalization target is already implemented. The revised instructions and
|
||||||
|
Delivery Decisions below govern the final state.
|
||||||
|
|
||||||
## Baseline And Working Rules
|
## Baseline And Working Rules
|
||||||
|
|
||||||
The reviewed baseline is `07a55e45f2a3c68918c12fe5caa3e814ee00227c`, with Go
|
The original reviewed baseline is `07a55e45f2a3c68918c12fe5caa3e814ee00227c`, with Go
|
||||||
1.26.0, ConfigKit v0.8.0 at the old module path, keyed resource mappings, and
|
1.26.0, ConfigKit v0.8.0 at the old module path, keyed resource mappings, and
|
||||||
descriptive prompt-version labels. No implementation changes accompany this
|
descriptive prompt-version labels. No implementation changes accompany this
|
||||||
plan. The local ConfigKit checkout's v1.0.0 tag resolves to
|
plan. The local ConfigKit checkout's v1.0.0 tag resolves to
|
||||||
@@ -99,10 +115,10 @@ Separate three things throughout the adapter:
|
|||||||
- local identity: `record.ID`, validated with existing exact local-ID rules;
|
- local identity: `record.ID`, validated with existing exact local-ID rules;
|
||||||
- runtime identity: existing namespace qualification of that local ID.
|
- runtime identity: existing namespace qualification of that local ID.
|
||||||
|
|
||||||
Use the index path for presence, normalization/default records, validation,
|
Use the index path for presence, validation errors, origins, and sensitivity.
|
||||||
origins, and sensitivity. Use the full identity for execution-owned maps.
|
Use the full identity for execution-owned maps. Preserve the retained ConfigKit
|
||||||
Mutate slice elements in place during resolution; avoid accidentally normalizing
|
tree as composed lists; normalize/default owned interpretations rather than
|
||||||
only a range-variable copy. Preserve the retained ConfigKit tree as lists.
|
mutating those lists or recording field/container replacements in them.
|
||||||
Build indexes in bounded passes over final records rather than repeatedly
|
Build indexes in bounded passes over final records rather than repeatedly
|
||||||
searching lists by ID during execution. Keep existing inventory sorting; this
|
searching lists by ID during execution. Keep existing inventory sorting; this
|
||||||
is not a promise that every operation is linear or that list order drives runs.
|
is not a promise that every operation is linear or that list order drives runs.
|
||||||
@@ -114,6 +130,59 @@ prevalidate sources or re-resolve history. Non-string/null/missing IDs fail
|
|||||||
through the existing typed/schema/domain boundary as appropriate; there is no
|
through the existing typed/schema/domain boundary as appropriate; there is no
|
||||||
filename fallback, trimming, or new namespace constraint.
|
filename fallback, trimming, or new namespace constraint.
|
||||||
|
|
||||||
|
### Execution-Owned Interpretation And Inspection
|
||||||
|
|
||||||
|
Keep one ConfigKit load and one interpretation of its final effective records.
|
||||||
|
The production resolver captures detached `EntryInfo` presence/null information
|
||||||
|
as needed but does not mutate resource lists. Never retain the callback context.
|
||||||
|
ConfigKit's registered final identity checks continue to run normally.
|
||||||
|
|
||||||
|
Construct owned normalized resource interpretations during the existing semantic
|
||||||
|
validation boundary, and validate those values using ConfigKit's `Validation`
|
||||||
|
context for source-located errors. This can reuse the private record/document
|
||||||
|
types and existing domain helpers; it does not need a second schema, generic
|
||||||
|
cloning framework, or a new public resolver API. Retain the interpreted values
|
||||||
|
for post-load target assembly and prompt materialization so that normalization
|
||||||
|
does not run again on every request. If validation fails, no engine is published.
|
||||||
|
|
||||||
|
Only the owned interpretation may be modified. Copy the slices and nested
|
||||||
|
structures that normalization writes, or construct fresh execution values;
|
||||||
|
replacing a field through a shared nested pointer can otherwise mutate the
|
||||||
|
ConfigKit tree indirectly. Preserve exact IDs, references, and record-to-index
|
||||||
|
association while constructing this interpretation. Read presence and origins
|
||||||
|
from ConfigKit, not from guesses based on zero/nil interpreted values. Existing
|
||||||
|
provider-map and snapshot ownership rules remain in place.
|
||||||
|
|
||||||
|
Preserve current domain normalization/defaulting behavior, including endpoints,
|
||||||
|
credential names, diagnostic settings, positive-concurrency queue defaults,
|
||||||
|
profile controls, prompt metadata/input names, session templates, output schema
|
||||||
|
paths, roles, and cache control. Do not change trimming or explicit-null semantics
|
||||||
|
merely because the transformation moves. Validate normalized values without
|
||||||
|
mutating the configuration passed to `Validate`. Keep normalization failures and
|
||||||
|
domain errors at their existing public boundary with concrete list-field paths.
|
||||||
|
Moved checks may now produce validation-phase rather than resolution-phase
|
||||||
|
ConfigKit diagnostics; preserve meaningful public error identity and source
|
||||||
|
locations rather than an obsolete phase-specific expectation.
|
||||||
|
|
||||||
|
Configuration inspection, metadata, explanations, and diffs expose ConfigKit's
|
||||||
|
composed values/provenance. PromptKit's normalization/defaults appear in its
|
||||||
|
interpreted metadata and effective execution views, not as ConfigKit resolution
|
||||||
|
events. For example, inspection may retain a padded endpoint and an omitted or
|
||||||
|
null queue capacity, while the execution backend has the normalized endpoint
|
||||||
|
and the existing default capacity. Do not insert those defaults into
|
||||||
|
`Result.Config`, fabricate normalization history, or add a second public report.
|
||||||
|
Existing `InspectPrompt`, `InspectProfile`, preparation, and diagnostic results
|
||||||
|
continue exposing the interpreted information their contracts already own.
|
||||||
|
|
||||||
|
Resolve `content_file` using the unchanged ConfigKit field origin and
|
||||||
|
`SourceContext`; interpreted list positions remain associated with those paths.
|
||||||
|
Do not save a parallel history-based source resolver or record whole-list
|
||||||
|
normalization merely to pass the mutation audit. This is final-value domain
|
||||||
|
interpretation under ADR 0001, not raw-source validation or another composition
|
||||||
|
pass. Upstream field-granular mutation support remains a
|
||||||
|
[future reevaluation](future.md#field-level-normalization-with-preserved-list-provenance),
|
||||||
|
not a prerequisite for finishing this sprint on v1.0.0.
|
||||||
|
|
||||||
### Layering And Resource Context
|
### Layering And Resource Context
|
||||||
|
|
||||||
Within one strict tier, duplicate IDs fail. Across tiers, registered sequences
|
Within one strict tier, duplicate IDs fail. Across tiers, registered sequences
|
||||||
@@ -176,6 +245,8 @@ Scope: `go.mod`, `go.sum`, imports, and the existing ConfigKit adapter/facade.
|
|||||||
and resolution recording calls to `RecordNormalization`/`RecordDerivedDefault`
|
and resolution recording calls to `RecordNormalization`/`RecordDerivedDefault`
|
||||||
as used. Recorded mutations must still perform their assignments; recording
|
as used. Recorded mutations must still perform their assignments; recording
|
||||||
methods do not assign values. Typed `Secret` references remain unchanged.
|
methods do not assign values. Typed `Secret` references remain unchanged.
|
||||||
|
This is API migration guidance where recording is still used; the revised
|
||||||
|
production interpretation does not require resource-list mutation records.
|
||||||
3. Audit public inspection wrappers and their tests against the upstream release
|
3. Audit public inspection wrappers and their tests against the upstream release
|
||||||
note's complete rename table: version evidence, empty import selections,
|
note's complete rename table: version evidence, empty import selections,
|
||||||
fallback destination flags, import defaults, layer names, and history-limit
|
fallback destination flags, import defaults, layer names, and history-limit
|
||||||
@@ -251,25 +322,30 @@ validation, indexing, prompt materialization, and older fixtures still expect
|
|||||||
maps; those migrations are assigned to the following stages. Formatting and
|
maps; those migrations are assigned to the following stages. Formatting and
|
||||||
`git diff --check` passed; execution of the new fixture remains deferred.
|
`git diff --check` passed; execution of the new fixture remains deferred.
|
||||||
|
|
||||||
## Stage 4: Preserve Field Presence And Resolution At List Paths
|
## Stage 4: Preserve Field Presence And Interpretation At List Paths
|
||||||
|
|
||||||
Scope: backend/profile field capture, normalization, and defaulting in
|
Scope: backend/profile field capture, normalization, and defaulting in
|
||||||
`internal/configuration/load.go` and their focused tests.
|
`internal/configuration/load.go` and their focused tests.
|
||||||
|
|
||||||
|
Revised target: the recorded implementation below used ConfigKit resolution
|
||||||
|
mutations; Stage 11 replaces that mechanism with execution-owned interpretation.
|
||||||
|
|
||||||
1. Iterate records by index, retaining the local ID for full-ID state-map keys.
|
1. Iterate records by index, retaining the local ID for full-ID state-map keys.
|
||||||
Replace resource `.Key(id)` paths with `.Index(i)` for effective fields.
|
Replace resource `.Key(id)` paths with `.Index(i)` for effective fields.
|
||||||
2. Adapt `captureFields` and related helpers to query `EntryInfo` before defaults
|
2. Adapt `captureFields` and related helpers to query `EntryInfo` before defaults
|
||||||
and normalization. Preserve absent, null, explicit zero/false/empty, inherited,
|
and normalization. Preserve absent, null, explicit zero/false/empty, inherited,
|
||||||
and backend-completed settings using the current semantics.
|
and backend-completed settings using the current semantics.
|
||||||
3. Adapt `resolveBackends` and `resolveProfiles` to update the actual slice
|
3. Interpret backend/profile records on owned copies rather than mutating the
|
||||||
elements and record precise field mutations. Keep existing endpoint,
|
actual ConfigKit slice elements. Keep existing endpoint, credential-name,
|
||||||
credential-name, diagnostic-setting, and queue-capacity rules.
|
diagnostic-setting, and queue-capacity rules; do not record these changes
|
||||||
|
against ConfigKit list fields or entire lists.
|
||||||
4. Convert the existing focused default/presence fixtures. Update a same-ID
|
4. Convert the existing focused default/presence fixtures. Update a same-ID
|
||||||
layered fixture to whole-record upsert rather than adding a hidden merge to
|
layered fixture to whole-record upsert rather than adding a hidden merge to
|
||||||
keep its previous expectation.
|
keep its previous expectation.
|
||||||
|
|
||||||
Validation: owning tests demonstrate explicit zeros/nulls, backend completion,
|
Validation: owning tests demonstrate explicit zeros/nulls and backend completion
|
||||||
and recorded normalization at the correct list entries. No new readiness rule.
|
in execution values while composed values and source origins stay unchanged.
|
||||||
|
No new readiness rule or ConfigKit normalization-event expectation.
|
||||||
|
|
||||||
Completion: backend and profile presence capture and resolution now use list
|
Completion: backend and profile presence capture and resolution now use list
|
||||||
indexes and mutate the effective slice elements while retaining full-ID state
|
indexes and mutate the effective slice elements while retaining full-ID state
|
||||||
@@ -278,6 +354,9 @@ same-ID replacement fixtures. Their execution remains deferred: the package
|
|||||||
still does not compile until the subsequent indexing, validation, and prompt
|
still does not compile until the subsequent indexing, validation, and prompt
|
||||||
list migrations. Formatting and `git diff --check` passed.
|
list migrations. Formatting and `git diff --check` passed.
|
||||||
|
|
||||||
|
Recovery required: this completion predates the atomic-list audit finding.
|
||||||
|
The revised production target and test expectations are assigned to Stage 11.
|
||||||
|
|
||||||
## Stage 5: Validate Final Records And Build Execution Indexes
|
## Stage 5: Validate Final Records And Build Execution Indexes
|
||||||
|
|
||||||
Scope: `validateEffective`, `indexedBackends`, `indexedProfiles`, and
|
Scope: `validateEffective`, `indexedBackends`, `indexedProfiles`, and
|
||||||
@@ -287,9 +366,10 @@ Scope: `validateEffective`, `indexedBackends`, `indexedProfiles`, and
|
|||||||
full backend IDs from final records for ordinary profile-reference checks.
|
full backend IDs from final records for ordinary profile-reference checks.
|
||||||
Keep namespace/local-ID syntax, model strings, and deferred prompt/default
|
Keep namespace/local-ID syntax, model strings, and deferred prompt/default
|
||||||
readiness semantics unchanged.
|
readiness semantics unchanged.
|
||||||
2. Build backend/profile indexes using each record's ID and namespace. Update
|
2. Build backend/profile indexes from interpreted records using each record's
|
||||||
capacity-policy and execution-target assembly to use those indexes and the
|
ID and namespace, leaving `result.Config` as the composed inspection tree.
|
||||||
Stage 4 presence state. Do not inspect history or add a second ConfigKit load.
|
Update capacity-policy and execution-target assembly to use those indexes and
|
||||||
|
the Stage 4 presence state. Do not inspect history or add a second ConfigKit load.
|
||||||
3. Keep final inventories sorted and collection membership independent of list
|
3. Keep final inventories sorted and collection membership independent of list
|
||||||
position. Do not conflate local IDs in separate namespaces or resource kinds.
|
position. Do not conflate local IDs in separate namespaces or resource kinds.
|
||||||
4. Convert target-focused fixtures and retain runtime override, provider-map,
|
4. Convert target-focused fixtures and retain runtime override, provider-map,
|
||||||
@@ -306,18 +386,22 @@ duplicate fixture to identified lists. The focused tests remain deferred because
|
|||||||
prompt materialization and remaining configuration fixtures have not yet been
|
prompt materialization and remaining configuration fixtures have not yet been
|
||||||
migrated. Formatting and `git diff --check` passed.
|
migrated. Formatting and `git diff --check` passed.
|
||||||
|
|
||||||
|
Recovery required: Stage 11 switches runtime construction from raw retained
|
||||||
|
records to their owned normalized interpretation.
|
||||||
|
|
||||||
## Stage 6: Materialize Prompts From Effective List Entries
|
## Stage 6: Materialize Prompts From Effective List Entries
|
||||||
|
|
||||||
Scope: prompt resolution/capture in `internal/configuration/prompts.go` and
|
Scope: prompt interpretation/capture in `internal/configuration/prompts.go` and
|
||||||
prompt-input presence capture in `load.go`.
|
prompt-input presence capture in `load.go`.
|
||||||
|
|
||||||
1. Iterate final prompt records using their IDs for runtime keys and their list
|
1. Iterate final prompt records using their IDs for runtime keys and their list
|
||||||
indexes for metadata paths, message paths, and validation errors. Remove the
|
indexes for metadata paths, message paths, and validation errors. Remove the
|
||||||
raw prompt-label parameter from materialization; remaining internal label
|
raw prompt-label parameter from materialization; remaining internal label
|
||||||
plumbing is removed in Stage 9.
|
plumbing is removed in Stage 9.
|
||||||
2. Adapt input-description/content-type presence capture and prompt defaulting
|
2. Adapt input-description/content-type presence capture to the new paths.
|
||||||
to the new paths. Continue compiling captured message/session templates and
|
Normalize/default owned prompt interpretations, not ConfigKit list fields.
|
||||||
validating effective output contracts only.
|
Continue compiling captured message/session templates and validating
|
||||||
|
interpreted output contracts only.
|
||||||
3. Resolve file-backed fields from their contributing origin and SourceContext
|
3. Resolve file-backed fields from their contributing origin and SourceContext
|
||||||
after imports, inherited prompt definitions, upsert, and index movement.
|
after imports, inherited prompt definitions, upsert, and index movement.
|
||||||
Share the existing lazy metadata snapshot across all resources, and preserve
|
Share the existing lazy metadata snapshot across all resources, and preserve
|
||||||
@@ -338,6 +422,9 @@ loader tests still index resource maps and reference removed prompt metadata;
|
|||||||
their conversion is assigned to later work. Formatting and `git diff --check`
|
their conversion is assigned to later work. Formatting and `git diff --check`
|
||||||
passed.
|
passed.
|
||||||
|
|
||||||
|
Recovery required: Stage 12 moves remaining prompt normalization off ConfigKit
|
||||||
|
state and verifies resource origins after that change.
|
||||||
|
|
||||||
## Stage 7: Preserve Inspection And Sensitive-Value Handling
|
## Stage 7: Preserve Inspection And Sensitive-Value Handling
|
||||||
|
|
||||||
Scope: `internal/configuration/inspection.go`, configuration inspection/diff
|
Scope: `internal/configuration/inspection.go`, configuration inspection/diff
|
||||||
@@ -347,8 +434,8 @@ facade tests, and path-specific metadata expectations.
|
|||||||
list indexes, retaining the existing sensitive key policy and nested values.
|
list indexes, retaining the existing sensitive key policy and nested values.
|
||||||
Use ConfigKit v1's `Sensitive` hook and schema tags where already applicable.
|
Use ConfigKit v1's `Sensitive` hook and schema tags where already applicable.
|
||||||
2. Convert inspection queries and fixtures from resource-key paths to concrete
|
2. Convert inspection queries and fixtures from resource-key paths to concrete
|
||||||
index paths. Retained effective output stays in list shape; runtime IDs are
|
index paths. Retained output stays in composed list shape without PromptKit
|
||||||
not synthetic inspection mapping keys.
|
normalization/default writes; runtime IDs are not synthetic inspection keys.
|
||||||
3. Preserve redaction in effective output, explanations, failure diagnostics,
|
3. Preserve redaction in effective output, explanations, failure diagnostics,
|
||||||
metadata, and diffs through existing owning coverage. Include a replaced or
|
metadata, and diffs through existing owning coverage. Include a replaced or
|
||||||
inherited sensitive record at a different index where it adds protection.
|
inherited sensitive record at a different index where it adds protection.
|
||||||
@@ -367,6 +454,9 @@ passed: `go test . -run '^TestConfigurationInspection' -count=1` with Go 1.27.0,
|
|||||||
formatting, and `git diff --check`. Internal package tests remain deferred until
|
formatting, and `git diff --check`. Internal package tests remain deferred until
|
||||||
the remaining map-indexed loader fixtures are converted.
|
the remaining map-indexed loader fixtures are converted.
|
||||||
|
|
||||||
|
Recovery required: Stage 12 reconciles inspection expectations with composed
|
||||||
|
configuration versus interpreted execution values. Preserve the redaction work.
|
||||||
|
|
||||||
## Stage 8: Convert Public Source Builders To Explicit-ID Slices
|
## Stage 8: Convert Public Source Builders To Explicit-ID Slices
|
||||||
|
|
||||||
Scope: `profiles.go`, `backends.go`, source-builder GoDoc, and owning construction
|
Scope: `profiles.go`, `backends.go`, source-builder GoDoc, and owning construction
|
||||||
@@ -445,7 +535,77 @@ asserting the removed field is absent from representative values. The isolated
|
|||||||
JSON contract suite passed on Go 1.27.0, as did formatting and `git diff --check`.
|
JSON contract suite passed on Go 1.27.0, as did formatting and `git diff --check`.
|
||||||
Remaining callers and the maintained example are assigned to later work.
|
Remaining callers and the maintained example are assigned to later work.
|
||||||
|
|
||||||
## Stage 11: Verify Identified Composition And Inheritance
|
## Stage 11: Recover Backend And Profile Interpretation Without List Mutation
|
||||||
|
|
||||||
|
Scope: the production definition/resolver/validator in
|
||||||
|
`internal/configuration/load.go`, target assembly in `targets.go`, and the
|
||||||
|
focused normalization/presence tests. This is the first resumption assignment.
|
||||||
|
|
||||||
|
1. Preserve the existing in-progress definition extraction and integration tests.
|
||||||
|
Remove production resolver calls that mutate resource lists, including the
|
||||||
|
prompt-list call that Stage 12 replaces. Retain the six identity registrations
|
||||||
|
and read-only presence capture; do not add covering whole-list records.
|
||||||
|
2. Build owned backend/profile interpretations from the final typed records at
|
||||||
|
the semantic validation boundary. Reuse the private typed structures and
|
||||||
|
domain normalization helpers. Keep each record's original index/path and
|
||||||
|
exact ID, and detach nested state that interpretation modifies. Report
|
||||||
|
normalization failures through the validation context using those paths.
|
||||||
|
3. Preserve backend endpoints, credential-name handling, diagnostic endpoint/kind
|
||||||
|
normalization, queue defaults, profile controls, and absent/null/explicit
|
||||||
|
values. Keep `EntryInfo` capture separate from the interpreted defaults.
|
||||||
|
Validate owned values without modifying the supplied ConfigKit configuration.
|
||||||
|
4. Retain the interpreted values for runtime backend/profile/capacity assembly;
|
||||||
|
stop those paths from assuming `result.Config` has been normalized. Do not
|
||||||
|
mutate `Result.Config` after success or rebuild definitions on ordinary runs.
|
||||||
|
5. Update the existing backend-normalization/null-default test to check two
|
||||||
|
outcomes: normalized/defaulted execution values and unchanged composed
|
||||||
|
values with original field provenance. Remove its expectation of a ConfigKit
|
||||||
|
`ChangeNormalization` event for PromptKit's transformation. Retain tests for
|
||||||
|
explicit zero/false/null and the existing public configuration-error boundary.
|
||||||
|
|
||||||
|
Validation: targeted real-loader cases with a padded endpoint and positive
|
||||||
|
concurrency plus omitted/null queue capacity load on the selected v1.0.0 without
|
||||||
|
an unrecorded-change error. Their execution values keep current behavior, while
|
||||||
|
inspection does not acquire synthesized whole-list origins/defaults. Record
|
||||||
|
unrelated old-fixture failures for their assigned stages rather than restoring
|
||||||
|
mutating resolution to satisfy them.
|
||||||
|
|
||||||
|
## Stage 12: Recover Prompt Interpretation And Preserve Inspection Origins
|
||||||
|
|
||||||
|
Scope: prompt interpretation/materialization in `load.go`/`prompts.go` and the
|
||||||
|
owning prompt/inspection tests, completing Stage 11's production recovery.
|
||||||
|
|
||||||
|
1. Move prompt description/session, input-name/content-type/description, and
|
||||||
|
output-schema-path normalization into owned interpreted records. Reuse the
|
||||||
|
Stage 11 ownership pattern and existing message role/cache-control handling.
|
||||||
|
Clone nested output/input structures that are modified; do not trim IDs or
|
||||||
|
stored resource references. Validate interpreted names/settings so normalization
|
||||||
|
cannot conceal a duplicate input name or invalid output contract.
|
||||||
|
2. Materialize prompts from interpreted records while using the unchanged
|
||||||
|
ConfigKit effective field paths, origins, and `SourceContext` for file reads.
|
||||||
|
Preserve one lazy metadata snapshot across root/collection resources, content
|
||||||
|
capture/closure, and existing prompt hash and requirement metadata behavior.
|
||||||
|
3. Extend an existing imported/inherited-content case with prompt metadata that
|
||||||
|
actually needs trimming, including a resource from another directory and a
|
||||||
|
replaced/moved record as appropriate. Verify the correct file is read and the
|
||||||
|
field retains its contributing source even when other fields normalize.
|
||||||
|
4. Reconcile inspection/diff tests with the agreed views: ConfigKit composed
|
||||||
|
values/provenance versus PromptKit-normalized metadata and execution settings.
|
||||||
|
Verify that normalizing the owned interpretation leaves the retained values
|
||||||
|
and origins unchanged, including nested structures. Keep redaction coverage
|
||||||
|
and upstream composition/inheritance history; do not manufacture records for
|
||||||
|
PromptKit transformations or duplicate the full test matrix.
|
||||||
|
5. Search production resource interpretation for leftover `Normalize`, `Default`,
|
||||||
|
or `RecordNormalization` calls writing ConfigKit list fields. Remove the
|
||||||
|
obsolete mutation-only helpers where unused. Deliberate recorded whole-list
|
||||||
|
mutations in upstream-registration tests are separate and remain legitimate.
|
||||||
|
|
||||||
|
Validation: the source-origin regression and focused normalized metadata,
|
||||||
|
inspection, and redaction tests pass without whole-list normalization. Complete
|
||||||
|
the backend/profile/prompt recovery before continuing the existing integration
|
||||||
|
work. No upstream release, extra public API, or provenance repair layer is needed.
|
||||||
|
|
||||||
|
## Stage 13: Verify Identified Composition And Inheritance
|
||||||
|
|
||||||
Scope: `internal/configuration/load_test.go`, `targets_test.go`, and focused
|
Scope: `internal/configuration/load_test.go`, `targets_test.go`, and focused
|
||||||
configuration fixtures not yet converted.
|
configuration fixtures not yet converted.
|
||||||
@@ -470,7 +630,7 @@ configuration fixtures not yet converted.
|
|||||||
Validation: real-loader tests assert effective behavior and structured diagnostic
|
Validation: real-loader tests assert effective behavior and structured diagnostic
|
||||||
identity/paths as appropriate, not complete upstream error wording or ordering.
|
identity/paths as appropriate, not complete upstream error wording or ordering.
|
||||||
|
|
||||||
## Stage 12: Complete Header, Origin, And Adapter Fixture Coverage
|
## Stage 14: Complete Header, Origin, And Adapter Fixture Coverage
|
||||||
|
|
||||||
Scope: remaining `internal/configuration` prompt, inspection, listing, and
|
Scope: remaining `internal/configuration` prompt, inspection, listing, and
|
||||||
source-context tests and `internal/engine` configuration fixtures.
|
source-context tests and `internal/engine` configuration fixtures.
|
||||||
@@ -485,12 +645,13 @@ source-context tests and `internal/engine` configuration fixtures.
|
|||||||
existing schema's allowed/rejected shapes; do not create a new application
|
existing schema's allowed/rejected shapes; do not create a new application
|
||||||
field just to demonstrate upstream control extraction.
|
field just to demonstrate upstream control extraction.
|
||||||
4. Close any missing source-origin or sensitive-path cases identified in
|
4. Close any missing source-origin or sensitive-path cases identified in
|
||||||
Stages 6–7. Reuse those owning tests instead of repeating their matrix here.
|
Stages 6–7 and their recovery in Stages 11–12. Reuse those owning tests instead
|
||||||
|
of repeating their matrix here.
|
||||||
|
|
||||||
Validation: run the configuration and internal-engine packages together when
|
Validation: run the configuration and internal-engine packages together when
|
||||||
they compile. Correct production defects before adjusting meaningful assertions.
|
they compile. Correct production defects before adjusting meaningful assertions.
|
||||||
|
|
||||||
## Stage 13: Migrate Public Configuration, Inventory, And Scope Tests
|
## Stage 15: Migrate Public Configuration, Inventory, And Scope Tests
|
||||||
|
|
||||||
Scope: root construction, sources, inspection/diff, inheritance, profile
|
Scope: root construction, sources, inspection/diff, inheritance, profile
|
||||||
inspection, listing, and namespace contract tests.
|
inspection, listing, and namespace contract tests.
|
||||||
@@ -510,7 +671,7 @@ inspection, listing, and namespace contract tests.
|
|||||||
Validation: run the affected external-package contract tests using real ConfigKit
|
Validation: run the affected external-package contract tests using real ConfigKit
|
||||||
composition and offline sources. Do not add index/list-position guarantees.
|
composition and offline sources. Do not add index/list-position guarantees.
|
||||||
|
|
||||||
## Stage 14: Migrate Internal Execution And Rendering Fixtures
|
## Stage 16: Migrate Internal Execution And Rendering Fixtures
|
||||||
|
|
||||||
Scope: remaining `internal/usecase`, `internal/prompt`, `internal/domain`, and
|
Scope: remaining `internal/usecase`, `internal/prompt`, `internal/domain`, and
|
||||||
internal observation fixtures affected by resource lists or removed labels.
|
internal observation fixtures affected by resource lists or removed labels.
|
||||||
@@ -529,7 +690,7 @@ internal observation fixtures affected by resource lists or removed labels.
|
|||||||
Validation: run the affected internal packages with final values and synthetic
|
Validation: run the affected internal packages with final values and synthetic
|
||||||
sources. Resolve remaining label-related compilation errors in these packages.
|
sources. Resolve remaining label-related compilation errors in these packages.
|
||||||
|
|
||||||
## Stage 15: Migrate Public Preparation And Execution Contracts
|
## Stage 17: Migrate Public Preparation And Execution Contracts
|
||||||
|
|
||||||
Scope: root ordinary/prepared execution, concrete-request validation,
|
Scope: root ordinary/prepared execution, concrete-request validation,
|
||||||
requirements, and capacity contract fixtures.
|
requirements, and capacity contract fixtures.
|
||||||
@@ -548,7 +709,7 @@ requirements, and capacity contract fixtures.
|
|||||||
Validation: run the focused root preparation/execution/requirements tests using
|
Validation: run the focused root preparation/execution/requirements tests using
|
||||||
existing injected clients or controlled HTTP transports, with no live provider.
|
existing injected clients or controlled HTTP transports, with no live provider.
|
||||||
|
|
||||||
## Stage 16: Migrate Public Diagnostics And Observation Contracts
|
## Stage 18: Migrate Public Diagnostics And Observation Contracts
|
||||||
|
|
||||||
Scope: root smoke diagnostic, observation, prepared-observation, and adapter
|
Scope: root smoke diagnostic, observation, prepared-observation, and adapter
|
||||||
boundary fixtures not completed by Stage 10's serialization changes.
|
boundary fixtures not completed by Stage 10's serialization changes.
|
||||||
@@ -565,7 +726,7 @@ boundary fixtures not completed by Stage 10's serialization changes.
|
|||||||
Validation: run these public contract tests offline; diagnostic operations in
|
Validation: run these public contract tests offline; diagnostic operations in
|
||||||
tests use controlled transports, not actual backend endpoints or API keys.
|
tests use controlled transports, not actual backend endpoints or API keys.
|
||||||
|
|
||||||
## Stage 17: Update Maintained Examples And Benchmarks
|
## Stage 19: Update Maintained Examples And Benchmarks
|
||||||
|
|
||||||
Scope: the three `examples/go-library` workflows, their assets, and configuration-
|
Scope: the three `examples/go-library` workflows, their assets, and configuration-
|
||||||
dependent benchmarks and shared test helpers still using the old representation.
|
dependent benchmarks and shared test helpers still using the old representation.
|
||||||
@@ -587,7 +748,7 @@ Validation: run all three examples through the semantic checker once runnable.
|
|||||||
Use a short focused construction benchmark if needed to investigate a suspected
|
Use a short focused construction benchmark if needed to investigate a suspected
|
||||||
repeated-scan regression, not to claim unmeasured performance improvements.
|
repeated-scan regression, not to claim unmeasured performance improvements.
|
||||||
|
|
||||||
## Stage 18: Document Formats And Internal Handoff
|
## Stage 20: Document Formats And Internal Handoff
|
||||||
|
|
||||||
Scope: `docs/formats.md`, `docs/internal/sources.md`, and other current internal
|
Scope: `docs/formats.md`, `docs/internal/sources.md`, and other current internal
|
||||||
documents whose descriptions changed.
|
documents whose descriptions changed.
|
||||||
@@ -600,14 +761,17 @@ documents whose descriptions changed.
|
|||||||
ConfigKit v1 for generic import/control/collection semantics rather than
|
ConfigKit v1 for generic import/control/collection semantics rather than
|
||||||
copying its full reference or imposing additional authoring restrictions.
|
copying its full reference or imposing additional authoring restrictions.
|
||||||
3. Explain final index-based presence/resource-context interpretation, captured
|
3. Explain final index-based presence/resource-context interpretation, captured
|
||||||
runtime indexes, sensitivity, and operator-only inspection. Update current
|
runtime indexes, sensitivity, and operator-only inspection. Explain that
|
||||||
upstream references and obsolete mapping examples without rewriting accepted
|
ConfigKit's composed values retain provenance while owned interpretations
|
||||||
ADR decision content or historical release notes.
|
carry PromptKit normalization/defaults; no leaf-level ConfigKit mutation or
|
||||||
|
synthetic whole-list history is required. Update current upstream references
|
||||||
|
and obsolete mapping examples without rewriting accepted ADR decision content
|
||||||
|
or historical release notes.
|
||||||
|
|
||||||
Validation: compare every current format example with the actual implemented
|
Validation: compare every current format example with the actual implemented
|
||||||
schema and owning tests. Exact Go declarations remain the API contract owner.
|
schema and owning tests. Exact Go declarations remain the API contract owner.
|
||||||
|
|
||||||
## Stage 19: Document One Coherent Consumer Migration
|
## Stage 21: Document One Coherent Consumer Migration
|
||||||
|
|
||||||
Scope: `docs/consumers/configuration-migration.md`, the Go consumer guide, README,
|
Scope: `docs/consumers/configuration-migration.md`, the Go consumer guide, README,
|
||||||
remaining exported GoDoc, and toolchain/release preparation guidance.
|
remaining exported GoDoc, and toolchain/release preparation guidance.
|
||||||
@@ -620,6 +784,9 @@ remaining exported GoDoc, and toolchain/release preparation guidance.
|
|||||||
minimum, actual root controls, optional imports/`required: true`, header 2,
|
minimum, actual root controls, optional imports/`required: true`, header 2,
|
||||||
removed prompt labels/JSON fields, changed inspection paths, and opaque hash
|
removed prompt labels/JSON fields, changed inspection paths, and opaque hash
|
||||||
changes. Include the standalone-item header-versus-former-label distinction.
|
changes. Include the standalone-item header-versus-former-label distinction.
|
||||||
|
Explain that configuration inspection/diffs now retain composed values rather
|
||||||
|
than PromptKit-normalized/defaulted ones; the existing interpreted views serve
|
||||||
|
execution-setting inspection, with no new combined report or equality promise.
|
||||||
3. Update the current consumer/README examples and links to maintained artifacts.
|
3. Update the current consumer/README examples and links to maintained artifacts.
|
||||||
Align toolchain/build guidance with the new minimum and the existing selected-
|
Align toolchain/build guidance with the new minimum and the existing selected-
|
||||||
toolchain release procedure; do not introduce a separate release-tool upgrade,
|
toolchain release procedure; do not introduce a separate release-tool upgrade,
|
||||||
@@ -633,7 +800,7 @@ Validation: render/read affected GoDoc; check local document links and snippets
|
|||||||
against implemented APIs. Keep current documentation free of obsolete contracts;
|
against implemented APIs. Keep current documentation free of obsolete contracts;
|
||||||
old syntax may remain explicitly labeled in migration explanations and history.
|
old syntax may remain explicitly labeled in migration explanations and history.
|
||||||
|
|
||||||
## Stage 20: Verify The Integrated Sprint And Record Completion
|
## Stage 22: Verify The Integrated Sprint And Record Completion
|
||||||
|
|
||||||
Scope: acceptance review and residual corrections, not another feature stage.
|
Scope: acceptance review and residual corrections, not another feature stage.
|
||||||
|
|
||||||
@@ -641,7 +808,9 @@ Scope: acceptance review and residual corrections, not another feature stage.
|
|||||||
proportionate existing tests: new dependency/types, source controls/header,
|
proportionate existing tests: new dependency/types, source controls/header,
|
||||||
all six identity rules, builder order/duplicates, inheritance/upsert, effective
|
all six identity rules, builder order/duplicates, inheritance/upsert, effective
|
||||||
field paths, file origins, sensitivity, removed labels, and preserved runtime
|
field paths, file origins, sensitivity, removed labels, and preserved runtime
|
||||||
operations. Close actual gaps at their owning boundary.
|
operations. Include the recovery distinction: normalized execution values
|
||||||
|
are valid without mutating ConfigKit's composed tree or its provenance.
|
||||||
|
Close actual gaps at their owning boundary.
|
||||||
2. Search current production code, tests, examples, module metadata, and current
|
2. Search current production code, tests, examples, module metadata, and current
|
||||||
docs for stale old-path imports, genuine old controls, prompt labels, keyed
|
docs for stale old-path imports, genuine old controls, prompt labels, keyed
|
||||||
resource fixtures, and version-1 headers. Classify intended migration examples,
|
resource fixtures, and version-1 headers. Classify intended migration examples,
|
||||||
@@ -677,4 +846,6 @@ diff establish sprint completion; intermediate checks alone do not.
|
|||||||
None required to begin the sprint. The accepted roadmap settles module identity,
|
None required to begin the sprint. The accepted roadmap settles module identity,
|
||||||
resource representation, layering/inheritance, source-builder inputs, header
|
resource representation, layering/inheritance, source-builder inputs, header
|
||||||
policy, removed labels, and the coordinated breaking upgrade. Implementation
|
policy, removed labels, and the coordinated breaking upgrade. Implementation
|
||||||
details above serve those decisions without adding consumer guarantees.
|
details above serve those decisions without adding consumer guarantees. The
|
||||||
|
approved execution-owned interpretation accommodates ConfigKit v1.0.0's atomic
|
||||||
|
sequence audit; upstream field-granular normalization is not an open dependency.
|
||||||
|
|||||||
Reference in New Issue
Block a user