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

Document application-owned alias contracts

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-19 19:59:41 +00:00
parent 666c006a89
commit 333a630cf1
15 changed files with 270 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/policy/architecture.md
View File

@@ -83,18 +83,24 @@ describes the outcome and delivery model.
Use explicit instance construction and composable command registration, not
package-global or import-time registries. Applications and integrations supply
the same captured command declarations through the core installation API.
captured canonical command declarations through the core installation API.
Declaration factories capture metadata, bindings, and callback references eagerly;
construction errors remain attached for installation to report. Capture the
metadata collections needed to keep later edits to a source declaration from
changing a returned command. Application callback objects retain their ownership.
One definition supplies routing, parsing, and help metadata.
Canonical command declarations own handlers, parsing metadata, and help
metadata. Applications may provide separate routing rules in the same
installation batch; these rules resolve invocations to canonical commands and
do not add command nodes, handlers, or flags.
Validate each installation batch before mutating the instance registry. A failed
construction yields no usable application; a failed later registration leaves the
existing registry intact. Separate successful registration calls are not one
transaction. Duplicate paths and attempts to replace reserved commands report
errors rather than letting registration order select a winner.
transaction. Duplicate canonical paths and attempts to replace reserved commands
report errors rather than letting registration order select a winner. Identical
routing rules are idempotent; competing targets for the same source and scope
report an error. Command-scoped flag routing refers to an exact canonical
command path.
Explicit absent-command declarations contribute no commands, help entries, or
namespace claims; attached errors are reported before skipping absence. An invalid