@supacloud/db 0.5.0 → 0.7.1

package/MIGRATION_BINDINGS.md

@@ -0,0 +1,138 @@
+# Controlled Migration Bindings
+
+This is a deployment-time API for **public environment bindings**, not a general
+SQL template language or another migration engine. Use identical migrations for
+schema, indexes, business functions and state machines. Explicitly register only
+SQL that must bind to a target-specific application ID, HTTPS URL or resource
+name. One-off account transfers and production data cleanup remain separately
+reviewed operations.
+
+## Drizzle v1 Boundary
+
+Reviewed against the Drizzle v1 PostgreSQL documentation on 2026-09-08:
+official documentation repository commit
+`dae09afd99baa6362ece434cfa7bab60ef4b8692`.
+
+- [Upgrade to v1](https://orm.drizzle.team/docs/upgrade-v1):
+  v1 removes the journal file and groups SQL and snapshots in migration folders.
+  Do not run `drizzle-kit up` automatically on an application's existing history.
+- [Custom migrations](https://orm.drizzle.team/docs/kit-custom-migrations):
+  `drizzle-kit generate --custom` is the extension point for custom SQL.
+- [Migrate](https://orm.drizzle.team/docs/drizzle-kit-migrate):
+  migration execution reads applied history and supports separate configuration
+  files for different deployment targets.
+
+Those documents do not define this parameter-rendering API. This is a SupaCloud
+extension, not a claim that Drizzle automatically reconciles account changes.
+The renderer accepts `20260908100000_binding/migration.sql` as well as legacy
+flat SQL filenames. It neither discovers nor changes snapshots, migration
+identities, order, or metadata. Call it on a deployment copy, never write its
+output over generated source SQL. When SupaCloud is the executor, continue using
+its canonical applied-migration ledger; do not additionally execute
+`drizzle-kit migrate` against that same migration stream.
+
+## Usage
+
+Commit a manifest containing explicit target pairs and reviewed source hashes.
+`templateSha256` is the SHA-256 of the exact UTF-8 source, including whitespace.
+An author obtains and reviews it once when adding a template; do not recompute
+and accept a changed source hash automatically during deployment.
+
+```ts
+import { renderMigrationBindings } from '@supacloud/db';
+
+const result = renderMigrationBindings({
+  manifest: {
+    schema: 'supacloud.migration-bindings.v1',
+    targets: [
+      { environment: 'test', projectRef: 'test-project' },
+      { environment: 'production', projectRef: 'production-project' },
+    ],
+    templates: [{
+      file: '20260908100000_binding/migration.sql',
+      templateSha256: reviewedSourceSha256,
+      parameters: [{
+        placeholder: '__SC_BINDING_APPLICATION_ID__',
+        variable: 'APPLICATION_ID',
+        type: 'uuid',
+        occurrences: 1,
+      }],
+    }],
+  },
+  target: selectedTarget,
+  migrations: sourceFiles,
+  values: selectedEnvironment,
+});
+// Send result.migrations to the existing dry-run/apply pipeline.
+// Persist result.attestation in the existing release artifacts.
+```
+
+Example source:
+
+```sql
+SELECT '__SC_BINDING_APPLICATION_ID__'::uuid;
+```
+
+The caller must select and verify the environment before invoking this API.
+Values are explicitly passed; the API does not read `process.env`, env files,
+SSH configuration, or another target's fallback values. The target pair must
+match the manifest. The full set of declared template sources must be supplied.
+Plain SQL sources pass through byte-for-byte.
+
+Only complete single-quoted placeholder literals are supported, including
+literals in dollar-quoted PostgreSQL function bodies. `uuid`, `https-url`, and
+`resource-name` have restricted alphabets excluding quotes, dollar delimiters,
+backslashes and control characters. HTTPS URLs must not contain userinfo.
+Do not put credentials, tokens, secrets or arbitrary text in these bindings.
+Object identifiers, SQL fragments and arbitrary string interpolation are
+intentionally unsupported.
+
+`__SC_BINDING_*__` is reserved. Undeclared reserved tokens, stray declared
+legacy tokens, duplicate definitions, missing inputs, changed source bytes,
+wrong occurrence counts, unknown fields and unknown types fail closed.
+Legacy tokens such as `__FA_SUPAUTH_CLIENT_ID__` can be explicitly declared
+without editing historical SQL.
+
+## Evidence And Changes
+
+The attestation includes the target pair, manifest digest, source digest,
+rendered digest and parameter names/types. It excludes SQL and parameter values.
+The returned `migrations` contain SQL and must not be logged as an attestation.
+This is reproducibility evidence, not a signature or proof of the database's
+current state. Store it in an existing access-controlled release receipt or
+artifact, and separately read back the target's applied migration inventory.
+
+The renderer never marks a migration as applied and has no database access.
+Compare the rendered SQL with the existing executor's inventory. A changed
+environment value is **not** permission to rewrite an applied migration or its
+ledger row. Add a forward binding migration and retain the old release artifact;
+historical reconciliation must use target-specific reviewed evidence.
+
+The CLI does not automatically enable this API. An application deployment
+adapter must supply the selected sources and target, then use its existing
+executor. In particular, this API does not add recursive Drizzle-folder discovery
+to the CLI's legacy flat-directory `push_migrations` command.
+
+## Acceptance
+
+```gherkin
+Scenario: Same template, separate targets
+  Given a reviewed template and explicit test and production project bindings
+  When each target provides its own valid parameters
+  Then source digests match and rendered digests differ without changing source files
+
+Scenario: Missing or unsafe parameter
+  Given a missing value, injected SQL fragment or secret-bearing URL
+  When rendering begins
+  Then it fails without echoing the supplied value or requesting any database mutation
+
+Scenario: Undeclared or changed SQL
+  Given a changed template, unexpected token or unregistered target
+  When rendering begins
+  Then deployment preparation fails before SQL is returned
+
+Scenario: Applied parameter changes
+  Given an already-applied binding migration and a changed parameter
+  When rendering again
+  Then a different digest is produced, not an automatic replay or ledger repair
+```

package/README.md

@@ -1,5 +1,35 @@
 # @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.
+
 SupaCloud 的数据库治理层：把 RLS 策略、RPC 函数、触发器、授权（grant）作为**一等资源**做声明式管理，并与 PostgreSQL 真实 Catalog 对账。
 
 定位：它是 Drizzle（schema/迁移）之上的治理层 —— Drizzle 负责表结构，本包负责表结构之外的安全与业务对象（策略、函数、权限）的声明、静态检查与漂移检测。**driver 无关**：所有 Catalog 读取都通过注入的 `QueryExecutor` 完成，不依赖任何数据库客户端，也不 import drizzle-orm（仅类型层兼容 drizzle Table 的内部形状）。

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

@@ -4,6 +4,9 @@ export { reconcileModule, splitQualifiedName, type ReconcileIssue, type Reconcil
 export { lintModule, lintSql, type LintIssue } from './lint.js';
 export { planModule, type ModulePlan, type PlanStep } from './plan.js';
 export { applyModulePlan, type ApplyResult } from './apply.js';
+export { migrationBindingSha256, parseMigrationBindingManifest, renderMigrationBindings, type MigrationBindingManifest, type MigrationBindingParameter, type MigrationBindingSource, type MigrationBindingTarget, type MigrationBindingTemplate, type MigrationBindingType, } from './migration-bindings.js';
 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

@@ -531,6 +531,152 @@ async function applyModulePlan(executor, plan) {
   }
   return result;
 }
+// src/migration-bindings.ts
+import { createHash } from "node:crypto";
+var TOKEN = /__[A-Z][A-Z0-9_]*__/g;
+var RESERVED_TOKEN = /__SC_BINDING_[A-Z0-9_]+__/;
+var HASH = /^[a-f0-9]{64}$/;
+function migrationBindingSha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function record(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid migration binding object");
+  }
+  return value;
+}
+function keys(row, expected) {
+  if (Object.keys(row).sort().join(",") !== expected.sort().join(",")) {
+    throw new Error("Unexpected migration binding fields");
+  }
+}
+function validTarget(value) {
+  const target = record(value);
+  keys(target, ["environment", "projectRef"]);
+  if (typeof target.environment !== "string" || !/^[a-z][a-z0-9-]{0,62}$/.test(target.environment) || typeof target.projectRef !== "string" || !/^[a-z0-9][a-z0-9_-]{0,62}$/.test(target.projectRef)) {
+    throw new Error("Invalid migration binding target");
+  }
+  return target;
+}
+function validFile(file) {
+  return typeof file === "string" && /^[a-zA-Z0-9_./-]+\.sql$/.test(file) && !file.startsWith("/") && file.split("/").every((part) => part && part !== "." && part !== "..");
+}
+function parseMigrationBindingManifest(value) {
+  const manifest = record(value);
+  keys(manifest, ["schema", "targets", "templates"]);
+  if (manifest.schema !== "supacloud.migration-bindings.v1" || !Array.isArray(manifest.targets) || !manifest.targets.length || !Array.isArray(manifest.templates)) {
+    throw new Error("Invalid migration binding manifest");
+  }
+  const targets = manifest.targets.map(validTarget);
+  if (new Set(targets.map((target) => target.environment)).size !== targets.length) {
+    throw new Error("Duplicate migration binding environment");
+  }
+  const files = new Set;
+  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((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");
+      }
+      placeholders.add(parameter.placeholder);
+      return parameter;
+    });
+    return { file: template.file, templateSha256: template.templateSha256, parameters };
+  });
+  return { schema: "supacloud.migration-bindings.v1", targets, templates };
+}
+function bindingValue(parameter, values) {
+  const value = Object.hasOwn(values, parameter.variable) ? values[parameter.variable] : undefined;
+  if (typeof value !== "string" || !value || value.trim() !== value) {
+    throw new Error(`Missing or invalid migration binding variable: ${parameter.variable}`);
+  }
+  let valid = false;
+  if (parameter.type === "uuid") {
+    valid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+  } else if (parameter.type === "resource-name") {
+    valid = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/.test(value);
+  } else if (/^https:\/\/[A-Za-z0-9._~:/?#[\]@!&()*+,;=%-]+$/.test(value)) {
+    try {
+      const url = new URL(value);
+      valid = url.protocol === "https:" && Boolean(url.hostname) && !url.username && !url.password;
+    } catch {}
+  }
+  if (!valid || value.includes("__"))
+    throw new Error(`Invalid ${parameter.type} migration binding: ${parameter.variable}`);
+  return value;
+}
+function renderMigrationBindings(options) {
+  const manifest = parseMigrationBindingManifest(options.manifest);
+  const target = validTarget(options.target);
+  if (!manifest.targets.some((candidate) => candidate.environment === target.environment && candidate.projectRef === target.projectRef)) {
+    throw new Error("Migration binding target is not registered in the manifest");
+  }
+  const sources = new Map;
+  for (const migration of options.migrations) {
+    if (!validFile(migration.file) || sources.has(migration.file) || typeof migration.sql !== "string" || !migration.sql.trim()) {
+      throw new Error("Invalid, empty, or duplicate migration binding source");
+    }
+    sources.set(migration.file, migration);
+  }
+  if (manifest.templates.some((template) => !sources.has(template.file))) {
+    throw new Error("Migration binding manifest references a missing source");
+  }
+  const templates = new Map(manifest.templates.map((template) => [template.file, template]));
+  const declaredTokens = new Set(manifest.templates.flatMap((template) => template.parameters.map((parameter) => parameter.placeholder)));
+  const files = [];
+  const migrations = options.migrations.map((migration) => {
+    const template = templates.get(migration.file);
+    const templateSha256 = migrationBindingSha256(migration.sql);
+    if (template && templateSha256 !== template.templateSha256) {
+      throw new Error(`Migration binding template checksum mismatch: ${migration.file}`);
+    }
+    const parameters = new Map(template?.parameters.map((parameter) => [parameter.placeholder, parameter]));
+    const counts = new Map;
+    const sql = migration.sql.replace(TOKEN, (token, offset) => {
+      const parameter = parameters.get(token);
+      if (!parameter) {
+        if (RESERVED_TOKEN.test(token) || declaredTokens.has(token)) {
+          throw new Error(`Undeclared migration binding placeholder: ${migration.file}`);
+        }
+        return token;
+      }
+      if (migration.sql[offset - 1] !== "'" || migration.sql[offset + token.length] !== "'") {
+        throw new Error(`Migration bindings must occupy a complete SQL string literal: ${migration.file}`);
+      }
+      counts.set(token, (counts.get(token) || 0) + 1);
+      return bindingValue(parameter, options.values);
+    });
+    for (const parameter of parameters.values()) {
+      if (counts.get(parameter.placeholder) !== parameter.occurrences) {
+        throw new Error(`Migration binding occurrence mismatch: ${migration.file}`);
+      }
+    }
+    files.push({
+      file: migration.file,
+      templateSha256,
+      renderedSqlSha256: migrationBindingSha256(sql),
+      parameters: [...parameters.values()].map(({ variable, type }) => ({ variable, type }))
+    });
+    return { file: migration.file, sql };
+  });
+  return {
+    migrations,
+    attestation: {
+      schema: "supacloud.migration-binding-attestation.v1",
+      ...target,
+      manifestSha256: migrationBindingSha256(JSON.stringify(manifest)),
+      files: files.sort((left, right) => left.file.localeCompare(right.file))
+    }
+  };
+}
 // src/manifest.ts
 function buildDatabaseManifest(modules) {
   return {
@@ -733,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,
@@ -746,8 +1185,11 @@ export {
   extractSearchPath,
   lintModule,
   lintSql,
+  migrationBindingSha256,
+  parseMigrationBindingManifest,
   planModule,
   readCatalog,
   reconcileModule,
+  renderMigrationBindings,
   splitQualifiedName
 };

package/dist/migration-bindings.d.ts

@@ -0,0 +1,57 @@
+export type MigrationBindingType = 'uuid' | 'https-url' | 'resource-name';
+export interface MigrationBindingTarget {
+    environment: string;
+    projectRef: string;
+}
+export interface MigrationBindingParameter {
+    placeholder: string;
+    variable: string;
+    type: MigrationBindingType;
+    occurrences: number;
+}
+export interface MigrationBindingTemplate {
+    file: string;
+    templateSha256: string;
+    parameters: MigrationBindingParameter[];
+}
+export interface MigrationBindingManifest {
+    schema: 'supacloud.migration-bindings.v1';
+    targets: MigrationBindingTarget[];
+    templates: MigrationBindingTemplate[];
+}
+export interface MigrationBindingSource {
+    file: string;
+    sql: string;
+}
+export declare function migrationBindingSha256(value: string): string;
+export declare function parseMigrationBindingManifest(value: unknown): MigrationBindingManifest;
+/**
+ * Pure rendering of explicitly declared SQL literals. The caller supplies an
+ * already-selected environment; this module never reads files or process.env.
+ */
+export declare function renderMigrationBindings(options: {
+    manifest: unknown;
+    target: MigrationBindingTarget;
+    migrations: readonly MigrationBindingSource[];
+    values: Readonly<Record<string, string | undefined>>;
+}): {
+    migrations: {
+        file: string;
+        sql: string;
+    }[];
+    attestation: {
+        environment: string;
+        projectRef: string;
+        schema: 'supacloud.migration-binding-attestation.v1';
+        manifestSha256: string;
+        files: {
+            file: string;
+            templateSha256: string;
+            renderedSqlSha256: string;
+            parameters: Array<{
+                variable: string;
+                type: MigrationBindingType;
+            }>;
+        }[];
+    };
+};

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@supacloud/db",
-  "version": "0.5.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",
@@ -15,11 +19,12 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "MIGRATION_BINDINGS.md"
   ],
   "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",
@@ -41,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"
   }
 }