@qvac/sdk 0.7.0 → 0.8.0

package/dist/server/rpc/profiling/operation-metrics.js

@@ -0,0 +1,199 @@
+/**
+ * Declarative extraction of operation-level metrics from request/response data.
+ * Used by operation wrappers to capture handler-specific profiling events.
+ */
+const metricsRegistry = new Map();
+function extractDownloadStatsGauges(stats, gauges) {
+    if (stats?.downloadTimeMs !== undefined) {
+        gauges["downloadTime"] = stats.downloadTimeMs;
+    }
+    if (stats?.totalBytesDownloaded !== undefined) {
+        gauges["totalBytesDownloaded"] = stats.totalBytesDownloaded;
+    }
+    if (stats?.downloadSpeedBps !== undefined) {
+        gauges["downloadSpeedBps"] = stats.downloadSpeedBps;
+    }
+}
+export function registerOperationMetrics(config) {
+    metricsRegistry.set(config.op, config);
+}
+export function buildOperationEvent(op, profileId, ts, executionMs, request, finalResponse, ttfb) {
+    const config = metricsRegistry.get(op);
+    if (!config) {
+        return {
+            ts,
+            op,
+            kind: "handler",
+            profileId,
+            ms: executionMs,
+        };
+    }
+    const gauges = {};
+    if (ttfb !== undefined) {
+        gauges["ttfb"] = ttfb;
+    }
+    if (config.fromRequest && request) {
+        const extracted = config.fromRequest(request);
+        if (extracted)
+            Object.assign(gauges, extracted);
+    }
+    if (config.fromFinalChunk && finalResponse) {
+        const extracted = config.fromFinalChunk(finalResponse);
+        if (extracted)
+            Object.assign(gauges, extracted);
+    }
+    if (config.fromResult && finalResponse) {
+        const extracted = config.fromResult(finalResponse);
+        if (extracted)
+            Object.assign(gauges, extracted);
+    }
+    const requestTags = config.getTags?.(request);
+    const resultTags = config.getTagsFromResult?.(finalResponse);
+    const tags = { ...requestTags, ...resultTags };
+    const hasGauges = Object.keys(gauges).length > 0;
+    const hasTags = Object.keys(tags).length > 0;
+    const event = {
+        ts,
+        op: config.op,
+        kind: config.kind,
+        profileId,
+        ms: executionMs,
+    };
+    if (hasGauges) {
+        event.gauges = gauges;
+    }
+    if (hasTags) {
+        event.tags = tags;
+    }
+    return event;
+}
+registerOperationMetrics({
+    op: "completionStream",
+    kind: "handler",
+    getTags: (req) => (req.modelId ? { modelId: req.modelId } : {}),
+    fromFinalChunk: (res) => {
+        if (!res.stats)
+            return undefined;
+        const gauges = {};
+        if (res.stats.timeToFirstToken !== undefined)
+            gauges["timeToFirstToken"] = res.stats.timeToFirstToken;
+        if (res.stats.tokensPerSecond !== undefined)
+            gauges["tokensPerSecond"] = res.stats.tokensPerSecond;
+        if (res.stats.cacheTokens !== undefined)
+            gauges["cacheTokens"] = res.stats.cacheTokens;
+        return Object.keys(gauges).length > 0 ? gauges : undefined;
+    },
+});
+registerOperationMetrics({
+    op: "translate",
+    kind: "handler",
+    getTags: (req) => (req.modelId ? { modelId: req.modelId } : {}),
+    fromFinalChunk: (res) => {
+        if (!res.stats)
+            return undefined;
+        const gauges = {};
+        if (res.stats.processedTokens !== undefined)
+            gauges["processedTokens"] = res.stats.processedTokens;
+        if (res.stats.processingTime !== undefined)
+            gauges["processingTime"] = res.stats.processingTime;
+        return Object.keys(gauges).length > 0 ? gauges : undefined;
+    },
+});
+registerOperationMetrics({
+    op: "transcribeStream",
+    kind: "handler",
+    getTags: (req) => (req.modelId ? { modelId: req.modelId } : {}),
+});
+registerOperationMetrics({
+    op: "textToSpeech",
+    kind: "handler",
+    getTags: (req) => (req.modelId ? { modelId: req.modelId } : {}),
+});
+registerOperationMetrics({
+    op: "embed",
+    kind: "handler",
+    getTags: (req) => (req.modelId ? { modelId: req.modelId } : {}),
+});
+registerOperationMetrics({
+    op: "ocrStream",
+    kind: "handler",
+    getTags: (req) => (req.modelId ? { modelId: req.modelId } : {}),
+    fromFinalChunk: (res) => {
+        if (!res.stats)
+            return undefined;
+        const gauges = {};
+        if (res.stats.detectionTime !== undefined)
+            gauges["detectionTime"] = res.stats.detectionTime;
+        if (res.stats.recognitionTime !== undefined)
+            gauges["recognitionTime"] = res.stats.recognitionTime;
+        if (res.stats.totalTime !== undefined)
+            gauges["totalTime"] = res.stats.totalTime;
+        return Object.keys(gauges).length > 0 ? gauges : undefined;
+    },
+});
+registerOperationMetrics({
+    op: "pluginInvoke",
+    kind: "handler",
+    getTags: (req) => {
+        const tags = {};
+        if (req.modelId)
+            tags["modelId"] = req.modelId;
+        if (req.handler)
+            tags["handler"] = req.handler;
+        return tags;
+    },
+});
+registerOperationMetrics({
+    op: "pluginInvokeStream",
+    kind: "handler",
+    getTags: (req) => {
+        const tags = {};
+        if (req.modelId)
+            tags["modelId"] = req.modelId;
+        if (req.handler)
+            tags["handler"] = req.handler;
+        return tags;
+    },
+});
+registerOperationMetrics({
+    op: "loadModel",
+    kind: "handler",
+    getTags: (req) => (req.modelType ? { modelType: req.modelType } : {}),
+    getTagsFromResult: (res) => {
+        const sourceType = res.__profilingMeta?.sourceType;
+        return sourceType ? { sourceType } : undefined;
+    },
+    fromResult: (res) => {
+        const meta = res.__profilingMeta;
+        if (!meta)
+            return undefined;
+        const gauges = {};
+        extractDownloadStatsGauges(meta.downloadStats, gauges);
+        if (meta.modelInitializationTimeMs !== undefined) {
+            gauges["modelInitializationTime"] = meta.modelInitializationTimeMs;
+        }
+        if (meta.totalLoadTimeMs !== undefined) {
+            gauges["totalLoadTime"] = meta.totalLoadTimeMs;
+        }
+        return Object.keys(gauges).length > 0 ? gauges : undefined;
+    },
+});
+registerOperationMetrics({
+    op: "downloadAsset",
+    kind: "handler",
+    getTagsFromResult: (res) => {
+        const sourceType = res.__profilingMeta?.sourceType;
+        return sourceType ? { sourceType } : undefined;
+    },
+    fromResult: (res) => {
+        const meta = res.__profilingMeta;
+        if (!meta)
+            return undefined;
+        const gauges = {};
+        extractDownloadStatsGauges(meta.downloadStats, gauges);
+        if (meta.totalDownloadTimeMs !== undefined) {
+            gauges["totalDownloadTime"] = meta.totalDownloadTimeMs;
+        }
+        return Object.keys(gauges).length > 0 ? gauges : undefined;
+    },
+});

package/dist/server/rpc/profiling/operation-wrappers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Generic wrappers for profiling handler execution.
+ * Used to wrap dispatch/invoke functions with timing capture.
+ */
+import { type PerCallProfiling } from "../../../schemas/index";
+export interface ProfiledReplyOptions<TRequest> {
+    op: string;
+    request: TRequest;
+    perCall?: PerCallProfiling;
+}
+export interface ProfiledStreamOptions<TRequest> {
+    op: string;
+    request: TRequest;
+    perCall?: PerCallProfiling;
+}
+export declare function profileReplyHandler<TRequest, TResponse>(options: ProfiledReplyOptions<TRequest>, handler: () => Promise<TResponse>): Promise<TResponse>;
+export declare function profileStreamHandler<TRequest, TResponse>(options: ProfiledStreamOptions<TRequest>, handler: () => AsyncGenerator<TResponse>): AsyncGenerator<TResponse>;
+//# sourceMappingURL=operation-wrappers.d.ts.map

package/dist/server/rpc/profiling/operation-wrappers.js

@@ -0,0 +1,124 @@
+/**
+ * Generic wrappers for profiling handler execution.
+ * Used to wrap dispatch/invoke functions with timing capture.
+ */
+import { PROFILING_KEY, } from "../../../schemas/index.js";
+import { nowMs, generateProfileId } from "../../../profiling/clock.js";
+import { record, shouldProfile } from "../../../profiling/controller.js";
+import { buildOperationEvent } from "./operation-metrics.js";
+function getRequestProfilingMeta(request) {
+    if (!request || typeof request !== "object") {
+        return undefined;
+    }
+    const meta = request[PROFILING_KEY];
+    if (!meta || typeof meta !== "object") {
+        return undefined;
+    }
+    return meta;
+}
+function resolvePerCallProfiling(options) {
+    if (options.perCall) {
+        return options.perCall;
+    }
+    const meta = getRequestProfilingMeta(options.request);
+    if (!meta) {
+        return undefined;
+    }
+    if (meta.enabled === false) {
+        return { enabled: false };
+    }
+    return {
+        enabled: true,
+        includeServerBreakdown: meta.includeServer,
+        mode: meta.mode,
+    };
+}
+function recordOperationEvent(params) {
+    const event = buildOperationEvent(params.options.op, params.profileId, params.startTs, params.executionMs, params.options.request, params.finalResponse, params.ttfb);
+    if (!event)
+        return;
+    if (params.errored) {
+        event.tags = { ...event.tags, error: "true" };
+    }
+    if (params.count !== undefined && params.count > 0) {
+        event.count = params.count;
+    }
+    record(event);
+}
+export async function profileReplyHandler(options, handler) {
+    const perCall = resolvePerCallProfiling(options);
+    if (!shouldProfile(options.op, perCall)) {
+        return handler();
+    }
+    const profileId = generateProfileId();
+    const startTs = nowMs();
+    try {
+        const result = await handler();
+        const executionMs = nowMs() - startTs;
+        recordOperationEvent({
+            options,
+            profileId,
+            startTs,
+            executionMs,
+            finalResponse: result,
+        });
+        return result;
+    }
+    catch (error) {
+        const executionMs = nowMs() - startTs;
+        recordOperationEvent({
+            options,
+            profileId,
+            startTs,
+            executionMs,
+            errored: true,
+        });
+        throw error;
+    }
+}
+export async function* profileStreamHandler(options, handler) {
+    const perCall = resolvePerCallProfiling(options);
+    if (!shouldProfile(options.op, perCall)) {
+        yield* handler();
+        return;
+    }
+    const profileId = generateProfileId();
+    const startTs = nowMs();
+    let ttfb;
+    let lastChunk;
+    let chunkCount = 0;
+    try {
+        for await (const chunk of handler()) {
+            if (ttfb === undefined) {
+                ttfb = nowMs() - startTs;
+            }
+            chunkCount++;
+            lastChunk = chunk;
+            yield chunk;
+        }
+        const executionMs = nowMs() - startTs;
+        recordOperationEvent({
+            options,
+            profileId,
+            startTs,
+            executionMs,
+            finalResponse: lastChunk,
+            ttfb,
+            count: chunkCount,
+        });
+    }
+    catch (error) {
+        const executionMs = nowMs() - startTs;
+        recordOperationEvent({
+            options,
+            profileId,
+            startTs,
+            executionMs,
+            finalResponse: lastChunk,
+            ttfb,
+            count: chunkCount,
+            errored: true,
+        });
+        throw error;
+    }
+}

package/dist/server/rpc/profiling/profiler.d.ts

@@ -0,0 +1,13 @@
+import { type Response, type ProfilingRequestMeta } from "../../../schemas/index";
+import { type ServerProfilingContext } from "./context";
+export type ServerProfiler = {
+    markRequestParsed: (ms: number) => void;
+    markRequestValidated: (ms: number) => void;
+    startHandler: () => void;
+    endHandler: () => void;
+    serialize: (response?: Response, final?: boolean) => string;
+    serializeError: (json: string) => string;
+    getContext: () => ServerProfilingContext | undefined;
+};
+export declare function createServerProfiler(meta?: ProfilingRequestMeta): ServerProfiler;
+//# sourceMappingURL=profiler.d.ts.map

package/dist/server/rpc/profiling/profiler.js

@@ -0,0 +1,97 @@
+import { nowMs } from "../../../profiling/index.js";
+import { responseSchema, DELEGATION_BREAKDOWN_KEY, OPERATION_EVENT_KEY, PROFILING_TRAILER_KEY, } from "../../../schemas/index.js";
+import { createProfilingContext, injectProfilingIntoString, } from "./context.js";
+const noopProfiler = {
+    markRequestParsed: () => { },
+    markRequestValidated: () => { },
+    startHandler: () => { },
+    endHandler: () => { },
+    serialize: (response) => {
+        if (!response)
+            return "";
+        const extended = response;
+        const delegation = extended[DELEGATION_BREAKDOWN_KEY];
+        const operation = extended[OPERATION_EVENT_KEY];
+        const json = JSON.stringify(responseSchema.parse(response));
+        if (delegation || operation) {
+            const opts = {};
+            if (delegation)
+                opts.delegation = delegation;
+            if (operation)
+                opts.operation = operation;
+            return injectProfilingIntoString(json, opts);
+        }
+        return json;
+    },
+    serializeError: (json) => json,
+    getContext: () => undefined,
+};
+function createActiveProfiler(meta) {
+    const ctx = createProfilingContext(meta);
+    let handlerStart = 0;
+    let handlerEnded = false;
+    let cachedDelegation;
+    let cachedOperation;
+    return {
+        markRequestParsed: (ms) => {
+            ctx.jsonParseMs = ms;
+        },
+        markRequestValidated: (ms) => {
+            ctx.zodValidationMs = ms;
+        },
+        startHandler: () => {
+            handlerStart = nowMs();
+            handlerEnded = false;
+        },
+        endHandler: () => {
+            if (handlerEnded)
+                return;
+            handlerEnded = true;
+            ctx.handlerExecutionMs = nowMs() - handlerStart;
+        },
+        serialize: (response, final = true) => {
+            if (!response) {
+                const opts = { ctx };
+                if (cachedDelegation)
+                    opts.delegation = cachedDelegation;
+                if (cachedOperation)
+                    opts.operation = cachedOperation;
+                return injectProfilingIntoString(`{"${PROFILING_TRAILER_KEY}":true}`, opts);
+            }
+            const extended = response;
+            const delegation = extended[DELEGATION_BREAKDOWN_KEY];
+            const operation = extended[OPERATION_EVENT_KEY];
+            if (delegation)
+                cachedDelegation = delegation;
+            if (operation)
+                cachedOperation = operation;
+            const zodStart = nowMs();
+            const validated = responseSchema.parse(response);
+            ctx.responseZodValidationMs =
+                (ctx.responseZodValidationMs ?? 0) + (nowMs() - zodStart);
+            const stringifyStart = nowMs();
+            const json = JSON.stringify(validated);
+            ctx.responseStringifyMs =
+                (ctx.responseStringifyMs ?? 0) + (nowMs() - stringifyStart);
+            if (final) {
+                const opts = { ctx };
+                if (delegation)
+                    opts.delegation = delegation;
+                if (operation)
+                    opts.operation = operation;
+                return injectProfilingIntoString(json, opts);
+            }
+            return json;
+        },
+        serializeError: (json) => injectProfilingIntoString(json, { ctx }),
+        getContext: () => ctx,
+    };
+}
+export function createServerProfiler(meta) {
+    if (meta?.includeServer &&
+        typeof meta.id === "string" &&
+        meta.id.length > 0) {
+        return createActiveProfiler(meta);
+    }
+    return noopProfiler;
+}

package/dist/server/utils/cache.d.ts

@@ -20,6 +20,7 @@ export declare function getShardPath(hyperdriveKey: string, shardFilename: strin
 /**
  * Check if all shards exist and are valid (size + checksum check)
  * Returns array of missing/invalid shard indices (0-based)
+ * @param onChecksumTimeMs - Optional callback to report checksum validation time
  */
-export declare function checkShardCompleteness(hyperdriveKey: string, shardFilenames: readonly string[], shardMetadata: readonly ShardFileMetadata[]): Promise<number[]>;
+export declare function checkShardCompleteness(hyperdriveKey: string, shardFilenames: readonly string[], shardMetadata: readonly ShardFileMetadata[], onChecksumTimeMs?: (ms: number) => void): Promise<number[]>;
 //# sourceMappingURL=cache.d.ts.map

package/dist/server/utils/cache.js

@@ -5,6 +5,7 @@ import { getConfiguredCacheDir } from "../bare/registry/config-registry.js";
 import { calculateFileChecksum } from "./checksum.js";
 import { validateAndJoinPath } from "./path-security.js";
 import { getServerLogger } from "../../logging/index.js";
+import { nowMs } from "../../profiling/index.js";
 const logger = getServerLogger();
 export function getCacheDir(subDir) {
     const homeDir = getEnv().HOME_DIR;
@@ -79,8 +80,9 @@ export function getShardPath(hyperdriveKey, shardFilename) {
 /**
  * Check if all shards exist and are valid (size + checksum check)
  * Returns array of missing/invalid shard indices (0-based)
+ * @param onChecksumTimeMs - Optional callback to report checksum validation time
  */
-export async function checkShardCompleteness(hyperdriveKey, shardFilenames, shardMetadata) {
+export async function checkShardCompleteness(hyperdriveKey, shardFilenames, shardMetadata, onChecksumTimeMs) {
     const invalidIndices = [];
     for (let i = 0; i < shardFilenames.length; i++) {
         const shardPath = getShardPath(hyperdriveKey, shardFilenames[i]);
@@ -97,7 +99,9 @@ export async function checkShardCompleteness(hyperdriveKey, shardFilenames, shar
                 continue;
             }
             if (fileMeta.sha256Checksum) {
+                const start = nowMs();
                 const actualChecksum = await calculateFileChecksum(shardPath);
+                onChecksumTimeMs?.(nowMs() - start);
                 if (actualChecksum !== fileMeta.sha256Checksum) {
                     logger.warn(`File ${i + 1} checksum mismatch for ${fileMeta.filename}. Expected: ${fileMeta.sha256Checksum}. Actual: ${actualChecksum}. Will re-download.`);
                     invalidIndices.push(i);

package/dist/server/utils/checksum.d.ts

@@ -1,2 +1,4 @@
+import type { DownloadMetricsHooks } from "../rpc/handlers/load-model/types";
 export declare function calculateFileChecksum(filePath: string): Promise<string>;
+export declare function measureChecksum(filePath: string, hooks?: DownloadMetricsHooks): Promise<string>;
 //# sourceMappingURL=checksum.d.ts.map

package/dist/server/utils/checksum.js

@@ -1,5 +1,6 @@
 import fs from "bare-fs";
 import crypto from "bare-crypto";
+import { nowMs } from "../../profiling/index.js";
 export async function calculateFileChecksum(filePath) {
     return new Promise((resolve, reject) => {
         try {
@@ -22,3 +23,9 @@ export async function calculateFileChecksum(filePath) {
         }
     });
 }
+export async function measureChecksum(filePath, hooks) {
+    const start = nowMs();
+    const checksum = await calculateFileChecksum(filePath);
+    hooks?.addChecksumValidationTimeMs(nowMs() - start);
+    return checksum;
+}

package/dist/server/utils/formatting.d.ts

@@ -2,6 +2,12 @@
  * Generate a short hash (16 characters) from any input string
  */
 export declare function generateShortHash(input: string): string;
+/**
+ * Create a stable, deterministic string representation of a config object.
+ * - Recursively sorts all object keys
+ * - Normalizes ModelDescriptor objects to their src string
+ */
+export declare function canonicalConfigString(config: Record<string, unknown> | undefined): string;
 /**
  * Calculate progress percentage with bounds checking and consistent formatting
  * @param current - Current progress value

package/dist/server/utils/formatting.js

@@ -9,6 +9,41 @@ export function generateShortHash(input) {
         .digest("hex");
     return hash.substring(0, 16);
 }
+function isModelDescriptor(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "src" in value &&
+        typeof value.src === "string");
+}
+function normalizeValue(value) {
+    if (isModelDescriptor(value)) {
+        return value.src;
+    }
+    if (Array.isArray(value)) {
+        return value.map(normalizeValue);
+    }
+    if (typeof value === "object" && value !== null) {
+        return normalizeConfig(value);
+    }
+    return value;
+}
+function normalizeConfig(config) {
+    const result = {};
+    for (const key of Object.keys(config).sort()) {
+        result[key] = normalizeValue(config[key]);
+    }
+    return result;
+}
+/**
+ * Create a stable, deterministic string representation of a config object.
+ * - Recursively sorts all object keys
+ * - Normalizes ModelDescriptor objects to their src string
+ */
+export function canonicalConfigString(config) {
+    if (!config)
+        return "{}";
+    return JSON.stringify(normalizeConfig(config));
+}
 /**
  * Calculate progress percentage with bounds checking and consistent formatting
  * @param current - Current progress value

package/dist/server/worker.js

@@ -4,7 +4,7 @@
 import { initializeWorkerCore, ensureRPCSetup } from "./worker-core.js";
 import { registerPlugin } from "./plugins/index.js";
 import { getServerLogger } from "../logging/index.js";
-import { llmPlugin, embeddingsPlugin, whisperPlugin, nmtPlugin, ttsPlugin, ocrPlugin, } from "./bare/plugins/index.js";
+import { llmPlugin, embeddingsPlugin, whisperPlugin, parakeetPlugin, nmtPlugin, ttsPlugin, ocrPlugin, } from "./bare/plugins/index.js";
 const { hasRPCConfig } = initializeWorkerCore();
 const logger = getServerLogger();
 logger.info("🐻 Hello from Bare");
@@ -12,6 +12,7 @@ logger.info("🐻 Hello from Bare");
 registerPlugin(llmPlugin);
 registerPlugin(embeddingsPlugin);
 registerPlugin(whisperPlugin);
+registerPlugin(parakeetPlugin);
 registerPlugin(nmtPlugin);
 registerPlugin(ttsPlugin);
 registerPlugin(ocrPlugin);

package/dist/utils/errors-client.d.ts

@@ -131,4 +131,7 @@ export declare class SetConfigFailedError extends QvacErrorBase {
 export declare class ModelRegistryQueryFailedError extends QvacErrorBase {
     constructor(details?: string, cause?: unknown);
 }
+export declare class ProfilerInvalidCapacityError extends QvacErrorBase {
+    constructor(minCapacity: number, cause?: unknown);
+}
 //# sourceMappingURL=errors-client.d.ts.map

package/dist/utils/errors-client.js

@@ -232,3 +232,9 @@ export class ModelRegistryQueryFailedError extends QvacErrorBase {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.QVAC_MODEL_REGISTRY_QUERY_FAILED, details ? [details] : undefined, cause));
     }
 }
+// ============== Profiler Errors ==============
+export class ProfilerInvalidCapacityError extends QvacErrorBase {
+    constructor(minCapacity, cause) {
+        super(createErrorOptions(SDK_CLIENT_ERROR_CODES.PROFILER_INVALID_CAPACITY, [minCapacity], cause));
+    }
+}

package/dist/utils/errors-server.d.ts

@@ -35,6 +35,9 @@ export declare class TtsArtifactsRequiredError extends QvacErrorBase {
 export declare class TtsReferenceAudioRequiredError extends QvacErrorBase {
     constructor(cause?: unknown);
 }
+export declare class ParakeetArtifactsRequiredError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
 export declare class ModelUnloadFailedError extends QvacErrorBase {
     constructor(modelId?: string, cause?: unknown);
 }
@@ -209,6 +212,12 @@ export declare class PluginResponseValidationFailedError extends QvacErrorBase {
 export declare class PluginAlreadyRegisteredError extends QvacErrorBase {
     constructor(modelType: string, cause?: unknown);
 }
+export declare class PluginModelTypeReservedError extends QvacErrorBase {
+    constructor(modelType: string, cause?: unknown);
+}
+export declare class PluginLoadConfigValidationFailedError extends QvacErrorBase {
+    constructor(modelType: string, details: string, cause?: unknown);
+}
 export declare class PluginHandlerTypeMismatchError extends QvacErrorBase {
     constructor(handlerName: string, expected: string, actual: string, cause?: unknown);
 }

package/dist/utils/errors-server.js

@@ -63,6 +63,11 @@ export class TtsReferenceAudioRequiredError extends QvacErrorBase {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.TTS_REFERENCE_AUDIO_REQUIRED, undefined, cause));
     }
 }
+export class ParakeetArtifactsRequiredError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PARAKEET_ARTIFACTS_REQUIRED, details ? [details] : undefined, cause));
+    }
+}
 // ============== Model Unloading Errors ==============
 export class ModelUnloadFailedError extends QvacErrorBase {
     constructor(modelId, cause) {
@@ -366,6 +371,16 @@ export class PluginAlreadyRegisteredError extends QvacErrorBase {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_ALREADY_REGISTERED, [modelType], cause));
     }
 }
+export class PluginModelTypeReservedError extends QvacErrorBase {
+    constructor(modelType, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_MODEL_TYPE_RESERVED, [modelType], cause));
+    }
+}
+export class PluginLoadConfigValidationFailedError extends QvacErrorBase {
+    constructor(modelType, details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_LOAD_CONFIG_VALIDATION_FAILED, [modelType, details], cause));
+    }
+}
 export class PluginHandlerTypeMismatchError extends QvacErrorBase {
     constructor(handlerName, expected, actual, cause) {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_HANDLER_TYPE_MISMATCH, [handlerName, expected, actual], cause));

package/dist/utils/global-singleton.d.ts

@@ -0,0 +1,2 @@
+export declare function getGlobalSingleton<T>(key: symbol, create: () => T): T;
+//# sourceMappingURL=global-singleton.d.ts.map

package/dist/utils/global-singleton.js

@@ -0,0 +1,10 @@
+export function getGlobalSingleton(key, create) {
+    const global = globalThis;
+    const existing = global[key];
+    if (existing !== undefined) {
+        return existing;
+    }
+    const value = create();
+    global[key] = value;
+    return value;
+}