@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/knowledge/install.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Private-tier catalog install (docs/knowledge-catalogs.md install sequence):
+ * resolve source → disk preflight → resumable download (`.partial` stays on
+ * kill or cancel; the next attempt resumes) → archive sha256 = the ref's
+ * contentDigest → identity check against the catalog entry → verified staged
+ * extract (every file hashed against the manifest) → open + count validation
+ * in staging → atomic sibling-rename publish → registry pointer. Yields
+ * install events; the manager's job registry consumes them and prunes older
+ * versions after unmounting the catalog's SQLite handles.
+ */
+import type { KnowledgeCatalogRef, KnowledgeInstallEvent, KnowledgeInstallSourceKind } from '@bendyline/gezel';
+import { type CatalogValidationReport } from '@bendyline/gezel-knowledge';
+import type { KnowledgeRegistry } from './registry.js';
+export type { KnowledgeInstallEvent } from '@bendyline/gezel';
+export type KnowledgeInstallSource = {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'url';
+    url: string;
+    expectedSha256?: string;
+};
+/** The identity a catalog entry pins; the archive must agree before it is installed. */
+export interface KnowledgeExpectedIdentity {
+    publisherId: string;
+    catalogId: string;
+    version: string;
+}
+export interface KnowledgeInstallOptions {
+    home: string;
+    source: KnowledgeInstallSource;
+    /** Recorded on the registry entry (default: the source kind). */
+    origin?: KnowledgeInstallSourceKind;
+    /** The pinned archive size: the download's byte cap and the disk preflight. */
+    archiveBytes?: number;
+    expectedIdentity?: KnowledgeExpectedIdentity;
+    registry: KnowledgeRegistry;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    /** Production supplies the worker-backed validator so untrusted SQLite is
+     * never opened on the daemon event-loop thread. */
+    validateCatalog?: (rootDir: string, deep: boolean) => Promise<CatalogValidationReport>;
+}
+export declare const KNOWLEDGE_DOWNLOAD_KEY_PATTERN: RegExp;
+/**
+ * The download's temp-file stem. A pinned digest keys the file by content, so
+ * an interrupted catalog download resumes across jobs, restarts, and any
+ * later entry that pins the same bytes; an unpinned URL keys by the URL.
+ */
+export declare function knowledgeDownloadKey(source: Extract<KnowledgeInstallSource, {
+    kind: 'url';
+}>): string;
+export declare function installKnowledgeCatalog(opts: KnowledgeInstallOptions): AsyncGenerator<KnowledgeInstallEvent, void>;
+/** Remove every private version except the active ref after its host has been unmounted. */
+export declare function pruneOtherKnowledgeCatalogVersions(home: string, ref: KnowledgeCatalogRef): Promise<void>;

package/dist/knowledge/install.js

@@ -0,0 +1,274 @@
+/**
+ * Private-tier catalog install (docs/knowledge-catalogs.md install sequence):
+ * resolve source → disk preflight → resumable download (`.partial` stays on
+ * kill or cancel; the next attempt resumes) → archive sha256 = the ref's
+ * contentDigest → identity check against the catalog entry → verified staged
+ * extract (every file hashed against the manifest) → open + count validation
+ * in staging → atomic sibling-rename publish → registry pointer. Yields
+ * install events; the manager's job registry consumes them and prunes older
+ * versions after unmounting the catalog's SQLite handles.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, readdir, rename, rm, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { createLogger } from '@bendyline/gezel';
+import { GEZK_ARCHIVE_LIMITS, extractGezkVerified, inspectGezkArchive, validateExtractedCatalog, } from '@bendyline/gezel-knowledge';
+import { knowledgeCatalogVersionDir, knowledgeCatalogsDir, knowledgeDownloadsDir, } from '@bendyline/gezel/paths';
+import { isPathInside, realpathContained } from '../fs/safe-paths.js';
+import { checkDiskSpace, describeDiskShortfall } from '../utils/disk-space.js';
+import { downloadWithRetry } from '../utils/download-with-retry.js';
+const log = createLogger('knowledge');
+const MAX_GEZK_ARCHIVE_BYTES = GEZK_ARCHIVE_LIMITS.maxTotalBytes + 512 * 1024 * 1024;
+export const KNOWLEDGE_DOWNLOAD_KEY_PATTERN = /^[0-9a-f]{16}$/;
+/**
+ * The download's temp-file stem. A pinned digest keys the file by content, so
+ * an interrupted catalog download resumes across jobs, restarts, and any
+ * later entry that pins the same bytes; an unpinned URL keys by the URL.
+ */
+export function knowledgeDownloadKey(source) {
+    if (source.expectedSha256)
+        return source.expectedSha256.toLowerCase().slice(0, 16);
+    return createHash('sha256').update(source.url, 'utf8').digest('hex').slice(0, 16);
+}
+export async function* installKnowledgeCatalog(opts) {
+    let archivePath;
+    let archiveSha = null;
+    let downloadedTemp = false;
+    const origin = opts.origin ?? opts.source.kind;
+    if (opts.source.kind === 'file') {
+        archivePath = resolve(opts.source.path);
+        try {
+            await stat(archivePath);
+        }
+        catch {
+            yield { type: 'error', error: `no such file: ${archivePath}` };
+            return;
+        }
+    }
+    else {
+        const downloads = knowledgeDownloadsDir(opts.home);
+        await mkdir(downloads, { recursive: true });
+        archivePath = join(downloads, `${knowledgeDownloadKey(opts.source)}.gezk`);
+        downloadedTemp = true;
+        const disk = await checkDiskSpace(downloads, opts.archiveBytes ?? 0);
+        if (!disk.ok) {
+            yield { type: 'error', error: describeDiskShortfall(disk, 'the catalog download') };
+            return;
+        }
+        const download = downloadWithRetry({
+            url: opts.source.url,
+            destPath: archivePath,
+            approxSizeBytes: opts.archiveBytes ?? 0,
+            ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            maxBytes: opts.archiveBytes ?? MAX_GEZK_ARCHIVE_BYTES,
+        });
+        let final = null;
+        try {
+            while (true) {
+                const step = await download.next();
+                if (step.done) {
+                    const value = step.value;
+                    if (value.kind === 'aborted')
+                        return; // .partial stays for resume
+                    if (value.kind !== 'ok') {
+                        yield { type: 'error', error: value.error };
+                        return;
+                    }
+                    final = value;
+                    break;
+                }
+                if (step.value.type === 'progress') {
+                    yield {
+                        type: 'progress',
+                        phase: 'download',
+                        bytesDone: step.value.bytesWritten,
+                        bytesTotal: step.value.totalBytes,
+                    };
+                }
+                else {
+                    yield {
+                        type: 'retrying',
+                        attempt: step.value.attempt,
+                        maxAttempts: step.value.maxAttempts,
+                        delayMs: step.value.delayMs,
+                        reason: step.value.reason,
+                    };
+                }
+            }
+        }
+        finally {
+            // Closing this generator early (a cancel) must unwind the download
+            // too, or its socket and file handle outlive the job.
+            await download.return(undefined).catch(() => { });
+        }
+        // Rename .partial into place; sha comes inline only on a fresh full
+        // transfer — resumed downloads are re-hashed below like local files.
+        await rm(archivePath, { force: true });
+        await rename(`${archivePath}.partial`, archivePath);
+        archiveSha = final?.sha256 ?? null;
+    }
+    try {
+        yield { type: 'verifying' };
+        if (!archiveSha)
+            archiveSha = await hashFile(archivePath);
+        if (opts.source.kind === 'url' && opts.source.expectedSha256) {
+            const expected = opts.source.expectedSha256.toLowerCase();
+            if (archiveSha !== expected) {
+                yield {
+                    type: 'error',
+                    error: `archive sha256 mismatch: expected ${expected}, got ${archiveSha}`,
+                    mismatch: { expected, actual: archiveSha },
+                };
+                return;
+            }
+        }
+        const inspection = await inspectGezkArchive(archivePath);
+        const manifest = inspection.manifest;
+        if (opts.expectedIdentity) {
+            const pinned = opts.expectedIdentity;
+            if (manifest.publisher.id !== pinned.publisherId ||
+                manifest.id !== pinned.catalogId ||
+                manifest.version !== pinned.version) {
+                yield {
+                    type: 'error',
+                    error: `catalog identity mismatch: the catalog entry pins ${pinned.publisherId}/${pinned.catalogId}@${pinned.version}, the archive is ${manifest.publisher.id}/${manifest.id}@${manifest.version}`,
+                };
+                return;
+            }
+        }
+        const ref = {
+            publisherId: manifest.publisher.id,
+            catalogId: manifest.id,
+            version: manifest.version,
+            contentDigest: archiveSha,
+            storageScope: 'user',
+        };
+        const targetDir = knowledgeCatalogVersionDir(opts.home, ref.publisherId, ref.catalogId, ref.version, ref.contentDigest);
+        const catalogsRoot = knowledgeCatalogsDir(opts.home);
+        await mkdir(catalogsRoot, { recursive: true });
+        await assertKnowledgePathContained(catalogsRoot, targetDir);
+        const existing = await stat(join(targetDir, 'manifest.json')).catch(() => null);
+        if (existing) {
+            // Bytes already on disk — just (re)point the registry.
+            opts.registry.upsert(ref, { enabled: true, source: origin });
+            yield { type: 'done', ref, rootDir: targetDir, storageScope: 'user' };
+            return;
+        }
+        const disk = await checkDiskSpace(dirname(targetDir), inspection.totalUncompressedBytes);
+        if (!disk.ok) {
+            yield { type: 'error', error: describeDiskShortfall(disk, 'the catalog install') };
+            return;
+        }
+        // Staged extract as a SIBLING of the final dir: same volume, so the
+        // publish rename is atomic; the suffix keeps concurrent installs apart.
+        const staging = `${targetDir}.staging-${process.pid}-${randomUUID()}`;
+        try {
+            await mkdir(dirname(targetDir), { recursive: true });
+            await assertKnowledgePathContained(catalogsRoot, targetDir);
+            yield {
+                type: 'progress',
+                phase: 'extract',
+                bytesDone: 0,
+                bytesTotal: inspection.totalUncompressedBytes,
+            };
+            await extractGezkVerified(archivePath, staging);
+            // Full integrity validation happens before publish. Production injects
+            // the worker-backed host; direct callers use the library validator.
+            yield { type: 'verifying' };
+            const report = opts.validateCatalog
+                ? await opts.validateCatalog(staging, true)
+                : await validateExtractedCatalog(staging, { deep: true });
+            if (!report.ok) {
+                const failed = report.checks.filter((c) => !c.ok);
+                yield {
+                    type: 'error',
+                    error: `catalog failed validation: ${failed.map((c) => `${c.name}${c.detail ? ` (${c.detail})` : ''}`).join('; ')}`,
+                };
+                return;
+            }
+            await assertKnowledgePathContained(catalogsRoot, targetDir);
+            await rm(targetDir, { recursive: true, force: true });
+            await rename(staging, targetDir);
+        }
+        catch (err) {
+            await rm(staging, { recursive: true, force: true }).catch(() => { });
+            throw err;
+        }
+        opts.registry.upsert(ref, { enabled: true, source: origin });
+        yield { type: 'done', ref, rootDir: targetDir, storageScope: 'user' };
+    }
+    catch (err) {
+        yield { type: 'error', error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        if (downloadedTemp)
+            await rm(archivePath, { force: true }).catch(() => { });
+    }
+}
+/** Remove every private version except the active ref after its host has been unmounted. */
+export async function pruneOtherKnowledgeCatalogVersions(home, ref) {
+    const catalogsRoot = knowledgeCatalogsDir(home);
+    const catalogDir = join(catalogsRoot, ref.publisherId, ref.catalogId);
+    await assertKnowledgePathContained(catalogsRoot, catalogDir);
+    const keepVersion = ref.version;
+    const keepDigest = ref.contentDigest.slice(0, 16);
+    let versions;
+    try {
+        versions = await readdir(catalogDir);
+    }
+    catch {
+        return;
+    }
+    for (const version of versions) {
+        if (version === keepVersion) {
+            const digests = await readdir(join(catalogDir, version)).catch(() => []);
+            for (const digest of digests) {
+                if (digest !== keepDigest) {
+                    const target = join(catalogDir, version, digest);
+                    if (await isKnowledgePathContained(catalogsRoot, target)) {
+                        await rm(target, {
+                            recursive: true,
+                            force: true,
+                            maxRetries: 5,
+                            retryDelay: 100,
+                        }).catch(() => { });
+                    }
+                }
+            }
+            continue;
+        }
+        const target = join(catalogDir, version);
+        if (!(await isKnowledgePathContained(catalogsRoot, target))) {
+            log.warn(`refusing to prune catalog path outside the knowledge root: ${target}`);
+            continue;
+        }
+        await rm(target, {
+            recursive: true,
+            force: true,
+            maxRetries: 5,
+            retryDelay: 100,
+        }).catch((err) => {
+            log.warn(`prune of ${ref.catalogId}@${version} failed: ${err}`);
+        });
+    }
+}
+async function isKnowledgePathContained(root, target) {
+    return isPathInside(target, root) && (await realpathContained(root, target));
+}
+async function assertKnowledgePathContained(root, target) {
+    if (!(await isKnowledgePathContained(root, target))) {
+        throw new Error(`refusing a catalog path outside the knowledge root: ${target}`);
+    }
+}
+async function hashFile(path) {
+    const hasher = createHash('sha256');
+    await new Promise((resolveHash, reject) => {
+        const stream = createReadStream(path, { highWaterMark: 16 * 1024 * 1024 });
+        stream.on('data', (chunk) => hasher.update(chunk));
+        stream.on('end', () => resolveHash());
+        stream.on('error', reject);
+    });
+    return hasher.digest('hex');
+}

package/dist/knowledge/manager.d.ts

@@ -0,0 +1,287 @@
+/**
+ * KnowledgeManager — the daemon-side owner of installed `.gezk` catalogs:
+ * registry + mount lifecycle (verify-before-mount → quarantine-with-reason),
+ * background install jobs (a client disconnect never abandons a download),
+ * the gilde join (what is available, what has a newer version), browse APIs
+ * for the routes, and the SearchService knowledge arm. Every SQLite touch
+ * goes through the KnowledgeCatalogHost (worker thread in production); this
+ * class never opens a catalog database itself.
+ */
+import type { GezelConfig, IncompleteKnowledgeDownload, KnowledgeActiveInstall, KnowledgeAvailableCatalog, KnowledgeCatalogRef, KnowledgeCatalogStatus, KnowledgeEmbeddingProfile, KnowledgeInstallEvent, KnowledgeInstallJob, KnowledgeInstallRequest, KnowledgePassageRead, KnowledgeSemanticSearchMode, KnowledgeUpdateCandidate, KnowledgeUri, ProjectKnowledgeCatalogs, UnifiedSearchResult } from '@bendyline/gezel';
+import { type KnowledgeNearbyRequest, type KnowledgeNearbyResponse, type KnowledgeRadius } from '@bendyline/gezel';
+import type { HistoryEvent } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import { type ModelDownloadProgress } from '@bendyline/gezel-knowledge';
+type HistoryManager = {
+    log(event: Omit<HistoryEvent, 'id' | 'at'> & {
+        at?: string;
+        id?: string;
+    }): Promise<void>;
+};
+import { ChatModelInstallRegistry } from '../models/install-registry.js';
+import type { KnowledgeCatalogHost, KnowledgeChunk } from './catalog-host.js';
+import { KnowledgeRegistry } from './registry.js';
+import type { SharedKnowledgeInstaller } from './shared-install-contract.js';
+import { type KnowledgeVectorFloors } from './vector-floors.js';
+export type { KnowledgeCatalogStatus, KnowledgeInstallJob, KnowledgeSemanticSearchMode };
+export type KnowledgeInstallRequestSource = KnowledgeInstallRequest['source'];
+interface MountedInfo {
+    ref: KnowledgeCatalogRef;
+    key: string;
+    rootDir: string;
+    name: string;
+    description?: string;
+    language: string;
+    license: string;
+    documents: number;
+    chunks: number;
+    sizeBytes: number;
+    vectorCompatible: boolean;
+    semanticSearch: KnowledgeSemanticSearchMode;
+    embedding: KnowledgeEmbeddingProfile;
+    /** topic id → display name, from the shipped TOC. */
+    topicNames: Map<string, string>;
+    sourceUrlByDoc: Map<string, string>;
+}
+interface InstallStart {
+    request: KnowledgeInstallRequestSource;
+}
+export interface KnowledgeManagerOptions {
+    home: string;
+    host: KnowledgeCatalogHost;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    /** The gilde loader: `knowledge-catalog` entries are the download source and the update oracle. */
+    catalog?: CatalogService;
+    history?: HistoryManager;
+    /** The security policy (app network) and the auto-update default. */
+    readConfig?: () => Promise<GezelConfig | null>;
+    /** The machine broker's shared store, when a machine engine is adopted. */
+    sharedInstaller?: SharedKnowledgeInstaller;
+    /** Project policy lookup (Store.getProject wrapper); null = no policy. */
+    projectPolicy?: (projectId: string) => Promise<ProjectKnowledgeCatalogs | null>;
+    /** Test seam: embed a query in a catalog profile's space (default: the embed worker). */
+    embedQueryForProfile?: (text: string, profile: KnowledgeEmbeddingProfile, opts?: {
+        onDownloadProgress?: (progress: ModelDownloadProgress) => void;
+        localFilesOnly?: boolean;
+    }) => Promise<number[]>;
+    /** Optional profile-model prewarm ceiling; keyword search remains usable on timeout. */
+    profilePrewarmTimeoutMs?: number;
+    /** Test seam; null turns off the bundled Handboek. */
+    bundledHandboekArchive?: string | null;
+    /** Test seam: per-profile cosine floors (default: the measured table + env override). */
+    vectorFloors?: KnowledgeVectorFloors;
+}
+export declare class KnowledgeManager {
+    private readonly opts;
+    readonly registry: KnowledgeRegistry;
+    private readonly mountedByKey;
+    private readonly installs;
+    /** What each running job was asked to install, for the active-install listing. */
+    private readonly jobRequests;
+    /** Download temp keys of running jobs, so the incomplete listing skips live transfers. */
+    private readonly jobDownloadKeys;
+    private readonly autoUpdateTimers;
+    private jobCounter;
+    private readonly vectorFloors;
+    constructor(opts: KnowledgeManagerOptions);
+    get host(): KnowledgeCatalogHost;
+    /** The job registry, for the SSE subscriber shared with the model install routes. */
+    get installRegistry(): ChatModelInstallRegistry<KnowledgeInstallEvent, InstallStart>;
+    private keyFor;
+    private dirFor;
+    /** Mount every enabled registry entry. Failures quarantine, never throw. */
+    start(): Promise<void>;
+    private ensureBundledHandboek;
+    private mountEntry;
+    /**
+     * Load a catalog's vector bits in the worker now, in the background. The
+     * first semantic search otherwise loads them itself — ~300 ms for a
+     * 200k-chunk shard — inside its 600 ms scope budget, times out, and the
+     * knowledge arm answers nothing, keyword hits included. A failure here
+     * costs only that first search.
+     */
+    private prewarmVectors;
+    stop(): Promise<void>;
+    /**
+     * Every gilde `knowledge-catalog` entry (newest version), keyed by
+     * publisher/id, with the catalog route URL of its Reference Mark artwork.
+     */
+    private gildeEntries;
+    /** Every gilde `knowledge-catalog` manifest (newest version), keyed by publisher/id. */
+    private gildeItems;
+    /** Coordinates present in the machine-shared asset store (public inventory, read-only). */
+    private sharedInventoryKeys;
+    list(): Promise<KnowledgeCatalogStatus[]>;
+    /** Installed catalogs for which the shipped gilde content carries a strictly newer version. */
+    updates(): Promise<KnowledgeUpdateCandidate[]>;
+    /**
+     * Every gilde `knowledge-catalog` entry joined with this user's registry,
+     * the machine-shared inventory, running installs and partial downloads —
+     * what the Knowledge screen's browser renders. Offline-safe: gilde is local.
+     */
+    available(): Promise<KnowledgeAvailableCatalog[]>;
+    /** Resolve a catalogId (URI authority) to its mounted info, or null. */
+    mountedCatalog(catalogId: string): MountedInfo | null;
+    /**
+     * Start an install, or attach to the one already running. A catalog
+     * install's job id is the catalog id, so a second click, the auto-updater
+     * and a reconnecting client all land on the same job.
+     */
+    startInstall(request: KnowledgeInstallRequestSource): {
+        jobId: string;
+        alreadyRunning: boolean;
+    };
+    private planInstall;
+    /**
+     * Ask the machine broker to ensure the coordinate in the shared store,
+     * relaying its progress. Cancelling this job cancels the broker's too:
+     * this daemon asked for the download, so its cancel is the honest signal.
+     */
+    private installShared;
+    /** Bytes a private install of this catalog left behind, once a shared copy replaces it. */
+    private deletePrivateBytes;
+    private runInstall;
+    /** Mount the fresh version, record it, and warm the query embedder before `done`. */
+    private finishInstall;
+    /**
+     * Pull the catalog's query model now, while the user is watching the
+     * install, instead of on the first search. Never an install failure: the
+     * catalog is on disk and keyword search works without the model. The model
+     * can outweigh the catalog — multilingual-e5-small's full-precision graph
+     * is ~470 MB against a 160 MB Wikipedia catalog — so its download reports
+     * bytes the way the catalog's own does.
+     *
+     * Not gated on `allowAppNetwork`: every install is either a person's own
+     * download or an auto-update `checkAutoUpdates` already gated, and skipping
+     * the model here would leave an offline machine without semantic search.
+     */
+    private prewarmProfile;
+    private recordInstallFailure;
+    getJob(jobId: string): KnowledgeInstallJob | null;
+    /** Live events for a job; replays the latest progress (and the terminal event) first. */
+    subscribeJob(jobId: string, listener: (event: KnowledgeInstallEvent) => void): (() => void) | null;
+    cancelJob(jobId: string): boolean;
+    /** Every running install with its latest progress (the polled twin of the SSE). */
+    activeInstalls(): KnowledgeActiveInstall[];
+    private partialDownloadKeys;
+    /**
+     * Partial archives no job is writing. A key that still matches a gilde
+     * pin resumes on the next install of that catalog; anything else can only
+     * be deleted. Largest first: the most disk to reclaim.
+     */
+    listIncompleteDownloads(): Promise<IncompleteKnowledgeDownload[]>;
+    /** Delete a partial download by key. Refuses a key a running job is writing. */
+    deleteIncompleteDownload(key: string): Promise<boolean>;
+    /**
+     * Start installs for catalogs whose registry entry (or the install-wide
+     * `config.knowledge.autoUpdate` default) opted into automatic updates.
+     * Returns the `catalog@version` pairs it started.
+     */
+    checkAutoUpdates(): Promise<string[]>;
+    /** Arm the daily auto-update check (a quiet start, then every 24 h); `stop()` disarms. */
+    startAutoUpdateTimer(): void;
+    private readConfig;
+    private networkAllowed;
+    private logHistory;
+    setEnabled(catalogId: string, enabled: boolean): Promise<boolean>;
+    /**
+     * Adopt a catalog that already exists in the machine-shared asset store:
+     * add this user's ref and mount read-only. The shared bytes belong to the
+     * machine installer — adoption and removal never touch them.
+     */
+    adoptSharedCatalog(coordinate: {
+        publisherId: string;
+        catalogId: string;
+        version: string;
+        expectedDigest: string;
+    }): Promise<boolean>;
+    /** Remove the ref and (for the private tier) delete the bytes. */
+    remove(catalogId: string): Promise<boolean>;
+    private requireMounted;
+    topics(catalogId: string): ReturnType<KnowledgeCatalogHost['topics']>;
+    documentsPage(catalogId: string, opts: {
+        topicId?: string;
+        offset?: number;
+        limit?: number;
+        descendants?: boolean;
+    }): ReturnType<KnowledgeCatalogHost['documentsPage']>;
+    getDocument(catalogId: string, documentId: string): ReturnType<KnowledgeCatalogHost['getDocument']>;
+    /** One passage by its citation id, with the document's title and origin. */
+    getPassage(catalogId: string, documentId: string, chunkUid: string): Promise<KnowledgePassageRead | null>;
+    /**
+     * Resolve a `knowledge://` citation: the catalog (publisher included) is
+     * installed and enabled, the document exists, and a `#chunk=` passage is in
+     * it. A citation is only evidence when it resolves; a model can write a
+     * well-formed URI for a passage that does not exist.
+     */
+    resolveCitation(raw: string): Promise<KnowledgeCitation>;
+    assets(catalogId: string): ReturnType<KnowledgeCatalogHost['assets']>;
+    readAsset(catalogId: string, path: string): ReturnType<KnowledgeCatalogHost['readAsset']>;
+    assetFile(catalogId: string, path: string): ReturnType<KnowledgeCatalogHost['assetFile']>;
+    /** The mounted version of a catalog — what an asset URL binds to for caching. */
+    mountedVersion(catalogId: string): string;
+    /**
+     * Discover subject articles under the active catalog policy. Source replicas
+     * deduplicate before counts and cursor pages, and scope is checked again
+     * before returning the response if catalogs changed during worker scans.
+     */
+    nearby(request: KnowledgeNearbyRequest, projectId?: string): Promise<KnowledgeNearbyResponse>;
+    /**
+     * Search each catalog in its embedding space and fuse lexical/vector ranks.
+     * Spatial eligibility applies inside workers before candidate selection.
+     */
+    searchUnified(query: string, opts: {
+        vector: number[] | null;
+        maxResults: number;
+        projectId?: string;
+        spatial?: KnowledgeRadius;
+        catalogs?: readonly string[];
+        /** Search a profile group keyword-only when its query model is not ready by then. */
+        queryEmbedBudgetMs?: number;
+        /** Query cached profile models only, falling back to keywords when absent. */
+        localModelsOnly?: boolean;
+        /**
+         * Include media rows (images, audio and video windows) as results of
+         * their own. Explicit search asks; proactive injection does not.
+         */
+        media?: boolean;
+    }): Promise<UnifiedSearchResult[]>;
+    /** A document the lexical arms named but no chunk carries: cite it with its lead paragraph. */
+    private toDocumentResult;
+    /** A catalog's vector floor, or null when its hits are keyword-only or its scale unmeasured. */
+    private vectorFloorFor;
+    /**
+     * Load every mounted catalog's own query model now. A search waits for
+     * these only briefly, so a caller that needs the semantic path measured
+     * (the retrieval preview's `warm`) loads them first.
+     */
+    warmQueryModels(): Promise<void>;
+    /**
+     * A profile's query vector, or undefined when its model is unavailable or
+     * not ready within `budgetMs` (that group searches FTS). A load that misses
+     * the budget keeps running — loads are single-flight per profile — so the
+     * next query gets vectors.
+     */
+    private embedForProfile;
+    private toResult;
+    /** Enabled+mounted catalogs, intersected with the project policy. */
+    private activeCatalogKeys;
+}
+export type KnowledgeCitation = {
+    ok: false;
+    reason: 'malformed' | 'catalog-not-installed' | 'no-document' | 'no-passage';
+} | {
+    ok: true;
+    uri: KnowledgeUri;
+    title: string;
+    catalogVersion: string;
+    sourceUrl?: string;
+    /** The cited passage, when the URI names one. */
+    chunk?: KnowledgeChunk;
+    /** The whole document, when the URI names no passage. */
+    markdown?: string;
+};
+export declare class KnowledgeNotFoundError extends Error {
+    constructor(message: string);
+}