sneakoscope 0.9.11 → 0.9.13

package/src/core/proof/selftest-proof-fixtures.mjs

@@ -0,0 +1,54 @@
+import { writeRouteCompletionProof } from './route-adapter.mjs';
+
+const CLAIM_TEXT = {
+  hard_blocker: 'Hard blocker unblocks incomplete active gate after repeated identical compliance stops.',
+  team_gate: 'Team selftest fixture reached Completion Proof gate before reflection validation.',
+  subagent_gate: 'Subagent selftest fixture records Completion Proof after subagent evidence.'
+};
+
+const DEFAULTS = {
+  hard_blocker: {
+    artifacts: ['hard-blocker.json', 'compliance-loop-guard.json'],
+    gateSource: 'selftest-hard-blocker',
+    unverified: ['selftest fixture does not claim a real Team run completed']
+  },
+  team_gate: {
+    artifacts: ['team-gate.json', 'team-session-cleanup.json'],
+    gateSource: 'selftest-route-gate',
+    unverified: ['selftest fixture does not claim a real Team implementation run completed']
+  },
+  subagent_gate: {
+    artifacts: ['team-gate.json', 'team-session-cleanup.json', 'reflection-gate.json'],
+    gateSource: 'selftest-subagent-gate',
+    unverified: ['selftest fixture records mocked subagent evidence only']
+  }
+};
+
+export async function writeSelftestRouteProof(root, {
+  missionId,
+  route = '$Team',
+  kind = 'team_gate',
+  artifacts = null,
+  gateSource = null,
+  unverified = null
+} = {}) {
+  const defaults = DEFAULTS[kind] || DEFAULTS.team_gate;
+  return writeRouteCompletionProof(root, {
+    missionId,
+    route,
+    status: 'verified_partial',
+    gate: { passed: true, source: gateSource || defaults.gateSource },
+    summary: { selftest: true, tests_passed: 1, manual_review_required: true },
+    artifacts: artifacts || defaults.artifacts,
+    evidence: {
+      route_gate: { passed: true },
+      commands: [{ cmd: 'sks selftest --mock', status: 'verified_partial' }]
+    },
+    claims: [{
+      id: `selftest-${kind.replaceAll('_', '-')}-proof`,
+      text: CLAIM_TEXT[kind] || CLAIM_TEXT.team_gate,
+      status: 'verified_partial'
+    }],
+    unverified: unverified || defaults.unverified
+  });
+}

package/src/core/proof/validation.mjs

@@ -0,0 +1,20 @@
+import { containsPlaintextSecret } from '../secret-redaction.mjs';
+import { COMPLETION_PROOF_SCHEMA, COMPLETION_PROOF_STATUSES } from './proof-schema.mjs';
+
+export function validateCompletionProof(proof = {}) {
+  const issues = [];
+  if (proof.schema !== COMPLETION_PROOF_SCHEMA) issues.push('schema');
+  if (!COMPLETION_PROOF_STATUSES.includes(proof.status)) issues.push('status');
+  if (!proof.summary || typeof proof.summary !== 'object') issues.push('summary');
+  if (!proof.evidence || typeof proof.evidence !== 'object') issues.push('evidence');
+  if (!Array.isArray(proof.claims)) issues.push('claims');
+  if (!Array.isArray(proof.unverified)) issues.push('unverified');
+  if (!Array.isArray(proof.blockers)) issues.push('blockers');
+  if (containsPlaintextSecret(proof)) issues.push('plaintext_secret');
+  if (proof.status === 'failed') issues.push('proof_failed');
+  return {
+    ok: issues.length === 0,
+    status: issues.length ? 'failed' : proof.status,
+    issues
+  };
+}

package/src/core/routes.mjs

@@ -532,8 +532,8 @@ export const COMMAND_CATALOG = [
   { name: 'root', usage: 'sks root [--json]', description: 'Show whether SKS is using a project root or the per-user global SKS runtime root.' },
   { name: 'deps', usage: 'sks deps check|install [tmux|codex|context7|all] [--yes]', description: 'Check or guided-install Node/npm PATH, Codex CLI/App, Context7, Browser tooling, Computer Use, tmux, and Homebrew on macOS.' },
   { name: 'codex-app', usage: 'sks codex-app [check|open|pat status|remote-control]', description: 'Check Codex App install, PAT-safe status, first-party MCP/plugin readiness, and Codex CLI 0.130.0+ remote-control availability.' },
-  { name: 'hooks', usage: 'sks hooks explain [--json]', description: 'Explain Codex hook events, config locations, handler support, and SKS hook policies without storing raw payloads.' },
-  { name: 'codex-lb', usage: 'sks codex-lb status|health|repair|setup --host <domain> --api-key <key>', description: 'Configure, health-check, or repair codex-lb provider auth by writing ~/.codex/config.toml, restoring CODEX_LB_API_KEY env auth from stored or legacy login-cache state, and preserving the shared Codex login cache unless explicitly requested.' },
+  { name: 'hooks', usage: 'sks hooks explain|status|trust-report|replay ... [--json]', description: 'Explain Codex hook events, config locations, handler support, replay fixtures, and SKS hook policies without storing raw payloads.' },
+  { name: 'codex-lb', usage: 'sks codex-lb status|health|metrics|doctor|circuit|repair|setup ...', description: 'Configure, health-check, repair, and record circuit evidence for codex-lb provider auth without confusing ChatGPT OAuth and proxy keys.' },
   { name: 'auth', usage: 'sks auth status|health|repair|setup --host <domain> --api-key <key>', description: 'Shortcut for codex-lb provider auth status, health, repair, and setup commands.' },
   { name: 'openclaw', usage: 'sks openclaw install|path|print [--dir path] [--force] [--json]', description: 'Generate an OpenClaw skill package so OpenClaw agents can discover and use local SKS workflows.' },
   { name: 'tmux', usage: 'sks | sks tmux open|check|status [--workspace name]', description: 'Open the default SKS tmux runtime with bare sks, or use tmux subcommands for explicit launch/check/status.' },
@@ -563,7 +563,8 @@ export const COMMAND_CATALOG = [
   { name: 'db', usage: 'sks db policy|scan|mcp-config|classify|check ...', description: 'Inspect and enforce database/Supabase safety policy.' },
   { name: 'eval', usage: 'sks eval run|compare|thresholds ...', description: 'Run deterministic context-quality and performance evidence checks.' },
   { name: 'harness', usage: 'sks harness fixture|review [--json]', description: 'Run Harness Growth Factory fixtures for forgetting, skills, experiments, tool taxonomy, permissions, MultiAgentV2, and tmux views.' },
-  { name: 'perf', usage: 'sks perf run|workflow [--json] [--iterations N] [--intent "task"] [--changed file1,file2]', description: 'Measure structured GPT-5.5/SKS performance budgets, including Proof Field workflow decisions and fast-lane evidence.' },
+  { name: 'perf', usage: 'sks perf run|workflow|cold-start [--json] [--iterations N]', description: 'Measure structured GPT-5.5/SKS performance budgets, including cold-start, Proof Field workflow decisions, and fast-lane evidence.' },
+  { name: 'proof', usage: 'sks proof show|latest|validate|export|smoke [--json|--md]', description: 'Show, validate, export, or smoke-write the unified Completion Proof Engine surface.' },
   { name: 'proof-field', usage: 'sks proof-field scan [--json] [--intent "task"] [--changed file1,file2]', description: 'Analyze Potential Proof Field cones, negative-work cache, and fast-lane eligibility for a change set.' },
   { name: 'skill-dream', usage: 'sks skill-dream status|run|record [--json]', description: 'Track generated-skill usage in lightweight JSON and periodically report keep, merge, prune, and improvement candidates without deleting skills automatically.' },
   { name: 'code-structure', usage: 'sks code-structure scan [--json]', description: 'Scan handwritten source files for 1000/2000/3000-line structure gates and split-review exceptions.' },

package/src/core/rust-accelerator.mjs

@@ -1,5 +1,8 @@
 import path from 'node:path';
-import { exists, packageRoot, runProcess, which } from './fsx.mjs';
+import { exists, packageRoot, readText, runProcess, which } from './fsx.mjs';
+import { sha256File } from './wiki-image/image-hash.mjs';
+import { validateImageVoxelLedger } from './wiki-image/validation.mjs';
+import { readImageVoxelLedger } from './wiki-image/image-voxel-ledger.mjs';
 
 export async function findRustAccelerator() {
   const env = process.env.SKS_RS_BIN || process.env.DCODEX_RS_BIN;
@@ -11,9 +14,58 @@ export async function findRustAccelerator() {
   return null;
 }
 
+export async function runRustOrFallback(command, args = [], fallbackFn = async () => null) {
+  const bin = await findRustAccelerator();
+  if (!bin) return normalizeAcceleratorResult(command, { engine: 'js', available: false, result: await fallbackFn() });
+  const result = await runProcess(bin, [command, ...args], { timeoutMs: 10000, maxOutputBytes: 1024 * 1024 }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+  if (result.code !== 0) return normalizeAcceleratorResult(command, { engine: 'js', available: true, rust_error: classifyRustError(command, result.stderr || result.stdout), result: await fallbackFn() });
+  return normalizeAcceleratorResult(command, { engine: 'rust', available: true, stdout: result.stdout.trim(), result: parseRustJson(result.stdout) });
+}
+
+export async function rustImageHash(file) {
+  return runRustOrFallback('image-hash', [file], async () => ({ ok: true, engine: 'js', path: file, sha256: await sha256File(file) }));
+}
+
+export async function rustVoxelValidate(file) {
+  return runRustOrFallback('voxel-validate', [file], async () => {
+    const validation = validateImageVoxelLedger(await readImageVoxelLedger(packageRoot(), file));
+    return { ok: validation.ok, engine: 'js', schema: 'sks.image-voxel-ledger.v1', images: validation.summary.images, anchors: validation.summary.anchors, issues: validation.issues };
+  });
+}
+
+export async function rustSecretScan(file) {
+  return runRustOrFallback('secret-scan', [file], async () => {
+    const text = await readText(file, '');
+    return { ok: !/(CODEX_ACCESS_TOKEN|OPENAI_API_KEY|CODEX_LB_API_KEY|sk-proj-|sk-clb-|github_pat_)/.test(text) };
+  });
+}
+
 export async function rustInfo() {
   const bin = await findRustAccelerator();
-  if (!bin) return { available: false };
+  const capabilities = ['compact-info', 'jsonl-tail', 'secret-scan', 'image-hash', 'voxel-validate'];
+  if (!bin) return { available: false, capabilities, packaging: 'source_checkout_or_optional_path', note: 'Rust accelerator available only from source checkout or SKS_RS_BIN until prebuilt packages exist.' };
   const result = await runProcess(bin, ['--version'], { timeoutMs: 3000, maxOutputBytes: 20_000 });
-  return { available: result.code === 0, bin, version: `${result.stdout}${result.stderr}`.trim() };
+  return { available: result.code === 0, bin, version: `${result.stdout}${result.stderr}`.trim(), capabilities, packaging: 'source_checkout_or_optional_path' };
+}
+
+function parseRustJson(text = '') {
+  try { return JSON.parse(text); } catch { return text.trim(); }
+}
+
+function classifyRustError(command, text = '') {
+  const s = String(text || '');
+  if (/unknown|Commands:|optional accelerator/i.test(s)) return { kind: 'command_missing', command, message: s };
+  return { kind: 'runtime_error', command, message: s };
+}
+
+function normalizeAcceleratorResult(command, value) {
+  const result = value.result && typeof value.result === 'object' ? value.result : { ok: false, value: value.result };
+  return {
+    command,
+    engine: value.engine,
+    available: Boolean(value.available),
+    rust_error: value.rust_error || null,
+    stdout: value.stdout || null,
+    result
+  };
 }

package/src/core/secret-redaction.mjs

@@ -0,0 +1,69 @@
+const SECRET_ENV_NAMES = [
+  'CODEX_ACCESS_TOKEN',
+  'OPENAI_API_KEY',
+  'CODEX_LB_API_KEY',
+  'ANTHROPIC_API_KEY',
+  'GITHUB_TOKEN',
+  'GITHUB_PAT'
+];
+
+const SECRET_PATTERNS = [
+  /\bsk-proj-[A-Za-z0-9_-]{12,}\b/g,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+  /\bsk-clb-[A-Za-z0-9_-]{8,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bghp_[A-Za-z0-9_]{20,}\b/g,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{16,}\b/gi,
+  /\b(?:access[_-]?token|api[_-]?key|secret|password|token)\s*[:=]\s*["']?[A-Za-z0-9._~+/=-]{12,}["']?/gi
+];
+
+export const REDACTION_MARKER = '[redacted]';
+
+export function redactSecrets(value, env = process.env) {
+  if (value == null) return value;
+  if (typeof value === 'string') return redactString(value, env);
+  if (Array.isArray(value)) return value.map((item) => redactSecrets(item, env));
+  if (typeof value === 'object') {
+    const out = {};
+    for (const [key, candidate] of Object.entries(value)) {
+      out[key] = secretKeyName(key) ? REDACTION_MARKER : redactSecrets(candidate, env);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function redactString(input = '', env = process.env) {
+  let out = String(input);
+  for (const name of SECRET_ENV_NAMES) {
+    const raw = env?.[name];
+    if (raw && raw.length >= 4) out = out.split(raw).join(REDACTION_MARKER);
+    out = out.replace(new RegExp(`(${name}\\s*[:=]\\s*)[^\\s"',}]+`, 'gi'), `$1${REDACTION_MARKER}`);
+  }
+  for (const pattern of SECRET_PATTERNS) out = out.replace(pattern, (match) => redactKeyValue(match));
+  return out;
+}
+
+export function containsPlaintextSecret(value, env = process.env) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value || {});
+  for (const name of SECRET_ENV_NAMES) {
+    const raw = env?.[name];
+    if (raw && raw.length >= 4 && text.includes(raw)) return true;
+  }
+  return SECRET_PATTERNS.some((pattern) => {
+    pattern.lastIndex = 0;
+    return pattern.test(text);
+  });
+}
+
+function secretKeyName(key = '') {
+  return /(?:access[_-]?token|api[_-]?key|secret|password|token)$/i.test(String(key || ''))
+    || SECRET_ENV_NAMES.includes(String(key || '').toUpperCase());
+}
+
+function redactKeyValue(match) {
+  const keyValue = String(match).match(/^([^:=]+[:=]\s*)/);
+  if (keyValue) return `${keyValue[1]}${REDACTION_MARKER}`;
+  if (/^Bearer\s+/i.test(match)) return `Bearer ${REDACTION_MARKER}`;
+  return REDACTION_MARKER;
+}

package/src/core/version-manager.mjs

@@ -308,13 +308,17 @@ async function syncPackageLockVersions(root, version) {
 }
 
 async function syncSourcePackageVersion(root, version) {
-  const file = path.join(root, 'src', 'core', 'fsx.mjs');
-  const text = await readFileMaybe(file);
-  if (!text) return { files: [], relative_files: [] };
-  const next = text.replace(/export const PACKAGE_VERSION = ['"][^'"]+['"];/, `export const PACKAGE_VERSION = '${version}';`);
-  if (next === text) return { files: [], relative_files: [] };
-  await writeTextAtomic(file, next);
-  return { files: [file], relative_files: [path.relative(root, file)] };
+  const files = [];
+  for (const rel of ['src/core/fsx.mjs', 'src/core/version.mjs']) {
+    const file = path.join(root, rel);
+    const text = await readFileMaybe(file);
+    if (!text) continue;
+    const next = text.replace(/export const PACKAGE_VERSION = ['"][^'"]+['"];/, `export const PACKAGE_VERSION = '${version}';`);
+    if (next === text) continue;
+    await writeTextAtomic(file, next);
+    files.push(file);
+  }
+  return { files, relative_files: files.map((file) => path.relative(root, file)) };
 }
 
 async function syncChangelogVersionSection(root, version) {

package/src/core/version.mjs

@@ -0,0 +1 @@
+export const PACKAGE_VERSION = '0.9.13';

package/src/core/wiki-image/bbox.mjs

@@ -0,0 +1,10 @@
+export function validateBbox(bbox, image = {}) {
+  const issues = [];
+  if (!Array.isArray(bbox) || bbox.length !== 4) return { ok: false, issues: ['bbox_shape'] };
+  const [x, y, width, height] = bbox.map(Number);
+  if (![x, y, width, height].every(Number.isFinite)) issues.push('bbox_number');
+  if (x < 0 || y < 0 || width <= 0 || height <= 0) issues.push('bbox_positive');
+  if (Number.isFinite(Number(image.width)) && x + width > Number(image.width)) issues.push('bbox_width_out_of_bounds');
+  if (Number.isFinite(Number(image.height)) && y + height > Number(image.height)) issues.push('bbox_height_out_of_bounds');
+  return { ok: issues.length === 0, issues };
+}

package/src/core/wiki-image/callout-parser.mjs

@@ -0,0 +1,16 @@
+export function parseGeneratedReviewCallouts(ledger = {}) {
+  const items = Array.isArray(ledger.callouts)
+    ? ledger.callouts
+    : Array.isArray(ledger.issues)
+      ? ledger.issues
+      : [];
+  return items.map((item, index) => ({
+    id: item.id || `callout-${String(index + 1).padStart(3, '0')}`,
+    image_id: item.image_id || item.imageId || ledger.image_id || null,
+    bbox: item.bbox || item.box || null,
+    label: item.label || item.title || item.issue || `Callout ${index + 1}`,
+    source: item.source || ledger.source || 'gpt-image-2-annotated-review',
+    evidence_path: item.evidence_path || ledger.path || null,
+    trust_score: item.trust_score ?? 0.82
+  }));
+}

package/src/core/wiki-image/computer-use-ledger.mjs

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { nowIso, packageRoot, readJson } from '../fsx.mjs';
+import { addVisualAnchor, readImageVoxelLedger, writeImageVoxelLedger } from './image-voxel-ledger.mjs';
+import { validateImageVoxelLedger } from './validation.mjs';
+
+export async function importComputerUseEvidence(root = packageRoot(), file, opts = {}) {
+  const ledger = await readJson(path.resolve(root, file), {});
+  const current = await readImageVoxelLedger(root);
+  const screens = Array.isArray(ledger.screens) ? ledger.screens : [];
+  const images = [
+    ...(current.images || []),
+    ...screens.map((screen) => ({
+      id: screen.id,
+      path: screen.path,
+      sha256: screen.sha256 || 'fixture',
+      width: screen.width,
+      height: screen.height,
+      source: screen.source || 'codex-computer-use',
+      captured_at: screen.captured_at || nowIso()
+    }))
+  ].filter((image, index, all) => image.id && all.findIndex((entry) => entry.id === image.id) === index);
+  let next = await writeImageVoxelLedger(root, { ...current, mission_id: opts.missionId || current.mission_id || null, images });
+  for (const action of ledger.actions || []) {
+    if (!action.bbox) continue;
+    const result = await addVisualAnchor(root, {
+      imageId: action.screen_id,
+      bbox: action.bbox,
+      label: action.target || action.type || 'Computer Use action',
+      source: 'codex-computer-use',
+      evidencePath: file,
+      route: opts.route || '$Computer-Use',
+      missionId: opts.missionId
+    });
+    next = result.ledger;
+  }
+  const validation = validateImageVoxelLedger(next, { requireAnchors: true, route: opts.route || '$Computer-Use' });
+  return { schema: 'sks.computer-use-image-voxel-import.v1', ok: validation.ok, mode: ledger.mode || 'mock', ledger: next, validation };
+}

package/src/core/wiki-image/image-hash.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+
+export async function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const input = fs.createReadStream(file);
+    input.on('error', reject);
+    input.on('data', (chunk) => hash.update(chunk));
+    input.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+export async function imageDimensions(file) {
+  const handle = await fs.promises.open(file, 'r');
+  try {
+    const header = Buffer.alloc(32);
+    const { bytesRead } = await handle.read(header, 0, header.length, 0);
+    if (bytesRead >= 24 && header.slice(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+      return { width: header.readUInt32BE(16), height: header.readUInt32BE(20), format: 'png' };
+    }
+    if (bytesRead >= 10 && header[0] === 0xff && header[1] === 0xd8) return jpegDimensions(file);
+    return { width: null, height: null, format: 'unknown' };
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+async function jpegDimensions(file) {
+  const buf = await fs.promises.readFile(file);
+  let offset = 2;
+  while (offset < buf.length) {
+    if (buf[offset] !== 0xff) break;
+    const marker = buf[offset + 1];
+    const length = buf.readUInt16BE(offset + 2);
+    if (marker >= 0xc0 && marker <= 0xc3) {
+      return { width: buf.readUInt16BE(offset + 7), height: buf.readUInt16BE(offset + 5), format: 'jpeg' };
+    }
+    offset += 2 + length;
+  }
+  return { width: null, height: null, format: 'jpeg' };
+}

package/src/core/wiki-image/image-relation.mjs

@@ -0,0 +1,2 @@
+export { createImageRelation } from './visual-anchor.mjs';
+export { addImageRelation } from './image-voxel-ledger.mjs';

package/src/core/wiki-image/image-voxel-ledger.mjs

@@ -0,0 +1,147 @@
+import path from 'node:path';
+import { ensureDir, exists, nowIso, packageRoot, readJson, writeJsonAtomic } from '../fsx.mjs';
+import { emptyImageVoxelLedger } from './image-voxel-schema.mjs';
+import { sha256File, imageDimensions } from './image-hash.mjs';
+import { validateImageVoxelLedger } from './validation.mjs';
+import { createImageRelation, createVisualAnchor } from './visual-anchor.mjs';
+
+export function wikiImageLedgerPath(root = packageRoot()) {
+  return path.join(root, '.sneakoscope', 'wiki', 'image-voxel-ledger.json');
+}
+
+export function wikiImageAssetsPath(root = packageRoot()) {
+  return path.join(root, '.sneakoscope', 'wiki', 'image-assets.json');
+}
+
+export function wikiVisualAnchorsPath(root = packageRoot()) {
+  return path.join(root, '.sneakoscope', 'wiki', 'visual-anchors.json');
+}
+
+export function missionImageLedgerPath(root = packageRoot(), missionId) {
+  return path.join(root, '.sneakoscope', 'missions', missionId, 'image-voxel-ledger.json');
+}
+
+export function missionVisualAnchorsPath(root = packageRoot(), missionId) {
+  return path.join(root, '.sneakoscope', 'missions', missionId, 'visual-anchors.json');
+}
+
+export async function readImageVoxelLedger(root = packageRoot(), file = wikiImageLedgerPath(root)) {
+  if (!await exists(file)) return emptyImageVoxelLedger();
+  return readJson(file);
+}
+
+export async function writeImageVoxelLedger(root = packageRoot(), ledger = emptyImageVoxelLedger()) {
+  await ensureDir(path.dirname(wikiImageLedgerPath(root)));
+  const normalized = { ...emptyImageVoxelLedger(), ...ledger, generated_at: nowIso() };
+  await writeJsonAtomic(wikiImageLedgerPath(root), normalized);
+  await writeJsonAtomic(wikiImageAssetsPath(root), {
+    schema: 'sks.image-assets.v1',
+    version: normalized.version,
+    generated_at: normalized.generated_at,
+    images: normalized.images
+  });
+  await writeJsonAtomic(wikiVisualAnchorsPath(root), {
+    schema: 'sks.visual-anchors.v1',
+    version: normalized.version,
+    generated_at: normalized.generated_at,
+    anchors: normalized.anchors
+  });
+  if (normalized.mission_id) {
+    const missionDir = path.dirname(missionImageLedgerPath(root, normalized.mission_id));
+    await ensureDir(missionDir);
+    await writeJsonAtomic(missionImageLedgerPath(root, normalized.mission_id), normalized);
+    await writeJsonAtomic(missionVisualAnchorsPath(root, normalized.mission_id), {
+      schema: 'sks.visual-anchors.v1',
+      version: normalized.version,
+      generated_at: normalized.generated_at,
+      anchors: normalized.anchors
+    });
+  }
+  return normalized;
+}
+
+export async function ingestImage(root = packageRoot(), imagePath, opts = {}) {
+  if (!imagePath) throw new Error('image path required');
+  const absolute = path.resolve(root, imagePath);
+  const dims = await imageDimensions(absolute);
+  const sha256 = await sha256File(absolute);
+  const ledger = await readImageVoxelLedger(root);
+  const rel = path.relative(root, absolute).split(path.sep).join('/');
+  const id = opts.id || stableImageId(rel, sha256);
+  const image = {
+    id,
+    path: rel,
+    sha256,
+    width: dims.width,
+    height: dims.height,
+    format: dims.format,
+    source: opts.source || 'manual',
+    captured_at: opts.capturedAt || nowIso()
+  };
+  const images = [...(ledger.images || []).filter((entry) => entry.id !== id), image];
+  const next = await writeImageVoxelLedger(root, { ...ledger, mission_id: opts.missionId || ledger.mission_id || null, images });
+  const validation = validateImageVoxelLedger(next);
+  return { ok: validation.ok, image, ledger: next, validation };
+}
+
+export async function imageVoxelSummary(root = packageRoot(), ledgerFile = wikiImageLedgerPath(root)) {
+  const ledger = await readImageVoxelLedger(root, ledgerFile);
+  const validation = validateImageVoxelLedger(ledger);
+  return {
+    schema: 'sks.image-voxel-summary.v1',
+    status: validation.status,
+    ok: validation.ok,
+    images: ledger.images?.length || 0,
+    anchors: ledger.anchors?.length || 0,
+    anchor_count: ledger.anchors?.length || 0,
+    relations: ledger.relations?.length || 0,
+    issues: validation.issues
+  };
+}
+
+export async function addVisualAnchor(root = packageRoot(), input = {}) {
+  const ledger = await readImageVoxelLedger(root);
+  const image = (ledger.images || []).find((entry) => entry.id === input.imageId);
+  const anchor = createVisualAnchor({
+    id: input.id || stableAnchorId(input.imageId, input.label, ledger.anchors?.length || 0),
+    imageId: input.imageId,
+    bbox: input.bbox,
+    label: input.label,
+    source: input.source || 'manual',
+    evidencePath: input.evidencePath || null,
+    trustScore: input.trustScore ?? 0.82,
+    route: input.route || null,
+    claimId: input.claimId || null
+  });
+  const anchors = [...(ledger.anchors || []).filter((entry) => entry.id !== anchor.id), anchor];
+  const next = await writeImageVoxelLedger(root, { ...ledger, mission_id: input.missionId || ledger.mission_id || null, anchors });
+  const validation = validateImageVoxelLedger(next, { requireAnchors: true, route: input.route || '$Wiki' });
+  return { ok: validation.ok && Boolean(image), anchor, ledger: next, validation: image ? validation : { ...validation, ok: false, issues: [...validation.issues, `missing_image:${input.imageId}`] } };
+}
+
+export async function addImageRelation(root = packageRoot(), input = {}) {
+  const ledger = await readImageVoxelLedger(root);
+  const relation = createImageRelation({
+    type: input.type || 'before_after',
+    beforeImageId: input.beforeImageId,
+    afterImageId: input.afterImageId,
+    anchors: input.anchors || [],
+    verification: input.verification || 'changed-screen-recheck',
+    status: input.status || 'verified_partial'
+  });
+  const relations = [...(ledger.relations || []), relation];
+  const next = await writeImageVoxelLedger(root, { ...ledger, mission_id: input.missionId || ledger.mission_id || null, relations });
+  const validation = validateImageVoxelLedger(next, { requireAnchors: true, requireRelations: true, route: input.route || '$Wiki' });
+  return { ok: validation.ok, relation, ledger: next, validation };
+}
+
+function stableImageId(rel, sha256) {
+  const base = path.basename(rel).replace(/\.[^.]+$/, '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-|-$/g, '') || 'image';
+  return `${base}-${sha256.slice(0, 8)}`;
+}
+
+function stableAnchorId(imageId = 'image', label = 'anchor', index = 0) {
+  const image = String(imageId || 'image').replace(/[^A-Za-z0-9_-]+/g, '-').slice(0, 40) || 'image';
+  const slug = String(label || 'anchor').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-|-$/g, '').slice(0, 32) || 'anchor';
+  return `${image}-${slug}-${String(index + 1).padStart(3, '0')}`;
+}

package/src/core/wiki-image/image-voxel-schema.mjs

@@ -0,0 +1,16 @@
+import { PACKAGE_VERSION, nowIso } from '../fsx.mjs';
+
+export const IMAGE_VOXEL_LEDGER_SCHEMA = 'sks.image-voxel-ledger.v1';
+
+export function emptyImageVoxelLedger(overrides = {}) {
+  return {
+    schema: IMAGE_VOXEL_LEDGER_SCHEMA,
+    version: PACKAGE_VERSION,
+    generated_at: nowIso(),
+    mission_id: null,
+    images: [],
+    anchors: [],
+    relations: [],
+    ...overrides
+  };
+}

package/src/core/wiki-image/proof-linker.mjs

@@ -0,0 +1,12 @@
+import { imageVoxelSummary } from './image-voxel-ledger.mjs';
+
+export async function imageVoxelProofEvidence(root, ledgerFile) {
+  const summary = await imageVoxelSummary(root, ledgerFile);
+  return {
+    schema: 'sks.image-voxel-proof-link.v1',
+    ok: summary.ok,
+    evidence: {
+      image_voxels: summary
+    }
+  };
+}

package/src/core/wiki-image/validation.mjs

@@ -0,0 +1,53 @@
+import { IMAGE_VOXEL_LEDGER_SCHEMA } from './image-voxel-schema.mjs';
+import { validateBbox } from './bbox.mjs';
+
+export function validateImageVoxelLedger(ledger = {}, opts = {}) {
+  const issues = [];
+  if (ledger.schema !== IMAGE_VOXEL_LEDGER_SCHEMA) issues.push('schema');
+  const images = Array.isArray(ledger.images) ? ledger.images : [];
+  const anchors = Array.isArray(ledger.anchors) ? ledger.anchors : [];
+  const relations = Array.isArray(ledger.relations) ? ledger.relations : [];
+  const imageById = new Map();
+  const anchorById = new Map();
+  for (const image of images) {
+    if (!image.id) issues.push('image_id');
+    if (image.id && imageById.has(image.id)) issues.push(`duplicate_image:${image.id}`);
+    if (image.id) imageById.set(image.id, image);
+    if (!image.path) issues.push(`image_path:${image.id || 'unknown'}`);
+    if (!image.sha256) issues.push(`image_sha256:${image.id || 'unknown'}`);
+    if (!Number.isFinite(Number(image.width)) || !Number.isFinite(Number(image.height))) issues.push(`image_dimensions:${image.id || 'unknown'}`);
+  }
+  if (opts.requireAnchors && anchors.length === 0) issues.push(`missing_anchors:${opts.route || 'visual-route'}`);
+  for (const anchor of anchors) {
+    if (!anchor.id) issues.push('anchor_id');
+    if (anchor.id && anchorById.has(anchor.id)) issues.push(`duplicate_anchor:${anchor.id}`);
+    if (anchor.id) anchorById.set(anchor.id, anchor);
+    if (!anchor.image_id || !imageById.has(anchor.image_id)) issues.push(`anchor_image_ref:${anchor.id || 'unknown'}`);
+    if (anchor.bbox) {
+      const image = imageById.get(anchor.image_id) || {};
+      if (!Number.isFinite(Number(image.width)) || !Number.isFinite(Number(image.height))) issues.push(`bbox_image_dimensions:${anchor.id || 'unknown'}`);
+      const bbox = validateBbox(anchor.bbox, image);
+      for (const issue of bbox.issues) issues.push(`${issue}:${anchor.id || 'unknown'}`);
+    } else {
+      issues.push(`anchor_bbox:${anchor.id || 'unknown'}`);
+    }
+  }
+  if (opts.requireRelations && relations.length === 0) issues.push(`missing_relations:${opts.route || 'visual-route'}`);
+  for (const relation of relations) {
+    if (relation.before_image_id && !imageById.has(relation.before_image_id)) issues.push(`relation_before:${relation.before_image_id}`);
+    if (relation.after_image_id && !imageById.has(relation.after_image_id)) issues.push(`relation_after:${relation.after_image_id}`);
+    for (const anchorId of relation.changed_anchor_ids || relation.anchors || []) {
+      if (!anchorById.has(anchorId)) issues.push(`relation_anchor:${anchorId}`);
+    }
+  }
+  return {
+    ok: issues.length === 0,
+    status: issues.length ? 'blocked' : (anchors.length ? 'verified_partial' : 'not_verified'),
+    issues,
+    summary: {
+      images: images.length,
+      anchors: anchors.length,
+      relations: relations.length
+    }
+  };
+}