diff --git a/docs/research/naming-decision-2026-05.md b/docs/research/naming-decision-2026-05.md new file mode 100644 index 000000000..46cf8d065 --- /dev/null +++ b/docs/research/naming-decision-2026-05.md @@ -0,0 +1,67 @@ +# 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