@camstack/system 1.2.390 → 1.2.391

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

@@ -1,31 +1,80 @@
-import { IEventBus, SystemEvent } from '@camstack/types';
 /**
- * Minimal interface this bus requires from the child-side UDS transport.
- * `LocalChildClient` satisfies it structurally; tests can provide a fake.
- *
- * - `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.
- *   Because the slot is single, this module registers it exactly ONCE per
- *   channel — the shared-state factory below — never once per addon bus.)
- * - `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.
- */
+* UDS-backed IEventBus for a forked child process (C1).
+*
+* Behaviour:
+*  - `emit(event)` — enriches with `sourceAddonId`, calls `deliverShared` for
+*    same-process local delivery, then forwards to the parent via
+*    `client.emitEvent`.
+*  - Inbound parent→child events (registered via `client.onEvent`) are fed
+*    into `deliverShared` so local subscribers receive them. They are NOT
+*    re-sent to the parent (no echo — the parent's C2 logic is responsible
+*    for not bouncing a child's own events back).
+*  - `subscribe` / `getRecent` delegate to the local `SharedBusState` using
+*    the same helpers as the Moleculer broker bus so filter semantics and
+*    the high-frequency deny-list behave identically.
+*
+* ## ONE shared state per channel — the group-runner contract
+*
+* `SharedBusState` is shared across every bus created on the SAME
+* `UdsEventChannel`, and `client.onEvent` is registered exactly ONCE per
+* channel (mirrors `getBrokerEventBus`'s "single in-process delivery map per
+* broker" — the property `createBrokerEventBus` already had). This matters for
+* GROUPED runners (`execution.group`), where several addons share one process
+* and therefore one `LocalChildClient`:
+*
+*   `LocalChildClient.onEvent` is SINGLE-SLOT (a new handler replaces the
+*   prior one). When each co-located addon's context built its own private
+*   state and registered its own `onEvent`, only the LAST-created addon's bus
+*   ever received parent→child events — every earlier addon's subscriptions
+*   were silently dead. In the `detection` group (pipeline-runner,
+*   detection-pipeline, motion-wasm — load order) this killed pipeline-runner's
+*   `MotionOnMotionChanged` subscriber: the dynamic onboard→analyzer gate never
+*   fired, the shared motion sink never registered, and no camera produced
+*   motion boxes, while the child's DECLARED pattern union (per-owner
+*   `updateEventPatterns`) still advertised the category, so the parent
+*   faithfully fanned events into a state with no subscriber.
+*
+* The per-addon return value is a thin facade over the shared state: `emit`
+* stamps the calling addon's `sourceAddonId`; `subscribe` reports the shared
+* key set under the calling addon's ownerId (a superset per owner — safe:
+* over-forwarding is filtered by the child-side delivery gate, and the
+* parent-forward ≡ child-deliver parity is exact because both read the same
+* shared key set). Sharing the state also restores broker-bus parity for
+* in-process sibling emits: an event emitted by one co-located addon reaches
+* another's subscriber synchronously, without a parent round-trip.
+*
+* The `UdsEventChannel` interface is the minimal surface this module needs
+* from `LocalChildClient` — typed structurally so tests can provide a fake
+* without any casts.
+*/
+import type { IEventBus, SystemEvent } from "@camstack/types";
+/**
+* Minimal interface this bus requires from the child-side UDS transport.
+* `LocalChildClient` satisfies it structurally; tests can provide a fake.
+*
+* - `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.
+*   Because the slot is single, this module registers it exactly ONCE per
+*   channel — the shared-state factory below — never once per addon bus.)
+* - `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;
+	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.
- * Returns a per-addon facade over the channel's ONE shared state (module doc).
- *
- * @param client  - The UDS channel toward the parent (hub or agent).
- * @param addonId - This child's stable addon id — stamped as `sourceAddonId`
- *                  on every outbound event so cluster consumers can attribute
- *                  events to their source addon.
- */
+* Create a UDS-backed `IEventBus` for use inside a forked child process.
+* Returns a per-addon facade over the channel's ONE shared state (module doc).
+*
+* @param client  - The UDS channel toward the parent (hub or agent).
+* @param addonId - This child's stable addon id — stamped as `sourceAddonId`
+*                  on every outbound event so cluster consumers can attribute
+*                  events to their source addon.
+*/
 export declare function createUdsEventBus(client: UdsEventChannel, addonId: string): IEventBus;

package/dist/kernel/transport/uds-local-transport.d.ts

@@ -1,18 +1,18 @@
-import { LocalChannel, LocalTransportServer, LocalTransportClient } from './local-transport.js';
+import type { LocalChannel, LocalTransportServer, LocalTransportClient } from "./local-transport.js";
 export declare class UdsLocalTransportServer implements LocalTransportServer {
-    private readonly path;
-    private server;
-    private connHandler;
-    private readonly channels;
-    constructor(path: string);
-    onConnection(handler: (channel: LocalChannel) => void): void;
-    listen(): Promise<void>;
-    close(): Promise<void>;
+	private readonly path;
+	private server;
+	private connHandler;
+	private readonly channels;
+	constructor(path: string);
+	onConnection(handler: (channel: LocalChannel) => void): void;
+	listen(): Promise<void>;
+	close(): Promise<void>;
 }
 export declare class UdsLocalTransportClient implements LocalTransportClient {
-    private readonly path;
-    private channel;
-    constructor(path: string);
-    connect(): Promise<LocalChannel>;
-    close(): Promise<void>;
+	private readonly path;
+	private channel;
+	constructor(path: string);
+	connect(): Promise<LocalChannel>;
+	close(): Promise<void>;
 }

package/dist/kernel/transport/uds-log-ingest.d.ts

@@ -1,28 +1,43 @@
-import { LogTags } from '@camstack/types';
-import { ChildLogMessage } from './child-cap-protocol.js';
 /**
- * The entry shape accepted by `LoggingService.writeFromWorker` (hub) and by
- * the agent's `log-receiver.ingest` Moleculer forwarding call.
- *
- * Typed here so the helper has no dependency on hub-only server classes.
- */
+* UDS child log ingest helpers — Task B2.
+*
+* Pure mapping function shared by the hub (`MoleculerService`) and the agent
+* (`agent-bootstrap`) to convert a `ChildLogMessage` received over a UDS
+* channel into the `writeFromWorker` / `log-receiver.ingest` entry shape.
+*
+* Kept in `@camstack/kernel` so both the hub (server/backend) and the agent
+* (`packages/agent`) can import it without cross-package coupling.
+*
+* The shape produced mirrors the existing `$hub.log` / `onLog` mapping in
+* `moleculer.service.ts` exactly — optional keys (`scope`, `tags`, `meta`)
+* are omitted rather than set to `undefined` so callers never receive stray
+* keys in spread operations.
+*/
+import type { LogTags } from "@camstack/types";
+import type { ChildLogMessage } from "./child-cap-protocol.js";
+/**
+* The entry shape accepted by `LoggingService.writeFromWorker` (hub) and by
+* the agent's `log-receiver.ingest` Moleculer forwarding call.
+*
+* Typed here so the helper has no dependency on hub-only server classes.
+*/
 export interface WorkerLogEntry {
-    readonly addonId: string;
-    readonly nodeId?: string;
-    readonly level: string;
-    readonly message: string;
-    readonly scope?: string;
-    readonly tags?: LogTags;
-    readonly meta?: Record<string, unknown>;
+	readonly addonId: string;
+	readonly nodeId?: string;
+	readonly level: string;
+	readonly message: string;
+	readonly scope?: string;
+	readonly tags?: LogTags;
+	readonly meta?: Record<string, unknown>;
 }
 /**
- * Convert a `ChildLogMessage` received over a UDS channel into the
- * `WorkerLogEntry` shape.
- *
- * - `childId` is used as the `nodeId` fallback when the child did not include
- *   its own `nodeId` in the log entry (pre-B2 runners or very early boot logs).
- * - The entry's `addonId` is preserved as-is — it identifies the actual addon
- *   that emitted the log, not the runner that forwarded it. Child identity is
- *   fully preserved so the admin-UI log stream shows the originating addon.
- */
+* Convert a `ChildLogMessage` received over a UDS channel into the
+* `WorkerLogEntry` shape.
+*
+* - `childId` is used as the `nodeId` fallback when the child did not include
+*   its own `nodeId` in the log entry (pre-B2 runners or very early boot logs).
+* - The entry's `addonId` is preserved as-is — it identifies the actual addon
+*   that emitted the log, not the runner that forwarded it. Child identity is
+*   fully preserved so the admin-UI log stream shows the originating addon.
+*/
 export declare function udsChildLogToWorkerEntry(childId: string, entry: ChildLogMessage): WorkerLogEntry;

package/dist/kernel/transport/uds-logger.d.ts

@@ -1,44 +1,44 @@
-import { IScopedLogger, LogTags } from '@camstack/types';
-import { ChildLogMessage } from './child-cap-protocol.js';
+import type { IScopedLogger, LogTags } from "@camstack/types";
+import type { ChildLogMessage } from "./child-cap-protocol.js";
 /**
- * Minimal interface this module requires from the transport client.
- *
- * `LocalChildClient` satisfies this structurally. Using a minimal named
- * interface keeps `uds-logger.ts` decoupled from the full `LocalChildClient`
- * class and allows tests to pass a plain fake object without casts.
- *
- * `isConnected` is intentionally omitted — the logger never reads it; all
- * pre-connect buffering is handled by the client implementation.
- */
+* Minimal interface this module requires from the transport client.
+*
+* `LocalChildClient` satisfies this structurally. Using a minimal named
+* interface keeps `uds-logger.ts` decoupled from the full `LocalChildClient`
+* class and allows tests to pass a plain fake object without casts.
+*
+* `isConnected` is intentionally omitted — the logger never reads it; all
+* pre-connect buffering is handled by the client implementation.
+*/
 export interface UdsLogSink {
-    /**
-     * Fire-and-forget: send a structured log entry to the parent.
-     * Safe to call before `start()` — entries are buffered and flushed on connect.
-     */
-    readonly sendLog: (entry: Omit<ChildLogMessage, 'kind'>) => void;
+	/**
+	* Fire-and-forget: send a structured log entry to the parent.
+	* Safe to call before `start()` — entries are buffered and flushed on connect.
+	*/
+	readonly sendLog: (entry: Omit<ChildLogMessage, "kind">) => void;
 }
 /**
- * Mutable log-level control shared across every `IScopedLogger` built by a
- * single `createUdsLogger` family (the root plus its `child`/`withTags`
- * descendants). Replaces the broker logger's per-appender level: the parent's
- * `$node-mgmt.setLogLevel` equivalent over UDS (`onSetLogLevel`) calls
- * `setLevel`, and entries below the threshold are dropped before `sendLog`
- * (the parent's LoggingService also filters at query time — this just trims
- * transport traffic, matching the broker `**: childLogLevel` appender gate).
- */
+* Mutable log-level control shared across every `IScopedLogger` built by a
+* single `createUdsLogger` family (the root plus its `child`/`withTags`
+* descendants). Replaces the broker logger's per-appender level: the parent's
+* `$node-mgmt.setLogLevel` equivalent over UDS (`onSetLogLevel`) calls
+* `setLevel`, and entries below the threshold are dropped before `sendLog`
+* (the parent's LoggingService also filters at query time — this just trims
+* transport traffic, matching the broker `**: childLogLevel` appender gate).
+*/
 export interface UdsLogLevelControl {
-    setLevel(level: string): void;
+	setLevel(level: string): void;
 }
 declare function createUdsLogger(client: UdsLogSink, addonId: string, nodeId: string, scope?: string, tags?: LogTags): IScopedLogger;
 /**
- * Like {@link createUdsLogger} but also returns a {@link UdsLogLevelControl}.
- * The control's `setLevel` retunes the threshold for this logger AND every
- * `child`/`withTags` descendant (they share the level state). Used by the
- * `addon-runner` self-logger so the parent's UDS `set-log-level` message can
- * raise/lower the child's outbound log verbosity.
- */
+* Like {@link createUdsLogger} but also returns a {@link UdsLogLevelControl}.
+* The control's `setLevel` retunes the threshold for this logger AND every
+* `child`/`withTags` descendant (they share the level state). Used by the
+* `addon-runner` self-logger so the parent's UDS `set-log-level` message can
+* raise/lower the child's outbound log verbosity.
+*/
 declare function createUdsLoggerWithControl(client: UdsLogSink, addonId: string, nodeId: string, scope?: string, tags?: LogTags): {
-    logger: IScopedLogger;
-    control: UdsLogLevelControl;
+	logger: IScopedLogger;
+	control: UdsLogLevelControl;
 };
 export { createUdsLogger, createUdsLoggerWithControl };

package/dist/kernel/utils/ring-buffer.d.ts

@@ -1,15 +1,15 @@
 /**
- * Fixed-capacity ring buffer. When full, push() overwrites the oldest entry.
- * drain() returns up to maxCount items in FIFO order and removes them.
- */
+* Fixed-capacity ring buffer. When full, push() overwrites the oldest entry.
+* drain() returns up to maxCount items in FIFO order and removes them.
+*/
 export declare class RingBuffer<T> {
-    private readonly capacity;
-    private readonly items;
-    private head;
-    private tail;
-    private count;
-    constructor(capacity: number);
-    get size(): number;
-    push(item: T): void;
-    drain(maxCount: number): T[];
+	private readonly capacity;
+	private readonly items;
+	private head;
+	private tail;
+	private count;
+	constructor(capacity: number);
+	get size(): number;
+	push(item: T): void;
+	drain(maxCount: number): T[];
 }

package/dist/kernel/workspace-detect.d.ts

@@ -1,9 +1,9 @@
 /**
- * Detect whether we're running inside the monorepo workspace.
- * Returns the absolute path to the packages/ directory if found, otherwise null.
- *
- * Single source of truth — replaces identical implementations in:
- * - first-boot-installer.ts
- * - addon-bridge.service.ts
- */
+* Detect whether we're running inside the monorepo workspace.
+* Returns the absolute path to the packages/ directory if found, otherwise null.
+*
+* Single source of truth — replaces identical implementations in:
+* - first-boot-installer.ts
+* - addon-bridge.service.ts
+*/
 export declare function detectWorkspacePackagesDir(startDir: string): string | null;

package/dist/lifecycle/lifecycle-state-machine.d.ts

@@ -1,28 +1,28 @@
-import { IScopedLogger, IEventBus } from '@camstack/types';
-export type ElementState = 'stopped' | 'starting' | 'running' | 'stopping' | 'error' | 'disabled';
+import type { IScopedLogger, IEventBus } from "@camstack/types";
+export type ElementState = "stopped" | "starting" | "running" | "stopping" | "error" | "disabled";
 export interface ElementStatus {
-    state: ElementState;
-    error?: string;
-    startedAt?: number;
-    stoppedAt?: number;
-    restartCount: number;
-    uptime: number;
+	state: ElementState;
+	error?: string;
+	startedAt?: number;
+	stoppedAt?: number;
+	restartCount: number;
+	uptime: number;
 }
 export declare class LifecycleStateMachine {
-    private readonly elementId;
-    private readonly elementType;
-    private readonly eventBus;
-    private readonly logger;
-    private _state;
-    private _error?;
-    private _startedAt?;
-    private _stoppedAt?;
-    private _restartCount;
-    private _hasStartedOnce;
-    constructor(elementId: string, elementType: 'provider' | 'device' | 'addon' | 'process', eventBus: IEventBus, logger: IScopedLogger);
-    get state(): ElementState;
-    getStatus(): ElementStatus;
-    transition(to: ElementState, error?: string): boolean;
-    incrementRestartCount(): void;
-    private isValidTransition;
+	private readonly elementId;
+	private readonly elementType;
+	private readonly eventBus;
+	private readonly logger;
+	private _state;
+	private _error?;
+	private _startedAt?;
+	private _stoppedAt?;
+	private _restartCount;
+	private _hasStartedOnce;
+	constructor(elementId: string, elementType: "provider" | "device" | "addon" | "process", eventBus: IEventBus, logger: IScopedLogger);
+	get state(): ElementState;
+	getStatus(): ElementStatus;
+	transition(to: ElementState, error?: string): boolean;
+	incrementRestartCount(): void;
+	private isValidTransition;
 }

package/dist/logging/formatter.d.ts

@@ -1,30 +1,57 @@
-import { LogEntry } from '@camstack/types';
+/**
+* Canonical single-line formatter for every `LogEntry` that reaches a
+* console transport — hub-side `WinstonDestination` +
+* `ConsoleDestination`, agent-side `HubForwarderDestination`. One
+* definition so the three paths can't drift.
+*
+* Layout mirrors NestJS `ConsoleLogger` output:
+*
+*   [Nest] 54994  - 04/20/2026, 12:45:53 AM     LOG [InstanceLoader] TrpcModule dependencies initialized +0ms
+*
+* Mapping for camstack — cluster-aware:
+*   - `[Nest]` (brand bracket)   → `[<agent>/<addonId>]` so operators see
+*                                   at a glance which node emitted the line
+*                                   (matches the cluster topology)
+*   - `54994` (pid)              → `process.pid`
+*   - `<timestamp>`              → `M/D/YYYY, H:MM:SS AM`
+*   - `LOG` / `WARN` / `ERROR`   → `entry.level` upper-cased, colour per level
+*   - `[InstanceLoader]` (ctx)   → `[<device>]` — shown only when a device
+*                                   tag is present; omitted otherwise
+*   - `<message>`                → `entry.message`
+*   - trailing `+Nms`            → we don't compute timing yet; omitted
+*
+* Rendered examples:
+*   [hub/winston-logging]        71184  - 04/20/2026, 12:45:53 AM     INFO  Winston logging initialized
+*   [hub/provider-rtsp]          71184  - 04/20/2026, 12:46:01 AM     WARN  [salone] probe failed {err="timeout"}
+*   [dev-agent-0/detection]      12345  - 04/20/2026, 12:47:15 AM     ERROR [cortile] no detector {codec=av1}
+*/
+import type { LogEntry } from "@camstack/types";
 /** Options for `formatLogLine`. */
 export interface FormatLogLineOptions {
-    /**
-     * Emit ANSI colour codes. When omitted, falls back to the shell-env
-     * heuristic (`NO_COLOR`/`FORCE_COLOR`/`isTTY`). Destinations that
-     * always target a console (ConsoleDestination, HubForwarderDestination)
-     * pass `true`; file sinks (Winston JSON) pass `false` so logs on disk
-     * stay plain text regardless of the shell env.
-     *
-     * `NO_COLOR=1` in the environment still wins — consumer opt-in beats
-     * producer opt-in, matching the https://no-color.org/ convention.
-     */
-    readonly colorize?: boolean;
+	/**
+	* Emit ANSI colour codes. When omitted, falls back to the shell-env
+	* heuristic (`NO_COLOR`/`FORCE_COLOR`/`isTTY`). Destinations that
+	* always target a console (ConsoleDestination, HubForwarderDestination)
+	* pass `true`; file sinks (Winston JSON) pass `false` so logs on disk
+	* stay plain text regardless of the shell env.
+	*
+	* `NO_COLOR=1` in the environment still wins — consumer opt-in beats
+	* producer opt-in, matching the https://no-color.org/ convention.
+	*/
+	readonly colorize?: boolean;
 }
 /**
- * Render a `LogEntry` as one complete console line — no trailing newline.
- * Caller appends `\n` (file sinks) or relies on `console.log` (stdout sink).
- *
- * PID column prefers `entry.tags.pid` when set (so forked-worker entries
- * carry the worker's OS pid even when the hub renders them), falling back
- * to the renderer's own `process.pid`.
- *
- * Colours (when enabled) follow the NestJS convention: the level token
- * AND the message body share the level colour (green/yellow/red/gray for
- * info/warn/error/debug). Brand, device context, scope and meta keep
- * their fixed hues so the structural fields stay visually distinct from
- * the message content.
- */
+* Render a `LogEntry` as one complete console line — no trailing newline.
+* Caller appends `\n` (file sinks) or relies on `console.log` (stdout sink).
+*
+* PID column prefers `entry.tags.pid` when set (so forked-worker entries
+* carry the worker's OS pid even when the hub renders them), falling back
+* to the renderer's own `process.pid`.
+*
+* Colours (when enabled) follow the NestJS convention: the level token
+* AND the message body share the level colour (green/yellow/red/gray for
+* info/warn/error/debug). Brand, device context, scope and meta keep
+* their fixed hues so the structural fields stay visually distinct from
+* the message content.
+*/
 export declare function formatLogLine(entry: LogEntry, options?: FormatLogLineOptions): string;