@effected/app 0.1.0

package/App.js

@@ -0,0 +1,77 @@
+import { AppCache } from "./AppCache.js";
+import { AppStore } from "./AppStore.js";
+import { Cache, Store } from "@effected/store";
+import { AppDirs, Xdg, XdgPaths } from "@effected/xdg";
+import { FileSystem, Layer, Path } from "effect";
+
+//#region src/App.ts
+/** The synthetic default XDG environment `layerTest` resolves against. */
+const testPaths = () => XdgPaths.make({
+	home: "/home/test",
+	configHome: "/home/test/.config",
+	dataHome: "/home/test/.local/share",
+	cacheHome: "/home/test/.cache",
+	stateHome: "/home/test/.local/state",
+	configDirs: ["/etc/xdg"],
+	dataDirs: ["/usr/local/share", "/usr/share"]
+});
+/**
+* Build the application control plane: namespaced directories, the state
+* database and the cache database, all pointed at the same place.
+*
+* @remarks
+* Composition is `AppDirs.layer(options)` `provideMerge` `Xdg.layer`, with the
+* {@link AppStore} and {@link AppCache} glue `provideMerge`d over the result,
+* 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.
+*
+* 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
+* databases — two connections onto one file, two migration ledgers, and two
+* independent `CacheEvent` PubSubs whose subscribers each see half the events.
+*/
+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);
+};
+/**
+* The hermetic control plane: fixed XDG paths, `:memory:` databases, and the
+* platform layers provided internally.
+*
+* @remarks
+* `Xdg.layerFrom` over a synthetic default {@link XdgPaths}, `Store.layerTest`
+* and `Cache.layerTest`, with `Path.layer` and `FileSystem.layerNoop` provided
+* **internally** via `Layer.provide` — not merged into the output, not
+* exposed. A consumer's first test needs no platform package at all.
+*
+* The documented limit: code paths that actually exercise `ensure*` **die**
+* against `FileSystem.layerNoop` — it is a stub, not a working filesystem.
+* `layerTest` is for testing logic that *uses* the control plane; a test of
+* real directory behaviour uses {@link (App:variable).layer} with a
+* temp-directory `HOME`.
+*/
+const layerTest = (options) => {
+	const dirs = Layer.provideMerge(AppDirs.layer({ namespace: options.namespace }), Xdg.layerFrom(options.paths ?? testPaths()));
+	const databases = Layer.mergeAll(Store.layerTest(options.store ?? { migrations: [] }), Cache.layerTest(options.cache));
+	return Layer.provide(Layer.mergeAll(databases, dirs), Layer.mergeAll(Path.layer, FileSystem.layerNoop({})));
+};
+/**
+* The application control plane: one layer wiring `Xdg`, `AppDirs`, `Store`
+* and `Cache` to the same namespace.
+*
+* @public
+*/
+const App = {
+	layer,
+	layerTest
+};
+
+//#endregion
+export { App };

package/AppCache.js

@@ -0,0 +1,43 @@
+import { badFilename } from "./internal/filename.js";
+import { Cache } from "@effected/store";
+import { AppDirs } from "@effected/xdg";
+import { Effect, Layer, Path } from "effect";
+
+//#region src/AppCache.ts
+/**
+* Build the cache-directory database layer: `AppDirs.ensureCache`, then
+* `Cache.layerSqlite` at `<cache dir>/<filename>`.
+*
+* @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.
+*
+* 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.
+*/
+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 cache-directory database glue: a TTL `Cache` whose file lives in the
+* ambient `AppDirs` cache directory.
+*
+* @public
+*/
+const AppCache = { layer };
+
+//#endregion
+export { AppCache };

package/AppConfig.js

@@ -0,0 +1,60 @@
+import { badFilename } from "./internal/filename.js";
+import { AppDirs, XdgConfig } from "@effected/xdg";
+import { Effect, Layer } from "effect";
+import { ConfigFile, MergeStrategy } from "@effected/config-file";
+
+//#region src/AppConfig.ts
+/**
+* Build the xdg-flavored config layer for a `ConfigFile.Service` class.
+*
+* @remarks
+* Wraps `ConfigFile.layer(tag, …)` with the resolver chain xdg documents, in
+* xdg's documented order — `XdgConfig.resolver`, then
+* `XdgConfig.nativeResolver` — and with `defaultPath:
+* XdgConfig.savePath(filename)`, which fits config-file's infallible
+* `defaultPath` slot without an `orDie` because xdg resolves at
+* layer-construction time.
+*
+* **The namespace is never a parameter.** It is read from the ambient
+* {@link AppDirs} service at layer build time, so it is typed exactly once, in
+* `App.layer` — the two-strings drift where an app passes `"myapp"` to
+* `App.layer` and `"my-app"` to its config preset cannot happen.
+*
+* 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.
+*/
+const layer = (tag, options) => Layer.unwrap(Effect.gen(function* () {
+	const invalid = badFilename("AppConfig.layer", options.filename);
+	if (invalid !== void 0) return yield* Effect.die(invalid);
+	const appDirs = yield* AppDirs;
+	const resolvers = options.native === false ? [XdgConfig.resolver({ filename: options.filename })] : [XdgConfig.resolver({ filename: options.filename }), XdgConfig.nativeResolver({
+		namespace: appDirs.namespace,
+		filename: options.filename
+	})];
+	return ConfigFile.layer(tag, {
+		schema: options.schema,
+		codec: options.codec,
+		strategy: options.strategy ?? MergeStrategy.firstMatch(),
+		resolvers,
+		defaultPath: XdgConfig.savePath(options.filename),
+		...options.validate !== void 0 && { validate: options.validate },
+		...options.events !== void 0 && { events: options.events }
+	});
+}));
+/**
+* The xdg-flavored `ConfigFile` preset: discovery through the app's XDG
+* config search path, saves into the app's own config directory.
+*
+* @remarks
+* A free-standing export, deliberately separate from anything that reaches
+* the sqlite driver: `AppConfig` reaches `@effected/xdg` and
+* `@effected/config-file` only, so a consumer who wants XDG-placed config
+* files and no database imports it without pulling a SQLite driver into
+* their graph.
+*
+* @public
+*/
+const AppConfig = { layer };
+
+//#endregion
+export { AppConfig };

package/AppStore.js

@@ -0,0 +1,45 @@
+import { badFilename } from "./internal/filename.js";
+import { Store } from "@effected/store";
+import { AppDirs } from "@effected/xdg";
+import { Effect, Layer, Path } from "effect";
+
+//#region src/AppStore.ts
+/**
+* Build the state-directory database layer: `AppDirs.ensureState`, then
+* `Store.layerSqlite` at `<state dir>/<filename>`.
+*
+* @remarks
+* The ensure-before-open ordering is the load-bearing glue.
+* `SqliteClient.layer` has no error channel and **defects** on a missing
+* parent directory; `AppDirs.ensureState` is a `mkdir -p` on a **typed**
+* `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.
+*
+* 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.
+*/
+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 state-directory database glue: a migrated SQLite `Store` whose file
+* lives in the ambient `AppDirs` state directory.
+*
+* @public
+*/
+const AppStore = { layer };
+
+//#endregion
+export { AppStore };

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/README.md

@@ -0,0 +1,210 @@
+# @effected/app
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fapp?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/app)
+[![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/)
+
+The application control plane for Effect. `App.layer` gives an application its XDG-namespaced directories, a migrated SQLite state database, a TTL cache and — through `AppConfig.layer` — a config file, all pointed at the same place, with the namespace typed exactly once. It is a composition over [`@effected/xdg`](../xdg), [`@effected/store`](../store) and [`@effected/config-file`](../config-file), and nothing else.
+
+> **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/app
+
+Every application built on this kit writes the same forty lines of wiring, and it is the kind of wiring that looks right and is wrong. `@effected/xdg` resolves where a namespace's directories are. `@effected/store` opens a database at a path. Between them sits an ordering nobody thinks about until it bites: `SqliteClient.layer` has no error channel and **defects** on a missing parent directory, so the directory must be ensured *before* the store layer is built, or the failure arrives as a defect that nothing downstream can catch typed.
+
+The other half is the namespace itself. An application names it for its directories, then names it again for its config file, and the two strings drift — `"myapp"` here, `"my-app"` there — and now it reads config from a directory nothing else in the process ever writes to.
+
+This package is the composition that gets both right, and that is all it is. It owns **no domain logic**: no service, no schema, no error class, and it re-exports nothing. The entire surface is layer factories, one config preset and one type alias. If a change here wants a `Context.Service`, that is the signal the change belongs in one of the three packages beneath it.
+
+**Nothing may depend on `@effected/app`.** A library taking an application control plane as a dependency would drag a SQLite driver into its own consumers' trees. This is the package an application composes at its edge — and the only one in the kit whose docs show where OpenTelemetry goes.
+
+## Install
+
+```bash
+npm install @effected/app effect @effected/xdg @effected/store @effected/config-file
+```
+
+```bash
+pnpm add @effected/app effect @effected/xdg @effected/store @effected/config-file
+```
+
+Requires Node.js >=24.11.0.
+
+There are **no runtime dependencies**. `effect` v4 is a peer dependency, and so are `@effected/xdg`, `@effected/store` and `@effected/config-file` — which is load-bearing rather than incidental. Each of the three appears in this package's public signature types, so a second copy of any of them in your graph would mint two distinct service tags for one concept and the layer would silently fail to satisfy the requirement. Single copies are the point, and that is exactly what a peer declares. Package managers that install peers automatically will pull them in; add them to your manifest explicitly if yours does not.
+
+The package is integrated tier **by inheritance, not by anything it does**: `@effected/store` reaches `@effect/sql-sqlite-node`, and that propagates. It performs no IO the three packages beneath it do not already perform.
+
+Creating directories needs a `FileSystem` and a `Path` implementation, provided once at the edge — from `@effect/platform-node` on Node.
+
+## Quick start
+
+A config file, a cache and a state database, over one platform import:
+
+```ts
+import { App, AppConfig } from "@effected/app";
+import { ConfigFile, JsonCodec } from "@effected/config-file";
+import { Cache, Store } from "@effected/store";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Layer, Schema } from "effect";
+
+class Settings extends Schema.Class<Settings>("Settings")({
+  registry: Schema.String,
+  concurrency: Schema.Number,
+}) {}
+class SettingsFile extends ConfigFile.Service<SettingsFile, Settings>()("myapp/Settings") {}
+
+const migrations = [
+  { id: 1, name: "runs", up: (sql) => sql`CREATE TABLE runs (id TEXT PRIMARY KEY, at TEXT)` },
+];
+
+// Bound once, to a const — see Memoization below. This is the whole control plane:
+// XDG dirs for "myapp", store.db in the state dir, cache.db in the cache dir.
+const AppLive = App.layer({ namespace: "myapp", store: { migrations }, cache: { maxEntries: 500 } });
+
+const ConfigLive = AppConfig.layer(SettingsFile, {
+  filename: "config.json", // no namespace: it comes from AppLive's AppDirs
+  schema: Settings,
+  codec: JsonCodec,
+});
+
+const MainLive = ConfigLive.pipe(
+  Layer.provideMerge(AppLive),
+  Layer.provide(NodeServices.layer), // the one place a platform is named
+);
+
+const main = Effect.gen(function* () {
+  const settings = yield* (yield* SettingsFile).load;
+  const store = yield* Store;
+  const cache = yield* Cache;
+
+  yield* store.client`INSERT INTO runs (id, at) VALUES (${crypto.randomUUID()}, datetime())`;
+  yield* cache.set({ key: "last-registry", value: new TextEncoder().encode(settings.registry) });
+});
+
+NodeRuntime.runMain(main.pipe(Effect.provide(MainLive)));
+```
+
+Four services, one platform import, one namespace typed once, and every failure on the typed channel. That is the whole package.
+
+## Where the files land
+
+`App.layer` ensures each directory before it opens anything in it. With `namespace: "myapp"` and the default `native: false`, the XDG rules apply on every platform:
+
+| What | Directory | Default file |
+| ---- | --------- | ------------ |
+| State database | `$XDG_STATE_HOME/myapp` — `~/.local/state/myapp` | `store.db` |
+| Cache database | `$XDG_CACHE_HOME/myapp` — `~/.cache/myapp` | `cache.db` |
+| Config file | `$XDG_CONFIG_HOME/myapp` — `~/.config/myapp` | your `filename` |
+
+`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.
+
+## The namespace is typed once
+
+`AppConfig.layer` takes no namespace. It reads one from the ambient `AppDirs` service at layer build time, so the namespace is named exactly once — in `App.layer` — and the two-strings drift cannot happen. Anything that can be derived is not asked for.
+
+What it does take is a **codec, required**, never inferred from the filename's extension. Inferring one would hard-code a *format* choice into a composition layer, which is not this package's decision to make; and the named import is also what keeps the other three parsing engines out of your bundle.
+
+`AppConfig` lives in its own module and reaches `@effected/xdg` and `@effected/config-file` **only** — never `@effected/store`. An application that wants XDG-placed config files and no database imports `AppConfig` alone, and no SQLite driver enters its graph. `App`, `AppStore` and `AppCache` are the exports that reach a database, and keeping the two graphs apart is why there is no `App = { … }` namespace object here.
+
+Its `native` option defaults to **`true`** — the opposite of `AppDirsOptions.native`, and the asymmetry is deliberate. *Creating* a native directory commits an application to a location, so it is opt-in; *probing* one for a config file the user already put there costs a `stat` that finds nothing, so it is opt-out. Reading `~/Library/Application Support` is a courtesy; writing there uninvited is not.
+
+## Ensure before open
+
+The one thing this package actually claims. `AppStore.layer` yields `AppDirs`, runs `ensureState`, joins the path, and only then hands it to `Store.layerSqlite`; `AppCache.layer` does the same over `ensureCache`. That ordering converts a defect surface into a typed one — `AppDirs.ensure*` is a `mkdir -p` on a **typed** `AppDirsError` channel, so "the state directory could not be created" arrives as a recoverable boundary failure rather than a die.
+
+Nothing is `orDie`d to make a signature tidier. A regression test pins an unwritable ancestor to a typed failure and watches for a die.
+
+`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. The honest consequence: passing no `cache` options **still opens `cache.db`**, because every `CacheOptions` field is optional and absence means defaults, not absence.
+
+## Memoization: bind the layer to a const
+
+Every export here is a **parameterized layer factory**, and Effect memoizes layers **by reference**. Each call to `App.layer(…)` builds a new one.
+
+```ts
+const AppLive = App.layer({ namespace: "myapp", store: { migrations } }); // once
+```
+
+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.
+
+## 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:
+
+```ts
+import { App } from "@effected/app";
+import { layer } from "@effect/vitest";
+import { Effect } from "effect";
+
+layer(App.layerTest({ namespace: "myapp" }))("app", (it) => {
+  it.effect("stores state", () =>
+    Effect.gen(function* () {
+      // Store and Cache are here, in memory, hermetic.
+    }));
+});
+```
+
+The documented limit, stated up front so nobody finds it in a debugger: code paths that actually exercise `ensure*` **die** against the stub filesystem `layerTest` provides. It is for testing logic that *uses* the control plane. Real directory behavior is tested through `App.layer` against a temp-directory `HOME`, which is what this package's own integration suite does.
+
+## Errors
+
+`AppError` is a **type-only** alias — the copy-pasteable union for the `catchTags` block at the application edge. It defines nothing: every tag in it is raised, and documented, by the package beneath that owns the operation, and each flows through unwrapped. A `StoreMigrationError` that reaches your handler still carries the migration's `id`, `name` and `direction`.
+
+| Tag | Raised by | Means |
+| --- | --------- | ----- |
+| `XdgEnvError` | [`@effected/xdg`](../xdg) | `$HOME` is not set — the one environment failure there is. |
+| `AppDirsError` | [`@effected/xdg`](../xdg) | A directory could not be created. Check permissions. |
+| `StoreError` | [`@effected/store`](../store) | The state database's own SQL failed — ledger bookkeeping, or the queries around a migration. |
+| `StoreMigrationError` | [`@effected/store`](../store) | One of your migrations failed. Carries `direction`, `id` and `name`. |
+| `CacheError` | [`@effected/store`](../store) | A cache operation's SQL failed. A cache is a cache — falling back to the origin is usually right. |
+
+Wiring mistakes are **defects**, not errors: a `filename` that is not a single path component dies at layer construction, as does a `namespace` that would escape `$HOME`. They can only come from code.
+
+## Telemetry goes at the app edge
+
+This package emits **no spans of its own**, deliberately. Every fallible operation in the glue is already spanned by the package that owns it — `AppDirs.ensure*` by xdg, migrations and every `Cache` method by store, every `ConfigFile` method by config-file. A span here would be a span around another package's span.
+
+Every library in this kit is telemetry-agnostic and none of them import `@effect/opentelemetry`. **Applications do, exactly once, at the top:**
+
+```ts
+import { NodeSdk } from "@effect/opentelemetry";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+const TelemetryLive = NodeSdk.layer(() => ({
+  resource: { serviceName: "myapp" },
+  spanProcessor: new BatchSpanProcessor(new OTLPTraceExporter()),
+}));
+
+const MainLive = ConfigLive.pipe(
+  Layer.provideMerge(AppLive),
+  Layer.provide(NodeServices.layer),
+  Layer.provide(TelemetryLive), // composed once, beneath everything
+);
+```
+
+Provide it beneath the stack and every span the kit's packages already emit — directory creation, migrations, cache reads, config loads — arrives at your collector. Nothing in the libraries changes, because a library that chose an exporter for you would be making an application's decision.
+
+## 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.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.
+- `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.
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,179 @@
+import { Cache, CacheError, CacheOptions, Store, StoreError, StoreMigrationError, StoreOptions } from "@effected/store";
+import { AppDirs, AppDirsError, AppDirsOptions, Xdg, XdgEnvError, XdgPaths } from "@effected/xdg";
+import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
+import { ConfigCodec, ConfigEvents, ConfigEventsShape, ConfigFileShape, ConfigValidationError, MergeStrategy } from "@effected/config-file";
+//#region src/AppCache.d.ts
+/**
+ * Options for {@link (AppCache:variable).layer}.
+ *
+ * @public
+ */
+interface AppCacheOptions extends CacheOptions {
+  /**
+   * File name within the app's cache directory. Default `"cache.db"`.
+   *
+   * @remarks
+   * A single path component. An empty name, or one containing a separator,
+   * would escape the namespace directory, so it **dies** at layer
+   * construction — it can only come from code, never from user input.
+   */
+  readonly filename?: string;
+}
+/**
+ * The cache-directory database glue: a TTL `Cache` whose file lives in the
+ * ambient `AppDirs` cache directory.
+ *
+ * @public
+ */
+declare const AppCache: {
+  readonly layer: (options?: AppCacheOptions) => Layer.Layer<Cache, AppDirsError | CacheError, AppDirs | Path.Path>;
+};
+//#endregion
+//#region src/AppStore.d.ts
+/**
+ * Options for {@link (AppStore:variable).layer}.
+ *
+ * @public
+ */
+interface AppStoreOptions extends StoreOptions {
+  /**
+   * File name within the app's state directory. Default `"store.db"`.
+   *
+   * @remarks
+   * A single path component. An empty name, or one containing a separator,
+   * would escape the namespace directory, so it **dies** at layer
+   * construction — it can only come from code, never from user input.
+   */
+  readonly filename?: string;
+}
+/**
+ * The state-directory database glue: a migrated SQLite `Store` whose file
+ * lives in the ambient `AppDirs` state directory.
+ *
+ * @public
+ */
+declare const AppStore: {
+  readonly layer: (options: AppStoreOptions) => Layer.Layer<Store, AppDirsError | StoreError | StoreMigrationError, AppDirs | Path.Path>;
+};
+//#endregion
+//#region src/App.d.ts
+/**
+ * Everything that can come out of the control plane, for the application
+ * edge's `catchTags` block.
+ *
+ * @remarks
+ * A **type-only** alias — it erases, so it costs nothing in the module graph
+ * and creates no runtime binding to tree-shake around. It is a convenience
+ * over the constituent packages' errors, not a new error model: every tag in
+ * it is defined and documented by the package that raises it, and each flows
+ * through unwrapped with its structure intact.
+ *
+ * @public
+ */
+type AppError = XdgEnvError | AppDirsError | StoreError | StoreMigrationError | CacheError;
+/**
+ * Options for {@link (App:variable).layer}.
+ *
+ * @remarks
+ * The `AppDirsOptions` fields — `namespace`, `native`, `fallbackDir`, `dirs` —
+ * are pass-through: they mean exactly what `@effected/xdg` documents,
+ * including the five-level precedence ladder.
+ *
+ * @public
+ */
+interface AppOptions extends AppDirsOptions {
+  /** The state database's options; `migrations` is the consumer's schema. */
+  readonly store: AppStoreOptions;
+  /** The cache database's options. Absence means defaults, not absence. */
+  readonly cache?: AppCacheOptions;
+}
+/**
+ * Options for {@link (App:variable).layerTest}.
+ *
+ * @public
+ */
+interface AppTestOptions {
+  /** The application namespace — one path component. */
+  readonly namespace: string;
+  /** Pin real XDG paths; defaults to a synthetic set under a fake home. */
+  readonly paths?: XdgPaths;
+  /** The in-memory state database's options. Default: no migrations. */
+  readonly store?: StoreOptions;
+  /** The in-memory cache's options. */
+  readonly cache?: CacheOptions;
+}
+/**
+ * The application control plane: one layer wiring `Xdg`, `AppDirs`, `Store`
+ * and `Cache` to the same namespace.
+ *
+ * @public
+ */
+declare const App: {
+  readonly layer: (options: AppOptions) => Layer.Layer<Xdg | AppDirs | Store | Cache, AppError, FileSystem.FileSystem | Path.Path>;
+  readonly layerTest: (options: AppTestOptions) => Layer.Layer<Xdg | AppDirs | Store | Cache, AppError>;
+};
+//#endregion
+//#region src/AppConfig.d.ts
+/**
+ * Options for {@link (AppConfig:variable).layer}.
+ *
+ * @public
+ */
+interface AppConfigOptions<A, I> {
+  /**
+   * The config file's name within the app's config directory.
+   *
+   * @remarks
+   * No default — a config filename is the consumer's decision. A single path
+   * component: an empty name, or one containing a separator, **dies** at
+   * layer construction.
+   */
+  readonly filename: string;
+  /** The schema every discovered document is decoded through. */
+  readonly schema: Schema.Codec<A, I>;
+  /**
+   * How file content becomes an unknown document, and back.
+   *
+   * @remarks
+   * Required — never inferred, never defaulted. Defaulting it, or inferring
+   * one from `filename`'s extension, would hard-code a *format* choice into a
+   * composition layer, which is not this package's decision to make. The
+   * named import (`JsonCodec`, `TomlCodec`, …) is also what keeps the other
+   * engines out of the consumer's bundle.
+   */
+  readonly codec: ConfigCodec;
+  /** How several discovered sources become one value. Default `MergeStrategy.firstMatch`. */
+  readonly strategy?: MergeStrategy<A>;
+  /** An optional caller-supplied check run after schema decoding. */
+  readonly validate?: (value: A) => Effect.Effect<A, ConfigValidationError>;
+  /** The opt-in event hook. Pass the `ConfigEvents` class itself. */
+  readonly events?: Context.Key<ConfigEvents, ConfigEventsShape>;
+  /**
+   * Probe the OS-native config directory as a fallback. Defaults to `true`.
+   *
+   * @remarks
+   * The native probe sits **after** the XDG resolver, so an existing
+   * `~/.config/<app>` still beats the native directory; on Linux it resolves
+   * to nothing and never touches the filesystem. Pass `false` to drop it.
+   */
+  readonly native?: boolean;
+}
+/**
+ * The xdg-flavored `ConfigFile` preset: discovery through the app's XDG
+ * config search path, saves into the app's own config directory.
+ *
+ * @remarks
+ * A free-standing export, deliberately separate from anything that reaches
+ * the sqlite driver: `AppConfig` reaches `@effected/xdg` and
+ * `@effected/config-file` only, so a consumer who wants XDG-placed config
+ * files and no database imports it without pulling a SQLite driver into
+ * their graph.
+ *
+ * @public
+ */
+declare const AppConfig: {
+  readonly layer: <Self, A, I>(tag: Context.Key<Self, ConfigFileShape<A>>, options: AppConfigOptions<A, I>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | AppDirs | Xdg>;
+};
+//#endregion
+export { App, AppCache, type AppCacheOptions, AppConfig, type AppConfigOptions, type AppError, type AppOptions, AppStore, type AppStoreOptions, type AppTestOptions };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,6 @@
+import { AppCache } from "./AppCache.js";
+import { AppStore } from "./AppStore.js";
+import { App } from "./App.js";
+import { AppConfig } from "./AppConfig.js";
+
+export { App, AppCache, AppConfig, AppStore };

package/internal/filename.js

@@ -0,0 +1,15 @@
+//#region src/internal/filename.ts
+/**
+* A filename is one path component. Anything else escapes the app's own
+* directory, so it dies rather than resolving somewhere surprising — the same
+* wiring-defect rule xdg applies to `namespace`. Shared by every module with
+* a `filename` option, so a new rejected shape is added here once; the
+* test-side mirror is `__test__/filenameGuard.ts`.
+*/
+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)}`);
+};
+
+//#endregion
+export { badFilename };

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@effected/app",
+	"version": "0.1.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": [
+		"app",
+		"xdg",
+		"sqlite",
+		"store",
+		"cache",
+		"config",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/app#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/app"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"@effected/config-file": "0.1.0",
+		"@effected/store": "0.1.0",
+		"@effected/xdg": "0.1.0",
+		"effect": "4.0.0-beta.98"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}