@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/internal/local-agent/local-agent-capabilities.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What a local agent cannot do, answered without throwing.
+ *
+ * `SDKAgent` is one interface over two runtimes, and a local agent genuinely has no artifacts — the
+ * LSP finding this closes is that `downloadArtifact` rejected with `UnsupportedRunOperationError`
+ * and nothing let a caller ASK first. `supports`/`unsupportedReason` are that question, and they
+ * live here rather than on the class because the answer is a property of the RUNTIME, not of any
+ * particular agent instance: it needs no field, no lock and no session.
+ *
+ * Kept a module and not a static on the class so `local-agent.ts` carries one fewer concern; the
+ * class keeps two one-line delegations, which is the surface `SDKAgent` requires.
+ */
+import type { AgentOperation, SDKArtifact } from "../../types/sdk-agent.js";
+/** Whether the local runtime implements `operation`. */
+export declare function localAgentSupports(operation: AgentOperation): boolean;
+/** Why `operation` is unavailable, or `undefined` when it is available. */
+export declare function localAgentUnsupportedReason(operation: AgentOperation): string | undefined;
+/** A local agent has no artifacts, so the list is empty rather than an error. */
+export declare function localAgentListArtifacts(): Promise<SDKArtifact[]>;
+/**
+ * Downloading one IS an error, and a typed one — the asymmetry is deliberate. An empty list is a
+ * true answer about a local agent; a download is a request the runtime cannot honour, and
+ * `supports("downloadArtifact")` is how a caller finds that out without provoking the rejection.
+ */
+export declare function localAgentDownloadArtifact(): Promise<Buffer>;
+/**
+ * The four answers as one object, so a consumer imports one name.
+ *
+ * Not decoration: `local-agent.ts` sits against a 400-line budget and a four-name import block costs
+ * five lines there. It is also the shape this package already uses for a namespace of related
+ * functions — see the static-namespace convention in `tests/lint/static-namespace-names-its-product.test.ts`.
+ */
+export declare const localAgentCapabilities: {
+    readonly supports: typeof localAgentSupports;
+    readonly unsupportedReason: typeof localAgentUnsupportedReason;
+    readonly listArtifacts: typeof localAgentListArtifacts;
+    readonly downloadArtifact: typeof localAgentDownloadArtifact;
+};

package/dist/internal/local-agent/local-agent-dispatch.d.ts

@@ -6,11 +6,11 @@
  */
 import type { AgentDefinition, AgentOptions, ModelSelection } from "../../types/agent.js";
 import type { Run, SDKUserMessage, SendOptions } from "../../types/run.js";
-import type { MemoryToolSpec } from "../agent-loop/loop-types.js";
+import type { MemoryToolSpec } from "../agent-loop/types.js";
 import type { PersonalityPreset } from "../personality/types.js";
 import type { PluginManager } from "../plugins/manager.js";
 import type { HooksExecutor } from "../runtime/hooks/hooks-executor.js";
-import type { MemoryFact } from "../runtime/memory/memory-store.js";
+import type { MemoryFact } from "../runtime/memory-glue/memory-store.js";
 import { createRealLocalRun } from "./real-local-run.js";
 export interface DispatchInputs {
     agentId: string;

package/dist/internal/local-agent/local-agent-memory-provider.d.ts

@@ -25,7 +25,7 @@
  * @internal — sdk-core's bridging glue. Replaced by sdk-memory rich impl
  * in Stage 3.
  */
-import type { MemoryProvider } from "../runtime/memory/memory-provider.js";
+import type { MemoryProvider } from "../runtime/memory-glue/memory-provider.js";
 import type { TelemetryHandle } from "../telemetry/tracer.js";
 /**
  * Options for `createLocalAgentMemoryProvider`. Mirrors what

package/dist/internal/local-agent/local-agent-personality-extensions.d.ts

@@ -16,4 +16,28 @@
  *
  * @internal
  */
-export {};
+import { PersonalityRegistry } from "../personality/registry.js";
+import type { PersonalityStore } from "../personality/store.js";
+/**
+ * What `localAgentUsePersonality` needs from the agent — the narrow-target shape
+ * `LocalAgentDisposeTarget` established in `local-agent-lifecycle.ts`.
+ *
+ * It replaced an eleven-member args bag carrying TWO callbacks bound straight back to the caller's
+ * own members: `invalidateCache` and an `onRegistryLoaded` whose only job was to write
+ * `personalityRegistry` back. An extraction that hands its dependencies back as closures has
+ * relocated text without reducing coupling — the defect this file's own sibling avoids by taking
+ * the agent. `personalityRegistry` is mutable here on purpose: the lazy load assigns it directly,
+ * which is what the write-back callback was simulating.
+ *
+ * `disposed` is deliberately absent: the CALLER owns that flag and checks it, the same division
+ * `disposeLocalAgentSession` states — "the caller owns the `disposed` flag (idempotence guard)".
+ * Reaching into a private field to re-ask a question the caller already answered is what forced the
+ * bag to carry it.
+ */
+export interface LocalAgentPersonalityTarget {
+    readonly agentId: string;
+    readonly workspaceCwd: string;
+    readonly personalityStore: PersonalityStore;
+    personalityRegistry: PersonalityRegistry | undefined;
+    invalidateCache(reason: string): Promise<void>;
+}

package/dist/internal/local-agent/local-agent-send.d.ts

@@ -1 +1,42 @@
-export {};
+import type { SDKUserMessage, SendOptions } from "../../types/run.js";
+import type { MemoryToolSpec } from "../agent-loop/types.js";
+import type { MemoryProvider } from "../runtime/memory-glue/memory-provider.js";
+import type { MemoryFact } from "../runtime/memory-glue/memory-store.js";
+/**
+ * What one send needs assembled into a system prompt. The port took the same five values
+ * positionally, so the binding in `LocalAgent` read `(ut, bp, mf, ams, cp) => …` — five
+ * abbreviations relaying into a six-argument helper call.
+ */
+export interface SendAssemblyRequest {
+    readonly userText: string;
+    readonly baseSystemPrompt: string | undefined;
+    readonly memoryFacts: ReadonlyArray<MemoryFact>;
+    readonly activeMemorySummary: string | undefined;
+    readonly contextPaths: readonly string[] | undefined;
+}
+/**
+ * The arguments of one dispatch, as a record.
+ *
+ * They were seven positional parameters declared TWICE — here and on `LocalAgent.dispatchRun` — kept
+ * in step by hand behind a `jscpd:ignore` pair, and relayed by
+ * `(msg, o, sp, mf, pm, mt, mp) => this.dispatchRun(msg, o, sp, mf, pm, mt, mp)`. The abbreviations
+ * were not carelessness: the arrow is one line because of the 400-LoC file budget, and a one-line
+ * arrow has no room for real names. `pm` there is `priorMessages` while `pm` in a sibling lambda two
+ * declarations up is `pluginManager`.
+ *
+ * One named type: the relay becomes `(args) => this.dispatchRun(args)`, which fits on one line
+ * without abbreviating anything, and the duplicate declaration — with the suppression that hid it —
+ * is gone.
+ */
+export interface DispatchRunArgs {
+    readonly message: string | SDKUserMessage;
+    readonly options: SendOptions;
+    readonly systemPrompt: string | undefined;
+    readonly memoryFacts: ReadonlyArray<MemoryFact>;
+    readonly priorMessages: ReadonlyArray<{
+        role: "user" | "assistant";
+        text: string;
+    }>;
+    readonly memoryTools: ReadonlyArray<MemoryToolSpec> | undefined;
+    readonly memoryProviderOverride?: MemoryProvider | undefined;
+}

package/dist/internal/local-agent/real-local-run-mcp.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The MCP client pool behind `mcpLifecycle: 'session'`, and who owns a run's clients.
+ *
+ * MOVED HERE 2026-09-02 from `real-local-run.ts`. It is a process-wide resource with its own
+ * lifecycle rules — acquisition, idle reaping, per-session disposal — living inside a file whose
+ * other five concerns were about assembling one run. Ownership (`runOwnsMcpClients`) is derived in
+ * ONE place so `buildMcpMap` and the run's `finally` cannot disagree about who releases a client;
+ * keeping that guarantee is the reason the two functions travel together.
+ *
+ * @internal
+ */
+import { type McpClient } from "../mcp/client.js";
+import type { CreateRealLocalRunOptions } from "./real-local-run-options.js";
+/** M77 — release one session's pooled MCP clients. Called from `LocalAgent.dispose()`. */
+export declare function disposeSessionMcpClients(agentId: string): void;
+/**
+ * theokit#155 — does THIS RUN own the MCP clients it was handed?
+ *
+ * Under the default `'run'` lifecycle the client is built for this send and dies with it, so the
+ * run closes it. Under `'session'` the pool owns it: closing it at the end of the turn SIGTERMs the
+ * child process, and the next turn spawns a new one — which is exactly why the option measured
+ * 0 ms of savings. Ownership is derived here, once, so `buildMcpMap` and the run's `finally` cannot
+ * disagree about who releases the resource.
+ */
+export declare function runOwnsMcpClients(agentOptions: AgentOptions): boolean;
+export declare function buildMcpMap(options: CreateRealLocalRunOptions): Map<string, McpClient>;

package/dist/internal/local-agent/real-local-run-options.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What one local run is built from.
+ *
+ * Its own module because `real-local-run.ts` and the two files split out of it —
+ * `real-local-run-provider.ts` and `real-local-run-mcp.ts` — all take it, and having any of them own
+ * it makes the other two import back into it. madge caught exactly that: the first version of the
+ * split put the interface in `real-local-run.ts` and produced a `provider -> run -> provider` pair.
+ *
+ * A type-only cycle erases at compile and breaks no build, but it is the same design statement in
+ * the wrong direction as any other, and this repo has a rule about it (`.dependency-cruiser.cjs`
+ * G7a, and `types/agent-prims.ts`, which exists for the identical reason).
+ *
+ *
+ * `SessionMessage` comes from `types/session-message.ts` and NOT from the `internal/session/` barrel:
+ * that barrel reaches back here through `compact-session.ts`, and madge reported the loop the moment
+ * this file existed. Importing the declaring module instead of the barrel is the cheaper half of the
+ * same lesson `types/agent-prims.ts` records.
+ *
+ * NAMED `-options` RATHER THAN `-types`: `tests/lint/types-module-naming.test.ts` refuses a
+ * `X-types.ts` in a folder with no bare `types.ts` to distinguish it from, on the grounds that the
+ * prefix then carries no information. The gate caught this file on its first commit, which is what
+ * it is for.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/local-agent/real-local-run-tools.d.ts

@@ -11,7 +11,7 @@
  * @internal
  */
 import type { AgentDefinition, AgentOptions, BuiltinToolName, CustomTool, ModelSelection } from "../../types/agent.js";
-import type { CustomToolSpec } from "../agent-loop/loop-types.js";
+import type { CustomToolSpec } from "../agent-loop/types.js";
 /**
  * Resolve the tool-catalog slice of `AgentLoopInputs` for this run: which custom tools the loop
  * declares, and which SDK builtins it must NOT.
@@ -29,10 +29,27 @@ import type { CustomToolSpec } from "../agent-loop/loop-types.js";
  *
  * Note the two halves are independent: an agent with no custom tools at all can still withhold a
  * builtin, so the "no tools" early return carries the withhold list out with it.
+ *
+ * ONE options record rather than eight positional parameters. Five of the eight were optional or
+ * nullable in adjacent slots — `ReadonlyArray<string> | undefined`, `string`, `string | undefined`,
+ * `Record | undefined`, `ModelSelection | undefined` — compatible enough that transposing two of
+ * them compiled. The single call site was already destructuring the same `CreateRealLocalRunOptions`
+ * value field by field, so the parameter list was re-deriving a record the caller held.
  */
-export declare function buildRunToolCatalogInput(agentOptions: AgentOptions, sendOptions: {
-    tools?: CustomTool[];
-} | undefined, pluginManager: import("../plugins/manager.js").PluginManager | undefined, personalityToolWhitelist: ReadonlyArray<string> | undefined, agentId: string, personalityName: string | undefined, subagents: Record<string, AgentDefinition> | undefined, effectiveModel: ModelSelection | undefined): {
+export interface RunToolCatalogInputs {
+    readonly agentOptions: AgentOptions;
+    readonly sendOptions: {
+        tools?: CustomTool[];
+    } | undefined;
+    readonly pluginManager: import("../plugins/manager.js").PluginManager | undefined;
+    readonly personalityToolWhitelist: ReadonlyArray<string> | undefined;
+    readonly agentId: string;
+    readonly personalityName: string | undefined;
+    readonly subagents: Record<string, AgentDefinition> | undefined;
+    /** The per-send override applied, NOT `agentOptions.model` — they differ on an override. */
+    readonly effectiveModel: ModelSelection | undefined;
+}
+export declare function buildRunToolCatalogInput({ agentOptions, sendOptions, pluginManager, personalityToolWhitelist, agentId, personalityName, subagents, effectiveModel, }: RunToolCatalogInputs): {
     customTools?: ReadonlyArray<CustomToolSpec>;
     withheldBuiltinTools?: ReadonlyArray<BuiltinToolName>;
 };

package/dist/internal/local-agent/real-local-run.d.ts

@@ -1,4 +1,4 @@
 import type { Run } from "../../types/run.js";
+export type { CreateRealLocalRunOptions } from "./real-local-run-options.js";
+import type { CreateRealLocalRunOptions } from "./real-local-run-options.js";
 export declare function createRealLocalRun(options: CreateRealLocalRunOptions): Run;
-/** M77 — release one session's pooled MCP clients. Called from `LocalAgent.dispose()`. */
-export declare function disposeSessionMcpClients(agentId: string): void;

package/dist/internal/mcp/handshake-timeout.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Which deadline applies to one MCP call.
+ *
+ * Extracted from `BaseMcpClient.timeoutFor` — where it was a private method, and therefore only
+ * reachable through integration tests that spawn child processes and race a hand-picked millisecond
+ * count against the cost of starting Node. It is a pure function of three values and now says so.
+ *
+ * @internal
+ */
+/**
+ * Floor for the `initialize` handshake, whatever `requestTimeoutMs` says.
+ *
+ * Sized against what the handshake actually pays for — spawning a child process and waiting for a
+ * server to come up — rather than against a steady-state RPC.
+ */
+export declare const HANDSHAKE_FLOOR_MS = 10000;
+export interface HandshakeTimeoutInput {
+    /** The JSON-RPC method about to be sent. */
+    readonly method: string;
+    /** Whether the client is inside its own reconnect cycle. */
+    readonly reconnecting: boolean;
+    /** The caller's `requestTimeoutMs`, already defaulted. */
+    readonly requestTimeoutMs: number;
+}
+/**
+ * The deadline for one RPC. The reconnect handshake gets a floor; everything else gets
+ * `requestTimeoutMs`.
+ *
+ * `requestTimeoutMs` sizes a STEADY-STATE request. `initialize` is not one — it is preceded by a
+ * process spawn and the server's own startup, and the caller who set a tight request budget was
+ * sizing latency, not process creation. Binding both to that number made a tight budget silently
+ * unable to CONNECT, and worse, unable to RECONNECT: `reconnect()` spawns a fresh child and calls
+ * `initialize()`, so every one of its attempts tried to fit a spawn into a steady-state budget,
+ * exhausted the loop and surfaced `mcp_disconnected` — precisely the wedge the bounded-retry loop
+ * exists to prevent.
+ *
+ * A FLOOR, not a replacement: a caller who deliberately sets a LARGER request timeout keeps it.
+ * That clause was prose until 2026-09-02 — `Math.max` could have been a bare `HANDSHAKE_FLOOR_MS`
+ * and all three integration tests stayed green. `tests/internal/mcp/handshake-timeout.test.ts` is
+ * the oracle for it now.
+ *
+ * SCOPED TO THE RECONNECT HANDSHAKE, not to the first connect, and the difference is which failure
+ * is visible. A caller whose `requestTimeoutMs` is too small to connect at ALL finds out
+ * immediately, at the call they made, and that is their explicit choice to correct — an existing
+ * test pins it (`client-timeout.test.ts`: a silent server rejects within 2s at 150ms, and a floor on
+ * first connect would make it wait the floor instead). The reconnect is the SDK's own recovery,
+ * which the caller never sized and never sees until a drop happens.
+ *
+ * A floor on every METHOD would also be wrong for a third reason: it would turn `requestTimeoutMs`
+ * into a suggestion, which is a worse defect than the one it fixes. Both halves of the condition
+ * matter — the method AND the flag — so an ordinary call mid-reconnect keeps the caller's budget.
+ */
+export declare function handshakeAwareTimeout(input: HandshakeTimeoutInput): number;

package/dist/internal/memory/active-memory.d.ts

@@ -1,4 +1,4 @@
-import type { CircuitBreaker } from "../resilience/circuit-breaker.js";
+import type { CircuitBreaker } from "../retry/circuit-breaker.js";
 import { type TelemetryHandle } from "../telemetry/tracer.js";
 import type { ActiveMemoryCache } from "./active-memory-cache.js";
 import type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus } from "./active-memory-types.js";

package/dist/internal/memory/adapters/index.cjs

@@ -1,22 +1,22 @@
 'use strict';
 
-var chunkKQ7TS7WW_cjs = require('../../../chunk-KQ7TS7WW.cjs');
+var chunkD6POWE7E_cjs = require('../../../chunk-D6POWE7E.cjs');
 var chunkGHX4P3V2_cjs = require('../../../chunk-GHX4P3V2.cjs');
-require('../../../chunk-UGT7GK7I.cjs');
+require('../../../chunk-24SYBZPL.cjs');
+require('../../../chunk-QOGNZMHD.cjs');
 require('../../../chunk-MUUQ2WFJ.cjs');
-require('../../../chunk-V2BOS4WF.cjs');
-require('../../../chunk-VKJ7V7EB.cjs');
-require('../../../chunk-ZSWPZ23K.cjs');
-require('../../../chunk-XWTLIGO3.cjs');
-require('../../../chunk-4ZHTIJNE.cjs');
-require('../../../chunk-XL7Q7HB2.cjs');
-require('../../../chunk-EG4QM7ZJ.cjs');
+require('../../../chunk-7A6535RA.cjs');
+require('../../../chunk-SA6K24NB.cjs');
+require('../../../chunk-I2PWY7VM.cjs');
+require('../../../chunk-KTTHHYEW.cjs');
+require('../../../chunk-J7J7J2GN.cjs');
+require('../../../chunk-6LHQPOMI.cjs');
 
 
 
 Object.defineProperty(exports, "createOpenAiCompatibleRuntime", {
   enumerable: true,
-  get: function () { return chunkKQ7TS7WW_cjs.createOpenAiCompatibleRuntime; }
+  get: function () { return chunkD6POWE7E_cjs.createOpenAiCompatibleRuntime; }
 });
 Object.defineProperty(exports, "LruEmbeddingCache", {
   enumerable: true,

package/dist/internal/memory/adapters/index.js

@@ -1,13 +1,13 @@
-export { createOpenAiCompatibleRuntime } from '../../../chunk-UBDMVMBZ.js';
+export { createOpenAiCompatibleRuntime } from '../../../chunk-55GB6JYQ.js';
 export { LruEmbeddingCache, globalEmbeddingCache } from '../../../chunk-H73MEMQB.js';
-import '../../../chunk-7YGCPMGB.js';
+import '../../../chunk-XB4GI5RZ.js';
+import '../../../chunk-24MGQDK3.js';
 import '../../../chunk-FD2UT76F.js';
-import '../../../chunk-HS7AVXTF.js';
-import '../../../chunk-RIAM53CP.js';
-import '../../../chunk-C72AZW7J.js';
-import '../../../chunk-4QZSA2HJ.js';
-import '../../../chunk-ZZMZWBR6.js';
-import '../../../chunk-D4CUGAKZ.js';
-import '../../../chunk-XEQ3TM66.js';
+import '../../../chunk-EH6XD3FY.js';
+import '../../../chunk-UKMBRMGT.js';
+import '../../../chunk-4MMWFSCD.js';
+import '../../../chunk-G7BLGBRN.js';
+import '../../../chunk-ALUN2B4W.js';
+import '../../../chunk-CZJ6Q7CW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/internal/memory/adapters/openai-embedding.d.cts

@@ -1,2 +1,12 @@
 import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+/**
+ * Vector width per OpenAI embedding model.
+ *
+ * Exported because Azure OpenAI HOSTS these same models, so the Azure adapter was carrying a
+ * byte-identical copy — and this table is a correctness gate, not a hint:
+ * `createOpenAiCompatibleRuntime` throws `embedding_unknown_model` for anything absent, and a wrong
+ * number produces a vec0 dimension mismatch that surfaces much later. Two copies meant adding the
+ * next model to one file silently broke the other provider.
+ */
+export declare const OPENAI_EMBEDDING_DIMENSIONS: Readonly<Record<string, number>>;
 export declare const openAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/openai-embedding.d.ts

@@ -1,2 +1,12 @@
 import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+/**
+ * Vector width per OpenAI embedding model.
+ *
+ * Exported because Azure OpenAI HOSTS these same models, so the Azure adapter was carrying a
+ * byte-identical copy — and this table is a correctness gate, not a hint:
+ * `createOpenAiCompatibleRuntime` throws `embedding_unknown_model` for anything absent, and a wrong
+ * number produces a vec0 dimension mismatch that surfaces much later. Two copies meant adding the
+ * next model to one file silently broke the other provider.
+ */
+export declare const OPENAI_EMBEDDING_DIMENSIONS: Readonly<Record<string, number>>;
 export declare const openAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/corpus-sync.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The corpus walk: read every markdown file under the memory root, and re-chunk the ones that
+ * changed.
+ *
+ * One of the four concerns that shared `IndexManager`, and the one with the most distinct reason to
+ * change — "which files are in the corpus and when is one stale" is a question about the filesystem,
+ * not about search or about the schema. It takes a {@link MemoryIndexRepository} rather than a
+ * database, so it cannot reach past it into SQL.
+ *
+ * The staleness test is the content hash, NOT the mtime. mtime is written into `files` for
+ * observability; a file touched without being edited must not cost a re-chunk, and a file restored
+ * from a backup with an older mtime must not be skipped.
+ *
+ * @internal
+ */
+import type { MemoryIndexRepository } from "./index-repository.js";
+import type { MemoryRoot } from "./storage/memory-root.js";
+export interface CorpusSyncCounts {
+    readonly filesScanned: number;
+    readonly filesUpdated: number;
+    readonly chunksWritten: number;
+}
+export declare function syncCorpus(repo: MemoryIndexRepository, memoryRoot: MemoryRoot): Promise<CorpusSyncCounts>;

package/dist/internal/memory/index-db.d.ts

@@ -24,7 +24,21 @@ export interface MemoryDb {
         simple?: boolean;
     }): unknown;
     close(): void;
-    /** Load a SQLite loadable extension at the given path (used by sqlite-vec). */
+    /**
+     * Load a SQLite loadable extension at the given path.
+     *
+     * NOTHING IN THIS PACKAGE CALLS IT, and it is not dead. The caller is the `sqlite-vec` package:
+     * `loadSqliteVecExtension` hands it this handle and its `load()` does
+     * `db.loadExtension(getLoadablePath())` (sqlite-vec@0.1.9 index.mjs:44). An audit read the absent
+     * in-repo call site as "dead surface that only exists to be refused" and recommended deleting the
+     * member — which would have removed the contract a third-party library depends on. Saying who
+     * calls it is what makes that reading impossible next time.
+     *
+     * On the `node:sqlite` fallback the adapter's Proxy answers with a throwing stub, and that is also
+     * deliberate: the throw is caught by `loadSqliteVecExtension` and becomes a
+     * `ConfigurationError` with code `sqlite_vec_unavailable`, so the bare `Error` never escapes to a
+     * consumer. The stub's message is what ends up as that error's cause.
+     */
     loadExtension(path: string): void;
 }
 export interface OpenDbOptions {

package/dist/internal/memory/index-manager-contract.d.ts

@@ -5,6 +5,18 @@ export interface IndexStatus {
     filesIndexed: number;
     chunksIndexed: number;
     lastSyncMs?: number;
+    /**
+     * Whether `filesIndexed` / `chunksIndexed` were MEASURED, or are placeholders.
+     *
+     * `IndexManager` counts rows with `SELECT COUNT(*)` and reports `true`. `LanceMemoryAdapter`
+     * reports `false`: its backing store is async and `status()` is not, so it hardcoded zeros while
+     * claiming `backend: "hybrid"` — and a caller deciding "is the index populated?" from
+     * `chunksIndexed > 0` got a false negative on every run, however many rows the table held.
+     *
+     * The zeros stay zero. Inventing a count would trade one false claim for another; what this flag
+     * fixes is a caller reading a placeholder as a measurement.
+     */
+    countsExact: boolean;
 }
 export interface SearchOptions {
     maxResults?: number;

package/dist/internal/memory/index-manager.d.ts

@@ -1,3 +1,4 @@
+import type { SyncResult } from "./memory-index.js";
 import { type MemoryIndex } from "./memory-index.js";
 import type { IndexStatus, MemorySearchHit, OpenIndexOptions, SearchOptions } from "./index-manager-contract.js";
 export declare class IndexManager implements MemoryIndex {
@@ -6,6 +7,8 @@ export declare class IndexManager implements MemoryIndex {
     private readonly embedding;
     private lastSyncMs;
     private vectorReady;
+    /** Every SQL string this class used to hold. See `index-repository.ts` for why it moved. */
+    private readonly repo;
     private constructor();
     /**
      * Open a memory index. Dispatches to SQLite (default) or Lance (opt-in
@@ -22,12 +25,7 @@ export declare class IndexManager implements MemoryIndex {
     private static openSqliteInternal;
     private initVectorBackend;
     /** Walk the memory corpus + (re)index changed files. */
-    sync(): Promise<{
-        filesScanned: number;
-        filesUpdated: number;
-        chunksWritten: number;
-        chunksEmbedded: number;
-    }>;
+    sync(): Promise<SyncResult>;
     search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
     status(): IndexStatus;
     private ftsSearch;
@@ -42,9 +40,5 @@ export declare class IndexManager implements MemoryIndex {
     private combineHybridScores;
     private mergeHits;
     private fetchChunksByIds;
-    private loadFilesIndex;
-    private upsertFile;
-    private deleteChunksForFile;
-    private insertChunk;
     close(): void;
 }

package/dist/internal/memory/index-repository.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Every SQL string the memory index runs, in one place.
+ *
+ * `IndexManager` answered four questions with four independent reasons to change: the corpus walk,
+ * the BM25-to-score normalisation, the vector-cache strategy, and the schema. This is the fourth.
+ * Changing a column, an index or a join is now a change to THIS file, and the caller above it reads
+ * as search logic rather than as SQL with scoring in between.
+ *
+ * The row-to-`MemorySearchHit` mapping deliberately stays with the caller: turning a row into a hit
+ * involves a score, a snippet and a citation, none of which the schema knows about. Keeping it here
+ * would move the normalisation into the repository and re-create the same mixture one layer down.
+ *
+ * Rows come back as `Record<string, unknown>` for the same reason: the repository knows what it
+ * SELECTed, not what the caller will make of it.
+ *
+ * @internal
+ */
+/** What `files` holds for one path — the pair the corpus walk compares against disk. */
+export interface FileRow {
+    readonly id: number;
+    readonly hash: string;
+}
+export declare class MemoryIndexRepository {
+    private readonly db;
+    constructor(db: MemoryDb);
+    counts(): {
+        files: number;
+        chunks: number;
+    };
+    /**
+     * FTS5 match, ordered by bm25. THROWS on an FTS5 error rather than swallowing it — whether that
+     * error means "CJK input the default tokenizer cannot segment" or "the table is missing" is a
+     * judgement the caller makes, and it makes it differently for each.
+     */
+    ftsRows(sanitizedQuery: string, limit: number): Array<Record<string, unknown>>;
+    /** Substring scan — the CJK fallback. No relevance score exists here; the caller supplies one. */
+    likeRows(escapedPattern: string, limit: number): Array<Record<string, unknown>>;
+    /** Hydrate the chunks a vector search returned by id. Empty in, empty out — no query runs. */
+    chunkRowsByIds(ids: ReadonlyArray<number>): Array<Record<string, unknown>>;
+    /** Absolute path → its row, for the corpus walk to compare hashes against disk. */
+    filesByPath(): Map<string, FileRow>;
+    upsertFile(file: {
+        absPath: string;
+        relPath: string;
+        hash: string;
+        mtimeMs: number;
+        source: "memory" | "wiki" | "sessions";
+    }): number;
+    deleteChunksForFile(fileId: number): void;
+    insertChunk(chunk: {
+        fileId: number;
+        startLine: number;
+        endLine: number;
+        text: string;
+        hash: string;
+    }): void;
+    close(): void;
+}

package/dist/internal/memory/lance-memory-adapter.d.ts

@@ -7,15 +7,22 @@
  * Semantic deltas vs SQLite (documented so callers know what to expect):
  *
  *  - `sync()` is a NO-OP. Lance is a pure vector store — there is no
- *    markdown corpus to crawl. Returns zero counts. Consumers writing
- *    facts use `LanceIndex.addFacts` directly (exposed via the index
- *    object returned to advanced callers).
- *  - `search()` performs vector-only retrieval. `MemorySearchHit.textScore`
- *    is undefined (no FTS5 layer); `vectorScore === score`.
+ *    markdown corpus to crawl. It returns zero counts with `supported: false`
+ *    so the result is not mistaken for a sync that found nothing. Consumers
+ *    writing facts hold a `LanceIndex` and call `addFacts` on it; the adapter
+ *    does not hand its adaptee out.
+ *  - `search()` is HYBRID, not vector-only. Lance supplies the vector distance
+ *    and `translateLanceHit` adds a client-side term-overlap ratio (T4.5), so
+ *    `textScore` is a real number in 0..1 and `score` is `0.7 * vectorScore +
+ *    0.3 * textScore` — never `=== vectorScore`. This block said the opposite
+ *    for as long as T4.5 has been shipped, while the docblock 90 lines below
+ *    described the change correctly, so the two halves of one file disagreed
+ *    and the header is the half a caller reads.
  *  - `status()` reports `backend: "hybrid"` only when an embedding runtime
  *    is wired (always the case for Lance — embedding is required at open).
- *    `chunksIndexed` reflects total Lance row count; `filesIndexed` is 0
- *    because Lance does not track file provenance per-row.
+ *    Both counts are 0 with `countsExact: false`: the port declares `status()`
+ *    synchronous and Lance's row count is async, so nothing can be measured
+ *    here. The zeros are placeholders and the flag says which.
  *
  * Ships with the lancedb-backend-ship-v1-1 plan (close D12, supersede via
  * D43). v1.4.0 of `@theokit/sdk`.
@@ -28,16 +35,11 @@ export declare class LanceMemoryAdapter implements MemoryIndex {
     private readonly inner;
     constructor(inner: LanceIndex);
     /**
-     * No-op for Lance — see file header. Returns zero counts so callers'
-     * existing logging (`filesScanned: X`) does not break.
+     * Not applicable to Lance — see file header. Returns zero counts with `supported: false` so a
+     * caller can distinguish this from a real sync that found nothing.
      */
     sync(): Promise<SyncResult>;
     search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
     status(): IndexStatus;
     close(): Promise<void>;
-    /**
-     * Escape hatch for advanced callers (migration tool, benchmark script)
-     * that need direct access to addFacts/countFacts/removeFacts.
-     */
-    unwrap(): LanceIndex;
 }

package/dist/internal/memory/memory-index.d.ts

@@ -21,6 +21,21 @@ export interface SyncResult {
     filesUpdated: number;
     chunksWritten: number;
     chunksEmbedded: number;
+    /**
+     * Whether this backend actually walked a corpus.
+     *
+     * REQUIRED, not optional, and that is the point. `MemoryIndex` has two implementers and consumers
+     * hold the interface: `IndexManager` walks files, and `LanceMemoryAdapter` has no corpus to walk —
+     * it is a vector store fed by explicit `addFacts`. The adapter used to answer with a frozen
+     * all-zeros result, which a caller cannot tell apart from a real sync that found nothing to do.
+     * The comment above it stated that as the intention ("so callers' existing logging does not
+     * break"), which is the substitution defect written down as a feature.
+     *
+     * A required boolean forces every implementer to say which case it is in, and forces the compiler
+     * to notice a new implementer that forgot. An optional flag would have let the next backend
+     * reproduce the silence.
+     */
+    supported: boolean;
 }
 /**
  * Common search-options parser used by both `IndexManager.search` and