@specverse/engines 6.66.0 → 6.75.0

package/dist/libs/instance-factories/services/templates/mongodb-native/controller-generator.js

@@ -15,12 +15,13 @@ function generateMongoNativeController(context) {
     Object.assign(modelRegistry, models);
   }
   const customActions = generateCustomActions(controller, modelRegistry);
-  const validate = generateValidateMethod(model, modelName);
-  const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection) : "";
+  const hasConstraints = Array.isArray(model.constraints) && model.constraints.length > 0;
+  const validate = generateValidateMethod(model, modelName, hasConstraints);
+  const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection, hasConstraints) : "";
   const retrieve = curedOps.retrieve ? generateRetrieveMethod(modelName, modelVar, collection) : "";
-  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar, collection) : "";
-  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, collection) : "";
-  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar, collection) : "";
+  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar, collection, hasConstraints) : "";
+  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, collection, hasConstraints) : "";
+  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar, collection, hasConstraints) : "";
   const hasEventPublishing = curedOps.create || curedOps.update || curedOps.evolve || curedOps.delete;
   return `/**
  * ${controllerName}
@@ -31,6 +32,7 @@ import { ObjectId, type Filter, type Document } from 'mongodb';
 import { getCollection } from '../db/mongoClient.js';
 ${hasEventPublishing || customActions.needsAiBehaviors ? `import { eventBus } from '../events/eventBus.js';` : ""}
 ${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${controllerName}.ai.js';` : ""}
+${hasConstraints ? `import { runGuards as runConstraintGuards } from './${modelName}.guards.js';` : ""}
 
 const COLLECTION_NAME = '${collection}';
 
@@ -67,17 +69,33 @@ function collectionName(model) {
   if (model?.storage?.collection) return String(model.storage.collection);
   return model.name.toLowerCase() + "s";
 }
-function generateValidateMethod(model, modelName) {
+function generateValidateMethod(model, modelName, hasConstraints) {
+  const opTypeUnion = hasConstraints ? `'create' | 'update' | 'evolve' | 'delete' | \`evolve.\${string}\`` : `'create' | 'update' | 'evolve'`;
+  const constraintsCheck = hasConstraints ? `
+    // Phase 2 \u2014 run model.constraints[] guards matching this operation.
+    // Slice 15b \u2014 ctx carries a per-model query helper for subquery sugars.
+    const __guardCtx = {
+      query: (modelName: string) => ({
+        exists: async (predicate: (e: any) => boolean) => {
+          const __col = await getCollection(modelName.toLowerCase() + 's');
+          const all = await __col.find({}).toArray();
+          return all.some(predicate);
+        },
+      }),
+    };
+    const constraintViolations = await runConstraintGuards(_data, _context.operation, _actor, __guardCtx);
+    for (const v of constraintViolations) errors.push(v.message);` : "";
   return `
   /**
-   * Validate ${modelName} data \u2014 runs before create / update / evolve.
+   * Validate ${modelName} data \u2014 runs before create / update / evolve / delete.
    */
-  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)}
+${generateValidationLogic(model)}${constraintsCheck}
     return { valid: errors.length === 0, errors };
   }
 `;
@@ -104,13 +122,24 @@ function generateValidationLogic(model) {
   });
   return out.join("\n") || "    // No validation rules defined";
 }
-function generateCreateMethod(model, modelName, modelVar, collection) {
+function generateCreateMethod(model, modelName, modelVar, collection, hasConstraints = false) {
+  const belongsToLoad = hasConstraints ? generateMongoBelongsToLoad(model) : "";
+  const validateSelf = belongsToLoad ? "__mergedSelf" : "data";
   return `
   /**
    * Create a new ${modelName}.
    */
-  public async create(data: any): Promise<any> {
-    const validation = this.validate(data, { operation: 'create' });
+  public async create(data: any, _actor: any = null): Promise<any> {
+${belongsToLoad ? `
+    // Phase 2 Slice 15 \u2014 Create-time relation loading. Mirrors prisma's
+    // pattern: for each belongsTo FK in input, load the related doc and
+    // merge into self so constraint guards traversing self.<rel> see
+    // the full related entity, not just the FK id.
+    const __loadedRels: Record<string, any> = {};
+    ${belongsToLoad}
+    const __mergedSelf = { ...data, ...__loadedRels };
+` : ""}
+    const validation = await this.validate(${validateSelf}, { operation: 'create' }, _actor);
     if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
 
     const collection = await getCollection(COLLECTION_NAME);
@@ -122,6 +151,20 @@ function generateCreateMethod(model, modelName, modelVar, collection) {
   }
 `;
 }
+function generateMongoBelongsToLoad(model) {
+  const rels = Array.isArray(model.relationships) ? model.relationships : Object.values(model.relationships || {});
+  const belongsToRels = rels.filter((r) => r.type === "belongsTo");
+  if (belongsToRels.length === 0) return "";
+  return belongsToRels.map((rel) => {
+    const relName = rel.name;
+    const targetName = rel.target;
+    const fkField = `${relName}Id`;
+    return `if (data.${fkField}) {
+      const __col_${relName} = await getCollection('${targetName.toLowerCase()}s');
+      __loadedRels.${relName} = await __col_${relName}.findOne(byId(data.${fkField}));
+    }`;
+  }).join("\n    ");
+}
 function generateRetrieveMethod(modelName, modelVar, collection) {
   return `
   /**
@@ -144,13 +187,23 @@ function generateRetrieveMethod(modelName, modelVar, collection) {
   }
 `;
 }
-function generateUpdateMethod(modelName, modelVar, collection) {
+function generateUpdateMethod(modelName, modelVar, collection, hasConstraints = false) {
   return `
   /**
    * Update ${modelName}.
    */
-  public async update(id: string, data: any): Promise<any> {
-    const validation = this.validate(data, { operation: 'update' });
+  public async update(id: string, data: any, _actor: any = null): Promise<any> {
+    const collection = await getCollection(COLLECTION_NAME);
+${hasConstraints ? `
+    // Phase 2 \u2014 Update self-from-DB. Load + merge before validate so
+    // update-time constraints see the full entity, not just the partial input.
+    const __existing = await collection.findOne(byId(id));
+    if (!__existing) throw new Error('${modelName} not found');
+    const __merged = { ...__existing, ...data };
+    const validation = await this.validate(__merged, { operation: 'update' }, _actor);
+` : `
+    const validation = await this.validate(data, { operation: 'update' }, _actor);
+`}
     if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
 
     // Strip nested objects + id \u2014 only scalar fields are written.
@@ -162,7 +215,6 @@ function generateUpdateMethod(modelName, modelVar, collection) {
       updateData[key] = value;
     }
 
-    const collection = await getCollection(COLLECTION_NAME);
     await collection.updateOne(byId(id), { $set: updateData });
     const ${modelVar} = await collection.findOne(byId(id));
     if (!${modelVar}) throw new Error('${modelName} not found after update');
@@ -172,7 +224,7 @@ function generateUpdateMethod(modelName, modelVar, collection) {
   }
 `;
 }
-function generateEvolveMethod(model, modelName, modelVar, collection) {
+function generateEvolveMethod(model, modelName, modelVar, collection, hasConstraints = false) {
   const lifecycles = Array.isArray(model.lifecycles) ? model.lifecycles : model.lifecycles ? Object.entries(model.lifecycles).map(([name, lc]) => ({ name, ...lc })) : [];
   const lifecycle = lifecycles[0];
   const lifecycleName = lifecycle?.name || "status";
@@ -181,12 +233,23 @@ function generateEvolveMethod(model, modelName, modelVar, collection) {
     ...Object.keys(validTransitions),
     ...Object.values(validTransitions).flat()
   ]));
+  const evolveOpsMap = {};
+  if (lifecycle?.transitions) {
+    for (const [actionName, t] of Object.entries(lifecycle.transitions)) {
+      const from = t.from;
+      const to = t.to;
+      if (typeof from === "string" && typeof to === "string") {
+        evolveOpsMap[from] = evolveOpsMap[from] ?? {};
+        evolveOpsMap[from][to] = actionName;
+      }
+    }
+  }
   return `
   /**
    * Evolve ${modelName} through lifecycle "${lifecycleName}"
    * States: ${states.join(" \u2192 ") || "(none declared)"}
    */
-  public async evolve(id: string, data: any): Promise<any> {
+  public async evolve(id: string, data: any, _actor: any = null): Promise<any> {
     const collection = await getCollection(COLLECTION_NAME);
     const current = await collection.findOne(byId(id));
     if (!current) throw new Error('${modelName} not found');
@@ -203,7 +266,22 @@ function generateEvolveMethod(model, modelName, modelVar, collection) {
       throw new Error(\`Invalid transition: \${currentState} \u2192 \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
     }
     ` : ""}
-
+${hasConstraints ? `
+    // Phase 2 \u2014 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(', ')}\`);
+    }
+` : ""}
     await collection.updateOne(byId(id), { $set: { [targetLifecycle]: targetState } });
     const ${modelVar} = await collection.findOne(byId(id));
     if (!${modelVar}) throw new Error('${modelName} not found after evolve');
@@ -213,14 +291,23 @@ function generateEvolveMethod(model, modelName, modelVar, collection) {
   }
 `;
 }
-function generateDeleteMethod(modelName, modelVar, collection) {
+function generateDeleteMethod(modelName, modelVar, collection, hasConstraints = false) {
   return `
   /**
    * Delete ${modelName}.
    */
-  public async delete(id: string): Promise<void> {
+  public async delete(id: string, _actor: any = null): Promise<void> {
     const collection = await getCollection(COLLECTION_NAME);
     const ${modelVar} = await collection.findOne(byId(id));
+${hasConstraints ? `
+    // Phase 2 \u2014 run delete-scoped constraint guards against the loaded record.
+    if (${modelVar}) {
+      const deleteValidation = await this.validate(${modelVar}, { operation: 'delete' }, _actor);
+      if (!deleteValidation.valid) {
+        throw new Error(\`Validation failed: \${deleteValidation.errors.join(', ')}\`);
+      }
+    }
+` : ""}
     await collection.deleteOne(byId(id));
     if (${modelVar}) {
       await eventBus.publish('${modelName}Deleted', { ...${modelVar}, timestamp: new Date().toISOString() } as any);

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

@@ -15,12 +15,13 @@ function generatePgNativeController(context) {
     Object.assign(modelRegistry, models);
   }
   const customActions = generateCustomActions(controller, modelRegistry);
-  const validate = generateValidateMethod(model, modelName);
-  const create = curedOps.create ? generateCreateMethod(modelName, modelVar) : "";
+  const hasConstraints = Array.isArray(model.constraints) && model.constraints.length > 0;
+  const validate = generateValidateMethod(model, modelName, hasConstraints);
+  const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, hasConstraints) : "";
   const retrieve = curedOps.retrieve ? generateRetrieveMethod(modelName, modelVar) : "";
-  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar) : "";
-  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar) : "";
-  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar) : "";
+  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar, hasConstraints) : "";
+  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, hasConstraints) : "";
+  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar, hasConstraints) : "";
   const hasEventPublishing = curedOps.create || curedOps.update || curedOps.evolve || curedOps.delete;
   const helperImports = [
     "insertOne",
@@ -40,6 +41,7 @@ function generatePgNativeController(context) {
 import { ${helperImports} } from '../db/pgClient.js';
 ${hasEventPublishing || customActions.needsAiBehaviors ? `import { eventBus } from '../events/eventBus.js';` : ""}
 ${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${controllerName}.ai.js';` : ""}
+${hasConstraints ? `import { runGuards as runConstraintGuards } from './${modelName}.guards.js';` : ""}
 
 const TABLE_NAME = '${table}';
 
@@ -64,17 +66,32 @@ function tableName(model) {
   if (model?.storage?.table) return String(model.storage.table);
   return model.name.toLowerCase() + "s";
 }
-function generateValidateMethod(model, modelName) {
+function generateValidateMethod(model, modelName, hasConstraints) {
+  const opTypeUnion = hasConstraints ? `'create' | 'update' | 'evolve' | 'delete' | \`evolve.\${string}\`` : `'create' | 'update' | 'evolve'`;
+  const constraintsCheck = hasConstraints ? `
+    // Phase 2 \u2014 run model.constraints[] guards matching this operation.
+    // Slice 15b \u2014 ctx carries a per-model query helper for subquery sugars.
+    const __guardCtx = {
+      query: (modelName: string) => ({
+        exists: async (predicate: (e: any) => boolean) => {
+          const all = await findAll(modelName);
+          return all.some(predicate);
+        },
+      }),
+    };
+    const constraintViolations = await runConstraintGuards(_data, _context.operation, _actor, __guardCtx);
+    for (const v of constraintViolations) errors.push(v.message);` : "";
   return `
   /**
-   * Validate ${modelName} data \u2014 runs before create / update / evolve.
+   * Validate ${modelName} data \u2014 runs before create / update / evolve / delete.
    */
-  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)}
+${generateValidationLogic(model)}${constraintsCheck}
     return { valid: errors.length === 0, errors };
   }
 `;
@@ -101,13 +118,23 @@ function generateValidationLogic(model) {
   });
   return out.join("\n") || "    // No validation rules defined";
 }
-function generateCreateMethod(modelName, modelVar) {
+function generateCreateMethod(model, modelName, modelVar, hasConstraints = false) {
+  const belongsToLoad = hasConstraints ? generatePgBelongsToLoad(model) : "";
+  const validateSelf = belongsToLoad ? "__mergedSelf" : "data";
   return `
   /**
    * Create a new ${modelName}.
    */
-  public async create(data: any): Promise<any> {
-    const validation = this.validate(data, { operation: 'create' });
+  public async create(data: any, _actor: any = null): Promise<any> {
+${belongsToLoad ? `
+    // Phase 2 Slice 15 \u2014 Create-time relation loading. Mirrors prisma's
+    // pattern: for each belongsTo FK in input, load the related row and
+    // merge into self for constraint guards.
+    const __loadedRels: Record<string, any> = {};
+    ${belongsToLoad}
+    const __mergedSelf = { ...data, ...__loadedRels };
+` : ""}
+    const validation = await this.validate(${validateSelf}, { operation: 'create' }, _actor);
     if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
 
     const ${modelVar} = await insertOne(TABLE_NAME, { ...data });
@@ -117,6 +144,19 @@ function generateCreateMethod(modelName, modelVar) {
   }
 `;
 }
+function generatePgBelongsToLoad(model) {
+  const rels = Array.isArray(model.relationships) ? model.relationships : Object.values(model.relationships || {});
+  const belongsToRels = rels.filter((r) => r.type === "belongsTo");
+  if (belongsToRels.length === 0) return "";
+  return belongsToRels.map((rel) => {
+    const relName = rel.name;
+    const targetName = rel.target;
+    const fkField = `${relName}Id`;
+    return `if (data.${fkField}) {
+      __loadedRels.${relName} = await findOneByField('${targetName}', 'id', data.${fkField});
+    }`;
+  }).join("\n    ");
+}
 function generateRetrieveMethod(modelName, _modelVar) {
   return `
   /**
@@ -140,13 +180,22 @@ function generateRetrieveMethod(modelName, _modelVar) {
   }
 `;
 }
-function generateUpdateMethod(modelName, modelVar) {
+function generateUpdateMethod(modelName, modelVar, hasConstraints = false) {
   return `
   /**
    * Update ${modelName}.
    */
-  public async update(id: string, data: any): Promise<any> {
-    const validation = this.validate(data, { operation: 'update' });
+  public async update(id: string, data: any, _actor: any = null): Promise<any> {
+${hasConstraints ? `
+    // Phase 2 \u2014 Update self-from-DB. Load + merge before validate so
+    // update-time constraints see the full entity, not just partial input.
+    const __existing = await findOneByField(TABLE_NAME, 'id', id);
+    if (!__existing) throw new Error('${modelName} not found');
+    const __merged = { ...__existing, ...data };
+    const validation = await this.validate(__merged, { operation: 'update' }, _actor);
+` : `
+    const validation = await this.validate(data, { operation: 'update' }, _actor);
+`}
     if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
 
     // Strip nested objects + id \u2014 only scalar fields are written.
@@ -167,7 +216,7 @@ function generateUpdateMethod(modelName, modelVar) {
   }
 `;
 }
-function generateEvolveMethod(model, modelName, modelVar) {
+function generateEvolveMethod(model, modelName, modelVar, hasConstraints = false) {
   const lifecycles = Array.isArray(model.lifecycles) ? model.lifecycles : model.lifecycles ? Object.entries(model.lifecycles).map(([name, lc]) => ({ name, ...lc })) : [];
   const lifecycle = lifecycles[0];
   const lifecycleName = lifecycle?.name || "status";
@@ -176,12 +225,23 @@ function generateEvolveMethod(model, modelName, modelVar) {
     ...Object.keys(validTransitions),
     ...Object.values(validTransitions).flat()
   ]));
+  const evolveOpsMap = {};
+  if (lifecycle?.transitions) {
+    for (const [actionName, t] of Object.entries(lifecycle.transitions)) {
+      const from = t.from;
+      const to = t.to;
+      if (typeof from === "string" && typeof to === "string") {
+        evolveOpsMap[from] = evolveOpsMap[from] ?? {};
+        evolveOpsMap[from][to] = actionName;
+      }
+    }
+  }
   return `
   /**
    * Evolve ${modelName} through lifecycle "${lifecycleName}"
    * States: ${states.join(" \u2192 ") || "(none declared)"}
    */
-  public async evolve(id: string, data: any): Promise<any> {
+  public async evolve(id: string, data: any, _actor: any = null): Promise<any> {
     const current = await findOneByField(TABLE_NAME, 'id', id);
     if (!current) throw new Error('${modelName} not found');
 
@@ -197,7 +257,20 @@ function generateEvolveMethod(model, modelName, modelVar) {
       throw new Error(\`Invalid transition: \${currentState} \u2192 \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
     }
     ` : ""}
-
+${hasConstraints ? `
+    // Phase 2 \u2014 resolve transition action name + call validate with evolve.<action>.
+    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(', ')}\`);
+    }
+` : ""}
     await updateOneById(TABLE_NAME, id, { [targetLifecycle]: targetState });
     const ${modelVar} = await findOneByField(TABLE_NAME, 'id', id);
     if (!${modelVar}) throw new Error('${modelName} not found after evolve');
@@ -207,13 +280,22 @@ function generateEvolveMethod(model, modelName, modelVar) {
   }
 `;
 }
-function generateDeleteMethod(modelName, modelVar) {
+function generateDeleteMethod(modelName, modelVar, hasConstraints = false) {
   return `
   /**
    * Delete ${modelName}.
    */
-  public async delete(id: string): Promise<void> {
+  public async delete(id: string, _actor: any = null): Promise<void> {
     const ${modelVar} = await findOneByField(TABLE_NAME, 'id', id);
+${hasConstraints ? `
+    // Phase 2 \u2014 run delete-scoped constraint guards against the loaded record.
+    if (${modelVar}) {
+      const deleteValidation = await this.validate(${modelVar}, { operation: 'delete' }, _actor);
+      if (!deleteValidation.valid) {
+        throw new Error(\`Validation failed: \${deleteValidation.errors.join(', ')}\`);
+      }
+    }
+` : ""}
     await deleteOneById(TABLE_NAME, id);
     if (${modelVar}) {
       await eventBus.publish('${modelName}Deleted', { ...${modelVar}, timestamp: new Date().toISOString() } as any);