@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