@fayegram-ai/decision-bridge 0.1.1 → 0.1.2

package/src/cli/config.mjs

@@ -4,6 +4,7 @@ import { parseEnv } from 'node:util';
 import { OPENAI_DEFAULT_MODEL } from '../providers/openai-profile.mjs';
 import { DecisionError, requireCondition as check } from '../errors.mjs';
 import { validateConfig, NUMERIC, PROVIDER_FIELDS } from './config-validation.mjs';
+import { jevDangerZone } from '../providers/jev-profile.mjs';
 export { validateConfig } from './config-validation.mjs';
 export { configuredProvider } from './provider-loader.mjs';
 
@@ -12,6 +13,7 @@ const ENV_FIELDS = {
     DECISION_API_KEY_ENV: 'apiKeyEnv', DECISION_TIMEOUT_MS: 'timeoutMs',
     DECISION_MAX_RETRIES: 'maxRetries', DECISION_RESPONSE_FORMAT: 'responseFormat',
     DECISION_ACCOUNT_ID: 'accountId', DECISION_REJECT_IF_BUSY: 'rejectIfBusy', DECISION_GATEWAY_ID: 'gateway',
+    DECISION_JEV_IMAGES: 'jevImages', DECISION_JEV_LONG_CONTEXT: 'jevLongContext',
 };
 
 async function boundedFile(path, maxBytes, label) {
@@ -47,13 +49,17 @@ export async function loadConfig({ configPath, envFile, overrides = {}, cwd = pr
     fileConfig = validateConfig(fileConfig);
     moduleBase = dirname(path);
   }
-  const environment = {};
+  const environment = Object.create(null);
   for (const [key, field] of Object.entries(ENV_FIELDS)) {
     if (effectiveEnv[key] === undefined) continue;
     const value = effectiveEnv[key];
     if (NUMERIC.has(field)) check(typeof value === 'string' && /^\d+$/.test(value),
       'Numeric DECISION_* variables must contain decimal integers.', 'CONFIGURATION_ERROR');
-    if (field === 'rejectIfBusy') {
+    if (field === 'jevImages' || field === 'jevLongContext') {
+      check(value === 'true' || value === 'false', 'Jev DECISION_* flags must be true or false.', 'CONFIGURATION_ERROR');
+      environment.dangerZone = { ...(Object.hasOwn(environment, 'dangerZone') ? environment.dangerZone : {}),
+        [field === 'jevImages' ? 'images' : 'longContext']: value === 'true' };
+    } else if (field === 'rejectIfBusy') {
       check(value === 'true' || value === 'false', 'DECISION_REJECT_IF_BUSY must be true or false.', 'CONFIGURATION_ERROR');
       environment[field] = value === 'true';
     } else environment[field] = field === 'gateway' ? { id: value } : NUMERIC.has(field) ? Number(value) : value;
@@ -62,6 +68,10 @@ export async function loadConfig({ configPath, envFile, overrides = {}, cwd = pr
   // environment-selected provider must not inherit that provider's key/endpoint.
   function mergeProviderLayer(base, layer, layerModuleBase = moduleBase) {
     const next = { ...base };
+    const dangerZone = Object.hasOwn(layer, 'dangerZone') ? layer.dangerZone : undefined;
+    // Validate before spreading, without filling defaults that would erase a
+    // different opt-in from a lower layer.
+    if (dangerZone !== undefined) jevDangerZone(dangerZone);
     // File and flag paths have different bases. Equal path text can identify
     // different implementations; compare destinations before changing the base.
     const moduleChanged = layer.module !== undefined && (typeof layer.module !== 'string' ||
@@ -72,6 +82,9 @@ export async function loadConfig({ configPath, envFile, overrides = {}, cwd = pr
     if (changed) for (const key of PROVIDER_FIELDS) delete next[key];
     if (layer.module !== undefined) moduleBase = layerModuleBase;
     return { ...next, ...layer,
+      ...(dangerZone === undefined ? {} : { dangerZone: {
+        ...(Object.hasOwn(next, 'dangerZone') ? next.dangerZone : {}), ...dangerZone,
+      } }),
       ...(layer.gateway === undefined ? {} : { gateway: { ...next.gateway, ...layer.gateway } }) };
   }
   const config = validateConfig(mergeProviderLayer(mergeProviderLayer(

package/src/cli/decisions.mjs

@@ -4,9 +4,17 @@ import { preflightCloudflareDecision, preflightCommonCloudflareDecision } from '
 import { encodeCloudflareDecision } from '../providers/cloudflare-codec.mjs';
 import { CLOUDFLARE_MAX_REQUEST_LIMIT } from '../providers/cloudflare-profile.mjs';
 import { resolveOpenAIModel } from '../providers/openai-profile.mjs';
+import { preflightCommonJevDecision, preflightJevDecision, encodeJevDecision } from '../providers/jev-preflight.mjs';
+import { JEV_REQUEST_LIMIT } from '../providers/jev-profile.mjs';
 
 /** Provider-specific native dispatch is shared by validation, initialization and calls. */
 export function decisionProfile(provider) {
+    if (provider === 'jev') return {
+        common: preflightCommonJevDecision, native: preflightJevDecision, encode: encodeJevDecision,
+        models: true, inputLimit: JEV_REQUEST_LIMIT,
+        options: config => ({ model: config.model, maxRequestBytes: config.maxRequestBytes,
+            dangerZone: Object.hasOwn(config, 'dangerZone') ? config.dangerZone : undefined }),
+    };
     if (provider === 'openai-decisions') return {
         common: preflightCommonDecision, native: preflightDecision, encode: encodeCommonDecision,
         resolveModel: resolveOpenAIModel,

package/src/cli/main.mjs

@@ -15,7 +15,8 @@ import { assertDistinctFiles, createWriter, readJson, readJsonLines } from './io
 import { mapOrdered } from './ordered.mjs';
 
 const SAMPLE_PATH = fileURLToPath(new URL('../../examples/request.json', import.meta.url));
-const BOOLS = ['help', 'version', 'pretty', 'compact', 'no-auth', 'force', 'native', 'reject-if-busy', 'no-reject-if-busy'];
+const BOOLS = ['help', 'version', 'pretty', 'compact', 'no-auth', 'force', 'native', 'reject-if-busy', 'no-reject-if-busy',
+    'jev-images', 'no-jev-images', 'jev-long-context', 'no-jev-long-context'];
 const STRINGS = ['config', 'env-file', 'provider', 'preset', 'model', 'base-url', 'api-key-env', 'timeout-ms',
   'retries', 'max-tokens', 'response-format', 'token-parameter', 'input', 'output', 'concurrency', 'provider-module', 'account-id', 'gateway-id'];
 const FIELD_MAP = { preset: 'preset', provider: 'provider', model: 'model', 'base-url': 'baseURL', 'api-key-env': 'apiKeyEnv',
@@ -50,6 +51,10 @@ Options:
   --timeout-ms N            End-to-end evaluation/provider deadline
   --retries N               HTTP retries, 0–10; Decisions default 0, others 2
   --native                  Selected decision provider native format (init/evaluate/validate/batch)
+  --jev-images              Enable experimental Jev images and box questions
+  --no-jev-images           Explicitly disable Jev images
+  --jev-long-context        Enable experimental Jev 262k context
+  --no-jev-long-context     Explicitly disable Jev long context
   --account-id ID           Cloudflare account (otherwise CLOUDFLARE_ACCOUNT_ID)
   --reject-if-busy          Unavailable for Clef REST; rejected before inference
   --no-reject-if-busy       Explicitly disable Cloudflare capacity rejection
@@ -95,7 +100,7 @@ function argumentsFor(argv) {
 }
 
 function overridesFor(values) {
-  const overrides = {};
+  const overrides = Object.create(null);
   for (const [flag, field] of Object.entries(FIELD_MAP)) if (values[flag] !== undefined) {
     const value = values[flag];
     if (['timeoutMs', 'maxRetries', 'maxTokens'].includes(field)) {
@@ -107,6 +112,12 @@ function overridesFor(values) {
   check(!(values['reject-if-busy'] && values['no-reject-if-busy']), 'Choose one reject-if-busy flag.', 'USAGE_ERROR');
   if (values['reject-if-busy'] || values['no-reject-if-busy']) overrides.rejectIfBusy = !!values['reject-if-busy'];
   if (values['gateway-id'] !== undefined) overrides.gateway = { id: values['gateway-id'] };
+  for (const [flag, field] of [['jev-images', 'images'], ['jev-long-context', 'longContext']]) {
+    check(!(values[flag] && values['no-' + flag]), 'Choose one Jev feature flag for each setting.', 'USAGE_ERROR');
+    if (values[flag] || values['no-' + flag]) overrides.dangerZone = {
+      ...(Object.hasOwn(overrides, 'dangerZone') ? overrides.dangerZone : {}), [field]: !!values[flag],
+    };
+  }
   return overrides;
 }
 
@@ -171,7 +182,7 @@ export async function runCli(argv, { stdin = process.stdin, stdout = process.std
       '--native requires a decision provider and init/evaluate/validate/batch.', 'USAGE_ERROR');
     check(!values.native || command === 'init' || values.input || positionals[1],
       '--native requires an explicit input file or -.', 'USAGE_ERROR');
-    check(command !== 'models' || !profile,
+    check(command !== 'models' || !profile || profile.models,
       'This decision provider does not implement model listing.', 'UNSUPPORTED_OPERATION');
     activeEnv = loaded.env;
     explicitSecret = loaded.config.apiKeyEnv ? activeEnv[loaded.config.apiKeyEnv] : undefined;
@@ -201,7 +212,7 @@ export async function runCli(argv, { stdin = process.stdin, stdout = process.std
       if (profile && command !== 'schema') return profile.common(raw, profile.options(loaded.config));
       const request = validateRequest(raw, raw?.model ?? loaded.config.model ?? 'validation-only');
       if (!isModule(loaded.config)) assertCapabilities(request,
-        builtInCapabilities(loaded.config.provider, request.model));
+        builtInCapabilities(loaded.config.provider, request.model, loaded.config));
       return request;
     };
     if (command === 'init') {

package/src/index.d.mts

@@ -1,4 +1,6 @@
 /** JSON values are read-only because the bridge snapshots/freezes its boundaries. */
+import type { JevDangerZone, JevQuestions, JevDecisionRequest, JevDecisionResponse, JevTransportMetadata } from './jev.d.mts';
+export type { JevDangerZone, JevImageAsset, JevQuestions, JevDecisionRequest, JevDecisionResponse, JevTransportMetadata } from './jev.d.mts';
 import type { NativeDecisionRequest, OpenAIDecisionResponse, OpenAIDecisionUsage,
     OpenAIDecisionsMetadata, OpenAIDecisionsTransportMetadata } from './decisions.d.mts';
 export type { NativeDecisionInputPart, NativeDecisionMessage, NativeDecisionQuestion, NativeDecisionRequest,
@@ -25,6 +27,15 @@ export interface NoulQuestion {
   readonly type: 'noul'; readonly instructions: Instructions;
   readonly criteria?: { readonly true?: Instructions; readonly false?: Instructions };
 }
+export interface BoxQuestion {
+    readonly type: 'box'; readonly instructions: Instructions; readonly criteria?: never;
+}
+export interface BoxCoordinates {
+    readonly top: number; readonly bottom: number; readonly left: number; readonly right: number;
+}
+export interface BoxAnswer {
+    readonly type: 'box'; readonly box: BoxCoordinates; readonly confidence?: number;
+}
 export interface ScoreQuestion<C extends ScoreCriteria = ScoreCriteria> {
   readonly type: 'score'; readonly instructions: Instructions; readonly criteria: C;
   readonly levels?: never;
@@ -45,7 +56,7 @@ export type DecisionInputPart = { readonly type: 'text'; readonly text: string }
     | { readonly type: 'audio'; readonly dataUrl: string }
     | { readonly type: 'video'; readonly dataUrl: string };
 export type OrderedInput = readonly DecisionInputPart[];
-export type Question = ChoiceQuestion | TypedChoiceQuestion | NoulQuestion | ScoreQuestion | LabeledScoreQuestion;
+export type Question = ChoiceQuestion | TypedChoiceQuestion | NoulQuestion | ScoreQuestion | LabeledScoreQuestion | BoxQuestion;
 export type Questions = Readonly<Record<string, Question>>;
 export interface ChoiceAnswer<K extends string = string> {
   readonly type: 'choice'; readonly choice: K;
@@ -71,7 +82,7 @@ type ChoiceLabel<K> = K extends string ? K : K extends number ? `${K}` : never;
 export type AnswerFor<Q extends Question> = Q extends TypedChoiceQuestion<infer O> ? TypedChoiceAnswer<O[number]['value']>
   : Q extends LabeledScoreQuestion<infer L> ? LabeledScoreAnswer<L>
   : Q extends ChoiceQuestion<infer C>
-  ? ChoiceAnswer<ChoiceLabel<keyof C>> : Q extends NoulQuestion ? NoulAnswer : ScoreAnswer;
+  ? ChoiceAnswer<ChoiceLabel<keyof C>> : Q extends NoulQuestion ? NoulAnswer : Q extends BoxQuestion ? BoxAnswer : ScoreAnswer;
 export type EvaluationRequest<Q extends Questions = Questions> = {
     readonly questions: Q; readonly model?: string; readonly safetyIdentifier?: string | null;
 } & ({ readonly state: State; readonly input?: never } | { readonly input: OrderedInput; readonly state?: never });
@@ -110,7 +121,7 @@ export interface ModelList {
     readonly release_date?: string; readonly [key: string]: unknown }[];
   readonly has_more?: boolean; readonly last_id?: string;
 }
-export interface ResultValidationOptions { readonly native?: boolean; readonly probabilityDecimalPlaces?: number; }
+export interface ResultValidationOptions { readonly native?: boolean; readonly nullableUsage?: boolean; readonly probabilityDecimalPlaces?: number; }
 export type ProviderKind = 'decision' | 'generative';
 export interface Provider {
   readonly kind: ProviderKind;
@@ -125,6 +136,7 @@ export interface Provider {
 }
 export interface DecisionProvider extends Provider { readonly kind: 'decision'; }
 export interface Capabilities {
+    readonly boxes?: boolean;
     readonly audio?: boolean; readonly videos?: boolean;
     readonly maxAudioClips?: number | null; readonly maxVideos?: number | null;
     readonly supported: boolean; readonly orderedInput: boolean; readonly images: boolean;
@@ -146,7 +158,7 @@ export interface TransportOptions {
   timeoutMs?: number; maxRetries?: number; maxRequestBytes?: number; maxResponseBytes?: number;
   fetchImpl?: (input: string, init?: RequestInit) => Promise<Response>;
 }
-export interface JevOptions extends TransportOptions { apiKey?: string; model?: string; baseURL?: string; }
+export interface JevOptions extends TransportOptions { apiKey?: string; model?: string; baseURL?: string; dangerZone?: JevDangerZone; }
 export interface OpenAIDecisionsOptions extends TransportOptions { apiKey?: string; model?: string; baseURL?: string; }
 export interface Bridge {
   readonly provider: string; readonly providerKind: ProviderKind; readonly defaultModel?: string;
@@ -166,6 +178,10 @@ export class JevProvider implements DecisionProvider {
   evaluate<const Q extends Questions>(request: EvaluationRequest<Q>, options?: ProviderCallOptions): Promise<ProviderResult<Q>>;
   listModels(options?: ProviderCallOptions): Promise<ModelList>;
   getCapabilities(model?: string): Capabilities;
+  getResultValidationOptions(model?: string): ResultValidationOptions;
+  validateRequest(request: ResolvedRequest): void;
+  createDecision<const Q extends JevQuestions>(request: JevDecisionRequest<Q>, options?: ProviderCallOptions):
+      Promise<{ readonly decision: JevDecisionResponse<Q>; readonly meta: JevTransportMetadata }>;
 }
 export class OpenAIDecisionsProvider implements DecisionProvider {
     readonly kind: 'decision'; readonly name: 'openai-decisions'; readonly probabilitySource: 'native'; readonly defaultModel: string;
@@ -187,10 +203,12 @@ export class CloudflareDecisionsProvider implements DecisionProvider {
         Promise<{ readonly decision: CloudflareDecisionResponse; readonly meta: CloudflareTransportMetadata }>;
 }
 export type CloudflareDecisionsConfig = { type: 'cloudflare-decisions' } & CloudflareDecisionsOptions;
-export type ProviderConfig = ({ type: 'jev' } & JevOptions)
+export type JevConfig = { type: 'jev' } & JevOptions;
+export type ProviderConfig = JevConfig
   | ({ type: 'openai-decisions' } & OpenAIDecisionsOptions)
   | CloudflareDecisionsConfig;
 export type OpenAIDecisionsConfig = { type: 'openai-decisions' } & OpenAIDecisionsOptions;
+export function createProvider(options: JevConfig): JevProvider;
 export function createProvider(options: OpenAIDecisionsConfig): OpenAIDecisionsProvider;
 export function createProvider(options: CloudflareDecisionsConfig): CloudflareDecisionsProvider;
 export function createProvider(options: ProviderConfig | OpenAIDecisionsConfig): DecisionProvider;
@@ -200,6 +218,7 @@ export function choice<const C extends ChoiceCriteria>(instructions: Instruction
 export function noul(instructions: Instructions, criteria?: NoulQuestion['criteria']): NoulQuestion;
 export function score<const C extends ScoreCriteria>(instructions: Instructions, criteria: C): ScoreQuestion<C>;
 export function scoreLevels<const L extends ScoreLevels>(instructions: Instructions, levels: L): LabeledScoreQuestion<L>;
+export function box(instructions: Instructions): BoxQuestion;
 export interface ChoicePolicyOptions<K extends string | boolean = string> {
     minProbability: number; minMargin?: number; abstainOptions?: readonly K[];
     /** Provider-declared probability precision; omission retains the baseline tolerance. */

package/src/index.mjs

@@ -1,6 +1,6 @@
 export { createBridge } from './bridge.mjs';
 export { JevProvider, OpenAIDecisionsProvider, CloudflareDecisionsProvider, createProvider } from './providers/index.mjs';
-export { choice, noul, score, scoreLevels } from './questions.mjs';
+export { choice, noul, score, scoreLevels, box } from './questions.mjs';
 export { decideChoice } from './policy.mjs';
 export { evaluateBatch } from './batch.mjs';
 export { DecisionError, publicError } from './errors.mjs';

package/src/jev.d.mts

@@ -0,0 +1,16 @@
+/** Native Jev JSON assets; file reading and image preparation remain caller-owned. */
+import type { State, ChoiceQuestion, NoulQuestion, ScoreQuestion, BoxQuestion, ProviderResult } from './index.d.mts';
+
+export interface JevDangerZone { readonly images?: boolean; readonly longContext?: boolean; }
+export interface JevImageAsset {
+    readonly type?: 'image'; readonly format: 'png' | 'jpg' | 'jpeg'; readonly data_base64: string;
+}
+export type JevQuestions = Readonly<Record<string, ChoiceQuestion | NoulQuestion | ScoreQuestion | BoxQuestion>>;
+export interface JevDecisionRequest<Q extends JevQuestions = JevQuestions> {
+    readonly state: State; readonly questions: Q; readonly model?: string;
+    readonly assets?: Readonly<Record<string, JevImageAsset>>;
+}
+export type JevDecisionResponse<Q extends JevQuestions = JevQuestions> = Omit<ProviderResult<Q>, 'meta'>;
+export interface JevTransportMetadata {
+    readonly requestedModel: string; readonly durationMs: number; readonly attempts: number; readonly requestId?: string;
+}

package/src/probabilities.mjs

@@ -6,14 +6,17 @@ export function validateResultOptions(options) {
         [Object.prototype, null].includes(Object.getPrototypeOf(options)) &&
         Object.getOwnPropertySymbols(options).length === 0 &&
         Object.entries(Object.getOwnPropertyDescriptors(options)).every(([key, descriptor]) =>
-            ['native', 'probabilityDecimalPlaces'].includes(key) && descriptor.enumerable && 'value' in descriptor),
+            ['native', 'nullableUsage', 'probabilityDecimalPlaces'].includes(key) && descriptor.enumerable && 'value' in descriptor),
     'Result-validation options contain an unknown field or accessor.', 'CONFIGURATION_ERROR');
-    const { native = false, probabilityDecimalPlaces } = options;
+    // Only own data fields select policy; inherited values and getters are not settings.
+    const { native = false, nullableUsage = false, probabilityDecimalPlaces } = Object.assign(Object.create(null), options);
     check(typeof native === 'boolean', 'native must be boolean.', 'CONFIGURATION_ERROR');
+    check(typeof nullableUsage === 'boolean', 'nullableUsage must be boolean.', 'CONFIGURATION_ERROR');
     check(probabilityDecimalPlaces === undefined || (Number.isSafeInteger(probabilityDecimalPlaces) &&
         probabilityDecimalPlaces >= 1 && probabilityDecimalPlaces <= 15),
     'probabilityDecimalPlaces must be an integer from 1 to 15.', 'CONFIGURATION_ERROR');
-    return { native, ...(probabilityDecimalPlaces === undefined ? {} : { probabilityDecimalPlaces }) };
+    // Keep even an omitted precision as an own value when callers read this policy again.
+    return { native, nullableUsage, probabilityDecimalPlaces };
 }
 
 /** Preserve native numbers. Only grid-aligned values receive the rounding budget. */

package/src/providers/cloudflare-images.mjs

@@ -1,65 +1,9 @@
 import { requireCondition as check } from '../errors.mjs';
 import { validateImage } from '../input.mjs';
 import { isRecord } from '../validation.mjs';
+import { imageDimensions } from './image-header.mjs';
 
 const FORMATS = ['image/png', 'image/jpeg', 'image/webp'];
-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));
-
-function dimensions(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);
-}
-
 /** Inspect bounded embedded bytes; this is header validation, not full image decoding. */
 export function validateCloudflareImages(images) {
     check(Array.isArray(images) && images.length <= 4, 'Cloudflare accepts at most four images.');
@@ -88,7 +32,7 @@ export function validateCloudflareImages(images) {
         const decoded = atob(payload);
         const bytes = new Uint8Array(decoded.length);
         for (let i = 0; i < decoded.length; i++) bytes[i] = decoded.charCodeAt(i);
-        const [width, height] = dimensions(bytes, format);
+        const [width, height] = imageDimensions(bytes, format);
         check(width > 0 && height > 0 && width * height <= 16000000,
             'Cloudflare images must have positive dimensions within 16 million pixels.');
     }

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,90 @@
+// 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);
+    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.');
+    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) {
+    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);
+    }
+}
+
+/** 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);
+    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');
+    }
+    // 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,61 @@
+// 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 }) };
+    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;

package/src/providers/jev-profile.mjs

@@ -0,0 +1,37 @@
+import { optionsObject } from '../options.mjs';
+import { requireCondition as check } from '../errors.mjs';
+
+export const JEV_REQUEST_LIMIT = 32 * 1024 * 1024;
+export const JEV_RESULT_OPTIONS = Object.freeze({ native: true, nullableUsage: true });
+
+/** Experimental features are explicit provider policy, never inferred from input. */
+export function jevDangerZone(value = {}) {
+    const options = optionsObject(value, ['images', 'longContext'], 'Jev dangerZone');
+    const images = Object.hasOwn(options, 'images') ? options.images : false;
+    const longContext = Object.hasOwn(options, 'longContext') ? options.longContext : false;
+    check([images, longContext].every(value => value === undefined || typeof value === 'boolean'),
+        'Jev dangerZone flags must be boolean.', 'CONFIGURATION_ERROR');
+    return Object.freeze({ images: images ?? false, longContext: longContext ?? false });
+}
+
+/** Moving stable aliases stay conservative; pin a supported version for boxes. */
+export function jevFeatures(model, dangerZone = {}) {
+    const version = /^jev-(\d+)\.(\d+)\.(\d+)$/.exec(model ?? '');
+    const boxes = model === 'jev-preview' || (version !== null &&
+        (Number(version[1]) > 1 || (Number(version[1]) === 1 && Number(version[2]) >= 14)));
+    const images = Object.hasOwn(dangerZone, 'images') && dangerZone.images === true;
+    return { orderedInput: true, images, boxes: images && boxes, maxImages: null };
+}
+
+export function jevHeaders(dangerZone) {
+    return {
+        ...(dangerZone.images ? { 'TypeSafe-Danger-Zone-Images': 'true' } : {}),
+        ...(dangerZone.longContext ? { 'TypeSafe-Danger-Zone-Long-Context': 'true' } : {}),
+    };
+}
+
+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');
+    return value;
+}