@camstack/system 1.2.390 → 1.2.392

package/dist/kernel/moleculer/device-event-ring.d.ts

@@ -1,113 +1,155 @@
-import { SystemEvent } from '@camstack/types';
+/**
+* Per-device event rings — the history a single camera's Events panel reads.
+*
+* WHY THIS EXISTS. The retaining bus keeps ONE global ring
+* (`SharedBusState.recent`, {@link MAX_RECENT_EVENTS}). That ring is a COUNT,
+* not a window, and it is shared by the whole fleet, so a quiet camera is
+* evicted by its 31 noisy siblings long before the operator opens its panel.
+* Measured on the live hub: 16 events/s fleet-wide, 817 B average per event —
+* a 10 000-slot global ring covers 10.4 minutes of FLEET traffic and can hold
+* nothing at all for a camera that emitted an hour ago.
+*
+* WHAT THIS IS NOT. Still telemetry (D8/D11): in-memory, hub-main only, lost on
+* restart, no table, no persistence. Nothing durable may be derived from it.
+*
+* SHAPE. One ring per device id, each holding two disjoint parts:
+*
+*  - `history` — events of categories nobody declared a mirror. Bounded by
+*    {@link MAX_DEVICE_RING_EVENTS}. After coalescing the fleet emits ~1.1
+*    events/s (~3 000/day/camera), so 2 000 slots ≈ 16 h per camera — the day
+*    the operator asked for.
+*  - `mirrors` — the LATEST event per declared-mirror category
+*    ({@link MIRROR_CATEGORIES}). A mirror has no history, only a current
+*    value: the penultimate value of `device.state-changed` means nothing, and
+*    keeping it is what made 89 % of the fleet's traffic evict everything else.
+*    Bounded by the size of the declared set, i.e. a handful of slots.
+*
+* A category NOBODY classified is NOT coalesced. Keeping history is the safe
+* default; silently collapsing an unclassified category would lose data nobody
+* decided to lose.
+*
+* NO deviceId ⇒ NOT HERE. An event that carries no device attribution
+* (`broker.message`, the Home Assistant state mirror, ~64 000/day, carries only
+* `brokerId` / `subscriptionId` / `key`) is a first-class case: it is retained
+* in the GLOBAL ring only and no device is invented for it. If attribution is
+* added later, the event starts landing in a device ring with no change here.
+*
+* MEMORY. The retained `data` payload is capped
+* ({@link MAX_RETAINED_DATA_BYTES}), not the event count — hub-main's heap is
+* not a place to spend 52 MB on telemetry. A capped payload is REPLACED by a
+* marked {@link TruncatedEventData} so a consumer can tell a short payload from
+* a cut one.
+*/
+import type { SystemEvent } from "@camstack/types";
 /** One declared mirror category and the reason it may be collapsed. */
 export interface MirrorCategoryDeclaration {
-    /** Exact event category. Not a glob — a mirror is declared one by one. */
-    readonly category: string;
-    /** Why the penultimate value of this category carries no information. */
-    readonly reason: string;
+	/** Exact event category. Not a glob — a mirror is declared one by one. */
+	readonly category: string;
+	/** Why the penultimate value of this category carries no information. */
+	readonly reason: string;
 }
 /**
- * The categories whose per-device history is ONE slot: the latest value.
- *
- * Declared here, with a reason each, on purpose — the alternative is `if`s
- * scattered over the delivery path, and nobody can then answer "what does this
- * system collapse, and who decided?".
- *
- * Adding an entry DELETES history for that category. Add one only when the
- * category is genuinely a state mirror (a snapshot of a current value), never
- * because it is merely frequent — a frequent EDGE (a motion start, a crash)
- * belongs in `RING_BUFFER_DENY_PATTERNS` or nowhere, not here.
- */
+* The categories whose per-device history is ONE slot: the latest value.
+*
+* Declared here, with a reason each, on purpose — the alternative is `if`s
+* scattered over the delivery path, and nobody can then answer "what does this
+* system collapse, and who decided?".
+*
+* Adding an entry DELETES history for that category. Add one only when the
+* category is genuinely a state mirror (a snapshot of a current value), never
+* because it is merely frequent — a frequent EDGE (a motion start, a crash)
+* belongs in `RING_BUFFER_DENY_PATTERNS` or nowhere, not here.
+*/
 export declare const MIRROR_CATEGORIES: readonly MirrorCategoryDeclaration[];
 /** The declared reason this category is a mirror, or `undefined` if unclassified. */
 export declare function mirrorReason(category: string): string | undefined;
 /**
- * Is this category declared a mirror? An unclassified category is NOT a mirror
- * — the safe default is to keep its history.
- */
+* Is this category declared a mirror? An unclassified category is NOT a mirror
+* — the safe default is to keep its history.
+*/
 export declare function isMirrorCategory(category: string): boolean;
 /**
- * Non-mirror events retained per device. ~1.1 events/s fleet-wide after
- * coalescing ⇒ ~3 000/day/camera ⇒ 2 000 ≈ 16 h.
- */
-export declare const MAX_DEVICE_RING_EVENTS = 2000;
+* Non-mirror events retained per device. ~1.1 events/s fleet-wide after
+* coalescing ⇒ ~3 000/day/camera ⇒ 2 000 ≈ 16 h.
+*/
+export declare const MAX_DEVICE_RING_EVENTS = 2e3;
 /**
- * Cap on the retained `data` payload, in UTF-8 bytes. The COUNT is not what
- * costs memory — 32 devices × 2 000 events × 817 B (measured average) ≈ 52 MB.
- * Capping the payload brings the worst case to ≈ 26 MB and the realistic case
- * far below it, since most events are already under the cap.
- */
+* Cap on the retained `data` payload, in UTF-8 bytes. The COUNT is not what
+* costs memory — 32 devices × 2 000 events × 817 B (measured average) ≈ 52 MB.
+* Capping the payload brings the worst case to ≈ 26 MB and the realistic case
+* far below it, since most events are already under the cap.
+*/
 export declare const MAX_RETAINED_DATA_BYTES = 256;
 /** Bytes of the original JSON kept as a human-readable preview of a cut payload. */
 export declare const TRUNCATED_PREVIEW_BYTES = 160;
 /**
- * Devices tracked at once. Far above the fleet (32) — it exists so a bad
- * deviceId stream cannot grow the map without bound. Eviction is
- * least-recently-written.
- */
+* Devices tracked at once. Far above the fleet (32) — it exists so a bad
+* deviceId stream cannot grow the map without bound. Eviction is
+* least-recently-written.
+*/
 export declare const MAX_TRACKED_DEVICES = 512;
 /** Marker key present on — and only on — a payload this module cut. */
 export declare const TRUNCATED_DATA_KEY = "__truncated";
 /**
- * What replaces a payload above {@link MAX_RETAINED_DATA_BYTES}. A consumer
- * MUST be able to tell a short payload from a cut one, so the replacement says
- * so explicitly rather than silently shipping a prefix.
- */
+* What replaces a payload above {@link MAX_RETAINED_DATA_BYTES}. A consumer
+* MUST be able to tell a short payload from a cut one, so the replacement says
+* so explicitly rather than silently shipping a prefix.
+*/
 export interface TruncatedEventData extends Record<string, unknown> {
-    readonly __truncated: true;
-    /** Size of the original JSON payload, or `null` when it could not be measured. */
-    readonly __originalBytes: number | null;
-    /** First {@link TRUNCATED_PREVIEW_BYTES} characters of the original JSON. */
-    readonly __preview: string;
+	readonly __truncated: true;
+	/** Size of the original JSON payload, or `null` when it could not be measured. */
+	readonly __originalBytes: number | null;
+	/** First {@link TRUNCATED_PREVIEW_BYTES} characters of the original JSON. */
+	readonly __preview: string;
 }
 /** Is this the marked replacement of a cut payload? */
 export declare function isTruncatedEventData(data: Record<string, unknown>): data is TruncatedEventData;
 /**
- * The event as it should be RETAINED: unchanged when its payload is within the
- * cap, otherwise a NEW event whose `data` is the marked replacement. The
- * argument is never mutated — the same object is still live on the fan-out path
- * and in the global ring.
- */
+* The event as it should be RETAINED: unchanged when its payload is within the
+* cap, otherwise a NEW event whose `data` is the marked replacement. The
+* argument is never mutated — the same object is still live on the fan-out path
+* and in the global ring.
+*/
 export declare function capEventData(event: SystemEvent): SystemEvent;
 /**
- * The device this event is about, or `undefined` when it is about no device.
- *
- * Same rule as `matchesEventFilter` — `source.deviceId`, or `source.id` when
- * the source IS a device — so a read filtered by `deviceId` and a read served
- * from that device's ring agree on which events belong to it. A non-numeric
- * device source id yields `undefined` rather than `NaN`: an unattributable
- * event must never become a bucket of its own.
- */
+* The device this event is about, or `undefined` when it is about no device.
+*
+* Same rule as `matchesEventFilter` — `source.deviceId`, or `source.id` when
+* the source IS a device — so a read filtered by `deviceId` and a read served
+* from that device's ring agree on which events belong to it. A non-numeric
+* device source id yields `undefined` rather than `NaN`: an unattributable
+* event must never become a bucket of its own.
+*/
 export declare function eventDeviceId(event: SystemEvent): number | undefined;
 interface DeviceRing {
-    /** Non-mirror events, oldest first, bounded by {@link MAX_DEVICE_RING_EVENTS}. */
-    readonly history: SystemEvent[];
-    /** Latest event per declared-mirror category. */
-    readonly mirrors: Map<string, SystemEvent>;
+	/** Non-mirror events, oldest first, bounded by {@link MAX_DEVICE_RING_EVENTS}. */
+	readonly history: SystemEvent[];
+	/** Latest event per declared-mirror category. */
+	readonly mirrors: Map<string, SystemEvent>;
 }
 /**
- * Every device's ring. Insertion order is least-recently-written first, which
- * is what {@link MAX_TRACKED_DEVICES} evicts by.
- */
+* Every device's ring. Insertion order is least-recently-written first, which
+* is what {@link MAX_TRACKED_DEVICES} evicts by.
+*/
 export interface DeviceEventRings {
-    readonly byDevice: Map<number, DeviceRing>;
+	readonly byDevice: Map<number, DeviceRing>;
 }
 export declare function createDeviceEventRings(): DeviceEventRings;
 /**
- * Retain `event` in its device's ring, with its payload capped.
- *
- * Returns the device it was filed under, or `undefined` when the event names no
- * device — the caller has already retained it in the global ring and nothing
- * more happens here. No device is fabricated.
- */
+* Retain `event` in its device's ring, with its payload capped.
+*
+* Returns the device it was filed under, or `undefined` when the event names no
+* device — the caller has already retained it in the global ring and nothing
+* more happens here. No device is fabricated.
+*/
 export declare function recordDeviceEvent(rings: DeviceEventRings, event: SystemEvent): number | undefined;
 /**
- * Everything retained for one device, oldest first — history merged with the
- * current value of each mirror, ordered by timestamp so the caller's `-limit`
- * slice means the same thing it means on the global ring.
- *
- * An unknown device yields `[]`: unknown is the truth about a camera that has
- * emitted nothing since this process started.
- */
+* Everything retained for one device, oldest first — history merged with the
+* current value of each mirror, ordered by timestamp so the caller's `-limit`
+* slice means the same thing it means on the global ring.
+*
+* An unknown device yields `[]`: unknown is the truth about a camera that has
+* emitted nothing since this process started.
+*/
 export declare function getDeviceRecent(rings: DeviceEventRings, deviceId: number): readonly SystemEvent[];
 export {};

package/dist/kernel/moleculer/event-bus-core.d.ts

@@ -1,186 +1,198 @@
-import { EventFilter, SystemEvent } from '@camstack/types';
-import { DeviceEventRings } from './device-event-ring.js';
+/**
+* Shared event-bus core — pure in-process fan-out logic with NO dependency on
+* Moleculer or any transport layer.
+*
+* Consumed by:
+*  - `event-bus.ts`      (Moleculer broker-backed cluster bus)
+*  - `uds-event-bus.ts`  (UDS-backed child-process bus, C1)
+*
+* Keeping this module transport-free means the UDS bus can reuse every piece
+* of logic (deny-list, subscriber map, filter semantics) without pulling in
+* Moleculer types.
+*/
+import type { EventFilter, SystemEvent } from "@camstack/types";
+import type { DeviceEventRings } from "./device-event-ring.js";
 export interface SubscriberEntry {
-    /** Original filter — kept whole so non-category dimensions are honoured per-event. */
-    readonly filter: EventFilter | string | undefined;
-    /**
-     * Pre-computed category pattern for the cheap pre-filter — the FIRST of
-     * {@link extractCategoryPatterns} when the filter names several. Diagnostic
-     * only: the authority on which keys an entry occupies is the handler map
-     * itself, written by {@link registerSubscriber}.
-     */
-    readonly categoryPattern: string;
-    readonly handler: (event: SystemEvent) => void;
+	/** Original filter — kept whole so non-category dimensions are honoured per-event. */
+	readonly filter: EventFilter | string | undefined;
+	/**
+	* Pre-computed category pattern for the cheap pre-filter — the FIRST of
+	* {@link extractCategoryPatterns} when the filter names several. Diagnostic
+	* only: the authority on which keys an entry occupies is the handler map
+	* itself, written by {@link registerSubscriber}.
+	*/
+	readonly categoryPattern: string;
+	readonly handler: (event: SystemEvent) => void;
 }
 export interface SharedBusState {
-    /**
-     * Subscribers indexed by category pattern. Each entry also carries its full
-     * filter so the subsequent `matchesEventFilter` call can reject events that
-     * match the category but not the scope (deviceId, addonId, …).
-     */
-    readonly handlers: Map<string, Set<SubscriberEntry>>;
-    /**
-     * In-memory recent-events buffer. The deny-list below filters out
-     * high-frequency categories so the buffer only accumulates audit-grade
-     * lifecycle events.
-     *
-     * ONLY populated when `retainRecent` is true (the hub main process). On every
-     * other bus this array stays empty for the process's whole lifetime.
-     *
-     * Cleared on server restart (intentional — events are volatile by design).
-     */
-    readonly recent: SystemEvent[];
-    /**
-     * Per-device rings BESIDE `recent[]` — not a replacement for it.
-     *
-     * `recent[]` is one global, count-bounded ring: a busy fleet evicts a quiet
-     * camera's events out of it long before an operator opens that camera's
-     * panel, and filtering a global ring by device cannot bring them back. A
-     * per-device ask is therefore answered from here instead
-     * (`getBrokerEventBus().getRecent({ deviceId })`), while an ask that names no
-     * device is still answered from `recent[]`.
-     *
-     * Populated under exactly the same conditions as `recent[]` (retaining bus,
-     * category not on the high-frequency deny-list), with mirror categories
-     * coalesced and payloads capped — see `device-event-ring.ts`. An event that
-     * names no device is retained in `recent[]` ONLY; no device is invented for
-     * it.
-     */
-    readonly deviceRings: DeviceEventRings;
-    /**
-     * Whether this bus retains events in `recent[]` to back the
-     * `getRecent`/audit capability.
-     *
-     * Events are one-shot (fire-and-forget): ONLY the hub main process — the
-     * single process that serves `getRecent` — needs the registry, so ONLY its
-     * broker bus sets this true. Child addon runners and remote agents leave it
-     * false: they fan every event out to their local subscribers but retain
-     * nothing, so their heap can never accumulate an unbounded recent[] backlog.
-     *
-     * Mutable so the authoritative opt-in (the hub-main `getBrokerEventBus`
-     * caller) can upgrade a bus that a non-retaining caller happened to create
-     * first — see `getSharedBusState`. Never downgraded from true → false.
-     */
-    retainRecent: boolean;
+	/**
+	* Subscribers indexed by category pattern. Each entry also carries its full
+	* filter so the subsequent `matchesEventFilter` call can reject events that
+	* match the category but not the scope (deviceId, addonId, …).
+	*/
+	readonly handlers: Map<string, Set<SubscriberEntry>>;
+	/**
+	* In-memory recent-events buffer. The deny-list below filters out
+	* high-frequency categories so the buffer only accumulates audit-grade
+	* lifecycle events.
+	*
+	* ONLY populated when `retainRecent` is true (the hub main process). On every
+	* other bus this array stays empty for the process's whole lifetime.
+	*
+	* Cleared on server restart (intentional — events are volatile by design).
+	*/
+	readonly recent: SystemEvent[];
+	/**
+	* Per-device rings BESIDE `recent[]` — not a replacement for it.
+	*
+	* `recent[]` is one global, count-bounded ring: a busy fleet evicts a quiet
+	* camera's events out of it long before an operator opens that camera's
+	* panel, and filtering a global ring by device cannot bring them back. A
+	* per-device ask is therefore answered from here instead
+	* (`getBrokerEventBus().getRecent({ deviceId })`), while an ask that names no
+	* device is still answered from `recent[]`.
+	*
+	* Populated under exactly the same conditions as `recent[]` (retaining bus,
+	* category not on the high-frequency deny-list), with mirror categories
+	* coalesced and payloads capped — see `device-event-ring.ts`. An event that
+	* names no device is retained in `recent[]` ONLY; no device is invented for
+	* it.
+	*/
+	readonly deviceRings: DeviceEventRings;
+	/**
+	* Whether this bus retains events in `recent[]` to back the
+	* `getRecent`/audit capability.
+	*
+	* Events are one-shot (fire-and-forget): ONLY the hub main process — the
+	* single process that serves `getRecent` — needs the registry, so ONLY its
+	* broker bus sets this true. Child addon runners and remote agents leave it
+	* false: they fan every event out to their local subscribers but retain
+	* nothing, so their heap can never accumulate an unbounded recent[] backlog.
+	*
+	* Mutable so the authoritative opt-in (the hub-main `getBrokerEventBus`
+	* caller) can upgrade a bus that a non-retaining caller happened to create
+	* first — see `getSharedBusState`. Never downgraded from true → false.
+	*/
+	retainRecent: boolean;
 }
 /**
- * @param retainRecent - `true` ONLY for the hub main broker bus (it serves
- *   `getRecent`). Defaults to `false` — the safe one-shot default for child
- *   runners + agents, which retain nothing.
- */
+* @param retainRecent - `true` ONLY for the hub main broker bus (it serves
+*   `getRecent`). Defaults to `false` — the safe one-shot default for child
+*   runners + agents, which retain nothing.
+*/
 export declare function createSharedBusState(retainRecent?: boolean): SharedBusState;
 export declare function matchesPattern(pattern: string, category: string): boolean;
 /**
- * The FIRST category pattern of a filter.
- *
- * Kept for the diagnostic `SubscriberEntry.categoryPattern` field and for
- * callers that genuinely want one string. It is NOT the registration path:
- * a filter naming several categories must occupy several map keys, which is
- * what {@link extractCategoryPatterns} + {@link registerSubscriber} do. Using
- * this function to key a subscriber is the bug described on
- * `extractCategoryPatterns`.
- */
+* The FIRST category pattern of a filter.
+*
+* Kept for the diagnostic `SubscriberEntry.categoryPattern` field and for
+* callers that genuinely want one string. It is NOT the registration path:
+* a filter naming several categories must occupy several map keys, which is
+* what {@link extractCategoryPatterns} + {@link registerSubscriber} do. Using
+* this function to key a subscriber is the bug described on
+* `extractCategoryPatterns`.
+*/
 export declare function extractCategoryPattern(filter: EventFilter | string): string;
 /**
- * EVERY category pattern a filter asks for — the registration key set.
- *
- * `EventFilter.category` has always accepted an array, and until 2026-08-12
- * the delivery path kept only `cat[0]`. Inside a forked runner that was not
- * merely a local filter: `createUdsEventBus` reports its handler-map keys to
- * the parent as this child's forwarding interest, so the categories that never
- * became keys were never forwarded across the process boundary at all. A
- * ten-category subscribe received one category, silently.
- *
- * Duplicates are collapsed so a filter that names the same category twice does
- * not put the entry in one key twice.
- */
+* EVERY category pattern a filter asks for — the registration key set.
+*
+* `EventFilter.category` has always accepted an array, and until 2026-08-12
+* the delivery path kept only `cat[0]`. Inside a forked runner that was not
+* merely a local filter: `createUdsEventBus` reports its handler-map keys to
+* the parent as this child's forwarding interest, so the categories that never
+* became keys were never forwarded across the process boundary at all. A
+* ten-category subscribe received one category, silently.
+*
+* Duplicates are collapsed so a filter that names the same category twice does
+* not put the entry in one key twice.
+*/
 export declare function extractCategoryPatterns(filter: EventFilter | string): readonly string[];
 /**
- * Register one handler under every category pattern its filter names, and
- * return the unsubscribe that removes it from all of them.
- *
- * The ONE place a subscriber enters `state.handlers` — both bus
- * implementations (broker and UDS) call it, so "which keys does this
- * subscriber occupy" has a single answer. An emptied key is DELETED rather
- * than left as an empty `Set`: on a child bus the key set is what the parent
- * is told to forward, and an empty set left behind pins the parent to forward
- * a category nobody wants.
- *
- * @param onKeysChanged - Called after the key set may have changed (both on
- *   registration and on unsubscribe), for buses that mirror their key set
- *   somewhere — the UDS child's parent report, the broker's local-interest
- *   surface. Receives the patterns this call touched.
- */
+* Register one handler under every category pattern its filter names, and
+* return the unsubscribe that removes it from all of them.
+*
+* The ONE place a subscriber enters `state.handlers` — both bus
+* implementations (broker and UDS) call it, so "which keys does this
+* subscriber occupy" has a single answer. An emptied key is DELETED rather
+* than left as an empty `Set`: on a child bus the key set is what the parent
+* is told to forward, and an empty set left behind pins the parent to forward
+* a category nobody wants.
+*
+* @param onKeysChanged - Called after the key set may have changed (both on
+*   registration and on unsubscribe), for buses that mirror their key set
+*   somewhere — the UDS child's parent report, the broker's local-interest
+*   surface. Receives the patterns this call touched.
+*/
 export declare function registerSubscriber(state: SharedBusState, filter: EventFilter | string, handler: (event: SystemEvent) => void, onKeysChanged?: (patterns: readonly string[], added: boolean) => void): () => void;
 /**
- * Match an event against the full `EventFilter`. The Map-keyed subscribe path
- * only handles the category pattern (deciding which handler set to fan out to);
- * this function applies the remaining scope dimensions (`agentId`, `addonId`,
- * `deviceId`, `source`, `since`) so per-device / per-addon subscribers don't
- * receive sibling events.
- */
+* Match an event against the full `EventFilter`. The Map-keyed subscribe path
+* only handles the category pattern (deciding which handler set to fan out to);
+* this function applies the remaining scope dimensions (`agentId`, `addonId`,
+* `deviceId`, `source`, `since`) so per-device / per-addon subscribers don't
+* receive sibling events.
+*/
 export declare function matchesEventFilter(event: SystemEvent, filter: EventFilter | string | undefined): boolean;
 /**
- * Categories filtered out of the `recent[]` ring buffer.
- *
- * High-frequency, low-value-for-the-operator categories — periodic metrics
- * snapshots, per-frame inference traces, raw motion-mask dumps, model-download
- * progress, etc. They still fan out to live subscribers (UI charts that
- * explicitly listen for them), but do NOT enter the recent-events ring so
- * meaningful events (motion / phase transitions / device lifecycle / addon
- * lifecycle / recording / detection.event) survive in the last-N window without
- * being displaced by per-frame noise.
- */
+* Categories filtered out of the `recent[]` ring buffer.
+*
+* High-frequency, low-value-for-the-operator categories — periodic metrics
+* snapshots, per-frame inference traces, raw motion-mask dumps, model-download
+* progress, etc. They still fan out to live subscribers (UI charts that
+* explicitly listen for them), but do NOT enter the recent-events ring so
+* meaningful events (motion / phase transitions / device lifecycle / addon
+* lifecycle / recording / detection.event) survive in the last-N window without
+* being displaced by per-frame noise.
+*/
 export declare const RING_BUFFER_DENY_PATTERNS: readonly string[];
 /**
- * Hard cap on the `recent[]` buffer size. Even audit-grade categories that
- * are NOT on the deny-list (e.g. `device.state-changed`) must not accumulate
- * without bound — this is the last-N window, not a durable log. Without this
- * cap the buffer grew forever (~26 MB/h/process across every broker, agent,
- * and UDS-child bus), filling the hub to 16 GB.
- */
-export declare const MAX_RECENT_EVENTS = 1000;
+* Hard cap on the `recent[]` buffer size. Even audit-grade categories that
+* are NOT on the deny-list (e.g. `device.state-changed`) must not accumulate
+* without bound — this is the last-N window, not a durable log. Without this
+* cap the buffer grew forever (~26 MB/h/process across every broker, agent,
+* and UDS-child bus), filling the hub to 16 GB.
+*/
+export declare const MAX_RECENT_EVENTS = 1e3;
 export declare function isHighFrequencyCategory(category: string): boolean;
 /**
- * Cross-node (Moleculer) inbound gate: an inbound cross-node event whose
- * category no local subscriber on THIS node wants (the union of its children's
- * declared patterns) is dropped and counted (`suppressed`). It always filters —
- * the `CAMSTACK_MOLECULER_EVENT_FANOUT` shadow/broadcast modes were removed on
- * 2026-10-06; the intra-host analogue is `LocalChildRegistry.childWantsEvent`.
- */
+* Cross-node (Moleculer) inbound gate: an inbound cross-node event whose
+* category no local subscriber on THIS node wants (the union of its children's
+* declared patterns) is dropped and counted (`suppressed`). It always filters —
+* the `CAMSTACK_MOLECULER_EVENT_FANOUT` shadow/broadcast modes were removed on
+* 2026-10-06; the intra-host analogue is `LocalChildRegistry.childWantsEvent`.
+*/
 /**
- * A node's inbound-interest snapshot used by {@link crossNodeAcceptsCategory}.
- *  - `retainRecent` — the receiving bus retains events for `getRecent`/audit
- *    (the hub main process). Such a bus genuinely wants EVERY category (its
- *    interest set is the admin-ui live stream + recent[] ring), so it always
- *    fails OPEN — it never filters inbound cross-node events.
- *  - `interest` — the union of this node's local subscribers' declared category
- *    patterns (aggregated from its UDS children). `null` = undeclared / unknown
- *    (a legacy child, or no oracle installed) → fail OPEN (accept everything).
- *    An EMPTY array is a *declared* "wants nothing" and drops every category.
- */
+* A node's inbound-interest snapshot used by {@link crossNodeAcceptsCategory}.
+*  - `retainRecent` — the receiving bus retains events for `getRecent`/audit
+*    (the hub main process). Such a bus genuinely wants EVERY category (its
+*    interest set is the admin-ui live stream + recent[] ring), so it always
+*    fails OPEN — it never filters inbound cross-node events.
+*  - `interest` — the union of this node's local subscribers' declared category
+*    patterns (aggregated from its UDS children). `null` = undeclared / unknown
+*    (a legacy child, or no oracle installed) → fail OPEN (accept everything).
+*    An EMPTY array is a *declared* "wants nothing" and drops every category.
+*/
 export interface CrossNodeInterestSnapshot {
-    readonly retainRecent: boolean;
-    readonly interest: readonly string[] | null;
+	readonly retainRecent: boolean;
+	readonly interest: readonly string[] | null;
 }
 /**
- * Does this node want to accept an inbound cross-node event in `category`?
- * The receiving-side mirror of `LocalChildRegistry.childWantsEvent`:
- *   - a retaining bus (hub main) → always (it serves `getRecent` + admin-ui;
- *     its interest is genuinely everything).
- *   - undeclared interest (`null`) → always (fail-open).
- *   - else the declared union must match via `matchesPattern` — the SAME
- *     function the local subscriber map-key gate uses, giving delivery parity.
- */
+* Does this node want to accept an inbound cross-node event in `category`?
+* The receiving-side mirror of `LocalChildRegistry.childWantsEvent`:
+*   - a retaining bus (hub main) → always (it serves `getRecent` + admin-ui;
+*     its interest is genuinely everything).
+*   - undeclared interest (`null`) → always (fail-open).
+*   - else the declared union must match via `matchesPattern` — the SAME
+*     function the local subscriber map-key gate uses, giving delivery parity.
+*/
 export declare function crossNodeAcceptsCategory(snapshot: CrossNodeInterestSnapshot, category: string): boolean;
 /**
- * Deliver `event` to all matching local subscribers and — ONLY on a bus that
- * opted into retention (`state.retainRecent`, i.e. the hub main process) and
- * unless the event is high-frequency — append it to the bounded `recent[]`
- * ring.
- *
- * On a non-retaining bus (child runners, agents) the retention block is skipped
- * entirely: events are one-shot / fire-and-forget, still fanned out to local
- * subscribers but never accumulated. `getRecent` on such a bus returns `[]`.
- */
+* Deliver `event` to all matching local subscribers and — ONLY on a bus that
+* opted into retention (`state.retainRecent`, i.e. the hub main process) and
+* unless the event is high-frequency — append it to the bounded `recent[]`
+* ring.
+*
+* On a non-retaining bus (child runners, agents) the retention block is skipped
+* entirely: events are one-shot / fire-and-forget, still fanned out to local
+* subscribers but never accumulated. `getRecent` on such a bus returns `[]`.
+*/
 export declare function deliverShared(state: SharedBusState, event: SystemEvent): void;