@quazardous/qdadm 2.2.0 → 2.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/components/layout/PageHeader.vue

@@ -20,6 +20,7 @@
  */
 import { computed, inject, type Ref } from 'vue'
 import Tag from 'primevue/tag'
+import type { ButtonSeverity } from '../../types'
 
 interface TitleParts {
   simple?: string
@@ -30,7 +31,7 @@ interface TitleParts {
 
 interface BadgeConfig {
   label: string
-  severity?: string
+  severity?: ButtonSeverity
 }
 
 interface Props {
@@ -80,7 +81,7 @@ const hasDecoratedTitle = computed((): boolean => {
                 v-for="badge in badges"
                 :key="badge.label"
                 :value="badge.label"
-                :severity="(badge.severity as any) || 'secondary'"
+                :severity="badge.severity || 'secondary'"
                 class="entity-badge"
               />
               <template v-if="!effectiveTitleParts && !simpleTitle">{{ title }}</template>

package/src/components/layout/PageNav.vue

@@ -17,7 +17,7 @@
  */
 import { computed, watch, inject, type Ref } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
-import { getSiblingRoutes, getChildRoutes, type ModuleRoute, type ParentConfig } from '../../module/moduleRegistry'
+import { getSiblingRoutes, getChildRoutes, routeParamsSatisfied, type ModuleRoute, type ParentConfig } from '../../module/moduleRegistry'
 import { useOrchestrator } from '../../orchestrator/useOrchestrator.js'
 import type { EntityManager } from '../../entity/EntityManager'
 import type { EntityRecord } from '../../types'
@@ -70,12 +70,15 @@ const siblingNavlinks = computed<NavLink[]>(() => {
   const { entity: parentEntityName, param } = parentConfig.value
   const siblings = getSiblingRoutes(parentEntityName, param)
 
-  // Filter out action routes (create, edit) - they're not navigation tabs
+  // Filter out item-level routes (create, edit, show) — they're not
+  // navigation tabs — and any route whose required params aren't all
+  // available here (#1205: a child show route needs its own :id, which
+  // doesn't exist at list level; useLink would throw).
   const navRoutes = siblings.filter((r: ModuleRoute) => {
     const name = r.name || ''
     const path = r.path || ''
-    // Exclude routes ending with -create, -edit, -new or paths with /create, /edit, /new
-    return !name.match(/-(create|edit|new)$/) && !path.match(/\/(create|edit|new)$/)
+    if (name.match(/-(create|edit|new|show)$/) || path.match(/\/(create|edit|new)$/)) return false
+    return routeParamsSatisfied(path, route.params as Record<string, unknown>)
   })
 
   // Build navlinks with current route params
@@ -109,11 +112,14 @@ const childNavlinks = computed<NavLink[]>(() => {
   const children = getChildRoutes(entityName)
   if (children.length === 0) return []
 
-  // Filter out action routes (create, edit) - they're not navigation tabs
+  // Filter out item-level routes (create, edit, show) and any route whose
+  // required params aren't satisfiable from the parent id alone (#1205).
   const navRoutes = children.filter((r: ModuleRoute) => {
     const name = r.name || ''
     const path = r.path || ''
-    return !name.match(/-(create|edit|new)$/) && !path.match(/\/(create|edit|new)$/)
+    if (name.match(/-(create|edit|new|show)$/) || path.match(/\/(create|edit|new)$/)) return false
+    const parentParam = (r.meta?.parent as ParentConfig)?.param || currentManager?.idField || 'id'
+    return routeParamsSatisfied(path, { [parentParam]: entityId })
   })
 
   if (navRoutes.length === 0) return []

package/src/components/pages/LoginPage.vue

@@ -23,6 +23,7 @@ import Card from 'primevue/card'
 import InputText from 'primevue/inputtext'
 import Password from 'primevue/password'
 import Button from 'primevue/button'
+import type { OrchestratorLike } from '../../entity/EntityManager.interface'
 
 /**
  * Auth adapter interface
@@ -46,15 +47,8 @@ interface LoginResult {
 /**
  * Orchestrator interface
  */
-interface Orchestrator {
-  toast: {
-    success: (summary: string, detail?: string, emitter?: string) => void
-    error: (summary: string, detail?: string, emitter?: string) => void
-  }
-  signals: {
-    emit: (signal: string, payload: unknown) => void
-  }
-}
+// #1191 — shared structural view (was: local redeclaration)
+type Orchestrator = OrchestratorLike
 
 /**
  * App config interface
@@ -184,7 +178,7 @@ async function handleLogin(): Promise<void> {
     })
 
     // Emit auth:login signal for debug bar and other listeners
-    orchestrator?.signals.emit('auth:login', { user: result.user })
+    orchestrator?.signals?.emit('auth:login', { user: result.user })
     orchestrator?.toast.success(
       'Welcome',
       `Logged in as ${result.user?.username || result.user?.email || username.value}`,
@@ -202,7 +196,7 @@ async function handleLogin(): Promise<void> {
       || axiosError.message
       || 'Invalid credentials'
 
-    orchestrator?.signals.emit('auth:login:error', {
+    orchestrator?.signals?.emit('auth:login:error', {
       username: username.value,
       error: message,
       status: axiosError.response?.status

package/src/components/show/ShowPage.vue

@@ -44,6 +44,7 @@ import Button from 'primevue/button'
 import Message from 'primevue/message'
 import FieldGroups from '../item/FieldGroups.vue'
 import ShowField from './ShowField.vue'
+import type { ButtonSeverity } from '../../types'
 
 /**
  * Page title parts for PageHeader
@@ -61,7 +62,7 @@ interface ResolvedAction {
   name: string
   label: string
   icon?: string
-  severity?: string
+  severity?: ButtonSeverity
   isLoading: boolean
   isDisabled: boolean
   onClick: () => void | Promise<void>
@@ -110,7 +111,7 @@ const props = defineProps({
   titleParts: { type: Object as PropType<PageTitleParts | null>, default: null },
 
   // Custom badges from entity manager
-  badges: { type: Array as PropType<Array<{ label: string; severity?: string }>>, default: () => [] },
+  badges: { type: Array as PropType<Array<{ label: string; severity?: ButtonSeverity }>>, default: () => [] },
 
   // Fields (for auto-rendering - optional, can use #fields slot instead)
   fields: { type: Array as PropType<ResolvedFieldConfig[]>, default: () => [] },
@@ -200,7 +201,7 @@ const fetchErrorMessage = computed<string | null>(() => {
           :key="action.name"
           :label="action.label"
           :icon="action.icon"
-          :severity="(action.severity as any)"
+          :severity="action.severity"
           :loading="action.isLoading"
           :disabled="action.isDisabled"
           @click="action.onClick"
@@ -283,7 +284,7 @@ const fetchErrorMessage = computed<string | null>(() => {
                   :key="action.name"
                   :label="action.label"
                   :icon="action.icon"
-                  :severity="(action.severity as any)"
+                  :severity="action.severity"
                   :loading="action.isLoading"
                   :disabled="action.isDisabled"
                   @click="action.onClick"
@@ -344,7 +345,7 @@ const fetchErrorMessage = computed<string | null>(() => {
                 :key="action.name"
                 :label="action.label"
                 :icon="action.icon"
-                :severity="(action.severity as any)"
+                :severity="action.severity"
                 :loading="action.isLoading"
                 :disabled="action.isDisabled"
                 @click="action.onClick"

package/src/composables/useBareForm.ts

@@ -35,28 +35,14 @@ import { useDirtyState } from './useDirtyState'
 import { useUnsavedChangesGuard, type GuardDialogState } from './useUnsavedChangesGuard'
 import { useBreadcrumb, type BreadcrumbDisplayItem } from './useBreadcrumb'
 import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
+import type { EntityManagerLike, OrchestratorLike } from '../entity/EntityManager.interface'
+
+// #1191 — shared minimal structural views (was: local redeclarations)
+type EntityManager = EntityManagerLike
+type Orchestrator = OrchestratorLike
+
 
-/**
- * Entity manager interface (minimal for this composable)
- */
-interface EntityManager {
-  label?: string
-  labelField?: string
-  getEntityLabel: (data: unknown) => string
-}
 
-/**
- * Orchestrator interface
- */
-interface Orchestrator {
-  get: (entityName: string) => EntityManager
-  toast: {
-    success: (summary: string, detail?: string, emitter?: unknown) => void
-    error: (summary: string, detail?: string, emitter?: unknown) => void
-    warn: (summary: string, detail?: string, emitter?: unknown) => void
-    info: (summary: string, detail?: string, emitter?: unknown) => void
-  }
-}
 
 /**
  * Toast helper interface
@@ -171,7 +157,7 @@ export function useBareForm(options: UseBareFormOptions): UseBareFormReturn {
     const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator', null)
     if (orchestrator) {
       try {
-        manager = orchestrator.get(entity)
+        manager = orchestrator.get(entity) ?? null
       } catch {
         // Manager not found, continue without it
       }
@@ -237,7 +223,8 @@ export function useBareForm(options: UseBareFormOptions): UseBareFormReturn {
       return manager.getEntityLabel(formData)
     }
     if (typeof effectiveLabelField === 'function') {
-      return effectiveLabelField(formData)
+      // labelField's param is contravariant-`never` in the Like — safe to call
+      return (effectiveLabelField as (data: unknown) => string)(formData)
     }
     return (formData[effectiveLabelField as string] as string) || null
   }

package/src/composables/useChildPage.ts

@@ -15,6 +15,12 @@
 import { computed, inject, type ComputedRef } from 'vue'
 import { useRoute } from 'vue-router'
 import { useStackHydrator, type StackHydratorReturn } from '../chain/useStackHydrator'
+import type { EntityManagerLike, OrchestratorLike } from '../entity/EntityManager.interface'
+
+// #1191 — shared minimal structural views (was: local redeclarations)
+type EntityManager = EntityManagerLike
+type Orchestrator = OrchestratorLike
+
 
 /**
  * Parent config from route meta
@@ -28,21 +34,10 @@ interface ParentConfig {
 /**
  * Entity manager interface (subset used by child pages)
  */
-interface EntityManager {
-  idField: string
-  label?: string
-  labelPlural?: string
-  routePrefix?: string
-  getEntityLabel: (data: unknown) => string
-  getEntityBadges?: (data: unknown) => Array<{ label: string; severity?: string }>
-}
 
 /**
  * Orchestrator interface
  */
-interface Orchestrator {
-  get: (entityName: string) => EntityManager | null
-}
 
 /**
  * Return type for useChildPage

package/src/composables/useEntityItemFormPage.types.ts

@@ -10,20 +10,13 @@ import type { BreadcrumbDisplayItem } from './useBreadcrumb'
 import type { ParentConfig, EntityManager } from './useEntityItemPage'
 import type { FieldGroup, GroupDefinition, GroupOptions, MoveFieldPosition } from './useFieldManager'
 import type { StackHydratorReturn } from '../chain/useStackHydrator'
+import type { OrchestratorLike } from '../entity/EntityManager.interface'
 
 /**
  * Orchestrator interface
  */
-export interface Orchestrator {
-  get: (entityName: string) => EntityManager
-  toast?: {
-    success: (summary: string, detail?: string, emitter?: unknown) => void
-    error: (summary: string, detail?: string, emitter?: unknown) => void
-    warn: (summary: string, detail?: string, emitter?: unknown) => void
-    info: (summary: string, detail?: string, emitter?: unknown) => void
-    [key: string]: ((summary: string, detail?: string, emitter?: unknown) => void) | undefined
-  }
-}
+// #1191 — shared structural view, parameterized on the CRUD tier
+export type Orchestrator = OrchestratorLike<EntityManager>
 
 /**
  * Field definition from EntityManager schema

package/src/composables/useEntityItemPage.ts

@@ -16,6 +16,7 @@ import { ref, computed, onMounted, inject, provide, type Ref, type ComputedRef }
 import { useRoute } from 'vue-router'
 import { useStackHydrator, type StackHydratorReturn } from '../chain/useStackHydrator'
 import type { EntityManagerCrud } from '../entity/EntityManager.interface'
+import type { OrchestratorLike } from '../entity/EntityManager.interface'
 
 /**
  * Parent configuration from route.meta.parent
@@ -61,12 +62,8 @@ export interface CreateContext {
  */
 export type EntityManager = EntityManagerCrud
 
-/**
- * Orchestrator interface
- */
-interface Orchestrator {
-  get: (entityName: string) => EntityManager
-}
+// #1191 — shared structural view, parameterized on the CRUD tier
+type Orchestrator = OrchestratorLike<EntityManager>
 
 /**
  * Options for useEntityItemPage

package/src/composables/useEntityItemShowPage.ts

@@ -54,19 +54,10 @@ import {
   type ShowFieldDefinition,
   type ShowResolvedFieldConfig,
 } from './createShowFieldResolver'
+import type { OrchestratorLike } from '../entity/EntityManager.interface'
 
-/**
- * Orchestrator interface
- */
-interface Orchestrator {
-  get: (entityName: string) => EntityManager
-  toast?: {
-    success: (summary: string, detail?: string, emitter?: unknown) => void
-    error: (summary: string, detail?: string, emitter?: unknown) => void
-    warn: (summary: string, detail?: string, emitter?: unknown) => void
-    info: (summary: string, detail?: string, emitter?: unknown) => void
-  }
-}
+// #1191 — shared structural view (manager tier from useEntityItemPage)
+type Orchestrator = OrchestratorLike<EntityManager>
 
 /**
  * Field definition from EntityManager schema.

package/src/composables/useListPage.types.ts

@@ -7,7 +7,7 @@ import type { Ref, ComputedRef } from 'vue'
 import type { Router } from 'vue-router'
 import type { FilterQuery } from '../query/FilterQuery'
 import type { ParentConfig, UseEntityItemPageReturn } from './useEntityItemPage.js'
-import type { EntityManagerRead } from '../entity/EntityManager.interface'
+import type { EntityManagerRead, OrchestratorLike } from '../entity/EntityManager.interface'
 
 /**
  * Entity manager interface for list pages (re-export for convenience)
@@ -27,16 +27,8 @@ export interface ListResponse<T = unknown> {
 /**
  * Orchestrator interface
  */
-export interface Orchestrator {
-  get: (entityName: string) => EntityManager
-  toast: {
-    success: (summary: string, detail?: string, emitter?: unknown) => void
-    error: (summary: string, detail?: string, emitter?: unknown) => void
-    warn: (summary: string, detail?: string, emitter?: unknown) => void
-    info: (summary: string, detail?: string, emitter?: unknown) => void
-    [key: string]: ((summary: string, detail?: string, emitter?: unknown) => void) | undefined
-  }
-}
+// #1191 — shared structural view, parameterized on the Read tier
+export type Orchestrator = OrchestratorLike<EntityManager>
 
 /**
  * Toast helper interface

package/src/composables/useNavContext.ts

@@ -21,6 +21,12 @@ import { useRoute, useRouter, type RouteParamsRawGeneric } from 'vue-router'
 import { getSiblingRoutes } from '../module/moduleRegistry'
 import { useSemanticBreadcrumb, type SemanticBreadcrumbItem } from './useSemanticBreadcrumb'
 import { useStackHydrator, type HydratedLevel } from '../chain/useStackHydrator'
+import type { EntityManagerLike, OrchestratorLike } from '../entity/EntityManager.interface'
+
+// #1191 — shared minimal structural views (was: local redeclarations)
+type EntityManager = EntityManagerLike
+type Orchestrator = OrchestratorLike
+
 
 /**
  * Navigation chain segment types
@@ -44,20 +50,10 @@ export interface NavChainSegment {
 /**
  * Entity manager interface
  */
-interface EntityManager {
-  routePrefix?: string
-  labelPlural?: string
-  idField?: string
-  readOnly?: boolean
-  getEntityLabel: (data: unknown) => string
-}
 
 /**
  * Orchestrator interface
  */
-interface Orchestrator {
-  get: (entityName: string) => EntityManager | null
-}
 
 /**
  * Breadcrumb item
@@ -307,7 +303,7 @@ export function useNavContext(_options: UseNavContextOptions = {}): UseNavContex
         })
       } else if (segment.type === 'item') {
         const data = chainData.value.get(i)
-        const label = data && segment.manager ? segment.manager.getEntityLabel(data) : '...'
+        const label = (data && segment.manager ? segment.manager.getEntityLabel(data) : null) ?? '...'
         const idField = segment.manager?.idField || 'id'
 
         // Only create link if we have a valid id

package/src/composables/useNavigation.ts

@@ -15,6 +15,11 @@ import { getNavSections, alterMenuSections, isMenuAltered } from '../module/modu
 import { useSemanticBreadcrumb } from './useSemanticBreadcrumb'
 import { useI18n } from '../i18n/useI18n'
 import type { HookRegistry } from '../hooks/HookRegistry'
+import type { OrchestratorLike } from '../entity/EntityManager.interface'
+
+// #1191 — shared minimal structural view (was: local redeclaration)
+type Orchestrator = OrchestratorLike
+
 
 /**
  * Navigation item interface
@@ -39,17 +44,10 @@ export interface NavSection {
 /**
  * Entity manager interface
  */
-interface EntityManager {
-  canRead: () => boolean
-}
 
 /**
  * Orchestrator interface
  */
-interface Orchestrator {
-  signals?: unknown
-  get: (entityName: string) => EntityManager | null
-}
 
 /**
  * Return type for useNavigation

package/src/composables/useUserImpersonator.ts

@@ -37,7 +37,7 @@ import {
   type Ref,
   type ComputedRef,
 } from 'vue'
-import type { SignalBus } from '../kernel/SignalBus'
+import type { EntityManagerLike, OrchestratorLike } from '../entity/EntityManager.interface'
 
 /**
  * User record type
@@ -55,28 +55,18 @@ interface AuthAdapterWithImpersonation {
   getOriginalUser?: () => UserRecord | null
 }
 
-/**
- * Entity auth adapter interface
- */
-interface EntityAuthAdapter {
-  isGranted?: (permission: string) => boolean
-}
-
 /**
  * Orchestrator interface
  */
-interface Orchestrator {
-  signals?: SignalBus
-  entityAuthAdapter?: EntityAuthAdapter
-  get: (entityName: string) => EntityManager | null
+// #1191 — shared structural view + the impersonator's extra surface
+type ImpersonatorManager = EntityManagerLike & {
+  findAll?: () => Promise<{ data?: UserRecord[] } | UserRecord[]>
 }
+type Orchestrator = OrchestratorLike<ImpersonatorManager | null | undefined>
 
 /**
  * Entity manager interface
  */
-interface EntityManager {
-  findAll: () => Promise<{ data?: UserRecord[] } | UserRecord[]>
-}
 
 /**
  * Options for useUserImpersonator
@@ -214,7 +204,7 @@ export function useUserImpersonator(
         error.value = null
         const manager = orchestrator.get(entity)
         if (manager) {
-          const result = await manager.findAll()
+          const result = await manager.findAll?.()
           users.value =
             (result as { data?: UserRecord[] })?.data ||
             (result as UserRecord[]) ||

package/src/entity/EntityManager.cache.ts

@@ -90,7 +90,9 @@ export function applyCacheMethods(EntityManagerClass: { prototype: any }): void
   Object.defineProperty(proto, 'overflow', {
     get(this: Self): boolean {
       const cache = this._cache
-      return cache.valid && cache.total > cache.items.length
+      // overflowed: total exceeded effectiveThreshold, cache was never
+      // filled (#1204) — the cache is unusable either way.
+      return cache.overflowed === true || (cache.valid && cache.total > cache.items.length)
     },
     configurable: true,
   })
@@ -398,6 +400,7 @@ export function applyCacheMethods(EntityManagerClass: { prototype: any }): void
     cache.valid = false
     cache.items = []
     cache.total = 0
+    cache.overflowed = false
     cache.loadedAt = null
     this._cacheLoading = null
     // Also clear detail cache

package/src/entity/EntityManager.crud.ts

@@ -182,6 +182,7 @@ export function applyCrudMethods(EntityManagerClass: { prototype: any }): void {
         cache.items = items
         cache.total = total
         cache.valid = true
+        cache.overflowed = false
         cache.loadedAt = Date.now()
         // Resolve parent fields for search (book.title, user.username, etc.)
         await this._resolveSearchFields(items)
@@ -191,6 +192,11 @@ export function applyCrudMethods(EntityManagerClass: { prototype: any }): void {
         // Fire-and-forget: load full cache in background
         this._loadCacheInBackground()
       }
+    } else if (canUseCache && this.isCacheEnabled && total > this.effectiveThreshold) {
+      // Entity outgrew the threshold: the cache can never hold it. Mark it
+      // so query() stops filtering an empty cache and goes to the API
+      // instead of returning an empty list (#1204).
+      cache.overflowed = true
     }
 
     return { items, total, fromCache: false }

package/src/entity/EntityManager.interface.ts

@@ -15,6 +15,10 @@
  * that flows through to method signatures for typed entity data.
  */
 
+import type { EntityBadge } from './EntityManager.types'
+import type { SignalBus } from '../kernel/SignalBus'
+import type { EntityAuthAdapter } from './auth/EntityAuthAdapter'
+
 // ─── Base ────────────────────────────────────────────────────────────────────
 
 /**
@@ -76,3 +80,71 @@ export interface EntityManagerCrud<T = unknown> extends EntityManagerRead<T> {
   getSeverity?: (field: string, value: string | number, defaultSeverity?: string) => string
   getSeverityDescriptor?: (field: string, value: string | number, defaultSeverity?: string) => { severity: string; icon?: string; label?: string }
 }
+// ============================================================================
+// ASSIGNMENT-SAFE STRUCTURAL VIEWS (#1191)
+// ============================================================================
+//
+// Composables and components used to redeclare tiny local `EntityManager` /
+// `Orchestrator` interfaces (24 sites) because the canonical generics don't
+// assign across erased type parameters. These shared, non-generic views are
+// the single replacement: the canonical classes satisfy them structurally
+// (compile-time asserted in orchestrator/Orchestrator.ts), and consumers
+// declare exactly the surface they touch by intersecting when they need more.
+//
+// NOTE: members use METHOD syntax on purpose — TS keeps method parameters
+// bivariant (even under strictFunctionTypes), which is what lets
+// `EntityManager<T>` assign to the erased signatures below.
+
+/** Toast surface exposed by the orchestrator (structural ToastHelper). */
+export interface ToastLike {
+  success(summary: string, detail?: string, emitter?: unknown): void
+  error(summary: string, detail?: string, emitter?: unknown): void
+  warn(summary: string, detail?: string, emitter?: unknown): void
+  info(summary: string, detail?: string, emitter?: unknown): void
+}
+
+/**
+ * Minimal structural view of an EntityManager for composables/components.
+ * Every member exists on the canonical `EntityManager`; optionals reflect
+ * genuinely optional configuration.
+ */
+export interface EntityManagerLike {
+  idField: string
+  label?: string
+  labelPlural?: string
+  // Function-typed PROPERTY → strictly contravariant param; `never` is the
+  // contravariant top, so the canonical `(entity: T) => string` assigns.
+  // Cast at the call site when invoking.
+  labelField?: string | ((data: never) => string)
+  routePrefix?: string
+  readOnly?: boolean
+  getEntityLabel(data: unknown): string | null
+  getEntityBadges?(data: unknown): EntityBadge[]
+  canRead(entity?: unknown): boolean
+  canCreate(): boolean
+  canUpdate(entity?: unknown): boolean
+  canDelete(entity?: unknown): boolean
+  list(params?: Record<string, unknown>, context?: unknown): Promise<{
+    items: unknown[]
+    total?: number
+    fromCache?: boolean
+  }>
+  get(id: string | number, context?: unknown): Promise<unknown>
+  create(data: Record<string, unknown>, context?: unknown): Promise<unknown>
+  update(id: string | number, data: Record<string, unknown>, context?: unknown): Promise<unknown>
+  delete(id: string | number, context?: unknown): Promise<unknown>
+}
+
+/**
+ * Minimal structural view of the Orchestrator for composables/components.
+ * `get()` is typed nullable so consumers guard — the canonical class throws
+ * on unknown names, injected test doubles commonly return null.
+ */
+export interface OrchestratorLike<M = EntityManagerLike | null | undefined> {
+  get(name: string): M
+  has?(name: string): boolean
+  isRegistered?(name: string): boolean
+  toast: ToastLike
+  signals?: SignalBus | null
+  entityAuthAdapter?: EntityAuthAdapter | null
+}

package/src/entity/EntityManager.query.ts

@@ -31,7 +31,7 @@ export function applyQueryMethods(EntityManagerClass: { prototype: any }): void
     // Ensure cache is filled (via list) — skip for dynamic endpoints
     // since list() disables caching when resolveStorage provides an endpoint
     const cache = this._cache
-    if (!isDynamicEndpoint && !cache.valid && this.isCacheEnabled) {
+    if (!isDynamicEndpoint && !cache.valid && !cache.overflowed && this.isCacheEnabled) {
       await this.list(
         { page_size: this.effectiveThreshold },
         routingContext ?? undefined
@@ -40,8 +40,11 @@ export function applyQueryMethods(EntityManagerClass: { prototype: any }): void
 
     let result: ListResult<any>
 
-    // Dynamic endpoint, overflow, or cache disabled → use API directly
-    if (isDynamicEndpoint || this.overflow || !this.isCacheEnabled) {
+    // Dynamic endpoint, overflow, cache disabled, or cache still not
+    // valid (fill failed / threshold exceeded) → use API directly. The
+    // cache is an optional layer: it must never turn into an empty
+    // result when it can't hold the data (#1204).
+    if (isDynamicEndpoint || this.overflow || !this.isCacheEnabled || !cache.valid) {
       result = await this.list(params, routingContext ?? undefined)
     } else {
       // Full cache available - filter locally

package/src/entity/EntityManager.ts

@@ -114,6 +114,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     total: 0,
     loadedAt: null,
     valid: false,
+    overflowed: false,
   }
   protected _cacheLoading: Promise<boolean> | null = null
 

package/src/entity/EntityManager.types.ts

@@ -26,6 +26,8 @@ export interface CacheState<T> {
   total: number
   loadedAt: number | null
   valid: boolean
+  /** Entity total exceeded effectiveThreshold — cache can't hold it (#1204). */
+  overflowed?: boolean
 }
 
 /**
@@ -286,3 +288,4 @@ export type EntityManagerInternal<T extends EntityRecord = EntityRecord> = Entit
 // Re-export types used by helpers
 export type { EntityRecord, ListResult, IStorage, StorageCapabilities }
 export type { SignalBus, HookRegistry }
+

package/src/generated/managers/testManager.ts

@@ -1,46 +0,0 @@
-/**
- * TestManager - Auto-generated EntityManager
- *
- * Generated by qdadm/gen/generateManagers
- * DO NOT EDIT MANUALLY - Changes will be overwritten
- *
- * Entity: test
- * Endpoint: /test
- */
-
-import { EntityManager } from '@quazardous/qdadm'
-import type { EntityRecord } from '@quazardous/qdadm'
-import { ApiStorage } from '@quazardous/qdadm'
-
-export interface TestEntity extends EntityRecord {
-}
-
-/**
- * Schema definition for test
- */
-export const testSchema = {
-  name: "test",
-  endpoint: "/test",
-  fields: {}
-} as const
-
-/**
- * Storage options for test
- */
-const storageOptions = {
-  endpoint: "/test"
-}
-
-/**
- * TestManager instance
- *
- * Provides CRUD operations for test entity.
- */
-export const testManager = new EntityManager<TestEntity>({
-  ...{
-  name: "test",
-  idField: "id",
-  fields: {}
-},
-  storage: new ApiStorage<TestEntity>(storageOptions)
-})

package/src/kernel/Kernel.routing.ts

@@ -212,7 +212,11 @@ export function applyRoutingMethods(KernelClass: { prototype: any }): void {
       }
 
       const entity = to.meta?.entity as string | undefined
-      if (entity && this.orchestrator) {
+      // Entity not registered → nothing to check yet (e.g. child route
+      // declared before its manager loads) — allow. This is the ONLY
+      // allowed pass-through; a failing access check must fail CLOSED,
+      // not silently allow (#1190).
+      if (entity && this.orchestrator && this.orchestrator.isRegistered(entity)) {
         try {
           const manager = this.orchestrator.get(entity)
           if (manager && !manager.canRead()) {
@@ -232,8 +236,13 @@ export function applyRoutingMethods(KernelClass: { prototype: any }): void {
             next({ path: '/' })
             return
           }
-        } catch {
-          // Entity not registered - allow navigation
+        } catch (err) {
+          console.error(
+            `[qdadm] Access check failed for ${to.path} (entity: ${entity}) — denying navigation:`,
+            err
+          )
+          next({ path: '/' })
+          return
         }
       }
 

package/src/module/moduleRegistry.ts

@@ -442,6 +442,21 @@ export function getEntityConfig(name: string): EntityConfig | undefined {
  * @param parentParam - Parent route param
  * @returns Routes with matching parent config
  */
+/**
+ * Check that every REQUIRED `:param` in a route path is present (non-empty)
+ * in the given params. Used by PageNav to avoid building navlinks that
+ * vue-router's useLink would reject with "Missing required param" (#1205).
+ */
+export function routeParamsSatisfied(path: string, params: Record<string, unknown>): boolean {
+  const tokens = path.match(/:([A-Za-z0-9_]+)\??/g) || []
+  return tokens.every((token) => {
+    if (token.endsWith('?')) return true // optional param
+    const name = token.slice(1)
+    const value = params[name]
+    return value !== undefined && value !== null && value !== ''
+  })
+}
+
 export function getSiblingRoutes(parentEntity: string, parentParam: string): ModuleRoute[] {
   return routes.filter((route) => {
     const parent = route.meta?.parent

package/src/orchestrator/Orchestrator.ts

@@ -34,6 +34,7 @@ import type { EntityRecord } from '../types'
 import type { SignalBus } from '../kernel/SignalBus'
 import type { HookRegistry } from '../hooks/HookRegistry'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
+import type { EntityManagerLike, OrchestratorLike } from '../entity/EntityManager.interface'
 
 /**
  * DeferredRegistry interface (minimal for Orchestrator needs)
@@ -425,3 +426,16 @@ Example fix in your module:
 export function createOrchestrator(options?: OrchestratorOptions): Orchestrator {
   return new Orchestrator(options)
 }
+
+// ============================================================================
+// #1191 — compile-time guarantee that the canonical classes satisfy the
+// minimal structural views consumed across composables/components. If a
+// rename breaks the structural match, this is where the compiler complains.
+// ============================================================================
+type _AssertManagerLike<T extends EntityManagerLike> = T
+type _AssertOrchestratorLike<T extends OrchestratorLike> = T
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type _LikeChecks = [
+  _AssertManagerLike<EntityManager>,
+  _AssertOrchestratorLike<Orchestrator>,
+]

package/src/query/FilterQuery.ts

@@ -52,7 +52,7 @@ export interface FilterQueryOptions<T = unknown> {
   source: FilterQuerySource
   entity?: string | null
   field?: string | null
-  parentManager?: EntityManagerLike | null
+  parentManager?: QueryManagerLike | null
   label?: ValueResolver<T>
   value?: ValueResolver<T>
   transform?: ((options: FilterOption[]) => FilterOption[]) | null
@@ -62,7 +62,10 @@ export interface FilterQueryOptions<T = unknown> {
 /**
  * Minimal interface for EntityManager (to avoid circular deps)
  */
-interface EntityManagerLike {
+// #1191 note: FilterQuery deliberately keeps a self-contained duck type —
+// callers pass minimal mocks ({ _cache, list }) that the full
+// QueryManagerLike would reject. Not a drift case.
+interface QueryManagerLike {
   _cache?: unknown[]
   list(params?: { page_size?: number }): Promise<{ items: unknown[] }>
 }
@@ -70,8 +73,8 @@ interface EntityManagerLike {
 /**
  * Minimal interface for Orchestrator (to avoid circular deps)
  */
-interface OrchestratorLike {
-  get(name: string): EntityManagerLike | undefined
+interface QueryOrchestratorLike {
+  get(name: string): QueryManagerLike | null | undefined
 }
 
 /**
@@ -97,7 +100,7 @@ export class FilterQuery<T = unknown> {
   source: FilterQuerySource
   entity: string | null
   field: string | null
-  parentManager: EntityManagerLike | null
+  parentManager: QueryManagerLike | null
   label: ValueResolver<T>
   value: ValueResolver<T>
   transform: ((options: FilterOption[]) => FilterOption[]) | null
@@ -146,7 +149,7 @@ export class FilterQuery<T = unknown> {
   /**
    * Set the parent manager (called by useListPage for field source)
    */
-  setParentManager(manager: EntityManagerLike): this {
+  setParentManager(manager: QueryManagerLike): this {
     this.parentManager = manager
     return this
   }
@@ -211,7 +214,7 @@ export class FilterQuery<T = unknown> {
   /**
    * Get options for dropdown
    */
-  async getOptions(orchestrator: OrchestratorLike | null = null): Promise<FilterOption[]> {
+  async getOptions(orchestrator: QueryOrchestratorLike | null = null): Promise<FilterOption[]> {
     // Return cached options if available
     if (this._options !== null) {
       return this._options
@@ -248,7 +251,7 @@ export class FilterQuery<T = unknown> {
   /**
    * Fetch items from entity manager
    */
-  private async _fetchFromEntity(orchestrator: OrchestratorLike | null): Promise<unknown[]> {
+  private async _fetchFromEntity(orchestrator: QueryOrchestratorLike | null): Promise<unknown[]> {
     if (!orchestrator) {
       throw new Error('FilterQuery: orchestrator is required for entity source')
     }

package/src/security/EntityRolesProvider.ts

@@ -5,6 +5,7 @@ import type {
   RoleHierarchyMap,
   RoleProviderContext,
 } from './RolesProvider'
+import type { EntityManagerLike, OrchestratorLike } from '../entity/EntityManager.interface'
 
 /**
  * Options for EntityRoleProvider
@@ -28,19 +29,13 @@ interface RoleEntity {
 /**
  * Entity manager interface (minimal for adapter needs)
  */
-interface EntityManager {
-  list(params?: Record<string, unknown>): Promise<{ items: RoleEntity[]; data?: RoleEntity[] }>
-  create(data: Record<string, unknown>): Promise<RoleEntity>
-  update(id: string | number, data: Record<string, unknown>): Promise<RoleEntity>
-  delete(id: string | number): Promise<void>
-}
+// #1191 — shared structural view; role-typed results are cast at call sites
+type EntityManager = EntityManagerLike
 
 /**
  * Orchestrator interface (minimal for adapter needs)
  */
-interface Orchestrator {
-  get(name: string): EntityManager | undefined
-}
+type Orchestrator = OrchestratorLike
 
 /**
  * Cache structure for roles
@@ -162,7 +157,7 @@ export class EntityRoleProvider extends RoleProvider {
     }
 
     try {
-      const { items: roles } = await manager.list({ page_size: 1000 })
+      const { items: roles } = (await manager.list({ page_size: 1000 })) as { items: RoleEntity[] }
 
       // Build cache
       const permissions: Record<string, string[]> = {}
@@ -317,7 +312,7 @@ export class EntityRoleProvider extends RoleProvider {
       [this._permissionsField]: permissions,
       [this._inheritsField]: inherits,
     }
-    const result = await manager.create(data)
+    const result = (await manager.create(data)) as RoleEntity
     this.invalidate()
     return result
   }
@@ -334,10 +329,10 @@ export class EntityRoleProvider extends RoleProvider {
     const manager = this._getManager()
 
     // Find the role entity by name
-    const response = await manager.list({
+    const response = (await manager.list({
       filter: { [this._nameField]: name },
       limit: 1,
-    })
+    })) as { items: RoleEntity[]; data?: RoleEntity[] }
     const roles = response.data || response.items
     if (roles.length === 0) {
       throw new Error(`Role '${name}' does not exist`)
@@ -352,7 +347,7 @@ export class EntityRoleProvider extends RoleProvider {
     if (permissions !== undefined) updates[this._permissionsField] = permissions
     if (inherits !== undefined) updates[this._inheritsField] = inherits
 
-    const result = await manager.update(roleEntity.id as string | number, updates)
+    const result = (await manager.update(roleEntity.id as string | number, updates)) as RoleEntity
     this.invalidate()
     return result
   }
@@ -366,10 +361,10 @@ export class EntityRoleProvider extends RoleProvider {
     const manager = this._getManager()
 
     // Find the role entity by name
-    const response = await manager.list({
+    const response = (await manager.list({
       filter: { [this._nameField]: name },
       limit: 1,
-    })
+    })) as { items: RoleEntity[]; data?: RoleEntity[] }
     const roles = response.data || response.items
     if (roles.length === 0) {
       throw new Error(`Role '${name}' does not exist`)

package/src/types/index.ts

@@ -283,3 +283,19 @@ export interface RequestOptions {
   headers?: Record<string, string>
   context?: unknown
 }
+
+// ============ UI TYPES ============
+
+/**
+ * PrimeVue Button/Tag severity values (#1191) — one shared union instead of
+ * `string` + `as any` casts at every :severity binding.
+ */
+export type ButtonSeverity =
+  | 'primary'
+  | 'secondary'
+  | 'success'
+  | 'info'
+  | 'warn'
+  | 'danger'
+  | 'help'
+  | 'contrast'