@fayegram-ai/decision-bridge 0.1.1 → 0.1.3

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 <= 64 * 1024 * 1024,
+        'Jev maxRequestBytes must be within the client budget of 1 to 64 MiB.', 'CONFIGURATION_ERROR');
+    return value;
+}

package/src/providers/jev.mjs

@@ -1,9 +1,11 @@
 import { optionsObject, TRANSPORT_FIELDS } from '../options.mjs';
 import { withResponseMeta, requireCondition as check } from '../errors.mjs';
-import { isRecord, validateRequest, validateResult } from '../validation.mjs';
+import { freezeJson, isRecord, validateResult } from '../validation.mjs';
 import { JsonTransport, parseBaseURL, validateApiKey } from '../transport.mjs';
 import { environmentValue } from '../runtime-env.mjs';
-import { assertCapabilities, LEGACY_CAPABILITIES } from '../capabilities.mjs';
+import { builtInCapabilities } from '../capabilities.mjs';
+import { jevDangerZone, jevHeaders, jevRequestLimit, JEV_RESULT_OPTIONS } from './jev-profile.mjs';
+import { prepareCommonJevDecision, prepareJevDecision } from './jev-preflight.mjs';
 
 /** Native TypeSafe HTTP provider: one shared-state request, no chat emulation. */
 export class JevProvider {
@@ -11,12 +13,13 @@ export class JevProvider {
   kind = 'decision';
   probabilitySource = 'native';
   #transport;
+  #options;
 
   constructor(options = {}) {
     const { apiKey,
     model = environmentValue('JEV_MODEL')?.trim() || 'jev-latest',
-    baseURL = 'https://api.typesafe.ai', ...transportOptions } = optionsObject(options,
-      ['apiKey', 'model', 'baseURL', ...TRANSPORT_FIELDS], 'Jev options');
+    baseURL = 'https://api.typesafe.ai', dangerZone, ...transportOptions } = Object.assign(Object.create(null), optionsObject(options,
+      ['apiKey', 'model', 'baseURL', 'dangerZone', ...TRANSPORT_FIELDS], 'Jev options'));
     const endpointInfo = parseBaseURL(baseURL, { originOnly: true });
     const supplied = apiKey === undefined && endpointInfo.origin === 'https://api.typesafe.ai'
       ? environmentValue('TYPESAFE_API_KEY') : apiKey;
@@ -24,20 +27,36 @@ export class JevProvider {
     check(typeof model === 'string' && model.trim(), 'model must be nonempty.', 'CONFIGURATION_ERROR');
     const endpoint = endpointInfo.baseURL;
     this.defaultModel = model.trim();
-    this.#transport = new JsonTransport({ ...transportOptions, baseURL: endpoint,
-      headers: { authorization: `Bearer ${key}` }, secrets: [key] });
+    this.#options = { model: this.defaultModel, dangerZone: jevDangerZone(dangerZone),
+        maxRequestBytes: jevRequestLimit(transportOptions.maxRequestBytes) };
+    this.#transport = new JsonTransport({ ...transportOptions, maxRequestBytes: this.#options.maxRequestBytes, baseURL: endpoint,
+      headers: { authorization: `Bearer ${key}`, ...jevHeaders(this.#options.dangerZone) }, secrets: [key] });
   }
 
   async evaluate(input, options = {}) {
-    const request = validateRequest(input, this.defaultModel);
-    assertCapabilities(request, this.getCapabilities(request.model));
-    const { data, meta } = await this.#transport.request('POST', '/v1/systemone', request, options);
-    const result = withResponseMeta(meta, () => validateResult(data, request.questions, { native: true }));
-    return { ...result, meta: { ...meta, provider: this.name, requestedModel: request.model,
-      probabilitySource: 'native', confidenceSource: 'native', modelSource: 'reported' } };
+    const prepared = prepareCommonJevDecision(input, this.#options);
+    const { decision, meta } = await this.#perform(prepared, options);
+    return freezeJson({ ...decision, meta: { ...meta, provider: this.name,
+      probabilitySource: 'native', confidenceSource: 'native', modelSource: 'reported' } });
   }
 
-  getCapabilities() { return LEGACY_CAPABILITIES; }
+  getCapabilities(model = this.defaultModel) { return builtInCapabilities('jev', model, this.#options); }
+
+  getResultValidationOptions() { return JEV_RESULT_OPTIONS; }
+
+  validateRequest(request) { prepareCommonJevDecision(request, this.#options); }
+
+  /** Native JSON assets allow images anywhere in state, instructions or criteria. */
+  async createDecision(input, options = {}) {
+    return this.#perform(prepareJevDecision(input, this.#options), options);
+  }
+
+  async #perform({ request, native }, options) {
+    const { data, meta: transport } = await this.#transport.request('POST', '/v1/systemone', native, options);
+    const meta = { ...transport, requestedModel: request.model };
+    const decision = withResponseMeta(meta, () => validateResult(data, request.questions, JEV_RESULT_OPTIONS));
+    return freezeJson({ decision, meta });
+  }
 
   async listModels(options = {}) {
     const { data, meta } = await this.#transport.request('GET', '/v1/models', undefined, options);

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/questions.mjs

@@ -13,3 +13,5 @@ export const noul = (instructions, criteria) => build({
 });
 export const score = (instructions, criteria) => build({ type: 'score', instructions, criteria });
 export const scoreLevels = (instructions, levels) => build({ type: 'score', instructions, levels });
+/** One bounding box; use a separate noul to check whether the target is present. */
+export const box = instructions => build({ type: 'box', instructions });

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;

package/src/validation.mjs

@@ -1,5 +1,6 @@
 import { requireCondition as check } from './errors.mjs';
-import { isTextWithinLimit, validateOrderedInput } from './input.mjs';
+import { validateOrderedInput } from './input.mjs';
+import { validateCacheOptions, validateCacheBreakpoint, validateDecisionInput } from './providers/decisions-input.mjs';
 import { validateProbabilitySum, validateResultOptions } from './probabilities.mjs';
 
 const own = (value, key) => Object.hasOwn(value, key);
@@ -81,14 +82,25 @@ function allowedKeys(value, expected, label, code = 'VALIDATION_ERROR') {
 export function validateRequest(input, defaultModel) {
   const request = cloneJson(input, 'request');
   check(isRecord(request), 'request must be an object.');
-  allowedKeys(request, ['state', 'input', 'questions', 'model', 'safetyIdentifier'], 'request');
-  check(own(request, 'state') !== own(request, 'input'), 'Provide exactly one of state or input.');
+  allowedKeys(request, ['state', 'input', 'conversation', 'questions', 'model', 'safetyIdentifier',
+    'promptCacheKey', 'promptCacheOptions'], 'request');
+  check(['state', 'input', 'conversation'].filter(key => own(request, key)).length === 1,
+    'Provide exactly one of state, input or conversation.');
   if (own(request, 'state')) check(request.state !== null && isEntry(request.state),
     'state must be text, a JSON object, or an array.');
-  else validateOrderedInput(request.input);
+  else if (own(request, 'conversation')) {
+    check(Array.isArray(request.conversation), 'conversation must be an ordered item array.');
+    validateDecisionInput(request.conversation);
+  } else {
+    validateOrderedInput(request.input);
+    for (const part of request.input) validateCacheBreakpoint(part.promptCacheBreakpoint);
+  }
+  if (own(request, 'promptCacheKey')) check(request.promptCacheKey === null || typeof request.promptCacheKey === 'string',
+    'promptCacheKey must be text or null.');
+  validateCacheOptions(request.promptCacheOptions);
   if (own(request, 'safetyIdentifier')) check(request.safetyIdentifier === null ||
-    isTextWithinLimit(request.safetyIdentifier, 128),
-  'safetyIdentifier must be a string up to 128 characters or null.');
+    typeof request.safetyIdentifier === 'string',
+  'safetyIdentifier must be a string or null.');
   if (own(request, 'model')) check(nonempty(request.model), 'model must be a nonempty string when provided.');
     const model = own(request, 'model') ? request.model : defaultModel;
   check(nonempty(model), 'model must be a nonempty string.');
@@ -97,9 +109,9 @@ export function validateRequest(input, defaultModel) {
   for (const [id, q] of Object.entries(request.questions)) {
     check(nonempty(id), 'Question IDs must be nonempty.');
     check(isRecord(q), 'Every question must be an object.');
-    allowedKeys(q, q.type === 'choice' ? ['type', 'instructions', 'criteria', 'options'] :
+    allowedKeys(q, q.type === 'box' ? ['type', 'instructions'] : q.type === 'choice' ? ['type', 'instructions', 'criteria', 'options'] :
       q.type === 'score' ? ['type', 'instructions', 'criteria', 'levels'] : ['type', 'instructions', 'criteria'], 'question');
-    check(['choice', 'noul', 'score'].includes(q.type), 'Question type must be choice, noul, or score.');
+    check(['choice', 'noul', 'score', 'box'].includes(q.type), 'Question type must be choice, noul, score, or box.');
     check(own(q, 'instructions') && q.instructions !== null && isEntry(q.instructions),
       'instructions are required and must be text, a JSON object, or an array.');
     if (typeof q.instructions === 'string') check(nonempty(q.instructions), 'instructions must not be empty.');
@@ -125,14 +137,14 @@ export function validateRequest(input, defaultModel) {
         if (own(level, 'description')) check(level.description !== null && isEntry(level.description), 'Invalid level description.');
       }
     } else if (q.type === 'choice') {
-      check(isRecord(q.criteria) && Object.keys(q.criteria).length > 0 && Object.keys(q.criteria).length <= 255,
-        'choice requires a criteria map with 1 to 255 options.');
+      check(isRecord(q.criteria) && Object.keys(q.criteria).length > 0,
+        'choice requires a nonempty criteria map.');
       for (const [label, description] of Object.entries(q.criteria)) {
         check(nonempty(label) && isEntry(description), 'choice criteria require labels and text, structured JSON, or null descriptions.');
       }
     } else if (q.type === 'score') {
-      check(Array.isArray(q.criteria) && q.criteria.length >= 2 && q.criteria.length <= 10,
-        'score requires 2 to 10 ordered criteria.');
+      check(Array.isArray(q.criteria) && q.criteria.length >= 2,
+        'score requires at least two ordered criteria.');
       check(q.criteria.every(value => value !== null && isEntry(value)),
         'score descriptions must be text or structured JSON, not null.');
     } else if (own(q, 'criteria')) {
@@ -158,7 +170,7 @@ function distribution(value, labels, decimalPlaces) {
 
 /** Validate, but do not invent, round, or normalize model results. */
 export function validateResult(input, questions, options = {}) {
-  const { native, probabilityDecimalPlaces } = validateResultOptions(options);
+  const { native, nullableUsage, probabilityDecimalPlaces } = validateResultOptions(options);
   const result = cloneJson(input, 'response', 'INVALID_RESPONSE');
   // Snapshot both sides so rubric comparison uses JSON values without executing accessors.
   const questionSnapshot = cloneJson(questions, 'questions');
@@ -168,23 +180,30 @@ export function validateResult(input, questions, options = {}) {
   check(nonempty(result.model), 'Response must include model.', 'INVALID_RESPONSE');
   exactKeys(result.answers, Object.keys(questionSnapshot), 'answers', 'INVALID_RESPONSE');
   for (const [id, q] of Object.entries(questionSnapshot)) {
-    check(isRecord(q) && ['noul', 'choice', 'score'].includes(q.type), 'A valid question type is required.');
+    check(isRecord(q) && ['noul', 'choice', 'score', 'box'].includes(q.type), 'A valid question type is required.');
     if (q.type === 'choice' && own(q, 'options')) check(Array.isArray(q.options) && q.options.length > 0 &&
       q.options.every(option => isRecord(option)), 'Typed choice requires nonempty option objects.');
     if (q.type === 'score' && own(q, 'levels')) check(Array.isArray(q.levels) && q.levels.length >= 2 &&
       q.levels.every(level => isRecord(level) && typeof level.label === 'string'), 'Labelled score requires valid levels.');
-    if (q.type === 'choice' && !own(q, 'options')) check(isRecord(q.criteria) && Object.keys(q.criteria).length > 0 &&
-      Object.keys(q.criteria).length <= 255, 'choice requires 1 to 255 criteria.');
-    if (q.type === 'score' && !own(q, 'levels')) check(Array.isArray(q.criteria) && q.criteria.length >= 2 && q.criteria.length <= 10, 'score requires 2–10 levels.');
+    if (q.type === 'choice' && !own(q, 'options')) check(isRecord(q.criteria) && Object.keys(q.criteria).length > 0,
+      'choice requires nonempty criteria.');
+    if (q.type === 'score' && !own(q, 'levels')) check(Array.isArray(q.criteria) && q.criteria.length >= 2, 'score requires at least two levels.');
     const answer = result.answers[id];
     check(isRecord(answer) && answer.type === q.type, 'Answer type must match its question.', 'INVALID_RESPONSE');
-    allowedKeys(answer, q.type === 'noul' ? ['type', 'noul'] : q.type === 'choice'
+    allowedKeys(answer, q.type === 'box' ? ['type', 'box', 'confidence'] : q.type === 'noul' ? ['type', 'noul'] : q.type === 'choice'
       ? ['type', 'choice', 'probabilities', 'confidence'] : ['type', 'score', 'legend', 'probabilities', 'confidence'], 'answer', 'INVALID_RESPONSE');
     if (q.type === 'noul') {
       probability(answer.noul, 'noul');
       continue;
     }
     if (native || own(answer, 'confidence')) probability(answer.confidence, 'confidence');
+    if (q.type === 'box') {
+      exactKeys(answer.box, ['top', 'bottom', 'left', 'right'], 'box', 'INVALID_RESPONSE');
+      Object.values(answer.box).forEach(value => probability(value, 'box edge'));
+      check(answer.box.left < answer.box.right && answer.box.top < answer.box.bottom,
+        'Box edges must enclose a positive area.', 'INVALID_RESPONSE');
+      continue;
+    }
     if (q.type === 'choice' && q.options) {
       validateTypedChoice(answer, q.options, probabilityDecimalPlaces);
       continue;
@@ -195,7 +214,7 @@ export function validateResult(input, questions, options = {}) {
     if (q.type === 'choice') {
       check(typeof answer.choice === 'string' && labels.includes(answer.choice), 'choice must be a supplied option.', 'INVALID_RESPONSE');
       const selected = answer.probabilities[answer.choice];
-      check(selected + 1e-6 >= Math.max(...Object.values(answer.probabilities)),
+      check(selected + 1e-6 >= Object.values(answer.probabilities).reduce((max, value) => Math.max(max, value), 0),
         'choice must select a highest-probability option.', 'INVALID_RESPONSE');
     } else {
       exactKeys(answer.legend, labels, 'legend', 'INVALID_RESPONSE');
@@ -215,7 +234,7 @@ export function validateResult(input, questions, options = {}) {
     if (own(result.usage, field)) check(Number.isSafeInteger(result.usage[field]) && result.usage[field] >= 0, 'Invalid cache token count.', 'INVALID_RESPONSE');
   }
   for (const field of ['input_tokens', 'output_tokens']) {
-    check((!native && result.usage[field] === null) ||
+    check(((!native || nullableUsage) && result.usage[field] === null) ||
       (Number.isSafeInteger(result.usage[field]) && result.usage[field] >= 0),
       'Token counts must be nonnegative safe integers.', 'INVALID_RESPONSE');
   }

package/src/version.mjs

@@ -1,2 +1,2 @@
 /** Keep in sync with package.json; scripts/check.mjs verifies the release version. */
-export const VERSION = '0.1.1';
+export const VERSION = '0.1.3';