Clarify source selector clearing behavior
This commit is contained in:
@@ -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
|
||||||
|
|||||||
@@ -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 ./...`
|
||||||
|
|||||||
Reference in New Issue
Block a user