@supacloud/db 0.6.0 → 0.7.1

package/README.md

@@ -1,5 +1,31 @@
 # @supacloud/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, including through its tests.
+
+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<T>(run: (transaction: CommandTransaction) => 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(database: CommandDatabase, options?: {
+    submission?: CommandSubmissionBinding;
+}): CommandStore<CommandTransaction> & CommandRetentionStore;

package/dist/command-bun.d.ts

@@ -0,0 +1,4 @@
+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;

package/dist/command-bun.js

@@ -0,0 +1,19 @@
+// 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;
+    }
+  };
+}
+export {
+  createBunCommandDatabase
+};

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/index.d.ts

@@ -8,3 +8,5 @@ export { migrationBindingSha256, parseMigrationBindingManifest, renderMigrationB
 export { buildDatabaseManifest, explainObject, type DatabaseManifest, type DatabaseManifestModule, } from './manifest.js';
 export { createDatabaseAccessBoundary, DatabaseAccessError, type AuthenticatedDatabaseIdentity, type DatabaseAccessBoundary, type DatabaseAccessBoundaryOptions, type DatabaseAccessErrorCode, } from './access.js';
 export { createRpcClient, defineRpcContract, RpcContractError, type RpcArgs, type RpcCallResult, type RpcContract, type RpcDecoder, type RpcResult, type RpcTransport, } from './rpc.js';
+export { COMMAND_PERSISTENCE_SQL, COMMAND_PERSISTENCE_UPGRADE_SQL } from "./command-schema";
+export { createPostgresCommandStore, type CommandDatabase, type CommandTransaction, type CommandSubmissionBinding, } from "./command-adapter";

package/dist/index.js

@@ -572,16 +572,16 @@ function parseMigrationBindingManifest(value) {
     throw new Error("Duplicate migration binding environment");
   }
   const files = new Set;
-  const templates = manifest.templates.map((value2) => {
-    const template = record(value2);
+  const templates = manifest.templates.map((value) => {
+    const template = record(value);
     keys(template, ["file", "templateSha256", "parameters"]);
     if (!validFile(template.file) || files.has(template.file) || typeof template.templateSha256 !== "string" || !HASH.test(template.templateSha256) || !Array.isArray(template.parameters) || !template.parameters.length) {
       throw new Error("Invalid or duplicate migration binding template");
     }
     files.add(template.file);
     const placeholders = new Set;
-    const parameters = template.parameters.map((value3) => {
-      const parameter = record(value3);
+    const parameters = template.parameters.map((value) => {
+      const parameter = record(value);
       keys(parameter, ["placeholder", "variable", "type", "occurrences"]);
       if (typeof parameter.placeholder !== "string" || !/^__[A-Z][A-Z0-9_]*__$/.test(parameter.placeholder) || placeholders.has(parameter.placeholder) || typeof parameter.variable !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(parameter.variable) || !["uuid", "https-url", "resource-name"].includes(String(parameter.type)) || !Number.isSafeInteger(parameter.occurrences) || Number(parameter.occurrences) < 1) {
         throw new Error("Invalid or duplicate migration binding parameter");
@@ -879,12 +879,305 @@ function createRpcClient(transport, contracts) {
     }
   };
 }
+// src/command-schema.ts
+var COMMAND_PERSISTENCE_SQL = `
+DO $runtime$
+BEGIN
+  IF to_regprocedure('supacloud_workflows.start_run(uuid,text,text,text,jsonb,integer)') IS NULL
+    OR to_regprocedure('supacloud_commands.status(jsonb)') IS NULL THEN
+    RAISE EXCEPTION 'Install the SupaCloud Commands/Workflow/PGMQ runtime before command persistence';
+  END IF;
+END
+$runtime$;
+CREATE SCHEMA IF NOT EXISTS supacloud_commands;
+REVOKE ALL ON SCHEMA supacloud_commands FROM PUBLIC;
+CREATE TABLE IF NOT EXISTS supacloud_commands.execution_receipts (
+  tenant_id text NOT NULL,
+  actor_id text NOT NULL,
+  command text NOT NULL,
+  operation_key text NOT NULL,
+  kind text NOT NULL CHECK (kind IN ('transactional', 'external')),
+  input_fingerprint text NOT NULL CHECK (input_fingerprint ~ '^[a-f0-9]{64}$'),
+  input_payload text,
+  dispatch_key uuid NOT NULL DEFAULT gen_random_uuid() UNIQUE,
+  status text NOT NULL CHECK (status IN ('pending', 'unknown', 'confirmed')),
+  audit_state text NOT NULL CHECK (audit_state IN ('pending', 'complete')),
+  result jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, actor_id, command, operation_key),
+  CHECK ((status = 'confirmed') = (result IS NOT NULL)),
+  CHECK (audit_state <> 'complete' OR status = 'confirmed'),
+  CHECK (kind <> 'transactional' OR (status = 'confirmed' AND audit_state = 'complete'))
+);
+CREATE TABLE IF NOT EXISTS supacloud_commands.execution_audit (
+  tenant_id text NOT NULL,
+  actor_id text NOT NULL,
+  command text NOT NULL,
+  operation_key text NOT NULL,
+  event text NOT NULL,
+  details jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, actor_id, command, operation_key),
+  FOREIGN KEY (tenant_id, actor_id, command, operation_key)
+    REFERENCES supacloud_commands.execution_receipts (tenant_id, actor_id, command, operation_key)
+);
+REVOKE ALL ON supacloud_commands.execution_receipts, supacloud_commands.execution_audit FROM PUBLIC;
+CREATE OR REPLACE FUNCTION supacloud_commands.enqueue_execution_recovery()
+RETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $recovery$
+DECLARE submission jsonb;
+BEGIN
+  PERFORM pg_advisory_xact_lock(hashtextextended(NEW.dispatch_key::text,0));
+  SELECT supacloud_commands.snapshot(NEW.dispatch_key,false) INTO submission;
+  IF submission IS NOT NULL THEN
+    IF submission->>'commandType' IS DISTINCT FROM NEW.command
+      OR submission->>'actorId' IS DISTINCT FROM NEW.actor_id
+      OR submission->>'tenantId' IS DISTINCT FROM NEW.tenant_id
+      OR NEW.operation_key <> NEW.dispatch_key::text THEN
+      RAISE EXCEPTION 'SUPACLOUD_COMMAND_IDENTITY_CONFLICT';
+    END IF;
+    RETURN NEW;
+  END IF;
+  IF NEW.kind = 'external' AND (NEW.status <> 'confirmed' OR NEW.audit_state <> 'complete') THEN
+    PERFORM supacloud_workflows.start_run(
+      NEW.dispatch_key, 'supacloud.command.reconcile', '1', 'reconcile',
+      jsonb_build_object('commandId', NEW.dispatch_key, 'tenantId', NEW.tenant_id,
+        'actorId', NEW.actor_id, 'command', NEW.command, 'operationId', NEW.operation_key),
+      20
+    );
+  END IF;
+  RETURN NEW;
+END
+$recovery$;
+CREATE OR REPLACE TRIGGER execution_recovery_enqueue
+AFTER INSERT ON supacloud_commands.execution_receipts
+FOR EACH ROW EXECUTE FUNCTION supacloud_commands.enqueue_execution_recovery();
+
+CREATE OR REPLACE FUNCTION supacloud_commands.execution_status(request jsonb)
+RETURNS jsonb LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $status$
+  SELECT jsonb_build_object('kind','execution','commandId',r.dispatch_key,
+    'execution',jsonb_build_object('tenantId',r.tenant_id,'actorId',r.actor_id,
+      'command',r.command,'operationId',r.operation_key,'dispatchKey',r.dispatch_key,
+      'status',r.status,'audit',r.audit_state)
+      || CASE WHEN r.status='confirmed' THEN jsonb_build_object('result',r.result) ELSE '{}'::jsonb END,
+    'workflow',CASE WHEN w.id IS NULL THEN NULL ELSE jsonb_build_object('runId',w.id,'status',w.status) END)
+  FROM supacloud_commands.execution_receipts r
+  LEFT JOIN supacloud_workflows.runs w ON w.id=r.dispatch_key
+  WHERE CASE WHEN request ? 'commandId' THEN r.dispatch_key::text=request->>'commandId'
+    ELSE r.tenant_id=request->>'tenantId' AND r.actor_id=request->>'actorId'
+      AND r.command=request->>'command' AND r.operation_key=request->>'operationId' END
+$status$;
+REVOKE ALL ON FUNCTION supacloud_commands.execution_status(jsonb) FROM PUBLIC;
+`;
+var COMMAND_PERSISTENCE_UPGRADE_SQL = `
+ALTER TABLE supacloud_commands.execution_receipts
+  ADD COLUMN IF NOT EXISTS input_fingerprint text,
+  ADD COLUMN IF NOT EXISTS input_payload text;
+DO $migration$
+BEGIN
+  IF EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema='supacloud_commands'
+    AND table_name='execution_receipts' AND column_name='input_key') THEN
+    EXECUTE 'UPDATE supacloud_commands.execution_receipts
+      SET input_fingerprint=encode(sha256(convert_to(input_key,''UTF8'')),''hex''),input_payload=input_key
+      WHERE input_fingerprint IS NULL';
+    ALTER TABLE supacloud_commands.execution_receipts DROP COLUMN input_key;
+  END IF;
+END
+$migration$;
+ALTER TABLE supacloud_commands.execution_receipts ALTER COLUMN input_fingerprint SET NOT NULL;
+DO $constraint$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint
+    WHERE conrelid='supacloud_commands.execution_receipts'::regclass
+      AND conname='execution_receipts_input_fingerprint_check') THEN
+    ALTER TABLE supacloud_commands.execution_receipts
+      ADD CONSTRAINT execution_receipts_input_fingerprint_check CHECK (input_fingerprint ~ '^[a-f0-9]{64}$');
+  END IF;
+END
+$constraint$;
+${COMMAND_PERSISTENCE_SQL}
+DO $backfill$
+DECLARE r record;
+BEGIN
+  FOR r IN SELECT * FROM supacloud_commands.execution_receipts
+    WHERE kind='external' AND (status<>'confirmed' OR audit_state<>'complete')
+      AND NOT EXISTS(SELECT FROM supacloud_workflows.runs w WHERE w.id=dispatch_key)
+  LOOP
+    PERFORM supacloud_workflows.start_run(
+      r.dispatch_key,'supacloud.command.reconcile','1','reconcile',
+      jsonb_build_object('commandId',r.dispatch_key,'tenantId',r.tenant_id,
+        'actorId',r.actor_id,'command',r.command,'operationId',r.operation_key),20
+    );
+  END LOOP;
+END
+$backfill$;
+DROP INDEX IF EXISTS supacloud_commands.execution_pending_recovery;
+ALTER TABLE supacloud_commands.execution_receipts
+  DROP COLUMN IF EXISTS lease_id,
+  DROP COLUMN IF EXISTS lease_until,
+  DROP COLUMN IF EXISTS next_attempt_at,
+  DROP COLUMN IF EXISTS recovery_attempts;
+`;
+// src/command-adapter.ts
+import {
+  CommandError,
+  canonicalCommandJson,
+  commandIdentifier,
+  decodeCommandJson,
+  decodeDurableCommandReceipt
+} from "@supacloud/contracts";
+var where = "tenant_id=$1 AND actor_id=$2 AND command=$3 AND operation_key=$4";
+var keys2 = (ref) => [ref.tenantId, ref.actorId, ref.command, ref.operationId].map(commandIdentifier);
+function rows(value) {
+  const isRow = (row) => row !== null && typeof row === "object" && !Array.isArray(row);
+  if (!Array.isArray(value) || !Array.from(value).every(isRow))
+    throw new CommandError("COMMAND_RECEIPT_INVALID");
+  return value;
+}
+function decodeStored(row) {
+  try {
+    const fingerprint = row["input_fingerprint"], payload = row["input_payload"], kind = row["kind"];
+    if (typeof fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(fingerprint) || payload !== null && typeof payload !== "string" || kind !== "transactional" && kind !== "external")
+      throw new Error("Invalid record");
+    const serialized = row["result_json"];
+    if (serialized !== null && typeof serialized !== "string")
+      throw new Error("Invalid stored JSON");
+    const raw = typeof serialized === "string" ? JSON.parse(serialized) : undefined;
+    const receipt = decodeDurableCommandReceipt({ ...row, ...raw === undefined ? {} : { result: raw } }, decodeCommandJson);
+    return { receipt, kind, inputFingerprint: fingerprint, inputPayload: payload };
+  } catch {
+    throw new CommandError("COMMAND_RECEIPT_INVALID");
+  }
+}
+var projection = `tenant_id AS "tenantId", actor_id AS "actorId", command,
+  operation_key AS "operationId", dispatch_key::text AS "dispatchKey",
+  status, audit_state AS audit, result::text AS result_json, input_fingerprint,input_payload,kind`;
+function createPostgresCommandStore(database, options = {}) {
+  const submission = options.submission === undefined ? undefined : { ...options.submission };
+  if (submission !== undefined && (!/^[0-9a-f-]{36}$/.test(submission.commandId) || !/^[0-9a-f-]{36}$/.test(submission.stepId) || !/^[1-9][0-9]*$/.test(submission.messageId) || !Number.isSafeInteger(submission.attempt) || submission.attempt < 1 || !commandIdentifier(submission.workerId)))
+    throw new CommandError("COMMAND_INPUT_INVALID");
+  const submittedPayload = async (tx, ref, inserting) => {
+    if (submission === undefined)
+      throw new CommandError("COMMAND_INPUT_INVALID");
+    if (ref.operationId !== submission.commandId)
+      throw new CommandError("COMMAND_IDEMPOTENCY_CONFLICT");
+    const found = rows(await tx.query(`SELECT c.command_type,c.actor_id::text,c.tenant_id,c.payload::text AS payload_json,
+      s.step_key,s.status FROM supacloud_commands.receipts c
+      JOIN LATERAL supacloud_workflows.lock_step_attempt($2::uuid,$3::bigint,$4::integer,$5) s
+      ON s.run_id=c.id WHERE c.id=$1::uuid`, [submission.commandId, submission.stepId, submission.messageId, submission.attempt, submission.workerId]));
+    const row = found[0];
+    if (found.length !== 1 || row === undefined || row["command_type"] !== ref.command || row["actor_id"] !== ref.actorId || row["tenant_id"] !== ref.tenantId || row["step_key"] !== "execute" || row["status"] !== "running" && (inserting || row["status"] !== "completed") || typeof row["payload_json"] !== "string")
+      throw new CommandError("COMMAND_REJECTED");
+    const payload = JSON.parse(row["payload_json"]);
+    return payload;
+  };
+  const transaction = async (run) => {
+    let started = false;
+    try {
+      return await database.transaction((tx) => {
+        started = true;
+        return run(tx);
+      });
+    } catch (error) {
+      if (error instanceof CommandError)
+        throw error;
+      throw new CommandError(started ? "COMMAND_OUTCOME_UNKNOWN" : "COMMAND_UNAVAILABLE");
+    }
+  };
+  const session = (tx) => ({
+    transaction: tx,
+    async lock(ref) {
+      await tx.query("SELECT pg_advisory_xact_lock(hashtextextended($1,0))", [JSON.stringify(keys2(ref))]);
+      if (submission !== undefined)
+        await submittedPayload(tx, ref, false);
+    },
+    async read(ref) {
+      const found = rows(await tx.query(`SELECT ${projection} FROM supacloud_commands.execution_receipts WHERE ${where}`, keys2(ref)));
+      if (found.length > 1)
+        throw new CommandError("COMMAND_RECEIPT_INVALID");
+      const row = found[0];
+      return row === undefined ? null : decodeStored(row);
+    },
+    async insert(record) {
+      const receipt = submission === undefined ? record.receipt : { ...record.receipt, dispatchKey: submission.commandId };
+      if (submission !== undefined) {
+        const payload = await submittedPayload(tx, receipt, true);
+        const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalCommandJson(payload)));
+        const fingerprint = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        if (fingerprint !== record.inputFingerprint)
+          throw new CommandError("COMMAND_IDEMPOTENCY_CONFLICT");
+      }
+      const result = receipt.status === "confirmed" ? canonicalCommandJson(receipt.result) : null;
+      await tx.query(`INSERT INTO supacloud_commands.execution_receipts
+        (tenant_id,actor_id,command,operation_key,dispatch_key,kind,input_fingerprint,input_payload,status,audit_state,result)
+        VALUES ($1,$2,$3,$4,$5::uuid,$6,$7,$8,$9,$10,$11::text::jsonb)`, [...keys2(receipt), receipt.dispatchKey, record.kind, record.inputFingerprint, record.inputPayload, receipt.status, receipt.audit, result]);
+      if (submission !== undefined) {
+        const attempt = { stepId: submission.stepId, messageId: submission.messageId, attempt: submission.attempt, workerId: submission.workerId };
+        const commandId = submission.commandId;
+        if (record.kind === "external") {
+          await tx.query("SELECT public.supacloud_workflow_advance($1::text::jsonb)", [JSON.stringify({
+            ...attempt,
+            output: { commandId, status: "intent-recorded" },
+            nextStepKey: "reconcile",
+            nextInput: { commandId, tenantId: receipt.tenantId, actorId: receipt.actorId, command: receipt.command, operationId: receipt.operationId },
+            nextMaxAttempts: 20
+          })]);
+        } else {
+          const output = { commandId, status: "confirmed", audit: "complete" };
+          await tx.query("SELECT public.supacloud_workflow_complete($1::text::jsonb)", [JSON.stringify({ ...attempt, stepOutput: output, runOutput: output })]);
+        }
+      }
+    },
+    async confirm(ref, result) {
+      await tx.query(`UPDATE supacloud_commands.execution_receipts SET status='confirmed',result=$5::text::jsonb,updated_at=now()
+        WHERE ${where} AND status<>'confirmed'`, [...keys2(ref), canonicalCommandJson(result)]);
+    },
+    async markUnknown(ref) {
+      await tx.query(`UPDATE supacloud_commands.execution_receipts SET status='unknown',updated_at=now()
+        WHERE ${where} AND status<>'confirmed'`, keys2(ref));
+    },
+    async audit(ref, event, details) {
+      await tx.query(`INSERT INTO supacloud_commands.execution_audit
+        (tenant_id,actor_id,command,operation_key,event,details) VALUES ($1,$2,$3,$4,$5,$6::text::jsonb)`, [...keys2(ref), commandIdentifier(event), canonicalCommandJson(details)]);
+    },
+    async completeAudit(ref) {
+      await tx.query(`UPDATE supacloud_commands.execution_receipts SET audit_state='complete',updated_at=now() WHERE ${where}`, keys2(ref));
+    }
+  });
+  const scopeKeys = (scope) => {
+    if (scope.commands.length === 0)
+      throw new CommandError("COMMAND_INPUT_INVALID");
+    return [commandIdentifier(scope.tenantId), JSON.stringify(scope.commands.map(commandIdentifier))];
+  };
+  const integer = (value, min, max = Number.MAX_SAFE_INTEGER) => {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+      throw new CommandError("COMMAND_INPUT_INVALID");
+    return value;
+  };
+  const selected = `tenant_id=$1 AND command IN (SELECT jsonb_array_elements_text($2::text::jsonb))`;
+  const join = `r.tenant_id=c.tenant_id AND r.actor_id=c.actor_id AND r.command=c.command AND r.operation_key=c.operation_key`;
+  return {
+    transaction: (run) => transaction((tx) => run(session(tx))),
+    async redactCompleted(options) {
+      return transaction(async (tx) => rows(await tx.query(`WITH candidates AS (
+        SELECT tenant_id,actor_id,command,operation_key FROM supacloud_commands.execution_receipts
+        WHERE ${selected} AND status='confirmed' AND audit_state='complete' AND input_payload IS NOT NULL
+          AND updated_at<to_timestamp($3::double precision/1000)
+        ORDER BY updated_at LIMIT $4 FOR UPDATE SKIP LOCKED
+      ) UPDATE supacloud_commands.execution_receipts r SET input_payload=NULL FROM candidates c
+        WHERE ${join} RETURNING r.operation_key`, [...scopeKeys(options), integer(options.before, 0), integer(options.limit, 1, 1000)])).length);
+    }
+  };
+}
 export {
+  COMMAND_PERSISTENCE_SQL,
+  COMMAND_PERSISTENCE_UPGRADE_SQL,
   DatabaseAccessError,
   RpcContractError,
   applyModulePlan,
   buildDatabaseManifest,
   createDatabaseAccessBoundary,
+  createPostgresCommandStore,
   createRpcClient,
   defineDatabaseModule,
   defineRpcContract,

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@supacloud/db",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Database governance layer for SupaCloud: RLS policies, RPC functions and grants as first-class resources, with manifest/catalog reconciliation",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./bun": {
+      "types": "./dist/command-bun.d.ts",
+      "import": "./dist/command-bun.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
@@ -20,7 +24,7 @@
   ],
   "scripts": {
     "build": "bun run clean && bun run build:js && bun run build:types",
-    "build:js": "bun build src/index.ts --outdir dist --target node",
+    "build:js": "bun build src/index.ts src/command-bun.ts --outdir dist --target node --external bun --external @supacloud/contracts",
     "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run build",
@@ -42,7 +46,13 @@
     "directory": "packages/db"
   },
   "devDependencies": {
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.2",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "@supacloud/contracts": "0.3.1"
+  },
+  "overrides": {
+    "@supacloud/contracts": "0.3.1"
   }
 }