agentic-qe 3.14.0 → 3.14.1

package/dist/mcp/services/session-resume.d.ts

@@ -1,29 +1,25 @@
-/**
- * Agentic QE v3 - Session Resume Service
- *
- * IMP-04: Transcript-First Session Durability
- * Reads an existing JSONL session file by sampling the head (first 4KB)
- * and tail (last 64KB) to reconstruct metadata and recent entries
- * without reading the entire file.
- *
- * @module mcp/services/session-resume
- */
 import type { SessionEntry, SessionMetadata } from './session-store';
+export type SessionRecoveryDisposition = 'MISSING' | 'EMPTY' | 'LEGACY_UNVERIFIED' | 'INVALID' | 'UNTRUSTED' | 'RESOURCE_LIMIT';
+export interface SessionResumeOptions {
+    /** Canonical directory that must contain the session file. */
+    sessionRoot: string;
+    /** Explicit compatibility opt-in; legacy JSONL has no commit proof. */
+    allowLegacyUnverified?: boolean;
+    maxFileBytes?: number;
+    maxRecordBytes?: number;
+    maxRecords?: number;
+}
 export interface SessionResumeResult {
     metadata: SessionMetadata;
     recentEntries: SessionEntry[];
     lastState: 'idle' | 'running' | 'requires_action';
     canResume: boolean;
+    disposition: SessionRecoveryDisposition;
+    diagnostics: string[];
 }
 /**
- * Resume a session from a JSONL file.
- *
- * Reads the first 4KB (head) to extract session start metadata and
- * the last 64KB (tail) to get recent entries. Parses JSONL lines,
- * reconstructs the parentUuid linked list, and returns metadata +
- * recent entries + resume capability.
- *
- * Corrupt or incomplete lines are skipped gracefully.
+ * Inspect a legacy transcript through one no-follow descriptor. Automatic
+ * resume requires an explicit opt-in because this format has no commit marker.
  */
-export declare function resumeSession(filePath: string): SessionResumeResult;
+export declare function resumeSession(filePath: string, options: SessionResumeOptions): SessionResumeResult;
 //# sourceMappingURL=session-resume.d.ts.map

package/dist/mcp/services/session-resume.js

@@ -1,221 +1,231 @@
-/**
- * Agentic QE v3 - Session Resume Service
- *
- * IMP-04: Transcript-First Session Durability
- * Reads an existing JSONL session file by sampling the head (first 4KB)
- * and tail (last 64KB) to reconstruct metadata and recent entries
- * without reading the entire file.
- *
- * @module mcp/services/session-resume
- */
+/** Bounded, fail-closed recovery for legacy JSONL session transcripts. */
 import * as fs from 'fs';
 import * as path from 'path';
-// ============================================================================
-// Constants
-// ============================================================================
-const HEAD_BYTES = 4 * 1024; // 4KB
-const TAIL_BYTES = 64 * 1024; // 64KB
-// ============================================================================
-// Public API
-// ============================================================================
-/**
- * Resume a session from a JSONL file.
- *
- * Reads the first 4KB (head) to extract session start metadata and
- * the last 64KB (tail) to get recent entries. Parses JSONL lines,
- * reconstructs the parentUuid linked list, and returns metadata +
- * recent entries + resume capability.
- *
- * Corrupt or incomplete lines are skipped gracefully.
- */
-export function resumeSession(filePath) {
-    // If file doesn't exist, return non-resumable result
-    if (!fs.existsSync(filePath)) {
-        return {
-            metadata: {
-                sessionId: extractSessionId(filePath),
-                createdAt: 0,
-                lastActivityAt: 0,
-                entryCount: 0,
-                state: 'idle',
-            },
-            recentEntries: [],
-            lastState: 'idle',
-            canResume: false,
-        };
-    }
-    const stat = fs.statSync(filePath);
-    const fileSize = stat.size;
-    if (fileSize === 0) {
-        return {
-            metadata: {
-                sessionId: extractSessionId(filePath),
-                createdAt: 0,
-                lastActivityAt: 0,
-                entryCount: 0,
-                state: 'idle',
-            },
-            recentEntries: [],
-            lastState: 'idle',
-            canResume: false,
-        };
-    }
-    // Read head (first 4KB)
-    const headEntries = readHead(filePath, fileSize);
-    // Read tail (last 64KB)
-    const tailEntries = readTail(filePath, fileSize);
-    // Merge and deduplicate: use a Map keyed by uuid to ensure uniqueness
-    const entryMap = new Map();
-    for (const entry of headEntries) {
-        entryMap.set(entry.uuid, entry);
-    }
-    for (const entry of tailEntries) {
-        entryMap.set(entry.uuid, entry);
-    }
-    const allEntries = Array.from(entryMap.values());
-    allEntries.sort((a, b) => a.timestamp - b.timestamp);
-    // Reconstruct metadata from available entries
-    const firstEntry = headEntries[0] ?? allEntries[0];
-    const lastEntry = tailEntries[tailEntries.length - 1] ?? allEntries[allEntries.length - 1];
-    // For entry count: if file is small enough that head+tail overlap,
-    // allEntries.length is accurate. Otherwise, count total lines.
-    let entryCount;
-    if (fileSize <= HEAD_BYTES + TAIL_BYTES) {
-        entryCount = allEntries.length;
-    }
-    else {
-        entryCount = countLines(filePath);
-    }
-    const lastState = lastEntry?.state ?? 'idle';
-    const metadata = {
-        sessionId: extractSessionId(filePath),
-        createdAt: firstEntry?.timestamp ?? 0,
-        lastActivityAt: lastEntry?.timestamp ?? 0,
-        entryCount,
-        state: lastState,
-    };
+const DEFAULT_MAX_FILE_BYTES = 16 * 1024 * 1024;
+const DEFAULT_MAX_RECORD_BYTES = 1024 * 1024;
+const DEFAULT_MAX_RECORDS = 100_000;
+const RECENT_ENTRY_LIMIT = 256;
+const ENTRY_TYPES = new Set(['tool_call', 'tool_result', 'state_change', 'error']);
+const ENTRY_STATES = new Set(['idle', 'running', 'requires_action']);
+const ENTRY_KEYS = new Set([
+    'uuid', 'parentUuid', 'timestamp', 'type', 'toolName', 'params', 'result', 'state', 'tokenEstimate',
+]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function emptyResult(filePath, disposition, diagnostics = []) {
     return {
-        metadata,
-        recentEntries: tailEntries,
-        lastState,
-        canResume: allEntries.length > 0,
+        metadata: {
+            sessionId: path.basename(filePath, '.jsonl'), createdAt: 0, lastActivityAt: 0,
+            entryCount: 0, state: 'idle',
+        },
+        recentEntries: [], lastState: 'idle', canResume: false, disposition, diagnostics,
     };
 }
-// ============================================================================
-// Private helpers
-// ============================================================================
-/**
- * Extract session ID from file path (filename without extension).
- */
-function extractSessionId(filePath) {
-    return path.basename(filePath, '.jsonl');
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
 }
-/**
- * Read and parse the first HEAD_BYTES of the file.
- */
-function readHead(filePath, fileSize) {
-    const bytesToRead = Math.min(HEAD_BYTES, fileSize);
-    const fd = fs.openSync(filePath, 'r');
+function isValidEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    if (Object.keys(entry).some(key => !ENTRY_KEYS.has(key)))
+        return false;
+    const params = entry.params;
+    return typeof entry.uuid === 'string' && UUID_PATTERN.test(entry.uuid)
+        && (entry.parentUuid === null
+            || (typeof entry.parentUuid === 'string' && UUID_PATTERN.test(entry.parentUuid)))
+        && typeof entry.timestamp === 'number' && Number.isSafeInteger(entry.timestamp) && entry.timestamp >= 0
+        && typeof entry.type === 'string' && ENTRY_TYPES.has(entry.type)
+        && typeof entry.state === 'string' && ENTRY_STATES.has(entry.state)
+        && (entry.toolName === undefined || (typeof entry.toolName === 'string' && entry.toolName.length > 0))
+        && (params === undefined || (typeof params === 'object' && params !== null && !Array.isArray(params)))
+        && (entry.tokenEstimate === undefined || (typeof entry.tokenEstimate === 'number'
+            && Number.isSafeInteger(entry.tokenEstimate)
+            && entry.tokenEstimate >= 0));
+}
+function resolveLimit(value, defaultValue) {
+    const limit = value ?? defaultValue;
+    return Number.isSafeInteger(limit) && limit > 0 && limit <= defaultValue ? limit : undefined;
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function validateOpenedPath(fd, candidate, root, openedStat) {
     try {
-        const buffer = Buffer.alloc(bytesToRead);
-        fs.readSync(fd, buffer, 0, bytesToRead, 0);
-        const text = buffer.toString('utf-8');
-        return parseJsonlLines(text, /* isHead */ true);
+        const canonicalTarget = fs.realpathSync(candidate);
+        const currentStat = fs.lstatSync(candidate);
+        if (!isWithin(root, canonicalTarget) || currentStat.isSymbolicLink() || !sameFile(openedStat, currentStat)) {
+            return 'session path changed or escaped the configured root';
+        }
+        // Linux exposes the descriptor target directly. This closes intermediate
+        // component substitution without relying only on the current pathname.
+        if (process.platform === 'linux') {
+            const descriptorTarget = fs.realpathSync(`/proc/self/fd/${fd}`);
+            if (!isWithin(root, descriptorTarget))
+                return 'opened session descriptor escapes the configured root';
+        }
     }
-    finally {
-        fs.closeSync(fd);
+    catch {
+        return 'opened session path cannot be verified';
     }
+    return undefined;
+}
+function readExactly(fd, fileSize) {
+    const buffer = Buffer.alloc(fileSize);
+    let offset = 0;
+    while (offset < fileSize) {
+        const count = fs.readSync(fd, buffer, offset, fileSize - offset, offset);
+        if (count === 0)
+            throw new Error('unexpected EOF while reading session transcript');
+        offset += count;
+    }
+    return buffer;
 }
 /**
- * Read and parse the last TAIL_BYTES of the file.
+ * Inspect a legacy transcript through one no-follow descriptor. Automatic
+ * resume requires an explicit opt-in because this format has no commit marker.
  */
-function readTail(filePath, fileSize) {
-    const bytesToRead = Math.min(TAIL_BYTES, fileSize);
-    const offset = Math.max(0, fileSize - bytesToRead);
-    const fd = fs.openSync(filePath, 'r');
+export function resumeSession(filePath, options) {
+    if (!options || typeof options.sessionRoot !== 'string' || options.sessionRoot.trim().length === 0) {
+        return emptyResult(filePath, 'UNTRUSTED', ['a non-empty session root is required']);
+    }
+    const maxFileBytes = resolveLimit(options.maxFileBytes, DEFAULT_MAX_FILE_BYTES);
+    const maxRecordBytes = resolveLimit(options.maxRecordBytes, DEFAULT_MAX_RECORD_BYTES);
+    const maxRecords = resolveLimit(options.maxRecords, DEFAULT_MAX_RECORDS);
+    if (maxFileBytes === undefined || maxRecordBytes === undefined || maxRecords === undefined) {
+        return emptyResult(filePath, 'RESOURCE_LIMIT', ['recovery limits must be finite positive integers within hard ceilings']);
+    }
+    const candidate = path.resolve(filePath);
+    let root;
+    let parent;
     try {
-        const buffer = Buffer.alloc(bytesToRead);
-        fs.readSync(fd, buffer, 0, bytesToRead, offset);
-        const text = buffer.toString('utf-8');
-        // When offset is 0, we read from the start of the file so
-        // the first line is complete -- don't skip it.
-        const isMidFileRead = offset > 0;
-        return parseJsonlLines(text, /* isHead */ false, isMidFileRead);
+        root = fs.realpathSync(options.sessionRoot);
+        parent = fs.realpathSync(path.dirname(candidate));
+        if (!fs.statSync(root).isDirectory())
+            throw new Error('session root is not a directory');
     }
-    finally {
-        fs.closeSync(fd);
+    catch {
+        return emptyResult(filePath, 'UNTRUSTED', ['session root or parent cannot be resolved']);
     }
-}
-/**
- * Parse JSONL text into SessionEntry[], skipping corrupt/incomplete lines.
- * When reading from a mid-file offset (tail), the first partial line is skipped.
- * When reading head, the last partial line is skipped if the chunk doesn't
- * end with a newline.
- *
- * @param text - Raw text from the file chunk
- * @param isHead - Whether this is a head read (skip trailing partial line)
- * @param skipFirstLine - Whether to skip the first line (true for mid-file
- *   tail reads where the first line is likely a partial). Defaults to !isHead.
- */
-function parseJsonlLines(text, isHead, skipFirstLine) {
-    const lines = text.split('\n');
-    const entries = [];
-    // Default: skip first line for non-head reads (standard tail behavior)
-    const shouldSkipFirst = skipFirstLine ?? !isHead;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i].trim();
-        if (!line)
-            continue;
-        // Skip first line of mid-file tail read (may be partial)
-        if (shouldSkipFirst && i === 0 && lines.length > 1)
-            continue;
-        // Skip last line of head read if it may be truncated
-        if (isHead && i === lines.length - 1 && lines.length > 1 && !text.endsWith('\n'))
-            continue;
-        try {
-            const entry = JSON.parse(line);
-            if (isValidEntry(entry)) {
-                entries.push(entry);
+    if (!isWithin(root, parent)) {
+        return emptyResult(filePath, 'UNTRUSTED', ['session path escapes the configured root']);
+    }
+    let linkStat;
+    try {
+        linkStat = fs.lstatSync(candidate);
+    }
+    catch (error) {
+        const code = error.code;
+        return emptyResult(filePath, code === 'ENOENT' ? 'MISSING' : 'UNTRUSTED', [`lstat failed: ${code ?? 'UNKNOWN'}`]);
+    }
+    if (linkStat.isSymbolicLink() || !linkStat.isFile()) {
+        return emptyResult(filePath, 'UNTRUSTED', ['session path is not a regular, non-symlink file']);
+    }
+    let fd;
+    try {
+        fd = fs.openSync(candidate, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        const stat = fs.fstatSync(fd);
+        if (!sameFile(linkStat, stat)) {
+            return emptyResult(filePath, 'UNTRUSTED', ['session path changed before secure open']);
+        }
+        if (!stat.isFile() || stat.nlink !== 1) {
+            return emptyResult(filePath, 'UNTRUSTED', ['opened session is not an exclusive regular file']);
+        }
+        if (stat.size === 0)
+            return emptyResult(filePath, 'EMPTY');
+        if (stat.size > maxFileBytes) {
+            return emptyResult(filePath, 'RESOURCE_LIMIT', [`file exceeds ${maxFileBytes} bytes`]);
+        }
+        const pathError = validateOpenedPath(fd, candidate, root, stat);
+        if (pathError)
+            return emptyResult(filePath, 'UNTRUSTED', [pathError]);
+        const bytes = readExactly(fd, stat.size);
+        const finalStat = fs.fstatSync(fd);
+        const finalPathError = validateOpenedPath(fd, candidate, root, finalStat);
+        if (finalPathError || !sameFile(stat, finalStat) || stat.size !== finalStat.size
+            || stat.mtimeMs !== finalStat.mtimeMs || stat.ctimeMs !== finalStat.ctimeMs) {
+            return emptyResult(filePath, 'UNTRUSTED', [finalPathError ?? 'session changed while it was being inspected']);
+        }
+        const hasTornTail = bytes[bytes.length - 1] !== 0x0a;
+        let committedBytes = bytes;
+        if (hasTornTail) {
+            const finalLineBreak = bytes.lastIndexOf(0x0a);
+            const tornTailStart = finalLineBreak + 1;
+            const tornTailBytes = bytes.length - tornTailStart;
+            if (tornTailBytes > maxRecordBytes) {
+                return emptyResult(filePath, 'RESOURCE_LIMIT', [`record exceeds ${maxRecordBytes} bytes`]);
             }
+            committedBytes = bytes.subarray(0, tornTailStart);
+        }
+        let text;
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(committedBytes);
         }
         catch {
-            // Skip corrupt lines
-            continue;
+            return emptyResult(filePath, 'INVALID', ['transcript is not valid UTF-8']);
         }
-    }
-    return entries;
-}
-/**
- * Minimal validation that a parsed object looks like a SessionEntry.
- */
-function isValidEntry(obj) {
-    if (typeof obj !== 'object' || obj === null)
-        return false;
-    const entry = obj;
-    return (typeof entry.uuid === 'string' &&
-        typeof entry.timestamp === 'number' &&
-        typeof entry.type === 'string' &&
-        typeof entry.state === 'string');
-}
-/**
- * Count total lines in a file (for large files where head+tail don't overlap).
- * Only counts non-empty lines that parse as valid JSON.
- */
-function countLines(filePath) {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    let count = 0;
-    for (const line of content.split('\n')) {
-        const trimmed = line.trim();
-        if (trimmed) {
+        const lines = text.split('\n');
+        const entries = [];
+        const seen = new Set();
+        let previous;
+        for (const rawLine of lines) {
+            if (!rawLine.trim())
+                continue;
+            if (Buffer.byteLength(rawLine, 'utf8') > maxRecordBytes) {
+                return emptyResult(filePath, 'RESOURCE_LIMIT', [`record exceeds ${maxRecordBytes} bytes`]);
+            }
+            if (entries.length >= maxRecords) {
+                return emptyResult(filePath, 'RESOURCE_LIMIT', [`record count exceeds ${maxRecords}`]);
+            }
+            let parsed;
             try {
-                JSON.parse(trimmed);
-                count++;
+                parsed = JSON.parse(rawLine);
             }
             catch {
-                // Skip corrupt lines in count
+                return emptyResult(filePath, 'INVALID', ['corrupt JSON occurs before the final torn record']);
+            }
+            if (!isValidEntry(parsed))
+                return emptyResult(filePath, 'INVALID', ['entry fails the session schema']);
+            if (seen.has(parsed.uuid))
+                return emptyResult(filePath, 'INVALID', ['duplicate entry UUID']);
+            if (previous) {
+                if (parsed.parentUuid !== previous.uuid)
+                    return emptyResult(filePath, 'INVALID', ['broken parentUuid lineage']);
+                if (parsed.timestamp < previous.timestamp)
+                    return emptyResult(filePath, 'INVALID', ['timestamps are not monotonic']);
             }
+            else if (parsed.parentUuid !== null) {
+                return emptyResult(filePath, 'INVALID', ['first entry has a forged parentUuid']);
+            }
+            seen.add(parsed.uuid);
+            entries.push(parsed);
+            previous = parsed;
+        }
+        if (entries.length === 0) {
+            return emptyResult(filePath, hasTornTail ? 'INVALID' : 'EMPTY', hasTornTail ? ['only record is torn'] : []);
         }
+        const lastEntry = entries[entries.length - 1];
+        const diagnostics = [
+            'legacy JSONL has no durable commit marker',
+            ...(hasTornTail ? ['discarded an incomplete final record'] : []),
+        ];
+        return {
+            metadata: {
+                sessionId: path.basename(filePath, '.jsonl'), createdAt: entries[0].timestamp,
+                lastActivityAt: lastEntry.timestamp, entryCount: entries.length, state: lastEntry.state,
+            },
+            recentEntries: entries.slice(-RECENT_ENTRY_LIMIT), lastState: lastEntry.state,
+            canResume: options.allowLegacyUnverified === true,
+            disposition: 'LEGACY_UNVERIFIED', diagnostics,
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        return emptyResult(filePath, 'UNTRUSTED', [`secure open/read failed: ${code ?? 'UNKNOWN'}`]);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
     }
-    return count;
 }
 //# sourceMappingURL=session-resume.js.map

package/dist/mcp/tools/quality-assessment/gate.d.ts

@@ -1,8 +1,8 @@
 /**
  * Agentic QE v3 - Quality Gate MCP Tool (ADR-119)
  *
- * qe/quality/gate - two-gate, three-valued quality verdict against a pinned
- * ADR-117 checklist. Calls the SAME `runQualityGate` orchestrator as the
+ * qe/quality/gate - fail-closed quality and verification-reach verdict against
+ * a pinned ADR-117 checklist. Calls the SAME `runQualityGate` orchestrator as the
  * `aqe quality-gate` CLI subcommand so CLI and MCP stay in exact parity.
  *
  * The frontier judge is built from the forwarded HybridRouter
@@ -11,7 +11,8 @@
  */
 import { MCPToolBase, MCPToolConfig, MCPToolContext } from '../base';
 import { ToolResult } from '../../types';
-import type { QualityVerdictResult } from '../../../validation/quality-verdict.js';
+import { type ReachAwareQualityGateResult } from '../../../validation/quality-gate-runner.js';
+import type { VerificationReachManifest } from '../../../validation/verification-reach.js';
 export interface QualityGateParams {
     /** Pinned anchor checklist id (e.g. "A1-inRange"). */
     checklistId: string;
@@ -27,12 +28,14 @@ export interface QualityGateParams {
     } | null;
     /** Override the frozen anchor path (ADR-117). */
     anchorPath?: string;
+    /** Revision-bound evidence proving which failure modes the checks can observe. */
+    verificationManifest?: VerificationReachManifest;
     /** Frontier judge model id (ADR-111: always frontier-tier). */
     model?: string;
     [key: string]: unknown;
 }
-export declare class QualityGateTool extends MCPToolBase<QualityGateParams, QualityVerdictResult> {
+export declare class QualityGateTool extends MCPToolBase<QualityGateParams, ReachAwareQualityGateResult> {
     readonly config: MCPToolConfig;
-    execute(params: QualityGateParams, context: MCPToolContext): Promise<ToolResult<QualityVerdictResult>>;
+    execute(params: QualityGateParams, context: MCPToolContext): Promise<ToolResult<ReachAwareQualityGateResult>>;
 }
 //# sourceMappingURL=gate.d.ts.map

package/dist/mcp/tools/quality-assessment/gate.js

@@ -1,8 +1,8 @@
 /**
  * Agentic QE v3 - Quality Gate MCP Tool (ADR-119)
  *
- * qe/quality/gate - two-gate, three-valued quality verdict against a pinned
- * ADR-117 checklist. Calls the SAME `runQualityGate` orchestrator as the
+ * qe/quality/gate - fail-closed quality and verification-reach verdict against
+ * a pinned ADR-117 checklist. Calls the SAME `runQualityGate` orchestrator as the
  * `aqe quality-gate` CLI subcommand so CLI and MCP stay in exact parity.
  *
  * The frontier judge is built from the forwarded HybridRouter
@@ -12,13 +12,13 @@
 import { MCPToolBase } from '../base.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 import { getLLMRouter } from '../base.js';
-import { runQualityGate } from '../../../validation/quality-gate-runner.js';
+import { runQualityGate, } from '../../../validation/quality-gate-runner.js';
 import { createRouterFrontierJudge, createUnavailableJudge, } from '../../../validation/frontier-judge.js';
 export class QualityGateTool extends MCPToolBase {
     config = {
         name: 'qe/quality/gate',
         description: 'Two-gate, three-valued quality verdict (ADR-119): mechanical oracle gate plus a frontier '
-            + 'judge grading the artifact against a pinned ADR-117 checklist. Returns pass|fail|inconclusive.',
+            + 'judge grading plus failure-mode verification reach. Returns pass|fail|inconclusive.',
         domain: 'quality-assessment',
         schema: QUALITY_GATE_SCHEMA,
         streaming: false,
@@ -48,6 +48,7 @@ export class QualityGateTool extends MCPToolBase {
                 checklistId: params.checklistId,
                 judge,
                 anchorPath: params.anchorPath,
+                verificationManifest: params.verificationManifest,
             });
             return { success: true, data: result };
         }
@@ -79,6 +80,10 @@ const QUALITY_GATE_SCHEMA = {
             type: 'string',
             description: 'Override the frozen anchor path (ADR-117)',
         },
+        verificationManifest: {
+            type: 'object',
+            description: 'Hashed, revision-bound failure-mode verification reach manifest (#651)',
+        },
         model: {
             type: 'string',
             description: 'Frontier judge model id (ADR-111: always frontier-tier)',

package/dist/validation/quality-gate-runner.d.ts

@@ -8,14 +8,17 @@
  *   1. loads the pinned, hash-checked ADR-117 anchor via `loadAnchorSet` (which
  *      throws on drift — the frozen checklist can't be silently edited),
  *   2. selects the constant-denominator checklist for `checklistId`,
- *   3. runs the two-gate, three-valued `computeQualityVerdict` with the injected
- *      frontier judge.
+ *   3. evaluates the revision-bound failure-mode reach manifest before any
+ *      judge call (missing legacy manifests remain explicitly inconclusive),
+ *   4. runs the two-gate, three-valued `computeQualityVerdict` with the injected
+ *      frontier judge and combines the independent verdicts fail-closed.
  *
  * The oracle result and the judge are injected — this module owns no LLM and no
  * mutation runner, so it is deterministic and unit-testable with a fake judge.
  */
 import { type Judge, type QualityVerdictResult, type RequirementChecklist } from './quality-verdict.js';
 import type { OracleResult } from './oracle-eval.js';
+import { type VerificationCoverageVerdict, type VerificationReachManifest, type VerificationReachResult } from './verification-reach.js';
 /** Default frozen anchor location, relative to the project root (ADR-117). */
 export declare const DEFAULT_ANCHOR_RELATIVE_PATH = "verification/anchors/qe-anchor-v1.json";
 export interface QualityGateRequest {
@@ -32,13 +35,33 @@ export interface QualityGateRequest {
     judge: Judge;
     /** Override the frozen anchor path (absolute, or relative to project root). */
     anchorPath?: string;
+    /** Revision-bound failure-mode reach evidence. Omit only for legacy migration. */
+    verificationManifest?: VerificationReachManifest;
+}
+export interface LegacyUnknownVerificationCoverage {
+    kind: 'legacy-unknown';
+    coverageVerdict: 'inconclusive';
+    reason: string;
+}
+export interface VerifiedVerificationCoverage extends VerificationReachResult {
+    kind: 'verified';
+}
+export type QualityGateVerificationCoverage = LegacyUnknownVerificationCoverage | VerifiedVerificationCoverage;
+export interface ReachAwareQualityGateResult extends QualityVerdictResult {
+    /** Threshold/oracle/judge verdict before verification-reach preflight. */
+    qualityVerdict: QualityVerdictResult['verdict'];
+    /** Independent verdict for required failure-mode observation coverage. */
+    coverageVerdict: VerificationCoverageVerdict;
+    /** Overall fail-closed verdict. A pass requires both independent gates to pass. */
+    verdict: QualityVerdictResult['verdict'];
+    verification: QualityGateVerificationCoverage;
 }
 /**
  * Run the two-gate quality gate for one artifact against one pinned checklist.
  * Throws only for caller error (unknown checklist id, unloadable/drifted anchor);
- * every judgement outcome is returned as a three-valued `QualityVerdictResult`.
+ * every judgement outcome is returned as a three-valued reach-aware result.
  */
-export declare function runQualityGate(req: QualityGateRequest): Promise<QualityVerdictResult>;
+export declare function runQualityGate(req: QualityGateRequest): Promise<ReachAwareQualityGateResult>;
 /**
  * Load the pinned checklist for `checklistId` from the frozen anchor. Exposed so
  * callers (CLI/MCP) can list valid ids or pre-validate before building a judge.