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 configuration. Generated help and shell completion belong in the direction
for the cutover. for the cutover.
Narratio continues to own pipeline orchestration, configuration-domain ConfigKit owns configuration policy and the lifecycle through the final,
resolution, artifact selection, manifests, resume, publishing, restore, and fully resolved configuration handoff. Narratio supplies its configuration
cleanup. CommandKit owns CLI mechanics and presentation through its public schema, domain defaults, validation, and genuine configuration-resolution
APIs. Application-owned declarations and providers connect those boundaries. 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. Keep `ckprompt` and direct PromptKit engine ownership outside this migration.
Narratio delegates prompt execution to Scriptorium. Prompt-requirements 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 using an eventual Scriptorium external contract. CommandKit adoption can
proceed independently. 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 ### Command organization
Use one general execution command, one regeneration convenience, and command 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` Expose four scopes corresponding to Narratio's configuration domains. Use `app`
as the native default scope. 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 | | `campaign` | The selected campaign's settings |
| `session` | The selected session's settings, including applicable campaign defaults | | `session` | The selected session's settings, with applicable configuration defaults resolved within ConfigKit's lifecycle |
| `party` | The canonical party roster selected by `--party-file` or the campaign default | | `party` | The party configuration selected by `--party-file` or the campaign default |
Use effective values for `show` and `diff`, native provenance for `sources` and Expose standard `show`, `diff`, `sources`, `explain`, and `validate` behavior
`explain`, and domain validation for `validate`. Inspection reflects imports, through native `ckconfig` adapters for each scope's ConfigKit result. Effective
overlays, inheritance, defaults, and applicable Narratio resolution. A separate values, provenance, history, validation findings, and path behavior come from
raw-versus-resolved mode is not part of the initial design. 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 Remove the earlier requirement that app show/diff include expanded artifacts
receives. Provenance must distinguish authored and derived values accurately; and generated publish rules. They display and compare whatever the genuine
a generated artifact must not appear to have been literally declared in a ConfigKit result contains. Domain products derived after handoff are not added
source file. Use native evidence without inventing source origins. 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 Keep `config artifacts` as a Narratio-owned domain catalog of concrete artifact
derived from the same effective pipeline. `session artifacts SESSION` reports definitions and dependencies derived from the handed-off configuration and
session-specific availability and publication state. Future input discovery can selected party. Planning commands describe derived execution and publication
extend the configuration catalog separately from this migration. 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 Acquire only the context needed for the selected scope's native configuration
expansion requires the selected campaign and party; effective session settings load. Applicable campaign defaults for session configuration resolve before
require the session and applicable campaign context. Campaign inspection does handoff. Standard app inspection does not acquire campaign/party context solely
not require a session. Scope discovery and help do not load configuration. to expand runtime artifacts. Domain catalog and planning operations acquire
Report missing required context explicitly rather than presenting a partially the additional context needed for domain work. Campaign inspection does not
resolved view as complete. 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 Retain CommandKit's operation-specific `--scope all` behavior. Do not silently
omit a selected scope whose required context is missing. 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 - detailed comparisons with before/after values and presence information; and
- native `diff --check`, including status `3` when differences exist. - native `diff --check`, including status `3` when differences exist.
These operations use the same configuration and evidence as ordinary These capabilities use upstream operations and evidence from the scope's native
inspection. Filtering findings changes presentation, not validation success. result. Filtering findings changes presentation, not validation success.
Expose available evidence for derived fields without manufacturing source ConfigKit owns the relationship between effective, historical, explainable,
history. and overridable paths; Narratio does not add a writable-path registry,
reinterpret explicitness, or manufacture provenance for domain products.
### Native application configuration overrides ### 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 the need to compose overrides across supporting domains or reconcile generic
and explicitly targeted override flags. and explicitly targeted override flags.
Apply overrides after typed defaults and decoding, before application ConfigKit applies overrides after typed defaults and decoding, before its
resolution and semantic validation. Preserve native explicit empty, false, resolution and semantic validation callbacks. Preserve native explicit empty,
zero, and null values, mapping merge and whole-sequence replacement, and false, zero, and null values, mapping merge and whole-sequence replacement, and
duplicate/overlapping-path rejection. Earlier parsing and decoding failures duplicate/overlapping-path rejection. Earlier parsing and decoding failures
remain errors. CommandKit's last-value convention for singleton flags does not remain errors. CommandKit's last-value convention for singleton flags does not
replace ConfigKit's conflict rules for override records. replace ConfigKit's conflict rules for override records.
Override paths address application configuration accepted by its loader. They Override paths and acceptance follow ConfigKit's native input semantics for
do not provide an independent patch mechanism over the final expanded artifact application configuration. Standard inspection does not promise that every
catalog. Ordinary Narratio derivation and validation determine the effective displayed path accepts an override. Narratio passes explicit assignments to
result, regardless of whether values came from files, inheritance, overlays, ConfigKit without translating runtime catalog paths into input paths or
or CLI overrides. patching domain products after handoff.
Overrides leave source configuration files unchanged. Normal run metadata and Overrides leave source configuration files unchanged. Normal run metadata and
prepared configuration may record the effective settings through established 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. 1. Parse the command and validate syntax and input combinations.
2. Bootstrap credentials when the operation needs configuration. 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. 4. Acquire execution resources and perform the operation.
5. Finalize domain state, release resources, present the result, and return the 5. Finalize domain state, release resources, present the result, and return the
outcome. 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, and require a coherent, compilable, fully validated final application.
Useful work boundaries are core invocation/domain commands; configuration Useful work boundaries are core invocation/domain commands; configuration
scopes, file selection, inspection, and app overrides; reports, diagnostics, handoff, native scopes and inspection, file selection, and app overrides;
cancellation, and completion; and integration verification, removal of reports, diagnostics, cancellation, and completion; and integration
superseded CLI machinery, and documentation. These are organizational verification, removal of superseded CLI machinery, and documentation. These
boundaries, not mandatory buildable milestones or a supported dual interface. are organizational boundaries, not mandatory buildable milestones or a
The subsequent implementation plan determines the most efficient order and supported dual interface. The subsequent implementation plan determines the
dependencies. most efficient order and dependencies.
Use CommandKit v0.7.0 and ckconfig v0.9.0 as the initial roadmap baseline. 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 Review relevant public contract changes before deliberately selecting a later
release. Before finalizing implementation details, verify public API support release. Before finalizing implementation details, verify native ConfigKit
for effective views with truthful provenance and Narratio-specific commands loader and `ckconfig` adapter integration and composition of Narratio-specific
alongside standard configuration commands. Address shared-capability gaps commands alongside standard configuration commands. Address required upstream
upstream where appropriate rather than silently recreating CommandKit behavior capability gaps upstream rather than compensating with custom effective views,
locally. 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, Retain Narratio's stage sequencing, resume authority, publication semantics,
restore safety, and cleanup rules. Changes required for the agreed overrides, restore safety, and cleanup rules. Changes required for the agreed ownership
reporting, and cancellation behavior are in scope. Workspace reorganization, boundary, inspection, overrides, reporting, and cancellation behavior are in
downstream-tool adoption, and Scriptorium requirements inspection remain scope. Workspace reorganization, downstream-tool adoption, and Scriptorium
separate work. requirements inspection remain separate work.
Validate the integration through representative behavioral acceptance cases: Validate the integration through representative behavioral acceptance cases:
- Native arguments and selectors reach the intended Narratio operation. - 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 - App inspection, planning, and execution resolve equivalent application
configuration selections and overrides. configuration selections and overrides.
- Explicit party-file selection consistently feeds roster inspection, derived - 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 Provide workflow-oriented release migration guidance: an old-to-new command
table plus explanations of removed shortcuts, identity/file selectors including table plus explanations of removed shortcuts, identity/file selectors including
party-file selection, app-only field overrides, native flag repetition and 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, visibility, exit classifications, and cancellation. Identify affected examples,
operator procedures, scripts, and downstream callers. operator procedures, scripts, and downstream callers.
Update canonical documentation and maintained examples as implementation lands; 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 roadmap and subsequent plan. Release version selection remains deferred to
release preparation. 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 ## Discussion and decision record
### 2026-11-19 — Initial direction ### 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 ### 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. Accepted `app`, `campaign`, `session`, and `party` scopes, with `app` as default.
Show/diff exposes effective values and source/explanation operations use native Show/diff exposes effective values and source/explanation operations use native
provenance. Concrete artifacts remain visible in the effective pipeline and the 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 and ordinary file-backed configuration composition. This revision supersedes
the earlier all-domain override and campaign-only party-selection decisions. 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 ### Continuing the discussion
For each topic, record the question, the agreed outcome, its rationale, and any For each topic, record the question, the agreed outcome, its rationale, and any