docs(runtime): define ActionTrail replay requirements

docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md

@@ -264,7 +264,75 @@ Current product expectations:
 
 ---
 
-## 12. Acceptance Criteria
+## 12. ActionTrail Replay Requirements
+
+ActionTrail replay is not required to reproduce every UI pixel of a product runtime.
+For the ecosystem roadmap, replay means reconstructing the execution narrative with enough fidelity
+to answer:
+
+1. what was requested
+2. what ran
+3. what approvals or pauses happened
+4. what artifacts or memories were produced
+5. why the final state was reached
+
+Minimum replay evidence for a run:
+
+1. stable identity
+   - `sessionId`
+   - `runId`
+   - `productId`
+   - `userId`
+2. execution timing
+   - `startedAt`
+   - `completedAt` when available
+   - checkpoint timestamps when resumable
+3. causal chain
+   - `correlationId`
+   - `causationId`
+   - `parentEventId`
+   - canonical event IDs on audit/action records when available
+4. control-flow state changes
+   - queued
+   - running
+   - paused
+   - waiting-approval
+   - completed / failed / cancelled
+5. human intervention evidence
+   - approval checkpoints
+   - approval decisions
+   - actor identity for approvals or overrides
+6. output evidence
+   - `artifactRefs`
+   - `memoryRefs`
+   - relevant task and todo state at the end of the run
+
+Required behaviors:
+
+1. products must preserve runtime action logs or equivalent audit records long enough for replay and
+   review
+2. products may keep private implementation details, but they must emit enough canonical metadata to
+   reconstruct the run narrative externally
+3. replay consumers should trust canonical event IDs and action-log IDs over inferred timestamps
+4. replay should tolerate partial fidelity
+   - if UI frames or low-level desktop events are unavailable, ActionTrail should still be able to
+     render a narrative replay from runtime actions, approvals, checkpoints, and artifacts
+5. replay views must clearly distinguish between:
+   - observed canonical events
+   - inferred transitions derived from checkpoints or final state
+
+Current product expectations:
+
+- Cowork
+  - Rust audit records plus canonical `event_id` values are the primary replay anchor
+  - checkpoint/resume should explain why a run paused, resumed, or required approval
+- FlowMonk
+  - scheduled entries, confirmations, and projected action logs are the primary replay anchor
+  - replay should make it obvious when an automation was queued versus actively running
+
+---
+
+## 13. Acceptance Criteria
 
 1. A dispatched Cowork task can be resumed after interruption without losing audit continuity.
 2. A FlowMonk execution can emit task/todo state using the same contract.
@@ -274,14 +342,14 @@ Current product expectations:
 
 ---
 
-## 13. Implementation Checklist
+## 14. Implementation Checklist
 
 - [x] finalize entity list and minimum required fields
 - [x] define run vs session vs task boundaries
 - [x] define checkpoint/resume semantics
 - [x] define dispatch payload contract
 - [x] define action-log hook points
-- [ ] define ActionTrail replay requirements
+- [x] define ActionTrail replay requirements
 - [ ] define first conforming implementation plan for Cowork and FlowMonk
 
 Commits:

docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md

@@ -272,7 +272,7 @@ These should be resolved before claiming the ecosystem docs are fully implementa
 
 - Cowork: add `AgentTodo` direct projection once the product exposes first-class todo entities.
 - FlowMonk: replace the current derived approval/todo projections once the product exposes first-class approval/todo primitives.
-- Shared runtime: define ActionTrail replay requirements.
+- Shared runtime: define the first conforming implementation plan for Cowork and FlowMonk beyond the current baseline projections.
 
 ### 6.2 Explicit Blockers And Questions
 

docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md

@@ -112,7 +112,7 @@ Observed baseline:
 
 - Cowork now emits shared runtime projections from cowork-service, preserves Rust-side canonical event IDs on approval/audit records, and still lacks a first-class native `AgentTodo` product source behind the current task-backed projection.
 - FlowMonk now emits direct runtime projections for planning sessions, tasks, todos, runs, approvals, and action logs, but it still lacks distinct native checklist and approval entities behind those projections.
-- ActionTrail replay requirements still need to be formalized in the contract.
+- the first conforming implementation plan still needs to be made explicit for Cowork and FlowMonk beyond the current baseline projections.
 
 ## 8. Explicit Blockers And Questions