@gencow/core 0.1.7 → 0.1.9

package/dist/storage.js

@@ -4,53 +4,137 @@ import * as crypto from "crypto";
 // ─── Constants ──────────────────────────────────────────
 /** 파일 업로드 최대 크기: 50MB (하드코딩 — 사용자가 오버라이드 불가) */
 const MAX_FILE_SIZE = 50 * 1024 * 1024;
+/** 기본 스토리지 쿼터: 1GB */
+const DEFAULT_STORAGE_QUOTA = 1024 * 1024 * 1024;
 function formatBytes(bytes) {
     if (bytes < 1024)
         return `${bytes}B`;
     if (bytes < 1024 * 1024)
         return `${(bytes / 1024).toFixed(1)}KB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
 }
 // ─── Implementation ─────────────────────────────────────
 const metaStore = new Map();
+/**
+ * files 테이블 자동 생성 (이미 존재하면 무시)
+ * admin.ts의 CREATE_FILES_TABLE_SQL과 동일한 스키마 사용
+ */
+let filesTableEnsured = false;
+async function ensureFilesTable(rawSql) {
+    if (filesTableEnsured)
+        return;
+    await rawSql(`
+        DO $$
+        BEGIN
+            IF NOT EXISTS (
+                SELECT 1 FROM information_schema.tables
+                WHERE table_schema = current_schema()
+                AND table_name = 'files'
+            ) THEN
+                CREATE TABLE files (
+                    id SERIAL PRIMARY KEY,
+                    storage_id TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    size TEXT NOT NULL,
+                    type TEXT NOT NULL DEFAULT 'application/octet-stream',
+                    uploaded_by TEXT DEFAULT 'api',
+                    created_at TIMESTAMP DEFAULT NOW()
+                );
+            END IF;
+        END$$;
+    `);
+    filesTableEnsured = true;
+}
+/**
+ * 스토리지 쿼터 검증 — 현재 총 사용량 + 새 파일 크기가 쿼터를 초과하는지 확인
+ */
+async function checkStorageQuota(rawSql, newFileSize, quota) {
+    if (quota <= 0)
+        return; // 무제한
+    const rows = await rawSql(`SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM files`);
+    const currentUsage = Number(rows[0]?.total || "0");
+    const projectedUsage = currentUsage + newFileSize;
+    if (projectedUsage > quota) {
+        throw new Error(`Storage quota exceeded: ${formatBytes(currentUsage)} used + ${formatBytes(newFileSize)} new = ${formatBytes(projectedUsage)}, ` +
+            `quota is ${formatBytes(quota)}. Delete files or increase quota.`);
+    }
+}
+/**
+ * DB에 파일 메타데이터 기록 — store() 호출 시 자동 수행
+ *
+ * 대시보드 업로드(admin.ts)는 uploaded_by='dashboard'로 별도 INSERT하므로,
+ * 여기서는 skipDbRecord 옵션으로 중복 방지 가능.
+ */
+async function recordFileToDb(rawSql, storageId, name, size, type, uploadedBy = "api") {
+    await ensureFilesTable(rawSql);
+    await rawSql(`INSERT INTO files (storage_id, name, size, type, uploaded_by, created_at)
+         VALUES ($1, $2, $3, $4, $5, NOW())`, [storageId, name, String(size), type, uploadedBy]);
+}
 /**
  * Create a storage instance — Convex storage 패턴 재현
  *
+ * @param dir - 파일 저장 디렉토리
+ * @param options - DB 연동 + 쿼터 옵션
+ *
  * @example
- * const storage = createStorage('./uploads');
+ * const storage = createStorage('./uploads', { rawSql, storageQuota: 1024 * 1024 * 1024 });
  * const id = await storage.store(file);
  * const url = storage.getUrl(id);
  */
-export function createStorage(dir = "./uploads") {
+export function createStorage(dir = "./uploads", options) {
+    const rawSql = options?.rawSql;
+    const quota = options?.storageQuota ?? DEFAULT_STORAGE_QUOTA;
     // Ensure directory exists
     fs.mkdir(dir, { recursive: true }).catch(() => { });
     return {
         async store(file, filename) {
-            // 크기 제한 검증
+            // 크기 제한 검증 (단일 파일)
             if (file.size > MAX_FILE_SIZE) {
                 throw new Error(`File too large: ${formatBytes(file.size)} exceeds limit of ${formatBytes(MAX_FILE_SIZE)}`);
             }
+            // 스토리지 쿼터 검증 (앱 전체 용량)
+            if (rawSql) {
+                await checkStorageQuota(rawSql, file.size, quota);
+            }
             const id = crypto.randomUUID();
             const name = filename || (file instanceof File ? file.name : `${id}.bin`);
             const filePath = path.join(dir, id);
             const arrayBuffer = await file.arrayBuffer();
             await fs.writeFile(filePath, Buffer.from(arrayBuffer));
+            const type = file.type || "application/octet-stream";
             metaStore.set(id, {
                 id,
                 name,
                 size: file.size,
-                type: file.type || "application/octet-stream",
+                type,
                 path: filePath,
             });
+            // DB 자동 기록 (rawSql 있을 때만)
+            if (rawSql) {
+                try {
+                    await recordFileToDb(rawSql, id, name, file.size, type, "api");
+                }
+                catch (e) {
+                    // DB 기록 실패해도 파일 저장은 성공 — 로그만 남김
+                    const msg = e instanceof Error ? e.message : String(e);
+                    console.warn(`[storage] DB record failed for ${id}: ${msg}`);
+                }
+            }
             return id;
         },
         async storeBuffer(buffer, filename, type = "application/octet-stream") {
-            const id = crypto.randomUUID();
-            const filePath = path.join(dir, id);
-            // 크기 제한 검증
+            // 크기 제한 검증 (단일 파일)
             if (buffer.length > MAX_FILE_SIZE) {
                 throw new Error(`File too large: ${formatBytes(buffer.length)} exceeds limit of ${formatBytes(MAX_FILE_SIZE)}`);
             }
+            // 스토리지 쿼터 검증 (앱 전체 용량)
+            if (rawSql) {
+                await checkStorageQuota(rawSql, buffer.length, quota);
+            }
+            const id = crypto.randomUUID();
+            const filePath = path.join(dir, id);
             await fs.writeFile(filePath, buffer);
             metaStore.set(id, {
                 id,
@@ -59,6 +143,16 @@ export function createStorage(dir = "./uploads") {
                 type,
                 path: filePath,
             });
+            // DB 자동 기록
+            if (rawSql) {
+                try {
+                    await recordFileToDb(rawSql, id, filename, buffer.length, type, "api");
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    console.warn(`[storage] DB record failed for ${id}: ${msg}`);
+                }
+            }
             return id;
         },
         getUrl(storageId) {
@@ -73,11 +167,21 @@ export function createStorage(dir = "./uploads") {
                 await fs.unlink(meta.path).catch(() => { });
                 metaStore.delete(storageId);
             }
+            // DB에서도 삭제 (rawSql 있을 때만)
+            if (rawSql) {
+                try {
+                    await rawSql(`DELETE FROM files WHERE storage_id = $1`, [storageId]);
+                }
+                catch { /* 삭제 실패 무시 — 파일은 이미 제거됨 */ }
+            }
         },
     };
 }
 /**
  * Hono routes for serving stored files
+ *
+ * 인증 없이 public URL로 서빙 — Convex getUrl() 패턴과 동일.
+ * 접근 제어는 URL을 반환하는 query/mutation 레벨에서 개발자가 구현.
  */
 export function storageRoutes(storage, rawSql, storageDir) {
     return async (c) => {

package/dist/table.d.ts

@@ -0,0 +1,67 @@
+/**
+ * packages/core/src/table.ts
+ *
+ * gencowTable() — Drizzle pgTable wrapper with schema-level access control.
+ * Inspired by KeystoneJS's declarative filter pattern.
+ *
+ * Run tests: bun test packages/core/src/__tests__/table.test.ts
+ */
+import { pgTable } from "drizzle-orm/pg-core";
+import type { GencowCtx } from "./reactive";
+import type { SQL } from "drizzle-orm";
+/**
+ * Access control filter function.
+ * Returns a Drizzle SQL condition, `true` (allow all), or `false` (deny all).
+ * Can be async (e.g., for team membership lookups).
+ */
+export type AccessFilter = (ctx: GencowCtx) => SQL | boolean | Promise<SQL | boolean>;
+/** Field-level access control: per-field read permission. */
+export interface FieldAccessRule {
+    read: (ctx: GencowCtx) => boolean;
+}
+/** Options for gencowTable — access control metadata. */
+export interface GencowTableOptions {
+    /** Row-level filter — auto-injected into all queries on this table */
+    filter: AccessFilter;
+    /** Field-level access — unauthorized fields are nullified in results */
+    fieldAccess?: Record<string, FieldAccessRule>;
+}
+/** Stored metadata for a gencowTable. */
+export interface TableAccessMeta {
+    filter: AccessFilter;
+    fieldAccess?: Record<string, FieldAccessRule>;
+    tableName: string;
+}
+declare global {
+    var __gencow_tableAccessRegistry: Map<any, TableAccessMeta>;
+}
+/**
+ * Drizzle pgTable wrapper with schema-level access control.
+ *
+ * Creates a standard Drizzle pgTable (100% compatible) and registers
+ * filter + fieldAccess metadata that ctx.db Proxy uses to auto-inject
+ * WHERE clauses.
+ *
+ * @param name    - PostgreSQL table name
+ * @param columns - Drizzle column definitions (same as pgTable)
+ * @param options - Access control (filter required, fieldAccess optional)
+ */
+export declare function gencowTable<T extends Record<string, any>>(name: string, columns: T, options: GencowTableOptions): ReturnType<typeof pgTable<string, T>>;
+/**
+ * Convenience helper for userId-based isolation.
+ *
+ * Usage:
+ *   export const tasks = gencowTable("tasks", { ... }, ownerFilter("userId"));
+ *   export const files = gencowTable("files", { ... }, ownerFilter("ownerId"));
+ *
+ * @param columnName - Name of the user ID column (default: "userId")
+ */
+export declare function ownerFilter(columnName?: string): GencowTableOptions;
+/** Get access control metadata for a table. Returns undefined for plain pgTable. */
+export declare function getTableAccessMeta(table: any): TableAccessMeta | undefined;
+/** Check if a table has gencowTable metadata registered. */
+export declare function isGencowTable(table: any): boolean;
+/** Get all registered gencowTables (for audit/boot-time checks). */
+export declare function getAllGencowTables(): Map<any, TableAccessMeta>;
+/** Reset registry (for testing only). */
+export declare function _resetTableRegistry(): void;

package/dist/table.js

@@ -0,0 +1,98 @@
+/**
+ * packages/core/src/table.ts
+ *
+ * gencowTable() — Drizzle pgTable wrapper with schema-level access control.
+ * Inspired by KeystoneJS's declarative filter pattern.
+ *
+ * Run tests: bun test packages/core/src/__tests__/table.test.ts
+ */
+import { pgTable } from "drizzle-orm/pg-core";
+import { eq } from "drizzle-orm";
+function isOwnerFilter(opts) {
+    return "_ownerColumn" in opts;
+}
+if (!globalThis.__gencow_tableAccessRegistry) {
+    globalThis.__gencow_tableAccessRegistry = new Map();
+}
+const tableAccessRegistry = globalThis.__gencow_tableAccessRegistry;
+// ─── gencowTable() ──────────────────────────────────────
+/**
+ * Drizzle pgTable wrapper with schema-level access control.
+ *
+ * Creates a standard Drizzle pgTable (100% compatible) and registers
+ * filter + fieldAccess metadata that ctx.db Proxy uses to auto-inject
+ * WHERE clauses.
+ *
+ * @param name    - PostgreSQL table name
+ * @param columns - Drizzle column definitions (same as pgTable)
+ * @param options - Access control (filter required, fieldAccess optional)
+ */
+export function gencowTable(name, columns, options) {
+    if (!options || (typeof options.filter !== "function" && !isOwnerFilter(options))) {
+        throw new Error(`[gencow] gencowTable("${name}") requires a filter option. ` +
+            `Use ownerFilter("userId") for simple user isolation, ` +
+            `or { filter: () => true } for public tables.`);
+    }
+    // Create standard Drizzle pgTable — fully compatible
+    const table = pgTable(name, columns);
+    // Resolve ownerFilter to a concrete filter bound to this table
+    let filter;
+    if (isOwnerFilter(options)) {
+        const columnName = options._ownerColumn;
+        const col = table[columnName];
+        if (!col) {
+            throw new Error(`[gencow] ownerFilter("${columnName}"): column "${columnName}" not found on table "${name}". ` +
+                `Available columns: ${Object.keys(table).filter(k => !k.startsWith("_") && !k.startsWith("$")).join(", ")}`);
+        }
+        filter = (ctx) => {
+            const user = ctx.auth.requireAuth();
+            return eq(col, user.id);
+        };
+    }
+    else {
+        filter = options.filter;
+    }
+    // Store access control metadata keyed by the table object reference
+    tableAccessRegistry.set(table, {
+        filter,
+        fieldAccess: options.fieldAccess,
+        tableName: name,
+    });
+    return table;
+}
+// ─── ownerFilter() helper ───────────────────────────────
+/**
+ * Convenience helper for userId-based isolation.
+ *
+ * Usage:
+ *   export const tasks = gencowTable("tasks", { ... }, ownerFilter("userId"));
+ *   export const files = gencowTable("files", { ... }, ownerFilter("ownerId"));
+ *
+ * @param columnName - Name of the user ID column (default: "userId")
+ */
+export function ownerFilter(columnName = "userId") {
+    // Return a marker object — gencowTable() resolves this to a concrete filter
+    // by binding to the actual table column at registration time.
+    return {
+        _ownerColumn: columnName,
+        // Placeholder filter — replaced by gencowTable()
+        filter: () => { throw new Error("[gencow] ownerFilter placeholder should not be called directly"); },
+    };
+}
+// ─── Lookup ─────────────────────────────────────────────
+/** Get access control metadata for a table. Returns undefined for plain pgTable. */
+export function getTableAccessMeta(table) {
+    return tableAccessRegistry.get(table);
+}
+/** Check if a table has gencowTable metadata registered. */
+export function isGencowTable(table) {
+    return tableAccessRegistry.has(table);
+}
+/** Get all registered gencowTables (for audit/boot-time checks). */
+export function getAllGencowTables() {
+    return new Map(tableAccessRegistry);
+}
+/** Reset registry (for testing only). */
+export function _resetTableRegistry() {
+    tableAccessRegistry.clear();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gencow/core",
-    "version": "0.1.7",
+    "version": "0.1.9",
     "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
     "type": "module",
     "main": "dist/index.js",

package/src/__tests__/auth.test.ts

@@ -0,0 +1,114 @@
+/**
+ * packages/core/src/__tests__/auth.test.ts
+ *
+ * Tests for auth module — AuthCtx, defineAuth, auth-config.
+ *
+ * Run: bun test packages/core/src/__tests__/auth.test.ts
+ */
+
+import { describe, it, expect } from "bun:test";
+import { defineAuth } from "../auth-config";
+import type { GencowAuthConfig } from "../auth-config";
+
+// ─── defineAuth() ───────────────────────────────────────
+
+describe("defineAuth()", () => {
+    it("빈 설정 객체 반환", () => {
+        const config = defineAuth({});
+        expect(config).toEqual({});
+    });
+
+    it("emailVerification 설정이 그대로 반환된다", () => {
+        const sendFn = async () => {};
+        const config = defineAuth({
+            emailVerification: {
+                sendOnSignUp: true,
+                requireEmailVerification: true,
+                autoSignInAfterVerification: true,
+                sendVerificationEmail: sendFn,
+            },
+        });
+
+        expect(config.emailVerification?.sendOnSignUp).toBe(true);
+        expect(config.emailVerification?.requireEmailVerification).toBe(true);
+        expect(config.emailVerification?.autoSignInAfterVerification).toBe(true);
+        expect(config.emailVerification?.sendVerificationEmail).toBe(sendFn);
+    });
+
+    it("부분 설정도 허용된다", () => {
+        const config = defineAuth({
+            emailVerification: {
+                sendVerificationEmail: async () => {},
+            },
+        });
+
+        expect(config.emailVerification?.sendOnSignUp).toBeUndefined();
+        expect(config.emailVerification?.sendVerificationEmail).toBeDefined();
+    });
+});
+
+// ─── AuthCtx interface 패턴 ─────────────────────────────
+
+describe("AuthCtx 패턴 (mock)", () => {
+    // AuthCtx는 런타임에서 생성되므로, 인터페이스 수준에서 패턴 검증
+
+    it("getUserIdentity — 비로그인 시 null", () => {
+        const authCtx = {
+            getUserIdentity: () => null,
+            requireAuth: () => { throw new Error("Authentication required"); },
+        };
+
+        expect(authCtx.getUserIdentity()).toBeNull();
+    });
+
+    it("getUserIdentity — 로그인 시 유저 반환", () => {
+        const user = { id: "u1", email: "test@test.com", name: "Test" };
+        const authCtx = {
+            getUserIdentity: () => user,
+            requireAuth: () => user,
+        };
+
+        expect(authCtx.getUserIdentity()).toEqual(user);
+        expect(authCtx.getUserIdentity()!.id).toBe("u1");
+        expect(authCtx.getUserIdentity()!.email).toBe("test@test.com");
+    });
+
+    it("requireAuth — 비로그인 시 에러 throw", () => {
+        const authCtx = {
+            getUserIdentity: () => null,
+            requireAuth: () => { throw new Error("Authentication required"); },
+        };
+
+        expect(() => authCtx.requireAuth()).toThrow("Authentication required");
+    });
+
+    it("requireAuth — 로그인 시 유저 반환 (throw 안 함)", () => {
+        const user = { id: "u2", email: "auth@test.com" };
+        const authCtx = {
+            getUserIdentity: () => user,
+            requireAuth: () => user,
+        };
+
+        expect(() => authCtx.requireAuth()).not.toThrow();
+        expect(authCtx.requireAuth()).toEqual(user);
+    });
+});
+
+// ─── Secure by Default 검증 ─────────────────────────────
+
+describe("Secure by Default — 기본 인증 필수", () => {
+    // query/mutation의 isPublic 기본값은 reactive.test.ts에서 검증됨.
+    // 여기서는 auth 엔드포인트 레벨 패턴만 확인.
+
+    it("공개(public) 쿼리는 auth 없이 실행 가능해야 함", () => {
+        // 이 테스트는 query({ public: true })의 isPublic 플래그 확인
+        // reactive.test.ts의 "Secure by Default" 섹션과 연계
+        const mockQueryDef = { isPublic: true, handler: async () => [] };
+        expect(mockQueryDef.isPublic).toBe(true);
+    });
+
+    it("비공개 쿼리는 기본적으로 auth 필수", () => {
+        const mockQueryDef = { isPublic: false, handler: async () => [] };
+        expect(mockQueryDef.isPublic).toBe(false);
+    });
+});

package/src/__tests__/httpaction.test.ts

@@ -0,0 +1,122 @@
+/**
+ * packages/core/src/__tests__/httpaction.test.ts
+ *
+ * Tests for httpAction() — custom HTTP endpoint registration.
+ *
+ * Run: bun test packages/core/src/__tests__/httpaction.test.ts
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { httpAction, getRegisteredHttpActions } from "../reactive";
+
+// Clean up httpAction registry between tests
+// Note: httpAction uses globalThis.__gencow_httpActionRegistry (push-only array)
+// We clear it in beforeEach to isolate tests.
+
+describe("httpAction()", () => {
+    const initialLength = getRegisteredHttpActions().length;
+
+    it("httpAction 등록 시 레지스트리에 추가된다", () => {
+        const before = getRegisteredHttpActions().length;
+
+        httpAction({
+            method: "GET",
+            path: "/test/health",
+            handler: async () => ({ body: { status: "ok" } }),
+        });
+
+        const after = getRegisteredHttpActions().length;
+        expect(after).toBe(before + 1);
+    });
+
+    it("method, path가 정확히 설정된다", () => {
+        httpAction({
+            method: "POST",
+            path: "/webhook/stripe",
+            handler: async () => ({ body: { received: true } }),
+        });
+
+        const actions = getRegisteredHttpActions();
+        const last = actions[actions.length - 1];
+        expect(last.method).toBe("POST");
+        expect(last.path).toBe("/webhook/stripe");
+    });
+
+    it("public 기본값은 false이다", () => {
+        httpAction({
+            method: "GET",
+            path: "/test/private",
+            handler: async () => ({ body: {} }),
+        });
+
+        const actions = getRegisteredHttpActions();
+        const last = actions[actions.length - 1];
+        expect(last.isPublic).toBe(false);
+    });
+
+    it("public: true 설정 시 isPublic === true", () => {
+        httpAction({
+            method: "GET",
+            path: "/test/public-endpoint",
+            public: true,
+            handler: async () => ({ body: {} }),
+        });
+
+        const actions = getRegisteredHttpActions();
+        const last = actions[actions.length - 1];
+        expect(last.isPublic).toBe(true);
+    });
+
+    it("handler가 HttpActionDef에 포함된다", () => {
+        const handler = async () => ({ body: { ok: true } });
+        httpAction({
+            method: "PUT",
+            path: "/test/with-handler",
+            handler,
+        });
+
+        const actions = getRegisteredHttpActions();
+        const last = actions[actions.length - 1];
+        expect(last.handler).toBe(handler);
+    });
+
+    it("모든 HTTP 메서드 지원 (GET, POST, PUT, DELETE, PATCH)", () => {
+        const methods = ["GET", "POST", "PUT", "DELETE", "PATCH"] as const;
+        const before = getRegisteredHttpActions().length;
+
+        for (const method of methods) {
+            httpAction({
+                method,
+                path: `/test/method-${method.toLowerCase()}`,
+                handler: async () => ({ body: {} }),
+            });
+        }
+
+        const after = getRegisteredHttpActions().length;
+        expect(after).toBe(before + 5);
+
+        const actions = getRegisteredHttpActions();
+        const registered = actions.slice(-5).map(a => a.method);
+        expect(registered).toEqual(["GET", "POST", "PUT", "DELETE", "PATCH"]);
+    });
+
+    it("getRegisteredHttpActions()는 복사본을 반환한다 (원본 보호)", () => {
+        const a = getRegisteredHttpActions();
+        const b = getRegisteredHttpActions();
+        expect(a).not.toBe(b);
+        expect(a).toEqual(b);
+    });
+
+    it("Hono 경로 패턴 (/api/:id) 지원", () => {
+        httpAction({
+            method: "GET",
+            path: "/api/apps/:id/status",
+            public: true,
+            handler: async () => ({ body: {} }),
+        });
+
+        const actions = getRegisteredHttpActions();
+        const last = actions[actions.length - 1];
+        expect(last.path).toBe("/api/apps/:id/status");
+    });
+});

package/src/__tests__/reactive.test.ts

@@ -235,3 +235,80 @@ describe("Secure by Default — public 플래그", () => {
         expect(priv?.isPublic).toBe(false);
     });
 });
+
+// ─── mutation("name", def) 새 시그니처 테스트 ────────────────────────────────
+
+describe("mutation(name, def) — query와 동일 패턴", () => {
+    it("mutation('name', { handler })로 등록하면 name이 올바르게 설정된다", () => {
+        const m = mutation("newsig.basic", {
+            handler: async () => ({ ok: true }),
+        });
+        expect((m as any).name || (getRegisteredMutations().find(x => x.invalidates.length === 0 && x.handler === (m as any).handler) as any)?.name).toBeDefined();
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.basic");
+        expect(found).toBeDefined();
+        expect(found!.isPublic).toBe(false);
+    });
+
+    it("mutation('name', { public: true })로 등록하면 isPublic === true", () => {
+        const m = mutation("newsig.public", {
+            public: true,
+            handler: async () => ({ ok: true }),
+        });
+        expect(m.isPublic).toBe(true);
+    });
+
+    it("invalidates 미지정 시 빈 배열이 기본값", () => {
+        const m = mutation("newsig.noInvalidates", {
+            handler: async () => ({ ok: true }),
+        });
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.noInvalidates");
+        expect(found!.invalidates).toEqual([]);
+    });
+
+    it("invalidates 지정 시 올바르게 전달된다", () => {
+        const m = mutation("newsig.withInvalidates", {
+            invalidates: ["tasks.list", "tasks.get"],
+            handler: async () => ({ ok: true }),
+        });
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.withInvalidates");
+        expect(found!.invalidates).toEqual(["tasks.list", "tasks.get"]);
+    });
+
+    it("기존 객체 스타일도 여전히 동작한다 (하위 호환)", () => {
+        const m = mutation({
+            name: "newsig.compat.object",
+            invalidates: ["a.list"],
+            handler: async () => ({ ok: true }),
+        });
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.compat.object");
+        expect(found).toBeDefined();
+        expect(found!.invalidates).toEqual(["a.list"]);
+    });
+
+    it("기존 배열 스타일도 여전히 동작한다 (하위 호환)", () => {
+        const m = mutation(["b.list"], async () => ({ ok: true }), "newsig.compat.array");
+        const all = getRegisteredMutations();
+        const found = all.find(x => x.name === "newsig.compat.array");
+        expect(found).toBeDefined();
+        expect(found!.invalidates).toEqual(["b.list"]);
+    });
+
+    it("이름 미지정 시 console.warn이 호출된다", () => {
+        const warnSpy = mock(() => {});
+        const originalWarn = console.warn;
+        console.warn = warnSpy;
+
+        mutation(["c.list"], async () => ({ ok: true }));
+
+        expect(warnSpy).toHaveBeenCalled();
+        const warnMsg = warnSpy.mock.calls[0][0] as string;
+        expect(warnMsg).toContain("[gencow]");
+        expect(warnMsg).toContain("without explicit name");
+
+        console.warn = originalWarn;
+    });
+});