fusion/docs/research/research-hardening-preflight.md

Research Hardening Preflight Baseline (FN-2999)

Date: 2026-05-04
Task: FN-3266

Scope and intent

This document is the verified baseline for FN-2999 hardening work. It reflects shipped behavior in-repo and explicitly calls out drift from older assumptions.

1) Verified module map (Research vs Insights)

Core (@fusion/core)

• packages/core/src/research-types.ts
  • Canonical research statuses/types/lifecycle contracts.
• packages/core/src/research-store.ts
  • Persistence-backed run lifecycle, transitions, cancellation request, retry creation, events/sources/results/exports operations.
• packages/core/src/research-settings.ts
  • Feature enablement and resolved runtime limits/provider settings.
• packages/core/src/db.ts
  • Research tables: research_runs, research_run_events, research_exports.

Dashboard API/UI (@fusion/dashboard)

• packages/dashboard/src/research-routes.ts
  • Research API endpoints (run CRUD + cancel/retry + results/sources/events + exports + finding-to-task actions).
• packages/dashboard/src/routes/register-integrated-routers.ts
  • Mounts router at /api/research via router.use("/research", createResearchRouter(store)).
• packages/dashboard/app/hooks/useResearch.ts
  • Dashboard hook consuming /api/research/* and run lifecycle updates.
• packages/dashboard/app/components/ResearchView.tsx
  • Standalone Research view, run controls, result display, finding task actions.

Engine (@fusion/engine)

• packages/engine/src/research-orchestrator.ts
  • Phase execution (planning/searching/fetching/synthesizing/finalizing), cancellation, retry handoff, status/event writes.
• packages/engine/src/research-step-runner.ts
  • Provider adapters with timeout + abort handling and error classification.

CLI + extension (@runfusion/fusion)

• packages/cli/src/commands/research.ts
  • create, list, show, export, cancel, retry commands.
• packages/cli/src/extension.ts
  • Research tools: fn_research_run, fn_research_list, fn_research_get, fn_research_cancel, fn_research_retry.

Boundary with Insights (separate subsystem)

• Insights files/routes/stores remain separate (insight-store, insights-routes, project_insights* tables).
• Research is not a wrapper around Insights and does not share run tables.

2) Renamed-path drift and stale assumptions

• Older wording referencing packages/dashboard/src/routes/register-research-routes.ts is stale.
• Actual implementation is:
  • route file: packages/dashboard/src/research-routes.ts
  • mount file: packages/dashboard/src/routes/register-integrated-routers.ts
  • mount path: /api/research

3) Lifecycle/status contract as shipped

Canonical ResearchRunStatus values in research-types.ts:

• queued
• running
• cancelling
• retry_waiting
• completed
• failed
• cancelled
• timed_out
• retry_exhausted

Important mismatch to older baseline text

Older baseline language (pending | running | completed | failed | cancelled) is obsolete. pending is normalized to queued for compatibility in store code, but not a primary status in current contracts.

4) Cancel/retry behavior (API + store + orchestrator)

Dashboard route behavior (research-routes.ts)

• POST /runs/:id/cancel
  • Rejects terminal statuses (completed, failed, cancelled, timed_out, retry_exhausted) with 409 INVALID_TRANSITION.
  • Otherwise calls ResearchStore.requestCancellation() → run moves to cancelling.
• POST /runs/:id/retry
  • Delegates to ResearchStore.createRetryRun().
  • Maps retry exhaustion to 409 RETRY_EXHAUSTED, non-retryable failures to 409 NON_RETRYABLE_PROVIDER_ERROR, invalid state to 409 INVALID_TRANSITION.

Store behavior (research-store.ts)

• requestCancellation()
  • Non-terminal runs transition to cancelling, append cancel_requested lifecycle event.
• createRetryRun()
  • Only from failed/timed_out.
  • Enforces retryable + max-attempt budget; can set source run to retry_exhausted and throw not_retryable.
  • Creates new run and sets new run status to retry_waiting with retry_scheduled event.

Orchestrator behavior (research-orchestrator.ts)

• cancelRun(runId) always calls store.requestCancellation(runId) first.
• If run is active in orchestrator activeRuns, abort controller is triggered and final state transitions through cancellation handling.
• If run is not active, orchestrator directly sets status cancelled.
• Practical limitation: orchestrator-side graceful cancellation logic only applies to runs currently tracked in activeRuns.

5) Persistence/storage model (verified)

Tables (db.ts)

• research_runs
  • Primary run row including JSON columns: providerConfig, sources, events, results, tokenUsage, tags, metadata, lifecycle.
• research_run_events
  • Append-only lifecycle/event stream (seq, type, message, optional status/classification/metadata).
• research_exports
  • Export artifacts linked by runId.

Read/write shape (research-store.ts)

• Run row stores denormalized snapshots (sources, events, results) in research_runs JSON fields.
• Lifecycle events are also persisted separately in research_run_events (durable ordered log).
• Results/citations/findings are stored in research_runs.results JSON.

6) Provider execution path and abort semantics

research-step-runner.ts:

• runSourceQuery → provider search(query, options, signal)
• runContentFetch → provider fetchContent(url, options, signal)
• runSynthesis → configured synthesis runner with model settings + signal

All step calls are wrapped by withTimeout(...):

• timeout classification: ResearchStepTimeoutError (retryable: true)
• abort classification: ResearchStepAbortError (retryable: false)
• provider failures: provider_error (retryable: true)

Abort propagation uses AbortSignal listeners and races promise vs timeout vs abort.

7) API shape summary (/api/research)

Key endpoints:

• GET /runs, POST /runs, GET /runs/:id, PATCH /runs/:id, DELETE /runs/:id
• POST /runs/:id/cancel, POST /runs/:id/retry, PATCH /runs/:id/status
• POST /runs/:id/events, POST /runs/:id/sources, PATCH /runs/:id/sources/:sourceId, PUT /runs/:id/results
• GET /runs/:id/export, POST /runs/:id/exports, GET /runs/:id/exports, GET /exports/:exportId
• GET /stats, GET /search
• POST /runs/:runId/findings/:findingId/task
• POST /runs/:runId/findings/:findingId/tasks/:taskId/enrich

8) Hardening pressure points recorded (no fixes in this task)

1. Status drift risk

   • Some surfaces (notably tool parameter enums in extension) still expose legacy compact status sets while core status domain is broader.

2. Orchestrator cancel scope nuance

   • Full graceful cancel path is only available when run is in activeRuns; non-active cancellation takes direct status path.

3. Dual event storage model complexity

   • research_runs.events JSON snapshot and research_run_events append-only log coexist; hardening should preserve consistency guarantees.

4. Export surface asymmetry

   • Route export endpoint advertises markdown/json/html behavior while core export type includes pdf; CLI command accepts pdf format but markdown renderer fallback behavior should remain explicitly documented/validated.

9) FN-3292 boundary stress-test confirmations

• Provider ordering assumptions were tightened: content fetch selection can now use source-level provider metadata (providerType) and falls back only when that provider is unavailable.
• Orchestrator/provider seam was validated with behavior-first tests:
  • fallback from failed primary provider to a later provider,
  • partial fetch failure with successful completion when at least one source is fetched,
  • real ResearchStore persistence verification at orchestrator level (sources/events/results/lifecycle events persisted end-to-end).
• Boundary guidance for future work:
  • keep retryability/lifecycle ownership in ResearchStore transitions,
  • keep error classification in ResearchStepRunner,
  • keep sequencing and policy decisions in ResearchOrchestrator.

10) FN-3370 refinement scope correction

• FN-3370 replaces FN-3015's stale insights-backed child scope with the landed research subsystem surfaces in this document (core ResearchStore + dashboard /api/research + engine orchestrator lifecycle persistence).
• Regression coverage work should stay bounded to shipped lifecycle/status/export/task-integration contracts and use follow-up tasks for any unshipped behavior instead of feature expansion.

11) Dashboard regression coverage status (FN-3368 refinement)

• Dashboard interaction tests are anchored to landed standalone research surfaces (ResearchView, ResearchTaskActionModal, useResearch, App research route wiring).
• Route regression tests explicitly cover finding-to-task create/enrich provenance metadata, task-document writes, duplicate-attachment skip behavior, archived/missing target guards, and payload validation.
• There is no placeholder/optional assumption that research dashboard files or /api/research routes are absent.

12) FN-3369/FN-3599 verification lock note

• Extension research tool contracts are now explicitly locked for missing-run errors and completed-run structured details (summary, findings, citations) across fn_research_get / fn_research_cancel / fn_research_retry behavior.
• Server-level /api/research integration assertions are locked through createServer coverage for cancel/retry success paths, structured 400/404/409 envelopes, and export response contract checks.
• CLI routing + docs alignment are locked to shipped behavior, including intentional CLI/core vs server export-format asymmetry documentation (no forced unification).

13) Validation references used for this baseline

• packages/dashboard/src/__tests__/research-routes.test.ts
• packages/core/src/__tests__/research-store.test.ts
• packages/engine/src/__tests__/research-orchestrator.test.ts
• packages/cli/src/commands/__tests__/research.test.ts

These tests were used as behavioral evidence while preparing this baseline.