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

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,102 @@
+---
+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 tail over a file replaces the file with
+the end 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 tail
+of each stream, because a failing command prints its verdict last; `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,114 @@
+---
+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.
+
+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).

package/docs/guides/implement-a-search-peer.md

@@ -0,0 +1,133 @@
+---
+title: "Implement your own search peer"
+description: "Bind a third implementation of the Search service using the shared matcher, then prove it agrees with a reference peer using the differential conformance kit."
+sidebar:
+  order: 9
+---
+
+`Search` is a public extension seam. A host binds its own implementation and
+every `grep` and `glob` call in the package goes through it, so an index server,
+a remote service, or a virtual filesystem can back the search flows. This guide
+is about filling that seam without drifting from what a pattern means.
+
+## The interface
+
+Two methods, both taking normalized input:
+
+```ts
+import * as Search from "@smthrs/std/Search"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+const peer = Search.make({
+  grep: (input) =>
+    Effect.succeed({
+      matches: [],
+      files: [],
+      filesSearched: 0,
+      skippedBinary: 0,
+      truncated: false
+    }),
+  glob: (input) => Effect.succeed({ paths: [], total: 0, truncated: false })
+})
+
+const layer = Layer.succeed(Search.Search, peer)
+```
+
+`Grep.run` and `Glob.run` do the validation and defaulting before they call you,
+so `GrepInput` and `GlobInput` arrive complete: `root` is resolved, `globs` is an
+array, the context fields are numbers, and `limit` is already capped. Your
+implementation never sees an undefined option.
+
+The error channel is `StdError`, and the codes a peer produces are `not_found`
+for a missing root, `invalid_pattern` for a pattern it cannot compile, and
+`command_failed` for a host failure of its own.
+
+## Reuse the shared matcher
+
+Do not reimplement pattern or glob semantics. `SearchContract` exports exactly
+the functions both shipped peers build on:
+
+```ts
+import * as SearchContract from "@smthrs/std/SearchContract"
+
+SearchContract.validatePattern(pattern, fixedStrings) // StdError | undefined
+SearchContract.validateGlob(glob) // StdError | undefined
+SearchContract.canonicalGlob("./src/**/*.ts ") // "/src/**/*.ts"
+SearchContract.expression(pattern, fixedStrings, insensitive) // a RegExp
+SearchContract.matchesGlob("*.ts", "src/widen.ts", "widen.ts") // true
+SearchContract.includedByGlobs(globs, relative, basename) // ordered include and exclude
+SearchContract.unsatisfiableNotice({ fileSystem, path, root, globs, hidden })
+```
+
+`matchesGlob` and `includedByGlobs` take a candidate's path **relative to the
+root** and its basename, which is the whole of the root-relative rule described
+in [The search contract](../concepts/search-contract.md).
+
+`unsatisfiableNotice` is what keeps an empty answer honest: attach its result to
+`notice` when your peer produced no entries, so "the tree holds no match" and
+"this pattern can never match" stay distinguishable.
+
+## Prove it agrees
+
+`SearchConformance` 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.
+
+```ts
+import { NodeServices } from "@effect/platform-node"
+import type * as KernelPath from "@smthrs/kernel/Path"
+import * as PortableSearch from "@smthrs/std/PortableSearch"
+import type * as Search from "@smthrs/std/Search"
+import * as SearchConformance from "@smthrs/std/SearchConformance"
+import * as Effect from "effect/Effect"
+import type * as FileSystem from "effect/FileSystem"
+
+const check = (subject: Search.Search) =>
+  Effect.gen(function*() {
+    const plan = SearchConformance.plan({
+      seed: 1234,
+      root: "/tmp/conformance",
+      files: 24,
+      calls: 40
+    })
+    yield* SearchConformance.materialize(plan)
+
+    const services = yield* Effect.context<FileSystem.FileSystem | KernelPath.Path>()
+    const divergences = yield* SearchConformance.compare({
+      plan,
+      subject,
+      reference: PortableSearch.make(services)
+    })
+    return SearchConformance.report(divergences)
+  })
+
+const report = await Effect.runPromise(Effect.provide(check(peer), NodeServices.layer))
+```
+
+| Export        | What it does                                                          |
+| ------------- | --------------------------------------------------------------------- |
+| `plan`        | Builds a reproducible tree and call batch from a seed.                |
+| `materialize` | Writes that plan's tree under its root.                               |
+| `compare`     | Runs every call through both peers and returns the `Divergence` list. |
+| `report`      | Renders divergences as the text a failing run should print.           |
+
+The same seed and root always produce the same plan, so a divergence a run
+reports replays exactly by rerunning that seed. A failure is compared like any
+other answer: two peers that refuse the same call with the same code agree, and
+one that refuses where the other answers has diverged.
+
+`PortableSearch` is the obvious reference, because it needs no external binary.
+
+## What the generator will not tell you
+
+The generator deliberately stays inside the ground both peers claim to share: no
+symlinks, no unreadable directories, no CRLF, no NUL bytes, no filename a shell
+would have to quote. Those cases have an intended behavior rather than merely an
+agreed one, and a generator can only say that two peers disagree, never which is
+right. Pin them with hand-written cases alongside the conformance run.
+
+The kit earns its place on the cases nobody thought to write down. A literal `?`
+matched `fo` in one shipped peer and `foo?` in the other for as long as nobody
+wrote that case; the generator found it, along with a `maxCount` interaction with
+context lines and a disagreement between `ignoreCase` and `smartCase`.