@session
Feature: Session Persistence and Repositories
  As a developer
  I want sessions to be persisted to the database
  So that conversation history survives restarts and can be managed via CLI

  # ---- Session Creation ----

  Scenario: Persist a new session with default values
    Given a session persistence service is initialised
    When I persist a new session with no actor
    Then the persisted session should have a valid ULID
    And the persisted session namespace should be "local"

  Scenario: Persist a session bound to an actor
    Given a session persistence service is initialised
    When I persist a new session with actor "local/orchestrator"
    Then the persisted session actor_name should be "local/orchestrator"

  Scenario: Persist a session and retrieve it by ID
    Given a session persistence service is initialised
    When I persist a new session with no actor
    And I retrieve the persisted session by ID
    Then the retrieved session should match the created session

  # ---- Session Listing ----

  Scenario: List all persisted sessions
    Given a session persistence service is initialised
    And I persist 3 sessions
    When I list all persisted sessions
    Then the persisted session list should have 3 entries

  Scenario: List sessions returns empty when none exist
    Given a session persistence service is initialised
    When I list all persisted sessions
    Then the persisted session list should have 0 entries

  # ---- Session Deletion ----

  Scenario: Delete a persisted session
    Given a session persistence service is initialised
    When I persist a new session with no actor
    And I delete the persisted session by ID
    Then retrieving the deleted session should raise SessionNotFoundError

  Scenario: Delete a non-existent session raises error
    Given a session persistence service is initialised
    When I try to delete a non-existent session
    Then the session deletion should raise SessionNotFoundError

  # ---- Message Append and Retrieval ----

  Scenario: Append a user message to a session
    Given a session persistence service is initialised
    And I persist a new session with no actor
    When I append a user message "Hello world" to the persisted session
    Then the appended message role should be "user"
    And the appended message content should be "Hello world"

  Scenario: Append multiple messages with correct sequencing
    Given a session persistence service is initialised
    And I persist a new session with no actor
    When I append 5 messages to the persisted session
    Then the persisted session should have 5 messages with sequential ordering

  Scenario: Retrieve messages in correct order
    Given a session persistence service is initialised
    And I persist a new session with no actor
    And I append 3 messages to the persisted session
    When I retrieve all messages for the persisted session
    Then the retrieved messages should be ordered by sequence

  Scenario: Append message to non-existent session raises error
    Given a session persistence service is initialised
    When I try to append a message to a non-existent session
    Then the message append should raise SessionNotFoundError

  # ---- Message Pagination ----

  Scenario: Retrieve messages with limit
    Given a session persistence service is initialised
    And I persist a new session with no actor
    And I append 10 messages to the persisted session
    When I retrieve messages with limit 3 and offset 0
    Then I should get exactly 3 messages

  Scenario: Retrieve messages with offset
    Given a session persistence service is initialised
    And I persist a new session with no actor
    And I append 10 messages to the persisted session
    When I retrieve messages with limit 3 and offset 5
    Then I should get exactly 3 messages
    And the first paginated message sequence should be 5

  Scenario: Message count matches appended messages
    Given a session persistence service is initialised
    And I persist a new session with no actor
    And I append 7 messages to the persisted session
    When I count messages for the persisted session
    Then the message count should be 7

  # ---- Export / Import ----

  Scenario: Export a session to JSON dict
    Given a session persistence service is initialised
    And I persist a new session with actor "local/orchestrator"
    And I append 2 messages to the persisted session
    When I export the persisted session
    Then the export dict should contain a schema_version key
    And the export dict should contain a checksum key
    And the export dict should contain 2 messages

  Scenario: Import a session from exported JSON
    Given a session persistence service is initialised
    And I persist a new session with actor "local/orchestrator"
    And I append 2 messages to the persisted session
    And I export the persisted session
    When I import the exported session data
    Then the imported session should have 2 messages
    And the imported session should have a different ID from the original

  Scenario: Import with invalid schema version raises error
    Given a session persistence service is initialised
    When I try to import session data with schema version "99.0"
    Then the import should raise SessionImportError

  Scenario: Import with corrupted checksum raises error
    Given a session persistence service is initialised
    And I persist a new session with no actor
    And I export the persisted session
    When I tamper with the exported checksum and import
    Then the import should raise SessionImportError

  # ---- Token Usage ----

  Scenario: Update token usage for a session
    Given a session persistence service is initialised
    And I persist a new session with no actor
    When I update token usage with 100 input and 50 output and 0.005 cost
    Then the persisted session token usage should show 100 input tokens
    And the persisted session token usage should show 50 output tokens
    And the persisted session token usage should show 0.005 estimated cost

  Scenario: Cumulative token usage across multiple updates
    Given a session persistence service is initialised
    And I persist a new session with no actor
    When I update token usage with 100 input and 50 output and 0.005 cost
    And I update token usage with 200 input and 100 output and 0.010 cost
    Then the persisted session token usage should show 300 input tokens
    And the persisted session token usage should show 150 output tokens

  Scenario: Token usage update on non-existent session raises error
    Given a session persistence service is initialised
    When I try to update token usage on a non-existent session
    Then the token update should raise SessionNotFoundError

  # ---- ORM Round-Trip ----

  Scenario: Session ORM round-trip preserves all fields
    Given a session persistence service is initialised
    When I persist a session with full metadata and actor
    And I retrieve the persisted session by ID
    Then all session fields should be preserved in the round-trip

  Scenario: SessionMessage ORM round-trip preserves metadata
    Given a session persistence service is initialised
    And I persist a new session with no actor
    When I append a message with metadata to the persisted session
    And I retrieve all messages for the persisted session
    Then the retrieved message metadata should be preserved
