enigma-memory 0.1.18 → 0.1.22

package/packages/vault/src/receipt.js

@@ -0,0 +1,459 @@
+// Enigma Cryptographic Memory Receipt Standard (v2).
+// Provides verifiable, portable, offline-provable state transition receipts
+// with cryptographically hiding commitments, Merkle inclusion/removal proofs,
+// operation-specific state transition consistency witnesses, and Ed25519 digital signatures.
+import crypto from 'node:crypto';
+import { MerkleSet, sha256Hex } from '../../core/src/index.js';
+
+export const MEMORY_RECEIPT_SCHEMA = 'enigma.memory_receipt.v2';
+
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const ED25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+
+/**
+ * Computes a cryptographically hiding leaf commitment from a memory plaintext and random blinding factor.
+ * Commitment = SHA-256(SHA-256(plaintext) || blinding_factor)
+ * @param {string} plaintext
+ * @param {Buffer|string} [blindingFactor] - 32-byte cryptographically random blinding factor
+ * @returns {{ commitment: string, blindingFactor: string, contentHash: string }}
+ */
+export function computeHidingCommitment(plaintext, blindingFactor = null) {
+  if (typeof plaintext !== 'string' || plaintext.length === 0) {
+    throw new TypeError('plaintext must be a non-empty string');
+  }
+
+  let r;
+  if (blindingFactor == null) {
+    r = crypto.randomBytes(32);
+  } else if (Buffer.isBuffer(blindingFactor)) {
+    if (blindingFactor.length !== 32) {
+      throw new TypeError(`blindingFactor Buffer must be exactly 32 bytes (received ${blindingFactor.length})`);
+    }
+    r = blindingFactor;
+  } else if (typeof blindingFactor === 'string') {
+    if (!/^[0-9a-fA-F]{64}$/.test(blindingFactor)) {
+      throw new TypeError('blindingFactor string must be exactly 64 hex characters (32 bytes)');
+    }
+    r = Buffer.from(blindingFactor, 'hex');
+  } else {
+    throw new TypeError('blindingFactor must be a 32-byte Buffer, 64-hex string, or null/undefined');
+  }
+
+  const contentHash = crypto.createHash('sha256').update(plaintext, 'utf8').digest('hex');
+  const commitment = crypto
+    .createHash('sha256')
+    .update(Buffer.from(contentHash, 'hex'))
+    .update(r)
+    .digest('hex');
+
+  return {
+    commitment,
+    blindingFactor: r.toString('hex'),
+    contentHash,
+  };
+}
+
+/**
+ * Verifies that a plaintext and blinding factor open to the given commitment.
+ * @param {string} plaintext
+ * @param {string} blindingFactorHex
+ * @param {string} expectedCommitmentHex
+ * @returns {boolean}
+ */
+export function verifyCommitmentOpening(plaintext, blindingFactorHex, expectedCommitmentHex) {
+  if (typeof blindingFactorHex !== 'string' || !/^[0-9a-fA-F]{64}$/.test(blindingFactorHex)) {
+    return false;
+  }
+  if (typeof expectedCommitmentHex !== 'string' || !/^[0-9a-fA-F]{64}$/.test(expectedCommitmentHex)) {
+    return false;
+  }
+  try {
+    const { commitment } = computeHidingCommitment(plaintext, blindingFactorHex);
+    return commitment === expectedCommitmentHex.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Computes canonical signable string for a memory receipt (excluding signature field).
+ * @param {Object} receipt
+ * @returns {string}
+ */
+export function getReceiptSignablePayload(receipt) {
+  return JSON.stringify({
+    schema: receipt.schema || MEMORY_RECEIPT_SCHEMA,
+    version: receipt.version || 2,
+    receipt_id: receipt.receipt_id,
+    memory_id: receipt.memory_id,
+    operation: receipt.operation,
+    commitment: receipt.commitment,
+    previous_root: receipt.previous_root,
+    new_root: receipt.new_root,
+    leaf_index: typeof receipt.leaf_index === 'number' ? receipt.leaf_index : 0,
+    timestamp: receipt.timestamp,
+    agent_pubkey: receipt.agent_pubkey,
+    metadata: receipt.metadata || {},
+  });
+}
+
+/**
+ * Creates and cryptographically signs a portable MemoryReceipt with Merkle state transition consistency.
+ * Supports append, revoke, and update operations with mathematical consistency witnesses.
+ * @param {Object} params
+ * @param {string} params.memoryId - Unique memory atom identifier
+ * @param {'append'|'update'|'revoke'} [params.operation='append']
+ * @param {string} params.plaintext - Raw memory text (used to derive hiding commitment)
+ * @param {Buffer|string} [params.blindingFactor] - Optional custom blinding factor
+ * @param {string} [params.previousRoot] - Prior Merkle root hash (must match computed root if priorCommitments given)
+ * @param {Array<string>} [params.priorCommitments=[]] - List of prior commitments to compute MerkleSet transition
+ * @param {string} [params.priorCommitment] - Required for 'update': the prior commitment being replaced
+ * @param {Buffer|string} params.signingSecretKey - 32-byte Ed25519 private key
+ * @param {Buffer|string} params.signingPublicKey - 32-byte Ed25519 public key
+ * @param {Object} [params.metadata]
+ * @returns {{ receipt: Object, opening: { blindingFactor: string, contentHash: string } }}
+ */
+export function createMemoryReceipt(params) {
+  if (!params.memoryId) throw new Error('memoryId is required');
+  if (!params.plaintext) throw new Error('plaintext is required to compute hiding commitment');
+  if (!params.signingSecretKey || !params.signingPublicKey) {
+    throw new Error('signingSecretKey and signingPublicKey are required');
+  }
+
+  const operation = params.operation || 'append';
+  if (!['append', 'update', 'revoke'].includes(operation)) {
+    throw new Error(`Unsupported receipt operation: "${operation}". Must be "append", "update", or "revoke".`);
+  }
+
+  // 1. Compute cryptographically hiding commitment
+  const { commitment, blindingFactor, contentHash } = computeHidingCommitment(
+    params.plaintext,
+    params.blindingFactor
+  );
+
+  // 2. Normalize and compute prior Merkle state
+  const priorCommitments = (params.priorCommitments || []).map(c => String(c).replace(/^sha256:/, '').toLowerCase());
+  const priorSet = new MerkleSet(priorCommitments);
+  const computedPreviousRoot = priorSet.root();
+  if (params.previousRoot && params.previousRoot !== computedPreviousRoot) {
+    throw new Error(`previousRoot mismatch: expected ${computedPreviousRoot}, got ${params.previousRoot}`);
+  }
+  const previousRoot = computedPreviousRoot;
+
+  let newCommitments;
+  let newSet;
+  let newRoot;
+  let leafIndex;
+  let inclusionProof = null;
+  let transitionProof;
+
+  if (operation === 'append') {
+    if (priorCommitments.includes(commitment)) {
+      throw new Error(`Cannot append existing commitment: ${commitment}`);
+    }
+    newCommitments = [...priorCommitments, commitment];
+    newSet = new MerkleSet(newCommitments);
+    newRoot = newSet.root();
+    inclusionProof = newSet.proveMembership(commitment);
+    leafIndex = inclusionProof.index;
+
+    transitionProof = {
+      type: 'merkle_set_consistency_witness',
+      operation: 'append',
+      prior_size: priorCommitments.length,
+      new_size: newCommitments.length,
+      prior_commitments: priorCommitments,
+    };
+  } else if (operation === 'revoke') {
+    if (!priorCommitments.includes(commitment)) {
+      throw new Error(`Cannot revoke commitment not present in prior commitments: ${commitment}`);
+    }
+    const priorInclusionProof = priorSet.proveMembership(commitment);
+    newCommitments = priorCommitments.filter(c => c !== commitment);
+    newSet = new MerkleSet(newCommitments);
+    newRoot = newSet.root();
+    leafIndex = priorInclusionProof.index;
+
+    let newNonMembershipProof = null;
+    if (newCommitments.length > 0) {
+      newNonMembershipProof = newSet.proveNonMembership(commitment);
+    }
+
+    transitionProof = {
+      type: 'merkle_set_consistency_witness',
+      operation: 'revoke',
+      prior_size: priorCommitments.length,
+      new_size: newCommitments.length,
+      prior_commitments: priorCommitments,
+      prior_inclusion_proof: priorInclusionProof,
+      new_non_membership_proof: newNonMembershipProof,
+    };
+  } else if (operation === 'update') {
+    const priorCommitment = params.priorCommitment
+      ? String(params.priorCommitment).replace(/^sha256:/, '').toLowerCase()
+      : null;
+    if (!priorCommitment || !priorCommitments.includes(priorCommitment)) {
+      throw new Error('Update operation requires a valid priorCommitment present in prior commitments');
+    }
+    const priorInclusionProof = priorSet.proveMembership(priorCommitment);
+    newCommitments = priorCommitments.filter(c => c !== priorCommitment).concat(commitment);
+    newSet = new MerkleSet(newCommitments);
+    newRoot = newSet.root();
+    inclusionProof = newSet.proveMembership(commitment);
+    leafIndex = inclusionProof.index;
+    transitionProof = {
+      type: 'merkle_set_consistency_witness',
+      operation: 'update',
+      prior_size: priorCommitments.length,
+      new_size: newCommitments.length,
+      prior_commitments: priorCommitments,
+      prior_commitment: priorCommitment,
+      prior_inclusion_proof: priorInclusionProof,
+    };
+  }
+
+  const receiptId = `rcpt_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+  const pubHex = Buffer.isBuffer(params.signingPublicKey)
+    ? params.signingPublicKey.toString('hex')
+    : params.signingPublicKey;
+  const privBuf = Buffer.isBuffer(params.signingSecretKey)
+    ? params.signingSecretKey
+    : Buffer.from(params.signingSecretKey, 'hex');
+
+  const unsignedReceipt = {
+    schema: MEMORY_RECEIPT_SCHEMA,
+    version: 2,
+    receipt_id: receiptId,
+    memory_id: params.memoryId,
+    operation,
+    commitment,
+    previous_root: previousRoot,
+    new_root: newRoot,
+    leaf_index: leafIndex,
+    inclusion_proof: inclusionProof,
+    transition_proof: transitionProof,
+    timestamp: new Date().toISOString(),
+    agent_pubkey: pubHex,
+    metadata: params.metadata || {},
+  };
+
+  const signable = getReceiptSignablePayload(unsignedReceipt);
+  const der = Buffer.concat([ED25519_PKCS8_PREFIX, privBuf]);
+  const privKeyObj = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  const signature = crypto.sign(null, Buffer.from(signable, 'utf8'), privKeyObj);
+
+  return {
+    receipt: {
+      ...unsignedReceipt,
+      signature: signature.toString('hex'),
+    },
+    opening: {
+      blindingFactor,
+      contentHash,
+    },
+  };
+}
+
+/**
+ * Completely offline, zero-dependency verification of a MemoryReceipt.
+ * Validates schema, Ed25519 signature, operation-specific Merkle inclusion/removal, state transition consistency, and optional plaintext opening.
+ * @param {Object} receipt
+ * @param {Object} [options]
+ * @param {string} [options.expectedAgentPubkey]
+ * @param {string} [options.plaintext] - If provided with blindingFactor, verifies hiding opening
+ * @param {string} [options.blindingFactor]
+ * @returns {{ ok: boolean, verified: boolean, receipt_id: string, memory_id: string, commitment: string, signatureValid: boolean, inclusionValid: boolean, transitionValid: boolean, openingValid?: boolean, errors: string[] }}
+ */
+export function verifyMemoryReceipt(receipt, options = {}) {
+  const errors = [];
+  if (!receipt || typeof receipt !== 'object') {
+    return { ok: false, verified: false, receipt_id: '', memory_id: '', commitment: '', signatureValid: false, inclusionValid: false, transitionValid: false, errors: ['Invalid receipt object'] };
+  }
+
+  if (receipt.schema !== MEMORY_RECEIPT_SCHEMA && receipt.schema !== 'enigma.memory_receipt.v1') {
+    errors.push(`Unrecognized receipt schema: ${receipt.schema}`);
+  }
+  if (!receipt.receipt_id) errors.push('Missing receipt_id');
+  if (!receipt.memory_id) errors.push('Missing memory_id');
+  const HASH_OR_PREFIX_RE = /^(sha256:)?[0-9a-fA-F]{64}$/;
+  if (!receipt.commitment || !/^[0-9a-fA-F]{64}$/.test(receipt.commitment)) errors.push('Invalid 64-hex commitment hash');
+  if (!receipt.previous_root || !HASH_OR_PREFIX_RE.test(receipt.previous_root)) errors.push('Invalid previous_root format');
+  if (!receipt.new_root || !HASH_OR_PREFIX_RE.test(receipt.new_root)) errors.push('Invalid new_root format');
+  if (!receipt.agent_pubkey || !/^[0-9a-fA-F]{64}$/.test(receipt.agent_pubkey)) errors.push('Invalid 64-hex agent_pubkey');
+  if (!receipt.signature || !/^[0-9a-fA-F]{128}$/.test(receipt.signature)) errors.push('Invalid 128-hex signature length');
+
+  const operation = receipt.operation || 'append';
+  if (!['append', 'update', 'revoke'].includes(operation)) {
+    errors.push(`Invalid receipt operation: ${operation}`);
+  }
+
+  if (options.expectedAgentPubkey && receipt.agent_pubkey !== options.expectedAgentPubkey) {
+    errors.push(`agent_pubkey mismatch: expected ${options.expectedAgentPubkey}, got ${receipt.agent_pubkey}`);
+  }
+
+  const normCommitment = String(receipt.commitment || '').replace(/^sha256:/, '').toLowerCase();
+
+  // 1. Verify Merkle Proof (inclusion for append/update, non-membership / removal for revoke)
+  let inclusionValid = false;
+  if (operation === 'append' || operation === 'update') {
+    if (!receipt.inclusion_proof || typeof receipt.inclusion_proof !== 'object') {
+      errors.push(`Missing or invalid Merkle inclusion_proof object for "${operation}" receipt`);
+    } else {
+      const proof = receipt.inclusion_proof;
+      const normProofVal = String(proof.value || '').replace(/^sha256:/, '').toLowerCase();
+
+      if (normProofVal !== normCommitment) {
+        errors.push(`Inclusion proof value substitution detected: proof.value (${proof.value}) does not match receipt.commitment (${receipt.commitment})`);
+      }
+
+      const valid = MerkleSet.verifyMembership(proof, receipt.new_root);
+      if (!valid) {
+        errors.push(`Merkle inclusion proof verification failed for root ${receipt.new_root}`);
+      } else if (normProofVal === normCommitment) {
+        if (typeof receipt.leaf_index === 'number' && typeof proof.index === 'number' && receipt.leaf_index !== proof.index) {
+          errors.push(`receipt.leaf_index mismatch: receipt signed index ${receipt.leaf_index}, but Merkle membership proof index is ${proof.index}`);
+        } else {
+          inclusionValid = true;
+        }
+      }
+    }
+  } else if (operation === 'revoke') {
+    // For revoke, inclusionValid signifies removal correctness
+    if (receipt.inclusion_proof !== null && receipt.inclusion_proof !== undefined) {
+      errors.push('Revoke receipt must not contain an active inclusion_proof in new_root');
+    } else {
+      inclusionValid = true;
+    }
+  }
+
+  // 2. Verify State Transition Consistency Witness (Operation-Specific)
+  let transitionValid = false;
+  if (!receipt.transition_proof || typeof receipt.transition_proof !== 'object') {
+    errors.push('Missing transition_proof in state transition receipt');
+  } else {
+    const tp = receipt.transition_proof;
+    if (tp.type === 'merkle_set_consistency_witness') {
+      if (tp.operation !== operation) {
+        errors.push(`Transition proof operation mismatch: receipt specifies "${operation}", witness specifies "${tp.operation}"`);
+      } else if (!Array.isArray(tp.prior_commitments)) {
+        errors.push('Missing or invalid prior_commitments array in transition_proof');
+      } else {
+        const priorCommitments = tp.prior_commitments.map(c => String(c).replace(/^sha256:/, '').toLowerCase());
+        const priorSet = new MerkleSet(priorCommitments);
+        const computedPriorRoot = priorSet.root();
+
+        if (computedPriorRoot !== receipt.previous_root) {
+          errors.push(`State transition root mismatch: recomputed prior root (${computedPriorRoot}) does not match receipt.previous_root (${receipt.previous_root})`);
+        } else if (operation === 'append') {
+          if (priorCommitments.includes(normCommitment)) {
+            errors.push(`State transition violation: appended commitment (${receipt.commitment}) already exists in prior_commitments`);
+          } else {
+            const expectedNewSet = new MerkleSet([...priorCommitments, normCommitment]);
+            const computedNewRoot = expectedNewSet.root();
+            if (computedNewRoot !== receipt.new_root) {
+              errors.push(`State transition continuity failed: recomputed new root (${computedNewRoot}) does not match receipt.new_root (${receipt.new_root})`);
+            } else if (receipt.inclusion_proof?.size !== (priorCommitments.length + 1)) {
+              errors.push(`State transition size mismatch: expected size ${priorCommitments.length + 1}, got ${receipt.inclusion_proof?.size}`);
+            } else {
+              transitionValid = true;
+            }
+          }
+        } else if (operation === 'revoke') {
+          if (!priorCommitments.includes(normCommitment)) {
+            errors.push(`State transition violation: revoked commitment (${receipt.commitment}) does not exist in prior_commitments`);
+          } else if (!tp.prior_inclusion_proof || typeof tp.prior_inclusion_proof !== 'object') {
+            errors.push('Missing prior_inclusion_proof in revoke transition_proof');
+          } else {
+            const priorMemValid = MerkleSet.verifyMembership(tp.prior_inclusion_proof, receipt.previous_root);
+            const expectedNewCommitments = priorCommitments.filter(c => c !== normCommitment);
+            const expectedNewSet = new MerkleSet(expectedNewCommitments);
+            const computedNewRoot = expectedNewSet.root();
+
+            if (!priorMemValid) {
+              errors.push(`Revoke state transition failed: prior_inclusion_proof invalid under previous_root ${receipt.previous_root}`);
+            } else if (typeof receipt.leaf_index === 'number' && typeof tp.prior_inclusion_proof?.index === 'number' && receipt.leaf_index !== tp.prior_inclusion_proof.index) {
+              errors.push(`receipt.leaf_index mismatch: revoke receipt signed index ${receipt.leaf_index}, but prior Merkle proof index is ${tp.prior_inclusion_proof.index}`);
+            } else if (computedNewRoot !== receipt.new_root) {
+              errors.push(`Revoke state transition failed: recomputed new root (${computedNewRoot}) does not match receipt.new_root (${receipt.new_root})`);
+            } else {
+              transitionValid = true;
+            }
+          }
+        } else if (operation === 'update') {
+          const priorComm = String(tp.prior_commitment || '').replace(/^sha256:/, '').toLowerCase();
+          if (!priorComm || !priorCommitments.includes(priorComm)) {
+            errors.push(`Update state transition violation: prior_commitment (${priorComm}) does not exist in prior_commitments`);
+          } else if (!tp.prior_inclusion_proof || typeof tp.prior_inclusion_proof !== 'object') {
+            errors.push('Missing prior_inclusion_proof in update transition_proof');
+          } else {
+            const priorMemValid = MerkleSet.verifyMembership(tp.prior_inclusion_proof, receipt.previous_root);
+            const expectedNewCommitments = priorCommitments.filter(c => c !== priorComm).concat(normCommitment);
+            const expectedNewSet = new MerkleSet(expectedNewCommitments);
+            const computedNewRoot = expectedNewSet.root();
+
+            if (!priorMemValid) {
+              errors.push(`Update state transition failed: prior_inclusion_proof invalid under previous_root ${receipt.previous_root}`);
+            } else if (computedNewRoot !== receipt.new_root) {
+              errors.push(`Update state transition failed: recomputed new root (${computedNewRoot}) does not match receipt.new_root (${receipt.new_root})`);
+            } else {
+              transitionValid = true;
+            }
+          }
+        }
+      }
+    } else {
+      errors.push(`Unrecognized transition_proof type: ${tp.type}`);
+    }
+  }
+
+  // 3. Verify Optional Plaintext & Blinding Factor Opening (must be provided as a pair if either is supplied)
+  let openingValid;
+  const hasPlaintext = options.plaintext !== undefined && options.plaintext !== null;
+  const hasBlindingFactor = options.blindingFactor !== undefined && options.blindingFactor !== null;
+
+  if (hasPlaintext || hasBlindingFactor) {
+    if (!hasPlaintext || !hasBlindingFactor) {
+      openingValid = false;
+      errors.push('Opening verification requires both plaintext and blindingFactor to be provided together');
+    } else {
+      openingValid = verifyCommitmentOpening(options.plaintext, options.blindingFactor, receipt.commitment);
+      if (!openingValid) {
+        errors.push('Provided plaintext and blinding factor do not open to receipt commitment');
+      }
+    }
+  }
+  // 4. Verify Cryptographic Ed25519 Signature
+  let signatureValid = false;
+  try {
+    const signable = getReceiptSignablePayload(receipt);
+    const pubBuf = Buffer.from(receipt.agent_pubkey, 'hex');
+    const der = Buffer.concat([ED25519_SPKI_PREFIX, pubBuf]);
+    const pubKeyObj = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+    const sigBuf = Buffer.from(receipt.signature, 'hex');
+
+    signatureValid = crypto.verify(null, Buffer.from(signable, 'utf8'), pubKeyObj, sigBuf);
+    if (!signatureValid) {
+      errors.push('Cryptographic Ed25519 signature verification failed');
+    }
+  } catch (err) {
+    errors.push(`Signature verification exception: ${err.message}`);
+  }
+
+  const ok = errors.length === 0 && signatureValid && inclusionValid && transitionValid && (openingValid === undefined || openingValid);
+
+  return {
+    ok,
+    verified: ok,
+    receipt_id: receipt.receipt_id || '',
+    memory_id: receipt.memory_id || '',
+    operation,
+    commitment: receipt.commitment || '',
+    previous_root: receipt.previous_root,
+    new_root: receipt.new_root,
+    signatureValid,
+    inclusionValid,
+    transitionValid,
+    openingValid,
+    errors,
+  };
+}

package/scripts/benchmark-optical-context.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import crypto from 'node:crypto';
+
+import {
+  countFrames,
+  decideContextTransport,
+  renderBitmapContext,
+  resolveProviderProfile,
+} from '../packages/snapcompact/src/index.js';
+
+const CLAIM_BOUNDARY = 'This deterministic transport benchmark reports layout, byte, token-heuristic, and caller-priced cost estimates only. It does not invoke a model and does not measure OCR accuracy, semantic recall, F1, latency, or provider delivery.';
+
+function usage() {
+  return [
+    'Usage: node scripts/benchmark-optical-context.mjs --fixture <text-file> --profile <json-file>',
+    '',
+    'The profile JSON must explicitly provide provider, model, vision, and costs with',
+    'textInputUsdPerMillion and imageInputUsdPerMillion. No credentials are read.',
+  ].join('\n');
+}
+
+function parseArguments(argv) {
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--help' || argument === '-h') return { help: true };
+    if (argument !== '--fixture' && argument !== '--profile') {
+      throw new Error(`Unknown argument: ${argument}`);
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${argument} requires a path`);
+    parsed[argument.slice(2)] = value;
+    index += 1;
+  }
+  if (!parsed.fixture || !parsed.profile) {
+    throw new Error('Both --fixture and --profile are required');
+  }
+  return parsed;
+}
+
+function requireFiniteNonNegative(value, field) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    throw new Error(`Profile ${field} must be a finite non-negative number`);
+  }
+  return value;
+}
+
+function loadProfile(profilePath) {
+  const profile = JSON.parse(fs.readFileSync(profilePath, 'utf8'));
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+    throw new Error('Profile must be a JSON object');
+  }
+  if (typeof profile.provider !== 'string' || !profile.provider.trim()) {
+    throw new Error('Profile provider is required');
+  }
+  if (typeof profile.model !== 'string' || !profile.model.trim()) {
+    throw new Error('Profile model is required');
+  }
+  if (typeof profile.vision !== 'boolean') {
+    throw new Error('Profile vision must be an explicit boolean');
+  }
+  if (!profile.costs || typeof profile.costs !== 'object') {
+    throw new Error('Profile costs are required for a cost decision');
+  }
+  requireFiniteNonNegative(profile.costs.textInputUsdPerMillion, 'costs.textInputUsdPerMillion');
+  requireFiniteNonNegative(profile.costs.imageInputUsdPerMillion, 'costs.imageInputUsdPerMillion');
+  for (const field of ['outputUsdPerMillion', 'decodeOutputTokens', 'decodeFixedUsd']) {
+    if (profile.costs[field] !== undefined) requireFiniteNonNegative(profile.costs[field], `costs.${field}`);
+  }
+  const provider = profile.provider.trim();
+  const model = profile.model.trim();
+  const resolved = resolveProviderProfile(provider, model);
+  if (!resolved) {
+    throw new Error(`No allowlisted bitmap profile exists for provider "${provider}" and model "${model}"`);
+  }
+  return { ...profile, provider, model, resolved };
+}
+
+function safeDecision(decision) {
+  return {
+    selected: decision.selected,
+    eligible: decision.eligible,
+    reason: decision.reason,
+    profile: decision.profile,
+    expectedReuse: decision.expectedReuse ?? null,
+    frameCount: decision.frameCount ?? null,
+    estimates: decision.estimates ?? null,
+  };
+}
+
+function main() {
+  const arguments_ = parseArguments(process.argv.slice(2));
+  if (arguments_.help) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+  const fixturePath = path.resolve(arguments_.fixture);
+  const profilePath = path.resolve(arguments_.profile);
+  const source = fs.readFileSync(fixturePath, 'utf8');
+  const profile = loadProfile(profilePath);
+  const renderOptions = {
+    limits: profile.limits,
+    tabWidth: profile.tabWidth,
+    collapseRepeatedLines: profile.collapseRepeatedLines,
+    repetition: profile.repetition,
+  };
+  const plan = countFrames(source, profile.resolved, renderOptions);
+  const decision = decideContextTransport({
+    source,
+    provider: profile.provider,
+    model: profile.model,
+    vision: profile.vision,
+    costs: profile.costs,
+    expectedReuse: profile.expectedReuse,
+    tokenEstimates: profile.tokenEstimates,
+    ...renderOptions,
+  });
+
+  let rendered;
+  try {
+    rendered = renderBitmapContext(source, { profile: profile.resolved, ...renderOptions });
+    const report = {
+      schema: 'enigma.optical_context_benchmark.v1',
+      deterministic: true,
+      credentialFree: true,
+      claimBoundary: CLAIM_BOUNDARY,
+      fixture: {
+        sha256: crypto.createHash('sha256').update(source, 'utf8').digest('hex'),
+        utf8Bytes: Buffer.byteLength(source, 'utf8'),
+        characters: source.length,
+      },
+      profile: {
+        id: profile.resolved.id,
+        provider: profile.provider,
+        model: profile.model,
+        vision: profile.vision,
+      },
+      layout: {
+        frames: plan.frameCount,
+        totalPixels: plan.pixelCount,
+        columns: plan.columns,
+        rowsPerFrame: plan.rowsPerFrame,
+      },
+      bitmap: {
+        bytes: rendered.receipt.byteCount,
+        frameBytes: rendered.pages.map((page) => page.bytes),
+        payloadDigest: rendered.receipt.payloadDigest,
+      },
+      decision: safeDecision(decision),
+    };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } finally {
+    for (const page of rendered?.pages || []) page.png.fill(0);
+    rendered = null;
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`Optical context benchmark refused to run: ${error.message}\n\n${usage()}\n`);
+  process.exitCode = 1;
+}