@specverse/engines 6.17.0 → 6.18.0

package/dist/libs/instance-factories/services/templates/postgres-native/ddl-generator.js

@@ -38,25 +38,38 @@ CREATE TABLE IF NOT EXISTS "${table}" (
 );`;
   }
   const list = Array.isArray(attrs) ? attrs.map((a) => [a.name, a]) : Object.entries(attrs);
+  const compositePk = parseColumnList(model.keys ?? model.primaryKey);
+  const compositeUniques = parseCompositeUnique(model.unique);
   const columns = [];
   const indexes = [];
   let hasIdColumn = false;
+  const compositePkSet = new Set(compositePk);
   for (const [colName, attr] of list) {
     if (!colName) continue;
-    const { sql, isPk, isUnique } = columnDef(colName, attr, modelName);
+    const partOfCompositePk = compositePkSet.has(colName);
+    const { sql, isPk, isUnique } = columnDef(colName, attr, modelName, partOfCompositePk);
     if (isPk) hasIdColumn = true;
     columns.push("  " + sql);
-    if (isUnique && !isPk) {
+    if (isUnique && !isPk && !partOfCompositePk) {
       indexes.push(
         `CREATE UNIQUE INDEX IF NOT EXISTS "${table}_${colName}_uq" ON "${table}" ("${colName}");`
       );
-    } else if (colName.endsWith("Id") && colName !== "id") {
+    } else if (colName.endsWith("Id") && colName !== "id" && !partOfCompositePk) {
       indexes.push(
         `CREATE INDEX IF NOT EXISTS "${table}_${colName}_idx" ON "${table}" ("${colName}");`
       );
     }
+    const partial = parsePartialIndex(attr.index);
+    if (partial) {
+      const indexName = `${table}_${colName}${partial.unique ? "_uq" : "_idx"}_partial`;
+      const uniqueClause = partial.unique ? "UNIQUE " : "";
+      const whereClause = partial.where ? ` WHERE ${partial.where}` : "";
+      indexes.push(
+        `CREATE ${uniqueClause}INDEX IF NOT EXISTS "${indexName}" ON "${table}" ("${colName}")${whereClause};`
+      );
+    }
   }
-  if (!hasIdColumn) {
+  if (compositePk.length === 0 && !hasIdColumn) {
     columns.unshift('  "id" TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text');
   }
   const declaredNames = new Set(list.map(([n]) => n));
@@ -74,18 +87,24 @@ CREATE TABLE IF NOT EXISTS "${table}" (
     const defaultClause = initial ? ` DEFAULT '${initial.replace(/'/g, "''")}'` : "";
     columns.push(`  "${lcName}" TEXT NOT NULL${defaultClause}`);
   }
+  if (compositePk.length > 0) {
+    columns.push(`  PRIMARY KEY (${compositePk.map(quoteIdent).join(", ")})`);
+  }
+  for (const cols of compositeUniques) {
+    columns.push(`  UNIQUE (${cols.map(quoteIdent).join(", ")})`);
+  }
   const indexBlock = indexes.length > 0 ? "\n\n" + indexes.join("\n") : "";
   return `-- ${modelName}
 CREATE TABLE IF NOT EXISTS "${table}" (
 ${columns.join(",\n")}
 );${indexBlock}`;
 }
-function columnDef(name, attr, _modelName) {
-  const required = !!attr.required;
+function columnDef(name, attr, _modelName, forceNotNull) {
+  const required = !!attr.required || forceNotNull;
   const unique = !!attr.unique;
   const type = (attr.type || "String").toLowerCase();
   const isIdColumn = name === "id";
-  if (isIdColumn) {
+  if (isIdColumn && !forceNotNull) {
     if (type === "uuid") {
       return { sql: `"id" UUID PRIMARY KEY DEFAULT gen_random_uuid()`, isPk: true, isUnique: true };
     }
@@ -164,6 +183,41 @@ function formatColumnDefault(value, type) {
   }
   return "";
 }
+function parseColumnList(raw) {
+  if (raw === void 0 || raw === null) return [];
+  if (typeof raw === "string") return [raw];
+  if (!Array.isArray(raw)) return [];
+  if (raw.length === 0) return [];
+  if (typeof raw[0] === "string") return raw.filter((x) => typeof x === "string");
+  if (Array.isArray(raw[0])) {
+    return raw[0].filter((x) => typeof x === "string");
+  }
+  return [];
+}
+function parseCompositeUnique(raw) {
+  if (raw === void 0 || raw === null) return [];
+  if (!Array.isArray(raw) || raw.length === 0) return [];
+  if (typeof raw[0] === "string") {
+    return [raw.filter((x) => typeof x === "string")];
+  }
+  if (Array.isArray(raw[0])) {
+    return raw.map((row) => row.filter((x) => typeof x === "string")).filter((row) => row.length > 0);
+  }
+  return [];
+}
+function parsePartialIndex(raw) {
+  if (raw === void 0 || raw === null || raw === false) return null;
+  if (raw === true) return { where: null, unique: false };
+  if (typeof raw === "object") {
+    const where = typeof raw.where === "string" && raw.where.trim() !== "" ? raw.where.trim() : null;
+    const unique = !!raw.unique;
+    return { where, unique };
+  }
+  return null;
+}
+function quoteIdent(name) {
+  return '"' + name.replace(/"/g, '""') + '"';
+}
 export {
   generatePgSchemaSql as default
 };

package/libs/instance-factories/services/templates/postgres-native/__tests__/ddl-generator.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Regression tests for the postgres-native DDL generator.
+ *
+ * Pins existing functionality (CREATE TABLE shape, type mapping, FK
+ * indexes, lifecycle columns, default values, unique constraints) AND
+ * the new Tier 1 / Tier 2 features added in engines 6.18.0:
+ *   - Composite primary keys (`keys: [a, b]`, `primaryKey: [a, b]`)
+ *   - Composite unique constraints (`unique: [[a, b]]`)
+ *   - Partial indexes (`attr.index: { where, unique }`)
+ *   - JSON type mapping (already present; pinned as a regression)
+ *
+ * Tests assert SQL substrings rather than full-text equality so a future
+ * comment / formatting tweak doesn't cascade into 30 broken tests.
+ */
+import { describe, it, expect } from 'vitest';
+import generatePgSchemaSql from '../ddl-generator.js';
+
+const todoModel = {
+  name: 'Todo',
+  attributes: {
+    id: { name: 'id', type: 'UUID', required: true, auto: 'uuid4' },
+    title: { name: 'title', type: 'String', required: true },
+    completed: { name: 'completed', type: 'Boolean', default: false },
+  },
+};
+
+describe('postgres-native — ddl-generator (existing functionality)', () => {
+  it('emits CREATE TABLE IF NOT EXISTS + pgcrypto extension', () => {
+    const sql = generatePgSchemaSql({ models: [todoModel] } as any);
+    expect(sql).toContain('CREATE EXTENSION IF NOT EXISTS "pgcrypto"');
+    expect(sql).toContain('CREATE TABLE IF NOT EXISTS "todos"');
+  });
+
+  it('maps types correctly (TEXT/INTEGER/BOOLEAN/TIMESTAMPTZ/UUID)', () => {
+    const model = {
+      name: 'Mix',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        title: { name: 'title', type: 'String', required: true },
+        count: { name: 'count', type: 'Integer', required: true },
+        ratio: { name: 'ratio', type: 'Float' },
+        active: { name: 'active', type: 'Boolean', default: true },
+        when: { name: 'when', type: 'DateTime' },
+      },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('"title" TEXT NOT NULL');
+    expect(sql).toContain('"count" INTEGER NOT NULL');
+    expect(sql).toContain('"ratio" DOUBLE PRECISION');
+    expect(sql).toContain('"active" BOOLEAN');
+    expect(sql).toContain('"when" TIMESTAMPTZ');
+    expect(sql).toContain('"id" UUID PRIMARY KEY DEFAULT gen_random_uuid()');
+  });
+
+  it('synthesises an id column when no id is declared', () => {
+    const model = {
+      name: 'NoId',
+      attributes: { name: { name: 'name', type: 'String', required: true } },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('"id" TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text');
+  });
+
+  it('emits FK indexes for *Id columns', () => {
+    const model = {
+      name: 'Item',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        userId: { name: 'userId', type: 'UUID', required: true },
+        categoryId: { name: 'categoryId', type: 'UUID', required: true },
+      },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('CREATE INDEX IF NOT EXISTS "items_userId_idx" ON "items" ("userId")');
+    expect(sql).toContain('CREATE INDEX IF NOT EXISTS "items_categoryId_idx" ON "items" ("categoryId")');
+  });
+
+  it('emits unique indexes for column-level `unique: true`', () => {
+    const model = {
+      name: 'User',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        email: { name: 'email', type: 'String', required: true, unique: true },
+      },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('CREATE UNIQUE INDEX IF NOT EXISTS "users_email_uq" ON "users" ("email")');
+  });
+
+  it('honours `model.storage.table` override', () => {
+    const sql = generatePgSchemaSql({
+      models: [{ ...todoModel, storage: { table: 'custom_todos' } }],
+    } as any);
+    expect(sql).toContain('CREATE TABLE IF NOT EXISTS "custom_todos"');
+    expect(sql).not.toContain('CREATE TABLE IF NOT EXISTS "todos"');
+  });
+
+  it('emits lifecycle columns auto-derived from `flow:` shorthand', () => {
+    const model = {
+      ...todoModel,
+      lifecycles: { status: { name: 'status', flow: 'open -> closed' } },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain(`"status" TEXT NOT NULL DEFAULT 'open'`);
+  });
+
+  it('adds createdAt/updatedAt defaults if not declared', () => {
+    const sql = generatePgSchemaSql({ models: [todoModel] } as any);
+    expect(sql).toContain('"createdAt" TIMESTAMPTZ NOT NULL DEFAULT NOW()');
+    expect(sql).toContain('"updatedAt" TIMESTAMPTZ NOT NULL DEFAULT NOW()');
+  });
+
+  it('returns a stub when no models declared', () => {
+    expect(generatePgSchemaSql({} as any)).toContain('No models declared');
+    expect(generatePgSchemaSql({ models: [] } as any)).toContain('No models declared');
+  });
+});
+
+describe('postgres-native — ddl-generator (engines 6.18.0 — Tier 1: composite keys + uniques)', () => {
+  it('composite primary key via `keys: [a, b]` emits a table-level PRIMARY KEY constraint', () => {
+    const model = {
+      name: 'Membership',
+      attributes: {
+        tenantId: { name: 'tenantId', type: 'UUID', required: true },
+        userId: { name: 'userId', type: 'UUID', required: true },
+        role: { name: 'role', type: 'String', required: true },
+      },
+      keys: ['tenantId', 'userId'],
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    // Table-level constraint
+    expect(sql).toContain('PRIMARY KEY ("tenantId", "userId")');
+    // Both columns NOT NULL (forced by composite-PK membership)
+    expect(sql).toContain('"tenantId" UUID NOT NULL');
+    expect(sql).toContain('"userId" UUID NOT NULL');
+    // No synthesised id column (composite PK takes its place)
+    expect(sql).not.toContain('"id" TEXT PRIMARY KEY');
+  });
+
+  it('accepts `primaryKey:` as an alias for `keys:`', () => {
+    const model = {
+      name: 'Pair',
+      attributes: {
+        a: { name: 'a', type: 'String', required: true },
+        b: { name: 'b', type: 'String', required: true },
+      },
+      primaryKey: ['a', 'b'],
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('PRIMARY KEY ("a", "b")');
+  });
+
+  it('composite unique constraint via `unique: [[a, b]]`', () => {
+    const model = {
+      name: 'Slug',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        tenantId: { name: 'tenantId', type: 'UUID', required: true },
+        slug: { name: 'slug', type: 'String', required: true },
+      },
+      unique: [['tenantId', 'slug']],
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('UNIQUE ("tenantId", "slug")');
+  });
+
+  it('multiple composite uniques', () => {
+    const model = {
+      name: 'Multi',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        a: { name: 'a', type: 'String' },
+        b: { name: 'b', type: 'String' },
+        c: { name: 'c', type: 'String' },
+      },
+      unique: [['a', 'b'], ['b', 'c']],
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('UNIQUE ("a", "b")');
+    expect(sql).toContain('UNIQUE ("b", "c")');
+  });
+
+  it('a single-array `unique: [a, b]` is treated as ONE composite (not two single-column)', () => {
+    // This is the documented contract: single uniques go at the attribute
+    // level, not in `model.unique`. So `unique: ["a", "b"]` is one
+    // composite spanning a and b.
+    const model = {
+      name: 'Single',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        a: { name: 'a', type: 'String' },
+        b: { name: 'b', type: 'String' },
+      },
+      unique: ['a', 'b'],
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('UNIQUE ("a", "b")');
+    // Did NOT generate two separate single-column unique indexes.
+    expect(sql).not.toContain('"single_a_uq"');
+    expect(sql).not.toContain('"single_b_uq"');
+  });
+
+  it('does not double-emit FK indexes for columns that are part of composite PK', () => {
+    // userId is the FK that would normally get an `_idx` index. When it's
+    // part of the PK, the PK already covers index lookups starting on
+    // userId, so the extra index would be wasted disk.
+    const model = {
+      name: 'Member',
+      attributes: {
+        userId: { name: 'userId', type: 'UUID', required: true },
+        groupId: { name: 'groupId', type: 'UUID', required: true },
+      },
+      keys: ['userId', 'groupId'],
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).not.toContain('"members_userId_idx"');
+    expect(sql).not.toContain('"members_groupId_idx"');
+  });
+});
+
+describe('postgres-native — ddl-generator (engines 6.18.0 — Tier 2: partial indexes + JSON)', () => {
+  it('partial unique index via `attr.index: { where, unique: true }`', () => {
+    const model = {
+      name: 'User',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        email: {
+          name: 'email',
+          type: 'String',
+          required: true,
+          // Soft-delete-aware unique: only enforce uniqueness for live rows.
+          index: { where: '"deletedAt" IS NULL', unique: true },
+        },
+        deletedAt: { name: 'deletedAt', type: 'DateTime' },
+      },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('CREATE UNIQUE INDEX IF NOT EXISTS "users_email_uq_partial" ON "users" ("email") WHERE "deletedAt" IS NULL');
+  });
+
+  it('plain partial index via `attr.index: { where: "..." }`', () => {
+    const model = {
+      name: 'Job',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        status: {
+          name: 'status',
+          type: 'String',
+          index: { where: "status IN ('pending', 'running')" },
+        },
+      },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain(`CREATE INDEX IF NOT EXISTS "jobs_status_idx_partial" ON "jobs" ("status") WHERE status IN ('pending', 'running')`);
+  });
+
+  it('`attr.index: true` emits a plain index (no WHERE)', () => {
+    const model = {
+      name: 'Q',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        priority: { name: 'priority', type: 'Integer', index: true },
+      },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    // Index emitted without WHERE clause.
+    const idxLine = sql.match(/CREATE.*"qs_priority_idx_partial".*$/m)?.[0] ?? '';
+    expect(idxLine).toContain('"priority"');
+    expect(idxLine).not.toContain('WHERE');
+  });
+
+  it('JSON / Jsonb maps to JSONB column', () => {
+    const model = {
+      name: 'Doc',
+      attributes: {
+        id: { name: 'id', type: 'UUID', required: true },
+        payload: { name: 'payload', type: 'Json', required: true },
+        metadata: { name: 'metadata', type: 'Jsonb' },
+      },
+    };
+    const sql = generatePgSchemaSql({ models: [model] } as any);
+    expect(sql).toContain('"payload" JSONB NOT NULL');
+    expect(sql).toContain('"metadata" JSONB');
+  });
+});

package/libs/instance-factories/services/templates/postgres-native/ddl-generator.ts

@@ -13,24 +13,35 @@
  *   Float, Number                 → DOUBLE PRECISION
  *   Boolean                       → BOOLEAN
  *   DateTime, Date                → TIMESTAMPTZ
- *   Json                          → JSONB
+ *   UUID                          → UUID
+ *   Json, Jsonb                   → JSONB
  *
  * Primary key:
- *   - `id UUID required`            → id UUID PRIMARY KEY DEFAULT gen_random_uuid()
- *   - any other "id" required       → id TEXT PRIMARY KEY
+ *   - Composite via `model.keys: [a, b]` or `model.primaryKey: [a, b]` →
+ *     PRIMARY KEY (a, b) constraint at the end of the table; the columns
+ *     are forced NOT NULL and the synthesised id column is suppressed.
+ *   - `id UUID required`           → id UUID PRIMARY KEY DEFAULT gen_random_uuid()
+ *   - any other "id" required      → id TEXT PRIMARY KEY
  *
- * Out of scope (deferred): partial indexes, RLS policies, check constraints
- * derived from `min/max` ranges, composite keys.
+ * Composite unique constraints:
+ *   - `model.unique: [[a, b], [c, d]]` → UNIQUE (a, b) constraint per
+ *     entry. Mixed: a single string array `[a, b]` is interpreted as ONE
+ *     composite (NOT two single-column ones) — use the
+ *     attribute-level `unique: true` for single-column uniqueness.
+ *
+ * Partial indexes:
+ *   - `attribute.index: { where: "deleted_at IS NULL", unique: true }`
+ *     emits `CREATE [UNIQUE] INDEX ... WHERE deleted_at IS NULL` after
+ *     the table. Adopt for soft-delete + tenant-scoped uniqueness.
+ *
+ * Out of scope (deferred — see TODO #43L): RLS policies, check
+ * constraints derived from `min/max` ranges, materialised views.
  */
 import type { TemplateContext } from '@specverse/types';
 
 export default function generatePgSchemaSql(context: TemplateContext): string {
   const { spec, models } = context as any;
 
-  // Pull a flat list of {modelName, model} from the most-likely shapes:
-  //   1. Realize passes `models` (array of model specs from the resolved
-  //      component); use it directly.
-  //   2. Otherwise walk spec.components[].models.
   const allModels: Array<[string, any]> = [];
   if (Array.isArray(models) && models.length > 0) {
     for (const m of models) if (m?.name) allModels.push([m.name, m]);
@@ -77,29 +88,57 @@ function generateTable(modelName: string, model: any): string {
     ? attrs.map((a: any) => [a.name, a])
     : Object.entries(attrs);
 
+  // Composite primary key — read either `keys` or `primaryKey`. Both
+  // accepted shapes: array of strings (one composite) OR a single string
+  // (degenerate single-column PK; used by some specs as a way to point
+  // at a non-`id` column).
+  const compositePk = parseColumnList(model.keys ?? model.primaryKey);
+  // Composite uniques — array of arrays, each defining one constraint.
+  const compositeUniques = parseCompositeUnique(model.unique);
+
   const columns: string[] = [];
   const indexes: string[] = [];
   let hasIdColumn = false;
+  const compositePkSet = new Set(compositePk);
 
   for (const [colName, attr] of list) {
     if (!colName) continue;
-    const { sql, isPk, isUnique } = columnDef(colName, attr, modelName);
+    // When this column is part of a composite PK, force NOT NULL and
+    // skip the column-level PRIMARY KEY (the constraint goes at the end
+    // of the CREATE TABLE).
+    const partOfCompositePk = compositePkSet.has(colName);
+    const { sql, isPk, isUnique } = columnDef(colName, attr, modelName, partOfCompositePk);
     if (isPk) hasIdColumn = true;
     columns.push('  ' + sql);
-    if (isUnique && !isPk) {
+
+    if (isUnique && !isPk && !partOfCompositePk) {
       indexes.push(
         `CREATE UNIQUE INDEX IF NOT EXISTS "${table}_${colName}_uq" ON "${table}" ("${colName}");`,
       );
-    } else if (colName.endsWith('Id') && colName !== 'id') {
+    } else if (colName.endsWith('Id') && colName !== 'id' && !partOfCompositePk) {
       // FK columns — index for join performance.
       indexes.push(
         `CREATE INDEX IF NOT EXISTS "${table}_${colName}_idx" ON "${table}" ("${colName}");`,
       );
     }
+
+    // Partial indexes — declared at the attribute level so the column +
+    // its specialised index live together in the spec. `attr.index` is
+    // either `true` (plain index, no WHERE) or `{ where, unique }`.
+    const partial = parsePartialIndex(attr.index);
+    if (partial) {
+      const indexName = `${table}_${colName}${partial.unique ? '_uq' : '_idx'}_partial`;
+      const uniqueClause = partial.unique ? 'UNIQUE ' : '';
+      const whereClause = partial.where ? ` WHERE ${partial.where}` : '';
+      indexes.push(
+        `CREATE ${uniqueClause}INDEX IF NOT EXISTS "${indexName}" ON "${table}" ("${colName}")${whereClause};`,
+      );
+    }
   }
 
-  // No id declared in spec — synthesise one so the table is keyed.
-  if (!hasIdColumn) {
+  // Composite PK takes precedence over the synthesised id column. Skip
+  // the synthesised id only if the composite covers every "id" need.
+  if (compositePk.length === 0 && !hasIdColumn) {
     columns.unshift('  "id" TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text');
   }
 
@@ -112,11 +151,7 @@ function generateTable(modelName: string, model: any): string {
     columns.push('  "updatedAt" TIMESTAMPTZ NOT NULL DEFAULT NOW()');
   }
 
-  // Lifecycle columns — for every declared lifecycle, add a TEXT column
-  // (named after the lifecycle, defaulting to its first state) so
-  // controller.evolve has somewhere to write the transitioned state.
-  // Mongo is schemaless so this happens implicitly there; in postgres we
-  // need an explicit column.
+  // Lifecycle columns.
   const lifecycles = Array.isArray(model.lifecycles)
     ? model.lifecycles
     : (model.lifecycles ? Object.entries(model.lifecycles).map(([name, lc]: [string, any]) => ({ name, ...lc })) : []);
@@ -128,6 +163,16 @@ function generateTable(modelName: string, model: any): string {
     columns.push(`  "${lcName}" TEXT NOT NULL${defaultClause}`);
   }
 
+  // Table-level constraints (composite PK + composite uniques) go at
+  // the end of the column list so the table reads top-to-bottom in the
+  // natural order: columns, then constraints.
+  if (compositePk.length > 0) {
+    columns.push(`  PRIMARY KEY (${compositePk.map(quoteIdent).join(', ')})`);
+  }
+  for (const cols of compositeUniques) {
+    columns.push(`  UNIQUE (${cols.map(quoteIdent).join(', ')})`);
+  }
+
   const indexBlock = indexes.length > 0 ? '\n\n' + indexes.join('\n') : '';
   return `-- ${modelName}\nCREATE TABLE IF NOT EXISTS "${table}" (\n${columns.join(',\n')}\n);${indexBlock}`;
 }
@@ -138,13 +183,15 @@ interface ColumnDefResult {
   isUnique: boolean;
 }
 
-function columnDef(name: string, attr: any, _modelName: string): ColumnDefResult {
-  const required = !!attr.required;
+function columnDef(name: string, attr: any, _modelName: string, forceNotNull: boolean): ColumnDefResult {
+  const required = !!attr.required || forceNotNull;
   const unique = !!attr.unique;
   const type = (attr.type || 'String').toLowerCase();
   const isIdColumn = name === 'id';
 
-  if (isIdColumn) {
+  // When the column is part of a composite PK, suppress the column-level
+  // PRIMARY KEY — the table-level PRIMARY KEY (a, b) constraint covers it.
+  if (isIdColumn && !forceNotNull) {
     if (type === 'uuid') {
       return { sql: `"id" UUID PRIMARY KEY DEFAULT gen_random_uuid()`, isPk: true, isUnique: true };
     }
@@ -212,7 +259,6 @@ function deriveInitialState(lc: any): string | null {
     return head || null;
   }
   if (lc.transitions && typeof lc.transitions === 'object') {
-    // Pick the source side of the first transition.
     const first = Object.values(lc.transitions)[0];
     if (typeof first === 'string') return first.split(/\s*->\s*/)[0]?.trim() || null;
   }
@@ -229,8 +275,78 @@ function formatColumnDefault(value: any, type: string): string {
     if (value === 'now' && (type === 'datetime' || type === 'date' || type === 'timestamp')) {
       return ` DEFAULT NOW()`;
     }
-    // Quoted SQL string literal — escape single quotes.
     return ` DEFAULT '${value.replace(/'/g, "''")}'`;
   }
   return '';
 }
+
+/** Parse a `keys:` / `primaryKey:` declaration. Accepts:
+ *   - undefined / empty → []
+ *   - string → [string]   (single-column PK named explicitly; degenerate)
+ *   - string[] → as-is    (composite PK)
+ *   - string[][] → flatten the first entry (defensive — some specs nest)
+ */
+function parseColumnList(raw: any): string[] {
+  if (raw === undefined || raw === null) return [];
+  if (typeof raw === 'string') return [raw];
+  if (!Array.isArray(raw)) return [];
+  if (raw.length === 0) return [];
+  if (typeof raw[0] === 'string') return raw.filter((x: any): x is string => typeof x === 'string');
+  if (Array.isArray(raw[0])) {
+    return (raw[0] as any[]).filter((x: any): x is string => typeof x === 'string');
+  }
+  return [];
+}
+
+/** Parse a composite-unique declaration. Accepts:
+ *   - undefined → []
+ *   - string[]  → [[...]]   (single composite spanning the listed columns)
+ *   - string[][] → as-is    (multiple composites)
+ *
+ * Single-column uniqueness is intentionally left at the attribute level
+ * (`attr.unique: true`) so the spec author signals intent at the right
+ * scope. Mixing single + composite at this entry would be ambiguous.
+ */
+function parseCompositeUnique(raw: any): string[][] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw) || raw.length === 0) return [];
+  if (typeof raw[0] === 'string') {
+    return [raw.filter((x: any): x is string => typeof x === 'string')];
+  }
+  if (Array.isArray(raw[0])) {
+    return (raw as any[][])
+      .map((row) => row.filter((x: any): x is string => typeof x === 'string'))
+      .filter((row) => row.length > 0);
+  }
+  return [];
+}
+
+interface PartialIndex {
+  where: string | null;
+  unique: boolean;
+}
+
+/** Parse an attribute-level `index` declaration. Accepts:
+ *   - undefined / false → null         (no extra index)
+ *   - true → { where: null, unique: false }   (plain index, no WHERE — same
+ *     as a regular index but explicit; useful for non-FK columns)
+ *   - { where, unique } → as-is
+ */
+function parsePartialIndex(raw: any): PartialIndex | null {
+  if (raw === undefined || raw === null || raw === false) return null;
+  if (raw === true) return { where: null, unique: false };
+  if (typeof raw === 'object') {
+    const where = typeof raw.where === 'string' && raw.where.trim() !== ''
+      ? raw.where.trim()
+      : null;
+    const unique = !!raw.unique;
+    // No `where` AND no `unique` → equivalent to `index: true`. Still
+    // emit so the spec author's explicit declaration stays meaningful.
+    return { where, unique };
+  }
+  return null;
+}
+
+function quoteIdent(name: string): string {
+  return '"' + name.replace(/"/g, '""') + '"';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "6.17.0",
+  "version": "6.18.0",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry, bundles",
   "type": "module",
   "main": "dist/index.js",