@attest-ai/core 0.6.0 → 1.0.0-rc.1

package/dist/esm/index.js

@@ -6,6 +6,15 @@ var STEP_AGENT_CALL = "agent_call";
 var STATUS_PASS = "pass";
 var STATUS_SOFT_FAIL = "soft_fail";
 var STATUS_HARD_FAIL = "hard_fail";
+var STATUS_NOT_EVALUATED = "not_evaluated";
+var REASON_PROVIDER_UNAVAILABLE = "provider_unavailable";
+var REASON_PROVIDER_NOT_CONFIGURED = "provider_not_configured";
+var REASON_SIMULATION = "simulation";
+var REASON_MISSING_EVIDENCE = "missing_evidence";
+var REASON_SHORT_CIRCUITED = "short_circuited";
+var OUTCOME_PASS = "pass";
+var OUTCOME_FAIL = "fail";
+var OUTCOME_SKIP = "skip";
 var TYPE_SCHEMA = "schema";
 var TYPE_CONSTRAINT = "constraint";
 var TYPE_TRACE = "trace";
@@ -31,6 +40,34 @@ function assertionId(id) {
 function agentId(id) {
   return id;
 }
+var FailureClass = {
+  BrokenCode: "broken_code",
+  FlakyJudge: "flaky_judge",
+  BadRubric: "bad_rubric",
+  MissingTraceData: "missing_trace_data",
+  StochasticVariance: "stochastic_variance"
+};
+function layerForType(assertionType) {
+  switch (assertionType) {
+    case "schema":
+      return 1;
+    case "constraint":
+      return 2;
+    case "trace":
+    case "trace_tree":
+      return 3;
+    case "content":
+      return 4;
+    case "embedding":
+      return 5;
+    case "llm_judge":
+      return 6;
+    case "plugin":
+      return 8;
+    default:
+      return 0;
+  }
+}
 
 // src/proto/errors.ts
 var ProtocolError = class extends Error {
@@ -57,6 +94,58 @@ var EngineTimeoutError = class extends Error {
     this.timeoutMs = timeoutMs;
   }
 };
+var ProtocolDesyncError = class extends Error {
+  diagnostics;
+  constructor(message, diagnostics) {
+    super(message);
+    this.name = "ProtocolDesyncError";
+    this.diagnostics = diagnostics;
+  }
+};
+
+// src/proto/diagnostics.ts
+var DEFAULT_BUFFER_SIZE = 32;
+var MAX_LINE_PREVIEW = 512;
+var ProtocolDiagnosticBuffer = class {
+  capacity;
+  entries = [];
+  constructor(capacity = DEFAULT_BUFFER_SIZE) {
+    if (capacity <= 0) {
+      throw new Error(
+        `ProtocolDiagnosticBuffer capacity must be positive, got ${capacity}`
+      );
+    }
+    this.capacity = capacity;
+  }
+  push(diagnostic) {
+    if (this.entries.length >= this.capacity) {
+      this.entries.shift();
+    }
+    this.entries.push(diagnostic);
+  }
+  snapshot() {
+    return this.entries.slice();
+  }
+  countWithin(windowMs, nowMs) {
+    const cutoff = nowMs - windowMs;
+    let count = 0;
+    for (let i = this.entries.length - 1; i >= 0; i -= 1) {
+      if (this.entries[i].timestampMs >= cutoff) {
+        count += 1;
+      } else {
+        break;
+      }
+    }
+    return count;
+  }
+  clear() {
+    this.entries.length = 0;
+  }
+};
+function previewLine(line) {
+  if (line.length <= MAX_LINE_PREVIEW) return line;
+  return line.slice(0, MAX_LINE_PREVIEW) + "\u2026";
+}
 
 // src/proto/codec.ts
 function encodeRequest(id, method, params) {
@@ -119,15 +208,14 @@ function extractId(response) {
 }
 
 // src/version.ts
-var VERSION = "0.6.0";
-var ENGINE_VERSION = "0.6.0";
+var VERSION = "1.0.0-rc.1";
+var ENGINE_VERSION = "1.0.0-rc.1";
 
 // src/engine-manager.ts
-import { spawn, execSync } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import { createInterface } from "readline";
-import { existsSync as existsSync2, accessSync, constants as fsConstants } from "fs";
-import { resolve, join as join2, dirname } from "path";
-import { fileURLToPath } from "url";
+import { existsSync, accessSync, statSync as statSync2, constants as fsConstants } from "fs";
+import { delimiter, join as join2 } from "path";
 
 // src/engine-downloader.ts
 import * as https from "https";
@@ -139,10 +227,8 @@ import * as crypto from "crypto";
 var RELEASE_BASE = `https://github.com/attest-framework/attest/releases/download/v${ENGINE_VERSION}`;
 var CHECKSUMS_URL = `${RELEASE_BASE}/checksums-sha256.txt`;
 var MAX_REDIRECTS = 5;
-function attestBinDir() {
-  const dir = path.join(os.homedir(), ".attest", "bin");
-  fs.mkdirSync(dir, { recursive: true });
-  return dir;
+function versionedBinDir() {
+  return path.join(os.homedir(), ".attest", "bin", ENGINE_VERSION);
 }
 function platformKey() {
   const platform2 = os.platform();
@@ -170,20 +256,8 @@ function binaryFilename() {
   return os.platform() === "win32" ? "attest-engine.exe" : "attest-engine";
 }
 function cachedEnginePath() {
-  const dir = path.join(os.homedir(), ".attest", "bin");
-  const binPath = path.join(dir, binaryFilename());
-  const versionFile = path.join(dir, ".engine-version");
-  if (!fs.existsSync(binPath)) {
-    return null;
-  }
-  if (!fs.existsSync(versionFile)) {
-    return null;
-  }
-  const cachedVersion = fs.readFileSync(versionFile, "utf-8").trim();
-  if (cachedVersion !== ENGINE_VERSION) {
-    return null;
-  }
-  return binPath;
+  const binPath = path.join(versionedBinDir(), binaryFilename());
+  return fs.statSync(binPath, { throwIfNoEntry: false })?.isFile() ? binPath : null;
 }
 function parseChecksums(text) {
   const checksums = /* @__PURE__ */ new Map();
@@ -203,7 +277,7 @@ function httpsGet(url, redirectCount = 0) {
       new Error(`Too many redirects (>${MAX_REDIRECTS}) following ${url}`)
     );
   }
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve, reject) => {
     const client = url.startsWith("https:") ? https : http;
     client.get(url, (res) => {
       const status = res.statusCode ?? 0;
@@ -214,7 +288,7 @@ function httpsGet(url, redirectCount = 0) {
           return;
         }
         res.resume();
-        resolve2(httpsGet(location, redirectCount + 1));
+        resolve(httpsGet(location, redirectCount + 1));
         return;
       }
       if (status < 200 || status >= 300) {
@@ -224,14 +298,14 @@ function httpsGet(url, redirectCount = 0) {
       }
       const chunks = [];
       res.on("data", (chunk) => chunks.push(chunk));
-      res.on("end", () => resolve2(Buffer.concat(chunks)));
+      res.on("end", () => resolve(Buffer.concat(chunks)));
       res.on("error", reject);
     }).on("error", reject);
   });
 }
 async function downloadEngine() {
   const key = platformKey();
-  const filename = `attest-engine-${key}`;
+  const filename = `attest-engine-${key}${os.platform() === "win32" ? ".exe" : ""}`;
   const binaryUrl = `${RELEASE_BASE}/${filename}`;
   process.stderr.write(`[attest] Downloading engine v${ENGINE_VERSION} for ${key}...
 `);
@@ -251,19 +325,24 @@ async function downloadEngine() {
   const actualHash = crypto.createHash("sha256").update(data).digest("hex");
   if (actualHash !== expectedHash) {
     throw new Error(
-      `SHA256 mismatch for ${filename}. Expected: ${expectedHash}, got: ${actualHash}. The download may be corrupted. Delete ~/.attest/bin/ and retry.`
+      `SHA256 mismatch for ${filename}. Expected: ${expectedHash}, got: ${actualHash}. The download may be corrupted. Retry or download manually.`
     );
   }
   process.stderr.write(`[attest] Checksum verified.
 `);
-  const dir = attestBinDir();
-  const destFilename = binaryFilename();
-  const destPath = path.join(dir, destFilename);
-  const tmpPath = path.join(dir, `.${destFilename}.tmp.${process.pid}`);
-  fs.writeFileSync(tmpPath, data);
-  fs.chmodSync(tmpPath, 493);
-  fs.renameSync(tmpPath, destPath);
-  fs.writeFileSync(path.join(dir, ".engine-version"), ENGINE_VERSION);
+  const dir = versionedBinDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const destPath = path.join(dir, binaryFilename());
+  const suffix = `${String(process.pid)}.${crypto.randomBytes(8).toString("hex")}`;
+  const tmpPath = path.join(dir, `.${binaryFilename()}.tmp.${suffix}`);
+  try {
+    fs.writeFileSync(tmpPath, data, { flag: "wx", mode: 493 });
+    fs.chmodSync(tmpPath, 493);
+    fs.renameSync(tmpPath, destPath);
+  } catch (err) {
+    if (err.code !== "EEXIST") fs.rmSync(tmpPath, { force: true });
+    throw err;
+  }
   process.stderr.write(`[attest] Engine installed at ${destPath}
 `);
   return destPath;
@@ -271,45 +350,92 @@ async function downloadEngine() {
 
 // src/engine-manager.ts
 var ENGINE_BINARY_NAME = "attest-engine";
-async function findEngineBinary() {
-  const envPath = process.env["ATTEST_ENGINE_PATH"];
-  if (envPath) {
-    if (!existsSync2(envPath)) {
-      throw new Error(
-        `ATTEST_ENGINE_PATH is set to '${envPath}' but the file does not exist.`
-      );
-    }
-    return envPath;
-  }
-  try {
-    const cmd = process.platform === "win32" ? "where" : "which";
-    const found = execSync(`${cmd} ${ENGINE_BINARY_NAME}`, { encoding: "utf-8" }).trim();
-    if (found) return found;
-  } catch {
+var VERSION_PROBE_TIMEOUT_MS = 1e4;
+var EngineVersionMismatchError = class extends Error {
+  enginePath;
+  source;
+  found;
+  required;
+  constructor(enginePath, source, found, required) {
+    const reported = found === null ? "reports no version" : `reports version ${found}`;
+    super(
+      `attest-engine at ${enginePath} (from ${source}) ${reported}; this SDK requires attest-engine ${required}. Point ATTEST_ENGINE_PATH at a matching engine, or remove the mismatched one from PATH so the SDK can download ${required} into ~/.attest/bin/${required}/.`
+    );
+    this.name = "EngineVersionMismatchError";
+    this.enginePath = enginePath;
+    this.source = source;
+    this.found = found;
+    this.required = required;
   }
-  const cached = cachedEnginePath();
-  if (cached) return cached;
-  const candidates = [
-    join2(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "..", "bin", ENGINE_BINARY_NAME),
-    join2(process.cwd(), "bin", ENGINE_BINARY_NAME)
-  ];
-  for (const candidate of candidates) {
-    const resolved = resolve(candidate);
+};
+function engineVersion(enginePath) {
+  const proc = spawnSync(enginePath, ["version"], {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    timeout: VERSION_PROBE_TIMEOUT_MS
+  });
+  if (proc.error) throw proc.error;
+  const out = proc.stdout.trim();
+  const prefix = `${ENGINE_BINARY_NAME} `;
+  if (proc.status !== 0 || !out.startsWith(prefix)) return null;
+  return out.slice(prefix.length).trim();
+}
+function onPath() {
+  for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join2(dir, binaryFilename());
     try {
-      accessSync(resolved, fsConstants.X_OK);
-      if (existsSync2(resolved)) return resolved;
+      accessSync(candidate, fsConstants.X_OK);
     } catch {
+      continue;
     }
+    if (statSync2(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+function requireFile(enginePath, label) {
+  if (!existsSync(enginePath) || !statSync2(enginePath).isFile()) {
+    throw new Error(`${label}=${enginePath} does not exist or is not a file.`);
+  }
+}
+async function locateEngine(explicitPath, allowDownload) {
+  if (explicitPath) {
+    requireFile(explicitPath, "Engine path");
+    return [explicitPath, "explicit engine path"];
+  }
+  const envPath = process.env["ATTEST_ENGINE_PATH"];
+  if (envPath) {
+    requireFile(envPath, "ATTEST_ENGINE_PATH");
+    return [envPath, "ATTEST_ENGINE_PATH"];
+  }
+  const found = onPath();
+  if (found) return [found, "PATH"];
+  const cached = cachedEnginePath();
+  if (cached) return [cached, "engine cache"];
+  if (!allowDownload) {
+    throw new Error(
+      `No '${ENGINE_BINARY_NAME}' ${ENGINE_VERSION} in ATTEST_ENGINE_PATH, PATH or ~/.attest/bin/${ENGINE_VERSION}/.`
+    );
   }
-  const noDownload = process.env["ATTEST_ENGINE_NO_DOWNLOAD"];
+  const noDownload = process.env["ATTEST_ENGINE_NO_DOWNLOAD"]?.toLowerCase();
   if (noDownload === "1" || noDownload === "true" || noDownload === "yes") {
     throw new Error(
-      `Cannot find '${ENGINE_BINARY_NAME}' binary and auto-download is disabled (ATTEST_ENGINE_NO_DOWNLOAD is set). Install the engine manually:
-  1. Download from https://github.com/attest-framework/attest/releases
-  2. Place the binary on your PATH or set ATTEST_ENGINE_PATH`
+      `Cannot find '${ENGINE_BINARY_NAME}' ${ENGINE_VERSION} and ATTEST_ENGINE_NO_DOWNLOAD is set.
+Install options:
+  1. Build from source: make engine, then set ATTEST_ENGINE_PATH
+  2. Download release v${ENGINE_VERSION}: https://github.com/attest-framework/attest/releases
+  3. Allow auto-download by unsetting ATTEST_ENGINE_NO_DOWNLOAD`
     );
   }
-  return downloadEngine();
+  return [await downloadEngine(), "download"];
+}
+async function resolveEngine(explicitPath, options = {}) {
+  const [enginePath, source] = await locateEngine(explicitPath, options.allowDownload ?? true);
+  const found = engineVersion(enginePath);
+  if (found !== ENGINE_VERSION) {
+    throw new EngineVersionMismatchError(enginePath, source, found, ENGINE_VERSION);
+  }
+  return enginePath;
 }
 var EngineManager = class {
   enginePath;
@@ -324,28 +450,41 @@ var EngineManager = class {
     this.logLevel = options?.logLevel ?? "warn";
   }
   async start() {
-    if (!this.enginePath) {
-      this.enginePath = await findEngineBinary();
-    }
+    this.enginePath = await resolveEngine(this.enginePath || void 0);
     this.process = spawn(this.enginePath, [`--log-level=${this.logLevel}`], {
       stdio: ["pipe", "pipe", "pipe"]
     });
     this.reader = createInterface({ input: this.process.stdout });
-    const result = await this.sendRequestInternal("initialize", {
+    try {
+      this.initResult = await this.initialize();
+    } catch (err) {
+      await this.stop();
+      throw err;
+    }
+    this.initialized = true;
+    return this.initResult;
+  }
+  /** Send initialize and check the engine's version and capabilities. */
+  async initialize() {
+    const init = await this.sendRequestInternal("initialize", {
       sdk_name: "attest-typescript",
       sdk_version: VERSION,
       protocol_version: 1,
       required_capabilities: ["layers_1_4"],
       preferred_encoding: "json"
     });
-    this.initResult = result;
-    if (!this.initResult.compatible) {
-      throw new Error(
-        `Engine incompatible. Missing capabilities: ${JSON.stringify(this.initResult.missing)}`
+    if (init.engine_version !== ENGINE_VERSION) {
+      throw new EngineVersionMismatchError(
+        this.enginePath,
+        "initialize",
+        init.engine_version,
+        ENGINE_VERSION
       );
     }
-    this.initialized = true;
-    return this.initResult;
+    if (!init.compatible) {
+      throw new Error(`Engine incompatible. Missing capabilities: ${JSON.stringify(init.missing)}`);
+    }
+    return init;
   }
   async stop() {
     if (this.process === null) return;
@@ -386,11 +525,11 @@ var EngineManager = class {
     }
     this.requestId += 1;
     const requestStr = encodeRequest(this.requestId, method, params);
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve, reject) => {
       const onLine = (line) => {
         try {
           const response = decodeResponse(line);
-          resolve2(extractResult(response));
+          resolve(extractResult(response));
         } catch (err) {
           reject(err);
         }
@@ -438,7 +577,11 @@ function config(options) {
   }
 }
 function isSimulationMode() {
-  return _simulationMode || process.env["ATTEST_SIMULATION"] === "1" || process.env["ATTEST_SIMULATION"] === "true" || process.env["ATTEST_SIMULATION"] === "yes";
+  return _simulationMode || simulationEnvEnabled();
+}
+function simulationEnvEnabled() {
+  const env = (process.env["ATTEST_SIMULATION"] ?? "").trim().toLowerCase();
+  return env === "1" || env === "true" || env === "yes";
 }
 function getSampleRate() {
   if (_sampleRate > 0) return _sampleRate;
@@ -459,25 +602,11 @@ function resetConfig() {
   _sampleRate = 0;
 }
 
-// src/simulation.ts
-function simulationEvaluateBatch(assertions) {
-  const results = assertions.map((assertion) => ({
-    assertion_id: assertion.assertion_id,
-    status: "pass",
-    score: 1,
-    explanation: `[simulation] assertion '${assertion.assertion_id}' passed (type: ${assertion.type})`,
-    cost: 0,
-    duration_ms: 0
-  }));
-  return {
-    results,
-    total_cost: 0,
-    total_duration_ms: 0
-  };
-}
-
 // src/client.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_DIAGNOSTIC_BUFFER = 32;
+var DEFAULT_DESYNC_THRESHOLD = 3;
+var DEFAULT_DESYNC_WINDOW_MS = 1e3;
 function resolveTimeoutMs(override) {
   if (override !== void 0) return override;
   const env = process.env["ATTEST_ENGINE_TIMEOUT"];
@@ -499,6 +628,24 @@ function makeTimeoutPromise(method, timeoutMs) {
     }, timeoutMs);
   });
 }
+function debugProtocolEnabled() {
+  const flag = process.env["ATTEST_DEBUG_PROTOCOL"];
+  return flag === "1" || flag === "true" || flag === "yes";
+}
+function envLoggerDefault() {
+  if (debugProtocolEnabled()) {
+    return {
+      warn: (msg, ...args) => console.warn(msg, ...args),
+      error: (msg, ...args) => console.error(msg, ...args)
+    };
+  }
+  return {
+    warn: () => {
+    },
+    error: () => {
+    }
+  };
+}
 var AttestClient = class {
   engine;
   requestId = 0;
@@ -506,8 +653,34 @@ var AttestClient = class {
   writeChain = Promise.resolve();
   readerActive = false;
   lineHandler = null;
-  constructor(engine) {
+  logger;
+  diagnosticBuffer;
+  diagnosticListeners = /* @__PURE__ */ new Set();
+  desyncThreshold;
+  desyncWindowMs;
+  desynced = false;
+  constructor(engine, options) {
     this.engine = engine;
+    this.logger = options?.logger ?? envLoggerDefault();
+    this.diagnosticBuffer = new ProtocolDiagnosticBuffer(
+      options?.diagnosticBufferSize ?? DEFAULT_DIAGNOSTIC_BUFFER
+    );
+    this.desyncThreshold = options?.desyncThreshold ?? DEFAULT_DESYNC_THRESHOLD;
+    this.desyncWindowMs = options?.desyncWindowMs ?? DEFAULT_DESYNC_WINDOW_MS;
+    if (options?.onDiagnostic !== void 0) {
+      this.diagnosticListeners.add(options.onDiagnostic);
+    }
+  }
+  /** Subscribe to protocol diagnostics. Returns an unsubscribe function. */
+  onProtocolDiagnostic(listener) {
+    this.diagnosticListeners.add(listener);
+    return () => {
+      this.diagnosticListeners.delete(listener);
+    };
+  }
+  /** Snapshot of the diagnostic ring buffer (most recent last). */
+  protocolDiagnostics() {
+    return this.diagnosticBuffer.snapshot();
   }
   startReader() {
     if (this.readerActive) return;
@@ -532,35 +705,101 @@ var AttestClient = class {
     this.lineHandler = null;
     this.readerActive = false;
   }
+  recordDiagnostic(kind, message, rawLine) {
+    const diagnostic = {
+      kind,
+      message,
+      rawLine: previewLine(rawLine),
+      timestampMs: Date.now()
+    };
+    this.diagnosticBuffer.push(diagnostic);
+    this.logger.warn(`[attest.protocol] ${kind}: ${message}`);
+    for (const listener of this.diagnosticListeners) {
+      try {
+        listener(diagnostic);
+      } catch (err) {
+        this.logger.error(
+          `[attest.protocol] diagnostic listener threw: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    this.maybeTriggerDesync(diagnostic.timestampMs);
+  }
+  maybeTriggerDesync(nowMs) {
+    if (this.desynced) return;
+    const recent = this.diagnosticBuffer.countWithin(this.desyncWindowMs, nowMs);
+    if (recent >= this.desyncThreshold) {
+      this.desynced = true;
+      const snapshot = this.diagnosticBuffer.snapshot();
+      const err = new ProtocolDesyncError(
+        `Engine protocol desync: ${recent} unroutable response lines within ${this.desyncWindowMs}ms.`,
+        snapshot
+      );
+      this.logger.error(`[attest.protocol] ${err.message}`);
+      this.failAll(err);
+    }
+  }
   handleLine(line) {
+    let response;
+    try {
+      response = decodeResponse(line);
+    } catch (err) {
+      this.handleDecodeFailure(line, err);
+      return;
+    }
     let reqId;
     try {
-      const response = decodeResponse(line);
       reqId = extractId(response);
-      const pending = this.pending.get(reqId);
-      if (pending === void 0) return;
-      this.pending.delete(reqId);
-      try {
-        const result = extractResult(response);
-        pending.resolve(result);
-      } catch (err) {
-        pending.reject(err);
-      }
     } catch (err) {
-      if (err instanceof ProtocolError) {
-        try {
-          const raw = JSON.parse(line.trim());
-          reqId = Number(raw.id ?? -1);
-        } catch {
-          reqId = -1;
-        }
-        const pending = this.pending.get(reqId);
-        if (pending !== void 0) {
-          this.pending.delete(reqId);
-          pending.reject(err);
+      const message = err instanceof Error ? err.message : String(err);
+      this.recordDiagnostic("missing_id", message, line);
+      return;
+    }
+    const pending = this.pending.get(reqId);
+    if (pending === void 0) {
+      this.recordDiagnostic(
+        "unknown_id",
+        `no pending request for id=${reqId}`,
+        line
+      );
+      return;
+    }
+    this.pending.delete(reqId);
+    try {
+      const result = extractResult(response);
+      pending.resolve(result);
+    } catch (err) {
+      pending.reject(err);
+    }
+  }
+  handleDecodeFailure(line, err) {
+    if (err instanceof ProtocolError) {
+      let reqId = -1;
+      try {
+        const raw = JSON.parse(line.trim());
+        const idCandidate = raw["id"];
+        if (typeof idCandidate === "number" && Number.isFinite(idCandidate)) {
+          reqId = idCandidate;
         }
+      } catch {
+        reqId = -1;
       }
+      const pending = this.pending.get(reqId);
+      if (pending !== void 0) {
+        this.pending.delete(reqId);
+        pending.reject(err);
+        return;
+      }
+      this.recordDiagnostic(
+        "non_routable_error",
+        `engine error code=${err.code} (${err.errorMessage}) had no matching pending id`,
+        line
+      );
+      return;
     }
+    const message = err instanceof Error ? err.message : String(err);
+    const kind = classifyDecodeError(message);
+    this.recordDiagnostic(kind, message, line);
   }
   failAll(err) {
     for (const pending of this.pending.values()) {
@@ -569,6 +808,12 @@ var AttestClient = class {
     this.pending.clear();
   }
   async sendRequest(method, params, timeoutMs) {
+    if (this.desynced) {
+      throw new ProtocolDesyncError(
+        "Engine protocol is desynced; AttestClient will not send further requests.",
+        this.diagnosticBuffer.snapshot()
+      );
+    }
     const resolvedTimeout = resolveTimeoutMs(timeoutMs);
     if (!this.readerActive) {
       return Promise.race([
@@ -581,12 +826,12 @@ var AttestClient = class {
       throw new Error("Engine process not started.");
     }
     let capturedReqId;
-    const requestPromise = new Promise((resolve2, reject) => {
+    const requestPromise = new Promise((resolve, reject) => {
       this.writeChain = this.writeChain.then(() => {
         this.requestId += 1;
         const reqId = this.requestId;
         capturedReqId = reqId;
-        this.pending.set(reqId, { resolve: resolve2, reject });
+        this.pending.set(reqId, { resolve, reject });
         const requestStr = encodeRequest(reqId, method, params);
         cp.stdin.write(requestStr, (err) => {
           if (err) {
@@ -606,7 +851,7 @@ var AttestClient = class {
   }
   async evaluateBatch(trace, assertions, options) {
     if (isSimulationMode()) {
-      return simulationEvaluateBatch(assertions);
+      requireSimulationCapability(this.engine["initResult"]);
     }
     const params = {
       trace,
@@ -645,10 +890,10 @@ var AttestClient = class {
     if (isSimulationMode()) {
       return {
         assertion_id: assertionId2,
-        mean: 1,
+        mean: 0,
         stddev: 0,
         count: 0,
-        latest_score: 1,
+        latest_score: 0,
         deviation: 0,
         status: "no_data"
       };
@@ -679,6 +924,23 @@ var AttestClient = class {
     return String(raw.message);
   }
 };
+function classifyDecodeError(message) {
+  if (message.startsWith("malformed JSON")) return "malformed_json";
+  if (message.startsWith("expected JSON object")) return "non_object_response";
+  if (message.startsWith("invalid jsonrpc version")) return "invalid_jsonrpc_version";
+  if (message.startsWith("empty response line")) return "malformed_json";
+  return "malformed_json";
+}
+function requireSimulationCapability(init) {
+  if (init === null || init === void 0) {
+    throw new Error("simulation mode: the engine has not been initialized");
+  }
+  if (!(init.capabilities ?? []).includes("simulation_mode")) {
+    throw new Error(
+      `simulation mode is on but attest-engine ${init.engine_version} was not started in simulation mode (capability 'simulation_mode' missing), so it would call real providers. Set ATTEST_SIMULATION=1 before the engine starts (the Vitest fixtures do this for you) and use attest-engine 1.0 or later.`
+    );
+  }
+}
 
 // src/trace.ts
 import { randomUUID } from "crypto";
@@ -769,6 +1031,20 @@ var TraceBuilder = class {
 };
 
 // src/result.ts
+var KNOWN_STATUSES = /* @__PURE__ */ new Set([
+  STATUS_PASS,
+  STATUS_SOFT_FAIL,
+  STATUS_HARD_FAIL,
+  STATUS_NOT_EVALUATED
+]);
+function normalizeAssertionResult(r) {
+  if (KNOWN_STATUSES.has(r.status)) return r;
+  return {
+    ...r,
+    status: STATUS_NOT_EVALUATED,
+    explanation: `[unknown status '${r.status}'] ${r.explanation}`
+  };
+}
 var AgentResult = class {
   trace;
   assertionResults;
@@ -776,15 +1052,31 @@ var AgentResult = class {
   totalDurationMs;
   constructor(trace, assertionResults = [], totalCost = 0, totalDurationMs = 0) {
     this.trace = trace;
-    this.assertionResults = assertionResults;
+    this.assertionResults = assertionResults.map(normalizeAssertionResult);
     this.totalCost = totalCost;
     this.totalDurationMs = totalDurationMs;
   }
+  /** True if every assertion has status "pass". */
   get passed() {
     return this.assertionResults.every((r) => r.status === STATUS_PASS);
   }
+  /**
+   * Test outcome after the whole batch. Any hard_fail fails; otherwise any
+   * not_evaluated skips (fails when `strict`); otherwise pass, including
+   * when only soft_fail rows are present (see `softFailures`).
+   */
+  outcome(options) {
+    if (this.hardFailures.length > 0) return OUTCOME_FAIL;
+    if (this.notEvaluated.length > 0) {
+      return options?.strict === true ? OUTCOME_FAIL : OUTCOME_SKIP;
+    }
+    return OUTCOME_PASS;
+  }
+  /** Failed assertions: hard_fail and soft_fail only. */
   get failedAssertions() {
-    return this.assertionResults.filter((r) => r.status !== STATUS_PASS);
+    return this.assertionResults.filter(
+      (r) => r.status === STATUS_HARD_FAIL || r.status === STATUS_SOFT_FAIL
+    );
   }
   get hardFailures() {
     return this.assertionResults.filter((r) => r.status === STATUS_HARD_FAIL);
@@ -792,14 +1084,226 @@ var AgentResult = class {
   get softFailures() {
     return this.assertionResults.filter((r) => r.status === STATUS_SOFT_FAIL);
   }
+  /** Assertions the engine did not evaluate; each carries a `reason`. */
+  get notEvaluated() {
+    return this.assertionResults.filter((r) => r.status === STATUS_NOT_EVALUATED);
+  }
+  /** Count of not_evaluated assertions per reason, in first-seen order. */
+  get notEvaluatedReasons() {
+    const counts = {};
+    for (const r of this.notEvaluated) {
+      const key = r.reason || "unknown";
+      counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return counts;
+  }
+  /**
+   * Passed / evaluated assertions; null when nothing was evaluated.
+   * not_evaluated rows are excluded from the denominator.
+   */
+  get passRate() {
+    const evaluated = this.assertionResults.length - this.notEvaluated.length;
+    return evaluated === 0 ? null : this.passCount / evaluated;
+  }
   get passCount() {
     return this.assertionResults.filter((r) => r.status === STATUS_PASS).length;
   }
+  /** Number of failed assertions (hard_fail + soft_fail). */
   get failCount() {
-    return this.assertionResults.length - this.passCount;
+    return this.failedAssertions.length;
+  }
+  /** "not evaluated: <reason>[, <reason> ×n ...]" for skipped tests. */
+  skipReason() {
+    const parts = Object.entries(this.notEvaluatedReasons).map(
+      ([reason, n]) => n === 1 ? reason : `${reason} \xD7${n}`
+    );
+    return `not evaluated: ${parts.join(", ")}`;
   }
 };
 
+// src/diagnostics.ts
+var ANSI_RESET = "\x1B[0m";
+var ANSI_RED = "\x1B[31m";
+var ANSI_YELLOW = "\x1B[33m";
+var ANSI_GREEN = "\x1B[32m";
+var ANSI_DIM = "\x1B[2m";
+var ANSI_BOLD = "\x1B[1m";
+var LAYER_NAMES = {
+  1: "schema",
+  2: "constraint",
+  3: "trace",
+  4: "content",
+  5: "embedding",
+  6: "llm_judge",
+  7: "trace_tree",
+  8: "plugin"
+};
+function layerLabel(layer, assertionType) {
+  if (layer === 0 && assertionType) {
+    return `L? ${assertionType}`;
+  }
+  const name = LAYER_NAMES[layer] ?? assertionType ?? "uncategorized";
+  return `L${layer} ${name}`;
+}
+function statusGlyph(status, color) {
+  let glyph;
+  let c;
+  if (status === STATUS_PASS) {
+    glyph = "PASS";
+    c = ANSI_GREEN;
+  } else if (status === STATUS_SOFT_FAIL) {
+    glyph = "SOFT";
+    c = ANSI_YELLOW;
+  } else if (status === STATUS_HARD_FAIL) {
+    glyph = "FAIL";
+    c = ANSI_RED;
+  } else if (status === STATUS_NOT_EVALUATED) {
+    glyph = "N/E";
+    c = ANSI_DIM;
+  } else {
+    glyph = status.toUpperCase() || "????";
+    c = ANSI_DIM;
+  }
+  return color ? `${c}${glyph}${ANSI_RESET}` : glyph;
+}
+function bold(s, color) {
+  return color ? `${ANSI_BOLD}${s}${ANSI_RESET}` : s;
+}
+function dim(s, color) {
+  return color ? `${ANSI_DIM}${s}${ANSI_RESET}` : s;
+}
+function truncate(value, limit = 280) {
+  if (value.length <= limit) {
+    return value;
+  }
+  return value.slice(0, limit - 3) + "...";
+}
+function renderAssertionFailure(result, options = {}) {
+  const color = options.color ?? false;
+  const testFile = options.testFile;
+  const layer = result.layer ?? 0;
+  const label = layerLabel(layer, result.type);
+  const lines = [];
+  lines.push(
+    `  ${statusGlyph(result.status, color)} ${bold(result.assertion_id, color)} ${dim(`\u2014 ${label}`, color)}`
+  );
+  if (result.reason) {
+    lines.push(`      reason:     not evaluated: ${result.reason}`);
+  }
+  if (result.trace_node_path) {
+    lines.push(`      trace path: ${result.trace_node_path}`);
+  }
+  if (result.status !== STATUS_NOT_EVALUATED) {
+    lines.push(`      score:      ${result.score.toFixed(3)}`);
+  }
+  if (result.expected) {
+    lines.push(`      expected:   ${truncate(result.expected)}`);
+  }
+  if (result.actual) {
+    lines.push(`      actual:     ${truncate(result.actual)}`);
+  }
+  if (result.explanation) {
+    lines.push(`      detail:     ${truncate(result.explanation)}`);
+  }
+  if (result.threshold_source && result.threshold_source !== "static") {
+    lines.push(`      threshold:  ${result.threshold_source}`);
+  }
+  if (result.failure_class) {
+    lines.push(`      class:      ${result.failure_class}`);
+  }
+  if (result.judge_metadata) {
+    appendJudgeMetadata(lines, result.judge_metadata);
+  }
+  if (result.suggested_action) {
+    lines.push(`      hint:       ${truncate(result.suggested_action)}`);
+  }
+  if ((result.cost ?? 0) > 0 || (result.duration_ms ?? 0) > 0) {
+    const cost = result.cost ?? 0;
+    const durMs = result.duration_ms ?? 0;
+    lines.push(`      cost/lat:   $${cost.toFixed(6)} / ${durMs}ms`);
+  }
+  if (testFile) {
+    lines.push(`      source:     ${testFile}`);
+  }
+  return lines.join("\n") + "\n";
+}
+function appendJudgeMetadata(lines, meta) {
+  if (meta.model) {
+    let rubric = meta.rubric_name ?? "default";
+    if (meta.rubric_version) {
+      rubric = `${rubric} @ ${meta.rubric_version}`;
+    }
+    lines.push(`      judge:      ${meta.model} / ${rubric}`);
+  }
+  if (meta.prompt_hash) {
+    lines.push(`      prompt:     #${meta.prompt_hash}`);
+  }
+  const samples = meta.sample_scores ?? [];
+  if (samples.length > 1) {
+    const formatted = samples.map((s) => s.toFixed(2)).join(", ");
+    const mean = (meta.score_mean ?? 0).toFixed(2);
+    const stddev = (meta.score_stddev ?? 0).toFixed(2);
+    const flag = meta.high_variance ? " \u26A0 HIGH VARIANCE" : "";
+    lines.push(
+      `      samples:    [${formatted}] mean=${mean} stddev=${stddev}${flag}`
+    );
+  }
+  const probes = meta.bias_probes ?? [];
+  if (probes.length > 0) {
+    const formatted = probes.map((p) => `${p.name} \u0394${p.delta >= 0 ? "+" : ""}${p.delta.toFixed(2)}`).join(", ");
+    lines.push(`      bias:       ${formatted}`);
+  }
+  if (meta.calibration) {
+    const c = meta.calibration;
+    lines.push(
+      `      calibrated: ${c.label_count} labels, agreement=${c.agreement.toFixed(2)}, \u03BA=${c.cohen_kappa.toFixed(2)}`
+    );
+  }
+}
+function renderSummary(result, options = {}) {
+  const color = options.color ?? false;
+  const passN = result.passCount;
+  const soft = result.assertionResults.filter(
+    (r) => r.status === STATUS_SOFT_FAIL
+  ).length;
+  const hard = result.assertionResults.filter(
+    (r) => r.status === STATUS_HARD_FAIL
+  ).length;
+  const parts = [
+    `${statusGlyph(STATUS_PASS, color)} ${passN}`,
+    `${statusGlyph(STATUS_SOFT_FAIL, color)} ${soft}`,
+    `${statusGlyph(STATUS_HARD_FAIL, color)} ${hard}`,
+    `${statusGlyph(STATUS_NOT_EVALUATED, color)} ${result.notEvaluated.length}`,
+    `cost $${result.totalCost.toFixed(6)}`,
+    `dur ${result.totalDurationMs}ms`
+  ];
+  return parts.join(" | ");
+}
+function renderDiagnostics(result, options = {}) {
+  const color = options.color ?? false;
+  const includePassing = options.includePassing ?? false;
+  const rows = includePassing ? result.assertionResults : result.assertionResults.filter((r) => r.status !== STATUS_PASS);
+  if (rows.length === 0) {
+    return dim("  (no failures)\n", color);
+  }
+  const out = [""];
+  out.push(bold(`Attest diagnostic \u2014 ${headerCounts(result)}:`, color));
+  for (const r of rows) {
+    out.push(renderAssertionFailure(r, options));
+  }
+  out.push(dim(`  Summary: ${renderSummary(result, { color })}`, color));
+  return out.join("\n");
+}
+function headerCounts(result) {
+  const total = result.assertionResults.length;
+  const notEvaluated = result.notEvaluated.length;
+  if (result.failCount === 0 && notEvaluated > 0) {
+    return `${notEvaluated} of ${total} assertions not evaluated`;
+  }
+  const text = `${result.failCount} of ${total} assertions failed`;
+  return notEvaluated > 0 ? `${text}, ${notEvaluated} not evaluated` : text;
+}
+
 // src/trace-tree.ts
 var TraceTree = class {
   root;
@@ -2004,6 +2508,222 @@ var ContinuousEvalRunner = class {
   }
 };
 
+// src/calibration.ts
+import { createHash as createHash2 } from "crypto";
+function computeAgreement(pairs, threshold) {
+  if (pairs.length === 0) {
+    throw new Error("no labeled pairs available");
+  }
+  if (threshold <= 0 || threshold >= 1) {
+    throw new Error("threshold must be in (0, 1)");
+  }
+  const n = pairs.length;
+  let humanPos = 0;
+  let judgePos = 0;
+  let bothPos = 0;
+  let bothNeg = 0;
+  for (const p of pairs) {
+    const hPos = p.human >= threshold;
+    const jPos = p.judge >= threshold;
+    if (hPos) humanPos++;
+    if (jPos) judgePos++;
+    if (hPos && jPos) bothPos++;
+    if (!hPos && !jPos) bothNeg++;
+  }
+  const humanNeg = n - humanPos;
+  const judgeNeg = n - judgePos;
+  const agreement = (bothPos + bothNeg) / n;
+  const expected = (humanPos * judgePos + humanNeg * judgeNeg) / (n * n);
+  const cohenKappa = expected < 1 ? (agreement - expected) / (1 - expected) : 0;
+  const rocAuc = rocAUC(pairs, threshold);
+  return { threshold, n, agreement, cohenKappa, rocAuc };
+}
+function rocAUC(pairs, threshold) {
+  const rows = pairs.map((p) => ({
+    score: p.judge,
+    pos: p.human >= threshold
+  }));
+  const pos = rows.filter((r) => r.pos).length;
+  const neg = rows.length - pos;
+  if (pos === 0 || neg === 0) return 0;
+  rows.sort((a, b) => a.score - b.score);
+  let rankSumPos = 0;
+  let i = 0;
+  while (i < rows.length) {
+    let j = i;
+    while (j < rows.length && rows[j].score === rows[i].score) {
+      j++;
+    }
+    const avgRank = (i + j + 1) / 2;
+    for (let k = i; k < j; k++) {
+      if (rows[k].pos) rankSumPos += avgRank;
+    }
+    i = j;
+  }
+  const auc = (rankSumPos - pos * (pos + 1) / 2) / (pos * neg);
+  if (Number.isNaN(auc) || !Number.isFinite(auc)) return 0;
+  return auc;
+}
+function loadLabelsCSV(text) {
+  const rows = parseCSV(text);
+  if (rows.length === 0) {
+    throw new Error("empty CSV");
+  }
+  let start = 0;
+  if (rows[0].length >= 2) {
+    const firstHuman = parseFloatStrict(rows[0][1]);
+    if (firstHuman === null) start = 1;
+  }
+  const out = [];
+  for (let idx = start; idx < rows.length; idx++) {
+    const row = rows[idx];
+    const lineNum = idx + 1;
+    if (row.length === 0) continue;
+    if (row[0].trimStart().startsWith("#")) continue;
+    if (row.length < 2) {
+      throw new Error(
+        `CSV line ${lineNum}: want at least 2 columns (input, human_label)`
+      );
+    }
+    const human = parseFloatStrict(row[1]);
+    if (human === null) {
+      throw new Error(`CSV line ${lineNum}: human_label not a float: ${row[1]}`);
+    }
+    const rec = {
+      input: row[0],
+      humanLabel: human,
+      judgeScore: 0,
+      judgeKnown: false
+    };
+    if (row.length >= 3 && row[2].trim() !== "") {
+      const judge = parseFloatStrict(row[2]);
+      if (judge === null) {
+        throw new Error(
+          `CSV line ${lineNum}: judge_score not a float: ${row[2]}`
+        );
+      }
+      rec.judgeScore = judge;
+      rec.judgeKnown = true;
+    }
+    out.push(rec);
+  }
+  if (out.length === 0) {
+    throw new Error("CSV contained no labeled rows");
+  }
+  return out;
+}
+function loadLabelsJSONL(text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const stripped = lines[i].trim();
+    if (!stripped) continue;
+    let obj;
+    try {
+      obj = JSON.parse(stripped);
+    } catch (err) {
+      throw new Error(`JSONL line ${i + 1}: ${err.message}`);
+    }
+    if (Object.keys(obj).length === 0) continue;
+    if (obj["human_label"] === void 0) {
+      throw new Error(`JSONL line ${i + 1}: missing human_label`);
+    }
+    const human = parseJSONNumber(obj["human_label"]);
+    if (human === null) {
+      throw new Error(`JSONL line ${i + 1}: human_label is not a number`);
+    }
+    const rec = {
+      input: typeof obj["input"] === "string" ? obj["input"] : "",
+      humanLabel: human,
+      judgeScore: 0,
+      judgeKnown: false
+    };
+    if (obj["judge_score"] !== void 0 && obj["judge_score"] !== null) {
+      const judge = parseJSONNumber(obj["judge_score"]);
+      if (judge === null) {
+        throw new Error(`JSONL line ${i + 1}: judge_score is not a number`);
+      }
+      rec.judgeScore = judge;
+      rec.judgeKnown = true;
+    }
+    out.push(rec);
+  }
+  if (out.length === 0) {
+    throw new Error("JSONL contained no labeled rows");
+  }
+  return out;
+}
+function promptHash(text) {
+  return createHash2("sha256").update(text).digest("hex").slice(0, 16);
+}
+function parseFloatStrict(raw) {
+  const trimmed = raw.trim();
+  if (trimmed === "") return null;
+  const n = Number(trimmed);
+  if (Number.isNaN(n)) return null;
+  return n;
+}
+function parseJSONNumber(value) {
+  if (typeof value !== "number") return null;
+  if (Number.isNaN(value)) return null;
+  return value;
+}
+function parseCSV(text) {
+  const rows = [];
+  let current = [];
+  let field = "";
+  let inQuotes = false;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i += 2;
+          continue;
+        }
+        inQuotes = false;
+        i++;
+        continue;
+      }
+      field += ch;
+      i++;
+      continue;
+    }
+    if (ch === '"') {
+      inQuotes = true;
+      i++;
+      continue;
+    }
+    if (ch === ",") {
+      current.push(field);
+      field = "";
+      i++;
+      continue;
+    }
+    if (ch === "\n") {
+      current.push(field);
+      rows.push(current);
+      current = [];
+      field = "";
+      i++;
+      continue;
+    }
+    if (ch === "\r") {
+      i++;
+      continue;
+    }
+    field += ch;
+    i++;
+  }
+  if (field.length > 0 || current.length > 0) {
+    current.push(field);
+    rows.push(current);
+  }
+  return rows;
+}
+
 // src/personas.ts
 var FRIENDLY_USER = {
   name: "FriendlyUser",
@@ -2438,15 +3158,27 @@ export {
   EngineTimeoutError,
   ExpectChain,
   FRIENDLY_USER,
+  FailureClass,
   GeminiAdapter,
   LangChainAdapter,
   ManualAdapter,
   OTelAdapter,
+  OUTCOME_FAIL,
+  OUTCOME_PASS,
+  OUTCOME_SKIP,
   OllamaAdapter,
   OpenAIAdapter,
   PluginRegistry,
+  ProtocolDesyncError,
+  ProtocolDiagnosticBuffer,
   ProtocolError,
+  REASON_MISSING_EVIDENCE,
+  REASON_PROVIDER_NOT_CONFIGURED,
+  REASON_PROVIDER_UNAVAILABLE,
+  REASON_SHORT_CIRCUITED,
+  REASON_SIMULATION,
   STATUS_HARD_FAIL,
+  STATUS_NOT_EVALUATED,
   STATUS_PASS,
   STATUS_SOFT_FAIL,
   STEP_AGENT_CALL,
@@ -2473,6 +3205,7 @@ export {
   agentId,
   assertionId,
   attestExpect,
+  computeAgreement,
   config,
   decodeResponse,
   delegate,
@@ -2482,8 +3215,17 @@ export {
   extractResult,
   getSampleRate,
   isSimulationMode,
+  layerForType,
+  loadLabelsCSV,
+  loadLabelsJSONL,
+  previewLine,
+  promptHash,
+  renderAssertionFailure,
+  renderDiagnostics,
+  renderSummary,
+  requireSimulationCapability,
   resetConfig,
-  simulationEvaluateBatch,
+  simulationEnvEnabled,
   tier,
   traceId
 };