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

package/NOTICE

@@ -15,9 +15,10 @@ The following Apache-licensed components are included in this shipped artifact:
   - HighwayHash
   - KleidiAI
   - Kompute
+  - LiteRT (TensorFlow Lite runtime)
   - MediaPipe
   - ml_dtypes
   - OpenCV
   - protoc-gen-validate
   - ruy
-  - TensorFlow (TensorFlow Lite)
+  - TensorFlow

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 Readiness: [check readiness and handle results](docs/device-readiness.md)
 - Metrics guide: <https://smartspectra.presagetech.com/docs/nodejs/metrics>
 
 ## Architecture

package/THIRD_PARTY_NOTICES.txt

@@ -19,12 +19,13 @@ Apache-2.0
   - HighwayHash
   - KleidiAI
   - Kompute
+  - LiteRT (TensorFlow Lite runtime)
   - MediaPipe
   - ml_dtypes
   - OpenCV
   - protoc-gen-validate
   - ruy
-  - TensorFlow (TensorFlow Lite)
+  - TensorFlow
 
 BSD-2-Clause
   - cpuinfo
@@ -294,7 +295,7 @@ Full license texts included in this file
    See the License for the specific language governing permissions and
    limitations under the License.
 
-Applies to: Abseil, CNCF xDS API, Envoy data-plane-api, FlatBuffers, gemmlowp, Google APIs, gRPC, HighwayHash, KleidiAI, Kompute, MediaPipe, ml_dtypes, OpenCV, protoc-gen-validate, ruy, TensorFlow (TensorFlow Lite)
+Applies to: Abseil, CNCF xDS API, Envoy data-plane-api, FlatBuffers, gemmlowp, Google APIs, gRPC, HighwayHash, KleidiAI, Kompute, LiteRT (TensorFlow Lite runtime), MediaPipe, ml_dtypes, OpenCV, protoc-gen-validate, ruy, TensorFlow
 
 ===== BSD-2-Clause =====
 Copyright (c) <year> <owner>. All rights reserved.

package/docs/device-readiness.md

@@ -0,0 +1,61 @@
+---
+title: Node.js Device Readiness
+description: Check device readiness for the configured metrics and camera, and handle the result.
+---
+
+# Node.js Device Readiness
+
+> **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.
+
+Configure the SDK's authentication, metrics, and camera, then check readiness
+before starting a measurement:
+
+```javascript
+const result = await sdk.checkDeviceReadiness();
+```
+
+Use `result.verdict` for application decisions and `result.reason` for the
+explanation and recommended next step. Keep the returned result if you need it later.
+
+Compare the verdict explicitly, for example `result.verdict === 'ready'`.
+Every verdict string is truthy, including `'blocked'`.
+
+See [Device Readiness](../../docs/device-readiness.md) for
+verdict meanings, supported inputs, and result handling.
+
+## Telemetry
+
+Telemetry is on by default. When it is enabled, each check sends its full
+diagnostic report to Presage: device and SDK details, requested metrics and camera
+settings, performance measurements, and free-text diagnostic messages. The report
+never includes video frames or vital signs.
+
+To turn it off, pass `enableTelemetry: false` when creating the SDK:
+
+```javascript
+const sdk = new SmartSpectraSDK({
+  // ...authentication and metrics...
+  enableTelemetry: false,
+});
+```
+
+See [SDK Telemetry & Privacy](../../docs/telemetry-and-privacy.md) for the full
+report contents, storage, and retention.
+
+## When a measurement stops for low frame rate
+
+When the frame rate stays too low to measure reliably during a measurement, the
+session ends and the `'error'` event receives
+`SmartSpectraErrorCode.kSustainedLowFrameRate` (14) instead of
+`SmartSpectraErrorCode.kProcessingFailed`. The message is "SmartSpectra stopped
+because the frame rate stayed too low to measure reliably." A frame submitted as
+the session ends is rejected with the same code. `retryable` is `false` when the
+SDK plays a video file, because the same file stops the same way; it is `true` for
+cameras and custom input:
+the host may offer a user-initiated fresh start; do not restart automatically.
+To check whether a device can sustain measurement before starting, call
+`checkDeviceReadiness()`.
+
+The SDK measures frame rate from frame timestamps: the timestamp file when one is
+given, otherwise the video's playback position. The interframe delay
+(`interframeDelayMs`) changes playback speed, not the measured frame rate.

package/js/constants.js

@@ -80,6 +80,8 @@ const SmartSpectraErrorCode = Object.freeze({
     kFrameConversionFailed: 9,
     kNonMonotonicTimestamp: 10,
     kTimestampGap:          11,
+    kMetricNotAuthorized:   13,
+    kSustainedLowFrameRate: 14,
 });
 
 // Spatial transform applied to each pushed frame before it enters the
@@ -101,16 +103,11 @@ const MetricType = Object.freeze(Object.fromEntries(
 
 // MetricType integer codes grouped by measurement type. Spread into
 // `requestedMetrics`; omitting `requestedMetrics` is equivalent to passing
-// `breathingMetrics`.
+// `breathingMetrics` (chest breathing, abdomen breathing, breathing rate).
 const breathingMetrics = Object.freeze([
     0,  // CHEST_BREATHING
     1,  // ABDOMEN_BREATHING
     2,  // BREATHING_RATE
-    3,  // BREATHING_AMPLITUDE
-    4,  // APNEA
-    5,  // RESPIRATORY_LINE_LENGTH
-    6,  // BASELINE
-    7,  // INHALE_EXHALE_RATIO
 ]);
 
 const cardioMetrics = Object.freeze([
@@ -135,8 +132,8 @@ const edaMetrics = Object.freeze([
     10, // EDA_TRACE
 ]);
 
-// The default metric bundle used when `requestedMetrics` is omitted; currently
-// equals the breathing bundle.
+// The default metric bundle used when `requestedMetrics` is omitted; equal to
+// `breathingMetrics`.
 const defaultSupportedMetrics = breathingMetrics;
 
 module.exports = {

package/js/device-readiness.js

@@ -0,0 +1,430 @@
+// 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 v9.');
+    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)')() !== 9) 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)'),
+        finish: lib.func('int smartspectra_readiness_finish_check(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',
+    'network_unavailable'];
+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 DeviceReadinessCheck {
+    #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); }
+}
+// Native threads do not keep Node's event loop alive. Drain surviving owners
+// before normal process exit, while native singleton dependencies still exist.
+// This does not promise delivery after process.exit(), SIGKILL, or a crash.
+const liveServices = new Set();
+function destroyNative(state) {
+    if (state.closing) return state.closing;
+    state.closing = new Promise((resolve, reject) => {
+        state.n.destroy.async(state.handle, error => {
+            if (error) reject(error);
+            else { state.destroyed = true; resolve(); }
+        });
+    }).finally(() => liveServices.delete(state));
+    return state.closing;
+}
+let exitDrainInstalled = false;
+function installExitDrain() {
+    if (exitDrainInstalled) return;
+    exitDrainInstalled = true;
+    process.on('beforeExit', () => {
+        for (const state of liveServices) void destroyNative(state).catch(() => {});
+    });
+}
+const services = new FinalizationRegistry(state => { void destroyNative(state).catch(() => {}); });
+class DeviceReadinessService {
+    static async run(configuration = {}) {
+        const service = new DeviceReadinessService();
+        try { return await service.check(configuration).result; }
+        finally { await service.close(); }
+    }
+    #native; #handle; #checks = new Set(); #closing; #lifetime; #finishing;
+    constructor() {
+        this.#native = getNative();
+        ensurePreconfigured();
+        this.#handle = this.#native.create();
+        if (!this.#handle) throw new Error('Unable to create native readiness service.');
+        this.#lifetime = { n: this.#native, handle: this.#handle };
+        liveServices.add(this.#lifetime);
+        installExitDrain();
+        services.register(this, this.#lifetime, this);
+    }
+    get closed() { return !!this.#lifetime.closing; }
+    reserve() {
+        if (!this.#handle || this.#closing || this.closed || this.#finishing) throw new Error('Readiness 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 = DeviceReadinessPolicies.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 || this.closed || this.#finishing) 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 || this.closed || this.#finishing) 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 DeviceReadinessCheck(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;
+    }
+    finishCheck() {
+        if (this.closed) return this.#lifetime.closing;
+        if (this.#closing) return this.#closing;
+        if (this.#finishing) return this.#finishing;
+        const checks = [...this.#checks];
+        checks.forEach(check => check.cancel());
+        this.#finishing = Promise.allSettled(checks.map(check => check.result)).then(() => new Promise((resolve, reject) => {
+            this.#native.finish.async(this.#handle, (error, status) => {
+                if (error) reject(error);
+                else if (status !== 0) reject(new Error('Unable to finish readiness check.'));
+                else resolve();
+            });
+        })).finally(() => { this.#finishing = null; });
+        return this.#finishing;
+    }
+    // SDK reset is an existing synchronous teardown API. Do not overlap an
+    // asynchronous finish/close; ordinary check returns have already joined it.
+    closeSync() {
+        // beforeExit may have finished draining this owner before another
+        // listener resumes application work. Its native handle is already gone.
+        if (this.#lifetime.destroyed) {
+            this.#handle = null;
+            services.unregister(this);
+            return;
+        }
+        if (this.#closing || this.#finishing || this.closed)
+            throw new Error('Readiness teardown is already in progress; await it before reset.');
+        this.#native.destroy(this.#handle);
+        this.#lifetime.destroyed = true;
+        this.#handle = null;
+        this.#lifetime.closing = Promise.resolve();
+        liveServices.delete(this.#lifetime);
+        services.unregister(this);
+    }
+    close() {
+        if (this.closed) return this.#lifetime.closing;
+        if (this.#closing) return this.#closing;
+        const checks = [...this.#checks];
+        checks.forEach(check => check.cancel());
+        this.#closing = Promise.allSettled([...checks.map(check => check.result), this.#finishing]).then(() => {
+            this.#handle = null;
+            services.unregister(this);
+            return destroyNative(this.#lifetime);
+        });
+        return this.#closing;
+    }
+}
+const DeviceReadinessPolicies = 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 deviceReadinessAvailable() { try { getNative(); return true; } catch { return false; } }
+module.exports = { DeviceReadinessService, DeviceReadinessPolicies, deviceReadinessAvailable, 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,10 @@ 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;
+    /** The frame rate stayed too low for a reliable measurement, so the session ended. */
+    readonly kSustainedLowFrameRate: 14;
 };
 export type SmartSpectraErrorCodeValue = typeof SmartSpectraErrorCode[keyof typeof SmartSpectraErrorCode];
 
@@ -121,7 +125,11 @@ export interface SmartSpectraOptions {
     apiKey?: string;
 
     /**
-     * MetricType integer codes. Defaults to `breathingMetrics` when omitted.
+     * MetricType integer codes. Defaults to `breathingMetrics` (`MetricType.CHEST_BREATHING`,
+     * `MetricType.ABDOMEN_BREATHING`, `MetricType.BREATHING_RATE`) when omitted. Requesting an
+     * Unavailable metric (`MetricType.BREATHING_AMPLITUDE`, `MetricType.APNEA`,
+     * `MetricType.RESPIRATORY_LINE_LENGTH`, `MetricType.BASELINE`,
+     * `MetricType.INHALE_EXHALE_RATIO`) makes `start()` throw `kConfigurationFailed`.
      */
     requestedMetrics?: number[];
 
@@ -134,7 +142,10 @@ export interface SmartSpectraOptions {
      */
     logLevel?: SmartSpectraLogLevelValue;
 
-    /** Aggregate SDK telemetry. Defaults to `true`; set `false` to opt out. */
+    /** Session summaries and full readiness reports. Defaults to `true`; set `false`
+     * to opt out. Reports can contain free text, paths and platform context, and
+     * authenticated requests can correlate them with an account/device. No raw frames
+     * or measured vitals are sent. See SDK Telemetry & Privacy. */
     enableTelemetry?: boolean;
 }
 
@@ -142,7 +153,12 @@ export interface SmartSpectraOptions {
 export interface VideoFileOptions {
     /** Path to a per-frame timestamps file (one timestamp per line). */
     timestampsPath?: string | null;
-    /** Throttle between frames in ms; omit/0 = as fast as possible. */
+    /**
+     * Throttle between frames in ms; omit/0 = as fast as possible. The SDK measures
+     * frame rate from frame timestamps: the timestamp file when one is given, otherwise
+     * the video's playback position. The interframe delay changes playback speed, not
+     * the measured frame rate.
+     */
     interframeDelayMs?: number;
     /** Seek this far into the file before playback (ms); omit/0 = start. */
     startOffsetMs?: number;
@@ -212,6 +228,8 @@ export interface CameraOptions {
  * ```
  */
 export declare class SmartSpectraSDK {
+    /** Device readiness uses this SDK's authentication. */
+    checkDeviceReadiness(): Promise<DeviceReadinessResult>;
     /** SDK package version. */
     static readonly version: string;
 
@@ -344,14 +362,14 @@ export declare class SmartSpectraSDK {
 /**
  * MetricType integer codes grouped by measurement type. Spread into
  * `requestedMetrics`; omitting it is equivalent to passing
- * `breathingMetrics`.
+ * `breathingMetrics` (chest breathing, abdomen breathing, breathing rate).
  */
 export declare const breathingMetrics:        readonly number[];
 export declare const cardioMetrics:           readonly number[];
 export declare const faceMetrics:             readonly number[];
 export declare const micromotionMetrics:      readonly number[];
 export declare const edaMetrics:              readonly number[];
-/** Default metric bundle used when `requestedMetrics` is omitted. */
+/** Default metric bundle used when `requestedMetrics` is omitted; equal to `breathingMetrics`. */
 export declare const defaultSupportedMetrics: readonly number[];
 
 /**
@@ -367,3 +385,11 @@ export declare function setMetricsClass(cls: unknown): void;
  * been registered via `setMetricsClass`, otherwise the raw Buffer.
  */
 export declare function decodeMetrics(buf: Buffer): unknown;
+
+/** Device readiness. Pin the JS and native SDK versions together. */
+/** Outcome for the configured SDK workload. */
+export type DeviceReadinessVerdict = 'ready' | 'limited' | 'blocked' | 'inconclusive';
+export interface DeviceReadinessResult {
+    readonly verdict: DeviceReadinessVerdict;
+    readonly reason: string;
+}

package/js/main/index.d.ts

@@ -5,7 +5,7 @@
 
 import type { BrowserWindow } from 'electron';
 
-export { SmartSpectraSDK, ProcessingStatus } from '../../js/index';
+export { SmartSpectraSDK, ProcessingStatus } from '../index';
 
 /** Options for `bindSmartSpectraIpc`. */
 export interface BindSmartSpectraIpcOptions {

package/js/messages/generated.d.ts

@@ -725,6 +725,9 @@ export namespace presage {
 
             /** End of the completed measurement window, in microseconds on the session input timeline */
             timestamp?: (number|Long|null);
+
+            /** True when the service returned a valid strict value; false means retry the measurement. */
+            stable?: (boolean|null);
         }
 
         /**
@@ -745,6 +748,9 @@ export namespace presage {
             /** End of the completed measurement window, in microseconds on the session input timeline */
             public timestamp: (number|Long);
 
+            /** True when the service returned a valid strict value; false means retry the measurement. */
+            public stable: boolean;
+
             /**
              * Creates a new Strict instance using the specified properties.
              * @param [properties] Properties to set
@@ -973,19 +979,19 @@ export namespace presage {
              */
             lowerTrace?: (presage.smartspectra.IMeasurement[]|null);
 
-            /** Breathing amplitude measurements */
+            /** Unavailable: breathing amplitude. This field stays empty; requesting BREATHING_AMPLITUDE makes start fail with ConfigurationFailed. */
             amplitude?: (presage.smartspectra.IMeasurement[]|null);
 
-            /** Apnea (breathing cessation) detection status */
+            /** Unavailable: apnea (breathing cessation) detection. This field stays empty; requesting APNEA makes start fail with ConfigurationFailed. */
             apnea?: (presage.smartspectra.IDetectionStatus[]|null);
 
-            /** Respiratory line length measurements for breathing pattern analysis */
+            /** Unavailable: respiratory line length. This field stays empty; requesting RESPIRATORY_LINE_LENGTH makes start fail with ConfigurationFailed. */
             respiratoryLineLength?: (presage.smartspectra.IMeasurement[]|null);
 
-            /** Baseline breathing measurements */
+            /** Unavailable: breathing baseline. This field stays empty; requesting BASELINE makes start fail with ConfigurationFailed. */
             baseline?: (presage.smartspectra.IMeasurement[]|null);
 
-            /** Inhale to exhale duration ratio measurements */
+            /** Unavailable: inhale/exhale duration ratio. This field stays empty; requesting INHALE_EXHALE_RATIO makes start fail with ConfigurationFailed. */
             inhaleExhaleRatio?: (presage.smartspectra.IMeasurement[]|null);
 
             /**
@@ -1031,19 +1037,19 @@ export namespace presage {
              */
             public lowerTrace: presage.smartspectra.IMeasurement[];
 
-            /** Breathing amplitude measurements */
+            /** Unavailable: breathing amplitude. This field stays empty; requesting BREATHING_AMPLITUDE makes start fail with ConfigurationFailed. */
             public amplitude: presage.smartspectra.IMeasurement[];
 
-            /** Apnea (breathing cessation) detection status */
+            /** Unavailable: apnea (breathing cessation) detection. This field stays empty; requesting APNEA makes start fail with ConfigurationFailed. */
             public apnea: presage.smartspectra.IDetectionStatus[];
 
-            /** Respiratory line length measurements for breathing pattern analysis */
+            /** Unavailable: respiratory line length. This field stays empty; requesting RESPIRATORY_LINE_LENGTH makes start fail with ConfigurationFailed. */
             public respiratoryLineLength: presage.smartspectra.IMeasurement[];
 
-            /** Baseline breathing measurements */
+            /** Unavailable: breathing baseline. This field stays empty; requesting BASELINE makes start fail with ConfigurationFailed. */
             public baseline: presage.smartspectra.IMeasurement[];
 
-            /** Inhale to exhale duration ratio measurements */
+            /** Unavailable: inhale/exhale duration ratio. This field stays empty; requesting INHALE_EXHALE_RATIO makes start fail with ConfigurationFailed. */
             public inhaleExhaleRatio: presage.smartspectra.IMeasurement[];
 
             /**

package/js/messages/generated.js

@@ -2053,6 +2053,7 @@ $root.presage = (function() {
              * @interface IStrict
              * @property {number|null} [value] The strict value requiring high precision
              * @property {number|Long|null} [timestamp] End of the completed measurement window, in microseconds on the session input timeline
+             * @property {boolean|null} [stable] True when the service returned a valid strict value; false means retry the measurement.
              */
 
             /**
@@ -2087,6 +2088,14 @@ $root.presage = (function() {
              */
             Strict.prototype.timestamp = $util.Long ? $util.Long.fromBits(0,0,false) : 0;
 
+            /**
+             * True when the service returned a valid strict value; false means retry the measurement.
+             * @member {boolean} stable
+             * @memberof presage.smartspectra.Strict
+             * @instance
+             */
+            Strict.prototype.stable = false;
+
             /**
              * Creates a new Strict instance using the specified properties.
              * @function create
@@ -2119,6 +2128,8 @@ $root.presage = (function() {
                     writer.uint32(/* id 1, wireType 5 =*/13).float(message.value);
                 if (message.timestamp != null && Object.hasOwnProperty.call(message, "timestamp"))
                     writer.uint32(/* id 2, wireType 0 =*/16).int64(message.timestamp);
+                if (message.stable != null && Object.hasOwnProperty.call(message, "stable"))
+                    writer.uint32(/* id 3, wireType 0 =*/24).bool(message.stable);
                 return writer;
             };
 
@@ -2177,6 +2188,10 @@ $root.presage = (function() {
                             message.timestamp = reader.int64();
                             break;
                         }
+                    case 3: {
+                            message.stable = reader.bool();
+                            break;
+                        }
                     default:
                         reader.skipType(tag & 7, long);
                         break;
@@ -2227,6 +2242,9 @@ $root.presage = (function() {
                 if (message.timestamp != null && Object.hasOwnProperty.call(message, "timestamp"))
                     if (!$util.isInteger(message.timestamp) && !(message.timestamp && $util.isInteger(message.timestamp.low) && $util.isInteger(message.timestamp.high)))
                         return "timestamp: integer|Long expected";
+                if (message.stable != null && Object.hasOwnProperty.call(message, "stable"))
+                    if (typeof message.stable !== "boolean")
+                        return "stable: boolean expected";
                 return null;
             };
 
@@ -2259,6 +2277,8 @@ $root.presage = (function() {
                         message.timestamp = object.timestamp;
                     else if (typeof object.timestamp === "object")
                         message.timestamp = new $util.LongBits(object.timestamp.low >>> 0, object.timestamp.high >>> 0).toNumber();
+                if (object.stable != null)
+                    message.stable = Boolean(object.stable);
                 return message;
             };
 
@@ -2286,6 +2306,7 @@ $root.presage = (function() {
                         object.timestamp = options.longs === String ? long.toString() : options.longs === Number ? long.toNumber() : typeof BigInt !== "undefined" && options.longs === BigInt ? long.toBigInt() : long;
                     } else
                         object.timestamp = options.longs === String ? "0" : typeof BigInt !== "undefined" && options.longs === BigInt ? BigInt("0") : 0;
+                    object.stable = false;
                 }
                 if (message.value != null && Object.hasOwnProperty.call(message, "value"))
                     object.value = options.json && !isFinite(message.value) ? String(message.value) : message.value;
@@ -2296,6 +2317,8 @@ $root.presage = (function() {
                         object.timestamp = options.longs === String ? String(message.timestamp) : message.timestamp;
                     else
                         object.timestamp = options.longs === String ? $util.Long.prototype.toString.call(message.timestamp) : options.longs === Number ? new $util.LongBits(message.timestamp.low >>> 0, message.timestamp.high >>> 0).toNumber() : message.timestamp;
+                if (message.stable != null && Object.hasOwnProperty.call(message, "stable"))
+                    object.stable = message.stable;
                 return object;
             };
 
@@ -2729,11 +2752,11 @@ $root.presage = (function() {
              * @property {Array.<presage.smartspectra.IMeasurement>|null} [lowerTrace] Abdominal breathing movement trace measurements. The trace has no confidence
              * of its own; `stable` is inherited from the breathing rate verdict (>= 45); see
              * the [breathing model card](https://vandv.presagetech.com/breathing_model_card.html).
-             * @property {Array.<presage.smartspectra.IMeasurement>|null} [amplitude] Breathing amplitude measurements
-             * @property {Array.<presage.smartspectra.IDetectionStatus>|null} [apnea] Apnea (breathing cessation) detection status
-             * @property {Array.<presage.smartspectra.IMeasurement>|null} [respiratoryLineLength] Respiratory line length measurements for breathing pattern analysis
-             * @property {Array.<presage.smartspectra.IMeasurement>|null} [baseline] Baseline breathing measurements
-             * @property {Array.<presage.smartspectra.IMeasurement>|null} [inhaleExhaleRatio] Inhale to exhale duration ratio measurements
+             * @property {Array.<presage.smartspectra.IMeasurement>|null} [amplitude] Unavailable: breathing amplitude. This field stays empty; requesting BREATHING_AMPLITUDE makes start fail with ConfigurationFailed.
+             * @property {Array.<presage.smartspectra.IDetectionStatus>|null} [apnea] Unavailable: apnea (breathing cessation) detection. This field stays empty; requesting APNEA makes start fail with ConfigurationFailed.
+             * @property {Array.<presage.smartspectra.IMeasurement>|null} [respiratoryLineLength] Unavailable: respiratory line length. This field stays empty; requesting RESPIRATORY_LINE_LENGTH makes start fail with ConfigurationFailed.
+             * @property {Array.<presage.smartspectra.IMeasurement>|null} [baseline] Unavailable: breathing baseline. This field stays empty; requesting BASELINE makes start fail with ConfigurationFailed.
+             * @property {Array.<presage.smartspectra.IMeasurement>|null} [inhaleExhaleRatio] Unavailable: inhale/exhale duration ratio. This field stays empty; requesting INHALE_EXHALE_RATIO makes start fail with ConfigurationFailed.
              * @property {presage.smartspectra.IStrict|null} [breathingRateStrict] Strict/high-precision breathing measurements over a fixed time interval.
              * Populated only when BREATHING_RATE_STRICT is requested and a value is
              * available.
@@ -2796,7 +2819,7 @@ $root.presage = (function() {
             Breathing.prototype.lowerTrace = $util.emptyArray;
 
             /**
-             * Breathing amplitude measurements
+             * Unavailable: breathing amplitude. This field stays empty; requesting BREATHING_AMPLITUDE makes start fail with ConfigurationFailed.
              * @member {Array.<presage.smartspectra.IMeasurement>} amplitude
              * @memberof presage.smartspectra.Breathing
              * @instance
@@ -2804,7 +2827,7 @@ $root.presage = (function() {
             Breathing.prototype.amplitude = $util.emptyArray;
 
             /**
-             * Apnea (breathing cessation) detection status
+             * Unavailable: apnea (breathing cessation) detection. This field stays empty; requesting APNEA makes start fail with ConfigurationFailed.
              * @member {Array.<presage.smartspectra.IDetectionStatus>} apnea
              * @memberof presage.smartspectra.Breathing
              * @instance
@@ -2812,7 +2835,7 @@ $root.presage = (function() {
             Breathing.prototype.apnea = $util.emptyArray;
 
             /**
-             * Respiratory line length measurements for breathing pattern analysis
+             * Unavailable: respiratory line length. This field stays empty; requesting RESPIRATORY_LINE_LENGTH makes start fail with ConfigurationFailed.
              * @member {Array.<presage.smartspectra.IMeasurement>} respiratoryLineLength
              * @memberof presage.smartspectra.Breathing
              * @instance
@@ -2820,7 +2843,7 @@ $root.presage = (function() {
             Breathing.prototype.respiratoryLineLength = $util.emptyArray;
 
             /**
-             * Baseline breathing measurements
+             * Unavailable: breathing baseline. This field stays empty; requesting BASELINE makes start fail with ConfigurationFailed.
              * @member {Array.<presage.smartspectra.IMeasurement>} baseline
              * @memberof presage.smartspectra.Breathing
              * @instance
@@ -2828,7 +2851,7 @@ $root.presage = (function() {
             Breathing.prototype.baseline = $util.emptyArray;
 
             /**
-             * Inhale to exhale duration ratio measurements
+             * Unavailable: inhale/exhale duration ratio. This field stays empty; requesting INHALE_EXHALE_RATIO makes start fail with ConfigurationFailed.
              * @member {Array.<presage.smartspectra.IMeasurement>} inhaleExhaleRatio
              * @memberof presage.smartspectra.Breathing
              * @instance

package/js/renderer/index.d.ts

@@ -9,7 +9,7 @@ import type {
     ValidationCodeValue,
     SmartSpectraErrorCodeValue,
     SmartSpectraOptions,
-} from '../../js/index';
+} from '../index';
 
 // Re-export the public value constants and matching type aliases so the
 // renderer-side consumer can import everything from one entry point.
@@ -26,7 +26,7 @@ export {
     micromotionMetrics,
     edaMetrics,
     defaultSupportedMetrics,
-} from '../../js/index';
+} from '../index';
 export type {
     ProcessingStatusValue,
     PixelFormatValue,
@@ -35,7 +35,7 @@ export type {
     FrameTransformValue,
     MetricTypeValue,
     SmartSpectraOptions,
-} from '../../js/index';
+} from '../index';
 
 /**
  * Renderer constructor options: the shared SDK options plus a renderer-only

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 readinessInFlight = 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._readinessInFlight = false;
+
         this._destroyPromise = null;
     }
 
@@ -99,6 +103,7 @@ class SmartSpectraSDK {
      *   Spatial transform applied to every pushed frame.
      */
     useCustomInput(frameTransform = DEFAULT_FRAME_TRANSFORM) {
+        this._requireReadinessIdle();
         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._requireReadinessIdle();
         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._requireReadinessIdle();
         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._requireReadinessIdle();
         if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
         const source = this._source;
         if (!source) {
@@ -207,6 +215,11 @@ class SmartSpectraSDK {
      * Typed selection requires any pending stopAsync() to settle before reset.
      */
     reset() {
+        this._requireReadinessIdle();
+        if (this._readinessService) {
+            this._readinessService.closeSync();
+            this._readinessService = null;
+        }
         if (!this._session) return;
         this._session.reset(this._explicitCameraSelection);
         if (!this._explicitCameraSelection) this._source = null;
@@ -264,18 +277,96 @@ 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._readinessService && !this._readinessInFlight) return Promise.resolve();
+            this._requireReadinessIdle();
+            const service = this._readinessService;
+            this._readinessService = null;
+            const session = this._session;
+            // Destroy the session synchronously unless a readiness service must drain first.
+            const teardown = service ? service.close().then(() => session?.destroy()) : 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 checkDeviceReadiness() {
+        if (this._readinessResultPending) return Object.freeze({ verdict: 'inconclusive',
+            reason: 'The SDK is busy. Wait for the current SDK operation to finish.' });
+        this._readinessResultPending = true;
+        try {
+            const result = await this._runDeviceReadiness();
+            return Object.freeze({ verdict: result.verdict, reason: result.reason });
+        } finally { this._readinessResultPending = false; }
+    }
+
+    async _runDeviceReadiness() {
+        const { DeviceReadinessService, DeviceReadinessPolicies } = require('./device-readiness');
+        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 (readinessInFlight || this._readinessInFlight || 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 readiness check.');
+        if (![ProcessingStatus.kUninitialized, ProcessingStatus.kIdle].includes(status)) return busy();
+        if (source?.kind !== 'camera') return preflight('unsupported_input',
+            'Select a camera before checking readiness. File and custom-frame inputs are not yet supported; no device capacity verdict was established.');
+        this._readinessInFlight = true;
+        readinessInFlight = 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 = DeviceReadinessPolicies.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;
+            }
+            if (!this._readinessService || this._readinessService.closed)
+                this._readinessService = new DeviceReadinessService();
+            service = this._readinessService;
+            if (!service.reserve()) return busy();
+            return await service.start(selected, request).result;
+        } finally {
+            try { if (service) await service.finishCheck(); }
+            finally { this._readinessInFlight = false; readinessInFlight = false; }
+        }
+    }
+
+    _requireReadinessIdle() {
+        if (readinessInFlight || this._readinessInFlight) throw Object.assign(new Error('Device readiness is running'), {
+            code: SmartSpectraErrorCode.kInvalidState, retryable: true,
+        });
     }
 
     // ---------- internal ----------------------------------------------------
 
     _requireSourceSelectionAllowed() {
+        this._requireReadinessIdle();
         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.5",
   "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-readiness.md",
+    "samples/device_readiness/*.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/strict-results.js 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-readiness.js test/device-readiness-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-readiness-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.5",
+    "@smartspectra/node-sdk-linux-arm64": "3.5.0-rc.5",
+    "@smartspectra/node-sdk-darwin-arm64": "3.5.0-rc.5",
+    "@smartspectra/node-sdk-win32-x64": "3.5.0-rc.5"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/samples/device_readiness/main.cjs

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

package/samples/device_readiness/presentation.cjs

@@ -0,0 +1,8 @@
+// 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' };
+}
+module.exports = { present };

package/samples/device_readiness/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 result = await sdk.checkDeviceReadiness();
+        console.log(result.verdict);
+        process.exitCode = result.verdict === 'ready' ? 0 : 2;
+    } finally { await sdk.destroy(); }
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });