@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/worker/lifecycle.js

@@ -0,0 +1,141 @@
+import os from 'bare-os';
+import Signal from 'bare-signals';
+import { createBareKitRPCServer, createIPCClient } from './create-server.js';
+import { initEnv, getValidatedEnv } from '../server/env.js';
+import { initialize as initializeEngine, close as closeEngine, cleanupForTerminate as cleanupEngineForTerminate } from '@qvac/inference/engine';
+import { getServerLogger } from '../logging/index.js';
+import { acquireWorkerLock, releaseWorkerLock } from '../server/utils/worker-lock.js';
+let workerInitialized = false;
+let rpcInitialized = false;
+// Set true when shutdownWorker is in flight, so a later
+// SIGTERM/SIGINT/uncaught-exception does not re-run releaseWorkerLock + Bare.exit.
+let isShuttingDown = false;
+const logger = getServerLogger();
+// Defense-in-depth grace period for the SIGKILL safety net armed before
+// Bare.exit() in shutdownWorker. If Bare.exit cannot
+// terminate the worker within this window — typically because some path
+// holds a non-cancellable native handle (e.g. a libuv worker thread
+// blocked on flock; see QVAC-18197) — we force-kill the OS process to
+// guarantee bounded shutdown time.
+const FORCE_EXIT_GRACE_MS = 3_000;
+function scheduleForceExit() {
+    const timer = setTimeout(() => {
+        logger.error(`Bare.exit did not terminate the worker within ${FORCE_EXIT_GRACE_MS}ms — ` +
+            `force-killing self (likely blocked native handle)`);
+        try {
+            os.kill(os.pid(), 'SIGKILL');
+        }
+        catch {
+            // best-effort — if SIGKILL itself fails, there's nothing more to do
+        }
+    }, FORCE_EXIT_GRACE_MS);
+    // Don't let the safety-net timer keep the process alive on the happy
+    // path. Bare returns an object (not a number) from setTimeout.
+    if (timer && typeof timer === 'object' && 'unref' in timer) {
+        ;
+        timer.unref();
+    }
+}
+export function initializeWorker() {
+    if (workerInitialized) {
+        const validatedEnv = getValidatedEnv();
+        return { hasRPCConfig: !!validatedEnv.QVAC_IPC_SOCKET_PATH };
+    }
+    initializeEngine();
+    const { hasRPCConfig } = initEnv();
+    acquireWorkerLock();
+    setupShutdownHandlers();
+    workerInitialized = true;
+    logger.debug('Worker initialized');
+    logger.debug('Arguments to worker:', Bare.argv);
+    return { hasRPCConfig };
+}
+export function ensureRPCSetup() {
+    if (rpcInitialized)
+        return;
+    if (!workerInitialized) {
+        initializeWorker();
+    }
+    try {
+        const validatedEnv = getValidatedEnv();
+        const ipcSocketPath = validatedEnv.QVAC_IPC_SOCKET_PATH;
+        if (ipcSocketPath) {
+            logger.info(`Running in desktop mode, connecting to IPC socket: ${ipcSocketPath}`);
+            const rpc = createIPCClient(ipcSocketPath, {
+                onDisconnect: () => void shutdownWorker('ipc-disconnect')
+            });
+            logger.debug('Desktop IPC client created?', !!rpc);
+        }
+        else {
+            logger.info('Running in BareKit IPC mode');
+            createBareKitRPCServer();
+        }
+        logger.info('Bare worker started and listening for RPC requests');
+        logger.debug('Working directory:', os.cwd());
+        rpcInitialized = true;
+    }
+    catch (error) {
+        logger.error('Worker error:', error);
+        Bare.exit(1);
+    }
+}
+export function isWorkerInitialized() {
+    return workerInitialized;
+}
+/**
+ * Pre-terminate cleanup, callable while the worker is still alive.
+ *
+ * On platforms where the worker lives in the same OS process as the JS host
+ * (i.e. mobile via react-native-bare-kit Worklet), `Bare.exit()` would kill the
+ * entire app. This path runs the engine's cleanup (models, swarm, RAG,
+ * downloads, registry client, plugin/addon registries) without releasing the
+ * worker lock or exiting, leaving the caller (typically the SDK client about to
+ * call `worklet.terminate()`) responsible for tearing the worker down.
+ *
+ * Critical for clean termination: addons hold static state with js_ref_t
+ * handles into the current V8 isolate; without this cleanup, those refs survive
+ * into the next worklet's isolate and crash on first access.
+ */
+export async function cleanupForTerminate() {
+    await cleanupEngineForTerminate();
+}
+export async function shutdownWorker(reason) {
+    if (isShuttingDown)
+        return;
+    isShuttingDown = true;
+    const messages = {
+        signal: '🐻 Bare worker shutdown signal received, cleaning up...',
+        'rpc-close': '🧹 Worker RPC closed, cleaning up...',
+        'uncaught-exception': '💥 Uncaught exception, cleaning up...',
+        'unhandled-rejection': '💥 Unhandled rejection, cleaning up...',
+        'ipc-disconnect': '🔌 Parent IPC disconnected, cleaning up...'
+    };
+    logger.info(messages[reason]);
+    try {
+        // Idempotent: if cleanupForTerminate already ran, this only releases the
+        // engine's cache lock.
+        await closeEngine();
+        logger.info('✅ Cleanup completed successfully');
+    }
+    catch (error) {
+        logger.error('❌ Error during shutdown cleanup:', error);
+    }
+    releaseWorkerLock();
+    scheduleForceExit();
+    const isGraceful = reason === 'signal' || reason === 'rpc-close';
+    Bare.exit(isGraceful ? 0 : 1);
+}
+function setupShutdownHandlers() {
+    const signals = new Signal.Emitter();
+    signals.unref();
+    signals.once('SIGTERM', () => void shutdownWorker('signal'));
+    signals.once('SIGINT', () => void shutdownWorker('signal'));
+    Bare.on('uncaughtException', (err) => {
+        logger.error('Uncaught exception in worker:', err);
+        void shutdownWorker('uncaught-exception');
+    });
+    Bare.on('unhandledRejection', (reason) => {
+        logger.error('Unhandled rejection in worker:', reason);
+        void shutdownWorker('unhandled-rejection');
+    });
+}

package/dist/src/worker/plugins/audiogen-ggml.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/audiogen-ggml/plugin';
+//# sourceMappingURL=audiogen-ggml.d.ts.map

package/dist/src/worker/plugins/audiogen-ggml.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/audiogen-ggml/plugin';

package/dist/src/worker/plugins/bci-whispercpp-transcription.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/bci-whispercpp-transcription/plugin';
+//# sourceMappingURL=bci-whispercpp-transcription.d.ts.map

package/dist/src/worker/plugins/bci-whispercpp-transcription.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/bci-whispercpp-transcription/plugin';

package/dist/src/worker/plugins/ggml-classification.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/ggml-classification/plugin';
+//# sourceMappingURL=ggml-classification.d.ts.map

package/dist/src/worker/plugins/ggml-classification.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/ggml-classification/plugin';

package/dist/src/worker/plugins/ggml-ocr.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/ggml-ocr/plugin';
+//# sourceMappingURL=ggml-ocr.d.ts.map

package/dist/src/worker/plugins/ggml-ocr.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/ggml-ocr/plugin';

package/dist/src/worker/plugins/ggml-vla.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/ggml-vla/plugin';
+//# sourceMappingURL=ggml-vla.d.ts.map

package/dist/src/worker/plugins/ggml-vla.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/ggml-vla/plugin';

package/dist/src/worker/plugins/llamacpp-completion.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/llamacpp-completion/plugin';
+//# sourceMappingURL=llamacpp-completion.d.ts.map

package/dist/src/worker/plugins/llamacpp-completion.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/llamacpp-completion/plugin';

package/dist/src/worker/plugins/llamacpp-embedding.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/llamacpp-embedding/plugin';
+//# sourceMappingURL=llamacpp-embedding.d.ts.map

package/dist/src/worker/plugins/llamacpp-embedding.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/llamacpp-embedding/plugin';

package/dist/src/worker/plugins/nmtcpp-translation.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/nmtcpp-translation/plugin';
+//# sourceMappingURL=nmtcpp-translation.d.ts.map

package/dist/src/worker/plugins/nmtcpp-translation.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/nmtcpp-translation/plugin';

package/dist/src/worker/plugins/parakeet-transcription.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/parakeet-transcription/plugin';
+//# sourceMappingURL=parakeet-transcription.d.ts.map

package/dist/src/worker/plugins/parakeet-transcription.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/parakeet-transcription/plugin';

package/dist/src/worker/plugins/sdcpp-generation.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/sdcpp-generation/plugin';
+//# sourceMappingURL=sdcpp-generation.d.ts.map

package/dist/src/worker/plugins/sdcpp-generation.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/sdcpp-generation/plugin';

package/dist/src/worker/plugins/tts-ggml.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/tts-ggml/plugin';
+//# sourceMappingURL=tts-ggml.d.ts.map

package/dist/src/worker/plugins/tts-ggml.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/tts-ggml/plugin';

package/dist/src/worker/plugins/whispercpp-transcription.d.ts

@@ -0,0 +1,2 @@
+export * from '@qvac/inference/whispercpp-transcription/plugin';
+//# sourceMappingURL=whispercpp-transcription.d.ts.map

package/dist/src/worker/plugins/whispercpp-transcription.js

@@ -0,0 +1 @@
+export * from '@qvac/inference/whispercpp-transcription/plugin';

package/dist/src/worker/worker-core.d.ts

@@ -0,0 +1,7 @@
+import { ensureRPCSetup, cleanupForTerminate, initializeWorker, isWorkerInitialized, shutdownWorker, type WorkerShutdownReason } from './lifecycle.js';
+export { ensureRPCSetup, cleanupForTerminate };
+export declare const initializeWorkerCore: typeof initializeWorker;
+export declare const isCoreInitialized: typeof isWorkerInitialized;
+export declare const shutdownBareDirectWorker: typeof shutdownWorker;
+export type BareDirectShutdownReason = WorkerShutdownReason;
+//# sourceMappingURL=worker-core.d.ts.map

package/dist/src/worker/worker-core.js

@@ -0,0 +1,8 @@
+import { deprecate } from '../deprecate.js';
+import { ensureRPCSetup, cleanupForTerminate, initializeWorker, isWorkerInitialized, shutdownWorker } from './lifecycle.js';
+deprecate('worker-core', "'@qvac/sdk/worker-core' is deprecated; import from '@qvac/sdk/worker-lifecycle' " +
+    '(initializeWorker, isWorkerInitialized, shutdownWorker, WorkerShutdownReason).');
+export { ensureRPCSetup, cleanupForTerminate };
+export const initializeWorkerCore = initializeWorker;
+export const isCoreInitialized = isWorkerInitialized;
+export const shutdownBareDirectWorker = shutdownWorker;

package/docs/system-resources-support-matrix.md

@@ -51,36 +51,55 @@ collector failure.
 
 ## Source and scope
 
-The exact collector source strings are `bare-cpu-info` and `bare-gpu-info`.
+The exact collector source strings are `bare-cpu-info`, `bare-gpu-info`, and
+`bare-os` (the process-scoped memory metrics).
 When present, scope is one of `system`, `process`, `device`, `budget`, or
 `shared-system`. Scope is optional: the current collector omits it where the
 native value does not establish one, rather than inventing a scope.
 
 ## Metric behavior
 
-| Public metric                                | Accepted value                              | Source and scope when `supported`                 | Current runtime evidence                          |
-| -------------------------------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
-| `capabilities.cpu.value.logicalCores`        | Positive integer                            | `bare-cpu-info`; scope omitted                    | `supported` on `darwin-arm64`                     |
-| `sample.cpu`                                 | Number from 0 through 1                     | `bare-cpu-info`; `system`                         | `supported` on `darwin-arm64`                     |
-| `capabilities.memory.totalBytes`             | Positive integer                            | `bare-cpu-info`; `system`                         | `supported` on `darwin-arm64`                     |
-| `sample.memory.usedBytes`                    | Non-negative integer                        | `bare-cpu-info`; `system`                         | `supported` on `darwin-arm64`                     |
-| `sample.memory.totalBytes`                   | Positive integer                            | `bare-cpu-info`; `system`                         | `supported` on `darwin-arm64`                     |
-| `capabilities.gpus`                          | Array, including an empty array             | `bare-gpu-info`; scope omitted                    | `supported` with one GPU on `darwin-arm64`        |
-| `capabilities.gpus.value[].memoryTotalBytes` | Non-negative number                         | Never marked `supported` while scope is ambiguous | `unverified` on `darwin-arm64`                    |
-| `sample.gpus`                                | Array aligned with the cached GPU inventory | `bare-gpu-info`; scope omitted                    | `supported` with one GPU sample on `darwin-arm64` |
-| `sample.gpus.value[].compute`                | Number from 0 through 1                     | `bare-gpu-info`; `device`                         | `supported` on `darwin-arm64`                     |
-| `sample.gpus.value[].encode`                 | Number from 0 through 1                     | `bare-gpu-info`; `device`                         | `unavailable` on `darwin-arm64`                   |
-| `sample.gpus.value[].decode`                 | Number from 0 through 1                     | `bare-gpu-info`; `device`                         | `unavailable` on `darwin-arm64`                   |
-| `sample.gpus.value[].memoryUsedBytes`        | Non-negative number                         | Never marked `supported` while scope is ambiguous | `unverified` on `darwin-arm64`                    |
-| `sample.gpus.value[].memoryTotalBytes`       | Non-negative number                         | Never marked `supported` while scope is ambiguous | `unverified` on `darwin-arm64`                    |
-| `sample.gpus.value[].powerWatts`             | Non-negative number                         | `bare-gpu-info`; `device`                         | `unavailable` on `darwin-arm64`                   |
-| `sample.gpus.value[].temperatureCelsius`     | Non-negative number                         | `bare-gpu-info`; `device`                         | `unavailable` on `darwin-arm64`                   |
-
-For GPU memory, a missing native value becomes `unavailable`; any present value
-remains `unverified` because the native API does not identify its source and
-scope. In particular, Windows readings can represent a process budget, and
-Apple readings can fall back from system-oriented data to the current process's
-allocation. Neither is reported as universally device-scoped memory.
+| Public metric                                | Accepted value                              | Source and scope when `supported`                                          | Current runtime evidence                                                                                    |
+| -------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `capabilities.cpu.value.logicalCores`        | Positive integer                            | `bare-cpu-info`; scope omitted                                             | `supported` on `darwin-arm64`                                                                               |
+| `sample.cpu`                                 | Number from 0 through 1                     | `bare-cpu-info`; `system`                                                  | `supported` on `darwin-arm64`                                                                               |
+| `capabilities.memory.totalBytes`             | Positive integer                            | `bare-cpu-info`; `system`                                                  | `supported` on `darwin-arm64`                                                                               |
+| `sample.memory.usedBytes`                    | Non-negative integer                        | `bare-cpu-info`; `system`                                                  | `supported` on `darwin-arm64`                                                                               |
+| `sample.memory.totalBytes`                   | Positive integer                            | `bare-cpu-info`; `system`                                                  | `supported` on `darwin-arm64`                                                                               |
+| `sample.memory.processUsedBytes`             | Non-negative integer                        | `bare-os`; `process`                                                       | `supported` where `bare-os` reports RSS                                                                     |
+| `sample.memory.processAvailableBytes`        | Non-negative integer                        | `bare-os`; `process`                                                       | `unavailable` everywhere — iOS needs a native `os_proc_available_memory` source before this reports a value |
+| `capabilities.gpus`                          | Array, including an empty array             | `bare-gpu-info`; scope omitted                                             | `supported` with one GPU on `darwin-arm64`                                                                  |
+| `capabilities.gpus.value[].memoryTotalBytes` | Non-negative number                         | `bare-gpu-info`; `device`, when not unified memory                         | `unverified` on `darwin-arm64` (unified)                                                                    |
+| `sample.gpus`                                | Array aligned with the cached GPU inventory | `bare-gpu-info`; scope omitted                                             | `supported` with one GPU sample on `darwin-arm64`                                                           |
+| `sample.gpus.value[].compute`                | Number from 0 through 1                     | `bare-gpu-info`; `device`                                                  | `supported` on `darwin-arm64`                                                                               |
+| `sample.gpus.value[].encode`                 | Number from 0 through 1                     | `bare-gpu-info`; `device`                                                  | `unavailable` on `darwin-arm64`                                                                             |
+| `sample.gpus.value[].decode`                 | Number from 0 through 1                     | `bare-gpu-info`; `device`                                                  | `unavailable` on `darwin-arm64`                                                                             |
+| `sample.gpus.value[].memoryUsedBytes`        | Non-negative number                         | `bare-gpu-info`; `device`, when the sample agrees with the declared memory | `unverified` on `darwin-arm64` (unified)                                                                    |
+| `sample.gpus.value[].memoryTotalBytes`       | Non-negative number                         | `bare-gpu-info`; `device`, when the sample agrees with the declared memory | `unverified` on `darwin-arm64` (unified)                                                                    |
+| `sample.gpus.value[].powerWatts`             | Non-negative number                         | `bare-gpu-info`; `device`                                                  | `unavailable` on `darwin-arm64`                                                                             |
+| `sample.gpus.value[].temperatureCelsius`     | Non-negative number                         | `bare-gpu-info`; `device`                                                  | `unavailable` on `darwin-arm64`                                                                             |
+
+For GPU memory, a missing native value becomes `unavailable`. The native API
+does not identify the scope of a present value, so the SDK establishes it
+itself, per device, and reports `unverified` wherever it cannot:
+
+- A GPU that reports `unifiedMemory` is never device-scoped — its allocation is
+  system RAM, which the memory budget already accounts for. Apple readings are
+  `unverified` for this reason, and are a working-set recommendation rather
+  than a device pool (an M4 Max reports 81% of system RAM).
+- On Windows the values come from DXGI's `QueryVideoMemoryInfo` — `CurrentUsage`
+  and `Budget`, which are what this process uses and may use. They are reported
+  under the `budget` scope rather than discarded: what a process is allowed to
+  allocate is what an admission decision needs. They are not device totals, and
+  on an idle machine `Budget` is indistinguishable from VRAM, so no value-level
+  check can separate them.
+- Otherwise a sample is trusted as `device` only when its total agrees with the
+  memory the device declares for itself, within 10%. A discrete card agrees
+  (measured 1.00 and 0.96); an Intel iGPU declares 128 MiB and samples half of
+  system RAM, because it is reporting the shared pool.
+
+Declared memory (`capabilities`) is therefore `supported` on any non-unified
+GPU, while the per-sample readings additionally require that agreement.
 
 ## Platform limitations
 
@@ -89,9 +108,9 @@ allocation. Neither is reported as universally device-scoped memory.
   aggregate CPU usage without processor-group coverage metadata, so systems
   with more than 64 logical processors are not validated as whole-system
   observations.
-- Apple GPU memory can fall back to process-local allocation without exposing
-  which path produced the value. GPU total and used memory therefore remain
-  `unverified`.
+- Apple GPU memory is unified with system RAM and can fall back to process-local
+  allocation without exposing which path produced the value. GPU total and used
+  memory therefore remain `unverified` there.
 - GPU compute, encode, decode, power, and temperature depend on OS and driver
   telemetry. Missing native readings become `unavailable`; desktop prebuild
   presence does not change that status.