@supacloud/db 0.6.0 → 0.8.0

package/README.md

@@ -1,5 +1,79 @@
 # @supacloud/db
 
+## Drizzle, Read Queries and SQL Impact
+
+Use `defineDrizzleDatabaseModule` and `createDrizzleCommandDatabase` from
+`@supacloud/db/drizzle`, or `createBunDrizzleCommandDatabase` from
+`@supacloud/db/drizzle-bun`. Authorization, business writes, receipts and audit
+share one transaction connection. Do not use the outer pool for command writes
+or retain `transaction.db` after the transaction. The adapter currently targets
+`drizzle-orm@1.0.0-rc.4`, not a stable 1.0 release.
+
+`executeDecodedSql` keeps SQL results unknown until an explicit decoder validates
+them. Use parameterized templates; `sql<T>` alone does not validate returned data.
+The optional `@supacloud/commands/typebox` contract can use schemas derived through
+`drizzle-orm/typebox-legacy`, selecting public fields rather than accepting
+internal tenant/permission fields.
+
+`defineReadQuery` combines input decoding, authorization, result decoding and
+payload-free observation. `createBunReadDatabase` admits one parsed SELECT and
+runs a PostgreSQL READ ONLY transaction with a statement timeout.
+`createBunDrizzleReadDatabase` provides the read transaction boundary for Drizzle.
+Keep least-privilege roles and RLS; AOP does not replace them.
+
+`supacloud-sql-impact impact.json --check` analyzes ordered, owned migrations:
+
+```json
+{
+  "migrations": [
+    { "id": "001", "owner": "orders", "path": "migrations/001.sql" }
+  ],
+  "baseline": []
+}
+```
+
+Paths are relative to this config. Reports include fingerprints, dependencies,
+transitive impact, review reasons and a digest. Persist applied IDs and SHA-256
+hashes as `baseline`; deleted, reordered or rewritten history fails validation.
+Supply `readSqlDependencyGraph(executor, ["app"])` results as `catalogEdges` and
+`catalogReview`. Import this catalog reader from `@supacloud/db/sql-analysis`.
+
+Dynamic SQL, opaque functions, unqualified names and unsupported semantics require
+review. This is conservative analysis, not proof of arbitrary SQL safety. Approve
+the exact reviewed report via `approvedDigest`; changes invalidate approval, and
+approval never overrides history errors. The tool does not execute migrations.
+
+The focused `tests/drizzle-foundation.test.ts` test needs Docker and starts a
+disposable local PostgreSQL/PGMQ instance. Prepare Commands and Compiler package
+dependencies first using `scripts/build-command-dependencies.ts db`.
+
+## Durable Commands
+
+`createPostgresCommandStore(database)` implements the protocol's storage ports.
+Use `createBunCommandDatabase` from `@supacloud/db/bun` for a native Bun SQL pool.
+This package contains transaction/receipt SQL, Workflow binding, row validation
+and input redaction. It does not own a recovery polling queue.
+
+Execution factories moved to `@supacloud/commands`; pass `store` instead of
+`database`. Errors moved to `CommandError` in `@supacloud/contracts`. Neither
+remote sending nor command orchestration is re-exported here. The DB package
+does not depend on the command runtime in production. The Drizzle integration
+test uses the command runtime to verify the shared transaction boundary.
+
+Install the existing PGMQ/Workflow runtime and updated commands-public SQL module,
+then `COMMAND_PERSISTENCE_SQL` through a privileged application migration.
+Existing unreleased v1 tables require `COMMAND_PERSISTENCE_UPGRADE_SQL`, with old
+writers stopped; preserve operation identifiers during cutover.
+The upgrade enqueues pending recovery using existing Workflow and removes prototype
+lease/backoff columns. Use `createPostgresCommandStore(database, { submission })`
+inside a submitted command's execute step to preserve its command ID and atomically
+advance to reconciliation (external) or complete its Workflow (transactional).
+`submission` carries commandId, stepId, messageId, attempt and workerId. The adapter
+checks the current attempt, recorded tenant/actor/command, and original input.
+Keep its schema private and supply domain authorization, JSON-stable input/result
+decoders and a single-connection transaction adapter. Metadata cannot provide a
+distributed transaction. See [migration, deployment and recovery](../../docs/command-migration.md).
+
 For reviewed deployment-time public SQL parameters, see
 [Controlled Migration Bindings](./MIGRATION_BINDINGS.md). This opt-in API preserves
 Drizzle v1 source/snapshot ownership and the existing executor's migration ledger.

package/dist/command-adapter.d.ts

@@ -0,0 +1,18 @@
+import type { CommandStore, CommandRetentionStore } from "@supacloud/contracts";
+export interface CommandTransaction {
+    query(sql: string, parameters?: readonly (string | number | boolean | null)[]): Promise<unknown>;
+}
+export interface CommandDatabase<Transaction extends CommandTransaction = CommandTransaction> {
+    transaction<T>(run: (transaction: Transaction) => Promise<T>): Promise<T>;
+}
+export interface CommandSubmissionBinding {
+    commandId: string;
+    stepId: string;
+    messageId: string;
+    attempt: number;
+    workerId: string;
+}
+/** PostgreSQL only: no remote sending, domain matching or recovery policy lives here. */
+export declare function createPostgresCommandStore<Transaction extends CommandTransaction>(database: CommandDatabase<Transaction>, options?: {
+    submission?: CommandSubmissionBinding;
+}): CommandStore<Transaction> & CommandRetentionStore;

package/dist/command-bun.d.ts

@@ -0,0 +1,8 @@
+import type { SQL } from "bun";
+import type { CommandDatabase } from "./command-adapter";
+/** The SQL pool owns one connection from BEGIN through COMMIT/ROLLBACK. */
+export declare function createBunCommandDatabase(sql: SQL): CommandDatabase;
+/** The driver owns a read-only transaction and enforces its statement timeout. */
+export declare function createBunReadDatabase(pool: SQL, timeoutMs?: number): Readonly<{
+    query(text: string, parameters?: readonly (string | number | boolean | null)[], signal?: AbortSignal): Promise<unknown>;
+}>;

package/dist/command-bun.js

@@ -0,0 +1,350 @@
+var __esm = (fn, res, err) => () => {
+  if (fn)
+    try {
+      res = fn(fn = 0);
+    } catch (e) {
+      err = [e];
+    }
+  if (err)
+    throw err[0];
+  return res;
+};
+
+// src/sql-analysis.ts
+import { createHash } from "node:crypto";
+import { fingerprint, parse } from "libpg-query";
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function walk(value, visit) {
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, visit);
+  } else if (record(value)) {
+    visit(value);
+    for (const item of Object.values(value))
+      walk(item, visit);
+  }
+}
+function names(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.flatMap((part) => record(part) && record(part["String"]) && typeof part["String"]["sval"] === "string" ? [part["String"]["sval"]] : []);
+}
+async function analyzeSql(sql) {
+  const result = await parse(sql);
+  const defines = new Set, touches = new Set, references = new Set, review = new Set;
+  const qualified = (kind, parts) => {
+    if (parts.length !== 2) {
+      review.add(`Resolve unqualified or unsupported ${kind} name: ${parts.join(".")}`);
+      return;
+    }
+    return objectId(kind, parts);
+  };
+  const relation = (value) => {
+    if (!record(value) || typeof value["relname"] !== "string")
+      return;
+    return qualified("relation", typeof value["schemaname"] === "string" ? [value["schemaname"], value["relname"]] : [value["relname"]]);
+  };
+  walk(result, (node) => {
+    if (record(node["RangeVar"])) {
+      const name = relation(node["RangeVar"]);
+      if (name)
+        references.add(name);
+    }
+    if (record(node["FuncCall"])) {
+      const name = qualified("function", names(node["FuncCall"]["funcname"]));
+      if (name)
+        references.add(name);
+    }
+    if (record(node["Constraint"])) {
+      const name = relation(node["Constraint"]["pktable"]);
+      if (name)
+        references.add(name);
+    }
+  });
+  const statements = record(result) && Array.isArray(result["stmts"]) ? result["stmts"] : [];
+  for (const raw of statements) {
+    if (!record(raw) || !record(raw["stmt"]))
+      throw new Error("Invalid PostgreSQL parse tree");
+    const [kind, node] = Object.entries(raw["stmt"])[0] ?? [];
+    if (!kind || !record(node))
+      throw new Error("Invalid SQL statement");
+    const target = relation(node["relation"] ?? node["view"] ?? node["table"]);
+    if (target) {
+      touches.add(target);
+      if (kind === "CreateStmt" || kind === "ViewStmt")
+        defines.add(target);
+    }
+    if (kind === "DropStmt") {
+      for (const item of Array.isArray(node["objects"]) ? node["objects"] : []) {
+        const name = record(item) && record(item["List"]) ? qualified(node["removeType"] === "OBJECT_TABLE" || node["removeType"] === "OBJECT_VIEW" ? "relation" : "object", names(item["List"]["items"])) : undefined;
+        if (name)
+          touches.add(name);
+        else
+          review.add("Review dropped object identity and dependencies");
+      }
+      review.add("Destructive DROP requires review");
+    } else if (kind === "CreateFunctionStmt") {
+      const name = qualified("function", names(node["funcname"]));
+      if (name) {
+        defines.add(name);
+        touches.add(name);
+      }
+      let language, body;
+      for (const item of Array.isArray(node["options"]) ? node["options"] : []) {
+        if (!record(item) || !record(item["DefElem"]))
+          continue;
+        const option = item["DefElem"];
+        if (option["defname"] === "language")
+          language = names([option["arg"]])[0];
+        if (option["defname"] === "as" && record(option["arg"]) && record(option["arg"]["List"]))
+          body = names(option["arg"]["List"]["items"])[0];
+      }
+      if (language === "sql" && body !== undefined) {
+        const nested = await analyzeSql(body);
+        for (const name of [...nested.references, ...nested.touches])
+          references.add(name);
+        for (const item of nested.review)
+          review.add(item);
+      } else {
+        review.add("Function body dependencies require catalog verification or explicit reviewed dependencies");
+      }
+      review.add("Review function security, grants and overloads");
+    } else if (![
+      "SelectStmt",
+      "CreateStmt",
+      "ViewStmt",
+      "AlterTableStmt",
+      "IndexStmt",
+      "InsertStmt",
+      "UpdateStmt",
+      "DeleteStmt",
+      "CreatePolicyStmt",
+      "AlterPolicyStmt",
+      "CreateTrigStmt"
+    ].includes(kind)) {
+      review.add(`Review unsupported dependency semantics: ${kind}`);
+    }
+    if (["AlterTableStmt", "CreatePolicyStmt", "AlterPolicyStmt", "CreateTrigStmt"].includes(kind)) {
+      review.add(`Review schema/access impact: ${kind}`);
+    }
+  }
+  return {
+    fingerprint: await fingerprint(sql),
+    defines: [...defines].sort(),
+    touches: [...touches].sort(),
+    references: [...references].sort(),
+    review: [...review].sort()
+  };
+}
+async function assertReadSql(sql) {
+  const tree = await parse(sql);
+  if (!record(tree) || !Array.isArray(tree["stmts"]) || tree["stmts"].length !== 1)
+    throw new Error("Expected one read statement");
+  const entry = tree["stmts"][0];
+  if (!record(entry) || !record(entry["stmt"]) || !record(entry["stmt"]["SelectStmt"]))
+    throw new Error("Expected SELECT");
+  walk(tree, (node) => {
+    if (["InsertStmt", "UpdateStmt", "DeleteStmt", "MergeStmt", "IntoClause", "intoClause", "LockingClause"].some((name) => (name in node))) {
+      throw new Error("Mutating or locking SQL is not a read query");
+    }
+  });
+  return fingerprint(sql);
+}
+async function readSqlDependencyGraph(executor, schemas) {
+  if (!schemas.length || schemas.some((schema) => !schema.trim()))
+    throw new TypeError("Select explicit application schemas");
+  const schemaParameters = schemas.map((_, index) => `$${index + 1}::text`).join(", ");
+  const rows = await executor.query(`
+WITH objects AS (
+  SELECT 'pg_class'::regclass::oid AS classid, c.oid AS objid, n.nspname,
+    'relation:' || to_json(n.nspname)::text || '.' || to_json(c.relname)::text AS identity
+  FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace
+  UNION ALL
+  SELECT 'pg_proc'::regclass::oid, p.oid, n.nspname,
+    'function:' || to_json(n.nspname)::text || '.' || to_json(p.proname)::text
+  FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace
+  UNION ALL
+  SELECT 'pg_rewrite'::regclass::oid, r.oid, n.nspname,
+    'relation:' || to_json(n.nspname)::text || '.' || to_json(c.relname)::text
+  FROM pg_rewrite r JOIN pg_class c ON c.oid=r.ev_class JOIN pg_namespace n ON n.oid=c.relnamespace
+  UNION ALL
+  SELECT 'pg_policy'::regclass::oid, p.oid, n.nspname,
+    'relation:' || to_json(n.nspname)::text || '.' || to_json(c.relname)::text
+  FROM pg_policy p JOIN pg_class c ON c.oid=p.polrelid JOIN pg_namespace n ON n.oid=c.relnamespace
+  UNION ALL
+  SELECT 'pg_trigger'::regclass::oid, t.oid, n.nspname,
+    'relation:' || to_json(n.nspname)::text || '.' || to_json(c.relname)::text
+  FROM pg_trigger t JOIN pg_class c ON c.oid=t.tgrelid JOIN pg_namespace n ON n.oid=c.relnamespace
+)
+SELECT DISTINCT a.identity AS dependent, b.identity AS dependency
+FROM pg_depend d
+JOIN objects a ON a.classid=d.classid AND a.objid=d.objid
+JOIN objects b ON b.classid=d.refclassid AND b.objid=d.refobjid
+WHERE a.nspname IN (${schemaParameters})
+  AND b.nspname IN (${schemaParameters}) AND a.identity<>b.identity
+ORDER BY dependent, dependency`, [...schemas]);
+  if (!Array.isArray(rows))
+    throw new TypeError("Invalid PostgreSQL dependency rows");
+  const edges = rows.map((row) => {
+    if (!record(row) || typeof row["dependent"] !== "string" || typeof row["dependency"] !== "string")
+      throw new TypeError("Invalid PostgreSQL dependency edge");
+    return { dependent: row["dependent"], dependency: row["dependency"] };
+  });
+  const functions = await executor.query(`
+SELECT DISTINCT n.nspname AS schema, p.proname AS name
+FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace
+JOIN pg_language l ON l.oid=p.prolang
+WHERE n.nspname IN (${schemaParameters})
+  AND (l.lanname='plpgsql' OR (l.lanname='sql' AND p.prosqlbody IS NULL))
+ORDER BY schema, name`, [...schemas]);
+  if (!Array.isArray(functions))
+    throw new TypeError("Invalid PostgreSQL function rows");
+  return {
+    edges,
+    review: functions.map((row) => {
+      if (!record(row) || typeof row["schema"] !== "string" || typeof row["name"] !== "string")
+        throw new TypeError("Invalid function identity");
+      return `Catalog cannot prove function-body dependencies: ${objectId("function", [row["schema"], row["name"]])}`;
+    })
+  };
+}
+async function planSqlImpact(sources, baseline = [], catalogEdges = []) {
+  const ids = new Set;
+  const migrations = [];
+  const edges = new Map;
+  const addEdge = (dependent, dependency) => {
+    if (dependent !== dependency)
+      edges.set(JSON.stringify([dependent, dependency]), { dependent, dependency });
+  };
+  for (const edge of catalogEdges)
+    addEdge(edge["dependent"], edge["dependency"]);
+  for (const source of sources) {
+    if (!source.id.trim() || !source.owner.trim() || ids.has(source.id))
+      throw new Error("Migration IDs must be unique and each migration must have an owner");
+    ids.add(source.id);
+    const analysis = await analyzeSql(source.sql);
+    const references = [...new Set([...analysis.references, ...source.dependencies ?? []])].sort();
+    for (const target of analysis.touches)
+      for (const reference of references)
+        addEdge(target, reference);
+    migrations.push({
+      id: source.id,
+      owner: source.owner,
+      sha256: createHash("sha256").update(source.sql).digest("hex"),
+      analysis: { ...analysis, references }
+    });
+  }
+  const current = new Map(migrations.map((entry) => [entry.id, entry]));
+  const previous = new Map(baseline.map((entry) => [entry.id, entry]));
+  const errors = [];
+  if (previous.size !== baseline.length)
+    errors.push("Duplicate migration in baseline");
+  for (const [index, old] of baseline.entries()) {
+    if (current.get(old.id)?.sha256 !== old.sha256 || migrations[index]?.id !== old.id) {
+      errors.push(`Applied migration removed, reordered or rewritten: ${old.id}`);
+    }
+  }
+  const changed = migrations.filter((entry) => previous.get(entry.id)?.sha256 !== entry.sha256);
+  const affected = new Set(changed.flatMap((entry) => entry.analysis.touches));
+  const reverse = new Map;
+  for (const edge of edges.values()) {
+    const values = reverse.get(edge["dependency"]) ?? [];
+    values.push(edge["dependent"]);
+    reverse.set(edge["dependency"], values);
+  }
+  for (const object of affected)
+    for (const dependent of reverse.get(object) ?? [])
+      affected.add(dependent);
+  const definitions = new Map;
+  migrations.forEach((entry, index) => {
+    for (const object of entry.analysis.defines)
+      if (!definitions.has(object))
+        definitions.set(object, index);
+  });
+  migrations.forEach((entry, index) => {
+    for (const reference of entry.analysis.references) {
+      if ((definitions.get(reference) ?? -1) > index)
+        errors.push(`${entry.id} references an object defined by a later migration: ${reference}`);
+    }
+  });
+  return {
+    migrations,
+    edges: [...edges.values()].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    changed: changed.map((entry) => entry.id),
+    affectedObjects: [...affected].sort(),
+    affectedMigrations: migrations.filter((entry) => [...entry.analysis.touches, ...entry.analysis.references].some((object) => affected.has(object))).map((entry) => entry.id),
+    errors,
+    review: changed.flatMap((entry) => entry.analysis.review.map((note) => `${entry.id}: ${note}`))
+  };
+}
+var objectId = (kind, parts) => `${kind}:${parts.map((part) => JSON.stringify(part)).join(".")}`;
+var init_sql_analysis = () => {};
+
+// src/command-bun.ts
+function createBunCommandDatabase(sql) {
+  return {
+    async transaction(run) {
+      const result = await sql.begin(async (connection) => ({
+        value: await run({
+          query: async (text, parameters = []) => {
+            const rows = await connection.unsafe(text, [...parameters]);
+            return rows;
+          }
+        })
+      }));
+      return result.value;
+    }
+  };
+}
+function createBunReadDatabase(pool, timeoutMs = 5000) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
+    throw new TypeError("Invalid read statement timeout");
+  }
+  const admitted = new Map;
+  return Object.freeze({
+    async query(text, parameters = [], signal) {
+      if (signal?.aborted)
+        throw new Error("Read aborted");
+      await Promise.resolve().then(() => init_sql_analysis());
+      let admission = admitted.get(text);
+      if (!admission) {
+        admission = assertReadSql(text);
+        if (admitted.size >= 256) {
+          const oldest = admitted.keys().next().value;
+          if (oldest !== undefined)
+            admitted.delete(oldest);
+        }
+        admitted.set(text, admission);
+      }
+      try {
+        await admission;
+      } catch (error) {
+        admitted.delete(text);
+        throw error;
+      }
+      return pool.begin(async (connection) => {
+        await connection.unsafe("SET TRANSACTION READ ONLY");
+        await connection`SELECT set_config('statement_timeout', ${String(timeoutMs)}, true)`;
+        if (signal?.aborted)
+          throw new Error("Read aborted");
+        const pending = connection.unsafe(text, [...parameters]);
+        const abort = () => pending.cancel();
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+          const rows = await pending;
+          if (signal?.aborted)
+            throw new Error("Read aborted");
+          return rows;
+        } finally {
+          signal?.removeEventListener("abort", abort);
+        }
+      });
+    }
+  });
+}
+export {
+  createBunCommandDatabase,
+  createBunReadDatabase
+};

package/dist/command-schema.d.ts

@@ -0,0 +1,4 @@
+/** Install through the application's normal migration flow, never during a request. */
+export declare const COMMAND_PERSISTENCE_SQL = "\nDO $runtime$\nBEGIN\n  IF to_regprocedure('supacloud_workflows.start_run(uuid,text,text,text,jsonb,integer)') IS NULL\n    OR to_regprocedure('supacloud_commands.status(jsonb)') IS NULL THEN\n    RAISE EXCEPTION 'Install the SupaCloud Commands/Workflow/PGMQ runtime before command persistence';\n  END IF;\nEND\n$runtime$;\nCREATE SCHEMA IF NOT EXISTS supacloud_commands;\nREVOKE ALL ON SCHEMA supacloud_commands FROM PUBLIC;\nCREATE TABLE IF NOT EXISTS supacloud_commands.execution_receipts (\n  tenant_id text NOT NULL,\n  actor_id text NOT NULL,\n  command text NOT NULL,\n  operation_key text NOT NULL,\n  kind text NOT NULL CHECK (kind IN ('transactional', 'external')),\n  input_fingerprint text NOT NULL CHECK (input_fingerprint ~ '^[a-f0-9]{64}$'),\n  input_payload text,\n  dispatch_key uuid NOT NULL DEFAULT gen_random_uuid() UNIQUE,\n  status text NOT NULL CHECK (status IN ('pending', 'unknown', 'confirmed')),\n  audit_state text NOT NULL CHECK (audit_state IN ('pending', 'complete')),\n  result jsonb,\n  created_at timestamptz NOT NULL DEFAULT now(),\n  updated_at timestamptz NOT NULL DEFAULT now(),\n  PRIMARY KEY (tenant_id, actor_id, command, operation_key),\n  CHECK ((status = 'confirmed') = (result IS NOT NULL)),\n  CHECK (audit_state <> 'complete' OR status = 'confirmed'),\n  CHECK (kind <> 'transactional' OR (status = 'confirmed' AND audit_state = 'complete'))\n);\nCREATE TABLE IF NOT EXISTS supacloud_commands.execution_audit (\n  tenant_id text NOT NULL,\n  actor_id text NOT NULL,\n  command text NOT NULL,\n  operation_key text NOT NULL,\n  event text NOT NULL,\n  details jsonb NOT NULL,\n  created_at timestamptz NOT NULL DEFAULT now(),\n  PRIMARY KEY (tenant_id, actor_id, command, operation_key),\n  FOREIGN KEY (tenant_id, actor_id, command, operation_key)\n    REFERENCES supacloud_commands.execution_receipts (tenant_id, actor_id, command, operation_key)\n);\nREVOKE ALL ON supacloud_commands.execution_receipts, supacloud_commands.execution_audit FROM PUBLIC;\nCREATE OR REPLACE FUNCTION supacloud_commands.enqueue_execution_recovery()\nRETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $recovery$\nDECLARE submission jsonb;\nBEGIN\n  PERFORM pg_advisory_xact_lock(hashtextextended(NEW.dispatch_key::text,0));\n  SELECT supacloud_commands.snapshot(NEW.dispatch_key,false) INTO submission;\n  IF submission IS NOT NULL THEN\n    IF submission->>'commandType' IS DISTINCT FROM NEW.command\n      OR submission->>'actorId' IS DISTINCT FROM NEW.actor_id\n      OR submission->>'tenantId' IS DISTINCT FROM NEW.tenant_id\n      OR NEW.operation_key <> NEW.dispatch_key::text THEN\n      RAISE EXCEPTION 'SUPACLOUD_COMMAND_IDENTITY_CONFLICT';\n    END IF;\n    RETURN NEW;\n  END IF;\n  IF NEW.kind = 'external' AND (NEW.status <> 'confirmed' OR NEW.audit_state <> 'complete') THEN\n    PERFORM supacloud_workflows.start_run(\n      NEW.dispatch_key, 'supacloud.command.reconcile', '1', 'reconcile',\n      jsonb_build_object('commandId', NEW.dispatch_key, 'tenantId', NEW.tenant_id,\n        'actorId', NEW.actor_id, 'command', NEW.command, 'operationId', NEW.operation_key),\n      20\n    );\n  END IF;\n  RETURN NEW;\nEND\n$recovery$;\nCREATE OR REPLACE TRIGGER execution_recovery_enqueue\nAFTER INSERT ON supacloud_commands.execution_receipts\nFOR EACH ROW EXECUTE FUNCTION supacloud_commands.enqueue_execution_recovery();\n\nCREATE OR REPLACE FUNCTION supacloud_commands.execution_status(request jsonb)\nRETURNS jsonb LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $status$\n  SELECT jsonb_build_object('kind','execution','commandId',r.dispatch_key,\n    'execution',jsonb_build_object('tenantId',r.tenant_id,'actorId',r.actor_id,\n      'command',r.command,'operationId',r.operation_key,'dispatchKey',r.dispatch_key,\n      'status',r.status,'audit',r.audit_state)\n      || CASE WHEN r.status='confirmed' THEN jsonb_build_object('result',r.result) ELSE '{}'::jsonb END,\n    'workflow',CASE WHEN w.id IS NULL THEN NULL ELSE jsonb_build_object('runId',w.id,'status',w.status) END)\n  FROM supacloud_commands.execution_receipts r\n  LEFT JOIN supacloud_workflows.runs w ON w.id=r.dispatch_key\n  WHERE CASE WHEN request ? 'commandId' THEN r.dispatch_key::text=request->>'commandId'\n    ELSE r.tenant_id=request->>'tenantId' AND r.actor_id=request->>'actorId'\n      AND r.command=request->>'command' AND r.operation_key=request->>'operationId' END\n$status$;\nREVOKE ALL ON FUNCTION supacloud_commands.execution_status(jsonb) FROM PUBLIC;\n";
+/** Explicit migration from the unreleased v1 prototype. Never discard operation keys. */
+export declare const COMMAND_PERSISTENCE_UPGRADE_SQL = "\nALTER TABLE supacloud_commands.execution_receipts\n  ADD COLUMN IF NOT EXISTS input_fingerprint text,\n  ADD COLUMN IF NOT EXISTS input_payload text;\nDO $migration$\nBEGIN\n  IF EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema='supacloud_commands'\n    AND table_name='execution_receipts' AND column_name='input_key') THEN\n    EXECUTE 'UPDATE supacloud_commands.execution_receipts\n      SET input_fingerprint=encode(sha256(convert_to(input_key,''UTF8'')),''hex''),input_payload=input_key\n      WHERE input_fingerprint IS NULL';\n    ALTER TABLE supacloud_commands.execution_receipts DROP COLUMN input_key;\n  END IF;\nEND\n$migration$;\nALTER TABLE supacloud_commands.execution_receipts ALTER COLUMN input_fingerprint SET NOT NULL;\nDO $constraint$\nBEGIN\n  IF NOT EXISTS (SELECT 1 FROM pg_constraint\n    WHERE conrelid='supacloud_commands.execution_receipts'::regclass\n      AND conname='execution_receipts_input_fingerprint_check') THEN\n    ALTER TABLE supacloud_commands.execution_receipts\n      ADD CONSTRAINT execution_receipts_input_fingerprint_check CHECK (input_fingerprint ~ '^[a-f0-9]{64}$');\n  END IF;\nEND\n$constraint$;\n\nDO $runtime$\nBEGIN\n  IF to_regprocedure('supacloud_workflows.start_run(uuid,text,text,text,jsonb,integer)') IS NULL\n    OR to_regprocedure('supacloud_commands.status(jsonb)') IS NULL THEN\n    RAISE EXCEPTION 'Install the SupaCloud Commands/Workflow/PGMQ runtime before command persistence';\n  END IF;\nEND\n$runtime$;\nCREATE SCHEMA IF NOT EXISTS supacloud_commands;\nREVOKE ALL ON SCHEMA supacloud_commands FROM PUBLIC;\nCREATE TABLE IF NOT EXISTS supacloud_commands.execution_receipts (\n  tenant_id text NOT NULL,\n  actor_id text NOT NULL,\n  command text NOT NULL,\n  operation_key text NOT NULL,\n  kind text NOT NULL CHECK (kind IN ('transactional', 'external')),\n  input_fingerprint text NOT NULL CHECK (input_fingerprint ~ '^[a-f0-9]{64}$'),\n  input_payload text,\n  dispatch_key uuid NOT NULL DEFAULT gen_random_uuid() UNIQUE,\n  status text NOT NULL CHECK (status IN ('pending', 'unknown', 'confirmed')),\n  audit_state text NOT NULL CHECK (audit_state IN ('pending', 'complete')),\n  result jsonb,\n  created_at timestamptz NOT NULL DEFAULT now(),\n  updated_at timestamptz NOT NULL DEFAULT now(),\n  PRIMARY KEY (tenant_id, actor_id, command, operation_key),\n  CHECK ((status = 'confirmed') = (result IS NOT NULL)),\n  CHECK (audit_state <> 'complete' OR status = 'confirmed'),\n  CHECK (kind <> 'transactional' OR (status = 'confirmed' AND audit_state = 'complete'))\n);\nCREATE TABLE IF NOT EXISTS supacloud_commands.execution_audit (\n  tenant_id text NOT NULL,\n  actor_id text NOT NULL,\n  command text NOT NULL,\n  operation_key text NOT NULL,\n  event text NOT NULL,\n  details jsonb NOT NULL,\n  created_at timestamptz NOT NULL DEFAULT now(),\n  PRIMARY KEY (tenant_id, actor_id, command, operation_key),\n  FOREIGN KEY (tenant_id, actor_id, command, operation_key)\n    REFERENCES supacloud_commands.execution_receipts (tenant_id, actor_id, command, operation_key)\n);\nREVOKE ALL ON supacloud_commands.execution_receipts, supacloud_commands.execution_audit FROM PUBLIC;\nCREATE OR REPLACE FUNCTION supacloud_commands.enqueue_execution_recovery()\nRETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $recovery$\nDECLARE submission jsonb;\nBEGIN\n  PERFORM pg_advisory_xact_lock(hashtextextended(NEW.dispatch_key::text,0));\n  SELECT supacloud_commands.snapshot(NEW.dispatch_key,false) INTO submission;\n  IF submission IS NOT NULL THEN\n    IF submission->>'commandType' IS DISTINCT FROM NEW.command\n      OR submission->>'actorId' IS DISTINCT FROM NEW.actor_id\n      OR submission->>'tenantId' IS DISTINCT FROM NEW.tenant_id\n      OR NEW.operation_key <> NEW.dispatch_key::text THEN\n      RAISE EXCEPTION 'SUPACLOUD_COMMAND_IDENTITY_CONFLICT';\n    END IF;\n    RETURN NEW;\n  END IF;\n  IF NEW.kind = 'external' AND (NEW.status <> 'confirmed' OR NEW.audit_state <> 'complete') THEN\n    PERFORM supacloud_workflows.start_run(\n      NEW.dispatch_key, 'supacloud.command.reconcile', '1', 'reconcile',\n      jsonb_build_object('commandId', NEW.dispatch_key, 'tenantId', NEW.tenant_id,\n        'actorId', NEW.actor_id, 'command', NEW.command, 'operationId', NEW.operation_key),\n      20\n    );\n  END IF;\n  RETURN NEW;\nEND\n$recovery$;\nCREATE OR REPLACE TRIGGER execution_recovery_enqueue\nAFTER INSERT ON supacloud_commands.execution_receipts\nFOR EACH ROW EXECUTE FUNCTION supacloud_commands.enqueue_execution_recovery();\n\nCREATE OR REPLACE FUNCTION supacloud_commands.execution_status(request jsonb)\nRETURNS jsonb LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $status$\n  SELECT jsonb_build_object('kind','execution','commandId',r.dispatch_key,\n    'execution',jsonb_build_object('tenantId',r.tenant_id,'actorId',r.actor_id,\n      'command',r.command,'operationId',r.operation_key,'dispatchKey',r.dispatch_key,\n      'status',r.status,'audit',r.audit_state)\n      || CASE WHEN r.status='confirmed' THEN jsonb_build_object('result',r.result) ELSE '{}'::jsonb END,\n    'workflow',CASE WHEN w.id IS NULL THEN NULL ELSE jsonb_build_object('runId',w.id,'status',w.status) END)\n  FROM supacloud_commands.execution_receipts r\n  LEFT JOIN supacloud_workflows.runs w ON w.id=r.dispatch_key\n  WHERE CASE WHEN request ? 'commandId' THEN r.dispatch_key::text=request->>'commandId'\n    ELSE r.tenant_id=request->>'tenantId' AND r.actor_id=request->>'actorId'\n      AND r.command=request->>'command' AND r.operation_key=request->>'operationId' END\n$status$;\nREVOKE ALL ON FUNCTION supacloud_commands.execution_status(jsonb) FROM PUBLIC;\n\nDO $backfill$\nDECLARE r record;\nBEGIN\n  FOR r IN SELECT * FROM supacloud_commands.execution_receipts\n    WHERE kind='external' AND (status<>'confirmed' OR audit_state<>'complete')\n      AND NOT EXISTS(SELECT FROM supacloud_workflows.runs w WHERE w.id=dispatch_key)\n  LOOP\n    PERFORM supacloud_workflows.start_run(\n      r.dispatch_key,'supacloud.command.reconcile','1','reconcile',\n      jsonb_build_object('commandId',r.dispatch_key,'tenantId',r.tenant_id,\n        'actorId',r.actor_id,'command',r.command,'operationId',r.operation_key),20\n    );\n  END LOOP;\nEND\n$backfill$;\nDROP INDEX IF EXISTS supacloud_commands.execution_pending_recovery;\nALTER TABLE supacloud_commands.execution_receipts\n  DROP COLUMN IF EXISTS lease_id,\n  DROP COLUMN IF EXISTS lease_until,\n  DROP COLUMN IF EXISTS next_attempt_at,\n  DROP COLUMN IF EXISTS recovery_attempts;\n";

package/dist/drizzle-bun.d.ts

@@ -0,0 +1,10 @@
+import type { SQL } from "bun";
+import { type BunSQLDatabase } from "drizzle-orm/bun-sql/postgres";
+import type { AnyRelations, EmptyRelations } from "drizzle-orm/relations";
+import type { DrizzlePgConfig } from "drizzle-orm/pg-core";
+/** Drizzle is bound to Bun's pinned transaction client, not the application pool. */
+export declare function createBunDrizzleCommandDatabase<Relations extends AnyRelations = EmptyRelations>(pool: SQL, config?: DrizzlePgConfig<Relations>): import("./command-adapter").CommandDatabase<import("./drizzle").DrizzleCommandTransaction<BunSQLDatabase<Relations>>>;
+/** Explicit read-only unit of work; use a least-privilege pool with the intended RLS identity. */
+export declare function createBunDrizzleReadDatabase<Relations extends AnyRelations = EmptyRelations>(pool: SQL, config?: DrizzlePgConfig<Relations>, timeoutMs?: number): Readonly<{
+    read<Result>(work: (db: BunSQLDatabase<Relations>) => Promise<Result>): Promise<Result>;
+}>;

package/dist/drizzle-bun.js

@@ -0,0 +1,93 @@
+// src/drizzle-bun.ts
+import { drizzle } from "drizzle-orm/bun-sql/postgres";
+
+// src/drizzle.ts
+import { is } from "drizzle-orm";
+import { getTableConfig, PgTable } from "drizzle-orm/pg-core";
+
+// src/module.ts
+function normalizeTable(ref) {
+  if (typeof ref === "string")
+    return ref;
+  const schema = ref._.schema ?? "public";
+  return `${schema}.${ref._.name}`;
+}
+function defineDatabaseModule(options) {
+  return {
+    name: options.name,
+    tables: (options.tables ?? []).map(normalizeTable),
+    policies: options.policies ?? [],
+    functions: options.functions ?? [],
+    triggers: options.triggers ?? [],
+    grants: options.grants ?? []
+  };
+}
+
+// src/drizzle.ts
+function defineDrizzleDatabaseModule(tables, options) {
+  const names = new Set;
+  for (const table of Object.values(tables)) {
+    if (!is(table, PgTable))
+      throw new TypeError("Expected a PostgreSQL Drizzle table");
+    const config = getTableConfig(table);
+    names.add(`${config.schema ?? "public"}.${config.name}`);
+  }
+  return defineDatabaseModule({ ...options, tables: [...names].sort() });
+}
+function createDrizzleCommandDatabase(options) {
+  return {
+    transaction: (work) => options.transaction(async (connection) => {
+      const db = options.bind(connection);
+      let active = true;
+      try {
+        return await work({
+          db,
+          query: async (text, parameters = []) => {
+            if (!active)
+              throw new Error("Command transaction is closed");
+            return options.query(connection, text, parameters);
+          }
+        });
+      } finally {
+        active = false;
+      }
+    })
+  };
+}
+async function executeDecodedSql(executor, query, decode) {
+  return decode(await executor.execute(query));
+}
+
+// src/drizzle-bun.ts
+function createBunDrizzleCommandDatabase(pool, config = {}) {
+  return createDrizzleCommandDatabase({
+    transaction: async (work) => {
+      const result = await pool.begin(async (connection) => ({ value: await work(connection) }));
+      return result.value;
+    },
+    bind: (connection) => drizzle({ ...config, client: connection }),
+    query: async (connection, text, parameters) => {
+      const rows = await connection.unsafe(text, [...parameters]);
+      return rows;
+    }
+  });
+}
+function createBunDrizzleReadDatabase(pool, config = {}, timeoutMs = 5000) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
+    throw new TypeError("Invalid read statement timeout");
+  }
+  return Object.freeze({
+    async read(work) {
+      const result = await pool.begin(async (connection) => {
+        await connection.unsafe("SET TRANSACTION READ ONLY");
+        await connection`SELECT set_config('statement_timeout', ${String(timeoutMs)}, true)`;
+        return { value: await work(drizzle({ ...config, client: connection })) };
+      });
+      return result.value;
+    }
+  });
+}
+export {
+  createBunDrizzleCommandDatabase,
+  createBunDrizzleReadDatabase
+};

package/dist/drizzle.d.ts

@@ -0,0 +1,26 @@
+import { type SQL } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import type { DatabaseModule, DatabaseModuleOptions } from "./module.js";
+import type { CommandDatabase, CommandTransaction } from "./command-adapter";
+/** Accept explicit table exports, not arbitrary objects or private type-only metadata. */
+export declare function defineDrizzleDatabaseModule(tables: Readonly<Record<string, PgTable>>, options: Omit<DatabaseModuleOptions, "tables">): DatabaseModule;
+export interface DrizzleCommandTransaction<Database> extends CommandTransaction {
+    readonly db: Database;
+}
+export interface DrizzleCommandDatabaseOptions<Connection, Database> {
+    /** Owns BEGIN/COMMIT/ROLLBACK and pins one connection for the callback. */
+    transaction<T>(work: (connection: Connection) => Promise<T>): Promise<T>;
+    /** Construct Drizzle on this connection, never on the outer connection pool. */
+    bind(connection: NoInfer<Connection>): Database;
+    /** Execute parameterized protocol SQL on the same connection; return rows only. */
+    query(connection: NoInfer<Connection>, text: string, parameters: readonly (string | number | boolean | null)[]): Promise<unknown>;
+}
+/**
+ * One native transaction serves Drizzle business writes and SQL receipts.
+ * No SQL placeholder rewriting, hidden second transaction or driver internals.
+ */
+export declare function createDrizzleCommandDatabase<Connection, Database>(options: DrizzleCommandDatabaseOptions<Connection, Database>): CommandDatabase<DrizzleCommandTransaction<Database>>;
+/** Raw SQL results stay unknown until an application-owned decoder validates them. */
+export declare function executeDecodedSql<Result>(executor: {
+    execute(query: SQL): PromiseLike<unknown>;
+}, query: SQL<unknown>, decode: (value: unknown) => Result): Promise<Result>;