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

package/docs/concepts/decoration-in-place.md

@@ -0,0 +1,117 @@
+---
+title: "Decoration in place"
+description: "Why the kernel guards the platform's own service tags instead of publishing protected copies: the closed port list, what each slot's error channel becomes, and what is deliberately not on the list."
+sidebar:
+  order: 1
+---
+
+A capability kernel has to answer one question before anything else: how does
+a caller get the guarded service rather than the raw one? The usual answer is
+a second tag. The platform provides `FileSystem`, the kernel provides
+`ProtectedFileSystem`, and every consumer is told to ask for the second. That
+answer fails the moment a dependency does not know about the kernel, and it
+leaves two tag lists to keep in sync.
+
+The kernel does the opposite. Each guarded implementation is a middleware
+`Layer` over the very tag the platform adapter provides: it requires
+`FileSystem` and it provides `FileSystem`. Composed over a host bundle, the
+guarded implementation shadows the raw one for everything downstream. A
+library that has never heard of Smithers is guarded because there is nothing
+else for it to resolve.
+
+```text
+raw platform service
+        |
+kernel decorator -> GrantStore
+        |
+flow-visible service
+```
+
+`HostServices.layer` is those five middleware layers merged, so one
+composition guards the whole surface at once.
+
+## The closed list
+
+Five tags, and everything that touches the outside world enters through one of
+them:
+
+| Slot       | Tag                   | Owner                   | Actions checked                                                                                                                         |
+| ---------- | --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Filesystem | `FileSystem`          | Effect                  | `fs:read`, `fs:write`                                                                                                                   |
+| Paths      | `Path`                | Effect                  | none, by decision                                                                                                                       |
+| Processes  | `ChildProcessSpawner` | Effect                  | `proc:spawn`                                                                                                                            |
+| Repository | `Jj`                  | [`@smthrs/jj`](/api/jj) | `jj:status`, `jj:diff`, `jj:snapshot`, `jj:restore`, `jj:workspace-add`, `jj:workspace-forget`, `jj:root`, `jj:revert`, `jj:op-restore` |
+| Network    | `HttpClient`          | Effect                  | `net:get`, `net:post`, `model:call`                                                                                                     |
+
+`HostServices.HostServiceTags` is that list as values and
+`HostServices.HostServiceIds` is the matching stable id per slot
+(`"effect/FileSystem"`, `"effect/Path"`,
+`"effect/process/ChildProcessSpawner"`, `"@smthrs/jj/Jj"`,
+`"effect/HttpClient"`).
+
+Two things depend on the list being closed. A service that is not on it cannot
+be attenuated, denied, or audited, so it must not exist. And the list is part
+of what a durable run records about itself: [`@smthrs/engine`](/api/engine)
+folds the implementations that were in scope into the identity of every step it
+caches, so a replay under a different set of them is a different step rather
+than a silent substitution. The slot ids are durable for that reason too, and
+change only when the service behind a slot changes.
+
+## Four of the five tags are Effect's
+
+Smithers supplies implementations of Effect's `FileSystem`, `Path`,
+`ChildProcessSpawner`, and `HttpClient` rather than wrappers around them. That
+choice decides where a refusal surfaces.
+
+Where Effect owns the tag, the error channel stays Effect's own, and the
+kernel projects its failure into it:
+
+- `FileSystem` and `ChildProcessSpawner` refusals become a `PlatformError`
+  whose reason is `PermissionDenied`, carrying the structured kernel failure
+  on `cause`. `Permission.fromPlatformError` reads it back.
+- `HttpClient` refusals become an `HttpClientError` whose reason is a
+  `TransportError`, again carrying the kernel failure.
+  `HttpClient.fromHttpClientError` reads it back.
+
+Where Smithers owns the service, the interface names the failure directly:
+`Jj` fails with `JjError | PermissionError`, and nothing has to be projected
+or read back.
+
+The asymmetry is not an accident. Widening Effect's error channels would mean
+forking Effect's service interfaces; hiding the kernel failure inside an
+opaque platform error would mean losing the capability, the reason, and the
+stable code. Projection with the original on the cause keeps both.
+
+## What is not on the list
+
+**`Path` is on the list and checks nothing.** It is pure string manipulation:
+`path.resolve` reads no directory and creates no file, so there is no
+authority to guard. The slot exists as an explicit decision rather than an
+omission. `Path.layer` resolves relative paths against `Workspace.root`, the
+directory `ChildProcessSpawner.layer` runs a command in when it names no
+`cwd`, so neither depends on the process's own directory.
+
+**`Clock` and `Random` are Effect core built-ins.** They are already
+port-shaped and already swappable with `Effect.provideService`, and neither
+carries host authority, so they are not the kernel's to define or decorate.
+
+**There is no Smithers transport port.** Network access is Effect's
+`HttpClient` and the kernel decorates it. A raw Smithers transport beneath it
+would be a second way to reach the network whose contract never mentions
+permission, which is exactly the hole this design closes.
+
+## What decoration cannot see
+
+The kernel checks capabilities at adapter call sites. It does not sandbox the
+operating system. Code that imports `node:fs` directly, or a native addon that
+opens a socket, never passes through a decorated service and is not observed.
+That is a real boundary, not a caveat to bury: confinement against untrusted
+code requires an operating-system sandbox as well, and hermetic execution
+requires a `StepBoundary` from [`@smthrs/engine`](/api/engine).
+
+## Related
+
+- [How a grant decision is made](./grant-decisions.md): what happens inside
+  the check each decorator performs.
+- [Guard a host bundle](../guides/guard-a-host-bundle.md): the composition,
+  in order, with the layers a real host adds.

package/docs/concepts/filesystem-batches.md

@@ -0,0 +1,58 @@
+---
+title: "Bounded filesystem batches"
+description: "Optional read batches on the guarded filesystem, with per-path grants, root identity, explicit failures, and portable fallback."
+---
+
+`FileSystem.batch(fs)` from `@smthrs/kernel/FileSystem` discovers an optional
+capability on the existing Effect filesystem service. It adds no host slot and
+changes no persisted host identity. A native adapter advertises `batchLimits`
+on its descriptor-relative executor. The kernel exposes the guarded capability
+after binding the workspace root; callers never receive the raw executor.
+
+```ts
+const batch = FileSystem.batch(fs)
+if (batch !== undefined) {
+  const response = yield * batch.execute([
+    { operation: "stat", path: "src/a.ts" },
+    { operation: "digest", path: "src/b.ts" },
+    { operation: "readDirectory", path: "src" }
+  ])
+}
+```
+
+A batch accepts 1 through `maxSize` requests, with a hard maximum of 128.
+`maxResponseBytes` bounds the aggregate encoded answer. Inputs are copied
+before asynchronous root or permission checks. Every member gets the same
+canonical `fs:read` check and post-grant re-resolution as an individual call.
+Each grant or quota refusal remains an explicit per-path `Result` carrying its
+original `PlatformError`. A batch with no admitted members starts no helper.
+
+Each response carries `rootIdentity`, the root device/inode checked by the
+executor. Members retain their original request `index` and normalized `path`,
+and sort by path and then index. Successful values discriminate `stat`,
+`readDirectory`, `glob`, and `digest`. A digest contains 64 lowercase SHA-256
+hex digits, its byte count, and bytes only when requested with `content: true`.
+Missing paths report `NotFound`; they are not silently dropped. The engine
+decides where absence means an empty expansion or an absent digest.
+
+Root loss or replacement refuses the entire operation. Helper failure,
+cancellation, deadline, malformed framing, and aggregate quota exhaustion also
+produce no partial batch. Ordinary path failures appear individually so an
+unrelated authorized path can still be measured. A batch is not a transaction
+or an assertion that the workspace was frozen.
+
+When the workspace root is a symlink, its logical path must still resolve to
+the captured root inode before and after grants. Retargeting the alias refuses
+the batch even if the original canonical directory still exists. The helper
+independently verifies that canonical directory against the same inode.
+
+Hosts may omit the capability. The engine then uses the existing guarded
+operations with at most four operations in flight. Isolated test/browser
+volumes keep their existing attestation; optional batching does not weaken it.
+The shared HostContract exercises each adapter that advertises batching, while
+the Node conformance tests additionally exercise the confined helper's fault
+and resource boundaries.
+
+Host glob grammar remains host-specific. Declared engine globs continue to use
+the plan's matcher, including dotfiles and its metadata-directory pruning, over
+batched directory/stat operations.

package/docs/concepts/filesystem-confinement.md

@@ -0,0 +1,168 @@
+---
+title: "Filesystem confinement"
+description: "Why authorizing a pathname is not enough: canonical resources, the re-resolution after a suspended grant, descriptor identity, and the two host extensions that make confinement enforceable."
+sidebar:
+  order: 3
+---
+
+Guarding a filesystem is harder than guarding a process, because a path is not
+a thing. It is a name that something else can rebind between the moment you
+authorize it and the moment the host acts on it. The naive decorator, check
+the pathname and then hand the same pathname to the host, is vulnerable to a
+symlink swap: authorize `/workspace/notes.txt`, and by the time the host
+resolves it the name points at `/etc/shadow`.
+
+Everything in this page exists to close that window.
+
+## The capability resource is canonical, not literal
+
+`FileSystem.canonicalResource(fileSystem, path, workspaceRoot, value)` is what
+turns a caller's string into the resource a capability names. It resolves the
+path through every existing ancestor, so an existing symlink cannot turn an
+inside-workspace grant into outside authority. Then it maps a canonical path
+that lands inside the workspace back to the stable logical workspace root, so
+capability resources stay readable and stable even when the root itself is a
+symlink. A relative path is resolved against the workspace root first.
+
+Every host, including a descriptor-relative executor, resolves existing
+components to their on-disk spelling before and after a grant decision.
+On a case-insensitive volume, `.ENV` therefore names `.env` for permission
+checks, and `REPORTDIR/new.txt` names `ReportDir/new.txt` when `ReportDir`
+already exists. Missing components retain their requested spelling. A
+path-based host must implement `realPath` with canonical on-disk spelling. The
+capability matcher remains case-sensitive so distinct files on case-sensitive
+volumes keep distinct permissions.
+
+Native guarded operations on outside-pointing symlinks fail with
+`PermissionDenied`, including `readLink`, `stat`, `exists`, and `remove`.
+Authorization for a descriptor-relative executor never resolves a pathname on
+the host. This matters on Windows, where `realpath` opens its argument through
+links: one call on a link to `\\.\pipe\name` or `\\host\share` connects to
+that pipe or share. Instead the executor answers one `resolve` request from the
+pinned root. It walks without following any link, junction, or mount point,
+and answers the on-disk spelling of existing components, or the first link on
+the way with its text. Link text is resolved lexically and asked again, so a
+component swapped for a link between two checks is seen as that link. A
+reparse point the executor cannot translate, such as a volume mount point, is
+refused without being traversed.
+
+Each guarded operation asks the executor to resolve its path before and after
+the grant decision, and then runs the operation itself. A guarded batch asks
+once for all of its members before the grants, once after them, and then runs
+the batch.
+
+Capability resources are native paths, and patterns match them as text. On
+Windows, write filesystem patterns with the native separator, such as
+`fs:read:C:\work\**`. The pattern `fs:read:C:\work/**` selects nothing.
+
+Resolution also applies one always-on refusal: a regular file with more than
+one link fails with `"hard-linked files cannot be confined to the workspace"`.
+A hard link is a second name for the same inode with no ancestry to check, so
+there is no canonical answer to give.
+
+## The path is resolved twice
+
+A grant decision can suspend. An attended request waits for a person; a
+journal-backed store waits for a write. What was authorized is the resource
+the path named at check time, so the path must still name it when the decision
+comes back.
+
+The guard therefore resolves the resource, checks the capability, and resolves
+it **again**. If the second answer differs, the operation fails with
+`"path no longer names the resource that was authorized"`. A symlink or rename
+swapped in during the wait is refused, never followed.
+
+## An open handle is bound to an inode
+
+Rechecking a pathname is not enough once a file is open. The pathname could be
+re-authorized while the descriptor you hold names something else: after a
+rename that descriptor can address an inode outside the workspace even though
+the replacement path is still allowed.
+
+So an open handle binds authorization to the descriptor's `device:inode`
+identity, captured at open time, and every guarded handle operation
+(`read`, `write`, `stat`, `truncate`, `sync`, and the `*All` and `*Alloc`
+forms) rechecks that identity as well as the capability. A mismatch fails with
+`"descriptor no longer names the resource at its authorized path"`.
+
+Open flags decide which capabilities the open itself requires. A read-only
+flag needs `fs:read`, a write flag needs `fs:write`, and a read-write flag
+needs both.
+
+A host that reports no inode identity is an isolated volume. Its attestation,
+not inode evidence, is the boundary, so there is nothing to verify and the
+recheck passes.
+
+## Two ways a host earns the filesystem
+
+The kernel refuses to delegate a checked pathname to a path-based host. A
+platform adapter has to provide one of two extensions, and a host that
+provides neither fails **every** relevant path, directory, stream, glob, and
+handle operation closed with
+`"host does not provide descriptor-relative, no-follow filesystem isolation"`.
+
+**`withAtomicFileSystem(fileSystem, atomic)`** attaches a descriptor-relative,
+no-follow executor. Operations are expressed as an `AtomicRequest` and run
+relative to a pinned root handle, so there is no pathname for anything to
+rebind between the check and the act. This is what a native host uses;
+[`@smthrs/platform-node`](/api/platform-node) attaches it.
+
+**`withIsolatedFileSystem(fileSystem)`** attests that the whole volume is
+already confined by an enforceable boundary, which is true of an in-memory
+browser volume or a test double that cannot address the host filesystem at
+all. Path delegation is safe there because there is no host filesystem to
+reach.
+
+Both decorate the supplied service object in place and return that same
+identity, so a host attaches exactly once at its boundary and keeps no
+undecorated alias.
+
+`withIsolatedFileSystem` **throws** on a filesystem that already carries a
+descriptor-relative executor. The executor is the stronger guarantee, and
+replacing it with a path-delegating attestation would route `access`, `copy`,
+`chmod`, `link`, `symlink`, `open`, `watch`, `sink`, `stream`, and every
+`makeTemp*` call back through pathnames after the capability check: the exact
+window the extension closes. The refusal is a throw at composition time, so a
+host cannot be assembled that way. Layering over an executor a caller has read
+and delegates to is still allowed, because that replacement is the caller's
+own decision.
+
+## Engine machinery uses a confined view
+
+The engine's own copy-back writes files a body produced; asking a grant store
+for them would make the engine ask permission for its own bookkeeping. It still
+must not follow a symlink a concurrent process swapped into the workspace.
+`confined(fileSystem, root)` gives it the same descriptor-relative requests the
+guarded layer sends, pinned to `root`, with no grant check. A path-based host
+gets no such view: `confined` refuses it rather than fall back to a
+check-then-write that a swap could beat.
+
+## Temporary directories are outside the workspace
+
+`makeTempDirectory`, `makeTempDirectoryScoped`, `makeTempFile`, and
+`makeTempFileScoped` name no directory of their own. An implicit one is
+authorized as `fs:write` on
+`path.resolve(workspace.root, "..", FileSystem.systemTemporaryDirectoryName)`,
+where the sentinel is the literal string `"<system-temp>"`.
+
+The sentinel is outside the workspace root by construction and is never
+confusable with a real path, so granting an ordinary workspace write does not
+grant system temporary-directory access. A host missing the required extension
+reports the refusal against the logical input `../<system-temp>`.
+
+## Mutable inputs are snapshotted
+
+An options record a caller still holds is a second way to change an operation
+after it was authorized. The guarded filesystem snapshots option records,
+nested arrays, and maps before any permission suspension, freezing what it
+copies, so the operation executed after a grant arrives is the operation that
+was approved. An options object carrying a getter rather than plain data
+fails with `"filesystem options must contain only data properties"`, because a
+getter is not something a snapshot can capture.
+
+## Related
+
+- [Adapt a new host platform](../guides/adapt-a-new-host-platform.md):
+  attaching an extension and proving it with the contract suite.
+- [How a grant decision is made](./grant-decisions.md): what happens between
+  the two resolutions.

package/docs/concepts/grant-decisions.md

@@ -0,0 +1,181 @@
+---
+title: "How a grant decision is made"
+description: "The order GrantStore.check consults authority in: the fiber ceiling, four rulesets under last-match-wins, the ask default, and what an attended and an unattended store each do with ask."
+sidebar:
+  order: 2
+---
+
+Every decorated host operation ends in one call: `grants.check(capability)`.
+That call either returns void, in which case the operation proceeds, or fails
+with a typed permission error. Everything the kernel decides happens inside
+it, in a fixed order.
+
+## The order of the check
+
+1. **Is the store open?** A closed store fails every check with
+   `store_closed`. Closing a store also rejects every request already parked
+   on it, so no waiter is stranded.
+2. **Is the capability inside the fiber's ceiling?** `CapabilitySet` is the
+   ambient authority of the current fiber. A capability outside it fails
+   immediately with `permission_denied` and the reason
+   `"outside capability ceiling"`. No rule and no operator can override the
+   ceiling.
+3. **What do the rules say?** `Permission.evaluate` reduces four rulesets into
+   `allow`, `deny`, or `ask`.
+4. **`allow` proceeds. `deny` fails** with `permission_denied` and the reason
+   `"denied by permission policy"`.
+5. **`ask` depends on who is there.** An unattended store fails with
+   `permission_required`, carrying the request id, the capability, its effect
+   tier, and the display metadata. An attended store parks the fiber on a
+   pending request and waits for a reply.
+
+The default decision is `ask`, so a capability no rule mentions is never
+allowed. What differs between a headless host and an operator-driven one is
+only what `ask` becomes.
+
+## The ceiling is monotone
+
+`CapabilitySet` is a normalized conjunction of any-of pattern groups: a
+capability is allowed only when every group contains a pattern matching it.
+`CapabilitySet.attenuate(patterns)` runs an effect with the parent authority
+**intersected** with one more group, which is the only way authority ever
+moves. There is no public widening constructor and no unrestricted value, so a
+scoped fiber can hand a narrower ceiling to work it delegates and can never
+recover what it gave up.
+
+A fiber that never passed through `attenuate` allows every capability, because
+unrestricted authority is the identity element of intersection and a
+permanently closed default would leave no operation able to widen a fiber
+again. The ceiling is not what makes the kernel fail closed. The ruleset is:
+its default verdict is `ask`, and an unattended store turns `ask` into a
+refusal. The ceiling's job is to bound what a _scoped_ fiber may ask for.
+
+## Four rulesets, last match wins
+
+`GrantStore` evaluates these in order:
+
+| Ruleset    | Where it comes from                                                                                            |
+| ---------- | -------------------------------------------------------------------------------------------------------------- |
+| Configured | `MakeOptions.rules`, or the first ruleset of a nested `rules` value. The operator's written policy.            |
+| Envelope   | Patterns activated by `grantEnvelope`, or the construction `envelope`, with run scope.                         |
+| Run        | `MakeOptions.runRules` and every `"run"` reply, each remembered alongside the ceiling of the fiber that asked. |
+| Remembered | Replayed remembered grants, and every `"remembered"` reply.                                                    |
+
+Matching rules are last-match-wins across all four. The configured ruleset gets
+one extra power: after it is reduced by the same last-match rule, an effective
+denial is a hard veto that no later ruleset can lift. A configured deny that a
+later configured allow or ask supersedes _within that ruleset_ is not a veto,
+so an operator can still write an exception after a broad denial.
+
+Run rules carry the ceiling of the fiber that requested them and are filtered
+out for any capability that ceiling would not allow. A grant handed to an
+attenuated fiber therefore cannot leak back up to a broader one, including after
+restart. Each `flows.kernel.grant.run.v2` event persists the normalized captured
+ceiling as a conjunction of any-of pattern groups. Replay intersects it with
+the constructor's ceiling; reopening under a broader parent cannot widen it.
+
+Trusted legacy `flows.kernel.grant.run.v1` events have no captured ceiling.
+The journal store refuses construction with `invalid_resolution` when it finds
+one. Their original boundary cannot be recovered, so obtain fresh approval in
+a new run instead of replaying legacy authority.
+
+A bare rule in `MakeOptions.runRules` uses the constructor's ceiling. A
+`{ rule, ceiling }` entry carries captured pattern groups and intersects them
+with that ceiling, as journal replay does.
+
+## The four resolutions
+
+`store.reply(requestId, resolution, pattern?)` takes one of four answers:
+
+| Resolution   | Effect                                                                                                                     |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `once`       | Authorizes this request alone. Nothing is added to the rules.                                                              |
+| `run`        | Adds an allow rule for the rest of the run. Requires a plan digest; without one the reply fails with `invalid_resolution`. |
+| `remembered` | Adds an allow rule that a journal-backed store replays into later processes.                                               |
+| `deny`       | Fails the parked request with `permission_denied`.                                                                         |
+
+For `run` and `remembered`, the pattern is the caller's if one is supplied and
+otherwise derived from the exact capability. A resource containing glob
+metacharacters has no unambiguous derived pattern, so the reply fails and says
+to supply a pattern explicitly or resolve `once`.
+
+A supplied pattern is checked before it is stored. `isValidGrantPattern`
+refuses a pattern that 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 grammar has no escape, so that pattern's
+wildcard reading would silently widen access. The refusal is
+`invalid_resolution` with `"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/**` resolves the queue behind it rather than
+asking again per file.
+
+A reply records its decision in the journal before anything activates, but the
+write never holds the store's mutation permit. A slow or dead journal stalls
+only the reply that issued it: checks, `list`, waiter cancellation, and store
+closure all proceed while a write is stuck, and a write that exceeds
+`maximumPersistMillis` (30 seconds) fails the reply with `journal_failed`,
+leaving the request parked for a retry. A second reply to the same request
+while its decision is mid-write fails fast with `request_not_found` rather
+than queueing behind the journal. Envelope admissions follow the same rule,
+and a concurrent identical envelope adopts the in-flight outcome instead of
+writing a duplicate record.
+
+## Envelope approvals
+
+`grantEnvelope` approves a whole set of patterns at once, which is what a plan
+approval is: the operator says yes to everything the plan declared, before it
+starts. An envelope is a **set**, so `canonicalEnvelopePatterns` deduplicates
+its predicates and sorts them by formatted identity, and `envelopeSignature`
+computes `sha256:` followed by the 64 lowercase hexadecimal digits of the
+SHA-256 digest of that canonical JSON encoding (plan digest, scope, sorted
+formatted predicates). Existing v1 journal events keep their format: replay
+recomputes the digest from their fields. Legacy full-JSON signature seeds are
+normalized to the same digest before comparison.
+Two approvals listing the same predicates in a different order are the same
+approval, and the second one is a no-op rather than a second durable record.
+
+Envelope patterns are checked by `isValidEnvelopePattern`, which preserves
+exact action and filesystem effect-tier boundaries, so an envelope cannot turn
+a read approval into a write one.
+
+## Bounds are part of the contract
+
+One store retains at most 1,024 policy rules across all four rulesets, 1,024
+activated envelope signatures, 256 patterns per envelope, and 1,024 parked
+requests. Metadata is limited to 16 levels of nesting, 1,024 members, and
+64 KiB of canonical JSON, and one encoded event to 256 KiB. Run, plan,
+and request identities are limited to 4,096 UTF-16 code units. Generated
+envelope signatures occupy 71 ASCII characters; legacy signature seeds must
+fit the 256 KiB event bound before normalization. Other supplied signature
+identities retain the 4,096-unit limit. Capability resources share the
+capability package's own 4,096-unit limit.
+
+Construction and runtime envelopes use the same admission check. Incoming
+canonical patterns count toward the combined rule ceiling; rules already
+replayed for the same envelope are counted once. Journal reconstruction uses
+this admission check before appending a construction envelope.
+
+Every bound failure is `invalid_resolution` and happens **before** any state
+or journal authority changes, so a refused write never half-applies. The
+constants are exported (`GrantStore.maximumRules` and its siblings) so a host
+can check against the same numbers rather than guessing them.
+
+## Identity is exact text
+
+Capability actions and resources, patterns, run ids, plan digests, request
+ids, and grant metadata are identity-bearing values. Smithers validates
+well-formed text but does not apply Unicode normalization: matching,
+signatures, and journal replay all use the exact JavaScript string and its
+UTF-16 code-unit sequence. A caller that wants NFC applies it before
+constructing the value. Identity fields whose contract forbids it reject lone
+surrogates and NUL.
+
+## Related
+
+- [Write a capability policy](../guides/write-a-capability-policy.md): rules
+  and ceilings in practice.
+- [Answer permission requests](../guides/answer-permission-requests.md): the
+  attended surface.
+- [The authorization model](/pkg/capability/concepts/authorization-model): the
+  vocabulary and the evaluation function this page drives.