@zackbart/connecta 0.34.1 → 0.35.0

package/dist/providers/_shared/rest/operation-index.js

@@ -1,3 +1,5 @@
+import { canonicalJson } from "../../../canonical-json.js";
+import { parseIndexDetails } from "./compact-index.js";
 // The pinned operation index a REST connector validates against before it
 // sends anything. `scripts/generate-openapi.mjs` compiles a vendor's OpenAPI
 // document into `OpenApiData` (search rows plus request-side details as one
@@ -114,16 +116,26 @@ export class OperationIndex {
     #vendor;
     #segments;
     #slashParams;
+    #uriTemplates;
+    get pathMatching() {
+        return this.#uriTemplates ? "uri-template" : "segments";
+    }
     #details;
+    #fields;
+    #requestSchemas;
     #words;
     /**
      * `vendor` is the tool-name prefix; `title` the display name in refusals.
      * `slashParams` names path parameters whose values may carry an encoded
      * "/" (`%2F`), such as an object key, and only as the path's last segment.
+     * `pathMatching: "uri-template"` opts into decoded literals and parameters
+     * embedded in a segment, such as Google's `{id}:batchUpdate`. The default
+     * retains exact literal segments and whole-segment parameters.
      */
     constructor(data, names) {
         const { title } = names;
         this.#slashParams = new Set(names.slashParams ?? []);
+        this.#uriTemplates = names.pathMatching === "uri-template";
         this.#data = data;
         this.#title = title;
         this.#vendor = names.vendor;
@@ -145,6 +157,46 @@ export class OperationIndex {
         this.#segments = this.ops.map((op) => op.path.slice(1).split("/"));
         this.methods = [...METHODS].filter((method) => this.ops.some((op) => op.method === method));
     }
+    /** Content binding for discovery continuations; labels alone never identify an index. */
+    async cursorRevision() {
+        const bytes = new TextEncoder().encode(canonicalJson([
+            this.#data,
+            this.revision,
+            [...this.#slashParams].sort(),
+            ...(this.#uriTemplates ? ["uri-template"] : []),
+        ]));
+        return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    }
+    /** The request and response properties this operation declares; none when the index carries no fields. */
+    fields(op) {
+        if (!this.#fields) {
+            const data = this.#data.fields;
+            if (typeof data === "string") {
+                // Generated REST indexes share response paths and complete rows. Kit
+                // vendor indexes retain their directly declared body/response fields.
+                const { p, d, o } = JSON.parse(data);
+                const rows = d.map((ids) => ids.map((id) => ({ in: "response", path: p[id] })));
+                this.#fields = o.map((id) => rows[id]);
+            }
+            else
+                this.#fields = data ?? [];
+        }
+        return this.#fields[op.row] ?? [];
+    }
+    /**
+     * The names a result's first dot-path segment may take: the success
+     * response's own properties, or its items' properties when it is an array.
+     * Undefined when the operation declares no response contract.
+     */
+    responseRoots(op) {
+        const paths = this.fields(op).filter((field) => field.in === "response");
+        if (paths.length === 0)
+            return undefined;
+        return new Set(paths.map((field) => field.path
+            .replace(/^\[\]\./, "")
+            .split(".")[0]
+            .replace(/\[\]$/, "")));
+    }
     /** The operation with this exact method and path template, if any. */
     operation(method, template) {
         return this.ops.find((op) => op.method === method && op.path === template);
@@ -165,11 +217,29 @@ export class OperationIndex {
                 return;
             let score = 0;
             for (const [index, part] of template.entries()) {
-                if (part.startsWith("{"))
+                if (!this.#uriTemplates) {
+                    if (part.startsWith("{"))
+                        continue;
+                    if (part !== segments[index])
+                        return;
+                    score += 1;
                     continue;
-                if (part !== segments[index])
-                    return;
-                score += 1;
+                }
+                const parameter = /^(.*)\{([^{}]+)\}(.*)$/.exec(part);
+                const value = decodeURIComponent(segments[index]);
+                if (parameter) {
+                    if (!value.startsWith(parameter[1]) ||
+                        !value.endsWith(parameter[3]) ||
+                        value.length <= parameter[1].length + parameter[3].length)
+                        return;
+                    if (parameter[1] || parameter[3])
+                        score += 0.5;
+                }
+                else {
+                    if (part !== value)
+                        return;
+                    score += 1;
+                }
             }
             if (score > best.score)
                 best = { score, rows: [row] };
@@ -195,9 +265,34 @@ export class OperationIndex {
         }
         const params = {};
         template.forEach((part, index) => {
-            if (part.startsWith("{"))
-                params[part.slice(1, -1)] = segments[index];
+            if (!this.#uriTemplates) {
+                if (part.startsWith("{"))
+                    params[part.slice(1, -1)] = segments[index];
+                return;
+            }
+            const parameter = /^(.*)\{([^{}]+)\}(.*)$/.exec(part);
+            if (parameter) {
+                const raw = segments[index];
+                const prefix = parameter[1], suffix = parameter[3];
+                params[parameter[2]] =
+                    raw.startsWith(prefix) && raw.endsWith(suffix)
+                        ? raw.slice(prefix.length, suffix ? -suffix.length : undefined)
+                        : encodeURIComponent(decodeURIComponent(raw).slice(prefix.length, suffix ? -suffix.length : undefined));
+            }
         });
+        const issues = [];
+        const repair = [];
+        for (const [name, at, , schema] of this.#row(op)?.[0] ?? []) {
+            if (at === "path" && params[name] !== undefined)
+                this.#check(schema, decodeURIComponent(params[name]), `/path/${name}`, issues, repair);
+        }
+        if (issues.length) {
+            const shown = issues
+                .slice(0, 5)
+                .map((issue) => `${issue.path} (${issue.code}: ${issue.expected})`)
+                .join("; ");
+            invalid(`Not sent: the path does not match ${op.method} ${op.path} in the pinned API index: ${shown}. Substitute real ids matching ${this.#vendorTool("details")}.${issues.some((issue) => issue.expected?.includes("safe integer")) ? " Integer ids use canonical ASCII decimal notation within the safe-integer range." : ""}`, issues.slice(0, MAX_ISSUES));
+        }
         return { op, params };
     }
     /** Up to five operations whose paths most resemble a missed one. */
@@ -231,6 +326,9 @@ export class OperationIndex {
      * the path, summary, operationId, or tag (plural-insensitive, prefixes of
      * three letters count), and path matches weigh most. A query that starts
      * with "/" also matches the templates that fit it.
+     * Standard hatches opt into partial matches, ordered by matched term count
+     * before relevance, including the person/people alias. Legacy callers keep
+     * the all-term contract.
      */
     search(query, options) {
         this.#words ??= this.ops.map((op) => ({
@@ -261,6 +359,12 @@ export class OperationIndex {
             if (set.has(term))
                 return 2;
             for (const word of set) {
+                if (options.partial && ((term === "person" && word === "people") || (term === "people" && word === "person")))
+                    return 2;
+                if (options.partial &&
+                    ((term.endsWith("y") && word === `${term.slice(0, -1)}ies`) ||
+                        (word.endsWith("y") && term === `${word.slice(0, -1)}ies`)))
+                    return 2;
                 if (word === `${term}s` || term === `${word}s` || word === `${term}es` || term === `${word}es`)
                     return 2;
                 if (term.length >= 3 && word.startsWith(term))
@@ -280,12 +384,13 @@ export class OperationIndex {
                     matched += 1;
                 score += path * 3 + summary * 1.5 + id;
             }
-            if (!fits.has(op.row) && (terms.length === 0 || matched < terms.length))
+            if (!fits.has(op.row) && (terms.length === 0 || matched < (options.partial ? 1 : terms.length)))
                 return [];
-            return [{ op, score }];
+            return [{ op, score, matched }];
         });
         return ranked
-            .sort((a, b) => b.score - a.score ||
+            .sort((a, b) => (options.partial ? b.matched - a.matched : 0) ||
+            b.score - a.score ||
             a.op.path.split("/").length - b.op.path.split("/").length ||
             a.op.path.localeCompare(b.op.path))
             .slice(0, options.limit)
@@ -302,8 +407,16 @@ export class OperationIndex {
         const declared = row ? row[0] : [];
         // A generator may omit plain-string path parameters (`pathParams:
         // "typed"`); the template still names them, so the contract does too.
-        const implied = this.#segments[op.row].filter((part) => part.startsWith("{") && !declared.some(([name, at]) => at === "path" && name === part.slice(1, -1)))
-            .map((part) => [part.slice(1, -1), "path", 1, { t: "string" }]);
+        const implied = this.#segments[op.row].flatMap((part) => {
+            const name = this.#uriTemplates
+                ? /\{([^{}]+)\}/.exec(part)?.[1]
+                : part.startsWith("{")
+                    ? part.slice(1, -1)
+                    : undefined;
+            return name !== undefined && !declared.some(([key, at]) => at === "path" && key === name)
+                ? [[name, "path", 1, { t: "string" }]]
+                : [];
+        });
         const parameters = [...implied, ...declared]
             .filter(([name]) => only === undefined || name === only)
             .map(([name, at, required, schema, description]) => ({
@@ -317,7 +430,22 @@ export class OperationIndex {
         if (row && row[1] !== 0) {
             const [contentType, schema] = row[1];
             const node = this.#deref(schema);
-            if (only !== undefined && node.p?.[only] !== undefined) {
+            const full = this.#requestSchema(op);
+            if (full && only === undefined) {
+                body = { contentType, ...(row[1][2] === 1 ? { required: true } : {}), schema: full };
+            }
+            else if (full && only !== undefined && full["properties"]?.[only]) {
+                body = {
+                    contentType,
+                    schema: {
+                        type: "object",
+                        properties: { [only]: full["properties"][only] },
+                        ...(Array.isArray(full["required"]) && full["required"].includes(only) ? { required: [only] } : {}),
+                        ...(full["$defs"] ? { $defs: full["$defs"] } : {}),
+                    },
+                };
+            }
+            else if (only !== undefined && node.p?.[only] !== undefined) {
                 body = {
                     contentType,
                     schema: {
@@ -402,8 +530,40 @@ export class OperationIndex {
     #vendorTool(kind) {
         return `${this.#vendor}_api_${kind}`;
     }
+    #requestSchema(op) {
+        if (!this.#data.requestSchemas)
+            return undefined;
+        this.#requestSchemas ??= JSON.parse(this.#data.requestSchemas);
+        const graph = this.#requestSchemas;
+        const root = graph.roots[op.row];
+        if (!root)
+            return undefined;
+        const definitions = {};
+        const visit = (value) => {
+            if (!value || typeof value !== "object")
+                return;
+            if (Array.isArray(value)) {
+                for (const child of value)
+                    visit(child);
+                return;
+            }
+            const object = value;
+            if (typeof object["$ref"] === "string" && object["$ref"].startsWith("#/$defs/")) {
+                const name = object["$ref"].slice(8);
+                if (!Object.hasOwn(definitions, name)) {
+                    definitions[name] = graph.definitions[name] ?? {};
+                    visit(definitions[name]);
+                }
+            }
+            for (const child of Object.values(object))
+                visit(child);
+        };
+        visit(root);
+        const resolved = typeof root["$ref"] === "string" ? graph.definitions[root["$ref"].slice(8)] : root;
+        return { ...resolved, ...(Object.keys(definitions).length ? { $defs: definitions } : {}) };
+    }
     #row(op) {
-        this.#details ??= JSON.parse(this.#data.details);
+        this.#details ??= parseIndexDetails(this.#data);
         const row = this.#details.o[op.row];
         return row === 0 ? undefined : row;
     }
@@ -427,6 +587,12 @@ export class OperationIndex {
             out["format"] = resolved.f;
         if (resolved.n === 1)
             out["nullable"] = true;
+        if (resolved.l !== undefined)
+            out["minimum"] = resolved.l;
+        if (resolved.u !== undefined)
+            out["maximum"] = resolved.u;
+        if (resolved.deprecated === true)
+            out["deprecated"] = true;
         if (resolved.a)
             out["anyOf"] = resolved.a.map((branch) => this.#schema(branch));
         if (resolved.p) {
@@ -446,6 +612,35 @@ export class OperationIndex {
         if (issues.length >= MAX_ISSUES)
             return;
         const schema = this.#deref(node);
+        const path = at.startsWith("/path/");
+        const types = typesOf(schema);
+        if (path && !schema.a && !types.includes("string") && (types.includes("integer") || types.includes("number"))) {
+            const integer = types.includes("integer") && !types.includes("number");
+            const numeric = typeof value === "string" ? Number(value) : NaN;
+            const syntax = integer ? /^(?:0|-?[1-9][0-9]*)$/ : /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/;
+            if (typeof value !== "string" ||
+                !syntax.test(value) ||
+                Object.is(numeric, -0) ||
+                !Number.isFinite(numeric) ||
+                Math.abs(numeric) > Number.MAX_SAFE_INTEGER ||
+                (integer && !Number.isSafeInteger(numeric))) {
+                issues.push({
+                    path: at,
+                    code: "type",
+                    expected: integer ? "a canonical ASCII decimal safe integer" : "a canonical ASCII decimal number",
+                });
+                return;
+            }
+            value = numeric;
+        }
+        else if (path && types.length && !types.includes("string") && !schema.a) {
+            if (types.includes("boolean") && (value === "true" || value === "false"))
+                value = value === "true";
+            else {
+                issues.push({ path: at, code: "type", expected: types.join(" or ") });
+                return;
+            }
+        }
         if (schema.x === 1)
             return;
         // Conflicting composed constraints (disjoint enums or types) admit nothing,
@@ -454,6 +649,28 @@ export class OperationIndex {
             issues.push({ path: at, code: "enum", expected: "no value: this field's combined constraints admit none" });
             return;
         }
+        // Only newly opted-in bounded schemas enforce scalar numeric values;
+        // existing indexes retain their previous validation behavior. HTTP query
+        // strings may represent numbers, but must match the declared numeric type.
+        if (schema.l !== undefined || schema.u !== undefined) {
+            if (value === null && schema.n === 1)
+                return;
+            const integer = typesOf(schema).includes("integer");
+            const syntax = integer ? /^-?\d+$/ : /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+            const numeric = typeof value === "number"
+                ? value
+                : at.startsWith("/query/") && typeof value === "string" && syntax.test(value)
+                    ? Number(value)
+                    : NaN;
+            if (!Number.isFinite(numeric) || (integer && !Number.isSafeInteger(numeric))) {
+                issues.push({ path: at, code: "type", expected: integer ? "integer" : "finite number" });
+                return;
+            }
+            if (schema.l !== undefined && numeric < schema.l)
+                issues.push({ path: at, code: "minimum", expected: `at least ${schema.l}` });
+            if (schema.u !== undefined && numeric > schema.u)
+                issues.push({ path: at, code: "maximum", expected: `at most ${schema.u}` });
+        }
         if (value === null || value === "")
             return;
         if (schema.a) {
@@ -472,7 +689,6 @@ export class OperationIndex {
             }
             return;
         }
-        const types = typesOf(schema);
         if (schema.e && (typeof value === "string" || typeof value === "number" || typeof value === "boolean")) {
             if (!schema.e.some((option) => option === value || String(option) === String(value))) {
                 issues.push({ path: at, code: "enum", expected: oneOf(schema.e.map(String)) });

package/dist/providers/_shared/rest/response-media.js

@@ -0,0 +1,11 @@
+/** Match a reviewed non-JSON success media type only on its pinned operation. */
+export function responseMedia(media, status, operation, contentType = "") {
+    if (status < 200 || status > 299)
+        return undefined;
+    const type = contentType.split(";", 1)[0].trim().toLowerCase();
+    const path = operation.template.replace(/:([^/]+)/g, "{$1}");
+    if (!type ||
+        !media[`${operation.method} ${path}`]?.some((declared) => declared === type || (declared.endsWith("/*") && type.startsWith(declared.slice(0, -1)))))
+        return undefined;
+    return /^text\/|\bxml\b|\bcsv\b|\b(?:x-ndjson|jsonl|stream\+json)\b/.test(type) ? "text" : "binary";
+}

package/dist/providers/_shared/rest/tools.js

@@ -1,6 +1,41 @@
+// Connecta's generic REST connector over one vendor's pinned operation index.
+//
+// `restTools(vendor)` returns four tools named `<vendor>_api_search`,
+// `_api_details`, `_api_read`, and `_api_write`. The first two read the index
+// and send nothing. `_api_read` sends GET, plus the vendor's reviewed
+// read-only POSTs; classification is per tool name, so that rule is enforced
+// here in the handler, not inferred. `_api_write` sends every other method and
+// is always destructive, with `method` and `path` top-level arguments so a
+// host's approval prompt shows them.
+//
+// Every call is matched to an operation and checked against its contract
+// before transport (unknown path → nearest operations; unknown or missing
+// parameters → `validation.issues`), then the vendor's reviewed refusals run,
+// then the vendor frames the request. Every vendor answers in one envelope:
+// `{ status, data, page?: { hasMore, next?, param? } }`, with an optional
+// `select` projection and no default projection. A write is dispatched once
+// (INV-9): nothing here retries it or replays it against another
+// implementation.
+//
+// A vendor adopts this module with configuration only: its transport, its
+// failure mapper, and optional `scope` (defaults and pins), `encode` (body
+// and query framing), `page` (cursor extraction), `refuse` (argument-dependent refusals),
+// `readPosts`, and an idempotency header. Every vendor ships a reviewed
+// value-safety table (`valueSafety`, `value-safety.ts` here): its refusals run
+// in the generic tools before any request, and its redaction runs on every
+// successful body in `callRest`, after `result` and before cursors and
+// `select`. Optional hooks cover the rest: `path` (fill default ids before
+// matching), `admit` (an awaited check in `callRest`, which every tool passes,
+// such as an account pin), `result` (unwrap a vendor envelope), a reviewed
+// `headers` allowlist, and `textBodies`. Named tools reuse `restCall` and
+// `callRest` to share the same validation-free request path.
+import { callClassification } from "../../../call-classification.js";
+import { providerFailureMessage } from "../../../write-outcome.js";
 import { guardedFetch, } from "../../../connectors/guarded-fetch.js";
 import { IDEMPOTENCY_KEY_MAX_LENGTH, recordRecovery } from "../../../call-recovery.js";
-import { ConnectorCallError, unavailableCallError } from "../../../errors.js";
+import { providerRequests } from "../../../provider-call.js";
+import { ConnectorCallError, keyResendAdvice, unavailableCallError } from "../../../errors.js";
+import { encodeForAgent, redactBeforeCut } from "../../../sent-secrets.js";
 const READ = { readOnlyHint: true };
 const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
 const MAX_SELECT = 50;
@@ -10,6 +45,24 @@ function isRecord(value) {
 function invalid(message) {
     throw new ConnectorCallError("invalid_args", message);
 }
+/** A header value as fetch sends it: leading and trailing HTTP whitespace removed. */
+function sentValue(value) {
+    return value.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, "");
+}
+/**
+ * Why fetch would not send `value` as a header value the vendor receives:
+ * blank once trimmed, or a byte fetch rejects (CR, LF, NUL, any other control
+ * character but tab, DEL, or a code point past Latin-1). Undici refuses the
+ * whole request for any of them; workerd at least for CR, LF and NUL.
+ */
+function unsendableKey(value) {
+    const sent = sentValue(value);
+    if (sent === "")
+        return "is blank; pass a key with at least one non-whitespace character";
+    if (!/^[\t\x20-\x7e\x80-\xff]*$/.test(sent))
+        return "contains a character an HTTP header cannot carry (a control character, or one past Latin-1); pass a printable key";
+    return undefined;
+}
 /**
  * A guarded transport whose requests, response bodies included, end after
  * `timeoutMs`: a stream the vendor never closes cannot hold a call open past
@@ -67,13 +120,6 @@ async function failureBody(response) {
         return undefined;
     }
 }
-function base64(bytes) {
-    let binary = "";
-    for (let offset = 0; offset < bytes.length; offset += 0x8000) {
-        binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
-    }
-    return btoa(binary);
-}
 async function successBody(vendor, response, ctx) {
     const type = (response.headers.get("content-type") ?? "").toLowerCase();
     try {
@@ -109,7 +155,8 @@ async function successBody(vendor, response, ctx) {
             return text === "" ? null : text;
         }
         const bytes = await response.bytes();
-        return bytes.length === 0 ? null : { contentType: type, bytes: bytes.length, base64: base64(bytes) };
+        // Checked before encoding: no later pass reads through base64 a field does not declare.
+        return bytes.length === 0 ? null : { contentType: type, bytes: bytes.length, base64: encodeForAgent(ctx, bytes) };
     }
     catch (error) {
         if (error instanceof ConnectorCallError)
@@ -127,36 +174,6 @@ async function successBody(vendor, response, ctx) {
         throw unavailableCallError(error, undefined, `${vendor.title} answered, but its response could not be read.`);
     }
 }
-/**
- * Network failures that prove nothing was sent, but only when `fetch` itself
- * rejected before any response existed: no connection was ever established,
- * so the vendor cannot have acted. Once a response arrived, the same codes
- * while reading its body prove nothing of the kind.
- */
-const NEVER_CONNECTED = new Set([
-    "ECONNREFUSED",
-    "ENOTFOUND",
-    "EAI_AGAIN",
-    "EAI_FAIL",
-    "EHOSTUNREACH",
-]);
-/**
- * A request that is not safe to repeat (a write without an idempotency key)
- * must never be advertised as retryable after it may have reached the vendor
- * (INV-9). Definite answers pass through: refusals and 4xx verdicts, a failure
- * proven to precede any connection, and timeouts, which the invocation layer
- * already reports as `write_outcome_unknown`. Exported so a named write tool
- * with its own transport (an upload) applies the same rule.
- */
-export function unknownOutcome(vendor, error, responded) {
-    if (!(error instanceof ConnectorCallError) || error.code !== "unavailable" || !error.retryable)
-        return error;
-    const code = error.details?.code;
-    if (code === "timeout" || (!responded && code !== undefined && NEVER_CONNECTED.has(code)))
-        return error;
-    return new ConnectorCallError("connector_call_failed", `${error.message} Whether the write took effect at ${vendor.title} is unknown: it carried no idempotency key, ` +
-        "so check the target before repeating it.", { retryable: false });
-}
 /**
  * Send one prepared call and read it into the envelope. No validation and no
  * refusal tables run here: the generic tools do both first, and named tools
@@ -169,14 +186,19 @@ export async function callRest(vendor, call, ctx, visibleHeaders = {}) {
         invalid(send);
     await vendor.admit?.(call, ctx);
     const framing = vendor.encode ? vendor.encode(call) : defaultFraming(vendor, call);
-    // Safe to repeat: a read, or a write that carried the vendor's idempotency key.
     const header = vendor.idempotencyHeader?.toLowerCase();
-    const repeatable = call.method === "GET" ||
-        call.method === "HEAD" ||
-        (vendor.readPosts ?? []).some(([method, path]) => method === call.method && path === call.op.path) ||
-        (header !== undefined && Object.keys(visibleHeaders).some((name) => name.toLowerCase() === header));
+    const idempotencyKey = header === undefined
+        ? undefined
+        : Object.entries(visibleHeaders).find(([name, value]) => name.toLowerCase() === header && unsendableKey(value) === undefined)?.[1];
     const request = {
         method: call.method,
+        classification: call.method === "GET" ||
+            call.method === "HEAD" ||
+            (vendor.readPosts ?? []).some(([method, path]) => method === call.method && path === call.op.path)
+            ? "read"
+            : "write",
+        // Only a key the vendor receives proves the write repeatable.
+        ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
         path: call.path,
         ...(framing.query ? { query: framing.query } : {}),
         ...(framing.headers ? { headers: framing.headers } : {}),
@@ -187,30 +209,22 @@ export async function callRest(vendor, call, ctx, visibleHeaders = {}) {
                 ? { body: framing.body }
                 : {}),
     };
-    // Set once a response exists: from then on the connection is proven, and no
-    // network failure means nothing was sent.
-    let responded = false;
-    try {
-        return await send(request, ctx, async (response) => {
-            responded = true;
-            if (!response.ok)
-                throw vendor.failure(response.status, response.headers, await failureBody(response), call);
-            // HEAD answers with headers alone; they are its data.
-            const body = call.method === "HEAD" ? headerData(response.headers) : await successBody(vendor, response, ctx);
-            // Order: unwrap the vendor's envelope, then redact (every success, HEAD
-            // header data and named tools included), then cursors (and, in the
-            // tools, `select`). Cursors read the envelope when the vendor unwraps
-            // one, and the redacted body otherwise.
-            const unwrapped = vendor.result && call.method !== "HEAD" ? vendor.result(body, call, response) : body;
-            const data = vendor.valueSafety.redact(unwrapped, call.method, call.op.path);
-            const page = vendor.page?.(vendor.result ? body : data, call);
-            return { status: response.status, data, ...(page ? { page } : {}) };
-        });
-    }
-    catch (error) {
-        // The whole transport call: connect/send failures, 5xx, and a lost body alike.
-        throw repeatable ? error : unknownOutcome(vendor, error, responded);
-    }
+    const write = (callClassification(ctx) ?? request.classification) === "write";
+    return await send(request, ctx, async (response) => {
+        // Mappers cut the vendor's prose short, so it is redacted whole first.
+        if (!response.ok)
+            throw vendor.failure(response.status, response.headers, redactBeforeCut(ctx, await failureBody(response)), call, write);
+        // HEAD answers with headers alone; they are its data.
+        const body = call.method === "HEAD" ? headerData(response.headers) : await successBody(vendor, response, ctx);
+        // Order: unwrap the vendor's envelope, then redact (every success, HEAD
+        // header data and named tools included), then cursors (and, in the
+        // tools, `select`). Cursors read the envelope when the vendor unwraps
+        // one, and the redacted body otherwise.
+        const unwrapped = vendor.result && call.method !== "HEAD" ? vendor.result(body, call, response, ctx) : body;
+        const data = vendor.valueSafety.redact(unwrapped, call.method, call.op.path);
+        const page = vendor.page?.(vendor.result ? body : data, call);
+        return { status: response.status, data, ...(page ? { page } : {}) };
+    });
 }
 /** A HEAD response's headers as data, without cookies. */
 function headerData(headers) {
@@ -340,6 +354,9 @@ export function restTools(vendor) {
         op.method === "HEAD" ||
         readPosts.some(([method, path]) => method === op.method && path === op.path);
     const writeMethods = index.methods.filter((method) => method !== "GET" && method !== "HEAD");
+    // The methods an idempotency key is sent with: never DELETE (see the handler).
+    const keyed = vendor.idempotencyHeader ? writeMethods.filter((method) => method !== "DELETE") : [];
+    const keyedText = keyed.join(" or ");
     const head = index.methods.includes("HEAD");
     const readMethods = [...new Set(["GET", ...(head ? ["HEAD"] : []), ...readPosts.map(([method]) => method)])];
     const routeOf = (op) => (reads(op) ? tool("read") : tool("write"));
@@ -490,7 +507,7 @@ export function restTools(vendor) {
         {
             name: tool("write"),
             description: `Call a ${title} API write (${writeMethods.join(", ")}); method and path are stated for approval. ` +
-                `Checked against the pinned index first.${vendor.idempotencyHeader ? " Pass idempotencyKey to retry safely." : ""}`,
+                `Checked against the pinned index first.${keyed.length ? ` Pass idempotencyKey to retry a ${keyedText} safely${keyed.length < writeMethods.length ? "; a DELETE sends no key" : ""}.` : ""}`,
             annotations: DESTRUCTIVE,
             inputSchema: closed({
                 method: { type: "string", enum: writeMethods, description: "The operation's HTTP method." },
@@ -507,7 +524,7 @@ export function restTools(vendor) {
                             type: "string",
                             minLength: 1,
                             maxLength: IDEMPOTENCY_KEY_MAX_LENGTH,
-                            description: "Reuse to retry this exact write; one is generated and returned when omitted.",
+                            description: `Reuse to retry this exact ${keyedText}; one is generated and returned when omitted.`,
                         },
                     }
                     : {}),
@@ -539,6 +556,11 @@ export function restTools(vendor) {
                 index.check(call.op, call.query, call.body);
                 const header = vendor.idempotencyHeader && call.method !== "DELETE" ? vendor.idempotencyHeader : undefined;
                 const given = typeof args["idempotencyKey"] === "string" ? args["idempotencyKey"] : undefined;
+                // A blank key reaches the vendor empty, and one fetch cannot carry
+                // never leaves: neither proves that a retry cannot repeat the write.
+                const unsendable = given === undefined ? undefined : unsendableKey(given);
+                if (unsendable)
+                    invalid(`idempotencyKey ${unsendable}, or omit it.`);
                 const key = header ? (given ?? crypto.randomUUID()) : undefined;
                 // Recorded before dispatch: if the invocation deadline interrupts this
                 // call, no failure of ours arrives, and the invocation returns the key
@@ -552,16 +574,17 @@ export function restTools(vendor) {
                 catch (error) {
                     // A generated key exists nowhere else, so a failure must carry it:
                     // only that key lets the caller check or retry this exact write.
+                    // The key stays in the message as a diagnostic; the advice to
+                    // reuse it is a segment the invocation composes only where the key
+                    // protects the whole logical call (keyResendAdvice), and exists
+                    // only once the ledger shows a dispatched request carrying it.
                     if (!key || given || !(error instanceof ConnectorCallError))
                         throw error;
-                    throw new ConnectorCallError(error.code, `${error.message} ${header}: ${key}. Reusing it with the exact original arguments retries this write ` +
-                        "without repeating it only while the vendor retains the key; after that, look the object up before retrying.", {
-                        retryable: error.retryable,
-                        ...(error.retryAfterMs !== undefined ? { retryAfterMs: error.retryAfterMs } : {}),
-                        ...(error.validation ? { validation: error.validation } : {}),
-                        ...(error.repair ? { repair: error.repair } : {}),
-                        ...(error.details ? { details: error.details } : {}),
-                    });
+                    const failure = providerFailureMessage(error, `${error.message} ${header}: ${key}.`);
+                    if (!providerRequests(ctx)?.some((request) => request.dispatched && request.key === key))
+                        throw failure;
+                    throw keyResendAdvice(failure, key, " Reusing it with the exact original arguments retries this write without repeating it only while " +
+                        "the vendor retains the key; after that, look the object up before retrying.");
                 }
             },
         },