@orkestrel/scaffold 0.0.67 → 0.0.68

package/dist/host/guides/timeout.md

@@ -0,0 +1,252 @@
+# Timeout
+
+> The time-bound half of the substrate's time-and-cancellation pair: a
+> controllable `setTimeout` wrapper carrying a trace `id` and a deadline `ms`,
+> whose native `AbortSignal` aborts on expiry.
+
+Arm the deadline with `start()`, then race its `signal` against work to bound
+how long that work may run; `clear()` cancels the deadline without firing it,
+and a `start()` after an expiry swaps in a fresh signal, so one handle serves a
+sequence of deadlines without re-construction. The package is deliberately
+thin: not a scheduler, not a debounce, not a retry policy — one `setTimeout`
+made re-armable, clearable, and parent-linkable. The native signal is the
+complete observation surface, so there is no separate event map. Source:
+[`src/core`](../src/core). Surfaced through the `@src/core` barrel.
+
+## Surface
+
+Create a deadline handle, arm it, and hand its `signal` to deadline-aware
+work — call `clear()` on the deadline if the work finishes first:
+
+```ts
+import { createTimeout } from '@orkestrel/timeout'
+
+const timeout = createTimeout({ ms: 5_000 })
+timeout.start()
+
+// `signal` aborts on expiry — pass it anywhere a native AbortSignal is accepted:
+const response = await fetch(url, { signal: timeout.signal })
+
+timeout.clear() // work finished first — cancel the deadline
+```
+
+Construction is a strict JavaScript boundary. Options must be a plain readable
+record; a defined `id` must be a string; `ms` must be an integer in the
+inclusive range from `0` through `MAX_TIMEOUT_MS`; and a defined parent
+`signal` must be a genuine native `AbortSignal`. Invalid input throws
+`ContractError` from `@orkestrel/contract`: malformed or unreadable options use
+code `bound`, while invalid `id`, `ms`, and `signal` values use `literal`,
+`range`, and `placement`, respectively. Each error carries safe `path`, `limit`,
+and `received` context. The package does not re-export `ContractError`.
+
+An optional parent signal clears the timeout rather than expiring it if it
+aborts before the deadline. An optional `id` labels the handle for tracing and
+defaults to a random UUID.
+
+### Factories
+
+| API             | Kind     | Summary                                                                                           |
+| --------------- | -------- | ------------------------------------------------------------------------------------------------- |
+| `createTimeout` | function | Creates a deadline handle from validated `TimeoutOptions` and returns it as a `TimeoutInterface`. |
+
+### Classes
+
+| API       | Kind  | Summary                                                                                                                                                       |
+| --------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Timeout` | class | Implements `TimeoutInterface` exactly, as a controllable `setTimeout` wrapper over one owned `AbortController` whose signal aborts when the deadline expires. |
+
+### Constants
+
+A `Shape` cell holds the constant's declared type.
+
+| API              | Kind  | Shape    | Summary                                                                               |
+| ---------------- | ----- | -------- | ------------------------------------------------------------------------------------- |
+| `MAX_TIMEOUT_MS` | const | `number` | Names the largest timeout duration the package accepts, `2_147_483_647` milliseconds. |
+
+### Validators
+
+In a guard table a `Shape` cell holds the type the guard narrows to.
+
+| API                 | Kind     | Shape         | Summary                                                                                                                                |
+| ------------------- | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `isTimeoutDuration` | function | `number`      | Determines whether a value is an integer in the inclusive range from `0` through `MAX_TIMEOUT_MS`, staying total for every input.      |
+| `isTimeoutSignal`   | function | `AbortSignal` | Determines whether a value is a genuine native `AbortSignal`, staying total for a structural spoof and for a hostile or revoked proxy. |
+
+### Helpers
+
+| API                      | Kind     | Summary                                                                                                             |
+| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `validateTimeoutOptions` | function | Validates once-read timeout construction options and returns a fresh normalized copy omitting absent optional keys. |
+
+### Types
+
+A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
+
+| Type               | Kind      | Shape                                           | Summary                                                                                   |
+| ------------------ | --------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `TimeoutOptions`   | interface | `{ id?, ms, signal? }`                          | Represents the options `createTimeout` and the `Timeout` constructor accept.              |
+| `TimeoutInterface` | interface | `{ id, ms, signal, expired } plus start, clear` | Represents a controllable deadline exposing a native `AbortSignal` that aborts on expiry. |
+
+The `id`, `ms`, `signal`, and `expired` members of `TimeoutInterface` are
+`readonly` data members (Shape cell, earlier) — its call-signature methods are
+documented under [Methods](#methods). `expired` derives directly from the
+owned signal's `aborted` state rather than storing a duplicate lifecycle flag.
+
+## Methods
+
+The public methods of `TimeoutInterface` — every call-signature member listed
+(its `readonly` members `id` / `ms` / `signal` / `expired` have no method row).
+`Timeout` implements the interface exactly, so this doubles as the class's
+instance-method surface (AGENTS.md, Documentation contract).
+
+#### `TimeoutInterface`
+
+The call-signature members, each with the type it returns:
+
+| Method  | Returns | Summary                                                                                                                                           |
+| ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start` | `void`  | Arms or re-arms the deadline for `ms`, installing a fresh `signal` when the current one has already aborted.                                      |
+| `clear` | `void`  | Cancels an armed deadline without aborting its `signal`, and resets expiry by installing a fresh signal when the current one has already aborted. |
+
+## Contract
+
+These invariants hold across `src/core` ↔ `timeout.md`:
+
+1. **DOC ↔ SOURCE bijection.** Every `function` / `class` / `const` /
+   `interface` row in the `## Surface` tables is a real export of the timeout
+   source, and every export appears as a Surface row — exhaustive, both
+   directions (AGENTS.md, Documentation contract).
+2. **Strict construction boundary.** `validateTimeoutOptions` requires a plain
+   readable record, reads `id`, `ms`, and `signal` exactly once inside a
+   contained boundary, validates them, and returns a fresh normalized copy that
+   omits absent optional keys. Defined identifiers must be strings, durations
+   must be integers in inclusive `[0, MAX_TIMEOUT_MS]`, and defined parent
+   signals must pass the native brand check. `Timeout` calls this helper before
+   allocating its controller or listener. Negative zero and zero are valid;
+   zero intentionally expires on the next turn. Invalid inputs throw the coded
+   `ContractError` taxonomy described under Surface.
+3. **Deadline signal and derived expiry.** The exposed `signal` fires (aborts)
+   on expiry. `expired` derives from that owned signal's `aborted` state, so
+   `expired` and `aborted` cannot drift apart.
+4. **Signal identity swaps only on a real expiry.** A cleared-but-never-fired
+   timeout keeps its original `signal` (not aborted); the identity is only
+   swapped for a fresh, non-aborted controller after the current controller has
+   fired — whether that swap happens inside `clear()` or at the next `start()`.
+5. **Parent linking clears, never expires.** A parent `options.signal` abort
+   clears the timeout — it does not expire the timeout, abort the timeout's own
+   signal, or forward the parent reason. The parent listener is attached only
+   while a timer is armed (added on `start()`, removed on expiry or `clear()`);
+   once the parent has aborted, a later `start()` is a no-op.
+6. **Identifiers are strict.** Omitted `id` values generate a random UUID and an
+   empty string is retained, but every other defined non-string value throws a
+   `literal`-coded `ContractError` rather than being coerced or replaced.
+7. **Native observation.** Consumers observe expiry through the complete native
+   `AbortSignal`; `Timeout` adds no `Emitter` or parallel event system.
+
+## Patterns
+
+### Race work against a deadline
+
+Builds a deadline handle, arms it, and clears it in a `finally` once the race resolves:
+
+```ts
+import { createTimeout } from '@orkestrel/timeout'
+
+async function fetchWithDeadline(url: string, ms: number): Promise<Response> {
+	const timeout = createTimeout({ ms })
+	timeout.start()
+
+	try {
+		return await fetch(url, { signal: timeout.signal })
+	} finally {
+		timeout.clear() // cancels the still-armed deadline when the fetch won the race
+	}
+}
+```
+
+### Link a parent signal
+
+A parent `AbortSignal` clears the deadline instead of letting it expire — so
+an outer cancellation (a request abort, a shutdown signal) short-circuits the
+timer cleanly without aborting the timeout's own signal:
+
+```ts
+import { createTimeout } from '@orkestrel/timeout'
+
+function withDeadline(parent: AbortSignal, ms: number) {
+	const timeout = createTimeout({ id: 'request-deadline', ms, signal: parent })
+	timeout.start()
+
+	timeout.signal.addEventListener(
+		'abort',
+		() => {
+			if (timeout.expired) giveUp() // only a real timeout expiry reaches this listener
+		},
+		{ once: true },
+	)
+
+	return timeout
+}
+```
+
+### Reuse a handle across deadlines
+
+Clears an armed deadline before it fires, then arms the same handle again for a fresh window:
+
+```ts
+import { createTimeout } from '@orkestrel/timeout'
+
+const timeout = createTimeout({ ms: 100 })
+
+timeout.start()
+timeout.clear() // cancels before firing — expired stays false
+
+timeout.start() // re-armed; a fresh deadline window begins
+```
+
+### Practices
+
+- **Race, don't poll** — attach a listener to `signal` (or pass it straight to
+  an API that accepts an `AbortSignal`, for example `fetch`) rather than
+  polling `expired`.
+- **`clear()` is always safe to call** — clearing an idle or already-cleared
+  handle is a no-op; after expiry it installs a fresh non-aborted signal. Call
+  it unconditionally in a `finally`.
+- **Keep parent cancellation distinct** — a parent abort clears the timer but
+  does not abort the timeout signal or forward the parent reason.
+- **Reuse, don't reconstruct** — call `start()` again on the same handle for a
+  new deadline window instead of constructing a fresh `Timeout`.
+
+## Tests
+
+- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔
+  `src/core` bijection over value and type exports, the `TimeoutInterface` ↔
+  `Timeout` method bijection, and the equality gate: every `Summary` cell
+  against its declaration's description paragraph, the titled fence against the
+  `@example` block of that title (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 their comments claim.
+- [`tests/src/core/Timeout.test.ts`](../tests/src/core/Timeout.test.ts) —
+  public-constructor integration, real expiry / clear / replacement / churn
+  behavior, signal identity and derived expiry, and the intentional parent-clear
+  lifecycle.
+- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — fresh
+  normalized copies, omitted optional keys, exactly-once property reads, hostile
+  getter containment, duration boundaries, and exact structured errors.
+- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) —
+  total duration and native-signal validation, including spoofed values and a
+  revoked proxy.
+- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) —
+  `createTimeout` returns a working `TimeoutInterface` and preserves the strict
+  construction boundary.
+
+## See also
+
+- [`AGENTS.md`](../AGENTS.md) — the rules, including the documentation contract
+  and the fixed lifecycle meanings of `start` and `clear`.
+- [`contract.md`](contract.md) — the mirrored guide for `@orkestrel/contract`,
+  the source of the validation primitives and `ContractError` used at the
+  construction boundary.
+- [`guide.md`](guide.md) — the mirrored guide for `@orkestrel/guide`, the
+  devDependency powering this repo's guides-parity test suite.
+- [`README.md`](README.md) — the guides index.

package/dist/host/guides/tool.md

@@ -0,0 +1,311 @@
+# Tool
+
+> The tool runtime for the `@orkestrel` line: a `Tool` binding an advertised JSON Schema
+> definition to its handler, a `ToolManager` registry that advertises those definitions and
+> executes calls with per-call error isolation, and the correlated `ToolCall` and `ToolResult`
+> pair that travels between a caller and the registry.
+
+A tool is a callable function described by a JSON Schema — a `name`, an optional description, an
+optional parameter schema, and the handler that runs it. That is the whole idea: a tool is an API
+call whose shape is data, so whoever calls it can discover it, present it, and invoke it without
+knowing anything about the code behind it.
+
+`Tool` and `ToolManager` carry the runtime. A `Tool` is inert — a definition plus a handler, with
+no lifecycle and no failure handling of its own. A `ToolManager` is the live surface a caller
+holds: it hands `definitions()` outward, takes a `ToolCall` back, and answers with a `ToolResult`,
+a result rather than a throw for a call whose members are plain values. Tools stay in the map by
+name in insertion order. Everything else in this module is the plain data those two exchange.
+
+**Anyone can call a tool.** Nothing here is model-specific — `tools.execute(call)` is an ordinary
+async call returning an ordinary result, and plain application code may drive it directly. The
+shape exists because callers that work from descriptions need the description and the handler to
+travel together: an agent loop choosing which function to invoke, an MCP bridge exposing local
+capability to a remote client, a backend dispatching a named operation. `@orkestrel/agent` and
+`@orkestrel/mcp` are two such callers; ready-made tools ship in `@orkestrel/toolbox`.
+
+**Mechanism only.** This runtime advertises, dispatches, and contains failure. It transports
+nothing, validates no arguments against a tool's schema, authorizes no call, and ships no concrete
+tools. Optional caller context is consumer-asserted and forwarded without verification. Each trust
+decision belongs to the invoking consumer, to a policy layer, or to the tool itself. Progress
+reporting belongs there too: it is a property of the invoking consumer's execution context, one
+layer up — the `@orkestrel/mcp` package's execution context carries a progress reporter — never of
+the tool contract itself.
+
+Source: [`src/core`](../src/core). Published through `@orkestrel/tool`.
+
+## Surface
+
+### Contracts
+
+The data shapes, from [`types.ts`](../src/core/types.ts). Every property is readonly, and an
+optional field the caller did not supply is absent from the value. A `Shape` cell holds an
+interface's data members as bare names in braces, `?` marking an optional member and `plus`
+introducing its call-signature members, and a type alias's own type literal with a union's arms
+escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
+
+| Name                   | Kind      | Shape                                                                  | Summary                                                                          |
+| ---------------------- | --------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `ToolDefinition`       | interface | `{ name, description?, parameters? }`                                  | Describes a tool as advertised to a caller.                                      |
+| `ToolCall`             | interface | `{ id, name, arguments, caller? }`                                     | Describes one request to run a named tool.                                       |
+| `ToolSuccess`          | interface | `Success<unknown> plus { id, name }`                                   | Reports the successful outcome of executing a `ToolCall`.                        |
+| `ToolFailure`          | interface | `Failure<string> plus { id, name }`                                    | Reports the failed outcome of executing a `ToolCall`.                            |
+| `ToolOptions`          | interface | `{ name, description?, summary?, parameters?, execute }`               | Configures an executable tool.                                                   |
+| `ToolInterface`        | interface | `ToolDefinition plus { summary? } plus execute`                        | Represents an executable tool: its advertised definition plus its local handler. |
+| `ToolManagerInterface` | interface | `{ count } plus add, tool, tools, definitions, execute, remove, clear` | Represents a registry of executable tools with per-call error isolation.         |
+| `ToolResult`           | type      | `ToolSuccess \| ToolFailure`                                           | Represents the outcome of executing a `ToolCall`.                                |
+
+`ToolInterface` and `ToolManagerInterface` list every member they declare or inherit. The
+call-signature members of each are documented under [Methods](#methods); the readonly `count` of
+`ToolManagerInterface` reports how many tools are registered and is a Surface member with no
+method row.
+
+### Validators
+
+The call-envelope guard, from [`validators.ts`](../src/core/validators.ts). In a guard table a
+`Shape` cell holds the type the guard narrows to.
+
+| Name         | Kind     | Shape      | Summary                                                                                                              |
+| ------------ | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
+| `isToolCall` | function | `ToolCall` | Determines whether an unknown value is structurally a `ToolCall`, staying total for malformed and adversarial input. |
+
+### Helpers
+
+The advertised-definition projection, from [`helpers.ts`](../src/core/helpers.ts).
+
+| Name               | Kind     | Signature                                 | Summary                                                                                                                                                                              |
+| ------------------ | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `toolToDefinition` | function | `(tool: ToolInterface) => ToolDefinition` | Projects a tool onto the plain definition advertised to a caller, advertising an authored `summary` in place of the full description and carrying the parameter schema by reference. |
+
+### Factories
+
+From [`factories.ts`](../src/core/factories.ts) — the constructor-free way to reach `Tool` and
+`ToolManager`.
+
+| Name                | Kind     | Signature                                 | Summary                                                                                                                                                                                                                    |
+| ------------------- | -------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createTool`        | function | `(options: ToolOptions) => ToolInterface` | Creates an executable tool bound to the supplied handler, returned as a `ToolInterface` so a call site holds the published contract rather than the `Tool` class.                                                          |
+| `createToolManager` | function | `() => ToolManagerInterface`              | Creates an empty registry that advertises definitions and executes calls with per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the published contract rather than the `ToolManager` class. |
+
+### Classes
+
+The implementing classes, from [`Tool.ts`](../src/core/tools/Tool.ts) and
+[`ToolManager.ts`](../src/core/tools/ToolManager.ts) — each documented in full under its own
+heading following this table.
+
+| Name          | Kind  | Summary                                                                      |
+| ------------- | ----- | ---------------------------------------------------------------------------- |
+| `Tool`        | class | Binds an executable tool definition to a handler.                            |
+| `ToolManager` | class | Represents an insertion-ordered tool registry with per-call error isolation. |
+
+### `Tool`
+
+The implementing class of `ToolInterface`, from [`Tool.ts`](../src/core/tools/Tool.ts). It
+copies the fields it was given — omitting each optional one that was not supplied — and keeps
+the handler in a private field, so a tool's advertised shape cannot drift from what it executes.
+The parameter schema, argument record, and present caller context are forwarded by reference,
+never cloned. `Tool` deliberately does not catch: a handler that throws throws, and per-call
+isolation belongs to the registry that dispatched it. See [`## Methods`](#methods) for its public
+call surface.
+
+### `ToolManager`
+
+The implementing class of `ToolManagerInterface`, from
+[`ToolManager.ts`](../src/core/tools/ToolManager.ts). One name-keyed map is its whole state:
+tools stay in insertion order, `tools()` and `definitions()` return fresh readonly arrays rather
+than a view of that map, and every projection is computed on demand so a mutation can never
+leave a stale copy behind. It is the only place a call can fail into a result instead of an
+exception. See [`## Methods`](#methods) for its public call surface.
+
+## Methods
+
+The public call-signature members of each behavioral interface, one table per interface.
+
+#### `ToolInterface`
+
+| Method    | Returns                       | Summary                                                                                              |
+| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `execute` | `Promise<unknown> \| unknown` | Runs the tool's handler with the caller-supplied arguments and any consumer-asserted caller context. |
+
+#### `ToolManagerInterface`
+
+| Method        | Returns                                        | Summary                                        |
+| ------------- | ---------------------------------------------- | ---------------------------------------------- |
+| `add`         | `void`                                         | Registers one tool.                            |
+| `tool`        | `ToolInterface \| undefined`                   | Finds one registered tool by name.             |
+| `tools`       | `readonly ToolInterface[]`                     | Lists the registered tools in insertion order. |
+| `definitions` | `readonly ToolDefinition[]`                    | Lists the definitions advertised to a caller.  |
+| `execute`     | `Promise<ToolResult \| readonly ToolResult[]>` | Executes one call with error isolation.        |
+| `remove`      | `boolean`                                      | Removes one registered tool.                   |
+| `clear`       | `void`                                         | Removes every registered tool.                 |
+
+`add`, `execute`, and `remove` each take one value or a readonly batch of them. A batch `add`
+registers every tool, later entries winning over earlier ones with the same name; a batch
+`execute` answers in input order with one result per call; a batch `remove` reports `true` only
+when every named tool was present.
+
+## Anatomy of a tool
+
+A definition is the part a caller can read; the handler is the part it cannot. Declare both at
+once:
+
+```ts
+import { createTool } from '@orkestrel/tool'
+
+const add = createTool({
+	name: 'add',
+	description: 'Add two numeric values and return their sum. Both operands are required.',
+	summary: 'Add two numbers.',
+	parameters: {
+		type: 'object',
+		properties: {
+			left: { type: 'number' },
+			right: { type: 'number' },
+		},
+		required: ['left', 'right'],
+	},
+	execute: (args) => Number(args.left) + Number(args.right),
+})
+```
+
+`new Tool({ … })` builds the same thing; reach for `createTool` where a call site must not name
+a class.
+
+The schema is descriptive runtime data, forwarded by reference and never interpreted here. A
+handler always receives the open `Readonly<Record<string, unknown>>` the caller sent and narrows
+the fields it consumes — declaring `required` tells the caller what to send, not this runtime
+what to reject. Its optional second parameter is the call's `caller` value verbatim. That value
+is asserted by the invoking consumer and is never verified here; a handler or policy layer must
+make every authorization and trust decision. Handlers may be synchronous or asynchronous; the
+registry awaits either. A handler can declare no parameter, one, or two. When the call carries
+no caller context the registry invokes the handler with the arguments record alone, so a handler
+that reads its own arity sees one argument and a handler that declares `caller` sees `undefined`.
+
+When one was authored, `definitions()` projects the tool's `summary` as `description`, advertising
+it in place of the full description. The full text stays on the tool for direct lookup through
+`tools.tool('add')?.description`.
+
+## The registry
+
+A registry is a working set, not a global. Build one per caller, fill it with the tools that
+caller is allowed to reach, and hand out its definitions:
+
+```ts
+import { Tool, createToolManager } from '@orkestrel/tool'
+
+const tools = createToolManager()
+tools.add(add) // the tool defined earlier
+tools.add([
+	new Tool({ name: 'echo', execute: (args) => args.value }),
+	new Tool({ name: 'now', description: 'Current epoch milliseconds.', execute: () => Date.now() }),
+])
+
+tools.count // 3
+tools.tool('add') // the exact instance that was registered, or undefined
+tools.tools() // a fresh readonly array, in insertion order
+tools.definitions() // the same order, projected to plain ToolDefinition values
+
+tools.remove('echo') // true — the tool was present
+tools.remove(['now', 'ghost']) // false — 'ghost' was never registered, so not every name succeeded
+tools.clear() // back to empty
+```
+
+Order is insertion order, and adding a name that already exists replaces the stored tool without
+moving it — the sequence a caller sees stays stable while a tool behind a name is swapped.
+Remove a name and add it again and it lands at the end, because the name is genuinely new to the
+map. In a batch, later entries win over earlier ones with the same name.
+
+`definitions()` projects fresh plain objects on every call: `name`, then `description` only when
+a summary or description exists, then `parameters` only when a schema exists, with the schema
+object's original identity preserved. Nothing that arrives on a definition is a live handle on
+the registry — advertising cannot be used to reach the handlers.
+
+## Calls and results
+
+A call arrives as unstructured input from somewhere else, so check the envelope before trusting
+it, then execute:
+
+```ts
+import { isToolCall } from '@orkestrel/tool'
+
+const incoming: unknown = {
+	id: 'call-1',
+	name: 'add',
+	arguments: { left: 2, right: 3 },
+	caller: { subject: 'user-42' },
+}
+
+if (isToolCall(incoming)) {
+	const result = await tools.execute(incoming)
+	if (result.success) {
+		result.value // 5
+	} else {
+		result.error // the failure message
+	}
+}
+
+const batch = await tools.execute([
+	{ id: '1', name: 'add', arguments: { left: 2, right: 3 } }, // → { id: '1', name: 'add', success: true, value: 5 }
+	{ id: '2', name: 'ghost', arguments: {} }, // → { id: '2', name: 'ghost', success: false, error: 'tool not found: ghost' }
+])
+```
+
+`isToolCall` validates the envelope only: the `id`, the `name`, and that `arguments` is a plain
+record. Optional `caller` remains opaque `unknown`; the guard does not verify it. It never checks
+arguments against a tool's schema, so a well-formed call for a badly shaped payload still reaches
+the handler, which is exactly where the domain knowledge to reject it lives.
+
+Caller context exists only on the call and in the tool execution chain. This package never adds
+it to advertised definitions, schemas, results, or logs. When present it is forwarded by
+identity; when absent it is not passed at all.
+
+Execution always resolves for a call whose members are plain values; a call whose `id` or `name`
+accessor throws when read makes `execute` reject, because no correlated result can be built
+without them. An unknown name becomes `tool not found: <name>`; a synchronous throw and an
+asynchronous rejection are both contained; an `Error` contributes its `message`, and any other
+thrown value is converted with `String`; a value whose conversion itself throws — a hostile
+`toString`, a throwing `message` getter, a null-prototype object — becomes the fixed message
+`Unknown thrown value`. Success and failure never mix in one result: a successful call carries
+`value` even when that value is `undefined`, `null`, `0`, `''`, or `false`, and a failed call
+carries `error`. Narrow on `success` to distinguish the two; a present success value is not
+necessarily meaningful or truthy.
+
+An in-process caller needing a typed error can call `tools.tool(name)`, then
+`tool.execute(args)` inside its own `try`/`catch`.
+
+A batch is dispatched concurrently and answered in input order, with each call whose members are
+plain values isolated from its siblings — a handler failure never voids the batch, a call whose
+`id` or `name` accessor throws when read rejects it, and duplicate ids stay distinct positional
+calls rather than collapsing into one. That isolation is what lets a caller feed every result back
+to whatever produced the calls and let it react to the failures itself.
+
+## Callers
+
+The registry's two-sided shape — `definitions()` out, `execute()` back — is all a caller needs,
+and it is the same shape whatever sits on the other side.
+
+An agent loop advertises `definitions()` to a model, receives tool calls in the model's reply,
+runs them through `execute`, and appends each `ToolResult` to the conversation; because a failure
+comes back as an error result, the model sees what went wrong and can try something else instead
+of the run collapsing. An MCP bridge maps the same definitions onto the protocol's tool listing
+and routes each invocation to `execute`. Plain code skips the discovery half entirely and calls
+`execute` with a call it wrote itself — a scheduled job, an HTTP handler dispatching a named
+operation, a test.
+
+Concrete tools are not this package's business. `@orkestrel/toolbox` ships ready-made ones, and
+anything a `ToolInterface` can describe — a local computation, a database query, a remote API —
+registers here unchanged.
+
+## Tests
+
+- [`guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection, the `ToolInterface` ↔ `Tool` and `ToolManagerInterface` ↔ `ToolManager` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Anatomy of a tool` fence against the `@example` block of that title (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 their comments claim.
+- [`Tool.test.ts`](../tests/src/core/tools/Tool.test.ts) — definition binding, optional-field omission, argument identity, return values, and the deliberate absence of handler isolation.
+- [`ToolManager.test.ts`](../tests/src/core/tools/ToolManager.test.ts) — insertion order, overwrite and removal lifecycle, definition projection, and isolated single and batch execution.
+- [`factories.test.ts`](../tests/src/core/factories.test.ts) — factory construction and working instances.
+- [`helpers.test.ts`](../tests/src/core/helpers.test.ts) — definition projection: summary preference, omitted optional keys, projected key order, schema identity, and a fresh object per call.
+- [`validators.test.ts`](../tests/src/core/validators.test.ts) — tool-call envelope boundaries: incomplete calls, wrong field types, and non-record arguments.
+
+## See also
+
+- [`README.md`](README.md) — the guides index.
+- [`contract.md`](contract.md) — the dependency mirror for `@orkestrel/contract`, whose total guards back `isToolCall` and the registry's overload narrowing.
+- [`AGENTS.md`](../AGENTS.md) — the repository's coding and documentation contract.