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

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

@@ -0,0 +1,118 @@
+---
+title: "Contain spawned processes"
+description: "Compose ContainedSpawner and ProcessLedger so a cancelled run kills its children on a deadline and a crashed host leaves records its successor can reap."
+sidebar:
+  order: 6
+---
+
+Without containment, a spawned child that ignores `SIGTERM` hangs a
+cancellation forever, and a host that crashes abandons every process it
+started. This guide composes a platform lifecycle and a process ledger to own cleanup.
+
+## Compose the spawner over the ledger
+
+On Node or Bun, `ProcessReaper.layerSpawner` supplies the native adapter,
+prepared lifecycle, and kernel containment together. It requires
+`ChildProcessSpawner` (which it also provides) and `ProcessLedger`:
+
+```ts
+import { ProcessLedger } from "@smthrs/kernel"
+import * as ProcessReaper from "@smthrs/platform-node/ProcessReaper"
+import { Layer } from "effect"
+
+const contained = ProcessReaper.layerSpawner({ graceMs: 2000 }).pipe(
+  Layer.provide(rawSpawner),
+  Layer.provideMerge(ProcessLedger.layer({ hostId: "my-host", ownerPid: process.pid }))
+)
+```
+
+`graceMs` is the interval between the `SIGTERM` that asks a child to stop and
+the `SIGKILL` that makes it. It defaults to `ContainedSpawner.defaultGraceMs`
+(2,000 ms).
+
+The factory always uses the real `process.platform`. A custom host can use
+`ContainedSpawner.layer(options, lifecycle)` directly; its `platform` option
+must describe the real process-group behavior. A win32 record claiming
+`pgid === pid` would name a group the child does not lead.
+
+The lifecycle prepares an owner before the command starts, records its
+identity, and only then activates the target. Each pipeline leg has its own
+record. Node and Bun use a live supervisor to keep group ownership after the
+target exits; its `pid` names that owner while `exitCode` and `isRunning`
+describe the target. A raw or deadline-only wrapper has no such contract and
+`ContainedSpawner.isContained` returns false for it.
+
+Compose the kernel permission decorator **above** containment. That order
+checks the caller's whole command before pipeline expansion or platform
+preparation. A permission decorator below it can see the trusted supervisor
+command instead of the command the caller requested.
+
+## Choose a ledger
+
+```ts
+// Durable: inherits a crashed incarnation's processes. Requires a `Journal`.
+ProcessLedger.layer({ hostId, ownerPid })
+
+// In-memory: contains this incarnation and inherits nothing. No journal.
+ProcessLedger.layerMemory({ hostId, ownerPid })
+```
+
+The durable half is only as good as the journal underneath it, so the choice
+belongs to the program that knows which it has. `hostId` names the run the
+records live on (`flows.host:<hostId>`), and `ownerPid` is what distinguishes
+this incarnation's processes from the orphans a previous one left.
+
+On Node, `@smthrs/platform-node`'s `NodeHost.layerContained` and
+`layerContainedAt` compose the spawner, bind `Jj` through it so a stray `jj`
+invocation is recorded too, and add the `ProcessReaper` that sweeps inherited
+records before handing the host over. You supply the ledger.
+
+## Handle a failed record
+
+`record`, `release`, `reaped`, and `skipped` all carry the journal's failure to
+their caller, and the spawner acts on it: a spawn whose durable record fails is
+cleaned up before target activation, and the call fails. Failed startup closes
+its own scope even if the caller catches the failure and keeps an outer scope
+open. A cleanup failure or an unverified result fails release and retains any
+record already committed; only the lifecycle's successful `settled` result
+permits retirement.
+
+The release finalizer is the exception, because it has nowhere left to report.
+A missed release leaves the record inherited, and the next reaper finds the pid
+already gone and retires it.
+
+## Read what is running and what was abandoned
+
+```ts
+const ledger = yield * ProcessLedger.ProcessLedger
+
+const running = yield * ledger.live // this incarnation's unreleased records
+const abandoned = yield * ledger.orphans // records whose owner pid is not ours
+```
+
+`orphans` replays the host's journal history, folds the exit, reap, and skip
+events onto the spawn events, and returns what is left. A host that wants to
+clean them up signals each group and then retires the record:
+
+```ts
+yield * ledger.reaped(record) // we signalled it
+yield * ledger.skipped(record, "pre-boot") // we refused to, and why
+```
+
+Use two different calls deliberately. An operator reading the journal can then
+tell "we killed it" from "we declined to", which a single retire event would
+erase.
+
+Signalling a process group you did not start is dangerous, because a pid can be
+recycled. Before reaping, verify that the record names a separate process group
+rather than your own, that the owner is gone, that the record belongs to the
+current boot, and, where the platform can read it, that the pid's start time
+still matches. `@smthrs/platform-node`'s `ProcessReaper` implements exactly
+those checks; reuse it rather than writing the comparisons again.
+
+## Related
+
+- [Process containment](../concepts/process-containment.md): why each of these
+  pieces exists.
+- [Guard a host bundle](./guard-a-host-bundle.md): containment inside the full
+  host composition.

package/docs/guides/guard-a-host-bundle.md

@@ -0,0 +1,109 @@
+---
+title: "Guard a host bundle"
+description: "Compose HostServices.layer over a platform bundle so every consumer of the five host tags resolves the guarded implementation, and get the composition order right."
+sidebar:
+  order: 1
+---
+
+`HostServices.layer` turns a raw platform bundle into the guarded surface a
+flow body runs on. This guide covers the composition, the order its pieces go
+in, and the two mistakes that quietly defeat it.
+
+## What the layer needs
+
+`HostServices.layer` both requires and provides all five host tags, and it
+additionally requires:
+
+- `Workspace`, the root that filesystem capability resources are resolved
+  against.
+- `GrantStore`, the service that decides.
+
+Every member requires the tag it provides, so the guarded implementation
+shadows the raw one for everything downstream.
+
+## The composition
+
+```ts
+import { GrantStore, HostServices, Workspace } from "@smthrs/kernel"
+import * as NodeHost from "@smthrs/platform-node/NodeHost"
+import { Layer } from "effect"
+
+const workspaceRoot = "/absolute/path/to/workspace"
+
+const guarded = HostServices.layer.pipe(
+  // 1. The decider, beneath the decorators that consult it.
+  Layer.provide(Layer.orDie(GrantStore.layer({ attended: false, rules: policy }))),
+  // 2. The raw platform, beneath the decorators that shadow it. `provideMerge`
+  //    because the composition below still needs the tags this bundle carries
+  //    that the kernel does not decorate.
+  Layer.provideMerge(NodeHost.layerAt(workspaceRoot)),
+  // 3. The workspace root, which both the store and the filesystem decorator
+  //    resolve resources against. One value, provided once, so they agree.
+  Layer.provide(Workspace.layer(workspaceRoot))
+)
+```
+
+`GrantStore.layer` fails with `GrantStoreError` when its options are invalid,
+which is a programming error rather than a runtime condition, so
+`Layer.orDie` is the honest handling. Both the store and the filesystem
+decorator take the workspace root from the same `Workspace` service, so
+provide it once above both.
+
+## Contain processes at the same time
+
+Under `NodeHost.layerAt`, the raw spawner signals its target at scope close.
+That target can ignore the signal or exit while descendants keep running, and
+a crashed host runs no finalizers. `NodeHost.layerContainedAt` adds a live
+supervisor, a cleanup deadline, a ledger, and restart reconciliation. Keep
+the permission decorator above it so the caller's complete command is
+authorized before platform preparation:
+
+```ts
+import { ProcessLedger } from "@smthrs/kernel"
+
+const guarded = HostServices.layer.pipe(
+  Layer.provide(Layer.orDie(GrantStore.layer({ attended: false, rules: policy }))),
+  Layer.provideMerge(NodeHost.layerContainedAt(workspaceRoot)),
+  Layer.provideMerge(ProcessLedger.layer({ hostId: "my-host", ownerPid: process.pid })),
+  Layer.provide(Workspace.layer(workspaceRoot))
+)
+```
+
+`ProcessLedger.layer` needs a `Journal`. For a host that has none, or one that
+should inherit nothing from a previous incarnation, use
+`ProcessLedger.layerMemory` with the same options. See
+[Contain spawned processes](./contain-spawned-processes.md).
+
+## Two mistakes to avoid
+
+**Keeping an unguarded alias.** The guarded layer shadows the raw tag for
+everything composed above it. Code that captured the raw service before the
+decorator was composed, or that resolves it from a context built without the
+decorator, is not guarded. If some part of the host genuinely needs unguarded
+access, give it a **separate service** rather than a stale reference to the
+shared one. [`@smthrs/engine`](/api/engine) does exactly that: its snapshot
+bookkeeping holds a private `Jj` service built over the raw host, so the flow
+bodies it runs get no repository authority from it.
+
+**Guarding your own bookkeeping.** The guarded surface exists to check the
+code you did not write. The machinery your host needs in order to run at all,
+the directory its database lives in, the working copy it lays down before it
+hands anything to a subject, has to exist before there is anyone to ask, so it
+cannot be behind a permission check. Build that machinery over the raw bundle,
+build the services you hand to the guarded code over the decorated one, and
+give the guarded code no way to reach the first set.
+
+## The real thing
+
+[`@smthrs/flows`](/api/flows) composes this at full size in its `NodeRuntime`:
+the Node host with containment on, the kernel over an unattended store,
+storage, the step boundary, the workspace sandbox, the engine, and signal
+handling. [Stand up a Node runtime](/pkg/flows/guides/stand-up-a-node-runtime)
+walks it when you need the whole picture rather than the shape.
+
+## Related
+
+- [Write a capability policy](./write-a-capability-policy.md): what goes in
+  `rules`.
+- [Decoration in place](../concepts/decoration-in-place.md): why the layer is
+  shaped this way.

package/docs/guides/persist-grants-across-restarts.md

@@ -0,0 +1,135 @@
+---
+title: "Persist grants across restarts"
+description: "Use JournalGrantStore so a remembered decision survives the process: the two run ids, what replay accepts and refuses, and how to keep the policy journal inside its ceiling."
+sidebar:
+  order: 4
+---
+
+The in-memory store forgets everything when its scope closes. `remembered`
+means nothing until something writes it down. `JournalGrantStore` is that
+something: it persists each decision to a [`@smthrs/journal`](/api/journal)
+journal **before** activating it, and replays the history when the next
+process builds a store.
+
+## Build it
+
+```ts
+import { JournalGrantStore } from "@smthrs/kernel"
+
+const store = JournalGrantStore.layer({
+  // The operational run. Run grants and run envelopes live here.
+  runId: "run-2026-09-03-a",
+  // The dedicated policy run. Remembered grants live here, and this id stays
+  // stable forever, because the journal has no global grant projection.
+  policyRunId: "kernel-policy",
+  // The producer id. Replay activates events from this source and no other.
+  sourceId: "my-host/grants",
+  // Binds run grants and run envelopes to the exact active plan.
+  planDigest: "plan-abc",
+  attended: true,
+  rules: [configuredPolicy]
+})
+```
+
+The layer requires `Journal` and `Workspace`. `runId` and `policyRunId` must be
+different, and every identity must be non-empty, well-formed text within
+`GrantStore.maximumIdentityLength`.
+
+`rules` here is the nested form: an array of rulesets whose first entry is your
+configured policy. Replayed remembered rules are appended as a further ruleset,
+so your configured deny keeps its hard veto over anything replay activates.
+
+The journal is authoritative permission storage. `SqlJournal` must use the
+`reject` overflow policy: a dropped grant decision cannot safely be treated as
+persisted, so drop-capable policies are unsupported.
+
+## Persist first, activate second
+
+Every decision commits to the journal before `GrantStore` activates it. A
+journal failure becomes `journal_failed` and the decision stays **inactive**,
+so a permission that could not be written down is a permission that was not
+granted.
+
+Events are routed by scope. Remembered grants and remembered envelopes go to
+`policyRunId`; once, denied, run, and run envelope events go to `runId`. They
+are written unfenced: the grant store is the kernel's own ledger rather than a
+run's lifecycle, and admissions are first-writer-wins records that every later
+process replays.
+
+## What replay accepts
+
+Replay is not a general read of the journal. It activates only what it can
+prove:
+
+- **Only the configured `sourceId`.** Events from another producer are
+  ignored, so nothing else writing to the same journal can grant kernel
+  authority.
+- **Only the five known event types.** Anything else in the run is ignored.
+- **Only correctly scoped events.** A run-scoped event found in the policy run,
+  or a remembered event found in the operational run, refuses construction
+  rather than being skipped.
+- **Only the current plan.** A run grant or run envelope whose `planDigest`
+  differs from the store's is skipped: it authorized a different plan.
+- **Only safe patterns.** Every replayed grant pattern is rechecked with
+  `isValidGrantPattern`, and every envelope pattern with
+  `isValidEnvelopePattern`. A pattern that would exceed its request refuses
+  construction, so a tampered journal cannot widen authority.
+
+Once and denied events are **audit evidence only**. They record what happened;
+they activate nothing.
+
+Two failures refuse construction outright rather than degrading: a payload that
+does not decode, or whose envelope type disagrees with its own payload type;
+and a journal page that does not advance past the cursor it was asked for.
+Following a non-advancing page would replay the same events forever, and
+accepting it would double-apply them.
+
+Replayed rules are deduplicated by formatted pattern identity, so a capability
+granted a hundred times costs one rule.
+
+## Start a new policy run when it fills
+
+A store retains at most `GrantStore.maximumRules` rules and the same number of
+envelope signatures. Because the policy run accumulates forever, that ceiling
+is a real operational limit, and `JournalGrantStore` fails closed when replay
+would exceed it. The failure names the policy run and the counts:
+
+```text
+policy run kernel-policy replayed 1024 remembered rules; configured rules (12)
+and replayed run rules (3) bring the total to 1039, which exceeds the
+1024-rule ceiling; remove configured rules or start a new policyRunId and
+grant again
+```
+
+Do not compact the policy run. Replay reads it from the first entry and never
+consults a checkpoint, so a compacted policy run fails every later
+construction with `journal_failed`. Point the store at a fresh `policyRunId`
+instead; the old run stays intact for audit.
+
+The envelope-signature ceiling produces the matching message. A construction
+envelope is refused rather than persisted once the replayed signatures already
+fill the ceiling, so the history a later process must replay cannot outgrow
+what it will accept.
+
+## Concurrent construction on one Journal service
+
+Two constructors sharing one `Journal` service instance could both replay the
+absence of the same construction envelope and both persist it. A critical
+section per service instance re-replays the target run inside the lock, so
+exactly one of those constructors appends the envelope and the others replay
+it instead. An envelope whose signature is already durable activates its rules
+without persisting again.
+
+The lock stops at the service object. Two processes, or two `Journal` services
+over one backing journal in one process, hold separate locks, and the envelope
+event carries no journal dedupe key, so both can append it. The duplicate is
+harmless to authority: replay collapses identical envelopes into one signature
+and the same rules. It costs one extra row per race, so build the store once
+per process and share the service where construction can overlap.
+
+## Related
+
+- [Answer permission requests](./answer-permission-requests.md): where
+  `remembered` decisions come from.
+- [How a grant decision is made](../concepts/grant-decisions.md): what replay
+  is rebuilding.

package/docs/guides/write-a-capability-policy.md

@@ -0,0 +1,159 @@
+---
+title: "Write a capability policy"
+description: "Turn what a host should allow into GrantStore rules: the four rulesets, the hard veto, the resource each action names, and how to narrow authority for delegated work."
+sidebar:
+  order: 2
+---
+
+A policy is an ordered list of `Permission.Rule` values handed to
+`GrantStore.make` or `GrantStore.layer` as `rules`. Each rule pairs a
+capability pattern with `allow`, `deny`, or `ask`.
+
+## Write the rules
+
+```ts
+import { Capability, GrantStore, Permission } from "@smthrs/kernel"
+
+const policy = [
+  // Read anything in the workspace.
+  new Permission.Rule({
+    effect: "allow",
+    pattern: new Capability.CapabilityPattern({ action: "fs:read", resource: "/workspace/**" })
+  }),
+  // Write anything in the workspace, except the lockfile.
+  new Permission.Rule({
+    effect: "allow",
+    pattern: new Capability.CapabilityPattern({ action: "fs:write", resource: "/workspace/**" })
+  }),
+  new Permission.Rule({
+    effect: "deny",
+    pattern: new Capability.CapabilityPattern({ action: "fs:write", resource: "/workspace/pnpm-lock.yaml" })
+  }),
+  // Exactly `npm test`, nothing appended.
+  new Permission.Rule({
+    effect: "allow",
+    pattern: new Capability.CapabilityPattern({ action: "proc:spawn", resource: "npm test" })
+  })
+]
+
+const store = GrantStore.layer({ attended: false, rules: policy })
+```
+
+Rules are last-match-wins, so the deny above beats the broad write allow that
+precedes it. Anything no rule matches defaults to `ask`, which an unattended
+store reports as `permission_required`. You never need a catch-all deny; write
+the allows.
+
+## Name the resource each action actually checks
+
+A rule only fires if its resource glob matches the resource the decorator
+built. These are the resources the kernel names:
+
+| Action                    | Resource                                                                                                                                                |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fs:read`, `fs:write`     | The canonical absolute path, with an inside-workspace path mapped back to the logical workspace root.                                                   |
+| `proc:spawn`              | `CommandLine.resource(command)`: the rendered line; a chained shell line as `sh -c '<line>'`; `env <NAME>… --` for non-bootstrap environment overrides. |
+| `net:get`, `net:post`     | The lowercased URL host for `https:`, and `<scheme>//<lowercased host>` for anything else.                                                              |
+| `model:call`              | The same, with `/<model id>` appended.                                                                                                                  |
+| `jj:status`               | `"."`                                                                                                                                                   |
+| `jj:diff`                 | `<from>:<to>`                                                                                                                                           |
+| `jj:snapshot`             | The commit message, or `""` when none was given.                                                                                                        |
+| `jj:restore`, `jj:revert` | The change id.                                                                                                                                          |
+| `jj:workspace-add`        | The canonicalized destination. This one also requires `fs:write` on the same resource.                                                                  |
+| `jj:workspace-forget`     | The workspace name.                                                                                                                                     |
+| `jj:op-restore`           | The operation id.                                                                                                                                       |
+| `jj:root`                 | The canonicalized starting directory.                                                                                                                   |
+
+Because `https` is the implicit scheme, a grant for `api.example.com` never
+authorizes `http://api.example.com`. That is the point: a host grant cannot be
+downgraded into a cleartext one.
+
+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 *`
+covers the `npm` stage of `npm test | sh` but not the `sh` stage. Grant exact
+command lines; `npm *` still runs any npm subcommand, including
+`npm exec <anything>`.
+
+The glob grammar has no escape character, so a resource that genuinely
+contains `*` or `?` cannot be named exactly. Never build a pattern by
+concatenating text an agent supplied. See
+[resource globs](/pkg/capability/concepts/resource-globs) for the full
+grammar and its edges.
+
+## The configured ruleset has a veto
+
+`MakeOptions.rules` accepts either a flat list or a nested one. The flat form
+is the configured policy. In the nested form, the first ruleset is configured
+policy and the rest are replayed remembered grants.
+
+The configured ruleset carries a power the others do not: after it is reduced
+by last-match-wins, an effective denial is a **hard veto** that no envelope
+approval, run grant, or remembered grant can lift. A configured deny that a
+later configured allow supersedes _within that same ruleset_ is not a veto, so
+an operator can still write an exception after a broad denial.
+
+Use it for the things no operator answering a prompt should be able to unlock:
+
+```ts
+const policy = [
+  new Permission.Rule({
+    effect: "allow",
+    pattern: new Capability.CapabilityPattern({ action: "fs:read", resource: "/workspace/**" })
+  }),
+  // No later grant of any kind reaches these.
+  new Permission.Rule({
+    effect: "deny",
+    pattern: new Capability.CapabilityPattern({ action: "fs:read", resource: "/workspace/.env*" })
+  })
+]
+```
+
+## Narrow authority for delegated work
+
+A rule says what the policy permits. `CapabilitySet` says what the current
+fiber may even ask for, and it only ever narrows:
+
+```ts
+import { Capability, CapabilitySet } from "@smthrs/kernel"
+
+const readOnly = CapabilitySet.attenuate([
+  new Capability.CapabilityPattern({ action: "fs:read", resource: "/workspace/**" })
+])
+
+// Inside `untrusted`, every other capability fails with permission_denied and
+// the reason "outside capability ceiling", whatever the rules say.
+const scoped = readOnly(untrusted)
+```
+
+`attenuate` intersects the parent ceiling with one more any-of group, so the
+child can narrow further and can never recover what it gave up. There is no
+public widening operation. A run grant made by an attenuated fiber is
+remembered with that fiber's ceiling and is filtered out for any capability the
+ceiling would not allow, so authority cannot leak back up.
+
+## Stay inside the bounds
+
+One store retains at most 1,024 rules across all four rulesets. The constant is
+exported as `GrantStore.maximumRules`, alongside
+`maximumEnvelopePatterns` (256), `maximumPendingRequests` (1,024),
+`maximumMetadataDepth` (16), `maximumMetadataMembers` (1,024),
+`maximumMetadataBytes` (64 KiB), `maximumEventBytes` (256 KiB),
+`maximumIdentityLength` (4,096), and `maximumCapabilityResourceLength`
+(4,096). Exceeding one fails with `invalid_resolution` before any state
+changes. Check against the exported constants rather than hardcoding the
+numbers.
+
+Decorator resources use UTF-16 code units: 4,096 is valid; 4,097 fails with
+`GrantStoreError` code `invalid_resolution` before the grant check or guarded
+host operation. Filesystem and process decorators project this error into
+`PlatformError`; HTTP projects it into `HttpClientError`. The structured error
+is retained as the cause. Jujutsu returns the typed `GrantStoreError` directly.
+Filesystem canonicalization can read metadata before rejecting a resource.
+
+## Related
+
+- [How a grant decision is made](../concepts/grant-decisions.md): the order
+  the rulesets are consulted in.
+- [Answer permission requests](./answer-permission-requests.md): what to do
+  with the `ask` the policy leaves behind.

package/docs/installation.md

@@ -0,0 +1,115 @@
+---
+title: "Installation"
+description: "Install @smthrs/kernel, its runtime requirements, its public subpaths, and the platform and journal packages a working host composition adds."
+sidebar:
+  order: 1
+---
+
+## Get the package
+
+`@smthrs/kernel` 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 under `packages/`, and depends on it with a workspace specifier:
+
+```json
+{
+  "dependencies": {
+    "@smthrs/kernel": "workspace:*"
+  }
+}
+```
+
+## Requirements
+
+The package requires Node.js 26.4.0 or later and ships as ESM, CommonJS, and
+TypeScript declarations. Its Smithers dependencies install with it:
+[`@smthrs/capability`](/api/capability), [`@smthrs/jj`](/api/jj), and
+[`@smthrs/journal`](/api/journal). The host supplies the exact
+`effect@4.0.0-rc.115` peer so the library never installs a second runtime.
+
+The root entry point carries no Node built-ins. A package test bundles the
+whole root dependency graph for the browser and asserts that no
+`node:child_process`, `node:fs`, `node:path`, or `node:process` import
+survives, so the kernel itself runs anywhere its host does.
+
+## Import forms
+
+The root entry point re-exports every module as a namespace:
+
+```ts
+import { Capability, CapabilitySet, GrantStore, HostServices, Permission, Workspace } from "@smthrs/kernel"
+```
+
+Each module is also importable from its own subpath, which is the form the
+API reference uses:
+
+```ts
+import * as GrantStore from "@smthrs/kernel/GrantStore"
+import * as HostServices from "@smthrs/kernel/HostServices"
+```
+
+`Capability` and `Permission` are re-exports. Their modules live in
+[`@smthrs/capability`](/api/capability), so their deep import paths are
+`@smthrs/capability/Capability` and `@smthrs/capability/Permission`.
+
+Two subpath shapes are blocked in the export map: `@smthrs/kernel/internal/*`
+and `@smthrs/kernel/*/index`. `@smthrs/kernel/package.json` is exported.
+
+## Test subpaths
+
+Two helpers ship for testing. They are published code, not dev-only files;
+`test/HostContract` is an alias for `test/contract`:
+
+| Subpath                              | What it gives you                                                                 | Platform |
+| ------------------------------------ | --------------------------------------------------------------------------------- | -------- |
+| `@smthrs/kernel/test/TestGrantStore` | `layerAllow`, `layerDeny`, and `layerScripted` grant-store doubles.               | any      |
+| `@smthrs/kernel/test/contract`       | `runHostContract`, the shared behavioral contract every host bundle must satisfy. | Node.js  |
+
+`test/contract` is Node-only because it uses Node process and
+temporary-directory fixtures. The deterministic host bundle is published by
+`@smthrs/testing/TestHost`; keeping it with the other test utilities avoids a
+kernel-to-platform dependency cycle. To use that host, add a devDependency
+in the consuming workspace package:
+
+```json
+{
+  "devDependencies": {
+    "@smthrs/testing": "workspace:*"
+  }
+}
+```
+
+`test/contract` registers Vitest cases, so importing it requires the declared
+peers, `@effect/vitest@4.0.0-rc.115` and `vitest@5.0.0`. Both are optional: a
+consumer that imports only the kernel or `test/TestGrantStore` needs neither.
+See [Testing](./testing.md) for what each one covers.
+
+## What a working host adds
+
+The kernel holds no platform implementations. It decorates ports that
+something else provides, so a composition that actually reaches a machine adds
+a platform bundle:
+
+- [`@smthrs/platform-node`](/api/platform-node) implements the five ports on
+  Node, attaches the descriptor-relative filesystem executor the kernel
+  requires, and ships the process reaper that retires orphaned records.
+- [`@smthrs/platform-bun`](/api/platform-bun) and
+  [`@smthrs/platform-browser`](/api/platform-browser) implement the same
+  ports for Bun and for the browser.
+- [`@smthrs/journal`](/api/journal) is already a dependency, but a host only
+  needs a live `Journal` service when it uses `JournalGrantStore` or the
+  durable `ProcessLedger`.
+
+## Next step
+
+Guard a host and watch a call get refused in the
+[Quickstart](./quickstart.md).