Session and message data query requirements
These requirements track the live implementation of the session and message data query specification.
The query contract is implemented, verified, and documented.
| ID | Requirement | Implementation | Verification | Documentation | Evidence |
|---|---|---|---|---|---|
| SDQ-001 | Session and message collection calls with no include or exclude selectors preserve their current routes, envelopes, canonical values, omission rules, ordering, and complete result types. | Implemented | Automated | Documented | Core/application default suites; HTTP legacy fast-path test; frontend SDK complete-after-projected integration; user guide |
| SDQ-002 | Callers may supply ordered RFC 9535 JSONPath include and exclude selectors; includes union matches with required ancestors, excludes are evaluated against the original document and win, array elements are removed cleanly, and selected canonical indices retain their values. | Implemented | Automated | Documented | core/python/tests/test_json_projection.py; Python/CLI/HTTP adapter tests; JSONPath contract |
| SDQ-003 | Projection remains generic across current and future message roles and metadata discriminators and introduces no role-specific options, closed role registry, named projection presets, or implementation-specific text-search syntax. | Implemented | Automated | Documented | Future-role and metadata-discriminator projection tests; HTTP future-role integration; generic examples |
| SDQ-004 | Plugin-declared session filters support timezone-aware datetime input and before/after comparisons over built-in or contributed summary fields with equivalent Python and TypeScript normalization. | Implemented | Automated | Documented | Shared filter-cases.json Python/TypeScript tests; timestamp plugin tests; mobile/desktop filter tests; plugin filter guide |
| SDQ-005 | The local Python runtime lists plugin-filtered session summaries and canonical message ranges with optional include/exclude projection while preserving compact history and explicit full-message lookup. | Implemented | Automated | Documented | test_local_agent_runtime.py; source/archive packaged-SDK smokes; Python guide |
| SDQ-006 | crystal-lattice sessions uses the active plugin filter schema, supports projection and JSON/text/TSV/CSV formats, and emits exactly one undecorated session ID per line when that is the only selected scalar. |
Implemented | Automated | Documented | test_headless_cli.py; test_query_rendering.py; source/archive/installer smokes; CLI guide |
| SDQ-007 | crystal-lattice messages retrieves exactly one session range, supports the same projection and formats, emits grep-friendly one-line selected values with session/index/type/path context, and composes safely in a sessions shell loop. |
Implemented | Automated | Documented | Real CLI subprocess chain and exact renderer tests; source/archive/installer smokes; shell search |
| SDQ-008 | Existing HTTP session and message collection endpoints accept plugin filter and JSONPath projection parameters while unchanged requests retain current behavior and invalid inputs receive bounded 400 responses. |
Implemented | Automated | Documented | test_session_data_query_http.py; existing server contract suite; HTTP guide |
| SDQ-009 | The frontend SDK represents projected data explicitly, forwards filters and selectors through the production REST adapter, preserves complete call types without projection, and prevents partial lazy-hydration data from corrupting complete caches. | Implemented | Automated | Documented | REST query unit tests; real FastAPI production-adapter integration; frontend SDK default suite; SDK guide |
| SDQ-010 | JSON output is structurally lossless within the requested projection; text, TSV, and CSV output have documented deterministic one-record rendering and escaping suitable for human inspection and ordinary grep. |
Implemented | Automated | Documented | test_query_rendering.py; CLI JSON/text chain; output guide |
| SDQ-011 | Projection and enumeration enforce bounded selector, range, result, output, and complexity limits without treating projection as an authorization boundary or exposing selected sensitive values in diagnostics. | Implemented | Automated | Documented | Projection selector/match/size tests; renderer row/value bounds; invalid CLI/HTTP tests; bounds and security |
| SDQ-012 | Current field documentation covers session summaries, plugin-contributed fields, indexed and canonical messages, metadata reasoning, multipart content, tool results, snapshot/cursor envelope fields, projection semantics, and copyable JSON and text search examples without named presets. | Implemented | Automated | Documented | Application and frontend SDK query guides; docs preparation and MkDocs build |
| SDQ-013 | Source, direct archive/manual, Bash-installed, and PowerShell-installed runtimes expose and execute the new session/message commands with platform-safe JSONPath quoting and line-oriented output on applicable native targets. | Implemented | Automated | Documented | Clean macOS ARM64 source smoke plus all applicable direct archive, Bash, and PowerShell paths passed on six native targets in run 36442124636 |
Active work
Implementation planning and approval are tracked by
tasks/20260825-crystal-lattice-product-positioning-and-website/022-session-and-message-query-projections.md.