Skip to content

feat: read-only session durability enhancements#18

Merged
k13gomez merged 4 commits intomainfrom
durability-enhancements
Jan 28, 2026
Merged

feat: read-only session durability enhancements#18
k13gomez merged 4 commits intomainfrom
durability-enhancements

Conversation

@k13gomez
Copy link
Member

@k13gomez k13gomez commented Jan 28, 2026

Summary

Adds support for query-only sessions as a durability optimization. Query-only sessions are a more restrictive subset of read-only sessions that support only query execution, resulting in significantly smaller memory footprint and serialization size.

Motivation

When deserializing sessions for query-only use cases, there's no need to restore the full rule network infrastructure (production nodes, alpha/beta roots, activation groups, etc.). By stripping out everything except query nodes and their beta memory, we can achieve additional memory and serialization size reductions for scenarios where only queries are needed.

Changes

Core Features

  • Added :query-only? option to session deserialization (similar to existing :read-only?)
  • Implemented rulebase->query-only-rulebase to create minimal rulebases containing only query nodes
  • Implemented memory->query-only-beta-memory to extract only query-related beta memory
  • Added assemble-query-only and as-query-only functions for creating query-only sessions

Durability Support

  • Added *read-only* dynamic var to coordinate expression compilation behavior during deserialization
  • Implemented reconstruct-node-expr-fn-lookup to centralize expression reconstruction logic
  • Updated Fressian serializer to support query-only deserialization

Documentation

  • Updated docstrings to clearly explain the relationship between read-only and query-only modes
  • Read-only: supports queries + inspection operations
  • Query-only: supports queries only (more aggressive optimization)

Relationship to Read-Only Sessions

  • Read-only sessions (:read-only? true): Support queries and inspection operations
  • Query-only sessions (:query-only? true): Support queries only (subset of read-only)

Query-only is the more aggressive optimization with smaller memory footprint.

Testing

  • Added comprehensive test coverage in test_durability.clj verifying query-only sessions:
    • Correctly restrict operations (no rule firing, insert, or retract)
    • Return identical query results to full and read-only sessions
    • Preserve session components correctly
  • Extended existing tests in test_rules.clj to verify query-only conversion with as-query-only

Breaking Changes

None. This is a backward-compatible addition. All existing code continues to work unchanged.

Usage Example

;; Deserialize with query-only optimization
(d/deserialize-session-state serializer
                             mem-serializer
                             {:query-only? true})

;; Convert existing session to query-only
(eng/as-query-only session)

@k13gomez k13gomez marked this pull request as ready for review January 28, 2026 20:57
@k13gomez k13gomez merged commit fea52df into main Jan 28, 2026
1 check passed
@k13gomez k13gomez deleted the durability-enhancements branch January 28, 2026 21:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants