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

package/docs/quickstart.md

@@ -0,0 +1,182 @@
+---
+title: "Quickstart"
+description: "Guard a host bundle end to end: refuse an ungranted read with an unattended store, then park the same read on an attended store and answer it."
+sidebar:
+  order: 2
+---
+
+This quickstart guards a host with the capability kernel and runs the same
+filesystem read twice: once against an unattended store, which refuses it, and
+once against an attended store, where you answer the request the read parks
+on. Nothing touches a real machine, so the run is deterministic.
+
+By the end you will have seen the two shapes every kernel refusal takes: the
+typed `PermissionRequired` that an unattended host reports, and the parked
+request an operator resolves.
+
+## Prerequisites
+
+- Node.js 26.4.0 or later.
+- A package that depends on `@smthrs/kernel` and has
+  `"@smthrs/testing": "workspace:*"` in devDependencies. See
+  [Installation](./installation.md) for how to get them.
+- A test runner, for the second half:
+
+```bash
+pnpm add -D @effect/vitest@4.0.0-rc.115 vitest@5.0.0
+```
+
+## Build the raw host
+
+The kernel decorates ports; something else has to provide them.
+`@smthrs/testing/TestHost` is the deterministic bundle: an in-memory
+filesystem, a scripted interpreter, `TestClock`, and a seeded PRNG. `Workspace`
+names the root that filesystem capability resources are resolved against.
+
+Create `quickstart.test.ts`. Vitest only discovers files matching
+`**/*.{test,spec}.?(c|m)[jt]s?(x)`, so the name is what makes the example
+runnable:
+
+```ts
+import { GrantStore, HostServices, Permission, Workspace } from "@smthrs/kernel"
+import * as TestHost from "@smthrs/testing/TestHost"
+import { Effect, Fiber, FileSystem, Layer, Option, type PlatformError } from "effect"
+
+/** The unguarded platform bundle plus the workspace root. */
+const raw = Layer.mergeAll(
+  TestHost.layer({ files: { "/workspace/README.md": "# hello" } }),
+  Workspace.layer("/workspace")
+)
+```
+
+## Refuse a read with no policy
+
+`GrantStore.layer({ attended: false })` builds a store with no rules and
+nobody to ask. `HostServices.layer` composed over the raw bundle replaces all
+five tags with their guarded implementations:
+
+```ts
+const unattended = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  const failure = yield* Effect.flip(fs.readFileString("/workspace/README.md"))
+  return Option.getOrThrow(
+    Permission.fromPlatformError(failure as PlatformError.PlatformError)
+  )
+}).pipe(
+  Effect.provide(HostServices.layer),
+  Effect.provide(Layer.orDie(GrantStore.layer({ attended: false }))),
+  Effect.provide(raw),
+  Effect.scoped
+)
+```
+
+The program calls Effect's own `readFileString`. It never mentions permission,
+and it is refused anyway, which is the point of decorating in place. Effect
+fixes that method's error channel to `PlatformError`, so the kernel projects
+its failure into one and keeps the structured original on the cause;
+`Permission.fromPlatformError` reads it back:
+
+```text
+{
+  _tag: '@smthrs/capability/PermissionRequired',
+  code: 'permission_required',
+  requestId: 'permission-1',
+  capability: { action: 'fs:read', resource: '/workspace/README.md' },
+  tier: 'sealed',
+  meta: {}
+}
+```
+
+`permission_required`, not `permission_denied`. No rule matched, so the
+decision was `ask`, and an unattended store turns `ask` into a refusal that
+names what it would have asked for. A `deny` would have produced
+`permission_denied` instead. The `tier` is `sealed` because re-running a read
+costs nothing; see [effect tiers](/pkg/capability/concepts/effect-tiers).
+
+## Answer the request instead
+
+An attended store parks the asking fiber on a request and waits. Build the
+store with `GrantStore.make` so you hold the service directly, fork the read,
+read the pending request, and reply:
+
+```ts
+const attended = Effect.gen(function*() {
+  const store = yield* GrantStore.make({ runId: "quickstart" })
+
+  /** Polls until the forked read has parked. A real host waits on its own UI. */
+  const pending = (): Effect.Effect<GrantStore.PendingRequest> =>
+    Effect.flatMap(store.list, (requests) =>
+      requests[0] === undefined
+        ? Effect.andThen(Effect.yieldNow, pending())
+        : Effect.succeed(requests[0]))
+
+  return yield* Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const reading = yield* Effect.forkChild(fs.readFileString("/workspace/README.md"), {
+      startImmediately: true
+    })
+
+    const request = yield* pending()
+    // request.capability is { action: "fs:read", resource: "/workspace/README.md" }
+    yield* store.reply(request.requestId, "once")
+
+    return yield* Fiber.join(reading)
+  }).pipe(
+    Effect.provide(HostServices.layer),
+    Effect.provideService(GrantStore.GrantStore, store)
+  )
+}).pipe(Effect.scoped, Effect.provide(raw))
+```
+
+`Fiber.join(reading)` answers `"# hello"`. The read did not fail and retry: it
+suspended inside the decorator, and the reply woke it up to finish the
+operation it was authorized for. `"once"` authorizes this request alone. The
+other resolutions, `"run"`, `"remembered"`, and `"deny"`, are covered in
+[Answer permission requests](./guides/answer-permission-requests.md).
+
+## Run it
+
+Append the assertions to `quickstart.test.ts`, below both programs:
+
+```ts
+import { describe, expect, it } from "@effect/vitest"
+
+describe("quickstart", () => {
+  it.effect("refuses an ungranted read", () =>
+    Effect.gen(function*() {
+      expect((yield* unattended).code).toBe("permission_required")
+    }))
+
+  it.effect("resumes a read the operator allows", () =>
+    Effect.gen(function*() {
+      expect(yield* attended).toBe("# hello")
+    }))
+})
+```
+
+```bash
+pnpm vitest run quickstart.test.ts
+```
+
+## What just happened
+
+`HostServices.layer` is five middleware layers merged. Each one requires the
+tag it also provides, so composing it over a platform bundle shadows the raw
+implementations for everything downstream. Before delegating, the filesystem
+decorator resolved `/workspace/README.md` to a canonical resource, built the
+capability `fs:read` on it, and handed it to the store. The store found no
+matching rule, defaulted to `ask`, and either refused or parked depending on
+whether anybody was there to answer.
+
+Nothing in either program held an unguarded `FileSystem`. That is the whole
+design: there is no second, protected tag to reach for, so there is no
+unguarded one to hold.
+
+## Next steps
+
+- [Write a capability policy](./guides/write-a-capability-policy.md): rules
+  that answer `allow` before anyone is asked.
+- [Guard a host bundle](./guides/guard-a-host-bundle.md): the same composition
+  over a real platform.
+- [How a grant decision is made](./concepts/grant-decisions.md): the ceiling,
+  the four rulesets, and the order they are consulted in.

package/docs/testing.md

@@ -0,0 +1,108 @@
+---
+title: "Testing"
+description: "Test guarded hosts with the kernel grant-store doubles, the shared host contract suite, and the deterministic host from @smthrs/testing."
+---
+
+The kernel ships two public test helpers: `test/TestGrantStore` and
+`test/contract` (also exported as `test/HostContract`). They are published code,
+so consumers can use the same doubles and host contract as the package tests.
+
+## Run the kernel suite
+
+From the repository root, run `pnpm --dir packages/smithers/flows/kernel exec vitest run`.
+The same command runs in the independent Windows kernel job, with the package's
+coverage thresholds enforced.
+
+## Pick a grant-store double
+
+`@smthrs/kernel/test/TestGrantStore` gives you three layers, and none of them
+needs a `Workspace`:
+
+```ts
+import * as TestGrantStore from "@smthrs/kernel/test/TestGrantStore"
+
+TestGrantStore.layerAllow // every check passes
+TestGrantStore.layerDeny("denied by test") // every check fails permission_denied
+TestGrantStore.layerScripted(["once", "deny"]) // a deterministic sequence
+```
+
+`layerScripted` consumes one reply per check, in order. `once`, `run`, and
+`remembered` allow the check; `deny` rejects it; exhausting the script rejects
+every further check with the reason
+`"permission reply script exhausted"`. Use it to assert **which** operations a
+subject attempts and in what order, which a blanket allow or deny cannot show.
+
+For a test about policy rather than about the subject, build a real store with
+`GrantStore.layer({ attended: false, rules })` instead. It exercises the actual
+evaluation path, and it needs a `Workspace`.
+
+## Run against the deterministic host
+
+Add `"@smthrs/testing": "workspace:*"` to the consuming package's
+devDependencies in the checkout. See [Installation](./installation.md).
+
+`@smthrs/testing/TestHost` is the whole host surface with every source of
+nondeterminism pinned: a `Map`-backed filesystem, a scripted interpreter,
+`TestClock` so time moves only when a test moves it, and a seeded PRNG.
+
+```ts
+import * as TestHost from "@smthrs/testing/TestHost"
+
+const host = TestHost.layer({
+  files: { "/workspace/README.md": "# hello" },
+  commands: { "npm test": { stdout: "1 passing\n", exitCode: 0 } },
+  seed: 42
+})
+```
+
+`TestHost.TestHost` is the zero-config bundle: empty filesystem, no scripted
+commands, seed 42.
+
+Three details are worth knowing. The filesystem is the very same
+`BrowserFileSystem` adapter the browser runs, over a `Map`-backed volume, so a
+bug in the adapter shows up in tests instead of hiding behind a second
+implementation. The spawner is provided **over** the filesystem and path
+layers, exactly as `NodeChildProcessSpawner` is, so the interpreter and the
+`FileSystem` service agree about what exists. And a command that is not in
+`commands` fails the way a real shell reports a missing binary, so a test
+cannot accidentally depend on a host tool being installed.
+
+`Jj` is [`@smthrs/jj`](/api/jj)'s `layerUnsupported`, whose every operation
+fails with `not_installed`, so a test that reaches for the repository fails
+loudly rather than touching the real machine. `HttpClient` is
+`HttpClient.layerNoop`, which reports the absent host as a `TransportError`.
+
+The module is Node-only: `effect/testing`'s `TestClock` reaches for
+`node:assert`.
+
+## Run the shared host contract
+
+`@smthrs/kernel/test/contract` exports `runHostContract`, the behavioral
+contract every host bundle must satisfy: the complete filesystem, process, Jj,
+and HTTP capability matrices, including observable process liveness and
+multi-leg pipelines. The Node, Bun, browser, test, and deliberately
+unsupported bundles all run it.
+
+It registers Vitest cases, so it requires the declared peers
+(`@effect/vitest@4.0.0-rc.115` and `vitest@5.0.0`) and Node process and
+temporary-directory fixtures. See
+[Adapt a new host platform](./guides/adapt-a-new-host-platform.md) for how to
+declare your bundle's capabilities to it.
+
+## What the package already proves
+
+The kernel's own suite covers capability-set intersection and equality;
+bounded, immutable grant state; journal replay and its envelope limits;
+canonical filesystem resources and descriptor identity; command snapshots;
+process containment and ledger recovery; HTTP method, origin, and redirect
+authorization; Jujutsu resources; browser-safe imports; and every supported and
+refused host operation.
+
+If you are testing a subject that reaches the host, you rarely need to re-prove
+any of that. Test what your subject does with the refusal.
+
+## Related
+
+- [Quickstart](./quickstart.md): the doubles in a working composition.
+- [Handle a permission failure](/pkg/capability/guides/handle-a-permission-failure):
+  reading the typed error a refusal carries.

package/docs/troubleshooting.md

@@ -0,0 +1,281 @@
+---
+title: "Troubleshooting"
+description: "The refusals @smthrs/kernel produces, what each one means, and what to change: policy misses, ceiling denials, filesystem confinement, grant replies, journal replay, and composition errors."
+---
+
+Every refusal this package produces is typed and carries a stable code. Find
+the message or the code and read the matching section.
+
+Where Effect owns the tag, the failure arrives projected. Read it back first:
+
+```ts
+import { HttpClient, Permission } from "@smthrs/kernel"
+import { Option } from "effect"
+
+// FileSystem and ChildProcessSpawner failures.
+Option.getOrThrow(Permission.fromPlatformError(failure))
+// HttpClient failures.
+Option.getOrThrow(HttpClient.fromHttpClientError(failure))
+```
+
+`Jj` names `Permission.PermissionError` in its own channel, so there is
+nothing to unwrap.
+
+## permission_required
+
+**What happened.** No rule matched the capability, so the decision defaulted to
+`ask`, and the store is unattended. The failure names the request id, the
+capability, its effect tier, and the display metadata.
+
+**What to change.** Add an allow rule for the capability, or run an attended
+store so an operator can answer. This is the expected refusal for a headless
+host meeting an operation nobody authorized; it is not a bug in the caller.
+
+## permission_denied: denied by permission policy
+
+**What happened.** A rule matched and denied it. Rules are last-match-wins
+across the four rulesets, and an effective denial in the **configured** ruleset
+is a hard veto no envelope, run grant, or remembered grant can lift.
+
+**What to change.** If the denial is in the configured policy and intended,
+nothing: that is the veto working. If it is not intended, add a later allow in
+the same configured ruleset, since a configured deny superseded within its own
+ruleset is not a veto.
+
+## permission_denied: outside capability ceiling
+
+**What happened.** The fiber passed through `CapabilitySet.attenuate` and the
+capability is outside the resulting ceiling. This is checked before any rule,
+so no policy and no operator reply can override it.
+
+**What to change.** Widen the group you passed to `attenuate`, or do the work
+outside the attenuated scope. There is no public widening operation by design:
+authority only narrows.
+
+## permission_denied: grant store closed, and store_closed
+
+**What happened.** The store's scope closed. A request that was parked at that
+moment fails with `permission_denied` and `"grant store closed"`; a call made
+afterwards fails with the `GrantStoreError` code `store_closed`.
+
+**What to change.** Keep the store's scope open for as long as the work that
+uses it. A store built inside `Effect.scoped` around a short program, while the
+guarded host outlives it, produces exactly this.
+
+## permission_denied: host does not provide descriptor-relative, no-follow filesystem isolation
+
+**What happened.** The filesystem in the composition carries neither
+confinement extension, so every path, directory, stream, glob, and handle
+operation fails closed.
+
+**What to change.** A native adapter attaches
+`FileSystem.withAtomicFileSystem` with operations rooted at a pinned
+descriptor. A volume that genuinely cannot address the host filesystem attests
+with `FileSystem.withIsolatedFileSystem`. Attaching neither is not a
+configuration to relax; the check exists because a path-delegating filesystem
+cannot be confined. See
+[Filesystem confinement](./concepts/filesystem-confinement.md).
+
+If the failure names `../<system-temp>`, the operation was
+`makeTempDirectory`, `makeTempFile`, or one of their scoped forms: they name no
+directory, so the kernel authorizes the system temporary directory sentinel.
+
+## permission_denied: hard-linked files cannot be confined to the workspace
+
+**What happened.** The target is a regular file with more than one link. A hard
+link is a second name for the same inode with no ancestry to check, so there is
+no canonical resource to authorize.
+
+**What to change.** Copy the file rather than hard-linking it, or operate on it
+outside the guarded surface. This refusal is always on and there is no option
+to disable it.
+
+## permission_denied: path no longer names the resource that was authorized
+
+**What happened.** The grant decision suspended (an attended request, or a
+journal write), and when it came back the path resolved to something else. A
+symlink or a rename swapped in during the wait.
+
+**What to change.** Usually nothing in the caller: this is the protection
+working. If it fires without an adversary, something else is rewriting the tree
+concurrently, most often a build or a watcher touching the same paths.
+
+## permission_denied: descriptor no longer names the resource at its authorized path
+
+**What happened.** An open handle's `device:inode` identity, captured at open
+time, no longer matches what the authorized path names. After a rename the
+descriptor can address an inode outside the workspace even when the replacement
+path is still allowed.
+
+**What to change.** Reopen the file. Holding a handle across a rename is what
+produces this.
+
+## Throw: filesystem already carries a descriptor-relative executor
+
+**What happened.** `withIsolatedFileSystem` was called on a filesystem that
+already carries a descriptor-relative executor. The refusal is a throw at
+composition time, so a host cannot be assembled that way.
+
+**What to change.** Do not attest whole-volume isolation over a native host.
+The executor is the stronger guarantee, and replacing it with a path-delegating
+attestation reopens the symlink-swap window. If you meant to layer over the
+existing executor, read it first and delegate to it; that replacement is your
+own decision and is allowed.
+
+## invalid_resolution: run grants require a plan digest
+
+**What happened.** A `"run"` reply arrived on a store built without
+`planDigest`. A run grant is bound to the exact active plan, and there is
+nothing to bind it to.
+
+**What to change.** Pass `planDigest` when building the store, or reply `once`
+or `remembered` instead.
+
+## invalid_resolution: grant pattern exceeds the requested authority
+
+**What happened.** The pattern supplied to `reply` names a different action,
+reaches a more dangerous effect tier than the request displayed, or is a
+wildcard-bearing pattern identical to the resource. The last case is refused
+because the grammar has no escape, so the pattern's wildcard reading would
+silently widen access.
+
+**What to change.** Supply a pattern within the request's own action and tier,
+or omit it and let the exact capability derive one.
+
+## invalid_resolution: the requested resource contains glob metacharacters
+
+**What happened.** A `"run"` or `"remembered"` reply with no explicit pattern,
+for a resource containing `*` or `?`. There is no unambiguous pattern to
+derive.
+
+**What to change.** Supply an explicit pattern, as the message says, or resolve
+`once`.
+
+## request_not_found
+
+**What happened.** No parked request has that id. It was already answered, the
+asking fiber was interrupted, or the store was rebuilt.
+
+**What to change.** Re-read `store.list` before replying. Reply ids are only
+valid for the store instance that issued them.
+
+## invalid_resolution: rules exceed 1024 entries
+
+**What happened.** A bound was reached. One store retains at most 1,024 rules
+across all four rulesets, 1,024 envelope signatures, 256 patterns per
+envelope, and 1,024 parked requests. Every bound failure happens **before**
+any state or journal authority changes.
+
+**What to change.** Narrow the policy: one broad pattern replaces many exact
+ones. If the count is coming from replay, the message from
+`JournalGrantStore` names the policy run and the counts, and the fix is to
+start a new `policyRunId`. Do not compact the policy run: replay never reads a
+checkpoint, so compaction makes every later construction fail. Check against
+the exported constants (`GrantStore.maximumRules` and its siblings) rather
+than hardcoding numbers.
+
+## journal_failed
+
+**What happened.** `JournalGrantStore` could not persist a decision, or could
+not replay history. The decision is **not** activated: a permission that could
+not be written down was not granted.
+
+**What to change.** Fix the journal (space, permissions, connectivity). Check
+that a `SqlJournal` uses the `reject` overflow policy: a dropped grant decision
+cannot safely be treated as persisted, so drop-capable policies are
+unsupported.
+
+## invalid_resolution: non-advancing journal page
+
+**What happened.** A journal page did not advance past the cursor it was asked
+for. Following it would replay the same events forever; accepting it would
+double-apply them, so construction is refused. The message names the run
+(`policyRunId` or `runId`) whose page failed to advance, and the sequence.
+
+**What to change.** This is corrupt journal output, not a policy problem.
+Investigate the journal implementation or the store beneath it.
+
+## invalid_resolution: run-scoped event found in policy journal
+
+**What happened.** Replay found an event in the wrong run: a run-scoped event
+in the policy run, or a remembered event in the operational run. The sibling
+failures are `"grant payload run mismatch"`, `"invalid grant payload"`,
+`"grant envelope/payload type mismatch"`, and the `"unsafe ... event"`
+refusals. Sequences are per run and the store replays two runs, so every one
+of these names the run it was replaying and the sequence within it, for
+example `invalid grant payload in run kernel-policy at journal sequence 7`.
+That row is the one to inspect.
+
+**What to change.** Check that `runId`, `policyRunId`, and `sourceId` are the
+ones this store has always used. Reusing an operational run id as a policy run
+id, or writing kernel event types from another producer under the same source
+id, produces exactly this.
+
+## invalid_resolution: runId and policyRunId must be distinct
+
+**What happened.** `JournalGrantStore` was given the same id for both. Run
+grants and remembered grants must live in separate runs, because remembered
+policy has to outlive any single run.
+
+**What to change.** Keep `policyRunId` stable across every run and give each
+operational run its own `runId`.
+
+## permission_denied: HTTP capability checks require an absolute, parseable URL
+
+**What happened.** The request URL did not parse as an absolute URL, so there
+is no host to name as a resource.
+
+**What to change.** Build requests with an absolute URL. A relative path
+resolved by a base elsewhere never reaches the decorator as one.
+
+## A grant for a host does not cover http:// to that host
+
+**What happened.** This is the design, not a bug. `https` is the implicit
+scheme: an `https:` URL names the bare lowercased host, and every other scheme
+names `<scheme>//<host>`. A grant for `api.example.test` therefore never
+authorizes `http://api.example.test`.
+
+**What to change.** Use `https`, or write the cleartext resource explicitly in
+the rule if a downgrade is genuinely intended.
+
+## Snapshot refusals
+
+Three failures mean a caller handed in something that could still change after
+the capability was checked:
+
+- `"filesystem options must contain only data properties"`: an options object
+  carrying a getter rather than plain data.
+- `"HTTP request must be an immutable supported request description"`: a
+  request body that is neither immutable nor copyable.
+- `"command must be an immutable supported process description"`, a
+  `PlatformError` with reason `InvalidData`: a command that could not be
+  snapshotted.
+
+**What to change.** Pass plain data. The snapshot exists so the operation
+executed after a grant arrives is the operation that was authorized.
+
+## NotFound: no process host for `<command>`
+
+**What happened.** The composition has `ChildProcessSpawner.layerNoop()`, the
+stub for a host that cannot start processes. The matching HTTP stub reports
+`"HTTP is unavailable on this host"` as a `TransportError`.
+
+**What to change.** Provide a real platform bundle. `TestHost` composes the
+HTTP stub deliberately, so a test that expected a network call will see this.
+
+## A spawn fails and no process is running
+
+**What happened.** The spawn's durable `ProcessLedger` record failed to commit.
+The child was signalled, the call failed, and no pid was left in
+`ProcessLedger.live`.
+
+**What to change.** Fix the journal. Do not catch this failure and proceed: a
+child no incarnation of the host can discover is the one outcome containment
+exists to prevent.
+
+## Related
+
+- [Handle a permission failure](/pkg/capability/guides/handle-a-permission-failure):
+  the error shapes themselves.
+- [How a grant decision is made](./concepts/grant-decisions.md): the order that
+  produces each of these.