@loomwork/plugin-sqlite 0.0.0-stage → 0.1.1

package/src/SqliteArchiveStore.ts

@@ -0,0 +1,189 @@
+import {
+  type ArchiveExecutionPage,
+  type ArchiveSegment,
+  type ArchiveSegmentHeader,
+  type ArchiveStore,
+  assertReplaceable,
+  classifyAppend,
+} from "@loomwork/event-runtime";
+import Database from "better-sqlite3";
+
+// ADR 0138 — the SQLite compaction archive. One row per segment, keyed (execution_id, from_seq).
+// The envelopes (and a sealing wrapper's `sealed` form) are stored as one JSON text; the header
+// fields are columns so `headers()` reads no bodies.
+
+interface Row {
+  from_seq: number;
+  through_seq: number;
+  count: number;
+  digest: string;
+  incarnation: string;
+  kind: string | null;
+  sender_digest: string | null;
+  body: string;
+}
+
+const kindOf = (k: string | null): Pick<ArchiveSegmentHeader, "kind"> =>
+  k === "legacy-checkpoint" ? { kind: "legacy-checkpoint" } : {};
+
+const senderOf = (d: string | null): Pick<ArchiveSegmentHeader, "senderDigest"> =>
+  d === null ? {} : { senderDigest: d };
+
+const toSegment = (r: Row): ArchiveSegment => {
+  const body = JSON.parse(r.body) as { envelopes: ArchiveSegment["envelopes"]; sealed?: unknown };
+  return {
+    from: r.from_seq,
+    through: r.through_seq,
+    count: r.count,
+    digest: r.digest,
+    incarnation: r.incarnation,
+    ...kindOf(r.kind),
+    ...senderOf(r.sender_digest),
+    envelopes: body.envelopes,
+    ...(body.sealed !== undefined && { sealed: body.sealed }),
+  };
+};
+
+export class SqliteArchiveStore implements ArchiveStore {
+  private readonly db: Database.Database;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    try {
+      this.db.pragma("journal_mode = WAL");
+      this.db.pragma("synchronous = NORMAL");
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS archive_segments (
+          execution_id TEXT NOT NULL,
+          from_seq INTEGER NOT NULL,
+          through_seq INTEGER NOT NULL,
+          count INTEGER NOT NULL,
+          digest TEXT NOT NULL,
+          incarnation TEXT NOT NULL,
+          kind TEXT,
+          sender_digest TEXT,
+          body TEXT NOT NULL,
+          PRIMARY KEY (execution_id, from_seq)
+        );
+      `);
+      // ADR 0139 N7: a table an earlier build created gains the column (CREATE IF NOT EXISTS never does).
+      const cols = this.db.prepare("PRAGMA table_info(archive_segments)").all() as Array<{
+        name: string;
+      }>;
+      if (!cols.some((c) => c.name === "sender_digest")) {
+        this.db.exec("ALTER TABLE archive_segments ADD COLUMN sender_digest TEXT");
+      }
+    } catch (err) {
+      this.db.close();
+      throw err;
+    }
+  }
+
+  async append(executionId: string, segment: ArchiveSegment): Promise<void> {
+    // One transaction: the classify read and the insert see the same rows.
+    const tx = this.db.transaction(() => {
+      const stored = this.headersSync(executionId);
+      if (classifyAppend(executionId, stored, segment) === "noop") return;
+      this.insert(executionId, segment);
+    });
+    tx.immediate();
+  }
+
+  private insert(executionId: string, segment: ArchiveSegment): void {
+    this.db
+      .prepare(
+        "INSERT INTO archive_segments (execution_id, from_seq, through_seq, count, digest, incarnation, kind, sender_digest, body) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+      )
+      .run(
+        executionId,
+        segment.from,
+        segment.through,
+        segment.count,
+        segment.digest,
+        segment.incarnation,
+        segment.kind ?? null,
+        segment.senderDigest ?? null,
+        JSON.stringify({
+          envelopes: segment.envelopes,
+          ...(segment.sealed !== undefined && { sealed: segment.sealed }),
+        })
+      );
+  }
+
+  /** ADR 0139 N1: one transaction - compare the headers, delete the key's segments, insert the new ones. */
+  async replaceSegments(
+    executionId: string,
+    expected: readonly ArchiveSegmentHeader[],
+    next: readonly ArchiveSegment[]
+  ): Promise<void> {
+    const tx = this.db.transaction(() => {
+      assertReplaceable(executionId, this.headersSync(executionId), expected, next);
+      this.db.prepare("DELETE FROM archive_segments WHERE execution_id = ?").run(executionId);
+      for (const seg of next) this.insert(executionId, seg);
+    });
+    tx.immediate();
+  }
+
+  private headersSync(executionId: string): ArchiveSegmentHeader[] {
+    return this.db
+      .prepare<[string], Omit<Row, "body">>(
+        "SELECT from_seq, through_seq, count, digest, incarnation, kind, sender_digest FROM archive_segments WHERE execution_id = ? ORDER BY from_seq"
+      )
+      .all(executionId)
+      .map((r) => ({
+        from: r.from_seq,
+        through: r.through_seq,
+        count: r.count,
+        digest: r.digest,
+        incarnation: r.incarnation,
+        ...kindOf(r.kind),
+        ...senderOf(r.sender_digest),
+      }));
+  }
+
+  async headers(executionId: string): Promise<ArchiveSegmentHeader[]> {
+    return this.headersSync(executionId);
+  }
+
+  async listExecutions(
+    opts: { cursor?: string; limit?: number } = {}
+  ): Promise<ArchiveExecutionPage> {
+    const limit = opts.limit ?? 500;
+    // BINARY collation = code point order for well-formed ids (the SPI's order).
+    const ids = this.db
+      .prepare<[string, number], { execution_id: string }>(
+        "SELECT DISTINCT execution_id FROM archive_segments WHERE execution_id > ? ORDER BY execution_id LIMIT ?"
+      )
+      .all(opts.cursor ?? "", limit + 1)
+      .map((r) => r.execution_id);
+    // An empty-string id sorts first and `> ''` would skip it; it names no execution, so that is moot.
+    const page = ids.slice(0, limit);
+    return ids.length > limit
+      ? { executionIds: page, nextCursor: page[page.length - 1]! }
+      : { executionIds: page };
+  }
+
+  async read(
+    executionId: string,
+    range: { readonly from?: number; readonly through?: number } = {}
+  ): Promise<ArchiveSegment[]> {
+    return this.db
+      .prepare<[string, number, number], Row>(
+        "SELECT * FROM archive_segments WHERE execution_id = ? AND through_seq >= ? AND from_seq <= ? ORDER BY from_seq"
+      )
+      .all(
+        executionId,
+        range.from ?? Number.MIN_SAFE_INTEGER,
+        range.through ?? Number.MAX_SAFE_INTEGER
+      )
+      .map(toSegment);
+  }
+
+  async deleteExecution(executionId: string): Promise<void> {
+    this.db.prepare("DELETE FROM archive_segments WHERE execution_id = ?").run(executionId);
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}

package/src/SqliteBranchRegistry.ts

@@ -0,0 +1,199 @@
+import {
+  BranchPromotionConflictError,
+  type BranchRef,
+  type BranchRegistry,
+  type LineageRecord,
+  type ListRefsOptions,
+  type PromoteOptions,
+  assertListRefsLimit,
+} from "@loomwork/event-runtime";
+import Database from "better-sqlite3";
+import { migrate } from "./schema";
+
+interface RefRow {
+  name: string;
+  execution_id: string;
+  tip: number;
+  parent_execution_id: string | null;
+  fork_sequence: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+interface LineageRow {
+  execution_id: string;
+  parent_execution_id: string;
+  fork_sequence: number;
+  created_at: number;
+}
+
+function rowToRef(row: RefRow): BranchRef {
+  return {
+    name: row.name,
+    executionId: row.execution_id,
+    tip: row.tip,
+    ...(row.parent_execution_id !== null && { parentExecutionId: row.parent_execution_id }),
+    ...(row.fork_sequence !== null && { forkSequence: row.fork_sequence }),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function rowToLineage(row: LineageRow): LineageRecord {
+  return {
+    executionId: row.execution_id,
+    parentExecutionId: row.parent_execution_id,
+    forkSequence: row.fork_sequence,
+    createdAt: row.created_at,
+  };
+}
+
+/**
+ * SQLite-backed {@link BranchRegistry}. Lives in @loomwork/event-runtime because
+ * refs describe event-log topology; point it at the same DB file as the
+ * SqliteEventStore (migrate() creates the `refs`/`lineage` tables idempotently).
+ */
+export class SqliteBranchRegistry implements BranchRegistry {
+  private readonly db: Database.Database;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    try {
+      this.db.pragma("journal_mode = WAL");
+      this.db.pragma("synchronous = NORMAL");
+      migrate(this.db);
+    } catch (err) {
+      this.db.close(); // don't leak the file handle if setup fails on a bad/locked file
+      throw err;
+    }
+  }
+
+  async putRef(ref: BranchRef): Promise<void> {
+    this.writeRef(ref);
+  }
+
+  /** Synchronous upsert — `putRef`'s body, callable from inside a transaction. */
+  private writeRef(ref: BranchRef): void {
+    this.db
+      .prepare<[string, string, number, string | null, number | null, number, number]>(`
+        INSERT INTO refs (name, execution_id, tip, parent_execution_id, fork_sequence, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(name) DO UPDATE SET
+          execution_id = excluded.execution_id,
+          tip = excluded.tip,
+          parent_execution_id = excluded.parent_execution_id,
+          fork_sequence = excluded.fork_sequence,
+          updated_at = excluded.updated_at
+      `)
+      .run(
+        ref.name,
+        ref.executionId,
+        ref.tip,
+        ref.parentExecutionId ?? null,
+        ref.forkSequence ?? null,
+        ref.createdAt,
+        ref.updatedAt
+      );
+  }
+
+  async getRef(name: string): Promise<BranchRef | null> {
+    const row = this.db.prepare<[string], RefRow>("SELECT * FROM refs WHERE name = ?").get(name);
+    return row ? rowToRef(row) : null;
+  }
+
+  async listRefs(options?: ListRefsOptions): Promise<BranchRef[]> {
+    assertListRefsLimit(options?.limit);
+    const after = options?.after ?? null;
+    // `LIMIT -1` is SQLite for "no limit", so the guard above is load-bearing: an
+    // unvalidated negative would return the whole table to a caller asking for a page.
+    const rows = this.db
+      .prepare<[string | null, string | null, number], RefRow>(
+        `SELECT * FROM refs
+          WHERE (? IS NULL OR name > ?)
+          ORDER BY name ASC
+          LIMIT ?`
+      )
+      .all(after, after, options?.limit ?? -1);
+    return rows.map(rowToRef);
+  }
+
+  async moveTip(name: string, tip: number): Promise<void> {
+    this.db
+      .prepare<[number, number, string]>("UPDATE refs SET tip = ?, updated_at = ? WHERE name = ?")
+      .run(tip, Date.now(), name);
+  }
+
+  async promote(fromName: string, toName: string, options?: PromoteOptions): Promise<void> {
+    // better-sqlite3 is synchronous, so wrapping the read-modify-write in a transaction
+    // makes the compare-and-set atomic against other connections to the same file.
+    const cas = options !== undefined && "expect" in options;
+    const expected = options?.expect ?? null;
+    const run = this.db.transaction(() => {
+      const from = this.readRef(fromName);
+      if (!from) {
+        throw new Error(`Cannot promote: ref "${fromName}" does not exist`);
+      }
+      const existing = this.readRef(toName);
+      if (cas) {
+        const actual = existing?.executionId ?? null;
+        if (actual !== expected) {
+          throw new BranchPromotionConflictError(toName, expected, actual);
+        }
+      }
+      const now = Date.now();
+      this.writeRef({
+        name: toName,
+        executionId: from.executionId,
+        tip: from.tip,
+        ...(from.parentExecutionId !== undefined && { parentExecutionId: from.parentExecutionId }),
+        ...(from.forkSequence !== undefined && { forkSequence: from.forkSequence }),
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+      });
+    });
+    run();
+  }
+
+  /** Synchronous ref read — the transaction body cannot await. */
+  private readRef(name: string): BranchRef | null {
+    const row = this.db.prepare<[string], RefRow>("SELECT * FROM refs WHERE name = ?").get(name);
+    return row ? rowToRef(row) : null;
+  }
+
+  async deleteRef(name: string): Promise<void> {
+    this.db.prepare<[string]>("DELETE FROM refs WHERE name = ?").run(name);
+  }
+
+  async recordLineage(rec: Omit<LineageRecord, "createdAt">): Promise<void> {
+    this.db
+      .prepare<[string, string, number, number]>(`
+        INSERT OR REPLACE INTO lineage (execution_id, parent_execution_id, fork_sequence, created_at)
+        VALUES (?, ?, ?, ?)
+      `)
+      .run(rec.executionId, rec.parentExecutionId, rec.forkSequence, Date.now());
+  }
+
+  async removeLineage(executionId: string): Promise<void> {
+    this.db.prepare<[string]>("DELETE FROM lineage WHERE execution_id = ?").run(executionId);
+  }
+
+  async getLineage(executionId: string): Promise<LineageRecord | null> {
+    const row = this.db
+      .prepare<[string], LineageRow>("SELECT * FROM lineage WHERE execution_id = ?")
+      .get(executionId);
+    return row ? rowToLineage(row) : null;
+  }
+
+  async children(executionId: string): Promise<LineageRecord[]> {
+    const rows = this.db
+      .prepare<[string], LineageRow>(
+        "SELECT * FROM lineage WHERE parent_execution_id = ? ORDER BY created_at ASC"
+      )
+      .all(executionId);
+    return rows.map(rowToLineage);
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}

package/src/SqliteContentStore.ts

@@ -0,0 +1,195 @@
+import { createHash } from "node:crypto";
+import {
+  type ContentListPage,
+  type ContentListPageOptions,
+  type ContentRef,
+  type ContentStore,
+  contentListPageLimit,
+} from "@loomwork/plugin-content";
+import Database from "better-sqlite3";
+
+/** Bind variables per `touch` UPDATE (SQLite builds cap at 999 on old versions). */
+const TOUCH_CHUNK = 500;
+
+/**
+ * SQLite-backed {@link ContentStore} (the first durable content backend —
+ * ADR 0046 deferred one "until a real requirement lands"; the db-copilot's
+ * evidence retention is that requirement, and `loom sweep content` needs a
+ * file-backed store to operate on). Content-addressed (`sha256:<hex>`),
+ * idempotent by hash, `putStream` per the ADR 0059 outcome contract
+ * (hash-while-spooling). Point it at its own file — blob I/O must not contend
+ * with event-append latency (TS-7 discipline).
+ *
+ * SPI 1.4.0 adds `touch` (a batched `UPDATE … RETURNING`). SPI 1.3.0 (ADR 0055 D5/D6): every blob carries `touched_at`, bumped by EVERY put (a dedup'd
+ * put is a re-citation), so `deleteIfUntouchedSince` is one conditional `DELETE` and
+ * `listPage` is a keyset scan on the `address` primary key. A pre-1.3.0 file is migrated on
+ * open: the column is added and existing blobs are backfilled to the migration time
+ * (conservative — none ages out until a full TTL after the upgrade).
+ */
+export interface SqliteContentStoreOptions {
+  /** Clock for touch times (epoch ms). Default `Date.now`. */
+  now?: () => number;
+}
+
+export class SqliteContentStore implements ContentStore {
+  private readonly db: Database.Database;
+  private readonly now: () => number;
+  private readonly insertStmt: Database.Statement;
+  private readonly getStmt: Database.Statement;
+  private readonly deleteStmt: Database.Statement;
+  private readonly deleteIfUntouchedStmt: Database.Statement;
+  private readonly pageStmt: Database.Statement;
+  private readonly pageBeforeStmt: Database.Statement;
+
+  constructor(dbPath: string, options: SqliteContentStoreOptions = {}) {
+    this.now = options.now ?? Date.now;
+    this.db = new Database(dbPath);
+    try {
+      this.db.pragma("journal_mode = WAL");
+      this.db.pragma("synchronous = NORMAL");
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS content_blobs (
+          address TEXT PRIMARY KEY,
+          bytes BLOB NOT NULL,
+          touched_at INTEGER NOT NULL DEFAULT 0
+        );
+      `);
+      this.migrateTouchedAt();
+      // Monotonic bump: a clock stepping back cannot make a re-cited blob look older.
+      this.insertStmt = this.db.prepare(
+        `INSERT INTO content_blobs (address, bytes, touched_at) VALUES (?, ?, ?)
+         ON CONFLICT(address) DO UPDATE SET touched_at = max(touched_at, excluded.touched_at)`
+      );
+      this.getStmt = this.db.prepare("SELECT bytes FROM content_blobs WHERE address = ?");
+      this.deleteStmt = this.db.prepare("DELETE FROM content_blobs WHERE address = ?");
+      this.deleteIfUntouchedStmt = this.db.prepare(
+        "DELETE FROM content_blobs WHERE address = ? AND touched_at < ?"
+      );
+      this.pageStmt = this.db.prepare(
+        `SELECT address, touched_at AS touchedAt FROM content_blobs
+         WHERE address > ? ORDER BY address LIMIT ?`
+      );
+      this.pageBeforeStmt = this.db.prepare(
+        `SELECT address, touched_at AS touchedAt FROM content_blobs
+         WHERE address > ? AND touched_at < ? ORDER BY address LIMIT ?`
+      );
+    } catch (err) {
+      this.db.close(); // don't leak the file handle if setup fails on a bad/locked file
+      throw err;
+    }
+  }
+
+  async put(bytes: Uint8Array): Promise<ContentRef> {
+    const address = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    this.insertStmt.run(address, Buffer.from(bytes), this.now());
+    return { __loomContent: address, size: bytes.byteLength };
+  }
+
+  async putStream(stream: AsyncIterable<Uint8Array>): Promise<ContentRef> {
+    // ADR 0059 outcome contract: address of the full sequence, idempotent —
+    // hash while spooling, then a single idempotent insert.
+    const hash = createHash("sha256");
+    const chunks: Buffer[] = [];
+    let size = 0;
+    for await (const chunk of stream) {
+      hash.update(chunk);
+      chunks.push(Buffer.from(chunk));
+      size += chunk.byteLength;
+    }
+    const address = `sha256:${hash.digest("hex")}`;
+    this.insertStmt.run(address, Buffer.concat(chunks, size), this.now());
+    return { __loomContent: address, size };
+  }
+
+  async get(ref: ContentRef): Promise<Uint8Array | null> {
+    const row = this.getStmt.get(ref.__loomContent) as { bytes: Buffer } | undefined;
+    return row === undefined ? null : new Uint8Array(row.bytes);
+  }
+
+  async delete(ref: ContentRef): Promise<void> {
+    this.deleteStmt.run(ref.__loomContent);
+  }
+
+  async deleteIfUntouchedSince(ref: ContentRef, cutoffMs: number): Promise<boolean> {
+    return this.deleteIfUntouchedStmt.run(ref.__loomContent, cutoffMs).changes > 0;
+  }
+
+  async touchClock(): Promise<number> {
+    return this.now();
+  }
+
+  /**
+   * SPI 1.4.0: bump `touched_at` for existing blobs without a put. One `UPDATE … WHERE address
+   * IN (…) RETURNING address` per chunk (bounded bind-variable count), all inside one
+   * transaction so a batch is all-or-nothing. `max()` keeps the time monotonic; an unknown
+   * address matches no row (no insert), and is reported back as missing.
+   */
+  /** One prepared `UPDATE` per distinct chunk size (at most {@link TOUCH_CHUNK} of them): a full chunk is prepared once, not per call. */
+  private readonly touchStatements = new Map<number, Database.Statement>();
+
+  private touchStatement(size: number): Database.Statement {
+    let statement = this.touchStatements.get(size);
+    if (statement === undefined) {
+      statement = this.db.prepare(
+        `UPDATE content_blobs SET touched_at = max(touched_at, ?)
+         WHERE address IN (${Array.from({ length: size }, () => "?").join(",")}) RETURNING address`
+      );
+      this.touchStatements.set(size, statement);
+    }
+    return statement;
+  }
+
+  async touch(addresses: readonly string[]): Promise<string[]> {
+    const unique = [...new Set(addresses)];
+    if (unique.length === 0) return [];
+    const touchedAt = this.now();
+    const present = new Set<string>();
+    this.db.transaction(() => {
+      for (let i = 0; i < unique.length; i += TOUCH_CHUNK) {
+        const chunk = unique.slice(i, i + TOUCH_CHUNK);
+        const rows = this.touchStatement(chunk.length).all(touchedAt, ...chunk) as {
+          address: string;
+        }[];
+        for (const row of rows) present.add(row.address);
+      }
+    })();
+    return unique.filter((a) => !present.has(a));
+  }
+
+  async listPage(opts: ContentListPageOptions = {}): Promise<ContentListPage> {
+    const limit = contentListPageLimit(opts.limit);
+    const after = opts.cursor ?? "";
+    const entries = (
+      opts.touchedBefore === undefined
+        ? this.pageStmt.all(after, limit)
+        : this.pageBeforeStmt.all(after, opts.touchedBefore, limit)
+    ) as { address: string; touchedAt: number }[];
+    const last = entries[entries.length - 1];
+    return entries.length === limit && last !== undefined
+      ? { entries, nextCursor: last.address }
+      : { entries };
+  }
+
+  /**
+   * One-time upgrade of a pre-1.3.0 file. IMMEDIATE so two processes opening the same file
+   * cannot both add the column; the re-check inside the transaction makes it idempotent.
+   */
+  private migrateTouchedAt(): void {
+    const hasColumn = (): boolean =>
+      (this.db.prepare("PRAGMA table_info(content_blobs)").all() as { name: string }[]).some(
+        (c) => c.name === "touched_at"
+      );
+    if (hasColumn()) return;
+    this.db
+      .transaction(() => {
+        if (hasColumn()) return;
+        this.db.exec("ALTER TABLE content_blobs ADD COLUMN touched_at INTEGER NOT NULL DEFAULT 0");
+        this.db.prepare("UPDATE content_blobs SET touched_at = ?").run(this.now());
+      })
+      .immediate();
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}

package/src/SqliteDurableStateStore.ts

@@ -0,0 +1,101 @@
+import type { DurableStateRecord, DurableStateStore } from "@loomwork/plugin-durable-state";
+import { RevisionConflictError } from "@loomwork/plugin-durable-state";
+import Database from "better-sqlite3";
+
+interface DurableStateRow {
+  contract_version: number;
+  revision: number;
+  payload: string;
+}
+
+/**
+ * SQLite-backed {@link DurableStateStore} (ADR 0051 D2). Point it at the same
+ * DB file as the SqliteEventStore so one backup captures events + carry state.
+ * Own idempotent migration, same pattern as SqliteTimerStore. CAS rides
+ * single-statement atomicity: the guarded INSERT/UPDATE either lands the new
+ * revision or changes nothing, and a zero-change outcome reports the actual
+ * revision in a loud RevisionConflictError.
+ */
+export class SqliteDurableStateStore implements DurableStateStore {
+  private readonly db: Database.Database;
+  private readonly loadStmt: Database.Statement;
+  private readonly insertStmt: Database.Statement;
+  private readonly updateStmt: Database.Statement;
+  private readonly revisionStmt: Database.Statement;
+  private readonly clearStmt: Database.Statement;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    try {
+      this.db.pragma("journal_mode = WAL");
+      this.db.pragma("synchronous = NORMAL");
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS durable_state (
+          key TEXT PRIMARY KEY,
+          contract_version INTEGER NOT NULL,
+          revision INTEGER NOT NULL,
+          payload TEXT NOT NULL
+        );
+      `);
+      this.loadStmt = this.db.prepare(
+        "SELECT contract_version, revision, payload FROM durable_state WHERE key = ?"
+      );
+      this.insertStmt = this.db.prepare(
+        "INSERT OR IGNORE INTO durable_state (key, contract_version, revision, payload) VALUES (?, ?, 1, ?)"
+      );
+      this.updateStmt = this.db.prepare(
+        "UPDATE durable_state SET contract_version = ?, revision = ?, payload = ? WHERE key = ? AND revision = ?"
+      );
+      this.revisionStmt = this.db.prepare("SELECT revision FROM durable_state WHERE key = ?");
+      this.clearStmt = this.db.prepare("DELETE FROM durable_state WHERE key = ?");
+    } catch (err) {
+      this.db.close(); // don't leak the file handle if setup fails on a bad/locked file
+      throw err;
+    }
+  }
+
+  async load(key: string): Promise<DurableStateRecord | null> {
+    const row = this.loadStmt.get(key) as DurableStateRow | undefined;
+    if (row === undefined) return null;
+    return {
+      contractVersion: row.contract_version,
+      revision: row.revision,
+      payload: JSON.parse(row.payload),
+    };
+  }
+
+  async save(
+    key: string,
+    value: { contractVersion: number; payload: unknown },
+    expectedRevision: number
+  ): Promise<DurableStateRecord> {
+    const payload = JSON.stringify(value.payload);
+    const changes =
+      expectedRevision === 0
+        ? this.insertStmt.run(key, value.contractVersion, payload).changes
+        : this.updateStmt.run(
+            value.contractVersion,
+            expectedRevision + 1,
+            payload,
+            key,
+            expectedRevision
+          ).changes;
+    if (changes === 1) {
+      return {
+        contractVersion: value.contractVersion,
+        revision: expectedRevision + 1,
+        payload: value.payload,
+      };
+    }
+    const row = this.revisionStmt.get(key) as { revision: number } | undefined;
+    throw new RevisionConflictError(key, expectedRevision, row?.revision ?? 0);
+  }
+
+  async clear(key: string): Promise<void> {
+    this.clearStmt.run(key);
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}