fusion/docs/research/naming-decision-2026-05.md

Naming Decision Record: Research vs Experiment Session (2026-05)

Date: 2026-05-13
Task: FN-4223

Context

Fusion currently ships a research subsystem that runs a provider-driven search → fetch → synthesize pipeline and stores cited findings. The FN-4136 audit confirms this is not the same product shape as upstream pi-autoresearch, which is an autonomous try-measure-keep-revert experiment loop.

The audit identified false-friend naming risks that can cause users to over-assume parity: research run (vs upstream experiment), confidence (Fusion synthesis-emitted score vs upstream MAD-style statistical confidence), and iteration-like wording (maxSources/maxSynthesisRounds vs upstream maxIterations).

Options considered

(a) Split products entirely by renaming current research subsystem

Rename current research_* naming to something like cited-research/web-research, reserving research for upstream-style experiments. This would reduce ambiguity but creates broad breaking churn across tools, docs, APIs, and storage naming.

(b) Keep current names and force upstream-parity work to avoid “research”

Preserve existing research_* names exactly and force the new domain to use strictly experiment-only vocabulary without any overlap. This avoids breaking existing users but risks making the parity domain feel secondary or awkwardly detached from the broader product narrative.

(c) Hybrid: keep current research names, add parallel experiment-session domain, disambiguate copy

Retain research_* for cited-search/synthesis runs, land a first-class experiment_session_* domain for upstream parity, and explicitly disambiguate names in docs/UI/JSDoc. This avoids breakage while giving both products explicit, durable vocabulary.

Decision

We choose Option (c) hybrid.

Rationale:

1. FN-4218 already defines the parallel domain as experiment_session / ExperimentSession, which aligns with a two-domain model.
2. Renaming existing fn_research_* tools or research_runs storage would be a breaking change for the published @runfusion/fusion interface and the SQLite migration ladder.
3. The two domains solve different problems and both should remain first-class: cited information synthesis vs autonomous benchmarked experimentation.

Contracts

Term	Meaning / scope
Research run	A cited-search/synthesis run. Backed by research_runs, ResearchRun, fn_research_* tools, /api/research/*, ResearchView, and fn research.
Experiment session	An upstream-pi-autoresearch-style try-measure-keep-revert session. Backed by experiment_sessions / ExperimentSession (FN-4218) and future experiment tools/routes/UI.
Confidence (research)	Synthesis-emitted 0–1 score from the LLM synthesis provider. Not a statistical MAD confidence score. If experiment sessions add metric confidence, use a distinct field name (for example madConfidence or metricConfidence).
Iterations	Research run bounds are maxSources and maxSynthesisRounds (fan-out within one run). Upstream-style maxIterations belongs to experiment sessions and is a separate concept.

Non-goals

This task does not rename or deprecate any of the following:

• ResearchRun
• research_runs
• fn_research_*
• /api/research/*
• ResearchView
• confidence field

No behavior changes are included.

Follow-ups

• FN-4218/FN-4219/FN-4221/FN-4222 remain the execution track for experiment-session capabilities.
• Experiment-session confidence semantics must use a distinct metric-confidence field name (for example madConfidence/metricConfidence) instead of overloading research confidence.

References

• docs/research/pi-autoresearch-audit-2026-05.md (FN-4136)
• docs/research/pi-autoresearch-analysis.md (FN-2990 historical spike)
• FN-4218, FN-4219, FN-4221, FN-4222