feat(session): sessions.db on the SQLite driver's native mode

[senamakel]

Summary

This moves sessions.db onto the tinystoragedrivers SQLite driver's native mode. The session crate keeps its own tables, SQL, FTS5 index and migrations exactly as they are, and the driver now owns the connection.

• store::with_connection / with_transaction (and through them every session op, the run ledger, the entry tree and retention) run on SqliteNative::run_blocking, the driver's shared per-file connection.
• Any other handle the host opens on the same file, async or sync, goes through that same connection and lock.
• The process-wide cache keyed by path stays. It now holds the native handle and still applies the session pragmas and migrations::apply once per path.
• On-disk compatibility: the same file at {workspace}/session_db/sessions.db, the same schema and schema_version marker, and no data migration. a_database_written_before_native_mode_opens_unchanged creates a database the old way and reads it through the new path.
• The public API is unchanged: db_path, with_connection, with_transaction, and every op signature.
• One behavioural note: the driver opens its connection with synchronous = NORMAL (with WAL). After a power loss, the last committed transactions may roll back, but the database stays consistent. WAL, the 5 s busy timeout and foreign_keys = ON are unchanged; the session still sets them itself.
• tinystoragedrivers-sqlite becomes a normal dependency of tinyagents-session, through a new workspace entry. It was already a dev-dependency, and cargo tree -d shows a single libsqlite3-sys.

Builds on tinyhumansai/tinystoragedrivers#6 (SqliteNative::run_blocking), merged and released as v0.4.0. vendor/tinystoragedrivers is pinned to that tag, and the workspace requirements are 0.4.0.

Tests

New store_tests.rs:

• a pre-native database opens unchanged;
• the store shares the driver's connection, with the session pragmas applied;
• transactions roll back on error;
• an unopenable path is a storage error.

cargo test -p tinyagents-session --all-features        # 528 passed
cargo test --workspace --all-features                  # all passed
cargo clippy --workspace --all-targets --all-features -- -D warnings   # stable and 1.99.0
cargo +1.88.0 check -p tinyagents-session --all-targets --all-features

cargo test --workspace (default features) hit one failure: providers::claude_agent_sdk::tests::provider_pipes_large_request_to_cli_stdin, which spawns a fake CLI script. It passes on every rerun and is untouched here, so it's a load-dependent flake on main.

[tinysweeper]

Tiny Sweeper review

Tiny Sweeper reviewed this pull request across 6 lane(s) and found 0 active actionable finding(s). The change moves the session store onto the SQLite driver's native mode, pins tinystoragedrivers to 0.4.0, documents the durability implications in the crate README and module docs, adds panic cleanup in with_connection so a panicking call cannot poison the shared connection, and adds tests in store_tests.rs covering the new behaviour. Reviewers noted the diff was reviewed without code retrieval or memory tooling, and the vendored SqliteNative submodule was not checked out, so the driver-side durability claims (WAL with synchronous = NORMAL, driver-set busy timeout) are stated but not verified or pinned by tests. All lanes concluded the change looks safe to merge.

State: Ready for maintainer review
Priority: low
Reviewed head: c1a8a029b2e5
Updated: 1791522207 (Unix time)

Review snapshot

Change surface	Files	Review signal	Count
Production	1	Active findings	0
Tests	1	Noted findings	0
Documentation	1	Resolved findings	0
Configuration	2	Pending checks/questions	0

Completeness: Complete
Test assessment: Test coverage is assessed from changed tests and lane evidence; execution is not claimed without trusted check data.

What changed

No supported behavioral explanation was produced.

Features

• Modified — Session store moved onto the SQLite driver's native mode: The per-path connection is now owned and shared by the SQLite driver (one shared connection per file behind its lock, shared with any other native handle the host opens on the same file, async or sync), with pragma setup and migrations still running exactly once per path. Operations on the same path serialize via the driver's lock and block the calling thread while waiting for it; a database file atomically replaced at the same path after first use is still not picked up because the connection is cached. This removes the per-call Connection::open cost previously measured as the dominant cost of session-store calls under load. (crates/tinyagents-session/src/store.rs#fn cached_connection(db_path: &Path) -> Result<ConnectionHandle> {)
• Modified — Panic-safe execution inside the shared connection lock: with_connection now catches panics from the caller's closure while the driver's connection lock is held, rolls back any open transaction left behind (logging a warning if the rollback itself fails), releases the lock, and then resumes the unwind so the caller still sees the panic. This keeps the one shared connection usable for later calls in the process, matching the earlier store's poison-tolerant lock behaviour. (crates/tinyagents-session/src/store.rs#fn cached_connection(db_path: &Path) -> Result<ConnectionHandle> {)
• Modified — Durability behaviour documented (WAL with synchronous = NORMAL): Code and README now state that the driver runs WAL with synchronous = NORMAL: commits survive a process crash, but after an OS crash or power loss the most recent committed transactions can be rolled back while the database stays consistent; anything that must survive power loss belongs in the transcript files, which remain the source of truth for resume. (crates/tinyagents-session/src/README.md#Six tables plus one FTS5 virtual table, created on demand and idempotently:, crates/tinyagents-session/src/store.rs#fn cached_connection(db_path: &Path) -> Result<ConnectionHandle> {)
• Modified — Workspace dependency updates for the SQLite driver: tinystoragedrivers-core is pinned to 0.4.0 and tinystoragedrivers-sqlite is added as a workspace dependency used by the session crate directly, replacing the dev-dependency path reference. (Cargo.toml#tokio = { version = "1", default-features = false, features = ["macros", "rt-mul, crates/tinyagents-session/Cargo.toml#storage-drivers = [, crates/tinyagents-session/Cargo.toml#tokio = { workspace = true, default-features = true, features = ["sync"] })
• Internal refactor — Database path resolution retained: db_path continues to resolve the workspace's session database location as before. (crates/tinyagents-session/src/store.rs#pub fn db_path(workspace_dir: &Path) -> PathBuf {)

Tests

• unit — a_database_written_before_native_mode_opens_unchanged creates a session DB the pre-change way (own connection, own pragmas and migrations), then records and reads a session through the store.: Pins on-disk backward compatibility with databases written before native mode. (crates/tinyagents-session/src/store_tests.rs)
• unit — the_store_shares_the_drivers_connection writes a session, then opens a separate SqliteNative handle and asserts the sessions row is visible and PRAGMA foreign_keys is 1.: Exercises the shared-connection and foreign_keys claims through public paths and would fail on regression. (crates/tinyagents-session/src/store_tests.rs)
• unit — a_transaction_rolls_back_on_error runs with_transaction that creates a scratch table then returns an error, and verifies the scratch table does not exist afterwards.: Covers transaction rollback on error through the store's connection path. (crates/tinyagents-session/src/store_tests.rs)
• unit — an_unopenable_path_is_a_storage_error places a file where the session_db directory should be and asserts with_connection returns a TinyAgentsError::Storage.: Covers the unopenable-path error mapping; the tests lane noted a tautological assertion (driver_error("x").to_string().contains("session DB")) as a nit. The tests lane also noted the durability claims (synchronous = NORMAL, driver-set busy timeout) are stated but not pinned by any test, and the vendored driver submodule was not checked out so they cannot be verified from the review. (crates/tinyagents-session/src/store_tests.rs)
• unit — a_panicking_call_leaves_the_connection_usable runs with_transaction whose closure creates a table then panics, catches the resumed panic, and then verifies via with_connection that the table was rolled back and via with_transaction that the connection still works.: Pins the panic-cleanup behaviour: the panic still reaches the caller, the open transaction is rolled back, and the shared connection remains usable. (crates/tinyagents-session/src/store_tests.rs)

Findings

No active actionable findings.

Before merge

None.

Agent review details

critique

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Lane summary: The change moves session storage onto the native SQLite driver, adds panic cleanup, and covers the new behavior with sibling unit tests. No concrete correctness issue is demonstrable from the available repository context; the native driver's implementation was not available to verify its sharing and error contracts. _Code retrieval was unavailable (model: ladder embeddings returned 400 Bad Request: {"error":{"message":"unknown ladder vectors; known ladders are flash (also chat-v1, flash-v1), instant (also no-think, instant-v1), reasoning (also deepseek), max-reasoning (also max-reasoning-v1), deepseek-flash (also reasoning-v1, agentic-v1), deep (also luna), scribe, uncensored, vectors-oai3 (also embeddings-oai3-v1), vision (also vision-v1, multimodal-v1), image (also images-v1, image-v1), vi), so this review saw the diff alone._ _Memory was unavailable (model: cortex: v1/recall: error sending request for url (http://cortexdb:3141/v1/recall\)\), so this review ran without it._

security

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Positive: The security lane found the change preserves migrations, transaction rollback, and panic recovery behaviour while moving to the native SQLite driver; no evident security or permission issue.
• Lane summary: The session store now uses the native SQLite driver while preserving migrations, transaction rollback, and panic recovery behavior. The change looks safe to merge. _Code retrieval was unavailable (model: ladder embeddings returned 400 Bad Request: {"error":{"message":"unknown ladder vectors; known ladders are flash (also chat-v1, flash-v1), instant (also no-think, instant-v1), reasoning (also deepseek), max-reasoning (also max-reasoning-v1), deepseek-flash (also reasoning-v1, agentic-v1), deep (also luna), scribe, uncensored, vectors-oai3 (also embeddings-oai3-v1), vision (also vision-v1, multimodal-v1), image (also images-v1, image-v1), vi), so this review saw the diff alone._ _Memory was unavailable (model: cortex: v1/recall: error sending request for url (http://cortexdb:3141/v1/recall\)\), so this review ran without it._

tests

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Positive: The new store_tests.rs pins legacy-database compatibility, the shared-connection/foreign_keys claim, transaction rollback, the unopenable-path error mapping, and panic recovery, exercising real behaviour through public paths and would fail on regression.
• Lane summary: The change moves the session store onto the tinystoragedrivers SQLite driver's native mode and adds a test module covering backward compatibility, shared-connection semantics, transaction rollback, error mapping, and panic recovery. The behaviour is real (error path construction in `cached_connection`) and tested; the remaining issues are two anti-patterns in the test file itself: a helper that throws away the error detail it wraps, and a test name that no longer matches what it actually exercises. _Code retrieval was unavailable (model: ladder embeddings returned 400 Bad Request: {"error":{"message":"unknown ladder vectors; known ladders are flash (also chat-v1, flash-v1), instant (also no-think, instant-v1), reasoning (also deepseek), max-reasoning (also max-reasoning-v1), deepseek-flash (also reasoning-v1, agentic-v1), deep (also luna), scribe, uncensored, vectors-oai3 (also embeddings-oai3-v1), vision (also vision-v1, multimodal-v1), image (also images-v1, image-v1), vi), so this review saw the diff alone._ _Memory was unavailable (model: cortex: v1/recall: error sending request for url (http://cortexdb:3141/v1/recall\)\), so this review ran without it._

commits

• Conclusion: Neutral
• Scope reviewed: all assigned evidence
• Positive: The commits lane found nothing sensitive in what this pull request commits.
• Lane summary: Nothing sensitive found in what this pull request commits.

description

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Positive: The description lane confirmed the diff matches the pull request description: sessions.db moves onto the tinystoragedrivers SQLite driver's native mode, the API is unchanged, the durability note about synchronous = NORMAL is documented in both the module docs and the README, and the claimed tests are present.
• Lane summary: The diff matches the pull request description: sessions.db moves onto the tinystoragedrivers SQLite driver's native mode, the API is unchanged, the durability note about `synchronous = NORMAL` is documented in both the module docs and the README, and the four claimed tests are present. The new README section stays within the 500-line cap and the tests follow the repository's `<module>_tests.rs` convention. Looks sound to merge. _Code retrieval was unavailable (model: ladder embeddings returned 400 Bad Request: {"error":{"message":"unknown ladder vectors; known ladders are flash (also chat-v1, flash-v1), instant (also no-think, instant-v1), reasoning (also deepseek), max-reasoning (also max-reasoning-v1), deepseek-flash (also reasoning-v1, agentic-v1), deep (also luna), scribe, uncensored, vectors-oai3 (also embeddings-oai3-v1), vision (also vision-v1, multimodal-v1), image (also images-v1, image-v1), vi), so this review saw the diff alone._ _Memory was unavailable (model: cortex: v1/recall: error sending request for url (http://cortexdb:3141/v1/recall\)\), so this review ran without it._

e2e

• Conclusion: Neutral
• Scope reviewed: all assigned evidence
• Lane summary: No end-to-end harness in this repository: no e2e test files and no e2e workflow.

Evidence and run details

• Models: gpt-5.6-luna, glm-5.3-flash
• Spend: $0.005616
• Tokens: 138220 input · 6965 output · 13575 cached · 0 embedding

Head	State	Pass summary
b5e0af5e554f	ready for maintainer review	0 active finding(s), 0 resolved finding(s) (at 1791520873)
2a2ba2595012	ready for maintainer review	0 active finding(s), 0 resolved finding(s) (at 1791521491)
713bfc15f9a5	ready for maintainer review	0 active finding(s), 0 resolved finding(s) (at 1791521842)
c1a8a029b2e5	ready for maintainer review	0 active finding(s), 0 resolved finding(s) (at 1791522207)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-09T05:03:32.055201Z	c1a8a02	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

Warning

Review limit reached

• Run on-demand review

_{This review includes 5 billable files and costs up to $1.25.}

Or wait 38 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3a1fd8b8-57b3-487e-ab34-0c5c208c7a77

📥 Commits

Reviewing files that changed from the base of the PR and between b5e0af5 and c1a8a02.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• Cargo.toml
• crates/tinyagents-session/src/README.md
• crates/tinyagents-session/src/store.rs
• crates/tinyagents-session/src/store_tests.rs
• vendor/tinystoragedrivers

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 5c1bfe6f-5a33-4d77-aa9e-02fc86143282

📥 Commits

Reviewing files that changed from the base of the PR and between f28201c and b5e0af5.

📒 Files selected for processing (5)

• Cargo.toml
• crates/tinyagents-session/Cargo.toml
• crates/tinyagents-session/src/store.rs
• crates/tinyagents-session/src/store_tests.rs
• vendor/tinystoragedrivers

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

---

📝 Walkthrough

Walkthrough

The session store now uses SqliteNative handles from the vendored SQLite driver. It runs connection preparation, migrations, and callbacks through the driver’s blocking interface. New tests cover database reads, foreign-key settings, transaction rollback, and open errors.

Changes

Session SQLite driver integration

Layer / File(s)	Summary
Add the SQLite driver dependency vendor/tinystoragedrivers, Cargo.toml, crates/tinyagents-session/Cargo.toml	The workspace and session crate declare tinystoragedrivers-sqlite as a regular dependency. The session crate removes its dev-dependency path declaration, and the vendored driver reference changes.
Use native handles in the session store crates/tinyagents-session/src/store.rs, crates/tinyagents-session/src/store_tests.rs	The store opens and caches SqliteNative handles and runs preparation, migrations, and callbacks through run_blocking. Tests cover session reads, foreign keys, transaction rollback, and open errors.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant SessionStore
  participant SqliteNative
  participant SQLiteDatabase
  SessionStore->>SqliteNative: Open database path
  SqliteNative->>SQLiteDatabase: Open native connection
  SessionStore->>SqliteNative: Run preparation and migrations with run_blocking
  SqliteNative->>SQLiteDatabase: Apply preparation and migrations
  SessionStore->>SqliteNative: Run connection callback with run_blocking
  SqliteNative->>SQLiteDatabase: Execute callback operations

Loading

Merge Risk

Merge Risk: ⚪ Minimal · up to b5e0a

The session database now uses the SQLite driver's native mode without changing the schema or the public API. No actionable merge-blocking risk remains after review.

Security Architecture Review

Security architecture risk: 🔵 Low · up to b5e0a

Session storage keeps its existing interface and file format. No increased attacker authority was demonstrated, but the shared connection’s concurrency, failure recovery, and power-loss guarantees could not be fully verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The changed entrypoints affect workspace session storage and the session operations, retention, and run ledger routed through them. The intended sharing scope is one database file within a process. Actual driver identity rules and deployment-level tenant or environment exposure remain unverified.

Trust Boundaries and Controls

• inferred — The inspected public entrypoints do not introduce a new caller input or grant additional SQL callback authority: workspace selection and direct Connection access already existed. This rejects a demonstrated entrypoint-level privilege expansion, but does not resolve the unavailable driver’s path identity or cross-handle isolation behavior.

Resilience and Maintainability Implications

• observed — The outer session cache still recovers a poisoned mutex, while per-connection locking and callback failures now cross the native driver boundary. Ordinary errors propagate as storage errors, but lock recovery and reusable transaction state after interruption cannot be established from the available implementation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 2 files. (3 skipped: 3…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the main change: moving session storage to the SQLite driver's native mode.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{A rabbit taps a SQLite door
A native handle opens wide
Migrations hop through blocking calls
Session rows are checked inside
Then carrots crunch beside the code}

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b5e0af5e55

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[tinysweeper]

tinysweeper found nothing blocking. Approving.

             $0.0078 · 160,626 in / 10,141 out · 17,432 cached (11%) · gpt-5.6-luna, glm-5.3-flash, deepseek-v4.1-flash
critique:    $0.0033 · 57,936 in  / 3,481 out  · 8,271 cached (14%)  · gpt-5.6-luna
security:    $0.0044 · 81,622 in  / 3,495 out  · 9,161 cached (11%)  · gpt-5.6-luna
tests:       $0.0001 · 7,474 in   / 627 out    · 0 cached (0%)       · glm-5.3-flash
description: $0.0001 · 7,462 in   / 203 out    · 0 cached (0%)       · glm-5.3-flash

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 713bfc15f9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c1a8a029b2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Release the cache lock before acquiring the driver lock

When a host uses SqliteNative directly, this introduces a lock-order inversion: cached_connection retains the process-wide cache mutex while run_blocking waits for a per-file driver lock. If one thread holds driver lock A and, from its callback, opens an uncached session DB B while another thread performs the first session access to A, the latter holds the cache mutex waiting for A and the former waits for the cache mutex, deadlocking both operations. Initialize the native connection without holding the global cache lock, then reconcile concurrent insertions afterward (or use per-path initialization state).

Useful? React with 👍 / 👎.