diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..0165543 --- /dev/null +++ b/docs/roadmap/implementation.md @@ -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. diff --git a/docs/roadmap/promptkit-resolved-configuration-request.md b/docs/roadmap/promptkit-resolved-configuration-request.md new file mode 100644 index 0000000..8114144 --- /dev/null +++ b/docs/roadmap/promptkit-resolved-configuration-request.md @@ -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. diff --git a/docs/roadmap/result-value.md b/docs/roadmap/result-value.md index 9c81371..c14eef9 100644 --- a/docs/roadmap/result-value.md +++ b/docs/roadmap/result-value.md @@ -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