From b8aada3b6e521b6e008a99148ade8118121c9cfb Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 10 Oct 2026 16:23:02 +0000 Subject: [PATCH] Align documentation with accepted ADR 0011 --- docs/policy/architecture.md | 11 ++++++----- docs/roadmap/modules.md | 10 ++++++---- docs/roadmap/registration-api.md | 11 ++++++----- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 6584d7d..c64c8ec 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -127,11 +127,12 @@ and execution dependencies are separate from CLI inputs. Integration suites keep their typed CLI input separate from shared acquisition state. For a configuration operation, initialize and populate each selected scope's input independently, applying only its applicable selector bindings; initialize shared state once for -the selected inspection invocation. Named definition inspection uses one input -and one shared state. Complete applicable preflight and input checks before shared -state initialization and provider acquisition. Factories need not run after a -failure and remain uninvoked during construction, installation, help, version, -and scope discovery. +the selected inspection invocation. Configuration input validation receives the +selected scope identity together with its applicable typed input. Named definition +inspection uses one input and one shared state. Complete applicable preflight +and input checks before shared state initialization and provider acquisition. +Factories need not run after a failure and remain uninvoked during construction, +installation, help, version, and scope discovery. Omitted input and state factories supply the respective type's zero value, including nil for pointers. Caller factories and callbacks retain responsibility diff --git a/docs/roadmap/modules.md b/docs/roadmap/modules.md index 7f7dc42..54c924f 100644 --- a/docs/roadmap/modules.md +++ b/docs/roadmap/modules.md @@ -201,9 +201,10 @@ needed for CommandKit's source-only releases. Completed: ADR 0010 is accepted and ADR 0003 is marked partially superseded, with its decision text preserved. The consumer API is finalized, ADR 0011 records its registration and input-lifetime choices, ADR 0001 remains accepted -with refinements recorded in ADR 0011, and ADR 0010's consumer-migration consequence is superseded for the -unreleased prototype transition. The architecture policy reflects the selected -core/integration facades and installed-family ownership. Earlier accepted decision text remains +with refinements recorded in ADR 0011. ADR 0010's consumer-migration consequence +is superseded for the unreleased prototype transition. The architecture policy +reflects the selected core/integration facades, installed-family ownership, and +scope-aware configuration input validation. Earlier accepted decision text remains intact. - Use the finalized [registration API](registration-api.md) and selected module @@ -211,7 +212,8 @@ intact. - Inventory root exports, imports, private helper use, and family registration behavior. Use the inventory as evidence of responsibilities and coupling, not as a list of APIs to preserve. Implement final exports and ownership from the - selected API and consumer needs; no compatibility mapping for the unpublished prototype is required. + selected API and consumer needs; no compatibility mapping for the unpublished + prototype is required. - Use the API document's [three representative consumers](registration-api.md#complete-consumer-registration-examples): core only, ConfigKit only, and both libraries. They define the target wiring, including combined configuration scopes and independent definition inspection; diff --git a/docs/roadmap/registration-api.md b/docs/roadmap/registration-api.md index c33a9c2..56c1af3 100644 --- a/docs/roadmap/registration-api.md +++ b/docs/roadmap/registration-api.md @@ -673,10 +673,11 @@ custom inspection callback; this does not redefine upstream version semantics. ### Why inputs and shared state have separate types -Combining selector fields and a cache in one context type obscures their lifetimes. -A shared pointer to that object cannot isolate selector fields between scopes. -Cloning arbitrary application graphs would add a promise CommandKit cannot make. -The selected `Suite[I, S]` makes the actual two responsibilities explicit: +Combining selector storage and a cache in one context type obscures their distinct +lifetimes and can cause scope-specific inputs to alias. Separate input values +could share a cache through references, but would leave input isolation and state +lifetime implicit. The selected `Suite[I, S]` makes the two responsibilities +explicit without requiring arbitrary application graphs to be cloned: - `I`: per-scope/per-command CLI input, initialized and populated independently. - `S`: shared acquisition state for one selected inspection invocation. @@ -1214,7 +1215,7 @@ The documentation alignment is complete: | Owner | Recorded decision | | --- | --- | -| [ADR 0011](../adr/0011-captured-declarations-and-installation.md) | Captured declarations, atomic installation batches, installed-family ownership, root-only placement, and separate input/shared-state lifetimes | +| [ADR 0011](../adr/0011-captured-declarations-and-installation.md) | Captured declarations, atomic installation batches, installed-family ownership, root-only placement, separate input/shared-state lifetimes, and scope-aware configuration input validation | | [ADR 0001 status](../adr/0001-command-dispatch-and-inputs.md#status) | Remains accepted, with refinements recorded in ADR 0011 and its decision text preserved | | [ADR 0010](../adr/0010-optional-integration-modules.md) | Core/integration dependency boundaries remain in effect; ADR 0011 refines registration and supersedes the migration-guide requirement for this unreleased prototype | | [Architecture policy](../policy/architecture.md) | Uniform installed-family ownership, optional integration facades, and declaration/input boundaries |