@stateledger/drizzle 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enow Divine
+
+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,98 @@
+# @stateledger/drizzle
+
+Drizzle + Postgres adapter for [stateledger](https://github.com/enowdivine/stateledger) — persisted, audited, concurrency-safe state machines for Node/TypeScript.
+
+Works with any Drizzle Postgres driver: `node-postgres`, `postgres-js`, `neon-serverless`, `vercel-postgres`.
+
+## Install
+
+```sh
+pnpm add @stateledger/core @stateledger/drizzle drizzle-orm
+```
+
+Plus a Drizzle-compatible Postgres driver (`pg`, `postgres`, `@neondatabase/serverless`, or `@vercel/postgres`).
+
+## Apply the schema
+
+The library expects a `stateledger_transitions` table. Apply it however you migrate:
+
+```ts
+import { STATELEDGER_SCHEMA_SQL } from "@stateledger/drizzle";
+// paste into a migration file, or:
+import { sql } from "drizzle-orm";
+import { STATELEDGER_SCHEMA_STATEMENTS } from "@stateledger/drizzle";
+
+for (const stmt of STATELEDGER_SCHEMA_STATEMENTS) {
+  await db.execute(sql.raw(stmt));
+}
+```
+
+The DDL is identical to what `@stateledger/prisma` ships — same table, same indexes, same locking guarantees.
+
+## Use it
+
+```ts
+import { drizzle } from "drizzle-orm/node-postgres";
+import { defineMachine } from "@stateledger/core";
+import { createDrizzleAdapter } from "@stateledger/drizzle";
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const db = drizzle(pool);
+
+const adapter = createDrizzleAdapter(db);
+
+const payment = defineMachine({
+  name: "payment",
+  states: ["pending", "authorized", "captured", "failed"] as const,
+  transitions: {
+    pending:    { authorize: "authorized", fail: "failed" },
+    authorized: { capture: "captured", fail: "failed" },
+  },
+  adapter,
+});
+
+await payment.transition("pay_123", "authorize");
+const current = await payment.readState("pay_123");
+```
+
+## Options
+
+```ts
+createDrizzleAdapter(db, {
+  tableName: "stateledger_transitions",   // default; override for multi-tenant setups
+  locking: "pessimistic",                 // default; use "optimistic" to skip pg_advisory_xact_lock
+});
+```
+
+- **`pessimistic`** (default) — uses `pg_advisory_xact_lock(hashtextextended(machine:subject, 0))` per transition. Concurrent writers wait their turn.
+- **`optimistic`** — skips the advisory lock and relies on the partial unique index on `most_recent`. Faster under low contention. Caller must catch `OptimisticConcurrencyError` and retry.
+
+## Joining an existing transaction
+
+Pass a Drizzle transaction context in place of the top-level client:
+
+```ts
+await db.transaction(async (tx) => {
+  await stripe.paymentIntents.create(...);   // your business logic
+  const adapter = createDrizzleAdapter(tx);  // joins the outer tx
+  const machine = defineMachine({ ..., adapter });
+  await machine.transition("pay_123", "authorize");
+});
+```
+
+## Contract-conformant
+
+Passes the same 13-spec [`@stateledger/core/contract-tests`](https://github.com/enowdivine/stateledger/blob/main/packages/core/src/contract-tests.ts) suite as `@stateledger/prisma` — reads, appends, rollback, `most_recent` flip invariants, cross-subject independence, and time-travel semantics.
+
+Run it locally:
+
+```sh
+pnpm --filter @stateledger/drizzle test:integration
+```
+
+Requires Docker (uses `testcontainers` to boot a real Postgres).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,266 @@
+'use strict';
+
+var core = require('@stateledger/core');
+var drizzleOrm = require('drizzle-orm');
+
+// src/adapter.ts
+var DEFAULT_TABLE = "stateledger_transitions";
+var DrizzleAdapter = class {
+  constructor(root, options = {}) {
+    this.root = root;
+    this.tableName = options.tableName ?? DEFAULT_TABLE;
+    this.locking = options.locking ?? "pessimistic";
+    assertValidIdentifier(this.tableName);
+  }
+  root;
+  tableName;
+  locking;
+  async withTransaction(fn) {
+    if (hasTransactionMethod(this.root)) {
+      return this.root.transaction((tx) => fn(tx));
+    }
+    return fn(this.root);
+  }
+  async acquireLock(tx, machine, subjectId) {
+    if (this.locking === "optimistic") return;
+    const key = `${machine}:${subjectId}`;
+    try {
+      await tx.execute(drizzleOrm.sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
+    } catch (err) {
+      throw new core.AdapterError(
+        `[${machine}] ${subjectId}: failed to acquire advisory lock`,
+        { cause: err }
+      );
+    }
+  }
+  async readCurrent(tx, machine, subjectId) {
+    try {
+      const result = await tx.execute(
+        drizzleOrm.sql`SELECT * FROM ${drizzleOrm.sql.identifier(this.tableName)}
+              WHERE machine = ${machine}
+                AND subject_id = ${subjectId}
+                AND most_recent = TRUE
+              LIMIT 1`
+      );
+      const rows = extractRows(result);
+      const row = rows[0];
+      return row ? mapRow(row) : null;
+    } catch (err) {
+      throw new core.AdapterError(
+        `[${machine}] ${subjectId}: readCurrent failed`,
+        { cause: err }
+      );
+    }
+  }
+  async appendTransition(tx, row) {
+    try {
+      await tx.execute(
+        drizzleOrm.sql`UPDATE ${drizzleOrm.sql.identifier(this.tableName)}
+               SET most_recent = FALSE
+             WHERE machine = ${row.machine}
+               AND subject_id = ${row.subjectId}
+               AND most_recent = TRUE`
+      );
+      const metadataJson = JSON.stringify(row.metadata ?? {});
+      const result = await tx.execute(
+        drizzleOrm.sql`INSERT INTO ${drizzleOrm.sql.identifier(this.tableName)} (
+              machine, subject_id, from_state, to_state, sort_key, most_recent,
+              actor_id, actor_type, metadata, machine_version
+            ) VALUES (
+              ${row.machine}, ${row.subjectId}, ${row.fromState}, ${row.toState},
+              ${row.sortKey}, ${row.mostRecent},
+              ${row.actorId}, ${row.actorType}, ${metadataJson}::jsonb, ${row.machineVersion}
+            )
+            RETURNING *`
+      );
+      const rows = extractRows(result);
+      const created = rows[0];
+      if (!created) {
+        throw new core.AdapterError(
+          `[${row.machine}] ${row.subjectId}: INSERT returned no rows`
+        );
+      }
+      return mapRow(created);
+    } catch (err) {
+      if (isUniqueViolation(err)) {
+        throw new core.OptimisticConcurrencyError(row.machine, row.subjectId);
+      }
+      if (err instanceof core.AdapterError || err instanceof core.OptimisticConcurrencyError) {
+        throw err;
+      }
+      throw new core.AdapterError(
+        `[${row.machine}] ${row.subjectId}: appendTransition failed`,
+        { cause: err }
+      );
+    }
+  }
+  async readHistory(tx, machine, subjectId) {
+    const client = tx ?? this.root;
+    try {
+      const result = await client.execute(
+        drizzleOrm.sql`SELECT * FROM ${drizzleOrm.sql.identifier(this.tableName)}
+              WHERE machine = ${machine}
+                AND subject_id = ${subjectId}
+              ORDER BY sort_key ASC`
+      );
+      return extractRows(result).map(mapRow);
+    } catch (err) {
+      throw new core.AdapterError(
+        `[${machine}] ${subjectId}: readHistory failed`,
+        { cause: err }
+      );
+    }
+  }
+  async readStateAt(tx, machine, subjectId, at) {
+    const client = tx ?? this.root;
+    try {
+      const result = await client.execute(
+        drizzleOrm.sql`SELECT * FROM ${drizzleOrm.sql.identifier(this.tableName)}
+              WHERE machine = ${machine}
+                AND subject_id = ${subjectId}
+                AND created_at <= ${at}
+              ORDER BY sort_key DESC
+              LIMIT 1`
+      );
+      const rows = extractRows(result);
+      const row = rows[0];
+      return row ? mapRow(row) : null;
+    } catch (err) {
+      throw new core.AdapterError(
+        `[${machine}] ${subjectId}: readStateAt failed`,
+        { cause: err }
+      );
+    }
+  }
+  async updateSubjectState(tx, hint, newState) {
+    const model = stringField(hint, "model");
+    const column = stringField(hint, "column") ?? "state";
+    const where = hint["where"];
+    if (!model) {
+      throw new core.AdapterError(
+        "updateSubjectState: subjectStateColumn.model is required (Postgres table name)"
+      );
+    }
+    if (!where || typeof where !== "object") {
+      throw new core.AdapterError(
+        "updateSubjectState: subjectStateColumn.where is required (object of identifying columns)"
+      );
+    }
+    assertValidIdentifier(model);
+    assertValidIdentifier(column);
+    const whereObj = where;
+    const keys = Object.keys(whereObj);
+    if (keys.length === 0) {
+      throw new core.AdapterError(
+        "updateSubjectState: subjectStateColumn.where must have at least one column"
+      );
+    }
+    for (const key of keys) assertValidIdentifier(key);
+    const whereFragments = keys.map(
+      (k) => drizzleOrm.sql`${drizzleOrm.sql.identifier(k)} = ${whereObj[k]}`
+    );
+    const whereSql = drizzleOrm.sql.join(whereFragments, drizzleOrm.sql` AND `);
+    try {
+      await tx.execute(
+        drizzleOrm.sql`UPDATE ${drizzleOrm.sql.identifier(model)}
+               SET ${drizzleOrm.sql.identifier(column)} = ${newState}
+             WHERE ${whereSql}`
+      );
+    } catch (err) {
+      throw new core.AdapterError(
+        `updateSubjectState failed for ${model}.${column}`,
+        { cause: err }
+      );
+    }
+  }
+};
+function createDrizzleAdapter(client, options) {
+  return new DrizzleAdapter(client, options);
+}
+function hasTransactionMethod(client) {
+  return typeof client.transaction === "function";
+}
+function extractRows(result) {
+  if (Array.isArray(result)) return result;
+  if (result && typeof result === "object" && "rows" in result && Array.isArray(result.rows)) {
+    return result.rows;
+  }
+  throw new core.AdapterError(
+    "Unexpected execute() result shape: expected an array or an object with `.rows`. Is this a Drizzle Postgres client?"
+  );
+}
+function isUniqueViolation(err) {
+  if (!err || typeof err !== "object") return false;
+  const e = err;
+  if (e.code === "23505") return true;
+  if (e.cause && typeof e.cause === "object" && e.cause.code === "23505") {
+    return true;
+  }
+  if (e.original && typeof e.original === "object" && e.original.code === "23505") {
+    return true;
+  }
+  return false;
+}
+function mapRow(raw) {
+  return {
+    id: raw.id,
+    machine: raw.machine,
+    subjectId: raw.subject_id,
+    fromState: raw.from_state,
+    toState: raw.to_state,
+    sortKey: Number(raw.sort_key),
+    mostRecent: raw.most_recent,
+    actorId: raw.actor_id,
+    actorType: raw.actor_type,
+    metadata: raw.metadata ?? {},
+    machineVersion: Number(raw.machine_version),
+    createdAt: raw.created_at instanceof Date ? raw.created_at : new Date(raw.created_at)
+  };
+}
+function stringField(obj, key) {
+  const v = obj[key];
+  return typeof v === "string" ? v : null;
+}
+function assertValidIdentifier(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new core.AdapterError(
+      `invalid SQL identifier: ${JSON.stringify(name)} (must match /^[A-Za-z_][A-Za-z0-9_]*$/)`
+    );
+  }
+}
+
+// src/schema-sql.ts
+var STATELEDGER_SCHEMA_STATEMENTS = [
+  `CREATE TABLE IF NOT EXISTS "stateledger_transitions" (
+    id               UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+    machine          TEXT         NOT NULL,
+    subject_id       TEXT         NOT NULL,
+    from_state       TEXT,
+    to_state         TEXT         NOT NULL,
+    sort_key         INTEGER      NOT NULL,
+    most_recent      BOOLEAN      NOT NULL DEFAULT TRUE,
+    actor_id         TEXT,
+    actor_type       TEXT,
+    metadata         JSONB        NOT NULL DEFAULT '{}'::jsonb,
+    machine_version  INTEGER      NOT NULL DEFAULT 1,
+    created_at       TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+  )`,
+  // Deterministic ordering for history reads + the (machine, subject) lookup.
+  `CREATE UNIQUE INDEX IF NOT EXISTS "stateledger_transitions_subject_sort_key"
+    ON "stateledger_transitions" (machine, subject_id, sort_key)`,
+  // Partial unique index: exactly one mostRecent row per (machine, subject).
+  // This is the optimistic-concurrency safety net + a hard correctness invariant.
+  `CREATE UNIQUE INDEX IF NOT EXISTS "stateledger_transitions_one_most_recent"
+    ON "stateledger_transitions" (machine, subject_id)
+    WHERE most_recent = TRUE`,
+  // "Recent transitions for this subject, newest first" — covers history pagination.
+  `CREATE INDEX IF NOT EXISTS "stateledger_transitions_history"
+    ON "stateledger_transitions" (machine, subject_id, sort_key DESC)`
+];
+var STATELEDGER_SCHEMA_SQL = STATELEDGER_SCHEMA_STATEMENTS.join(";\n\n") + ";";
+
+exports.STATELEDGER_SCHEMA_SQL = STATELEDGER_SCHEMA_SQL;
+exports.STATELEDGER_SCHEMA_STATEMENTS = STATELEDGER_SCHEMA_STATEMENTS;
+exports.createDrizzleAdapter = createDrizzleAdapter;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapter.ts","../src/schema-sql.ts"],"names":["sql","AdapterError","OptimisticConcurrencyError"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Drizzle adapter implementation for stateledger.\n *\n * All persistence goes through Drizzle's `execute()` + `sql`` `` template.\n * The adapter doesn't require the user to have added a `stateledger`\n * schema definition to their `drizzle` schema file — only the underlying\n * `stateledger_transitions` table (see `./schema-sql.ts`).\n *\n * Structural typing means any Drizzle Postgres client (node-postgres,\n * postgres.js, neon-serverless) satisfies the `DrizzleDb` contract via\n * duck typing.\n */\n\nimport type {\n  Adapter,\n  NewTransitionRow,\n  SubjectStateHint,\n  TransitionRow,\n} from \"@stateledger/core\";\nimport { AdapterError, OptimisticConcurrencyError } from \"@stateledger/core\";\nimport { sql } from \"drizzle-orm\";\n\nimport type {\n  DrizzleAdapterOptions,\n  DrizzleDb,\n  DrizzleExecutor,\n  DrizzleTransactionalClient,\n} from \"./types.js\";\n\nconst DEFAULT_TABLE = \"stateledger_transitions\";\n\n/**\n * Raw row shape returned by Postgres before we map to `TransitionRow`.\n */\ntype RawTransitionRow = {\n  id: string;\n  machine: string;\n  subject_id: string;\n  from_state: string | null;\n  to_state: string;\n  sort_key: number | bigint | string;\n  most_recent: boolean;\n  actor_id: string | null;\n  actor_type: string | null;\n  metadata: Record<string, unknown> | null;\n  machine_version: number | bigint | string;\n  created_at: Date | string;\n};\n\nclass DrizzleAdapter implements Adapter<DrizzleExecutor> {\n  private readonly tableName: string;\n  private readonly locking: \"pessimistic\" | \"optimistic\";\n\n  constructor(\n    private readonly root: DrizzleDb,\n    options: DrizzleAdapterOptions = {},\n  ) {\n    this.tableName = options.tableName ?? DEFAULT_TABLE;\n    this.locking = options.locking ?? \"pessimistic\";\n    assertValidIdentifier(this.tableName);\n  }\n\n  async withTransaction<R>(fn: (tx: DrizzleExecutor) => Promise<R>): Promise<R> {\n    if (hasTransactionMethod(this.root)) {\n      return this.root.transaction((tx: DrizzleExecutor) => fn(tx));\n    }\n    // Already inside a transaction context — just call the fn with it.\n    return fn(this.root);\n  }\n\n  async acquireLock(\n    tx: DrizzleExecutor,\n    machine: string,\n    subjectId: string,\n  ): Promise<void> {\n    if (this.locking === \"optimistic\") return;\n    const key = `${machine}:${subjectId}`;\n    try {\n      // `hashtextextended` returns bigint, which `pg_advisory_xact_lock`\n      // accepts. The lock auto-releases when the surrounding transaction\n      // ends — no explicit unlock is needed (or possible).\n      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`);\n    } catch (err) {\n      throw new AdapterError(\n        `[${machine}] ${subjectId}: failed to acquire advisory lock`,\n        { cause: err },\n      );\n    }\n  }\n\n  async readCurrent(\n    tx: DrizzleExecutor,\n    machine: string,\n    subjectId: string,\n  ): Promise<TransitionRow | null> {\n    try {\n      const result = await tx.execute<unknown>(\n        sql`SELECT * FROM ${sql.identifier(this.tableName)}\n              WHERE machine = ${machine}\n                AND subject_id = ${subjectId}\n                AND most_recent = TRUE\n              LIMIT 1`,\n      );\n      const rows = extractRows<RawTransitionRow>(result);\n      const row = rows[0];\n      return row ? mapRow(row) : null;\n    } catch (err) {\n      throw new AdapterError(\n        `[${machine}] ${subjectId}: readCurrent failed`,\n        { cause: err },\n      );\n    }\n  }\n\n  async appendTransition(\n    tx: DrizzleExecutor,\n    row: NewTransitionRow,\n  ): Promise<TransitionRow> {\n    try {\n      // Flip the previous mostRecent row (no-op for the bootstrap transition).\n      await tx.execute(\n        sql`UPDATE ${sql.identifier(this.tableName)}\n               SET most_recent = FALSE\n             WHERE machine = ${row.machine}\n               AND subject_id = ${row.subjectId}\n               AND most_recent = TRUE`,\n      );\n\n      // Insert the new row and return it. `metadata` is JSON-encoded here\n      // because Drizzle's raw execute doesn't stringify objects for JSONB.\n      const metadataJson = JSON.stringify(row.metadata ?? {});\n      const result = await tx.execute<unknown>(\n        sql`INSERT INTO ${sql.identifier(this.tableName)} (\n              machine, subject_id, from_state, to_state, sort_key, most_recent,\n              actor_id, actor_type, metadata, machine_version\n            ) VALUES (\n              ${row.machine}, ${row.subjectId}, ${row.fromState}, ${row.toState},\n              ${row.sortKey}, ${row.mostRecent},\n              ${row.actorId}, ${row.actorType}, ${metadataJson}::jsonb, ${row.machineVersion}\n            )\n            RETURNING *`,\n      );\n\n      const rows = extractRows<RawTransitionRow>(result);\n      const created = rows[0];\n      if (!created) {\n        throw new AdapterError(\n          `[${row.machine}] ${row.subjectId}: INSERT returned no rows`,\n        );\n      }\n      return mapRow(created);\n    } catch (err) {\n      // The partial unique index on (machine, subject_id) WHERE most_recent = TRUE\n      // surfaces lost optimistic races as a unique-constraint violation.\n      if (isUniqueViolation(err)) {\n        throw new OptimisticConcurrencyError(row.machine, row.subjectId);\n      }\n      // Re-throw our own errors as-is so callers can match on them.\n      if (err instanceof AdapterError || err instanceof OptimisticConcurrencyError) {\n        throw err;\n      }\n      throw new AdapterError(\n        `[${row.machine}] ${row.subjectId}: appendTransition failed`,\n        { cause: err },\n      );\n    }\n  }\n\n  async readHistory(\n    tx: DrizzleExecutor | null,\n    machine: string,\n    subjectId: string,\n  ): Promise<TransitionRow[]> {\n    const client = tx ?? this.root;\n    try {\n      const result = await client.execute<unknown>(\n        sql`SELECT * FROM ${sql.identifier(this.tableName)}\n              WHERE machine = ${machine}\n                AND subject_id = ${subjectId}\n              ORDER BY sort_key ASC`,\n      );\n      return extractRows<RawTransitionRow>(result).map(mapRow);\n    } catch (err) {\n      throw new AdapterError(\n        `[${machine}] ${subjectId}: readHistory failed`,\n        { cause: err },\n      );\n    }\n  }\n\n  async readStateAt(\n    tx: DrizzleExecutor | null,\n    machine: string,\n    subjectId: string,\n    at: Date,\n  ): Promise<TransitionRow | null> {\n    const client = tx ?? this.root;\n    try {\n      // Most recent transition row whose created_at <= cutoff. Order by\n      // sort_key DESC (not created_at DESC) for the tiebreak — sortKey is\n      // monotonic per (machine, subjectId) and is the canonical ordering\n      // used everywhere else in the library.\n      const result = await client.execute<unknown>(\n        sql`SELECT * FROM ${sql.identifier(this.tableName)}\n              WHERE machine = ${machine}\n                AND subject_id = ${subjectId}\n                AND created_at <= ${at}\n              ORDER BY sort_key DESC\n              LIMIT 1`,\n      );\n      const rows = extractRows<RawTransitionRow>(result);\n      const row = rows[0];\n      return row ? mapRow(row) : null;\n    } catch (err) {\n      throw new AdapterError(\n        `[${machine}] ${subjectId}: readStateAt failed`,\n        { cause: err },\n      );\n    }\n  }\n\n  async updateSubjectState(\n    tx: DrizzleExecutor,\n    hint: SubjectStateHint,\n    newState: string,\n  ): Promise<void> {\n    const model = stringField(hint, \"model\");\n    const column = stringField(hint, \"column\") ?? \"state\";\n    const where = hint[\"where\"];\n\n    if (!model) {\n      throw new AdapterError(\n        \"updateSubjectState: subjectStateColumn.model is required (Postgres table name)\",\n      );\n    }\n    if (!where || typeof where !== \"object\") {\n      throw new AdapterError(\n        \"updateSubjectState: subjectStateColumn.where is required (object of identifying columns)\",\n      );\n    }\n\n    assertValidIdentifier(model);\n    assertValidIdentifier(column);\n\n    const whereObj = where as Record<string, unknown>;\n    const keys = Object.keys(whereObj);\n    if (keys.length === 0) {\n      throw new AdapterError(\n        \"updateSubjectState: subjectStateColumn.where must have at least one column\",\n      );\n    }\n    for (const key of keys) assertValidIdentifier(key);\n\n    // Build the parameterized WHERE fragment via sql.join so each column\n    // stays parameterized (no string concatenation of user values into\n    // raw SQL).\n    const whereFragments = keys.map(\n      (k) => sql`${sql.identifier(k)} = ${whereObj[k]}`,\n    );\n    const whereSql = sql.join(whereFragments, sql` AND `);\n\n    try {\n      await tx.execute(\n        sql`UPDATE ${sql.identifier(model)}\n               SET ${sql.identifier(column)} = ${newState}\n             WHERE ${whereSql}`,\n      );\n    } catch (err) {\n      throw new AdapterError(\n        `updateSubjectState failed for ${model}.${column}`,\n        { cause: err },\n      );\n    }\n  }\n}\n\n/**\n * Create an adapter bound to a Drizzle client.\n *\n * Pass a top-level Drizzle client for typical use — the adapter will open\n * its own transactions via `db.transaction()`. Pass a Drizzle transaction\n * context to join an existing transaction the caller opened higher up\n * the stack.\n */\nexport function createDrizzleAdapter(\n  client: DrizzleDb,\n  options?: DrizzleAdapterOptions,\n): Adapter<DrizzleExecutor> {\n  return new DrizzleAdapter(client, options);\n}\n\n// ---- internal helpers ----\n\nfunction hasTransactionMethod(client: DrizzleDb): client is DrizzleTransactionalClient {\n  return typeof (client as DrizzleTransactionalClient).transaction === \"function\";\n}\n\n/**\n * Normalize `execute()` output across Drizzle's Postgres drivers.\n *\n * - `drizzle-orm/node-postgres`: returns pg's `QueryResult` — `{ rows: T[] }`.\n * - `drizzle-orm/postgres-js`: returns a `RowList<T>` that IS a `T[]` (with\n *   extra properties like `.count`).\n * - `drizzle-orm/neon-serverless`: also `{ rows: T[] }` (uses pg protocol).\n */\nfunction extractRows<T>(result: unknown): T[] {\n  if (Array.isArray(result)) return result as T[];\n  if (\n    result &&\n    typeof result === \"object\" &&\n    \"rows\" in result &&\n    Array.isArray((result as { rows?: unknown }).rows)\n  ) {\n    return (result as { rows: T[] }).rows;\n  }\n  throw new AdapterError(\n    \"Unexpected execute() result shape: expected an array or an object with `.rows`. \" +\n      \"Is this a Drizzle Postgres client?\",\n  );\n}\n\n/**\n * Detect \"unique constraint violation\" from the Postgres driver error.\n * All Postgres drivers surface SQLSTATE `23505`; some (pg) put it on\n * `.code`, some (postgres.js) on `.code` too, node-postgres nests it\n * further in some setups. Check every plausible location.\n */\nfunction isUniqueViolation(err: unknown): boolean {\n  if (!err || typeof err !== \"object\") return false;\n  const e = err as {\n    code?: unknown;\n    cause?: { code?: unknown } | null;\n    original?: { code?: unknown } | null;\n  };\n  if (e.code === \"23505\") return true;\n  if (e.cause && typeof e.cause === \"object\" && (e.cause as { code?: unknown }).code === \"23505\") {\n    return true;\n  }\n  if (\n    e.original &&\n    typeof e.original === \"object\" &&\n    (e.original as { code?: unknown }).code === \"23505\"\n  ) {\n    return true;\n  }\n  return false;\n}\n\nfunction mapRow(raw: RawTransitionRow): TransitionRow {\n  return {\n    id: raw.id,\n    machine: raw.machine,\n    subjectId: raw.subject_id,\n    fromState: raw.from_state,\n    toState: raw.to_state,\n    sortKey: Number(raw.sort_key),\n    mostRecent: raw.most_recent,\n    actorId: raw.actor_id,\n    actorType: raw.actor_type,\n    metadata: raw.metadata ?? {},\n    machineVersion: Number(raw.machine_version),\n    createdAt: raw.created_at instanceof Date ? raw.created_at : new Date(raw.created_at),\n  };\n}\n\nfunction stringField(obj: Record<string, unknown>, key: string): string | null {\n  const v = obj[key];\n  return typeof v === \"string\" ? v : null;\n}\n\n/**\n * Reject table/column names that aren't safe to interpolate into raw SQL.\n *\n * `sql.identifier()` already quotes identifiers to make injection hard,\n * but we still validate at the boundary so misconfigured hints fail loud\n * and early instead of at query time.\n */\nfunction assertValidIdentifier(name: string): void {\n  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {\n    throw new AdapterError(\n      `invalid SQL identifier: ${JSON.stringify(name)} (must match /^[A-Za-z_][A-Za-z0-9_]*$/)`,\n    );\n  }\n}\n","/**\n * Recommended Postgres schema for the transitions table.\n *\n * Exported in two shapes:\n *\n * - `STATELEDGER_SCHEMA_STATEMENTS`: an array of individual DDL statements.\n *   Use this when applying the schema through a driver that runs one\n *   statement at a time.\n * - `STATELEDGER_SCHEMA_SQL`: the same statements concatenated into one\n *   multi-statement script. Use this when writing a Drizzle migration\n *   (`drizzle-kit generate`) or any tool that accepts multi-statement input.\n *\n * The SQL here is identical to what `@stateledger/prisma` ships. It's\n * duplicated intentionally: the two adapters have separate release\n * cadences, and the SQL is ORM-agnostic Postgres DDL that shouldn't\n * change often. If it needs to change, both adapters must be bumped in\n * lockstep.\n */\n\nexport const STATELEDGER_SCHEMA_STATEMENTS: readonly string[] = [\n  `CREATE TABLE IF NOT EXISTS \"stateledger_transitions\" (\n    id               UUID         PRIMARY KEY DEFAULT gen_random_uuid(),\n    machine          TEXT         NOT NULL,\n    subject_id       TEXT         NOT NULL,\n    from_state       TEXT,\n    to_state         TEXT         NOT NULL,\n    sort_key         INTEGER      NOT NULL,\n    most_recent      BOOLEAN      NOT NULL DEFAULT TRUE,\n    actor_id         TEXT,\n    actor_type       TEXT,\n    metadata         JSONB        NOT NULL DEFAULT '{}'::jsonb,\n    machine_version  INTEGER      NOT NULL DEFAULT 1,\n    created_at       TIMESTAMPTZ  NOT NULL DEFAULT NOW()\n  )`,\n\n  // Deterministic ordering for history reads + the (machine, subject) lookup.\n  `CREATE UNIQUE INDEX IF NOT EXISTS \"stateledger_transitions_subject_sort_key\"\n    ON \"stateledger_transitions\" (machine, subject_id, sort_key)`,\n\n  // Partial unique index: exactly one mostRecent row per (machine, subject).\n  // This is the optimistic-concurrency safety net + a hard correctness invariant.\n  `CREATE UNIQUE INDEX IF NOT EXISTS \"stateledger_transitions_one_most_recent\"\n    ON \"stateledger_transitions\" (machine, subject_id)\n    WHERE most_recent = TRUE`,\n\n  // \"Recent transitions for this subject, newest first\" — covers history pagination.\n  `CREATE INDEX IF NOT EXISTS \"stateledger_transitions_history\"\n    ON \"stateledger_transitions\" (machine, subject_id, sort_key DESC)`,\n];\n\nexport const STATELEDGER_SCHEMA_SQL: string = STATELEDGER_SCHEMA_STATEMENTS.join(\";\\n\\n\") + \";\";\n"]}

package/dist/index.d.cts

@@ -0,0 +1,124 @@
+import { Adapter } from '@stateledger/core';
+
+/**
+ * Public types for the Drizzle adapter.
+ *
+ * The adapter does NOT import Drizzle's driver-specific types at the type
+ * boundary — Drizzle has separate flavors (`drizzle-orm/node-postgres`,
+ * `drizzle-orm/postgres-js`, `drizzle-orm/neon-serverless`, etc.), each
+ * with a slightly different `execute()` return shape. We define the
+ * minimal structural surface the adapter actually uses; any Drizzle
+ * Postgres client satisfies it via duck typing.
+ *
+ * The `sql` template tag is imported from `drizzle-orm` at value level —
+ * users install `drizzle-orm` as a peer, so it's always available.
+ */
+/**
+ * Minimal interface for any Drizzle Postgres client capable of executing
+ * a raw SQL fragment. `execute()`'s return shape varies by driver — for
+ * `drizzle-orm/node-postgres` it's `{ rows: T[] }` (pg's `QueryResult`),
+ * for `drizzle-orm/postgres-js` it's `T[]` directly. Both are unwrapped
+ * by the adapter internally.
+ */
+type DrizzleExecutor = {
+    execute<T = unknown>(query: any): Promise<T>;
+};
+/**
+ * Minimal interface for a top-level Drizzle client (capable of opening a
+ * transaction). Drizzle's `db.transaction(async (tx) => …)` calls back with
+ * a scoped client that still exposes `execute()` — that's the `tx` we hand
+ * on to the adapter's methods.
+ */
+type DrizzleTransactionalClient = DrizzleExecutor & {
+    transaction<R>(fn: (tx: any) => Promise<R>): Promise<R>;
+};
+/**
+ * What `createDrizzleAdapter` accepts: either a top-level Drizzle client
+ * (and we open our own transactions) or a Drizzle transaction context
+ * (and we join the caller's transaction).
+ */
+type DrizzleDb = DrizzleTransactionalClient | DrizzleExecutor;
+type DrizzleAdapterOptions = {
+    /**
+     * Postgres table that holds the transition rows. Defaults to
+     * `stateledger_transitions`. Override if you've namespaced it (e.g. per
+     * tenant schema, or to avoid a collision in a legacy database).
+     */
+    tableName?: string;
+    /**
+     * Locking strategy.
+     * - `"pessimistic"` (default): `pg_advisory_xact_lock` per
+     *   `(machine, subjectId)`. Concurrent writers wait their turn.
+     * - `"optimistic"`: skip the advisory lock; rely on the partial unique
+     *   index on `most_recent` to detect lost races. Caller must catch
+     *   `OptimisticConcurrencyError` and retry.
+     */
+    locking?: "pessimistic" | "optimistic";
+};
+/**
+ * Shape of the optional `subjectStateColumn` hint passed to
+ * `updateSubjectState`.
+ *
+ * Example (for a Drizzle `payments` table with `id` primary key):
+ * ```ts
+ * subjectStateColumn: {
+ *   model: "payments",         // Postgres table name
+ *   where: { id: payment.id }, // identifying columns
+ *   column: "state",           // column to update
+ * }
+ * ```
+ */
+type DrizzleSubjectStateHint = {
+    /** Postgres table name. */
+    model: string;
+    /** Columns to identify the row. */
+    where: Record<string, string | number | boolean>;
+    /** Column to write the new state into. Defaults to `state`. */
+    column?: string;
+};
+
+/**
+ * Drizzle adapter implementation for stateledger.
+ *
+ * All persistence goes through Drizzle's `execute()` + `sql`` `` template.
+ * The adapter doesn't require the user to have added a `stateledger`
+ * schema definition to their `drizzle` schema file — only the underlying
+ * `stateledger_transitions` table (see `./schema-sql.ts`).
+ *
+ * Structural typing means any Drizzle Postgres client (node-postgres,
+ * postgres.js, neon-serverless) satisfies the `DrizzleDb` contract via
+ * duck typing.
+ */
+
+/**
+ * Create an adapter bound to a Drizzle client.
+ *
+ * Pass a top-level Drizzle client for typical use — the adapter will open
+ * its own transactions via `db.transaction()`. Pass a Drizzle transaction
+ * context to join an existing transaction the caller opened higher up
+ * the stack.
+ */
+declare function createDrizzleAdapter(client: DrizzleDb, options?: DrizzleAdapterOptions): Adapter<DrizzleExecutor>;
+
+/**
+ * Recommended Postgres schema for the transitions table.
+ *
+ * Exported in two shapes:
+ *
+ * - `STATELEDGER_SCHEMA_STATEMENTS`: an array of individual DDL statements.
+ *   Use this when applying the schema through a driver that runs one
+ *   statement at a time.
+ * - `STATELEDGER_SCHEMA_SQL`: the same statements concatenated into one
+ *   multi-statement script. Use this when writing a Drizzle migration
+ *   (`drizzle-kit generate`) or any tool that accepts multi-statement input.
+ *
+ * The SQL here is identical to what `@stateledger/prisma` ships. It's
+ * duplicated intentionally: the two adapters have separate release
+ * cadences, and the SQL is ORM-agnostic Postgres DDL that shouldn't
+ * change often. If it needs to change, both adapters must be bumped in
+ * lockstep.
+ */
+declare const STATELEDGER_SCHEMA_STATEMENTS: readonly string[];
+declare const STATELEDGER_SCHEMA_SQL: string;
+
+export { type DrizzleAdapterOptions, type DrizzleDb, type DrizzleExecutor, type DrizzleSubjectStateHint, type DrizzleTransactionalClient, STATELEDGER_SCHEMA_SQL, STATELEDGER_SCHEMA_STATEMENTS, createDrizzleAdapter };

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import { Adapter } from '@stateledger/core';
+
+/**
+ * Public types for the Drizzle adapter.
+ *
+ * The adapter does NOT import Drizzle's driver-specific types at the type
+ * boundary — Drizzle has separate flavors (`drizzle-orm/node-postgres`,
+ * `drizzle-orm/postgres-js`, `drizzle-orm/neon-serverless`, etc.), each
+ * with a slightly different `execute()` return shape. We define the
+ * minimal structural surface the adapter actually uses; any Drizzle
+ * Postgres client satisfies it via duck typing.
+ *
+ * The `sql` template tag is imported from `drizzle-orm` at value level —
+ * users install `drizzle-orm` as a peer, so it's always available.
+ */
+/**
+ * Minimal interface for any Drizzle Postgres client capable of executing
+ * a raw SQL fragment. `execute()`'s return shape varies by driver — for
+ * `drizzle-orm/node-postgres` it's `{ rows: T[] }` (pg's `QueryResult`),
+ * for `drizzle-orm/postgres-js` it's `T[]` directly. Both are unwrapped
+ * by the adapter internally.
+ */
+type DrizzleExecutor = {
+    execute<T = unknown>(query: any): Promise<T>;
+};
+/**
+ * Minimal interface for a top-level Drizzle client (capable of opening a
+ * transaction). Drizzle's `db.transaction(async (tx) => …)` calls back with
+ * a scoped client that still exposes `execute()` — that's the `tx` we hand
+ * on to the adapter's methods.
+ */
+type DrizzleTransactionalClient = DrizzleExecutor & {
+    transaction<R>(fn: (tx: any) => Promise<R>): Promise<R>;
+};
+/**
+ * What `createDrizzleAdapter` accepts: either a top-level Drizzle client
+ * (and we open our own transactions) or a Drizzle transaction context
+ * (and we join the caller's transaction).
+ */
+type DrizzleDb = DrizzleTransactionalClient | DrizzleExecutor;
+type DrizzleAdapterOptions = {
+    /**
+     * Postgres table that holds the transition rows. Defaults to
+     * `stateledger_transitions`. Override if you've namespaced it (e.g. per
+     * tenant schema, or to avoid a collision in a legacy database).
+     */
+    tableName?: string;
+    /**
+     * Locking strategy.
+     * - `"pessimistic"` (default): `pg_advisory_xact_lock` per
+     *   `(machine, subjectId)`. Concurrent writers wait their turn.
+     * - `"optimistic"`: skip the advisory lock; rely on the partial unique
+     *   index on `most_recent` to detect lost races. Caller must catch
+     *   `OptimisticConcurrencyError` and retry.
+     */
+    locking?: "pessimistic" | "optimistic";
+};
+/**
+ * Shape of the optional `subjectStateColumn` hint passed to
+ * `updateSubjectState`.
+ *
+ * Example (for a Drizzle `payments` table with `id` primary key):
+ * ```ts
+ * subjectStateColumn: {
+ *   model: "payments",         // Postgres table name
+ *   where: { id: payment.id }, // identifying columns
+ *   column: "state",           // column to update
+ * }
+ * ```
+ */
+type DrizzleSubjectStateHint = {
+    /** Postgres table name. */
+    model: string;
+    /** Columns to identify the row. */
+    where: Record<string, string | number | boolean>;
+    /** Column to write the new state into. Defaults to `state`. */
+    column?: string;
+};
+
+/**
+ * Drizzle adapter implementation for stateledger.
+ *
+ * All persistence goes through Drizzle's `execute()` + `sql`` `` template.
+ * The adapter doesn't require the user to have added a `stateledger`
+ * schema definition to their `drizzle` schema file — only the underlying
+ * `stateledger_transitions` table (see `./schema-sql.ts`).
+ *
+ * Structural typing means any Drizzle Postgres client (node-postgres,
+ * postgres.js, neon-serverless) satisfies the `DrizzleDb` contract via
+ * duck typing.
+ */
+
+/**
+ * Create an adapter bound to a Drizzle client.
+ *
+ * Pass a top-level Drizzle client for typical use — the adapter will open
+ * its own transactions via `db.transaction()`. Pass a Drizzle transaction
+ * context to join an existing transaction the caller opened higher up
+ * the stack.
+ */
+declare function createDrizzleAdapter(client: DrizzleDb, options?: DrizzleAdapterOptions): Adapter<DrizzleExecutor>;
+
+/**
+ * Recommended Postgres schema for the transitions table.
+ *
+ * Exported in two shapes:
+ *
+ * - `STATELEDGER_SCHEMA_STATEMENTS`: an array of individual DDL statements.
+ *   Use this when applying the schema through a driver that runs one
+ *   statement at a time.
+ * - `STATELEDGER_SCHEMA_SQL`: the same statements concatenated into one
+ *   multi-statement script. Use this when writing a Drizzle migration
+ *   (`drizzle-kit generate`) or any tool that accepts multi-statement input.
+ *
+ * The SQL here is identical to what `@stateledger/prisma` ships. It's
+ * duplicated intentionally: the two adapters have separate release
+ * cadences, and the SQL is ORM-agnostic Postgres DDL that shouldn't
+ * change often. If it needs to change, both adapters must be bumped in
+ * lockstep.
+ */
+declare const STATELEDGER_SCHEMA_STATEMENTS: readonly string[];
+declare const STATELEDGER_SCHEMA_SQL: string;
+
+export { type DrizzleAdapterOptions, type DrizzleDb, type DrizzleExecutor, type DrizzleSubjectStateHint, type DrizzleTransactionalClient, STATELEDGER_SCHEMA_SQL, STATELEDGER_SCHEMA_STATEMENTS, createDrizzleAdapter };

package/dist/index.js

@@ -0,0 +1,262 @@
+import { AdapterError, OptimisticConcurrencyError } from '@stateledger/core';
+import { sql } from 'drizzle-orm';
+
+// src/adapter.ts
+var DEFAULT_TABLE = "stateledger_transitions";
+var DrizzleAdapter = class {
+  constructor(root, options = {}) {
+    this.root = root;
+    this.tableName = options.tableName ?? DEFAULT_TABLE;
+    this.locking = options.locking ?? "pessimistic";
+    assertValidIdentifier(this.tableName);
+  }
+  root;
+  tableName;
+  locking;
+  async withTransaction(fn) {
+    if (hasTransactionMethod(this.root)) {
+      return this.root.transaction((tx) => fn(tx));
+    }
+    return fn(this.root);
+  }
+  async acquireLock(tx, machine, subjectId) {
+    if (this.locking === "optimistic") return;
+    const key = `${machine}:${subjectId}`;
+    try {
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
+    } catch (err) {
+      throw new AdapterError(
+        `[${machine}] ${subjectId}: failed to acquire advisory lock`,
+        { cause: err }
+      );
+    }
+  }
+  async readCurrent(tx, machine, subjectId) {
+    try {
+      const result = await tx.execute(
+        sql`SELECT * FROM ${sql.identifier(this.tableName)}
+              WHERE machine = ${machine}
+                AND subject_id = ${subjectId}
+                AND most_recent = TRUE
+              LIMIT 1`
+      );
+      const rows = extractRows(result);
+      const row = rows[0];
+      return row ? mapRow(row) : null;
+    } catch (err) {
+      throw new AdapterError(
+        `[${machine}] ${subjectId}: readCurrent failed`,
+        { cause: err }
+      );
+    }
+  }
+  async appendTransition(tx, row) {
+    try {
+      await tx.execute(
+        sql`UPDATE ${sql.identifier(this.tableName)}
+               SET most_recent = FALSE
+             WHERE machine = ${row.machine}
+               AND subject_id = ${row.subjectId}
+               AND most_recent = TRUE`
+      );
+      const metadataJson = JSON.stringify(row.metadata ?? {});
+      const result = await tx.execute(
+        sql`INSERT INTO ${sql.identifier(this.tableName)} (
+              machine, subject_id, from_state, to_state, sort_key, most_recent,
+              actor_id, actor_type, metadata, machine_version
+            ) VALUES (
+              ${row.machine}, ${row.subjectId}, ${row.fromState}, ${row.toState},
+              ${row.sortKey}, ${row.mostRecent},
+              ${row.actorId}, ${row.actorType}, ${metadataJson}::jsonb, ${row.machineVersion}
+            )
+            RETURNING *`
+      );
+      const rows = extractRows(result);
+      const created = rows[0];
+      if (!created) {
+        throw new AdapterError(
+          `[${row.machine}] ${row.subjectId}: INSERT returned no rows`
+        );
+      }
+      return mapRow(created);
+    } catch (err) {
+      if (isUniqueViolation(err)) {
+        throw new OptimisticConcurrencyError(row.machine, row.subjectId);
+      }
+      if (err instanceof AdapterError || err instanceof OptimisticConcurrencyError) {
+        throw err;
+      }
+      throw new AdapterError(
+        `[${row.machine}] ${row.subjectId}: appendTransition failed`,
+        { cause: err }
+      );
+    }
+  }
+  async readHistory(tx, machine, subjectId) {
+    const client = tx ?? this.root;
+    try {
+      const result = await client.execute(
+        sql`SELECT * FROM ${sql.identifier(this.tableName)}
+              WHERE machine = ${machine}
+                AND subject_id = ${subjectId}
+              ORDER BY sort_key ASC`
+      );
+      return extractRows(result).map(mapRow);
+    } catch (err) {
+      throw new AdapterError(
+        `[${machine}] ${subjectId}: readHistory failed`,
+        { cause: err }
+      );
+    }
+  }
+  async readStateAt(tx, machine, subjectId, at) {
+    const client = tx ?? this.root;
+    try {
+      const result = await client.execute(
+        sql`SELECT * FROM ${sql.identifier(this.tableName)}
+              WHERE machine = ${machine}
+                AND subject_id = ${subjectId}
+                AND created_at <= ${at}
+              ORDER BY sort_key DESC
+              LIMIT 1`
+      );
+      const rows = extractRows(result);
+      const row = rows[0];
+      return row ? mapRow(row) : null;
+    } catch (err) {
+      throw new AdapterError(
+        `[${machine}] ${subjectId}: readStateAt failed`,
+        { cause: err }
+      );
+    }
+  }
+  async updateSubjectState(tx, hint, newState) {
+    const model = stringField(hint, "model");
+    const column = stringField(hint, "column") ?? "state";
+    const where = hint["where"];
+    if (!model) {
+      throw new AdapterError(
+        "updateSubjectState: subjectStateColumn.model is required (Postgres table name)"
+      );
+    }
+    if (!where || typeof where !== "object") {
+      throw new AdapterError(
+        "updateSubjectState: subjectStateColumn.where is required (object of identifying columns)"
+      );
+    }
+    assertValidIdentifier(model);
+    assertValidIdentifier(column);
+    const whereObj = where;
+    const keys = Object.keys(whereObj);
+    if (keys.length === 0) {
+      throw new AdapterError(
+        "updateSubjectState: subjectStateColumn.where must have at least one column"
+      );
+    }
+    for (const key of keys) assertValidIdentifier(key);
+    const whereFragments = keys.map(
+      (k) => sql`${sql.identifier(k)} = ${whereObj[k]}`
+    );
+    const whereSql = sql.join(whereFragments, sql` AND `);
+    try {
+      await tx.execute(
+        sql`UPDATE ${sql.identifier(model)}
+               SET ${sql.identifier(column)} = ${newState}
+             WHERE ${whereSql}`
+      );
+    } catch (err) {
+      throw new AdapterError(
+        `updateSubjectState failed for ${model}.${column}`,
+        { cause: err }
+      );
+    }
+  }
+};
+function createDrizzleAdapter(client, options) {
+  return new DrizzleAdapter(client, options);
+}
+function hasTransactionMethod(client) {
+  return typeof client.transaction === "function";
+}
+function extractRows(result) {
+  if (Array.isArray(result)) return result;
+  if (result && typeof result === "object" && "rows" in result && Array.isArray(result.rows)) {
+    return result.rows;
+  }
+  throw new AdapterError(
+    "Unexpected execute() result shape: expected an array or an object with `.rows`. Is this a Drizzle Postgres client?"
+  );
+}
+function isUniqueViolation(err) {
+  if (!err || typeof err !== "object") return false;
+  const e = err;
+  if (e.code === "23505") return true;
+  if (e.cause && typeof e.cause === "object" && e.cause.code === "23505") {
+    return true;
+  }
+  if (e.original && typeof e.original === "object" && e.original.code === "23505") {
+    return true;
+  }
+  return false;
+}
+function mapRow(raw) {
+  return {
+    id: raw.id,
+    machine: raw.machine,
+    subjectId: raw.subject_id,
+    fromState: raw.from_state,
+    toState: raw.to_state,
+    sortKey: Number(raw.sort_key),
+    mostRecent: raw.most_recent,
+    actorId: raw.actor_id,
+    actorType: raw.actor_type,
+    metadata: raw.metadata ?? {},
+    machineVersion: Number(raw.machine_version),
+    createdAt: raw.created_at instanceof Date ? raw.created_at : new Date(raw.created_at)
+  };
+}
+function stringField(obj, key) {
+  const v = obj[key];
+  return typeof v === "string" ? v : null;
+}
+function assertValidIdentifier(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new AdapterError(
+      `invalid SQL identifier: ${JSON.stringify(name)} (must match /^[A-Za-z_][A-Za-z0-9_]*$/)`
+    );
+  }
+}
+
+// src/schema-sql.ts
+var STATELEDGER_SCHEMA_STATEMENTS = [
+  `CREATE TABLE IF NOT EXISTS "stateledger_transitions" (
+    id               UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+    machine          TEXT         NOT NULL,
+    subject_id       TEXT         NOT NULL,
+    from_state       TEXT,
+    to_state         TEXT         NOT NULL,
+    sort_key         INTEGER      NOT NULL,
+    most_recent      BOOLEAN      NOT NULL DEFAULT TRUE,
+    actor_id         TEXT,
+    actor_type       TEXT,
+    metadata         JSONB        NOT NULL DEFAULT '{}'::jsonb,
+    machine_version  INTEGER      NOT NULL DEFAULT 1,
+    created_at       TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+  )`,
+  // Deterministic ordering for history reads + the (machine, subject) lookup.
+  `CREATE UNIQUE INDEX IF NOT EXISTS "stateledger_transitions_subject_sort_key"
+    ON "stateledger_transitions" (machine, subject_id, sort_key)`,
+  // Partial unique index: exactly one mostRecent row per (machine, subject).
+  // This is the optimistic-concurrency safety net + a hard correctness invariant.
+  `CREATE UNIQUE INDEX IF NOT EXISTS "stateledger_transitions_one_most_recent"
+    ON "stateledger_transitions" (machine, subject_id)
+    WHERE most_recent = TRUE`,
+  // "Recent transitions for this subject, newest first" — covers history pagination.
+  `CREATE INDEX IF NOT EXISTS "stateledger_transitions_history"
+    ON "stateledger_transitions" (machine, subject_id, sort_key DESC)`
+];
+var STATELEDGER_SCHEMA_SQL = STATELEDGER_SCHEMA_STATEMENTS.join(";\n\n") + ";";
+
+export { STATELEDGER_SCHEMA_SQL, STATELEDGER_SCHEMA_STATEMENTS, createDrizzleAdapter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapter.ts","../src/schema-sql.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Drizzle adapter implementation for stateledger.\n *\n * All persistence goes through Drizzle's `execute()` + `sql`` `` template.\n * The adapter doesn't require the user to have added a `stateledger`\n * schema definition to their `drizzle` schema file — only the underlying\n * `stateledger_transitions` table (see `./schema-sql.ts`).\n *\n * Structural typing means any Drizzle Postgres client (node-postgres,\n * postgres.js, neon-serverless) satisfies the `DrizzleDb` contract via\n * duck typing.\n */\n\nimport type {\n  Adapter,\n  NewTransitionRow,\n  SubjectStateHint,\n  TransitionRow,\n} from \"@stateledger/core\";\nimport { AdapterError, OptimisticConcurrencyError } from \"@stateledger/core\";\nimport { sql } from \"drizzle-orm\";\n\nimport type {\n  DrizzleAdapterOptions,\n  DrizzleDb,\n  DrizzleExecutor,\n  DrizzleTransactionalClient,\n} from \"./types.js\";\n\nconst DEFAULT_TABLE = \"stateledger_transitions\";\n\n/**\n * Raw row shape returned by Postgres before we map to `TransitionRow`.\n */\ntype RawTransitionRow = {\n  id: string;\n  machine: string;\n  subject_id: string;\n  from_state: string | null;\n  to_state: string;\n  sort_key: number | bigint | string;\n  most_recent: boolean;\n  actor_id: string | null;\n  actor_type: string | null;\n  metadata: Record<string, unknown> | null;\n  machine_version: number | bigint | string;\n  created_at: Date | string;\n};\n\nclass DrizzleAdapter implements Adapter<DrizzleExecutor> {\n  private readonly tableName: string;\n  private readonly locking: \"pessimistic\" | \"optimistic\";\n\n  constructor(\n    private readonly root: DrizzleDb,\n    options: DrizzleAdapterOptions = {},\n  ) {\n    this.tableName = options.tableName ?? DEFAULT_TABLE;\n    this.locking = options.locking ?? \"pessimistic\";\n    assertValidIdentifier(this.tableName);\n  }\n\n  async withTransaction<R>(fn: (tx: DrizzleExecutor) => Promise<R>): Promise<R> {\n    if (hasTransactionMethod(this.root)) {\n      return this.root.transaction((tx: DrizzleExecutor) => fn(tx));\n    }\n    // Already inside a transaction context — just call the fn with it.\n    return fn(this.root);\n  }\n\n  async acquireLock(\n    tx: DrizzleExecutor,\n    machine: string,\n    subjectId: string,\n  ): Promise<void> {\n    if (this.locking === \"optimistic\") return;\n    const key = `${machine}:${subjectId}`;\n    try {\n      // `hashtextextended` returns bigint, which `pg_advisory_xact_lock`\n      // accepts. The lock auto-releases when the surrounding transaction\n      // ends — no explicit unlock is needed (or possible).\n      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`);\n    } catch (err) {\n      throw new AdapterError(\n        `[${machine}] ${subjectId}: failed to acquire advisory lock`,\n        { cause: err },\n      );\n    }\n  }\n\n  async readCurrent(\n    tx: DrizzleExecutor,\n    machine: string,\n    subjectId: string,\n  ): Promise<TransitionRow | null> {\n    try {\n      const result = await tx.execute<unknown>(\n        sql`SELECT * FROM ${sql.identifier(this.tableName)}\n              WHERE machine = ${machine}\n                AND subject_id = ${subjectId}\n                AND most_recent = TRUE\n              LIMIT 1`,\n      );\n      const rows = extractRows<RawTransitionRow>(result);\n      const row = rows[0];\n      return row ? mapRow(row) : null;\n    } catch (err) {\n      throw new AdapterError(\n        `[${machine}] ${subjectId}: readCurrent failed`,\n        { cause: err },\n      );\n    }\n  }\n\n  async appendTransition(\n    tx: DrizzleExecutor,\n    row: NewTransitionRow,\n  ): Promise<TransitionRow> {\n    try {\n      // Flip the previous mostRecent row (no-op for the bootstrap transition).\n      await tx.execute(\n        sql`UPDATE ${sql.identifier(this.tableName)}\n               SET most_recent = FALSE\n             WHERE machine = ${row.machine}\n               AND subject_id = ${row.subjectId}\n               AND most_recent = TRUE`,\n      );\n\n      // Insert the new row and return it. `metadata` is JSON-encoded here\n      // because Drizzle's raw execute doesn't stringify objects for JSONB.\n      const metadataJson = JSON.stringify(row.metadata ?? {});\n      const result = await tx.execute<unknown>(\n        sql`INSERT INTO ${sql.identifier(this.tableName)} (\n              machine, subject_id, from_state, to_state, sort_key, most_recent,\n              actor_id, actor_type, metadata, machine_version\n            ) VALUES (\n              ${row.machine}, ${row.subjectId}, ${row.fromState}, ${row.toState},\n              ${row.sortKey}, ${row.mostRecent},\n              ${row.actorId}, ${row.actorType}, ${metadataJson}::jsonb, ${row.machineVersion}\n            )\n            RETURNING *`,\n      );\n\n      const rows = extractRows<RawTransitionRow>(result);\n      const created = rows[0];\n      if (!created) {\n        throw new AdapterError(\n          `[${row.machine}] ${row.subjectId}: INSERT returned no rows`,\n        );\n      }\n      return mapRow(created);\n    } catch (err) {\n      // The partial unique index on (machine, subject_id) WHERE most_recent = TRUE\n      // surfaces lost optimistic races as a unique-constraint violation.\n      if (isUniqueViolation(err)) {\n        throw new OptimisticConcurrencyError(row.machine, row.subjectId);\n      }\n      // Re-throw our own errors as-is so callers can match on them.\n      if (err instanceof AdapterError || err instanceof OptimisticConcurrencyError) {\n        throw err;\n      }\n      throw new AdapterError(\n        `[${row.machine}] ${row.subjectId}: appendTransition failed`,\n        { cause: err },\n      );\n    }\n  }\n\n  async readHistory(\n    tx: DrizzleExecutor | null,\n    machine: string,\n    subjectId: string,\n  ): Promise<TransitionRow[]> {\n    const client = tx ?? this.root;\n    try {\n      const result = await client.execute<unknown>(\n        sql`SELECT * FROM ${sql.identifier(this.tableName)}\n              WHERE machine = ${machine}\n                AND subject_id = ${subjectId}\n              ORDER BY sort_key ASC`,\n      );\n      return extractRows<RawTransitionRow>(result).map(mapRow);\n    } catch (err) {\n      throw new AdapterError(\n        `[${machine}] ${subjectId}: readHistory failed`,\n        { cause: err },\n      );\n    }\n  }\n\n  async readStateAt(\n    tx: DrizzleExecutor | null,\n    machine: string,\n    subjectId: string,\n    at: Date,\n  ): Promise<TransitionRow | null> {\n    const client = tx ?? this.root;\n    try {\n      // Most recent transition row whose created_at <= cutoff. Order by\n      // sort_key DESC (not created_at DESC) for the tiebreak — sortKey is\n      // monotonic per (machine, subjectId) and is the canonical ordering\n      // used everywhere else in the library.\n      const result = await client.execute<unknown>(\n        sql`SELECT * FROM ${sql.identifier(this.tableName)}\n              WHERE machine = ${machine}\n                AND subject_id = ${subjectId}\n                AND created_at <= ${at}\n              ORDER BY sort_key DESC\n              LIMIT 1`,\n      );\n      const rows = extractRows<RawTransitionRow>(result);\n      const row = rows[0];\n      return row ? mapRow(row) : null;\n    } catch (err) {\n      throw new AdapterError(\n        `[${machine}] ${subjectId}: readStateAt failed`,\n        { cause: err },\n      );\n    }\n  }\n\n  async updateSubjectState(\n    tx: DrizzleExecutor,\n    hint: SubjectStateHint,\n    newState: string,\n  ): Promise<void> {\n    const model = stringField(hint, \"model\");\n    const column = stringField(hint, \"column\") ?? \"state\";\n    const where = hint[\"where\"];\n\n    if (!model) {\n      throw new AdapterError(\n        \"updateSubjectState: subjectStateColumn.model is required (Postgres table name)\",\n      );\n    }\n    if (!where || typeof where !== \"object\") {\n      throw new AdapterError(\n        \"updateSubjectState: subjectStateColumn.where is required (object of identifying columns)\",\n      );\n    }\n\n    assertValidIdentifier(model);\n    assertValidIdentifier(column);\n\n    const whereObj = where as Record<string, unknown>;\n    const keys = Object.keys(whereObj);\n    if (keys.length === 0) {\n      throw new AdapterError(\n        \"updateSubjectState: subjectStateColumn.where must have at least one column\",\n      );\n    }\n    for (const key of keys) assertValidIdentifier(key);\n\n    // Build the parameterized WHERE fragment via sql.join so each column\n    // stays parameterized (no string concatenation of user values into\n    // raw SQL).\n    const whereFragments = keys.map(\n      (k) => sql`${sql.identifier(k)} = ${whereObj[k]}`,\n    );\n    const whereSql = sql.join(whereFragments, sql` AND `);\n\n    try {\n      await tx.execute(\n        sql`UPDATE ${sql.identifier(model)}\n               SET ${sql.identifier(column)} = ${newState}\n             WHERE ${whereSql}`,\n      );\n    } catch (err) {\n      throw new AdapterError(\n        `updateSubjectState failed for ${model}.${column}`,\n        { cause: err },\n      );\n    }\n  }\n}\n\n/**\n * Create an adapter bound to a Drizzle client.\n *\n * Pass a top-level Drizzle client for typical use — the adapter will open\n * its own transactions via `db.transaction()`. Pass a Drizzle transaction\n * context to join an existing transaction the caller opened higher up\n * the stack.\n */\nexport function createDrizzleAdapter(\n  client: DrizzleDb,\n  options?: DrizzleAdapterOptions,\n): Adapter<DrizzleExecutor> {\n  return new DrizzleAdapter(client, options);\n}\n\n// ---- internal helpers ----\n\nfunction hasTransactionMethod(client: DrizzleDb): client is DrizzleTransactionalClient {\n  return typeof (client as DrizzleTransactionalClient).transaction === \"function\";\n}\n\n/**\n * Normalize `execute()` output across Drizzle's Postgres drivers.\n *\n * - `drizzle-orm/node-postgres`: returns pg's `QueryResult` — `{ rows: T[] }`.\n * - `drizzle-orm/postgres-js`: returns a `RowList<T>` that IS a `T[]` (with\n *   extra properties like `.count`).\n * - `drizzle-orm/neon-serverless`: also `{ rows: T[] }` (uses pg protocol).\n */\nfunction extractRows<T>(result: unknown): T[] {\n  if (Array.isArray(result)) return result as T[];\n  if (\n    result &&\n    typeof result === \"object\" &&\n    \"rows\" in result &&\n    Array.isArray((result as { rows?: unknown }).rows)\n  ) {\n    return (result as { rows: T[] }).rows;\n  }\n  throw new AdapterError(\n    \"Unexpected execute() result shape: expected an array or an object with `.rows`. \" +\n      \"Is this a Drizzle Postgres client?\",\n  );\n}\n\n/**\n * Detect \"unique constraint violation\" from the Postgres driver error.\n * All Postgres drivers surface SQLSTATE `23505`; some (pg) put it on\n * `.code`, some (postgres.js) on `.code` too, node-postgres nests it\n * further in some setups. Check every plausible location.\n */\nfunction isUniqueViolation(err: unknown): boolean {\n  if (!err || typeof err !== \"object\") return false;\n  const e = err as {\n    code?: unknown;\n    cause?: { code?: unknown } | null;\n    original?: { code?: unknown } | null;\n  };\n  if (e.code === \"23505\") return true;\n  if (e.cause && typeof e.cause === \"object\" && (e.cause as { code?: unknown }).code === \"23505\") {\n    return true;\n  }\n  if (\n    e.original &&\n    typeof e.original === \"object\" &&\n    (e.original as { code?: unknown }).code === \"23505\"\n  ) {\n    return true;\n  }\n  return false;\n}\n\nfunction mapRow(raw: RawTransitionRow): TransitionRow {\n  return {\n    id: raw.id,\n    machine: raw.machine,\n    subjectId: raw.subject_id,\n    fromState: raw.from_state,\n    toState: raw.to_state,\n    sortKey: Number(raw.sort_key),\n    mostRecent: raw.most_recent,\n    actorId: raw.actor_id,\n    actorType: raw.actor_type,\n    metadata: raw.metadata ?? {},\n    machineVersion: Number(raw.machine_version),\n    createdAt: raw.created_at instanceof Date ? raw.created_at : new Date(raw.created_at),\n  };\n}\n\nfunction stringField(obj: Record<string, unknown>, key: string): string | null {\n  const v = obj[key];\n  return typeof v === \"string\" ? v : null;\n}\n\n/**\n * Reject table/column names that aren't safe to interpolate into raw SQL.\n *\n * `sql.identifier()` already quotes identifiers to make injection hard,\n * but we still validate at the boundary so misconfigured hints fail loud\n * and early instead of at query time.\n */\nfunction assertValidIdentifier(name: string): void {\n  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {\n    throw new AdapterError(\n      `invalid SQL identifier: ${JSON.stringify(name)} (must match /^[A-Za-z_][A-Za-z0-9_]*$/)`,\n    );\n  }\n}\n","/**\n * Recommended Postgres schema for the transitions table.\n *\n * Exported in two shapes:\n *\n * - `STATELEDGER_SCHEMA_STATEMENTS`: an array of individual DDL statements.\n *   Use this when applying the schema through a driver that runs one\n *   statement at a time.\n * - `STATELEDGER_SCHEMA_SQL`: the same statements concatenated into one\n *   multi-statement script. Use this when writing a Drizzle migration\n *   (`drizzle-kit generate`) or any tool that accepts multi-statement input.\n *\n * The SQL here is identical to what `@stateledger/prisma` ships. It's\n * duplicated intentionally: the two adapters have separate release\n * cadences, and the SQL is ORM-agnostic Postgres DDL that shouldn't\n * change often. If it needs to change, both adapters must be bumped in\n * lockstep.\n */\n\nexport const STATELEDGER_SCHEMA_STATEMENTS: readonly string[] = [\n  `CREATE TABLE IF NOT EXISTS \"stateledger_transitions\" (\n    id               UUID         PRIMARY KEY DEFAULT gen_random_uuid(),\n    machine          TEXT         NOT NULL,\n    subject_id       TEXT         NOT NULL,\n    from_state       TEXT,\n    to_state         TEXT         NOT NULL,\n    sort_key         INTEGER      NOT NULL,\n    most_recent      BOOLEAN      NOT NULL DEFAULT TRUE,\n    actor_id         TEXT,\n    actor_type       TEXT,\n    metadata         JSONB        NOT NULL DEFAULT '{}'::jsonb,\n    machine_version  INTEGER      NOT NULL DEFAULT 1,\n    created_at       TIMESTAMPTZ  NOT NULL DEFAULT NOW()\n  )`,\n\n  // Deterministic ordering for history reads + the (machine, subject) lookup.\n  `CREATE UNIQUE INDEX IF NOT EXISTS \"stateledger_transitions_subject_sort_key\"\n    ON \"stateledger_transitions\" (machine, subject_id, sort_key)`,\n\n  // Partial unique index: exactly one mostRecent row per (machine, subject).\n  // This is the optimistic-concurrency safety net + a hard correctness invariant.\n  `CREATE UNIQUE INDEX IF NOT EXISTS \"stateledger_transitions_one_most_recent\"\n    ON \"stateledger_transitions\" (machine, subject_id)\n    WHERE most_recent = TRUE`,\n\n  // \"Recent transitions for this subject, newest first\" — covers history pagination.\n  `CREATE INDEX IF NOT EXISTS \"stateledger_transitions_history\"\n    ON \"stateledger_transitions\" (machine, subject_id, sort_key DESC)`,\n];\n\nexport const STATELEDGER_SCHEMA_SQL: string = STATELEDGER_SCHEMA_STATEMENTS.join(\";\\n\\n\") + \";\";\n"]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@stateledger/drizzle",
+  "version": "0.0.0",
+  "description": "Drizzle + Postgres adapter for stateledger — persisted, audited, concurrency-safe state machines.",
+  "license": "MIT",
+  "author": {
+    "name": "Enow Divine",
+    "email": "sirdivine16@gmail.com",
+    "url": "https://github.com/enowdivine"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/enowdivine/stateledger.git",
+    "directory": "packages/drizzle"
+  },
+  "homepage": "https://github.com/enowdivine/stateledger#readme",
+  "bugs": {
+    "url": "https://github.com/enowdivine/stateledger/issues"
+  },
+  "keywords": [
+    "state-machine",
+    "drizzle",
+    "drizzle-orm",
+    "postgres",
+    "stateledger",
+    "audit-trail",
+    "fsm"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@stateledger/core": "0.2.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.36"
+  },
+  "devDependencies": {
+    "drizzle-orm": "^0.36.4",
+    "pg": "^8.13.1",
+    "@types/pg": "^8.11.10",
+    "testcontainers": "^10.16.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist"
+  }
+}