@specverse/engines 6.5.3 → 6.6.3

package/dist/analyse-prepass/adapters/typescript-decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typescript-decorators.d.ts","sourceRoot":"","sources":["../../../src/analyse-prepass/adapters/typescript-decorators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,SAAS,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,GAAG,SAAS,CAAC;IAC/E,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpG,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,CAAC;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,mDAAmD;IACnD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,cAAc,CAAC,CAoCzB"}
+{"version":3,"file":"typescript-decorators.d.ts","sourceRoot":"","sources":["../../../src/analyse-prepass/adapters/typescript-decorators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,SAAS,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,GAAG,SAAS,CAAC;IAC/E,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpG,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,CAAC;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,mDAAmD;IACnD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,cAAc,CAAC,CA0CzB"}

package/dist/analyse-prepass/adapters/typescript-decorators.js

@@ -17,13 +17,19 @@ export async function extractTypeScriptDecorators(prepass) {
         catch {
             continue;
         }
-        const classBody = sliceClass(body, cls.startLine, cls.endLine);
-        if (!classBody)
+        const slice = sliceClass(body, cls.startLine, cls.endLine);
+        if (!slice)
             continue;
-        const framework = detectFramework(classBody);
+        // Detect framework from the class-level decorator block (immediately above
+        // `class X {`). Walking the decorator block specifically — rather than the
+        // first ~600 chars of an arbitrary lookback — handles long import blocks
+        // and multi-line decorator arguments (twenty: 9-16 lines of class-level
+        // decorators between @Entity and the class declaration).
+        const framework = detectFramework(slice.decorators);
         if (framework === 'not-an-entity')
             continue;
         seenFrameworks.add(framework);
+        const classBody = slice.body;
         const attributes = extractAttributes(classBody);
         facts.entities.push({
             name: cls.name,
@@ -45,22 +51,25 @@ export async function extractTypeScriptDecorators(prepass) {
 // Detection + extraction helpers
 // ─────────────────────────────────────────────────────────────────────
 /**
- * Look at the class header (and a few lines before the class declaration
- * for class-level decorators) to decide whether it's an entity and which
- * framework it uses. Returns `not-an-entity` to signal "skip this class".
+ * Decide whether the class is an entity and which framework it uses, given
+ * the class-level decorator block (collected by `sliceClass`). The block is
+ * already trimmed to just `@...` decorators + their multi-line arguments +
+ * the `extends` clause from the class declaration, so framework probes can
+ * scan it directly without char-count guards.
+ *
+ * Returns `not-an-entity` to signal "skip this class".
  */
-function detectFramework(classBody) {
-    const head = classBody.slice(0, 600); // first ~10 lines is usually enough
-    // Sequelize: @Table or `extends Model`
-    if (/@Table\s*\(/.test(head))
+function detectFramework(decoratorBlock) {
+    // Sequelize: @Table or `extends Model` (Model can appear on the class line)
+    if (/@Table\s*\(/.test(decoratorBlock))
         return 'sequelize';
-    if (/\bextends\s+Model\b/.test(head))
+    if (/\bextends\s+Model\b/.test(decoratorBlock))
         return 'sequelize';
     // TypeORM / NestJS: @Entity
-    if (/@Entity\s*[\s(]/.test(head))
+    if (/@Entity\s*[\s(]/.test(decoratorBlock))
         return 'typeorm';
     // Mongoose with NestJS: @Schema
-    if (/@Schema\s*[\s(]/.test(head))
+    if (/@Schema\s*[\s(]/.test(decoratorBlock))
         return 'mongoose';
     // JPA (Java) — same @Entity but in a Java file. We err on the side of typeorm
     // because we're only called on TypeScript codebases right now.
@@ -140,11 +149,29 @@ function extractRelationships(body, fromName) {
     return out;
 }
 /**
- * Slice the class body from a file's full text using gitnexus's startLine /
- * endLine. Includes up to 8 lines BEFORE startLine to capture class-level
- * decorators (TypeORM's `@Entity()` typically sits 1-2 lines above
- * `export class X`; Sequelize's `@Table()` similarly). Without this padding,
- * the framework detector misses class-level decorators entirely.
+ * Slice a class into two pieces: the class-level decorator block (immediately
+ * above `class X {`) and the class body (from `class X {` through endLine).
+ *
+ * The decorator block is built by walking UPWARD from the class line and
+ * collecting every line that is either:
+ *   - blank,
+ *   - starts with `@` (a decorator), or
+ *   - is a continuation of an unclosed parenthesised decorator argument.
+ *
+ * It also includes the class-declaration line itself (so `extends Model` is
+ * visible to framework detection). The walk stops at the first
+ * non-decorator-non-blank line (typically an `import`, `}`, or comment).
+ *
+ * This handles real-world shapes that the previous fixed-line lookback
+ * missed — e.g. twenty's class-level decorator stacks like:
+ *   @Entity({ name: 'view', schema: 'core' })
+ *   @Index(...)
+ *   @Unique('IDX_...', [...])
+ *   @Index(...)
+ *   ...
+ *   export class ViewEntity { ... }
+ * which can run 9-16 lines before the class declaration, well past any
+ * fixed lookback or char-count slice.
  *
  * Returns null if line numbers are missing or out of range.
  */
@@ -152,7 +179,42 @@ function sliceClass(fileText, startLine, endLine) {
     if (!startLine || !endLine || endLine <= startLine)
         return null;
     const lines = fileText.split('\n');
-    const sliceStart = Math.max(0, startLine - 1 - 8); // 8-line lookback for class-level decorators
-    return lines.slice(sliceStart, Math.min(lines.length, endLine + 1)).join('\n');
+    if (startLine - 1 >= lines.length)
+        return null;
+    const classLineIdx = startLine - 1;
+    const decoratorLines = [];
+    // Walk UP from class line, tracking paren balance contributed by lines we visit.
+    // Going backward, ')' tokens INCREASE depth (unclosed-from-above) and '(' tokens
+    // DECREASE depth. While depth > 0 we're inside a multi-line decorator argument.
+    let parenDepth = 0;
+    for (let i = classLineIdx - 1; i >= 0 && i >= classLineIdx - 60; i--) {
+        const line = lines[i];
+        const opens = (line.match(/\(/g) || []).length;
+        const closes = (line.match(/\)/g) || []).length;
+        parenDepth += closes - opens;
+        if (line.trim() === '') {
+            decoratorLines.unshift(line);
+            // blank lines OK as long as we haven't seen a decorator yet, OR we're inside parens
+            if (decoratorLines.some((l) => l.trim().startsWith('@')) || parenDepth > 0)
+                continue;
+            // a leading blank line (no decorators yet) is benign — keep walking
+            continue;
+        }
+        if (parenDepth > 0) {
+            decoratorLines.unshift(line);
+            continue;
+        }
+        if (line.trim().startsWith('@')) {
+            decoratorLines.unshift(line);
+            continue;
+        }
+        // Hit a non-decorator, non-continuation, non-blank line — stop.
+        break;
+    }
+    // Include the class declaration line (covers `extends Model`).
+    decoratorLines.push(lines[classLineIdx]);
+    const decorators = decoratorLines.join('\n');
+    const body = lines.slice(classLineIdx, Math.min(lines.length, endLine + 1)).join('\n');
+    return { decorators, body };
 }
 //# sourceMappingURL=typescript-decorators.js.map

package/dist/analyse-prepass/adapters/typescript-decorators.js.map

@@ -1 +1 @@
-{"version":3,"file":"typescript-decorators.js","sourceRoot":"","sources":["../../../src/analyse-prepass/adapters/typescript-decorators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"typescript-decorators.js","sourceRoot":"","sources":["../../../src/analyse-prepass/adapters/typescript-decorators.ts"],"names":[],"mappings":"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"}

package/dist/libs/instance-factories/services/mongodb-native-services.yaml

@@ -0,0 +1,84 @@
+name: MongoDBNativeDriver
+version: "1.0.0"
+category: service
+description: "Business logic services using the native MongoDB driver for collection access (no ORM layer)"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [services, business-logic, mongodb, native-driver, controllers]
+
+compatibility:
+  specverse: ">=5.0.0"
+  node: ">=18.0.0"
+
+# With the MongoDB native driver, collection access IS the data layer — there
+# is no ORM layer to swap in independently. So this single factory provides
+# both the "orm.client" capability AND the service-layer capabilities.
+capabilities:
+  provides:
+    - "orm.schema"     # Emits the MongoDB client connector (the client IS the schema layer)
+    - "orm.client"
+    - "orm.mongodb.native"
+    - "service.controller"
+    - "service.business"
+    - "service.crud"
+  requires:
+    - "storage.database.document"
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  orm: "mongodb-native"
+  version: "^6.0.0"
+
+dependencies:
+  runtime:
+    - name: "mongodb"
+      version: "^6.3.0"
+
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  # `schema` is the orm.schema-capability slot the realize engine drives for
+  # ORM-side artifacts. With Prisma this emits `schema.prisma`; with the
+  # MongoDB native driver there is no separate db-schema artifact, so this
+  # slot emits the singleton client connector instead — same intent
+  # ("how does the app reach the data layer"), different physical output.
+  schema:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/mongodb-native/client-generator.ts"
+    outputPattern: "{backendDir}/src/db/mongoClient.ts"
+
+  controllers:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/mongodb-native/controller-generator.ts"
+    outputPattern: "{backendDir}/src/controllers/{model}Controller.ts"
+
+  services:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/mongodb-native/service-generator.ts"
+    outputPattern: "{backendDir}/src/services/{service}.ts"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"
+  collectionNaming: "lowercase-pluralized"  # User → users, OrderItem → orderitems
+  validation: true
+  eventPublishing: true
+  errorHandling: "throw"
+
+requirements:
+  dependencies:
+    npm:
+      dependencies:
+        "mongodb": "^6.3.0"
+  environment:
+    - name: "MONGODB_URI"
+      description: "MongoDB connection string (e.g. mongodb://localhost:27017/myapp)"
+      required: true
+  configuration: {}

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

@@ -0,0 +1,43 @@
+function generateMongoClient(_context) {
+  return `/**
+ * MongoDB native driver \u2014 singleton client + helpers.
+ *
+ * Picks up MONGODB_URI / MONGODB_DB from the environment. The client is
+ * lazily initialised on first use and reused across requests; \`disconnect\`
+ * is exposed for graceful-shutdown wiring.
+ */
+import { MongoClient, type Db, type Collection, type Document } from 'mongodb';
+
+const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017';
+const dbName = process.env.MONGODB_DB || 'specverse';
+
+let client: MongoClient | null = null;
+let database: Db | null = null;
+
+export async function getDb(): Promise<Db> {
+  if (database) return database;
+  client = new MongoClient(uri);
+  await client.connect();
+  database = client.db(dbName);
+  return database;
+}
+
+export async function getCollection<T extends Document = Document>(
+  name: string,
+): Promise<Collection<T>> {
+  const db = await getDb();
+  return db.collection<T>(name);
+}
+
+export async function disconnect(): Promise<void> {
+  if (client) {
+    await client.close();
+    client = null;
+    database = null;
+  }
+}
+`;
+}
+export {
+  generateMongoClient as default
+};

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

@@ -0,0 +1,259 @@
+import { buildTransitionMap, isAutoField } from "@specverse/types/spec-rules";
+function generateMongoNativeController(context) {
+  const { controller, model } = context;
+  if (!controller) throw new Error("Controller is required in template context");
+  if (!model) throw new Error("Model is required for controller generation");
+  const controllerName = controller.name;
+  const modelName = model.name;
+  const modelVar = lowerFirst(modelName);
+  const collection = collectionName(model);
+  const curedOps = controller.cured || {};
+  const customActions = generateCustomActions(controller, modelName);
+  const validate = generateValidateMethod(model, modelName);
+  const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection) : "";
+  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 hasEventPublishing = curedOps.create || curedOps.update || curedOps.evolve || curedOps.delete;
+  return `/**
+ * ${controllerName}
+ * Model-specific business logic for ${modelName} (MongoDB native driver)
+ * ${controller.description || ""}
+ */
+import { ObjectId, type Filter, type Document } from 'mongodb';
+import { getCollection } from '../db/mongoClient.js';
+${hasEventPublishing ? `import { eventBus } from '../events/eventBus.js';` : ""}
+${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : ""}
+
+const COLLECTION_NAME = '${collection}';
+
+/** Parse an id string to the value the collection expects: ObjectId for
+ * 24-hex-character ids, otherwise pass-through (UUIDs, slugs, ints-as-string). */
+function parseId(id: string): ObjectId | string {
+  if (typeof id === 'string' && /^[a-fA-F0-9]{24}$/.test(id)) return new ObjectId(id);
+  return id;
+}
+
+/** _id-aware filter builder. */
+function byId(id: string): Filter<Document> {
+  return { _id: parseId(id) as any };
+}
+
+export class ${controllerName} {
+${validate}
+${create}
+${retrieve}
+${update}
+${evolve}
+${del}
+${customActions.code}
+}
+
+export const ${modelVar}Controller = new ${controllerName}();
+export default ${modelVar}Controller;
+`;
+}
+function lowerFirst(s) {
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+function collectionName(model) {
+  if (model?.storage?.collection) return String(model.storage.collection);
+  return model.name.toLowerCase() + "s";
+}
+function generateValidateMethod(model, modelName) {
+  return `
+  /**
+   * Validate ${modelName} data \u2014 runs before create / update / evolve.
+   */
+  public validate(
+    _data: any,
+    _context: { operation: 'create' | 'update' | 'evolve' }
+  ): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+${generateValidationLogic(model)}
+    return { valid: errors.length === 0, errors };
+  }
+`;
+}
+function generateValidationLogic(model) {
+  if (!model.attributes) return "    // No validation rules defined";
+  const attrList = Array.isArray(model.attributes) ? model.attributes.map((a) => [a.name, a]) : Object.entries(model.attributes);
+  const out = [];
+  attrList.forEach(([name, attr]) => {
+    if (attr.required && !isAutoField(name, attr)) {
+      out.push(`    if (_context.operation === 'create' && !_data.${name}) errors.push('${name} is required');`);
+    }
+    if (attr.type === "String" || attr.type === "string") {
+      if (attr.min) out.push(`    if (_data.${name} && _data.${name}.length < ${attr.min}) errors.push('${name} must be at least ${attr.min} characters');`);
+      if (attr.max) out.push(`    if (_data.${name} && _data.${name}.length > ${attr.max}) errors.push('${name} must be at most ${attr.max} characters');`);
+    }
+    if (attr.values && Array.isArray(attr.values)) {
+      const values = attr.values.map((v) => `'${v}'`).join(", ");
+      out.push(`    if (_data.${name} && ![${values}].includes(_data.${name})) errors.push('${name} must be one of: ${attr.values.join(", ")}');`);
+    }
+    if (attr.format === "email") {
+      out.push(`    if (_data.${name} && !/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(_data.${name})) errors.push('${name} must be a valid email address');`);
+    }
+  });
+  return out.join("\n") || "    // No validation rules defined";
+}
+function generateCreateMethod(model, modelName, modelVar, collection) {
+  return `
+  /**
+   * Create a new ${modelName}.
+   */
+  public async create(data: any): Promise<any> {
+    const validation = this.validate(data, { operation: 'create' });
+    if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
+
+    const collection = await getCollection('${collection}');
+    const result = await collection.insertOne({ ...data });
+    const ${modelVar} = { _id: result.insertedId, ...data };
+
+    await eventBus.publish('${modelName}Created', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+function generateRetrieveMethod(modelName, modelVar, collection) {
+  return `
+  /**
+   * Retrieve ${modelName} by id. Returns null when not found.
+   */
+  public async retrieve(id: string): Promise<any | null> {
+    const collection = await getCollection('${collection}');
+    return await collection.findOne(byId(id));
+  }
+
+  /**
+   * Retrieve a page of ${modelName}s.
+   */
+  public async retrieveAll(options: { skip?: number; take?: number } = {}): Promise<any[]> {
+    const collection = await getCollection('${collection}');
+    const cursor = collection.find({});
+    if (options.skip) cursor.skip(options.skip);
+    if (options.take) cursor.limit(options.take);
+    return await cursor.toArray();
+  }
+`;
+}
+function generateUpdateMethod(modelName, modelVar, collection) {
+  return `
+  /**
+   * Update ${modelName}.
+   */
+  public async update(id: string, data: any): Promise<any> {
+    const validation = this.validate(data, { operation: 'update' });
+    if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
+
+    // Strip nested objects + id \u2014 only scalar fields are written.
+    const updateData: any = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (key === 'id' || key === '_id') continue;
+      if (Array.isArray(value)) continue;
+      if (value !== null && typeof value === 'object' && !(value instanceof Date)) continue;
+      updateData[key] = value;
+    }
+
+    const collection = await getCollection('${collection}');
+    await collection.updateOne(byId(id), { $set: updateData });
+    const ${modelVar} = await collection.findOne(byId(id));
+    if (!${modelVar}) throw new Error('${modelName} not found after update');
+
+    await eventBus.publish('${modelName}Updated', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+function generateEvolveMethod(model, modelName, modelVar, collection) {
+  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";
+  const validTransitions = lifecycle ? buildTransitionMap(lifecycle) : {};
+  const states = lifecycle?.states && lifecycle.states.length > 0 ? lifecycle.states.map((s) => typeof s === "string" ? s : s.name) : Array.from(/* @__PURE__ */ new Set([
+    ...Object.keys(validTransitions),
+    ...Object.values(validTransitions).flat()
+  ]));
+  return `
+  /**
+   * Evolve ${modelName} through lifecycle "${lifecycleName}"
+   * States: ${states.join(" \u2192 ") || "(none declared)"}
+   */
+  public async evolve(id: string, data: any): Promise<any> {
+    const collection = await getCollection('${collection}');
+    const current = await collection.findOne(byId(id));
+    if (!current) throw new Error('${modelName} not found');
+
+    const targetLifecycle = data?.lifecycleName || '${lifecycleName}';
+    const targetState = data?.toState ?? data?.state ?? data?.[targetLifecycle];
+    if (!targetState) throw new Error('evolve requires toState (or ${lifecycleName}) in the request body');
+
+    ${states.length > 0 ? `
+    const currentState = (current as any)[targetLifecycle];
+    const validTransitions: Record<string, string[]> = ${JSON.stringify(validTransitions)};
+    const allowed = validTransitions[currentState] || [];
+    if (!allowed.includes(targetState)) {
+      throw new Error(\`Invalid transition: \${currentState} \u2192 \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
+    }
+    ` : ""}
+
+    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');
+
+    await eventBus.publish('${modelName}Evolved', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+function generateDeleteMethod(modelName, modelVar, collection) {
+  return `
+  /**
+   * Delete ${modelName}.
+   */
+  public async delete(id: string): Promise<void> {
+    const collection = await getCollection('${collection}');
+    const ${modelVar} = await collection.findOne(byId(id));
+    await collection.deleteOne(byId(id));
+    if (${modelVar}) {
+      await eventBus.publish('${modelName}Deleted', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    }
+  }
+`;
+}
+function generateCustomActions(controller, modelName) {
+  if (!controller.actions || Object.keys(controller.actions).length === 0) {
+    return { code: "", needsAiBehaviors: false };
+  }
+  const out = [];
+  for (const [actionName, action] of Object.entries(controller.actions)) {
+    const params = generateActionParams(action);
+    const stepsHeader = action.steps && action.steps.length > 0 ? action.steps.map((s) => `   *   - ${typeof s === "string" ? s : s.action || JSON.stringify(s)}`).join("\n") : "   *   (no spec steps declared)";
+    out.push(`
+  /**
+   * ${actionName}
+   * ${action.description || ""}
+   *
+   * Spec steps:
+${stepsHeader}
+   */
+  public async ${actionName}(${params}): Promise<any> {
+    return await aiBehaviors.${actionName}({ controller: this, ...args });
+  }
+`);
+  }
+  return { code: out.join("\n"), needsAiBehaviors: true };
+}
+function generateActionParams(action) {
+  if (Array.isArray(action.parameters) && action.parameters.length > 0) {
+    return "args: any";
+  }
+  if (action.parameters && typeof action.parameters === "object" && Object.keys(action.parameters).length > 0) {
+    return "args: any";
+  }
+  return "args: any = {}";
+}
+export {
+  generateMongoNativeController as default
+};

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

@@ -0,0 +1,64 @@
+function generateMongoNativeService(context) {
+  const { service } = context;
+  if (!service) throw new Error("Service is required in template context");
+  const serviceName = service.name;
+  const operationsCode = generateOperations(service);
+  const usesDb = /\bgetDb\b|\bgetCollection\b/.test(operationsCode);
+  const hasEvents = service.publishes && service.publishes.length > 0 || service.subscribes && service.subscribes.length > 0;
+  return `/**
+ * ${serviceName}
+ * Abstract business logic service (MongoDB native driver)
+ * ${service.description || ""}
+ */
+${usesDb ? `import { getDb, getCollection } from '../db/mongoClient.js';` : ""}
+${hasEvents ? `import { eventBus } from '../events/eventBus.js';` : ""}
+
+export class ${serviceName} {
+${operationsCode}
+}
+
+const ${lowerFirst(serviceName)} = new ${serviceName}();
+export const ${lowerFirst(serviceName)}Instance = ${lowerFirst(serviceName)};
+export default ${lowerFirst(serviceName)};
+`;
+}
+function lowerFirst(s) {
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+function generateOperations(service) {
+  const ops = service.operations;
+  if (!ops || Array.isArray(ops) && ops.length === 0 || !Array.isArray(ops) && Object.keys(ops).length === 0) {
+    return `
+  /**
+   * Default service entrypoint \u2014 replace with real operations once declared
+   * on the service's spec.
+   */
+  public async execute(_params: any = {}): Promise<any> {
+    throw new Error('${service.name}.execute is not implemented');
+  }
+`;
+  }
+  const entries = Array.isArray(ops) ? ops.map((op) => [op.name, op]) : Object.entries(ops);
+  return entries.map(([name, op]) => generateOperation(name, op, service.name)).join("\n");
+}
+function generateOperation(operationName, operation, serviceName) {
+  const stepsHeader = operation.steps && operation.steps.length > 0 ? operation.steps.map((s) => `   *   - ${typeof s === "string" ? s : s.action || JSON.stringify(s)}`).join("\n") : "   *   (no spec steps declared)";
+  return `
+  /**
+   * ${operationName}
+   * ${operation.description || ""}
+   *
+   * Spec steps:
+${stepsHeader}
+   */
+  public async ${operationName}(_args: any = {}): Promise<any> {
+    // TODO (#43 follow-up): translate spec steps into native MongoDB driver
+    // calls. For now this is a stub so realize completes and the service
+    // surface is callable for parity tests.
+    throw new Error('${serviceName}.${operationName} is not implemented');
+  }
+`;
+}
+export {
+  generateMongoNativeService as default
+};

package/dist/realize/library/library.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../../../src/realize/library/library.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../../../src/realize/library/library.ts"],"names":[],"mappings":"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"}

package/dist/realize/library/library.js

@@ -48,6 +48,17 @@ export class InstanceFactoryLibrary {
         // Sort by priority (highest first)
         const sortedSources = [...sources].sort((a, b) => (b.priority || 0) - (a.priority || 0));
         const result = await loadFromMultipleSources(sortedSources.map(s => ({ path: s.path })), { validate: true, ignoreInvalid: true });
+        // Surface validation errors as warnings so a malformed factory doesn't
+        // disappear without a trace. ignoreInvalid: true means we keep loading
+        // the other factories — but the user still needs to see WHY one was
+        // dropped (otherwise the symptom is a confusing "Unknown factory X" at
+        // the manifest stage with no hint that the yaml was rejected upstream).
+        if (result.errors && result.errors.length > 0) {
+            for (const err of result.errors) {
+                const lines = (err.errors || []).map(e => `    - ${e}`).join('\n');
+                console.warn(`⚠️  Skipped instance factory ${err.filePath}\n${lines}`);
+            }
+        }
         // Add to library
         for (const loadResult of result.types) {
             const name = loadResult.type.name;