cabloy 5.1.98 → 5.1.100

package/.cabloy-version

@@ -1 +1 @@
-5.1.98
+5.1.100

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync, statSync, writeFileSync, existsSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
@@ -21,6 +21,25 @@ interface SyncStateEntry {
   timestamp: number;
 }
 
+interface CommandPlan {
+  args: readonly string[];
+  display: string;
+}
+
+interface EditionConfig {
+  id: 'basic' | 'start';
+  label: string;
+  reverseVonaContentMarkers: readonly string[];
+  reverseAutoSyncCommands: readonly CommandPlan[];
+  reverseWebBuildCommand: string;
+}
+
+type ReverseSyncOutcome =
+  | { kind: 'not-applicable'; message: string }
+  | { kind: 'skipped'; message: string }
+  | { kind: 'success'; message: string }
+  | { kind: 'failure'; message: string };
+
 type SyncState = Record<string, SyncStateEntry>;
 
 const SCRIPT_FILE = fileURLToPath(import.meta.url);
@@ -45,13 +64,10 @@ 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',
+const SHARED_REVERSE_VONA_CONTENT_MARKERS = [
   'ZovaRender.',
   'tableActionRow(',
   'tableActionBulk(',
-  'ZovaRender.field(',
-  'ZovaRender.cell(',
 ];
 
 const REVERSE_ZOVA_PATH_MARKERS = ['/src/bean/', '/src/component/', '/src/.metadata/'];
@@ -64,6 +80,35 @@ const REVERSE_ZOVA_CONTENT_MARKERS = [
   '@Component<',
 ];
 
+const REVERSE_AUTO_SYNC_COMMANDS: readonly CommandPlan[] = [
+  { args: ['run', 'build:zova:admin'], display: 'npm run build:zova:admin' },
+  { args: ['run', 'deps:vona'], display: 'npm run deps:vona' },
+];
+
+const EDITION_CONFIGS: Record<'basic' | 'start', EditionConfig> = {
+  basic: {
+    id: 'basic',
+    label: 'Cabloy Basic',
+    reverseVonaContentMarkers: ['zova-rest-cabloy-basic-admin'],
+    reverseAutoSyncCommands: REVERSE_AUTO_SYNC_COMMANDS,
+    reverseWebBuildCommand: 'npm run build:zova:web',
+  },
+  start: {
+    id: 'start',
+    label: 'Cabloy Start',
+    reverseVonaContentMarkers: ['zova-rest-cabloy-start-admin'],
+    reverseAutoSyncCommands: REVERSE_AUTO_SYNC_COMMANDS,
+    reverseWebBuildCommand: 'npm run build:zova:web',
+  },
+};
+
+const ACTIVE_EDITION = resolveEdition();
+const FALLBACK_REVERSE_VONA_CONTENT_MARKERS = [
+  ...SHARED_REVERSE_VONA_CONTENT_MARKERS,
+  ...EDITION_CONFIGS.basic.reverseVonaContentMarkers,
+  ...EDITION_CONFIGS.start.reverseVonaContentMarkers,
+];
+
 function toPosixPath(value: string): string {
   return value.split(path.sep).join('/');
 }
@@ -78,6 +123,21 @@ function normalizePath(value?: string): string | null {
   }
 }
 
+function resolveEdition(): EditionConfig | null {
+  if (existsSync(path.resolve(ROOT, '__CABLOY_BASIC__'))) {
+    return EDITION_CONFIGS.basic;
+  }
+  if (existsSync(path.resolve(ROOT, '__CABLOY_START__'))) {
+    return EDITION_CONFIGS.start;
+  }
+  return null;
+}
+
+function getReverseVonaContentMarkers(edition: EditionConfig | null): readonly string[] {
+  if (!edition) return FALLBACK_REVERSE_VONA_CONTENT_MARKERS;
+  return [...SHARED_REVERSE_VONA_CONTENT_MARKERS, ...edition.reverseVonaContentMarkers];
+}
+
 function isCodeFile(filePath: string): boolean {
   return TARGET_PATTERNS.some(([prefix, suffix]) => filePath.includes(prefix) && filePath.endsWith(suffix));
 }
@@ -98,8 +158,12 @@ function detectForward(filePath: string, content: string): string | null {
   return null;
 }
 
-function detectReverse(filePath: string, content: string): string | null {
-  if (filePath.includes('/vona/src/') && containsAny(content, REVERSE_VONA_CONTENT_MARKERS)) {
+function detectReverse(
+  filePath: string,
+  content: string,
+  reverseVonaContentMarkers: readonly string[],
+): string | null {
+  if (filePath.includes('/vona/src/') && containsAny(content, reverseVonaContentMarkers)) {
     return 'Vona code is consuming frontend metadata or render resources.';
   }
   if (
@@ -112,10 +176,10 @@ function detectReverse(filePath: string, content: string): string | null {
   return null;
 }
 
-function analyze(filePath: string, content: string): AnalysisResult {
+function analyze(filePath: string, content: string, edition: EditionConfig | null): AnalysisResult {
   return {
     forwardReason: detectForward(filePath, content),
-    reverseReason: detectReverse(filePath, content),
+    reverseReason: detectReverse(filePath, content, getReverseVonaContentMarkers(edition)),
   };
 }
 
@@ -180,9 +244,9 @@ function markAutoSync(filePath: string): void {
   saveState(state);
 }
 
-function runNpm(args: string[]): SpawnSyncReturns<string> {
+function runNpm(args: readonly string[]): SpawnSyncReturns<string> {
   const command = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  return spawnSync(command, args, {
+  return spawnSync(command, [...args], {
     cwd: ROOT,
     encoding: 'utf8',
   });
@@ -205,22 +269,79 @@ function summarizeProcess(result: SpawnSyncReturns<string>): string {
   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)}`];
+function autoSyncReverse(filePath: string, edition: EditionConfig): ReverseSyncOutcome {
+  for (const command of edition.reverseAutoSyncCommands) {
+    const result = runNpm(command.args);
+    if (result.status !== 0) {
+      return {
+        kind: 'failure',
+        message: `Auto-sync failed during \`${command.display}\`: ${summarizeProcess(result)}`,
+      };
+    }
+  }
+
+  markAutoSync(filePath);
+  const commands = edition.reverseAutoSyncCommands.map(command => `\`${command.display}\``).join(' and ');
+  return {
+    kind: 'success',
+    message: `Auto-sync ran ${commands} for this ${edition.label} reverse-chain edit.`,
+  };
+}
+
+function buildReverseGuidance(edition: EditionConfig | null): string {
+  if (!edition) {
+    return 'If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable, resolve the active Cabloy edition marker before choosing the relevant Zova build and generated-output path, and then run `npm run deps:vona`.';
+  }
+
+  const autoSyncCommands = edition.reverseAutoSyncCommands
+    .map(command => `\`${command.display}\``)
+    .join(', then ');
+  return `If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable, run ${autoSyncCommands}, and also run \`${edition.reverseWebBuildCommand}\` when the Web flavor is affected in this ${edition.label} repo.`;
+}
+
+function resolveReverseSyncOutcome(
+  filePath: string,
+  result: AnalysisResult,
+  edition: EditionConfig | null,
+): ReverseSyncOutcome {
+  if (!result.reverseReason) {
+    return {
+      kind: 'not-applicable',
+      message: '',
+    };
   }
 
-  const depsResult = runNpm(['run', 'deps:vona']);
-  if (depsResult.status !== 0) {
-    return [false, `Auto-sync failed during \`npm run deps:vona\`: ${summarizeProcess(depsResult)}`];
+  if (!isHighConfidenceReverseSource(filePath)) {
+    return {
+      kind: 'not-applicable',
+      message:
+        'Auto-sync did not run because this reverse-chain signal came from the consumer side rather than a high-confidence frontend source edit.',
+    };
   }
 
-  markAutoSync(filePath);
-  return [true, 'Auto-sync ran `npm run build:zova:admin` and `npm run deps:vona` for this reverse-chain edit.'];
+  if (shouldSkipAutoSync(filePath)) {
+    return {
+      kind: 'skipped',
+      message: 'Auto-sync skipped because the same reverse-source edit was already synced recently in this repo.',
+    };
+  }
+
+  if (!edition) {
+    return {
+      kind: 'not-applicable',
+      message:
+        'Auto-sync did not run because the active Cabloy edition marker could not be resolved for this repo.',
+    };
+  }
+
+  return autoSyncReverse(filePath, edition);
 }
 
-function buildMessages(filePath: string, result: AnalysisResult): string {
+function buildMessages(
+  result: AnalysisResult,
+  edition: EditionConfig | null,
+  reverseSyncOutcome: ReverseSyncOutcome,
+): string {
   const messages = ["Contract-loop gate: this change may affect Cabloy's bidirectional contract loop."];
 
   if (result.forwardReason) {
@@ -233,30 +354,15 @@ function buildMessages(filePath: string, result: AnalysisResult): string {
   }
 
   if (result.reverseReason) {
-    messages.push(
-      `Reverse chain: ${result.reverseReason} If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable, run the relevant Zova build first, and then run \`npm run deps:vona\` for the Cabloy Basic path. Use \`npm run build:zova:admin\` for Admin changes, and also run \`npm run build:zova:web\` when the Web flavor is affected.`,
-    );
-    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(`Reverse chain: ${result.reverseReason} ${buildReverseGuidance(edition)}`);
+    if (reverseSyncOutcome.message) {
+      messages.push(reverseSyncOutcome.message);
+    }
+    if (reverseSyncOutcome.kind === 'failure') {
       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.',
+        '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.',
       );
     }
-    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(' ');
@@ -277,10 +383,11 @@ function runClaudeHook(): number {
   const content = readText(filePath);
   if (content === null) return 0;
 
-  const result = analyze(filePath, content);
+  const result = analyze(filePath, content, ACTIVE_EDITION);
   if (!hasSignal(result)) return 0;
 
-  const message = buildMessages(filePath, result);
+  const reverseSyncOutcome = resolveReverseSyncOutcome(filePath, result, ACTIVE_EDITION);
+  const message = buildMessages(result, ACTIVE_EDITION, reverseSyncOutcome);
   console.log(
     JSON.stringify({
       hookSpecificOutput: {

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 5.1.100
+
+### Improvements
+
+- Refresh the Zova lockfile after compensation rerun preparation.
+- Refresh the Vona `zova-core` patch for v5.1.77.
+
+## 5.1.99
+
+### Features
+
+- Add dossier files to training records.
+- Derive dossier file policy from the file scene.
+
+### Improvements
+
+- Rename and standardize `QueryAutoLoad` helpers.
+- Use `QueryAutoLoad` for upload policy handling.
+- Simplify the contract loop hook.
+- Share Claude assets across editions.
+- Split permission cache beans for clearer responsibility.
+- Clarify permission action method names.
+- Align default permission guard evaluation.
+- Reuse derived upload policy state.
+- Streamline upload policy queries.
+- Derive image policy from the image scene.
+- Generate the file SDK and move policy state into the model.
+
 ## 5.1.98
 
 ### Features

package/CLAUDE.md

@@ -53,6 +53,8 @@ Before inventing a custom implementation path:
 - For frontend work, assume Cabloy Basic and Cabloy Start share a frontend engineering layer but may diverge in UI layer, frontend flavors, suite/module availability, SSR site baselines, project assets, and generated outputs.
 - For Zova frontend analysis, do not default to generic Vue reinterpretation first. Read the code through Zova’s controller / bean / IoC architecture before mapping it to Vue concepts.
 - For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `cabloy-docs/frontend/` before doing framework-neutral reinterpretation.
+- For frontend async state that affects rendering or interaction across consumers, prefer model-owned `$useStateData(...)` over controller-managed fetch/cache state.
+- Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; if strict readiness is needed later, wait explicitly at the interaction boundary.
 - Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
 - For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
 - In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.

package/cabloy-docs/.vitepress/config.mjs

@@ -485,6 +485,10 @@ export default defineConfig({
               text: 'Resource Models & CRUD',
               items: [
                 { text: 'Model State Guide', link: '/frontend/model-state-guide' },
+                {
+                  text: '`$useStateData` Best Practices',
+                  link: '/frontend/use-state-data-best-practices',
+                },
                 {
                   text: 'Model Resource Owner Pattern',
                   link: '/frontend/model-resource-owner-pattern',

package/cabloy-docs/backend/controller-aop-guide.md

@@ -93,7 +93,6 @@ Typical jobs include:
 ```typescript
 @Passport.public()
 @Passport.activated(false)
-@Passport.userName({ name: 'admin' })
 @Passport.roleName({ name: 'admin' })
 @Passport.admin()
 ```

package/cabloy-docs/frontend/a-openapi-under-the-hood.md

@@ -131,7 +131,7 @@ The source confirms that:
 
 - bootstrap data is loaded first
 - permissions are then loaded through `getPermissions(resource)`
-- on the server, permissions are autoloaded as part of the bootstrap path
+- on the server, permissions are ensured loaded as part of the bootstrap path
 - on the client, permission queries are refetched when needed
 
 That means bootstrap and permissions are part of the same lower-level OpenAPI/runtime ladder, not unrelated utilities.

package/cabloy-docs/frontend/generated-contract-consumption-entry-branch.md

@@ -121,7 +121,7 @@ Representative source facts:
 
 - the page resolves `$$modelResource` from the route resource
 - it derives `formMeta` from `formScene`
-- it autoloads `this.$$modelResource.getFormApiSchemas(this.formMeta)?.sdk`
+- it ensures `this.$$modelResource.getFormApiSchemas(this.formMeta)?.sdk` is loaded
 - it derives `formSchema` from `this.$$modelResource.getFormSchema(this.formMeta)`
 
 This is the entry-shell boundary:

package/cabloy-docs/frontend/generated-contract-consumption-list-branch.md

@@ -94,7 +94,7 @@ The clearest current list shell is:
 Representative source facts:
 
 - the page resolves `$$modelResource` from the route resource
-- `__init__()` autoloads `this.$$modelResource.apiSchemasSelect.sdk`
+- `__init__()` ensures `this.$$modelResource.apiSchemasSelect.sdk` is loaded
 - render reads `schemaRow?.rest?.blocks`
 
 This is the list-shell boundary:

package/cabloy-docs/frontend/generated-contract-consumption-verify-playbook.md

@@ -117,7 +117,7 @@ Primary anchors:
 What to prove:
 
 - the list route shell resolves the expected `resource`
-- `apiSchemasSelect.sdk` still autoloads where expected
+- `apiSchemasSelect.sdk` is still ensured loaded where expected
 - `schemaRow`, `schemaFilter`, and list data flow are still exposed correctly
 - `basic-page:blockPage` still becomes the deeper list runtime owner
 

package/cabloy-docs/frontend/model-resource-owner-pattern.md

@@ -162,7 +162,7 @@ protected async __init__(resource: string) {
 And `_bootstrap()` uses:
 
 ```typescript
-const queryBootstrap = await $QueryAutoLoad(() => this.$sdk.getBootstrap(this.resource));
+const queryBootstrap = await $QueryEnsureLoaded(() => this.$sdk.getBootstrap(this.resource));
 ```
 
 Then it resolves:

package/cabloy-docs/frontend/model-state-guide.md

@@ -10,6 +10,8 @@ If you specifically want the scalable resource-facade pattern, continue with [Mo
 
 If you want the generic lower-level model runtime beneath these helper families, continue with [A-Model Under the Hood](/frontend/a-model-under-the-hood).
 
+If your main question is how to design and review `$useStateData(...)` usage itself, continue with [`$useStateData` Best Practices](/frontend/use-state-data-best-practices).
+
 If you want to understand how that owner pattern expands into the whole `rest-resource` module runtime, continue with [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood), then [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map).
 
 If you want to apply that pattern in your own module with a more uniform two-usage model, continue with [Using `ModelResource` in Your Module](/frontend/model-resource-usage-guide).
@@ -346,7 +348,7 @@ A plain CRUD helper usually forwards requests.
 
 It owns several resource-level concerns together:
 
-- bootstrap of resource metadata through `$QueryAutoLoad(...)`
+- bootstrap of resource metadata through `$QueryEnsureLoaded(...)`
 - resolution of the final `resourceApi`
 - permissions lookup
 - OpenAPI schema access for view/create/update/select

package/cabloy-docs/frontend/resource-entry-page-deep-dive.md

@@ -110,7 +110,7 @@ Its main jobs are:
 - derive `formMeta`
 - resolve `formProvider`
 - resolve `formSchema`
-- autoload form API schemas
+- ensure form API schemas are loaded
 - render `formSchema?.rest?.blocks`
 
 This is the first key architectural boundary:
@@ -154,7 +154,7 @@ Its main jobs are:
 - derive `formMeta` and `schemaScene`
 - derive `formProvider`, `formSchema`, and `formData`
 - prepare the shared JSX render context
-- autoload view/query data
+- ensure view/query data is loaded
 - own submit flow through `submitData(...)`
 - update page meta through `setPageMeta(...)`
 - expose `$$pageEntry` into the render context for downstream blocks

package/cabloy-docs/frontend/resource-list-page-deep-dive.md

@@ -102,7 +102,7 @@ zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controlle
 Its main jobs are:
 
 - resolve the current selector-backed `ModelResource`
-- autoload select API schemas
+- ensure select API schemas are loaded
 - read `schemaRow?.rest?.blocks`
 - render those blocks through `ZovaJsx`
 

package/cabloy-docs/frontend/rest-resource-source-reading-map.md

@@ -207,7 +207,7 @@ Read:
 This controller does three main things:
 
 1. resolves the selector-backed `ModelResource` instance from `this.$params.resource`
-2. autoloads `apiSchemasSelect.sdk`
+2. ensures `apiSchemasSelect.sdk` is loaded
 3. reads `schemaRow?.rest?.blocks` and renders those blocks through `ZovaJsx`
 
 The key point is what it does **not** do.
@@ -239,7 +239,7 @@ It mainly owns:
 - `formMeta` derivation
 - `formProvider` lookup from `ModelResource`
 - `formSchema` lookup from `ModelResource`
-- autoload of the form API schemas
+- ensuring the form API schemas are loaded
 - block rendering from `formSchema?.rest?.blocks`
 
 Again, the most important insight is what it does **not** fully own.

package/cabloy-docs/frontend/rest-resource-under-the-hood.md

@@ -98,7 +98,7 @@ Route record
                  └─ page-controller shell
                       ├─ resolves current resource / id / formScene
                       ├─ resolves selector-backed ModelResource
-                      ├─ autoloads top-level API schema surface
+                      ├─ ensures top-level API schema surface is loaded
                       └─ reads schemaRow.rest.blocks or formSchema.rest.blocks
                                │
                                ▼
@@ -255,7 +255,7 @@ zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controlle
 The main jobs of `ControllerPageResource` are:
 
 1. resolve the selector-backed model from `this.$params.resource`
-2. autoload the select API schema through `this.$$modelResource.apiSchemasSelect.sdk`
+2. ensure the select API schema is loaded through `this.$$modelResource.apiSchemasSelect.sdk`
 3. read `this.schemaRow?.rest?.blocks`
 4. render those blocks through `ZovaJsx`
 
@@ -291,7 +291,7 @@ The main jobs of `ControllerPageEntry` are:
 - derive `formMeta`
 - expose `formProvider` from the model
 - expose `formSchema` from the model
-- autoload the form API schemas
+- ensure the form API schemas are loaded
 - read `formSchema?.rest?.blocks`
 - render those blocks through `ZovaJsx`
 
@@ -366,7 +366,7 @@ That means one generic model class can serve many resources safely, because the
 Inside initialization, `_bootstrap()` calls:
 
 ```typescript
-$QueryAutoLoad(() => this.$sdk.getBootstrap(this.resource));
+$QueryEnsureLoaded(() => this.$sdk.getBootstrap(this.resource));
 ```
 
 and then resolves: