@supacloud/db 0.1.0 → 0.2.0

package/README.md

@@ -16,7 +16,8 @@ db/
 ```
 
 ```ts
-import { defineDatabaseModule } from '@supacloud/db';
+import { createDatabaseAccessBoundary, defineDatabaseModule } from '@supacloud/db';
+import { requireTrustedIdentity } from '@supacloud/elysia';
 import { cases } from './schema'; // drizzle 表对象
 
 export const casesModule = defineDatabaseModule({
@@ -57,6 +58,26 @@ export const casesModule = defineDatabaseModule({
 | `lintSql(sql, file)` / `lintModule(module, readFile)` | 纯 SQL 文本静态分析，无需数据库 |
 | `buildDatabaseManifest(modules)` | 汇总模块为可 JSON 序列化的 `DatabaseManifest`（version 1） |
 | `explainObject(manifest, name)` | 人类可读地解释对象的所属模块、类型、源文件、权限、测试 |
+| `createDatabaseAccessBoundary(options)` | 统一用户 RLS 客户端与显式 service-role 客户端的访问边界 |
+| `planModule(module, readFile)` | 把模块声明编译为有序 `ModulePlan`（step 依赖序：function → policy → trigger → grant），含 sha256 与 lint 风险 |
+| `applyModulePlan(executor, plan)` | 按 plan 落库：账本幂等 + advisory lock + 单事务 + catalog 回读验证 |
+
+### 数据库访问边界
+
+业务请求只应通过 `forUser({ subject, accessToken })` 创建 RLS-preserving 客户端；
+后台任务才可以通过 `forService("declared-reason")` 获取缓存的 service-role 客户端。
+service-role 原因必须预先加入 `allowedServiceReasons`，缺少身份、令牌或理由时会 fail-closed。
+
+```ts
+const database = createDatabaseAccessBoundary({
+  createUserClient: ({ accessToken }) => createSupabaseClient(accessToken),
+  createServiceClient: () => createServiceRoleClient(),
+  allowedServiceReasons: ["scheduled-worker", "migration-check"],
+});
+
+const userDb = await database.forUser(requireTrustedIdentity(requestContext));
+const workerDb = await database.forService("scheduled-worker");
+```
 
 ## 诊断码
 
@@ -66,7 +87,9 @@ export const casesModule = defineDatabaseModule({
 | --- | --- | --- |
 | `missing-policy` | error | 声明的策略在 catalog 中不存在 |
 | `missing-function` | error | 声明的 RPC 函数在 catalog 中不存在 |
+| `missing-trigger` | error | 声明的触发器在 catalog 中不存在（按 schema.table + name 匹配） |
 | `undeclared-policy` | warn | 归属表上存在 manifest 未声明的策略（漂移） |
+| `undeclared-trigger` | warn | 归属表上存在 manifest 未声明的触发器（含已禁用的，漂移） |
 | `rls-disabled` | error | 归属表 `relrowsecurity = false` |
 | `definer-without-search-path` | error | security definer 函数未设置固定 search_path（含空元素或 `pg_temp` 也算不固定） |
 | `security-mismatch` | warn | 声明的 invoker/definer 与 catalog 实际不一致 |
@@ -83,8 +106,25 @@ export const casesModule = defineDatabaseModule({
 | `grant-to-public` | error | `grant ... to public` |
 | `missing-rls-enable` | warn | 声明了策略但所有策略源文件都没有 `enable row level security` |
 | `drop-without-if-exists` | warn | `drop table/column` 缺少 `if exists` |
+| `non-idempotent-policy` | warn | `create policy` 前缺少 `drop policy if exists`（PostgreSQL CREATE POLICY 无 IF NOT EXISTS，不先 drop 就不可重复执行） |
 | `policy-without-test` | warn | 声明的策略/函数没有 `tests` 条目 |
 
+## Plan / Apply
+
+`planModule` 把模块声明编译为 `ModulePlan`（version 1）：每个声明对象（函数/策略/触发器/授权）对应一个 `PlanStep`，按依赖序 **function → policy → trigger → grant** 排列；每个 step 携带源文件内容的 sha256、`lintSql` 静态分析得出的 `risk`（error 级 lint 原样保留 severity=error），plan 级 `digest` 为全部 step sha256 的组合哈希。step 的 `name` 是对象标识：函数为 schema 限定名，策略/触发器为 `table.name`，授权为 `object:privilege:role`。
+
+`applyModulePlan` 的语义：
+
+1. plan 含任何 error 级 risk → 直接抛错拒绝执行，不触碰数据库。
+2. 确保账本：`create schema if not exists _supacloud` + `create table if not exists _supacloud.db_object_ledger(object_identity text primary key, module text, sha256 text, applied_at timestamptz default now())`。
+3. `pg_advisory_lock(hashtext('supacloud-db-apply'))` 串行化并发 apply，`finally` 中 unlock。
+4. 单事务内逐 step 执行：`object_identity = ${kind}:${name}` 查账本，sha256 一致则 `skipped`；否则执行 step.sql 并 upsert 账本。任何 step 失败 → ROLLBACK 并返回 `failed`；全成功 → COMMIT。
+5. 提交后 `readCatalog` 回读验证声明对象真实存在，结果进 `verified`，缺失进 `failed`。
+
+**幂等要求**：step.sql 必须可重复执行（`create or replace function`、`drop policy if exists` + `create policy`、`drop trigger if exists` + `create trigger`、`grant` 天然幂等）。sha256 一致即跳过，因此改源文件才会触发重放。executor 提供可选 `transaction(fn)` 时用它管理事务，否则退化为顺序执行 `begin/commit/rollback` 语句。
+
+**与 migration 的边界**：本执行器只管模块声明的**可重复 SQL 对象**（函数/策略/触发器/授权），不做表结构变更 —— 建表、加列等表结构演进仍走前向 migration（Drizzle/SQL migration 文件）。
+
 ## 与 Supabase / PostgreSQL 的关系
 
 SupaCloud 兼容 Supabase 的托管 PostgreSQL 模型：`authenticated` / `anon` / `service_role` 角色、RLS 策略、`security definer` RPC 都是治理对象。本包读取的系统目录（`pg_class` / `pg_policy` / `pg_proc` / `information_schema`）是标准 PostgreSQL 接口，因此同样适用于自托管 PostgreSQL；针对 Supabase 风格的角色与 schema 约定没有硬编码依赖。

package/dist/access.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Driver-independent database access boundary for request-scoped user clients
+ * and explicitly authorized service-role clients.
+ */
+export interface AuthenticatedDatabaseIdentity {
+    subject: string;
+    accessToken: string;
+}
+export interface DatabaseAccessBoundaryOptions<UserClient, ServiceClient> {
+    createUserClient(identity: AuthenticatedDatabaseIdentity): UserClient | Promise<UserClient>;
+    createServiceClient?: () => ServiceClient | Promise<ServiceClient>;
+    /** Service-role access is denied unless the supplied reason is allowlisted. */
+    allowedServiceReasons?: readonly string[];
+}
+export interface DatabaseAccessBoundary<UserClient, ServiceClient> {
+    /** Create an RLS-preserving client for the verified request identity. */
+    forUser(identity: AuthenticatedDatabaseIdentity): Promise<UserClient>;
+    /** Return a cached service-role client for an explicitly allowlisted reason. */
+    forService(reason: string): Promise<ServiceClient>;
+}
+export type DatabaseAccessErrorCode = "DATABASE_IDENTITY_REQUIRED" | "DATABASE_ACCESS_TOKEN_REQUIRED" | "SERVICE_ROLE_UNAVAILABLE" | "SERVICE_ROLE_REASON_REQUIRED" | "SERVICE_ROLE_REASON_NOT_ALLOWED";
+export declare class DatabaseAccessError extends Error {
+    readonly expose: true;
+    readonly code: DatabaseAccessErrorCode;
+    readonly status: number;
+    constructor(code: DatabaseAccessErrorCode, status: number, message: string);
+}
+export declare function createDatabaseAccessBoundary<UserClient, ServiceClient = never>(options: DatabaseAccessBoundaryOptions<UserClient, ServiceClient>): DatabaseAccessBoundary<UserClient, ServiceClient>;

package/dist/apply.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Apply：把 ModulePlan 落到数据库 —— 账本幂等 + advisory lock + 单事务 + catalog 回读验证。
+ * 边界与 plan 一致：只管模块声明的可重复 SQL 对象，不做表结构 migration。
+ */
+import { type QueryExecutor } from './catalog.js';
+import type { ModulePlan } from './plan.js';
+export interface ApplyResult {
+    module: string;
+    /** 实际执行了 SQL 的 step 名 */
+    applied: string[];
+    /** ledger 哈希一致跳过的 */
+    skipped: string[];
+    /** 应用后在 catalog 中确认存在的对象 */
+    verified: string[];
+    failed?: {
+        step: string;
+        error: string;
+    };
+}
+export declare function applyModulePlan(executor: QueryExecutor, plan: ModulePlan): Promise<ApplyResult>;

package/dist/catalog.d.ts

@@ -5,6 +5,11 @@
 import type { PolicyOperation } from './module.js';
 export interface QueryExecutor {
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * 可选事务封装：提供时 apply 用它包裹 begin/commit/rollback；
+     * 缺省时退化为在 executor 上顺序执行 begin/commit/rollback 语句（mock 友好）。
+     */
+    transaction?<T>(fn: (executor: QueryExecutor) => Promise<T>): Promise<T>;
 }
 export interface CatalogTable {
     schema: string;
@@ -28,6 +33,13 @@ export interface CatalogFunction {
     searchPath: string | null;
     language: string;
 }
+export interface CatalogTrigger {
+    schema: string;
+    table: string;
+    name: string;
+    /** tgenabled !== 'D'（未被 disable） */
+    enabled: boolean;
+}
 export interface CatalogGrant {
     objectSchema: string;
     objectName: string;
@@ -38,6 +50,7 @@ export interface DatabaseCatalog {
     tables: CatalogTable[];
     policies: CatalogPolicy[];
     functions: CatalogFunction[];
+    triggers: CatalogTrigger[];
     grants: CatalogGrant[];
 }
 /** 从 proconfig（text[]）中提取 search_path=... 配置，无则 null */

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { defineDatabaseModule, type DatabaseModule, type DatabaseModuleOptions, type DrizzleTableLike, type FunctionDecl, type GrantDecl, type PolicyDecl, type PolicyOperation, type TableRef, type TriggerDecl, } from './module.js';
-export { extractSearchPath, readCatalog, type CatalogFunction, type CatalogGrant, type CatalogPolicy, type CatalogTable, type DatabaseCatalog, type QueryExecutor, } from './catalog.js';
-export { reconcileModule, type ReconcileIssue, type ReconcileReport, } from './reconcile.js';
+export { extractSearchPath, readCatalog, type CatalogFunction, type CatalogGrant, type CatalogPolicy, type CatalogTable, type CatalogTrigger, type DatabaseCatalog, type QueryExecutor, } from './catalog.js';
+export { reconcileModule, splitQualifiedName, type ReconcileIssue, type ReconcileReport, } from './reconcile.js';
 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 { buildDatabaseManifest, explainObject, type DatabaseManifest, type DatabaseManifestModule, } from './manifest.js';
+export { createDatabaseAccessBoundary, DatabaseAccessError, type AuthenticatedDatabaseIdentity, type DatabaseAccessBoundary, type DatabaseAccessBoundaryOptions, type DatabaseAccessErrorCode, } from './access.js';

package/dist/index.js

@@ -56,6 +56,18 @@ JOIN pg_language l ON l.oid = p.prolang
 WHERE n.nspname = ANY($1)
 ORDER BY n.nspname, p.proname
 `;
+var TRIGGERS_SQL = `
+SELECT n.nspname AS schema,
+       c.relname AS table,
+       t.tgname AS name,
+       t.tgenabled <> 'D' AS enabled
+FROM pg_trigger t
+JOIN pg_class c ON c.oid = t.tgrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE NOT t.tgisinternal
+  AND n.nspname = ANY($1)
+ORDER BY n.nspname, c.relname, t.tgname
+`;
 var GRANTS_SQL = `
 SELECT table_schema AS object_schema,
        table_name AS object_name,
@@ -88,10 +100,11 @@ function extractSearchPath(config) {
 }
 async function readCatalog(executor, schemas = ["public"]) {
   const params = [schemas];
-  const [tableRows, policyRows, functionRows, grantRows] = await Promise.all([
+  const [tableRows, policyRows, functionRows, triggerRows, grantRows] = await Promise.all([
     executor.query(TABLES_SQL, params),
     executor.query(POLICIES_SQL, params),
     executor.query(FUNCTIONS_SQL, params),
+    executor.query(TRIGGERS_SQL, params),
     executor.query(GRANTS_SQL, params)
   ]);
   return {
@@ -117,6 +130,12 @@ async function readCatalog(executor, schemas = ["public"]) {
       searchPath: extractSearchPath(row.config),
       language: row.language
     })),
+    triggers: triggerRows.map((row) => ({
+      schema: row.schema,
+      table: row.table,
+      name: row.name,
+      enabled: row.enabled
+    })),
     grants: grantRows.map((row) => ({
       objectSchema: row.object_schema,
       objectName: row.object_name,
@@ -171,6 +190,20 @@ function reconcileModule(module, catalog) {
       push("error", "definer-without-search-path", fn.name, `security definer 函数 ${fn.name} 未设置固定 search_path（当前: ${cf.searchPath ?? "未设置"}）`);
     }
   }
+  for (const trigger of module.triggers) {
+    const [schema, table] = splitQualifiedName(trigger.table);
+    const found = catalog.triggers.some((ct) => ct.schema === schema && ct.table === table && ct.name === trigger.name);
+    if (!found) {
+      push("error", "missing-trigger", `${trigger.table}.${trigger.name}`, `声明的触发器 ${trigger.name} 在表 ${trigger.table} 的 catalog 中不存在`);
+    }
+  }
+  const declaredTriggerKeys = new Set(module.triggers.map((t) => `${t.table}::${t.name}`));
+  for (const ct of catalog.triggers) {
+    const qualified = `${ct.schema}.${ct.table}`;
+    if (ownedTables.has(qualified) && !declaredTriggerKeys.has(`${qualified}::${ct.name}`)) {
+      push("warn", "undeclared-trigger", `${qualified}.${ct.name}`, `归属表 ${qualified} 上存在未声明的触发器 ${ct.name}${ct.enabled ? "" : "（已禁用）"}，可能发生漂移`);
+    }
+  }
   for (const table of module.tables) {
     const [schema, name] = splitQualifiedName(table);
     const ct = catalog.tables.find((t) => t.schema === schema && t.name === name);
@@ -203,6 +236,8 @@ var SET_SEARCH_PATH_RE = /\bset\s+search_path\b/i;
 var GRANT_TO_PUBLIC_RE = /\bgrant\b[^;]*\bto\s+public\b/i;
 var DROP_WITHOUT_IF_EXISTS_RE = /\bdrop\s+(?:table|column)\s+(?!if\s+exists\b)/i;
 var ENABLE_RLS_RE = /\benable\s+row\s+level\s+security\b/i;
+var CREATE_POLICY_RE = /\bcreate\s+policy\b/i;
+var DROP_POLICY_IF_EXISTS_RE = /\bdrop\s+policy\s+if\s+exists\b/i;
 function lineOf(sql, index) {
   let line = 1;
   for (let i = 0;i < index; i += 1) {
@@ -243,6 +278,19 @@ function lintSql(sql, file) {
       line: lineOf(sql, drop.index)
     });
   }
+  const createPolicy = CREATE_POLICY_RE.exec(sql);
+  if (createPolicy) {
+    const dropPolicy = DROP_POLICY_IF_EXISTS_RE.exec(sql);
+    if (!dropPolicy || dropPolicy.index > createPolicy.index) {
+      issues.push({
+        severity: "warn",
+        code: "non-idempotent-policy",
+        message: "create policy 前缺少 drop policy if exists，策略不可重复执行",
+        file,
+        line: lineOf(sql, createPolicy.index)
+      });
+    }
+  }
   return issues;
 }
 async function lintModule(module, readFile) {
@@ -296,6 +344,193 @@ async function lintModule(module, readFile) {
   }
   return issues;
 }
+// src/plan.ts
+async function sha256Hex(content) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(content));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function planModule(module, readFile) {
+  const contents = new Map;
+  const load = async (path) => {
+    const cached = contents.get(path);
+    if (cached !== undefined)
+      return cached;
+    const sql = await readFile(path);
+    contents.set(path, sql);
+    return sql;
+  };
+  const steps = [];
+  const addStep = async (kind, name, source) => {
+    const sql = await load(source);
+    steps.push({
+      kind,
+      name,
+      source,
+      sha256: await sha256Hex(sql),
+      sql,
+      risk: lintSql(sql, source).map(({ severity, code, message }) => ({
+        severity,
+        code,
+        message
+      }))
+    });
+  };
+  for (const fn of module.functions) {
+    await addStep("function", fn.name, fn.source);
+  }
+  for (const policy of module.policies) {
+    await addStep("policy", `${policy.table}.${policy.name}`, policy.source);
+  }
+  for (const trigger of module.triggers) {
+    await addStep("trigger", `${trigger.table}.${trigger.name}`, trigger.source);
+  }
+  for (const grant of module.grants) {
+    await addStep("grant", `${grant.object}:${grant.privilege}:${grant.role}`, grant.source);
+  }
+  return {
+    version: 1,
+    module: module.name,
+    createdAt: new Date().toISOString(),
+    steps,
+    digest: await sha256Hex(steps.map((step) => step.sha256).join(`
+`))
+  };
+}
+// src/apply.ts
+var LEDGER_SCHEMA_SQL = "create schema if not exists _supacloud";
+var LEDGER_TABLE_SQL = `create table if not exists _supacloud.db_object_ledger(
+  object_identity text primary key,
+  module text not null,
+  sha256 text not null,
+  applied_at timestamptz not null default now()
+)`;
+var LOCK_SQL = `select pg_advisory_lock(hashtext('supacloud-db-apply'))`;
+var UNLOCK_SQL = `select pg_advisory_unlock(hashtext('supacloud-db-apply'))`;
+var LEDGER_READ_SQL = "select sha256 from _supacloud.db_object_ledger where object_identity = $1";
+var LEDGER_UPSERT_SQL = `insert into _supacloud.db_object_ledger (object_identity, module, sha256)
+values ($1, $2, $3)
+on conflict (object_identity) do update
+set module = excluded.module, sha256 = excluded.sha256, applied_at = now()`;
+
+class StepFailure extends Error {
+  step;
+  constructor(step, cause) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.step = step;
+  }
+}
+function toFailure(error) {
+  if (error instanceof StepFailure)
+    return { step: error.step, error: error.message };
+  return { step: "(unknown)", error: error instanceof Error ? error.message : String(error) };
+}
+async function runInTransaction(executor, fn) {
+  if (executor.transaction) {
+    try {
+      await executor.transaction(fn);
+      return;
+    } catch (error) {
+      return toFailure(error);
+    }
+  }
+  await executor.query("begin");
+  try {
+    await fn(executor);
+  } catch (error) {
+    await executor.query("rollback");
+    return toFailure(error);
+  }
+  await executor.query("commit");
+  return;
+}
+function existsInCatalog(step, catalog) {
+  switch (step.kind) {
+    case "function": {
+      const [schema, name] = splitQualifiedName(step.name);
+      return catalog.functions.some((f) => f.schema === schema && f.name === name);
+    }
+    case "policy": {
+      const [schema, table, ...rest] = step.name.split(".");
+      const name = rest.join(".");
+      return catalog.policies.some((p) => p.schema === schema && p.table === table && p.name === name);
+    }
+    case "trigger": {
+      const [schema, table, ...rest] = step.name.split(".");
+      const name = rest.join(".");
+      return catalog.triggers.some((t) => t.schema === schema && t.table === table && t.name === name);
+    }
+    case "grant": {
+      const [object, privilege, role] = step.name.split(":");
+      const [schema, name] = splitQualifiedName(object);
+      return catalog.grants.some((g) => g.objectSchema === schema && g.objectName === name && g.privilege.toLowerCase() === privilege.toLowerCase() && g.grantee.toLowerCase() === role.toLowerCase());
+    }
+  }
+}
+function planSchemas(plan) {
+  const schemas = new Set;
+  for (const step of plan.steps) {
+    const target = step.kind === "grant" ? step.name.split(":")[0] : step.name;
+    schemas.add(splitQualifiedName(target)[0]);
+  }
+  return schemas.size > 0 ? [...schemas].sort() : ["public"];
+}
+async function applyModulePlan(executor, plan) {
+  const errorRisks = plan.steps.flatMap((step) => step.risk.filter((risk) => risk.severity === "error").map((risk) => `${step.name}: ${risk.code} ${risk.message}`));
+  if (errorRisks.length > 0) {
+    throw new Error(`plan 含 error 级风险，拒绝执行: ${errorRisks.join("; ")}`);
+  }
+  const result = {
+    module: plan.module,
+    applied: [],
+    skipped: [],
+    verified: []
+  };
+  await executor.query(LEDGER_SCHEMA_SQL);
+  await executor.query(LEDGER_TABLE_SQL);
+  await executor.query(LOCK_SQL);
+  try {
+    const applied = [];
+    const skipped = [];
+    const failed = await runInTransaction(executor, async (tx) => {
+      for (const step of plan.steps) {
+        const identity = `${step.kind}:${step.name}`;
+        const rows = await tx.query(LEDGER_READ_SQL, [identity]);
+        if (rows[0]?.sha256 === step.sha256) {
+          skipped.push(step.name);
+          continue;
+        }
+        try {
+          await tx.query(step.sql);
+          await tx.query(LEDGER_UPSERT_SQL, [identity, plan.module, step.sha256]);
+        } catch (error) {
+          throw new StepFailure(step.name, error);
+        }
+        applied.push(step.name);
+      }
+    });
+    if (failed) {
+      result.failed = failed;
+      return result;
+    }
+    result.applied = applied;
+    result.skipped = skipped;
+  } finally {
+    await executor.query(UNLOCK_SQL);
+  }
+  const catalog = await readCatalog(executor, planSchemas(plan));
+  for (const step of plan.steps) {
+    if (existsInCatalog(step, catalog)) {
+      result.verified.push(step.name);
+    } else {
+      result.failed = {
+        step: step.name,
+        error: `应用后 catalog 中未找到 ${step.kind} ${step.name}`
+      };
+      break;
+    }
+  }
+  return result;
+}
 // src/manifest.ts
 function buildDatabaseManifest(modules) {
   return {
@@ -400,13 +635,65 @@ function explainObject(manifest, name) {
   }
   return `未找到对象: ${name}`;
 }
+// src/access.ts
+class DatabaseAccessError extends Error {
+  expose = true;
+  code;
+  status;
+  constructor(code, status, message) {
+    super(message);
+    this.name = "DatabaseAccessError";
+    this.code = code;
+    this.status = status;
+  }
+}
+function createDatabaseAccessBoundary(options) {
+  const allowedReasons = new Set(options.allowedServiceReasons ?? []);
+  let serviceClient;
+  return {
+    async forUser(identity) {
+      if (!identity.subject) {
+        throw new DatabaseAccessError("DATABASE_IDENTITY_REQUIRED", 401, "A verified user identity is required for request database access");
+      }
+      if (!identity.accessToken) {
+        throw new DatabaseAccessError("DATABASE_ACCESS_TOKEN_REQUIRED", 401, "A verified user access token is required for request database access");
+      }
+      return options.createUserClient({
+        subject: identity.subject,
+        accessToken: identity.accessToken
+      });
+    },
+    async forService(reason) {
+      const normalizedReason = reason.trim();
+      if (!normalizedReason) {
+        throw new DatabaseAccessError("SERVICE_ROLE_REASON_REQUIRED", 403, "Service-role database access requires a non-empty reason");
+      }
+      if (!allowedReasons.has(normalizedReason)) {
+        throw new DatabaseAccessError("SERVICE_ROLE_REASON_NOT_ALLOWED", 403, `Service-role database access reason "${normalizedReason}" is not allowed`);
+      }
+      if (!options.createServiceClient) {
+        throw new DatabaseAccessError("SERVICE_ROLE_UNAVAILABLE", 501, "Service-role database access is not configured");
+      }
+      serviceClient ??= Promise.resolve(options.createServiceClient()).catch((error) => {
+        serviceClient = undefined;
+        throw error;
+      });
+      return serviceClient;
+    }
+  };
+}
 export {
+  DatabaseAccessError,
+  applyModulePlan,
   buildDatabaseManifest,
+  createDatabaseAccessBoundary,
   defineDatabaseModule,
   explainObject,
   extractSearchPath,
   lintModule,
   lintSql,
+  planModule,
   readCatalog,
-  reconcileModule
+  reconcileModule,
+  splitQualifiedName
 };

package/dist/plan.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Plan：把模块声明的可重复 SQL 对象（函数/策略/触发器/授权）编译为有序执行计划。
+ * 边界：只管可重复对象，不做表结构 migration —— 表结构仍走前向 migration。
+ */
+import type { DatabaseModule } from './module.js';
+export interface PlanStep {
+    kind: 'function' | 'policy' | 'trigger' | 'grant';
+    /** 对象标识：函数为 schema 限定名；策略/触发器为 table.name；授权为 object:privilege:role */
+    name: string;
+    /** 模块相对路径 */
+    source: string;
+    /** 源文件内容哈希 */
+    sha256: string;
+    sql: string;
+    risk: Array<{
+        severity: 'error' | 'warn';
+        code: string;
+        message: string;
+    }>;
+}
+export interface ModulePlan {
+    version: 1;
+    module: string;
+    createdAt: string;
+    /** 依赖序：function -> policy -> trigger -> grant */
+    steps: PlanStep[];
+    /** 全部 step sha256 的组合哈希 */
+    digest: string;
+}
+export declare function planModule(module: DatabaseModule, readFile: (path: string) => Promise<string>): Promise<ModulePlan>;

package/dist/reconcile.d.ts

@@ -16,4 +16,6 @@ export interface ReconcileReport {
     /** 无 error 级问题 */
     ok: boolean;
 }
+/** 'public.cases' → ['public', 'cases']；无 schema 前缀时默认 public */
+export declare function splitQualifiedName(name: string): [string, string];
 export declare function reconcileModule(module: DatabaseModule, catalog: DatabaseCatalog): ReconcileReport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/db",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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",