@camstack/system 1.0.2

package/dist/kernel/moleculer/capabilities-access.d.ts

@@ -0,0 +1,21 @@
+import { ServiceBroker } from 'moleculer';
+import { BrokerRegistries } from './provider-registry.js';
+/**
+ * Build `ctx.capabilities` for a worker context.
+ *
+ * Broker mode (hub / agent / in-process addons): merges the local registry
+ * (providers from THIS process) with cross-process discovery via the
+ * Moleculer service registry — remote providers are returned as Proxy
+ * objects that forward method calls back through `broker.call(...)`.
+ * Synchronous on the read side because Moleculer's service registry is a
+ * local in-memory mirror of cluster state (updated via gossip).
+ *
+ * UDS mode (broker-less forked child, Phase F1+F2): `broker` is `undefined`,
+ * so `ctx.capabilities` is LOCAL-ONLY — it sees only providers registered in
+ * THIS process. This matches the canonical contract (CLAUDE.md: "`ctx.capabilities`
+ * is the LOCAL CapabilityRegistry of the calling addon's group runner"). For
+ * cross-process access a UDS child uses `ctx.api`, which routes over UDS to
+ * the parent's `onUnownedCall`.
+ */
+declare function buildCapabilitiesAccess(broker: ServiceBroker | undefined, localRegs: BrokerRegistries): import('@camstack/types').CapabilitiesAccess;
+export { buildCapabilitiesAccess };

package/dist/kernel/moleculer/child-addon-call-dispatch.d.ts

@@ -0,0 +1,46 @@
+import { AddonCallInput } from '../transport/child-cap-protocol.js';
+import { CustomActionRegistry } from '../custom-action-registry.js';
+import { ICamstackAddon, AddonDataPlaneEndpoint } from '@camstack/types';
+/**
+ * Serializable HTTP route descriptor sent from a forked child to the hub over
+ * UDS. The `handler` function on the live `IAddonHttpRoute` is intentionally
+ * OMITTED — MsgPack (the UDS frame codec) cannot encode a function, and the
+ * hub re-binds dispatch through the `addon-routes` cap's `invoke` method
+ * anyway. Mirrors the `addonRoutesCapability.getRoutes` output schema.
+ */
+export interface SerializableRouteDescriptor {
+    readonly method: string;
+    readonly path: string;
+    readonly access?: string;
+    readonly description?: string;
+}
+/**
+ * Resolved `addon-routes` provider lookup — the live provider object the addon
+ * registered (`buildAddonRouteProvider(...)`). Returning `null`/`undefined`
+ * means the addon registered no routes.
+ */
+export type RouteProviderLookup = (addonId: string) => object | null | undefined;
+/** Injected lookups the addon-call dispatcher uses to resolve addon-level surfaces. */
+export interface ChildAddonCallDispatchDeps {
+    /** Resolve the live `addon-routes` provider an addon registered, by addon id. */
+    getRouteProvider: RouteProviderLookup;
+    /** The runner-wide custom-action registry (populated during the init loop). */
+    customActions: CustomActionRegistry;
+    /** Resolve the loaded addon instance by id — used for the `settings` surface. */
+    getAddonInstance: (addonId: string) => ICamstackAddon | null;
+    /** Resolve an addon's live HTTP data-plane endpoints (published by its
+     *  `ctx.dataPlane` facility). Empty when the addon serves no data-plane. */
+    getDataPlanes: (addonId: string) => readonly AddonDataPlaneEndpoint[];
+}
+/**
+ * Creates the addon-level dispatcher the addon-runner wires to
+ * `LocalChildClient.onAddonCall`. Routes a {@link AddonCallInput} to one of the
+ * exhaustive {@link AddonCallTarget} surfaces (routes / custom / settings) —
+ * everything the per-addon Moleculer broker used to carry before the UDS
+ * migration removed it. The `target` switch is exhaustive (`never` check): a
+ * new surface added to the protocol union that isn't dispatched here is a
+ * COMPILE ERROR — the guard that makes a "missed link" impossible.
+ *
+ * Pure module — no Moleculer, no broker, no addon-runner dependency.
+ */
+export declare function createChildAddonCallDispatch(deps: ChildAddonCallDispatchDeps): (call: AddonCallInput) => Promise<unknown>;

package/dist/kernel/moleculer/child-cap-dispatch.d.ts

@@ -0,0 +1,20 @@
+import { CapCallInput } from '../transport/child-cap-protocol.js';
+/**
+ * Injected lookups that the dispatcher uses to resolve cap providers. A provider
+ * is an opaque object whose methods are resolved structurally (via {@link isCapMethod})
+ * at the UDS dispatch boundary. Returning `null`/`undefined` signals "no provider
+ * registered".
+ */
+export interface ChildCapDispatchDeps {
+    /** Resolve a singleton/system-scoped provider by cap name. */
+    getSingletonProvider(capName: string): object | null | undefined;
+    /** Resolve a device-scoped provider by cap name and device id. */
+    getDeviceProvider(capName: string, deviceId: number): object | null | undefined;
+}
+/**
+ * Creates a unified dispatcher that routes a {@link CapCallInput} to either a
+ * device-scoped or singleton provider, then invokes the requested method.
+ *
+ * Pure module — no Moleculer, no broker, no addon-runner dependency.
+ */
+export declare function createChildCapDispatch(deps: ChildCapDispatchDeps): (call: CapCallInput) => Promise<unknown>;

package/dist/kernel/moleculer/cluster-secret.d.ts

@@ -0,0 +1,15 @@
+/** Moleculer error `type` marking a registration rejected for a bad cluster secret. */
+export declare const CLUSTER_SECRET_MISMATCH_TYPE = "CLUSTER_SECRET_MISMATCH";
+/** Process exit code a runner uses when its registration is rejected for a bad secret. */
+export declare const CLUSTER_SECRET_REJECTED_EXIT_CODE = 78;
+/** SHA-256 hex digest of a cluster secret. Never transmit or log the raw secret. */
+export declare function hashClusterSecret(secret: string): string;
+/**
+ * True if a registration carrying `presentedHash` is allowed against a
+ * receiver whose own secret hashes to `expectedHash`.
+ * - `expectedHash` undefined → the gate is OFF; everything is allowed.
+ * - otherwise `presentedHash` must be present and equal (constant-time).
+ */
+export declare function clusterSecretMatches(expectedHash: string | undefined, presentedHash: string | undefined): boolean;
+/** Recognises a cluster-secret rejection, including after a Moleculer RPC round-trip. */
+export declare function isClusterSecretMismatchError(err: unknown): boolean;

package/dist/kernel/moleculer/core-cap-service.d.ts

@@ -0,0 +1,50 @@
+import { ServiceSchema } from 'moleculer';
+/**
+ * Default Moleculer service name for the hub core-capability bridge.
+ *
+ * `$`-prefixed so it never collides with an addon id (addon services
+ * take their name from `declaration.id`). It is still a regular,
+ * discoverable service — `findServiceCandidates` in `trpc-links.ts`
+ * scans every entry returned by `registry.getServiceList()`.
+ */
+export declare const CORE_CAP_SERVICE_NAME = "$core-caps";
+/**
+ * A single hub core-capability procedure, ready to expose as a
+ * Moleculer action.
+ *
+ * `actionName` must be the kebab-cased `<capName>.<method>` pair the
+ * worker-side `brokerTransportLink` resolves: it parses `op.path`,
+ * kebab-cases the namespace and looks for a service action ending in
+ * `.<capName>.<method>` (see `findServiceCandidates`). Mounting the
+ * action as `system.info` makes Moleculer register it as
+ * `$core-caps.system.info`, which matches that suffix lookup.
+ */
+export interface CoreCapAction {
+    /** Kebab-cased `<capName>.<method>` — e.g. `system.info`, `addon-settings-raw.getGlobal`. */
+    readonly actionName: string;
+    /** Invoke the underlying tRPC procedure with a trusted mesh context. */
+    readonly invoke: (input: unknown) => Promise<unknown> | unknown;
+}
+export interface CoreCapServiceOptions {
+    /** Moleculer service name. Defaults to {@link CORE_CAP_SERVICE_NAME}. */
+    readonly serviceName?: string;
+    readonly actions: readonly CoreCapAction[];
+}
+/**
+ * Wrap the hub's core (non-addon) tRPC procedures as a single Moleculer
+ * service so forked addons and remote agents can reach them through
+ * `ctx.api.<coreCap>.<method>`.
+ *
+ * Core routers (`system`, `addons`, `capabilities`, `nodes`, …) are
+ * mounted only as the hub's tRPC routers — no addon registers a
+ * provider for them, so `addon-service-factory` never gives them a
+ * Moleculer service. Without this bridge a forked addon's
+ * `ctx.api.<coreCap>` falls through `localProviderLink` into
+ * `brokerTransportLink`, whose load-balanced discovery wait has no
+ * deadline, and hangs forever.
+ *
+ * Mirrors `createAddonService`: each action deserializes typed arrays
+ * and normalizes Moleculer's `{}` (empty params) back to `undefined`
+ * so void-input procedures don't receive a spurious empty object.
+ */
+export declare function createCoreCapService(options: CoreCapServiceOptions): ServiceSchema;

package/dist/kernel/moleculer/crash-supervisor.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Per-runner crash circuit-breaker.
+ *
+ * Replaces the old infinite-respawn loop in `process-service.ts`'s
+ * `spawnRunner` exit handler. A runner that exits unexpectedly is
+ * respawned with exponential backoff while the crash count inside a
+ * sliding time window stays under `maxCrashes`. Once the window fills
+ * up the breaker trips: respawning STOPS and the caller marks the
+ * addon `failed`.
+ *
+ * State is per-runner (keyed on `runnerId`) and crash timestamps older
+ * than `windowMs` age out — a runner that crashed once an hour ago and
+ * then crashes again starts a fresh streak.
+ */
+/** Tunables for `CrashSupervisor`. */
+export interface CrashSupervisorOptions {
+    /** CRASH_WINDOW_MS — crashes older than this age out of the count. */
+    readonly windowMs: number;
+    /** Crashes within the window before the breaker trips to `failed`. */
+    readonly maxCrashes: number;
+    /** Backoff cap — the exponential backoff never exceeds this. */
+    readonly maxBackoffMs: number;
+}
+/**
+ * Outcome of recording a crash. Discriminated on `action`:
+ *   - `respawn` — under the threshold, schedule another spawn after `backoffMs`.
+ *   - `failed`  — breaker tripped, do NOT respawn; mark the addon `failed`.
+ */
+export type CrashDecision = {
+    readonly action: 'respawn';
+    readonly backoffMs: number;
+    readonly crashesInWindow: number;
+} | {
+    readonly action: 'failed';
+    readonly crashesInWindow: number;
+};
+/** Per-runner crash circuit-breaker. Replaces the old infinite-respawn loop. */
+export declare class CrashSupervisor {
+    private readonly opts;
+    /** runnerId → crash timestamps (ms epoch), pruned to the active window. */
+    private readonly crashes;
+    constructor(opts: CrashSupervisorOptions);
+    /**
+     * Record a crash for `runnerId` and decide what to do. `now` is
+     * injectable for deterministic tests; production calls omit it.
+     */
+    recordCrash(runnerId: string, now?: number): CrashDecision;
+    /** Clear crash history after a clean run / manual restart. */
+    reset(runnerId: string): void;
+}

package/dist/kernel/moleculer/device-cap-proxy.d.ts

@@ -0,0 +1,79 @@
+import { deviceOpsCapability, AddonApi, CapabilityDefinition, DeviceManagerApi, IDevice, IEventBus, IKernelStreamProbe, IScopedLogger, InferProvider } from '@camstack/types';
+import { ServiceBroker } from 'moleculer';
+import { DeviceRegistry } from '../device-registry.js';
+import { CapabilityRegistry } from '../capability-registry.js';
+import { LocalChildRegistry } from '../transport/local-child-registry.js';
+export { NATIVE_PROVIDER_SERVICE_INFIX } from '../transport/cap-action-name.js';
+export interface WorkerDeviceManagerOptions {
+    readonly api: AddonApi;
+    readonly addonId: string;
+    readonly nodeId: string;
+    readonly logger: IScopedLogger;
+    readonly eventBus: IEventBus;
+    readonly registry: DeviceRegistry;
+    readonly capabilityRegistry?: CapabilityRegistry;
+    readonly broker?: ServiceBroker;
+    /**
+     * UDS-only forked child (Phase F1+F2): no `capabilityRegistry`, no
+     * `broker`. `registerNativeCap` populates the per-process `workerNativeCaps`
+     * map (read by the UDS dispatch in `addon-runner`) but mounts NO Moleculer
+     * `<addon>.native-provider.*` service — the child has no broker.
+     */
+    readonly udsMode?: boolean;
+    readonly streamProbe?: IKernelStreamProbe;
+}
+/** Subscribe to worker native-cap set changes. Pass null to clear. */
+export declare function setWorkerNativeCapsChangeListener(listener: (() => void) | null): void;
+/**
+ * Mount the Moleculer service exposing `<addonId>.native-provider.<capName>`
+ * with per-method actions that dispatch to `workerNativeCaps`. Called
+ * lazily on first `registerNativeCap` AND proactively at worker boot for
+ * always-on caps (e.g. `device-ops`) so the INFO packet sent at TCP
+ * connect already advertises the service.
+ */
+export declare function mountNativeCapService<TCap extends CapabilityDefinition>(broker: ServiceBroker, addonId: string, cap: TCap): void;
+export declare function getWorkerNativeCap(capName: string, deviceId: number): unknown | null;
+export declare function clearWorkerNativeCapsForDevice(deviceId: number): void;
+export declare function getWorkerNativeCapNames(): readonly string[];
+/**
+ * Snapshot of every device-scoped native cap this worker hosts, with the
+ * device ids and registering addonId for each. Used by the D3 registration
+ * handshake (`process-runner`/`group-runner` → `$hub.registerNode`'s
+ * `nativeCaps` field) so the hub's `HubNodeRegistry` learns device-scoped
+ * native caps (including addonId) without the pull-based discovery sweep.
+ *
+ * Groups by `(capName, addonId)` because different addons in the same group
+ * may register the same cap for different devices — each such pair becomes
+ * its own entry so the hub can build the correct Moleculer proxy target.
+ */
+export declare function getWorkerNativeCapSnapshot(): ReadonlyArray<{
+    readonly capName: string;
+    readonly addonId: string;
+    readonly deviceIds: readonly number[];
+}>;
+export declare function getWorkerNativeCapsForDevice(deviceId: number): readonly string[];
+/**
+ * Read-only accessor for UDS dispatch — returns the provider registered for a
+ * given (capName, deviceId) pair, or `undefined` when none is registered.
+ * Returns the provider as an opaque `object`; `createChildCapDispatch` resolves
+ * its methods structurally via a type guard, so no cast is needed.
+ */
+export declare function getWorkerNativeCapProvider(capName: string, deviceId: number): object | undefined;
+/**
+ * Hub-side proxy factory. Returns an object whose method access dispatches
+ * via `broker.call('<addonId>.native-provider.<capName>.<method>', input)`.
+ * Calls are wrapped in exponential-backoff retry to absorb the race between
+ * worker `broker.createService` and the hub's Moleculer registry INFO packet.
+ */
+export declare function buildNativeCapProxy(broker: ServiceBroker, addonId: string, capName: string, deviceId: number): Record<string, (input: unknown) => Promise<unknown>>;
+/**
+ * Hub-side proxy for a device-scoped native cap whose owning runner is a
+ * HUB-LOCAL forked child reachable over UDS. Mirrors {@link buildNativeCapProxy}
+ * but dispatches via `LocalChildRegistry.callCapOnChild` (UDS) instead of
+ * `broker.call` — the child no longer hosts a Moleculer service after the UDS
+ * cutover, so a broker call fails "is not found". The `deviceId` is merged into
+ * the method args (provider convention) and carried as the routing field.
+ */
+export declare function buildUdsNativeCapProxy(registry: LocalChildRegistry, childId: string, capName: string, deviceId: number): Record<string, (input: unknown) => Promise<unknown>>;
+export declare function buildDeviceOpsProvider(device: IDevice): InferProvider<typeof deviceOpsCapability>;
+export declare function createBrokerDeviceManagerApi(opts: WorkerDeviceManagerOptions): DeviceManagerApi;

package/dist/kernel/moleculer/event-bus-core.d.ts

@@ -0,0 +1,53 @@
+import { SystemEvent, EventFilter } from '@camstack/types';
+export interface SubscriberEntry {
+    /** Original filter — kept whole so non-category dimensions are honoured per-event. */
+    readonly filter: EventFilter | string | undefined;
+    /** Pre-computed category pattern for the cheap pre-filter. */
+    readonly categoryPattern: string;
+    readonly handler: (event: SystemEvent) => void;
+}
+export interface SharedBusState {
+    /**
+     * Subscribers indexed by category pattern. Each entry also carries its full
+     * filter so the subsequent `matchesEventFilter` call can reject events that
+     * match the category but not the scope (deviceId, addonId, …).
+     */
+    readonly handlers: Map<string, Set<SubscriberEntry>>;
+    /**
+     * In-memory recent-events buffer. The deny-list below filters out
+     * high-frequency categories so the buffer only accumulates audit-grade
+     * lifecycle events.
+     *
+     * Cleared on server restart (intentional — events are volatile by design).
+     */
+    readonly recent: SystemEvent[];
+}
+export declare function createSharedBusState(): SharedBusState;
+export declare function matchesPattern(pattern: string, category: string): boolean;
+export declare function extractCategoryPattern(filter: EventFilter | string): string;
+/**
+ * Match an event against the full `EventFilter`. The Map-keyed subscribe path
+ * only handles the category pattern (deciding which handler set to fan out to);
+ * this function applies the remaining scope dimensions (`agentId`, `addonId`,
+ * `deviceId`, `source`, `since`) so per-device / per-addon subscribers don't
+ * receive sibling events.
+ */
+export declare function matchesEventFilter(event: SystemEvent, filter: EventFilter | string | undefined): boolean;
+/**
+ * Categories filtered out of the `recent[]` ring buffer.
+ *
+ * High-frequency, low-value-for-the-operator categories — periodic metrics
+ * snapshots, per-frame inference traces, raw motion-mask dumps, model-download
+ * progress, etc. They still fan out to live subscribers (UI charts that
+ * explicitly listen for them), but do NOT enter the recent-events ring so
+ * meaningful events (motion / phase transitions / device lifecycle / addon
+ * lifecycle / recording / detection.event) survive in the last-N window without
+ * being displaced by per-frame noise.
+ */
+export declare const RING_BUFFER_DENY_PATTERNS: readonly string[];
+export declare function isHighFrequencyCategory(category: string): boolean;
+/**
+ * Deliver `event` to all matching local subscribers and — unless it is
+ * high-frequency — append it to the `recent[]` ring.
+ */
+export declare function deliverShared(state: SharedBusState, event: SystemEvent): void;

package/dist/kernel/moleculer/event-bus.d.ts

@@ -0,0 +1,53 @@
+import { ServiceBroker } from 'moleculer';
+import { IEventBus } from '@camstack/types';
+/**
+ * Narrow interface for the Moleculer ServiceBroker surface used in this file.
+ * moleculer's index.d.ts chains through eventemitter2 whose package.json has
+ * no `types` field; typescript-eslint's no-unsafe-* rules flag every
+ * broker.X access. Cast once per function: `const bkr = broker as unknown as BrokerLike`.
+ */
+export interface BrokerLike {
+    readonly nodeID: string;
+    call<T = unknown>(action: string, params?: unknown, opts?: unknown): Promise<T>;
+    createService(schema: unknown): void;
+    waitForServices(service: unknown, timeout?: number): Promise<unknown>;
+    broadcast(event: string, data: unknown): void;
+    localBus: {
+        on(event: string, handler: (data: unknown) => void): void;
+    };
+    logger: {
+        warn?: (msg: string) => void;
+    };
+}
+/**
+ * Topic prefix for clustered EventBus broadcasts. The `camstack.evt.`
+ * namespace keeps our events disjoint from Moleculer internal events
+ * (`$node.*`, `$services.*`) — the `$event-bus` service's
+ * `camstack.evt.**` wildcard handler therefore never sees them.
+ */
+export declare const EVENT_TOPIC_PREFIX = "camstack.evt.";
+/** Build the Moleculer broadcast topic for an event category. */
+export declare function clusterEventTopic(category: string): string;
+/**
+ * Register the `$event-bus` service on a broker. MUST be called BEFORE
+ * `broker.start()` — Moleculer announces a service's event
+ * subscriptions to remote nodes only during the discovery handshake;
+ * a post-start `createService` propagates via the ~10s heartbeat and
+ * makes cross-node delivery unreliable in the meantime.
+ *
+ * The service's single wildcard handler (`camstack.evt.**`) is the
+ * inbound bridge: every `broker.broadcast('camstack.evt.<cat>', event)`
+ * from any node lands here. Self-origin echoes are dropped (the
+ * emitting node already delivered synchronously in `emit`).
+ *
+ * Idempotent. Internal service (`$`-prefixed) — hidden from the
+ * capability graph.
+ *
+ * Callers:
+ *  - hub backend (`MoleculerService.onModuleInit`), before `broker.start()`
+ *  - agent bootstrap, before `broker.start()`
+ *  - forkable process / group runner, before `broker.start()`
+ */
+export declare function registerEventBusService(broker: ServiceBroker): void;
+export declare function getBrokerEventBus(broker: ServiceBroker): IEventBus;
+export declare function createBrokerEventBus(broker: ServiceBroker, addonId: string): IEventBus;

package/dist/kernel/moleculer/hub-log-forwarder.d.ts

@@ -0,0 +1,36 @@
+import { LogTags } from '@camstack/types';
+import { ServiceBroker } from 'moleculer';
+interface LogEntry {
+    timestamp: Date;
+    level: string;
+    scope?: string;
+    message: string;
+    meta?: Record<string, unknown>;
+    tags?: LogTags;
+}
+/**
+ * Hub Log Forwarder — forwards log entries to the hub via $hub.log.
+ *
+ * Listens for Moleculer node discovery events. When the hub node
+ * connects, forwarding activates. When it disconnects, forwarding
+ * pauses and resumes on reconnect. No timeouts — fully event-driven.
+ *
+ * NOTE on `console.*` below: this class IS the log transport. Its own
+ * lifecycle messages (connected / disconnected / call-failed) must NOT
+ * be routed through a hub-forwarding logger — that would recurse (the
+ * log transport logging about itself through itself). The reference
+ * `HubForwarderDestination` in `@camstack/system` solves the same problem
+ * with an injected `statusLogger` that is wired to a non-forwarding
+ * destination. `HubLogForwarder` has no such injection point and is
+ * currently unused in the tree (exported only), so its status writes
+ * stay on raw `console.*` as a deliberate, documented residual.
+ */
+declare class HubLogForwarder {
+    private readonly broker;
+    private connected;
+    constructor(broker: ServiceBroker);
+    initialize(): Promise<void>;
+    write(entry: LogEntry): void;
+    shutdown(): Promise<void>;
+}
+export { HubLogForwarder };

package/dist/kernel/moleculer/hub-service.d.ts

@@ -0,0 +1,35 @@
+import { ServiceSchema } from 'moleculer';
+import { LogTags } from '@camstack/types';
+import { RegisterNodeParams } from './node-registry.js';
+interface HubServiceDeps {
+    readonly getAddonConfig: (addonId: string) => unknown;
+    readonly getSettings: (scope: string, key?: string) => unknown;
+    readonly getRecentEvents: (category?: string, limit?: number) => readonly unknown[];
+    readonly onLog: (entry: {
+        level: string;
+        message: string;
+        addonId: string;
+        nodeId: string;
+        scope?: string;
+        tags?: LogTags;
+        meta?: Record<string, unknown>;
+    }) => void;
+    readonly onSetLogLevel?: (level: string) => void;
+    /**
+     * D3 registration handshake. A node calls `$hub.registerNode` once it
+     * has finished mounting EVERY service; the payload is its complete cap
+     * manifest. Idempotent — replaces the node's prior manifest entirely.
+     */
+    readonly onRegisterNode?: (params: RegisterNodeParams) => void;
+    /** Explicit deregistration (graceful shutdown). `$node.disconnected` covers crashes. */
+    readonly onUnregisterNode?: (nodeId: string) => void;
+    /**
+     * SHA-256 hash of the hub's own `CAMSTACK_CLUSTER_SECRET`, or `undefined`
+     * when no secret is configured. When set, `$hub.registerNode` rejects any
+     * node not presenting a matching `clusterSecretHash`. (Cluster-secret gate.)
+     */
+    readonly expectedClusterSecretHash?: string;
+}
+declare function createHubService(deps: HubServiceDeps): ServiceSchema;
+export { createHubService };
+export type { HubServiceDeps };

package/dist/kernel/moleculer/node-registry.d.ts

@@ -0,0 +1,126 @@
+/**
+ * HubNodeRegistry — the single authority for which capabilities each
+ * cluster node provides. Holds the union of node manifests delivered by
+ * the D3 `$hub.registerNode` handshake; a node is dropped on
+ * `$node.disconnected`. Pure data — no Moleculer, no timers, no scan.
+ */
+/**
+ * A capability call function — routes a method call to a remote cap provider
+ * via Moleculer. Moved here from `capability-bridge.ts` when that file was
+ * deleted as part of the D3 clean-up (Task 11).
+ */
+type CallFn = (method: string, params: unknown, targetNodeId?: string) => Promise<unknown>;
+/** One addon's contribution within a node's registration manifest. */
+interface RegisteredAddonManifest {
+    readonly addonId: string;
+    readonly capabilities: readonly string[];
+}
+/**
+ * One device-scoped native cap a node hosts, with the device ids that
+ * registered it and the addonId of the registering addon. Device-scoped
+ * native caps (`ctx.registerNativeCap` from a `BaseDevice` subclass) are
+ * registered per device AFTER the node's system caps, once background device
+ * restore completes — so the node re-handshakes carrying these once they are
+ * known (D3 idempotent replace).
+ *
+ * `addonId` is required for the hub to build the correct Moleculer proxy
+ * target (`<addonId>.native-provider.<capName>.<method>`). It replaces the
+ * pull-based `syncWorkerNativeCaps` discovery sweep (Task 13).
+ */
+interface RegisteredNativeCap {
+    readonly capName: string;
+    readonly addonId: string;
+    readonly deviceIds: readonly number[];
+}
+/** Payload of the `$hub.registerNode` RPC — a node's COMPLETE manifest. */
+interface RegisterNodeParams {
+    readonly nodeId: string;
+    readonly addons: readonly RegisteredAddonManifest[];
+    /**
+     * Device-scoped native caps the node hosts. Optional — absent (or empty)
+     * on the FIRST handshake, populated by the re-handshake the node fires
+     * after `runWorkerDeviceRestoreWithRetry` completes. Each entry includes
+     * the registering `addonId` so the hub can build the correct Moleculer
+     * proxy target without the pull-based discovery sweep (Task 13).
+     */
+    readonly nativeCaps?: readonly RegisteredNativeCap[];
+    /**
+     * SHA-256 hash of the node's `CAMSTACK_CLUSTER_SECRET`. Optional — absent
+     * when the node has no secret configured. Verified by the `registerNode`
+     * receiver; never carries the raw secret. (Cluster-secret registration gate.)
+     */
+    readonly clusterSecretHash?: string;
+}
+/** Ack returned by `$hub.registerNode` — presence of `ok` is the signal. */
+interface RegisterNodeResult {
+    readonly ok: true;
+}
+/** Flattened registry view: one row per (node, addon, capability). */
+interface NodeCapEntry {
+    readonly nodeId: string;
+    readonly addonId: string;
+    readonly capName: string;
+}
+/** Flattened native-cap view: one row per (node, native cap, device). */
+interface NodeNativeCapEntry {
+    readonly nodeId: string;
+    readonly addonId: string;
+    readonly capName: string;
+    readonly deviceId: number;
+}
+declare class HubNodeRegistry {
+    /** nodeId → its complete addon manifest (last `registerNode` wins). */
+    private readonly nodes;
+    /** nodeId → its device-scoped native caps (last `registerNode` wins). */
+    private readonly nativeCaps;
+    /**
+     * deviceId → flat native-cap entries for THAT device, across all nodes.
+     * Maintained incrementally on every `registerNode`/`removeNode` so a
+     * per-device lookup is O(caps-for-device) instead of flattening the whole
+     * cluster (`listNativeCapEntries()`) and filtering — the latter makes the
+     * per-device `getBindings`, run for every device in `getAllBindings`, an
+     * O(D²·C) boot-time hot spot. Insertion order mirrors `listNativeCapEntries`
+     * (node-registration order) so consumers that take the first match are
+     * unaffected.
+     */
+    private readonly nativeCapsByDevice;
+    /**
+     * Drop every `nativeCapsByDevice` entry contributed by `nodeId`, reading the
+     * node's CURRENT (about-to-be-replaced) native caps to know which device
+     * rows it touched. Must run BEFORE `nativeCaps` is overwritten/deleted.
+     */
+    private dropNodeFromDeviceIndex;
+    /**
+     * Replace the node's ENTIRE manifest atomically — addons AND native
+     * caps. Idempotent: a reconnect, hot-update, or post-device-restore
+     * re-handshake simply overwrites. Partial state is impossible because
+     * the node sends its complete picture every time.
+     */
+    registerNode(params: RegisterNodeParams): void;
+    /** Drop a node entirely — caps AND native caps — on `$node.disconnected`. */
+    removeNode(nodeId: string): void;
+    /** The node's manifest, or undefined when the node never registered. */
+    getNodeManifest(nodeId: string): readonly RegisteredAddonManifest[] | undefined;
+    /**
+     * The node's device-scoped native caps. `[]` when the node registered
+     * without any (or has not yet re-handshaked post-device-restore);
+     * `undefined` when the node never registered at all.
+     */
+    getNodeNativeCaps(nodeId: string): readonly RegisteredNativeCap[] | undefined;
+    /** Flat (nodeId, addonId, capName) view of the whole cluster. */
+    listEntries(): readonly NodeCapEntry[];
+    /** Flat (nodeId, addonId, capName, deviceId) native-cap view of the whole cluster. */
+    listNativeCapEntries(): readonly NodeNativeCapEntry[];
+    /**
+     * Native-cap entries for ONE device, across all nodes — O(caps-for-device).
+     * Equivalent to `listNativeCapEntries().filter(e => e.deviceId === deviceId)`
+     * but served from the incrementally-maintained `nativeCapsByDevice` index, so
+     * per-device resolution (and `getAllBindings`, which runs it per device)
+     * doesn't flatten the whole cluster each call.
+     */
+    listNativeCapEntriesForDevice(deviceId: number): readonly NodeNativeCapEntry[];
+    /** Every node id currently registered. */
+    listNodeIds(): readonly string[];
+}
+export { HubNodeRegistry };
+export type { CallFn, RegisteredAddonManifest, RegisteredNativeCap, RegisterNodeParams, RegisterNodeResult, NodeCapEntry, NodeNativeCapEntry, };

package/dist/kernel/moleculer/process-context.d.ts

@@ -0,0 +1,4 @@
+import { ServiceBroker } from 'moleculer';
+import { IAddonProcessManager } from '@camstack/types';
+declare function createScopedProcessManager(broker: ServiceBroker, addonId: string): IAddonProcessManager;
+export { createScopedProcessManager };