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

package/docs/concepts/host-surface.md

@@ -0,0 +1,152 @@
+---
+title: "The Host surface on Bun"
+description: "The five service slots a Smithers program reaches the world through, what fills each one on Bun, why the bundle adds no shell and no HTTP wrapper, and how to take one service without the other four."
+sidebar:
+  order: 1
+---
+
+Smithers programs do not call `node:fs`, `Bun.spawn`, or a global `fetch`.
+Everything that touches the outside world enters through a closed list of five
+Effect service tags, and a host bundle is the thing that fills them:
+
+| Slot            | Tag                                           |
+| --------------- | --------------------------------------------- |
+| Filesystem      | `effect/FileSystem`                           |
+| Path            | `effect/Path`                                 |
+| Child processes | `effect/unstable/process/ChildProcessSpawner` |
+| Version control | `Jj`, from [`@smthrs/jj`](/api/jj)            |
+| Network         | `effect/unstable/http/HttpClient`             |
+
+The list is closed for one reason, owned by
+[`@smthrs/kernel`](/api/kernel): a service that is not on it cannot be
+attenuated, denied, or audited, so it must not exist.
+
+Closing the list does not make the platform implementations part of a step's
+identity. [`@smthrs/plan`](/api/plan)'s step key digests only the `layers` its
+caller passes it, so "which platform implementations were in scope" is an
+explicit input a caller supplies, not something this bundle contributes. The
+identity table below is data to pass; nothing reads it for you.
+
+`BunHost.layer` provides all five, and `BunHost` is the type union of them:
+
+```ts
+export type BunHost = FileSystem | Path.Path | ChildProcessSpawner | Jj | HttpClient
+```
+
+## What fills each slot, and whose code it is
+
+`BunHost.implementationIds` is this mapping as data, so a swapped
+implementation is a visible change to a public value rather than a comment
+that drifted:
+
+```ts
+import { BunHost } from "@smthrs/platform-bun"
+
+BunHost.implementationIds
+// {
+//   "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"
+// }
+```
+
+Each value names the module actually behind the slot, not the specifier you
+import it through. The filesystem entry says
+`@smthrs/platform-node/AtomicFileSystem` because that is the implementation,
+even though a Bun program reaches it through this package. Each key is the
+slot's stable identity in the closed list, which is likewise not always the
+specifier the tag comes from: the spawner key is
+`effect/process/ChildProcessSpawner` while its tag is imported from
+`effect/unstable/process/ChildProcessSpawner`.
+
+Nothing digests these values today. [`@smthrs/plan`](/api/plan)'s step key
+carries a `layers` component they are meant to feed, but no planner derives it
+from a host bundle yet, so changing one invalidates no cached step.
+
+## Three slots the bundle does not implement
+
+**Path** is runtime independent. `effect/Path`'s own layer goes in the slot
+unchanged, and the kernel keeps `Path` on the closed list as an explicit
+pass-through decision rather than dropping it.
+
+**Child processes** are Effect's. `@effect/platform-bun`'s
+`BunChildProcessSpawner` is `@effect/platform-node-shared`'s spawner
+re-exported, which means Bun and Node run literally the same module. There is
+no Bun shell wrapper here and no runtime detection, because there is nothing
+to choose between. See
+[Runtime parity with Node](./runtime-parity.md) for what that means for your
+program, and where the parity stops.
+
+**The network** is Effect's `HttpClient`. There is no Smithers transport port
+beneath it, because a raw port would be a second way to reach the network
+whose contract never mentions permission. The bundle provides
+`@smthrs/platform-node`'s egress client, with hostname-based proxy routing
+and connection pinning for web tools.
+
+## Redirects and connection pinning
+
+```ts
+const layerHttpClient: Layer.Layer<HttpClient> = EgressHttpClient.layer(process.env)
+```
+
+A `302` therefore comes back to the caller as a `302`, with its `location`
+header intact and the second origin never contacted. That is deliberate: a
+client that follows a redirect on its own reaches a host the capability kernel
+never authorized. Following a redirect is the kernel's guarded
+`HttpClient.layer`, which rechecks the capability on every hop.
+
+## Two slots the bundle composes from Smithers packages
+
+**Version control** is `Jj`, the service whose methods make a step reversible:
+snapshot, restore, diff, workspace lanes. It runs the `jj` command from
+[Jujutsu](https://jj-vcs.github.io), a version-control system that works on a
+Git repository, so the slot needs that binary on the host. Bun's adapter is
+`@smthrs/jj/bun/BunJj`, which is the Node adapter under another name because
+Bun implements the child-process API it uses. The adapter is imported from
+[`@smthrs/jj`](/api/jj) and deliberately not re-exported here: it belongs to
+that package.
+
+**The filesystem** is `@smthrs/platform-node`'s `AtomicFileSystem`, byte for
+byte the layer [`@smthrs/platform-node`](/api/platform-node) puts in its own
+filesystem slot. It carries the kernel's atomic host extension, which is what
+lets the kernel's guarded `FileSystem.layer` perform a guarded path operation
+descriptor-relative and no-follow instead of failing closed. With the
+extension, the operation runs against file descriptors, so a symlink swapped in
+after authorization cannot redirect it somewhere else. Without a working one,
+every guarded path operation is refused with a typed `PermissionDenied` rather
+than falling back to a path-based call, because the fallback is the race the
+extension exists to prevent.
+
+That extension executes its syscalls in a `smithers-jj-export` subprocess
+rather than in-process, which is why the host needs that helper. See
+[Configure the filesystem helper](../guides/configure-the-filesystem-helper.md).
+
+## Taking one service without the other four
+
+`BunHost` re-exports the single-slot modules, so a program that should
+reach only part of the host has one import to take it from:
+
+```ts
+import { BunHost } from "@smthrs/platform-bun"
+
+BunHost.AtomicFileSystem // the filesystem implementation, with its options
+BunHost.BunFileSystem // the filesystem slot as this package spells it
+BunHost.BunChildProcessSpawner
+BunHost.layerHttpClient // the network slot, redirects stopped
+```
+
+`@effect/platform-bun/BunHttpClient` is not re-exported: its `layer` follows
+redirects, which is the escape the section above closes.
+
+`AtomicFileSystem` is in that set for a specific reason: it owns the only
+configuration escape hatch the filesystem slot has, and a Bun program whose
+helper is elsewhere must be able to reach
+`AtomicFileSystem.layerWith` without adding
+[`@smthrs/platform-node`](/api/platform-node) as a second dependency.
+
+Composing individual slots yourself means you own the closure. `BunHost.layer`
+is the only thing that guarantees all five are present and consistent; a
+hand-composed subset is a surface the kernel can still guard, but not one this
+package pins.

package/docs/concepts/runtime-parity.md

@@ -0,0 +1,80 @@
+---
+title: "Runtime parity with Node"
+description: "Which adapters Bun and Node share, how contained hosts prepare a runtime supervisor, and which runtime and platform boundaries still need separate verification."
+sidebar:
+  order: 2
+---
+
+The Bun bundle shares its host adapters with Node. A flow asks for the same
+service tags on either runtime. Shared source does not make every runtime or
+operating-system behavior identical, especially around native process pipes
+and cleanup.
+
+## Bun and Node run the same modules here
+
+Three of the raw bundle's five slots use shared implementations:
+
+- `@effect/platform-bun/BunChildProcessSpawner` is
+  `@effect/platform-node-shared`'s spawner re-exported. Spawning a child is one
+  module, so there is nothing for a detection branch to choose between.
+- `@smthrs/jj/bun/BunJj` is `@smthrs/jj/node/NodeJj` re-exported, because Bun
+  implements the child-process API the argv-safe jj adapter uses. The two share
+  the same error classification and the same interruption finalizer by
+  construction, not by agreement.
+- The filesystem slot is `@smthrs/platform-node`'s `AtomicFileSystem.layer`
+  itself, the same value [`@smthrs/platform-node`](/api/platform-node) puts in
+  its own slot.
+
+`effect/Path` is runtime independent, and the network slot is the shared Undici egress client, including the same
+connection-pinning and proxy policy on both runtimes.
+
+Contained POSIX variants substitute `ProcessReaper.layerSpawner`. It combines
+the shared native process adapter with a supervisor started by the current
+Node or Bun runtime. Preparation records the supervisor before executing the
+target. Compiled Bun executables and Node single-executable applications are
+refused before activation because they do not supply the runtime eval entry
+point. Windows retains the raw runtime spawner and remains unsupported best
+effort for containment.
+
+## Two consequences you can rely on
+
+**The bundle runs unchanged under Node.** Nothing in it requires the Bun
+runtime, so a program composed on `BunHost.layer` executes on Node 26.4.0 or later as well. That is not a compatibility shim; it is what "the same modules"
+means. The package declares both floors in `engines`.
+
+**Recorded durable behavior does not require a Bun-specific flow.** The same
+service contracts and error adapters are available on Node. Replay still
+depends on the flow's recorded inputs and implementations; shared source alone
+does not prove that a new native command has identical behavior on both hosts.
+
+## Node-only in the browser-bundle sense
+
+The same property that makes the bundle portable between Bun and Node is what
+stops it reaching a browser. Falling back to the `@effect/platform-node`
+adapters means resolving `node:` built-ins, so a browser bundler asked to
+resolve `@smthrs/platform-bun` stops at `node:fs`. That is the intended
+resolution, not a packaging defect to work around with an alias.
+
+It runs on Bun and it runs on Node. What it does not do is bundle for a page.
+That is [`@smthrs/platform-browser`](/api/platform-browser), which fills the
+same five slots from browser primitives.
+
+## Where the parity stops
+
+The package's `test` target runs conformance under Node with V8 coverage.
+The `bunTest` target imports Vitest's JavaScript entry under Bun and asserts
+`process.versions.bun` inside every worker. Both lanes exercise redirects,
+process containment, and filesystem helpers. Node coverage reports use private
+`0700` directories under the package's gitignored `coverage/` directory and are
+removed when the runner exits. Bun coverage is disabled.
+
+Verify process streams, cancellation, and cleanup on the runtime and operating
+system you deploy. The contained handle's POSIX
+`pid` identifies its supervisor; target status and supported cleanup boundaries
+are described in [Contain and reap child processes](../guides/contain-child-processes.md).
+
+The filesystem is the exception worth holding on to. Its no-follow extension
+does not run in-process: it executes each guarded operation in a
+`smithers-jj-export` subprocess, so the slot depends on that helper rather than
+on anything either runtime ships. See
+[Configure the filesystem helper](../guides/configure-the-filesystem-helper.md).

package/docs/guides/bind-a-repository-root.md

@@ -0,0 +1,109 @@
+---
+title: "Bind the host to a repository root"
+description: "Use BunHost.layerAt and BunHost.layerContainedAt so the Jj slot runs against one absolute repository root instead of the process working directory, and handle the refusal they throw."
+---
+
+`BunHost.layer` binds the `Jj` slot to the process working directory. That is
+the right default for a command-line tool a person runs inside a repository,
+and the wrong one for a long-lived host: the working directory is ambient
+state that some other part of the program can change, and a host that inherits
+it commits version-control operations against whichever repository happened to
+be current.
+
+`BunHost.layerAt` binds the slot to one root you name.
+
+## Bind the root
+
+```ts
+import { Jj } from "@smthrs/jj"
+import { BunHost } from "@smthrs/platform-bun"
+import * as Effect from "effect/Effect"
+
+const program = Effect.gen(function*() {
+  const jj = yield* Jj
+  return yield* jj.status()
+})
+
+Effect.runPromise(
+  Effect.scoped(Effect.provide(program, BunHost.layerAt("/srv/repositories/app")))
+)
+```
+
+The other four slots are identical to `BunHost.layer`. Only `Jj` changes: it
+is built with `BunJj.layerAt(root)` instead of `BunJj.layer`.
+
+`BunHost.layerContainedAt` is the same substitution on the contained bundle.
+Use it whenever you want both properties, which is the usual case for a
+supervisor:
+
+```ts
+BunHost.layerContainedAt("/srv/repositories/app", { graceMs: 2_000 })
+```
+
+## Pass an absolute root
+
+Both factories require an absolute path. A relative root, and the empty string,
+are refused:
+
+```ts
+BunHost.layerAt("repositories/app")
+// throws BunHostError: BunHost.layerAt requires an absolute repository root,
+// got "repositories/app"
+```
+
+Three properties of that refusal matter when you handle it.
+
+**It throws rather than fails.** A factory is called while your program
+composes its layers, where there is no fiber to fail into. A wrong root is a
+composition mistake, not a runtime outcome, so it surfaces where the mistake
+was written, before any layer exists.
+
+**It is this package's error, not the adapter's.** The `Jj` adapter underneath
+would also refuse, with a bare `TypeError` that names `NodeJj.layerAt`, carries
+no code, and echoes the whole string. You composed `BunHost`, so you get
+`BunHost.BunHostError`, whose message names the Bun factory that refused and
+mentions no adapter.
+
+**Branch on `code`, never on the message.** The message is for a person and its
+wording is not a contract:
+
+```ts
+import { BunHost } from "@smthrs/platform-bun"
+
+try {
+  return BunHost.layerAt(configuredRoot)
+} catch (error) {
+  if (error instanceof BunHost.BunHostError && error.code === "invalid_repository_root") {
+    throw new Error(`SMITHERS_REPOSITORY_ROOT must be an absolute path, got ${configuredRoot}`)
+  }
+  throw error
+}
+```
+
+`BunHost.BunHostErrorCode` is the union of codes a factory refuses with; today
+`"invalid_repository_root"` is the only member.
+
+## Roots that come from input
+
+A root read from an environment variable, a request, or a configuration file is
+untrusted text, and it lands in a log line the moment it is refused. The whole
+message stays under 256 UTF-16 code units for a root of any content and any
+length, so a hostile root cannot flood the line. A root is quoted in full when
+it is 64 code points or fewer and its quoted form fits that bound. Otherwise
+it is cut: the message carries a quoted excerpt of at most 64 code points,
+then `... (N characters)` with the root's true length in code points.
+
+The excerpt is passed through `JSON.stringify`, so a newline in the root
+cannot break the line it lands on. Escaping widens some characters: a control
+character becomes a six-character `\u0001`, so a root made of them is cut
+well before 64 code points. The cut is counted in code points rather than
+UTF-16 units and lands between escapes, so it never splits a surrogate pair
+or an escape, and the excerpt is always one valid JSON string.
+
+## Related
+
+- [Contain and reap child processes](./contain-child-processes.md): what
+  `layerContainedAt` adds on top of the root binding, including why `jj` runs
+  through the contained spawner.
+- [`@smthrs/jj`](/api/jj): the `Jj` contract itself, its failure codes, and
+  choosing which `jj` binary runs.

package/docs/guides/configure-the-filesystem-helper.md

@@ -0,0 +1,109 @@
+---
+title: "Configure the filesystem helper"
+description: "Point the filesystem slot at a smithers-jj-export helper with BunFileSystem.layerWith, and tune the helper's concurrency, timeout, and byte limits."
+---
+
+The filesystem slot carries the kernel's atomic host extension, and that
+extension does not run in-process. Each guarded path operation is executed by
+the `smithers-jj-export` helper the adapter spawns, which is what makes the
+operation descriptor-relative and no-follow: a symlink swapped in after
+authorization cannot redirect it somewhere else.
+
+The adapter uses the first of `executable`, `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`,
+the package's `bin/<platform>-<arch>/smithers-jj-export`, a source checkout's
+`target/release` or `target/debug` build, and
+`/usr/local/bin/smithers-jj-export`. It never searches `PATH`.
+
+## Build or name the helper
+
+In a source checkout:
+
+```bash
+cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
+```
+
+Anywhere else, set the absolute path:
+
+```bash
+export SMITHERS_WORKSPACE_JJ_EXPORT_BINARY=/opt/smithers/bin/smithers-jj-export
+```
+
+Or pass it to the layer:
+
+```ts
+import { BunFileSystem } from "@smthrs/platform-bun"
+
+const fileSystem = BunFileSystem.layerWith({ executable: "/opt/smithers/bin/smithers-jj-export" })
+```
+
+The executable is re-validated on every request rather than read once when the
+layer is built, because the file a path names can be replaced while the host
+runs.
+
+## Use it as the whole host's filesystem slot
+
+`BunHost.layer` builds its filesystem slot from `BunFileSystem.layer`, which
+uses the default search. Merge your configured layer over the bundle so it
+shadows that slot, and put it last: for a duplicate tag, the later layer in a
+merge wins.
+
+```ts
+import { BunFileSystem, BunHost } from "@smthrs/platform-bun"
+import * as Layer from "effect/Layer"
+
+// The override comes second. Reversing the arguments silently keeps the
+// default helper.
+const host = Layer.merge(
+  BunHost.layer,
+  BunFileSystem.layerWith({ executable: "/opt/smithers/bin/smithers-jj-export" })
+)
+```
+
+This replaces the `FileSystem` tag every consumer resolves, including the
+kernel's guarded `FileSystem.layer`, which is where the helper actually runs.
+The spawner inside the bundle keeps the default filesystem layer it was built
+with for resolving executables and working directories; that path is unguarded
+and does not use the helper.
+
+Prefer this over hand-composing the five slots. Rebuilding them yourself means
+rebuilding the `HttpClient` slot too, and its `redirect: "manual"` wiring is
+internal, so a hand-composed bundle quietly gains redirect following.
+
+`BunHost` also re-exports `AtomicFileSystem` itself, so you can reach the
+implementation and its full option set without adding
+[`@smthrs/platform-node`](/api/platform-node) as a second dependency:
+
+```ts
+BunHost.AtomicFileSystem.layerWith({ executable, concurrency, timeoutMs })
+```
+
+## The other options
+
+`BunFileSystem.Options` is `AtomicFileSystem.Options`:
+
+| Field         | Meaning                                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------------------- |
+| `executable`  | The absolute `smithers-jj-export` path. Default: the search above. Re-validated per request.              |
+| `concurrency` | How many helper processes may run at once. A contract, not a tuning knob: every operation is one process. |
+| `timeoutMs`   | How long one helper may run before it is killed and the operation fails closed.                           |
+| `limits`      | The byte ceilings the helper enforces on the values it moves.                                             |
+
+`concurrency` exists because an unbounded `Effect.forEach` over a directory
+would start one helper per entry and pin every core. Raise it deliberately.
+
+Everything except `executable` is snapshotted when the layer is built. The
+options object stays yours, and a byte ceiling that changed under a running
+host would not be a ceiling.
+
+## Windows
+
+The extension is unsupported on Windows. A guarded path operation there fails
+closed.
+
+## Related
+
+- [The Host surface on Bun](../concepts/host-surface.md): why the filesystem
+  slot is the Node package's implementation, and what the extension buys under
+  the kernel's guard.
+- [`@smthrs/platform-node`](/api/platform-node): the `AtomicFileSystem` adapter
+  itself, its full option set, and its refusal matrix.

package/docs/guides/contain-child-processes.md

@@ -0,0 +1,176 @@
+---
+title: "Contain and reap child processes"
+description: "Compose BunHost.layerContained with a ProcessLedger so each command has a supervised process group, a cleanup deadline, and a durable identity for restart reconciliation."
+---
+
+`BunHost.layer` provides the raw process service. A scope finalizer can signal
+its target, but a target that exits first can leave descendants holding output
+open. A crashed host runs no finalizers at all.
+
+`BunHost.layerContained` combines a live process owner with a ledger for
+cleanup that a later host must reconcile.
+
+## What containment adds
+
+**A live owner and deadline.** Every pipeline leg gets a prepared POSIX
+supervisor. Its lifetime is independent of the native target, so cleanup can
+stop the owned group even after the target exits. The default policy is
+`SIGTERM`, then `SIGKILL` after `graceMs`; an explicit `killSignal` or
+`forceKillAfter` is preserved. A private connection also initiates cleanup
+when the host disappears.
+
+**A durable record before execution.** The kernel records the prepared
+supervisor's identity and the executable it runs before activation starts the
+target. The record carries the owner pid and group, host identity, host
+incarnation pid, and start time. Only verified cleanup retires it; failed or
+unverified cleanup fails scope release and retains the record.
+
+`commandDigest` names the program and never its arguments, because a
+journal-backed ledger keeps every record permanently and arguments carry
+credentials: `curl -u user:pass`, `mysql -phunter2`, `deploy --token hunter2`.
+Nothing that reads a record needs more, since the reaper matches on pid and
+process group. Keep credentials out of argv anyway, in the environment or on
+stdin: while a child runs, its arguments are readable through `ps`.
+
+**A sweep on the way up.** While the layer is built,
+[`@smthrs/platform-node`](/api/platform-node)'s `ProcessReaper` reads the
+records a previous incarnation of the same `hostId` left behind and signals the
+groups they name after checking their identities. The lifecycle and reaper
+live in the Node package and support ordinary Node and Bun runtimes.
+
+On POSIX, a returned handle's `pid` identifies the supervisor; `exitCode` and
+`isRunning` describe the target. Signal through `handle.kill`, not either
+numeric pid. `detached: false` retains a supervisor but opts out of group
+cleanup, signalling only the target. Explicit stopping while a grouped target
+is still alive also attempts a revalidated positive-PID sweep of escaped
+descendants. That extra sweep is best effort; natural exit does not promise
+cleanup of deliberately escaped sessions. Windows remains unsupported best
+effort. Node single-executable applications and compiled Bun executables are
+refused before activation because the supervisor needs a runtime eval entry
+point.
+
+## Compose it
+
+The ledger is a layer requirement rather than a built-in default, because only
+your program knows whether it has a durable one:
+
+```ts
+import * as ProcessLedger from "@smthrs/kernel/ProcessLedger"
+import { BunHost } from "@smthrs/platform-bun"
+import * as Layer from "effect/Layer"
+
+const host = BunHost.layerContainedAt("/srv/repositories/app", {
+  graceMs: 2_000,
+  ownerPid: process.pid
+}).pipe(
+  Layer.provide(ProcessLedger.layerMemory({ hostId: "worker-a", ownerPid: process.pid }))
+)
+```
+
+`ProcessLedger.layerMemory` records nothing durably. A host built on it still
+contains the process groups it owns, including when the host connection closes,
+but it inherits nothing from a previous incarnation, so the reaper has nothing
+to sweep. Use it in tests and in short-lived programs.
+
+`ProcessLedger.layer` writes through a [`@smthrs/journal`](/api/journal)
+`Journal`, which is what makes the durable half real. Give two incarnations the
+same `hostId` and the second inherits the first's unreleased records.
+
+## The options both contained factories take
+
+`BunHost.ContainedOptions` is the containment configuration plus the reaper's:
+
+| Field      | Meaning                                                                                                               |
+| ---------- | --------------------------------------------------------------------------------------------------------------------- |
+| `graceMs`  | Milliseconds between the `SIGTERM` that asks a child to stop and the `SIGKILL` that makes it. Default 2000.           |
+| `ownerPid` | The pid this host must never signal a group for, so it cannot kill itself. Default `process.pid`.                     |
+| `system`   | The operating-system seam the reaper reads liveness and start times through. Default: chosen from `process.platform`. |
+
+Each factory reads the options when you call it, not when the layer is built,
+and splits them into the two halves so a field meant for one can never be read
+by the other. Mutating the object you passed afterwards changes neither layer.
+
+## Why there is no `platform` option
+
+`ContainedSpawner.Options` has a `platform` field. `ContainedOptions` omits it,
+deliberately.
+
+The contained factories use `ProcessReaper.layerSpawner`, which reads the real
+`process.platform`. The native process-group behavior and recorded identity
+must agree: a caller cannot describe a Windows record for an owner that
+actually leads a POSIX group. Casting `platform: "win32"` past the type does
+not override the running platform.
+
+For a smaller Bun composition, use `ProcessReaper.layerSpawner` with a ledger
+and an underlying runtime spawner. It includes the prepared native adapter
+whose pipe error listeners remain alive through cancellation. Keep the kernel
+permission decorator above it to authorize the caller's command before
+preparation.
+
+## `jj` is contained too
+
+Under `BunHost.layer`, the `Jj` slot spawns the jj CLI through
+`node:child_process` directly. A jj child therefore leads no group the host
+recorded, appears in no ledger, and outlives the host that ran it.
+
+`layerContained` and `layerContainedAt` build `Jj` over the contained spawner
+(`BunJj.layerSpawner` and `BunJj.layerSpawnerAt`) rather than around it, so a
+`jj` invocation is a ledger record like any other child:
+
+```ts
+import { Jj } from "@smthrs/jj"
+import * as Effect from "effect/Effect"
+
+// The ledger records the jj executable while status runs, and retires it when the
+// invocation and its cleanup finish.
+const status = Effect.flatMap(Jj, (jj) => jj.status()).pipe(
+  Effect.provide(host),
+  Effect.scoped
+)
+```
+
+That is the observable difference: the same call under `BunHost.layer` leaves
+the ledger empty. The initial `jj --version` probe uses the selected runner
+too, so a contained host records and retires it before exposing `Jj`. Probe
+results are cached per resolved absolute executable path and runner, with a
+separate cache for each spawner instance.
+
+Every aggregate host waits up to 5000 ms for the startup probe, then interrupts
+it and awaits process cleanup. The typed `JjError` has `method: "version"`,
+`code: "unknown"`, `cause.code: "ETIMEDOUT"`, and the executable path in its
+command and message. Cleanup can add the contained spawner's shutdown grace
+period to the startup budget. Raw hosts close the probe's pipes and kill its
+direct child; they do not add a ledger entry.
+
+Override the budget per host layer through the shared Node and Bun adapter:
+
+```ts
+import * as NodeJj from "@smthrs/jj/node/NodeJj"
+
+const boundedHost = host.pipe(
+  Layer.provide(Layer.succeed(NodeJj.StartupTimeoutMs)(1_500))
+)
+```
+
+The budget is a positive, finite number of milliseconds, at most 2147483647.
+Timeout and interruption allow a later construction to retry the probe.
+
+## What the reaper refuses to kill
+
+A record is not a licence to signal. `ProcessReaper.reap` re-checks each
+inherited record and declines when the numbers do not clearly name an
+abandoned process: the owning incarnation is still alive, the record names this
+host's own group, 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 host could
+not ask the question at all.
+
+Four refusals leave the record inherited rather than retiring it:
+`owner-alive`, `identity-unverified`, `own-group-unknown`, and `kill-failed`. A host that
+could not ask, or that has no business signalling, must not be the one that
+closes the question. A later incarnation that can ask gets the chance.
+
+## Related
+
+- [Bind the host to a repository root](./bind-a-repository-root.md): what
+  `layerContainedAt` adds beyond containment, and the refusal it throws.
+- [Quickstart](../quickstart.md): a runnable version of the composition above.