root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(FN-3292): document research boundary contract

Browse Source 
Documents the research boundary contract in the architecture docs and research hardening preflight guide, updating architecture documentation and adding a new boundary definition file.

Fusion-Task-Id: FN-3292
This commit is contained in:
Fusion
2026-05-04 11:09:38 -07:00
committed by gsxdsm
parent 8483a5ffae
commit d2e9423f75
6 changed files with 180 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/architecture.md
View File

@@ -169,13 +169,18 @@ Concrete references:
### Research Runs
- `ResearchStore` (`research-store.ts`, `research-types.ts`, `research-settings.ts`) persists bounded research runs, sources/events, and exports
- Backed by `research_runs`, `research_exports`, and `research_run_events`
- Engine orchestration is implemented in `packages/engine/src/research-orchestrator.ts` + `research-step-runner.ts`
- Dashboard/API surface is implemented under `/api/research` (`packages/dashboard/src/research-routes.ts`) with `ResearchView.tsx` in the app
- CLI surface is implemented in `packages/cli/src/commands/research.ts` with six subcommands (create, list, show, export, cancel, retry)
- Agent tool surface is exposed via `packages/cli/src/extension.ts` (`fn_research_run`, `fn_research_list`, `fn_research_get`, `fn_research_cancel`, `fn_research_retry`)
- **Boundary note:** research and insights are parallel subsystems sharing host infrastructure, not one table/store family
- `ResearchStore` (`research-store.ts`, `research-types.ts`, `research-settings.ts`) persists bounded research runs, sources/events, exports, lifecycle metadata, and retry/cancel state transitions.
- Backed by `research_runs`, `research_exports`, and `research_run_events`.
- Engine orchestration is implemented in `packages/engine/src/research-orchestrator.ts` + `research-step-runner.ts`.
- Dashboard/API surface is implemented under `/api/research` (`packages/dashboard/src/research-routes.ts`) with `ResearchView.tsx` in the app.
- CLI surface is implemented in `packages/cli/src/commands/research.ts` with six subcommands (create, list, show, export, cancel, retry).
- Agent tool surface is exposed via `packages/cli/src/extension.ts` (`fn_research_run`, `fn_research_list`, `fn_research_get`, `fn_research_cancel`, `fn_research_retry`).
- **Boundary contract (FN-3292):**
- `ResearchStore` owns persistence and lifecycle writes (status transitions, lifecycle event log rows, sources/results snapshots).
- `ResearchStepRunner` owns provider I/O concerns only (provider selection, timeout/abort/provider-error classification, synthesis call execution); it does not read/write run state.
- `ResearchOrchestrator` owns sequencing and failure policy (phase progression, provider fallback, partial-step continuation, terminal status choice) and interacts with store only through public store methods.
- Provider substitution must remain data-driven: source metadata can carry provider identity, and fetching should resolve providers per source rather than relying on provider ordering.
- **Boundary note:** research and insights are parallel subsystems sharing host infrastructure, not one table/store family.
### Plugin System

14
docs/research/research-hardening-preflight.md
View File

@@ -147,7 +147,19 @@ Key endpoints:
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) Validation references used for this baseline
## 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) Validation references used for this baseline
- `packages/dashboard/src/__tests__/research-routes.test.ts`
- `packages/core/src/__tests__/research-store.test.ts`