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
|
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
|
||||||
|
|||||||
Reference in New Issue
Block a user