Expose semantic database query names

[AnnieZhou08]

Related issue

N/A

Summary

• Expose a context-local semantic name for the database query currently executing, without coupling stores to a query-comment format or telemetry backend.
• Name every application DML statement in the SQLAlchemy file-store lifecycle and in conversation create/get paths, including split-database execution.

Test Plan

Added listener-based unit coverage that rejects empty names and verifies exact names for every DML statement exercised by FileStore CRUD and ConversationStore create/get. The existing file, conversation, and split-database conversation suites pass (225 tests), and the relevant Ruff, Pyrefly, and test-quality hooks pass.

Demo

N/A; this is a backend observability API.

Type of change

• Bug fix
• Feature
• UI / frontend change
• Refactor / chore
• Docs
• Test / CI
• Breaking change

Test coverage

• Unit tests added / updated
• Integration tests added / updated
• E2E tests added / updated
• Manual verification completed
• Existing tests cover this change
• Not applicable

Coverage notes

The listener tests exclude managed-session setup SQL and prove that inserts and deletes execute during their own named flush scopes.

Changelog

Database observability integrations can identify semantic FileStore and ConversationStore queries.

[github-actions]

@AnnieZhou08 This PR is a Bug fix, Feature, or UI / frontend change but the Demo section is missing or only contains a placeholder.

These change types require a screenshot or screen recording so reviewers can see the new behaviour without checking out the branch. Please update the Demo section with:

• A screenshot or screen recording of the change, or
• A link to a hosted video or GIF showing the new behaviour.

Use N/A only when the change has no user-visible effect whatsoever (e.g. a pure refactor or test-only change). If that's the case, uncheck the relevant type box and check Refactor / chore or Test / CI instead.

[omnigent-ci]

Polly AI Review

Blocking issues

None. The change is well-scoped: query_name_scope sets a ContextVar around explicit flush()/execute() calls, the name is hardcoded (never interpolated into SQL), and every named DML path has an accompanying listener-based test asserting the exact name sequence. Context restoration on both nested and raised paths is verified.

Security vulnerabilities

None. Query names are constant string literals stored in a ContextVar — they are never written into SQL text or comments, so there is no injection surface. No lockfile or dependency changes.

Non-blocking notes

• Autoflush can mis-attribute names. query_name_scope labels whatever statements execute inside it, but SQLAlchemy autoflush can emit unrelated pending INSERT/UPDATE statements when a SELECT runs. In the current paths there is no pending write inside a named SELECT scope, so it doesn't manifest, but it's a latent gotcha: a future named SELECT on a session with dirty state would attribute those flushed writes to the SELECT's name. Worth a one-line comment on query_name_scope noting the name applies to all SQL emitted in the scope, autoflush included.
• Partial coverage by design. Only the FileStore CRUD and ConversationStore create/get paths are named; other DML (updates, conversation search/list, item persistence) remains unnamed and will surface as None to instrumentation. That matches the PR's stated scope, but consumers should not assume every query carries a name yet.
• Name strings are duplicated between the stores and the test assertions, so a rename can silently drift the two apart. A shared constants module would keep them in lockstep; minor, optional.

Summary

A clean, low-risk observability primitive: a context-local semantic query name that decouples stores from any specific tracer/telemetry backend, applied to the FileStore and Conversation create/get DML paths with matching listener-based tests. No correctness or security concerns; the only caveat is the autoflush attribution edge case, which is latent rather than present in this diff. As a backend-only API with no user-visible surface, no visual demonstration is needed. Good to merge.

---

_{Automated review by Polly · workflow run}