@supacloud/db 0.6.0 → 0.8.0

package/dist/drizzle.js

@@ -0,0 +1,61 @@
+// 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));
+}
+export {
+  createDrizzleCommandDatabase,
+  defineDrizzleDatabaseModule,
+  executeDecodedSql
+};

package/dist/index.d.ts

@@ -8,3 +8,6 @@ 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 { defineReadQuery, decodePostgrestQuery, QueryBoundaryError, type QueryEvent, type QueryObserver, type ReadQueryDefinition } from "./query";
+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,14 +879,388 @@ 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/query.ts
+class QueryBoundaryError extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.code = code;
+    this.name = "QueryBoundaryError";
+  }
+}
+function defineReadQuery(definition) {
+  const contract = { ...definition };
+  if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/.test(contract.name) || contract.fingerprint !== undefined && !/^[a-f0-9]{16,64}$/.test(contract.fingerprint) || contract.slowMs !== undefined && (!Number.isFinite(contract.slowMs) || contract.slowMs < 0)) {
+    throw new TypeError("Invalid query observation metadata");
+  }
+  const emit = (event) => {
+    try {
+      Promise.resolve(contract.observe?.(Object.freeze(event))).catch(() => {});
+    } catch {}
+  };
+  const executeUnknown = async (identity, raw, signal) => {
+    if (signal?.aborted)
+      throw new QueryBoundaryError("QUERY_ABORTED");
+    let input;
+    try {
+      input = contract.input(raw);
+    } catch {
+      throw new QueryBoundaryError("QUERY_INPUT_INVALID");
+    }
+    let decision;
+    try {
+      decision = await contract.authorize(identity, input);
+    } catch {
+      throw new QueryBoundaryError("QUERY_AUTHORIZATION_FAILED");
+    }
+    if (decision === "deny")
+      throw new QueryBoundaryError("QUERY_REJECTED");
+    if (decision !== "allow")
+      throw new QueryBoundaryError("QUERY_AUTHORIZATION_FAILED");
+    if (signal?.aborted)
+      throw new QueryBoundaryError("QUERY_ABORTED");
+    const started = performance.now();
+    const metadata = { operation: contract.name, ...contract.fingerprint ? { fingerprint: contract.fingerprint } : {} };
+    emit({ ...metadata, phase: "started" });
+    try {
+      const value = await contract.execute(input, identity, signal);
+      if (signal?.aborted)
+        throw new QueryBoundaryError("QUERY_ABORTED");
+      let result;
+      try {
+        result = contract.result(value);
+      } catch {
+        throw new QueryBoundaryError("QUERY_RESULT_INVALID");
+      }
+      const durationMs = performance.now() - started;
+      emit({ ...metadata, phase: "succeeded", durationMs, slow: durationMs >= (contract.slowMs ?? 500) });
+      return result;
+    } catch (error) {
+      const durationMs = performance.now() - started;
+      emit({ ...metadata, phase: "failed", durationMs, slow: durationMs >= (contract.slowMs ?? 500) });
+      throw error;
+    }
+  };
+  const execute = (identity, input, signal) => contract.policy ? contract.policy.execute((signal) => executeUnknown(identity, input, signal), signal) : executeUnknown(identity, input, signal);
+  return Object.freeze({
+    execute: (identity, input, signal) => execute(identity, input, signal),
+    executeUnknown: execute
+  });
+}
+async function decodePostgrestQuery(query, decode) {
+  const response = await query;
+  if (response.error !== null)
+    throw new QueryBoundaryError("QUERY_TRANSPORT_FAILED");
+  try {
+    return decode(response.data);
+  } catch {
+    throw new QueryBoundaryError("QUERY_RESULT_INVALID");
+  }
+}
+// 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,
+  QueryBoundaryError,
   RpcContractError,
   applyModulePlan,
   buildDatabaseManifest,
   createDatabaseAccessBoundary,
+  createPostgresCommandStore,
   createRpcClient,
+  decodePostgrestQuery,
   defineDatabaseModule,
+  defineReadQuery,
   defineRpcContract,
   explainObject,
   extractSearchPath,

package/dist/migration-bindings.d.ts

@@ -40,9 +40,6 @@ export declare function renderMigrationBindings(options: {
         sql: string;
     }[];
     attestation: {
-        environment: string;
-        projectRef: string;
-        schema: 'supacloud.migration-binding-attestation.v1';
         manifestSha256: string;
         files: {
             file: string;
@@ -53,5 +50,8 @@ export declare function renderMigrationBindings(options: {
                 type: MigrationBindingType;
             }>;
         }[];
+        environment: string;
+        projectRef: string;
+        schema: "supacloud.migration-binding-attestation.v1";
     };
 };

package/dist/query.d.ts

@@ -0,0 +1,36 @@
+export interface QueryEvent {
+    readonly operation: string;
+    readonly fingerprint?: string;
+    readonly phase: "started" | "succeeded" | "failed";
+    readonly durationMs?: number;
+    readonly slow?: boolean;
+}
+export type QueryObserver = (event: Readonly<QueryEvent>) => void | Promise<void>;
+export interface ReadQueryDefinition<Input, Result, Identity> {
+    name: string;
+    /** Parser-derived SQL fingerprint or a generated operation hash; never raw SQL. */
+    fingerprint?: string;
+    input(value: unknown): Input;
+    result(value: unknown): Result;
+    authorize(identity: Identity, input: NoInfer<Input>): "allow" | "deny" | Promise<"allow" | "deny">;
+    execute(input: NoInfer<Input>, identity: Identity, signal?: AbortSignal): Promise<unknown>;
+    observe?: QueryObserver;
+    slowMs?: number;
+    policy?: {
+        execute<Value>(run: (signal: AbortSignal) => Promise<Value>, parent?: AbortSignal): Promise<Value>;
+    };
+}
+export declare class QueryBoundaryError extends Error {
+    readonly code: "QUERY_INPUT_INVALID" | "QUERY_REJECTED" | "QUERY_AUTHORIZATION_FAILED" | "QUERY_RESULT_INVALID" | "QUERY_ABORTED" | "QUERY_TRANSPORT_FAILED";
+    constructor(code: "QUERY_INPUT_INVALID" | "QUERY_REJECTED" | "QUERY_AUTHORIZATION_FAILED" | "QUERY_RESULT_INVALID" | "QUERY_ABORTED" | "QUERY_TRANSPORT_FAILED");
+}
+/** Explicit composition shared by SQL, pg_graphql and PostgREST. No DI, caching or SQL rewriting. */
+export declare function defineReadQuery<Input, Result, Identity>(definition: ReadQueryDefinition<Input, Result, Identity>): Readonly<{
+    execute: (identity: Identity, input: Input, signal?: AbortSignal) => Promise<Result>;
+    executeUnknown: (identity: Identity, input: unknown, signal?: AbortSignal) => Promise<Result>;
+}>;
+/** Preserve the official client's selected/embedded result type; validate before returning it. */
+export declare function decodePostgrestQuery<Query extends PromiseLike<{
+    data: unknown;
+    error: unknown;
+}>>(query: Query, decode: (value: unknown) => NoInfer<Awaited<Query>["data"]>): Promise<Awaited<Query>["data"]>;

package/dist/sql-analysis.d.ts

@@ -0,0 +1,47 @@
+export interface SqlAnalysis {
+    fingerprint: string;
+    defines: string[];
+    touches: string[];
+    references: string[];
+    review: string[];
+}
+/** PostgreSQL 18 grammar, not regex-based SQL rewriting. Names group overloads conservatively. */
+export declare function analyzeSql(sql: string): Promise<SqlAnalysis>;
+/** Read-only admission check; PostgreSQL READ ONLY and least-privilege grants remain mandatory. */
+export declare function assertReadSql(sql: string): Promise<string>;
+export interface SqlMigrationSource {
+    id: string;
+    owner: string;
+    sql: string;
+    /** Object IDs from a reviewed catalog graph; never silently inferred for dynamic SQL. */
+    dependencies?: readonly string[];
+}
+export interface SqlDependencyEdge {
+    dependent: string;
+    dependency: string;
+}
+export interface SqlCatalogDependencies {
+    edges: SqlDependencyEdge[];
+    review: string[];
+}
+/** Collapse columns/overloads to their owning object for conservative impact propagation. */
+export declare function readSqlDependencyGraph(executor: {
+    query(sql: string, parameters: unknown[]): Promise<unknown>;
+}, schemas: readonly string[]): Promise<SqlCatalogDependencies>;
+export interface SqlMigrationSnapshot {
+    id: string;
+    owner: string;
+    sha256: string;
+    analysis: SqlAnalysis;
+}
+export interface SqlImpactPlan {
+    migrations: SqlMigrationSnapshot[];
+    edges: SqlDependencyEdge[];
+    changed: string[];
+    affectedObjects: string[];
+    affectedMigrations: string[];
+    errors: string[];
+    review: string[];
+}
+/** Offline, append-only migration review. Does not execute SQL or approve a deployment. */
+export declare function planSqlImpact(sources: readonly SqlMigrationSource[], baseline?: readonly Pick<SqlMigrationSnapshot, "id" | "sha256">[], catalogEdges?: readonly SqlDependencyEdge[]): Promise<SqlImpactPlan>;