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

package/dist/vendor/platform-node.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+/**
+ * @stability experimental
+ * @since 4.0.0
+ */
+export * as NodeAddressResolver from "./node/NodeAddressResolver.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeChildProcessSpawner from "./node/NodeChildProcessSpawner.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeClusterHttp from "./node/NodeClusterHttp.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeClusterSocket from "./node/NodeClusterSocket.ts";
+/**
+ * @stability unstable
+ * @since 1.0.0
+ */
+export * as NodeCrypto from "./node/NodeCrypto.ts";
+/**
+ * @stability experimental
+ * @since 4.0.0
+ */
+export * as NodeDatagramSocket from "./node/NodeDatagramSocket.ts";
+/**
+ * @stability experimental
+ * @since 4.0.0
+ */
+export * as NodeDns from "./node/NodeDns.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeFileSystem from "./node/NodeFileSystem.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeHttpClient from "./node/NodeHttpClient.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeHttpIncomingMessage from "./node/NodeHttpIncomingMessage.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeHttpPlatform from "./node/NodeHttpPlatform.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeHttpServer from "./node/NodeHttpServer.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeHttpServerRequest from "./node/NodeHttpServerRequest.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeMultipart from "./node/NodeMultipart.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeMultipartParser from "./node/NodeMultipartParser.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodePath from "./node/NodePath.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeRedis from "./node/NodeRedis.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeRuntime from "./node/NodeRuntime.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeServices from "./node/NodeServices.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeSink from "./node/NodeSink.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeSocket from "./node/NodeSocket.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeSocketServer from "./node/NodeSocketServer.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeStdio from "./node/NodeStdio.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeStream from "./node/NodeStream.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeTerminal from "./node/NodeTerminal.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeWorker from "./node/NodeWorker.ts";
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as NodeWorkerRunner from "./node/NodeWorkerRunner.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/vendor/platform-node.js

@@ -0,0 +1,130 @@
+import "./chunk-6QPSLCUZ.js";
+import {
+  NodeSocketServer_exports
+} from "./chunk-J43O5GFH.js";
+import {
+  NodeWorker_exports
+} from "./chunk-YJGNV6EV.js";
+import {
+  NodeWorkerRunner_exports
+} from "./chunk-6R444NFO.js";
+import {
+  NodeRedis_exports
+} from "./chunk-XDPP24MG.js";
+import {
+  NodeRuntime_exports
+} from "./chunk-DWSNOBD4.js";
+import {
+  NodeDatagramSocket_exports
+} from "./chunk-4YK2MHSO.js";
+import "./chunk-TCKM3JXD.js";
+import {
+  NodeDns_exports
+} from "./chunk-2LGUVSNM.js";
+import {
+  NodeHttpServerRequest_exports
+} from "./chunk-NNTJGFLB.js";
+import {
+  NodeAddressResolver_exports
+} from "./chunk-OV2KKGBA.js";
+import {
+  NodeClusterHttp_exports
+} from "./chunk-KANNAI65.js";
+import {
+  NodeHttpServer_exports
+} from "./chunk-6KYVM2ZC.js";
+import {
+  NodeMultipart_exports
+} from "./chunk-QKYYD3AZ.js";
+import {
+  NodeMultipartParser_exports
+} from "./chunk-X6FYP2EH.js";
+import {
+  NodeServices_exports
+} from "./chunk-DHTPLWAP.js";
+import {
+  NodeStdio_exports
+} from "./chunk-WGUQHMX2.js";
+import {
+  NodeTerminal_exports
+} from "./chunk-GITB76ZP.js";
+import {
+  NodePath_exports
+} from "./chunk-XF3WZCMZ.js";
+import {
+  NodeSocket_exports
+} from "./chunk-GMORYZG4.js";
+import {
+  NodeHttpPlatform_exports
+} from "./chunk-KEMBVIRS.js";
+import {
+  NodeChildProcessSpawner_exports
+} from "./chunk-QLI7T34M.js";
+import {
+  NodeClusterSocket_exports
+} from "./chunk-2AP6TO77.js";
+import {
+  NodeHttpClient_exports
+} from "./chunk-V577GRCI.js";
+import {
+  NodeSink_exports
+} from "./chunk-XAVBQY4D.js";
+import {
+  NodeHttpIncomingMessage_exports
+} from "./chunk-AMAL6TRE.js";
+import {
+  NodeFileSystem_exports
+} from "./chunk-WNS3OER2.js";
+import {
+  NodeStream_exports
+} from "./chunk-S3MN5OXB.js";
+import {
+  NodeCrypto_exports
+} from "./chunk-ZJEHEPDQ.js";
+import "./chunk-BHV44Z6K.js";
+import "./chunk-AW6WQVI7.js";
+import "./chunk-226TYKP6.js";
+import "./chunk-FIPFWLCV.js";
+import "./chunk-PBM2HJOX.js";
+import "./chunk-JTST2Z7N.js";
+import "./chunk-IXI7RW3A.js";
+import "./chunk-TBMTA5LD.js";
+import "./chunk-T5WDTZCE.js";
+import "./chunk-DX4VFONH.js";
+import "./chunk-M2QOSF47.js";
+import "./chunk-UXIG7ALP.js";
+import "./chunk-Q7YXUH7M.js";
+import "./chunk-4O4Z52A2.js";
+import "./chunk-R2PFJKSP.js";
+import "./chunk-7JOAEKDV.js";
+import "./chunk-3SUO3TTE.js";
+import "./chunk-MLKGABMK.js";
+export {
+  NodeAddressResolver_exports as NodeAddressResolver,
+  NodeChildProcessSpawner_exports as NodeChildProcessSpawner,
+  NodeClusterHttp_exports as NodeClusterHttp,
+  NodeClusterSocket_exports as NodeClusterSocket,
+  NodeCrypto_exports as NodeCrypto,
+  NodeDatagramSocket_exports as NodeDatagramSocket,
+  NodeDns_exports as NodeDns,
+  NodeFileSystem_exports as NodeFileSystem,
+  NodeHttpClient_exports as NodeHttpClient,
+  NodeHttpIncomingMessage_exports as NodeHttpIncomingMessage,
+  NodeHttpPlatform_exports as NodeHttpPlatform,
+  NodeHttpServer_exports as NodeHttpServer,
+  NodeHttpServerRequest_exports as NodeHttpServerRequest,
+  NodeMultipart_exports as NodeMultipart,
+  NodeMultipartParser_exports as NodeMultipartParser,
+  NodePath_exports as NodePath,
+  NodeRedis_exports as NodeRedis,
+  NodeRuntime_exports as NodeRuntime,
+  NodeServices_exports as NodeServices,
+  NodeSink_exports as NodeSink,
+  NodeSocket_exports as NodeSocket,
+  NodeSocketServer_exports as NodeSocketServer,
+  NodeStdio_exports as NodeStdio,
+  NodeStream_exports as NodeStream,
+  NodeTerminal_exports as NodeTerminal,
+  NodeWorker_exports as NodeWorker,
+  NodeWorkerRunner_exports as NodeWorkerRunner
+};

package/docs/README.md

@@ -0,0 +1,135 @@
+---
+title: "@smthrs/platform-bun"
+description: "The Bun host bundle for Smithers: one Effect layer that fills the five services a program reaches the outside world through, with optional containment for the processes it spawns."
+---
+
+`@smthrs/platform-bun` is the Bun host bundle for Smithers, which runs long jobs
+as durable flows: each step is recorded, so a restart resumes what did not
+finish instead of starting over. `BunHost.layer` is a single Effect layer that
+fills the five services a program reaches the outside world through: the
+filesystem, path handling, child processes, version control, and HTTP.
+
+## What it solves
+
+A program that calls `node:fs`, `Bun.spawn`, or a global `fetch` directly cannot
+be permission checked, denied, audited, or replayed, because nothing sits
+between it and the runtime. Smithers closes the outside world behind five Effect
+service tags instead, and a host bundle is the object that fills them. This
+package is that object for a process running on Bun.
+
+Composing the same five slots by hand costs you two properties this bundle
+already has:
+
+- **A filesystem that survives a symlink race.** The filesystem slot carries
+  [`@smthrs/platform-node`](/api/platform-node)'s `AtomicFileSystem`, so under
+  [`@smthrs/kernel`](/api/kernel)'s guard an authorized path operation runs
+  against file descriptors and refuses to follow a link, rather than failing
+  closed. A symlink swapped in after authorization cannot redirect the write.
+- **An HTTP client that stops at a redirect.** The bundle configures Effect's
+  egress client without automatic redirects, so a `302`
+  comes back to you as a `302` and the second origin is never contacted. A
+  client that follows redirects on its own reaches a host nobody authorized.
+
+The bundle also runs on Node.js 26.4.0 or later. The raw child-process spawner
+is Effect's Node spawner re-exported; contained POSIX variants use
+`ProcessReaper.layerSpawner` and its prepared native adapter. See
+[Runtime parity with Node](./concepts/runtime-parity.md).
+
+## Install
+
+```bash
+bun add @smthrs/platform-bun@1.0.0-rc.13 effect
+```
+
+`effect` is a required peer at exactly `4.0.5`. `@effect/platform-bun` is
+bundled privately, built from `effect@4.0.5`. The filesystem slot runs the
+`smithers-jj-export` helper that the required peer `@smthrs/platform-node`
+ships. The `Jj` slot needs jj 0.39.0 or later, checked on its first operation;
+every bundle builds without jj. [Installation](./installation.md) covers all
+three and the import forms.
+
+## Run a command and a file operation through the host
+
+This program names Bun nowhere. It asks for two service tags, and the layer
+decides what fills them:
+
+```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")
+  return yield* spawner.string(ChildProcess.make("wc", ["-c", "report.txt"]))
+})
+
+Effect.runPromise(Effect.provide(program, BunHost.layer)).then(console.log)
+```
+
+Replace `BunHost.layer` with `NodeHost.layer` from
+[`@smthrs/platform-node`](/api/platform-node) and the program above does not
+change a character. That portability is what the five tags buy.
+
+Two variants change one slot each. `BunHost.layerAt(root)` binds version control
+to one absolute repository root instead of the process working directory, which
+a long-lived host wants because the working directory is ambient state anything
+can change. `BunHost.layerContained(options)` routes every spawn through a
+prepared supervisor with a `SIGTERM`-then-`SIGKILL` deadline. The owner is
+recorded before target activation; each pipeline leg has its own record. The
+handle's `pid` names the supervisor, and `exitCode` describes the target. A
+natural target exit still cleans up its owned group, and only verified cleanup
+retires the record. The durable ledger lets a later incarnation reconcile any
+retained records.
+
+## How this relates to @smthrs/flows
+
+[`@smthrs/flows`](/api/flows) is the durable flow engine: it records each step of
+a long job in a journal, so a restart replays what finished and resumes at what
+did not. Steps still have to read files and spawn processes, and this package is
+one of the three bundles that let them.
+
+`@smthrs/flows` re-exports no platform bundle on purpose, for the same reason
+`effect`'s own index does not re-export `@effect/platform-node`: a platform is
+chosen by the program that runs, not by the library it depends on. Its
+`NodeRuntime` helper builds a Node host for you, so a program that calls
+`NodeRuntime.layerHost` never imports a platform package. A program that runs on
+Bun composes this package instead and provides `BunHost.layer` itself.
+[`@smthrs/platform-node`](/api/platform-node) and
+[`@smthrs/platform-browser`](/api/platform-browser) are the sibling bundles that
+fill the same five slots on their own runtimes.
+
+Above both sits [`@smthrs/cli`](/api/cli), the `smithers` command that finds the
+flows in a project, plans them, runs them, and reads their events back. Install
+the CLI to run flows from a shell or a CI job, `@smthrs/flows` when the program
+that runs them is yours, and this package when that program runs on Bun.
+
+## Where to go next
+
+- [Installation](./installation.md): the install line, the peer dependencies,
+  the `smithers-jj-export` helper, the supported runtimes, and the import forms.
+- [Quickstart](./quickstart.md): the program above, run twice, the second time
+  with containment on and a child visible in the ledger.
+- [The Host surface on Bun](./concepts/host-surface.md): what each of the five
+  slots is, whose code fills it, and how to take one service without the other
+  four.
+- [Contain and reap child processes](./guides/contain-child-processes.md): the
+  escalation deadline, the ledger, and the sweep that kills what a crashed host
+  abandoned.
+- [Bind the host to a repository root](./guides/bind-a-repository-root.md):
+  `layerAt`, `layerContainedAt`, and the refusal they throw.
+- [API reference](./api.md): every export, with its signature.
+- [Troubleshooting](./troubleshooting.md): the failures these modules produce,
+  and what to change.
+
+The host exports `implementationIds` for its five service slots. Its rooted
+factories reject invalid roots before constructing a layer, using the host's
+own error with code `invalid_repository_root`.
+
+BunHost includes BunCrypto in every bundle, so ArtifactStore.put composes
+with BunHost alone. Crypto remains separate from the five capability slots.
+BunHost also re-exports ProcessReaper and HostLiveness from platform-node.

package/docs/api.md

@@ -0,0 +1,264 @@
+---
+title: "API reference"
+description: "Every export of @smthrs/platform-bun: the BunHost layers and their refusal, the containment options, the implementation identities, and the BunFileSystem escape hatch."
+---
+
+```ts
+import { BunHost } from "@smthrs/platform-bun"
+import * as Effect from "effect/Effect"
+import * as ChildProcess from "effect/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner"
+
+const program = Effect.gen(function*() {
+  const spawner = yield* ChildProcessSpawner
+  return yield* spawner.string(ChildProcess.make("printf", ["hello"]))
+}).pipe(Effect.provide(BunHost.layer))
+```
+
+This barrel and `BunHost` import `@effect/platform-bun` at module load. It
+and the Effect Node platform packages are bundled privately, built from
+`effect@4.0.5`. `effect` is a required peer at exactly `4.0.5`.
+
+:::warning
+This entry point is Node-only in the browser-bundle sense: it falls back to the
+`@effect/platform-node` adapters off Bun, so it resolves `node:fs` and the other
+`node:` built-ins. It runs on Bun and on Node. What it does not do is bundle for
+a browser; a page composes
+[`@smthrs/platform-browser`](/api/platform-browser) instead.
+:::
+
+Every host bundle builds without jj. The `Jj` slot requires jj 0.39.0 or newer
+and checks its executable on its first operation, which fails with `JjError`
+`not_installed` or `unsupported_version` when jj is missing or older. The
+contained bundles route that probe through their process spawner and retire its
+ledger entry when it exits. Probe results are cached per resolved absolute
+executable path and runner; contained spawners share a result only within the
+same spawner instance.
+
+## Entry points
+
+| Import                               | Source                                                                                                                             | Platform  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| `@smthrs/platform-bun`               | [src/index.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-bun/src/index.ts)                 | Bun, Node |
+| `@smthrs/platform-bun/BunHost`       | [src/BunHost.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-bun/src/BunHost.ts)             | Bun, Node |
+| `@smthrs/platform-bun/BunFileSystem` | [src/BunFileSystem.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-bun/src/BunFileSystem.ts) | Bun, Node |
+
+The root entry point exports exactly two names, `BunHost` and `BunFileSystem`,
+each the namespace of the module above. `@smthrs/platform-bun/internal/*` and
+`@smthrs/platform-bun/*/index` are blocked in the export map;
+`@smthrs/platform-bun/package.json` is exported.
+
+Supported runtimes are Bun >=1.4.0 and Node.js >=26.4.0.
+
+## BunHost
+
+The complete closed Host bundle: layers, root errors, models,
+implementation identities, and platform module re-exports.
+
+### Layers
+
+| Export             | Signature                                                                                                   |
+| ------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `layer`            | `Layer.Layer<BunHost \| Crypto.Crypto>`                                                                     |
+| `layerAt`          | `(root: string) => Layer.Layer<BunHost \| Crypto.Crypto>`                                                   |
+| `layerContained`   | `(options?: ContainedOptions) => Layer.Layer<BunHost \| Crypto.Crypto, never, ProcessLedger>`               |
+| `layerContainedAt` | `(root: string, options?: ContainedOptions) => Layer.Layer<BunHost \| Crypto.Crypto, never, ProcessLedger>` |
+| `layerHttpClient`  | `Layer.Layer<HttpClient>`                                                                                   |
+
+`layer` provides all five Host services, including the runtime-independent
+`Path`. `Jj` is bound to the process working directory.
+
+`layerAt` is `layer` with `Jj` bound to `root` instead. `root` must be an
+absolute path without NUL; see [BunHostError](#bunhosterror).
+
+`layerContained` is `layer` with process containment turned on: every child is
+spawned through `@smthrs/kernel`'s `ContainedSpawner` with
+`ProcessReaper.layerSpawner`, including its native adapter and
+`ProcessReaper.processLifecycle`. Each pipeline leg prepares a supervisor,
+records its identity, and then activates the target with a
+`SIGTERM`-then-`SIGKILL` deadline. The ledger retires a record only after
+verified cleanup, and `@smthrs/platform-node`'s `ProcessReaper` sweeps the records a
+crashed incarnation left behind while the layer is built. `Jj` is built over
+that same spawner (`BunJj.layerSpawner`), so a `jj` a dead host left running is
+a ledger record like any other. The `ProcessLedger` requirement is deliberate:
+only the program knows whether it has a durable one.
+
+On POSIX, `handle.pid` names the supervisor; `exitCode` and `isRunning`
+describe the target. Natural target exit still cleans up children in its owned
+group, including children holding output open. `detached: false` retains the
+supervisor but opts out of group cleanup, signalling only the target. Use the
+handle's `kill` rather than signalling its numeric pid yourself. Explicit
+stopping while a grouped target is alive attempts a best-effort ancestry sweep
+for escaped descendants; natural exit does not reclaim deliberately escaped
+sessions. Failed cleanup fails scope close and retains its record. Ordinary
+Bun runtimes are supported; compiled Bun applications are refused before
+activation because they cannot launch the runtime supervisor.
+
+`layerContainedAt` is `layerContained` with `Jj` bound to `root`
+(`BunJj.layerSpawnerAt`). It refuses a root exactly as `layerAt` does.
+
+`layerHttpClient` is the network slot every factory above installs, on its
+own: `EgressHttpClient.layer(process.env)` from `@smthrs/platform-node`. A `3xx`
+comes back with its `location` header intact and the second origin is never
+contacted. Following a redirect is `@smthrs/kernel`'s guarded
+`HttpClient.layer`, which rechecks the capability on every hop.
+
+### BunHostError
+
+```ts
+class BunHostError extends Schema.TaggedError<BunHostError>()("@smthrs/platform-bun/BunHostError", {
+  code: Schema.Literal("invalid_repository_root"),
+  message: Schema.String
+}) {
+  readonly name: "BunHostError"
+}
+
+type BunHostErrorCode = "invalid_repository_root"
+```
+
+The refusal `layerAt` and `layerContainedAt` throw when `root` is not absolute,
+the empty string included, or contains NUL. It is thrown rather than failed
+because a factory runs while a program composes its layers, where there is no
+fiber to fail into and a wrong root is a composition mistake, not a runtime
+outcome. The check runs when the factory is called, before any layer exists.
+
+It is this package's class rather than the `Jj` adapter's: a Bun caller
+composed `BunHost` and should learn nothing about the adapter behind the `Jj`
+slot from an error message. The message names the Bun factory that refused,
+never `NodeJj`, and repeats at most 64 code points of the root before reporting
+its true length, so a root taken from input cannot flood a log line. Branch on
+`code`; the message is for a person.
+
+### Models
+
+| Export              | Type                                                                                  | Meaning                                                        |
+| ------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `BunHost`           | `FileSystem \| Path \| ChildProcessSpawner \| Jj \| HttpClient \| ProcessConfinement` | The Host services and native confinement this bundle provides. |
+| `BunHostErrorCode`  | `"invalid_repository_root"`                                                           | The stable codes a factory refuses with.                       |
+| `ContainedOptions`  | `ProcessReaper.SpawnerOptions & ProcessReaper.Options`                                | What a caller may configure about containment.                 |
+| `implementationIds` | `Readonly<Record<HostServiceIds[number], string>>`                                    | The module behind each raw bundle Host slot.                   |
+
+All four factories supply the shared native
+[`ProcessConfinement.layer()`](/api/platform-node#processconfinement).
+Guarded commands use the same OS confinement on Node and Bun.
+
+`ContainedOptions` carries three fields:
+
+| Field      | Meaning                                                                                                               |
+| ---------- | --------------------------------------------------------------------------------------------------------------------- |
+| `graceMs`  | Milliseconds between the `SIGTERM` that asks a child to stop and the `SIGKILL` that makes it. Default 2000.           |
+| `ownerPid` | The pid the reaper must never signal a group for. Default `process.pid`.                                              |
+| `system`   | The operating-system seam the reaper reads liveness and start times through. Default: chosen from `process.platform`. |
+
+`platform` is deliberately not part of it. The factory uses the real
+`process.platform`, so the native process-group behavior and recorded identity
+agree. A caller cannot describe a Windows record for an owner that actually
+leads a POSIX group. For a smaller Bun composition, use
+`ProcessReaper.layerSpawner` with a ledger and an underlying runtime spawner.
+
+Each factory reads its options when it is called and splits them into the
+spawner half and the reaper half, so a field meant for one can never be read by
+the other and mutating the object afterwards changes neither layer.
+
+`implementationIds` names the raw bundle implementation behind each slot rather than the
+specifier you import it through, which is why the filesystem entry is
+`@smthrs/platform-node/AtomicFileSystem`. Contained factories replace the
+process runner with `ProcessReaper.layerSpawner`; this static table does not
+describe that substitution:
+
+```ts
+{
+  "effect/FileSystem": "@smthrs/platform-node/AtomicFileSystem",
+  "effect/Path": "@effect/platform-bun/BunPath",
+  "effect/process/ChildProcessSpawner": "@effect/platform-bun/BunChildProcessSpawner",
+  "@smthrs/jj/Jj": "@smthrs/jj/bun/BunJj",
+  "effect/HttpClient": "@smthrs/platform-node/EgressHttpClient"
+}
+```
+
+A key is the slot's stable identity in [`@smthrs/kernel`](/api/kernel)'s closed
+list, which is not always the specifier the tag is imported from: the spawner
+slot is `effect/process/ChildProcessSpawner` while its tag comes from
+`effect/process/ChildProcessSpawner`. The keys are written as literals
+rather than positions in that list, so reordering it cannot silently pair a slot
+with another slot's implementation. Nothing digests the record yet:
+[`@smthrs/plan`](/api/plan)'s step key carries a `layers` component these values
+are meant to feed, but no planner derives it from a host bundle today, so
+changing one invalidates no cached step.
+
+### Re-exports
+
+`BunHost` re-exports these modules so a program that should reach only part of
+the host has one place to take it from:
+
+| Export                   | What it is                                                                                                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AtomicFileSystem`       | `@smthrs/platform-node/AtomicFileSystem`, the filesystem implementation itself.                                                                                           |
+| `BunChildProcessSpawner` | `@effect/platform-bun/BunChildProcessSpawner`.                                                                                                                            |
+| `BunCrypto`              | `@effect/platform-bun/BunCrypto`, the [Effect Crypto service](https://github.com/Effect-TS/effect/blob/main/packages/platform/bun/src/BunCrypto.ts) layer.                |
+| `BunFileSystem`          | This package's `BunFileSystem` module.                                                                                                                                    |
+| `HostLiveness`           | `@smthrs/platform-node/HostLiveness`, the [host liveness probe](/api/platform-node#liveness-and-reaping).                                                                 |
+| `ProcessReaper`          | `@smthrs/platform-node/ProcessReaper`, the [contained spawner](/api/platform-node#processreaperlayerspawner) and [orphan sweep](/api/platform-node#liveness-and-reaping). |
+
+`AtomicFileSystem` is in the set for the same reason `NodeHost` re-exports it:
+it owns the only configuration escape hatch the filesystem slot has, and a Bun
+program whose helper is elsewhere must reach
+`AtomicFileSystem.layerWith` without adding
+[`@smthrs/platform-node`](/api/platform-node) as a second dependency.
+
+`BunJj` is deliberately absent. It belongs to [`@smthrs/jj`](/api/jj) and is
+imported from there, never re-exported here.
+
+`@effect/platform-bun/BunHttpClient` is deliberately absent too: its `layer`
+follows redirects to origins the capability kernel never authorized. Take the
+network slot on its own from `layerHttpClient`.
+
+## BunFileSystem
+
+The filesystem slot on its own.
+
+| Export      | Signature                                 | Meaning                                                                                        |
+| ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `layer`     | `Layer<FileSystem>`                       | The filesystem slot, carrying the kernel's atomic host extension. Is `AtomicFileSystem.layer`. |
+| `layerWith` | `(options: Options) => Layer<FileSystem>` | The same filesystem against an explicitly configured helper and byte limits.                   |
+| `Options`   | `AtomicFileSystem.Options`                | The helper, concurrency ceiling, timeout, and byte limits `layerWith` accepts.                 |
+
+`layer` is `@smthrs/platform-node`'s `AtomicFileSystem.layer`, the same value
+behind `NodeHost`'s filesystem slot, by identity and not by resemblance. It
+carries the kernel's atomic host extension, so under
+[@smthrs/kernel](/api/kernel)'s `FileSystem.layer` a guarded path operation runs
+descriptor-relative and no-follow instead of failing closed, and a symlink
+swapped in after authorization cannot redirect it.
+
+That extension executes its syscalls through the `smithers-jj-export` helper,
+a host prerequisite. Windows is unsupported.
+
+`layerWith` is the escape hatch for a host whose helper is outside the default
+search; `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` does the same without code. `BunHost` re-exports the
+same escape hatch as `AtomicFileSystem`, for parity with `NodeHost`.
+`executable` is re-validated per request, because the file it names can be
+replaced while the host runs; everything else is snapshotted when the layer is
+built.
+
+## Two services the bundle does not wrap
+
+There is no shell service, and no runtime detection either, because Bun's
+spawner _is_ the Node one. Running a command is Effect's `ChildProcess` and
+`ChildProcessSpawner`, and there is nothing for a detection branch to choose
+between.
+
+There is no HTTP service either. `BunHost` provides the shared `EgressHttpClient.layer(process.env)`, so the
+runtime never walks to a second origin behind the capability kernel's back.
+Following a redirect is [@smthrs/kernel](/api/kernel)'s guarded
+`HttpClient.layer`, which rechecks the capability on every hop.
+
+## Reading next
+
+[@smthrs/kernel](/api/kernel) owns the closed list and decorates these same tags
+with capability checks. [@smthrs/platform-node](/api/platform-node) and
+[@smthrs/platform-browser](/api/platform-browser) are the sibling bundles.
+[The Host surface on Bun](./concepts/host-surface.md) explains what each slot
+buys, [Runtime parity with Node](./concepts/runtime-parity.md) explains how far
+the two runtimes are interchangeable, and
+[Troubleshooting](./troubleshooting.md) lists the failures these exports
+produce.