Clarify configuration ownership and native inspection boundaries

This commit is contained in:
2026-11-20 00:16:42 +00:00
parent 084e6d178b
commit 7ee362f1c3

View File

@@ -35,10 +35,18 @@ Use the standard inspection capabilities where they apply to Narratio's
configuration. Generated help and shell completion belong in the direction
for the cutover.
Narratio continues to own pipeline orchestration, configuration-domain
resolution, artifact selection, manifests, resume, publishing, restore, and
cleanup. CommandKit owns CLI mechanics and presentation through its public
APIs. Application-owned declarations and providers connect those boundaries.
ConfigKit owns configuration policy and the lifecycle through the final,
fully resolved configuration handoff. Narratio supplies its configuration
schema, domain defaults, validation, and genuine configuration-resolution
rules through ConfigKit's supported extension points. Those callbacks operate
within ConfigKit's lifecycle and provenance model.
Narratio owns interpreting the handed-off configuration and using it for
pipeline orchestration, artifact selection, manifests, resume, publishing,
restore, and cleanup. CommandKit owns CLI mechanics and presentation;
`ckconfig` exposes ConfigKit's inspection features through native adapters.
Narratio provides neutral command declarations, selection, and acquisition
wiring rather than an intervening configuration or inspection policy layer.
Keep `ckprompt` and direct PromptKit engine ownership outside this migration.
Narratio delegates prompt execution to Scriptorium. Prompt-requirements
@@ -46,6 +54,29 @@ inspection and early pipeline dependency checks remain separate feature work
using an eventual Scriptorium external contract. CommandKit adoption can
proceed independently.
### Configuration handoff and domain interpretation
The completed ConfigKit result is authoritative configuration. Consume it
without post-handoff mutation. Any genuine configuration defaulting,
normalization, or resolution must complete within ConfigKit's supported
lifecycle before handoff, with native evidence. If a required capability is
missing, identify the specific upstream gap instead of implementing a second
configuration system in Narratio.
Domain interpretation produces separate domain objects. For example, Narratio
can interpret artifact-family declarations and a party roster to produce a
concrete artifact catalog, execution plan, and publication actions. It must
not write those products back into the resolved configuration or present them
as a replacement effective configuration. Domain derivation remains Narratio's
responsibility; it does not need to be moved into configuration callbacks merely
to appear in standard inspection output.
Standard inspection uses the genuine ConfigKit result through native
`ckconfig` adapters. Do not construct a separate effective inspection document,
combine it with another result's authoring evidence, or add custom path or
provenance reconciliation. Native inspection and override semantics are
upstream contracts that Narratio exposes neutrally.
### Command organization
Use one general execution command, one regeneration convenience, and command
@@ -109,34 +140,42 @@ ckconfig operations, with the view defined below.
Expose four scopes corresponding to Narratio's configuration domains. Use `app`
as the native default scope.
| Scope | Effective configuration |
| Scope | Native ConfigKit configuration result |
| --- | --- |
| `app` | Pipeline configuration, including campaign-dependent artifact expansion and generated publish rules |
| `app` | Resolved application/pipeline configuration |
| `campaign` | The selected campaign's settings |
| `session` | The selected session's settings, including applicable campaign defaults |
| `party` | The canonical party roster selected by `--party-file` or the campaign default |
| `session` | The selected session's settings, with applicable configuration defaults resolved within ConfigKit's lifecycle |
| `party` | The party configuration selected by `--party-file` or the campaign default |
Use effective values for `show` and `diff`, native provenance for `sources` and
`explain`, and domain validation for `validate`. Inspection reflects imports,
overlays, inheritance, defaults, and applicable Narratio resolution. A separate
raw-versus-resolved mode is not part of the initial design.
Expose standard `show`, `diff`, `sources`, `explain`, and `validate` behavior
through native `ckconfig` adapters for each scope's ConfigKit result. Effective
values, provenance, history, validation findings, and path behavior come from
that result and the upstream integration. Narratio supplies domain validation
through the supported ConfigKit lifecycle, not a separate inspection policy.
`app` show/diff includes the concrete artifacts and publish rules execution
receives. Provenance must distinguish authored and derived values accurately;
a generated artifact must not appear to have been literally declared in a
source file. Use native evidence without inventing source origins.
Remove the earlier requirement that app show/diff include expanded artifacts
and generated publish rules. They display and compare whatever the genuine
ConfigKit result contains. Domain products derived after handoff are not added
to standard inspection, and differences between those products are not added
to native configuration comparisons. A separate raw-versus-resolved mode is
not part of the design.
Keep `config artifacts` as a focused catalog of definitions and dependencies
derived from the same effective pipeline. `session artifacts SESSION` reports
session-specific availability and publication state. Future input discovery can
extend the configuration catalog separately from this migration.
Keep `config artifacts` as a Narratio-owned domain catalog of concrete artifact
definitions and dependencies derived from the handed-off configuration and
selected party. Planning commands describe derived execution and publication
work. These domain views do not redefine ConfigKit's effective configuration.
`session artifacts SESSION` reports session-specific availability and
publication state. Future input discovery can extend the domain catalog
separately from this migration.
Acquire only the context needed for the selected scope. Party-driven pipeline
expansion requires the selected campaign and party; effective session settings
require the session and applicable campaign context. Campaign inspection does
not require a session. Scope discovery and help do not load configuration.
Report missing required context explicitly rather than presenting a partially
resolved view as complete.
Acquire only the context needed for the selected scope's native configuration
load. Applicable campaign defaults for session configuration resolve before
handoff. Standard app inspection does not acquire campaign/party context solely
to expand runtime artifacts. Domain catalog and planning operations acquire
the additional context needed for domain work. Campaign inspection does not
require a session. Scope discovery and help do not load configuration. Report
missing required context explicitly rather than presenting an incomplete load
as a complete configuration result.
Retain CommandKit's operation-specific `--scope all` behavior. Do not silently
omit a selected scope whose required context is missing.
@@ -209,10 +248,11 @@ configuration scopes:
- detailed comparisons with before/after values and presence information; and
- native `diff --check`, including status `3` when differences exist.
These operations use the same configuration and evidence as ordinary
inspection. Filtering findings changes presentation, not validation success.
Expose available evidence for derived fields without manufacturing source
history.
These capabilities use upstream operations and evidence from the scope's native
result. Filtering findings changes presentation, not validation success.
ConfigKit owns the relationship between effective, historical, explainable,
and overridable paths; Narratio does not add a writable-path registry,
reinterpret explicitness, or manufacture provenance for domain products.
### Native application configuration overrides
@@ -248,18 +288,18 @@ authoring and provenance differ from late CLI overrides. This decision removes
the need to compose overrides across supporting domains or reconcile generic
and explicitly targeted override flags.
Apply overrides after typed defaults and decoding, before application
resolution and semantic validation. Preserve native explicit empty, false,
zero, and null values, mapping merge and whole-sequence replacement, and
ConfigKit applies overrides after typed defaults and decoding, before its
resolution and semantic validation callbacks. Preserve native explicit empty,
false, zero, and null values, mapping merge and whole-sequence replacement, and
duplicate/overlapping-path rejection. Earlier parsing and decoding failures
remain errors. CommandKit's last-value convention for singleton flags does not
replace ConfigKit's conflict rules for override records.
Override paths address application configuration accepted by its loader. They
do not provide an independent patch mechanism over the final expanded artifact
catalog. Ordinary Narratio derivation and validation determine the effective
result, regardless of whether values came from files, inheritance, overlays,
or CLI overrides.
Override paths and acceptance follow ConfigKit's native input semantics for
application configuration. Standard inspection does not promise that every
displayed path accepts an override. Narratio passes explicit assignments to
ConfigKit without translating runtime catalog paths into input paths or
patching domain products after handoff.
Overrides leave source configuration files unchanged. Normal run metadata and
prepared configuration may record the effective settings through established
@@ -369,7 +409,8 @@ Keep startup lightweight and acquire dependencies only when needed:
1. Parse the command and validate syntax and input combinations.
2. Bootstrap credentials when the operation needs configuration.
3. Resolve the required configuration and domain context.
3. Load the required configuration through ConfigKit's completed lifecycle,
then derive the domain context needed by the operation.
4. Acquire execution resources and perform the operation.
5. Finalize domain state, release resources, present the result, and return the
outcome.
@@ -412,30 +453,41 @@ commit working. Report intermediate status accurately, use focused checks when
useful, and require a coherent, compilable, fully validated final application.
Useful work boundaries are core invocation/domain commands; configuration
scopes, file selection, inspection, and app overrides; reports, diagnostics,
cancellation, and completion; and integration verification, removal of
superseded CLI machinery, and documentation. These are organizational
boundaries, not mandatory buildable milestones or a supported dual interface.
The subsequent implementation plan determines the most efficient order and
dependencies.
handoff, native scopes and inspection, file selection, and app overrides;
reports, diagnostics, cancellation, and completion; and integration
verification, removal of superseded CLI machinery, and documentation. These
are organizational boundaries, not mandatory buildable milestones or a
supported dual interface. The subsequent implementation plan determines the
most efficient order and dependencies.
Use CommandKit v0.7.0 and ckconfig v0.9.0 as the initial roadmap baseline.
Review relevant public contract changes before deliberately selecting a later
release. Before finalizing implementation details, verify public API support
for effective views with truthful provenance and Narratio-specific commands
alongside standard configuration commands. Address shared-capability gaps
upstream where appropriate rather than silently recreating CommandKit behavior
locally.
release. Before finalizing implementation details, verify native ConfigKit
loader and `ckconfig` adapter integration and composition of Narratio-specific
commands alongside standard configuration commands. Address required upstream
capability gaps upstream rather than compensating with custom effective views,
provenance reconciliation, or replacement configuration behavior.
Remove the current post-load configuration mutation and the split between
runtime inspection snapshots and authoring evidence. Separate domain products
from the authoritative configuration handoff while preserving their intended
processing behavior. Do not retain those inspection projections merely to
reproduce existing output. Safe persisted configuration and domain artifacts
remain useful records, but do not replace the result used by native inspection.
Retain Narratio's stage sequencing, resume authority, publication semantics,
restore safety, and cleanup rules. Changes required for the agreed overrides,
reporting, and cancellation behavior are in scope. Workspace reorganization,
downstream-tool adoption, and Scriptorium requirements inspection remain
separate work.
restore safety, and cleanup rules. Changes required for the agreed ownership
boundary, inspection, overrides, reporting, and cancellation behavior are in
scope. Workspace reorganization, downstream-tool adoption, and Scriptorium
requirements inspection remain separate work.
Validate the integration through representative behavioral acceptance cases:
- Native arguments and selectors reach the intended Narratio operation.
- Standard configuration commands expose genuine ConfigKit results through
native adapters, with upstream value, provenance, and path semantics.
- Domain catalog and plan generation consume handed-off configuration without
modifying it or replacing the native inspection result.
- App inspection, planning, and execution resolve equivalent application
configuration selections and overrides.
- Explicit party-file selection consistently feeds roster inspection, derived
@@ -460,7 +512,8 @@ adoption work.
Provide workflow-oriented release migration guidance: an old-to-new command
table plus explanations of removed shortcuts, identity/file selectors including
party-file selection, app-only field overrides, native flag repetition and
placement, configuration scopes and comparisons, structured output, diagnostic
placement, native configuration inspection and its distinction from domain
catalogs and plans, configuration comparisons, structured output, diagnostic
visibility, exit classifications, and cancellation. Identify affected examples,
operator procedures, scripts, and downstream callers.
Update canonical documentation and maintained examples as implementation lands;
@@ -505,6 +558,10 @@ checks and detailed implementation sequencing remain preparation work for the
roadmap and subsequent plan. Release version selection remains deferred to
release preparation.
The next discussion is whether and how to crystallize the agreed configuration
ownership boundary in an ADR. The boundary is settled; an ADR has not yet been
prepared.
## Discussion and decision record
### 2026-11-19 — Initial direction
@@ -531,6 +588,10 @@ workflow. Configuration scopes and views are the next discussion topic.
### 2026-11-19 — Configuration scopes and views agreed
The later configuration-ownership revision supersedes the expanded app
inspection view recorded below. The four scopes remain, with standard
inspection exposing their native ConfigKit results.
Accepted `app`, `campaign`, `session`, and `party` scopes, with `app` as default.
Show/diff exposes effective values and source/explanation operations use native
provenance. Concrete artifacts remain visible in the effective pipeline and the
@@ -625,6 +686,28 @@ to meaningfully reduce complexity while retaining native app override behavior
and ordinary file-backed configuration composition. This revision supersedes
the earlier all-domain override and campaign-only party-selection decisions.
### 2026-11-19 — Configuration ownership and native inspection clarified
Accepted ConfigKit's completed result as authoritative configuration, with
Narratio's schema, defaults, validation, and genuine resolution rules supplied
through ConfigKit's supported lifecycle. Narratio consumes the handoff without
mutation and produces separate domain catalogs, plans, and execution objects.
CommandKit's `ckconfig` integration neutrally exposes the native ConfigKit
features; Narratio does not reinterpret or improve their inspection semantics.
Superseded the requirement that app show/diff contain expanded artifacts and
generated publish rules. Standard inspection uses native results and adapters;
domain catalogs and planning commands expose the work derived from those
results. Remove post-load configuration mutation and separate inspection
snapshots rather than reconcile them with retained authoring evidence. Native
path and override semantics remain upstream contracts, not a Narratio design
problem.
The user identified the configuration/inspection split as a boundary violation.
The agreed correction is to restore ownership, not add machinery to make
different representations appear consistent. A potential ADR recording this
boundary is the next discussion topic.
### Continuing the discussion
For each topic, record the question, the agreed outcome, its rationale, and any