@camstack/system 1.1.11 → 1.1.13

package/dist/builtins/device-manager/device-state-mirror.d.ts

@@ -0,0 +1,137 @@
+import { AddonContext, ICapabilityRegistry } from '@camstack/types';
+import { ResolvedTargetLink, DependentLink } from './device-link-overlay.js';
+import { DeviceManagerSettings } from './device-meta-store.js';
+/**
+ * Live view of the addon's cross-device link reverse-index + capability
+ * registry the mirror reads when overlaying linked values. Exposed via getters
+ * because the link maps are reassigned on every `rebuildLinkDependents`.
+ */
+export interface LinkOverlayHost {
+    readonly linkTargets: Map<string, ResolvedTargetLink[]>;
+    readonly linkDependents: Map<string, DependentLink[]>;
+    readonly capabilityRegistry: ICapabilityRegistry | undefined;
+}
+export declare class DeviceStateMirror {
+    private readonly ctx;
+    private readonly linkHost;
+    /**
+     * Hub-side mirror of every device's cap-keyed runtime state.
+     * Key: deviceId. Value: per-cap slice map. Empty by default —
+     * slices show up as `setCapSlice` calls trickle in.
+     */
+    private readonly stateMirror;
+    /**
+     * Per-device disk-write debouncer for runtime-state. `setCapSlice`
+     * updates the in-memory mirror synchronously and emits the change
+     * event immediately, but the disk write is coalesced.
+     */
+    private readonly runtimeStateDebounce;
+    private static readonly RUNTIME_STATE_DEBOUNCE_MS;
+    /** Loop/churn guard: last overlaid slice emitted per `${deviceId}:${cap}`. */
+    private readonly lastEmittedOverlay;
+    constructor(ctx: AddonContext, linkHost: LinkOverlayHost);
+    /**
+     * Single-cap mirror update — diff against the current mirror,
+     * persist the new slice in-memory, emit `DeviceStateChanged` for
+     * this cap. No-op on identical writes (both same shape and same
+     * values). Called by `setCapSlice` provider.
+     */
+    applySingleCapUpdate(deviceId: number, capName: string, slice: Record<string, unknown>): void;
+    /**
+     * Debounced disk writer. Coalesces frequent writes (motion phase
+     * transitions, battery pushes) into one `writeDeviceRuntimeState`
+     * per `RUNTIME_STATE_DEBOUNCE_MS` window. Reads the per-device
+     * blob from the live mirror at flush time so the disk picture is
+     * always the latest state — no risk of writing a stale snapshot.
+     */
+    scheduleRuntimeStateDiskWrite(deviceId: number, settings: DeviceManagerSettings): void;
+    /**
+     * One-shot mirror seed used by `loadRuntimeState` at boot so the
+     * hub knows about every persisted slice without waiting for the
+     * first `setCapSlice` call. No events emitted — this is
+     * initial-state population, not a transition.
+     *
+     * Callers that must not carry a stale per-session probe across a
+     * restart pass the blob through `withResetSessionProbe` first (see
+     * `loadRuntimeState`).
+     */
+    seedMirror(deviceId: number, blob: Record<string, unknown>): void;
+    /**
+     * The hub mirror's `feature-probe.lastProbedAt` is a PER-SESSION liveness
+     * signal — it means "this worker process completed a probe THIS session".
+     * Persisted runtime state carries the PRE-RESTART timestamp, which is stale
+     * after a hub or worker restart: the device has not re-probed yet. Seeding it
+     * verbatim makes `resolveDeviceProbed` report `probed:true` during the
+     * restart→reprobe window, which defeats the export carry-forward gate
+     * (`resolveExportFingerprint`, gated on `device.probed`) and posts a spurious
+     * partial `AddOrUpdateReport` to Alexa/HAP before the real probe lands.
+     *
+     * Reset `lastProbedAt` to 0 for the MIRROR seed only — `probed:false` carries
+     * the last-advertised fingerprint forward until the worker republishes a
+     * fresh probe (its post-probe `setCapSlice` raises `lastProbedAt` again, which
+     * also fires `DeviceReady`). The worker's returned `initialRuntimeState` blob
+     * is untouched, and every non-probe slice (e.g. `device-status`/online) is
+     * preserved.
+     */
+    withResetSessionProbe(blob: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Resolve a device's REAL `online` flag for the persisted/forked-worker
+     * list branch. Forked workers own the live `IDevice` in their own process,
+     * so the hub registry can't read `device.online` directly. The owning
+     * driver instead publishes its liveness through the auto-registered
+     * `device-status` runtime-state slice (`markOnline` → `setCapState`), which
+     * the canonical `deviceState.setCapSlice` write entrypoint mirrors into the
+     * hub-side `stateMirror`. We read that mirrored slice here so the list
+     * payload reflects the device's actual reachability instead of a constant.
+     *
+     * Fallback (`fallbackOnline`) preserves the legacy behaviour when no slice
+     * has been published yet: a persisted device with a live registry is
+     * assumed online (it was successfully registered by its owning process),
+     * and the null-registry "offline view" keeps reporting offline. We never
+     * regress a device to offline merely because its mirror is empty.
+     */
+    resolveDeviceOnline(deviceId: number, fallbackOnline: boolean): boolean;
+    /**
+     * Derive the `probed` flag for an offline-view (forked-worker, not
+     * live in the hub registry) device projection. Reads the mirrored
+     * `feature-probe` slice the owning worker publishes. Mirrors the
+     * `toDeviceInfo` rule: no mirrored slice → ready (`true`, no probe seen);
+     * slice present → ready iff `lastProbedAt` has advanced past 0. The
+     * mirror is populated when the worker's first `setCapSlice` RPC arrives
+     * (BaseDevice seeds `feature-probe` `lastProbedAt:0` at construction, but
+     * cross-process delivery is async); until then the no-entry path returns
+     * `true` — a brief transient window, same as `resolveDeviceOnline`.
+     */
+    resolveDeviceProbed(deviceId: number): boolean;
+    snapshotForDevice(deviceId: number): Record<string, Record<string, unknown>>;
+    /**
+     * Read-time overlay of a cap slice with its cross-device linked values.
+     * Returns a cloned raw mirror slice when the (device, cap) pair has no
+     * links. Sources are read from the same in-hub stateMirror — sync, no
+     * cross-process call. The disk writer must NOT use this method; it must
+     * persist raw provider truth via snapshotForDevice.
+     */
+    overlayedSlice(deviceId: number, cap: string): Record<string, unknown> | null;
+    /**
+     * Like snapshotForDevice but applies the device-link overlay per cap.
+     * Used exclusively by the device-state READ methods (getSnapshot,
+     * getAllSnapshots) so callers see overlayed values. The debounced disk
+     * writer must continue to call snapshotForDevice (raw truth).
+     */
+    snapshotForDeviceOverlayed(deviceId: number): Record<string, Record<string, unknown>>;
+    /** Whole-system mirror dump (overlaid). Backs `deviceState.getAllSnapshots`. */
+    allSnapshotsOverlayed(): Record<string, Record<string, Record<string, unknown>>>;
+    private emitStateChanged;
+    /** Emit DeviceStateChanged for (deviceId, cap) using the OVERLAID slice,
+     *  skipping when the overlay is unchanged since the last emit (loop/churn
+     *  guard). Used for the written pair AND its dependent targets. */
+    private emitOverlayed;
+    /** Drop a removed device's overlay-emit guard entries (keyed
+     *  `${deviceId}:${cap}`) so the map doesn't retain rows for a removed device.
+     *  Called from `removeDevice`. */
+    dropDeviceOverlays(deviceId: number): void;
+    /** Flush every pending debounced disk write (graceful shutdown). Clears the
+     *  debounce slots after awaiting in-flight + scheduled writes so shutdown is
+     *  lossless. */
+    flushPendingWrites(settings: DeviceManagerSettings | undefined): Promise<void>;
+}

package/dist/builtins/device-manager/device-sync-resolvers.d.ts

@@ -0,0 +1,41 @@
+import { ProviderContext } from './device-provider-context.js';
+/**
+ * Sync ownership lookup backing persistence fallbacks (e.g. remove()
+ * when the owning worker is offline). Ownership is keyed by numeric
+ * deviceId → owning addonId as recorded in the persisted meta. NOT
+ * a native-cap lookup: an addon can own a device without registering
+ * every possible cap natively (e.g. RtspCamera without snapshotUrl
+ * doesn't register the snapshot cap). Use `resolveNativeCapOwnerSync`
+ * for cap-resolution paths.
+ */
+export declare function resolveDeviceOwnerSync(pctx: ProviderContext, deviceId: number): string | null;
+/**
+ * Sync lookup for the addon that registered a native provider for
+ * `(capName, deviceId)`. Backs `CapabilityRegistry`'s native fallback
+ * so the hub only synthesizes a cross-process proxy when the cap is
+ * actually published — never on speculative device ownership.
+ *
+ * Resolution order:
+ *  1. Hub-local `capabilityRegistry` (in-process natives — fastest path).
+ *  2. Push-fed `remoteNativeCaps` cache (`DeviceBindingsChanged` events
+ *     from forked workers — accurate in steady state).
+ *  3. Handshake-fed `HubNodeRegistry` via `listClusterNativeCaps()`
+ *     (D3 re-handshake after device restore — covers the Moleculer
+ *     transport window where push events were lost). This is the
+ *     reliable replacement for the deleted `syncWorkerNativeCaps` pull.
+ */
+export declare function resolveNativeCapOwnerSync(pctx: ProviderContext, capName: string, deviceId: number): {
+    addonId: string;
+    nodeId: string;
+} | null;
+/**
+ * Read-time overlay: merge cross-device linked values onto a target cap's
+ * status. Returns null when the device has no links for `cap` (caller uses
+ * the base status untouched). Reads each source cap via the hub registry's
+ * `getProviderForDevice` (routes cross-process); merge is pure.
+ */
+export declare function resolveLinkedStatus(pctx: ProviderContext, input: {
+    deviceId: number;
+    cap: string;
+    baseStatus: unknown;
+}): Promise<Record<string, unknown> | null>;

package/dist/index.js

@@ -4896,6 +4896,219 @@ var CapabilityRegistry = class CapabilityRegistry {
 	}
 };
 //#endregion
+//#region src/kernel/cap-router-builder.ts
+/**
+* Runtime cap-router builder (BIG PLAN 2).
+*
+* Builds the per-capability tRPC routers DYNAMICALLY at hub boot by
+* iterating `ALL_CAPABILITY_DEFINITIONS`, instead of importing the
+* statically codegen'd `createCapRouter_<Cap>` value functions baked into
+* `@camstack/server`. Moving the CONSTRUCTION here means a capability
+* update ships via the framework plugin (`@camstack/types` +
+* `@camstack/system`, live-updated together) WITHOUT a `@camstack/server`
+* image rebuild.
+*
+* Type vs value split:
+*   - The runtime VALUE is built here, generically.
+*   - The static AppRouter TYPE stays codegen'd into `@camstack/types`
+*     (`generated/addon-api.ts`) via the `generated-cap-routers.ts`
+*     per-cap router factory TYPES. The server delegation site assigns
+*     this builder's output to that static type at the single documented
+*     boundary, so the SDK keeps full procedure inference.
+*
+* Behaviour MUST stay byte-identical to the codegen output
+* (`scripts/generate-cap-routers.ts`). The per-method procedure shape is
+* mechanically derived from each `cap.methods.*` (input/output zod schema
+* + kind) + the auto-injected `getStatus` / 3 settings-contribution
+* methods (via `expandCapMethods`). Provider resolution is derived from
+* the declarative `mount` hint (`resolveCapMount`) — the same decision the
+* codegen `generate-cap-mounts.ts` baked in.
+*
+* This module owns NO tRPC primitives of its own: `@camstack/system`
+* cannot import the server's `TrpcContext`-bound procedures. The server
+* passes them in via {@link CapRouterPrimitives} (the `t` half of the
+* `buildCapRouters(t, services)` contract), keeping the kernel free of any
+* backend coupling (self-sufficiency invariant).
+*/
+/** Auth level → procedure key. Mirrors codegen's AUTH_PROCEDURE_MAP. */
+function procedureKeyFor(auth) {
+	if (auth === "public") return "public";
+	if (auth === "admin" || auth === "superAdmin") return "admin";
+	return "protected";
+}
+/** Zod schema is `z.void()` — input carries no data. Mirrors codegen's isVoidInput. */
+function isVoidInput(schema) {
+	const def = schema._def;
+	return schema.constructor?.name === "ZodVoid" || def?.type === "void" || def?.typeName === "ZodVoid";
+}
+/** Zod schema is `z.object()` — supports `.loose()` for nodeId passthrough. Mirrors codegen's isObjectInput. */
+function isObjectInput(schema) {
+	const def = schema._def;
+	return schema.constructor?.name === "ZodObject" || def?.type === "object" || def?.typeName === "ZodObject";
+}
+/**
+* Apply `.loose()` to an object input schema when available (Zod 4) so the
+* router accepts the out-of-band `nodeId` / `addonId` selector keys
+* without stripping them — matching the codegen's `.input(schema.loose())`.
+* Falls back to the schema unchanged when `.loose()` is absent.
+*/
+function looseSchema(schema) {
+	const loose = schema.loose;
+	return typeof loose === "function" ? loose.call(schema) : schema;
+}
+function methodsFor(def) {
+	const effective = (0, _camstack_types.expandCapMethods)(def);
+	return Object.entries(effective).map(([name, schema]) => {
+		const m = schema;
+		return {
+			name,
+			kind: m.kind ?? "query",
+			auth: m.auth ?? "protected",
+			schema: m,
+			isVoid: isVoidInput(m.input),
+			isObject: isObjectInput(m.input)
+		};
+	});
+}
+/** Strip a set of selector keys from an input object, returning a NEW object. */
+function stripKeys(input, keys) {
+	const src = input ?? {};
+	const rest = {};
+	const picked = {};
+	for (const [k, v] of Object.entries(src)) if (keys.includes(k)) picked[k] = v;
+	else rest[k] = v;
+	return {
+		rest,
+		picked
+	};
+}
+/**
+* Resolve the provider object for a NON-void/object method call, applying
+* the same local-first → remote-proxy routing the codegen's
+* `resolveProvider` does. `nodeId` undefined / `'hub'` resolves the local
+* provider; otherwise it crosses to the named node via the proxy.
+*/
+function resolveProviderForCall(capName, nodeId, getLocal, services) {
+	if (!nodeId || nodeId === "hub") {
+		const local = getLocal();
+		if (local !== null && local !== void 0) return local;
+		const proxy = services.remoteProxy(capName, "hub");
+		if (proxy) return proxy;
+		return services.noProvider(capName);
+	}
+	const proxy = services.remoteProxy(capName, nodeId);
+	if (!proxy) return services.noProvider(capName, nodeId);
+	return proxy;
+}
+/** Require a local provider (singleton-style, no node routing) or raise. */
+function requireLocal(capName, getLocal, services) {
+	const p = getLocal();
+	if (p === null || p === void 0) return services.noProvider(capName);
+	return p;
+}
+/**
+* Build a single capability's router (the runtime equivalent of one
+* codegen'd `createCapRouter_<Cap>`). Each method becomes a typed
+* procedure with the SAME routing branch the codegen emits.
+*/
+function buildOneCapRouter(def, primitives, services) {
+	const capName = def.name;
+	const mount = (0, _camstack_types.resolveCapMount)(def);
+	const isCollection = mount.kind === "collection";
+	const nodeIdData = def.nodeIdMode === "data";
+	const procedures = {};
+	const getLocal = (ctx, addonId) => services.getLocalProvider(capName, mount.kind, ctx, addonId);
+	for (const method of methodsFor(def)) {
+		const base = primitives.procedures[procedureKeyFor(method.auth)];
+		const inputSchema = method.schema.input;
+		const outputSchema = method.schema.output;
+		if (method.kind === "subscription") {
+			procedures[method.name] = base.input(inputSchema).subscription(({ input, ctx }) => {
+				const provider = requireLocal(capName, () => getLocal(ctx), services);
+				return primitives.iterableSubscription((push) => {
+					const fn = provider[method.name];
+					const unsub = fn?.(input, push);
+					return typeof unsub === "function" ? unsub : () => {};
+				});
+			});
+			continue;
+		}
+		const procKind = method.kind === "mutation" ? "mutation" : "query";
+		if (method.isVoid) {
+			const voidSelector = isCollection ? zod.z.object({
+				nodeId: zod.z.string().optional(),
+				addonId: zod.z.string().optional()
+			}).optional() : zod.z.object({ nodeId: zod.z.string().optional() }).optional();
+			procedures[method.name] = base.input(voidSelector).output(outputSchema)[procKind](({ input, ctx }) => {
+				const sel = input ?? {};
+				return (nodeIdData ? requireLocal(capName, () => getLocal(ctx, isCollection ? sel.addonId : void 0), services) : resolveProviderForCall(capName, sel.nodeId, () => getLocal(ctx, isCollection ? sel.addonId : void 0), services))[method.name]?.();
+			});
+			continue;
+		}
+		if (method.isObject) {
+			const schema = nodeIdData ? inputSchema : looseSchema(inputSchema);
+			procedures[method.name] = base.input(schema).output(outputSchema)[procKind](({ input, ctx }) => {
+				if (nodeIdData) return requireLocal(capName, () => getLocal(ctx), services)[method.name]?.(input);
+				if (isCollection) {
+					const { rest, picked } = stripKeys(input, ["nodeId", "addonId"]);
+					const nodeId = typeof picked.nodeId === "string" ? picked.nodeId : void 0;
+					const addonId = typeof picked.addonId === "string" ? picked.addonId : void 0;
+					return resolveProviderForCall(capName, nodeId, () => getLocal(ctx, addonId), services)[method.name]?.(rest);
+				}
+				const { rest, picked } = stripKeys(input, ["nodeId"]);
+				return resolveProviderForCall(capName, typeof picked.nodeId === "string" ? picked.nodeId : void 0, () => getLocal(ctx), services)[method.name]?.(rest);
+			});
+			continue;
+		}
+		procedures[method.name] = base.input(inputSchema).output(outputSchema)[procKind](({ input, ctx }) => {
+			return requireLocal(capName, () => getLocal(ctx), services)[method.name]?.(input);
+		});
+	}
+	return primitives.router(procedures);
+}
+/** kebab-case → camelCase, matching the codegen router-map key naming. */
+function kebabToCamel(s) {
+	return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+/**
+* Mount kinds the runtime builder constructs. `service-backed` IS built
+* (the server supplies the provider via `getLocalProvider`); `custom` and
+* `skip` are NOT (the server's hand-written override fills the slot for
+* `custom`; `skip` is never mounted). `hub-only` is built but its remote
+* leg is `null` — handled by the server's `remoteProxy` returning null for
+* that cap.
+*/
+function isBuilderMounted(kind) {
+	return kind !== "custom" && kind !== "skip";
+}
+/**
+* Build the runtime cap-router map: `{ <camelCapName>: <router> }` for
+* every capability the builder owns. Caps with `mount.kind` `custom` /
+* `skip` are omitted (the server overrides / never mounts them). The
+* server spreads this BEFORE its hand-written overrides + core routers so
+* override-by-spread precedence is preserved.
+*/
+function buildCapRouters(primitives, services) {
+	const out = {};
+	for (const def of _camstack_types.ALL_CAPABILITY_DEFINITIONS) {
+		if (!isBuilderMounted((0, _camstack_types.resolveCapMount)(def).kind)) continue;
+		const effective = (0, _camstack_types.expandCapMethods)(def);
+		if (Object.keys(effective).length === 0) continue;
+		out[kebabToCamel(def.name)] = buildOneCapRouter(def, primitives, services);
+	}
+	return out;
+}
+/** The set of cap camelNames the builder owns (for drift checks / tests). */
+function builderMountedCapNames() {
+	const names = [];
+	for (const def of _camstack_types.ALL_CAPABILITY_DEFINITIONS) {
+		if (!isBuilderMounted((0, _camstack_types.resolveCapMount)(def).kind)) continue;
+		if (Object.keys((0, _camstack_types.expandCapMethods)(def)).length === 0) continue;
+		names.push(kebabToCamel(def.name));
+	}
+	return names;
+}
+//#endregion
 //#region src/kernel/provider-kind-drift.ts
 /**
 * Compare a runtime registration hint against the authoritative cap
@@ -93094,11 +93307,13 @@ Object.defineProperty(exports, "buildBinaryPath", {
 		return _camstack_types_node.buildBinaryPath;
 	}
 });
+exports.buildCapRouters = buildCapRouters;
 exports.buildLinkChain = require_manifest_python_deps.buildLinkChain;
 exports.buildNativeCapProxy = require_manifest_python_deps.buildNativeCapProxy;
 exports.buildNodeManifest = buildNodeManifest;
 exports.buildStorageLocationRegistry = buildStorageLocationRegistry;
 exports.buildUdsNativeCapProxy = require_manifest_python_deps.buildUdsNativeCapProxy;
+exports.builderMountedCapNames = builderMountedCapNames;
 exports.callRegisterNodeWithRetry = callRegisterNodeWithRetry;
 exports.callWithServiceDiscovery = require_manifest_python_deps.callWithServiceDiscovery;
 exports.capActionName = require_manifest_python_deps.capActionName;