Link the finalized registration backend design
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user