Plan typed result access and focused inspection
This commit is contained in:
336
docs/roadmap/implementation.md
Normal file
336
docs/roadmap/implementation.md
Normal file
@@ -0,0 +1,336 @@
|
|||||||
|
# Implementation plan: typed result values and focused inspection
|
||||||
|
|
||||||
|
Status: ready for implementation; no stages implemented by this document.
|
||||||
|
|
||||||
|
## Scope and working instructions
|
||||||
|
|
||||||
|
Implement the agreed end state in [result-value.md](result-value.md), including
|
||||||
|
settled OD-1 through OD-5 and accepted [ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md).
|
||||||
|
The runtime baseline is v1.3.0 (`652ddb6`); subsequent documentation commits
|
||||||
|
settle the API and comparison choices. Inspect the current checkout before editing.
|
||||||
|
The broader [consumer request](promptkit-resolved-configuration-request.md) is
|
||||||
|
background, not additional acceptance criteria: independent source-version
|
||||||
|
policies and isolation of sibling evidence are outside this feature.
|
||||||
|
|
||||||
|
Audience: a Luna coding agent implementing stages sequentially in one end-to-end
|
||||||
|
sprint. Intermediate stages may leave compilation temporarily incomplete; do not
|
||||||
|
add temporary public bridges or duplicate implementations to keep them green.
|
||||||
|
Private helper names and file boundaries below are implementation suggestions;
|
||||||
|
public signatures and the roadmap's behavior are selected decisions.
|
||||||
|
|
||||||
|
Start with [development guidance](../development.md), [agent policy](../policy/agents.md),
|
||||||
|
[architecture policy](../policy/architecture.md), [testing policy](../policy/testing.md),
|
||||||
|
and [documentation policy](../policy/documentation.md). Preserve unrelated work.
|
||||||
|
Use focused behavioral checks as each part becomes runnable, then perform the
|
||||||
|
final checks once the complete feature is in place. Commit completed nonempty
|
||||||
|
units according to agent policy; do not publish a release or modify dependencies.
|
||||||
|
|
||||||
|
## Implementation boundaries
|
||||||
|
|
||||||
|
- Root `configkit` owns exported declarations and explicit conversions. Engine
|
||||||
|
helpers remain private to consumers. Keep root-to-engine dependency direction
|
||||||
|
and avoid exported aliases or anonymous internal embedding.
|
||||||
|
- `Value` reads current `Config`; inspection borrows the existing frozen load
|
||||||
|
state. Neither capability loads again, projects a new execution snapshot,
|
||||||
|
runs codecs or callbacks, reads resources, or resolves secrets.
|
||||||
|
- Preserve existing `Result` methods and generic `Diff[T]`. The new non-generic
|
||||||
|
view compares frozen snapshots structurally across root Go types, as ADR 0024
|
||||||
|
explicitly permits. No runtime root-type tracking is needed.
|
||||||
|
- Reuse descriptor field bindings, path parsing/index rules, history inventories,
|
||||||
|
snapshot redaction, and the existing comparison algorithm. No new global
|
||||||
|
caches, registry, synchronization, conversion framework, or load-time snapshot
|
||||||
|
is needed. Do not impose new limits or validation on returned terminal values.
|
||||||
|
- Ordinary Go assignment governs ownership. Maps, slices, and pointers may alias
|
||||||
|
`Config`; neither deep copying nor concurrent mutation safety is promised.
|
||||||
|
Typed value availability is independent of YAML presence and load evidence.
|
||||||
|
- Reporting scope is a canonical JSON Pointer location. Explicit typed lookup,
|
||||||
|
explanation, and metadata queries retain their existing semantic path intent.
|
||||||
|
|
||||||
|
## Stage 1 — Implement private current-value navigation
|
||||||
|
|
||||||
|
Read `internal/engine/schema.go`, `schema_fields.go`, `value_operation.go`,
|
||||||
|
`decode.go`, and semantic paths before adding a small engine helper, for example
|
||||||
|
in `internal/engine/result_value.go`. Accept the current Go root, an engine Path,
|
||||||
|
and the existing root-supplied Secret binding; return `(any, bool)`.
|
||||||
|
|
||||||
|
1. Reject invalid paths. For a reached terminal, return its actual Go value before
|
||||||
|
dereferencing pointers or attempting structural validation. The root selects
|
||||||
|
the entire current configuration. Nil interfaces return `(nil, true)`;
|
||||||
|
typed nil pointers/maps/slices retain their typed nil value in `any` with
|
||||||
|
`true`, as ordinary Go assignment requires. Unsupported terminal values are
|
||||||
|
still returned without conversion or revalidation.
|
||||||
|
2. For continued navigation, follow non-nil pointers/interfaces and describe the
|
||||||
|
containing type using existing operation-local schema machinery. Reuse
|
||||||
|
`schemaBuilder.describe`, descriptor kinds and field bindings; share small
|
||||||
|
helpers where needed rather than introducing a second YAML-tag parser.
|
||||||
|
`buildSchema` enforces load-root requirements and `resolveSchemaPath` accepts
|
||||||
|
some merely schema-valid dynamic paths; neither alone proves runtime presence.
|
||||||
|
3. Struct fields use `fieldByName`, field index chains, and the inline-map fallback.
|
||||||
|
Reuse `fieldForDecode` with allocation disabled if suitable; ordinary named
|
||||||
|
fields take precedence over inline-map entries. Do not allocate nil embedded
|
||||||
|
pointers. Keep ignored/unexported fields inaccessible. Convert string map keys
|
||||||
|
to the declared key type when necessary, preserving named string-key support.
|
||||||
|
4. Check actual map membership and slice/array bounds. Use `schemaIndex` for
|
||||||
|
contextual numeric tokens, canonical index spelling, and explicit key/index
|
||||||
|
intent. Text-codec scalars, duration, Secret, and other scalar descriptors are
|
||||||
|
leaves, even if represented by structs. Inspect method sets only; do not call
|
||||||
|
codecs, projection, cloning, or secret-value getters during navigation.
|
||||||
|
5. For `any`, describe its current dynamic concrete value under existing supported
|
||||||
|
type/field rules, including supported structs supplied after loading or in a
|
||||||
|
manually constructed result. Reuse dynamic descriptor machinery where its
|
||||||
|
semantics fit; do not apply projection's secret-classification admission as a
|
||||||
|
new lookup validation pass. Existing Secret descriptors remain scalar leaves.
|
||||||
|
An unsupported containing shape returns false when further navigation needs it.
|
||||||
|
6. Keep descriptor/cache state local to the call. Traverse the requested path,
|
||||||
|
using direct field/map/index selection; do not scan or project all runtime
|
||||||
|
configuration values. Recursive types must work. If pointer/interface unwrapping
|
||||||
|
can repeat without consuming a segment, detect that loop locally and return
|
||||||
|
false instead of hanging; do not reject a whole object graph for a cycle on
|
||||||
|
an unvisited branch or introduce a general cycle-validation phase.
|
||||||
|
|
||||||
|
Acceptance: navigation can distinguish missing from present nil and can return
|
||||||
|
named values without changing the configuration. Descriptor work may inspect
|
||||||
|
reachable schema types; lookup should not depend on total runtime collection size.
|
||||||
|
|
||||||
|
## Stage 2 — Expose Value and verify its public contract
|
||||||
|
|
||||||
|
Add `func (r *Result[T]) Value(path Path) (any, bool)` in a focused root file,
|
||||||
|
forwarding current `r.Config`, the converted path, and the existing Secret binding.
|
||||||
|
A nil receiver returns `(nil, false)`. Any non-nil result works independently of
|
||||||
|
its inspection field, including `&Result[T]{Config: ...}`.
|
||||||
|
|
||||||
|
Add focused public tests, for example `facade_result_value_test.go`, protecting:
|
||||||
|
|
||||||
|
- Root and nested lookup, YAML/default names, inline structs/pointers/maps,
|
||||||
|
ignored and unexported fields, and literal escaped/empty keys.
|
||||||
|
- Named scalars, structs, arrays, pointers at terminals, and non-nil intermediate
|
||||||
|
pointers. Present zero/false/empty values remain available without input;
|
||||||
|
metadata separately distinguishes defaulted from explicit values.
|
||||||
|
- Dynamic maps, sequences, and supported structs in `any`, including post-load
|
||||||
|
replacements and hand-built results. Unsupported navigation fails cleanly;
|
||||||
|
reached terminals are not revalidated.
|
||||||
|
- Numeric mapping keys versus sequence indices, parsed contextual tokens,
|
||||||
|
negative/invalid indices, bounds, missing entries, and nil intermediates.
|
||||||
|
A nil interface and typed nil values are tested using their Go semantics.
|
||||||
|
- Struct/array assignment copies and pointer/map/slice aliasing. Mutations to
|
||||||
|
current `Config` are visible to Value while existing inspection stays frozen.
|
||||||
|
- Trusted access to a resolved Secret with a disposable canary and unchanged
|
||||||
|
redaction through existing inspection. A codec that fails if invoked proves
|
||||||
|
lookup does not run application codecs after construction.
|
||||||
|
|
||||||
|
Use a few readable fixtures/tables rather than one test for every helper branch.
|
||||||
|
Reuse existing schema/path tests for rules unchanged by this work. Run focused
|
||||||
|
Value tests and the public boundary tests when this stage is runnable.
|
||||||
|
|
||||||
|
## Stage 3 — Add the inspection view and canonical scope selection
|
||||||
|
|
||||||
|
Add a root-owned, non-generic `Inspection` with unexported state retaining the
|
||||||
|
existing engine Inspection and normalized scope. Put scope-aware implementation
|
||||||
|
in engine (a small private-to-consumers view/helper is sufficient); do not copy the
|
||||||
|
frozen result or construct a partially populated `Result`.
|
||||||
|
|
||||||
|
Implement these public signatures:
|
||||||
|
|
||||||
|
```go
|
||||||
|
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool)
|
||||||
|
func (i Inspection) Metadata() Metadata
|
||||||
|
func (i Inspection) HistoricalPaths() []Path
|
||||||
|
func (i Inspection) Sources() []SourceInfo
|
||||||
|
func (i Inspection) Source(id string) (SourceInfo, bool)
|
||||||
|
func (i Inspection) SourceContext(id string) (ResourceContext, bool)
|
||||||
|
func (i Inspection) Explain(path Path) (Explanation, bool)
|
||||||
|
func (i Inspection) WriteExplanation(output io.Writer, path Path) error
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Constructor failure means nil result, missing completed-load inspection, or
|
||||||
|
invalid path. A valid absent path succeeds. Normalize only after checking
|
||||||
|
validity: parse the canonical pointer spelling into contextual tokens so
|
||||||
|
explicit numeric key/index spellings select the same reporting location.
|
||||||
|
Empty scope selects the whole result.
|
||||||
|
2. Centralize a small canonical-location containment operation for enumeration
|
||||||
|
and later diff filtering. Compare pointer tokens or canonical strings with
|
||||||
|
slash boundaries and an explicit root case. `/a` must not include `/ab`;
|
||||||
|
escaped slashes and empty keys retain their meaning. Existing `pathHasPrefix`
|
||||||
|
compares segment kinds and is not the reporting-location operation needed here.
|
||||||
|
Do not alter semantic path equality elsewhere or build a new path inventory.
|
||||||
|
3. HistoricalPaths filters the existing detached, pointer-sorted enumeration to
|
||||||
|
equal/descendant locations. Preserve its order and uniqueness. Effective
|
||||||
|
presence remains available via `Metadata().Lookup(path)`; no new effective-path
|
||||||
|
public API is needed. Metadata itself remains the original unfiltered view.
|
||||||
|
4. Forward explicit Explain and WriteExplanation paths unchanged, including paths
|
||||||
|
outside the focus. Forward source catalogs/IDs and contexts without ownership
|
||||||
|
filtering. Reuse existing root conversions, extracting small shared conversion
|
||||||
|
helpers only when useful. Ancestor snapshots and dependency evidence remain
|
||||||
|
intact even when they contain siblings outside the focus.
|
||||||
|
5. A zero view uses existing unavailable-state results: empty metadata/path
|
||||||
|
enumeration, nil source catalog, false query results, and explanation-rendering
|
||||||
|
errors as appropriate. Preserve the existing detached-record and borrowed
|
||||||
|
ResourceContext ownership rules.
|
||||||
|
|
||||||
|
Add constructor/forwarding tests for root, absent scopes, malformed paths, nil and
|
||||||
|
manual results, zero views, native paths outside scope, equivalent numeric scope
|
||||||
|
spellings, escaped keys, and sibling-prefix exclusion. Do not require a scope to
|
||||||
|
exist in either effective or historical data.
|
||||||
|
|
||||||
|
## Stage 4 — Render focused effective output with original sensitivity
|
||||||
|
|
||||||
|
Add `func (i Inspection) WriteEffective(output io.Writer) error` and a scoped
|
||||||
|
engine rendering operation using the saved final tree.
|
||||||
|
|
||||||
|
1. Resolve the normalized contextual scope against the frozen document with
|
||||||
|
existing document traversal. No value means an error before writing bytes;
|
||||||
|
explicit null is a present node and renders normally. A zero view or nil
|
||||||
|
writer follows existing effective-rendering failure behavior.
|
||||||
|
2. Pass the selected node and its original application path to the existing
|
||||||
|
snapshot/redaction boundary (`safeSnapshotDocument`/`redactedDocument`), then
|
||||||
|
write with the existing YAML adapter. `pathIsSecret` already checks ancestors;
|
||||||
|
do not reset the selected value to root before sensitivity evaluation.
|
||||||
|
3. Output just the selected value, with existing formatting and redaction.
|
||||||
|
Writer errors propagate normally and may leave partial output. Do not use
|
||||||
|
trusted Value output or marshal/redecode typed settings for this operation.
|
||||||
|
|
||||||
|
Add public behavioral tests for mapping/scalar/sequence/root output, null versus
|
||||||
|
absent, historical-only scopes, ancestor and descendant sensitivity, numeric
|
||||||
|
mapping/sequence scopes, and unchanged output after Config mutation. Use a
|
||||||
|
controlled failing writer for failure propagation; preserve whole-result output
|
||||||
|
coverage rather than duplicating it comprehensively.
|
||||||
|
|
||||||
|
## Stage 5 — Compare focused views using the existing diff
|
||||||
|
|
||||||
|
Implement `func (i Inspection) Diff(other Inspection) ([]Difference, error)`.
|
||||||
|
Validate both initialized views and equality of normalized reporting locations
|
||||||
|
before comparison. Errors return no records; do not add root-Go-type checks.
|
||||||
|
|
||||||
|
Delegate to `engine.Diff` on the original complete frozen inspections, then
|
||||||
|
retain each record whose native Path is equal to, beneath, or above the scope.
|
||||||
|
Use the Stage 3 location helper in both directions. Preserve record order,
|
||||||
|
original paths, snapshot text, Present/Redacted flags, and HiddenChanged.
|
||||||
|
Filter before root record conversion where convenient. Reuse the existing root
|
||||||
|
Difference conversion instead of copying comparison logic.
|
||||||
|
|
||||||
|
Do not extract and compare section roots: doing so would change sequence-atomic
|
||||||
|
regions, ancestor changes, or paired sensitivity. Whole-result comparison cost
|
||||||
|
is deliberately selected; no narrower algorithm or performance experiment is
|
||||||
|
part of this implementation.
|
||||||
|
|
||||||
|
Add focused tests covering:
|
||||||
|
|
||||||
|
- Equal views, ordinary in-scope changes, sibling-only differences filtered out,
|
||||||
|
same-scope comparisons across different application root Go types, and root scope.
|
||||||
|
- Scope addition/removal, absent on both sides, explicit null, and mismatched or
|
||||||
|
zero views. Equivalent numeric scope spellings compare successfully.
|
||||||
|
- A change to a containing sequence or cross-kind ancestor retains that ancestor
|
||||||
|
record, even when its cause is outside the selected descendant. This is the
|
||||||
|
documented consequence of focusing an atomic difference, not proof the selected
|
||||||
|
value changed. Include mapping-to-sequence shape changes at numeric locations.
|
||||||
|
- Sensitivity from either side, ancestor sensitivity and sensitive removal, with
|
||||||
|
disposable canaries absent from returned snapshots and unchanged HiddenChanged
|
||||||
|
semantics. Whole-result Diff retains its existing same-type API and behavior.
|
||||||
|
|
||||||
|
Run focused view-diff tests together with the existing diff tests.
|
||||||
|
|
||||||
|
## Stage 6 — Verify history, provenance, and view ownership together
|
||||||
|
|
||||||
|
Use a small loaded fixture to exercise the interactions not covered by stages
|
||||||
|
3–5. Prefer extending their fixtures rather than creating another test framework.
|
||||||
|
|
||||||
|
- Select a component with effective and removed descendants. HistoricalPaths
|
||||||
|
includes only observed equal/descendant locations, including historical-only
|
||||||
|
paths; Metadata.History and Explain retain ordinary ancestor records and native
|
||||||
|
query paths. Check the distinction between constructor success and presence.
|
||||||
|
- Retain source catalogs, locations and SourceContext through placed inputs and
|
||||||
|
an existing structural transformation such as inheritance. Assert effective
|
||||||
|
field origins lead to the original resource base. A source that contributes
|
||||||
|
siblings remains discoverable; historical-only origins do not restore a lost
|
||||||
|
effective resource origin.
|
||||||
|
- Mutate current Config after selecting the view. Value sees that mutation while
|
||||||
|
view rendering, explanation and comparison still describe the completed load.
|
||||||
|
Mutating returned query records does not alter later reports. Reuse existing
|
||||||
|
detached metadata/source tests where forwarding already protects this risk.
|
||||||
|
- Confirm contextual scope enumeration across historical key/index shape changes
|
||||||
|
without rewriting explicit query paths or collapsing existing history semantics.
|
||||||
|
|
||||||
|
Run the focused history/metadata/render/source-context tests plus the new public
|
||||||
|
view tests. This stage verifies integration, not a new confidentiality or
|
||||||
|
concurrent-mutation contract.
|
||||||
|
|
||||||
|
## Stage 7 — Demonstrate one-library handoff
|
||||||
|
|
||||||
|
Add a maintained example and focused test under `examples/consumers/`, for example
|
||||||
|
`result_component.go` and `result_component_test.go`, using representative small
|
||||||
|
library-owned settings rather than adding an actual PromptKit dependency.
|
||||||
|
|
||||||
|
Show an application-owned root and a library-owned consumer interface using
|
||||||
|
Value, Metadata, and SourceContext. The application passes the whole result;
|
||||||
|
the library selects its conventional path and asserts its public settings type.
|
||||||
|
Registration uses an ordinary typed field selector and existing Definition hooks
|
||||||
|
for defaults, normalization, validation, sensitivity and sequence identities.
|
||||||
|
Bundled defaults enter as ordinary underlays where needed. Runtime construction
|
||||||
|
and resource capture remain library/application responsibilities.
|
||||||
|
|
||||||
|
Show a library-owned inspection facade selecting InspectSubtree once and
|
||||||
|
forwarding effective output, explicit native-path queries and view comparison.
|
||||||
|
Test one normal load followed by handoff, useful typed values, presence/origin,
|
||||||
|
safe reporting, a relative resource resolved from its effective source, and a
|
||||||
|
component validation failure during the application load. Do not create a new
|
||||||
|
ConfigKit registration API or a second library-specific load.
|
||||||
|
|
||||||
|
## Stage 8 — Demonstrate two-library composition
|
||||||
|
|
||||||
|
Extend the example with a second small consumer using the same application
|
||||||
|
result and a smaller consumer-owned interface where sufficient. Compose existing
|
||||||
|
application and library callbacks with explicit ordering and authoritative
|
||||||
|
sequence identity registrations. Use fresh per-load state rather than shared
|
||||||
|
mutable registration captures.
|
||||||
|
|
||||||
|
Verify both consumers receive their own named settings from the same result,
|
||||||
|
application rules still run, explicit values survive absence-based defaults,
|
||||||
|
invalid component identities fail through the normal lifecycle, and source
|
||||||
|
contexts remain usable through placement/inheritance. Include repeated loads to
|
||||||
|
show callback/default state does not leak. Reuse Stage 7's fixtures and existing
|
||||||
|
source-operation tests; demonstrate representative integration without multiplying
|
||||||
|
every layering/import/override combination. Do not modify downstream repositories
|
||||||
|
or claim completion of real PromptKit integration.
|
||||||
|
|
||||||
|
## Stage 9 — Document the implemented boundary and validate the sprint
|
||||||
|
|
||||||
|
Update documentation only once the corresponding behavior exists:
|
||||||
|
|
||||||
|
- Declaration comments own signatures, nil/absence behavior, ordinary aliasing,
|
||||||
|
trusted values, current Config versus frozen evidence, and reporting-only scope.
|
||||||
|
Document canonical scope equivalence on InspectSubtree and errors on unavailable
|
||||||
|
output or invalid comparisons. Do not add public error codes/sentinels merely
|
||||||
|
for this feature; use existing error style.
|
||||||
|
- `docs/config.md` owns shared ownership/inspection and comparison behavior.
|
||||||
|
Distinguish same-type Diff[T] from cross-root-type view comparison, ancestor
|
||||||
|
differences and paired redaction, and value availability from input presence.
|
||||||
|
- `docs/consumers/README.md` links the maintained examples and explains one-load
|
||||||
|
registration, whole-result handoff, owned runtime settings, and native paths.
|
||||||
|
Link from README only with a short useful orientation entry.
|
||||||
|
- `docs/internal/overview.md` records actual helper ownership and reuse.
|
||||||
|
`docs/development.md` adds focused test guidance and ADR 0024 navigation.
|
||||||
|
Update the architecture policy's comparison wording to include accepted
|
||||||
|
ADR 0024 while preserving its existing provenance and other constraints.
|
||||||
|
- Update roadmap status accurately. Retain historical release records and the
|
||||||
|
deferred candidates in future.md. Release notes/publication are a separate task.
|
||||||
|
|
||||||
|
Run the focused tests introduced above, `go test -race ./...`, and the everyday
|
||||||
|
`./scripts/check.sh` using an installed compatible toolchain and pre-acquired
|
||||||
|
dependencies. The everyday check supplies formatting, whitespace, tests, vet and
|
||||||
|
build validation. Run the consumer examples and existing public API/dependency
|
||||||
|
boundary checks through their ordinary tests. Review changed Markdown links and
|
||||||
|
all newly documented behavior against the implementation; no new release gate,
|
||||||
|
performance threshold or benchmark requirement is introduced.
|
||||||
|
|
||||||
|
Completion review must establish that both consumers use one application result,
|
||||||
|
current typed access follows existing field/path conventions, frozen inspection
|
||||||
|
preserves native evidence and sensitivity, cross-type view comparison follows
|
||||||
|
ADR 0024, and whole-result loading/inspection remains compatible. Review the full
|
||||||
|
diff for accidental stronger contracts, unsafe reflect access and duplicated
|
||||||
|
machinery. Commit validated, nonempty work with plain-English messages and report
|
||||||
|
remaining limitations accurately.
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
None. OD-1 through OD-5 and ADR 0024 settle the decisions required for this scope.
|
||||||
|
Private naming and file organization remain ordinary implementation choices.
|
||||||
190
docs/roadmap/promptkit-resolved-configuration-request.md
Normal file
190
docs/roadmap/promptkit-resolved-configuration-request.md
Normal file
@@ -0,0 +1,190 @@
|
|||||||
|
# PromptKit Request: Consume A Component From One Resolved Application Configuration
|
||||||
|
|
||||||
|
Status: upstream feature request for discussion, not an accepted implementation
|
||||||
|
plan. This document specifies consumer capabilities and leaves API names and
|
||||||
|
internal implementation to ConfigKit.
|
||||||
|
|
||||||
|
## Consumer Need
|
||||||
|
|
||||||
|
PromptKit is a Go library used by applications such as Audita and Scriptorium.
|
||||||
|
Today, an application can load its own settings with ConfigKit, then assemble
|
||||||
|
separate sources for PromptKit to load again. Audita uses the application main
|
||||||
|
source's recorded filesystem context to locate companion PromptKit resources.
|
||||||
|
|
||||||
|
The desired workflow is one application-owned ConfigKit load. The application
|
||||||
|
passes the **entire resolved result** to PromptKit, which consumes only the fixed
|
||||||
|
root-level `promptkit` section. The application should not extract, serialize,
|
||||||
|
reshape, or reload that section, or reconstruct its resource contexts.
|
||||||
|
|
||||||
|
The resulting document can contain both sets of settings:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: 3
|
||||||
|
application:
|
||||||
|
output_directory: ./reports
|
||||||
|
promptkit:
|
||||||
|
schema_root: ./schemas
|
||||||
|
collections:
|
||||||
|
weatherreporter:
|
||||||
|
prompts:
|
||||||
|
- id: summarize.alerts
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content_file: ./messages/summary.md
|
||||||
|
output:
|
||||||
|
format: json
|
||||||
|
validation_mode: json_schema
|
||||||
|
schema_path: alerts.json
|
||||||
|
```
|
||||||
|
|
||||||
|
This is an illustrative target configuration, not current PromptKit syntax.
|
||||||
|
The fixed key is PromptKit's convention, not a proposed ConfigKit reserved key.
|
||||||
|
Applications retain source discovery, layering, imports, and override policy.
|
||||||
|
PromptKit retains its field rules and engine construction. ConfigKit retains
|
||||||
|
composition, effective field contexts, and inspection semantics.
|
||||||
|
|
||||||
|
## Verified Baseline
|
||||||
|
|
||||||
|
Assessment baseline: ConfigKit v1.3.0, commit
|
||||||
|
`652ddb649c60208dbba964f0ef919e36725c12c0`. Public-API offline diagnostics verified:
|
||||||
|
|
||||||
|
- A typed component field and an inline catch-all map can allow application
|
||||||
|
siblings while rejecting unknown fields inside the component.
|
||||||
|
- Application callbacks can default component values after composition;
|
||||||
|
registered identities can validate nested resource lists.
|
||||||
|
- Mounted fragments retain field origins and usable `SourceContext` information.
|
||||||
|
- `Explain` on the component path returns a redacted section snapshot.
|
||||||
|
- `WriteEffective` and `Diff` still operate on the whole result. A sibling-only
|
||||||
|
change produces a native difference outside the component.
|
||||||
|
- One shared source-version rule accepting application version 3 rejects a
|
||||||
|
PromptKit fragment declaring version 2.
|
||||||
|
|
||||||
|
The relevant public contracts are [definitions and results](../../lifecycle.go),
|
||||||
|
[resource contexts](../../resource_context.go), [inspection](../../inspection.go),
|
||||||
|
[metadata](../../metadata.go), [comparison](../../diff.go), and
|
||||||
|
[shared source-version checks](../config.md#shared-source-version-checks).
|
||||||
|
These findings establish partial feasibility, not a working whole-result
|
||||||
|
PromptKit integration.
|
||||||
|
|
||||||
|
## 1. Resolved Component Access And Scoped Inspection
|
||||||
|
|
||||||
|
Provide a public way for a library receiving the whole application result to
|
||||||
|
select its section for execution and inspection, independently of the application's
|
||||||
|
particular Go root type. It must retain the original load's effective values and
|
||||||
|
resource contexts without another configuration load or historical reconstruction.
|
||||||
|
|
||||||
|
Execution access must provide usable, trusted configuration values. Existing
|
||||||
|
redacted inspection YAML is not an execution input. Define ownership explicitly:
|
||||||
|
`Result.Config` is mutable while inspection describes a frozen snapshot today.
|
||||||
|
The new contract should state which values a consumer receives and how later
|
||||||
|
caller mutations relate to those values and their inspection evidence. This
|
||||||
|
request does not require all existing `Result.Config` values to become immutable.
|
||||||
|
|
||||||
|
For the selected section, support:
|
||||||
|
|
||||||
|
- Effective configuration output, with native redaction.
|
||||||
|
- Presence/origin queries, relevant history, and path enumeration.
|
||||||
|
- Explanations retaining full native paths such as
|
||||||
|
`/promptkit/collections/weatherreporter/prompts/0/output`.
|
||||||
|
- Comparison of the section between successful loads, retaining native sensitive
|
||||||
|
change semantics and excluding changes confined to sibling application values.
|
||||||
|
- Effective field context lookup so relative message and schema files keep the
|
||||||
|
filesystem and base directory of the source that contributed the field.
|
||||||
|
|
||||||
|
Define absent-section and explicit-null behavior, including comparisons where a
|
||||||
|
section is added or removed. A component view must not turn an absent section
|
||||||
|
into a new composition operation. Scope value-bearing reports and history so
|
||||||
|
selecting a component does not disclose unrelated sibling values through ancestor
|
||||||
|
records. Relevant source provenance remains useful; no requirement is made to hide
|
||||||
|
the existence of a shared source document.
|
||||||
|
|
||||||
|
This is a request for a native consumer boundary, not a guarantee about which
|
||||||
|
nodes ConfigKit may visit internally. Whole-result comparison followed by local
|
||||||
|
filtering can approximate the public diff, but leaves PromptKit maintaining
|
||||||
|
separate adapters for output, opaque metadata, history, and comparison.
|
||||||
|
|
||||||
|
## 2. Independent Source-Version Policies Within One Load
|
||||||
|
|
||||||
|
An application's main configuration and imported component collections can have
|
||||||
|
independent specification versions. For example, the application document above
|
||||||
|
uses `version: 3`, while a PromptKit collection can begin with:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: 2
|
||||||
|
prompts:
|
||||||
|
- id: summarize.alerts
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: Summarize the supplied alerts.
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
```
|
||||||
|
|
||||||
|
The application mounts that standalone collection beneath
|
||||||
|
`promptkit.collections.weatherreporter`. Its version declaration should be checked
|
||||||
|
against PromptKit's collection policy, not the application's version policy.
|
||||||
|
|
||||||
|
Provide public selection of the appropriate version policy for component sources
|
||||||
|
and their imports within the same load. Define the selection behavior for direct
|
||||||
|
inputs, transitive imports, and sources mounted at destinations. Policy assignment
|
||||||
|
must be explicit and independent of whether a declaration's numeric value happens
|
||||||
|
to match one checker; accepting both 2 and 3 everywhere does not meet this need.
|
||||||
|
|
||||||
|
Preserve optional declarations: a collection may omit its header, but a supplied
|
||||||
|
header must be checked under the applicable policy before composition consumes it.
|
||||||
|
Maintain ordinary final-value validation and native diagnostics. Header handling
|
||||||
|
must not let a collection overwrite the application's main version declaration.
|
||||||
|
The application must not preparse fragments, strip headers, or load collections
|
||||||
|
separately to achieve this behavior.
|
||||||
|
|
||||||
|
No particular selector syntax or internal routing mechanism is requested. An
|
||||||
|
application-owned document containing `promptkit` settings is still an application
|
||||||
|
document; it does not require two competing root version headers.
|
||||||
|
|
||||||
|
## 3. Demonstrate A Small Component Integration Contract
|
||||||
|
|
||||||
|
Please evaluate this complete consumer sequence alongside the requested APIs:
|
||||||
|
|
||||||
|
1. The application declares its own configuration type and includes PromptKit's
|
||||||
|
supported public settings/registration at `promptkit`.
|
||||||
|
2. It incorporates PromptKit-owned defaults, normalization, validation, sequence
|
||||||
|
identities, and sensitivity rules into its ordinary ConfigKit load. Desired
|
||||||
|
bundled resources enter as ordinary underlays before resolution.
|
||||||
|
3. ConfigKit loads and resolves the complete configuration once, applying the
|
||||||
|
application's rules and the component's rules in the supported lifecycle.
|
||||||
|
4. The application passes that whole result to PromptKit. PromptKit uses the
|
||||||
|
fixed section and original source contexts to capture resources and construct
|
||||||
|
its engine. It does not inject defaults through a second load.
|
||||||
|
5. PromptKit delegates its configuration reports and comparisons to the native
|
||||||
|
scoped inspection capability.
|
||||||
|
|
||||||
|
Existing `Definition[T]` callbacks may be sufficient with a small library helper.
|
||||||
|
A new component registry is **not** a prerequisite of this request. Please show
|
||||||
|
how component rules can be composed with an application-owned root type without
|
||||||
|
the application reproducing those rules or depending on the library's internal
|
||||||
|
types. If a public extension is needed, keep it limited to the demonstrated gap.
|
||||||
|
The section handoff should not require a per-application extraction adapter.
|
||||||
|
|
||||||
|
## Acceptance Scenarios
|
||||||
|
|
||||||
|
- One load contains application fields and a typed PromptKit section; unrelated
|
||||||
|
fields are governed by the application, while invalid component fields fail.
|
||||||
|
- Component defaulting, normalization, identities, and sensitivity run through
|
||||||
|
the normal lifecycle and remain visible in the resolved result and inspection.
|
||||||
|
- Whole-result handoff works with an application-owned Go configuration type,
|
||||||
|
with no section serialization/reload or source-context reconstruction.
|
||||||
|
- Embedded and operator collection fragments retain relative-file contexts after
|
||||||
|
mounting, inheritance, and overrides, including identical file basenames.
|
||||||
|
- Component execution access preserves values needed for execution, while public
|
||||||
|
inspection redacts sensitive values. Ownership/mutation behavior is documented.
|
||||||
|
- Sibling-only changes do not appear in component comparisons; component changes,
|
||||||
|
sensitive changes, and section addition/removal follow native reporting rules.
|
||||||
|
- Application version 3 and PromptKit collection version 2 coexist under their
|
||||||
|
respective policies; each rejects unsupported declarations independently.
|
||||||
|
Headerless collections and transitive imports exercise the selected policies.
|
||||||
|
|
||||||
|
PromptKit's repair-default change and its domain-specific validation rules are
|
||||||
|
outside this upstream request. No changes to ConfigKit's internal representation,
|
||||||
|
algorithms, or package layout are proposed. Please distinguish capabilities already
|
||||||
|
available through a concise public example from those needing new public APIs.
|
||||||
@@ -227,47 +227,14 @@ APIs and a limited stand-in for `Value`. They establish feasibility, not complet
|
|||||||
of real PromptKit integration. PromptKit still owns its public settings model,
|
of real PromptKit integration. PromptKit still owns its public settings model,
|
||||||
presence-state handling, resource capture, and settings ownership refactoring.
|
presence-state handling, resource capture, and settings ownership refactoring.
|
||||||
|
|
||||||
## Work needed
|
## Delivery scope and completion
|
||||||
|
|
||||||
1. Record representative lookup and reporting
|
The [implementation plan](implementation.md) owns execution order and validation.
|
||||||
outcomes, including nil values, absent scopes, and the difference between
|
The change includes private typed traversal using existing schema bindings, the
|
||||||
typed-value availability and input presence.
|
root-owned value accessor and inspection view, focused behavioral coverage,
|
||||||
2. Add the root-owned method and reuse existing schema bindings and semantic path
|
maintained one-library and two-library examples, and updates to the public
|
||||||
logic for typed traversal. Keep any supporting implementation private. Do not
|
contracts and consumer guidance. Architecture and comparison documentation will
|
||||||
route through inspection projection or add another complete load-time snapshot.
|
reflect ADR 0024 when its implementation lands.
|
||||||
3. Add focused public tests for root/nested lookup, named and pointer types,
|
|
||||||
inline fields/maps, dynamic containers and supported structs inside `any`,
|
|
||||||
numeric keys versus indices, bounds, missing/nil values, scalar leaves, and
|
|
||||||
the settled receiver/mutation rules, including manually constructed results.
|
|
||||||
Verify ordinary aliasing and unchanged frozen inspection without promising
|
|
||||||
concurrent mutation safety. Check trusted secret access and existing redaction
|
|
||||||
with disposable values.
|
|
||||||
4. Add the root-owned inspection view over existing private inspection state.
|
|
||||||
Reuse explanations, metadata, source queries, rendering, and comparison;
|
|
||||||
add only subtree rendering and reporting selection where needed. Keep
|
|
||||||
whole-result APIs unchanged. Preserve original paths and sensitivity context.
|
|
||||||
5. Add focused inspection checks for absent, null, and historical-only sections;
|
|
||||||
subtree output and discovery; native-path queries outside the focus; ancestor
|
|
||||||
history and differences; source-context continuity; and sensitivity inherited
|
|
||||||
from ancestors or either compared result. Check sibling path names and numeric
|
|
||||||
path segments, including equivalent scope spellings and a container changing
|
|
||||||
between mapping and sequence. Verify frozen behavior after caller mutation
|
|
||||||
and unchanged whole-result inspection. Include comparisons between different
|
|
||||||
root Go types, a section existing on only one side, mismatched scopes, and
|
|
||||||
zero views.
|
|
||||||
6. Add maintained one-library and two-library consumer examples. Demonstrate one
|
|
||||||
load, typed registration, whole-result handoff, composed callbacks and identity
|
|
||||||
checks, and resource contexts retained through placement and existing structural
|
|
||||||
operations. Include a library-owned inspection facade that selects its scope
|
|
||||||
once and forwards focused reports and explicit queries. Keep library-specific
|
|
||||||
runtime construction outside ConfigKit.
|
|
||||||
7. Document the APIs beside their declarations, extend the configuration ownership
|
|
||||||
contract and consumer guidance, and run the relevant public tests and normal
|
|
||||||
repository checks. This is an additive API; existing loading, inspection,
|
|
||||||
comparison, and shared source-version behavior remain as documented.
|
|
||||||
Clarify the distinction between same-type `Diff[T]` and structural view
|
|
||||||
comparison in the architecture policy and comparison documentation, following
|
|
||||||
[ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md).
|
|
||||||
|
|
||||||
Completion means both representative library consumers can obtain their typed
|
Completion means both representative library consumers can obtain their typed
|
||||||
settings and existing provenance from one application result without application
|
settings and existing provenance from one application result without application
|
||||||
|
|||||||
Reference in New Issue
Block a user