@superdurable/connectors-sdk 0.1.1 → 0.3.0

package/dist/chunk-NQQJS6OC.js

@@ -0,0 +1,316 @@
+import {
+  validateMutationDefinition,
+  validateQueryDefinition
+} from "./chunk-32YJXBE4.js";
+import {
+  createCall
+} from "./chunk-QDMBAWXD.js";
+import {
+  CallIDSchema,
+  ConnectionRefSchema,
+  ConnectorConfigurationUISchema,
+  DefectBranchID,
+  OperationRefSchema,
+  ReceiptSchema,
+  UncertainBranchID,
+  defaultConnectorStepExecuteRetryPolicy
+} from "./chunk-BQGYGCOQ.js";
+import {
+  FailureSchema,
+  RetryError
+} from "./chunk-IHG6ADQG.js";
+
+// src/run_operation.ts
+async function runQuery(operation, call, input) {
+  if (!operation) return defectResult(void 0, call, "connector query is required");
+  const definition = operation.definition();
+  try {
+    validateQueryDefinition(definition);
+  } catch (error) {
+    return defectResult(definition, call, `invalid query definition: ${safeErrorMessage(error)}`);
+  }
+  const invalidCall = validateCall(call, definition.operation);
+  if (invalidCall) return defectResult(definition, call, invalidCall);
+  const attempt = await operation.invoke(call, input);
+  return resultFromAttempt(definition, call, attempt, "query");
+}
+async function runMutation(operation, call, input) {
+  if (!operation) return defectResult(void 0, call, "connector mutation is required");
+  const definition = operation.definition();
+  try {
+    validateMutationDefinition(definition);
+  } catch (error) {
+    return defectResult(definition, call, `invalid mutation definition: ${safeErrorMessage(error)}`);
+  }
+  const invalidCall = validateCall(call, definition.operation);
+  if (invalidCall) return defectResult(definition, call, invalidCall);
+  const chosenKey = operation.idempotencyKey(call.id, input) || call.id;
+  if (!chosenKey.trim()) return defectResult(definition, call, "mutation returned an invalid idempotency key");
+  const mutationCall = { ...call, context: call.context, idempotencyKey: chosenKey };
+  Object.defineProperty(mutationCall, "context", { value: call.context, enumerable: false });
+  for (const method of ["reportProgress", "writeText", "hasProgressStream", "hasTextStream"]) Object.defineProperty(mutationCall, method, { value: call[method], enumerable: false });
+  const attempt = await operation.invoke(mutationCall, input);
+  return resultFromAttempt(definition, mutationCall, attempt, "mutation");
+}
+function resultFromAttempt(definition, call, attempt, operationKind) {
+  if (!attempt || typeof attempt !== "object") return defectResult(definition, call, `${operationKind} returned an invalid attempt`);
+  if (attempt.kind === "retry") {
+    const failure = FailureSchema.safeParse(attempt.failure);
+    if (!failure.success || !Number.isSafeInteger(attempt.retryAfterMs) || attempt.retryAfterMs < 0) return defectResult(definition, call, `${operationKind} returned an invalid retry attempt`);
+    throw new RetryError(failure.data, attempt.retryAfterMs);
+  }
+  if (attempt.kind === "branch" || operationKind === "mutation" && attempt.kind === "uncertain") {
+    const branch = attempt.kind === "uncertain" ? UncertainBranchID : attempt.branch;
+    if (!definition.branches.some((declared) => declared.id === branch)) {
+      return defectResult(definition, call, attempt.kind === "uncertain" ? "mutation returned uncertainty without declaring the uncertain branch" : `${operationKind} returned an unknown branch`);
+    }
+    const failure = "failure" in attempt && attempt.failure !== void 0 ? FailureSchema.safeParse(attempt.failure) : void 0;
+    if (failure && !failure.success) return defectResult(definition, call, `${operationKind} returned an invalid failure`);
+    if (attempt.kind === "uncertain" && !failure) return defectResult(definition, call, "mutation returned an invalid uncertainty failure");
+    let receipt;
+    try {
+      receipt = completeReceipt(attempt.receipt, call);
+    } catch (error) {
+      return defectResult(definition, call, safeErrorMessage(error));
+    }
+    const result = { branch, value: attempt.value, receipt };
+    if (failure?.success) result.failure = failure.data;
+    return result;
+  }
+  return defectResult(definition, call, `${operationKind} returned an invalid attempt`);
+}
+function completeReceipt(draft, call) {
+  if (draft.callId && draft.callId !== call.id) throw new TypeError("operation returned a receipt for another call");
+  if (draft.idempotencyKey && draft.idempotencyKey !== call.idempotencyKey) throw new TypeError("operation returned a receipt with another idempotency key");
+  return ReceiptSchema.parse({ ...draft, callId: call.id, ...call.idempotencyKey ? { idempotencyKey: call.idempotencyKey } : {}, provider: draft.provider || call.operation.connectorId, observedAt: draft.observedAt && draft.observedAt !== "0001-01-01T00:00:00Z" ? draft.observedAt : (/* @__PURE__ */ new Date()).toISOString() });
+}
+function validateCall(call, operation) {
+  if (!call) return "connector call is required";
+  if (!CallIDSchema.safeParse(call.id).success) return "call ID must be a UUID";
+  if (!ConnectionRefSchema.safeParse(call.connection).success) return "connection provider and name are required";
+  if (!OperationRefSchema.safeParse(call.operation).success || call.operation.connectorId !== operation.connectorId || call.operation.operationId !== operation.operationId) return "connector call operation does not match the definition";
+  return void 0;
+}
+function defectResult(definition, call, message) {
+  const operation = definition?.operation;
+  const failure = { kind: "LOCAL_DEFECT", provider: operation?.connectorId || "connector", operation: operation?.operationId || "invoke", message };
+  const receipt = call && CallIDSchema.safeParse(call.id).success ? completeReceipt({}, call) : void 0;
+  return { branch: DefectBranchID, value: void 0, receipt, failure };
+}
+function safeErrorMessage(error) {
+  return error instanceof Error ? error.message : "invalid value";
+}
+
+// src/step.ts
+import { StepRef, forceFail, goTo, retryAfter } from "@superdurable/dex";
+function goToBranch(branch, target) {
+  return target ? { branch, target } : { branch };
+}
+function stepRef(stepType) {
+  return new StepRef(stepType);
+}
+var QueryStep = class {
+  inputCodec;
+  #configuration;
+  #options;
+  #ui;
+  #targets;
+  #optional;
+  #identity;
+  /** Validate static wiring before registering the Step in a Flow. */
+  constructor(configuration) {
+    if (!configuration?.operation) throw new TypeError("query operation is required");
+    const definition = configuration.operation.definition();
+    validateQueryDefinition(definition);
+    validateFactoryConfiguration(configuration);
+    const routes = validateBranchTargets(definition.branches, configuration.branches);
+    this.#configuration = configuration;
+    this.#options = mergeStepOptions(definition.stepDefaults, configuration.stepOptionsOverride);
+    this.#ui = ConnectorConfigurationUISchema.parse(configuration.configurationUI ?? { units: [] });
+    this.#targets = routes.targets;
+    this.#optional = routes.optional;
+    this.#identity = { operation: definition.operation, connection: configuration.connection };
+    if (configuration.inputCodec) this.inputCodec = configuration.inputCodec;
+  }
+  /** Stable Dex Step type. */
+  getStepType() {
+    return this.#configuration.stepType;
+  }
+  /** Isolated Execute options, including connector retry defaults. */
+  getStepOptions() {
+    return cloneStepOptions(this.#options);
+  }
+  /** Group metadata for Connector Studio. */
+  annotations() {
+    return { ...this.#configuration.annotations };
+  }
+  /** Isolated connector UI composition. */
+  configurationUI() {
+    return structuredClone(this.#ui);
+  }
+  /** Invoke, persist the optional terminal Attribute, and route the selected branch. */
+  async execute(context, input) {
+    const operationInput = this.#configuration.mapToOperationInput(input);
+    const call = createCall(context, this.#identity.connection, this.#identity.operation, {
+      ...this.#configuration.progressStream ? { progressStream: this.#configuration.progressStream } : {},
+      ...this.#configuration.textStream ? { textStream: this.#configuration.textStream } : {},
+      ...this.#configuration.textOptions ? { textOptions: this.#configuration.textOptions } : {}
+    });
+    let result;
+    try {
+      result = await runQuery(this.#configuration.operation, call, operationInput);
+    } catch (error) {
+      throwDexRetry(error);
+    }
+    if (this.#configuration.resultAttribute) context.setAttribute(this.#configuration.resultAttribute, result);
+    return routeBranch(this.#targets, this.#optional, result, this.#identity, "query");
+  }
+};
+var MutationStep = class {
+  inputCodec;
+  #configuration;
+  #options;
+  #ui;
+  #targets;
+  #optional;
+  #identity;
+  /** Validate static wiring before registering the Step in a Flow. */
+  constructor(configuration) {
+    if (!configuration?.operation) throw new TypeError("mutation operation is required");
+    const definition = configuration.operation.definition();
+    validateMutationDefinition(definition);
+    validateFactoryConfiguration(configuration);
+    const routes = validateBranchTargets(definition.branches, configuration.branches);
+    this.#configuration = configuration;
+    this.#options = mergeStepOptions(definition.stepDefaults, configuration.stepOptionsOverride);
+    this.#ui = ConnectorConfigurationUISchema.parse(configuration.configurationUI ?? { units: [] });
+    this.#targets = routes.targets;
+    this.#optional = routes.optional;
+    this.#identity = { operation: definition.operation, connection: configuration.connection };
+    if (configuration.inputCodec) this.inputCodec = configuration.inputCodec;
+  }
+  /** Stable Dex Step type. */
+  getStepType() {
+    return this.#configuration.stepType;
+  }
+  /** Isolated Execute options, including connector retry defaults. */
+  getStepOptions() {
+    return cloneStepOptions(this.#options);
+  }
+  /** Group metadata for Connector Studio. */
+  annotations() {
+    return { ...this.#configuration.annotations };
+  }
+  /** Isolated connector UI composition. */
+  configurationUI() {
+    return structuredClone(this.#ui);
+  }
+  /** Invoke, persist the optional terminal Attribute, and route the selected branch. */
+  async execute(context, input) {
+    const operationInput = this.#configuration.mapToOperationInput(input);
+    const call = createCall(context, this.#identity.connection, this.#identity.operation, {
+      ...this.#configuration.progressStream ? { progressStream: this.#configuration.progressStream } : {},
+      ...this.#configuration.textStream ? { textStream: this.#configuration.textStream } : {},
+      ...this.#configuration.textOptions ? { textOptions: this.#configuration.textOptions } : {}
+    });
+    let result;
+    try {
+      result = await runMutation(this.#configuration.operation, call, operationInput);
+    } catch (error) {
+      throwDexRetry(error);
+    }
+    if (this.#configuration.resultAttribute) context.setAttribute(this.#configuration.resultAttribute, result);
+    return routeBranch(this.#targets, this.#optional, result, this.#identity, "mutation");
+  }
+};
+function newQueryStep(configuration) {
+  return new QueryStep(configuration);
+}
+function newMutationStep(configuration) {
+  return new MutationStep(configuration);
+}
+function validateFactoryConfiguration(configuration) {
+  if (!configuration.stepType?.trim()) throw new TypeError("stable Step type is required");
+  if (!/^[a-z][a-z0-9-]*$/.test(configuration.annotations?.groupId ?? "") || !configuration.annotations.groupLabel?.trim() || !configuration.annotations.explanation?.trim()) throw new TypeError("Step group, group label, and explanation are required");
+  ConnectionRefSchema.parse(configuration.connection);
+  if (typeof configuration.mapToOperationInput !== "function") throw new TypeError("mapToOperationInput is required");
+}
+function validateBranchTargets(definitions, routes) {
+  const expected = new Map(definitions.map((branch) => [branch.id, branch]));
+  const targets = /* @__PURE__ */ new Map();
+  const optional = new Set(definitions.filter((branch) => branch.optional).map((branch) => branch.id));
+  for (const route of routes) {
+    if (!expected.has(route.branch)) throw new TypeError(`branch target ${route.branch} is not declared by the operation`);
+    if (!route.target) {
+      if (!optional.has(route.branch)) throw new TypeError(`branch target ${route.branch} must name a Step`);
+      continue;
+    }
+    if (route.target instanceof StepRef && !route.target.stepType.trim()) throw new TypeError(`branch target ${route.branch} must name a Step`);
+    if (typeof route.target === "object" && !(route.target instanceof StepRef) && !route.target.getStepType().trim()) throw new TypeError(`branch target ${route.branch} must name a Step`);
+    if (targets.has(route.branch)) throw new TypeError(`branch target ${route.branch} is duplicated`);
+    targets.set(route.branch, route.target);
+  }
+  for (const branch of definitions) if (!branch.optional && !targets.has(branch.id)) throw new TypeError(`branch target ${branch.id} is required`);
+  return { targets, optional };
+}
+function mergeStepOptions(defaults, override) {
+  if (override && Object.keys(override).some((key) => key.startsWith("waitFor") && override[key] !== void 0)) throw new TypeError("execute-only connector Step rejects WaitFor options");
+  const merged = {
+    ...override?.executeMethodTimeoutMs || defaults.executeMethodTimeoutMs ? { executeMethodTimeoutMs: override?.executeMethodTimeoutMs || defaults.executeMethodTimeoutMs } : {},
+    ...override?.heartbeatTimeoutMs || defaults.heartbeatTimeoutMs ? { heartbeatTimeoutMs: override?.heartbeatTimeoutMs || defaults.heartbeatTimeoutMs } : {},
+    executeRetry: { ...override?.executeRetry ?? defaults.executeRetry ?? defaultConnectorStepExecuteRetryPolicy() },
+    ...override?.executeDurability || (defaults.executeDurability !== "default" ? defaults.executeDurability : void 0) ? { executeDurability: override?.executeDurability ?? defaults.executeDurability } : {},
+    ...override?.executeFailure ? { executeFailure: override.executeFailure } : {},
+    ...override?.executeLockAttributes ? { executeLockAttributes: override.executeLockAttributes } : {},
+    ...override?.executeLoadAttributeMaps ? { executeLoadAttributeMaps: override.executeLoadAttributeMaps } : {},
+    ...override?.executeLoadAttributeMapInstances ? { executeLoadAttributeMapInstances: override.executeLoadAttributeMapInstances } : {},
+    ...override?.executeLoadChannels ? { executeLoadChannels: override.executeLoadChannels } : {},
+    ...override?.executeLoadChannelMaps ? { executeLoadChannelMaps: override.executeLoadChannelMaps } : {},
+    ...override?.executeLoadChannelMapInstances ? { executeLoadChannelMapInstances: override.executeLoadChannelMapInstances } : {}
+  };
+  return cloneStepOptions(merged);
+}
+function cloneStepOptions(options) {
+  return {
+    ...options,
+    ...options.executeRetry ? { executeRetry: { ...options.executeRetry } } : {},
+    ...options.executeLockAttributes ? { executeLockAttributes: [...options.executeLockAttributes] } : {},
+    ...options.executeLoadAttributeMaps ? { executeLoadAttributeMaps: [...options.executeLoadAttributeMaps] } : {},
+    ...options.executeLoadAttributeMapInstances ? { executeLoadAttributeMapInstances: [...options.executeLoadAttributeMapInstances] } : {},
+    ...options.executeLoadChannels ? { executeLoadChannels: [...options.executeLoadChannels] } : {},
+    ...options.executeLoadChannelMaps ? { executeLoadChannelMaps: [...options.executeLoadChannelMaps] } : {},
+    ...options.executeLoadChannelMapInstances ? { executeLoadChannelMapInstances: [...options.executeLoadChannelMapInstances] } : {}
+  };
+}
+function routeBranch(targets, optional, result, identity, operationKind) {
+  const target = targets.get(result.branch);
+  if (target) return goTo(target, result);
+  if (optional.has(result.branch)) {
+    let reason = `${identity.operation.connectorId} ${identity.operation.operationId} (connection ${identity.connection.name}) selected branch ${result.branch} with no target`;
+    if (result.failure) reason += `: ${result.failure.kind}: ${boundedFailureMessage(result.failure.message)}`;
+    return forceFail(reason);
+  }
+  throw new TypeError(`${operationKind} result selected unconfigured branch ${result.branch}`);
+}
+function boundedFailureMessage(message) {
+  const bytes = Buffer.from(message);
+  if (bytes.length <= 1024) return message;
+  let end = 1024;
+  while (end > 0 && (bytes[end] & 192) === 128) end--;
+  return `${bytes.subarray(0, end).toString("utf8")} (truncated)`;
+}
+function throwDexRetry(error) {
+  if (error instanceof RetryError && error.retryAfterMs >= 1e3) throw retryAfter(Math.floor(error.retryAfterMs / 1e3), error);
+  throw error;
+}
+
+export {
+  runQuery,
+  runMutation,
+  goToBranch,
+  stepRef,
+  QueryStep,
+  MutationStep,
+  newQueryStep,
+  newMutationStep
+};

package/dist/{chunk-KD5DYYSU.js → chunk-QDMBAWXD.js}

@@ -2,7 +2,7 @@ import {
   ConnectionRefSchema,
   OperationRefSchema,
   deriveCallID
-} from "./chunk-SOXYPIMO.js";
+} from "./chunk-BQGYGCOQ.js";
 
 // src/credentials.ts
 function createCall(context, connection, operation, options = {}) {

package/dist/{chunk-2IDXFKMY.js → chunk-UWB627CI.js}

@@ -43,7 +43,7 @@ function isLinkLocalIPAddressLiteral(hostname) {
 }
 function isAlwaysRefusedIPAddressLiteral(hostname) {
   const address = unbracketHostname(hostname);
-  return address === "0.0.0.0" || address === "::" || address.toLowerCase() === "fd00:ec2::254" || contains(linkLocal, address) || contains(multicast, address);
+  return address === "0.0.0.0" || address === "255.255.255.255" || address === "::" || address.toLowerCase() === "fd00:ec2::254" || contains(linkLocal, address) || contains(multicast, address);
 }
 function isAllowedProviderIPAddress(address, protocol, policy) {
   if (isIP(unbracketHostname(address)) === 0 || isAlwaysRefusedIPAddressLiteral(address)) return false;
@@ -92,6 +92,13 @@ var ProviderTransportError = class extends Error {
   }
   isProvablyNotSent;
 };
+var ProviderStalledError = class extends Error {
+  /** Construct a sanitized no-byte timeout failure. */
+  constructor() {
+    super("provider sent no bytes within the stall timeout");
+    this.name = "ProviderStalledError";
+  }
+};
 function parseRetryAfter(value, now = /* @__PURE__ */ new Date()) {
   const trimmed = value.trim();
   if (/^[0-9]+$/.test(trimmed)) {
@@ -153,7 +160,10 @@ function readErrorTokens(body, pointers) {
 }
 async function sendProviderRequest(request) {
   if (!Number.isSafeInteger(request.maxResponseBytes) || request.maxResponseBytes < 0) throw new RangeError("response body limit must be a non-negative integer");
-  if (request.addressPolicy !== "publicHTTPS" && request.addressPolicy !== "privateNetworkHTTP") throw new AddressRefusal("address policy is invalid");
+  if (request.maxErrorResponseBytes !== void 0 && (!Number.isSafeInteger(request.maxErrorResponseBytes) || request.maxErrorResponseBytes < 0)) throw new RangeError("error body limit must be a non-negative integer");
+  if (request.onBodyLimit !== void 0 && request.onBodyLimit !== "destroy" && request.onBodyLimit !== "drain") throw new TypeError("response body limit action is invalid");
+  if (request.onBodyLimit === "drain" && !(request.timeoutMs && request.timeoutMs > 0) && !(request.stallTimeoutMs && request.stallTimeoutMs > 0) && !request.signal) throw new TypeError("draining requires a timeout or abort signal");
+  if (request.addressPolicy !== "publicHTTPS" && request.addressPolicy !== "privateNetworkHTTP" && request.addressPolicy !== "unrestricted") throw new AddressRefusal("address policy is invalid");
   let parsed;
   try {
     parsed = new URL(request.url);
@@ -172,7 +182,8 @@ async function sendProviderRequest(request) {
   } catch {
     throw new ProviderTransportError(true);
   }
-  if (addresses.length === 0 || addresses.some(({ address }) => !isAllowedProviderIPAddress(address, parsed.protocol, request.addressPolicy))) {
+  const restrictedPolicy = request.addressPolicy === "unrestricted" ? void 0 : request.addressPolicy;
+  if (addresses.length === 0 || restrictedPolicy && addresses.some(({ address }) => !isAllowedProviderIPAddress(address, parsed.protocol, restrictedPolicy))) {
     throw new AddressRefusal("resolved address violates policy");
   }
   const selected = addresses[0];
@@ -186,15 +197,70 @@ async function sendProviderRequest(request) {
   return new Promise((resolve, reject) => {
     let hasConnected = false;
     let hasWrittenRequest = false;
+    let hasReceivedResponse = false;
     let clientRequest;
+    let responseStallTimer;
     try {
       clientRequest = (parsed.protocol === "https:" ? https : http).request(parsed, options, (response) => {
-        void readBoundedBody(response, request.maxResponseBytes).then((body) => {
-          resolve({ status: response.statusCode ?? 0, headers: response.headers, body });
-        }).catch((error) => {
-          response.destroy();
-          reject(error instanceof BodyTooLargeError ? new BodyTooLargeError(response.statusCode ?? 0, response.headers) : new ProviderTransportError(false));
-        });
+        hasReceivedResponse = true;
+        if (responseStallTimer) clearTimeout(responseStallTimer);
+        const chunks = [];
+        let size = 0;
+        let isBodyTooLarge = false;
+        let stallTimer;
+        const observeProgress = () => {
+          if (stallTimer) clearTimeout(stallTimer);
+          if (request.stallTimeoutMs && request.stallTimeoutMs > 0) stallTimer = setTimeout(() => response.destroy(new ProviderStalledError()), request.stallTimeoutMs);
+        };
+        observeProgress();
+        void (async () => {
+          try {
+            for await (const chunk of response) {
+              observeProgress();
+              if (isBodyTooLarge) continue;
+              const isSuccess = (response.statusCode ?? 0) >= 200 && (response.statusCode ?? 0) <= 299;
+              const limit = isSuccess ? request.maxResponseBytes : request.maxErrorResponseBytes ?? request.maxResponseBytes;
+              if (!isSuccess && request.maxErrorResponseBytes !== void 0 && size + chunk.length > limit) {
+                chunks.push(chunk.subarray(0, Math.max(0, limit - size)));
+                response.destroy();
+                resolve({ status: response.statusCode ?? 0, headers: response.headers, body: Buffer.concat(chunks) });
+                return;
+              }
+              if (request.onBodyLimit === "drain" && size + chunk.length > limit) {
+                const remainingBytes = limit - size;
+                isBodyTooLarge = true;
+                chunks.length = 0;
+                if (remainingBytes > 0) request.onResponseChunk?.(chunk.subarray(0, remainingBytes), response.statusCode ?? 0, response.headers);
+                continue;
+              }
+              const shouldContinue = request.onResponseChunk?.(chunk, response.statusCode ?? 0, response.headers);
+              if (shouldContinue === false) {
+                response.destroy();
+                resolve({ status: response.statusCode ?? 0, headers: response.headers, body: Buffer.concat(chunks) });
+                return;
+              }
+              size += chunk.length;
+              if (size > limit) throw new BodyTooLargeError(response.statusCode ?? 0, response.headers);
+              chunks.push(chunk);
+            }
+            if (isBodyTooLarge) {
+              reject(new BodyTooLargeError(response.statusCode ?? 0, response.headers));
+              return;
+            }
+            resolve({ status: response.statusCode ?? 0, headers: response.headers, body: Buffer.concat(chunks) });
+          } catch (error) {
+            response.destroy();
+            if (isBodyTooLarge) {
+              reject(new BodyTooLargeError(response.statusCode ?? 0, response.headers));
+            } else if (request.ignoreErrorBodyReadFailure && ((response.statusCode ?? 0) < 200 || (response.statusCode ?? 0) >= 300)) {
+              resolve({ status: response.statusCode ?? 0, headers: response.headers, body: Buffer.concat(chunks) });
+            } else {
+              reject(error instanceof BodyTooLargeError || error instanceof ProviderStalledError ? error : new ProviderTransportError(false));
+            }
+          } finally {
+            if (stallTimer) clearTimeout(stallTimer);
+          }
+        })();
       });
     } catch {
       reject(new ProviderTransportError(true));
@@ -202,14 +268,18 @@ async function sendProviderRequest(request) {
     }
     clientRequest.on("socket", (socket) => {
       if (!socket.connecting) hasConnected = true;
-      socket.once(parsed.protocol === "https:" ? "secureConnect" : "connect", () => {
+      else socket.once(parsed.protocol === "https:" ? "secureConnect" : "connect", () => {
         hasConnected = true;
       });
     });
     clientRequest.on("finish", () => {
       hasWrittenRequest = true;
     });
-    clientRequest.on("error", () => reject(new ProviderTransportError(!hasConnected && !hasWrittenRequest)));
+    clientRequest.on("error", (error) => {
+      if (responseStallTimer) clearTimeout(responseStallTimer);
+      if (!hasReceivedResponse) reject(error instanceof ProviderStalledError ? error : new ProviderTransportError(!hasConnected && !hasWrittenRequest));
+    });
+    if (request.stallTimeoutMs && request.stallTimeoutMs > 0) responseStallTimer = setTimeout(() => clientRequest.destroy(new ProviderStalledError()), request.stallTimeoutMs);
     try {
       clientRequest.end(request.body);
     } catch {
@@ -242,6 +312,7 @@ export {
   BodyTooLargeError,
   AddressRefusal,
   ProviderTransportError,
+  ProviderStalledError,
   parseRetryAfter,
   validateBaseURL,
   isHeaderSafeCredential,

package/dist/connectormock/index.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { F as Failure, B as BranchID, C as Call, M as MutationAttempt, Q as QueryAttempt, U as UncertainBranchID, a as CallID } from '../credentials-vrvW0d4j.js';
-import { Q as QueryDefinition, M as Mutation, a as MutationDefinition, b as Query } from '../operation-Ca8rfacf.js';
+import { F as Failure, B as BranchID, M as MutationAttempt, Q as QueryAttempt, U as UncertainBranchID, C as CallID } from '../types-D6De3sry.js';
+import { C as Call } from '../credentials-JqG97kJ5.js';
+import { Q as QueryDefinition, M as Mutation, a as MutationDefinition, b as Query } from '../operation-CASLOg86.js';
 import '@superdurable/dex';
 
 /** One answered mock call, including input only in test memory. */

package/dist/connectormock/index.js

@@ -1,10 +1,9 @@
 import {
   validateMutationDefinition,
   validateQueryDefinition
-} from "../chunk-2NBM7P4T.js";
+} from "../chunk-32YJXBE4.js";
 import {
   DefectBranchID,
-  FailureSchema,
   UncertainBranchID,
   newMutationBranch,
   newMutationRetry,
@@ -12,7 +11,10 @@ import {
   newQueryBranch,
   newQueryRetry,
   zeroReceipt
-} from "../chunk-SOXYPIMO.js";
+} from "../chunk-BQGYGCOQ.js";
+import {
+  FailureSchema
+} from "../chunk-IHG6ADQG.js";
 
 // src/connectormock/index.ts
 import { readFile } from "fs/promises";

package/dist/credentials-JqG97kJ5.d.ts

@@ -0,0 +1,102 @@
+import { C as CallID, d as ConnectionRef, O as OperationRef } from './types-D6De3sry.js';
+import { AsyncContext, Stream, BufferedTextStreamOptions } from '@superdurable/dex';
+
+/** Provider-safe progress before Dex identity and sequence are added. */
+interface Progress {
+    /** Provider-specific stable phase. */ phase: string;
+    /** Optional safe progress text. */ message?: string;
+    /** Optional inclusive fraction from zero to one. */ percent?: number;
+    /** Optional provider-owned monotonic sequence. */ providerSequence?: number;
+}
+/** Structured best-effort Dex Stream message. */
+interface ProgressUpdate extends Progress {
+    /** Stable connector call ID. */ callId: CallID;
+    /** One-based Dex Execute attempt. */ attempt: number;
+    /** Connector-assigned monotonic sequence within this attempt. */ sequence: number;
+}
+/** Optional application-owned Streams for one connector invocation. */
+interface CallProgressOptions {
+    /** Registered structured progress Stream. */ progressStream?: Stream<ProgressUpdate>;
+    /** Registered string Stream for ordered buffered text. */ textStream?: Stream<string>;
+    /** Flush interval and soft UTF-8 batch limit for text. */ textOptions?: BufferedTextStreamOptions;
+}
+/** Provider-safe call metadata with its live, non-serializable Dex Step context. */
+interface Call {
+    /** Active Dex Execute context; Step factories attach it as a non-enumerable field. */ context: AsyncContext;
+    /** Stable identity across retries. */ id: CallID;
+    /** Provider deduplication key, when available. */ idempotencyKey?: string;
+    /** Logical named connection. */ connection: ConnectionRef;
+    /** Manifest operation identity. */ operation: OperationRef;
+    /** Append structured progress when a Stream is configured. */ reportProgress(progress: Progress): void;
+    /** Append text in order when a buffered Stream is configured. */ writeText(value: string): void;
+    /** Whether structured progress output is configured. */ hasProgressStream(): boolean;
+    /** Whether buffered text output is configured. */ hasTextStream(): boolean;
+}
+/** Bind a live Dex Execute context to a stable, provider-safe call identity. */
+declare function createCall(context: AsyncContext, connection: ConnectionRef, operation: OperationRef, options?: CallProgressOptions): Call;
+/** Resolve a credential at call time outside durable Flow state. */
+interface CredentialProvider<C> {
+    /** Return current credentials, honoring cancellation. */
+    resolve(call: Call, signal?: AbortSignal): Promise<C>;
+}
+/** Resolve credentials outside a Dex Step, such as for a Trigger source. */
+interface ContextCredentialProvider<C> extends CredentialProvider<C> {
+    /** Return current credentials under an explicit cancellation signal. */
+    resolveContext(call: Call, signal: AbortSignal): Promise<C>;
+}
+/** Current private material and decision time for a refresh driver. */
+interface CredentialRefreshState<C> {
+    /** Current connector-specific credential. */ credentials: C;
+    /** Known access credential expiry. */ expiresAt?: Date;
+    /** Captured decision time. */ now: Date;
+}
+/** Complete replacement credential and mandatory access expiry. */
+interface CredentialRefreshResult<C> {
+    /** Complete replacement, retaining omitted renewal material. */ credentials: C;
+    /** Replacement access expiry. */ expiresAt: Date;
+}
+/** Connector-specific provider refresh contract; persistence belongs to the host. */
+interface CredentialRefreshDriver<C> {
+    /** Decide deterministically whether a credential needs provider renewal. */
+    refreshRequired(state: CredentialRefreshState<C>): boolean;
+    /** Make one provider refresh request after the host admits it durably. */
+    refresh(state: CredentialRefreshState<C>, signal: AbortSignal): Promise<CredentialRefreshResult<C>>;
+}
+/** Host adapter that refreshes and persists a connection atomically. */
+interface RefreshingCredentialProvider<C> extends CredentialProvider<C> {
+    /** Serialize refresh for one connection, reload state, and persist replacement. */
+    resolveWithRefresh(call: Call, driver: CredentialRefreshDriver<C>, signal?: AbortSignal): Promise<C>;
+}
+/** Host adapter for one explicit provider authentication rejection. */
+interface RejectedCredentialRefreshingProvider<C> {
+    /** Force one coordinated refresh after the provider rejects an access token. */
+    resolveAfterRejection(call: Call, driver: CredentialRefreshDriver<C>, signal?: AbortSignal): Promise<C>;
+}
+/** Resolve through host refresh support, then context-aware or ordinary lookup. */
+declare function resolveCredential<C>(provider: CredentialProvider<C>, call: Call, driver: CredentialRefreshDriver<C>, signal?: AbortSignal): Promise<C>;
+/** Force one coordinated refresh after a provider authentication rejection. */
+declare function resolveCredentialAfterRejection<C>(provider: CredentialProvider<C>, call: Call, driver: CredentialRefreshDriver<C>, signal?: AbortSignal): Promise<C>;
+/** In-memory named credentials for examples and tests; never persisted by this class. */
+declare class StaticCredentialProvider<C> implements RefreshingCredentialProvider<C> {
+    #private;
+    /** Capture all connection values during construction. */
+    constructor(entries: Iterable<readonly [ConnectionRef, C]>);
+    /** Return the configured credential or reject a missing connection. */
+    resolve(call: Call): Promise<C>;
+    /** Static credentials never expire and therefore do not call the driver. */
+    resolveWithRefresh(call: Call): Promise<C>;
+}
+/** Wrap a secret that cannot be serialized or printed. */
+declare class SecretString {
+    #private;
+    /** Hold one private value outside default stringification and inspection. */
+    constructor(value: string);
+    /** Reveal only at the provider request boundary. */
+    reveal(): string;
+    /** Return a fixed redaction for accidental string formatting. */
+    toString(): string;
+    /** Reject accidental JSON persistence. */
+    toJSON(): never;
+}
+
+export { type Call as C, type ProgressUpdate as P, type RefreshingCredentialProvider as R, SecretString as S, type CallProgressOptions as a, type ContextCredentialProvider as b, type CredentialProvider as c, type CredentialRefreshDriver as d, type CredentialRefreshResult as e, type CredentialRefreshState as f, type Progress as g, type RejectedCredentialRefreshingProvider as h, StaticCredentialProvider as i, createCall as j, resolveCredentialAfterRejection as k, resolveCredential as r };

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { C as Call, b as MutationResult, c as QueryResult, d as ConnectorConfigurationUI, e as ConnectionRef, P as ProgressUpdate } from './credentials-vrvW0d4j.js';
-export { f as BranchDefinition, g as BranchDefinitionSchema, B as BranchID, a as CallID, h as CallIDNamespace, i as CallIDSchema, j as CallProgressOptions, k as ConnectionRefSchema, l as ConnectorConfigurationRef, m as ConnectorConfigurationRefSchema, n as ConnectorConfigurationUISchema, o as ConnectorUIBinding, p as ConnectorUIBindingSchema, q as ConnectorUIUnit, r as ConnectorUIUnitSchema, s as ContextCredentialProvider, t as CredentialProvider, u as CredentialRefreshDriver, v as CredentialRefreshResult, w as CredentialRefreshState, D as DefectBranchID, F as Failure, x as FailureKind, y as FailureKindSchema, z as FailureSchema, I as IdempotencyKey, M as MutationAttempt, A as MutationDefinitionWire, E as MutationDefinitionWireSchema, G as MutationResultSchema, O as OperationRef, H as OperationRefSchema, J as Progress, Q as QueryAttempt, K as QueryDefinitionWire, L as QueryDefinitionWireSchema, N as QueryResultSchema, R as ReauthorizationRequiredError, S as Receipt, T as ReceiptDraft, V as ReceiptSchema, W as RefreshingCredentialProvider, X as RejectedCredentialRefreshingProvider, Y as RetryError, Z as RetryPolicy, _ as SecretString, $ as StaticCredentialProvider, a0 as StepDefaultsWire, a1 as StepDefaultsWireSchema, U as UncertainBranchID, a2 as createCall, a3 as defaultConnectorStepExecuteRetryPolicy, a4 as defaultIdempotencyKey, a5 as deriveCallID, a6 as newMutationBranch, a7 as newMutationRetry, a8 as newMutationUncertain, a9 as newQueryBranch, aa as newQueryRetry, ab as resolveCredential, ac as resolveCredentialAfterRejection, ad as retryPolicyToGoWire, ae as zeroReceipt } from './credentials-vrvW0d4j.js';
-import { M as Mutation, b as Query } from './operation-Ca8rfacf.js';
-export { a as MutationDefinition, Q as QueryDefinition, S as StepDefaults, v as validateMutationDefinition, c as validateQueryDefinition } from './operation-Ca8rfacf.js';
+import { a as MutationResult, b as QueryResult, c as ConnectorConfigurationUI, d as ConnectionRef } from './types-D6De3sry.js';
+export { e as BranchDefinition, f as BranchDefinitionSchema, B as BranchID, C as CallID, g as CallIDNamespace, h as CallIDSchema, i as ConnectionRefSchema, j as ConnectorConfigurationRef, k as ConnectorConfigurationRefSchema, l as ConnectorConfigurationUISchema, m as ConnectorUIBinding, n as ConnectorUIBindingSchema, o as ConnectorUIUnit, p as ConnectorUIUnitSchema, D as DefectBranchID, F as Failure, q as FailureKind, r as FailureKindSchema, s as FailureSchema, I as IdempotencyKey, M as MutationAttempt, t as MutationDefinitionWire, u as MutationDefinitionWireSchema, v as MutationResultSchema, O as OperationRef, w as OperationRefSchema, Q as QueryAttempt, x as QueryDefinitionWire, y as QueryDefinitionWireSchema, z as QueryResultSchema, R as ReauthorizationRequiredError, A as Receipt, E as ReceiptDraft, G as ReceiptSchema, H as RetryError, J as RetryPolicy, S as StepDefaultsWire, K as StepDefaultsWireSchema, U as UncertainBranchID, L as defaultConnectorStepExecuteRetryPolicy, N as defaultIdempotencyKey, P as deriveCallID, T as newMutationBranch, V as newMutationRetry, W as newMutationUncertain, X as newQueryBranch, Y as newQueryRetry, Z as retryPolicyToGoWire, _ as zeroReceipt } from './types-D6De3sry.js';
+import { C as Call, P as ProgressUpdate } from './credentials-JqG97kJ5.js';
+export { a as CallProgressOptions, b as ContextCredentialProvider, c as CredentialProvider, d as CredentialRefreshDriver, e as CredentialRefreshResult, f as CredentialRefreshState, g as Progress, R as RefreshingCredentialProvider, h as RejectedCredentialRefreshingProvider, S as SecretString, i as StaticCredentialProvider, j as createCall, r as resolveCredential, k as resolveCredentialAfterRejection } from './credentials-JqG97kJ5.js';
+import { M as Mutation, b as Query } from './operation-CASLOg86.js';
+export { a as MutationDefinition, Q as QueryDefinition, S as StepDefaults, v as validateMutationDefinition, c as validateQueryDefinition } from './operation-CASLOg86.js';
 import { StepTarget, Step, Codec, Attribute, Stream, BufferedTextStreamOptions, StepOptions, AsyncContext, StepDecision, StepRef } from '@superdurable/dex';
 import 'zod';