@specverse/engines 6.66.0 → 6.75.0

package/libs/instance-factories/services/templates/prisma/controller-generator.ts

@@ -46,6 +46,14 @@ export default function generatePrismaController(context: TemplateContext): stri
   // Generate custom actions and collect AI behavior stubs
   const customActions = generateCustomActions(controller, modelName, modelVar);
 
+  // Phase 2 — the guards module only exists for models with declared
+  // constraints, so import + invocation are gated on this flag. Computed
+  // up-front so generateValidateMethod / generateEvolveMethod /
+  // generateDeleteMethod can emit the runConstraintGuards call.
+  const hasConstraints =
+    Array.isArray((model as any).constraints) &&
+    (model as any).constraints.length > 0;
+
   // Build the class body first, then introspect to decide which
   // top-of-file declarations are actually needed. Controllers with no
   // CURVED ops and no prisma-using custom actions (e.g. a controller
@@ -54,12 +62,12 @@ export default function generatePrismaController(context: TemplateContext): stri
   // unconditionally produced TS6133 unused-decl errors at every
   // realize run. Gating on actual body content drops those.
   const classBody = [
-    generateValidateMethod(model, modelName),
-    curedOps.create ? generateCreateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : '',
+    generateValidateMethod(model, modelName, hasConstraints),
+    curedOps.create ? generateCreateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels, hasConstraints) : '',
     curedOps.retrieve ? generateRetrieveMethod(model, modelName, modelVar, prismaDelegate) : '',
-    curedOps.update ? generateUpdateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : '',
-    curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, prismaDelegate, controller) : '',
-    curedOps.delete ? generateDeleteMethod(model, modelName, modelVar, prismaDelegate, controller) : '',
+    curedOps.update ? generateUpdateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels, hasConstraints) : '',
+    curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, prismaDelegate, controller, hasConstraints) : '',
+    curedOps.delete ? generateDeleteMethod(model, modelName, modelVar, prismaDelegate, controller, hasConstraints) : '',
     customActions.code,
   ].filter(Boolean).join('\n  ');
 
@@ -78,6 +86,9 @@ export default function generatePrismaController(context: TemplateContext): stri
     usesPrisma ? `import { PrismaClient } from '@prisma/client';` : '',
     usesEventBus ? `import { eventBus } from '../events/eventBus.js';` : '',
     usesAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : '',
+    hasConstraints
+      ? `import { runGuards as runConstraintGuards } from './${modelName}.guards.js';`
+      : '',
   ].filter(Boolean).join('\n');
 
   const declarations = [
@@ -112,20 +123,60 @@ export default ${modelVar}Controller;
 
 /**
  * Generate validate method (unified validation for all operations)
+ *
+ * Phase 2 — when the model has declared constraints, the body ALSO calls
+ * `runConstraintGuards(data, op, actor)` from the per-model `.guards.ts`
+ * module and appends any constraint violation messages to the errors
+ * array. `op:` shape supports the wider CURVED vocabulary including
+ * `delete` and `evolve.<transition>`.
  */
-function generateValidateMethod(model: any, modelName: string): string {
+function generateValidateMethod(model: any, modelName: string, hasConstraints: boolean): string {
+  // The `_context.operation` union widens for Phase 2 so the guards
+  // module's matchesOp() can match evolve.<transition> and delete records.
+  const opTypeUnion = hasConstraints
+    ? `'create' | 'update' | 'evolve' | 'delete' | \`evolve.\${string}\``
+    : `'create' | 'update' | 'evolve'`;
+
+  const constraintsCheck = hasConstraints
+    ? `
+    // Phase 2 — run model.constraints[] guards matching this operation.
+    // ctx carries a per-model query helper so subquery sugars (rewritten
+    // to async guards by guards-generator) can run their findFirst calls.
+    const __guardCtx = {
+      query: (modelName: string) => {
+        const delegate = (prisma as any)[modelName.charAt(0).toLowerCase() + modelName.slice(1)];
+        if (!delegate) return undefined;
+        return {
+          exists: async (predicate: (e: any) => boolean) => {
+            const all = await delegate.findMany();
+            return all.some(predicate);
+          },
+        };
+      },
+    };
+    const constraintViolations = await runConstraintGuards(_data, _context.operation, _actor, __guardCtx);
+    for (const v of constraintViolations) errors.push(v.message);`
+    : '';
+
+  // Phase 2 actor wiring — validate() ALWAYS accepts _actor (default null)
+  // even on unconstrained models, so route handlers can pass it unconditionally
+  // without per-model knowledge of whether constraints exist.
+  // Slice 15b — validate is async (it awaits runConstraintGuards which may
+  // execute subquery sugars). Callers must await this.validate(...).
+
   return `
   /**
    * Validate ${modelName} data
    * Unified validation method for all operations
    */
-  public validate(
+  public async validate(
     _data: any,
-    _context: { operation: 'create' | 'update' | 'evolve' }
-  ): { valid: boolean; errors: string[] } {
+    _context: { operation: ${opTypeUnion} },
+    _actor: any = null
+  ): Promise<{ valid: boolean; errors: string[] }> {
     const errors: string[] = [];
 
-    ${generateValidationLogic(model, '_data', '_context')}
+    ${generateValidationLogic(model, '_data', '_context')}${constraintsCheck}
 
     return {
       valid: errors.length === 0,
@@ -196,14 +247,28 @@ function generateValidationLogic(model: any, dataParam: string = '_data', contex
 /**
  * Generate create method
  */
-function generateCreateMethod(model: any, modelName: string, modelVar: string, prismaDelegate: string, controller: any, allModels?: any[]): string {
+function generateCreateMethod(model: any, modelName: string, modelVar: string, prismaDelegate: string, controller: any, allModels?: any[], hasConstraints: boolean = false): string {
+  const belongsToLoad = hasConstraints ? generateBelongsToLoad(model, allModels) : '';
+  const validateSelf = belongsToLoad ? '__mergedSelf' : 'data';
+
   return `
   /**
    * Create a new ${modelName}
    */
-  public async create(data: any): Promise<any> {
+  public async create(data: any, _actor: any = null): Promise<any> {
+${belongsToLoad ? `
+    // Phase 2 Slice 15 — Create-time relation loading. For each belongsTo
+    // FK present in input, load the related entity and merge into self
+    // so constraints traversing self.<rel>.<field> see the full related
+    // record (not just the FK id). Mirrors Slice 8's Update pattern but
+    // for the create path. Only fires when the model has declared
+    // constraints; one extra round-trip per FK in input.
+    const __loadedRels: Record<string, any> = {};
+    ${belongsToLoad}
+    const __mergedSelf = { ...data, ...__loadedRels };
+` : ''}
     // Validate input
-    const validationResult = this.validate(data, { operation: 'create' });
+    const validationResult = await this.validate(${validateSelf}, { operation: 'create' }, _actor);
     if (!validationResult.valid) {
       throw new Error(\`Validation failed: \${validationResult.errors.join(', ')}\`);
     }
@@ -225,6 +290,52 @@ function generateCreateMethod(model: any, modelName: string, modelVar: string, p
 `;
 }
 
+/**
+ * Phase 2 Slice 15 — emit `if (data.<fkField>) __loadedRels.<relName> = await prisma.<target>.findUnique(...)`
+ * statements for each belongsTo relationship. Used by create() to load
+ * related entities before constraint guards run.
+ *
+ * IDs are parsed via parseId() when the target model has an Integer id;
+ * UUID/String targets pass through as-is (parseId is the no-op identity
+ * function for those).
+ */
+function generateBelongsToLoad(model: any, allModels?: any[]): string {
+  const rels = Array.isArray(model.relationships)
+    ? model.relationships
+    : Object.values(model.relationships || {});
+
+  const belongsToRels = (rels as any[]).filter(r => r.type === 'belongsTo');
+  if (belongsToRels.length === 0) return '';
+
+  const RESERVED_WORDS = new Set(['import', 'export', 'default', 'class', 'function', 'return', 'delete', 'new', 'this', 'switch', 'case', 'break', 'continue', 'for', 'while', 'do', 'if', 'else', 'try', 'catch', 'finally', 'throw', 'typeof', 'instanceof', 'in', 'of', 'let', 'const', 'var', 'void', 'with', 'yield', 'async', 'await', 'enum', 'implements', 'interface', 'package', 'private', 'protected', 'public', 'static', 'super', 'extends']);
+
+  return belongsToRels.map((rel: any) => {
+    const relName = rel.name;
+    const targetName = rel.target;
+    const fkField = `${relName}Id`;
+    const targetVar = targetName.charAt(0).toLowerCase() + targetName.slice(1);
+    const targetDelegate = RESERVED_WORDS.has(targetVar) ? `prisma['${targetVar}']` : `prisma.${targetVar}`;
+
+    // Determine if target uses int IDs
+    let idExpr = `data.${fkField}`;
+    if (allModels) {
+      const targetModel = allModels.find((m: any) => m.name === targetName);
+      if (targetModel) {
+        const idAttr = (Array.isArray(targetModel.attributes) ? targetModel.attributes : Object.values(targetModel.attributes || {}))
+          .find((a: any) => a.name === 'id');
+        const idType = idAttr?.type || 'String';
+        if (idType === 'Integer' || idType === 'Int' || idType === 'Number') {
+          idExpr = `parseInt(data.${fkField}, 10)`;
+        }
+      }
+    }
+
+    return `if (data.${fkField}) {
+      __loadedRels.${relName} = await ${targetDelegate}.findUnique({ where: { id: ${idExpr} } });
+    }`;
+  }).join('\n    ');
+}
+
 /**
  * Generate retrieve method
  */
@@ -255,14 +366,26 @@ function generateRetrieveMethod(model: any, modelName: string, modelVar: string,
 /**
  * Generate update method
  */
-function generateUpdateMethod(model: any, modelName: string, modelVar: string, prismaDelegate: string, controller: any, allModels?: any[]): string {
+function generateUpdateMethod(model: any, modelName: string, modelVar: string, prismaDelegate: string, controller: any, allModels?: any[], hasConstraints: boolean = false): string {
   return `
   /**
    * Update ${modelName}
    */
-  public async update(id: string, data: any): Promise<any> {
+  public async update(id: string, data: any, _actor: any = null): Promise<any> {
+${hasConstraints ? `
+    // Phase 2 — Update self-from-DB: load the entity first and validate
+    // against the MERGED \`loaded + input\` shape so update-time constraints
+    // like \`self.poll.votingStatus == "open"\` see the full record even
+    // when the caller only sent a partial payload. Costs one extra DB
+    // round-trip; only fires for models with declared constraints.
+    const __existing = await ${prismaDelegate}.findUnique({ where: { id: parseId(id) }${generateIncludeRelationships(model)} });
+    if (!__existing) throw new Error('${modelName} not found');
+    const __merged = { ...__existing, ...data };
+    const validationResult = await this.validate(__merged, { operation: 'update' }, _actor);
+` : `
     // Validate input
-    const validationResult = this.validate(data, { operation: 'update' });
+    const validationResult = await this.validate(data, { operation: 'update' }, _actor);
+`}
     if (!validationResult.valid) {
       throw new Error(\`Validation failed: \${validationResult.errors.join(', ')}\`);
     }
@@ -296,7 +419,7 @@ function generateUpdateMethod(model: any, modelName: string, modelVar: string, p
 /**
  * Generate evolve method (lifecycle-aware updates)
  */
-function generateEvolveMethod(model: any, modelName: string, modelVar: string, prismaDelegate: string, controller: any): string {
+function generateEvolveMethod(model: any, modelName: string, modelVar: string, prismaDelegate: string, controller: any, hasConstraints: boolean = false): string {
   // Extract lifecycle — handle both array and object format
   const lifecycles = Array.isArray(model.lifecycles) ? model.lifecycles :
     (model.lifecycles ? Object.entries(model.lifecycles).map(([name, lc]: [string, any]) => ({ name, ...lc })) : []);
@@ -307,6 +430,22 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, p
   // Build transition map using shared spec-rules
   const validTransitions = lifecycle ? buildTransitionMap(lifecycle) : {};
 
+  // Phase 2 — reverse map (currentState -> targetState -> actionName) so
+  // evolve() can pass the correct `evolve.<actionName>` op to validate.
+  // Falls through to the targetState string for shorthand-flow lifecycles
+  // that don't have named transition actions.
+  const evolveOpsMap: Record<string, Record<string, string>> = {};
+  if (lifecycle?.transitions) {
+    for (const [actionName, t] of Object.entries(lifecycle.transitions as Record<string, any>)) {
+      const from = (t as any).from;
+      const to = (t as any).to;
+      if (typeof from === 'string' && typeof to === 'string') {
+        evolveOpsMap[from] = evolveOpsMap[from] ?? {};
+        evolveOpsMap[from][to] = actionName;
+      }
+    }
+  }
+
   return `
   /**
    * Evolve ${modelName} through lifecycle "${lifecycleName}"
@@ -317,7 +456,7 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, p
    * runtime's useTransitionStateMutation always sends the former; the
    * realized smoke-parity script can send either.
    */
-  public async evolve(id: string, data: any): Promise<any> {
+  public async evolve(id: string, data: any, _actor: any = null): Promise<any> {
     // Get current record to check lifecycle state
     const current = await ${prismaDelegate}.findUnique({ where: { id: parseId(id) } });
     if (!current) {
@@ -342,7 +481,22 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, p
       throw new Error(\`Invalid transition: \${currentState} → \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
     }
     ` : ''}
-
+${hasConstraints ? `
+    // Phase 2 — resolve the transition's action name so constraints scoped
+    // to \`on: 'evolve.<action>'\` match correctly. EVOLVE_OPS is baked at
+    // codegen from the lifecycle definition.
+    const EVOLVE_OPS: Record<string, Record<string, string>> = ${JSON.stringify(evolveOpsMap)};
+    const currentStateForOp = (current as any)[targetLifecycle];
+    const actionName = EVOLVE_OPS[currentStateForOp]?.[targetState] ?? targetState;
+    const evolveValidation = await this.validate(
+      { ...data, ...current, [targetLifecycle]: targetState },
+      { operation: \`evolve.\${actionName}\` as any },
+      _actor
+    );
+    if (!evolveValidation.valid) {
+      throw new Error(\`Validation failed: \${evolveValidation.errors.join(', ')}\`);
+    }
+` : ''}
     // Build the Prisma update payload — only the lifecycle column
     // changes. Strips toState/lifecycleName/state so Prisma doesn't
     // reject unknown fields.
@@ -365,15 +519,25 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, p
 /**
  * Generate delete method
  */
-function generateDeleteMethod(model: any, modelName: string, modelVar: string, prismaDelegate: string, controller: any): string {
+function generateDeleteMethod(model: any, modelName: string, modelVar: string, prismaDelegate: string, controller: any, hasConstraints: boolean = false): string {
   return `
   /**
    * Delete ${modelName}
    */
-  public async delete(id: string): Promise<void> {
+  public async delete(id: string, _actor: any = null): Promise<void> {
     // Get record before deletion for event
     const ${modelVar} = await ${prismaDelegate}.findUnique({ where: { id: parseId(id) } });
-
+${hasConstraints ? `
+    // Phase 2 — run delete-scoped constraint guards against the loaded
+    // record. \`self\` is the entity being deleted (loaded above), giving
+    // delete-time constraints access to the entity's current field values.
+    if (${modelVar}) {
+      const deleteValidation = await this.validate(${modelVar}, { operation: 'delete' }, _actor);
+      if (!deleteValidation.valid) {
+        throw new Error(\`Validation failed: \${deleteValidation.errors.join(', ')}\`);
+      }
+    }
+` : ''}
     await ${prismaDelegate}.delete({
       where: { id: parseId(id) }
     });

package/package.json

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