@superdurable/connectors-sdk 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Connector TypeScript SDK
 
-`@superdurable/connectors-sdk` is the provider-neutral TypeScript SDK for Dex connectors. It provides stable value contracts, typed Query and Mutation operations, Dex Step factories, credential refresh, OAuth token exchanges, HTTP safety helpers, project configuration loading, scripted mocks, and single-dispatch marker decisions. The package is at version `0.1.1`, requires Node 22 or 24, and uses `@superdurable/dex` 1.28.0 or newer. It is ESM-only, matching Dex: use `import`; direct `require()` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+`@superdurable/connectors-sdk` is the provider-neutral TypeScript SDK for Dex connectors. It provides stable value contracts, typed Query and Mutation operations, Dex Step factories, credential refresh, OAuth token exchanges, HTTP safety helpers, project configuration loading, scripted mocks, and single-dispatch marker decisions. The package is at version `0.3.0`, requires Node 22 or 24, and uses `@superdurable/dex` 1.28.0 or newer. It is ESM-only, matching Dex: use `import`; direct `require()` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
 
 Install dependencies and verify the package from this directory:
 
@@ -17,14 +17,32 @@ node examples/refreshing_project.mjs
 node examples/shared_project.mjs
 node examples/connectormock.mjs
 node examples/oauthtoken.mjs
+node examples/manifest_refresh.mjs
 node examples/singledispatch.mjs
 node examples/fence.mjs
+node examples/textgen.mjs
 ```
 
 All durations in this package are milliseconds. Public JSON shapes use the Go SDK's field names. Credential values and project objects stay outside Flow state and cannot be serialized through their wrappers.
 
 The [Dex integration harness](test/integ/step_flows.mjs) exercises the same Step factories through a real Worker and Client. Start `dexcli dev --open=false --dex-port 18891` with a local Dex server, set `DEX_SERVER_ADDRESS` when its gRPC address differs from `127.0.0.1:18891`, and run `npm run test:integration`. It verifies a happy path, optional branch, unwired optional branch failure, retry then success, retry exhaustion, uncertain mutation, a lost-response single-dispatch fence, repeated claim heartbeats, result Attribute persistence, progress and text Stream delivery, and scripted mock replay. It uses fixture operations and no provider credentials. CI runs the same harness in `sdkts-integration` using its once-per-run resolved Dex CLI.
 
+## Portable text generation
+
+The [runnable text generation example](examples/textgen.mjs) uses `newTextGenerationQuery` with the OpenAI-compatible Chat Completions adapter from `@superdurable/connectors-sdk/textgen/openaichat`. The `@superdurable/connectors-sdk/textgen` entrypoint also exports request and response contracts, model ID validation, portable schema checks, branch definitions, temperature policies, error rules, and the provider-neutral wire-format contract. The example exercises a local fixture provider; a consuming connector supplies a real connection, credential resolver, and Dex Step.
+
+`generateText` requires sync Execute durability and a request timeout shorter than the Step Execute timeout. It writes streamed text deltas to a configured text Stream as bytes arrive; the Result text is authoritative after retries or a blocked response. Register that Stream in the Flow persistence schema. Its six branches are `generated`, `truncated`, `blocked`, `providerRejected`, `invalidResponse`, and `defect`; only `generated` is required. The query retries transport errors, stalled responses, interrupted streams, and safe HTTP failures. A credential is resolved once after local validation and is never stored in Flow state, results, failures, or receipts.
+
+Each invocation resolves the trimmed request model or connection model, then validates messages, the token limit, the structured-output name and schema, declared features, temperature, and reasoning effort in that order. It applies model schema rules, resolves one credential, and encodes the request before dispatch. The first error in this order selects `defect` with zero provider requests. A nil heartbeat every five seconds keeps a silent call alive and clears any Step heartbeat checkpoint. Stream text may contain text from an attempt later retried or blocked, so consumers use the final Result for decisions. A caller may inject `httpClient` to own HTTP transport as in Go; the default transport permits private HTTPS endpoints and neither transport should replay redirects.
+
+An injected HTTP client may return a complete SSE response body without calling `onResponseChunk`. If it calls `onResponseChunk`, it must feed every chunk in order before returning and stop when the callback returns `false`. A provider retry-delay reader that throws or returns a non-finite value is treated as absent, allowing the `Retry-After` header to supply the delay. Usage token counts are JavaScript numbers and require safe integers; unlike Go's `int64` counts, larger values are rejected because they cannot be represented exactly in the public TypeScript `Usage` contract.
+
+The schema subset is the same as Go `sdkgo/textgen`: root object, closed objects with every property required, nullable optional values, arrays with `items`, and only the documented portable keywords. Structured output is checked locally even when the provider accepts a transformed schema. Model IDs are validated according to whether the adapter sends them in a JSON body or path segment. Optional request fields rejected by a wire format or selected model produce a `defect` branch before dispatch.
+
+Exact structured-output numbers may use at most 256 literal characters and an exponent magnitude of at most 400. Date and time formats follow Go's parser, including calendar-valid dates, one-digit hours, comma fractions, and offsets through hour 24 and minute 60. The JSON-object instruction uses Go's sorted, HTML-safe JSON encoding so provider requests match the Go connector. The shared [string-format fixture](../sdkgo/textgen/textgentest/testdata/string_format_cases.json) runs in both Go and TypeScript tests.
+
+The `@superdurable/connectors-sdk/textgen/textgentest` entrypoint ports Go's credential-safe fake provider and reusable exchange suite. [Its provider-dialect test](test/textgentest.test.ts) exercises model precedence, all common branches, error rules, complete and interrupted streams, usage, receipts, and credential redaction. The [Dex integration harness](test/integ/step_flows.mjs) calls `runTextGenerationDexScenarios` through a real Worker and Client to verify retry, heartbeat, text Stream persistence, and an unwired optional branch.
+
 ## Typed operations and credential resolution
 
 The [runnable operation example](examples/operations.mjs) validates a Query definition, binds a live Step context to stable call identity, resolves credentials at invocation time, and completes a Go-compatible zero receipt. `Mutation` adds an idempotency-key method and may return `newMutationUncertain` only for a dispatched write that cannot be repeated or confirmed by read-back. `runQuery` and `runMutation` throw `RetryError` for a safe retry; a Step factory turns that into Dex retry behavior. The example uses a test context; application Steps receive `AsyncContext` from Dex.
@@ -101,6 +119,7 @@ if (result.kind !== 'branch' || retryPolicy.totalDurationMs !== 3600000 || crede
 
 The [complete runnable HTTP example](examples/providerhttp.mjs) sends one bounded request to a local server. `sendProviderRequest` resolves every address before connecting, pins the chosen address for IP literals and hostnames, and returns redirects without following them. `ProviderTransportError.isProvablyNotSent` is true for DNS, TCP connect, or TLS handshake failures before a usable connection could send HTTP bytes. Failures after connection or request writing have an unknown dispatch outcome, matching the Go connectors' DNS, connect, TLS, and obtained-connection trace.
 `BodyTooLargeError` preserves the response `status` and `headers`, so a caller can classify a 429 or 503 and its `Retry-After` even when the response body exceeds its limit.
+`ProviderRequest.onBodyLimit` defaults to `destroy`, closing an oversized response immediately. Set it to `drain` for provider calls that continue or bill work after a client disconnect: the SDK releases buffered bytes, delivers callback bytes only through the limit, reads to EOF, then rejects with `BodyTooLargeError`. Drain requires at least one positive `timeoutMs`, positive `stallTimeoutMs`, or `signal`; otherwise `sendProviderRequest` throws `TypeError`. These bounds remain active while draining. For non-2xx responses, an explicit `maxErrorResponseBytes` takes precedence and truncates the body immediately instead of draining. Once drain begins, a later read failure still rejects with `BodyTooLargeError`, including when `ignoreErrorBodyReadFailure` is set. The runnable example exercises `drain` with a local server.
 
 ```js
 import { createServer } from 'node:http';
@@ -212,7 +231,9 @@ mutation.assertNoFailures();
 
 ## OAuth token refresh
 
-The [runnable OAuth exchange example](examples/oauthtoken.mjs) shows a provider-neutral refresh-token grant. The injected `fetch` returns a local fixture; a connector normally uses the provider's fixed HTTPS token endpoint. `TokenEndpoint` also supports client-credentials and JWT-bearer grants, optional Basic authentication, declared response fields, bounded responses, and terminal OAuth error-code classification. A connector-specific `CredentialRefreshDriver` owns the credential shape; the host owns serialized persistence and must keep an old refresh token when the provider omits a replacement.
+The [runnable OAuth exchange example](examples/oauthtoken.mjs) shows a provider-neutral refresh-token grant. The injected `fetch` returns a local fixture; a connector normally uses the provider's fixed HTTPS token endpoint. `TokenEndpoint` also supports client-credentials and JWT-bearer grants, optional Basic authentication, declared response fields, bounded responses, and terminal OAuth error-code classification. The [manifest refresh example](examples/manifest_refresh.mjs) uses `ManifestCredentialRefreshDriver` with a generated authorization declaration and field map to exchange refresh-token, client-credentials, or JWT-bearer grants, preserve rotated material, check scopes, and replace only mapped fields. Constructor options also accept startup-pinned `settings`, a caller-owned `fetch`, and an injectable `now` clock. Credentials for a connector with several authorization methods use `authMethodId`; an empty value selects `defaultMethod`. Refresh validation uses `requiredScopes` when declared, and a grant can override `exactScopes` or `acceptsMissingTokenType`. `refresh.scopeSeparators` selects `whitespace` (the default) or `whitespaceAndComma` for both exact and all-scope checks. A blank client secret requires reauthorization unless `refresh.allowsPublicClient` is true. A response lacking `expires_in` is retryable unless the manifest declares `missingExpiry`. Only declared terminal OAuth errors below HTTP 500 require reauthorization; transport, server, and other token errors remain retryable.
+
+An access token with no stored expiry remains usable; the current project provider requires authoritative expiry before forcing refresh after a provider rejection. A response without `expires_in` uses the manifest's `missingExpiry` lifetime or returns an expired result for `keep`. The current project provider rejects that result without changing stored material. Refreshing multiple grants follows the Go driver's current single-expiry behavior: active grants rotate together and the earliest expiry wins. A process failure between provider response and persistence, or failure of a later grant after an earlier rotation, can lose a one-use refresh token.
 
 ```js
 import { SecretString } from '../dist/index.js';
@@ -260,6 +281,16 @@ await fence.recordProviderId(result.providerId);
 
 ## Release notes
 
+### 0.3.0
+
+Adds declaration-driven required and exact scope checks, per-grant token-type rules, Go-compatible duration validation, and default-method selection for manifest refresh drivers. Scope parsing now follows `scopeSeparators`: whitespace by default, or spaces and commas when declared. A blank client secret now requires reauthorization unless public-client refresh is declared. A missing `expires_in` is retryable unless the manifest declares `missingExpiry`. These changes alter the published 0.2.0 refresh driver's behavior.
+
+Public HTTPS address checks now refuse the IPv4 broadcast address, matching Go's global-unicast rule. Adds opt-in draining of oversized Provider HTTP responses with bounded cancellation and byte-exact chunk callbacks.
+
+### 0.2.0
+
+Adds manifest-driven refresh for OAuth, client-credentials, and JWT bearer grants, including rotated refresh tokens, declared scope and token-type checks, and retryable token endpoint failures. Connector migration requires schema and codegen support for the new token-type declarations.
+
 ### 0.1.0
 
 First public ESM-only TypeScript Connector SDK release: Go-compatible contracts and conformance fixtures, safe provider HTTP, project configuration with durable credential refresh and guarded local writeback, typed operations and Dex Step factories, OAuth exchanges, scripted mocks, and the live single-dispatch fence. No live provider authorization has been tested.

package/dist/{chunk-2NBM7P4T.js → chunk-32YJXBE4.js}

@@ -2,7 +2,7 @@ import {
   DefectBranchID,
   OperationRefSchema,
   UncertainBranchID
-} from "./chunk-SOXYPIMO.js";
+} from "./chunk-BQGYGCOQ.js";
 
 // src/operation.ts
 function validateQueryDefinition(definition) {

package/dist/chunk-466BPS3M.js

@@ -0,0 +1,336 @@
+import {
+  FailureKindSchema
+} from "./chunk-IHG6ADQG.js";
+
+// src/textgen/structured_output.ts
+var keywords = /* @__PURE__ */ new Set(["type", "properties", "required", "additionalProperties", "items", "enum", "const", "description", "title", "minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems", "format"]);
+var movableSchemaKeywords = Object.freeze(["minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems", "format"]);
+var removableSchemaKeywords = Object.freeze([...movableSchemaKeywords, "title", "additionalProperties"]);
+var types = /* @__PURE__ */ new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+var formats = /* @__PURE__ */ new Set(["date-time", "date", "time", "uuid"]);
+function jsonPointerError(pointer, reason) {
+  return new Error(`at ${pointer || "the root"}: ${reason}`);
+}
+function isJSONObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function pointerSegment(value) {
+  return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function boundedNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && parseRational(String(value)) !== void 0;
+}
+function validateCountBounds(node, pointer, minimum, maximum) {
+  for (const keyword of [minimum, maximum]) if (keyword in node && (!Number.isSafeInteger(node[keyword]) || node[keyword] < 0)) throw jsonPointerError(pointer, `"${keyword}" must be a non-negative integer`);
+  if (minimum in node && maximum in node && node[minimum] > node[maximum]) throw jsonPointerError(pointer, `"${minimum}" exceeds "${maximum}"`);
+}
+function schemaType(node, pointer) {
+  const type = node.type;
+  if (typeof type === "string" && types.has(type)) return [type, false];
+  if (Array.isArray(type) && type.length === 2 && type.every((entry) => typeof entry === "string") && type.includes("null")) {
+    const other = type.find((entry) => entry !== "null");
+    if (other && types.has(other)) return [other, true];
+  }
+  throw jsonPointerError(pointer, '"type" must be one JSON type or a pair of one type and "null"');
+}
+function canonicalizePortableSchema(schema) {
+  function checkSerializable(value, seen) {
+    if (typeof value === "number" && !Number.isFinite(value)) throw new Error("schema must be JSON serializable");
+    if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") throw new Error("schema must be JSON serializable");
+    if (value && typeof value === "object") {
+      if ("toJSON" in value && typeof value.toJSON === "function") return;
+      if (seen.has(value)) throw new Error("schema must be JSON serializable");
+      seen.add(value);
+      for (const child of Object.values(value)) checkSerializable(child, seen);
+      seen.delete(value);
+    }
+  }
+  checkSerializable(schema, /* @__PURE__ */ new Set());
+  let canonical;
+  try {
+    canonical = JSON.parse(JSON.stringify(schema));
+  } catch {
+    throw new Error("schema must be JSON serializable");
+  }
+  if (!isJSONObject(canonical)) throw new Error("schema must be a JSON object");
+  const [rootType, nullable] = schemaType(canonical, "");
+  if (rootType !== "object" || nullable) throw jsonPointerError("", 'the root must have type "object"');
+  checkNode(canonical, "", 1);
+  return canonical;
+}
+function checkNode(node, pointer, depth) {
+  if (depth > 10) throw jsonPointerError(pointer, "the schema is nested deeper than 10 levels");
+  for (const keyword of Object.keys(node).sort()) if (!keywords.has(keyword)) throw jsonPointerError(pointer, `keyword ${JSON.stringify(keyword.slice(0, 64))} is outside the portable subset`);
+  const [type] = schemaType(node, pointer);
+  const keywordRequiredType = { properties: "object", required: "object", additionalProperties: "object", items: "array", minItems: "array", maxItems: "array", minLength: "string", maxLength: "string", format: "string" };
+  for (const keyword of Object.keys(node).sort()) {
+    if (keywordRequiredType[keyword] && keywordRequiredType[keyword] !== type) throw jsonPointerError(pointer, `keyword "${keyword}" applies only to type "${keywordRequiredType[keyword]}"`);
+    if ((keyword === "minimum" || keyword === "maximum") && type !== "number" && type !== "integer") throw jsonPointerError(pointer, `keyword "${keyword}" applies only to number and integer types`);
+  }
+  for (const keyword of ["description", "title"]) if (keyword in node && typeof node[keyword] !== "string") throw jsonPointerError(pointer, `"${keyword}" must be a string`);
+  if ("enum" in node && (!Array.isArray(node.enum) || node.enum.length === 0)) throw jsonPointerError(pointer, '"enum" must be a non-empty array');
+  for (const value of node.enum ?? []) if (!scalar(value)) throw jsonPointerError(pointer, '"enum" values must be strings, numbers, booleans, or null');
+  if ("const" in node && !scalar(node.const)) throw jsonPointerError(pointer, '"const" must be a string, number, boolean, or null');
+  if (type === "object") {
+    if (!isJSONObject(node.properties)) throw jsonPointerError(pointer, 'an object requires a "properties" object');
+    if (node.additionalProperties !== false) throw jsonPointerError(pointer, 'an object must set "additionalProperties" to false');
+    if (!Array.isArray(node.required)) throw jsonPointerError(pointer, 'an object must list every property in "required"');
+    const required = node.required;
+    if (required.some((name) => typeof name !== "string") || new Set(required).size !== required.length) throw jsonPointerError(pointer, '"required" must list property names once each');
+    for (const name of required) if (!Object.hasOwn(node.properties, name)) throw jsonPointerError(pointer, '"required" lists a property that "properties" does not declare');
+    if (required.length !== Object.keys(node.properties).length) throw jsonPointerError(pointer, 'an object must list every property in "required"; use type [T, "null"] for an optional value');
+    for (const [name, child] of Object.entries(node.properties).sort(([a], [b]) => a.localeCompare(b))) {
+      const childPointer = `${pointer}/properties/${pointerSegment(name)}`;
+      if (!isJSONObject(child)) throw jsonPointerError(childPointer, "a property schema must be an object");
+      checkNode(child, childPointer, depth + 1);
+    }
+  } else if (type === "array") {
+    validateCountBounds(node, pointer, "minItems", "maxItems");
+    if (!isJSONObject(node.items)) throw jsonPointerError(pointer, 'an array requires an "items" schema object');
+    checkNode(node.items, `${pointer}/items`, depth + 1);
+  } else if (type === "string") {
+    if ("format" in node && !formats.has(node.format)) throw jsonPointerError(pointer, '"format" must be date-time, date, time, or uuid');
+    validateCountBounds(node, pointer, "minLength", "maxLength");
+  } else if (type === "number" || type === "integer") {
+    for (const keyword of ["minimum", "maximum"]) if (keyword in node && !boundedNumber(node[keyword])) throw jsonPointerError(pointer, `"${keyword}" must be a number`);
+    if (node.minimum !== void 0 && node.maximum !== void 0 && node.minimum > node.maximum) throw jsonPointerError(pointer, '"minimum" exceeds "maximum"');
+  }
+}
+function scalar(value) {
+  return value === null || typeof value === "string" || typeof value === "boolean" || boundedNumber(value);
+}
+function transformSchemaForProvider(schema, rules) {
+  const copy = JSON.parse(JSON.stringify(schema));
+  function visit(node) {
+    const constraints = [];
+    for (const keyword of [...rules.keywordsMovedToDescription ?? []].sort()) if (Object.hasOwn(node, keyword)) {
+      constraints.push(`${keyword}: ${marshalGoJSON(node[keyword])}`);
+      delete node[keyword];
+    }
+    if (constraints.length) node.description = `${typeof node.description === "string" && node.description ? `${node.description} ` : ""}(${constraints.join(", ")})`;
+    for (const keyword of rules.keywordsRemoved ?? []) delete node[keyword];
+    if (isJSONObject(node.properties)) {
+      for (const child of Object.values(node.properties)) if (isJSONObject(child)) visit(child);
+    }
+    if (isJSONObject(node.items)) visit(node.items);
+  }
+  visit(copy);
+  return copy;
+}
+function jsonObjectInstruction(name, description, schema) {
+  return `Respond with only one JSON object, without Markdown code fences, that matches the JSON Schema named ${JSON.stringify(name)}${description ? ` (${description})` : ""}:
+${marshalGoJSON(schema)}`;
+}
+function marshalGoJSON(value) {
+  if (Array.isArray(value)) return `[${value.map(marshalGoJSON).join(",")}]`;
+  if (isJSONObject(value)) {
+    const keys = Object.keys(value).sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+    return `{${keys.map((key) => `${marshalGoJSON(key)}:${marshalGoJSON(value[key])}`).join(",")}}`;
+  }
+  const encoded = JSON.stringify(value);
+  if (encoded === void 0) throw new Error("schema must be JSON serializable");
+  return encoded.replace(/[<>&\u2028\u2029]/g, (character) => `\\u${character.codePointAt(0).toString(16).padStart(4, "0")}`);
+}
+function extractStructuredAnswer(request, generatedText) {
+  if (!request.structuredOutput) return generatedText;
+  const schema = canonicalizePortableSchema(request.structuredOutput.schema);
+  return extractStructuredAnswerFromSchema(schema, generatedText);
+}
+function extractStructuredAnswerFromSchema(schema, generatedText) {
+  let text = generatedText.trim();
+  const fence = /^```([^\n]*)\n([\s\S]*)```$/.exec(text);
+  if (fence && (!fence[1]?.trim() || fence[1].trim().toLowerCase() === "json")) text = (fence[2] ?? "").trim();
+  let value;
+  const sourceByHolder = /* @__PURE__ */ new WeakMap();
+  try {
+    const sourceReviver = function(key, child, context) {
+      if (typeof child === "number" && context.source !== void 0) {
+        let sources = sourceByHolder.get(this);
+        if (!sources) {
+          sources = /* @__PURE__ */ new Map();
+          sourceByHolder.set(this, sources);
+        }
+        sources.set(key, context.source);
+      }
+      return child;
+    };
+    value = JSON.parse(text, sourceReviver);
+  } catch {
+    throw jsonPointerError("", "the text is not one JSON value");
+  }
+  const numbers = /* @__PURE__ */ new Map();
+  function assign(current, pointer) {
+    if (current === null || typeof current !== "object") return;
+    for (const [name, child] of Object.entries(current)) {
+      const childPointer = `${pointer}/${pointerSegment(name)}`;
+      if (typeof child === "number") numbers.set(childPointer, sourceByHolder.get(current)?.get(name) ?? "");
+      else assign(child, childPointer);
+    }
+  }
+  assign(value, "");
+  validateInstance(value, schema, "", numbers);
+  return text;
+}
+function validateInstance(value, schema, pointer, numbers) {
+  const [type, nullable] = schemaType(schema, pointer);
+  const number = typeof value === "number" ? parseRational(numbers.get(pointer) ?? "") : void 0;
+  if (typeof value === "number" && !number) throw jsonPointerError(pointer, "the number is out of range");
+  if (value === null) {
+    if (!nullable && type !== "null") throw jsonPointerError(pointer, `expected type ${type}, found null`);
+  } else {
+    const actualType = Array.isArray(value) ? "array" : isJSONObject(value) ? "object" : typeof value;
+    if (!(type === actualType || type === "integer" && number && number.numerator % number.denominator === 0n || type === "number" && number)) throw jsonPointerError(pointer, `expected type ${type}`);
+  }
+  const equal = (expected) => {
+    if (typeof expected === "number" && number) {
+      const wanted = parseRational(String(expected));
+      return wanted !== void 0 && compareRational(wanted, number) === 0;
+    }
+    return Object.is(expected, value);
+  };
+  if (Array.isArray(schema.enum) && !schema.enum.some(equal)) throw jsonPointerError(pointer, "the value is not one of the enum values");
+  if ("const" in schema && !equal(schema.const)) throw jsonPointerError(pointer, "the value does not equal const");
+  if (value === null) return;
+  if (type === "object" && isJSONObject(value) && isJSONObject(schema.properties)) {
+    for (const name of Object.keys(value).sort()) if (!Object.hasOwn(schema.properties, name)) throw jsonPointerError(pointer, "the object has a property the schema does not declare");
+    for (const [name, child] of Object.entries(schema.properties).sort(([a], [b]) => a.localeCompare(b))) {
+      const childPointer = `${pointer}/${pointerSegment(name)}`;
+      if (!Object.hasOwn(value, name)) throw jsonPointerError(childPointer, "a required property is missing");
+      if (isJSONObject(child)) validateInstance(value[name], child, childPointer, numbers);
+    }
+  } else if (type === "array" && Array.isArray(value) && isJSONObject(schema.items)) {
+    checkInstanceCount(value.length, schema, pointer, "minItems", "maxItems", "items");
+    value.forEach((item, index) => validateInstance(item, schema.items, `${pointer}/${index}`, numbers));
+  } else if (type === "string" && typeof value === "string") {
+    checkInstanceCount([...value].length, schema, pointer, "minLength", "maxLength", "characters");
+    if (typeof schema.format === "string" && !matchesFormat(value, schema.format)) throw jsonPointerError(pointer, `the string does not match format ${schema.format}`);
+  } else if ((type === "number" || type === "integer") && typeof value === "number") {
+    if (number && typeof schema.minimum === "number" && compareRational(number, parseRational(String(schema.minimum))) < 0) throw jsonPointerError(pointer, "the value is below minimum");
+    if (number && typeof schema.maximum === "number" && compareRational(number, parseRational(String(schema.maximum))) > 0) throw jsonPointerError(pointer, "the value is above maximum");
+  }
+}
+function checkInstanceCount(value, schema, pointer, minimum, maximum, unit) {
+  if (typeof schema[minimum] === "number" && value < schema[minimum]) throw jsonPointerError(pointer, `the value has fewer ${unit} than ${minimum}`);
+  if (typeof schema[maximum] === "number" && value > schema[maximum]) throw jsonPointerError(pointer, `the value has more ${unit} than ${maximum}`);
+}
+function matchesFormat(value, format) {
+  if (format === "uuid") return /^[0-9A-Fa-f]{8}-(?:[0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$/.test(value);
+  if (format === "date") {
+    const match2 = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    return !!match2 && isValidCalendarDate(Number(match2[1]), Number(match2[2]), Number(match2[3]));
+  }
+  if (format === "time") return matchesGoClock(value);
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(.+)$/.exec(value);
+  if (!match || !matchesGoClock(match[4] ?? "")) return false;
+  return isValidCalendarDate(Number(match[1]), Number(match[2]), Number(match[3]));
+}
+function isValidCalendarDate(year, month, day) {
+  const daysInMonth = [31, year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0;
+  return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth;
+}
+function matchesGoClock(value) {
+  const match = /^(\d{1,2}):(\d{2}):(\d{2})(?:[.,]\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/.exec(value);
+  return !!match && Number(match[1]) < 24 && Number(match[2]) < 60 && Number(match[3]) < 60 && Number(match[4] ?? 0) <= 24 && Number(match[5] ?? 0) <= 60;
+}
+function parseRational(literal) {
+  if (!literal || literal.length > 256) return void 0;
+  const match = /^(-?)(0|[1-9]\d*)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(literal);
+  if (!match) return void 0;
+  const exponent = Number(match[4] ?? 0);
+  if (!Number.isInteger(exponent) || Math.abs(exponent) > 400) return void 0;
+  const digits = (match[2] ?? "") + (match[3] ?? "");
+  const power = exponent - (match[3]?.length ?? 0);
+  const signed = BigInt(digits) * (match[1] === "-" ? -1n : 1n);
+  return power >= 0 ? { numerator: signed * 10n ** BigInt(power), denominator: 1n } : { numerator: signed, denominator: 10n ** BigInt(-power) };
+}
+function compareRational(left, right) {
+  const difference = left.numerator * right.denominator - right.numerator * left.denominator;
+  return difference < 0n ? -1 : difference > 0n ? 1 : 0;
+}
+
+// src/textgen/wire_format.ts
+function temperatureAccepted() {
+  return { kind: "accepted" };
+}
+function temperatureRange(minimum, maximum) {
+  return { kind: "range", minimum, maximum };
+}
+function temperatureNotAccepted() {
+  return { kind: "notAccepted" };
+}
+function validateStructuredOutputRules(rules) {
+  if (!["none", "jsonSchema", "jsonObjectWithInstruction"].includes(rules.mode)) throw new TypeError(`structured output mode ${JSON.stringify(rules.mode)} is invalid`);
+  for (const keyword of rules.keywordsMovedToDescription ?? []) if (!movableSchemaKeywords.includes(keyword)) throw new TypeError(`schema keyword ${JSON.stringify(keyword)} cannot be moved to a description`);
+  for (const keyword of rules.keywordsRemoved ?? []) if (!removableSchemaKeywords.includes(keyword)) throw new TypeError(`schema keyword ${JSON.stringify(keyword)} cannot be removed`);
+}
+function retryOutcome(kind) {
+  return { disposition: "retry", kind };
+}
+function providerRejectedOutcome(kind) {
+  return { disposition: "providerRejected", kind };
+}
+function quotaExhaustedOutcome() {
+  return providerRejectedOutcome("QUOTA_EXHAUSTED");
+}
+function blockedOutcome() {
+  return { disposition: "blocked", kind: "PROVIDER_REJECTION" };
+}
+function invalidResponseOutcome() {
+  return { disposition: "invalidResponse", kind: "PROTOCOL" };
+}
+var ProviderReportedError = class extends Error {
+  /** Bounded machine-readable tokens. */
+  errorTokens;
+  /** Construct without exposing provider message text. */
+  constructor(errorTokens) {
+    super("provider reported an error inside a 2xx response");
+    this.name = "ProviderReportedError";
+    this.errorTokens = errorTokens;
+  }
+};
+function classifyError(rules, statusCode, tokens, isReported = false) {
+  for (const rule of rules) if ((rule.statusCode === 0 || rule.statusCode === statusCode) && (!isReported || rule.statusCode === 0) && (!rule.errorToken || tokens.includes(rule.errorToken))) return rule.outcome;
+  if (isReported) return invalidResponseOutcome();
+  if (statusCode === 429) return retryOutcome("RATE_LIMIT");
+  if (statusCode === 408 || statusCode >= 500 && statusCode !== 501) return retryOutcome("AVAILABILITY");
+  const kinds = { 401: "AUTHENTICATION", 402: "QUOTA_EXHAUSTED", 403: "AUTHORIZATION", 404: "NOT_FOUND", 409: "CONFLICT" };
+  if (statusCode >= 300 && statusCode < 400) return invalidResponseOutcome();
+  return providerRejectedOutcome(kinds[statusCode] ?? "PROVIDER_REJECTION");
+}
+function validateWireFormat(format) {
+  if (!format.providerName) throw new TypeError("wire format provider name is required");
+  if (format.modelIDRule !== "body" && format.modelIDRule !== "pathSegment") throw new TypeError("wire format model ID rule is invalid");
+  if (typeof format.rulesForModel !== "function" || typeof format.encodeRequest !== "function") throw new TypeError("wire format rulesForModel and encodeRequest are required");
+  if (!format.decodeResponse && !format.decodeStreamEvent) throw new TypeError("wire format requires decodeResponse, decodeStreamEvent, or both");
+  if (typeof format.credentialHeader?.name !== "string" || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/.test(format.credentialHeader.name)) throw new TypeError("wire format credential header name is invalid");
+  if (typeof format.credentialHeader.prefix !== "string" || !/^[\x20-\x7e]*$/.test(format.credentialHeader.prefix)) throw new TypeError("wire format credential header prefix must be printable ASCII");
+  for (const [token, reason] of Object.entries(format.finishReasons)) if (!/^[A-Za-z0-9_.:-]{1,64}$/.test(token) || !["stop", "length", "contentPolicy", "refusal"].includes(reason)) throw new TypeError("wire format finish token is invalid");
+  for (const [index, rule] of (format.errorRules ?? []).entries()) {
+    if (!Number.isInteger(rule.statusCode) || rule.statusCode !== 0 && (rule.statusCode < 300 || rule.statusCode > 599)) throw new TypeError(`error rule ${index} status is invalid`);
+    if (rule.errorToken && !/^[A-Za-z0-9_.:-]{1,64}$/.test(rule.errorToken)) throw new TypeError(`error rule ${index} token is invalid`);
+    if (!rule.outcome || !["retry", "providerRejected", "invalidResponse", "blocked"].includes(rule.outcome.disposition) || !FailureKindSchema.safeParse(rule.outcome.kind).success) throw new TypeError(`error rule ${index} outcome is invalid`);
+  }
+  for (const pointer of format.errorTokenPointers ?? []) if (pointer !== "" && !pointer.startsWith("/")) throw new TypeError("wire format error-token pointer must start with /");
+  for (const name of [...format.requestIDHeaders ?? [], ...format.rateLimitHeaders ?? []]) if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/.test(name)) throw new TypeError("wire format response header name is invalid");
+  if (!Number.isSafeInteger(format.stallTimeoutMs ?? 0) || (format.stallTimeoutMs ?? 0) < 0) throw new TypeError("wire format stall timeout cannot be negative");
+}
+
+export {
+  canonicalizePortableSchema,
+  transformSchemaForProvider,
+  jsonObjectInstruction,
+  extractStructuredAnswer,
+  extractStructuredAnswerFromSchema,
+  temperatureAccepted,
+  temperatureRange,
+  temperatureNotAccepted,
+  validateStructuredOutputRules,
+  retryOutcome,
+  providerRejectedOutcome,
+  quotaExhaustedOutcome,
+  blockedOutcome,
+  invalidResponseOutcome,
+  ProviderReportedError,
+  classifyError,
+  validateWireFormat
+};

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