@effected/app 0.20.0 → 0.21.0

package/App.js

@@ -15,11 +15,11 @@ const testPaths = () => XdgPaths.make({
 	configDirs: ["/etc/xdg"],
 	dataDirs: ["/usr/local/share", "/usr/share"]
 });
+const layerDirs = (options) => Layer.provideMerge(AppDirs.layer(options), Xdg.layer);
 const layer = (options) => {
 	const { store, cache, ...dirOptions } = options;
-	const dirs = Layer.provideMerge(AppDirs.layer(dirOptions), Xdg.layer);
 	const databases = Layer.mergeAll(AppStore.layer(store), AppCache.layer(cache));
-	return Layer.provideMerge(databases, dirs);
+	return Layer.provideMerge(databases, layerDirs(dirOptions));
 };
 const layerTest = (options) => {
 	const dirs = Layer.provideMerge(AppDirs.layer({ namespace: options.namespace }), Xdg.layerFrom(options.paths ?? testPaths()));
@@ -44,10 +44,29 @@ var App = class {
 	* so all four services come out and only `FileSystem` and `Path` stay in `R` —
 	* the two the consumer's platform layer supplies once, at the edge.
 	*
-	* `App.layer` always provides **both** databases: an application that wants
-	* only one composes `AppStore.layer` or `AppCache.layer` directly and never
-	* opens the other file. Passing no `cache` options still opens `cache.db`,
-	* because `CacheOptions` are all-optional and absence means defaults.
+	* `App.layer` always provides **both** databases, and **building it opens
+	* and migrates both eagerly** — `store.db` and `cache.db` exist on disk the
+	* moment the layer is built, whether or not the program ever touches them.
+	* Passing no `cache` options still opens `cache.db`, because `CacheOptions`
+	* are all-optional and absence means defaults. An application that wants
+	* only one composes {@link App.layerDirs} with `AppStore.layer` or
+	* `AppCache.layer` and never opens the other file.
+	*
+	* A CLI should therefore not provide `App.layer` at its entry point: every
+	* command, `--help`-adjacent paths included, would create and migrate both
+	* databases, and a command that deletes the app's files would delete a
+	* database its own process holds open. Provide {@link App.layerDirs} once at
+	* the platform edge instead, bind `AppStore.layer(...)` / `AppCache.layer(...)`
+	* once at module scope, and attach them with `Command.provide` only on the
+	* commands that use them — see the second example.
+	*
+	* A module-scope binding such as `StoreLive` stays ONE connection however
+	* many composites reuse it inside one provided layer graph —
+	* `Layer.mergeAll(StoreLive, …)` beside `Repo.pipe(Layer.provide(StoreLive))`
+	* — because a layer graph memoises by reference, and an `Effect.provide`
+	* nested inside another reuses what the enclosing one already built.
+	* Provides that are not nested — one after another, or side by side under a
+	* common parent — each build it, and so open the database, again.
 	*
 	* This is a layer-returning function: bind the result to a `const` once and
 	* reuse that binding. Calling it inline at two provide sites opens two
@@ -75,9 +94,89 @@ var App = class {
 	* 	Layer.provide(NodeServices.layer),
 	* );
 	* ```
+	*
+	* @example
+	* Databases per command, directories everywhere — the CLI shape:
+	* ```ts
+	* import { App, AppStore } from "@effected/app";
+	* import { CliRuntime } from "@effected/cli";
+	* import type { StoreMigration } from "@effected/store";
+	* import { Store } from "@effected/store";
+	* import { NodeRuntime, NodeServices } from "@effect/platform-node";
+	* import { Effect, Layer } from "effect";
+	* import { Command } from "effect/cli";
+	*
+	* const migrations: ReadonlyArray<StoreMigration> = [
+	* 	{ id: 1, name: "runs", up: (sql) => sql`CREATE TABLE runs (id TEXT PRIMARY KEY)` },
+	* ];
+	*
+	* // Module scope, bound once: built once per provided layer graph.
+	* const StoreLive = AppStore.layer({ migrations });
+	*
+	* // Opens store.db — only when `history` runs.
+	* const history = Command.make("history", {}, () =>
+	* 	Effect.gen(function* () {
+	* 		const store = yield* Store;
+	* 		yield* store.client`SELECT id FROM runs`;
+	* 	}),
+	* ).pipe(Command.provide(StoreLive));
+	*
+	* // Opens no database at all.
+	* const where = Command.make("where", {}, () => Effect.void);
+	*
+	* const cli = Command.make("myapp").pipe(Command.withSubcommands([history, where]));
+	*
+	* // Directories at the edge, once; AppDirs satisfies StoreLive's requirement.
+	* const PlatformLive = App.layerDirs({ namespace: "myapp" }).pipe(Layer.provideMerge(NodeServices.layer));
+	*
+	* NodeRuntime.runMain(CliRuntime.main(Command.run(cli, { version: "1.0.0" }), { platform: PlatformLive }));
+	* ```
 	*/
 	static layer = layer;
 	/**
+	* Build the directories half of the control plane alone: `Xdg` and
+	* `AppDirs` for one namespace, with no database opened.
+	*
+	* @remarks
+	* Exactly the directory composition {@link App.layer} builds on —
+	* `AppDirs.layer(options)` `provideMerge` `Xdg.layer` — lifted out so an
+	* application can provide "directories everywhere" at its edge and attach
+	* the databases only where they are used. Building it resolves the XDG
+	* environment and nothing else: no directory is created until an `ensure*`
+	* member runs, and no SQLite file is touched. Its output satisfies the
+	* `AppDirs` requirement of `AppStore.layer`, `AppStore.layerAs`,
+	* `AppCache.layer`, `AppCache.layerAs` and `AppConfig.layer`.
+	*
+	* The error channel is `XdgEnvError` alone — an unset `HOME` — and `R` is
+	* the `FileSystem` and `Path` a platform layer supplies once. `options` is
+	* `AppDirsOptions` pass-through: `namespace`, `native`, `fallbackDir` and
+	* `dirs` mean exactly what `@effected/xdg` documents.
+	*
+	* This is a layer-returning function: bind the result to a `const` once and
+	* reuse that binding.
+	*
+	* @example
+	* ```ts
+	* import { App, AppStore } from "@effected/app";
+	* import { NodeServices } from "@effect/platform-node";
+	* import { AppDirs } from "@effected/xdg";
+	* import { Effect, Layer } from "effect";
+	*
+	* // Bound once, to a const: XDG directories for "myapp", no databases.
+	* const DirsLive = App.layerDirs({ namespace: "myapp" }).pipe(Layer.provideMerge(NodeServices.layer));
+	*
+	* const program = Effect.gen(function* () {
+	* 	const dirs = yield* AppDirs;
+	* 	return dirs.dirs.state; // resolved, not created
+	* });
+	*
+	* // A database, attached where it is wanted, over the same directories.
+	* const StoreLive = AppStore.layer({ migrations: [] });
+	* const withStore = program.pipe(Effect.provide(StoreLive), Effect.provide(DirsLive));
+	* ```
+	*/
+	static layerDirs = layerDirs;
+	/**
 	* The hermetic control plane: fixed XDG paths, `:memory:` databases, and the
 	* platform layers provided internally.
 	*

package/AppCache.js

@@ -1,45 +1,121 @@
-import { badFilename } from "./internal/filename.js";
+import { ensureLocation, resolveLocation } from "./internal/location.js";
 import { Cache } from "@effected/store";
-import { AppDirs } from "@effected/xdg";
-import { Effect, Layer, Path } from "effect";
+import { Effect, Layer } from "effect";
 
 //#region src/AppCache.ts
-const layer = (options) => Layer.unwrap(Effect.gen(function* () {
-	const opts = options ?? {};
-	const filename = opts.filename ?? "cache.db";
-	const invalid = badFilename("AppCache.layer", filename);
-	if (invalid !== void 0) return yield* Effect.die(invalid);
-	const appDirs = yield* AppDirs;
-	const path = yield* Path.Path;
-	const cacheDir = yield* appDirs.ensureCache;
-	return Cache.layerSqlite({
-		...opts,
-		filename: path.join(cacheDir, filename)
+/** The one derivation of the file's location, shared by `location` and both layers. */
+const locate = (context, options) => {
+	const { filename = "cache.db", directory = "cache", subdir } = options ?? {};
+	return resolveLocation(context, directory, subdir, filename);
+};
+const build = (context, options, open) => Layer.unwrap(Effect.gen(function* () {
+	const { filename: _filename, directory: _directory, subdir: _subdir, ...rest } = options ?? {};
+	const location = yield* locate(context, options);
+	yield* ensureLocation(location);
+	return open({
+		...rest,
+		filename: location.file
 	});
 }));
+const location = (options) => Effect.map(locate("AppCache.location", options), (resolved) => resolved.file);
+const layer = (options) => build("AppCache.layer", options, Cache.layerSqlite);
+const layerAs = (tag, options) => build("AppCache.layerAs", options, (resolved) => Cache.layerSqliteAs(tag, resolved));
 /**
-* The cache-directory database glue: a TTL `Cache` whose file lives in the
-* ambient `AppDirs` cache directory.
+* The cache database glue: a TTL `Cache` whose file lives in one of the
+* ambient `AppDirs` directories — the cache directory unless told otherwise.
 *
 * @public
 */
 var AppCache = class {
 	constructor() {}
 	/**
-	* Build the cache-directory database layer: `AppDirs.ensureCache`, then
-	* `Cache.layerSqlite` at `<cache dir>/<filename>`.
+	* Build the cache database layer: ensure `<directory>[/<subdir>]`, then
+	* `Cache.layerSqlite` at `<directory>[/<subdir>]/<filename>` — by default
+	* `AppDirs.ensureCache` and `<cache dir>/cache.db`.
 	*
 	* @remarks
 	* The same ensure-before-open ordering as `AppStore.layer`, and it matters
 	* *more* here: the cache directory is the one an operator is most likely to
 	* have deleted between runs. `options` is optional because every
-	* `CacheOptions` field is.
+	* `CacheOptions` field is. A `subdir` is created with a recursive `mkdir`
+	* after the directory is ensured — that is why `FileSystem` is in `R` — and
+	* its failure lands on the same typed `AppDirsError`.
 	*
 	* This is a layer-returning function: bind the result to a `const` and reuse
 	* that binding, or memoization by reference is lost and the database is
 	* opened twice.
 	*/
 	static layer = layer;
+	/**
+	* Build an additional cache under a service key the consumer defines: the
+	* same ensure-before-open glue as {@link AppCache.layer}, over
+	* `Cache.layerSqliteAs`, provided as `I` instead of `Cache`.
+	*
+	* @remarks
+	* For an application that keeps more than one cache — each with its own
+	* file, size bound, TTL default and `CacheEvent` stream. `tag` is a
+	* consumer-defined `Context.Service` whose service type is `CacheShape`.
+	* An incompatible shape is a compile error, and so is one that adds members
+	* (`CacheShape & { … }`), reported as an argument "not assignable to
+	* parameter of type 'never'". The check cannot see through method-syntax
+	* parameter bivariance: a member redeclared as a method with a wider
+	* parameter still compiles. The
+	* output is `I` alone: the `Cache` built internally never leaks, so
+	* `layerAs` composes beside `AppCache.layer` without either shadowing the
+	* other.
+	*
+	* `filename` is **required** here, unlike on `AppCache.layer`. A defaulted
+	* `cache.db` would silently land on the primary cache's file — two
+	* connections onto one database, with two independent eviction passes and
+	* two event streams that each see half the writes. Give each cache its own
+	* name. The same single-path-component guard applies, and a bad name dies
+	* at construction.
+	*
+	* This is a layer-returning function: bind the result to a `const` once and
+	* reuse that binding, or memoization by reference is lost and the database
+	* is opened twice.
+	*
+	* @example
+	* ```ts
+	* import { AppCache } from "@effected/app";
+	* import type { CacheShape } from "@effected/store";
+	* import { Context } from "effect";
+	*
+	* class TarballCache extends Context.Service<TarballCache, CacheShape>()("myapp/TarballCache") {}
+	*
+	* // Bound once, to a const: <cache dir>/tarballs.db, provided as TarballCache.
+	* const TarballCacheLive = AppCache.layerAs(TarballCache, { filename: "tarballs.db", maxEntries: 200 });
+	* // Requires AppDirs, Path and FileSystem — App.layerDirs and the platform layer supply them.
+	* ```
+	*/
+	static layerAs = layerAs;
+	/**
+	* Resolve the absolute path of the database file the layers would open for
+	* these options — `directory`, `subdir` and `filename` — without creating
+	* anything.
+	*
+	* @remarks
+	* The same derivation `AppCache.layer` and `AppCache.layerAs` use, not a copy of
+	* it, so the path a consumer reports or persists is the path the layer
+	* opens. Requires only `AppDirs` and `Path`: nothing is touched on disk.
+	* `filename` defaults to `"cache.db"` as on `AppCache.layer`; pass the same
+	* options you pass the layer. A bad `filename` or `subdir` dies, exactly as
+	* it would at layer construction.
+	*
+	* @example
+	* ```ts
+	* import { AppCache } from "@effected/app";
+	* import { Effect } from "effect";
+	*
+	* const options = { filename: "registry.db", directory: "data" } as const;
+	*
+	* const program = Effect.gen(function* () {
+	* 	const file = yield* AppCache.location(options); // e.g. ~/.local/share/myapp/registry.db
+	* 	yield* Effect.log(`database: ${file}`);
+	* });
+	* ```
+	*/
+	static location = location;
 };
 
 //#endregion

package/AppConfig.js

@@ -72,6 +72,14 @@ var AppConfig = class {
 	* `App.layer` — the two-strings drift where an app passes `"myapp"` to
 	* `App.layer` and `"my-app"` to its config preset cannot happen.
 	*
+	* `tag` is a `ConfigFile.Service` key — its service type
+	* `ConfigFileShape<A>` for the schema's `A`. A key whose shape adds members
+	* (`ConfigFileShape<A> & { … }`) is a compile error, reported as an argument
+	* "not assignable to parameter of type 'never'", because this layer could
+	* not supply them. The check cannot see through method-syntax parameter
+	* bivariance: a member redeclared as a method with a wider parameter still
+	* compiles.
+	*
 	* This is a layer-returning function: bind the result to a `const` and reuse
 	* that binding, or two provide sites mint two independent service instances.
 	*

package/AppStore.js

@@ -1,32 +1,37 @@
-import { badFilename } from "./internal/filename.js";
+import { ensureLocation, resolveLocation } from "./internal/location.js";
 import { Store } from "@effected/store";
-import { AppDirs } from "@effected/xdg";
-import { Effect, Layer, Path } from "effect";
+import { Effect, Layer } from "effect";
 
 //#region src/AppStore.ts
-const layer = (options) => Layer.unwrap(Effect.gen(function* () {
-	const filename = options.filename ?? "store.db";
-	const invalid = badFilename("AppStore.layer", filename);
-	if (invalid !== void 0) return yield* Effect.die(invalid);
-	const appDirs = yield* AppDirs;
-	const path = yield* Path.Path;
-	const stateDir = yield* appDirs.ensureState;
-	return Store.layerSqlite({
-		...options,
-		filename: path.join(stateDir, filename)
+/** The one derivation of the file's location, shared by `location` and both layers. */
+const locate = (context, options) => {
+	const { filename = "store.db", directory = "state", subdir } = options;
+	return resolveLocation(context, directory, subdir, filename);
+};
+const build = (context, options, open) => Layer.unwrap(Effect.gen(function* () {
+	const { filename: _filename, directory: _directory, subdir: _subdir, ...rest } = options;
+	const location = yield* locate(context, options);
+	yield* ensureLocation(location);
+	return open({
+		...rest,
+		filename: location.file
 	});
 }));
+const location = (options) => Effect.map(locate("AppStore.location", options), (resolved) => resolved.file);
+const layer = (options) => build("AppStore.layer", options, Store.layerSqlite);
+const layerAs = (tag, options) => build("AppStore.layerAs", options, (resolved) => Store.layerSqliteAs(tag, resolved));
 /**
-* The state-directory database glue: a migrated SQLite `Store` whose file
-* lives in the ambient `AppDirs` state directory.
+* The database glue: a migrated SQLite `Store` whose file lives in one of the
+* ambient `AppDirs` directories — the state directory unless told otherwise.
 *
 * @public
 */
 var AppStore = class {
 	constructor() {}
 	/**
-	* Build the state-directory database layer: `AppDirs.ensureState`, then
-	* `Store.layerSqlite` at `<state dir>/<filename>`.
+	* Build the database layer: ensure `<directory>[/<subdir>]`, then
+	* `Store.layerSqlite` at `<directory>[/<subdir>]/<filename>` — by default
+	* `AppDirs.ensureState` and `<state dir>/store.db`.
 	*
 	* @remarks
 	* The ensure-before-open ordering is the load-bearing glue.
@@ -35,13 +40,102 @@ var AppStore = class {
 	* `AppDirsError` channel. Running the ensure inside `Layer.unwrap`, before the
 	* store layer is built, converts a defect surface into a typed one — "the
 	* state directory could not be created" is an expected, recoverable boundary
-	* failure and it stays on `E`. Nothing is `orDie`d.
+	* failure and it stays on `E`. Nothing is `orDie`d. A `subdir` is created
+	* with a recursive `mkdir` after the directory is ensured — that is why
+	* `FileSystem` is in `R` — and its failure lands on the same `AppDirsError`,
+	* naming the directory kind and the full path.
 	*
 	* This is a layer-returning function: bind the result to a `const` and reuse
 	* that binding, or memoization by reference is lost and the database is
 	* opened twice.
 	*/
 	static layer = layer;
+	/**
+	* Build an additional database under a service key the consumer defines:
+	* the same ensure-before-open glue as {@link AppStore.layer}, over
+	* `Store.layerSqliteAs`, provided as `I` instead of `Store`.
+	*
+	* @remarks
+	* For an application that keeps more than one SQLite database — each with
+	* its own migrations, its own ledger, and its own `directory` / `subdir`. `tag` is a
+	* consumer-defined `Context.Service` whose service type is `StoreShape`.
+	* An incompatible shape is a compile error, and so is one that adds members
+	* (`StoreShape & { … }`), reported as an argument "not assignable to
+	* parameter of type 'never'". The check cannot see through method-syntax
+	* parameter bivariance: a member redeclared as a method with a wider
+	* parameter still compiles. The
+	* output is `I` alone: the `Store` the layer builds internally is provided
+	* to the re-tagging step and never leaks, so `layerAs` composes beside
+	* `AppStore.layer` without either shadowing the other.
+	*
+	* `filename` is **required** here, unlike on `AppStore.layer`. A defaulted
+	* `store.db` would silently land on the primary store's file — two
+	* connections and two migration ledgers on one database, each recording
+	* the other's migrations as unknown. Give each store its own name. The same
+	* single-path-component guard applies, and a bad name dies at construction.
+	*
+	* This is a layer-returning function: bind the result to a `const` once and
+	* reuse that binding, or memoization by reference is lost and the database
+	* is opened twice.
+	*
+	* @example
+	* ```ts
+	* import { AppStore } from "@effected/app";
+	* import type { StoreMigration, StoreShape } from "@effected/store";
+	* import { Context, Effect } from "effect";
+	*
+	* class RegistryStore extends Context.Service<RegistryStore, StoreShape>()("myapp/RegistryStore") {}
+	*
+	* const registryMigrations: ReadonlyArray<StoreMigration> = [
+	* 	{ id: 1, name: "packages", up: (sql) => sql`CREATE TABLE packages (name TEXT PRIMARY KEY)` },
+	* ];
+	*
+	* // Bound once, to a const: <state dir>/registry.db, provided as RegistryStore.
+	* const RegistryStoreLive = AppStore.layerAs(RegistryStore, {
+	* 	filename: "registry.db",
+	* 	migrations: registryMigrations,
+	* });
+	*
+	* const program = Effect.gen(function* () {
+	* 	const registry = yield* RegistryStore;
+	* 	yield* registry.client`INSERT INTO packages (name) VALUES ('effect')`;
+	* });
+	*
+	* // A per-project database under the data directory: <data dir>/<projectKey>/data.db.
+	* // Call it once per key and bind the result — each call is a new layer.
+	* const projectStore = (projectKey: string) =>
+	* 	AppStore.layerAs(RegistryStore, { filename: "data.db", directory: "data", subdir: projectKey, migrations: [] });
+	* // Requires AppDirs, Path and FileSystem — App.layerDirs and the platform layer supply them.
+	* ```
+	*/
+	static layerAs = layerAs;
+	/**
+	* Resolve the absolute path of the database file the layers would open for
+	* these options — `directory`, `subdir` and `filename` — without creating
+	* anything.
+	*
+	* @remarks
+	* The same derivation `AppStore.layer` and `AppStore.layerAs` use, not a copy of
+	* it, so the path a consumer reports or persists is the path the layer
+	* opens. Requires only `AppDirs` and `Path`: nothing is touched on disk.
+	* `filename` defaults to `"store.db"` as on `AppStore.layer`; pass the same
+	* options you pass the layer. A bad `filename` or `subdir` dies, exactly as
+	* it would at layer construction.
+	*
+	* @example
+	* ```ts
+	* import { AppStore } from "@effected/app";
+	* import { Effect } from "effect";
+	*
+	* const options = { filename: "registry.db", directory: "data", migrations: [] } as const;
+	*
+	* const program = Effect.gen(function* () {
+	* 	const file = yield* AppStore.location(options); // e.g. ~/.local/share/myapp/registry.db
+	* 	yield* Effect.log(`database: ${file}`);
+	* });
+	* ```
+	*/
+	static location = location;
 };
 
 //#endregion

package/README.md

@@ -111,7 +111,15 @@ Four services, one platform import, one namespace typed once, and every failure
 
 `AppOptions` is [`@effected/xdg`](../xdg)'s `AppDirsOptions` straight through — `namespace`, `native`, `fallbackDir` and `dirs` mean there exactly what they mean here, five-rung precedence ladder included, and this package re-documents none of it.
 
-Every `filename` takes a **single path component**. An empty name, one containing a separator, or `.` / `..` would escape the namespace directory, so it dies at layer construction: it can only come from code, never from user input.
+`AppStore` and `AppCache` take a `directory` (`"state"`, `"data"` or `"cache"`; defaults as above) and an optional relative `subdir` under it, created with `mkdir -p` before the database opens — so `{ directory: "data", subdir: "projects/abc123", filename: "data.db" }` lands at `~/.local/share/myapp/projects/abc123/data.db`. A `subdir` that cannot be created fails on the same typed `AppDirsError` as the directory itself; because of that `mkdir`, the database layers need `FileSystem` as well as `AppDirs` and `Path`.
+
+Every `filename` takes a **single path component**, and every `subdir` component obeys the same rule (no empty component, no `.` or `..`, no leading `/`, no `\`). Both are wiring, so a bad one **dies** rather than failing typed. A `subdir` derived from runtime data — a per-project key from a path — must therefore come from a derivation that can only produce valid components, such as a hash:
+
+```ts
+import { createHash } from "node:crypto";
+
+const subdir = createHash("sha256").update(projectRoot).digest("hex").slice(0, 16);
+``` An empty name, one containing a separator, or `.` / `..` would escape the namespace directory, so it dies at layer construction: it can only come from code, never from user input.
 
 ## The namespace is typed once
 
@@ -194,6 +202,87 @@ const AppLive = App.layer({ namespace: "myapp", store: { migrations } }); // onc
 
 Call the factory inline at two provide sites and you open **two databases**: two connections onto one file, two migration ledgers, and two independent `CacheEvent` PubSubs whose subscribers each see half the events. This is the package where an application is most likely to compose the same layer twice, which is why the rule is here and not in a footnote.
 
+## Databases per command: directories everywhere
+
+Building `App.layer` **opens and migrates both databases**, eagerly — `store.db` and `cache.db` exist the moment the layer is built, whether or not the program touches them. For a long-running service that is what you want. For a CLI it is not: provide `App.layer` at the entry point and every command creates and migrates both files, `--help`-adjacent paths included, and a command that deletes the app's files ends up deleting a database its own process holds open.
+
+`App.layerDirs` is the directories half on its own — `Xdg` and `AppDirs` for one namespace, `XdgEnvError` on the error channel, `FileSystem` and `Path` in `R`, and no database opened. Provide it once at the edge, bind each database layer once at module scope, and attach it with `Command.provide` only on the commands that use it:
+
+```ts
+import { App, AppStore } from "@effected/app";
+import { CliRuntime } from "@effected/cli";
+import { Store } from "@effected/store";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { Command } from "effect/cli";
+
+// Module scope, bound once: built once per provided layer graph.
+const StoreLive = AppStore.layer({ migrations });
+
+// Opens store.db — only when `history` runs.
+const history = Command.make("history", {}, () =>
+  Effect.gen(function* () {
+    const store = yield* Store;
+    yield* store.client`SELECT id FROM runs`;
+  }),
+).pipe(Command.provide(StoreLive));
+
+// Opens no database at all.
+const where = Command.make("where", {}, () => Effect.void);
+
+const cli = Command.make("myapp").pipe(Command.withSubcommands([history, where]));
+
+// Directories at the edge, once; AppDirs satisfies StoreLive's requirement.
+const PlatformLive = App.layerDirs({ namespace: "myapp" }).pipe(Layer.provideMerge(NodeServices.layer));
+
+NodeRuntime.runMain(CliRuntime.main(Command.run(cli, { version: "1.0.0" }), { platform: PlatformLive }));
+```
+
+A module-scope binding such as `StoreLive` stays **one** connection however many composites reuse it inside one provided layer graph — `Layer.mergeAll(StoreLive, …)` beside `Repo.pipe(Layer.provide(StoreLive))` — because a layer graph memoises by reference, and an `Effect.provide` nested inside another reuses what the enclosing one already built. Provides that are not nested — one after another, or side by side under a common parent — each build it, and so open the database, again.
+
+`Command.provide` also accepts a function of the command's parsed input, `(input) => Layer`, for a database whose options depend on a flag. Bind anything that does not depend on the input outside that function — a layer built inside it is a new reference on every call.
+
+## More than one store
+
+`AppStore.layer` and `AppCache.layer` provide the kit's single `Store` and `Cache` services. An application that keeps a second database — a registry beside its run history, a separate cache for large objects — declares its own service key over the same shape and builds it with `layerAs`:
+
+```ts
+import { AppCache, AppStore } from "@effected/app";
+import type { CacheShape, StoreShape } from "@effected/store";
+import { Context, Layer } from "effect";
+
+class RegistryStore extends Context.Service<RegistryStore, StoreShape>()("myapp/RegistryStore") {}
+class TarballCache extends Context.Service<TarballCache, CacheShape>()("myapp/TarballCache") {}
+
+// Every one bound once, to a const.
+const StoreLive = AppStore.layer({ migrations });
+const RegistryStoreLive = AppStore.layerAs(RegistryStore, { filename: "registry.db", migrations: registryMigrations });
+const TarballCacheLive = AppCache.layerAs(TarballCache, { filename: "tarballs.db", maxEntries: 200 });
+
+const DatabasesLive = Layer.mergeAll(StoreLive, RegistryStoreLive, TarballCacheLive);
+```
+
+Each keyed layer runs the same ensure-before-open glue, in the same default directory as its primary — state for stores, cache for caches, unless `directory` / `subdir` say otherwise — and outputs **only its own key**: the `Store` or `Cache` it builds internally never leaks, so it composes beside the primary without shadowing it. Each file has its own migrations and its own ledger.
+
+- **`filename` is required.** A default of `store.db` or `cache.db` would land a keyed layer silently on the primary's file — two connections and two migration ledgers on one database.
+- **The key's service type must be `StoreShape` or `CacheShape`.** An incompatible shape is a compile error, and so is one that adds members (`StoreShape & { … }`), reported as an argument not assignable to `never` because this layer cannot supply them. The check cannot see through method-syntax parameter bivariance: a member redeclared as a method with a wider parameter still compiles.
+- **Bind every keyed layer to a `const`.** Each `layerAs(…)` call is a new layer, and the memoization trap above applies to each one separately: two inline calls with the same key open the file twice.
+
+The keyed layers need `AppDirs`, `Path` and `FileSystem`, which is exactly what `App.layerDirs` plus the platform provides — they slot into the per-command shape above unchanged.
+
+Every `AppStore` / `AppCache` option beyond the path is `@effected/store`'s, passed straight through: `client` (driver options such as `busyTimeout` and `disableWAL` — the place for per-connection settings, never a migration), `checkpointOnClose`, `onConnect` (a per-connection hook run before the ledger, outside any transaction), and on stores `adoptMigratorLedger` and `mirrorMigratorLedger`, which move a database previously migrated by effect/sql's `Migrator` onto `Store` without re-running its history and keep that ledger current for older versions (see `@effected/store`'s README for the rules). A database at an absolute or host-chosen path is not an app concern: use `Store.layerSqliteAs` / `Cache.layerSqliteAs` from `@effected/store` directly.
+
+### Where is the file?
+
+A program that reports or persists the database path — a `doctor` command, a "your data lives at" line — derives it with `AppStore.location(options)` / `AppCache.location(options)`, passing the same options it passes the layer. It resolves the absolute path from the ambient `AppDirs` without creating anything (`R` is `AppDirs | Path`), and it is the very derivation the layers use, so the reported path and the opened file cannot disagree:
+
+```ts
+const options = { filename: "registry.db", directory: "data", migrations } as const;
+
+const RegistryStoreLive = AppStore.layerAs(RegistryStore, options);
+const where = AppStore.location(options); // Effect<string, never, AppDirs | Path>
+```
+
 ## Testing: one line, no platform package
 
 `App.layerTest` is the hermetic control plane — fixed XDG paths, `:memory:` databases, and the platform layers provided *internally* rather than merged into the output. A consumer's first test needs no platform import at all:
@@ -255,8 +344,10 @@ Provide it beneath the stack and every span the kit's packages already emit —
 ## Features
 
 - `App.layer` — the control plane: `Xdg`, `AppDirs`, `Store` and `Cache` from one call, with only `FileSystem` and `Path` left for the platform layer to supply.
+- `App.layerDirs` — `Xdg` and `AppDirs` alone, opening no database: directories everywhere, databases attached only where they are used.
 - `App.layerTest` — the same four services, hermetic: synthetic XDG paths, `:memory:` databases, no platform package required.
 - `AppStore.layer` / `AppCache.layer` — the state-directory and cache-directory databases on their own, each ensuring its directory before it opens the file.
+- `AppStore.layerAs` / `AppCache.layerAs` — an additional database under a service key you define, with its own file, migrations and ledger.
 - `AppConfig.layer` — `@effected/config-file` wired to xdg's resolver chain and save path, with the namespace read from the ambient `AppDirs` and the codec named by you.
 - `AppError` — the type-only union of everything the control plane can fail with, for the `catchTags` block at the edge.
 

package/index.d.ts

@@ -1,77 +1,218 @@
-import { Cache, CacheError, CacheOptions, Store, StoreError, StoreMigrationError, StoreOptions } from "@effected/store";
+import { Cache, CacheError, CacheOptions, CacheShape, CacheSqliteOptions, Store, StoreError, StoreMigrationError, StoreOptions, StoreShape, StoreSqliteOptions } from "@effected/store";
 import { AppDirs, AppDirsError, AppDirsOptions, Xdg, XdgEnvError, XdgPaths } from "@effected/xdg";
 import { Context, Effect, FileSystem, Layer, Path, Schema, SchemaAST } from "effect";
 import { ConfigCodec, ConfigEvents, ConfigEventsShape, ConfigFileShape, ConfigResolver, ConfigValidationError, MergeStrategy } from "@effected/config-file";
 //#region src/AppCache.d.ts
 /**
- * Options for {@link AppCache.layer}.
+ * Options for {@link AppCache.layer} and {@link AppCache.layerAs}.
+ *
+ * @remarks
+ * `CacheOptions` plus the SQLite driver passthrough — `client`,
+ * `checkpointOnClose` — exactly as `Cache.layerSqlite` takes them. Only the
+ * path is this package's: a directory kind, an optional subdirectory under
+ * it, and a file name.
  *
  * @public
  */
-interface AppCacheOptions extends CacheOptions {
+interface AppCacheOptions extends CacheOptions, Pick<CacheSqliteOptions, "client" | "checkpointOnClose" | "onConnect"> {
   /**
-   * File name within the app's cache directory. Default `"cache.db"`.
+   * File name within the database's directory. Default `"cache.db"` on
+   * `AppCache.layer`; required on `AppCache.layerAs`.
    *
    * @remarks
-   * A single path component. An empty name, or one containing a separator,
-   * would escape the namespace directory, so it **dies** at layer
+   * A single path component. An empty name, one containing a separator, or
+   * `.` / `..` would escape the namespace directory, so it **dies** at layer
    * construction — it can only come from code, never from user input.
    */
   readonly filename?: string;
+  /**
+   * Which of the app's directories holds the file. Default `"cache"`.
+   *
+   * @remarks
+   * The matching `AppDirs.ensure*` member creates it before the database
+   * opens.
+   */
+  readonly directory?: "state" | "data" | "cache";
+  /**
+   * A relative subdirectory under `directory`, created (`mkdir -p`) before
+   * the database opens.
+   *
+   * @remarks
+   * `/`-separated single path components: no empty component, no `.` or
+   * `..`, no leading `/`, no `\`. Anything else would escape the namespace
+   * directory, so it **dies** at layer construction. A failure to create it
+   * is a typed `AppDirsError` naming `directory` and the full path.
+   *
+   * A subdir derived from runtime data — a project path, a user-supplied
+   * name — must come from a derivation that can only produce a valid
+   * component, such as a hash:
+   * `subdir: createHash("sha256").update(projectRoot).digest("hex").slice(0, 16)`.
+   * Passed raw, an unexpected value is a defect, not a typed failure.
+   */
+  readonly subdir?: string;
 }
 /**
- * The cache-directory database glue: a TTL `Cache` whose file lives in the
- * ambient `AppDirs` cache directory.
+ * The cache database glue: a TTL `Cache` whose file lives in one of the
+ * ambient `AppDirs` directories — the cache directory unless told otherwise.
  *
  * @public
  */
 export declare class AppCache {
   private constructor();
   /**
-   * Build the cache-directory database layer: `AppDirs.ensureCache`, then
-   * `Cache.layerSqlite` at `<cache dir>/<filename>`.
+   * Build the cache database layer: ensure `<directory>[/<subdir>]`, then
+   * `Cache.layerSqlite` at `<directory>[/<subdir>]/<filename>` — by default
+   * `AppDirs.ensureCache` and `<cache dir>/cache.db`.
    *
    * @remarks
    * The same ensure-before-open ordering as `AppStore.layer`, and it matters
    * *more* here: the cache directory is the one an operator is most likely to
    * have deleted between runs. `options` is optional because every
-   * `CacheOptions` field is.
+   * `CacheOptions` field is. A `subdir` is created with a recursive `mkdir`
+   * after the directory is ensured — that is why `FileSystem` is in `R` — and
+   * its failure lands on the same typed `AppDirsError`.
    *
    * This is a layer-returning function: bind the result to a `const` and reuse
    * that binding, or memoization by reference is lost and the database is
    * opened twice.
    */
-  static readonly layer: (options?: AppCacheOptions) => Layer.Layer<Cache, AppDirsError | CacheError, AppDirs | Path.Path>;
+  static readonly layer: (options?: AppCacheOptions) => Layer.Layer<Cache, AppDirsError | CacheError, AppDirs | Path.Path | FileSystem.FileSystem>;
+  /**
+   * Build an additional cache under a service key the consumer defines: the
+   * same ensure-before-open glue as {@link AppCache.layer}, over
+   * `Cache.layerSqliteAs`, provided as `I` instead of `Cache`.
+   *
+   * @remarks
+   * For an application that keeps more than one cache — each with its own
+   * file, size bound, TTL default and `CacheEvent` stream. `tag` is a
+   * consumer-defined `Context.Service` whose service type is `CacheShape`.
+   * An incompatible shape is a compile error, and so is one that adds members
+   * (`CacheShape & { … }`), reported as an argument "not assignable to
+   * parameter of type 'never'". The check cannot see through method-syntax
+   * parameter bivariance: a member redeclared as a method with a wider
+   * parameter still compiles. The
+   * output is `I` alone: the `Cache` built internally never leaks, so
+   * `layerAs` composes beside `AppCache.layer` without either shadowing the
+   * other.
+   *
+   * `filename` is **required** here, unlike on `AppCache.layer`. A defaulted
+   * `cache.db` would silently land on the primary cache's file — two
+   * connections onto one database, with two independent eviction passes and
+   * two event streams that each see half the writes. Give each cache its own
+   * name. The same single-path-component guard applies, and a bad name dies
+   * at construction.
+   *
+   * This is a layer-returning function: bind the result to a `const` once and
+   * reuse that binding, or memoization by reference is lost and the database
+   * is opened twice.
+   *
+   * @example
+   * ```ts
+   * import { AppCache } from "@effected/app";
+   * import type { CacheShape } from "@effected/store";
+   * import { Context } from "effect";
+   *
+   * class TarballCache extends Context.Service<TarballCache, CacheShape>()("myapp/TarballCache") {}
+   *
+   * // Bound once, to a const: <cache dir>/tarballs.db, provided as TarballCache.
+   * const TarballCacheLive = AppCache.layerAs(TarballCache, { filename: "tarballs.db", maxEntries: 200 });
+   * // Requires AppDirs, Path and FileSystem — App.layerDirs and the platform layer supply them.
+   * ```
+   */
+  static readonly layerAs: <I, S extends CacheShape>(tag: Context.Key<I, S> & ([CacheShape] extends [S] ? unknown : never), options: AppCacheOptions & {
+    readonly filename: string;
+  }) => Layer.Layer<I, AppDirsError | CacheError, AppDirs | Path.Path | FileSystem.FileSystem>;
+  /**
+   * Resolve the absolute path of the database file the layers would open for
+   * these options — `directory`, `subdir` and `filename` — without creating
+   * anything.
+   *
+   * @remarks
+   * The same derivation `AppCache.layer` and `AppCache.layerAs` use, not a copy of
+   * it, so the path a consumer reports or persists is the path the layer
+   * opens. Requires only `AppDirs` and `Path`: nothing is touched on disk.
+   * `filename` defaults to `"cache.db"` as on `AppCache.layer`; pass the same
+   * options you pass the layer. A bad `filename` or `subdir` dies, exactly as
+   * it would at layer construction.
+   *
+   * @example
+   * ```ts
+   * import { AppCache } from "@effected/app";
+   * import { Effect } from "effect";
+   *
+   * const options = { filename: "registry.db", directory: "data" } as const;
+   *
+   * const program = Effect.gen(function* () {
+   * 	const file = yield* AppCache.location(options); // e.g. ~/.local/share/myapp/registry.db
+   * 	yield* Effect.log(`database: ${file}`);
+   * });
+   * ```
+   */
+  static readonly location: (options?: AppCacheOptions) => Effect.Effect<string, never, AppDirs | Path.Path>;
 }
 //#endregion
 //#region src/AppStore.d.ts
 /**
- * Options for {@link AppStore.layer}.
+ * Options for {@link AppStore.layer} and {@link AppStore.layerAs}.
+ *
+ * @remarks
+ * `StoreOptions` (the migrations, and `adoptMigratorLedger`) plus the SQLite
+ * driver passthrough — `client`, `checkpointOnClose` — exactly as
+ * `Store.layerSqlite` takes them. Only the path is this package's: a
+ * directory kind, an optional subdirectory under it, and a file name.
  *
  * @public
  */
-interface AppStoreOptions extends StoreOptions {
+interface AppStoreOptions extends StoreOptions, Pick<StoreSqliteOptions, "client" | "checkpointOnClose" | "onConnect"> {
   /**
-   * File name within the app's state directory. Default `"store.db"`.
+   * File name within the database's directory. Default `"store.db"` on
+   * `AppStore.layer`; required on `AppStore.layerAs`.
    *
    * @remarks
-   * A single path component. An empty name, or one containing a separator,
-   * would escape the namespace directory, so it **dies** at layer
+   * A single path component. An empty name, one containing a separator, or
+   * `.` / `..` would escape the namespace directory, so it **dies** at layer
    * construction — it can only come from code, never from user input.
    */
   readonly filename?: string;
+  /**
+   * Which of the app's directories holds the file. Default `"state"`.
+   *
+   * @remarks
+   * The matching `AppDirs.ensure*` member creates it before the database
+   * opens. `"data"` suits a database that is the user's data rather than
+   * the app's bookkeeping; `"cache"` one that is safe to delete.
+   */
+  readonly directory?: "state" | "data" | "cache";
+  /**
+   * A relative subdirectory under `directory`, created (`mkdir -p`) before
+   * the database opens — for example a per-project key.
+   *
+   * @remarks
+   * `/`-separated single path components: no empty component, no `.` or
+   * `..`, no leading `/`, no `\`. Anything else would escape the namespace
+   * directory, so it **dies** at layer construction. A failure to create it
+   * is a typed `AppDirsError` naming `directory` and the full path.
+   *
+   * A subdir derived from runtime data — a project path, a user-supplied
+   * name — must come from a derivation that can only produce a valid
+   * component, such as a hash:
+   * `subdir: createHash("sha256").update(projectRoot).digest("hex").slice(0, 16)`.
+   * Passed raw, an unexpected value is a defect, not a typed failure.
+   */
+  readonly subdir?: string;
 }
 /**
- * The state-directory database glue: a migrated SQLite `Store` whose file
- * lives in the ambient `AppDirs` state directory.
+ * The database glue: a migrated SQLite `Store` whose file lives in one of the
+ * ambient `AppDirs` directories — the state directory unless told otherwise.
  *
  * @public
  */
 export declare class AppStore {
   private constructor();
   /**
-   * Build the state-directory database layer: `AppDirs.ensureState`, then
-   * `Store.layerSqlite` at `<state dir>/<filename>`.
+   * Build the database layer: ensure `<directory>[/<subdir>]`, then
+   * `Store.layerSqlite` at `<directory>[/<subdir>]/<filename>` — by default
+   * `AppDirs.ensureState` and `<state dir>/store.db`.
    *
    * @remarks
    * The ensure-before-open ordering is the load-bearing glue.
@@ -80,13 +221,104 @@ export declare class AppStore {
    * `AppDirsError` channel. Running the ensure inside `Layer.unwrap`, before the
    * store layer is built, converts a defect surface into a typed one — "the
    * state directory could not be created" is an expected, recoverable boundary
-   * failure and it stays on `E`. Nothing is `orDie`d.
+   * failure and it stays on `E`. Nothing is `orDie`d. A `subdir` is created
+   * with a recursive `mkdir` after the directory is ensured — that is why
+   * `FileSystem` is in `R` — and its failure lands on the same `AppDirsError`,
+   * naming the directory kind and the full path.
    *
    * This is a layer-returning function: bind the result to a `const` and reuse
    * that binding, or memoization by reference is lost and the database is
    * opened twice.
    */
-  static readonly layer: (options: AppStoreOptions) => Layer.Layer<Store, AppDirsError | StoreError | StoreMigrationError, AppDirs | Path.Path>;
+  static readonly layer: (options: AppStoreOptions) => Layer.Layer<Store, AppDirsError | StoreError | StoreMigrationError, AppDirs | Path.Path | FileSystem.FileSystem>;
+  /**
+   * Build an additional database under a service key the consumer defines:
+   * the same ensure-before-open glue as {@link AppStore.layer}, over
+   * `Store.layerSqliteAs`, provided as `I` instead of `Store`.
+   *
+   * @remarks
+   * For an application that keeps more than one SQLite database — each with
+   * its own migrations, its own ledger, and its own `directory` / `subdir`. `tag` is a
+   * consumer-defined `Context.Service` whose service type is `StoreShape`.
+   * An incompatible shape is a compile error, and so is one that adds members
+   * (`StoreShape & { … }`), reported as an argument "not assignable to
+   * parameter of type 'never'". The check cannot see through method-syntax
+   * parameter bivariance: a member redeclared as a method with a wider
+   * parameter still compiles. The
+   * output is `I` alone: the `Store` the layer builds internally is provided
+   * to the re-tagging step and never leaks, so `layerAs` composes beside
+   * `AppStore.layer` without either shadowing the other.
+   *
+   * `filename` is **required** here, unlike on `AppStore.layer`. A defaulted
+   * `store.db` would silently land on the primary store's file — two
+   * connections and two migration ledgers on one database, each recording
+   * the other's migrations as unknown. Give each store its own name. The same
+   * single-path-component guard applies, and a bad name dies at construction.
+   *
+   * This is a layer-returning function: bind the result to a `const` once and
+   * reuse that binding, or memoization by reference is lost and the database
+   * is opened twice.
+   *
+   * @example
+   * ```ts
+   * import { AppStore } from "@effected/app";
+   * import type { StoreMigration, StoreShape } from "@effected/store";
+   * import { Context, Effect } from "effect";
+   *
+   * class RegistryStore extends Context.Service<RegistryStore, StoreShape>()("myapp/RegistryStore") {}
+   *
+   * const registryMigrations: ReadonlyArray<StoreMigration> = [
+   * 	{ id: 1, name: "packages", up: (sql) => sql`CREATE TABLE packages (name TEXT PRIMARY KEY)` },
+   * ];
+   *
+   * // Bound once, to a const: <state dir>/registry.db, provided as RegistryStore.
+   * const RegistryStoreLive = AppStore.layerAs(RegistryStore, {
+   * 	filename: "registry.db",
+   * 	migrations: registryMigrations,
+   * });
+   *
+   * const program = Effect.gen(function* () {
+   * 	const registry = yield* RegistryStore;
+   * 	yield* registry.client`INSERT INTO packages (name) VALUES ('effect')`;
+   * });
+   *
+   * // A per-project database under the data directory: <data dir>/<projectKey>/data.db.
+   * // Call it once per key and bind the result — each call is a new layer.
+   * const projectStore = (projectKey: string) =>
+   * 	AppStore.layerAs(RegistryStore, { filename: "data.db", directory: "data", subdir: projectKey, migrations: [] });
+   * // Requires AppDirs, Path and FileSystem — App.layerDirs and the platform layer supply them.
+   * ```
+   */
+  static readonly layerAs: <I, S extends StoreShape>(tag: Context.Key<I, S> & ([StoreShape] extends [S] ? unknown : never), options: AppStoreOptions & {
+    readonly filename: string;
+  }) => Layer.Layer<I, AppDirsError | StoreError | StoreMigrationError, AppDirs | Path.Path | FileSystem.FileSystem>;
+  /**
+   * Resolve the absolute path of the database file the layers would open for
+   * these options — `directory`, `subdir` and `filename` — without creating
+   * anything.
+   *
+   * @remarks
+   * The same derivation `AppStore.layer` and `AppStore.layerAs` use, not a copy of
+   * it, so the path a consumer reports or persists is the path the layer
+   * opens. Requires only `AppDirs` and `Path`: nothing is touched on disk.
+   * `filename` defaults to `"store.db"` as on `AppStore.layer`; pass the same
+   * options you pass the layer. A bad `filename` or `subdir` dies, exactly as
+   * it would at layer construction.
+   *
+   * @example
+   * ```ts
+   * import { AppStore } from "@effected/app";
+   * import { Effect } from "effect";
+   *
+   * const options = { filename: "registry.db", directory: "data", migrations: [] } as const;
+   *
+   * const program = Effect.gen(function* () {
+   * 	const file = yield* AppStore.location(options); // e.g. ~/.local/share/myapp/registry.db
+   * 	yield* Effect.log(`database: ${file}`);
+   * });
+   * ```
+   */
+  static readonly location: (options: AppStoreOptions) => Effect.Effect<string, never, AppDirs | Path.Path>;
 }
 //#endregion
 //#region src/App.d.ts
@@ -153,10 +385,29 @@ export declare class App {
    * so all four services come out and only `FileSystem` and `Path` stay in `R` —
    * the two the consumer's platform layer supplies once, at the edge.
    *
-   * `App.layer` always provides **both** databases: an application that wants
-   * only one composes `AppStore.layer` or `AppCache.layer` directly and never
-   * opens the other file. Passing no `cache` options still opens `cache.db`,
-   * because `CacheOptions` are all-optional and absence means defaults.
+   * `App.layer` always provides **both** databases, and **building it opens
+   * and migrates both eagerly** — `store.db` and `cache.db` exist on disk the
+   * moment the layer is built, whether or not the program ever touches them.
+   * Passing no `cache` options still opens `cache.db`, because `CacheOptions`
+   * are all-optional and absence means defaults. An application that wants
+   * only one composes {@link App.layerDirs} with `AppStore.layer` or
+   * `AppCache.layer` and never opens the other file.
+   *
+   * A CLI should therefore not provide `App.layer` at its entry point: every
+   * command, `--help`-adjacent paths included, would create and migrate both
+   * databases, and a command that deletes the app's files would delete a
+   * database its own process holds open. Provide {@link App.layerDirs} once at
+   * the platform edge instead, bind `AppStore.layer(...)` / `AppCache.layer(...)`
+   * once at module scope, and attach them with `Command.provide` only on the
+   * commands that use them — see the second example.
+   *
+   * A module-scope binding such as `StoreLive` stays ONE connection however
+   * many composites reuse it inside one provided layer graph —
+   * `Layer.mergeAll(StoreLive, …)` beside `Repo.pipe(Layer.provide(StoreLive))`
+   * — because a layer graph memoises by reference, and an `Effect.provide`
+   * nested inside another reuses what the enclosing one already built.
+   * Provides that are not nested — one after another, or side by side under a
+   * common parent — each build it, and so open the database, again.
    *
    * This is a layer-returning function: bind the result to a `const` once and
    * reuse that binding. Calling it inline at two provide sites opens two
@@ -184,8 +435,88 @@ export declare class App {
    * 	Layer.provide(NodeServices.layer),
    * );
    * ```
+   *
+   * @example
+   * Databases per command, directories everywhere — the CLI shape:
+   * ```ts
+   * import { App, AppStore } from "@effected/app";
+   * import { CliRuntime } from "@effected/cli";
+   * import type { StoreMigration } from "@effected/store";
+   * import { Store } from "@effected/store";
+   * import { NodeRuntime, NodeServices } from "@effect/platform-node";
+   * import { Effect, Layer } from "effect";
+   * import { Command } from "effect/cli";
+   *
+   * const migrations: ReadonlyArray<StoreMigration> = [
+   * 	{ id: 1, name: "runs", up: (sql) => sql`CREATE TABLE runs (id TEXT PRIMARY KEY)` },
+   * ];
+   *
+   * // Module scope, bound once: built once per provided layer graph.
+   * const StoreLive = AppStore.layer({ migrations });
+   *
+   * // Opens store.db — only when `history` runs.
+   * const history = Command.make("history", {}, () =>
+   * 	Effect.gen(function* () {
+   * 		const store = yield* Store;
+   * 		yield* store.client`SELECT id FROM runs`;
+   * 	}),
+   * ).pipe(Command.provide(StoreLive));
+   *
+   * // Opens no database at all.
+   * const where = Command.make("where", {}, () => Effect.void);
+   *
+   * const cli = Command.make("myapp").pipe(Command.withSubcommands([history, where]));
+   *
+   * // Directories at the edge, once; AppDirs satisfies StoreLive's requirement.
+   * const PlatformLive = App.layerDirs({ namespace: "myapp" }).pipe(Layer.provideMerge(NodeServices.layer));
+   *
+   * NodeRuntime.runMain(CliRuntime.main(Command.run(cli, { version: "1.0.0" }), { platform: PlatformLive }));
+   * ```
    */
   static readonly layer: (options: AppOptions) => Layer.Layer<Xdg | AppDirs | Store | Cache, AppError, FileSystem.FileSystem | Path.Path>;
+  /**
+   * Build the directories half of the control plane alone: `Xdg` and
+   * `AppDirs` for one namespace, with no database opened.
+   *
+   * @remarks
+   * Exactly the directory composition {@link App.layer} builds on —
+   * `AppDirs.layer(options)` `provideMerge` `Xdg.layer` — lifted out so an
+   * application can provide "directories everywhere" at its edge and attach
+   * the databases only where they are used. Building it resolves the XDG
+   * environment and nothing else: no directory is created until an `ensure*`
+   * member runs, and no SQLite file is touched. Its output satisfies the
+   * `AppDirs` requirement of `AppStore.layer`, `AppStore.layerAs`,
+   * `AppCache.layer`, `AppCache.layerAs` and `AppConfig.layer`.
+   *
+   * The error channel is `XdgEnvError` alone — an unset `HOME` — and `R` is
+   * the `FileSystem` and `Path` a platform layer supplies once. `options` is
+   * `AppDirsOptions` pass-through: `namespace`, `native`, `fallbackDir` and
+   * `dirs` mean exactly what `@effected/xdg` documents.
+   *
+   * This is a layer-returning function: bind the result to a `const` once and
+   * reuse that binding.
+   *
+   * @example
+   * ```ts
+   * import { App, AppStore } from "@effected/app";
+   * import { NodeServices } from "@effect/platform-node";
+   * import { AppDirs } from "@effected/xdg";
+   * import { Effect, Layer } from "effect";
+   *
+   * // Bound once, to a const: XDG directories for "myapp", no databases.
+   * const DirsLive = App.layerDirs({ namespace: "myapp" }).pipe(Layer.provideMerge(NodeServices.layer));
+   *
+   * const program = Effect.gen(function* () {
+   * 	const dirs = yield* AppDirs;
+   * 	return dirs.dirs.state; // resolved, not created
+   * });
+   *
+   * // A database, attached where it is wanted, over the same directories.
+   * const StoreLive = AppStore.layer({ migrations: [] });
+   * const withStore = program.pipe(Effect.provide(StoreLive), Effect.provide(DirsLive));
+   * ```
+   */
+  static readonly layerDirs: (options: AppDirsOptions) => Layer.Layer<Xdg | AppDirs, XdgEnvError, FileSystem.FileSystem | Path.Path>;
   /**
    * The hermetic control plane: fixed XDG paths, `:memory:` databases, and the
    * platform layers provided internally.
@@ -407,6 +738,14 @@ export declare class AppConfig {
    * `App.layer` — the two-strings drift where an app passes `"myapp"` to
    * `App.layer` and `"my-app"` to its config preset cannot happen.
    *
+   * `tag` is a `ConfigFile.Service` key — its service type
+   * `ConfigFileShape<A>` for the schema's `A`. A key whose shape adds members
+   * (`ConfigFileShape<A> & { … }`) is a compile error, reported as an argument
+   * "not assignable to parameter of type 'never'", because this layer could
+   * not supply them. The check cannot see through method-syntax parameter
+   * bivariance: a member redeclared as a method with a wider parameter still
+   * compiles.
+   *
    * This is a layer-returning function: bind the result to a `const` and reuse
    * that binding, or two provide sites mint two independent service instances.
    *
@@ -429,7 +768,7 @@ export declare class AppConfig {
    * });
    * ```
    */
-  static readonly layer: <Self, A, I, RR = never>(tag: Context.Key<Self, ConfigFileShape<A>>, options: AppConfigOptions<A, I, RR>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | AppDirs | Xdg | RR>;
+  static readonly layer: <Self, A, I, RR = never, S extends ConfigFileShape<A> = ConfigFileShape<A>>(tag: Context.Key<Self, S> & ([ConfigFileShape<A>] extends [S] ? unknown : never), options: AppConfigOptions<A, I, RR>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | AppDirs | Xdg | RR>;
 }
 //#endregion
 export type { AppCacheOptions, AppConfigOptions, AppError, AppOptions, AppStoreOptions, AppTestOptions };

package/internal/filename.js

@@ -10,6 +10,17 @@ const badFilename = (context, filename) => {
 	if (filename.length === 0) return /* @__PURE__ */ new Error(`${context}: \`filename\` must not be empty`);
 	if (/[/\\]/.test(filename) || filename === "." || filename === "..") return /* @__PURE__ */ new Error(`${context}: \`filename\` must be a single path component, received ${JSON.stringify(filename)}`);
 };
+/**
+* A subdirectory is a relative path of single components, joined under the
+* app's own directory. Every component obeys the filename rule, and the whole
+* must not be absolute — so it can never climb out of the namespace directory.
+*/
+const badSubdir = (context, subdir) => {
+	const reject = () => /* @__PURE__ */ new Error(`${context}: \`subdir\` must be a relative path of single path components, received ${JSON.stringify(subdir)}`);
+	if (subdir.length === 0) return /* @__PURE__ */ new Error(`${context}: \`subdir\` must not be empty`);
+	if (subdir.includes("\\") || subdir.startsWith("/")) return reject();
+	for (const component of subdir.split("/")) if (component.length === 0 || component === "." || component === "..") return reject();
+};
 
 //#endregion
-export { badFilename };
+export { badFilename, badSubdir };

package/internal/location.js

@@ -0,0 +1,44 @@
+import { badFilename, badSubdir } from "./filename.js";
+import { AppDirs, AppDirsError } from "@effected/xdg";
+import { Effect, FileSystem, Path } from "effect";
+
+//#region src/internal/location.ts
+/**
+* Resolve a database file's location from the ambient `AppDirs`, guarding the
+* path options, and creating NOTHING. The single derivation behind both the
+* `location` statics and the layers, so a reported path and an opened path
+* cannot disagree. A bad `filename` or `subdir` dies, naming `context`.
+*/
+const resolveLocation = (context, kind, subdir, filename) => Effect.gen(function* () {
+	const invalid = badFilename(context, filename) ?? (subdir === void 0 ? void 0 : badSubdir(context, subdir));
+	if (invalid !== void 0) return yield* Effect.die(invalid);
+	const appDirs = yield* AppDirs;
+	const path = yield* Path.Path;
+	const base = appDirs.dirs[kind];
+	const dir = subdir === void 0 ? base : path.join(base, ...subdir.split("/"));
+	return {
+		kind,
+		dir,
+		file: path.join(dir, filename),
+		nested: subdir !== void 0
+	};
+});
+/**
+* Create a resolved location's directory — the ensure-before-open half of every
+* database layer here. The kind's own `ensure*` runs first; a subdirectory's
+* `mkdir -p` then reports on the same typed `AppDirsError` channel, tagged with
+* the directory kind it sits under, so a failure stays a value, never a defect.
+*/
+const ensureLocation = (location) => Effect.gen(function* () {
+	const appDirs = yield* AppDirs;
+	yield* location.kind === "state" ? appDirs.ensureState : location.kind === "data" ? appDirs.ensureData : appDirs.ensureCache;
+	if (!location.nested) return;
+	yield* (yield* FileSystem.FileSystem).makeDirectory(location.dir, { recursive: true }).pipe(Effect.mapError((cause) => new AppDirsError({
+		directory: location.kind,
+		path: location.dir,
+		cause
+	})));
+});
+
+//#endregion
+export { ensureLocation, resolveLocation };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/app",
-	"version": "0.20.0",
+	"version": "0.21.0",
 	"private": false,
 	"description": "The application control plane for Effect: one layer wiring XDG-namespaced directories, a migrated SQLite store, a TTL cache and a config file to the same place.",
 	"keywords": [
@@ -39,10 +39,10 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.14.0",
+		"@effected/config-file": "^0.14.1",
 		"@effected/glob": "^0.10.0",
 		"@effected/jsonc": "^0.15.0",
-		"@effected/store": "^0.12.0",
+		"@effected/store": "^0.13.0",
 		"@effected/toml": "^0.11.0",
 		"@effected/walker": "^0.15.0",
 		"@effected/xdg": "^0.9.0",