seal-gate 0.3.0

package/src/drift/trust-integration.ts

@@ -0,0 +1,28 @@
+import type { DriftStatus } from './drift-guard.js';
+
+/**
+ * Lightweight adapter: map drift distance/status to [0,1] reliability score
+ * that can be fed into TrustMemory.
+ *
+ * Safe to import even when TrustMemory v2 is not yet integrated:
+ * this module has zero side effects and produces a plain number.
+ */
+export function driftScoreForTrust(
+  status: DriftStatus,
+  distance: number,
+  options?: { hardLimit: number }
+): number {
+  const hard = options?.hardLimit ?? 0.55;
+
+  switch (status) {
+    case 'NORMAL':
+      return 1.0;
+    case 'SOFT_DRIFT': {
+      // Linear degradation from 1.0 at soft_limit to 0.5 at hard_limit
+      const t = Math.min(distance / hard, 1.0);
+      return 1.0 - t * 0.5;
+    }
+    case 'HARD_DRIFT':
+      return 0.0;
+  }
+}

package/src/engine/citation-verifier.ts

@@ -0,0 +1,210 @@
+import { createHash } from 'node:crypto'
+import { SealIssue, CitationStatus } from '../types.js'
+
+export type EvidenceGrade = 'strong' | 'weak' | 'none'
+
+export interface CitationVerdict {
+  status: CitationStatus
+  quality: EvidenceGrade
+  similarScore: number
+  isFabricated: boolean
+  fabricatedReason?: 'location_not_found' | 'content_mismatch'
+}
+
+export interface AbsencePattern {
+  positive: RegExp
+  negated: RegExp
+  label?: string
+}
+
+const SIMILARITY_STRONG = 0.85
+const SIMILARITY_WEAK = 0.60
+
+function normalize(str: string): string {
+  return str.replace(/\s+/g, ' ').trim().toLowerCase()
+}
+
+/** Levenshtein distance between two strings */
+function levenshtein(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  // Early termination for empty strings
+  if (m === 0) return n
+  if (n === 0) return m
+
+  // Use two rows to reduce memory
+  let prev: number[] = Array.from({ length: n + 1 }, (_, i) => i)
+  let curr: number[] = new Array(n + 1)
+
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      curr[j] = Math.min(
+        prev[j] + 1,        // deletion
+        curr[j - 1] + 1,    // insertion
+        prev[j - 1] + cost, // substitution
+      )
+    }
+    ;[prev, curr] = [curr, prev]
+  }
+  return prev[n]
+}
+
+/**
+ * Fuzzy-match a quote against actual content.
+ * Returns 0-1 similarity score where 1 = exact match.
+ */
+function fuzzyMatch(quote: string, content: string): number {
+  const normQuote = normalize(quote)
+  const normContent = normalize(content)
+  if (normContent.length === 0 && normQuote.length === 0) return 1
+  if (normContent.length === 0) return 0
+  const dist = levenshtein(normQuote, normContent)
+  const maxLen = Math.max(normQuote.length, normContent.length)
+  if (maxLen === 0) return 1
+  return Math.max(0, 1 - dist / maxLen)
+}
+
+/** Check if the issue describes an absence (something missing) */
+function isAbsenceDescription(quote: string): boolean {
+  return /^(no |missing |absent |lacks? |without )/i.test(quote.trim())
+}
+
+export class CitationVerifier {
+  /** Compute SHA-256 hash of artifact content for pipeline integrity */
+  static computeHash(content: string): string {
+    return createHash('sha256').update(content).digest('hex')
+  }
+
+  /** Check pipeline integrity: preflight hash vs current hash */
+  static checkIntegrity(preflightHash: string, currentHash: string): boolean {
+    return preflightHash === currentHash
+  }
+
+  /**
+   * Verify a single issue's citation against the actual artifact content.
+   *
+   * @param issue - The issue with evidence_file/evidence_lines/evidence_quote
+   * @param artifact - The artifact string (input.output or input.evidence.diff)
+   * @param artifactFile - The logical file name of the artifact
+   * @param opts - Optional: absencePatterns for absence-mode verification
+   * @returns CitationVerdict with status and quality
+   */
+  static verify(
+    issue: SealIssue,
+    artifact: string,
+    artifactFile: string,
+    opts?: { absencePatterns?: AbsencePattern[] },
+  ): CitationVerdict {
+    // No evidence fields → not_applicable
+    if (!issue.evidence_file || !issue.evidence_lines || issue.evidence_lines.length === 0) {
+      return { status: 'not_applicable', quality: 'none', similarScore: 0, isFabricated: false }
+    }
+
+    // If the issue cites a different file, skip (we only check against the main artifact)
+    if (issue.evidence_file !== artifactFile) {
+      return { status: 'not_applicable', quality: 'none', similarScore: 0, isFabricated: false }
+    }
+
+    const lines = artifact.split('\n')
+    const [lineA] = issue.evidence_lines
+
+    // Phantom: line out of range
+    if (lineA < 1 || lineA > lines.length) {
+      return { status: 'phantom', quality: 'none', similarScore: 0, isFabricated: true, fabricatedReason: 'location_not_found' }
+    }
+
+    const lineContent = lines[lineA - 1] ?? ''
+    const quote = issue.evidence_quote ?? ''
+
+    // Absence mode: check if this looks like a "something is missing" description
+    if (opts?.absencePatterns && opts.absencePatterns.length > 0 && isAbsenceDescription(quote)) {
+      for (const pattern of opts.absencePatterns) {
+        const hasPositive = pattern.positive.test(artifact)
+        const hasNegated = pattern.negated.test(artifact)
+
+        if (hasPositive && !hasNegated) {
+          // Absence confirmed: positive anchor present, negated token absent
+          return { status: 'verified', quality: 'strong', similarScore: 1, isFabricated: false }
+        }
+        if (hasPositive && hasNegated) {
+          // Absence NOT confirmed: negated token IS present
+          // This means the detector was wrong about the absence
+          return { status: 'void', quality: 'none', similarScore: 0, isFabricated: true, fabricatedReason: 'content_mismatch' }
+        }
+        // No positive anchor → can't confirm, fall through to literal mode
+      }
+    }
+
+    // Literal excerpt mode: fuzzy-match the quote against the line content
+    const score = fuzzyMatch(quote, lineContent)
+
+    if (score >= SIMILARITY_STRONG) {
+      return { status: 'verified', quality: 'strong', similarScore: score, isFabricated: false }
+    }
+    if (score >= SIMILARITY_WEAK) {
+      return { status: 'drifted', quality: 'weak', similarScore: score, isFabricated: false }
+    }
+    return { status: 'void', quality: 'none', similarScore: score, isFabricated: true, fabricatedReason: 'content_mismatch' }
+  }
+
+  /**
+   * Verify multiple issues and annotate them with citation_status.
+   * Returns fabricated_evidence entries for any that failed verification.
+   */
+  static verifyIssues(
+    issues: SealIssue[],
+    artifact: string,
+    artifactFile: string,
+    opts?: { absencePatterns?: AbsencePattern[] },
+  ): { issues: SealIssue[]; fabricated: FabricatedEvidenceEntry[] } {
+    const fabricated: FabricatedEvidenceEntry[] = []
+
+    const annotated = issues.map(issue => {
+      const verdict = this.verify(issue, artifact, artifactFile, opts)
+      // Annotate the issue
+      const updated = { ...issue, citation_status: verdict.status }
+
+      if (verdict.isFabricated) {
+        fabricated.push({
+          type: 'FABRICATED_EVIDENCE',
+          severity: verdict.status === 'phantom' ? 'CRITICAL' : 'HIGH',
+          is_blocking: false,
+          evidence: `Detector claimed citation at ${issue.evidence_file}:${issue.evidence_lines?.[0]} but it was ${verdict.fabricatedReason}`,
+          layer: 'L3',
+          source: 'core',
+          citation_status: verdict.status,
+          fabricated_reason: verdict.fabricatedReason!,
+          claimed_evidence: {
+            file: issue.evidence_file,
+            lines: issue.evidence_lines,
+            quote: issue.evidence_quote,
+          },
+        })
+      }
+
+      return updated
+    })
+
+    return { issues: annotated, fabricated }
+  }
+}
+
+export interface FabricatedEvidenceEntry {
+  type: 'FABRICATED_EVIDENCE'
+  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW'
+  is_blocking: boolean
+  evidence: string
+  layer: IssueLayer
+  source: 'core' | 'llm-overlay' | 'extension'
+  citation_status: CitationStatus
+  fabricated_reason: 'location_not_found' | 'content_mismatch'
+  claimed_evidence: {
+    file?: string
+    lines?: number[]
+    quote?: string
+  }
+}
+
+type IssueLayer = 'L1' | 'L2' | 'L3' | 'L4' | 'EXTENSION' | 'LLM_OVERLAY'

package/src/engine/extension-registry.ts

@@ -0,0 +1,35 @@
+import { SealExtension, SealInput, SealIssue, makeIssue } from '../types.js'
+
+export interface ExtensionResult {
+  issues: SealIssue[]
+  errors: string[]
+}
+
+export class ExtensionRegistry {
+  private extensions: SealExtension[] = []
+
+  add(ext: SealExtension): void {
+    this.extensions.push(ext)
+  }
+
+  run(input: SealInput): ExtensionResult {
+    const issues: SealIssue[] = []
+    const errors: string[] = []
+
+    for (const ext of this.extensions) {
+      try {
+        const result = ext.check(input)
+        issues.push(...result)
+      } catch (err) {
+        const msg = `Extension [${ext.name}] failed: ${err instanceof Error ? err.message : String(err)}`
+        errors.push(msg)
+        issues.push(makeIssue({
+          type: 'OTHER', severity: 'LOW', layer: 'EXTENSION', source: 'extension',
+          evidence: msg,
+        }))
+      }
+    }
+
+    return { issues, errors }
+  }
+}

package/src/engine/heuristic-scorer.ts

@@ -0,0 +1,16 @@
+import { SealIssue, Verdict, verdictFromScore } from '../types.js'
+
+export class HeuristicScorer {
+  static computeDetectorScore(findings: Array<{ trust_deduction?: number }>): number {
+    const total = findings.reduce((sum, f) => sum + (f.trust_deduction ?? 0), 0)
+    return Math.max(0, Math.min(100, Math.floor(100 - total)))
+  }
+
+  static computeFinalScore(detectorScore: number, policyDeductions: number): number {
+    return Math.max(0, Math.min(100, Math.floor(detectorScore - policyDeductions)))
+  }
+
+  static toVerdict(score: number, blockingIssues: SealIssue[]): Verdict {
+    return verdictFromScore(score, blockingIssues.length > 0)
+  }
+}

package/src/engine/input-normalizer.ts

@@ -0,0 +1,32 @@
+import { SealInput, ArtifactType, RiskLevel } from '../types.js'
+import { SealInputError } from '../errors.js'
+
+const VALID_ARTIFACT_TYPES: ArtifactType[] = ['llm_response', 'code_diff', 'test_plan', 'design', 'migration', 'plan_review']
+const VALID_RISK_LEVELS: RiskLevel[] = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL']
+
+export class InputNormalizer {
+  static normalize(input: Partial<SealInput>): SealInput {
+    if (!input.output || input.output.trim() === '') {
+      throw new SealInputError('output is required and must be non-empty', 'output')
+    }
+    if (!input.artifact_type || !VALID_ARTIFACT_TYPES.includes(input.artifact_type)) {
+      throw new SealInputError(`artifact_type must be one of: ${VALID_ARTIFACT_TYPES.join(', ')}`, 'artifact_type')
+    }
+    if (input.risk_hint !== null && input.risk_hint !== undefined && !VALID_RISK_LEVELS.includes(input.risk_hint)) {
+      throw new SealInputError(`risk_hint must be one of: ${VALID_RISK_LEVELS.join(', ')} or null`, 'risk_hint')
+    }
+    return {
+      artifact_type: input.artifact_type,
+      spec: input.spec ?? null,
+      output: input.output.trim(),
+      evidence: {
+        test_log: input.evidence?.test_log ?? '',
+        build_log: input.evidence?.build_log ?? '',
+        diff: input.evidence?.diff ?? '',
+        references: input.evidence?.references ?? [],
+      },
+      risk_hint: input.risk_hint ?? null,
+      context: input.context,
+    }
+  }
+}

package/src/engine/plan-review-pipeline.ts

@@ -0,0 +1,209 @@
+/**
+ * plan_review mode pipeline — gates plans, designs, proposals, spec seeds.
+ *
+ * Core principle: no runtime exists, so behavioral claims are out of scope.
+ * The gateable question is "is this coherent and complete against what was
+ * locked before it was written?" Falsification, not approval.
+ *
+ * Pass threshold: 90 (higher than code mode's 85)
+ * High-risk [71,89]: ESCALATE_TO_HUMAN instead of PASS_WITH_WARNINGS
+ */
+
+import {
+  SealInput, SealVerdict, SealIssue, Verdict,
+  gradeEvidence, maxVerdict, worstOf, makeIssue, SCHEMA_VERSION, NEXT_ACTION
+} from '../types.js'
+import type { ScoreBreakdown, FabricatedEvidence } from '../types.js'
+import { ClaimExtractor } from '../detectors/claim-extractor.js'
+import { RiskClassifier } from '../detectors/risk-classifier.js'
+import { SpecCoverageDetector } from '../detectors/spec-coverage-detector.js'
+import { ContradictionDetector } from '../detectors/contradiction-detector.js'
+import { CriteriaCoverageDetector } from '../detectors/criteria-coverage-detector.js'
+import { OrphanClaimDetector } from '../detectors/orphan-claim-detector.js'
+import { FalsificationDetector } from '../detectors/falsification-detector.js'
+import { HeuristicScorer } from './heuristic-scorer.js'
+import { PolicyEngine } from './policy-engine.js'
+import { ExtensionRegistry } from './extension-registry.js'
+import { TrustMemory } from '../trust-memory.js'
+
+const PLAN_PASS_THRESHOLD = 90
+const PLAN_ESCALATE_BAND_LOW = 71
+const PLAN_ESCALATE_BAND_HIGH = 89
+
+function planReviewVerdict(score: number, hasBlocking: boolean, riskLevel: string): Verdict {
+  if (hasBlocking) return 'BLOCK'
+
+  // High-risk middle band → ESCALATE instead of PASS_WITH_WARNINGS
+  if (score >= PLAN_ESCALATE_BAND_LOW && score <= PLAN_ESCALATE_BAND_HIGH && riskLevel === 'HIGH') {
+    return 'ESCALATE_TO_HUMAN'
+  }
+
+  if (score >= PLAN_PASS_THRESHOLD) return 'PASS'
+  if (score >= PLAN_ESCALATE_BAND_LOW) return 'PASS_WITH_WARNINGS'
+  if (score >= 50) return 'REVISE'
+  if (score >= 30) return 'ESCALATE_TO_HUMAN'
+  return 'BLOCK'
+}
+
+function evidenceBonus(issues: SealIssue[]): number {
+  // +5 per confirmed-strong field (from CriteriaCoverageDetector), capped at +15
+  const strongCount = issues
+    .filter(i => gradeEvidence(i) === 'strong' && i.type !== 'LOGIC_BUG')
+    .length
+  return Math.min(strongCount * 5, 15)
+}
+
+export async function runPlanReviewPipeline(
+  input: SealInput,
+  registry: ExtensionRegistry,
+  trustMemory: TrustMemory | null,
+): Promise<SealVerdict> {
+  const artifactFile = (input.context?.artifact_file as string) ?? 'artifact.md'
+
+  // Step 1: Extract claims — behavioral claim patterns are designed for code artifacts,
+  // not prose (words like "fixed", "fully" in specs are noise, not claims needing evidence).
+  // OrphanClaimDetector in plan_review mode checks traceability anchors, not behavioral claims.
+  const claims = input.artifact_type === 'plan_review' ? [] : ClaimExtractor.extract(input.output)
+
+  // Step 2: Classify risk
+  const riskResult = RiskClassifier.classify({
+    output: input.output,
+    diff: input.evidence?.diff ?? '',
+    risk_hint: input.risk_hint,
+  })
+
+  // Step 3: Spec coverage (reused from code mode)
+  const specResult = SpecCoverageDetector.detect(input.spec, input.output)
+  const assumptions_detected = [...specResult.assumptions]
+
+  // Stage 1 — ContradictionDetector (inline, keystone)
+  const contradictionResult = ContradictionDetector.detect({
+    artifact: input.output,
+    artifact_file: artifactFile,
+  })
+
+  // Stage 2 — CriteriaCoverageDetector (inline)
+  const lockedCriteria = input.context?.locked_criteria ?? []
+  const coverageResult = CriteriaCoverageDetector.detect({
+    artifact: input.output,
+    artifact_file: artifactFile,
+    locked_criteria: lockedCriteria as Array<{ id: string; text: string; source_file?: string; source_line?: number }>,
+  })
+
+  // Preflight failure: no locked criteria
+  if (coverageResult.no_criteria_escalate) {
+    assumptions_detected.push('No locked criteria — coverage measurement not possible')
+  }
+
+  // Stage 3 — OrphanClaimDetector (inline)
+  const orphanResult = OrphanClaimDetector.detect(claims, input.output)
+
+  // All deterministic findings
+  const deterministicFindings: SealIssue[] = [
+    ...contradictionResult.issues,
+    ...coverageResult.issues,
+    ...orphanResult.issues,
+    ...specResult.issues,
+  ]
+
+  // Evidence bonus from covered criteria (confirmed-strong fields)
+  const criteriaBonus = Math.min(coverageResult.confirmed_strong_fields * 5, 15)
+
+  // Stage 4 — FalsificationDetector (parallel agent, async)
+  const falsificationIssues = await FalsificationDetector.detect(input)
+
+  // Score computation (start 100 + bonus, deduct per issue)
+  const allDeductions = deterministicFindings.filter(f => (f.trust_deduction ?? 0) > 0)
+  const falsificationDeductions = falsificationIssues
+    .filter(f => (f.trust_deduction ?? 0) > 0)
+    .reduce((sum, f) => sum + (f.trust_deduction ?? 0), 0)
+  const baseScore = HeuristicScorer.computeDetectorScore(allDeductions)
+  const detectorScore = Math.max(0, Math.min(100, baseScore + criteriaBonus - falsificationDeductions))
+
+  // Policy engine (reused)
+  const hasBlocking = deterministicFindings.some(f => f.is_blocking)
+  const baseVerdict = planReviewVerdict(detectorScore, hasBlocking, riskResult.risk_level)
+
+  const allForPolicy = [...deterministicFindings, ...falsificationIssues]
+  const policyResult = PolicyEngine.apply({
+    base_verdict: baseVerdict,
+    detector_score: detectorScore,
+    risk_level: riskResult.risk_level,
+    input,
+    all_findings: allForPolicy,
+    llm_signals: null,
+  })
+
+  // Extensions
+  const extResult = registry.run(input)
+
+  // Combine all issues
+  const allIssues = [...deterministicFindings, ...policyResult.injected_issues, ...falsificationIssues]
+
+  // Final score
+  const finalScore = HeuristicScorer.computeFinalScore(detectorScore, policyResult.policy_deductions)
+
+  // Honor required_verdict on all findings (including non-blocking)
+  const requiredVerdicts = allForPolicy
+    .map(i => i.required_verdict)
+    .filter((v): v is Verdict => !!v)
+
+  // Final verdict
+  let finalVerdict = worstOf(
+    policyResult.verdict,
+    planReviewVerdict(finalScore, allIssues.some(i => i.is_blocking), riskResult.risk_level),
+  )
+  for (const rv of requiredVerdicts) finalVerdict = worstOf(finalVerdict, rv)
+
+  // Preflight escalation overrides
+  if (coverageResult.no_criteria_escalate) {
+    finalVerdict = worstOf(finalVerdict, 'ESCALATE_TO_HUMAN')
+  }
+
+  // Extension block check
+  if (extResult.issues.some(i => i.is_blocking && i.required_verdict === 'BLOCK')) {
+    finalVerdict = 'BLOCK'
+  }
+
+  const allIssuesFull = [...allIssues, ...extResult.issues]
+  const blocking = allIssuesFull.filter(i => i.is_blocking)
+  const nonBlocking = allIssuesFull.filter(i => !i.is_blocking)
+
+  // TrustMemory
+  const agentId = input.context?.agent_id
+  if (trustMemory && agentId) {
+    trustMemory.record(agentId, {
+      verdict: finalVerdict,
+      trust_score: finalScore,
+      risk_level: riskResult.risk_level,
+      blocking_count: blocking.length,
+    })
+  }
+
+  return {
+    verdict: finalVerdict,
+    trust_score: finalScore,
+    risk_level: riskResult.risk_level,
+    summary: `plan_review: ${finalVerdict} (trust=${finalScore}, risk=${riskResult.risk_level}): ${blocking.length} blocking, ${nonBlocking.length} non-blocking`,
+    deterministic_findings: allIssuesFull,
+    llm_findings: falsificationIssues,
+    blocking_issues: blocking,
+    non_blocking_issues: nonBlocking,
+    missing_evidence: [],
+    assumptions_detected,
+    advisory_notes: [],
+    next_action: NEXT_ACTION[finalVerdict],
+    schema_version: SCHEMA_VERSION,
+    score_breakdown: {
+      base: 100,
+      issue_deductions: blocking.reduce((s, i) => s + (i.trust_deduction ?? 0), 0) + nonBlocking.reduce((s, i) => s + (i.trust_deduction ?? 0), 0),
+      missing_evidence_deductions: 0,
+      risk_deductions: riskResult.trust_deduction,
+      overconfidence_deductions: 0,
+      evidence_bonuses: 0,
+      final: finalScore,
+    },
+    fabricated_evidence: [],
+    trust_memory_summary: (trustMemory && agentId) ? trustMemory.getSummary(agentId) : undefined,
+  }
+}