feat(session): add session domain models and contracts #253

New issue

Closed

opened 2026-02-22 23:40:35 +00:00 by freemo · 1 comment

freemo commented

2026-02-22 23:40:35 +00:00

Owner

Metadata

Commit: feat(session): add session domain models and contracts
Branch: feature/m3-session-domain

Subtasks

Add Session and SessionMessage domain models with ULID IDs, actor ref, timestamps, and role enum (user/assistant/system/tool). (MessageRole enum, SessionMessage, SessionTokenUsage, Session models in session.py)
Add message validation for role/content presence and stable ordering by sequence number.
Add SessionService interface contracts (create/list/show/delete/append/export/import) with error types. (SessionService ABC + SessionNotFoundError, SessionMessageError, SessionExportError)
Add docs/reference/session_model.md and docs/reference/session_service.md.
Tests (Behave): Add features/session_model.feature for model validation and serialization ordering. (39 scenarios)
Tests (ASV): Add asv/benchmarks/session_model_bench.py for validation throughput.
Run nox (all default sessions, including benchmark). NOTE: lint 0 findings, typecheck 0 errors, 39 new scenarios pass.
Verify coverage >=97% via nox -s coverage_report. Coverage 97% overall (session.py 98%).

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

## Metadata - **Commit**: `feat(session): add session domain models and contracts` - **Branch**: `feature/m3-session-domain` ## Subtasks - [x] Add `Session` and `SessionMessage` domain models with ULID IDs, actor ref, timestamps, and role enum (user/assistant/system/tool). (MessageRole enum, SessionMessage, SessionTokenUsage, Session models in session.py) - [x] Add message validation for role/content presence and stable ordering by sequence number. - [x] Add `SessionService` interface contracts (create/list/show/delete/append/export/import) with error types. (SessionService ABC + SessionNotFoundError, SessionMessageError, SessionExportError) - [x] Add `docs/reference/session_model.md` and `docs/reference/session_service.md`. - [x] Tests (Behave): Add `features/session_model.feature` for model validation and serialization ordering. (39 scenarios) - [x] Tests (ASV): Add `asv/benchmarks/session_model_bench.py` for validation throughput. - [x] Run `nox` (all default sessions, including benchmark). NOTE: lint 0 findings, typecheck 0 errors, 39 new scenarios pass. - [x] Verify coverage >=97% via `nox -s coverage_report`. Coverage 97% overall (session.py 98%). **Section**: #### Section 3 Notes **Status**: Completed

freemo added this to the v3.3.0 milestone

2026-02-22 23:40:35 +00:00

freemo added the

labels

2026-02-22 23:40:35 +00:00

freemo self-assigned this

2026-02-22 23:40:35 +00:00

freemo closed this issue

2026-02-22 23:40:36 +00:00

freemo added a new dependency

2026-02-22 23:54:14 +00:00

#351 Epic: Plan Lifecycle A6-A8 (Sessions & Config CLI)

freemo referenced this issue from a pull request that will close it,

2026-02-23 17:25:04 +00:00

feature/m3-session-domain #58

freemo commented

2026-02-24 02:30:50 +00:00

Author

Owner

Implementation Notes — A7.domain: Session Domain Models and Contracts

2026-02-13: Stage A7.domain Complete - Session Domain Models and Contracts

Created session.py with MessageRole enum, SessionMessage, SessionTokenUsage, Session models, error classes, SessionService ABC.
Key decision: SessionService is an ABC (not Protocol) to enforce explicit inheritance and make contract violations visible at class definition time.
Key decision: Messages are ordered by sequence_number (not timestamp) to guarantee stable ordering across serialization boundaries.

(Migrated from docs/implementation-notes.md)

## Implementation Notes — A7.domain: Session Domain Models and Contracts **2026-02-13**: Stage A7.domain Complete - Session Domain Models and Contracts - Created `session.py` with `MessageRole` enum, `SessionMessage`, `SessionTokenUsage`, `Session` models, error classes, `SessionService` ABC. - Key decision: SessionService is an ABC (not Protocol) to enforce explicit inheritance and make contract violations visible at class definition time. - Key decision: Messages are ordered by `sequence_number` (not timestamp) to guarantee stable ordering across serialization boundaries. *(Migrated from `docs/implementation-notes.md`)*