invariants.md

Backend Invariants...

These invariants MUST hold for all backend operations.
Violation of any invariant is a critical bug.

Enforcement categories:

• [REPLAY] – Enforced during replay of events
• [EXEC] – Enforced at execution / event-emission time (replay may not be able to verify)

---

RUN INVARIANTS

1. Run IDs are UUID v4 strings, unique across all time

• [EXEC] RunID uniqueness is enforced at creation time
• No two runs share the same RunID

2. A Run exists in exactly one state at any time

• [EXEC] State transitions are enforced during execution
• Valid transitions:
  • pending → running → completed, or
  • pending → running → failed
• State transitions are monotonic (no going backwards)

3. A Run must have exactly one run.started event

• [REPLAY] Enforced during replay
• run.started must be the first event
• No events may exist before run.started
• Duplicate run.started events cause replay failure

4. A Run must have exactly one run.finished OR run.failed event

• [REPLAY] Enforced during replay
• Termination event must have the highest seq value
• No events may exist after termination
• Exactly one termination event must exist
• Duplicate termination events cause replay failure

5. A Run's steps must follow the fixed pipeline order if they execute

• [REPLAY] Enforced during replay
• Phase order: planner → executor → reviewer
• Steps may stop early on failure (see invariant #7)
• No steps may be out of order

6. A Run's workspace_root must be an absolute path

• [EXEC] Path validation enforced at execution time
• All file operations are restricted to workspace_root or subdirectories
• No file access outside workspace_root is permitted

7. A Run that fails during any phase does not execute subsequent phases

• [EXEC] Enforced during execution
• If planner fails, executor and reviewer do not run
• If executor fails, reviewer does not run

---

STEP INVARIANTS

8. Step IDs are UUID v4 strings, unique within a run

• [EXEC] Uniqueness enforced at creation time

9. A Step must have exactly one step.started event

• [REPLAY] Enforced during replay
• No duplicate step.started events for the same step_id
• Duplicate start events cause replay failure
• Start seq is tracked for error reporting

10. A Step must have exactly one step.finished OR step.failed event

• [REPLAY] Enforced during replay
• No subsequent events may reference the same step_id
• Incomplete steps cause replay failure

11. A Step must belong to exactly one Run

• [REPLAY] Enforced during replay
• Step.RunID must match a valid RunID

12. A Step must have exactly one Phase

• [EXEC] Phase is immutable for a step
• Valid phases: planner, executor, reviewer

13. A Step's agent_id must be valid for the step's phase

• [EXEC] Enforced before emitting step.started
• Planner phase → planner agent
• Executor phase → executor agent
• Reviewer phase → reviewer agent

---

TOOL CALL INVARIANTS

14. ToolCall IDs are UUID v4 strings, unique within a run

• [EXEC] Uniqueness enforced at creation time

15. A ToolCall must have exactly one tool.called event

• [REPLAY] Enforced during replay
• No duplicate tool.called events
• Duplicate start events cause replay failure
• Start seq is tracked for error reporting

16. A ToolCall must have exactly one tool.returned OR tool.failed event

• [REPLAY] Enforced during replay
• No subsequent events may reference the same tool_call_id
• Incomplete tool calls cause replay failure

17. A ToolCall must belong to exactly one Step

• [REPLAY] Enforced during replay
• ToolCall.StepID must match a valid StepID

18. A ToolCall's tool_name must be valid and registered

• [EXEC] Enforced before emitting tool.called
• Tool must exist in the registry
• Tool must be whitelisted for the step's agent

19. A ToolCall must respect permission tiers

• [EXEC] Enforced before emitting tool.called
• Agent.PermissionTier ≥ Tool.PermissionTier
• Permission check happens before execution

20. A ToolCall's input must validate against the InputSchema

• [EXEC] Enforced before emitting tool.called
• Invalid input → tool.failed (INVALID_INPUT)

21. A ToolCall's output must validate against the OutputSchema

• [EXEC] Enforced before emitting tool.returned
• Invalid output → tool.failed (INVALID_OUTPUT)

22. A ToolCall duration_ms must be ≥ 0

• [EXEC] Enforced when calculating duration

---

LLM CALL INVARIANTS

23. LLMCall IDs are UUID v4 strings, unique within a run

• [EXEC] Uniqueness enforced at creation time

24. An LLMCall must have exactly one llm.requested event

• [REPLAY] Enforced during replay
• No duplicate start events
• Start seq is tracked for error reporting

25. An LLMCall must have exactly one llm.responded event

• [REPLAY] Enforced during replay
• No subsequent events may reference the same llm_call_id
• Incomplete calls cause replay failure

26. An LLMCall must belong to exactly one Step

• [REPLAY] Enforced during replay
• LLMCall.StepID must match a valid StepID

---

ARTIFACT INVARIANTS

27. Artifact IDs are UUID v4 strings, unique within a run

• [EXEC] Uniqueness enforced at creation time

28. An Artifact must have exactly one artifact.created event

• [EXEC] Enforced at creation time

29. An Artifact must belong to exactly one Step

• [REPLAY] Enforced during replay

30. An Artifact must belong to exactly one Run

• [REPLAY] Enforced during replay

31. An Artifact's type must be one of:

• [EXEC] file, diff, text
• Type is immutable

32. An Artifact's checksum must be valid SHA256

• [EXEC] Calculated at creation time

33. An Artifact's size_bytes must be ≥ 0

• [EXEC] Calculated at creation time

34. File artifacts must have a valid path

• [EXEC] Enforced at creation time
• Absolute and within workspace_root
• No path traversal or escapes
• Path optional for diff and text

---

EVENT LOG INVARIANTS

35. Event log is append-only

• [EXEC] Events are never modified or deleted
• Written in seq order

36. Each event has a unique UUID v4 ID

• [EXEC] Enforced at creation time

37. Each event has a valid type

• [REPLAY] Valid types:
  • run.started, run.finished, run.failed
  • step.started, step.finished, step.failed
  • llm.requested, llm.responded
  • tool.called, tool.returned, tool.failed
  • artifact.created

38. Each event has a valid seq

• [REPLAY] Strictly increasing per run
• No duplicate seq values

39. Event payloads must match schemas

• [REPLAY] Invalid payloads are critical errors

40. Events are stored as JSONLines

• [EXEC] One JSON object per line
• Newline-terminated

41. Event log is replayable

• [REPLAY] Guaranteed by replay engine
• Entire RunView reconstructed from events

---

FILE SYSTEM INVARIANTS

42. File operations are restricted to workspace_root

• [EXEC] Enforced by file tools

43. File paths are normalized to absolute paths

• [EXEC] Relative paths resolved against workspace_root
• Path containment enforced

44. Arbitrary shell execution is forbidden

• [EXEC] No execute_shell tool (yet)
• Only allowlisted wrappers:
  • run_tests
  • run_build
  • run_lint

---

AGENT INVARIANTS

45. Agents are configured at startup

• [EXEC] Configuration is immutable
• Agents identified by ID

46. Agents have fixed tool whitelists

• [EXEC] Enforced before tool execution

47. Agents have fixed permission tiers

• [EXEC] Permission tiers are immutable

48. Uses exactly three agents (for now)

• [EXEC]
  • Planner (READ-only)
  • Executor (WRITE / EXECUTE)
  • Reviewer (READ-only)

---

MEMORY INVARIANTS

49. Memory store is isolated per run

• [EXEC] Namespaced by RunID
• No cross-run access

50. Memory store is ephemeral

• [EXEC] Lost on restart
• Not persisted (yet)
• Event log is the source of truth

51. Memory keys are strings

• [EXEC] Values are JSON-serializable

---

REPLAY INVARIANTS

52. Replay is deterministic

• [REPLAY] Based only on events sorted by seq

53. Replay validates invariants

• [REPLAY] Errors include:
  • seq
  • event type
  • short reason

54. Replay produces a complete RunView

• [REPLAY] Equivalent to the original run state