@zackbart/connecta 0.34.1 → 0.35.0

package/dist/http/paging.js

@@ -0,0 +1,228 @@
+// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+//
+// Paging is a strategy plus one cursor codec. A strategy turns "the next page
+// after this cursor" into a vendor request and reads back rows and the next
+// vendor cursor; tools take one page, and `allRows` walks every page as a
+// Stream for programs and the hatch. The codec is the only place a cursor is
+// minted: `plain` hands the vendor's cursor through (what shipped providers
+// promise today, so goldens hold), `bound` ties it to the tool and its
+// arguments so a cursor from another call is refused instead of silently
+// reading the wrong list.
+import { Effect, Option, Schema, Stream } from "effect";
+import { ConnectorCallError } from "../errors.js";
+import { Refusal } from "./errors.js";
+import { confinementBase } from "../http-policy.js";
+import { canonicalJson } from "../canonical-json.js";
+import { ContinuationBinding, ContinuationStorage } from "../runtime/call.js";
+import { continuationKeys } from "../storage/keys.js";
+/** The `page` object every list tool returns. */
+export const PageInfo = Schema.Struct({
+    hasMore: Schema.Boolean,
+    nextCursor: Schema.NullOr(Schema.String),
+});
+/**
+ * The standard `page` (decision 0011 S2): `nextCursor` is present exactly
+ * when `hasMore` is true and continuation is safe. A hatch adapter can report
+ * more data without a cursor when its continuation cannot be confined.
+ * Step-1 lists keep `PageInfo` until their step 2.
+ */
+export const StandardPage = Schema.Struct({
+    hasMore: Schema.Boolean,
+    nextCursor: Schema.optionalKey(Schema.String),
+});
+/** The input field that carries a cursor back. */
+export const Cursor = Schema.String.check(Schema.isMinLength(1)).annotate({
+    description: "Opaque nextCursor from the previous page. Pass it back unchanged.",
+});
+/**
+ * Lookahead paging, for a vendor that returns no `has_more`: ask for one row
+ * more than wanted, keep `limit`, and address the next page by the last kept
+ * row's id. A full page proves nothing; the extra row does.
+ */
+export function lookahead(options) {
+    return Effect.gen(function* () {
+        const all = yield* options.fetch(options.limit + 1);
+        const rows = all.slice(0, options.limit);
+        const hasMore = all.length > options.limit;
+        if (!hasMore)
+            return { rows, page: { hasMore, nextCursor: null } };
+        const last = rows[rows.length - 1];
+        const id = last?.[options.idKey];
+        if (typeof id !== "string" || id === "") {
+            return yield* Effect.fail(new Refusal({
+                error: new ConnectorCallError("connector_call_failed", `${options.provider} returned a page whose last row has no ${options.idKey}, so the next page cannot be addressed.`, { retryable: false }),
+            }));
+        }
+        return { rows, page: { hasMore, nextCursor: id } };
+    });
+}
+/** Vendor-supplied continuation, read only after the connection made its data safe. */
+export function token(options) {
+    return Effect.flatMap(Effect.suspend(options.fetch), ({ rows, hasMore, nextCursor }) => {
+        if (hasMore && !nextCursor)
+            return badPage("The vendor reported another page without a next cursor.");
+        return Effect.succeed({ rows, page: { hasMore, nextCursor: hasMore ? nextCursor : null } });
+    });
+}
+/** Offset paging advances by the rows actually returned, with a total when supplied. */
+export function offset(options) {
+    return Effect.gen(function* () {
+        yield* position(options.offset, 0);
+        yield* position(options.limit, 1);
+        return yield* Effect.map(options.fetch(options.offset, options.limit), ({ rows, total }) => {
+            const next = options.offset + rows.length;
+            const hasMore = rows.length > 0 && (total === undefined ? rows.length >= options.limit : next < total);
+            return { rows, page: { hasMore, nextCursor: hasMore ? String(next) : null } };
+        });
+    });
+}
+/** Page numbers from a vendor's safe body or headers, with full-page fallback. */
+export function page(options) {
+    return Effect.gen(function* () {
+        yield* position(options.page, 1);
+        yield* position(options.limit, 1);
+        return yield* Effect.map(options.fetch(options.page, options.limit), ({ rows, hasMore, totalPages }) => {
+            const more = hasMore ?? (totalPages === undefined ? rows.length >= options.limit : options.page < totalPages);
+            return { rows, page: { hasMore: more, nextCursor: more ? String(options.page + 1) : null } };
+        });
+    });
+}
+/** Extract only a cursor from a next URL confined to this connection's origin and path. */
+export function link(options) {
+    const base = confinementBase("Paging", options.baseUrl);
+    const prefix = base.pathname.replace(/\/+$/, "");
+    if (!options.param)
+        throw new Error("Link paging needs a cursor parameter.");
+    return Effect.flatMap(Effect.suspend(options.fetch), ({ rows, next }) => {
+        if (!next)
+            return Effect.succeed({ rows, page: { hasMore: false, nextCursor: null } });
+        let url;
+        try {
+            url = new URL(next, base);
+        }
+        catch {
+            return badPage("The vendor returned an invalid next-page URL.");
+        }
+        if (url.origin !== base.origin ||
+            !`${url.pathname}/`.startsWith(`${prefix}/`) ||
+            url.username ||
+            url.password ||
+            url.hash)
+            return badPage("The vendor returned a next-page URL outside this connection.");
+        const cursors = url.searchParams.getAll(options.param);
+        if (cursors.length !== 1 || !cursors[0])
+            return badPage("The vendor returned no unique next-page cursor.");
+        return Effect.succeed({ rows, page: { hasMore: true, nextCursor: cursors[0] } });
+    });
+}
+function position(value, minimum) {
+    return Number.isSafeInteger(value) && value >= minimum
+        ? Effect.void
+        : Effect.fail(new Refusal({
+            error: new ConnectorCallError("invalid_args", "Paging positions and limits must be whole numbers within their bounds."),
+        }));
+}
+function badPage(message) {
+    return Effect.fail(new Refusal({ error: new ConnectorCallError("connector_call_failed", message, { retryable: false }) }));
+}
+/** Every row of every page, fetched as the stream is pulled. */
+export function allRows(fetchPage) {
+    return Stream.paginate(undefined, (cursor) => Effect.map(fetchPage(cursor), ({ rows, page }) => [rows, Option.fromNullishOr(page.hasMore ? page.nextCursor : null)]));
+}
+const STRAY_CURSOR = "This cursor belongs to a different call. Pass back the nextCursor from the previous page of this same call, with the same arguments.";
+/** Resolved, nonextractable keys only: no request promise is retained between calls. */
+const signingKeys = new WeakMap();
+async function signingKey(storage) {
+    const cached = signingKeys.get(storage);
+    if (cached)
+        return cached;
+    let raw = await storage.get(continuationKeys.signingKey);
+    if (raw === null) {
+        const candidate = Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        raw = (await storage.compareAndSet(continuationKeys.signingKey, null, candidate))
+            ? candidate
+            : await storage.get(continuationKeys.signingKey);
+    }
+    if (raw === null || !/^[a-f0-9]{64}$/.test(raw))
+        throw new Error("The continuation signing key is unavailable.");
+    const key = await crypto.subtle.importKey("raw", Uint8Array.from(raw.match(/../g), (byte) => Number.parseInt(byte, 16)), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+    signingKeys.set(storage, key);
+    return key;
+}
+const keyUnavailable = () => new Refusal({
+    error: new ConnectorCallError("unavailable", "The cursor signing key is unavailable. Retry after storage recovers; a corrupt key requires operator recovery.", { retryable: true }),
+});
+const keyForCall = ContinuationStorage.use((storage) => storage
+    ? Effect.tryPromise({ try: () => signingKey(storage), catch: keyUnavailable })
+    : Effect.fail(keyUnavailable()));
+/**
+ * Authenticated base64url JSON `{v, d, c, m}`: the MAC covers the version,
+ * connection/owner/caller binding, tool/argument digest and continuation
+ * payload in a canonical tuple and envelope. The deployment store owns
+ * the key across isolates/restarts; limit and cursor are excluded from args.
+ */
+export const boundCursor = {
+    encode(tool, args, cursor, encode = base64url) {
+        return Effect.gen(function* () {
+            const d = yield* digest(tool, args);
+            const key = yield* keyForCall;
+            const binding = yield* ContinuationBinding;
+            const claims = new TextEncoder().encode(canonicalJson([2, binding.connection, binding.principal, d, cursor]));
+            const mac = yield* Effect.promise(() => crypto.subtle.sign("HMAC", key, claims));
+            const m = base64urlBytes(new Uint8Array(mac));
+            return encode(JSON.stringify({ v: 2, d, c: cursor, m }));
+        });
+    },
+    decode(tool, args, token) {
+        return Effect.gen(function* () {
+            const expected = yield* digest(tool, args);
+            let parsed;
+            try {
+                parsed = JSON.parse(new TextDecoder().decode(fromBase64url(token)));
+            }
+            catch {
+                parsed = undefined;
+            }
+            const record = parsed;
+            if (record?.v !== 2 ||
+                record.d !== expected ||
+                typeof record.c !== "string" ||
+                typeof record.m !== "string" ||
+                !/^[A-Za-z0-9_-]{43}$/.test(record.m)) {
+                return yield* Effect.fail(new Refusal({ error: new ConnectorCallError("invalid_args", STRAY_CURSOR) }));
+            }
+            if (token !== base64url(JSON.stringify({ v: record.v, d: record.d, c: record.c, m: record.m })))
+                return yield* Effect.fail(new Refusal({ error: new ConnectorCallError("invalid_args", STRAY_CURSOR) }));
+            const key = yield* keyForCall;
+            const mac = fromBase64url(record.m);
+            const binding = yield* ContinuationBinding;
+            const claims = new TextEncoder().encode(canonicalJson([record.v, binding.connection, binding.principal, record.d, record.c]));
+            const valid = yield* Effect.promise(() => crypto.subtle.verify("HMAC", key, mac, claims));
+            if (!valid || base64urlBytes(mac) !== record.m) {
+                return yield* Effect.fail(new Refusal({ error: new ConnectorCallError("invalid_args", STRAY_CURSOR) }));
+            }
+            return record.c;
+        });
+    },
+};
+function digest(tool, args) {
+    const shape = Object.keys(args)
+        .filter((key) => key !== "cursor" && key !== "limit" && args[key] !== undefined)
+        .sort()
+        .map((key) => [key, args[key]]);
+    const bytes = new TextEncoder().encode(canonicalJson([tool, shape]));
+    return Effect.promise(() => crypto.subtle.digest("SHA-256", bytes)).pipe(Effect.map((hash) => Array.from(new Uint8Array(hash).slice(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("")));
+}
+function base64url(text) {
+    return base64urlBytes(new TextEncoder().encode(text));
+}
+function base64urlBytes(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64url(token) {
+    const binary = atob(token.replace(/-/g, "+").replace(/_/g, "/"));
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}

package/dist/http/provider.js

@@ -0,0 +1,221 @@
+// Internal provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+import { Context, Effect, Option } from "effect";
+import { api } from "../connectors/api.js";
+import { OAUTH_CHALLENGE_MAX_BYTES } from "../auth/renewable-grant.js";
+import { ConnectorCallError } from "../errors.js";
+import { defineProvider, } from "../provider.js";
+import { tracksEveryRequest } from "../provider-call.js";
+import { unsentAfterUnauthorized } from "../write-outcome.js";
+import { Operation } from "../runtime/call.js";
+import { runEdge } from "../runtime/run.js";
+import { guardedClient } from "./client.js";
+import { errorMeanings, Refusal, toConnectorCallError, withheldDefect, } from "./errors.js";
+import { hatch } from "./hatch.js";
+import { takesIdempotencyKey } from "./tools.js";
+import { Grant, grantFromOAuth, refreshOnce } from "./oauth.js";
+import { resultSafety } from "./safety.js";
+import { Classification, Dispatches, Signal, WriteCapacity, fromConnectorContext, } from "./services.js";
+import { connect, operations } from "./vendor.js";
+/** A declared hatch for one connection: its notes resolved from that connection's options. */
+function hatchDeclaration(declared, options, connection) {
+    const { notes, binding, writeEnabled, ...rest } = declared;
+    return {
+        ...rest,
+        ...(notes ? { notes: notes(options) } : {}),
+        ...(writeEnabled ? { writeEnabled: writeEnabled(options) } : {}),
+        ...(binding ? { binding: binding({ connection, options }) } : {}),
+    };
+}
+/** Bind the Promise OAuth facade belonging to this call, never a connection-wide grant. */
+const callGrant = Effect.gen(function* () {
+    // Operation is bridge metadata, not a service a provider program supplies.
+    const operation = yield* Effect.serviceOption(Operation);
+    const oauth = Option.isSome(operation) ? operation.value?.oauth : undefined;
+    return oauth ? grantFromOAuth(oauth) : missingGrant;
+});
+const noGrant = Effect.fail(new Refusal({
+    error: new ConnectorCallError("auth_required", "This connection has no OAuth grant."),
+}));
+const missingGrant = {
+    token: noGrant,
+    refresh: () => noGrant,
+    rejected: noGrant,
+};
+/** An ordinary Promise connector factory; Effect remains inside the kit. */
+export function defineApiProvider(definition) {
+    const { displayTitle, description, authScope, vendor, baseUrl, maxResponseBytes, timeoutMs, headers, admit, transport, defaultCallAdmission, pageSize: declaredPageSize, idempotencyKey, credential, oauth, oauthWrite401, grant, grantRenewal, authenticate, errors, safety, result, inBandRefusals, probe, guide, transformGuide, hatch: declaredHatch, tools, tagConnector, ...metadata } = definition;
+    if (credential !== undefined && oauth !== undefined) {
+        throw new Error(`${metadata.title} declares both credential and oauth; declare one authentication method.`);
+    }
+    if (oauthWrite401 && !oauth)
+        throw new Error("oauthWrite401 requires a static OAuth declaration.");
+    if (grant && oauth)
+        throw new Error("A provider declares either a machine grant or static OAuth, never both.");
+    if (grantRenewal && !grant)
+        throw new Error("grantRenewal requires a machine grant declaration.");
+    const renewalModes = grantRenewal ? { ...grantRenewal } : undefined;
+    if (!Number.isInteger(maxResponseBytes) || maxResponseBytes < 1) {
+        throw new Error(`${metadata.title} maxResponseBytes must be a whole number of bytes >= 1.`);
+    }
+    const pageSize = declaredPageSize === undefined ? undefined : { ...declaredPageSize };
+    if (pageSize &&
+        (!Number.isSafeInteger(pageSize.default) ||
+            !Number.isSafeInteger(pageSize.max) ||
+            pageSize.default < 1 ||
+            pageSize.max < pageSize.default)) {
+        throw new Error(`${metadata.title} pageSize needs positive whole default and max values, with default <= max.`);
+    }
+    const meanings = errorMeanings(errors);
+    if (idempotencyKey !== undefined && typeof idempotencyKey !== "boolean")
+        throw new Error(`${metadata.title} idempotencyKey must be true or false when declared.`);
+    const hatchOptions = declaredHatch
+        ? {
+            ...declaredHatch,
+            verdicts: { ...declaredHatch.verdicts },
+            ...(declaredHatch.named ? { named: { ...declaredHatch.named } } : {}),
+        }
+        : undefined;
+    return defineProvider({
+        ...metadata,
+        kind: "api",
+        kit: {
+            operations: operations(vendor),
+            ...(pageSize ? { pageSize } : {}),
+            ...(hatchOptions
+                ? {
+                    hatch: {
+                        name: hatchOptions.name,
+                        verdicts: hatchOptions.verdicts,
+                        ...(hatchOptions.fieldsRoot ? { fieldsRoot: hatchOptions.fieldsRoot } : {}),
+                        ...(hatchOptions.pageCursor && Object.keys(hatchOptions.pages ?? {}).length
+                            ? { paging: hatchOptions.pageCursor }
+                            : {}),
+                    },
+                    refusesWithheld: true,
+                }
+                : {}),
+            ...(meanings ? { errors: meanings } : {}),
+            ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+        },
+        create(id, options, provider) {
+            const connectionCredential = typeof credential === "function" ? credential(options) : credential;
+            const override = "defaultPageSize" in options ? options.defaultPageSize : undefined;
+            if (override !== undefined &&
+                (!pageSize ||
+                    typeof override !== "number" ||
+                    !Number.isSafeInteger(override) ||
+                    override < 1 ||
+                    override > pageSize.max)) {
+                throw new Error(`defaultPageSize must be a whole number from 1 to ${pageSize?.max ?? "a declared pageSize maximum"}.`);
+            }
+            const configured = transport?.(options);
+            const machineGrant = grant?.(options);
+            const guarded = guardedClient({
+                provider: errors.provider,
+                baseUrl: baseUrl(options),
+                maxResponseBytes,
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                ...(oauthWrite401 ? { maxUnauthorizedResponseBytes: OAUTH_CHALLENGE_MAX_BYTES } : {}),
+                ...(headers === undefined ? {} : { headers }),
+                ...(admit === undefined ? {} : { admit }),
+                authenticate: typeof authenticate === "function" ? authenticate(options) : authenticate,
+                ...configured,
+            });
+            const connected = connect(vendor, oauth || machineGrant
+                ? refreshOnce(guarded, oauthWrite401
+                    ? {
+                        challengeMaxBytes: OAUTH_CHALLENGE_MAX_BYTES,
+                        writeUnauthorized: (renewal) => unsentAfterUnauthorized(`Connector "${id}"'s API`, renewal._tag === "Renewed"
+                            ? undefined
+                            : renewal._tag === "Failed"
+                                ? renewal.failure
+                                : new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`), "downstream_oauth_required"),
+                    }
+                    : renewalModes)
+                : guarded, {
+                errors,
+                safety: resultSafety(safety(options)),
+                ...(inBandRefusals ? { inBandRefusals } : {}),
+                ...(result ? { result } : {}),
+            });
+            const authorize = (work) => work.pipe(Effect.provideServiceEffect(Grant, machineGrant ?? (oauth ? callGrant : Effect.succeed(missingGrant))));
+            const connection = {
+                ...connected,
+                send: (...args) => authorize(connected.send(...args)),
+                sendPath: (...args) => authorize(connected.sendPath(...args)),
+                sendItem: (...args) => authorize(connected.sendItem(...args)),
+            };
+            // Construct programs outside every caller context; only execution receives candidate services.
+            const probeProgram = probe.run
+                ? probe.run(connection, options)
+                : connection
+                    .send(probe.operation, (typeof probe.request === "function" ? probe.request(options) : probe.request))
+                    .pipe(Effect.map(({ data }) => data));
+            const test = (values, ctx) => {
+                const problem = probe.check?.(values, options);
+                if (problem !== undefined)
+                    return Promise.resolve({ ok: false, message: problem });
+                // api() has already installed anonymous, uncharged candidate services.
+                // Bridge those services directly; never copy the supplied context.
+                const lease = fromConnectorContext(ctx, "read");
+                const signal = Context.get(lease.services, Signal);
+                const map = {
+                    classification: Context.get(lease.services, Classification),
+                    dispatches: Context.get(lease.services, Dispatches),
+                    withholds: connection.safety.withholdsErrors,
+                    signal,
+                };
+                return runEdge(probeProgram.pipe(Effect.provideService(WriteCapacity, new Map()), Effect.flatMap((data) => Effect.try({
+                    try: () => {
+                        const described = probe.describe(data, options);
+                        return typeof described === "string" ? { ok: true, message: described } : described;
+                    },
+                    catch: (error) => error,
+                }).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error)))), Effect.catch((failure) => Effect.sync(() => {
+                    const error = toConnectorCallError(failure, errors, map);
+                    return probe.failure?.(error, options) ?? { ok: false, message: error.message };
+                })), Effect.catchDefect((defect) => Effect.die(withheldDefect(defect, map, !!probe.run))), Effect.provideContext(lease.services), Effect.ensuring(Effect.sync(lease.close))), { signal: ctx.signal });
+            };
+            const builtTools = tools({
+                connection,
+                options,
+                get pageSize() {
+                    if (!pageSize)
+                        throw new Error("Declare pageSize before using the kit's pageSize.");
+                    return typeof override === "number" ? override : pageSize.default;
+                },
+            });
+            const hatchTools = hatchOptions
+                ? hatch({ ...hatchDeclaration(hatchOptions, options, connection), connection })
+                : [];
+            // The declared fact the Writes convention states must match what the write builders send.
+            if (idempotencyKey !== undefined && [...builtTools, ...hatchTools].some(takesIdempotencyKey) !== idempotencyKey)
+                throw new Error(`${metadata.title} declares idempotencyKey: ${idempotencyKey}, but its write tools ${idempotencyKey ? "send no" : "send an"} idempotency key.`);
+            const usageGuide = guide(options);
+            const renderedGuide = "content" in usageGuide ? usageGuide : provider.usageGuide(usageGuide);
+            const connector = tracksEveryRequest(api(id, {
+                ...(defaultCallAdmission
+                    ? {
+                        callAdmission: typeof defaultCallAdmission === "function" ? defaultCallAdmission(options) : defaultCallAdmission,
+                    }
+                    : {}),
+                ...provider.connectorOptions,
+                ...(authScope ? { authScope: authScope(options) } : {}),
+                title: options.title ?? displayTitle?.(options) ?? metadata.title,
+                ...(description ? { description: description(options) } : {}),
+                usageGuide: transformGuide ? transformGuide(renderedGuide, options) : renderedGuide,
+                ...(connectionCredential
+                    ? {
+                        credential: connectionCredential,
+                        testCredential: (value, ctx) => test({ value }, ctx),
+                        testCredentials: (values, ctx) => test(values, ctx),
+                    }
+                    : {}),
+                ...(oauth ? { oauth: oauth(options) } : {}),
+                tools: [...builtTools, ...hatchTools],
+            }));
+            tagConnector?.(connector, options);
+            return connector;
+        },
+    });
+}

package/dist/http/safety.js

@@ -0,0 +1,82 @@
+// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+//
+// The one value-safety boundary of a kit connection. `connect` requires it,
+// and `Send` hands a provider nothing it has not passed: a named tool, a
+// hatch, a paging strategy, and a projection all read an answer only after
+// the vendor's reviewed redaction and the deployment's sensitive-field
+// choice ran on it. Nothing upstream of it reaches a cursor or a result.
+//
+// The same boundary answers, per operation and before any detail is
+// extracted, whether a failure may quote the vendor's text. A stored secret
+// a request never sent can still sit in a vendor's error prose, so
+// sent-secret redaction cannot stand in for it.
+import { Effect } from "effect";
+import { ConnectorCallError } from "../errors.js";
+import { Refusal } from "./errors.js";
+/** Refuses at construction a connection with neither a reviewed table nor a reason (INV-11). */
+export function resultSafety(options) {
+    const review = options.review?.trim();
+    if (!options.reviewed && !review) {
+        throw new Error("A kit connection needs a reviewed value-safety table, or a review saying why it has none.");
+    }
+    const { choice, names } = options.sensitiveFields;
+    if (choice !== "drop" && choice !== "return")
+        throw new Error('sensitiveFields must be "drop" or "return".');
+    const dropped = new Set(choice === "drop" ? names : []);
+    const strip = (value) => {
+        if (Array.isArray(value))
+            return value.map(strip);
+        if (!value || typeof value !== "object")
+            return value;
+        return Object.fromEntries(Object.entries(value)
+            .filter(([name]) => !dropped.has(name))
+            .map(([name, entry]) => [name, strip(entry)]));
+    };
+    const reviewed = options.reviewed;
+    return {
+        refusal: (operation) => reviewed?.refusal?.(operation),
+        resolve: (method, path) => Effect.try({
+            try: () => {
+                if (reviewed?.resolve)
+                    return reviewed.resolve(method, path);
+                if (!reviewed && review)
+                    return { method, template: path };
+                throw new ConnectorCallError("invalid_args", "A reviewed path request needs a canonical operation index.");
+            },
+            catch: (error) => error,
+        }).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error))),
+        redact: (data, operation) => {
+            const safe = reviewed ? reviewed.redact(data, operation) : data;
+            return dropped.size > 0 ? strip(safe) : safe;
+        },
+        withholdsErrors: (operation) => reviewed?.withholdsErrors(operation) === true,
+    };
+}
+/** Bind the REST value-safety table to its pinned index; unknown operations never bypass its review. */
+export function restSafety(reviewed, index) {
+    const indexed = (operation) => index.operation(operation.method, operation.template) ??
+        index.operation(operation.method, operation.template.replace(/\/:([^/]+)/g, "/{$1}"));
+    return {
+        refusal: (operation) => {
+            const op = indexed(operation);
+            return op ? reviewed.refusal(op.method, op.path) : undefined;
+        },
+        resolve: (method, path) => {
+            const { op } = index.resolve(method, path);
+            const refusal = reviewed.refusal(op.method, op.path);
+            if (refusal)
+                throw new ConnectorCallError("invalid_args", refusal);
+            return { method: op.method, template: op.path };
+        },
+        redact: (data, operation) => {
+            const op = indexed(operation);
+            if (!op)
+                throw new Error("A reviewed answer has no canonical operation in its index.");
+            return reviewed.redact(data, op.method, op.path);
+        },
+        withholdsErrors: (operation) => {
+            const op = indexed(operation);
+            return op ? reviewed.withholdsErrors(op) : true;
+        },
+    };
+}

package/dist/http/services.js

@@ -0,0 +1,79 @@
+// HTTP request facts and fixed write reservations (B.2/B.4).
+import { Context, Effect } from "effect";
+import { dispatchProviderRequest, providerRequest } from "../provider-call.js";
+import { callClassification } from "../call-classification.js";
+import { fromSignal } from "../runtime/run.js";
+import { callFromContext, ContinuationBinding, ContinuationStorage, openCall as openCoreCall, serviceFor, Signal, } from "../runtime/call.js";
+import { RequestRefused, ResendRefused } from "./errors.js";
+export { writeRequestKey } from "./write-request.js";
+export { Caller, Credentials, Secrets, RequestSecrets, Budget, Recovery, Signal, Classification, Ledger, openRequest, operationView, deriveView, viewCaller, callView, chargeView, } from "../runtime/call.js";
+/** Permanent write reservations plus resource dispatches, in reservation order. */
+export class Dispatches extends Context.Service()("connecta/http/Dispatches") {
+}
+/** A genuine idempotency key the vendor honors, and the header that carries it, for the call's one write. */
+export const IdempotencyKey = Context.Reference("connecta/http/IdempotencyKey", { defaultValue: () => undefined });
+/** The authored read's review; served classification remains the call's own. */
+export const ReadTool = Context.Reference("connecta/http/ReadTool", {
+    defaultValue: () => undefined,
+});
+/** Closed capacity and the requests bound to bulk items, snapshotted before the program runs. */
+export class WriteCapacity extends Context.Service()("connecta/http/WriteCapacity") {
+}
+/** No await or fiber yield between the check and insertion. Reservations are never released. */
+export function reserveWrite(ledger, capacity, facts) {
+    const step = facts.step ?? "write";
+    if (!capacity.get(step)?.has(facts.item)) {
+        return new RequestRefused({ message: "This write step/item was not declared by the tool for this call." });
+    }
+    const first = ledger.find((entry) => entry.write && entry.step === step && entry.item === facts.item);
+    if (first)
+        return new ResendRefused({ first });
+    const slot = {
+        write: true,
+        step,
+        ...(facts.item === undefined ? {} : { item: facts.item }),
+        ...(facts.operation ? { operation: facts.operation } : {}),
+        state: "reserved",
+    };
+    ledger.push(slot);
+    return slot;
+}
+/**
+ * What one request inside a call is: the call's own effect, or an auxiliary
+ * request inside a write tool, and which logical write. Auxiliary ownership
+ * does not itself prove a physical read. Set by `Send`, read by
+ * the transport and the OAuth middleware. `sent` is filled by the transport
+ * with the request it handed to `fetch`, so `Send` can record that request's
+ * own failure in the ledger.
+ */
+export const RequestFacts = Context.Reference("connecta/http/RequestFacts", { defaultValue: () => ({ effect: "call" }) });
+/** A call's use of renewal ends on close; a submitted claim remains coordinator-owned. */
+export function duringCall(work) {
+    return Signal.use((signal) => {
+        const closed = () => new RequestRefused({ message: "This call has ended; no renewal work may continue." });
+        if (!signal)
+            return work;
+        if (signal.aborted)
+            return Effect.fail(closed());
+        return Effect.raceFirst(work, fromSignal(signal).pipe(Effect.mapError(closed)));
+    });
+}
+export function fromConnectorContext(ctx, fallback) {
+    const lease = callFromContext(ctx, callClassification(ctx) ?? fallback, {
+        ledger: {
+            open: ({ auxiliary, provider, method, key }) => providerRequest(ctx, auxiliary, provider, { method, ...(key === undefined ? {} : { key }) }),
+            dispatch: (entry, headers, method) => dispatchProviderRequest(ctx, entry, headers, method),
+        },
+    });
+    return {
+        ...lease,
+        services: lease.services.pipe(Context.add(ContinuationStorage, serviceFor(ctx, ContinuationStorage) ?? ctx.storage), Context.add(ContinuationBinding, serviceFor(ctx, ContinuationBinding) ?? { connection: "", principal: null }), Context.add(Dispatches, []), Context.add(WriteCapacity, new Map([["write", new Map([[undefined, undefined]])]]))),
+    };
+}
+export function openCall(inputs) {
+    const lease = openCoreCall(inputs);
+    return {
+        ...lease,
+        services: lease.services.pipe(Context.add(Dispatches, []), Context.add(WriteCapacity, new Map([["write", new Map([[undefined, undefined]])]]))),
+    };
+}