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,
|
||||
presence-state handling, resource capture, and settings ownership refactoring.
|
||||
|
||||
## Work needed
|
||||
## Delivery scope and completion
|
||||
|
||||
1. Record representative lookup and reporting
|
||||
outcomes, including nil values, absent scopes, and the difference between
|
||||
typed-value availability and input presence.
|
||||
2. Add the root-owned method and reuse existing schema bindings and semantic path
|
||||
logic for typed traversal. Keep any supporting implementation private. Do not
|
||||
route through inspection projection or add another complete load-time snapshot.
|
||||
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).
|
||||
The [implementation plan](implementation.md) owns execution order and validation.
|
||||
The change includes private typed traversal using existing schema bindings, the
|
||||
root-owned value accessor and inspection view, focused behavioral coverage,
|
||||
maintained one-library and two-library examples, and updates to the public
|
||||
contracts and consumer guidance. Architecture and comparison documentation will
|
||||
reflect ADR 0024 when its implementation lands.
|
||||
|
||||
Completion means both representative library consumers can obtain their typed
|
||||
settings and existing provenance from one application result without application
|
||||
|
||||
Reference in New Issue
Block a user