Refresh native configuration, CLI, and LLM internal guides
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user