@specverse/engines 6.16.0 → 6.18.0

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/libs/instance-factories/services/templates/prisma/ai-behaviors-generator.ts

@@ -19,6 +19,7 @@
 
 import type { TemplateContext } from '@specverse/types';
 import { matchStep, type StepContext } from './step-conventions.js';
+import { validateImportWhitelist } from '@specverse/engines/ai';
 import { createHash } from 'crypto';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'fs';
 import { dirname, join } from 'path';
@@ -59,6 +60,26 @@ async function validateTypeScript(code: string): Promise<string | null> {
  * unused locals, undefined references. Reprompting with the tsc error
  * lets the LLM self-correct without burning a per-step retry.
  */
+/**
+ * Validate that every dynamic `await import('LIT')` in `code` references
+ * a whitelisted library. Returns null if clean; an error message
+ * otherwise. The whitelist (and the rationale behind each entry) lives
+ * in `engines/src/ai/library-whitelist.ts` — single source of truth.
+ *
+ * This closes the gap noted in TODO #43K-B-review: pre-fix, the type
+ * validator above failed on every dynamic import (whitelisted or not)
+ * because the engines workspace has none of the whitelist libs
+ * installed; bodies were silently routed through the AI-INVALID
+ * fallback regardless of import legality. Bodies importing
+ * non-whitelisted libs would crash at runtime in the realized backend.
+ * Now we reject them at generation time.
+ */
+function validateImports(code: string): string | null {
+  const offenders = validateImportWhitelist(code);
+  if (offenders.length === 0) return null;
+  return `import not in whitelist: ${offenders.join(', ')} (allowed: jsonwebtoken | bcryptjs | uuid | crypto | expr-eval)`;
+}
+
 async function validateTypeScriptTypes(code: string): Promise<string | null> {
   let ts: any;
   try {
@@ -135,7 +156,7 @@ async function validateTypeScriptTypes(code: string): Promise<string | null> {
  * produces a new hash. The prompt version is part of the hash so
  * prompt upgrades also invalidate.
  */
-const PROMPT_VERSION = '9.7.0';
+const PROMPT_VERSION = '9.8.0';  // 9.8: import-whitelist enforcement (#43K-B-review)
 
 function cacheKey(step: string, modelName: string, operationName: string, functionName: string, inputs: string[]): string {
   const payload = JSON.stringify({ step, modelName, operationName, functionName, inputs: [...inputs].sort(), v: PROMPT_VERSION });
@@ -458,8 +479,9 @@ export async function generateAiBehaviorsFile(opts: {
       const testCode = `export async function ${functionName}(input: any): Promise<any> {\n${body}\n}`;
       const syntaxError = await validateTypeScript(testCode);
       const typeError = syntaxError ? null : await validateTypeScriptTypes(testCode);
-      if (syntaxError || typeError) {
-        console.warn(`      [ai-validate] cached ${functionName} failed validation: ${syntaxError || typeError}`);
+      const importError = (syntaxError || typeError) ? null : validateImports(testCode);
+      if (syntaxError || typeError || importError) {
+        console.warn(`      [ai-validate] cached ${functionName} failed validation: ${syntaxError || typeError || importError}`);
         body = null;  // Force regeneration
         source = 'STUB';
       } else {
@@ -498,10 +520,18 @@ export async function generateAiBehaviorsFile(opts: {
             source = 'AI-INVALID';
           } else {
             const typeError = await validateTypeScriptTypes(testCode);
-            if (typeError) {
-              console.warn(`      [ai-validate] ${functionName} type errors: ${typeError}`);
+            // Whitelist gate runs after type check so error precedence is
+            // syntax > types > imports (most-actionable error first).
+            const importError = typeError ? null : validateImports(testCode);
+            if (typeError || importError) {
+              console.warn(`      [ai-validate] ${functionName} ${typeError ? 'type errors: ' + typeError : 'whitelist violation: ' + importError}`);
               try {
-                const retryHint = `Your previous output produced TypeScript type errors:\n${typeError}\n\nFix these specifically — common causes:\n- RegExp match indices are 'string | undefined'; use non-null assertion or extract to a typed variable\n- Strict null checks: guard or assert before use\n- Don't declare locals you never reference\n\nIMPORTANT: The destructure line \`const { ... } = input;\` is added by the wrapper, NOT by you. Output ONLY the function body that goes AFTER that line — do not repeat the destructure or you will produce duplicate-declaration errors.`;
+                // Build a retry hint that targets whichever gate failed.
+                // Mixed failures (type AND import) get both messages.
+                const errorParts: string[] = [];
+                if (typeError) errorParts.push(`TypeScript type errors:\n${typeError}`);
+                if (importError) errorParts.push(`Import-whitelist violation: ${importError}.\nOnly these libraries may be dynamic-imported: jsonwebtoken, bcryptjs, uuid, crypto, expr-eval. Anything else is forbidden — throw an Error if the step needs an unsupported library.`);
+                const retryHint = `Your previous output had problems:\n\n${errorParts.join('\n\n')}\n\nFix these specifically — common type-error causes:\n- RegExp match indices are 'string | undefined'; use non-null assertion or extract to a typed variable\n- Strict null checks: guard or assert before use\n- Don't declare locals you never reference\n\nIMPORTANT: The destructure line \`const { ... } = input;\` is added by the wrapper, NOT by you. Output ONLY the function body that goes AFTER that line — do not repeat the destructure or you will produce duplicate-declaration errors.`;
                 const retried = await aiService.generateBehavior({
                   step: `${step}\n\n${retryHint}`,
                   modelName,
@@ -516,7 +546,8 @@ export async function generateAiBehaviorsFile(opts: {
                   const retryCode = `export async function ${functionName}(input: any): Promise<any> {\n${retried}\n}`;
                   const retrySyntaxError = await validateTypeScript(retryCode);
                   const retryTypeError = retrySyntaxError ? null : await validateTypeScriptTypes(retryCode);
-                  if (!retrySyntaxError && !retryTypeError) {
+                  const retryImportError = (retrySyntaxError || retryTypeError) ? null : validateImports(retryCode);
+                  if (!retrySyntaxError && !retryTypeError && !retryImportError) {
                     body = retried;
                     source = 'AI-GENERATED';
                     cacheWrite(key, body);

package/package.json

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