@specverse/engines 4.1.21 → 4.1.23

package/dist/libs/instance-factories/views/templates/react/components-generator.js

@@ -135,13 +135,14 @@ function pluralize(s) {
 function generateListView(name, model, lower, plural, api, classified, belongsTo, lifecycle, view) {
   const displayCols = classified.business.slice(0, 5);
   const statusField = lifecycle?.statusField || classified.lifecycle[0]?.name;
+  const apiPath = api.replace(/^\/api/, "");
   const relFetches = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
     return `  const [${tLower}Map, set${r.target}Map] = useState<Record<string, any>>({});`;
   }).join("\n");
   const relEffects = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `    fetch('/api/${tLower}s').then(r => r.json()).then(data => {
+    return `    apiRequest('GET', '/${tLower}s').then(data => {
       if (Array.isArray(data)) {
         const m: Record<string, any> = {};
         data.forEach(e => { m[e.id] = e; });
@@ -156,6 +157,7 @@ function generateListView(name, model, lower, plural, api, classified, belongsTo
   });
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatValue, formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -165,7 +167,7 @@ function ${name}() {
 ${relFetches}
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -228,6 +230,7 @@ export default ${name};
 }
 function generateDetailView(name, model, lower, plural, api, classified, belongsTo, hasMany, lifecycle, view) {
   const statusField = lifecycle?.statusField || classified.lifecycle[0]?.name;
+  const apiPath = api.replace(/^\/api/, "");
   const relFetches = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
     return `  const [${tLower}Ref, set${r.target}Ref] = useState<any>(null);`;
@@ -235,7 +238,7 @@ function generateDetailView(name, model, lower, plural, api, classified, belongs
   const relEffects = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
     const fk = `${r.name}_id`;
-    return `      if (data.${fk}) fetch(\`/api/${tLower}s/\${data.${fk}}\`).then(r => r.json()).then(d => set${r.target}Ref(d)).catch(() => {});`;
+    return `      if (data.${fk}) apiRequest('GET', \`/${tLower}s/\${data.${fk}}\`).then(d => set${r.target}Ref(d)).catch(() => {});`;
   }).join("\n");
   const hasManyFetches = hasMany.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
@@ -243,10 +246,11 @@ function generateDetailView(name, model, lower, plural, api, classified, belongs
   }).join("\n");
   const hasManyEffects = hasMany.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `      fetch(\`/api/${tLower}s?${lower}Id=\${data.id}\`).then(r => r.json()).then(d => set${capitalize(r.name)}Items(Array.isArray(d) ? d : [])).catch(() => {});`;
+    return `      apiRequest('GET', \`/${tLower}s?${lower}Id=\${data.id}\`).then(d => set${capitalize(r.name)}Items(Array.isArray(d) ? d : [])).catch(() => {});`;
   }).join("\n");
   return `import { useState, useEffect } from 'react';
 import { Link, useSearchParams, useNavigate } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatValue, formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -261,7 +265,7 @@ ${hasManyFetches}
 
   useEffect(() => {
     if (!id) { setLoading(false); return; }
-    fetch(\`${api}/\${id}\`).then(r => r.ok ? r.json() : null).then(data => {
+    apiRequest('GET', \`${apiPath}/\${id}\`).then(data => {
       setItem(data);
       setLoading(false);
       if (data) {
@@ -276,7 +280,7 @@ ${hasManyEffects}
 
   const handleDelete = async () => {
     if (!confirm('Delete this ${lower}?')) return;
-    await fetch(\`${api}/\${id}\`, { method: 'DELETE' });
+    await apiRequest('DELETE', \`${apiPath}/\${id}\`);
     navigate('/${lower}list');
   };
 
@@ -358,12 +362,13 @@ export default ${name};
 function generateFormView(name, model, lower, plural, api, classified, belongsTo, lifecycle, view) {
   const editableFields = [...classified.business, ...classified.lifecycle];
   const statusField = lifecycle?.statusField;
+  const apiPath = api.replace(/^\/api/, "");
   const relStates = belongsTo.map((r) => {
     return `  const [${r.target.charAt(0).toLowerCase() + r.target.slice(1)}Options, set${r.target}Options] = useState<any[]>([]);`;
   }).join("\n");
   const relEffects = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `    fetch('/api/${tLower}s').then(r => r.json()).then(d => set${r.target}Options(Array.isArray(d) ? d : [])).catch(() => {});`;
+    return `    apiRequest('GET', '/${tLower}s').then(d => set${r.target}Options(Array.isArray(d) ? d : [])).catch(() => {});`;
   }).join("\n");
   function inputForField(attr) {
     const { name: n, type, required, values } = attr;
@@ -390,6 +395,7 @@ ${lifecycle.states.map((s) => `          <option value="${s}">${s.replace(/[_-]/
   }
   return `import { useState, useEffect } from 'react';
 import { useSearchParams, useNavigate } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 
 function ${name}() {
@@ -403,7 +409,7 @@ ${relStates}
 
   useEffect(() => {
     if (editId) {
-      fetch(\`${api}/\${editId}\`).then(r => r.json()).then(data => setForm(data || {})).catch(() => {});
+      apiRequest('GET', \`${apiPath}/\${editId}\`).then(data => setForm(data || {})).catch(() => {});
     }
 ${relEffects}
   }, [editId]);
@@ -418,17 +424,12 @@ ${relEffects}
     setSaving(true);
     setError('');
     try {
-      const method = editId ? 'PUT' : 'POST';
-      const url = editId ? \`${api}/\${editId}\` : '${api}';
-      const res = await fetch(url, {
-        method,
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(form),
-      });
-      if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw new Error(err.message || 'Save failed');
+      if (editId) {
+        await apiRequest('PUT', \`${apiPath}/\${editId}\`, form);
+      } else {
+        await apiRequest('POST', '${apiPath}', form);
       }
+      // apiRequest throws on non-2xx so reaching here means success.
       navigate('/${lower}list');
     } catch (err: any) {
       setError(err.message);
@@ -490,7 +491,9 @@ export default ${name};
 function generateDashboardView(name, model, lower, plural, api, classified, view, modelDef) {
   const numericAttrs = classified.business.filter((a) => ["integer", "number", "money", "decimal", "float"].includes(a.type.toLowerCase()));
   const metricNames = numericAttrs.map((a) => a.name).slice(0, 4);
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -499,7 +502,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -552,8 +555,10 @@ export default ${name};
 function generateBoardView(name, model, lower, plural, api, lifecycle, view) {
   const states = lifecycle?.states || ["todo", "in_progress", "done"];
   const statusField = lifecycle?.statusField || "status";
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { statusColor } from '../lib/view-helpers';
 
@@ -562,7 +567,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -614,8 +619,10 @@ export default ${name};
 `;
 }
 function generateTimelineView(name, model, lower, plural, api, view) {
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -624,7 +631,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       const sorted = (Array.isArray(data) ? data : []).sort((a, b) =>
         new Date(b.createdAt || 0).getTime() - new Date(a.createdAt || 0).getTime()
       );
@@ -669,7 +676,9 @@ function generateCalendarView(name, model, lower, plural, api, view, modelDef) {
   const dateField = attrs.find(
     (a) => ["startdate", "duedate", "scheduledat", "eventdate", "date"].includes(a.name.toLowerCase())
   )?.name || "createdAt";
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 
 function ${name}() {
@@ -678,7 +687,7 @@ function ${name}() {
   const [currentMonth, setCurrentMonth] = useState(new Date());
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -737,14 +746,16 @@ export default ${name};
 function generateAnalyticsView(name, model, lower, plural, api, classified, lifecycle, view, modelDef) {
   const numericAttrs = classified.business.filter((a) => ["integer", "number", "money", "decimal", "float"].includes(a.type.toLowerCase()));
   const statusField = lifecycle?.statusField || "status";
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 
 function ${name}() {
   const [items, setItems] = useState<any[]>([]);
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));

package/dist/libs/instance-factories/views/templates/react/hooks-generator.js

@@ -1,111 +1,81 @@
 function generateReactHook(context) {
-  const { model, controller, spec } = context;
+  const { model } = context;
   if (!model) {
     throw new Error("Model is required in template context");
   }
   const modelName = model.name;
   const hookName = `use${modelName}`;
   const controllerName = `${modelName}Controller`;
+  const singular = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+  const plural = singular + "s";
   return `/**
  * ${hookName}
- * Custom React hook for ${modelName} data fetching and mutations
+ *
+ * Thin delegator over the canonical useApi hooks. All state flows
+ * through \`['entities', '${modelName}']\` so WebSocket invalidation
+ * reaches every view consuming this hook.
  */
 
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { executeOperation } from '../lib/apiClient';
+import { useMemo } from 'react';
+import {
+  useEntitiesQuery,
+  useExecuteOperationMutation,
+} from './useApi';
 import type { ${modelName} } from '../types/${modelName}';
 
-interface Use${modelName}Options {
+interface ${capitalize(hookName)}Options {
   id?: string;
   list?: boolean;
   filters?: Record<string, any>;
 }
 
-/**
- * ${hookName} - Fetch and mutate ${modelName} data
- */
-export function ${hookName}(options: Use${modelName}Options = {}) {
-  const queryClient = useQueryClient();
-  const { id, list, filters } = options;
-
-  // Fetch single ${modelName}
-  const { data: ${modelName.toLowerCase()}, isLoading: singleLoading, error: singleError } = useQuery({
-    queryKey: ['${modelName.toLowerCase()}', id],
-    queryFn: async () => {
-      if (!id) return null;
-      return await executeOperation('${controllerName}', 'retrieve', { id });
-    },
-    enabled: !!id && !list,
-  });
-
-  // Fetch list of ${modelName}s
-  const { data: ${modelName.toLowerCase()}s, isLoading: listLoading, error: listError } = useQuery({
-    queryKey: ['${modelName.toLowerCase()}s', filters],
-    queryFn: async () => {
-      return await executeOperation('${controllerName}', 'list', filters || {});
-    },
-    enabled: list,
-  });
-
-  const isLoading = list ? listLoading : singleLoading;
-  const error = list ? listError : singleError;
-
-  // Create mutation
-  const createMutation = useMutation({
-    mutationFn: async (data: Partial<${modelName}>) => {
-      return await executeOperation('${controllerName}', 'create', data);
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
+export function ${hookName}(opts: ${capitalize(hookName)}Options = {}) {
+  const { id, filters: _filters } = opts;
 
-  // Update mutation
-  const updateMutation = useMutation({
-    mutationFn: async ({ id, data }: { id: string; data: Partial<${modelName}> }) => {
-      return await executeOperation('${controllerName}', 'update', { id, ...data });
-    },
-    onSuccess: (_, variables) => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}', variables.id] });
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
+  // Canonical list query \u2014 one cache key per model. The list flag
+  // is preserved for backwards compatibility but the query always
+  // runs; React Query dedupes across consumers automatically.
+  const query = useEntitiesQuery('${controllerName}', '${modelName}');
+  const ${plural} = (query.data as ${modelName}[] | undefined) || [];
 
-  // Delete mutation
-  const deleteMutation = useMutation({
-    mutationFn: async (id: string) => {
-      return await executeOperation('${controllerName}', 'delete', { id });
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
-
-  // Refetch functions
-  const refetch = () => {
-    if (list) {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    } else if (id) {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}', id] });
+  // Single-entity lookup is client-side against the canonical list
+  // so both the detail view and the list view share one source of
+  // truth. If the caller needs server-side hydration for a single
+  // entity, they should call useEntitiesQuery directly with a
+  // filtered controller endpoint.
+  const ${singular} = useMemo<${modelName} | null>(() => {
+    if (!id) return null;
+    for (const entity of ${plural}) {
+      const entityId = (entity as any)?.id || (entity as any)?.data?.id;
+      if (entityId === id) return entity;
     }
-  };
+    return null;
+  }, [id, ${plural}]);
+
+  const mutation = useExecuteOperationMutation();
 
   return {
-    ${modelName.toLowerCase()},
-    ${modelName.toLowerCase()}s,
-    isLoading,
-    error,
-    refetch,
-    create: createMutation.mutateAsync,
-    update: updateMutation.mutateAsync,
-    delete: deleteMutation.mutateAsync,
-    isCreating: createMutation.isPending,
-    isUpdating: updateMutation.isPending,
-    isDeleting: deleteMutation.isPending,
+    ${singular},
+    ${plural},
+    isLoading: query.isLoading,
+    error: query.error,
+    refetch: () => { /* handled by useEntitiesQuery refetchInterval + WS invalidation */ },
+    create: (data: Partial<${modelName}>) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'create', data: data as Record<string, unknown> }),
+    update: (args: { id: string; data: Partial<${modelName}> }) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'update', entityId: args.id, data: args.data as Record<string, unknown> }),
+    delete: (entityId: string) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'delete', entityId, data: {} }),
+    isCreating: mutation.isPending,
+    isUpdating: mutation.isPending,
+    isDeleting: mutation.isPending,
   };
 }
 `;
 }
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
 export {
   generateReactHook as default
 };

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realize/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAMlE,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AASnF,cAAM,sBAAuB,YAAW,aAAa;IACnD,IAAI,SAAa;IACjB,OAAO,SAAW;IAClB,YAAY,WAA+E;IAE3F,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,WAAW,CAAS;IAEtB,UAAU,CAAC,MAAM,CAAC,EAAE;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBjB,OAAO,IAAI,UAAU;IAIrB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG;IAK1B,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC;IAKvF;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA4lB9F;;;OAGG;YACW,UAAU;IAwDxB,OAAO,CAAC,oBAAoB;CAuB7B;AAED,eAAO,MAAM,MAAM,wBAA+B,CAAC;AACnD,eAAe,MAAM,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realize/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAMlE,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AASnF,cAAM,sBAAuB,YAAW,aAAa;IACnD,IAAI,SAAa;IACjB,OAAO,SAAW;IAClB,YAAY,WAA+E;IAE3F,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,WAAW,CAAS;IAEtB,UAAU,CAAC,MAAM,CAAC,EAAE;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBjB,OAAO,IAAI,UAAU;IAIrB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG;IAK1B,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC;IAKvF;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAoyB9F;;;OAGG;YACW,UAAU;IAwDxB,OAAO,CAAC,oBAAoB;CAuB7B;AAED,eAAO,MAAM,MAAM,wBAA+B,CAAC;AACnD,eAAe,MAAM,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/realize/index.js

@@ -665,6 +665,210 @@ export default {
         catch (e) {
             errors.push(`Assets: ${e.message}`);
         }
+        // 13. UI contract tests (Phase 1 of the inference test framework).
+        // Rules live in engines/src/inference/ui-contracts/. Each rule is
+        // a pure function (spec) => TestCase[]; the translator renders each
+        // rule's output into a single .spec.ts file under
+        // generated/code/tests/contract/. A Playwright config and the
+        // test:contract npm script are emitted alongside.
+        try {
+            const { generateContractTests, normalizeSpec } = await import('../inference/ui-contracts/index.js');
+            const normalized = normalizeSpec(spec);
+            const contractFiles = generateContractTests(normalized);
+            if (contractFiles.length > 0) {
+                const contractDir = join(outputDir, 'tests', 'contract');
+                if (!existsSync(contractDir))
+                    mkdirSync(contractDir, { recursive: true });
+                let totalTests = 0;
+                for (const f of contractFiles) {
+                    writeFileSync(join(contractDir, f.filename), f.contents, 'utf-8');
+                    totalTests += f.testCount;
+                }
+                // Playwright config — written once at the output root. Uses
+                // the tests/contract directory exclusively; behavioral tests
+                // (if any) live under tests/e2e/ and are handled by a
+                // separate playwright.behavioral.config.ts (not auto-generated).
+                const playwrightConfigPath = join(outputDir, 'playwright.contract.config.ts');
+                const playwrightConfig = `/**
+ * Playwright config for auto-generated UI contract tests.
+ * DO NOT EDIT — regenerated every \`spv realize\` run.
+ *
+ * Behavioral tests (hand-written) live under tests/e2e/ and use a
+ * separate playwright.config.ts that you maintain yourself.
+ */
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/contract',
+  timeout: 30_000,
+  expect: { timeout: 10_000 },
+  reporter: 'list',
+  use: {
+    baseURL: process.env.SPECVERSE_FRONTEND_URL || 'http://localhost:5173',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { browserName: 'chromium' },
+    },
+  ],
+});
+`;
+                writeFileSync(playwrightConfigPath, playwrightConfig, 'utf-8');
+                console.log(`   ✅ UI contract tests: ${contractFiles.length} file(s), ${totalTests} test case(s)`);
+            }
+        }
+        catch (e) {
+            errors.push(`UI contract tests: ${e.message}`);
+        }
+        // 14. Implementation conformance checks (Phase 5 of the inference
+        // test framework). Static, grep-level checks that verify the
+        // current React-Query-based implementation honors the design
+        // contract. Runs in milliseconds, no browser needed. When the
+        // runtime is rewritten in a different state library, this script
+        // gets rewritten too — the design-contract Playwright tests above
+        // are the stable layer, these checks are the short-lived ratchet
+        // that enforces "no escape hatches in the current implementation".
+        try {
+            const scriptsDir = join(outputDir, 'scripts');
+            if (!existsSync(scriptsDir))
+                mkdirSync(scriptsDir, { recursive: true });
+            const conformanceScript = `#!/usr/bin/env node
+/**
+ * Implementation conformance checks — auto-generated.
+ * DO NOT EDIT — regenerated every \`spv realize\` run.
+ *
+ * Verifies the current React-Query-based runtime implementation
+ * doesn't have escape hatches that could violate the design
+ * contract:
+ *   1. no-raw-fetch-in-views — view components go through apiClient
+ *   2. no-bare-usequery-in-views — view components use named hooks
+ *   3. websocket-invalidates-cache — WS events trigger cache refetch
+ *   4. mutation-hooks-invalidate — mutations invalidate after success
+ *
+ * Exits 1 on any failure. Fast (grep-level, no browser).
+ */
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, '..');
+let failed = false;
+
+function walk(dir, pattern, exclude = []) {
+  const hits = [];
+  const visit = (d) => {
+    let stat;
+    try { stat = statSync(d); } catch { return; }
+    if (!stat.isDirectory()) return;
+    for (const entry of readdirSync(d)) {
+      const p = join(d, entry);
+      if (exclude.some(e => p.includes(e))) continue;
+      let s;
+      try { s = statSync(p); } catch { continue; }
+      if (s.isDirectory()) visit(p);
+      else if (/\\.(ts|tsx|js|jsx|mjs)$/.test(entry)) {
+        const lines = readFileSync(p, 'utf-8').split('\\n');
+        lines.forEach((line, i) => {
+          if (pattern.test(line)) hits.push({ file: p, line: i + 1, text: line.trim() });
+        });
+      }
+    }
+  };
+  visit(dir);
+  return hits;
+}
+
+function report(name, ok, msg, hits) {
+  console.log(\`\${ok ? '\\u2713' : '\\u2717'} \${name}\${msg ? ' \\u2014 ' + msg : ''}\`);
+  if (!ok) {
+    failed = true;
+    if (hits) {
+      for (const h of hits.slice(0, 5)) {
+        console.log(\`    \${h.file}:\${h.line}  \${h.text.slice(0, 120)}\`);
+      }
+      if (hits.length > 5) console.log(\`    ... and \${hits.length - 5} more\`);
+    }
+  }
+}
+
+const frontendSrc = join(root, 'frontend', 'src');
+const componentsDir = join(frontendSrc, 'components');
+const pagesDir = join(frontendSrc, 'pages');
+
+// 1. no-raw-fetch-in-views
+{
+  const hits = [
+    ...walk(componentsDir, /\\bfetch\\s*\\(/),
+    ...walk(pagesDir, /\\bfetch\\s*\\(/),
+  ];
+  report(
+    'no-raw-fetch-in-views',
+    hits.length === 0,
+    hits.length === 0 ? '' : \`found \${hits.length} raw fetch() call(s) outside apiClient\`,
+    hits
+  );
+}
+
+// 2. no-bare-usequery-in-views — allow useQuery only inside hooks/useApi
+{
+  const hits = walk(frontendSrc, /\\buseQuery\\s*\\(/, ['hooks/useApi', 'lib/']);
+  report(
+    'no-bare-usequery-in-views',
+    hits.length === 0,
+    hits.length === 0 ? '' : \`found \${hits.length} bare useQuery() call(s) outside useApi\`,
+    hits
+  );
+}
+
+// 3. websocket-invalidates-cache — runtime must wire WS → invalidate
+{
+  const candidates = [
+    join(root, 'node_modules', '@specverse', 'runtime', 'dist', 'runtime', 'views', 'react', 'hooks', 'useEntitySync.js'),
+  ];
+  let content = null;
+  for (const path of candidates) {
+    try { content = readFileSync(path, 'utf-8'); break; } catch { /* keep trying */ }
+  }
+  if (!content) {
+    report('websocket-invalidates-cache', false, 'useEntitySync hook not found in @specverse/runtime');
+  } else if (!/invalidateEntities/.test(content)) {
+    report('websocket-invalidates-cache', false, 'useEntitySync does not call invalidateEntities on event receipt');
+  } else {
+    report('websocket-invalidates-cache', true, '');
+  }
+}
+
+// 4. mutation-hooks-invalidate — useApi.ts must invalidate on success
+{
+  const useApiPath = join(frontendSrc, 'hooks', 'useApi.ts');
+  let content = null;
+  try { content = readFileSync(useApiPath, 'utf-8'); } catch { /* ignore */ }
+  if (!content) {
+    report('mutation-hooks-invalidate', false, 'frontend/src/hooks/useApi.ts not found');
+  } else if (!/useExecuteOperationMutation/.test(content)) {
+    report('mutation-hooks-invalidate', false, 'useExecuteOperationMutation not exported from useApi.ts');
+  } else if (!/invalidateQueries/.test(content)) {
+    report('mutation-hooks-invalidate', false, 'useApi.ts does not call invalidateQueries on mutation success');
+  } else {
+    report('mutation-hooks-invalidate', true, '');
+  }
+}
+
+if (failed) {
+  console.log('\\n\\u2717 conformance checks failed');
+  process.exit(1);
+}
+console.log('\\n\\u2713 all conformance checks passed');
+`;
+            writeFileSync(join(scriptsDir, 'test-conformance.mjs'), conformanceScript, 'utf-8');
+            console.log(`   ✅ UI contract conformance: scripts/test-conformance.mjs`);
+        }
+        catch (e) {
+            errors.push(`UI conformance: ${e.message}`);
+        }
         console.log(`\n✅ All code generated in: ${outputDir}`);
         if (errors.length) {
             console.warn(`⚠️  ${errors.length} warning(s) during generation`);