Skip to content

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.