@camstack/system 1.0.2

package/dist/kernel/storage-location-registry.d.ts

@@ -0,0 +1,40 @@
+import { StorageLocationDeclaration } from '@camstack/types';
+/**
+ * Read-only view over all aggregated storage-location declarations.
+ *
+ * Built at kernel boot by {@link buildStorageLocationRegistry} from the
+ * `storageLocations` arrays declared in each installed addon's manifest.
+ */
+export interface StorageLocationRegistry {
+    /** Returns the declaration for `id`, or `undefined` if not declared. */
+    get(id: string): StorageLocationDeclaration | undefined;
+    /** Returns `true` when at least one addon declared `id`. */
+    has(id: string): boolean;
+    /**
+     * Returns the cardinality of `id`, or `null` when no addon declared it.
+     * Convenience shortcut over `get(id)?.cardinality`.
+     */
+    cardinalityOf(id: string): 'single' | 'multi' | null;
+    /**
+     * Stable, immutable list of all aggregated declarations (insertion order of
+     * first occurrence per `id`).
+     */
+    list(): readonly StorageLocationDeclaration[];
+}
+/**
+ * Aggregates per-addon {@link StorageLocationDeclaration} arrays into a single
+ * {@link StorageLocationRegistry}.
+ *
+ * Merge rules:
+ * - Declarations are keyed by `id`; iteration order follows first occurrence.
+ * - **First declarer wins** for metadata (`displayName`, `description`,
+ *   `defaultsTo`): if a later addon declares the same `id`, its metadata is
+ *   silently ignored.
+ * - **Cardinality conflict throws**: if two addons declare the same `id` with
+ *   different `cardinality` values an `Error` is thrown immediately (message
+ *   contains the words "cardinality" and the conflicting `id`).
+ *
+ * @param perAddon - One entry per addon; each entry is that addon's
+ *   `storageLocations` declaration array.
+ */
+export declare function buildStorageLocationRegistry(perAddon: readonly (readonly StorageLocationDeclaration[])[]): StorageLocationRegistry;

package/dist/kernel/transport/cap-action-name.d.ts

@@ -0,0 +1,100 @@
+/**
+ * cap-action-name.ts — single source of truth for Moleculer cap
+ * action/service naming conventions.
+ *
+ * Moleculer service / action naming rules
+ * ─────────────────────────────────────────────────────────────────────────────
+ * System (manifest) cap:
+ *   service  : `${addonId}.${capName}`             (service `name` field)
+ *   action   : `${capName}.${method}`              (registered INSIDE the service)
+ *   full key : `${addonId}.${capName}.${method}`   (broker.call key)
+ *
+ * Native (device-scoped) cap:
+ *   service  : `${addonId}${NATIVE_PROVIDER_SERVICE_INFIX}.${capName}`
+ *   action   : `${method}`                         (registered INSIDE the service)
+ *              also aliased as `${capName}.${method}` for bridge discovery
+ *   full key : `${addonId}${NATIVE_PROVIDER_SERVICE_INFIX}.${capName}.${method}`
+ *
+ * Registry-scan helpers:
+ *   suffix   : `.${capName}.${method}`  — trailing match against a full action key
+ *   bare     : `${capName}.${method}`   — the action key as registered by
+ *               addon-service-factory (without the service-name prefix)
+ *
+ * Parse helper:
+ *   parseCapAction(action) → { addonId, capName, method, native }
+ *   Inverse of capActionName / capServiceName + ".${method}".
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * All five construction sites that previously built these strings inline now
+ * import from here instead:
+ *   1. packages/kernel/src/transport/cap-route-resolver.ts (remote dispatch)
+ *   2. packages/kernel/src/moleculer/trpc-links.ts (findServiceCandidates + brokerTransportLink)
+ *   3. packages/kernel/src/moleculer/addon-service-factory.ts (service action registration)
+ *   4. packages/kernel/src/moleculer/device-cap-proxy.ts (native service/proxy)
+ *   5. server/backend/src/core/moleculer/moleculer.service.ts (legacy callFn fallback)
+ */
+/**
+ * Infix segment that separates the addonId from the capName in the Moleculer
+ * service name for device-scoped NATIVE capability providers.
+ *
+ * Native service name  : `${addonId}${NATIVE_PROVIDER_SERVICE_INFIX}.${capName}`
+ * System service name  : `${addonId}.${capName}`  (no infix)
+ */
+export declare const NATIVE_PROVIDER_SERVICE_INFIX: ".native-provider";
+/**
+ * Build the Moleculer SERVICE name for a cap provider.
+ *
+ * System cap : `${addonId}.${capName}`
+ * Native cap : `${addonId}${NATIVE_PROVIDER_SERVICE_INFIX}.${capName}`
+ */
+export declare function capServiceName(addonId: string, capName: string, native: boolean): string;
+/**
+ * Build the full Moleculer ACTION key (broker.call key) for a cap method.
+ *
+ * System cap : `${addonId}.${capName}.${method}`
+ * Native cap : `${addonId}${NATIVE_PROVIDER_SERVICE_INFIX}.${capName}.${method}`
+ */
+export declare function capActionName(addonId: string, capName: string, method: string, native: boolean): string;
+/**
+ * Build the trailing SUFFIX used to scan the Moleculer service registry for
+ * any service that exposes a given (capName, method) pair.
+ *
+ * The suffix `.${capName}.${method}` is compared against full action keys via
+ * `action.endsWith(suffix)` in `findServiceCandidates` (trpc-links.ts).
+ */
+export declare function capActionSuffix(capName: string, method: string): string;
+/**
+ * Build the BARE action name — the key under which addon-service-factory
+ * registers the action WITHIN a service (i.e. without the addonId prefix).
+ *
+ * The full broker key is `${addonId}.${bareAction}` for system caps, but the
+ * registry scan checks for `bareAction` directly (`a === bareAction`) to catch
+ * the case where the service name itself IS the capName (e.g. stream-broker
+ * registering `camera-streams.getRtspEntries`).
+ */
+export declare function capBareAction(capName: string, method: string): string;
+/** Result of parsing a full Moleculer action key. */
+export interface ParsedCapAction {
+    readonly addonId: string;
+    readonly capName: string;
+    readonly method: string;
+    readonly native: boolean;
+}
+/**
+ * Parse a full Moleculer action key back into its constituent parts.
+ *
+ * Handles both forms:
+ *   system : `${addonId}.${capName}.${method}`
+ *            (splits on first and last dot; 3 segments minimum)
+ *   native : `${addonId}${NATIVE_PROVIDER_SERVICE_INFIX}.${capName}.${method}`
+ *            (NATIVE_PROVIDER_SERVICE_INFIX = `.native-provider`, so the raw
+ *             action has the form `${addonId}.native-provider.${capName}.${method}`)
+ *
+ * Returns `null` when the action string cannot be parsed into at least 3
+ * dot-separated segments.
+ *
+ * **Parse semantics** — exact inverse of `capActionName`:
+ *   capActionName(a, c, m, native)  →  action
+ *   parseCapAction(action)          →  { addonId: a, capName: c, method: m, native }
+ */
+export declare function parseCapAction(action: string): ParsedCapAction | null;

package/dist/kernel/transport/cap-route-resolver.d.ts

@@ -0,0 +1,148 @@
+import { CapCallInput } from './child-cap-protocol.js';
+import { ServiceDiscoveryBroker } from '../moleculer/resilient-cap-call.js';
+import { CapRoute, CapRouteOpts, HubLocalUdsRoute, InProcessProviderRef } from './cap-route.js';
+/**
+ * Minimal surface of LocalChildRegistry that the resolver needs.
+ * Keeping a narrow interface here prevents the resolver from depending on the
+ * full LocalChildRegistry class and avoids `as unknown as` casts in tests.
+ * The real `LocalChildRegistry` structurally satisfies this interface.
+ */
+export interface HubLocalChildDispatcher {
+    /** Returns the childId that provides the cap, or null. */
+    resolveChildId(capName: string, deviceId?: number): string | null;
+    /** Forwards a cap call to a specific child by id. */
+    callCapOnChild(childId: string, input: CapCallInput): Promise<unknown>;
+}
+/**
+ * Minimal view of the cluster node registry needed to build a CapRouteSnapshot.
+ * The concrete implementation (HubNodeRegistry) lives in server/backend and is
+ * wired in by Task 4/5. Keeping this interface in kernel prevents a layering
+ * inversion.
+ */
+export interface NodeCapAuthority {
+    /** Returns true if the given node's latest manifest includes the given cap. */
+    nodeKnowsCap(nodeId: string, capName: string): boolean;
+    /** Returns true if the given nodeId is an agent (bare id, no '/' separator). */
+    nodeIsAgent(nodeId: string): boolean;
+    /** Returns true if the given node is currently connected/online. */
+    nodeOnline(nodeId: string): boolean;
+    /** Returns all nodeIds currently in the registry. */
+    listNodeIds(): readonly string[];
+    /**
+     * Returns the addonId for the provider that registered (nodeId, capName).
+     * Used to build the Moleculer action `${addonId}.${capName}.${method}`.
+     * Returns null when the node does not host the cap (should not happen if
+     * nodeKnowsCap is true, but guard defensively).
+     */
+    getAddonId(nodeId: string, capName: string): string | null;
+    /**
+     * Returns the childId (runner id) of the agent's UDS child that provides
+     * the given cap. Only meaningful when nodeIsAgent(nodeId) is true.
+     * Returns null when unknown.
+     */
+    getAgentChildId(agentNodeId: string, capName: string): string | null;
+    /**
+     * Returns true if the (nodeId, capName, deviceId?) tuple is a device-scoped
+     * NATIVE cap (vs. a system/manifest cap). When true, the remote-moleculer
+     * dispatcher uses `capActionName(addonId, cap, method, true)` which expands to
+     * `${addonId}.native-provider.${cap}.${method}` instead of the plain system-cap
+     * action `${addonId}.${cap}.${method}`.
+     * Implementations that do not track native caps should return false.
+     */
+    isNativeCap(nodeId: string, capName: string, deviceId?: number): boolean;
+}
+/**
+ * Injected lookup for providers that live in the hub host process.
+ * Returns a ready-to-invoke InProcessProviderRef, or null if the cap is not
+ * hosted in-process.
+ */
+export type InProcessProviderLookup = (capName: string) => InProcessProviderRef | null;
+export interface CapRouteResolverDeps {
+    /** The hub's own Moleculer nodeId (e.g. `'hub'`). */
+    readonly hubNodeId: string;
+    /**
+     * Minimal Moleculer broker surface: `call` + `waitForServices`.
+     * Used for remote-moleculer and agent-child-forward dispatches.
+     */
+    readonly broker: ServiceDiscoveryBroker;
+    /**
+     * Local UDS child dispatcher — routes hub-local-uds dispatches.
+     * May be null when the UDS server failed to start.
+     */
+    readonly hubLocalRegistry: HubLocalChildDispatcher | null;
+    /**
+     * Authority over which nodes are online and which caps they know.
+     * Decouples the resolver from the concrete HubNodeRegistry class.
+     */
+    readonly nodeAuthority: NodeCapAuthority;
+    /**
+     * Lookup for hub-in-process providers.
+     * Decouples the resolver from CapabilityRegistry.
+     */
+    readonly inProcessProviders: InProcessProviderLookup;
+}
+/**
+ * Params envelope sent to the agent's `$agent-cap-fwd.forward` Moleculer action.
+ *
+ * Task 6 MUST register a Moleculer service named `$agent-cap-fwd` with an
+ * action `forward` that receives this payload, resolves `childId` in its own
+ * LocalChildRegistry, and dispatches over UDS to that child.
+ */
+export interface AgentCapForwardParams {
+    readonly capName: string;
+    readonly method: string;
+    readonly args: unknown;
+    /**
+     * Optional: the hub cannot resolve which forked child under the agent provides the cap.
+     * The agent resolves its own child locally (Task 6). Present when the hub authority
+     * happens to know it, absent (undefined) when not.
+     */
+    readonly childId?: string;
+    readonly deviceId?: number;
+}
+/** The Moleculer service name that Task 6's agent registers. */
+export declare const AGENT_CAP_FWD_SERVICE: "$agent-cap-fwd";
+/** The Moleculer action (service.action) for agent cap forwarding. */
+export declare const AGENT_CAP_FWD_ACTION: "$agent-cap-fwd.forward";
+export declare function extractDeviceId(args: unknown): number | undefined;
+export declare class CapRouteResolver {
+    private readonly hubNodeId;
+    private readonly broker;
+    private readonly hubLocalRegistry;
+    private readonly nodeAuthority;
+    private readonly inProcessProviders;
+    private readonly snapshot;
+    constructor(deps: CapRouteResolverDeps);
+    resolveCapRoute(capName: string, opts: CapRouteOpts): CapRoute;
+    /**
+     * Resolve the hub-local-uds route for a cap owned by a forked hub-local
+     * child, IGNORING any in-hub provider registered for the same cap name.
+     *
+     * `resolveCapRoute` gives Priority 1 to `hub-in-process`: when an in-hub
+     * provider (e.g. a wrapper) is registered for the cap, the route always
+     * classifies as `hub-in-process` and the hub-local-uds NATIVE child is never
+     * reached. That is correct for the generic dispatch path (the wrapper is the
+     * active provider), but WRONG for the native-cap fallback
+     * (`setNativeFallback`), whose contract is to reach the NATIVE provider in
+     * the forked vendor child so a wrapper can delegate to it. A wrapper cap
+     * with a forked native (today: `snapshot`) otherwise resolves to the wrapper
+     * itself, the native is never invoked, and the wrapper silently falls
+     * through to its secondary strategy.
+     *
+     * This method consults ONLY the hub-local-child authority
+     * (`hubLocalChildProvides` + `getHubLocalChildId`, both deviceId-aware), so
+     * it returns the native child route regardless of any in-process shadow.
+     * Returns null when no hub-local child owns `(capName, deviceId)` — the
+     * caller then falls through to its remote-resolution branch.
+     */
+    resolveHubLocalUdsRoute(capName: string, deviceId?: number): HubLocalUdsRoute | null;
+    dispatch(route: CapRoute, method: string, args: unknown): Promise<unknown>;
+    /**
+     * Inner dispatch: may throw CapRouteError (validation failures) or arbitrary
+     * transport errors. The outer `dispatch` wraps non-CapRouteErrors.
+     */
+    private dispatchInner;
+    private buildSnapshot;
+    /** Extract a nodeId string from a route for error reporting, or undefined. */
+    private routeNodeId;
+}

package/dist/kernel/transport/cap-route.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Discriminated union describing HOW a capName call should be dispatched.
+ * Every variant carries `capName` so a resolved route is a self-contained
+ * dispatch descriptor.  `method` is a dispatch-time concern supplied separately
+ * to the dispatcher — it does not belong on the route.
+ *
+ * This file is intentionally import-free — no broker/registry deps — so it can
+ * be imported from both the hub and agent without pulling the full kernel graph.
+ */
+export interface CapRouteBase {
+    readonly capName: string;
+}
+/**
+ * A typed thunk that invokes a method on a provider that lives in the current
+ * process. Using an invoker thunk instead of a raw `object` avoids `as`-casts
+ * at every dispatch site: the resolver builds the thunk once (knowing the
+ * provider's concrete type), and every consumer calls `ref.invoke(method, args)`
+ * without any type assertion.
+ */
+export type CapInvoker = (method: string, args: unknown) => Promise<unknown>;
+export interface InProcessProviderRef {
+    readonly invoke: CapInvoker;
+}
+export interface HubInProcessRoute extends CapRouteBase {
+    readonly kind: 'hub-in-process';
+    readonly ref: InProcessProviderRef;
+}
+export interface HubLocalUdsRoute extends CapRouteBase {
+    readonly kind: 'hub-local-uds';
+    readonly childId: string;
+}
+export interface RemoteMoleculerRoute extends CapRouteBase {
+    readonly kind: 'remote-moleculer';
+    readonly nodeId: string;
+}
+export interface AgentChildForwardRoute extends CapRouteBase {
+    readonly kind: 'agent-child-forward';
+    readonly agentNodeId: string;
+    /** Optional: the hub cannot resolve which forked child under an agent provides the cap.
+     * The agent resolves its own child locally (Task 6). */
+    readonly childId?: string;
+}
+export type CapRoute = HubInProcessRoute | HubLocalUdsRoute | RemoteMoleculerRoute | AgentChildForwardRoute;
+export type CapRouteReason = 'no-provider' | 'node-offline' | 'cap-unknown' | 'transport-failed';
+export interface RejectedRoute {
+    readonly kind: string;
+    readonly why: string;
+}
+export interface CapRouteErrorDetail {
+    readonly reason: CapRouteReason;
+    readonly nodeId?: string;
+    readonly rejected: readonly RejectedRoute[];
+}
+export declare class CapRouteError extends Error {
+    readonly reason: CapRouteReason;
+    readonly nodeId: string | undefined;
+    readonly rejected: readonly RejectedRoute[];
+    /**
+     * @param cause  Optional original error that triggered this routing failure.
+     *               Stored as `Error.cause` (TC39 standard option, Node 16.9+).
+     *               Dispatchers wrapping transport errors MUST pass the original.
+     */
+    constructor(capName: string, method: string | undefined, detail: CapRouteErrorDetail, cause?: Error);
+}
+/**
+ * A read-only snapshot of the registry state needed to classify a route.
+ * All fields are predicates or accessors — no live broker/registry deps.
+ *
+ * `getInProcessProviderRef` is OPTIONAL: the plan's table-driven test literal
+ * omits it because none of the 4 plan cases hit the hub-in-process branch.
+ * When present, the function calls it; when absent (or returns null), the
+ * hub-in-process branch falls through to a `no-provider` CapRouteError instead
+ * of using an unsafe cast.  This keeps the union type-safe without casts.
+ *
+ * `listKnownNodeIds` is OPTIONAL: used for singleton resolution (no nodeId
+ * given) to find a remote node that knows the cap. When absent, remote
+ * singleton resolution is skipped (no remote-moleculer route for singletons).
+ *
+ * `getHubLocalChildId` is OPTIONAL: resolves the runner childId of the
+ * hub-local child that provides this cap. When absent or returns null, the
+ * hub-local-uds branch falls through to a `no-provider` CapRouteError.
+ *
+ * `getAgentChildId` is OPTIONAL: resolves the runner childId of the agent's
+ * child that provides this cap. When absent or returns null, the
+ * agent-child-forward branch falls through to a `no-provider` CapRouteError.
+ */
+export interface CapRouteSnapshot {
+    /** The nodeId that represents the hub itself in the mesh. */
+    readonly hubNodeId: string;
+    /**
+     * Returns true if a hub-local UDS child process provides this cap.
+     * The optional `deviceId` is a routing hint for device-scoped native caps:
+     * a child that owns only a specific device's cap will match on (capName, deviceId)
+     * while a singleton provider (no deviceId on the descriptor) matches on capName alone.
+     */
+    readonly hubLocalChildProvides: (cap: string, deviceId?: number) => boolean;
+    /** Returns true if the hub host process provides this cap in-process. */
+    readonly hubInProcessProvides: (cap: string) => boolean;
+    /** Returns true if the given node knows (registers) the given cap. */
+    readonly nodeKnowsCap: (nodeId: string, cap: string) => boolean;
+    /** Returns true if the given nodeId is an agent node (not a hub-local child). */
+    readonly nodeIsAgent: (nodeId: string) => boolean;
+    /** Returns true if the given node is currently online/reachable. */
+    readonly nodeOnline: (nodeId: string) => boolean;
+    /**
+     * Optional: resolves a concrete InProcessProviderRef for an in-process cap.
+     * Required to actually produce a HubInProcessRoute.  When absent or returns
+     * null, classifyCapRoute throws no-provider rather than casting.
+     */
+    readonly getInProcessProviderRef?: (cap: string) => InProcessProviderRef | null;
+    /**
+     * Optional: enumerates all known remote nodeIds for singleton cap resolution
+     * (the case where no explicit nodeId is given by the caller).
+     */
+    readonly listKnownNodeIds?: () => readonly string[];
+    /**
+     * Optional: resolves the runner childId of the hub-local child that provides this cap.
+     * The optional `deviceId` is a routing hint for device-scoped native caps (same semantics
+     * as `hubLocalChildProvides`).
+     */
+    readonly getHubLocalChildId?: (cap: string, deviceId?: number) => string | null;
+    /** Optional: resolves the runner childId of the agent's child that provides this cap. */
+    readonly getAgentChildId?: (agentNodeId: string, cap: string) => string | null;
+}
+export interface CapRouteOpts {
+    readonly nodeId?: string;
+    /** Numeric device id — a routing hint for device-scoped native caps. */
+    readonly deviceId?: number;
+}
+/**
+ * Classifies a (capName, opts) pair into a typed CapRoute dispatch descriptor.
+ *
+ * Precedence (explicit nodeId path):
+ *   1. hub-in-process — hub node + hubInProcessProvides
+ *   2. hub-local-uds  — hub node + hubLocalChildProvides
+ *   3. node-offline   → CapRouteError{reason:'node-offline'}
+ *   4. agent-child-forward — node is an agent AND nodeKnowsCap
+ *   5. remote-moleculer — any other online non-agent node
+ *
+ * Singleton path (no nodeId):
+ *   1. hub-in-process (hub provides in-process)
+ *   2. hub-local-uds  (a hub-local UDS child provides it)
+ *   3. remote-moleculer (any online, non-hub node that knows it)
+ *   4. → CapRouteError{reason:'no-provider', rejected: all considered routes}
+ *
+ * PURE: no side effects, no async, no broker/registry imports.
+ */
+export declare function classifyCapRoute(capName: string, opts: CapRouteOpts, snapshot: CapRouteSnapshot): CapRoute;

package/dist/kernel/transport/child-cap-protocol.d.ts

@@ -0,0 +1,136 @@
+import { SystemEvent, IReadinessRegistryRecord, LogLevel, LogTags } from '@camstack/types';
+/**
+ * Routing descriptor a child sends so the parent can route cap calls to it.
+ * The provider implementation never crosses the wire — only these keys do.
+ */
+export interface ChildCapDescriptor {
+    readonly capName: string;
+    /** Cap mode. Carried for the future cluster-exposure layer (agent-as-proxy); the local registry routes only on capName + deviceId. */
+    readonly mode: 'singleton' | 'collection';
+    /** Present for device-scoped caps; absent for singleton/system caps. */
+    readonly deviceId?: number;
+}
+/** First message a child sends after connecting — its complete cap manifest. */
+export interface RegisterMessage {
+    readonly kind: 'register';
+    readonly childId: string;
+    readonly caps: readonly ChildCapDescriptor[];
+}
+/** Child → parent outbound cap invocation — the child asks the parent to route a cap call it does not own. */
+export interface CapCallOutMessage {
+    readonly kind: 'cap-call-out';
+    readonly capName: string;
+    readonly method: string;
+    readonly args: unknown;
+    readonly deviceId?: number;
+}
+/** Child → parent: a system event produced by the child to be forwarded to the hub event bus. */
+export interface ChildEventMessage {
+    readonly kind: 'event';
+    readonly event: SystemEvent;
+}
+/** Child → parent: a structured log entry emitted by the child process. */
+export interface ChildLogMessage {
+    readonly kind: 'log';
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly addonId: string;
+    readonly nodeId?: string;
+    readonly scope?: string;
+    readonly tags?: LogTags;
+    readonly meta?: Record<string, unknown>;
+}
+/** Child → parent: request for the current readiness snapshot (all known records). */
+export interface ReadinessSnapshotRequest {
+    readonly kind: 'readiness-request';
+}
+/**
+ * Child → parent message bodies.
+ * `RegisterMessage`, `CapCallOutMessage`, and `ReadinessSnapshotRequest` travel
+ * as correlated request frames (`channel.request`) and carry a response.
+ * `ChildEventMessage` and `ChildLogMessage` are sent fire-and-forget via
+ * `channel.emit()` and do NOT carry a response.
+ */
+export type ChildToParentRequest = RegisterMessage | CapCallOutMessage | ChildEventMessage | ChildLogMessage | ReadinessSnapshotRequest;
+/** Parent → child cap invocation. */
+export interface CapCallMessage {
+    readonly kind: 'cap-call';
+    readonly capName: string;
+    readonly method: string;
+    readonly args: unknown;
+    readonly deviceId?: number;
+}
+/** Parent → child: a system event delivered by the hub for the child to handle locally. */
+export interface ParentEventMessage {
+    readonly kind: 'event';
+    readonly event: SystemEvent;
+    /** Moleculer node ID of the hub or agent that forwarded this event. */
+    readonly sourceNodeId: string;
+}
+/** Parent → child: authoritative readiness snapshot in response to a `readiness-request`. */
+export interface ReadinessSnapshotResponse {
+    readonly kind: 'readiness-snapshot';
+    readonly records: readonly IReadinessRegistryRecord[];
+}
+/**
+ * The exhaustive set of ADDON-LEVEL surfaces carried over the UDS addon-call
+ * plane — i.e. everything the removed per-addon Moleculer broker used to carry
+ * besides cap methods. THIS UNION IS THE SINGLE SOURCE OF TRUTH: every such
+ * surface MUST appear here AND be handled by `createChildAddonCallDispatch`'s
+ * exhaustive switch (a `never` check fails the build if one is added here but
+ * not dispatched, or hub-side routing is added without a target). Routes +
+ * custom-actions were ported in the UDS migration; `settings` was MISSED for
+ * months because it lived on a separate Moleculer path — adding it here makes
+ * that class of "missed link" a compile error from now on.
+ *
+ * `AddonCallTarget` values:
+ *   - `routes`   → the addon's `addon-routes` provider `getRoutes()` (handlers
+ *     STRIPPED — MsgPack can't encode functions; the hub re-binds via `invoke`).
+ *   - `custom`   → the addon's custom-action handler (`action` + `args`).
+ *   - `settings` → the addon's global/device settings methods (`method` names
+ *     the entry; `args` carries the params). Mirrors the removed
+ *     `<addonId>.settings.<method>` Moleculer action.
+ *   - `data-planes` → the addon's live HTTP data-plane endpoints
+ *     (`{prefix, access, baseUrl, secret}[]`), pulled when the hub mounts the
+ *     addon so it can set up its reverse-proxy. Mirrors `routes`.
+ */
+export type AddonCallTarget = 'routes' | 'custom' | 'settings' | 'data-planes';
+/** The four addon-settings methods reachable over the addon-call plane. */
+export type AddonSettingsMethod = 'getGlobalSettings' | 'updateGlobalSettings' | 'getDeviceSettings' | 'updateDeviceSettings';
+/**
+ * Parent → child: invoke an ADDON-LEVEL method on a loaded addon (not a cap).
+ * Carried as a correlated request frame (`channel.request`) — it returns a
+ * value (route descriptors, the custom-action result, or the settings schema /
+ * update ack). See {@link AddonCallTarget} for the exhaustive surface list.
+ */
+export interface AddonCallMessage {
+    readonly kind: 'addon-call';
+    readonly addonId: string;
+    readonly target: AddonCallTarget;
+    /** Required when `target === 'custom'` — the custom-action name. */
+    readonly action?: string;
+    /** Required when `target === 'settings'` — which settings method to invoke. */
+    readonly method?: AddonSettingsMethod;
+    /** Custom-action / settings input (already validated by the hub). */
+    readonly args?: unknown;
+}
+/**
+ * Parent → child: request to change the child's Moleculer log level.
+ * Fire-and-forget (sent via `channel.emit` — no response expected).
+ * Mirrors the `$node-mgmt.setLogLevel` Moleculer action for UDS children.
+ */
+export interface SetLogLevelMessage {
+    readonly kind: 'set-log-level';
+    readonly level: string;
+}
+/** Parent → child request bodies. */
+export type ParentToChildRequest = CapCallMessage | ParentEventMessage | ReadinessSnapshotResponse | SetLogLevelMessage | AddonCallMessage;
+/** Public view of a registered child (no channel handle). */
+export interface RegisteredChild {
+    readonly childId: string;
+    readonly caps: readonly ChildCapDescriptor[];
+}
+/** Arguments to route a cap method call (the `cap-call` message minus its discriminant). */
+export type CapCallInput = Omit<CapCallMessage, 'kind'>;
+/** Arguments to route an addon-level call (the `addon-call` message minus its discriminant). */
+export type AddonCallInput = Omit<AddonCallMessage, 'kind'>;

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

@@ -0,0 +1,7 @@
+import { LocalTransportFactory } from './local-transport.js';
+/**
+ * The extension seam. UDS is the only shipped implementation; a future
+ * transport implements `LocalTransportFactory` and is selected here (e.g. via
+ * a `CAMSTACK_LOCAL_TRANSPORT` env) without touching any consumer.
+ */
+export declare function createLocalTransport(): LocalTransportFactory;

package/dist/kernel/transport/frame-codec.d.ts

@@ -0,0 +1,7 @@
+/** Encode a value as a length-prefixed (4-byte big-endian) MsgPack frame. */
+export declare function encodeFrame(value: unknown): Buffer;
+/** Reassembles length-prefixed MsgPack frames from a byte stream. */
+export declare class FrameDecoder {
+    private buf;
+    push(chunk: Buffer): unknown[];
+}

package/dist/kernel/transport/index.d.ts

@@ -0,0 +1,27 @@
+export type { Frame, RequestHandler, EventHandler, LocalChannel, LocalTransportServer, LocalTransportClient, LocalTransportFactory, } from './local-transport.js';
+export { encodeFrame, FrameDecoder } from './frame-codec.js';
+export { localEndpointPath } from './local-endpoint-path.js';
+export { SocketChannel } from './socket-channel.js';
+export { UdsLocalTransportServer, UdsLocalTransportClient } from './uds-local-transport.js';
+export { createLocalTransport } from './create-local-transport.js';
+export type { ChildCapDescriptor, RegisterMessage, ChildLogMessage, ChildEventMessage, ChildToParentRequest, CapCallMessage, CapCallInput, CapCallOutMessage, AddonCallMessage, AddonCallInput, AddonCallTarget, AddonSettingsMethod, ParentToChildRequest, RegisteredChild, SetLogLevelMessage, } from './child-cap-protocol.js';
+export { LocalChildRegistry, UDS_NO_ROUTE_PREFIX } from './local-child-registry.js';
+export type { LocalChildRegistryOptions, LocalChildRegistryLogger } from './local-child-registry.js';
+export type { LocalChildClientOptions, AddonCallHandler } from './local-child-client.js';
+export { LocalChildClient } from './local-child-client.js';
+export type { CapRoute, CapRouteBase, CapRouteOpts, HubInProcessRoute, HubLocalUdsRoute, RemoteMoleculerRoute, AgentChildForwardRoute, CapInvoker, InProcessProviderRef, CapRouteReason, RejectedRoute, CapRouteErrorDetail, } from './cap-route.js';
+export { CapRouteError, classifyCapRoute } from './cap-route.js';
+export { CapRouteResolver, AGENT_CAP_FWD_SERVICE, AGENT_CAP_FWD_ACTION, } from './cap-route-resolver.js';
+export type { NodeCapAuthority, InProcessProviderLookup, CapRouteResolverDeps, AgentCapForwardParams, HubLocalChildDispatcher, } from './cap-route-resolver.js';
+export { NATIVE_PROVIDER_SERVICE_INFIX, capServiceName, capActionName, capActionSuffix, capBareAction, parseCapAction, } from './cap-action-name.js';
+export type { ParsedCapAction } from './cap-action-name.js';
+export { createUdsLogger, createUdsLoggerWithControl } from './uds-logger.js';
+export type { UdsLogSink, UdsLogLevelControl } from './uds-logger.js';
+export { udsChildLogToWorkerEntry } from './uds-log-ingest.js';
+export type { WorkerLogEntry } from './uds-log-ingest.js';
+export { createUdsEventBus } from './uds-event-bus.js';
+export type { UdsEventChannel } from './uds-event-bus.js';
+export { createUdsEventBridge } from './uds-event-bridge.js';
+export type { UdsEventBridgeDeps, ChildEventBroadcaster } from './uds-event-bridge.js';
+export { createParentUnownedCallHandler } from './parent-unowned-call.js';
+export type { ParentUnownedCallDeps, ParentUnownedCallLogger } from './parent-unowned-call.js';