fusion/docs/research/experiment-session-model.md

Experiment Session Domain Model

Motivation

pi-autoresearch parity requires a persistent session model for iterative experiment loops (configure → run → evaluate keep/discard → finalize). Existing research_runs is query/synthesis-oriented and cannot represent session segments, metric direction, or append-only experiment records.

Entity Model

experiment_sessions (1) ──< (many) experiment_session_records

Session
  ├─ metric definition (name/unit/direction)
  ├─ currentSegment
  ├─ baselineRunId / bestRunId
  └─ keptRunIds[]

Record (append-only by seq per session)
  ├─ config (segment headers)
  ├─ run (metric outcomes + keep/discard/checks_failed/etc.)
  ├─ hook (before/after hook execution)
  └─ finalize (kept/discarded summary + branch metadata)

SQLite Schema

experiment_sessions

• id TEXT PK
• name TEXT NOT NULL
• projectId TEXT
• status TEXT NOT NULL (active|finalizing|finalized|archived)
• metric TEXT NOT NULL (JSON)
• currentSegment INTEGER NOT NULL DEFAULT 1
• maxIterations INTEGER
• workingDir TEXT
• baselineRunId TEXT
• bestRunId TEXT
• keptRunIds TEXT NOT NULL DEFAULT '[]'
• tags TEXT NOT NULL DEFAULT '[]'
• metadata TEXT
• createdAt TEXT NOT NULL
• updatedAt TEXT NOT NULL
• finalizedAt TEXT

Indexes: status, projectId, createdAt.

experiment_session_records

• id TEXT PK
• sessionId TEXT NOT NULL FK → experiment_sessions(id) ON DELETE CASCADE
• segment INTEGER NOT NULL
• seq INTEGER NOT NULL
• type TEXT NOT NULL (config|run|hook|finalize)
• payload TEXT NOT NULL (JSON)
• createdAt TEXT NOT NULL

Constraints/indexes:

• UNIQUE(sessionId, seq)
• (sessionId, segment, seq) index
• (sessionId, type) index

Status State Machine

active → finalizing → finalized → archived

Rules:

• Records are append-only.
• seq is allocated monotonically per session inside a transaction.
• Appending is rejected for finalized and archived sessions.
• Transitioning to finalized sets finalizedAt if unset.

Upstream Mapping

Upstream concept (pi-autoresearch)	Fusion model
ExperimentState	ExperimentSession
Metric (name/unit/direction)	ExperimentMetricDefinition + experiment_sessions.metric
Segment reset via config row	startNewSegment() + config record
Iteration result	run record payload
Hook log entry	hook record payload
Keep/discard ledger	run.status + session keptRunIds[]
Baseline/current best pointers	baselineRunId, bestRunId
Finalization summary	finalize record payload + session status/finalizedAt

Store API Notes

• recordKept(sessionId, runRecordId) is idempotent and only appends missing run IDs.
• updateRecordPayload(recordId, patch) applies additive payload patches for existing records (used by executor to backfill run commit SHA after keep commits).

Follow-ups

• FN-4219: executor/orchestrator loop (init/run/log) and runtime integration.
• FN-4221: unify dashboard/CLI/extension/engine surfaces with one execution contract.
• FN-4222: finalize workflow and branch-splitting parity.