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

package/docs/concepts/descriptor-relative-filesystem.md

@@ -0,0 +1,181 @@
+---
+title: "The descriptor-relative filesystem"
+description: "Why AtomicFileSystem runs every filesystem operation through the smithers-jj-export helper, what confinement that buys, which operations it covers, and what it costs per call."
+sidebar:
+  order: 2
+---
+
+`AtomicFileSystem` is `NodeHost`'s filesystem slot, and it is not Effect's
+`NodeFileSystem`. It exists to close one race.
+
+## The race it closes
+
+A capability check names a path. A path-based operation resolves that path
+again when it runs. Between the two, anything with write access to the
+workspace can replace a component of the path with a symlink, and the operation
+that was authorized for one file performs on another.
+
+POSIX has the answer: open a directory, keep the descriptor, and perform the
+final syscall relative to it (`openat(2)`, `renameat(2)`, and the `dir_fd`
+family). A descriptor names an inode, not a name, so a swap after the walk
+cannot redirect anything.
+
+Node's JavaScript filesystem API exposes none of that, and no root-handle
+equivalent. So `AtomicFileSystem` delegates each operation to the native
+`smithers-jj-export` helper, which does have it. For ordinary operations and batches, the helper walks
+from the filesystem root to the canonical workspace root using descriptor-relative
+`O_NOFOLLOW | O_DIRECTORY` opens for every component. It verifies the opened
+root's device/inode against the identity captured when the kernel layer was
+composed, then performs the operation relative to a pinned parent descriptor.
+An ancestor symlink swap or replacement of the root by another directory fails
+ordinary operations with `PermissionDenied` before any content is read or changed.
+
+## What the helper refuses
+
+The confinement rules are strict, and two of them surprise people:
+
+- **A regular file with more than one hard link cannot be opened.** A hard link
+  is not a symlink, so `O_NOFOLLOW` cannot confine it: the same inode is
+  reachable from outside the workspace under another name. Refusing the open is
+  the only confinement available.
+- **A symlink is never traversed, opened, renamed, or removed.** Directory
+  listing is the single exception. It names a symlink entry and never descends
+  through it, because listing resolves nothing and refusing would buy no
+  confinement.
+
+Two more rules follow from requiring the kind on the descriptor rather than on
+a name:
+
+- **Only regular files carry content.** A FIFO, a socket, a device, or a
+  directory is refused for every read and write, because the kind is checked on
+  the already-open descriptor and cannot be swapped afterwards.
+- **Every open is non-blocking.** A named pipe planted at a path cannot park
+  the adapter inside `open()` until some other process opens the other end. A
+  write-only open of a reader-less pipe returns a typed failure instead. Node's
+  own filesystem waits there indefinitely, which is the one place this adapter
+  is deliberately stricter than the implementation it mirrors.
+
+The workspace root itself is addressable like any other directory: `exists`,
+`stat`, `readDirectory`, `realPath`, `glob`, and a recursive `makeDirectory`
+all answer for it. Removing it, renaming it or onto it, reading it as a file,
+writing over it, and a non-recursive `makeDirectory` on it stay refused.
+
+## Which operations it covers
+
+Fifteen operations can be expressed as one descriptor-relative request, and
+those are the ones the adapter implements:
+
+```text
+readFile  readFileString  writeFile  writeFileString  exists  stat
+readLink  realPath  makeDirectory  readDirectory  remove  rename  glob
+chmod  chown
+```
+
+`chmod` and `chown` change metadata through the descriptor of the resolved
+target (`fchmod`, `fchown`), never through a path. They refuse a symbolic link,
+a hard-linked file and the workspace root, a mode outside `0` to `0o7777`, and
+an owner below `-1`; `-1` leaves a `uid` or `gid` unchanged. The change is
+synced before the call returns. A refusal arrives as a typed failure and the
+target keeps its previous mode and owner.
+
+Everything else on Effect's `FileSystem` surface returns a live handle or a
+stream that Node cannot open relative to a pinned descriptor: `open`, `stream`, `sink`, `watch`, `copy`,
+`copyFile`, `link`, `symlink`, `access`, `truncate`, `utimes`, and the `makeTemp*` family.
+Under the kernel decorator each of those fails closed with a typed
+`PermissionDenied` rather than silently reverting to a path-based call. A
+program that needs them reaches for the raw `NodeHost.NodeFileSystem` outside
+the capability boundary.
+
+Wrapping that raw layer directly also fails closed, because it carries no
+atomic extension for the kernel to call.
+
+## How the helper is started
+
+The helper is `smithers-jj-export --atomic-fs`, a Rust binary shipped with the
+package. Three properties of how it is started are load-bearing:
+
+- **Absolute path, never a `PATH` lookup.** A binary planted in the working
+  directory or on an injected `PATH` would run inside the process that holds
+  the pinned root descriptor.
+- **Outside the workspace.** The resolved executable must be an executable
+  regular file outside the confined root. A packaged helper is copied out of
+  the workspace when the first host layer in the process is built, before any
+  flow runs; later layer builds copy nothing.
+- **Inert process.** It starts with an empty environment and the filesystem
+  root as its working directory.
+
+Both directions of the protocol are length-framed and bounded, so neither a
+large file nor a malfunctioning helper can make the host allocate without
+limit. See
+[Configure the filesystem helper](../guides/configure-the-filesystem-helper.md)
+for the ceilings and how to change them.
+
+## What it costs
+
+An ordinary operation starts one helper. The guarded filesystem also
+offers `FileSystem.batch(fs)` from `@smthrs/kernel/FileSystem`: one helper
+serves up to 128 read requests against the same root descriptor. Requests may
+stat, list directories, expand host globs, or collect SHA-256 digests, optionally
+with file bytes. The helper exits after that request. There is no persistent
+process.
+
+Through the kernel's guarded filesystem, authorization resolves each path
+through the helper too, never through a host pathname: once before the grant
+decision and once after. A guarded operation therefore starts three helpers,
+and so does a guarded batch, whose members are resolved together.
+
+- Prefer one recursive `readDirectory` (one helper for the whole tree) to a read
+  per entry.
+- Use bounded batches for a wide fan-out. Without a ceiling, an
+  `Effect.forEach(files, read, { concurrency: "unbounded" })` over fifty paths
+  would start fifty helpers at once, which is why the adapter carries a
+  process ceiling at all.
+
+Each batch member keeps its own canonical resource and grant check. Denied
+members never enter the helper. Results retain their request index and sort by
+normalized path using JavaScript's UTF-16 order, including Unicode names and
+duplicate requests. Directory and glob results also sort deterministically.
+
+The guard captures the root's device/inode at composition. The helper walks to
+that root without following any component symlink and verifies its identity
+before and after measurement. Root loss is a boundary failure, not a collection
+of absent files. Digest reads compare descriptor metadata before and after the
+read, then compare the pathname against that descriptor. Directory walks check
+their opened directories for observed mutations. These checks detect changes
+during a measurement; they do not freeze a workspace or claim a simultaneous
+snapshot of unrelated paths.
+
+A workspace symlink is allowed when composed, but the kernel rechecks its
+logical path before and after grants. Retargeting it refuses the batch even
+while the old canonical root remains available to the helper.
+
+An entry absent before measurement reports `NotFound`. An entry or ancestor
+that disappears after measurement begins reports `Busy`, so an interrupted
+read cannot become evidence that the file was initially absent.
+
+The digest is SHA-256 of the original bytes. No JSON, encoding, or pathname is
+added to its input. Boundary tree and read-set identities remain the engine's
+existing canonical constructions.
+
+`AtomicFileSystem.helperSpawns()` exposes a process-local count for diagnostics.
+Elapsed timings from `scripts/observation-bench.ts` are local measurements and
+do not establish a production speed claim.
+
+## Errors
+
+Errno is normalized to the same reasons `@effect/platform-node` reports, so a
+caller reads the same typed reason it would get from the native filesystem,
+with one addition: a helper failure that carries no errno at all stays
+`PermissionDenied`, so the boundary fails closed.
+
+Writes follow Effect's `OpenFlag` contract exactly (`r`, `r+`, `w`, `wx`, `w+`,
+`wx+`, `a`, `ax`, `a+`, `ax+`), and the test suite checks each flag against the
+native Node filesystem. Truncation runs on the opened descriptor rather than
+through `O_TRUNC`, so a hard link is refused before the file is modified.
+
+`remove(path, { recursive: true })` walks iteratively with an explicit
+descriptor stack, bounded at 512 levels deep and 100000 entries visited. One
+directory's names are read before any of its entries is unlinked, because
+unlinking from a directory while iterating it is undefined. Progress is partial
+on refusal: entries already unlinked stay unlinked. `force: true` succeeds for
+a path whose ancestors do not exist, exactly as `fs.rm` does.

package/docs/concepts/host-bundle.md

@@ -0,0 +1,125 @@
+---
+title: "The host bundle"
+description: "Why the Host surface is a closed set of five tags, which of them this package composes and which it implements, and why there is no shell service, no HTTP wrapper, and no Windows support."
+sidebar:
+  order: 1
+---
+
+A Smithers **host** is the boundary between a durable flow and the machine
+underneath it. The surface is closed: five service tags, no more, and
+[`@smthrs/kernel`](/api/kernel) owns the list.
+
+```text
+FileSystem  Path  ChildProcessSpawner  Jj  HttpClient
+```
+
+Closing the list is what makes the capability check complete. The kernel
+decorates each of the five with a permission check, so a program that reaches
+the machine has to go through a tag the kernel is watching. A sixth capability
+smuggled in beside them would be authority nobody checked.
+
+Three of the five tags are Effect's own, from `effect/FileSystem`,
+`effect/Path`, and `effect/unstable/process/ChildProcessSpawner` and
+`effect/unstable/http/HttpClient`. Smithers provides implementations of them
+rather than wrappers around them, so an ordinary Effect program runs on a
+Smithers host unchanged. `Jj` is the one Smithers tag, and it lives in
+[`@smthrs/jj`](/api/jj).
+
+## What this package composes
+
+`@effect/platform-node` already ships most of a Node host. `NodeHost.layer` is
+mostly assembly:
+
+| Tag                   | Implementation                          |
+| --------------------- | --------------------------------------- |
+| `Path`                | `NodePath.layer`                        |
+| `ChildProcessSpawner` | `NodeChildProcessSpawner.layer`         |
+| `HttpClient`          | `EgressHttpClient.layer(process.env)`   |
+| `Jj`                  | `@smthrs/jj`'s `NodeJj.layer`           |
+| `FileSystem`          | this package's `AtomicFileSystem.layer` |
+
+Only the filesystem slot is this package's own implementation, and
+[it exists because Node cannot express what the kernel needs](./descriptor-relative-filesystem.md).
+
+The HTTP slot is Undici either way. `EgressHttpClient.layer` routes it through
+the egress proxy `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` name, and is exactly
+`NodeHttpClient.layerUndici` when they name none, so an unproxied host is
+unchanged. A bundle spans a whole host, and a host may be a sandbox whose only
+way out is that proxy; a bare Undici `Agent` reads none of those variables and
+dials every origin directly, which such a host drops.
+
+`NodeHost` re-exports the pieces it composes, so a program that wants one slot
+rather than the whole bundle needs no second dependency:
+`NodeHost.AtomicFileSystem`, `NodeHost.ProcessReaper`, `NodeHost.NodeCrypto`,
+`NodeHost.NodeFileSystem`, `NodeHost.NodeChildProcessSpawner`,
+`NodeHost.NodeHttpClient`, and `NodeHost.EgressHttpClient`.
+
+`NodeCrypto` is there for a different reason from the rest. `Crypto` is not a
+Host service: it carries no host authority the kernel could attenuate, so it is
+not in the closed list. Every durable composition needs one anyway, and a
+program that already depends on this package for its host should not need a
+second dependency for the digest.
+
+## The four layers
+
+The bundle ships four layers, along two independent axes: where `Jj` is rooted,
+and whether spawned processes are contained.
+
+| Layer                                       | `Jj` bound to                 | Containment |
+| ------------------------------------------- | ----------------------------- | ----------- |
+| `NodeHost.layer`                            | the process working directory | no          |
+| `NodeHost.layerAt(root)`                    | one absolute repository root  | no          |
+| `NodeHost.layerContained(options?)`         | the process working directory | yes         |
+| `NodeHost.layerContainedAt(root, options?)` | one absolute repository root  | yes         |
+
+The rooted pair exists because a durable host outlives any one working
+directory. `@smthrs/flows`' `NodeRuntime` composes `layerContainedAt`, so both
+the repository and the process containment are pinned by the runtime rather
+than inherited from whatever shell started it.
+
+The contained pair carries a requirement the plain pair does not: a
+`ProcessLedger`. See [Process containment](./process-containment.md) for what
+it buys and why the ledger is not defaulted.
+
+## What the bundle does not provide
+
+Each of these is a decision with a consequence, not a gap.
+
+**There is no shell service.** Running a command is Effect's `ChildProcess` and
+`ChildProcessSpawner`. That means a wall-clock budget is `Effect.timeout`
+around the effect rather than an option on a command record, and cancellation
+is fiber interruption rather than an `AbortSignal`. A Smithers shell service
+would be a second way to express what Effect already expresses, and the kernel
+would then have two spawn paths to check instead of one.
+
+**There is no HTTP service.** An outgoing request is Effect's `HttpClient`, and
+`@effect/platform-node` already ships the Undici-backed implementation. Undici
+follows no redirect unless a redirect interceptor is installed, and this bundle
+installs none, so every hop stays a separate request. That is what lets the
+kernel check `net:get` and `net:post` against the host of every URL a request
+actually reaches, redirect targets included.
+
+**There is no Windows support.** `AtomicFileSystem` needs `O_NOFOLLOW`,
+`O_DIRECTORY`, and `dir_fd`, none of which Windows has, so every filesystem
+call fails closed there. `ProcessReaper` still reaches `taskkill /T /F` through
+`systemFor("win32")` rather than retiring every record unsignalled, because a
+reaper that silently discarded records would be worse than one that says what
+it does. Treat it as unsupported best-effort.
+
+**There is no path-based fallback.** A host with no usable `smithers-jj-export` helper fails
+every guarded filesystem call with `PermissionDenied`. The adapter never
+degrades to a check-then-path operation, because that is exactly the race it
+exists to close.
+
+## Conformance
+
+The bundle is not trusted to be correct because it is composed correctly. It
+runs the shared host contract from `@smthrs/kernel/test/contract` twice: once
+with explicit expectations, and once taking every default the suite offers,
+against a loopback HTTP server so the `HttpClient` success path is asserted
+rather than only its refusal.
+
+On top of that, the atomic filesystem is compared row by row against
+`@effect/platform-node`'s own adapter (open flags, errno classification, `stat`
+fields, and the glob grammar), and containment is driven over real detached
+process groups.

package/docs/concepts/process-containment.md

@@ -0,0 +1,190 @@
+---
+title: "Process containment"
+description: "How a crashed host's abandoned processes get killed: incarnations, the process ledger, and every guard ProcessReaper checks before it signals a durable record."
+sidebar:
+  order: 3
+---
+
+A target's exit does not mean its children exited. A host killed outright
+runs no finalizers either. The contained Node host uses a live POSIX supervisor
+to own each process group independently of the target and to observe host loss
+through a private connection. A process ledger lets a later host reconcile
+records whose cleanup was not confirmed.
+
+## Incarnations
+
+A **host** has a durable `hostId`. Each time a process starts under that id, it
+is a new **incarnation**, identified by its pid. The ledger records which
+incarnation started each process, so a later incarnation can tell its own live
+children from an abandoned one's.
+
+That is the whole shape of the problem: the input to reaping is a durable
+record that outlived the process that wrote it, on a machine where the
+operating system reuses pid numbers.
+
+## The live half: the contained spawner
+
+`NodeHost.layerContained` uses `ProcessReaper.layerSpawner` to compose
+[`@smthrs/kernel`](/api/kernel)'s `ContainedSpawner` with a native process
+adapter and `ProcessReaper.processLifecycle`:
+
+- Preparation creates an owner without executing the target. The kernel
+  records its identity and the original command digest before activation.
+- Every pipeline leg has a separate owner and ledger record. On POSIX the
+  handle's `pid` is that supervisor's; `exitCode` and `isRunning` describe the
+  target. Signals go through `handle.kill`.
+- Cleanup keeps its deadline after the target exits, so a same-group child
+  cannot keep inherited output open indefinitely. Only verified cleanup retires
+  the record; failed cleanup fails scope close and retains it.
+- The grace period is an upper bound. Once the target has exited and the group
+  holds no other live member and no captured escaped descendant, cleanup
+  finishes at once.
+- A grouped supervisor starts a guardian in its group before the target: a
+  `/bin/sh` that waits on a pipe only the supervisor holds. A supervisor killed
+  outright (`SIGKILL`, the OOM killer) runs no handler, so at that pipe's EOF
+  the guardian kills its own group with `kill 0`, which names the caller's
+  group rather than a number that could be stale. It ignores the catchable
+  signals a stop sends the group and dies in the supervisor's final `SIGKILL`.
+  A host without `/bin/sh` refuses to start a grouped target. A lost
+  supervisor sends no cleanup receipt, so its release stays unverified.
+
+Confined children use private directories for `HOME` and XDG config, cache, data, and state.
+
+Default commands lead their own group. `detached: false` opts out of group
+cleanup and signals only the native target. Explicit stopping of a still-live
+grouped target additionally attempts a revalidated positive-PID sweep of
+escaped descendants, with ordinary POSIX PID races remaining. Natural exit
+does not promise cleanup of deliberately escaped sessions.
+
+An explicit stop owns its deadline until cleanup is acknowledged. A target exit
+received during that stop does not send another request. The helper preserves
+the accepted signal and grace period across target exit and either socket's
+closure, even when its configured default is `SIGKILL`. A still-live target
+receives that policy even after calling `setsid()` to leave the supervisor's
+group. Group membership selects the descendant sweep, not the target's signal
+or grace period. Only an unactivated owner or verified natural completion can
+use the host's immediate cleanup shortcut. After the target exits, the helper
+reads the process table once: an empty group with no captured escaped
+descendant ends the stop at once, since waiting cannot clean anything more.
+A live group member, a captured escaped descendant or an unreadable table keeps
+the full deadline. Requests and lifetime
+status use separate private sockets, so an EPIPE on a late request cannot discard
+a buffered target exit or cleanup receipt. The host drains that receipt and
+verifies the process group before retiring the ledger record.
+
+Delivery deadlines and verification retries use the platform clock. Freezing
+the caller's Effect clock does not freeze native process cleanup or turn an
+unverifiable group into an unbounded scope finalizer.
+
+`jj` goes through that same spawner rather than around it. `NodeJj.layer`
+spawns its own children, which is right for a host that has no spawner to
+offer; under containment it would mean a `jj` invocation that leads no recorded
+process group, appears in no ledger, and survives the incarnation that started
+it.
+
+## The durable half: the sweep
+
+`ProcessReaper.reap` runs once while the contained layer is built. It reads the
+records a previous incarnation of the same `hostId` left behind and kills the
+process groups they name. Standing a host up is therefore also what cleans up
+after the incarnation that crashed.
+
+The rules are narrow on purpose. A record is signalled only when every one of
+these holds:
+
+1. It belongs to a different incarnation of the same `hostId`. The ledger
+   filters that before the reaper sees it.
+2. Its owner is gone. A pid that exists but belongs to another user counts as
+   alive, so only `ESRCH` reads as dead and every other answer keeps the
+   record.
+3. Its numbers name something this platform can signal. On POSIX that is a
+   process group the child leads itself, so `pgid` has to be a safe integer
+   above 1 and equal to `pid`. On Windows it is a pid, so `pgid` has to be
+   absent. The check is made against the durable record rather than trusted
+   from it, because `process.kill(-0, "SIGKILL")` would signal this host's own
+   process group.
+4. That group is not this process's group, and its pid is not this process's
+   pid. The host's real process group is read from the operating system,
+   because a stored number can claim anything and the shell that started this
+   host shares its group.
+5. The number still names the process the record describes. A record written
+   before this machine booted names a pid from a pid space that no longer
+   exists; within one boot, the recorded start time has to match the start time
+   the operating system reports for that pid.
+
+## No evidence never authorizes a kill
+
+Two of those guards are questions put to `ps`: this process's own group, and
+when the recorded pid started. Either can go unanswered on a host with no
+usable `ps`.
+
+An unanswered guard refuses. A guard that did not run is not a guard that
+passed, so a record whose identity could not be verified is kept rather than
+signalled.
+
+The probe is deliberately unhelpful to anyone trying to fool it. It runs
+`/bin/ps` by absolute path, never a `PATH` lookup, under `LC_ALL=C` and `TZ=UTC`
+in a minimal environment, with a five-second `SIGKILL` deadline. Start times
+are parsed explicitly as UTC, independent of the host runtime's timezone.
+Live cleanup on Linux instead reads group membership, start times, and zombie
+state directly from `/proc`, so it works without `procps`. Missing processes
+are skipped; unreadable or malformed data leaves cleanup unverified. Other
+POSIX hosts use `/bin/ps` for live cleanup with the same timezone and parsing.
+The crash-recovery sweep still uses the `ps` probes described here.
+The probe reads the
+`pgid` column as one run of decimal digits and nothing else: `Number.parseInt`
+reads a prefix, so `"12 34"`, `"12abc"`, and `"0x10"` would each become a
+number that is not this host's group, silently pass the own-group comparison,
+and suppress the refusal that exists to say the comparison could not be made.
+
+## Refusals, and which ones are final
+
+Every refusal also decides whether the record is retired. Retiring says in the
+journal that nothing was signalled, which stops every later incarnation
+re-examining a number the operating system has moved on from. Only a refusal a
+later incarnation cannot answer differently is final.
+
+| Refusal               | What it means                                               | Retired |
+| --------------------- | ----------------------------------------------------------- | ------- |
+| `owner-alive`         | the incarnation that started it is still running            | no      |
+| `identity-unverified` | this host could not read the pid's start time               | no      |
+| `own-group-unknown`   | this host could not read its own process group              | no      |
+| `kill-failed`         | the signal was refused, so it is tried again                | no      |
+| `no-group`            | it shared its owner's group, so there is no group to signal | yes     |
+| `own-group`           | it named this host's own group or pid                       | yes     |
+| `invalid-record`      | its numbers name nothing this platform may signal           | yes     |
+| `pre-boot`            | it was written before this machine booted                   | yes     |
+| `process-gone`        | the pid it names does not exist                             | yes     |
+| `identity-mismatch`   | the pid exists but did not start when the record says       | yes     |
+
+A retirement that fails to commit is logged rather than propagated. The process
+is already dead and the record stays inherited, so the next incarnation reads
+it, finds the pid gone, and retires it then; failing the whole sweep would take
+the host down for a bookkeeping write.
+
+## The one deliberate leak
+
+`identityToleranceMs` is 2000. It covers two gaps at once: `ps` reports
+`lstart` with one-second granularity, and `uptime` places the boot instant to
+the nearest second.
+
+The boot tolerance points backwards, so a record written moments after boot is
+read as predating it and refused. That refusal is `pre-boot`, which retires the
+record, so a group spawned inside that two-second window is never reaped by any
+later incarnation either. It is a leak rather than a retry, and it is the
+deliberate price of refusing to kill on an instant the host can only place to
+the nearest second.
+
+## Windows
+
+Windows has no `lstart` and no process groups, so two guards cannot be answered
+there: the identity check falls back to the boot-time comparison alone, and
+there is no own-group refusal to make. `taskkill /T /F` walks the tree down
+from the recorded pid instead. This is a documented weaker guarantee on an
+unsupported platform, not an oversight.
+
+## Next
+
+[Contain child processes](../guides/contain-child-processes.md) is the
+task-shaped version of this page: the layers to compose, the ledger to choose,
+and how to read what the sweep decided.

package/docs/guides/answer-run-ownership.md

@@ -0,0 +1,87 @@
+---
+title: "Answer whether a run owner is alive"
+description: "Wire HostLiveness.isAlive as the probe the engine consults before it steals a run, understand why the rule errs toward alive, and know where the sibling implementation disagrees."
+---
+
+A durable run records the owner that holds it: a `hostId` and a pid. When
+another process wants that run, it asks whether the recorded owner is still
+alive. `HostLiveness.isAlive` is this package's answer.
+
+Both ways of being wrong are expensive, and they are not equally expensive. A
+wrong `true` strands a run until an operator intervenes. A wrong `false` runs
+one run twice.
+
+## Wire the probe
+
+```ts
+import { HostLiveness } from "@smthrs/platform-node"
+
+const isAlive = HostLiveness.isAlive({ hostId: "engine-1" })
+```
+
+`isAlive` returns a function from an owner to `Effect<boolean>`. The owner type
+is structural: `{ hostId: string, pid: number }`, which is exactly the shape of
+[`@smthrs/journal`](/api/journal)'s `OwnerId` minus its nonce, so an `OwnerId`
+is accepted without this package depending on the journal to name a type.
+
+`@smthrs/flows`' `NodeRuntime` defaults to this function, so a program that
+composes the runtime gets it without asking.
+
+## The rule
+
+The rule is asymmetric on purpose:
+
+- **An owner on 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 on this host is dead only when the signal-0 probe reports
+  `ESRCH`.** Every other result preserves liveness.
+
+`process.kill(pid, 0)` sends no signal. `EPERM` means
+the process 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 keeps that from crashing the
+probe: a thrown string or `null` is an answer nobody gave, which counts as a
+live owner.
+
+## The residual risk
+
+Pid reuse. An owner whose pid was recycled by an unrelated program reads as
+alive, and its run waits for an operator.
+
+That 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.
+
+## Substitute a better answer where you have one
+
+A multi-process deployment with a supervisor or a lease system knows better
+than any pid probe, and should answer from that instead. `isAlive` is one
+implementation of a slot, not a fixed policy.
+
+## Know where the sibling disagrees
+
+`@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 signal-error rows describe valid same-host pids:
+
+| Input                                            | `HostLiveness.isAlive` | `Ownership.sameHostPidProbe` |
+| ------------------------------------------------ | ---------------------- | ---------------------------- |
+| signal error `ESRCH`                             | dead                   | dead                         |
+| signal error `EPERM`, `EINVAL`, or unknown error | alive                  | alive                        |
+| owner on a different `hostId`                    | alive                  | defer to expired lease       |
+
+`sameHostPidProbe` returns `false` for a foreign host without probing its pid.
+The engine consults it after lease expiry, and the store verifies the expired
+lease before allowing a steal. `HostLiveness.isAlive` returns `true` for a
+foreign host, so runs on a permanently dead host 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`](/api/cli)'s `NodeControl` passes `sameHostPidProbe`.
+
+`HostLiveness.isAlive` compares with its configured `hostId` and ignores the
+`context` argument of `Ownership.LivenessCheck`. `sameHostPidProbe` compares
+with `context.claimant.hostId`. Pick the probe for its cross-host policy and
+source of host identity.