@camstack/system 1.0.2

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

@@ -0,0 +1,72 @@
+import { ChildProcess, SpawnOptions } from 'node:child_process';
+import { ServiceSchema } from 'moleculer';
+/** One addon hosted inside a runner subprocess. */
+interface RunnerAddonSpec {
+    readonly addonId: string;
+    readonly addonDir: string;
+}
+interface SpawnedProcess {
+    readonly pid: number;
+    readonly nodeId: string;
+    readonly name: string;
+    /**
+     * Synthetic supervisor label `runner:${runnerId}` — the real list of
+     * hosted addons lives on `runnerAddons`. The normal case is a size-1
+     * `runnerAddons` array (one addon, one process); the media-pipeline
+     * group is the sole multi-addon exception.
+     */
+    readonly addonId: string;
+    readonly addonDir: string;
+    /** Every addon hosted by this runner subprocess (size 1 in the normal case). */
+    readonly runnerAddons: readonly RunnerAddonSpec[];
+    readonly startedAt: number;
+    restartCount: number;
+    /**
+     * Runner lifecycle state. `failed` is terminal — the D6 crash
+     * circuit-breaker tripped (too many crashes inside `CRASH_WINDOW_MS`)
+     * and the runner will NOT be respawned. `crashed` is transient — the
+     * window between an exit and the next backoff respawn.
+     */
+    state: 'starting' | 'running' | 'stopping' | 'stopped' | 'crashed' | 'failed';
+    child: ChildProcess;
+}
+interface ProcessInfo {
+    readonly pid: number;
+    readonly nodeId: string;
+    readonly name: string;
+    readonly addonId: string;
+    /**
+     * The full list of addon ids inside this runner subprocess. Size 1 in
+     * the normal one-addon-one-process case; longer only for the media
+     * group. Cluster page UI expands this to render every addon under the
+     * same process card so operators see what's running where.
+     */
+    readonly addonIds: readonly string[];
+    /** Runner label — the `runnerId` this subprocess was spawned with. */
+    readonly groupId: string;
+    readonly isolated: boolean;
+    readonly spawnedBy: string | null;
+    readonly startedAt: number;
+    readonly restartCount: number;
+    readonly state: string;
+    readonly cpuPercent: number;
+    readonly memoryRss: number;
+    readonly uptimeSeconds: number;
+}
+/**
+ * Subprocess spawner injected into `createProcessService`. Production
+ * code passes `child_process.spawn`; tests pass a fake that records
+ * the call shape and returns a stub `ChildProcess`. Centralising the
+ * dependency here is the only ESM-safe way to intercept spawn — the
+ * `node:child_process` module export is non-configurable so `vi.spyOn`
+ * fails. The injection point is private to this module: callers don't
+ * see it, so the public `createProcessService(parentNodeId, dataDir)`
+ * shape stays unchanged.
+ */
+type SpawnFn = (command: string, args: readonly string[], opts: SpawnOptions) => ChildProcess;
+interface ProcessServiceDeps {
+    readonly spawnFn?: SpawnFn;
+}
+declare function createProcessService(parentNodeId: string, dataDir: string, deps?: ProcessServiceDeps, parentTcpPort?: number, parentUdsPath?: string): ServiceSchema;
+export { createProcessService };
+export type { ProcessInfo, SpawnedProcess };

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

@@ -0,0 +1,28 @@
+import { ServiceBroker } from 'moleculer';
+/**
+ * Per-broker provider registries. In production there is one broker per
+ * process, so these behave like module-scoped singletons. In tests that
+ * spin up multiple brokers in the same process, each broker gets its
+ * own isolated set of maps so providers don't leak across nodes.
+ */
+interface BrokerRegistries {
+    readonly providers: Map<string, unknown[]>;
+    readonly preferred: Map<string, string>;
+    readonly byAddonId: Map<string, Map<string, unknown>>;
+}
+declare function getRegistries(brokerNodeId: string): BrokerRegistries;
+export { getRegistries };
+export type { BrokerRegistries };
+declare function withAddonScope<T>(addonId: string, fn: () => T): T;
+/** Exported for test harnesses that drive the factory manually. */
+export { withAddonScope };
+/** The addon id currently in scope, used by `registerProvider` to tag providers. */
+declare function getCurrentAddonId(): string | null;
+export { getCurrentAddonId };
+/** Update the preferred provider for a capability (called from binding-changed subscribers). */
+declare function setPreferredProvider(capabilityName: string, addonId: string | null, brokerNodeId?: string): void;
+export { setPreferredProvider };
+declare function ensureBindingSubscription(broker: ServiceBroker): void;
+export { ensureBindingSubscription };
+declare function __resetBindingSubscriptionForTests(): void;
+export { __resetBindingSubscriptionForTests };

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

@@ -0,0 +1,62 @@
+import { ServiceBroker } from 'moleculer';
+import { IEventBus, IScopedLogger, ReadinessRegistry } from '@camstack/types';
+/**
+ * Minimal interface for the `LocalChildClient` surface used in UDS-mode
+ * readiness hydration. Declared here (rather than importing the concrete
+ * class) so this module stays free of a direct transport dependency and
+ * remains independently testable with a plain fake object.
+ */
+interface UdsReadinessClient {
+    /** True once `start()` has connected and registered with the parent. */
+    readonly isConnected: boolean;
+    /** Request the current readiness snapshot from the parent over UDS. */
+    requestReadinessSnapshot(): Promise<readonly import('@camstack/types').IReadinessRegistryRecord[]>;
+    /** Register a callback fired each time the client connects (including reconnects). */
+    onConnected(cb: () => void): void;
+}
+/**
+ * Return the shared ReadinessRegistry for this broker — one per
+ * process is enough. Every addon context on the same broker gets the
+ * same instance via `ctx.kernel.readinessRegistry`.
+ *
+ * For non-hub brokers (forked workers + remote agents) the registry
+ * is hydrated from the hub's `$readiness.getSnapshot` Moleculer action
+ * on every `$node.connected` — this closes the boot-time race where
+ * `broker.broadcast` consumers on the hub fire before the worker is
+ * in the cluster, and makes hub reconnects refresh consumer state
+ * without forcing every producer to re-emit. Live deltas continue
+ * through the normal `system.ready-state` event bridge; hydrate skips
+ * entries already observed locally.
+ */
+declare function getOrInitReadinessRegistry(broker: ServiceBroker, eventBus: IEventBus, logger: IScopedLogger): ReadinessRegistry;
+/**
+ * Return (or create) the shared `ReadinessRegistry` for a UDS-only child
+ * process — one per child node id. The registry is hydrated from the parent
+ * over UDS instead of via `$readiness.getSnapshot` Moleculer action.
+ *
+ * **Hydration strategy:**
+ *   - Initial snapshot: `client.requestReadinessSnapshot()` is called once
+ *     `client.isConnected` becomes true (the `onConnected` callback).
+ *   - Reconnect: each time `onConnected` fires again (the client re-connected
+ *     after a parent-side restart), a fresh snapshot is pulled so pending
+ *     `awaitReady` callers can unblock.
+ *   - Live deltas: `system.ready-state` events arrive via the UDS event bus
+ *     (Phase C) — the registry ingests them through its own event-bus
+ *     subscription, exactly as in broker mode.
+ *
+ * **No `$services.changed` reconcile signal needed:**
+ *   The broker-mode `$services.changed` reconcile existed because Moleculer
+ *   broadcasts can be dropped during the boot window. Over UDS the parent
+ *   reliably forwards every `system.ready-state` delta to each child (via
+ *   the event bridge wired in Phase C). Dropped deltas are not a concern;
+ *   the initial snapshot + live event bus is sufficient. A new
+ *   parent-to-child "topology changed, re-pull" signal is therefore NOT
+ *   added — it would be redundant and would complicate the protocol.
+ *
+ * **`awaitReady`/`acquireCapability`/`onReadyState` semantics unchanged.**
+ *
+ * Keep `$readiness.getSnapshot` (broker path) intact — Phase F removes it.
+ */
+declare function getOrInitReadinessRegistryForClient(client: UdsReadinessClient, eventBus: IEventBus, logger: IScopedLogger, nodeId: string): ReadinessRegistry;
+export { getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient };
+export type { UdsReadinessClient };

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

@@ -0,0 +1,7 @@
+import { ServiceSchema } from 'moleculer';
+import { IReadinessRegistry, IReadinessRegistryRecord } from '@camstack/types';
+export interface ReadinessServiceDeps {
+    readonly getSnapshot: () => readonly IReadinessRegistryRecord[];
+}
+export declare function createReadinessService(deps: ReadinessServiceDeps): ServiceSchema;
+export declare function createReadinessServiceForRegistry(registry: IReadinessRegistry): ServiceSchema;

package/dist/kernel/moleculer/register-node-client.d.ts

@@ -0,0 +1,35 @@
+import { RegisteredAddonManifest, RegisteredNativeCap, RegisterNodeParams } from './node-registry.js';
+/** Minimal broker surface this client needs. */
+interface RegisterNodeBroker {
+    call(action: string, params: unknown, opts?: {
+        nodeID?: string;
+    }): Promise<unknown>;
+}
+interface CallRegisterNodeOptions {
+    /** `'hub'` → `$hub.registerNode`; `'agent'` → `$agent.registerNode`. */
+    readonly target: 'hub' | 'agent';
+    /** Required when target is `'agent'` — the agent's nodeID to route to. */
+    readonly targetNodeId?: string;
+    /** First retry delay; doubles each attempt, capped at 5000ms. Default 250. */
+    readonly baseDelayMs?: number;
+    /** Abort the retry loop (e.g. on node shutdown). */
+    readonly signal?: AbortSignal;
+    /** Optional logger for retry diagnostics. */
+    readonly log?: (msg: string) => void;
+}
+/**
+ * Build a `RegisterNodeParams` from a node id, its per-addon manifests,
+ * optionally its device-scoped native caps, and optionally the SHA-256 hash
+ * of the cluster secret. `nativeCaps` is omitted entirely on the first
+ * handshake; `clusterSecretHash` is omitted when no secret is configured.
+ */
+declare function buildNodeManifest(nodeId: string, addons: readonly RegisteredAddonManifest[], nativeCaps?: readonly RegisteredNativeCap[], clusterSecretHash?: string): RegisterNodeParams;
+/**
+ * Call `<target>.registerNode` and retry until the parent acks. The loop
+ * terminates ONLY on a successful ack or an abort — there is no fixed
+ * attempt cap, because the real terminating condition is "the hub
+ * received it", not "we tried N times".
+ */
+declare function callRegisterNodeWithRetry(broker: RegisterNodeBroker, params: RegisterNodeParams, opts: CallRegisterNodeOptions): Promise<void>;
+export { callRegisterNodeWithRetry, buildNodeManifest };
+export type { RegisterNodeBroker, CallRegisterNodeOptions };

package/dist/kernel/moleculer/remote-logger.d.ts

@@ -0,0 +1,43 @@
+import { ServiceBroker } from 'moleculer';
+import { IScopedLogger, LogTags } from '@camstack/types';
+import { BrokerLike } from './event-bus.js';
+/**
+ * Call after `broker.waitForServices('$hub')` to enable log forwarding.
+ *
+ * Marks the broker connected and flushes any log lines buffered during
+ * the pre-discovery window. With no argument (test harnesses), every
+ * known broker state is connected and flushed — the buffered entries
+ * carry their own dispatch closures so no broker reference is needed.
+ */
+declare function setHubConnected(broker?: ServiceBroker): void;
+/**
+ * Test-only: clear all per-broker hub-connection state + buffers and the
+ * process-wide baseline so specs that create brokers in sequence start
+ * from a clean slate. Production never calls this.
+ */
+declare function __resetHubConnectedForTests(): void;
+export { __resetHubConnectedForTests };
+declare function createRemoteLogger(broker: ServiceBroker, addonId: string, scope?: string, tags?: LogTags): IScopedLogger;
+export { createRemoteLogger };
+/**
+ * Build a hub-forwarding logger for a forked-process runner (process-runner
+ * / group-runner). The runner has no `AddonContext` of its own — its own
+ * diagnostics ("started", "handshake failed", …) would otherwise be raw
+ * `console.*` that never reaches the hub `LogManager`. This routes them
+ * through the same `$hub.log` transport every addon logger uses, with the
+ * Part A pre-connect buffer so boot-time lines survive.
+ *
+ * `scope` lets the runner tag its own lines (e.g. `process-runner`) so the
+ * hub renderer distinguishes runner plumbing from the hosted addon's output.
+ */
+declare function createRunnerLogger(broker: ServiceBroker, addonId: string, scope: string): IScopedLogger;
+export { createRunnerLogger };
+/**
+ * Test-only: build a remote logger against a structural broker spy.
+ * `createRemoteLogger` only touches `broker.nodeID` + `broker.call`, so a
+ * minimal stand-in is enough — this avoids spinning a real `ServiceBroker`
+ * just to assert the pre-connect buffer behaviour.
+ */
+declare function __createRemoteLoggerForTests(broker: BrokerLike, addonId: string): IScopedLogger;
+export { __createRemoteLoggerForTests };
+export { setHubConnected };

package/dist/kernel/moleculer/resilient-cap-call.d.ts

@@ -0,0 +1,28 @@
+/**
+ * D3 — resilient cross-process capability call.
+ *
+ * The `$hub.registerNode` handshake registers a cap proxy the moment the
+ * RPC lands — decoupled from Moleculer's service-discovery INFO packet,
+ * which propagates separately. A call through the proxy in that window
+ * fails with `ServiceNotFoundError`. This wraps a `broker.call` so that,
+ * on a discovery error, it waits for Moleculer to discover the service
+ * (the framework-native `waitForServices` primitive) and retries ONCE.
+ * Happy path (service already discovered) pays nothing. If the service
+ * genuinely never appears, `waitForServices` rejects → fail-fast.
+ */
+/** Minimal broker surface this helper needs. */
+export interface ServiceDiscoveryBroker {
+    call(action: string, params: unknown, opts: {
+        nodeID?: string;
+        timeout?: number;
+    }): Promise<unknown>;
+    waitForServices(services: string[], timeout?: number): Promise<unknown>;
+}
+/**
+ * Call a Moleculer action; on a service-discovery error, wait for the
+ * named service to be discovered and retry the call exactly once.
+ */
+export declare function callWithServiceDiscovery(broker: ServiceDiscoveryBroker, serviceName: string, action: string, params: unknown, opts: {
+    nodeID?: string;
+    timeout?: number;
+}, discoveryTimeoutMs?: number): Promise<unknown>;

package/dist/kernel/moleculer/stream-probe-service.d.ts

@@ -0,0 +1,9 @@
+import { ServiceSchema } from 'moleculer';
+import { IKernelStreamProbe } from '@camstack/types';
+/**
+ * Hub-side dependencies for the `$stream-probe` broker service.
+ * Matches `IKernelStreamProbe` exactly so the same function references
+ * are reused for hub-direct injection and worker broker routing.
+ */
+export type StreamProbeBrokerDeps = IKernelStreamProbe;
+export declare function createStreamProbeBrokerService(deps: StreamProbeBrokerDeps): ServiceSchema;

package/dist/kernel/moleculer/trpc-links.d.ts

@@ -0,0 +1,189 @@
+import { ServiceBroker } from 'moleculer';
+import { TRPCLink } from '@trpc/client';
+import { AnyRouter } from '@trpc/server';
+import { LocalChildRegistry, CapCallInput } from '../transport/index.js';
+/**
+ * Resolver for in-process capability providers.
+ *
+ * The localProviderLink calls this on every operation to check whether
+ * a provider exists in the local process. Implementations differ:
+ *   - Worker: reads from `localProviderRegistry` + `preferredProviderRegistry`
+ *   - Hub: reads from `CapabilityRegistry`
+ */
+/**
+ * Shared interface — also re-exported by `broker-api-proxy.ts`.
+ * Single method is sufficient: the link only needs to resolve the
+ * first matching provider. Singleton vs collection distinction is
+ * a registry concern, not a transport concern.
+ */
+export interface LocalProviderResolver {
+    /** First matching provider (active singleton or first collection member). */
+    getByName(capabilityName: string): unknown | null;
+}
+/**
+ * A single tRPC cap call observation. Recorded by `localProviderLink`
+ * / `brokerTransportLink` on every op, regardless of in-process vs
+ * cluster-bound routing, and fed to the hub's `CapUsageRegistry`.
+ *
+ * Observation is best-effort — observers MUST NOT throw. The link
+ * wraps the recorder in a try/catch so a broken observer never fails
+ * the caller's RPC.
+ */
+export interface CapUsageObservation {
+    readonly callerAddonId: string;
+    readonly providerAddonId: string;
+    readonly capName: string;
+    readonly methodName: string;
+    readonly atMs: number;
+}
+export type CapUsageObserver = (obs: CapUsageObservation) => void;
+export interface CapUsageObserverOptions {
+    /** The addon whose `ctx.api` produced this link chain. */
+    readonly callerAddonId: string;
+    /** Resolve which addon hosts the provider for `capName`. Return `null` to skip recording. */
+    readonly providerAddonIdForCap: (capName: string) => string | null;
+    /** Sink for observations. MUST NOT throw — wrapper catches anyway. */
+    readonly observer: CapUsageObserver;
+}
+/**
+ * Non-terminating tRPC link that intercepts calls when the target
+ * capability has a provider registered in the local process.
+ *
+ * When a local provider is found and implements the requested method,
+ * the call is made directly (zero serialization). When no local
+ * provider exists, the call passes through to `next(op)`.
+ *
+ * This is the mechanism that makes `ctx.api.streamBroker.getBrokerStats.query()`
+ * resolve in-process on the hub without going through Moleculer, and
+ * makes `ctx.api.pipelineExecutor.runPipeline.mutate()` resolve locally
+ * on a forked worker that has a co-located pipeline-executor.
+ */
+export declare function localProviderLink<TRouter extends AnyRouter>(resolver: LocalProviderResolver, observerOpts?: CapUsageObserverOptions): TRPCLink<TRouter>;
+/**
+ * Hard deadline for service discovery on a load-balanced cap call.
+ *
+ * Before this constant existed, `awaitServiceCandidates` polled forever
+ * if a service never (re-)appeared — every consumer of a wedged cap then
+ * hung indefinitely (observed live as `[brokerTransportLink] still
+ * awaiting … after 200s+` in dev logs, cascading through every chain
+ * that touched the affected cap). With the deadline in place, a missing
+ * provider surfaces as a Moleculer "service not found" rejection at the
+ * caller site after at most ~30s — within the cold-boot / respawn
+ * window for any well-behaved addon, while still bounding the failure
+ * mode of a genuinely-stuck cap.
+ *
+ * Callers that legitimately need to wait longer (e.g. boot ordering)
+ * use `ctx.acquireCapability(name, scope, { timeoutMs })` BEFORE issuing
+ * the RPC — see CLAUDE.md's "Do not re-implement Moleculer discovery /
+ * liveness / events" rule. Per-link override is exposed for tests +
+ * tuning via `BrokerTransportLinkOptions.discoveryTimeoutMs`.
+ */
+export declare const DEFAULT_DISCOVERY_TIMEOUT_MS = 30000;
+/**
+ * Options for {@link brokerCallForCap} — the reusable broker-dispatch core
+ * shared by `brokerTransportLink` and the parent-side `onUnownedCall` fallback.
+ */
+export interface BrokerCapCallOpts {
+    /**
+     * Pins the call to a specific Moleculer node. When set, the call uses the
+     * bounded pinned-discovery retry (2s) and surfaces "service not found" fast,
+     * mirroring `brokerTransportLink`'s pinned path. When absent, the call uses
+     * the unbounded load-balanced discovery wait.
+     */
+    readonly nodeId?: string;
+    /** Static service-name override for the cap (matches `brokerTransportLink`'s serviceMap entry). */
+    readonly forceServiceName?: string;
+    /**
+     * Abort flag — set `aborted = true` to tear down a pending discovery wait.
+     * Defaults to a never-aborted flag when omitted.
+     */
+    readonly abort?: {
+        aborted: boolean;
+    };
+}
+/**
+ * Resolve and dispatch a cap method call over a Moleculer broker.
+ *
+ * Routing (service discovery + node resolution + `capActionName`) is delegated
+ * to the shared {@link resolveBrokerCapCall} core — the SAME core
+ * `brokerTransportLink` uses — so the two can never drift. This function is the
+ * thin "resolve then `broker.call`" wrapper.
+ *
+ * What this function IS used for:
+ *   The hub / agent parent-side `onUnownedCall` fallback (F0 — when a forked
+ *   child calls a cap no local sibling owns and the resolver returns `no-provider`,
+ *   e.g. the hub's `$core-caps` / `$stream-probe` core services, which are
+ *   Moleculer services NOT registered as CapabilityRegistry providers).
+ *
+ * A genuinely-absent service surfaces the broker's "service not found" error
+ * (bounded for pinned calls) rather than hanging.
+ */
+export declare function brokerCallForCap(broker: ServiceBroker, capName: string, method: string, args: unknown, opts?: BrokerCapCallOpts): Promise<unknown>;
+/**
+ * Tunables for {@link brokerTransportLink}.
+ *
+ * `discoveryTimeoutMs` bounds the load-balanced service-discovery wait
+ * inside `awaitServiceCandidates`. Default {@link DEFAULT_DISCOVERY_TIMEOUT_MS}.
+ * Overriding is for tests + tuning — production callers that need a
+ * different deadline should use `ctx.acquireCapability` instead, since
+ * that's the documented liveness mechanism (CLAUDE.md).
+ */
+export interface BrokerTransportLinkOptions {
+    readonly discoveryTimeoutMs?: number;
+}
+export declare function brokerTransportLink<TRouter extends AnyRouter>(broker: ServiceBroker, serviceMap?: Readonly<Record<string, string>>, observerOpts?: CapUsageObserverOptions, linkOptions?: BrokerTransportLinkOptions): TRPCLink<TRouter>;
+/**
+ * Middle link that routes a cap op to a LOCAL addon-runner over UDS via the
+ * `LocalChildRegistry`. If no local child owns `(capName, deviceId?)`, the op
+ * passes through to `next(op)` (e.g. `brokerTransportLink` for remote agents),
+ * so this link is transparent for everything it does not own.
+ *
+ * `deviceId` for device-scoped caps is read from `op.input` (the same place
+ * the codegen'd device-scoped routers carry it); the full `op.input` is
+ * forwarded as the child method's argument.
+ */
+export declare function ipcChildLink<TRouter extends AnyRouter>(registry: LocalChildRegistry): TRPCLink<TRouter>;
+/**
+ * Middle link that routes a child addon's outbound `ctx.api` cap call to the
+ * parent hub over UDS via `callOut` (obtained at call-time so the child can
+ * reconnect without rebuilding its tRPC client).
+ *
+ * Delegation rules:
+ *  - `getCallOut()` returns `null`  → not connected, delegate via `next(op)`.
+ *  - `parsePath(op.path)` returns `null` → unparseable path, delegate via `next(op)`.
+ *  - `callOut` rejects with a no-route error (message starts with `UDS_NO_ROUTE_PREFIX`)
+ *    → the parent could not route the call (no local sibling, no cluster fallback);
+ *    delegate via `next(op)` (broker fallback) — safe because no provider ran.
+ *  - `callOut` rejects with any other error → real provider error; propagate to
+ *    the caller via `observer.error` — NEVER retry via broker to avoid
+ *    double-executing side effects.
+ */
+export declare function ipcParentLink<TRouter extends AnyRouter>(getCallOut: () => ((input: CapCallInput) => Promise<unknown>) | null): TRPCLink<TRouter>;
+export type LinkChainTarget = {
+    type: 'local-router';
+    terminatingLink: TRPCLink<AnyRouter>;
+} | {
+    type: 'ws';
+    terminatingLink: TRPCLink<AnyRouter>;
+} | {
+    type: 'broker';
+    broker: ServiceBroker;
+    serviceMap?: Readonly<Record<string, string>>;
+};
+/**
+ * Optional observer hookup for `buildLinkChain` — threads the same
+ * `CapUsageObserverOptions` through `localProviderLink` and
+ * `brokerTransportLink` so every op is recorded once regardless of
+ * whether it resolved locally or over the broker.
+ */
+export interface LinkChainObserverHookup {
+    readonly observerOpts?: CapUsageObserverOptions;
+}
+/**
+ * Build the tRPC link chain for an addon context.
+ *
+ * Always starts with `localProviderLink` (if a resolver is provided),
+ * then falls through to the appropriate terminating link based on the
+ * deployment context.
+ */
+export declare function buildLinkChain(target: LinkChainTarget, localResolver?: LocalProviderResolver, hookup?: LinkChainObserverHookup): TRPCLink<AnyRouter>[];

package/dist/kernel/moleculer/typed-array-serde.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Serialize/deserialize non-Buffer TypedArrays for Moleculer MsgPack transport.
+ *
+ * MsgPack handles Buffer natively but serializes Float32Array, Int16Array etc.
+ * as plain objects with numeric keys. These helpers convert them to Buffer
+ * with a type tag for transport and reconstruct them on arrival.
+ *
+ * Used by:
+ * - capability-bridge.ts (hub → child proxy calls)
+ * - addon-service-factory.ts (child → provider param reconstruction)
+ */
+/**
+ * Convert non-Buffer TypedArrays → `{ __typedArray, type, data: Buffer }` recursively.
+ *
+ * A WeakSet tracks objects already visited on the current descent path so a
+ * cyclic input throws a precise error at the offending path instead of
+ * blowing the stack with "Maximum call stack size exceeded". tRPC inputs
+ * should never be cyclic in practice — this is a safety net for regressions
+ * that accidentally introduce shared-reference loops (e.g. a config object
+ * that holds a back-pointer into its own container).
+ */
+declare function serializeTypedArrays(value: unknown, seen?: WeakSet<object>, path?: string): unknown;
+/** Reconstruct TypedArrays from tagged objects. */
+declare function deserializeTypedArrays(value: unknown): unknown;
+export { serializeTypedArrays, deserializeTypedArrays };

package/dist/kernel/moleculer/worker-device-restore.d.ts

@@ -0,0 +1,10 @@
+import { ICamstackAddon, IEventBus, IScopedLogger } from '@camstack/types';
+export declare function runWorkerDeviceRestoreWithRetry(addon: ICamstackAddon, context: {
+    api?: unknown;
+    eventBus?: IEventBus;
+    logger?: IScopedLogger | {
+        info?: (m: string) => void;
+        warn?: (m: string) => void;
+        debug?: (m: string) => void;
+    };
+}, addonId: string, sourceNodeId: string): Promise<void>;

package/dist/kernel/provider-kind-drift.d.ts

@@ -0,0 +1,12 @@
+import { CapabilityDefinition } from '@camstack/types';
+/** The deprecated runtime metadata hint carried on a `ProviderRegistration`. */
+export type ProviderKindHint = {
+    readonly kind?: 'native' | 'wrapper';
+    readonly defaultActive?: boolean;
+};
+/**
+ * Compare a runtime registration hint against the authoritative cap
+ * definition. Returns a human-readable warning string when they disagree,
+ * or `null` when the hint is absent or consistent.
+ */
+export declare function describeProviderKindDrift(capName: string, capDef: Pick<CapabilityDefinition, 'kind' | 'defaultActive'>, hint: ProviderKindHint): string | null;

package/dist/kernel/restart-coordinator.d.ts

@@ -0,0 +1,90 @@
+/**
+ * RestartCoordinator — shared primitives for the framework live-update flow.
+ *
+ * Spec: docs/superpowers/specs/2026-05-14-framework-live-update-design.md (P2)
+ *
+ * Three responsibilities:
+ *   1) Marker schema + read/write/clear on `<dataDir>/.restart-pending`.
+ *   2) Boot-side handoff: `readPendingRestart()` returns the payload exactly
+ *      once and atomically clears the marker so a crashed second boot
+ *      doesn't re-fire the completion event.
+ *   3) Environment-agnostic `scheduleSelfRestart()` — Electron calls
+ *      `app.relaunch()`+`app.exit(0)`, everything else `process.exit(0)`.
+ *
+ * The cap method that writes the marker lives in the addons cap (P3); this
+ * module is the zero-dep primitive both the cap (writer) and PostBootService
+ * (reader) call into.
+ */
+/** Filename of the restart marker, written under `<dataDir>`. */
+export declare const RESTART_MARKER_FILE = ".restart-pending";
+/** Discriminated union of reasons the hub can be asked to restart. */
+export type RestartKind = 'framework-update' | 'framework-bulk-update' | 'manual' | 'system';
+/**
+ * On-disk shape. All fields stable + load-bearing for the completion event.
+ * Future kinds add new optional fields; existing readers ignore them.
+ */
+export interface PendingRestartMarker {
+    readonly kind: RestartKind;
+    readonly packageName?: string;
+    readonly fromVersion?: string;
+    readonly toVersion?: string;
+    readonly requestedBy?: string;
+    readonly requestedAt: number;
+}
+/** Resolve the marker path inside a data directory. */
+export declare function getRestartMarkerPath(dataDir: string): string;
+/**
+ * Write the marker atomically. Existing marker is overwritten — the most
+ * recent restart request wins.
+ *
+ * Uses write-then-rename so a crash mid-write leaves either the old marker
+ * intact or no marker at all (never a half-written file).
+ */
+export declare function writePendingRestart(dataDir: string, marker: PendingRestartMarker): void;
+/**
+ * Read + consume the marker. Returns the parsed payload on success and
+ * clears the file in the same tick (rename → unlink), so a crash between
+ * read and emit won't replay the completion event on the next boot.
+ *
+ * Failure modes:
+ *   - no marker present     → returns null
+ *   - file unreadable / IO  → logs to console, returns null, leaves marker
+ *   - JSON malformed        → logs, clears the marker, returns null
+ *   - missing required `kind` / `requestedAt` → logs, clears, returns null
+ *
+ * "Clear on parse failure" is intentional: a stuck unparseable marker would
+ * otherwise block every subsequent restart's completion event.
+ *
+ * NOTE: the `console.error` calls below are deliberate, documented
+ * residuals. This is a stateless bootstrap utility invoked during hub
+ * startup before `LogManager` / the Moleculer broker exist — there is no
+ * `IScopedLogger` or `$hub.log` transport in scope. Threading a logger
+ * parameter through every caller is out of scope for the D8 log-forwarding
+ * work (which only touches `packages/kernel/src`).
+ */
+export declare function readPendingRestart(dataDir: string): PendingRestartMarker | null;
+/** Remove the marker if present. No-op if missing. */
+export declare function clearPendingRestart(dataDir: string): void;
+/**
+ * Schedule a self-restart appropriate for the runtime:
+ *   - Electron: `app.relaunch()` then `app.exit(0)` — the bundle handles the spawn.
+ *   - Docker / standalone Node: `process.exit(0)` — the supervisor (compose
+ *     `restart: unless-stopped`, systemd, pm2, …) brings the process back up.
+ *
+ * Caller is expected to have:
+ *   1) Written the marker via `writePendingRestart`.
+ *   2) Returned the cap-method response to the caller (so the WS doesn't
+ *      drop mid-reply).
+ *   3) Closed the Fastify instance gracefully (`await fastify.close()`).
+ *
+ * The 500ms delay is the same beat used by P3's cap method — kept here as a
+ * default so non-cap callers (signal handlers, future flows) share the same
+ * shutdown pacing.
+ */
+export interface ScheduleSelfRestartOptions {
+    /** Delay before exit (ms). Default 500 — gives in-flight RPC time to drain. */
+    readonly delayMs?: number;
+    /** Override exit code. Default 0 (clean exit → supervisor restart). */
+    readonly exitCode?: number;
+}
+export declare function scheduleSelfRestart(options?: ScheduleSelfRestartOptions): void;