@qvac/sdk 0.9.2 → 0.10.1

package/dist/server/rpc/handlers/load-model/resolve.js

@@ -63,20 +63,6 @@ async function resolveLocalOrCachedFile(modelIdOrPath) {
         }
     }
 }
-function selectDownloaders(mode) {
-    if (mode === "stats") {
-        return {
-            http: downloadModelFromHttpWithStats,
-            registry: downloadModelFromRegistryWithStats,
-            hyperdrive: downloadModelFromHyperdriveWithStats,
-        };
-    }
-    return {
-        http: downloadModelFromHttp,
-        registry: downloadModelFromRegistry,
-        hyperdrive: downloadModelFromHyperdrive,
-    };
-}
 function isDownloadResult(value) {
     return value !== null && typeof value === "object" && "path" in value;
 }
@@ -88,9 +74,8 @@ function buildResult(pathOrResult, sourceType) {
     }
     return { path: pathOrResult, sourceType };
 }
-async function resolveModelPathCore(modelSrc, progressCallback, seed, mode) {
+async function resolveModelPathCore(modelSrc, progressCallback, seed, mode, hooks) {
     const srcString = modelInputToSrcSchema.parse(modelSrc);
-    const downloaders = selectDownloaders(mode);
     // Parse hyperdrive URLs if present
     let hyperdriveKey;
     let actualModelSrc = srcString;
@@ -106,7 +91,9 @@ async function resolveModelPathCore(modelSrc, progressCallback, seed, mode) {
         // Look up model metadata for checksum validation
         const modelMetadata = getModelByPath(registryPath);
         const expectedChecksum = modelMetadata?.sha256Checksum;
-        const result = await downloaders.registry(registryPath, registrySource, progressCallback, expectedChecksum);
+        const result = mode === "stats"
+            ? await downloadModelFromRegistryWithStats(registryPath, registrySource, progressCallback, expectedChecksum, hooks)
+            : await downloadModelFromRegistry(registryPath, registrySource, progressCallback, expectedChecksum, hooks);
         logger.info(`Loaded Model to ${isDownloadResult(result) ? result.path : result}`);
         return buildResult(result, "registry");
     }
@@ -118,14 +105,18 @@ async function resolveModelPathCore(modelSrc, progressCallback, seed, mode) {
     if (actualModelSrc.startsWith("http://") ||
         actualModelSrc.startsWith("https://")) {
         logger.info(`Loading from HTTP URL: ${actualModelSrc}`);
-        const result = await downloaders.http(actualModelSrc, progressCallback);
+        const result = mode === "stats"
+            ? await downloadModelFromHttpWithStats(actualModelSrc, progressCallback, hooks)
+            : await downloadModelFromHttp(actualModelSrc, progressCallback, hooks);
         logger.info(`Loaded Model to ${isDownloadResult(result) ? result.path : result}`);
         return buildResult(result, "http");
     }
     // Hyperdrive source
     if (hyperdriveKey) {
         logger.info(`Loading from hyperdrive: ${hyperdriveKey}`);
-        const result = await downloaders.hyperdrive(hyperdriveKey, actualModelSrc, seed, progressCallback);
+        const result = mode === "stats"
+            ? await downloadModelFromHyperdriveWithStats(hyperdriveKey, actualModelSrc, seed, progressCallback, hooks)
+            : await downloadModelFromHyperdrive(hyperdriveKey, actualModelSrc, seed, progressCallback, hooks);
         return buildResult(result, "hyperdrive");
     }
     // Filesystem source (local files, cached files)
@@ -146,10 +137,10 @@ async function resolveModelPathCore(modelSrc, progressCallback, seed, mode) {
     }
     return { path: resolvedPath, sourceType: "filesystem" };
 }
-export async function resolveModelPath(modelSrc, progressCallback, seed) {
-    const result = await resolveModelPathCore(modelSrc, progressCallback, seed, "base");
+export async function resolveModelPath(modelSrc, progressCallback, seed, hooks) {
+    const result = await resolveModelPathCore(modelSrc, progressCallback, seed, "base", hooks);
     return result.path;
 }
-export async function resolveModelPathWithStats(modelSrc, progressCallback, seed) {
-    return resolveModelPathCore(modelSrc, progressCallback, seed, "stats");
+export async function resolveModelPathWithStats(modelSrc, progressCallback, seed, hooks) {
+    return resolveModelPathCore(modelSrc, progressCallback, seed, "stats", hooks);
 }

package/dist/server/rpc/handlers/load-model/types.d.ts

@@ -5,6 +5,7 @@ export interface DownloadStats {
     downloadSpeedBps?: number;
     checksumValidationTimeMs?: number;
     cacheHit?: boolean;
+    sharedTransfer?: boolean;
 }
 export interface ResolveResult {
     path: string;
@@ -15,10 +16,12 @@ export interface DownloadResult {
     path: string;
     stats?: DownloadStats;
 }
-export interface DownloadMetricsHooks {
-    markCacheHit: () => void;
-    markCacheMiss: () => void;
-    addChecksumValidationTimeMs: (durationMs: number) => void;
+export interface DownloadHooks {
+    onDownloadKey?: (key: string) => void;
+    markCacheHit?: () => void;
+    markCacheMiss?: () => void;
+    markSharedTransfer?: () => void;
+    addChecksumValidationTimeMs?: (durationMs: number) => void;
 }
 export interface LoadModelProfilingMeta {
     sourceType?: string;
@@ -26,4 +29,8 @@ export interface LoadModelProfilingMeta {
     modelInitializationTimeMs?: number;
     totalLoadTimeMs?: number;
 }
+export declare function buildDownloadProfilingFields(downloadStats: DownloadStats | undefined, sourceType?: string): {
+    gauges: Record<string, number>;
+    tags: Record<string, string>;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/server/rpc/handlers/load-model/types.js

@@ -1 +1,28 @@
-export {};
+export function buildDownloadProfilingFields(downloadStats, sourceType) {
+    const gauges = {};
+    const tags = {};
+    if (downloadStats) {
+        if (downloadStats.downloadTimeMs !== undefined) {
+            gauges["downloadTime"] = downloadStats.downloadTimeMs;
+        }
+        if (downloadStats.totalBytesDownloaded !== undefined) {
+            gauges["totalBytesDownloaded"] = downloadStats.totalBytesDownloaded;
+        }
+        if (downloadStats.downloadSpeedBps !== undefined) {
+            gauges["downloadSpeedBps"] = downloadStats.downloadSpeedBps;
+        }
+        if (downloadStats.checksumValidationTimeMs !== undefined) {
+            gauges["checksumValidationTime"] = downloadStats.checksumValidationTimeMs;
+        }
+        if (downloadStats.cacheHit !== undefined) {
+            tags["cacheHit"] = downloadStats.cacheHit ? "true" : "false";
+        }
+        if (downloadStats.sharedTransfer) {
+            tags["sharedTransfer"] = "true";
+        }
+    }
+    if (sourceType) {
+        tags["sourceType"] = sourceType;
+    }
+    return { gauges, tags };
+}

package/dist/server/rpc/handlers/load-model-delegated.js

@@ -12,11 +12,10 @@ export async function handleLoadModelDelegated(request, options) {
         throw new ModelLoadFailedError("Delegate information is required for delegated load model");
     }
     const { delegate } = request;
-    const { topic, providerPublicKey, timeout, healthCheckTimeout, fallbackToLocal, forceNewConnection, } = delegate;
+    const { providerPublicKey, timeout, healthCheckTimeout, fallbackToLocal, forceNewConnection, } = delegate;
     try {
         logger.info(`📤 Sending delegated loadModel request to provider: ${providerPublicKey}${timeout ? `, timeout: ${timeout}ms` : ""}${forceNewConnection ? " (forcing new connection)" : ""}`);
-        // Create RPC instance for this HyperSwarm peer
-        const rpc = await getRPC(topic, providerPublicKey, {
+        const rpc = await getRPC(providerPublicKey, {
             timeout,
             healthCheckTimeout,
             forceNewConnection,
@@ -77,7 +76,6 @@ export async function handleLoadModelDelegated(request, options) {
             modelInputToSrcSchema.parse(request.modelSrc) ||
             `delegated-${Date.now()}`;
         const delegateOptions = {
-            topic,
             providerPublicKey,
         };
         if (timeout !== undefined) {

package/dist/server/rpc/handlers/plugin-dispatch.js

@@ -1,13 +1,13 @@
 import { getModelEntry } from "../../bare/registry/model-registry.js";
-import { getPlugin } from "../../plugins/index.js";
+import { getAllPlugins, getPlugin } from "../../plugins/index.js";
 import { profileReplyHandler, profileStreamHandler, } from "../profiling/index.js";
-import { ModelNotFoundError, ModelIsDelegatedError, PluginNotFoundError, PluginHandlerNotFoundError, PluginHandlerTypeMismatchError, } from "../../../utils/errors-server.js";
+import { ModelNotFoundError, ModelIsDelegatedError, ModelOperationNotSupportedError, PluginNotFoundError, PluginHandlerTypeMismatchError, } from "../../../utils/errors-server.js";
 function resolvePluginHandlerDef(modelId, handlerName) {
     const entry = getModelEntry(modelId);
     if (!entry) {
         throw new ModelNotFoundError(modelId);
     }
-    if (entry.isDelegated || !entry.local) {
+    if (entry.isDelegated) {
         throw new ModelIsDelegatedError(modelId);
     }
     const plugin = getPlugin(entry.local.modelType);
@@ -16,8 +16,12 @@ function resolvePluginHandlerDef(modelId, handlerName) {
     }
     const handlerDef = plugin.handlers[handlerName];
     if (!handlerDef) {
-        const availableHandlers = Object.keys(plugin.handlers);
-        throw new PluginHandlerNotFoundError(entry.local.modelType, handlerName, availableHandlers);
+        const loadedModelType = entry.local.modelType;
+        const supportedOperations = Object.keys(plugin.handlers);
+        const suggestedModelTypes = getAllPlugins()
+            .filter((p) => p.modelType !== loadedModelType && handlerName in p.handlers)
+            .map((p) => p.modelType);
+        throw new ModelOperationNotSupportedError(modelId, loadedModelType, handlerName, supportedOperations, suggestedModelTypes);
     }
     return handlerDef;
 }

package/dist/server/rpc/handlers/plugin-invoke.js

@@ -9,7 +9,7 @@ function resolvePluginHandler(modelId, handlerName) {
     if (!modelEntry) {
         throw new ModelNotFoundError(modelId);
     }
-    if (modelEntry.isDelegated || !modelEntry.local) {
+    if (modelEntry.isDelegated) {
         throw new ModelIsDelegatedError(modelId);
     }
     const modelType = modelEntry.local.modelType;

package/dist/server/rpc/handlers/provideHandler/connection.js

@@ -1,5 +1,6 @@
 import RPC from "bare-rpc";
 import { createRpcProxy } from "./proxy.js";
+import { hasActiveProviders } from "../../../bare/hyperswarm.js";
 import { getServerLogger } from "../../../../logging/index.js";
 const logger = getServerLogger();
 export function setupConnectionHandlers(swarm) {
@@ -8,11 +9,21 @@ export function setupConnectionHandlers(swarm) {
         logger.debug("🔗 Connection closed!");
     });
     swarm.on("connection", (conn) => {
-        logger.debug("🔗 Connection event triggered!");
         const peerPubkey = conn.remotePublicKey?.toString("hex");
+        // The swarm is shared between consumer and provider sides, and once
+        // `swarm.listen()` has bound our keyPair on the DHT we cannot un-bind
+        // it without destroying the swarm. To honor `stopQVACProvider()` —
+        // which decrements `activeProviderCount` to 0 — we drop incoming
+        // connections at the RPC layer when there's no active provider, so
+        // peers can no longer dispatch delegated requests at us.
+        if (!hasActiveProviders()) {
+            logger.debug(`🚪 Dropping inbound connection from ${peerPubkey?.substring(0, 16)}... — provider is stopped`);
+            conn.destroy();
+            return;
+        }
+        logger.debug("🔗 Connection event triggered!");
         logger.info(`📡 New connection established from: ${peerPubkey?.substring(0, 16)}...`);
         logger.debug("🔐 Full peer public key:", peerPubkey);
-        // Create RPC instance for this connection (as server)
         logger.debug("⚙️ Creating RPC instance for connection...");
         new RPC(conn, createRpcProxy());
         logger.debug("✅ RPC instance created successfully");

package/dist/server/rpc/handlers/provideHandler/handler.js

@@ -1,53 +1,66 @@
-import { getSwarm, registerProviderTopic } from "../../../bare/hyperswarm.js";
+import { getSwarm, hasActiveProviders, registerProvider, } from "../../../bare/hyperswarm.js";
 import { setupConnectionHandlers } from "./connection.js";
 import { getServerLogger } from "../../../../logging/index.js";
 const logger = getServerLogger();
+// Tracks whether the connection listener has been attached on this swarm
+// instance. `swarm.listen()` and `swarm.on("connection", ...)` cannot be
+// undone without destroying the swarm (which is shared with consumers), so
+// we only ever set them up once per process and gate inbound RPC mounting
+// inside the listener on `hasActiveProviders()`.
+let listenerAttached = false;
+// Consumers reach the provider by calling `dht.connect(publicKey)` directly,
+// so the provider only needs its DHT server bound on its keyPair — no topic
+// announce required. `swarm.listen()` is the minimal operation that makes
+// the keyPair reachable on the DHT.
+//
+// This handler is idempotent: a second `startQVACProvider()` call returns
+// success without re-listening, re-attaching listeners, or double-counting
+// the active-provider counter (which would prevent a single `stopQVACProvider`
+// from cleanly shutting things down).
 export async function provideHandler(request) {
     const swarm = getSwarm({
         firewallConfig: request.firewall,
     });
     logger.debug("🚀 Provide request received:", request);
-    logger.debug("🔍 Swarm keyPair exists:", !!swarm.keyPair);
-    logger.debug("🔍 Swarm publicKey:", swarm.keyPair?.publicKey?.toString("hex")?.substring(0, 16));
     try {
-        logger.debug("⚡ Starting provide handler execution");
         const pubKey = swarm.keyPair.publicKey;
-        logger.debug("🔑 Got public key:", pubKey.toString("hex"));
-        // Use provided topic from hex string
-        const topic = Buffer.from(request.topic, "hex");
-        // Join topic as server (provider)
-        logger.info("🌐 Joining topic as server...");
-        const discovery = swarm.join(topic, { server: true, client: false });
-        logger.debug("📡 Discovery object created:", !!discovery);
-        // Wait for the topic to be fully announced on the DHT
-        logger.debug("⏳ Waiting for topic announcement...");
-        await discovery.flushed();
-        logger.info(`✅ Topic announced: ${topic.toString("hex")}`);
-        // Wait for connections
-        logger.debug("⏳ Waiting for swarm flush...");
-        await swarm.flush();
-        logger.info(`🎯 Ready to accept connections on topic: ${topic.toString("hex").substring(0, 16)}...`);
-        // Handle incoming connections
-        setupConnectionHandlers(swarm);
-        registerProviderTopic(topic.toString("hex"));
-        logger.debug("🏁 About to return success response...");
-        const response = {
+        logger.debug("🔑 Provider public key:", pubKey.toString("hex"));
+        if (hasActiveProviders()) {
+            logger.info("ℹ️ Provider already running, returning existing identity");
+            return {
+                type: "provide",
+                success: true,
+                publicKey: pubKey.toString("hex"),
+            };
+        }
+        // We must wait for the DHT routing table to populate BEFORE announcing.
+        // `swarm.listen()` only does a single initial announce using whatever
+        // peers are in the routing table at that moment — if the DHT isn't
+        // bootstrapped yet, that announce reaches very few nodes and consumers
+        // won't be able to find us via dht.connect(publicKey).
+        logger.info("🌐 Waiting for DHT to fully bootstrap...");
+        await swarm.dht.fullyBootstrapped();
+        logger.info("🌐 Announcing provider on DHT (binding keyPair)...");
+        await swarm.listen();
+        logger.info("🎯 Provider is listening and ready to accept connections");
+        if (!listenerAttached) {
+            setupConnectionHandlers(swarm);
+            listenerAttached = true;
+        }
+        registerProvider();
+        return {
             type: "provide",
             success: true,
             publicKey: pubKey.toString("hex"),
         };
-        logger.debug("📤 Returning response:", response);
-        return response;
     }
     catch (error) {
         logger.error("❌ Error in provide handler:", error);
         logger.error("❌ Error stack:", error instanceof Error ? error.stack : "No stack trace");
-        const errorResponse = {
+        return {
             type: "provide",
             success: false,
             error: error instanceof Error ? error.message : "Unknown error",
         };
-        logger.debug("📤 Returning error response:", errorResponse);
-        return errorResponse;
     }
 }

package/dist/server/rpc/handlers/state.d.ts

@@ -0,0 +1,3 @@
+import type { StateResponse } from "../../../schemas/index";
+export declare function handleState(): StateResponse;
+//# sourceMappingURL=state.d.ts.map

package/dist/server/rpc/handlers/state.js

@@ -0,0 +1,7 @@
+import { getLifecycleState } from "../../bare/runtime-lifecycle.js";
+export function handleState() {
+    return {
+        type: "state",
+        state: getLifecycleState(),
+    };
+}

package/dist/server/rpc/handlers/stopProvideHandler.d.ts

@@ -1,3 +1,3 @@
-import type { StopProvideRequest, StopProvideResponse } from "../../../schemas/stop-provide";
-export declare function stopProvideHandler(request: StopProvideRequest): StopProvideResponse;
+import type { StopProvideResponse } from "../../../schemas/stop-provide";
+export declare function stopProvideHandler(): StopProvideResponse;
 //# sourceMappingURL=stopProvideHandler.d.ts.map

package/dist/server/rpc/handlers/stopProvideHandler.js

@@ -1,13 +1,18 @@
-import { getSwarm, unregisterProviderTopic } from "../../bare/hyperswarm.js";
+import { unregisterProvider } from "../../bare/hyperswarm.js";
 import { getServerLogger } from "../../../logging/index.js";
 const logger = getServerLogger();
-export function stopProvideHandler(request) {
-    const swarm = getSwarm();
+// Decrements the active-provider counter. The shared connection listener
+// (set up once in `provideHandler` per process) checks `hasActiveProviders()`
+// before mounting an RPC server on incoming sockets, so once the counter
+// reaches 0 inbound peers are dropped and remote calls stop being served.
+//
+// We deliberately do NOT destroy the swarm or unbind the keyPair from the
+// DHT here, because the same swarm is also used by this SDK instance as a
+// consumer (delegate-rpc-client.ts). Stopping the provider role must not
+// kill outgoing delegation connections.
+export function stopProvideHandler() {
     try {
-        const topic = Buffer.from(request.topic, "hex");
-        const topicHex = request.topic;
-        swarm.leave(topic);
-        unregisterProviderTopic(topicHex);
+        unregisterProvider();
         return {
             type: "stopProvide",
             success: true,

package/dist/server/rpc/handlers/text-to-speech-stream.d.ts

@@ -0,0 +1,3 @@
+import type { TextToSpeechStreamRequest, TextToSpeechStreamResponse } from "../../../schemas/index";
+export declare function handleTextToSpeechStream(request: TextToSpeechStreamRequest, inputStream: AsyncIterable<Buffer>): AsyncGenerator<TextToSpeechStreamResponse>;
+//# sourceMappingURL=text-to-speech-stream.d.ts.map

package/dist/server/rpc/handlers/text-to-speech-stream.js

@@ -0,0 +1,4 @@
+import { dispatchPluginStream } from "./plugin-dispatch.js";
+export async function* handleTextToSpeechStream(request, inputStream) {
+    yield* dispatchPluginStream(request.modelId, "textToSpeechStream", request, inputStream);
+}

package/dist/server/rpc/handlers/unload-model-delegated.js

@@ -8,14 +8,14 @@ import { getServerLogger } from "../../../logging/index.js";
 const logger = getServerLogger();
 export async function handleUnloadModelDelegated(request) {
     const entry = getModelEntry(request.modelId);
-    if (!entry?.isDelegated || !entry.delegated) {
+    if (!entry?.isDelegated) {
         throw new ModelIsDelegatedError(request.modelId);
     }
-    const { topic, providerPublicKey, timeout, healthCheckTimeout } = entry.delegated;
+    const { providerPublicKey, timeout, healthCheckTimeout } = entry.delegated;
     unregisterModel(request.modelId);
     try {
         logger.info(`Sending delegated unload for model ${request.modelId} to provider: ${providerPublicKey}`);
-        const rpc = await getRPC(topic, providerPublicKey, { timeout, healthCheckTimeout });
+        const rpc = await getRPC(providerPublicKey, { timeout, healthCheckTimeout });
         await send({ type: "unloadModel", modelId: request.modelId, clearStorage: false }, rpc, { timeout, peerKey: providerPublicKey });
         logger.info(`Delegated model ${request.modelId} unloaded on provider`);
     }

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

@@ -167,6 +167,26 @@ registerOperationMetrics({
         return Object.keys(gauges).length > 0 ? gauges : undefined;
     },
 });
+// Duplex sibling of `textToSpeech`. Server emits the same `TtsStats` on the
+// final chunk (via `collectTtsStats`), so the gauge set mirrors the
+// non-streaming path; without registering here, sessions would silently
+// skip `modelExecutionTime` / `audioDuration` / `totalSamples` metrics.
+registerOperationMetrics({
+    op: "textToSpeechStream",
+    kind: "handler",
+    getTags: (req) => (req.modelId ? { modelId: req.modelId } : {}),
+    fromFinalChunk: (res) => {
+        const gauges = {};
+        const modelExecMs = readModelExecutionMs(res);
+        if (modelExecMs !== undefined)
+            gauges["modelExecutionTime"] = modelExecMs;
+        if (res.stats?.audioDuration !== undefined)
+            gauges["audioDuration"] = res.stats.audioDuration;
+        if (res.stats?.totalSamples !== undefined)
+            gauges["totalSamples"] = res.stats.totalSamples;
+        return Object.keys(gauges).length > 0 ? gauges : undefined;
+    },
+});
 registerOperationMetrics({
     op: "embed",
     kind: "handler",

package/dist/server/rpc/rpc-utils.js

@@ -7,5 +7,5 @@ export function isTerminalChunk(value) {
     return (typeof value === "object" &&
         value !== null &&
         "done" in value &&
-        value.done === true);
+        (value).done === true);
 }

package/dist/server/rpc/transport-selector.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerEntry } from "./handler-utils";
+export declare function shouldUseStreamErrorTransport(entry: HandlerEntry | undefined, rawRequest: Record<string, unknown> | undefined): boolean;
+//# sourceMappingURL=transport-selector.d.ts.map

package/dist/server/rpc/transport-selector.js

@@ -0,0 +1,18 @@
+export function shouldUseStreamErrorTransport(entry, rawRequest) {
+    if (!entry)
+        return false;
+    if (entry.type === "stream")
+        return true;
+    if (entry.type !== "reply")
+        return false;
+    if (rawRequest?.["withProgress"] !== true)
+        return false;
+    try {
+        return typeof entry.supportsProgress === "function"
+            ? entry.supportsProgress(rawRequest)
+            : !!entry.supportsProgress;
+    }
+    catch {
+        return !!entry.supportsProgress;
+    }
+}

package/dist/server/utils/cache/auto-history.d.ts

@@ -0,0 +1,4 @@
+import type { CacheMessage } from "./types";
+export declare function getAutoCacheLookupHistory(currentHistory: CacheMessage[]): CacheMessage[];
+export declare function buildAutoCacheSaveHistory(currentHistory: CacheMessage[], assistantResponse: string): CacheMessage[];
+//# sourceMappingURL=auto-history.d.ts.map

package/dist/server/utils/cache/auto-history.js

@@ -0,0 +1,22 @@
+import { normalizeAssistantCacheContent } from "../../../utils/cache-normalize.js";
+function normalizeAssistantMessage(message) {
+    if (message.role !== "assistant") {
+        return message;
+    }
+    return { ...message, content: normalizeAssistantCacheContent(message.content) };
+}
+export function getAutoCacheLookupHistory(currentHistory) {
+    if (currentHistory.length <= 1) {
+        return [];
+    }
+    return currentHistory.slice(0, -1).map(normalizeAssistantMessage);
+}
+export function buildAutoCacheSaveHistory(currentHistory, assistantResponse) {
+    return [
+        ...currentHistory,
+        {
+            role: "assistant",
+            content: normalizeAssistantCacheContent(assistantResponse),
+        },
+    ];
+}

package/dist/server/utils/{cache.d.ts → cache/paths.d.ts}

@@ -1,4 +1,4 @@
-import type { ShardFileMetadata } from "../../schemas/index";
+import type { ShardFileMetadata } from "../../../schemas/index";
 export declare function getCacheDir(subDir: string): string;
 export declare function getModelsCacheDir(): string;
 export declare function getKVCacheDir(): string;
@@ -8,19 +8,36 @@ export declare function getKVCacheDir(): string;
  */
 export declare function getShardedModelCacheDir(hyperdriveKey: string): string;
 /**
- * Get full path to ONNX file in cache
- * Returns: cache/onnx/<cacheKey>/<filename>
+ * Get cache directory for a companion set.
+ * Returns: cache/sets/<setKey>/
  */
-export declare function getOnnxModelPath(cacheKey: string, filename: string): string;
+export declare function getCompanionSetCacheDir(setKey: string): string;
+/**
+ * Get full path to a file within a companion set cache.
+ * Returns: cache/sets/<setKey>/<targetName>
+ */
+export declare function getCompanionSetPath(setKey: string, targetName: string): string;
+/**
+ * Get cache path for a single (non-sharded, non-companion) registry model.
+ */
+export declare function getSingleFileCachePath(registryPath: string): string;
 /**
  * Get full path to specific shard file
  * Returns: cache/sharded/<hyperdriveKey>/<shardFilename>
  */
 export declare function getShardPath(hyperdriveKey: string, shardFilename: string): string;
+/**
+ * Returns the deletion target for `clearStorage`. Scoped to the SDK cache
+ * directory — companion set and legacy ONNX paths delete the parent directory.
+ */
+export declare function getClearStorageTarget(modelPath: string): {
+    path: string;
+    kind: "file" | "directory";
+};
 /**
  * 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[], onChecksumTimeMs?: (ms: number) => void): Promise<number[]>;
-//# sourceMappingURL=cache.d.ts.map
+//# sourceMappingURL=paths.d.ts.map

package/dist/server/utils/{cache.js → cache/paths.js}

@@ -1,15 +1,16 @@
 import fs, { promises as fsPromises } from "bare-fs";
 import path from "bare-path";
-import { getEnv } from "../env.js";
-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";
+import { getConfiguredCacheDir } from "../../bare/registry/config-registry.js";
+import { getQvacPath } from "../qvac-paths.js";
+import { calculateFileChecksum } from "../checksum.js";
+import { validateAndJoinPath } from "../path-security.js";
+import { generateShortHash } from "../formatting.js";
+import { getServerLogger } from "../../../logging/index.js";
+import { nowMs } from "../../../profiling/index.js";
+import { resolveClearStorageTarget } from "../clear-storage.js";
 const logger = getServerLogger();
 export function getCacheDir(subDir) {
-    const homeDir = getEnv().HOME_DIR;
-    const cacheDir = path.join(homeDir, ".qvac", subDir);
+    const cacheDir = getQvacPath(subDir);
     try {
         fs.mkdirSync(cacheDir, { recursive: true });
     }
@@ -47,27 +48,35 @@ export function getShardedModelCacheDir(hyperdriveKey) {
     return shardDir;
 }
 /**
- * Get cache directory for ONNX model with external data
- * Returns: cache/onnx/<cacheKey>/
+ * Get cache directory for a companion set.
+ * Returns: cache/sets/<setKey>/
  */
-function getOnnxModelCacheDir(cacheKey) {
+export function getCompanionSetCacheDir(setKey) {
     const baseCache = getModelsCacheDir();
-    const onnxDir = validateAndJoinPath(baseCache, "onnx", cacheKey);
+    const setDir = validateAndJoinPath(baseCache, "sets", setKey);
     try {
-        fs.mkdirSync(onnxDir, { recursive: true });
+        fs.mkdirSync(setDir, { recursive: true });
     }
     catch (error) {
-        logger.error(`Error creating ONNX model cache directory:`, error instanceof Error ? error.message : String(error));
+        logger.error(`Error creating companion set cache directory:`, error instanceof Error ? error.message : String(error));
     }
-    return onnxDir;
+    return setDir;
 }
 /**
- * Get full path to ONNX file in cache
- * Returns: cache/onnx/<cacheKey>/<filename>
+ * Get full path to a file within a companion set cache.
+ * Returns: cache/sets/<setKey>/<targetName>
  */
-export function getOnnxModelPath(cacheKey, filename) {
-    const onnxDir = getOnnxModelCacheDir(cacheKey);
-    return validateAndJoinPath(onnxDir, filename);
+export function getCompanionSetPath(setKey, targetName) {
+    const setDir = getCompanionSetCacheDir(setKey);
+    return validateAndJoinPath(setDir, targetName);
+}
+/**
+ * Get cache path for a single (non-sharded, non-companion) registry model.
+ */
+export function getSingleFileCachePath(registryPath) {
+    const filename = registryPath.split("/").pop() || registryPath;
+    const sourceHash = generateShortHash(registryPath);
+    return path.join(getModelsCacheDir(), `${sourceHash}_${filename}`);
 }
 /**
  * Get full path to specific shard file
@@ -77,6 +86,13 @@ export function getShardPath(hyperdriveKey, shardFilename) {
     const shardDir = getShardedModelCacheDir(hyperdriveKey);
     return validateAndJoinPath(shardDir, shardFilename);
 }
+/**
+ * Returns the deletion target for `clearStorage`. Scoped to the SDK cache
+ * directory — companion set and legacy ONNX paths delete the parent directory.
+ */
+export function getClearStorageTarget(modelPath) {
+    return resolveClearStorageTarget(modelPath, getModelsCacheDir());
+}
 /**
  * Check if all shards exist and are valid (size + checksum check)
  * Returns array of missing/invalid shard indices (0-based)