commandkit/docs/roadmap/registration-proposal.md

# Unified command registration proposal

Status: direction agreed; exact API declarations and complete consumer examples
await the next authoring and review pass. No implementation is authorized by this
document alone.

## Purpose and authority

Applications and integrations construct captured command declarations and install
them through the same core API. Installation validates each batch before registry
mutation. Integrations supply complete standard families and focused conveniences
while retaining ownership of their provider semantics.

This document records the selected direction following the
[registration alternatives](registration-alternatives.md). It replaces that
comparison's recommendation of Option A with a refinement of Option C: capture
declarations and any construction errors eagerly, then report errors at
installation. The comparison remains background, not the selected API proposal.

[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 proposal does not silently rewrite those records.

Design for the best consumer API without preserving current implementation
signatures or machinery. Existing code can supply evidence and reusable work,
but does not constrain the design. This is future API design, not documentation
of implemented behavior.

## Selected consumer model

A consumer can use only the core or add any supported combination of integrations.
Every command reaches the application through core `New` or `Register`, regardless
of whether an application or integration declared it. There is no mandatory
integration interface, application-wide generic input type, or separate
integration installation lifecycle.

The core remains independent of integration modules and their upstream libraries.
Integrations may depend on one another as documented. Such module dependencies
do not install commands or acquire providers. The selected modules remain
`CommandKit`, `CommandKit/integrations/ckconfig`, and
`CommandKit/integrations/ckprompt`, under the existing repository module prefix.

Each application command retains its own typed input and domain handler.
Integration suites retain their own typed context and provider declarations.
Both produce the same opaque core `Command` handle. Consumers need not construct
individual standard handlers, duplicate integration adapters, or expose backend
objects to assemble an application.

## Declaration and installation

### One declaration model

A `Command` is a captured declaration, not proof that the declaration is valid
or installed. Ordinary command, group, scope, and suite adapter construction
does not require a separate error check at each call site.

The intended shape is illustrated below. Names of existing concepts aid discussion;
the complete signatures and fields still need the example pass.

```go
// Core package:
func NewCommand[I any](spec CommandSpec[I]) Command
func Group(name, summary string, children ...Command) Command

func New(identity Identity, commands ...Command) (*App, error)
func (app *App) Register(commands ...Command) error
```

The initial integrations expose complete-family factories using their own suite
types:

```go
// In each initial integration package; Suite belongs to that integration:
func Command[C any](suite Suite[C]) commandkit.Command
```

Future integrations can accept declarations suited to their resources while
returning the same core `Command`; the core does not prescribe a universal suite.

Application-owned command factories follow the same declaration pattern.
Application helpers that genuinely perform other fallible work may still return
errors; the design does not suppress those errors or require all application
functions to be infallible.

### Eager capture, errors reported at installation

Factories capture declaration metadata and callback references and assemble
neutral command descriptions immediately. Validation that can already be done
may occur then, but its errors remain attached to the declaration for installation
to report. Internally fallible assembly can capture an error without returning it
to the consumer at every construction step.

The core needs a small supported public mechanism for integrations to carry
construction errors in opaque declarations. Its exact signature remains to be
specified. Do not substitute an untyped integration payload, root-private access,
or a general preparation callback. The proposed `DeferredGroup` lifecycle from
the comparison is not selected.

`New` and `Register` report retained declaration errors and validate the batch,
including bindings, root placement, and collisions, before registry mutation.
A failed `New` yields no usable application. A failed `Register` leaves the
existing registry intact. No rollback guarantee spans separate registration calls.

Declaration construction, installation, help, and version do not invoke provider
acquisition or invocation input/context factories. They do not validate files,
credentials, or application configuration. Invalid wiring fails at installation;
an upstream error returned by a valid provider remains an invocation result.

An originally nil loader remains invalid wiring even if an adapter would wrap
it in a non-nil function. Integration declarations retain enough information to
detect this. An intentionally absent capability is distinct from an invalid
adapter. Errors identify the affected command family and relevant scope, binding,
or capability and preserve supported wrapped error identity; exact prose is not
selected here.

## Integration composition and conveniences

Configuration scopes are composed before installation into one configuration
suite. Application and engine scopes can share that suite. Named definition
inspection remains independently selectable: installing an engine configuration
scope does not automatically install definition commands, or vice versa.

Keep provider declarations integration-owned. Configuration supports ConfigKit
for now; the core does not acquire a universal configuration or suite interface.
The PromptKit integration can use the ConfigKit integration's selection and scope
contracts through its selected dependency.

Provide the focused `ckconfig.AppCommand(load)` convenience for a context-free
application configuration loader. It declares the standard `app` scope, with a
default description, through the same declaration model as the full suite. It
does not require an unused context argument or `Suite[struct{}]` at the consumer
call site. A loader still receives `context.Context` and configuration selection.
Use the full suite when adding scopes, selectors, custom state, or other metadata.

Do not initially expose integration-specific `Register` or `RegisterApp`
functions alongside declaration factories. Core registration is the installation
path for all consumers. Additional conveniences should address demonstrated
consumer needs rather than mirror every underlying constructor automatically.

## Namespaces and empty declarations

Help and version are reserved by core construction. Optional families claim
their complete root namespace when installed. Before installation, a domain group
may occupy that name; subsequent integration installation then fails with a
collision. The reverse order also rejects a collision. Neither order replaces or
merges an existing group.

Standard-family declarations carry enforceable root-only placement metadata.
Installing them beneath an ordinary group is an assembly error. Use the same
`Command` type with a narrow placement declaration mechanism, whose final shape
remains to be specified. It represents placement, not authentication of the
declaring package. Installed standard families cannot be extended with private
application operations or have their handlers replaced.

The selected empty-suite behavior is:

| Declaration | Installation result |
| --- | --- |
| Configuration suite with no scopes | Declaration error |
| Named configuration scopes with no inspection operations | Install scope discovery with the actual empty capability sets |
| Configuration scopes with supplied operations | Install discovery and supported operations |
| Otherwise valid definition suite with no capabilities | Successful no-op; no namespace or help entry |
| Adapter with a nil loader | Declaration error, even when selected capabilities otherwise appear empty |

Use an explicit `commandkit.NoCommand()` declaration for intentional absence.
Core installation skips it. A zero-value `Command` remains invalid. Integration
factories validate or retain wiring errors before representing an empty family
as a no-op; absence must not swallow errors. A no-op does not reserve a namespace.

## Capture, reuse, and invocation inputs

Capture scope metadata, capability lists, selector applicability, bindings, and
callback references when declarations are constructed. Copy the declaration
collections needed for those semantics. Later edits to the source suite or its
metadata slices do not change a returned command declaration.

Declarations may be installed in multiple applications. Registries maintain
independent installed state, and invocations have independent parsed state.
Application callback closures and objects they reference remain application-owned
and may deliberately be shared. These choices do not promise arbitrary deep
copies or concurrent dispatch.

Use the same typed, presence-aware binding primitives for application commands
and integration inputs. Configuration selectors additionally declare scope
applicability; definition selectors need no configuration-specific wrapper.
Explicit empty, false, and zero values remain distinguishable from omission.

An omitted invocation input/context factory supplies the zero value of its type.
For pointer types that is nil; do not silently allocate arbitrary pointer state
or prohibit a loader that intentionally accepts nil. Applications supply a factory
when initialized state is needed. A supplied factory returning nil retains its
application-owned meaning.

Scope-specific parsed values must stay separate from shared acquisition state.
The value-shaped input with a shared cache pointer in the comparison illustrates
one suitable arrangement. Shallow-copying a shared pointer input and mutating its
selector fields is not sufficient to isolate scope values. The next example pass
must specify this interaction without inventing deep-copy guarantees, banning
pointer contexts, or silently changing factory lifetimes.

## Next example and review pass

The next step is to complete this proposal's declarations and examples, then
review them before implementation. Focus on the following work:

1. Show a complete core-only registration example with a typed application
   command and group. Ordinary declaration construction should follow the same
   error-reporting pattern as integration factories, rather than hiding an older
   pattern in a fallible helper.
2. Show context-free application configuration through `AppCommand`, including
   the loader signature and absence of placeholder state or forwarding wrappers.
3. Show full configuration-scope and definition-suite assembly beside application
   commands, with all registration-related setup visible. Demonstrate independent
   capability selection without importing an integration into the core.
4. Specify the supported mechanisms for retained declaration errors and root-only
   placement, plus their interaction with ordinary groups and explicit no-ops.
   Show how integration-owned validation feeds core installation without a public
   preparation callback or private-state access.
5. Complete the typed selector/override example, including input initialization,
   scope filtering, explicit presence, and shared cache lifetime. Explain how
   pointer-shaped inputs preserve scope isolation, and align input factory
   semantics with application commands.
6. Include focused examples or expected outcomes for invalid wiring, collisions,
   nesting a root-only group, empty suites, declaration reuse, and edits to source
   metadata after construction. These are design checks, not a mandate for a new
   exhaustive test matrix.
7. Reconcile the selected namespace lifetime with the ADR and architecture policy,
   and update the module implementation plan once this proposal's examples and
   remaining API details have passed review.

The uniform declaration-and-installation pattern is decided. Exact supporting
API names and the unresolved input-isolation mechanics above remain work for the
next pass. This step adds no code, new inspection operations, or release-cadence
decision.