Link the finalized registration backend design

This commit is contained in:
2026-10-10 23:44:28 +00:00
parent 336d489727
commit bb849ff3e1
3 changed files with 122 additions and 37 deletions

View File

@@ -2,8 +2,10 @@
Status: module boundary accepted in ADR 0010; implementation planning remains
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.
and its ADR/architecture-policy alignment is complete. The internal registration
and execution design is finalized, including both composition-question resolutions.
The next minor ReleaseKit release will support individual module releases;
CommandKit adoption is pending.
## Purpose and authority
@@ -15,7 +17,9 @@ module dependencies. ConfigKit-only consumers should not acquire PromptKit.
This roadmap records the targeted end state, selected module layout, and
migration work. The finalized [registration API](registration-api.md) owns the
selected declarations, installation semantics, and representative consumer
examples. Neither document describes these changes as implemented.
examples. The finalized [registration backend design](registration-backend.md)
owns internal structure, shared installation/execution mechanics, and the resolved
composition decisions. These documents describe the implementation target.
[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.
@@ -143,6 +147,16 @@ shapes merely because they already exist.
Built-in help/version remain reserved; optional integration roots are owned
when their real family is installed. ADR 0011 and the architecture policy now
record that lifetime; implementation remains pending.
- Use the finalized [internal registration and execution design](registration-backend.md).
Built-ins, application commands, and integration families share one
[installation path](registration-backend.md#one-installation-path-for-every-command)
and typed compiler. Captured metadata and invocation state have distinct owners;
the backend document defines the capture, binding, routing, and presentation
mechanics without adding another integration installation API.
- Apply the resolved [unused-binding validation boundary](registration-backend.md#resolved-unused-binding-validation-oq-1)
and [scope-error handoff](registration-backend.md#resolved-scope-error-handoff-oq-2).
The registration API incorporates the selected runnable-parent and scope-error
attachment declarations. No absence-validation overload is selected.
- 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
@@ -205,10 +219,13 @@ 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.
intact. The internal backend design is also finalized; its runnable-child,
scope-error attachment, and unused-binding decisions are incorporated into the
API target. Both composition questions are resolved.
- Use the finalized [registration API](registration-api.md) and selected module
layout as the implementation target before moving public symbols.
layout together with the [backend design](registration-backend.md) as the
implementation target before moving public symbols.
- 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
@@ -218,7 +235,8 @@ intact.
core only, ConfigKit only, and both libraries. They define the target wiring,
including combined configuration scopes and independent definition inspection;
port them into maintained examples as implementation lands.
- Prepare a staged implementation plan from this roadmap and the finalized API,
- Prepare a staged implementation plan from this roadmap, the finalized API,
and the finalized [backend design](registration-backend.md),
preserving the unreleased-prototype organizing principle above.
Completion: the dependency direction, final API, and registration approach
@@ -227,14 +245,21 @@ are concrete enough to implement without inventing a general plugin framework.
### 2. Extract the integrations and isolate the core
- Establish the selected module layout, preserving the existing root import
path for the core.
path for the core. Use the backend document's [internal ownership boundaries](registration-backend.md#selected-internal-ownership)
when organizing private declarations, bindings, registry, execution, neutral
metadata, and the Cobra adapter.
- Move configuration declarations, registration, handlers, reports, and
ConfigKit adapters together. Move PromptKit declarations, handlers, reports,
and its configuration-scope adapter into the PromptKit integration.
- Replace access to root-private registry state and helpers with the smallest
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.
- Use the shared installer and typed compiler for every command source, including
built-in help/version. Replace direct registry writes, duplicated family
collision checks, and integration-specific core state with the selected
captured-declaration path. Integration factories use public core contracts,
and `ckprompt` uses the selected scope-error attachment contract in `ckconfig`.
- Follow the backend document's [integration preparation design](registration-backend.md#integration-preparation-without-parallel-execution-frameworks)
for selected inputs and shared state. Preserve each operation's acquisition
and report timing while removing repeated scope selection and mixed-context
projection.
- 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