@autorag/librarian 2.4.2 → 2.5.1

package/dist/datasource/connector-skill.d.ts

@@ -1,6 +1,6 @@
 /**
  * Shared {@link DatasourceSkill} implementation for connector-backed
- * datasources (Slack, Discord, Notion, GitHub, Google Drive, Gmail/IMAP,
+ * datasources (Slack, Discord, Notion, GitHub, Google Drive,
  * local mail exports, RSS/news).
  *
  * Composition: a trusted {@link DatasourceConnector} fetches documents, a

package/dist/datasource/connector.d.ts

@@ -1,6 +1,6 @@
 /**
  * Connector contract shared by the built-in datasource skills (Slack, Discord,
- * Notion, GitHub, Google Drive, Gmail/IMAP, local mail exports,
+ * Notion, GitHub, Google Drive, local mail exports,
  * RSS/news).
  *
  * A *connector* is the trusted, server-configured bridge to one external

package/dist/datasource/index.d.ts

@@ -9,10 +9,9 @@ export { DatasourceSkillRegistry, type RegisteredDatasourceSkill } from "./regis
 export { DatasourceResultFilter, type ResultsByMethod } from "./result-filter.js";
 export { buildDatasourceChunkSource, buildDatasourceInstanceSource, DATASOURCE_CHUNKS_SEGMENT, datasourceSourceHasFragment, datasourceSourcePath, isDatasourceSource, matchesDatasourceScope, matchesVirtualPathScope, normalizeVirtualPath, } from "./scope.js";
 export { CLOUD_DRIVE_SKILL_DEFINITION, CloudDriveSkill, type CloudDriveSkillOptions, RcloneConnector, type RcloneConnectorOptions, type RcloneRunner, type RcloneRunResult, } from "./skills/cloud-drive/index.js";
-export { DEFAULT_DISCRAWL_EMBEDDING_MODEL, DEFAULT_DISCRAWL_MODE, DEFAULT_DISCRAWL_SOURCE, DiscrawlClient, type DiscrawlFailureReason, DiscrawlFtsMethod, DiscrawlHybridMethod, type DiscrawlOptions, type DiscrawlSearchHit, type DiscrawlSearchMode, type DiscrawlSearchOptions, type DiscrawlSearchResult, DiscrawlSemanticMethod, DiscrawlSkill, type DiscrawlSkillClient, type DiscrawlSkillOptions, type DiscrawlSourceKind, ENGLISH_ONLY_EMBEDDING_MODELS, } from "./skills/discrawl/index.js";
+export { DEFAULT_DISCRAWL_EMBEDDING_MODEL, DEFAULT_DISCRAWL_MODE, DiscrawlClient, type DiscrawlFailureReason, DiscrawlFtsMethod, DiscrawlHybridMethod, type DiscrawlOptions, type DiscrawlSearchHit, type DiscrawlSearchMode, type DiscrawlSearchOptions, type DiscrawlSearchResult, DiscrawlSemanticMethod, DiscrawlSkill, type DiscrawlSkillClient, type DiscrawlSkillOptions, ENGLISH_ONLY_EMBEDDING_MODELS, } from "./skills/discrawl/index.js";
 export { BUILTIN_DATASOURCE_SKILL_NAMES, type BuildDatasourceSkillsResult, buildDatasourceSkills, type DatasourceSkillConfig, type DatasourcesConfig, } from "./skills/factory.js";
 export { GitHubConnector, type GitHubConnectorOptions, GitHubSkill, type GitHubSkillOptions, } from "./skills/github/index.js";
-export { GmailConnector, type GmailConnectorOptions, GmailSkill, type GmailSkillOptions, } from "./skills/gmail/index.js";
 export type { KatokFailureReason, KatokHit, KatokOptions, KatokSearchMode, KatokSearchOptions, KatokSearchResult, KatokSkillClient, KatokSkillOptions, } from "./skills/katok/index.js";
 export { KatokBm25Method, KatokClient, KatokSemanticMethod, KatokSkill, } from "./skills/katok/index.js";
 export { MailExportConnector, type MailExportConnectorOptions, MailExportSkill, type MailExportSkillOptions, } from "./skills/mail-export/index.js";

package/dist/datasource/skills/discrawl/client.d.ts

@@ -1,4 +1,4 @@
-import type { DiscrawlDoctorResult, DiscrawlEmbedResult, DiscrawlOptions, DiscrawlSearchMode, DiscrawlSearchOptions, DiscrawlSearchResult, DiscrawlStatusResult, DiscrawlSyncResult } from "./types.js";
+import type { DiscrawlDoctorResult, DiscrawlEmbeddingConfigResult, DiscrawlEmbeddingRuntime, DiscrawlEmbedResult, DiscrawlMetadataResult, DiscrawlOptions, DiscrawlSearchMode, DiscrawlSearchOptions, DiscrawlSearchResult, DiscrawlStatusResult, DiscrawlSyncResult } from "./types.js";
 /**
  * Thin external `discrawl` CLI wrapper. Every method spawns the `discrawl`
  * binary as a child process, parses JSON from stdout, and returns a
@@ -12,12 +12,22 @@ import type { DiscrawlDoctorResult, DiscrawlEmbedResult, DiscrawlOptions, Discra
 export declare class DiscrawlClient {
     private readonly options;
     constructor(options?: DiscrawlOptions);
+    configureEmbeddings(runtime: DiscrawlEmbeddingRuntime): Promise<DiscrawlEmbeddingConfigResult>;
+    prepareEmbeddings(): Promise<boolean>;
+    metadata(signal?: AbortSignal): Promise<DiscrawlMetadataResult>;
     doctor(signal?: AbortSignal): Promise<DiscrawlDoctorResult>;
     status(signal?: AbortSignal): Promise<DiscrawlStatusResult>;
+    /**
+     * Imports new messages from the local Discord Desktop cache through
+     * `discrawl wiretap`. AutoRAG never drives discrawl's bot sync — that path
+     * belongs to the CLI, which owns its own credential — so no Discord token is
+     * involved in an AutoRAG refresh.
+     */
     sync(signal?: AbortSignal): Promise<DiscrawlSyncResult>;
-    embed(limit?: number, signal?: AbortSignal): Promise<DiscrawlEmbedResult>;
+    embed(limit?: number, rebuild?: boolean, signal?: AbortSignal): Promise<DiscrawlEmbedResult>;
     search(mode: DiscrawlSearchMode, query: string, options?: DiscrawlSearchOptions): Promise<DiscrawlSearchResult>;
     private runJson;
     private run;
 }
 export declare function discrawlWorkspace(options: DiscrawlOptions): string | undefined;
+export declare function nativeGatewayBaseUrl(baseUrl: string): string;

package/dist/datasource/skills/discrawl/index.d.ts

@@ -2,4 +2,4 @@ export { DiscrawlClient, discrawlWorkspace } from "./client.js";
 export { DiscrawlFtsMethod, DiscrawlHybridMethod, type DiscrawlMethodOptions, type DiscrawlSearchClient, DiscrawlSemanticMethod, } from "./methods.js";
 export { DISCRAWL_SOURCE_KIND, discrawlConfigPath, discrawlDatabasePath, discrawlDatasourceRoot, discrawlSourcePath, parseDiscrawlSourcePath, } from "./paths.js";
 export { DiscrawlSkill, type DiscrawlSkillClient, type DiscrawlSkillOptions } from "./skill.js";
-export { DEFAULT_DISCRAWL_BINARY, DEFAULT_DISCRAWL_EMBEDDING_MODEL, DEFAULT_DISCRAWL_EMBEDDING_PROVIDER, DEFAULT_DISCRAWL_MAX_BUFFER_BYTES, DEFAULT_DISCRAWL_MODE, DEFAULT_DISCRAWL_SOURCE, DEFAULT_DISCRAWL_TIMEOUT_MS, type DiscrawlDoctorInfo, type DiscrawlDoctorResult, type DiscrawlEmbedInfo, type DiscrawlEmbedResult, type DiscrawlFailure, type DiscrawlFailureReason, type DiscrawlMessage, type DiscrawlOptions, type DiscrawlSearchHit, type DiscrawlSearchMode, type DiscrawlSearchOptions, type DiscrawlSearchResult, type DiscrawlSourceKind, type DiscrawlStatusInfo, type DiscrawlStatusResult, type DiscrawlSyncInfo, type DiscrawlSyncResult, ENGLISH_ONLY_EMBEDDING_MODELS, } from "./types.js";
+export { DEFAULT_DISCRAWL_BINARY, DEFAULT_DISCRAWL_EMBEDDING_MODEL, DEFAULT_DISCRAWL_EMBEDDING_PROVIDER, DEFAULT_DISCRAWL_MAX_BUFFER_BYTES, DEFAULT_DISCRAWL_MODE, DEFAULT_DISCRAWL_TIMEOUT_MS, type DiscrawlDoctorInfo, type DiscrawlDoctorResult, type DiscrawlEmbeddingConfigResult, type DiscrawlEmbeddingRuntime, type DiscrawlEmbedInfo, type DiscrawlEmbedResult, type DiscrawlFailure, type DiscrawlFailureReason, type DiscrawlMessage, type DiscrawlMetadataInfo, type DiscrawlMetadataResult, type DiscrawlOptions, type DiscrawlSearchHit, type DiscrawlSearchMode, type DiscrawlSearchOptions, type DiscrawlSearchResult, type DiscrawlStatusInfo, type DiscrawlStatusResult, type DiscrawlSyncInfo, type DiscrawlSyncResult, ENGLISH_ONLY_EMBEDDING_MODELS, } from "./types.js";

package/dist/datasource/skills/discrawl/skill.d.ts

@@ -5,7 +5,8 @@ import type { DiscrawlDoctorResult, DiscrawlEmbedResult, DiscrawlSearchMode, Dis
 export interface DiscrawlSkillClient extends DiscrawlSearchClient {
     doctor(): Promise<DiscrawlDoctorResult>;
     sync(): Promise<DiscrawlSyncResult>;
-    embed(limit?: number): Promise<DiscrawlEmbedResult>;
+    embed(limit?: number, rebuild?: boolean): Promise<DiscrawlEmbedResult>;
+    prepareEmbeddings?(): Promise<boolean>;
 }
 export interface DiscrawlSkillOptions {
     readonly client: DiscrawlSkillClient;

package/dist/datasource/skills/discrawl/types.d.ts

@@ -8,22 +8,6 @@ import type { RetrievalOptions } from "../../../retrieval/types.js";
  *                semantic is unavailable.
  */
 export type DiscrawlSearchMode = "fts" | "semantic" | "hybrid";
-/**
- * Where the `discrawl` CLI reads Discord data from.
- *
- * - `wiretap`  — the local Discord Desktop cache. Requires no token and issues
- *                no Discord API calls; it reads only files Discord already
- *                wrote to disk. Includes classifiable direct messages.
- * - `discord`  — the Discord bot API using a server-configured bot token. This
- *                is the ToS-sanctioned automation path (a bot token identifies
- *                an OAuth2 application, not a human user).
- * - `both`     — bot API plus desktop cache.
- *
- * AutoRAG never uses a Discord *user* token: automating a user account is
- * prohibited by Discord's Community Guidelines and can get the account
- * terminated.
- */
-export type DiscrawlSourceKind = "wiretap" | "discord" | "both";
 /**
  * Embedding models known to be English-only. Selecting one for a non-English
  * archive silently degrades semantic search to noise rather than failing, so
@@ -49,7 +33,31 @@ export declare const DEFAULT_DISCRAWL_EMBEDDING_PROVIDER = "ollama";
  * Configuration for the discrawl client. All fields optional; defaults mirror
  * the katok client. The client spawns the `discrawl` binary as a child process
  * — it never opens the Discord archive database directly.
+ *
+ * AutoRAG drives discrawl's local archive only: `wiretap` to import the
+ * Discord Desktop cache plus search/embed against that native store. The bot
+ * API path belongs to the CLI, which owns its own credential, so no Discord
+ * token is configured, required, or forwarded here.
  */
+export interface DiscrawlEmbeddingRuntime {
+    readonly provider: string;
+    readonly model: string;
+    readonly baseUrl: string;
+    readonly dimensions: number;
+    readonly identity?: string;
+}
+export interface DiscrawlEmbeddingConfigResult {
+    readonly configured: boolean;
+    readonly rebuildRequired: boolean;
+    readonly diagnostic?: string;
+}
+export interface DiscrawlMetadataInfo {
+    readonly embeddingProvider?: string;
+    readonly embeddingModel?: string;
+    readonly embeddingDimensions?: number;
+    readonly embeddingIdentity?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
 export interface DiscrawlOptions {
     /** Explicit path to the `discrawl` binary. Defaults to a bare PATH lookup. */
     readonly binaryPath?: string;
@@ -57,8 +65,6 @@ export interface DiscrawlOptions {
     readonly timeoutMs?: number;
     /** Max stdout/stderr bytes retained. Default 1_048_576 (1 MiB). */
     readonly maxBufferBytes?: number;
-    /** Archive source for the CLI. Default `wiretap` (no token required). */
-    readonly source?: DiscrawlSourceKind;
     /**
      * Explicit operator-owned discrawl config file passed as `--config`.
      * AutoRAG never rewrites an explicit config.
@@ -68,10 +74,12 @@ export interface DiscrawlOptions {
     readonly root?: string;
     /** Explicit workspace directory overriding the computed default. */
     readonly workspacePath?: string;
-    /** Restrict search and sync to one guild id. */
+    /** Restrict search to one guild id. */
     readonly guildId?: string;
     /** Embedding provider understood by the native discrawl configuration. */
     readonly embeddingProvider?: string;
+    /** AutoRAG-owned runtime to write into a managed workspace config. */
+    readonly embeddingRuntime?: DiscrawlEmbeddingRuntime;
     /**
      * Embedding model understood by the native discrawl configuration.
      * English-only models are accepted but reported through a diagnostic.
@@ -91,7 +99,6 @@ export interface DiscrawlOptions {
 export declare const DEFAULT_DISCRAWL_BINARY = "discrawl";
 export declare const DEFAULT_DISCRAWL_TIMEOUT_MS = 30000;
 export declare const DEFAULT_DISCRAWL_MAX_BUFFER_BYTES = 1048576;
-export declare const DEFAULT_DISCRAWL_SOURCE: DiscrawlSourceKind;
 export declare const DEFAULT_DISCRAWL_MODE: DiscrawlSearchMode;
 /**
  * Reasons a discrawl CLI invocation can fail. The client never throws for
@@ -147,7 +154,7 @@ export interface DiscrawlDoctorInfo {
     readonly embeddingProvider?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-/** Result of `discrawl sync` / `discrawl wiretap`. */
+/** Result of `discrawl wiretap`. */
 export interface DiscrawlSyncInfo {
     readonly messages: number;
     readonly guilds?: number;
@@ -184,6 +191,7 @@ export interface DiscrawlSearchOk {
 }
 export type DiscrawlDoctorResult = DiscrawlOk<DiscrawlDoctorInfo> | DiscrawlFailure;
 export type DiscrawlStatusResult = DiscrawlOk<DiscrawlStatusInfo> | DiscrawlFailure;
+export type DiscrawlMetadataResult = DiscrawlOk<DiscrawlMetadataInfo> | DiscrawlFailure;
 export type DiscrawlSyncResult = DiscrawlOk<DiscrawlSyncInfo> | DiscrawlFailure;
 export type DiscrawlEmbedResult = DiscrawlOk<DiscrawlEmbedInfo> | DiscrawlFailure;
 export type DiscrawlSearchResult = DiscrawlSearchOk | DiscrawlFailure;

package/dist/datasource/skills/factory.d.ts

@@ -8,6 +8,7 @@
  * and reported so setup surfaces actionable (but path-opaque) feedback.
  */
 import type { DatasourceSkill } from "../types.js";
+import { type DiscrawlEmbeddingRuntime } from "./discrawl/index.js";
 /** One configured datasource entry (the trusted `datasources.<name>` value). */
 export interface DatasourceSkillConfig {
     readonly enabled?: boolean;
@@ -41,4 +42,4 @@ export declare const BUILTIN_DATASOURCE_SKILL_NAMES: readonly string[];
  * collected in `unknown` (never thrown) so callers can surface setup
  * feedback without failing agent construction.
  */
-export declare function buildDatasourceSkills(config: DatasourcesConfig | undefined, workspaceRoot?: string): BuildDatasourceSkillsResult;
+export declare function buildDatasourceSkills(config: DatasourcesConfig | undefined, workspaceRoot?: string, embeddingRuntime?: DiscrawlEmbeddingRuntime): BuildDatasourceSkillsResult;

package/dist/datasource/skills/katok/client.d.ts

@@ -2,12 +2,9 @@ import type { KatokChunkResult, KatokContextResult, KatokDoctorResult, KatokInde
 /**
  * Thin external `katok` CLI wrapper. Every method spawns the `katok` binary as
  * a child process, parses JSON from stdout, and returns a discriminated ok/fail
- * union. No method throws for expected failures (missing binary, rejected
- * remote-embedding config, CLI nonzero exit, timeout, oversized output, or
- * invalid JSON). The client never opens the KakaoTalk database directly.
- *
- * Remote-embedding configuration is rejected before spawn, case-insensitively,
- * so the spawned process can never egress embeddings to a remote endpoint.
+ * union. No method throws for expected failures (missing binary, CLI nonzero
+ * exit, timeout, oversized output, or invalid JSON). The client never opens the
+ * KakaoTalk database directly.
  */
 export declare class KatokClient {
     private readonly options;
@@ -19,6 +16,6 @@ export declare class KatokClient {
     chunkGet(chunkId: string, signal?: AbortSignal): Promise<KatokChunkResult>;
     context(chunkId: string, signal?: AbortSignal): Promise<KatokContextResult>;
     parent(chunkId: string, signal?: AbortSignal): Promise<KatokParentResult>;
-    /** Single retrieval pipeline: build env, gate remote embeddings, spawn, parse-free raw result. */
+    /** Single retrieval pipeline: build env, spawn, parse-free raw result. */
     private run;
 }

package/dist/datasource/skills/katok/types.d.ts

@@ -39,7 +39,7 @@ export declare const DEFAULT_KATOK_OPTIONS: {
  * every method returns a discriminated union with `ok: false` and one of these
  * reasons.
  */
-export type KatokFailureReason = "binary-missing" | "remote-embedding-rejected" | "nonzero-exit" | "spawn-error" | "timeout" | "aborted" | "stdout-too-large" | "stderr-too-large" | "invalid-json" | "invalid-shape";
+export type KatokFailureReason = "binary-missing" | "nonzero-exit" | "spawn-error" | "timeout" | "aborted" | "stdout-too-large" | "stderr-too-large" | "invalid-json" | "invalid-shape";
 /** Common failure payload shared by every method result union. */
 export interface KatokFailure {
     readonly ok: false;
@@ -50,11 +50,6 @@ export interface KatokFailure {
     readonly stderr: string;
     /** Exit code, or `null` when the process never exited normally. */
     readonly code: number | null;
-    /**
-     * The offending environment key when `reason === "remote-embedding-rejected"`.
-     * A config key name (never a path, never the key's value).
-     */
-    readonly violatingKey?: string;
     readonly hits?: readonly unknown[];
 }
 /** A single indexed chat chunk returned by the katok CLI. */

package/dist/embedding-runtime/cache.d.ts

@@ -0,0 +1,21 @@
+export { CacheError } from "./types.js";
+export interface CacheAsset {
+    readonly id: string;
+    readonly url: string;
+    readonly filename: string;
+    readonly sha256: string;
+    readonly kind?: "model" | "runtime";
+    readonly archiveMembers?: readonly string[];
+}
+export declare function cacheDirectory(kind: "models" | "runtime", cacheRoot?: string): string;
+export interface CacheOptions {
+    readonly cacheRoot?: string;
+    readonly offline?: boolean;
+    readonly fetch?: typeof globalThis.fetch;
+    /** Total budget (ms) for a single asset download. Defaults to 10 minutes so large models can transfer. */
+    readonly downloadTimeoutMs?: number;
+}
+export declare function verifyCacheEntry(path: string, expectedSha256: string): Promise<string>;
+export declare function hasVerifiedAsset(asset: CacheAsset, cacheRoot?: string): Promise<boolean>;
+export declare function downloadAsset(asset: CacheAsset, options?: CacheOptions): Promise<string>;
+export declare function importAsset(sourcePath: string, asset: CacheAsset, options?: CacheOptions): Promise<string>;

package/dist/embedding-runtime/gateway.d.ts

@@ -0,0 +1,27 @@
+import type { RuntimeProfile } from "./types.js";
+export type GatewayErrorCode = "non-loopback-host" | "non-loopback-upstream" | "bad-request" | "batch-limit" | "upstream" | "upstream-violation" | "timeout";
+export declare class GatewayError extends Error {
+    readonly code: GatewayErrorCode;
+    readonly status: number;
+    constructor(code: GatewayErrorCode, message: string, status?: number, options?: {
+        readonly cause?: unknown;
+    });
+}
+export interface StartEmbeddingGatewayOptions {
+    readonly profile: RuntimeProfile;
+    readonly host?: string;
+    readonly port?: number;
+    readonly upstreamUrl: string;
+    readonly fetch?: typeof fetch;
+    readonly maxInputs?: number;
+    readonly maxCharacters?: number;
+    readonly timeoutMs?: number;
+}
+export interface EmbeddingGateway {
+    readonly host: string;
+    readonly port: number;
+    readonly url: string;
+    close(): Promise<void>;
+}
+export declare function isLoopbackHost(host: string): boolean;
+export declare function startEmbeddingGateway(options: StartEmbeddingGatewayOptions): Promise<EmbeddingGateway>;

package/dist/embedding-runtime/index.d.ts

@@ -0,0 +1,120 @@
+import { type CacheOptions } from "./cache.js";
+import { startEmbeddingGateway } from "./gateway.js";
+import { type SupervisorStatus } from "./supervisor.js";
+import type { BackendKind, HealthStatus, ProfileId, RuntimeProfile } from "./types.js";
+export interface EmbeddingRuntimeCache {
+    downloadAsset(asset: {
+        id: string;
+        url: string;
+        filename: string;
+        sha256: string;
+        kind?: "model" | "runtime";
+        archiveMembers?: readonly string[];
+    }, options?: CacheOptions): Promise<string>;
+    importAsset(sourcePath: string, asset: {
+        id: string;
+        url: string;
+        filename: string;
+        sha256: string;
+        kind?: "model" | "runtime";
+        archiveMembers?: readonly string[];
+    }, options?: CacheOptions): Promise<string>;
+    verifyCacheEntry(path: string, expectedSha256: string): Promise<string>;
+    hasVerifiedAsset?(asset: {
+        id: string;
+        url: string;
+        filename: string;
+        sha256: string;
+        kind?: "model" | "runtime";
+        archiveMembers?: readonly string[];
+    }, cacheRoot?: string): Promise<boolean>;
+}
+export interface EmbeddingRuntimeSupervisor {
+    ensureRunning(): Promise<SupervisorStatus>;
+    shutdown(): Promise<void>;
+    status(): SupervisorStatus;
+}
+export interface EmbeddingRuntimeGateway {
+    readonly url: string;
+    close(): Promise<void>;
+}
+export interface EmbeddingRuntimeOptions {
+    cacheRoot?: string;
+    backend?: BackendKind;
+    offline?: boolean;
+    platform?: "darwin-arm64-metal" | "win-x64-cpu" | "win-x64-vulkan";
+    fetch?: typeof fetch;
+    supervisor?: EmbeddingRuntimeSupervisor;
+    cache?: EmbeddingRuntimeCache;
+    gatewayFactory?: (options: Parameters<typeof startEmbeddingGateway>[0]) => Promise<EmbeddingRuntimeGateway>;
+}
+export interface EnsureRuntimeOptions extends EmbeddingRuntimeOptions {
+    profileId?: ProfileId;
+    /** Refuse downloads; used by MinSync refresh/query paths. */
+    cachedOnly?: boolean;
+}
+export interface RuntimeIdentity {
+    readonly profileId: ProfileId;
+    readonly provider: string;
+    readonly model: string;
+    readonly dimension: number;
+    readonly runtimeBuild: string;
+    readonly modelRevision: string;
+    readonly artifactSha256: string;
+}
+export interface EnsuredRuntime {
+    readonly baseUrl: string;
+    readonly profile: RuntimeProfile;
+    readonly identity: RuntimeIdentity;
+    readonly supervisor: SupervisorStatus;
+}
+export interface RuntimeStatus {
+    readonly state: SupervisorStatus["state"];
+    readonly backend: BackendKind;
+    readonly model: string;
+    readonly pid?: number;
+    readonly port?: number;
+    readonly uptimeMs?: number;
+    readonly lastError?: string;
+    readonly profileId?: ProfileId;
+    readonly baseUrl?: string;
+    readonly health: HealthStatus;
+}
+export declare function createEmbeddingRuntime(options?: EmbeddingRuntimeOptions): {
+    resolveRuntimeProfile: (profileId?: ProfileId) => RuntimeProfile;
+    ensureRuntime: (input?: EnsureRuntimeOptions) => Promise<EnsuredRuntime>;
+    releaseRuntimeHandles: () => Promise<void>;
+    stopRuntime: () => Promise<void>;
+    runtimeStatus: () => Promise<RuntimeStatus>;
+    prefetchModel: (profileId?: ProfileId) => Promise<{
+        profileId: ProfileId;
+        path: string;
+    }>;
+    importModel: (profileId: ProfileId | undefined, sourcePath: string) => Promise<{
+        profileId: ProfileId;
+        path: string;
+    }>;
+    verifyModel: (profileId?: ProfileId) => Promise<{
+        profileId: ProfileId;
+        path: string;
+        hash: string;
+    }>;
+};
+export declare const resolveRuntimeProfile: (profileId?: ProfileId) => RuntimeProfile;
+export declare const ensureRuntime: (input?: EnsureRuntimeOptions) => Promise<EnsuredRuntime>;
+export declare const releaseRuntimeHandles: () => Promise<void>;
+export declare const stopRuntime: () => Promise<void>;
+export declare const runtimeStatus: () => Promise<RuntimeStatus>;
+export declare const prefetchModel: (profileId?: ProfileId) => Promise<{
+    profileId: ProfileId;
+    path: string;
+}>;
+export declare const importModel: (profileId: ProfileId | undefined, sourcePath: string) => Promise<{
+    profileId: ProfileId;
+    path: string;
+}>;
+export declare const verifyModel: (profileId?: ProfileId) => Promise<{
+    profileId: ProfileId;
+    path: string;
+    hash: string;
+}>;

package/dist/embedding-runtime/manifest.d.ts

@@ -0,0 +1,24 @@
+import type { BackendKind, PlatformId, ProfileId, RuntimeAsset, RuntimeProfile } from "./types.js";
+export declare function resolveProfile(profileId: ProfileId): RuntimeProfile;
+export declare function platformRuntimeAsset(platform: PlatformId): RuntimeAsset;
+export declare function selectPlatformAsset(platform: PlatformId, backend: BackendKind, vulkanAvailable?: boolean): RuntimeAsset;
+export declare const MODEL_ASSETS: {
+    readonly qwen3: {
+        readonly url: "https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF/resolve/370f27d7550e0def9b39c1f16d3fbaa13aa67728/Qwen3-Embedding-0.6B-Q8_0.gguf";
+        readonly revision: "370f27d7550e0def9b39c1f16d3fbaa13aa67728";
+        readonly sha256: "06507c7b42688469c4e7298b0a1e16deff06caf291cf0a5b278c308249c3e439";
+        readonly license: "Apache-2.0";
+        readonly noticeReference: "Qwen3 model card and Apache-2.0 license";
+    };
+    readonly embeddinggemma: {
+        readonly url: "https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF/resolve/0f741b5a6585bd53aeb15cd1372c56f2a0f65e12/embeddinggemma-300M-Q8_0.gguf";
+        readonly revision: "0f741b5a6585bd53aeb15cd1372c56f2a0f65e12";
+        readonly sha256: "b5ce9d77a3fc4b3b39ccb5643c36777911cc4eb46a66962eadfa3f5f60490d63";
+        readonly license: "Gemma Terms of Use";
+        readonly noticeReference: "Google EmbeddingGemma model card and Gemma Terms of Use";
+    };
+};
+export declare const MODEL_ASSET_URLS: {
+    readonly qwen3: "https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF/resolve/370f27d7550e0def9b39c1f16d3fbaa13aa67728/Qwen3-Embedding-0.6B-Q8_0.gguf";
+    readonly embeddinggemma: "https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF/resolve/0f741b5a6585bd53aeb15cd1372c56f2a0f65e12/embeddinggemma-300M-Q8_0.gguf";
+};

package/dist/embedding-runtime/supervisor.d.ts

@@ -0,0 +1,74 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import type { BackendKind, ProfileId } from "./types.js";
+export type SupervisorState = "stopped" | "starting" | "ready" | "failed" | "stopping";
+export interface SupervisorStatus {
+    readonly state: SupervisorState;
+    readonly pid?: number;
+    readonly port?: number;
+    readonly backend: BackendKind;
+    readonly model: string;
+    readonly uptimeMs?: number;
+    readonly lastError?: string;
+}
+export declare class SupervisorError extends Error {
+    readonly code: "lock-conflict" | "readiness-timeout" | "spawn" | "exited" | "shutdown" | "missing-executable";
+    constructor(code: SupervisorError["code"], message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+type SpawnLike = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+type KillLike = (pid: number, signal?: NodeJS.Signals | number) => void;
+export interface SupervisorOptions {
+    readonly cacheRoot?: string;
+    readonly profileId?: ProfileId;
+    readonly backend?: BackendKind;
+    readonly executablePath?: string;
+    readonly modelPath?: string;
+    readonly readinessTimeoutMs?: number;
+    readonly readinessIntervalMs?: number;
+    readonly logMaxBytes?: number;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly spawn?: SpawnLike;
+    readonly kill?: KillLike;
+    readonly platform?: NodeJS.Platform;
+}
+export declare const DEFAULT_READINESS_TIMEOUT_MS = 60000;
+export declare class EmbeddingRuntimeSupervisor {
+    private readonly root;
+    private readonly backend;
+    private readonly executablePath;
+    private readonly modelPath;
+    private readonly timeoutMs;
+    private readonly intervalMs;
+    private readonly logMaxBytes;
+    private readonly spawnProcess;
+    private readonly killProcess;
+    private readonly fetchHealth;
+    private readonly osPlatform;
+    private readonly defaultExecutable;
+    private child?;
+    private adoptedPid?;
+    private startedAt?;
+    private currentPort?;
+    private state;
+    private lastError?;
+    private restartCount;
+    private shutdownRequested;
+    private stopping?;
+    constructor(options?: SupervisorOptions);
+    ensureRunning(): Promise<SupervisorStatus>;
+    status(): SupervisorStatus;
+    shutdown(): Promise<void>;
+    private adoptExistingRuntime;
+    private acquireLock;
+    private resolveExecutable;
+    private startChild;
+    private recoverUnexpectedExit;
+    private waitUntilReady;
+    private stopAdopted;
+    private stopChild;
+    private cleanupState;
+    private appendLog;
+    private readLog;
+}
+export {};

package/dist/embedding-runtime/types.d.ts

@@ -0,0 +1,66 @@
+export type BackendKind = "auto" | "cpu" | "vulkan";
+export type PlatformId = "darwin-arm64-metal" | "win-x64-cpu" | "win-x64-vulkan";
+export type ProfileId = "qwen3-embedding-0.6b" | "embeddinggemma-300m";
+export interface ProtocolCapabilities {
+    readonly healthz: boolean;
+    readonly embed: boolean;
+    readonly openaiCompatible: boolean;
+    readonly ollamaCompatible: boolean;
+}
+export interface RuntimeProfile {
+    readonly profileId: ProfileId;
+    readonly provider: string;
+    readonly model: string;
+    readonly dimension: number;
+    readonly queryPrefix: string;
+    readonly passagePrefix: string;
+    readonly runtimeBuild: string;
+    readonly modelRevision: string;
+    readonly artifactSha256: string;
+    readonly backend: BackendKind;
+    readonly protocolCapabilities: ProtocolCapabilities;
+}
+export interface HealthResult {
+    readonly ok: true;
+    readonly profileId: ProfileId;
+    readonly dimension: number;
+    readonly runtimeBuild: string;
+}
+export interface HealthFailure {
+    readonly ok: false;
+    readonly code: "unavailable" | "starting" | "incompatible" | "failed";
+    readonly message: string;
+    readonly retryable: boolean;
+}
+export type HealthStatus = HealthResult | HealthFailure;
+export interface FailureResult {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+export declare class CacheError extends Error {
+    readonly code: "invalid-hash" | "offline-missing" | "download" | "hash-mismatch" | "io" | "extraction" | "missing-member";
+    readonly path?: string;
+    constructor(code: CacheError["code"], message: string, options?: {
+        readonly path?: string;
+        readonly cause?: unknown;
+    });
+}
+export interface ModelAsset {
+    readonly url: string;
+    readonly revision: string;
+    readonly sha256: string;
+    readonly license: string;
+    readonly noticeReference: string;
+}
+export interface RuntimeAsset {
+    readonly id: string;
+    readonly url: string;
+    readonly filename: string;
+    readonly sha256: string;
+    readonly version: string;
+    readonly platform: PlatformId;
+    readonly archiveMembers: readonly string[];
+    readonly kind: "runtime";
+}

package/dist/filesystem/source-paths.d.ts

@@ -14,13 +14,44 @@ export interface ResolvedVirtualSource {
     readonly realPath: string;
     readonly sourceId: string;
 }
+/**
+ * True when `source` is an absolute filesystem path on any supported OS
+ * (POSIX `/...`, Windows drive `C:\` or `C:/`, or UNC `\\...`).
+ * Platform-independent so peer wire ids behave identically on macOS, Linux,
+ * and Windows servers.
+ */
+export declare function isFilesystemAbsolutePath(source: string): boolean;
 /**
  * Normalize an opaque virtual source id. Returns the normalized id, or
  * `undefined` when the input is syntactically invalid or unsafe (no leading
- * slash, URL scheme, fragment/query, traversal, NUL, backslash). Never throws
- * and never returns a real path — failures are signaled as `undefined`.
+ * slash, URL scheme, traversal, NUL, backslash). Never throws and never
+ * returns a real path — failures are signaled as `undefined`.
+ *
+ * `#` and `?` are NOT rejected: they are ordinary characters in a real file
+ * name, and ids are derived verbatim from real file names. URL-shaped input
+ * is already rejected by the scheme check above.
  */
 export declare function normalizeVirtualPath(virtual: string | undefined | null): string | undefined;
+/**
+ * Canonicalize any retrieval source form to the canonical virtual source id:
+ *
+ * 1. An id already inside a configured root's virtual namespace is validated
+ *    and returned unchanged (modulo separator cleanup).
+ * 2. An OS-absolute real path contained in a configured source root becomes
+ *    that root's virtual id (`/<prefix>/<relative>`); the longest containing
+ *    root wins for nested roots.
+ * 3. A datasource slash identity (`/kakao/<instance>/chunks/<chunk>`) is a
+ *    virtual id in a non-filesystem namespace and passes through validation.
+ * 4. An absolute filesystem path outside every root passes through as its
+ *    own canonical form — backslashes are converted to forward slashes so
+ *    Windows drive/UNC paths canonicalize identically on every host — letting
+ *    operators write policy globs against real absolute paths.
+ *
+ * Everything else fails closed as `undefined`: traversal segments, URL
+ * schemes (including the retired `kakao:<chat>` colon scheme), backslashes in
+ * non-absolute sources, and empty input.
+ */
+export declare function normalizeSource(source: string, sourceRoots: readonly SourceRoot[]): string | undefined;
 /**
  * Exact-prefix boundary match: `/docs` matches `/docs` and `/docs/...` but NOT
  * `/docs-2`. Prevents prefix confusion between sibling roots like `/docs` and