@zackbart/connecta 0.34.0 → 0.35.0

package/dist/http/vendor.js

@@ -0,0 +1,448 @@
+// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+//
+// A vendor is an `HttpApi`: endpoints with Schemas for path params, query,
+// and payload, from which requests are encoded and the endpoint manifest is
+// derived. This is the only kit module that imports effect/http-api, which
+// 4.0.5 annotates unstable; providers declare operations through the names
+// re-exported here, so an upstream change is absorbed in this file.
+// Re-exporting confines those modules; it does not make them stable.
+//
+// The typed client runs in `response-only` mode, and `Send` hands providers an
+// `Answer`, never a response. HttpApiClient's own decoding would read the
+// whole body without a ceiling, quote the body in a SchemaError, and fail an
+// empty 200. Every answer, from a declared operation or a hatch's path, takes
+// one route: bounded read, JSON, closed public classifier facts captured,
+// the request's sent secrets redacted from
+// every value of the whole body before anything can cut or extract from it
+// (#911), its keys kept for value safety to match by name, status (with
+// its operation, so value safety decides what a failure may quote), the
+// vendor's `result` hook, then the connection's ResultSafety. A provider
+// cannot reach a body earlier. A Content-Type redaction altered selects the
+// format the vendor reads as JSON, so no altered type routes a body around
+// ResultSafety as text or bytes (#703).
+import { Context, Effect } from "effect";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as HttpApi from "effect/http-api/HttpApi";
+import * as HttpApiClient from "effect/http-api/HttpApiClient";
+import * as HttpApiEndpoint from "effect/http-api/HttpApiEndpoint";
+import * as HttpApiGroup from "effect/http-api/HttpApiGroup";
+import * as HttpApiSchema from "effect/http-api/HttpApiSchema";
+import * as OpenApi from "effect/http-api/OpenApi";
+import { redactionAltered } from "../redaction-marker.js";
+import { ConnectorCallError } from "../errors.js";
+import { refuseWithheldValues } from "../providers/_shared/rest/value-safety.js";
+import { parameterPairs } from "./write-request.js";
+import { validateVendorErrors, captureClassifierFacts, withClassifierFacts, isHttpFailure, RequestRefused, Refusal, ResendRefused, StatusFailure, UnreadableBody, } from "./errors.js";
+import { Classification, Dispatches, RequestFacts, RequestSecrets, ReadTool, WriteCapacity, reserveWrite, } from "./services.js";
+/** Declare a GET operation: `get("getCharge", "/charges/:chargeId", { params, query, success })`. */
+export const get = HttpApiEndpoint.get;
+export const head = HttpApiEndpoint.head;
+export const post = HttpApiEndpoint.post;
+export const put = HttpApiEndpoint.put;
+export const patch = HttpApiEndpoint.patch;
+export const del = HttpApiEndpoint.delete;
+/** A form-encoded request payload: `post("createCharge", "/charges", { payload: form(Schema.Struct(…)) })`. */
+export function form(schema) {
+    return HttpApiSchema.asFormUrlEncoded()(schema);
+}
+/** The vendor's one-line operation summary, for the manifest and a hatch index: `get(…).annotate(Summary, "…")`. */
+export const Summary = OpenApi.Summary;
+const encodedProvenance = new WeakMap();
+/** Result hooks alone may inspect byte counts and redaction flags for an exact decoded JSON field. */
+export function encodedFieldProvenance(answer, path) {
+    return answer !== null && typeof answer === "object"
+        ? encodedProvenance.get(answer)?.get(JSON.stringify(path))
+        : undefined;
+}
+function encodedPath(path) {
+    if (typeof path !== "string" || !/^[A-Za-z0-9_]+(?:\[\*\])?(?:\.[A-Za-z0-9_]+(?:\[\*\])?)*$/.test(path))
+        throw new Error("Encoded fields require exact JSON paths with only whole array wildcards.");
+    return Object.freeze(path.split(".").flatMap((part) => (part.endsWith("[*]") ? [part.slice(0, -3), "*"] : [part])));
+}
+function decodedBase64url(value) {
+    try {
+        // Linear checks: a repeated-group pattern overflows the regex stack on multi-MiB fields.
+        const units = value.replace(/={1,2}$/, "");
+        if (!/^[A-Za-z0-9_+/-]*$/.test(units) || units.length % 4 === 1)
+            return undefined;
+        if (units.length !== value.length && value.length % 4 !== 0)
+            return undefined;
+        const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            bytes[i] = binary.charCodeAt(i);
+        return bytes;
+    }
+    catch {
+        return undefined;
+    }
+}
+function encodedFieldsReview(fields) {
+    const seen = new Set();
+    return Object.freeze((fields ?? []).map((field) => {
+        if (field.encoding !== "base64url" ||
+            typeof field.review !== "string" ||
+            !field.review.trim() ||
+            /[\r\n]/.test(field.review) ||
+            seen.has(field.path))
+            throw new Error("Encoded fields require unique paths, base64url encoding and a one-line review reason.");
+        seen.add(field.path);
+        const path = encodedPath(field.path);
+        const sizePath = field.sizePath === undefined ? undefined : encodedPath(field.sizePath);
+        // Wildcards refer to the same array elements; a size cannot come from another lane.
+        if (sizePath &&
+            (sizePath.filter((part) => part === "*").length !== path.filter((part) => part === "*").length ||
+                sizePath.some((part, index) => part === "*" && path.slice(0, index + 1).join(".") !== sizePath.slice(0, index + 1).join("."))))
+            throw new Error("An encoded field's size path must address the same array elements.");
+        return Object.freeze({ path, ...(sizePath ? { sizePath } : {}) });
+    }));
+}
+function normalizeEncodedFields(value, fields, secrets) {
+    const provenance = new Map();
+    for (const field of fields) {
+        const visit = (node, index, concrete) => {
+            if (node === null || typeof node !== "object")
+                return;
+            const segment = field.path[index];
+            const keys = segment === "*" ? (Array.isArray(node) ? node.map((_, i) => i) : []) : [segment];
+            for (const key of keys) {
+                if (!Object.hasOwn(node, key))
+                    continue;
+                const record = node;
+                const next = [...concrete, key];
+                if (index + 1 < field.path.length) {
+                    visit(record[key], index + 1, next);
+                    continue;
+                }
+                const encoded = record[key];
+                if (typeof encoded !== "string")
+                    continue;
+                const bytes = decodedBase64url(encoded);
+                if (!bytes)
+                    continue;
+                let sizeValid;
+                if (field.sizePath) {
+                    let declared = value;
+                    for (const [i, part] of field.sizePath.entries()) {
+                        const sizeKey = part === "*" ? next[i] : part;
+                        declared =
+                            declared !== null && typeof declared === "object" && Object.hasOwn(declared, sizeKey)
+                                ? declared[sizeKey]
+                                : undefined;
+                    }
+                    sizeValid = typeof declared === "number" && Number.isSafeInteger(declared) && declared === bytes.length;
+                }
+                let changed = false;
+                if (sizeValid !== false) {
+                    let sanitized;
+                    try {
+                        const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+                        const redacted = secrets.redact(text);
+                        sanitized = redacted === text ? bytes : new TextEncoder().encode(redacted);
+                    }
+                    catch {
+                        // Preserve arbitrary bytes; encode's byte path also checks UTF-8 and nested encodings.
+                        let binary = "";
+                        for (const byte of bytes)
+                            binary += String.fromCharCode(byte);
+                        sanitized = Uint8Array.from(secrets.redact(binary), (unit) => unit.charCodeAt(0));
+                    }
+                    const url = !/[+/]/.test(encoded);
+                    let safe = secrets.encode(sanitized, { url });
+                    safe = /=+$/.test(encoded) ? safe + "=".repeat((4 - (safe.length % 4)) % 4) : safe.replace(/=+$/, "");
+                    const safeBytes = decodedBase64url(safe);
+                    changed = safeBytes.length !== bytes.length || safeBytes.some((byte, i) => byte !== bytes[i]);
+                    // Preserve untouched spelling, including padding. The ordinary JSON pass still checks it.
+                    if (changed)
+                        record[key] = safe;
+                }
+                provenance.set(JSON.stringify(next), Object.freeze({ originalLength: bytes.length, ...(sizeValid === undefined ? {} : { sizeValid }), changed }));
+            }
+        };
+        visit(value, 0, []);
+    }
+    return provenance;
+}
+/** Group a vendor's operations into one API, the source of its client and its manifest. */
+export function vendor(declaration, ...operations) {
+    const name = typeof declaration === "string" ? declaration : declaration.name;
+    const manifestBase = typeof declaration === "string" ? undefined : declaration.manifestBase;
+    if (manifestBase !== undefined &&
+        (!/^\/(?:[A-Za-z0-9._~-]+|\{[A-Za-z0-9_]+\})(?:\/(?:[A-Za-z0-9._~-]+|\{[A-Za-z0-9_]+\}))*$/.test(manifestBase) ||
+            manifestBase.split("/").some((segment) => segment === "." || segment === "..")))
+        throw new Error("A vendor manifestBase must be an absolute path prefix without dot segments or a trailing slash.");
+    if (!name.trim() ||
+        operations.length === 0 ||
+        new Set(operations.map((op) => op.identifier)).size !== operations.length)
+        throw new Error("A vendor needs a name and operations with unique identifiers.");
+    return {
+        api: HttpApi.make(name).add(HttpApiGroup.make("operations", { topLevel: true }).add(...operations)),
+        ...(manifestBase === undefined ? {} : { manifestBase }),
+    };
+}
+/**
+ * Bind a vendor to one connection's guarded client. The typed client is built
+ * once, on first use, and lives as long as the connection.
+ */
+export function connect(vendor, guarded, options) {
+    validateVendorErrors(options.errors);
+    const textBodies = vendor.textBodies ? { ...vendor.textBodies } : undefined;
+    const binaryBodies = vendor.binaryBodies ? { ...vendor.binaryBodies } : undefined;
+    const encodedFields = encodedFieldsReview(vendor.encodedFields);
+    if (binaryBodies && (!binaryBodies.review.trim() || typeof binaryBodies.forResponse !== "function"))
+        throw new Error("Binary bodies require a nonempty vendor review and a response contract selector.");
+    if (textBodies && (!textBodies.review.trim() || typeof textBodies.forResponse !== "function"))
+        throw new Error("Text bodies require a nonempty vendor review and a response contract selector.");
+    let built;
+    // HttpApiClient closes over the services it is built in (its middleware
+    // lookup), and the client outlives every call. Build it with none, so it
+    // holds no caller's context, signal, credentials or request scope (INV-7);
+    // its endpoints read each call's services when they run.
+    const construct = HttpApiClient.makeWith(vendor.api, { httpClient: guarded.client }).pipe(Effect.setContext(Context.empty()));
+    const client = Effect.suspend(() => built
+        ? Effect.succeed(built)
+        : construct.pipe(Effect.map((made) => (built = made))));
+    const settle = (operation, response, sendOptions) => Effect.suspend(() => {
+        // The transport names the request it handed to `fetch` here; whatever
+        // its answer settles into is recorded on it in the ledger, so the
+        // write-outcome rule can tell the write's own failure from a later one.
+        const sent = {};
+        return Effect.gen(function* () {
+            const authored = yield* ReadTool;
+            if (authored !== undefined && operation.method !== "GET" && operation.method !== "HEAD" && !authored.review)
+                return yield* Effect.die(new Error("A read tool sending a method other than GET or HEAD requires a review."));
+            if ((yield* Classification) === "write" && sendOptions?.effect !== "read") {
+                const ledger = yield* Dispatches;
+                const capacity = yield* WriteCapacity;
+                // Reserve before request encoding, authentication, or any asynchronous preparation.
+                const slot = yield* Effect.sync(() => reserveWrite(ledger, capacity, { ...sendOptions, operation }));
+                if (slot instanceof RequestRefused || slot instanceof ResendRefused)
+                    return yield* Effect.fail(slot);
+                sent.reservation = slot;
+            }
+            const secrets = yield* RequestSecrets;
+            const reply = yield* Effect.flatMap(response, (response) => {
+                const contentType = formatType(secrets.redact(String(response.headers["content-type"] ?? "")));
+                const binary = response.status >= 200 &&
+                    response.status <= 299 &&
+                    binaryBodies?.forResponse(response.status, operation, contentType) === true;
+                return guarded
+                    .read(response, undefined, binary ? "bytes" : undefined, sendOptions?.prefix)
+                    .pipe(Effect.catchDefect((defect) => Effect.die(sendOptions?.prefix && options.safety.withholdsErrors(operation)
+                    ? new Error("A prefix hook withholding vendor text failed.")
+                    : defect)));
+            });
+            // Header-derived format decisions see only redacted Content-Type. Names are protocol
+            // constants `Headers` must accept, so only the values are redacted, together (#703).
+            const entries = [...reply.headers];
+            const values = secrets.redact(entries.map(([, value]) => value));
+            const headers = new Headers(entries.map(([name], index) => [name, values[index]]));
+            // Whole, before a detail line trims it or a projection extracts from it. Values only:
+            // result safety and projections match fields by their vendor names (#703).
+            let classifierFacts;
+            const parsed = reply.bytes !== undefined
+                ? {
+                    value: reply.bytes.length === 0
+                        ? null
+                        : {
+                            contentType: secrets.redact(reply.headers.get("content-type") ?? "").toLowerCase(),
+                            bytes: reply.bytes.length,
+                            base64: secrets.encode(reply.bytes),
+                        },
+                    format: "json",
+                }
+                : parse(reply.text, (value, format) => {
+                    if (reply.status < 200 || reply.status > 299 || options.inBandRefusals)
+                        classifierFacts = captureClassifierFacts(value, options.errors, reply.headers);
+                    const provenance = format === "json" && encodedFields.length > 0
+                        ? normalizeEncodedFields(value, encodedFields, secrets)
+                        : undefined;
+                    const redacted = reply.prefix?.truncated && typeof value === "string"
+                        ? secrets.redactOpenTail(value)
+                        : secrets.redact(value, "values");
+                    if (provenance?.size && redacted !== null && typeof redacted === "object")
+                        encodedProvenance.set(redacted, provenance);
+                    return redacted;
+                }, textBodies?.forResponse(reply.status, operation, formatType(headers.get("content-type") ?? "")));
+            // Empty and malformed bodies still carry declared numeric response headers.
+            if ((reply.status < 200 || reply.status > 299 || options.inBandRefusals) && !classifierFacts)
+                classifierFacts = captureClassifierFacts(undefined, options.errors, reply.headers);
+            if (reply.status < 200 || reply.status > 299) {
+                return yield* Effect.fail(withClassifierFacts(new StatusFailure({
+                    status: reply.status,
+                    headers,
+                    body: parsed?.value,
+                    ...(parsed ? {} : { unreadable: true }),
+                    operation,
+                }), classifierFacts));
+            }
+            if (!parsed)
+                return yield* Effect.fail(new UnreadableBody(reply.readFailed
+                    ? { readFailed: true }
+                    : formatType(headers.get("content-type") ?? "")
+                        .split(";", 1)[0]
+                        .trim() === "text/html" && !/^[\t\r\n ]*[[{]/.test(reply.text ?? "")
+                        ? { unexpectedText: true }
+                        : {}));
+            const withheld = options.safety.withholdsErrors(operation);
+            const kept = options.result
+                ? yield* Effect.suspend(() => options.result(parsed.value, {
+                    status: reply.status,
+                    bodyFormat: parsed.format,
+                    headers,
+                    operation: { ...operation },
+                    withheld,
+                    ...(reply.prefix ? { prefix: reply.prefix } : {}),
+                })).pipe(Effect.catch((failure) => {
+                    if (failure._tag === "StatusFailure")
+                        return Effect.fail(withClassifierFacts(new StatusFailure({ ...failure, operation }), classifierFacts));
+                    if (!withheld || failure._tag === "UnreadableBody")
+                        return Effect.fail(failure);
+                    return Effect.die(new Error("A result hook withholding vendor text must report an in-band refusal as StatusFailure."));
+                }))
+                : parsed.value;
+            return {
+                status: reply.status,
+                data: options.safety.redact(kept, operation),
+                ...(sendOptions?.responseHeaders?.length
+                    ? {
+                        headers: Object.fromEntries(sendOptions.responseHeaders.flatMap((name) => {
+                            const value = headers.get(name);
+                            return value === null ? [] : [[name.toLowerCase(), value]];
+                        })),
+                    }
+                    : {}),
+                ...(reply.prefix ? { prefix: reply.prefix } : {}),
+            };
+        }).pipe(Effect.tapError((failure) => Effect.sync(() => {
+            const slot = sent.dispatch ?? sent.reservation;
+            if (slot && slot.failure === undefined && failure._tag !== "ResendRefused")
+                slot.failure = failure;
+        })), Effect.provideService(RequestFacts, {
+            effect: sendOptions?.effect === "read" ? "read" : "call",
+            ...(sendOptions?.step === undefined ? {} : { step: sendOptions.step }),
+            ...(sendOptions?.item === undefined ? {} : { item: sendOptions.item }),
+            operation,
+            ...(sendOptions?.prefix ? { successPrefix: true } : {}),
+            sent,
+        }));
+    });
+    const admitAddress = (value) => Effect.try({
+        try: () => refuseWithheldValues(value, guarded.provider, true),
+        catch: (error) => error,
+    }).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error)));
+    const connection = {
+        provider: guarded.provider,
+        errors: options.errors,
+        safety: options.safety,
+        send: (operation, request, sendOptions) => {
+            // Every endpoint carries both; the constraint type erases them.
+            const declared = operation;
+            const ref = {
+                method: declared.method,
+                template: declared.path,
+                ...(sendOptions?.flags ? { flags: sendOptions.flags } : {}),
+            };
+            return Effect.flatMap(admitAddress({
+                params: request.params,
+                query: request.query,
+            }), () => settle(ref, client.pipe(Effect.flatMap((methods) => {
+                const method = methods[operation.identifier];
+                return method
+                    ? method({ ...request, responseMode: "response-only" })
+                    : Effect.fail(new RequestRefused({ message: "This operation is not a named vendor endpoint." }));
+            }), 
+            // The guarded client fails only with HttpFailure. Anything else is a
+            // request the vendor's own Schemas could not encode: a provider bug.
+            Effect.catch((error) => (isHttpFailure(error) ? Effect.fail(error) : Effect.die(error)))), sendOptions));
+        },
+        sendItem: (step, item) => Effect.gen(function* () {
+            const request = (yield* WriteCapacity).get(step)?.get(item);
+            if (!request)
+                return yield* Effect.fail(new RequestRefused({ message: "This write item has no declared request." }));
+            return yield* connection.sendPath(request, { step, item });
+        }),
+        sendPath: (request, sendOptions) => {
+            const { method, path } = request;
+            if (request.rawBody !== undefined &&
+                (sendOptions?.item !== undefined ||
+                    request.json !== undefined ||
+                    request.form !== undefined ||
+                    request.emptyForm))
+                return Effect.fail(new RequestRefused({ message: "A raw body cannot accompany a bulk item or another body encoding." }));
+            return Effect.flatMap(admitAddress({ path, query: request.query }), () => Effect.flatMap(options.safety.resolve(method, path), (operation) => settle({ ...operation, ...(sendOptions?.flags ? { flags: sendOptions.flags } : {}) }, Effect.suspend(() => {
+                let built = HttpClientRequest.make(method)(path, request.query ? { urlParams: parameterPairs(request.query) } : {});
+                if (request.headers)
+                    built = HttpClientRequest.setHeaders(built, request.headers);
+                if (request.form !== undefined && (Object.keys(request.form).length > 0 || request.emptyForm === true)) {
+                    built = HttpClientRequest.bodyText(built, new URLSearchParams(parameterPairs(request.form)).toString(), "application/x-www-form-urlencoded");
+                }
+                if (request.json !== undefined)
+                    built = HttpClientRequest.bodyText(built, request.json, "application/json");
+                if (request.rawBody !== undefined) {
+                    const type = new Headers(request.headers).get("content-type") ?? undefined;
+                    built =
+                        typeof request.rawBody === "string"
+                            ? HttpClientRequest.bodyText(built, request.rawBody, type)
+                            : request.rawBody instanceof Uint8Array
+                                ? HttpClientRequest.bodyUint8Array(built, request.rawBody, type)
+                                : HttpClientRequest.bodyFormData(built, request.rawBody);
+                    // Body combinators supply defaults; an explicit reviewed media type wins.
+                    if (type !== undefined)
+                        built = HttpClientRequest.setHeader(built, "content-type", type);
+                }
+                return guarded.client.execute(built);
+            }), sendOptions)));
+        },
+    };
+    return connection;
+}
+/**
+ * The Content-Type a format decision reads. One redaction altered reads as
+ * `application/json`: a vendor's text or binary choice for it would hand
+ * result safety a body it cannot read field by field (#703).
+ */
+function formatType(redacted) {
+    return redactionAltered(redacted) ? "application/json" : redacted.toLowerCase();
+}
+function parse(text, redact, format) {
+    if (text === undefined)
+        return undefined;
+    if (format === "text")
+        return { value: redact(text, "text"), format: "text" };
+    if (text.trim() === "")
+        return format === "json-or-text"
+            ? { value: redact(text, "text"), format: "text" }
+            : { value: undefined, format: "empty" };
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return format === "json-or-text" ? { value: redact(text, "text"), format: "text" } : undefined;
+    }
+    return { value: redact(value, "json"), format: "json" };
+}
+/** The endpoint manifest drift checks compare against the vendor's published contract. */
+export function manifest(vendor) {
+    const document = OpenApi.fromApi(vendor.indexed?.api() ?? vendor.api);
+    return vendor.manifestBase === undefined
+        ? document
+        : {
+            ...document,
+            paths: Object.fromEntries(Object.entries(document.paths).map(([path, operation]) => [vendor.manifestBase + path, operation])),
+        };
+}
+const METHODS = ["get", "head", "post", "put", "patch", "delete"];
+/**
+ * Every operation of `manifest(vendor)` as `"METHOD /path"`, sorted: the
+ * `operations` of decision 0011's `ProviderKitFacts`, which
+ * `providers:generate` writes into `drift.json`'s `generated.operations`.
+ */
+export function operations(vendor) {
+    if (vendor.indexed)
+        return [...vendor.indexed.operations];
+    return Object.entries(manifest(vendor).paths)
+        .flatMap(([path, item]) => METHODS.filter((method) => item[method] !== undefined).map((method) => `${method.toUpperCase()} ${path}`))
+        .sort();
+}

package/dist/http/write-request.js

@@ -0,0 +1,66 @@
+// Lossless identifying content for bulk reservations. In particular, never
+// turn wire parameters or JSON properties into an Object: vendors disagree
+// about first/last-value semantics, so duplicate keys require an explicit
+// per-key contract and their value order always remains significant.
+import { parseExpressionAt } from "acorn";
+export function parameterPairs(parameters) {
+    return Array.isArray(parameters) ? parameters.map(([key, value]) => [key, value]) : Object.entries(parameters ?? {});
+}
+/** Sort distinct names only; stable sorting preserves every repeated value's order. */
+function ordered(pairs, allowed = []) {
+    const seen = new Set();
+    for (const [key] of pairs) {
+        if (seen.has(key) && !allowed.includes(key))
+            throw new Error("Duplicate identifying keys need declared multi-value semantics.");
+        seen.add(key);
+    }
+    return pairs.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+function jsonContent(text, allowed = []) {
+    // Validate the JSON grammar first. Acorn retains every property, including
+    // escaped duplicate names; JSON.parse alone would silently discard them.
+    JSON.parse(text);
+    const visit = (node, path) => {
+        switch (node.type) {
+            case "ObjectExpression": {
+                const pairs = node.properties.map((property) => {
+                    if (property.type !== "Property" || property.key.type !== "Literal")
+                        throw new Error("Invalid JSON property.");
+                    const key = String(property.key.value);
+                    const pointer = `${path}/${key.replace(/~/g, "~0").replace(/\//g, "~1")}`;
+                    return [key, visit(property.value, pointer)];
+                });
+                return [
+                    "object",
+                    ordered(pairs, pairs.flatMap(([key]) => {
+                        const pointer = `${path}/${key.replace(/~/g, "~0").replace(/\//g, "~1")}`;
+                        return allowed.includes(pointer) ? [key] : [];
+                    })),
+                ];
+            }
+            case "ArrayExpression":
+                return ["array", node.elements.map((element, index) => visit(element, `${path}/${index}`))];
+            default: {
+                const raw = text.slice(node.start, node.end);
+                // Never round large identifiers, coerce -0, or collapse overflow to
+                // null while making the key. Retain numeric lexemes losslessly.
+                return /^[-0-9]/.test(raw) ? ["number", raw] : ["value", JSON.parse(raw)];
+            }
+        }
+    };
+    return visit(parseExpressionAt(text, 0, { ecmaVersion: "latest" }), "");
+}
+/** Canonical ordered multimaps, including JSON structure and paths; no credentials. */
+export function writeRequestKey(request) {
+    if ("rawBody" in request && request.rawBody !== undefined)
+        throw new Error("A bulk write item cannot declare a raw body.");
+    if (request.form !== undefined && request.json !== undefined)
+        throw new Error("A write item declares one body encoding.");
+    return JSON.stringify([
+        request.method,
+        new URL(`https://request.example${request.path}`).pathname,
+        ordered(parameterPairs(request.query), request.multiValue?.query),
+        ordered(parameterPairs(request.form), request.multiValue?.form),
+        request.json === undefined ? null : jsonContent(request.json, request.multiValue?.json),
+    ]);
+}

package/dist/http-policy.d.ts

@@ -0,0 +1,11 @@
+/** Statuses that instruct a client to re-send somewhere else. Never followed. */
+export declare const REDIRECT_STATUSES: Set<number>;
+/** Statuses the HTTP spec defines as carrying no body at all. */
+export declare const BODILESS_STATUSES: Set<number>;
+/**
+ * A base URL is deployment configuration, so a bad one is a structural mistake
+ * and throws where it is written rather than on the first call that uses it.
+ */
+export declare function confinementBase(provider: string, baseUrl: string): URL;
+/** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
+export declare function retryAfterMs(headers: Headers): number | undefined;

package/dist/http-policy.js

@@ -0,0 +1,45 @@
+// Pure policy shared by the Promise and Effect transports. No runtime or kit imports.
+/** Statuses that instruct a client to re-send somewhere else. Never followed. */
+export const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Statuses the HTTP spec defines as carrying no body at all. */
+export const BODILESS_STATUSES = new Set([204, 205, 304]);
+/**
+ * A base URL is deployment configuration, so a bad one is a structural mistake
+ * and throws where it is written rather than on the first call that uses it.
+ */
+export function confinementBase(provider, baseUrl) {
+    let base;
+    try {
+        base = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`${provider} baseUrl must be an absolute URL.`);
+    }
+    const loopback = base.hostname === "localhost" || base.hostname === "127.0.0.1" || base.hostname === "[::1]";
+    if (base.protocol !== "https:" && !(base.protocol === "http:" && loopback)) {
+        throw new Error(`${provider} baseUrl must be https (http is allowed only for a loopback proxy or test double).`);
+    }
+    if (base.username || base.password) {
+        throw new Error(`${provider} baseUrl must not embed URL credentials; authentication belongs in headers.`);
+    }
+    if (base.search || base.hash) {
+        throw new Error(`${provider} baseUrl must not carry a query or fragment.`);
+    }
+    return base;
+}
+/** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
+export function retryAfterMs(headers) {
+    const raw = headers.get("retry-after");
+    if (!raw)
+        return undefined;
+    const seconds = Number(raw.trim());
+    if (Number.isFinite(seconds)) {
+        return seconds < 0 ? undefined : Math.trunc(seconds * 1000);
+    }
+    // Require the HTTP-date shape, so Date.parse cannot reinterpret "-1" as
+    // a calendar date on runtimes that accept loose date strings.
+    if (!/^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(raw.trim()))
+        return undefined;
+    const date = Date.parse(raw);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
+}

package/dist/inbound-credential.js

@@ -45,7 +45,7 @@ export function authorizationRequest(request) {
     parsed.set(normalized, { header: headers.get("authorization"), credential });
     return normalized;
 }
-/** Reserved machine syntax, even when the optional verifier is not installed. */
+/** Reserved token syntax, even when the optional verifier is not installed. */
 export function isMachineCredential(request) {
     const credential = authorizationCredential(request);
     return credential.kind === "bearer" && credential.token.startsWith("cta_");

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export { remoteMcp } from "./connectors/remote-mcp.js";
 export { api } from "./connectors/api.js";
 export { keys, optionsOf, array, opaque, instance, strings, variants } from "./config-schema.js";
 export { defineProvider, PROVIDER_COMMON } from "./provider.js";
-export type { ProviderContext, ProviderDefinition, ProviderFactory, ProviderGuideInput, ProviderKind, ProviderOptions, ProviderSkill, } from "./provider.js";
+export type { ProviderContext, ProviderDefinition, ProviderFactory, ProviderGuideBlocks, ProviderGuideInput, ProviderKitFacts, ProviderOptions, ProviderSkill, } from "./provider.js";
 export { ConnectorCallError } from "./errors.js";
 export type { ConnectorCallErrorCode, CallErrorDetails } from "./errors.js";
 export { validateToolInput } from "./validate.js";
@@ -40,6 +40,6 @@ export type { GuestApi, GuestResourceResult, GuestResult, GuestResultPage, Guest
 export type { Registry } from "./registry.js";
 export type { RemoteMcpOptions, RemoteMcpAuth, RemoteMcpRedirectPolicy } from "./connectors/remote-mcp.js";
 export type { ApiHandlerContext, ApiOAuthAccess, ApiOAuthClientAuthentication, ApiOAuthConfig, ApiOptions, ApiTool, } from "./connectors/api.js";
-export type { CatalogDriftCounts, CatalogDriftReport, ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorAuthDescription, ConnectorDescription, ConnectorToolDescription, ConnectorUsageGuide, ConnectorSkill, ConnectorSkillResourceContents, DescribedEndpoint, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ReviewedTool, ToolClassification, ToolDef, ToolAnnotations, ToolVerdict, } from "./types.js";
+export type { ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorAuthDescription, ConnectorDescription, ConnectorToolDescription, ConnectorUsageGuide, ConnectorSkill, ConnectorSkillResourceContents, DescribedEndpoint, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
 export type { ActivityActor, ActivityCatalogChange, ActivityCallSource, ActivityOutcome, ActivityPage, ActivityReadActor, ActivityReadEvent, ActivityReader, ActivityReadGate, ActivityReadPage, ActivitySink, ActivityStore, AgentFriction, ToolCallActivityEvent, } from "./activity.js";
 export { META_TOOL_NAMES } from "./meta-tool-names.js";

package/dist/index.js

@@ -61,6 +61,9 @@ function resolvePools(pools, readOnly, registry, members) {
         if (pool.members.length === 0) {
             throw new ConfigError(`${path} is empty; a pool serves only its members, so list at least one.`);
         }
+        if (pool.executeCode !== undefined && pool.surface !== "native") {
+            throw new ConfigError(`ConnectaConfig.pools.${name}.executeCode needs surface: "native"; the meta surface always includes execute_code.`);
+        }
         // A pool inherits the deployment value unless it sets its own, either way.
         resolved.set(name, Object.freeze({
             access,
@@ -68,6 +71,7 @@ function resolvePools(pools, readOnly, registry, members) {
             members: Object.freeze(resolveMembers(pool.members, path, members)),
             ...(pool.owner !== undefined ? { owner: pool.owner.trim() } : {}),
             ...(pool.description !== undefined ? { description: pool.description.trim() } : {}),
+            ...(pool.surface === "native" ? { native: { executeCode: pool.executeCode ?? true } } : {}),
         }));
     }
     return resolved;