solidity-argus 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Solidity smart contract security auditing plugin for OpenCode — 4 specialized agents, 12 tools (11 core + optional Solodit), and a curated vulnerability knowledge base",
   "keywords": [
     "solidity",

package/src/agents/argus-prompt.ts

@@ -225,6 +225,49 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
   \`\`\`
 - Wait for both to complete before synthesizing their results.
 
+### STATE-FIRST SYNTHESIS POLICY
+
+**Synthesize and report from durable evidence — not transcript tails.**
+
+When building the final report or synthesizing findings:
+1. **Primary source**: \`toolsExecuted\` records, \`findings\` from state, and event stream data persisted via argus_* tool outputs.
+2. **Secondary source**: Tool transcript text (use only when durable evidence is unavailable or incomplete).
+3. **Never** synthesize findings from ephemeral background transcript retrieval alone if durable state evidence exists.
+
+**Bounded background fan-out**: For deep audits, limit concurrent high-context background delegations to max 2 at a time. Split larger workloads into sequential waves. This prevents retrieval blind spots from simultaneous long-running tasks.
+
+Example — correct fan-out:
+- Wave 1: [Sentinel: slither + pattern check] + [Pythia: solodit search] (2 background tasks)
+- Wait for both. Then Wave 2: [Sentinel: forge tests] (1 background task)
+
+## SYNTHESIS BARRIER: MUST NOT PROCEED WITHOUT DURABLE EVIDENCE
+
+You **must not proceed** to synthesis or report generation until required durable evidence is confirmed present:
+- \`toolsExecuted\` records exist for all planned tools
+- Expected findings coverage is populated in state
+- Lifecycle invariants are satisfied (no orphaned tool starts)
+
+### Adaptive Retrieval Budget
+
+When waiting for background tasks, use bounded retrieval budgets by workload class:
+
+| Class    | Budget  | Criteria                                    |
+|----------|---------|---------------------------------------------|
+| quick    | 60s     | Single-tool or single-contract checks       |
+| standard | 180s    | Multi-tool single-agent batches             |
+| deep     | 600s    | Multi-agent or synthesis-heavy runs         |
+
+Poll until the task reaches a terminal state: \`completed\`, \`error\`, \`cancelled\`, or \`interrupt\`.
+
+### Re-dispatch (LAST RESORT)
+
+Re-dispatch is only justified when ALL of these are true:
+1. The task has reached terminal state OR retrieval budget has expired
+2. Required durable evidence is STILL missing from state/events
+3. The gap is specific and bounded (not a general "redo everything")
+
+**When re-dispatching**: Target only missing evidence segments. Use \`run_in_background=false\` (foreground only) for re-dispatch pivots. Do NOT re-dispatch routinely after a single transcript retrieval miss if durable state evidence is already complete.
+
 ## TASK COMPLETION TRACKING
 
 You must track which audit phases are complete to avoid redundant work and tool re-execution.
@@ -272,7 +315,7 @@ Your subagents have access to these specialized tools. Know when to delegate eac
 - **\`argus_generate_report\`**:
   - **Use**: During Reporting.
   - **Purpose**: Generates the final artifact.
-  - **Note**: Requires structured input of findings. Ensure the tone is objective and helpful.
+  - **Note**: Requires a versioned report_input JSON string matching the ReportInput contract (schema_version 1.0.0). Do not send natural-language-only findings to Scribe for tool invocation.
 
 - **\`argus_sync_knowledge\`**:
   - **Use**: Maintenance.
@@ -422,18 +465,28 @@ Tools may fail. You must be resilient.
 
 **An audit without a report is an incomplete audit.** Your FINAL action before finishing MUST be delegating to Scribe. No exceptions.
 
-After you have synthesized your findings, compile them into a structured list and invoke Scribe:
+After you have synthesized your findings, build a canonical ReportInput payload and invoke Scribe:
+
+**State-first requirement**: Before invoking Scribe, verify that \`toolsExecuted\` in your ReportInput contains entries for each tool you ran. Do NOT proceed to report generation if required tool coverage is missing from durable state — re-run the missing tool instead. Use \`preflight_policy: "strict-fail"\` for the final report invocation.
 
 \`\`\`
 Task(subagent_type="scribe", prompt="Generate the final security audit report.
 
 Project: {name}
 Scope: {list of audited files}
-
-Findings (pass ALL of these):
-1. [SEVERITY] Title — File:Lines — Description — Impact — Recommendation
-2. [SEVERITY] Title — File:Lines — Description — Impact — Recommendation
-...
+ReportInput JSON (pass EXACTLY, no prose substitution):
+{
+  "run_id": "{run-id}",
+  "seq": {last-seq},
+  "session_id": "{session-id}",
+  "tool_call_id": "{tool-call-id}",
+  "source": "argus",
+  "schema_version": "1.0.0",
+  "projectDir": "{project-dir}",
+  "findings": [canonical findings],
+  "toolsExecuted": [canonical tool executions],
+  "scope": ["..."]
+}
 
 Additional context:
 - Tools used: Slither, Forge, Pattern Checker, Solodit
@@ -442,7 +495,13 @@ Additional context:
 ")
 \`\`\`
 
-You do NOT need to pass raw JSON or serialized audit state. Just pass your findings as a structured list in natural language — Scribe will format them professionally.
+Scribe must call argus_generate_report with:
+- project_name: project name
+- scope: audited file list
+- report_input: serialized ReportInput JSON string
+- preflight_policy: "strict-fail" (non-negotiable for final report)
+
+Legacy audit_state is transitional-only and deprecated.
 
 **If you have zero findings, still invoke Scribe** with an empty findings list. A clean report is still a report.
 

package/src/agents/scribe-prompt.ts

@@ -8,7 +8,7 @@ Your core responsibilities are:
 1.  **Aggregation**: Collecting findings from various tools and subagents.
 2.  **Deduplication**: Merging similar findings (e.g., multiple Slither warnings for the same issue).
 3.  **Contextualization**: Explaining *why* a finding matters in the context of the specific protocol.
-4.  **Report Generation**: Producing the final Markdown artifact and writing it to disk.
+4.  **Report Generation**: Producing the final Markdown artifact via \`argus_generate_report\`.
 
 ## REPORT STRUCTURE
 
@@ -41,13 +41,21 @@ You must adhere to these strict writing standards:
 
 ## HOW TO GENERATE THE REPORT
 
-Argus passes you findings in natural language. Write the full report yourself in Markdown following the Report Structure above.
+Argus passes you structured report data. Use that payload directly and keep it schema-accurate.
 
 **Your workflow**:
-1. Read the findings Argus provides. Deduplicate, cross-reference, and assess severity.
+1. Validate Argus provided a serialized ReportInput JSON string (schema_version 1.0.0) with required fields: run_id, seq, session_id, tool_call_id, source, schema_version, projectDir, findings, toolsExecuted, scope. **Execution integrity check**: \`toolsExecuted\` must be non-empty for the audit to be considered complete. If \`toolsExecuted\` is empty or missing key tool families (slither, forge, patterns), add a \`## Limitations\` section to the report noting which tool coverage is absent.
 2. Write the complete report in Markdown following the Report Structure and Output Format sections.
-3. Save the report to disk using the \`write\` tool. Path: \`.opencode/reports/{ProjectName}-audit-{YYYY-MM-DD}.md\` relative to the project root.
-4. Confirm the file path in your response to Argus: "Report written to: {filePath}".
+3. Call \`argus_generate_report\` with arguments { project_name, scope, report_input }. Use legacy \`audit_state\` only for transitional compatibility and treat it as deprecated.
+4. **Limitations disclosure** (MANDATORY when tools fail): If any tool was unavailable, timed out, or failed, add a \`## Limitations\` section to the report BEFORE \`## Findings\`. Use this format:
+   - \`**Tool name**: [reason \u2014 unavailable/failed/timed out]. [Impact on finding coverage if any.]\`
+   - Example: \`**argus_solodit_search**: External database was unavailable. Known-vulnerability cross-referencing was performed using local patterns only.\`
+   - Never silently omit limitations — incomplete coverage must be disclosed.
+5. Confirm the report was generated in your response to Argus: "Report generated via argus_generate_report: {filePath}".
+
+## SINGLE-WRITER POLICY
+
+**CRITICAL**: You must NEVER write final report files directly to disk. All report persistence MUST go through \`argus_generate_report\`. This tool enforces the single-writer policy — it is the sole component authorized to create report artifacts on disk. Direct file writes for report output are a policy violation and will be rejected.
 
 ## QUALITY STANDARDS
 

package/src/cli/commands/init.ts

@@ -20,7 +20,7 @@ export const initCommand: CliCommand = {
   description: "Initialize Argus configuration for this project",
   async execute(_args: string[]): Promise<number> {
     const cwd = process.cwd()
-    const configDir = join(cwd, ".opencode")
+    const configDir = join(cwd, ".argus")
     const configPath = join(configDir, "solidity-argus.json")
 
     if (existsSync(configPath)) {

package/src/config/schema.ts

@@ -31,7 +31,7 @@ const ReportingConfigSchema = z.object({
   format: z.enum(["markdown"]).default("markdown"),
   severityThreshold: z.enum(["critical", "high", "medium", "low", "informational"]).default("low"),
   gasAnalysis: z.boolean().default(false),
-  output_dir: z.string().default(".opencode/reports/"),
+  output_dir: z.string().default(".argus/reports/"),
 })
 
 const SoloditConfigSchema = z.object({
@@ -43,6 +43,10 @@ const BackgroundConfigSchema = z.object({
   max_concurrent: z.number().positive().default(3),
 })
 
+const MigrationConfigSchema = z.object({
+  mode: z.enum(["legacy", "dual", "strict"]).default("legacy"),
+})
+
 export const ArgusConfigSchema = z.object({
   agents: z
     .object({
@@ -70,7 +74,7 @@ export const ArgusConfigSchema = z.object({
     format: "markdown",
     severityThreshold: "low",
     gasAnalysis: false,
-    output_dir: ".opencode/reports/",
+    output_dir: ".argus/reports/",
   }),
   solodit: SoloditConfigSchema.default({
     enabled: true,
@@ -82,4 +86,5 @@ export const ArgusConfigSchema = z.object({
   background: BackgroundConfigSchema.default({
     max_concurrent: 3,
   }),
+  migration: MigrationConfigSchema.optional(),
 })

package/src/create-hooks.ts

@@ -1,4 +1,3 @@
-import { join } from "node:path"
 import type { Hooks as PluginHooks } from "@opencode-ai/plugin"
 import type { ArgusConfig } from "./config/types"
 import { createAuditEnforcer } from "./features/audit-enforcer/audit-enforcer"
@@ -7,7 +6,12 @@ import {
   createSessionRecoveryHandler,
   createToolErrorRecoveryHandler,
 } from "./features/error-recovery"
+import { getMigrationMode } from "./features/migration"
+import { adaptLegacyFindings } from "./features/migration/migration-adapter"
+import { computeParityMetrics, formatParityReport } from "./features/migration/parity-telemetry"
 import { createDebouncedSave } from "./features/persistent-state/audit-state-manager"
+import { createEventSink, type EventSink } from "./features/persistent-state/event-sink"
+import { materializeFindings } from "./features/persistent-state/findings-materializer"
 import { recordRun } from "./features/persistent-state/global-run-index"
 import { createRunJournal } from "./features/persistent-state/run-journal"
 import { createAgentTracker } from "./hooks/agent-tracker"
@@ -22,6 +26,7 @@ import { createSystemPromptHook } from "./hooks/system-prompt-hook"
 import { createToolTrackingHook } from "./hooks/tool-tracking-hook"
 import type { HookName } from "./hooks/types"
 import type { Managers } from "./managers/types"
+import { createAuditArtifactResolver } from "./shared/audit-artifact-resolver"
 import { createLogger } from "./shared/logger"
 import type { AuditState } from "./state/types"
 import { detectAuditArtifacts } from "./utils/audit-artifact-detector"
@@ -77,6 +82,9 @@ export function createHooks(args: {
   const agentTracker = createAgentTracker()
   _agentTrackerRef = agentTracker
 
+  const migrationMode = getMigrationMode(config)
+  logger.debug(`Migration mode: ${migrationMode}`)
+
   const contextMonitor = createContextMonitor()
   const sessionRecoveryHandler = createSessionRecoveryHandler(auditStateManager)
   const debouncedSave = createDebouncedSave(auditStateManager.save)
@@ -88,15 +96,21 @@ export function createHooks(args: {
   )
   const outputTruncator = createToolOutputTruncator()
 
+  let currentEventSink: EventSink | null = null
+  let currentOpencodeSessionId = ""
+
   // Sub-handlers run sequentially. The state persistence handler MUST be first:
   // it loads persisted state on session.created, overriding the fresh default.
   const {
     hook: eventHook,
     getAuditState,
     setAuditState,
+    setEventSink,
+    getLastFinalizationResult,
   } = createEventHook(projectDir, [
     async ({ type, sessionId, auditState, setAuditState: setState }) => {
       if (type === "session.created") {
+        currentOpencodeSessionId = sessionId ?? ""
         const timestamp = Date.now()
         let recoveredState: AuditState | null = null
 
@@ -123,12 +137,24 @@ export function createHooks(args: {
 
         const effectiveState = recoveredState ?? auditStateManager.get()
         if (effectiveState) {
+          const resolver = createAuditArtifactResolver(effectiveState.sessionId, projectDir)
+          try {
+            const journalFile = resolver.paths().journalFile
+            // createEventSink builds the same path internally; the resolver makes it explicit.
+            currentEventSink = createEventSink(effectiveState.sessionId, projectDir)
+            setEventSink(currentEventSink)
+            logger.debug(`Event sink journal path: ${journalFile}`)
+          } catch (error) {
+            logger.error(
+              `Failed to create event sink: ${error instanceof Error ? error.message : String(error)}`,
+            )
+          }
           void recordRun({
             runId: effectiveState.sessionId,
             opencodeSessionId: sessionId,
             projectDir: effectiveState.projectDir,
-            statePath: join(effectiveState.projectDir, ".opencode", "argus-state.json"),
-            journalPath: join(effectiveState.projectDir, ".opencode", "argus-journal.jsonl"),
+            statePath: resolver.paths().stateFile,
+            journalPath: resolver.paths().journalFile,
             startedAt: effectiveState.startTime,
             phase: effectiveState.currentPhase,
             findingsCount: effectiveState.findings.length,
@@ -161,17 +187,36 @@ export function createHooks(args: {
           toolsExecutedCount: auditState.toolsExecuted.length,
         })
 
+        const idleResolver = createAuditArtifactResolver(
+          auditState.sessionId,
+          auditState.projectDir,
+        )
         void recordRun({
           runId: auditState.sessionId,
           opencodeSessionId: sessionId,
           projectDir: auditState.projectDir,
-          statePath: join(auditState.projectDir, ".opencode", "argus-state.json"),
-          journalPath: join(auditState.projectDir, ".opencode", "argus-journal.jsonl"),
+          statePath: idleResolver.paths().stateFile,
+          journalPath: idleResolver.paths().journalFile,
           startedAt: auditState.startTime,
           phase: auditState.currentPhase,
           findingsCount: auditState.findings.length,
         })
 
+        if (migrationMode !== "legacy") {
+          try {
+            const { legacyFindings, canonicalFindings } = adaptLegacyFindings(
+              auditState,
+              migrationMode,
+              auditState.sessionId,
+            )
+            const parityMetrics = computeParityMetrics(legacyFindings, canonicalFindings)
+            logger.debug(formatParityReport(parityMetrics))
+          } catch (error) {
+            logger.warn(
+              `Migration parity check failed: ${error instanceof Error ? error.message : String(error)}`,
+            )
+          }
+        }
         return
       }
 
@@ -180,16 +225,10 @@ export function createHooks(args: {
         if (auditState) {
           await auditStateManager.save(auditState)
         }
-        await auditStateManager.archive()
-
-        if (sessionId) {
-          agentTracker.clearSession(sessionId)
-        }
-
         runJournal.log({
-          type: "session.deleted",
+          type: "state.saved",
           timestamp: Date.now(),
-          archived: true,
+          success: true,
         })
       }
     },
@@ -253,25 +292,75 @@ export function createHooks(args: {
   const toolTrackingHook = isHookEnabled("tool-tracking")
     ? safeCreateHook(
         () =>
-          createToolTrackingHook(getAuditState, ({ tool, findingsCount }) => {
-            const currentState = getAuditState()
-            if (currentState) {
-              debouncedSave.save(currentState)
-            }
-
-            runJournal.log({
-              type: "tool.executed",
-              tool,
-              timestamp: Date.now(),
-              findingsCount,
-            })
-          }),
+          createToolTrackingHook(
+            getAuditState,
+            ({ tool, findingsCount }) => {
+              const currentState = getAuditState()
+              if (currentState) {
+                debouncedSave.save(currentState)
+              }
+
+              runJournal.log({
+                type: "tool.executed",
+                tool,
+                timestamp: Date.now(),
+                findingsCount,
+              })
+            },
+            {
+              getEventSink: () => currentEventSink,
+              getSessionId: () => currentOpencodeSessionId,
+            },
+          ),
         "tool-tracking",
       )
     : undefined
 
   const safeEventHook = isHookEnabled("event")
-    ? safeCreateHook(() => eventHook, "event")
+    ? safeCreateHook(
+        () => async (input: Parameters<typeof eventHook>[0]) => {
+          const isSessionDeleted = input.event.type === "session.deleted"
+          const finalizationBeforeDelete = isSessionDeleted ? getLastFinalizationResult() : null
+
+          try {
+            await eventHook(input)
+          } finally {
+            if (isSessionDeleted) {
+              const finalizationResult = getLastFinalizationResult()
+              const hasNewFinalization =
+                finalizationResult !== null && finalizationResult !== finalizationBeforeDelete
+
+              if (hasNewFinalization && finalizationResult.runId.length > 0) {
+                try {
+                  await materializeFindings(finalizationResult.runId, projectDir)
+                } catch (error) {
+                  logger.warn(
+                    `Failed to materialize findings artifact for run ${finalizationResult.runId}: ${error instanceof Error ? error.message : String(error)}`,
+                  )
+                }
+              }
+
+              await auditStateManager.archive()
+
+              const deletedSessionId = input.event.sessionId
+              if (deletedSessionId) {
+                agentTracker.clearSession(deletedSessionId)
+              }
+
+              runJournal.log({
+                type: "session.deleted",
+                timestamp: Date.now(),
+                archived: true,
+                finalizationPassed: finalizationResult?.invariantsPassed ?? null,
+              })
+
+              currentEventSink = null
+              currentOpencodeSessionId = ""
+            }
+          }
+        },
+        "event",
+      )
     : undefined
 
   return {

package/src/features/audit-enforcer/audit-enforcer.ts

@@ -11,6 +11,24 @@ const PHASE_ORDER: AuditPhase[] = [
   "complete",
 ]
 
+const REPORTING_PHASES: AuditPhase[] = ["reporting", "complete"]
+
+
+const KEY_TOOL_FAMILIES: Array<{ family: string; prefixes: string[] }> = [
+  { family: "slither", prefixes: ["argus_slither_analyze", "slither"] },
+  { family: "forge_test", prefixes: ["argus_forge_test", "forge_test"] },
+  { family: "forge_fuzz", prefixes: ["argus_forge_fuzz", "forge_fuzz"] },
+  { family: "forge_coverage", prefixes: ["argus_forge_coverage", "forge_coverage"] },
+]
+
+function getMissingToolFamilies(auditState: AuditState): string[] {
+  const executedTools = auditState.toolsExecuted.map((t) => t.tool)
+  return KEY_TOOL_FAMILIES.filter(
+    ({ prefixes }) =>
+      !executedTools.some((tool) => prefixes.some((prefix) => tool.startsWith(prefix))),
+  ).map(({ family }) => family)
+}
+
 function getNextPhase(current: AuditPhase): AuditPhase | null {
   const idx = PHASE_ORDER.indexOf(current)
   if (idx === -1 || idx >= PHASE_ORDER.length - 1) return null
@@ -25,10 +43,21 @@ export function createAuditEnforcer() {
     const nextPhase = getNextPhase(auditState.currentPhase)
     if (!nextPhase) return null
 
-    return [
+    const parts: string[] = [
       `[Argus Audit Enforcer] Audit in progress — current phase: ${auditState.currentPhase}.`,
       `Next phase: ${nextPhase}. Do not stop until audit is complete.`,
       `Progress: ${auditState.findings.length} findings, ${auditState.contractsReviewed.length} contracts reviewed.`,
-    ].join(" ")
+    ]
+
+    if (REPORTING_PHASES.includes(auditState.currentPhase)) {
+      const missing = getMissingToolFamilies(auditState)
+      if (missing.length > 0) {
+        parts.push(
+          `\u26a0\ufe0f Tool coverage incomplete: ${missing.join(", ")} have not been executed. Do not proceed to report generation until required tools are complete.`,
+        )
+      }
+    }
+
+    return parts.join(" ")
   }
 }

package/src/features/migration/index.ts

@@ -0,0 +1,14 @@
+export {
+  adaptLegacyFindings,
+  adaptLegacyStateToReportInput,
+  getMigrationMode,
+  type MigrationMode,
+  validateStrictCompatibility,
+} from "./migration-adapter"
+
+export {
+  computeParityMetrics,
+  formatParityReport,
+  type ParityMetrics,
+  type SeverityDistribution,
+} from "./parity-telemetry"

package/src/features/migration/migration-adapter.ts

@@ -0,0 +1,151 @@
+import {
+  createDropDiagnosticsCollector,
+  type DropDiagnosticsCollector,
+} from "../../shared/drop-diagnostics"
+import { normalizeLegacyFindingsArray, normalizeToCanonicalFinding } from "../../state/adapters"
+import type { CanonicalFinding, ReportInput } from "../../state/schemas"
+import { SCHEMA_VERSION } from "../../state/schemas"
+import type { AuditState, Finding } from "../../state/types"
+
+export type MigrationMode = "legacy" | "dual" | "strict"
+
+/**
+ * Returns the active migration mode from config, defaulting to "legacy".
+ */
+export function getMigrationMode(config: { migration?: { mode?: MigrationMode } }): MigrationMode {
+  return config.migration?.mode ?? "legacy"
+}
+
+/**
+ * Adapts a legacy `AuditState` into canonical `CanonicalFinding[]`.
+ *
+ * In legacy mode: returns the raw findings as-is (backward compatible).
+ * In dual mode: normalizes findings to canonical AND returns both.
+ * In strict mode: normalizes to canonical, rejects payloads missing required canonical fields.
+ */
+export function adaptLegacyFindings(
+  state: AuditState,
+  mode: MigrationMode,
+  runId: string,
+): {
+  legacyFindings: Finding[]
+  canonicalFindings: CanonicalFinding[]
+  diagnostics: ReturnType<DropDiagnosticsCollector["getDiagnostics"]>
+} {
+  const legacyFindings = state.findings
+
+  if (mode === "legacy") {
+    return {
+      legacyFindings,
+      canonicalFindings: [],
+      diagnostics: [],
+    }
+  }
+
+  const policy = mode === "strict" ? "strict-fail" : "warn"
+  const diag = createDropDiagnosticsCollector(policy, "migration-adapter")
+
+  const { findings: canonicalFindings, diagnostics: adapterDiags } = normalizeLegacyFindingsArray(
+    legacyFindings as unknown as unknown[],
+    runId,
+  )
+
+  for (const d of adapterDiags) {
+    if (d.level === "error") {
+      diag.error(d.code, d.message, d.field)
+    } else {
+      diag.warn(d.code, d.message, d.field)
+    }
+  }
+
+  // In strict mode, validate that all legacy findings survived normalization
+  if (mode === "strict" && canonicalFindings.length < legacyFindings.length) {
+    const dropped = legacyFindings.length - canonicalFindings.length
+    diag.error(
+      "STRICT_FINDINGS_DROPPED",
+      `${dropped} legacy finding(s) could not be normalized to canonical format`,
+    )
+  }
+
+  // Throws DropDiagnosticsError in strict mode if errors exist
+  diag.throwIfStrict()
+
+  return {
+    legacyFindings,
+    canonicalFindings,
+    diagnostics: diag.getDiagnostics(),
+  }
+}
+
+/**
+ * Adapts a legacy `AuditState` into a canonical `ReportInput`.
+ *
+ * Maps legacy AuditState fields to the canonical ReportInput contract.
+ */
+export function adaptLegacyStateToReportInput(
+  state: AuditState,
+  mode: MigrationMode,
+  runId: string,
+): {
+  reportInput: ReportInput
+  diagnostics: ReturnType<DropDiagnosticsCollector["getDiagnostics"]>
+} {
+  const { canonicalFindings, diagnostics } = adaptLegacyFindings(
+    state,
+    mode === "legacy" ? "dual" : mode,
+    runId,
+  )
+
+  const reportInput: ReportInput = {
+    run_id: runId,
+    seq: 0,
+    session_id: state.sessionId,
+    tool_call_id: "",
+    source: "migration-adapter",
+    schema_version: SCHEMA_VERSION,
+    projectDir: state.projectDir,
+    findings: canonicalFindings,
+    toolsExecuted: state.toolsExecuted.map((t) => ({
+      ...t,
+      run_id: runId,
+      schema_version: SCHEMA_VERSION,
+    })),
+    scope: state.scope,
+    soloditResults: state.soloditResults,
+    fuzzCounterexamples: state.fuzzCounterexamples,
+    coverageReport: state.coverageReport,
+    gasHotspots: state.gasHotspots,
+    proxyContracts: state.proxyContracts,
+  }
+
+  return { reportInput, diagnostics }
+}
+
+/**
+ * Validates that a legacy AuditState is compatible with strict mode.
+ * Returns true if ALL findings can be normalized without errors.
+ */
+export function validateStrictCompatibility(
+  state: AuditState,
+  runId: string,
+): { compatible: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  for (const [index, finding] of state.findings.entries()) {
+    const result = normalizeToCanonicalFinding(
+      finding as unknown as Record<string, unknown>,
+      runId,
+      index + 1,
+    )
+    const hasErrors = result.diagnostics.some((d) => d.level === "error")
+    if (hasErrors) {
+      errors.push(
+        ...result.diagnostics
+          .filter((d) => d.level === "error")
+          .map((d) => `[finding:${index}] ${d.message}`),
+      )
+    }
+  }
+
+  return { compatible: errors.length === 0, errors }
+}