> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Execution Replay & Time Travel — Integration Contract

> Feature ID: FW-56 Spec: specs/fw/specs/FW-56-workflow-execution-replay-time-travel.md Status: 📝 Planned Owner Core: FW (Forms & Workflow)

**Feature ID:** FW-56\
**Spec:** `specs/fw/specs/FW-56-workflow-execution-replay-time-travel.md`\
**Status:** 📝 Planned\
**Owner Core:** FW (Forms & Workflow)

***

## Purpose

Defines integration contracts for **read-only historical replay** of workflow executions using FW-48 step checkpoints, **what-if** forks into FW-24 sandbox executions, **comparison** of two runs of the same workflow, and **single-execution export** (JSON/PDF) aligned with FW-43 retention posture.

***

## Integration Matrix

| Dependency                 | Type           | Direction | Contract Summary                                                                    |
| -------------------------- | -------------- | --------- | ----------------------------------------------------------------------------------- |
| FW-22 Execution Monitoring | Intra-core UI  | FW → FW   | Execution detail shell, list entry points; replay mode/tab; replaces stub replay    |
| FW-48 Step Checkpointing   | Data           | FW → FW   | `fw_execution_steps` ordered timeline, `input_data`/`output_data`, gateway metadata |
| FW-24 Sandbox              | Runtime / Data | FW → FW   | `fw_sandbox_executions` extended with `what_if` + fork columns; `sandbox-execute`   |
| FW-06 Workflow Builder     | UI             | FW → FW   | Canvas read + node highlight by `node_id`                                           |
| FW-18 Variables            | Domain         | FW → FW   | Variable naming and merge semantics at fork                                         |
| FW-43 Audit Trail          | Compliance     | FW → FW   | Export/redaction alignment; retention messaging                                     |
| PF-04 Audit                | Platform       | FW → PF   | Optional `logAuditEvent` for replay open / export                                   |
| PF-46 Data Retention       | Platform       | FW → PF   | Block export when underlying rows purged                                            |

***

## Data Contracts

### Replay bundle query

**Inputs:** `execution_id`, `organization_id`\
**Reads:**

* `fw_workflow_executions` (single row, tenant filter)
* `fw_execution_steps` — `SELECT * WHERE execution_id = ? AND organization_id = ? ORDER BY step_index ASC, attempt_number ASC`
* Optional `fw_execution_logs` — filter `execution_id`, ascending time

**Output (logical):**

* `execution`, `steps[]`, `logs[]` for UI layers

### What-if fork write

**Table:** `fw_sandbox_executions`\
**Required fields (minimum):**

* `organization_id`, `rule_id` (from source execution), `execution_type = 'what_if'`
* `forked_from_execution_id`, `forked_from_step_id`
* `modified_variables` (JSON object)
* `input_data` — **deterministic merge (spec FR-3.4):** shallow copy `fw_workflow_executions.variables`; for each `fw_execution_steps` row in order through the fork step (inclusive), shallow-merge that step’s `output_data` into the accumulator; then shallow-merge `modified_variables`; result = `input_data` for the sandbox row.

**Invokes:** `sandbox-execute` edge function (or equivalent RPC) with sandbox row id after insert.

### Comparison query

**Inputs:** `execution_id_a`, `execution_id_b`, `organization_id`\
**Precondition:** Both rows share the same `rule_id` (client + server validation).\
**Reads:** Two step lists; **align** by `step_index` for divergence detection.

### Export

**MVP:** Client-assembled JSON download from replay bundle; PDF via jsPDF.\
**Redaction:** Sanitize all `error_message` fields via `sanitizeErrorMessage` before serialization; variable bodies match on-screen replay (spec FR-5.3).\
**No new storage bucket required** unless product later moves to signed URLs (defer).

### Workflow definition for canvas

* If `fw_workflow_executions.workflow_version` is set: load `fw_workflow_definitions` where `(rule_id, version)` matches.
* If null: load the row with **maximum `version`** for `rule_id` + org; show UI banner that layout may differ from run-time graph (spec FR-2.1).

***

## API / Edge Contracts

| Endpoint / path   | Role                                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `sandbox-execute` | Existing FW-24 executor; extended payload may include fork metadata (verify function accepts `execution_type` / fork ids) |
| Supabase REST/RPC | Reads use standard client with RLS; inserts to `fw_sandbox_executions` respect `fw_has_sandbox_access`                    |

***

## Security & Tenancy

* All queries: `.eq('organization_id', orgId)` in application code in addition to RLS.
* Permission: `fw.workflow-executions.replay` for replay UI, compare, what-if launch, single-execution export (see spec).
* No PHI in audit payloads — identifiers only.

***

## Consumer Notes

* **FW-22:** Remove or bypass client-only replay simulation in `ExecutionDetailDialog.handleReplay` once FW-56 ships.
* **FW-48:** If step retention deletes rows, replay must show empty state with explanation (link to FW settings / retention doc).

***

## Revision History

| Date       | Change                                                                                          |
| ---------- | ----------------------------------------------------------------------------------------------- |
| 2026-03-22 | Initial integration doc from spec workflow                                                      |
| 2026-03-22 | Resolved: fork merge (FR-3.4), export redaction (FR-5.3), definition version selection (FR-2.1) |