Turn struct

[andreasronge]

Summary

Create immutable Turn struct to capture each LLM interaction cycle.

Spec: message-history-optimization-requirements.md (Roadmap Issue #5)

Requirements

ARC-001: Turn struct fields

Turn struct with fields:

• number - turn sequence number (integer)
• raw_response - full LLM output including reasoning (string, always captured per ARC-010)
• program - parsed PTC-Lisp program (string or nil for failures)
• result - execution result (any term)
• prints - captured println output (list of strings)
• tool_calls - tool invocations made (list of %{name, args, result})
• memory - accumulated definitions (map)
• success? - whether turn succeeded (boolean)

ARC-002: Append-only turns list

Turns list is append-only (no mutation). Each turn is a snapshot of that cycle's execution.

ARC-010: raw_response always captured

raw_response captures full LLM output including reasoning. Always captured, no debug flag needed.

DBG-001: Full programs preserved

Full programs preserved in Step.turns. Each Turn contains complete execution data.

DBG-002: Turn contains complete execution data

Turn contains: number, raw_response, program, result, prints, tool_calls, memory, success?

Implementation

File to create

• lib/ptc_runner/turn.ex

Struct definition

defstruct [
  :number,
  :raw_response,
  :program,
  :result,
  :prints,
  :tool_calls,
  :memory,
  :success?
]

Constructor functions

Two smart constructors for creating turns:

@doc """
Create a successful turn.
"""
def success(number, raw_response, program, result, prints, tool_calls, memory)

@doc """
Create a failed turn.
"""
def failure(number, raw_response, program, error, prints, tool_calls, memory)

The success? field is set automatically:

• Turn.success/7 sets success?: true
• Turn.failure/7 sets success?: false

No update functions

The struct is immutable - no update/merge functions should be provided. If a turn needs modification, create a new one.

Files to modify

None - this is a standalone struct with no integration yet. Integration happens in:

• Step.trace → Step.turns migration (dual-write) #629 (Step.turns migration - dual-write)

Acceptance criteria

• Turn.success/7 constructor creates turn with success?: true
• Turn.failure/7 constructor creates turn with success?: false
• All 8 fields accessible via pattern matching and dot notation
• Struct is immutable (no update functions provided)
• Basic tests for both constructors
• Typespec defined for Turn struct

Blocked by

• feat: Enable prompt caching by moving dynamic content out of system prompt #603 (PRE-001) - Complete

Blocks

• Compression behaviour and normalize #619 (Compression behaviour and normalize)
• Step.trace → Step.turns migration (dual-write) #629 (Step.turns migration)

Automation State

Field	Value
Status	SUCCESS
PR	#636
Branch	claude/634-turn-struct
Attempts	1

Details: Implemented Turn struct with success/7 and failure/7 constructors. All tests passing, PR created.

[claude]

Issue Review: Turn struct

Summary: Well-scoped issue to create an immutable Turn struct for capturing LLM interaction cycles. This is a foundational type for the message history optimization epic.

Pre-Review Checks:

• Codebase health: Pass (tests green)
• Higher-priority blockers: None
• Issue claims verified: Yes - confirmed file location, no existing Turn struct, patterns match codebase

Analysis:

1. Should This Be Done?: Yes - Turn struct is required by ARC-001/ARC-002/ARC-010 and is a dependency for compression and Step.turns migration.

2. Simplifications: Issue is already minimal - just a struct with two constructors.

3. Codebase Research: Verified existing patterns:

   • Step.ok/error constructors provide the pattern to follow
   • No existing Turn struct in codebase
   • Context.ex has turn_history field showing turns concept exists
   • TurnFeedback.ex handles turn state in loop

4. Reuse Opportunities: Can follow Step.ex constructor pattern exactly.

5. Refactoring Needs: None - this is additive.

6. Edge Cases: None significant for a simple struct.

7. Issue Scope: Appropriately sized - single file, ~50 LOC.

8. Test Plan: Basic constructor tests are sufficient for a simple struct.

9. Solution Outline: Clear implementation path provided.

Changes Made to Issue Body:

• Fixed constructor arity: success/7 and failure/7 (was incorrectly /6)
• Added type annotations for each field
• Clarified that success? is set automatically by constructors
• Fixed "Blocks" references to use actual GitHub issue numbers (Compression behaviour and normalize #619, Step.trace → Step.turns migration (dual-write) #629) instead of roadmap numbers ([From PR #10] Add test for sandbox memory limit enforcement #12, [Phase 2] Add comparison operations (neq, gt, gte, lt, lte) #21)
• Added typespec requirement to acceptance criteria
• Clarified that feat: Enable prompt caching by moving dynamic content out of system prompt #603 (blocked-by) is complete

Dependencies:

• Blocked by: feat: Enable prompt caching by moving dynamic content out of system prompt #603 (PRE-001) - Already complete
• Blocks: Compression behaviour and normalize #619 (Compression behaviour), Step.trace → Step.turns migration (dual-write) #629 (Step.turns migration)

Verdict: Ready for implementation

[claude]

@claude Please implement this issue.