Add mounted collection consumer examples

This commit is contained in:
2026-10-14 13:59:37 +00:00
parent 53601e68ed
commit 2d8df22dd1
13 changed files with 348 additions and 5 deletions

View File

@@ -17,6 +17,7 @@ sanitized shapes using only ConfigKit and the Go standard library:
| Seriatim-like | Independent strict ordered speaker and autocorrect rule files | First-match and ordered replacement algorithms; no central application configuration file |
| Bundled file | Simple native `fs.FS` source through ordinary `Load` | Selection and lifetime of the application-owned embedded filesystem |
| Layered catalog | Embedded defaults with an import, a mapping underlay, an independent host main file, explicit false/zero input, and source-relative resource access | Domain validation and opening/interpreting the template resource |
| Mounted collections | Literal input destinations, peer prompt/profile fragments, local inheritance, imported collection metadata, and a version-only higher-tier override | Collection IDs, profile meaning, and opening/interpreting prompt resources |
| Named presets | One-load sibling inheritance, explicit false, nested destination resolution, and source/derivation inspection | Choosing and executing a preset |
| Effective configuration diff | Same-type frozen effective comparisons for two selected files or base-versus-overlay impact | Source/options selection and consumer-owned safe presentation |
@@ -108,6 +109,32 @@ and may fail independently of the completed configuration load. The
[configuration contract](../config.md#source-resource-contexts) owns exact
lifetime and precedence rules.
## Input destinations and mounted collections
The small [`Example_inputDestination`](../../examples/consumers/destinations_test.go)
mounts one mapping source beneath literal collection/prompt keys and loads a
second input without a destination to show that root placement remains the
default. Consumers pass paths, not filenames or namespace strings for ConfigKit
to interpret.
[`LoadCollectionBundle`](../../examples/consumers/destinations.go) assembles an
embedded collection manifest with a source-root import, separate prompt and
profile peers, and a higher-priority input that changes only one prompt's
ordinary `version` field. The main document alone supplies the application
schema version. A prompt's local `extends` relationship resolves after all
tiers, so `custom` inherits the final `brief` content and fields while retaining
its own profile selection.
The resolver follows each effective `content_file` origin to its declaring
source context. This also works for `custom`'s inherited resource. The
application-owned [`ReadCollectionPromptContent`](../../examples/consumers/destinations.go)
demonstrates the same lookup after loading; ConfigKit does not open or interpret
the resource. [`destinations_test.go`](../../examples/consumers/destinations_test.go)
checks source destinations and authored coordinates, presence, inherited values,
relative resources, and strict peer conflicts. The
[configuration contract](../config.md#input-destinations) owns shared placement,
import, source-location, and ownership behavior.
Known module catalogs should use canonical object entries with a module identifier
and typed options. A small union struct is sufficient when the available option
fields are known; validation selects which fields apply to each module. Runtime-
@@ -187,6 +214,7 @@ focused behavioral owner:
| Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
| `LoadSecretsDir`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
| Native filesystem, grouped underlays, programmatic mapping, retained resource context | `Example_nativeFilesystem`, `Example_layeredCatalog`, and their focused consumer tests |
| Literal input destinations, root-default compatibility, and mounted peer collections | `Example_inputDestination`, `LoadCollectionBundle`, and `destinations_test.go` |
| Named sibling inheritance, presence, and derivation | `Example_inheritedPresets` and `TestPresetCatalogOneLoadAndDerivation` |
| Effective configuration diffs and consumer-owned presentation | `ExampleDiff`, `ExampleCompareFiles`, and `ExampleCompareRolloutOverlay` |
| Results, metadata, diagnostics, effective output, and writer failures | Focused root-package load, provenance, rendering, and explanation tests |

View File

@@ -465,7 +465,7 @@ supported ConfigKit import path.
## Stage 11 — Add maintained simple and collection-style consumer examples
Status: planned. Scope: executable adoption examples with consumer-owned types.
Status: complete. Scope: executable adoption examples with consumer-owned types.
1. Add a minimal mounted-fragment example using `Input.Destination` in an
ordinary layered load. Show literal keys and root-default compatibility
@@ -483,9 +483,24 @@ Status: planned. Scope: executable adoption examples with consumer-owned types.
from the consumer guide; add a small executable root example if useful for
discovery without duplicating the complete scenario.
Validate: `go test ./examples/consumers`, applicable `Example` tests, local links,
and everyday check. Done: simple and representative consumers substantiate the
same configuration model and need no compensating structural pass.
Validated with `go test ./examples/consumers -count=1`,
`go test . -run '^Example' -count=1`, and `./scripts/check.sh` (go1.26.8
linux/amd64); all passed, including local documentation links.
`Example_inputDestination` demonstrates a literal mounted mapping path and an
ordinary root input without consumer-side parsing or merging.
`LoadCollectionBundle` and `TestCollectionBundleAssemblesMountedPeersAndResources`
exercise prompt/profile peer sources, imported collection metadata with an
ordinary version label, main-owned schema-version checking, local sibling
inheritance, and a higher-tier prompt version-only change that retains the rest
of its body. The resolver and `ReadCollectionPromptContent` follow direct and
inherited `content_file` provenance to the declaring native-filesystem context.
The test checks final values, explicit presence, source destinations and authored
coordinates, relative resources, and the inherited field's origin.
`TestCollectionPeerPromptConflictsRemainStrict` preserves expected conflict
behavior. The examples are linked from the consumer adoption guide. Done: simple
and representative consumers substantiate the same model without a compensating
structural pass.
## Stage 12 — Reconcile documentation and audit the complete implementation