@effected/config-file 0.1.0

package/ConfigProvider.js

@@ -0,0 +1,87 @@
+import { ConfigProvider, Effect } from "effect";
+
+//#region src/ConfigProvider.ts
+/**
+* Expose a loaded, merged, schema-validated document as a v4 `ConfigProvider`,
+* so it can be read through `Config.string("port")` and layered beneath other
+* providers.
+*
+* @remarks
+* Strictly additive, and deliberately in its own module so it never becomes a
+* required import. The schema-validated whole-document
+* {@link ConfigFileShape.load} remains the primary API: v4's `Config` has no
+* whole-document story, and this function is the bridge, not a replacement.
+*
+* Three properties, in order of how easy they are to lose:
+*
+* 1. **A missing file is a failure, not an empty provider.** The
+*    {@link ConfigFileNotFoundError} propagates. Handing back an empty provider
+*    would silently turn every subsequent `Config` read into "not found", which
+*    is the exact class of lie this port exists to undo.
+* 2. **Nested keys are structural, not dotted.** `fromUnknown` descends one path
+*    segment at a time, so `{ db: { host } }` is reached with
+*    `Config.nested(Config.string("host"), "db")` — never `Config.string("db.host")`,
+*    which is looked up as a single literal key and fails. No flattening happens
+*    here, because none is needed.
+* 3. **The decoded value is handed over as-is.** `fromUnknown` descends with
+*    `Object.hasOwn`, and a `Schema.Class` instance carries its fields as own
+*    properties, so no encoding step is required. The corollary: leaves are read
+*    in their **decoded** form, and a field whose decoded type is not a JSON
+*    primitive is exposed **structurally**, not turned into a value — with no
+*    two decoded types exposed the same way. A `Date` has no own enumerable
+*    properties, so it descends as an empty record and any nested read finds
+*    nothing. Such a field reports the same `ConfigError` as a missing key —
+*    `Expected string, got undefined` — so a `Config` read of a present `Date`
+*    field looks exactly like a typo in the key name. An `Option.some`
+*    descends as a record carrying Effect's internal `value` own-property, so
+*    `Config.nested(Config.string("value"), "field")` happens to read the
+*    wrapped value straight through — an internal representation, not a
+*    supported spelling. An `Option.none` has no own keys and so reads as
+*    absent, making `Some` and `None` asymmetric. None of this is a supported
+*    way to read such a field: `load` is the API that was designed to carry it.
+*
+* Descent by own property is also why a prototype getter and `__proto__` are
+* both unreachable through the returned provider.
+*
+* @example
+* ```ts
+* const fileProvider = yield* asConfigProvider(cfg);
+* const provider = ConfigProvider.orElse(ConfigProvider.fromEnv(), fileProvider);
+* ```
+*
+* @public
+*/
+const asConfigProvider = (service) => Effect.map(service.load, (value) => ConfigProvider.fromUnknown(value));
+/**
+* Install a loaded config document as a fallback beneath the **ambient**
+* `ConfigProvider`, so `Config` accessors read env first and the file second.
+*
+* @remarks
+* This is the composition the v3 library could not express. This layer
+* composes beneath the **ambient** `ConfigProvider`, v4's `Context.Reference`
+* for it, so a consumer supplying `ConfigProvider.layer(...)` controls
+* precedence explicitly: whatever that provider resolves wins, and the config
+* file supplies whatever it lacks. That reference's own default is
+* `ConfigProvider.fromEnv()`, which is what most applications want; this
+* module composes beneath whichever provider is ambient rather than pinning
+* that default itself, so verify the precedence you need with the provider
+* you actually wire in.
+*
+* The load happens when the layer is built, and a {@link ConfigFileNotFoundError}
+* surfaces in the layer's error channel rather than degrading to an empty
+* provider — the same honesty {@link asConfigProvider} keeps.
+*
+* @example
+* ```ts
+* const stack = layerConfigProvider(AppConfig).pipe(Layer.provide(AppConfigLive));
+* ```
+*
+* @public
+*/
+const layerConfigProvider = (tag, options) => {
+	const provider = Effect.flatMap(tag, asConfigProvider);
+	return ConfigProvider.layerAdd(provider, { asPrimary: options?.asPrimary });
+};
+
+//#endregion
+export { asConfigProvider, layerConfigProvider };

package/ConfigResolver.js

@@ -0,0 +1,95 @@
+import { Effect, FileSystem, Option, Path } from "effect";
+import { Walker } from "@effected/walker";
+
+//#region src/ConfigResolver.ts
+/** Absorb any failure into `Option.none()` — the resolver contract. */
+const absorb = (effect) => Effect.catch(effect, () => Effect.succeed(Option.none()));
+const cwdOf = (given) => given ?? globalThis.process?.cwd?.() ?? "/";
+const explicitPath = (target) => ({
+	name: "explicit",
+	resolve: absorb(Effect.gen(function* () {
+		return (yield* (yield* FileSystem.FileSystem).exists(target)) ? Option.some(target) : Option.none();
+	}))
+});
+const staticDir = (options) => ({
+	name: "static",
+	resolve: absorb(Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const candidate = (yield* Path.Path).join(options.dir, options.filename);
+		return (yield* fs.exists(candidate)) ? Option.some(candidate) : Option.none();
+	}))
+});
+const upwardWalk = (options) => ({
+	name: "walk",
+	resolve: Effect.gen(function* () {
+		const path = yield* Path.Path;
+		const subpaths = options.subpaths ?? ["."];
+		const dirs = yield* Walker.ascend(cwdOf(options.cwd), { ...options.stopAt !== void 0 && { stopAt: options.stopAt } });
+		return yield* Walker.findUpward(dirs, (dir) => subpaths.map((sub) => path.join(dir, sub, options.filename)));
+	})
+});
+/**
+* Ascend from `cwd` looking for the first directory where `isRoot` reports
+* true, then probe `subpaths` under it. Shared by `gitRoot` and
+* `workspaceRoot`, which differ only in how a "root" is detected.
+*/
+const rootAnchored = (name, isRoot, options) => ({
+	name,
+	resolve: Effect.gen(function* () {
+		const path = yield* Path.Path;
+		const dirs = yield* Walker.ascend(cwdOf(options.cwd));
+		const root = yield* Walker.findRoot(dirs, isRoot);
+		if (Option.isNone(root)) return Option.none();
+		const subpaths = options.subpaths ?? ["."];
+		return yield* Walker.findUpward([root.value], (dir) => subpaths.map((sub) => path.join(dir, sub, options.filename)));
+	})
+});
+/** `.git` may be a directory (a normal repo) or a file (a worktree pointing at the real repo). */
+const isGitRoot = (dir) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	return yield* fs.exists(path.join(dir, ".git"));
+});
+/** A workspace root is marked by `pnpm-workspace.yaml`, or a `package.json` with a `workspaces` field. */
+const isWorkspaceRoot = (dir) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	if (yield* fs.exists(path.join(dir, "pnpm-workspace.yaml"))) return true;
+	const pkgPath = path.join(dir, "package.json");
+	if (yield* fs.exists(pkgPath)) {
+		const content = yield* fs.readFileString(pkgPath);
+		try {
+			if ("workspaces" in JSON.parse(content)) return true;
+		} catch {}
+	}
+	return false;
+});
+const gitRoot = (options) => rootAnchored("git", isGitRoot, options);
+const workspaceRoot = (options) => rootAnchored("workspace", isWorkspaceRoot, options);
+const systemEtc = (options) => ({
+	name: "system",
+	resolve: absorb(Effect.gen(function* () {
+		if (globalThis.process?.platform === "win32") return Option.none();
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const base = options.dir ?? "/etc";
+		const candidate = path.join(base, options.app, options.filename);
+		return (yield* fs.exists(candidate)) ? Option.some(candidate) : Option.none();
+	}))
+});
+/**
+* Built-in resolvers, in the order a typical chain uses them.
+*
+* @public
+*/
+const ConfigResolver = {
+	explicitPath,
+	staticDir,
+	upwardWalk,
+	workspaceRoot,
+	gitRoot,
+	systemEtc
+};
+
+//#endregion
+export { ConfigResolver };

package/EncryptedCodec.js

@@ -0,0 +1,123 @@
+import { decrypt, deriveKey, encrypt, fromBase64, randomIv, toBase64 } from "./internal/crypto.js";
+import { Duration, Effect, Exit, Schema } from "effect";
+
+//#region src/EncryptedCodec.ts
+/**
+* Indicates that an encryption, decryption, key-derivation or base64 step
+* failed.
+*
+* @remarks
+* Its own error rather than v3's `"key-derivation"` value on the generic
+* `ConfigCodecError.operation` union — an encryption-only concern was leaking
+* into every codec's error type. `cause` preserves the underlying host failure
+* structurally; v3 assembled it into a prose `reason` string.
+*
+* @public
+*/
+var ConfigEncryptionError = class extends Schema.TaggedErrorClass()("ConfigEncryptionError", {
+	/** Which cryptographic stage failed. */
+	phase: Schema.Literals([
+		"key-derivation",
+		"encrypt",
+		"decrypt",
+		"encoding"
+	]),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Config encryption failed during ${this.phase}`;
+	}
+};
+/** Lift `internal/crypto`'s dependency-free failure into the public error. */
+const toPublic = (failure) => new ConfigEncryptionError({
+	phase: failure.phase,
+	cause: failure.cause
+});
+/**
+* Convenience constructors for {@link (EncryptedCodecKey:type)}.
+*
+* @public
+*/
+const EncryptedCodecKey = {
+	/**
+	* Use a pre-derived `CryptoKey` effect directly.
+	*
+	* @remarks
+	* The effect is resolved once per codec instance and its **success** is
+	* reused for every encrypt/decrypt operation. A failure or an interruption
+	* is not cached — the next operation resolves it again. Supply your own
+	* `Effect.retry` inside this effect to bound retries; wrap it in
+	* `Effect.cached` yourself if you want a failure to be terminal.
+	*
+	* A `throw` from it is a programmer bug and stays a defect; signal
+	* recoverable failure with `Effect.fail`.
+	*/
+	fromCryptoKey: (key) => ({
+		_tag: "CryptoKey",
+		key
+	}),
+	/**
+	* Derive a `CryptoKey` from a passphrase and salt via PBKDF2.
+	*
+	* @remarks
+	* Derivation runs lazily on the first encrypt/decrypt call. It is resolved
+	* once per codec instance and its **success** is reused for subsequent
+	* operations on that instance. A failure or an interruption is not cached —
+	* the next operation derives again.
+	*/
+	fromPassphrase: (passphrase, salt) => ({
+		_tag: "Passphrase",
+		passphrase,
+		salt
+	})
+};
+/** The key effect a codec instance resolves against, before memoization. */
+const keyEffect = (keySource) => keySource._tag === "CryptoKey" ? keySource.key : Effect.mapError(deriveKey(keySource.passphrase, keySource.salt), toPublic);
+/**
+* Wrap any {@link (ConfigCodec:interface)} with AES-GCM encryption.
+*
+* @remarks
+* `stringify` serializes with the inner codec, generates a random 12-byte IV,
+* encrypts, prepends the IV to the ciphertext and base64-encodes the result.
+* `parse` reverses that: the first 12 bytes of the decoded envelope are the IV,
+* the remainder is the ciphertext, and the plaintext is handed to the inner
+* codec's `parse`.
+*
+* The error channel **widens** to `E | ConfigEncryptionError` rather than
+* flattening — the inner codec's failures stay distinguishable from
+* cryptographic ones.
+*
+* @public
+*/
+function EncryptedCodec(inner, keySource) {
+	const name = `encrypted(${inner.name})`;
+	const [resolveKey, invalidateKey] = Effect.runSync(Effect.cachedInvalidateWithTTL(keyEffect(keySource), Duration.infinity));
+	const getKey = Effect.onExit(resolveKey, (exit) => Exit.isSuccess(exit) ? Effect.void : invalidateKey);
+	return {
+		name,
+		parse: (raw) => Effect.gen(function* () {
+			const combined = yield* Effect.mapError(fromBase64(raw), toPublic);
+			if (combined.length <= 12) return yield* Effect.fail(new ConfigEncryptionError({
+				phase: "decrypt",
+				cause: /* @__PURE__ */ new Error("Ciphertext too short to contain IV")
+			}));
+			const key = yield* getKey;
+			const iv = combined.slice(0, 12);
+			const ciphertext = combined.slice(12);
+			const plaintext = yield* Effect.mapError(decrypt(key, iv, ciphertext), toPublic);
+			return yield* inner.parse(new TextDecoder().decode(plaintext));
+		}),
+		stringify: (value) => Effect.gen(function* () {
+			const key = yield* getKey;
+			const serialized = yield* inner.stringify(value);
+			const encoded = new TextEncoder().encode(serialized);
+			const iv = randomIv();
+			const ciphertext = yield* Effect.mapError(encrypt(key, iv, encoded), toPublic);
+			return yield* Effect.mapError(toBase64(iv, ciphertext), toPublic);
+		})
+	};
+}
+
+//#endregion
+export { ConfigEncryptionError, EncryptedCodec, EncryptedCodecKey };

package/JsonCodec.js

@@ -0,0 +1,38 @@
+import { ConfigCodecError } from "./ConfigCodec.js";
+import { Effect } from "effect";
+
+//#region src/JsonCodec.ts
+/**
+* A `ConfigCodec` backed by the host `JSON` global: plain JSON as
+* configuration file content.
+*
+* @remarks
+* The only codec that reaches no parsing engine at all — it is why this
+* package can be depended on for JSON config alone without pulling a parser
+* into the bundle. Both directions preserve the underlying failure
+* structurally in `cause` — never stringified.
+*
+* @public
+*/
+const JsonCodec = {
+	name: "json",
+	parse: (raw) => Effect.try({
+		try: () => JSON.parse(raw),
+		catch: (cause) => new ConfigCodecError({
+			codec: "json",
+			operation: "parse",
+			cause
+		})
+	}),
+	stringify: (value) => Effect.try({
+		try: () => JSON.stringify(value, null, 2),
+		catch: (cause) => new ConfigCodecError({
+			codec: "json",
+			operation: "stringify",
+			cause
+		})
+	})
+};
+
+//#endregion
+export { JsonCodec };

package/JsoncCodec.js

@@ -0,0 +1,38 @@
+import { ConfigCodecError } from "./ConfigCodec.js";
+import { Effect } from "effect";
+import { Jsonc } from "@effected/jsonc";
+
+//#region src/JsoncCodec.ts
+/**
+* A `ConfigCodec` backed by `@effected/jsonc`: JSON with comments and
+* trailing commas.
+*
+* @remarks
+* `@effected/jsonc` does not expose a `stringify` — its schema layer's encode
+* direction is `JSON.stringify` (comments never survive a round-trip encode;
+* see `Jsonc.fromString`'s remarks), so `stringify` here calls `JSON.stringify`
+* directly and wraps a thrown defect the same way `JsonCodec` does.
+* Both directions preserve the underlying failure structurally in `cause` —
+* never stringified.
+*
+* @public
+*/
+const JsoncCodec = {
+	name: "jsonc",
+	parse: (raw) => Jsonc.parse(raw).pipe(Effect.mapError((cause) => new ConfigCodecError({
+		codec: "jsonc",
+		operation: "parse",
+		cause
+	}))),
+	stringify: (value) => Effect.try({
+		try: () => JSON.stringify(value, null, 2),
+		catch: (cause) => new ConfigCodecError({
+			codec: "jsonc",
+			operation: "stringify",
+			cause
+		})
+	})
+};
+
+//#endregion
+export { JsoncCodec };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MergeStrategy.js

@@ -0,0 +1,53 @@
+import { canMerge, deepMerge } from "./internal/deepMerge.js";
+import { Effect } from "effect";
+
+//#region src/MergeStrategy.ts
+const firstMatch = () => ({
+	name: "first-match",
+	resolve: (sources) => Effect.succeed(sources[0].value)
+});
+/**
+* Deep-merge every contributing source, higher priority winning on conflict.
+*
+* @remarks
+* Two values merge only when both are record-like and share a prototype, so a
+* document decoded through `Schema.Class` merges with another of the same class
+* and **survives as a real instance** — `instanceof` holds and its getters
+* still work. Everything else is atomic: a nested `Date`, `Map`, `Set`,
+* `RegExp`, array, or class instance is taken whole from the highest-priority
+* source that defines it, never reshaped field-by-field.
+*
+* The alternative — spreading each value into a fresh object — would make
+* `load`'s declared `Effect<A>` a lie, handing back a structurally-equal plain
+* object whose class methods are gone and whose `Date` fields have decayed to
+* `{}`.
+*
+* Nested *plain* objects (a `Schema.Struct` section) still merge field-wise.
+*/
+const layeredMerge = () => ({
+	name: "layered-merge",
+	resolve: (sources) => {
+		let merged = sources[sources.length - 1]?.value;
+		for (let i = sources.length - 2; i >= 0; i--) {
+			const higher = sources[i]?.value;
+			merged = canMerge(merged, higher) ? deepMerge(higher, merged) : higher;
+		}
+		return Effect.succeed(merged);
+	}
+});
+/**
+* Built-in merge strategies.
+*
+* @remarks
+* Renamed from v3's `ConfigWalkStrategy`, which never walked anything — the
+* thing that walks is the `upwardWalk` resolver.
+*
+* @public
+*/
+const MergeStrategy = {
+	firstMatch,
+	layeredMerge
+};
+
+//#endregion
+export { MergeStrategy };

package/README.md

@@ -0,0 +1,176 @@
+# @effected/config-file
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fconfig-file?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/config-file)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Composable config file loading for Effect. Declare a resolver chain — an explicit path, an upward walk from the cwd, the workspace or git root, `/etc` — decode every discovered file through an Effect `Schema`, and combine the results with a merge strategy. JSON, JSONC, YAML and TOML all decode with no extra install. Codecs, resolvers and merge strategies are pluggable seams, and failures arrive as tagged errors carrying structured payloads rather than prose, so "no config anywhere" is routable separately from "the config I found is broken".
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 beta. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/config-file
+
+Config loading is where a well-typed application usually gives up: a library finds a file, parses it, validates it, and reports every one of those distinct failures as the same opaque error with a `reason` string. This package refuses that. Discovery, reading, parsing, validation and persistence each fail with their own tagged error, and each carries its cause structurally — a `ConfigValidationError` hands you the schema issue tree, not `String(ParseError)`. Resolver requirements flow into the layer's type rather than being cast away, the merge step reports every source that contributed rather than only the first, and a loaded document can be handed to `Config` accessors as a v4 `ConfigProvider` layered beneath the environment.
+
+## Install
+
+```bash
+npm install @effected/config-file effect @effect/platform-node
+```
+
+```bash
+pnpm add @effected/config-file effect @effect/platform-node
+```
+
+Requires Node.js >=24.11.0. Every format is covered by that one install; there is no separate package to add for YAML or TOML.
+
+`effect` v4 is a peer dependency, and so are `@effected/jsonc`, `@effected/toml`, `@effected/walker` and `@effected/yaml` — the first-party engines behind the JSONC, YAML and TOML codecs, plus the traversal primitive the `upwardWalk`, `workspaceRoot` and `gitRoot` resolvers are built on. Package managers that install peers automatically will pull them in; add them to your manifest explicitly if yours does not. The package declares no runtime dependencies of its own, so nothing it drags into your tree comes from outside `effect` and `@effected/*`.
+
+Reading and writing files needs a `FileSystem` and a `Path` implementation, provided once at the edge — from `@effect/platform-node` on Node.
+
+## Quick start
+
+Declare a schema, mint a service class for it with `ConfigFile.Service`, and build its live layer with `ConfigFile.layer`. The platform layers are provided once, at the edge:
+
+```ts
+import { ConfigFile, ConfigResolver, JsonCodec, MergeStrategy } from "@effected/config-file";
+import { NodeFileSystem, NodePath } from "@effect/platform-node";
+import { Effect, Layer, Schema } from "effect";
+
+class AppShape extends Schema.Class<AppShape>("AppShape")({
+  port: Schema.Number,
+  host: Schema.String,
+}) {}
+
+class AppConfig extends ConfigFile.Service<AppConfig, AppShape>()("app/Config") {}
+
+const AppConfigLive = ConfigFile.layer(AppConfig, {
+  schema: AppShape,
+  codec: JsonCodec,
+  resolvers: [ConfigResolver.upwardWalk({ filename: ".apprc" })],
+  strategy: MergeStrategy.firstMatch<AppShape>(),
+});
+
+const program = Effect.gen(function* () {
+  const config = yield* AppConfig;
+  return yield* config.load;
+});
+
+const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer);
+
+Effect.runPromise(program.pipe(Effect.provide(AppConfigLive), Effect.provide(PlatformLive))).then(console.log);
+// AppShape { port: 3000, host: "localhost" }
+```
+
+`ConfigFile.layer` is a layer-returning *function*, not a layer: calling it twice builds two independent service instances. Bind its result to a const, as above, and provide that const.
+
+Resolvers are consulted in priority order, highest first. `MergeStrategy.firstMatch` takes the winner; `MergeStrategy.layeredMerge` deep-merges every source that matched, with higher-priority keys overwriting lower ones:
+
+```ts
+import { ConfigFile, ConfigResolver, MergeStrategy, YamlCodec } from "@effected/config-file";
+import { Schema } from "effect";
+
+class Settings extends Schema.Class<Settings>("Settings")({ port: Schema.Number }) {}
+class SettingsConfig extends ConfigFile.Service<SettingsConfig, Settings>()("app/Settings") {}
+
+export const SettingsLive = ConfigFile.layer(SettingsConfig, {
+  schema: Settings,
+  codec: YamlCodec,
+  resolvers: [
+    ConfigResolver.upwardWalk({ filename: ".apprc.yaml" }),
+    ConfigResolver.workspaceRoot({ filename: ".apprc.yaml" }),
+    ConfigResolver.systemEtc({ app: "myapp", filename: "config.yaml" }),
+  ],
+  strategy: MergeStrategy.layeredMerge<Settings>(),
+});
+```
+
+## Errors
+
+Every failure is a tagged error you route on with `Effect.catchTag`. The tags exist so that recovery can differ:
+
+| Tag | Means | Recovery |
+| --- | --- | --- |
+| `ConfigFileNotFoundError` | The resolver chain matched nothing. Carries `searched`, the resolver names probed. | Fall back to defaults — the one failure that is often not an error. `loadOrDefault` handles it for you. |
+| `ConfigFileReadError` | A file was found but could not be read. Carries `path` and the structural `cause`. | Usually fatal: the file exists and the process cannot read it. Check permissions. |
+| `ConfigFileWriteError` | A file could not be written. Carries `path` and the structural `cause`. | Retry elsewhere, or surface to the user. |
+| `ConfigDefaultPathMissingError` | `save` or `update` was called on a service configured without a `defaultPath`. | A wiring bug, not a data condition. Fix the layer, or call `write` with an explicit path. |
+| `ConfigValidationError` | The document did not satisfy the schema, or a caller-supplied `validate` rejected it. Carries the structured `issue` tree and an optional `path`. | Report the issue; do not run on config you could not validate. |
+| `ConfigCodecError` | The codec could not parse or stringify. Carries `codec`, `operation` and the structural `cause`. | The file is corrupt. Report the path and the cause. |
+| `ConfigMigrationError` | A versioned migration failed. Carries `version`, `name`, `phase` and the structural `cause`. | Report which step failed; the config on disk is left untouched. |
+| `ConfigEncryptionError` | An encrypt, decrypt, key-derivation or base64 step failed. Carries `phase` and the structural `cause`. | A wrong passphrase and a corrupt envelope both land here; inspect `phase`. |
+
+`ConfigLoadError`, `ConfigReadError`, `ConfigWriteError`, `ConfigSaveError` and `ConfigUpdateError` are exported unions naming exactly the failures each method can produce. Catching one tag narrows the union, leaving the rest to propagate:
+
+```ts
+import type { ConfigFileShape } from "@effected/config-file";
+import { Effect, Schema } from "effect";
+
+class AppShape extends Schema.Class<AppShape>("AppShape")({ port: Schema.Number }) {}
+
+const fallback = new AppShape({ port: 3000 });
+
+// `load` fails with ConfigLoadError. Handling the not-found tag leaves
+// ConfigReadError — the file-is-broken failures, which we let propagate.
+export const loadOrFallback = (config: ConfigFileShape<AppShape>) =>
+  config.load.pipe(Effect.catchTag("ConfigFileNotFoundError", () => Effect.succeed(fallback)));
+```
+
+## Codecs
+
+Four codecs ship in the package, each a free-standing named export:
+
+| Codec | Format | Engine |
+| ----- | ------ | ------ |
+| `JsonCodec` | JSON | the host `JSON` global, no parser at all |
+| `JsoncCodec` | JSONC | `@effected/jsonc` |
+| `YamlCodec` | YAML | `@effected/yaml` |
+| `TomlCodec` | TOML | `@effected/toml` |
+
+One install covers every format, and you still pay only for the parser you name. The codecs are free-standing exports rather than properties of a namespace object, so importing `TomlCodec` never references the YAML or JSONC bindings, their parsing engines are unreachable from your entrypoint and a bundler drops them. A JSON-only application ships no parser at all.
+
+Codecs compose. `EncryptedCodec` wraps any codec with AES-GCM, and `ConfigMigration.make` wraps any codec so parsed content is brought up to the latest version. Each *widens* the error channel rather than flattening its failures into the inner codec's error:
+
+```ts
+import { ConfigMigration, EncryptedCodec, EncryptedCodecKey, JsonCodec } from "@effected/config-file";
+import { Effect } from "effect";
+
+const migrating = ConfigMigration.make({
+  codec: JsonCodec,
+  migrations: [
+    {
+      version: 2,
+      name: "add-port",
+      up: (raw) => Effect.succeed({ ...(raw as Record<string, unknown>), port: 8080 }),
+    },
+  ],
+});
+
+// `parse` now fails with ConfigCodecError | ConfigMigrationError | ConfigEncryptionError.
+export const secret = EncryptedCodec(migrating, EncryptedCodecKey.fromPassphrase("hunter2", new Uint8Array(16)));
+```
+
+## Features
+
+- `ConfigFile.Service` / `ConfigFile.layer` / `ConfigFile.testLayer` — a per-schema service class and its layers. `testLayer` seeds files into a temp directory and wires the *real* implementation over them, so tests exercise the actual pipeline rather than a stub that can drift from it.
+- `ConfigResolver` — `explicitPath`, `staticDir`, `upwardWalk`, `workspaceRoot`, `gitRoot` and `systemEtc`. A resolver's error channel is `never` by contract: every filesystem failure becomes `Option.none()`, so one unreadable tier never aborts the chain.
+- `MergeStrategy` — `firstMatch` and `layeredMerge`, combining discovered sources in priority order.
+- `JsonCodec`, `JsoncCodec`, `YamlCodec`, `TomlCodec` — JSON, JSONC, YAML and TOML in the box, exported free-standing so an unused format's engine is tree-shaken away.
+- `ConfigCodec` / `EncryptedCodec` / `ConfigMigration` — a pluggable codec seam, generic in its error type so decorators widen rather than flatten. `ConfigCodec` is the interface: bring your own format by satisfying it.
+- `ConfigEvents` — an opt-in `PubSub` of `ConfigEvent`, honestly zero-cost when omitted: no `events` option means no context lookup at all. Failure events carry the structured typed error, never a `reason` string.
+- `asConfigProvider` / `layerConfigProvider` — expose a loaded, validated document as a v4 `ConfigProvider`, layered beneath the ambient one so an environment variable overrides the file it was deployed with.
+
+## License
+
+[MIT](LICENSE)

package/TomlCodec.js

@@ -0,0 +1,39 @@
+import { ConfigCodecError } from "./ConfigCodec.js";
+import { Effect } from "effect";
+import { Toml } from "@effected/toml";
+
+//#region src/TomlCodec.ts
+/**
+* A `ConfigCodec` backed by `@effected/toml`.
+*
+* @remarks
+* `@effected/toml`'s input hardening — a nesting-depth cap on arrays and
+* inline tables, enforced independently on both the parse and stringify
+* sides — fails through the typed error channel, so a hostile config file
+* surfaces as a `ConfigCodecError` rather than crashing the process. Both
+* directions preserve the underlying failure structurally in `cause` —
+* never stringified.
+*
+* Stringify is genuinely fallible beyond hostile input: TOML has no null,
+* so a document carrying `null` (or any other unrepresentable value, an
+* out-of-int64-range `bigint`, a circular reference) fails with a
+* `ConfigCodecError` whose `cause` is the structured `TomlStringifyError`.
+*
+* @public
+*/
+const TomlCodec = {
+	name: "toml",
+	parse: (raw) => Toml.parse(raw).pipe(Effect.mapError((cause) => new ConfigCodecError({
+		codec: "toml",
+		operation: "parse",
+		cause
+	}))),
+	stringify: (value) => Toml.stringify(value).pipe(Effect.mapError((cause) => new ConfigCodecError({
+		codec: "toml",
+		operation: "stringify",
+		cause
+	})))
+};
+
+//#endregion
+export { TomlCodec };