@quazardous/qdadm 2.19.0 → 2.21.0

package/src/routeState/UrlPersister.ts

@@ -0,0 +1,207 @@
+/**
+ * Route state in the query string — the default (#2146).
+ *
+ * The default because it is the only medium where "what I am looking at" is
+ * also "what I can send you". A list URL that does not carry its page is a
+ * link that shows the recipient something else.
+ *
+ * CLEAN AROUND THE EXISTING ROUTER: this goes through the `router` the app
+ * already has, with `replace`, and touches no route declaration. Paging is
+ * not a history step of its own — but the URL must carry the state at the
+ * moment the user leaves, so that coming back restores it.
+ *
+ * Keys are namespaced by scope (`offers.page=2`), which is what stops two
+ * lists on one route from fighting over `page` — the collision
+ * `page-compositions.md` currently tells people to avoid by switching
+ * persistence off.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+import { dottedKeyLocator, type RouteStateKeyLocator } from './keyLocator'
+
+/** The bits of vue-router this needs, so tests need no real router. */
+/** One query value, shaped as vue-router accepts them. */
+export type UrlPersisterQueryValue = string | number | null | undefined
+
+export interface UrlPersisterRouter {
+  // Values are narrowed to what vue-router's own query type accepts, so the
+  // real router satisfies this without a cast — and so does a two-line fake
+  // in a test.
+  replace(to: { query: Record<string, UrlPersisterQueryValue> }): unknown
+}
+export interface UrlPersisterRoute {
+  query: Record<string, unknown>
+}
+
+export interface UrlPersisterOptions {
+  router: UrlPersisterRouter
+  /** Live route — read at call time, never captured. */
+  route: UrlPersisterRoute
+  /**
+   * How a (scope, key) pair becomes a query parameter. Defaults to
+   * `offers.page`; override to impose your own scheme.
+   */
+  keyLocator?: RouteStateKeyLocator
+  /**
+   * Also read UNPREFIXED keys when the scope has none of its own.
+   *
+   * Transitional, and on by default: qdadm wrote `?page=2` flat before this
+   * seam existed, so links people bookmarked or pasted into tickets carry
+   * that shape. Without this they would silently resolve to page 1 — the
+   * reader would see a wrong screen and no error.
+   *
+   * Writes are always prefixed, so a link refreshes itself the first time
+   * anyone touches the list. Set false to drop the compatibility, and expect
+   * to remove it here in a later version.
+   */
+  readFlatFallback?: boolean
+}
+
+export class UrlPersister implements RouteStatePersister {
+  readonly name = 'url'
+
+  private readonly _router: UrlPersisterRouter
+  private readonly _route: UrlPersisterRoute
+  private readonly _keys: RouteStateKeyLocator
+  private readonly _readFlatFallback: boolean
+
+  constructor(options: UrlPersisterOptions) {
+    this._router = options.router
+    this._route = options.route
+    this._keys = options.keyLocator ?? dottedKeyLocator
+    this._readFlatFallback = options.readFlatFallback ?? true
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    const state: Record<string, unknown> = {}
+    let found = false
+
+    for (const [storedKey, raw] of Object.entries(this._route.query)) {
+      const key = this._keys.decode(scope, storedKey)
+      if (key === null) continue
+      found = true
+      state[key] = decodeValue(raw)
+    }
+
+    if (found || !this._readFlatFallback) return found ? state : null
+
+    // Nothing under this scope: possibly a link written before the seam
+    // existed. Read it flat rather than showing the wrong screen without a
+    // word — but ONLY keys nobody has scoped. `jobs.page` belongs to the jobs
+    // list, and handing it to this one would be worse than ignoring it.
+    const flat: Record<string, unknown> = {}
+    for (const [storedKey, raw] of Object.entries(this._route.query)) {
+      if (this._keys.looksScoped(storedKey)) continue
+      flat[storedKey] = decodeValue(raw)
+    }
+    return Object.keys(flat).length ? flat : null
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    const query: Record<string, UrlPersisterQueryValue> = { ...toQuery(this._route.query) }
+
+    for (const [key, value] of Object.entries(state)) {
+      const param = this._keys.encode(scope, key)
+      // A flat key left by an older link would shadow the prefixed one on the
+      // next read, so writing a scope also retires its legacy twin.
+      if (this._readFlatFallback && param !== key) delete query[key]
+      // Absent, not stored empty: a pristine screen leaves a clean link.
+      if (value === null || value === undefined || value === '') delete query[param]
+      else query[param] = encodeValue(value)
+    }
+
+    this._router.replace({ query })
+  }
+
+  clear(scope: string): void {
+    const query: Record<string, UrlPersisterQueryValue> = { ...toQuery(this._route.query) }
+    let scoped = false
+    for (const storedKey of Object.keys(query)) {
+      if (this._keys.decode(scope, storedKey) === null) continue
+      scoped = true
+      delete query[storedKey]
+    }
+
+    // Clear what read() would have READ, or the URL starts lying: arrive on a
+    // pre-scope `?page=4` link, clear the filters, and the list shows page 1
+    // under an address still claiming page 4 — and a refresh would restore
+    // the state that was just cleared.
+    if (!scoped && this._readFlatFallback) {
+      for (const storedKey of Object.keys(query)) {
+        if (!this._keys.looksScoped(storedKey)) delete query[storedKey]
+      }
+    }
+
+    this._router.replace({ query })
+  }
+}
+
+/**
+ * A value on its way into a URL.
+ *
+ * Primitives stay readable — `page=2`, not `page=%222%22` — because a query
+ * string people paste into tickets is worth more than perfect round-tripping.
+ * Objects and arrays are JSON, which `decodeValue` recognises by its opening
+ * brace.
+ */
+function encodeValue(value: unknown): string {
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+/**
+ * And on its way back out.
+ *
+ * The coercion is deliberately the one `restoreFilters` already applied to
+ * query params, so behaviour does not shift underneath anyone: `'true'`
+ * becomes a boolean, a numeric string becomes a number.
+ *
+ * It follows that a filter whose value is the STRING `'42'` comes back as the
+ * NUMBER 42. That was already true before this seam existed; it is written
+ * down here rather than left to be rediscovered.
+ *
+ * BUT ONLY WHEN NOTHING IS LOST (#2147). `'007'` is not the number 7 and
+ * `'9876667194123456789'` is not the float it would become — those are text
+ * that merely looks numeric, and coercing them hands the app a value the user
+ * never typed. So the coercion happens only when it round-trips exactly, and
+ * anything else stays the string it was. Reference numbers, invoice ids and
+ * phone numbers all live in that gap, and a search box is full of them.
+ */
+function decodeValue(raw: unknown): unknown {
+  if (Array.isArray(raw)) return raw.map(decodeValue)
+  if (typeof raw !== 'string') return raw
+
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  if (raw === 'null') return null
+  if (raw !== '' && !Number.isNaN(Number(raw))) {
+    const asNumber = Number(raw)
+    // The round-trip test IS the rule: if the number cannot be written back
+    // as the exact same text, the text was never a number.
+    if (String(asNumber) === raw) return asNumber
+    return raw
+  }
+
+  const first = raw[0]
+  if (first === '{' || first === '[') {
+    try {
+      return JSON.parse(raw)
+    } catch {
+      // Not JSON after all — a filter value that merely starts with a brace.
+      return raw
+    }
+  }
+
+  return raw
+}
+
+/** The live route's query, narrowed to what we may hand back to the router. */
+function toQuery(query: Record<string, unknown>): Record<string, UrlPersisterQueryValue> {
+  const out: Record<string, UrlPersisterQueryValue> = {}
+  for (const [key, value] of Object.entries(query)) {
+    if (value === null || value === undefined) continue
+    // An array param is one vue-router supports and we do not produce; keep
+    // its first value rather than dropping the key entirely.
+    out[key] = Array.isArray(value) ? (value[0] as UrlPersisterQueryValue) : (String(value) as string)
+  }
+  return out
+}

package/src/routeState/WebStoragePersister.ts

@@ -0,0 +1,149 @@
+/**
+ * Route state in `localStorage` or `sessionStorage` (#2146).
+ *
+ * The medium you pick when the state is worth keeping but not worth putting
+ * in a link: a back-office list somebody returns to twenty times a day, whose
+ * URL nobody ever sends anyone.
+ *
+ * ONE ENTRY PER KEY, namespaced — `qdadm:offers:page`. Not one JSON blob per
+ * scope, because web storage is shared with everything else the app keeps
+ * there, and per-key namespacing is what lets this persister pick out its own
+ * entries without owning the medium. It also means devtools shows you
+ * readable state instead of a blob to decode by hand.
+ *
+ * VALUES ARE JSON, so they come back exactly as they went in. That differs
+ * from `UrlPersister`, which coerces (`'42'` reads back as the number 42)
+ * because a query string is meant to be read by people. A list moved from one
+ * to the other can therefore see a filter value change TYPE — worth knowing
+ * before you switch a screen that compares with `===`.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+import { namespacedKeyLocator, type RouteStateKeyLocator } from './keyLocator'
+
+/** The bit of the Storage API this needs, so a test needs no browser. */
+export interface RouteStateStorage {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+  readonly length: number
+  key(index: number): string | null
+}
+
+export interface WebStoragePersisterOptions {
+  /** `window.localStorage` or `window.sessionStorage`, or a stand-in. */
+  storage: RouteStateStorage
+  /** For diagnostics — which medium answered. */
+  name?: string
+  /** How a (scope, key) pair becomes a storage key. Defaults to `qdadm:scope:key`. */
+  keyLocator?: RouteStateKeyLocator
+}
+
+export class WebStoragePersister implements RouteStatePersister {
+  readonly name: string
+
+  private readonly _storage: RouteStateStorage
+  private readonly _keys: RouteStateKeyLocator
+  private _warned = false
+
+  constructor(options: WebStoragePersisterOptions) {
+    this._storage = options.storage
+    this._keys = options.keyLocator ?? namespacedKeyLocator
+    this.name = options.name ?? 'web-storage'
+  }
+
+  /**
+   * Web storage throws rather than returning null in more situations than
+   * people expect: Safari's private mode, a browser set to block site data,
+   * a quota that filled up.
+   *
+   * We warn ONCE and carry on with the screen working. That is not the silent
+   * no-op [ADR 0011](../../docs/adr/0011-no-silent-no-ops.md) forbids — the
+   * failure is announced, and it is the environment's, not a mistake in the
+   * app's configuration. Taking the list down because a page number could not
+   * be remembered would be the worse trade.
+   */
+  private _guard<T>(operation: () => T, fallback: T): T {
+    try {
+      return operation()
+    } catch (error) {
+      if (!this._warned) {
+        this._warned = true
+        console.warn(
+          `[qdadm] Route-state persister "${this.name}" cannot reach its storage; ` +
+            `this screen will not remember its state. ` +
+            `Usually private browsing, blocked site data, or a full quota.`,
+          error
+        )
+      }
+      return fallback
+    }
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    return this._guard(() => {
+      const state: Record<string, unknown> = {}
+      let found = false
+
+      for (const storedKey of this._ownKeys(scope)) {
+        const key = this._keys.decode(scope, storedKey)
+        if (key === null) continue
+        const raw = this._storage.getItem(storedKey)
+        if (raw === null) continue
+        found = true
+        state[key] = decode(raw)
+      }
+
+      return found ? state : null
+    }, null)
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    this._guard(() => {
+      for (const [key, value] of Object.entries(state)) {
+        const storedKey = this._keys.encode(scope, key)
+        // Absent, not stored empty — the same rule every persister follows,
+        // so a pristine screen leaves no trace whichever medium it uses.
+        if (value === null || value === undefined || value === '') {
+          this._storage.removeItem(storedKey)
+        } else {
+          this._storage.setItem(storedKey, JSON.stringify(value))
+        }
+      }
+    }, undefined)
+  }
+
+  clear(scope: string): void {
+    this._guard(() => {
+      for (const storedKey of this._ownKeys(scope)) {
+        if (this._keys.decode(scope, storedKey) !== null) this._storage.removeItem(storedKey)
+      }
+    }, undefined)
+  }
+
+  /**
+   * Snapshot the key names before touching anything.
+   *
+   * `Storage.key(i)` walks a live collection: removing as you iterate
+   * renumbers what is left and skips entries. Reading the names first is the
+   * difference between clearing a scope and clearing every other one of it.
+   */
+  private _ownKeys(scope: string): string[] {
+    const keys: string[] = []
+    for (let i = 0; i < this._storage.length; i++) {
+      const key = this._storage.key(i)
+      if (key !== null && this._keys.decode(scope, key) !== null) keys.push(key)
+    }
+    return keys
+  }
+}
+
+function decode(raw: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    // Written by something other than us, or truncated. Hand back the string
+    // rather than dropping the key: a readable wrong value beats a silent
+    // absent one.
+    return raw
+  }
+}

package/src/routeState/defaultPersister.ts

@@ -0,0 +1,66 @@
+/**
+ * What a list uses when nobody chose (#2146).
+ *
+ * Not simply `UrlPersister`, because not all list state wants the same
+ * medium. Filters, search and the page belong in a link — that is the whole
+ * argument for the URL being the default. Rows-per-page does not: it is a
+ * comfort setting somebody picked once, and a link carrying it would impose
+ * the sender's row count on the reader.
+ *
+ * So the default is a composition, and it says out loud what qdadm was
+ * already doing by accident:
+ *
+ * | State | Medium | Scope |
+ * |---|---|---|
+ * | filters, search, page | query string | the list |
+ * | `pageSize` | cookie, a year | the app |
+ * | `sort` | `sessionStorage` | the list |
+ *
+ * **Sort stays in the session** — decided on #2146 rather than moved to the
+ * URL. Moving it would make a list link carry its ordering, which is a real
+ * gain; it would also mean the sort no longer survives opening a clean
+ * `/offers`, which it has always done. Between a gain nobody asked for and a
+ * loss every existing user would feel, the seam is worth having without the
+ * behaviour change: this expresses today's arrangement rather than replacing
+ * it.
+ */
+import { CompositePersister } from './CompositePersister'
+import { CookiePersister, type CookieJar } from './CookiePersister'
+import { WebStoragePersister, type RouteStateStorage } from './WebStoragePersister'
+import { UrlPersister, type UrlPersisterRoute, type UrlPersisterRouter } from './UrlPersister'
+import type { RouteStatePersister } from './RouteStatePersister'
+
+export interface DefaultRouteStateOptions {
+  router: UrlPersisterRouter
+  route: UrlPersisterRoute
+  /** Stand-in for `document`, for a test or an environment without one. */
+  cookieJar?: CookieJar
+  /** Stand-in for `sessionStorage`, same reason. */
+  sessionStorage?: RouteStateStorage
+}
+
+/** The scope `pageSize` is remembered under: one setting for the whole app. */
+export const APP_ROUTE_STATE_SCOPE = 'app'
+
+export function createDefaultRouteStatePersister(
+  options: DefaultRouteStateOptions
+): RouteStatePersister {
+  const session = new WebStoragePersister({
+    storage: options.sessionStorage ?? globalThis.sessionStorage,
+    name: 'session_storage',
+  })
+
+  return new CompositePersister({
+    fallback: new UrlPersister(options),
+    keys: {
+      pageSize: {
+        persister: new CookiePersister(options.cookieJar ? { jar: options.cookieJar } : {}),
+        scope: APP_ROUTE_STATE_SCOPE,
+      },
+      // Per-list, unlike pageSize: an ordering belongs to the screen you were
+      // looking at, not to the whole app.
+      sort: { persister: session },
+      sortOrder: { persister: session },
+    },
+  })
+}

package/src/routeState/factory.ts

@@ -0,0 +1,86 @@
+/**
+ * Slugs to persisters (#2146).
+ *
+ * Mirrors what `entity/storage/factory.ts` does for storages — an instance, or
+ * a name the framework knows — so a consumer meets one convention rather than
+ * two.
+ *
+ * | Slug | Medium | Reach for it when |
+ * |---|---|---|
+ * | `default` | query string + cookie | what a list uses when nobody chose |
+ * | `url` | query string | EVERYTHING in the link, row count included |
+ * | `local_storage` | `localStorage` | worth keeping, not worth linking |
+ * | `session_storage` | `sessionStorage` | worth keeping until the tab closes |
+ * | `cookie` | one cookie per scope | the SERVER needs to read it |
+ * | `memory` | a shared Map | survives navigation, not a reload |
+ * | `none` | nowhere | this screen forgets, and says so |
+ */
+import type { RouteStatePersister, RouteStatePersisterFactory } from './RouteStatePersister'
+import { UrlPersister, type UrlPersisterRoute, type UrlPersisterRouter } from './UrlPersister'
+import { WebStoragePersister, type RouteStateStorage } from './WebStoragePersister'
+import { CookiePersister, type CookieJar } from './CookiePersister'
+import { MemoryPersister } from './MemoryPersister'
+import { NullPersister } from './NullPersister'
+import { createDefaultRouteStatePersister } from './defaultPersister'
+
+export interface RouteStateFactoryContext {
+  router: UrlPersisterRouter
+  route: UrlPersisterRoute
+  /**
+   * Overrides for the browser globals the storage-backed slugs reach for.
+   *
+   * Only needed off a browser — SSR, or a test that would rather not share
+   * one `localStorage` between cases. Left alone, each slug uses the real
+   * thing, resolved AT BUILD TIME rather than captured here, so a factory
+   * created before the app mounts still works.
+   */
+  localStorage?: RouteStateStorage
+  sessionStorage?: RouteStateStorage
+  cookieJar?: CookieJar
+}
+
+/**
+ * The built-in factory.
+ *
+ * Returns null for a slug it does not know — the CALLER throws, with the name
+ * in the message. Returning a default here would make an unknown slug behave
+ * like `url` and say nothing, which is the failure ADR 0011 forbids and the
+ * one this seam is cleaning up after.
+ */
+export function createRouteStatePersisterFactory(
+  context: RouteStateFactoryContext
+): RouteStatePersisterFactory {
+  return (slug: string): RouteStatePersister | null => {
+    switch (slug) {
+      // Nameable, so "the default, stated out loud" has a way to be said.
+      // It is NOT `url`: the default routes `pageSize` to a cookie, because a
+      // link should not impose the sender's row count on its reader.
+      case 'default':
+        return createDefaultRouteStatePersister({
+          router: context.router,
+          route: context.route,
+          cookieJar: context.cookieJar,
+        })
+      case 'url':
+        return new UrlPersister(context)
+      case 'local_storage':
+        return new WebStoragePersister({
+          storage: context.localStorage ?? globalThis.localStorage,
+          name: 'local_storage',
+        })
+      case 'session_storage':
+        return new WebStoragePersister({
+          storage: context.sessionStorage ?? globalThis.sessionStorage,
+          name: 'session_storage',
+        })
+      case 'cookie':
+        return new CookiePersister(context.cookieJar ? { jar: context.cookieJar } : {})
+      case 'memory':
+        return new MemoryPersister()
+      case 'none':
+        return new NullPersister()
+      default:
+        return null
+    }
+  }
+}

package/src/routeState/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Route-state persistence (#2146).
+ *
+ * The seam that decides WHERE a route remembers what it is showing. The list
+ * is one consumer; a detail page's active tab and a dashboard's date range
+ * are the same problem.
+ */
+export type {
+  RouteStatePersister,
+  RouteStateScope,
+  RouteStatePersisterSpec,
+  RouteStatePersisterFactory,
+} from './RouteStatePersister'
+export { isRouteStatePersister, resolveRouteStatePersister } from './RouteStatePersister'
+export { UrlPersister } from './UrlPersister'
+export type { UrlPersisterOptions, UrlPersisterRouter, UrlPersisterRoute } from './UrlPersister'
+export { createRouteStatePersisterFactory } from './factory'
+export { dottedKeyLocator, namespacedKeyLocator } from './keyLocator'
+export type { RouteStateKeyLocator } from './keyLocator'
+export { WebStoragePersister } from './WebStoragePersister'
+export type { WebStoragePersisterOptions, RouteStateStorage } from './WebStoragePersister'
+export { CookiePersister } from './CookiePersister'
+export type { CookiePersisterOptions, CookieJar } from './CookiePersister'
+export { MemoryPersister, clearRouteStateMemory } from './MemoryPersister'
+export type { MemoryPersisterOptions, RouteStateMemoryStore } from './MemoryPersister'
+export { NullPersister } from './NullPersister'
+export { underscoreScopeLocator } from './keyLocator'
+export type { RouteStateScopeLocator } from './keyLocator'
+export type { RouteStateFactoryContext } from './factory'
+export { CompositePersister } from './CompositePersister'
+export type { CompositePersisterOptions, RoutedKey } from './CompositePersister'
+export { createDefaultRouteStatePersister } from './defaultPersister'

package/src/routeState/keyLocator.ts

@@ -0,0 +1,84 @@
+/**
+ * How a (scope, key) pair becomes a stored key — and back (#2146).
+ *
+ * Hard-coding `offers.page` inside the URL persister would make the naming
+ * scheme a property of qdadm rather than of the app. An app that wants
+ * `o_page`, or a single packed parameter, or a `[]`-suffixed convention its
+ * backend already understands, must be able to say so — the same way it can
+ * already override how a storage is resolved.
+ *
+ * ONE PER PERSISTER TYPE, because the right scheme differs by medium: dots
+ * read well in a query string, colons are the convention in `localStorage`,
+ * and a cookie has its own constraints entirely.
+ *
+ * `decode` returns null for a key that is not ours. That is what lets a
+ * persister pick its own entries out of a medium it shares with everything
+ * else — the whole reason the scope exists.
+ */
+export interface RouteStateKeyLocator {
+  encode(scope: string, key: string): string
+  /** The bare key, or null when this stored key belongs to someone else. */
+  decode(scope: string, storedKey: string): string | null
+  /**
+   * Whether this key carries a scope at all — ANY scope, not just one.
+   *
+   * A legacy-compatibility reader needs this: `offers.page` and `jobs.page`
+   * both belong to somebody, and treating them as unscoped leftovers would
+   * hand one list the other's state. Only a key that is scoped by nobody can
+   * be read as pre-scope state.
+   */
+  looksScoped(storedKey: string): boolean
+  readonly name: string
+}
+
+/** `offers` + `page` → `offers.page`. The default in a query string. */
+export const dottedKeyLocator: RouteStateKeyLocator = {
+  name: 'dotted',
+  encode: (scope, key) => (scope ? `${scope}.${key}` : key),
+  decode: (scope, storedKey) => {
+    if (!scope) return storedKey
+    const prefix = `${scope}.`
+    return storedKey.startsWith(prefix) ? storedKey.slice(prefix.length) : null
+  },
+  looksScoped: (storedKey) => storedKey.includes('.'),
+}
+
+/** `offers` + `page` → `qdadm:offers:page`. The default in web storage. */
+export const namespacedKeyLocator: RouteStateKeyLocator = {
+  name: 'namespaced',
+  encode: (scope, key) => `qdadm:${scope}:${key}`,
+  decode: (scope, storedKey) => {
+    const prefix = `qdadm:${scope}:`
+    return storedKey.startsWith(prefix) ? storedKey.slice(prefix.length) : null
+  },
+  looksScoped: (storedKey) => storedKey.startsWith('qdadm:'),
+}
+
+/**
+ * How a SCOPE becomes a stored name, for media that keep one entry per scope.
+ *
+ * The cookie jar is the case: a cookie rides on every request, so a scope
+ * gets one cookie holding a blob rather than one per key. There is no key
+ * half to encode, which is why this is its own small interface rather than
+ * `RouteStateKeyLocator` called with a key nobody uses.
+ */
+export interface RouteStateScopeLocator {
+  encode(scope: string): string
+  /** The bare scope, or null when this stored name belongs to someone else. */
+  decode(storedName: string): string | null
+  readonly name: string
+}
+
+/**
+ * `offers` → `qdadm_offers`. The default in a cookie jar.
+ *
+ * Underscores rather than the colons web storage uses: a cookie NAME is an
+ * RFC 6265 token, and `:` is a separator there. `qdadm:offers` is not a
+ * cookie name a server is obliged to accept.
+ */
+export const underscoreScopeLocator: RouteStateScopeLocator = {
+  name: 'underscore',
+  encode: (scope) => `qdadm_${scope}`,
+  decode: (storedName) =>
+    storedName.startsWith('qdadm_') ? storedName.slice('qdadm_'.length) : null,
+}

package/src/security/RolesProvider.ts

@@ -70,6 +70,14 @@ export interface RoleProviderContext {
   orchestrator?: {
     get: (name: string) => unknown
   }
+  /**
+   * The live permission registry (#2225) — a reference, not a snapshot:
+   * `install` runs before modules register their entities, so read
+   * `getKeys()` later, when you actually fetch.
+   */
+  permissionRegistry?: {
+    getKeys: () => string[]
+  }
   [key: string]: unknown
 }