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

package/docs/installation.md

@@ -0,0 +1,128 @@
+---
+title: "Installation"
+description: "Install @smthrs/platform-bun, its required peers, the smithers-jj-export helper the filesystem slot needs, the jj executable every complete bundle probes at startup, and the import forms for each entry point."
+sidebar:
+  order: 1
+---
+
+## Install the package and its peers
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Version 1.0.0-rc.0 is not on npm yet. Until it is published, take the package
+from [the repository](https://github.com/smithersai/smithers); the rest of this
+page applies either way.
+
+The manifest declares five required peers, none optional:
+
+| Peer                           | Version        | Why                                                        |
+| ------------------------------ | -------------- | ---------------------------------------------------------- |
+| `effect`                       | `4.0.0-rc.115` | The runtime every service tag belongs to.                  |
+| `@effect/platform-bun`         | `4.0.0-rc.115` | Imported at module load by the root entry and `BunHost`.   |
+| `@effect/platform-node`        | `4.0.0-rc.115` | The Node adapters the bundle falls back to off Bun.        |
+| `@effect/platform-node-shared` | `4.0.0-rc.115` | The shared adapter implementation both Effect bundles use. |
+| `@smthrs/platform-node`        | `1.0.0-rc.0`   | The atomic filesystem slot and the containment machinery.  |
+
+Package managers that resolve required peers install all five automatically;
+the command above pins them so a lockfile records the versions. All Effect
+versions are exact so the host shares one compatible Effect runtime.
+
+## 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.
+
+## Install 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. From a source checkout, build it with:
+
+```bash
+cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
+```
+
+Elsewhere, set `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` to its absolute path; see
+[Configure the filesystem helper](./guides/configure-the-filesystem-helper.md).
+
+Windows is unsupported for this slot.
+
+## Install Jujutsu for the complete bundles
+
+Every complete bundle, `BunHost.layer`, `layerAt`, `layerContained`, and
+`layerContainedAt`, requires jj 0.39.0 or later on the host, whether or not
+the program uses the `Jj` slot. Each factory merges its `Jj` layer with the
+other four, and that layer runs one `jj --version` probe while the layer is
+built. On a host without the executable, or with an older one, construction
+fails with `JjError` carrying `not_installed` or `unsupported_version` before
+the program body runs, even for a program that asked for only `FileSystem`.
+
+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 must run without jj composes the individual service layers
+instead of a complete bundle: `BunFileSystem.layer`, `Path.layer`, and the
+spawner and HTTP client layers each build without a probe. 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 complete bundles](#install-jujutsu-for-the-complete-bundles)
+covers. A bundle probes it at construction, so the executable is a startup
+requirement rather than a slot the program opts into.
+
+## Next step
+
+Run a command and a file operation through the host in the
+[Quickstart](./quickstart.md).

package/docs/quickstart.md

@@ -0,0 +1,159 @@
+---
+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.
+- The `smithers-jj-export` helper. See
+  [Installation](./installation.md#install-the-filesystem-helper).
+- [Jujutsu](https://jj-vcs.github.io) at jj 0.39.0 or later on `PATH`. Confirm
+  it with `jj --version`. Neither program below touches `Jj`, but every
+  complete bundle probes jj while the layer is built and fails with `JjError`
+  before the program body runs when it is missing. See
+  [Installation](./installation.md) for `SMITHERS_JJ_PATH` and for composing
+  service layers without jj.
+- A package with the dependencies installed. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+## 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/unstable/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/unstable/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, and building `Jj` is where the
+jj version probe ran.
+
+## 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/unstable/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/unstable/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,178 @@
+---
+title: "Troubleshooting"
+description: "The failures @smthrs/platform-bun produces: a missing required peer, 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).
+
+## ERR_MODULE_NOT_FOUND for @effect/platform-bun/BunChildProcessSpawner
+
+**Symptom.** The first `import { BunHost } from "@smthrs/platform-bun"`, or
+`import * as BunHost from "@smthrs/platform-bun/BunHost"`, throws
+`ERR_MODULE_NOT_FOUND` before any of your code runs.
+
+**Cause.** The install is missing the required `@effect/platform-bun` peer,
+which both the root entry point and `BunHost` import at module load. This can
+happen with an older package version that marked it optional, or when peer
+installation was disabled.
+
+**Fix.** Install it yourself, at the version your composition's `effect` is
+built against:
+
+```bash
+pnpm add @effect/platform-bun@4.0.0-rc.115 @effect/platform-node-shared@4.0.0-rc.115
+```
+
+`@smthrs/platform-bun/BunFileSystem` is the one entry point that resolves
+without it, because it imports nothing from `@effect/platform-bun`.
+
+## 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"
+```
+
+**Cause.** The root is not absolute. The empty string counts, and so does 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.** Run `cargo build --locked --release -p smithers-ffi --bin smithers-jj-export`
+in a source checkout, or set `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` to an
+absolute helper path. 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, JjError, 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.** Building any complete bundle fails with a `JjError` whose code
+is `not_installed` or `unsupported_version` before the program body runs,
+even when the program never asks for `Jj`.
+
+**Cause.** No usable `jj` executable, or one older than 0.39.0. Every
+`BunHost` factory builds its `Jj` layer eagerly, and that layer probes
+`jj --version` at construction. 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.
+[`@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.4",
+  "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.4",
+    "@smthrs/kernel": "1.0.0-rc.4",
+    "undici": "8.10.2",
+    "redis": "6.2.1",
+    "@types/ws": "8.18.1",
+    "ws": "8.21.3"
+  },
+  "peerDependencies": {
+    "@smthrs/platform-node": "1.0.0-rc.4",
+    "effect": "4.0.0-rc.115"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/platform-bun": "4.0.0-rc.115",
+    "@effect/platform-node": "4.0.0-rc.115",
+    "@effect/platform-node-shared": "4.0.0-rc.115",
+    "@effect/vitest": "4.0.0-rc.115",
+    "@eslint/js": "9.39.5",
+    "@smthrs/platform-node": "1.0.0-rc.4",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.0-rc.115",
+    "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.4"
+  },
+  "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