@zackbart/connecta 0.34.1 → 0.36.0

package/dist/http/errors.js

@@ -0,0 +1,558 @@
+// Internal HTTP failure contract (decision 0010, B.3). Unreachable from src/index.ts.
+//
+// Every way a kit request can fail, as a tagged error, and the one mapping
+// from those to the wire `ConnectorCallError`. A provider supplies meaning
+// only where meaning differs by vendor: what 401, 403, and 404 say (required,
+// because the same 403 is an ungranted capability at one vendor and a token
+// scope at another), which machine-readable facts its error bodies and
+// headers carry, rules that cut across statuses, and its wording.
+//
+// Classification and wording are two steps. A vendor's `facts` reads a copy
+// of the error body that keeps only tokens, finite numbers, and booleans.
+// Declared public fact values and parsed numeric sources are captured before sent-secret redaction;
+// wording reads a separate extraction from the redacted body. The vendor's
+// rules read those facts and the reviewed `headers` allowlist, nothing
+// else, and return a `Verdict`: a code and retry advice. Only after that does
+// the kit build the vendor's detail line, and the verdict's `words` render
+// the message from it. A rule's input has no prose to read, and when a rule
+// runs, this failure's prose does not exist yet.
+//
+// This file decides no write's outcome. The core does (src/write-outcome.ts):
+// the transport records every request in the core ledger as it leaves, and
+// `api()`'s boundary hands the call's failure to `providerCallFailure`, which
+// reads that ledger over the whole logical call (INV-9). What the kit adds is
+// provenance, recorded where it was observed: a failure that is its own
+// request's served answer is marked as that request's (`vendorRefusal`), so a
+// refusing status counts only for the request that received it. Advice to
+// send a call again is a segment of its own (`resendAdvice`), never part of
+// the message, so output composes it only where the outcome allows.
+// Q8 policy is decided once by the core's `settleWrite` (#917), from the
+// ledger entries this kit forwards its matched proof and renewals to. A
+// write answered 401 stays unknown; only renewal removes its handoff, and
+// only a reviewed authentication-before-execution declaration proves refusal.
+import { Data } from "effect";
+import { ConnectorCallError, isConnectorCallErrorCode, resendAdvice, unavailableCallError, } from "../errors.js";
+import { attachFailureFacts } from "../operator-record.js";
+import { vendorRefusal } from "../provider-call.js";
+import { providerFailureMessage } from "../write-outcome.js";
+/** A request the kit refused before sending: confinement, a shadowed credential header. */
+export class RequestRefused extends Data.TaggedError("RequestRefused") {
+}
+/** `fetch` rejected. `failure` is read for its errno only and never surfaces. */
+export class TransportFailure extends Data.TaggedError("TransportFailure") {
+}
+/** The vendor answered with a redirect; the credential is never forwarded. */
+export class RedirectRefused extends Data.TaggedError("RedirectRefused") {
+}
+/** The body crossed the connector's byte ceiling, declared or streamed. */
+export class ResponseTooLarge extends Data.TaggedError("ResponseTooLarge") {
+}
+/**
+ * A logical write was about to be handed to `fetch` a second time in one
+ * call, by any path (an Effect retry, a redirect follower, a renewal that
+ * replays, a reconnect, a retry under a new request id). Raised below all of
+ * them, before anything leaves; `first` is the permanent reservation, which may still be preparing.
+ */
+export class ResendRefused extends Data.TaggedError("ResendRefused") {
+}
+/** A non-2xx answer (or an in-band refusal mapped as one), with the body parsed when it was JSON. */
+export class StatusFailure extends Data.TaggedError("StatusFailure") {
+}
+/** A successful status whose body is not JSON. Its text never surfaces. */
+export class UnreadableBody extends Data.TaggedError("UnreadableBody") {
+    constructor(options = {}) {
+        super(options);
+    }
+}
+/** The vendor's own typed verdict: an in-band refusal, a missing credential. */
+export class Refusal extends Data.TaggedError("Refusal") {
+}
+// One completeness-checked vocabulary for the typed client boundary.
+const TAGS = {
+    RequestRefused: true,
+    TransportFailure: true,
+    RedirectRefused: true,
+    ResponseTooLarge: true,
+    ResendRefused: true,
+    StatusFailure: true,
+    UnreadableBody: true,
+    Refusal: true,
+};
+export function isHttpFailure(error) {
+    if (typeof error !== "object" || error === null || !("_tag" in error))
+        return false;
+    return typeof error._tag === "string" && Object.hasOwn(TAGS, error._tag);
+}
+/** Refuse empty evidence at connection construction (INV-11); prose is never proof by itself. */
+export function validateVendorErrors(vendor) {
+    errorMeanings(vendor);
+    captureErrorReviews(vendor);
+    const proof = vendor.authBeforeExecution;
+    if (proof && (typeof proof.evidence !== "string" || !proof.evidence.trim() || typeof proof.matches !== "function")) {
+        throw new Error("An authBeforeExecution declaration requires nonempty evidence and a narrow raw-fact predicate.");
+    }
+}
+// No 409 default: only a vendor that documents its meaning may name a conflict.
+// The core decides refusal from the served answer's provenance, never this code.
+const DEFAULTS = {
+    400: () => ({ code: "invalid_args" }),
+    422: () => ({ code: "invalid_args" }),
+    429: ({ retryAfterMs: wait }) => ({ code: "rate_limited", retryAfterMs: wait }),
+};
+const serverErrorDefault = ({ retryAfterMs: wait }) => ({ code: "unavailable", retryAfterMs: wait });
+const otherwiseDefault = () => ({ code: "connector_call_failed", retryable: false });
+const TOKEN = /^[A-Za-z0-9_.:[\]-]{1,128}$/;
+/** How many entries of a list the detail line sees. Classification sees them all. */
+const DISPLAYED = 8;
+const MAX_HEADER = 128;
+const MAX_DEPTH = 32;
+const MAX_WAIT_MS = 86_400_000;
+const errorReviews = new WeakMap();
+/** Metadata snapshots contain no request data, promises or services. */
+function captureErrorReviews(vendor) {
+    const previous = errorReviews.get(vendor);
+    if (previous)
+        return previous;
+    const presence = {};
+    for (const [name, review] of Object.entries(vendor.presence ?? {})) {
+        if (!TOKEN.test(name) ||
+            !Array.isArray(review.path) ||
+            review.path.length === 0 ||
+            review.path.length > MAX_DEPTH ||
+            review.path.some((part) => typeof part !== "string" || !part) ||
+            !["string", "text"].includes(review.content))
+            throw new Error("Error presence reviews need a name, a bounded property path and string or text content.");
+        presence[name] = Object.freeze({ path: Object.freeze([...review.path]), content: review.content });
+    }
+    const display = {};
+    for (const [name, review] of Object.entries(vendor.displayFacts ?? {})) {
+        if (!TOKEN.test(name) || !Number.isSafeInteger(review.maxItems) || review.maxItems < 1 || !review.review.trim())
+            throw new Error("Displayed error facts need a positive whole maxItems and a nonempty review.");
+        display[name] = review.maxItems;
+    }
+    const numbers = {};
+    for (const [name, review] of Object.entries(vendor.numericFacts ?? {})) {
+        const path = review.path;
+        const header = review.header;
+        if (!TOKEN.test(name) ||
+            (header === undefined
+                ? !Array.isArray(path) ||
+                    path.length === 0 ||
+                    path.length > MAX_DEPTH ||
+                    path.some((part) => typeof part !== "string" || !part)
+                : path !== undefined ||
+                    typeof header !== "string" ||
+                    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(header) ||
+                    header.length > MAX_HEADER) ||
+            (review.format !== undefined &&
+                !["integer", "seconds", "epoch-seconds", "retry-after"].includes(review.format)) ||
+            (name === "retryAfterMs" && (review.format === undefined || review.format === "integer")) ||
+            typeof review.review !== "string" ||
+            !review.review.trim())
+            throw new Error("Numeric error facts need a name, an exact path or lowercase header, a numeric format and a nonempty review.");
+        numbers[name] = Object.freeze({
+            ...(header === undefined ? { path: Object.freeze([...path]) } : { header }),
+            format: review.format ?? "integer",
+            review: review.review,
+        });
+    }
+    const captured = {
+        ...(vendor.bodyFailures
+            ? {
+                bodyFailures: (() => {
+                    const review = vendor.bodyFailures;
+                    if (!review.review?.trim() ||
+                        !review.readFailed?.trim() ||
+                        !Array.isArray(review.statusOnly) ||
+                        review.statusOnly.some((status) => !Number.isInteger(status) || status < 400 || status > 599 || status === 401))
+                        throw new Error("Body-failure handling needs a review, fixed wording and reviewed error statuses other than 401.");
+                    return Object.freeze({ ...review, statusOnly: Object.freeze([...review.statusOnly]) });
+                })(),
+            }
+            : {}),
+        presence: Object.freeze(presence),
+        display: Object.freeze(display),
+        numbers: Object.freeze(numbers),
+        vocabulary: Object.freeze(Object.fromEntries(Object.entries(vendor.factVocabulary ?? {}).map(([name, values]) => {
+            if (!TOKEN.test(name) || !Array.isArray(values) || values.some((value) => boundedFact(value) === undefined))
+                throw new Error("Error fact vocabularies need token names and finite public token, number or boolean values.");
+            return [name, new Set(values)];
+        }))),
+    };
+    errorReviews.set(vendor, captured);
+    return captured;
+}
+/**
+ * The body as a vendor's `facts` may read it: tokens, finite numbers,
+ * booleans, and null, under keys that are tokens. Prose, URLs, and anything
+ * deeper than 32 levels are gone before any vendor code runs.
+ */
+function tokensOf(value, depth = 0) {
+    if (typeof value === "string")
+        return TOKEN.test(value) ? value : undefined;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === "boolean" || value === null)
+        return value;
+    if (typeof value !== "object" || depth >= MAX_DEPTH)
+        return undefined;
+    if (Array.isArray(value))
+        return value.map((entry) => tokensOf(entry, depth + 1));
+    return Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => (TOKEN.test(key) ? [[key, tokensOf(entry, depth + 1)]] : [])));
+}
+function boundedFact(value) {
+    if (typeof value === "string")
+        return TOKEN.test(value) ? value : undefined;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    return typeof value === "boolean" ? value : undefined;
+}
+/** Keep tokens, finite numbers, and booleans, in complete lists; anything else is dropped. */
+function bounded(facts) {
+    return Object.fromEntries(Object.entries(facts)
+        .filter(([name]) => TOKEN.test(name))
+        .map(([name, value]) => [
+        name,
+        Array.isArray(value)
+            ? value.map(boundedFact).filter((fact) => fact !== undefined)
+            : boundedFact(value),
+    ]));
+}
+const classifierFacts = new WeakMap();
+function vocabularyFacts(facts, vendor) {
+    return Object.fromEntries(Object.entries(captureErrorReviews(vendor).vocabulary).map(([name, values]) => {
+        const value = facts[name];
+        return [
+            name,
+            Array.isArray(value)
+                ? Object.freeze(value.filter((entry) => values.has(entry)))
+                : value !== undefined && values.has(value)
+                    ? value
+                    : undefined,
+        ];
+    }));
+}
+/** Read only declared public facts before redaction; never retain the original body or an unreviewed value. */
+export function captureClassifierFacts(body, vendor, headers = new Headers()) {
+    const review = captureErrorReviews(vendor);
+    const vocabulary = Object.keys(review.vocabulary).length > 0;
+    if (!vocabulary && !Object.keys(review.numbers).length)
+        return undefined;
+    return {
+        vendor,
+        facts: vocabulary ? vocabularyFacts(bounded(vendor.facts(tokensOf(body))), vendor) : {},
+        numbers: numericFacts(body, headers, review.numbers),
+    };
+}
+/** Reject coercions and unbounded text; only parsed integers or bounded wait windows leave this function. */
+function numericValue(value, format) {
+    if (typeof value === "string") {
+        if (value.length > MAX_HEADER)
+            return undefined;
+        const raw = value.trim();
+        if (format === "retry-after" && /^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(raw)) {
+            const date = Date.parse(raw);
+            return Number.isFinite(date) ? Math.min(MAX_WAIT_MS, Math.max(0, date - Date.now())) : undefined;
+        }
+        if (!/^\d+$/.test(raw))
+            return undefined;
+        value = Number(raw);
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0)
+        return undefined;
+    const integer = Math.min(Number.MAX_SAFE_INTEGER, value);
+    if (format === "integer")
+        return integer;
+    const milliseconds = integer * 1000 - (format === "epoch-seconds" ? Date.now() : 0);
+    return Math.min(MAX_WAIT_MS, Math.max(0, milliseconds));
+}
+function numericFacts(body, headers, reviews) {
+    return Object.freeze(Object.fromEntries(Object.entries(reviews).map(([name, review]) => {
+        let value = review.header === undefined ? body : headers.get(review.header);
+        for (const part of review.path ?? [])
+            value =
+                value !== null && typeof value === "object" && Object.hasOwn(value, part)
+                    ? value[part]
+                    : undefined;
+        return [name, numericValue(value, review.format ?? "integer")];
+    })));
+}
+/** Keep classification facts off the failure's enumerable data and its redacted detail body. */
+export function withClassifierFacts(failure, captured) {
+    if (captured)
+        classifierFacts.set(failure, captured);
+    return failure;
+}
+/** The detail line gets eight list entries by default; reviewed recovery fields retain their fixed bound. */
+function displayed(facts, vendor) {
+    const { display } = captureErrorReviews(vendor);
+    return Object.fromEntries(Object.entries(facts).map(([name, value]) => [
+        name,
+        Array.isArray(value) ? value.slice(0, display[name] ?? DISPLAYED) : value,
+    ]));
+}
+function visibleHeaders(headers, allowed) {
+    const out = Object.create(null);
+    for (const name of allowed ?? []) {
+        const value = headers.get(name);
+        if (value !== null && value.length <= MAX_HEADER && !hasControl(value))
+            out[name.toLowerCase()] = value;
+    }
+    return out;
+}
+function hasControl(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/** Shed a defect's text and typed identity when any request withholds vendor text. */
+export function withheldDefect(defect, options, 
+// Custom probe programs may send outside this ledger, so always withhold their defects.
+always = false) {
+    try {
+        if (!always && !options.dispatches.some(({ operation }) => operation && options.withholds(operation)))
+            return defect;
+    }
+    catch {
+        // A broken visibility hook cannot authorize exposing a defect's text.
+    }
+    return new Error("A provider hook withholding vendor text failed.");
+}
+/**
+ * The single mapping from a kit failure to what an agent reads. It decides
+ * no write: the core does, from its ledger (`providerCallFailure` at the
+ * `api()` boundary, and Q8's `settleWrite` once per logical call). A failure
+ * that is its own request's served answer carries that request as its
+ * provenance (`vendorRefusal`, which holds only for a refusing status: a 4xx
+ * other than 408). A write call records each 401 its requests met
+ * ({@link recordUnauthorized}) and words a blocked resend.
+ */
+export function toConnectorCallError(failure, vendor, options) {
+    if (options.classification === "write")
+        recordUnauthorized(vendor, options);
+    // A served read can still issue a physical write (POST or a method override).
+    // A blocked resend always reports that reservation's original attempt.
+    return failure._tag === "ResendRefused"
+        ? resent(failure.first, vendor, options)
+        : answered(failure, verdict(failure, vendor, options), options.dispatches);
+}
+/**
+ * Provenance (b), recorded where it was observed: `error` is its own
+ * request's answer, so it carries that request's core ledger entry. The core
+ * counts a refusal only for a refusing status on that entry, and only when it
+ * is the one request the whole logical call sent.
+ */
+function answered(failure, error, dispatches) {
+    const own = dispatches.find((dispatch) => dispatch.failure === failure);
+    return own?.request ? vendorRefusal(error, own.request) : error;
+}
+const RESEND = "A second attempt to send it was stopped before it left: connecta sends a write once.";
+/**
+ * The transport stopped a second dispatch of a write. The call reports what
+ * the first attempt was answered, with that attempt's provenance, so the
+ * core keeps a sole served refusal known and anything else that left unknown.
+ * A first attempt that never left reports its own failure.
+ */
+function resent(first, vendor, options) {
+    const own = first.failure ?? (first.state === "answered" && !ok(first.status) ? answerOf(first) : undefined);
+    if (own === undefined) {
+        return new ConnectorCallError("connector_call_failed", !first.write || first.request?.auxiliary
+            ? `The ${JSON.stringify(first.step ?? "write")} write step's slot is already taken. ` +
+                `Declare a separate writeSteps entry for each request the tool must send. ${RESEND}`
+            : `This call had already sent its write to ${vendor.provider}` +
+                `${first.state === "answered" ? `, which answered HTTP ${first.status}` : ""}. ${RESEND}`, { retryable: false });
+    }
+    const error = verdict(own, vendor, options, first);
+    const marked = first.request ? vendorRefusal(error, first.request) : error;
+    return providerFailureMessage(marked, `${marked.message} ${RESEND}`);
+}
+/**
+ * Record, on the core ledger entry of each write request answered 401, the
+ * facts Q8 is decided from (`settleWrite`): that answer's own vendor verdict
+ * (`vendorRefusal`, from its recorded answer even when no body was read), and
+ * whether the vendor's reviewed `authBeforeExecution` evidence covers it
+ * (`ProviderRequest.authBeforeExecution`). It decides nothing: a write's
+ * outcome, its code and its handoff are the core's.
+ */
+export function recordUnauthorized(vendor, options) {
+    const proof = vendor.authBeforeExecution;
+    for (const dispatch of options.dispatches) {
+        if (!dispatch.write || dispatch.state !== "answered" || dispatch.status !== 401 || !dispatch.request)
+            continue;
+        const recorded = recordedAnswer(dispatch);
+        if (proof !== undefined &&
+            proof.evidence.trim().length > 0 &&
+            proof.matches(classificationInput(recorded, vendor, options.withholds?.(recorded.operation) === true)))
+            dispatch.request.authBeforeExecution = true;
+        vendorRefusal(verdict(recorded, vendor, options), dispatch.request);
+    }
+}
+/** Use a parsed body only when it belongs to this recorded status; ceilings and later failures cannot supply its code. */
+function recordedAnswer(dispatch) {
+    return dispatch.failure?._tag === "StatusFailure" && dispatch.failure.status === dispatch.status
+        ? dispatch.failure
+        : answerOf(dispatch);
+}
+/** A recorded answer as the failure it was, from the facts the ledger kept (its body is gone). */
+function answerOf(dispatch) {
+    return new StatusFailure({
+        status: dispatch.status ?? 0,
+        headers: dispatch.headers ?? new Headers(),
+        body: undefined,
+        operation: dispatch.operation ?? { method: "", template: "" },
+    });
+}
+function ok(status) {
+    return status !== undefined && status >= 200 && status <= 299;
+}
+function verdict(failure, vendor, options, dispatch = options.dispatches.find((entry) => entry.failure === failure)) {
+    switch (failure._tag) {
+        case "Refusal":
+            return failure.error;
+        case "RequestRefused":
+            return new ConnectorCallError("invalid_args", failure.message);
+        case "TransportFailure":
+            return unavailableCallError(failure.failure, failure.host, `Could not reach the ${vendor.provider} API.`, options.signal);
+        case "RedirectRefused":
+            return new ConnectorCallError("connector_call_failed", `${vendor.provider} answered HTTP ${failure.status} with a redirect; this connector talks to exactly one origin and never forwards its credential to another.`, { retryable: false });
+        case "ResponseTooLarge": {
+            if (dispatch?.status !== undefined &&
+                captureErrorReviews(vendor).bodyFailures?.statusOnly.includes(dispatch.status)) {
+                // The ceiling discarded the body, not the answered status. Only opted-in
+                // statuses use the vendor's status-only rules; 401/Q8 stays unchanged.
+                const mapped = statusVerdict(new StatusFailure({
+                    status: dispatch.status,
+                    headers: new Headers(),
+                    body: undefined,
+                    unreadable: true,
+                    operation: dispatch.operation ?? { method: "", template: "" },
+                }), vendor, options.withholds?.(dispatch.operation ?? { method: "", template: "" }) === true, !dispatch.write);
+                return providerFailureMessage(mapped, failure.detail);
+            }
+            const uncertainWrite = options.classification === "write" &&
+                dispatch?.request?.auxiliary !== true &&
+                dispatch?.status !== undefined &&
+                Number.isInteger(dispatch.status) &&
+                ok(dispatch.status);
+            return attachFailureFacts(new ConnectorCallError("connector_call_failed", uncertainWrite
+                ? `${failure.detail} Whether the write took effect is unknown; check the target before repeating it.`
+                : failure.detail, { retryable: false }), dispatch?.status === undefined ? {} : { httpStatus: dispatch.status });
+        }
+        case "ResendRefused":
+            return new ConnectorCallError("connector_call_failed", `This call already sent a write to ${vendor.provider}; a second attempt was stopped before it left.`, { retryable: false });
+        case "UnreadableBody": {
+            const unreadable = failure.readFailed
+                ? (captureErrorReviews(vendor).bodyFailures?.readFailed ?? vendor.unreadable)
+                : failure.unexpectedText
+                    ? `${vendor.provider} returned unexpected text/HTML for a JSON response.`
+                    : vendor.unreadable;
+            return new ConnectorCallError("connector_call_failed", options.classification === "write" && dispatch?.request?.auxiliary !== true
+                ? (!failure.unexpectedText && vendor.unreadableWrite) ||
+                    `${unreadable} Whether the write took effect is unknown; check the target before repeating it.`
+                : unreadable, { retryable: false });
+        }
+        case "StatusFailure":
+            return statusVerdict(failure, vendor, options.withholds?.(failure.operation) === true, options.dispatches.some((dispatch) => dispatch.failure === failure && !dispatch.write));
+    }
+}
+function statusVerdict(failure, vendor, withheld, read) {
+    const input = classificationInput(failure, vendor, withheld);
+    const { headers, presence } = input;
+    // Classification first, over facts and headers only.
+    const decided = classified(input, vendor);
+    // The transport already applied the core's positive-read method/header rule.
+    // A 421 advises an explicit retry only for that request; no resend happens here.
+    const { code, retryable, retryAfterMs: wait, current, words, advice, } = failure.status === 421 && read ? { ...decided, code: "unavailable", retryable: true } : decided;
+    // Then the wording. The body reaches `detail` only when this operation's
+    // value-safety review lets its vendor text through.
+    const detail = vendor.detail({
+        status: failure.status,
+        facts: displayed(bounded(vendor.facts(tokensOf(failure.body))), vendor),
+        presence,
+        numbers: numericFacts(failure.body, failure.headers, captureErrorReviews(vendor).numbers),
+        headers,
+        withheld,
+        ...(withheld ? {} : { body: failure.body }),
+    });
+    const error = new ConnectorCallError(code, words ? words(detail) : detail, {
+        ...(retryable === undefined ? {} : { retryable }),
+        ...(wait === undefined ? {} : { retryAfterMs: wait }),
+        ...(current ? { current } : {}),
+    });
+    attachFailureFacts(error, { httpStatus: failure.status });
+    return advice === undefined ? error : resendAdvice(error, advice);
+}
+/** Only membership and whitespace are examined; no text is copied into classification. */
+function structuralPresence(body, reviews) {
+    return Object.fromEntries(Object.entries(reviews ?? {}).map(([name, review]) => {
+        let value = body;
+        for (const part of review.path) {
+            value =
+                value !== null && typeof value === "object" && Object.hasOwn(value, part)
+                    ? value[part]
+                    : undefined;
+        }
+        const strings = typeof value === "string"
+            ? [value]
+            : review.content === "text" && Array.isArray(value)
+                ? value.filter((entry) => typeof entry === "string")
+                : [];
+        return [
+            name,
+            { present: strings.some((text) => text.length > 0), nonBlank: strings.some((text) => text.trim().length > 0) },
+        ];
+    }));
+}
+function classificationInput(failure, vendor, withheld) {
+    const redacted = bounded(vendor.facts(tokensOf(failure.body)));
+    const captured = classifierFacts.get(failure);
+    const numbers = captured?.vendor === vendor
+        ? captured.numbers
+        : numericFacts(failure.body, failure.headers, captureErrorReviews(vendor).numbers);
+    return {
+        status: failure.status,
+        facts: { ...redacted, ...(captured?.vendor === vendor ? captured.facts : vocabularyFacts(redacted, vendor)) },
+        presence: structuralPresence(failure.body, captureErrorReviews(vendor).presence),
+        numbers,
+        headers: visibleHeaders(failure.headers, vendor.headers),
+        retryAfterMs: numbers["retryAfterMs"],
+        operation: failure.operation,
+        withheld,
+    };
+}
+/**
+ * A frozen copy of a vendor's declared meanings, refused when inconsistent
+ * (INV-11): `not_found` exactly when the vendor tells absence from a
+ * permission gap, and each conflict source a one-line documented fact.
+ */
+export function errorMeanings(vendor) {
+    const declared = vendor.meanings;
+    if (declared === undefined)
+        return undefined;
+    const { unknownId, provesAbsence, conflicts } = declared;
+    if (!isConnectorCallErrorCode(unknownId) ||
+        typeof provesAbsence !== "boolean" ||
+        (unknownId === "not_found") !== provesAbsence ||
+        !Array.isArray(conflicts) ||
+        conflicts.some((fact) => typeof fact !== "string" || !fact.trim() || /[\r\n]/.test(fact))) {
+        throw new Error(`${vendor.provider} error meanings need unknownId "not_found" exactly when provesAbsence is true, and one-line conflict facts.`);
+    }
+    return Object.freeze({ unknownId, provesAbsence, conflicts: Object.freeze([...conflicts]) });
+}
+function classified(input, vendor) {
+    for (const rule of vendor.classify ?? []) {
+        const decided = rule(input);
+        if (decided)
+            return decided;
+    }
+    const table = vendor.statuses;
+    const rule = table[input.status] ??
+        (input.status >= 500 && input.status <= 599 ? (table.serverError ?? serverErrorDefault) : undefined) ??
+        DEFAULTS[input.status] ??
+        table.otherwise ??
+        otherwiseDefault;
+    return rule(input);
+}

package/dist/http/fields.js

@@ -0,0 +1,49 @@
+// Internal provider kit (decision 0011 S5). Unreachable from src/index.ts.
+//
+// `fields` narrows a result to the dot paths an agent names. It runs on the
+// result a tool already built (after value safety, the privacy projection and
+// any named projection), so it can only remove. A list narrows each item.
+import { Schema } from "effect";
+import { ConnectorCallError } from "../errors.js";
+import { isMaxChars, isMinChars } from "./json-schema.js";
+const MAX_FIELDS = 50;
+/** The `fields` argument: at most 50 dot paths of 1 to 200 characters. */
+export function fieldsInput(description) {
+    return Schema.Array(Schema.String.check(isMinChars(1), isMaxChars(200)))
+        .check(Schema.isMaxLength(MAX_FIELDS))
+        .annotate({ description });
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * The refusal for a path whose first segment is not a property the result can
+ * carry, if any. Named tools pass their output Schema's property names and
+ * the hatch its operation's declared response roots, so a bad path fails
+ * before anything is sent.
+ */
+export function fieldsProblem(fields, names, of) {
+    const bad = fields?.find((field) => !names.has(field.replace(/\[\](?=\.|$)/g, "").split(".")[0]));
+    if (bad === undefined)
+        return undefined;
+    const choices = names.size > 0 && names.size <= 40 ? `: one of ${[...names].join(", ")}` : "";
+    return new ConnectorCallError("invalid_args", `fields path ${bad} does not begin with a property of ${of}${choices}.`);
+}
+/** Keep only the named dot paths; arrays are narrowed item by item. */
+export function selectFields(data, fields) {
+    if (!fields?.length)
+        return data;
+    const pick = (value, paths) => {
+        if (Array.isArray(value))
+            return value.map((item) => pick(item, paths));
+        if (!record(value))
+            return value;
+        const children = new Map();
+        for (const path of paths) {
+            const [key, ...tail] = path.replace(/\[\](?=\.|$)/g, "").split(".");
+            children.set(key, [...(children.get(key) ?? []), tail.join(".")]);
+        }
+        return Object.fromEntries([...children].flatMap(([key, tails]) => Object.hasOwn(value, key) ? [[key, tails.includes("") ? value[key] : pick(value[key], tails)]] : []));
+    };
+    return pick(data, fields);
+}