@fayegram-ai/decision-bridge 0.1.2 → 0.1.3

package/src/providers/decisions-codec.mjs

@@ -9,10 +9,13 @@ const description = value => value === undefined || value === null ? {} : { desc
 export function encodeCommonDecision(request) {
     check(!request.input?.some(part => !['text', 'image'].includes(part.type)),
         'OpenAI Decisions does not support audio or video input.', 'UNSUPPORTED_CAPABILITY');
-    const input = own(request, 'state') ? encodeText(request.state) : [{ role: 'user', content: request.input.map(part =>
-        part.type === 'text' ? { type: 'input_text', text: part.text } : {
-            type: 'input_image', image_url: part.dataUrl, ...(own(part, 'detail') ? { detail: part.detail } : {}),
-        }) }];
+    const cache = part => own(part, 'promptCacheBreakpoint') ? { prompt_cache_breakpoint: part.promptCacheBreakpoint } : {};
+    const input = own(request, 'state') ? encodeText(request.state) : own(request, 'conversation') ? request.conversation
+        : [{ role: 'user', content: request.input.map(part => part.type === 'text'
+            ? { type: 'input_text', text: part.text, ...cache(part) } : {
+                type: 'input_image', image_url: part.dataUrl ?? part.url, ...cache(part),
+                ...(own(part, 'detail') ? { detail: part.detail } : {}),
+            }) }];
     const questions = Object.entries(request.questions).map(([name, q]) => {
         const base = { name, instructions: encodeText(q.instructions) };
         if (q.type === 'noul') {
@@ -29,7 +32,9 @@ export function encodeCommonDecision(request) {
             : q.criteria.map((entry, index) => ({ label: String(index), description: encodeText(entry) })) };
     });
     return { model: request.model, input, questions,
-        ...(own(request, 'safetyIdentifier') ? { safety_identifier: request.safetyIdentifier } : {}) };
+        ...(own(request, 'safetyIdentifier') ? { safety_identifier: request.safetyIdentifier } : {}),
+        ...(own(request, 'promptCacheKey') ? { prompt_cache_key: request.promptCacheKey } : {}),
+        ...(own(request, 'promptCacheOptions') ? { prompt_cache_options: request.promptCacheOptions } : {}) };
 }
 
 export function decodeCommonDecision(decision, request, meta) {

package/src/providers/decisions-input.mjs

@@ -0,0 +1,120 @@
+import { requireCondition as check } from '../errors.mjs';
+import { isRecord } from '../validation.mjs';
+import { validateImageSource } from '../input.mjs';
+
+const own = (value, key) => Object.hasOwn(value, key);
+export function fields(value, allowed, required, label, code = 'VALIDATION_ERROR') {
+    check(isRecord(value) && Object.keys(value).every(key => allowed.includes(key)) &&
+        required.every(key => own(value, key)), `Invalid ${label} fields.`, code);
+}
+const text = (value, label) => check(typeof value === 'string', `${label} must be text.`);
+
+export function validateCacheBreakpoint(value) {
+    if (value === undefined || value === null) return;
+    fields(value, ['mode'], ['mode'], 'cache breakpoint');
+    check(value.mode === 'explicit', 'Cache breakpoint mode must be explicit.');
+}
+
+export function validateCacheOptions(value) {
+    if (value === undefined || value === null) return;
+    fields(value, ['mode', 'ttl'], [], 'cache options');
+    check(value.mode === undefined || value.mode === null || ['implicit', 'explicit'].includes(value.mode), 'Invalid cache mode.');
+    check(value.ttl === undefined || value.ttl === '30m', 'Unsupported Decisions cache TTL.');
+}
+
+function inputPart(part, textOnly = false) {
+    if (part?.type === 'input_text') {
+        fields(part, ['type', 'text', 'prompt_cache_breakpoint'], ['type', 'text'], 'input text');
+        text(part.text, 'Input text');
+    } else {
+        check(!textOnly && part?.type === 'input_image', 'Unsupported input content.');
+        fields(part, ['type', 'image_url', 'detail', 'prompt_cache_breakpoint'], ['type', 'image_url'], 'input image');
+        validateImageSource(part.image_url, part.detail);
+    }
+    validateCacheBreakpoint(part.prompt_cache_breakpoint);
+}
+
+function outputPart(part) {
+    if (part?.type === 'output_text') {
+        fields(part, ['type', 'text'], ['type', 'text'], 'output text');
+        text(part.text, 'Output text');
+    } else {
+        fields(part, ['type', 'refusal'], ['type', 'refusal'], 'refusal');
+        check(part.type === 'refusal', 'Unsupported assistant content.');
+        text(part.refusal, 'Refusal');
+    }
+}
+
+/** Keep strings, item order, explicit nulls and tool arguments verbatim. */
+export function validateDecisionInput(input) {
+    if (typeof input === 'string') return;
+    check(Array.isArray(input) && input.length > 0, 'input must be text or a nonempty item array.');
+    const calls = new Map();
+    for (const item of input) {
+        if (isRecord(item) && own(item, 'role')) {
+            fields(item, ['type', 'role', 'content', 'phase'], ['role', 'content'], 'message');
+            check(item.type === undefined || item.type === 'message', 'Invalid message type.');
+            check(['user', 'developer', 'system', 'assistant'].includes(item.role), 'Unsupported message role.');
+            check(item.phase === undefined || item.phase === null ||
+                ['commentary', 'final_answer'].includes(item.phase), 'Invalid assistant phase.');
+            if (typeof item.content !== 'string') {
+                check(Array.isArray(item.content) && item.content.length > 0, 'Message requires ordered content.');
+                for (const part of item.content) {
+                    if (item.role === 'assistant') outputPart(part);
+                    else inputPart(part, item.role === 'system' || item.role === 'developer');
+                }
+            }
+            continue;
+        }
+        const call = ['function_call', 'custom_tool_call'].includes(item?.type);
+        const output = ['function_call_output', 'custom_tool_call_output'].includes(item?.type);
+        check(call || output, 'Unsupported conversation item.');
+        const payload = output ? 'output' : item.type === 'function_call' ? 'arguments' : 'input';
+        fields(item, ['type', 'call_id', payload, 'id', 'status', ...(call ? ['name', 'namespace'] : [])],
+            ['type', 'call_id', payload, ...(call ? ['name'] : [])], 'tool item');
+        check(typeof item.call_id === 'string' && item.call_id.length > 0, 'Tool items require a call_id.');
+        for (const key of ['id', 'namespace']) if (own(item, key) && item[key] !== null) text(item[key], key);
+        check(item.status === undefined || item.status === null ||
+            ['in_progress', 'completed', 'incomplete'].includes(item.status), 'Invalid tool status.');
+        if (call) {
+            check(typeof item.name === 'string' && item.name.length > 0, 'Tool calls require a name.');
+            text(item[payload], payload);
+            calls.set(item.call_id, item.type);
+        } else {
+            check(calls.get(item.call_id) === item.type.replace('_output', ''), 'Tool output requires a matching preceding call.');
+            if (typeof item.output !== 'string') {
+                check(Array.isArray(item.output) && item.output.length > 0, 'Tool output requires text or ordered content.');
+                item.output.forEach(part => inputPart(part));
+            }
+        }
+    }
+}
+
+export function validateDecisionQuestions(questions) {
+    check(Array.isArray(questions) && questions.length > 0, 'questions must be a nonempty array.');
+    for (const q of questions) {
+        check(isRecord(q) && ['predicate', 'choice', 'score'].includes(q.type), 'Unsupported native question type.');
+        const extra = q.type === 'choice' ? ['choices'] : q.type === 'score' ? ['levels'] : [];
+        fields(q, ['type', 'name', 'instructions', ...extra], ['type', 'instructions', ...extra], 'question');
+        text(q.instructions, 'Instructions');
+        if (own(q, 'name')) text(q.name, 'Question name');
+        if (q.type === 'choice') {
+            check(Array.isArray(q.choices) && q.choices.length >= 2, 'choices requires at least two options.');
+            const values = new Set();
+            for (const option of q.choices) {
+                fields(option, ['value', 'description'], ['value'], 'choice option');
+                check(typeof option.value === 'string' || typeof option.value === 'boolean', 'Choice values must be strings or booleans.');
+                check(!values.has(option.value), 'Choice values must be distinct.');
+                values.add(option.value);
+                if (own(option, 'description')) text(option.description, 'Choice description');
+            }
+        } else if (q.type === 'score') {
+            check(Array.isArray(q.levels) && q.levels.length > 0, 'levels must be nonempty.');
+            for (const level of q.levels) {
+                fields(level, ['label', 'description'], ['label'], 'score level');
+                text(level.label, 'Score label');
+                if (own(level, 'description')) text(level.description, 'Score description');
+            }
+        }
+    }
+}

package/src/providers/decisions-validation.mjs

@@ -1,81 +1,24 @@
 import { DecisionError, requireCondition as check } from '../errors.mjs';
 import { cloneJson, freezeJson, isRecord } from '../validation.mjs';
-import { isTextWithinLimit, validateImage } from '../input.mjs';
 import { builtInCapabilities } from '../capabilities.mjs';
 import { OPENAI_DEFAULT_MODEL } from './openai-profile.mjs';
+import { fields, validateCacheOptions, validateDecisionInput, validateDecisionQuestions } from './decisions-input.mjs';
 
-const own = (value, key) => Object.hasOwn(value, key);
-function fields(value, allowed, required, label, code = 'VALIDATION_ERROR') {
-    check(isRecord(value) && Object.keys(value).every(key => allowed.includes(key)) &&
-        required.every(key => own(value, key)), `Invalid ${label} fields.`, code);
-}
-function text(value, label, max = 1048576) {
-    check(isTextWithinLimit(value, max), `Invalid ${label}.`);
-}
-
-/** Validate native fields while retaining the selected model for preparation and metadata. */
+/** Structural preflight; service counts and context limits remain server-owned. */
 export function validateDecisionRequest(input, defaultModel = OPENAI_DEFAULT_MODEL) {
     const request = cloneJson(input, 'native decision request');
-    fields(request, ['input', 'model', 'questions', 'safety_identifier'], ['input', 'questions'], 'decision request');
-    const model = request.model ?? defaultModel;
+    fields(request, ['input', 'model', 'questions', 'safety_identifier', 'prompt_cache_key', 'prompt_cache_options'],
+        ['input', 'questions'], 'decision request');
+    const model = Object.hasOwn(request, 'model') ? request.model : defaultModel;
     check(typeof model === 'string' && model.trim().length > 0, 'model must be nonempty.');
     check(builtInCapabilities('openai-decisions', model).supported,
         'Selected provider/model does not support this model.', 'UNSUPPORTED_CAPABILITY');
-    if (own(request, 'model')) text(request.model, 'model');
-    if (own(request, 'safety_identifier') && request.safety_identifier !== null) text(request.safety_identifier, 'safety_identifier', 128);
-    let images = 0;
-    if (typeof request.input === 'string') text(request.input, 'input', 10485760);
-    else {
-        check(Array.isArray(request.input) && request.input.length > 0, 'input must be text or nonempty user messages.');
-        for (const message of request.input) {
-            fields(message, ['role', 'content', 'type'], ['role', 'content'], 'input message');
-            check(message.role === 'user' && (!own(message, 'type') || message.type === 'message'),
-                'Only user input messages are supported.');
-            if (typeof message.content === 'string') text(message.content, 'message content', 10485760);
-            else {
-                check(Array.isArray(message.content) && message.content.length > 0, 'Message content must contain ordered parts.');
-                for (const part of message.content) {
-                    if (part?.type === 'input_text') {
-                        fields(part, ['type', 'text'], ['type', 'text'], 'text part');
-                        text(part.text, 'input text', 10485760);
-                    } else {
-                        fields(part, ['type', 'image_url', 'detail'], ['type', 'image_url'], 'image part');
-                        check(part.type === 'input_image', 'Unsupported input part.');
-                        validateImage(part.image_url, part.detail);
-                        images++;
-                    }
-                }
-            }
-        }
-    }
-    check(images <= 128, 'At most 128 images are supported.', 'UNSUPPORTED_CAPABILITY');
-    check(Array.isArray(request.questions) && request.questions.length > 0, 'questions must be a nonempty array.');
-    for (const q of request.questions) {
-        check(isRecord(q) && ['predicate', 'choice', 'score'].includes(q.type), 'Unsupported native question type.');
-        const extra = q.type === 'choice' ? ['choices'] : q.type === 'score' ? ['levels'] : [];
-        fields(q, ['type', 'name', 'instructions', ...extra], ['type', 'instructions', ...extra], 'question');
-        text(q.instructions, 'instructions');
-        if (own(q, 'name')) text(q.name, 'question name');
-        if (q.type === 'choice') {
-            check(Array.isArray(q.choices) && q.choices.length >= 2 && q.choices.length <= 255,
-                'choices must contain 2 to 255 options.');
-            const values = new Set();
-            for (const option of q.choices) {
-                fields(option, ['value', 'description'], ['value'], 'choice option');
-                check(typeof option.value === 'string' || typeof option.value === 'boolean', 'Choice values must be strings or booleans.');
-                check(!values.has(option.value), 'Choice values must be distinct.');
-                values.add(option.value);
-                if (own(option, 'description')) text(option.description, 'choice description');
-            }
-        } else if (q.type === 'score') {
-            check(Array.isArray(q.levels) && q.levels.length > 0, 'levels must be nonempty.');
-            for (const level of q.levels) {
-                fields(level, ['label', 'description'], ['label'], 'score level');
-                text(level.label, 'score label');
-                if (own(level, 'description')) text(level.description, 'score description');
-            }
-        }
+    for (const key of ['safety_identifier', 'prompt_cache_key']) {
+        check(request[key] === undefined || request[key] === null || typeof request[key] === 'string', key + ' must be text or null.');
     }
+    validateCacheOptions(request.prompt_cache_options);
+    validateDecisionInput(request.input);
+    validateDecisionQuestions(request.questions);
     return freezeJson({ ...request, model });
 }
 
@@ -94,11 +37,36 @@ function validateUsage(usage) {
 }
 
 /** Refusals are failures even when valid sibling answers exist. No partial success. */
-export function validateDecisionResponse(input, request) {
+export function validateDecisionResponse(input, request, { allowRefusals = false } = {}) {
     const data = cloneJson(input, 'native decision response', 'INVALID_RESPONSE');
     fields(data, ['model', 'answers', 'usage'], ['model', 'answers', 'usage'], 'decision response', 'INVALID_RESPONSE');
     invalid(typeof data.model === 'string' && data.model.trim().length > 0, 'Missing reported model.');
     validateUsage(data.usage);
+    // Live can deliver a native result before its configuration is observed.
+    // Validate its self-contained distribution without inventing request correlation.
+    if (!request) {
+        invalid(Array.isArray(data.answers) && data.answers.length > 0, 'Missing decision answers.');
+        request = { questions: data.answers.map(answer => {
+            invalid(isRecord(answer) && (answer.name === null || typeof answer.name === 'string'), 'Invalid answer name.');
+            invalid(['predicate', 'choice', 'score', 'refusal'].includes(answer.type), 'Invalid answer type.');
+            const question = { type: answer.type, ...(answer.name === null ? {} : { name: answer.name }) };
+            if (answer.type === 'choice' || answer.type === 'score') {
+                invalid(Array.isArray(answer.probabilities) && answer.probabilities.length > 0, 'Missing decision distribution.');
+                if (answer.type === 'choice') question.choices = answer.probabilities.map(item => {
+                    invalid(isRecord(item) && ['string', 'boolean'].includes(typeof item.value), 'Invalid choice value.');
+                    return { value: item.value };
+                });
+                else {
+                    const sorted = [...answer.probabilities].sort((a, b) => a?.value - b?.value);
+                    question.levels = sorted.map((item, index) => {
+                        invalid(isRecord(item) && item.value === index && typeof item.label === 'string', 'Invalid score level.');
+                        return { label: item.label };
+                    });
+                }
+            }
+            return question;
+        }) };
+    }
     invalid(Array.isArray(data.answers) && data.answers.length === request.questions.length, 'Decision answer count mismatch.');
     const refusedQuestions = [];
     for (let index = 0; index < data.answers.length; index++) {
@@ -144,7 +112,7 @@ export function validateDecisionResponse(input, request) {
             answer.score <= supplied.length - 1 && Math.abs(answer.score - mean) <= 0.02 * supplied.length,
         'Decision score is inconsistent with its rubric.');
     }
-    if (refusedQuestions.length) throw new DecisionError('The model refused one or more decision questions.', {
+    if (refusedQuestions.length && !allowRefusals) throw new DecisionError('The model refused one or more decision questions.', {
         code: 'MODEL_REFUSAL', refusedQuestions, usage: data.usage,
     });
     return freezeJson(data);

package/src/providers/jev-images.mjs

@@ -11,16 +11,13 @@ function inspectImage(asset) {
         (asset.type === undefined || asset.type === 'image') && ['png', 'jpg', 'jpeg'].includes(asset.format),
     'Jev JSON image assets require PNG/JPEG format and data_base64.');
     const size = base64ByteLength(asset.data_base64);
-    check(size <= 16 * 1024 * 1024, 'Jev images must be within 16 MiB each.', 'REQUEST_TOO_LARGE');
     const decoded = atob(asset.data_base64);
     // A string iterator makes Uint8Array.from allocate an intermediate element
     // list. Copy directly into one bounded byte buffer for multi-MiB images.
     const bytes = new Uint8Array(decoded.length);
     for (let i = 0; i < decoded.length; i++) bytes[i] = decoded.charCodeAt(i);
     const [width, height] = imageDimensions(bytes, asset.format === 'png' ? 'image/png' : 'image/jpeg');
-    check(width >= 256 && width <= 1568 && height >= 256 && height <= 1568 &&
-        width * height >= 78400 && width * height <= 2458624,
-    'Jev image dimensions must be 256–1568 pixels with an area of 78400–2458624 pixels.');
+    check(width > 0 && height > 0, 'Images require positive dimensions.');
     if (asset.format === 'png') {
         const view = new DataView(bytes.buffer);
         for (let offset = 8; offset < bytes.length;) {
@@ -37,7 +34,6 @@ function inspectImage(asset) {
 
 /** Apply TypeSafe's JSON nesting boundary and collect only replaceable values. */
 function stringValues(value, output, depth = 0) {
-    check(depth <= 64, 'Jev state, instructions, and criteria must not exceed 64 nested levels.');
     if (typeof value === 'string') output.push(value);
     else if (value !== null && typeof value === 'object') {
         for (const child of Object.values(value)) stringValues(child, output, depth + 1);
@@ -78,11 +74,9 @@ export function validateJevAssets(request) {
         check(referenceBytes <= 65536, 'Jev asset references exceed 65536 UTF-8 bytes.', 'REQUEST_TOO_LARGE');
     }
     const used = usedReferences(strings, references);
-    let imageBytes = 0;
     for (const reference of references) {
         check(used.has(reference), 'Every Jev asset must be used by reference substitution in a string value.');
-        imageBytes += inspectImage(assets[reference]);
-        check(imageBytes <= 32 * 1024 * 1024, 'Jev images exceed 32 MiB total.', 'REQUEST_TOO_LARGE');
+        inspectImage(assets[reference]);
     }
     // Server re-encoding, expanded references, full image decoding and token limits
     // remain authoritative; original file sizes cannot predict those exactly.

package/src/providers/jev-preflight.mjs

@@ -41,6 +41,7 @@ export function prepareJevDecision(input, options = {}) {
     const dangerZone = jevDangerZone(options.dangerZone);
     assertCapabilities(request, builtInCapabilities('jev', request.model, { dangerZone }));
     const native = { ...request, ...(assets === undefined ? {} : { assets }) };
+    serializeRequestBody(native, jevRequestLimit(options.maxRequestBytes));
     const imageCount = validateJevAssets(native);
     if (imageCount) check(dangerZone.images, 'Enable Jev dangerZone.images to send images.', 'UNSUPPORTED_CAPABILITY');
     if (Object.values(request.questions).some(question => question.type === 'box')) {

package/src/providers/jev-profile.mjs

@@ -31,7 +31,7 @@ export function jevHeaders(dangerZone) {
 }
 
 export function jevRequestLimit(value = JEV_REQUEST_LIMIT) {
-    check(Number.isSafeInteger(value) && value > 0 && value <= JEV_REQUEST_LIMIT,
-        'Jev maxRequestBytes must be within 1 to 32 MiB.', 'CONFIGURATION_ERROR');
+    check(Number.isSafeInteger(value) && value > 0 && value <= 64 * 1024 * 1024,
+        'Jev maxRequestBytes must be within the client budget of 1 to 64 MiB.', 'CONFIGURATION_ERROR');
     return value;
 }

package/src/providers/media-binary.mjs

@@ -42,10 +42,3 @@ export function mediaBytes(payload, size) {
         },
     };
 }
-
-/** Container metadata can reject an overlong clip; full decoding remains upstream. */
-export function checkMediaDuration(duration, limit) {
-    if (duration === undefined) return;
-    mediaCheck(Number.isFinite(duration) && duration >= 0);
-    check(duration <= limit + 1e-9, 'Embedded media exceeds the duration limit.');
-}

package/src/providers/openai-decisions.mjs

@@ -8,6 +8,7 @@ import { validateDecisionResponse } from './decisions-validation.mjs';
 import { decodeCommonDecision } from './decisions-codec.mjs';
 import { preflightCommonDecision, prepareCommonDecision, prepareDecision } from './decisions-preflight.mjs';
 import { OPENAI_DEFAULT_MODEL } from './openai-profile.mjs';
+import { openaiError } from './openai-errors.mjs';
 
 /** Native Decisions transport. Common and dedicated access share a single codec. */
 export class OpenAIDecisionsProvider {
@@ -26,7 +27,7 @@ export class OpenAIDecisionsProvider {
         const key = validateApiKey(supplied, 'OPENAI_API_KEY');
         check(typeof model === 'string' && model.trim(), 'model must be nonempty.', 'CONFIGURATION_ERROR');
         this.defaultModel = model.trim();
-        this.#transport = new JsonTransport({ ...transportOptions, maxRetries, baseURL: endpoint.baseURL,
+        this.#transport = new JsonTransport({ ...transportOptions, maxRetries, errorDecoder: openaiError, baseURL: endpoint.baseURL,
             headers: { authorization: `Bearer ${key}` }, secrets: [key] });
         this.#maxRequestBytes = transportOptions.maxRequestBytes;
     }

package/src/providers/openai-errors.mjs

@@ -0,0 +1,23 @@
+import { DecisionError } from '../errors.mjs';
+import { isRecord } from '../validation.mjs';
+
+const BILLING_CODES = new Set(['insufficient_quota', 'credit_balance_exhausted',
+    'organization_spend_limit_exceeded', 'project_spend_limit_exceeded', 'organization_usage_limit_exceeded']);
+const machineCode = value => typeof value === 'string' && /^[a-zA-Z0-9_.-]{1,128}$/.test(value) ? value : undefined;
+
+/** Only machine codes leave the decoder; upstream messages can contain input. */
+export function openaiError(data, status, meta = {}) {
+    const details = isRecord(data) && isRecord(data.error) ? data.error : {};
+    const upstreamErrorCode = machineCode(details.code);
+    const upstreamErrorType = machineCode(details.type);
+    const billing = BILLING_CODES.has(upstreamErrorCode) || upstreamErrorType === 'insufficient_quota';
+    const code = billing ? 'ALLOCATION_EXCEEDED' : status === 401 ? 'AUTHENTICATION_ERROR'
+        : status === 403 ? 'PERMISSION_DENIED' : status === 429 ? 'RATE_LIMITED'
+        : status === 413 ? 'REQUEST_TOO_LARGE' : status === 400 || status === 422 ? 'INVALID_REQUEST' : 'HTTP_ERROR';
+    return new DecisionError(`OpenAI rejected the request (${code}).`, {
+        ...meta, code, status, source: 'provider',
+        retryable: !billing && [429, 500, 502, 503, 504, 529].includes(status),
+        ...(upstreamErrorCode ? { upstreamErrorCode } : {}),
+        ...(upstreamErrorType ? { upstreamErrorType } : {}),
+    });
+}

package/src/providers/openai-profile.mjs

@@ -8,7 +8,8 @@ const PROFILES = Object.freeze({
     [LUNA_MODEL]: Object.freeze({
         supported: true, orderedInput: true, images: true, typedChoices: true,
         labeledScores: true, safetyIdentifier: true,
-        maxImages: 128, maxChoiceOptions: 255, maxScoreLevels: null,
+        maxImages: null, maxChoiceOptions: null, maxScoreLevels: null,
+        conversation: true, toolHistory: true, remoteImages: true, promptCaching: true,
     }),
 });
 

package/src/response-transport.mjs

@@ -13,8 +13,9 @@ const BYTE_VIEW_KIND = Object.getOwnPropertyDescriptor(BYTE_VIEW_PROTOTYPE, Symb
 /** Shared wire-size check for offline preflight and actual HTTP dispatch. */
 export function serializeRequestBody(body, maxRequestBytes = 8 * 1024 * 1024) {
   const serialized = body === undefined ? undefined : JSON.stringify(body);
-  check(serialized === undefined || UTF8_ENCODER.encode(serialized).byteLength <= maxRequestBytes,
-    'Provider request exceeds the byte limit.', 'REQUEST_TOO_LARGE');
+  if (serialized !== undefined && UTF8_ENCODER.encode(serialized).byteLength > maxRequestBytes) {
+    throw new DecisionError('Request exceeds the configured client byte budget.', { code: 'REQUEST_TOO_LARGE', source: 'client' });
+  }
   return serialized;
 }
 
@@ -35,15 +36,52 @@ export function sanitizeId(value, secrets = []) {
   return safe.replace(/[\x00-\x1f\x7f]/g, '').slice(0, 200) || undefined;
 }
 
-function retryDelay(headers, attempt) {
-  const raw = headers.get('retry-after');
-  if (raw !== null) {
-    const seconds = Number(raw);
-    const milliseconds = raw.trim() !== '' && Number.isFinite(seconds)
-      ? seconds * 1000 : Date.parse(raw) - Date.now();
-    if (Number.isFinite(milliseconds) && milliseconds >= 0) return milliseconds;
-  }
-  return Math.min(8000, 250 * 2 ** attempt) * (0.5 + Math.random());
+/** RFC 9110 HTTP dates use UTC, including the timezone-free asctime form. */
+function httpDate(value, now) {
+    let parts = /^([A-Z][a-z]{2}), (\d{2}) ([A-Z][a-z]{2}) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/.exec(value);
+    let legacy = false;
+    if (!parts) {
+        parts = /^([A-Z][a-z]+), (\d{2})-([A-Z][a-z]{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/.exec(value);
+        legacy = !!parts;
+    }
+    if (!parts) {
+        const match = /^([A-Z][a-z]{2}) ([A-Z][a-z]{2}) (\d{2}| \d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/.exec(value);
+        if (!match) return undefined;
+        const [, weekday, month, day, hour, minute, second, year] = match;
+        parts = [value, weekday, day, month, year, hour, minute, second];
+    }
+    const [, weekday, dayText, monthText, yearText, hourText, minuteText, secondText] = parts;
+    const days = legacy ? ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
+        : ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+    const month = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'].indexOf(monthText);
+    const [day, hour, minute, second] = [dayText, hourText, minuteText, secondText].map(Number);
+    if (!days.includes(weekday) || month < 0 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 60) return undefined;
+    const future = new Date(now);
+    future.setUTCFullYear(future.getUTCFullYear() + 50);
+    let year = Number(yearText) + (legacy ? Math.floor(future.getUTCFullYear() / 100) * 100 : 0);
+    const dateFor = selectedYear => {
+        const date = new Date(0);
+        date.setUTCFullYear(selectedYear, month, day);
+        date.setUTCHours(hour, minute, Math.min(second, 59), 0);
+        return date;
+    };
+    let date = dateFor(year);
+    // Two-digit years denote the most recent matching year no more than 50 years ahead.
+    if (legacy && date > future) { year -= 100; date = dateFor(year); }
+    if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month || date.getUTCDate() !== day) return undefined;
+    return date.getTime() + (second === 60 ? 1000 : 0);
+}
+
+export function retryAfter(headers) {
+    const raw = headers.get('retry-after');
+    if (raw === null) return undefined;
+    if (/^\d+$/.test(raw)) {
+        const milliseconds = Number(raw) * 1000;
+        return Number.isFinite(milliseconds) ? milliseconds : undefined;
+    }
+    const now = Date.now();
+    const date = httpDate(raw, now);
+    return date === undefined ? undefined : Math.max(0, date - now);
 }
 
 async function readJson(response, maxBytes, budget) {
@@ -123,7 +161,18 @@ export class JsonResponseTransport {
             for (let retry = 0; ; retry++) {
                 budget.throwIfAborted();
                 attempts++;
-                const response = await withSignal(dispatch(serialized, budget.signal), budget.signal);
+                let response;
+                try { response = await withSignal(dispatch(serialized, budget.signal), budget.signal); }
+                catch (error) {
+                    // Binding exceptions may provide structured own data, never inspect messages/getters.
+                    const descriptors = error && typeof error === 'object' ? Object.getOwnPropertyDescriptors(error) : {};
+                    const status = descriptors.status?.value;
+                    const internalCode = descriptors.internalCode?.value;
+                    if (this.#errorDecoder && Number.isInteger(status) && status >= 400 && status <= 599 &&
+                        Number.isSafeInteger(internalCode) && internalCode >= 0) {
+                        response = Response.json({ internalCode }, { status });
+                    } else throw error;
+                }
                 check(response instanceof Response, 'Provider must return a Response.', 'INVALID_RESPONSE');
                 const extra = this.#responseMetadata?.(response) ?? {};
                 lastRequestId = sanitizeId(extra.requestId ?? response.headers.get('x-request-id') ??
@@ -135,7 +184,14 @@ export class JsonResponseTransport {
                     ...(lastGatewayLogId ? { gatewayLogId: lastGatewayLogId } : {}),
                 };
                 if (response.ok) {
-                    const data = await readJson(response, this.#options.maxResponseBytes, budget);
+                    let data;
+                    try { data = await readJson(response, this.#options.maxResponseBytes, budget); }
+                    catch (error) {
+                        if (error instanceof DecisionError) throw new DecisionError(error.message,
+                            { ...error.toJSON(), status: response.status, ...meta,
+                                source: error.code === 'RESPONSE_TOO_LARGE' ? 'client' : 'provider' });
+                        throw error;
+                    }
                     budget.throwIfAborted();
                     meta.durationMs = Math.round((performance.now() - started) * 1000) / 1000;
                     return { data, meta };
@@ -143,15 +199,25 @@ export class JsonResponseTransport {
                 let data;
                 if (this.#errorDecoder) {
                     try { data = await readJson(response, this.#options.maxResponseBytes, budget); }
-                    catch (error) { if (error.code !== 'INVALID_RESPONSE') throw error; }
+                    catch {
+                        // A rejection remains authoritative when its body is malformed,
+                        // oversized or interrupted. Cancellation/deadlines still win.
+                        budget.throwIfAborted();
+                    }
                 } else response.body?.cancel().catch(() => {});
                 const error = this.#errorDecoder?.(data, response.status, meta) ??
                     new DecisionError(`Provider returned HTTP ${response.status}.`, {
-                        code: 'HTTP_ERROR', status: response.status, ...meta,
+                        code: 'HTTP_ERROR', status: response.status, source: 'provider', ...meta,
                     });
                 budget.throwIfAborted();
-                if (!RETRY_STATUSES.has(response.status) || retry >= this.#options.maxRetries) throw error;
-                const delay = retryDelay(response.headers, retry);
+                error.retryable ??= RETRY_STATUSES.has(response.status);
+                const hint = retryAfter(response.headers);
+                if (hint !== undefined) error.retryAfterMs = hint;
+                for (const key of ['upstreamErrorCode', 'upstreamErrorType']) {
+                    if (error[key] !== undefined) error[key] = sanitizeId(error[key], this.#secrets);
+                }
+                if (!error.retryable || retry >= this.#options.maxRetries) throw error;
+                const delay = hint === undefined ? Math.min(8000, 250 * 2 ** retry) * (0.5 + Math.random()) : hint;
                 if (delay >= budget.remainingMs) throw new DecisionError('Retry delay exceeds the remaining request deadline.', {
                     ...error.toJSON(), code: 'RETRY_BUDGET_EXCEEDED',
                 });
@@ -164,6 +230,7 @@ export class JsonResponseTransport {
             if (budget.timedOut) throw new DecisionError('Provider request deadline exceeded.', { code: 'TIMEOUT', ...diagnostics });
             if (error instanceof DecisionError) {
                 error.attempts ??= attempts;
+                error.source ??= 'client';
                 if (lastRequestId) error.requestId ??= lastRequestId;
                 if (lastGatewayLogId) error.gatewayLogId ??= lastGatewayLogId;
                 throw error;