Clarify configuration ownership and native inspection boundaries
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user