timmy-talking-turd/src/vision-corpus.js

// Contract for the deterministic vision corpus under tests/fixtures/vision-corpus.
//
// The corpus exists to prove one claim continuously: every provider response Timmy
// receives is either a schema-valid visible-field suggestion or it fails closed.
// Fixtures are synthetic images generated by scripts/build_vision_corpus.py; no real
// medical imagery, personal data, or third-party content is redistributable here.
import { readFile } from 'node:fs/promises';
import { createHash } from 'node:crypto';
import { join } from 'node:path';
import { parseVisionResponse, VISION_FAILURE_CODES } from './analysis.js';

export const VISION_CORPUS_LICENSE = 'CC0-1.0';

// Case classes the corpus must always cover, from issue #18.
export const VISION_CORPUS_CLASSES = Object.freeze([
  'stool',
  'non-stool',
  'blur',
  'glare',
  'empty-bowl',
  'malformed-response',
]);

export const VISION_CORPUS_OUTCOMES = Object.freeze(['suggestion', 'abstained', 'fail_closed']);

const ALLOWED_CLASSES = new Set(VISION_CORPUS_CLASSES);

export function validateCorpusManifest(manifest) {
  if (!manifest || typeof manifest !== 'object') throw new Error('vision corpus manifest must be an object');
  if (manifest.schemaVersion !== 1) throw new Error('vision corpus manifest must declare schemaVersion 1');
  if (manifest.license !== VISION_CORPUS_LICENSE) {
    throw new Error(`vision corpus must be redistributable under ${VISION_CORPUS_LICENSE}`);
  }
  if (!Array.isArray(manifest.cases) || manifest.cases.length === 0) throw new Error('vision corpus must list cases');
  const ids = new Set();
  for (const entry of manifest.cases) {
    if (!entry?.id) throw new Error('every corpus case needs an id');
    if (ids.has(entry.id)) throw new Error(`duplicate corpus case: ${entry.id}`);
    ids.add(entry.id);
    if (!ALLOWED_CLASSES.has(entry.caseClass)) throw new Error(`${entry.id} has an unsupported caseClass: ${entry.caseClass}`);
    if (entry.synthetic !== true) throw new Error(`${entry.id} must be a synthetic fixture`);
    if (entry.license !== VISION_CORPUS_LICENSE) throw new Error(`${entry.id} must record its ${VISION_CORPUS_LICENSE} license`);
    if (typeof entry.provenance !== 'string' || !entry.provenance.trim()) throw new Error(`${entry.id} must record provenance`);
    if (!/^[a-f0-9]{64}$/.test(String(entry.sha256 || ''))) throw new Error(`${entry.id} must record a sha256`);
    if (!VISION_CORPUS_OUTCOMES.includes(entry.expectedOutcome)) {
      throw new Error(`${entry.id} must declare an expectedOutcome from ${VISION_CORPUS_OUTCOMES.join(', ')}`);
    }
    if (!('providerContent' in entry)) throw new Error(`${entry.id} must record the provider response it replays`);
  }
  for (const required of VISION_CORPUS_CLASSES) {
    if (!manifest.cases.some(entry => entry.caseClass === required)) {
      throw new Error(`vision corpus is missing the required ${required} case`);
    }
  }
  return manifest;
}

export function classifyVisionOutcome(providerContent) {
  let parsed;
  try {
    parsed = parseVisionResponse(providerContent);
  } catch (error) {
    const reason = error?.code === VISION_FAILURE_CODES.invalidJson
      ? 'unparsable_content'
      : error?.code === VISION_FAILURE_CODES.invalidFields
        ? 'out_of_range_or_missing_fields'
        : 'unexpected_error';
    return { outcome: 'fail_closed', reason, detail: error.message };
  }
  if (parsed.status === 'suggestion') {
    return {
      outcome: 'suggestion',
      reason: 'schema_valid_suggestion',
      bristolType: parsed.bristolType,
      color: parsed.color,
      confidence: parsed.confidence,
    };
  }
  if (parsed.status === 'needs_user_input') {
    return {
      outcome: 'abstained',
      reason: parsed.abstainedFor,
      detail: parsed.reason,
    };
  }
  return { outcome: 'fail_closed', reason: 'unparsable_content', detail: 'The response could not be used.' };
}

export async function loadVisionCorpus(directory) {
  const manifestPath = join(directory, 'manifest.json');
  let manifest;
  try {
    manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
  } catch (error) {
    throw new Error(`vision corpus manifest could not be read at ${manifestPath}: ${error.message}`);
  }
  validateCorpusManifest(manifest);
  for (const entry of manifest.cases) {
    let bytes;
    try {
      bytes = await readFile(join(directory, entry.file));
    } catch {
      throw new Error(`${entry.id} is missing its fixture ${entry.file}`);
    }
    const digest = createHash('sha256').update(bytes).digest('hex');
    if (digest !== entry.sha256 || bytes.length !== entry.bytes) {
      throw new Error(`${entry.id} fixture ${entry.file} does not match its recorded sha256; regenerate the corpus instead of editing it`);
    }
  }
  return { ...manifest, directory };
}