From 160604095c95c5f286279094ac02ee814910fef4 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 10 Oct 2026 16:19:45 +0000 Subject: [PATCH] Accept the captured declaration architecture and align documentation --- README.md | 2 + docs/adr/0001-command-dispatch-and-inputs.md | 4 + docs/adr/0010-optional-integration-modules.md | 6 + ...-captured-declarations-and-installation.md | 187 ++++++++++++++++++ docs/consumers/guide.md | 4 +- docs/development.md | 5 +- docs/internal/overview.md | 5 +- docs/policy/architecture.md | 97 +++++++-- docs/roadmap/modules.md | 31 +-- docs/roadmap/registration-api.md | 41 ++-- 10 files changed, 325 insertions(+), 57 deletions(-) create mode 100644 docs/adr/0011-captured-declarations-and-installation.md diff --git a/README.md b/README.md index 2dfe5b6..616aa53 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ The [consumer guide](docs/consumers/guide.md) links to two maintained examples: ## Future work and history +- [Optional integration module roadmap](docs/roadmap/modules.md) +- [Finalized registration API design](docs/roadmap/registration-api.md) - [Deferred capabilities and proposals](docs/roadmap/deferred.md) - [Completed planning and implementation records in Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap) diff --git a/docs/adr/0001-command-dispatch-and-inputs.md b/docs/adr/0001-command-dispatch-and-inputs.md index 6562830..4d7b81f 100644 --- a/docs/adr/0001-command-dispatch-and-inputs.md +++ b/docs/adr/0001-command-dispatch-and-inputs.md @@ -4,6 +4,10 @@ Accepted. +[ADR 0011](0011-captured-declarations-and-installation.md) refines +declaration construction, installation, optional-family namespace reservation, +and integration input/state lifetimes. + ## Date 2026-10-06 diff --git a/docs/adr/0010-optional-integration-modules.md b/docs/adr/0010-optional-integration-modules.md index e0c51dc..2534178 100644 --- a/docs/adr/0010-optional-integration-modules.md +++ b/docs/adr/0010-optional-integration-modules.md @@ -4,6 +4,12 @@ Accepted. Partially supersedes [ADR 0003](0003-public-facade.md) as described below. +Partially superseded by [ADR 0011](0011-captured-declarations-and-installation.md) +for the consumer-migration consequence during the unreleased prototype +transition. It also supplies the registration and invocation-lifetime +decisions left open here. The module +boundary and remaining principles continue to apply; this record's decision +text is retained. ## Date diff --git a/docs/adr/0011-captured-declarations-and-installation.md b/docs/adr/0011-captured-declarations-and-installation.md new file mode 100644 index 0000000..ee11ced --- /dev/null +++ b/docs/adr/0011-captured-declarations-and-installation.md @@ -0,0 +1,187 @@ +# ADR 0011: Capture command declarations and install optional families explicitly + +## Status + +Accepted. Refines [ADR 0001](0001-command-dispatch-and-inputs.md) for declaration +construction, installation, optional-family namespace reservation, and integration +input/state lifetimes. Partially supersedes +[ADR 0010](0010-optional-integration-modules.md) only for its consumer-migration +consequence during the unreleased prototype transition, and refines its +convenient composition principle. + +## Date + +2026-10-10 + +## Context + +Optional integration modules need to assemble complete standard families through +public core contracts. Applications also declare their own commands and groups. +Different construction and installation paths would add repeated error checks +and registration plumbing, weakening CommandKit's infrastructure-reduction goal. +The current implementation is an unreleased prototype with no downstream +consumers. Its declarations are evidence to evaluate, without compatibility +obligations that would constrain the selected API. + +Declaring an optional integration is distinct from installing it. Broad references +to reserved standard families in ADR 0001 do not specify when an optional name +becomes reserved. Dependency selection alone should not consume an application +namespace or install commands. + +Configuration inspection can select several scopes. Those scopes may share an +application-owned cache while receiving different selector values. Combining +selector storage and shared state in one context obscures their distinct +lifetimes and can cause scope-specific inputs to alias. Separate input and state +types make those lifetimes explicit. +Integrations also need to compose typed bindings without accessing private core +parsers and setters or exposing backend structures. + +## Decision + +### Uniform captured declarations + +Applications and integrations construct the same opaque core command declarations +and install them through core application construction or registration. Initial +integrations provide complete-family factories and focused conveniences; they do +not add separate integration-specific installation APIs. Suite/provider types +remain integration-owned rather than becoming a universal core provider model. + +Factories capture metadata, bindings, capability selections, selector +applicability, and callback references eagerly. They copy the declaration +collections needed so later edits to the source metadata do not change a returned +command. Construction errors remain attached to the declaration and are reported +at installation. There is no public deferred preparation lifecycle or untyped +integration payload. + +Core installation validates the whole batch before registry mutation, including +retained errors, bindings, placement, and collisions. Failed application +construction returns no usable application; failed later registration leaves the +existing registry intact. This atomicity applies to one installation call, not +separate calls or arbitrary effects in caller code. Report retained errors with +useful command context and preserve supported wrapped error identity without +requiring a particular aggregate-error representation. + +An explicit absence declaration contributes no command, help entry, or namespace +claim. Installation checks its attached errors before skipping it. A zero command +declaration remains invalid. Integrations define their own empty-suite semantics: +the initial configuration suite needs at least one named scope, while a valid +definition suite with no capabilities is absent. Metadata-only configuration +scopes remain discoverable. A nil loader supplied to an adapter is invalid wiring; +narrowing its capability list does not erase that error. + +Declarations may be installed in multiple applications with independent registry +and invocation state. Callback references and the objects they capture remain +application-owned; declaration reuse neither deep-copies those objects nor +establishes concurrent-dispatch support. Application helpers performing other +fallible work may still return errors. + +### Optional-family namespace lifetime and placement + +Core construction always reserves help and version. An optional standard family +owns its complete root namespace when a real family declaration is installed. +An import or absent declaration reserves nothing. An application may use that +name while the family is uninstalled, but later installation then fails with a +collision. Application registration after standard-family installation fails in +the same way. Neither order merges groups, replaces handlers, or permits private +application operations beneath an installed standard family. + +Standard-family declarations carry root-only placement metadata. Core rejects +their installation below another group. Placement is a public declaration +property, not authentication of the declaring package or a core allowlist of +integration names. A real empty root-only group still claims its namespace and +obeys placement checks; explicit absence does neither. + +### Separate typed input from shared acquisition state + +Integration suites distinguish typed CLI input from typed shared acquisition +state. Configuration inspection initializes and populates one input per selected +scope, applying only applicable selector bindings, and initializes shared state +once for the selected inspection invocation. Named definition inspection uses +one input and one shared state. Providers receive both explicitly. +Configuration input validation receives the selected scope identity together +with its applicable typed input. + +Availability preflight and applicable input checks precede shared-state +initialization and acquisition. A failed check stops that path; later input +factories need not run. Construction, installation, help, version, and scope +discovery invoke neither input/state factories nor acquisition providers. + +An omitted factory supplies its type's zero value, including nil for a pointer. +Applications supply initialization when their accessors or providers need it. +CommandKit does not allocate arbitrary pointer types, clone arbitrary application +graphs, repair aliases returned by factories, or reject a provider that accepts +nil intentionally. Core-owned parsed collections remain independent when applied +to separate inputs. Caller-owned objects and callback effects retain their own +lifetimes. + +Provide a narrow typed core binding-composition contract to capture converted +values and apply a selected binding subset to an initialized input. Preserve +binding identity, defaults, and presence without string-based handler lookup or +exposure of private setters, parser state, or backend objects. Copying a binding +preserves its identity; constructing a lookalike binding does not. + +Execution-required checks apply to the selected subset, so an app-only selector +does not become required for an engine-only scope request. Missing required input +is a usage failure. An invalid binding selection or destination is a wiring +failure, classified as operational when encountered at invocation. Those +categories remain identifiable through supported wrapping; assembly-detectable +metadata defects remain installation errors. Both invocation failures stop before +shared-state initialization and acquisition. This composition is part of the +existing typed-input model, not another parser or a raw-argument handler API. + +### Relationship to earlier decisions + +No compatibility wrappers or downstream migration guide are required for this +unreleased prototype transition. This replaces +ADR 0010's consumer-migration consequence for this transition only. Changes to +published contracts remain governed by the [release policy](../policy/release.md). + +ADR 0001 continues to govern dispatcher ownership, explicit instance registries, +typed bindings, presence, and application/domain boundaries. This decision +clarifies that optional-family namespace ownership begins upon installation. +It refines the construction and installation mechanics left open there and +distinguishes integration input from shared state. +It does not change the grammar, report formats, supported operation inventory, +or outcome/delivery rules in ADRs 0004 through 0009. + +ADR 0010 continues to govern separate core/integration module contracts and +dependency direction. Integration factories return core declarations through +supported public composition contracts. Deliberate exports, private +implementation state, and backend isolation remain governed by +[ADR 0003](0003-public-facade.md) as scoped by ADR 0010. Exact exported signatures +belong in Go declarations and GoDoc when implemented; this record owns the +architectural choices rather than an implementation inventory. + +## Alternatives considered + +| Alternative | Analysis | +| --- | --- | +| Fallible constructors plus integration-specific registration helpers | Makes each construction failure immediate, but creates several assembly conventions and repeated consumer checks. Captured errors keep one installation boundary. | +| Deferred preparation callbacks | Allows installation to construct a family, but adds lifecycle and error timing beyond eager capture. No demonstrated assembly need requires it. | +| Reserve all known optional family names at core construction | Prevents later name conflicts, but consumes namespaces for integrations the application has not selected. Installed-family ownership keeps conflicts explicit without that restriction. | +| Separate family/plugin registration framework | Could encode ownership and composition, but a captured command with root-only placement and batch validation expresses the required behavior without another installation model. | +| One shared input/state object | Uses fewer type parameters and can share a cache through references in separate input values, but leaves the distinct lifetimes implicit and scope-input isolation to application conventions. Explicit input and state types make those lifetimes visible. | +| Clone hooks or automatic pointer allocation | Can hide input construction, but adds object-graph and initialization responsibilities that belong to the application. Explicit factories keep those choices visible. | +| Public binding getters/setters or an untyped value bag | Enables integration assembly, but exposes private mechanics or returns typed-input assembly to string lookup. Narrow typed composition addresses the actual need. | + +## Consequences + +Consumers assemble domain commands and optional families visibly through one +installation boundary. Integrations remain convenient without private core +access. Errors identified during eager assembly are observed at installation, +before provider acquisition. + +Installing an optional family can fail if the application already uses its root +name; the application decides which declaration to install. Installed standard +families retain their ownership and root placement in either registration order. + +Composed suites use two types and explicit initialization when needed. The +context-free application-configuration convenience hides unused suite machinery +for simple consumers. The public typed-composition seam adds a deliberate core +contract while keeping implementation and backend state private. + +The [architecture policy](../policy/architecture.md) owns normative boundaries. +Implementation status and sequencing remain in the roadmaps. These choices +govern CommandKit's declarations and calls; application loading, cache design, +startup, domain validation, callback effects, and process exit remain consumer +choices. diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index 68c42ca..2442146 100644 --- a/docs/consumers/guide.md +++ b/docs/consumers/guide.md @@ -1,7 +1,7 @@ # Consumer guide -CommandKit's supported Go API is the root `commandkit` package. Start with an -`App`, register CommandKit's standard inspection families, register application +CommandKit's currently implemented Go API is the root `commandkit` package. +Start with an `App`, register CommandKit's standard inspection families, register application commands, and call `App.Execute` with the caller's context and streams. The caller retains process startup, signal handling, and exit mapping. diff --git a/docs/development.md b/docs/development.md index 552fac3..41a311b 100644 --- a/docs/development.md +++ b/docs/development.md @@ -49,9 +49,10 @@ canonical documentation owners. | --- | --- | | Implemented CLI behavior | [CLI reference](cli.md) | | Public API usage and standard-suite wiring | [Consumer guide](consumers/guide.md), [configuration declarations](../config.go), [PromptKit declarations](../promptkit.go), and applicable ADRs | -| Dispatcher, registration, or typed inputs | [Command declarations](../command.go), [bindings](../binding.go), [invocation](../execute.go), and [ADR 0001](adr/0001-command-dispatch-and-inputs.md) | +| Dispatcher, registration, or typed inputs | [Command declarations](../command.go), [bindings](../binding.go), [invocation](../execute.go), and [ADR 0001](adr/0001-command-dispatch-and-inputs.md), refined by [ADR 0011](adr/0011-captured-declarations-and-installation.md) | | Backend integration | [Internal overview](internal/overview.md), [adapter implementation](../internal/cobra/parse.go), and [ADR 0002](adr/0002-cobra-backend.md) | -| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0003](adr/0003-public-facade.md), and the architecture policy | +| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0003](adr/0003-public-facade.md) as scoped by [ADR 0010](adr/0010-optional-integration-modules.md), and the architecture policy | +| Optional integration module transition and finalized API | [Module roadmap](roadmap/modules.md), [registration API target](roadmap/registration-api.md), and [ADR 0011](adr/0011-captured-declarations-and-installation.md) | | Deferred capabilities and proposals | [Deferred work](roadmap/deferred.md) | | Completed planning and implementation history | [Retired records in Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap) | | Release tooling | [Maintainer release procedure](release.md) | diff --git a/docs/internal/overview.md b/docs/internal/overview.md index dfcbed2..b05a0a3 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -3,7 +3,10 @@ CommandKit ships one public package, `commandkit`, and one internal package, `internal/cobra`. This inventory describes the current implementation; the [architecture policy](../policy/architecture.md) owns normative boundaries and -[ADR 0003](../adr/0003-public-facade.md) records the public package boundary. +[ADR 0003](../adr/0003-public-facade.md) records the original facade decision. +[ADR 0010](../adr/0010-optional-integration-modules.md) now scopes that decision to +the core and optional integrations; the [module roadmap](../roadmap/modules.md) +tracks the pending transition. The inventory below describes the prototype. ## `commandkit` diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index cf2dd1e..6584d7d 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-10-08 +**Last Updated**: 2026-10-10 **Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) @@ -44,14 +44,22 @@ flexibility to express genuine application requirements within one command model [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) records the selected CommandKit-owned dispatcher, per-instance registry, and typed-input model. +[ADR 0011](../adr/0011-captured-declarations-and-installation.md) refines declaration +capture, installation, optional-family ownership, and invocation input lifetimes. CommandKit owns dispatch, common parsing, presence tracking, help, shared syntax diagnostics, and the handlers and observable contracts of its standard families. Applications register domain commands outside those families and own their meaning, effects, domain validation, artifacts, and operational outcomes. -Namespaces provide the ownership boundary: standard `config` and an installed -`promptkit` family remain CommandKit-owned. CommandKit reports registration errors -for attempts to replace their handlers or add private operations beneath them. +Namespaces provide the ownership boundary. Core construction reserves help and +version. Optional standard families, including config and promptkit, own their +root namespace when installed; importing an integration or declaring an absent +family claims no namespace. An application may occupy an uninstalled family name. +Installing the standard family then reports a collision, as does application +registration after the standard family is installed. Neither order merges groups +or replaces handlers. Installed standard families cannot acquire private +application operations beneath them. Standard-family declarations are root-only; +nesting a real family beneath another group reports an assembly error. Applications own their executable entry points, context creation, signals, stream selection, runtime construction, and final process exit. CommandKit @@ -71,9 +79,24 @@ retain control of their own output. [ADR 0005](../adr/0005-invocation-outcomes.m describes the outcome and delivery model. Use explicit instance construction and composable command registration, not -package-global or import-time registries. One definition supplies routing, -parsing, and help metadata. Duplicate paths and attempts to replace reserved -commands report errors rather than letting registration order select a winner. +package-global or import-time registries. Applications and integrations supply +the same captured command declarations through the core installation API. +Declaration factories capture metadata, bindings, and callback references eagerly; +construction errors remain attached for installation to report. Capture the +metadata collections needed to keep later edits to a source declaration from +changing a returned command. Application callback objects retain their ownership. +One definition supplies routing, parsing, and help metadata. + +Validate each installation batch before mutating the instance registry. A failed +construction yields no usable application; a failed later registration leaves the +existing registry intact. Separate successful registration calls are not one +transaction. Duplicate paths and attempts to replace reserved commands report +errors rather than letting registration order select a winner. + +Explicit absent-command declarations contribute no commands, help entries, or +namespace claims; attached errors are reported before skipping absence. An invalid +zero declaration is not absence. Integrations define their own empty-suite +semantics and retain invalid wiring errors even when capabilities are narrowed. Standard families are assembled from declared provider capabilities. Each family specifies its own resources and supported operations; shared verbs retain @@ -100,7 +123,31 @@ application-owned. Handlers receive typed input structs with explicit flag and operand bindings. Use presence-aware fields where omission matters; preserve explicitly supplied empty, false, and zero values independently of parser defaults. Context, streams, -and execution dependencies are separate from CLI inputs. +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. + +Omitted input and state factories supply the respective type's zero value, +including nil for pointers. Caller factories and callbacks retain responsibility +for objects they return or reference; do not promise arbitrary deep copies, +repair caller-created aliases, or silently allocate arbitrary pointer types. +Core-owned parsed collections stay independent where values are applied to +separate inputs. + +Provide typed binding composition through supported public core contracts when +integrations need to apply captured converted values to selected inputs. Preserve +binding identity and presence without exposing private setters or backend state. +Required-value checks apply to the selected binding subset. Missing required +operator input is a usage failure; invalid binding selection or destination is a +wiring failure with operational classification when detected during invocation. +Metadata defects detectable during assembly remain installation errors. Input +composition does not create a second parser or a raw-argument handler model. CommandKit keeps parsed values, collections, and presence from one invocation out of subsequent runs. Storage allocation and safe reuse are implementation choices; @@ -114,10 +161,20 @@ Keep input declarations available without application initialization. ## Public Facade And Dependency Direction -[ADR 0003](../adr/0003-public-facade.md) records the root `commandkit` facade and -internal adapter boundary. The root is the sole initial supported public package -and defines CommandKit's public named types. Additional public packages require a -deliberate decision based on a durable consumer responsibility. +[ADR 0010](../adr/0010-optional-integration-modules.md) scopes the root +`commandkit` facade to the core module and selects separate optional integration +modules with their own public package contracts. It partially supersedes +[ADR 0003](../adr/0003-public-facade.md), whose remaining facade and internal +adapter principles apply to the core and integrations alike. + +The core owns command declarations, registration, bindings, dispatch, help/version, +shared syntax, diagnostics, and outcomes. Each integration owns its standard +handlers, provider contracts, reports, adapters, and integration-specific public +types. Dependencies point from integrations toward the core; an integration may +depend on another integration when its responsibility requires that relationship. +Document those dependencies. Core public signatures, implementation imports, and +module requirements remain independent of optional integration libraries, +including dependencies introduced through tests, examples, or tools. Public handles retain private implementation state and expose explicitly selected methods. Any forwarding and conversions must preserve type identity, value @@ -125,9 +182,9 @@ ownership, callback lifetime, presence, and supported public error semantics. Do not alias public types to internal or backend types, anonymously embed those types to promote methods, or expose implementation bridge methods. -Straightforward implementation may live in the root package without expanding -its exports. Introduce internal packages, interfaces, and conversions where they -simplify implementation or protect the backend boundary. Package organization and +Straightforward implementation may live in an owning public package without +expanding its exports. Introduce internal packages, interfaces, and conversions +where they simplify implementation or protect the backend boundary. Package organization and the amount of internal layering follow implementation needs. Public signatures, fields, callbacks, constraints, and method sets must not expose @@ -138,9 +195,13 @@ retain their documented handling; this boundary does not require inspecting or transforming arbitrary application objects. Standard contracts such as `context.Context` and `io.Writer` remain appropriate. -Public types from integration libraries, such as ConfigKit and PromptKit, may be -selected as deliberate dependencies. Application-owned input types remain -application-owned. Do not expand exports merely to simplify internal assembly. +Upstream public types may be selected as deliberate dependencies in the +integrations that own them; that permission does not justify optional library +dependencies in the core. Core diagnostics use a CommandKit-owned severity type, +and integrations convert upstream diagnostics while preserving selected outcome +and error semantics. Application-owned input types remain application-owned. +Expose narrow core composition contracts for demonstrated integration needs, +without exporting private assembly or backend structures. ## Backend And Library Integration diff --git a/docs/roadmap/modules.md b/docs/roadmap/modules.md index 334df9b..7f7dc42 100644 --- a/docs/roadmap/modules.md +++ b/docs/roadmap/modules.md @@ -1,7 +1,8 @@ # Optional integration modules Status: module boundary accepted in ADR 0010; implementation planning remains -in progress and no module extraction has begun. The next minor ReleaseKit +in progress and no module extraction has begun. The consumer API is finalized +and its ADR/architecture-policy alignment is complete. The next minor ReleaseKit release will support individual module releases; CommandKit adoption is pending. ## Purpose and authority @@ -18,9 +19,10 @@ examples. Neither document describes these changes as implemented. [ADR 0010](../adr/0010-optional-integration-modules.md) owns the accepted module boundary and convenient registration principles; it partially supersedes [ADR 0003](../adr/0003-public-facade.md), whose remaining principles still apply. -Alignment of the [architecture policy](../policy/architecture.md) remains part of -the work below. GoDoc, the [CLI reference](../cli.md), and the -[consumer guide](../consumers/guide.md) describe the prototype baseline; they do +[ADR 0011](../adr/0011-captured-declarations-and-installation.md) records the +finalized registration and invocation-lifetime decisions. The +[architecture policy](../policy/architecture.md) is aligned with those decisions. +GoDoc, the [CLI reference](../cli.md), and the [consumer guide](../consumers/guide.md) describe the prototype baseline; they do not make its incidental API shapes compatibility requirements for this sprint. ## Organizing principle: design the final API @@ -139,8 +141,8 @@ shapes merely because they already exist. signatures and the [input/shared-state separation](registration-api.md#why-inputs-and-shared-state-have-separate-types). - Follow the selected [namespace lifetime and reconciliation requirements](registration-api.md#namespace-reconciliation-and-implementation-handoff). Built-in help/version remain reserved; optional integration roots are owned - when their real family is installed. Complete the identified durable-document - alignment before implementing that lifetime. + when their real family is installed. ADR 0011 and the architecture policy now + record that lifetime; implementation remains pending. - Core diagnostics use a small CommandKit-owned severity type. Upstream diagnostic conversion belongs in the integrations, preserving selected classification, delivery, and error semantics without copying ConfigKit's @@ -194,17 +196,18 @@ needed for CommandKit's source-only releases. ## Work sequence -### 1. Align policy and prepare the selected API for implementation +### 1. Prepare the selected API for implementation Completed: ADR 0010 is accepted and ADR 0003 is marked partially superseded, -with its decision text preserved. The partial status follows the explicitly -authorized exception to the documentation policy for this decision. +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 +intact. - Use the finalized [registration API](registration-api.md) and selected module layout as the implementation target before moving public symbols. -- Align the architecture policy with ADR 0010 and complete the registration - API document's namespace reconciliation. Review other ADRs for affected - ownership statements without reopening unrelated decisions. - 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 @@ -230,8 +233,8 @@ are concrete enough to implement without inventing a general plugin framework. supported interactions needed by those integrations. Preserve duplicate registration handling and standard-family ownership; audit these boundaries rather than assuming package relocation preserves them automatically. -- Design core outcomes, diagnostics, bindings, and command declarations as shared - contracts for the final API. Replace ConfigKit severity in core diagnostics +- Implement core outcomes, diagnostics, bindings, and command declarations using + the finalized API. Replace ConfigKit severity in core diagnostics with the selected CommandKit-owned type. Place report encoding and upstream diagnostic conversion with their owners. Remove redundant prototype state and helpers; avoid copying ConfigKit's data model merely to remove imports. diff --git a/docs/roadmap/registration-api.md b/docs/roadmap/registration-api.md index b7d9f56..c33a9c2 100644 --- a/docs/roadmap/registration-api.md +++ b/docs/roadmap/registration-api.md @@ -18,10 +18,12 @@ completed alternatives comparison is retained in Git history. [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) owns explicit registration, typed inputs, and command ownership. [ADR 0010](../adr/0010-optional-integration-modules.md) owns optional module -boundaries and convenient integration registration. The -[module roadmap](modules.md) tracks extraction work. Reconcile the namespace -lifetime decision below with the relevant ADR and architecture-policy wording -before implementation; this API design does not silently rewrite those records. +boundaries and convenient integration registration. +[ADR 0011](../adr/0011-captured-declarations-and-installation.md) records the +captured-declaration model, optional-family namespace lifetime, and separated +input/shared-state lifetimes. The [architecture policy](../policy/architecture.md) +reflects those boundaries. The [module roadmap](modules.md) tracks extraction +work; this API design remains a target rather than implemented behavior. Design for the best consumer API without preserving current implementation signatures or machinery. Existing code can supply evidence and reusable work, @@ -200,9 +202,9 @@ Scope-specific parsed values stay separate from shared acquisition state through the selected `Suite[I, S]`: `NewInput` initializes each selected scope's input, while `NewState` initializes `S` once for the selected inspection invocation. Providers receive both explicitly. Pointer inputs are independently initialized, -not shallow copies of a single pointer. The detailed lifetime table below makes -this change from the comparison's mixed context model explicit; it does not -require arbitrary deep copies or prohibit pointer inputs or shared pointer state. +not shallow copies of a single pointer. The detailed lifetime table below +spells out those calls without requiring arbitrary deep copies or prohibiting +pointer inputs or shared pointer state. ## Selected core declarations @@ -1208,19 +1210,18 @@ is installed. An absent/no-op family reserves nothing. A domain group using an uninstalled integration name is permitted, but blocks later installation of the same root with a collision. Root-only placement is independent of that lifetime. -This clarifies an ambiguity rather than assuming that earlier broad reservation -wording already specifies the same lifetime. The durable documents need deliberate -alignment before implementation: +The documentation alignment is complete: -| Owner | Required alignment before implementation | +| Owner | Recorded decision | | --- | --- | -| ADR 0001 | Clarify the reservation lifetime through the ADR change process if its accepted wording is interpreted as unconditional reservation | -| ADR 0010 | Retain core/integration dependency and convenient-composition boundaries; exact factories now return captured declarations | -| Architecture policy | State installed-family ownership uniformly for config and promptkit; align its public facade rules with ADR 0010 | -| Staged module implementation plan | Specify eager capture, error retention, neutral bindings, scope isolation, examples, and release adoption using this finalized API | +| [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 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 | +| [Module roadmap](modules.md) | Final API selected; documentation alignment completed; extraction and release adoption still pending | -A new or superseding ADR can record the lifetime clarification where needed; -accepted decision text is not revised silently. The [module roadmap](modules.md) -now references this finalized API. Policy/ADR reconciliation and a staged -implementation plan remain pending; this document does not claim that those -records are already aligned or authorize implementation. +A staged module implementation plan remains to be written from this finalized +API and the module roadmap. It should specify eager capture, error retention, +neutral bindings, scope isolation, maintained examples, and release adoption. +The documentation alignment neither implements these changes nor authorizes +implementation by itself.