@quazardous/qdadm 2.14.0 → 2.16.0

package/src/kernel/Kernel.registries.ts

@@ -9,6 +9,7 @@ import { defaultStorageResolver } from '../entity/storage/factory'
 import { createDeferredRegistry } from '../deferred/DeferredRegistry.js'
 import { createEventRouter } from './EventRouter'
 import { createSSEBridge } from './SSEBridge'
+import { createLiveEntityRouter, type LiveOrchestratorLike } from './LiveEntityRouter'
 import { ActiveStack } from '../chain/ActiveStack.js'
 import { StackHydrator } from '../chain/StackHydrator.js'
 import { Orchestrator } from '../orchestrator/Orchestrator'
@@ -222,9 +223,14 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     const debug = this.options.debug ?? false
 
-    const getToken = authAdapter?.getToken
-      ? () => authAdapter.getToken!()
-      : () => localStorage.getItem('auth_token')
+    // An explicit sse.getToken wins — including an explicit null, which means
+    // "send no token" and must not fall back to the auth adapter.
+    const getToken =
+      sse.getToken !== undefined
+        ? sse.getToken
+        : authAdapter?.getToken
+          ? () => authAdapter.getToken!()
+          : () => localStorage.getItem('auth_token')
 
     this.sseBridge = createSSEBridge({
       signals: this.signals!,
@@ -235,13 +241,33 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       withCredentials: sse.withCredentials ?? false,
       tokenParam: sse.tokenParam ?? 'token',
       getToken,
+      ...(sse.connectOnSignal !== undefined ? { connectOnSignal: sse.connectOnSignal } : {}),
+      ...(sse.disconnectOnSignal !== undefined ? { disconnectOnSignal: sse.disconnectOnSignal } : {}),
       debug,
     })
 
-    if (sse.events?.length) {
+    // The declared entities imply their own frames: an app that declares
+    // `entities` should not also have to remember to list the event names.
+    const declaredEvents = sse.entities
+      ? ['entity:created', 'entity:updated', 'entity:deleted']
+      : []
+    const events = [...new Set([...(sse.events ?? []), ...declaredEvents])]
+
+    if (events.length) {
       this.signals!.once('sse:connected', () => {
-        this.sseBridge!.registerEvents(sse.events!)
+        this.sseBridge!.registerEvents(events)
+      })
+    }
+
+    if (sse.entities) {
+      this.liveEntityRouter = createLiveEntityRouter({
+        signals: this.signals!,
+        entities: sse.entities,
+        orchestrator: this.orchestrator as unknown as LiveOrchestratorLike,
+        signalPrefix: sse.signalPrefix ?? 'sse',
+        debug,
       })
+      this.liveEntityRouter.attachSignalTransport()
     }
   }
 }

package/src/kernel/Kernel.ts

@@ -39,6 +39,7 @@ import type { KernelContext } from './KernelContext'
 import type { DeferredRegistry } from '../deferred/DeferredRegistry.js'
 import type { EventRouter } from './EventRouter'
 import type { SSEBridge } from './SSEBridge'
+import type { LiveEntityRouter } from './LiveEntityRouter'
 import type { ActiveStack } from '../chain/ActiveStack.js'
 import type { StackHydrator } from '../chain/StackHydrator.js'
 import { NotificationModule } from '../notifications/NotificationModule'
@@ -89,6 +90,8 @@ export class Kernel {
   deferred: DeferredRegistry | null = null
   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

package/src/kernel/Kernel.types.ts

@@ -109,6 +109,37 @@ export interface SSEConfig {
   withCredentials?: boolean
   tokenParam?: string
   events?: string[]
+  /**
+   * Entities this backend writes to out of session.
+   *
+   * The APP declares what it knows about the backend — the backend knows
+   * nothing of this config, it only emits. Declaring an entity here routes the
+   * stream's `entity:{created,updated,deleted}` frames to that entity's cache
+   * invalidation; anything not declared is ignored (a stream carries more than
+   * entity mutations). `true` or `'*'` accepts every registered entity.
+   *
+   * See docs/adr/0009-live-entities.md.
+   */
+  entities?: string[] | true | '*'
+  /**
+   * Token appended to the SSE URL as a query parameter.
+   *
+   * Defaults to the session auth adapter's token. Override it — the function
+   * may be async — when that durable credential must not reach an access log:
+   * return a short-lived, single-use ticket fetched per connect instead. Pass
+   * `null` to send no token at all (e.g. cookie auth with `withCredentials`).
+   */
+  getToken?: (() => string | null | Promise<string | null>) | null
+  /**
+   * Signal that triggers a connect. Defaults to `'auth:login'`;
+   * `null` disables the auth coupling.
+   */
+  connectOnSignal?: string | null
+  /**
+   * Signal that triggers a disconnect. Defaults to `'auth:logout'`;
+   * `null` disables the auth coupling.
+   */
+  disconnectOnSignal?: string | null
 }
 
 /**

package/src/kernel/LiveEntityRouter.ts

@@ -0,0 +1,189 @@
+/**
+ * LiveEntityRouter — turns "something changed elsewhere" into cache
+ * invalidation for the right EntityManager (#1888 lot C, reported in #1887).
+ *
+ * The transport is deliberately not part of this class. Its entry point is
+ * `notify()`, a plain fact: *this entity changed, possibly this record*. SSE is
+ * wired on top by `attachSignalTransport()`, and a WebSocket or a
+ * `BroadcastChannel` between two tabs of the same admin would attach the same
+ * way — see docs/adr/0009-live-entities.md.
+ *
+ * Two boundaries the ADR fixes and this class enforces:
+ *
+ * - **The event carries a fact, never an instruction.** Nothing in the payload
+ *   may tell the front what to do; the payload says what changed and the front
+ *   decides what that implies.
+ * - **The security scope is the front's.** An event never causes a request the
+ *   current user could not have issued: an entity they cannot read is dropped
+ *   rather than refetched, otherwise every pushed event sprays 401/403.
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ */
+
+import type { SignalBus } from './SignalBus'
+
+/** The actions a live event can report. */
+export type LiveEntityAction = 'created' | 'updated' | 'deleted'
+
+/**
+ * Which entities the app declares as having an external writer.
+ * `true` / `'*'` accepts every registered entity.
+ */
+export type LiveEntitiesDeclaration = string[] | true | '*'
+
+/** Minimal orchestrator surface this router needs. */
+export interface LiveOrchestratorLike {
+  has(name: string): boolean
+  get(name: string): { canRead?: () => boolean } | undefined
+}
+
+export interface LiveEntityRouterOptions {
+  signals: SignalBus
+  /** Entities declared as externally written. */
+  entities: LiveEntitiesDeclaration
+  /** Used to resolve the manager for the permission check. */
+  orchestrator?: LiveOrchestratorLike | null
+  /** Signal prefix the transport publishes under (default: 'sse'). */
+  signalPrefix?: string
+  debug?: boolean
+}
+
+/** Payload shape a transport frame is expected to carry. */
+interface LiveFramePayload {
+  entity?: string
+  id?: string | number
+  action?: LiveEntityAction
+}
+
+const ACTION_BY_EVENT: Record<string, LiveEntityAction> = {
+  'entity:created': 'created',
+  'entity:updated': 'updated',
+  'entity:deleted': 'deleted',
+}
+
+export class LiveEntityRouter {
+  private _signals: SignalBus
+  private _entities: LiveEntitiesDeclaration
+  private _orchestrator: LiveOrchestratorLike | null
+  private _signalPrefix: string
+  private _debug: boolean
+  private _cleanups: Array<() => void> = []
+  /** Entities seen on the wire but never declared — warned about once each. */
+  private _warned = new Set<string>()
+
+  constructor(options: LiveEntityRouterOptions) {
+    const {
+      signals,
+      entities,
+      orchestrator = null,
+      signalPrefix = 'sse',
+      debug = false,
+    } = options
+
+    if (!signals) throw new Error('[LiveEntityRouter] signals (SignalBus) is required')
+
+    this._signals = signals
+    this._entities = entities
+    this._orchestrator = orchestrator
+    this._signalPrefix = signalPrefix
+    this._debug = debug
+  }
+
+  /** Is this entity declared as externally written? */
+  isDeclared(entity: string): boolean {
+    if (this._entities === true || this._entities === '*') return true
+    return Array.isArray(this._entities) && this._entities.includes(entity)
+  }
+
+  /**
+   * Report an external change. Transport-agnostic entry point.
+   *
+   * @returns true when the change was routed, false when it was dropped
+   *   (undeclared entity, unknown manager, or one the user cannot read).
+   */
+  notify(entity: string, action: LiveEntityAction = 'updated', id?: string | number): boolean {
+    if (!entity) return false
+
+    if (!this.isDeclared(entity)) {
+      // Not an error: a stream carries more than entity mutations. But a
+      // silently dropped frame is the hardest kind of bug to find, so say it
+      // once per entity in dev.
+      if (!this._warned.has(entity)) {
+        this._warned.add(entity)
+        this._log(
+          `Ignoring a live event for "${entity}": not declared in sse.entities. ` +
+            `Add it there if this backend writes to it out of session.`
+        )
+      }
+      return false
+    }
+
+    // has() first: Orchestrator.get() THROWS for an unknown name (it is built
+    // to catch developer typos loudly). Letting that escape would blow up
+    // inside the signal bus on every incoming frame — a declared entity whose
+    // module is lazily loaded, or a typo in sse.entities, must degrade to a
+    // dropped event, not to an exception storm.
+    let manager: { canRead?: () => boolean } | undefined
+    if (this._orchestrator) {
+      if (!this._orchestrator.has(entity)) {
+        this._log(`Ignoring a live event for "${entity}": no manager registered under that name.`)
+        return false
+      }
+      manager = this._orchestrator.get(entity)
+    }
+
+    // The security scope is the front's: never refetch what this user could not
+    // have asked for in the first place.
+    if (manager?.canRead && !manager.canRead()) {
+      this._log(`Ignoring a live event for "${entity}": current user cannot read it.`)
+      return false
+    }
+
+    this._signals.emit('entity:data-invalidate', {
+      entity,
+      action,
+      id,
+      source: 'remote',
+    })
+    this._signals.emitEntity?.(entity, action, { id, source: 'remote' })
+
+    this._log(`Routed ${action} on "${entity}"${id !== undefined ? ` (id ${id})` : ''}`)
+    return true
+  }
+
+  /**
+   * Subscribe to the transport's frames on the signal bus.
+   *
+   * Recognises `{prefix}:entity:{created,updated,deleted}` carrying
+   * `{ entity, id? }` — the contract validated downstream in #1887.
+   */
+  attachSignalTransport(): void {
+    for (const [event, action] of Object.entries(ACTION_BY_EVENT)) {
+      const signal = `${this._signalPrefix}:${event}`
+      this._cleanups.push(
+        this._signals.on(signal, (received: { name: string; data: unknown }) => {
+          const frame = (received?.data ?? {}) as { data?: LiveFramePayload }
+          // Transports wrap the decoded body in `data` (see SSEBridge); accept
+          // a bare payload too so a non-SSE caller isn't forced to fake it.
+          const payload = (frame.data ?? frame) as LiveFramePayload
+          if (!payload?.entity) return
+          this.notify(payload.entity, payload.action ?? action, payload.id)
+        })
+      )
+    }
+  }
+
+  /** Drop every subscription. */
+  destroy(): void {
+    this._cleanups.forEach((off) => off())
+    this._cleanups = []
+  }
+
+  private _log(...args: unknown[]): void {
+    if (this._debug) console.debug('[LiveEntityRouter]', ...args)
+  }
+}
+
+export function createLiveEntityRouter(options: LiveEntityRouterOptions): LiveEntityRouter {
+  return new LiveEntityRouter(options)
+}

package/src/kernel/SSEBridge.ts

@@ -5,6 +5,9 @@
  * shared with qdcms. The auth-aware connect/disconnect behaviour is now
  * configurable via `connectOnSignal` / `disconnectOnSignal` options; defaults
  * remain `'auth:login'` / `'auth:logout'` for backwards compatibility.
+ *
+ * @experimental Signal mapping and reconnection options may change in a minor
+ * release — see docs/API_STABILITY.md.
  */
 
 export { SSEBridge, createSSEBridge, SSE_SIGNALS } from '@quazardous/qdcore'

package/src/query/index.ts

@@ -2,6 +2,13 @@
  * Query Module - MongoDB-like filtering for arrays
  *
  * Provides client-side filtering with the same query syntax used for API calls.
+ *
+ * @experimental Applies to the EXECUTOR CLASSES below, used directly. The query
+ * object syntax they interpret (`{ field: { $in: [...] } }`) is stable — it is
+ * what list filters and EntityManager.query() speak. See
+ * docs/API_STABILITY.md.
+ *
+ * @module query
  */
 
 export { QueryExecutor, getNestedValue } from './QueryExecutor'

package/src/types/index.ts

@@ -164,6 +164,8 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   readOnly?: boolean
   warmup?: boolean
   authSensitive?: boolean
+  /** What this entity does when it changed elsewhere (#1888). */
+  live?: { refresh?: 'mounted' | false; coalesceMs?: number }
   system?: boolean
   scopeWhitelist?: string[] | null
   isOwn?: ((record: T, user: unknown) => boolean) | null