From 4a0e3c83db11a4a9ccee011662c8a5084de52616 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 17 Nov 2026 20:27:47 +0000 Subject: [PATCH] Record the agreed ConfigKit adoption decisions --- docs/roadmap/configkit.md | 140 +++++++++++++------------------------- 1 file changed, 48 insertions(+), 92 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 475958a..bdfb333 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -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.