034528cee4
Implements the `experiment-finalize` CLI command (FN-4222) and its companion dashboard API route, wiring the feature through the pi extension as a new callable tool. Includes the command implementation, extension tooling, API integration, and corresponding test coverage. Fusion-Task-Id: FN-4222
57 lines
1.8 KiB
Markdown
57 lines
1.8 KiB
Markdown
# Experiment Session Finalize Workflow
|
|
|
|
## Motivation
|
|
FN-4136 identified a gap versus upstream `autoresearch-finalize`: Fusion had no workflow to split kept experiment commits into reviewable branches from a shared merge-base.
|
|
|
|
## Plan model
|
|
Finalize builds groups of kept run records, each with ordered commits and a suggested branch name. Branch names default to:
|
|
|
|
`experiment/<session-id>/<slug>-<index>`
|
|
|
|
Override schema:
|
|
|
|
```json
|
|
{
|
|
"groups": [
|
|
{
|
|
"id": "segment:1",
|
|
"title": "Latency fixes",
|
|
"suggestedBranchName": "experiment/exp-1/latency-fixes-1",
|
|
"runRecordIds": ["RUN-2", "RUN-5"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Algorithm
|
|
1. Resolve merge-base from session baseline ref and integration branch.
|
|
2. Build default plan from kept runs.
|
|
3. Apply optional override and validate run IDs / branch uniqueness.
|
|
4. For each group: create branch at merge-base, checkout, cherry-pick commits in order.
|
|
5. Restore original ref.
|
|
6. Append `finalize` session record and move session to `finalized`.
|
|
7. On failure, rollback created branches and restore original ref; session remains `finalizing`.
|
|
|
|
## Error taxonomy
|
|
|
|
| Error code | CLI exit | HTTP status |
|
|
|---|---:|---:|
|
|
| `state_error` | 2 | 409 |
|
|
| `no_kept_runs` | 3 | 409 |
|
|
| `plan_error` | 4 | 400 |
|
|
| `merge_base_error` | 5 | 422 |
|
|
| `cherry_pick_conflict` | 6 | 422 |
|
|
| `branch_exists` | 7 | 409 |
|
|
| unknown/untyped | 1 | 500 |
|
|
|
|
## Recovery
|
|
If finalize fails after session status moves to `finalizing`:
|
|
1. Inspect and delete leftover branches (`git branch -D <name>`).
|
|
2. Restore session status manually via store update to `active`.
|
|
3. Re-run finalize (optionally with a plan override).
|
|
|
|
## Follow-ups
|
|
- FN-4221: dashboard finalize UI wiring.
|
|
- FN-4223: naming clarifications around research/experiment command surfaces.
|
|
- Upstream reference: `autoresearch-finalize` branch-split semantics.
|