@gencow/core 0.1.21 → 0.1.23

package/dist/crud.d.ts

@@ -118,23 +118,23 @@ export declare function parseFilterNode(node: Record<string, unknown>, table: an
  * ```
  */
 export declare function crud<T extends PgTable>(table: T, options?: CrudOptions<T>): {
-    list: import("./reactive").QueryDef<{
-        page: import("./v").Validator<number | undefined>;
-        limit: import("./v").Validator<number | undefined>;
-        search: import("./v").Validator<string | undefined>;
-        orderBy: import("./v").Validator<string | undefined>;
-        orderDir: import("./v").Validator<string | undefined>;
-        filters: import("./v").Validator<any>;
+    list: import("./reactive.js").QueryDef<{
+        page: import("./v.js").Validator<number | undefined>;
+        limit: import("./v.js").Validator<number | undefined>;
+        search: import("./v.js").Validator<string | undefined>;
+        orderBy: import("./v.js").Validator<string | undefined>;
+        orderDir: import("./v.js").Validator<string | undefined>;
+        filters: import("./v.js").Validator<any>;
     }, {
         data: any;
         total: number;
     }> | undefined;
-    get: import("./reactive").QueryDef<{
-        id: import("./v").Validator<string> | import("./v").Validator<number>;
+    get: import("./reactive.js").QueryDef<{
+        id: import("./v.js").Validator<string> | import("./v.js").Validator<number>;
     }, any> | undefined;
-    create: import("./reactive").MutationDef<any, any> | undefined;
-    update: import("./reactive").MutationDef<any, any> | undefined;
-    remove: import("./reactive").MutationDef<any, {
+    create: import("./reactive.js").MutationDef<any, any> | undefined;
+    update: import("./reactive.js").MutationDef<any, any> | undefined;
+    remove: import("./reactive.js").MutationDef<any, {
         success: boolean;
     }> | undefined;
 };

package/dist/crud.js

@@ -36,9 +36,9 @@
  */
 import { eq, ne, gt, gte, lt, lte, desc, asc, like, ilike, inArray, notInArray, or, and, count as drizzleCount, getTableName, getTableColumns } from "drizzle-orm";
 import { getTableConfig } from "drizzle-orm/pg-core";
-import { query, mutation } from "./reactive";
-import { v } from "./v";
-import { getOwnerRlsMeta, registerOwnerRls } from "./rls";
+import { query, mutation } from "./reactive.js";
+import { v } from "./v.js";
+import { getOwnerRlsMeta, registerOwnerRls } from "./rls.js";
 // ─── ownerRls 감지 추적 (부트 로그용) ──────────────────
 /** crud()가 ownerRls를 자동 감지한 테이블 목록 — 서버 부트 로그에서 출력 */
 const _ownerRlsTables = [];
@@ -321,7 +321,7 @@ export function crud(table, options) {
         return await fn(db);
     }
     // ── 내부 헬퍼: list+count 데이터 가져오기 (realtime push용 재사용) ──
-    // Runs inside db.transaction so createRlsDb() can SET LOCAL app.current_user_id for RLS.
+    // Runs inside db.transaction so createRlsDb() RLS session vars apply for RLS.
     // ⚠️ limit/offset 없이 전체 SELECT — 대량 데이터 시 성능 저하 주의
     // TODO(P2): realtime emit 시 invalidation 메시지만 전송하고 클라이언트가 re-fetch하는 패턴 검토
     async function fetchListWithTotal(db, whereClause, userId) {

package/dist/index.d.ts

@@ -4,21 +4,22 @@
  * Provides: query, mutation, storage, scheduler, auth
  * All with Convex-compatible DX patterns.
  */
-export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx, HttpActionDef, HttpActionRequest, HttpActionResponse, HttpActionHandler, AIContext, AIMessage, AIResult } from "./reactive";
-export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive";
-export type { Storage } from "./storage";
-export { createScheduler, getSchedulerInfo } from "./scheduler";
-export type { Scheduler, ScheduleOptions, FailedJob } from "./scheduler";
-export { v, parseArgs, GencowValidationError } from "./v";
-export type { Validator, Infer, InferArgs } from "./v";
-export { withRetry } from "./retry";
-export type { RetryOptions } from "./retry";
-export { cronJobs } from "./crons";
-export type { CronJobsBuilder, CronJobDef, IntervalOptions, DailyOptions, WeeklyOptions } from "./crons";
-export { defineAuth } from "./auth-config";
-export type { GencowAuthConfig, AuthEmailVerification } from "./auth-config";
-export { ownerRls, getOwnerRlsMeta, registerOwnerRls } from "./rls";
-export type { OwnerRlsMeta } from "./rls";
-export { createRlsDb } from "./rls-db";
-export { crud, parseFilterNode, applyFilterOp, getOwnerRlsTables } from "./crud";
-export { crud as gencowCrud } from "./crud";
+export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx, HttpActionDef, HttpActionRequest, HttpActionResponse, HttpActionHandler, AIContext, AIMessage, AIResult } from "./reactive.js";
+export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive.js";
+export type { Storage } from "./storage.js";
+export { createScheduler, getSchedulerInfo } from "./scheduler.js";
+export type { Scheduler, ScheduleOptions, FailedJob, CreateSchedulerOptions, ScheduledJobRecord } from "./scheduler.js";
+export { v, parseArgs, GencowValidationError } from "./v.js";
+export type { Validator, Infer, InferArgs } from "./v.js";
+export { withRetry } from "./retry.js";
+export type { RetryOptions } from "./retry.js";
+export { cronJobs } from "./crons.js";
+export type { CronJobsBuilder, CronJobDef, IntervalOptions, DailyOptions, WeeklyOptions } from "./crons.js";
+export { defineAuth } from "./auth-config.js";
+export type { GencowAuthConfig, AuthEmailVerification } from "./auth-config.js";
+export { ownerRls, getOwnerRlsMeta, registerOwnerRls } from "./rls.js";
+export type { OwnerRlsMeta } from "./rls.js";
+export { createRlsDb } from "./rls-db.js";
+export type { RlsSessionContext } from "./rls-db.js";
+export { crud, parseFilterNode, applyFilterOp, getOwnerRlsTables } from "./crud.js";
+export { crud as gencowCrud } from "./crud.js";

package/dist/index.js

@@ -4,15 +4,15 @@
  * Provides: query, mutation, storage, scheduler, auth
  * All with Convex-compatible DX patterns.
  */
-export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive";
-export { createScheduler, getSchedulerInfo } from "./scheduler";
-export { v, parseArgs, GencowValidationError } from "./v";
-export { withRetry } from "./retry";
-export { cronJobs } from "./crons";
-export { defineAuth } from "./auth-config";
+export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive.js";
+export { createScheduler, getSchedulerInfo } from "./scheduler.js";
+export { v, parseArgs, GencowValidationError } from "./v.js";
+export { withRetry } from "./retry.js";
+export { cronJobs } from "./crons.js";
+export { defineAuth } from "./auth-config.js";
 // ─── RLS + CRUD Factory ───────────
-export { ownerRls, getOwnerRlsMeta, registerOwnerRls } from "./rls";
-export { createRlsDb } from "./rls-db";
-export { crud, parseFilterNode, applyFilterOp, getOwnerRlsTables } from "./crud";
+export { ownerRls, getOwnerRlsMeta, registerOwnerRls } from "./rls.js";
+export { createRlsDb } from "./rls-db.js";
+export { crud, parseFilterNode, applyFilterOp, getOwnerRlsTables } from "./crud.js";
 // Deprecated alias — 하위호환용, 향후 메이저 버전에서 제거 예정
-export { crud as gencowCrud } from "./crud";
+export { crud as gencowCrud } from "./crud.js";

package/dist/reactive.d.ts

@@ -1,7 +1,7 @@
 import type { WSContext } from "hono/ws";
-import type { Storage } from "./storage";
-import type { Scheduler } from "./scheduler";
-import { type InferArgs } from "./v";
+import type { Storage } from "./storage.js";
+import type { Scheduler } from "./scheduler.js";
+import { type InferArgs } from "./v.js";
 export interface UserIdentity {
     id: string;
     email: string;
@@ -100,7 +100,7 @@ export interface GencowCtx {
     /** 실시간 push — ctx.realtime.emit(queryKey, data) */
     realtime: RealtimeCtx;
     /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
-    retry: <T>(fn: () => Promise<T>, options?: import("./retry").RetryOptions) => Promise<T>;
+    retry: <T>(fn: () => Promise<T>, options?: import("./retry.js").RetryOptions) => Promise<T>;
     /** AI 헬퍼 */
     ai?: AIContext;
 }

package/dist/reactive.js

@@ -239,6 +239,12 @@ export function buildRealtimeCtx(options) {
                 }
                 try {
                     // refresh용 ctx 생성 (mutation ctx와 동일한 DB/auth 스코프)
+                    if (!options?.buildCtxForRefresh) {
+                        console.warn(`[gencow] ⚠️  refresh("${key}"): buildCtxForRefresh not provided. ` +
+                            `Query handler will receive an empty ctx — ctx.db will be undefined. ` +
+                            `This is a framework configuration error. ` +
+                            `💡 Ensure buildRealtimeCtx() receives a buildCtxForRefresh callback.`);
+                    }
                     const refreshCtx = options?.buildCtxForRefresh?.() ?? {};
                     const result = await queryDef.handler(refreshCtx, {});
                     // emit과 동일한 경로로 push

package/dist/rls-db.d.ts

@@ -1,8 +1,47 @@
 import type { PgDatabase } from "drizzle-orm/pg-core";
 /**
- * Wraps Drizzle so `transaction()` runs `set_config('app.current_user_id', ...)` first (RLS policies).
- * Supabase-style session GUC injection.
+ * RLS DB wrapper — execution paths for `withRlsConnection`:
+ * 1. **Reuse outer Drizzle transaction** (`reuseOuterConnection`): same connection, apply GUCs then run `fn`.
+ * 2. **Bun SQL** (`session.client.begin`): short transaction around `fn`.
+ * 3. **PGlite / drivers with `transaction()`**: delegate to driver helper.
+ * 4. **node-pg Pool** (`connect` + `query`): lease a client, BEGIN → set_config → `fn` → COMMIT, or ROLLBACK on error, then `release()`.
+ */
+/**
+ * Values pushed into PostgreSQL session GUCs (`set_config(..., true)`) for RLS / tenant checks.
+ * Optional fields become `app.*` settings; add arbitrary allowed keys via `vars`.
+ */
+export type RlsSessionContext = {
+    /** `app.current_user_id` — required by `ownerRls()` policies in this repo. */
+    userId: string;
+    /** When set: `app.current_user_role`. */
+    role?: string;
+    /** When set: `app.tenant_id`. */
+    tenantId?: string;
+    /**
+     * Extra transaction-local settings: keys must be validated `app.*` GUC names
+     * and must not duplicate `app.current_user_id` / `app.current_user_role` / `app.tenant_id`
+     * (use the top-level fields for those).
+     */
+    vars?: Record<string, string>;
+};
+/**
+ * pg `Pool.connect()`-style client: BEGIN → apply RLS GUCs → `fn` → COMMIT on success,
+ * or ROLLBACK if anything fails (including failed COMMIT). Always `release()` in `finally`.
+ *
+ * @internal Exported only for unit tests — not re-exported from `@gencow/core` public API.
+ */
+export declare function withRlsLeasedConnection<T>(leased: {
+    query: (sql: string) => Promise<unknown>;
+    release: () => void;
+}, rls: RlsSessionContext, fn: (client: {
+    query: (sql: string) => Promise<unknown>;
+    release: () => void;
+}) => Promise<T>): Promise<T>;
+/**
+ * RLS-scoped Drizzle handle: every query path (`select`, `insert`, `execute`, …) runs
+ * `set_config` for the given context in the same DB transaction as the query
+ * (PgBouncer–safe transaction-local GUCs).
  *
- * `set_config(..., true)` is transaction-local (safe with PgBouncer transaction pooling).
+ * `db.transaction()` still injects the same variables at the start of the callback transaction.
  */
-export declare function createRlsDb(db: PgDatabase<any, any, any>, userId: string): PgDatabase<any, any, any>;
+export declare function createRlsDb(db: PgDatabase<any, any, any>, rls: RlsSessionContext): PgDatabase<any, any, any>;

package/dist/rls-db.js

@@ -1,23 +1,228 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { sql } from "drizzle-orm";
+const gucNameRe = /^app\.[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/;
+const RESERVED_VARS_KEYS = new Set([
+    "app.current_user_id",
+    "app.current_user_role",
+    "app.tenant_id",
+]);
+function assertSafeGucName(key) {
+    if (!gucNameRe.test(key)) {
+        throw new Error(`createRlsDb: GUC name "${key}" is invalid — use lowercase app.* names (e.g. app.org_id)`);
+    }
+}
+/** Ordered `(name, value)` pairs for `set_config(name, value, true)`. */
+function rlsSetConfigPairs(rls) {
+    const pairs = [["app.current_user_id", rls.userId]];
+    if (rls.role !== undefined) {
+        pairs.push(["app.current_user_role", rls.role]);
+    }
+    if (rls.tenantId !== undefined) {
+        pairs.push(["app.tenant_id", rls.tenantId]);
+    }
+    if (rls.vars) {
+        for (const [key, value] of Object.entries(rls.vars)) {
+            assertSafeGucName(key);
+            if (RESERVED_VARS_KEYS.has(key)) {
+                throw new Error(`createRlsDb: vars must not set "${key}" — use userId, role, or tenantId on the context object`);
+            }
+            pairs.push([key, value]);
+        }
+    }
+    return pairs;
+}
+async function forEachSetConfig(rls, setOne) {
+    for (const [name, value] of rlsSetConfigPairs(rls)) {
+        await setOne(name, value);
+    }
+}
+/**
+ * While a prepared query runs, nested queries reuse this client (same outer `begin` / tx).
+ */
+const rlsExecClient = new AsyncLocalStorage();
+function isDrizzleTransactionDb(db) {
+    const d = db;
+    if (typeof d?.rollback === "function") {
+        return true;
+    }
+    const name = d?.constructor?.name;
+    return typeof name === "string" && name.includes("Transaction");
+}
+async function execSetConfig(client, name, value) {
+    if (typeof client?.unsafe === "function") {
+        await client.unsafe(`select set_config($1::text, $2::text, true)`, [name, value]);
+        return;
+    }
+    if (typeof client?.query === "function") {
+        await client.query(`select set_config($1::text, $2::text, true)`, [name, value]);
+        return;
+    }
+    throw new Error("createRlsDb: unsupported SQL driver (expected Bun SQL, node-pg client/pool, or PGlite)");
+}
+async function applyRlsSessionVars(client, rls) {
+    await forEachSetConfig(rls, (name, value) => execSetConfig(client, name, value));
+}
+async function injectRlsVarsOnTx(tx, rls) {
+    await forEachSetConfig(rls, (name, value) => tx.execute(sql `SELECT set_config(${name}, ${value}, true)`));
+}
+/**
+ * pg `Pool.connect()`-style client: BEGIN → apply RLS GUCs → `fn` → COMMIT on success,
+ * or ROLLBACK if anything fails (including failed COMMIT). Always `release()` in `finally`.
+ *
+ * @internal Exported only for unit tests — not re-exported from `@gencow/core` public API.
+ */
+export async function withRlsLeasedConnection(leased, rls, fn) {
+    try {
+        await leased.query("begin");
+        await applyRlsSessionVars(leased, rls);
+        const result = await rlsExecClient.run(leased, () => fn(leased));
+        await leased.query("commit");
+        return result;
+    }
+    catch (e) {
+        try {
+            await leased.query("rollback");
+        }
+        catch {
+            /* ignore */
+        }
+        throw e;
+    }
+    finally {
+        leased.release();
+    }
+}
+/**
+ * Runs `fn` with a connection that has transaction-local RLS session variables set.
+ * Pool / autocommit: opens a short transaction (Bun `begin`, PGlite `transaction`).
+ * When `db` is already a Drizzle transaction object, reuses that connection (no nested top-level tx).
+ */
+async function withRlsConnection(session, rls, reuseOuterConnection, fn) {
+    if (reuseOuterConnection) {
+        const c = session.client;
+        return rlsExecClient.run(c, async () => {
+            await applyRlsSessionVars(c, rls);
+            return fn(c);
+        });
+    }
+    const c = session.client;
+    const runInner = async (client) => {
+        await applyRlsSessionVars(client, rls);
+        return rlsExecClient.run(client, () => fn(client));
+    };
+    if (typeof c.begin === "function") {
+        return c.begin(runInner);
+    }
+    if (typeof c.transaction === "function") {
+        return c.transaction(runInner);
+    }
+    if (typeof c.connect === "function" && typeof c.query === "function") {
+        const leased = await c.connect();
+        return withRlsLeasedConnection(leased, rls, fn);
+    }
+    return runInner(c);
+}
+function wrapPreparedQuery(pq, session, rls, reuseOuterConnection) {
+    const origExecute = pq.execute.bind(pq);
+    const origAll = pq.all.bind(pq);
+    pq.execute = async (placeholderValues) => {
+        const active = rlsExecClient.getStore();
+        if (active) {
+            const prev = pq.client;
+            pq.client = active;
+            try {
+                return await origExecute(placeholderValues);
+            }
+            finally {
+                pq.client = prev;
+            }
+        }
+        return withRlsConnection(session, rls, reuseOuterConnection, async (client) => {
+            const prev = pq.client;
+            pq.client = client;
+            try {
+                return await origExecute(placeholderValues);
+            }
+            finally {
+                pq.client = prev;
+            }
+        });
+    };
+    pq.all = async (placeholderValues) => {
+        const active = rlsExecClient.getStore();
+        if (active) {
+            const prev = pq.client;
+            pq.client = active;
+            try {
+                return await origAll(placeholderValues);
+            }
+            finally {
+                pq.client = prev;
+            }
+        }
+        return withRlsConnection(session, rls, reuseOuterConnection, async (client) => {
+            const prev = pq.client;
+            pq.client = client;
+            try {
+                return await origAll(placeholderValues);
+            }
+            finally {
+                pq.client = prev;
+            }
+        });
+    };
+}
+function wrapSession(session, rls, reuseOuterConnection) {
+    return new Proxy(session, {
+        get(sTarget, sProp, sRecv) {
+            if (sProp === "prepareQuery") {
+                return (...args) => {
+                    const pq = sTarget.prepareQuery(...args);
+                    wrapPreparedQuery(pq, sTarget, rls, reuseOuterConnection);
+                    return pq;
+                };
+            }
+            const v = Reflect.get(sTarget, sProp, sRecv);
+            return typeof v === "function" ? v.bind(sTarget) : v;
+        },
+    });
+}
 /**
- * Wraps Drizzle so `transaction()` runs `set_config('app.current_user_id', ...)` first (RLS policies).
- * Supabase-style session GUC injection.
+ * RLS-scoped Drizzle handle: every query path (`select`, `insert`, `execute`, …) runs
+ * `set_config` for the given context in the same DB transaction as the query
+ * (PgBouncer–safe transaction-local GUCs).
  *
- * `set_config(..., true)` is transaction-local (safe with PgBouncer transaction pooling).
+ * `db.transaction()` still injects the same variables at the start of the callback transaction.
  */
-export function createRlsDb(db, userId) {
+export function createRlsDb(db, rls) {
+    const reuseOuterConnection = isDrizzleTransactionDb(db);
+    const baseSession = db.session;
+    const wrappedSession = wrapSession(baseSession, rls, reuseOuterConnection);
     return new Proxy(db, {
         get(target, prop, receiver) {
+            if (prop === "session") {
+                return wrappedSession;
+            }
+            if (prop === "_") {
+                const inner = target._;
+                return new Proxy(inner, {
+                    get(i, p, r) {
+                        if (p === "session")
+                            return wrappedSession;
+                        return Reflect.get(i, p, r);
+                    },
+                });
+            }
             if (prop === "transaction") {
                 return async (callback, ...rest) => {
                     return await target.transaction(async (tx) => {
-                        await tx.execute(sql `SELECT set_config('app.current_user_id', ${userId}, true)`);
+                        await injectRlsVarsOnTx(tx, rls);
                         return await callback(tx);
                     }, ...rest);
                 };
             }
             const value = Reflect.get(target, prop, receiver);
-            return typeof value === "function" ? value.bind(target) : value;
-        }
+            return typeof value === "function" ? value.bind(receiver) : value;
+        },
     });
 }

package/dist/rls.d.ts

@@ -24,7 +24,7 @@ export declare function registerOwnerRls(table: PgTable, meta: OwnerRlsMeta): vo
  *   모든 CRUD 쿼리에 WHERE userId = auth.userId 자동 주입.
  *   PGlite + PostgreSQL 양쪽에서 동작.
  * - Layer 2 (DB 레벨): PostgreSQL RLS 정책으로 심층 방어.
- *   createRlsDb()의 transaction() 내에서 set_config 주입.
+ *   createRlsDb()가 RlsSessionContext로 set_config 주입.
  *
  * @example
  * ```ts

package/dist/rls.js

@@ -25,7 +25,7 @@ export function registerOwnerRls(table, meta) {
  *   모든 CRUD 쿼리에 WHERE userId = auth.userId 자동 주입.
  *   PGlite + PostgreSQL 양쪽에서 동작.
  * - Layer 2 (DB 레벨): PostgreSQL RLS 정책으로 심층 방어.
- *   createRlsDb()의 transaction() 내에서 set_config 주입.
+ *   createRlsDb()가 RlsSessionContext로 set_config 주입.
  *
  * @example
  * ```ts

package/dist/scheduler.d.ts

@@ -4,6 +4,28 @@ export interface ScheduleOptions {
     /** 실패 시 호출할 action 이름 (dead-letter 패턴) */
     onError?: string;
 }
+/** scheduled job의 DB 영속화를 위한 콜백 */
+export interface ScheduledJobRecord {
+    id: string;
+    action: string;
+    args: unknown;
+    runAt: Date;
+    onErrorAction?: string;
+}
+/**
+ * createScheduler 옵션.
+ *
+ * persistJob/removeJob이 주어지면 runAfter()가 setTimeout 대신 DB에 영속화.
+ * 외부 폴러(Platform Cron Runner)가 주기적으로 due된 job을 조회하여 실행.
+ *
+ * 콜백 미설정 시 기존 인메모리 setTimeout 동작 유지 (로컬 dev).
+ */
+export interface CreateSchedulerOptions {
+    /** Job을 DB에 영속화 (INSERT) */
+    persistJob?: (job: ScheduledJobRecord) => Promise<void>;
+    /** Job을 DB에서 제거 (DELETE) — cancel/완료 시 */
+    removeJob?: (jobId: string) => Promise<boolean>;
+}
 /** 실패한 작업의 기록 */
 export interface FailedJob {
     id: string;
@@ -29,18 +51,26 @@ export interface Scheduler {
 /**
  * Create a scheduler instance — Convex scheduler 패턴 재현
  *
+ * @param options  persistJob/removeJob 콜백을 전달하면 durable mode 활성화.
+ *                 BaaS 모드에서는 서버가 DB 콜백을 전달하여 sleep-safe 보장.
+ *                 로컬 dev에서는 콜백 없이 호출하여 기존 setTimeout 동작.
+ *
  * @example
+ * // 로컬 dev (인메모리)
  * const scheduler = createScheduler();
  *
+ * // BaaS (DB-backed durable)
+ * const scheduler = createScheduler({
+ *     persistJob: async (job) => { await rawSql('INSERT INTO ...', ...) },
+ *     removeJob: async (id) => { await rawSql('DELETE FROM ...', [id]) },
+ * });
+ *
  * // Register actions
  * scheduler.registerAction('emails.send', async (args) => { ... });
  *
- * // Schedule (Convex-style)
+ * // Schedule (Convex-style) — durable mode에서는 DB에 영속화
  * scheduler.runAfter(5 * 60 * 1000, 'emails.send', { to: 'user@test.com' });
  *
- * // Schedule with error callback (dead-letter 패턴)
- * scheduler.runAfter(0, 'pipeline.step2', args, { onError: 'pipeline.onStepError' });
- *
  * // Cron (Convex-style)
  * scheduler.cron('daily-cleanup', '0 2 * * *', async () => { ... });
  */
@@ -60,5 +90,5 @@ export declare function getSchedulerInfo(): {
     pendingJobs: PendingJobEntry[];
     failedJobs: FailedJob[];
 };
-export declare function createScheduler(): Scheduler;
+export declare function createScheduler(options?: CreateSchedulerOptions): Scheduler;
 export {};