@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/client/api/rag.js

@@ -0,0 +1,490 @@
+import { send, stream } from '../rpc/rpc-client.js';
+import { InvalidResponseError, InvalidOperationError, StreamEndedError, RAGChunkFailedError, RAGSaveFailedError, RAGSearchFailedError, RAGDeleteFailedError, RAGCloseWorkspaceFailedError, RAGListWorkspacesFailedError } from '../../utils/errors-client.js';
+import { generateClientRequestId } from './client-request-id.js';
+import { decoratePromise } from '../../utils/decorate-promise.js';
+// ============== Chunk ==============
+/**
+ * Chunks documents into smaller pieces for embedding.
+ * Part of the segregated flow: ragChunk() → embed() → ragSaveEmbeddings()
+ *
+ * @param params - The parameters for chunking
+ * @param params.documents - Documents to chunk (string or array)
+ * @param params.chunkOpts - Chunking options (chunkSize, chunkOverlap, chunkStrategy)
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns Array of chunk results with id and content
+ * @throws {RAGChunkFailedError} When the operation fails
+ *
+ * @example
+ * ```typescript
+ * const chunks = await ragChunk({
+ *   documents: ["Long document text here..."],
+ *   chunkOpts: {
+ *     chunkSize: 256,
+ *     chunkOverlap: 50,
+ *     chunkStrategy: "paragraph",
+ *   },
+ * });
+ * ```
+ */
+export async function ragChunk(params, options) {
+    const request = {
+        type: 'rag',
+        operation: 'chunk',
+        ...params
+    };
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGChunkFailedError(response.error);
+    }
+    if (response.operation !== 'chunk') {
+        throw new InvalidOperationError();
+    }
+    return response.chunks;
+}
+// ============== Ingest ==============
+/**
+ * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+ *
+ * Ingests documents into the RAG vector database.
+ * Full pipeline: chunk → embed → save
+ *
+ * **Workspace lifecycle:** This operation implicitly opens (or creates) the workspace.
+ * The workspace remains open until closed.
+ *
+ * @param params - The embedding model, documents, optional chunking settings,
+ *   workspace (default: `"default"`), and progress callback configuration.
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns Processing results and dropped indices
+ * @throws {RAGSaveFailedError} When the operation fails
+ * @throws {StreamEndedError} When streaming ends unexpectedly (only when using onProgress)
+ *
+ * @example
+ * ```typescript
+ * // Simple ingest
+ * const result = await ragIngest({
+ *   modelId,
+ *   documents: ["Document 1", "Document 2"],
+ * });
+ *
+ * // With progress tracking
+ * const result = await ragIngest({
+ *   modelId,
+ *   documents: ["Document 1", "Document 2"],
+ *   workspace: "my-docs",
+ *   onProgress: (stage, current, total) => {
+ *     console.log(`[${stage}] ${current}/${total}`);
+ *   },
+ * });
+ * ```
+ */
+export function ragIngest(params, options) {
+    const requestId = generateClientRequestId();
+    const inner = runRagIngest(params, requestId, options);
+    return decoratePromise(inner, { requestId });
+}
+async function runRagIngest(params, requestId, options) {
+    const { onProgress, ...requestParams } = params;
+    const request = {
+        type: 'rag',
+        operation: 'ingest',
+        ...requestParams,
+        chunk: requestParams.chunk ?? true,
+        withProgress: onProgress ? true : undefined,
+        requestId
+    };
+    if (onProgress) {
+        // Use streaming for progress updates
+        for await (const event of stream(request, options)) {
+            if (event.type === 'rag:progress' && event.operation === 'ingest') {
+                const progress = event;
+                onProgress(progress.stage, progress.current, progress.total);
+                continue;
+            }
+            if (event.type === 'rag' && event.operation === 'ingest') {
+                if (!event.success) {
+                    throw new RAGSaveFailedError(event.error);
+                }
+                return {
+                    processed: event.processed,
+                    droppedIndices: event.droppedIndices
+                };
+            }
+        }
+        throw new StreamEndedError();
+    }
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGSaveFailedError(response.error);
+    }
+    if (response.operation !== 'ingest') {
+        throw new InvalidOperationError();
+    }
+    return {
+        processed: response.processed,
+        droppedIndices: response.droppedIndices
+    };
+}
+// ============== SaveEmbeddings ==============
+/**
+ * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+ *
+ * Saves pre-embedded documents to the RAG vector database.
+ * Part of the segregated flow: chunk() → embed() → saveEmbeddings()
+ *
+ * **Workspace lifecycle:** This operation implicitly opens (or creates) the workspace.
+ * The workspace remains open until closed.
+ *
+ * @param params - The pre-embedded documents, workspace (default:
+ *   `"default"`), and optional progress callback configuration.
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns Array of save results
+ * @throws {RAGSaveFailedError} When the operation fails
+ * @throws {StreamEndedError} When streaming ends unexpectedly (only when using onProgress)
+ *
+ * @example
+ * ```typescript
+ * // Segregated flow
+ * const chunks = await ragChunk({ documents: ["text1", "text2"] });
+ * const { embedding: embeddings } = await embed({ modelId, text: chunks.map(c => c.content) });
+ * const embeddedDocs = chunks.map((chunk, i) => ({
+ *   ...chunk,
+ *   embedding: embeddings[i],
+ *   embeddingModelId: modelId,
+ * }));
+ * const result = await ragSaveEmbeddings({
+ *   documents: embeddedDocs,
+ *   workspace: "my-workspace",
+ * });
+ * ```
+ */
+export function ragSaveEmbeddings(params, options) {
+    const requestId = generateClientRequestId();
+    const inner = runRagSaveEmbeddings(params, requestId, options);
+    return decoratePromise(inner, { requestId });
+}
+async function runRagSaveEmbeddings(params, requestId, options) {
+    const { onProgress, ...requestParams } = params;
+    const request = {
+        type: 'rag',
+        operation: 'saveEmbeddings',
+        ...requestParams,
+        withProgress: onProgress ? true : undefined,
+        requestId
+    };
+    if (onProgress) {
+        for await (const event of stream(request, options)) {
+            if (event.type === 'rag:progress' && event.operation === 'saveEmbeddings') {
+                const progress = event;
+                onProgress(progress.stage, progress.current, progress.total);
+                continue;
+            }
+            if (event.type === 'rag' && event.operation === 'saveEmbeddings') {
+                if (!event.success) {
+                    throw new RAGSaveFailedError(event.error);
+                }
+                return event.processed;
+            }
+        }
+        throw new StreamEndedError();
+    }
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGSaveFailedError(response.error);
+    }
+    if (response.operation !== 'saveEmbeddings') {
+        throw new InvalidOperationError();
+    }
+    return response.processed;
+}
+// ============== Search ==============
+/**
+ * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+ *
+ * Searches for similar documents in the RAG vector database.
+ *
+ * **Workspace lifecycle:** This operation requires an existing workspace. If the workspace
+ * doesn't exist, returns an empty array.
+ *
+ * @param params - The parameters for searching
+ * @param params.modelId - The identifier of the embedding model to use
+ * @param params.query - The search query text
+ * @param params.topK - Number of top results to retrieve (default: 5)
+ * @param params.n - Number of centroids to use for IVF index search (default: 3)
+ * @param params.workspace - Workspace to search in (default: "default").
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns Array of search results with id, content, and score. Empty array if workspace doesn't exist.
+ * @throws {RAGSearchFailedError} When the operation fails
+ *
+ * @example
+ * ```typescript
+ * const results = await ragSearch({
+ *   modelId,
+ *   query: "AI and machine learning",
+ *   topK: 5,
+ *   workspace: "my-docs",
+ * });
+ * ```
+ */
+export async function ragSearch(params, options) {
+    const request = {
+        type: 'rag',
+        operation: 'search',
+        ...params,
+        topK: params.topK ?? 5,
+        n: params.n ?? 3
+    };
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGSearchFailedError(response.error);
+    }
+    if (response.operation !== 'search') {
+        throw new InvalidOperationError();
+    }
+    return response.results;
+}
+// ============== Delete Embeddings ==============
+/**
+ * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+ *
+ * Deletes document embeddings from the RAG vector database.
+ *
+ * **Workspace lifecycle:** This operation requires an existing workspace.
+ *
+ * @param params - The parameters for deleting embeddings
+ * @param params.ids - Array of document IDs to delete
+ * @param params.workspace - Workspace to delete from (default: "default")
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @throws {RAGDeleteFailedError} When the operation fails or workspace doesn't exist
+ *
+ * @example
+ * ```typescript
+ * await ragDeleteEmbeddings({
+ *   ids: ["doc-1", "doc-2"],
+ *   workspace: "my-docs",
+ * });
+ * ```
+ */
+export async function ragDeleteEmbeddings(params, options) {
+    const request = {
+        type: 'rag',
+        operation: 'deleteEmbeddings',
+        ...params
+    };
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGDeleteFailedError(response.error);
+    }
+    if (response.operation !== 'deleteEmbeddings') {
+        throw new InvalidOperationError();
+    }
+}
+// ============== Reindex ==============
+/**
+ * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+ *
+ * Reindexes the RAG database to optimize search performance.
+ * For HyperDB, this rebalances centroids using k-means clustering.
+ *
+ * **Workspace lifecycle:** This operation requires an existing workspace.
+ *
+ * **Note:** Reindex requires a minimum number of documents to perform clustering.
+ * For HyperDB, this is 16 documents by default. If there are insufficient documents,
+ * `reindexed` will be `false` with `details` explaining the reason.
+ *
+ * @param params - The existing workspace to reindex (default: `"default"`)
+ *   and optional progress callback.
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns Reindex result with `reindexed` boolean and optional `details`
+ * @throws {RAGSaveFailedError} When the operation fails or workspace doesn't exist
+ * @throws {StreamEndedError} When streaming ends unexpectedly (only when using onProgress)
+ *
+ * @example
+ * ```typescript
+ * // Simple reindex
+ * const result = await ragReindex({
+ *   workspace: "my-docs",
+ * });
+ *
+ * // Check result
+ * if (!result.reindexed) {
+ *   console.log("Reindex skipped:", result.details?.reason);
+ * }
+ *
+ * // With progress tracking
+ * const result = await ragReindex({
+ *   workspace: "my-docs",
+ *   onProgress: (stage, current, total) => {
+ *     console.log(`[${stage}] ${current}/${total}`);
+ *   },
+ * });
+ * ```
+ */
+export function ragReindex(params, options) {
+    const requestId = generateClientRequestId();
+    const inner = runRagReindex(params, requestId, options);
+    return decoratePromise(inner, { requestId });
+}
+async function runRagReindex(params, requestId, options) {
+    const { onProgress, ...requestParams } = params;
+    const request = {
+        type: 'rag',
+        operation: 'reindex',
+        ...requestParams,
+        withProgress: onProgress ? true : undefined,
+        requestId
+    };
+    if (onProgress) {
+        for await (const event of stream(request, options)) {
+            if (event.type === 'rag:progress' && event.operation === 'reindex') {
+                const progress = event;
+                onProgress(progress.stage, progress.current, progress.total);
+                continue;
+            }
+            if (event.type === 'rag' && event.operation === 'reindex') {
+                if (!event.success) {
+                    throw new RAGSaveFailedError(event.error);
+                }
+                return event.result;
+            }
+        }
+        throw new StreamEndedError();
+    }
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGSaveFailedError(response.error);
+    }
+    if (response.operation !== 'reindex') {
+        throw new InvalidOperationError();
+    }
+    return response.result;
+}
+// ============== List Workspaces ==============
+/**
+ * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+ *
+ * Lists all RAG workspaces with their open status.
+ *
+ * Returns all workspaces that exist on disk. The `open` field indicates whether
+ * the workspace is currently loaded in memory and holding active resources
+ * (Corestore, HyperDB adapter, and possibly a RAG instance).
+ *
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns Array of workspace info with name and open status
+ * @throws {RAGListWorkspacesFailedError} When the operation fails
+ *
+ * @example
+ * ```typescript
+ * const workspaces = await ragListWorkspaces();
+ * // [{ name: "default", open: true }, { name: "my-docs", open: false }]
+ * ```
+ */
+export async function ragListWorkspaces(options) {
+    const request = {
+        type: 'rag',
+        operation: 'listWorkspaces'
+    };
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGListWorkspacesFailedError(response.error);
+    }
+    if (response.operation !== 'listWorkspaces') {
+        throw new InvalidOperationError();
+    }
+    return response.workspaces;
+}
+// ============== Close Workspace ==============
+/**
+ * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+ *
+ * Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance).
+ *
+ * **Workspace lifecycle:** Workspaces are implicitly opened.
+ * This function explicitly closes them, releasing memory and file locks. The workspace data
+ * remains on disk unless `deleteOnClose` is set to true.
+ *
+ * @param params - The workspace to close (default: `"default"`) and whether
+ *   its on-disk data should also be deleted.
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @throws {RAGCloseWorkspaceFailedError} When the operation fails
+ *
+ * @example
+ * ```typescript
+ * // Close a specific workspace
+ * await ragCloseWorkspace({ workspace: "my-docs" });
+ *
+ * // Close and delete in one call
+ * await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true });
+ * ```
+ */
+export async function ragCloseWorkspace(params, options) {
+    const request = {
+        type: 'rag',
+        operation: 'closeWorkspace',
+        ...params
+    };
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGCloseWorkspaceFailedError(response.error);
+    }
+    if (response.operation !== 'closeWorkspace') {
+        throw new InvalidOperationError();
+    }
+}
+// ============== Delete Workspace ==============
+/**
+ * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+ *
+ * Deletes a RAG workspace and all its data.
+ * The workspace must not be currently loaded/in-use.
+ *
+ * @param params - The parameters for deletion
+ * @param params.workspace - Name of the workspace to delete
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @throws {RAGDeleteFailedError} When the workspace doesn't exist or is currently loaded
+ *
+ * @example
+ * ```typescript
+ * await ragDeleteWorkspace({ workspace: "my-docs" });
+ * ```
+ */
+export async function ragDeleteWorkspace(params, options) {
+    const request = {
+        type: 'rag',
+        operation: 'deleteWorkspace',
+        ...params
+    };
+    const response = await send(request, options);
+    if (response.type !== 'rag') {
+        throw new InvalidResponseError('rag');
+    }
+    if (!response.success) {
+        throw new RAGDeleteFailedError(response.error);
+    }
+    if (response.operation !== 'deleteWorkspace') {
+        throw new InvalidOperationError();
+    }
+}

package/dist/src/client/api/registry.d.ts

@@ -0,0 +1,40 @@
+import type { ModelRegistryEntry, ModelRegistryEntryAddon } from '@qvac/inference/surface';
+export type { ModelRegistryEntry, ModelRegistryEntryAddon };
+export interface ModelRegistrySearchParams {
+    filter?: string;
+    engine?: string;
+    quantization?: string;
+    modelType?: ModelRegistryEntryAddon;
+    addon?: ModelRegistryEntryAddon;
+}
+/**
+ * Returns all available models from the QVAC distributed model registry.
+ *
+ * @returns A promise resolving to an array of `ModelRegistryEntry` describing every model the SDK's connected registry knows about.
+ * @throws {ModelRegistryQueryFailedError} When the registry query fails.
+ */
+declare function modelRegistryList(): Promise<ModelRegistryEntry[]>;
+/**
+ * Searches the model registry with optional filters for model type, engine, and quantization.
+ *
+ * @param params - Search filters (all optional).
+ * @param params.filter - Free-text filter matched against model metadata.
+ * @param params.engine - Inference engine identifier (e.g., `"llamacpp-completion"`).
+ * @param params.quantization - Quantization identifier (e.g., `"Q4_K_M"`).
+ * @param params.modelType - Alias for `addon`; kept for backward compatibility.
+ * @param params.addon - Model addon / category to restrict results to.
+ * @returns A promise resolving to the matching `ModelRegistryEntry` entries.
+ * @throws {ModelRegistryQueryFailedError} When the registry query fails.
+ */
+declare function modelRegistrySearch(params?: ModelRegistrySearchParams): Promise<ModelRegistryEntry[]>;
+/**
+ * Fetches a single model entry from the registry by its path and source.
+ *
+ * @param registryPath - Registry-relative path of the model to fetch.
+ * @param registrySource - Registry source identifier (e.g., `"huggingface"`, `"local"`).
+ * @returns A promise resolving to the matching `ModelRegistryEntry`.
+ * @throws {ModelRegistryQueryFailedError} When the model cannot be located or the registry query fails.
+ */
+declare function modelRegistryGetModel(registryPath: string, registrySource: string): Promise<ModelRegistryEntry>;
+export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel };
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/client/api/registry.js

@@ -0,0 +1,63 @@
+import { send } from '../rpc/rpc-client.js';
+import { ModelRegistryQueryFailedError } from '../../utils/errors-client.js';
+function validateRegistryResponse(response, fallbackError) {
+    if (!response.success) {
+        throw new ModelRegistryQueryFailedError(response.error ?? fallbackError ?? 'Unknown registry error');
+    }
+}
+/**
+ * Returns all available models from the QVAC distributed model registry.
+ *
+ * @returns A promise resolving to an array of `ModelRegistryEntry` describing every model the SDK's connected registry knows about.
+ * @throws {ModelRegistryQueryFailedError} When the registry query fails.
+ */
+async function modelRegistryList() {
+    const request = {
+        type: 'modelRegistryList'
+    };
+    const response = (await send(request));
+    validateRegistryResponse(response);
+    return response.models;
+}
+/**
+ * Searches the model registry with optional filters for model type, engine, and quantization.
+ *
+ * @param params - Search filters (all optional).
+ * @param params.filter - Free-text filter matched against model metadata.
+ * @param params.engine - Inference engine identifier (e.g., `"llamacpp-completion"`).
+ * @param params.quantization - Quantization identifier (e.g., `"Q4_K_M"`).
+ * @param params.modelType - Alias for `addon`; kept for backward compatibility.
+ * @param params.addon - Model addon / category to restrict results to.
+ * @returns A promise resolving to the matching `ModelRegistryEntry` entries.
+ * @throws {ModelRegistryQueryFailedError} When the registry query fails.
+ */
+async function modelRegistrySearch(params = {}) {
+    const { modelType, ...rest } = params;
+    const request = {
+        type: 'modelRegistrySearch',
+        ...rest,
+        addon: modelType ?? rest.addon
+    };
+    const response = (await send(request));
+    validateRegistryResponse(response);
+    return response.models;
+}
+/**
+ * Fetches a single model entry from the registry by its path and source.
+ *
+ * @param registryPath - Registry-relative path of the model to fetch.
+ * @param registrySource - Registry source identifier (e.g., `"huggingface"`, `"local"`).
+ * @returns A promise resolving to the matching `ModelRegistryEntry`.
+ * @throws {ModelRegistryQueryFailedError} When the model cannot be located or the registry query fails.
+ */
+async function modelRegistryGetModel(registryPath, registrySource) {
+    const request = {
+        type: 'modelRegistryGetModel',
+        registryPath,
+        registrySource
+    };
+    const response = (await send(request));
+    validateRegistryResponse(response, `Model not found: ${registrySource}/${registryPath}`);
+    return response.model;
+}
+export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel };

package/dist/src/client/api/resume.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resumes the SDK runtime: restores all suspended Hyperswarm and Corestore
+ * resources and releases the lifecycle gate so all SDK operations are allowed
+ * again.
+ *
+ * Safe to call from any lifecycle state — `resume()` is never blocked by the
+ * lifecycle gate (along with `suspend()` and `state()`). Idempotent. Also
+ * serves as the recovery path after a partial suspend failure.
+ *
+ * After `resume()` resolves successfully, runtime state is `"active"` and
+ * non-lifecycle SDK operations are accepted normally.
+ *
+ * Behavior of in-flight operations from before the previous `suspend()`:
+ *   - P2P / Hyperdrive downloads: continue automatically once their underlying
+ *     swarm/corestore is restored
+ *
+ * @throws {RPCError} When one or more resources fail to resume. On partial
+ *   failure the runtime stays `"suspended"` (operations remain blocked) so
+ *   callers can retry `resume()`.
+ *
+ * @example
+ * // Foreground handler
+ * await resume();
+ * console.log(await state()); // "active"
+ */
+export declare function resume(): Promise<void>;
+//# sourceMappingURL=resume.d.ts.map

package/dist/src/client/api/resume.js

@@ -0,0 +1,33 @@
+import { send } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+/**
+ * Resumes the SDK runtime: restores all suspended Hyperswarm and Corestore
+ * resources and releases the lifecycle gate so all SDK operations are allowed
+ * again.
+ *
+ * Safe to call from any lifecycle state — `resume()` is never blocked by the
+ * lifecycle gate (along with `suspend()` and `state()`). Idempotent. Also
+ * serves as the recovery path after a partial suspend failure.
+ *
+ * After `resume()` resolves successfully, runtime state is `"active"` and
+ * non-lifecycle SDK operations are accepted normally.
+ *
+ * Behavior of in-flight operations from before the previous `suspend()`:
+ *   - P2P / Hyperdrive downloads: continue automatically once their underlying
+ *     swarm/corestore is restored
+ *
+ * @throws {RPCError} When one or more resources fail to resume. On partial
+ *   failure the runtime stays `"suspended"` (operations remain blocked) so
+ *   callers can retry `resume()`.
+ *
+ * @example
+ * // Foreground handler
+ * await resume();
+ * console.log(await state()); // "active"
+ */
+export async function resume() {
+    const response = await send({ type: 'resume' });
+    if (response.type !== 'resume') {
+        throw new InvalidResponseError('resume');
+    }
+}

package/dist/src/client/api/state.d.ts

@@ -0,0 +1,23 @@
+import type { LifecycleState } from '@qvac/inference/surface';
+/**
+ * Returns the current runtime lifecycle state.
+ *
+ * Safe to call from any lifecycle state — `state()` is never blocked by the
+ * lifecycle gate (along with `suspend()` and `resume()`).
+ *
+ * @returns The current lifecycle state:
+ *   - `"active"`: all SDK operations are allowed
+ *   - `"suspending"` | `"suspended"` | `"resuming"`: non-lifecycle operations
+ *     throw `LifecycleOperationBlockedError`
+ *
+ * @throws {InvalidResponseError} When the response envelope does not match the request type.
+ *
+ * @example
+ * // Branch on lifecycle state before issuing work
+ * const current = await state();
+ * if (current !== "active") {
+ *   await resume();
+ * }
+ */
+export declare function state(): Promise<LifecycleState>;
+//# sourceMappingURL=state.d.ts.map