@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/runtime/token-estimator.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * TokenEstimator — singleton wrapper around js-tiktoken (cl100k_base).
+ *
+ * Provides accurate token counting for Korean + English text.
+ * Falls back to byte-length heuristic if WASM init fails or during loading.
+ *
+ * Uses dynamic import to avoid blocking vitest fork initialization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initTokenEstimator = initTokenEstimator;
+exports.countTokens = countTokens;
+exports.resetTokenEstimator = resetTokenEstimator;
+exports.forceFallbackMode = forceFallbackMode;
+let _encoder = null;
+let _initFailed = false;
+let _initPromise = null;
+/**
+ * Initialize the encoder asynchronously. Safe to call multiple times.
+ */
+async function initTokenEstimator() {
+    if (_encoder || _initFailed)
+        return;
+    if (_initPromise)
+        return _initPromise;
+    _initPromise = (async () => {
+        try {
+            const { encodingForModel } = await import('js-tiktoken');
+            _encoder = encodingForModel('gpt-4o');
+        }
+        catch {
+            _initFailed = true;
+        }
+    })();
+    return _initPromise;
+}
+function getEncoder() {
+    if (!_encoder && !_initFailed && !_initPromise) {
+        // Fire-and-forget init on first sync access
+        initTokenEstimator().catch(() => { });
+    }
+    return _encoder;
+}
+/**
+ * Byte-length fallback: ~0.4 tokens per byte (empirical for mixed CJK+Latin).
+ */
+function fallbackCount(text) {
+    return Math.ceil(Buffer.byteLength(text, 'utf-8') * 0.4);
+}
+/**
+ * Count tokens in text. Uses js-tiktoken if available, else byte fallback.
+ */
+function countTokens(text) {
+    const enc = getEncoder();
+    if (enc) {
+        return enc.encode(text).length;
+    }
+    return fallbackCount(text);
+}
+/**
+ * Reset singleton state (for testing).
+ */
+function resetTokenEstimator() {
+    _encoder = null;
+    _initFailed = false;
+    _initPromise = null;
+}
+/**
+ * Force fallback mode (for testing).
+ */
+function forceFallbackMode() {
+    _encoder = null;
+    _initFailed = true;
+}
+//# sourceMappingURL=token-estimator.js.map

package/dist/runtime/tool-trace-store.d.ts

@@ -0,0 +1,22 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { AppendToolTraceInput, AppendOperationToolTraceInput, ToolTraceRecord, ToolTraceScope, ListToolTracesInput, ToolTracePage } from './model-run-types.js';
+type ToolTraceAdapter = Pick<DatabaseAdapter, 'prepare'>;
+/** Model-backed append. `model_run_id` is required and validated as before. */
+export declare function appendToolTrace(adapter: ToolTraceAdapter, input: AppendToolTraceInput): Promise<ToolTraceRecord>;
+/**
+ * Service/CLI operation append. Records a truthful operation trace anchored by a
+ * nonempty `operation_id` and `actor_principal_id`. No `model_runs` row is
+ * created or required.
+ *
+ * `model_run_id` is optional causal provenance: when a real completed model run
+ * caused this operation observation it is stored (the DB `model_runs` FK rejects
+ * an invalid reference); absent, it stays NULL. It never authorizes execution.
+ */
+export declare function appendOperationToolTrace(adapter: ToolTraceAdapter, input: AppendOperationToolTraceInput): ToolTraceRecord;
+export declare function listToolTracesForRun(adapter: ToolTraceAdapter, modelRunId: string): Promise<ToolTraceRecord[]>;
+/** Access is exact host-derived scope; knowing a trace ID never grants access. */
+export declare function readToolTrace(adapter: ToolTraceAdapter, traceId: string, scope: ToolTraceScope): Promise<ToolTraceRecord | null>;
+/** Bounded metadata discovery; detailed evidence is read explicitly by trace ID. */
+export declare function listToolTraces(adapter: ToolTraceAdapter, input: ListToolTracesInput): Promise<ToolTracePage>;
+export {};
+//# sourceMappingURL=tool-trace-store.d.ts.map

package/dist/{model-runs → runtime}/tool-trace-store.js

@@ -4,11 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.appendToolTrace = appendToolTrace;
+exports.appendOperationToolTrace = appendOperationToolTrace;
 exports.listToolTracesForRun = listToolTracesForRun;
 exports.readToolTrace = readToolTrace;
 exports.listToolTraces = listToolTraces;
 const node_crypto_1 = __importDefault(require("node:crypto"));
-const db_manager_js_1 = require("../db-manager.js");
 function traceId() {
     return `tr_${node_crypto_1.default.randomUUID().replace(/-/g, '')}`;
 }
@@ -77,7 +77,10 @@ function mapToolTraceRow(row) {
         project_id: nullableString(row.project_id),
         channel_id: nullableString(row.channel_id),
         trace_id: requiredString(row.trace_id, 'trace_id'),
-        model_run_id: requiredString(row.model_run_id, 'model_run_id'),
+        // NULL for operation-origin rows; legacy/model-backed rows keep their id.
+        model_run_id: nullableString(row.model_run_id),
+        operation_id: nullableString(row.operation_id),
+        actor_principal_id: nullableString(row.actor_principal_id),
         gateway_call_id: nullableString(row.gateway_call_id),
         tool_name: requiredString(row.tool_name, 'tool_name'),
         input_summary: nullableString(row.input_summary),
@@ -89,17 +92,15 @@ function mapToolTraceRow(row) {
         created_at: requiredInteger(row.created_at, 'created_at'),
     };
 }
-async function initializedAdapter() {
-    await (0, db_manager_js_1.initDB)();
-    return (0, db_manager_js_1.getAdapter)();
-}
+/** Columns selected for every full trace read; kept in one place so operation-origin rows are never joined away. */
+const TOOL_TRACE_COLUMNS = `trace_id, model_run_id, operation_id, actor_principal_id, gateway_call_id, tool_name, input_summary,
+          output_summary, execution_status, duration_ms, envelope_hash, failure_code,
+          created_at, diagnostic_json, evidence_json, catalog_revision, owner_scope, project_id, channel_id`;
 function selectToolTrace(adapter, id) {
     const row = adapter
         .prepare(`
         SELECT
-          trace_id, model_run_id, gateway_call_id, tool_name, input_summary,
-          output_summary, execution_status, duration_ms, envelope_hash, failure_code,
-          created_at, diagnostic_json, evidence_json, catalog_revision, owner_scope, project_id, channel_id
+          ${TOOL_TRACE_COLUMNS}
         FROM tool_traces
         WHERE trace_id = ?
       `)
@@ -109,32 +110,52 @@ function selectToolTrace(adapter, id) {
     }
     return mapToolTraceRow(row);
 }
-async function appendToolTrace(input) {
-    const adapter = await initializedAdapter();
-    const id = nullableString(input.trace_id) ?? traceId();
-    const modelRunId = requiredString(input.model_run_id, 'model_run_id');
-    const toolName = requiredString(input.tool_name, 'tool_name');
+function insertToolTraceRow(adapter, id, origin, input) {
     adapter
         .prepare(`
         INSERT INTO tool_traces (
-          trace_id, model_run_id, gateway_call_id, tool_name, input_summary,
+          trace_id, model_run_id, operation_id, actor_principal_id, gateway_call_id, tool_name, input_summary,
           output_summary, execution_status, duration_ms, envelope_hash, failure_code,
           created_at, diagnostic_json, evidence_json, catalog_revision, owner_scope, project_id, channel_id
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `)
-        .run(id, modelRunId, nullableString(input.gateway_call_id), toolName, nullableString(input.input_summary), nullableString(input.output_summary), nullableString(input.execution_status), normalizeDuration(input.duration_ms), nullableString(input.envelope_hash), nullableString(input.failure_code), normalizeTimestamp(input.created_at), nullableJsonObject(input.diagnostic_json, 'diagnostic_json'), nullableJsonObject(input.evidence_json, 'evidence_json'), nullableString(input.catalog_revision), nullableString(input.owner_scope), nullableString(input.project_id), nullableString(input.channel_id));
+        .run(id, origin.model_run_id, origin.operation_id, origin.actor_principal_id, nullableString(input.gateway_call_id), requiredString(input.tool_name, 'tool_name'), nullableString(input.input_summary), nullableString(input.output_summary), nullableString(input.execution_status), normalizeDuration(input.duration_ms), nullableString(input.envelope_hash), nullableString(input.failure_code), normalizeTimestamp(input.created_at), nullableJsonObject(input.diagnostic_json, 'diagnostic_json'), nullableJsonObject(input.evidence_json, 'evidence_json'), nullableString(input.catalog_revision), nullableString(input.owner_scope), nullableString(input.project_id), nullableString(input.channel_id));
+}
+/** Model-backed append. `model_run_id` is required and validated as before. */
+async function appendToolTrace(adapter, input) {
+    const id = nullableString(input.trace_id) ?? traceId();
+    const modelRunId = requiredString(input.model_run_id, 'model_run_id');
+    insertToolTraceRow(adapter, id, { model_run_id: modelRunId, operation_id: null, actor_principal_id: null }, input);
     return selectToolTrace(adapter, id);
 }
-async function listToolTracesForRun(modelRunId) {
-    const adapter = await initializedAdapter();
+/**
+ * Service/CLI operation append. Records a truthful operation trace anchored by a
+ * nonempty `operation_id` and `actor_principal_id`. No `model_runs` row is
+ * created or required.
+ *
+ * `model_run_id` is optional causal provenance: when a real completed model run
+ * caused this operation observation it is stored (the DB `model_runs` FK rejects
+ * an invalid reference); absent, it stays NULL. It never authorizes execution.
+ */
+function appendOperationToolTrace(adapter, input) {
+    const id = nullableString(input.trace_id) ?? traceId();
+    const operationId = requiredString(input.operation_id, 'operation_id');
+    const actorPrincipalId = requiredString(input.actor_principal_id, 'actor_principal_id');
+    const causalModelRunId = nullableString(input.model_run_id);
+    insertToolTraceRow(adapter, id, {
+        model_run_id: causalModelRunId,
+        operation_id: operationId,
+        actor_principal_id: actorPrincipalId,
+    }, input);
+    return selectToolTrace(adapter, id);
+}
+async function listToolTracesForRun(adapter, modelRunId) {
     const id = requiredString(modelRunId, 'model_run_id');
     const rows = adapter
         .prepare(`
         SELECT
-          trace_id, model_run_id, gateway_call_id, tool_name, input_summary,
-          output_summary, execution_status, duration_ms, envelope_hash, failure_code,
-          created_at, diagnostic_json, evidence_json, catalog_revision, owner_scope, project_id, channel_id
+          ${TOOL_TRACE_COLUMNS}
         FROM tool_traces
         WHERE model_run_id = ?
         ORDER BY created_at DESC, rowid DESC
@@ -155,18 +176,17 @@ function scopedWhere(scope) {
     return { clauses, values };
 }
 /** Access is exact host-derived scope; knowing a trace ID never grants access. */
-async function readToolTrace(traceId, scope) {
+async function readToolTrace(adapter, traceId, scope) {
     const { clauses, values } = scopedWhere(scope);
     clauses.push('trace_id = ?');
     values.push(requiredString(traceId, 'trace_id'));
-    const adapter = await initializedAdapter();
     const row = adapter
         .prepare(`SELECT * FROM tool_traces WHERE ${clauses.join(' AND ')}`)
         .get(...values);
     return row ? mapToolTraceRow(row) : null;
 }
 /** Bounded metadata discovery; detailed evidence is read explicitly by trace ID. */
-async function listToolTraces(input) {
+async function listToolTraces(adapter, input) {
     const { clauses, values } = scopedWhere(input);
     if (input.evidence_only !== undefined && typeof input.evidence_only !== 'boolean') {
         throw new Error('tool_traces.evidence_only must be a boolean');
@@ -205,9 +225,8 @@ async function listToolTraces(input) {
         clauses.push('(created_at < ? OR (created_at = ? AND trace_id < ?))');
         values.push(cursorCreatedAt, cursorCreatedAt, cursorTraceId);
     }
-    const adapter = await initializedAdapter();
     const rows = adapter
-        .prepare(`SELECT trace_id, model_run_id, gateway_call_id, tool_name,
+        .prepare(`SELECT trace_id, model_run_id, operation_id, actor_principal_id, gateway_call_id, tool_name,
     input_summary, output_summary, execution_status, duration_ms, envelope_hash, failure_code,
     created_at, diagnostic_json, NULL AS evidence_json, catalog_revision, owner_scope, project_id, channel_id
     FROM tool_traces WHERE ${clauses.join(' AND ')}

package/dist/runtime/trace-summary.d.ts

@@ -0,0 +1,5 @@
+/** Shared raw diagnostic redaction; callers choose their own output bounds. */
+export declare function redactTraceText(value: string): string;
+/** Bounded diagnostics only: never mutate the executed input or stored evidence. */
+export declare function traceSummary(value: unknown): string | null;
+//# sourceMappingURL=trace-summary.d.ts.map

package/dist/runtime/trace-summary.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactTraceText = redactTraceText;
+exports.traceSummary = traceSummary;
+const secret_filter_js_1 = require("../memory/secret-filter.js");
+const SECRET_FIELD = /(?:authorization|credential|password|passwd|secret|token|api[_-]?key|private[_-]?key)/i;
+const SECRET_ASSIGNMENT = /\b([\w-]*(?:token|secret|password|passwd|credential|api[_-]?key|private[_-]?key)[\w-]*(?:\\?["'])?\s*[=:]\s*)(?:\\"[^\r\n]*?\\"|"[^"\n]*"|'[^'\n]*'|[^\s,;&}\]]+)/gi;
+/** Shared raw diagnostic redaction; callers choose their own output bounds. */
+function redactTraceText(value) {
+    return (0, secret_filter_js_1.redactSecretPatterns)(value)
+        .replace(/\beyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\b/g, '[REDACTED]')
+        .replace(/https?:\/\/[^\s<>"']+/gi, (raw) => {
+        try {
+            const url = new URL(raw);
+            if (url.username || url.password) {
+                url.username = '[REDACTED]';
+                url.password = '';
+            }
+            for (const key of [...url.searchParams.keys()]) {
+                if (SECRET_FIELD.test(key))
+                    url.searchParams.set(key, '[REDACTED]');
+            }
+            // URL fragments are not sent to servers and do not help diagnose tool execution.
+            url.hash = '';
+            return url.toString();
+        }
+        catch {
+            return '[INVALID-URL]';
+        }
+    })
+        .replace(/(--[\w-]*(?:token|secret|password|passwd|credential|api[_-]?key|private[_-]?key)[\w-]*\s+)(?:"[^"\n]*"|'[^'\n]*'|[^\s,;&}\]]+)/gi, '$1[REDACTED]')
+        .replace(SECRET_ASSIGNMENT, '$1[REDACTED]')
+        .replace(/\b(Authorization["']?\s*[:=]\s*["']?)(?:(?:Bearer|Basic)\s+)?[^\s,"';]+/gi, '$1[REDACTED]');
+}
+/** Bounded diagnostics only: never mutate the executed input or stored evidence. */
+function traceSummary(value) {
+    if (value === undefined)
+        return null;
+    const seen = new WeakSet();
+    let remaining = 4_000;
+    const text = (value) => {
+        const safe = redactTraceText(value);
+        const result = safe.slice(0, Math.max(0, remaining));
+        remaining -= result.length;
+        return result;
+    };
+    const visit = (item, depth) => {
+        if (remaining <= 0 || depth > 6)
+            return '[TRUNCATED]';
+        if (typeof item === 'string')
+            return text(item);
+        if (!item || typeof item !== 'object')
+            return item;
+        if (seen.has(item))
+            return '[CIRCULAR]';
+        seen.add(item);
+        if (Array.isArray(item))
+            return item.slice(0, 40).map((entry) => visit(entry, depth + 1));
+        return Object.fromEntries(Object.entries(item)
+            .slice(0, 40)
+            .map(([key, entry]) => [
+            text(key),
+            SECRET_FIELD.test(key) ? '[REDACTED]' : visit(entry, depth + 1),
+        ]));
+    };
+    try {
+        const serialized = JSON.stringify(visit(value, 0)) ?? '';
+        return serialized.length <= 4_000 ? serialized : `${serialized.slice(0, 3_997)}...`;
+    }
+    catch {
+        return '[UNSERIALIZABLE]';
+    }
+}
+//# sourceMappingURL=trace-summary.js.map

package/dist/runtime/turn-text.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reading and writing a turn's text, with nothing in it that knows which product
+ * the turn belongs to.
+ *
+ * These five were methods on the product's loop class only because they were written
+ * there. None of them reads any state on that class; the one that needed to know the
+ * backend takes it as an argument. They come out first so that what remains of the
+ * turn body is the part that actually holds state.
+ */
+import type { BackendType, ContentBlock, Message, PromptResult } from './drivers/types.js';
+/** The text blocks of one content array, joined. */
+export declare function extractTextFromContent(content: ContentBlock[]): string;
+/** The last assistant message's text, or empty when the history holds none. */
+export declare function extractTextResponse(history: Message[]): string;
+/**
+ * Tokens a turn counts against the run budget.
+ *
+ * One backend reports cache reads and cache creation outside input_tokens; the other
+ * reports input tokens inclusive of cached ones. Adding cache reads for the second
+ * doubled every count in 0.44.0, where a 2.8M turn read as 5.5M and was stopped.
+ */
+export declare function countBudgetTokens(usage: PromptResult['usage'], backend: BackendType): number;
+//# sourceMappingURL=turn-text.d.ts.map

package/dist/runtime/turn-text.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTextFromContent = extractTextFromContent;
+exports.extractTextResponse = extractTextResponse;
+exports.countBudgetTokens = countBudgetTokens;
+/** The text blocks of one content array, joined. */
+function extractTextFromContent(content) {
+    return content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('\n');
+}
+/** The last assistant message's text, or empty when the history holds none. */
+function extractTextResponse(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const message = history[i];
+        if (message.role === 'assistant') {
+            const content = message.content;
+            if (typeof content === 'string') {
+                return content;
+            }
+            return extractTextFromContent(content);
+        }
+    }
+    return '';
+}
+/**
+ * Tokens a turn counts against the run budget.
+ *
+ * One backend reports cache reads and cache creation outside input_tokens; the other
+ * reports input tokens inclusive of cached ones. Adding cache reads for the second
+ * doubled every count in 0.44.0, where a 2.8M turn read as 5.5M and was stopped.
+ */
+function countBudgetTokens(usage, backend) {
+    const base = usage.input_tokens + usage.output_tokens;
+    if (backend === 'codex') {
+        return base;
+    }
+    return base + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0);
+}
+//# sourceMappingURL=turn-text.js.map

package/dist/storage/database.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Database lifetime.
+ *
+ * `openDatabase` returns a handle to one database. It does not register itself
+ * anywhere, so two calls give two independent databases and a caller always
+ * knows which one it holds. `db-manager.ts` keeps a single handle for the
+ * callers that still reach for a module-level connection; nothing here depends
+ * on that handle existing.
+ *
+ * @module storage/database
+ */
+import type { DatabaseInstance } from '../db-manager.js';
+/** Migrations ship beside the compiled output, two levels up from `dist/storage`. */
+export declare const MIGRATIONS_DIR: string;
+export interface OpenDatabaseOptions {
+    /** Where to open. Falls back to the adapter's own resolution when omitted. */
+    path?: string;
+    /** Directory holding the core's migration files. Defaults to the shipped one. */
+    migrationsDir?: string;
+    /**
+     * Migrations this consumer brings of its own, run after the core's.
+     *
+     * A package that needs a table has somewhere to put it other than inside the
+     * core. Each source namespaces its own version numbers, so the core's next
+     * number is not spoken for by somebody else.
+     */
+    migrations?: ReadonlyArray<{
+        name: string;
+        dir: string;
+    }>;
+}
+export interface DatabaseHandle {
+    adapter: DatabaseInstance;
+    /** The value `connect()` returned, for callers that still need the raw driver. */
+    connection: unknown;
+    /** Where this handle actually opened, or a description when the adapter cannot say. */
+    dbPath: string;
+    close: () => Promise<void>;
+}
+export declare function isTestMode(): boolean;
+/**
+ * Declare where this product's live database is, as a resolved absolute path.
+ * Call once, before opening anything.
+ */
+export declare function declareProductionDatabasePath(value: string): void;
+/** Test seam: forget what was declared. */
+export declare function clearProductionDatabasePaths(): void;
+/**
+ * Refuse, in a test process, to open a database nobody named or one a product
+ * declared as live.
+ *
+ * This used to compare against one hard-coded path, `~/.claude/mama-memory.db`, which
+ * meant the core held a product's data location in order to protect it. The rule is
+ * the same and says no product's name: a test that did not state where it wanted to
+ * write is about to write somewhere it did not choose, and that failure surfaces far
+ * from its cause.
+ */
+export declare function assertTestProcessIsNotUsingRealDb(effectivePath?: string, effectivePathSource?: string): void;
+export declare function resolveAdapterDbPath(adapter: DatabaseInstance): string | undefined;
+/**
+ * Open one database: connect, migrate, and verify the embedding scheme.
+ *
+ * Throws if any step fails. Nothing partially opened is returned, so a caller
+ * that receives a handle holds a migrated database it can use.
+ */
+export declare function openDatabase(options?: OpenDatabaseOptions): Promise<DatabaseHandle>;
+//# sourceMappingURL=database.d.ts.map

package/dist/storage/database.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Database lifetime.
+ *
+ * `openDatabase` returns a handle to one database. It does not register itself
+ * anywhere, so two calls give two independent databases and a caller always
+ * knows which one it holds. `db-manager.ts` keeps a single handle for the
+ * callers that still reach for a module-level connection; nothing here depends
+ * on that handle existing.
+ *
+ * @module storage/database
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATIONS_DIR = void 0;
+exports.isTestMode = isTestMode;
+exports.declareProductionDatabasePath = declareProductionDatabasePath;
+exports.clearProductionDatabasePaths = clearProductionDatabasePaths;
+exports.assertTestProcessIsNotUsingRealDb = assertTestProcessIsNotUsingRealDb;
+exports.resolveAdapterDbPath = resolveAdapterDbPath;
+exports.openDatabase = openDatabase;
+const node_path_1 = __importDefault(require("node:path"));
+const index_js_1 = require("../db-adapter/index.js");
+const db_manager_js_1 = require("../db-manager.js");
+const debug_logger_js_1 = require("../debug-logger.js");
+const progress_indicator_js_1 = require("../progress-indicator.js");
+/** Migrations ship beside the compiled output, two levels up from `dist/storage`. */
+exports.MIGRATIONS_DIR = node_path_1.default.join(__dirname, '..', '..', 'db', 'migrations');
+function isTestMode() {
+    return Boolean(process.env.MAMA_TEST_MODE || process.env.VITEST || process.env.NODE_ENV === 'test');
+}
+/**
+ * A path a consumer states must already be resolved.
+ *
+ * The core used to expand `~` and `${HOME}` itself, which made it the thing that
+ * decides what home means. Two consumers with different homes then got the same
+ * answer from a library neither of them configured. Expansion belongs to whoever owns
+ * the home directory; this only refuses to guess.
+ */
+function requireResolvedPath(value, source) {
+    if (value === '~' || value.startsWith('~/') || value.includes('${HOME}')) {
+        throw new Error(`[db-boundary] ${source} is not a resolved path (${value}). ` +
+            'Expand it where the home directory is known and state the result.');
+    }
+    return node_path_1.default.resolve(value);
+}
+/**
+ * Databases a product has declared as its live one.
+ *
+ * The core used to hold one such path itself, `~/.claude/mama-memory.db`, which meant
+ * a shared library knew where one product kept its data in order to protect it. Each
+ * product declares its own now, and the guard below refuses all of them.
+ */
+const productionDatabasePaths = new Set();
+/**
+ * Declare where this product's live database is, as a resolved absolute path.
+ * Call once, before opening anything.
+ */
+function declareProductionDatabasePath(value) {
+    productionDatabasePaths.add(requireResolvedPath(value, 'the declared production database path'));
+}
+/** Test seam: forget what was declared. */
+function clearProductionDatabasePaths() {
+    productionDatabasePaths.clear();
+}
+/**
+ * Refuse, in a test process, to open a database nobody named or one a product
+ * declared as live.
+ *
+ * This used to compare against one hard-coded path, `~/.claude/mama-memory.db`, which
+ * meant the core held a product's data location in order to protect it. The rule is
+ * the same and says no product's name: a test that did not state where it wanted to
+ * write is about to write somewhere it did not choose, and that failure surfaces far
+ * from its cause.
+ */
+function assertTestProcessIsNotUsingRealDb(effectivePath, effectivePathSource = 'adapter') {
+    if (!isTestMode()) {
+        return;
+    }
+    const configuredPaths = [
+        { name: 'MAMA_DB_PATH', value: process.env.MAMA_DB_PATH },
+        { name: 'MAMA_DATABASE_PATH', value: process.env.MAMA_DATABASE_PATH },
+    ];
+    if (effectivePath) {
+        configuredPaths.push({ name: effectivePathSource, value: effectivePath });
+    }
+    const named = configuredPaths.find((configuredPath) => Boolean(configuredPath.value));
+    if (!named) {
+        throw new Error('[db-boundary] Refusing to open an unnamed database from a test process. ' +
+            'Set MAMA_DB_PATH to a temporary path first.');
+    }
+    for (const configuredPath of configuredPaths) {
+        if (!configuredPath.value) {
+            continue;
+        }
+        const resolvedPath = requireResolvedPath(configuredPath.value, configuredPath.name);
+        if (productionDatabasePaths.has(resolvedPath)) {
+            throw new Error(`[db-boundary] Refusing to open the live database ${resolvedPath} ` +
+                `from a test process (${configuredPath.name}=${configuredPath.value}). ` +
+                'Set MAMA_DB_PATH to a temporary path first.');
+        }
+    }
+}
+function resolveAdapterDbPath(adapter) {
+    if (typeof adapter.getDbPath === 'function') {
+        return adapter.getDbPath();
+    }
+    return adapter.dbPath;
+}
+/**
+ * Open one database: connect, migrate, and verify the embedding scheme.
+ *
+ * Throws if any step fails. Nothing partially opened is returned, so a caller
+ * that receives a handle holds a migrated database it can use.
+ */
+async function openDatabase(options = {}) {
+    assertTestProcessIsNotUsingRealDb(options.path, 'openDatabase({ path })');
+    (0, progress_indicator_js_1.logSearching)('Initializing database...');
+    const adapter = (0, index_js_1.createAdapter)(options.path ? { dbPath: options.path } : {});
+    assertTestProcessIsNotUsingRealDb(resolveAdapterDbPath(adapter), 'adapter.getDbPath()');
+    let connection;
+    try {
+        connection = await adapter.connect();
+        await adapter.runMigrations([
+            { name: 'core', dir: options.migrationsDir ?? exports.MIGRATIONS_DIR },
+            ...(options.migrations ?? []),
+        ]);
+        // New tables and rows exist only after migrations run.
+        if (typeof adapter.reloadVectorCache === 'function') {
+            adapter.reloadVectorCache();
+        }
+        // Fail loud on legacy vectors meeting current code.
+        (0, db_manager_js_1.assertEmbeddingSchemeCurrent)(adapter);
+    }
+    catch (error) {
+        try {
+            adapter.disconnect();
+        }
+        catch {
+            // The open already failed; a disconnect error would only mask it.
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to initialize database: ${message}`);
+    }
+    (0, debug_logger_js_1.info)(`[storage/database] Database opened (${adapter.constructor.name})`);
+    (0, progress_indicator_js_1.logComplete)('Database ready');
+    return {
+        adapter,
+        connection,
+        dbPath: resolveAdapterDbPath(adapter) ?? `${adapter.constructor.name} (path unavailable)`,
+        close: async () => {
+            await adapter.disconnect();
+        },
+    };
+}
+//# sourceMappingURL=database.js.map