@superdurable/connectors-sdk 0.1.1 → 0.2.0

package/dist/{chunk-SOXYPIMO.js → chunk-BQGYGCOQ.js}

@@ -1,48 +1,14 @@
-// src/errors.ts
-import { z } from "zod";
-var FailureKindSchema = z.enum([
-  "VALIDATION",
-  "AUTHENTICATION",
-  "AUTHORIZATION",
-  "NOT_FOUND",
-  "CONFLICT",
-  "RATE_LIMIT",
-  "QUOTA_EXHAUSTED",
-  "AVAILABILITY",
-  "PROVIDER_REJECTION",
-  "TRANSPORT",
-  "RESPONSE_TOO_LARGE",
-  "PROTOCOL",
-  "LOCAL_DEFECT"
-]);
-var FailureSchema = z.strictObject({ kind: FailureKindSchema, provider: z.string().min(1), operation: z.string().min(1), message: z.string().min(1) });
-var RetryError = class extends Error {
-  /** Validated provider fact behind the retry request. */
-  failure;
-  /** Provider-requested retry delay in milliseconds; zero uses the Step policy. */
-  retryAfterMs;
-  constructor(failure, retryAfterMs = 0) {
-    const validated = FailureSchema.parse(failure);
-    super(`connector ${validated.provider} ${validated.operation} retry (${validated.kind}): ${validated.message}`);
-    this.name = "RetryError";
-    this.failure = validated;
-    this.retryAfterMs = retryAfterMs;
-  }
-};
-var ReauthorizationRequiredError = class extends Error {
-  constructor() {
-    super("connector reauthorization is required");
-    this.name = "ReauthorizationRequiredError";
-  }
-};
+import {
+  FailureSchema
+} from "./chunk-IHG6ADQG.js";
 
 // src/types.ts
-import { z as z2 } from "zod";
+import { z } from "zod";
 import { createHash } from "crypto";
-var CallIDSchema = z2.uuid();
+var CallIDSchema = z.uuid();
 var CallIDNamespace = "63281a42-70ad-5bc3-a289-728819af723f";
-var ConnectionRefSchema = z2.strictObject({ provider: z2.string().refine((value) => value.trim().length > 0), name: z2.string().refine((value) => value.trim().length > 0) });
-var OperationRefSchema = z2.strictObject({ connectorId: z2.string().regex(/^[a-z][a-z0-9-]{1,62}$/), operationId: z2.string().regex(/^[a-z][A-Za-z0-9]+$/) });
+var ConnectionRefSchema = z.strictObject({ provider: z.string().refine((value) => value.trim().length > 0), name: z.string().refine((value) => value.trim().length > 0) });
+var OperationRefSchema = z.strictObject({ connectorId: z.string().regex(/^[a-z][a-z0-9-]{1,62}$/), operationId: z.string().regex(/^[a-z][A-Za-z0-9]+$/) });
 function deriveCallID(flowId, stepExecutionId, operation) {
   OperationRefSchema.parse(operation);
   const namespace = CallIDNamespace;
@@ -68,28 +34,28 @@ function uuidSHA1(namespace, name) {
 }
 var DefectBranchID = "defect";
 var UncertainBranchID = "uncertain";
-var BranchDefinitionSchema = z2.strictObject({ id: z2.string().min(1), description: z2.string(), optional: z2.boolean().optional() });
-var StepDefaultsWireSchema = z2.strictObject({
-  executeMethodTimeout: z2.number().int().nonnegative(),
-  heartbeatTimeout: z2.number().int().nonnegative().optional(),
-  executeRetry: z2.strictObject({ InitialInterval: z2.number().int().nonnegative(), BackoffCoefficient: z2.number().positive(), MaximumInterval: z2.number().int().nonnegative(), MaximumAttempts: z2.number().int().nonnegative(), TotalDuration: z2.number().int().nonnegative() }).optional(),
-  executeDurability: z2.number().int()
+var BranchDefinitionSchema = z.strictObject({ id: z.string().min(1), description: z.string(), optional: z.boolean().optional() });
+var StepDefaultsWireSchema = z.strictObject({
+  executeMethodTimeout: z.number().int().nonnegative(),
+  heartbeatTimeout: z.number().int().nonnegative().optional(),
+  executeRetry: z.strictObject({ InitialInterval: z.number().int().nonnegative(), BackoffCoefficient: z.number().positive(), MaximumInterval: z.number().int().nonnegative(), MaximumAttempts: z.number().int().nonnegative(), TotalDuration: z.number().int().nonnegative() }).optional(),
+  executeDurability: z.number().int()
 });
-var QueryDefinitionWireSchema = z2.strictObject({ operation: OperationRefSchema, branches: z2.array(BranchDefinitionSchema).nullable(), stepDefaults: StepDefaultsWireSchema });
+var QueryDefinitionWireSchema = z.strictObject({ operation: OperationRefSchema, branches: z.array(BranchDefinitionSchema).nullable(), stepDefaults: StepDefaultsWireSchema });
 var MutationDefinitionWireSchema = QueryDefinitionWireSchema;
-var ReceiptSchema = z2.strictObject({
+var ReceiptSchema = z.strictObject({
   callId: CallIDSchema,
-  idempotencyKey: z2.string().optional(),
-  provider: z2.string().min(1),
-  providerObjectId: z2.string().optional(),
-  providerRequestId: z2.string().optional(),
-  observedAt: z2.iso.datetime({ offset: true }),
-  metadata: z2.record(z2.string(), z2.string()).optional()
+  idempotencyKey: z.string().optional(),
+  provider: z.string().min(1),
+  providerObjectId: z.string().optional(),
+  providerRequestId: z.string().optional(),
+  observedAt: z.iso.datetime({ offset: true }),
+  metadata: z.record(z.string(), z.string()).optional()
 });
 function zeroReceipt() {
   return { callId: "", provider: "", observedAt: "0001-01-01T00:00:00Z" };
 }
-var QueryResultSchema = (valueSchema) => z2.strictObject({ branch: z2.string().min(1), value: valueSchema, receipt: ReceiptSchema, failure: FailureSchema.optional() });
+var QueryResultSchema = (valueSchema) => z.strictObject({ branch: z.string().min(1), value: valueSchema, receipt: ReceiptSchema, failure: FailureSchema.optional() });
 var MutationResultSchema = QueryResultSchema;
 function newQueryBranch(branch, value, receipt = {}, failure) {
   return failure === void 0 ? { kind: "branch", branch, value, receipt } : { kind: "branch", branch, value, receipt, failure };
@@ -119,36 +85,32 @@ function retryPolicyToGoWire(policy) {
     TotalDuration: policy.totalDurationMs * 1e6
   };
 }
-var ConnectorUIBindingSchema = z2.strictObject({ port: z2.string().regex(/^[a-z][A-Za-z0-9]*$/), jsonPointer: z2.string().regex(/^\/(?:[^~]|~[01])*$/) });
-var ConnectorUIUnitSchema = z2.strictObject({
-  id: z2.string().regex(/^[a-z][A-Za-z0-9]*$/),
-  unitId: z2.string().regex(/^[a-z][A-Za-z0-9]*$/),
-  label: z2.string().refine((value) => value.trim().length > 0),
-  description: z2.string().refine((value) => value.trim().length > 0),
-  required: z2.boolean(),
-  bindings: z2.array(ConnectorUIBindingSchema).min(1)
+var ConnectorUIBindingSchema = z.strictObject({ port: z.string().regex(/^[a-z][A-Za-z0-9]*$/), jsonPointer: z.string().regex(/^\/(?:[^~]|~[01])*$/) });
+var ConnectorUIUnitSchema = z.strictObject({
+  id: z.string().regex(/^[a-z][A-Za-z0-9]*$/),
+  unitId: z.string().regex(/^[a-z][A-Za-z0-9]*$/),
+  label: z.string().refine((value) => value.trim().length > 0),
+  description: z.string().refine((value) => value.trim().length > 0),
+  required: z.boolean(),
+  bindings: z.array(ConnectorUIBindingSchema).min(1)
 }).superRefine((unit, context) => {
   if (new Set(unit.bindings.map((binding) => binding.port)).size !== unit.bindings.length) context.addIssue({ code: "custom", message: "duplicate UI port" });
 });
-var ConnectorConfigurationUISchema = z2.strictObject({ units: z2.array(ConnectorUIUnitSchema) }).superRefine((ui, context) => {
+var ConnectorConfigurationUISchema = z.strictObject({ units: z.array(ConnectorUIUnitSchema) }).superRefine((ui, context) => {
   if (new Set(ui.units.map((unit) => unit.id)).size !== ui.units.length) context.addIssue({ code: "custom", message: "duplicate UI unit ID" });
 });
-var ConnectorConfigurationRefSchema = z2.strictObject({
+var ConnectorConfigurationRefSchema = z.strictObject({
   connectorId: OperationRefSchema.shape.connectorId,
-  connectionName: z2.string().refine((value) => value.trim().length > 0),
+  connectionName: z.string().refine((value) => value.trim().length > 0),
   operationId: OperationRefSchema.shape.operationId,
-  flowType: z2.string().refine((value) => value.trim().length > 0),
-  stepType: z2.string().refine((value) => value.trim().length > 0)
+  flowType: z.string().refine((value) => value.trim().length > 0),
+  stepType: z.string().refine((value) => value.trim().length > 0)
 });
 function validateRetryDelay(delayMs) {
   if (!Number.isSafeInteger(delayMs) || delayMs < 0) throw new RangeError("retry delay must be a non-negative integer in milliseconds");
 }
 
 export {
-  FailureKindSchema,
-  FailureSchema,
-  RetryError,
-  ReauthorizationRequiredError,
   CallIDSchema,
   CallIDNamespace,
   ConnectionRefSchema,

package/dist/chunk-IHG6ADQG.js

@@ -0,0 +1,44 @@
+// src/errors.ts
+import { z } from "zod";
+var FailureKindSchema = z.enum([
+  "VALIDATION",
+  "AUTHENTICATION",
+  "AUTHORIZATION",
+  "NOT_FOUND",
+  "CONFLICT",
+  "RATE_LIMIT",
+  "QUOTA_EXHAUSTED",
+  "AVAILABILITY",
+  "PROVIDER_REJECTION",
+  "TRANSPORT",
+  "RESPONSE_TOO_LARGE",
+  "PROTOCOL",
+  "LOCAL_DEFECT"
+]);
+var FailureSchema = z.strictObject({ kind: FailureKindSchema, provider: z.string().min(1), operation: z.string().min(1), message: z.string().min(1) });
+var RetryError = class extends Error {
+  /** Validated provider fact behind the retry request. */
+  failure;
+  /** Provider-requested retry delay in milliseconds; zero uses the Step policy. */
+  retryAfterMs;
+  constructor(failure, retryAfterMs = 0) {
+    const validated = FailureSchema.parse(failure);
+    super(`connector ${validated.provider} ${validated.operation} retry (${validated.kind}): ${validated.message}`);
+    this.name = "RetryError";
+    this.failure = validated;
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var ReauthorizationRequiredError = class extends Error {
+  constructor() {
+    super("connector reauthorization is required");
+    this.name = "ReauthorizationRequiredError";
+  }
+};
+
+export {
+  FailureKindSchema,
+  FailureSchema,
+  RetryError,
+  ReauthorizationRequiredError
+};

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/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 };