@camstack/system 1.1.18 → 1.1.20

package/dist/kernel/transport/local-child-registry.d.ts

@@ -1,6 +1,22 @@
+import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
+import { AddonCallInput, CapCallInput, ChildLogMessage, RegisteredChild } from './child-cap-protocol.js';
 import { LocalTransportServer } from './local-transport.js';
-import { ChildLogMessage, CapCallInput, AddonCallInput, RegisteredChild } from './child-cap-protocol.js';
-import { SystemEvent, IReadinessRegistryRecord } from '@camstack/types';
+/**
+ * Fan-out mode for parent→child event delivery, from the
+ * `CAMSTACK_UDS_EVENT_FANOUT` env (read once at registry construction):
+ *   - `filter`    (default) — apply the subscription gate; a child receives a
+ *     category only if one of its declared patterns matches.
+ *   - `shadow`    — compute the gate decision + count would-suppresses, but
+ *     STILL send every event (burn-in: prove zero would-be-starved deliveries).
+ *   - `broadcast` — ignore the gate entirely (today's behaviour); the operator's
+ *     one-env rollback without redeploying runners.
+ */
+export type UdsEventFanoutMode = 'filter' | 'shadow' | 'broadcast';
+/** Per-child event fan-out counters (sent = delivered, suppressed = gated/would-gate). */
+export interface ChildEventStats {
+    sent: number;
+    suppressed: number;
+}
 /**
  * Sentinel prefix used in the no-route error thrown when `cap-call-out` has no
  * local sibling and no `onUnownedCall` fallback. `ipcParentLink` detects this
@@ -38,6 +54,16 @@ export interface LocalChildRegistryOptions {
      * preference is set or the cap is not a singleton.
      */
     readonly getActiveSingletonAddonId?: (capName: string) => string | null;
+    /**
+     * Resolve an addonId to its runner/child id — the addon's
+     * `execution.group` when it declares one, else the addon id itself
+     * (`resolveRunnerId`). Needed so the active-singleton preference (which
+     * is expressed as an addonId) can be matched against the registry's
+     * candidate CHILD ids: a grouped addon's child id is the group name, not
+     * its own id. Omitted → identity (addonId === childId), preserving the
+     * solo-runner behaviour for every ungrouped addon.
+     */
+    readonly resolveChildIdForAddon?: (addonId: string) => string;
 }
 /**
  * Parent-side authority for local addon-runners reachable over a
@@ -56,8 +82,15 @@ export declare class LocalChildRegistry {
     private readonly onUnownedCall?;
     private readonly logger?;
     private readonly getActiveSingletonAddonId?;
+    private readonly resolveChildIdForAddon?;
     /** Tracks capNames already logged as UDS-routed; one INFO line per capName per process. */
     private readonly egressRoutedCaps;
+    /** Active event fan-out mode, read once from `CAMSTACK_UDS_EVENT_FANOUT`. */
+    private readonly fanoutMode;
+    /** Per-child event fan-out counters (sent / suppressed). */
+    private readonly childEventStats;
+    /** Last pattern-set string logged per child, to dedup the INFO line. */
+    private readonly loggedPatternSet;
     /**
      * Accepts either a plain positional `server` argument (backward-compatible)
      * or a full `LocalChildRegistryOptions` object.
@@ -71,6 +104,28 @@ export declare class LocalChildRegistry {
      */
     constructor(serverOrOptions: LocalTransportServer | LocalChildRegistryOptions, onUnownedCallArg?: (input: CapCallInput) => Promise<unknown>);
     start(): Promise<void>;
+    /**
+     * Per-child event fan-out counters (`{ sent, suppressed }`) or `null` if the
+     * child has no recorded events yet. Exposed for the starvation-verification
+     * surface (shadow burn-in + operator debug).
+     */
+    getChildEventStats(childId: string): ChildEventStats | null;
+    /**
+     * Does `entry` want to receive an event in `category`? Honours the fan-out
+     * mode: `broadcast` → always; undeclared patterns (`null`) → always
+     * (fail-open); else the child's declared set must match via `matchesPattern`
+     * — the SAME function the child's own `deliverShared` map-key gate uses,
+     * giving provable delivery parity. `shadow` is handled by the caller (it
+     * counts the would-suppress but still sends).
+     *
+     * NOTE: this gate must NOT consult `RING_BUFFER_DENY_PATTERNS` /
+     * `isHighFrequencyCategory` — those are ring-buffer STORAGE policy; a child
+     * that explicitly subscribes to a ring-denied category must still RECEIVE it.
+     */
+    private childWantsEvent;
+    private statsFor;
+    /** Deduped INFO line whenever a child's declared pattern set changes. */
+    private logPatternSet;
     /**
      * Child id that can service a call to `capName` (optionally addressing
      * `deviceId`), or null.

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 {
     /**

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.