@fayegram-ai/decision-bridge 0.1.1 → 0.1.3

package/src/providers/cloudflare-profile.mjs

@@ -24,7 +24,7 @@ export function cloudflareModel(value = 'clef') {
 
 export function cloudflareRequestLimit(model, ceiling) {
     const profile = CLOUDFLARE_MODELS[cloudflareModel(model)];
-    return ceiling === undefined ? profile.requestBytes : Math.min(profile.maxRequestBytes, ceiling);
+    return ceiling === undefined ? profile.requestBytes : ceiling;
 }
 
 export function validateCloudflareLimits({ maxRequestBytes, maxRetries = 0,
@@ -40,10 +40,7 @@ export function validateCloudflareLimits({ maxRequestBytes, maxRetries = 0,
     return { ...(maxRequestBytes === undefined ? {} : { maxRequestBytes }), maxRetries, rejectIfBusy };
 }
 
-// Cloudflare's one-month TTL is 30 days in its official Gateway reference:
-// https://github.com/cloudflare/skills/blob/0cb6116228ad153126f474dce1dfbd05f7944604/skills/cloudflare/references/ai-gateway/README.md
-const GATEWAY_MAX_CACHE_TTL = 30 * 24 * 60 * 60;
-const headerString = (value, maxLength = 200) => typeof value === 'string' && value.trim().length > 0 &&
+const headerString = (value, maxLength = Infinity) => typeof value === 'string' && value.trim().length > 0 &&
     value.length <= maxLength && !/[^\x20-\x7e]/.test(value);
 
 /** Use the documented Workers Gateway shape for both transports. */
@@ -52,14 +49,14 @@ export function cloudflareGateway(input) {
     const gateway = cloneJson(input, 'Cloudflare gateway', 'CONFIGURATION_ERROR');
     optionsObject(gateway, ['id', 'cacheKey', 'cacheTtl', 'skipCache', 'metadata', 'collectLog',
         'requestTimeoutMs', 'retries'], 'Cloudflare gateway');
-    check(headerString(gateway.id, 64), 'Gateway id must be a printable ASCII string up to 64 characters.', 'CONFIGURATION_ERROR');
+    check(headerString(gateway.id), 'Gateway id must be a printable ASCII string without control characters.', 'CONFIGURATION_ERROR');
     if (gateway.cacheKey !== undefined) check(headerString(gateway.cacheKey),
-        'Gateway cacheKey must be a printable ASCII string up to 200 characters.', 'CONFIGURATION_ERROR');
+        'Gateway cacheKey must be a printable ASCII string without control characters.', 'CONFIGURATION_ERROR');
     for (const key of ['skipCache', 'collectLog']) check(gateway[key] === undefined || typeof gateway[key] === 'boolean',
         'Gateway cache and logging flags must be boolean.', 'CONFIGURATION_ERROR');
     check(gateway.cacheTtl === undefined || (Number.isSafeInteger(gateway.cacheTtl) &&
-        gateway.cacheTtl >= 60 && gateway.cacheTtl <= GATEWAY_MAX_CACHE_TTL),
-    'Gateway cacheTtl must be integer seconds from 60 to 2592000 (30 days).', 'CONFIGURATION_ERROR');
+        gateway.cacheTtl >= 0),
+    'Gateway cacheTtl must be nonnegative integer seconds.', 'CONFIGURATION_ERROR');
     check(gateway.requestTimeoutMs === undefined || (Number.isSafeInteger(gateway.requestTimeoutMs) &&
         gateway.requestTimeoutMs > 0 && gateway.requestTimeoutMs <= 2147483647),
     'Gateway requestTimeoutMs must be a positive 32-bit integer.', 'CONFIGURATION_ERROR');
@@ -69,18 +66,17 @@ export function cloudflareGateway(input) {
     if (gateway.metadata !== undefined) {
         // Reject predictable metadata loss instead of truncating or stripping caller data.
         const keys = Object.keys(gateway.metadata);
-        check(keys.length <= 5, 'Gateway metadata accepts at most five entries.', 'CONFIGURATION_ERROR');
         check(keys.every(key => !key.startsWith('cf.')),
             'Gateway metadata keys beginning with cf. are reserved.', 'CONFIGURATION_ERROR');
     }
     const retries = gateway.retries === undefined ? {} : gateway.retries;
     optionsObject(retries, ['maxAttempts', 'retryDelayMs', 'backoff'], 'Gateway retries');
     const maxAttempts = retries.maxAttempts === undefined ? 1 : retries.maxAttempts;
-    check(Number.isSafeInteger(maxAttempts) && maxAttempts >= 1 && maxAttempts <= 5,
-        'Gateway maxAttempts must be from 1 to 5.', 'CONFIGURATION_ERROR');
+    check(Number.isSafeInteger(maxAttempts) && maxAttempts >= 1,
+        'Gateway maxAttempts must be a positive integer.', 'CONFIGURATION_ERROR');
     check(retries.retryDelayMs === undefined || (Number.isSafeInteger(retries.retryDelayMs) &&
-        retries.retryDelayMs >= 0 && retries.retryDelayMs <= 60000),
-    'Gateway retryDelayMs must be from 0 to 60000.', 'CONFIGURATION_ERROR');
+        retries.retryDelayMs >= 0),
+    'Gateway retryDelayMs must be a nonnegative integer.', 'CONFIGURATION_ERROR');
     check(retries.backoff === undefined || ['constant', 'linear', 'exponential'].includes(retries.backoff),
         'Invalid Gateway backoff.', 'CONFIGURATION_ERROR');
     return freezeJson({ ...gateway, retries: { ...retries, maxAttempts } });

package/src/providers/cloudflare-transport.mjs

@@ -12,22 +12,27 @@ const responseMetadata = response => ({
 });
 
 /** The two dispatch mechanisms share bounded reads, cancellation, retries and errors. */
-export class CloudflareDecisionTransport {
+export class CloudflareTransport {
     #transports = new Map();
     #ceiling;
     #kind;
     #accountId;
     #ai;
     #gateway;
+    #requestLimit;
+    #bindingBody;
 
-    constructor(options) {
+    constructor(options, { requestLimit = cloudflareRequestLimit, bindingBody = cloudflareBindingBody,
+        models = ['clef', 'clef-omni'] } = {}) {
         const { transport = 'rest', accountId, apiKey, baseURL = 'https://api.cloudflare.com',
             ai, gateway, fetchImpl, model: _model, rejectIfBusy: _busy, ...limits } = options;
         this.#kind = transport;
         this.#gateway = gateway;
         this.#ceiling = limits.maxRequestBytes;
+        this.#requestLimit = model => requestLimit(model, this.#ceiling);
+        this.#bindingBody = bindingBody;
         const shared = { ...limits, errorDecoder: cloudflareError, responseMetadata };
-        const byteLimits = new Set(['clef', 'clef-omni'].map(model => cloudflareRequestLimit(model, this.#ceiling)));
+        const byteLimits = new Set(models.map(model => this.#requestLimit(model)));
         if (transport === 'binding') {
             check(ai !== null && typeof ai === 'object' && typeof ai.run === 'function',
                 'Binding transport requires an ai binding with run().', 'CONFIGURATION_ERROR');
@@ -52,12 +57,14 @@ export class CloudflareDecisionTransport {
     }
 
     request(request, options) {
-        const transport = this.#transports.get(cloudflareRequestLimit(request.model, this.#ceiling));
+        const transport = this.#transports.get(this.#requestLimit(request.model));
         if (this.#kind === 'rest') return transport.request('POST',
             '/client/v4/accounts/' + encodeURIComponent(this.#accountId) + '/ai/run/@cf/cloudflare/' + request.model,
             request, options);
-        const body = cloudflareBindingBody(request, this.#gateway);
+        const body = this.#bindingBody(request, this.#gateway);
         return transport.request(body, (_serialized, signal) => this.#ai.run(
             '@cf/cloudflare/' + request.model, body.inputs, { ...body.options, signal }), options);
     }
 }
+
+export class CloudflareDecisionTransport extends CloudflareTransport {}

package/src/providers/cloudflare-validation.mjs

@@ -23,7 +23,9 @@ export function cloudflareError(data, status, meta) {
     const upstreamCode = Number.isSafeInteger(value) && value >= 0 ? value : undefined;
     const [code, message] = CODES.get(upstreamCode) ?? STATUSES.get(status) ??
         ['HTTP_ERROR', 'Cloudflare rejected the inference request.'];
-    return new DecisionError(message, { code, status, ...meta,
+    return new DecisionError(message, { code, status, ...meta, source: 'provider',
+        retryable: !['ALLOCATION_EXCEEDED', 'AUTHENTICATION_ERROR', 'PERMISSION_DENIED', 'REQUEST_TOO_LARGE'].includes(code) &&
+            (code === 'CAPACITY_EXCEEDED' || code === 'RATE_LIMITED' || [502, 503, 504, 529].includes(status)),
         ...(upstreamCode === undefined ? {} : { upstreamCode }) });
 }
 

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/image-header.mjs

@@ -0,0 +1,59 @@
+// Shared bounded image-header inspection; full decoding remains the service boundary.
+import { requireCondition as check } from '../errors.mjs';
+
+const checkImage = condition => check(condition, 'Invalid embedded image header or dimensions.', 'VALIDATION_ERROR');
+const ascii = (bytes, start, length) => String.fromCharCode(...bytes.subarray(start, start + length));
+
+export function imageDimensions(bytes, format) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (format === 'image/png') {
+        checkImage(bytes.length >= 33 && [137, 80, 78, 71, 13, 10, 26, 10].every((value, i) => bytes[i] === value) &&
+            view.getUint32(8) === 13 && ascii(bytes, 12, 4) === 'IHDR');
+        return [view.getUint32(16), view.getUint32(20)];
+    }
+    if (format === 'image/jpeg') {
+        checkImage(bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216);
+        let offset = 2;
+        while (offset < bytes.length) {
+            checkImage(bytes[offset++] === 255);
+            while (offset < bytes.length && bytes[offset] === 255) offset++;
+            checkImage(offset < bytes.length);
+            const marker = bytes[offset++];
+            if (marker === 217 || marker === 218) break;
+            if (marker === 1 || (marker >= 208 && marker <= 215)) continue;
+            checkImage(offset + 2 <= bytes.length);
+            const length = view.getUint16(offset);
+            checkImage(length >= 2 && offset + length <= bytes.length);
+            if ([192, 193, 194, 195, 197, 198, 199, 201, 202, 203, 205, 206, 207].includes(marker)) {
+                checkImage(length >= 8 && bytes[offset + 7] > 0 && length >= 8 + 3 * bytes[offset + 7]);
+                return [view.getUint16(offset + 5), view.getUint16(offset + 3)];
+            }
+            offset += length;
+        }
+        checkImage(false);
+    }
+    checkImage(bytes.length >= 20 && ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WEBP' &&
+        view.getUint32(4, true) + 8 === bytes.length);
+    const little24 = offset => bytes[offset] | bytes[offset + 1] << 8 | bytes[offset + 2] << 16;
+    for (let offset = 12; offset + 8 <= bytes.length;) {
+        const kind = ascii(bytes, offset, 4);
+        const length = view.getUint32(offset + 4, true);
+        const start = offset + 8;
+        checkImage(start + length <= bytes.length);
+        if (kind === 'VP8X') {
+            checkImage(length === 10);
+            return [little24(start + 4) + 1, little24(start + 7) + 1];
+        }
+        if (kind === 'VP8L') {
+            checkImage(length >= 5 && bytes[start] === 47 && (bytes[start + 4] >> 5) === 0);
+            return [1 + (bytes[start + 1] | (bytes[start + 2] & 63) << 8),
+                1 + (bytes[start + 2] >> 6 | bytes[start + 3] << 2 | (bytes[start + 4] & 15) << 10)];
+        }
+        if (kind === 'VP8 ') {
+            checkImage(length >= 10 && ascii(bytes, start + 3, 3) === '\x9d\x01\x2a');
+            return [view.getUint16(start + 6, true) & 16383, view.getUint16(start + 8, true) & 16383];
+        }
+        offset = start + length + length % 2;
+    }
+    checkImage(false);
+}

package/src/providers/jev-images.mjs

@@ -0,0 +1,84 @@
+// Jev JSON assets use reference substitution in string values, never object keys.
+import { requireCondition as check } from '../errors.mjs';
+import { base64ByteLength } from '../embedded.mjs';
+import { isRecord } from '../validation.mjs';
+import { imageDimensions } from './image-header.mjs';
+
+const encoder = new TextEncoder();
+
+function inspectImage(asset) {
+    check(isRecord(asset) && Object.keys(asset).every(key => ['type', 'format', 'data_base64'].includes(key)) &&
+        (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);
+    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 > 0 && height > 0, 'Images require positive dimensions.');
+    if (asset.format === 'png') {
+        const view = new DataView(bytes.buffer);
+        for (let offset = 8; offset < bytes.length;) {
+            check(offset + 12 <= bytes.length, 'Invalid PNG chunk.');
+            const length = view.getUint32(offset);
+            check(offset + length + 12 <= bytes.length, 'Invalid PNG chunk length.');
+            check(String.fromCharCode(...bytes.subarray(offset + 4, offset + 8)) !== 'acTL',
+                'Jev does not accept animated PNG images.');
+            offset += length + 12;
+        }
+    }
+    return size;
+}
+
+/** Apply TypeSafe's JSON nesting boundary and collect only replaceable values. */
+function stringValues(value, output, depth = 0) {
+    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);
+    }
+}
+
+/** Whole values win first; other matches are consumed left to right. Alternatives
+ * at the same position retain asset-map order, as on the native TypeSafe API.
+ */
+function usedReferences(strings, references) {
+    const known = new Set(references);
+    const used = new Set();
+    if (!references.length) return used;
+    const pattern = new RegExp(references.map(reference => reference.replace(/[.*+?^$(){}|[\]\\]/g, '\\$&')).join('|'), 'g');
+    for (const value of strings) {
+        if (known.has(value)) used.add(value);
+        else for (const match of value.matchAll(pattern)) used.add(match[0]);
+    }
+    return used;
+}
+
+export function validateJevAssets(request) {
+    const strings = [];
+    stringValues(request.state, strings);
+    for (const question of Object.values(request.questions)) {
+        stringValues(question.instructions, strings);
+        if (question.criteria !== undefined) stringValues(question.criteria, strings);
+    }
+    const assets = request.assets === undefined ? {} : request.assets;
+    check(isRecord(assets), 'Jev assets must be an object.');
+    const references = Object.keys(assets);
+    let referenceBytes = 0;
+    // Bound the literal pattern before compiling it or decoding any images.
+    for (const reference of references) {
+        const size = encoder.encode(reference).length;
+        check(reference.trim() && size <= 1024, 'Jev asset references must be nonempty and within 1024 UTF-8 bytes.');
+        referenceBytes += size;
+        check(referenceBytes <= 65536, 'Jev asset references exceed 65536 UTF-8 bytes.', 'REQUEST_TOO_LARGE');
+    }
+    const used = usedReferences(strings, references);
+    for (const reference of references) {
+        check(used.has(reference), 'Every Jev asset must be used by reference substitution in a string value.');
+        inspectImage(assets[reference]);
+    }
+    // Server re-encoding, expanded references, full image decoding and token limits
+    // remain authoritative; original file sizes cannot predict those exactly.
+    return references.length;
+}

package/src/providers/jev-preflight.mjs

@@ -0,0 +1,62 @@
+// Shared pure preflight keeps offline validation and inference on the same path.
+import { requireCondition as check } from '../errors.mjs';
+import { cloneJson, freezeJson, isRecord, validateRequest } from '../validation.mjs';
+import { assertCapabilities, builtInCapabilities } from '../capabilities.mjs';
+import { embeddedDataUrl } from '../embedded.mjs';
+import { serializeRequestBody } from '../transport.mjs';
+import { jevDangerZone, jevRequestLimit } from './jev-profile.mjs';
+import { validateJevAssets } from './jev-images.mjs';
+
+/** Convert ordered parts to an ordered state array, without altering question text. */
+export function encodeJevDecision(request) {
+    if (!Object.hasOwn(request, 'input')) return request;
+    const text = JSON.stringify(request);
+    // Look ahead without consuming a token: two user tokens can share their
+    // boundary underscores, and both must be reserved before choosing a key.
+    const references = new Set(Array.from(text.matchAll(/(?=(__decision_bridge_image_\d+__))/g), match => match[1]));
+    const assets = {};
+    const state = request.input.map((part, index) => {
+        if (part.type === 'text') return part.text;
+        const image = embeddedDataUrl(part.dataUrl, 'image');
+        check(['image/png', 'image/jpeg'].includes(image.format), 'Jev accepts only embedded PNG or JPEG images.');
+        check(part.detail === undefined || part.detail === null || part.detail === 'auto',
+            'Jev does not support image detail controls.', 'UNSUPPORTED_CAPABILITY');
+        let suffix = index;
+        let reference = `__decision_bridge_image_${suffix}__`;
+        while (references.has(reference)) reference = `__decision_bridge_image_${++suffix}__`;
+        references.add(reference);
+        assets[reference] = { type: 'image', format: image.format === 'image/png' ? 'png' : 'jpg', data_base64: image.payload };
+        return reference;
+    });
+    return { model: request.model, state, questions: request.questions,
+        ...(Object.keys(assets).length ? { assets } : {}) };
+}
+
+export function prepareJevDecision(input, options = {}) {
+    const snapshot = cloneJson(input, 'Jev request');
+    check(isRecord(snapshot) && Object.keys(snapshot).every(key => ['model', 'state', 'questions', 'assets'].includes(key)),
+        'Jev native requests require state, questions, optional model and assets.');
+    const { assets, ...common } = snapshot;
+    const request = validateRequest(common, options.model ?? 'jev-latest');
+    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')) {
+        check(imageCount > 0, 'Jev box questions require at least one image asset.');
+    }
+    serializeRequestBody(native, jevRequestLimit(options.maxRequestBytes));
+    return { request: freezeJson(request), native: freezeJson(native) };
+}
+
+export function prepareCommonJevDecision(input, options = {}) {
+    const request = validateRequest(input, options.model ?? 'jev-latest');
+    assertCapabilities(request, builtInCapabilities('jev', request.model, { dangerZone: jevDangerZone(options.dangerZone) }));
+    const { native } = prepareJevDecision(encodeJevDecision(request), options);
+    return { request: freezeJson(request), native };
+}
+
+export const preflightJevDecision = (input, options) => prepareJevDecision(input, options).native;
+export const preflightCommonJevDecision = (input, options) => prepareCommonJevDecision(input, options).request;