@ponraaj/dimple-sdk 0.0.0-alpha.1 → 0.0.0-alpha.10

package/dist/indexer.d.ts

@@ -25,11 +25,20 @@ export interface WalkResult {
      * SAME file always gets the SAME key regardless of which path list was
      * passed (idempotent re-indexing across invocation shapes). */
     readonly root: string;
+    /** The resolved input paths — the reconcile DOMAIN: units whose file
+     * path is outside every root are untouched by subtree runs. */
+    readonly roots: readonly string[];
 }
 /** Recursively collect indexable files from paths (dirs or files). */
 export declare const walkFiles: (paths: readonly string[], extensions: readonly string[]) => WalkResult;
 /** Read a file's text, capped at `maxBytes` (string slice = char-safe). */
 export declare const readCapped: (path: string, maxBytes: number) => string;
+/** The repository's HEAD commit for provenance stamping — soft-failed
+ * (non-git trees, missing git, permission errors → null). Walks UP from
+ * the first indexed file (git finds the enclosing repo), so it works for
+ * absolute-path trees whose key root is "/". Platform side; the facade
+ * never touches node APIs. */
+export declare const currentCommit: (firstFile: string | undefined) => string | null;
 /** Resolve a file's relative import specifiers to indexed-tree files
  * (bare/absolute specifiers are external modules — no node_modules
  * resolution). */

package/dist/internal/config/schema.d.ts

@@ -13,11 +13,40 @@ export declare const EmbeddingModelConfig: Schema.Struct<{
     readonly dimensions: Schema.Number;
     readonly vectorType: Schema.optional<Schema.String>;
     readonly apiKey: Schema.optional<Schema.String>;
+    /** Hosted providers: OpenAI-compatible endpoint override (default
+     * `https://api.openai.com/v1`). */
+    readonly baseURL: Schema.optional<Schema.String>;
     readonly indexConfig: Schema.optional<Schema.Struct<{
         readonly compressNeighbors: Schema.optional<Schema.String>;
         readonly maxNeighbors: Schema.optional<Schema.Number>;
         readonly searchL: Schema.optional<Schema.Number>;
     }>>;
+    /** Transformers.js runtime options — per-model, all optional (defaults:
+     * device "cpu", dtype "q8", pooling "mean", normalize true). `dtype`
+     * quantizes the MODEL WEIGHTS (inference memory/speed), never the
+     * output vectors; unsupported devices fail typed at first use. */
+    readonly device: Schema.optional<Schema.Literals<readonly ["auto", "gpu", "cpu", "wasm", "webgpu", "cuda", "dml", "coreml", "webnn"]>>;
+    readonly dtype: Schema.optional<Schema.Literals<readonly ["fp32", "fp16", "q8", "int8", "uint8", "q4", "bnb4", "q4f16", "q2", "q2f16", "q1", "q1f16"]>>;
+    readonly pooling: Schema.optional<Schema.Literals<readonly ["mean", "cls", "none"]>>;
+    readonly normalize: Schema.optional<Schema.Boolean>;
+    readonly cacheDir: Schema.optional<Schema.String>;
+    /** ONNX Runtime CUDA session options — the verified fix for GPUs with
+     * limited VRAM (≤8GB): ORT's default arena is unbounded and grows by
+     * powers of two, so batch inference OOMs mid-run and poisons the
+     * process for later queries. `gpuMemLimit` caps the arena (bytes);
+     * `arenaExtendStrategy` picks the growth policy (0 = kNextPowerOfTwo,
+     * 1 = kSameAsRequested). CPU / ample-VRAM GPUs are unaffected (ORT
+     * defaults preserved when absent). */
+    readonly sessionOptions: Schema.optional<Schema.Struct<{
+        readonly gpuMemLimit: Schema.optional<Schema.Number>;
+        readonly arenaExtendStrategy: Schema.optional<Schema.Literals<readonly [0, 1]>>;
+    }>>;
+    /** First-use auto-install of the optional `@huggingface/transformers`
+     * peer (default true) — the package is installed with the project's
+     * own package manager on the first local-embed use (scripts skipped,
+     * proven unnecessary for embedding). Set false to require a manual
+     * install. */
+    readonly autoInstall: Schema.optional<Schema.Boolean>;
 }>;
 export interface EmbeddingModelConfig extends Schema.Schema.Type<typeof EmbeddingModelConfig> {
 }
@@ -30,11 +59,40 @@ export declare const EmbeddingConfig: Schema.Struct<{
         readonly dimensions: Schema.Number;
         readonly vectorType: Schema.optional<Schema.String>;
         readonly apiKey: Schema.optional<Schema.String>;
+        /** Hosted providers: OpenAI-compatible endpoint override (default
+         * `https://api.openai.com/v1`). */
+        readonly baseURL: Schema.optional<Schema.String>;
         readonly indexConfig: Schema.optional<Schema.Struct<{
             readonly compressNeighbors: Schema.optional<Schema.String>;
             readonly maxNeighbors: Schema.optional<Schema.Number>;
             readonly searchL: Schema.optional<Schema.Number>;
         }>>;
+        /** Transformers.js runtime options — per-model, all optional (defaults:
+         * device "cpu", dtype "q8", pooling "mean", normalize true). `dtype`
+         * quantizes the MODEL WEIGHTS (inference memory/speed), never the
+         * output vectors; unsupported devices fail typed at first use. */
+        readonly device: Schema.optional<Schema.Literals<readonly ["auto", "gpu", "cpu", "wasm", "webgpu", "cuda", "dml", "coreml", "webnn"]>>;
+        readonly dtype: Schema.optional<Schema.Literals<readonly ["fp32", "fp16", "q8", "int8", "uint8", "q4", "bnb4", "q4f16", "q2", "q2f16", "q1", "q1f16"]>>;
+        readonly pooling: Schema.optional<Schema.Literals<readonly ["mean", "cls", "none"]>>;
+        readonly normalize: Schema.optional<Schema.Boolean>;
+        readonly cacheDir: Schema.optional<Schema.String>;
+        /** ONNX Runtime CUDA session options — the verified fix for GPUs with
+         * limited VRAM (≤8GB): ORT's default arena is unbounded and grows by
+         * powers of two, so batch inference OOMs mid-run and poisons the
+         * process for later queries. `gpuMemLimit` caps the arena (bytes);
+         * `arenaExtendStrategy` picks the growth policy (0 = kNextPowerOfTwo,
+         * 1 = kSameAsRequested). CPU / ample-VRAM GPUs are unaffected (ORT
+         * defaults preserved when absent). */
+        readonly sessionOptions: Schema.optional<Schema.Struct<{
+            readonly gpuMemLimit: Schema.optional<Schema.Number>;
+            readonly arenaExtendStrategy: Schema.optional<Schema.Literals<readonly [0, 1]>>;
+        }>>;
+        /** First-use auto-install of the optional `@huggingface/transformers`
+         * peer (default true) — the package is installed with the project's
+         * own package manager on the first local-embed use (scripts skipped,
+         * proven unnecessary for embedding). Set false to require a manual
+         * install. */
+        readonly autoInstall: Schema.optional<Schema.Boolean>;
     }>>;
 }>;
 export interface EmbeddingConfig extends Schema.Schema.Type<typeof EmbeddingConfig> {
@@ -110,11 +168,40 @@ export declare const DimpleConfig: Schema.Struct<{
             readonly dimensions: Schema.Number;
             readonly vectorType: Schema.optional<Schema.String>;
             readonly apiKey: Schema.optional<Schema.String>;
+            /** Hosted providers: OpenAI-compatible endpoint override (default
+             * `https://api.openai.com/v1`). */
+            readonly baseURL: Schema.optional<Schema.String>;
             readonly indexConfig: Schema.optional<Schema.Struct<{
                 readonly compressNeighbors: Schema.optional<Schema.String>;
                 readonly maxNeighbors: Schema.optional<Schema.Number>;
                 readonly searchL: Schema.optional<Schema.Number>;
             }>>;
+            /** Transformers.js runtime options — per-model, all optional (defaults:
+             * device "cpu", dtype "q8", pooling "mean", normalize true). `dtype`
+             * quantizes the MODEL WEIGHTS (inference memory/speed), never the
+             * output vectors; unsupported devices fail typed at first use. */
+            readonly device: Schema.optional<Schema.Literals<readonly ["auto", "gpu", "cpu", "wasm", "webgpu", "cuda", "dml", "coreml", "webnn"]>>;
+            readonly dtype: Schema.optional<Schema.Literals<readonly ["fp32", "fp16", "q8", "int8", "uint8", "q4", "bnb4", "q4f16", "q2", "q2f16", "q1", "q1f16"]>>;
+            readonly pooling: Schema.optional<Schema.Literals<readonly ["mean", "cls", "none"]>>;
+            readonly normalize: Schema.optional<Schema.Boolean>;
+            readonly cacheDir: Schema.optional<Schema.String>;
+            /** ONNX Runtime CUDA session options — the verified fix for GPUs with
+             * limited VRAM (≤8GB): ORT's default arena is unbounded and grows by
+             * powers of two, so batch inference OOMs mid-run and poisons the
+             * process for later queries. `gpuMemLimit` caps the arena (bytes);
+             * `arenaExtendStrategy` picks the growth policy (0 = kNextPowerOfTwo,
+             * 1 = kSameAsRequested). CPU / ample-VRAM GPUs are unaffected (ORT
+             * defaults preserved when absent). */
+            readonly sessionOptions: Schema.optional<Schema.Struct<{
+                readonly gpuMemLimit: Schema.optional<Schema.Number>;
+                readonly arenaExtendStrategy: Schema.optional<Schema.Literals<readonly [0, 1]>>;
+            }>>;
+            /** First-use auto-install of the optional `@huggingface/transformers`
+             * peer (default true) — the package is installed with the project's
+             * own package manager on the first local-embed use (scripts skipped,
+             * proven unnecessary for embedding). Set false to require a manual
+             * install. */
+            readonly autoInstall: Schema.optional<Schema.Boolean>;
         }>>;
     }>>;
     readonly jobs: Schema.optional<Schema.Struct<{

package/dist/internal/core/hosted-embedding.d.ts

@@ -0,0 +1,33 @@
+import { type EmbeddingModel } from "./internal/embedder/index.js";
+export interface HostedEmbeddingOptions {
+    readonly modelId: string;
+    readonly model: string;
+    readonly dimensions: number;
+    readonly apiKey: string;
+    /** The AI SDK provider family — see
+     * https://ai-sdk.dev/providers for the full provider list. */
+    readonly provider?: "openai" | "google" | "cohere" | "bedrock";
+    /** OpenAI-compatible endpoint override — ONLY needed for custom
+     * endpoints (vLLM/ollama/…). The preconfigured providers have their
+     * base URL baked in. */
+    readonly baseURL?: string;
+}
+/**
+ * Hosted embeddings — the `ai` SDK IS the implementation (`embedMany`),
+ * this adapter only bridges it to the dimple `EmbeddingModel` interface.
+ *
+ * Provider mapping (config `provider` field):
+ * - `"openai"` — openai-compatible provider; `baseURL` defaults to
+ *   `https://api.openai.com/v1`, override for any compatible endpoint
+ * - `"google"` — native `@ai-sdk/google` (gemini-embedding-*), no baseURL
+ * - `"cohere"` — native `@ai-sdk/cohere` (embed-*-v3.0), no baseURL
+ * - `"bedrock"` — native `@ai-sdk/amazon-bedrock` (titan/nova/cohere
+ *   models), no baseURL — credentials come from AWS env (or the provider
+ *   settings)
+ *
+ * `dimensions` is sent as a provider option where the API supports it
+ * (openaiCompatible.dimensions / google.outputDimensionality /
+ * cohere.outputDimension) and ALWAYS enforced on the output (some
+ * endpoints ignore the option).
+ */
+export declare const makeHostedEmbeddingModel: (options: HostedEmbeddingOptions) => EmbeddingModel;

package/dist/internal/embedder/auto-install.d.ts

@@ -0,0 +1,10 @@
+import { type PackageManager } from "./internal/installer/index.js";
+export type { InstallTarget, PackageManager } from "./internal/installer/index.js";
+export { detectPackageManager } from "./internal/installer/index.js";
+/** The install argv for a manager with the transformers package (kept for
+ * callers/tests that assert the shape). */
+export declare const installCommand: (pm: PackageManager) => readonly [string, ...string[]];
+/** Install transformers at the project root detected from `cwd`. The
+ * shared installer kills the child on timeout and dedups concurrent
+ * first-use installs; failures reject with the manual command. */
+export declare const installTransformers: (cwd: string) => Promise<void>;

package/dist/internal/embedder/index.d.ts

@@ -1,4 +1,3 @@
 export { Service as EmbeddingModelRegistry, type Interface as EmbeddingModelRegistryInterface, type EmbeddingModel, EmbeddingError, } from "./provider.ts";
-export { layer as transformersEmbeddingLayer, layerConfig as transformersEmbeddingLayerConfig, makeTransformersModel, } from "./transformers.ts";
-export { makeOpenAIModel } from "./openai.ts";
+export { layer as transformersEmbeddingLayer, layerConfig as transformersEmbeddingLayerConfig, makeTransformersModel, buildSessionOptions, } from "./transformers.ts";
 export { layer as registryLayer, type ModelSpec } from "./registry.ts";

package/dist/internal/embedder/transformers.d.ts

@@ -1,16 +1,54 @@
 import { Config, Layer } from "effect";
-import type { DeviceType } from "@huggingface/transformers";
 import { Service, type EmbeddingModel } from "./provider.ts";
+/** Mirror of transformers.js's `DeviceType` (the config schema carries the
+ * same literals) — kept local so the optional peer's types never appear
+ * in this module's surface. */
+type DeviceType = "auto" | "gpu" | "cpu" | "wasm" | "webgpu" | "cuda" | "dml" | "coreml" | "webnn";
+/** The ORT session-options shape transformers.js forwards to
+ * onnxruntime-node (executionProviders with a bounded CUDA arena). */
+interface OrtSessionOptions {
+    readonly executionProviders: readonly [
+        {
+            readonly name: string;
+            readonly device_id: number;
+            readonly gpu_mem_limit?: number;
+            readonly arena_extend_strategy?: 0 | 1;
+        }
+    ];
+}
+/** Map the focused dimple-level pair to ORT's snake_case session keys.
+ * Both fields absent → `undefined`, so the caller can skip the whole
+ * sessionOptions (ORT defaults preserved). */
+export declare const buildSessionOptions: (opts: {
+    readonly gpuMemLimit?: number | undefined;
+    readonly arenaExtendStrategy?: 0 | 1 | undefined;
+}) => OrtSessionOptions;
 interface TransformersOptions {
     readonly modelId?: string;
     readonly device?: DeviceType;
-    readonly dtype?: "fp32" | "fp16" | "q8" | "q4";
+    readonly dtype?: "fp32" | "fp16" | "q8" | "int8" | "uint8" | "q4" | "bnb4" | "q4f16" | "q2" | "q2f16" | "q1" | "q1f16";
     readonly pooling?: "mean" | "cls" | "none";
     readonly normalize?: boolean;
     readonly cacheDir?: string;
+    /** ONNX Runtime CUDA session options — the verified fix for GPUs with
+     * limited VRAM (≤8GB): ORT's default arena is unbounded (grows by
+     * powers of two), so batch inference OOMs mid-run and leaves the
+     * process unable to allocate even a cublas handle afterwards. Forwarded
+     * to the pipeline's sessionOptions; absent = ORT defaults (CPU and
+     * ample-VRAM GPUs unaffected). */
+    readonly sessionOptions?: {
+        readonly gpuMemLimit?: number | undefined;
+        readonly arenaExtendStrategy?: 0 | 1 | undefined;
+    };
     /** Declared output dimension — validated against the model's actual
      * output on first embed (a mismatch fails typed, precisely). */
     readonly dimensions?: number;
+    /** First-use auto-install of the optional `@huggingface/transformers`
+     * peer (default true): the config declaring a transformers provider is
+     * explicit intent — the missing package is installed with the project's
+     * own package manager (scripts skipped; proven unnecessary for
+     * embedding). Set false to require a manual install. */
+    readonly autoInstall?: boolean;
 }
 export declare const makeTransformersModel: (options?: TransformersOptions) => EmbeddingModel;
 export declare const layer: (options?: TransformersOptions) => Layer.Layer<Service>;

package/dist/internal/extractor/models/extraction.d.ts

@@ -15,6 +15,13 @@ export declare const ExtractedChunk: Schema.Struct<{
     readonly endLine: Schema.Number;
     readonly language: Schema.String;
     readonly docstring: Schema.optional<Schema.String>;
+    /** Call sites inside this definition — the code_calls edge source:
+     * `[{ name, line }]`, callee names only (member/property calls unwrap
+     * to the property name). */
+    readonly calls: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly line: Schema.Number;
+    }>>>;
 }>;
 export interface ExtractedChunk extends Schema.Schema.Type<typeof ExtractedChunk> {
 }
@@ -40,6 +47,13 @@ export declare const ExtractedFile: Schema.Struct<{
         readonly endLine: Schema.Number;
         readonly language: Schema.String;
         readonly docstring: Schema.optional<Schema.String>;
+        /** Call sites inside this definition — the code_calls edge source:
+         * `[{ name, line }]`, callee names only (member/property calls unwrap
+         * to the property name). */
+        readonly calls: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly line: Schema.Number;
+        }>>>;
     }>>;
     readonly imports: Schema.optional<Schema.$Array<Schema.Struct<{
         readonly source: Schema.String;

package/dist/internal/installer/index.d.ts

@@ -0,0 +1,26 @@
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+export interface InstallTarget {
+    readonly pm: PackageManager;
+    readonly root: string;
+}
+export declare class InstallerError extends Error {
+    constructor(message: string);
+}
+/** Detect the project's package manager by walking UP from `cwd` for a
+ * lockfile. NO lockfile → npm (the most universal — a bun fallback broke
+ * Node-only machines with ENOENT). */
+export declare const detectPackageManager: (cwd: string) => InstallTarget;
+/** The executable name for a manager. win32 ships `.cmd` shims for
+ * npm/pnpm/yarn — the bare names fail with ENOENT. */
+export declare const resolveExecutable: (pm: PackageManager, platform?: NodeJS.Platform) => string;
+/** The base install argv for a manager. Scripts are skipped everywhere;
+ * pnpm at a workspace root additionally gets `-w`. */
+export declare const installArgs: (pm: PackageManager, packages: readonly string[], root: string) => string[];
+export interface InstallOptions {
+    readonly cwd?: string;
+    /** Hard deadline; the child is SIGKILLed when it trips (default 5 min). */
+    readonly timeoutMs?: number;
+    /** Injectable for tests (defaults to process.platform). */
+    readonly platform?: NodeJS.Platform;
+}
+export declare const installOptionalPeers: (packages: readonly string[], opts?: InstallOptions) => Promise<void>;

package/dist/internal/logger/index.d.ts

@@ -1,4 +1,4 @@
-export { Service as Logging, layer as loggingLayer, layerConfig as loggingLayerConfig, make as makeLogging, consoleSink, fileSink, effectLogger, type Sink, type Interface as LoggingInterface, type StructuredOutput, } from "./service.ts";
+export { Service as Logging, layer as loggingLayer, layerConfig as loggingLayerConfig, makeEffect as makeLogging, consoleSink, fileSink, effectLogger, type Sink, type Interface as LoggingInterface, type StructuredOutput, } from "./service.ts";
 export { LogConfig, LogLevel, SEV_NUM, LEVEL_ORDER, type LogEntry } from "./types.ts";
 export { RingBuffer, type RingFrame, type Subscriber } from "./ring.ts";
 export { renderJson, renderPretty } from "./format.ts";

package/dist/internal/logger/service.d.ts

@@ -1,4 +1,4 @@
-import { Config, Context, Layer, Logger } from "effect";
+import { Config, Context, Effect, Layer, Logger, Schema } from "effect";
 import type { Scope } from "effect/Scope";
 import { RingBuffer } from "./ring.ts";
 import { type LogConfig, type LogEntry } from "./types.ts";
@@ -9,35 +9,54 @@ export interface Sink {
     /** Receives the ENTRY — each sink renders it its own way (pretty on the
      * console, JSONL in the file and ring). */
     readonly write: (entry: LogEntry) => void;
-    readonly dispose: () => void;
+    readonly dispose: () => void | Promise<void>;
 }
 export declare const consoleSink: (pretty: boolean) => Sink;
-/** Append-per-event file sink (the pino model): each rendered line goes
+/**
+ * Append-per-event file sink (the pino model): each rendered line goes
  * straight to the fd and the OS page cache does the buffering; `fsync`
  * runs on process exit and on dispose. NOT sync-flush-per-event (kills
- * throughput), NOT end-of-run dumps (lose everything on crash). */
-export declare const fileSink: (path: string) => Sink;
+ * throughput), NOT end-of-run dumps (lose everything on crash).
+ *
+ * `node:fs` loads LAZILY (dynamic import) — the module stays free of
+ * static node imports, so the worker bundle builds anywhere; a file sink
+ * is never configured on edge.
+ */
+export declare const fileSink: (path: string) => Effect.Effect<Sink>;
 export interface Interface {
     readonly emit: (entry: LogEntry) => void;
     /** Live tail mirror: pre-rendered JSONL lines, drop-oldest, NOT durable. */
     readonly ring: RingBuffer;
-    readonly dispose: () => void;
+    readonly dispose: () => void | Promise<void>;
 }
 declare const Service_base: Context.ServiceClass<Service, "@dimple/logger/Logging", Interface>;
 export declare class Service extends Service_base {
 }
-export declare const make: (config: LogConfig) => Interface;
-/** The structured shape Effect's `Logger.formatStructured` emits. */
+/** Effect variant of `make` — builds the file sink through lazy `node:fs`
+ * (see `fileSink`; the console sink is sync). */
+export declare const makeEffect: (config: LogConfig) => Effect.Effect<Interface>;
+/** Effect log messages: strings pass through, arrays are joined, anything
+ * else renders as JSON (the `Logger.formatStructured` message contract).
+ * The schema is total for the values Effect actually emits; the caller
+ * supplies the JSON fallback when decoding fails. */
+declare const LogMessage: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.Unknown>]>;
+type LogMessage = Schema.Schema.Type<typeof LogMessage>;
+/** The structured shape after boundary decoding of Effect's raw
+ * `Logger.formatStructured` output (annotations carry arbitrary JSON
+ * values; the decode happens in `effectLogger` before `toEntry`). */
 export interface StructuredOutput {
     readonly level: string;
     readonly fiberId: string;
     readonly timestamp: string;
-    readonly message: unknown;
+    readonly message: LogMessage;
     readonly cause: string | undefined;
-    readonly annotations: Record<string, unknown>;
-    readonly spans: Record<string, number>;
+    readonly annotations: Readonly<Record<string, Schema.Json>>;
+    readonly spans: Readonly<Record<string, number>>;
 }
-/** The Effect `Logger` that feeds the Logging service. */
+/** The Effect `Logger` that feeds the Logging service. The raw structured
+ * output is decoded at this boundary: annotations may carry arbitrary
+ * values, so each is decoded as JSON (non-JSON payloads degrade to their
+ * JSON rendering, keeping the JSONL sink lossless). */
 export declare const effectLogger: (logging: Interface) => Logger.Logger<unknown, void>;
 /** Installs the Logging service AND replaces Effect's default logger with
  * the adapter feeding it. `mergeWithExisting: false` — one logger

package/dist/internal/logger/types.d.ts

@@ -6,8 +6,20 @@ export type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
 export declare const LogLevel: Schema.Literals<readonly ["trace", "debug", "info", "warn", "error"]>;
 /** OTel severity numbers (logs data model): TRACE=1, DEBUG=5, INFO=9,
  * WARN=13, ERROR=17. */
-export declare const SEV_NUM: Record<LogLevel, number>;
-export declare const LEVEL_ORDER: Record<LogLevel, number>;
+export declare const SEV_NUM: {
+    trace: number;
+    debug: number;
+    info: number;
+    warn: number;
+    error: number;
+};
+export declare const LEVEL_ORDER: {
+    trace: number;
+    debug: number;
+    info: number;
+    warn: number;
+    error: number;
+};
 export declare const LogConfig: Schema.Struct<{
     readonly enabled: Schema.withDecodingDefaultType<Schema.optional<Schema.Boolean>, never>;
     readonly level: Schema.withDecodingDefaultType<Schema.optional<Schema.Literals<readonly ["trace", "debug", "info", "warn", "error"]>>, never>;
@@ -34,6 +46,6 @@ export interface LogEntry {
     readonly fiber: string;
     readonly traceId?: string;
     readonly spanId?: string;
-    readonly attrs: Record<string, unknown>;
+    readonly attrs: Record<string, Schema.Json>;
     readonly cause?: string;
 }

package/dist/internal/store/audit.d.ts

@@ -1,9 +1,15 @@
 import { Effect } from "effect";
+import type { RetrievalAuditRow } from "./models.ts";
 import { JobFailure, type Handler, type JobContext } from "./internal/workflow/index.js";
 import { Service as DbBackend } from "./db-backend.ts";
 import type { Interface as DbBackendInterface } from "./db-backend.ts";
+/** The decoded `audit.write` payload — mirrors the queue definition's
+ * schema (`{ rows }`); the executor decodes before calling. */
+export interface AuditWritePayload {
+    readonly rows: ReadonlyArray<RetrievalAuditRow>;
+}
 /** The `audit.write` handler shape (see queue.ts). */
-export type AuditWriteHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+export type AuditWriteHandler = (payload: AuditWritePayload, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
 /**
  * Factory for the `audit.write` job handler. Payload: `{ rows }` — one or
  * more `retrieval_log` rows enqueued by the store's `enqueueAudit` seam

package/dist/internal/store/db-backend.d.ts

@@ -54,12 +54,23 @@ export interface GraphNeighborsOptions {
     readonly maxNeighbors?: number;
     readonly maxTotal?: number;
     readonly includePending?: boolean;
+    /** Restrict traversal to these edge kinds (default: all). The common
+     * ask is memory-only navigation: pass the three `memory_*` kinds to
+     * keep the topic/concept legs out of the answer. */
+    readonly edgeKinds?: readonly string[];
     /** Optional scope for the topic legs of the view (topic edges are
      * model-scoped by PK). `undefined` unions every model's topic edges —
      * the intended default (topic edges are retrieval context regardless
      * of the model that wrote them). */
     readonly modelKey?: string;
 }
+/** Metadata filter keys for `queryByMetadata` — `topic` (LIKE on
+ * `$.topics`) and `sourceType` (equality on `$.sourceType`); unknown keys
+ * are ignored (see the SQL in libsql-backend). */
+export interface MetadataFilter {
+    readonly topic?: string;
+    readonly sourceType?: string;
+}
 export interface Interface {
     readonly runMigrations: () => Effect.Effect<void, StoreError>;
     /**
@@ -77,31 +88,58 @@ export interface Interface {
      * `limit` bounds the rows (0 = unbounded); `modelKey` optionally scopes
      * to the model's active population.
      */
-    readonly listIsolatedMemories: (limit: number, modelKey?: string) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
+    readonly listIsolatedMemories: (limit: number, modelKey?: string) => Effect.Effect<readonly unknown[], StoreError>;
     readonly db: DrizzleDB;
     readonly tables: StoreTables;
-    readonly ftsSearch: (query: string, namespace: string, limit: number, topicKeys?: ReadonlyArray<string>, modelKey?: string) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
-    readonly vectorSearch: (query: ReadonlyArray<number>, namespace: string, limit: number, model: EmbeddingModelConfig, topicKeys?: ReadonlyArray<string>) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
+    readonly ftsSearch: (query: string, namespace: string, limit: number, topicKeys?: ReadonlyArray<string>, modelKey?: string, contentType?: string | ReadonlyArray<string>, 
+    /** Include the 384-float `embedding` blob per row (default false —
+     * search results never need vectors; write paths read them via
+     * fetchMemoryVectors). */
+    includeEmbedding?: boolean) => Effect.Effect<readonly unknown[], StoreError>;
+    readonly vectorSearch: (query: ReadonlyArray<number>, namespace: string, limit: number, model: EmbeddingModelConfig, topicKeys?: ReadonlyArray<string>, contentType?: string | ReadonlyArray<string>, includeEmbedding?: boolean) => Effect.Effect<readonly unknown[], StoreError>;
     readonly sweep: (namespace: string) => Effect.Effect<SweepResult, StoreError>;
+    /** The DB's tables + columns (`dimple db-schema` surface). */
+    readonly listSchema: () => Effect.Effect<ReadonlyArray<{
+        readonly table: string;
+        readonly columns: ReadonlyArray<{
+            readonly name: string;
+            readonly type: string;
+        }>;
+    }>, StoreError>;
     /** Persist retrieval-audit rows (`retrieval_log`). Owned by the backend
      * so the `audit.write` job handler stays dialect-neutral. */
     readonly writeAuditRows: (rows: readonly RetrievalAuditRow[]) => Effect.Effect<void, StoreError>;
     /** Metadata-filtered memory lookup (the one
      * `json_extract` (SQLite) / `->` (PG) portability wart, now backend-owned
-     * like `ftsSearch`). Raw SQL, returns `Record<string, unknown>[]` — the
-     * store casts once at the boundary. Supported filter keys mirror the old
-     * store-level SQL exactly: `topic` (LIKE on `$.topics`) and `sourceType`
+     * like `ftsSearch`). Raw SQL, returns raw rows — the store casts once at
+     * the boundary. Supported filter keys mirror the old store-level SQL
+     * exactly: `topic` (LIKE on `$.topics`) and `sourceType`
      * (equality on `$.sourceType`); unknown keys are ignored. `limit` is
      * optional — omitted means no LIMIT. */
-    readonly queryByMetadata: (filter: Record<string, unknown>, limit?: number) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
-    readonly graphNeighbors: (kind: "memory" | "topic" | "concept", id: string, opts?: GraphNeighborsOptions) => Effect.Effect<readonly Record<string, unknown>[], StoreError>;
+    readonly queryByMetadata: (filter: MetadataFilter, limit?: number) => Effect.Effect<readonly unknown[], StoreError>;
+    readonly graphNeighbors: (kind: "memory" | "topic" | "concept", id: string, opts?: GraphNeighborsOptions) => Effect.Effect<readonly unknown[], StoreError>;
     readonly ensureVectorTable: (model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly insertVector: (memoryId: string, vector: ReadonlyArray<number>, model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
+    /** Batch variant of `insertVector` — one multi-row statement (bulk
+     * ingest: per-memory statements dominate the write path). */
+    readonly insertVectors: (entries: ReadonlyArray<{
+        readonly memoryId: string;
+        readonly vector: ReadonlyArray<number>;
+    }>, model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly deleteVector: (memoryId: string, dimensions: number) => Effect.Effect<void, StoreError>;
     readonly ensureTopicVectorTable: (model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly upsertTopicVector: (topicKey: string, sumVector: ReadonlyArray<number>, model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
+    /** Batch variant of `upsertTopicVector` — one multi-row statement (the
+     * bulk-routing path: sequential per-key upserts dominate batch ingest). */
+    readonly upsertTopicVectors: (entries: ReadonlyArray<{
+        readonly topicKey: string;
+        readonly sumVector: ReadonlyArray<number>;
+    }>, model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly deleteTopicVectors: (model: EmbeddingModelConfig) => Effect.Effect<void, StoreError>;
     readonly fetchTopicVectors: (model: EmbeddingModelConfig) => Effect.Effect<ReadonlyArray<TopicVectorRow>, StoreError>;
+    /** Single-row variant — the forget path's per-ancestor maintenance
+     * re-read the WHOLE table per level before (O(depth × N) decodes). */
+    readonly fetchTopicVector: (topicKey: string, model: EmbeddingModelConfig) => Effect.Effect<TopicVectorRow | undefined, StoreError>;
     readonly fetchMemoryVectors: (memoryIds: ReadonlyArray<string>, model: EmbeddingModelConfig) => Effect.Effect<ReadonlyArray<MemoryVectorRow>, StoreError>;
     readonly listMemoryIds: (model: EmbeddingModelConfig) => Effect.Effect<ReadonlyArray<string>, StoreError>;
 }

package/dist/internal/store/graph/candidates.d.ts

@@ -42,7 +42,7 @@ export interface CandidateMember {
     readonly metadata?: string | null;
 }
 /** Which rule produced a candidate (the provenance on `EdgeCandidate`). */
-export type CandidateKind = "near-duplicate" | "conflict-band" | "identity";
+export type CandidateKind = "near-duplicate" | "conflict-band" | "identity" | "rename";
 /** One rule-derived edge proposal from `leafLocalCandidates`. */
 export interface EdgeCandidate {
     readonly fromMemoryId: string;
@@ -81,6 +81,8 @@ export interface GraphCandidatesOptions {
     /** Max pending candidates returned (clamped to [1, 200]; default 50). */
     readonly limit?: number;
 }
+/** Cosine similarity of two vectors (equal-length; zero norm ⇒ 0). */
+export declare const cosineSimilarity: (a: Float32Array, b: Float32Array) => number;
 /**
  * The leaf-local candidate scan: compare the new memory against its
  * leaf-mates (per the module rules) and return at most one candidate per

package/dist/internal/store/graph/concepts.d.ts

@@ -78,10 +78,13 @@ export declare const farthestPointSeeds: (vectors: readonly Float32Array[], k: n
  * vectors themselves — the initial assignment is nearest-seed, not
  * seed-region).
  */
-export declare const kGroupLloyd: (vectors: readonly Float32Array[], seeds: readonly number[], passes: number) => {
-    groups: Uint32Array;
-    centroids: readonly Float32Array[];
-};
+/** Outcome of the k-means refinement — per-vector group assignment plus
+ * the final centroids. */
+export interface KGroupResult {
+    readonly groups: Uint32Array;
+    readonly centroids: readonly Float32Array[];
+}
+export declare const kGroupLloyd: (vectors: readonly Float32Array[], seeds: readonly number[], passes: number) => KGroupResult;
 /** Result of {@link clusterMembers}: per-vector group assignment + centroids. */
 export interface ClusterResult {
     /** `groups[i]` = the group of `vectors[i]` (caller index space). */
@@ -146,8 +149,14 @@ export interface ConceptClusterHandlerDeps {
     /** Backend captured at registration (see {@link topicSplitHandler}). */
     readonly backend?: DbBackendInterface;
 }
+/** The decoded `concept.cluster` payload — mirrors the queue definition's
+ * schema (`{ modelKey, topicKey? }`); the executor decodes before calling. */
+export interface ConceptClusterPayload {
+    readonly modelKey: string;
+    readonly topicKey?: string;
+}
 /** The `concept.cluster` handler shape (see jobs.ts). */
-export type ConceptClusterHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+export type ConceptClusterHandler = (payload: ConceptClusterPayload, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
 /**
  * Factory for the `concept.cluster` job handler. Two modes, selected by the
  * payload:

package/dist/internal/store/graph/dream.d.ts

@@ -145,8 +145,14 @@ export interface DreamHandlerDeps {
     /** Backend captured at registration (see {@link topicSplitHandler}). */
     readonly backend?: DbBackendInterface;
 }
+/** The decoded `memory.dream` payload — mirrors the queue definition's
+ * schema (`{ modelKey, runId? }`); the executor decodes before calling. */
+export interface DreamPayload {
+    readonly modelKey: string;
+    readonly runId?: string;
+}
 /** The `memory.dream` handler shape (see jobs.ts). */
-export type DreamHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+export type DreamHandler = (payload: DreamPayload, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
 /**
  * Factory for the `memory.dream` job handler. Payload: `{ modelKey }`.
  * Runs the four phases (orient → gather → consolidate → prune) for that

package/dist/internal/store/graph/repair.d.ts

@@ -64,7 +64,13 @@ export interface GraphRepairHandlerDeps {
     readonly expiredGraceMs?: number;
 }
 /** The `graph.repair` handler shape (see jobs.ts). */
-export type GraphRepairHandler = (payload: unknown, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
+/** The decoded `graph.repair` payload — mirrors the queue definition's
+ * schema (`{ modelKey, runId? }`); the executor decodes before calling. */
+export interface RepairPayload {
+    readonly modelKey: string;
+    readonly runId?: string;
+}
+export type GraphRepairHandler = (payload: RepairPayload, ctx: JobContext) => Effect.Effect<unknown, JobFailure, DbBackend>;
 /**
  * Factory for the `graph.repair` job handler. Payload: `{ modelKey }`.
  * Validates the model key, then runs the repair transaction: orphaned

package/dist/internal/store/graph/traversal.d.ts

@@ -36,4 +36,4 @@ export interface GraphNeighborRow extends Schema.Schema.Type<typeof GraphNeighbo
  * does not match — the backend owns the query, so a mismatch is a real bug,
  * not a runtime condition.
  */
-export declare const fromNeighborRows: (rows: readonly Record<string, unknown>[]) => readonly GraphNeighborRow[];
+export declare const fromNeighborRows: (rows: readonly unknown[]) => readonly GraphNeighborRow[];