base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finalize the registration API roadmap

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-10 15:44:53 +00:00
parent 892186d4ac
commit 8f86852456
3 changed files with 57 additions and 964 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/roadmap/modules.md
View File

@@ -12,8 +12,9 @@ should acquire neither ConfigKit nor PromptKit through CommandKit's package or
module dependencies. ConfigKit-only consumers should not acquire PromptKit.
This roadmap records the targeted end state, selected module layout, and
migration work. Recommendations under [Open Decisions](#open-decisions) remain
proposals. It does not describe these changes as implemented.
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.
[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.
@@ -130,11 +131,16 @@ shapes merely because they already exist.
### Selected API and release principles
- Design convenient integration registration around representative consumers.
Reuse public command/group registration when it fits the final design. Add a
narrow core capability only where a concrete responsibility requires it; do
not introduce a general family framework or preserve private bookkeeping for
its own sake. Exact signatures remain implementation-planning work.
- Use the finalized [uniform registration API](registration-api.md#declaration-and-installation).
Applications and integrations produce captured core command declarations and
install them through core `New` or `App.Register`; construction errors are
retained for installation-time validation. Integration factories provide
complete families and focused conveniences. The API document owns exact
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.
- 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
@@ -188,25 +194,27 @@ needed for CommandKit's source-only releases.
## Work sequence
### 1. Align policy and settle implementation boundaries
### 1. Align policy and 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.
- Resolve the remaining choices under Open Decisions before moving public
symbols, using the selected module paths and package names above.
- Align the architecture policy with ADR 0010 and review other
ADRs for affected ownership statements without reopening unrelated decisions.
- 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. Select final exports and ownership from consumer
needs; no compatibility mapping for the unpublished prototype is required.
- Sketch three representative consumers: core only, ConfigKit only, and both
libraries. Confirm that combined configuration scopes remain straightforward
and that registration meets ADR 0010's convenience principle without replacing
removed boilerplate with new plumbing. Use these examples to evaluate the
registration API; no fixed call count or particular options pattern is selected.
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.
- 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;
port them into maintained examples as implementation lands.
- Prepare a staged implementation plan from this roadmap and the finalized API,
preserving the unreleased-prototype organizing principle above.
Completion: the dependency direction, final API, and registration approach
are concrete enough to implement without inventing a general plugin framework.
@@ -307,22 +315,3 @@ change after extraction unless an implementation dependency justifies combining
them. Catalogs and requirement discovery are subsequent integration features.
Semantic comparison retains the upstream-contract dependency recorded in
[deferred work](deferred.md). None is needed to demonstrate module isolation.
## Open Decisions
### Exact registration API
The design principle is selected: convenient registration through the simplest
coherent public core contracts, without preserving the prototype. Exact
signatures and any additional core capability remain to be settled through the
three representative consumer sketches and an ownership/collision review.
**Recommendation:** integrations construct their standard groups and install them
through ordinary public registration, adding a narrow capability only if the
selected ownership or atomicity behavior cannot be expressed coherently. Remove
redundant private flags and checks rather than reproducing them publicly.
**Alternative:** an explicit public family declaration and installation API can
represent ownership and collision handling if command groups cannot adequately
express those responsibilities. It adds a lasting abstraction, so select it only
for a demonstrated consumer or core responsibility, not to imitate current state.