@quazardous/qdadm 2.18.0 → 2.20.0

package/src/entity/storage/SdkStorage.ts

@@ -1,6 +1,6 @@
 import { IStorage } from './IStorage'
 import type { EntityRecord, ListParams, ListResult, StorageCapabilities } from '../../types'
-import { sortItems, filterItems, paginate } from '../../query/clientFilter'
+import { sortItems, filterItems, paginate, searchItems } from '../../query/clientFilter'
 
 /**
  * SDK method result with data property
@@ -275,9 +275,13 @@ export class SdkStorage<T extends EntityRecord = EntityRecord> extends IStorage<
   }
 
   async list(params: ListParams = {}): Promise<ListResult<T>> {
-    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {} } = params
+    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {}, search } = params
 
-    const queryParams = { query: { page, page_size, sort_by, sort_order, ...filters } }
+    // `search` goes to the SDK with everything else (#2147). It was dropped
+    // here, so a search box over an SDK-backed entity typed into the void:
+    // the call went out without the term and the rows came back unfiltered,
+    // with nothing anywhere saying why.
+    const queryParams = { query: { page, page_size, sort_by, sort_order, search, ...filters } }
     const data = (await this._execute('list', queryParams)) as ListResult<T>
 
     let { items, total } = data
@@ -292,8 +296,13 @@ export class SdkStorage<T extends EntityRecord = EntityRecord> extends IStorage<
 
       // Shared pipeline (#1192) — original order preserved: sort, then
       // filter (substring semantics), then paginate.
+      //
+      // The search is applied here TOO, not only sent (#2147). An SDK that
+      // ignores the term would otherwise hand back the whole collection and
+      // this branch would paginate it as if it had been searched.
       items = sortItems([...items], sort_by, sort_order)
       items = filterItems(items, filters, { stringMatch: 'includes' })
+      items = searchItems(items, search)
       total = items.length
       items = paginate(items, page, page_size)
     }

package/src/gen/createManagers.ts

@@ -196,7 +196,7 @@ function findSchemaForEntity(
  * const users = await usersManager.list()
  * ```
  */
-export function createManagers(config: CreateManagersConfig): Map<string, EntityManager> {
+export function createGeneratedManagers(config: CreateManagersConfig): Map<string, EntityManager> {
   // Validate config structure early
   validateConfig(config)
 
@@ -243,3 +243,17 @@ export function createManagers(config: CreateManagersConfig): Map<string, Entity
 
   return managers
 }
+
+/**
+ * @deprecated Renamed to `createGeneratedManagers` (#1902).
+ *
+ * The root exports a DIFFERENT `createManagers` — `entity/factory.ts`, which
+ * takes `(config, context)` and returns a `Record`, where this one takes a
+ * single generated config and returns a `Map`. Same name, two public entry
+ * points, different signatures and different return types, with nothing to
+ * warn whoever picked the wrong import: the mistake surfaces at the first
+ * `.get()`.
+ *
+ * This alias keeps existing imports working. Use `createGeneratedManagers`.
+ */
+export const createManagers = createGeneratedManagers

package/src/gen/index.ts

@@ -51,7 +51,13 @@ export { OpenAPIConnector, type OpenAPIConnectorOptions, type OperationFilter }
 export { type StorageProfileFactory, type StorageProfileOptions } from './StorageProfileFactory'
 
 // T00317: createManagers - Runtime factory for EntityManager creation
-export { createManagers, type CreateManagersConfig, type EntityConfig } from './createManagers'
+export {
+  createGeneratedManagers,
+  /** @deprecated Renamed to `createGeneratedManagers` (#1902) — it collided with the root's own `createManagers`. */
+  createManagers,
+  type CreateManagersConfig,
+  type EntityConfig,
+} from './createManagers'
 
 // T00318: Decorators - Per-entity field customization layer
 export { applyDecorators, type FieldDecorator, type EntityDecorator } from './decorators'

package/src/index.ts

@@ -237,10 +237,13 @@ export * from './composables/useJsonSyntax'
 export {
   useListPage,
   PAGE_SIZE_OPTIONS,
+  FILTER_TYPES,
   type UseListPageOptions,
   type UseListPageReturn,
   type ColumnConfig,
   type FilterConfig,
+  type FilterOptions,
+  type FilterType,
   type ActionConfig as ListActionConfig,
   type ResolvedAction,
   type HeaderActionConfig,
@@ -322,6 +325,22 @@ export {
   type LayoutMeta,
 } from './composables/useLayoutResolver'
 export { useSSEBridge, type UseSSEBridgeReturn } from './composables/useSSEBridge'
+
+// Route-state persistence (#2146) — where a route remembers what it shows.
+export {
+  UrlPersister,
+  isRouteStatePersister,
+  resolveRouteStatePersister,
+  createRouteStatePersisterFactory,
+  type RouteStatePersister,
+  type RouteStateScope,
+  type RouteStatePersisterSpec,
+  type RouteStatePersisterFactory,
+  type UrlPersisterOptions,
+  dottedKeyLocator,
+  namespacedKeyLocator,
+  type RouteStateKeyLocator,
+} from './routeState'
 export {
   useDeferred,
   useDeferredValue,

package/src/kernel/Kernel.registries.ts

@@ -52,9 +52,14 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create hook registry for Drupal-inspired extensibility
    */
   proto._createHookRegistry = function (this: Self): void {
+    // Idempotent, and built in the constructor (#1906 lot B1): replacing it in
+    // createApp() would orphan every hook registered before then — silently,
+    // which is the failure this lot exists to remove.
+    if (this.hookRegistry) return
+
     const debug = this.options.debug ?? false
     this.hookRegistry = createHookRegistry({
-      kernel: this.signals!.getKernel(),
+      kernel: this.signals.getKernel(),
       debug,
     })
   }
@@ -94,6 +99,9 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create PermissionRegistry early so modules can register permissions
    */
   proto._createPermissionRegistry = function (this: Self): void {
+    // Idempotent, built in the constructor (#1906 lot B1) — see _createHookRegistry.
+    if (this.permissionRegistry) return
+
     this.permissionRegistry = new PermissionRegistry()
     this._registerCorePermissions()
   }
@@ -102,12 +110,12 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Register core system permissions provided by the framework
    */
   proto._registerCorePermissions = function (this: Self): void {
-    this.permissionRegistry!.register('auth', {
+    this.permissionRegistry.register('auth', {
       impersonate: 'Impersonate other users',
       manage: 'Manage authentication settings',
     })
 
-    this.permissionRegistry!.register('admin', {
+    this.permissionRegistry.register('admin', {
       access: 'Access admin panel',
       config: 'Edit system configuration',
     })
@@ -119,12 +127,10 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
   proto._setupSecurity = function (this: Self): void {
     const { security, entityAuthAdapter } = this.options
 
-    if (!this.permissionRegistry) {
-      this.permissionRegistry = new PermissionRegistry()
-    }
-
     if (!security) return
 
+    this._validateSecurityConfig(security as unknown as Record<string, unknown>)
+
     // security configured but no user source: every isGranted() falls back
     // to permissive — a newcomer believes gating is on when it isn't (#1388)
     if (!entityAuthAdapter) {
@@ -173,6 +179,9 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create zone registry for extensible UI composition
    */
   proto._createZoneRegistry = function (this: Self): void {
+    // Idempotent, built in the constructor (#1906 lot B1) — see _createHookRegistry.
+    if (this.zoneRegistry) return
+
     const debug = this.options.debug ?? false
     this.zoneRegistry = createZoneRegistry({ debug })
   }
@@ -199,9 +208,15 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create deferred registry for async service loading
    */
   proto._createDeferredRegistry = function (this: Self): void {
+    // Idempotent, built in the constructor (#1906 lot B1) — see _createHookRegistry.
+    if (this.deferred) return
+
     const debug = this.options.debug ?? false
+    // `this.signals` is never null now, so the defensive `?.` this line used
+    // to carry is gone. Less guarding, not more: that is the point of closing
+    // the window rather than warning about it.
     this.deferred = createDeferredRegistry({
-      kernel: this.signals?.getKernel() || null,
+      kernel: this.signals.getKernel(),
       debug,
     })
   }
@@ -225,49 +240,93 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create SSEBridge for Server-Sent Events to SignalBus integration
    */
   /**
-   * Warn about unrecognised `sse` keys (#1898 lot A).
+   * The known key a typo most likely meant, or undefined.
    *
-   * A consumer configured `sse.getToken` against a version that predated it.
-   * It was not rejected — it was ignored, and the bridge fell back to the
-   * session's DURABLE token, which then travelled in the query string of every
-   * `/events` request and into logs that outlive the session by months. No
-   * error, no warning, and a stream that worked perfectly.
-   *
-   * The warning therefore names what happens INSTEAD, not merely that the key
-   * was ignored: "ignored" reads as "no effect", not as "falls back to a more
-   * sensitive secret". That reading is what made the failure invisible.
+   * Case differences and prefixes were all the original matcher caught
+   * (#1898), which misses the commonest typo of all: one missing or
+   * transposed letter. `securty` suggested nothing, so the reader got
+   * "IGNORED" with no hint and no consequence — the two things that make the
+   * warning worth printing. An edit distance of one covers an omission, an
+   * insertion, a substitution or a transposition; two is allowed only for
+   * longer keys, where it stays specific enough not to guess wildly.
    */
-  proto._validateSseConfig = function (this: Self, sse: SSEConfig): void {
-    const known = new Set([
-      'url',
-      'reconnectDelay',
-      'signalPrefix',
-      'autoConnect',
-      'withCredentials',
-      'tokenParam',
-      'events',
-      'entities',
-      'getToken',
-      'connectOnSignal',
-      'disconnectOnSignal',
-    ])
-
-    const unknown = Object.keys(sse).filter((key) => !known.has(key))
-    if (!unknown.length) return
+  function nearestKnownKey(key: string, known: Set<string>): string | undefined {
+    const exact = [...known].find(
+      (k) => k.toLowerCase() === key.toLowerCase() || k.startsWith(key) || key.startsWith(k)
+    )
+    if (exact) return exact
+
+    const budget = key.length >= 8 ? 2 : 1
+    let best: string | undefined
+    let bestDistance = budget + 1
+    for (const candidate of known) {
+      const distance = editDistance(key.toLowerCase(), candidate.toLowerCase(), bestDistance)
+      if (distance < bestDistance) {
+        bestDistance = distance
+        best = candidate
+      }
+    }
+    return bestDistance <= budget ? best : undefined
+  }
 
-    // What the app loses by having the key ignored, wherever we can say it.
-    const consequences: Record<string, string> = {
-      getToken:
-        'the session auth token will be sent in the stream URL instead — ' +
-        'and query strings reach access logs',
-      entities: 'no entity cache will be invalidated from the stream',
-      tokenParam: 'the token will be sent under the default name "token"',
+  /** Damerau-Levenshtein, abandoned as soon as it exceeds `cap`. */
+  function editDistance(a: string, b: string, cap: number): number {
+    if (Math.abs(a.length - b.length) > cap) return cap + 1
+
+    let previous: number[] = Array.from({ length: b.length + 1 }, (_, i) => i)
+    let beforePrevious: number[] = []
+
+    for (let i = 1; i <= a.length; i++) {
+      const current: number[] = [i]
+      let rowBest = i
+      for (let j = 1; j <= b.length; j++) {
+        const cost = a[i - 1] === b[j - 1] ? 0 : 1
+        let value = Math.min(
+          (current[j - 1] as number) + 1,
+          (previous[j] as number) + 1,
+          (previous[j - 1] as number) + cost
+        )
+        // Transposition: `raods` for `roads`.
+        if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+          value = Math.min(value, (beforePrevious[j - 2] as number) + 1)
+        }
+        current[j] = value
+        rowBest = Math.min(rowBest, value)
+      }
+      if (rowBest > cap) return cap + 1
+      beforePrevious = previous
+      previous = current
     }
+    return previous[b.length] as number
+  }
+
+  /**
+   * Warn about keys a config object does not recognise (#1906 lot B2).
+   *
+   * Extracted from the `sse` validator of #1898, which was the only one of its
+   * kind: every other qdadm config accepted anything in silence. The shape of
+   * the message is the lesson from that incident and is kept intact — it names
+   * what happens INSTEAD of what was asked, because "ignored" reads as "no
+   * effect" rather than "falls back to something else", and that reading is
+   * what cost a durable auth token in access logs.
+   *
+   * Only for CLOSED shapes. A config that deliberately forwards unknown keys
+   * elsewhere — `debugBar`, whose extra options reach the DebugModule — must
+   * not be passed through here: a warning that cries wolf is worse than none
+   * (ADR 0011).
+   */
+  proto._warnUnknownKeys = function (
+    this: Self,
+    scope: string,
+    config: Record<string, unknown>,
+    known: Set<string>,
+    consequences: Record<string, string> = {}
+  ): void {
+    const unknown = Object.keys(config).filter((key) => !known.has(key))
+    if (!unknown.length) return
 
     for (const key of unknown) {
-      const near = [...known].find(
-        (k) => k.toLowerCase() === key.toLowerCase() || k.startsWith(key) || key.startsWith(k)
-      )
+      const near = nearestKnownKey(key, known)
       // Look the consequence up under the NEAREST KNOWN key: a typo like
       // `getTokens` means `getToken` is absent, and it is that absence whose
       // effect the reader needs to hear.
@@ -275,13 +334,110 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       const because = consequence ? ` — ${consequence}` : ''
       const suggestion = near ? ` Did you mean "${near}"?` : ''
       console.warn(
-        `[Kernel] sse.${key} is not a recognised option and is IGNORED${because}.` +
+        `[Kernel] ${scope}${key} is not a recognised option and is IGNORED${because}.` +
           `${suggestion} This usually means the installed qdadm predates the option ` +
           `— check the version before assuming the key has no effect.`
       )
     }
   }
 
+  /**
+   * Every option `KernelOptions` accepts (#1906 lot B2).
+   *
+   * A misspelled TOP-LEVEL key is the worst silence of the family: it does not
+   * degrade a feature, it removes a whole section of configuration. `securty:`
+   * means no security config at all, and nothing says so. TypeScript catches
+   * it; the many consumers whose module files are plain JavaScript get
+   * nothing.
+   *
+   * Kept in sync with the interface by a test that reads `Kernel.types.ts` and
+   * compares — a hand-maintained list that drifts would start crying wolf,
+   * which is the failure mode this whole ticket exists to avoid.
+   */
+  const KNOWN_KERNEL_OPTIONS = new Set([
+    'apiClient', 'app', 'authAdapter', 'authTypes', 'basePath', 'coreRoutes',
+    'debug', 'debugBar', 'defaultEntityCacheTtlMs', 'entityAuthAdapter',
+    'eventRouter', 'existingApp', 'existingRouter', 'existingSignals',
+    'features', 'hashMode', 'homeRoute', 'i18n', 'layouts', 'managerRegistry',
+    'managerResolver', 'managers', 'moduleDefs', 'modules', 'modulesOptions',
+    'notifications', 'onAuthExpired', 'pages', 'parentParamMode', 'primevue',
+    'root', 'routeParamResolver', 'routePrefix', 'routeState', 'sectionOrder',
+    'security', 'sse', 'storageResolver', 'toast', 'warmup',
+  ])
+
+  proto._validateKernelOptions = function (this: Self): void {
+    this._warnUnknownKeys('', this.options as Record<string, unknown>, KNOWN_KERNEL_OPTIONS, {
+      security: 'no role hierarchy or permissions will be applied — every check falls back to the default',
+      sse: 'no server-sent events will be connected',
+      debugBar: 'no debug bar will be mounted',
+      layouts: 'pages will fall back to the base layout',
+      i18n: 'translations will not be configured',
+      authAdapter: 'the app will run unauthenticated',
+    })
+  }
+
+  /**
+   * Warn about unrecognised `security` keys (#1906 lot B2).
+   *
+   * Chosen first, and by damage: a misspelled key here means a role hierarchy
+   * or a permission map is simply absent, and every check then falls through
+   * to whatever the default is. Nothing fails, nothing warns, and the app is
+   * open where its author believed it closed.
+   */
+  proto._validateSecurityConfig = function (this: Self, security: Record<string, unknown>): void {
+    this._warnUnknownKeys(
+      'security.',
+      security,
+      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider']),
+      {
+        role_hierarchy: 'roles will not inherit from one another',
+        role_permissions: 'no role will carry any permission',
+        entity_permissions: 'per-entity permissions will not be generated',
+        rolesProvider: "the current user's roles will not be resolved",
+      }
+    )
+  }
+
+  /**
+   * Warn about unrecognised `sse` keys (#1898 lot A).
+   *
+   * A consumer configured `sse.getToken` against a version that predated it.
+   * It was not rejected — it was ignored, and the bridge fell back to the
+   * session's DURABLE token, which then travelled in the query string of every
+   * `/events` request and into logs that outlive the session by months. No
+   * error, no warning, and a stream that worked perfectly.
+   *
+   * The warning therefore names what happens INSTEAD, not merely that the key
+   * was ignored: "ignored" reads as "no effect", not as "falls back to a more
+   * sensitive secret". That reading is what made the failure invisible.
+   */
+  proto._validateSseConfig = function (this: Self, sse: SSEConfig): void {
+    this._warnUnknownKeys(
+      'sse.',
+      sse as unknown as Record<string, unknown>,
+      new Set([
+        'url',
+        'reconnectDelay',
+        'signalPrefix',
+        'autoConnect',
+        'withCredentials',
+        'tokenParam',
+        'events',
+        'entities',
+        'getToken',
+        'connectOnSignal',
+        'disconnectOnSignal',
+      ]),
+      {
+        getToken:
+          'the session auth token will be sent in the stream URL instead — ' +
+          'and query strings reach access logs',
+        entities: 'no entity cache will be invalidated from the stream',
+        tokenParam: 'the token will be sent under the default name "token"',
+      }
+    )
+  }
+
   proto._createSSEBridge = function (this: Self): void {
     const { sse, authAdapter } = this.options
     if (!sse?.url) return

package/src/kernel/Kernel.ts

@@ -94,18 +94,18 @@ export class Kernel {
    * window existed for no reason. Removing it beats warning about it
    * (ADR 0011).
    */
-  signals: SignalBus | null = null
+  signals!: SignalBus
   orchestrator: Orchestrator | null = null
-  zoneRegistry: ZoneRegistry | null = null
-  hookRegistry: HookRegistry | null = null
-  deferred: DeferredRegistry | null = null
+  zoneRegistry!: ZoneRegistry
+  hookRegistry!: HookRegistry
+  deferred!: DeferredRegistry
   eventRouter: EventRouter | null = null
   sseBridge: SSEBridge | null = null
   /** Routes external entity changes to cache invalidation (#1888). */
   liveEntityRouter: LiveEntityRouter | null = null
   layoutComponents: InternalLayoutComponents | null = null
   securityChecker: SecurityChecker | null = null
-  permissionRegistry: PermissionRegistry | null = null
+  permissionRegistry!: PermissionRegistry
   moduleLoader: ModuleLoader | null = null
   activeStack: ActiveStack | null = null
   stackHydrator: StackHydrator | null = null
@@ -181,11 +181,28 @@ export class Kernel {
 
     this.options = options
 
-    // The bus exists from here on (#1905 lot B). It has no dependencies, and
-    // the natural place to wire it is right after `new Kernel()` — so it must
-    // be usable there. _createSignalBus() is idempotent, so the later call in
-    // createApp() keeps this instance rather than orphaning its listeners.
+    // Everything that CAN exist from here on, does (#1905 lot B, #1906 lot B1).
+    //
+    // These five have no dependency beyond `options` and each other, and the
+    // natural place to wire a kernel is right after `new Kernel()` — so they
+    // have to be usable there. Someone reached for `kernel.signals` before
+    // createApp(), got `null`, and `null?.emit?.()` swallowed it without a
+    // word; there were seventeen properties shaped like that, and these are
+    // the ones that need not have been.
+    //
+    // Every creator is idempotent, so the later calls in createApp() keep
+    // these instances rather than orphaning whatever was registered on them
+    // in between — which would be the same silent failure wearing a new hat.
+    // Before anything reads them (#1906 lot B2): a misspelled top-level key
+    // removes a whole section of configuration, and TypeScript only catches
+    // it for consumers whose module files are TypeScript.
+    this._validateKernelOptions()
+
     this._createSignalBus()
+    this._createHookRegistry()
+    this._createZoneRegistry()
+    this._createDeferredRegistry()
+    this._createPermissionRegistry()
   }
 
   /**
@@ -479,6 +496,14 @@ export interface Kernel {
   _createDeferredRegistry(): void
   _createEventRouter(): void
   _validateSseConfig(sse: SSEConfigType): void
+  _validateSecurityConfig(security: Record<string, unknown>): void
+  _validateKernelOptions(): void
+  _warnUnknownKeys(
+    scope: string,
+    config: Record<string, unknown>,
+    known: Set<string>,
+    consequences?: Record<string, string>
+  ): void
   _createSSEBridge(): void
 
   // Vue (Kernel.vue.ts)

package/src/kernel/Kernel.types.ts

@@ -12,6 +12,7 @@ import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { RoleProvider } from '../security/RolesProvider'
 import type { I18nOptions } from '../i18n/types'
 import type { ApiClientSource } from '../api/apiClient'
+import type { RouteStatePersister } from '../routeState'
 
 /**
  * Auth adapter interface (app-level authentication)
@@ -70,10 +71,12 @@ export interface Pages {
 export interface LayoutComponents {
   list?: Component | null
   form?: Component | null
+  show?: Component | null
   dashboard?: Component | null
   base?: Component | null
   ListLayout?: Component
   FormLayout?: Component
+  ShowLayout?: Component
   DashboardLayout?: Component
   BaseLayout?: Component
 }
@@ -216,6 +219,21 @@ export interface KernelOptions {
   defaultEntityCacheTtlMs?: number
   eventRouter?: RoutesConfig
   sse?: SSEConfig
+  /**
+   * Where screens remember their route state by default (#2146): a slug the
+   * framework knows (`'url'`, `'local_storage'`, `'cookie'`, `'memory'`,
+   * `'none'`), or a persister instance.
+   *
+   * The app-wide floor. An entity overrides it for every screen showing that
+   * entity; a single list overrides it for itself. Unset means `'url'`, which
+   * is the only medium where what you are looking at is also what you can
+   * send someone.
+   *
+   * An unknown slug throws at list construction rather than falling back —
+   * a persistence choice that quietly does something else is the failure
+   * ADR 0011 forbids.
+   */
+  routeState?: string | RouteStatePersister
   debugBar?: DebugBarConfig
   notifications?: NotificationsConfig
   toast?: Record<string, unknown>
@@ -293,6 +311,7 @@ export interface KernelOptions {
 export interface InternalLayoutComponents {
   list: Component | null
   form: Component | null
+  show: Component | null
   dashboard: Component | null
   base: Component | null
 }

package/src/kernel/Kernel.vue.ts

@@ -115,6 +115,10 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
     this.layoutComponents = {
       list: layouts.list || layouts.ListLayout || null,
       form: layouts.form || layouts.FormLayout || null,
+      // Until #1922 this literal had no `show` key, so an app that passed one
+      // had it dropped without a word while crud({ show }) kept emitting
+      // `layout: 'show'` for a layout nothing could honour.
+      show: layouts.show || layouts.ShowLayout || null,
       dashboard: layouts.dashboard || layouts.DashboardLayout || null,
       base: layouts.base || layouts.BaseLayout || null,
     }
@@ -319,6 +323,9 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
     }
 
     app.provide('qdadmHooks', this.hookRegistry)
+    // The app-wide route-state default (#2146). Provided even when unset, so
+    // a list can tell "nobody chose" from "somebody chose and it was null".
+    app.provide('qdadmRouteState', this.options.routeState ?? null)
     app.provide('qdadmDeferred', this.deferred)
     app.provide('qdadmLayoutComponents', this.layoutComponents)
     // Surface PrimeVue presence so host-rendered <QdadmRoot /> can

package/src/kernel/KernelContext.routing.ts

@@ -9,9 +9,13 @@
  * The string helpers (`singularize`, `toKebab`, `capitalize`) are kept
  * module-local — they're pure, stateless, and were only used by `crud()` and
  * `childPage()`. Keeping them off the prototype keeps the public shape clean.
+ * `singularize` is a thin call into the vendored `pluralize` since #1923: the
+ * hand-rolled version disagreed with the one `EntityManager` uses, and a
+ * framework cannot afford two answers to the same question.
  */
 
 import type { RouteRecordRaw } from 'vue-router'
+import pluralize from '../utils/pluralize'
 import { registry, getRoutes } from '../module/moduleRegistry'
 import type {
   ChildPageOptions,
@@ -26,14 +30,21 @@ import type { KernelContext } from './KernelContext'
 // #1196 Phase B — this-typing against the real KernelContext shape (was Self = any)
 type Self = KernelContext
 
-/** Singularize a plural word (simple English rules) */
+/**
+ * Singularize an entity name (#1923).
+ *
+ * This used to be six hand-rolled lines, while `EntityManager.routePrefix`
+ * used the vendored `pluralize`. Two engines, and they disagreed: `crud()`
+ * named a route `people-show` while `useListPage` looked for `person-show`,
+ * so every navigation helper missed silently — no error at boot, nothing until
+ * someone clicked. They agreed on every regular plural, which is exactly why
+ * it went unnoticed.
+ *
+ * One engine now, the real one. `pluralize` is vendored (#1454) and imports
+ * nothing, so there is no cycle to fear from calling it here.
+ */
 function singularize(plural: string): string {
-  if (plural.endsWith('ies')) return plural.slice(0, -3) + 'y'
-  if (plural.endsWith('ses') || plural.endsWith('xes') || plural.endsWith('zes')) {
-    return plural.slice(0, -2)
-  }
-  if (plural.endsWith('s') && !plural.endsWith('ss')) return plural.slice(0, -1)
-  return plural
+  return pluralize.singular(plural)
 }
 
 /** Convert camelCase to kebab-case (e.g. 'botTasks' → 'bot-tasks') */

package/src/plugin.ts

@@ -107,7 +107,7 @@ export interface QdadmPlugin {
 export function createQdadm(options: QdadmOptions): QdadmPlugin {
   return {
     install(app: App) {
-      // Validation des contrats requis
+      // The contracts this plugin cannot run without.
       if (!options.entityFactory && !options.orchestrator && !options.managers) {
         throw new Error('[qdadm] entityFactory, orchestrator, or managers required')
       }