# ADR-044: Drizzle-Honker Session Adapter

## Status

Accepted

## Context

Drizzle ORM provides typed query builders for SQLite via driver packages (`drizzle-orm/better-sqlite3`, `drizzle-orm/libsql`). Honker provides SQLite with pubsub/queue extensions but is not a Drizzle driver.

Running both simultaneously against the same `.db` file would require two separate connections, losing the transactional consistency that Honker provides (data writes + event notifications in one transaction).

## Decision

Implement a thin session adapter (~100 lines) that wraps Honker's Node.js `Database.query()`/`Transaction.execute()` API inside Drizzle's `SQLiteSession<'sync'>` contract. No Drizzle fork required.

The adapter implements:

- `HonkerSQLiteSession` — extends `SQLiteSession<'sync', HonkerRunResult, ...>`. Implements `prepareQuery()` and `transaction()`.
- `HonkerPreparedQuery` — extends `SQLitePreparedQuery`. Implements `run()`, `all()`, `get()`, `values()`.
- `HonkerSQLiteTransaction` — extends `SQLiteTransaction<'sync', ...>`. Provides `$honkerTx` for access to Honker's transaction methods.
- `drizzle(client, config)` — factory function that creates a Drizzle database instance from a Honker `Database`.

**Key integration points**:

- `prepareQuery()` delegates to `honkerDb.query(sql, params)` for reads and `tx.execute(sql, params)` for writes
- `transaction()` wraps honker's explicit begin/commit/rollback in Drizzle's callback pattern
- `$client` on the database instance exposes the Honker `Database` for `notify()`, `queue()`, `stream()`, `listen()`, `scheduler()`
- `$honkerTx` on the transaction object exposes the Honker `Transaction` for `notify()` and `enqueueTx()` within a Drizzle transaction callback
- `run()` returns `{ changes, lastInsertRowid }` where `lastInsertRowid` is obtained via `SELECT last_insert_rowid()` (pending a small Rust addition to honker-node for zero-overhead access)

**Usage**:

```typescript
import { open } from '@russellthehippo/honker-node';
import { drizzle } from '@alkdev/storage/sqlite/honker-adapter';
import * as schema from './schema';

const honkerDb = open('app.db');
const db = drizzle(honkerDb, { schema });

// Drizzle typed queries
const activeGraphs = db.select().from(schema.graphs)
  .where(eq(schema.graphs.status, 'active'));

// Honker + Drizzle in one transaction
db.transaction((tx) => {
  tx.insert(schema.nodes).values({ graphId, key: 'call-1', attributes: {} }).run();
  tx.$honkerTx.notify('graph:updated', { graphId });
});
```

## Consequences

**Positive:**

- Single connection — Drizzle queries and Honker pubsub/queue share the same SQLite file and transaction context
- No Drizzle fork — the adapter is consumer-side code (~100 lines)
- Full Drizzle type safety for all queries
- Full Honker feature access via `$client` and `$honkerTx`
- Transactional consistency: data writes and event notifications commit atomically
- The adapter could be open-sourced independently as `drizzle-honker` for community use

**Negative:**

- `lastInsertRowid` requires an extra query until honker-node adds a native method
- No prepared statement handle reuse at the JS level (mitigated by Rust-side `prepare_cached`)
- The adapter depends on Drizzle's internal SQLite session API path (`drizzle-orm/sqlite-core/session`) — if Drizzle restructures, the adapter needs updating
- Object-to-array conversion for Drizzle's `values()` method relies on JS object property insertion order, which matches SQLite column order but is a subtle dependency

## References

- Honker Node binding: `/workspace/honker/packages/honker-node/`
- Drizzle SQLite session: `/workspace/drizzle-orm/src/sqlite-core/session.ts`
- ADR-039: Honker as SQLite extension
- ADR-004: Injectable clients (adapter pattern is consistent)