@camstack/system 1.0.2

package/dist/kernel/config-schema.d.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+/** Default data directory — used when CAMSTACK_DATA env var is not set */
+export declare const DEFAULT_DATA_PATH = "camstack-data";
+/** Bootstrap config -- loaded from config.yaml ONLY at startup.
+ *  All other settings live in SQL (system_settings table). */
+export declare const bootstrapSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        agent: "agent";
+        hub: "hub";
+    }>>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+        dataPath: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    auth: z.ZodDefault<z.ZodObject<{
+        jwtSecret: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        adminUsername: z.ZodDefault<z.ZodString>;
+        adminPassword: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    hub: z.ZodDefault<z.ZodObject<{
+        url: z.ZodDefault<z.ZodString>;
+        token: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    agent: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        statusPort: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    tls: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        certPath: z.ZodOptional<z.ZodString>;
+        keyPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    bootstrap: z.ZodDefault<z.ZodObject<{
+        settingsStoreAddon: z.ZodDefault<z.ZodString>;
+        installSource: z.ZodOptional<z.ZodEnum<{
+            local: "local";
+            npm: "npm";
+            symlink: "symlink";
+        }>>;
+        requiredAddons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        forceDisable: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BootstrapConfig = z.infer<typeof bootstrapSchema>;
+/**
+ * Runtime defaults — re-exported from @camstack/types (canonical location).
+ * Kept here for backward compatibility with existing kernel consumers.
+ */
+export { RUNTIME_DEFAULTS } from '@camstack/types';
+export type ServerMode = 'hub' | 'agent';
+export type AppConfig = BootstrapConfig & {
+    features: {
+        streaming: boolean;
+        notifications: boolean;
+        objectDetection: boolean;
+        remoteAccess: boolean;
+        agentCluster: boolean;
+        smartHome: boolean;
+        recordings: boolean;
+        backup: boolean;
+        repl: boolean;
+    };
+    storage: {
+        provider: string;
+        locations: Record<string, string>;
+    };
+    logging: {
+        level: string;
+        retentionDays: number;
+    };
+    eventBus: {
+        ringBufferSize: number;
+    };
+    retention: {
+        detectionEventsDays: number;
+        audioLevelsDays: number;
+    };
+    providers: Array<{
+        id: string;
+        type: string;
+        name: string;
+        url?: string;
+        username?: string;
+        password?: string;
+        mqtt?: {
+            brokerUrl: string;
+            username?: string;
+            password?: string;
+            topicPrefix: string;
+        };
+    }>;
+};

package/dist/kernel/custom-action-registry.d.ts

@@ -0,0 +1,23 @@
+import { CustomActionSpec, CustomActionsSpec } from '@camstack/types';
+type Handler = (action: string, input: unknown) => Promise<unknown>;
+export interface CustomActionEntry {
+    readonly spec: CustomActionSpec;
+    readonly handler: (input: unknown) => Promise<unknown>;
+}
+/**
+ * CustomActionRegistry — per-process registry of addon custom actions.
+ *
+ * Populated at boot from each addon's `AddonInitResult.customActions` +
+ * `handleCustomAction` handler. Rejects actions declared with scope other
+ * than 'system' (today only 'system' is runtime-supported; the descriptor
+ * allows future scopes for forward compat).
+ */
+export declare class CustomActionRegistry {
+    private readonly byAddon;
+    registerAddon(addonId: string, catalog: CustomActionsSpec, handler: Handler): void;
+    unregisterAddon(addonId: string): void;
+    resolve(addonId: string, action: string): CustomActionEntry | null;
+    listActions(addonId: string): readonly string[];
+    listAddons(): readonly string[];
+}
+export {};

package/dist/kernel/deps/addon-deps-manager.d.ts

@@ -0,0 +1,19 @@
+import { IScopedLogger, IAddonDepsManager } from '@camstack/types';
+export declare class AddonDepsManager implements IAddonDepsManager {
+    private readonly logger;
+    private readonly nodeRoot;
+    private readonly depsDir;
+    constructor(_dataDir: string, logger: IScopedLogger);
+    ensureBinary(opts: {
+        readonly name: string;
+        readonly downloadUrl: string;
+        readonly isArchive?: boolean;
+        readonly archiveFormat?: 'zip' | 'tar.gz' | 'tar.xz';
+        readonly archiveInnerPath?: string;
+    }): Promise<string>;
+    ensureFfmpeg(): Promise<string>;
+    ensurePython(): Promise<string | null>;
+    installPythonPackages(packages: readonly string[]): Promise<void>;
+    installPythonRequirements(requirementsFile: string): Promise<void>;
+    getDepsDir(): string;
+}

package/dist/kernel/deps/manifest-native-deps.d.ts

@@ -0,0 +1,25 @@
+import { IScopedLogger } from '@camstack/types';
+/**
+ * Native node modules an addon needs at runtime but cannot be bundled
+ * (`.node` binary files require ABI-matched compilation). Mirror of the
+ * Python `requirements.txt` pattern in `manifest-python-deps.ts` —
+ * declared in the addon's `package.json` under `camstack.nativeDependencies`,
+ * installed per-addon at install time so the host's regular `npm install`
+ * doesn't pull in the union of every camera driver's native deps.
+ *
+ * Phase E of the bundles + builder modernization spec
+ * (`docs/superpowers/specs/2026-05-09-bundles-and-builder-modernization-design.md`).
+ *
+ * Idempotent: hashes the `nativeDependencies` map and writes a marker
+ * to `<addonDir>/.camstack-native-deps-installed`. Re-installing only
+ * happens when the declared set changes.
+ *
+ * Failure modes:
+ *   - manifest doesn't declare `nativeDependencies` (or declares empty) → no-op
+ *   - `npm install` fails → throws (caller decides whether to abort install)
+ *   - rebuild step fails → logs warning + continues (install may still
+ *     work if prebuilt binaries shipped in the package cover the host
+ *     ABI; surface a clear error at first `import` of the native module
+ *     otherwise).
+ */
+export declare function installManifestNativeDeps(addonDir: string, pkgRaw: Record<string, unknown>, logger: IScopedLogger, registry?: string): Promise<void>;

package/dist/kernel/deps/manifest-python-deps.d.ts

@@ -0,0 +1,20 @@
+import { AddonDeclaration, IAddonDepsManager, IScopedLogger } from '@camstack/types';
+/**
+ * Auto-install the pip requirements file declared in an addon's manifest
+ * (`camstack.addons[].python.requirements`) into the embedded portable
+ * Python before `onInitialize()` runs.
+ *
+ * Idempotent: `installPythonRequirements` skips when the file's content
+ * hash matches an existing marker under `<python>/.requirements-installed/`.
+ * Re-downloading the embedded Python wipes the marker dir together with
+ * site-packages, forcing a fresh re-install.
+ *
+ * Failure modes:
+ *   - manifest doesn't declare `python.requirements` → no-op.
+ *   - embedded Python download fails → warn + continue. The addon's
+ *     own `onInitialize` will raise a precise error if Python is
+ *     actually required.
+ *   - pip install fails → propagate so the group-runner aborts boot
+ *     loudly (vs silently shipping a half-installed env).
+ */
+export declare function installManifestPythonDeps(declaration: AddonDeclaration, addonDir: string, deps: IAddonDepsManager, logger: IScopedLogger): Promise<void>;

package/dist/kernel/device-registry.d.ts

@@ -0,0 +1,29 @@
+import { IDevice, IDeviceRegistry } from '@camstack/types';
+export declare class DeviceRegistry implements IDeviceRegistry {
+    /** Primary map: every registered device keyed by its progressive
+     *  numeric id. Numeric id is the system-wide unique handle; stableId
+     *  is integration-scoped and only used at external boundaries. */
+    private readonly byId;
+    /** Addon scoping index: addonId → set of numeric device ids owned
+     *  by that addon. Lets `getAllForAddon` and per-addon teardown stay
+     *  O(1) per lookup without a second primary table. */
+    private readonly byAddon;
+    /** Inverse of byAddon for the single-device case. */
+    private readonly idToAddon;
+    register(addonId: string, device: IDevice): void;
+    /** Owning addonId for a registered numeric id, or null if not registered. */
+    getAddonId(id: number): string | null;
+    /** Look up any registered device by its progressive numeric id. */
+    getById(id: number): IDevice | null;
+    getAllForAddon(addonId: string): readonly IDevice[];
+    getChildren(parentDeviceId: number): readonly IDevice[];
+    remove(deviceId: number): void;
+    getAll(): readonly IDevice[];
+    /** All devices with their owning addonId. */
+    getAllWithAddonId(): readonly {
+        addonId: string;
+        device: IDevice;
+    }[];
+    /** All addonIds that have at least one registered device. */
+    getAddonIds(): readonly string[];
+}

package/dist/kernel/fs-utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Ensure a directory exists (recursive).
+ * Single source of truth — replaces scattered mkdirSync calls.
+ */
+export declare function ensureDir(dirPath: string): void;
+/**
+ * Copy a directory recursively.
+ * Single source of truth — extracted from addon-installer + first-boot-installer.
+ */
+export declare function copyDirRecursive(src: string, dest: string): void;
+/**
+ * Strip @camstack/* dependencies and devDependencies from a package.json object.
+ * Used when installing addons into the addons directory — @camstack packages
+ * are provided by the host runtime, not installed per-addon.
+ *
+ * Returns a new object (immutable).
+ */
+export declare function stripCamstackDeps(pkg: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Copy extra file directories declared in package.json "files" field.
+ * Copies directories (not individual files) from source to destination.
+ * Skips "dist" (already handled) and glob patterns.
+ */
+export declare function copyExtraFileDirs(pkgJson: Record<string, unknown>, sourceDir: string, destDir: string): void;
+/**
+ * Check if any file in src/ is newer than dist/.
+ * Returns true if rebuild is needed.
+ */
+export declare function isSourceNewer(packageDir: string): boolean;
+/**
+ * Ensure a library dependency (not an addon) has a dist/ directory.
+ * Does NOT rebuild — in dev mode, `npm run build` should be run separately.
+ * Only checks that dist/ exists and has an index file.
+ */
+export declare function ensureLibraryBuilt(packageName: string, packagesDir: string): void;
+/**
+ * Install a single npm package into a target directory (package.json + dist/).
+ * No validation on camstack.addons -- works for any @camstack/* package.
+ * Uses synchronous child_process calls (suitable for first-boot and update paths).
+ */
+export declare function installPackageFromNpmSync(packageName: string, targetDir: string): void;

package/dist/kernel/hwaccel/hwaccel-resolver.d.ts

@@ -0,0 +1,19 @@
+import { HwAccelBackend, HwAccelResolution } from '@camstack/types';
+/**
+ * Resolve the preferred hardware acceleration backend order for the
+ * current host.
+ *
+ * An explicit `prefer` override — typically read from
+ * `system-config.hwaccel.prefer` — wins unconditionally: the caller
+ * stays on that single backend and falls back to software only if it
+ * fails at decoder init.
+ *
+ * When no override is set, platform signals drive the order.
+ */
+export declare function resolveHwAccel(prefer?: HwAccelBackend | 'none' | null): HwAccelResolution;
+/**
+ * Build the `IKernelHwAccel` provider used to populate `ctx.kernel.hwaccel`.
+ * Thin async wrapper around the sync `resolveHwAccel` function so the
+ * contract matches the per-node `$hwaccel.resolve` Moleculer action.
+ */
+export declare function createKernelHwAccel(): import('@camstack/types').IKernelHwAccel;

package/dist/kernel/hwaccel/hwaccel-service.d.ts

@@ -0,0 +1,4 @@
+import { ServiceSchema } from 'moleculer';
+import { IKernelHwAccel } from '@camstack/types';
+export type HwAccelServiceDeps = IKernelHwAccel;
+export declare function createHwAccelService(deps: HwAccelServiceDeps): ServiceSchema;

package/dist/kernel/index.d.ts

@@ -0,0 +1,74 @@
+export type { RegisteredAddon } from './addon-loader.js';
+export { AddonLoader } from './addon-loader.js';
+export { AddonEngineManager } from './addon-engine-manager.js';
+export type { AddonInstallerConfig, InstallSource, InstalledPackage } from './addon-installer.js';
+export { AddonInstaller } from './addon-installer.js';
+export type { AddonInstallSource, AddonManifestEntry, AddonManifestFile } from './addon-manifest.js';
+export { AddonManifest } from './addon-manifest.js';
+export { copyDirRecursive, ensureDir, stripCamstackDeps, copyExtraFileDirs, ensureLibraryBuilt, installPackageFromNpmSync, isSourceNewer, } from './fs-utils.js';
+export { detectWorkspacePackagesDir } from './workspace-detect.js';
+export { RESTART_MARKER_FILE, clearPendingRestart, getRestartMarkerPath, readPendingRestart, scheduleSelfRestart, writePendingRestart, } from './restart-coordinator.js';
+export type { PendingRestartMarker, RestartKind, ScheduleSelfRestartOptions, } from './restart-coordinator.js';
+export { CapabilityHandle, CapabilityUnavailableError } from './capability-handle.js';
+export { CapabilityRegistry } from './capability-registry.js';
+export { describeProviderKindDrift } from './provider-kind-drift.js';
+export type { ProviderKindHint } from './provider-kind-drift.js';
+export type { CapabilityRouter, CapabilityRouterFactory, ConfigReader, } from './capability-registry.js';
+export { CustomActionRegistry, type CustomActionEntry } from './custom-action-registry.js';
+export { INFRA_CAPABILITIES, isInfraCapability } from './infra-capabilities.js';
+export type { InfraCapability } from './infra-capabilities.js';
+export { ConfigManager } from './config-manager.js';
+export type { ISettingsStore } from './config-manager.js';
+export { bootstrapSchema, RUNTIME_DEFAULTS, DEFAULT_DATA_PATH } from './config-schema.js';
+export type { BootstrapConfig, AppConfig, ServerMode } from './config-schema.js';
+export type { AddonSettingsView } from './config-manager.js';
+export { DeviceRegistry } from './device-registry.js';
+export { buildStorageLocationRegistry } from './storage-location-registry.js';
+export type { StorageLocationRegistry } from './storage-location-registry.js';
+export { createBroker, deriveAgentListenPort } from './moleculer/broker-factory.js';
+export type { BrokerConfig } from './moleculer/broker-factory.js';
+export { createAddonService, validateProviderRegistrations, } from './moleculer/addon-service-factory.js';
+export { createCoreCapService, CORE_CAP_SERVICE_NAME } from './moleculer/core-cap-service.js';
+export type { CoreCapAction, CoreCapServiceOptions } from './moleculer/core-cap-service.js';
+export { createAddonContext, createUdsAddonContext, setHubConnected, adaptBrokerToCluster, registerEventBusService, getBrokerEventBus, EVENT_TOPIC_PREFIX, } from './moleculer/addon-context-factory.js';
+export { HubLogForwarder } from './moleculer/hub-log-forwarder.js';
+export type { AddonContextOptions } from './moleculer/addon-context-factory.js';
+export { createHubService } from './moleculer/hub-service.js';
+export { HubNodeRegistry } from './moleculer/node-registry.js';
+export type { CallFn, RegisteredAddonManifest, RegisteredNativeCap, RegisterNodeParams, RegisterNodeResult, NodeCapEntry, NodeNativeCapEntry, } from './moleculer/node-registry.js';
+export { callRegisterNodeWithRetry, buildNodeManifest } from './moleculer/register-node-client.js';
+export type { RegisterNodeBroker, CallRegisterNodeOptions, } from './moleculer/register-node-client.js';
+export { hashClusterSecret, clusterSecretMatches, isClusterSecretMismatchError, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, } from './moleculer/cluster-secret.js';
+export { serializeTypedArrays } from './moleculer/typed-array-serde.js';
+export { createReadinessService, createReadinessServiceForRegistry, } from './moleculer/readiness-service.js';
+export type { ReadinessServiceDeps } from './moleculer/readiness-service.js';
+export { getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, } from './moleculer/readiness-context.js';
+export type { UdsReadinessClient } from './moleculer/readiness-context.js';
+export { createStreamProbeBrokerService } from './moleculer/stream-probe-service.js';
+export type { StreamProbeBrokerDeps } from './moleculer/stream-probe-service.js';
+export { resolveHwAccel, createKernelHwAccel } from './hwaccel/hwaccel-resolver.js';
+export { createHwAccelService } from './hwaccel/hwaccel-service.js';
+export { AddonDepsManager } from './deps/addon-deps-manager.js';
+export { installManifestPythonDeps } from './deps/manifest-python-deps.js';
+export { installManifestNativeDeps } from './deps/manifest-native-deps.js';
+export { AddonHealthMonitor, HEALTH_MONITOR_TICK_MS, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, } from './addon-health-monitor.js';
+export type { AddonHealthPhase, AddonHealthState, AddonHealthSnapshot, AddonHealthMonitorOptions, } from './addon-health-monitor.js';
+export type { HwAccelServiceDeps } from './hwaccel/hwaccel-service.js';
+export type { HubServiceDeps } from './moleculer/hub-service.js';
+export { createBrokerDeviceManagerApi, buildNativeCapProxy, buildUdsNativeCapProxy, mountNativeCapService, NATIVE_PROVIDER_SERVICE_INFIX, } from './moleculer/device-cap-proxy.js';
+export type { WorkerDeviceManagerOptions } from './moleculer/device-cap-proxy.js';
+export { getWorkerDeviceRegistry } from './moleculer/addon-context-factory.js';
+export { localProviderLink, brokerTransportLink, ipcChildLink, ipcParentLink, buildLinkChain, brokerCallForCap, } from './moleculer/trpc-links.js';
+export type { LocalProviderResolver, BrokerCapCallOpts } from './moleculer/trpc-links.js';
+export { createProcessService } from './moleculer/process-service.js';
+export type { ProcessInfo } from './moleculer/process-service.js';
+export { CapUsageRegistry, getCapUsageRegistry, __resetCapUsageRegistryForTests, } from './moleculer/cap-usage-registry.js';
+export type { CapUsageCallRecord, CapUsageEdge, CapUsageRegistryOptions, } from './moleculer/cap-usage-registry.js';
+export { createScopedProcessManager } from './moleculer/process-context.js';
+export type { IAddonProcessManager } from '@camstack/types';
+export { callWithServiceDiscovery } from './moleculer/resilient-cap-call.js';
+export type { ServiceDiscoveryBroker } from './moleculer/resilient-cap-call.js';
+export { RingBuffer } from './utils/ring-buffer.js';
+export * from './transport/index.js';
+export { ReadinessRegistry, ReadinessTimeoutError, readinessKey, scopeKey, emitDownForOwnedCaps, } from '@camstack/types';
+export type { ReadinessHandler, ReadinessTransition, AwaitReadyOptions, ReadinessRegistryOptions, } from '@camstack/types';

package/dist/kernel/infra-capabilities.d.ts

@@ -0,0 +1,13 @@
+export interface InfraCapability {
+    /** Capability name */
+    readonly name: string;
+    /** If true, boot aborts when this capability's addon fails to initialize */
+    readonly required: boolean;
+}
+/**
+ * Infrastructure capabilities that must boot before all other addons.
+ * Enabled in Phase 1 of the boot sequence. Order matters: storage before logging.
+ */
+export declare const INFRA_CAPABILITIES: readonly InfraCapability[];
+/** Check if a capability name is an infrastructure capability */
+export declare function isInfraCapability(name: string): boolean;

package/dist/kernel/moleculer/addon-context-factory.d.ts

@@ -0,0 +1,91 @@
+import { ServiceBroker } from 'moleculer';
+import { InternalAddonContext, AddonDeclaration, IStorageProvider, IScopedLogger, IClusterBroker } from '@camstack/types';
+import { DeviceRegistry } from '../device-registry.js';
+import { CapabilityRegistry } from '../capability-registry.js';
+import { CapCallInput } from '../transport/index.js';
+import { LocalChildClient } from '../transport/local-child-client.js';
+import { DataPlaneSink } from './addon-data-plane-facility.js';
+import { getBrokerEventBus, registerEventBusService, clusterEventTopic, EVENT_TOPIC_PREFIX } from './event-bus.js';
+import { createRunnerLogger, setHubConnected, ___resetHubConnectedForTests, ___createRemoteLoggerForTests } from './remote-logger.js';
+import { withAddonScope, setPreferredProvider, ___resetBindingSubscriptionForTests } from './provider-registry.js';
+/**
+ * Adapt a Moleculer ServiceBroker to the camstack-types `IClusterBroker`
+ * structural interface so addons can consume cluster-level RPC without
+ * pulling a moleculer dependency. Method signatures differ slightly
+ * (Moleculer's overloads are wider than the camstack contract), so we
+ * forward through a thin object instead of casting at the boundary.
+ */
+declare function adaptBrokerToCluster(broker: ServiceBroker): IClusterBroker;
+/**
+ * Expose the per-process worker device registry so the process-runner can
+ * mount the `device-ops-bridge` Moleculer service on top of the same live
+ * IDevice instances that `createBrokerDeviceManagerApi` writes to.
+ *
+ * Hub-side contexts also share this module, but they pass their own
+ * `opts.deviceRegistry` explicitly — nothing hub-side uses this accessor.
+ */
+export declare function getWorkerDeviceRegistry(): DeviceRegistry;
+/**
+ * Options for enriching the addon context with infrastructure providers.
+ * When the agent boots with core addons (storage, settings-store),
+ * pass them here so deployed addons get full capabilities.
+ */
+interface AddonContextOptions {
+    readonly storageProvider?: IStorageProvider;
+    readonly addonConfig?: Record<string, unknown>;
+    /** Custom logger factory — when set, overrides the default remote logger */
+    readonly createLogger?: (addonId: string) => IScopedLogger;
+    /**
+     * Hub `CapabilityRegistry`. When set, the `DeviceManagerApi` created
+     * for this context wires `DeviceContext.registerNativeCap` through it
+     * so device-driver addons can publish per-device native capability
+     * providers. Forked-worker processes don't carry a CapabilityRegistry,
+     * so this field is left undefined there — `registerNativeCap` becomes
+     * unavailable on workers, which throw at runtime if called.
+     */
+    readonly capabilityRegistry?: CapabilityRegistry;
+    /**
+     * UDS egress function for child→parent cap calls. When provided,
+     * `ipcParentLink` is inserted between `localProviderLink` and
+     * `brokerTransportLink` so addon-runner cap calls route over UDS
+     * instead of through Moleculer when the parent owns the target cap.
+     *
+     * Returns `null` when the UDS channel is not yet connected (before
+     * `LocalChildClient.start()` resolves), in which case `ipcParentLink`
+     * no-ops and the call falls through to `brokerTransportLink`.
+     *
+     * Hub-side contexts omit this option; their link chain is unchanged.
+     */
+    readonly getParentCallOut?: () => ((input: CapCallInput) => Promise<unknown>) | null;
+    /**
+     * Where this context's `ctx.dataPlane` publishes its live HTTP data-plane
+     * endpoints. The forked addon-runner passes a sink writing into a per-addonId
+     * map the hub pulls (`target: 'data-planes'`); the hub passes a sink writing
+     * straight into its `DataPlaneRegistry` for co-located addons. Omitted → the
+     * facility still serves locally but nothing advertises it (tests/isolation).
+     */
+    readonly dataPlaneSink?: DataPlaneSink;
+}
+/**
+ * Broker-mode entry point — UNCHANGED public signature. The hub
+ * (`addon-registry.service.ts`), the agent (`agent-bootstrap.ts`), and
+ * every broker-mode test call this with a positional `ServiceBroker`.
+ */
+declare function createAddonContext(broker: ServiceBroker, declaration: AddonDeclaration, dataDir: string, options?: AddonContextOptions): Promise<InternalAddonContext>;
+/**
+ * UDS-mode entry point — for a broker-less forked `addon-runner` child
+ * (Phase F1+F2). Logger/eventBus/readiness ride the UDS channel; the tRPC
+ * link chain is `[localProviderLink, ipcParentLink]` (no broker, so no
+ * `brokerTransportLink`). `getParentCallOut` is implied by the client and
+ * wired automatically — callers MUST NOT pass it in `options`.
+ */
+declare function createUdsAddonContext(client: LocalChildClient, nodeId: string, declaration: AddonDeclaration, dataDir: string, options?: AddonContextOptions): Promise<InternalAddonContext>;
+/**
+ * Drain (and forget) the disposer chain for a worker-side addon. Idempotent:
+ * subsequent calls are no-ops. Called by process-runner / group-runner
+ * before reload or graceful shutdown so resources clean up before the
+ * next addon instance loads.
+ */
+declare function drainWorkerDisposerChain(nodeId: string, addonId: string): Promise<void>;
+export { createAddonContext, createUdsAddonContext, setHubConnected, adaptBrokerToCluster, drainWorkerDisposerChain, registerEventBusService, clusterEventTopic, EVENT_TOPIC_PREFIX, getBrokerEventBus, withAddonScope, setPreferredProvider, createRunnerLogger, __resetHubConnectedForTests, __resetBindingSubscriptionForTests, __createRemoteLoggerForTests, };
+export type { AddonContextOptions };

package/dist/kernel/moleculer/addon-data-plane-facility.d.ts

@@ -0,0 +1,19 @@
+import { AddonDataPlane, AddonDataPlaneEndpoint, IScopedLogger } from '@camstack/types';
+/** Where the facility publishes the addon's current data-plane endpoints so the
+ *  runner can expose them to the hub's pull. */
+export interface DataPlaneSink {
+    set(addonId: string, endpoints: readonly AddonDataPlaneEndpoint[]): void;
+}
+export interface AddonDataPlaneFacility {
+    readonly dataPlane: AddonDataPlane;
+    /** Close the listener + clear endpoints. Wired to the context disposer chain. */
+    dispose(): Promise<void>;
+}
+export declare function createAddonDataPlaneFacility(args: {
+    readonly addonId: string;
+    readonly logger: IScopedLogger;
+    readonly sink?: DataPlaneSink;
+    /** Bind host — `127.0.0.1` for a hub-local addon (default). Remote agents bind
+     *  their reachable interface (deferred — single-hub first). */
+    readonly bindHost?: string;
+}): AddonDataPlaneFacility;

package/dist/kernel/moleculer/addon-runner.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/kernel/moleculer/addon-service-factory.d.ts

@@ -0,0 +1,50 @@
+import { ServiceSchema } from 'moleculer';
+import { ICamstackAddon, AddonDeclaration } from '@camstack/types';
+/**
+ * Validate that every capability declared in the addon manifest has a
+ * provider registered via context.registerProvider() during initialize().
+ *
+ * Call after addon.initialize() to catch missing registrations at boot time
+ * instead of at runtime when a consumer tries to use the capability.
+ */
+declare function validateProviderRegistrations(addonId: string, declaration: AddonDeclaration, providers: ReadonlyMap<string, unknown>, logger?: {
+    warn: (msg: string) => void;
+    debug?: (msg: string) => void;
+    info?: (msg: string) => void;
+}): readonly string[];
+/**
+ * Optional resolver that returns method names for a capability.
+ * Used by the hub to resolve methods from CapabilityDefinitions (*.cap.ts)
+ * when the package.json declaration doesn't include explicit methods.
+ */
+type MethodResolver = (capabilityName: string) => readonly string[];
+/**
+ * Wrap an ICamstackAddon as a Moleculer ServiceSchema.
+ *
+ * Methods for each capability are resolved in this order:
+ * 1. `declaration.capabilities[].methods` from package.json
+ * 2. `methodResolver(capName)` from CapabilityRegistry definitions
+ * 3. Auto-discovery: enumerate own methods on the registered provider
+ *
+ * Additionally, the four two-level settings methods (`getGlobalSettings`,
+ * `updateGlobalSettings`, `getDeviceSettings`, `updateDeviceSettings`)
+ * are auto-exposed under a
+ * `settings.*` namespace if the addon implements them. This replaces the
+ * former `$addonHost` Moleculer service — the hub's `addon-settings`
+ * singleton provider calls `broker.call('<addonId>.settings.<method>')`.
+ */
+declare function createAddonService(addon: ICamstackAddon, declaration: AddonDeclaration, options?: {
+    readonly methodResolver?: MethodResolver;
+    /** Per-action Moleculer timeout override: (capName, methodName) → ms */
+    readonly timeoutResolver?: (capName: string, methodName: string) => number | undefined;
+    readonly providers?: ReadonlyMap<string, unknown>;
+    /**
+     * Custom action catalog declared via `onInitialize()`'s `customActions`
+     * field. The service exposes them as `custom.<actionName>` moleculer
+     * actions + advertises their names via metadata so the hub can proxy
+     * dispatches into the worker when the addon runs forkable.
+     */
+    readonly customActions?: Readonly<Record<string, unknown>>;
+    readonly actionHandlers?: Readonly<Record<string, (input: unknown) => unknown | Promise<unknown>>>;
+}): ServiceSchema;
+export { createAddonService, validateProviderRegistrations };

package/dist/kernel/moleculer/broker-factory.d.ts

@@ -0,0 +1,50 @@
+import { ServiceBroker } from 'moleculer';
+interface BrokerConfig {
+    readonly nodeID: string;
+    readonly mode: 'hub' | 'agent' | 'test';
+    readonly hubAddress?: string;
+    readonly logLevel?: string;
+    /** Shared secret — used as Moleculer namespace to isolate the cluster on the network */
+    readonly secret?: string;
+    /**
+     * TCP port the hub listens on for cluster traffic.
+     * Agents need a deterministic port to connect via `urls: 'hub@host:port'`
+     * when UDP multicast discovery is disabled.
+     */
+    readonly tcpPort?: number;
+    /** UDP port for cluster discovery (default: 4445). */
+    readonly udpPort?: number;
+    /**
+     * Explicit TCP port for the agent's own Moleculer reader to bind.
+     * When omitted, the port is derived deterministically from `nodeID`
+     * (see `deriveAgentListenPort`). Set this only to resolve a port
+     * collision between two agents that happen to hash to the same port
+     * on one host.
+     */
+    readonly agentListenPort?: number;
+}
+/**
+ * Derive a STABLE Moleculer reader port for an agent from its nodeID.
+ *
+ * Moleculer's TCP transporter keeps disconnected nodes in its
+ * `NodeCatalog` (it never deletes them) and `processGossipHello` only
+ * adopts a node's host/port when the node is unknown — a reconnecting
+ * node's address is therefore never refreshed. With an OS-assigned
+ * EPHEMERAL reader port (`port: 0`) every agent restart picks a new
+ * port, so after a kill+restart under the SAME nodeID the hub (and every
+ * forked group-runner that gossiped about the agent) keeps the DEAD port
+ * and can never deliver the `GOSSIP_RESPONSE` carrying its INFO. The
+ * agent then never re-discovers the hub's services and `ctx.api.*` calls
+ * (e.g. the early `settings-store.get` in `bootCoreAddons`) poll service
+ * discovery forever.
+ *
+ * Binding a port DERIVED FROM the nodeID makes the agent reconnect at the
+ * SAME address every restart — exactly like the hub's fixed 6000 — so the
+ * stale catalog entries everywhere still point at a live socket and
+ * Moleculer's gossip seq self-healing completes the handshake. The nodeID
+ * is the agent's persisted stable identity, so the port is stable too.
+ */
+declare function deriveAgentListenPort(nodeID: string): number;
+declare function createBroker(config: BrokerConfig): ServiceBroker;
+export { createBroker, deriveAgentListenPort };
+export type { BrokerConfig };

package/dist/kernel/moleculer/cap-usage-registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * In-memory observation of tRPC cap calls between addons.
+ *
+ * Storage: `Map<callerAddonId, Map<providerAddonId, Map<capName, RollingWindow>>>`.
+ * `RollingWindow` is a fixed-size ring of 1-second buckets — default 300
+ * buckets = 5 minutes retention. Queries narrower than the retention
+ * window filter buckets at read time.
+ *
+ * Memory bound: 30 callers × 30 providers × 50 caps × 300 buckets × 16 B ≈ 22 MB
+ * worst case. Realistic load (~10 active caller→provider→cap triples)
+ * keeps it under 200 KB.
+ */
+export interface CapUsageCallRecord {
+    readonly callerAddonId: string;
+    readonly providerAddonId: string;
+    readonly capName: string;
+    readonly methodName: string;
+    readonly atMs: number;
+}
+export interface CapUsageEdge {
+    readonly callerAddonId: string;
+    readonly providerAddonId: string;
+    readonly capName: string;
+    readonly callsPerMin: number;
+    readonly lastCallAtMs: number;
+}
+export interface CapUsageRegistryOptions {
+    /** Max retention in seconds (ring length). Default 300. */
+    readonly retentionSeconds?: number;
+}
+export declare class CapUsageRegistry {
+    private readonly retentionSeconds;
+    private readonly map;
+    constructor(opts?: CapUsageRegistryOptions);
+    recordCall(rec: CapUsageCallRecord): void;
+    getGraph(opts: {
+        windowSeconds: number;
+        nowMs: number;
+    }): readonly CapUsageEdge[];
+    /** Test / diagnostic helper — drops all recorded calls. */
+    clear(): void;
+}
+/** Hub-side singleton. The first caller seeds it; subsequent calls return the same. */
+export declare function getCapUsageRegistry(): CapUsageRegistry;
+/** Test helper — clears the singleton (kept module-private elsewhere). */
+export declare function __resetCapUsageRegistryForTests(): void;