agentic-qe 3.14.0 → 3.14.2

package/dist/mcp/tool-registry.js

@@ -6,6 +6,7 @@
  */
 import { v4 as uuidv4 } from 'uuid';
 import { ALL_DOMAINS } from '../shared/types/index.js';
+import { resolveToolAnnotations } from './tool-annotations.js';
 import { sanitizeInput } from './security/cve-prevention.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { BatchToolExecutor } from './middleware/batch-executor.js';
@@ -234,32 +235,36 @@ export class ToolRegistry {
      * Register a tool
      */
     register(definition, handler) {
-        const existing = this.tools.get(definition.name);
+        const normalizedDefinition = {
+            ...definition,
+            annotations: resolveToolAnnotations(definition.name, definition.annotations),
+        };
+        const existing = this.tools.get(normalizedDefinition.name);
         if (existing) {
             // Update existing tool
-            existing.definition = definition;
+            existing.definition = normalizedDefinition;
             existing.handler = handler;
             return;
         }
         // Register new tool
         const tool = {
-            definition,
+            definition: normalizedDefinition,
             handler,
-            loaded: !definition.lazyLoad,
+            loaded: !normalizedDefinition.lazyLoad,
             loadCount: 0,
         };
-        this.tools.set(definition.name, tool);
+        this.tools.set(normalizedDefinition.name, tool);
         this.stats.totalTools++;
         // Track by category
-        this.categoryTools.get(definition.category)?.add(definition.name);
-        this.stats.byCategory[definition.category]++;
+        this.categoryTools.get(normalizedDefinition.category)?.add(normalizedDefinition.name);
+        this.stats.byCategory[normalizedDefinition.category]++;
         // Track by domain if specified
-        if (definition.domain) {
-            this.domainTools.get(definition.domain)?.add(definition.name);
-            this.stats.byDomain[definition.domain] =
-                (this.stats.byDomain[definition.domain] || 0) + 1;
+        if (normalizedDefinition.domain) {
+            this.domainTools.get(normalizedDefinition.domain)?.add(normalizedDefinition.name);
+            this.stats.byDomain[normalizedDefinition.domain] =
+                (this.stats.byDomain[normalizedDefinition.domain] || 0) + 1;
         }
-        if (!definition.lazyLoad) {
+        if (!normalizedDefinition.lazyLoad) {
             this.stats.loadedTools++;
         }
     }

package/dist/mcp/tools/base.d.ts

@@ -5,7 +5,7 @@
  * All domain tools extend this base class.
  */
 import { DomainName } from '../../shared/types';
-import { ToolResult, ToolResultMetadata } from '../types';
+import { ToolAnnotations, ToolResult, ToolResultMetadata } from '../types';
 import { MemoryBackend } from '../../kernel/interfaces';
 /**
  * Database-free mode: when AQE_MEMORY_BACKEND=memory, the MCP server keeps all
@@ -114,6 +114,7 @@ export interface MCPToolConfig {
     schema: MCPToolSchema;
     streaming?: boolean;
     timeout?: number;
+    annotations?: ToolAnnotations;
 }
 /**
  * Streaming callback for long-running operations
@@ -279,6 +280,11 @@ export declare abstract class MCPToolBase<TParams extends Record<string, unknown
      * Get tool description
      */
     get description(): string;
+    /**
+     * Return the complete, conservative safety metadata for this tool.
+     * Missing hints must never be interpreted as permission to skip policy.
+     */
+    get annotations(): ToolAnnotations;
     /**
      * Get domain this tool belongs to
      */

package/dist/mcp/tools/base.js

@@ -5,6 +5,7 @@
  * All domain tools extend this base class.
  */
 import { v4 as uuidv4 } from 'uuid';
+import { resolveToolAnnotations } from '../tool-annotations.js';
 import { HybridMemoryBackend } from '../../kernel/hybrid-backend.js';
 import { InMemoryBackend } from '../../kernel/memory-backend.js';
 import { findProjectRoot } from '../../kernel/unified-memory.js';
@@ -457,6 +458,13 @@ export class MCPToolBase {
     get description() {
         return this.config.description;
     }
+    /**
+     * Return the complete, conservative safety metadata for this tool.
+     * Missing hints must never be interpreted as permission to skip policy.
+     */
+    get annotations() {
+        return resolveToolAnnotations(this.name, this.config.annotations);
+    }
     /**
      * Get domain this tool belongs to
      */

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/mcp/tools/registry.d.ts

@@ -6,6 +6,7 @@
  */
 import { MCPToolBase } from './base';
 import { ToolRegistry } from '../tool-registry';
+import type { ToolAnnotations } from '../types';
 export declare const QE_TOOL_NAMES: {
     readonly QX_ANALYZE: "qe/qx/analyze";
     readonly TEST_SCHEDULE: "qe/tests/schedule";
@@ -80,6 +81,7 @@ export declare function getToolsByDomain(domain: string): MCPToolBase[];
 export declare function getToolDefinition(tool: MCPToolBase): {
     name: string;
     description: string;
+    annotations: ToolAnnotations;
     inputSchema: Record<string, unknown>;
 };
 /**
@@ -88,6 +90,7 @@ export declare function getToolDefinition(tool: MCPToolBase): {
 export declare function getAllToolDefinitions(): Array<{
     name: string;
     description: string;
+    annotations: ToolAnnotations;
     inputSchema: Record<string, unknown>;
 }>;
 /**

package/dist/mcp/tools/registry.js

@@ -216,6 +216,7 @@ export function getToolDefinition(tool) {
     return {
         name: tool.name,
         description: tool.description,
+        annotations: tool.annotations,
         inputSchema: {
             ...schema,
             type: schema.type || 'object',

package/dist/mcp/types.d.ts

@@ -15,6 +15,20 @@ export interface ToolParameter {
     default?: unknown;
     enum?: string[];
 }
+/**
+ * Optional safety metadata advertised by an MCP tool.
+ *
+ * These hints help clients make better presentation and confirmation
+ * decisions. They are advisory only: authorization, sandboxing, and policy
+ * checks remain authoritative for every invocation.
+ */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
 /**
  * MCP tool definition
  */
@@ -26,6 +40,7 @@ export interface ToolDefinition {
     domain?: DomainName;
     lazyLoad?: boolean;
     isConcurrencySafe?: boolean;
+    annotations?: ToolAnnotations;
 }
 /**
  * Tool categories for organization and lazy loading

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.

package/dist/validation/quality-gate-runner.js

@@ -8,8 +8,10 @@
  *   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.
@@ -18,21 +20,48 @@ import path from 'node:path';
 import { loadAnchorSet } from './anchor-set.js';
 import { computeQualityVerdict, } from './quality-verdict.js';
 import { findProjectRoot } from '../kernel/unified-memory.js';
+import { computeVerificationArtifactDigest, evaluateVerificationReach, } from './verification-reach.js';
 /** Default frozen anchor location, relative to the project root (ADR-117). */
 export const DEFAULT_ANCHOR_RELATIVE_PATH = 'verification/anchors/qe-anchor-v1.json';
 /**
  * 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 async function runQualityGate(req) {
     const checklist = loadChecklist(req.checklistId, req.anchorPath);
-    return computeQualityVerdict({
+    if (req.verificationManifest
+        && req.verificationManifest.artifact.digest !== computeVerificationArtifactDigest(req.artifact)) {
+        throw new Error('Verification reach manifest artifact digest does not match the judged artifact');
+    }
+    const verification = req.verificationManifest
+        ? { kind: 'verified', ...evaluateVerificationReach(req.verificationManifest) }
+        : {
+            kind: 'legacy-unknown',
+            coverageVerdict: 'inconclusive',
+            reason: 'legacy quality-gate request has no verification reach manifest',
+        };
+    const coverageVerdict = verification.coverageVerdict;
+    const quality = await computeQualityVerdict({
         oracle: req.oracleResult,
         artifact: req.artifact,
         checklist,
         judge: req.judge,
     });
+    return {
+        ...quality,
+        qualityVerdict: quality.verdict,
+        coverageVerdict,
+        verdict: combineVerdicts(quality.verdict, coverageVerdict),
+        verification,
+    };
+}
+function combineVerdicts(quality, coverage) {
+    if (quality === 'fail' || coverage === 'fail')
+        return 'fail';
+    if (quality === 'pass' && coverage === 'pass')
+        return 'pass';
+    return 'inconclusive';
 }
 /**
  * Load the pinned checklist for `checklistId` from the frozen anchor. Exposed so

package/dist/validation/verification-reach.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Failure-mode verification reach contracts (#651).
+ *
+ * Quality evidence is useful only within the boundary it actually observed.
+ * This module keeps that boundary revision-bound and fail-closed: direct,
+ * executed, fresh evidence with the required oracle can cover a risk; partial,
+ * inferred, stale, unavailable, and wrong-target evidence remains visible but
+ * cannot silently produce a passing coverage verdict.
+ */
+export type FailureModeSeverity = 'critical' | 'high' | 'medium' | 'low';
+export type VerificationChannel = 'static' | 'build' | 'runtime' | 'api' | 'browser' | 'telemetry' | 'hardware' | 'human';
+export type VerificationReachLevel = 'direct' | 'partial' | 'none';
+export type VerificationEvidenceClass = 'EXECUTED' | 'STATIC' | 'INFERRED' | 'UNKNOWN';
+export type VerificationExecutionStatus = 'passed' | 'failed' | 'not-run' | 'unavailable';
+export type UncoveredDisposition = 'fail' | 'inconclusive' | 'human-review';
+export type VerificationCoverageVerdict = 'pass' | UncoveredDisposition;
+export interface VerificationTarget {
+    revision: string;
+    digest: string;
+    environment: string;
+}
+export interface VerificationCost {
+    tokens?: number;
+    durationMs?: number;
+    monetary?: number;
+}
+export interface VerificationReach {
+    checkId: string;
+    channel: VerificationChannel;
+    reach: VerificationReachLevel;
+    evidenceClass: VerificationEvidenceClass;
+    executionStatus: VerificationExecutionStatus;
+    target: VerificationTarget;
+    oracleRef?: string;
+    observedAt?: string;
+    limitations: string[];
+    cost?: VerificationCost;
+}
+export interface FailureModeRequirement {
+    riskId: string;
+    failureMode: string;
+    severity: FailureModeSeverity;
+    requiredOracle: string;
+    requiredObservations: VerificationChannel[];
+    checks: VerificationReach[];
+    dispositionWhenUncovered: UncoveredDisposition;
+}
+export interface VerificationReachManifest {
+    id: string;
+    systemUnderTest: string;
+    artifact: VerificationTarget;
+    risks: FailureModeRequirement[];
+    generatedAt: string;
+    expiresAt?: string;
+    manifestHash: string;
+}
+export type VerificationReachManifestInput = Omit<VerificationReachManifest, 'manifestHash'>;
+export interface FailureModeReachResult {
+    riskId: string;
+    failureMode: string;
+    severity: FailureModeSeverity;
+    verdict: VerificationCoverageVerdict;
+    directCheckIds: string[];
+    partialCheckIds: string[];
+    failedCheckIds: string[];
+    uncoveredObservations: VerificationChannel[];
+    limitations: string[];
+    reason: string;
+}
+export interface VerificationReachResult {
+    manifestId: string;
+    manifestHash: string;
+    systemUnderTest: string;
+    artifact: VerificationTarget;
+    coverageVerdict: VerificationCoverageVerdict;
+    risks: FailureModeReachResult[];
+    evaluatedAt: string;
+}
+export interface VerificationReachEvaluationOptions {
+    now?: Date;
+}
+/** Create a manifest whose hash binds its target, risks, checks, and lifetime. */
+export declare function createVerificationReachManifest(input: VerificationReachManifestInput): VerificationReachManifest;
+/** Compute the canonical SHA-256 identity for all manifest content except the hash itself. */
+export declare function computeVerificationReachManifestHash(manifest: VerificationReachManifest | VerificationReachManifestInput): string;
+/** Bind a reach manifest to the exact artifact bytes submitted to the gate. */
+export declare function computeVerificationArtifactDigest(artifact: string): string;
+/** Evaluate whether the declared evidence can directly observe every required failure mode. */
+export declare function evaluateVerificationReach(manifest: VerificationReachManifest, options?: VerificationReachEvaluationOptions): VerificationReachResult;
+//# sourceMappingURL=verification-reach.d.ts.map

package/dist/validation/verification-reach.js

@@ -0,0 +1,187 @@
+/**
+ * Failure-mode verification reach contracts (#651).
+ *
+ * Quality evidence is useful only within the boundary it actually observed.
+ * This module keeps that boundary revision-bound and fail-closed: direct,
+ * executed, fresh evidence with the required oracle can cover a risk; partial,
+ * inferred, stale, unavailable, and wrong-target evidence remains visible but
+ * cannot silently produce a passing coverage verdict.
+ */
+import { createHash } from 'node:crypto';
+/** Create a manifest whose hash binds its target, risks, checks, and lifetime. */
+export function createVerificationReachManifest(input) {
+    validateManifestShape(input);
+    const manifest = structuredClone(input);
+    return {
+        ...manifest,
+        manifestHash: computeVerificationReachManifestHash(manifest),
+    };
+}
+/** Compute the canonical SHA-256 identity for all manifest content except the hash itself. */
+export function computeVerificationReachManifestHash(manifest) {
+    const { manifestHash: _ignored, ...content } = manifest;
+    return `sha256:${createHash('sha256').update(canonicalJson(content)).digest('hex')}`;
+}
+/** Bind a reach manifest to the exact artifact bytes submitted to the gate. */
+export function computeVerificationArtifactDigest(artifact) {
+    return `sha256:${createHash('sha256').update(artifact).digest('hex')}`;
+}
+/** Evaluate whether the declared evidence can directly observe every required failure mode. */
+export function evaluateVerificationReach(manifest, options = {}) {
+    validateManifestShape(manifest);
+    const expectedHash = computeVerificationReachManifestHash(manifest);
+    if (manifest.manifestHash !== expectedHash) {
+        throw new Error(`Verification reach manifestHash mismatch: expected ${expectedHash}`);
+    }
+    const now = options.now ?? new Date();
+    const evaluatedAt = now.toISOString();
+    const manifestExpired = manifest.expiresAt != null
+        && now.getTime() > parseTimestamp(manifest.expiresAt, 'expiresAt');
+    const risks = manifest.risks.map((requirement) => evaluateRisk(requirement, manifest, manifestExpired, now.getTime()));
+    return {
+        manifestId: manifest.id,
+        manifestHash: manifest.manifestHash,
+        systemUnderTest: manifest.systemUnderTest,
+        artifact: structuredClone(manifest.artifact),
+        coverageVerdict: aggregateVerdicts(risks.map((risk) => risk.verdict)),
+        risks,
+        evaluatedAt,
+    };
+}
+function evaluateRisk(requirement, manifest, manifestExpired, evaluatedAt) {
+    const direct = new Set();
+    const partial = new Set();
+    const failed = new Set();
+    const covered = new Set();
+    const limitations = new Set();
+    for (const check of requirement.checks) {
+        for (const limitation of check.limitations)
+            limitations.add(limitation);
+        if (!isUsableObservation(check, manifest, manifestExpired, evaluatedAt))
+            continue;
+        if (check.reach === 'partial') {
+            partial.add(check.checkId);
+            continue;
+        }
+        if (check.reach !== 'direct')
+            continue;
+        if (!requirement.requiredObservations.includes(check.channel))
+            continue;
+        if (check.oracleRef !== requirement.requiredOracle)
+            continue;
+        if (check.executionStatus === 'failed') {
+            failed.add(check.checkId);
+            continue;
+        }
+        if (check.executionStatus === 'passed') {
+            direct.add(check.checkId);
+            covered.add(check.channel);
+        }
+    }
+    const uncoveredObservations = requirement.requiredObservations.filter((channel) => !covered.has(channel));
+    const verdict = failed.size > 0
+        ? 'fail'
+        : uncoveredObservations.length === 0
+            ? 'pass'
+            : requirement.dispositionWhenUncovered;
+    return {
+        riskId: requirement.riskId,
+        failureMode: requirement.failureMode,
+        severity: requirement.severity,
+        verdict,
+        directCheckIds: [...direct],
+        partialCheckIds: [...partial],
+        failedCheckIds: [...failed],
+        uncoveredObservations,
+        limitations: [...limitations],
+        reason: buildRiskReason(verdict, failed, uncoveredObservations, manifestExpired),
+    };
+}
+function isUsableObservation(check, manifest, manifestExpired, evaluatedAt) {
+    if (manifestExpired)
+        return false;
+    if (!sameTarget(check.target, manifest.artifact))
+        return false;
+    if (check.evidenceClass !== 'EXECUTED')
+        return false;
+    if (check.executionStatus === 'not-run' || check.executionStatus === 'unavailable')
+        return false;
+    if (!check.observedAt)
+        return false;
+    const observedAt = parseTimestamp(check.observedAt, `check ${check.checkId} observedAt`);
+    const generatedAt = parseTimestamp(manifest.generatedAt, 'generatedAt');
+    if (observedAt < generatedAt)
+        return false;
+    if (observedAt > evaluatedAt)
+        return false;
+    if (manifest.expiresAt && observedAt > parseTimestamp(manifest.expiresAt, 'expiresAt'))
+        return false;
+    return true;
+}
+function sameTarget(actual, expected) {
+    return actual.revision === expected.revision
+        && actual.digest === expected.digest
+        && actual.environment === expected.environment;
+}
+function aggregateVerdicts(verdicts) {
+    if (verdicts.some((verdict) => verdict === 'fail'))
+        return 'fail';
+    if (verdicts.some((verdict) => verdict === 'human-review'))
+        return 'human-review';
+    if (verdicts.some((verdict) => verdict === 'inconclusive'))
+        return 'inconclusive';
+    return 'pass';
+}
+function buildRiskReason(verdict, failed, uncovered, manifestExpired) {
+    if (manifestExpired)
+        return `verification manifest expired; uncovered: ${uncovered.join(', ')}`;
+    if (failed.size > 0)
+        return `direct check failed: ${[...failed].join(', ')}`;
+    if (verdict === 'pass')
+        return 'all required observation channels have direct executed reach';
+    return `required reach is uncovered (${uncovered.join(', ')}); disposition: ${verdict}`;
+}
+function validateManifestShape(manifest) {
+    if (!manifest.id || !manifest.systemUnderTest) {
+        throw new Error('Verification reach manifest requires id and systemUnderTest');
+    }
+    if (!manifest.artifact.revision || !manifest.artifact.digest || !manifest.artifact.environment) {
+        throw new Error('Verification reach manifest artifact requires revision, digest, and environment');
+    }
+    parseTimestamp(manifest.generatedAt, 'generatedAt');
+    if (manifest.expiresAt)
+        parseTimestamp(manifest.expiresAt, 'expiresAt');
+    if (manifest.risks.length === 0) {
+        throw new Error('Verification reach manifest requires at least one failure mode');
+    }
+    const riskIds = new Set();
+    for (const risk of manifest.risks) {
+        if (riskIds.has(risk.riskId))
+            throw new Error(`Duplicate riskId: ${risk.riskId}`);
+        riskIds.add(risk.riskId);
+        if (!risk.riskId || !risk.failureMode || !risk.requiredOracle) {
+            throw new Error('Each failure mode requires riskId, failureMode, and requiredOracle');
+        }
+        if (risk.requiredObservations.length === 0) {
+            throw new Error(`Failure mode ${risk.riskId} requires at least one observation channel`);
+        }
+    }
+}
+function parseTimestamp(value, field) {
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        throw new Error(`Invalid ${field} timestamp: ${value}`);
+    return timestamp;
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=verification-reach.js.map

package/dist/verification/adversarial-verify/index.d.ts

@@ -11,7 +11,7 @@
  *   const verdicts = await adversarialVerify(findings, { judge, refuters: 3 });
  *   const { confirmed, killed } = partitionVerdicts(verdicts);
  */
-export type { Finding, FindingVerdict, FindingSeverity, FindingOutcome, RefuterVote, Judge, AdversarialVerifyOptions, } from './types.js';
+export type { Finding, FindingVerdict, FindingSeverity, FindingOutcome, RefuterVote, JudgeMeasurementReceipt, EndpointClass, SnapshotIdentityLevel, ReceiptSemantics, CacheStatus, Judge, AdversarialVerifyOptions, } from './types.js';
 export { adversarialVerify, partitionVerdicts } from './verify.js';
 export { synthesizeVerdict, majorityKill, isFindingVerdict } from './synthesize.js';
 export { refuterPrompt, DEFAULT_LENSES } from './prompts.js';