@juno-ai/bind 6.0.0 → 8.0.0

package/README.md

@@ -463,6 +463,164 @@ a tool an array where it expects fields turns a clear failure here into a
 confusing one inside the tool, after any side effect it performs before its own
 validation.
 
+### How to assemble streamed tool calls
+
+Providers send tool calls as indexed deltas, and the obvious accumulation loop
+is wrong in four ways that all fail silently.
+
+```ts
+import { createToolCallAccumulator } from "@juno-ai/bind/completion";
+
+const toolCalls = createToolCallAccumulator();
+for await (const chunk of stream) {
+  toolCalls.observe(chunk.choices?.[0]?.delta?.tool_calls);
+}
+const assembled = toolCalls.isEmpty ? undefined : toolCalls.assembled();
+```
+
+Key by the provider's `index`, not arrival order — deltas for index 1 can
+precede index 0, and pushing onto an array transposes the calls while leaving
+both parseable. Read `id` on every delta, not just the first for a slot; a
+late one is legal and a call without an id cannot be answered. Concatenate
+`name` as well as `arguments` — providers split it, and assigning keeps only
+the last fragment (`_file` from `read_file`), which surfaces as an unknown-tool
+error naming a tool the model never asked for. Order by index at the end, since
+`Map` iterates in insertion order.
+
+### How to keep a retry from repeating a tool's side effect
+
+A durable runtime retries: a queue redelivers, a workflow step re-runs, a
+reclaimed job starts the turn again. If the turn sent an email, the retry sends
+a second one. A *receipt* is the row that lets the second attempt find out.
+
+```ts
+import {
+  toolCallArgsHash, decideToolCallReceipt, type DigestFn,
+} from "@juno-ai/bind/run";
+
+const sha256: DigestFn = async (s) => {
+  const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
+  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+};
+
+const key = { tenantId, runId, toolName, argsHash: await toolCallArgsHash(args, sha256) };
+const decision = decideToolCallReceipt({
+  state: await store.read(key),            // yours — see the shape below
+  effect: tool.resumable ? "resumable" : "opaque",
+});
+
+switch (decision.kind) {
+  case "replay":    return (await store.read(key)).result;
+  case "wait":      return retryLater(decision.reason);
+  case "ambiguous": return surfaceToAHuman(decision.reason);
+  case "execute": {
+    await store.claim(key, decision.attempt);   // BEFORE executing
+    const result = await tool.execute(args);
+    await store.complete(key, decision.attempt, result);
+    return result;
+  }
+}
+```
+
+**Identity is content, not position.** The key is
+`(tenant, run, tool, arguments)`. Keying by position — run + turn + index in the
+batch — looks equivalent and is not: a retried turn is a *fresh completion*, so
+above temperature zero the model may reorder the batch or ask for a different
+tool at the same index. Position-keyed receipts then match calls that are not
+the same call, replay one tool's result as another's, and skip the tool actually
+requested. Content keying fails the other way, which is the safe way: a genuinely
+new call finds no receipt and runs.
+
+**The tenant is part of the key.** Without it the key cannot be partitioned or
+relocated by tenant, and two tenants' runs are not guaranteed to share a database.
+
+**Record before executing, not after.** A receipt claimed but never completed is
+the evidence that a write *may* have landed. Record afterwards and that window is
+invisible.
+
+**"Claimed but not completed" is not automatically ambiguous** — this is the part
+worth getting right. On any at-least-once substrate a lease expires whenever a
+worker dies *or merely stalls*, which is routine. `decideToolCallReceipt` needs a
+lease and an attempt counter to tell the three cases apart:
+
+| Receipt state | Decision |
+|---|---|
+| absent | `execute`, attempt 1 |
+| completed | `replay` |
+| failed | `execute`, attempt n+1 |
+| running, lease **live** | `wait` — another attempt owns it and is alive |
+| running, lease **expired**, effect `resumable` | `execute`, attempt n+1 — reclaim |
+| running, lease **expired**, effect `opaque` | `ambiguous` — refuse, surface it |
+
+`resumable` means the host records each sub-operation as it completes, so a
+reclaimed attempt skips what already happened. `opaque` is one indivisible
+effect with no trail, where reclaiming cannot tell "never sent" from "sent, then
+crashed".
+
+Two obligations the package cannot enforce: **lease times must come from the
+store's clock**, because application clocks drift enough to steal a live lease;
+and **every write must gate on the attempt fence** (`status = 'running' AND
+attempts = <mine>`), inside the same transaction as the side effect where the
+store allows it — fencing only the completion write leaves a window where two
+attempts both believe they own the call.
+
+**Hash the raw parsed arguments**, not the output of a schema parse that coerced
+types. `canonicalJson` throws rather than serializing a value it cannot
+represent faithfully — a `Map`, a `Set`, a class instance, `NaN`, a cycle —
+because a silent collision here reads as "same call" and skips a write that
+never happened.
+
+### How to stream tokens to a user without breaking fallback
+
+Content never passes through this package — `callModel` and `AttemptFn` are
+*your* functions, so forwarding deltas from inside them is already supported and
+needs nothing from here. What the package gives you is three granularities and
+one rule.
+
+| You want | Use |
+|---|---|
+| Each assistant message as it lands | `onAssistantMessage(content)` on the loop — fires per message, including text emitted alongside tool calls, rather than batching at turn end |
+| A live "N tokens so far" indicator | `onOutputProgress` into `callModel` → `onProgressUpdate(outputTokens, toolCalls)` — a count, never content |
+| Individual tokens in a UI | Forward them yourself, inside `callModel` / `AttemptFn` |
+
+**The rule, if you take the third option: set `producedOutput: true` on the
+failure outcome the moment you have forwarded anything.** Routing will otherwise
+retry the same endpoint or traverse to another provider, and re-render a turn
+your user is already reading.
+
+```ts
+attempt: async (candidate, cursor) => {
+  let forwarded = false;
+  try {
+    const value = await callProvider(candidate, {
+      onDelta: (text) => { forwarded = true; sendToClient(text); },
+    });
+    return { kind: "success", value };
+  } catch (error) {
+    return { kind: "failure", error: classify(error, candidate, cursor), producedOutput: forwarded };
+  }
+}
+```
+
+This costs less fallback than it looks. Retriable failures split cleanly:
+connection refused, a 429, a 5xx at the header, a time-to-first-token stall —
+none has forwarded anything, so `forwarded` is false and traversal is
+unaffected. What the flag removes is the mid-stream retry, which was never safe
+to replay in the first place.
+
+Two edges are yours to decide, because the answer is a product judgement rather
+than a routing one:
+
+- **Structured-output retries need the same care.** `structuredOutputParses`
+  retries a completion whose JSON will not parse — but if you forwarded that
+  JSON, the user has already seen it. Either withhold structured output from the
+  stream, or clamp the retry.
+- **Reasoning deltas are ambiguous.** The watchdog gates its tight budget on the
+  first *answer* token, so reasoning can flow well before one. A UI rendering
+  "thinking…" has emitted *something*, but discarding it on retry usually
+  confuses nobody. Decide whether reasoning counts as output for you; the
+  package deliberately does not decide it.
+
 ### How to map your transport errors onto the routing taxonomy
 
 `failureDisposition` decides what the router does with a classified failure, but
@@ -643,10 +801,10 @@ keeps a consumer who only wants routing from pulling in the rest.
 | Import | Owns | Reach for it when |
 |---|---|---|
 | `@juno-ai/bind/routing` | Route plans, the planner, the failure taxonomy and the classifier that maps your errors onto it, the plan executor, the circuit breaker, billing-basis arithmetic, config degradation | You call more than one provider or model, or you want retries and fallback governed by one table |
-| `@juno-ai/bind/completion` | Streaming idle watchdog (time-to-first-token, inter-chunk, absolute cap), completion-defect detection, the tool-call argument read (`parseToolCallArguments`), and the structured-output retry predicates | You read a streamed completion |
+| `@juno-ai/bind/completion` | Streaming idle watchdog (time-to-first-token, inter-chunk, absolute cap), streamed tool-call assembly, completion-defect detection, the tool-call argument read (`parseToolCallArguments`), and the structured-output retry predicates | You read a streamed completion |
 | `@juno-ai/bind/contracts` | Turn vocabulary — `TurnFn`, `ModelTurnResult`, `StopReason`, `RunStats` and its folds | You want one seam between your loop and any LLM client, and comparable per-run metrics |
 | `@juno-ai/bind/loop` | `runToolLoop` — the iteration engine: model turn, two-phase tool batch, activation, compaction, interrupts, suspend | You want the agent loop itself, not just the pieces to build one |
-| `@juno-ai/bind/run` | Wall-clock deadline, failure classification, coalesced heartbeat, tool-batch pooling, child-run lineage and admission, poll backoff | A run must be bounded, observable, and able to say *why* it stopped — or it can spawn runs of its own |
+| `@juno-ai/bind/run` | Wall-clock deadline, failure classification, coalesced heartbeat, tool-batch pooling, child-run lineage and admission, poll backoff, tool-call receipts for retry-safe side effects | A run must be bounded, observable, and able to say *why* it stopped — or it can spawn runs of its own |
 | `@juno-ai/bind/transcript` | `validateAndHealMessages` | You send transcripts to more than one provider, or you build them across turns |
 | `@juno-ai/bind/tools` | `sanitizeToolSchema` | Any tool schema reaches a provider — especially third-party ones |
 | `@juno-ai/bind/plugins` | Tool/plugin vocabulary, the registry factory, progressive-disclosure activation | You have more tools than fit comfortably in one prompt |
@@ -663,6 +821,17 @@ fact (`aborted` / `completion_defect` / `network` / `http` + category);
 propagate. Putting routing logic in a transport is the one way to break the
 guarantee that identical inputs produce identical plans.
 
+**Routing — an attempt that already produced output is never replayed.** Every
+other input to a disposition is a property of the *error*; this one is a
+property of the *attempt*, and only your transport knows it. A transport that
+buffers the whole completion can always replay; one that forwards deltas to a
+live view has already shown someone tokens, and retrying — on the same endpoint
+or another provider — appends a second partial answer to what they are reading.
+Set `producedOutput: true` on the failure outcome and the executor withholds all
+traversal. **If you stream to a UI and do not set it, you have this bug.** The
+breaker still records the failure: the endpoint really did fail, and hiding that
+because it failed late is backwards.
+
 **Routing — a healthy endpoint must not be punished for a bad request.**
 Request-shaped rejections (a 400, a moderation refusal) traverse to another
 provider but record **no** breaker failure. Otherwise one caller's malformed or
@@ -1287,7 +1456,16 @@ an oversight.
   when the loop folds `RunStats` directly; today a host that wants throughput
   metrics accumulates them alongside.
 - **A streaming turn contract.** `callModel` reports an output-token estimate
-  mid-stream; the assistant message itself still arrives whole.
+  mid-stream and `onAssistantMessage` fires per message, but the message itself
+  still arrives whole — no token-level content crosses this boundary. Hosts
+  stream inside their own `callModel` / `AttemptFn` today
+  ([how-to](#how-to-stream-tokens-to-a-user-without-breaking-fallback)), which
+  works and keeps the package content-blind. Moving emission *in* would mean
+  owning the emit/retry interaction rather than delegating it: forwarding the
+  first delta would have to arm the `producedOutput` clamp automatically, and
+  the structured-output retry budget would need the same treatment. Deferred
+  because the host's transport is a better place for a hot-path content
+  callback, not because the design is unclear.
 
 ---
 

package/completion/index.d.ts

@@ -1,3 +1,4 @@
 export { createStreamWatchdog, DEFAULT_TIME_TO_FIRST_TOKEN_MS, DEFAULT_INTER_CHUNK_MS, DEFAULT_MAX_CALL_DURATION_MS, type ChunkOutput, type StreamStall, type StreamWatchdog, type StreamWatchdogOptions, } from "./watchdog.js";
 export { detectCompletionDefect, expectsJsonOutput, jsonParses, structuredOutputParses, DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES, DEFAULT_COMPLETION_DEFECT_MAX_RETRIES, type AssembledCompletion, type CompletionDefect, type CompletionOutputs, type ResponseFormatShape, type StreamedToolCall, } from "./defects.js";
 export { parseToolCallArguments, toolCallArgumentsAbsent, type DispatchableToolCall, type ToolCallArguments, } from "./tool-calls.js";
+export { createToolCallAccumulator, type ToolCallDelta, type AssembledToolCall, type ToolCallAccumulator, } from "./stream-assembly.js";

package/completion/index.js

@@ -1,3 +1,4 @@
 export { createStreamWatchdog, DEFAULT_TIME_TO_FIRST_TOKEN_MS, DEFAULT_INTER_CHUNK_MS, DEFAULT_MAX_CALL_DURATION_MS, } from "./watchdog.js";
 export { detectCompletionDefect, expectsJsonOutput, jsonParses, structuredOutputParses, DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES, DEFAULT_COMPLETION_DEFECT_MAX_RETRIES, } from "./defects.js";
 export { parseToolCallArguments, toolCallArgumentsAbsent, } from "./tool-calls.js";
+export { createToolCallAccumulator, } from "./stream-assembly.js";

package/completion/stream-assembly.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Assembling streamed tool calls out of the deltas a provider sends.
+ *
+ * `detectCompletionDefect` and `parseToolCallArguments` both consume a
+ * *finished* tool call, which quietly assumes something turned chunks into one.
+ * That something is this module. Until now every host wrote it, and the loop
+ * looks trivial enough that it usually gets written from memory — which is the
+ * problem, because four of its details are wrong in the obvious version and all
+ * four fail silently:
+ *
+ *  1. **Key by `index`, not by arrival order.** Deltas for index 1 can arrive
+ *     before index 0. Pushing onto an array in arrival order transposes the
+ *     calls, and both still parse, so nothing errors — the model just gets the
+ *     wrong tool's arguments.
+ *  2. **`id` can arrive in any chunk**, not necessarily the first for its
+ *     index. Reading it only when the slot is created leaves the call with an
+ *     empty id, and the `tool` message that answers it then pairs with nothing.
+ *  3. **`name` is concatenated, not assigned.** Providers split it across
+ *     chunks. Assigning keeps only the last fragment (`_file` from
+ *     `read_file`), which surfaces as an unknown-tool error naming a tool the
+ *     model never asked for.
+ *  4. **Order the result by index at the end.** `Map` iterates in insertion
+ *     order, which is arrival order, which is (1) again at the finish line.
+ *
+ * A fifth is this module's own to avoid: **a missing `index` is not a malformed
+ * one.** A provider that omits the field is describing a single call; one that
+ * sends `-1` or `"0"` is unintelligible. Dropping both loses a call the model
+ * asked for, and loses it silently, because the batch still comes back
+ * non-empty and defect detection sees nothing wrong.
+ *
+ * **The accumulator is unbounded by design and the host must bound the stream.**
+ * There is no cap on distinct indices or on accumulated argument bytes — a
+ * provider streaming either without limit will grow this `Map` until the
+ * process dies. That is the host's to prevent, with an inter-chunk watchdog
+ * (`createStreamWatchdog`), a completion-token cap, or a byte budget; a
+ * primitive that guessed a limit would break a legitimate large batch.
+ *
+ * Everything here is pure and structural. The host owns the transport — SSE
+ * framing, byte decoding, `[DONE]` — and passes the per-chunk delta arrays in.
+ */
+/**
+ * One provider's tool-call delta. Structural rather than tied to an SDK: the
+ * fields are those the OpenAI streaming protocol defines, and every field but
+ * `index` is optional because a chunk may carry any subset of them.
+ */
+export interface ToolCallDelta {
+    /**
+     * The call's position in the batch. Optional because a provider describing a
+     * single call may omit it — those fold into one slot rather than being
+     * dropped. A *present* but non-integer or negative value is malformed and is
+     * counted in {@link ToolCallAccumulator.droppedDeltas}.
+     */
+    readonly index?: number | undefined;
+    readonly id?: string | undefined;
+    /**
+     * Carried for structural compatibility and deliberately **not** read:
+     * `assembled()` always emits `"function"`. Every streamed tool call in the
+     * OpenAI protocol is a function call, and a non-function type
+     * (`type: "custom"`) does not arrive as a delta stream — `defects.ts` and
+     * `parseToolCallArguments` handle that shape on the assembled message. If a
+     * provider ever streams one, this is the line to revisit.
+     */
+    readonly type?: string | undefined;
+    readonly function?: {
+        readonly name?: string | undefined;
+        readonly arguments?: string | undefined;
+    } | undefined;
+}
+/** A tool call assembled from its deltas, ready to dispatch or inspect. */
+export interface AssembledToolCall {
+    readonly id: string;
+    readonly type: "function";
+    readonly function: {
+        readonly name: string;
+        readonly arguments: string;
+    };
+}
+/**
+ * Accumulates tool-call deltas across the chunks of one completion.
+ *
+ * Stateful because a stream is: the host calls {@link observe} per chunk and
+ * {@link assembled} once at the end. One accumulator per completion — reusing
+ * one across two calls merges them.
+ */
+export interface ToolCallAccumulator {
+    /** Fold one chunk's deltas in. Safe to call with an empty array. */
+    observe(deltas: readonly ToolCallDelta[] | undefined): void;
+    /** Whether any delta has been seen — cheaper than assembling to find out. */
+    readonly isEmpty: boolean;
+    /**
+     * Deltas discarded because their `index` was present but unusable — not an
+     * integer, or negative. Non-zero means the model asked for a call that is
+     * **not** in {@link assembled}, and nothing downstream can tell: the batch
+     * comes back non-empty, so defect detection sees no defect and no retry
+     * fires. Log it at minimum; a host that would rather fail the turn than
+     * answer a partial batch has to decide that here.
+     *
+     * A delta with **no** `index` is not counted — that is a provider describing
+     * a single call, and it is assembled rather than dropped.
+     */
+    readonly droppedDeltas: number;
+    /**
+     * The calls so far, ordered by the provider's `index`. Returns a fresh array
+     * each call and does not end accumulation, so it is safe to inspect mid-stream.
+     */
+    assembled(): AssembledToolCall[];
+}
+export declare function createToolCallAccumulator(): ToolCallAccumulator;

package/completion/stream-assembly.js

@@ -0,0 +1,117 @@
+/**
+ * Assembling streamed tool calls out of the deltas a provider sends.
+ *
+ * `detectCompletionDefect` and `parseToolCallArguments` both consume a
+ * *finished* tool call, which quietly assumes something turned chunks into one.
+ * That something is this module. Until now every host wrote it, and the loop
+ * looks trivial enough that it usually gets written from memory — which is the
+ * problem, because four of its details are wrong in the obvious version and all
+ * four fail silently:
+ *
+ *  1. **Key by `index`, not by arrival order.** Deltas for index 1 can arrive
+ *     before index 0. Pushing onto an array in arrival order transposes the
+ *     calls, and both still parse, so nothing errors — the model just gets the
+ *     wrong tool's arguments.
+ *  2. **`id` can arrive in any chunk**, not necessarily the first for its
+ *     index. Reading it only when the slot is created leaves the call with an
+ *     empty id, and the `tool` message that answers it then pairs with nothing.
+ *  3. **`name` is concatenated, not assigned.** Providers split it across
+ *     chunks. Assigning keeps only the last fragment (`_file` from
+ *     `read_file`), which surfaces as an unknown-tool error naming a tool the
+ *     model never asked for.
+ *  4. **Order the result by index at the end.** `Map` iterates in insertion
+ *     order, which is arrival order, which is (1) again at the finish line.
+ *
+ * A fifth is this module's own to avoid: **a missing `index` is not a malformed
+ * one.** A provider that omits the field is describing a single call; one that
+ * sends `-1` or `"0"` is unintelligible. Dropping both loses a call the model
+ * asked for, and loses it silently, because the batch still comes back
+ * non-empty and defect detection sees nothing wrong.
+ *
+ * **The accumulator is unbounded by design and the host must bound the stream.**
+ * There is no cap on distinct indices or on accumulated argument bytes — a
+ * provider streaming either without limit will grow this `Map` until the
+ * process dies. That is the host's to prevent, with an inter-chunk watchdog
+ * (`createStreamWatchdog`), a completion-token cap, or a byte budget; a
+ * primitive that guessed a limit would break a legitimate large batch.
+ *
+ * Everything here is pure and structural. The host owns the transport — SSE
+ * framing, byte decoding, `[DONE]` — and passes the per-chunk delta arrays in.
+ */
+export function createToolCallAccumulator() {
+    const byIndex = new Map();
+    // Deltas carrying no `index` at all fold together here, in their OWN
+    // variable rather than a reserved key in `byIndex`. A sentinel index would
+    // share a keyspace with real ones — `Number.MAX_SAFE_INTEGER` is a legal
+    // index — and an explicit delta at that index would merge with the implicit
+    // call, concatenating two tools' names into one. That is footgun 3 of this
+    // module's own header, re-created by the fix for footgun 5.
+    //
+    // A missing index is distinct from a MALFORMED one and they must not be
+    // treated alike: a provider that omits the field is describing a single call
+    // and is intelligible, while one that sends `-1` or `"0"` is not.
+    let implicit = null;
+    let dropped = 0;
+    const upsert = (existing) => existing ?? { id: "", name: "", args: "" };
+    const fold = (call, delta) => {
+        // Read `id` on EVERY delta, not just the first: providers are free to send
+        // it late, and a call assembled without one cannot be answered.
+        if (typeof delta.id === "string" && delta.id !== "")
+            call.id = delta.id;
+        // Both are concatenated. `arguments` is obviously chunked; `name` is less
+        // obviously so, and assigning it keeps only the final fragment.
+        if (delta.function?.name)
+            call.name += delta.function.name;
+        if (delta.function?.arguments)
+            call.args += delta.function.arguments;
+    };
+    return {
+        observe(deltas) {
+            // `== null` rather than `=== undefined`: a transport that sets the field
+            // to `null` would otherwise reach `for...of` and throw.
+            if (deltas == null)
+                return;
+            for (const delta of deltas) {
+                const index = delta.index;
+                if (index === undefined || index === null) {
+                    implicit = upsert(implicit);
+                    fold(implicit, delta);
+                    continue;
+                }
+                // A malformed index cannot be placed. Dropping loses that call;
+                // guessing a slot corrupts a different one, which is worse — a lost
+                // call reads as missing, a misfiled one reads as valid. The drop is
+                // counted rather than silent, because the host is the only layer that
+                // can decide whether a lost call is worth failing the turn over.
+                if (!Number.isInteger(index) || index < 0) {
+                    dropped += 1;
+                    continue;
+                }
+                const call = upsert(byIndex.get(index));
+                byIndex.set(index, call);
+                fold(call, delta);
+            }
+        },
+        get isEmpty() {
+            return byIndex.size === 0 && implicit === null;
+        },
+        get droppedDeltas() {
+            return dropped;
+        },
+        assembled() {
+            const ordered = [...byIndex.entries()]
+                .sort(([left], [right]) => left - right)
+                .map(([, call]) => call);
+            // The implicit call sorts last: it has no index to place it by, and a
+            // provider that mixes indexed and index-less deltas has told us nothing
+            // about where it belongs.
+            if (implicit !== null)
+                ordered.push(implicit);
+            return ordered.map((call) => ({
+                id: call.id,
+                type: "function",
+                function: { name: call.name, arguments: call.args },
+            }));
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "6.0.0",
+  "version": "8.0.0",
   "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",

package/routing/errors.d.ts

@@ -66,6 +66,26 @@ export interface FailureDisposition {
     /** Return to the caller immediately; no further traversal. */
     readonly propagate: boolean;
 }
+/**
+ * The disposition for a failure whose attempt **already produced output the
+ * caller cannot take back** — tokens streamed to a UI, or a provider-side
+ * effect a replay would repeat.
+ *
+ * Every other input to `failureDisposition` is a property of the *error*. This
+ * one is a property of the *attempt*, and only the host knows it: a transport
+ * that buffers the whole completion before returning can always replay, and one
+ * that forwards deltas to a live view cannot. So it arrives as a fact on the
+ * failure outcome rather than as another arm of the taxonomy.
+ *
+ * Traversal is withheld entirely — not just the same-endpoint retry. Trying the
+ * next provider re-renders the same turn, which is the same duplication with a
+ * different label on it.
+ *
+ * The **breaker effect is preserved**: the endpoint really did fail, and that is
+ * true regardless of how far the response got. Suppressing it here would hide a
+ * dying endpoint from every later call precisely because it dies late.
+ */
+export declare function propagateOnly(disposition: FailureDisposition): FailureDisposition;
 /**
  * The exhaustive failure → routing-behavior matrix (PRD §7.1). Pure; the
  * executor applies it, the circuit breaker consumes its `breaker` effect.

package/routing/errors.js

@@ -39,6 +39,36 @@ const CREDENTIAL_FAILURE = Object.freeze({
     breaker: "open_immediately",
     propagate: false,
 });
+/**
+ * The disposition for a failure whose attempt **already produced output the
+ * caller cannot take back** — tokens streamed to a UI, or a provider-side
+ * effect a replay would repeat.
+ *
+ * Every other input to `failureDisposition` is a property of the *error*. This
+ * one is a property of the *attempt*, and only the host knows it: a transport
+ * that buffers the whole completion before returning can always replay, and one
+ * that forwards deltas to a live view cannot. So it arrives as a fact on the
+ * failure outcome rather than as another arm of the taxonomy.
+ *
+ * Traversal is withheld entirely — not just the same-endpoint retry. Trying the
+ * next provider re-renders the same turn, which is the same duplication with a
+ * different label on it.
+ *
+ * The **breaker effect is preserved**: the endpoint really did fail, and that is
+ * true regardless of how far the response got. Suppressing it here would hide a
+ * dying endpoint from every later call precisely because it dies late.
+ */
+export function propagateOnly(disposition) {
+    if (disposition.propagate)
+        return disposition;
+    return Object.freeze({
+        sameEndpointRetry: false,
+        nextProvider: false,
+        fallbackModel: false,
+        breaker: disposition.breaker,
+        propagate: true,
+    });
+}
 /**
  * The exhaustive failure → routing-behavior matrix (PRD §7.1). Pure; the
  * executor applies it, the circuit breaker consumes its `breaker` effect.

package/routing/executor.d.ts

@@ -7,6 +7,18 @@ export type AttemptOutcome<T> = Readonly<{
 }> | Readonly<{
     kind: "failure";
     error: InferenceAttemptError;
+    /**
+     * This attempt already put output somewhere the caller cannot take it
+     * back — tokens forwarded to a live view, or a provider-side effect a
+     * replay would repeat. The executor then **withholds all traversal** and
+     * propagates, because retrying re-renders a turn the user has partly seen.
+     *
+     * Omitted means replayable, which is right for a transport that buffers
+     * the whole completion before returning — it has shown nobody anything
+     * yet. Set it from the transport, at the point the first byte leaves:
+     * a boolean the transport flips when it forwards its first delta.
+     */
+    producedOutput?: boolean;
 }>;
 /**
  * One provider request. The host's transport adapter performs the network

package/routing/executor.js

@@ -1,4 +1,4 @@
-import { failureDisposition, isRetriableAttemptError, } from "./errors.js";
+import { failureDisposition, propagateOnly, isRetriableAttemptError, } from "./errors.js";
 /**
  * Drive one structured-output attempt over a frozen route plan with the
  * normative loop nesting (PRD §5.2): model stage → provider candidate →
@@ -71,7 +71,12 @@ export async function executeRoutePlan(options) {
                     };
                 }
                 failures.push(outcome.error);
-                const disposition = failureDisposition(outcome.error);
+                // The clamp is applied to the taxonomy's answer rather than folded into
+                // it, so `failureDisposition` stays total over the error kinds and this
+                // stays one testable step. See `propagateOnly`.
+                const disposition = outcome.producedOutput === true
+                    ? propagateOnly(failureDisposition(outcome.error))
+                    : failureDisposition(outcome.error);
                 switch (disposition.breaker) {
                     case "none":
                         // A breaker-invisible failure (abort, propagated client error)

package/routing/index.d.ts

@@ -6,7 +6,7 @@ export { buildRoutePlan, type RoutePlanRequest, type RoutePlanResult } from "./p
 export { buildRoutePlanWithConfigDegradation, type DegradedStage, type DegradedPlanResult, } from "./plan-degradation.js";
 export { computeConfiguredRatesCostCents, type BillingBasisUsage, type BillingBasisResult, } from "./billing-basis.js";
 export { fallbackKindOfCursor } from "./executor.js";
-export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, type RouteAttemptCursor, type AttemptTarget, type HttpFailureCategory, type InferenceAttemptError, type FailureDisposition, type BreakerEffect, } from "./errors.js";
+export { failureDisposition, propagateOnly, categorizeHttpStatus, isRetriableAttemptError, type RouteAttemptCursor, type AttemptTarget, type HttpFailureCategory, type InferenceAttemptError, type FailureDisposition, type BreakerEffect, } from "./errors.js";
 export { classifyAttemptError, retryAfterMsFromHeaders, isAbortByName, type AttemptClassification, type TransportFailure, type TransportFailureKind, } from "./attempt-errors.js";
 export { createCircuitBreaker, type BreakerKey, type CircuitBreakerOptions, type EndpointAdmission, type RecordFailureOptions, type RouteCircuitBreaker, } from "./circuit-breaker.js";
 export { executeRoutePlan, type AttemptOutcome, type AttemptFn, type FallbackKind, type ExecutePlanOptions, type RouteExecutionResult, } from "./executor.js";

package/routing/index.js

@@ -6,7 +6,7 @@ export { buildRoutePlan } from "./planner.js";
 export { buildRoutePlanWithConfigDegradation, } from "./plan-degradation.js";
 export { computeConfiguredRatesCostCents, } from "./billing-basis.js";
 export { fallbackKindOfCursor } from "./executor.js";
-export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, } from "./errors.js";
+export { failureDisposition, propagateOnly, categorizeHttpStatus, isRetriableAttemptError, } from "./errors.js";
 export { classifyAttemptError, retryAfterMsFromHeaders, isAbortByName, } from "./attempt-errors.js";
 export { createCircuitBreaker, } from "./circuit-breaker.js";
 export { executeRoutePlan, } from "./executor.js";

package/run/index.d.ts

@@ -1,3 +1,4 @@
 export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, type RunDeadline, type CoalescedHeartbeat, } from "./harness.js";
 export { runToolCallsPooledByTool } from "./tool-batch.js";
 export { rootChain, descendChain, admitChildRun, createPollSchedule, type ChainRef, type ChainRule, type ChildAdmission, type PollStep, type PollSchedule, type PollScheduleOptions, } from "./children.js";
+export { toolCallReceiptKeyString, canonicalJson, toolCallArgsHash, decideToolCallReceipt, type ToolCallReceiptKey, type DigestFn, type ReceiptState, type EffectResumability, type ReceiptDecision, } from "./receipts.js";

package/run/index.js

@@ -1,3 +1,4 @@
 export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, } from "./harness.js";
 export { runToolCallsPooledByTool } from "./tool-batch.js";
 export { rootChain, descendChain, admitChildRun, createPollSchedule, } from "./children.js";
+export { toolCallReceiptKeyString, canonicalJson, toolCallArgsHash, decideToolCallReceipt, } from "./receipts.js";

package/run/receipts.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Deciding whether a tool call has already happened, so a retry does not repeat
+ * its side effect.
+ *
+ * A durable runtime retries. A queue redelivers, a workflow step re-runs, a
+ * crashed worker's claim is reclaimed — and the agent loop starts the turn
+ * again. If the turn asked a tool to send an email, the retry sends a second
+ * one. A *receipt* is the row that lets the second attempt find out.
+ *
+ * Two things in that are the same for every host and belong here: **what
+ * identifies a call**, and **what to do about a receipt you found**. Everything
+ * else — the table, the clock, the transaction — is the host's, and this module
+ * deliberately owns none of it.
+ *
+ * ## Identity is content, not position
+ *
+ * A call is identified by `(tenant, run, tool, arguments)`. The tempting
+ * alternative is position — run + turn index + index within the batch — and it
+ * is wrong: **a retried turn is a fresh completion.** At any temperature above
+ * zero the model may reorder the batch, drop a call, or ask for a different
+ * tool at the same index. Position-keyed receipts then match calls that are not
+ * the same call, and the failure is the one this module exists to prevent: the
+ * first tool's recorded result is replayed as the second tool's, and the tool
+ * actually requested never runs.
+ *
+ * Content keying has the opposite failure mode, which is the safe one. A
+ * genuinely new call finds no receipt and executes; a repeated one finds its
+ * own. Nondeterminism costs an extra execution of something that was never run
+ * before, rather than a skipped execution of something that was.
+ *
+ * **The tenant is part of the key, not context.** A key without it cannot be
+ * partitioned or relocated by tenant, and two tenants' runs are not guaranteed
+ * to live in the same database.
+ *
+ * ## The decision needs a lease, not just a status
+ *
+ * "Recorded but not completed" does **not** mean "this may have reached the
+ * provider." On an at-least-once substrate it is also the ordinary state while
+ * another worker is *still running the call* — a queue that reclaims a wedged
+ * handler's claim can have two workers on one job by design. Treating that as
+ * ambiguous-and-never-repeat blocks the call permanently and needs a human.
+ *
+ * So the host records a **lease** and an **attempt counter**, and
+ * {@link decideToolCallReceipt} distinguishes the three cases a bare status
+ * cannot: someone else holds it and is alive (wait), someone else held it and
+ * died (reclaim, if the effect can resume), or it finished (replay).
+ *
+ * Two host obligations this module cannot enforce and a correct implementation
+ * needs:
+ *
+ *  - **Lease times come from the store's clock, not the process's.** Application
+ *    clocks drift enough to steal a live lease.
+ *  - **Every write gates on the attempt fence** (`status = 'running' AND
+ *    attempts = <mine>`), inside the same transaction as the side effect where
+ *    the store allows it. Fencing only the completion write leaves the window
+ *    where two attempts both believe they own the call.
+ *
+ * Monad's `agent_side_effect_receipts` is the worked example of all of the
+ * above; this module is the part of it that is not Postgres.
+ */
+/**
+ * What identifies a tool call across retries.
+ *
+ * All four parts are required. Dropping `tenantId` makes the key unpartitionable
+ * and, in a multi-database deployment, ambiguous; dropping `toolName` makes any
+ * two zero-argument calls in a run identical, and `{}` is the commonest
+ * argument bag there is.
+ */
+export interface ToolCallReceiptKey {
+    readonly tenantId: string;
+    readonly runId: string;
+    readonly toolName: string;
+    /** From {@link toolCallArgsHash}. */
+    readonly argsHash: string;
+}
+/**
+ * The key as one opaque string, for a store without composite keys (KV, a
+ * document id). A host with a composite primary key should use the parts
+ * directly and ignore this.
+ *
+ * Each part is length-prefixed, so no value can impersonate a boundary however
+ * many delimiters it contains.
+ */
+export declare function toolCallReceiptKeyString(key: ToolCallReceiptKey): string;
+/**
+ * Serialize a value so that two structurally equal values produce byte-equal
+ * strings.
+ *
+ * `JSON.stringify` does not: it emits object keys in insertion order, so
+ * `{a:1,b:2}` and `{b:2,a:1}` — the same arguments, assembled by two code paths
+ * or streamed in a different chunk order — serialize differently. A retry then
+ * reads "different arguments" and executes a call it should have replayed.
+ *
+ * Keys are sorted; arrays keep their order, because in an argument bag order is
+ * meaning. `undefined` becomes `null` rather than vanishing, so a key whose
+ * value is absent cannot be confused with a key that is not there.
+ *
+ * **A value this cannot represent faithfully throws rather than serializing to
+ * something wrong.** `toJSON` is honored exactly as `JSON.stringify` honors it,
+ * so a `Date` canonicalizes to its ISO string; but a `Map`, a `Set`, or a class
+ * instance keeping its state off the enumerable own keys has no such escape and
+ * would otherwise come out as `{}` — colliding with an *empty argument bag* and
+ * with every other such value. In a hash that decides whether a write already
+ * happened, a silent collision is the one failure worth crashing over. Cycles
+ * and excessive depth throw for the same reason, rather than overflowing the
+ * stack: a model can author deeply nested arguments, and `JSON.parse` accepts
+ * far deeper input than a recursive walk survives.
+ *
+ * Hash the raw parsed arguments, not the output of a schema parse that coerced
+ * types — that is how a `Date` gets in.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Hash the canonical form of a call's arguments. Supplied by the host because
+ * the package cannot name a digest: it builds with no DOM and no Node types, so
+ * neither `crypto.subtle` nor `node:crypto` is in scope — both are one line away
+ * in every runtime that would use this.
+ *
+ * **Use a full-width cryptographic digest.** The value is compared for equality
+ * here, but it is also *persisted*, and its input is tool arguments — routinely
+ * a recipient address or a document title. Over a low-entropy input domain an
+ * equality-comparable hash of user data is a confirmation oracle for anyone who
+ * can read the receipt table, so preimage resistance matters even though this
+ * code never inverts it. Truncating to save a column re-introduces collisions
+ * in exactly the comparison that decides whether a write already happened.
+ *
+ * It must also be **stable across process restarts and package versions** — a
+ * digest that changes orphans every receipt already stored.
+ */
+export type DigestFn = (canonical: string) => Promise<string>;
+/** Hash a call's arguments into the `argsHash` half of a {@link ToolCallReceiptKey}. */
+export declare function toolCallArgsHash(args: unknown, digest: DigestFn): Promise<string>;
+/**
+ * A receipt as the host found it. `absent` covers both "never recorded" and
+ * "recorded under a different key", which are the same thing to the decision.
+ *
+ * `leaseExpired` must be computed on the **store's** clock.
+ */
+export type ReceiptState = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "completed";
+} | {
+    readonly kind: "failed";
+    readonly attempts: number;
+} | {
+    readonly kind: "running";
+    readonly attempts: number;
+    readonly leaseExpired: boolean;
+};
+/**
+ * Whether an interrupted effect can be safely resumed.
+ *
+ * `resumable` — the host records each sub-operation as it completes, so a
+ * reclaimed attempt skips what already happened. Monad's canvas plans work this
+ * way.
+ *
+ * `opaque` — one indivisible side effect with no record of whether it landed.
+ * A reclaimed attempt cannot tell "never sent" from "sent, then crashed", and
+ * this module refuses to guess.
+ */
+export type EffectResumability = "resumable" | "opaque";
+/** What to do about the receipt that was found. */
+export type ReceiptDecision = 
+/** Execute, then complete the receipt under this attempt number. */
+{
+    readonly kind: "execute";
+    readonly attempt: number;
+}
+/** Do not execute. The recorded result is this call's result. */
+ | {
+    readonly kind: "replay";
+}
+/**
+ * Another attempt holds a live lease. Not a failure — come back. The host
+ * chooses the delay; a queue redelivery is the natural one.
+ */
+ | {
+    readonly kind: "wait";
+    readonly reason: string;
+}
+/**
+ * The effect may or may not have reached the outside world, and nothing can
+ * tell. Refuse rather than risk repeating it, and surface it — this is the
+ * state a human resolves.
+ */
+ | {
+    readonly kind: "ambiguous";
+    readonly reason: string;
+};
+/**
+ * Decide what a found receipt means. Pure; the host does the reading and the
+ * writing, and owns the clock that decided `leaseExpired`.
+ *
+ * The `running`-with-an-expired-lease case is the one worth understanding. It
+ * is **not** automatically ambiguous: on an at-least-once substrate a lease
+ * expires whenever a worker dies *or merely stalls*, which is common and
+ * recoverable. Whether it is safe to reclaim depends on something only the host
+ * knows — whether the effect left a trail. Hence {@link EffectResumability}.
+ */
+export declare function decideToolCallReceipt(input: {
+    readonly state: ReceiptState;
+    readonly effect: EffectResumability;
+}): ReceiptDecision;

package/run/receipts.js

@@ -0,0 +1,226 @@
+/**
+ * Deciding whether a tool call has already happened, so a retry does not repeat
+ * its side effect.
+ *
+ * A durable runtime retries. A queue redelivers, a workflow step re-runs, a
+ * crashed worker's claim is reclaimed — and the agent loop starts the turn
+ * again. If the turn asked a tool to send an email, the retry sends a second
+ * one. A *receipt* is the row that lets the second attempt find out.
+ *
+ * Two things in that are the same for every host and belong here: **what
+ * identifies a call**, and **what to do about a receipt you found**. Everything
+ * else — the table, the clock, the transaction — is the host's, and this module
+ * deliberately owns none of it.
+ *
+ * ## Identity is content, not position
+ *
+ * A call is identified by `(tenant, run, tool, arguments)`. The tempting
+ * alternative is position — run + turn index + index within the batch — and it
+ * is wrong: **a retried turn is a fresh completion.** At any temperature above
+ * zero the model may reorder the batch, drop a call, or ask for a different
+ * tool at the same index. Position-keyed receipts then match calls that are not
+ * the same call, and the failure is the one this module exists to prevent: the
+ * first tool's recorded result is replayed as the second tool's, and the tool
+ * actually requested never runs.
+ *
+ * Content keying has the opposite failure mode, which is the safe one. A
+ * genuinely new call finds no receipt and executes; a repeated one finds its
+ * own. Nondeterminism costs an extra execution of something that was never run
+ * before, rather than a skipped execution of something that was.
+ *
+ * **The tenant is part of the key, not context.** A key without it cannot be
+ * partitioned or relocated by tenant, and two tenants' runs are not guaranteed
+ * to live in the same database.
+ *
+ * ## The decision needs a lease, not just a status
+ *
+ * "Recorded but not completed" does **not** mean "this may have reached the
+ * provider." On an at-least-once substrate it is also the ordinary state while
+ * another worker is *still running the call* — a queue that reclaims a wedged
+ * handler's claim can have two workers on one job by design. Treating that as
+ * ambiguous-and-never-repeat blocks the call permanently and needs a human.
+ *
+ * So the host records a **lease** and an **attempt counter**, and
+ * {@link decideToolCallReceipt} distinguishes the three cases a bare status
+ * cannot: someone else holds it and is alive (wait), someone else held it and
+ * died (reclaim, if the effect can resume), or it finished (replay).
+ *
+ * Two host obligations this module cannot enforce and a correct implementation
+ * needs:
+ *
+ *  - **Lease times come from the store's clock, not the process's.** Application
+ *    clocks drift enough to steal a live lease.
+ *  - **Every write gates on the attempt fence** (`status = 'running' AND
+ *    attempts = <mine>`), inside the same transaction as the side effect where
+ *    the store allows it. Fencing only the completion write leaves the window
+ *    where two attempts both believe they own the call.
+ *
+ * Monad's `agent_side_effect_receipts` is the worked example of all of the
+ * above; this module is the part of it that is not Postgres.
+ */
+/**
+ * The key as one opaque string, for a store without composite keys (KV, a
+ * document id). A host with a composite primary key should use the parts
+ * directly and ignore this.
+ *
+ * Each part is length-prefixed, so no value can impersonate a boundary however
+ * many delimiters it contains.
+ */
+export function toolCallReceiptKeyString(key) {
+    return [key.tenantId, key.runId, key.toolName, key.argsHash]
+        .map((part) => `${part.length}:${part}`)
+        .join("|");
+}
+/**
+ * Serialize a value so that two structurally equal values produce byte-equal
+ * strings.
+ *
+ * `JSON.stringify` does not: it emits object keys in insertion order, so
+ * `{a:1,b:2}` and `{b:2,a:1}` — the same arguments, assembled by two code paths
+ * or streamed in a different chunk order — serialize differently. A retry then
+ * reads "different arguments" and executes a call it should have replayed.
+ *
+ * Keys are sorted; arrays keep their order, because in an argument bag order is
+ * meaning. `undefined` becomes `null` rather than vanishing, so a key whose
+ * value is absent cannot be confused with a key that is not there.
+ *
+ * **A value this cannot represent faithfully throws rather than serializing to
+ * something wrong.** `toJSON` is honored exactly as `JSON.stringify` honors it,
+ * so a `Date` canonicalizes to its ISO string; but a `Map`, a `Set`, or a class
+ * instance keeping its state off the enumerable own keys has no such escape and
+ * would otherwise come out as `{}` — colliding with an *empty argument bag* and
+ * with every other such value. In a hash that decides whether a write already
+ * happened, a silent collision is the one failure worth crashing over. Cycles
+ * and excessive depth throw for the same reason, rather than overflowing the
+ * stack: a model can author deeply nested arguments, and `JSON.parse` accepts
+ * far deeper input than a recursive walk survives.
+ *
+ * Hash the raw parsed arguments, not the output of a schema parse that coerced
+ * types — that is how a `Date` gets in.
+ */
+export function canonicalJson(value) {
+    return canonicalize(value, new Set(), 0);
+}
+/** Depth at which input is refused. Comfortably past any real argument bag, and
+ *  far below where a recursive walk overflows. */
+const MAX_DEPTH = 200;
+function canonicalize(value, seen, depth) {
+    if (depth > MAX_DEPTH) {
+        throw new TypeError(`canonicalJson: value nested deeper than ${MAX_DEPTH} levels. Tool ` +
+            `arguments are model-authored, so this is refused rather than walked.`);
+    }
+    if (typeof value === "object" && value !== null) {
+        if (seen.has(value)) {
+            throw new TypeError("canonicalJson: value contains a cycle.");
+        }
+        seen.add(value);
+        try {
+            if (Array.isArray(value)) {
+                // A plain `.map` preserves holes and `join` renders them empty, which
+                // emits `[,1]` — not valid JSON. Index explicitly so a hole becomes the
+                // `null` that `JSON.stringify` would have produced.
+                const items = [];
+                for (let i = 0; i < value.length; i++) {
+                    items.push(canonicalize(value[i], seen, depth + 1));
+                }
+                return `[${items.join(",")}]`;
+            }
+            const toJSON = value.toJSON;
+            if (typeof toJSON === "function") {
+                return canonicalize(toJSON.call(value), seen, depth + 1);
+            }
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== Object.prototype && proto !== null) {
+                throw new TypeError(`canonicalJson cannot faithfully serialize ${constructorNameOf(value)}: ` +
+                    `it is not a plain object and has no toJSON, so it would collapse to ` +
+                    `an empty object and collide with one.`);
+            }
+            return `{${Object.entries(value)
+                .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+                .map(([key, nested]) => `${JSON.stringify(key)}:${canonicalize(nested, seen, depth + 1)}`)
+                .join(",")}}`;
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    // Everything below would otherwise reach `JSON.stringify` and come back as
+    // the string "null" — the same bytes as an explicit `null`, and as each
+    // other. `{timeout: NaN}` and `{timeout: null}` fingerprinting alike means a
+    // replay skips a write that never happened, which is the failure this module
+    // exists to prevent. `undefined` is the one deliberate exception: it maps to
+    // `null` so a key whose value is absent stays distinguishable from a key that
+    // is not there, and that is worth its collision with an explicit `null`.
+    if (typeof value === "bigint" || typeof value === "symbol" || typeof value === "function") {
+        throw new TypeError(`canonicalJson cannot faithfully serialize a ${typeof value}: it has no ` +
+            `JSON form and would collapse to null, colliding with an explicit null.`);
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new TypeError(`canonicalJson cannot faithfully serialize ${String(value)}: JSON has no ` +
+            `representation for it, so it would collapse to null and collide with ` +
+            `an explicit null. A NaN here usually means a schema coerced a bad ` +
+            `value — fingerprint the raw parsed arguments instead.`);
+    }
+    // `JSON.stringify` returns undefined for a bare `undefined`.
+    return JSON.stringify(value) ?? "null";
+}
+function constructorNameOf(value) {
+    const name = value.constructor?.name;
+    return typeof name === "string" && name.length > 0 ? name : "a non-plain object";
+}
+/** Hash a call's arguments into the `argsHash` half of a {@link ToolCallReceiptKey}. */
+export async function toolCallArgsHash(args, digest) {
+    return digest(canonicalJson(args));
+}
+/**
+ * Decide what a found receipt means. Pure; the host does the reading and the
+ * writing, and owns the clock that decided `leaseExpired`.
+ *
+ * The `running`-with-an-expired-lease case is the one worth understanding. It
+ * is **not** automatically ambiguous: on an at-least-once substrate a lease
+ * expires whenever a worker dies *or merely stalls*, which is common and
+ * recoverable. Whether it is safe to reclaim depends on something only the host
+ * knows — whether the effect left a trail. Hence {@link EffectResumability}.
+ */
+export function decideToolCallReceipt(input) {
+    const { state, effect } = input;
+    switch (state.kind) {
+        case "absent":
+            return { kind: "execute", attempt: 1 };
+        case "completed":
+            return { kind: "replay" };
+        case "failed":
+            // A failed attempt is a finished one: it released its lease and recorded
+            // that it did not succeed. Retrying is the point of recording the failure.
+            return { kind: "execute", attempt: nextAttempt(state.attempts) };
+        case "running":
+            if (!state.leaseExpired) {
+                return {
+                    kind: "wait",
+                    reason: "another attempt holds a live lease on this call — it is running, " +
+                        "not stuck; retry once the lease would have expired",
+                };
+            }
+            return effect === "resumable"
+                ? { kind: "execute", attempt: nextAttempt(state.attempts) }
+                : {
+                    kind: "ambiguous",
+                    reason: "an attempt claimed this call and its lease expired without " +
+                        "completing. The effect is not resumable, so whether it reached " +
+                        "the outside world cannot be determined — repeating it may " +
+                        "duplicate it",
+                };
+        default: {
+            const _exhaustive = state;
+            throw new Error(`unknown receipt state: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+function nextAttempt(attempts) {
+    // A broken counter must not silently reset the fence to 1 and let two
+    // attempts believe they own the call.
+    if (!Number.isInteger(attempts) || attempts < 1) {
+        throw new TypeError(`receipt attempts must be a positive integer, got ${String(attempts)}`);
+    }
+    return attempts + 1;
+}