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

@@ -1,8 +1,8 @@
# Registration and execution internals
Status: proposed internal design for the finalized consumer API; no implementation
has begun. Runnable-command children and scope-error attachment are selected API
additions to incorporate into the registration API document. Both composition
Status: finalized internal design; no implementation has begun. Runnable-command
children, scope-error attachment, and the unused-binding validation resolution are
incorporated into the [registration API](registration-api.md). Both composition
questions below are resolved; the staged implementation plan remains to be written.
## Purpose and authority
@@ -18,8 +18,9 @@ capture, installation, namespace, and input/state decisions.
[ADR 0010](../adr/0010-optional-integration-modules.md) owns module boundaries, and
the [architecture policy](../policy/architecture.md) governs implementation.
The [module roadmap](modules.md) owns the broader extraction and release work.
This document proposes internal mechanics and identifies gaps; it neither changes
the finalized API silently nor establishes additional consumer guarantees.
This document defines selected internal mechanics and records the resolved
composition decisions. Public declarations and consumer examples belong in the
registration API document; these changes remain unimplemented.
The prototype has no compatibility priority. Replace its parallel paths and
bookkeeping where they obstruct the selected design. Preserve deliberately
@@ -46,7 +47,7 @@ opportunities and structural risks, not measured performance regressions.
| `bridgeTree` in [parser.go](../../parser.go) caches neutral metadata; [internal/cobra/parse.go](../../internal/cobra/parse.go) creates a session per invocation | The useful metadata/session split should survive the refactor | Share captured metadata, refresh it after registry changes, and keep mutable backend values invocation-local |
| `commandAt` traverses names again after the adapter has already resolved a command | Duplicate route lookup can become another source of dispatch disagreement | Return a private command key from the adapter and resolve the captured runner directly |
## Proposed internal ownership
## Selected internal ownership
Keep most cohesive core machinery private in the root package. A facade does not
require forwarding-only files or duplicate representations for every public type.
@@ -58,7 +59,7 @@ Use an internal package where it protects an actual dependency boundary.
| Core bindings | Binding identity, typed conversion, presence/defaults, converted-value application, binding metadata validation | Scope names, ConfigKit/PromptKit types, application object cloning |
| Core registry | Validate/stage/commit installation batches and invalidate derived metadata | Integration-specific installed flags, command factories, report rendering |
| Core execution | Invoke the selected compiled runner, share the current presentation context, normalize/present outcomes | Application startup, provider schemas, process exit |
| `internal/commandmeta` (proposed) | Narrow backend-neutral routing/help DTOs, private command keys, parse result shapes | Public contracts, typed handlers, registry policy, upstream library types |
| `internal/commandmeta` (planned) | Narrow backend-neutral routing/help DTOs, private command keys, parse result shapes | Public contracts, typed handlers, registry policy, upstream library types |
| `internal/cobra` | Translate neutral metadata into one invocation session; route, collect raw occurrences, render help | Typed value conversion, declaration validation, family ownership, acquisitions |
| `ckconfig` private implementation | Capture scopes, compile applicable selectors, prepare selected inputs, acquire views, perform each configuration operation | Core registry state or private binding access |
| `ckprompt` private implementation | Capture definition providers, adapt engine inspection, prepare definition input/state, render definition reports | A second dispatcher/parser or configuration-suite installation |
@@ -164,9 +165,8 @@ Keep payload and children independent in the private model. Do not introduce a
new prohibition on runnable commands with children merely because separate leaf
and group constructors are convenient.
The selected public addition is `Children []Command` on `CommandSpec[I]`. The
registration API currently has no way to combine a handler with children; the
private model alone cannot expose the behavior described by
The selected public addition is [children on runnable commands](registration-api.md#runnable-parents-and-captured-children)
through `CommandSpec.Children`. It exposes the behavior described by
[ADR 0006](../adr/0006-command-grammar.md). Capture the child-handle slice using the
same ownership and immediate composition checks as `Group`, and enforce the same
placement rules at installation. `Group` remains a convenience for non-runnable
@@ -434,8 +434,8 @@ metadata-only, while the original invalid loader must remain an error. Wrapping
the nil loader in a non-nil acquisition closure would incorrectly defer it to
invocation. A core `WithError` only accepts a `Command`, not a scope.
**Selected:** add the integration-owned operation
`ckconfig.WithScopeError[I, S](scope Scope[I, S], err error) Scope[I, S]`.
**Selected:** use the integration-owned [retained scope-error operation](registration-api.md#retained-scope-errors),
`ckconfig.WithScopeError`, declared in the registration API document.
It returns a scope retaining the original issue, preserving supported error
identity. Repeated attachments preserve earlier causes and leave the original
scope unchanged; a nil error preserves the scope. Retained causes survive scope