cabloy 5.1.59 → 5.1.61

package/.claude/hooks/contract-loop-gate.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+import { readFileSync, statSync, writeFileSync, existsSync } from 'node:fs';
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+interface HookPayload {
+  tool_input?: {
+    file_path?: string;
+  };
+}
+
+interface AnalysisResult {
+  forwardReason: string | null;
+  reverseReason: string | null;
+}
+
+interface SyncStateEntry {
+  fingerprint: string;
+  timestamp: number;
+}
+
+type SyncState = Record<string, SyncStateEntry>;
+
+const SCRIPT_FILE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(SCRIPT_FILE), '../..');
+const ROOT_KEY = toPosixPath(ROOT);
+const STATE_FILE = path.join(os.tmpdir(), 'cabloy-contract-loop-gate-state.json');
+const AUTO_SYNC_WINDOW_SECONDS = 300;
+
+const TARGET_PATTERNS: Array<readonly [string, string]> = [
+  ['zova/src/module/', '.ts'],
+  ['zova/src/module/', '.tsx'],
+  ['zova/src/module/', '.jsx'],
+  ['zova/src/suite/', '.ts'],
+  ['zova/src/suite/', '.tsx'],
+  ['zova/src/suite/', '.jsx'],
+  ['vona/src/', '.ts'],
+  ['vona/src/', '.tsx'],
+  ['vona/src/', '.jsx'],
+];
+
+const FORWARD_PATH_MARKERS = ['/controller/', '/dto/', '/entity/'];
+
+const FORWARD_CONTENT_MARKERS = ['@Web.', '@Api.field', '@Api.body', 'v.openapi(', '@Dto<'];
+
+const REVERSE_VONA_CONTENT_MARKERS = [
+  'zova-rest-cabloy-basic-admin',
+  'ZovaRender.',
+  'tableActionRow(',
+  'tableActionBulk(',
+  'ZovaRender.field(',
+  'ZovaRender.cell(',
+];
+
+const REVERSE_ZOVA_PATH_MARKERS = ['/src/bean/', '/src/component/', '/src/.metadata/'];
+
+const REVERSE_ZOVA_CONTENT_MARKERS = [
+  "declare module 'zova-module-a-openapi'",
+  'IResourceTableActionRowRecord',
+  '@TableCell<',
+  '@Component(',
+  '@Component<',
+];
+
+function toPosixPath(value: string): string {
+  return value.split(path.sep).join('/');
+}
+
+function normalizePath(value?: string): string | null {
+  if (!value) return null;
+  try {
+    const candidate = path.isAbsolute(value) ? value : path.join(ROOT, value);
+    return toPosixPath(path.resolve(candidate));
+  } catch {
+    return null;
+  }
+}
+
+function isCodeFile(filePath: string): boolean {
+  return TARGET_PATTERNS.some(([prefix, suffix]) => filePath.includes(prefix) && filePath.endsWith(suffix));
+}
+
+function containsAny(text: string, needles: readonly string[]): boolean {
+  return needles.some(needle => text.includes(needle));
+}
+
+function pathContainsAny(filePath: string, needles: readonly string[]): boolean {
+  return needles.some(needle => filePath.includes(needle));
+}
+
+function detectForward(filePath: string, content: string): string | null {
+  if (!filePath.includes('/vona/src/')) return null;
+  if (pathContainsAny(filePath, FORWARD_PATH_MARKERS) || containsAny(content, FORWARD_CONTENT_MARKERS)) {
+    return 'Backend contract source may have changed.';
+  }
+  return null;
+}
+
+function detectReverse(filePath: string, content: string): string | null {
+  if (filePath.includes('/vona/src/') && containsAny(content, REVERSE_VONA_CONTENT_MARKERS)) {
+    return 'Vona code is consuming frontend metadata or render resources.';
+  }
+  if (
+    filePath.includes('/zova/src/') &&
+    (pathContainsAny(filePath, REVERSE_ZOVA_PATH_MARKERS) ||
+      containsAny(content, REVERSE_ZOVA_CONTENT_MARKERS))
+  ) {
+    return 'Frontend-owned resources or metadata may affect backend consumers.';
+  }
+  return null;
+}
+
+function analyze(filePath: string, content: string): AnalysisResult {
+  return {
+    forwardReason: detectForward(filePath, content),
+    reverseReason: detectReverse(filePath, content),
+  };
+}
+
+function hasSignal(result: AnalysisResult): boolean {
+  return Boolean(result.forwardReason || result.reverseReason);
+}
+
+function isHighConfidenceReverseSource(filePath: string): boolean {
+  return filePath.includes('/zova/src/') && pathContainsAny(filePath, REVERSE_ZOVA_PATH_MARKERS);
+}
+
+function readText(filePath: string): string | null {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function loadState(): SyncState {
+  if (!existsSync(STATE_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, 'utf8')) as SyncState;
+  } catch {
+    return {};
+  }
+}
+
+function saveState(state: SyncState): void {
+  try {
+    writeFileSync(STATE_FILE, JSON.stringify(state), 'utf8');
+  } catch {
+    // ignore state persistence failures
+  }
+}
+
+function syncFingerprint(filePath: string): string {
+  try {
+    const stats = statSync(filePath, { bigint: true });
+    return `${filePath}:${stats.mtimeNs.toString()}`;
+  } catch {
+    return filePath;
+  }
+}
+
+function shouldSkipAutoSync(filePath: string): boolean {
+  const state = loadState();
+  const fingerprint = syncFingerprint(filePath);
+  const entry = state[ROOT_KEY];
+  if (!entry) return false;
+  if (entry.fingerprint !== fingerprint) return false;
+  if (Date.now() - entry.timestamp > AUTO_SYNC_WINDOW_SECONDS * 1000) return false;
+  return true;
+}
+
+function markAutoSync(filePath: string): void {
+  const state = loadState();
+  state[ROOT_KEY] = {
+    fingerprint: syncFingerprint(filePath),
+    timestamp: Date.now(),
+  };
+  saveState(state);
+}
+
+function runNpm(args: string[]): SpawnSyncReturns<string> {
+  const command = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return spawnSync(command, args, {
+    cwd: ROOT,
+    encoding: 'utf8',
+  });
+}
+
+function summarizeProcess(result: SpawnSyncReturns<string>): string {
+  if (result.error) {
+    return result.error.message;
+  }
+  const combined = [result.stdout?.trim(), result.stderr?.trim()].filter(Boolean).join('\n');
+  const exitCode = result.status ?? 1;
+  if (!combined) {
+    return `command exited with code ${exitCode}`;
+  }
+  const lines = combined
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean);
+  const tail = lines.slice(-3).join(' | ');
+  return `exit ${exitCode}: ${tail}`;
+}
+
+function autoSyncReverse(filePath: string): readonly [boolean, string] {
+  const buildResult = runNpm(['run', 'build:zova:admin']);
+  if (buildResult.status !== 0) {
+    return [false, `Auto-sync failed during \`npm run build:zova:admin\`: ${summarizeProcess(buildResult)}`];
+  }
+
+  const depsResult = runNpm(['run', 'deps:vona']);
+  if (depsResult.status !== 0) {
+    return [false, `Auto-sync failed during \`npm run deps:vona\`: ${summarizeProcess(depsResult)}`];
+  }
+
+  markAutoSync(filePath);
+  return [true, 'Auto-sync ran `npm run build:zova:admin` and `npm run deps:vona` for this reverse-chain edit.'];
+}
+
+function buildMessages(filePath: string, result: AnalysisResult): string {
+  const messages = ["Contract-loop gate: this change may affect Cabloy's bidirectional contract loop."];
+
+  if (result.forwardReason) {
+    messages.push(
+      `Forward chain: ${result.forwardReason} If backend contract truth changed, verify the emitted OpenAPI/contract output and regenerate the frontend consumer path before considering the task done.`,
+    );
+    messages.push(
+      'After forward regeneration, keep frontend follow-up thin: prefer semantic model facades and reuse the existing resource-owner when the custom API still belongs to the same resource.',
+    );
+  }
+
+  if (result.reverseReason) {
+    messages.push(
+      `Reverse chain: ${result.reverseReason} If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable, then run \`npm run build:zova:admin\` and \`npm run deps:vona\` for the Cabloy Basic Admin path.`,
+    );
+    if (isHighConfidenceReverseSource(filePath)) {
+      if (shouldSkipAutoSync(filePath)) {
+        messages.push('Auto-sync skipped because the same reverse-source edit was already synced recently in this repo.');
+      } else {
+        const [ok, detail] = autoSyncReverse(filePath);
+        messages.push(detail);
+        if (!ok) {
+          messages.push(
+            'Please review the failure before continuing. If generated artifacts already contain the expected changes but consumers still behave stale, suspect local dependency drift before making more source edits.',
+          );
+          return messages.join(' ');
+        }
+      }
+    } else {
+      messages.push(
+        'Auto-sync did not run because this reverse-chain signal came from the consumer side rather than a high-confidence frontend source edit.',
+      );
+    }
+    messages.push(
+      'For Cabloy Start, apply the same reverse-chain logic but resolve the Start-specific flavor names and generated-output paths from the active Start repo before executing edition-specific steps.',
+    );
+  }
+
+  return messages.join(' ');
+}
+
+function runClaudeHook(): number {
+  let payload: HookPayload;
+  try {
+    const raw = readFileSync(0, 'utf8');
+    payload = JSON.parse(raw) as HookPayload;
+  } catch {
+    return 0;
+  }
+
+  const filePath = normalizePath(payload.tool_input?.file_path);
+  if (!filePath || !isCodeFile(filePath)) return 0;
+
+  const content = readText(filePath);
+  if (content === null) return 0;
+
+  const result = analyze(filePath, content);
+  if (!hasSignal(result)) return 0;
+
+  const message = buildMessages(filePath, result);
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: message,
+      },
+      systemMessage: message,
+    }),
+  );
+  return 0;
+}
+
+process.exit(runClaudeHook());

package/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/contract-loop-gate.ts",
+            "statusMessage": "Checking contract-loop gate"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -15,6 +15,7 @@ After generating or extending a backend thread, check which follow-up layers app
 - OpenAPI metadata
 - inferred DTO opportunities
 - frontend contract impact
+- `@Api.field(...)` ordering when explicit zod schema is present: put `z.xxx(...)` last so later helpers do not get ignored
 
 ## Persistence follow-up
 

package/.claude/skills/cabloy-contract-loop/SKILL.md

@@ -5,18 +5,44 @@ description: Use this skill whenever a Cabloy task crosses the Vona-to-Zova cont
 
 # Cabloy Contract Loop
 
-Use this skill when a backend contract change needs to be reflected in frontend consumers, or when frontend consumers appear stale and you need to diagnose whether the backend contract loop is the real source of drift.
+Use this skill when a backend contract change needs to be reflected in frontend consumers, when frontend-owned metadata or resources need to be reflected back into backend consumers, or when either side appears stale and you need to diagnose where drift actually lives.
+
+Read the public [Contract Loop Playbook](../../../cabloy-docs/fullstack/contract-loop-playbook.md) for the canonical bidirectional model. This skill is the branching orchestration guide.
+
+## Important recovery note for stale local file consumers
+
+When generated `.zova-rest` output or other generated consumer artifacts already contain the expected new keys or types but Vona still behaves as if old consumer types are installed, treat that first as a local file-dependency installation problem rather than a source-editing problem.
+
+This includes the reverse fullstack direction where newly added frontend resources such as custom renderers are later consumed by backend metadata.
+
+In that situation:
+
+1. run the normal sync or regeneration flow first
+2. if Vona consumes newly added or changed Zova Admin render/action/metadata in Cabloy Basic, run `npm run build:zova:admin` from the repo root before anything else
+3. otherwise, if the change only affects flavor-built REST/type output, rebuild the relevant Zova flavor output first
+4. run `deps:vona`
+5. if stale behavior remains, rebuild `vona/node_modules` and reinstall dependencies
+
+Do not keep debugging source-level contract or renderer changes until the local file-package installation state is known to be healthy.
+
+## Current safeguard behavior in this repo
+
+- there is no contract-loop pre-commit gate in the current repo workflow
+- the active safeguard lives in the Claude `PostToolUse` hook configured in `.claude/settings.json`
+- for high-confidence reverse-chain source edits on the Zova side, the hook auto-runs `npm run build:zova:admin` and then `npm run deps:vona`
+- forward-chain detections remain reminder-only, so backend contract changes still require deliberate regeneration and verification
+- consumer-side reverse signals remain reminder-only, so do not assume every reverse-chain case auto-syncs itself
 
 ## Goals
 
 1. detect whether the active repository is Cabloy Basic or Cabloy Start
 2. classify whether the task truly crosses the backend/frontend contract boundary
-3. support both forward contract changes and reverse stale-consumer detection
+3. route the task into one of four modes: forward chain, reverse chain, consumer drift diagnosis, or local dependency drift recovery
 4. keep the workflow contract-first instead of hand-patching generated frontend types or services
 5. prefer CLI-first regeneration paths on both Vona and Zova sides
 6. finish with end-to-end verification guidance that checks both contract production and consumption
 
-## Step 1: Detect repo and contract scope
+## Step 1: Detect repo, edition, and branch
 
 Check the repository root for these marker files:
 
@@ -31,9 +57,11 @@ Interpretation:
 
 Then classify whether the task is really a contract-loop task.
 
-Use this skill in two common entry modes.
+These four modes are shared across Cabloy Basic and Cabloy Start. Edition detection chooses the operational branch, but does not change the core contract-loop model.
+
+Use this skill in four common entry modes.
 
-### Mode A: forward contract change
+### Mode A: forward chain
 
 The user already changed or plans to change backend contract surfaces such as:
 
@@ -44,7 +72,18 @@ The user already changed or plans to change backend contract surfaces such as:
 - OpenAPI metadata
 - inferred DTO or ORM DTO output that affects API consumers
 
-### Mode B: reverse stale-consumer detection
+### Mode B: reverse chain
+
+The user changed or plans to change frontend-owned resources or metadata that backend-side tooling or metadata will later consume, such as:
+
+- routes
+- components
+- icons
+- custom form-field resources
+- custom table-cell resources
+- generated frontend metadata that backend `ZovaRender.*(...)` references depend on
+
+### Mode C: consumer drift diagnosis
 
 The user reports symptoms on the frontend side such as:
 
@@ -53,7 +92,11 @@ The user reports symptoms on the frontend side such as:
 - API/model consumers no longer matching backend reality
 - hand-patched frontend types that seem to drift from backend truth
 
-In this mode, first diagnose whether the frontend is stale because the backend contract changed and the regeneration loop was skipped.
+In this mode, first diagnose whether the visible stale behavior comes from skipped regeneration, a wrong source-of-truth edit, or a stale generated consumer.
+
+### Mode D: local dependency drift recovery
+
+Use this mode when generated artifacts already contain the expected keys, types, or resources, but installed local file dependencies still behave stale after the normal sync flow.
 
 If the task is only backend scaffolding or only frontend scaffolding, the more specialized scaffold skills may be the better primary choice.
 
@@ -71,12 +114,13 @@ For deeper reference material, read:
 
 - `references/contract-loop-map.md`
 - `references/verification-checklist.md`
+- `references/resource-custom-state-pattern.md`
 
 ## Step 3: Identify the contract source of truth deliberately
 
-In Cabloy, the backend is often the source of truth for the contract. Treat that as the default unless the codebase clearly shows a generated or schema-owned frontend artifact that should be regenerated from backend output.
+In Cabloy, the backend is often the source of truth for the contract. Treat that as the default unless the codebase clearly shows a frontend-owned artifact that the reverse chain should hand back into backend consumers.
 
-### If this is a forward change
+### If this is the forward chain
 
 Start with the backend side and update the contract deliberately.
 
@@ -93,16 +137,37 @@ The key rule is:
 
 - do **not** patch frontend consumers first if the backend contract is the real source of truth
 
-### If this is reverse stale-consumer detection
+### If this is the reverse chain
+
+Start with the frontend-owned resource or metadata that backend consumers later depend on.
 
-Do not assume the frontend is the right place to fix the problem.
+Typical frontend layers to inspect or change include:
+
+- routes
+- components
+- icons
+- custom form-field resources
+- custom table-cell resources
+- generated metadata that backend `ZovaRender.*(...)` references depend on
+
+The key rule is:
+
+- do **not** treat this as frontend-only cleanup if backend consumers depend on the generated handoff
+
+### If this is consumer drift diagnosis
+
+Do not assume the visible stale behavior identifies the wrong layer automatically.
 
 Instead:
 
-1. inspect what frontend artifact looks stale
+1. inspect what artifact looks stale
 2. identify whether that artifact is generated, schema-driven, or hand-authored
-3. inspect the backend contract source that should feed it
-4. only then decide whether the fix is regeneration, backend correction, or a genuine frontend bug
+3. inspect the source layer that should feed it
+4. only then decide whether the fix is regeneration, source correction, consumer alignment, or a genuine bug
+
+### If this is local dependency drift recovery
+
+Only enter this branch after the source layer and generated handoff are already known to be correct.
 
 ## Step 4: Verify backend contract output before touching frontend consumers
 
@@ -114,6 +179,7 @@ That may include:
 - confirming DTO and validation alignment
 - checking Swagger/OpenAPI output
 - confirming that the changed endpoint or schema now reflects the intended contract
+- if local OpenAPI generation depends on a running Swagger source, starting the backend service first — in Cabloy Basic, `npm run dev` is the normal path and exposes `http://localhost:7102/swagger/json?version=V31`
 
 If the backend contract output is wrong, frontend regeneration will only spread the mistake.
 
@@ -130,6 +196,13 @@ Typical Zova commands include:
 - `npm run zova :openapi:config ...`
 - `npm run zova :openapi:generate ...`
 
+Preflight reminder:
+
+- if `:openapi:generate` reads from a local Swagger endpoint, do not assume the generator itself is broken when fetch fails
+- first start the backend service, typically with `npm run dev`, and confirm `http://localhost:7102/swagger/json?version=V31` is reachable
+
+When the target is a module-local SDK, constrain `openapi.config.ts` with `operations.match` unless the module intentionally owns a broad API surface. This prevents unrelated APIs from being generated into the module.
+
 ### Path B: REST/type generation by flavor
 
 Use the edition-specific Zova REST/type build path when the workflow depends on the built flavor outputs.
@@ -139,6 +212,15 @@ Typical examples in Cabloy Basic include:
 - `cd zova && npm run build:rest:cabloyBasicAdmin`
 - `cd zova && npm run build:rest:cabloyBasicWeb`
 
+Important Cabloy Basic reverse-sync rule:
+
+- if Vona consumes newly added or changed Zova Admin render/action/metadata, do **not** stop at `build:rest:cabloyBasicAdmin`
+- run `npm run build:zova:admin` from the repo root instead, then run `npm run deps:vona`
+- treat this as a JS-bundle-plus-rest-output handoff, not a rest-types-only refresh
+- the current repo safeguard may auto-run those two commands for high-confidence Zova reverse-source edits, but only as a convenience layer on top of the contract-loop model
+- if the change was consumer-side, low-confidence, cross-edition, or happened outside the Claude hook path, run the reverse sync flow deliberately yourself
+- prefer visible proof under `zova/src/**/.metadata/**` when it is available; if the effective handoff only appears in `.zova-rest`, treat the safeguard as conservative reminder/auto-sync assistance rather than strict proof
+
 For Cabloy Start, verify the exact Start-specific flavor names, paths, SSR site baselines, and project assets in the licensed Start repo.
 
 ### Path C: Downstream frontend alignment
@@ -150,6 +232,13 @@ After generation, inspect whether the frontend still needs follow-up in:
 - schema-driven UI
 - page or component assumptions
 
+Keep frontend follow-up thin:
+
+- use thin semantic model facades over generated consumers instead of re-declaring the contract
+- if a custom endpoint still belongs to an existing resource, prefer one resource-state owner instead of letting a module-local model create a second cache tree
+
+Reuse the resource-owned custom state pattern in `references/resource-custom-state-pattern.md`.
+
 ## Step 6: Keep edition-aware differences explicit
 
 The collaboration model is shared across Basic and Start, but the operational details may differ.

package/.claude/skills/cabloy-contract-loop/references/contract-loop-map.md

@@ -2,9 +2,16 @@
 
 Use this reference when a task crosses the backend/frontend contract boundary.
 
+This map is symmetric across Cabloy Basic and Cabloy Start. Detect the active edition to choose commands and output paths, but keep the same four-way diagnosis model:
+
+- forward chain
+- reverse chain
+- consumer drift
+- local dependency drift
+
 ## Typical triggers
 
-### Backend contract changed
+### Forward chain
 
 Common examples:
 
@@ -19,28 +26,135 @@ Likely next step:
 - verify backend OpenAPI output
 - regenerate the frontend consumer path
 
-### Frontend consumer drift
+### Reverse chain
+
+Common examples:
+
+- backend metadata now references a new frontend table cell or form field
+- routes, components, or icons changed and backend-side tooling depends on them
+- frontend-generated metadata needs to be consumed back into Vona
+
+Likely next step:
+
+- regenerate frontend metadata or build output
+- run the correct flavor build for the active edition
+- run `deps:vona`
+
+### Consumer drift
 
 Common examples:
 
-- generated SDK no longer matches backend
+- generated SDK no longer matches visible frontend behavior
 - schema-driven UI expects old shape
 - model or API service types are stale
 
 Likely next step:
 
-- confirm whether backend contract really changed
-- regenerate instead of hand-patching
+- confirm whether source truth or generated output really changed
+- regenerate instead of hand-patching when the generated layer is the stale one
+
+### Local dependency drift
+
+Common examples:
+
+- generated artifacts already contain the expected change
+- normal sync already ran
+- installed local file consumers still behave stale
+
+Likely next step:
+
+- stop editing source files
+- repair install state only after proving the earlier stages are healthy
+
+## Module-local OpenAPI generation boundary
+
+When generating a module-local OpenAPI SDK, do not leave the module config effectively unconstrained if the module should only own a narrow resource surface.
+
+Preferred rule:
+
+- set `operations.match` in `openapi.config.ts` so the module generates only the intended API operations
+
+Reason:
+
+- an unconstrained or overly broad generation pass can pull unrelated APIs into the module
+- that expands generated SDK files, metadata exports, and downstream type surfaces far beyond the module’s real ownership boundary
+- the result may still compile, but it weakens module boundaries and makes maintenance harder
+
+Representative example:
+
+- a module-level OpenAPI config such as `zova/src/module/demo-student/cli/openapi.config.ts`
+- narrow the generated surface with a module-specific matcher such as `operations.match: [/^DemoStudent_*/]`
+
+Treat that module path as an example, not as a durable dependency of the rule. The durable rule is to align `operations.match` with the module’s true API ownership boundary.
+
+Practical check after generation:
+
+- confirm the generated API files only contain the intended resource operations
+- confirm the module metadata and exports were not polluted by unrelated APIs
+
+## Forward chain artifact map
+
+1. backend contract source
+   - controllers
+   - DTOs
+   - entities
+   - validation rules
+   - OpenAPI metadata
+2. emitted proof surface
+   - Swagger/OpenAPI output
+3. generated handoff
+   - generated SDK
+   - schema-aware helpers
+   - flavor-built REST output when needed
+4. consumer layers
+   - frontend API files
+   - thin model facades
+   - schema-driven UI
+   - row and page actions
+
+## Reverse chain artifact map
+
+1. frontend contract source
+   - routes
+   - components
+   - icons
+   - custom table cells
+   - custom form-field resources
+   - module metadata
+2. generated handoff
+   - metadata output
+   - flavor build output
+3. sync surface
+   - `deps:vona`
+4. consumer layers
+   - backend `ZovaRender.*(...)` references
+   - backend tooling and type hints
+   - SSR or integration paths that depend on refreshed frontend output
+
+## Drift diagnosis matrix
+
+### Source wrong
+
+- wrong layer was edited
+- emitted or generated output is therefore wrong
+- fix the contract source first
+
+### Generated output wrong
+
+- source is correct, but generation did not run or ran on the wrong boundary
+- regenerate rather than hand-patch consumers
+
+### Consumer stale
 
-## Shared rule
+- generated output is correct, but the next consumer layer is still reading old expectations
+- inspect the consumer path before changing source again
 
-The sequence is usually:
+### Install stale
 
-1. change backend contract
-2. verify backend contract output
-3. regenerate frontend artifacts
-4. inspect frontend consumers
-5. verify end to end
+- generated output is correct
+- normal sync already ran
+- local file dependencies still behave stale
+- repair install state only after proving the earlier stages are healthy
 
 ## Anti-pattern