@specverse/engines 6.0.7 → 6.0.9

package/dist/analyse-prepass/interface.d.ts

@@ -0,0 +1,222 @@
+/**
+ * StructuralPrepass — pluggable backend interface for analyse pre-pass.
+ *
+ * The pre-pass extracts deterministic structural facts from a source codebase
+ * (entities / relationships / lifecycle state literals / etc.) BEFORE the LLM
+ * sees it, so the LLM can focus on semantic interpretation rather than
+ * structural discovery.
+ *
+ * Backends: grep-only (zero deps, fallback for tests/CI), codegraph
+ * (recommended default), gitnexus (alternative for multi-component cases
+ * where Leiden community detection adds value).
+ *
+ * Adapters: per-framework translators (typescript-prisma first, then
+ * typescript-typeorm / python-sqlalchemy / go-gorm / etc.) that consume
+ * this interface and produce SpecVerse-vocabulary facts.
+ *
+ * Design rationale: see specverse-self/docs/proposals/STRUCTURAL-PREPASS-FOR-ANALYSE.md
+ */
+/** A symbol detected by tree-sitter (or grep heuristics) — class / function / method / etc. */
+export interface Symbol {
+    kind: 'class' | 'function' | 'method' | 'interface' | 'type_alias' | 'constant' | 'enum';
+    name: string;
+    /** Fully-qualified name where applicable (e.g. "PollController.evolve"). */
+    qualifiedName: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    /** Function/method signature, e.g. "(id: string, data: any): Promise<any>" */
+    signature?: string;
+    /** Leading docstring or JSDoc, if present */
+    docstring?: string;
+    /** Whether the symbol is exported from its module */
+    isExported?: boolean;
+    /** Decorators on the symbol (TypeScript / Python / Java) */
+    decorators?: string[];
+    /** Source-level language (typescript, javascript, python, go, ...) */
+    language: string;
+}
+/** An import edge — file imports symbols from target module. */
+export interface Import {
+    fromFile: string;
+    toModule: string;
+    symbols: string[];
+}
+/** Capability flags — adapters check before using optional methods. */
+export interface Capabilities {
+    /** Backend can resolve callers/callees of a symbol via call graph. */
+    callGraph: boolean;
+    /** Backend resolves cross-file references (vs single-file regex). */
+    crossFileResolution: boolean;
+    /** Backend has community-detection clustering (e.g. Leiden in GitNexus). */
+    componentClustering: boolean;
+    /** Backend supports full-text search across source. */
+    fullTextSearch: boolean;
+    /** Backend automatically syncs as files change (e.g. CodeGraph file watchers). */
+    fileWatching: boolean;
+}
+export interface FileFilter {
+    dir?: string;
+    lang?: string;
+    glob?: string;
+}
+export interface ClassFilter {
+    dir?: string;
+    namePattern?: RegExp;
+}
+export interface MethodFilter {
+    /** Class qualified-name (e.g. "OrderProcessorController") */
+    class?: string;
+    /** Names to filter to — e.g. ['evolve', 'create', 'validate'] */
+    nameIn?: string[];
+}
+export interface InterfaceFilter {
+    dir?: string;
+    namePattern?: RegExp;
+}
+export interface IndexResult {
+    files: number;
+    symbols: number;
+    durationMs: number;
+}
+/**
+ * Per-method fact sheet for behavior extraction.
+ *
+ * The structural pre-pass surfaces these facts from a method's body via
+ * tree-sitter call graph (where available) + regex heuristics for common
+ * patterns (event emission, DB writes, throws, async boundaries). The
+ * SpecVerse adapter layer (and downstream behavior-extraction prompt)
+ * consumes these to translate procedural code into spec-vocabulary
+ * `behaviors:` blocks with `steps:` decomposition.
+ *
+ * Design rationale: see specverse-self/docs/proposals/BEHAVIOR-EXTRACTION-FOR-ANALYSE.md
+ * — per-method fact sheets shrink the LLM's job from "summarize 200 lines
+ * of code" to "given this structured fact sheet, write a SpecVerse behavior
+ * block". Smaller cognitive load → smaller variance surface.
+ */
+export interface MethodFactSheet {
+    qualifiedName: string;
+    signature: string;
+    /** Raw source body (the function body — between { and }). */
+    body: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    language: string;
+    /**
+     * Methods/functions this one invokes (call graph).
+     * From CodeGraph: SQL on edges table (kind='call').
+     * From grep-only: regex for `(\w+)\(` calls within the body.
+     */
+    calls: Symbol[];
+    /**
+     * Event names emitted from this method's body.
+     * Patterns matched: emit() / dispatchEvent() / .next() (RxJS) /
+     * eventBus.publish() / pubsub.publish() / send() with first-arg literal.
+     */
+    emits: string[];
+    /**
+     * Persisted-state writes detected in the body (per ORM heuristic).
+     * Prisma: prisma.X.create() / .update() / .delete() / .upsert().
+     * TypeORM: repository.save() / .update() / .remove().
+     * SQLAlchemy: session.add() / .delete() / commit-tracked mutations.
+     * For arbitrary code, populated only when the adapter knows the ORM.
+     */
+    dbWrites: Array<{
+        entity: string;
+        field?: string;
+        op: 'create' | 'update' | 'delete' | 'upsert' | 'unknown';
+    }>;
+    /**
+     * External system calls detected in the body.
+     * Patterns: fetch() / axios.X() / http.request() (HTTP),
+     * kafka.send() / rabbit.publish() (queue), redis.set() / cache.set() (cache).
+     */
+    externalCalls: Array<{
+        kind: 'http' | 'queue' | 'cache' | 'unknown';
+        target?: string;
+    }>;
+    /**
+     * Explicit throw statements with their error type. `throw new BadRequestError(...)`
+     * → `BadRequestError`. Useful for inferring preconditions / error states.
+     */
+    throws: string[];
+    /**
+     * Async boundaries — locations where the method awaits, runs in parallel,
+     * or races. Useful for distinguishing sequential from parallel steps.
+     */
+    asyncBoundaries: Array<{
+        type: 'await' | 'promise.all' | 'promise.race' | 'promise.allSettled';
+        line: number;
+    }>;
+    /**
+     * Cyclomatic complexity proxy: count of branch points (if/else/switch/catch/ternary).
+     * High values suggest the LLM should look for branching steps in spec.
+     */
+    branchPoints: number;
+    /**
+     * For SpecVerse-realized backends: the body has comment-delineated regions
+     * (PRECONDITIONS / EXECUTE / POSTCONDITIONS / EVENTS). When detected, the
+     * regions are sliced out for the verify-behavior pass to cross-check spec
+     * preconditions/postconditions/events against source-side markers.
+     *
+     * For arbitrary backends, all fields here are undefined.
+     */
+    bodyTextSliced?: {
+        preconditions?: string;
+        execute?: string;
+        postconditions?: string;
+        events?: string;
+    };
+}
+/**
+ * Pluggable backend for structural extraction. Implementations:
+ *   - backends/grep-only.ts   — no external tools, regex per language
+ *   - backends/codegraph.ts   — tree-sitter via CodeGraph CLI + SQLite
+ *   - backends/gitnexus.ts    — tree-sitter via GitNexus MCP + LadybugDB
+ */
+export interface StructuralPrepass {
+    /** Initialize the backend on a source directory. */
+    init(sourceDir: string): Promise<void>;
+    /** Build / refresh the index. Returns stats. May be a no-op on grep-only. */
+    index(): Promise<IndexResult>;
+    /** List files in scope, optionally filtered. */
+    listFiles(filter?: FileFilter): Promise<string[]>;
+    /** List classes (or class-like declarations across languages). */
+    listClasses(filter?: ClassFilter): Promise<Symbol[]>;
+    /** List methods on classes. Class membership encoded in qualifiedName. */
+    listMethods(filter?: MethodFilter): Promise<Symbol[]>;
+    /** List interfaces / type-defs. */
+    listInterfaces(filter?: InterfaceFilter): Promise<Symbol[]>;
+    /** List imports for a single file. */
+    listImports(file: string): Promise<Import[]>;
+    /** Read raw source text. Adapters use this for regex extraction of literals. */
+    fileSourceText(file: string): Promise<string>;
+    /**
+     * Optional: callers/callees graph traversal.
+     * Throws if `capabilities.callGraph === false`.
+     */
+    callers?(symbol: string): Promise<Symbol[]>;
+    callees?(symbol: string): Promise<Symbol[]>;
+    /**
+     * Get the per-method fact sheet for a single method (by qualified name,
+     * e.g. "OrderProcessorController.processOrder"). Returns null if the
+     * method isn't found or isn't analyseable.
+     *
+     * All backends implement this — grep-only via regex over the method body,
+     * CodeGraph via SQL on the edges table for call data + regex for everything
+     * else (events, dbWrites, etc. aren't tree-sitter symbols, they're patterns).
+     */
+    getMethodDetails(qualifiedName: string): Promise<MethodFactSheet | null>;
+    /**
+     * Optional: cluster files into communities (Leiden / similar).
+     * Throws if `capabilities.componentClustering === false`.
+     */
+    clusterFiles?(): Promise<Array<{
+        id: string;
+        files: string[];
+    }>>;
+    /** Capability flags — adapters check before calling optional methods. */
+    capabilities: Capabilities;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/analyse-prepass/interface.d.ts.map

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

package/dist/analyse-prepass/interface.js

@@ -0,0 +1,20 @@
+/**
+ * StructuralPrepass — pluggable backend interface for analyse pre-pass.
+ *
+ * The pre-pass extracts deterministic structural facts from a source codebase
+ * (entities / relationships / lifecycle state literals / etc.) BEFORE the LLM
+ * sees it, so the LLM can focus on semantic interpretation rather than
+ * structural discovery.
+ *
+ * Backends: grep-only (zero deps, fallback for tests/CI), codegraph
+ * (recommended default), gitnexus (alternative for multi-component cases
+ * where Leiden community detection adds value).
+ *
+ * Adapters: per-framework translators (typescript-prisma first, then
+ * typescript-typeorm / python-sqlalchemy / go-gorm / etc.) that consume
+ * this interface and produce SpecVerse-vocabulary facts.
+ *
+ * Design rationale: see specverse-self/docs/proposals/STRUCTURAL-PREPASS-FOR-ANALYSE.md
+ */
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/analyse-prepass/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/analyse-prepass/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/libs/instance-factories/cli/templates/commander/command-generator.js

@@ -374,6 +374,110 @@ import type { ParserEngine, InferenceEngine, RealizeEngine } from '@specverse/ty
         }
         const inferredSpec = { ...componentData, componentName, components: inferredYaml?.components || {} };
 
+        // --estimate: report what realize WOULD do, broken down by layer.
+        // Skip the actual realizeAll call (no manifest needed, no LLM cost).
+        // The three layers:
+        //   L1 \u2014 Instance factory (templates, no LLM)
+        //   L2 \u2014 Convention pattern matching (CURVED ops + default events, no LLM)
+        //   L3 \u2014 AI from steps (one LLM call per declared step)
+        if (options.estimate) {
+          const components = inferredSpec.components || {};
+          const compNames = Object.keys(components);
+          let entityCount = 0, controllerCount = 0, serviceCount = 0, eventCount = 0, viewCount = 0;
+          let modelBehaviorSteps = 0, controllerActionSteps = 0, serviceOpSteps = 0;
+          let modelBehaviorsWithSteps = 0, controllerActionsWithSteps = 0, serviceOpsWithSteps = 0;
+          let curvedOpCount = 0;
+          const sumSteps = (block: any) => {
+            if (!block || typeof block !== 'object') return { ops: 0, opsWithSteps: 0, totalSteps: 0 };
+            let ops = 0, opsWithSteps = 0, totalSteps = 0;
+            for (const def of Object.values(block)) {
+              ops++;
+              const steps = (def as any)?.steps;
+              if (Array.isArray(steps) && steps.length > 0) {
+                opsWithSteps++;
+                totalSteps += steps.length;
+              }
+            }
+            return { ops, opsWithSteps, totalSteps };
+          };
+          for (const compName of compNames) {
+            const comp = components[compName] || {};
+            const models = comp.models || {};
+            const controllers = comp.controllers || {};
+            const services = comp.services || {};
+            const events = comp.events || {};
+            const views = comp.views || {};
+            entityCount += Object.keys(models).length;
+            controllerCount += Object.keys(controllers).length;
+            serviceCount += Object.keys(services).length;
+            eventCount += Object.keys(events).length;
+            viewCount += Object.keys(views).length;
+            for (const m of Object.values(models)) {
+              const r = sumSteps((m as any)?.behaviors);
+              modelBehaviorsWithSteps += r.opsWithSteps;
+              modelBehaviorSteps += r.totalSteps;
+            }
+            for (const c of Object.values(controllers)) {
+              const r = sumSteps((c as any)?.actions);
+              controllerActionsWithSteps += r.opsWithSteps;
+              controllerActionSteps += r.totalSteps;
+              const cured = (c as any)?.cured || (c as any)?.curved;
+              if (cured && typeof cured === 'object') curvedOpCount += Object.keys(cured).length;
+            }
+            for (const s of Object.values(services)) {
+              const r = sumSteps((s as any)?.operations);
+              serviceOpsWithSteps += r.opsWithSteps;
+              serviceOpSteps += r.totalSteps;
+            }
+          }
+          const totalLlmCalls = modelBehaviorSteps + controllerActionSteps + serviceOpSteps;
+          const fileEstimate = entityCount * 7 + controllerCount + serviceCount * 2 + viewCount + 15;
+          console.log('');
+          console.log('\u2554\u2550\u2550 spv realize --estimate \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550');
+          console.log('\u2551');
+          console.log('\u2551  Type: ' + type);
+          console.log('\u2551  Components: ' + compNames.length + (compNames.length > 0 ? ' (' + compNames.join(', ') + ')' : ''));
+          console.log('\u2551');
+          console.log('\u2551  \u2500\u2500 Spec inventory (post-inference) \u2500\u2500');
+          console.log('\u2551    Entities (models):    ' + entityCount);
+          console.log('\u2551    Controllers:          ' + controllerCount);
+          console.log('\u2551    Services:             ' + serviceCount);
+          console.log('\u2551    Events:               ' + eventCount);
+          console.log('\u2551    Views:                ' + viewCount);
+          console.log('\u2551');
+          console.log('\u2551  \u2500\u2500 Output by realize layer \u2500\u2500');
+          console.log('\u2551');
+          console.log('\u2551  L1 \u2014 Instance factory (file scaffolding, no LLM):');
+          console.log('\u2551    File scaffolding for each entity / controller / service / view');
+          console.log('\u2551    + framework boilerplate (Fastify routes, Prisma schema, React shell)');
+          console.log('\u2551    Estimate: ~' + fileEstimate + ' files');
+          console.log('\u2551');
+          console.log('\u2551  L2 \u2014 Convention pattern matching (bodies, no LLM):');
+          console.log('\u2551    CURVED ops auto-implemented:    ' + curvedOpCount);
+          console.log('\u2551    Default events on lifecycles:   ' + eventCount + ' (declared) + auto-derived');
+          console.log('\u2551    Default validation patterns:    ~' + (entityCount * 2));
+          console.log('\u2551');
+          console.log('\u2551  L3 \u2014 AI from steps (LLM, 1 call per step):');
+          console.log('\u2551    Model behaviors with steps:    ' + modelBehaviorsWithSteps + ' behaviors \u2192 ' + modelBehaviorSteps + ' steps');
+          console.log('\u2551    Controller actions with steps: ' + controllerActionsWithSteps + ' actions \u2192 ' + controllerActionSteps + ' steps');
+          console.log('\u2551    Service ops with steps:        ' + serviceOpsWithSteps + ' operations \u2192 ' + serviceOpSteps + ' steps');
+          console.log('\u2551    \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500');
+          console.log('\u2551    Total LLM calls:               ' + totalLlmCalls);
+          console.log('\u2551');
+          if (totalLlmCalls > 0) {
+            console.log('\u2551  \u2500\u2500 Estimated wall time + cost (L3 only) \u2500\u2500');
+            console.log('\u2551    On Opus 4.7 / Max:    ~' + Math.ceil(totalLlmCalls * 0.2) + ' min wall (free, claude-cli session-cached)');
+            console.log('\u2551    On Sonnet 4.6:        ~' + Math.ceil(totalLlmCalls * 0.1) + ' min wall (free)');
+            console.log('\u2551    On Anthropic API:     ~' + Math.ceil(totalLlmCalls * 0.1) + ' min wall, ~$' + (totalLlmCalls * 0.015).toFixed(2) + ' (Sonnet rates)');
+            console.log('\u2551    On DeepSeek/Together: ~' + Math.ceil(totalLlmCalls * 0.08) + ' min wall, ~$' + (totalLlmCalls * 0.0008).toFixed(3) + ' (10-30\xD7 cheaper)');
+          } else {
+            console.log('\u2551  No LLM cost \u2014 all output is L1 + L2 (templates + conventions only).');
+          }
+          console.log('\u2551');
+          console.log('\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550');
+          return;
+        }
+
         // Realize \u2014 let the realize engine handle its own library.
         // Locate the nearest implementation manifest by walking up from the
         // spec file, then falling back to the user's cwd. This lets the same

package/dist/libs/instance-factories/orms/templates/prisma/schema-generator.js

@@ -17,12 +17,24 @@ function generatePrismaSchema(context) {
     }
   }
   const header = generateHeader(implType);
+  const enumCollector = /* @__PURE__ */ new Map();
   const modelSchemas = allModels.map(
-    (model) => generateModelSchema(model, relationMap, backRefs, hasOneTargets, allModels)
+    (model) => generateModelSchema(model, relationMap, backRefs, hasOneTargets, allModels, enumCollector)
   ).join("\n\n");
+  let enumBlock = "";
+  if (enumCollector.size > 0) {
+    const enumDecls = [];
+    for (const [enumName, values] of enumCollector) {
+      const body = values.map((v) => `  ${v}`).join("\n");
+      enumDecls.push(`enum ${enumName} {
+${body}
+}`);
+    }
+    enumBlock = enumDecls.join("\n\n") + "\n\n";
+  }
   return `${header}
 
-${modelSchemas}`;
+${enumBlock}${modelSchemas}`;
 }
 function buildRelationMap(allModels) {
   const targetRefs = /* @__PURE__ */ new Map();
@@ -148,7 +160,7 @@ datasource db {
   url      = ${provider === "sqlite" ? '"file:./dev.db"' : 'env("DATABASE_URL")'}
 }`;
 }
-function generateModelSchema(model, relationMap, backRefs, hasOneTargets, allModels) {
+function generateModelSchema(model, relationMap, backRefs, hasOneTargets, allModels, enumCollector) {
   const modelName = model.name;
   let schema = `model ${modelName} {
 `;
@@ -158,6 +170,7 @@ function generateModelSchema(model, relationMap, backRefs, hasOneTargets, allMod
     schema += `  ${generateField(attr, model)}
 `;
   });
+  const ENUM_VALUE_REGEX = /^[a-zA-Z][a-zA-Z0-9_]*$/;
   const rawLifecycles = model.lifecycles || [];
   const lifecycleList = Array.isArray(rawLifecycles) ? rawLifecycles : Object.entries(rawLifecycles).map(([name, lc]) => ({ name, ...typeof lc === "object" ? lc : {} }));
   for (const lifecycle of lifecycleList) {
@@ -166,8 +179,16 @@ function generateModelSchema(model, relationMap, backRefs, hasOneTargets, allMod
     if (!exists && lifecycle.states?.length > 0) {
       const defaultState = lifecycle.states[0];
       const padding = " ".repeat(Math.max(1, 15 - fieldName.length));
-      schema += `  ${fieldName}${padding}String @default("${defaultState}")
+      const allValid = lifecycle.states.every((s) => ENUM_VALUE_REGEX.test(s));
+      if (allValid && enumCollector) {
+        const enumName = `${modelName}${fieldName.charAt(0).toUpperCase()}${fieldName.slice(1)}`;
+        enumCollector.set(enumName, lifecycle.states);
+        schema += `  ${fieldName}${padding}${enumName} @default(${defaultState})
 `;
+      } else {
+        schema += `  ${fieldName}${padding}String @default("${defaultState}")
+`;
+      }
     }
   }
   relationships.forEach((rel) => {

package/libs/instance-factories/cli/templates/commander/command-generator.ts

@@ -429,6 +429,110 @@ import type { ParserEngine, InferenceEngine, RealizeEngine } from '@specverse/ty
         }
         const inferredSpec = { ...componentData, componentName, components: inferredYaml?.components || {} };
 
+        // --estimate: report what realize WOULD do, broken down by layer.
+        // Skip the actual realizeAll call (no manifest needed, no LLM cost).
+        // The three layers:
+        //   L1 — Instance factory (templates, no LLM)
+        //   L2 — Convention pattern matching (CURVED ops + default events, no LLM)
+        //   L3 — AI from steps (one LLM call per declared step)
+        if (options.estimate) {
+          const components = inferredSpec.components || {};
+          const compNames = Object.keys(components);
+          let entityCount = 0, controllerCount = 0, serviceCount = 0, eventCount = 0, viewCount = 0;
+          let modelBehaviorSteps = 0, controllerActionSteps = 0, serviceOpSteps = 0;
+          let modelBehaviorsWithSteps = 0, controllerActionsWithSteps = 0, serviceOpsWithSteps = 0;
+          let curvedOpCount = 0;
+          const sumSteps = (block: any) => {
+            if (!block || typeof block !== 'object') return { ops: 0, opsWithSteps: 0, totalSteps: 0 };
+            let ops = 0, opsWithSteps = 0, totalSteps = 0;
+            for (const def of Object.values(block)) {
+              ops++;
+              const steps = (def as any)?.steps;
+              if (Array.isArray(steps) && steps.length > 0) {
+                opsWithSteps++;
+                totalSteps += steps.length;
+              }
+            }
+            return { ops, opsWithSteps, totalSteps };
+          };
+          for (const compName of compNames) {
+            const comp = components[compName] || {};
+            const models = comp.models || {};
+            const controllers = comp.controllers || {};
+            const services = comp.services || {};
+            const events = comp.events || {};
+            const views = comp.views || {};
+            entityCount += Object.keys(models).length;
+            controllerCount += Object.keys(controllers).length;
+            serviceCount += Object.keys(services).length;
+            eventCount += Object.keys(events).length;
+            viewCount += Object.keys(views).length;
+            for (const m of Object.values(models)) {
+              const r = sumSteps((m as any)?.behaviors);
+              modelBehaviorsWithSteps += r.opsWithSteps;
+              modelBehaviorSteps += r.totalSteps;
+            }
+            for (const c of Object.values(controllers)) {
+              const r = sumSteps((c as any)?.actions);
+              controllerActionsWithSteps += r.opsWithSteps;
+              controllerActionSteps += r.totalSteps;
+              const cured = (c as any)?.cured || (c as any)?.curved;
+              if (cured && typeof cured === 'object') curvedOpCount += Object.keys(cured).length;
+            }
+            for (const s of Object.values(services)) {
+              const r = sumSteps((s as any)?.operations);
+              serviceOpsWithSteps += r.opsWithSteps;
+              serviceOpSteps += r.totalSteps;
+            }
+          }
+          const totalLlmCalls = modelBehaviorSteps + controllerActionSteps + serviceOpSteps;
+          const fileEstimate = entityCount * 7 + controllerCount + serviceCount * 2 + viewCount + 15;
+          console.log('');
+          console.log('╔══ spv realize --estimate ══════════════════════════════════════════');
+          console.log('║');
+          console.log('║  Type: ' + type);
+          console.log('║  Components: ' + compNames.length + (compNames.length > 0 ? ' (' + compNames.join(', ') + ')' : ''));
+          console.log('║');
+          console.log('║  ── Spec inventory (post-inference) ──');
+          console.log('║    Entities (models):    ' + entityCount);
+          console.log('║    Controllers:          ' + controllerCount);
+          console.log('║    Services:             ' + serviceCount);
+          console.log('║    Events:               ' + eventCount);
+          console.log('║    Views:                ' + viewCount);
+          console.log('║');
+          console.log('║  ── Output by realize layer ──');
+          console.log('║');
+          console.log('║  L1 — Instance factory (file scaffolding, no LLM):');
+          console.log('║    File scaffolding for each entity / controller / service / view');
+          console.log('║    + framework boilerplate (Fastify routes, Prisma schema, React shell)');
+          console.log('║    Estimate: ~' + fileEstimate + ' files');
+          console.log('║');
+          console.log('║  L2 — Convention pattern matching (bodies, no LLM):');
+          console.log('║    CURVED ops auto-implemented:    ' + curvedOpCount);
+          console.log('║    Default events on lifecycles:   ' + eventCount + ' (declared) + auto-derived');
+          console.log('║    Default validation patterns:    ~' + (entityCount * 2));
+          console.log('║');
+          console.log('║  L3 — AI from steps (LLM, 1 call per step):');
+          console.log('║    Model behaviors with steps:    ' + modelBehaviorsWithSteps + ' behaviors → ' + modelBehaviorSteps + ' steps');
+          console.log('║    Controller actions with steps: ' + controllerActionsWithSteps + ' actions → ' + controllerActionSteps + ' steps');
+          console.log('║    Service ops with steps:        ' + serviceOpsWithSteps + ' operations → ' + serviceOpSteps + ' steps');
+          console.log('║    ────────────────────────────────────────────────────────');
+          console.log('║    Total LLM calls:               ' + totalLlmCalls);
+          console.log('║');
+          if (totalLlmCalls > 0) {
+            console.log('║  ── Estimated wall time + cost (L3 only) ──');
+            console.log('║    On Opus 4.7 / Max:    ~' + Math.ceil(totalLlmCalls * 0.2) + ' min wall (free, claude-cli session-cached)');
+            console.log('║    On Sonnet 4.6:        ~' + Math.ceil(totalLlmCalls * 0.1) + ' min wall (free)');
+            console.log('║    On Anthropic API:     ~' + Math.ceil(totalLlmCalls * 0.1) + ' min wall, ~$' + (totalLlmCalls * 0.015).toFixed(2) + ' (Sonnet rates)');
+            console.log('║    On DeepSeek/Together: ~' + Math.ceil(totalLlmCalls * 0.08) + ' min wall, ~$' + (totalLlmCalls * 0.0008).toFixed(3) + ' (10-30× cheaper)');
+          } else {
+            console.log('║  No LLM cost — all output is L1 + L2 (templates + conventions only).');
+          }
+          console.log('║');
+          console.log('╚════════════════════════════════════════════════════════════════════');
+          return;
+        }
+
         // Realize — let the realize engine handle its own library.
         // Locate the nearest implementation manifest by walking up from the
         // spec file, then falling back to the user's cwd. This lets the same

package/libs/instance-factories/orms/templates/prisma/schema-generator.ts

@@ -42,12 +42,28 @@ export default function generatePrismaSchema(context: TemplateContext): string {
   // Generate header
   const header = generateHeader(implType);
 
+  // Collector for Prisma enum declarations derived from model lifecycles.
+  // Generated as a side-effect of generateModelSchema and emitted at the
+  // top level (Prisma requires enums declared OUTSIDE model blocks).
+  const enumCollector = new Map<string, string[]>();
+
   // Generate models
   const modelSchemas = allModels.map((model: any) =>
-    generateModelSchema(model, relationMap, backRefs, hasOneTargets, allModels)
+    generateModelSchema(model, relationMap, backRefs, hasOneTargets, allModels, enumCollector)
   ).join('\n\n');
 
-  return `${header}\n\n${modelSchemas}`;
+  // Emit collected enums before models, so models can reference them.
+  let enumBlock = '';
+  if (enumCollector.size > 0) {
+    const enumDecls: string[] = [];
+    for (const [enumName, values] of enumCollector) {
+      const body = values.map((v) => `  ${v}`).join('\n');
+      enumDecls.push(`enum ${enumName} {\n${body}\n}`);
+    }
+    enumBlock = enumDecls.join('\n\n') + '\n\n';
+  }
+
+  return `${header}\n\n${enumBlock}${modelSchemas}`;
 }
 
 /**
@@ -285,7 +301,8 @@ function generateModelSchema(
   relationMap: Map<string, string | null>,
   backRefs: Map<string, string[]>,
   hasOneTargets: Set<string>,
-  allModels?: any[]
+  allModels?: any[],
+  enumCollector?: Map<string, string[]>,
 ): string {
   const modelName = model.name;
   let schema = `model ${modelName} {\n`;
@@ -305,7 +322,19 @@ function generateModelSchema(
     schema += `  ${generateField(attr, model)}\n`;
   });
 
-  // Add lifecycle status fields (if model has lifecycles)
+  // Add lifecycle status fields (if model has lifecycles).
+  //
+  // Each lifecycle's state literals become a Prisma `enum` declared at the
+  // schema's top level. The field's type is the enum, not a plain `String`.
+  // This preserves the state vocabulary in source so the realize→analyse
+  // round-trip oracle can recover lifecycle states (previously, only the
+  // default state survived — the others were silently dropped).
+  //
+  // Prisma enum value identifier rules: `^[a-zA-Z][a-zA-Z0-9_]*$`. SpecVerse
+  // states are already snake_case (enforced by the convention prompt) so they
+  // satisfy this without transformation. If a state somehow contains an
+  // illegal char, fall back to plain String so we don't emit an invalid schema.
+  const ENUM_VALUE_REGEX = /^[a-zA-Z][a-zA-Z0-9_]*$/;
   const rawLifecycles = model.lifecycles || [];
   const lifecycleList = Array.isArray(rawLifecycles)
     ? rawLifecycles
@@ -316,7 +345,16 @@ function generateModelSchema(
     if (!exists && lifecycle.states?.length > 0) {
       const defaultState = lifecycle.states[0];
       const padding = ' '.repeat(Math.max(1, 15 - fieldName.length));
-      schema += `  ${fieldName}${padding}String @default("${defaultState}")\n`;
+      const allValid = lifecycle.states.every((s: string) => ENUM_VALUE_REGEX.test(s));
+      if (allValid && enumCollector) {
+        const enumName = `${modelName}${fieldName.charAt(0).toUpperCase()}${fieldName.slice(1)}`;
+        enumCollector.set(enumName, lifecycle.states);
+        schema += `  ${fieldName}${padding}${enumName} @default(${defaultState})\n`;
+      } else {
+        // Fallback for invalid identifiers or when no collector — preserves the
+        // pre-fix behavior so downstream code never sees an undefined enum ref.
+        schema += `  ${fieldName}${padding}String @default("${defaultState}")\n`;
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "6.0.7",
+  "version": "6.0.9",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry, bundles",
   "type": "module",
   "main": "dist/index.js",
@@ -19,6 +19,10 @@
       "types": "./dist/inference/index.d.ts",
       "import": "./dist/inference/index.js"
     },
+    "./analyse-prepass": {
+      "types": "./dist/analyse-prepass/index.d.ts",
+      "import": "./dist/analyse-prepass/index.js"
+    },
     "./realize": {
       "types": "./dist/realize/index.d.ts",
       "import": "./dist/realize/index.js"

package/libs/instance-factories/cli/templates/commander/command-generator.d.ts

@@ -1,14 +0,0 @@
-/**
- * Command Generator
- *
- * Generates individual command files from command specifications.
- * Each command registers itself on a Commander program and wires
- * to its corresponding service for business logic delegation.
- */
-import type { TemplateContext } from '@specverse/types';
-/**
- * Generate a single command file.
- * Called once per command in the spec.
- */
-export default function generateCommand(context: TemplateContext): string;
-//# sourceMappingURL=command-generator.d.ts.map