@camstack/system 1.2.390 → 1.2.391

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

@@ -1,191 +1,191 @@
-import { ChildCustomActionCatalogs, IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
-import { AddonCallInput, CapCallInput, ChildCapDescriptor, ChildLogMessage } from './child-cap-protocol.js';
+import type { ChildCustomActionCatalogs, IReadinessRegistryRecord, SystemEvent } from "@camstack/types";
+import type { AddonCallInput, CapCallInput, ChildCapDescriptor, ChildLogMessage } from "./child-cap-protocol.js";
 export interface LocalChildClientOptions {
-    /** Parent node id — selects the UDS endpoint this child connects to. */
-    readonly nodeId: string;
-    /** This child's stable id (its addon-runner id). */
-    readonly childId: string;
-    /** Cap manifest sent to the parent on registration. */
-    readonly caps: readonly ChildCapDescriptor[];
-    /** Invoked for each parent→child cap call; returns the cap method's result. */
-    readonly dispatch: (call: CapCallInput) => Promise<unknown>;
+	/** Parent node id — selects the UDS endpoint this child connects to. */
+	readonly nodeId: string;
+	/** This child's stable id (its addon-runner id). */
+	readonly childId: string;
+	/** Cap manifest sent to the parent on registration. */
+	readonly caps: readonly ChildCapDescriptor[];
+	/** Invoked for each parent→child cap call; returns the cap method's result. */
+	readonly dispatch: (call: CapCallInput) => Promise<unknown>;
 }
 /** Handler invoked for each parent→child addon-level call (`routes` / `custom`). */
 export type AddonCallHandler = (call: AddonCallInput) => Promise<unknown>;
 /**
- * Child side of the local UDS transport. Connects to its parent (hub or
- * agent), registers its cap manifest, and serves parent→child cap calls by
- * delegating to `dispatch`. The provider implementation lives in the child;
- * only routing keys + call arguments cross the wire.
- *
- * Additional channels beyond cap-call:
- *   - `emitEvent`              fire-and-forget event toward the parent
- *   - `sendLog`                fire-and-forget log entry toward the parent
- *   - `requestReadinessSnapshot` request/response snapshot of readiness records
- *   - `onEvent`                register a handler for parent→child events
- *
- * Events and logs emitted before `start()` resolves are buffered and flushed
- * on connect (mirrors the `updateCaps`/`latestCaps` pattern).
- */
+* Child side of the local UDS transport. Connects to its parent (hub or
+* agent), registers its cap manifest, and serves parent→child cap calls by
+* delegating to `dispatch`. The provider implementation lives in the child;
+* only routing keys + call arguments cross the wire.
+*
+* Additional channels beyond cap-call:
+*   - `emitEvent`              fire-and-forget event toward the parent
+*   - `sendLog`                fire-and-forget log entry toward the parent
+*   - `requestReadinessSnapshot` request/response snapshot of readiness records
+*   - `onEvent`                register a handler for parent→child events
+*
+* Events and logs emitted before `start()` resolves are buffered and flushed
+* on connect (mirrors the `updateCaps`/`latestCaps` pattern).
+*/
 export declare class LocalChildClient {
-    private readonly options;
-    private client;
-    private channel;
-    /**
-     * The cap set `start()` will register, kept current by `updateCaps`. Native
-     * device caps register on device-restore, which can race AHEAD of the UDS
-     * connect — buffering here lets a pre-start `updateCaps` survive (start sends
-     * the latest set) instead of being lost or throwing.
-     */
-    private latestCaps;
-    /**
-     * Per-owner (addonId) category-pattern subscription sets, and their union.
-     * The union is declared to the parent (in `RegisterMessage.eventPatterns`
-     * pre/at-connect, or via an `event-sub` emit post-connect) so the parent can
-     * subscription-filter its event fan-out. Per-owner keying keeps the union
-     * correct if multiple event buses ever share one client (group-runner case).
-     */
-    private readonly patternsByOwner;
-    private latestEventPatterns;
-    /**
-     * Whether `updateEventPatterns` has ever been called. A client that never
-     * declared a subscription set (no event bus wired — e.g. a pure cap-call
-     * runner) omits `eventPatterns` from its register frame entirely, so the
-     * parent treats it as UNDECLARED and fails OPEN (broadcast-all). Once any
-     * owner declares (in production every addon context's framework
-     * subscriptions do), the register carries the real union — even if empty.
-     */
-    private hasDeclaredEventPatterns;
-    /**
-     * The custom-action catalogs of every hosted addon, once the runner's init
-     * loop has produced them (`updateCaps(caps, catalogs)` at post-init). `null`
-     * until then, and OMITTED from the register frame while null: the parent
-     * reads absence as "not described yet", and a pre-init register must never
-     * look like "this child declares no actions". Kept on the client so every
-     * later re-register (native-cap change, reconnect) re-carries it unchanged.
-     */
-    private latestCustomActions;
-    /** Events and logs queued while the channel is not yet open. */
-    private readonly pendingEmits;
-    /**
-     * Whether the parent acknowledged raw-forward at `register`. Until it has,
-     * `callOut` sends args inline exactly as every child always did — a legacy
-     * parent would decode a payload-borne call to `args: undefined` and run the
-     * provider on nothing, silently. Re-read on every re-register.
-     */
-    private parentRawForward;
-    /** Handler for parent→child events. Registered via `onEvent`. */
-    private eventHandler;
-    /**
-     * Handler for parent→child addon-level calls (`routes` / `custom`).
-     * Registered via `onAddonCall`. Resolves the loaded addon instance and
-     * invokes its `addon-routes.getRoutes()` or its custom-action handler.
-     * Replaces the per-addon Moleculer `getRoutes` / `custom.<action>` actions
-     * removed in F1/F2. Only one handler is active at a time.
-     */
-    private addonCallHandler;
-    /**
-     * Handler for `set-log-level` messages pushed by the parent.
-     * Registered via `onSetLogLevel`. The handler applies the new level to the
-     * child's local Moleculer logger (mirrors `$node-mgmt.setLogLevel`).
-     * E2: wired in `addon-runner.ts` to forward to the broker logger.
-     */
-    private setLogLevelHandler;
-    /** Callbacks registered via `onConnected`. Fired on every (re)connect. */
-    private readonly connectedHandlers;
-    constructor(options: LocalChildClientOptions);
-    /**
-     * Declare an owner's live category-pattern subscription set. Stores it
-     * per-owner (keyed by `ownerId` = addonId), recomputes the union, and — only
-     * if the union changed — declares it to the parent:
-     *   - pre-connect: buffered only; `start()`'s register frame carries the set.
-     *   - post-connect: emitted as a fire-and-forget `event-sub` (full-set
-     *     replace).
-     * Idempotent on an unchanged union (no redundant `event-sub` frames).
-     */
-    updateEventPatterns(ownerId: string, patterns: readonly string[]): void;
-    /** Sorted, de-duplicated union across all owners' pattern sets. */
-    private computePatternUnion;
-    /** Order-insensitive equality — both inputs are already sorted unions here. */
-    private patternsEqual;
-    /**
-     * Register a callback that fires each time the client successfully connects
-     * (or reconnects) to its parent. Multiple handlers may be registered; all
-     * are called in registration order. Used by readiness-context in UDS mode
-     * to trigger a snapshot hydrate on connect/reconnect.
-     */
-    onConnected(handler: () => void): void;
-    /**
-     * Register a handler for events pushed from the parent to this child.
-     * Must be called before `start()` to avoid missing early events (though
-     * registration after start is also safe for events not yet delivered).
-     * Replaces any previously registered handler.
-     */
-    onEvent(handler: (event: SystemEvent) => void): void;
-    /**
-     * Register the handler invoked when the parent sends an `addon-call` (the
-     * addon-level routes / custom-action plane). The addon-runner wires this to
-     * resolve the loaded addon by id and dispatch to its `getRoutes()` or its
-     * custom-action handler. Safe to register before or after `start()`;
-     * replaces any prior handler.
-     */
-    onAddonCall(handler: AddonCallHandler): void;
-    /**
-     * E2: Register a handler invoked when the parent sends a `set-log-level`
-     * message to this child. The handler should forward the new level to the
-     * child's local Moleculer broker logger (mirrors `$node-mgmt.setLogLevel`).
-     * Safe to register before or after `start()`. Replaces any prior handler.
-     */
-    onSetLogLevel(handler: (level: string) => void): void;
-    /**
-     * True once `start()` has successfully connected and registered. Used by
-     * callers (event-bus/logger bridges) to know the channel is live.
-     */
-    get isConnected(): boolean;
-    start(): Promise<void>;
-    /** Flush buffered pre-start emits over the now-open channel. */
-    private flushPending;
-    /**
-     * Re-send the cap manifest to the parent, atomically replacing the child's
-     * registered descriptor set. Call this after device-restore so newly
-     * registered native (device-scoped) caps become routable over UDS.
-     *
-     * Safe to call before `start()`: the new set is buffered and `start()` sends
-     * it (device-restore can race ahead of the UDS connect). After `start()`,
-     * the set is sent immediately.
-     */
-    updateCaps(caps: readonly ChildCapDescriptor[], customActions?: ChildCustomActionCatalogs): Promise<void>;
-    /**
-     * The register frame: caps, plus everything a re-register must atomically
-     * re-carry so no separate re-sync can be missed — the subscription union
-     * (omitted if nothing ever declared, which keeps the fail-open shape) and the
-     * custom-action catalogs (omitted until the init loop produced them).
-     */
-    private registerFrame;
-    /**
-     * Fire-and-forget: send a system event to the parent for forwarding to the
-     * hub event bus. Safe to call before `start()` — events are buffered and
-     * flushed on connect.
-     */
-    emitEvent(event: SystemEvent): void;
-    /**
-     * Fire-and-forget: send a structured log entry to the parent. Safe to call
-     * before `start()` — log entries are buffered and flushed on connect.
-     */
-    sendLog(entry: Omit<ChildLogMessage, 'kind'>): void;
-    /**
-     * Request the current readiness snapshot from the parent. Returns the
-     * authoritative set of `IReadinessRegistryRecord` entries the hub holds.
-     * Requires `start()` to have been called; throws with a clear message if not.
-     */
-    requestReadinessSnapshot(): Promise<readonly IReadinessRegistryRecord[]>;
-    /**
-     * Ask the parent to execute a cap call this child does NOT own. The parent
-     * routes to the owning local sibling over UDS, or — if no sibling owns it —
-     * to its `onUnownedCall` fallback (the cluster CapabilityRegistry in
-     * production). Throws if called before `start()`.
-     */
-    callOut(input: CapCallInput): Promise<unknown>;
-    /** Disconnect from the parent. Safe to call before `start()` (no-op) and idempotent. */
-    close(): Promise<void>;
+	private readonly options;
+	private client;
+	private channel;
+	/**
+	* The cap set `start()` will register, kept current by `updateCaps`. Native
+	* device caps register on device-restore, which can race AHEAD of the UDS
+	* connect — buffering here lets a pre-start `updateCaps` survive (start sends
+	* the latest set) instead of being lost or throwing.
+	*/
+	private latestCaps;
+	/**
+	* Per-owner (addonId) category-pattern subscription sets, and their union.
+	* The union is declared to the parent (in `RegisterMessage.eventPatterns`
+	* pre/at-connect, or via an `event-sub` emit post-connect) so the parent can
+	* subscription-filter its event fan-out. Per-owner keying keeps the union
+	* correct if multiple event buses ever share one client (group-runner case).
+	*/
+	private readonly patternsByOwner;
+	private latestEventPatterns;
+	/**
+	* Whether `updateEventPatterns` has ever been called. A client that never
+	* declared a subscription set (no event bus wired — e.g. a pure cap-call
+	* runner) omits `eventPatterns` from its register frame entirely, so the
+	* parent treats it as UNDECLARED and fails OPEN (broadcast-all). Once any
+	* owner declares (in production every addon context's framework
+	* subscriptions do), the register carries the real union — even if empty.
+	*/
+	private hasDeclaredEventPatterns;
+	/**
+	* The custom-action catalogs of every hosted addon, once the runner's init
+	* loop has produced them (`updateCaps(caps, catalogs)` at post-init). `null`
+	* until then, and OMITTED from the register frame while null: the parent
+	* reads absence as "not described yet", and a pre-init register must never
+	* look like "this child declares no actions". Kept on the client so every
+	* later re-register (native-cap change, reconnect) re-carries it unchanged.
+	*/
+	private latestCustomActions;
+	/** Events and logs queued while the channel is not yet open. */
+	private readonly pendingEmits;
+	/**
+	* Whether the parent acknowledged raw-forward at `register`. Until it has,
+	* `callOut` sends args inline exactly as every child always did — a legacy
+	* parent would decode a payload-borne call to `args: undefined` and run the
+	* provider on nothing, silently. Re-read on every re-register.
+	*/
+	private parentRawForward;
+	/** Handler for parent→child events. Registered via `onEvent`. */
+	private eventHandler;
+	/**
+	* Handler for parent→child addon-level calls (`routes` / `custom`).
+	* Registered via `onAddonCall`. Resolves the loaded addon instance and
+	* invokes its `addon-routes.getRoutes()` or its custom-action handler.
+	* Replaces the per-addon Moleculer `getRoutes` / `custom.<action>` actions
+	* removed in F1/F2. Only one handler is active at a time.
+	*/
+	private addonCallHandler;
+	/**
+	* Handler for `set-log-level` messages pushed by the parent.
+	* Registered via `onSetLogLevel`. The handler applies the new level to the
+	* child's local Moleculer logger (mirrors `$node-mgmt.setLogLevel`).
+	* E2: wired in `addon-runner.ts` to forward to the broker logger.
+	*/
+	private setLogLevelHandler;
+	/** Callbacks registered via `onConnected`. Fired on every (re)connect. */
+	private readonly connectedHandlers;
+	constructor(options: LocalChildClientOptions);
+	/**
+	* Declare an owner's live category-pattern subscription set. Stores it
+	* per-owner (keyed by `ownerId` = addonId), recomputes the union, and — only
+	* if the union changed — declares it to the parent:
+	*   - pre-connect: buffered only; `start()`'s register frame carries the set.
+	*   - post-connect: emitted as a fire-and-forget `event-sub` (full-set
+	*     replace).
+	* Idempotent on an unchanged union (no redundant `event-sub` frames).
+	*/
+	updateEventPatterns(ownerId: string, patterns: readonly string[]): void;
+	/** Sorted, de-duplicated union across all owners' pattern sets. */
+	private computePatternUnion;
+	/** Order-insensitive equality — both inputs are already sorted unions here. */
+	private patternsEqual;
+	/**
+	* Register a callback that fires each time the client successfully connects
+	* (or reconnects) to its parent. Multiple handlers may be registered; all
+	* are called in registration order. Used by readiness-context in UDS mode
+	* to trigger a snapshot hydrate on connect/reconnect.
+	*/
+	onConnected(handler: () => void): void;
+	/**
+	* Register a handler for events pushed from the parent to this child.
+	* Must be called before `start()` to avoid missing early events (though
+	* registration after start is also safe for events not yet delivered).
+	* Replaces any previously registered handler.
+	*/
+	onEvent(handler: (event: SystemEvent) => void): void;
+	/**
+	* Register the handler invoked when the parent sends an `addon-call` (the
+	* addon-level routes / custom-action plane). The addon-runner wires this to
+	* resolve the loaded addon by id and dispatch to its `getRoutes()` or its
+	* custom-action handler. Safe to register before or after `start()`;
+	* replaces any prior handler.
+	*/
+	onAddonCall(handler: AddonCallHandler): void;
+	/**
+	* E2: Register a handler invoked when the parent sends a `set-log-level`
+	* message to this child. The handler should forward the new level to the
+	* child's local Moleculer broker logger (mirrors `$node-mgmt.setLogLevel`).
+	* Safe to register before or after `start()`. Replaces any prior handler.
+	*/
+	onSetLogLevel(handler: (level: string) => void): void;
+	/**
+	* True once `start()` has successfully connected and registered. Used by
+	* callers (event-bus/logger bridges) to know the channel is live.
+	*/
+	get isConnected(): boolean;
+	start(): Promise<void>;
+	/** Flush buffered pre-start emits over the now-open channel. */
+	private flushPending;
+	/**
+	* Re-send the cap manifest to the parent, atomically replacing the child's
+	* registered descriptor set. Call this after device-restore so newly
+	* registered native (device-scoped) caps become routable over UDS.
+	*
+	* Safe to call before `start()`: the new set is buffered and `start()` sends
+	* it (device-restore can race ahead of the UDS connect). After `start()`,
+	* the set is sent immediately.
+	*/
+	updateCaps(caps: readonly ChildCapDescriptor[], customActions?: ChildCustomActionCatalogs): Promise<void>;
+	/**
+	* The register frame: caps, plus everything a re-register must atomically
+	* re-carry so no separate re-sync can be missed — the subscription union
+	* (omitted if nothing ever declared, which keeps the fail-open shape) and the
+	* custom-action catalogs (omitted until the init loop produced them).
+	*/
+	private registerFrame;
+	/**
+	* Fire-and-forget: send a system event to the parent for forwarding to the
+	* hub event bus. Safe to call before `start()` — events are buffered and
+	* flushed on connect.
+	*/
+	emitEvent(event: SystemEvent): void;
+	/**
+	* Fire-and-forget: send a structured log entry to the parent. Safe to call
+	* before `start()` — log entries are buffered and flushed on connect.
+	*/
+	sendLog(entry: Omit<ChildLogMessage, "kind">): void;
+	/**
+	* Request the current readiness snapshot from the parent. Returns the
+	* authoritative set of `IReadinessRegistryRecord` entries the hub holds.
+	* Requires `start()` to have been called; throws with a clear message if not.
+	*/
+	requestReadinessSnapshot(): Promise<readonly IReadinessRegistryRecord[]>;
+	/**
+	* Ask the parent to execute a cap call this child does NOT own. The parent
+	* routes to the owning local sibling over UDS, or — if no sibling owns it —
+	* to its `onUnownedCall` fallback (the cluster CapabilityRegistry in
+	* production). Throws if called before `start()`.
+	*/
+	callOut(input: CapCallInput): Promise<unknown>;
+	/** Disconnect from the parent. Safe to call before `start()` (no-op) and idempotent. */
+	close(): Promise<void>;
 }