From ff1b1b1a3eeb85971b8d57db45b539dbf31bcbd1 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 7 Oct 2026 02:47:46 +0000 Subject: [PATCH] Align architecture policy with revised ADRs --- docs/policy/architecture.md | 69 ++++++++++++++++++++++++++----------- 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 1baf9cf..3ef3826 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-10-06 +**Last Updated**: 2026-10-07 **Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) @@ -59,6 +59,17 @@ returns invocation outcomes and must not terminate the process. Its common mechanics apply to custom commands without taking ownership of their domain semantics or success-report formats. +CommandKit's grammar applies to commands using its dispatcher and binding APIs. +Its documentation recommends the same grammar and vocabulary for application-owned +commands, including those outside its dispatcher, under +[ADR 0006](../adr/0006-command-grammar.md). + +CommandKit preserves application-supplied outcome classifications and supported +error identity. It assigns responsibility for its diagnostics, avoids duplicate +presentation through its own paths, and reports write failures. Caller callbacks +retain control of their own output. [ADR 0005](../adr/0005-invocation-outcomes.md) +describes the outcome and delivery model. + Use explicit instance construction and composable command registration, not package-global or import-time registries. One definition supplies routing, parsing, and help metadata. Duplicate paths and attempts to replace reserved @@ -91,10 +102,11 @@ Use presence-aware fields where omission matters; preserve explicitly supplied empty, false, and zero values independently of parser defaults. Context, streams, and execution dependencies are separate from CLI inputs. -CommandKit creates fresh input and backend command/flag state per invocation, -keeping its parsed values, collections, and presence out of subsequent runs. -Caller-owned closures and runtime state retain their own lifecycle. Concurrent -dispatch is a separate contract. +CommandKit keeps parsed values, collections, and presence from one invocation out +of subsequent runs. Storage allocation and safe reuse are implementation choices; +rebuilding backend state is the initial strategy under +[ADR 0002](../adr/0002-cobra-backend.md). Caller-owned closures and runtime state +retain their own lifecycle. Concurrent dispatch is a separate contract. Applications may interpret parsed domain values and provide domain value parsers through the binding system. Raw-argument parsing is not the primary handler model. @@ -108,22 +120,27 @@ and defines CommandKit's public named types. Additional public packages require deliberate decision based on a durable consumer responsibility. Public handles retain private implementation state and expose explicitly selected -methods. Use explicit forwarding and conversions that preserve type identity, -value ownership, callback lifetime, presence, and public error semantics. Do not -alias or anonymously embed implementation types into the public API, promote -internal methods, or expose backend bridge methods. +methods. Any forwarding and conversions must preserve type identity, value +ownership, callback lifetime, presence, and supported public error semantics. Do +not alias public types to internal or backend types, anonymously embed those types +to promote methods, or expose implementation bridge methods. -Implementation belongs under Go's `internal/` boundary. Dependencies run from the -facade inward; internal production packages do not import the root. Shared -implementation contracts belong inside the internal boundary. Public signatures, -fields, callbacks, constraints, and method sets must not expose internal or -Cobra/pflag types. Backend objects must not escape through loosely typed values -or returned errors. +Straightforward implementation may live in the root package without expanding +its exports. Introduce internal packages, interfaces, and conversions where they +simplify implementation or protect the backend boundary. Package organization and +the amount of internal layering follow implementation needs. + +Public signatures, fields, callbacks, constraints, and method sets must not expose +internal or Cobra/pflag types. CommandKit does not expose its internal backend +objects or backend-specific syntax errors through its public API, including +through loosely typed values or returned errors. Caller-supplied values and errors +retain their documented handling; this boundary does not require inspecting or +transforming arbitrary application objects. Standard contracts such as `context.Context` and `io.Writer` remain appropriate. -Other public dependency types require deliberate API selection. Application-owned -input types remain application-owned. Do not expand exports merely to simplify -internal assembly. +Public types from integration libraries, such as ConfigKit and PromptKit, may be +selected as deliberate dependencies. Application-owned input types remain +application-owned. Do not expand exports merely to simplify internal assembly. ## Backend And Library Integration @@ -145,12 +162,24 @@ inspection providers. CommandKit exposes those capabilities without implementing a parallel configuration or prompt engine. Use independently released public contracts; do not import sibling internal packages or depend on adjacent checkouts. +Use narrow integration contracts, reusing upstream public types where useful and +introducing CommandKit-owned abstractions where they simplify integration. +Concrete integration needs guide provider representations under +[ADR 0009](../adr/0009-configuration-scopes.md). + +Native report writers and safe inspection data preserve owning-library semantics. +Loading all selected views before report output is a `config show` decision under +[ADR 0007](../adr/0007-native-yaml-reports.md); other inspection operations define +their own output timing. Semantic comparison uses supported safe snapshots and +reports sensitivity gaps under [ADR 0008](../adr/0008-semantic-configuration-diff.md). + ## Scope And Non-goals Keep packages and abstractions proportionate to cohesive responsibilities. The library is not a general application runtime, dependency-injection framework, -logging system, hosted service, or standalone application. It does not prescribe -domain execution vocabulary outside the standard suite. +logging system, hosted service, or standalone application. Shared vocabulary is +recommended for application-owned commands; their names and domain behavior +remain application choices. The [CLI roadmap](../roadmap/01-cli-plan.md) distinguishes accepted operator choices from remaining command and grammar proposals. Backend defaults and