Interface ConfigPluginOptions

The opt-in value-free configuration provenance policy (M98e).

Present only when the developer explicitly opts in. An omitted option builds no provenance metadata, and the plugin registers an inert source whose snapshots report disabled. When present, the loader records, at the existing resolution steps, value-free provenance for the approved keys only: source category and approved source aliases, evidenced precedence overrides and ${NAME} expansion references, and schema input/output presence effects. No value, value hash, value length, file content, or validation payload is ever retained, and provenance adds no read to the configuration object.

loadConfig(runtime, { diagnostics }) builds the metadata with the snapshot; ConfigPlugin({ instance, diagnostics }) adopts the record when its exact instance was produced by this loader, and otherwise reports every approved alias with an unknown origin and schema effect. An adopted record is served exactly as the loader built it, under the loadConfig call's own approvals: the plugin's keys and files then decide nothing beyond enabling the source, and govern only the opaque case. Pass the same policy to both calls.

When true, a path in ConfigPluginOptions.envFilePath that does not exist is skipped instead of throwing. Defaults to false, which is the behaviour released in 0.1.0.

This exists for the layered-dotenv arrangement a scaffolded project uses: a gitignored .env beside a tracked .env.example. The file is present on the machine that generated it and absent on every fresh clone, in CI, and in a container built from the repository — so requiring it would make the project fail to start everywhere except its author's machine. A file that EXISTS but cannot be read still throws; only absence is tolerated.

Ignored when ConfigPluginOptions.instance is set.

Path or paths to .env files to load. Defaults to no file loading. When supplied, the runtime must provide fs (absent on edge platforms).

Ignored when ConfigPluginOptions.instance is set.

When true (default), expand ${NAME} references in values. Set to false to disable variable expansion.

Ignored when ConfigPluginOptions.instance is set.

An already-loaded configuration snapshot to use verbatim.

Present → nothing is read from the environment or from disk; envFilePath, envFileOptional, validationSchema, and expandVariables are ignored. Declared sections still validate through named reads on this exact object before it becomes the application's CAPABILITIES.CONFIG service. Absent → configuration is loaded normally.

This exists so configuration can be resolved BEFORE plugins are constructed — deciding which plugins to register from a value in the environment — without the application then loading a second snapshot. Two snapshots read at different moments can disagree, and the one the composer branched on would not be the one handlers read.

Typed sections to validate at startup after validationSchema has parsed the whole snapshot. Each section reads only its declared prefix-plus-key entries, then caches its schema output for getConfigSection.

Sections are also validated when instance is supplied. This keeps a preloaded snapshot and the application using it on the same safe path.

A structural schema (e.g., a Zod schema) for validating configuration at startup. When provided, the schema's parse() is called once after merging and expansion, and the parsed output is stored as the configuration snapshot. This preserves Zod coercions and defaults.

Ignored when ConfigPluginOptions.instance is set — the supplied snapshot has already been through whatever validation produced it.