@qvac/sdk 0.10.2 → 0.12.0

package/dist/server/rpc/handlers/cancel-delegated.js

@@ -3,38 +3,35 @@ import { getModelEntry } from "../../bare/registry/model-registry.js";
 import { getRPC } from "../../bare/delegate-rpc-client.js";
 import { send } from "../delegate-transport.js";
 const logger = getServerLogger();
+/**
+ * Resolve the delegated provider for a cancel request, if any.
+ *
+ * After the 0.11.0 wire-schema collapse the cancel envelope has only
+ * two operations. Only `broad` cancels delegate at the cancel layer —
+ * see `isCancelDelegated` in `handler-registry.ts` for the policy and
+ * the rationale.
+ *
+ * The targeted `request` arm is handled locally because the registry
+ * is worker-singleton and already holds the entry for delegated
+ * requests (the delegated handler registers its own context on the
+ * provider-facing side). For pre-0.11.0 behaviour where a `requestId`
+ * cancel against a delegated model needed to round-trip to the
+ * provider, hold onto the delegated `loadModel(...).requestId` and
+ * fire a broad cancel against the model id instead.
+ */
 function resolveDelegationTarget(request) {
-    if (request.operation === "inference" || request.operation === "embeddings") {
-        const entry = getModelEntry(request.modelId);
-        if (!entry?.isDelegated) {
-            return null;
-        }
-        const target = {
-            providerPublicKey: entry.delegated.providerPublicKey,
-        };
-        if (entry.delegated.timeout !== undefined) {
-            target.timeout = entry.delegated.timeout;
-        }
-        return target;
-    }
-    if (request.operation === "downloadAsset" && request.delegate) {
-        const target = {
-            providerPublicKey: request.delegate.providerPublicKey,
-        };
-        if (request.delegate.timeout !== undefined) {
-            target.timeout = request.delegate.timeout;
-        }
-        return target;
-    }
-    return null;
-}
-function toProviderCancelRequest(request) {
-    if (request.operation !== "downloadAsset") {
-        return request;
+    if (request.operation !== "broad")
+        return null;
+    const entry = getModelEntry(request.modelId);
+    if (!entry?.isDelegated)
+        return null;
+    const target = {
+        providerPublicKey: entry.delegated.providerPublicKey,
+    };
+    if (entry.delegated.timeout !== undefined) {
+        target.timeout = entry.delegated.timeout;
     }
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { delegate: _delegate, ...providerRequest } = request;
-    return providerRequest;
+    return target;
 }
 export async function handleCancelDelegated(request, options) {
     const target = resolveDelegationTarget(request);
@@ -55,7 +52,7 @@ export async function handleCancelDelegated(request, options) {
         if (options?.profilingMeta) {
             delegateOpts.profilingMeta = options.profilingMeta;
         }
-        await send(toProviderCancelRequest(request), rpc, delegateOpts);
+        await send(request, rpc, delegateOpts);
         return { type: "cancel", success: true };
     }
     catch (error) {

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

@@ -1,3 +1,32 @@
 import type { CancelRequest, CancelResponse } from "../../../schemas/cancel";
-export declare function cancelHandler(request: CancelRequest): Promise<CancelResponse>;
+/**
+ * Cancel RPC entry point. The 5-arm `switch (request.operation)`
+ * dispatcher that lived here through 0.10.x was retired in 0.11.0:
+ * every long-running handler now registers itself on the
+ * worker-singleton `RequestRegistry`, so the cancel surface narrows to
+ * two paths that route through the same registry primitive:
+ *
+ *  - `{ operation: "request", requestId, clearCache? }` — targeted
+ *    cancel by client-generated id. Looks up the registry entry,
+ *    fires its abort signal, optionally marks the underlying download
+ *    transfer for cache clear. The "stop-button race" case (client
+ *    cancel beats its own begin to the worker) is handled inside the
+ *    registry via the cancel-before-begin tripwire.
+ *
+ *  - `{ operation: "broad", modelId, kind? }` — abort every in-flight
+ *    request on a model (optionally narrowed by `kind`). Used for
+ *    model unload, app shutdown, and admin sweeps where the caller
+ *    has no `requestId`. Delegates to the `cancel` bare op so the
+ *    `ModelNotLoadedError` validation is shared with internal
+ *    server-side broad cancels.
+ *
+ * Always returns `success: true` plus a `cancelled` count (the number
+ * of contexts this call flipped to `cancelling` — already-cancelled
+ * contexts are not counted). A targeted cancel with no in-flight
+ * match still returns `success: true, cancelled: 0`; the
+ * cancel-before-begin tripwire ensures the cancel is applied
+ * retroactively if a matching begin arrives within the registry's
+ * race window.
+ */
+export declare function cancelHandler(request: CancelRequest): CancelResponse;
 //# sourceMappingURL=cancelHandler.d.ts.map

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

@@ -1,30 +1,62 @@
-import { cancel } from "../../bare/ops/cancel.js";
-import { cancelTransfer } from "./load-model/download-manager.js";
-import { cancelRagOperation, DEFAULT_WORKSPACE, } from "../../bare/rag-hyperdb/index.js";
+import { cancel as cancelByModelId } from "../../bare/ops/cancel.js";
+import { getRequestRegistry } from "../../bare/runtime/index.js";
+import { markClearCacheForRequest } from "./load-model/download-manager.js";
 import { getServerLogger } from "../../../logging/index.js";
 const logger = getServerLogger();
-export async function cancelHandler(request) {
+/**
+ * Cancel RPC entry point. The 5-arm `switch (request.operation)`
+ * dispatcher that lived here through 0.10.x was retired in 0.11.0:
+ * every long-running handler now registers itself on the
+ * worker-singleton `RequestRegistry`, so the cancel surface narrows to
+ * two paths that route through the same registry primitive:
+ *
+ *  - `{ operation: "request", requestId, clearCache? }` — targeted
+ *    cancel by client-generated id. Looks up the registry entry,
+ *    fires its abort signal, optionally marks the underlying download
+ *    transfer for cache clear. The "stop-button race" case (client
+ *    cancel beats its own begin to the worker) is handled inside the
+ *    registry via the cancel-before-begin tripwire.
+ *
+ *  - `{ operation: "broad", modelId, kind? }` — abort every in-flight
+ *    request on a model (optionally narrowed by `kind`). Used for
+ *    model unload, app shutdown, and admin sweeps where the caller
+ *    has no `requestId`. Delegates to the `cancel` bare op so the
+ *    `ModelNotLoadedError` validation is shared with internal
+ *    server-side broad cancels.
+ *
+ * Always returns `success: true` plus a `cancelled` count (the number
+ * of contexts this call flipped to `cancelling` — already-cancelled
+ * contexts are not counted). A targeted cancel with no in-flight
+ * match still returns `success: true, cancelled: 0`; the
+ * cancel-before-begin tripwire ensures the cancel is applied
+ * retroactively if a matching begin arrives within the registry's
+ * race window.
+ */
+export function cancelHandler(request) {
     try {
-        switch (request.operation) {
-            case "inference":
-            case "embeddings":
-                await cancel({ modelId: request.modelId });
-                break;
-            case "downloadAsset":
-                cancelTransfer(request.downloadKey, request.clearCache);
-                break;
-            case "rag": {
-                const cancelled = cancelRagOperation(request.workspace);
-                if (!cancelled) {
-                    logger.warn(`No active RAG operation to cancel for workspace: ${request.workspace ?? DEFAULT_WORKSPACE}`);
-                }
-                break;
+        if (request.operation === "request") {
+            if (request.clearCache) {
+                markClearCacheForRequest(request.requestId);
             }
+            const cancelled = getRequestRegistry().cancel({
+                requestId: request.requestId,
+            });
+            if (cancelled === 0) {
+                // info-level (not debug) because the decorated-promise pattern
+                // makes "no in-flight match" a common and user-visible case:
+                // a Stop button fired after the request settled but before
+                // the UI cleared lands here. The cancel-before-begin tripwire
+                // inside the registry already captured the cancel for any
+                // matching begin in flight; this log just helps operators
+                // debugging "my Stop button isn't working" without lowering
+                // the log level.
+                logger.info(`[cancel] no in-flight request matched requestId=${request.requestId}`);
+            }
+            return { type: "cancel", success: true, cancelled };
         }
-        return {
-            type: "cancel",
-            success: true,
-        };
+        // operation === "broad"
+        const cancelled = cancelByModelId({ modelId: request.modelId }, request.kind ? { kind: request.kind } : undefined);
+        return { type: "cancel", success: true, cancelled };
     }
     catch (error) {
         logger.error("Error during cancellation:", error);

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

@@ -0,0 +1,3 @@
+import type { ClassifyRequest, ClassifyResponse } from "../../../schemas/classification";
+export declare function handleClassify(request: ClassifyRequest): AsyncGenerator<ClassifyResponse>;
+//# sourceMappingURL=classify.d.ts.map

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

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

package/dist/server/rpc/handlers/delete-cache.d.ts

@@ -1,3 +1,12 @@
 import type { DeleteCacheRequest, DeleteCacheResponse } from "../../../schemas/index";
+/**
+ * RPC handler for `deleteCache(...)`. The three KV-cache bookkeeping
+ * layers (on-disk `.bin`, `initializedCaches`, `cachedMessageCounts`)
+ * are private to `kv-cache-session.ts`; this handler delegates to that
+ * module's single administrative entry point (`deleteKvCacheState`).
+ * The handler must have **zero** direct references to
+ * `fsPromises.unlink`, the `initializedCaches` set, or the
+ * `cachedMessageCounts` map.
+ */
 export declare function handleDeleteCache(request: DeleteCacheRequest): Promise<DeleteCacheResponse>;
 //# sourceMappingURL=delete-cache.d.ts.map

package/dist/server/rpc/handlers/delete-cache.js

@@ -1,26 +1,24 @@
-import { clearCacheRegistry, deleteCache as deleteCacheUtil, } from "../../bare/ops/kv-cache-utils.js";
-import { clearCachedMessageCounts } from "../../bare/plugins/llamacpp-completion/ops/completion-stream.js";
+import { deleteKvCacheState } from "../../bare/plugins/llamacpp-completion/ops/kv-cache-session.js";
 import { getServerLogger } from "../../../logging/index.js";
 const logger = getServerLogger();
+/**
+ * RPC handler for `deleteCache(...)`. The three KV-cache bookkeeping
+ * layers (on-disk `.bin`, `initializedCaches`, `cachedMessageCounts`)
+ * are private to `kv-cache-session.ts`; this handler delegates to that
+ * module's single administrative entry point (`deleteKvCacheState`).
+ * The handler must have **zero** direct references to
+ * `fsPromises.unlink`, the `initializedCaches` set, or the
+ * `cachedMessageCounts` map.
+ */
 export async function handleDeleteCache(request) {
     try {
         if ("all" in request && request.all) {
-            await deleteCacheUtil({ all: true });
-            clearCachedMessageCounts();
-            clearCacheRegistry();
+            await deleteKvCacheState({ all: true });
         }
         else if ("kvCacheKey" in request) {
-            const params = {
+            await deleteKvCacheState({
                 kvCacheKey: request.kvCacheKey,
-            };
-            if (request.modelId !== undefined) {
-                params.modelId = request.modelId;
-            }
-            const removedPath = await deleteCacheUtil(params);
-            clearCachedMessageCounts(removedPath);
-            clearCacheRegistry({
-                cacheKey: request.kvCacheKey,
-                modelId: request.modelId,
+                ...(request.modelId !== undefined && { modelId: request.modelId }),
             });
         }
         return {

package/dist/server/rpc/handlers/download-asset.js

@@ -1,53 +1,146 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { PROFILING_KEY, OPERATION_EVENT_KEY, } from "../../../schemas/index.js";
 import { resolveModelPath, resolveModelPathWithStats, } from "./load-model/resolve.js";
-import { buildDownloadProfilingFields } from "./load-model/types.js";
+import { buildDownloadProfilingFields, } from "./load-model/types.js";
 import { nowMs, generateProfileId } from "../../../profiling/clock.js";
 import { getServerLogger } from "../../../logging/index.js";
+import { getRequestRegistry, withRequestContext, } from "../../bare/runtime/index.js";
+import { generateServerRequestId } from "../../bare/runtime/request-id.js";
+import { InferenceCancelledError } from "../../../utils/errors-server.js";
 const logger = getServerLogger();
 export async function handleDownloadAsset(request, progressCallback) {
-    const { assetSrc, seed } = request;
-    const profilingMeta = request[PROFILING_KEY];
-    const profilingEnabled = profilingMeta?.enabled !== false && !!profilingMeta;
+    const env_1 = { stack: [], error: void 0, hasError: false };
     try {
-        const totalDownloadStart = profilingEnabled ? nowMs() : 0;
-        let sourceType;
-        let downloadStats;
-        if (profilingEnabled) {
-            const result = await resolveModelPathWithStats(assetSrc, progressCallback, seed);
-            sourceType = result.sourceType;
-            downloadStats = result.downloadStats;
-        }
-        else {
-            await resolveModelPath(assetSrc, progressCallback, seed);
-        }
-        const response = {
-            type: "downloadAsset",
-            success: true,
-            assetId: assetSrc,
+        const { assetSrc, seed } = request;
+        const profilingMeta = request[PROFILING_KEY];
+        const profilingEnabled = profilingMeta?.enabled !== false && !!profilingMeta;
+        const requestId = request.requestId ?? generateServerRequestId();
+        // `downloadAsset` is artifact-shaped, not model-shaped — there is no
+        // `modelId` to register on the registry entry. Cancel by `requestId`
+        // is the primary path; `cancel({ modelId })` is intentionally a
+        // non-match for this kind.
+        const ctx = __addDisposableResource(env_1, getRequestRegistry().begin({
+            requestId,
+            kind: "downloadAsset",
+        }), true);
+        const log = withRequestContext(getServerLogger(), ctx);
+        log.debug(`downloadAsset start assetSrc=${assetSrc}`);
+        const hooks = {
+            requestBinding: {
+                signal: ctx.signal,
+                scope: ctx.scope,
+                requestId,
+            },
         };
-        if (profilingEnabled) {
-            const totalDownloadTimeMs = nowMs() - totalDownloadStart;
-            const profileId = profilingMeta?.id ?? generateProfileId();
-            const { gauges, tags } = buildDownloadProfilingFields(downloadStats, sourceType);
-            gauges["totalDownloadTime"] = totalDownloadTimeMs;
-            const operationEvent = {
-                op: "downloadAsset",
-                kind: "handler",
-                ms: totalDownloadTimeMs,
-                profileId,
-                gauges: Object.keys(gauges).length > 0 ? gauges : undefined,
-                tags: Object.keys(tags).length > 0 ? tags : undefined,
+        try {
+            const totalDownloadStart = profilingEnabled ? nowMs() : 0;
+            let sourceType;
+            let downloadStats;
+            if (profilingEnabled) {
+                const result = await resolveModelPathWithStats(assetSrc, progressCallback, seed, ctx.signal, hooks);
+                sourceType = result.sourceType;
+                downloadStats = result.downloadStats;
+            }
+            else {
+                await resolveModelPath(assetSrc, progressCallback, seed, ctx.signal, hooks);
+            }
+            const response = {
+                type: "downloadAsset",
+                success: true,
+                assetId: assetSrc,
+            };
+            if (profilingEnabled) {
+                const totalDownloadTimeMs = nowMs() - totalDownloadStart;
+                const profileId = profilingMeta?.id ?? generateProfileId();
+                const { gauges, tags } = buildDownloadProfilingFields(downloadStats, sourceType);
+                gauges["totalDownloadTime"] = totalDownloadTimeMs;
+                const operationEvent = {
+                    op: "downloadAsset",
+                    kind: "handler",
+                    ms: totalDownloadTimeMs,
+                    profileId,
+                    gauges: Object.keys(gauges).length > 0 ? gauges : undefined,
+                    tags: Object.keys(tags).length > 0 ? tags : undefined,
+                };
+                response[OPERATION_EVENT_KEY] = operationEvent;
+            }
+            return response;
+        }
+        catch (error) {
+            // Mirror the load-model handler's cancel contract: a typed cancel
+            // bubbles up as the rejection so client-side callers can branch on
+            // `instanceof InferenceCancelledError`. Every other error keeps
+            // the legacy `success: false` envelope.
+            if (error instanceof InferenceCancelledError) {
+                log.info(`downloadAsset cancelled requestId=${requestId}`);
+                throw error;
+            }
+            logger.error("Error downloading asset:", error);
+            return {
+                type: "downloadAsset",
+                success: false,
+                error: error instanceof Error ? error.message : "Unknown error",
             };
-            response[OPERATION_EVENT_KEY] = operationEvent;
         }
-        return response;
     }
-    catch (error) {
-        logger.error("Error downloading asset:", error);
-        return {
-            type: "downloadAsset",
-            success: false,
-            error: error instanceof Error ? error.message : "Unknown error",
-        };
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
     }
 }

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

@@ -20,6 +20,8 @@ import { handleFinetune } from "./finetune";
 import { handleOCRStream } from "./ocr-stream";
 import { handleHeartbeat } from "./heartbeat";
 import { handleDiffusionStream } from "./diffusion-stream";
+import { handleVideoStream } from "./video-stream";
+import { handleUpscaleStream } from "./upscale-stream";
 import { handlePluginInvoke, handlePluginInvokeStream } from "./plugin-invoke";
 import { handleModelRegistryList, handleModelRegistrySearch, handleModelRegistryGetModel } from "./registry";
 import { handleSuspend } from "./suspend";
@@ -48,6 +50,8 @@ export declare const handlers: {
     finetune: typeof handleFinetune;
     ocrStream: typeof handleOCRStream;
     diffusionStream: typeof handleDiffusionStream;
+    videoStream: typeof handleVideoStream;
+    upscaleStream: typeof handleUpscaleStream;
     pluginInvoke: typeof handlePluginInvoke;
     pluginInvokeStream: typeof handlePluginInvokeStream;
     modelRegistryList: typeof handleModelRegistryList;

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

@@ -20,6 +20,8 @@ import { handleFinetune } from "./finetune.js";
 import { handleOCRStream } from "./ocr-stream.js";
 import { handleHeartbeat } from "./heartbeat.js";
 import { handleDiffusionStream } from "./diffusion-stream.js";
+import { handleVideoStream } from "./video-stream.js";
+import { handleUpscaleStream } from "./upscale-stream.js";
 import { handlePluginInvoke, handlePluginInvokeStream } from "./plugin-invoke.js";
 import { handleModelRegistryList, handleModelRegistrySearch, handleModelRegistryGetModel, } from "./registry.js";
 import { handleSuspend } from "./suspend.js";
@@ -48,6 +50,8 @@ export const handlers = {
     finetune: handleFinetune,
     ocrStream: handleOCRStream,
     diffusionStream: handleDiffusionStream,
+    videoStream: handleVideoStream,
+    upscaleStream: handleUpscaleStream,
     pluginInvoke: handlePluginInvoke,
     pluginInvokeStream: handlePluginInvokeStream,
     modelRegistryList: handleModelRegistryList,

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

@@ -1,6 +1,29 @@
 import type { ModelProgressUpdate } from "../../../../schemas/index";
-import { AbortController } from "bare-abort-controller";
+import { AbortController, type AbortSignal } from "bare-abort-controller";
+import type { DisposableScope } from "../../../bare/runtime/disposable-scope";
 import type { DownloadHooks } from "./types";
+/**
+ * Per-subscriber binding to a registry-tracked request.
+ * `startOrJoinDownload` is request-aware: each caller (the
+ * `await using ctx = registry.begin(...)` inside `handleLoadModel` /
+ * `handleDownloadAsset`) registers a subscriber bound to its
+ * `requestId`. A `cancel({ requestId })` against the registry aborts
+ * the subscriber's `ctx.signal`, which:
+ *   - rejects this subscriber's promise so the awaiting handler unwinds;
+ *   - removes this subscriber from `transfer.subscribers`;
+ *   - tears down the transfer iff this was the last subscriber.
+ *
+ * The shared-transfer dedup logic in `startOrJoinDownload` is preserved
+ * — two callers requesting the same `downloadKey` still share one
+ * underlying download — but cancel is per-`requestId`-honest:
+ * cancelling one subscriber does not affect siblings on the same
+ * `downloadKey`.
+ */
+export interface SubscriberRequestBinding {
+    signal: AbortSignal;
+    scope: DisposableScope;
+    requestId: string;
+}
 export interface Subscriber {
     id: string;
     onProgress?: ((progress: ModelProgressUpdate) => void) | undefined;
@@ -8,6 +31,8 @@ export interface Subscriber {
     resolve: (path: string) => void;
     reject: (error: unknown) => void;
     promise: Promise<string>;
+    /** Identity of the registry request this subscriber belongs to, if any. */
+    requestId?: string | undefined;
 }
 export interface Transfer {
     downloadKey: string;
@@ -29,7 +54,40 @@ export interface StartOrJoinResult {
     joined: boolean;
     getCacheHit: () => boolean | undefined;
 }
-export declare function startOrJoinDownload(downloadKey: string, startDownload: (ctx: DownloadContext) => Promise<string>, onProgress?: (progress: ModelProgressUpdate) => void): StartOrJoinResult;
+export declare function startOrJoinDownload(downloadKey: string, startDownload: (ctx: DownloadContext) => Promise<string>, onProgress?: (progress: ModelProgressUpdate) => void, request?: SubscriberRequestBinding): StartOrJoinResult;
+/**
+ * Legacy cancel entry point. Callers (`cancelHandler`'s deprecated
+ * `case "downloadAsset"` arm, the shutdown sweep, intra-resolve
+ * cleanup) call this with a `downloadKey`. The single source of cancel
+ * routing is the request registry, so this function resolves each
+ * subscriber's request via `registry.cancel({ requestId })`.
+ *
+ * Subscribers without a `requestId` (legacy callers that didn't pass a
+ * registry binding) are settled directly with `DownloadCancelledError`
+ * so we don't leak the transfer if a legacy code path holds the only
+ * reference.
+ */
+/**
+ * Set `clearCache=true` on the transfer that owns the subscriber bound
+ * to `requestId`, so when the registry's targeted cancel removes that
+ * subscriber and we reach last-subscriber teardown, the partial
+ * download file is deleted instead of preserved for automatic resume.
+ *
+ * Lookup is O(transfers * subscribers); transfers are short-lived and
+ * subscriber counts per transfer are tiny in practice, so this is
+ * fine. Returns `true` if a matching subscriber was found, `false`
+ * otherwise — the cancel handler treats both cases identically (the
+ * registry cancel still fires) and the return value is informational.
+ *
+ * Added in 0.11.0 to support `cancel({ requestId, clearCache: true })`
+ * for download requests after the wire schema collapse removed the
+ * `{ operation: "downloadAsset", downloadKey, clearCache }` arm. The
+ * subscriber is the unit of `clearCache` even though the flag lives on
+ * the shared transfer: if any subscriber on the transfer asks for
+ * clearCache, the partial file is deleted when the last subscriber
+ * leaves, matching the pre-collapse behaviour.
+ */
+export declare function markClearCacheForRequest(requestId: string): boolean;
 export declare function cancelTransfer(downloadKey: string, clearCache?: boolean): void;
 export declare function createHyperdriveDownloadKey(hyperdriveKey: string, modelFileName: string): string;
 export declare function createHttpDownloadKey(url: string): string;