@zackbart/connecta 0.34.0 → 0.35.0

package/dist/http/json-schema.js

@@ -0,0 +1,267 @@
+// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+//
+// One Schema is a tool's type, its argument decoder, and its catalog JSON
+// Schema. Effect's generator is correct but spells some things differently
+// from the catalogs agents already read, and catalog bytes may not change
+// without a recorded decision. This renders the "connecta dialect": the same
+// constraints, minus what JSON Schema already defaults or Effect adds for its
+// own decoder.
+//
+// - `additionalProperties: true` is the default and is dropped. Inputs are
+//   closed (`onExcessProperty: "error"`), and their root always names
+//   `required`, as every hand-written input does.
+// - Nothing the decoder enforces is dropped. `Schema.Int` refuses integers
+//   past 2^53 and says so (`minimum`/`maximum`); catalogs have always meant
+//   any whole number, so kit Schemas use `Integer` below, which decodes and
+//   renders exactly that.
+// - String lengths count code points, as JSON Schema and api()'s validator
+//   (@cfworker/json-schema's `ucs2length`) do: an astral character is one,
+//   a combining mark is one, and a lone surrogate is one. Effect's
+//   `isMinLength`/`isMaxLength` count UTF-16 units and render an
+//   approximation, so kit Schemas use `isMinChars`/`isMaxChars` below, and an
+//   input whose check renders approximately, or not at all, is refused at
+//   construction.
+// - An array's own keywords (`maxItems`, `description`) come before `items`.
+// - `anyOf` over primitive branches with disjoint types, each constrained only
+//   by keywords that apply to its own type, becomes one `type` array. Bare
+//   object and array branches also collapse. JSON
+//   Schema applies `minLength` only to strings and `minimum` only to numbers,
+//   so the two spellings accept exactly the same values.
+//
+// Only the stable `effect` Schema module is used here.
+import { Schema } from "effect";
+const NUMERIC = new Set(["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"]);
+const OWN_KEYWORDS = {
+    string: new Set(["minLength", "maxLength", "pattern", "format"]),
+    integer: NUMERIC,
+    number: NUMERIC,
+    boolean: new Set(),
+    null: new Set(),
+    // Bare object/array unions are exact too; constrained branches keep anyOf.
+    object: new Set(),
+    array: new Set(["items", "minItems", "maxItems", "uniqueItems"]),
+};
+/**
+ * A whole number, as JSON Schema's `type: integer` and api()'s validator mean
+ * it: finite, with no safe-integer bound. Use it, not `Schema.Int`, wherever a
+ * catalog or a request encodes an integer.
+ */
+export const Integer = Schema.Finite.check(Schema.makeFilter((value) => Number.isInteger(value), {
+    expected: "an integer",
+    toJsonSchema: () => ({ type: "integer" }),
+}));
+/**
+ * A string's length as JSON Schema counts it: code points, with a lone
+ * surrogate counted as one. The same loop as api()'s validator.
+ */
+export function codePoints(value) {
+    let count = 0;
+    for (let index = 0; index < value.length; count++) {
+        const unit = value.charCodeAt(index++);
+        if (unit >= 0xd800 && unit <= 0xdbff && index < value.length && (value.charCodeAt(index) & 0xfc00) === 0xdc00) {
+            index++;
+        }
+    }
+    return count;
+}
+/** At least `minimum` code points, rendered `minLength` exactly. */
+export function isMinChars(minimum) {
+    return Schema.makeFilter((value) => codePoints(value) >= minimum, {
+        expected: `a string of at least ${minimum} characters`,
+        toJsonSchema: () => ({ minLength: minimum }),
+    });
+}
+/** At most `maximum` code points, rendered `maxLength` exactly. */
+export function isMaxChars(maximum) {
+    return Schema.makeFilter((value) => codePoints(value) <= maximum, {
+        expected: `a string of at most ${maximum} characters`,
+        toJsonSchema: () => ({ maxLength: maximum }),
+    });
+}
+const JSON_TYPES = {
+    String: "string",
+    Number: "number",
+    Boolean: "boolean",
+    Arrays: "array",
+    Objects: "object",
+};
+/**
+ * Refuse an input whose checks the catalog cannot state exactly: a check
+ * with no JSON Schema rendering, or one Effect marks approximate (a UTF-16
+ * string length, a RegExp whose flags differ). The validator api() runs on
+ * the catalog and the decoder would then disagree about some value.
+ */
+function exactChecks(ast, seen = new Set()) {
+    if (seen.has(ast))
+        return;
+    seen.add(ast);
+    // Transformations can change what the decoder accepts; the inline renderer
+    // has no reviewed exactness contract for them.
+    if (ast.encoding)
+        throw new Error("A kit input encoding has no exact catalog spelling.");
+    const type = JSON_TYPES[ast._tag];
+    const visit = (checks) => {
+        for (const check of checks) {
+            if (check._tag === "FilterGroup") {
+                visit(check.checks);
+                continue;
+            }
+            const render = check.annotations?.toJsonSchema;
+            const rendered = render?.({ type, schemas: [] });
+            if (rendered === undefined || Array.isArray(rendered)) {
+                throw new Error(`A kit input check (${String(check.annotations?.expected ?? "a filter")}) has no exact catalog spelling; ` +
+                    "use the kit's isMinChars/isMaxChars or Integer, or a check that renders exactly.");
+            }
+        }
+    };
+    if (ast.checks)
+        visit(ast.checks);
+    switch (ast._tag) {
+        case "Objects":
+            for (const property of ast.propertySignatures)
+                exactChecks(property.type, seen);
+            for (const index of ast.indexSignatures) {
+                exactChecks(index.parameter, seen);
+                exactChecks(index.type, seen);
+            }
+            return;
+        case "Arrays":
+            for (const element of [...ast.elements, ...ast.rest])
+                exactChecks(element, seen);
+            return;
+        case "Union":
+            for (const member of ast.types)
+                exactChecks(member, seen);
+            return;
+        case "Suspend":
+            exactChecks(ast.thunk(), seen);
+            return;
+        case "String":
+        case "Number":
+        case "Boolean":
+        case "Null":
+        case "Unknown":
+        case "Never":
+        case "Literal":
+            return;
+        default:
+            throw new Error(`A kit input AST form (${ast._tag}) has no exact catalog spelling.`);
+    }
+}
+/** Preserve an explicitly empty required list in a legacy output catalog. */
+export function emptyRequired(schema) {
+    return schema.annotate({ "connecta/emptyRequired": true });
+}
+function restoreRequired(node, ast) {
+    if (ast.annotations?.["connecta/emptyRequired"] === true) {
+        if (node["type"] !== "object" || (Array.isArray(node["required"]) && node["required"].length > 0))
+            throw new Error("emptyRequired requires an object with no required properties.");
+        node["required"] = [];
+    }
+    if (ast._tag === "Objects") {
+        const properties = node["properties"];
+        for (const property of ast.propertySignatures) {
+            const child = properties?.[String(property.name)];
+            if (child && typeof child === "object")
+                restoreRequired(child, property.type);
+        }
+    }
+    else if (ast._tag === "Arrays") {
+        const item = node["items"];
+        if (item && typeof item === "object" && ast.rest[0])
+            restoreRequired(item, ast.rest[0]);
+    }
+}
+/** Render a Schema as catalog JSON Schema. Throws on a schema that needs `$defs`, or an inexact input check. */
+export function catalogSchema(schema, mode) {
+    if (mode === "input")
+        exactChecks(schema.ast);
+    const document = Schema.toJsonSchemaDocument(schema, mode === "input" ? { onExcessProperty: "error" } : {});
+    if (Object.keys(document.definitions).length > 0) {
+        throw new Error("A catalog schema is rendered inline; remove the identifier that asked for a definition.");
+    }
+    restoreRequired(document.schema, schema.ast);
+    let root = normalize(document.schema);
+    if (mode === "input" &&
+        root["type"] === "object" &&
+        root["additionalProperties"] === false &&
+        !("properties" in root)) {
+        const { type, ...rest } = root;
+        root = { type, properties: {}, ...rest };
+    }
+    if (mode === "input" && root["type"] === "object" && !("required" in root)) {
+        return Object.fromEntries(Object.entries(root).flatMap(([key, value]) => key === "properties"
+            ? [
+                [key, value],
+                ["required", []],
+            ]
+            : [[key, value]]));
+    }
+    return root;
+}
+function normalize(value) {
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (!value || typeof value !== "object")
+        return value;
+    const node = value;
+    const out = {};
+    for (const [key, child] of Object.entries(node)) {
+        if (key === "additionalProperties" && child === true)
+            continue;
+        if (key === "properties") {
+            out[key] = Object.fromEntries(Object.entries(child).map(([name, schema]) => [name, normalize(schema)]));
+            continue;
+        }
+        if (key === "anyOf") {
+            const branches = child.map(normalize);
+            const merged = collapse(branches);
+            if (merged)
+                Object.assign(out, merged);
+            else
+                out[key] = branches;
+            continue;
+        }
+        out[key] = key === "items" || key === "additionalProperties" ? normalize(child) : child;
+    }
+    // A discrete integer constraint may render in one allOf member beside its integer type.
+    // Flatten disjoint keywords so enum/default/max remain one usable parameter contract.
+    const members = out["allOf"];
+    if (out["type"] === "integer" && Array.isArray(members) && members.length === 1) {
+        const part = members[0];
+        if (Array.isArray(part["enum"]) &&
+            Object.keys(part).every((key) => ["enum", "minimum", "maximum", "description", "default"].includes(key) &&
+                (!(key in out) || out[key] === part[key]))) {
+            delete out["allOf"];
+            Object.assign(out, part);
+        }
+    }
+    // Hand-written catalogs spell an array's own keywords before its `items`.
+    if ("items" in out) {
+        const { items, ...rest } = out;
+        return { ...rest, items };
+    }
+    return out;
+}
+/** One `type` array for disjoint branches whose constraints cannot collide, else undefined. */
+function collapse(branches) {
+    const types = [];
+    const merged = {};
+    for (const branch of branches) {
+        const type = branch["type"];
+        if (typeof type !== "string" || types.includes(type) || !OWN_KEYWORDS[type])
+            return undefined;
+        for (const [key, keyword] of Object.entries(branch)) {
+            if (key === "type")
+                continue;
+            if (!OWN_KEYWORDS[type].has(key) || key in merged)
+                return undefined;
+            merged[key] = keyword;
+        }
+        types.push(type);
+    }
+    // integer and number share keywords, so they never merge.
+    if (types.includes("integer") && types.includes("number"))
+        return undefined;
+    return { type: types, ...merged };
+}

package/dist/http/node-transport.js

@@ -0,0 +1,241 @@
+// Node-only: owned undici dispatcher and Node stream adapters, reached via /node.
+import { Readable } from "node:stream";
+import { isIP } from "node:net";
+import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
+import { Client, ProxyAgent } from "undici";
+import { ConnectorCallError } from "../errors.js";
+/** Pull-based bridge: Node 22's Readable.toWeb can enqueue after Web cancellation. */
+function responseBody(body, signal) {
+    const chunks = body[Symbol.asyncIterator]();
+    let closed = false;
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const chunk = await chunks.next();
+                if (closed)
+                    return;
+                if (chunk.done) {
+                    closed = true;
+                    controller.close();
+                }
+                else
+                    controller.enqueue(chunk.value);
+            }
+            catch (error) {
+                if (closed)
+                    return;
+                closed = true;
+                controller.error(signal.aborted ? signal.reason : error);
+            }
+        },
+        cancel() {
+            closed = true;
+            body.destroy();
+            // A pending next() can still settle: it checks closed before touching
+            // the canceled controller, and every iterator rejection is observed.
+            void chunks.return?.().catch(() => { });
+        },
+    });
+}
+/**
+ * One Client per send, no shared/global dispatcher or interceptor. request()
+ * avoids fetch's 421 retry; HTTP/1.1 and non-idempotent dispatch disable the
+ * HTTP/2 REFUSED_STREAM and pipeline recovery paths, for every method.
+ * The response/abort owns the client until the body ends or is cancelled.
+ */
+export function createNodeGuardedTransport(proxy) {
+    let proxyUri;
+    let proxyToken;
+    if (proxy !== undefined) {
+        try {
+            const url = new URL(proxy);
+            if (!["http:", "https:"].includes(url.protocol) || url.pathname !== "/" || url.search || url.hash)
+                throw new Error();
+            if (url.username || url.password) {
+                if (!url.username)
+                    throw new Error();
+                proxyToken = `Basic ${Buffer.from(`${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`).toString("base64")}`;
+            }
+            url.username = "";
+            url.password = "";
+            proxyUri = url.href;
+        }
+        catch {
+            // Configuration can contain passwords: never include the input or cause.
+            throw new Error("proxy must be an absolute HTTP(S) proxy URL with no path, query or fragment.");
+        }
+    }
+    return {
+        delaysDispatch: true,
+        async send(url, init, beforeDispatch = () => { }) {
+            const framed = new Request(url, init);
+            if (!framed.headers.has("user-agent"))
+                framed.headers.set("user-agent", "connecta");
+            let dispatched = false;
+            const dispatch = () => {
+                framed.signal.throwIfAborted();
+                if (dispatched)
+                    throw new Error("A transport send cannot open a second connection.");
+                beforeDispatch();
+                dispatched = true;
+            };
+            const clientOptions = { allowH2: false, pipelining: 0, interceptors: { Client: [] } };
+            let tunnelClient;
+            const client = proxyUri
+                ? new ProxyAgent({
+                    uri: proxyUri,
+                    ...(proxyToken ? { token: proxyToken } : {}),
+                    proxyTunnel: true,
+                    ...clientOptions,
+                    interceptors: { Agent: [], Client: [] },
+                    // Neither side of CONNECT uses a Pool, interceptor or global dispatcher.
+                    clientFactory: (origin, options) => {
+                        const connect = options.connect;
+                        return (tunnelClient = new Client(origin, {
+                            ...options,
+                            ...clientOptions,
+                            connect: (parameters, callback) => {
+                                const name = parameters.servername;
+                                // ProxyAgent 6 explicitly sets SNI to the proxy hostname.
+                                // Node 26 rejects IP SNI. Omit it for literal IPs; tls.connect
+                                // still checks the certificate against its connection host.
+                                connect({ ...parameters, ...(name && isIP(name.replace(/^\[|\]$/g, "")) ? { servername: "" } : {}) }, callback);
+                            },
+                        }));
+                    },
+                    factory: (origin, options) => {
+                        const connect = options.connect;
+                        return new Client(origin, {
+                            ...options,
+                            ...clientOptions,
+                            connect: (options, callback) => {
+                                let settled = false;
+                                connect(options, (error, socket) => {
+                                    // undici 6's refused HTTP CONNECT can invoke its callback twice.
+                                    if (settled)
+                                        return;
+                                    settled = true;
+                                    if (error || !socket) {
+                                        // A CONNECT reset is pre-send, never a recoverable
+                                        // UND_ERR_SOCKET that Client may silently reconnect.
+                                        callback(new Error("Outbound proxy tunnel failed."), null);
+                                        return;
+                                    }
+                                    try {
+                                        dispatch();
+                                    }
+                                    catch (error) {
+                                        socket.destroy();
+                                        callback(error, null);
+                                        return;
+                                    }
+                                    callback(null, socket);
+                                });
+                            },
+                        });
+                    },
+                })
+                : new Client(url.origin, clientOptions);
+            const destroy = () => Promise.allSettled([tunnelClient?.destroy(), client.destroy()]);
+            const abort = () => {
+                void destroy();
+            };
+            framed.signal.addEventListener("abort", abort, { once: true });
+            try {
+                framed.signal.throwIfAborted();
+                if (!proxyUri)
+                    dispatch();
+                const answer = await client.request({
+                    origin: url.origin,
+                    path: `${url.pathname}${url.search}`,
+                    method: framed.method,
+                    headers: Object.fromEntries(framed.headers),
+                    // Keep serialized SDK/provider bodies sized: undici computes their exact
+                    // UTF-8 Content-Length instead of using chunked transfer encoding.
+                    body: typeof init.body === "string"
+                        ? init.body
+                        : init.body instanceof URLSearchParams
+                            ? init.body.toString()
+                            : framed.body
+                                ? Readable.fromWeb(framed.body)
+                                : null,
+                    signal: framed.signal,
+                    idempotent: false,
+                    maxRedirections: 0,
+                });
+                const headers = new Headers();
+                for (const [name, values] of Object.entries(answer.headers)) {
+                    for (const value of Array.isArray(values) ? values : values === undefined ? [] : [values]) {
+                        headers.append(name, value);
+                    }
+                }
+                const raw = answer.body;
+                // Undici emits AbortError even for a deliberate destroy() with no
+                // consumer (HEAD or an unsupported encoding). Active Web/decode stream
+                // listeners still receive read failures; cleanup always has an observer.
+                raw.on("error", () => { });
+                const close = () => {
+                    framed.signal.removeEventListener("abort", abort);
+                    void destroy();
+                };
+                raw.once("close", close);
+                if (framed.method === "HEAD" || [204, 205, 304].includes(answer.statusCode)) {
+                    raw.destroy();
+                    return new Response(null, { status: answer.statusCode, headers });
+                }
+                let body = raw;
+                // Native fetch decodes content encodings before exposing response bytes.
+                // Bound the number of decoders; an unsupported chain fails closed.
+                const encodings = (headers.get("content-encoding") ?? "")
+                    .split(",")
+                    .map((value) => value.trim())
+                    .filter(Boolean);
+                const unreadable = () => {
+                    raw.destroy();
+                    // Preserve the physical status (notably a write's 401) even when
+                    // the content encoding cannot be read. A body failure is not a lost reply.
+                    return new Response(new ReadableStream({
+                        start(controller) {
+                            controller.error(new Error("Unsupported response content encoding."));
+                        },
+                    }), { status: answer.statusCode, headers });
+                };
+                if (encodings.length > 5)
+                    return unreadable();
+                for (const encoding of encodings.reverse()) {
+                    if (encoding === "identity")
+                        continue;
+                    const decode = encoding === "gzip" || encoding === "x-gzip"
+                        ? createGunzip()
+                        : encoding === "deflate"
+                            ? createInflate()
+                            : encoding === "br"
+                                ? createBrotliDecompress()
+                                : undefined;
+                    if (!decode)
+                        return unreadable();
+                    const previous = body;
+                    previous.once("error", (error) => decode.destroy(error));
+                    decode.once("close", () => previous.destroy());
+                    body = previous.pipe(decode);
+                }
+                return new Response(responseBody(body, framed.signal), { status: answer.statusCode, headers });
+            }
+            catch (error) {
+                // ProxyAgent destroys its destination Agent before its CONNECT Client.
+                // An unfinished CONNECT holds the former's connector open: cancel both
+                // together so a reset/abort cannot deadlock cleanup.
+                framed.signal.removeEventListener("abort", abort);
+                await destroy();
+                if (framed.signal.aborted)
+                    throw framed.signal.reason;
+                if (proxyUri)
+                    throw new ConnectorCallError("unavailable", dispatched
+                        ? "The proxied request did not return a confirmed response."
+                        : "The outbound proxy tunnel could not be established; the destination request was not sent.", { retryable: false });
+                throw error;
+            }
+        },
+    };
+}
+export const nodeGuardedTransport = createNodeGuardedTransport();

package/dist/http/oauth.js

@@ -0,0 +1,162 @@
+// Refresh-once middleware (decision 0010, B.2). Unreachable from src/index.ts.
+//
+// Refresh-once for a connection that authenticates with a token it can
+// renew: a downstream OAuth grant, a service-account assertion, a machine
+// login. A 401 earns one renewal. A read is then replayed once; a second 401
+// is the grant's own refusal. A write is never sent again (INV-9): the
+// renewal still runs, so the next deliberate call has a fresh token, and this
+// call answers with the write's own 401.
+//
+// This file decides nothing about that write. The transport recorded its
+// answer in the call's dispatch ledger when the resource server gave it, and
+// api()'s boundary delegates the verdict to the core's settleWrite. The
+// middleware records facts only, including a successful renewal. By default a failed
+// renewal is discarded; the static bridge can opt into the core's grant diagnostic.
+// Neither path can turn the write into a known refusal or advertise a retry; the
+// ledger notes only a renewal that succeeded, so the agent is not sent to
+// re-authorize a credential that already works. Even a wrapper here that
+// did resend would be stopped by the transport's one-dispatch guard.
+//
+// The core's positive-read classifier is authoritative: only a positively
+// classified GET/HEAD is replayable. Overrides force a write, and a reviewed
+// POST or an auxiliary label cannot bypass the physical-write reservation.
+//
+// The grant itself (storage, coordination across isolates, the token
+// request, the request-scope latch) stays in src/auth/.
+import { Cause, Context, Effect, Option } from "effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientResponse from "effect/http/HttpClientResponse";
+import { readRequest, renewedAfterUnauthorized } from "../provider-call.js";
+import { renewableGrantFor } from "../auth/renewable-grant.js";
+import { ConnectorCallError } from "../errors.js";
+import { responseRequest } from "./client.js";
+import { Refusal, RequestRefused } from "./errors.js";
+import { Dispatches, Signal, duringCall } from "./services.js";
+/** The calling owner's renewable token, as the operations a transport needs from it. */
+export class Grant extends Context.Service()("connecta/http/Grant") {
+}
+/** Bridge a production static OAuth facade without adding anything to its public interface. */
+export function grantFromOAuth(oauth) {
+    const grant = renewableGrantFor(oauth);
+    const use = (work) => Effect.tryPromise({
+        try: work,
+        catch: (error) => new Refusal({
+            error: error instanceof ConnectorCallError
+                ? error
+                : new ConnectorCallError("connector_call_failed", "The OAuth grant could not be used.", {
+                    retryable: false,
+                }),
+        }),
+    });
+    const missing = () => Promise.reject(new ConnectorCallError("connector_call_failed", "This OAuth facade has no renewable grant."));
+    return {
+        token: use(grant ? () => grant.token() : missing),
+        refresh: (stale) => use(grant ? () => grant.refresh(stale) : missing),
+        rejected: use(grant ? () => grant.rejected() : missing),
+    };
+}
+/** Headers for `GuardedOptions.authenticate`: the grant's bearer token. */
+export const bearer = Grant.use((grant) => Effect.map(grant.token, (token) => ({ Authorization: `Bearer ${token}` })));
+/** The bearer token a prepared request carried, as the grant issued it. */
+function sentToken(request) {
+    return (request.headers["authorization"] ?? "").replace(/^Bearer /, "");
+}
+/** Wrap a guarded client whose `authenticate` is {@link bearer}. */
+export function refreshOnce(guarded, options) {
+    if (options?.writeRenewal === "discard" && options.writeUnauthorized)
+        throw new Error("A write that is not renewed has no renewal facts to map.");
+    const inner = guarded.client;
+    const challengeFailure = (entry) => Effect.gen(function* () {
+        const error = new ConnectorCallError("connector_call_failed", "The OAuth challenge exceeded its response ceiling.", { retryable: false });
+        const refusal = new Refusal({
+            error: !readRequest(entry ?? {}) && options?.writeUnauthorized
+                ? options.writeUnauthorized({ _tag: "Failed", failure: error })
+                : error,
+        });
+        const dispatch = entry ? (yield* Dispatches).find((item) => item.request === entry) : undefined;
+        if (dispatch)
+            dispatch.failure = refusal;
+        return yield* Effect.fail(refusal);
+    });
+    const execute = (request) => Effect.gen(function* () {
+        const response = yield* inner.execute(request).pipe(Effect.catchTag("ResponseTooLarge", (failure) => {
+            const entry = responseRequest(failure);
+            return options?.challengeMaxBytes !== undefined && entry?.status === 401
+                ? challengeFailure(entry)
+                : Effect.fail(failure);
+        }));
+        if (response.status !== 401)
+            return response;
+        // Read under the ceiling now, so nothing is left open while renewing.
+        const reply = yield* guarded
+            .read(response, options?.challengeMaxBytes)
+            .pipe(Effect.catchTag("ResponseTooLarge", (failure) => options?.challengeMaxBytes !== undefined
+            ? challengeFailure(responseRequest(response))
+            : Effect.fail(failure)));
+        const grant = yield* Grant;
+        const stale = sentToken(response.request);
+        const entry = responseRequest(response);
+        if (!readRequest(entry ?? {}) && options?.writeRenewal === "discard") {
+            // No renewal: the next deliberate call obtains a fresh token. The
+            // write's own 401 is answered; nothing is marked renewed (Q8).
+            if (grant.discard)
+                yield* grant.discard(stale);
+            return HttpClientResponse.fromWeb(request, new Response(reply.text ?? "", { status: reply.status, headers: reply.headers }));
+        }
+        if (!readRequest(entry ?? {})) {
+            // Whatever renewal meets is the authorization server's, not the
+            // write's. The ledger keeps only whether it succeeded, which decides
+            // whether the agent still needs the handoff, never the outcome.
+            const renewal = yield* Effect.exit(grant.refresh(stale));
+            // Recorded on this request's own ledger entry, and only for a token
+            // other than the one it sent; the core decides from it (Q8).
+            if (renewal._tag === "Success" && !(yield* Signal)?.aborted)
+                renewedAfterUnauthorized(entry, stale, renewal.value);
+            if (options?.writeUnauthorized) {
+                const cause = renewal._tag === "Failure" ? Cause.findErrorOption(renewal.cause) : Option.none();
+                const failure = Option.isSome(cause) ? cause.value : undefined;
+                const facts = renewal._tag === "Success"
+                    ? { _tag: renewal.value === stale ? "Unchanged" : "Renewed" }
+                    : {
+                        _tag: "Failed",
+                        failure: failure?._tag === "Refusal"
+                            ? failure.error
+                            : (failure ?? new Error("OAuth renewal did not complete.")),
+                    };
+                // This is still the resource request's own 401. The common failure
+                // mapper attaches its provenance; settleWrite decides the outcome.
+                return yield* Effect.fail(new Refusal({ error: options.writeUnauthorized(facts) }));
+            }
+            return HttpClientResponse.fromWeb(request, new Response(reply.text ?? "", { status: reply.status, headers: reply.headers }));
+        }
+        const fresh = yield* grant.refresh(stale);
+        if ((yield* Signal)?.aborted)
+            return yield* Effect.fail(new RequestRefused({ message: "This call has ended; no renewal work may continue." }));
+        renewedAfterUnauthorized(entry, stale, fresh);
+        // `authenticate` runs again on the replay and reads the renewed token.
+        const replay = yield* inner
+            .execute(request)
+            .pipe(Effect.catchTag("ResponseTooLarge", (failure) => options?.challengeMaxBytes !== undefined && responseRequest(failure)?.status === 401
+            ? grant.rejected
+            : Effect.fail(failure)));
+        if (replay.status !== 401)
+            return replay;
+        if (options?.replayRejection === "answer") {
+            // The connection reads and redacts this answer like any other.
+            if (grant.discard)
+                yield* grant.discard(sentToken(replay.request));
+            return replay;
+        }
+        yield* Effect.ignore(guarded.read(replay));
+        return yield* grant.rejected;
+    }).pipe(duringCall, Effect.catchTag("RequestRefused", (failure) => Signal.use((signal) => Effect.fail(signal?.aborted
+        ? new Refusal({
+            error: new ConnectorCallError("connector_call_failed", "This call has ended; no renewal work may continue."),
+        })
+        : failure))));
+    return {
+        provider: guarded.provider,
+        client: HttpClient.makeWith((request) => Effect.flatMap(request, execute), (request) => Effect.succeed(request)),
+        read: guarded.read,
+    };
+}