Refresh native configuration, CLI, and LLM internal guides

This commit is contained in:
2026-11-22 06:41:22 +00:00
parent 2c27695df9
commit 5db09d0203
4 changed files with 428 additions and 642 deletions

View File

@@ -1,204 +1,157 @@
# CLI Internals
This document describes **internal/cli**, Notarius's production composition
root. The [CLI reference](../cli.md) owns command syntax and exit statuses;
[Configuration](../config.md) owns configuration values; and
[Operations](../operations.md) owns filesystem layout, recovery, and operator
procedures.
`internal/cli` is the production composition root. [CLI Reference](../cli.md)
owns syntax, reports, and outcome codes; [Configuration](../config.md) owns
settings; [Operations](../operations.md) owns physical state and recovery.
This guide explains declaration, loading, and orchestration owners, not another
public command manual.
## Inputs, Outputs, And Boundaries
## Native Application Construction
The CLI accepts process arguments, standard streams, and injectable options
used by tests and embedding code. It writes command results to the supplied
streams and returns a process exit status. For a run, it also creates the
production catalog and runtime collaborators, hands a prepared pipeline and
source bytes to the framework, and places the logical files returned by the
runner.
[NewApplication](../../internal/cli/application.go) returns a native
`*commandkit.App` from application identity and injectable options. Construction
declares commands without configuration discovery, engine creation, provider
calls, or run-storage allocation. The executable supplies build identity;
`RunWithOptions` is a convenience execution entry point, not a manual dispatcher.
It is the only boundary allowed to compose concrete registries, LLM clients,
cache/checkpoint collaborators, debug recorders, and physical output paths.
Pipeline modules receive interfaces and request data rather than CLI streams or
filesystem roots. The [Architecture](../policy/architecture.md) defines this
composition-root boundary; [Pipeline Internals](pipeline.md) owns resolution,
preparation, and runner mechanics after their inputs are supplied.
The constructor wires:
## Dispatch And Configuration Handoff
- native help/version and installed shell completion;
- application pipeline declarations and a native run alias;
- ckconfig whole-application and focused PromptKit scopes, sharing one loader;
- ckprompt resource/requirements inspection, concrete request validation,
prepared preview, namespace selection, and explicit smoke testing.
The root dispatcher handles help, version reporting, configuration validation,
effective-configuration inspection, explanation inspection, pipeline listing,
and a pipeline run. Version reporting resolves build
information through `internal/buildinfo` before production composition, so the
diagnostic remains available without configuration or runtime collaborators.
The public syntax, streams, exit classes, and version semantics are defined by
the [CLI reference](../cli.md). Other root commands normalize injectable
options before dispatch so that a missing production dependency fails as a
command error rather than reaching execution.
ckconfig adapters use the original application result and focused native subtree
view. ckprompt uses an engine loader through its standard builders rather than
application-owned copies of inspection DTOs. Ordinary resource inspection does
not become request preparation or an implicit probe. The
[native CLI reference][native-cli] owns parser/report mechanics.
Commands that need configuration use one shared ConfigKit-backed loader. The
CLI constructs an exclusive file source for an explicit flag or environment
selection, or a native required search source, then passes it to `LoadSource`
with the requested overlay and only explicit configuration-valued run overrides.
It receives a **LoadedConfig** and uses its retained main-source path for
invocation provenance without a second search. The
configured discovery and precedence contract is in
[Configuration](../config.md), while the loading and resolution mechanics are
in [Configuration Internals](configuration.md).
## Invocation-Local Loading
`config effective` and `config explain` render the loaded ConfigKit view by
default and do not resolve pipelines or construct providers. With explicit
`--scope promptkit`, they construct the PromptKit inspection engine from the
same captured source groups used by execution. Effective output is PromptKit's
redacted YAML; explanation output shows its source history. `config profile`
uses that engine to emit one neutral Notarius-owned JSON summary for the exact
requested profile ID. These inspection commands load no run pipeline, prepare
no request, resolve no credential value, and make no provider call. Ordinary
prompt and provider-parameter content is not generally secret-free even though
credential-shaped provider parameter keys are redacted.
[nativeLoaders](../../internal/cli/configkit_load.go) belongs to one invocation.
It selects the main source and assembles one layered ConfigKit application
result. Engine construction calls `promptkit.NewFromConfig` on that result,
with runtime-only client options; it does not load YAML again.
Configuration validation without a selected pipeline checks structural
configuration only. Validation with a selected pipeline also builds the
effective catalog, resolves the pipeline, and verifies every explicit effective
PromptKit profile. Selected LLM-backed input, chunk, lane, output, and validator
profiles are inspected against the configured PromptKit source and backend
registrations without preparing a request or performing generation. Engine
construction validates effective prompt definitions and captures message content;
an unknown or invalid profile fails before pipeline preparation.
Credential availability remains an execution-time concern. Pipeline listing
validates configuration before returning normalized, sorted identifiers.
The retained selection includes supplied-value state, overlay, and override
values. Repeated identical selections share a result/engine, while distinct
comparison selections cannot be memoized into one side. There is no
process-global loader cache. The selected main's native context anchors companion
imports; source edits do not mutate an existing captured engine.
## Production Composition
[Configuration Internals](configuration.md) owns definition, normalization,
origins, and conversion. Shared loaders allocate no output/cache/debug data.
The production composition helper allocates every framework registry and the
prompt-asset registry, then registers the generic, Seriatim, and D&D module
families in that order. The resulting registries provide both the module
catalog used for resolution and the concrete constructors used for preparation.
Tests may provide a catalog or registries instead; production code must not
silently merge an injected partial catalog with production registrations.
## Catalog And Preflight Boundaries
The production LLM factory builds one PromptKit-backed client from the native
source groups assembled from PromptKit catalogs, registered application prompt
and fallback assets, the optional operator file or recursively selected
directory, and the optional local backend registration. The same construction
path serves runtime, preflight, and configuration inspection. It attaches the
profile-provenance recorder, captures one immutable PromptKit configuration
identity, creates one scheduler from the effective global LLM limit, and wraps
the client before it reaches modules. Registration and LLM construction errors
are returned before a pipeline is prepared. Configuration fields remain in
[Configuration](../config.md#promptkit-profiles); source ownership, capture,
identity, and adapter mechanics remain in [LLM Runtime](llm.md).
[catalog.go](../../internal/cli/catalog.go) composes generic, Seriatim, and D&D
registrars into typed registries, codecs, evidence projectors, and validator
defaults. Registration does not build an asset/schema registry or an LLM service.
Injected registries/catalogs are alternative sources, not implicitly augmented
with production entries.
The factory also accepts `LLMRuntimeOverrides`, whose reasoning pointer
preserves inherit, replace, and clear states across the composition boundary.
Run orchestration constructs this value from the mutually exclusive
`--reasoning-effort` and `--clear-reasoning-effort` controls. Absence preserves
a nil pointer, replacement is trimmed, and clear uses a non-nil empty string.
The same override reaches the one shared production client, checkpoint
identity, and debug invocation metadata. Persistent reasoning configuration
remains owned by PromptKit profiles; Notarius configuration has no reasoning
field.
[pipeline_commands.go](../../internal/cli/pipeline_commands.go) separates:
- listing: enumerate captured configured IDs without a catalog/engine;
- showing: domain resolution and composition description, without profile expansion;
- validating: domain resolution plus known-resource preflight, supplying the
same captured engine only when model roles require it.
[Preflight](../../internal/preflight/preflight.go) accepts collaborators/data;
it does not load configuration, register/construct modules, read execution
inputs, render CLI reports, or allocate state. Partial profiles pass native
inspection, with concrete request readiness deferred until preparation.
## Run Inputs And Native Overrides
[run_input.go](../../internal/cli/run_input.go) binds typed application inputs
and repeated literal selections. [execution_overrides.go](../../internal/cli/execution_overrides.go)
uses reusable ckprompt resource/execution inputs, preserving omission versus
explicit empty/false/zero. Only profile/session and execution controls needed
by pipeline runs are selected; prompt inputs stay module-owned.
The resolved run-wide profile selection reaches every LLM-backed role. Native
execution overrides travel through operation requests to producers, validators,
and continuation, without mutating loaded settings. The
[public reference](../cli.md#run-wide-llm-overrides) owns exact spellings/semantics.
Reference selectors are expanded at the CLI boundary using registered target
specifications. Pipeline/lane actions become exact binding changes after
specificity/conflict handling. Generic resolution receives exact reference
bindings/unbinds, not CLI selector grammar. External/generated conflicts and
required-slot/type checks remain with domain resolution; materialization follows.
[session.go](../../internal/cli/session.go) resolves the effective session from
explicit supplied input or the input-module/raw-byte policy before runner work.
Framework/model code transports it rather than deriving another session.
## Run Orchestration
After parsing and validating a run invocation, the CLI performs this ordered
handoff:
[pipeline_run.go](../../internal/cli/pipeline_run.go) performs the ordered handoff:
1. load and validate configuration with ConfigKit command overrides;
2. create and validate a safe run identity, then allocate a debug bundle only
when requested;
3. build the effective catalog, resolve requested reference changes, resolve
the effective pipeline, and inspect its explicit effective PromptKit
profiles;
4. materialize external or generated references and record redacted invocation
and resolution provenance when debug capture is enabled;
5. construct registries, the scheduled LLM client, and prepared modules;
6. read the source input once, resolve its effective session from the explicit
override or resolved input module and raw bytes, then construct requested
checkpoint collaborators and invoke the framework runner with that same
value; and
7. write the runner's logical output files only after a successful run, then
complete the command report and user-facing result.
1. Load/validate the selected application result and derive runtime configuration.
2. Generate a safe run identity and allocate requested capture.
3. Capture selected configuration, compose registries, expand reference actions,
and resolve the effective pipeline.
4. Obtain the shared engine when needed and perform offline preflight.
5. Materialize references, construct prepared typed modules, read input bytes,
and resolve the effective session.
6. Construct the accepted-result cache and optional recorder collaborator,
create one native execution group, and invoke the runner with independent
worker and execution selections.
7. Report process diagnostics, publish returned logical files only after runner
success, finalize requested capture, then submit the native completion report.
Preparation happens before source parsing, so module construction and
dependency failures cannot begin stage execution. The CLI also preserves the
framework's result and warning information when it writes summaries and the
final command result. Detailed state lifecycle, resume handling, and physical
path confinement are maintained in [Run State Internals](state.md) and
[Operations](../operations.md).
Modules receive the shared engine, operation data, and explicit collaborators,
not physical roots or CommandKit reporters. Detailed worker, assessment,
eligibility, and cache algorithms belong in [Pipeline Internals](pipeline.md);
physical publication/capture collaborators belong in [Run State Internals](state.md).
The CLI owns the versioned generated-session policy and resolves the sole
effective value before checkpoint construction. It records that value in the
final debug invocation summary when capture is enabled and passes it unchanged
to checkpoint identity and `pipeline.RunInput`. The public flag and stability
contract are defined by the [CLI reference](../cli.md#run); framework and LLM
packages only transport the supplied value.
Requested capture allocates before engine/preflight and finalizes once.
Primary operation causes and additional capture failures remain available.
Later report delivery failure does not rerun model work, remove valid artifacts,
or terminalize capture again.
The CLI also owns the scope grammar for reference flags. It enumerates the
selected chunk and lane targets from registered module specifications, expands
pipeline- and lane-scoped actions into exact stage-and-lane bindings, and
resolves overlapping bind and unbind actions by specificity before calling
configuration resolution. The generic pipeline therefore receives only exact
`ReferenceBinding` and `ReferenceUnbind` values and has no knowledge of CLI
selector syntax. Configuration resolution retains ownership of configured
external/generated conflicts, required slots, and module compatibility; file
materialization still occurs afterward.
## Native Reporting And Outcomes
For `run --json`, the CLI constructs and encodes its private run-result receipt
after a successful runner result is available, before it publishes logical
output files. It writes the prepared receipt to standard output only after
output publication and requested debug terminalization succeed. A receipt-write
failure exits with runtime status 1 and may leave partial standard-output bytes,
but the already-published output bundle remains complete and requested debug
reporting remains successfully terminalized. The CLI reports a bounded
command-owned error and does not repeat terminal reporting. The receipt remains
a CLI reporting concern rather than a framework or output-module responsibility;
its public contract is the
[native completion report](../cli.md#completion-report).
[run_result.go](../../internal/cli/run_result.go) submits one small application
value with a native text template. Native serializers render that same value.
Domain files, not a persisted report or ledger, are the deliverables.
Fallback qualification is independent of optional diagnostic visibility.
## Failure Mapping And Terminal Reporting
Warnings/advisories keep their domain classification and use the reporter's
diagnostic channel. Outcome helpers retain native configuration/preflight causes
and distinguish identifiable invalid input from operational/mixed failures.
CommandKit retains rendering/output/diagnostic delivery evidence separately from
the operation cause; quiet mode does not mask such failures.
Argument, flag, and invocation-combination failures are reported to standard
error before runtime composition and use the syntax error class. Once an
invocation is syntactically valid, configuration loading and validation,
resolution, registration, profile checks, reference materialization, module
construction, input reads, runner failures, output publication, and requested
debug handling use the runtime failure class. The public status numbers and
stream contract are defined in the [CLI reference](../cli.md#output-streams-and-exit-statuses).
The [completion report](../cli.md#completion-report) owns fields and
[stream/outcome contract](../cli.md#output-streams-and-exit-statuses) owns process
behavior. There is no universal Notarius envelope or parallel serializer.
When debug capture has been allocated, one command-state value records the
known run result. Guarded terminalization writes a success report once, or
attempts a failure report and error record once. A persistence failure is
reported in addition to the original failure and never replaces it. If a debug
path exists, failure output includes that path so the retained diagnostic data
is discoverable.
## Focused Verification
## Invariants To Preserve
- [Application tests](../../internal/cli/application_test.go) cover lazy built-ins,
shared scopes, selection evidence, and native diff outcomes.
- [Loader tests](../../internal/cli/native_load_test.go) and
[schema tests](../../internal/cli/native_schema_load_test.go) cover native
composition, captured contexts, and operator contracts.
- [Pipeline command tests](../../internal/cli/pipeline_commands_test.go) cover
listing/showing/preflight without execution inputs or state.
- [Override tests](../../internal/cli/execution_overrides_test.go) and
[run tests](../../internal/cli/pipeline_run_test.go) cover supplied values,
routing, references, sessions, and run ordering.
- [Reference tests](../../internal/cli/reference_contract_test.go) cover selector
specificity, generated conflicts, and materialization boundaries.
- [Native executable tests](../../internal/cli/native_process_test.go) cover the
real command routes and fake-provider presentations.
- [Completion tests](../../internal/cli/run_result_command_test.go) and
[recovery contracts](../../internal/cli/recovery_contract_test.go) cover retained
publication, capture/delivery failures, reuse, fallback, and native facts.
- Only the CLI composes production implementations and physical runtime roots.
- Configuration and resolved composition failures occur before module
preparation or source parsing.
- A runner's logical files are published only after a successful run.
- Production registries and a caller-supplied catalog or registries are
alternative composition sources, not an implicit mixture.
- A requested debug bundle has one terminal report attempt; its persistence
errors supplement rather than obscure the primary command error.
- User-facing flags, paths, exit codes, and configuration fields are defined
by their public documentation, not duplicated here.
Use focused CLI tests and pair with configuration/preflight tests when those
boundaries change. [Development](../development.md#validation) owns wider checks.
## Focused Tests
- **internal/cli/command_contract_test.go** covers dispatch, help, syntax and
runtime error classes, discovery, validation, and listing.
- **internal/cli/run_contract_test.go** covers the run handoff, publication,
debug reporting, and command-owned state collaborators.
- **internal/cli/production_contract_test.go** covers registrar composition,
production catalog contents, assets, and representative configuration
validation.
- **internal/cli/reference_contract_test.go** covers scoped CLI reference
expansion, specificity, bind/unbind conflicts, generated-reference
protection, origin separation, and materialization boundaries.
- **internal/cli/state_hardening_test.go** covers safe run identity, state
roots, and failure ordering.
Run **go test ./internal/cli** after changing command composition or command
behavior. Pair it with **go test ./internal/core/config** when the configuration
handoff changes.
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md