Application session-listing requirements
These requirements track the live state relative to the application session-listing specification.
The preserved groups describe behavior that existed before persistent, deadline-bounded session listing. The new groups describe behavior introduced by that correction. Functional requirements define results observed by application users or developers consuming the application API. Non-functional requirements constrain compatibility, reliability, performance, encapsulation, concurrency, privacy, and maintainability.
Each evidence cell contains only integration-test evidence generated from
structured comments above tests carrying pytest.mark.integration:
python scripts/update_session_list_requirement_evidence.py \
--requirements core/python/docs/development/specifications/session-listing/requirements.md \
--test application/python/tests/test_session_listing_requirements_integration.py
Use the same command with --check to verify that test links and line numbers
are current.
Preserved requirements
Functional requirements
| ID | Requirement | Implementation | Verification | Documentation | Evidence |
|---|---|---|---|---|---|
| SLIST-001 | AgentApplication provides one shared ordered session-summary collection, exact unfiltered summary lookup, structured diagnostics, filter schema access, and filter-evaluator installation through SessionListService. |
Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:210 |
| SLIST-002 | Session stores expose opaque live-session records with identity, modification time, and equality-comparable revision, and support collection and exact-record lookup without exposing storage paths. | Implemented | Automated | Not applicable | application/python/tests/test_session_listing_requirements_integration.py:210 |
| SLIST-003 | A complete summary contains record identity and modification time, a normalized first-user-message preview, session metadata excluding native_messages, contributed fields, and stable title/subtitle/meta presentation. |
Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:210 |
| SLIST-004 | Valid session_list application actions execute in plugin and declaration order with only declared inputs and application lifecycle context, may contribute JSON-serializable non-reserved fields and ordering, and fail independently with diagnostics. |
Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:210 |
| SLIST-005 | Session-list ordering defaults to descending modification time and composes valid contributed order declarations deterministically while ignoring invalid, incomplete, incompatible, or conflicting declarations with diagnostics. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:210 |
| SLIST-006 | Presentation fields resolve dotted summary paths, apply deterministic role/order/template/datetime rules, and fall back from title fields to preview and then an ID-derived title. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:210 |
| SLIST-007 | Declarative filters preserve ordered input, combine paths and active filters according to their typed contract, report invalid declarations and values without losing unrelated filters, run before limits, and do not affect exact lookup. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:210 |
| SLIST-010 | HTTP and terminal adapters delegate session listing and exact lookup to AgentApplication; HTTP preserves the {"sessions": [...]} envelope and maps missing exact IDs to 404. |
Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:210 |
Non-functional requirements
| ID | Requirement | Implementation | Verification | Documentation | Evidence |
|---|---|---|---|---|---|
| SLIST-008 | An unreadable or malformed stored session and an invalid plugin contribution do not fail the collection; the service returns safe fallback summary values and structured diagnostics. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:210 |
| SLIST-009 | Within one application instance, complete summaries are reused only while record revision and list contract token match; saves, deletes, external changes, and missing records invalidate stale results. | Implemented | Automated | Not applicable | application/python/tests/test_session_listing_requirements_integration.py:210; application/python/tests/test_session_listing_requirements_integration.py:519 |
New requirements
Functional requirements
| ID | Requirement | Implementation | Verification | Documentation | Evidence |
|---|---|---|---|---|---|
| SLIST-012 | Metadata enumeration establishes current session membership from identities and attributes without opening session content before the initial implementation's foreground full-resolution interval starts. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:369 |
| SLIST-013 | An unfiltered unlimited list returns one ordinary summary-shaped entry for every metadata-discovered session; unresolved entries use content-free fallback values and normal presentation without exposing implementation state. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:369; application/python/tests/test_session_listing_requirements_integration.py:645 |
| SLIST-014 | Complete summaries remain reusable across application runtimes, and unchanged records with compatible revisions and summary-contract fingerprints do not require session-content reads. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:519 |
| SLIST-015 | The initial implementation attempts required full resolutions in descending modification time, waits no longer than its privately configured foreground interval after enumeration, and continues unfinished work for later calls without requiring client changes. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:369; application/python/tests/test_session_listing_requirements_integration.py:645 |
| SLIST-016 | While unresolved entries remain, complete summaries use established ordering and precede metadata-only summaries ordered by descending modification time; filters conservatively retain entries whose unavailable data prevents a conclusive decision, and limits remain last. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:369 |
| SLIST-019 | Application-owned saves and deletes and externally observed revisions converge persistent and in-memory summaries without allowing obsolete work to overwrite a newer record or contract. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:519; application/python/tests/test_session_listing_requirements_integration.py:645 |
Non-functional requirements
| ID | Requirement | Implementation | Verification | Documentation | Evidence |
|---|---|---|---|---|---|
| SLIST-011 | SessionListService retains its existing public method signatures and return types while selected implementations receive opaque application context and keep cache, deadline, worker, scan, placeholder-state, and storage-backend concepts out of the public surface and shared configuration model. |
Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:369 |
| SLIST-017 | Concurrent calls share compatible in-flight work; background resource use and retries are bounded; blocking reads do not hold the service lock or request event loop; and application close or reload releases implementation-owned resources. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:369; application/python/tests/test_session_listing_requirements_integration.py:645 |
| SLIST-018 | Persistent derived state is private, transactional, bounded, and recoverable; corruption or unavailability degrades safely without changing source sessions, and diagnostics and logs do not expose session content or credentials. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:519 |
| SLIST-020 | The server delivers the target through existing application and HTTP contracts without changes to mobile, desktop, frontend SDK, or other client packages. | Implemented | Automated | Documented | application/python/tests/test_session_listing_requirements_integration.py:369; application/python/tests/test_session_listing_requirements_integration.py:645 |
Session-query refinement requirements
These target requirements refine filtering for the session and message data query specification. They do not change the implementation state of the completed bounded-listing requirements above.
| ID | Requirement | Implementation | Verification | Documentation | Evidence |
|---|---|---|---|---|---|
| SLIST-021 | Plugins may declare timezone-aware datetime session-list filters over built-in or contributed summary paths with before and after comparison variants. | Implemented | Automated | Documented | application/python/tests/test_session_data_query_http.py:99 |
| SLIST-022 | Python and TypeScript filter normalization, coercion, defaults, missing-value handling, UTC comparison, and diagnostics remain equivalent for datetime declarations and runtime values. | Implemented | Automated | Documented | application/python/tests/test_session_data_query_http.py:99 |
| SLIST-023 | Local Python, CLI, HTTP, terminal, and frontend callers pass filter IDs and values through the normalized plugin schema without adapter-specific date fields or changes to exact unfiltered lookup. | Implemented | Automated | Documented | application/python/tests/test_session_data_query_http.py:99 |
| SLIST-024 | Established summary ordering remains before filter evaluation, filters remain before limits, metadata-only uncertainty remains conservative, and JSONPath projection occurs only after the ordinary collection envelope is serialized. | Implemented | Automated | Documented | application/python/tests/test_session_data_query_http.py:99 |