feat(session): add session persistence and repositories #255

Closed
opened 2026-02-22 23:40:36 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit: feat(session): add session persistence and repositories
  • Branch: feature/m3-session-persistence

Subtasks

  • Add DB tables sessions (9 cols, ULID PK, indexes on created_at and actor_name) and session_messages (8 cols, ULID PK, FK to sessions CASCADE, composite index on (session_id, sequence)) via migration a7_001_session_persistence (depends on b1_001_resource_registry).
  • Implement SessionRepository (5 methods: create/get_by_id/list_all/delete/update) + SessionMessageRepository (3 methods: append/get_for_session/count_for_session) with pagination (limit/offset), message append semantics, and @database_retry on all methods.
  • Implement PersistentSessionService extending domain SessionService ABC (8 methods: create/get/list/delete/append_message/export_session/import_session/update_token_usage) with ULID generation, auto-sequencing, SHA-256 checksum verification on import, schema version validation, and cumulative token usage tracking.
  • Wire session repositories/services into exports: 4 symbols in infrastructure/database/__init__.py (SessionModel, SessionMessageModel, SessionRepository, SessionMessageRepository), 1 symbol in application/services/__init__.py (PersistentSessionService).
  • Update docs/reference/database_schema.md with 2 new table sections (sessions, session_messages), updated ER diagram, migration chain, and source locations.
  • Tests (Behave): Add features/session_persistence.feature (24 scenarios across 8 groups: creation/listing/deletion/message-append/pagination/export-import/token-usage/ORM-round-trip) with features/steps/session_persistence_steps.py (431 lines).
  • Tests (Robot): Add robot/session_persistence.robot (4 integration tests: round-trip, message ordering, export+import, token tracking) with robot/helper_session_persistence.py (139 lines).
  • Tests (ASV): Add benchmarks/session_persistence_bench.py (2 ASV suites, 7 benchmarks: session create/get/list, message append, export, token update, import).
  • Run nox (all default sessions, including benchmark).
  • Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
  • Run nox (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Section: #### Section 3 Notes
Status: Completed

## Metadata - **Commit**: `feat(session): add session persistence and repositories` - **Branch**: `feature/m3-session-persistence` ## Subtasks - [x] Add DB tables `sessions` (9 cols, ULID PK, indexes on `created_at` and `actor_name`) and `session_messages` (8 cols, ULID PK, FK to sessions CASCADE, composite index on `(session_id, sequence)`) via migration `a7_001_session_persistence` (depends on `b1_001_resource_registry`). - [x] Implement `SessionRepository` (5 methods: `create`/`get_by_id`/`list_all`/`delete`/`update`) + `SessionMessageRepository` (3 methods: `append`/`get_for_session`/`count_for_session`) with pagination (`limit`/`offset`), message append semantics, and `@database_retry` on all methods. - [x] Implement `PersistentSessionService` extending domain `SessionService` ABC (8 methods: `create`/`get`/`list`/`delete`/`append_message`/`export_session`/`import_session`/`update_token_usage`) with ULID generation, auto-sequencing, SHA-256 checksum verification on import, schema version validation, and cumulative token usage tracking. - [x] Wire session repositories/services into exports: 4 symbols in `infrastructure/database/__init__.py` (`SessionModel`, `SessionMessageModel`, `SessionRepository`, `SessionMessageRepository`), 1 symbol in `application/services/__init__.py` (`PersistentSessionService`). - [x] Update `docs/reference/database_schema.md` with 2 new table sections (`sessions`, `session_messages`), updated ER diagram, migration chain, and source locations. - [x] Tests (Behave): Add `features/session_persistence.feature` (24 scenarios across 8 groups: creation/listing/deletion/message-append/pagination/export-import/token-usage/ORM-round-trip) with `features/steps/session_persistence_steps.py` (431 lines). - [x] Tests (Robot): Add `robot/session_persistence.robot` (4 integration tests: round-trip, message ordering, export+import, token tracking) with `robot/helper_session_persistence.py` (139 lines). - [x] Tests (ASV): Add `benchmarks/session_persistence_bench.py` (2 ASV suites, 7 benchmarks: session create/get/list, message append, export, token update, import). - [x] Run `nox` (all default sessions, including benchmark). - [ ] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. **Section**: #### Section 3 Notes **Status**: Completed
freemo added this to the v3.3.0 milestone 2026-02-22 23:40:36 +00:00
Author
Owner

Implementation Notes — A7.persistence: Session Persistence and Repositories

2026-02-15: Stage A7.persistence Complete - Session Persistence and Repositories

  • Created Alembic migration with 2 tables: sessions, session_messages.
  • Created SessionRepository (5 methods), SessionMessageRepository (3 methods), PersistentSessionService (8 methods).
  • Key decision: PersistentSessionService extends the domain SessionService ABC.
  • Key decision: append_message() auto-calculates sequence number and updates parent session's updated_at timestamp.
  • Key decision: import_session() validates schema version and SHA-256 checksum before persisting, then generates fresh ULIDs to avoid ID collisions.
  • Key decision: update_token_usage() uses cumulative addition (+=) rather than replacement.

(Migrated from docs/implementation-notes.md)

## Implementation Notes — A7.persistence: Session Persistence and Repositories **2026-02-15**: Stage A7.persistence Complete - Session Persistence and Repositories - Created Alembic migration with 2 tables: `sessions`, `session_messages`. - Created `SessionRepository` (5 methods), `SessionMessageRepository` (3 methods), `PersistentSessionService` (8 methods). - Key decision: `PersistentSessionService` extends the domain `SessionService` ABC. - Key decision: `append_message()` auto-calculates sequence number and updates parent session's `updated_at` timestamp. - Key decision: `import_session()` validates schema version and SHA-256 checksum before persisting, then generates fresh ULIDs to avoid ID collisions. - Key decision: `update_token_usage()` uses cumulative addition (+=) rather than replacement. *(Migrated from `docs/implementation-notes.md`)*
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
Reference
cleveragents/cleveragents-core#255
No description provided.