@camstack/system 1.1.19 → 1.1.21

package/dist/kernel/transport/uds-event-bridge.d.ts

@@ -2,6 +2,16 @@ import { IEventBus, SystemEvent } from '@camstack/types';
 /**
  * Minimal surface the bridge requires from `LocalChildRegistry`.
  * Structurally typed so tests can provide a fake without any casts.
+ *
+ * CONTRACT: `broadcastEventToChildren` is SUBSCRIPTION-FILTERED. The registry
+ * fans an event only to children whose declared category-pattern set matches
+ * `event.category` (mirror of each child's local `SharedBusState.handlers`
+ * keys). A child that never declared a set (legacy/undeclared) fails OPEN and
+ * receives everything. The `CAMSTACK_UDS_EVENT_FANOUT` env (`filter` default /
+ * `shadow` / `broadcast`) is the registry-side kill-switch. The bridge itself
+ * needs no per-event logic change — both fan-out call sites here go through the
+ * filtered `broadcastEventToChildren`. `sendEventToChild` (targeted push) is
+ * NOT filtered — an explicit single-child send expresses intent.
  */
 export interface ChildEventBroadcaster {
     /**
@@ -22,6 +32,18 @@ export interface UdsEventBridgeDeps {
     readonly parentBus: IEventBus;
     /** This process's Moleculer node ID (e.g. `'hub'` or `'agent-a1b2c3'`). */
     readonly parentNodeId: string;
+    /**
+     * D2: subscribe the bridge's cluster/parent-local → children RELAY handler to
+     * the parent bus WITHOUT registering it in the node's local-interest surface
+     * (`subscribePassthrough` from `@camstack/system`). The bridge is a conduit to
+     * forked children, not a terminal local consumer — counting its wildcard `*`
+     * subscription would make every cross-node category appear "wanted" and defeat
+     * the inbound gate. When omitted (tests / legacy callers) the bridge falls
+     * back to `parentBus.subscribe({}, …)`, which is functionally correct but
+     * counts toward local interest — acceptable only where the D2 gate is not
+     * under test.
+     */
+    readonly subscribePassthrough?: (handler: (event: SystemEvent) => void) => () => void;
 }
 /**
  * Create the parent-side UDS ↔ Moleculer event bridge.

package/dist/kernel/transport/uds-event-bus.d.ts

@@ -6,10 +6,16 @@ import { IEventBus, SystemEvent } from '@camstack/types';
  * - `emitEvent` — fire-and-forget: send a system event to the parent.
  * - `onEvent`   — register the single handler for parent→child events.
  *   (Only one handler is registered; calling again replaces the previous one.)
+ * - `updateEventPatterns` — declare this owner's live category-pattern set to
+ *   the parent so it can subscription-filter the event fan-out. Called after
+ *   every subscribe/unsubscribe with the CURRENT key set (full-set replace).
+ *   Keyed by `ownerId` (the addonId) so multiple buses sharing one client
+ *   union correctly.
  */
 export interface UdsEventChannel {
     emitEvent(event: SystemEvent): void;
     onEvent(handler: (event: SystemEvent) => void): void;
+    updateEventPatterns(ownerId: string, patterns: readonly string[]): void;
 }
 /**
  * Create a UDS-backed `IEventBus` for use inside a forked child process.