@specverse/engines 4.1.21 → 4.1.23

package/dist/inference/ui-contracts/test-case-types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * TestCase — declarative description of a UI contract test.
+ *
+ * Rules (pure functions) produce TestCase[]. The translator renders
+ * each TestCase into a Playwright `.spec.ts` file that imports helpers
+ * from `@specverse/runtime/test-harness`. Neither rules nor test cases
+ * know anything about React Query, cache invalidation, or any
+ * implementation detail — they speak only spec language.
+ *
+ * v1 steps cover navigation + assertion. Later phases add create /
+ * delete / evolve / expect-absent for state-sync rules.
+ */
+export type TestStep = {
+    action: 'bootRuntime';
+} | {
+    action: 'expectNavHasModel';
+    modelName: string;
+} | {
+    action: 'navigateToModel';
+    modelName: string;
+} | {
+    action: 'expectViewRenders';
+} | {
+    action: 'expectListColumn';
+    modelName: string;
+    attributeName: string;
+} | {
+    action: 'expectFormInput';
+    modelName: string;
+    attributeName: string;
+    required?: boolean;
+} | {
+    action: 'expectLifecycleState';
+    modelName: string;
+    stateName: string;
+} | {
+    action: 'expectRelationshipSection';
+    modelName: string;
+    relationshipName: string;
+} | {
+    action: 'expectActionButton';
+    modelName: string;
+    actionLabel: string;
+} | {
+    action: 'createEntity';
+    modelName: string;
+    data: Record<string, unknown>;
+    bindAs?: string;
+} | {
+    action: 'deleteEntity';
+    modelName: string;
+    idExpr: string;
+} | {
+    action: 'evolveEntity';
+    modelName: string;
+    idExpr: string;
+    targetState: string;
+} | {
+    action: 'expectEntityInList';
+    modelName: string;
+    displayValue: string;
+} | {
+    action: 'expectEntityAbsent';
+    modelName: string;
+    displayValue: string;
+};
+export interface TestCase {
+    /** The rule that produced this test case. Used in test names for attribution. */
+    ruleId: string;
+    /** The spec element the case applies to (e.g. 'Poll', 'PollController.delete'). */
+    specElement: string;
+    /** Full test name — shown by Playwright reporter. */
+    name: string;
+    /** Ordered sequence of actions/assertions. */
+    steps: TestStep[];
+}
+/**
+ * A rule is a pure function from a normalized spec to a list of test
+ * cases. Rules never touch the filesystem, the network, or any mutable
+ * state — they just describe what should be tested.
+ */
+export type UiContractRule = (spec: NormalizedSpec) => TestCase[];
+/**
+ * Minimal normalized spec shape the rules operate on. The realize
+ * pipeline converts raw spec output into this shape before running
+ * rules. Kept deliberately small — rules grow their own helpers as
+ * they need richer data.
+ */
+export interface NormalizedSpec {
+    models: ModelInfo[];
+    controllers?: ControllerInfo[];
+    services?: ServiceInfo[];
+    views?: ViewInfo[];
+}
+export interface ModelInfo {
+    name: string;
+    attributes?: AttributeInfo[];
+    lifecycles?: Record<string, unknown>;
+    relationships?: RelationshipInfo[];
+}
+export interface AttributeInfo {
+    name: string;
+    type?: string;
+    required?: boolean;
+    category?: 'business' | 'metadata' | 'relationship';
+}
+export interface RelationshipInfo {
+    name: string;
+    type: string;
+    target?: string;
+}
+export interface ControllerInfo {
+    name: string;
+    model?: string;
+    cured?: Record<string, unknown>;
+}
+export interface ServiceInfo {
+    name: string;
+    operations?: Record<string, unknown>;
+}
+export interface ViewInfo {
+    name: string;
+    type: string;
+    model?: string;
+}
+//# sourceMappingURL=test-case-types.d.ts.map

package/dist/inference/ui-contracts/test-case-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-case-types.d.ts","sourceRoot":"","sources":["../../../src/inference/ui-contracts/test-case-types.ts"],"names":[],"mappings":"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"}

package/dist/inference/ui-contracts/test-case-types.js

@@ -0,0 +1,14 @@
+/**
+ * TestCase — declarative description of a UI contract test.
+ *
+ * Rules (pure functions) produce TestCase[]. The translator renders
+ * each TestCase into a Playwright `.spec.ts` file that imports helpers
+ * from `@specverse/runtime/test-harness`. Neither rules nor test cases
+ * know anything about React Query, cache invalidation, or any
+ * implementation detail — they speak only spec language.
+ *
+ * v1 steps cover navigation + assertion. Later phases add create /
+ * delete / evolve / expect-absent for state-sync rules.
+ */
+export {};
+//# sourceMappingURL=test-case-types.js.map

package/dist/inference/ui-contracts/test-case-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-case-types.js","sourceRoot":"","sources":["../../../src/inference/ui-contracts/test-case-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/inference/ui-contracts/translator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * TestCase → Playwright .spec.ts translator.
+ *
+ * Renders a list of TestCase objects into a single Playwright spec
+ * file. The output file imports from `@specverse/runtime/test-harness`
+ * and nothing else from the runtime — all logic lives in the harness
+ * helpers. The translator is intentionally dumb: each step maps to a
+ * helper call, nothing more.
+ */
+import type { TestCase } from './test-case-types.js';
+/**
+ * Render a full `.spec.ts` file for one or more test cases sharing
+ * the same rule. One file per rule keeps failures easy to attribute
+ * and lets `npx playwright test` filter by rule ID via file glob.
+ */
+export declare function renderSpecFile(ruleId: string, testCases: TestCase[]): string;
+//# sourceMappingURL=translator.d.ts.map

package/dist/inference/ui-contracts/translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.d.ts","sourceRoot":"","sources":["../../../src/inference/ui-contracts/translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAwF/D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,CA6B5E"}

package/dist/inference/ui-contracts/translator.js

@@ -0,0 +1,127 @@
+/**
+ * TestCase → Playwright .spec.ts translator.
+ *
+ * Renders a list of TestCase objects into a single Playwright spec
+ * file. The output file imports from `@specverse/runtime/test-harness`
+ * and nothing else from the runtime — all logic lives in the harness
+ * helpers. The translator is intentionally dumb: each step maps to a
+ * helper call, nothing more.
+ */
+/**
+ * Render a single step as a line of test body code.
+ */
+function renderStep(step) {
+    switch (step.action) {
+        case 'bootRuntime':
+            // Assign `page` once per test body. Multiple bootRuntime steps
+            // inside one test aren't supported and would shadow the binding.
+            return `  const { page } = await bootRuntime(browser);`;
+        case 'expectNavHasModel':
+            return `  await expectNavHasModel(page, ${JSON.stringify(step.modelName)});`;
+        case 'navigateToModel':
+            return `  await navigateToModel(page, ${JSON.stringify(step.modelName)});`;
+        case 'expectViewRenders':
+            return `  await expectViewRenders(page);`;
+        case 'expectListColumn':
+            return `  await expectListColumn(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.attributeName)});`;
+        case 'expectFormInput': {
+            const opts = step.required ? `, { required: true }` : ``;
+            return `  await expectFormInput(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.attributeName)}${opts});`;
+        }
+        case 'expectLifecycleState':
+            return `  await expectLifecycleState(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.stateName)});`;
+        case 'expectRelationshipSection':
+            return `  await expectRelationshipSection(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.relationshipName)});`;
+        case 'expectActionButton':
+            return `  await expectActionButton(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.actionLabel)});`;
+        case 'createEntity': {
+            const varName = step.bindAs || '_entityId';
+            const dataLit = JSON.stringify(step.data);
+            return `  const ${varName} = await createEntity(page, ${JSON.stringify(step.modelName)}, ${dataLit});`;
+        }
+        case 'deleteEntity':
+            return `  await deleteEntity(page, ${JSON.stringify(step.modelName)}, ${step.idExpr});`;
+        case 'evolveEntity':
+            return `  await evolveEntity(page, ${JSON.stringify(step.modelName)}, ${step.idExpr}, ${JSON.stringify(step.targetState)});`;
+        case 'expectEntityInList':
+            return `  await expectEntityInList(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.displayValue)});`;
+        case 'expectEntityAbsent':
+            return `  await expectEntityAbsent(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.displayValue)});`;
+        default: {
+            const _exhaustive = step;
+            throw new Error(`translator: unknown step action: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Collect the set of harness helpers a test case depends on so the
+ * import list only contains what's actually used.
+ */
+function helpersFor(step) {
+    switch (step.action) {
+        case 'bootRuntime':
+            return ['bootRuntime'];
+        case 'expectNavHasModel':
+            return ['expectNavHasModel'];
+        case 'navigateToModel':
+            return ['navigateToModel'];
+        case 'expectViewRenders':
+            return ['expectViewRenders'];
+        case 'expectListColumn':
+            return ['expectListColumn'];
+        case 'expectFormInput':
+            return ['expectFormInput'];
+        case 'expectLifecycleState':
+            return ['expectLifecycleState'];
+        case 'expectRelationshipSection':
+            return ['expectRelationshipSection'];
+        case 'expectActionButton':
+            return ['expectActionButton'];
+        case 'createEntity':
+            return ['createEntity'];
+        case 'deleteEntity':
+            return ['deleteEntity'];
+        case 'evolveEntity':
+            return ['evolveEntity'];
+        case 'expectEntityInList':
+            return ['expectEntityInList'];
+        case 'expectEntityAbsent':
+            return ['expectEntityAbsent'];
+        default:
+            return [];
+    }
+}
+/**
+ * Render a full `.spec.ts` file for one or more test cases sharing
+ * the same rule. One file per rule keeps failures easy to attribute
+ * and lets `npx playwright test` filter by rule ID via file glob.
+ */
+export function renderSpecFile(ruleId, testCases) {
+    const helpers = new Set();
+    for (const tc of testCases) {
+        for (const step of tc.steps) {
+            for (const h of helpersFor(step))
+                helpers.add(h);
+        }
+    }
+    const importList = [...helpers].sort().join(', ');
+    const header = `/**
+ * Auto-generated UI contract test file.
+ * Rule: ${ruleId}
+ * DO NOT EDIT — regenerated every \`spv realize\` run. Hand edits are
+ * lost on the next regenerate. Change the rule or the spec instead.
+ */
+
+import { test } from '@playwright/test';
+import { ${importList} } from '@specverse/runtime/test-harness';
+`;
+    const body = testCases.map(tc => {
+        const stepLines = tc.steps.map(renderStep).join('\n');
+        return `
+test(${JSON.stringify(tc.name)}, async ({ browser }) => {
+${stepLines}
+});`;
+    }).join('\n');
+    return header + body + '\n';
+}
+//# sourceMappingURL=translator.js.map

package/dist/inference/ui-contracts/translator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.js","sourceRoot":"","sources":["../../../src/inference/ui-contracts/translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,SAAS,UAAU,CAAC,IAAc;IAChC,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,aAAa;YAChB,+DAA+D;YAC/D,iEAAiE;YACjE,OAAO,gDAAgD,CAAC;QAC1D,KAAK,mBAAmB;YACtB,OAAO,mCAAmC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAC/E,KAAK,iBAAiB;YACpB,OAAO,iCAAiC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAC7E,KAAK,mBAAmB;YACtB,OAAO,kCAAkC,CAAC;QAC5C,KAAK,kBAAkB;YACrB,OAAO,kCAAkC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;QACrH,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,OAAO,iCAAiC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,IAAI,IAAI,CAAC;QAC3H,CAAC;QACD,KAAK,sBAAsB;YACzB,OAAO,sCAAsC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QACrH,KAAK,2BAA2B;YAC9B,OAAO,2CAA2C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;QACjI,KAAK,oBAAoB;YACvB,OAAO,oCAAoC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QACrH,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,WAAW,CAAC;YAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1C,OAAO,WAAW,OAAO,+BAA+B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,OAAO,IAAI,CAAC;QACzG,CAAC;QACD,KAAK,cAAc;YACjB,OAAO,8BAA8B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC;QAC1F,KAAK,cAAc;YACjB,OAAO,8BAA8B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAC/H,KAAK,oBAAoB;YACvB,OAAO,oCAAoC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;QACtH,KAAK,oBAAoB;YACvB,OAAO,oCAAoC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;QACtH,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,IAAI,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,oCAAoC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,IAAc;IAChC,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,aAAa;YAChB,OAAO,CAAC,aAAa,CAAC,CAAC;QACzB,KAAK,mBAAmB;YACtB,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAC/B,KAAK,iBAAiB;YACpB,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAC7B,KAAK,mBAAmB;YACtB,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAC/B,KAAK,kBAAkB;YACrB,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAC9B,KAAK,iBAAiB;YACpB,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAC7B,KAAK,sBAAsB;YACzB,OAAO,CAAC,sBAAsB,CAAC,CAAC;QAClC,KAAK,2BAA2B;YAC9B,OAAO,CAAC,2BAA2B,CAAC,CAAC;QACvC,KAAK,oBAAoB;YACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC;QAChC,KAAK,cAAc;YACjB,OAAO,CAAC,cAAc,CAAC,CAAC;QAC1B,KAAK,cAAc;YACjB,OAAO,CAAC,cAAc,CAAC,CAAC;QAC1B,KAAK,cAAc;YACjB,OAAO,CAAC,cAAc,CAAC,CAAC;QAC1B,KAAK,oBAAoB;YACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC;QAChC,KAAK,oBAAoB;YACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC;QAChC;YACE,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,SAAqB;IAClE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;YAC5B,KAAK,MAAM,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAElD,MAAM,MAAM,GAAG;;WAEN,MAAM;;;;;;WAMN,UAAU;CACpB,CAAC;IAEA,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QAC9B,MAAM,SAAS,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,OAAO;OACJ,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC;EAC5B,SAAS;IACP,CAAC;IACH,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;AAC9B,CAAC"}

package/dist/libs/instance-factories/applications/templates/react/api-client-generator.js

@@ -43,9 +43,12 @@ export const WS_URL = apiUrl
   : \`\${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}/\${window.location.host}/ws\`;
 
 /**
- * Generic API request helper
+ * Generic API request helper \u2014 exported so view components can
+ * use it as a drop-in replacement for raw fetch calls. Always
+ * routes through this module so the conformance check
+ * \`no-raw-fetch-in-views\` stays green.
  */
-async function apiRequest<T = any>(
+export async function apiRequest<T = any>(
   method: string,
   path: string,
   body: any = null
@@ -304,6 +307,22 @@ export async function executeOperation(
   return apiRequest<ApiResponse>(method, path, Object.keys(params).length > 0 ? params : null);
 }
 
+/**
+ * Execute a service operation
+ * Services are RPC-style under /services/{serviceName}/{operationName}
+ */
+export async function executeServiceOperation(
+  serviceName: string,
+  operationName: string,
+  params: Record<string, any>
+): Promise<ApiResponse> {
+  return apiRequest<ApiResponse>(
+    'POST',
+    \`/services/\${serviceName}/\${operationName}\`,
+    params
+  );
+}
+
 /**
  * Transition entity lifecycle state
  */
@@ -395,6 +414,22 @@ export async function executeOperation(
   );
 }
 
+/**
+ * Execute a service operation
+ * Services are RPC-style under /services/{serviceName}/{operationName}
+ */
+export async function executeServiceOperation(
+  serviceName: string,
+  operationName: string,
+  params: Record<string, any>
+): Promise<ApiResponse> {
+  return apiRequest<ApiResponse>(
+    'POST',
+    \`/services/\${serviceName}/\${operationName}\`,
+    params
+  );
+}
+
 /**
  * Transition entity lifecycle state
  */

package/dist/libs/instance-factories/applications/templates/react/runtime-app-tsx-generator.js

@@ -1,10 +1,10 @@
 function generateRuntimeAppTsx(context) {
   const { spec } = context;
   const appName = spec?.metadata?.name || spec?.name || "SpecVerse App";
-  return `import { useState, useEffect, useMemo } from 'react';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+  return `import { useState, useEffect, useMemo, useCallback } from 'react';
+import { QueryClient, QueryClientProvider, useQueryClient } from '@tanstack/react-query';
 import yaml from 'js-yaml';
-import { RuntimeViewProvider } from '@specverse/runtime/views/react';
+import { RuntimeViewProvider, useEntitySync } from '@specverse/runtime/views/react';
 import { DevShell } from '@specverse/runtime/views/react';
 import {
   useEntitiesQuery,
@@ -12,6 +12,7 @@ import {
   useExecuteOperationMutation,
   useTransitionStateMutation,
 } from './hooks/useApi';
+import { listEntities, getRuntimeInfo } from './lib/apiClient';
 import devSpecRaw from './dev.specly?raw';
 
 // Parse YAML spec
@@ -64,6 +65,40 @@ function AppContent() {
       .catch(() => {});
   }, []);
 
+  // State-sync contract: WebSocket entity events \u2192 React Query cache
+  // invalidation. This is what guarantees "delete in one view is visible
+  // in every other view within one WS round-trip" \u2014 it runs at the App
+  // level so it's always on, regardless of which tab is active.
+  const queryClient = useQueryClient();
+  const invalidateEntities = useCallback((modelName: string) => {
+    queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+  }, [queryClient]);
+  useEntitySync({ invalidateEntities, apiBaseUrl: '/api' });
+
+  // Name resolver for OperationResultView. Kept in the host so runtime
+  // view components never issue raw fetch() calls \u2014 all HTTP goes
+  // through apiClient's canonical layer.
+  const resolveEntityNames = useCallback(async (ids: string[]): Promise<Record<string, string>> => {
+    const names: Record<string, string> = {};
+    try {
+      const info = await getRuntimeInfo();
+      const models = info?.models || [];
+      await Promise.all(models.map(async (model: string) => {
+        try {
+          const entities = await listEntities(model + 'Controller');
+          for (const entity of entities) {
+            const id = (entity as any)?.id;
+            const dataId = (entity as any)?.data?.id;
+            const display = (entity as any)?.name || (entity as any)?.title || (entity as any)?.label || id;
+            if (id && ids.includes(id)) names[id] = String(display);
+            if (dataId && ids.includes(dataId)) names[dataId] = String(display);
+          }
+        } catch { /* skip this model */ }
+      }));
+    } catch { /* ignore \u2014 caller falls back to raw IDs */ }
+    return names;
+  }, []);
+
   const runtimeValue = useMemo(() => ({
     useEntitiesQuery,
     useModelSchemaQuery,
@@ -74,7 +109,9 @@ function AppContent() {
     views: [],
     spec: appSpec,
     apiBaseUrl: '/api',
-  }), [appSpec]);
+    invalidateEntities,
+    resolveEntityNames,
+  }), [appSpec, invalidateEntities, resolveEntityNames]);
 
   return (
     <RuntimeViewProvider value={runtimeValue}>

package/dist/libs/instance-factories/applications/templates/react/use-api-hooks-generator.js

@@ -11,6 +11,7 @@ import {
   getModelSchema,
   listEntities,
   executeOperation,
+  executeServiceOperation,
   transitionState
 } from '../lib/apiClient';
 import type { ModelSchema, Entity, ApiResponse } from '../types/api';
@@ -49,9 +50,14 @@ export function useEntitiesQuery(controllerName: string | null, modelName: strin
 }
 
 /**
- * Mutation hook for executing operations
- * Matches RuntimeViewProviderValue.useExecuteOperationMutation contract:
- *   { controllerName, operationName, data, entityId? }
+ * Mutation hook for executing operations \u2014 handles both controllers
+ * and services. Pass either \`controllerName\` (for CRUD or custom
+ * controller actions) or \`serviceName\` (for RPC-style service ops).
+ *
+ * Matches RuntimeViewProviderValue.useExecuteOperationMutation contract.
+ * Service operations invalidate the \`services\` query key; controller
+ * operations invalidate the corresponding model's \`entities\` key so
+ * all mounted views refetch automatically.
  */
 export function useExecuteOperationMutation() {
   const queryClient = useQueryClient();
@@ -59,12 +65,14 @@ export function useExecuteOperationMutation() {
   return useMutation({
     mutationFn: ({
       controllerName,
+      serviceName,
       operationName,
       data,
       params,
       entityId
     }: {
-      controllerName: string;
+      controllerName?: string;
+      serviceName?: string;
       operationName: string;
       data?: Record<string, any>;
       params?: Record<string, any>;
@@ -73,11 +81,23 @@ export function useExecuteOperationMutation() {
       // Merge: accept both 'data' and 'params' for compatibility
       const mergedParams = { ...(data || params || {}) };
       if (entityId) mergedParams.id = entityId;
-      return executeOperation(controllerName, operationName, mergedParams);
+      if (serviceName) {
+        return executeServiceOperation(serviceName, operationName, mergedParams);
+      }
+      if (controllerName) {
+        return executeOperation(controllerName, operationName, mergedParams);
+      }
+      throw new Error('useExecuteOperationMutation: either controllerName or serviceName is required');
     },
     onSuccess: (_data, variables) => {
-      const modelName = variables.controllerName.replace(/Controller$/, '');
-      queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+      if (variables.controllerName) {
+        const modelName = variables.controllerName.replace(/Controller$/, '');
+        queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+      }
+      // Service operations aren't tied to a single entity type; no
+      // cache key to invalidate here. If a service mutation affects
+      // entities, the backend should publish an event that
+      // useEntitySync picks up via WebSocket.
     }
   });
 }

package/dist/libs/instance-factories/scaffolding/templates/generic/package-json-generator.js

@@ -29,6 +29,13 @@ function generatePackageJson(context) {
       "test": "npm test --workspaces",
       "test:backend": `npm test --workspace=${backendDir}`,
       "test:frontend": `npm test --workspace=${frontendDir}`,
+      // UI contract tests — auto-generated from spec inference rules.
+      // Assumes backend + frontend are already running (see docs/proposals/UI-CONTRACT-INFERENCE.md).
+      "test:contract": "playwright test --config=playwright.contract.config.ts",
+      // Implementation conformance — static grep-level checks that
+      // verify the runtime implementation has no escape hatches
+      // violating the design contract. Fast (millis), no browser.
+      "test:conformance": "node scripts/test-conformance.mjs",
       // Database management (backend)
       "db:setup": `npm run db:setup --workspace=${backendDir}`,
       "db:generate": `npm run db:generate --workspace=${backendDir}`,
@@ -39,6 +46,9 @@ function generatePackageJson(context) {
       "lint": "npm run lint --workspaces",
       "lint:fix": "npm run lint:fix --workspaces"
     };
+    pkg.devDependencies = {
+      "@playwright/test": "^1.40.0"
+    };
   } else {
     pkg.scripts = {
       ...aggregated.scripts,