Revisit 'Own Our Schema' architecture claim — docs, ADRs, PRD misrepresent what we are

[Alberto-Codes]

Problem

Multiple foundational documents describe adk-secure-sessions as having an "independent schema" and being "just an encryption layer." Investigation revealed both claims are inaccurate, and the current architecture has a ceiling that blocks multi-database support.

What we discovered

1. Our schema mirrors ADK, it's not independent

Our 4 tables (app_states, user_states, sessions, events) are a copy of ADK's SqliteSessionService schema with TEXT → BLOB for encrypted columns and an added version column. Same table names, same columns, same structure.

2. We're a full session service replacement, not an encryption layer

We reimplement all persistence logic (CRUD, state splitting, event storage, connection management) in addition to encryption. Every customer-facing doc says "encryption layer" or "drop-in replacement for DatabaseSessionService" — neither is accurate. We implement BaseSessionService from scratch with our own persistence.

3. ADR-000's decorator rejection reasoning is stale

ADR-000 rejected wrapping because append_event used json_patch SQL operations with no interception point. That was true for V0's per-column event schema. ADK V1 changed this — events are now a single event_data JSON blob, and DatabaseSessionService merges state in Python (dict | delta), not SQL.

4. Architecture B (current) was right for MVP, but has a ceiling

For SQLite-only MVP, reimplementing persistence in raw aiosqlite was pragmatic. But to mature beyond SQLite, we'd have to reimplement everything ADK already provides:

• PostgreSQL/MySQL/MariaDB dialect handling
• Connection pooling with pool_pre_ping
• Row-level locking (SELECT ... FOR UPDATE)
• Schema version detection and migration
• GetSessionConfig filtering
• Timestamp dialect normalization

5. SqliteSessionService cannot be wrapped

SqliteSessionService uses json_patch(state, excluded.state) — a SQLite JSON function that merges deltas in SQL. The state column MUST be valid JSON text. Encrypted data (BLOB or base64) breaks this. This is the same blocker ADR-000 identified, just in a different service.

6. DatabaseSessionService CAN be wrapped

DatabaseSessionService V1 loads state into Python, merges with dict | delta, writes back through SQLAlchemy. No SQL-level JSON operations. A SQLAlchemy TypeDecorator can intercept at the ORM boundary — encrypt on write, decrypt on read. SQLAlchemy is already in our dep tree via google-adk.

7. Table name collision risk

ADK's tables and our tables share identical names. Pointing both at the same database would collide. Wrapping DatabaseSessionService eliminates this — we'd use their tables with encrypted column types.

Architecture decision needed

To mature beyond SQLite-only, wrap DatabaseSessionService via SQLAlchemy TypeDecorator. This gives us:

• SQLite + PostgreSQL + MySQL + MariaDB encryption — for free
• Row-level locking, connection pooling, dialect handling — for free
• Schema migrations when ADK evolves — for free
• Focus solely on encryption — our actual value-add
• No table name collision (we use their tables)

The encryption backends (Fernet, AES-256-GCM) are properly abstracted behind EncryptionBackend protocol and survive this change untouched.

Blast radius

10 HIGH / 8 MEDIUM / 8 LOW severity findings across docs, source, and planning artifacts.

HIGH — must fix

File	Issue
pyproject.toml:4	"drop-in replacement for DatabaseSessionService"
README.md:13	Same
CLAUDE.md:11	"own schema independent of ADK"
.claude/rules/conventions.md:35-39	"Own Our Schema" — lists 2 of 4 tables, "independent" claim
docs/adr/ADR-004	Entire "own schema" narrative
docs/adr/ADR-000:45	Stale V0-era rejection reasoning
docs/ROADMAP.md:5	"missing encryption layer"
docs/index.md:13	"drop-in replacement for DatabaseSessionService and SqliteSessionService"
src/__init__.py:10-11	"Drop-in replacement for DatabaseSessionService"
src/services/encrypted_session.py:3,123	Same in module + class docstrings

MEDIUM — should fix

ADR-000 additional lines, ARCHITECTURE.md, index.md feature bullet, project-overview.md, docstring-templates.md, services/init.py, PRD line 334, planning architecture

LOW — minor / historical

CHANGELOG entries, epics, project-context.md, implementation artifacts

Action items

Phase A: Documentation honesty (can do now)

• Revise ADR-004 — "mirror ADK V1 with encrypted column types, managed via raw SQL"
• Revise ADR-000 — note V1 changes, document why full replacement was chosen for MVP, note wrapping is viable path forward
• Update conventions.md — fix 2-table parenthetical (we have 4), honest framing
• Update all HIGH severity files (pyproject.toml, README, CLAUDE.md, index.md, docstrings)
• Update ROADMAP.md — "encrypted session service" not "encryption layer"

Phase B: Architecture migration (before Phase 3 epics)

• Spike: prototype wrapping DatabaseSessionService with SQLAlchemy TypeDecorator
• Evaluate migration path for existing SQLite users
• New ADR: Architecture migration from direct implementation to DatabaseSessionService wrapper
• Rewrite encrypted_session.py from ~800 lines raw SQL to thin wrapper
• Update Epic 4 scope (Postgres comes for free)

Phase C: Sub-issues

• Runner interaction surface conformance test
• Behavioral conformance test (round-trip same Session/Event through both services)
• Namespace tables if any raw-SQL path is retained as fallback

[Alberto-Codes]

Additional findings: Postgres cost and ORM question

Phase 3 Postgres — reimplementation cost

ADK's DatabaseSessionService already handles for Postgres:

• Connection pooling (pool_pre_ping)
• Row-level locking (SELECT ... FOR UPDATE) for concurrent writes
• SQLAlchemy async engine management
• Dialect-aware timestamp handling (SQLite vs Postgres)
• Schema version detection and migration (V0→V1)
• GetSessionConfig filtering (after_timestamp, num_recent_events)
• MySQL/MariaDB/PostgreSQL dialect support

Under Architecture B (current), we'd reimplement all of the above from scratch for Phase 3 — just to change TEXT columns to BLOB. This is a significant engineering effort to replicate what ADK gives for free.

ORM consideration: SQLAlchemy TypeDecorator

ADK already uses SQLAlchemy async. It's in our dependency tree via google-adk. If we adopted SQLAlchemy, we could create a custom TypeDecorator that transparently encrypts/decrypts:

class EncryptedJSON(TypeDecorator):
    impl = LargeBinary  # BLOB instead of TEXT
    
    def process_bind_param(self, value, dialect):
        return encrypt(json.dumps(value))
    
    def process_result_value(self, value, dialect):
        return json.loads(decrypt(value))

This could enable extending ADK's existing storage models with encrypted column types rather than reimplementing all CRUD, locking, pooling, and dialect handling.

Architecture A revisited

The V0→V1 migration eliminated the main blocker for wrapping DatabaseSessionService. With V1's single event_data JSON blob, a wrapper/interceptor approach may now be viable. Combined with SQLAlchemy TypeDecorator for the column type mismatch, this could mean:

• Zero persistence code to maintain
• Free Postgres/MySQL/MariaDB support from ADK
• Free row-level locking, connection pooling, dialect handling
• Free schema migrations when ADK evolves
• We focus solely on encryption — our actual value-add

Decision needed before Phase 3

Before building Postgres persistence (Phase 3), we should evaluate:

1. Can we wrap DatabaseSessionService with V1's simplified schema?
2. Does SQLAlchemy TypeDecorator solve the TEXT→BLOB column type issue?
3. What's the migration path for existing SQLite users?

[Alberto-Codes]

ADK session service landscape — what we're actually aligning to

All ADK session services (as of 1.26.0)

Service	Backend	ORM	Schema
SqliteSessionService	SQLite only	Raw aiosqlite	TEXT, REAL — our schema is a copy of this
DatabaseSessionService	SQLite, PostgreSQL, MySQL, MariaDB	SQLAlchemy async	V0/V1 with VARCHAR, DATETIME
InMemorySessionService	Dict in memory	None	N/A
VertexAiSessionService	Google Cloud managed	REST API	N/A

Key finding

Our schema is not aligned to DatabaseSessionService (as docs imply with "drop-in replacement for DatabaseSessionService"). We are a copy of SqliteSessionService's schema with TEXT → BLOB and an added version column. Same raw aiosqlite, same REAL timestamps, same DDL structure.

SqliteSessionService is a separate, newer implementation from DatabaseSessionService — it uses raw SQL like us, not SQLAlchemy.

Architecture options now expand

Approach	Wraps	Gets for free	Limitation
Wrap SqliteSessionService	SQLite raw aiosqlite	Cleanest path, same approach we use	SQLite only
Wrap DatabaseSessionService	SQLAlchemy async	SQLite + Postgres + MySQL + MariaDB	Heavier dependency, SQLAlchemy coupling
Wrap both	Pick per backend	Full coverage of local persistence	More integration surface
Current (Architecture B)	Neither	Nothing	Reimplement everything ourselves

What this means for epic ordering

The decision of WHICH service(s) to wrap determines the entire Phase 3 scope:

• If we wrap DatabaseSessionService: Epic 4 (Postgres) comes for free. Epic 3 (AES-256-GCM) is unaffected.
• If we wrap SqliteSessionService: Simpler migration from current code, but Postgres still requires separate work.
• VertexAiSessionService: Different beast entirely (REST API). Encrypting for managed cloud sessions would mean intercepting payloads before they hit Google's API. Separate epic if ever needed.
• InMemorySessionService: No persistence = no encryption at rest needed. Out of scope.

Recommendation

Resolve this architecture question BEFORE starting Epic 3. The encryption backends (Fernet, AES-256-GCM) are properly abstracted behind EncryptionBackend protocol and survive any architecture change. But integration tests, the service layer, and serialization code all depend on which wrapping strategy we choose.

[Alberto-Codes]

Critical finding: json_patch blocks wrapping SqliteSessionService

SqliteSessionService uses SQL-level JSON merging

SqliteSessionService._upsert_app_state() and _update_session_state_in_db() use SQLite's json_patch(state, excluded.state) function to merge state deltas directly in SQL. The state column MUST contain valid JSON text.

This means:

• Cannot encrypt state to BLOB — json_patch() needs valid JSON
• Cannot base64-encode encrypted data as TEXT — not valid JSON
• Cannot encrypt state values only — json_patch merging two encrypted value strings = garbage

DatabaseSessionService V1 does NOT have this problem

V1 loads state into Python (storage_session.state | session_state_delta), merges in Python, writes back through SQLAlchemy. No SQL-level JSON operations. A TypeDecorator could intercept before/after SQLAlchemy serialization.

Updated wrapping viability

Target	Wrappable?	Blocker
SqliteSessionService	No	json_patch() SQL function requires valid JSON in TEXT column
DatabaseSessionService	Yes	Merges state in Python; TypeDecorator can intercept at ORM boundary
InMemorySessionService	N/A	No persistence = no encryption at rest
VertexAiSessionService	Separate concern	REST API interception, different architecture entirely

Conclusion

DatabaseSessionService is the only viable wrapping target. This means:

1. We'd adopt SQLAlchemy (already in our dep tree via google-adk)
2. We'd get SQLite + PostgreSQL + MySQL + MariaDB for free
3. The SqliteSessionService raw-aiosqlite approach (which we copied) is a dead end for wrapping due to json_patch
4. Our current Architecture B (own raw SQL) was the right choice for raw aiosqlite, but the ceiling is SQLite-only

This is the key architectural decision: stay with raw aiosqlite (SQLite-only, own DDL, current approach) or migrate to wrapping DatabaseSessionService via SQLAlchemy (multi-dialect, free Postgres, but SQLAlchemy coupling).