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

package/src/EgressHttpClient.ts

@@ -0,0 +1,327 @@
+/**
+ * The outbound HTTP client a Node process should use, read off its environment.
+ *
+ * `@effect/platform-node` ships `NodeHttpClient.layerUndici`, and its
+ * dispatcher is a bare Undici `Agent`. A bare `Agent` dials every origin
+ * directly: it does not read `HTTP_PROXY`, `HTTPS_PROXY` or `NO_PROXY`, and
+ * nothing at the call site says so. That is invisible on a developer machine
+ * with open egress and fatal inside a sandbox whose egress is default-deny
+ * behind a named proxy — the request leaves for the origin, the firewall drops
+ * it, and the only symptom is a transport failure far from the composition
+ * that chose the client.
+ *
+ * This module is the one place that decision is made. {@link layer} is the
+ * client every Node host composition installs; it honours the proxy the
+ * environment names. Requests without a web destination use a shared pool;
+ * web requests receive a fresh pinned dispatcher.
+ *
+ * The rule for loopback is fixed here, not by the environment: `localhost`,
+ * `127.0.0.1` and `[::1]` are always reached directly, even when the
+ * environment names a proxy and no exclusion, and every other origin follows
+ * `NO_PROXY`. A proxy is how a process leaves its machine, and
+ * `--remote http://127.0.0.1:3000` is not leaving it. The exemption is those
+ * three names and nothing wider: Undici matches `NO_PROXY` entries by name,
+ * never by resolved address, so `127.0.0.2` or a hostname that resolves to
+ * loopback is an origin like any other and goes through the proxy.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
+import type * as Undici from "@effect/platform-node/Undici"
+import { GrantStore } from "@smthrs/kernel/GrantStore"
+import * as KernelHttpClient from "@smthrs/kernel/HttpClient"
+import { Destination, withDestinationPinning } from "@smthrs/kernel/HttpClient"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import * as Scope from "effect/Scope"
+import * as Semaphore from "effect/Semaphore"
+import { HttpClient } from "effect/unstable/http/HttpClient"
+import * as EffectHttpClient from "effect/unstable/http/HttpClient"
+import * as HttpClientError from "effect/unstable/http/HttpClientError"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import { isIP } from "node:net"
+
+/**
+ * A pinned connection asked for an address family none of the authorized
+ * addresses has. It is the `cause` of the `TransportError` the request fails
+ * with; `code` is always `no_approved_address`.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class EgressAddressError extends Schema.TaggedError<EgressAddressError>()(
+  "@smthrs/platform-node/EgressAddressError",
+  { code: Schema.Literal("no_approved_address"), message: Schema.String }
+) {
+  override readonly name = "EgressAddressError"
+}
+
+/**
+ * The hosts a proxy is never for. A proxy is how a process leaves its machine;
+ * these names are the machine itself. Matched by name, the way Undici matches
+ * every `NO_PROXY` entry, so the list is exactly these three and not
+ * `127.0.0.0/8`.
+ */
+const loopback = ["localhost", "127.0.0.1", "::1"] as const
+
+/**
+ * The exclusion list to hand Undici, given the one the environment names.
+ *
+ * Undici proxies *every* origin when `NO_PROXY` is empty — `#shouldProxy`
+ * returns early with "Always proxy if NO_PROXY is not set or empty" — so a host
+ * that names a proxy to reach the internet would also send `smthrs --remote
+ * http://127.0.0.1:3000` and a local Ollama at `http://localhost:11434` to it.
+ * Nothing in this repository has ever needed `NO_PROXY=127.0.0.1`, because the
+ * client these compositions used before ignored the proxy variables outright.
+ * So loopback is always excluded, the way Go's `net/http.ProxyFromEnvironment`
+ * excludes it, and the environment's own entries are kept beside it.
+ *
+ * `*` is returned untouched: Undici recognises the wildcard only as the entire
+ * value, and it already means every origin is direct.
+ */
+const exclusions = (declared: string): string =>
+  declared === "*" ? declared : [declared, ...loopback].filter((entry) => entry !== "").join(",")
+
+// Split ESM bundles expose CommonJS Undici through default, without synthetic
+// named exports. Node and Bun also expose its constructors through default.
+// Its typings declare `default` as a namespace without them, and `bundler`
+// resolution reads that, so the value is typed as the module it carries.
+const loadUndici = Effect.promise(
+  async () => (await import("undici/index.js")).default as unknown as typeof Undici
+)
+
+/**
+ * An Undici dispatcher that routes through the egress proxy the supplied
+ * environment names, or a direct one when it names none.
+ *
+ * The proxy variables are read in the order Undici itself reads them,
+ * lowercase first, and passed explicitly rather than left to
+ * `EnvHttpProxyAgent`'s own ambient lookup: a host serving a guest's
+ * environment is not the guest, and the pool has to follow the record it was
+ * handed. Loopback is always direct; see {@link exclusions}. Each dispatcher is
+ * acquired in the caller's scope and destroyed with it, so a composition that
+ * builds several still owns every pool it opened.
+ *
+ * @param environment the environment record whose proxy variables decide the route
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const dispatcher = (
+  environment: Readonly<Record<string, string | undefined>>
+): Effect.Effect<Undici.Dispatcher, never, Scope.Scope> =>
+  Effect.suspend(() => {
+    const httpProxy = environment.http_proxy ?? environment.HTTP_PROXY ?? ""
+    const httpsProxy = environment.https_proxy ?? environment.HTTPS_PROXY ?? ""
+    const noProxy = exclusions(environment.no_proxy ?? environment.NO_PROXY ?? "")
+    // Explicit empty values prevent Undici from falling back to a different
+    // ambient environment. Each replacement pool uses the same proxy policy.
+    //
+    // Undici is loaded here rather than imported at the top, the way
+    // `NodeHttpClient.makeDispatcher` loads it, because this module is imported
+    // by `NodeHost` and every bundle built on it. A static import pulls the
+    // whole of Undici into any process that merely composes a host, whose
+    // side effects a host bundle must not carry: it reddened the Node host's
+    // own `FileSystem` contract case, which never makes a request. The explicit
+    // package entry also avoids Bun's incomplete built-in "undici" substitute.
+    return Effect.acquireRelease(
+      Effect.map(
+        loadUndici,
+        (undici) => new undici.EnvHttpProxyAgent({ httpProxy, httpsProxy, noProxy })
+      ),
+      (dispatcher) => Effect.promise(() => dispatcher.destroy())
+    )
+  })
+
+/**
+ * The Undici `HttpClient` to install, given the environment the process runs in.
+ *
+ * Use this wherever `NodeHttpClient.layerUndici` would otherwise be provided
+ * under a layer that takes `HttpClient` from context — a model transport, a
+ * judge, a fetch rule, a host bundle. The two differ only in whether the pool
+ * honours `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`, which is the difference
+ * between a request that reaches the gateway from inside a default-deny
+ * sandbox and one the firewall drops.
+ *
+ * @param environment the environment record whose proxy variables decide the route
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer = (
+  environment: Readonly<Record<string, string | undefined>>
+): Layer.Layer<HttpClient> =>
+  Layer.effect(
+    HttpClient,
+    Effect.gen(function*() {
+      const shared = yield* dispatcher(environment)
+      const ordinary = yield* NodeHttpClient.makeUndici.pipe(Effect.provideService(NodeHttpClient.Dispatcher, shared))
+      return withDestinationPinning(EffectHttpClient.transform(ordinary, (execute, request) =>
+        Effect.gen(function*() {
+          const destination = yield* Destination
+          if (destination === undefined) return yield* execute
+          const url = new URL(request.url)
+          if (
+            url.origin !== destination.origin || destination.addresses.length === 0 ||
+            destination.addresses.some((address) => isIP(address) === 0)
+          ) {
+            return yield* Effect.fail(
+              new HttpClientError.HttpClientError({
+                reason: new HttpClientError.TransportError({
+                  request,
+                  description: "Invalid pinned HTTP destination"
+                })
+              })
+            )
+          }
+          const proxies = [
+            environment.http_proxy ?? environment.HTTP_PROXY,
+            environment.https_proxy ?? environment.HTTPS_PROXY
+          ]
+          // The record is read per request, and a live one such as NodeHost's
+          // `process.env` can name an unparsable proxy after the shared pool
+          // was built from it; that is a refusal here, never a thrown URL error.
+          const validProxies = proxies.every((proxy) => {
+            if (!proxy) return true
+            try {
+              return ["http:", "https:"].includes(new URL(proxy).protocol)
+            } catch {
+              return false
+            }
+          })
+          if (!validProxies) {
+            return yield* Effect.fail(
+              new HttpClientError.HttpClientError({
+                reason: new HttpClientError.TransportError({
+                  request,
+                  description: "Pinned HTTP requests require HTTP or HTTPS proxies"
+                })
+              })
+            )
+          }
+          const undici = yield* loadUndici
+          const addresses = destination.addresses.map((address) => ({ address, family: isIP(address) }))
+          // Construction and its disposal are one uninterruptible step: an
+          // interruption that lands after the agent exists but before the request
+          // owns it would otherwise leave the agent neither destroyed nor closed.
+          return yield* Effect.uninterruptibleMask((restore) => {
+            const pinned = new undici.EnvHttpProxyAgent({
+              httpProxy: environment.http_proxy ?? environment.HTTP_PROXY ?? "",
+              httpsProxy: environment.https_proxy ?? environment.HTTPS_PROXY ?? "",
+              noProxy: exclusions(environment.no_proxy ?? environment.NO_PROXY ?? ""),
+              // Tunnelling HTTP too prevents the proxy resolving the target hostname.
+              proxyTunnel: true,
+              connect: {
+                lookup: (_hostname, options, callback) => {
+                  const candidates = options.family
+                    ? addresses.filter((item) => item.family === options.family)
+                    : addresses
+                  const first = candidates[0]
+                  if (first === undefined) {
+                    return callback(
+                      new EgressAddressError({
+                        code: "no_approved_address",
+                        message: "No approved address for family"
+                      }),
+                      "",
+                      4
+                    )
+                  }
+                  if (options.all) callback(null, candidates)
+                  else callback(null, first.address, first.family)
+                }
+              },
+              clientFactory: (origin, options) => {
+                const proxy = new undici.Pool(origin, options)
+                const connect = proxy.connect.bind(proxy)
+                // EnvHttpProxyAgent selects the route using the ORIGINAL hostname.
+                // Only the proxy tunnel destination changes; endpoint TLS still uses
+                // the original hostname for SNI and certificate verification.
+                proxy.connect = (options: Undici.Dispatcher.ConnectOptions) => {
+                  const address = addresses[0]!.address
+                  const host = isIP(address) === 6 ? `[${address}]` : address
+                  const authority = `${host}:${url.port || (url.protocol === "https:" ? "443" : "80")}`
+                  return connect({ ...options, path: authority, headers: { ...options.headers, host: authority } })
+                }
+                return proxy
+              }
+            })
+            const pinnedRequest = request.pipe(
+              HttpClientRequest.setHeader("host", url.host),
+              HttpClientRequest.removeHeader("proxy-authorization"),
+              HttpClientRequest.removeHeader("connection"),
+              HttpClientRequest.removeHeader("transfer-encoding"),
+              HttpClientRequest.removeHeader("content-length")
+            )
+            return restore(NodeHttpClient.makeUndici.pipe(
+              Effect.provideService(NodeHttpClient.Dispatcher, pinned),
+              Effect.flatMap((client) => client.execute(pinnedRequest))
+            )).pipe(Effect.onExit((exit) =>
+              Exit.isFailure(exit)
+                ? Effect.promise(() => pinned.destroy())
+                // close prevents reuse immediately, but lets the active body drain.
+                : Effect.sync(() => {
+                  void pinned.close().catch(() => pinned.destroy())
+                })
+            ))
+          })
+        })))
+    })
+  )
+
+/**
+ * Owns one replaceable Undici pool in the caller's scope. Each replacement
+ * receives the same middleware and closes the previous pool.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const rebuildableTransport = (
+  acquire: Effect.Effect<Undici.Dispatcher, never, Scope.Scope>,
+  decorate: (client: HttpClient) => Effect.Effect<HttpClient> = Effect.succeed
+): Effect.Effect<
+  {
+    readonly client: HttpClient
+    readonly rebuild: Effect.Effect<HttpClient>
+  },
+  never,
+  Scope.Scope
+> =>
+  Effect.gen(function*() {
+    const scope = yield* Scope.Scope
+    const gate = yield* Semaphore.make(1)
+    let held: Scope.Closeable | undefined = undefined
+    const rebuild = gate.withPermit(Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function*() {
+        const owned = yield* Scope.fork(scope)
+        const client = yield* restore(NodeHttpClient.makeUndici.pipe(
+          Effect.provideServiceEffect(NodeHttpClient.Dispatcher, acquire),
+          Effect.flatMap(decorate),
+          Effect.provideService(Scope.Scope, owned)
+        )).pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : Scope.close(owned, exit)))
+        const previous = held
+        held = owned
+        if (previous !== undefined) yield* Scope.close(previous, Exit.void)
+        return client
+      })
+    ))
+    return { client: yield* rebuild, rebuild }
+  })
+
+/**
+ * A model transport whose replacements retain the caller's grant store and
+ * environment proxy policy. Pass it to RequestExecutor.makeWith in the host scope.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const guardedTransport = (environment: Readonly<Record<string, string | undefined>>) =>
+  Effect.gen(function*() {
+    const grants = yield* GrantStore
+    return yield* rebuildableTransport(dispatcher(environment), (client) =>
+      HttpClient.pipe(Effect.provide(KernelHttpClient.layer.pipe(
+        Layer.provide(Layer.succeed(HttpClient)(client)),
+        Layer.provide(Layer.succeed(GrantStore)(grants))
+      ))))
+  })

package/src/HostLiveness.ts

@@ -0,0 +1,103 @@
+/**
+ * Answers whether a recorded run owner is still alive on this host.
+ *
+ * @since 0.1.0
+ */
+
+import * as Effect from "effect/Effect"
+
+/**
+ * The owner identity fields liveness is decided from.
+ *
+ * Structural on purpose: `@smthrs/journal`'s `OwnerId` is exactly this shape
+ * plus a nonce, so an `OwnerId` is accepted here without this package taking a
+ * dependency on the journal to name a type.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Owner {
+  /** The host the owner ran on. */
+  readonly hostId: string
+  /** The operating-system process id that held the run. */
+  readonly pid: number
+}
+
+/**
+ * Liveness configuration.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+  /** The host id this process answers for. */
+  readonly hostId: string
+  /**
+   * How the probe asks the operating system. Default `process.kill`, which
+   * delivers nothing for signal 0 and only reports whether the pid is
+   * signalable.
+   */
+  readonly signal?: ((pid: number, signal: 0) => void) | undefined
+}
+
+const signalable = (send: (pid: number, signal: 0) => void, pid: number): boolean => {
+  try {
+    send(pid, 0)
+    return true
+  } catch (cause) {
+    // ESRCH means the process is gone. EPERM means it exists and belongs to
+    // another user, which is still a live owner this host must not rob. A throw
+    // that is not an object at all carries no code, and reading through it
+    // rather than off it is what stops that crashing the probe: a thrown string
+    // or `null` is an answer nobody gave, which is a live owner.
+    return (cause as { readonly code?: string } | null | undefined)?.code !== "ESRCH"
+  }
+}
+
+/**
+ * Builds the liveness probe `EngineStore` consults before it steals a run.
+ *
+ * The engine asks this before taking a run whose recorded owner it is not, so
+ * a wrong `true` strands a run and a wrong `false` runs it twice. The rule is
+ * therefore asymmetric on purpose:
+ *
+ * - An owner from a **different host** is alive. A pid means nothing across
+ *   machines, and the process table this probe reads is only this machine's.
+ * - An owner from **this host** is dead only when the signal-0 probe reports
+ *   `ESRCH`. Every other result preserves liveness.
+ *
+ * The residual risk is pid reuse. An owner whose pid was recycled by an
+ * unrelated program reads as alive and its run waits for an operator, which is
+ * the safe direction: nothing about a recycled pid can tell this process
+ * whether the run is still being driven, and the cost of guessing wrong the
+ * other way is two hosts executing one run.
+ *
+ * A multi-process deployment with a supervisor or a lease system knows better
+ * than any pid probe and should answer from that instead.
+ *
+ * `@smthrs/run-store`'s `Ownership.sameHostPidProbe` fills the same
+ * `LivenessCheck`. Both probes use the same `ESRCH`-only death rule.
+ * `EPERM`, `EINVAL`, and unknown signal errors preserve liveness.
+ *
+ * The cross-host policy differs. `sameHostPidProbe` compares the owner's
+ * `hostId` with `context.claimant.hostId` and returns `false` for a foreign
+ * host, leaving the expired lease to govern reclaiming the run. This probe
+ * compares with the configured `hostId` and returns `true` for a foreign
+ * host, so a permanently dead foreign host's runs wait for an operator.
+ *
+ * Which answer a deployment gets depends on the entry point it used:
+ * `@smthrs/flows`' `NodeRuntime` defaults to this function, while
+ * `@smthrs/cli`'s `NodeControl` passes `sameHostPidProbe`. This function
+ * returns a one-argument function, which is structurally accepted as an
+ * `Ownership.LivenessCheck` and ignores its `context` argument. Pick the
+ * probe for its cross-host policy and source of host identity.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const isAlive = (options: Options): (owner: Owner) => Effect.Effect<boolean> => {
+  const send = options.signal ?? ((pid, signal) => {
+    process.kill(pid, signal)
+  })
+  return (owner) => Effect.sync(() => owner.hostId !== options.hostId || signalable(send, owner.pid))
+}

package/src/NodeHost.ts

@@ -0,0 +1,253 @@
+/**
+ * Aggregate Node.js Host bundle.
+ *
+ * This module defines the `NodeHost` service union and a single `layer` that
+ * provides the closed Host surface backed by Node: `@effect/platform-node`'s
+ * filesystem, child-process spawner, Undici `HttpClient`, native `Path`,
+ * and the Node `Jj` adapter from its own package. Use the layer when a Node
+ * program wants every host capability from one place; use the individual
+ * modules when a program should only be able to reach part of the host. The
+ * bundle also supplies native `ProcessConfinement` for the kernel spawner.
+ *
+ * There is no Node HTTP module either: outgoing requests are Effect's
+ * `HttpClient`, and `@effect/platform-node` already ships the Undici-backed
+ * implementation. Undici follows no redirect unless a redirect interceptor is
+ * installed, so every hop stays visible to `@smthrs/kernel`'s decorator.
+ *
+ * There is no Node shell module: running a command is Effect's
+ * `ChildProcessSpawner`, and `@effect/platform-node` already ships the
+ * implementation.
+ *
+ * @since 0.1.0
+ */
+
+import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner"
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
+import * as NodePath from "@effect/platform-node/NodePath"
+import type { Jj, JjError } from "@smthrs/jj"
+import * as NodeJj from "@smthrs/jj/node/NodeJj"
+import type { HostServiceIds } from "@smthrs/kernel/HostServices"
+import type * as KernelProcessConfinement from "@smthrs/kernel/ProcessConfinement"
+import type * as ProcessLedger from "@smthrs/kernel/ProcessLedger"
+import type { FileSystem } from "effect/FileSystem"
+import * as Layer from "effect/Layer"
+import type * as Path from "effect/Path"
+import * as Schema from "effect/Schema"
+import type { HttpClient } from "effect/unstable/http/HttpClient"
+import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
+import { isAbsolute } from "node:path"
+import * as AtomicFileSystem from "./AtomicFileSystem.ts"
+import * as EgressHttpClient from "./EgressHttpClient.ts"
+import * as ProcessConfinement from "./ProcessConfinement.ts"
+import * as ProcessReaper from "./ProcessReaper.ts"
+
+/**
+ * The Node platform modules Effect ships, re-exported so a program that wants
+ * only part of the host has one place to reach for them. `NodeJj` belongs to
+ * `@smthrs/jj`; import it from there.
+ *
+ * `NodeCrypto` is here for a different reason than the rest. `Crypto` is not a
+ * Host service — it carries no host authority the kernel could attenuate, so
+ * it is not in {@link NodeHost} and not in the closed list — but every durable
+ * composition needs one, and a program that already depends on this package
+ * for its host should not have to add a second dependency for the digest.
+ *
+ * @category re-exports
+ * @since 0.1.0
+ */
+export {
+  AtomicFileSystem,
+  EgressHttpClient,
+  NodeChildProcessSpawner,
+  NodeCrypto,
+  NodeFileSystem,
+  NodeHttpClient,
+  ProcessReaper
+}
+
+/**
+ * The `HttpClient` every bundle below installs: Undici through the egress
+ * proxy this process's environment names, and a direct Undici pool when it
+ * names none.
+ *
+ * `NodeHttpClient.layerUndici` is the direct pool unconditionally. It is still
+ * re-exported above for a program composing its own services, but a bundle
+ * that spans a whole host has to work inside a sandbox whose only way out is a
+ * proxy, so the bundles read the environment. See {@link EgressHttpClient}.
+ */
+const httpClient = EgressHttpClient.layer(process.env)
+
+/**
+ * The union of host services provided by the Node host layer.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type NodeHost =
+  | FileSystem
+  | Path.Path
+  | ChildProcessSpawner
+  | Jj
+  | HttpClient
+  | KernelProcessConfinement.ProcessConfinement
+
+/**
+ * Invalid repository-root configuration, refused before layer construction.
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export class NodeHostError extends Schema.TaggedError<NodeHostError>()("@smthrs/platform-node/NodeHostError", {
+  code: Schema.Literal("invalid_repository_root"),
+  message: Schema.String
+}) {
+  override readonly name = "NodeHostError"
+}
+
+const absoluteRoot = (root: string): string => {
+  if (isAbsolute(root)) return root
+  throw new NodeHostError({
+    code: "invalid_repository_root",
+    message: `NodeHost requires an absolute repository root, got ${
+      JSON.stringify(Array.from(root).slice(0, 64).join(""))
+    }`
+  })
+}
+
+/**
+ * Stable implementation identities for the raw bundle's five Host slots.
+ * Contained POSIX factories replace its spawner with {@link ProcessReaper.layerSpawner}.
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const implementationIds: Readonly<Record<(typeof HostServiceIds)[number], string>> = {
+  "effect/FileSystem": "@smthrs/platform-node/AtomicFileSystem",
+  "effect/Path": "@effect/platform-node/NodePath",
+  "effect/process/ChildProcessSpawner": "@effect/platform-node/NodeChildProcessSpawner",
+  "@smthrs/jj/Jj": "@smthrs/jj/node/NodeJj",
+  "effect/HttpClient": "@smthrs/platform-node/EgressHttpClient"
+}
+
+/** The two services `NodeChildProcessSpawner` resolves paths and files with. */
+const platform = Layer.mergeAll(AtomicFileSystem.layer, NodePath.layer)
+
+/**
+ * What a caller may configure about a contained Node host.
+ *
+ * `platform` is deliberately absent. `ContainedSpawner.Options` declares it so a
+ * caller that supplies its own spawner can describe one, but this native host
+ * detaches by `process.platform` whatever a record claims. A caller-supplied
+ * `"win32"` on a POSIX host would therefore
+ * record `pgid: null` for a child that really does lead a group, and
+ * {@link ProcessReaper.reap} would retire that record as `no-group` and leave
+ * the orphan running forever — a durable lie rather than a compile error.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ContainedOptions = ProcessReaper.SpawnerOptions & ProcessReaper.Options
+
+/** The reaper half of {@link ContainedOptions}. */
+const reaping = (options?: ContainedOptions): ProcessReaper.Options => ({
+  ownerPid: options?.ownerPid,
+  system: options?.system
+})
+
+/**
+ * Provides the default Node implementations for the whole closed Host surface.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer: Layer.Layer<NodeHost, JjError> = Layer.mergeAll(
+  ProcessConfinement.layer(),
+  platform,
+  Layer.provide(NodeChildProcessSpawner.layer, platform),
+  httpClient,
+  NodeJj.layer
+)
+
+/**
+ * Provides the Node host with `Jj` bound to one absolute repository root.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerAt = (repositoryRoot: string): Layer.Layer<NodeHost, JjError> =>
+  Layer.mergeAll(
+    ProcessConfinement.layer(),
+    platform,
+    Layer.provide(NodeChildProcessSpawner.layer, platform),
+    httpClient,
+    NodeJj.layerAt(absoluteRoot(repositoryRoot))
+  )
+
+/**
+ * Provides the Node host with process containment turned on.
+ *
+ * The difference from {@link layer} is what happens to a spawned process when
+ * its run stops. Under {@link layer} a child is signalled when its scope
+ * closes and then waited for, forever if it ignores `SIGTERM`, and a host that
+ * dies without closing its scopes abandons every child it started. This layer
+ * gives each child an escalation deadline and records it in the
+ * `ProcessLedger`, then sweeps the records a previous incarnation of the same
+ * host left behind before it hands the host over
+ * ({@link ProcessReaper.reap}).
+ *
+ * jj is contained here too: `layerContained` builds the `Jj` service over the
+ * same spawner rather than letting it start its own children, so a `jj`
+ * invocation a crashed host left running is a record the next incarnation
+ * reaps like any other.
+ *
+ * The ledger is a requirement rather than a default because the durable half
+ * of containment is only as good as the journal underneath it:
+ * `ProcessLedger.layer` inherits a crashed incarnation's processes,
+ * `ProcessLedger.layerMemory` contains this incarnation and nothing more, and
+ * the choice belongs to the program that knows which it has.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerContained = (
+  options?: ContainedOptions
+): Layer.Layer<NodeHost, JjError, ProcessLedger.ProcessLedger> => {
+  const spawner = Layer.provide(
+    ProcessReaper.layerSpawner({ graceMs: options?.graceMs }),
+    Layer.provide(NodeChildProcessSpawner.layer, platform)
+  )
+  return Layer.mergeAll(
+    ProcessConfinement.layer(),
+    platform,
+    httpClient,
+    // jj goes through the CONTAINED spawner here, not around it. `NodeJj.layer`
+    // spawns its own children, which is right for a host that has no spawner
+    // to offer, but under containment it would mean a `jj` that leads no
+    // recorded process group, appears in no ledger, and survives the
+    // incarnation that started it.
+    Layer.provideMerge(NodeJj.layerSpawner, spawner)
+  ).pipe(Layer.provideMerge(ProcessReaper.layer(reaping(options))))
+}
+
+/**
+ * Provides the contained Node host with `Jj` bound to one absolute repository
+ * root.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerContainedAt = (
+  repositoryRoot: string,
+  options?: ContainedOptions
+): Layer.Layer<NodeHost, JjError, ProcessLedger.ProcessLedger> => {
+  const spawner = Layer.provide(
+    ProcessReaper.layerSpawner({ graceMs: options?.graceMs }),
+    Layer.provide(NodeChildProcessSpawner.layer, platform)
+  )
+  return Layer.mergeAll(
+    ProcessConfinement.layer(),
+    platform,
+    httpClient,
+    Layer.provideMerge(NodeJj.layerSpawnerAt(absoluteRoot(repositoryRoot)), spawner)
+  ).pipe(Layer.provideMerge(ProcessReaper.layer(reaping(options))))
+}