@orkestrel/scaffold 0.0.139 → 0.0.141

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/bin/main.js +86 -26
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +2 -1
  4. package/dist/host/claude/agents/orkestrel.md +51 -51
  5. package/dist/host/claude/rules/architecture.md +4 -2
  6. package/dist/host/claude/rules/typescript.md +23 -10
  7. package/dist/host/configs/policy.ts +174 -11
  8. package/dist/host/guides/abort.md +2 -0
  9. package/dist/host/guides/agent.md +447 -531
  10. package/dist/host/guides/browser.md +1 -1
  11. package/dist/host/guides/guide.md +10 -2
  12. package/dist/host/guides/mcp.md +9 -9
  13. package/dist/host/guides/middleware.md +34 -49
  14. package/dist/host/guides/ollama.md +44 -12
  15. package/dist/host/guides/probe.md +1 -2
  16. package/dist/host/guides/scaffold.md +25 -16
  17. package/dist/host/guides/server.md +5 -5
  18. package/dist/host/guides/study.md +2680 -760
  19. package/dist/host/manifest.json +18 -18
  20. package/dist/host/scripts/browsers.sh +0 -0
  21. package/dist/host/scripts/codex.sh +0 -0
  22. package/dist/host/scripts/cursor.sh +0 -0
  23. package/dist/host/scripts/deps.sh +0 -0
  24. package/dist/host/scripts/npm.sh +0 -0
  25. package/dist/host/scripts/ollama.sh +0 -0
  26. package/dist/host/tests/config.test.ts +185 -1
  27. package/dist/src/core/index.cjs +14 -14
  28. package/dist/src/core/index.cjs.map +1 -1
  29. package/dist/src/core/index.js +14 -14
  30. package/dist/src/core/index.js.map +1 -1
  31. package/dist/src/server/index.cjs +6 -24
  32. package/dist/src/server/index.cjs.map +1 -1
  33. package/dist/src/server/index.d.cts +1 -1
  34. package/dist/src/server/index.d.ts +1 -1
  35. package/dist/src/server/index.js +7 -25
  36. package/dist/src/server/index.js.map +1 -1
  37. package/package.json +11 -11
@@ -103,7 +103,7 @@ Beside those rows, the core face exports what the constructors and the leaves co
103
103
  | `ollamaJudgeOptionsShape` | const | `import("@orkestrel/contract").ObjectShape<{ model: import("@orkestrel/contract").StringShape; system: import("@orkestrel/contract").StringShape; calibration: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ temperature: import("@orkestrel/contract").NumberShape; }, boolean \| import("@orkestrel/contract").ContractShape>>; url: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; keepAlive: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>>; options: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{}, true>>; truncate: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the serializable part of `OllamaJudgeOptions`, the record a judge's constructor checks exactly. |
104
104
  | `ollamaOptionsContract` | const | `ContractInterface<unknown>` | Holds the compiled contract a provider's constructor checks its serializable options against. |
105
105
  | `ollamaJudgeOptionsContract` | const | `ContractInterface<unknown>` | Holds the compiled contract a judge's constructor checks its serializable options against. |
106
- | `OLLAMA_CONTEXT_REMEDY` | const | `"the prompt exceeds the model's context window; set AgentOptions.window to fold the conversation, raise options.num_ctx, or set truncate: true to let the daemon cut it"` | Names what a chat refusal appends when the daemon's text names the context window. |
106
+ | `OLLAMA_CONTEXT_REMEDY` | const | `"the prompt exceeds the model's context window; serve the conversation through createLedger to bound every request, raise options.num_ctx, or set truncate: true to let the daemon cut it"` | Names what a chat refusal appends when the daemon's text names the context window. |
107
107
  | `OLLAMA_JUDGE_CONTEXT_REMEDY` | const | `"the prompt exceeds the model's context window; shorten the state, raise options.num_ctx, or set truncate: true to let the daemon cut it"` | Names what a judge refusal appends when the daemon's text names the context window. |
108
108
  | `scanOptionFaults` | function | `(contract: ContractInterface<unknown>, options: object, live: readonly string[]) => readonly AuditFault[]` | Scans a constructor's options against a contract, leaving out the live values and every key set to `undefined`. |
109
109
  | `matchesContextRefusal` | function | `(text: string) => boolean` | Checks whether a daemon's refusal text names the context window. |
@@ -122,7 +122,7 @@ The reach is measured on one model and one daemon. On Ollama 0.40.14 with `qwen3
122
122
 
123
123
  A false positive costs an invisible character: text that spells a listed token reaches the model with U+200B inside it, and a model can copy that character into a file.
124
124
 
125
- `OllamaProvider` declares `name` (`'ollama'`) and inherits the rest of its data members from the base: `id` is the stable per-instance trace label, and `replay` selects which stored assistant reasoning reaches the provider input (default `'none'`). The Ollama request mapper omits stored reasoning from the wire regardless of that policy. Its wire seams are documented under [Methods](#methods), and the `generate` / `stream` boundary it inherits under `AgentProviderInterface` in [`agent.md`](agent.md). `AgentProvider` / `AgentProviderInterface` / `ProviderInterface` / `ProviderOptions` / `ProviderRequest` / `ProviderIncrement` / `ProviderParserInterface` / `ProviderResult` / `ProviderDelta` / `ProviderStreamOptions` / `ProviderError` / `isProviderError` / `ProviderAbortError` / `isProviderAbortError` / `Message` / `ContextSectionFormat` / `InstructionInterface` are owned by `@orkestrel/agent`; `ToolDefinition` / `ToolCall` by `@orkestrel/tool`; the `TokenUsage` shape by `@orkestrel/budget`; `createNDJSONParser` by `@orkestrel/ndjson`. All are reused here, never redefined. The agent package also owns the `JudgeInterface` interface, `JudgeRequest` type, `JudgeResult` interface, `JudgeAnswer` type, `Refusal` interface, `AgentJudge` class, `JudgeError` class, `JudgeAbortError` class, and `measureAnswer` function.
125
+ `OllamaProvider` declares `name` (`'ollama'`) and inherits the rest of its data members from the base: `id` is the stable per-instance trace label, `model` is the tag the constructor received, which every request body names, and `replay` selects which stored assistant reasoning reaches the provider input (default `'none'`). The Ollama request mapper omits stored reasoning from the wire regardless of that policy. Its wire seams are documented under [Methods](#methods), and the `generate` / `stream` boundary it inherits under `AgentProviderInterface` in [`agent.md`](agent.md). `AgentProvider` / `AgentProviderInterface` / `ProviderInterface` / `ProviderOptions` / `ProviderRequest` / `ProviderIncrement` / `ProviderParserInterface` / `ProviderResult` / `ProviderDelta` / `ProviderStreamOptions` / `ProviderError` / `isProviderError` / `ProviderAbortError` / `isProviderAbortError` / `Message` / `ContextSectionFormat` / `InstructionInterface` are owned by `@orkestrel/agent`; `ToolDefinition` / `ToolCall` by `@orkestrel/tool`; the `TokenUsage` shape by `@orkestrel/budget`; `createNDJSONParser` by `@orkestrel/ndjson`. All are reused here, never redefined. The agent package also owns the `JudgeInterface` interface, `JudgeRequest` type, `JudgeResult` interface, `JudgeAnswer` type, `Refusal` interface, `AgentJudge` class, `JudgeError` class, `JudgeAbortError` class, and `measureAnswer` function.
126
126
 
127
127
  The raw judge exports the following declarations.
128
128
 
@@ -204,6 +204,28 @@ The session composes the following validators and protocol helpers, each exporte
204
204
 
205
205
  `OllamaDaemonInterface` keeps its data members in its row: `url` is the declared origin, `identity` is the verified startup receipt (`undefined` before verification and kept after stop), `maintenance` is every unload attempt in sequence order, and `emitter` is the typed lifecycle surface. Its lifecycle methods are documented under [Methods](#methods). `DuplexOptions` is owned by `@orkestrel/process`, and `EmitterInterface`, `EmitterHooks`, and `EmitterErrorHandler` by `@orkestrel/emitter`; the server face reuses them and redefines none of them.
206
206
 
207
+ The server face also exports a loopback protocol fixture, which hands each logged request to a reply callback before any built-in answer, together with its options guard and the builders that write Ollama's wire bodies.
208
+
209
+ | Name | Kind | Signature | Summary |
210
+ | ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
211
+ | `createOllamaFixture` | function | `(options: OllamaFixtureOptions) => Promise<OllamaFixtureInterface>` | Creates a fixture and resolves after it listens. |
212
+ | `OllamaFixture` | class | `new (options: OllamaFixtureOptions) => OllamaFixtureInterface` | Serves Ollama's protocol on a loopback port, handing each logged request to the reply callback before any built-in answer. |
213
+ | `OllamaFixtureInterface` | interface | `{ url, requests, emitter, start(), destroy() }` | Owns a loopback Ollama protocol fixture from `start` through `destroy`. |
214
+ | `OllamaFixtureOptions` | interface | `{ on?, error?, models, version, context, reply? }` | Configures a fixture's listed models, reported version, context length, reply callback, and listeners. |
215
+ | `OllamaFixtureRequest` | interface | `{ method, path, headers, body }` | Records one received request: its method, path, headers, and whole body text. |
216
+ | `OllamaFixtureHandler` | type | `(request: OllamaFixtureRequest, signal: AbortSignal) => Response \| undefined \| Promise<Response \| undefined>` | Defines the reply callback, which answers a logged request with a `Response` or declines it with `undefined`. |
217
+ | `OllamaFixtureEventMap` | type | `{ readonly request: readonly [request: OllamaFixtureRequest]; readonly error: readonly [error: unknown]; }` | Reports logged requests and serving failures. |
218
+ | `isOllamaFixtureOptions` | function | `(value: unknown) => value is OllamaFixtureOptions` | Checks whether a value configures a fixture with unique model names, a nonempty version, and a positive integer context. |
219
+ | `buildOllamaAnswer` | function | `(request: OllamaFixtureRequest, options: Pick<OllamaFixtureOptions, 'models' \| 'version' \| 'context'>) => Response` | Builds the answer a fixture gives a request its reply callback declines. |
220
+ | `buildOllamaReply` | function | `(options?: OllamaReplyOptions) => string` | Builds an NDJSON chat reply: a delta row for each part, then one terminal row. |
221
+ | `buildOllamaReadout` | function | `(options: OllamaReadoutOptions) => string` | Builds a one-token raw generate reply carrying the token's top logprob list. |
222
+ | `buildOllamaInventory` | function | `(models: readonly OllamaModel[]) => string` | Builds a `/api/tags` listing body for the given models, in the shape a real daemon sends. |
223
+ | `buildOllamaTiming` | function | `(durations?: Partial<OllamaDurations>, counts?: Partial<OllamaCounts>) => Readonly<Record<string, number>>` | Builds the timing fields of a terminal wire record, leaving out every member that is not set. |
224
+ | `OllamaReplyOptions` | interface | `{ model?, content?, parts?, thinking?, calls?, reason?, counts?, durations? }` | Configures a chat reply's delta rows and its terminal row. |
225
+ | `OllamaReadoutOptions` | interface | `{ model?, token, top, counts? }` | Configures a one-token judge readout: the chosen token, its top list, and an optional model and counts. |
226
+ | `OLLAMA_FIXTURE_KEYS` | const | `readonly string[]` | Lists the keys the fixture options admit, live values included. |
227
+ | `OLLAMA_FIXTURE_TIME` | const | `"2026-10-23T14:08:45.7014834Z"` | Names the fixed timestamp a fixture writes as each listed model's `modified_at` and each unload reply's `created_at`. |
228
+
207
229
  ## Methods
208
230
 
209
231
  Each following table lists the methods one class or interface declares. The wire seams `OllamaProvider` declares are exactly the members of `AgentProviderInterface` that the base leaves open. The runtime never calls them directly: a caller drives `generate` or `stream`, and the engine calls these to frame, project, decode, and drain the Ollama wire. Those inherited calls, the `id` / `name` / `format` data members, and the `ProviderParserInterface` the seam returns are documented in [`agent.md`](agent.md).
@@ -239,9 +261,18 @@ A caller drives these methods directly, in the order [Daemon session](#daemon-se
239
261
  | `stop` | `Promise<boolean>` | Permanently stops the owned tree, joins its session, and re-hashes the executable. |
240
262
  | `destroy` | `Promise<void>` | Stops the daemon and releases its observation emitter after cleanup settles. |
241
263
 
264
+ #### `OllamaFixtureInterface`
265
+
266
+ `createOllamaFixture` calls `start` before it resolves, and a caller calls `destroy` when it is done. `OllamaFixture` implements both and exposes no other public method.
267
+
268
+ | Method | Returns | Summary |
269
+ | --------- | --------------- | --------------------------------------------------------------------------------------------------------- |
270
+ | `start` | `Promise<void>` | Listens on an ephemeral port on `127.0.0.1` and records the origin in `url`. |
271
+ | `destroy` | `Promise<void>` | Aborts every callback signal, cancels each held body, closes the listener, and releases the emitter last. |
272
+
242
273
  ## Contract
243
274
 
244
- These invariants hold across `src/core`, `src/server`, and `ollama.md`. The doc ↔ source bijection and the method bijection cover both faces, and the rest state the core face; [Daemon session](#daemon-session) states the server face's lifecycle, detection forms, and limits. The engine contract itself — `ProviderInterface`, `AgentProvider`, `ProviderResult`, `ProviderError`, `ProviderAbortError` — is in `@orkestrel/agent`, and [`agent.md`](agent.md) states it.
275
+ These invariants hold across `src/core`, `src/server`, and `ollama.md`. The doc ↔ source bijection and the method bijection cover both faces, and the rest state the core face; [Daemon session](#daemon-session) states the daemon session's lifecycle, detection forms, and limits. The engine contract itself — `ProviderInterface`, `AgentProvider`, `ProviderResult`, `ProviderError`, `ProviderAbortError` — is in `@orkestrel/agent`, and [`agent.md`](agent.md) states it.
245
276
 
246
277
  1. **Doc ↔ source bijection.** Every `function` / `class` / `const` / `interface` / `type` row in the `## Surface` tables is a real export of the `src/core` or `src/server` surface, and every export of either barrel appears as a Surface row — exhaustive, both directions.
247
278
  2. **Imports each boundary from its owner, no cycle.** `OllamaProvider` extends `AgentProvider` and implements `AgentProviderInterface`; that base, `ProviderRequest`, `ProviderIncrement`, `ProviderParserInterface`, `ProviderInterface`, `ProviderOptions`, and `Message` come from `@orkestrel/agent`. `createNDJSONParser` comes from `@orkestrel/ndjson`, `ToolCall` from `@orkestrel/tool`, `TokenUsage` from `@orkestrel/budget`, and the guards (`isRecord` / `isString` / `isNumber` / `isNonNegativeInteger` / `parseJSONAs`) from `@orkestrel/contract`. The provider errors are owned by `@orkestrel/agent` and `ToolDefinition` by `@orkestrel/tool`: `src/core` throws those errors for a malformed record or malformed options, and the base accepts the `ToolDefinition[]` a call advertises. `describeFaults` comes from `@orkestrel/tool` and writes a refused option's lines. Each dependency is one-way and never imports from `@src/core`. No module under `src/` imports `@orkestrel/timeout` — the base arms the deadline — and the manifest declares it as a development dependency for the guide's bounding pattern, which imports it as a consumer would.
@@ -254,13 +285,13 @@ These invariants hold across `src/core`, `src/server`, and `ollama.md`. The doc
254
285
  9. **Boundary narrowing — all wire `unknown` through guards, never `as`.** Every value read off the wire (each NDJSON record, `message`, `content`, `thinking`, the usage counts, `tool_calls`, `arguments`) arrives as `unknown` and is narrowed through the `@orkestrel/contract` guards — never a type assertion. A record that leaves out `message`, `content`, `thinking`, or `tool_calls` reads as empty, and one that carries any of them malformed refuses as `ProviderError` `'PROTOCOL'` — the one external boundary kept honest.
255
286
  10. **The base owns everything that is not the wire.** The per-call deadline (`OllamaOptions.timeout`, `120_000`ms when omitted, folded with the caller's signal so either cancels the request and the timer is always cleared), the cancellation rule (a `stream` cancelled mid-flight throws `ProviderAbortError` carrying the partial, and the reader and parser are released in a `finally`), the transport seam (`OllamaOptions.fetch` and the per-request `OllamaOptions.headers` hook, awaited inside the deadline and raced against the combined signal), and the bounded error read all live in `AgentProvider`. `OllamaOptions` extends `ProviderOptions`, so those keys are the base's and behave identically for every provider built on it; [`agent.md`](agent.md) defines those rules.
256
287
  11. **Context framing.** An instruction manager accepts a `ContextSectionFormat<InstructionInterface>` through `createInstructionManager({ format })`. The agent uses that manager to build the instruction text. Ollama structured output uses the separate per-call `ProviderStreamOptions.schema` value, forwarded as the wire `format` field.
257
- 12. **Event-free.** The provider and the judge are a pure functional boundary — no Emitter, no events. Each call is a function of its arguments. The server face's daemon session is the one emitter in the package, through `OllamaDaemonInterface.emitter`.
288
+ 12. **Event-free.** The provider and the judge are a pure functional boundary — no Emitter, no events. Each call is a function of its arguments. The server face's daemon session and protocol fixture are the package's emitters, through `OllamaDaemonInterface.emitter` and `OllamaFixtureInterface.emitter`.
258
289
  13. **A core face that runs in a browser.** The `.` entry is built from `src/core`, which imports no `node:*` module and no DOM global; the scoped core typecheck compiles it with the `ESNext` and `WebWorker` libraries and no ambient `@types`, so neither Node's globals nor the DOM's are in scope, and the base binds `globalThis.fetch` to its own receiver so a browser does not throw `Illegal invocation` on a bare transport reference. The `./server` entry, built from `src/server`, imports Node modules and the process session, so a browser bundle takes the `.` entry alone. [`tests/service/page.test.ts`](../tests/service/page.test.ts) gates that claim rather than recording it: it launches the host's own Chrome or Edge through `@orkestrel/browser`, serves the built `@orkestrel/ollama` core entry and its whole `@orkestrel` import closure from an import map on a `127.0.0.1` fixture, and reads the page's requests from the browser's own request log. The page loads with no uncaught error and no console error, on the recorders a deliberate page fault then makes report; an `Agent` holding a page-defined DOM-writing `Tool` completes a tool loop against the live daemon through a same-origin `createRelay` server, where the model's recorded call reaches the page, the tool's minted receipt is read back out of the real DOM and found again as the `role: 'tool'` message of the relay request and the `/api/chat` request that follow the turn the call was dispatched in, and the run settles with `partial: false`; the page issues exactly one `POST /inference` per turn and nothing else across the whole operation window, with a deliberate `/control` request proving such a window can report one; a wrong bearer arrives as `ProviderError` with code `'HTTP'` and status `401` with no daemon request made; and `createOllama` in the page answers a prompt over `/api/chat` on the daemon's own origin after `requireDaemonOrigin` confirms the daemon permits the page's origin. Each attempt ends within its allowance plus its release share, so nothing the attempt schedules outlasts the case that holds it. The attempt's signal cancels the part of the connection the installed `BrowserOptions.signal` races — discovery, the port-free check, the launch, and `client.connect()` — and the attempt's own race is what bounds every phase after that, the target listing the connection ends with included; [`tests/service/page.test.ts`](../tests/service/page.test.ts) and the `PAGE_BOUNDS` table it spends state the mechanism. The model's choice to call a tool is retried at most 3 times, and that choice is the only reading another attempt buys: every attempt retains its observations before any page read can throw, and only a run that completed an answer without dispatching the tool spends another launch. An acquisition, read, release, or run failure ends the retry, and so does a run that deadline interrupted before it settled — an interrupted run reports no tool call for a reason another launch cannot clear, so retrying it would report the exhaustion as the model never choosing the tool. The request accounting is asserted over each retained attempt, so what the gate establishes is that the model called the tool within those attempts and that no attempt's traffic went unread. The daemon is the remaining limit — a page reaches `/api/chat` directly only where the daemon, or a proxy in front of it, answers the page's origin; otherwise relay the call through your own server ([Relaying through your own server](#relaying-through-your-own-server)).
259
290
  14. **Tested live against a real local Ollama (no `skipIf`).** The live tests run against a real Ollama daemon — no mocks, only genuine third-party calls — model `qwen3.5:4b-q4_K_M`, with `OLLAMA_HOST` / `OLLAMA_MODEL` overridable. Unlike the other surfaces, the dedicated `service` project requires the daemon: `tests/setupService.ts` throws a clear error if it is unreachable and warms the model (a `num_predict: 1` chat) before the suite, so the live tests run unconditionally (no `describe.skipIf`). The project runs serially (`fileParallelism: false`) with a 120s test/hook timeout so a cold load cannot flake it; `keep_alive` keeps the model resident across files, and `bash scripts/ollama.sh` brings the daemon and model up before the battery in CI. Assertions are structural — they hold whatever wording a small model produces — and never pin exact output. The hermetic half sits in `tests/src/core/`, and the relay round trip is proved hermetically in [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) and live in [`tests/service/relay.test.ts`](../tests/service/relay.test.ts).
260
- 15. **Doc ↔ source method bijection.** Each `## Methods` table lists the methods its class or interface declares: `frame`, `encode`, `read`, and `finish` for `OllamaProvider`; `encode` and `read` for `OllamaJudge`; `start`, `unload`, `stop`, and `destroy` for `OllamaDaemonInterface`, which `OllamaDaemon` implements with no other public method. The inherited `generate`, `stream`, and `ask` methods are declared by the agent package's engines, and the two overrides of `stream` and `ask` add only the context remedy.
291
+ 15. **Doc ↔ source method bijection.** Each `## Methods` table lists the methods its class or interface declares: `frame`, `encode`, `read`, and `finish` for `OllamaProvider`; `encode` and `read` for `OllamaJudge`; `start`, `unload`, `stop`, and `destroy` for `OllamaDaemonInterface`, which `OllamaDaemon` implements with no other public method; and `start` and `destroy` for `OllamaFixtureInterface`, which `OllamaFixture` implements with no other public method. The inherited `generate`, `stream`, and `ask` methods are declared by the agent package's engines, and the two overrides of `stream` and `ask` add only the context remedy.
261
292
 
262
293
  16. **Render.** The raw prompt mirrors the TypeSafe adapter path of Mica's server: the `rows_from_request` function in the `typesafe_server.py` file followed by the `prompt_for` function in the `native.py` file. Structured state uses JSON with a one-space indent and JavaScript numeric spelling: JavaScript cannot distinguish 100.0 from 100 and spells an exponent as 1e-7 where Python spells 1e-07. Parity is byte-exact for string states and structured states whose numbers spell the same in both runtimes. The wire preserves the system prompt and escapes control tokens in state, instructions, option names, and descriptions with U+200B after the opening angle bracket. Noul criteria render false before true; an absent or empty side renders its key. A question with blank instructions and no candidate text refuses with the `QUESTION` code, because a choice's name counts as text and nothing else would reach the model. Choice names render in brackets unless empty, positional (including Unicode decimal digits), or equal to the wire label. A null description renders the `None` text. Score levels omit names. The assistant suffix disables thinking with the `<think>\n\n</think>\n\n` text.
263
- 17. **Readout.** The wire sends each question in its own `POST` request to the `OLLAMA_GENERATE_PATH` endpoint. Each body carries the `raw: true`, `stream: false`, `logprobs: true`, `top_logprobs: 20`, and `truncate: false` settings; `OllamaJudgeOptions.truncate` sets the last. The fixed `num_predict: 1` and `temperature: 1` settings override the caller's sampling settings. Calibration divides candidate logprob gaps by its finite positive temperature before a softmax over candidates alone. The `extractTopLogprobs` function reads only the `logprobs[0].top_logprobs` list and preserves token text. Malformed or duplicate entries raise a `JudgeError` error with the `PROTOCOL` code. The wire reads usage from a completed record through the `extractUsage` function, and a present count that is not a finite nonnegative number raises the `PROTOCOL` code. A `model` that is present and is not the configured tag raises the same code.
294
+ 17. **Readout.** The wire sends each question in its own `POST` request to the `OLLAMA_GENERATE_PATH` endpoint. Each body carries the `raw: true`, `stream: false`, `logprobs: true`, `top_logprobs: 20`, and `truncate: false` settings; `OllamaJudgeOptions.truncate` sets the last. The fixed `num_predict: 1` and `temperature: 1` settings override the caller's sampling settings. Calibration divides candidate logprob gaps by its finite positive temperature before a softmax over candidates alone. The `extractTopLogprobs` function reads only the `logprobs[0].top_logprobs` list and preserves token text. Malformed entries raise a `JudgeError` error with the `PROTOCOL` code, even when a token repeats. A top list that repeats a token refuses that question, and its `missing` collection names every candidate key. The wire reads usage from a completed record through the `extractUsage` function, and a present count that is not a finite nonnegative number raises the `PROTOCOL` code. A `model` that is present and is not the configured tag raises the same code.
264
295
  18. **Refusal.** A label outside the top list refuses that question. The `missing` collection names the caller's option, level index, or the `false` or `true` key. The wire still answers the other questions and the result keeps the spent usage. A missing label never receives an invented probability.
265
296
  19. **Limits.** A choice admits 2 to 20 options and a score 2 to 10 levels. A request outside those limits raises a `JudgeError` error with the `QUESTION` code. Structured instructions or criteria raise the same error before inference because the Mica server flattens them with Python's `str()` function. The engine validates every body before making a transport call. The `keepAlive` setting accepts a duration string or a number and defaults to the `DEFAULT_KEEP_ALIVE` value. The daemon enforces its context window, and an over-long prompt raises a `JudgeError` error with the `HTTP` code, status 400, and `OLLAMA_JUDGE_CONTEXT_REMEDY`. The caller selects the wire.
266
297
  20. **Identity and cancellation.** The `judge.model` property and every `JudgeResult.model` property carry a JSON tuple of the model tag, system prompt, effective calibration temperature, effective options with sorted keys, and the `MICA_RENDER_REVISION` value. The effective options include the fixed `num_predict: 1` and `temperature: 1` settings. A judge set to `truncate: true` appends the switch to the tuple, because a cut prompt can answer differently, and the default leaves the tuple unchanged, because a prompt that fits renders and answers the same. Equal option bags yield one identity regardless of key order; a changed effective option changes it. Each call has the inherited deadline and header hook. Cancellation raises a `JudgeAbortError` error carrying the completed calls' answers, refusals, and usage.
@@ -579,6 +610,7 @@ const messages = [{ id: '1', role: 'user', content: 'Say hello.' }] as const
579
610
 
580
611
  const browser = createRelayProvider({
581
612
  url,
613
+ model: 'qwen3.5:2b-q4_K_M', // the model the server half's provider serves
582
614
  headers: () => ({ authorization: 'Bearer session-token' }),
583
615
  })
584
616
  const relayed = await browser.generate(messages, abort.signal)
@@ -676,7 +708,7 @@ A provider and a judge send `truncate: false`, so the daemon refuses a prompt ov
676
708
  - **`truncate` omitted or `true`.** The daemon answers HTTP 200 with `done_reason: 'stop'`, the earlier turn dropped whole, and nothing that flags the cut: asked what the first note says, the model invented an answer. `read` has nothing to project, so `ProviderResult.truncated` stays absent.
677
709
  - **`shift`.** `shift: false` stops no prompt cut. At 2014 prompt tokens of 2048 with `num_predict: 300`, `shift` omitted, `true`, and `false` each ended with HTTP 200, `done_reason: 'length'`, and an `eval_count` of 34, so the daemon stops at the window and `read` reports that as `truncated`. `OllamaOptions.shift` stays an option a host sets, and the provider sends no key otherwise.
678
710
 
679
- Set `AgentOptions.window` to fold the conversation before the provider call, raise `options.num_ctx`, or set `truncate: true` to let the daemon cut the prompt. Set `window` well under `num_ctx`: real prompt tokens ran 1.23 to 1.78 times `estimateTokens` on the same daemon, and an over-window request refuses.
711
+ Serve the conversation through `createLedger`, which bounds every request it sends, raise `options.num_ctx`, or set `truncate: true` to let the daemon cut the prompt.
680
712
 
681
713
  The default changes the request body, so `StudyOllamaReplay` refuses a recorded prefix made before it. That is a new replay lineage, so screen the model and the daemon again before you record it, as you would after a daemon change.
682
714
 
@@ -829,7 +861,7 @@ timing?.invalid // []
829
861
  - **Give a thinking model headroom** — with `think: true`, a reasoning model (for example `qwen3.5:2b` at `temperature: 0`) can spend 200+ tokens on `message.thinking` before any `content` token arrives; a tight `num_predict` cap ends the turn before content starts, yielding empty `result.content` with `result.truncated` set, and a tight external token budget exhausts on the usage the turn reports. Size `num_predict` and the budget with thinking overhead in mind for any model run with `think: true`.
830
862
  - **Read the model layer** — a `num_predict` cap reached sets `result.truncated`, and an agent run ending there reports `stop.layer: 'model'`. A prompt the daemon cuts under `truncate: true` returns normally and is not reported.
831
863
  - **Tune through `options`** — pass sampling parameters (`temperature`, `seed`, and `num_predict`) through `OllamaOptions.options`; they forward verbatim to the wire.
832
- - **Keep the refusal** — leave `OllamaOptions.truncate` at its `false` default so an oversized prompt refuses, and set `AgentOptions.window` or `options.num_ctx` to fit it. Set `truncate: true` only where losing the earlier turns silently is acceptable.
864
+ - **Keep the refusal** — leave `OllamaOptions.truncate` at its `false` default so an oversized prompt refuses, and serve the conversation through `createLedger` or raise `options.num_ctx` to fit it. Set `truncate: true` only where losing the earlier turns silently is acceptable.
833
865
  - **Observe at the call site** — the provider publishes no events; read `stream`'s deltas and its returned result for everything a turn produced.
834
866
 
835
867
  ## Tests
@@ -849,12 +881,12 @@ The daemon session proofs run in the `src:server` project against `tests/src/ser
849
881
 
850
882
  The hermetic projects — `src:core`, `src:server`, `setup`, `guides`, `conformance`, `policy`, and `config` — run with no Ollama daemon and no network beyond loopback. The `src:server` project starts no Ollama executable: its lifecycle proofs spawn the fake daemon and bind loopback ports only. The `service` project requires a warm local Ollama and, for the page proof, a Chromium-family browser and a built `dist`, and for the daemon session proof an executable on `PATH`, an `OLLAMA_DAEMON_EXECUTABLE` path, or an explicit `OLLAMA_DAEMON_DECLARATION` value; `distribution` packs and installs the artifact. The import guard reads `distribution` with the hermetic projects, because it never reaches the daemon; it leaves out `probe` and `service` alone, the two projects that may.
851
883
 
852
- - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` and `src/server` bijection (value + type exports), the `OllamaProvider`, `OllamaJudge`, and `OllamaDaemonInterface` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, each titled fence — `Ask Mica a noul` and `createOllama + generate` — against the `@example` block of that title, with `Ask Mica a noul` pinned so the titled pair cannot be retired silently, and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values they log. Of the server face's fences, it runs the declaration refusal, the model digest comparison, and the retained unload reply, none of which starts a process, and never runs the dedicated daemon fence, which starts a real executable. It extracts each streaming fence from the README and from this guide and executes it, with its real imports and a global `fetch` the test replaces, over the turns the fence handles: this guide's over a plain, a reclassified, a cancelled, and a refused turn, and the README's, which has no `catch` arm, over the plain and the reclassified turn. It asserts the logged values, the deltas, the fence's message list, the whole body of each request, and the error the fence throws.
884
+ - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` and `src/server` bijection (value + type exports), the `OllamaProvider`, `OllamaJudge`, `OllamaDaemonInterface`, and `OllamaFixtureInterface` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, each titled fence — `Ask Mica a noul` and `createOllama + generate` — against the `@example` block of that title, with `Ask Mica a noul` pinned so the titled pair cannot be retired silently, and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values they log. Of the server face's fences, it runs the declaration refusal, the model digest comparison, and the retained unload reply, none of which starts a process, and never runs the dedicated daemon fence, which starts a real executable. It extracts each streaming fence from the README and from this guide and executes it, with its real imports and a global `fetch` the test replaces, over the turns the fence handles: this guide's over a plain, a reclassified, a cancelled, and a refused turn, and the README's, which has no `catch` arm, over the plain and the reclassified turn. It asserts the logged values, the deltas, the fence's message list, the whole body of each request, and the error the fence throws.
853
885
  - [`tests/src/core/OllamaProvider.test.ts`](../tests/src/core/OllamaProvider.test.ts) — hermetic provider request-shape (including the default `truncate` key and the opt-in `shift` key), options, framing, transport-seam, abort, deadline, and unreachable-upstream coverage, the wire refusals — an in-band error, another model, a model load, a malformed record, empty `messages`, a stream cut before `done`, and the context remedy — plus the streaming fold — deltas, tool-call accumulation, done-line usage, the `done_reason: 'length'` truncation and its stray-reason refusals, the unterminated tail flush, and think separation — driven over a canned NDJSON transport. Its recording proxy uses a deliberately unreachable default and asserts only captured requests and local provider behavior.
854
886
  - [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the wire leaves: the request projection with its control-token escape and every response extraction, including each malformed-wire refusal, the `done_reason` reader's `'length'`, other-reason, missing, and non-string cases, and the terminal timing reader's verbatim nanoseconds, zero, absent, malformed, and `done` cases.
855
887
  - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — hermetic `createOllama` shape, identity, defaults, passthrough, and unreachable-upstream coverage.
856
- - [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) — the `src/core` integration scope. A real `@orkestrel/server` + `@orkestrel/router` relay in front of this provider carries ordered content and thinking deltas, tools, and usage while keeping the browser and daemon credentials apart, refuses a wrong bearer with an empty `401` before the daemon transport is entered, crosses a browser cancel and a server deadline as an abort frame with its partial, reduces a daemon stream failure to the fixed public error frame, and replays a returned tool call. Beside those, a real agent over a canned NDJSON stream reports the model, meter, and budget layers in `result.stop`, and hermetic context framing, recap, reference, cherry-pick, canonical assembly order, scope allow-lists, workspace injection, and conversation selection run through the unreachable recording proxy, with a compile-time drift gate asserting the wire request and response shapes stay compatible with the official `ollama` client's types; that gate's authoritative check is `npm run check` (root tsc), while its run under vitest is an incidental no-op (`expectTypeOf` performs no runtime assertions).
857
- - [`tests/setup.test.ts`](../tests/setup.test.ts) — the shared host-independent test infrastructure, over the conversation padding, the window consumers, the throwing and recording summarizers, the workspace seeder, and the `PAGE_TOOL` definition `tests/setup.ts` exports, and over the host-independent half of `tests/setupServer.ts`: its request-narrowing guards, its refusing and streaming transports, its tool fixtures, its scripted agent stream and agent-stream driver, and its environment readers.
888
+ - [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) — the `src/core` integration scope. A real `@orkestrel/server` + `@orkestrel/router` relay in front of this provider carries ordered content and thinking deltas, tools, and usage while keeping the browser and daemon credentials apart, refuses a wrong bearer with an empty `401` before the daemon transport is entered, crosses a browser cancel and a server deadline as an abort frame with its partial, reduces a daemon stream failure to the fixed public error frame, and replays a returned tool call. Beside those, a real agent over a canned NDJSON stream reports the model, meter, and budget layers in `result.stop`, and hermetic context framing, reference, cherry-pick, canonical assembly order, scope allow-lists, workspace injection, and conversation selection run through the unreachable recording proxy, with a compile-time drift gate asserting the wire request and response shapes stay compatible with the official `ollama` client's types; that gate's authoritative check is `npm run check` (root tsc), while its run under vitest is an incidental no-op (`expectTypeOf` performs no runtime assertions).
889
+ - [`tests/setup.test.ts`](../tests/setup.test.ts) — the shared host-independent test infrastructure, over the conversation padding, the workspace seeder, and the `PAGE_TOOL` definition `tests/setup.ts` exports, and over the host-independent half of `tests/setupServer.ts`: its request-narrowing guards, its refusing and streaming transports, its tool fixtures, its scripted agent stream and agent-stream driver, and its environment readers.
858
890
  - [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the Node-resource half of `tests/setupServer.ts`: the daemon fixtures the `src:server` proofs use — the fake daemon declarations built without starting a child, and the in-process peer that answers the metadata and unload routes and records each request's exact bytes — the recording proxy and the relay server on real loopback sockets, the captured and open transports, whose fixtures answer in memory, the capture wait, the provider-stream driver, the wire tables `WEATHER_TOOL` and the insatiable tool's chunk line, and the page fixture's Node half — the request recorder the relay server and the page fixture share, the derived import map, the served document's presence guards, the contained file route, the control route, the port reservation, the membership the page bounds declare — the attempt allowance, the release share beside it, the per-call shares spent inside them, the case bound that contains the pair, and the launch count the retry spends — the ordering the live controls' own intervals hold, the attempt deadline's own expiry error, the elapsed completion a bounded attempt reports on each interleaving that can outlast it (an acquisition that never settles, one that settles inside the release share, a release that parks past that share, and a release that crossed the allowance), each of those measured against the deadlines it had to wait out plus one named scheduling allowance, so what the case proves is timer-bounded completion rather than a nominal sum, the failure each of them keeps reachable as its cause — the attempt's own failure under a composed strand, and the deadline's `TimeoutError` under a crossed release — the reading each thrown failure carries into a composed message, the decision the bounded retry's predicate makes over an inert attempt record, including the interrupted run it refuses, the release order a real fixture takes when the release after it rejects, the evaluate boundary's narrowing and the deadline it carries, the guards that narrow what the page reports back, the live page proof's browser and build gates — a host with no browser and a tree with no build — the scenarios that capture the first request a provider sends through a recording proxy, each ending the call by aborting it, awaiting it, or leaving it open, the readers and runners that measure a packed package, proved against a dependency-free fixture package and a loopback registry that answers only `ping`, and the guard that keeps every hermetic project from importing `tests/setupService.ts`, which contacts the daemon when it loads: it takes the projects from `vite.config.ts`, follows every import form to a fixed point, and refuses the module as a setup file. It compares the files that references and setup paths resolve to, never their spelling, so a backslash separator, a letter case the host folds, and a query after the path cannot hide the module, while a `?raw` or `?url` import stays an asset. It refuses a `new URL(…, import.meta.url)` built at run time as it refuses a computed `import()`, apart from `vite.config.ts`, whose computed URL is inspected and listed.
859
891
  - [`tests/setupService.test.ts`](../tests/setupService.test.ts) — the hermetic half of the `service` project's setup: the environment readers, the sampling tables, the readiness contract, and the live page gate's refusal of an origin the daemon refuses.
860
892
  - [`tests/conformance.test.ts`](../tests/conformance.test.ts) — where this package's wire types drift from the official `ollama` client they are written against.
@@ -868,7 +900,7 @@ The hermetic projects — `src:core`, `src:server`, `setup`, `guides`, `conforma
868
900
  - [`tests/service/tools.test.ts`](../tests/service/tools.test.ts) and [`tests/service/authority.test.ts`](../tests/service/authority.test.ts) — live tool dispatch through the agent loop, and the authority gate's approval and denial paths.
869
901
  - [`tests/service/budget.test.ts`](../tests/service/budget.test.ts) and [`tests/service/lifecycle.test.ts`](../tests/service/lifecycle.test.ts) — live token-budget enforcement on the reported usage, the meter layer's mid-stream trip under `allowance: budget`, the daemon's `done_reason: 'length'` at a `num_predict` cap with its `result.truncated` and model-layer `stop`, and the agent's status, event, and abort lifecycle.
870
902
  - [`tests/service/schema.test.ts`](../tests/service/schema.test.ts) and [`tests/service/scopes.test.ts`](../tests/service/scopes.test.ts) — a live structured-output `schema` constraining the answer, and a live scope filtering what reaches the wire.
871
- - [`tests/service/compaction.test.ts`](../tests/service/compaction.test.ts) and [`tests/service/conversation.test.ts`](../tests/service/conversation.test.ts) — live recap retention with manual, automatic, and repeated compaction, and a throwing summarizer that rejects the run under the strict default and stays non-fatal under `strict: false`, and long-conversation instruction behavior, with proxy calls explicitly forwarding to `OLLAMA_CONFIG.host`.
903
+ - [`tests/service/conversation.test.ts`](../tests/service/conversation.test.ts) — long-conversation instruction behavior, with proxy calls explicitly forwarding to `OLLAMA_CONFIG.host`.
872
904
 
873
905
  ## See also
874
906
 
@@ -1276,8 +1276,7 @@ server, and the supervising Codex process remained present; no synthetic load wa
1276
1276
  - [`lsp.md`](lsp.md) — the dependency mirror for `@orkestrel/lsp`, whose client and stdio client
1277
1277
  transport carry the lint stage's conversation with the Oxlint language server.
1278
1278
  - [`pool.md`](pool.md) — the dependency mirror for `@orkestrel/pool`, which owns stage leases
1279
- and replacement. The catalog refresh carries the published 0.0.15 guide; the release visit must
1280
- refresh it to 0.0.16 alongside the dependency range.
1279
+ and replacement.
1281
1280
  - [`tool.md`](tool.md) — the dependency mirror for `@orkestrel/tool`, whose registry holds it.
1282
1281
  - [`contract.md`](contract.md) — the dependency mirror for `@orkestrel/contract`, whose shapes
1283
1282
  compile both the published tool schema and the guards.
@@ -1266,7 +1266,7 @@ standard error, so a piped value is never polluted.
1266
1266
  | Verb | Value |
1267
1267
  | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1268
1268
  | `new` | `MaterializeResult` — `target`, `written`, `skipped`, `removed` — plus `provenance` |
1269
- | `audit` | `Audit` — `findings` and `questions` — plus `releases` and `provenance`; findings carry `ownership` |
1269
+ | `audit` | `Audit` — `findings` and `questions` — plus `releases` and `provenance`, which carries `guides` when mirrors were compared; findings carry `ownership` |
1270
1270
  | `surface` | `owners` with each owner's `source`, `collisions` with each entry's `standing` (`error`, `recorded`, or `closed`), and `provenance` with `guides` and `record` |
1271
1271
  | `repair` | `MaterializeResult` plus `audit`, the terminal audit taken after the write, `releases`, and `provenance` |
1272
1272
  | `catalog` | `MaterializeResult` plus `mirrors`, `provenance`, optional `membership` with `entries`, `dropped`, and `releases`, and an explanatory `note` on a partial run |
@@ -2260,12 +2260,17 @@ target holds. The refusal is deliberate at `0.0.x` and there is no migration pat
2260
2260
 
2261
2261
  ## Fleet catalog
2262
2262
 
2263
- During `audit`, a present foreign guide whose bytes differ from the hosted guide produces a
2264
- non-blocking question whose `field` is `guides`. Its message names the mirror path and `catalog`
2265
- as the refresh action. The message says
2266
- "differs from the hosted guide": byte inequality establishes no chronology. The question sits
2267
- outside repair findings, so `repair` preserves a present mirror. The target's own guide and its
2268
- guide index are excluded, and the comparison follows the `guides` group selection.
2263
+ During an online `audit` that selects the `guides` group, each present `guides/*.md` mirror is
2264
+ compared with the guide on its package's `main` branch, the read `catalog` performs. A mirror
2265
+ differing from that guide produces a non-blocking question whose `field` is `guides`. Its message
2266
+ names the mirror path and `catalog` as the refresh action, or `catalog --all` when the target does
2267
+ not declare the package. The message says "differs from the guide on" the package's `main` branch:
2268
+ byte inequality establishes no chronology. A mirror that cannot be read from its repository
2269
+ produces a non-blocking `guides` question that names the cause and states that the mirror was not
2270
+ compared. The comparison covers a mirror only when the hosted catalog lists its package. The
2271
+ target's own guide, the guide index, and nested paths are excluded. Offline, `audit` reads no
2272
+ repository and raises no `guides` question. The question sits outside repair findings, so `repair`
2273
+ preserves a present mirror, and the `Materializer` audit raises no guide question.
2269
2274
 
2270
2275
  `catalog` rewrites one marker-bounded region in `CATALOG_AGENT_PATH` and nothing else in that file.
2271
2276
  The region holds a table with these columns:
@@ -2350,7 +2355,10 @@ the baseline toolchain a generated workspace receives is the toolchain scaffold
2350
2355
  browser framework can override a floor through `TOOLCHAIN_HOLDS`. The rows scaffold does
2351
2356
  not install are seeds — `@orkestrel/capture`, `@vitejs/plugin-vue`, `vue`, `vue-tsc`, `vite-plugin-singlefile`, and the
2352
2357
  application-server fleet packages — and each carries the highest triple its supported major served
2353
- when it was written.
2358
+ when it was written. The three application-server fleet seeds (`@orkestrel/middleware`,
2359
+ `@orkestrel/router`, and `@orkestrel/server`) carry the version the committed catalog in
2360
+ `.claude/agents/orkestrel.md` lists, and the constants proof holds them there and checks that the
2361
+ catalog's runtime and peer edges among the three admit the seeded versions.
2354
2362
  [`tests/src/core/constants.test.ts`](../tests/src/core/constants.test.ts) names that seeded set, so a
2355
2363
  row entering or leaving the manifest moves a test rather than passing unnoticed. `sass`, the one row
2356
2364
  of `STYLES_DEV_DEPENDENCIES`, is a seed as well: it carries the `^1.105.1` range the
@@ -2417,7 +2425,8 @@ alike.
2417
2425
 
2418
2426
  ### What each verb reads
2419
2427
 
2420
- `new`, `audit`, and `repair` read declared versions and the vendored host. `catalog` reads
2428
+ `new`, `audit`, and `repair` read declared versions and the vendored host. `audit` also reads the
2429
+ upstream guide of each present guide mirror when the `guides` group is selected. `catalog` reads
2421
2430
  organization membership, its packuments, and the selected guides. `overwrite` reads every surface
2422
2431
  that `repair` and `catalog` read. A network-forced floor is drift except for a successful `new` run;
2423
2432
  an explicit `--offline` floor is intentional, and the verb's result decides its exit. `catalog` has
@@ -2427,13 +2436,13 @@ Each verb resolves a surface's complete answer before it opens that surface's wr
2427
2436
  a partial answer never becomes a partial pin set. `overwrite` keeps the repair and removal work it
2428
2437
  committed before a later catalog refusal and records that refusal in `note`.
2429
2438
 
2430
- | Verb | Reads live | When the network forces a floor | With `--offline` |
2431
- | ----------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
2432
- | `new` | Declared versions and the vendored host | Writes the distributed version and host floors; exits `0` after creating the workspace | Reads no upstream surface, writes the same floors, and exits `0` after creating the workspace |
2433
- | `audit` | Declared versions and the vendored host | Compares through the distributed floors and exits `1` | Compares through the floors; exits `0` for an aligned target or `1` for drift |
2434
- | `repair` | Declared versions and the vendored host | Repairs from the distributed floors and exits `1`, even when the terminal audit is aligned | Repairs from the floors; the terminal audit decides exit `0` or `1` |
2435
- | `catalog` | Organization membership, its packuments, and the selected guides | Refreshes guides alone on a membership outage; refuses version failure; preserves present mirrors or fills absent mirrors from the verified host; exits `1` | Is a usage error; exits `2` and writes nothing |
2436
- | `overwrite` | Everything `repair` and `catalog` read | Keeps completed repair and deletion work, names each floor or refused catalog step in `note`, and exits `1` | Repairs, deletes, and writes version floors; skips `catalog`, records that refusal in `note`, and exits `1` |
2439
+ | Verb | Reads live | When the network forces a floor | With `--offline` |
2440
+ | ----------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
2441
+ | `new` | Declared versions and the vendored host | Writes the distributed version and host floors; exits `0` after creating the workspace | Reads no upstream surface, writes the same floors, and exits `0` after creating the workspace |
2442
+ | `audit` | Declared versions, the vendored host, and the present guide mirrors | Compares through the distributed floors, or reports `provenance.guides` as `floor` after an unread guide, and exits `1` | Compares through the floors and reads no guide; exits `0` for an aligned target or `1` for drift |
2443
+ | `repair` | Declared versions and the vendored host | Repairs from the distributed floors and exits `1`, even when the terminal audit is aligned | Repairs from the floors; the terminal audit decides exit `0` or `1` |
2444
+ | `catalog` | Organization membership, its packuments, and the selected guides | Refreshes guides alone on a membership outage; refuses version failure; preserves present mirrors or fills absent mirrors from the verified host; exits `1` | Is a usage error; exits `2` and writes nothing |
2445
+ | `overwrite` | Everything `repair` and `catalog` read | Keeps completed repair and deletion work, names each floor or refused catalog step in `note`, and exits `1` | Repairs, deletes, and writes version floors; skips `catalog`, records that refusal in `note`, and exits `1` |
2437
2446
 
2438
2447
  A fleet row is compared exactly — `^0.1.0` is stale the moment the registry serves `0.1.2` — and
2439
2448
  that inequality alone raises `audit` to exit `1`. A foreign row is compared inside its declared
@@ -338,7 +338,7 @@ These invariants hold across `src/server` ↔ `server.md`.
338
338
  4. **Startup is bounded and caller-cancellable.** `start(signal?)` observes
339
339
  caller cancellation only while binding; `timeouts.start` independently
340
340
  bounds the bind (`0` permits no startup window) and is an integer from 0
341
- through 2_147_483_647, or construction throws a `TypeError`. Cancellation
341
+ through 2_147_483_647, or construction throws a `ContractError` of code `range`. Cancellation
342
342
  or deadline expiry closes the partial listener, clears the startup
343
343
  deadline, resets the entity to `idle`, and rejects; expiry rejects with a
344
344
  `DOMException` named `TimeoutError`, while caller cancellation rejects
@@ -614,11 +614,11 @@ These invariants hold across `src/server` ↔ `server.md`.
614
614
  `m` is the smaller positive of `headers` and `request` as Node applies
615
615
  them, so each expires at most one such interval after it passes; with
616
616
  neither positive, Node keeps its own interval. Construction refuses,
617
- with a `TypeError` that names the key and its limit, a `headers` or
617
+ with a `ContractError` of code `range` that names the key and its limit, a `headers` or
618
618
  `request` that is not an integer from 0 through 2_147_483_647 and a
619
619
  `keepalive` that is not an integer from 0 through 2_147_482_647, because
620
620
  Node arms `keepalive` plus its buffer as one timer; and it refuses, with a
621
- `TypeError` that names both keys, a `headers` above `request` while
621
+ `ContractError` of code `range` that names both keys, a `headers` above `request` while
622
622
  `request` is positive: Node's own `headersTimeout ≤ requestTimeout`
623
623
  relation. No server timeout bounds the response; a response deadline is
624
624
  a middleware's, such as the `createDeadline` middleware of
@@ -733,7 +733,7 @@ const server = createServer<State>({
733
733
  })
734
734
  ```
735
735
 
736
- The dispatcher of the `@orkestrel/router` release that 0.0.29 depends on
736
+ The dispatcher of the `@orkestrel/router` release that 0.0.30 depends on
737
737
  answers a path that matches with no route for the method with `405` and an
738
738
  `Allow` header that lists `OPTIONS`. It answers a `HEAD` with no `HEAD` route
739
739
  by running the `GET` handler, cancelling that response's body, and sending its
@@ -797,7 +797,7 @@ deadline expires and cuts it. A request that such a connection sends after
797
797
  the listener closes is refused, and its connection is destroyed. A second
798
798
  `stop()` call made during the stop returns the first call's promise. The
799
799
  `drain` option is an integer from 0 through 2_147_483_647 milliseconds, and
800
- construction throws a `TypeError` for any other value.
800
+ construction throws a `ContractError` of code `range` for any other value.
801
801
 
802
802
  ```ts
803
803
  import { createServer } from '@orkestrel/server'