@qvac/sdk 0.15.0 → 0.17.0

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

@@ -0,0 +1,103 @@
+# System resources support matrix
+
+`getSystemResources` reports observations from `bare-cpu-info` and
+`bare-gpu-info`. A `supported` metric means that the collector returned a value
+which passed SDK normalization. It does not guarantee that a model fits, reserve
+resources, or prove equivalent semantics on every operating system or device.
+
+## Evidence levels
+
+Packaging and runtime evidence are separate:
+
+| Target         | Collector prebuilds               | Runtime evidence               |
+| -------------- | --------------------------------- | ------------------------------ |
+| `darwin-arm64` | Present                           | Local Bare run on Apple M4 Pro |
+| `darwin-x64`   | Present                           | Not run                        |
+| `linux-arm64`  | Present                           | Not run                        |
+| `linux-x64`    | Present                           | Not run                        |
+| `win32-arm64`  | Present                           | Not run                        |
+| `win32-x64`    | Present                           | Not run                        |
+| Android        | Not in the desktop packaging gate | No physical-device acceptance  |
+| iOS            | Not in the desktop packaging gate | No physical-device acceptance  |
+
+The desktop packaging gate verified that both collector addons were in the
+linked worker graph and addon manifest, that each listed desktop target had
+prebuilds, and that their packaged size stayed within the configured budgets.
+The 2 MiB compressed and 5 MiB uncompressed budgets are release ceilings for catching accidental packaging expansion, not fine-grained size regression thresholds.
+Prebuild presence is compile and packaging evidence only; it does not prove that
+a metric works on target hardware.
+
+The `darwin-arm64` runtime observation exercised collector initialization,
+capability queries, sampling, schema validation, and teardown on the current
+development host. It is not a general physical-device support claim. Android
+and iOS remain without runtime support claims until physical-device acceptance
+is recorded.
+
+## Status semantics
+
+Every metric uses one of the public schema statuses:
+
+- `supported`: a value passed normalization and includes `provenance`.
+- `unavailable`: the native collector returned no value for that metric.
+- `unverified`: a value was present but failed normalization, or its meaning or
+  scope could not be verified.
+- `failed`: the collector module, initialization, inventory query, or sample
+  operation failed.
+
+An unavailable individual field does not fail its enclosing CPU or GPU
+observation. If GPU enumeration succeeds and finds no devices, `gpus` is
+`supported` with an empty array. That is a supported observation, not a
+collector failure.
+
+## Source and scope
+
+The exact collector source strings are `bare-cpu-info` and `bare-gpu-info`.
+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.
+
+## Platform limitations
+
+- On Windows, the upstream CPU collector documents that per-core sampling covers
+  only the first processor group, at most 64 logical processors. The SDK exposes
+  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`.
+- 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.
+- A successful empty GPU inventory means no GPU was enumerated. It should not be
+  interpreted as a failed collector or as proof that the machine has no GPU.
+- Driver names, versions, and graphics API flags are passive observations. They
+  cannot establish backend compatibility. Only a machine-readable addon probe
+  may report `compatible` or `incompatible`; missing evidence remains
+  `unknown`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/sdk",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -108,6 +108,10 @@
       "types": "./dist/server/bare/plugins/sdcpp-generation/plugin.d.ts",
       "import": "./dist/server/bare/plugins/sdcpp-generation/plugin.js"
     },
+    "./audiogen-ggml/plugin": {
+      "types": "./dist/server/bare/plugins/audiogen-ggml/plugin.d.ts",
+      "import": "./dist/server/bare/plugins/audiogen-ggml/plugin.js"
+    },
     "./ggml-vla/plugin": {
       "types": "./dist/server/bare/plugins/ggml-vla/plugin.d.ts",
       "import": "./dist/server/bare/plugins/ggml-vla/plugin.js"
@@ -170,7 +174,8 @@
     "!**/pnpm-lock.yaml",
     "!**/bun.lock",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "docs/system-resources-support-matrix.md"
   ],
   "scripts": {
     "test:unit": "bun run scripts/run-unit-tests.ts",
@@ -184,44 +189,49 @@
     "lint": "eslint . --max-warnings=0",
     "lint:fix": "eslint . --fix",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "postcompile:aliases": "node ./scripts/resolve-aliases.mjs",
+    "postcompile:aliases": "tsc-alias -p tsconfig.alias.json",
     "build": "rm -rf dist && npm run lint && tsc --project tsconfig.json && npm run postcompile:aliases",
     "build:pack": "bun run build && bun pm pack --destination dist/",
     "watch": "nodemon --watch server --ext ts --exec 'bun run build'",
     "bare:ensureprebuilds:llamacpp": "cp -r node_modules/@qvac/llm-llamacpp/prebuilds/android-arm64 node_modules/@qvac/llm-llamacpp/prebuilds/android-ia32 && cp -r node_modules/@qvac/llm-llamacpp/prebuilds/android-arm64 node_modules/@qvac/llm-llamacpp/prebuilds/android-arm && cp -r node_modules/@qvac/llm-llamacpp/prebuilds/android-arm64 node_modules/@qvac/llm-llamacpp/prebuilds/android-x64",
-    "bare:ensureprebuilds:whispercpp": "cp -r node_modules/@qvac/transcription-whispercpp/prebuilds/android-arm64 node_modules/@qvac/transcription-whispercpp/prebuilds/android-ia32 && cp -r node_modules/@qvac/transcription-whispercpp/prebuilds/android-arm64 node_modules/@qvac/transcription-whispercpp/prebuilds/android-arm && cp -r node_modules/@qvac/transcription-whispercpp/prebuilds/android-arm64 node_modules/@qvac/transcription-whispercpp/prebuilds/android-x64",
+    "bare:ensureprebuilds:asr": "cp -r node_modules/@qvac/asr-ggml/prebuilds/android-arm64 node_modules/@qvac/asr-ggml/prebuilds/android-ia32 && cp -r node_modules/@qvac/asr-ggml/prebuilds/android-arm64 node_modules/@qvac/asr-ggml/prebuilds/android-arm && cp -r node_modules/@qvac/asr-ggml/prebuilds/android-arm64 node_modules/@qvac/asr-ggml/prebuilds/android-x64",
     "bare:ensureprebuilds:embeddings": "cp -r node_modules/@qvac/embed-llamacpp/prebuilds/android-arm64 node_modules/@qvac/embed-llamacpp/prebuilds/android-ia32 && cp -r node_modules/@qvac/embed-llamacpp/prebuilds/android-arm64 node_modules/@qvac/embed-llamacpp/prebuilds/android-arm && cp -r node_modules/@qvac/embed-llamacpp/prebuilds/android-arm64 node_modules/@qvac/embed-llamacpp/prebuilds/android-x64",
-    "bare:ensureprebuilds": "bun run bare:ensureprebuilds:llamacpp && bun run bare:ensureprebuilds:whispercpp && bun run bare:ensureprebuilds:embeddings",
+    "bare:ensureprebuilds": "bun run bare:ensureprebuilds:llamacpp && bun run bare:ensureprebuilds:asr && bun run bare:ensureprebuilds:embeddings",
     "prepare:husky": "bun run husky",
     "bare:example": "bare ./scripts/bare-bootstrap.js",
+    "contract:export": "tsx ./scripts/export-contract.ts",
+    "contract:check": "tsx ./scripts/export-contract.ts --check",
+    "check:resource-collectors": "tsx ./scripts/check-resource-collectors-packaging.ts",
     "check-models": "tsx ./models/update-models/index.ts --check",
     "check-models:hook": "tsx ./models/update-models/index.ts --check --non-blocking",
-    "update-models": "tsx ./models/update-models/index.ts",
+    "update-models": "tsx ./models/update-models/index.ts && bun run contract:export",
     "changelog:generate": "node ../../scripts/sdk/generate-changelog-sdk-pod.cjs --package=sdk && prettier --write changelog"
   },
   "dependencies": {
-    "@qvac/bci-whispercpp": "^0.4.1",
-    "@qvac/classification-ggml": "^0.10.2",
+    "@qvac/audiogen-ggml": "^0.1.0",
+    "@qvac/asr-ggml": "^0.1.0",
+    "@qvac/bci-whispercpp": "^0.6.0",
+    "@qvac/classification-ggml": "^0.15.1",
     "@qvac/decoder-audio": "^0.5.0",
-    "@qvac/diffusion-cpp": "^0.13.3",
-    "@qvac/embed-llamacpp": "^0.26.2",
+    "@qvac/diffusion-cpp": "^0.17.0",
+    "@qvac/embed-llamacpp": "^0.30.1",
     "@qvac/error": "^0.1.1",
     "@qvac/langdetect-text": "^0.1.2",
-    "@qvac/llm-llamacpp": "^0.36.3",
+    "@qvac/llm-llamacpp": "^0.39.3",
     "@qvac/logging": "^0.1.0",
-    "@qvac/ocr-ggml": "^0.10.2",
+    "@qvac/ocr-ggml": "^0.13.1",
     "@qvac/rag": "^0.6.4",
     "@qvac/registry-client": "^0.6.1",
-    "@qvac/transcription-parakeet": "^0.9.1",
-    "@qvac/transcription-whispercpp": "^0.11.1",
-    "@qvac/translation-nmtcpp": "^7.2.2",
-    "@qvac/tts-ggml": "^0.4.2",
-    "@qvac/vla-ggml": "^0.11.2",
+    "@qvac/translation-nmtcpp": "^8.3.0",
+    "@qvac/tts-ggml": "^0.6.0",
+    "@qvac/vla-ggml": "^0.16.2",
     "bare-abort-controller": "^1.0.0",
+    "bare-cpu-info": "0.1.1",
     "bare-crypto": "^1.15.0",
     "bare-env": "^3.0.0",
     "bare-fetch": "^3.0.1",
     "bare-fs": "^4.5.1",
+    "bare-gpu-info": "0.1.1",
     "bare-net": "^2.3.2",
     "bare-os": "^3.6.2",
     "bare-pack": "^2.0.1",
@@ -251,6 +261,7 @@
     "@types/node": "^24.2.1",
     "@types/semver": "^7.7.1",
     "@types/tar-stream": "^3.1.4",
+    "ajv": "8.20.0",
     "bare-process": "^4.4.1",
     "bare-readline": "^1.2.0",
     "bare-stdio": "^1.0.2",
@@ -267,14 +278,16 @@
     "expo-device": "^8.0.10",
     "expo-file-system": "^19.0.21",
     "husky": "^9.1.7",
+    "mongodb": "^7.5.0",
     "pear-pipe": "^1.0.6",
     "prettier": "^3.9.4",
     "prettier-config-holepunch": "^2.0.0",
     "react-native-bare-kit": "^0.14.0",
     "tsc-alias": "^1.8.17",
-    "tsx": "^4.21.0",
+    "tsx": "4.23.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.39.0"
+    "typescript-eslint": "^8.39.0",
+    "@qvac/infer-base": "0.4.2"
   },
   "peerDependencies": {
     "@electron-forge/plugin-base": "^7.11.1",
@@ -312,5 +325,10 @@
       "optional": true
     }
   },
+  "overrides": {
+    "tar": "^7.5.22",
+    "shell-quote": "^1.10.0",
+    "@electron/rebuild": "^4.2.0"
+  },
   "patchedDependencies": {}
 }