@mandujs/core 0.54.5 → 0.54.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.54.5",
+  "version": "0.54.6",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/__tests__/build-runner.ts

@@ -80,24 +80,42 @@ const manifest: RoutesManifest = mode === "server-page-client-module"
         },
       ],
     }
-  : {
-  version: 1,
-  routes: [
-    {
-      id: "demo",
-      kind: "page",
-      pattern: "/",
-      module: "app/page.tsx",
-      componentModule: "app/page.tsx",
-      clientModule: "app/demo.client.tsx",
-      hydration: {
-        strategy: "island",
-        priority: "visible",
-        preload: false,
-      },
-    },
-  ],
-};
+  : mode === "hydration-no-client-module"
+    ? {
+        version: 1,
+        routes: [
+          {
+            id: "login",
+            kind: "page",
+            pattern: "/login",
+            module: "app/login/page.tsx",
+            componentModule: "app/login/page.tsx",
+            hydration: {
+              strategy: "full",
+              priority: "immediate",
+              preload: false,
+            },
+          },
+        ],
+      }
+    : {
+        version: 1,
+        routes: [
+          {
+            id: "demo",
+            kind: "page",
+            pattern: "/",
+            module: "app/page.tsx",
+            componentModule: "app/page.tsx",
+            clientModule: "app/demo.client.tsx",
+            hydration: {
+              strategy: "island",
+              priority: "visible",
+              preload: false,
+            },
+          },
+        ],
+      };
 
 try {
   const result = await buildClientBundles(manifest, rootDir, {

package/src/bundler/__tests__/cold-start.test.ts

@@ -28,11 +28,12 @@ import { describe, it, expect, beforeEach, afterEach } from "bun:test";
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import path from "path";
-import type { RouteSpec } from "../../spec/schema";
+import type { RouteSpec, RoutesManifest } from "../../spec/schema";
 import {
   _testOnly_scanIslandFiles,
   _testOnly_scanPartialFiles,
   _testOnly_getHydratedRoutes,
+  _testOnly_getHydrationRoutesMissingClientModule,
 } from "../build";
 import { HMR_PERF } from "../../perf/hmr-markers";
 import {
@@ -504,6 +505,29 @@ describe("Phase 7.1 R1 Agent C — per-island scan skips non-hydrated routes", (
   });
 });
 
+describe("hydration route validation", () => {
+  it("finds pages that request hydration without a client module", () => {
+    const manifest = {
+      version: 1,
+      routes: [
+        {
+          id: "login",
+          pattern: "/login",
+          kind: "page",
+          module: "app/login/page.tsx",
+          componentModule: "app/login/page.tsx",
+          hydration: { strategy: "full", priority: "immediate", preload: false },
+        },
+        pureSsrRoute("about", "/about", "app/about"),
+        pageRoute("dashboard", "/dashboard", "app/dashboard"),
+      ],
+    } as RoutesManifest;
+
+    const missing = _testOnly_getHydrationRoutesMissingClientModule(manifest);
+    expect(missing.map((route) => route.id)).toEqual(["login"]);
+  });
+});
+
 describe("partial bundle scan", () => {
   let project: ReturnType<typeof createProject>;
 

package/src/bundler/build.test.ts

@@ -218,4 +218,39 @@ describe("buildClientBundles vendor shims", () => {
       await rm(staleRoot, { recursive: true, force: true });
     }
   });
+
+  test("fails when hydration is enabled but no clientModule can be resolved", async () => {
+    const missingRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-hydration-no-client-"));
+    try {
+      await mkdir(path.join(missingRoot, "app", "login"), { recursive: true });
+      await mkdir(path.join(missingRoot, "src", "client", "widgets", "login-form"), { recursive: true });
+      await writeFile(
+        path.join(missingRoot, "package.json"),
+        JSON.stringify({ name: "mandu-hydration-no-client-test", type: "module" }, null, 2),
+        "utf-8",
+      );
+      await writeFile(
+        path.join(missingRoot, "app", "login", "page.tsx"),
+        'import { LoginForm } from "../../src/client/widgets/login-form/LoginForm.client";\n' +
+          "export default function LoginPage() {\n" +
+          "  return <main><LoginForm /></main>;\n" +
+          "}\n",
+        "utf-8",
+      );
+      await writeFile(
+        path.join(missingRoot, "src", "client", "widgets", "login-form", "LoginForm.client.tsx"),
+        "export function LoginForm() { return <form />; }\n",
+        "utf-8",
+      );
+
+      const noClientResult = await runBuildInSubprocess(missingRoot, "hydration-no-client-module");
+      const errors = noClientResult.errors.join("\n");
+      expect(noClientResult.success).toBe(false);
+      expect(errors).toContain("no clientModule could be resolved");
+      expect(errors).toContain("LoginForm.client");
+      expect(errors).toContain("partial({ component }).Render");
+    } finally {
+      await rm(missingRoot, { recursive: true, force: true });
+    }
+  });
 });

package/src/bundler/build.ts

@@ -23,7 +23,10 @@ import type { BunPlugin } from "bun";
 import { mark, measure } from "../perf";
 import { HMR_PERF } from "../perf/hmr-markers";
 import { runOnBundleComplete } from "../plugins/runner";
-import { validateClientModuleForBrowserBundle } from "../router/client-entry";
+import {
+  describeMissingHydrationClientModule,
+  validateClientModuleForBrowserBundle,
+} from "../router/client-entry";
 import {
   readVendorCache,
   writeVendorCache,
@@ -236,7 +239,9 @@ export const _testOnly_scanPartialFiles = scanPartialFiles;
  *
  * @internal
  */
-export const _testOnly_getHydratedRoutes = getHydratedRoutes;
+export const _testOnly_getHydratedRoutes = getHydratedRoutes;
+export const _testOnly_getHydrationRoutesMissingClientModule =
+  getHydrationRoutesMissingClientModule;
 
 /**
  * Issue #240 Phase 2 — collect every file the React Compiler plugin
@@ -402,14 +407,23 @@ function createEmptyManifest(env: "development" | "production"): BundleManifest
 /**
  * Hydration이 필요한 라우트 필터링
  */
-function getHydratedRoutes(manifest: RoutesManifest): RouteSpec[] {
-  return manifest.routes.filter(
-    (route) =>
-      route.kind === "page" &&
-      route.clientModule &&
-      needsHydration(route)
-  );
-}
+function getHydratedRoutes(manifest: RoutesManifest): RouteSpec[] {
+  return manifest.routes.filter(
+    (route) =>
+      route.kind === "page" &&
+      route.clientModule &&
+      needsHydration(route)
+  );
+}
+
+function getHydrationRoutesMissingClientModule(manifest: RoutesManifest): RouteSpec[] {
+  return manifest.routes.filter(
+    (route) =>
+      route.kind === "page" &&
+      !route.clientModule &&
+      needsHydration(route)
+  );
+}
 
 const REACT_SHIM_EXPORTS = [
   "Activity",
@@ -2120,10 +2134,24 @@ export async function buildClientBundles(
       errors.push(`onBundleComplete[${e.source}]: ${e.error.message}`);
     }
   };
-  const env = resolveBundlerMode(options);
-
+  const env = resolveBundlerMode(options);
+
   // 1. Hydration이 필요한 라우트 필터링
   const invalidClientRouteIds = new Set<string>();
+  const runtimeRoutes = manifest.routes.filter((route) => route.kind === "page" && needsHydration(route));
+  const partialFiles = runtimeRoutes.length > 0 ? await scanPartialFiles(rootDir) : [];
+  const routesMissingClientModule = getHydrationRoutesMissingClientModule(manifest);
+  if (routesMissingClientModule.length > 0) {
+    const missingClientErrors = await Promise.all(
+      routesMissingClientModule.map((route) =>
+        describeMissingHydrationClientModule(route, rootDir, {
+          allowPartialOnly: partialFiles.length > 0,
+        })
+      )
+    );
+    errors.push(...missingClientErrors.filter((error): error is string => error !== null));
+  }
+
   let hydratedRoutes = getHydratedRoutes(manifest);
   if (hydratedRoutes.length > 0) {
     const validRoutes: RouteSpec[] = [];
@@ -2138,10 +2166,7 @@ export async function buildClientBundles(
     }
     hydratedRoutes = validRoutes;
   }
-  const runtimeRoutes = manifest.routes.filter((route) => route.kind === "page" && needsHydration(route));
-  const partialFiles = runtimeRoutes.length > 0 ? await scanPartialFiles(rootDir) : [];
-
-  // 2. 출력 디렉토리 생성 (항상 필요 - 매니페스트 저장용)
+  // 2. 출력 디렉토리 생성 (항상 필요 - 매니페스트 저장용)
   const outDir = resolveClientOutDir(rootDir, options.outDir);
   await fs.mkdir(outDir, { recursive: true });
 

package/src/generator/generate.ts

@@ -99,17 +99,25 @@ export interface GeneratedMap {
   frameworkPaths: string[];
 }
 
-async function ensureDir(dirPath: string): Promise<void> {
-  try {
-    await fs.mkdir(dirPath, { recursive: true });
-  } catch  {
-    // ignore if exists
-  }
-}
-
-async function getExistingFiles(dir: string): Promise<string[]> {
-  try {
-    const files = await fs.readdir(dir);
+async function ensureDir(dirPath: string): Promise<void> {
+  try {
+    await fs.mkdir(dirPath, { recursive: true });
+  } catch  {
+    // ignore if exists
+  }
+}
+
+function touchGenerateStamp(rootDir: string): void {
+  const stampDir = path.join(rootDir, ".mandu");
+  if (!fsSync.existsSync(stampDir)) {
+    fsSync.mkdirSync(stampDir, { recursive: true });
+  }
+  fsSync.writeFileSync(path.join(stampDir, "generate.stamp"), Date.now().toString());
+}
+
+async function getExistingFiles(dir: string): Promise<string[]> {
+  try {
+    const files = await fs.readdir(dir);
     return files.filter((f) => f.endsWith(".route.ts") || f.endsWith(".route.tsx"));
   } catch {
     return [];
@@ -138,9 +146,10 @@ export async function generateRoutes(
     warnings: [],
   };
 
-  // Suppress watcher during generation to avoid false positives
-  const watcher = getWatcher();
-  watcher?.suppress();
+  // Suppress watcher during generation to avoid false positives
+  const watcher = getWatcher();
+  watcher?.suppress();
+  touchGenerateStamp(rootDir);
 
   const generatedPaths = resolveGeneratedPaths(rootDir);
   const serverRoutesDir = generatedPaths.serverRoutesDir;
@@ -354,14 +363,10 @@ export async function generateRoutes(
   const mapPath = path.join(mapDir, "generated.map.json");
   await Bun.write(mapPath, JSON.stringify(generatedMap, null, 2));
 
-  // Resume watcher after generation
-  watcher?.resume();
-  // Cross-process timestamp: watcher skips warnings if generate finished recently
-  const stampDir = path.join(rootDir, ".mandu");
-  if (!fsSync.existsSync(stampDir)) {
-    fsSync.mkdirSync(stampDir, { recursive: true });
-  }
-  fsSync.writeFileSync(path.join(stampDir, "generate.stamp"), Date.now().toString());
-
-  return result;
-}
+  // Cross-process timestamp: watcher skips warnings if generate finished recently
+  touchGenerateStamp(rootDir);
+  // Resume watcher after the stamp is visible.
+  watcher?.resume();
+
+  return result;
+}

package/src/resource/__tests__/generator.test.ts

@@ -671,10 +671,12 @@ describe("generateSchemaArtifacts — diff + migration orchestration", () => {
       const result = await computeSchemaGeneration(resources, rootDir);
       expect(result.changes.length).toBe(2);
       expect(result.changes.every((c) => c.kind === "create-table")).toBe(true);
-      expect(result.migrationFilename).not.toBeNull();
-      expect(result.migrationSql).toContain("CREATE TABLE");
-      expect(result.desiredSchema).toContain("CREATE TABLE");
-      expect(Object.keys(result.desiredSchemaByTable).sort()).toEqual(["products", "users"]);
+      expect(result.migrationFilename).not.toBeNull();
+      expect(result.migrationSql).toContain("CREATE TABLE");
+      expect(result.migrationSql).not.toMatch(/\bBEGIN\b/i);
+      expect(result.migrationSql).not.toMatch(/\bCOMMIT\b/i);
+      expect(result.desiredSchema).toContain("CREATE TABLE");
+      expect(Object.keys(result.desiredSchemaByTable).sort()).toEqual(["products", "users"]);
     } finally {
       await fs.rm(rootDir, { recursive: true, force: true });
     }

package/src/resource/ddl/__tests__/emit.test.ts

@@ -415,13 +415,112 @@ describe("emitChange — add-column", () => {
     expect(emitChange(change, "mysql"))
       .toBe("ALTER TABLE `users` ADD COLUMN `age` DOUBLE;");
   });
-  test("sqlite", () => {
-    expect(emitChange(change, "sqlite"))
-      .toBe('ALTER TABLE "users" ADD COLUMN "age" REAL;');
-  });
-
-  test("indexed:true field emits ADD COLUMN plus auto CREATE INDEX", () => {
-    const indexed: Change = {
+  test("sqlite", () => {
+    expect(emitChange(change, "sqlite"))
+      .toBe('ALTER TABLE "users" ADD COLUMN "age" REAL;');
+  });
+
+  test("sqlite refuses required add-column without a non-NULL constant default (#294)", () => {
+    const required: Change = {
+      kind: "add-column",
+      resourceName: "votes",
+      field: field({ name: "created_at", type: "date" }),
+    };
+
+    expect(() => emitChange(required, "sqlite")).toThrow(
+      /SQLite cannot add required column "created_at"/,
+    );
+  });
+
+  test("sqlite allows required add-column when a scalar literal default is present", () => {
+    const requiredWithDefault: Change = {
+      kind: "add-column",
+      resourceName: "votes",
+      field: field({
+        name: "created_at",
+        type: "date",
+        default: { kind: "literal", value: "1970-01-01T00:00:00.000Z" },
+      }),
+    };
+
+    expect(emitChange(requiredWithDefault, "sqlite")).toBe(
+      'ALTER TABLE "votes" ADD COLUMN "created_at" TEXT NOT NULL DEFAULT \'1970-01-01T00:00:00.000Z\';',
+    );
+  });
+
+  test("sqlite refuses default: now on add-column because SQLite requires a constant default", () => {
+    const nowDefault: Change = {
+      kind: "add-column",
+      resourceName: "votes",
+      field: field({
+        name: "created_at",
+        type: "date",
+        nullable: true,
+        default: { kind: "now" },
+      }),
+    };
+
+    expect(() => emitChange(nowDefault, "sqlite")).toThrow(
+      /CURRENT_TIMESTAMP, which SQLite rejects/,
+    );
+  });
+
+  test("sqlite refuses UNIQUE add-column because SQLite cannot add the constraint in place", () => {
+    const unique: Change = {
+      kind: "add-column",
+      resourceName: "votes",
+      field: field({ name: "slug", type: "string", nullable: true, unique: true }),
+    };
+
+    expect(() => emitChange(unique, "sqlite")).toThrow(/cannot add UNIQUE column/);
+  });
+
+  test("sqlite refuses PRIMARY KEY add-column because SQLite cannot add the constraint in place", () => {
+    const primary: Change = {
+      kind: "add-column",
+      resourceName: "votes",
+      field: field({ name: "other_id", type: "uuid", primary: true }),
+    };
+
+    expect(() => emitChange(primary, "sqlite")).toThrow(/cannot add PRIMARY KEY column/);
+  });
+
+  test("sqlite refuses raw function defaults on add-column", () => {
+    const rawFunction: Change = {
+      kind: "add-column",
+      resourceName: "votes",
+      field: field({
+        name: "created_at",
+        type: "date",
+        nullable: true,
+        default: { kind: "sql", expr: "datetime('now')" },
+      }),
+    };
+
+    expect(() => emitChange(rawFunction, "sqlite")).toThrow(
+      /non-constant function defaults/,
+    );
+  });
+
+  test("sqlite refuses raw expression defaults on add-column", () => {
+    const rawExpression: Change = {
+      kind: "add-column",
+      resourceName: "votes",
+      field: field({
+        name: "score",
+        type: "number",
+        nullable: true,
+        default: { kind: "sql", expr: "(1+2)" },
+      }),
+    };
+
+    expect(() => emitChange(rawExpression, "sqlite")).toThrow(
+      /only accepts literal constant defaults/,
+    );
+  });
+
+  test("indexed:true field emits ADD COLUMN plus auto CREATE INDEX", () => {
+    const indexed: Change = {
       kind: "add-column",
       resourceName: "users",
       field: field({ name: "role", type: "string", indexed: true }),
@@ -477,22 +576,24 @@ describe("emitChange — alter-column-type stub", () => {
     stub: true,
   };
 
-  test("emits comment block with required TODO text", () => {
-    for (const p of PROVIDERS) {
-      const sql = emitChange(change, p);
-      expect(sql).toContain("-- TODO: Mandu does not auto-generate ALTER COLUMN TYPE in v1.");
-      expect(sql).toContain("mandu db apply");
-      expect(sql).toContain("Column type change detected: users.age");
-      expect(sql).toContain("from: number");
-      expect(sql).toContain("to:   string");
-    }
-  });
-
-  test("includes SELECT 1 no-op statement", () => {
-    const sql = emitChange(change, "postgres");
-    expect(sql).toContain("SELECT 1;");
-  });
-});
+  test("emits comment block with required TODO text", () => {
+    for (const p of PROVIDERS) {
+      const sql = emitChange(change, p);
+      expect(sql).toContain("-- TODO: Mandu does not auto-generate ALTER COLUMN TYPE in v1.");
+      expect(sql).toContain("mandu db apply");
+      expect(sql).toContain("Column type change detected: users.age");
+      expect(sql).toContain("from: number");
+      expect(sql).toContain("to:   string");
+      expect(sql).toContain("mandu_manual_migration_required");
+    }
+  });
+
+  test("includes a deliberate failing manual-migration sentinel", () => {
+    const sql = emitChange(change, "postgres");
+    expect(sql).toContain("SELECT mandu_manual_migration_required");
+    expect(sql).not.toContain("SELECT 1;");
+  });
+});
 
 describe("emitChange — alter-column-nullable", () => {
   test("postgres SET NOT NULL / DROP NOT NULL", () => {
@@ -510,24 +611,24 @@ describe("emitChange — alter-column-nullable", () => {
     ).toBe('ALTER TABLE "users" ALTER COLUMN "email" DROP NOT NULL;');
   });
 
-  test("sqlite emits a stub (cannot toggle NOT NULL in place)", () => {
-    const sql = emitChange(
-      { kind: "alter-column-nullable", resourceName: "users", fieldName: "email", nullable: true },
-      "sqlite",
-    );
-    expect(sql).toContain("TODO: SQLite cannot toggle NOT NULL in place");
-    expect(sql).toContain("SELECT 1;");
-  });
-
-  test("mysql emits a stub (MODIFY COLUMN needs full type)", () => {
-    const sql = emitChange(
-      { kind: "alter-column-nullable", resourceName: "users", fieldName: "email", nullable: false },
-      "mysql",
-    );
-    expect(sql).toContain("MySQL MODIFY COLUMN requires");
-    expect(sql).toContain("SELECT 1;");
-  });
-});
+  test("sqlite emits a stub (cannot toggle NOT NULL in place)", () => {
+    const sql = emitChange(
+      { kind: "alter-column-nullable", resourceName: "users", fieldName: "email", nullable: true },
+      "sqlite",
+    );
+    expect(sql).toContain("TODO: SQLite cannot toggle NOT NULL in place");
+    expect(sql).toContain("mandu_manual_migration_required");
+  });
+
+  test("mysql emits a stub (MODIFY COLUMN needs full type)", () => {
+    const sql = emitChange(
+      { kind: "alter-column-nullable", resourceName: "users", fieldName: "email", nullable: false },
+      "mysql",
+    );
+    expect(sql).toContain("MySQL MODIFY COLUMN requires");
+    expect(sql).toContain("mandu_manual_migration_required");
+  });
+});
 
 describe("emitChange — alter-column-default", () => {
   test("postgres SET DEFAULT", () => {
@@ -551,20 +652,35 @@ describe("emitChange — alter-column-default", () => {
     expect(sql).toBe('ALTER TABLE "users" ALTER COLUMN "status" DROP DEFAULT;');
   });
 
-  test("mysql supports SET/DROP DEFAULT directly", () => {
-    expect(
-      emitChange(
-        {
+  test("mysql supports SET/DROP DEFAULT directly", () => {
+    expect(
+      emitChange(
+        {
           kind: "alter-column-default",
           resourceName: "u",
           fieldName: "f",
           default: { kind: "literal", value: 1 },
         },
         "mysql",
-      ),
-    ).toBe("ALTER TABLE `u` ALTER COLUMN `f` SET DEFAULT 1;");
-  });
-});
+      ),
+    ).toBe("ALTER TABLE `u` ALTER COLUMN `f` SET DEFAULT 1;");
+  });
+
+  test("sqlite emits a failing manual stub for default changes", () => {
+    const sql = emitChange(
+      {
+        kind: "alter-column-default",
+        resourceName: "users",
+        fieldName: "status",
+        default: { kind: "literal", value: "active" },
+      },
+      "sqlite",
+    );
+    expect(sql).toContain("TODO: SQLite cannot ALTER DEFAULT in place");
+    expect(sql).toContain("mandu_manual_migration_required");
+    expect(sql).not.toContain("SELECT 1;");
+  });
+});
 
 describe("emitChange — indexes", () => {
   test("add-index single column, non-unique", () => {

package/src/resource/ddl/emit.ts

@@ -15,10 +15,11 @@
  *   4. Value literals in `DEFAULT` clauses flow through `resolveDefault`
  *      which handles quote escaping. `kind: "sql"` is the explicit
  *      escape hatch — caller's responsibility.
- *   5. Unsupported changes (v1 scope — `alter-column-type`) emit a
- *      `-- TODO:` comment block + a no-op `SELECT 1;` so the generated
- *      migration still parses and Agent C's runner can record an
- *      "applied but manual" row.
+ *   5. Unsupported changes (v1 scope — `alter-column-type`, and some
+ *      dialect-specific ALTER gaps) emit a `-- TODO:` comment block plus
+ *      a deliberate failing sentinel statement. The generated migration
+ *      is reviewable/editable, but `mandu db apply` will not record it
+ *      until the operator replaces the TODO with real SQL.
  *
  * Determinism:
  *   - `emitCreateTable` emits columns in `DdlFieldDef` array order — the
@@ -338,15 +339,16 @@ export function emitChange(change: Change, provider: SqlProvider): string {
 // Change emitters (internal — called only via emitChange dispatch).
 // =====================================================================
 
-function emitAddColumn(
-  resourceName: string,
-  field: DdlFieldDef,
-  provider: SqlProvider,
-): string {
-  const table = quoteIdent(resourceName, provider);
-  const columnDef = emitColumnDef(field, provider);
-  const addColumn = `ALTER TABLE ${table} ADD COLUMN ${columnDef};`;
-  if (!field.indexed || field.unique || field.primary) return addColumn;
+function emitAddColumn(
+  resourceName: string,
+  field: DdlFieldDef,
+  provider: SqlProvider,
+): string {
+  validateAddColumn(resourceName, field, provider);
+  const table = quoteIdent(resourceName, provider);
+  const columnDef = emitColumnDef(field, provider);
+  const addColumn = `ALTER TABLE ${table} ADD COLUMN ${columnDef};`;
+  if (!field.indexed || field.unique || field.primary) return addColumn;
   return [
     addColumn,
     emitCreateIndex(
@@ -356,8 +358,85 @@ function emitAddColumn(
       false,
       provider,
     ),
-  ].join("\n");
-}
+  ].join("\n");
+}
+
+function validateAddColumn(
+  resourceName: string,
+  field: DdlFieldDef,
+  provider: SqlProvider,
+): void {
+  if (provider !== "sqlite") return;
+
+  if (field.primary) {
+    throw new Error(
+      `SQLite cannot add PRIMARY KEY column "${field.name}" to existing table "${resourceName}" via ALTER TABLE. ` +
+        `Create a manual table-rebuild migration instead.`,
+    );
+  }
+
+  if (field.unique) {
+    throw new Error(
+      `SQLite cannot add UNIQUE column "${field.name}" to existing table "${resourceName}" via ALTER TABLE. ` +
+        `Add a nullable/non-unique column first, backfill it, then create a unique index manually.`,
+    );
+  }
+
+  const defaultIssue = sqliteAddColumnDefaultIssue(field);
+  if (defaultIssue) {
+    throw new Error(
+      `SQLite cannot add column "${field.name}" to existing table "${resourceName}" with this DEFAULT: ` +
+        `${defaultIssue} Use a scalar literal default or write a manual backfill migration.`,
+    );
+  }
+
+  if (field.nullable) return;
+  if (field.default !== undefined && !isSqliteNullDefault(field.default)) return;
+
+  throw new Error(
+    `SQLite cannot add required column "${field.name}" to existing table "${resourceName}" without a non-NULL constant DEFAULT. ` +
+      `Add a scalar default, set required:false, or write a manual backfill migration.`,
+  );
+}
+
+function sqliteAddColumnDefaultIssue(field: DdlFieldDef): string | null {
+  const def = field.default;
+  if (!def) return null;
+  if (def.kind === "now") {
+    return `default "now" maps to CURRENT_TIMESTAMP, which SQLite rejects in ADD COLUMN.`;
+  }
+  if (def.kind !== "sql") return null;
+
+  const expr = def.expr.trim();
+  if (/^CURRENT_(?:TIME|DATE|TIMESTAMP)\b/i.test(expr)) {
+    return `SQLite rejects CURRENT_TIME/CURRENT_DATE/CURRENT_TIMESTAMP in ADD COLUMN.`;
+  }
+  if (/\b[A-Za-z_][A-Za-z0-9_]*\s*\(/.test(expr)) {
+    return `SQLite rejects non-constant function defaults in ADD COLUMN.`;
+  }
+  if (!isSqliteAddColumnConstantSqlDefault(expr)) {
+    return `SQLite ADD COLUMN only accepts literal constant defaults; raw SQL expression ${JSON.stringify(expr)} is not safe to emit automatically.`;
+  }
+  return null;
+}
+
+function isSqliteNullDefault(def: NonNullable<DdlFieldDef["default"]>): boolean {
+  return def.kind === "null" || (def.kind === "sql" && /^NULL$/i.test(def.expr.trim()));
+}
+
+function isSqliteAddColumnConstantSqlDefault(expr: string): boolean {
+  let value = expr.trim();
+  while (value.startsWith("(") && value.endsWith(")")) {
+    value = value.slice(1, -1).trim();
+  }
+  return (
+    /^NULL$/i.test(value) ||
+    /^(?:TRUE|FALSE)$/i.test(value) ||
+    /^[+-]?(?:\d+|\d+\.\d+|\.\d+)(?:e[+-]?\d+)?$/i.test(value) ||
+    /^'(?:''|[^'])*'$/.test(value) ||
+    /^X'(?:[0-9a-f]{2})*'$/i.test(value)
+  );
+}
 
 /**
  * DROP COLUMN.
@@ -383,8 +462,8 @@ function emitDropColumn(
  *
  * Output: a multi-line SQL comment block naming the resource + field +
  * fromType → toType, followed by the literal TODO message and a no-op
- * `SELECT 1;` so the migration runner (Agent C) parses and advances past
- * this statement.
+ * a deliberate failing sentinel so the migration runner refuses to mark
+ * this TODO as applied until the operator edits the migration manually.
  */
 function emitAlterColumnTypeStub(
   resourceName: string,
@@ -398,11 +477,13 @@ function emitAlterColumnTypeStub(
     `--   from: ${fromType}`,
     `--   to:   ${toType}`,
     `-- TODO: Mandu does not auto-generate ALTER COLUMN TYPE in v1.`,
-    `-- Please write the migration manually, then re-run \`mandu db apply\`.`,
-    `-- ================================================================`,
-    `SELECT 1;`,
-  ].join("\n");
-}
+    `-- Please write the migration manually, then re-run \`mandu db apply\`.`,
+    `-- ================================================================`,
+    manualMigrationRequiredStatement(
+      `Mandu cannot auto-generate ALTER COLUMN TYPE for ${resourceName}.${fieldName}`,
+    ),
+  ].join("\n");
+}
 
 function emitAlterColumnNullable(
   resourceName: string,
@@ -419,30 +500,34 @@ function emitAlterColumnNullable(
       : `ALTER TABLE ${table} ALTER COLUMN ${col} SET NOT NULL;`;
   }
   if (provider === "sqlite") {
-    // SQLite cannot toggle NOT NULL on an existing column without a full
-    // table recreate. Emit a stub so the user handles it manually.
-    return [
-      `-- ================================================================`,
-      `-- Nullability change: ${resourceName}.${fieldName} → ${nullable ? "NULL" : "NOT NULL"}`,
-      `-- TODO: SQLite cannot toggle NOT NULL in place. Recreate the table`,
-      `-- manually (CREATE new, INSERT SELECT, DROP old, RENAME) and re-run.`,
-      `-- ================================================================`,
-      `SELECT 1;`,
-    ].join("\n");
-  }
+    // SQLite cannot toggle NOT NULL on an existing column without a full
+    // table recreate. Emit a failing stub so the user handles it manually.
+    return [
+      `-- ================================================================`,
+      `-- Nullability change: ${resourceName}.${fieldName} → ${nullable ? "NULL" : "NOT NULL"}`,
+      `-- TODO: SQLite cannot toggle NOT NULL in place. Recreate the table`,
+      `-- manually (CREATE new, INSERT SELECT, DROP old, RENAME) and re-run.`,
+      `-- ================================================================`,
+      manualMigrationRequiredStatement(
+        `SQLite nullability change requires manual table rebuild for ${resourceName}.${fieldName}`,
+      ),
+    ].join("\n");
+  }
   // MySQL requires the full column spec; we cannot reconstruct it here.
   // Emit a stub — Agent B's diff emits `alter-column-nullable` only when
   // everything else matches, so this is narrow-scope.
   return [
     `-- ================================================================`,
     `-- Nullability change: ${resourceName}.${fieldName} → ${nullable ? "NULL" : "NOT NULL"}`,
-    `-- TODO: MySQL MODIFY COLUMN requires the full column type; Mandu v1`,
-    `-- cannot emit this automatically. Please edit this migration to use`,
-    `-- \`ALTER TABLE ${resourceName} MODIFY COLUMN ${fieldName} <TYPE> ${nullable ? "NULL" : "NOT NULL"}\``,
-    `-- ================================================================`,
-    `SELECT 1;`,
-  ].join("\n");
-}
+    `-- TODO: MySQL MODIFY COLUMN requires the full column type; Mandu v1`,
+    `-- cannot emit this automatically. Please edit this migration to use`,
+    `-- \`ALTER TABLE ${resourceName} MODIFY COLUMN ${fieldName} <TYPE> ${nullable ? "NULL" : "NOT NULL"}\``,
+    `-- ================================================================`,
+    manualMigrationRequiredStatement(
+      `MySQL nullability change requires manual MODIFY COLUMN for ${resourceName}.${fieldName}`,
+    ),
+  ].join("\n");
+}
 
 function emitAlterColumnDefault(
   resourceName: string,
@@ -458,15 +543,17 @@ function emitAlterColumnDefault(
       : `ALTER TABLE ${table} ALTER COLUMN ${col} DROP DEFAULT;`;
   }
   if (provider === "sqlite") {
-    // Same constraint as nullability — SQLite needs a table recreate.
-    return [
-      `-- ================================================================`,
-      `-- Default change: ${resourceName}.${fieldName}`,
-      `-- TODO: SQLite cannot ALTER DEFAULT in place. Recreate the table.`,
-      `-- ================================================================`,
-      `SELECT 1;`,
-    ].join("\n");
-  }
+    // Same constraint as nullability — SQLite needs a table recreate.
+    return [
+      `-- ================================================================`,
+      `-- Default change: ${resourceName}.${fieldName}`,
+      `-- TODO: SQLite cannot ALTER DEFAULT in place. Recreate the table.`,
+      `-- ================================================================`,
+      manualMigrationRequiredStatement(
+        `SQLite default change requires manual table rebuild for ${resourceName}.${fieldName}`,
+      ),
+    ].join("\n");
+  }
   // MySQL — ALTER COLUMN ... SET DEFAULT / DROP DEFAULT is actually supported.
   return def
     ? `ALTER TABLE ${table} ALTER COLUMN ${col} SET DEFAULT ${resolveDefault(def, provider)};`
@@ -510,7 +597,7 @@ function emitRenameTable(
   return `ALTER TABLE ${from} RENAME TO ${to};`;
 }
 
-function emitRenameColumn(
+function emitRenameColumn(
   resourceName: string,
   oldName: string,
   newName: string,
@@ -522,7 +609,15 @@ function emitRenameColumn(
   // All three dialects use `ALTER TABLE ... RENAME COLUMN ... TO ...` in
   // their modern versions (PG >=9.2, MySQL >=8.0.3, SQLite >=3.25).
   return `ALTER TABLE ${table} RENAME COLUMN ${from} TO ${to};`;
-}
+}
+
+function manualMigrationRequiredStatement(message: string): string {
+  return `SELECT mandu_manual_migration_required(${sqlStringLiteral(message)});`;
+}
+
+function sqlStringLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
 
 // =====================================================================
 // Validation helpers.

package/src/resource/generator-schema.ts

@@ -363,21 +363,17 @@ ${result.migrationSql}`;
 // ============================================
 
 /**
- * Wrap the sequence of `Change` → SQL emission with a transaction
- * header/footer. SQLite uses `BEGIN` / `COMMIT` (plain) because its
- * migration runner invokes each file via `db.transaction()` anyway —
- * but the explicit BEGIN/COMMIT is harmless inside an already-open tx
- * and makes the file runnable standalone via `sqlite3 foo.db < file.sql`.
- */
-function composeMigrationSql(changes: readonly Change[], provider: SqlProvider): string {
-  const body = emitChanges(changes, provider);
-  if (body.length === 0) return "";
-  return `BEGIN;
-
-${body}
-
-COMMIT;`;
-}
+ * Compose the sequence of `Change` → SQL emission.
+ *
+ * Do not wrap with `BEGIN` / `COMMIT`: the migration runner already applies
+ * each file inside a transaction, and SQLite rejects nested BEGIN with
+ * "cannot start a transaction within a transaction".
+ */
+function composeMigrationSql(changes: readonly Change[], provider: SqlProvider): string {
+  const body = emitChanges(changes, provider);
+  if (body.length === 0) return "";
+  return body;
+}
 
 // ============================================
 // Internals — filesystem I/O

package/src/router/client-entry.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "bun:test";
+import { findClientComponentImports } from "./client-entry";
+
+describe("findClientComponentImports", () => {
+  it("detects named .client imports for diagnostics", () => {
+    const imports = findClientComponentImports(`
+      import { LoginForm, SubmitButton as Button } from "@/client/widgets/login-form/LoginForm.client";
+      import Header from "./Header.client.tsx";
+    `);
+
+    expect(imports).toEqual([
+      {
+        module: "@/client/widgets/login-form/LoginForm.client",
+        kind: "named",
+        names: ["LoginForm", "SubmitButton"],
+      },
+      {
+        module: "./Header.client.tsx",
+        kind: "default",
+        names: ["Header"],
+      },
+    ]);
+  });
+});

package/src/router/client-entry.ts

@@ -2,6 +2,12 @@ import { readFile } from "fs/promises";
 import path from "path";
 import type { RouteSpec } from "../spec/schema";
 
+export interface ClientComponentImport {
+  module: string;
+  kind: "default" | "named" | "namespace" | "side-effect" | "mixed";
+  names: string[];
+}
+
 export function normalizeRouteModulePath(value: string | undefined): string {
   return (value ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
 }
@@ -32,6 +38,62 @@ async function readRouteModule(rootDir: string, modulePath: string): Promise<str
   }
 }
 
+export function findClientComponentImports(source: string): ClientComponentImport[] {
+  const imports: ClientComponentImport[] = [];
+  const importFromPattern = /import\s+([\s\S]*?)\s+from\s+["']([^"']*\.client(?:\.[tj]sx?)?)["']/g;
+  const sideEffectPattern = /import\s+["']([^"']*\.client(?:\.[tj]sx?)?)["']/g;
+
+  for (const match of source.matchAll(importFromPattern)) {
+    const clause = (match[1] ?? "").trim();
+    const module = match[2] ?? "";
+    const names: string[] = [];
+    let hasDefault = false;
+    let hasNamed = false;
+    let hasNamespace = false;
+
+    const namedMatch = clause.match(/\{([^}]*)\}/);
+    if (namedMatch) {
+      hasNamed = true;
+      for (const rawName of namedMatch[1].split(",")) {
+        const name = rawName.trim();
+        if (!name) continue;
+        names.push(name.split(/\s+as\s+/i)[0].trim());
+      }
+    }
+
+    if (/\*\s+as\s+/.test(clause)) {
+      hasNamespace = true;
+      const namespaceMatch = clause.match(/\*\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)/);
+      if (namespaceMatch?.[1]) names.push(namespaceMatch[1]);
+    }
+
+    const beforeNamed = clause.split("{")[0]?.replace(/,\s*$/, "").trim() ?? "";
+    if (beforeNamed && !beforeNamed.startsWith("*")) {
+      hasDefault = true;
+      names.push(beforeNamed.split(",")[0].trim());
+    }
+
+    const kind =
+      (hasDefault && (hasNamed || hasNamespace))
+        ? "mixed"
+        : hasNamed
+          ? "named"
+          : hasNamespace
+            ? "namespace"
+            : "default";
+
+    imports.push({ module, kind, names });
+  }
+
+  for (const match of source.matchAll(sideEffectPattern)) {
+    const module = match[1] ?? "";
+    if (imports.some((entry) => entry.module === module)) continue;
+    imports.push({ module, kind: "side-effect", names: [] });
+  }
+
+  return imports;
+}
+
 export async function shouldPreserveExistingClientModule(
   route: RouteSpec,
   clientModule: string,
@@ -69,3 +131,48 @@ export async function validateClientModuleForBrowserBundle(
 
   return null;
 }
+
+export async function describeMissingHydrationClientModule(
+  route: RouteSpec,
+  rootDir: string,
+  options: { allowPartialOnly?: boolean } = {},
+): Promise<string | null> {
+  const hydration = route.hydration?.strategy ?? "island";
+  const base =
+    `[${route.id}] Route has hydration strategy "${hydration}" but no clientModule could be resolved. ` +
+    `Mandu cannot emit a working data-mandu-src for this route.`;
+
+  const componentModule = route.kind === "page" ? route.componentModule : undefined;
+  if (!componentModule) {
+    return options.allowPartialOnly && hydration === "island" ? null : base;
+  }
+
+  const source = await readRouteModule(rootDir, componentModule);
+  if (source === null) {
+    return options.allowPartialOnly && hydration === "island" ? null : base;
+  }
+
+  const clientImports = findClientComponentImports(source);
+  if (clientImports.length === 0) {
+    if (options.allowPartialOnly && hydration === "island") return null;
+    return (
+      `${base}\n` +
+      `  Fix: add a route-level client module (for example app/*.island.tsx or spec/slots/${route.id}.client.tsx) ` +
+      `or set hydration.strategy to "none".`
+    );
+  }
+
+  const importList = clientImports
+    .map((entry) => {
+      const suffix = entry.names.length > 0 ? ` (${entry.kind}: ${entry.names.join(", ")})` : ` (${entry.kind})`;
+      return `    - ${entry.module}${suffix}`;
+    })
+    .join("\n");
+
+  return (
+    `${base}\n` +
+    `  The page imports client-looking modules, but inline .client.tsx imports are not route bundles:\n` +
+    `${importList}\n` +
+    `  Fix: use partial({ component }).Render for embedded client regions, or expose a route-level client module.`
+  );
+}

package/src/runtime/server.ts

@@ -2232,18 +2232,26 @@ async function renderPageSSR(
 
     // Island 래핑: 레이아웃 적용 전에 페이지 콘텐츠만 island div로 감쌈
     // 이렇게 하면 레이아웃은 island 바깥에 위치하여 하이드레이션 시 레이아웃이 유지됨
-    const needsIslandWrap = !!(
+    const needsIslandHydration = !!(
       route.hydration &&
       route.hydration.strategy !== "none" &&
       settings.bundleManifest
     );
-
-    if (needsIslandWrap) {
-      const bundle = settings.bundleManifest?.bundles[route.id];
-      const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
-      const priority = route.hydration!.priority || "visible";
-      app = React.createElement("div", {
-        "data-mandu-island": route.id,
+    const routeBundle = settings.bundleManifest?.bundles[route.id];
+    const bundleSrc = routeBundle?.js ? `${routeBundle.js}?t=${Date.now()}` : "";
+    const needsIslandWrap = needsIslandHydration && bundleSrc.length > 0;
+
+    if (needsIslandHydration && !needsIslandWrap && settings.isDev) {
+      console.warn(
+        `[Mandu] Hydration requested for route "${route.id}" but no client bundle was found. ` +
+        `Run mandu build/generate and ensure the route has a clientModule.`,
+      );
+    }
+
+    if (needsIslandWrap) {
+      const priority = route.hydration!.priority || "visible";
+      app = React.createElement("div", {
+        "data-mandu-island": route.id,
         "data-mandu-src": bundleSrc,
         "data-mandu-priority": priority,
         style: { display: "contents" },

package/src/watcher/__tests__/watcher.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { hasRecentGenerateStamp } from "../watcher";
+
+const tmpRoots: string[] = [];
+
+function makeRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), "mandu-watch-"));
+  tmpRoots.push(root);
+  return root;
+}
+
+afterEach(() => {
+  for (const root of tmpRoots.splice(0)) {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("hasRecentGenerateStamp suppresses generated events using the root stamp", () => {
+  const root = makeRoot();
+  const now = 1_700_000_000_000;
+  mkdirSync(join(root, ".mandu"), { recursive: true });
+  writeFileSync(join(root, ".mandu", "generate.stamp"), String(now - 500));
+
+  const generatedFile = join(
+    root,
+    ".mandu",
+    "generated",
+    "server",
+    "repos",
+    "notification.repo.ts",
+  );
+
+  expect(hasRecentGenerateStamp(root, generatedFile, now)).toBe(true);
+});
+
+test("hasRecentGenerateStamp does not suppress stale generated events", () => {
+  const root = makeRoot();
+  const now = 1_700_000_000_000;
+  mkdirSync(join(root, ".mandu"), { recursive: true });
+  writeFileSync(join(root, ".mandu", "generate.stamp"), String(now - 30_000));
+
+  const generatedFile = join(root, ".mandu", "generated", "server", "old.route.ts");
+
+  expect(hasRecentGenerateStamp(root, generatedFile, now)).toBe(false);
+});
+
+test("hasRecentGenerateStamp does not suppress source files after generation", () => {
+  const root = makeRoot();
+  const now = 1_700_000_000_000;
+  mkdirSync(join(root, ".mandu"), { recursive: true });
+  writeFileSync(join(root, ".mandu", "generate.stamp"), String(now - 500));
+
+  const sourceFile = join(root, "app", "page.tsx");
+
+  expect(hasRecentGenerateStamp(root, sourceFile, now)).toBe(false);
+});

package/src/watcher/watcher.ts

@@ -61,13 +61,63 @@ const DEFAULT_CONFIG: Partial<WatcherConfig> = {
  * These cause EISDIR/ENOENT errors when file watchers try to access them.
  * See: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file
  */
-const WINDOWS_RESERVED_NAMES = new Set([
-  "CON", "PRN", "AUX", "NUL",
-  "COM0", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
-  "LPT0", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
-]);
-
-export class FileWatcher {
+const WINDOWS_RESERVED_NAMES = new Set([
+  "CON", "PRN", "AUX", "NUL",
+  "COM0", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
+  "LPT0", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+]);
+
+const GENERATE_STAMP_SUPPRESS_MS = 10_000;
+
+function readGenerateStamp(stampFile: string): number | null {
+  try {
+    const stamp = Number.parseInt(fs.readFileSync(stampFile, "utf-8"), 10);
+    return Number.isFinite(stamp) ? stamp : null;
+  } catch {
+    return null;
+  }
+}
+
+function isManduGeneratedPath(rootDir: string, filePath: string): boolean {
+  const relativePath = path.relative(rootDir, filePath).replace(/\\/g, "/");
+  return relativePath === ".mandu/generated" || relativePath.startsWith(".mandu/generated/");
+}
+
+export function hasRecentGenerateStamp(
+  rootDir: string,
+  filePath: string,
+  now: number = Date.now()
+): boolean {
+  if (!isManduGeneratedPath(rootDir, filePath)) {
+    return false;
+  }
+
+  const candidates = new Set<string>([
+    path.join(rootDir, ".mandu", "generate.stamp"),
+  ]);
+  const resolvedRoot = path.resolve(rootDir);
+  let stampDir = path.dirname(path.resolve(filePath));
+
+  while (stampDir !== path.dirname(stampDir)) {
+    candidates.add(path.join(stampDir, ".mandu", "generate.stamp"));
+    if (stampDir === resolvedRoot) break;
+    stampDir = path.dirname(stampDir);
+  }
+
+  for (const stampFile of candidates) {
+    const stamp = readGenerateStamp(stampFile);
+    if (stamp === null) continue;
+
+    const ageMs = now - stamp;
+    if (ageMs >= 0 && ageMs < GENERATE_STAMP_SUPPRESS_MS) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export class FileWatcher {
   private config: WatcherConfig;
   private chokidarWatcher: FSWatcher | null = null;
   private handlers: Set<WatchEventHandler> = new Set();
@@ -311,21 +361,10 @@ export class FileWatcher {
 
     const { rootDir } = this.config;
 
-    // Cross-process: skip if generate finished within last 2 seconds
-    // Walk up from the changed file to find nearest .mandu/generate.stamp
-    let stampDir = path.dirname(filePath);
-    while (stampDir !== path.dirname(stampDir)) {
-      const stampFile = path.join(stampDir, ".mandu", "generate.stamp");
-      try {
-        const stamp = parseInt(fs.readFileSync(stampFile, "utf-8"), 10);
-        if (Date.now() - stamp < 2000) return;
-        break;
-      } catch {}
-      stampDir = path.dirname(stampDir);
-    }
-
-
-    // Validate file against rules
+    // Cross-process: skip generated-file churn from a recent mandu generate.
+    if (hasRecentGenerateStamp(rootDir, filePath)) return;
+
+    // Validate file against rules
     try {
       const warnings = await validateFile(filePath, event, rootDir);