Clarify source selector clearing behavior

This commit is contained in:
2026-11-18 00:29:33 +00:00
parent 65bd2da51a
commit 932fd6da25
2 changed files with 34 additions and 10 deletions

View File

@@ -59,7 +59,7 @@ promptkit_sources:
schema_dir: ./examples/schemas schema_dir: ./examples/schemas
``` ```
Omitting the field or setting it to `[]` (or `null`) selects no An empty or null final resolved `promptkit_sources` list selects no
application-supplied framework sources; Promptkit's selected catalog and application-supplied framework sources; Promptkit's selected catalog and
maintained definitions still apply. A later sequence item overlays an earlier maintained definitions still apply. A later sequence item overlays an earlier
one. Files within a selected directory are composed together, so conflicting one. Files within a selected directory are composed together, so conflicting
@@ -96,6 +96,16 @@ precedence boundaries. The [collection example](../examples/config.collections.y
declares `file` identity with `upsert`, combines imported file selectors, and declares `file` identity with `upsert`, combines imported file selectors, and
lets an overlay add another. CLI list overrides still replace the whole list. lets an overlay add another. CLI list overrides still replace the whole list.
At application precedence boundaries, omission preserves lower-precedence
selectors. Under ordinary list replacement, `[]` clears the selection and
`null` resolves to no selectors. Under authored `append` or `upsert`, `[]`
contributes no records and `null` is invalid. To clear a collection with an
inherited policy, declare `mode: replace` at
`destination: [promptkit_sources]` in the higher-precedence source and supply
`promptkit_sources: []`. See
[ConfigKit's collection policy contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#yaml-declarations-and-policy-lifetime)
for policy lifetime and combination rules.
These application root `config` controls do not change the separate These application root `config` controls do not change the separate
Promptkit v0.12.0 framework format: its selected framework files use the Promptkit v0.12.0 framework format: its selected framework files use the
[Promptkit contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) [Promptkit contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
@@ -105,11 +115,13 @@ and its older ConfigKit controls.
root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty
and exact lowercase `default` select no overlay. There is no fallback, and exact lowercase `default` select no overlay. There is no fallback,
case folding, inherited stack, or automatic selection; a missing selected case folding, inherited stack, or automatic selection; a missing selected
overlay fails. Mappings merge and explicit nulls replace; sequence behavior overlay fails. Mappings merge; sequence contributions and nulls at collection
depends on any authored collection policy. Defaults-only loading can enable destinations follow the effective collection policy described above. Other
imports, but an absent main has no import declarations. This CLI supplies no explicit nulls replace lower values subject to the application schema.
independent overlay root, so an active overlay cannot be located without a Defaults-only loading can enable imports, but an absent main has no import
selected main context. That is not a general ConfigKit restriction. declarations. This CLI supplies no independent overlay root, so an active
overlay cannot be located without a selected main context. That is not a general
ConfigKit restriction.
The [composed example](../examples/config.composed.yml) imports the application The [composed example](../examples/config.composed.yml) imports the application
[source-selection fragment](../examples/config-fragments/sources.yml) and has [source-selection fragment](../examples/config-fragments/sources.yml) and has

View File

@@ -15,7 +15,8 @@ validation. PromptKit v0.12.0 retains old-path ConfigKit v0.5.0 for framework
sources and captured inspection. Each generation's paths, diagnostics, and sources and captured inspection. Each generation's paths, diagnostics, and
writers remain separate; the shared YAML dependency stays at v4.0.0-rc.6. writers remain separate; the shared YAML dependency stays at v4.0.0-rc.6.
No runtime correctness defect, unnecessary compatibility layer, or unrequested No runtime correctness defect, unnecessary compatibility layer, or unrequested
runtime restriction was found. One documentation contract overstatement remains. runtime restriction was found. One documentation contract overstatement was
identified; its remediation is complete below.
| Stage | Review result | | Stage | Review result |
| --- | --- | | --- | --- |
@@ -24,12 +25,12 @@ runtime restriction was found. One documentation contract overstatement remains.
| 3: Adapter type separation | Application and framework values use their respective public types; structured errors and warnings reach the matching native writer. | | 3: Adapter type separation | Application and framework values use their respective public types; structured errors and warnings reach the matching native writer. |
| 4: Configuration coverage | Tests cover discovery, optional/required imports, placement, authored collections, CLI timing, presence, normalization, and inspection without new application identity rules. | | 4: Configuration coverage | Tests cover discovery, optional/required imports, placement, authored collections, CLI timing, presence, normalization, and inspection without new application identity rules. |
| 5: Integration and examples | New application controls coexist with old framework controls; ordinary, composed, inheritance, and collection examples work, including overlay retention. | | 5: Integration and examples | New application controls coexist with old framework controls; ordinary, composed, inheritance, and collection examples work, including overlay retention. |
| 6: Documentation and attribution | Dependency/toolchain ownership and both notices are aligned; selector-clearing language still overstates the native contract (R6). | | 6: Documentation and attribution | Dependency/toolchain ownership and both notices are aligned; selector-clearing wording is now corrected (R6). |
| 7: End-state validation | Independent tests, builds, example commands, dependency checks, and document checks passed; R6 must be resolved for complete documentation alignment. | | 7: End-state validation | Independent tests, builds, example commands, dependency checks, and document checks passed; R6's documentation alignment is now complete. |
### R6: Qualify Selector Clearing By The Effective Collection Policy ### R6: Qualify Selector Clearing By The Effective Collection Policy
Priority: P3 (low). Status: Open. Priority: P3 (low). Status: Complete.
Locations: `docs/config.md:62–64` and `docs/config.md:108–109`. Locations: `docs/config.md:62–64` and `docs/config.md:108–109`.
@@ -76,6 +77,17 @@ Acceptance: the selector and overlay descriptions agree with the pinned native
contract and the reproduced empty/null cases. Check the affected links and any contract and the reproduced empty/null cases. Check the affected links and any
added example. No production-code change or new runtime guarantee is required. added example. No production-code change or new runtime guarantee is required.
Resolution (2026-11-18): the configuration reference now distinguishes the final
resolved selector list from individual source contributions. It explains
omission, empty lists, nulls, and explicit replacement under the effective
collection policy, qualifies overlay null handling, and links to the pinned
upstream policy-lifetime contract. Runtime behavior and CLI whole-list overrides
are unchanged. All 15 temporary selector-policy checks passed against a fresh
build: omitted/empty/null/explicit-replace overlays under ordinary replacement,
append, and upsert, plus CLI whole-list replacement and no-generation rendering
under each policy. The pinned document and anchor and diff whitespace were
checked. No provider was contacted; no production code or tests changed.
### Independent Review Verification ### Independent Review Verification
- `go test -count=1 ./...`, `go test -race -count=1 ./...`, and `go vet ./...` - `go test -count=1 ./...`, `go test -race -count=1 ./...`, and `go vet ./...`