@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/inference-service.js

@@ -0,0 +1,275 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { join } from 'node:path';
+import { GEZEL_API_GENERATION, GEZEL_API_GENERATION_FLOOR, GEZEL_VERSION, GezelConfigSchema, createLogger, nowIso, startSuspendMonitor, stopSuspendMonitor, } from '@bendyline/gezel';
+import { BundledSource, CatalogService } from '@bendyline/gezel-catalog';
+import { discoverNativeBinaries } from '@bendyline/gezel/native';
+import { gezelHome } from '@bendyline/gezel/paths';
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { ZodError } from 'zod';
+import { createEngineComponents } from './engine-components.js';
+import { ConfigStore } from './fs/config-store.js';
+import { ensurePrivateUserHome } from './fs/home-permissions.js';
+import { enginesRoutes } from './http/routes/engines.js';
+import { modelBundleRoutes } from './http/routes/model-bundles.js';
+import { v1ChatRoutes } from './http/routes/v1-chat.js';
+import { v1EmbeddingsRoutes } from './http/routes/v1-embeddings.js';
+import { v1KnowledgeRoutes } from './http/routes/v1-knowledge.js';
+import { v1ModelsEnsureRoutes } from './http/routes/v1-models-ensure.js';
+import { v1ModelsRoutes } from './http/routes/v1-models.js';
+import { v1ResponsesRoutes } from './http/routes/v1-responses.js';
+import { KnowledgeManager } from './knowledge/manager.js';
+import { createWorkerCatalogHost } from './knowledge/worker-host.js';
+import { embeddingsHealth, openEmbeddings, shutdownEmbeddings } from './memory/embeddings.js';
+import { AppleFoundationModelsProvider } from './providers/apple-foundation-models/provider.js';
+import { EngineInference } from './providers/native/inference.js';
+import { resolveModelSessionDefaults } from './providers/session-defaults.js';
+import { MlxRuntimeStatusBus } from './python/mlx-runtime-status-bus.js';
+import { RelevanceModelManager } from './relevance/manager.js';
+import { relevanceScorer } from './relevance/relevance-model.js';
+import { acquireSingleInstanceLock } from './runtime-lock.js';
+import { HF_CACHE_DIR_ENV, transformersCacheDir } from './transformers-cache.js';
+import { findServiceBundleResource } from './utils/service-worker-entry.js';
+import './http/auth-context.js';
+const log = createLogger('inference');
+/** Direct Fetch host: no listener, product store, background downloads or daemon discovery. */
+export async function startService(options = {}) {
+    const home = options.home ?? gezelHome();
+    await ensurePrivateUserHome(home);
+    // Model files must land in this home's managed cache: unset, transformers.js
+    // falls back to a module-relative cache that is read-only inside a packaged
+    // app, and the embed worker (which reads this env) has no other view of home.
+    process.env[HF_CACHE_DIR_ENV] ??= transformersCacheDir(home);
+    const startedAt = nowIso();
+    const runtimeDir = join(home, 'runtime');
+    const lock = await acquireSingleInstanceLock({ runtimeDir, lockPath: join(runtimeDir, 'lock') });
+    const cleanup = [() => lock.release()];
+    const requests = new Set();
+    let stopping;
+    let closed = false;
+    const stop = () => {
+        stopping ??= (async () => {
+            closed = true;
+            for (const controller of requests)
+                controller.abort();
+            const errors = [];
+            for (const close of cleanup.reverse())
+                try {
+                    await close();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            if (errors.length)
+                throw new AggregateError(errors, 'Inference shutdown failed');
+        })();
+        return stopping;
+    };
+    try {
+        startSuspendMonitor();
+        cleanup.push(() => stopSuspendMonitor());
+        openEmbeddings();
+        cleanup.push(() => shutdownEmbeddings(5000));
+        const store = new ConfigStore(home);
+        const bootConfig = await store.readConfig();
+        discoverNativeBinaries({
+            home,
+            ...(bootConfig.llamaCppBackendOverride
+                ? { llamaCppBackendOverride: bootConfig.llamaCppBackendOverride }
+                : {}),
+        });
+        const dataDir = process.env.GEZEL_GILDE_DATA_DIR?.trim() ||
+            findServiceBundleResource(import.meta.url, ['catalog']);
+        if (!dataDir)
+            throw new Error('The inference package is missing its model catalog');
+        const catalog = new CatalogService([new BundledSource({ dataDir })]);
+        const components = await createEngineComponents({
+            home,
+            catalog,
+            bootConfig,
+            mlxRuntimeStatus: new MlxRuntimeStatusBus(),
+            scheduleInstallProbe: () => { },
+        });
+        cleanup.push(() => {
+            components.cacheController.stop();
+            components.engineBinaries.clear();
+        });
+        class HostedInference extends EngineInference {
+            apple;
+            getProviderForModel(name, model) {
+                if (closed)
+                    return Promise.reject(new Error('Inference is shutting down'));
+                if (name !== 'llama-cpp' &&
+                    name !== 'mlx' &&
+                    name !== 'ds4' &&
+                    name !== 'apple-foundation-models')
+                    return Promise.reject(new Error('Hosted inference only serves on-device models'));
+                const supplied = options.providers?.get(name);
+                if (supplied)
+                    return Promise.resolve(supplied);
+                if (name === 'apple-foundation-models') {
+                    this.apple ??= new AppleFoundationModelsProvider();
+                    return Promise.resolve(this.apple);
+                }
+                return super.getProviderForModel(name, model);
+            }
+            async listModelsForProvider(name) {
+                const supplied = options.providers?.get(name);
+                return supplied ? supplied.listModels() : super.listModelsForProvider(name);
+            }
+            resolveModelSessionDefaults(name, model, overrides) {
+                return resolveModelSessionDefaults(store, catalog, name, model, overrides);
+            }
+            async shutdown() {
+                const results = await Promise.allSettled([
+                    super.shutdown(),
+                    this.apple?.shutdown(),
+                    ...[...(options.providers?.values() ?? [])].map((p) => p.shutdown()),
+                ]);
+                const errors = results
+                    .filter((result) => result.status === 'rejected')
+                    .map((result) => result.reason);
+                if (errors.length)
+                    throw new AggregateError(errors, 'Provider shutdown failed');
+            }
+        }
+        const chat = new HostedInference({ home, store, catalog, ...components });
+        cleanup.push(() => chat.shutdown());
+        const knowledge = new KnowledgeManager({
+            home,
+            host: createWorkerCatalogHost(),
+            catalog,
+            readConfig: () => store.readConfig(),
+            bundledHandboekArchive: null,
+        });
+        cleanup.push(() => knowledge.stop());
+        await knowledge.start();
+        const relevance = new RelevanceModelManager({ home, readConfig: () => store.readConfig() });
+        cleanup.push(() => relevanceScorer().dispose());
+        const context = { home, store, catalog, chat, knowledge, relevance, ...components };
+        const clientToken = randomBytes(32).toString('base64url');
+        const tokenBytes = Buffer.from(clientToken);
+        const app = new Hono();
+        app.onError((error, c) => {
+            if (error instanceof ZodError)
+                return c.json({ error: { code: 'invalid_request', message: error.message } }, 400);
+            const detail = error instanceof Error ? error.message : String(error);
+            try {
+                options.onUnexpectedHttpError?.({
+                    kind: 'unhandled_exception',
+                    requestId: randomUUID(),
+                    method: c.req.method,
+                    path: c.req.path,
+                    status: 500,
+                    detail,
+                });
+            }
+            catch (handlerError) {
+                log.error(`onUnexpectedHttpError threw: ${String(handlerError)}`);
+            }
+            log.error(`${c.req.method} ${c.req.path}: ${detail}`);
+            return c.json({ error: { code: 'internal_error', message: error.message } }, 500);
+        });
+        app.get('/api/health', (c) => c.json({
+            ok: true,
+            version: GEZEL_VERSION,
+            apiCompat: { floor: GEZEL_API_GENERATION_FLOOR, current: GEZEL_API_GENERATION },
+            serviceRole: 'user',
+            profile: 'embedded-inference',
+            startedAt,
+            nodeVersion: process.versions.node,
+            platform: process.platform,
+            embeddings: embeddingsHealth(),
+        }));
+        app.use('*', async (c, next) => {
+            const candidate = Buffer.from(c.req.header('authorization')?.replace(/^Bearer /, '') ?? '');
+            if (candidate.length !== tokenBytes.length || !timingSafeEqual(candidate, tokenBytes))
+                return c.json({ error: 'Unauthorized' }, 401);
+            c.set('auth', { appId: 'host', scopes: ['openai', 'knowledge'] });
+            return next();
+        });
+        const allowedProviders = ['llama-cpp', 'mlx', 'ds4', 'apple-foundation-models'];
+        app.use('/v1/chat/*', bodyLimit({ maxSize: 4 * 1024 * 1024 }));
+        app.route('/v1/chat', v1ChatRoutes(context, { allowedProviders }));
+        app.route('/v1/responses', v1ResponsesRoutes(context, { allowedProviders }));
+        app.route('/v1/embeddings', v1EmbeddingsRoutes(context));
+        app.route('/v1/models/ensure', v1ModelsEnsureRoutes(context));
+        app.route('/v1/models', v1ModelsRoutes(context, { localOnly: true }));
+        app.route('/v1/knowledge', v1KnowledgeRoutes(context));
+        app.route('/api/engines', enginesRoutes(context));
+        app.route('/api/model-bundles', modelBundleRoutes(context));
+        for (const [engine, manager] of [
+            ['llama-cpp', components.llamaCppModels],
+            ['ds4', components.ds4Models],
+            ['mlx', components.mlxModels],
+        ]) {
+            app.get(`/api/${engine}/models`, async (c) => c.json({ models: await manager.listInstalled() }));
+        }
+        app.get('/api/config', async (c) => c.json(await store.readConfig()));
+        const pinSchema = GezelConfigSchema.pick({
+            provider: true,
+            defaultModel: true,
+            firstRunCompleted: true,
+        }).strict();
+        app.put('/api/config', async (c) => c.json(await store.writeConfig(pinSchema.parse(await c.req.json()))));
+        const transport = async (input, init) => {
+            if (closed)
+                throw new Error('Inference is stopped');
+            const request = new Request(input, init);
+            const controller = new AbortController();
+            requests.add(controller);
+            const signal = AbortSignal.any([request.signal, controller.signal]);
+            try {
+                const response = await app.fetch(new Request(request, { signal }));
+                if (!response.body) {
+                    requests.delete(controller);
+                    return response;
+                }
+                const reader = response.body.getReader();
+                const body = new ReadableStream({
+                    async pull(sink) {
+                        try {
+                            const result = await reader.read();
+                            if (result.done) {
+                                requests.delete(controller);
+                                sink.close();
+                            }
+                            else
+                                sink.enqueue(result.value);
+                        }
+                        catch (error) {
+                            requests.delete(controller);
+                            sink.error(error);
+                        }
+                    },
+                    async cancel(reason) {
+                        controller.abort(reason);
+                        requests.delete(controller);
+                        await reader.cancel(reason);
+                    },
+                });
+                return new Response(body, {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: response.headers,
+                });
+            }
+            catch (error) {
+                requests.delete(controller);
+                throw error;
+            }
+        };
+        return {
+            profile: 'embedded-inference',
+            port: 0,
+            cert: null,
+            clientToken,
+            fetch: transport,
+            stop,
+        };
+    }
+    catch (error) {
+        await stop().catch((cleanupError) => log.error(String(cleanupError)));
+        throw error;
+    }
+}

package/dist/knowledge/admission.d.ts

@@ -0,0 +1,3 @@
+import { type UnifiedSearchResult } from '@bendyline/gezel';
+export declare function clearsInjectionFloor(result: UnifiedSearchResult): boolean;
+export declare function admitsUnjudgedKnowledge(result: UnifiedSearchResult): boolean;

package/dist/knowledge/admission.js

@@ -0,0 +1,22 @@
+import { MERGE_WEIGHTS } from '@bendyline/gezel';
+const INJECTION_MIN_RELEVANCE = {
+    content: 120 / 420,
+    symbol: 120 / 520,
+    document: 120 / 680,
+    memory: 120 / 360,
+    session: 120 / 400,
+    // The behavior-preserving quotient over the knowledge merge weight; the
+    // knowledge-bench evals own tuning it from here.
+    knowledge: 120 / 370,
+};
+const INJECTION_MIN_RELEVANCE_DEFAULT = 0.25;
+export function clearsInjectionFloor(result) {
+    const floor = INJECTION_MIN_RELEVANCE[result.kind] ?? INJECTION_MIN_RELEVANCE_DEFAULT;
+    // Results from older callers/stubs may lack `relevance`; derive it from the
+    // weighted score so the check stays exactly equivalent to the old floor.
+    const relevance = result.relevance ?? result.score / (MERGE_WEIGHTS[result.kind] || 1);
+    return relevance >= floor;
+}
+export function admitsUnjudgedKnowledge(result) {
+    return result.arm === 'vector' && clearsInjectionFloor(result);
+}

package/dist/knowledge/bundled-catalog.d.ts

@@ -0,0 +1,2 @@
+export declare const HANDBOEK_KNOWLEDGE_PUBLISHER = "bendyline";
+export declare const HANDBOEK_KNOWLEDGE_CATALOG = "handboek";

package/dist/knowledge/bundled-catalog.js

@@ -0,0 +1,2 @@
+export const HANDBOEK_KNOWLEDGE_PUBLISHER = 'bendyline';
+export const HANDBOEK_KNOWLEDGE_CATALOG = 'handboek';

package/dist/knowledge/catalog-host.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The catalog host boundary: everything that touches catalog SQLite goes
+ * through this interface. Two implementations — the in-process host below
+ * (tests, and the fallback when the worker cannot boot) and the worker
+ * host (worker-host.ts), which confines node:sqlite's synchronous scans to
+ * a dedicated thread so a 100 ms shard scan never stalls the daemon loop
+ * (docs/gezk-format.md). The in-process implementation is test/CLI-only;
+ * production fails closed if its worker becomes unavailable.
+ */
+import type { CatalogAssetFile, CatalogAssetInfo, CatalogAssetRead, CatalogChunkHit, CatalogDocumentMeta, CatalogTopic, CatalogValidationReport } from '@bendyline/gezel-knowledge';
+import type { KnowledgeRadius } from '@bendyline/gezel';
+import type { SpatialMatch } from '@bendyline/gezel-knowledge';
+export interface MountSpec {
+    /** `publisherId/catalogId` — stable across versions. */
+    key: string;
+    rootDir: string;
+    catalogId: string;
+    version: string;
+}
+export interface GlobalSearchHit extends CatalogChunkHit, Partial<SpatialMatch> {
+    catalogKey: string;
+    catalogId: string;
+}
+/** A passage read by its citation id, without search scoring. */
+export type KnowledgeChunk = Omit<CatalogChunkHit, 'cosine' | 'source'>;
+export interface GlobalSearchRequest {
+    /** Unit query vector, or absent for FTS-only search. */
+    vector?: Float32Array;
+    query: string;
+    /** Global shard budget across every mounted catalog (S). */
+    shardBudget: number;
+    /**
+     * Extra shards, beyond S and across every catalog, holding a page the
+     * query names by title (`CatalogHandle.titleRouteShards`), most specific
+     * name first. Default 0.
+     */
+    titleRouteShards?: number;
+    finalK: number;
+    /** Chunk-body FTS over routed shards (explicit search only). */
+    includeChunkFts: boolean;
+    /** Restrict to these catalog keys (default: all mounted). */
+    catalogKeys?: string[];
+    docFtsLimit?: number;
+    /** Chunk-body FTS hits per shard (default 8). */
+    chunkFtsLimit?: number;
+    spatial?: KnowledgeRadius;
+    /**
+     * Media rows to return per modality per catalog from the exact media lane
+     * (`CatalogHandle.searchMedia`). Needs `vector`; default 0, so proactive
+     * retrieval stays text-only unless it asks.
+     */
+    mediaK?: number;
+}
+export interface GlobalSearchResponse {
+    chunks: GlobalSearchHit[];
+    documents: Array<{
+        catalogKey: string;
+        catalogId: string;
+        documentId: string;
+        rank: number;
+    } & Partial<SpatialMatch>>;
+}
+export interface KnowledgeCatalogHost {
+    mount(spec: MountSpec): Promise<void>;
+    unmount(key: string): Promise<void>;
+    mounted(): Promise<string[]>;
+    /** Load a mounted catalog's vector bits ahead of its first search; resolves to the shards loaded. */
+    prewarm(key: string): Promise<number>;
+    /** Deep or shallow validation of an extracted catalog dir (quarantine gate). */
+    validate(rootDir: string, deep: boolean): Promise<CatalogValidationReport>;
+    topics(key: string): Promise<CatalogTopic[]>;
+    documentsPage(key: string, opts: {
+        topicId?: string;
+        offset?: number;
+        limit?: number;
+        descendants?: boolean;
+    }): Promise<{
+        documents: CatalogDocumentMeta[];
+        total: number;
+    }>;
+    nearbyDocuments(key: string, radius: KnowledgeRadius, opts: {
+        offset?: number;
+        limit?: number;
+    }): Promise<{
+        documents: Array<CatalogDocumentMeta & SpatialMatch>;
+        total: number;
+    }>;
+    getDocument(key: string, documentId: string): Promise<(CatalogDocumentMeta & {
+        markdown: string;
+    }) | null>;
+    /** One passage by its citation id; null when the catalog does not hold it. */
+    getChunk(key: string, documentId: string, chunkUid: string): Promise<KnowledgeChunk | null>;
+    /** The catalog's declared `assets/` files. */
+    assets(key: string): Promise<CatalogAssetInfo[]>;
+    /** One declared asset's bytes, or null when the catalog ships no such asset. */
+    readAsset(key: string, path: string): Promise<CatalogAssetRead | null>;
+    /** A declared asset's verified file on disk, for range-streaming large media. */
+    assetFile(key: string, path: string): Promise<CatalogAssetFile | null>;
+    search(request: GlobalSearchRequest): Promise<GlobalSearchResponse>;
+    dispose(): Promise<void>;
+}
+/** Direct CatalogHandle host — used by tests and as the no-worker fallback. */
+export declare function createInProcessCatalogHost(): Promise<KnowledgeCatalogHost>;

package/dist/knowledge/catalog-host.js

@@ -0,0 +1,180 @@
+/**
+ * The catalog host boundary: everything that touches catalog SQLite goes
+ * through this interface. Two implementations — the in-process host below
+ * (tests, and the fallback when the worker cannot boot) and the worker
+ * host (worker-host.ts), which confines node:sqlite's synchronous scans to
+ * a dedicated thread so a 100 ms shard scan never stalls the daemon loop
+ * (docs/gezk-format.md). The in-process implementation is test/CLI-only;
+ * production fails closed if its worker becomes unavailable.
+ */
+/** Direct CatalogHandle host — used by tests and as the no-worker fallback. */
+export async function createInProcessCatalogHost() {
+    const { CatalogHandle: Handle, validateExtractedCatalog } = await import('@bendyline/gezel-knowledge');
+    const handles = new Map();
+    const searchImpl = (request) => {
+        const keys = request.catalogKeys ?? [...handles.keys()];
+        const active = keys
+            .map((key) => ({ key, handle: handles.get(key) }))
+            .filter((e) => Boolean(e.handle));
+        const spatial = new Map(active.map(({ key, handle }) => [
+            key,
+            request.spatial ? handle.spatialMatches(request.spatial) : undefined,
+        ]));
+        const allowed = (key) => {
+            const matches = spatial.get(key);
+            return matches ? new Set(matches.keys()) : undefined;
+        };
+        const documents = [];
+        for (const { key, handle } of active) {
+            for (const hit of handle.searchDocumentsFts(request.query, request.docFtsLimit ?? 8, allowed(key))) {
+                documents.push({
+                    catalogKey: key,
+                    catalogId: handle.catalogId,
+                    documentId: hit.documentId,
+                    rank: hit.rank,
+                    ...spatial.get(key)?.get(hit.documentId),
+                });
+            }
+        }
+        const chunks = [];
+        /** Global routing: score shards across all catalogs, spend S once. */
+        const routed = new Map();
+        if (request.spatial) {
+            for (const { key, handle } of active)
+                routed.set(key, handle.shardsForDocuments(allowed(key)));
+        }
+        if (request.vector) {
+            const scored = [];
+            for (const { key, handle } of active) {
+                if (request.spatial)
+                    continue;
+                for (const s of handle.scoreShards(request.vector)) {
+                    scored.push({ key, shardId: s.shardId, score: s.score });
+                }
+            }
+            for (const pick of scored.sort((a, b) => b.score - a.score).slice(0, request.shardBudget)) {
+                const list = routed.get(pick.key) ?? [];
+                list.push(pick.shardId);
+                routed.set(pick.key, list);
+            }
+            // Title-assisted routing: centroid scores alone can leave out the
+            // shard holding the very page the question names, so scan it too.
+            const extra = request.spatial ? 0 : (request.titleRouteShards ?? 0);
+            if (extra > 0) {
+                const named = [];
+                for (const { key, handle } of active) {
+                    for (const s of handle.titleRouteShards(request.query, extra))
+                        named.push({ key, ...s });
+                }
+                // Exact-title matches score Infinity, so compare rather than subtract.
+                named.sort((a, b) => (a.score === b.score ? 0 : a.score < b.score ? 1 : -1));
+                let added = 0;
+                for (const pick of named) {
+                    if (added >= extra)
+                        break;
+                    const list = routed.get(pick.key) ?? [];
+                    if (list.includes(pick.shardId))
+                        continue;
+                    list.push(pick.shardId);
+                    routed.set(pick.key, list);
+                    added++;
+                }
+            }
+            for (const { key, handle } of active) {
+                const shardIds = routed.get(key);
+                if (!shardIds || shardIds.length === 0)
+                    continue;
+                for (const hit of handle.searchShards(request.vector, shardIds, request.finalK, allowed(key))) {
+                    chunks.push({
+                        ...hit,
+                        catalogKey: key,
+                        catalogId: handle.catalogId,
+                        ...spatial.get(key)?.get(hit.documentId),
+                    });
+                }
+            }
+        }
+        if (request.vector && (request.mediaK ?? 0) > 0) {
+            for (const { key, handle } of active) {
+                for (const hit of handle.searchMedia(request.vector, {
+                    perModality: request.mediaK,
+                    ...(request.spatial ? { allowedDocumentIds: allowed(key) } : {}),
+                })) {
+                    chunks.push({
+                        ...hit,
+                        catalogKey: key,
+                        catalogId: handle.catalogId,
+                        ...spatial.get(key)?.get(hit.documentId),
+                    });
+                }
+            }
+        }
+        if (request.includeChunkFts) {
+            for (const { key, handle } of active) {
+                const shardIds = routed.get(key) ?? handle.shards.map((s) => s.id);
+                for (const hit of handle.searchChunksFts(request.query, shardIds, request.chunkFtsLimit ?? 8, allowed(key))) {
+                    chunks.push({
+                        ...hit,
+                        catalogKey: key,
+                        catalogId: handle.catalogId,
+                        ...spatial.get(key)?.get(hit.documentId),
+                    });
+                }
+            }
+        }
+        return { chunks, documents };
+    };
+    return {
+        mount: async (spec) => {
+            if (handles.has(spec.key))
+                return;
+            const handle = Handle.open(spec.rootDir);
+            handle.catalogId = spec.catalogId;
+            const metaCatalog = handle.meta.catalog_id;
+            if (metaCatalog !== spec.catalogId) {
+                handle.close();
+                throw new Error(`catalog identity mismatch: router says '${metaCatalog}'`);
+            }
+            handles.set(spec.key, handle);
+        },
+        unmount: async (key) => {
+            handles.get(key)?.close();
+            handles.delete(key);
+        },
+        mounted: async () => [...handles.keys()],
+        prewarm: async (key) => {
+            const handle = mustGet(handles, key);
+            let loaded = 0;
+            // Stop if the catalog is unmounted mid-warm: a closed handle would
+            // reopen its shard connections to load the next one.
+            while (handles.get(key) === handle && handle.prewarmNextShard()) {
+                loaded++;
+                // Yield between shards so searches queued behind a large catalog's
+                // warm-up are answered instead of waiting for all of it.
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+            return loaded;
+        },
+        validate: async (rootDir, deep) => validateExtractedCatalog(rootDir, { deep }),
+        topics: async (key) => mustGet(handles, key).topics(),
+        documentsPage: async (key, opts) => mustGet(handles, key).documentsPage(opts),
+        nearbyDocuments: async (key, radius, opts) => mustGet(handles, key).nearbyDocuments(radius, opts),
+        getDocument: async (key, documentId) => mustGet(handles, key).getDocument(documentId),
+        getChunk: async (key, documentId, chunkUid) => mustGet(handles, key).getChunk(documentId, chunkUid),
+        assets: async (key) => mustGet(handles, key).assets(),
+        readAsset: async (key, path) => mustGet(handles, key).readAsset(path),
+        assetFile: async (key, path) => mustGet(handles, key).assetFile(path),
+        search: async (request) => searchImpl(request),
+        dispose: async () => {
+            for (const handle of handles.values())
+                handle.close();
+            handles.clear();
+        },
+    };
+}
+function mustGet(map, key) {
+    const value = map.get(key);
+    if (!value)
+        throw new Error(`catalog not mounted: ${key}`);
+    return value;
+}

package/dist/knowledge/catalog-source.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve a gilde `knowledge-catalog` entry to the hardened URL install the
+ * daemon already knows how to run: the pinned commit + path become an
+ * immutable Hugging Face resolve URL, and the pinned sha256 becomes the
+ * digest the installer must observe. The entry is the trust root, exactly as
+ * a chat model's pinned files are — no signature, no registry round trip.
+ */
+import type { KnowledgeCatalogHuggingfaceSource, KnowledgeCatalogItemManifest } from '@bendyline/gezel';
+import type { TrustedKnowledgeCoordinate } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+/** Test seam: an e2e run points this at a local server. */
+export declare const HF_BASE_URL_ENV = "GEZEL_HF_BASE_URL";
+export declare function huggingfaceDatasetResolveUrl(source: KnowledgeCatalogHuggingfaceSource, baseUrl?: string): string;
+export interface ResolvedKnowledgeCatalogSource {
+    item: KnowledgeCatalogItemManifest;
+    url: string;
+    sha256: string;
+    archiveBytes: number;
+    uncompressedBytes: number;
+    coordinate: TrustedKnowledgeCoordinate;
+}
+export declare function resolveKnowledgeCatalogSource(catalog: CatalogService, id: string, version?: string): Promise<ResolvedKnowledgeCatalogSource | null>;

package/dist/knowledge/catalog-source.js

@@ -0,0 +1,35 @@
+/**
+ * Resolve a gilde `knowledge-catalog` entry to the hardened URL install the
+ * daemon already knows how to run: the pinned commit + path become an
+ * immutable Hugging Face resolve URL, and the pinned sha256 becomes the
+ * digest the installer must observe. The entry is the trust root, exactly as
+ * a chat model's pinned files are — no signature, no registry round trip.
+ */
+/** Test seam: an e2e run points this at a local server. */
+export const HF_BASE_URL_ENV = 'GEZEL_HF_BASE_URL';
+export function huggingfaceDatasetResolveUrl(source, baseUrl = process.env[HF_BASE_URL_ENV]?.trim() || 'https://huggingface.co') {
+    const path = source.path
+        .split('/')
+        .map((seg) => encodeURIComponent(seg))
+        .join('/');
+    return `${baseUrl.replace(/\/$/, '')}/datasets/${source.repo}/resolve/${encodeURIComponent(source.revision)}/${path}?download=true`;
+}
+export async function resolveKnowledgeCatalogSource(catalog, id, version) {
+    const detail = await catalog.get('knowledge-catalog', id, undefined, version);
+    if (!detail || detail.manifest.kind !== 'knowledge-catalog')
+        return null;
+    const item = detail.manifest;
+    return {
+        item,
+        url: huggingfaceDatasetResolveUrl(item.huggingface),
+        sha256: item.sha256,
+        archiveBytes: item.archiveBytes,
+        uncompressedBytes: item.uncompressedBytes,
+        coordinate: {
+            publisherId: item.publisherId,
+            catalogId: item.id,
+            version: item.version,
+            expectedDigest: item.sha256,
+        },
+    };
+}