From 90c2d7e409622541e835707a161b7c3dbf20e23a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 16 Oct 2026 14:49:23 +0000 Subject: [PATCH] Clarify unresolved source destination evidence in implementation plan --- docs/roadmap/implementation.md | 69 +++++++++++++++++++++++++++++----- 1 file changed, 59 insertions(+), 10 deletions(-) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index c155411..bdf451e 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -50,6 +50,9 @@ type SequenceComposition struct { - Add `SequenceCompositions []SequenceComposition` to `Definition[T]`. - Add `PlacementMode PlacementMode` to `Input` and `SourceInfo`. +- Add `DestinationUnresolved bool` to `SourceInfo`. False preserves the existing + exact-destination interpretation; true explicitly marks the enclosing-container + fallback described below. This is output evidence, not an input option. - Add both `Destination Path` and `PlacementMode PlacementMode` to `Options[T]`. Ordinary `Load` needs the same per-source controls as the layered entry point; its overlay and CLI coordinates remain application-rooted. @@ -131,6 +134,37 @@ inventing an all-errors guarantee or freezing incidental message wording. Output evidence may contain such indexes even though input destinations and registrations accept only mapping-key segments. +### Unresolved destination evidence + +`SourceInfo.DestinationUnresolved` describes whether that snapshot's `Destination` +is the source's exact effective destination container: + +- When false, `Destination` is exact. This says nothing about whether the load + succeeded or the source's values survived later replacement. An item source + can have an exact sequence-container destination before its own item index is + assigned, because that index is not part of its reported container path. +- When true, an enclosing item index needed for the destination has not been + assigned. `Destination` is only the nearest resolved enclosing collection + container, not the source's actual mapping destination or nested sequence + destination. Do not append the unresolved local suffix as though the missing + index were a mapping key, or use a fabricated index. +- For example, a mapping helper destined for `prompts[1].metadata` reports the + container `prompts` with `DestinationUnresolved: true` until the outer item + index is assigned. Later snapshots report `prompts[1].metadata` with false. + The item-root source itself reports `prompts` with false when that container + is known. The placement mode continues to describe each source's own mode. +- Apply this distinction to every source-record exposure, including source + records available during callbacks and failed-load records. Once projection + resolves the container, subsequent snapshots report the exact path with false. + Previously returned detached snapshots retain their original path and flag. + Completed successful loads report resolved containers; early failures may + contain both resolved and unresolved source records. + +This flag makes the existing planned fallback observable without adding a public +item-index API, promising permanent indexes, or reconstructing unknown placement +after a failure. Physical source locations, source IDs, and source-local version +evidence retain their existing meaning regardless of the flag. + Choose private helper names and file splits to fit existing responsibilities. Do not introduce a provider framework, generic merge callbacks, a second loading lifecycle, or a public identity-selector API to implement these mechanics. @@ -307,6 +341,8 @@ Scope: placement primitives and engine per-input options; not public exposure. - Add the private placement mode to engine input/request/options/source records, with preflight validation. Keep mapping placement unchanged. A valid item mode needs a nonempty mapping-key destination relative to its current mapping scope. +- Carry the destination-resolution state in engine source records so later + scoped acquisition can distinguish exact containers from unresolved fallbacks. - Extend placement to wrap one completed source mapping in a singleton sequence at that destination. Preserve mapping-root input validation; do not accept raw source sequence/scalar roots. A nil payload stays absent, and `{}` contributes @@ -342,6 +378,10 @@ Scope: directive parsing and scoped acquisition/composition. composer. Assign outer ranges there, then project the retained item body and helper events through those ranges. Do not emit each ordinary helper as a separate record or validate its identity independently. +- Maintain source destination-resolution state as enclosing ranges are assigned. + Before assignment, source snapshots use the explicitly marked fallback from + the fixed design; after assignment, project the exact container. Preserve + already-returned snapshots rather than updating them in place. - Cover path and glob item imports, a helper-provided ID, relative and transitive helper destinations, mixed authored lists/items, optional unmatched imports, empty items, nested placement, default-mode independence, and physical paths @@ -424,19 +464,25 @@ Scope: root facade declarations, conversions, and public integration tests. describing defaults, option failures, and ownership. Convert Definition registrations and paths, ordinary Options destinations/modes, layered Inputs, and successful/failed SourceInfo records in both directions as applicable. + Convert `DestinationUnresolved` alongside `Destination` and `PlacementMode`. Update callback-entry source conversions too, not only `Result.Sources`. - Preserve immutable source snapshots, reader single-use behavior, callback lifetime, independent loads, and no public exposure of engine/parser types. SourceInfo reports its own selected mode; CLI/overlay sources use mapping mode unless an actual supported item placement was applied. - For a completed load, resolve nested source containers through their owning - item projection. On an early failure retain acquired evidence without inventing - an index that was never assigned: keep an unresolved nested source's Destination - at its nearest resolved enclosing collection container, rather than flattening - away an index and reporting a fictitious effective mapping path. Once assigned, - use the projected destination. Failed-load records describe acquisition context, - not a usable partial configuration. Do not add a public index or identity-address - API or promise resolution of every failed source's final placement. + item projection. Apply the fixed unresolved-destination contract to callbacks + and early failures: a fallback container always has `DestinationUnresolved` + set to true; an exact container has false. Failed-load records describe + acquisition context, not a usable partial configuration. Do not add a public + index or identity-address API or promise resolution of every failed source's + final placement. +- Test an unresolved helper record exposed during a callback and on early + failure, its exact projected destination after assignment, and a failure after + assignment that retains the exact destination. Distinguish an exact item-root + container from a helper fallback with the same path. Verify nested-item + fallback, preserved snapshot ownership, and false for unchanged mapping-only + sources. Reuse fixtures where these scenarios share the same lifecycle path. - Public tests demonstrate ordinary and layered opt-in, an item-import glob, authored-list/item interoperability, one-source validation, helper origins and resource contexts at shifted indexes, both option-error entry points, detached @@ -444,9 +490,12 @@ Scope: root facade declarations, conversions, and public integration tests. edge cases in engine tests. - Update `docs/config.md` for the now-public registration controls, ordinary destination options, complete placement/evidence behavior, and strict-versus- - replacement validation boundary. Update the architecture policy's composition - summary to recognize the registered-sequence rule and link ADR 0014. Stage 13 - reviews and completes the surrounding guidance, not these canonical contracts. + replacement validation boundary. Document `DestinationUnresolved` and its + fallback meaning in both `SourceInfo` comments and the owning configuration + contract, including callback and failure snapshots. Update the architecture + policy's composition summary to recognize the registered-sequence rule and + link ADR 0014. Stage 13 reviews and completes the surrounding guidance, not + these canonical contracts. Validation: focused facade tests, `go test . -run 'TestPublicFacadeBoundary|TestDependencyImportBoundary'`,