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

package/CHANGELOG.md

@@ -0,0 +1,130 @@
+# @smthrs/std
+
+## [Unreleased]
+
+### Fixed
+
+- Container commands reject sparse argument arrays and build plans from the
+  validated argument snapshot.
+
+- `webfetch` uses one timeout budget across requests, redirects, and response
+  body reads. It rejects non-finite and non-positive timeouts before dispatch,
+  retains the 30-second default, and caps valid timeouts at 120 seconds.
+- `webfetch` owns its redirect loop when composed with the kernel HTTP client,
+  reports the final URL, and allows at most ten redirects (eleven requests).
+  Each hop remains subject to the kernel's permission check.
+
+### Changed
+
+- `webfetch` caps its rendered `content` at the shared 60,000-byte head budget
+  and reports the cut through `truncated` and `notice`, matching `fetch` and
+  `http-post`. It previously returned up to 5 MiB of text to the model. The
+  5 MiB network read limit is unchanged.
+- `bash` measures the tree a containerised command runs in. For an
+  `unhermetic` call that names a `container`, the flow runs
+  `TreeFingerprint.script` through the container transport in the command's
+  working directory before and after the command and reports whether the two
+  answers differ as `mutated` on its output: `true` for a tree that changed,
+  `false` for one that held still, absent when it could not be measured (no
+  transport, no `find` or `stat -c`, a timeout, or a listing past `maxPaths`).
+  The host's workspace walk never sees a container's filesystem, so every
+  edit an agent made through `docker exec` read as an idle frame: on
+  Terminal-Bench 4.0 (2026-09-22) the harness's own read-only cap ended one
+  run after twenty-four frames of container writes and its claim judge
+  refused another's finished work as never recorded. Two extra `docker exec`
+  calls per containerised command, each bounded by the command's own timeout
+  and by 60 s.
+
+### Added
+
+- Added `TreeFingerprint`: the in-container tree measurement `bash` uses, and
+  the owner of the prune and suffix lists `@smthrs/agent/WorkspaceObservation`
+  now re-exports, so the host walk and the container measurement skip the
+  same derived artifacts. `key` (`"mutated"`) is the reserved output key,
+  documented beside `Probe.key`.
+
+- A batched `classify` call reports how long it took. `Classify.askAll` times
+  itself and the batch output carries `latencyMs` beside `results`, the way a
+  single verdict already carried the transport's. Without it the only timing a
+  caller had was the gap between the call's start and settle events, which the
+  harness publishes in one tick, so every batched classify card in the
+  OpenCode server read about 1 ms while single-state calls read 319, 264 and
+  265 ms. The field is additive: `results` is unchanged.
+
+- `Classify` maps evaluator failures with `Classifier.fromEvaluatorError` from
+  `@smthrs/model` instead of a private copy.
+
+### Added
+
+- Added the `classify` flow (`Classify`): typed Jev questions about any JSON state, one state or a batch of up to 64 at 32 KiB each, evaluated eight at a time through the `Evaluator` service of `@smthrs/model`. Answers carry probabilities and a confidence per question; a batch keeps every failure beside its state. `Classify.curated(classifier)` declares a `classify/<id>` flow from any `Classifier.make` declaration, with the classifier's state as input and its digest on the declaration.
+- Added `Classifiers`: the three curated classifiers `triage/relevance`, `check/verdict`, and `edit/risk`, and `Classifiers.all` for a host to bind as a set.
+- `Manifest` registers `classify`; it is part of `Manifest.readOnly` because a `model:call` observes and changes nothing.
+- Every flow module now exports `Input` and `Output` as the decoded TypeScript types beside the schemas. Only `Bash` did, so every other caller wrote `typeof Read.Input.Type`.
+
+### Changed
+
+- **Breaking.** Every service key, error tag, and class identifier now carries the package name: `@smthrs/std/<Name>`. `StdError` was tagged `flows/std/StdError`, `Checkpoints.Snapshot` was identified as `flows/std/Checkpoints/Snapshot`, and the `Search`, `Container`, `Checkpoints`, `TestRunner`, `WebSearch`, and `LanguageServer` keys were `/std/<Name>`. An `Effect.catchTag` on the old tag no longer matches; catch `"@smthrs/std/StdError"`.
+- **Breaking.** `Checkpoints.unavailable` is now `(id: string) => StdError` and names the checkpoint it was asked for, the same shape as `Container.unavailable`. It was a shared `StdError` value.
+- The `LanguageServer`, `Lsp`, `NodeLanguageServer`, `WebFetch`, `WebSearch`, and `ExaWebSearch` module headers describe the module instead of citing a plan file that does not exist, the barrel header names `@smthrs/std`, and every `@since` stamp reads `1.0.0` instead of the never-released `0.1.0`.
+
+- `grep` and `glob` now declare `noIgnore` as the literal `true` rather than a boolean. Ignore files are never consulted in v1, so `noIgnore: false` was accepted by the schema and then refused at runtime; the schema now states what it accepts. A caller reaching `run` without decoding still gets the same `invalid_input` refusal.
+
+### Removed
+
+- Removed `grep`'s `types` input. File-type registries are not supported in v1, so every non-empty value failed with `invalid_input` while the field cost its description in every model frame.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Added `Manifest.effectsFor`, a frozen name-to-narrowing registry, and the missing `effectsFor` narrowing on `apply_patch`, `shell_command` and `update_plan`, so a host holding a flow name and a decoded input can narrow the envelope instead of serializing against the registry-time worst case.
+- Added `SearchContract` as a public module: `validatePattern`, `validateGlob`, `canonicalGlob`, `matchesGlob`, `includedByGlobs`, `expression` and `unsatisfiableNotice` are what an external `Search` peer must build on, and they were reachable only through the null-mapped `internal/` subpath.
+- Added default wall-clock timeouts to `bash` and `test` (`DEFAULT_TIMEOUT_MS`, ten minutes) and a capture bound to every buffered command, so a hung command no longer hangs the flow forever and a command printing gigabytes costs the bound rather than the whole of what it printed. `<stream>DroppedBytes` now counts what the process produced rather than what survived the display budget.
+- Added package-owned documentation: `docs/api.md` states the limits, the failure codes and the services a host binds, `docs/reference/flows.md` describes every flow's input, output and failures, and `test/Readme.test.ts` fails when `README.md`'s Public API or Limits table, or `docs/api.md`'s module list, no longer matches the barrel. The README's table had named 21 of the 30 exported namespaces, omitting three registry flows a model can call, and stated no limits, no failure codes and no service-binding behaviour.
+- Added a `test` flow bound to the repository's declared runner (`TestRunner`): it answers `{passed, failed[ids], parsed, tail}` read from the runner's own report — pytest, unittest and TAP are recognised — instead of twenty kilobytes of stdout, and `against: "base"` runs the same selection again on the pristine base commit in a detached worktree so `introduced`, `preexisting` and `fixed` come back from one call. The base is the engine's `refs/flows/capture-base`, then HEAD.
+- Added a `Container` transport service, and `script`/`interpreter`/`args`/`stdin`/`container` inputs to `bash`. A script reaches its interpreter on standard input as data, so no caller composes `docker exec c bash -lc '…heredoc…'` again; the argv for a container is built by the injected transport, and a host with none refuses the call by saying so.
+- Added the enclosing definition to every returned `grep` hit where the file's shape says so plainly, so a read window is computed rather than guessed; `symbols: false` turns it off.
+- Added `startLine`/`endLine`/`expect` anchoring to `edit`, so an edit can target the span a prior `read` or `grep` hit reported instead of retyping it.
+- Added `webfetch`, `websearch`, and `lsp` flows with provider-neutral service boundaries.
+- Added one ripgrep-compatible search contract with native `rg` and in-process peer implementations, shared conformance coverage, context lines, case modes, globs, per-file match limits, hidden-file control, and files-with-matches output.
+
+### Changed
+
+- **Breaking.** `read` now returns raw file text in `content`, with the line numbers in the sibling `startLine`/`endLine` fields, instead of rendering `NNN\t` before every line. An anchor copied out of a read used to carry the gutter, so every `edit` built from a read missed and cells wrote string surgery to strip it. A byte-capped page now also ends on a whole line rather than a fragment that reads like an anchor.
+- **Breaking.** `grep` results are match-centric: `limit` counts matches, each hit carries the `before`/`after` context that belongs to it, every context line belongs to exactly one hit, and a hit can no longer be dropped to make room for context. The flat `{file, line, text, kind}` rows are gone. A metacharacter pattern that finds nothing is retried as a literal, with `retriedAsLiteral` set.
+- **Breaking.** `edit` matches its anchor byte-exactly or fails, and reports the file's real text at the nearest region with its line range. The tolerant apply cascade (trailing whitespace, then collapsed whitespace) is gone from the apply path and survives only as that diagnosis: a match that is not the caller's bytes is an edit nobody inspected, which silently dedented a guard on one instance and corrupted a file on another. `edit` also returns the applied hunk, and `edit`, `write` and `apply_patch` all restore permission bits a host write moved.
+- Documented Bash's `stdoutTruncated`/`stderrTruncated` flags as the wire convention `@smthrs/harness/TruncatedOutput` reads, and stated in each stream's description that a truncated capture is a fragment that must not be written to a file.
+- Allowed hermetic Bash invocations to use the resolved base directory as their working directory without declaring it as a read.
+- Exempted `/dev/*` from the hermetic Bash path scan; process plumbing is not a workspace effect.
+
+### Fixed
+
+- **Breaking.** Closed three independent bypasses in the hermetic pre-check, each on its own sufficient to defeat it. A newline is now a command boundary, so `rm` on line two of a `script` is checked against `writes` instead of being classified under line one's command, and a leading `env`/`sudo`/`nice`/`xargs` wrapper no longer lends its own read classification to the command it wraps. Every path token and every declared entry is resolved before comparison, so `/work/../outside/secret.txt` is no longer inside `reads: ["/work"]` and `/dev/../etc/passwd` is checked as `/etc/passwd` rather than dropped as process plumbing. A blank entry in `reads`/`writes` no longer grants every absolute path, `"/"` now means the whole filesystem rather than nothing, and both fields reject the empty string at decode time.
+- Refused a container name that is empty or starts with `-`, and terminated the container argv with `--`, so `container: "--privileged"` can no longer be read as an option by `docker exec`.
+- Stopped `Html.decode` from throwing on an out-of-range or surrogate numeric entity, and bounded the element-skipping scan, which took thirty seconds on a two-megabyte page with unclosed `<script>` tags outside every timeout `webfetch` applies.
+- Made `test` report a reading only when the runner's own counts and the failure ids it named agree. A summary-only capture (`2 failed`, or `Ran 2 tests` with `FAILED (failures=2)` and no headers) used to come back `parsed: true` with an empty failure set, which reported every base failure as fixed.
+- Gave the `against: "base"` worktree the shape `Checkpoints` already proved it needs: a stale checkout is discarded first, the checkout's git pointer is relative so a container can read it, and the repository's format is restored. One killed run used to break every later baseline permanently.
+- Escaped `?` in a fixed-string search, so a literal `foo?` no longer matches `fo` and a bare `?` no longer dies as an unhandled defect instead of a typed failure.
+- Counted lines the way `grep` counts them in `read` and `edit`: a file ending in a newline no longer reports one line more than it has, and an empty file reads as an empty page instead of an out-of-range offset.
+- Refused a `file:`, `data:` or credential-bearing URL in `fetch`, `http-post` and `webfetch` through one shared guard, and bounded every HTTP response before decoding.
+- Made `apply_patch` derive every hunk before writing any of it, so a miss on the third hunk leaves the first two unwritten, and named what had been applied when a write itself fails.
+- Made `edit` refuse `expect` under an `oldString` anchor and `replaceAll` under a line span instead of silently ignoring them, and refuse an `endLine` past the end of the file instead of clamping it.
+- Made `edit` and `apply_patch` read bytes and refuse a non-UTF-8 file the way `read` does, instead of rewriting the whole file with replacement characters where the invalid bytes were.
+- Propagated a permission-restoration failure instead of swallowing it, so a write that moved the mode bits and could not put them back is a failure rather than a success.
+- Ordered `ls` by UTF-16 code unit rather than the host's ICU locale, reported a file as `not_a_directory`, and described every entry once before cutting the page, so `offset` addresses the same listing at every page size and a broken symlink no longer fails the whole listing.
+- Turned an Exa HTTP error into a distinguishable failure instead of a successful empty search, and bounded the provider request.
+- Parsed `rg --files` output as NUL-separated, so a legal filename containing a newline is one path rather than two fabricated ones.
+- Reported the truncation notice with the real byte totals, and stopped the cut-repair from eating a replacement character the source itself contained.
+- Classified the invalid-command probe in `test` against the text the caller receives, so its evidence line is always quotable from the returned tail.
+- Anchored the `Probe` recognisers the module documents as whole-line matchers.
+- Bounded the language-server transport: a frame header over 8 KiB and a frame over 8 MiB are refused and resynchronized past, the pending buffer grows by chunks instead of copying itself per chunk, and every outstanding request fails when stdout closes or the child exits.
+- Returned the workspace-wide envelope from `Lsp.effectsFor`, which narrowed reads to the queried file while the server reads the whole project.
+- Dropped the single-in-progress sentence from `update_plan`'s description, which the schema never enforced.
+- Made `edit` report the nearest actual region on a miss, as raw quotable bytes rather than line-number-prefixed text; two benchmark runs burned their whole frame budget on whitespace-guessing loops. Prior art: `reference/opencode` `tool/edit.ts`, where this deviates deliberately by refusing to apply a loose match.
+
+- Stopped `grep` and `glob` walks from descending into version-control, dependency, and cache directories; one `.git` descent held a frame for its whole evaluation ceiling.
+
+- Reported a directory entry whose metadata cannot be read as a plain entry instead of failing the whole `ls` listing.
+
+[Unreleased]: https://github.com/smithersai/smithers/compare/v1.0.0-rc.0...HEAD
+[1.0.0-rc.0]: https://github.com/smithersai/smithers/releases/tag/v1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @smthrs/std
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://std.smithers.sh
+
+The standard flows tool library for filesystem, search, HTTP, shell, language-server, and Jev judgment work. Each callable tool is an ordinary `@smthrs/core` flow declaration with explicit capabilities and effects, plus an injectable handler where execution is host-owned.
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+## Public API
+
+The root entry point exports these namespaces; each is also importable from `@smthrs/std/<Module>`.
+
+| Module               | Public exports                                                                                                                                                                                             | Description                                                                    |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `ApplyPatch`         | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `activity`, `presentation`, `paths`                                                                      | Declares and applies a V4A patch.                                              |
+| `Bash`               | `name`, `description`, `DEFAULT_TIMEOUT_MS`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `invocation`, `inTerminal`, `outsideContainer`, `sealed`, `presentation`           | Declares and runs bounded shell commands, here or in a registered terminal.    |
+| `Checkpoints`        | `baseId`, `scratchDirectory`, `configSection`, `Snapshot`, `Materialized`, `Checkpoints`, `make`, `unavailable`, `makeNoop`, `layerNoop`, `GitOptions`, `makeGit`, `layerGit`, `Relocation`, `relocate`    | Pins a working tree as a git checkpoint and materializes it again.             |
+| `Container`          | `Request`, `Plan`, `Container`, `make`, `unavailable`, `makeNoop`, `layerNoop`, `makeCommand`, `layerCommand`                                                                                              | Routes a command into a named container.                                       |
+| `Edit`               | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `activity`, `presentation`                                                                               | Declares and applies exact text replacements.                                  |
+| `ExaWebSearch`       | `layer`                                                                                                                                                                                                    | Provides WebSearch through the Exa API and kernel HTTP client.                 |
+| `Explore`            | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `make`, `flow`                                                                                                          | Declares a dynamic exploration flow composed from other standard flows.        |
+| `Fetch`              | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`                                                                                                           | Declares and runs raw HTTP GET requests.                                       |
+| `Glob`               | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `activity`, `presentation`                                                                               | Declares and runs filesystem glob searches.                                    |
+| `Grep`               | `name`, `description`, `Input`, `ContextLine`, `Symbol`, `Match`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `activity`, `presentation`                                             | Declares and runs text searches over files.                                    |
+| `HttpPost`           | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`                                                                                                           | Declares and runs HTTP POST requests.                                          |
+| `LanguageServer`     | `Position`, `LanguageServer`, `make`, `makeNoop`, `layerNoop`                                                                                                                                              | Defines the language-server query service.                                     |
+| `Ls`                 | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `activity`, `presentation`                                                                               | Declares and runs directory listings.                                          |
+| `Lsp`                | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`                                                                                                           | Declares and runs ten language-server queries, from hover to diagnostics.      |
+| `Manifest`           | `flows`, `handlers`, `effectsFor`, `names`, `readOnly`                                                                                                                                                     | Exposes frozen flow, handler, and narrowing registries plus the read-only set. |
+| `NativeSearch`       | `MAX_CAPTURE_BYTES`, `make`, `layer`                                                                                                                                                                       | Implements Search through the ripgrep binary.                                  |
+| `NodeLanguageServer` | `Config`, `MAX_QUEUED_FRAMES`, `MAX_PENDING_REQUESTS`, `make`, `makeLazy`, `layer`, `layerLazy`                                                                                                            | Implements LanguageServer with Node child processes, routed by extension.      |
+| `PortableSearch`     | `make`, `layer`                                                                                                                                                                                            | Implements Search by walking the kernel filesystem in process.                 |
+| `Probe`              | `key`, `Reason`, `InvalidProbe`, `Attribution`, `CONFIDENCE_FLOOR`, `MAX_OUTPUT_BYTES`, `posix`, `probeAttribution`, `classify`, `unjudged`                                                                | Attributes a non-zero exit to the command or to the tree, with Jev.            |
+| `Read`               | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `activity`, `presentation`, `MAX_READ_FILE_BYTES`, `Preconditions`, `ReadSession`, `VersionedFileSystem` | Declares and runs bounded file reads.                                          |
+| `Relocate`           | `Relocation`, `relocate`                                                                                                                                                                                   | Rewrites a call's input so the call runs against a materialized checkpoint.    |
+| `Search`             | `GrepInput`, `GrepLine`, `ContextLine`, `Symbol`, `GrepMatch`, `GrepOutput`, `GlobInput`, `GlobOutput`, `Search`, `make`, `makeNoop`, `layerNoop`                                                          | Defines the search service both peers implement.                               |
+| `SearchConformance`  | `GeneratedFile`, `Plan`, `Divergence`, `plan`, `materialize`, `compare`, `report`                                                                                                                          | Generates a tree and calls, then reports where two Search peers disagree.      |
+| `SearchContract`     | `validatePattern`, `validateGlob`, `canonicalGlob`, `matchesGlob`, `includedByGlobs`, `expression`, `unsatisfiableNotice`, `isContractRejection`                                                           | The shared matcher an external Search peer must build on.                      |
+| `ShellCommand`       | `name`, `description`, `DEFAULT_TIMEOUT_MS`, `MAX_CAPTURE_BYTES`, `DEFAULT_MAX_OUTPUT_TOKENS`, `TIMEOUT_EXIT_CODE`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`              | Declares and runs a Codex-shaped shell command.                                |
+| `StdError`           | `Code`, `StdError`                                                                                                                                                                                         | Defines typed standard-tool failures.                                          |
+| `TestRun`            | `name`, `description`, `scratchDirectory`, `DEFAULT_TIMEOUT_MS`, `MAX_CAPTURE_BYTES`, `Input`, `Outcome`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `activity`, `presentation`     | Runs the declared test suite and reads its report.                             |
+| `TreeFingerprint`    | `key`, `defaultPrune`, `defaultIgnoreSuffixes`, `maxPaths`, `Measurement`, `script`, `parse`, `moved`                                                                                                      | Measures a container's working directory so `bash` can report a write there.   |
+| `TestRunner`         | `captureBase`, `Runner`, `TestRunner`, `make`, `makeNoop`, `layer`, `layerNoop`                                                                                                                            | Declares how the project under test runs its suite.                            |
+| `UpdatePlan`         | `name`, `description`, `StepStatus`, `Plan`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`                                                                                     | Acknowledges a Codex plan update.                                              |
+| `WebFetch`           | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`                                                                                                           | Declares and runs normalized web-page fetches.                                 |
+| `WebSearch`          | `name`, `description`, `Input`, `Result`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `WebSearch`, `make`, `makeNoop`, `layerNoop`, `run`                                                   | Declares web search and its injectable provider service.                       |
+| `Write`              | `name`, `description`, `Input`, `Output`, `effects`, `effectsFor`, `capabilities`, `flow`, `run`, `activity`, `presentation`                                                                               | Declares and runs file writes.                                                 |
+
+```ts
+import { Read } from "@smthrs/std"
+import { Effect } from "effect"
+
+const program = Read.run({ path: "/workspace/notes.md" }).pipe(
+  Effect.map((result) => result.content)
+)
+// Provide the kernel FileSystem and Path layers in the host.
+```
+
+`Read.content` preserves source-line bytes, including trailing `\r` in CRLF files, and omits the page's final `\n`. Copy it unchanged into an edit anchor and retain the `\r` bytes in replacement text to keep CRLF endings.
+
+`Manifest.flows` is the declaration registry, `Manifest.handlers` contains directly executable handlers, `Manifest.effectsFor` narrows a declaration for one decoded input, and `Manifest.readOnly` is the canonical read-only projection. `@smthrs/std/package.json` is also exported; `internal/*` and nested `*/index` subpaths are blocked.
+
+The root entry point is Node-only: `NodeLanguageServer` pulls in `node:url`. The four subpaths `@smthrs/std/Grep`, `@smthrs/std/Glob`, `@smthrs/std/Search` and `@smthrs/std/PortableSearch` are browser-safe, because nothing any of them imports reaches a Node built-in.
+
+## Child process environment
+
+Commands started by `bash`, `shell_command`, `test`, and the package's internal
+process helpers do not inherit the full Smithers process environment. They
+receive only `PATH`, `HOME`, `USER`, `LANG`, `LC_*`, `TERM`, `TMPDIR`, and
+`SHELL`, plus variables the caller explicitly declares. Credential-shaped
+ambient names such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GH_TOKEN` are
+withheld; an explicitly declared name is intentional and is delivered even
+when its name looks sensitive.
+
+## Limits
+
+Every limit is a display budget disclosed to the caller, never a silent cut. A capped result says so in its own output: `truncated`, `<stream>Truncated`, or a `notice` line naming what was shown and what there was. Rows named by prose are fixed in the package and not exported; the rest are the constants named.
+
+| Limit                                     | Value       | Applies to                                                      |
+| ----------------------------------------- | ----------- | --------------------------------------------------------------- |
+| Default `read` page                       | 2,000 lines | one `read` call with no `limit`                                 |
+| Displayed line                            | 2,000       | one displayed line; a clipped line is not an edit anchor        |
+| Entries per page                          | 1,000       | one `ls` or `glob` page                                         |
+| Matches per call                          | 200         | one `grep` call                                                 |
+| Rendered text payload                     | 60,000      | one rendered text payload (`fetch`, `http-post`, `webfetch`)    |
+| Shell stream capture                      | 30,000      | each captured shell stream                                      |
+| `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   | the 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   | the command output one `shell_command` call holds in memory     |
+| `NativeSearch.MAX_CAPTURE_BYTES`          | 64 MiB      | one `rg` invocation's captured output, refused past the cap     |
+| HTTP response bytes                       | 5 MiB       | `fetch`, `http-post` and `webfetch`, refused past the cap       |
+| `fetch` / `http-post` timeout             | 30 s        | total request and body budget; `timeout` seconds, capped at 120 |
+| `webfetch` request timeout                | 120 s cap   | the request and the body read                                   |
+| Language-server frame                     | 8 MiB       | one JSON-RPC frame, with an 8 KiB header bound                  |
+| `NodeLanguageServer.MAX_QUEUED_FRAMES`    | 256         | frames buffered for one language server's stdin                 |
+| `NodeLanguageServer.MAX_PENDING_REQUESTS` | 512         | concurrent in-flight JSON-RPC requests to one server            |
+
+Shell capture is bounded where it is read rather than after: a command that prints gigabytes costs the bound, not the whole of what it printed, and the `<stream>DroppedBytes` fields count what the process actually produced. Every caller-supplied command (`bash`, `test`, `shell_command`) passes a bound. The internal `git` plumbing calls behind `Checkpoints` and `TestRun`'s baseline do not, because a listing read for its content is useless with its head missing. Those fields and the `<stream>Truncated` flags beside them are a wire convention: [`@smthrs/harness`](https://harness.smithers.sh) reads them to refuse a later write of those exact bytes, so check the flag before writing captured output anywhere.
+
+## Failures
+
+Handlers keep ordinary outcomes in the success channel: a non-zero exit code, an empty match set and a 500 response are all values. `StdError` is reserved for failures a model must see as failures, and its `code` is a closed, stable list carried with the offending `path` where one exists.
+
+| Code                       | Meaning                                                       |
+| -------------------------- | ------------------------------------------------------------- |
+| `not_found`                | The named path or ref does not exist.                         |
+| `not_a_file`               | A file operation was aimed at something that is not a file.   |
+| `not_a_directory`          | A directory operation was aimed at something that is not one. |
+| `is_directory`             | A read was aimed at a directory.                              |
+| `binary_file`              | The bytes hold a NUL or are not valid UTF-8.                  |
+| `offset_out_of_range`      | The requested page or line span is past the end.              |
+| `invalid_pattern`          | The search pattern does not compile.                          |
+| `invalid_input`            | The input is self-contradictory or names an unusable value.   |
+| `no_match`                 | The edit anchor or patch context is not in the file.          |
+| `not_modified`             | The write would leave the file exactly as it was.             |
+| `permission_denied`        | The host or the capability kernel refused access to the path. |
+| `outside_declared_reads`   | A hermetic path token is outside the declared read set.       |
+| `outside_declared_writes`  | A hermetic path token is outside the declared write set.      |
+| `command_failed`           | The process could not start, or a host operation failed.      |
+| `request_failed`           | The HTTP or language-server request failed.                   |
+| `timeout`                  | The call exceeded its wall-clock budget.                      |
+| `rate_limited`             | Provider rate limit reached; back off before retrying.        |
+| `provider_unavailable`     | No host bound the service this flow needs, or it refused.     |
+| `unsupported`              | The service does not implement this query.                    |
+| `unsupported_content_type` | The response is not a type this flow renders.                 |
+| `response_too_large`       | The response or file exceeded the byte cap before decoding.   |
+
+Six services are injected, and a flow whose service a host has not bound gets a `makeNoop` refusal rather than a silent success: `Search` for `grep` and `glob`, `Container` for a containerised `bash` or `test`, `TestRunner` for `test`, `Checkpoints` for agent-side pinning, `WebSearch` for `websearch`, and `LanguageServer` for `lsp`. Refusing loudly is the contract, because a flow that appears to work while doing nothing costs a model the frames it takes to notice.
+
+`NativeSearch` and `PortableSearch` are two implementations of one contract. `SearchContract` exports the matcher both build on, so an external peer binding its own `Search` cannot drift on what a pattern means. `SearchConformance` is how a peer proves it: it generates a tree and a batch of calls from a seed, runs them through two implementations, and reports every answer that differs. It found two drifts between the peers shipped here, one in how `maxCount` interacts with context lines and one in how `ignoreCase` and `smartCase` combine.
+
+## Hermetic mode is a pre-check, not a sandbox
+
+`Bash` retains `mode: "hermetic"` as effect-contract vocabulary, but the handler is not an operating-system sandbox. It performs a fail-closed lexical pre-check of the explicit path tokens in the command against `reads` and `writes`, resolving every token and every declaration to a canonical absolute path before comparing, and treating each physical line of a script as its own command. The host spawner runs the command under its configured confinement. Shell expansion, subprocess access, and paths computed at runtime are not observed, so the check bounds what a caller declared it would do rather than what the process can do. The CLI and native flow hosts supply OS confinement from the grants in force. The lexical check alone cannot prove hermetic execution.
+
+## Documentation
+
+The full documentation is at [std.smithers.sh](https://std.smithers.sh):
+
+- [Quickstart](https://std.smithers.sh/quickstart/): search a tree and read the definition a hit sits in.
+- [Flows and handlers](https://std.smithers.sh/concepts/flows-and-handlers/): the model behind the two halves.
+- [The search contract](https://std.smithers.sh/concepts/search-contract/): Smithers Ripgrep Subset v1 and its two peers.
+- [Flow reference](https://std.smithers.sh/reference/flows/): every flow's input and output fields.
+- [API reference](https://std.smithers.sh/reference/api/): every module and every public export.
+- [Troubleshooting](https://std.smithers.sh/troubleshooting/): the failures this package produces and what to change.

package/dist/cjs/ApplyPatch.d.ts

@@ -0,0 +1,174 @@
+/**
+ * apply_patch flow declaration and portable handler.
+ *
+ * A Codex CLI clone: the V4A patch grammar (`*** Begin Patch` /
+ * `*** Add File:` / `*** Update File:` / `*** Delete File:` /
+ * `*** End Patch`), the fuzzy context-matching applier, and Codex's error
+ * and summary text, expressed as a flow over the kernel filesystem.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+import * as StdError from "./StdError.ts";
+/**
+ * Registry name for the apply_patch flow. Matches the Codex CLI tool name.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "apply_patch";
+/**
+ * Model-facing description of the apply_patch flow. Matches the Codex CLI
+ * freeform tool description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.";
+/**
+ * Input schema for the apply_patch flow.
+ *
+ * Codex delivers the patch as freeform text; the JSON function fallback uses
+ * a single `input` field, which is the shape cloned here.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly input: Schema.String;
+}>;
+/**
+ * Decoded input accepted by the `apply_patch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * Output schema for the apply_patch flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly output: Schema.String;
+    readonly added: Schema.$Array<Schema.String>;
+    readonly modified: Schema.$Array<Schema.String>;
+    readonly deleted: Schema.$Array<Schema.String>;
+}>;
+/**
+ * Decoded output returned by the `apply_patch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * Static conservative effect envelope for the apply_patch flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the effect envelope for a decoded invocation.
+ *
+ * A patch names its files inside its own text rather than in a decoded field,
+ * and the parse that finds them is the same parse that can fail, so there is
+ * nothing here to narrow before the handler runs: the static envelope is the
+ * honest answer.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Capabilities required by the apply_patch flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * Declaration-only apply_patch flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "apply_patch";
+    readonly description: "The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.";
+    readonly input: Schema.Struct<{
+        readonly input: Schema.String;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly output: Schema.String;
+        readonly added: Schema.$Array<Schema.String>;
+        readonly modified: Schema.$Array<Schema.String>;
+        readonly deleted: Schema.$Array<Schema.String>;
+    }>;
+    readonly capabilities: string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const activity: "writes";
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const presentation: {
+    readonly verb: {
+        readonly pending: "patching";
+        readonly success: "patched";
+        readonly failure: "failed to patch";
+    };
+    readonly subject: "patch";
+    readonly result: "patch";
+};
+/**
+ * Every path a patch writes, in the order it names them, including a move's
+ * destination. The patch is read by the parser {@link run} uses, so a header
+ * `run` accepts is never missed.
+ *
+ * Returns `undefined` when `run` would refuse the patch. A caller asking
+ * permission for the call then asks for everything the flow declares.
+ *
+ * @category parsing
+ * @since 1.0.0-rc.1
+ */
+export declare const paths: (patch: string) => ReadonlyArray<string> | undefined;
+/**
+ * Parses and applies a V4A patch through the permission-aware kernel
+ * filesystem, preserving Codex error text.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly input: string;
+}) => Effect.Effect<{
+    readonly output: string;
+    readonly added: readonly string[];
+    readonly modified: readonly string[];
+    readonly deleted: readonly string[];
+}, StdError.StdError, import("effect/Path").Path | FileSystem.FileSystem>;
+//# sourceMappingURL=ApplyPatch.d.ts.map

package/dist/cjs/ApplyPatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApplyPatch.d.ts","sourceRoot":"","sources":["../../src/ApplyPatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAE/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAOvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,gBAAgB,CAAA;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,iHACwF,CAAA;AAEhH;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK;;EAEhB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;;;EAOjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAAuF,CAAA;AAE3G;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,UAAgE,CAAA;AAEzF;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;CAAsF,CAAA;AAEvG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAG,QAAiB,CAAA;AAEzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;;;;;;;;CAIf,CAAA;AAEV;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,aAAa,CAAC,MAAM,CAAC,GAAG,SAc7D,CAAA;AAsBD;;;;;;GAMG;AACH,eAAO,MAAM,GAAG;;;;;;;yEA0Pd,CAAA"}