@quazardous/qdadm 2.19.0 → 2.21.0

package/src/kernel/Kernel.registries.ts

@@ -141,6 +141,15 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       )
     }
 
+    // A `grant` that cannot judge would be silently skipped, leaving the role
+    // matrix to decide alone while the app believes its backend does (#2225).
+    if (security.grant && typeof security.grant.isGranted !== 'function') {
+      throw new Error(
+        '[qdadm] security.grant must provide isGranted(attribute, subject, user). ' +
+          'Without it the application judgement would be skipped and the role matrix would decide alone.'
+      )
+    }
+
     let rolesProvider = security.rolesProvider
     if (!rolesProvider && (security.role_permissions || security.role_hierarchy)) {
       rolesProvider = new StaticRoleProvider({
@@ -152,6 +161,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     this.securityChecker = createSecurityChecker({
       rolesProvider: rolesProvider || undefined,
+      grant: security.grant,
       getCurrentUser: () =>
         (entityAuthAdapter as EntityAuthAdapter | null)?.getCurrentUser?.() || null,
     })
@@ -165,14 +175,22 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       adapter.setSecurityChecker(this.securityChecker)
     }
 
+    // One context for both installers. `permissionRegistry` lets a provider or
+    // a judge pre-warm in one batch (#2225) — but modules register their
+    // entities AFTER this point, so the keys must be read at fetch time, not
+    // inside install().
+    const ctx = {
+      orchestrator: this.orchestrator,
+      signals: this.signals,
+      permissionRegistry: this.permissionRegistry,
+    }
     if (rolesProvider?.install) {
-      const ctx = {
-        orchestrator: this.orchestrator,
-        signals: this.signals,
-      }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       rolesProvider.install(ctx as any)
     }
+    if (security.grant?.install) {
+      security.grant.install(ctx)
+    }
   }
 
   /**
@@ -361,8 +379,8 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
     'features', 'hashMode', 'homeRoute', 'i18n', 'layouts', 'managerRegistry',
     'managerResolver', 'managers', 'moduleDefs', 'modules', 'modulesOptions',
     'notifications', 'onAuthExpired', 'pages', 'parentParamMode', 'primevue',
-    'root', 'routeParamResolver', 'routePrefix', 'sectionOrder', 'security',
-    'sse', 'storageResolver', 'toast', 'warmup',
+    'root', 'routeParamResolver', 'routePrefix', 'routeState', 'sectionOrder',
+    'security', 'sse', 'storageResolver', 'toast', 'warmup',
   ])
 
   proto._validateKernelOptions = function (this: Self): void {
@@ -388,12 +406,13 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
     this._warnUnknownKeys(
       'security.',
       security,
-      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider']),
+      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant']),
       {
         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",
+        grant: "the application's judgement will not be consulted — the role matrix decides alone",
       }
     )
   }

package/src/kernel/Kernel.types.ts

@@ -10,8 +10,10 @@ import type { RoutesConfig } from './EventRouter'
 import type { EntityManager } from '../entity/EntityManager'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { RoleProvider } from '../security/RolesProvider'
+import type { GrantJudge } from '../entity/auth/SecurityChecker'
 import type { I18nOptions } from '../i18n/types'
 import type { ApiClientSource } from '../api/apiClient'
+import type { RouteStatePersister } from '../routeState'
 
 /**
  * Auth adapter interface (app-level authentication)
@@ -97,7 +99,12 @@ export interface SecurityConfig {
   role_permissions?: Record<string, string[]>
   role_labels?: Record<string, string>
   entity_permissions?: boolean | string[]
-  rolesProvider?: RoleProvider
+  rolesProvider?: RoleProvider  /**
+   * Application-provided judgement (#2225), consulted before the role matrix.
+   * `true`/`false` is the verdict, anything else falls through; a judge that
+   * throws denies. See docs/security.md.
+   */
+  grant?: GrantJudge
 }
 
 /**
@@ -218,6 +225,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>

package/src/kernel/Kernel.vue.ts

@@ -323,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/SignalBus.ts

@@ -43,6 +43,12 @@ export const SIGNALS = {
   AUTH_LOGOUT: 'auth:logout',
   AUTH_EXPIRED: 'auth:expired', // Emitted on 401/403 API responses
 
+  // Security signals
+  // The application's permission answers changed — every screen re-evaluates
+  // (#2225). Emit it only when an answer actually differs: it remounts the app,
+  // which discards unsaved form state.
+  SECURITY_CHANGED: 'security:changed',
+
   // API error signals
   API_ERROR: 'api:error', // Emitted on any API error { status, message, url }
 } as const

package/src/modules/debug/AuthCollector.ts

@@ -41,7 +41,7 @@ export interface AuthEvent {
  * Auth entry types
  */
 export interface AuthEntry extends CollectorEntry {
-  type: 'status' | 'user' | 'impersonated' | 'token' | 'user-permissions' | 'hierarchy' | 'role-permissions' | 'permissions' | 'adapter' | 'error'
+  type: 'status' | 'user' | 'impersonated' | 'token' | 'user-permissions' | 'hierarchy' | 'role-permissions' | 'permissions' | 'delegated-verdicts' | 'adapter' | 'error'
   label?: string
   message?: string
   data?: unknown
@@ -372,6 +372,20 @@ export class AuthCollector extends Collector<AuthEntry> {
           label: 'Permissions',
           data: permissions
         })
+
+        // With a delegated judge (#2225) the role matrix above is not the
+        // authority, and showing it alone would mislead. Show what the
+        // checker actually answers for every registered key — the judge's
+        // verdicts, with the matrix only where the judge abstains.
+        const judged = (this._securityChecker ?? authCtx?.security) as SecurityChecker | null | undefined
+        if (judged?.grant) {
+          entries.push({
+            timestamp: Date.now(),
+            type: 'delegated-verdicts',
+            label: 'Delegated Judgement (security.grant)',
+            data: Object.fromEntries(permissions.map((key: string) => [key, judged.isGranted(key)]))
+          })
+        }
       }
     } catch (e) {
       console.warn('[AuthCollector] Error accessing permissionRegistry:', e)

package/src/modules/debug/components/panels/AuthPanel.vue

@@ -157,6 +157,7 @@ function getIcon(type: string): string {
     permissions: 'pi-list',
     hierarchy: 'pi-sitemap',
     'role-permissions': 'pi-lock',
+    'delegated-verdicts': 'pi-server',
     adapter: 'pi-cog'
   }
   return icons[type] || 'pi-info-circle'

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')
       }

package/src/query/clientFilter.ts

@@ -103,9 +103,20 @@ export function filterItems<T>(
 }
 
 /** Substring match on every string field (the adapters' full-text search). */
-export function searchItems<T>(items: T[], search?: string | null): T[] {
-  if (!search || typeof search !== 'string' || !search.trim()) return items
-  const query = search.toLowerCase().trim()
+export function searchItems<T>(items: T[], search?: unknown): T[] {
+  // A NUMBER is a search term too (#2147). This used to require a string and
+  // return the list untouched for anything else — so searching an order id
+  // that had been through a numeric round trip filtered nothing, silently,
+  // which is the failure ADR 0011 forbids. Objects and booleans are still
+  // ignored: there is no sensible text for them.
+  const term =
+    typeof search === 'string'
+      ? search
+      : typeof search === 'number' || typeof search === 'bigint'
+        ? String(search)
+        : ''
+  if (!term.trim()) return items
+  const query = term.toLowerCase().trim()
   return items.filter((item) => {
     for (const value of Object.values(item as Record<string, unknown>)) {
       if (typeof value === 'string' && value.toLowerCase().includes(query)) {

package/src/routeState/CompositePersister.ts

@@ -0,0 +1,144 @@
+/**
+ * One state, several media (#2146).
+ *
+ * The seam's signature was chosen so composition would be expressible without
+ * changing it, and this is the case that needed it: qdadm's own default.
+ * Filters, search and the page belong in a link; rows-per-page does not — it
+ * is a comfort setting somebody chose once, and putting it in the URL would
+ * mean a link imposing the sender's row count on the reader.
+ *
+ * So the default routes by key: everything to the URL, `pageSize` to the
+ * cookie it has always lived in.
+ *
+ * ```js
+ * new CompositePersister({
+ *   fallback: new UrlPersister({ router, route }),
+ *   keys: { pageSize: { persister: new CookiePersister(), scope: 'app' } },
+ * })
+ * ```
+ *
+ * A ROUTED KEY MAY PIN ITS OWN SCOPE. `pageSize` is remembered once for the
+ * whole app rather than per list — that is what the year-long
+ * `qdadm_pageSize` cookie already did, and expressing it here makes it a
+ * visible decision instead of an accident of where the code happened to live.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+
+export interface RoutedKey {
+  persister: RouteStatePersister
+  /**
+   * Remember this key under a fixed scope instead of the caller's.
+   *
+   * For state that is one setting across the whole app rather than one per
+   * screen. Leave it out and the key follows the scope like everything else.
+   */
+  scope?: string
+}
+
+export interface CompositePersisterOptions {
+  /** Where anything unrouted goes. */
+  fallback: RouteStatePersister
+  /** Keys that live somewhere else. */
+  keys?: Record<string, RoutedKey | RouteStatePersister>
+}
+
+export class CompositePersister implements RouteStatePersister {
+  readonly name: string
+
+  private readonly _fallback: RouteStatePersister
+  private readonly _keys: Map<string, RoutedKey>
+
+  constructor(options: CompositePersisterOptions) {
+    this._fallback = options.fallback
+    this._keys = new Map(
+      Object.entries(options.keys ?? {}).map(([key, routed]) => [
+        key,
+        'persister' in routed ? routed : { persister: routed },
+      ])
+    )
+
+    const media = new Set([
+      this._fallback.name,
+      ...[...this._keys.values()].map((routed) => routed.persister.name),
+    ])
+    this.name = `composite(${[...media].join('+')})`
+  }
+
+  /**
+   * The fallback's state, with each routed key overlaid from its own medium.
+   *
+   * Order matters: a routed key wins even if the fallback happens to hold one
+   * under the same name — a stale `?pageSize=50` left in somebody's URL must
+   * not beat the cookie that owns the setting.
+   */
+  read(scope: string): Record<string, unknown> | null {
+    const base = this._fallback.read(scope)
+    const state: Record<string, unknown> = base ? { ...base } : {}
+    let found = base !== null
+
+    // Read each medium once, however many keys it owns.
+    for (const [medium, keys] of this._byMedium()) {
+      const stored = medium.persister.read(medium.scope ?? scope)
+      if (!stored) continue
+      for (const key of keys) {
+        if (stored[key] === undefined) continue
+        found = true
+        state[key] = stored[key]
+      }
+    }
+
+    return found ? state : null
+  }
+
+  /**
+   * Split the state by owner and write each medium once.
+   *
+   * A routed key ABSENT from `state` is still passed on as absent, so the
+   * empty-means-removed rule reaches the medium that owns it — otherwise
+   * clearing a filter would leave it behind in whichever store it lived in.
+   */
+  write(scope: string, state: Record<string, unknown>): void {
+    const forFallback: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(state)) {
+      if (this._keys.has(key)) continue
+      forFallback[key] = value
+    }
+    this._fallback.write(scope, forFallback)
+
+    for (const [medium, keys] of this._byMedium()) {
+      const slice: Record<string, unknown> = {}
+      for (const key of keys) slice[key] = state[key]
+      medium.persister.write(medium.scope ?? scope, slice)
+    }
+  }
+
+  /**
+   * Clear the fallback, and any routed key that follows the caller's scope.
+   *
+   * A key PINNED to its own scope is deliberately left alone: `pageSize` is
+   * an app-wide setting somebody chose, and "clear this list's filters" is
+   * not a request to reset it. Clearing it here would make one list's clear
+   * button change every other list's row count.
+   */
+  clear(scope: string): void {
+    this._fallback.clear(scope)
+    for (const [medium, keys] of this._byMedium()) {
+      if (medium.scope !== undefined) continue
+      const slice: Record<string, unknown> = {}
+      for (const key of keys) slice[key] = null
+      medium.persister.write(scope, slice)
+    }
+  }
+
+  /** Group routed keys by the (persister, scope) pair that owns them. */
+  private _byMedium(): Map<RoutedKey, string[]> {
+    const grouped = new Map<string, { medium: RoutedKey; keys: string[] }>()
+    for (const [key, routed] of this._keys) {
+      const id = `${routed.persister.name} ${routed.scope ?? ''}`
+      const existing = grouped.get(id)
+      if (existing) existing.keys.push(key)
+      else grouped.set(id, { medium: routed, keys: [key] })
+    }
+    return new Map([...grouped.values()].map(({ medium, keys }) => [medium, keys]))
+  }
+}

package/src/routeState/CookiePersister.ts

@@ -0,0 +1,109 @@
+/**
+ * Route state in a cookie (#2146).
+ *
+ * Here because qdadm already does this — page size lives in a year-long
+ * `qdadm_pageSize` cookie — and a seam that could not express what the
+ * framework already does would be a seam with a hole in it.
+ *
+ * **Every cookie is sent on every request to your origin.** That is the whole
+ * difference from web storage, and the reason this persister is shaped
+ * differently: ONE cookie per scope holding a JSON blob, not one per key. A
+ * list with eight filters would otherwise put eight cookies on every image,
+ * script and API call the page makes.
+ *
+ * Which also means: keep it small, and do not reach for this when
+ * `local_storage` would do. The case for a cookie is state the SERVER needs
+ * to see — a rows-per-page the backend renders against, say. If the server
+ * never reads it, it is paying wire cost for nothing.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+import { underscoreScopeLocator, type RouteStateScopeLocator } from './keyLocator'
+
+/** The document surface this needs, so a test needs no browser. */
+export interface CookieJar {
+  cookie: string
+}
+
+export interface CookiePersisterOptions {
+  /** Defaults to `document`. */
+  jar?: CookieJar
+  /** How a scope becomes a cookie name. Defaults to `qdadm_offers`. */
+  scopeLocator?: RouteStateScopeLocator
+  /** Lifetime in days. Defaults to 365 — what `qdadm_pageSize` already used. */
+  maxAgeDays?: number
+  /** `SameSite` attribute. Defaults to `Lax`. */
+  sameSite?: 'Strict' | 'Lax' | 'None'
+  /** Path the cookie applies to. Defaults to `/`. */
+  path?: string
+}
+
+export class CookiePersister implements RouteStatePersister {
+  readonly name = 'cookie'
+
+  private readonly _jar: CookieJar
+  private readonly _scopes: RouteStateScopeLocator
+  private readonly _maxAgeDays: number
+  private readonly _sameSite: string
+  private readonly _path: string
+
+  constructor(options: CookiePersisterOptions = {}) {
+    this._jar = options.jar ?? (document as unknown as CookieJar)
+    this._scopes = options.scopeLocator ?? underscoreScopeLocator
+    this._maxAgeDays = options.maxAgeDays ?? 365
+    this._sameSite = options.sameSite ?? 'Lax'
+    this._path = options.path ?? '/'
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    const raw = this._readCookie(this._scopes.encode(scope))
+    if (raw === null) return null
+    try {
+      const parsed = JSON.parse(decodeURIComponent(raw))
+      return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : null
+    } catch {
+      // Somebody else's cookie under our name, or a truncated one. Ignoring it
+      // is right here: unlike a single key, a corrupt blob tells us nothing
+      // partial worth keeping.
+      return null
+    }
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    // The blob is rewritten whole, so the empty-means-absent rule is applied
+    // by dropping keys rather than by removing entries.
+    const kept: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(state)) {
+      if (value === null || value === undefined || value === '') continue
+      kept[key] = value
+    }
+
+    // Nothing left to remember: take the cookie off the wire rather than
+    // shipping `{}` on every request for the next year.
+    if (!Object.keys(kept).length) {
+      this.clear(scope)
+      return
+    }
+
+    this._writeCookie(this._scopes.encode(scope), encodeURIComponent(JSON.stringify(kept)))
+  }
+
+  clear(scope: string): void {
+    const name = this._scopes.encode(scope)
+    this._jar.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=${this._path}; SameSite=${this._sameSite}`
+  }
+
+  private _readCookie(name: string): string | null {
+    for (const part of this._jar.cookie.split(';')) {
+      const separator = part.indexOf('=')
+      if (separator === -1) continue
+      if (part.slice(0, separator).trim() !== name) continue
+      return part.slice(separator + 1)
+    }
+    return null
+  }
+
+  private _writeCookie(name: string, value: string): void {
+    const expires = new Date(Date.now() + this._maxAgeDays * 864e5).toUTCString()
+    this._jar.cookie = `${name}=${value}; expires=${expires}; path=${this._path}; SameSite=${this._sameSite}`
+  }
+}

package/src/routeState/MemoryPersister.ts

@@ -0,0 +1,60 @@
+/**
+ * Route state in memory (#2146).
+ *
+ * Survives navigating away and back within the running app; does not survive
+ * a reload, and is invisible to a link. That makes it the right answer for
+ * state that would be noise anywhere else — a wizard's step, a panel a user
+ * opened once — and the right answer in tests, where a shared `localStorage`
+ * leaks one case into the next.
+ *
+ * THE STORE OUTLIVES THE PERSISTER ON PURPOSE. A list builds its persister on
+ * mount; if the state lived on the instance it would die on unmount, which is
+ * exactly the navigation this is supposed to survive. So the default store is
+ * module-level and shared. Pass your own `store` to get an isolated one —
+ * which is what a test usually wants.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+
+export type RouteStateMemoryStore = Map<string, Record<string, unknown>>
+
+/** The shared default. See the note above on why this is module-level. */
+const defaultStore: RouteStateMemoryStore = new Map()
+
+export interface MemoryPersisterOptions {
+  store?: RouteStateMemoryStore
+}
+
+export class MemoryPersister implements RouteStatePersister {
+  readonly name = 'memory'
+
+  private readonly _store: RouteStateMemoryStore
+
+  constructor(options: MemoryPersisterOptions = {}) {
+    this._store = options.store ?? defaultStore
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    const stored = this._store.get(scope)
+    // Copied out, so a caller mutating what it read cannot rewrite history.
+    return stored ? { ...stored } : null
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    const kept: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(state)) {
+      if (value === null || value === undefined || value === '') continue
+      kept[key] = value
+    }
+    if (!Object.keys(kept).length) this._store.delete(scope)
+    else this._store.set(scope, kept)
+  }
+
+  clear(scope: string): void {
+    this._store.delete(scope)
+  }
+}
+
+/** Empty the shared store — for tests that use the default. */
+export function clearRouteStateMemory(): void {
+  defaultStore.clear()
+}

package/src/routeState/NullPersister.ts

@@ -0,0 +1,33 @@
+/**
+ * Route state remembered nowhere (#2146).
+ *
+ * The way to say "this screen forgets" and have it read as a decision. An
+ * embedded list inside a detail view, a picker in a dialog, a preview — none
+ * of them should put anything in the address bar, and none of them should
+ * leave anything behind.
+ *
+ * A no-op object looks like the thing
+ * [ADR 0011](../../docs/adr/0011-no-silent-no-ops.md) forbids, and the
+ * difference is the whole point: this one is NAMED. Nothing falls back to it,
+ * nothing resolves to it by accident, and an unknown slug throws rather than
+ * landing here. It does nothing because somebody wrote `routeState: 'none'`,
+ * and that sentence is in the app's source where the next reader will find
+ * it.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+
+export class NullPersister implements RouteStatePersister {
+  readonly name = 'none'
+
+  read(): null {
+    return null
+  }
+
+  write(): void {
+    /* deliberately nothing — see the note above */
+  }
+
+  clear(): void {
+    /* deliberately nothing */
+  }
+}

package/src/routeState/RouteStatePersister.ts

@@ -0,0 +1,86 @@
+/**
+ * Where a route's state is remembered (#2146).
+ *
+ * Not "list state": the list is one CONSUMER of routing state, not the
+ * subject. A detail page's active tab, a dashboard's date range and a child
+ * page's own state are the same problem, and each would invent its own answer
+ * if this seam did not exist — which is exactly how qdadm ended up with five
+ * unrelated persistence sites, one of them a year-long cookie.
+ *
+ * The state is opaque on purpose. Every consumer has its own shape, and a
+ * fixed one here would only fit whichever consumer was written first.
+ *
+ * NOT for chrome preferences. A collapsed sidebar belongs to the person, not
+ * to the route: sending someone a link must not fold their menu. The line is
+ * *what I am looking at* versus *how I like my interface*.
+ */
+export interface RouteStatePersister {
+  /** Everything remembered under this scope, or null when nothing is. */
+  read(scope: string): Record<string, unknown> | null
+  /**
+   * Remember this state under this scope.
+   *
+   * A key whose value is `null`, `undefined` or `''` is REMOVED rather than
+   * stored empty — so a pristine screen leaves no trace, and a shared link
+   * carries only what was actually chosen.
+   */
+  write(scope: string, state: Record<string, unknown>): void
+  clear(scope: string): void
+  /** For diagnostics: which persister answered. */
+  readonly name: string
+}
+
+/**
+ * How a consumer names itself.
+ *
+ * The scope is what makes two lists on one route stop fighting over `page` —
+ * the collision `page-compositions.md` currently tells people to avoid by
+ * switching persistence off entirely.
+ */
+export type RouteStateScope = string
+
+/** A handler as the bootstrap declares it: a slug, or an instance. */
+export type RouteStatePersisterSpec = string | RouteStatePersister
+
+/** Anything that can build a persister from a slug. */
+export type RouteStatePersisterFactory = (slug: string) => RouteStatePersister | null
+
+/** An instance, duck-typed — the same test the storage factory applies. */
+export function isRouteStatePersister(value: unknown): value is RouteStatePersister {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as RouteStatePersister
+  return (
+    typeof candidate.read === 'function' &&
+    typeof candidate.write === 'function' &&
+    typeof candidate.clear === 'function'
+  )
+}
+
+/**
+ * Turn a spec into a persister.
+ *
+ * An unknown slug THROWS. It does not fall back to the URL: a persistence
+ * choice that silently does something else is the exact failure
+ * [ADR 0011](../../docs/adr/0011-no-silent-no-ops.md) exists to forbid, and
+ * the one this seam is cleaning up after.
+ */
+export function resolveRouteStatePersister(
+  spec: RouteStatePersisterSpec,
+  factory: RouteStatePersisterFactory
+): RouteStatePersister {
+  if (isRouteStatePersister(spec)) return spec
+
+  if (typeof spec === 'string') {
+    const built = factory(spec)
+    if (built) return built
+    throw new Error(
+      `[qdadm] Unknown route-state persister "${spec}". ` +
+        `Pass a known slug, or an object with read/write/clear.`
+    )
+  }
+
+  throw new Error(
+    `[qdadm] Invalid route-state persister: ${typeof spec}. ` +
+      `Expected a slug or an object with read/write/clear.`
+  )
+}