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

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

@@ -0,0 +1,152 @@
+---
+title: "Configure the filesystem helper"
+description: "Point AtomicFileSystem at a smithers-jj-export helper and set the byte ceilings, process ceiling, and timeout that bound what one filesystem call may cost."
+---
+
+Use this when the host keeps the `smithers-jj-export` helper somewhere the
+adapter does not look, or when the default ceilings do not fit the workload.
+`AtomicFileSystem.layerWith` takes all of it in one options object.
+
+```ts
+import * as AtomicFileSystem from "@smthrs/platform-node/AtomicFileSystem"
+
+const filesystem = AtomicFileSystem.layerWith({
+  executable: "/opt/smithers/bin/smithers-jj-export",
+  concurrency: 4,
+  timeoutMs: 60_000,
+  limits: { content: 4 * 1024 * 1024 }
+})
+```
+
+`layerWith` returns a `Layer<FileSystem.FileSystem>` with no requirements, the
+same shape as `AtomicFileSystem.layer`. Substitute it wherever the bundle would
+have used the default.
+
+## Choose the helper
+
+The adapter runs `smithers-jj-export --atomic-fs` and uses the first of:
+
+1. `executable` from `layerWith`.
+2. `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`.
+3. The package's `bin/<platform>-<arch>/smithers-jj-export`.
+4. In a source checkout, `target/release/smithers-jj-export`, then
+   `target/debug/smithers-jj-export`.
+5. `/usr/local/bin/smithers-jj-export`.
+
+Build it in a source checkout:
+
+```sh
+cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
+```
+
+Or name an installed helper:
+
+```sh
+export SMITHERS_WORKSPACE_JJ_EXPORT_BINARY=/opt/smithers/bin/smithers-jj-export
+```
+
+A configured path must be absolute. The adapter never searches `PATH` or the
+working directory.
+
+The executable is re-validated on every request, as an absolute, executable
+regular file outside the confined workspace. The file a path names can be
+replaced while a host runs, so a check made only at construction would describe
+a file that is no longer there. A host with no helper builds cleanly and then
+fails every guarded filesystem call with `PermissionDenied`.
+
+The packaged helper and the source-checkout builds (steps 3 and 4) are copied
+to a private `0700` directory when the first layer in the process is built,
+before any flow runs. Later layer builds copy nothing, because a flow of an
+earlier run may already have written those paths. Requests execute that copy,
+so a flow that rewrites one of those files later changes nothing that runs. A
+default helper not present at that first build is refused with
+`PermissionDenied` when its path, or the file the path links to, lies inside the
+confined workspace: its bytes, or the choice of binary, could only have come
+from a flow.
+
+## Set the byte ceilings
+
+`limits` accepts a partial `Limits`; the fields you omit keep their defaults.
+
+| Field        | Default | What it bounds                                                                           |
+| ------------ | ------- | ---------------------------------------------------------------------------------------- |
+| `content`    | 16 MiB  | the bytes one `readFile` or `writeFile` may carry                                        |
+| `request`    | 24 MiB  | the framed request, refused before a helper is even started                              |
+| `response`   | 24 MiB  | the framed response, which is what a directory listing is charged against as it is built |
+| `stderr`     | 64 KiB  | the diagnostic text retained from a failing helper                                       |
+| `batchEntry` | 24 MiB  | one batch member's encoded result envelope, in UTF-8 JSON bytes                          |
+| `batchSize`  | 128     | the number of operations in one batch; inclusive, maximum 128                            |
+
+`request` and `response` are larger than `content` because base64 expands
+16 MiB to 22369624 bytes, which has to fit.
+
+A binary `writeFile` over the `content` ceiling never reaches the helper.
+The kernel checks the advertised limit before encoding anything and fails
+with a typed `BadArgument`; the helper's own ceiling is the backstop.
+
+`request` and `response` count UTF-8 JSON payload bytes; each frame also has a
+separately bounded header. A batch shares those same ceilings. `content`
+continues to apply separately to every file, including digest-only reads, so
+hashing in the helper does not bypass the existing read quota. `batchEntry`
+includes the member's success or failure envelope. If even a failure cannot fit,
+the whole call refuses. Aggregate response exhaustion likewise refuses the
+call instead of returning an incomplete result list.
+
+Every one of these is a contract rather than a tuning knob: without them a
+large file, a large directory tree, or a malfunctioning helper makes the host
+allocate until it dies. Raising one raises what a single call can cost the
+host.
+
+Lowering `response` has one consequence worth knowing. It bounds the rejection
+envelope too, so a ceiling small enough to cut one off degrades that
+operation's typed reason to the fail-closed one, and you lose the specific
+errno.
+
+## Set the process and time ceilings
+
+The two ceilings that decide whether the host survives a wide fan-out are not
+byte ceilings.
+
+| Field         | Default                     | What it bounds                                  |
+| ------------- | --------------------------- | ----------------------------------------------- |
+| `concurrency` | `os.availableParallelism()` | how many helpers may run at once                |
+| `timeoutMs`   | 300000                      | how long one helper may run before it is killed |
+
+Each ordinary call or bounded batch starts one helper, and three under the
+kernel's guarded filesystem, which resolves the path before and after its grant
+decision. Without a process ceiling,
+an `Effect.forEach(files, read, { concurrency: "unbounded" })` over fifty paths
+would start fifty helpers at once. The same permit covers request JSON
+serialization and framing, so queued calls retain their input rather than an
+additional encoded request buffer. Invalid settings and batch counts are
+rejected before admission; serialized request sizes are checked after admission
+and before starting the helper.
+
+`timeoutMs` is a backstop, not a latency budget. A read at the content ceiling
+over a slow disk has to fit under it, so five minutes is generous; what it
+bounds is a helper that will never answer at all. A helper that passes the
+deadline is killed and the operation fails closed.
+
+## Ceilings are read once
+
+Every field except `executable` is read once, when the layer value is
+constructed. `Options` is a plain object the caller still holds, and a byte
+ceiling that changes under a running host is not a ceiling.
+
+The reading happens outside the layer body, so two compositions of the same
+layer value enforce the same ceilings and share one process semaphore. Building
+the layer twice does not double the concurrency budget.
+
+## Check the defaults from code
+
+The defaults are exported, so a program that reports its own configuration does
+not have to restate them:
+
+```ts
+import * as AtomicFileSystem from "@smthrs/platform-node/AtomicFileSystem"
+
+AtomicFileSystem.defaultExecutable // "/usr/local/bin/smithers-jj-export"
+AtomicFileSystem.defaultLimits // { content, request, response, stderr, batchSize, batchEntry }
+AtomicFileSystem.defaultConcurrency // os.availableParallelism()
+AtomicFileSystem.defaultTimeoutMs // 300000
+```

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

@@ -0,0 +1,139 @@
+---
+title: "Contain child processes"
+description: "Compose NodeHost.layerContained with a process ledger so every spawned process gets a kill deadline and a durable record, and a crashed host's orphans are reaped at the next boot."
+---
+
+Use this when a host spawns long-running children and must not leave them
+behind if it dies. Under `NodeHost.layer` a child is signalled when its scope
+closes and then waited for, forever if it ignores `SIGTERM`, and a host killed
+outright abandons everything it started.
+
+## Choose a ledger
+
+`NodeHost.layerContained` requires a `ProcessLedger` and does not default one,
+because the durable half of containment is only as good as the journal
+underneath it. The choice belongs to the program that knows which it has.
+
+| Ledger                      | Inherits a crashed incarnation's processes | Requires  |
+| --------------------------- | ------------------------------------------ | --------- |
+| `ProcessLedger.layer`       | yes                                        | `Journal` |
+| `ProcessLedger.layerMemory` | no                                         | nothing   |
+
+`layerMemory` still supplies the live supervisor lifecycle and kill deadline.
+It simply inherits nothing, so the sweep always finds an empty orphan set.
+
+Both take the same options: `hostId`, the durable identity two incarnations
+share, and `ownerPid`, the process id of this one.
+
+## Compose the host
+
+```ts
+import * as ProcessLedger from "@smthrs/kernel/ProcessLedger"
+import { NodeHost } from "@smthrs/platform-node"
+import * as Layer from "effect/Layer"
+
+const host = NodeHost.layerContained({ graceMs: 2000 }).pipe(
+  Layer.provide(ProcessLedger.layerMemory({ hostId: "engine-1", ownerPid: process.pid }))
+)
+```
+
+`host` is a `Layer<NodeHost, JjError>`: the same five services `NodeHost.layer` hands
+out, spawning through the contained spawner. Swap `layerMemory` for
+`ProcessLedger.layer` to get the durable ledger, and provide a `Journal` from
+[`@smthrs/journal`](/api/journal) underneath it.
+
+To pin the repository root as well, use `layerContainedAt`:
+
+```ts
+const rooted = NodeHost.layerContainedAt("/absolute/repository", { graceMs: 2000 }).pipe(
+  Layer.provide(ProcessLedger.layerMemory({ hostId: "engine-1", ownerPid: process.pid }))
+)
+```
+
+## What building the layer does
+
+Two things happen while the layer is built, in this order:
+
+1. `ProcessReaper.reap` sweeps the records a previous incarnation of the same
+   `hostId` left behind, killing the process groups it is willing to signal.
+2. The contained services are handed to everything downstream.
+
+So standing a host up is also what cleans up after the incarnation that
+crashed. `jj` runs through that same spawner, so a `jj` invocation a crashed
+host left running is a ledger record like any other.
+
+Every spawn prepares a supervisor, commits its identity, and then activates
+the target. Each pipeline leg is recorded. On POSIX the handle's `pid` names
+the owner while `exitCode` describes the target. A natural target exit also
+cleans up its owned group; use the handle's `kill`, never an external signal
+to its numeric pid. Failed or unverified cleanup fails close and retains the
+record.
+
+A smaller host composition can use `ProcessReaper.layerSpawner` with a ledger
+and an underlying runtime spawner. This factory includes the native adapter
+whose pipe listeners remain alive through cancellation. Custom platform
+authors can pass a lifecycle to `ContainedSpawner.layer` directly. Compose
+the permission decorator above containment so it checks the original command
+before preparation.
+
+## Set the options
+
+`NodeHost.ContainedOptions` has three fields, all optional:
+
+| Field      | Default                          | What it does                                                                                                                    |
+| ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `graceMs`  | 2000                             | most milliseconds between the `SIGTERM` that asks a child to stop and the `SIGKILL` that makes it; an emptied group ends sooner |
+| `ownerPid` | `process.pid`                    | the pid the sweep must never signal, nor signal the group of                                                                    |
+| `system`   | selected from `process.platform` | the operating-system seam the sweep asks its questions through                                                                  |
+
+A command that already names its own `killSignal` or `forceKillAfter` keeps
+them: a caller who set one thought about it.
+
+`ContainedSpawner.Options.platform` is deliberately not among these. The
+platform factory reads the real `process.platform`, so process-group behavior
+and the recorded identity agree. A caller cannot describe a Windows record
+for an owner that actually leads a POSIX group.
+
+## Read what the sweep decided
+
+`layerContained` runs the sweep and discards its report. To log the decisions,
+call `ProcessReaper.reap` yourself:
+
+```ts
+import * as ProcessLedger from "@smthrs/kernel/ProcessLedger"
+import * as ProcessReaper from "@smthrs/platform-node/ProcessReaper"
+import * as Effect from "effect/Effect"
+
+const sweep = Effect.gen(function*() {
+  const decided = yield* ProcessReaper.reap()
+  for (const entry of decided) {
+    yield* Effect.log(
+      entry.killed
+        ? `killed ${entry.record.pid}`
+        : `kept ${entry.record.pid}: ${entry.refusal}`
+    )
+  }
+}).pipe(Effect.provide(ProcessLedger.layerMemory({ hostId: "engine-1", ownerPid: process.pid })))
+```
+
+Each entry carries the record, whether it was killed, and, when it was not, the
+`Refusal` that says why. `Reaped` is a union discriminated by `killed`, so the
+check in the branch above is what makes `entry.refusal` readable. Four refusals leave the record for a later
+incarnation to try again: `owner-alive`, `identity-unverified`,
+`own-group-unknown`, and `kill-failed`. The rest are final. See
+[Process containment](../concepts/process-containment.md) for what each one
+means and why the split falls where it does.
+
+## Verify it
+
+Use a UUID-marked fixture that installs its signal handler before reporting
+readiness. Check both cancellation and natural target exit, including a child
+that inherits stdout, and require a stopped heartbeat plus an exited process
+identity. A target exit code alone is insufficient evidence.
+
+For host-loss behavior, kill only the fixture host and verify the private
+supervisor stops its owned group without requiring a new host. A subsequent
+host with the same `hostId` and durable journal reconciles retained records.
+Read any refusal instead of treating a skipped signal as a successful reap.
+The [process containment](../concepts/process-containment.md) page describes
+`detached: false`, deliberately escaped sessions, and unsupported hosts.

package/docs/guides/match-files-with-glob.md

@@ -0,0 +1,151 @@
+---
+title: "Match files with a glob pattern"
+description: "The glob grammar AtomicFileSystem implements, how exclusions prune the walk, the patterns it refuses outright, and the three answers where it deliberately differs from Node's globber."
+---
+
+Use this when a program needs to select files under the workspace. `glob` is
+one of the fifteen operations the atomic adapter implements, so it costs one
+helper process for the whole tree rather than one per entry.
+
+```ts
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+
+const sources = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  return yield* fs.glob("**/*.ts", {
+    root: "/absolute/workspace",
+    exclude: ["**/node_modules/**", "**/*.test.ts"]
+  })
+})
+```
+
+The helper cannot call Node's globber, so it implements the grammar itself.
+That has three consequences you need to know: what the grammar supports, what
+it refuses, and where it deliberately answers differently.
+
+## The grammar
+
+| Construct      | Meaning                                         |
+| -------------- | ----------------------------------------------- |
+| `*`            | any run of characters within one segment        |
+| `?`            | any one character within one segment            |
+| `[abc]`        | a character class, with `!` or `^` for negation |
+| `**`           | zero or more whole segments                     |
+| `{a,b}`        | alternation                                     |
+| a trailing `/` | directory-only matching                         |
+
+The dotfile rule keeps a wildcard out of a name beginning with `.`, while a
+segment that spells the dot matches one: `*` misses `.git`, and `.*` or `[.]*`
+finds it.
+
+A one-member class is the literal it spells, so `[.]` is a `.` path segment.
+The globber drops a spelled `.` before it parses and collapses `[.]` only
+afterwards, so this one survives, and as the last segment it names its own
+anchor. A `**` immediately before it addresses nothing, so `**/[.]` names
+nothing while `**/deep/[.]` names the directory. Anywhere but last, and in an
+exclusion, a `.` segment names an entry no directory holds.
+
+A trailing `**` spans zero segments, so it also names its own anchor: a
+directory always, and a non-directory only when every segment before it is
+literal. `top.txt/**` names the file; `t*.txt/**` names nothing. Adjacent `**`
+segments act as one: `deep/**/**` includes `deep`, `.hidden/**/**` includes
+`.hidden`, and `**/**/**` includes the root. Repeating `**` still excludes
+hidden descendants unless another segment explicitly names their leading dot.
+
+Matching is segment-wise and linear in the candidate's length, never a compiled
+regular expression, because a pattern of repeated `*x` fragments costs a regex
+engine exponential backtracking.
+
+## Exclusions prune the walk
+
+An exclusion is not a filter applied to the results. Excluding a directory
+excludes everything below it, and nothing under an excluded directory is
+listed, counted against the 100000-entry ceiling, or charged against the
+response ceiling. An exclusion that names the root stops the walk before it
+begins.
+
+An absolute exclude is rewritten against the glob root, so it applies to the
+same names the selecting pattern does.
+
+The selecting pattern prunes the same walk. A directory is entered only when a
+remaining pattern segment, or an open `**`, can still name something below it,
+so `src/index.ts` or `*.ts` never reads the subtrees beside its match, and a
+name the pattern does not select is never charged against the response
+ceiling. Names in a directory the walk does read still count against the
+100000-entry ceiling, because reading them was work. Literal segments are found
+by reading their parent rather than by a direct lookup: matching is
+case-sensitive on every host, and a lookup on a case-insensitive filesystem
+would answer for a name the pattern did not spell.
+
+## Patterns the adapter refuses
+
+Five inputs fail as a typed `BadArgument` before filesystem walking. The byte
+limit is checked before brace expansion, which stops at its alternative limit.
+Each expanded alternative is checked for unsupported syntax before compilation,
+so refused patterns cost no directory listing:
+
+| Input                                             | Why                               |
+| ------------------------------------------------- | --------------------------------- |
+| a pattern longer than 4096 UTF-8 bytes            | a bound on what one call may cost |
+| braces expanding past 64 alternatives             | brace expansion is multiplicative |
+| extglob, such as `+(a\|b)`                        | not implemented                   |
+| `[:` inside an open class, such as `[a[:digit:]]` | not implemented                   |
+| brace bodies containing `..`, including `{1..3}`  | not implemented                   |
+
+The last three checks conservatively refuse unsupported syntax, including
+unrecognized class names and non-range brace sets containing `..`. Treating an
+unsupported construct as literal text could make an exclusion return the paths
+it was meant to remove. The refusal covers the
+exclude list as well as the pattern, and it reads a character class as a class,
+so `[!(]*` is an ordinary negated class and not an extglob.
+
+Backslashes follow Node's POSIX rules: an absolute selector and every exclude
+drop them while leaving following wildcard magic active, and a relative
+selector containing one matches nothing.
+
+## Three answers pinned against Node
+
+Every other row of the grammar is asserted against `@effect/platform-node`'s
+own globber in a parity suite. Three answers are pinned instead, because the
+native globber gives no single answer to copy.
+
+**Case is always sensitive.** Node's globber passes
+`nocase: isMacOS || isWindows` with `nocaseMagicOnly: true`. On a
+case-insensitive host that means a magic segment folds case (`*.TXT` finds
+`upper.txt`), a literal segment the matcher decides is compared exactly
+(`**/MID.txt` misses `mid.txt`), and a literal segment Node addresses directly
+comes back with the pattern's own spelling (`TOP.TXT` returns `TOP.TXT`) even
+though the directory does not hold that spelling. This adapter returns only
+names its walk found, and keeps one rule on every host. A pattern whose meaning
+depends on which machine reads it is worse than one that means the same
+everywhere, and worst of all in an exclusion.
+
+**A globstar exclusion leaves the directory entry.** A trailing `**` in an
+exclusion removes what is under a directory and leaves the directory entry
+itself. Node's answer here depends on the shape of the selecting pattern:
+`**/*` with `exclude: ["nested/**"]` keeps `nested`, and `**` with the same
+exclusion drops it. This adapter gives one answer for every selector.
+Consequently the directory-only `**/` names directories below its own anchor
+but not that anchor: with `exclude: ["**/"]`, `**` keeps the root and its files
+while pruning every directory. Node empties the answer instead.
+
+**A dotted segment after a globstar matches dotfiles, but a globstar never
+spans a hidden directory.** Node 22 matched nothing for `**/.hidden`; Node 24
+and later match the dotfiles. This adapter matches the dotfiles on every
+version. Node 24 and later also walk into a hidden directory when the segment
+after `**` matches it, so with `.hidden/.secret` and `.hidden/.nested/.wanted`
+present, `**/.*` returns `.hidden`, `.hidden/.secret`, `.hidden/.nested` and
+`.hidden/.nested/.wanted`, and `**/.*/**` returns `.hidden` and
+`.hidden/.nested`. This adapter returns `.hidden` alone for both, because only a
+segment that names a hidden directory may enter it: `.hidden/.*` returns
+`.hidden/.nested` and `.hidden/.secret`.
+
+## Keep the cost down
+
+One `glob` is one fork, so prefer a single pattern with an `exclude` list to
+several calls you merge yourself. Prune with exclusions rather than filtering
+results: an excluded subtree is never walked at all, which is the difference
+between a cheap call and one that reads a `node_modules` tree before discarding
+it. A narrow selector is cheap on its own: `src/**/*.ts` enters `src` and
+nothing beside it.

package/docs/installation.md

@@ -0,0 +1,204 @@
+---
+title: "Installation"
+description: "Install @smthrs/platform-node, the peers and host prerequisites it needs, its entry points, and the packages a real host composition adds."
+sidebar:
+  order: 1
+---
+
+## Get the package
+
+`@smthrs/platform-node` is not on npm at 1.0.0-rc.0. It ships as a member of
+the [smithers repository](https://github.com/smithersai/smithers) workspace, so
+using it today means working from a checkout:
+
+```bash
+git clone https://github.com/smithersai/smithers.git
+cd smithers
+pnpm install
+```
+
+Code that consumes it lives in that workspace too, either an existing package
+or one you add, and depends on it with a workspace specifier:
+
+```json
+{
+  "dependencies": {
+    "@smthrs/platform-node": "workspace:*"
+  }
+}
+```
+
+## Peers
+
+`@effect/platform-node`, `@effect/platform-node-shared`, and `effect` are peer
+dependencies, so your project pins their versions rather than inheriting a
+second copy. `@smthrs/platform-node` declares `4.0.0-rc.115` for all three:
+
+```bash
+pnpm add @effect/platform-node@4.0.0-rc.115 @effect/platform-node-shared@4.0.0-rc.115 effect@4.0.0-rc.115
+```
+
+The shared adapter peer keeps the Node implementation on the same Effect
+release candidate. The upstream Node adapter uses a caret for that dependency,
+which otherwise permits a later shared adapter with an incompatible Effect peer.
+Package managers that install peers automatically resolve the exact version
+from this package's manifest.
+
+Its own runtime dependencies, [`@smthrs/jj`](/api/jj) and
+[`@smthrs/kernel`](/api/kernel), resolve from the same workspace.
+
+The package ships ESM, CommonJS, and TypeScript declarations.
+
+## Host requirements
+
+| Requirement                     | Why it is needed                                                      |
+| ------------------------------- | --------------------------------------------------------------------- |
+| Node.js 26.4.0 or later         | the minimum this package's `engines` field declares                   |
+| a POSIX host                    | Windows has none of the primitives below and is unsupported           |
+| the `smithers-jj-export` helper | `AtomicFileSystem` runs every guarded filesystem operation through it |
+| `jj` 0.39.0 or newer on `PATH`  | required at construction by every complete `NodeHost` layer           |
+
+### jj is checked at construction
+
+Every complete host bundle, `NodeHost.layer`, `NodeHost.layerAt`,
+`NodeHost.layerContained`, and `NodeHost.layerContainedAt`, builds a
+version-checked `Jj` layer before providing its services. This requires jj
+0.39.0 or newer even when the program requests only the filesystem or process
+spawner. Check the installed version with `jj --version`.
+
+If the executable is missing, bundle construction fails with a typed `JjError`
+whose code is `not_installed`. An older version fails with
+`unsupported_version`. The version probe runs outside the host process ledger;
+repository commands use the selected process runner.
+
+### The filesystem helper
+
+From a source checkout, build it with:
+
+```sh
+cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
+```
+
+The host finds `target/release/smithers-jj-export` automatically. Elsewhere,
+set `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` to its absolute path.
+
+`NodeHost.layer` builds cleanly on a host with no helper. The executable is
+re-validated on every request rather than once at construction, because the
+file a path names can be replaced while a host runs, and a check that happened
+only at boot would be a check about a file that is no longer there.
+
+The consequence is that on `node:22-slim`, `node:22-alpine`, or a distroless
+image the layer builds, the run starts, and the first guarded filesystem call
+inside a flow body fails with `PermissionDenied`. For the search order and
+`layerWith`, see
+[Configure the filesystem helper](./guides/configure-the-filesystem-helper.md).
+
+## Individual services without jj
+
+Applications that do not need `Jj` can provide individual service layers.
+This composition supplies the bundle's filesystem, path, process spawner, and
+HTTP client without constructing a `Jj` layer:
+
+```ts
+import { NodeHost } from "@smthrs/platform-node"
+import * as Layer from "effect/Layer"
+import * as Path from "effect/Path"
+
+const platform = Layer.mergeAll(NodeHost.AtomicFileSystem.layer, Path.layer)
+const spawner = NodeHost.NodeChildProcessSpawner.layer.pipe(Layer.provide(platform))
+const http = NodeHost.EgressHttpClient.layer(process.env)
+const hostWithoutJj = Layer.mergeAll(platform, spawner, http)
+```
+
+`NodeHost.EgressHttpClient.layer(process.env)` is the HTTP client the complete
+bundles above use. It routes through the proxy `HTTP_PROXY`, `HTTPS_PROXY` and
+`NO_PROXY` name, and is the plain Undici pool when they name none.
+`NodeHost.NodeHttpClient.layerUndici` is that plain pool on its own: it dials
+every origin directly and ignores the proxy variables, so it bypasses an
+egress proxy allowlist. Compose it only when direct egress is intended.
+
+Provide `hostWithoutJj` to a program that needs these services, or provide only
+the individual layer it needs. The spawner requires both filesystem and path
+services, supplied by `platform` above. The filesystem still requires the
+helper described above. This composition does not provide `Jj`
+and cannot satisfy consumers that require the complete five-tag host.
+
+## Import forms
+
+The root entry point re-exports three modules as namespaces:
+
+```ts
+import { HostLiveness, NodeHost, ProcessReaper, ScopedProcess } from "@smthrs/platform-node"
+```
+
+Each module is also importable from its own subpath, which is the form the
+[API reference](./api.md) uses:
+
+```ts
+import * as HostLiveness from "@smthrs/platform-node/HostLiveness"
+import * as NodeHost from "@smthrs/platform-node/NodeHost"
+import * as ProcessReaper from "@smthrs/platform-node/ProcessReaper"
+```
+
+`AtomicFileSystem` is deliberately not in the barrel. Reach it through its own
+subpath, or as a re-export off `NodeHost`:
+
+```ts
+import * as AtomicFileSystem from "@smthrs/platform-node/AtomicFileSystem"
+// or
+import { NodeHost } from "@smthrs/platform-node"
+const filesystem = NodeHost.AtomicFileSystem.layer
+```
+
+Two subpath shapes are blocked in the export map:
+`@smthrs/platform-node/internal/*` and `@smthrs/platform-node/*/index`.
+`@smthrs/platform-node/package.json` is exported.
+
+## Entry points
+
+| Import                                   | Source                                                                                                                                    |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `@smthrs/platform-node`                  | [src/index.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/index.ts)                       |
+| `@smthrs/platform-node/NodeHost`         | [src/NodeHost.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/NodeHost.ts)                 |
+| `@smthrs/platform-node/AtomicFileSystem` | [src/AtomicFileSystem.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/AtomicFileSystem.ts) |
+| `@smthrs/platform-node/HostLiveness`     | [src/HostLiveness.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/HostLiveness.ts)         |
+| `@smthrs/platform-node/ProcessReaper`    | [src/ProcessReaper.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/ProcessReaper.ts)       |
+| `@smthrs/platform-node/ScopedProcess`    | [src/ScopedProcess.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/platform-node/src/ScopedProcess.ts)       |
+
+Every entry point is Node-only by construction: the bundle resolves
+`node:child_process` and its siblings, and a build check keeps it that way. For a
+browser host, use [`@smthrs/platform-browser`](/api/platform-browser); for Bun,
+[`@smthrs/platform-bun`](/api/platform-bun).
+
+## What a real composition adds
+
+This package provides raw host services. A composition that enforces
+capabilities wraps them in [`@smthrs/kernel`](/api/kernel)'s decorators, which
+need a workspace root and a grant store. Add that package to your own
+dependencies with the same workspace specifier, then compose:
+
+```ts
+import * as GrantStore from "@smthrs/kernel/GrantStore"
+import * as HostServices from "@smthrs/kernel/HostServices"
+import * as Workspace from "@smthrs/kernel/Workspace"
+import { NodeHost } from "@smthrs/platform-node"
+import * as Layer from "effect/Layer"
+
+const guarded = HostServices.layer.pipe(
+  Layer.provide(NodeHost.layer),
+  Layer.provide(Workspace.layer("/absolute/workspace")),
+  Layer.provide(GrantStore.layerNoop)
+)
+```
+
+`GrantStore.layerNoop` allows every operation inside the workspace. It is a
+seam for tests and boot paths, not a production policy. Replace it with a
+rule-based store before running untrusted work; see
+[Write a capability policy](https://kernel.smithers.sh/guides/write-a-capability-policy/).
+
+Turning on process containment adds a `ProcessLedger`, which the journal backs.
+See [Contain child processes](./guides/contain-child-processes.md).
+
+Most programs never compose this by hand. `@smthrs/flows`' `NodeRuntime` builds
+the whole durable runtime, including `NodeHost.layerContainedAt` and
+`HostLiveness.isAlive`, from one options object.