@camstack/system 1.0.2

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

@@ -0,0 +1,136 @@
+import { ChildCapDescriptor, CapCallInput, ChildLogMessage, AddonCallInput } from './child-cap-protocol.js';
+import { SystemEvent, IReadinessRegistryRecord } from '@camstack/types';
+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>;
+}
+/** 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).
+ */
+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;
+    /** Events and logs queued while the channel is not yet open. */
+    private readonly pendingEmits;
+    /** 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);
+    /**
+     * 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[]): Promise<void>;
+    /**
+     * 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>;
+}

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

@@ -0,0 +1,179 @@
+import { LocalTransportServer } from './local-transport.js';
+import { ChildLogMessage, CapCallInput, AddonCallInput, RegisteredChild } from './child-cap-protocol.js';
+import { SystemEvent, IReadinessRegistryRecord } from '@camstack/types';
+/**
+ * Sentinel prefix used in the no-route error thrown when `cap-call-out` has no
+ * local sibling and no `onUnownedCall` fallback. `ipcParentLink` detects this
+ * prefix to distinguish routing failures (safe to retry via broker) from real
+ * provider errors (must NOT retry to avoid double-executing side effects).
+ */
+export declare const UDS_NO_ROUTE_PREFIX = "UDS_NO_ROUTE";
+/**
+ * Minimal logger interface accepted by `LocalChildRegistry`.
+ * Kept narrow so the registry doesn't depend on any concrete logger class.
+ */
+export interface LocalChildRegistryLogger {
+    info(msg: string, meta?: unknown): void;
+}
+/**
+ * Options accepted by `LocalChildRegistry`.
+ * The `server` field is the UDS server to listen on.
+ * The optional `onUnownedCall` is the parent-supplied fallback invoked when no
+ * local child owns the requested cap (the hub / agent will wire this to the
+ * cluster CapabilityRegistry).
+ * The optional `logger` receives a single deduplicated INFO line the first time
+ * each capName is routed child→sibling over UDS.
+ */
+export interface LocalChildRegistryOptions {
+    readonly server: LocalTransportServer;
+    readonly onUnownedCall?: (input: CapCallInput) => Promise<unknown>;
+    readonly logger?: LocalChildRegistryLogger;
+    /**
+     * Resolver for the operator's active-singleton preference. When two or
+     * more local children register the SAME singleton capName (e.g. two
+     * addons both providing `webrtc-session`), the registry must consult
+     * `CapabilityRegistry` to pick the operator-selected provider instead of
+     * returning the first-registered child by insertion order. Returns the preferred
+     * addonId (== childId for solo-addon runners), or null when no
+     * preference is set or the cap is not a singleton.
+     */
+    readonly getActiveSingletonAddonId?: (capName: string) => string | null;
+}
+/**
+ * Parent-side authority for local addon-runners reachable over a
+ * `LocalTransportServer` (UDS). Children register their cap manifest on
+ * connect; the registry routes `(capName, deviceId?)` cap calls to the
+ * owning child over the channel and drops a child's caps on disconnect.
+ */
+export declare class LocalChildRegistry {
+    private readonly children;
+    private registeredHandler;
+    private goneHandler;
+    private eventHandler;
+    private logHandler;
+    private readinessHandler;
+    private readonly server;
+    private readonly onUnownedCall?;
+    private readonly logger?;
+    private readonly getActiveSingletonAddonId?;
+    /** Tracks capNames already logged as UDS-routed; one INFO line per capName per process. */
+    private readonly egressRoutedCaps;
+    /**
+     * Accepts either a plain positional `server` argument (backward-compatible)
+     * or a full `LocalChildRegistryOptions` object.
+     *
+     * Positional overloads (existing call sites are unchanged):
+     *   new LocalChildRegistry(server)
+     *   new LocalChildRegistry(server, onUnownedCall)
+     *
+     * Options object (new call sites that pass a logger):
+     *   new LocalChildRegistry({ server, onUnownedCall, logger })
+     */
+    constructor(serverOrOptions: LocalTransportServer | LocalChildRegistryOptions, onUnownedCallArg?: (input: CapCallInput) => Promise<unknown>);
+    start(): Promise<void>;
+    /**
+     * Child id that can service a call to `capName` (optionally addressing
+     * `deviceId`), or null.
+     *
+     * `deviceId` is a routing HINT, not a hard filter. A singleton cap
+     * (`pipeline-runner`, `stream-broker`, …) addresses devices through its
+     * METHOD ARGUMENTS — `attachCamera({ deviceId })` is one provider serving
+     * many cameras — so its descriptor carries no `deviceId`. Resolving on
+     * `deviceId` alone would never match it and would force the call onto the
+     * broker fallback (which then hangs in service discovery). Hence:
+     *   1. exact device-scoped owner (native per-device caps where each child
+     *      owns a disjoint device subset) is preferred, then
+     *   2. a singleton owner (deviceId-less descriptor) is the fallback.
+     * A cap is globally singleton XOR device-scoped, so the two tiers never
+     * compete for the same capName.
+     */
+    resolveChildId(capName: string, deviceId?: number): string | null;
+    /** First child whose cap manifest contains a descriptor matching `predicate`. */
+    private findChildId;
+    /** Every child whose cap manifest contains a descriptor matching `predicate`. */
+    private findAllChildIds;
+    /**
+     * Does the named child currently provide `(capName, deviceId?)`?
+     *
+     * Used by the hub proxy seam, which knows the EXACT addon (→ runner →
+     * childId) a provider belongs to. Unlike `resolveChildId` (which picks the
+     * first child owning `capName`), this targets one child — required for
+     * COLLECTION caps (`addon-widgets-source`, …) where many children register
+     * the same capName: routing by capName alone collapses every provider to
+     * the first child. Same deviceId-as-hint semantics as `resolveChildId`:
+     * a device-scoped descriptor matching `deviceId` OR a deviceId-less
+     * (singleton/collection) descriptor counts.
+     */
+    /**
+     * Is `childId` currently connected (has it completed its UDS handshake)?
+     * Coarser than {@link childProvides}: it answers "is the child reachable
+     * over UDS at all", regardless of which caps it has announced yet. Used by
+     * the route-mount fallback to decide between the handler-stripped
+     * `callAddonOnChild(target:'routes')` path (child reachable) and awaiting a
+     * cap proxy's `getRoutes()` (child not yet UDS-registered).
+     */
+    isChildKnown(childId: string): boolean;
+    childProvides(childId: string, capName: string, deviceId?: number): boolean;
+    /** Forward a cap method call to a SPECIFIC child by id over UDS; rejects if that child is absent. */
+    callCapOnChild(childId: string, input: CapCallInput): Promise<unknown>;
+    /** Forward a cap method call to the owning child over UDS; rejects if none. */
+    callCap(input: CapCallInput): Promise<unknown>;
+    /**
+     * Forward an ADDON-LEVEL call (routes / custom-action) to a SPECIFIC child
+     * by id over UDS; rejects if that child is absent.
+     *
+     * The childId for a hub-local single-addon runner equals the addonId
+     * (`resolveRunnerId` returns the addonId when no `execution.group` is
+     * declared — no shipped addon declares one). Mirrors `callCapOnChild` for
+     * the cap plane; carries the two surfaces the removed per-addon Moleculer
+     * broker used to serve (`getRoutes` + `custom.<action>`).
+     */
+    callAddonOnChild(childId: string, input: AddonCallInput): Promise<unknown>;
+    /** Build the parent→child `addon-call` wire message from an addon-call input. */
+    private toAddonCall;
+    /** Build the parent→child `cap-call` wire message from a routing input. */
+    private toCapCall;
+    listChildren(): readonly RegisteredChild[];
+    /** Register the (single) child-registered handler. Only one handler is active at a time. */
+    onChildRegistered(handler: (child: RegisteredChild) => void): void;
+    /** Register the (single) child-gone handler. Only one handler is active at a time. */
+    onChildGone(handler: (childId: string) => void): void;
+    /**
+     * Register the (single) child-event handler. Invoked when a child sends an
+     * event via `LocalChildClient.emitEvent`. Only one handler is active at a
+     * time; a new handler replaces the prior one. Pass `null` to clear the
+     * handler entirely (used by the UDS event bridge disposer on shutdown).
+     */
+    onChildEvent(handler: ((childId: string, event: SystemEvent) => void) | null): void;
+    /**
+     * Register the (single) child-log handler. Invoked when a child sends a log
+     * entry via `LocalChildClient.sendLog`. Only one handler is active.
+     */
+    onChildLog(handler: (childId: string, entry: ChildLogMessage) => void): void;
+    /**
+     * Register the handler that supplies the authoritative readiness snapshot
+     * when a child sends a `readiness-request`. Only one handler is active.
+     */
+    onReadinessSnapshotRequest(handler: () => readonly IReadinessRegistryRecord[]): void;
+    /**
+     * Push a parent→child event to a specific child. Fire-and-forget (uses the
+     * one-way `emit` path on the channel). No-op if the child is not connected.
+     */
+    sendEventToChild(childId: string, event: SystemEvent, sourceNodeId: string): void;
+    /**
+     * Push a parent→child event to every registered child, optionally skipping
+     * one (the originating child, to avoid echo). Fire-and-forget.
+     */
+    broadcastEventToChildren(event: SystemEvent, sourceNodeId: string, exceptChildId?: string): void;
+    /**
+     * E2: Send a `set-log-level` control message to a specific child.
+     * Returns `true` if the child is currently connected and the message was
+     * emitted; `false` if the child is not connected (no-op). The `false`
+     * return lets the caller (MoleculerService.setChildLogLevelByNodeId) fall
+     * back to the Moleculer `$node-mgmt.setLogLevel` action for the node.
+     * Mirrors the `$node-mgmt.setLogLevel` Moleculer action for UDS children.
+     */
+    setChildLogLevel(childId: string, level: string): boolean;
+    close(): Promise<void>;
+    private onConnection;
+}

package/dist/kernel/transport/local-endpoint-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Filesystem path (POSIX) or named-pipe path (Windows) a node listens on for
+ * its local addon-runners. Derived deterministically from the nodeId so a
+ * parent and its children agree without extra coordination.
+ */
+export declare function localEndpointPath(nodeId: string): string;

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

@@ -0,0 +1,46 @@
+/** Wire frame exchanged over a local channel. */
+export type Frame = {
+    readonly k: 'req';
+    readonly id: number;
+    readonly body: unknown;
+} | {
+    readonly k: 'res';
+    readonly id: number;
+    readonly ok: true;
+    readonly body: unknown;
+} | {
+    readonly k: 'res';
+    readonly id: number;
+    readonly ok: false;
+    readonly err: string;
+} | {
+    readonly k: 'evt';
+    readonly body: unknown;
+};
+export type RequestHandler = (body: unknown) => Promise<unknown>;
+export type EventHandler = (body: unknown) => void;
+/** A bidirectional request/response + one-way event channel over one socket. */
+export interface LocalChannel {
+    request(body: unknown): Promise<unknown>;
+    emit(body: unknown): void;
+    onRequest(handler: RequestHandler): void;
+    onEvent(handler: EventHandler): void;
+    onClose(handler: () => void): void;
+    close(): void;
+}
+/** Parent side: listens and hands a channel per accepted child connection. */
+export interface LocalTransportServer {
+    listen(): Promise<void>;
+    onConnection(handler: (channel: LocalChannel) => void): void;
+    close(): Promise<void>;
+}
+/** Child side: connects to the parent and returns a channel. */
+export interface LocalTransportClient {
+    connect(): Promise<LocalChannel>;
+    close(): Promise<void>;
+}
+/** The extension seam: a future transport implements this factory. */
+export interface LocalTransportFactory {
+    createServer(nodeId: string): LocalTransportServer;
+    createClient(nodeId: string): LocalTransportClient;
+}

package/dist/kernel/transport/parent-unowned-call.d.ts

@@ -0,0 +1,75 @@
+import { CapCallInput } from './child-cap-protocol.js';
+import { CapRouteResolver, HubLocalChildDispatcher } from './cap-route-resolver.js';
+import { HubNodeRegistry } from '../moleculer/node-registry.js';
+import { ServiceBroker } from 'moleculer';
+/**
+ * Minimal logger surface accepted by the unowned-call handler. Matches the
+ * `LocalChildRegistryLogger` shape so a single logger object can be shared.
+ */
+export interface ParentUnownedCallLogger {
+    debug?(msg: string, meta?: unknown): void;
+    warn?(msg: string, meta?: unknown): void;
+}
+export interface ParentUnownedCallDeps {
+    /**
+     * Returns the parent's `CapRouteResolver` at call time, or `null` when the
+     * parent has none (the agent) or it has not been constructed yet (the hub,
+     * before `onModuleInit` finishes — the resolver is built late, so this is a
+     * live getter, not a captured value).
+     */
+    readonly getResolver: () => CapRouteResolver | null;
+    /** The parent's Moleculer broker — reaches the cluster + the hub's `$`-infra services. */
+    readonly broker: ServiceBroker;
+    /**
+     * The hub's single capability authority. Used to find the node that OWNS a
+     * device-scoped native cap so the broker-fallback can be pinned to it instead
+     * of load-balancing the call (which can hit the wrong provider).
+     */
+    readonly nodeRegistry: HubNodeRegistry;
+    /**
+     * Hub-local UDS child dispatcher (`LocalChildRegistry`). Resolves
+     * device-scoped native caps OWNED by hub-local children (reolink/hikvision
+     * cameras run as forked hub-local UDS children — they register via the hub's
+     * `LocalChildRegistry`, NOT via `registerNode`, so the `nodeRegistry` lookup
+     * is empty for them) and dispatches the call to the owning child over UDS.
+     *
+     * A live GETTER (init-order safety): on the agent the local registry is built
+     * AFTER this handler, so the instance is captured lazily. Returns null when
+     * no local registry exists (failed to start) or when not yet constructed.
+     */
+    readonly getLocalDispatcher?: () => HubLocalChildDispatcher | null;
+    /**
+     * Optional predicate — returns `true` when `capName` is a DEVICE-NATIVE cap
+     * (`deviceNative: true` in its `CapabilityDefinition`): the provider IS the
+     * device and routes ONLY over UDS / the per-node native path, never as a plain
+     * Moleculer service. The kernel layer has no cap registry, so the wiring side
+     * (which does) injects this.
+     *
+     * It gates the registration-race recovery in the broker-fallback branch: when
+     * a device-scoped call's hub-local binding is not yet in the LocalChildRegistry
+     * (`resolveChildId === null`) and no remote owner is known, the handler applies
+     * a SHORT bounded retry, then — if still unresolved AND the cap is device-native
+     * — throws a precise "binding not yet registered" error instead of attempting
+     * the unpinned `brokerCallForCap`, which can NEVER reach a device-native cap and
+     * would surface the misleading doubled `${cap}.${cap}.${method}` Moleculer error.
+     *
+     * Omitted (or returning `false`) ⇒ legacy behaviour is preserved exactly: no
+     * retry, no precise error, straight to the existing broker fallback. This keeps
+     * deviceId-carrying SYSTEM-cap calls (e.g. `system.info({deviceId})`) fast.
+     */
+    readonly isDeviceNativeCap?: (capName: string) => boolean;
+    /** Optional logger for the broker-fallback diagnostic line. */
+    readonly logger?: ParentUnownedCallLogger;
+}
+/**
+ * Build the `onUnownedCall` handler the hub / agent passes into
+ * `new LocalChildRegistry({ ..., onUnownedCall })`.
+ *
+ * The returned handler:
+ *   - tries the resolver first (when present),
+ *   - falls back to the broker for `no-provider` resolver misses (the
+ *     `$`-infra / core services), and
+ *   - surfaces a clear error when the call is genuinely unroutable (so the
+ *     child's call rejects rather than hanging).
+ */
+export declare function createParentUnownedCallHandler(deps: ParentUnownedCallDeps): (input: CapCallInput) => Promise<unknown>;

package/dist/kernel/transport/socket-channel.d.ts

@@ -0,0 +1,27 @@
+import { Socket } from 'node:net';
+import { LocalChannel, RequestHandler, EventHandler } from './local-transport.js';
+export declare class SocketChannel implements LocalChannel {
+    private readonly socket;
+    private nextId;
+    private readonly pending;
+    private readonly decoder;
+    private requestHandler;
+    private eventHandler;
+    private closeHandler;
+    private closed;
+    private closeFired;
+    constructor(socket: Socket);
+    request(body: unknown): Promise<unknown>;
+    emit(body: unknown): void;
+    /** Replace the request handler. Only one handler is active at a time. */
+    onRequest(handler: RequestHandler): void;
+    /** Replace the event handler. Only one handler is active at a time. */
+    onEvent(handler: EventHandler): void;
+    /** Replace the close handler. Only one handler is active at a time. */
+    onClose(handler: () => void): void;
+    close(): void;
+    private send;
+    private onData;
+    private handleFrame;
+    private handleClose;
+}

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

@@ -0,0 +1,36 @@
+import { IEventBus, SystemEvent } from '@camstack/types';
+/**
+ * Minimal surface the bridge requires from `LocalChildRegistry`.
+ * Structurally typed so tests can provide a fake without any casts.
+ */
+export interface ChildEventBroadcaster {
+    /**
+     * Register the (single) child-event handler, or pass `null` to clear it.
+     * A new handler replaces the prior one; `null` removes it entirely.
+     */
+    onChildEvent(handler: ((childId: string, event: SystemEvent) => void) | null): void;
+    sendEventToChild(childId: string, event: SystemEvent, sourceNodeId: string): void;
+    broadcastEventToChildren(event: SystemEvent, sourceNodeId: string, exceptChildId?: string): void;
+}
+/**
+ * Dependencies for the UDS event bridge.
+ */
+export interface UdsEventBridgeDeps {
+    /** The parent-side child registry. Only the event-related surface is required. */
+    readonly registry: ChildEventBroadcaster;
+    /** The parent process's event bus (backed by `getBrokerEventBus(broker)`). */
+    readonly parentBus: IEventBus;
+    /** This process's Moleculer node ID (e.g. `'hub'` or `'agent-a1b2c3'`). */
+    readonly parentNodeId: string;
+}
+/**
+ * Create the parent-side UDS ↔ Moleculer event bridge.
+ *
+ * Call this once after the parent's `LocalChildRegistry` and `IEventBus` are
+ * both ready. The bridge is inert-but-correct while no children are connected
+ * (UDS child events never arrive, cluster events are fan-outed to zero children).
+ *
+ * @returns A disposer function that unsubscribes the bridge from the parent bus
+ *          and clears the child-event handler. Call it on process shutdown.
+ */
+export declare function createUdsEventBridge(deps: UdsEventBridgeDeps): () => void;

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

@@ -0,0 +1,22 @@
+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.)
+ */
+export interface UdsEventChannel {
+    emitEvent(event: SystemEvent): void;
+    onEvent(handler: (event: SystemEvent) => void): void;
+}
+/**
+ * Create a UDS-backed `IEventBus` for use inside a forked child process.
+ *
+ * @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

@@ -0,0 +1,18 @@
+import { 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>;
+}
+export declare class UdsLocalTransportClient implements LocalTransportClient {
+    private readonly path;
+    private channel;
+    constructor(path: string);
+    connect(): Promise<LocalChannel>;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,28 @@
+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.
+ */
+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>;
+}
+/**
+ * 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

@@ -0,0 +1,44 @@
+import { IScopedLogger, LogTags } from '@camstack/types';
+import { 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.
+ */
+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;
+}
+/**
+ * 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;
+}
+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.
+ */
+declare function createUdsLoggerWithControl(client: UdsLogSink, addonId: string, nodeId: string, scope?: string, tags?: LogTags): {
+    logger: IScopedLogger;
+    control: UdsLogLevelControl;
+};
+export { createUdsLogger, createUdsLoggerWithControl };

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

@@ -0,0 +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.
+ */
+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[];
+}

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

@@ -0,0 +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
+ */
+export declare function detectWorkspacePackagesDir(startDir: string): string | null;