seal-gate 0.3.0

package/src/detectors/confidence-language-detector.ts

@@ -0,0 +1,267 @@
+import { SealIssue, RiskLevel, SealEvidence, StructuralClaim, makeIssue } from '../types.js'
+
+/**
+ * Group definitions for overconfident language detection.
+ * Each group has:
+ * - patterns: regex patterns to match
+ * - category: human-readable category name
+ * - requires_evidence: whether matching requires supporting evidence
+ * - correlation_fn: optional function to cross-correlate with structural claims
+ */
+interface ConfidenceGroup {
+  id: string
+  label: string
+  patterns: RegExp[]
+  requires_evidence: boolean
+  evidence_type?: 'test_log' | 'security' | 'compatibility'
+  severity: 'MEDIUM' | 'HIGH'
+  correlation_fn?: (structuralClaims: StructuralClaim[]) => boolean
+}
+
+const GROUPS: ConfidenceGroup[] = [
+  // Group A — Completeness
+  {
+    id: 'A',
+    label: 'complete',
+    patterns: [
+      /\bfully\s+implemented\b/gi,
+      /\bfully\s+(?:tested|working|functional)\b/gi,
+      /\bhandles?\s+all\s+(edge\s+)?cases\b/gi,
+      /\b100%\s+complete\b/gi,
+    ],
+    requires_evidence: false,
+    severity: 'MEDIUM',
+  },
+  // Group B — Correctness
+  {
+    id: 'B',
+    label: 'correctness',
+    patterns: [
+      /\ball\s+tests?\s+pass(?:ed)?\b/gi,
+      /\bverified\s+correct\b/gi,
+      /\bbug-free\b/gi,
+      /\bguaranteed\b/gi,
+    ],
+    requires_evidence: true,
+    evidence_type: 'test_log',
+    severity: 'MEDIUM',
+  },
+  // Group C — Safety/Security
+  {
+    id: 'C',
+    label: 'security',
+    patterns: [
+      /\bsecure\b/gi,
+      /\bno\s+security\s+impact\b/gi,
+      /\bno\s+vulnerabilit(?:y|ies)\b/gi,
+    ],
+    requires_evidence: true,
+    evidence_type: 'security',
+    severity: 'HIGH',
+  },
+  // Group D — Compatibility
+  {
+    id: 'D',
+    label: 'compatibility',
+    patterns: [
+      /\bbackward\s+compatible\b/gi,
+      /\bno\s+breaking\s+changes?\b/gi,
+      /\bsafe\s+to\s+deploy\b/gi,
+    ],
+    requires_evidence: true,
+    evidence_type: 'compatibility',
+    severity: 'HIGH',
+    correlation_fn: (structuralClaims: StructuralClaim[]) => {
+      // If there are any endpoint changes, compatibility claims need extra scrutiny
+      return structuralClaims.some(c => c.type === 'structural_endpoint' || c.type === 'structural_migration')
+    },
+  },
+  // Group E — Readiness
+  {
+    id: 'E',
+    label: 'readiness',
+    patterns: [
+      /\bproduction[- ]ready\b/gi,
+      /\bready\s+to\s+ship\b/gi,
+      /\bdeploy-ready\b/gi,
+      /\bready\s+for\s+(production|deploy|release)\b/gi,
+    ],
+    requires_evidence: true,
+    evidence_type: 'test_log',
+    severity: 'HIGH',
+  },
+]
+
+export interface ConfidenceLangResult {
+  issues: SealIssue[]
+  trust_deductions: number
+  advisory_notes: string[]
+  matched_groups: Array<{ group: string; phrase: string }>
+}
+
+function hasEvidenceEvidence(evidence: SealEvidence, type: string): boolean {
+  switch (type) {
+    case 'test_log':
+      return evidence.test_log.trim().length > 0
+    case 'security':
+      return evidence.test_log.trim().length > 0 &&
+        /security|auth|unauthorized|pentest|vuln|safe|protect/i.test(evidence.test_log)
+    case 'compatibility':
+      return evidence.diff.trim().length > 0 // diff itself is a form of compatibility evidence
+    default:
+      return false
+  }
+}
+
+export class ConfidenceLanguageDetector {
+  static detect(params: {
+    output: string
+    risk_level: RiskLevel
+    evidence: SealEvidence
+    deduped_spans: Set<string>
+    structural_claims?: StructuralClaim[]
+  }): ConfidenceLangResult {
+    const { output, risk_level, evidence, deduped_spans, structural_claims = [] } = params
+    const issues: SealIssue[] = []
+    const advisory_notes: string[] = []
+    const matched_groups: Array<{ group: string; phrase: string }> = []
+    let trust_deductions = 0
+
+    const riskOrder = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL']
+    const isHighPlus = riskOrder.indexOf(risk_level) >= riskOrder.indexOf('HIGH')
+    const isLowEvidence = evidence.references.length === 0 && evidence.test_log.trim() === '' &&
+      evidence.build_log.trim() === '' && evidence.diff.trim() === ''
+
+    // Count total matches for OVERCONFIDENT_PATTERN advisory
+    let totalMatches = 0
+    const allPhrases: string[] = []
+
+    // Generic overconfident phrases (catch-all for phrases not in groups A-E)
+    const GENERIC_OVERCONFIDENT = /\b(definitely|all\s+good|no\s+issues|completely)\b/gi
+    let genMatch: RegExpExecArray | null
+    while ((genMatch = GENERIC_OVERCONFIDENT.exec(output)) !== null) {
+      totalMatches++
+      allPhrases.push(genMatch[0])
+      matched_groups.push({ group: 'generic', phrase: genMatch[0] })
+      trust_deductions += 5
+    }
+
+    // CL402: hedging language on HIGH+ risk (backward compat)
+    const HEDGING_PATTERN = /\b(probably|should\s+work|seems|might|appears\s+to|I\s+think)\b/gi
+    if (isHighPlus) {
+      HEDGING_PATTERN.lastIndex = 0
+      if (HEDGING_PATTERN.exec(output) !== null) {
+        issues.push(makeIssue({
+          type: 'AMBIGUITY', severity: 'HIGH', layer: 'L4', source: 'core',
+          rule_id: 'CL402', required_verdict: 'ESCALATE_TO_HUMAN',
+          evidence: `Hedging language in ${risk_level} risk artifact`,
+          required_fix: 'Either assert with evidence or escalate to human review',
+        }))
+      }
+    }
+
+    for (const group of GROUPS) {
+      for (const pattern of group.patterns) {
+        pattern.lastIndex = 0
+        let match: RegExpExecArray | null
+        while ((match = pattern.exec(output)) !== null) {
+          totalMatches++
+          allPhrases.push(match[0])
+
+          // Track matched group
+          matched_groups.push({ group: group.id, phrase: match[0] })
+
+          // Check if phrase is inside code fence (skip if deduped_spans contains it)
+          const spanKey = `${match.index}-${match.index + match[0].length}`
+          if (deduped_spans.has(spanKey)) continue
+
+          // Deduction for any overconfident phrase
+          trust_deductions += 5
+
+          if (group.requires_evidence) {
+            const hasEvidence = hasEvidenceEvidence(evidence, group.evidence_type!)
+
+            // Group D: check correlation with structural claims
+            if (group.id === 'D' && group.correlation_fn) {
+              const hasEndpointChanges = group.correlation_fn(structural_claims)
+              if (!hasEvidence && hasEndpointChanges) {
+                issues.push(makeIssue({
+                  type: 'COMPATIBILITY_RISK',
+                  severity: 'HIGH',
+                  layer: 'L4',
+                  source: 'core',
+                  rule_id: `CL-${group.id}01`,
+                  required_verdict: isHighPlus ? 'ESCALATE_TO_HUMAN' : 'REVISE',
+                  evidence: `"${match[0]}" claimed but endpoint/migration changes exist and no compatibility evidence provided`,
+                  required_fix: 'Provide backward-compatibility analysis or remove the claim',
+                }))
+                trust_deductions += 15
+              } else if (!hasEvidence) {
+                issues.push(makeIssue({
+                  type: 'MISSING_EVIDENCE',
+                  severity: group.severity,
+                  layer: 'L3',
+                  source: 'core',
+                  rule_id: `CL-${group.id}02`,
+                  evidence: `"${match[0]}" without supporting ${group.evidence_type} evidence`,
+                  required_fix: `Provide ${group.evidence_type} evidence or qualify the claim`,
+                }))
+                trust_deductions += 15
+              }
+            } else if (!hasEvidence && group.id === 'B') {
+              // Group B: correctness without test evidence
+              issues.push(makeIssue({
+                type: 'MISSING_EVIDENCE',
+                severity: 'MEDIUM',
+                layer: 'L3',
+                source: 'core',
+                rule_id: `CL-${group.id}01`,
+                evidence: `"${match[0]}" without test execution evidence`,
+                required_fix: 'Provide test_log demonstrating test coverage',
+              }))
+              trust_deductions += 10
+            } else if (!hasEvidence && group.id === 'C') {
+              // Group C: security without security evidence
+              issues.push(makeIssue({
+                type: 'MISSING_EVIDENCE',
+                severity: 'HIGH',
+                layer: 'L3',
+                source: 'core',
+                rule_id: `CL-${group.id}01`,
+                evidence: `"${match[0]}" without security review evidence`,
+                required_fix: 'Provide security test log or security reasoning',
+              }))
+              trust_deductions += 20
+            } else if (!hasEvidence && group.id === 'E') {
+              // Group E: readiness at HIGH+ risk
+              if (isHighPlus && isLowEvidence) {
+                issues.push(makeIssue({
+                  type: 'MISSING_EVIDENCE',
+                  severity: 'HIGH',
+                  layer: 'L3',
+                  source: 'core',
+                  rule_id: `CL-${group.id}01`,
+                  evidence: `"${match[0]}" at ${risk_level} risk without supporting evidence`,
+                  required_fix: 'Provide test evidence or reduce risk level before claiming readiness',
+                }))
+                trust_deductions += 20
+              }
+            }
+          }
+
+          // Non-blocking advisory note for 3+ matches at HIGH+ risk
+          if (totalMatches >= 3 && isHighPlus) {
+            advisory_notes.push(`Multiple overconfident patterns (${totalMatches}) at ${risk_level} risk — review claims carefully`)
+          }
+        }
+      }
+    }
+
+    // Also keep CL401/CL402 for backward compatibility
+    if (isLowEvidence && matched_groups.length > 0) {
+      advisory_notes.push(`CL401: overconfident language without supporting evidence — consider qualifying or adding evidence`)
+    }
+
+    return { issues, trust_deductions, advisory_notes, matched_groups }
+  }
+}

package/src/detectors/contradiction-detector.ts

@@ -0,0 +1,180 @@
+import { SealIssue, makeIssue } from '../types.js'
+
+export interface ContradictionDetectorInput {
+  artifact: string
+  artifact_file?: string
+}
+
+interface Section {
+  heading: string
+  body: string
+  startLine: number
+}
+
+// Conflict patterns: [write side pattern, readonly side pattern, description]
+const CONFLICT_PAIRS: Array<[RegExp, RegExp, string]> = [
+  [/\b(writes?|modifies?|overwrites?|creates?)\s+(\S+)/gi, /\b(\S+)\s+is\s+(read.?only|append.?only|immutable)\b/gi, 'write vs readonly constraint'],
+  [/\b(removes?|deletes?|drops?)\s+(\S+)/gi, /\b(requires?|depends?\s+on|needs?)\s+(\S+)/gi, 'remove vs dependency'],
+  [/step\s+(\d+)\s+.*?(writes?|creates?)\s+(\S+)/gi, /(\S+)\s+must\s+(exist|be\s+present)\s+before\s+step\s+(\d+)/gi, 'step ordering'],
+]
+
+// Non-goal violation: "non-goal: X" but body contains "SHALL/WILL/MUST X"
+const NON_GOAL_PATTERN = /non.?goals?\s*:?\s*([^\n]+)/gi
+const GOAL_CLAIM_PATTERN = /\b(?:shall|will|must|implement)\s+(\S+(?:\s+\S+){0,5})/gi
+
+function parseLines(text: string): string[] {
+  return text.split('\n')
+}
+
+// Strip code fences and inline code so pattern matching operates on prose only
+function stripCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')   // block fences
+    .replace(/`[^`\n]+`/g, ' ')         // inline code
+    .replace(/^\s*[-*]\s+\[[ x]\]\s*/gm, ' ') // task checkboxes
+}
+
+function extractSections(text: string): Section[] {
+  const lines = parseLines(text)
+  const sections: Section[] = []
+  let current: Section | null = null
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^#{1,4}\s/.test(line)) {
+      if (current) sections.push(current)
+      current = { heading: line.replace(/^#{1,4}\s*/, ''), body: '', startLine: i + 1 }
+    } else if (current) {
+      current.body += line + '\n'
+    }
+  }
+  if (current) sections.push(current)
+  return sections
+}
+
+function findLineNumber(text: string, searchStr: string): number {
+  const lines = parseLines(text)
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(searchStr)) return i + 1
+  }
+  return 1
+}
+
+export interface ContradictionResult {
+  issues: SealIssue[]
+  confirmed_strong_fields: number
+}
+
+export class ContradictionDetector {
+  static detect(input: ContradictionDetectorInput): ContradictionResult {
+    const { artifact, artifact_file = 'artifact' } = input
+    const issues: SealIssue[] = []
+    const sections = extractSections(artifact)
+
+    // Pairwise cross-section scan for write/readonly conflicts
+    for (let i = 0; i < sections.length; i++) {
+      for (let j = 0; j < sections.length; j++) {
+        if (i === j) continue
+        const secA = sections[i]
+        const secB = sections[j]
+        const proseA = stripCode(secA.body)
+        const proseB = stripCode(secB.body)
+
+        for (const [writePattern, readonlyPattern, desc] of CONFLICT_PAIRS) {
+          writePattern.lastIndex = 0
+          readonlyPattern.lastIndex = 0
+
+          const writeMatcher = writePattern.exec(proseA)
+          const readonlyMatcher = readonlyPattern.exec(proseB)
+
+          if (!writeMatcher || !readonlyMatcher) continue
+
+          // Find actual position in original (unstripped) body, since writeMatcher.index
+          // is relative to proseA (stripped) which is shorter when code blocks exist.
+          const actualIndexA = secA.body.indexOf(writeMatcher[0])
+          const actualIndexB = secB.body.indexOf(readonlyMatcher[0])
+          const lineA = actualIndexA >= 0
+            ? secA.startLine + (secA.body.slice(0, actualIndexA).split('\n').length - 1)
+            : secA.startLine
+          const lineB = actualIndexB >= 0
+            ? secB.startLine + (secB.body.slice(0, actualIndexB).split('\n').length - 1)
+            : secB.startLine
+
+          // Only emit once per pair (lower section index first)
+          if (i > j) continue
+
+          const quote = `§${secA.heading}: '${writeMatcher[0]}' || §${secB.heading}: '${readonlyMatcher[0]}'`
+
+          issues.push({
+            ...makeIssue({
+              type: 'LOGIC_BUG',
+              severity: 'HIGH',
+              layer: 'L1',
+              source: 'core',
+              rule_id: 'PR001',
+              required_verdict: 'BLOCK',
+              trust_deduction: 20,
+              evidence: `Contradiction (${desc}): ${quote}`,
+              suggested_fix: `Reconcile §${secA.heading} with §${secB.heading}`,
+            }),
+            evidence_file: artifact_file,
+            evidence_lines: [lineA, lineB],
+            evidence_quote: quote,
+            confidence: 0.85,
+            policy_tags: ['consistency'],
+          })
+        }
+      }
+    }
+
+    // Non-goal violation scan — operate on prose only
+    const artifactProse = stripCode(artifact)
+    NON_GOAL_PATTERN.lastIndex = 0
+    let ngMatch: RegExpExecArray | null
+    while ((ngMatch = NON_GOAL_PATTERN.exec(artifactProse)) !== null) {
+      const ngText = ngMatch[1].trim().toLowerCase()
+      // Search ngMatch text in artifactProse (stripCode preserves line structure
+      // even though content length changes), so the same text is on the same line.
+      const ngLine = findLineNumber(artifactProse, ngMatch[0].slice(0, 40))
+
+      GOAL_CLAIM_PATTERN.lastIndex = 0
+      let gcMatch: RegExpExecArray | null
+      while ((gcMatch = GOAL_CLAIM_PATTERN.exec(artifactProse)) !== null) {
+        // Extract significant words from the claim phrase (captured group after verb)
+        const claimPhrase = (gcMatch[1] ?? '').toLowerCase()
+        const claimWords = claimPhrase.split(/\s+/).filter(w => w.length > 4)
+        const ngWords = ngText.split(/\s+/).filter(w => w.length > 4)
+        // Require word overlap between non-goal text and claim line
+        const hasOverlap = ngWords.length > 0 && claimWords.length > 0 &&
+          claimWords.some(cw => ngWords.some(nw => nw.includes(cw) || cw.includes(nw)))
+        if (hasOverlap) {
+          const claimLine = findLineNumber(artifactProse, gcMatch[0].slice(0, 40))
+          if (Math.abs(claimLine - ngLine) < 3) continue // same line, skip
+
+          const quote = `Non-goal: '${ngText}' || Goal claim: '${gcMatch[0]}'`
+          issues.push({
+            ...makeIssue({
+              type: 'LOGIC_BUG',
+              severity: 'HIGH',
+              layer: 'L1',
+              source: 'core',
+              rule_id: 'PR001',
+              required_verdict: 'BLOCK',
+              trust_deduction: 20,
+              evidence: `Non-goal violated: ${quote}`,
+              suggested_fix: 'Remove claim or move item out of non-goals',
+            }),
+            evidence_file: artifact_file,
+            evidence_lines: [ngLine, claimLine],
+            evidence_quote: quote,
+            confidence: 0.8,
+            policy_tags: ['consistency'],
+          })
+          break // one violation per non-goal entry
+        }
+      }
+    }
+
+    return { issues, confirmed_strong_fields: 0 }
+  }
+}

package/src/detectors/criteria-coverage-detector.ts

@@ -0,0 +1,107 @@
+import { SealIssue, makeIssue } from '../types.js'
+
+export interface LockedCriterion {
+  id: string
+  text: string
+  source_file?: string
+  source_line?: number
+}
+
+export interface CriteriaCoverageInput {
+  artifact: string
+  artifact_file?: string
+  locked_criteria: LockedCriterion[]
+}
+
+export interface CriteriaCoverageResult {
+  issues: SealIssue[]
+  confirmed_strong_fields: number   // covered ACs → +5 TrustScore each (capped externally)
+  no_criteria_escalate: boolean     // true → no locked criteria found → ESCALATE_TO_HUMAN
+}
+
+function isCovered(criterion: LockedCriterion, artifact: string): boolean {
+  const lower = artifact.toLowerCase()
+
+  // Direct AC id mention
+  if (lower.includes(criterion.id.toLowerCase())) return true
+
+  // Keyword coverage: extract significant words (>4 chars) from criterion text
+  const words = criterion.text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 4)
+    .filter(w => !['shall', 'must', 'should', 'when', 'then', 'given', 'that', 'this', 'with'].includes(w))
+
+  if (words.length === 0) return false
+
+  // Require at least half of significant words present in artifact
+  const matched = words.filter(w => lower.includes(w)).length
+  return matched / words.length >= 0.5
+}
+
+export class CriteriaCoverageDetector {
+  static detect(input: CriteriaCoverageInput): CriteriaCoverageResult {
+    const { artifact, artifact_file = 'artifact', locked_criteria } = input
+
+    // Preflight: no locked criteria → ESCALATE
+    if (!locked_criteria || locked_criteria.length === 0) {
+      return {
+        issues: [{
+          ...makeIssue({
+            type: 'AMBIGUITY',
+            severity: 'MEDIUM',   // non-blocking — escalation comes from required_verdict, not severity
+            layer: 'L1',
+            source: 'core',
+            rule_id: 'PR002',
+            required_verdict: 'ESCALATE_TO_HUMAN',
+            trust_deduction: 15,
+            evidence: 'No locked acceptance criteria — cannot measure coverage against fixed yardstick',
+            suggested_fix: 'Lock criteria in intent.md or self-check.md BEFORE generating the artifact',
+          }),
+          policy_tags: ['coverage'],
+          confidence: 1.0,
+        }],
+        confirmed_strong_fields: 0,
+        no_criteria_escalate: true,
+      }
+    }
+
+    const issues: SealIssue[] = []
+    let confirmed = 0
+
+    for (const criterion of locked_criteria) {
+      if (isCovered(criterion, artifact)) {
+        confirmed++
+        continue
+      }
+
+      // Uncovered → SPEC_MISMATCH, Type H
+      const sourceFile = criterion.source_file ?? 'intent.md'
+      const sourceLine = criterion.source_line ?? 1
+      const quote = `${criterion.id} ${criterion.text.length > 120 ? criterion.text.slice(0, 120) + '…' : criterion.text} — no artifact section addresses this`
+
+      issues.push({
+        ...makeIssue({
+          type: 'SPEC_MISMATCH',
+          severity: 'MEDIUM',
+          layer: 'L1',
+          source: 'core',
+          rule_id: 'PR002',
+          required_verdict: 'REVISE',
+          trust_deduction: 10,
+          evidence: `Uncovered criterion: ${criterion.id} — ${criterion.text.slice(0, 80)}`,
+          suggested_fix: `Add a section in ${artifact_file} addressing: ${criterion.text.slice(0, 80)}`,
+        }),
+        evidence_file: sourceFile,
+        evidence_lines: [sourceLine],
+        evidence_quote: quote,
+        criterion_ref: criterion.id,
+        confidence: 0.8,
+        policy_tags: ['coverage'],
+      })
+    }
+
+    return { issues, confirmed_strong_fields: confirmed, no_criteria_escalate: false }
+  }
+}

package/src/detectors/evidence-checker.ts

@@ -0,0 +1,98 @@
+import { EvidenceEnvelope, EvidenceResult, CitationStatus } from '../types.js'
+import { existsSync, readFileSync } from 'node:fs'
+
+export type EvidenceMode = 'portable' | 'filesystem'
+
+export class EvidenceChecker {
+  static check(references: EvidenceEnvelope[], options: { mode: EvidenceMode } = { mode: 'portable' }): EvidenceResult[] {
+    return references.map(envelope => this.checkOne(envelope, options.mode))
+  }
+
+  private static checkOne(envelope: EvidenceEnvelope, mode: EvidenceMode): EvidenceResult {
+    // Structural validation
+    if (envelope.type === 'file') {
+      if (!envelope.path || envelope.line === undefined || !envelope.snapshot) {
+        return {
+          envelope, structurally_valid: false, filesystem_verified: null,
+          mismatch_detail: 'Missing path, line, or snapshot',
+          citation_status: 'not_applicable',
+        }
+      }
+      if (mode === 'filesystem') {
+        if (!existsSync(envelope.path)) {
+          return {
+            envelope, structurally_valid: true, filesystem_verified: false,
+            mismatch_detail: `File not found: ${envelope.path}`,
+            citation_status: 'phantom',
+          }
+        }
+        const lines = readFileSync(envelope.path, 'utf-8').split('\n')
+        const actualLine = lines[envelope.line - 1] ?? ''
+        if (actualLine.trim() !== envelope.snapshot.trim()) {
+          return {
+            envelope, structurally_valid: true, filesystem_verified: false,
+            mismatch_detail: `Snapshot mismatch at ${envelope.path}:${envelope.line}`,
+            citation_status: 'void',
+          }
+        }
+        return {
+          envelope, structurally_valid: true, filesystem_verified: true,
+          citation_status: 'verified',
+        }
+      }
+      // Portable mode: structurally valid but no filesystem check
+      return {
+        envelope, structurally_valid: true, filesystem_verified: null,
+        citation_status: 'not_applicable',
+      }
+    }
+
+    if (envelope.type === 'command') {
+      const hasRequiredFields = !!(envelope.command && envelope.output && envelope.exit_code !== undefined)
+      if (!hasRequiredFields) {
+        return {
+          envelope, structurally_valid: false, filesystem_verified: null,
+          mismatch_detail: 'Missing command, exit_code, or output',
+          citation_status: 'not_applicable',
+        }
+      }
+      const passed = envelope.exit_code === 0
+      return {
+        envelope, structurally_valid: true, filesystem_verified: passed,
+        mismatch_detail: passed ? undefined : `Command failed with exit_code ${envelope.exit_code}`,
+        citation_status: passed ? 'verified' : 'void',
+      }
+    }
+
+    if (envelope.type === 'url') {
+      const valid = !!(envelope.url && envelope.retrieved_at && envelope.content_snapshot)
+      return {
+        envelope, structurally_valid: valid, filesystem_verified: null,
+        citation_status: valid ? 'verified' : 'not_applicable',
+        mismatch_detail: valid ? undefined : 'Missing url, retrieved_at, or content_snapshot',
+      }
+    }
+
+    if (envelope.type === 'text') {
+      const valid = !!(envelope.label && envelope.content)
+      return {
+        envelope, structurally_valid: valid, filesystem_verified: null,
+        citation_status: valid ? 'verified' : 'not_applicable',
+      }
+    }
+
+    if (envelope.type === 'memory') {
+      const valid = !!(envelope.memory_key && envelope.retrieved_at && envelope.content_snapshot)
+      return {
+        envelope, structurally_valid: valid, filesystem_verified: null,
+        citation_status: valid ? 'verified' : 'not_applicable',
+      }
+    }
+
+    return {
+      envelope, structurally_valid: false, filesystem_verified: null,
+      mismatch_detail: 'Unknown envelope type',
+      citation_status: 'not_applicable',
+    }
+  }
+}