@smthrs/platform-bun 0.0.0-stage → 1.0.0-rc.13

package/docs/installation.md

@@ -0,0 +1,131 @@
+---
+title: "Installation"
+description: "Install @smthrs/platform-bun from npm with its required peers, the smithers-jj-export helper @smthrs/platform-node ships for the filesystem slot, the jj executable the Jj slot probes on first use, and the import forms for each entry point."
+sidebar:
+  order: 1
+---
+
+## Install the package and its peers
+
+The package is on npm under the `next` tag, which carries the 1.0 release
+candidates. Install the current candidate with Bun:
+
+```bash
+bun add @smthrs/platform-bun@1.0.0-rc.13 effect @smthrs/kernel@1.0.0-rc.13
+```
+
+`@smthrs/kernel` is on the line because the [Quickstart](./quickstart.md)'s
+`contained.ts` imports its `ProcessLedger`, which the contained bundles require.
+Bun's isolated linker and pnpm link only the packages a project declares.
+
+The manifest declares two required peers, neither optional:
+
+| Peer                    | Version                        | Why                                                       |
+| ----------------------- | ------------------------------ | --------------------------------------------------------- |
+| `effect`                | `4.0.5`                        | The runtime every service tag belongs to.                 |
+| `@smthrs/platform-node` | exactly this package's version | The atomic filesystem slot and the containment machinery. |
+
+Bun installs required peers, so the line above also installs
+`@smthrs/platform-node` at the matching version. Install one `effect` in the
+peer range so the host shares one Effect runtime. `@effect/platform-bun`,
+`@effect/platform-node` and `@effect/platform-node-shared` are bundled
+privately, built from `effect@4.0.5`, so your project installs none of them.
+
+## Supported runtimes
+
+Bun 1.4.0 or later, and Node.js 26.4.0 or later. Both are declared in
+`engines`, and both are real: the bundle falls back to the
+`@effect/platform-node` adapters off Bun, so it runs unchanged under Node. See
+[Runtime parity with Node](./concepts/runtime-parity.md) for what that does and
+does not buy you.
+
+## The filesystem helper
+
+The filesystem slot is `@smthrs/platform-node`'s `AtomicFileSystem`, which
+carries the kernel's atomic host extension. That extension does not run
+in-process: it executes each guarded path operation through the
+`smithers-jj-export` helper so the operation is descriptor-relative and
+no-follow.
+
+`@smthrs/platform-node` ships the helper prebuilt for macOS (arm64, x64), Linux
+(arm64, x64), and Windows (x64), so installing the package installs it; there
+is nothing to build. `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` only overrides the
+packaged helper with another absolute path; see
+[Configure the filesystem helper](./guides/configure-the-filesystem-helper.md).
+
+Windows is unsupported for this slot.
+
+## Install Jujutsu for the Jj slot
+
+Every bundle, `BunHost.layer`, `layerAt`, `layerContained`, and
+`layerContainedAt`, builds without jj, so a program that never calls `Jj` runs
+on a host without it. The `Jj` slot requires jj 0.39.0 or later: its first
+operation runs one `jj --version` probe, and on a host without the executable,
+or with an older one, that operation fails with `JjError` carrying
+`not_installed` or `unsupported_version`. The slot selects the executable when
+the layer is built, so restart the program after installing jj.
+
+Install [Jujutsu](https://jj-vcs.github.io), a version-control system that
+works on a Git repository, and confirm the version:
+
+```bash
+jj --version
+```
+
+This package vendors no binaries. [`@smthrs/jj`](/api/jj) documents the
+resolution order and the `SMITHERS_JJ_PATH` override for an executable that is
+not on `PATH`.
+
+A program that wants only some of the services composes the individual service
+layers instead of a complete bundle: `BunFileSystem.layer`, `Path.layer`, and
+the spawner and HTTP client layers. See
+[The Host surface on Bun](./concepts/host-surface.md) for taking one service
+without the other four.
+
+## Import forms
+
+The root entry point re-exports both modules as namespaces:
+
+```ts
+import { BunFileSystem, BunHost } from "@smthrs/platform-bun"
+```
+
+Each module is also importable from its own subpath, which is the form the
+[API reference](./api.md) uses:
+
+```ts
+import * as BunFileSystem from "@smthrs/platform-bun/BunFileSystem"
+import * as BunHost from "@smthrs/platform-bun/BunHost"
+```
+
+Two subpath forms are blocked in the export map and are not public:
+`@smthrs/platform-bun/internal/*` and `@smthrs/platform-bun/*/index`.
+`@smthrs/platform-bun/package.json` is exported.
+
+The bundle resolves `node:` built-ins, so it does not bundle for a browser. A
+page composes [`@smthrs/platform-browser`](/api/platform-browser) instead.
+
+## What a real composition adds
+
+`BunHost.layer` provides the raw host. Two additions are common:
+
+- [`@smthrs/kernel`](/api/kernel) guards it. Its `FileSystem.layer`,
+  `ChildProcessSpawner.layer`, `HttpClient.layer`, `Jj.layer`, and `Path.layer`
+  decorate the very tags this bundle provides, in place, so a capability check
+  runs before every host call. The guarded filesystem is also where the atomic
+  extension earns its keep, and it needs a `Workspace` root and a `GrantStore`.
+- A `ProcessLedger`, from `@smthrs/kernel/ProcessLedger`, is required by
+  `BunHost.layerContained` and `BunHost.layerContainedAt`. It is a requirement
+  rather than a default because only your program knows whether it has a
+  durable journal to write to. See
+  [Contain and reap child processes](./guides/contain-child-processes.md).
+
+The `Jj` slot spawns the `jj` command that
+[Install Jujutsu for the Jj slot](#install-jujutsu-for-the-jj-slot) covers. The
+slot probes it on its first operation, so jj is a requirement of the programs
+that call `Jj`, not of every host.
+
+## Next step
+
+Run a command and a file operation through the host in the
+[Quickstart](./quickstart.md).

package/docs/quickstart.md

@@ -0,0 +1,163 @@
+---
+title: "Quickstart"
+description: "Run a file operation and a command through BunHost.layer, then turn containment on and watch a spawned child enter and leave the process ledger."
+sidebar:
+  order: 2
+---
+
+This quickstart runs one program against the Bun host twice: first on the plain
+bundle, then with process containment turned on. By the end you will have
+executed a real child process through the host surface and seen its record
+appear in, and disappear from, the process ledger.
+
+## Prerequisites
+
+- Bun 1.4.0 or later, or Node.js 26.4.0 or later.
+- A project with the packages installed:
+  `bun add @smthrs/platform-bun@1.0.0-rc.13 effect @smthrs/kernel@1.0.0-rc.13`.
+  That also installs the required peer `@smthrs/platform-node`, which ships the
+  `smithers-jj-export` helper the filesystem slot runs. `@smthrs/kernel` is on
+  the line because `contained.ts` imports its `ProcessLedger`, and Bun's
+  isolated linker and pnpm link only the packages a project declares. See
+  [Installation](./installation.md).
+- [Jujutsu](https://jj-vcs.github.io) at jj 0.39.0 or later on `PATH`, only for
+  a program that calls `Jj`. Neither program below does, and every bundle
+  builds without jj; a `Jj` operation on a host without it fails with
+  `JjError` `not_installed`. See [Installation](./installation.md) for
+  `SMITHERS_JJ_PATH`.
+
+## Run a file operation and a command
+
+Create `quickstart.ts`. The program asks for two of the five host services by
+tag, and names Bun nowhere:
+
+```ts
+import { BunHost } from "@smthrs/platform-bun"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as ChildProcess from "effect/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner"
+
+const program = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  const spawner = yield* ChildProcessSpawner
+
+  yield* fs.writeFileString("report.txt", "written through the host filesystem\n")
+  const readBack = yield* fs.readFileString("report.txt")
+  const listed = yield* spawner.string(ChildProcess.make("ls", ["report.txt"]))
+
+  return { listed: listed.trim(), readBack: readBack.trim() }
+})
+
+Effect.runPromise(Effect.provide(program, BunHost.layer)).then(console.log)
+```
+
+Run it:
+
+```bash
+bun run quickstart.ts
+```
+
+```text
+{
+  listed: "report.txt",
+  readBack: "written through the host filesystem",
+}
+```
+
+`BunHost.layer` provided all five slots; the program used two of them. The
+other three were built and never asked for. Building `Jj` spawned nothing: its
+jj version probe runs on the first `Jj` operation, which this program never
+makes.
+
+## Turn containment on
+
+The plain bundle signals its target when the scope closes. A target that exits
+first can leave background descendants holding output open, and a crashed
+host cannot run that finalizer.
+
+`BunHost.layerContained` prepares a supervisor for each command, records its
+identity before target execution, and keeps a `SIGTERM`-then-`SIGKILL` deadline
+for the owned process group even after the target exits. The supervisor's
+private host connection also initiates cleanup on host loss. The required
+`ProcessLedger` lets a later host reconcile cleanup that was not confirmed;
+the memory ledger below deliberately has no persistence across restarts.
+
+Create `contained.ts`:
+
+```ts
+import * as ProcessLedger from "@smthrs/kernel/ProcessLedger"
+import { BunHost } from "@smthrs/platform-bun"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as ChildProcess from "effect/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner"
+
+const program = Effect.gen(function*() {
+  const ledger = yield* ProcessLedger.makeMemory({
+    hostId: "quickstart",
+    ownerPid: process.pid
+  })
+
+  const host = BunHost.layerContained({ graceMs: 500 }).pipe(
+    Layer.provide(Layer.succeed(ProcessLedger.ProcessLedger)(ledger))
+  )
+
+  const duringScope = yield* Effect.gen(function*() {
+    const spawner = yield* ChildProcessSpawner
+    yield* spawner.spawn(ChildProcess.make("sleep", ["30"]))
+    return yield* ledger.live
+  }).pipe(Effect.provide(host), Effect.scoped)
+
+  return { afterScope: yield* ledger.live, duringScope }
+})
+
+Effect.runPromise(program).then((result) => console.log(JSON.stringify(result, null, 2)))
+```
+
+Run it:
+
+```bash
+bun run contained.ts
+```
+
+```text
+{
+  "afterScope": [],
+  "duringScope": [
+    {
+      "pid": 51234,
+      "pgid": 51234,
+      "hostId": "quickstart",
+      "ownerPid": 51230,
+      "startedAtMs": 1756900000000,
+      "commandDigest": "sleep"
+    }
+  ]
+}
+```
+
+The recorded pid is the live supervisor, which leads the owned process group;
+it is not the native `sleep` target's pid. `commandDigest` names the executable
+and never its arguments: journal entries are permanent, and arguments carry
+credentials. A returned handle's `exitCode`
+describes the target. The record also names the host incarnation that started
+it, and it is gone after verified scope cleanup. See
+[Contain and reap child processes](./guides/contain-child-processes.md) for
+the `detached: false`, escaped-session, and unsupported-platform boundaries.
+
+Give it a durable half by swapping `ProcessLedger.makeMemory` for
+`ProcessLedger.layer`, which writes through a [`@smthrs/journal`](/api/journal)
+`Journal`. Then a crashed host's records survive, and the next incarnation
+kills what the last one abandoned while its layer is built.
+
+## Where to go next
+
+- [Contain and reap child processes](./guides/contain-child-processes.md):
+  the escalation deadline, the reaper, and the options both contained
+  factories take.
+- [Bind the host to a repository root](./guides/bind-a-repository-root.md):
+  `layerAt` and `layerContainedAt`, so `Jj` does not inherit the process
+  working directory.
+- [The Host surface on Bun](./concepts/host-surface.md): what each of the five
+  slots is, and how to take one service without the other four.

package/docs/troubleshooting.md

@@ -0,0 +1,163 @@
+---
+title: "Troubleshooting"
+description: "The failures @smthrs/platform-bun produces: a refused repository root, a filesystem guard that fails closed, an unfollowed redirect, a missing process ledger, and a browser bundle that will not resolve."
+---
+
+Find the symptom, read the cause, apply the fix. Every failure here is one this
+package or its slots actually produce; the signatures behind them are on the
+[API reference](./api.md).
+
+## BunHostError: requires an absolute repository root
+
+**Symptom.** `BunHost.layerAt` or `BunHost.layerContainedAt` throws while your
+program is still composing its layers:
+
+```text
+BunHostError: BunHost.layerAt requires an absolute repository root, got "repositories/app"
+BunHostError: BunHost.layerAt requires a repository root without NUL, got "/repo\u0000"
+```
+
+**Cause.** The root is not absolute, or it contains NUL, which no filesystem
+or process API can represent. The empty string is not absolute, and neither is
+a path that looks absolute only after the process working directory is applied.
+
+**Fix.** Resolve the root before you hand it over, and branch on
+`error.code === "invalid_repository_root"` rather than on the message text. The
+message names the Bun factory that refused and repeats at most 64 code points
+of the root, so a root taken from input cannot flood a log line. See
+[Bind the host to a repository root](./guides/bind-a-repository-root.md).
+
+## PermissionDenied: descriptor-relative filesystem isolation failed closed
+
+**Symptom.** A guarded filesystem operation fails, naming the helper it
+could not find:
+
+```text
+PlatformError: PermissionDenied: AtomicFileSystem.writeFileString (/tmp/work/x.txt):
+descriptor-relative filesystem isolation failed closed:
+Error: smithers-jj-export is missing; install @smthrs/platform-node with its native helper, ...
+```
+
+**Cause.** The filesystem slot's no-follow extension executes its syscalls
+through the `smithers-jj-export` helper, and no usable helper was found, or
+the one it was told to spawn is missing or not executable. The guard fails closed rather than falling back to a path-based
+operation, because a path-based fallback is exactly the symlink race the
+extension exists to prevent.
+
+**Fix.** Install `@smthrs/platform-node`, the required peer that ships the
+helper for macOS, Linux, and Windows, at this package's version. If
+`SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` is set, it overrides the packaged helper:
+point it at an executable helper or unset it. A source checkout of the
+repository has no packaged helper; build one there with
+`cargo build --locked --release -p smithers-ffi --bin smithers-jj-export`. See
+[Configure the filesystem helper](./guides/configure-the-filesystem-helper.md).
+
+This failure is unguarded-path-safe: it appears only under
+[`@smthrs/kernel`](/api/kernel)'s `FileSystem.layer`. A program that uses
+`BunFileSystem.layer` without the kernel's guard never starts the helper, so a
+missing helper goes unnoticed until the guard is composed.
+
+## BadResource: Not a directory, on a path that exists
+
+**Symptom.** Reading a file through a directory symlink fails with a
+`BadResource` reason, and the same path opens fine from a shell:
+
+```text
+{ "_tag": "BadResource", "syscall": "open", "description": "[Errno 20] Not a directory: 'escape'" }
+```
+
+**Cause.** This is the guard working. The component named a symlink pointing
+outside the workspace boundary, and the descriptor-relative helper refuses to
+traverse it rather than following it. A path-based filesystem would have
+followed the link and returned the bytes.
+
+**Fix.** Nothing, if the boundary is the one you meant. If the target is
+legitimately part of the workspace, move it inside the boundary root rather
+than reaching it through a link.
+
+## A 302 comes back instead of the redirected response
+
+**Symptom.** `HttpClient.execute` returns status `302` with a `location`
+header, and the destination never receives a request.
+
+**Cause.** The bundle uses the shared egress client without automatic redirects. A client that follows a
+redirect on its own reaches a second origin the capability kernel never
+authorized.
+
+**Fix.** Compose [`@smthrs/kernel`](/api/kernel)'s guarded `HttpClient.layer`,
+which follows redirects and rechecks the capability on every hop. Handling the
+`302` yourself is the other option, and it puts the authorization decision in
+your code.
+
+## layerContained will not compose without a ProcessLedger
+
+**Symptom.** `BunHost.layerContained(...)` does not satisfy a
+`Layer.Layer<BunHost>`, and the type error names
+`@smthrs/kernel/ProcessLedger`.
+
+**Cause.** Both contained factories return
+`Layer.Layer<BunHost | Crypto.Crypto, never, ProcessLedger.ProcessLedger>`.
+The ledger is a
+requirement rather than a built-in default, because the durable half is only as
+good as the journal underneath it, and only your program knows whether it has
+one.
+
+**Fix.** Provide a ledger. `ProcessLedger.layerMemory({ hostId, ownerPid })`
+contains this incarnation's children and inherits nothing;
+`ProcessLedger.layer` writes through a [`@smthrs/journal`](/api/journal)
+`Journal` and is what makes the cross-incarnation sweep real. See
+[Contain and reap child processes](./guides/contain-child-processes.md).
+
+## A contained child outlives the host
+
+**Symptom.** After a crash, a `sleep`, a `jj`, or a build tool the host started
+is still running, and the next incarnation does not kill it.
+
+**Cause, and what to check in order.**
+
+1. **The ledger was in-memory.** `ProcessLedger.layerMemory` records nothing
+   durably, so the next incarnation inherits an empty orphan set. Use
+   `ProcessLedger.layer`.
+2. **The `hostId` changed.** Inheritance is keyed on it. Two incarnations of
+   the same host must pass the same string.
+3. **The reaper declined.** `ProcessReaper.reap` refuses to signal a record
+   whose numbers do not clearly name an abandoned process: the owning
+   incarnation is alive, the pid is gone, the pid exists but did not start when
+   the record says it did, the record predates the machine's boot, or the
+   record names this host's own group. Three of those refusals leave the record
+   inherited so a later incarnation can try again.
+4. **The child was started around the host.** A process spawned with
+   `node:child_process` directly, rather than through the host's
+   `ChildProcessSpawner`, is in no ledger and no reaper can find it. Under
+   `BunHost.layer` that includes `jj`, which is why the contained factories
+   build `Jj` over the contained spawner.
+
+## A bundler cannot resolve node:fs
+
+**Symptom.** Bundling for a browser fails on `node:fs`, `node:path`, or
+`node:child_process` reached from `@smthrs/platform-bun`.
+
+**Cause.** The bundle falls back to the `@effect/platform-node` adapters off
+Bun, so it resolves `node:` built-ins by design. That is what makes one bundle
+run on both runtimes, and it is exactly what a browser bundler cannot resolve.
+
+**Fix.** Compose [`@smthrs/platform-browser`](/api/platform-browser) in the
+page. It fills the same five slots from browser primitives, so the program
+between them does not change. See
+[Runtime parity with Node](./concepts/runtime-parity.md).
+
+## Jj fails with not_installed
+
+**Symptom.** A `Jj` operation fails with a `JjError` whose code is
+`not_installed` or `unsupported_version` and whose method is `version`. The
+host built and every other service works.
+
+**Cause.** No usable `jj` executable, or one older than 0.39.0. The `Jj` slot
+probes `jj --version` on its first operation, and the operation that triggered
+the probe did not run. This package vendors no binaries and installs nothing on
+your behalf.
+
+**Fix.** Install [Jujutsu](https://jj-vcs.github.io), which provides the `jj`
+command, or set `SMITHERS_JJ_PATH` to the executable you want spawned, then
+restart the program: the slot selects the executable when the layer is built.
+[`@smthrs/jj`](/api/jj) documents the resolution order and the failure codes.

package/package.json

@@ -1,6 +1,149 @@
 {
   "name": "@smthrs/platform-bun",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.13",
+  "license": "MIT",
+  "smthrs": {
+    "group": "engine",
+    "privateEffectAdapters": [
+      "@effect/platform-bun",
+      "@effect/platform-node",
+      "@effect/platform-node-shared"
+    ]
+  },
+  "description": "Bun Host bundle for flows: Effect's Bun platform services composed into the closed Host surface",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/flows/platform-bun"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "bun",
+    "platform"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "bun",
+    "platform"
+  ],
+  "engines": {
+    "bun": ">=1.4.0",
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./internal/*": null,
+    "./*/index": null,
+    "./BunFileSystem": {
+      "import": {
+        "types": "./dist/esm/BunFileSystem.d.ts",
+        "default": "./dist/esm/BunFileSystem.js"
+      },
+      "require": {
+        "types": "./dist/cjs/BunFileSystem.d.ts",
+        "default": "./dist/cjs/BunFileSystem.js"
+      }
+    },
+    "./BunHost": {
+      "import": {
+        "types": "./dist/esm/BunHost.d.ts",
+        "default": "./dist/esm/BunHost.js"
+      },
+      "require": {
+        "types": "./dist/cjs/BunHost.d.ts",
+        "default": "./dist/cjs/BunHost.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "dist/vendor/**",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/jj": "1.0.0-rc.13",
+    "@smthrs/kernel": "1.0.0-rc.13",
+    "undici": "8.11.2",
+    "redis": "6.2.1",
+    "@types/ws": "8.18.2",
+    "ws": "8.22.0"
+  },
+  "peerDependencies": {
+    "@smthrs/platform-node": "1.0.0-rc.13",
+    "effect": "4.0.5"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/platform-bun": "4.0.5",
+    "@effect/platform-node": "4.0.5",
+    "@effect/platform-node-shared": "4.0.5",
+    "@effect/vitest": "4.0.5",
+    "@eslint/js": "9.39.5",
+    "@smthrs/platform-node": "1.0.0-rc.13",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.5",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0",
+    "@smthrs/artifacts": "1.0.0-rc.13"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  }
 }

package/src/BunFileSystem.ts

@@ -0,0 +1,47 @@
+/**
+ * Bun layer for Effect's `FileSystem` service.
+ *
+ * This is `@smthrs/platform-node`'s `AtomicFileSystem.layer`, the same
+ * implementation the Node bundle puts in its filesystem slot. It carries the
+ * kernel's atomic host extension, so `@smthrs/kernel`'s `FileSystem.layer`
+ * performs every guarded path operation descriptor-relative and no-follow
+ * instead of failing closed.
+ *
+ * The extension uses the packaged `smithers-jj-export --atomic-fs` helper.
+ * `layerWith` accepts another absolute executable path. Windows is unsupported.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as AtomicFileSystem from "@smthrs/platform-node/AtomicFileSystem"
+import type { FileSystem } from "effect/FileSystem"
+import type * as Layer from "effect/Layer"
+
+/**
+ * Provides Bun's filesystem implementation, carrying the kernel's atomic host
+ * extension.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const layer: Layer.Layer<FileSystem> = AtomicFileSystem.layer
+
+/**
+ * Provides the same filesystem against an explicitly configured helper and
+ * set of byte limits.
+ *
+ * This is the escape hatch for a host with a different packaged helper path.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerWith: (options: AtomicFileSystem.Options) => Layer.Layer<FileSystem> = AtomicFileSystem.layerWith
+
+/**
+ * The helper path and byte limits {@link layerWith} accepts.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Options = AtomicFileSystem.Options