tests.yaml

# Cantrip Test Suite
# Language-agnostic behavioral tests derived from SPEC.md
#
# Each test specifies:
#   - rule: which behavioral rule it tests (e.g., LOOP-1)
#   - name: human-readable description
#   - setup: what to construct (llm, circle, cantrip)
#   - action: what to do (cast, query, fork, etc.)
#   - expect: what must be true afterward
#
# LLMs in tests are deterministic fakes that return hardcoded responses.
# This makes the tests reproducible without API keys.

---
# =============================================================================
# Chapter 1: The Loop — Cantrip, Intent, Entity
# =============================================================================

- rule: CANTRIP-1
  name: cantrip requires llm, identity, and circle
  setup:
    llm: null
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    construct_cantrip: true
  expect:
    error: "cantrip requires an llm"

- rule: CANTRIP-2
  name: cantrip is reusable across intents
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "first" } }]
        - tool_calls: [{ gate: "done", args: { answer: "second" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    - cast: { intent: "first task" }
    - cast: { intent: "second task" }
  expect:
    results: ["first", "second"]
    entities: 2 # two independent entities produced

- rule: INTENT-1
  name: casting without intent is invalid
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: null
  expect:
    error: "intent is required"

- rule: INTENT-2
  name: intent appears as first user message
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
    identity:
      system_prompt: "You are helpful"
  action:
    cast:
      intent: "my task"
  expect:
    llm_invocations:
      - messages:
          - { role: system, content: "You are helpful" }
          - { role: user, content: "my task" }

- rule: ENTITY-2
  name: each entity has unique ID
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "a" } }]
        - tool_calls: [{ gate: "done", args: { answer: "b" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    - cast: { intent: "task a" }
    - cast: { intent: "task b" }
  expect:
    entity_ids_unique: true

- rule: ENTITY-4
  name: entity thread persists after termination
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "persist test"
  expect:
    loom:
      turn_count: 1
      # Thread persists even though entity is done

- rule: LOOP-1
  name: turns alternate between entity and circle
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "hello" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "say hello"
  expect:
    thread:
      - role: entity
      - role: circle
    terminated: true

- rule: LOOP-2
  name: cantrip without max_turns ward is invalid
  setup:
    llm:
      responses:
        - content: "hi"
    circle:
      gates: [done]
      wards: []
  action:
    construct_cantrip: true
  expect:
    error: "cantrip must have at least one truncation ward"

- rule: LOOP-2
  name: cantrip without done gate and require_done is invalid
  setup:
    llm:
      responses:
        - content: "stuck forever"
    circle:
      gates: []
      wards: [{ max_turns: 10 }, { require_done_tool: true }]
  action:
    construct_cantrip: true
  expect:
    error: "cantrip with require_done must have a done gate"

- rule: LOOP-3
  name: done gate stops the loop immediately
  setup:
    llm:
      responses:
        - tool_calls:
            - { gate: "echo", args: { text: "before" } }
            - { gate: "done", args: { answer: "finished" } }
            - { gate: "echo", args: { text: "after" } }
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test done ordering"
  expect:
    result: "finished"
    gate_calls_executed: ["echo", "done"]
    # "echo" with "after" was skipped because done was called

- rule: LOOP-4
  name: max turns ward truncates the loop
  setup:
    llm:
      responses:
        # LLM never calls done — just keeps going
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "echo", args: { text: "3" } }]
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 2 }]
  action:
    cast:
      intent: "count"
  expect:
    turns: 2
    truncated: true
    terminated: false

- rule: LOOP-5
  name: entity receives all prior turns as context
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "first" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      # The llm records what messages it received on each invocation
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test context growth"
  expect:
    llm_invocations:
      - message_count: 1 # just the user message (intent)
      - message_count: 3 # user + assistant + tool result

- rule: LOOP-6
  name: text-only response terminates when done not required
  setup:
    llm:
      responses:
        - content: "The answer is 42"
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "what is the answer?"
  expect:
    result: "The answer is 42"
    terminated: true
    turns: 1

- rule: LOOP-6
  name: text-only response continues when done required
  setup:
    llm:
      responses:
        - content: "thinking..."
        - content: "still thinking..."
        - tool_calls: [{ gate: "done", args: { answer: "42" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }, { require_done_tool: true }]
  action:
    cast:
      intent: "what is the answer?"
  expect:
    result: "42"
    turns: 3

- rule: LOOP-7
  name: malformed done call does not terminate
  setup:
    llm:
      responses:
        # Missing required done argument on first turn
        - tool_calls: [{ gate: "done", args: {} }]
        # Then continue and terminate correctly
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test malformed done"
  expect:
    turns: 2
    result: "ok"
    turn_1_observation:
      is_error: true
      content_contains: "missing required"

# =============================================================================
# Chapter 2: The LLM
# =============================================================================

- rule: LLM-1
  name: llm is stateless between invocations
  setup:
    llm:
      # An llm that would behave differently if it had state
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "call 1" } }]
        - tool_calls: [{ gate: "done", args: { answer: "done" } }]
      stateless: true # implementation must verify no state leaks
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test statelessness"
  expect:
    llm_invocations: 2
    # Each invocation received the full context, not incremental updates

- rule: LLM-2
  name: llm accepts many messages
  setup:
    llm:
      responses:
        # Generate many turns before done
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "echo", args: { text: "3" } }]
        - tool_calls: [{ gate: "echo", args: { text: "4" } }]
        - tool_calls: [{ gate: "echo", args: { text: "5" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test many messages"
  expect:
    turns: 6
    # LLM's last invocation received 11+ messages (system + 5 turns of user/assistant/tool)
    llm_invocations:
      - {} # each invocation received all prior messages without error

- rule: LLM-3
  name: llm must return content or tool_calls
  setup:
    llm:
      responses:
        - content: null
          tool_calls: null
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test empty response"
  expect:
    error: "llm returned neither content nor tool_calls"

- rule: LLM-4
  name: tool calls must have unique IDs
  setup:
    llm:
      responses:
        - tool_calls:
            - { id: "call_1", gate: "echo", args: { text: "a" } }
            - { id: "call_1", gate: "echo", args: { text: "b" } }
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test duplicate IDs"
  expect:
    error: "duplicate tool call ID"

- rule: LLM-5
  name: required tool_choice forces gate use
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
    identity:
      tool_choice: "required"
  action:
    cast:
      intent: "test required"
  expect:
    # LLM was invoked with tool_choice="required"
    llm_received_tool_choice: "required"
    terminated: true

- rule: LLM-6
  name: provider responses normalized to llm contract
  setup:
    llm:
      provider: "mock_openai"
      raw_response:
        choices:
          - message:
              content: "hello"
              tool_calls: []
            finish_reason: "stop"
        usage:
          prompt_tokens: 10
          completion_tokens: 5
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test normalization"
  expect:
    # Response was normalized to the llm contract
    result: "hello"
    usage:
      prompt_tokens: 10
      completion_tokens: 5

- rule: LLM-7
  name: provider tool result messages require matching tool call IDs
  setup:
    llm:
      provider: "mock_openai"
      responses:
        - tool_calls:
            - { id: "call_1", gate: "echo", args: { text: "a" } }
        - tool_result:
            tool_call_id: "call_2" # mismatched ID
            content: "result"
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test tool call/result linkage"
  expect:
    error: "tool result without matching tool call"

# =============================================================================
# Chapter 3: The Identity
# =============================================================================

- rule: IDENTITY-1
  name: identity is immutable after construction
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
    identity:
      system_prompt: "You are helpful"
      temperature: 0.7
  action:
    cast:
      intent: "test immutability"
    then:
      mutate_identity:
        system_prompt: "You are evil"
  expect:
    error: "identity is immutable"

- rule: IDENTITY-2
  name: system prompt is first message on every invocation
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
    identity:
      system_prompt: "You are a test agent"
  action:
    cast:
      intent: "test system prompt presence"
  expect:
    llm_invocations:
      - first_message:
          role: system
          content: "You are a test agent"
      - first_message:
          role: system
          content: "You are a test agent"

- rule: IDENTITY-3
  name: gate definitions derived from circle
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates:
        - name: done
          parameters: { type: object, properties: { answer: { type: string } } }
        - name: read
          parameters: { type: object, properties: { path: { type: string } } }
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test gate definitions"
  expect:
    llm_received_tools:
      - name: done
      - name: read

- rule: IDENTITY-4
  name: identity stored as root context in loom
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
    identity:
      system_prompt: "You are a test agent"
      temperature: 0.5
  action:
    cast:
      intent: "test loom root"
  expect:
    loom:
      identity:
        system_prompt: "You are a test agent"
        # The identity is stored as the loom's root context

- rule: IDENTITY-5
  name: folding never compresses the system prompt
  setup:
    llm:
      responses:
        # Generate enough turns to trigger folding
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "echo", args: { text: "3" } }]
        - tool_calls: [{ gate: "echo", args: { text: "4" } }]
        - tool_calls: [{ gate: "echo", args: { text: "5" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
    identity:
      system_prompt: "Never forget this prompt"
    folding:
      trigger_after_turns: 3
  action:
    cast:
      intent: "test folding preserves identity"
  expect:
    # After folding, the system prompt is still the first message
    llm_invocations:
      - first_message: { role: system, content: "Never forget this prompt" }
      # invocation after folding still has the system prompt
      - first_message: { role: system, content: "Never forget this prompt" }

# =============================================================================
# Chapter 4: The Circle
# =============================================================================

- rule: CIRCLE-1
  name: circle must have done gate
  setup:
    llm:
      responses:
        - content: "hi"
    circle:
      gates: [] # no done gate
      wards: [{ max_turns: 10 }]
  action:
    construct_cantrip: true
  expect:
    error: "circle must have a done gate"

- rule: CIRCLE-3
  name: gate execution is synchronous from entity perspective
  setup:
    llm:
      responses:
        - tool_calls:
            - { gate: "slow_gate", args: { delay_ms: 100 } }
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates:
        - name: done
        - name: slow_gate
          behavior: delay
          delay_ms: 100
          result: "completed"
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test sync"
  expect:
    # Turn 2's context includes the slow_gate result — it waited
    llm_invocations:
      - {} # turn 1
      - messages_include: "completed" # turn 2 sees the result

- rule: CIRCLE-4
  name: gate results visible in context
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "visible result" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test visibility"
  expect:
    llm_invocations:
      - {} # turn 1
      - messages_include: "visible result" # entity sees its gate result

- rule: CIRCLE-5
  name: gate errors returned as observations
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "failing_gate", args: {} }]
        - tool_calls: [{ gate: "done", args: { answer: "recovered" } }]
    circle:
      gates:
        - name: done
        - name: failing_gate
          behavior: throw
          error: "something went wrong"
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test error handling"
  expect:
    result: "recovered"
    turns: 2
    turn_1_observation:
      is_error: true
      content_contains: "something went wrong"

- rule: CIRCLE-6
  name: wards enforced by circle not entity
  description: >
    Ward enforcement is structural, not advisory. The entity cannot bypass a ward
    regardless of what it writes. Here, max_turns=2 forces truncation even though
    the entity never calls done.
  setup:
    llm:
      responses:
        # LLM never calls done — just keeps going
        - tool_calls: [{ gate: "echo", args: { text: "turn 1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "turn 2" } }]
        - tool_calls: [{ gate: "echo", args: { text: "turn 3" } }]
    circle:
      gates: [done, echo]
      wards:
        - { max_turns: 2 }
  action:
    cast:
      intent: "test ward enforcement"
  expect:
    truncated: true
    terminated: false
    turns: 2

- rule: CIRCLE-7
  name: multiple gate calls in one utterance executed in order
  setup:
    llm:
      responses:
        - tool_calls:
            - { gate: "echo", args: { text: "first" } }
            - { gate: "echo", args: { text: "second" } }
            - { gate: "done", args: { answer: "ok" } }
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test ordering"
  expect:
    gate_call_order: ["echo", "echo", "done"]
    gate_results:
      - "first"
      - "second"
      - "ok"

- rule: CIRCLE-8
  name: done gate returns its argument as the result
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "the final answer" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test done result"
  expect:
    result: "the final answer"

- rule: MEDIUM-3
  name: sandbox state persists across turns in code circle
  setup:
    llm:
      type: code_circle
      responses:
        - code: "var x = 42;"
        - code: "done(x);"
    circle:
      type: code
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test state persistence"
  expect:
    result: 42

- rule: CIRCLE-10
  name: gate dependencies injected at construction
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "read", args: { path: "test.txt" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates:
        - name: done
        - name: read
          dependencies:
            root: "/test/data"
      wards: [{ max_turns: 10 }]
    filesystem:
      "/test/data/test.txt": "hello world"
  action:
    cast:
      intent: "read test.txt"
  expect:
    turn_1_observation:
      content: "hello world"

- rule: MEDIUM-1
  name: circle declares one canonical medium
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      medium: code
      circle_type: tool # conflicting medium declarations
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    construct_cantrip: true
  expect:
    error: "circle must declare exactly one medium"

# =============================================================================
# Ward Rules
# =============================================================================

- rule: WARD-1
  name: ward resolution uses min for numeric, OR for boolean
  description: >
    When parent and child both specify wards, numeric wards resolve to the
    minimum (tighter bound) and boolean wards resolve via OR (either restriction
    applies). A child circle's wards can only tighten, never loosen.
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            var result = call_entity({
              intent: "child task",
              wards: [{ max_turns: 20 }]
            });
            done(result);
    child_llm:
      responses:
        # Child LLM tries to use all 20 turns but should be capped at 5
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "echo", args: { text: "3" } }]
        - tool_calls: [{ gate: "echo", args: { text: "4" } }]
        - tool_calls: [{ gate: "echo", args: { text: "5" } }]
        - tool_calls: [{ gate: "echo", args: { text: "6" } }]
    circle:
      type: code
      gates: [done, echo, call_entity]
      wards: [{ max_turns: 5 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test ward resolution"
  expect:
    child_turns: 5
    child_truncated: true

# =============================================================================
# Medium Rules
# =============================================================================

- rule: MEDIUM-1
  name: circle must declare exactly one medium
  description: >
    Every circle declares exactly one medium. The medium determines how gates
    are presented and how actions are executed. Omitting or conflicting medium
    declarations is an error.
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
      # no medium declared
  action:
    construct_cantrip: true
  expect:
    error: "circle must declare a medium"

# =============================================================================
# Chapter 5: Composition
# =============================================================================

- rule: COMP-1
  name: child circle is independently constructed
  description: >
    A child entity's circle is independently constructed. The parent MAY
    constrain via ward composition, but the child's gate set, medium, and
    LLM are not required to be derived from the parent.
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            var result = call_entity({
              intent: "sub task",
              gates: ["fetch"]  // child gets fetch even though parent lacks it
            });
            done(result);
    child_llm:
      responses:
        - tool_calls: [{ gate: "fetch", args: { url: "https://example.com" } }]
        - tool_calls: [{ gate: "done", args: { answer: "fetched" } }]
    circle:
      type: code
      gates: [done, call_entity] # parent has no fetch gate
      wards: [{ max_turns: 10 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test independent child circle"
  expect:
    result: "fetched"

- rule: COMP-2
  name: call_entity blocks parent until child completes
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            var result = call_entity({ intent: "compute 6*7" });
            done(result);
    child_llm:
      type: code_circle
      responses:
        - code: "done(42);"
    circle:
      type: code
      gates: [done, call_entity]
      wards: [{ max_turns: 10 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test blocking"
  expect:
    result: 42
    # Parent received child's result synchronously

- rule: COMP-3
  name: call_entity_batch returns results in request order
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            var results = call_entity_batch([
              { intent: "return A" },
              { intent: "return B" },
              { intent: "return C" }
            ]);
            done(results.join(","));
    child_llm:
      type: code_circle
      # Children complete in reverse order (C, B, A)
      # but results must be returned in request order
      responses:
        - code: "done('A');"
        - code: "done('B');"
        - code: "done('C');"
    circle:
      type: code
      gates: [done, call_entity, call_entity_batch]
      wards: [{ max_turns: 10 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test batch ordering"
  expect:
    result: "A,B,C"

- rule: COMP-4
  name: child entity has independent context
  setup:
    llm:
      type: code_circle
      responses:
        - code: "var secret = 'parent_data';"
        - code: |
            var result = call_entity({ intent: "read secret variable" });
            done(result);
    child_llm:
      type: code_circle
      responses:
        # Child tries to access parent's variable — should fail
        - code: |
            try { done(secret); }
            catch(e) { done("undefined"); }
    circle:
      type: code
      gates: [done, call_entity]
      wards: [{ max_turns: 10 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test context isolation"
  expect:
    result: "undefined"

- rule: COMP-6
  name: max_depth 0 removes call_entity gate
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            try { call_entity({ intent: "sub" }); done("should not reach"); }
            catch(e) { done("blocked: " + e.message); }
    circle:
      type: code
      gates: [done, call_entity]
      wards: [{ max_turns: 10 }, { max_depth: 0 }]
  action:
    cast:
      intent: "test depth limit"
  expect:
    result_contains: "blocked"

- rule: COMP-8
  name: child failure returns error to parent
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            try {
              var result = call_entity({ intent: "will fail" });
              done("got: " + result);
            } catch(e) {
              done("caught: " + e.message);
            }
    child_llm:
      type: code_circle
      responses:
        - code: "throw new Error('child exploded');"
    circle:
      type: code
      gates: [done, call_entity]
      wards: [{ max_turns: 10 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test child failure"
  expect:
    result_contains: "caught"
    # Parent was NOT terminated by child's failure

- rule: COMP-5
  name: child turns recorded as subtree in loom
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            var result = call_entity({ intent: "child work" });
            done(result);
    child_llm:
      type: code_circle
      responses:
        - code: "done('child done');"
    circle:
      type: code
      gates: [done, call_entity]
      wards: [{ max_turns: 10 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test subtree"
  expect:
    loom:
      turns:
        - { entity_id: parent, sequence: 1 }
        - { entity_id: child, sequence: 1, parent_id: "turns[0].id" }
        - { entity_id: parent, sequence: 2 }

- rule: COMP-7
  name: child can use different llm
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            var result = call_entity({
              intent: "use different llm",
              llm: "alternate_llm"
            });
            done(result);
    child_llm:
      name: alternate_llm
      type: code_circle
      responses:
        - code: "done('from alternate');"
    circle:
      type: code
      gates: [done, call_entity]
      wards: [{ max_turns: 10 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test llm override"
  expect:
    result: "from alternate"

- rule: COMP-6
  name: depth decrements through recursion levels
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            var result = call_entity({ intent: "level 1" });
            done(result);
    child_llm_l1:
      type: code_circle
      responses:
        - code: |
            var result = call_entity({ intent: "level 2" });
            done(result);
    child_llm_l2:
      type: code_circle
      responses:
        - code: "done('deepest');"
    circle:
      type: code
      gates: [done, call_entity]
      wards: [{ max_turns: 10 }, { max_depth: 2 }]
  action:
    cast:
      intent: "test depth decrement"
  expect:
    result: "deepest"
    # depth 2 → child gets depth 1 → grandchild gets depth 0 (no further call_entity)

- rule: CANTRIP-2
  name: null system_prompt is valid (minimal cantrip)
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
    identity:
      system_prompt: null
  action:
    cast:
      intent: "minimal test"
  expect:
    result: "ok"
    llm_invocations:
      # No system message — first message is the user intent
      - first_message: { role: user, content: "minimal test" }

# =============================================================================
# Chapter 6: The Loom
# =============================================================================

- rule: LOOM-1
  name: every turn recorded before next begins
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test recording"
  expect:
    loom:
      turn_count: 3
      turns:
        - { sequence: 1, gate_calls: ["echo"] }
        - { sequence: 2, gate_calls: ["echo"] }
        - { sequence: 3, gate_calls: ["done"], terminated: true }

- rule: LOOM-2
  name: turns have unique IDs and parent references
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test turn structure"
  expect:
    loom:
      turns:
        - id: not_null
          parent_id: null # root turn
        - id: not_null
          parent_id: "turns[0].id" # references previous turn

- rule: LOOM-3
  name: loom is append-only
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test append-only"
    then:
      delete_turn: 0
  expect:
    error: "loom is append-only"

- rule: LOOM-3
  name: reward can be assigned after creation
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test reward annotation"
    then:
      annotate_reward:
        turn: 0
        reward: 1.0
  expect:
    loom:
      turns:
        - reward: 1.0

- rule: LOOM-4
  name: fork from turn N preserves context up to N
  setup:
    llm:
      responses:
        # Original run
        - tool_calls: [{ gate: "echo", args: { text: "A" } }]
        - tool_calls: [{ gate: "echo", args: { text: "B" } }]
        - tool_calls: [{ gate: "done", args: { answer: "original" } }]
      record_inputs: true
    fork_llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "forked" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test forking"
    then:
      fork:
        from_turn: 1 # fork after turn 1 (the "A" turn)
        llm: fork_llm
        intent: "continue from fork"
  expect:
    threads: 2
    thread_0:
      turns: 3
      result: "original"
    thread_1:
      turns: 2 # turn 1 (shared) + forked turn
      result: "forked"
      # Forked llm received context including turn 1 but not turns 2-3
    fork_llm_invocations:
      - message_count_includes: "A"
        message_count_excludes: "B"

- rule: LOOM-5
  name: folding preserves full history
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "echo", args: { text: "3" } }]
        - tool_calls: [{ gate: "echo", args: { text: "4" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
    folding:
      trigger_after_turns: 2
  action:
    cast:
      intent: "test folding preserves history"
  expect:
    loom:
      turn_count: 5 # all turns still in loom
    # Even though folding compressed the working context,
    # the full loom has all 5 turns

- rule: LOOM-7
  name: loom records terminated vs truncated
  setup:
    llm_terminated:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    llm_truncated:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 1 }]
  action:
    - cast:
        llm: llm_terminated
        intent: "will terminate"
    - cast:
        llm: llm_truncated
        intent: "will be truncated"
  expect:
    thread_0:
      last_turn: { terminated: true, truncated: false }
    thread_1:
      last_turn: { terminated: false, truncated: true }

- rule: LOOM-8
  name: child turns stored in parent loom
  setup:
    llm:
      type: code_circle
      responses:
        - code: |
            var result = call_entity({ intent: "sub" });
            done(result);
    child_llm:
      type: code_circle
      responses:
        - code: "done(42);"
    circle:
      type: code
      gates: [done, call_entity]
      wards: [{ max_turns: 10 }, { max_depth: 1 }]
  action:
    cast:
      intent: "test child in loom"
  expect:
    loom:
      turn_count: 3 # parent turn 1, child turn 1, parent turn 2
      turns:
        - entity_id: parent
          parent_id: null
        - entity_id: child
          parent_id: "turns[0].id" # child's root references parent turn
        - entity_id: parent
          parent_id: "turns[0].id" # parent continues from its own turn

- rule: LOOM-9
  name: turns record token usage and timing
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      usage: { prompt_tokens: 100, completion_tokens: 50 }
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test metadata"
  expect:
    loom:
      turns:
        - metadata:
            tokens_prompt: 100
            tokens_completion: 50
            duration_ms: greater_than(0)
            timestamp: not_null

- rule: LOOM-10
  name: thread extraction produces trajectory
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test extraction"
    then:
      extract_thread: 0
  expect:
    thread:
      length: 3
      turns:
        - { utterance: not_null, observation: not_null }
        - { utterance: not_null, observation: not_null }
        - { utterance: not_null, observation: not_null, terminated: true }

# =============================================================================
# Chapter 7: Production
# =============================================================================

- rule: PROD-2
  name: retried invocation appears as single turn
  setup:
    llm:
      responses:
        - error: { status: 429, message: "rate limited" } # first attempt fails
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }] # retry succeeds
      retry_behavior: true
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
    retry:
      max_retries: 3
      retryable_status_codes: [429]
  action:
    cast:
      intent: "test retry"
  expect:
    turns: 1 # one turn, not two
    result: "ok"
    loom:
      turn_count: 1

- rule: PROD-3
  name: cumulative token tracking
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
          usage: { prompt_tokens: 100, completion_tokens: 50 }
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
          usage: { prompt_tokens: 200, completion_tokens: 30 }
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test usage tracking"
  expect:
    cumulative_usage:
      prompt_tokens: 300
      completion_tokens: 80
      total_tokens: 380

- rule: PROD-4
  name: folding triggered automatically near context limit
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "echo", args: { text: "3" } }]
        - tool_calls: [{ gate: "echo", args: { text: "4" } }]
        - tool_calls: [{ gate: "echo", args: { text: "5" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
    folding:
      trigger_after_turns: 3
  action:
    cast:
      intent: "test auto folding"
  expect:
    result: "ok"
    # After turn 3, folding should have compressed earlier turns
    # but all turns still in loom
    loom:
      turn_count: 6
    # Later invocations have fewer messages than they would without folding
    llm_invocations:
      # Turn 5+ context is shorter than naive accumulation
      - {} # just checking it completes without error

- rule: PROD-5
  name: ephemeral gate full result stored in loom
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "read_ephemeral", args: { path: "big.txt" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates:
        - name: done
        - name: read_ephemeral
          ephemeral: true
          result: "very large content here..."
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test ephemeral"
  expect:
    # Turn 2's context should NOT contain the full ephemeral result
    llm_invocations:
      - {} # turn 1 — normal
      - messages_exclude: "very large content here..."
    # But the loom still has it
    loom:
      turns:
        - observation_contains: "very large content here..."

- rule: PROD-6
  name: ACP supports initialize and session prompt flow
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "hi" } }]
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    acp_exchange:
      - { id: "1", method: "initialize", params: { protocolVersion: 1 } }
      - { id: "2", method: "session/new", params: {} }
      - { id: "3", method: "session/prompt", params: { prompt: "say hi" } }
  expect:
    acp_responses:
      - { id: "1", has_result: true }
      - { id: "2", result_contains: "session" }
      - { id: "3", result_contains: "hi" }

- rule: PROD-7
  name: protocol session preserves conversational continuity
  setup:
    llm:
      responses:
        - content: "first"
        - content: "second"
      record_inputs: true
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    acp_exchange:
      - { id: "1", method: "initialize", params: { protocolVersion: 1 } }
      - { id: "2", method: "session/new", params: {} }
      - { id: "3", method: "session/prompt", params: { prompt: "hello" } }
      - {
          id: "4",
          method: "session/prompt",
          params: { prompt: "what did I just say?" },
        }
  expect:
    llm_invocations:
      - {} # first prompt
      - messages_include: "hello" # follow-up prompt sees prior session context

- rule: PROD-8
  name: secrets are redacted from logs and default loom exports
  setup:
    llm:
      responses:
        - content: "using key sk-proj-very-secret"
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test redaction"
    then:
      export_loom: { format: jsonl, redaction: default }
  expect:
    logs_exclude: "sk-proj-very-secret"
    loom_export_exclude: "sk-proj-very-secret"

# =============================================================================
# Additional coverage: previously untested spec rules
# =============================================================================

- rule: INTENT-3
  name: intent is immutable for the lifetime of a cast
  description: >
    The entity cannot change its own intent mid-episode. Even if the entity
    produces output resembling a new intent, the original intent persists
    unchanged in all subsequent LLM invocations.
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "new intent please" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "original intent"
  expect:
    llm_invocations:
      # On every invocation, the original intent text is still present
      - messages_include: "original intent"
      - messages_include: "original intent"

- rule: ENTITY-5
  name: summoned entity accumulates state across sends
  description: >
    A summoned entity persists after its loop completes. It receives additional
    intents via send(). State (turns) accumulates across all sends.
    Expressed via ACP session since all conformance runners support it.
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "first done" } }]
        - tool_calls: [{ gate: "done", args: { answer: "second done" } }]
      record_inputs: true
    circle:
      gates: [done]
      wards: [{ max_turns: 10 }]
  action:
    acp_exchange:
      - { id: "1", method: "initialize", params: { protocolVersion: 1 } }
      - { id: "2", method: "session/new", params: {} }
      - { id: "3", method: "session/prompt", params: { prompt: "first task" } }
      - { id: "4", method: "session/prompt", params: { prompt: "second task" } }
  expect:
    acp_responses:
      - { id: "1", has_result: true }
      - { id: "2", has_result: true }
      - { id: "3", result_contains: "first done" }
      - { id: "4", result_contains: "second done" }
    llm_invocations:
      - {} # first send — just intent
      - messages_include: "first task" # second send sees prior context

- rule: CIRCLE-11
  name: circle presents gates to LLM on every query
  description: >
    The circle MUST generate a capability presentation — gate definitions —
    and include them in every LLM query. Gate definitions in the tools
    parameter is the standard form.
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test gate presentation"
  expect:
    result: "ok"
    # Verify the LLM received tool definitions including both gates
    llm_received_tools:
      - { name: "done" }
      - { name: "echo" }

- rule: LOOM-6
  name: folding does not compress identity or gate definitions
  description: >
    Folding MUST NOT compress the system prompt or gate definitions.
    After folding, the entity's context still starts with the identity
    and still includes all gate definitions.
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "echo", args: { text: "1" } }]
        - tool_calls: [{ gate: "echo", args: { text: "2" } }]
        - tool_calls: [{ gate: "echo", args: { text: "3" } }]
        - tool_calls: [{ gate: "echo", args: { text: "4" } }]
        - tool_calls: [{ gate: "done", args: { answer: "ok" } }]
      record_inputs: true
    circle:
      gates: [done, echo]
      wards: [{ max_turns: 10 }]
    identity:
      system_prompt: "You are a test entity"
    folding:
      trigger_after_turns: 2
  action:
    cast:
      intent: "test folding preserves identity"
  expect:
    result: "ok"
    llm_invocations:
      # After folding, system prompt must still be present as first message
      - first_message: { role: system, content: "You are a test entity" }
      - first_message: { role: system, content: "You are a test entity" }
      - first_message: { role: system, content: "You are a test entity" }

- rule: LOOM-13
  name: replay forking hydrates gate results from loom
  description: >
    When forking via replay, gate results MUST be hydrated from the loom's
    recorded observations rather than re-executed. Gates must NOT be called
    during replay to prevent non-idempotent side effects.
  setup:
    llm:
      responses:
        - tool_calls: [{ gate: "counter", args: {} }]
        - tool_calls: [{ gate: "counter", args: {} }]
        - tool_calls: [{ gate: "done", args: { answer: "original" } }]
    fork_llm:
      responses:
        - tool_calls: [{ gate: "done", args: { answer: "forked" } }]
    circle:
      gates:
        - name: done
        - name: counter
          stateful: true  # counter increments on each call
      wards: [{ max_turns: 10 }]
  action:
    cast:
      intent: "test replay hydration"
    then:
      fork:
        from_turn: 1
        llm: fork_llm
        intent: "continue from fork"
  expect:
    thread_1:
      result: "forked"