shapecraft 1.0.0

package/packages/core/src/shape/transforms/sql/transform.test.ts

@@ -0,0 +1,880 @@
+import { describe, expect } from "vitest";
+import { R } from "../../../common/result";
+import { annotate, shapes } from "../../shape";
+import { toSQL } from "./transform";
+
+const ok = (res: R.Result<string, string[]>): string => {
+  if (!R.isOk(res))
+    throw new Error(`expected ok, got err: ${res.error.join("; ")}`);
+  return res.value;
+};
+
+const err = (res: R.Result<string, string[]>): string[] => {
+  if (R.isOk(res)) throw new Error(`expected err, got ok: ${res.value}`);
+  return res.error;
+};
+
+describe("toSQL — top-level errors", (it) => {
+  it("non-mapping top-level → err", () => {
+    expect(err(toSQL(shapes.string()))).toEqual([
+      "toSQL expects a top-level mapping (table) or module",
+    ]);
+  });
+
+  it("mapping without title → err", () => {
+    const m = shapes.mapping({ id: shapes.int() });
+    expect(err(toSQL(m))).toEqual([
+      "mapping is missing required title (table name)",
+    ]);
+  });
+
+  it("nil/undefined field → err", () => {
+    const m = annotate.titled(
+      shapes.mapping({ a: shapes.nil(), b: shapes.notDefined() }),
+      "t",
+    );
+    expect(err(toSQL(m))).toEqual([
+      "field 'a': nil cannot be a column",
+      "field 'b': undefined cannot be a column",
+    ]);
+  });
+
+  it("autoIncrement on non-integer → err", () => {
+    const m = annotate.titled(
+      shapes.mapping({ s: annotate.autoIncremented(shapes.string()) }),
+      "t",
+    );
+    expect(err(toSQL(m))).toEqual([
+      "field 's': autoIncrement requires an integer type",
+    ]);
+  });
+
+  it("autoIncrement on uint64 → err", () => {
+    const m = annotate.titled(
+      shapes.mapping({ x: annotate.autoIncremented(shapes.uint64()) }),
+      "t",
+    );
+    expect(err(toSQL(m))).toEqual([
+      "field 'x': autoIncrement is not supported on uint64 (numeric column)",
+    ]);
+  });
+
+  it("multiple errors collected", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        a: shapes.nil(),
+        b: annotate.autoIncremented(shapes.string()),
+      }),
+      "t",
+    );
+    expect(err(toSQL(m))).toEqual([
+      "field 'a': nil cannot be a column",
+      "field 'b': autoIncrement requires an integer type",
+    ]);
+  });
+});
+
+describe("toSQL — scalars", (it) => {
+  it("string → text NOT NULL", () => {
+    const m = annotate.titled(shapes.mapping({ name: shapes.string() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "name" text NOT NULL\n);`,
+    );
+  });
+
+  it("optional string → no NOT NULL", () => {
+    const m = annotate.titled(
+      shapes.mapping({ name: annotate.optional(shapes.string()) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "name" text\n);`,
+    );
+  });
+
+  it("boolean → boolean NOT NULL", () => {
+    const m = annotate.titled(shapes.mapping({ flag: shapes.boolean() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "flag" boolean NOT NULL\n);`,
+    );
+  });
+
+  it("date → timestamptz", () => {
+    const m = annotate.titled(shapes.mapping({ when: shapes.date() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "when" timestamptz NOT NULL\n);`,
+    );
+  });
+
+  it("binary → bytea", () => {
+    const m = annotate.titled(shapes.mapping({ blob: shapes.binary() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "blob" bytea NOT NULL\n);`,
+    );
+  });
+
+  it("unknown → jsonb", () => {
+    const m = annotate.titled(
+      shapes.mapping({ payload: shapes.unknown() }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "payload" jsonb NOT NULL\n);`,
+    );
+  });
+});
+
+describe("toSQL — strings", (it) => {
+  it("varchar(N) when max set; no min check", () => {
+    const m = annotate.titled(
+      shapes.mapping({ n: annotate.max(shapes.string(), 32) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "n" varchar(32) NOT NULL\n);`,
+    );
+  });
+
+  it("text + CHECK char_length when only min set", () => {
+    const m = annotate.titled(
+      shapes.mapping({ n: annotate.min(shapes.string(), 3) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "n" text NOT NULL CHECK (char_length("n") >= 3)\n);`,
+    );
+  });
+
+  it("RegExp pattern → ~ check using .source", () => {
+    const m = annotate.titled(
+      shapes.mapping({ n: annotate.pattern(shapes.string(), /^[a-z]+$/) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "n" text NOT NULL CHECK ("n" ~ '^[a-z]+$')\n);`,
+    );
+  });
+
+  it("string pattern stored verbatim; single quotes escaped", () => {
+    const m = annotate.titled(
+      shapes.mapping({ n: annotate.pattern(shapes.string(), "it's") }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "n" text NOT NULL CHECK ("n" ~ 'it''s')\n);`,
+    );
+  });
+});
+
+describe("toSQL — numbers", (it) => {
+  it("number() → double precision (no checks)", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.number() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" double precision NOT NULL\n);`,
+    );
+  });
+
+  it("int() → bigint (no checks)", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.int() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" bigint NOT NULL\n);`,
+    );
+  });
+
+  it("int8 → smallint + tag-range CHECKs", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.int8() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" smallint NOT NULL CHECK ("x" >= -128) CHECK ("x" <= 127)\n);`,
+    );
+  });
+
+  it("uint8 → smallint + [0, 255] CHECKs", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.uint8() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" smallint NOT NULL CHECK ("x" >= 0) CHECK ("x" <= 255)\n);`,
+    );
+  });
+
+  it("int16 → smallint, no CHECKs (range matches pg type)", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.int16() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" smallint NOT NULL\n);`,
+    );
+  });
+
+  it("uint16 → integer + [0, 65535] CHECKs", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.uint16() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" integer NOT NULL CHECK ("x" >= 0) CHECK ("x" <= 65535)\n);`,
+    );
+  });
+
+  it("int32 → integer, no CHECKs", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.int32() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" integer NOT NULL\n);`,
+    );
+  });
+
+  it("uint32 → bigint + [0, 4294967295] CHECKs", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.uint32() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" bigint NOT NULL CHECK ("x" >= 0) CHECK ("x" <= 4294967295)\n);`,
+    );
+  });
+
+  it("int64 → bigint, no CHECKs", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.int64() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" bigint NOT NULL\n);`,
+    );
+  });
+
+  it("uint64 → numeric(20,0) + >= 0 CHECK", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.uint64() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" numeric(20,0) NOT NULL CHECK ("x" >= 0)\n);`,
+    );
+  });
+
+  it("float / float32 → real", () => {
+    const m = annotate.titled(
+      shapes.mapping({ a: shapes.float(), b: shapes.float32() }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "a" real NOT NULL,\n  "b" real NOT NULL\n);`,
+    );
+  });
+
+  it("float64 → double precision", () => {
+    const m = annotate.titled(shapes.mapping({ x: shapes.float64() }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" double precision NOT NULL\n);`,
+    );
+  });
+
+  it("tighter anno.min/max replaces tag bound", () => {
+    const m = annotate.titled(
+      shapes.mapping({ x: annotate.as(shapes.int16(), { min: 0, max: 100 }) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" smallint NOT NULL CHECK ("x" >= 0) CHECK ("x" <= 100)\n);`,
+    );
+  });
+
+  it("wider anno.min/max keeps the tag bound (intersection)", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        x: annotate.as(shapes.uint8(), { min: -1000, max: 1000 }),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" smallint NOT NULL CHECK ("x" >= 0) CHECK ("x" <= 255)\n);`,
+    );
+  });
+
+  it("anno.min/max on plain number → CHECKs", () => {
+    const m = annotate.titled(
+      shapes.mapping({ x: annotate.as(shapes.number(), { min: 0, max: 1 }) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "x" double precision NOT NULL CHECK ("x" >= 0) CHECK ("x" <= 1)\n);`,
+    );
+  });
+});
+
+describe("toSQL — arrays", (it) => {
+  it("array(string) → text[]", () => {
+    const m = annotate.titled(
+      shapes.mapping({ tags: shapes.array(shapes.string()) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "tags" text[] NOT NULL\n);`,
+    );
+  });
+
+  it("array(int32) → integer[]", () => {
+    const m = annotate.titled(
+      shapes.mapping({ ns: shapes.array(shapes.int32()) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "ns" integer[] NOT NULL\n);`,
+    );
+  });
+
+  it("array(varchar) element honors element max", () => {
+    const m = annotate.titled(
+      shapes.mapping({ ns: shapes.array(annotate.max(shapes.string(), 8)) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "ns" varchar(8)[] NOT NULL\n);`,
+    );
+  });
+
+  it("array(mapping) → jsonb", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        rows: shapes.array(shapes.mapping({ a: shapes.string() })),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "rows" jsonb NOT NULL\n);`,
+    );
+  });
+
+  it("array min/max → cardinality CHECKs", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        tags: annotate.as(shapes.array(shapes.string()), { min: 1, max: 3 }),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "tags" text[] NOT NULL CHECK (cardinality("tags") >= 1) CHECK (cardinality("tags") <= 3)\n);`,
+    );
+  });
+
+  it("anno.unique on array → column-level UNIQUE (cross-row)", () => {
+    const m = annotate.titled(
+      shapes.mapping({ tags: annotate.unique(shapes.array(shapes.string())) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "tags" text[] NOT NULL UNIQUE\n);`,
+    );
+  });
+
+  it("anno.uniqueItems on array → CHECK via helper + prelude function", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        tags: annotate.uniqueItems(shapes.array(shapes.string())),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      [
+        `CREATE OR REPLACE FUNCTION shapecraft_array_is_unique(anyarray) RETURNS boolean`,
+        `  LANGUAGE sql IMMUTABLE PARALLEL SAFE`,
+        `  AS $$ SELECT cardinality($1) = cardinality(ARRAY(SELECT DISTINCT unnest($1))) $$;`,
+        ``,
+        `CREATE TABLE IF NOT EXISTS "t" (`,
+        `  "tags" text[] NOT NULL CHECK (shapecraft_array_is_unique("tags"))`,
+        `);`,
+      ].join("\n"),
+    );
+  });
+
+  it("anno.unique + anno.uniqueItems → both UNIQUE and element CHECK", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        tags: annotate.unique(
+          annotate.uniqueItems(shapes.array(shapes.string())),
+        ),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      [
+        `CREATE OR REPLACE FUNCTION shapecraft_array_is_unique(anyarray) RETURNS boolean`,
+        `  LANGUAGE sql IMMUTABLE PARALLEL SAFE`,
+        `  AS $$ SELECT cardinality($1) = cardinality(ARRAY(SELECT DISTINCT unnest($1))) $$;`,
+        ``,
+        `CREATE TABLE IF NOT EXISTS "t" (`,
+        `  "tags" text[] NOT NULL UNIQUE CHECK (shapecraft_array_is_unique("tags"))`,
+        `);`,
+      ].join("\n"),
+    );
+  });
+
+  it("anno.uniqueItems on two arrays → only one prelude function emitted", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        a: annotate.uniqueItems(shapes.array(shapes.string())),
+        b: annotate.uniqueItems(shapes.array(shapes.int32())),
+      }),
+      "t",
+    );
+    const sql = ok(toSQL(m));
+    const fnOccurrences =
+      sql.split("CREATE OR REPLACE FUNCTION shapecraft_array_is_unique")
+        .length - 1;
+    expect(fnOccurrences).toBe(1);
+  });
+
+  it("anno.uniqueItems on jsonb-backed array → err", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        rows: annotate.uniqueItems(
+          shapes.array(shapes.mapping({ a: shapes.string() })),
+        ),
+      }),
+      "t",
+    );
+    expect(err(toSQL(m))).toEqual([
+      "field 'rows': uniqueItems is not supported on jsonb array columns",
+    ]);
+  });
+});
+
+describe("toSQL — vector", (it) => {
+  it("vector(3, float32) → vector(3)", () => {
+    const m = annotate.titled(
+      shapes.mapping({ emb: shapes.vector(3, shapes.float32()) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "emb" vector(3) NOT NULL\n);`,
+    );
+  });
+
+  it("vector(384) → vector(384) (default format ignored)", () => {
+    const m = annotate.titled(shapes.mapping({ emb: shapes.vector(384) }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "emb" vector(384) NOT NULL\n);`,
+    );
+  });
+});
+
+describe("toSQL — mappings / records as fields → jsonb", (it) => {
+  it("nested mapping → jsonb", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        profile: shapes.mapping({ a: shapes.string() }),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "profile" jsonb NOT NULL\n);`,
+    );
+  });
+
+  it("record → jsonb", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        counters: shapes.record(shapes.string(), shapes.int32()),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "counters" jsonb NOT NULL\n);`,
+    );
+  });
+});
+
+describe("toSQL — unions", (it) => {
+  it("string-literal union with title → CREATE TYPE enum + column type ref", () => {
+    const role = annotate.titled(
+      shapes.union(shapes.literal("admin"), shapes.literal("user")),
+      "user_role",
+    );
+    const m = annotate.titled(shapes.mapping({ role }), "users");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TYPE "user_role" AS ENUM ('admin', 'user');\n\nCREATE TABLE IF NOT EXISTS "users" (\n  "role" "user_role" NOT NULL\n);`,
+    );
+  });
+
+  it("string-literal union without title → text + IN check", () => {
+    const u = shapes.union(shapes.literal("a"), shapes.literal("b"));
+    const m = annotate.titled(shapes.mapping({ k: u }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "k" text NOT NULL CHECK ("k" IN ('a', 'b'))\n);`,
+    );
+  });
+
+  it("mixed / non-literal union → jsonb", () => {
+    const u = shapes.union(shapes.literal("a"), shapes.number());
+    const m = annotate.titled(shapes.mapping({ k: u }), "t");
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "k" jsonb NOT NULL\n);`,
+    );
+  });
+
+  it("same titled enum used twice → only one CREATE TYPE", () => {
+    const role = annotate.titled(
+      shapes.union(shapes.literal("admin"), shapes.literal("user")),
+      "user_role",
+    );
+    const m = annotate.titled(
+      shapes.mapping({ role_a: role, role_b: role }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TYPE "user_role" AS ENUM ('admin', 'user');\n\nCREATE TABLE IF NOT EXISTS "t" (\n  "role_a" "user_role" NOT NULL,\n  "role_b" "user_role" NOT NULL\n);`,
+    );
+  });
+});
+
+describe("toSQL — annotations", (it) => {
+  it("primary → PRIMARY KEY (always NOT NULL)", () => {
+    const m = annotate.titled(
+      shapes.mapping({ id: annotate.primary(shapes.int()) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "id" bigint NOT NULL PRIMARY KEY\n);`,
+    );
+  });
+
+  it("unique on scalar → UNIQUE", () => {
+    const m = annotate.titled(
+      shapes.mapping({ slug: annotate.unique(shapes.string()) }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "slug" text NOT NULL UNIQUE\n);`,
+    );
+  });
+
+  it("autoIncrement on int → GENERATED ALWAYS AS IDENTITY", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        id: annotate.primary(annotate.autoIncremented(shapes.int())),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "id" bigint NOT NULL PRIMARY KEY GENERATED ALWAYS AS IDENTITY\n);`,
+    );
+  });
+
+  it("foreign → REFERENCES", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        user_id: annotate.foreign(shapes.int(), "users", "id"),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "user_id" bigint NOT NULL REFERENCES "users"("id")\n);`,
+    );
+  });
+
+  it("string default", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        s: annotate.defaulted(shapes.string(), "hi"),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "s" text NOT NULL DEFAULT 'hi'\n);`,
+    );
+  });
+
+  it("number default", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        n: annotate.defaulted(shapes.int32(), 42),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "n" integer NOT NULL DEFAULT 42\n);`,
+    );
+  });
+
+  it("boolean default", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        b: annotate.defaulted(shapes.boolean(), true),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "b" boolean NOT NULL DEFAULT TRUE\n);`,
+    );
+  });
+
+  it("null default on optional column", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        s: annotate.as(annotate.optional(shapes.string()), { default: null }),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "s" text DEFAULT NULL\n);`,
+    );
+  });
+
+  it("object default on jsonb column", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        meta: annotate.as(shapes.unknown(), { default: { a: 1 } }),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      `CREATE TABLE IF NOT EXISTS "t" (\n  "meta" jsonb NOT NULL DEFAULT '{"a":1}'::jsonb\n);`,
+    );
+  });
+
+  it("unsupported object default on non-jsonb column → err", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        s: annotate.as(shapes.string(), { default: { a: 1 } }),
+      }),
+      "t",
+    );
+    expect(err(toSQL(m))).toEqual([
+      "field 's': default value of type object is not supported for column type text",
+    ]);
+  });
+});
+
+describe("toSQL — end-to-end users table", (it) => {
+  it("realistic users table with enum, vector, jsonb, default", () => {
+    const role = annotate.titled(
+      shapes.union(shapes.literal("admin"), shapes.literal("user")),
+      "user_role",
+    );
+    const m = annotate.titled(
+      shapes.mapping({
+        id: annotate.primary(annotate.autoIncremented(shapes.int())),
+        email: annotate.unique(
+          annotate.pattern(annotate.max(shapes.string(), 255), /.+@.+/),
+        ),
+        age: shapes.uint8(),
+        role,
+        embedding: shapes.vector(384, shapes.float32()),
+        profile: shapes.mapping({ bio: shapes.string() }),
+        created_at: annotate.as(shapes.date(), { default: null }),
+      }),
+      "users",
+    );
+
+    const sql = ok(toSQL(m));
+    expect(sql).toBe(
+      [
+        `CREATE TYPE "user_role" AS ENUM ('admin', 'user');`,
+        "",
+        `CREATE TABLE IF NOT EXISTS "users" (`,
+        `  "id" bigint NOT NULL PRIMARY KEY GENERATED ALWAYS AS IDENTITY,`,
+        `  "email" varchar(255) NOT NULL UNIQUE CHECK ("email" ~ '.+@.+'),`,
+        `  "age" smallint NOT NULL CHECK ("age" >= 0) CHECK ("age" <= 255),`,
+        `  "role" "user_role" NOT NULL,`,
+        `  "embedding" vector(384) NOT NULL,`,
+        `  "profile" jsonb NOT NULL,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT NULL`,
+        `);`,
+      ].join("\n"),
+    );
+  });
+});
+
+describe("toSQL — comments", (it) => {
+  it("column with description → single -- comment above it", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        name: annotate.described(shapes.string(), "the user's name"),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      [
+        `CREATE TABLE IF NOT EXISTS "t" (`,
+        `  -- the user's name`,
+        `  "name" text NOT NULL`,
+        `);`,
+      ].join("\n"),
+    );
+  });
+
+  it("column with description + comment → /* */ block above it", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        name: annotate.commented(
+          annotate.described(shapes.string(), "display name"),
+          "indexed",
+        ),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      [
+        `CREATE TABLE IF NOT EXISTS "t" (`,
+        `  /*`,
+        `   * display name`,
+        `   * indexed`,
+        `   */`,
+        `  "name" text NOT NULL`,
+        `);`,
+      ].join("\n"),
+    );
+  });
+
+  it("column with format → -- (format: ...) above it", () => {
+    const m = annotate.titled(
+      shapes.mapping({ email: annotate.format(shapes.string(), "email") }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      [
+        `CREATE TABLE IF NOT EXISTS "t" (`,
+        `  -- (format: email)`,
+        `  "email" text NOT NULL`,
+        `);`,
+      ].join("\n"),
+    );
+  });
+
+  it("table-level description → comment before CREATE TABLE", () => {
+    const m = annotate.described(
+      annotate.titled(shapes.mapping({ id: shapes.int() }), "t"),
+      "rows of stuff",
+    );
+    expect(ok(toSQL(m))).toBe(
+      [
+        `-- rows of stuff`,
+        `CREATE TABLE IF NOT EXISTS "t" (`,
+        `  "id" bigint NOT NULL`,
+        `);`,
+      ].join("\n"),
+    );
+  });
+
+  it("comments coexist with native column constraints", () => {
+    const m = annotate.titled(
+      shapes.mapping({
+        id: annotate.described(
+          annotate.primary(shapes.int()),
+          "the primary key",
+        ),
+      }),
+      "t",
+    );
+    expect(ok(toSQL(m))).toBe(
+      [
+        `CREATE TABLE IF NOT EXISTS "t" (`,
+        `  -- the primary key`,
+        `  "id" bigint NOT NULL PRIMARY KEY`,
+        `);`,
+      ].join("\n"),
+    );
+  });
+});
+
+describe("toSQL — module / multi-table", (it) => {
+  it("emits CREATE TABLE for each table in module", () => {
+    const m = shapes.module({
+      product: annotate.titled(
+        shapes.mapping({
+          id: annotate.autoIncremented(annotate.primary(shapes.int64())),
+          name: shapes.string(),
+        }),
+        "product",
+      ),
+      order: annotate.titled(
+        shapes.mapping({
+          id: annotate.autoIncremented(annotate.primary(shapes.int64())),
+        }),
+        "order",
+      ),
+    });
+    const sql = ok(toSQL(m));
+    expect(sql).toContain(`CREATE TABLE IF NOT EXISTS "product"`);
+    expect(sql).toContain(`CREATE TABLE IF NOT EXISTS "order"`);
+  });
+
+  it("emits tables in topological order (referenced first)", () => {
+    const m = shapes.module({
+      post: annotate.titled(
+        shapes.mapping({
+          id: annotate.autoIncremented(annotate.primary(shapes.int64())),
+          author_id: annotate.foreign(shapes.int64(), "user", "id"),
+        }),
+        "post",
+      ),
+      user: annotate.titled(
+        shapes.mapping({
+          id: annotate.autoIncremented(annotate.primary(shapes.int64())),
+        }),
+        "user",
+      ),
+    });
+    const sql = ok(toSQL(m));
+    const userIdx = sql.indexOf(`CREATE TABLE IF NOT EXISTS "user"`);
+    const postIdx = sql.indexOf(`CREATE TABLE IF NOT EXISTS "post"`);
+    expect(userIdx).toBeGreaterThanOrEqual(0);
+    expect(postIdx).toBeGreaterThan(userIdx);
+  });
+
+  it("composite PK → table-level PRIMARY KEY constraint", () => {
+    const m = shapes.module({
+      ab: annotate.titled(
+        shapes.mapping({
+          a_id: annotate.primary(annotate.foreign(shapes.int64(), "a", "id")),
+          b_id: annotate.primary(annotate.foreign(shapes.int64(), "b", "id")),
+        }),
+        "ab",
+      ),
+      a: annotate.titled(
+        shapes.mapping({
+          id: annotate.autoIncremented(annotate.primary(shapes.int64())),
+        }),
+        "a",
+      ),
+      b: annotate.titled(
+        shapes.mapping({
+          id: annotate.autoIncremented(annotate.primary(shapes.int64())),
+        }),
+        "b",
+      ),
+    });
+    const sql = ok(toSQL(m));
+    expect(sql).toContain(`PRIMARY KEY ("a_id", "b_id")`);
+    expect(sql).not.toContain(
+      `"a_id" bigint NOT NULL REFERENCES "a"("id") PRIMARY KEY`,
+    );
+  });
+
+  it("FK cycle → err", () => {
+    const m = shapes.module({
+      a: annotate.titled(
+        shapes.mapping({
+          b_ref: annotate.foreign(shapes.int64(), "b", "id"),
+        }),
+        "a",
+      ),
+      b: annotate.titled(
+        shapes.mapping({
+          a_ref: annotate.foreign(shapes.int64(), "a", "id"),
+        }),
+        "b",
+      ),
+    });
+    expect(err(toSQL(m))[0]).toMatch(/FK cycle/);
+  });
+
+  it("self-reference allowed (1-node cycle)", () => {
+    const m = shapes.module({
+      category: annotate.titled(
+        shapes.mapping({
+          id: annotate.autoIncremented(annotate.primary(shapes.int64())),
+          parent: annotate.foreign(shapes.int64(), "category", "id"),
+        }),
+        "category",
+      ),
+    });
+    const sql = ok(toSQL(m));
+    expect(sql).toContain(`CREATE TABLE IF NOT EXISTS "category"`);
+    expect(sql).toContain(`REFERENCES "category"("id")`);
+  });
+
+  it("module errors are prefixed by table name", () => {
+    const m = shapes.module({
+      bad: annotate.titled(shapes.mapping({ x: shapes.nil() }), "bad"),
+    });
+    expect(err(toSQL(m))).toEqual([
+      "table 'bad': field 'x': nil cannot be a column",
+    ]);
+  });
+});