@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/docs/concepts/effects-and-capabilities.md

@@ -0,0 +1,138 @@
+---
+title: "Effects and capabilities"
+description: "What each flow declares before it runs, how effectsFor narrows that declaration to one call, and why hermetic mode is a lexical pre-check rather than a sandbox."
+sidebar:
+  order: 2
+---
+
+Every declaration carries two statements about what running it would do: an
+**effect envelope** and a list of **capabilities**. A scheduler reads the first
+to decide what may run beside what. A permission kernel reads the second to
+decide whether it may run at all.
+
+## The envelope
+
+An envelope has four parts:
+
+- `tier` is how reversible the effect is: `sealed` (observes only),
+  `compensable` (can be undone), or `irreversible` (cannot).
+- `mode` is `hermetic` when the flow declares the paths it touches, and
+  `expected` when it does not.
+- `reads` and `writes` are path globs.
+- `onConflict` is `serialize` for every flow in this package. The library owns
+  no lane partitioning of its own, so the conservative choice is the safe one.
+
+Here is what each flow declares at registry time, before any input is known:
+
+| Flow            | Tier           | Mode       | Declared reads and writes | Capabilities                  |
+| --------------- | -------------- | ---------- | ------------------------- | ----------------------------- |
+| `read`          | `sealed`       | `hermetic` | reads `/**`               | `fs:read:/**`                 |
+| `ls`            | `sealed`       | `hermetic` | reads `/**`               | `fs:read:/**`                 |
+| `glob`          | `sealed`       | `hermetic` | reads `/**`               | `fs:read:/**`                 |
+| `grep`          | `sealed`       | `hermetic` | reads `/**`               | `fs:read:/**`                 |
+| `explore`       | `sealed`       | `hermetic` | reads `/**`               | `fs:read:/**`                 |
+| `lsp`           | `sealed`       | `hermetic` | reads `/**`               | `fs:read:/**`                 |
+| `write`         | `compensable`  | `hermetic` | writes `/**`              | `fs:write:/**`                |
+| `edit`          | `compensable`  | `hermetic` | reads and writes `/**`    | `fs:read:/**`, `fs:write:/**` |
+| `apply_patch`   | `compensable`  | `hermetic` | reads and writes `/**`    | `fs:read:/**`, `fs:write:/**` |
+| `update_plan`   | `sealed`       | `hermetic` | nothing                   | none                          |
+| `fetch`         | `sealed`       | `expected` | nothing                   | `net:get:*`                   |
+| `webfetch`      | `sealed`       | `expected` | nothing                   | `net:get:*`                   |
+| `websearch`     | `sealed`       | `expected` | nothing                   | `net:post:*`                  |
+| `http-post`     | `irreversible` | `expected` | nothing                   | `net:post:*`                  |
+| `bash`          | `irreversible` | `expected` | nothing                   | `proc:spawn:*`                |
+| `test`          | `irreversible` | `expected` | nothing                   | `proc:spawn:*`                |
+| `shell_command` | `irreversible` | `expected` | nothing                   | `proc:spawn:*`                |
+
+`fetch` is `sealed` even though it leaves the machine, because a retrieval
+leaves no durable state behind. `http-post` is `irreversible` because the
+remote side may already have acted.
+
+## Narrowing to one call
+
+The declared envelope is the registry-time worst case. It has to be, because the
+declaration exists before any input does. `effectsFor` is the other half: hand
+it one decoded input and it returns the envelope that call actually needs.
+
+```ts
+import * as Read from "@smthrs/std/Read"
+
+Read.effects // reads: ["/**"]
+Read.effectsFor({ path: "/workspace/notes.md" }) // reads: ["/workspace/notes.md"]
+```
+
+That is the difference between serializing every read in the workspace and
+serializing the two calls that touch one file. Seven flows narrow to something
+smaller than their declaration:
+
+| Flow           | What the narrowing says                                                                                                     |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `read`, `ls`   | reads the one `path` the input names                                                                                        |
+| `write`        | writes the one `path` the input names                                                                                       |
+| `edit`         | reads and writes the one `path` the input names                                                                             |
+| `glob`, `grep` | reads the `root` subtree, or `/**` when no root is given                                                                    |
+| `bash`         | in `hermetic` mode, `compensable` with the caller's own `reads` and `writes`; in `unhermetic` mode, the declared worst case |
+
+The other ten return their static envelope, and each says why in its own doc
+comment. `apply_patch` is the interesting one: a patch names its files inside
+its own text rather than in a decoded field, and the parse that finds them is
+the parse that can fail, so the static envelope is the honest answer.
+
+`Manifest.effectsFor` reaches the same functions by flow name, which is what a
+host needs when it holds a name and a decoded input rather than a module:
+
+```ts
+import * as Manifest from "@smthrs/std/Manifest"
+
+const narrow = Manifest.effectsFor["read"]
+```
+
+## Capabilities
+
+A capability is an `action:resource` string on the declaration, and the
+permission kernel decides whether the call is allowed to hold it. This package
+uses five:
+
+| Capability     | Flows                                                                 |
+| -------------- | --------------------------------------------------------------------- |
+| `fs:read:/**`  | `read`, `ls`, `glob`, `grep`, `edit`, `apply_patch`, `explore`, `lsp` |
+| `fs:write:/**` | `write`, `edit`, `apply_patch`                                        |
+| `proc:spawn:*` | `bash`, `test`, `shell_command`                                       |
+| `net:get:*`    | `fetch`, `webfetch`                                                   |
+| `net:post:*`   | `http-post`, `websearch`                                              |
+
+`explore` declares the union of the capabilities of the four flows it composes
+from, sorted and deduplicated, so a model offered `explore` is offered exactly
+the authority its readers need.
+
+## Hermetic mode is a pre-check, not a sandbox
+
+`bash` accepts `mode: "hermetic"` with explicit `reads` and `writes`, and the
+handler checks the command against them before spawning anything. Read what the
+check does, because the name promises more than it delivers.
+
+The check is **lexical**. It tokenizes the command line, keeping quoted spans
+whole, treats each physical line as its own command, reads the body of a
+command substitution, the argument of a shell's `-c` flag, and the arguments of
+`eval` as commands of their own, classifies each path token
+as a read or a write from the command that governs it, resolves both the token
+and every declaration to a canonical absolute path, and refuses the call with
+`outside_declared_reads` or `outside_declared_writes` when one falls outside.
+Paths under `/dev/` are exempt, because `2>/dev/null` is process plumbing rather
+than a filesystem access.
+
+Then it starts an ordinary host process. Shell expansion, subprocesses, and
+paths computed at runtime are not observed. So the check bounds **what a caller
+declared it would do**, not what the process can do. A host that needs
+confinement supplies a sandbox or an access-reporting boundary; this check alone
+cannot prove hermetic execution.
+
+Two inputs are refused rather than pre-checked, for the same reason:
+
+- A hermetic call that also names a `container`. A container has its own
+  filesystem, so declared host paths cannot describe it.
+- A hermetic `script` whose `interpreter` is not a shell. The pre-check reads
+  shell text, and Python is not shell text.
+
+Both refusals arrive as `invalid_input` with a message naming the alternative.
+See [Run a shell command](../guides/run-a-shell-command.md).

package/docs/concepts/flows-and-handlers.md

@@ -0,0 +1,115 @@
+---
+title: "Flows and handlers"
+description: "Every tool in this package is a portable declaration plus a separately supplied handler, and the Manifest registries are how a host reaches both halves by name."
+sidebar:
+  order: 1
+---
+
+A tool in this package is two halves that ship apart.
+
+The **declaration** is data. It carries `name`, `description`, `Input`,
+`Output`, `capabilities`, and `effects`, and it reaches nothing: no filesystem,
+no process, no network. That is what makes it safe to hand to a model, safe to
+put in a registry, and safe to plan against before a single call runs.
+
+The **handler** is the executable half. It is an ordinary Effect whose
+requirement names the host services it needs, so the host decides what `read`
+actually reads from.
+
+## The module shape
+
+Every flow module exports the same names, which is what lets a host treat all 17
+uniformly:
+
+| Export         | What it is                                                     |
+| -------------- | -------------------------------------------------------------- |
+| `name`         | The registry name, such as `"read"`.                           |
+| `description`  | The one line the model sees.                                   |
+| `Input`        | The input schema.                                              |
+| `Output`       | The output schema.                                             |
+| `effects`      | The declared effect envelope, before any input is known.       |
+| `effectsFor`   | The same envelope narrowed to one decoded input.               |
+| `capabilities` | The authority the flow requires, as `action:resource` strings. |
+| `flow`         | The declaration itself, built by `Flow.make`.                  |
+| `run`          | The handler.                                                   |
+
+`Explore` is the one exception: it has no `run`, because it is a dynamic flow
+composed from other flows rather than a handler.
+
+## Naming a declaration from another flow
+
+Because the declaration is data, a larger flow can name it and inherit both its
+capabilities and its effect envelope, without importing the handler at all:
+
+```ts
+import * as Read from "@smthrs/std/Read"
+import * as Schema from "effect/Schema"
+
+/** A step that reads a file. It declares what `read` declares. */
+export const ReadTarget = {
+  name: "read-target",
+  input: Schema.Struct({ path: Schema.String }),
+  output: Read.Output,
+  capabilities: Read.capabilities,
+  effects: Read.effects,
+  flows: [Read.flow]
+}
+```
+
+A planner reading `ReadTarget` can see that the step reads and does not write,
+before anything runs. That is the same property a review gate or an approval
+prompt needs.
+
+## The registries
+
+`Manifest` is the whole library keyed by name, so a host binds all of it without
+writing 17 imports:
+
+```ts
+import * as Manifest from "@smthrs/std/Manifest"
+
+Manifest.names // the 17 names, in registry order
+Manifest.flows // name -> declaration, all 17
+Manifest.handlers // name -> handler, the 16 that have one
+Manifest.effectsFor // name -> narrowing function, all 17
+Manifest.readOnly // the 8 names a read-only tool surface may see
+```
+
+Every registry is frozen. `Manifest.handlers` omits `explore` because a dynamic
+flow has no handler; `Manifest.effectsFor` includes it, because a model can
+still be offered the declaration and its envelope still narrows.
+
+`Manifest.readOnly` is `read`, `ls`, `glob`, `grep`, `fetch`, `explore`,
+`webfetch`, and `lsp`. `websearch` is deliberately absent: its provider contract
+requires `net:post` authority, which is mutating under the kernel capability
+taxonomy, so it cannot ride in a read-only tool surface.
+
+## The services a host binds
+
+Most handlers ask only for platform services such as `FileSystem` or
+`ChildProcessSpawner`. Six ask for a service this package defines, because the
+answer is a host decision rather than a platform one:
+
+| Service          | The flows that need it  | What it decides                                    |
+| ---------------- | ----------------------- | -------------------------------------------------- |
+| `Search`         | `grep`, `glob`          | Whether searching runs in process or through `rg`. |
+| `Container`      | `bash`, `test`          | How a command reaches a named container.           |
+| `TestRunner`     | `test`                  | How the project under test runs its suite.         |
+| `Checkpoints`    | agent-side tree pinning | Where a pinned tree is recorded and checked out.   |
+| `WebSearch`      | `websearch`             | Which search provider answers.                     |
+| `LanguageServer` | `lsp`                   | Which language server answers.                     |
+
+Each one ships a refusal implementation, and binding it is the honest way to say
+"this host cannot do that". A `makeNoop` service fails the call with
+`provider_unavailable` and a message naming what to do instead. Refusing loudly
+is the contract: a flow that appears to work while doing nothing costs a model
+the frames it takes to notice.
+
+## What stays in the success channel
+
+A handler fails only when a model must see a failure. A non-zero exit code, an
+empty match set, and an HTTP 500 are all ordinary values, returned in the
+success channel with the fields that describe them. `StdError` carries the rest,
+under a closed list of codes. See
+[Failures](../reference/flows.md#failures) for the list and
+[Troubleshooting](../troubleshooting.md) for what each one means in practice.

package/docs/concepts/limits-and-disclosure.md

@@ -0,0 +1,105 @@
+---
+title: "Limits are disclosed, never silent"
+description: "Every cap in this package is a display budget the result declares, plus the truncation flags the harness reads to refuse writing a fragment back to a file."
+sidebar:
+  order: 3
+---
+
+Every limit here is a display budget, not a policy limit. Exceeding one is
+always stated in the result, because a silent cut is how a caller comes to
+believe it has seen a whole file, a whole listing, or a whole match set when it
+has not.
+
+Three disclosure shapes cover the library:
+
+- `truncated` plus an optional `notice` string, on the paged and HTTP flows.
+  The notice reads `Showing 3 of 40 lines; output was truncated.`, or
+  `Showing 60000 of 1048576 bytes; output was truncated.` on the HTTP flows.
+- `<stream>Truncated` plus `<stream>DroppedBytes`, on the flows that capture a
+  process.
+- A typed refusal, where handing back a fragment would be worse than answering
+  nothing. `webfetch` and `fetch` refuse a response past 5 MiB with
+  `response_too_large`; `NativeSearch` refuses an `rg` stream past its capture
+  bound rather than risk disagreeing with the in-process peer.
+
+## The caps
+
+These values are fixed in the package and are not exported. They are what the
+handlers apply:
+
+| Cap                   | Value                       | Applies to                                                 |
+| --------------------- | --------------------------- | ---------------------------------------------------------- |
+| Default `read` page   | 2,000 lines                 | one `read` call with no `limit`                            |
+| Displayed line        | 2,000 Unicode scalar values | one line of a `read` page                                  |
+| Entries per page      | 1,000                       | one `ls` or `glob` page                                    |
+| Matches per call      | 200                         | one `grep` call                                            |
+| Match line preview    | 500 characters              | one `grep` match or context line                           |
+| Rendered text payload | 60,000 bytes                | one `read` page, `fetch`/`http-post` body, `webfetch` page |
+| Shell stream capture  | 30,000 bytes                | each captured `bash` stream                                |
+| HTTP response body    | 5 MiB                       | `fetch`, `http-post`, and `webfetch`, refused past the cap |
+| Redirects             | 10                          | one `webfetch` call                                        |
+| Language-server frame | 8 MiB body, 8 KiB header    | one JSON-RPC frame                                         |
+
+These are exported constants, so a host can read them and a caller can raise or
+lower what it passes:
+
+| Constant                                  | Value      | Applies to                                                  |
+| ----------------------------------------- | ---------- | ----------------------------------------------------------- |
+| `Bash.DEFAULT_TIMEOUT_MS`                 | 600,000    | one `bash` call with no `timeoutMs`                         |
+| `TestRun.DEFAULT_TIMEOUT_MS`              | 600,000    | one `test` call with no `timeoutMs`                         |
+| `TestRun.MAX_CAPTURE_BYTES`               | 8,000,000  | runner output one `test` call holds in memory               |
+| `ShellCommand.DEFAULT_TIMEOUT_MS`         | 10,000     | one `shell_command` call with no `timeout_ms`               |
+| `ShellCommand.MAX_CAPTURE_BYTES`          | 8,000,000  | command output one `shell_command` call holds in memory     |
+| `ShellCommand.DEFAULT_MAX_OUTPUT_TOKENS`  | 10,000     | the Codex token budget the output is shaped to              |
+| `ShellCommand.TIMEOUT_EXIT_CODE`          | 124        | the exit code a timed-out `shell_command` reports           |
+| `NativeSearch.MAX_CAPTURE_BYTES`          | 67,108,864 | one `rg` invocation's captured output, refused past the cap |
+| `NodeLanguageServer.MAX_QUEUED_FRAMES`    | 256        | frames buffered for one server's standard input             |
+| `NodeLanguageServer.MAX_PENDING_REQUESTS` | 512        | concurrent in-flight requests to one server                 |
+
+## A page ends on a whole line
+
+A byte budget cuts mid-line, and a partial line reads like an anchor and is not
+one. So a `read` page truncated by bytes ends at the last whole line it could
+afford, and `endLine` counts only the lines it actually returned. A line clipped
+by the 2,000-character display cap is called out in the notice by name, because
+such a line cannot be used as an `edit` anchor either.
+
+## A limit counts matches, not rows
+
+`grep` returns match-centric results, which is how `rg --json` groups its own
+output. `limit` counts matches, each match carries the context lines that belong
+to it, and every context line belongs to exactly one match. A budget that
+counted rows could spend itself on context and drop the hit, which is a result
+that shows the lines around a match and not the match.
+
+## A listing is ordered before it is paged
+
+`ls` describes every entry before it cuts the page, because the order it
+promises is directories first and a kind costs a stat. Ordering inside the page
+instead would make `offset` address a different listing at every page size, so a
+caller paging a large directory could see one entry twice and another never.
+
+## Truncation flags are a wire contract
+
+`stdoutTruncated`, `stderrTruncated`, and `tailTruncated` are not display
+details. A truncated capture is a fragment of what the process printed, and
+[`@smthrs/harness`](/api/harness) reads these flags to refuse a later write of
+those exact bytes: writing a captured fragment over a file replaces the file
+with a piece of a log. Read the flag before writing captured output anywhere, and set
+it in your own handler whenever you cut a capture: a consumer that cannot tell a
+fragment from the whole writes the fragment.
+
+`stdoutDroppedBytes`, `stderrDroppedBytes`, and `tailDroppedBytes` count what
+the process actually produced beyond the capture. Capture is bounded where the
+stream is read rather than after it is read, so a command that prints gigabytes
+costs the bound instead of the whole of what it printed. `bash` keeps the
+first and last 15,000 bytes of each stream and puts one line such as
+`[10025 bytes omitted]` where the middle was, because a search prints its
+matches first and a failing command prints its verdict last. Its dropped-bytes
+count is the size of that middle. `test` keeps the tail; `read`, `fetch`, and
+`http-post` keep the head.
+
+Every caller-supplied command (`bash`, `test`, `shell_command`) passes a capture
+bound. The internal `git` plumbing behind `Checkpoints` and `TestRun`'s baseline
+does not, because a listing read for its content is useless with its head
+missing.

package/docs/concepts/search-contract.md

@@ -0,0 +1,182 @@
+---
+title: "The search contract"
+description: "Smithers Ripgrep Subset v1: what grep and glob support, how patterns and globs are read relative to the search root, and how two peer implementations are held to one answer."
+sidebar:
+  order: 4
+---
+
+`grep` and `glob` are two projections of one contract, Smithers Ripgrep Subset
+v1. The contract exists because the package ships two implementations of it, and
+a caller must not be able to tell which one answered.
+
+- `PortableSearch` walks the injected `FileSystem` in process. It needs no
+  external binary, so it is the peer a browser host and a test host use.
+- `NativeSearch` drives the `rg` executable through the permission-aware
+  spawner.
+
+Both are bound to the `Search` service, and `Grep.run` and `Glob.run` call
+whichever one the host provided. Neither module knows which peer is in play.
+
+## What v1 supports
+
+`grep` corresponds to a bounded subset of ripgrep's flags:
+
+| Input field                                | Ripgrep flag                              |
+| ------------------------------------------ | ----------------------------------------- |
+| `fixedStrings`                             | `-F`                                      |
+| `ignoreCase`                               | `-i`                                      |
+| `smartCase`                                | `-S`                                      |
+| `globs`                                    | ordered `-g` include and exclude patterns |
+| `beforeContext`, `afterContext`, `context` | `-B`, `-A`, `-C`                          |
+| `maxCount`                                 | `--max-count`, per file                   |
+| `filesWithMatches`                         | `--files-with-matches`                    |
+| `hidden`                                   | `--hidden`                                |
+| `noIgnore`                                 | `--no-ignore`                             |
+| `limit`                                    | the global result budget, capped at 200   |
+
+`glob` corresponds to `rg --files -g <pattern>`.
+
+`noIgnore` is an optional boolean defaulting to `false`. Both flows apply
+`.gitignore` rules from the search root and nested directories, even outside
+Git repositories. Set `noIgnore: true` to include ignored paths. Parent and
+global ignore rules, `.ignore`, `.rgignore`, and `.git/info/exclude` do not
+participate. Hidden-file and fixed directory skips still apply.
+
+File-type registries are not supported, so there is no `types` field to pass.
+`-i` and `-S` together, and `-C` combined with `-A` or `-B`, are `invalid_input`,
+because ripgrep's own precedence for those combinations is not a thing two peers
+should each guess at.
+
+## The pattern grammar
+
+Smithers Ripgrep ASCII v1 is deliberately the intersection of Rust's regex crate
+and JavaScript's `RegExp`, so both peers compile the same pattern to the same
+meaning. A pattern is rejected with `invalid_pattern` when it:
+
+- contains anything outside printable ASCII, or exceeds 4,096 bytes;
+- opens a special group with `(?`, which covers lookaround and named groups;
+- escapes an alphanumeric, which covers backreferences, shorthand classes such
+  as `\d`, and encoded escapes;
+- nests a character class, leaves one empty, or uses a class set operation
+  (`&&`, `--`, `~~`);
+- names a counted repetition above 1,000;
+- exceeds 128 nested groups or 8,192 compiled states after repetition expansion;
+- fails to compile as a JavaScript regular expression.
+
+`fixedStrings: true` skips the grammar entirely except for the ASCII and length
+checks, because a literal is escaped rather than compiled.
+
+Inside the shared compiler, `.` matches any character except a newline and `$`
+anchors at the end of the whole input, which is what makes a line-oriented
+search behave the same in both peers.
+
+Portable grep evaluates this grammar with a Thompson state machine. Matching
+work is linear in line length times the bounded state count, including nested
+quantifiers and ambiguous alternatives. It yields every 4,096 state visits so
+host timers and Effect interruption can run during a long match. JavaScript
+regular expressions are used only for individual character predicates.
+
+The portable scan reads files in chunks and counts overflow without retaining
+all hits. It keeps the first `limit` hits and their context, plus one boundary
+hit to preserve context ownership at truncation. Symbol source is loaded only
+for files with returned hits and released after annotating each file. Memory
+still includes the current line and, with `symbols: true`, one retained hit's
+source file; `limit` is a result budget, not a byte limit on that source.
+
+## Globs are relative to the root, never absolute
+
+This is the rule that most often surprises a caller, and getting it wrong is
+silent: an absolute pattern matches nothing at all, forever.
+
+A candidate is matched by the path it has **relative to the search root**. Three
+consequences, and both peers implement all three identically:
+
+- A pattern with no `/` matches the **basename** at any depth. `*.py` finds
+  every Python file in the subtree.
+- A pattern containing `/` is matched against the root-relative path and is
+  anchored at the root. `tests/*.py` matches `<root>/tests/a.py` and not
+  `<root>/src/tests/a.py`.
+- A leading `/` is that same anchor spelled explicitly, not a filesystem
+  absolute path. `/a.py` matches only `<root>/a.py`, where bare `a.py` would
+  match any `a.py` in the subtree. A leading `./` means the same anchor.
+
+`**` crosses directory boundaries; `*` and `?` stay inside one segment; `?`
+consumes one UTF-8 byte. Brace alternatives expand, up to 256 patterns. Glob
+escapes and character classes are not supported. Trailing spaces are not part of
+a pattern, because `rg` reads `-g` by gitignore's rules and drops them, and a
+pattern left blank by that is rejected rather than read as no filter at all.
+
+Ordered include and exclude globs work like ripgrep's: with no positive glob
+everything is included, and the last pattern to match a candidate decides, with
+`!` marking an exclusion.
+
+So `/home/repo/tests/**` passed against a root of `/home/repo` is read as the
+root-relative path `home/repo/tests/**`, which nothing under that root can
+match. That answer is never silent: a positive glob no file under the root could
+match is explained through `notice`, naming the reason (a missing directory, a
+skipped directory, a hidden path with `hidden` left false) and, where it applies,
+the root-relative pattern the caller probably meant.
+
+A `root` that names one file is that file. It is reported whatever the pattern
+says, because `rg` searches a path given on its command line without consulting
+`-g`.
+
+## What a walk skips
+
+Repository internals, dependency trees, caches, and worktrees are never
+descended into. This includes `.artifacts`, `.backend-go-modcache`,
+`.pnpm-store`, `.worktrees`, and `worktrees`. Skipping applies to descent and
+never to what the caller named, so naming one of them as the `root` still
+searches it.
+
+A walk also skips what it cannot read: a dangling symlink, a link cycle, a
+directory the process may not list. One unreadable entry never fails the call,
+which is what `rg --no-messages` does with the same tree. Only the root the
+caller named can fail the walk.
+
+Files with a NUL byte are skipped and counted in `skippedBinary`. Invalid UTF-8
+in a searched file is replacement-decoded rather than refused.
+
+## Two properties that belong to the contract, not to a peer
+
+Both are computed in shared code, so neither peer can drift on them:
+
+- **Each hit carries its enclosing definition.** A line number is not a read
+  window. When a file's shape says plainly which definition a hit sits in, the
+  match carries `symbol` with that definition's `kind`, `name`, `startLine`, and
+  `endLine`, so the follow-up `read` is a fact rather than a guess. The
+  heuristic answers nothing rather than guessing when the shape is not plain.
+- **A metacharacter pattern that finds nothing is retried literally.** If a
+  pattern containing regex metacharacters produces no matches and no files, the
+  search runs again with `fixedStrings: true`. When that finds something, the
+  result carries `retriedAsLiteral: true` and says so in `notice`. A search that
+  found nothing because the caller wrote a literal containing `(` is the most
+  common way a search lies.
+
+## Proving a third peer
+
+`Search` is a public seam: a host may bind its own implementation. Two modules
+exist so that a new peer can be held to the same contract as the shipped ones.
+
+`SearchContract` exports the matcher both peers build on, so a third peer reuses
+the meaning of a pattern instead of reimplementing it:
+
+```ts
+import * as SearchContract from "@smthrs/std/SearchContract"
+
+SearchContract.validatePattern("foo.*bar", false) // undefined, or a StdError
+SearchContract.validateGlob("src/**/*.ts") // undefined, or a StdError
+SearchContract.canonicalGlob("./src/**/*.ts ") // "/src/**/*.ts"
+SearchContract.matchesGlob("*.ts", "src/widen.ts", "widen.ts") // true
+SearchContract.includedByGlobs(["**/*.ts", "!**/*.d.ts"], "src/a.d.ts", "a.d.ts") // false
+```
+
+`SearchConformance` is the differential kit: it generates a tree and a batch of
+calls from a seed, runs them through two implementations, and reports every
+answer that differs. It knows nothing about which peer is right; a divergence is
+the finding. It found two real drifts between the peers shipped here, one in how
+`maxCount` interacts with context lines and one in how `ignoreCase` and
+`smartCase` combine.
+
+The walkthrough is
+[Implement your own search peer](../guides/implement-a-search-peer.md).

package/docs/guides/bind-the-standard-flows.md

@@ -0,0 +1,116 @@
+---
+title: "Bind the standard flows into a host"
+description: "Compose the platform and service layers the handlers require, offer the declarations to a model, and use the read-only projection for a restricted tool surface."
+sidebar:
+  order: 1
+---
+
+A host does two things with this package: it offers declarations to a model, and
+it runs the matching handlers when a call arrives. This guide covers the
+composition both halves need.
+
+## Compose the host layer
+
+Start with a platform layer, then add one layer per service a flow needs:
+
+```ts
+import { NodeServices } from "@effect/platform-node"
+import * as Container from "@smthrs/std/Container"
+import * as NativeSearch from "@smthrs/std/NativeSearch"
+import * as TestRunner from "@smthrs/std/TestRunner"
+import * as Layer from "effect/Layer"
+
+/** FileSystem, Path, and ChildProcessSpawner. */
+const platform = NodeServices.layer
+
+const host = Layer.mergeAll(
+  platform,
+  // grep and glob, through the rg executable.
+  NativeSearch.layer.pipe(Layer.provide(platform)),
+  // bash and test, when a call names a container.
+  Container.layerCommand({ program: "docker" }),
+  // test: how the project under test runs its suite.
+  TestRunner.layer({ command: "pnpm vitest run", cwd: "/workspace" })
+)
+```
+
+Swap `NativeSearch.layer` for `PortableSearch.layer` to search in process with
+no external binary. Both satisfy the same `Search` service, and nothing above
+the layer changes. When the files live on another machine, such as a container
+or a sandbox machine, `RemoteSearch.make` over that machine's spawner and `Path`
+answers in two round trips where the portable peer would ask once per file.
+
+A host that cannot serve a service binds its refusal layer instead of leaving it
+out, so the failure names the missing service rather than a missing context:
+
+```ts
+import * as Checkpoints from "@smthrs/std/Checkpoints"
+import * as LanguageServer from "@smthrs/std/LanguageServer"
+import * as WebSearch from "@smthrs/std/WebSearch"
+
+const unavailable = Layer.mergeAll(
+  WebSearch.layerNoop, // websearch fails with provider_unavailable
+  LanguageServer.layerNoop, // lsp fails with unsupported
+  Checkpoints.layerNoop // pinning fails with provider_unavailable
+)
+```
+
+## Run one handler
+
+A handler is an ordinary Effect. Provide the composed host and run it:
+
+```ts
+import * as Grep from "@smthrs/std/Grep"
+import * as Effect from "effect/Effect"
+
+const hits = Effect.provide(
+  Grep.run({ pattern: "TODO", root: "/workspace", globs: ["*.ts"] }),
+  host
+)
+```
+
+## Offer the declarations
+
+`Manifest.flows` is the declaration registry, keyed by the same names a model
+calls. Offering all 17 is one expression:
+
+```ts
+import * as Manifest from "@smthrs/std/Manifest"
+
+const offered = Manifest.names.map((name) => Manifest.flows[name])
+```
+
+For a tool surface that must not change anything, use the read-only projection
+instead of filtering by hand:
+
+```ts
+const readOnly = Manifest.readOnly.map((name) => Manifest.flows[name])
+```
+
+`Manifest.readOnly` is `read`, `ls`, `glob`, `grep`, `fetch`, `explore`,
+`webfetch`, and `lsp`. `websearch` is not in it: its provider contract requires
+`net:post` authority, which is mutating under the kernel capability taxonomy.
+
+## Narrow the envelope for one call
+
+When a call arrives, narrow its declared envelope to what that input actually
+touches before scheduling it. `Manifest.effectsFor` reaches the narrowing by
+name:
+
+```ts
+const narrowed = Manifest.effectsFor["read"]({ path: "/workspace/notes.md" })
+// reads: ["/workspace/notes.md"], instead of the declared ["/**"]
+```
+
+Without this, two reads of two different files serialize against each other. See
+[Effects and capabilities](../concepts/effects-and-capabilities.md).
+
+## The production path
+
+[`@smthrs/agent`](/api/agent) already does all of this. Its `StandardFlows`
+module pairs each declaration with its handler through
+[`@smthrs/harness`](/api/harness)'s `FlowBinding` contract, and groups them by
+the slice of host services they need: `filesystem` binds `read`, `write`,
+`edit`, `apply_patch`, `ls`, `glob`, and `grep`; `shell` binds `bash`; `tests`
+binds `test`. If you are building an agent rather than a tool host, start there:
+[Give a run capabilities](/pkg/agent/guides/capabilities).