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.
|
are migration inputs rather than compatibility requirements for this work.
|
||||||
|
|
||||||
This roadmap defines the target and required changes. A subsequent implementation
|
This roadmap defines the target and required changes. A subsequent implementation
|
||||||
plan will define staged work after the open decisions are resolved. This pass
|
plan will define staged work for the agreed target. This pass adds documentation
|
||||||
adds documentation only. The earlier [v0.5.0 roadmap](config.md) and
|
only. The earlier [v0.5.0 roadmap](config.md) and
|
||||||
[implementation plan](implementation.md) describe the completed baseline.
|
[implementation plan](implementation.md) describe the completed baseline.
|
||||||
|
|
||||||
The ownership boundary in [ADR 0003](../adr/0003-assign-configuration-ownership.md)
|
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
|
### Discovery, credentials, and resource paths
|
||||||
|
|
||||||
Replace Narratio-owned local candidate probing with ConfigKit search descriptions
|
Replace Narratio-owned local candidate probing with ConfigKit search descriptions
|
||||||
and `SearchConfig`. Explicit `--config` selection remains an exclusive `File`
|
and `SearchConfig`. Use the native `WorkingDirectory`, `UserConfigDirectory`,
|
||||||
input. Report the source actually selected by the library. The open decisions
|
and `UnixSystemDirectories` presets in that order with application name
|
||||||
below select search conventions and the independent bootstrap directory needed
|
`narratio`. Use their documented filenames. Explicit `--config` selection
|
||||||
before a discovered load resolves credentials.
|
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
|
Bootstrap uses `LoadSecretsIntoEnvironment` once per invocation before typed
|
||||||
credential resolution and concurrent work. Existing environment variables win,
|
credential resolution and concurrent work. Existing environment variables win,
|
||||||
including explicitly empty variables. Keep explicit `--secrets-dir`, safe
|
including explicitly empty variables. Use the invocation-owned conventional
|
||||||
partial-report handling, and exact-name forwarding to subprocesses. The selected
|
directory `/usr/local/etc/narratio/secrets`, with `--secrets-dir` selecting
|
||||||
bootstrap convention must allow native discovery without a second preliminary
|
another directory. A missing conventional directory remains optional; an
|
||||||
configuration load or a duplicate file-selection loop.
|
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
|
The independent directory lets bootstrap precede ConfigKit's first and only
|
||||||
resource-base decision below applies to file references rather than artifact
|
configuration selection. Service environments can provide credentials directly;
|
||||||
destinations, command names, or remote object keys. ConfigKit's consumer examples
|
development invocations can choose a project-local secrets directory explicitly.
|
||||||
illustrate application policy; they do not impose it on Narratio.
|
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
|
### 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
|
- Adopt native discovery, destination-based artifact authoring, authored
|
||||||
collection operations, and native final-domain rendering/comparison. Remove
|
collection operations, and native final-domain rendering/comparison. Remove
|
||||||
replaced search, comparison, and redundant metadata machinery.
|
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
|
Share definitions and loading context between execution and inspection so an
|
||||||
operator validates the configuration the pipeline will actually consume.
|
operator validates the configuration the pipeline will actually consume.
|
||||||
- If secondary-document imports are adopted, review input materialization and
|
- Review secondary-document input materialization and publication as well as
|
||||||
publication as well as parsing. A copied root file can retain imports whose
|
parsing. A copied root file can retain imports whose
|
||||||
companions are absent at its new location. Materialize the effective domain
|
companions are absent at its new location. Materialize the effective domain
|
||||||
document where a subprocess or restored session consumes it, retaining native
|
document where a subprocess or restored session consumes it, retaining native
|
||||||
authoring evidence separately. Review placeholder checks against the effective
|
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
|
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
|
current supported build targets. No new live-service or CI-completion gate is
|
||||||
introduced by this migration.
|
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