@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/db-manager.d.ts

@@ -1,10 +1,9 @@
 /**
  * MAMA Database Manager (SQLite-only)
  *
- * SQLite-exclusive database interface for MAMA Plugin.
- * Uses better-sqlite3 for local storage.
+ * SQLite-exclusive database interface. Uses better-sqlite3 for local storage.
  *
- * PostgreSQL support is only available in the legacy mcp-server repository.
+ * There is no PostgreSQL path.
  *
  * Features:
  * - WAL mode for better concurrency
@@ -17,17 +16,44 @@
  * @date 2026-02-01
  * @source-of-truth packages/mama-core/src/db-manager.js (mama-core)
  */
+export { assertTestProcessIsNotUsingRealDb, clearProductionDatabasePaths, declareProductionDatabasePath, isTestMode, } from './storage/database.js';
+export { openDatabase } from './storage/database.js';
+export type { DatabaseHandle, OpenDatabaseOptions } from './storage/database.js';
 import type { PreparedStatement } from './db-adapter/statement.js';
 export type { PreparedStatement };
+/**
+ * What a module needs to read and write rows.
+ *
+ * Measured 2026-09-15: outside the three files that own the database
+ * (db-adapter/, db-manager.ts, storage/database.ts), consumers call `prepare`
+ * 255 times, `transaction` 26 and `transactionImmediate` 4. They call `connect`,
+ * `disconnect`, `runMigrations`, `reloadVectorCache`, `getDbPath` and `dbPath`
+ * zero times. `exec` stays because a caller's memoryDb shim issues DDL
+ * through it. Handing every store the lifetime and vector surface coupled 45
+ * modules to a contract they never use; this is that contract minus what they
+ * never touched.
+ */
 export interface DatabaseAdapter {
-    connect: () => unknown;
-    disconnect: () => void;
-    runMigrations: (dir: string) => void;
     prepare: (sql: string) => PreparedStatement;
+    exec: (sql: string) => void;
     transaction: <T>(fn: () => T) => T;
+    transactionImmediate?: <T>(fn: () => T) => T;
+}
+/**
+ * The whole adapter: rows plus lifetime, vector storage and identification.
+ *
+ * Five files need it - the implementation, the lifetime owner, the lifetime
+ * holder, and the two knowledge modules that write and search vectors.
+ */
+export interface DatabaseInstance extends DatabaseAdapter {
+    connect: () => unknown;
+    disconnect: () => void;
+    runMigrations: (sources: string | ReadonlyArray<{
+        name: string;
+        dir: string;
+    }>) => void;
     insertEmbedding: (rowid: number, embedding: Float32Array | number[]) => void;
-    vectorSearch: (embedding: Float32Array | number[], limit: number, topicPrefix?: string, excludeStatuses?: readonly string[]) => Promise<VectorSearchResult[] | null> | VectorSearchResult[] | null;
-    vectorSearchEnabled: boolean;
+    vectorSearch: (embedding: Float32Array | number[], limit: number, topicPrefix?: string, excludeStatuses?: readonly string[], kind?: string | [string, ...string[]]) => Promise<VectorSearchResult[] | null> | VectorSearchResult[] | null;
     reloadVectorCache?: () => void;
     refreshDecisionStatusCache?: (rowid: number) => void;
     getDbPath?: () => string;
@@ -68,13 +94,6 @@ export interface OutcomeData {
     duration_days?: number | null;
     confidence?: number | null;
 }
-export interface VectorSearchParams {
-    query: string;
-    limit?: number;
-    threshold?: number;
-    timeWindow?: number;
-    includeSuperseded?: boolean;
-}
 export interface DecisionEdgeRow {
     from_id: string;
     to_id: string;
@@ -118,15 +137,20 @@ export interface SemanticEdges {
  * vectors exist, cosine search would be non-discriminative, so we throw with the exact
  * re-embed command instead of silently serving degraded results. No-fallback by design.
  */
-export declare function assertEmbeddingSchemeCurrent(adapter: DatabaseAdapter): void;
-export declare function initDB(): Promise<unknown>;
-export declare function assertTestProcessIsNotUsingRealDb(effectivePath?: string, effectivePathSource?: string): void;
+export declare function assertEmbeddingSchemeCurrent(adapter: DatabaseInstance): void;
+export declare function initDB(options?: {
+    /** Migrations this consumer brings of its own, run after the core's. */
+    migrations?: ReadonlyArray<{
+        name: string;
+        dir: string;
+    }>;
+}): Promise<unknown>;
 /**
  * Get database connection (singleton pattern)
  *
  * Returns better-sqlite3 Database instance
  *
- * Note: Synchronous for backward compatibility with memory-store.js
+ * Note: Synchronous because callers assume a resolved adapter, not a promise.
  * Will throw if database not initialized
  *
  * @returns SQLite database connection
@@ -139,34 +163,20 @@ export declare function getDB(): unknown;
  *
  * @returns Adapter instance
  */
-export declare function getAdapter(): DatabaseAdapter;
+export declare function getAdapter(): DatabaseInstance;
+export declare function buildMemoryScopeId(kind: string, externalId: string): string;
 /**
  * Close database connection
  *
  * Call this on process exit
  */
 export declare function closeDB(): Promise<void>;
-export declare function ensureMemoryScope(kind: string, externalId: string): Promise<string>;
 /**
- * Insert embedding into vector search table
- *
- * Stores embedding in the embeddings table for vector similarity search
- *
- * @param decisionRowid - SQLite rowid
- * @param embedding - 1024-dim embedding vector
+ * The single write boundary for memory_scopes. Callers inside a transaction
+ * pass their adapter through; the public wrapper resolves the global adapter
+ * for the call sites that predate the adapter-taking boundary.
  */
-export declare function insertEmbedding(decisionRowid: number, embedding: Float32Array | number[]): Promise<void>;
-/**
- * Perform vector similarity search
- *
- * Returns empty array if vector search not available (no keyword fallback)
- *
- * @param queryEmbedding - Query embedding (1024-dim)
- * @param limit - Max results to return (default: 5)
- * @param threshold - Minimum similarity threshold (default: 0.7)
- * @returns Array of decisions with similarity scores, or empty array
- */
-export declare function vectorSearch(queryEmbedding: Float32Array | number[], limit?: number, threshold?: number, topicPrefix?: string, excludeStatuses?: readonly string[]): Promise<DecisionRecord[]>;
+export declare function ensureMemoryScope(adapter: DatabaseAdapter, kind: string, externalId: string): string;
 /**
  * Decision input for storage
  */
@@ -208,45 +218,10 @@ export interface DecisionInput {
     source_refs_json?: string | null;
     provenance_json?: string | null;
 }
-/**
- * Insert decision with embedding
- *
- * Combined operation: Insert decision + Generate embedding + Insert embedding
- * SQLite-only implementation
- *
- * @param decision - Decision object
- * @returns Decision ID
- */
-export declare function insertDecisionWithEmbedding(decision: DecisionInput): Promise<string>;
-/**
- * Query decision graph for topic
- *
- * Recursive CTE to traverse supersedes chain
- * SQLite implementation using WITH RECURSIVE
- *
- * @param topic - Decision topic to query
- * @returns Array of decisions (ordered by recency)
- */
-export declare function queryDecisionGraph(topic: string): Promise<DecisionRecord[]>;
-/**
- * Query semantic edges for a list of decisions
- *
- * Returns both outgoing (from_id) and incoming (to_id) edges
- * for refines and contradicts relationships
- *
- * @param decisionIds - Decision IDs to query edges for
- * @returns Categorized edges
- */
-export declare function querySemanticEdges(decisionIds: string[]): Promise<SemanticEdges>;
-/**
- * Query vector search with time window and threshold
- *
- * Story 014.14: AC #1 - Vector Search for Related Decisions
- *
- * @param params - Search parameters
- * @returns Results with similarity scores and decision data
- */
-export declare function queryVectorSearch(params: VectorSearchParams): Promise<DecisionRecord[]>;
+/** Generate the optional vector before opening a synchronous SQLite transaction. */
+export declare function prepareDecisionEmbedding(decision: DecisionInput): Promise<Float32Array | null>;
+/** Insert one decision and its already-prepared vector inside the caller's transaction. */
+export declare function insertPreparedDecision(adapter: DatabaseInstance, decision: DecisionInput, embedding: Float32Array | null): number;
 /**
  * Update decision outcome
  *
@@ -254,16 +229,6 @@ export declare function queryVectorSearch(params: VectorSearchParams): Promise<D
  * @param outcomeData - Outcome data
  */
 export declare function updateDecisionOutcome(decisionId: string, outcomeData: OutcomeData): Promise<void>;
-/**
- * Get prepared statement
- *
- * For backward compatibility with memory-store.js
- * Returns a compatibility shim that proxies to adapter.prepare()
- *
- * @param sql - SQL statement
- * @returns Statement-like object with run/get/all methods
- */
-export declare function getPreparedStmt(sql: string): PreparedStatement;
 /**
  * Get database file path
  *
@@ -287,13 +252,4 @@ export declare function resetDBState(options?: {
  *
  * Returns true if MAMA_TEST_MODE, VITEST, or NODE_ENV=test env vars are set
  */
-export declare function isTestMode(): boolean;
-/**
- * FTS5 keyword search on decisions table.
- * Returns matching decision IDs with BM25 rank scores.
- */
-export declare function fts5Search(query: string, limit?: number): Promise<{
-    id: string;
-    rank: number;
-}[]>;
 //# sourceMappingURL=db-manager.d.ts.map