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

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`.

package/docs/guides/pin-a-checkpoint.md

@@ -0,0 +1,161 @@
+---
+title: "Pin a tree and read it later"
+description: "Record the working tree as a checkpoint, materialize it as a scratch directory for the length of one call, and relocate a read or a command onto it."
+sidebar:
+  order: 6
+---
+
+A checkpoint is a **value**. Minting one changes nothing about the workspace,
+and running a call against one leaves the live tree exactly as it stands. That
+is the whole of what it buys: before it existed, the only way to answer "did
+this fail before my change" was to undo the change, which means reverting the
+very work the reading was meant to prove.
+
+This module is the host half of [`@smthrs/harness`](/api/harness)'s
+`ctx.checkpoint()` and `ctx.call(flow, input, { at })`. The harness owns the
+surface, the identity, the bound, and the refusals; this owns the two host
+operations that need a real tree.
+
+## Bind the git store
+
+```ts
+import * as Checkpoints from "@smthrs/std/Checkpoints"
+
+const store = Checkpoints.layerGit({
+  root: "/workspace/repo", // the host path of the git repository
+  cwd: "/testbed", // where a container sees that same directory
+  baseRef: "refs/flows/capture-base" // optional
+})
+```
+
+`layerGit` requires a `ChildProcessSpawner`. A host that pins nothing binds
+`Checkpoints.layerNoop`, whose refusal says to take the reading on the live tree
+instead.
+
+## Bind the container store
+
+When the repository lives only in a container and `bash` runs there, bind
+`layerContainer` instead. It runs git inside that container through the
+`Container` transport `bash` uses, so `ctx.base` and `ctx.checkpoint()` read the
+container's tree. A git store would look for the repository on the host and
+refuse every call that names a checkpoint.
+
+```ts
+const store = Checkpoints.layerContainer({
+  container: "task", // the container `bash` runs in
+  cwd: "/app" // optional; absent is the container's working directory
+})
+```
+
+`layerContainer` requires a `ChildProcessSpawner` and a `Container`. It records
+and names a checkpoint as the git store does, and checks a tree out at the same
+`<top>/.flows-checkpoints/<id>-<lease>` path inside the container, so a
+relocated `bash` call keeps its subdirectory.
+
+## Capture and materialize
+
+```ts
+import * as Effect from "effect/Effect"
+
+const reading = Effect.gen(function*() {
+  const checkpoints = yield* Checkpoints.Checkpoints
+  const snapshot = yield* checkpoints.capture("before-fix")
+  return yield* checkpoints.materialize(snapshot.id, (tree) => Effect.succeed(tree.host))
+})
+```
+
+`capture(id)` records the working tree as it stands and returns a `Snapshot`
+with the `id` you gave and the store's own `ref` for it. `materialize(id, use)`
+hands the tree back as a directory for the length of the effect you pass, and
+removes it however that effect ends. It is scoped rather than returned, because
+a run killed at its wall-clock budget would otherwise leave a second checkout of
+the whole repository inside the tree whose diff is the run's answer.
+
+A `Materialized` carries four paths, because one directory can have two names:
+
+| Field       | Meaning                                               |
+| ----------- | ----------------------------------------------------- |
+| `host`      | Where a process on this machine finds the checkpoint. |
+| `guest`     | Where a container finds the same directory.           |
+| `root`      | The workspace itself, as this machine names it.       |
+| `guestRoot` | The workspace as a container names it.                |
+
+`Checkpoints.baseId` is `"base"`, the tree the run opened on. It is not minted:
+the store uses `baseRef` when one is declared. A declared ref that
+does not resolve is `not_found`. Otherwise it tries `TestRunner.captureBase`
+and then `HEAD`, matching `test`.
+
+## What the git binding does, and does not do
+
+`layerGit` records with `git stash create`, which is the one git command that
+records the working tree and changes nothing else: it does not move the
+worktree and does not touch the stash ref. It runs against a temporary shadow
+`GIT_DIR` that shares only the workspace's objects and reads a copy of the
+workspace index, so it never writes the agent's index and never runs a hook,
+`core.fsmonitor` command or filter driver the workspace's `.git` names. That matters
+because the agent runs `git` in this same workspace and its own `git diff` is
+the run's evidence. A capture that staged into the real index would be the
+harness editing the evidence while recording it. A tree with nothing to record
+prints nothing, and the checkpoint is then `HEAD`, which is exactly what the
+tree is.
+
+The commit is named in the repository's own git config, under
+`Checkpoints.configSection` (`flows-checkpoint`), and **not** by a ref. A ref is
+history: `git log --all` lists it, `git show` prints it, and `git log --all -S`
+searches it, so a checkpoint named by a ref would hand an agent a commit
+containing its own edit and let it read that back as if it were upstream work.
+Under config the commit object stays unreferenced, a checkout by id works
+perfectly well, and no command that walks refs can reach it.
+
+One command still sees it: `git fsck` reports it as a dangling commit, because
+that is what an unreferenced commit is. A checkout is a standalone repository
+rather than a worktree of the workspace, so `git log --all` in the workspace
+does not list it even while a call runs in it.
+
+Untracked files are not in the recorded tree, which matches how a patch is
+captured. Materialization is a detached checkout at
+`<root>/.flows-checkpoints/<id>-<lease>`, under `Checkpoints.scratchDirectory`.
+Its own `.git` names the commit in `HEAD` and reaches the workspace's objects
+through a relative `objects/info/alternates`, so git run in it through a
+container mount works.
+Each call gets a unique lease, so overlapping calls never remove each other's
+checkout. Existing checkouts are left alone; a `SIGKILL` can leave one behind.
+Inside the workspace is the only placement that works, for the same reason the
+`test` baseline is placed there: a container sees the workspace through a mount,
+and a scratch checkout anywhere else on the host is not visible to it.
+
+## Point a call at a checkpoint
+
+`relocate` rewrites one call's input so the call runs against a materialized
+checkpoint. It is a closed table, not a per-flow hook:
+
+```ts
+const relocation = Checkpoints.relocate("read", { path: "src/widen.ts" }, tree)
+
+if (relocation._tag === "Relocated") {
+  // relocation.input now reads .flows-checkpoints/<id>-<lease>/src/widen.ts
+}
+```
+
+| Flow           | The field it is relocated by                                           |
+| -------------- | ---------------------------------------------------------------------- |
+| `bash`         | `cwd`, into the checkpoint and into the same subdirectory it asked for |
+| `read`, `ls`   | `path`, prefixed with the checkpoint's workspace-relative directory    |
+| `grep`, `glob` | `root`, prefixed the same way                                          |
+
+`bash` is relocated from the guest side when the call names a container, because
+that is the path the container will be given. Keeping the subdirectory matters:
+a check declared in `tests/` that silently ran at the top would come back
+failing for a reason nobody chose.
+
+Three inputs are refused rather than rewritten, and the tag says which:
+
+- `UnsupportedFlow`, for any flow outside that table. `test` is deliberately
+  outside it: it answers this question already with `against: "base"`, and two
+  mechanisms pointed at one tree are two answers that can disagree.
+- `AbsolutePath`, because an absolute path in these runs is a container path and
+  the host cannot know which prefix of it names the tree.
+- `OutsideTree`, for a relative path that climbs past the checkpoint with `..`,
+  which names the live tree under another name. That is exactly the tree the
+  reading was taken to avoid, and a call key folds the checkpoint in, so a live
+  reading recorded under a checkpoint would replay as a pinned one forever.

package/docs/guides/query-a-language-server.md

@@ -0,0 +1,257 @@
+---
+title: "Query a language server"
+description: "Run the ten LSP operations through the lsp flow, spawn a server with NodeLanguageServer, and understand the 1-based coordinates and the pass-through result."
+sidebar:
+  order: 8
+---
+
+`lsp` is one flow with ten operations. It answers the questions a text search
+cannot: where a symbol is defined, who calls it, what type it has.
+
+## Spawn a server
+
+`NodeLanguageServer` speaks framed JSON-RPC over ordinary stdio pipes, spawned
+through [`@smthrs/kernel`](/api/kernel)'s `ChildProcessSpawner`. No terminal is
+involved.
+
+```ts
+import * as NodeLanguageServer from "@smthrs/std/NodeLanguageServer"
+
+const server = NodeLanguageServer.layer({
+  command: "typescript-language-server",
+  args: ["--stdio"],
+  cwd: "/workspace",
+  environment: { NODE_ENV: "development" },
+  timeoutMs: 30_000
+})
+```
+
+The layer sends `initialize` with `cwd` as the root URI and then `initialized`,
+so the service is ready when it resolves. `timeoutMs` defaults to 30 seconds and
+bounds every request as well as every write to the server's standard input.
+The child inherits only `PATH`, `HOME`, `USER`, `LANG`, `LC_*`, `TERM`, `TMPDIR`,
+and `SHELL`, with credential-shaped names withheld. Declare other names through
+`environment`; explicit values override the allowlist.
+
+### Keep the server's code out of the workspace
+
+The server runs on the host as the host user, so a program the workspace
+supplies would let files an agent wrote choose what the host executes. The
+layer fails with `permission_denied`, before spawning, when:
+
+- `command` resolves to a file under `cwd`, directly, through a `PATH` entry
+  such as `node_modules/.bin`, or through a symlink planted there;
+- an argument, or the value after `=` in one, names an existing file under
+  `cwd`;
+- `command` is a launcher whose arguments choose what runs: a shell
+  (`sh -c ...`), `env`, a package runner (`npx`, `pnpm exec`, `npm`, `yarn`,
+  `bunx`, `bun x`, `deno`), or `node` or `bun` given inline code or a preload
+  (`-e`, `-p`, `-r`, `--require`, `--import`, `--loader`). `npx` and
+  `pnpm exec` resolve the workspace's `node_modules/.bin` first, and inline
+  code resolves bare requires from `cwd`. Name the server's own host binary,
+  or an interpreter and a host script file, instead.
+
+The layer cannot see what the server loads after it starts. By default
+typescript-language-server runs the workspace's own `node_modules/typescript`;
+tsserver started with `--allowLocalPluginLoads` loads `tsconfig` plugins from
+the project; rust-analyzer runs build scripts and proc macros. Pin those to
+host copies, or run the server in a sandbox:
+
+```ts
+const server = NodeLanguageServer.layer({
+  command: "/opt/lsp/node_modules/.bin/typescript-language-server",
+  args: ["--stdio"],
+  cwd: "/workspace",
+  initializationOptions: { tsserver: { path: "/opt/lsp/node_modules/typescript/lib/tsserver.js" } }
+})
+```
+
+`initializationOptions` is sent on `initialize` unchanged. With `tsserver.path`
+outside the workspace and local plugin loads left off, tsserver probes for
+plugins only beside its own install.
+
+A host with no server binds `LanguageServer.layerNoop`, and every operation
+fails with `unsupported`.
+
+### One server per language
+
+Pass several configs and each file goes to the server whose `extensions`
+include its extension. A config without `extensions` takes every file no other
+server claims; a file nobody claims fails with `unsupported`.
+`workspaceSymbols` asks every server and concatenates the answers.
+
+`NodeLanguageServer.layerLazy` takes the same configs but starts each server on
+the first request for one of its files, so a host can bind servers a run may
+never need. The workspace checks above still run when the layer is built. A
+server starts with the services and permissions of the code that built the
+layer, not those of the request that first needs it. A server that fails to
+start fails that request and every later one for its files. `refresh` and
+`close` never start a server.
+
+```ts
+const servers = NodeLanguageServer.layer([
+  { command: "typescript-language-server", args: ["--stdio"], cwd: "/workspace", extensions: [".ts", ".tsx"] },
+  { command: "pyright-langserver", args: ["--stdio"], cwd: "/workspace", extensions: [".py"] }
+])
+```
+
+## Edits reach the server
+
+With a `LanguageServer` bound, `edit`, `write` and `apply_patch` send each file
+they write to its server after the entire operation succeeds: `textDocument/didOpen` the first time, then
+`textDocument/didChange` with the full text. A file `apply_patch` deletes or
+moves away gets `textDocument/didClose`. `edit` then returns `errors`, the
+error-severity diagnostics in the file after the edit (at most 20, 1-based
+positions). `errors` is absent when no server is bound or it did not answer;
+the edit itself never fails because of the server.
+
+`bash` does not know which files a command changed, so after a command on the
+host it calls `refresh`: the client re-reads every file it has open, sends the
+text of each that changed, and closes each that is gone. A command run in a
+container leaves the host's files alone and refreshes nothing.
+
+`diagnostics` pulls `textDocument/diagnostic`. A server that answers
+`MethodNotFound` is read from its `textDocument/publishDiagnostics`
+notifications instead: the client opens the file if it is not open yet and waits
+up to `settleMs` (5 seconds by default) for a publish for the latest synced
+text, then fails with `timeout`. After a publish it keeps waiting while later
+ones arrive less than `quietMs` (300 ms by default) apart, within `settleMs`, and
+answers with the last. Either way the answer is a report,
+`{ kind: "full", items }`.
+
+A publish that carries no version counts for the text synced before it arrived.
+Before each sync the client sends a `$/` request, which the specification has
+every server refuse at once, so a report the server wrote earlier (such as the
+empty one typescript-language-server publishes when a file closes) reaches the
+client first and never counts for the new text. A server that does not answer
+within a second is not asked again.
+
+### typescript-language-server
+
+typescript-language-server 6 has no pull diagnostics, publishes without
+versions, and publishes nothing for a change that leaves a file with no
+problems, so such a change always waits the full `settleMs` and fails with
+`timeout`. On the first open of a file it publishes syntax errors before
+semantic ones. Pick `settleMs` and `quietMs` from a measurement on your host:
+
+```sh
+node scripts/lsp-settle-bench.ts <typescript-language-server or gopls> <tsserver.js or -> <workspace> <iterations> <settleMs> <quietMs> <file>...
+```
+
+### Measured settle with real servers
+
+Repeat it with `sh scripts/lsp-real.sh <dir> [iterations] [settleMs] [quietMs]`.
+It installs typescript-language-server 6.0.1 with typescript 5.9.3 (typescript 7
+ships no `tsserver.js`) and, when Go is on `PATH`, gopls under `<dir>`, runs
+`test/NodeLanguageServerReal.test.ts` (a real server on `test/fixtures/lsp/ts`;
+skipped when no server is on `PATH` or named by `SMITHERS_LSP_TLS` and
+`SMITHERS_LSP_TSSERVER`), then writes `<dir>/out/ts.json` and `go.json`. Each
+file is opened with a type error, then cycles fix, comment-only change, restore,
+break, close and reopen, 5 times, at `settleMs` 3000 and `quietMs` 500.
+
+One run on a 14 CPU macOS host at load average 44 to 54, from other agents, on
+the two-file fixtures. Milliseconds from sync to the first publish (raw, p50 and
+max), and to the client's answer:
+
+| Server, step                 | First publish        | Client answer            | Correct                  |
+| ---------------------------- | -------------------- | ------------------------ | ------------------------ |
+| tls, fix                     | 377 to 623, max 1301 | 878 to 908, max 3010     | 9/10                     |
+| tls, break                   | 373 to 401, max 472  | 874 to 887, max 1202     | 10/10                    |
+| tls, reopen                  | 1 to 4, max 33       | 864 to 871, max 930      | 10/10                    |
+| tls, comment-only or restore | none                 | waits `settleMs` (3.0 s) | 1/20, no errors returned |
+| tls, cold open               | none in 4 s          | 3.0 s, `timeout`         | 0/2                      |
+| gopls, every step            | 2 to 5, max 24       | 1 to 3, max 6            | 50/50                    |
+| gopls, cold open             | 252 to 1541          | 415 to 553               | 2/2                      |
+
+`settleMs: 3000` and `quietMs: 500` hold for warm typescript-language-server
+edits. Limitations: one host, loaded, n of 5 per step and 2 files; a cold open
+under load exceeded 3 s for both files, and a change that leaves a file
+clean returns no `errors` after the full `settleMs`. gopls publishes within
+milliseconds, so it never needs more than the defaults. No Python server was
+measured. The raw JSON is written by the script and is not checked in.
+
+## Run a query
+
+```ts
+import * as Lsp from "@smthrs/std/Lsp"
+
+const definition = Lsp.run({
+  operation: "definition",
+  path: "/workspace/src/widen.ts",
+  line: 12,
+  character: 17
+})
+// definition.result is the server's own answer, passed through unchanged
+```
+
+| Operation               | What it takes               |
+| ----------------------- | --------------------------- |
+| `hover`                 | `path`, `line`, `character` |
+| `definition`            | `path`, `line`, `character` |
+| `references`            | `path`, `line`, `character` |
+| `implementation`        | `path`, `line`, `character` |
+| `prepareCallHierarchy`  | `path`, `line`, `character` |
+| `callHierarchyIncoming` | `path`, `line`, `character` |
+| `callHierarchyOutgoing` | `path`, `line`, `character` |
+| `documentSymbols`       | `path`                      |
+| `diagnostics`           | `path`                      |
+| `workspaceSymbols`      | `query`                     |
+
+`line` and `character` are **1-based**, which is how `read` and `grep` report
+them, so a hit from a search is a position you can pass straight in. The flow
+converts to the protocol's 0-based coordinates for you.
+
+`path` must be a normalized absolute path. A relative path, or a missing one for
+any operation except `workspaceSymbols`, fails with `invalid_input`, as does a
+position operation missing `line` or `character`. The server reads the file
+itself, so the flow first reads `path` through the bound `FileSystem`: a path the
+guarded filesystem denies fails with `permission_denied` before the server sees
+it.
+
+`references` includes the declaration. The two call-hierarchy directions run
+`prepareCallHierarchy` first and return an empty array when the server prepares
+no item, so a position that is not a callable is an empty answer rather than a
+failure.
+
+## The result is not a schema
+
+`Output` is `{ result: unknown }`. The server's answer is passed through in the
+server's own shape, because LSP responses vary by server and by version, and
+narrowing them here would be a second, staler schema. Decode it on the caller's
+side against what the server you bound actually returns.
+
+## Bounds a server cannot exceed
+
+The client refuses a malformed or oversized stream rather than growing without
+limit:
+
+| Bound                                     | Value                                               |
+| ----------------------------------------- | --------------------------------------------------- |
+| One JSON-RPC frame body                   | 8 MiB                                               |
+| One frame's headers                       | 8 KiB                                               |
+| `NodeLanguageServer.MAX_QUEUED_FRAMES`    | 256 frames buffered for the server's standard input |
+| `NodeLanguageServer.MAX_PENDING_REQUESTS` | 512 concurrent in-flight requests                   |
+
+Every queued write uses the request timeout, so a server that stops reading
+produces a typed `timeout` rather than an unbounded queue or a new hang. Process
+exit or a closed stdout fails every pending request after at most 100 ms for
+stderr to finish draining.
+
+Request errors include the protocol `method`. A server refusal keeps its numeric
+code, message, and optional data in `StdError.rpcError`; the response frame limit
+bounds that data. The main error message also includes the server message.
+`StdError.stderr`, when present, contains the latest stderr tail, captured from
+at most 64 KiB. Initialization failures and exits retain this diagnostic context.
+
+## Bring your own server
+
+`LanguageServer` is an ordinary service interface: ten query methods, each
+taking a `Position` (`path`, `line`, `character`) or a string, plus
+`sync(path, text)` and `close(path)`. A host with its own client, in-process
+index, or remote service implements those twelve methods and
+binds them with `LanguageServer.make`. Nothing above the service knows which one
+answered.
+
+One detail to implement against: a `Position` reaching the service is already
+**0-based**. The 1-based to 0-based conversion happens in the flow, so the
+service speaks the protocol's own coordinates.