@intentface/latch-drizzle 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intentface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @intentface/latch-drizzle
+
+The persistence tier for Latch — a `StorageAdapter` and `SecretStore` implemented on **Drizzle** (libsql/SQLite first-class, Postgres alongside).
+
+## What it does
+
+- **`createSqliteAdapter` / (pg variant)** — the `StorageAdapter` the runtime persists through: chats, messages (the `AppMessage` source of truth), runs (status, leases, usage, cost incl. cached-token split), usage ledger, and schedules. Owner-keyed for org/user isolation (the `owner` fn derives the key from your `Principal`).
+- **`createSqliteSecretStore`** — the encrypted record store behind the core `Vault` (it never sees plaintext; the Vault wraps/unwraps).
+- **`migrate(client)`** — creates the `latch_*` tables (`CREATE TABLE IF NOT EXISTS`) plus idempotent `ALTER`s for columns added later (timezone, cached-token counts, …). Safe to run at startup; no migration tooling required.
+
+Tables: `latch_chats`, `latch_messages`, `latch_runs`, `latch_usage`, `latch_secrets`, `latch_schedules`.
+
+## Usage
+
+```ts
+import { createClient } from "@libsql/client";
+import { createSqliteAdapter, createSqliteSecretStore, migrate } from "@intentface/latch-drizzle";
+
+const client = createClient({ url: DATABASE_URL, authToken: TURSO_AUTH_TOKEN });
+await migrate(client);
+
+const owner = (p: Principal) => (p.userId ? [p.orgId, p.userId] : [p.orgId]);
+const storage = createSqliteAdapter<Principal>(client, { owner });
+```
+
+**Owner-key contract.** `owner` must be a pure projection of the *stable* part
+of your principal — durable ids from your database, never per-session state
+(an "active org" that can be null on some requests will silently split one
+user's data across two keys). The key is derived once, at root-resource
+creation; child rows inherit it. Never re-derive it from a live principal in
+a different request context (OAuth callbacks, webhooks, cron) — pin identity
+into the flow/run and rebuild it via `reconstructPrincipal` instead.
+
+## Where it fits
+
+The T1 (persistence) tier under `@intentface/latch-core`. Swap it for another `StorageAdapter` implementation behind the same contract.

package/dist/adapter.d.ts

@@ -0,0 +1,18 @@
+import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+import type { StorageAdapter } from "@intentface/latch-core";
+export { isUniqueViolation } from "./adapter.shared.js";
+export interface SqliteAdapterOptions<P> {
+    /**
+     * Derive the ownership key for a principal — the isolation boundary. Coarser
+     * (fewer segments) = more sharing; finer = more isolation. Must be
+     * server-derived from the authenticated principal, never client input.
+     */
+    owner: (principal: P) => string[];
+}
+/**
+ * A `StorageAdapter` on a Drizzle SQLite database (libsql / better-sqlite3 /
+ * Turso). The caller owns the connection — pass a `drizzle(...)` instance — so
+ * the adapter never opens or dialect-binds one itself.
+ */
+export declare function createSqliteAdapter<P>(db: BaseSQLiteDatabase<"sync" | "async", any, any>, opts: SqliteAdapterOptions<P>): StorageAdapter<P>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC;;;;OAIG;IACH,KAAK,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,EAAE,EAAE,kBAAkB,CAAC,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,EAClD,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5B,cAAc,CAAC,CAAC,CAAC,CAyBnB"}

package/dist/adapter.js

@@ -0,0 +1,33 @@
+import * as schema from "./schema.js";
+import { makeStorageAdapter } from "./adapter.shared.js";
+export { isUniqueViolation } from "./adapter.shared.js";
+/**
+ * A `StorageAdapter` on a Drizzle SQLite database (libsql / better-sqlite3 /
+ * Turso). The caller owns the connection — pass a `drizzle(...)` instance — so
+ * the adapter never opens or dialect-binds one itself.
+ */
+export function createSqliteAdapter(db, opts) {
+    return makeStorageAdapter(db, schema, {
+        owner: opts.owner,
+        // No interactive transaction: this adapter also serves synchronous drivers
+        // (better-sqlite3), whose transaction API rejects an async callback — and
+        // libsql opens a transaction on a NEW connection, which for an in-memory
+        // database is a new, empty database. Each INSERT computes its own seq
+        // atomically and the UNIQUE (chat_id, seq) index backstops a true race.
+        withTx: (fn) => fn(db),
+        // Atomicity where it matters (`openTurn`): drizzle's `batch` runs a list of
+        // independent statements in one transaction on libsql/Turso (local, memory
+        // and remote alike). better-sqlite3 has no batch → sequential fallback.
+        ...(typeof db.batch === "function"
+            ? {
+                batch: (stmts) => db.batch(stmts),
+            }
+            : {
+                // Synchronous driver (better-sqlite3, bun:sqlite): drizzle's sync
+                // `transaction` with the builders' `.run()` / `.get()` is a real
+                // transaction — `openTurn` uses it, so it is atomic here too.
+                syncTx: (fn) => db.transaction(fn),
+            }),
+    });
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAWxD;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,EAAkD,EAClD,IAA6B;IAE7B,OAAO,kBAAkB,CAAI,EAAE,EAAE,MAAM,EAAE;QACvC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,2EAA2E;QAC3E,0EAA0E;QAC1E,yEAAyE;QACzE,sEAAsE;QACtE,wEAAwE;QACxE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QACtB,4EAA4E;QAC5E,2EAA2E;QAC3E,wEAAwE;QACxE,GAAG,CAAC,OAAQ,EAAqC,CAAC,KAAK,KAAK,UAAU;YACpE,CAAC,CAAC;gBACE,KAAK,EAAE,CAAC,KAAgB,EAAE,EAAE,CACzB,EAA6D,CAAC,KAAK,CAAC,KAAc,CAAC;aACvF;YACH,CAAC,CAAC;gBACE,kEAAkE;gBAClE,iEAAiE;gBACjE,8DAA8D;gBAC9D,MAAM,EAAE,CAAK,EAAsB,EAAE,EAAE,CACpC,EAA+D,CAAC,WAAW,CAAC,EAAE,CAAC;aACnF,CAAC;KACP,CAAC,CAAC;AACL,CAAC"}

package/dist/adapter.pg.d.ts

@@ -0,0 +1,10 @@
+import type { PgDatabase } from "drizzle-orm/pg-core";
+import type { StorageAdapter } from "@intentface/latch-core";
+import type { SqliteAdapterOptions } from "./adapter.js";
+/**
+ * A `StorageAdapter` backed by Postgres. Pass a Drizzle pg database built from any
+ * driver — node-postgres / postgres-js in production, or PGlite for tests.
+ * Same contract + same query logic as the SQLite adapter (different dialect schema).
+ */
+export declare function createPostgresAdapter<P>(db: PgDatabase<any, any, any>, opts: SqliteAdapterOptions<P>): StorageAdapter<P>;
+//# sourceMappingURL=adapter.pg.d.ts.map

package/dist/adapter.pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.pg.d.ts","sourceRoot":"","sources":["../src/adapter.pg.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,EAAE,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC7B,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5B,cAAc,CAAC,CAAC,CAAC,CASnB"}

package/dist/adapter.pg.js

@@ -0,0 +1,18 @@
+import * as schema from "./schema.pg.js";
+import { makeStorageAdapter } from "./adapter.shared.js";
+/**
+ * A `StorageAdapter` backed by Postgres. Pass a Drizzle pg database built from any
+ * driver — node-postgres / postgres-js in production, or PGlite for tests.
+ * Same contract + same query logic as the SQLite adapter (different dialect schema).
+ */
+export function createPostgresAdapter(db, opts) {
+    return makeStorageAdapter(db, schema, {
+        owner: opts.owner,
+        // One transaction per message batch: the max(seq) reads and the inserts
+        // commit (or roll back) together, so a crash mid-batch can't leave a
+        // partial write and a concurrent appender can't interleave into the same
+        // seq range.
+        withTx: (fn) => db.transaction(fn),
+    });
+}
+//# sourceMappingURL=adapter.pg.js.map

package/dist/adapter.pg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.pg.js","sourceRoot":"","sources":["../src/adapter.pg.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,EAA6B,EAC7B,IAA6B;IAE7B,OAAO,kBAAkB,CAAI,EAAE,EAAE,MAAM,EAAE;QACvC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,wEAAwE;QACxE,qEAAqE;QACrE,yEAAyE;QACzE,aAAa;QACb,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC;KACnC,CAAC,CAAC;AACL,CAAC"}

package/dist/adapter.shared.d.ts

@@ -0,0 +1,55 @@
+import { type StorageAdapter } from "@intentface/latch-core";
+/**
+ * Dialect-shared `StorageAdapter` implementation. The SQLite and Postgres entry
+ * points (`adapter.ts`, `adapter.pg.ts`) pass their dialect's schema tables and
+ * a `withTx` — the only two things that differ. Every query below uses the
+ * common query-builder surface (insert / onConflictDoUpdate / update /
+ * returning), which both dialects support. Rows are typed structurally (`any`)
+ * for the same reason `memory-job-store.shared.ts` does: the two schemas are
+ * shape-identical but distinct types.
+ */
+/** The tables the adapter touches, in either dialect's schema. */
+export interface AdapterSchema {
+    chats: any;
+    messages: any;
+    runs: any;
+    usage: any;
+    schedules: any;
+}
+export interface SharedAdapterOptions<P> {
+    /**
+     * Derive the ownership key for a principal — the isolation boundary. Coarser
+     * (fewer segments) = more sharing; finer = more isolation. Must be
+     * server-derived from the authenticated principal, never client input.
+     */
+    owner: (principal: P) => string[];
+    /**
+     * Run a message batch as one unit. Postgres: `db.transaction`. SQLite:
+     * sequential on the same handle (synchronous drivers can't take the async
+     * callback).
+     */
+    withTx: <T>(fn: (tx: any) => Promise<T>) => Promise<T>;
+    /**
+     * Run independent statements in ONE transaction, returning each statement's
+     * result in order (drizzle `db.batch`). Preferred by `openTurn` where the
+     * dialect offers it and `withTx` isn't a real transaction (libsql).
+     */
+    batch?: (stmts: any[]) => Promise<any[]>;
+    /** A synchronous transaction (sync SQLite drivers): the builders' `.run()`/`.get()` inside it are atomic. */
+    syncTx?: <T>(fn: (tx: any) => T) => T;
+}
+/**
+ * True if a driver error is a primary-key / unique-constraint violation. Walks
+ * the cause chain: drizzle wraps driver errors in a "Failed query: …" error and
+ * the constraint code lives on the cause (libsql `SQLITE_CONSTRAINT_UNIQUE`, pg
+ * `23505`), two levels down for libsql.
+ */
+export declare function isUniqueViolation(error: unknown): boolean;
+/**
+ * How long a NON-durable (T1) active run may stay active before a new turn in
+ * its chat supersedes it. T1 has no heartbeat, so without this a crashed T1
+ * turn would block its chat forever. Durable runs use their lease instead.
+ */
+export declare const STALE_RUN_MS: number;
+export declare function makeStorageAdapter<P>(db: any, s: AdapterSchema, opts: SharedAdapterOptions<P>): StorageAdapter<P>;
+//# sourceMappingURL=adapter.shared.d.ts.map

package/dist/adapter.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.shared.d.ts","sourceRoot":"","sources":["../src/adapter.shared.ts"],"names":[],"mappings":"AAcA,OAAO,EAQL,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;GAQG;AAEH,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,GAAG,CAAC;IACX,QAAQ,EAAE,GAAG,CAAC;IACd,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,EAAE,GAAG,CAAC;IACX,SAAS,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC;;;;OAIG;IACH,KAAK,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC;IAClC;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACzC,6GAA6G;IAC7G,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CACvC;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAUzD;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAc,CAAC;AAOxC,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,EAAE,EAAE,GAAG,EACP,CAAC,EAAE,aAAa,EAChB,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5B,cAAc,CAAC,CAAC,CAAC,CAujBnB"}