enigma-memory 0.1.17 → 0.1.22

package/packages/inference-runtime/src/privacy.js

@@ -0,0 +1,400 @@
+import { createHmac, randomBytes } from 'node:crypto';
+
+export const ENIGMA_PRIVACY_RECEIPT_SCHEMA = 'enigma.smart_privacy_receipt.v1';
+const MODES = new Set(['off', 'smart', 'full']);
+const ACTIONS = new Set(['removed', 'generalized', 'dropped', 'masked', 'preserved', 'preserved_approximate', 'kept', 'kept_approximate']);
+const referenceKey = randomBytes(32);
+const DETERMINISTIC_DETECTORS = Object.freeze([
+  ['email', /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi],
+  ['evm_wallet', /\b0x[a-fA-F0-9]{40}\b/g],
+  ['solana_wallet', /\b[1-9A-HJ-NP-Za-km-z]{32,44}\b/g],
+  ['ipv4', /\b(?:\d{1,3}\.){3}\d{1,3}\b/g, (value) => value.split('.').every((part) => Number(part) <= 255)],
+  ['phone', /(?:\+\d{1,3}[\s.-]?)?(?:\(\d{2,4}\)|\d{2,4})[\s.-]\d{3,4}[\s.-]\d{4}\b/g],
+  ['credit_card', /\b(?:\d[ -]*?){13,19}\b/g, luhn],
+  ['api_key', /\b(?:sk|pk|api|token|key)[_-](?:live|test)?[_-]?[A-Za-z0-9]{16,}\b/gi],
+  ['private_key', /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g],
+  ['gps', /(?<!\d)(?:-?(?:[1-8]?\d(?:\.\d+)?|90(?:\.0+)?))\s*[,/]\s*(?:-?(?:1[0-7]\d(?:\.\d+)?|\d?\d(?:\.\d+)?|180(?:\.0+)?))(?!\d)/g],
+]);
+
+function luhn(value) {
+  const digits = value.replace(/\D/g, '');
+  if (digits.length < 13 || digits.length > 19 || /^(\d)\1+$/.test(digits)) return false;
+  let sum = 0;
+  let double = false;
+  for (let index = digits.length - 1; index >= 0; index -= 1) {
+    let digit = Number(digits[index]);
+    if (double) { digit *= 2; if (digit > 9) digit -= 9; }
+    sum += digit;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}
+
+function reference(value) {
+  return createHmac('sha256', referenceKey).update(String(value)).digest('hex');
+}
+
+function normalizeMessages(value) {
+  if (!Array.isArray(value) || !value.length) throw new TypeError('messages must be a non-empty array');
+  return value.map((message, index) => {
+    if (!message || typeof message !== 'object') throw new TypeError(`messages[${index}] must be an object`);
+    const role = String(message.role || '');
+    if (!['system', 'user', 'assistant', 'tool'].includes(role)) throw new TypeError(`messages[${index}].role is invalid`);
+    if (typeof message.content !== 'string') throw new TypeError(`messages[${index}].content must be text for privacy minimization`);
+    return { ...message, role, content: message.content };
+  });
+}
+
+function deterministicSpans(text) {
+  const spans = [];
+  for (const [type, expression, valid] of DETERMINISTIC_DETECTORS) {
+    expression.lastIndex = 0;
+    let match;
+    while ((match = expression.exec(text))) {
+      if ((!valid || valid(match[0])) && match[0]) spans.push({ start: match.index, end: match.index + match[0].length, type, confidence: 1, action: 'masked', source: 'deterministic' });
+      if (expression.lastIndex === match.index) expression.lastIndex += 1;
+    }
+  }
+  return spans;
+}
+
+function normalizeSemanticSpans(value, length) {
+  if (!Array.isArray(value)) throw new Error('semantic privacy classifier must return a spans array');
+  return value.map((span, index) => {
+    if (!span || typeof span !== 'object') throw new TypeError(`privacy span ${index} is invalid`);
+    const start = Number(span.start);
+    const end = Number(span.end);
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end <= start || end > length) {
+      throw new TypeError(`privacy span ${index} is out of bounds`);
+    }
+    const type = String(span.type || 'personal_detail').toLowerCase().replace(/[^a-z0-9_]/g, '_').slice(0, 40);
+    const confidence = Number.isFinite(span.confidence) ? Math.max(0, Math.min(1, span.confidence)) : 0.5;
+    const action = ACTIONS.has(span.action) ? span.action : 'masked';
+    return { start, end, type: type || 'personal_detail', confidence, action, source: 'semantic', generalized: span.generalized ? String(span.generalized).slice(0, 120) : null };
+  });
+}
+
+function mergeSpans(spans) {
+  const ordered = [...spans].sort((a, b) => a.start - b.start || b.end - a.end || b.confidence - a.confidence);
+  const result = [];
+  for (const span of ordered) {
+    const overlap = result.find((current) => span.start < current.end && span.end > current.start);
+    if (!overlap) result.push(span);
+    else if (span.source === 'deterministic' && overlap.source !== 'deterministic') Object.assign(overlap, span);
+  }
+  return result.sort((a, b) => a.start - b.start);
+}
+
+function privacySegmentPairs(original, minimized, replacements) {
+  if (!replacements.length) return { youWrote: [['kept', original]], modelSaw: [['kept', minimized]] };
+  const youWrote = [];
+  const modelSaw = [];
+  let cursor = 0;
+  for (const replacement of replacements) {
+    if (replacement.start > cursor) {
+      const kept = original.slice(cursor, replacement.start);
+      youWrote.push(['kept', kept]);
+      modelSaw.push(['kept', kept]);
+    }
+    youWrote.push([replacement.type, original.slice(replacement.start, replacement.end)]);
+    modelSaw.push([replacement.type, replacement.replacement]);
+    cursor = replacement.end;
+  }
+  if (cursor < original.length) {
+    youWrote.push(['kept', original.slice(cursor)]);
+    modelSaw.push(['kept', original.slice(cursor)]);
+  }
+  return { youWrote, modelSaw };
+}
+function privacyChangeProof(original, replacements) {
+  return replacements.map((replacement) => {
+    const raw = original.slice(replacement.start, replacement.end);
+    return {
+      type: replacement.type,
+      action: replacement.action,
+      originalRef: reference(raw),
+      originalLength: raw.length,
+      replacementRef: reference(replacement.replacement),
+      replacementLength: replacement.replacement.length,
+    };
+  });
+}
+
+
+export function createSemanticPrivacyEngine(options = {}) {
+  const classifier = options.classifier || null;
+  if (classifier && classifier.local !== true) {
+    throw new TypeError('Smart Privacy classifier must execute locally inside the Enigma trust boundary');
+  }
+  const minimumConfidence = Number.isFinite(options.minimumConfidence) ? options.minimumConfidence : 0.72;
+  const classifierTimeoutMs = Number.isInteger(options.classifierTimeoutMs) ? options.classifierTimeoutMs : 8_000;
+  const externalSensitiveTypes = new Set(options.externalSensitiveTypes || [
+    'email', 'evm_wallet', 'solana_wallet', 'ipv4', 'phone', 'credit_card', 'api_key', 'private_key', 'gps',
+    'person', 'name', 'location', 'address', 'organization', 'account', 'medical', 'legal_matter',
+  ]);
+
+  async function classify(text, context) {
+    if (!classifier) throw new Error('semantic classifier is not configured');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('semantic privacy classifier timed out')), classifierTimeoutMs);
+    try {
+      const result = await classifier.classify(text, { ...context, signal: controller.signal });
+      return normalizeSemanticSpans(result?.spans ?? result, text.length);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return Object.freeze({
+    async minimize(messagesInput, input = {}) {
+      const mode = String(input.mode || 'smart').toLowerCase();
+      if (!MODES.has(mode)) throw new TypeError('privacy mode must be off, smart, or full');
+      const messages = normalizeMessages(messagesInput);
+      if (mode === 'off') {
+        let disposed = false;
+        const privateState = Object.freeze({
+          restore(value) { if (disposed) throw new Error('privacy state is disposed'); return String(value ?? ''); },
+          restoreChunk(value) { if (disposed) throw new Error('privacy state is disposed'); return String(value ?? ''); },
+          preview() { if (disposed) throw new Error('privacy state is disposed'); return []; },
+          dispose() { disposed = true; },
+          get disposed() { return disposed; },
+        });
+        return {
+          mode,
+          messages,
+          privateState,
+          receipt: { schema: ENIGMA_PRIVACY_RECEIPT_SCHEMA, mode, status: 'ready', summary: [], proof: [], promptRef: reference(messages.map((m) => m.content).join('\n')), rawValuesRetained: false },
+          safeForExternal: true,
+        };
+      }
+      const tokenByValue = new Map();
+      const valueByToken = new Map();
+      const typeCounts = new Map();
+      const summaries = [];
+      const proofs = [];
+      const previews = [];
+      const minimizedMessages = [];
+
+      for (let messageIndex = 0; messageIndex < messages.length; messageIndex += 1) {
+        const message = messages[messageIndex];
+        const deterministic = deterministicSpans(message.content);
+        let semantic;
+        try {
+          semantic = await classify(message.content, { mode, role: message.role, messageIndex });
+        } catch (error) {
+          if (options.failOpen === true) semantic = [];
+          else {
+            const privacyError = new Error(`semantic privacy minimization failed closed: ${error.message}`);
+            privacyError.code = 'privacy_unavailable';
+            throw privacyError;
+          }
+        }
+        const candidates = mergeSpans([...deterministic, ...semantic.filter((span) => span.confidence >= minimumConfidence)]);
+        const selected = candidates.filter((span) => {
+          if (span.action === 'preserved' || span.action === 'kept') return false;
+          if (mode === 'full') return true;
+          return externalSensitiveTypes.has(span.type) || span.source === 'deterministic';
+        });
+        let output = '';
+        let cursor = 0;
+        const replacements = [];
+        for (const span of selected) {
+          const raw = message.content.slice(span.start, span.end);
+          output += message.content.slice(cursor, span.start);
+          let replacement;
+          let action = span.action;
+          if ((span.action === 'generalized' || span.action === 'kept_approximate' || span.action === 'preserved_approximate') && span.generalized) {
+            replacement = span.generalized;
+            action = 'generalized';
+          } else {
+            replacement = tokenByValue.get(raw);
+            if (!replacement) {
+              const count = (typeCounts.get(span.type) || 0) + 1;
+              typeCounts.set(span.type, count);
+              replacement = `⟦${span.type}_${count}⟧`;
+              tokenByValue.set(raw, replacement);
+              valueByToken.set(replacement, raw);
+            }
+            action = span.action === 'dropped' || span.action === 'removed' ? 'removed' : 'masked';
+          }
+          output += replacement;
+          replacements.push({ ...span, replacement, action });
+          summaries.push({ type: span.type, action, token: replacement, reason: span.source === 'deterministic' ? 'high-confidence identifier' : 'local semantic classification' });
+          cursor = span.end;
+        }
+        output += message.content.slice(cursor);
+        minimizedMessages.push({ ...message, content: output });
+        proofs.push({ messageIndex, changes: privacyChangeProof(message.content, replacements) });
+        previews.push({ messageIndex, ...privacySegmentPairs(message.content, output, replacements) });
+      }
+
+      let disposed = false;
+      let streamBuffer = '';
+      const privateState = Object.freeze({
+        restore(value) {
+          if (disposed) throw new Error('privacy state is disposed');
+          let restored = String(value ?? '');
+          for (const [token, original] of valueByToken) restored = restored.split(token).join(original);
+          return restored;
+        },
+        restoreChunk(value, input = {}) {
+          if (disposed) throw new Error('privacy state is disposed');
+          streamBuffer += String(value ?? '');
+          let boundary = streamBuffer.length;
+          if (input.final !== true) {
+            const open = streamBuffer.lastIndexOf('⟦');
+            const close = streamBuffer.lastIndexOf('⟧');
+            if (open > close) boundary = open;
+          }
+          const ready = streamBuffer.slice(0, boundary);
+          streamBuffer = streamBuffer.slice(boundary);
+          let restored = ready;
+          for (const [token, original] of valueByToken) restored = restored.split(token).join(original);
+          return restored;
+        },
+        preview() {
+          if (disposed) throw new Error('privacy state is disposed');
+          return structuredClone(previews);
+        },
+        dispose() {
+          tokenByValue.clear();
+          valueByToken.clear();
+          typeCounts.clear();
+          previews.length = 0;
+          streamBuffer = '';
+          disposed = true;
+        },
+        get disposed() { return disposed; },
+      });
+      const unresolved = minimizedMessages.some((message) => deterministicSpans(message.content).length > 0);
+      const receipt = {
+        schema: ENIGMA_PRIVACY_RECEIPT_SCHEMA,
+        mode,
+        status: 'ready',
+        classifier: classifier.id || 'semantic-local',
+        summary: summaries.slice(0, 64),
+        proof: proofs,
+        promptRef: reference(messages.map((message) => message.content).join('\n')),
+        rawValuesRetained: false,
+      };
+      return { mode, messages: minimizedMessages, privateState, receipt, safeForExternal: !unresolved };
+    },
+  });
+}
+
+export function createClassifierAdapter(options = {}) {
+  if (typeof options.classify !== 'function') throw new TypeError('classifier adapter requires classify()');
+  return Object.freeze({ id: String(options.id || 'local-semantic-classifier'), local: options.local !== false, classify: options.classify });
+}
+
+export function createLocalEmbeddingSemanticClassifier(options = {}) {
+  const id = String(options.id || 'enigma-local-minilm-privacy');
+  const similarityThreshold = Number.isFinite(options.similarityThreshold) ? options.similarityThreshold : 0.46;
+  let providerPromise = null;
+  let prototypePromise = null;
+  let disposed = false;
+  const prototypes = Object.freeze({
+    person: 'a private person real name identity individual full name',
+    location: 'a private home address city location residence where someone lives',
+    organization: 'a private employer company workplace school institution organization',
+    medical: 'a private medical diagnosis health condition treatment patient information',
+    legal_matter: 'a confidential legal case lawsuit docket investigation legal matter',
+    account: 'a private account identifier username customer number membership',
+  });
+
+  async function provider() {
+    if (disposed) throw new Error('local privacy classifier is disposed');
+    if (!providerPromise) {
+      providerPromise = import('../../rag/src/embeddings.js').then(({ createEmbeddingProvider }) => createEmbeddingProvider({ modelType: 'neural' }));
+    }
+    return providerPromise;
+  }
+
+  async function embeddedPrototypes() {
+    if (!prototypePromise) {
+      prototypePromise = (async () => {
+        const embedding = await provider();
+        const entries = await Promise.all(Object.entries(prototypes).map(async ([type, text]) => [type, await embedding.embed(text)]));
+        return entries;
+      })();
+    }
+    return prototypePromise;
+  }
+
+  function directCandidates(text) {
+    const patterns = [
+      ['person', /\b(?:[Mm]y name is|[Cc]all me|[Ii] am)\s+([A-Z][\p{L}'-]+(?:\s+[A-Z][\p{L}'-]+){0,3})/gu],
+      ['location', /\b(?:i live in|my address is|located in|based in)\s+([^\n,.;]{2,100})/giu],
+      ['organization', /\b(?:i work at|employed by|my employer is|i study at)\s+([^\n,.;]{2,100})/giu],
+      ['medical', /\b(?:diagnosed with|my diagnosis is|my medical condition is)\s+([^\n,.;]{2,140})/giu],
+      ['legal_matter', /\b(?:my case|our lawsuit|docket number|legal matter)\s+(?:is\s+)?([^\n,.;]{2,140})/giu],
+      ['account', /\b(?:my username is|account number|customer id|member id)\s*(?:is|:)?\s*([^\s,.;]{2,100})/giu],
+    ];
+    const spans = [];
+    for (const [type, expression] of patterns) {
+      expression.lastIndex = 0;
+      let match;
+      while ((match = expression.exec(text))) {
+        const value = match[1];
+        const start = match.index + match[0].lastIndexOf(value);
+        spans.push({ start, end: start + value.length, type, confidence: 0.99, action: type === 'location' ? 'generalized' : 'masked', generalized: type === 'location' ? 'a private location' : null });
+      }
+    }
+    return spans;
+  }
+
+  function phraseCandidates(text) {
+    const common = new Set(['The', 'This', 'That', 'When', 'Where', 'What', 'Please', 'Enigma', 'I']);
+    const spans = [];
+    const expression = /\b[A-Z][\p{L}'-]{1,}(?:\s+[A-Z][\p{L}'-]{1,}){0,3}\b/gu;
+    let match;
+    while ((match = expression.exec(text))) {
+      if (!common.has(match[0]) && match[0].length <= 100) spans.push({ start: match.index, end: match.index + match[0].length, text: match[0] });
+    }
+    return spans.slice(0, 24);
+  }
+
+  return Object.freeze({
+    id,
+    local: true,
+    async classify(text) {
+      if (typeof text !== 'string') throw new TypeError('privacy classifier text must be a string');
+      const direct = directCandidates(text);
+      const covered = (candidate) => direct.some((span) => candidate.start < span.end && candidate.end > span.start);
+      const phrases = phraseCandidates(text).filter((candidate) => !covered(candidate));
+      if (!phrases.length) return { spans: direct };
+      const [{ cosineSimilarity }, embedding, prototypeEntries] = await Promise.all([
+        import('../../rag/src/embeddings.js'),
+        provider(),
+        embeddedPrototypes(),
+      ]);
+      for (const phrase of phrases) {
+        const contextStart = Math.max(0, phrase.start - 80);
+        const contextEnd = Math.min(text.length, phrase.end + 80);
+        const vector = await embedding.embed(`${phrase.text}. Context: ${text.slice(contextStart, contextEnd)}`);
+        let best = { type: null, score: -1 };
+        for (const [type, prototype] of prototypeEntries) {
+          const score = cosineSimilarity(vector, prototype);
+          if (score > best.score) best = { type, score };
+        }
+        if (best.score >= similarityThreshold) {
+          direct.push({
+            start: phrase.start,
+            end: phrase.end,
+            type: best.type,
+            confidence: Math.min(0.95, best.score),
+            action: best.type === 'location' ? 'generalized' : 'masked',
+            generalized: best.type === 'location' ? 'a private location' : null,
+          });
+        }
+      }
+      return { spans: direct };
+    },
+    async dispose() {
+      disposed = true;
+      if (providerPromise) await (await providerPromise).dispose();
+      providerPromise = null;
+      prototypePromise = null;
+    },
+  });
+}

package/packages/inference-runtime/src/video.js

@@ -0,0 +1,253 @@
+import { createHmac, randomBytes, randomUUID } from 'node:crypto';
+
+export const ENIGMA_VIDEO_JOB_SCHEMA = 'enigma.video_job.v1';
+export const ENIGMA_VIDEO_RESULT_SCHEMA = 'enigma.video_result.v1';
+
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled', 'expired']);
+const STATUS = new Set(['queued', 'running', ...TERMINAL]);
+const runtimeReferenceKey = randomBytes(32);
+
+function requiredString(value, field, maxLength = 16_000) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${field} must be a non-empty string`);
+  const normalized = value.trim();
+  if (normalized.length > maxLength) throw new TypeError(`${field} exceeds ${maxLength} characters`);
+  return normalized;
+}
+
+function integer(value, field, minimum, maximum, fallback) {
+  const candidate = value === undefined ? fallback : value;
+  if (!Number.isInteger(candidate) || candidate < minimum || candidate > maximum) {
+    throw new TypeError(`${field} must be an integer from ${minimum} to ${maximum}`);
+  }
+  return candidate;
+}
+
+function reference(value) {
+  return createHmac('sha256', runtimeReferenceKey).update(value).digest('hex');
+}
+
+function normalizeSourceImage(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const source = requiredString(value, 'sourceImage', 16 * 1024 * 1024);
+  if (source.startsWith('data:image/')) {
+    if (!/^data:image\/(?:png|jpeg|webp);base64,[A-Za-z0-9+/=]+$/.test(source)) {
+      throw new TypeError('sourceImage data URL must be base64 PNG, JPEG, or WebP');
+    }
+    return source;
+  }
+  const url = new URL(source);
+  if (url.protocol !== 'https:') throw new TypeError('sourceImage URL must use HTTPS');
+  return url.toString();
+}
+
+export function normalizeVideoRequest(input = {}) {
+  const sourceImage = normalizeSourceImage(input.sourceImage ?? input.source_image);
+  return {
+    model: requiredString(input.model, 'model', 160),
+    prompt: requiredString(input.prompt, 'prompt'),
+    kind: sourceImage ? 'image-to-video' : 'text-to-video',
+    sourceImage,
+    duration: integer(input.duration, 'duration', 1, 30, 5),
+    resolution: requiredString(input.resolution || '720p', 'resolution', 32),
+    aspectRatio: requiredString(input.aspectRatio ?? input.aspect_ratio ?? '16:9', 'aspectRatio', 16),
+    audio: input.audio === true,
+  };
+}
+
+function normalizeProviderStatus(value) {
+  const aliases = { pending: 'queued', processing: 'running', complete: 'succeeded', completed: 'succeeded', error: 'failed' };
+  const status = aliases[value] || value;
+  if (!STATUS.has(status)) throw new Error(`video provider returned unsupported status: ${value}`);
+  return status;
+}
+
+function normalizeVideoAsset(value) {
+  if (!value || typeof value !== 'object') throw new Error('video provider returned no asset');
+  if (typeof value.url === 'string') {
+    const url = new URL(value.url);
+    if (url.protocol !== 'https:' && url.protocol !== 'data:') throw new Error('video asset URL must use HTTPS or data:');
+    return { url: url.toString(), mimeType: value.mimeType || 'video/mp4' };
+  }
+  if (typeof value.base64 === 'string') {
+    if (value.base64.length > 192 * 1024 * 1024) throw new Error('video asset exceeds the 144 MiB decoded limit');
+    return { base64: value.base64, mimeType: value.mimeType || 'video/mp4' };
+  }
+  throw new Error('video asset requires url or base64');
+}
+
+export function createHttpVideoProvider(options = {}) {
+  const id = requiredString(options.id || 'http-video', 'provider id', 160);
+  const baseUrl = new URL(options.baseUrl);
+  const apiKey = requiredString(options.apiKey, 'apiKey', 4_096);
+  const models = [...new Set((options.models || []).map((model) => requiredString(model, 'model', 160)))];
+  if (!models.length) throw new TypeError('HTTP video provider requires models');
+  const queuePath = options.queuePath || 'videos/queue';
+  const retrievePath = options.retrievePath || 'videos/retrieve';
+  return Object.freeze({
+    id,
+    models: Object.freeze(models),
+    async queue(request, context = {}) {
+      const response = await fetch(new URL(queuePath, baseUrl), {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', ...(options.headers || {}) },
+        body: JSON.stringify({
+          model: request.model,
+          prompt: request.prompt,
+          duration: request.duration,
+          resolution: request.resolution,
+          aspect_ratio: request.aspectRatio,
+          audio: request.audio,
+          ...(request.sourceImage ? { source_image: request.sourceImage } : {}),
+        }),
+        signal: context.signal,
+      });
+      const payload = await response.json();
+      if (!response.ok) throw new Error(`video provider ${id} queue failed with HTTP ${response.status}`);
+      const providerJobId = payload.id ?? payload.job_id ?? payload.jobId;
+      return { providerJobId: requiredString(providerJobId, 'providerJobId', 512), status: normalizeProviderStatus(payload.status || 'queued') };
+    },
+    async retrieve(providerJobId, context = {}) {
+      const response = await fetch(new URL(retrievePath, baseUrl), {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', ...(options.headers || {}) },
+        body: JSON.stringify({ id: providerJobId }),
+        signal: context.signal,
+      });
+      const contentType = response.headers.get('content-type') || '';
+      if (response.ok && contentType.startsWith('video/')) {
+        return { status: 'succeeded', asset: { base64: Buffer.from(await response.arrayBuffer()).toString('base64'), mimeType: contentType.split(';')[0] } };
+      }
+      const payload = await response.json();
+      if (!response.ok) throw new Error(`video provider ${id} retrieve failed with HTTP ${response.status}`);
+      const asset = payload.asset || (payload.url ? { url: payload.url, mimeType: payload.mime_type } : null);
+      return {
+        status: normalizeProviderStatus(payload.status || (asset ? 'succeeded' : 'running')),
+        progress: Number.isFinite(payload.progress) ? Math.max(0, Math.min(100, payload.progress)) : null,
+        asset,
+        error: payload.error || null,
+        providerRequestId: response.headers.get('x-request-id') || null,
+      };
+    },
+    async cancel(providerJobId, context = {}) {
+      if (!options.cancelPath) return false;
+      const response = await fetch(new URL(options.cancelPath.replace(':id', encodeURIComponent(providerJobId)), baseUrl), {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}`, ...(options.headers || {}) },
+        signal: context.signal,
+      });
+      return response.ok;
+    },
+  });
+}
+
+export function createVideoBackend(options = {}) {
+  const providers = new Map();
+  const modelRoutes = new Map();
+  for (const candidate of options.providers || []) {
+    if (!candidate || typeof candidate.queue !== 'function' || typeof candidate.retrieve !== 'function') {
+      throw new TypeError('video provider requires queue() and retrieve()');
+    }
+    const id = requiredString(candidate.id, 'provider id', 160);
+    if (providers.has(id)) throw new TypeError(`duplicate video provider: ${id}`);
+    const models = [...new Set((candidate.models || []).map((model) => requiredString(model, 'model', 160)))];
+    if (!models.length) throw new TypeError(`video provider ${id} requires models`);
+    const provider = Object.freeze({ ...candidate, id, models: Object.freeze(models) });
+    providers.set(id, provider);
+    for (const model of models) {
+      if (modelRoutes.has(model)) throw new TypeError(`video model has multiple providers: ${model}`);
+      modelRoutes.set(model, provider);
+    }
+  }
+  const ttlMs = integer(options.ttlMs, 'ttlMs', 60_000, 24 * 60 * 60_000, 60 * 60_000);
+  const timeoutMs = integer(options.timeoutMs, 'timeoutMs', 1_000, 15 * 60_000, 120_000);
+  const jobs = new Map();
+
+  function publicJob(job) {
+    return {
+      schema: ENIGMA_VIDEO_JOB_SCHEMA,
+      id: job.id,
+      model: job.model,
+      provider: job.provider.id,
+      kind: job.kind,
+      status: job.status,
+      progress: job.progress,
+      createdAt: job.createdAt,
+      expiresAt: job.expiresAt,
+      promptRef: job.promptRef,
+      error: job.error,
+    };
+  }
+
+  async function withTimeout(operation) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('video provider timed out')), timeoutMs);
+    try { return await operation(controller.signal); } finally { clearTimeout(timer); }
+  }
+
+  return Object.freeze({
+    listModels() {
+      return [...modelRoutes].map(([model, provider]) => ({ model, provider: provider.id, modality: 'video' }));
+    },
+    async queue(input = {}) {
+      const request = normalizeVideoRequest(input);
+      const provider = modelRoutes.get(request.model);
+      if (!provider) throw new Error(`no video provider configured for model ${request.model}`);
+      const queued = await withTimeout((signal) => provider.queue(request, { signal }));
+      const now = Date.now();
+      const job = {
+        id: randomUUID(),
+        provider,
+        providerJobId: requiredString(queued.providerJobId, 'providerJobId', 512),
+        model: request.model,
+        kind: request.kind,
+        status: normalizeProviderStatus(queued.status || 'queued'),
+        progress: 0,
+        promptRef: reference(request.prompt),
+        createdAt: now,
+        expiresAt: now + ttlMs,
+        error: null,
+        usageRecorded: false,
+      };
+      jobs.set(job.id, job);
+      return publicJob(job);
+    },
+    async retrieve(id) {
+      const job = jobs.get(requiredString(id, 'job id', 512));
+      if (!job) throw new Error('video job not found');
+      if (Date.now() >= job.expiresAt && !TERMINAL.has(job.status)) job.status = 'expired';
+      if (job.status === 'expired') return publicJob(job);
+      if (!TERMINAL.has(job.status)) {
+        const result = await withTimeout((signal) => job.provider.retrieve(job.providerJobId, { signal }));
+        job.status = normalizeProviderStatus(result.status);
+        job.progress = result.progress ?? (job.status === 'succeeded' ? 100 : job.progress);
+        job.error = result.error ? String(result.error).slice(0, 1_000) : null;
+        if (job.status === 'succeeded') {
+          job.asset = normalizeVideoAsset(result.asset);
+          job.providerRequestId = result.providerRequestId || null;
+          if (!job.usageRecorded) {
+            job.usageRecorded = true;
+            await options.onUsage?.({ modality: 'video', provider: job.provider.id, model: job.model, units: 1, promptRef: job.promptRef });
+          }
+        }
+      }
+      return job.status === 'succeeded'
+        ? { schema: ENIGMA_VIDEO_RESULT_SCHEMA, job: publicJob(job), asset: job.asset, providerRequestId: job.providerRequestId, retention: 'caller-controlled' }
+        : publicJob(job);
+    },
+    async cancel(id) {
+      const job = jobs.get(requiredString(id, 'job id', 512));
+      if (!job) throw new Error('video job not found');
+      if (TERMINAL.has(job.status)) return publicJob(job);
+      await job.provider.cancel?.(job.providerJobId, {});
+      job.status = 'cancelled';
+      return publicJob(job);
+    },
+    sweep(now = Date.now()) {
+      let removed = 0;
+      for (const [id, job] of jobs) {
+        if (now >= job.expiresAt) { jobs.delete(id); removed += 1; }
+      }
+      return removed;
+    },
+  });
+}