@specverse/engines 4.2.0 → 4.2.1

package/dist/libs/instance-factories/tools/vscode.yaml

@@ -0,0 +1,35 @@
+name: VSCodeExtension
+version: "4.0.0"
+category: tools
+description: "VSCode extension with language support, commands, themes, and schema validation"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [vscode, ide, extension, language-support]
+
+compatibility:
+  specverse: "^4.0.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "tools.vscode"
+    - "tools.ide"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "vscode"
+
+dependencies:
+  runtime:
+    - name: "vscode"
+      version: "^1.85.0"
+
+codeTemplates:
+  vscode-extension:
+    engine: typescript
+    generator: "libs/instance-factories/tools/templates/vscode/vscode-extension-generator.ts"
+    outputPattern: "tools/vscode-extension/"

package/dist/libs/instance-factories/validation/README.md

@@ -0,0 +1,38 @@
+# Validation Instance Factory
+
+Generates Zod runtime validation schemas from SpecVerse model definitions, with optional JSON Schema output for Fastify integration.
+
+## Definition
+
+- **`zod.yaml`** -- Single definition (category: `service`, no external dependencies required).
+
+## Generator
+
+- `templates/zod/validation-generator.ts` -- Wraps `generate-validation.js`. Produces per-model validation files.
+
+## Capabilities
+
+| Capability | Description |
+|---|---|
+| `validation.runtime` | Zod schemas for runtime type checking |
+| `validation.zod` | Zod-specific schema generation |
+| `validation.jsonschema` | JSON Schema output (for Fastify route validation) |
+
+## Output Pattern
+
+```
+src/validation/{model}.validation.ts
+```
+
+Each file contains Zod schema definitions with inferred TypeScript types, plus optional JSON Schema equivalents.
+
+## Default Configuration
+
+- **Framework**: Zod 3.22+
+- **JSON Schema generation**: Enabled
+- **Strip unknown keys**: Enabled
+- **Abort early**: Disabled (collect all errors)
+
+## Status
+
+Wrapper implementation. Future TODO to split into dedicated generators for Zod schemas, JSON Schemas, and validation helper functions.

package/dist/libs/instance-factories/validation/zod.yaml

@@ -0,0 +1,56 @@
+name: ZodValidation
+version: "1.0.0"
+category: service
+description: "Zod schema generator for runtime validation with type inference"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [zod, validation, typescript, schema]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "validation.runtime"
+    - "validation.zod"
+    - "validation.jsonschema"
+  requires: []  # Fixed: removed incorrect api.rest dependency
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "zod"
+  validation: "zod"
+
+dependencies:
+  runtime:
+    - name: "zod"
+      version: "^3.22.0"
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  validation:
+    engine: typescript
+    generator: "libs/instance-factories/validation/templates/zod/validation-generator.ts"
+    outputPattern: "src/validation/{model}.validation.ts"
+
+configuration:
+  framework: "zod"
+  generateJsonSchema: true
+  stripUnknown: true
+  abortEarly: false
+
+# NOTE: This implementation type wraps the existing generate-validation.js script
+# TODO: Future enhancement - Convert generate-validation.js to native TypeScript template generator
+#       The current script generates Zod schemas, JSON schemas, and validation functions.
+#       Converting to native templates would require breaking it into multiple template files:
+#       - zod-schema-generator.ts (Zod schema definitions)
+#       - json-schema-generator.ts (JSON Schema for Fastify)
+#       - validation-function-generator.ts (validation helper functions)

package/dist/realize/engines/code-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-generator.d.ts","sourceRoot":"","sources":["../../../src/realize/engines/code-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,sBAAsB,EAAyB,MAAM,sBAAsB,CAAC;AACrF,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IAErB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,oDAAoD;IACpD,cAAc,CAAC,EAAE,sBAAsB,CAAC;IAExC,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,kCAAkC;IAClC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,GAAE,qBAA0B;IAK/C;;OAEG;IACG,oBAAoB,CACxB,QAAQ,EAAE,sBAAsB,EAChC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,CAAC;IA4C3B;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,EAAE,CAAC;IAwB7B;;OAEG;IACG,qBAAqB,CACzB,QAAQ,EAAE,sBAAsB,EAAE,EAClC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;IAW1C;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAwCzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,iBAAiB,IAAI,sBAAsB;IAI3C;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,YAAY,IAAI,MAAM;CAGvB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAElF"}
+{"version":3,"file":"code-generator.d.ts","sourceRoot":"","sources":["../../../src/realize/engines/code-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,sBAAsB,EAAyB,MAAM,sBAAsB,CAAC;AACrF,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IAErB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,oDAAoD;IACpD,cAAc,CAAC,EAAE,sBAAsB,CAAC;IAExC,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,kCAAkC;IAClC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,GAAE,qBAA0B;IAK/C;;OAEG;IACG,oBAAoB,CACxB,QAAQ,EAAE,sBAAsB,EAChC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,CAAC;IA+C3B;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,EAAE,CAAC;IAwB7B;;OAEG;IACG,qBAAqB,CACzB,QAAQ,EAAE,sBAAsB,EAAE,EAClC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;IAW1C;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAwCzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,iBAAiB,IAAI,sBAAsB;IAI3C;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,YAAY,IAAI,MAAM;CAGvB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAElF"}

package/dist/realize/engines/code-generator.js

@@ -37,6 +37,9 @@ export class CodeGenerator {
             workspaceRoot: process.cwd(),
             backendDir: 'backend',
             frontendDir: 'frontend',
+            // Realize-time output root, so multi-file generators (orchestrators
+            // that write their own files) know where the project is on disk.
+            outputDir: options.outputDir,
             ...(resolved.configuration || {}),
             ...(options.additionalContext || {}),
             ...context

package/dist/realize/engines/code-generator.js.map

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

package/libs/instance-factories/applications/react-app-starter.yaml

@@ -18,9 +18,9 @@ capabilities:
     - "app.frontend"
     - "ui.scaffolding"
     - "ui.router"
-    - "ui.static-views"
-    - "ui.static-forms"
-    - "ui.static-components"
+    - "ui.staticviews"
+    - "ui.staticforms"
+    - "ui.staticcomponents"
   requires: []
 
 technology:
@@ -99,21 +99,19 @@ codeTemplates:
     generator: "libs/instance-factories/applications/templates/react/env-example-generator.ts"
     outputPattern: "{frontendDir}/.env.example"
 
-  # API wiring — generated per project (endpoint paths / fetch client
-  # are instance-factory specific).
-  api-client:
-    engine: typescript
-    generator: "libs/instance-factories/applications/templates/react/api-client-generator.ts"
-    outputPattern: "{frontendDir}/src/lib/apiClient.ts"
-
+  # API wiring — starter-specific. The starter's hooks inline their
+  # own fetch transport so there is NO apiClient.ts (the runtime
+  # apiClient imports runtime-only types that this factory doesn't
+  # emit). Users wanting a shared transport layer can add one by
+  # hand; the hooks file is intentionally small enough to edit.
   use-api-hooks:
     engine: typescript
-    generator: "libs/instance-factories/applications/templates/react/use-api-hooks-generator.ts"
+    generator: "libs/instance-factories/applications/templates/react-starter/use-api-hooks-starter-generator.ts"
     outputPattern: "{frontendDir}/src/hooks/useApi.ts"
 
   api-types:
     engine: typescript
-    generator: "libs/instance-factories/applications/templates/react/api-types-generator.ts"
+    generator: "libs/instance-factories/applications/templates/react-starter/api-types-starter-generator.ts"
     outputPattern: "{frontendDir}/src/types/api.ts"
 
   # === Starter-specific: emitted view components + helpers + App + package.json ===
@@ -143,8 +141,3 @@ configuration:
     host: "localhost"
     proxy:
       "/api": "http://localhost:3000"
-
-notes:
-  - "Generated code is a starter — user edits are preserved across regeneration via content-hashing in .specverse-gen/hashes.json."
-  - "To accept an upstream regeneration for a file you've edited: delete the file first, then re-run `spv realize`."
-  - "No @specverse/runtime dep — the generated project is fully forkable; delete the .specverse-gen directory and rely only on the emitted source."

package/libs/instance-factories/applications/templates/react/env-example-generator.ts

@@ -11,8 +11,30 @@ export default function generateEnvExample(context: TemplateContext): string {
   const pathConfig = getPathConfig(context);
   const defaultApiUrl = getApiBaseUrl(pathConfig);
 
-  return `# API Configuration
-# Base URL for backend API
+  return `# ─── Ports ────────────────────────────────────────────────────
+# Running more than one SpecVerse project at once? Each project reads
+# its own .env — copy this file to .env and bump the numbers so the
+# projects don't collide.
+#
+# Suggested ranges (shared across the ecosystem):
+#   3000-3049 : generated project backends (one per project)
+#   3050-3099 : app-demo per-spec runtime backends
+#   5173-5199 : vite frontends (one per project)
+#   9000+     : app-demo Server Manager
+
+# Backend (Fastify) port — read by \`npm run dev:backend\`.
+PORT=3000
+
+# Frontend (vite) port — read by \`npm run dev:frontend\`.
+VITE_PORT=5173
+
+# Frontend host — '0.0.0.0' if you want LAN access.
+VITE_HOST=localhost
+
+# ─── API wiring ────────────────────────────────────────────────
+# Base URL for backend API. Used by the generated apiClient AND by
+# vite's dev-server proxy (so /api and /ws requests from the browser
+# are forwarded to your backend). Keep this in sync with PORT.
 VITE_API_BASE_URL=${defaultApiUrl}
 
 # API Path Prefix

package/libs/instance-factories/applications/templates/react/vite-config-generator.ts

@@ -16,45 +16,66 @@ export default function generateViteConfig(context: TemplateContext): string {
   const apiBaseUrl = getApiBaseUrl(pathConfig);
   const apiProxy = configuration?.vite?.proxy?.['/api'] || apiBaseUrl;
 
-  return `import { defineConfig } from 'vite';
+  return `import { defineConfig, loadEnv } from 'vite';
 import react from '@vitejs/plugin-react';
 import path from 'path';
 
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [react()],
-  server: {
-    port: ${vitePort},
-    host: '${viteHost}',
-    proxy: {
-      '/api': {
-        target: '${apiProxy}',
-        changeOrigin: true,
-      },
-      // WebSocket proxy — the runtime's useEntitySync hook opens
-      // ws://<host>/ws to receive entity mutation events from the
-      // backend event bus. Without this proxy the socket tries to
-      // connect to the vite dev server on /ws and fails, forcing
-      // state-sync to fall back to React Query's refetchInterval
-      // polling (usable but slow).
-      '/ws': {
-        target: '${apiProxy.replace(/^http/, 'ws')}',
-        ws: true,
-        changeOrigin: true,
+/**
+ * Ports and proxy targets are env-overridable via this project's
+ * .env (and .env.local). Lets you run several SpecVerse projects
+ * side-by-side without port collisions:
+ *
+ *   # project-a/.env
+ *   PORT=3001
+ *   VITE_PORT=5174
+ *   VITE_API_BASE_URL=http://localhost:3001
+ *
+ *   # project-b/.env
+ *   PORT=3002
+ *   VITE_PORT=5175
+ *   VITE_API_BASE_URL=http://localhost:3002
+ */
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '');
+  const port = Number(env.VITE_PORT ?? ${vitePort});
+  const host = env.VITE_HOST ?? '${viteHost}';
+  const apiTarget = env.VITE_API_BASE_URL ?? '${apiProxy}';
+
+  return {
+    plugins: [react()],
+    server: {
+      port,
+      host,
+      proxy: {
+        '/api': {
+          target: apiTarget,
+          changeOrigin: true,
+        },
+        // WebSocket proxy — the runtime's useEntitySync hook opens
+        // ws://<host>/ws to receive entity mutation events from the
+        // backend event bus. Without this proxy the socket tries to
+        // connect to the vite dev server on /ws and fails, forcing
+        // state-sync to fall back to React Query's refetchInterval
+        // polling (usable but slow).
+        '/ws': {
+          target: apiTarget.replace(/^http/, 'ws'),
+          ws: true,
+          changeOrigin: true,
+        },
       },
     },
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
-  },
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src'),
+    build: {
+      outDir: 'dist',
+      sourcemap: true,
+    },
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, './src'),
+      },
+      // Prevent React duplication when using local packages
+      dedupe: ['react', 'react-dom'],
     },
-    // Prevent React duplication when using local packages
-    dedupe: ['react', 'react-dom'],
-  },
+  };
 });
 `;
 }

package/libs/instance-factories/applications/templates/react-starter/__tests__/detail-body-composer.test.ts

@@ -57,10 +57,11 @@ describe('composeDetailBody — direct output', () => {
     expect(body).toContain('>Title<');
     expect(body).toContain('>Body<');
 
-    // belongsTo section — surfaces authorId and notes the FK→name gap
+    // belongsTo section — surfaces author as a resolved name via
+    // resolveEntityDisplayName against the authorOptions array wired
+    // in by view-emitter's RELATED_HOOKS substitution.
     expect(body).toContain('>Author<');
-    expect(body).toContain('.authorId ??');
-    expect(body).toContain('TODO: resolve FK ids');
+    expect(body).toContain('resolveEntityDisplayName((item as any).authorId, authorOptions)');
 
     // Metadata section (id / createdAt / publishedAt) — muted styling
     expect(body).toContain('>Id<');
@@ -113,7 +114,7 @@ describe('composeDetailBody — direct output', () => {
       viewName: 'SoloDetailView',
       modelSchemas: { Solo: solo },
     }));
-    expect(body).not.toContain('TODO: resolve FK');
+    expect(body).not.toContain('resolveEntityDisplayName');
     expect(body).toContain('>Name<');
   });
 });

package/libs/instance-factories/applications/templates/react-starter/__tests__/form-body-composer.test.ts

@@ -15,6 +15,7 @@ function makeContext(overrides: Partial<EmitContext> = {}): EmitContext {
       email: { type: 'Email', required: false },
       status: { type: 'String', required: false, values: ['draft', 'live', 'archived'] },
       authorId: { type: 'UUID', required: true },   // belongsTo FK
+      externalId: { type: 'UUID', required: false },   // non-FK UUID
       createdAt: { type: 'DateTime', required: false },   // metadata
     },
     relationships: {
@@ -121,8 +122,11 @@ describe('composeFormBody — input type per attribute', () => {
   });
 
   it('UUID → text input (treated like string)', () => {
+    // externalId is a plain UUID attribute — no belongsTo relationship
+    // shadows it, so it renders as a text input. (FK UUIDs like
+    // authorId render as a <select> instead; see the belongsTo suite.)
     const body = composeFormBody(makeContext());
-    expect(body).toMatch(/id="authorId"[\s\S]*type="text"/);
+    expect(body).toMatch(/id="externalId"[\s\S]*type="text"/);
   });
 });
 
@@ -145,11 +149,20 @@ describe('composeFormBody — required markers', () => {
 });
 
 describe('composeFormBody — belongsTo section', () => {
-  it('surfaces belongsTo FK inputs with a TODO comment', () => {
+  it('emits a <select> for each belongsTo, iterating ${relName}Options', () => {
     const body = composeFormBody(makeContext());
-    expect(body).toContain('TODO: swap these text inputs for <select>s');
-    // authorId is emitted as a text input
-    expect(body).toMatch(/id="authorId"[\s\S]*?type="text"/);
+    // Author belongsTo User — author is the relationship name, so the
+    // options array is authorOptions and the FK column is authorId.
+    expect(body).toMatch(/<select[\s\S]*?id="authorId"/);
+    expect(body).toContain('authorOptions.map');
+    expect(body).toContain('getEntityDisplayName(opt)');
+  });
+
+  it('does not emit plain text inputs for FK columns shadowed by a belongsTo', () => {
+    // authorId is shadowed by the author belongsTo relationship — it
+    // should only render once (as the <select>), never as a text input.
+    const body = composeFormBody(makeContext());
+    expect(body).not.toMatch(/<input[\s\S]*?id="authorId"[\s\S]*?type="text"/);
   });
 });
 

package/libs/instance-factories/applications/templates/react-starter/__tests__/orchestrator.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
 import * as ts from 'typescript';
@@ -55,22 +55,36 @@ function assertValidTsx(source: string, label: string): void {
 }
 
 /**
- * Apply an orchestrator output to disk — simulates what realize does
- * when it receives the multi-file generator result.
+ * Drive the orchestrator with the per-test tmp dir as the effective
+ * frontend root. `frontendDir='.'` collapses the
+ * `${outputDir}/${frontendDir}` join so files land directly under
+ * `projectRoot`, which keeps test assertions terse.
  */
-function applyOutput(output: Record<string, string>, root: string): void {
-  for (const [relPath, content] of Object.entries(output)) {
-    const abs = join(root, relPath);
-    mkdirSync(join(abs, '..'), { recursive: true });
-    writeFileSync(abs, content, 'utf8');
+async function runGenerate(spec = makeSpec()) {
+  return generate({ spec, outputDir: projectRoot, frontendDir: '.' });
+}
+
+/** List every file the orchestrator wrote under projectRoot. */
+function walk(dir: string, prefix = ''): string[] {
+  const { readdirSync, statSync } = require('fs');
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    const rel = prefix ? `${prefix}/${entry}` : entry;
+    if (statSync(abs).isDirectory()) out.push(...walk(abs, rel));
+    else out.push(rel);
   }
+  return out.sort();
 }
 
 describe('orchestrator — first-run (empty project)', () => {
-  it('returns the full set of files: views + helpers + App.tsx + package.json + hash manifest', async () => {
-    const output = await generate({ spec: makeSpec(), projectRoot });
-    const paths = Object.keys(output).sort();
-    expect(paths).toEqual([
+  it('writes the full set of files: views + helpers + App.tsx + package.json + hash manifest', async () => {
+    const ret = await runGenerate();
+    // Contract: returns '' (realize's single-file writeOutput skips it).
+    expect(ret).toBe('');
+
+    const written = walk(projectRoot);
+    expect(written).toEqual([
       `${HASHES_DIR}/${HASHES_FILE}`,
       'package.json',
       'src/App.tsx',
@@ -82,82 +96,89 @@ describe('orchestrator — first-run (empty project)', () => {
     ]);
   });
 
-  it('does not write to disk (that is realize\'s job)', async () => {
-    await generate({ spec: makeSpec(), projectRoot });
-    // Orchestrator is pure — nothing on disk yet.
-    expect(existsSync(join(projectRoot, 'package.json'))).toBe(false);
-    expect(existsSync(join(projectRoot, 'src/App.tsx'))).toBe(false);
-  });
-
   it('every emitted .tsx parses as valid TSX', async () => {
-    const output = await generate({ spec: makeSpec(), projectRoot });
-    for (const [path, source] of Object.entries(output)) {
-      if (path.endsWith('.tsx')) assertValidTsx(source, path);
+    await runGenerate();
+    for (const path of walk(projectRoot)) {
+      if (path.endsWith('.tsx')) {
+        const source = readFileSync(join(projectRoot, path), 'utf8');
+        assertValidTsx(source, path);
+      }
     }
   });
 
   it('package.json has no @specverse/runtime dependency', async () => {
-    const output = await generate({ spec: makeSpec(), projectRoot });
-    const pkg = JSON.parse(output['package.json']);
+    await runGenerate();
+    const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     expect(deps['@specverse/runtime']).toBeUndefined();
   });
 
   it('the emitted hash manifest records every approved file', async () => {
-    const output = await generate({ spec: makeSpec(), projectRoot });
-    const manifestKey = `${HASHES_DIR}/${HASHES_FILE}`;
-    const manifest = JSON.parse(output[manifestKey]);
-    // Every returned file (except the manifest itself) should have a hash.
-    for (const path of Object.keys(output)) {
-      if (path === manifestKey) continue;
-      expect(manifest[path]).toBe(sha256(output[path]));
+    await runGenerate();
+    const manifestPath = join(projectRoot, HASHES_DIR, HASHES_FILE);
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    for (const path of walk(projectRoot)) {
+      if (path === `${HASHES_DIR}/${HASHES_FILE}`) continue;
+      const content = readFileSync(join(projectRoot, path), 'utf8');
+      expect(manifest[path]).toBe(sha256(content));
     }
   });
 });
 
 describe('orchestrator — regeneration safety', () => {
   it('re-approves pristine files on a second run', async () => {
-    // First run — write outputs to disk to simulate realize.
-    const firstOutput = await generate({ spec: makeSpec(), projectRoot });
-    applyOutput(firstOutput, projectRoot);
-
-    // Second run — everything is pristine, should be re-approved.
-    const secondOutput = await generate({ spec: makeSpec(), projectRoot });
-    // The view files etc. should reappear in the output (realize will overwrite).
-    expect(secondOutput['src/views/PostListView.tsx']).toBeDefined();
+    await runGenerate();
+
+    // Record the first-run hash of one of the view files.
+    const listPath = 'src/views/PostListView.tsx';
+    const listAbs = join(projectRoot, listPath);
+    const firstContent = readFileSync(listAbs, 'utf8');
+
+    // Second run. Pristine files should be rewritten (the orchestrator
+    // writes them, possibly with identical bytes).
+    await runGenerate();
+    expect(existsSync(listAbs)).toBe(true);
+    expect(readFileSync(listAbs, 'utf8')).toBe(firstContent);
   });
 
-  it('omits a user-edited file from the output', async () => {
-    const firstOutput = await generate({ spec: makeSpec(), projectRoot });
-    applyOutput(firstOutput, projectRoot);
+  it('preserves a user-edited file across regeneration', async () => {
+    await runGenerate();
 
-    // User edits one of the files
     const editedPath = 'src/views/PostListView.tsx';
-    writeFileSync(join(projectRoot, editedPath), '/* edited */', 'utf8');
-
-    const secondOutput = await generate({ spec: makeSpec(), projectRoot });
-
-    // User-edited file not in the output → realize won't overwrite it
-    expect(secondOutput[editedPath]).toBeUndefined();
-    // Other files still present
-    expect(secondOutput['src/views/PostDetailView.tsx']).toBeDefined();
-    // Manifest preserves the OLD hash for the skipped file
-    const manifest = JSON.parse(secondOutput[`${HASHES_DIR}/${HASHES_FILE}`]);
-    const oldManifest = JSON.parse(firstOutput[`${HASHES_DIR}/${HASHES_FILE}`]);
-    expect(manifest[editedPath]).toBe(oldManifest[editedPath]);
+    const editedAbs = join(projectRoot, editedPath);
+    const userEdit = '/* user edit */';
+    writeFileSync(editedAbs, userEdit, 'utf8');
+
+    await runGenerate();
+
+    // File on disk is unchanged — user edit survived.
+    expect(readFileSync(editedAbs, 'utf8')).toBe(userEdit);
+    // Manifest still records the ORIGINAL (pre-edit) hash so a future
+    // un-edit can re-sync cleanly.
+    const manifest = JSON.parse(
+      readFileSync(join(projectRoot, HASHES_DIR, HASHES_FILE), 'utf8')
+    );
+    expect(manifest[editedPath]).toBeDefined();
+    expect(manifest[editedPath]).not.toBe(sha256(userEdit));
   });
 
   it('is cautious when the user deletes the hash manifest', async () => {
-    const firstOutput = await generate({ spec: makeSpec(), projectRoot });
-    applyOutput(firstOutput, projectRoot);
+    await runGenerate();
 
-    // User deletes the hash manifest
+    // User deletes the hash manifest but keeps the view files.
     rmSync(join(projectRoot, HASHES_DIR), { recursive: true, force: true });
 
-    const secondOutput = await generate({ spec: makeSpec(), projectRoot });
+    // Record the existing file contents (may be identical to what the
+    // orchestrator would emit, but we're treating them as unknown origin).
+    const listPath = join(projectRoot, 'src/views/PostListView.tsx');
+    const before = readFileSync(listPath, 'utf8');
+
+    await runGenerate();
 
-    // All existing files are now "unknown origin" → skipped.
-    // Output should only contain the fresh hash manifest.
-    expect(Object.keys(secondOutput)).toEqual([`${HASHES_DIR}/${HASHES_FILE}`]);
+    // No hash manifest means we can't tell user edits from originals, so
+    // existing files are skipped. Content is unchanged.
+    expect(readFileSync(listPath, 'utf8')).toBe(before);
+    // A fresh hash manifest was written.
+    expect(existsSync(join(projectRoot, HASHES_DIR, HASHES_FILE))).toBe(true);
   });
 });