@smartspectra/node-sdk 3.5.0-rc.2 → 3.5.0-rc.3

package/README.md

@@ -14,6 +14,7 @@ no native addon, no `binding.gyp`, no `electron-rebuild`, no `node-gyp`.
 
 - Electron sample: [electron-quickstart](https://github.com/Presage-Security/SmartSpectra/tree/main/nodejs/samples/electron-quickstart)
 - API reference: <https://smartspectra.presagetech.com/docs/nodejs/api-reference>
+- Device compatibility: [configured checks and diagnostic results](docs/device-compatibility.md)
 - Metrics guide: <https://smartspectra.presagetech.com/docs/nodejs/metrics>
 
 ## Architecture

package/docs/device-compatibility.md

@@ -0,0 +1,31 @@
+---
+title: Node.js Device Compatibility
+description: Check the configured SDK and return a verdict, actionable reason, and diagnostic JSON.
+---
+
+# Node.js Device Compatibility
+
+> **Important:** SDK metrics are offered for general wellness and informational purposes only. SDK metrics have not been cleared by the FDA and may not be used for medical diagnosis or treatment.
+
+After configuring the SDK's authentication, metrics, and camera, call:
+
+```javascript
+const verdict = await sdk.isDeviceCompatible();
+```
+
+Compare the returned verdict explicitly, for example `verdict === 'ready'`.
+Every verdict string is truthy, including `'blocked'`; do not use it as a Boolean. Call `sdk.getDeviceCompatibilityResult()`
+for the saved explanation and diagnostic JSON. The getter is empty before or during
+a check and after an exception; starting a new check clears the previous result. There is no separate configuration input
+or public policy/timing override. The check uses the SDK's configured workload,
+keeps its settings unchanged, and rejects competing measurement operations.
+
+The selected camera supplies capture pacing; bundled reference imagery replaces
+captured pixels. Stable checks may finish after 20 seconds of observation;
+otherwise observation continues to approximately 30 seconds. Setup and cleanup
+add time. File/custom-frame inputs are currently Inconclusive with an explanation.
+
+Await the result; the check does not block the JavaScript event loop.
+
+See [Device Compatibility Results and Recovery](../../docs/device-compatibility-experience.md)
+for complete setup, verdict meanings, execution safety, and JSON export examples.

package/js/constants.js

@@ -80,6 +80,7 @@ const SmartSpectraErrorCode = Object.freeze({
     kFrameConversionFailed: 9,
     kNonMonotonicTimestamp: 10,
     kTimestampGap:          11,
+    kMetricNotAuthorized:   13,
 });
 
 // Spatial transform applied to each pushed frame before it enters the

package/js/device-compatibility.js

@@ -0,0 +1,371 @@
+// Copyright (C) 2026 Presage Technologies, Inc.
+// SPDX-License-Identifier: LicenseRef-Proprietary
+'use strict';
+const koffi = require('koffi');
+const { readinessLibrary, ensurePreconfigured } = require('./ffi');
+let native;
+let typesRegistered = false;
+function unsupported() {
+    const error = new Error('This native SDK does not support device readiness ABI v8.');
+    error.code = 'unsupported_capability';
+    return error;
+}
+function getNative() {
+    if (native) return native;
+    const lib = readinessLibrary();
+    try {
+        if (lib.func('int smartspectra_readiness_abi_version(void)')() !== 8) throw unsupported();
+    } catch { throw unsupported(); }
+    if (!typesRegistered) {
+        koffi.struct('smartspectra_readiness_requirement_t', {
+            metric_id: 'int',
+            minimum_samples: 'uint64_t',
+            minimum_output_hz: 'double',
+            output_required: 'int',
+        });
+        koffi.struct('smartspectra_readiness_policy_t', {
+            version: 'const char*',
+            rationale: 'const char*',
+            input_mode: 'const char*',
+            frame_width: 'int',
+            frame_height: 'int',
+            target_fps: 'double',
+            minimum_throughput_fps: 'double',
+            minimum_duration_us: 'uint64_t',
+            metrics: 'const smartspectra_readiness_requirement_t*',
+            metrics_len: 'size_t',
+            early_window_us: 'uint64_t',
+            early_stable_windows: 'uint32_t',
+            early_minimum_headroom: 'double',
+            uncertainty_fraction: 'double',
+        });
+        koffi.struct('smartspectra_readiness_request_t', {
+            struct_size: 'uint32_t',
+            reserved_opt_in: 'int',
+            authentication_prepared: 'int',
+            scope: 'int',
+            camera_permission: 'int',
+            camera_index: 'int',
+            camera_width: 'int',
+            camera_height: 'int',
+            camera_fps: 'int',
+            frame_width: 'int',
+            frame_height: 'int',
+            target_fps: 'double',
+            duration_us: 'uint64_t',
+            maximum_wait_us: 'uint64_t',
+            cleanup_reserve_us: 'uint64_t',
+            reference_bgr_frame: 'const uint8_t*',
+            reference_bgr_frame_len: 'size_t',
+            policy: 'smartspectra_readiness_policy_t',
+            camera_selection_kind: 'int', camera_selection_id: 'const char*',
+        });
+        koffi.struct('smartspectra_readiness_progress_t', {
+            phase: 'int',
+            timing_available: 'int',
+            elapsed_us: 'uint64_t',
+            has_deadline: 'int',
+            remaining_us: 'uint64_t',
+        });
+        koffi.struct('smartspectra_readiness_result_t', {
+            verdict: 'int', reason: 'const char*', diagnostics: 'const char*',
+        });
+        typesRegistered = true;
+    }
+    native = {
+        referencePolicy: lib.func('int smartspectra_readiness_reference_policy(int workload, int scope, _Out_ smartspectra_readiness_policy_t *out)'),
+        fallbackPolicy: lib.func('int smartspectra_readiness_fallback_policy(const smartspectra_readiness_policy_t *policy, int verdict, int reason, _Out_ smartspectra_readiness_policy_t *out)'),
+        policy: lib.func('int smartspectra_readiness_chest_policy(_Out_ smartspectra_readiness_policy_t *out)'),
+        create: lib.func('void *smartspectra_readiness_create(void)'),
+        reserve: lib.func('int smartspectra_readiness_reserve(void *service)'),
+        destroy: lib.func('void smartspectra_readiness_destroy(void *service)'),
+        start: lib.func('void *smartspectra_readiness_start(void *service, const smartspectra_config_t *config, const smartspectra_readiness_request_t *request)'),
+        cancel: lib.func('void smartspectra_readiness_cancel(void *check)'),
+        background: lib.func('void smartspectra_readiness_background(void *check)'),
+        progress: lib.func('int smartspectra_readiness_progress(void *check, _Out_ smartspectra_readiness_progress_t *out)'),
+        poll: lib.func('int smartspectra_readiness_poll(void *check, _Out_ smartspectra_readiness_result_t *out)'),
+        free: lib.func('void smartspectra_readiness_check_free(void *check)'),
+    };
+    return native;
+}
+const verdicts = ['ready', 'limited', 'blocked', 'inconclusive'];
+const reasons = ['qualified', 'performance_below_policy', 'invalid_configuration',
+    'authentication_required', 'authorization_denied', 'input_unavailable', 'setup_failed',
+    'run_incomplete', 'insufficient_evidence', 'policy_unavailable', 'backend_unknown',
+    'configuration_changed', 'cancelled', 'deadline_exceeded', 'application_backgrounded',
+    'busy', 'camera_interrupted', 'permission_required', 'permission_denied',
+    'borderline_performance', 'experimental_opt_in_required', 'unsupported_capability'];
+const actions = ['proceed', 'retry', 'authenticate', 'obtain_authorization', 'correct_configuration',
+    'supply_policy', 'reduce_workload', 'collect_evidence', 'inspect_backend', 'release_session',
+    'restore_input', 'grant_permission', 'return_to_foreground', 'resolve_setup',
+    'enable_experimental', 'choose_supported_workload'];
+const phases = ['preparing', 'running', 'cleaning_up', 'finalizing'];
+const scopes = ['reference_frame', 'camera_paced_reference_frame'];
+const permissions = ['unknown', 'granted', 'denied'];
+const booleanFields = new Set(['output_required', 'retryable', 'message_truncated', 'available', 'has_deadline', 'phases_available', 'timing_available',
+    'authorization_complete', 'backend_coverage_complete', 'input_validated',
+    'camera_geometry_changed', 'workload_completed', 'early_completion_requested']);
+function fields(object) {
+    return Object.fromEntries(Object.entries(object).map(([key, value]) => [
+        key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase()),
+        booleanFields.has(key) ? !!value : typeof value === 'bigint' ? Number(value) : value,
+    ]));
+}
+function array(pointer, type, length) {
+    return Number(length) ? Array.from(koffi.decode(pointer, koffi.array(type, Number(length)))) : [];
+}
+function policyFromNative(p) {
+    const { metrics, metrics_len, early_window_us, early_stable_windows,
+        early_minimum_headroom, ...rest } = p;
+    return { ...fields(rest),
+        metrics: array(metrics, 'smartspectra_readiness_requirement_t', metrics_len).map(fields),
+        earlyCompletion: { windowUs: Number(early_window_us), stableWindows: early_stable_windows,
+            minimumHeadroom: early_minimum_headroom } };
+}
+function freeze(value) {
+    if (value && typeof value === 'object') {
+        Object.values(value).forEach(freeze);
+        Object.freeze(value);
+    }
+    return value;
+}
+function resultFromNative(r) {
+    return freeze({ verdict: verdicts[r.verdict], reason: r.reason, diagnostics: r.diagnostics });
+}
+
+function number(value, fallback, name, integer = false, min = -Infinity, max = Infinity) {
+    const result = value === undefined ? fallback : value;
+    if (typeof result !== 'number' || !Number.isFinite(result) ||
+        (integer && !Number.isSafeInteger(result)) || result < min || result > max)
+        throw new TypeError(`${name} must be a finite ${integer ? 'integer' : 'number'} in range.`);
+    return result;
+}
+const int = (v, d, n) => number(v, d, n, true, -2147483648, 2147483647);
+const us = (v, d, n) => number(v, d, n, true, 0, Number.MAX_SAFE_INTEGER);
+function string(value, fallback, name) {
+    const result = value === undefined ? fallback : value;
+    if (typeof result !== 'string' || result.includes('\0')) throw new TypeError(`${name} must be a string without NUL.`);
+    return result;
+}
+function flag(value, fallback, name) {
+    if (value === undefined) return +fallback;
+    if (typeof value !== 'boolean') throw new TypeError(`${name} must be boolean.`);
+    return +value;
+}
+function choice(value, fallback, choices, name) {
+    const index = choices.indexOf(value ?? fallback);
+    if (index < 0) throw new TypeError(`Unsupported ${name}.`);
+    return index;
+}
+function policyToNative(p = {}) {
+    const early = p.earlyCompletion ?? {};
+    if (!Array.isArray(p.metrics ?? [])) throw new TypeError('policy.metrics must be an array.');
+    return {
+        version: string(p.version, '', 'policy.version'), rationale: string(p.rationale, '', 'policy.rationale'),
+        input_mode: string(p.inputMode, '', 'policy.inputMode'),
+        frame_width: int(p.frameWidth, 0, 'policy.frameWidth'), frame_height: int(p.frameHeight, 0, 'policy.frameHeight'),
+        target_fps: number(p.targetFps, 0, 'policy.targetFps'),
+        minimum_throughput_fps: number(p.minimumThroughputFps, 0, 'policy.minimumThroughputFps'),
+        minimum_duration_us: us(p.minimumDurationUs, 0, 'policy.minimumDurationUs'),
+        metrics: (p.metrics ?? []).map(m => ({ metric_id: int(m.metricId, 0, 'metricId'),
+            minimum_samples: us(m.minimumSamples, 2, 'minimumSamples'),
+            minimum_output_hz: number(m.minimumOutputHz, 0, 'minimumOutputHz'),
+            output_required: flag(m.outputRequired, true, 'outputRequired') })),
+        metrics_len: (p.metrics ?? []).length,
+        early_window_us: us(early.windowUs, 0, 'earlyCompletion.windowUs'),
+        early_stable_windows: number(early.stableWindows, 0, 'earlyCompletion.stableWindows', true, 0, 4294967295),
+        early_minimum_headroom: number(early.minimumHeadroom, 0, 'earlyCompletion.minimumHeadroom'),
+        uncertainty_fraction: number(p.uncertaintyFraction, 0, 'policy.uncertaintyFraction'),
+    };
+}
+function requestToNative(request) {
+    const frame = request.referenceBgrFrame ?? Buffer.alloc(0);
+    if (!(frame instanceof Uint8Array)) throw new TypeError('referenceBgrFrame must be a Buffer or Uint8Array.');
+    const camera = request.camera ?? {};
+    return {
+        struct_size: koffi.sizeof('smartspectra_readiness_request_t'),
+        reserved_opt_in: 0,
+        authentication_prepared: flag(request.authenticationPrepared, false, 'authenticationPrepared'),
+        scope: choice(request.scope, 'camera_paced_reference_frame', scopes, 'scope'),
+        camera_permission: choice(request.cameraPermission, 'unknown', permissions, 'cameraPermission'),
+        camera_index: int(camera.deviceIndex, 0, 'camera.deviceIndex'),
+        camera_width: int(camera.preferredWidth, 1280, 'camera.preferredWidth'),
+        camera_height: int(camera.preferredHeight, 720, 'camera.preferredHeight'),
+        camera_fps: int(camera.preferredFps, 30, 'camera.preferredFps'),
+        frame_width: int(request.frameWidth, 1280, 'frameWidth'),
+        frame_height: int(request.frameHeight, 720, 'frameHeight'),
+        target_fps: number(request.targetFps, 30, 'targetFps'),
+        duration_us: us(request.durationUs, 30000000, 'durationUs'),
+        maximum_wait_us: us(request.maximumWaitUs, 40000000, 'maximumWaitUs'),
+        cleanup_reserve_us: us(request.cleanupReserveUs, 5000000, 'cleanupReserveUs'),
+        reference_bgr_frame: frame, reference_bgr_frame_len: frame.byteLength,
+        policy: policyToNative(request.policy),
+        camera_selection_kind: request.cameraSelection ? choice(request.cameraSelection.kind, '', ['default', 'front', 'back', 'byId'], 'cameraSelection.kind') : -1,
+        camera_selection_id: request.cameraSelection?.id ?? null,
+    };
+}
+function configurationToNative(config) {
+    const metrics = config.requestedMetrics ?? [];
+    if (!Array.isArray(metrics)) throw new TypeError('requestedMetrics must be an array.');
+    const requested = Int32Array.from(metrics.map(m => int(m, 0, 'requested metric')));
+    return { api_key: string(config.apiKey, '', 'apiKey'), requested_metrics: requested,
+        requested_metrics_len: requested.length,
+        enable_accumulated_output: flag(config.enableAccumulatedOutput, false, 'enableAccumulatedOutput'),
+        log_level: config.logLevel === undefined ? 0 : number(config.logLevel, 0, 'logLevel', true, 0, 4) + 1,
+        struct_size: koffi.sizeof('smartspectra_config_t'),
+        disable_telemetry: 1 - flag(config.enableTelemetry, true, 'enableTelemetry'), reserved0: 0 };
+}
+function progressFromNative(n, handle) {
+    const progress = {};
+    if (n.progress(handle, progress) !== 0) throw new Error('Unable to read native readiness progress.');
+    return freeze({ ...fields(progress), phase: phases[progress.phase] });
+}
+class DeviceCompatibilityCheck {
+    #handle; #native; #progress; #value; #promise;
+    constructor(n, handle, signal, finished) {
+        this.#native = n;
+        this.#handle = handle;
+        this.#progress = freeze({ phase: 'preparing', timingAvailable: false, elapsedUs: 0,
+            hasDeadline: false, remainingUs: 0 });
+        const abort = () => this.cancel();
+        let timer;
+        this.#promise = new Promise((resolve, reject) => {
+            const tick = () => {
+                try {
+                    this.#progress = progressFromNative(n, handle);
+                    const result = {};
+                    const status = n.poll(handle, result);
+                    if (status === 0) return;
+                    if (status !== 1) throw new Error('Unable to read native readiness result.');
+                    this.#value = resultFromNative(result);
+                    resolve(this.#value);
+                } catch (error) { reject(error); }
+                clearInterval(timer);
+                // A user-overridden listener method must not prevent native
+                // handle cleanup or leave close() waiting on an abandoned check.
+                try { signal?.removeEventListener('abort', abort); } catch {}
+                try { n.free(handle); }
+                finally { this.#handle = null; finished(this); }
+            };
+            // Referenced timer retains the event loop until native cleanup and
+            // result copying finish, even if the caller only awaits result.
+            timer = setInterval(tick, 25);
+        });
+        // Keep ignored result promises from becoming unhandled rejections.
+        this.#promise.catch(() => {});
+        try {
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted) this.cancel();
+        } catch (error) {
+            clearInterval(timer);
+            try { signal?.removeEventListener('abort', abort); } catch {}
+            this.#handle = null;
+            throw error; // start() still owns the native handle on this path.
+        }
+    }
+    get result() { return this.#promise; }
+    poll() { return this.#value; }
+    progress() {
+        if (this.#handle) this.#progress = progressFromNative(this.#native, this.#handle);
+        return this.#progress;
+    }
+    cancel() { if (this.#handle) this.#native.cancel(this.#handle); }
+    applicationBackgrounded() { if (this.#handle) this.#native.background(this.#handle); }
+}
+const services = new FinalizationRegistry(({ n, handle }) => {
+    // Best effort for abandoned services; explicit close() is deterministic.
+    n.destroy.async(handle, () => {});
+});
+class DeviceCompatibilityService {
+    static async run(configuration = {}) {
+        const service = new DeviceCompatibilityService();
+        try { return await service.check(configuration).result; }
+        finally { await service.close(); }
+    }
+    #native; #handle; #checks = new Set(); #closing;
+    constructor() {
+        this.#native = getNative();
+        ensurePreconfigured();
+        this.#handle = this.#native.create();
+        if (!this.#handle) throw new Error('Unable to create native readiness service.');
+        services.register(this, { n: this.#native, handle: this.#handle }, this);
+    }
+    reserve() {
+        if (!this.#handle || this.#closing) throw new Error('Compatibility service is closed.');
+        const result = this.#native.reserve(this.#handle);
+        if (result < 0) throw new Error('Unable to reserve SDK state.');
+        return result === 1;
+    }
+    check(configuration, referenceBgrFrame = undefined, workload = 'full', scope = 'camera_paced_reference_frame') {
+        const policy = DeviceCompatibilityPolicies.reference720p30(workload, scope);
+        return this.start({ ...configuration, requestedMetrics: policy.metrics.map(m => m.metricId) }, {
+            referenceBgrFrame, policy, scope, authenticationPrepared: !!configuration?.apiKey,
+        });
+    }
+    start(configuration = {}, request = {}) {
+        if (!this.#handle || this.#closing) throw new Error('Readiness service is closed.');
+        const signal = request.signal;
+        if (signal !== undefined && !(signal instanceof AbortSignal))
+            throw new TypeError('signal must be an AbortSignal.');
+        if (signal?.aborted) throw new DOMException('Readiness was aborted before submission.', 'AbortError');
+        const config = configurationToNative(configuration);
+        const input = requestToNative(request);
+        // Configuration/request getters can call close() during conversion.
+        if (!this.#handle || this.#closing) throw new Error('Readiness service is closed.');
+        const handle = this.#native.start(this.#handle, config, input);
+        if (!handle) throw new Error('Unable to submit native readiness request.');
+        let check;
+        try {
+            check = new DeviceCompatibilityCheck(this.#native, handle, signal, value => this.#checks.delete(value));
+        } catch (error) {
+            try { this.#native.cancel(handle); }
+            finally { this.#native.free(handle); }
+            throw error;
+        }
+        this.#checks.add(check);
+        return check;
+    }
+    close() {
+        if (this.#closing) return this.#closing;
+        const checks = [...this.#checks];
+        checks.forEach(check => check.cancel());
+        this.#closing = Promise.allSettled(checks.map(check => check.result)).then(() => new Promise((resolve, reject) => {
+            const handle = this.#handle;
+            this.#handle = null;
+            services.unregister(this);
+            this.#native.destroy.async(handle, error => error ? reject(error) : resolve());
+        }));
+        return this.#closing;
+    }
+}
+const DeviceCompatibilityPolicies = Object.freeze({
+    reference720p30(workload = 'full', scope = 'camera_paced_reference_frame') {
+        const tier = choice(workload, 'full', ['breathing_pulse_eda', 'breathing_pulse', 'breathing', 'full'], 'workload');
+        const policy = {};
+        if (getNative().referencePolicy(tier, choice(scope, 'camera_paced_reference_frame', scopes, 'scope'), policy) !== 0) throw new Error('Unable to read native readiness policy.');
+        return freeze(policyFromNative(policy));
+    },
+    fallback(result) {
+        const policy = {};
+        const status = getNative().fallbackPolicy(policyToNative(result.policy),
+            choice(result.qualification.verdict, '', verdicts, 'verdict'),
+            choice(result.qualification.reason, '', reasons, 'reason'), policy);
+        if (status === 1) return undefined;
+        if (status !== 0) throw new Error('Unable to read native fallback policy.');
+        return freeze(policyFromNative(policy));
+    },
+    chestTraceReference720p30() {
+        const policy = {};
+        if (getNative().policy(policy) !== 0) throw new Error('Unable to read native readiness policy.');
+        return freeze(policyFromNative(policy));
+    },
+});
+function deviceCompatibilityAvailable() { try { getNative(); return true; } catch { return false; } }
+module.exports = { DeviceCompatibilityService, DeviceCompatibilityPolicies, deviceCompatibilityAvailable, busyResult };
+
+// A rejected busy check has no measurement evidence. Keep the full result shape.
+function busyResult() {
+    return freeze({ verdict: 'inconclusive',
+        reason: 'The SDK is busy. Wait for the current SDK operation to finish.',
+        diagnostics: JSON.stringify({ reason: 'busy', workloadCompleted: false }) });
+}

package/js/ffi.js

@@ -17,9 +17,9 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const koffi = require('koffi');
-const { resolveNativeLibrary } = require('./resolve-native');
+const { loadNativeLibrary } = require('./resolve-native');
 
-const lib = koffi.load(resolveNativeLibrary());
+const lib = loadNativeLibrary(koffi);
 
 // ---------------------------------------------------------------------------
 // Type declarations — mirror smartspectra_capi.h
@@ -648,4 +648,5 @@ module.exports = {
     availableCameras,
     preconfigure,
     ensurePreconfigured,
+    readinessLibrary: () => lib,
 };

package/js/index.d.ts

@@ -76,6 +76,8 @@ export declare const SmartSpectraErrorCode: {
     readonly kFrameConversionFailed: 9;
     readonly kNonMonotonicTimestamp: 10;
     readonly kTimestampGap:          11;
+    /** Requested metric is not authorized for this API key. */
+    readonly kMetricNotAuthorized:   13;
 };
 export type SmartSpectraErrorCodeValue = typeof SmartSpectraErrorCode[keyof typeof SmartSpectraErrorCode];
 
@@ -212,6 +214,10 @@ export interface CameraOptions {
  * ```
  */
 export declare class SmartSpectraSDK {
+    /** Device Compatibility uses this SDK's authentication. */
+    isDeviceCompatible(): Promise<DeviceCompatibilityVerdict>;
+    /** Latest completed result; undefined before/during a check or after an error. */
+    getDeviceCompatibilityResult(): DeviceCompatibilityResult | undefined;
     /** SDK package version. */
     static readonly version: string;
 
@@ -367,3 +373,13 @@ export declare function setMetricsClass(cls: unknown): void;
  * been registered via `setMetricsClass`, otherwise the raw Buffer.
  */
 export declare function decodeMetrics(buf: Buffer): unknown;
+
+/** Device Compatibility. Pin the JS and native SDK versions together. */
+/** Outcome for the configured SDK workload. */
+export type DeviceCompatibilityVerdict = 'ready' | 'limited' | 'blocked' | 'inconclusive';
+export interface DeviceCompatibilityResult {
+    readonly verdict: DeviceCompatibilityVerdict;
+    readonly reason: string;
+    /** Native JSON support report; detailed fields are not a stable typed API. */
+    readonly diagnostics: string;
+}

package/js/resolve-native.js

@@ -113,7 +113,37 @@ function resolveNativeLibrary() {
     return libPath;
 }
 
+// Koffi tries LoadLibraryW before its adjacent-DLL fallback. On Windows that
+// can successfully bind a packaged shim to an unrelated SDK DLL on PATH.
+// Preload the package with a scoped dependency search; do not change the
+// process-wide DLL directory or the explicit development override's behavior.
+function loadNativeLibrary(koffi) {
+    const filename = resolveNativeLibrary();
+    if (process.platform !== 'win32' || process.env.SMARTSPECTRA_CAPI_PATH) {
+        return koffi.load(filename);
+    }
+    const kernel32 = koffi.load('kernel32.dll');
+    try {
+        const load = kernel32.func('__stdcall', 'LoadLibraryExW', 'void *', ['str16', 'void *', 'uint32_t']);
+        const free = kernel32.func('__stdcall', 'FreeLibrary', 'int', ['void *']);
+        // LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | LOAD_LIBRARY_SEARCH_DEFAULT_DIRS
+        const handle = load(path.resolve(filename), null, 0x00000100 | 0x00001000);
+        if (!handle) {
+            throw new Error(`@smartspectra/node-sdk: could not load packaged runtime ${filename} and its adjacent DLLs`);
+        }
+        try {
+            // Koffi takes its own module reference and owns its lifetime from here.
+            return koffi.load(filename);
+        } finally {
+            free(handle);
+        }
+    } finally {
+        kernel32.unload();
+    }
+}
+
 module.exports = {
+    loadNativeLibrary,
     resolveNativeLibrary,
     // Exposed for diagnostics and tests.
     LIB_BASENAME,

package/js/smartspectra.js

@@ -39,6 +39,8 @@ const SUPPORTED_EVENTS = new Set([
 // FrameTransform object declared later.
 const DEFAULT_FRAME_TRANSFORM = 0;
 
+let compatibilityInFlight = false;
+
 class SmartSpectraSDK {
     /** SDK package version (matches `package.json#version`). */
     static get version() { return PACKAGE_VERSION; }
@@ -71,6 +73,8 @@ class SmartSpectraSDK {
         this._source = null;
         this._explicitCameraSelection = false;
         this._session = null;  // lazy: created on start()
+        this._compatibilityInFlight = false;
+
         this._destroyPromise = null;
     }
 
@@ -99,6 +103,7 @@ class SmartSpectraSDK {
      *   Spatial transform applied to every pushed frame.
      */
     useCustomInput(frameTransform = DEFAULT_FRAME_TRANSFORM) {
+        this._requireCompatibilityIdle();
         if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
         this._source = { kind: 'custom', frameTransform: frameTransform | 0 };
         return this;
@@ -119,6 +124,7 @@ class SmartSpectraSDK {
      * getUserMedia — use the renderer SDK's useMediaStream() there instead.
      */
     useCamera(selection = null, options = {}) {
+        this._requireCompatibilityIdle();
         const isSelection = selection !== null && typeof selection === 'object' && 'kind' in selection;
         if (!isSelection && arguments.length < 2) {
             if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
@@ -145,6 +151,7 @@ class SmartSpectraSDK {
      *   { timestampsPath?, interframeDelayMs?, startOffsetMs?, maxDurationMs?, frameTransform? }
      */
     useFile(videoPath, options = null) {
+        this._requireCompatibilityIdle();
         if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
         if (typeof videoPath !== 'string' || !videoPath) {
             throw new TypeError('useFile: videoPath must be a non-empty string');
@@ -160,6 +167,7 @@ class SmartSpectraSDK {
      * useCustomInput(), useCamera(), or useFile() first.
      */
     start() {
+        this._requireCompatibilityIdle();
         if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
         const source = this._source;
         if (!source) {
@@ -207,6 +215,7 @@ class SmartSpectraSDK {
      * Typed selection requires any pending stopAsync() to settle before reset.
      */
     reset() {
+        this._requireCompatibilityIdle();
         if (!this._session) return;
         this._session.reset(this._explicitCameraSelection);
         if (!this._explicitCameraSelection) this._source = null;
@@ -264,18 +273,93 @@ class SmartSpectraSDK {
      * replacement session, since SDK state is process-global.
      */
     destroy() {
-        if (this._destroyPromise) return this._destroyPromise;
-        if (!this._session) return Promise.resolve();
-        const teardown = this._session.destroy();
-        this._session = null;
-        this._source = null;
-        this._destroyPromise = Promise.resolve(teardown).finally(() => { this._destroyPromise = null; });
-        return this._destroyPromise;
+        try {
+            if (this._destroyPromise) return this._destroyPromise;
+            // An unrelated, unused SDK owns no native state to tear down.
+            if (!this._session && !this._compatibilityInFlight) return Promise.resolve();
+            this._requireCompatibilityIdle();
+            const teardown = this._session.destroy();
+            this._session = null;
+            this._source = null;
+            this._destroyPromise = Promise.resolve(teardown).finally(() => { this._destroyPromise = null; });
+            return this._destroyPromise;
+        } catch (error) {
+            return Promise.reject(error);
+        }
+    }
+
+    async isDeviceCompatible() {
+        if (this._compatibilityResultPending) return 'inconclusive';
+        this._compatibilityResult = undefined;
+        this._compatibilityResultPending = true;
+        try {
+            const result = await this._runDeviceCompatibility();
+            this._compatibilityResult = Object.freeze({ ...result });
+            return result.verdict;
+        } finally { this._compatibilityResultPending = false; }
+    }
+
+    getDeviceCompatibilityResult() { return this._compatibilityResult; }
+
+    async _runDeviceCompatibility() {
+        const { DeviceCompatibilityService, DeviceCompatibilityPolicies } = require('./device-compatibility');
+        const selected = { ...this._options,
+            requestedMetrics: [...(this._options.requestedMetrics?.length
+                ? this._options.requestedMetrics : defaultSupportedMetrics)] };
+        const source = this._source;
+        const preflight = (code, reason) => Object.freeze({ verdict: 'inconclusive', reason,
+            diagnostics: JSON.stringify({ sdkVersion: PACKAGE_VERSION, schemaVersion: 1, reason: code,
+                reasonName: code, verdictName: 'inconclusive',
+                requestedMetrics: selected.requestedMetrics, input: source?.kind ?? 'unconfigured',
+                workloadCompleted: false, observationUs: 0, framesAttempted: 0,
+                performanceChecks: [], metricOutputs: [], timing: { available: false } }) });
+        const busy = () => preflight('busy', 'The SDK is busy. Wait for the current SDK operation to finish.');
+        if (compatibilityInFlight || this._compatibilityInFlight || this._destroyPromise)
+            return busy();
+        const status = this.processingStatus;
+        if (status === ProcessingStatus.kError) return preflight('reset_required',
+            'The SDK is in an error state. Resolve the previous error, reset the SDK, and retry the compatibility check.');
+        if (![ProcessingStatus.kUninitialized, ProcessingStatus.kIdle].includes(status)) return busy();
+        if (source?.kind !== 'camera') return preflight('unsupported_input',
+            'Select a camera before checking compatibility. File and custom-frame inputs are not yet supported; no device capacity verdict was established.');
+        this._compatibilityInFlight = true;
+        compatibilityInFlight = true;
+        let service;
+        try {
+            const capture = source.options ?? {};
+            const request = { authenticationPrepared: !!selected.apiKey,
+                cameraSelection: source.selection && { ...source.selection },
+                camera: { deviceIndex: capture.deviceIndex ?? 0,
+                    preferredWidth: capture.width || 1280, preferredHeight: capture.height || 720,
+                    preferredFps: capture.fps || 30 },
+                frameWidth: capture.width || 1280, frameHeight: capture.height || 720, targetFps: capture.fps || 30 };
+            const policy = DeviceCompatibilityPolicies.reference720p30('full');
+            const metrics = new Set(selected.requestedMetrics);
+            request.policy = { ...policy, frameWidth: request.frameWidth, frameHeight: request.frameHeight,
+                targetFps: request.targetFps, metrics: policy.metrics.filter(metric => metrics.has(metric.metricId)) };
+            if (this._session) {
+                await this._session.destroy();
+                this._session = null;
+            }
+            service = new DeviceCompatibilityService();
+            if (!service.reserve()) return busy();
+            return await service.start(selected, request).result;
+        } finally {
+            try { if (service) await service.close(); }
+            finally { this._compatibilityInFlight = false; compatibilityInFlight = false; }
+        }
+    }
+
+    _requireCompatibilityIdle() {
+        if (compatibilityInFlight || this._compatibilityInFlight) throw Object.assign(new Error('Device compatibility is running'), {
+            code: SmartSpectraErrorCode.kInvalidState, retryable: true,
+        });
     }
 
     // ---------- internal ----------------------------------------------------
 
     _requireSourceSelectionAllowed() {
+        this._requireCompatibilityIdle();
         if (this._destroyPromise) {
             throw Object.assign(new Error('SmartSpectra is shutting down'), {
                 code: SmartSpectraErrorCode.kInvalidState, retryable: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartspectra/node-sdk",
-  "version": "3.5.0-rc.2",
+  "version": "3.5.0-rc.3",
   "description": "Node.js (Electron) FFI binding for SmartSpectra vitals measurement",
   "author": "Presage Technologies, Inc.",
   "license": "SEE LICENSE IN LICENSE",
@@ -35,13 +35,15 @@
     "THIRD_PARTY_FFMPEG.md",
     "THIRD_PARTY_NOTICES.txt",
     "NOTICE",
+    "docs/device-compatibility.md",
+    "samples/device_compatibility/*.cjs",
     "README.md"
   ],
   "scripts": {
     "prepare": "node scripts/gen-proto.cjs",
     "build:proto": "node scripts/gen-proto.cjs",
-    "test": "npm run test:types && node --test test/log-level-pin.js test/renderer-timestamp.js test/renderer-frame-transform.js test/camera-selection.js test/reset-lifecycle.js test/smoke.js",
-    "test:types": "tsc --noEmit --strict --skipLibCheck --target es2022 --module nodenext test/camera-selection-types.ts test/renderer-types.ts",
+    "test": "npm run test:types && node --test test/log-level-pin.js test/renderer-timestamp.js test/renderer-frame-transform.js test/camera-selection.js test/reset-lifecycle.js test/resolve-native.js test/device-compatibility.js test/device-compatibility-presentation.js test/smoke.js",
+    "test:types": "tsc --noEmit --strict --skipLibCheck --target es2022 --module nodenext test/camera-selection-types.ts test/renderer-types.ts test/device-compatibility-types.ts",
     "test:models-allowlist": "node test/models-allowlist.js"
   },
   "keywords": [
@@ -71,10 +73,10 @@
   "dependencies": {
     "koffi": "^2.10.0",
     "protobufjs": "^7.6.5",
-    "@smartspectra/node-sdk-linux-x64": "3.5.0-rc.2",
-    "@smartspectra/node-sdk-linux-arm64": "3.5.0-rc.2",
-    "@smartspectra/node-sdk-darwin-arm64": "3.5.0-rc.2",
-    "@smartspectra/node-sdk-win32-x64": "3.5.0-rc.2"
+    "@smartspectra/node-sdk-linux-x64": "3.5.0-rc.3",
+    "@smartspectra/node-sdk-linux-arm64": "3.5.0-rc.3",
+    "@smartspectra/node-sdk-darwin-arm64": "3.5.0-rc.3",
+    "@smartspectra/node-sdk-win32-x64": "3.5.0-rc.3"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/samples/device_compatibility/main.cjs

@@ -0,0 +1,16 @@
+// Copyright (C) 2026 Presage Technologies, Inc.
+// SPDX-License-Identifier: LicenseRef-Proprietary
+'use strict';
+const { SmartSpectraSDK } = require('@smartspectra/node-sdk');
+const { writeFileSync } = require('node:fs');
+(async () => {
+    const sdk = new SmartSpectraSDK({ apiKey: process.env.PHYSIOLOGY_API_KEY });
+    sdk.useCamera();
+    try {
+        await sdk.isDeviceCompatible();
+        const result = sdk.getDeviceCompatibilityResult();
+        console.log(result.verdict, result.reason);
+        if (process.argv[2]) writeFileSync(process.argv[2], result.diagnostics, { flag: 'wx', mode: 0o600 });
+        process.exitCode = result.verdict === 'ready' ? 0 : 2;
+    } finally { await sdk.destroy(); }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/samples/device_compatibility/presentation.cjs

@@ -0,0 +1,9 @@
+// Copyright (C) 2026 Presage Technologies, Inc.
+// SPDX-License-Identifier: LicenseRef-Proprietary
+'use strict';
+function present(result) {
+    return { title: result.verdict, reason: result.reason, action: result.reason,
+        canProceed: result.verdict === 'ready' };
+}
+function supportReport(result) { return result.diagnostics; }
+module.exports = { present, supportReport };

package/samples/device_compatibility/simple.cjs

@@ -0,0 +1,14 @@
+// Copyright (C) 2026 Presage Technologies, Inc.
+// SPDX-License-Identifier: LicenseRef-Proprietary
+'use strict';
+const { SmartSpectraSDK } = require('@smartspectra/node-sdk');
+async function main() {
+    const sdk = new SmartSpectraSDK({ apiKey: process.env.PHYSIOLOGY_API_KEY });
+    sdk.useCamera();
+    try {
+        const verdict = await sdk.isDeviceCompatible();
+        console.log(verdict);
+        process.exitCode = verdict === 'ready' ? 0 : 2;
+    } finally { await sdk.destroy(); }
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });