sandoichi 0.5.0 → 0.6.1

package/index.mjs

@@ -7,7 +7,13 @@ export {
 } from './src/core.mjs';
 export { createRedactionProfile } from './src/redaction-profile.mjs';
 export { loadProjectRedactionProfile } from './src/redaction-config.mjs';
-export { detectProviderBody, listSemanticCandidates, transformProviderRequest } from './src/context-transform.mjs';
+export {
+  detectProviderBody,
+  listSemanticCandidates,
+  listSemanticJudgmentCandidates,
+  restoreSemanticJudgmentCandidates,
+  transformProviderRequest,
+} from './src/context-transform.mjs';
 export {
   DEFAULT_ACCOUNTING_WEIGHTS,
   PAIRED_ARMS,
@@ -24,6 +30,12 @@ export {
   SEMANTIC_SUMMARY_SCHEMA,
   validateSemanticSummary,
 } from './src/semantic-compactor.mjs';
+export {
+  buildSemanticJudgeRequest,
+  createSemanticJudge,
+  SEMANTIC_JUDGMENT_SCHEMA,
+} from './src/semantic-judge.mjs';
+export { createSemanticGate } from './src/semantic-gate.mjs';
 export { createProviderProxy } from './src/proxy.mjs';
 export { shakeHistoricalResult } from './src/history-shake.mjs';
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandoichi",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Bound repeated tool-output context in Claude Code and Codex with deterministic local routing and provider accounting.",
   "license": "MIT",
   "author": "yuzushi",

package/src/artifact-lifecycle.mjs

@@ -4,6 +4,23 @@ import path from 'node:path';
 export const DEFAULT_ARTIFACT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 export const DEFAULT_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024;
 
+export function reuseArtifact(destination, expectedContent) {
+  const { O_NOFOLLOW, O_NONBLOCK } = fs.constants;
+  if (!Number.isInteger(O_NOFOLLOW) || !Number.isInteger(O_NONBLOCK)) {
+    throw new Error('artifact storage requires no-follow open support');
+  }
+  const flags = fs.constants.O_RDONLY | O_NOFOLLOW | O_NONBLOCK;
+  const handle = fs.openSync(destination, flags);
+  try {
+    const stat = fs.fstatSync(handle);
+    if (!stat.isFile() || stat.nlink !== 1) throw new Error('artifact file is unsafe');
+    if (fs.readFileSync(handle, 'utf8') !== expectedContent) throw new Error('artifact content differs');
+    fs.fchmodSync(handle, 0o600);
+  } finally {
+    fs.closeSync(handle);
+  }
+}
+
 function validNumber(value, name) {
   if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${name} is invalid`);
   return value;

package/src/context-transform.mjs

@@ -320,6 +320,46 @@ export function listSemanticCandidates({ provider, body, model } = {}) {
     }));
 }
 
+export function listSemanticJudgmentCandidates({ provider, originalBody, transformedBody, model } = {}) {
+  const originalRecords = collectHistoryRecords(provider, originalBody);
+  const originalById = new Map(originalRecords.map((record) => [record.id, record]));
+  return collectHistoryRecords(provider, transformedBody)
+    .filter((record) => record.safe && record.historical)
+    .flatMap((preview) => {
+      const original = originalById.get(preview.id);
+      const originalText = resultText(original?.output);
+      const previewText = resultText(preview.output);
+      if (!original || originalText === null || previewText === null || originalText === previewText) return [];
+      return [{
+        id: preview.id,
+        provider,
+        model: model ?? null,
+        toolName: preview.toolName,
+        originalText,
+        previewText,
+        historical: preview.historical,
+        isError: preview.isError,
+        recoverable: historyArchiveMarker(previewText),
+        estimatedTokens: original.estimatedTokens,
+        previewTokens: preview.estimatedTokens,
+      }];
+    });
+}
+
+export function restoreSemanticJudgmentCandidates({ provider, originalBody, transformedBody, ids = [] } = {}) {
+  const restoreIds = new Set(ids);
+  const body = structuredClone(transformedBody);
+  if (restoreIds.size === 0) return body;
+  const originalById = new Map(collectHistoryRecords(provider, originalBody).map((record) => [record.id, record]));
+  for (const preview of collectHistoryRecords(provider, body)) {
+    if (!restoreIds.has(preview.id) || !preview.historical || !preview.safe) continue;
+    const original = originalById.get(preview.id);
+    if (!original?.safe || resultText(original.output) === null) continue;
+    replaceResult(preview.entry.item, preview.entry.key, structuredClone(original.output));
+  }
+  return body;
+}
+
 function carriesBreakpoint(value) {
   if (Array.isArray(value)) return value.some(carriesBreakpoint);
   if (!object(value)) return false;

package/src/history-archive.mjs

@@ -2,6 +2,8 @@ import { createHash, randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { reuseArtifact } from './artifact-lifecycle.mjs';
+
 const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
 const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
 
@@ -70,11 +72,11 @@ export function persistHistoryArtifact(artifact) {
     fs.writeFileSync(temporary, artifact.content, { flag: 'wx', mode: 0o600 });
     try { fs.linkSync(temporary, destination); }
     catch (error) {
-      if (error?.code !== 'EEXIST' || fs.readFileSync(destination, 'utf8') !== artifact.content) throw error;
+      if (error?.code !== 'EEXIST') throw error;
+      reuseArtifact(destination, artifact.content);
     }
   } finally {
     fs.rmSync(temporary, { force: true });
   }
-  fs.chmodSync(destination, 0o600);
   return artifact;
 }

package/src/hook-cli.mjs

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
 import { createReceipt, normalizeEvent, normalizePolicy, optimizeToolOutput } from './core.mjs';
-import { cleanupArtifacts } from './artifact-lifecycle.mjs';
+import { cleanupArtifacts, reuseArtifact } from './artifact-lifecycle.mjs';
 import { loadProjectRedactionProfile } from './redaction-config.mjs';
 import { defaultMetricsPath, recordMetrics } from './metrics.mjs';
 import {
@@ -86,12 +86,12 @@ function artifactPath(cwd, artifact) {
     fs.writeFileSync(temporary, artifact.content, { flag: 'wx', mode: 0o600 });
     try { fs.linkSync(temporary, destination); }
     catch (error) {
-      if (error?.code !== 'EEXIST' || fs.readFileSync(destination, 'utf8') !== artifact.content) throw error;
+      if (error?.code !== 'EEXIST') throw error;
+      reuseArtifact(destination, artifact.content);
     }
   } finally {
     fs.rmSync(temporary, { force: true });
   }
-  fs.chmodSync(destination, 0o600);
   cleanupArtifacts(directory, { preserveName: name });
   if (!artifactPresent(destination)) throw new Error('artifact storage limit removed the new artifact');
   return path.posix.join('.sando/sando', 'artifacts', name);

package/src/proxy.mjs

@@ -6,7 +6,12 @@ import { brotliDecompressSync, gunzipSync, inflateSync, zstdDecompressSync } fro
 
 import { estimateTokens } from './core.mjs';
 import { buildContextCaptureRecord, recordContextCapture } from './context-capture.mjs';
-import { detectProviderBody, listSemanticCandidates, transformProviderRequest } from './context-transform.mjs';
+import {
+  detectProviderBody,
+  listSemanticCandidates,
+  listSemanticJudgmentCandidates,
+  transformProviderRequest,
+} from './context-transform.mjs';
 import { publishF1Telemetry } from './f1-telemetry.mjs';
 import { recordProxyRequest } from './proxy-metrics.mjs';
 import {
@@ -407,9 +412,61 @@ async function observeSemanticCandidates({ provider, candidates, semanticCompact
   }
 }
 
+function createSemanticJudgeStats(candidates) {
+  return {
+    candidates: candidates.length,
+    attempted: candidates.length,
+    judged: 0,
+    losses: 0,
+    preserved: 0,
+    fallbacks: 0,
+    skipped: 0,
+    pending: candidates.length,
+  };
+}
+
+function createPendingSemanticJudgeStats() {
+  const stats = createSemanticJudgeStats([]);
+  stats.pending = 1;
+  return stats;
+}
+
+function scheduleSemanticJudgments({ provider, originalBody, transformedBody, model, semanticJudge, stats }) {
+  setImmediate(() => {
+    let candidates;
+    try {
+      candidates = listSemanticJudgmentCandidates({ provider, originalBody, transformedBody, model });
+    } catch {
+      stats.fallbacks += 1;
+      stats.pending = 0;
+      return;
+    }
+    Object.assign(stats, createSemanticJudgeStats(candidates));
+    void observeSemanticJudgments({ candidates, semanticJudge, stats });
+  });
+}
+
+async function observeSemanticJudgments({ candidates, semanticJudge, stats }) {
+  for (const candidate of candidates) {
+    try {
+      const result = await semanticJudge(candidate);
+      if (result?.status === 'judged') {
+        stats.judged += 1;
+        if (result.verdict === 'loss') stats.losses += 1;
+        else if (result.verdict === 'preserved') stats.preserved += 1;
+      } else if (result?.status === 'skipped') stats.skipped += 1;
+      else stats.fallbacks += 1;
+    } catch {
+      stats.fallbacks += 1;
+    } finally {
+      stats.pending -= 1;
+    }
+  }
+}
+
 export async function createProviderProxy({
   upstream, host = '127.0.0.1', port = 0, policy = {}, maxBodyBytes = DEFAULT_MAX_BODY_BYTES,
-  semanticCompactor, metricsPath, contextCapturePath, contextCaptureHost, contextSessionKey,
+  semanticCompactor, semanticJudge, metricsPath, contextCapturePath, contextCaptureHost, contextSessionKey,
   f1TelemetryPublisher = publishF1Telemetry, transformProviderRequests = false,
   historyArchiveRoot,
   env = process.env,
@@ -521,6 +578,18 @@ export async function createProviderProxy({
                 lastStats.semantic = stats;
                 setImmediate(() => observeSemanticCandidates({ provider, candidates, semanticCompactor, stats }));
               }
+              if (typeof semanticJudge === 'function' && transformed.changed) {
+                const stats = createPendingSemanticJudgeStats();
+                lastStats.semanticJudge = stats;
+                scheduleSemanticJudgments({
+                  provider,
+                  originalBody: parsed,
+                  transformedBody: transformed.body,
+                  model: recordModel,
+                  semanticJudge,
+                  stats,
+                });
+              }
             }
           } catch {
             recordProxyFailure({ env, provider, failureStage: 'optimization' });

package/src/redaction-profile.mjs

@@ -2,10 +2,6 @@ import { createHash } from 'node:crypto';
 
 const BUILT_IN_MATCHERS = Object.freeze([
   [/-----BEGIN [A-Z ]+ KEY-----[\s\S]*?-----END [A-Z ]+ KEY-----/g, '[REDACTED PRIVATE KEY]'],
-  [/(authorization\s*[:=]\s*(?!(?:bearer\s+)?\[REDACTED(?: (?:PRIVATE KEY|TOKEN))?\](?=$|[\s,"'}]))(?:bearer\s+)?)[^\s,"'}]+/gi,
-    (_match, prefix) => `${prefix}[REDACTED]`],
-  [/(["']?(?:api[_-]?key|access[_-]?token|password|secret|private[_-]?key)["']?\s*[:=]\s*["']?)(?!\[REDACTED(?: (?:PRIVATE KEY|TOKEN))?\](?=$|[\s,"'}]))[^\s,"'}]+/gi,
-    (_match, prefix) => `${prefix}[REDACTED]`],
   [/\b(?:sk|rk)-[A-Za-z0-9_-]{12,}\b/g, '[REDACTED TOKEN]'],
   [/\bgh[pousr]_[A-Za-z0-9_-]{12,}\b/g, '[REDACTED TOKEN]'],
   [/\bgithub_pat_[A-Za-z0-9_-]{20,}\b/g, '[REDACTED TOKEN]'],
@@ -20,6 +16,55 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+const REDACTION_WORD = 'REDACTED';
+const REDACTION_PLACEHOLDER = `[${REDACTION_WORD}]`;
+const REDACTION_VALUE = String.raw`\[${REDACTION_WORD}(?: (?:PRIVATE KEY|TOKEN))?\]`;
+const ASSIGNMENT_VALUE = String.raw`${REDACTION_VALUE}(?=$|[\s,"'}])|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\\n])*(?=\n|$)|'(?:\\.|[^'\\\n])*(?=\n|$)|[^\s,"'}]+`;
+
+function isRedactionPlaceholder(value) {
+  const unquoted = value.length >= 2 && ((value.startsWith('"') && value.endsWith('"'))
+    || (value.startsWith("'") && value.endsWith("'"))) ? value.slice(1, -1) : value;
+  return new RegExp(`^${REDACTION_VALUE}$`).test(unquoted);
+}
+
+function redactAssignment(prefix, value) {
+  if (isRedactionPlaceholder(value)) return `${prefix}${value}`;
+  const quote = value[0] === '"' || value[0] === "'" ? value[0] : '';
+  return `${prefix}${quote}${REDACTION_PLACEHOLDER}${quote}`;
+}
+
+function assignmentMatcher(keyPattern) {
+  return [
+    new RegExp(`(${keyPattern}\\s*[:=]\\s*)(${ASSIGNMENT_VALUE})`, 'gi'),
+    (_match, prefix, value) => redactAssignment(prefix, value),
+  ];
+}
+
+const AUTHORIZATION_MATCHER = [
+  new RegExp(
+    '(["\\\']?authorization["\\\']?\\s*[:=]\\s*(?:(?:bearer|basic)\\s+)?' + ')(' + ASSIGNMENT_VALUE + ')',
+    'gi',
+  ),
+  (_match, prefix, value) => redactAssignment(prefix, value),
+];
+const AUTHORIZATION_FIELD_MATCHER = [
+  new RegExp(
+    '(["\\\']?authorization["\\\']?\\s*[:=]\\s*)(?!(?:\\s*)(?:bearer|basic)\\s+)('
+      + '"(?:\\\\.|[^"\\\\])*"|\'(?:\\\\.|[^\'\\\\])*\'|[^\\r\\n]+)',
+    'gi',
+  ),
+  (_match, prefix, value) => {
+    const leading = value.match(/^\s*/u)?.[0] ?? '';
+    const withoutLeading = value.slice(leading.length);
+    const trailing = withoutLeading.match(/\s*$/u)?.[0] ?? '';
+    const body = trailing ? withoutLeading.slice(0, -trailing.length) : withoutLeading;
+    return `${prefix}${leading}${redactAssignment('', body)}${trailing}`;
+  },
+];
+const BUILT_IN_ASSIGNMENT_MATCHER = assignmentMatcher(
+  String.raw`["']?(?:api[_-]?key|access[_-]?token|password|secret|private[_-]?key)["']?`,
+);
+
 function compareCanonical(left, right) {
   const a = JSON.stringify(left);
   const b = JSON.stringify(right);
@@ -79,11 +124,10 @@ function customMatchers(rules) {
   const tokens = [];
   for (const rule of rules) {
     if (rule.type === 'assignment-key') {
-      const key = escapeRegExp(rule.key);
-      assignments.push([
-        new RegExp(`(?<![A-Za-z0-9_.-])(["']?${key}["']?\\s*[:=]\\s*["']?)(?!\\[REDACTED\\](?=$|[\\s,"'}]))[^\\s,"'}]+`, 'gi'),
-        (_match, prefix) => `${prefix}[REDACTED]`,
-      ]);
+    const key = escapeRegExp(rule.key);
+      assignments.push(assignmentMatcher(
+        String.raw`(?<![A-Za-z0-9_.-])["']?${key}["']?`,
+      ));
     } else {
       const maximum = rule.maxLength === null ? '' : rule.maxLength;
       tokens.push([
@@ -99,8 +143,9 @@ function applyMatchers(text, matchers) {
   let count = 0;
   for (const [pattern, replacement] of matchers) {
     text = text.replace(pattern, (...args) => {
-      count += 1;
-      return typeof replacement === 'function' ? replacement(...args) : replacement;
+      const next = typeof replacement === 'function' ? replacement(...args) : replacement;
+      if (next !== args[0]) count += 1;
+      return next;
     });
   }
   return { text, count };
@@ -110,9 +155,12 @@ export function createRedactionProfile(customRules = []) {
   const rules = normalizeRules(customRules);
   const custom = customMatchers(rules);
   const matchers = [
-    ...BUILT_IN_MATCHERS.slice(0, 3),
+    BUILT_IN_MATCHERS[0],
+    AUTHORIZATION_FIELD_MATCHER,
+    AUTHORIZATION_MATCHER,
+    BUILT_IN_ASSIGNMENT_MATCHER,
     ...custom.assignments,
-    ...BUILT_IN_MATCHERS.slice(3),
+    ...BUILT_IN_MATCHERS.slice(1),
     ...custom.tokens,
   ];
   const digest = `sha256:${createHash('sha256')

package/src/semantic-compactor.mjs

@@ -5,6 +5,8 @@ import { redact, hasSecret } from './secret-redaction.mjs';
 
 export const SEMANTIC_SUMMARY_SCHEMA = 'sando-semantic-summary/v1';
 
+// Ordered extraction guarantees grounding in source text, not preservation of every omitted fact.
+
 const DEFAULT_POLICY = Object.freeze({
   minInputTokens: 8000,
   maxSummaryRatio: 0.2,
@@ -48,7 +50,7 @@ export function buildSemanticPrompt({ provider, model, toolName, text, requiredF
   const required = facts(requiredFacts);
   return [
     `Schema: ${SEMANTIC_SUMMARY_SCHEMA}`,
-    'Summarize the historical tool result for a coding agent.',
+    'Return a concise extractive summary using only complete source lines in their original order; do not paraphrase or invent clauses.',
     'Keep exact paths, identifiers, errors, numbers, negations, and every required fact.',
     'Preserved facts must be copied verbatim from the tool result or required-facts list; do not invent or estimate counts.',
     'Return JSON only with schema, summary, and preservedFacts fields.',
@@ -82,6 +84,15 @@ export function validateSemanticSummary({
   if ((redactionProfile ? redactionProfile.hasSecret(summary) : hasSecret(summary))) {
     return { valid: false, reason: 'secret-detected', inputTokens, outputTokens };
   }
+  const redactedOriginal = redactionProfile ? redactionProfile.redact(originalText).text : redact(originalText).text;
+  const sourceLines = redactedOriginal.split(/\r?\n/);
+  let sourceIndex = 0;
+  for (const line of summary.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const matchIndex = sourceLines.indexOf(line, sourceIndex);
+    if (matchIndex < 0) return { valid: false, reason: 'summary-not-extractive', inputTokens, outputTokens };
+    sourceIndex = matchIndex + 1;
+  }
   return { valid: true, inputTokens, outputTokens };
 }
 

package/src/semantic-gate.mjs

@@ -0,0 +1,69 @@
+import {
+  listSemanticJudgmentCandidates,
+  restoreSemanticJudgmentCandidates,
+} from './context-transform.mjs';
+
+const DEFAULT_LOSS_THRESHOLD = 0.7;
+
+function lossThreshold(value) {
+  if (value === undefined) return DEFAULT_LOSS_THRESHOLD;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new TypeError('lossThreshold must be a number between 0 and 1');
+  }
+  return value;
+}
+
+export function createSemanticGate({ judge, lossThreshold: threshold } = {}) {
+  if (typeof judge !== 'function') throw new TypeError('judge must be a function');
+  const selectedThreshold = lossThreshold(threshold);
+
+  return async function gate({ provider, originalBody, transformedBody, model } = {}) {
+    const candidates = listSemanticJudgmentCandidates({
+      provider, originalBody, transformedBody, model,
+    });
+    const restoreIds = [];
+    const stats = {
+      candidates: candidates.length,
+      judged: 0,
+      losses: 0,
+      preserved: 0,
+      restored: 0,
+      fallbacks: 0,
+      skipped: 0,
+      lossThreshold: selectedThreshold,
+    };
+
+    for (const candidate of candidates) {
+      let result;
+      try {
+        result = await judge(candidate);
+      } catch {
+        stats.fallbacks += 1;
+        continue;
+      }
+      if (result?.status === 'judged') {
+        stats.judged += 1;
+        if (result.verdict === 'loss') {
+          stats.losses += 1;
+          if (Number.isFinite(result.lossProbability) && result.lossProbability >= selectedThreshold) {
+            restoreIds.push(candidate.id);
+          }
+        } else if (result.verdict === 'preserved') {
+          stats.preserved += 1;
+        } else {
+          stats.fallbacks += 1;
+        }
+      } else if (result?.status === 'skipped') {
+        stats.skipped += 1;
+      } else {
+        stats.fallbacks += 1;
+      }
+    }
+
+    const body = restoreSemanticJudgmentCandidates({
+      provider, originalBody, transformedBody, ids: restoreIds,
+    });
+    stats.restored = restoreIds.length;
+    return { body, stats };
+  };
+}

package/src/semantic-judge.mjs

@@ -0,0 +1,261 @@
+import { createHash } from 'node:crypto';
+
+import { estimateTokens } from './core.mjs';
+import { redact } from './secret-redaction.mjs';
+
+export const SEMANTIC_JUDGMENT_SCHEMA = 'sando-semantic-judgment/v1';
+const QUESTION_ID = 'preview_loses_diagnostic_evidence';
+
+const DEFAULT_POLICY = Object.freeze({
+  minInputTokens: 8000,
+  maxTextChars: 6000,
+  timeoutMs: 1500,
+  maxRequests: 20,
+  lossThreshold: 0.7,
+});
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function validatePolicy(policy) {
+  const result = { ...DEFAULT_POLICY, ...(policy ?? {}) };
+  if (!Number.isInteger(result.minInputTokens) || result.minInputTokens < 1
+    || !Number.isInteger(result.maxTextChars) || result.maxTextChars < 64
+    || !Number.isInteger(result.timeoutMs) || result.timeoutMs < 1
+    || !Number.isInteger(result.maxRequests) || result.maxRequests < 1
+    || !Number.isFinite(result.lossThreshold) || result.lossThreshold < 0 || result.lossThreshold > 1) {
+    throw new TypeError('invalid semantic judge policy');
+  }
+  return result;
+}
+
+function boundedText(text, maxChars) {
+  if (text.length <= maxChars) return { text, sampled: false };
+  const marker = '\n[sando semantic judge middle elided]\n';
+  if (maxChars <= marker.length) return { text: text.slice(0, maxChars), sampled: true };
+  const available = maxChars - marker.length;
+  const headChars = Math.ceil(available / 2);
+  return {
+    text: `${text.slice(0, headChars)}${marker}${text.slice(-available + headChars)}`,
+    sampled: true,
+  };
+}
+
+function redactedBounded(text, maxChars, redactionProfile) {
+  const safe = redactionProfile ? redactionProfile.redact(text) : redact(text);
+  const bounded = boundedText(safe.text, maxChars);
+  return { ...bounded, count: safe.count };
+}
+
+function prepareSemanticJudgeRequest(options) {
+  const {
+    originalText, previewText, maxTextChars = DEFAULT_POLICY.maxTextChars, redactionProfile,
+  } = options;
+  requireText(originalText, 'originalText');
+  requireText(previewText, 'previewText');
+  if (!Number.isInteger(maxTextChars) || maxTextChars < 64) throw new TypeError('maxTextChars is invalid');
+  if (typeof options.recoverable !== 'boolean') throw new TypeError('recoverable must be a boolean');
+
+  const original = redactedBounded(originalText, maxTextChars, redactionProfile);
+  const preview = redactedBounded(previewText, maxTextChars, redactionProfile);
+  return {
+    request: {
+      state: {
+        provider: typeof options.provider === 'string' ? options.provider : 'unknown',
+        model: typeof options.model === 'string' ? options.model : 'unknown',
+        tool: typeof options.toolName === 'string' ? options.toolName : 'unknown',
+        original: original.text,
+        preview: preview.text,
+        originalSampled: original.sampled,
+        previewSampled: preview.sampled,
+        recoverable: options.recoverable,
+      },
+      questions: {
+        [QUESTION_ID]: {
+          type: 'noul',
+          instructions: 'Does `preview` omit diagnostic information from `original` that a coding agent would need to diagnose the result? If `recoverable` is true, treat intentionally omitted information as available through the Sando recovery artifact.',
+          criteria: 'Answer yes only for task-relevant diagnostic evidence that is absent from the preview and not recoverable; answer no when the preview preserves the evidence or the omission is recoverable.',
+        },
+      },
+    },
+    redactions: original.count + preview.count,
+  };
+}
+
+function requireText(value, name) {
+  if (typeof value !== 'string') throw new TypeError(`${name} must be a string`);
+}
+
+export function buildSemanticJudgeRequest({
+  provider, model, toolName, originalText, previewText, recoverable = false,
+  maxTextChars = DEFAULT_POLICY.maxTextChars, redactionProfile,
+} = {}) {
+  return prepareSemanticJudgeRequest({
+    provider, model, toolName, originalText, previewText, recoverable, maxTextChars, redactionProfile,
+  }).request;
+}
+
+function cacheKey(candidate, request) {
+  return sha256(JSON.stringify({
+    schema: SEMANTIC_JUDGMENT_SCHEMA,
+    id: candidate.id ?? null,
+    provider: candidate.provider ?? null,
+    model: candidate.model ?? null,
+    toolName: candidate.toolName ?? null,
+    recoverable: candidate.recoverable === true,
+    state: request.state,
+  }));
+}
+
+function probability(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1 ? value : null;
+}
+
+function usageSummary(value) {
+  if (!object(value)) return null;
+  const result = {};
+  const fields = {
+    inputTokens: ['inputTokens', 'input_tokens'],
+    outputTokens: ['outputTokens', 'output_tokens'],
+  };
+  for (const [target, keys] of Object.entries(fields)) {
+    const tokenValue = keys.map((key) => value[key]).find(
+      (item) => Number.isSafeInteger(item) && item >= 0,
+    );
+    if (tokenValue !== undefined) result[target] = tokenValue;
+  }
+  return Object.keys(result).length ? result : null;
+}
+
+function resultBase(candidate, inputTokens, previewTokens) {
+  return {
+    schema: SEMANTIC_JUDGMENT_SCHEMA,
+    mode: 'shadow',
+    status: 'fallback',
+    id: typeof candidate.id === 'string' ? candidate.id : null,
+    inputTokens,
+    previewTokens,
+    omittedTokens: Math.max(0, inputTokens - previewTokens),
+    lossProbability: null,
+    cacheHit: false,
+  };
+}
+
+function validCandidate(candidate) {
+  return candidate && typeof candidate === 'object' && !Array.isArray(candidate);
+}
+
+async function evaluateWithTimeout(evaluate, request, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      const error = new Error('semantic judge timeout');
+      error.code = 'SEMANTIC_JUDGE_TIMEOUT';
+      reject(error);
+    }, timeoutMs);
+  });
+  const operation = Promise.resolve().then(() => evaluate(request, { signal: controller.signal }));
+  try {
+    return await Promise.race([operation, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function cachedResult(value, lossThreshold) {
+  const lossProbability = probability(value?.lossProbability);
+  if (lossProbability === null) return null;
+  const result = {
+    status: 'judged',
+    lossProbability,
+    verdict: lossProbability >= lossThreshold ? 'loss' : 'preserved',
+    cacheHit: true,
+  };
+  if (Number.isSafeInteger(value?.latencyMs) && value.latencyMs >= 0) result.latencyMs = value.latencyMs;
+  if (Number.isSafeInteger(value?.redactions) && value.redactions >= 0) result.redactions = value.redactions;
+  const usage = usageSummary(value?.usage);
+  if (usage) result.usage = usage;
+  return result;
+}
+
+export function createSemanticJudge({ evaluate, cache = new Map(), policy, redactionProfile } = {}) {
+  if (typeof evaluate !== 'function') throw new TypeError('semantic judge evaluate callback is required');
+  if (!cache || typeof cache.get !== 'function' || typeof cache.set !== 'function') {
+    throw new TypeError('semantic judge cache must implement get and set');
+  }
+  if (redactionProfile && typeof redactionProfile.redact !== 'function') {
+    throw new TypeError('redactionProfile is invalid');
+  }
+  const options = validatePolicy(policy);
+  const pending = new Map();
+  let requests = 0;
+
+  return async function judge(candidate = {}) {
+    if (!validCandidate(candidate)) throw new TypeError('semantic judge candidate must be an object');
+    requireText(candidate.originalText, 'originalText');
+    requireText(candidate.previewText, 'previewText');
+    const inputTokens = estimateTokens(candidate.originalText);
+    const previewTokens = estimateTokens(candidate.previewText);
+    const base = resultBase(candidate, inputTokens, previewTokens);
+    if (candidate.historical === false) return { ...base, status: 'skipped', reason: 'current-result' };
+    if (candidate.isError === true) return { ...base, status: 'skipped', reason: 'error-result' };
+    if (inputTokens < options.minInputTokens) return { ...base, status: 'skipped', reason: 'below-threshold' };
+
+    const prepared = prepareSemanticJudgeRequest({
+      provider: candidate.provider,
+      model: candidate.model,
+      toolName: candidate.toolName,
+      originalText: candidate.originalText,
+      previewText: candidate.previewText,
+      recoverable: candidate.recoverable === true,
+      maxTextChars: options.maxTextChars,
+      redactionProfile,
+    });
+    const request = prepared.request;
+    const key = cacheKey(candidate, request);
+    let cached;
+    try { cached = cachedResult(cache.get(key), options.lossThreshold); } catch { cached = null; }
+    if (cached) return { ...base, ...cached };
+    if (pending.has(key)) return { ...base, ...(await pending.get(key)), cacheHit: true };
+    if (requests >= options.maxRequests) return { ...base, reason: 'budget' };
+
+    requests += 1;
+    const started = Date.now();
+    const operation = (async () => {
+      let raw;
+      try {
+        raw = await evaluateWithTimeout(evaluate, request, options.timeoutMs);
+      } catch (error) {
+        return { ...base, reason: error?.code === 'SEMANTIC_JUDGE_TIMEOUT' ? 'timeout' : 'judge-error', latencyMs: Date.now() - started };
+      }
+      const lossProbability = probability(raw?.answers?.[QUESTION_ID]?.noul);
+      if (lossProbability === null) {
+        return { ...base, reason: 'invalid-response', latencyMs: Date.now() - started };
+      }
+      const judged = {
+        status: 'judged',
+        lossProbability,
+        verdict: lossProbability >= options.lossThreshold ? 'loss' : 'preserved',
+        cacheHit: false,
+        latencyMs: Number.isSafeInteger(raw?.elapsedMs) ? raw.elapsedMs : Date.now() - started,
+        usage: usageSummary(raw?.usage),
+        redactions: prepared.redactions,
+      };
+      try { cache.set(key, judged); } catch { /* cache is best-effort */ }
+      return { ...base, ...judged };
+    })();
+    pending.set(key, operation);
+    try {
+      return await operation;
+    } finally {
+      pending.delete(key);
+    }
+  };
+}