Record the agreed ConfigKit adoption decisions

This commit is contained in:
2026-11-17 20:27:47 +00:00
parent f5451a0cf5
commit 4a0e3c83db

View File

@@ -8,8 +8,8 @@ semantics with other ConfigKit consumers. Existing Narratio assembly conventions
are migration inputs rather than compatibility requirements for this work.
This roadmap defines the target and required changes. A subsequent implementation
plan will define staged work after the open decisions are resolved. This pass
adds documentation only. The earlier [v0.5.0 roadmap](config.md) and
plan will define staged work for the agreed target. This pass adds documentation
only. The earlier [v0.5.0 roadmap](config.md) and
[implementation plan](implementation.md) describe the completed baseline.
The ownership boundary in [ADR 0003](../adr/0003-assign-configuration-ownership.md)
@@ -140,22 +140,53 @@ capabilities do not establish new uniqueness requirements for every list.
### Discovery, credentials, and resource paths
Replace Narratio-owned local candidate probing with ConfigKit search descriptions
and `SearchConfig`. Explicit `--config` selection remains an exclusive `File`
input. Report the source actually selected by the library. The open decisions
below select search conventions and the independent bootstrap directory needed
before a discovered load resolves credentials.
and `SearchConfig`. Use the native `WorkingDirectory`, `UserConfigDirectory`,
and `UnixSystemDirectories` presets in that order with application name
`narratio`. Use their documented filenames. Explicit `--config` selection
remains an exclusive `File` input. Report the source actually selected by the
library. This provides convenient development-local configuration and standard
ConfigKit naming. Existing `pipeline.yml` files remain explicitly selectable;
migration guidance explains the new discovery names and precedence.
Bootstrap uses `LoadSecretsIntoEnvironment` once per invocation before typed
credential resolution and concurrent work. Existing environment variables win,
including explicitly empty variables. Keep explicit `--secrets-dir`, safe
partial-report handling, and exact-name forwarding to subprocesses. The selected
bootstrap convention must allow native discovery without a second preliminary
configuration load or a duplicate file-selection loop.
including explicitly empty variables. Use the invocation-owned conventional
directory `/usr/local/etc/narratio/secrets`, with `--secrets-dir` selecting
another directory. A missing conventional directory remains optional; an
explicit selection follows the existing explicit-selection behavior. Retain
safe partial-report handling and exact-name forwarding to subprocesses.
Use native source/resource context for application path interpretation. The
resource-base decision below applies to file references rather than artifact
destinations, command names, or remote object keys. ConfigKit's consumer examples
illustrate application policy; they do not impose it on Narratio.
The independent directory lets bootstrap precede ConfigKit's first and only
configuration selection. Service environments can provide credentials directly;
development invocations can choose a project-local secrets directory explicitly.
The implicit sibling `secrets/` convention retires with this cutover.
Resolve relative file-resource references from their effective defining source's
ConfigKit resource context. Inherited values follow their effective origin;
CLI-relative paths use the invocation directory. Application-derived paths
record their dependencies. Use the main source as a documented fallback for
origins without a distinct usable resource base. This makes imported definitions
portable across bundles.
Review actual path-bearing fields explicitly. Artifact destinations, command
names, session-relative products, and remote object keys retain their domain
meanings. This policy introduces no new target-existence or root-containment
checks. ConfigKit's consumer examples illustrate application policy; Narratio
owns the selected interpretation.
### Imports in secondary documents
Enable native explicit imports for locally sourced campaign, party, and session
documents as well as pipelines. This supports split rosters and shared metadata
with consistent library semantics. Campaign selection, party schema validation,
and session domain rules remain application-owned. Pipeline overlay selection
remains associated with the pipeline.
Materialize effective documents where raw root-file copying would leave
unresolved imports in downstream inputs or published session data. Remote
session snapshots retain their explicit source context; resolving imports
against an incidental download directory would give them an incorrect base.
Remote companion-file retrieval remains separate work.
### Final-domain inspection through native APIs
@@ -227,11 +258,11 @@ provider probes. Audita and workspace work retain their separate roadmaps.
- Adopt native discovery, destination-based artifact authoring, authored
collection operations, and native final-domain rendering/comparison. Remove
replaced search, comparison, and redundant metadata machinery.
- Follow the decisions below for resource bases and secondary-document loading.
- Apply the agreed source-relative resource bases and secondary-document imports.
Share definitions and loading context between execution and inspection so an
operator validates the configuration the pipeline will actually consume.
- If secondary-document imports are adopted, review input materialization and
publication as well as parsing. A copied root file can retain imports whose
- Review secondary-document input materialization and publication as well as
parsing. A copied root file can retain imports whose
companions are absent at its new location. Materialize the effective domain
document where a subprocess or restored session consumes it, retaining native
authoring evidence separately. Review placeholder checks against the effective
@@ -282,78 +313,3 @@ configuration/command/example/documentation checks and the established full
test, race, vet, build, and module checks on the adopted Go line. Preserve the
current supported build targets. No new live-service or CI-completion gate is
introduced by this migration.
## Open Decisions
### 1. Default pipeline discovery conventions
**Recommendation:** use the native `WorkingDirectory`, `UserConfigDirectory`,
and `UnixSystemDirectories` presets in that order with application name
`narratio`. Use their documented filenames and retain `--config` for exclusive
selection. This makes development-local configuration convenient and matches
ConfigKit's standard naming. Existing `pipeline.yml` files remain explicitly
selectable; migration guidance explains the new discovery names and precedence.
**Alternative:** use ConfigKit `SearchPaths` for the current two system
`pipeline.yml` paths, or add those paths to a broader ordered native search.
This reduces deployment disruption while still removing Narratio's probing
loop, but preserves project-specific naming and gives local development less
convenience. Adding fallback paths also creates more precedence to explain.
### 2. Secrets bootstrap before native discovery
**Recommendation:** use an invocation-owned conventional directory
`/usr/local/etc/narratio/secrets`, with `--secrets-dir` selecting another
directory and existing environment variables taking priority. Missing
conventional secrets remain optional; an explicitly selected directory follows
the existing explicit-selection behavior. This separates bootstrap from main
file discovery and lets ConfigKit perform the first and only configuration
selection. Service environments can provide credentials directly; development
invocations can choose a project-local secrets directory explicitly.
**Alternative:** preserve implicit `secrets/` beside the selected main file.
This is convenient for portable configuration bundles, but ConfigKit's discovery
source selects its file during loading. Preserving pre-load bootstrap would
require a coordinated upstream discovery/bootstrap facility or retaining
Narratio-owned preselection. The latter reduces native consolidation; moving
environment mutation into a hidden resolver would change the existing startup
boundary. An upstream request is viable if sibling-directory convenience is
more important than an immediately self-contained migration.
### 3. Relative resource paths in imported definitions
**Recommendation:** resolve relative file-resource references from their
effective defining source's ConfigKit resource context. Inherited values follow
their effective origin. CLI-relative paths use the invocation directory;
application-derived paths record their dependencies. Use the main source as a
documented fallback for origins without a distinct usable resource base.
This makes imported artifact/integration definitions portable across bundles.
Review actual path-bearing fields explicitly; session-relative products and
remote keys retain their domain bases. Introduce no new target-existence or
root-containment checks merely to adopt this policy.
**Alternative:** retain current per-field pipeline-root bases while using native
metadata elsewhere. This minimizes path edits and remains a valid ConfigKit
consumer policy, but moving reusable definitions still requires knowing the
destination bundle's root. Absolute resource paths are another viable operator
choice, with clear meaning but reduced portability.
### 4. Imports in campaign, party, and session documents
**Recommendation:** enable native explicit imports for locally sourced campaign,
party, and session documents as well as pipelines. This supports split rosters
and shared metadata with consistent library semantics. Keep campaign selection,
party schema validation, and session domain rules application-owned. Remote
session snapshots retain their explicit source context: remote companion-file
retrieval needs its own supported input contract, rather than resolving relative
imports against an incidental download directory. Pipeline overlay selection
remains associated with the pipeline; it does not implicitly select overlays
for every document. Adoption includes effective-document materialization where
raw root-file copying would leave unresolved imports in downstream inputs or
published session data.
**Alternative:** enable the richer facilities only for pipelines and retain
single-source secondary documents. This bounds the migration and simplifies
remote/local parity, but leaves an intentional project-specific difference in
authoring ergonomics. If selected, document that scope explicitly rather than
presenting it as a ConfigKit limitation.