From 3f58d44e9653da90bee24a4e08bca2b8606c825e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 18 Nov 2026 15:06:06 +0000 Subject: [PATCH] Remove completed secrets bootstrap plans --- docs/roadmap/implementation.md | 396 ------------------------------ docs/roadmap/secrets-directory.md | 209 ---------------- 2 files changed, 605 deletions(-) delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/secrets-directory.md diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index e8c5834..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,396 +0,0 @@ -# Configured secrets bootstrap implementation plan - -## Scope and execution - -Implement the [secrets-directory roadmap](secrets-directory.md) and accepted -[ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md). The starting -revision is `fb0560d`. Read [development](../development.md), the -[agent policy](../policy/agents.md), and the applicable architecture, testing, -and documentation policies before implementing a stage. - -The stages run sequentially in one sprint. Intermediate stages may leave callers -temporarily uncompilable while an internal handoff changes. Finish the shared -integration before final validation. Keep tests with their behavior's owning -stage and reuse existing fixtures and failure seams. Each stage is intended to -fit one Luna implementation prompt. - -The completed feature provides explicit bootstrap before ordinary configuration -loading. Discovery and the captured main document are shared between those two -calls. Ordinary secret resolution continues to read the environment at its -existing lifecycle point. Filesystem access and bootstrap finish synchronously. - -## Decisions for implementation - -### Public API - -Keep the existing function and its exact function type. Add these root-owned -public declarations, following the existing facade-to-engine conversion pattern. - -```go -func LoadSecretsIntoEnvironment(directory string) (*SecretsReport, error) - -type SecretsOptions struct { - Overwrite bool -} - -func LoadSecretsIntoEnvironmentWithOptions( - directory string, options SecretsOptions, -) (*SecretsReport, error) - -type SecretsFromConfigOptions struct { - Filesystem *FilesystemContext - Overwrite *bool -} - -func LoadSecretsIntoEnvironmentFromConfig( - main Source, supplied ...SecretsFromConfigOptions, -) (*SecretsReport, Source, error) -``` - -The companion accepts zero or one options value, matching the load entry points. -Multiple values produce `LoadError` with `CodeOptionsInvalid`, an empty non-nil -report, and zero `Source` before acquisition or writes. Snapshot the supplied -context and Boolean value at call entry using existing conversion conventions. -Nil overwrite uses YAML, then false. A supplied false or true wins over YAML. - -The companion accepts host `File` and `SearchConfig` sources and `NoSource`. -A prepared host source can also be supplied to an explicit companion call using -its captured main. Reject other source kinds and native filesystem contexts as -`LoadError` option failures before consuming them. Preserve constructor and search -validation diagnostics through the existing helpers. NoSource and optional search -exhaustion succeed with an empty report and `NoSource()`. Explicit context on an -absent input follows existing absent-host-context validation; subsequent absent -loading uses the ordinary caller-supplied context rules. - -Every failure returns a non-nil report and zero `Source`. Discovery, acquisition, -parse, control, and preparation-context failures use `LoadError`. Directory -resolution/inspection, credential reads, and environment writes use -`SecretsError`. Keep both error wrappers and their existing safe rendering and -detached records. Successful preparation with no directory returns the prepared -main and an empty report. - -### Controls and source roles - -Recognize root `config.secrets_dir` as a nonempty string containing a relative -host path and root `config.secrets_overwrite` as a Boolean. Accept ordinary YAML -Boolean spellings through the parser's existing type handling. Nulls, wrong -types, empty directory strings, absolute paths, and host volume-qualified paths -are invalid. Treat path text literally using host path operations. Parent-relative -paths are usable when their canonical targets stay inside the selected root. - -Only the main input's document root owns these controls. Imports, underlays, -and selected overlays containing them produce a source-local control diagnostic. -Nested application `config` mappings and root application data introduced by -placement, defaults, CLI, or resolution retain their existing meaning under -[ADR 0020](../adr/0020-document-root-controls.md). - -Normal loading checks and consumes the main controls, with imports enabled or -disabled. Filesystem checks for the declared secrets directory happen in the -companion helper. Both ordinary loading entry points perform their usual secret -lookup. Preparation validates the root control mapping and the bootstrap fields, -while other control grammars and import enablement are checked by the later load. -Retain the original main tree so imports and collection declarations are still -available to that load. A valid overwrite declaration without a directory is a -no-op. Invalid bootstrap fields fail even if a Go overwrite choice is supplied. - -Use existing diagnostic codes. Use `CodeSecretsInvalidPath` for invalid directory -syntax, `CodeSecretsInvalidValue` for a non-Boolean overwrite setting, and the -existing directive-context codes for misplaced controls (`CodeImportInvalid` or -`CodeOverlayDirective`). Root mapping errors keep their current classification. -Bootstrap-field diagnostics carry `/config/secrets_dir` or -`/config/secrets_overwrite` and source-local locations, inside a `LoadError`. -Avoid raw input, parser errors, or credential contents in messages. - -### Captured-source ownership and context - -Represent preparation privately as a captured host-file payload attached to an -engine `sourceFile`. Keep public `Source` opaque and report `SourceKindFile`. -Capture the original parsed document, original byte count, canonical main path, -canonical base, and canonical containment root. Retain the unconsumed controls. -Keep captured data read-only and give each load an owned document clone with -fresh source IDs and accounting. Namespace tokens and acquisition state belong -to each load. Retain passive path facts with the source. - -Normal acquisition consumes the captured main without discovery, file reading, -or bootstrap. Apply the usual byte, document, placement, and aggregate accounting -to the captured input in every load. A preparation-time count never substitutes -for load-wide admission. Imports and resources continue to be acquired when their -normal operations run. Main deletion or modification does not change captured -contents; later filesystem operations may fail under their existing contracts. - -Use the captured context when later loading supplies none. Resolve an explicit -later host context against the captured canonical main path. It is compatible -when its canonical root, base, and main path match the captured facts. Compare -path facts using the existing host path rules, allowing equivalent spellings -and root symlink aliases. Native contexts, a supplied file BaseDir, and genuinely -different roots fail with `CodeOptionsInvalid` in `LoadError`. Avoid re-resolving -the original main filename to compare contexts, since it may now point elsewhere. -Use the same check for ordinary options and layered main input contexts before -import or overlay handling can substitute a context. - -### Directory bootstrap semantics - -Reuse `loadSecretsDir` and its environment/access seams for all three public -helpers. Preservation mode retains both existing-variable checks, including -empty values and a variable created between preflight and application. -Overwrite mode reads existing names' eligible files and applies them regardless -of environment presence. Unrelated environment variables retain their values. -Use the existing loaded/skipped/failed/not-applied statuses. `ExistingEmpty` -continues to describe skipped existing values. - -Configured directory resolution uses the captured base and root. Canonicalize -the selected directory with the existing filesystem helpers and check containment -of that canonical target before reads or writes. A directory symlink can resolve -to a contained target, following the existing bootstrap directory convention. -Return `SecretsError` with `CodeSecretsInvalidPath` for an outside-root target; -use existing filesystem classifications for missing or unreadable targets. -The direct-directory helpers keep their existing path resolution behavior. - -Bootstrap includes all eligible directory entries, independently of the later -typed schema. Reuse dot-entry exclusion, regular-file checks, limits, sorted -order, newline handling, empty-file handling, and NUL rejection. Complete -metadata checks and required reads before writes. A write failure retains prior -writes and reports remaining entries as not applied. Later load failures leave -bootstrap effects in place. Reports and prepared sources retain no credential -bytes from secret files. Applications own startup ordering and concurrent -process-environment mutation under the existing bootstrap contract. - -## Stage 1 — Extend shared directory bootstrap with overwrite - -**Completed.** - -Work in `internal/engine/secrets.go` and `internal/engine/secrets_test.go`. - -1. Add a small engine options value for overwrite and keep `LoadSecretsDir` - delegating with preservation enabled. Add its options-bearing counterpart. - Extend the shared private worker and existing test seams accordingly. -2. Make overwrite affect only staging and applying values. Preserve sorted - enumeration, all metadata validation before reads, bounded reads before - writes, skipped-file behavior in preservation mode, and failure reporting. -3. Add focused behavioral cases for overwriting nonempty and empty existing - variables, overwriting with empty file content, and leaving names without - files alone. Extend the existing staged-presence-race and partial-apply-failure - cases to cover overwrite. Reuse current read-limit, dot-file, NUL, and safe - error coverage. Process-mutating tests restore state and run serially. - -Stage completion means both policies work through one bootstrap worker and -existing preservation behavior remains covered. Run the relevant existing and -new `LoadSecretsDir` tests once callers compile. - -## Stage 2 — Add main-scoped bootstrap control parsing - -**Completed.** - -Work primarily in `internal/engine/directives.go`, `acquisition.go`, and the -directive/version parsing handoffs in `source_version.go`. - -1. Introduce a small private bootstrap-settings value with declaration presence, - directory text, overwrite value, and source-local diagnostic locations. Share - its field validation between preparation and normal control extraction. -2. Give extraction enough source-role information to allow these controls only - on the actual main document. `rootDirectiveContextSource` and - `rootDirectiveContextLayered` alone cannot identify that role because those - contexts also occur on contributions. Carry the role through the relevant - acquisition/version and import traversal call sites. -3. Keep bootstrap-only extraction usable before normal imports/sequence grammar - validation. The companion can prepare a main that declares imports without - enabling or acquiring them. Normal extraction checks the complete control - block and removes it before placement and application decoding. -4. Extend directive-scope and facade-control tests with main declarations, - disabled imports, wrong types, explicit false, misplaced controls, and nested - ordinary data. Verify source-version control-overlap checks recognize the - new fields and that version acceptance itself stays in the load. - -Stage completion means the normal load accepts and consumes valid main settings -while leaving environment state untouched. Other source-root controls retain -their existing grammar, enablement, and error precedence. - -## Stage 3 — Share host-main selection and capture - -**Completed.** - -Work in `internal/engine/source.go`, `parse.go`, `discovery.go`, and the initial -selection/read portion of `acquisition.go`. A focused `prepared_source.go` may -hold the new private payload and preparation helpers. - -1. Factor the existing selection and bounded main parsing handoff for reuse by - normal acquisition and preparation. Reuse `resolveSearchInput`, search option - checks, `readSource`, and YAML adapter diagnostics. Keep candidate ordering, - optional exhaustion, selected-file failure, and regular-file semantics. -2. Add the captured host payload specified above. Preserve original source line - locations and all controls. Construct independent documents for subsequent - loads with `document.Clone` and `setDocumentSourceID`. Count captured bytes - under the current read limits before returning a document to acquisition. -3. For capture, resolve and validate the host base/root through existing - `filesystemOptionDiagnostics`, `resolveFilesystemContext`, and directory - validation. Store path facts without access handles or a preparation token. -4. Add internal cases proving captured data stays fixed after the original file - changes, becomes absent, or another search candidate appears. Retain ordinary - File/SearchConfig reread behavior. Cover parser/read failures and limits with - existing narrow test fixtures. Keep sources and payloads private until the - public wrapper stage. - -Stage completion means the acquisition front end can consume an ordinary host -file or its captured payload through the same parsed-source handoff. - -## Stage 4 — Integrate captured contexts with ordinary loading - -**Completed.** - -Work in `options.go`, `filesystem_context.go`, `filesystem.go`, `acquisition.go`, -`load_input.go`, `selected_overlay.go`, and `source_context.go` as needed. - -1. Make context resolution select captured path facts and enforce the explicit - context equivalence rule at the shared acquisition boundary. Ensure both - imported and standalone branches receive the selected resolved context. -2. Carry the captured base/root into standalone main acquisition, ordinary - overlay resolution, and passive source-context completion. Ordinary overlays - keep their established root-relative lookup convention. -3. Preserve file-kind records, canonical paths, source-local diagnostics, and - placement projection. Reuse normal source registration and accounting. -4. Add focused internal cases for omitted/equivalent/incompatible later contexts, - explicit wider roots, a symlinked selected main, main removal, destinations, - and ordinary overlay/resource-context behavior. Compare relevant records and - values with a normal load of the same unmodified file. - -Stage completion means an ordinary load uses captured contents and context -through all its normal paths. Real filesystem failures are handled at the -existing access boundaries without retaining an open handle in the source. - -## Stage 5 — Integrate imports and layered main-relative consumers - -**Completed.** - -Work in `import_acquisition.go`, `load_request.go`, and layered/context owners -identified by the shared acquisition handoff. - -1. Feed the captured main document and resolved context into imported acquisition. - Charge its raw bytes and nodes through existing accounting exactly once per - load. Keep placement wrapper accounting and per-tier repetition tracking. -2. Treat the captured main as the same canonical host file for repeated-file and - cycle checks. A fresh load gets its own host namespace and source IDs. -3. Ensure layered acquisition propagates the captured main context to declared - MainRelative underlays and selected overlays, with existing explicit context - and fallback precedence. Preserve main-first acquisition and tier precedence. -4. Verify live imports after main capture, repeat/cycle detection involving the - captured main, source/version evidence with imports, an explicitly wider root - permitting contained parent-relative imports, and independent repeated loads. - Include one integrated layered case with a main-relative underlay and overlay. - Use existing import/placement/version suites for unchanged semantics. - -Stage completion means prepared main sources behave as host main inputs across -ordinary and layered composition, metadata, and main-relative bindings. - -## Stage 6 — Implement configured bootstrap orchestration - -**Completed.** - -Add a focused engine companion in `secrets_from_config.go`, using the capture -and bootstrap helpers from earlier stages. - -1. Validate and snapshot options, resolve the main, capture its document and - context, and extract bootstrap settings. Return the no-directory and absent - cases under the public return contract. A valid Go overwrite override does - not bypass validation of malformed YAML bootstrap fields. -2. Join the declared directory to the captured base. Add an optional internal - containment-root constraint to shared directory preparation so canonical - resolution and containment validation occur before the worker uses that - canonical directory. Direct-directory calls supply no such constraint. -3. Select overwrite using Go, YAML, then false, and invoke the shared worker. - Return the prepared source only after successful bootstrap. All branches - return the non-nil report and appropriate existing error family. -4. Test no declaration, overwrite without a directory, optional/required missing - main, unsupported source/context, malformed controls, missing or outside-root - directory, and directory symlink containment. Assert empty/partial reports and - zero prepared sources on errors. Use the existing environment seam for - deterministic apply failures and verify safe error/report output. - -Stage completion means configured bootstrap can finish independently of schema, -imports, version hooks, resolution, and validation, returning a reusable main -only when its own operation succeeds. - -## Stage 7 — Expose root-owned APIs and convert both error families - -**Completed.** - -Work in root `secrets.go`, `source.go`, and existing facade conversion owners. - -1. Add the two options types and new functions with the signatures above. Keep - the existing function type intact and route its default behavior through the - shared bootstrap implementation. -2. Convert the companion's report, prepared engine Source, and errors to the - existing public wrappers. Preserve `LoadError` source records as well as - diagnostics. Preserve `SecretsError` without exposing underlying filesystem - or environment errors. Add only the small conversion logic this boundary - needs, reusing existing converters. -3. Document signatures, options precedence, reports, error types, and source - ownership on their declarations. Explain captured reuse versus File/SearchConfig - reuse in Source's documentation. Keep implementation types private. -4. Add facade tests for both new functions and assignment of the old function to - `func(string) (*SecretsReport, error)`. Exercise YAML true with explicit Go - false, YAML false with Go true, omitted choices, and multiple options. Verify - public `errors.As` behavior for preparation and bootstrap failures. - -Stage completion means applications can use the complete two-call startup flow -through ConfigKit's public package with the documented ownership and errors. - -## Stage 8 — Verify the complete startup handoff - -**Completed.** - -Extend public integration coverage and add one maintained consumer startup -example with ordinary and layered use explained from the same helper. - -1. Start in a different working directory, discover a main with relative secrets, - bootstrap all eligible entries including an SDK-only name, and load the - prepared source. Verify configured overwrite and existing empty-variable - behavior with disposable environment names. -2. Change the main, discovery candidates, an import, and an environment value - after preparation. Verify captured main values, live import values, fresh - environment lookup, and independent metadata/results across subsequent loads. - Include selected-main provenance and source resource context assertions. -3. Exercise the layered handoff with explicit root preparation and companion - inputs. Confirm compatible later context succeeds and incompatible context - fails safely after the already-completed bootstrap. -4. Show a later version/decoding or validation failure preserves the bootstrap - report and environment effects. Separately verify ordinary Load/LoadLayered - on a main containing the controls perform no environment writes, even with - YAML overwrite true. Existing secret-resolution tests continue to own - credential lookup and redaction behavior. -5. Verify captured sources retain no handles through successful and failed - preparation. Use existing resource-lifetime techniques and narrow seams, - avoiding a new filesystem framework. Exercise independent captured-source - loads under the race detector without concurrent process mutation. - -Stage completion means the feature works through normal entry points and its -integration risks are covered without duplicating every internal test at the -facade boundary. - -## Stage 9 — Update canonical documentation and validate the sprint - -**Completed.** - -1. Update `docs/config.md` with the two main controls, preparation and bootstrap - boundaries, lookup timing, overwrite precedence, reports/errors, host scope, - and prepared-source reuse/context behavior. Keep source-local controls - distinct from application paths and preserve existing loading semantics. -2. Update `docs/consumers/README.md` and its test map to link the new maintained - example. Update `docs/development.md` only where navigation/test ownership - changes. Explain internal capture and acquisition handoffs in - `docs/internal/overview.md` and relevant import documentation. -3. Update the implemented-behavior paragraphs in architecture policy and retire - its roadmap implementation-status link. Keep ADR 0023's accepted decision - text intact. Preserve the existing bootstrap limits and concurrency/rollback - contract while documenting explicit overwrite as the selected extension. -4. Format changed Go files and run the focused tests for changed owners. Run - `./scripts/check.sh` and `go test -race ./...` on the completed implementation. - Verify edited Markdown links and headings, exported declaration comments, - and the public example. Reuse successful checks for unchanged content. -5. Review the final diff for captured-state aliasing, handles, extra parsing or - discovery, secret disclosure, omitted accounting, and accidental changes to - current configuration processing or helper signatures. Resolve failures and - finish the documented target before marking the sprint complete. - -The final result is the implemented feature with current documentation and -appropriate behavioral coverage. Release preparation follows its separate -procedure when requested. diff --git a/docs/roadmap/secrets-directory.md b/docs/roadmap/secrets-directory.md deleted file mode 100644 index b4eb9cd..0000000 --- a/docs/roadmap/secrets-directory.md +++ /dev/null @@ -1,209 +0,0 @@ -# Main-relative secrets directories - -Status: implemented. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md) -supersedes ADR 0004 and records explicit configured bootstrap and optional -overwrite. The decisions below preserve ordinary loading without environment -writes and the existing direct-directory helper's Go signature. - -## Motivation and baseline - -Applications can use `SearchConfig` to select their main configuration file -during a load. They can also call `LoadSecretsIntoEnvironment` during startup, -but that helper takes a native directory path before the load begins. A relative -argument uses the process working directory. Using a directory beside the -discovered file therefore requires the application to take over main-file -selection or perform a preliminary load. [Configuration discovery](../config.md#configuration-discovery) · [Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap) - -ConfigKit already retains filesystem context for acquired main files and binds -companion inputs to that context. Typed `Secret` references read the environment -after application resolution and before final validation. A companion bootstrap -helper can use the main's context before loading while preserving this -processing order. [Main-relative contexts](../adr/0022-main-relative-context.md) · [Typed secret references](../config.md#typed-secret-references) - -## Target behavior - -### Declaration and path resolution - -An application explicitly calls a companion to -`LoadSecretsIntoEnvironment` before `Load` or `LoadLayered`. The selected main -document supplies the directory and overwrite policy through its root control -mapping. For example, the following declaration in `/etc/demo/config.yml` -selects `/etc/demo/secrets` and authorizes replacement of existing variables -when the companion helper is called. - -```yaml -config: - secrets_dir: secrets - secrets_overwrite: true - -api_key: DEMO_API_KEY -``` - -Interpret these fields at the main document's root before placement and -composition. They are bootstrap settings consumed as document controls. -`Load` and `LoadLayered` recognize the controls and perform their usual -environment lookup without invoking bootstrap. The companion helper call is -the explicit authorization for environment writes. - -Only the main document selects the bootstrap directory and YAML overwrite -policy. Diagnose these controls in unsupported source-control contexts. -Nested application data follows the existing `config` rules. Imports, -underlays, overlays, CLI overrides, and application resolution retain their -ordinary effects on application configuration. They do not redirect this -bootstrap operation. - -`secrets_overwrite` is an optional Boolean with a default of `false`. -An explicitly supplied Go overwrite choice takes precedence over YAML, -including when that choice is `false`. If the main supplies no directory, -bootstrap is a no-op and the prepared main can still be loaded. An optional -search that finds no main preserves the existing absent-main lifecycle. - -Resolve the directory from the selected main file's canonical base within its -existing filesystem root. For a discovered symlink, the base is the selected -file's canonical target directory. Parent-relative paths follow the same -containment rule as other main-relative inputs. The declaration must be a -nonempty relative path and requires a usable main-file context. Keep the -declaration and any diagnostics in source-local coordinates. [Document-root controls](../adr/0020-document-root-controls.md) · [Layered loading](../config.md#layered-loading) - -### Companion helper and prepared main source - -The companion accepts the main `Source`, including a `SearchConfig` source, -and returns a secrets report and a prepared main source. Its options accept an -explicit host `FilesystemContext` for main preparation and an optional overwrite -choice. Represent overwrite as `*bool`: nil defers to YAML, while a supplied -false or true takes precedence. The public names below are illustrative. - -```go -main := configkit.SearchConfig("demo", search) -report, preparedMain, err := configkit.LoadSecretsIntoEnvironmentFromConfig(main) -if err != nil { - // Handle the bootstrap failure and inspect report. - return err -} -result, err := configkit.Load[AppConfig](preparedMain) -``` - -For layered loading, supply the prepared source as the main `Input.Source`. -The helper resolves discovery once, reads the selected main document, extracts -the bootstrap controls, and performs bootstrap. It returns the captured main -contents with the selected file's identity and filesystem context so the later -load consumes that same main document. Keep its remaining controls, including -imports and collection declarations, available to normal loading. - -Apply the supplied host context using the existing main-file root rules during -preparation. Without an explicit context, derive the usual context from the -selected main file. Capture the resolved canonical base and containment root -with the document. Later loading uses that captured context when no explicit -context is supplied. An explicit later context must resolve to the same context; -diagnose an incompatible context rather than silently rebinding the prepared -source. A caller needing a different root prepares the original source again. -This rule applies to ordinary loading options and layered main `Input` alike. - -The helper prepares only the main document. Composition, import acquisition, -inheritance, typed decoding, application resolution, secret lookup, and -validation run through the subsequent ordinary or layered load. Main -preparation must retain the applicable source limits and root constraints. -Source records, diagnostics, placements, imports, and main-relative companions -use the selected main's identity and context. - -Release library-owned file handles before the helper returns, including on -error. Prepared sources are reusable snapshots of the main contents, with -passive filesystem context and no shared mutable load state. Reusing one neither -rediscovers nor rereads the main file and does not repeat bootstrap. This differs -from reusing the original `File` or `SearchConfig` source. Later imports and -resources observe the filesystem when accessed. A later load reads the environment -at its normal secret-resolution step. Each load accounts for the captured main -under its normal source limits and creates its own source and inspection records. -[Complete-on-return loading](../adr/0008-complete-on-return-loading.md) · [Source resource contexts](../config.md#source-resource-contexts) - -### Preparation failures and return values - -Use the existing error families at their respective boundaries. Discovery, -main-file acquisition, YAML parsing, bootstrap-control validation, and preparation -context failures return `LoadError` with applicable source records and source-local -diagnostics. Secret-directory inspection, reads, and environment writes return -`SecretsError` with the existing safe diagnostics. Do not introduce another error -or reporting framework. - -Return a secrets report on every attempt. Before directory processing begins, -it has no entries; after processing begins, it retains the entries and outcomes -observed so far. On any error, return a zero, unusable prepared `Source`. Earlier -environment writes remain reported and are not rolled back. A caller must handle -the failure before attempting configuration loading. - -On success, return a reusable prepared source, including when no directory was -declared. Optional search exhaustion returns the absent-main source and an empty -report. Preparation validates YAML and the bootstrap settings needed for its -operation; it does not claim the later configuration load will succeed. Normal -version checks, composition, decoding, and application validation remain in that -load. A later incompatible-context error is a loading error and does not undo -bootstrap writes. - -### Shared bootstrap and overwrite behavior - -Keep `LoadSecretsIntoEnvironment(string) (*SecretsReport, error)` unchanged, -including its nonvariadic function type and preservation behavior. Add a separately -named options-bearing helper for explicit overwrite. Changing the existing helper -to accept variadic options would preserve ordinary calls but break assignments to -its existing function type. The new public names below are provisional. - -```go -report, err := configkit.LoadSecretsIntoEnvironment("/etc/demo/secrets") -report, err = configkit.LoadSecretsIntoEnvironmentWithOptions( - "/etc/demo/secrets", - configkit.SecretsOptions{Overwrite: true}, -) -``` - -The existing helper, options-bearing helper, and main-config companion use the -same directory-bootstrap implementation. The direct helper's Boolean option -defaults to false; it has no YAML policy to override. With overwrite -disabled, existing variables win, including empty ones, with presence checked -again immediately before application as today. With overwrite enabled, -eligible files are read even for existing variables and their values replace -those variables. Variables without a corresponding file are left alone. -An applied empty file supplies an empty value in either mode. - -Bootstrap processes the directory's eligible entries, including credentials -used by SDKs or subprocesses outside typed `Secret` fields. Reuse the existing -dot-entry handling, file checks, content rules, limits, and filename ordering. -Validate metadata and read all content needed by the chosen overwrite policy -before beginning writes. -Directory and file failures produce the existing safe reporting behavior. -The secrets report identifies writes, skips, and partial failures without -retaining credential bytes. - -Call bootstrap during startup before starting concurrent work. Successful -bootstrap precedes configuration loading and validation. A later load failure -leaves the completed environment writes in place. A bootstrap write failure -stops further writes, leaves earlier writes in place, and reports remaining -entries as `not_applied`. The existing lack of rollback and concurrent -environment transaction guarantees continues to apply. - -Keep bootstrap reporting separate from the subsequent configuration's secret -lookup evidence. Each operation describes what it observed and performed. -[Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap) · [Explicit configured bootstrap](../adr/0023-explicit-configured-secrets-bootstrap.md) - -### Filesystem scope - -Support discovered and explicitly selected host files, including their existing -main-root options. This covers the requested deployment pattern and reuses the -native secret-file checks. Caller-supplied filesystem support is a possible -later extension requiring decisions about file-type and symlink capabilities. - -## Target integration - -Main-file selection and bounded capture are shared with normal acquisition. -The prepared source carries the main contents, identity, and context through -ordinary and layered loading with normal placement, accounting, and source -records. Directory bootstrap has one implementation behind the existing helper, -the options-bearing helper, and the configured companion. - -Canonical configuration and public source documentation describe the two-call -startup flow, capture lifetime, and overwrite policy. Consumer examples and -behavioral tests cover discovery, prepared-source reuse, relative inputs, -failure reporting, environment effects, and ordinary loading's boundaries under -the [testing policy](../policy/testing.md). - -The [implementation plan](implementation.md) owns the selected API names, -execution stages, and validation work needed to reach this target.