@qvac/sdk 0.10.2 → 0.12.0

package/dist/server/bare/rag-hyperdb/rag-operation-manager.js

@@ -1,39 +1,76 @@
-import { AbortController } from "bare-abort-controller";
-import { DEFAULT_WORKSPACE } from "./rag-workspace-manager.js";
-// Map of workspace -> active operation
-const activeOperations = new Map();
+import { getRequestRegistry } from "../runtime/index.js";
+// Sentinel for "no workspace specified". Mirrors the value re-exported
+// from `rag-workspace-manager.ts`; redeclared locally so this module is
+// safely importable in environments that don't have the Bare runtime
+// (unit tests, doc generators) — `rag-workspace-manager` pulls in
+// `bare-fs` / `bare-path` at module load.
+const DEFAULT_WORKSPACE = "default";
+/**
+ * RAG operation tracking — workspace-level admission bookkeeping.
+ *
+ * In 0.11.0 the cancel surface for in-flight RAG operations consolidates
+ * onto the request registry (`getRequestRegistry().cancel({ requestId })`).
+ * The historical workspace-level pre-emption rule — "starting a new
+ * `ingest` / `reindex` / `saveEmbeddings` on a workspace cancels any prior
+ * op on the same workspace" — is preserved by the dispatcher in
+ * `server/rpc/handlers/rag.ts`: the dispatcher cancels the workspace's
+ * prior `requestId` (if any) and then begins a new registry context.
+ * Workspace-level admission lives in the dispatcher rather than as a
+ * registry policy primitive — it's a dispatch concern, not part of the
+ * registry's per-`kind` admission rules.
+ *
+ * This module owns the small workspace → requestId map that makes that
+ * pre-emption decision routable from the dispatcher. The map is module-
+ * scoped (one per Bare worker) so the dispatcher, the shutdown sweep
+ * (`cancelAllRagOperations`), and the workspace-close sweep (which
+ * delegates to it via `rag-workspace-manager.ts`) all see the same state.
+ */
+// workspace key → requestId of the in-flight RAG operation on that workspace.
+const activeRagRequestByWorkspace = new Map();
 export function getWorkspaceKey(workspace) {
     return workspace ?? DEFAULT_WORKSPACE;
 }
-export function registerRagOperation(workspace, operation) {
-    const key = getWorkspaceKey(workspace);
-    // Cancel any existing operation on this workspace
-    cancelRagOperation(workspace);
-    const abortController = new AbortController();
-    activeOperations.set(key, {
-        abortController,
-        operation,
-        startTime: Date.now(),
-    });
-    return abortController.signal;
+/**
+ * Returns the `requestId` of any in-flight RAG operation on the workspace
+ * (or `undefined` if none). The dispatcher uses this to decide whether to
+ * pre-empt before calling `registry.begin(...)`.
+ */
+export function getActiveRagRequest(workspace) {
+    return activeRagRequestByWorkspace.get(getWorkspaceKey(workspace));
 }
-export function unregisterRagOperation(workspace) {
-    const key = getWorkspaceKey(workspace);
-    activeOperations.delete(key);
+/**
+ * Records the `requestId` of a freshly-begun RAG operation. Called by the
+ * dispatcher in `rag.ts` after `registry.begin(...)` succeeds; paired with
+ * `clearActiveRagRequest` via the request scope's deferred cleanup so the
+ * map never outlives the request.
+ */
+export function setActiveRagRequest(workspace, requestId) {
+    activeRagRequestByWorkspace.set(getWorkspaceKey(workspace), requestId);
 }
-export function cancelRagOperation(workspace) {
+/**
+ * Clears the workspace's mapping iff it still belongs to `requestId`. The
+ * conditional guard handles the natural race between two ingest calls on
+ * the same workspace: the older context's scope unwind must not stomp the
+ * newer context's mapping installed by the pre-emption sequence.
+ */
+export function clearActiveRagRequest(workspace, requestId) {
     const key = getWorkspaceKey(workspace);
-    const entry = activeOperations.get(key);
-    if (!entry) {
-        return false;
+    if (activeRagRequestByWorkspace.get(key) === requestId) {
+        activeRagRequestByWorkspace.delete(key);
     }
-    entry.abortController.abort();
-    activeOperations.delete(key);
-    return true;
 }
+/**
+ * Shutdown / workspace-close sweep. Cancels every tracked RAG request via
+ * the registry and clears the workspace map. Idempotent — callers that
+ * re-invoke during a teardown (workspace-close fired twice, shutdown
+ * racing with `close-all`) get a no-op on the second pass.
+ */
 export function cancelAllRagOperations() {
-    for (const [key, entry] of activeOperations.entries()) {
-        entry.abortController.abort();
-        activeOperations.delete(key);
+    if (activeRagRequestByWorkspace.size === 0)
+        return;
+    const registry = getRequestRegistry();
+    for (const [key, requestId] of activeRagRequestByWorkspace) {
+        registry.cancel({ requestId, reason: "rag-shutdown" });
+        activeRagRequestByWorkspace.delete(key);
     }
 }

package/dist/server/bare/registry/model-config-utils.js

@@ -3,6 +3,8 @@ import { llmConfigSchema, embedConfigSchema } from "../../../schemas/llamacpp-co
 import { whisperConfigSchema, parakeetRuntimeConfigSchema, } from "../../../schemas/transcription-config.js";
 import { ocrConfigSchema } from "../../../schemas/ocr.js";
 import { sdcppConfigSchema } from "../../../schemas/sdcpp-config.js";
+import { vlaConfigSchema } from "../../../schemas/vla.js";
+import { classificationConfigSchema } from "../../../schemas/classification.js";
 export const CANONICAL_TO_ALIAS = {
     [ModelType.llamacppCompletion]: "llm",
     [ModelType.llamacppEmbedding]: "embeddings",
@@ -10,8 +12,11 @@ export const CANONICAL_TO_ALIAS = {
     [ModelType.parakeetTranscription]: "parakeet",
     [ModelType.nmtcppTranslation]: "nmt",
     [ModelType.onnxTts]: "tts",
+    [ModelType.ttsGgml]: "tts",
     [ModelType.onnxOcr]: "ocr",
     [ModelType.sdcppGeneration]: "diffusion",
+    [ModelType.ggmlVla]: "vla",
+    [ModelType.ggmlClassification]: "classification",
 };
 export const MODEL_CONFIG_SCHEMAS = {
     [ModelType.llamacppCompletion]: llmConfigSchema,
@@ -20,6 +25,8 @@ export const MODEL_CONFIG_SCHEMAS = {
     [ModelType.parakeetTranscription]: parakeetRuntimeConfigSchema.passthrough(),
     [ModelType.onnxOcr]: ocrConfigSchema,
     [ModelType.sdcppGeneration]: sdcppConfigSchema,
+    [ModelType.ggmlVla]: vlaConfigSchema,
+    [ModelType.ggmlClassification]: classificationConfigSchema,
 };
 // Ordered general → specific (later patterns override earlier)
 export const BUILTIN_DEVICE_PATTERNS = [

package/dist/server/bare/runtime/disposable-scope.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bounded-lifetime cleanup scope for an in-flight request.
+ *
+ * Callers register cleanup callbacks via `defer(...)` while a handler runs.
+ * On `[Symbol.asyncDispose]()` (used implicitly by `await using` or
+ * explicitly) every registered callback is awaited in **LIFO** order — the
+ * mirror of how `try/finally` blocks would unwind in a sequential write-up
+ * of the same handler.
+ *
+ * Guarantees:
+ *
+ *  - **Idempotent.** A scope can be disposed once. Subsequent disposes are
+ *    no-ops; subsequent `defer` calls run the cleanup eagerly so callers
+ *    never silently leak a deferred resource if they hand a deferred
+ *    callback to an already-disposed scope.
+ *  - **Error aggregation.** Every deferred cleanup runs even when an
+ *    earlier one throws. If a single cleanup throws, that error is
+ *    rethrown verbatim. If two or more throw, an `AggregateError` is
+ *    rethrown carrying every failure in the order it occurred. The
+ *    handler unwinding the scope can therefore see _all_ cleanup
+ *    failures, not just the first one.
+ */
+export interface DisposableScope {
+    /**
+     * Register a cleanup callback. Cleanups run on dispose in LIFO order.
+     * Calling `defer` after the scope has been disposed runs the cleanup
+     * eagerly so resources never leak silently.
+     */
+    defer(cleanup: () => Promise<void> | void): void;
+    /** Run all registered cleanups. Idempotent. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** True after the first dispose has been initiated. */
+    readonly disposed: boolean;
+}
+export declare function createDisposableScope(): DisposableScope;
+//# sourceMappingURL=disposable-scope.d.ts.map

package/dist/server/bare/runtime/disposable-scope.js

@@ -0,0 +1,69 @@
+import { AsyncDisposeUnavailableError } from "../../../utils/errors-server.js";
+/**
+ * Module-load guard. The whole request-lifecycle primitive stack (scopes,
+ * the registry's `ManagedRequestContext`, `await using ctx = ...`) is
+ * built on `Symbol.asyncDispose`, which is an ES2024 feature. If the host
+ * runtime doesn't expose it (older Bare/Expo build, missing polyfill),
+ * the `[Symbol.asyncDispose]:` property key in this file's `dispose`
+ * function would coerce to the string `"undefined"` and silently produce
+ * objects that look async-disposable but are not — handlers would leak
+ * registry entries forever. Better to fail loudly at import time with a
+ * clear error than to debug a slow registry leak in production.
+ */
+if (typeof Symbol.asyncDispose !== "symbol") {
+    throw new AsyncDisposeUnavailableError();
+}
+export function createDisposableScope() {
+    const cleanups = [];
+    let disposed = false;
+    let disposing = false;
+    function defer(cleanup) {
+        if (disposed || disposing) {
+            void runEagerly(cleanup);
+            return;
+        }
+        cleanups.push(cleanup);
+    }
+    async function runEagerly(cleanup) {
+        try {
+            await cleanup();
+        }
+        catch {
+            // Late-deferred cleanups have no caller waiting on them; the
+            // unwinding path that disposed the scope already returned its own
+            // errors. Swallowing here matches the user's intent of registering
+            // a fire-and-forget cleanup.
+        }
+    }
+    async function dispose() {
+        if (disposed || disposing)
+            return;
+        disposing = true;
+        const errors = [];
+        while (cleanups.length > 0) {
+            const cleanup = cleanups.pop();
+            if (!cleanup)
+                continue;
+            try {
+                await cleanup();
+            }
+            catch (err) {
+                errors.push(err);
+            }
+        }
+        disposed = true;
+        disposing = false;
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, `DisposableScope: ${errors.length} cleanups failed`);
+        }
+    }
+    return {
+        defer,
+        [Symbol.asyncDispose]: dispose,
+        get disposed() {
+            return disposed;
+        },
+    };
+}

package/dist/server/bare/runtime/index.d.ts

@@ -0,0 +1,8 @@
+export { createDisposableScope } from "./disposable-scope";
+export type { DisposableScope } from "./disposable-scope";
+export type { RequestContext, RequestKind, RequestState, } from "./request-context";
+export { createRequestRegistry, getRequestRegistry, } from "./request-registry-singleton";
+export type { BeginOpts, CancelByModelId, CancelByRequestId, CancelTarget, ConcurrencyPolicy, ManagedRequestContext, RequestOutcome, RequestRegistry, } from "./request-registry";
+export { withRequestContext } from "./with-request-context";
+export type { RequestLogContext } from "./with-request-context";
+//# sourceMappingURL=index.d.ts.map

package/dist/server/bare/runtime/index.js

@@ -0,0 +1,3 @@
+export { createDisposableScope } from "./disposable-scope.js";
+export { createRequestRegistry, getRequestRegistry, } from "./request-registry-singleton.js";
+export { withRequestContext } from "./with-request-context.js";

package/dist/server/bare/runtime/request-context.d.ts

@@ -0,0 +1,49 @@
+import type { AbortSignal } from "bare-abort-controller";
+import type { DisposableScope } from "./disposable-scope";
+/**
+ * Coarse classification of a long-running request. Used by
+ * `RequestRegistry.cancel({ modelId, kind })` so a broad cancel can target
+ * just one operation kind on a given model (e.g. cancel an in-flight
+ * completion without touching a finetune running on the same model).
+ *
+ * The set is intentionally open-coded — adding a new kind is a one-line
+ * change and the union surfaces in editor autocomplete at every call site.
+ */
+export type RequestKind = "completion" | "embeddings" | "transcribe" | "translate" | "diffusion" | "tts" | "ocr" | "vla" | "finetune" | "loadModel" | "downloadAsset" | "rag";
+/**
+ * Lifecycle states a request transitions through. A new context starts in
+ * `"running"`. `cancel(...)` flips it to `"cancelling"` and aborts the
+ * signal; `end({ outcome: "completed" | "failed" | "cancelled" })` flips
+ * it to a terminal state and removes it from the registry.
+ *
+ * Kept as a string union (not a state machine) on purpose — handlers read
+ * `state` defensively at most a couple of points and a flat enum is easier
+ * to log/assert than a transition table.
+ */
+export type RequestState = "running" | "cancelling" | "completed" | "failed" | "cancelled";
+/**
+ * Per-request lifecycle handle. Created by `RequestRegistry.begin(...)`
+ * and consumed by long-running handlers as the single owner of:
+ *
+ *  - `requestId` — stable identity; visible to the client so it can
+ *    target this exact request with `cancel({ requestId })`.
+ *  - `signal` — `AbortSignal` that fires when the request is cancelled.
+ *    Composes with addon-level cancellation through a single
+ *    `signal.addEventListener("abort", ...)` hook installed by the
+ *    handler.
+ *  - `scope` — `DisposableScope` for `await using` / `Symbol.asyncDispose`
+ *    cleanup. The scope unwinds whether the handler returns, throws, or
+ *    is cancelled — there is no manual cleanup path for handlers to
+ *    forget on the cancel branch.
+ *  - `state` — current lifecycle state. Treat as read-mostly; the
+ *    registry mutates it.
+ */
+export interface RequestContext {
+    readonly requestId: string;
+    readonly kind: RequestKind;
+    readonly modelId: string | undefined;
+    readonly signal: AbortSignal;
+    readonly scope: DisposableScope;
+    state: RequestState;
+}
+//# sourceMappingURL=request-context.d.ts.map

package/dist/server/bare/runtime/request-context.js

@@ -0,0 +1 @@
+export {};

package/dist/server/bare/runtime/request-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Server-side fallback for `requestId`. The new wire contract is that
+ * the client generates the id (UUIDv4) at call time so it's surfaced
+ * synchronously on the `CompletionRun` for use with `cancel({ requestId })`.
+ * To keep older clients working, the request schema marks `requestId`
+ * optional and the server fills it in here when it's missing.
+ *
+ * `bare-crypto.randomUUID()` mirrors Node's `crypto.randomUUID()` and is
+ * Bare-runtime safe. Returns a v4 UUID.
+ */
+export declare function generateServerRequestId(): string;
+//# sourceMappingURL=request-id.d.ts.map

package/dist/server/bare/runtime/request-id.js

@@ -0,0 +1,14 @@
+import { randomUUID } from "bare-crypto";
+/**
+ * Server-side fallback for `requestId`. The new wire contract is that
+ * the client generates the id (UUIDv4) at call time so it's surfaced
+ * synchronously on the `CompletionRun` for use with `cancel({ requestId })`.
+ * To keep older clients working, the request schema marks `requestId`
+ * optional and the server fills it in here when it's missing.
+ *
+ * `bare-crypto.randomUUID()` mirrors Node's `crypto.randomUUID()` and is
+ * Bare-runtime safe. Returns a v4 UUID.
+ */
+export function generateServerRequestId() {
+    return randomUUID();
+}

package/dist/server/bare/runtime/request-registry-singleton.d.ts

@@ -0,0 +1,4 @@
+import { createRequestRegistry as createRegistry, type RequestRegistry } from "./request-registry";
+export declare function getRequestRegistry(): RequestRegistry;
+export { createRegistry as createRequestRegistry };
+//# sourceMappingURL=request-registry-singleton.d.ts.map

package/dist/server/bare/runtime/request-registry-singleton.js

@@ -0,0 +1,27 @@
+import { createRequestRegistry as createRegistry, } from "./request-registry.js";
+/**
+ * Worker-process singleton. Every long-running request in this Bare
+ * worker registers under this registry, so a `cancel({ requestId })` RPC
+ * can find its target without the caller needing to know which plugin /
+ * handler owns the request.
+ *
+ * Exposed alongside `createRequestRegistry()` rather than replacing it so
+ * unit tests can spin up isolated registries without contaminating the
+ * shared instance. On first use the singleton registers the SDK's
+ * baseline concurrency policies.
+ */
+let registry = null;
+function installDefaultPolicies(r) {
+    // The llama.cpp addon owns one KV-cache + one decode loop per model,
+    // so two concurrent `completionStream` requests on the same model
+    // would interleave their token streams on the same logical session.
+    r.policy({ kind: "completion", oneAtATimePerModel: true });
+}
+export function getRequestRegistry() {
+    if (!registry) {
+        registry = createRegistry();
+        installDefaultPolicies(registry);
+    }
+    return registry;
+}
+export { createRegistry as createRequestRegistry };

package/dist/server/bare/runtime/request-registry.d.ts

@@ -0,0 +1,136 @@
+import { type AbortSignal } from "bare-abort-controller";
+import type { RequestContext, RequestKind } from "./request-context";
+import type { Logger } from "../../../logging/types";
+/**
+ * Outcome the caller declares when terminating a request through
+ * `registry.end(...)`. The registry maps it to a terminal `RequestState`
+ * before disposing the scope so observers see a coherent final state.
+ */
+export type RequestOutcome = "completed" | "failed" | "cancelled";
+export interface BeginOpts {
+    /** Stable identity. Caller-provided so the client and server agree. */
+    requestId: string;
+    kind: RequestKind;
+    modelId?: string;
+    /**
+     * Optional parent abort signal — typically the worker-level "shutdown"
+     * signal. When the parent aborts, the request's own signal aborts too.
+     * Composes through a `addEventListener("abort", ...)` hook so cancelling
+     * the parent does not require iterating the registry.
+     */
+    parentSignal?: AbortSignal;
+}
+export interface CancelByRequestId {
+    requestId: string;
+    reason?: string;
+}
+export interface CancelByModelId {
+    modelId: string;
+    kind?: RequestKind;
+    reason?: string;
+}
+export type CancelTarget = CancelByRequestId | CancelByModelId;
+/**
+ * Per-kind admission rule. Kinds without a registered policy have no
+ * admission control (every `begin(...)` is accepted as long as the
+ * request id is unique).
+ */
+export interface ConcurrencyPolicy {
+    kind: RequestKind;
+    /**
+     * When true, at most one in-flight request per `(kind, modelId)`
+     * tuple — a second `begin(...)` rejects with
+     * `RequestRejectedByPolicyError`. Requests without a `modelId` are
+     * unaffected.
+     */
+    oneAtATimePerModel: boolean;
+}
+/**
+ * `ManagedRequestContext` is the value `begin(...)` returns. It extends
+ * `RequestContext` with an async-dispose method so handlers can write:
+ *
+ *   await using ctx = registry.begin({ ... });
+ *
+ * On dispose the scope unwinds (LIFO cleanup) and the registry slot is
+ * freed. If the handler doesn't override `ctx.state` before unwinding,
+ * the registry derives the terminal state from `signal.aborted` —
+ * `"cancelled"` when an abort was recorded, `"completed"` otherwise.
+ */
+export interface ManagedRequestContext extends RequestContext {
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export interface RequestRegistry {
+    /**
+     * Open a new request. Throws:
+     *  - `RequestIdConflictError` if `requestId` is already present
+     *    (UUIDv4 collision is astronomically unlikely; the guard exists
+     *    so a buggy client retry sending the same id can't silently
+     *    overwrite an in-flight request).
+     *  - `RequestRejectedByPolicyError` if a concurrency policy was
+     *    registered for `opts.kind` and the new request would violate
+     *    it (e.g. `oneAtATimePerModel` rejects when another request
+     *    with the same `(kind, modelId)` pair is already in flight).
+     */
+    begin(opts: BeginOpts): ManagedRequestContext;
+    /**
+     * Register or replace the concurrency policy for a `RequestKind`.
+     * Subsequent `begin(...)` calls for that kind run the policy before
+     * allocating a controller / scope. One policy per kind — calling
+     * twice replaces the previous declaration.
+     *
+     * @example
+     *   r.policy({ kind: "completion", oneAtATimePerModel: true });
+     *   await using a = r.begin({ requestId: "r-1", kind: "completion", modelId: "m1" });
+     *   r.begin({ requestId: "r-2", kind: "completion", modelId: "m1" });
+     *   // → throws RequestRejectedByPolicyError (code 52420)
+     */
+    policy(opts: ConcurrencyPolicy): void;
+    /** Look up an in-flight request by id. */
+    get(requestId: string): RequestContext | null;
+    /**
+     * Snapshot of currently-tracked requests. Useful for diagnostics /
+     * structured logs ("which requests are in flight right now?"). Returns
+     * a fresh array; mutations on it are not observed by the registry.
+     */
+    list(): RequestContext[];
+    /**
+     * Cancel matching requests. Returns the number of contexts whose abort
+     * was triggered by *this* call (already-cancelled contexts are skipped
+     * so callers can rely on the count to log "n requests cancelled" once).
+     *
+     * For `{ modelId }` and an optional `kind`, cancels every active
+     * request that matches the predicate. This is the broad-cancel path
+     * the pre-registry `cancel({ modelId })` API maps to.
+     */
+    cancel(target: CancelTarget): number;
+    /**
+     * Cancel every active request — the worker-shutdown / model-unload
+     * sweep. The reason is forwarded to each request as the abort reason
+     * so handler logs can distinguish a normal cancel from a sweep.
+     * Resolves once all targeted contexts have flipped to `"cancelling"`;
+     * scope unwinding still happens on each handler's own dispose path.
+     */
+    cancelAll(reason: "shutdown" | "modelUnload"): Promise<void>;
+    /**
+     * Mark a request finished and dispose its scope. Equivalent to
+     * `await ctx[Symbol.asyncDispose]()` with an explicit outcome.
+     * Idempotent — calling `end` after a scope dispose is a no-op.
+     */
+    end(requestId: string, outcome: RequestOutcome): Promise<void>;
+}
+export declare function createRequestRegistry(options?: {
+    /** Defaults to `getServerLogger()`. Tests inject a stub. */
+    logger?: Logger;
+}): RequestRegistry;
+/**
+ * Test-only knobs exported for `request-registry.test.ts` so the bound
+ * assertions can pin the documented limits without re-reading them via
+ * fragile string comparison. **Not part of the public SDK surface.**
+ *
+ * @internal
+ */
+export declare const __requestRegistryTestHooks: {
+    cancelBeforeBeginMaxEntries: number;
+    cancelBeforeBeginTtlMs: number;
+};
+//# sourceMappingURL=request-registry.d.ts.map