Record the agreed ConfigKit adoption decisions
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user