@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/mama-api.d.ts

@@ -17,16 +17,16 @@
  * @version 1.3
  * @date 2025-11-26
  */
-import { DecisionRecord } from './db-manager.js';
+import { type CheckpointRow, type ListDecisionsOptions, type SearchCandidate, type SuggestFunctionOptions, type UpdateOutcomeParams } from './memory/api.js';
+import { DecisionRecord, type DatabaseInstance } from './db-manager.js';
 import { SemanticEdges } from './decision-formatter.js';
-import { saveMemory, saveMemoryWithTrustedProvenance, recallMemory, buildProfile, ingestMemory, ingestWithTrustedProvenance, ingestConversation, ingestConversationWithTrustedProvenance, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary } from './memory/api.js';
-import { createAuditFinding, listOpenAuditFindings } from './memory/finding-store.js';
-import { listMemoryEventsForMemory, listRecentMemoryEvents } from './memory/event-store.js';
-import type { TrustedMemoryWriteOptions } from './memory/provenance.js';
-import { getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId } from './memory/provenance-query.js';
-import { beginModelRun, beginModelRunInAdapter, commitModelRun, commitModelRunInAdapter, failModelRun, failModelRunInAdapter, getModelRun, getModelRunInAdapter } from './model-runs/store.js';
-import { appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace } from './model-runs/tool-trace-store.js';
-import { type SearchHitDiagnostics, type SearchQualityOptions } from './search/search-quality.js';
+import { saveMemory as saveMemoryInAdapter, recallMemory as recallMemoryInAdapter, buildProfile as buildProfileInAdapter, ingestMemory as ingestMemoryInAdapter, ingestConversation as ingestConversationInAdapter, evolveMemory, buildMemoryBootstrap as buildMemoryBootstrapInAdapter, createAuditAck, recordMemoryAudit as recordMemoryAuditInAdapter, upsertChannelSummary as upsertChannelSummaryInAdapter, getChannelSummary as getChannelSummaryInAdapter } from './memory/api.js';
+import { createAuditFinding as createAuditFindingInAdapter, listOpenAuditFindings as listOpenAuditFindingsInAdapter } from './memory/finding-store.js';
+import { listMemoryEventsForMemory as listMemoryEventsForMemoryInAdapter, listRecentMemoryEvents as listRecentMemoryEventsInAdapter } from './memory/event-store.js';
+import { getMemoryProvenance as getMemoryProvenanceInAdapter, listMemoriesByEnvelopeHash as listMemoriesByEnvelopeHashInAdapter, listMemoriesByGatewayCallId as listMemoriesByGatewayCallIdInAdapter, listMemoriesByModelRunId as listMemoriesByModelRunIdInAdapter } from './memory/provenance-query.js';
+import { beginModelRun as beginModelRunInAdapter, commitModelRun as commitModelRunInAdapter, failModelRun as failModelRunInAdapter, getModelRun as getModelRunInAdapter, listModelRunNativeInputs as listModelRunNativeInputsInAdapter } from './runtime/model-run-store.js';
+import { appendToolTrace as appendToolTraceInAdapter, listToolTracesForRun as listToolTracesForRunInAdapter, listToolTraces as listToolTracesInAdapter, readToolTrace as readToolTraceInAdapter } from './runtime/tool-trace-store.js';
+import { type SearchHitDiagnostics } from './knowledge/search-quality.js';
 /**
  * Parameters for mama.save()
  */
@@ -42,23 +42,16 @@ interface SaveParams {
     trust_context?: Record<string, unknown> | null;
     is_static?: number;
     scopes?: Array<{
-        kind: 'global' | 'user' | 'channel' | 'project';
+        kind: string;
         id: string;
     }>;
+    item?: string | null;
+    actors?: Array<{
+        person: string;
+        role: string;
+    }>;
     /** ISO 8601 date string for when the event actually occurred (e.g. "2023-01-15") */
     event_date?: string | null;
-    timelineEvent?: {
-        id?: string;
-        entity_id?: string;
-        event_type: string;
-        role?: string | null;
-        valid_from?: number | null;
-        valid_to?: number | null;
-        observed_at?: number | null;
-        source_ref?: string | null;
-        summary: string;
-        details?: string | null;
-    };
 }
 /**
  * Similar decision result from search
@@ -129,10 +122,7 @@ interface SaveResult {
     success: boolean;
     id: string;
     saved_decision_id?: string;
-    timeline_event_id?: string | null;
-    timeline_event_ids?: string[];
     similar_decisions?: SimilarDecision[];
-    warning?: string;
     collaboration_hint?: string;
     reasoning_graph?: ReasoningGraphInfo;
     error?: string;
@@ -235,174 +225,6 @@ export interface DBLinkStatsResult {
     unique_decisions: number;
     relationship_breakdown: string;
 }
-/**
- * Deletion target for auto-generated links
- */
-interface DeletionTarget {
-    from_id: string;
-    to_id: string;
-    relationship: string;
-}
-/**
- * Post cleanup report structure
- */
-export interface PostCleanupReport {
-    orphaned_decisions: number;
-    duplicate_links: number;
-    invalid_references: number;
-}
-/**
- * Quality report options
- */
-interface QualityReportOptions {
-    format?: 'json' | 'markdown' | null;
-    period?: '24h' | '7d' | '30d' | null;
-    thresholds?: QualityThresholds | null;
-}
-/**
- * Quality thresholds
- */
-interface QualityThresholds {
-    minSuccessRate?: number;
-    maxLatencyMs?: number;
-}
-/**
- * Deprecate auto-links result
- */
-interface DeprecateAutoLinksResult {
-    dryRun: boolean;
-    deprecated: number;
-    protected: number;
-    total: number;
-    autoLinkRatio: string;
-    links: Array<{
-        from_id: string;
-        to_id: string;
-        relationship: string;
-        reason?: string;
-        created_at?: number | string;
-    }>;
-}
-/**
- * Scan auto-links result
- */
-interface ScanAutoLinksResult {
-    total_links: number;
-    auto_links: number;
-    protected_links: number;
-    deletion_targets: number;
-    deletion_target_list: DeletionTarget[];
-}
-/**
- * Create link backup result
- */
-interface CreateLinkBackupResult {
-    backup_file: string;
-    manifest_file: string;
-    checksum: string;
-    link_count: number;
-}
-/**
- * Restore link backup result
- */
-interface RestoreLinkBackupResult {
-    total_links: number;
-    restored: number;
-    failed: number;
-    backup_file: string;
-}
-/**
- * Verify backup exists result
- */
-interface VerifyBackupResult {
-    backup_file: string;
-    age_hours: number;
-    link_count: number;
-}
-/**
- * Delete auto-links result (dry run mode)
- */
-interface DeleteAutoLinksDryRunResult {
-    dry_run: true;
-    would_delete: number;
-    deleted: 0;
-    backup_file: string;
-    large_deletion_warning: boolean;
-    warning_message: string | null;
-    sample_links: Array<{
-        from_id: string;
-        to_id: string;
-        relationship: string;
-    }>;
-    message: string;
-}
-/**
- * Delete auto-links error entry
- */
-type DeleteAutoLinksError = {
-    link: string;
-    error: string;
-} | {
-    batch_index: number;
-    batch_size: number;
-    error: string;
-};
-/**
- * Delete auto-links result (execute mode)
- */
-interface DeleteAutoLinksExecuteResult {
-    dry_run: false;
-    deleted: number;
-    failed: number;
-    total_targets: number;
-    batches_processed: number;
-    backup_file: string;
-    errors: DeleteAutoLinksError[];
-    success_rate: number;
-}
-/**
- * Delete auto-links result (empty case)
- */
-interface DeleteAutoLinksEmptyResult {
-    dry_run: boolean;
-    deleted: 0;
-    failed: 0;
-    total_targets: 0;
-    backup_file: string;
-    message: string;
-}
-/**
- * Delete auto-links union type
- */
-type DeleteAutoLinksResult = DeleteAutoLinksDryRunResult | DeleteAutoLinksExecuteResult | DeleteAutoLinksEmptyResult;
-/**
- * Quality recommendation
- */
-export interface QualityRecommendation {
-    category: string;
-    severity: string;
-    message: string;
-}
-/**
- * Quality report structure
- */
-export interface QualityReport {
-    successRate: {
-        period: string;
-        total: number;
-        success: number;
-        failure: number;
-        successRate: string;
-        meetsTarget: boolean;
-    };
-    latency?: {
-        avgMs: number;
-        p50Ms: number;
-        p95Ms: number;
-        maxMs: number;
-        meetsTarget: boolean;
-    };
-}
 /**
  * Recall decisions by topic
  *
@@ -467,570 +289,45 @@ interface RecallGraphResult {
         };
     };
 }
-declare function recall(topic: string, options?: RecallOptions): Promise<string | RecallGraphResult>;
-/**
- * Update outcome of a decision
- *
- * Track whether a decision succeeded, failed, or partially worked
- * AC: Evolutionary Decision Memory - Learn from outcomes
- *
- * @param {string} decisionId - Decision ID to update
- * @param {Object} outcome - Outcome details
- * @param {string} outcome.outcome - 'SUCCESS', 'FAILED', or 'PARTIAL'
- * @param {string} [outcome.failure_reason] - Reason for failure (if FAILED)
- * @param {string} [outcome.limitation] - Limitation description (if PARTIAL)
- * @returns {Promise<void>}
- *
- * @example
- * await mama.updateOutcome('decision_auth_strategy_123456_abc', {
- *   outcome: 'FAILED',
- *   failure_reason: 'Missing token expiration handling'
- * });
- */
-interface UpdateOutcomeParams {
-    outcome: string;
-    failure_reason?: string | null;
-    limitation?: string | null;
-}
-declare function updateOutcome(decisionId: string, { outcome, failure_reason, limitation }: UpdateOutcomeParams): Promise<void>;
-/**
- * Expand search results with graph context (Phase 1 - Graph-Enhanced Retrieval)
- *
- * For each candidate decision:
- * 1. Add supersedes chain (evolution history)
- * 2. Add semantic edges (refines, contradicts)
- * 3. Deduplicate by ID
- * 4. Re-rank by relevance (primary candidates ranked higher)
- *
- * @param {Array} candidates - Initial search results from vector/keyword search
- * @returns {Promise<Array>} Graph-enhanced results with evolution context
- */
-interface SearchCandidate {
-    id: string;
-    topic: string;
-    decision: string;
-    reasoning?: string | null;
-    confidence?: number;
-    similarity?: number;
-    created_at?: number | string;
-    graph_source?: string;
-    graph_rank?: number;
-    related_to?: string | null;
-    edge_reason?: string | null;
-    recency_score?: number;
-    recency_age_days?: number;
-    final_score?: number;
-    outcome?: string | null;
-    failure_reason?: string | null;
-    is_static?: number;
-}
-declare function expandWithGraph(candidates: SearchCandidate[]): Promise<SearchCandidate[]>;
-/**
- * Suggest relevant decisions based on user question
- *
- * DEFAULT: Returns JSON object with search results (LLM-first design)
- * OPTIONAL: Returns Markdown string if format='markdown' (for human display)
- *
- * Simplified: Direct vector search without LLM intent analysis
- * Works with short queries, long questions, Korean/English
- *
- * @param {string} userQuestion - User's question or intent
- * @param {Object} options - Search options
- * @param {string} [options.format='json'] - Output format: 'json' (default) or 'markdown'
- * @param {number} [options.limit=5] - Max results to return
- * @param {number} [options.threshold=0.6] - Minimum similarity (adaptive by query length)
- * @param {boolean} [options.useReranking=false] - Use LLM re-ranking (optional, slower)
- * @returns {Promise<Object|string|null>} Search results as JSON or Markdown, null if no results
- *
- * @example
- * // LLM usage (default)
- * const data = await mama.suggest('Why did we choose JWT?');
- * // → { query, results: [...], meta: {...} }
- *
- * // Human display
- * const markdown = await mama.suggest('mesh optimization', { format: 'markdown' });
- * // → "💡 MAMA found 3 related topics:\n1. ..."
- */
-interface SuggestFunctionOptions extends SearchQualityOptions {
-    format?: 'json' | 'markdown';
-    limit?: number;
-    useReranking?: boolean;
-    /** Phase 3 Task 33: apply learned offline ranker rescoring. */
-    rerankWithLearned?: boolean;
-    recencyWeight?: number;
-    recencyScale?: number;
-    recencyDecay?: number;
-    scopes?: Array<{
-        kind: 'global' | 'user' | 'channel' | 'project';
-        id: string;
-    }>;
-}
 declare function save(params: SaveParams): Promise<SaveResult>;
-declare function saveWithTrustedProvenance(params: SaveParams, options: TrustedMemoryWriteOptions): Promise<SaveResult>;
-/**
- * Annotate suggest results with topic currency. MAMA semantics treat topic
- * reuse as supersession, so a result row is stale when the DB holds a newer
- * decision row for the same topic - even when its status column still says
- * 'active' (historical chains predate status maintenance). Surfacing
- * `superseded_by_newer` lets consumers (and LLMs) tell current truth from
- * superseded history; delta-bench measured 80% -> 92.5% answer accuracy when
- * the current row is explicitly marked.
- */
-declare function annotateTopicCurrency<T extends {
-    id?: unknown;
-    topic?: unknown;
-}>(rows: T[], scopes?: Array<{
-    kind: string;
-    id: string;
-}>): Array<T & {
-    superseded_by_newer?: boolean;
-}>;
 declare function suggest(userQuestion: string, options?: SuggestFunctionOptions): Promise<any>;
-/**
- * List recent decisions (all topics, chronological)
- *
- * DEFAULT: Returns JSON array with recent decisions (LLM-first design)
- * OPTIONAL: Returns Markdown string if format='markdown' (for human display)
- *
- * @param {Object} [options] - Options
- * @param {number} [options.limit=10] - Max results
- * @param {string} [options.format='json'] - Output format
- * @returns {Promise<Array|string>} Recent decisions
- */
-interface ListDecisionsOptions {
-    limit?: number;
-    format?: 'json' | 'markdown';
-    scopes?: Array<{
-        kind: 'global' | 'user' | 'channel' | 'project';
-        id: string;
-    }>;
-}
+declare function recall(topic: string, options?: RecallOptions): Promise<string | RecallGraphResult>;
+declare function expandWithGraph(candidates: SearchCandidate[]): Promise<SearchCandidate[]>;
+declare function updateOutcome(decisionId: string, outcome: UpdateOutcomeParams): Promise<void>;
 declare function listDecisions(options?: ListDecisionsOptions): Promise<DecisionRecord[] | string>;
-/**
- * Save current session checkpoint (New Feature: Session Continuity)
- *
- * @param {string} summary - Summary of current session state
- * @param {Array<string>} openFiles - List of currently open files
- * @param {string} nextSteps - Next steps to be taken
- * @returns {Promise<number>} Checkpoint ID
- */
 declare function saveCheckpoint(summary: string, openFiles?: string[], nextSteps?: string, recentConversation?: any[]): Promise<number | bigint>;
-/**
- * Load latest active checkpoint (New Feature: Session Continuity)
- *
- * @returns {Promise<Object|null>} Latest checkpoint or null
- */
-interface ConversationMessage {
-    role: string;
-    content: string | Array<{
-        type: string;
-        text?: string;
-        [key: string]: unknown;
-    }>;
-}
-interface CheckpointRow {
-    id?: number;
-    timestamp?: number;
-    summary?: string;
-    open_files?: string | string[];
-    next_steps?: string;
-    recent_conversation?: string | ConversationMessage[];
-    status?: string;
-}
 declare function loadCheckpoint(): Promise<CheckpointRow | null>;
-/**
- * List recent checkpoints (New Feature: Session Continuity)
- *
- * @param {number} limit - Max number of checkpoints to return
- * @returns {Promise<Array>} Recent checkpoints
- */
 declare function listCheckpoints(limit?: number): Promise<CheckpointRow[]>;
 /**
- * Propose a new link between decisions (Epic 3 - Story 3.1)
- *
- * LLM proposes a link for user approval. Link is created but marked as pending.
- *
- * @param {Object} params - Link parameters
- * @param {string} params.from_id - Source decision ID
- * @param {string} params.to_id - Target decision ID
- * @param {string} params.relationship - 'refines' or 'contradicts'
- * @param {string} params.reason - Why this link should exist
- * @param {string} [params.decision_id] - Context decision where link was proposed
- * @param {string} [params.evidence] - Supporting evidence
- * @returns {Promise<void>}
- */
-interface ProposeLinkParams {
-    from_id: string;
-    to_id: string;
-    relationship: string;
-    reason: string;
-    decision_id?: string;
-    evidence?: string;
-}
-declare function proposeLink({ from_id, to_id, relationship, reason, decision_id, evidence, }: ProposeLinkParams): Promise<void>;
-/**
- * Approve a proposed link (Epic 3 - Story 3.1)
- *
- * User approves a pending link, making it active.
- *
- * @param {string} from_id - Source decision ID
- * @param {string} to_id - Target decision ID
- * @param {string} relationship - Link relationship type
- * @returns {Promise<void>}
- */
-declare function approveLink(from_id: string, to_id: string, relationship: string): Promise<void>;
-/**
- * Reject a proposed link (Epic 3 - Story 3.1)
- *
- * User rejects a pending link, removing it from the database.
- *
- * @param {string} from_id - Source decision ID
- * @param {string} to_id - Target decision ID
- * @param {string} relationship - Link relationship type
- * @param {string} [reason] - Optional reason for rejection
- * @returns {Promise<void>}
- */
-declare function rejectLink(from_id: string, to_id: string, relationship: string, reason?: string): Promise<void>;
-/**
- * Get pending links awaiting approval (Epic 3 - Story 3.1)
- *
- * Returns all links that need user approval.
- *
- * @param {Object} [options] - Query options
- * @param {string} [options.from_id] - Filter by source decision
- * @param {string} [options.to_id] - Filter by target decision
- * @returns {Promise<Array>} Pending links with decision details
- */
-interface GetPendingLinksOptions {
-    from_id?: string;
-    to_id?: string;
-}
-declare function getPendingLinks(options?: GetPendingLinksOptions): Promise<any[]>;
-/**
- * Deprecate auto-generated links (Epic 3 - Story 3.3)
- *
- * Identifies and removes v0 auto-generated links that lack explicit approval context.
- * Protected links (with decision_id or created_by='llm') are preserved.
- *
- * @param {Object} [options] - Deprecation options
- * @param {boolean} [options.dryRun=true] - If true, only report without deleting
- * @returns {Promise<Object>} Report with counts and deprecated links
- */
-interface DeprecateAutoLinksOptions {
-    dryRun?: boolean;
-}
-interface EdgeLink {
-    from_id: string;
-    to_id: string;
-    relationship: string;
-    reason?: string;
-    created_at?: number | string;
-}
-declare function deprecateAutoLinks(options?: DeprecateAutoLinksOptions): Promise<DeprecateAutoLinksResult>;
-/**
- * Scan and identify auto-generated links for cleanup (Epic 5 - Story 5.1)
- *
- * Identifies auto-generated links lacking proper approval metadata.
- * Separates deletion targets from protected links.
- *
- * Identification criteria:
- * - approved_by_user = 0 OR (created_by IS NULL AND decision_id IS NULL)
- *
- * Protected (excluded from deletion):
- * - approved_by_user = 1 AND (decision_id IS NOT NULL OR evidence IS NOT NULL)
- *
- * @returns {Object} Scan results with counts and link details
- */
-declare function scanAutoLinks(): ScanAutoLinksResult;
-/**
- * Create backup of links before cleanup (Epic 5 - Story 5.1)
- *
- * Backs up deletion target links with full metadata to JSON file.
- * Generates SHA-256 checksum for data integrity verification.
- * Creates backup manifest with timestamp and metadata.
- *
- * @param {Array} targetLinks - Links to back up
- * @returns {Object} Backup result with file paths and checksum
- */
-declare function createLinkBackup(targetLinks: EdgeLink[]): CreateLinkBackupResult;
-/**
- * Generate pre-cleanup report with risk assessment (Epic 5 - Story 5.1)
- *
- * Creates comprehensive report with statistics, risk level, and samples.
- * Risk assessment based on deletion ratio:
- * - HIGH: > 50% deletion
- * - MEDIUM: 30-50% deletion
- * - LOW: < 30% deletion
- *
- * @returns {Object} Report data with markdown output and file path
- */
-declare function generatePreCleanupReport(): {
-    report: {
-        generated_at: string;
-        statistics: {
-            total_links: number;
-            auto_links: number;
-            protected_links: number;
-            deletion_targets: number;
-            deletion_ratio: string;
-        };
-        risk_assessment: {
-            level: string;
-            message: string;
-        };
-        deletion_target_samples: {
-            from_id: any;
-            to_id: any;
-            relationship: any;
-            reason: any;
-            created_by: any;
-            approved_by_user: any;
-        }[];
-    };
-    report_file: string;
-    markdown: string;
-};
-/**
- * Restore links from backup file (Epic 5 - Story 5.1)
- *
- * Restores previously backed-up links to the database.
- * Verifies checksum before restoration to ensure data integrity.
- * Reports number of restored and failed links.
- *
- * @param {string} backupFile - Path to backup file
- * @returns {Object} Restoration result with counts
- */
-declare function restoreLinkBackup(backupFile: string): RestoreLinkBackupResult;
-/**
- * Verify backup file exists and is recent (Epic 5 - Story 5.2)
- *
- * Checks for backup files in backup directory and verifies they are recent enough.
- * Required as safety check before executing link deletion.
- *
- * @param {number} maxAgeHours - Maximum age of backup in hours (default: 24)
- * @returns {Object} Backup verification result with latest backup info
- */
-declare function verifyBackupExists(maxAgeHours?: number): VerifyBackupResult;
-/**
- * Delete auto-generated links with batch processing (Epic 5 - Story 5.2)
- *
- * Executes batch deletion of auto-generated links with transaction support.
- * Requires recent backup (within 24 hours) before execution.
- * Logs all deletions to audit trail.
- *
- * Safety features:
- * - Backup verification before deletion
- * - Batch processing with transaction support
- * - Dry-run mode for simulation
- * - Large deletion warning (> 1000 links)
- *
- * @param {number} batchSize - Number of links to delete per batch (default: 100)
- * @param {boolean} dryRun - If true, simulate deletion without actual changes (default: true)
- * @returns {Object} Deletion result with counts and backup info
- */
-declare function deleteAutoLinks(batchSize?: number, dryRun?: boolean): DeleteAutoLinksResult;
-/**
- * Validate cleanup result and generate post-cleanup report (Epic 5 - Story 5.2)
- *
- * Re-scans for remaining auto-generated links and evaluates cleanup success.
- * Generates comprehensive report with statistics and recommendations.
- *
- * Success criteria:
- * - SUCCESS: Remaining auto links < 5%
- * - PARTIAL: Remaining auto links 5-10%
- * - FAILED: Remaining auto links > 10%
- *
- * @returns {Object} Validation result with report and file path
- */
-declare function validateCleanupResult(): {
-    status: string;
-    total_links_before: number;
-    auto_links_remaining: number;
-    remaining_ratio: number;
-    protected_links: number;
-    report: {
-        validated_at: string;
-        status: string;
-        message: string;
-        statistics: {
-            total_links: number;
-            remaining_auto_links: number;
-            remaining_ratio: string;
-            protected_links: number;
-            deletion_targets: number;
-        };
-        recommendation: string;
-    };
-    report_file: string;
-    markdown: string;
-};
-/**
- * Calculate coverage metrics (Epic 4 - Story 4.1)
- *
- * Measures narrative coverage (% of decisions with narrative fields)
- * and link coverage (% of decisions with at least one link).
- *
- * @returns {Object} Coverage metrics
- */
-declare function calculateCoverage(): {
-    narrativeCoverage: string;
-    linkCoverage: string;
-    totalDecisions: number;
-    completeNarratives: number;
-    decisionsWithLinks: number;
-};
-/**
- * Log restart attempt (Epic 4 - Story 4.2)
- *
- * Records restart attempt with success/failure status, latency, and mode.
- * Replaces in-memory restart-metrics.js with SQLite-backed storage.
- *
- * @param {string} sessionId - Session identifier
- * @param {string} status - 'success' or 'failure'
- * @param {string|null} failureReason - 'NO_CHECKPOINT', 'LOAD_ERROR', 'CONTEXT_INCOMPLETE', or null
- * @param {number} latencyMs - Latency in milliseconds
- * @param {string} mode - 'full' (narrative+links) or 'summary' (summary only)
- * @returns {void}
- */
-declare function logRestartAttempt(sessionId: string, status: string, failureReason: string | null, latencyMs: number, mode?: string): void;
-/**
- * Calculate restart success rate (Epic 4 - Story 4.2)
- *
- * Calculates success rate over a given period (24h, 7d, 30d).
- *
- * @param {string} period - '24h', '7d', or '30d'
- * @returns {Object} Success rate metrics
- */
-declare function calculateRestartSuccessRate(period?: '24h' | '7d' | '30d'): {
-    period: "24h" | "7d" | "30d";
-    total: number;
-    success: number;
-    failure: number;
-    successRate: string;
-    meetsTarget: boolean;
-};
-/**
- * Calculate restart latency percentiles (Epic 4 - Story 4.2)
- *
- * Calculates p50, p95, p99 latencies for successful restarts.
- * Optionally filters by mode (full/summary).
- *
- * @param {string} period - '24h', '7d', or '30d'
- * @param {string|null} mode - 'full', 'summary', or null (all modes)
- * @returns {Object} Latency percentile metrics
- */
-declare function calculateRestartLatency(period?: '24h' | '7d' | '30d', mode?: string | null): {
-    p50: number;
-    p95: number;
-    p99: number;
-    count: number;
-    mode: string;
-};
-/**
- * Get restart metrics (Epic 4 - Story 4.2)
- *
- * Combines success rate and latency metrics for a given period.
- *
- * @param {string} period - '24h', '7d', or '30d'
- * @param {boolean} includeLatency - Whether to include latency percentiles
- * @returns {Object} Combined restart metrics
- */
-declare function getRestartMetrics(period?: '24h' | '7d' | '30d', includeLatency?: boolean): {
-    successRate: ReturnType<typeof calculateRestartSuccessRate>;
-    latency?: {
-        full: ReturnType<typeof calculateRestartLatency>;
-        summary: ReturnType<typeof calculateRestartLatency>;
-    };
-};
-/**
- * Calculate quality metrics (Epic 4 - Story 4.1)
- *
- * Measures narrative quality (field completeness per layer)
- * and link quality (rich reason ratio, approved link ratio).
- *
- * @returns {Object} Quality metrics
- */
-declare function calculateQuality(): {
-    narrativeQuality: {
-        evidence: string;
-        alternatives: string;
-        risks: string;
-    };
-    linkQuality: {
-        richReasonRatio: string;
-        approvedRatio: string;
-        totalLinks: number;
-        richLinks: number;
-        approvedLinks: number;
-    };
-};
-/**
- * Generate quality report with recommendations (Epic 4 - Story 4.1 + 4.2)
- *
- * Generates a comprehensive quality report with coverage, quality metrics,
- * restart metrics, and recommendations for improvement.
- *
- * @param {Object} options - Report options
- * @param {string} [options.format='json'] - Output format: 'json' or 'markdown'
- * @param {string} [options.period='7d'] - Period for restart metrics: '24h', '7d', or '30d'
- * @param {Object} [options.thresholds] - Custom thresholds
- * @param {number} [options.thresholds.narrativeCoverage=0.8] - Narrative coverage threshold (0-1)
- * @param {number} [options.thresholds.linkCoverage=0.7] - Link coverage threshold (0-1)
- * @param {number} [options.thresholds.richReasonRatio=0.7] - Rich reason ratio threshold (0-1)
- * @param {number} [options.thresholds.restartSuccessRate=0.95] - Restart success rate threshold (0-1)
- * @param {number} [options.thresholds.restartLatencyP95Full=2500] - Full mode p95 latency threshold (ms)
- * @param {number} [options.thresholds.restartLatencyP95Summary=1000] - Summary mode p95 latency threshold (ms)
- * @returns {Object|string} Quality report as JSON or Markdown
- */
-declare function generateQualityReport(options?: QualityReportOptions): string | {
-    generated_at: string;
-    period: "24h" | "7d" | "30d" | null;
-    coverage: {
-        narrativeCoverage: string;
-        linkCoverage: string;
-        totalDecisions: number;
-        completeNarratives: number;
-        decisionsWithLinks: number;
-    };
-    quality: {
-        narrativeQuality: {
-            evidence: string;
-            alternatives: string;
-            risks: string;
-        };
-        linkQuality: {
-            richReasonRatio: string;
-            approvedRatio: string;
-            totalLinks: number;
-            richLinks: number;
-            approvedLinks: number;
-        };
-    };
-    restart: {
-        successRate: ReturnType<typeof calculateRestartSuccessRate>;
-        latency?: {
-            full: ReturnType<typeof calculateRestartLatency>;
-            summary: ReturnType<typeof calculateRestartLatency>;
-        };
-    };
-    thresholds: {
-        minSuccessRate?: number;
-        maxLatencyMs?: number;
-        narrativeCoverage: number;
-        linkCoverage: number;
-        richReasonRatio: number;
-        restartSuccessRate: number;
-        restartLatencyP95Full: number;
-        restartLatencyP95Summary: number;
-    };
-    recommendations: {
-        type: string;
-        message: string;
-        target: string;
-        current: string;
-    }[];
-    format: "json" | "markdown" | null;
-};
+ * Public write boundary for audit findings. The store writer takes the adapter
+ * from its caller; this edge resolves the ambient adapter so the
+ * MAMAApiInterface signature stays (input) => Promise<string>.
+ */
+declare function createAuditFinding(input: Parameters<typeof createAuditFindingInAdapter>[1]): Promise<string>;
+declare function upsertChannelSummary(input: Parameters<typeof upsertChannelSummaryInAdapter>[1]): Promise<void>;
+declare function getChannelSummary(channelKey: string): Promise<Awaited<ReturnType<typeof getChannelSummaryInAdapter>>>;
+declare function listOpenAuditFindings(): Promise<Awaited<ReturnType<typeof listOpenAuditFindingsInAdapter>>>;
+declare function listMemoryEventsForMemory(memoryId: string): Promise<Awaited<ReturnType<typeof listMemoryEventsForMemoryInAdapter>>>;
+declare function listRecentMemoryEvents(limit?: number): Promise<Awaited<ReturnType<typeof listRecentMemoryEventsInAdapter>>>;
+declare function getMemoryProvenance(memoryId: string, options?: Parameters<typeof getMemoryProvenanceInAdapter>[2]): Promise<Awaited<ReturnType<typeof getMemoryProvenanceInAdapter>>>;
+declare function listMemoriesByEnvelopeHash(envelopeHash: string, options?: Parameters<typeof listMemoriesByEnvelopeHashInAdapter>[2]): Promise<Awaited<ReturnType<typeof listMemoriesByEnvelopeHashInAdapter>>>;
+declare function listMemoriesByGatewayCallId(gatewayCallId: string, options?: Parameters<typeof listMemoriesByGatewayCallIdInAdapter>[2]): Promise<Awaited<ReturnType<typeof listMemoriesByGatewayCallIdInAdapter>>>;
+declare function listMemoriesByModelRunId(modelRunId: string, options?: Parameters<typeof listMemoriesByModelRunIdInAdapter>[2]): Promise<Awaited<ReturnType<typeof listMemoriesByModelRunIdInAdapter>>>;
+declare function saveMemory(input: Parameters<typeof saveMemoryInAdapter>[1]): Promise<Awaited<ReturnType<typeof saveMemoryInAdapter>>>;
+declare function recallMemory(query: string, options?: Parameters<typeof recallMemoryInAdapter>[2]): Promise<Awaited<ReturnType<typeof recallMemoryInAdapter>>>;
+declare function buildProfile(scopes: Parameters<typeof buildProfileInAdapter>[1]): Promise<Awaited<ReturnType<typeof buildProfileInAdapter>>>;
+declare function ingestMemory(input: Parameters<typeof ingestMemoryInAdapter>[1]): Promise<Awaited<ReturnType<typeof ingestMemoryInAdapter>>>;
+declare function ingestConversation(input: Parameters<typeof ingestConversationInAdapter>[1]): Promise<Awaited<ReturnType<typeof ingestConversationInAdapter>>>;
+declare function buildMemoryBootstrap(params: Parameters<typeof buildMemoryBootstrapInAdapter>[1]): Promise<Awaited<ReturnType<typeof buildMemoryBootstrapInAdapter>>>;
+declare function recordMemoryAudit(input: Parameters<typeof recordMemoryAuditInAdapter>[1]): Promise<Awaited<ReturnType<typeof recordMemoryAuditInAdapter>>>;
+declare function beginModelRun(input: Parameters<typeof beginModelRunInAdapter>[1]): Promise<Awaited<ReturnType<typeof beginModelRunInAdapter>>>;
+declare function commitModelRun(modelRunId: string, summary?: string, tokenCount?: number): Promise<Awaited<ReturnType<typeof commitModelRunInAdapter>>>;
+declare function failModelRun(modelRunId: string, errorSummary: string, tokenCount?: number): Promise<Awaited<ReturnType<typeof failModelRunInAdapter>>>;
+declare function getModelRun(modelRunId: string): Promise<Awaited<ReturnType<typeof getModelRunInAdapter>>>;
+declare function appendToolTrace(input: Parameters<typeof appendToolTraceInAdapter>[1]): Promise<Awaited<ReturnType<typeof appendToolTraceInAdapter>>>;
+declare function listToolTracesForRun(modelRunId: string): Promise<Awaited<ReturnType<typeof listToolTracesForRunInAdapter>>>;
+declare function listToolTraces(input: Parameters<typeof listToolTracesInAdapter>[1]): Promise<Awaited<ReturnType<typeof listToolTracesInAdapter>>>;
+declare function readToolTrace(traceId: string, scope: Parameters<typeof readToolTraceInAdapter>[2]): Promise<Awaited<ReturnType<typeof readToolTraceInAdapter>>>;
 /**
  * MAMA Public API
  *
@@ -1043,21 +340,83 @@ declare function generateQualityReport(options?: QualityReportOptions): string |
  * 3. Claude-First Design - Claude decides what to save
  * 4. Non-Intrusive - Silent failures for helpers (suggest)
  */
+/**
+ * Instance-bound MAMA API factory.
+ *
+ * Same member surface as the ambient `mama` object, but every call reads and
+ * writes through the adapter the owner hands in — no module-global handle is
+ * consulted. Products that own their database lifetime (openDatabase) bind
+ * once at boot and pass this object down; the ambient `mama` export remains
+ * the compatibility boundary for callers without an instance.
+ */
+export declare function createMamaApi(adapter: DatabaseInstance): {
+    save: (params: SaveParams) => Promise<SaveResult>;
+    suggest: (userQuestion: string, options?: SuggestFunctionOptions) => Promise<any>;
+    saveMemory: (input: Parameters<typeof saveMemoryInAdapter>[1]) => Promise<{
+        success: boolean;
+        id: string;
+        saved_decision_id?: string;
+    }>;
+    recallMemory: (query: Parameters<typeof recallMemoryInAdapter>[1], options?: Parameters<typeof recallMemoryInAdapter>[2]) => Promise<import("./index.js").RecallBundle>;
+    list: (options?: ListDecisionsOptions) => Promise<string | DecisionRecord[]>;
+    listDecisions: (options?: ListDecisionsOptions) => Promise<string | DecisionRecord[]>;
+    listCheckpoints: (limit?: number) => Promise<CheckpointRow[]>;
+    updateOutcome: (decisionId: string, outcome: UpdateOutcomeParams) => Promise<void>;
+    buildProfile: (scopes: Parameters<typeof buildProfileInAdapter>[1]) => Promise<import("./index.js").ProfileSnapshot>;
+    ingestMemory: (input: Parameters<typeof ingestMemoryInAdapter>[1]) => Promise<{
+        success: boolean;
+        id: string;
+    }>;
+    ingestConversation: (input: Parameters<typeof ingestConversationInAdapter>[1]) => Promise<import("./index.js").IngestConversationResult>;
+    evolveMemory: (input: Parameters<typeof evolveMemory>[0]) => Promise<import("./memory/evolution-engine.js").EvolutionResult>;
+    buildMemoryBootstrap: (params: Parameters<typeof buildMemoryBootstrapInAdapter>[1]) => Promise<import("./memory/types.js").MemoryAgentBootstrap>;
+    createAuditAck: (input: Parameters<typeof createAuditAck>[0]) => import("./memory/types.js").MemoryAuditAck;
+    recordMemoryAudit: (input: Parameters<typeof recordMemoryAuditInAdapter>[1]) => Promise<{
+        eventIds: string[];
+        findingIds: string[];
+        state: import("./memory/types.js").ChannelSummaryStateRecord;
+    }>;
+    upsertChannelSummary: (input: Parameters<typeof upsertChannelSummaryInAdapter>[1]) => void;
+    getChannelSummary: (channelKey: Parameters<typeof getChannelSummaryInAdapter>[1]) => Promise<import("./memory/types.js").ChannelSummaryRecord | null>;
+    listAuditFindings: () => Promise<import("./index.js").AuditFindingRecord[]>;
+    listOpenAuditFindings: () => Promise<import("./index.js").AuditFindingRecord[]>;
+    createAuditFinding: (input: Parameters<typeof createAuditFindingInAdapter>[1]) => string;
+    getMemoryProvenance: (memoryId: Parameters<typeof getMemoryProvenanceInAdapter>[1], options?: Parameters<typeof getMemoryProvenanceInAdapter>[2]) => Promise<import("./index.js").MemoryProvenanceRecord | null>;
+    listMemoriesByEnvelopeHash: (envelopeHash: Parameters<typeof listMemoriesByEnvelopeHashInAdapter>[1], options?: Parameters<typeof listMemoriesByEnvelopeHashInAdapter>[2]) => Promise<import("./index.js").MemoryProvenanceRecord[]>;
+    listMemoriesByGatewayCallId: (gatewayCallId: Parameters<typeof listMemoriesByGatewayCallIdInAdapter>[1], options?: Parameters<typeof listMemoriesByGatewayCallIdInAdapter>[2]) => Promise<import("./index.js").MemoryProvenanceRecord[]>;
+    listMemoriesByModelRunId: (modelRunId: Parameters<typeof listMemoriesByModelRunIdInAdapter>[1], options?: Parameters<typeof listMemoriesByModelRunIdInAdapter>[2]) => Promise<import("./index.js").MemoryProvenanceRecord[]>;
+    listMemoryEventsForMemory: (memoryId: Parameters<typeof listMemoryEventsForMemoryInAdapter>[1]) => Promise<import("./memory/types.js").MemoryEventRecord[]>;
+    listRecentMemoryEvents: (limit?: Parameters<typeof listRecentMemoryEventsInAdapter>[1]) => Promise<import("./memory/types.js").MemoryEventRecord[]>;
+    beginModelRun: (input: Parameters<typeof beginModelRunInAdapter>[1]) => import("./index.js").ModelRunRecord;
+    commitModelRun: (modelRunId: Parameters<typeof commitModelRunInAdapter>[1], summary?: Parameters<typeof commitModelRunInAdapter>[2], tokenCount?: Parameters<typeof commitModelRunInAdapter>[3]) => import("./index.js").ModelRunRecord;
+    failModelRun: (modelRunId: Parameters<typeof failModelRunInAdapter>[1], errorSummary: Parameters<typeof failModelRunInAdapter>[2], tokenCount?: Parameters<typeof failModelRunInAdapter>[3]) => import("./index.js").ModelRunRecord;
+    getModelRun: (modelRunId: Parameters<typeof getModelRunInAdapter>[1]) => import("./index.js").ModelRunRecord | null;
+    listModelRunNativeInputs: (modelRunId: Parameters<typeof listModelRunNativeInputsInAdapter>[1], principalId: Parameters<typeof listModelRunNativeInputsInAdapter>[2], options?: Parameters<typeof listModelRunNativeInputsInAdapter>[3]) => Promise<{
+        items: import("./runtime/model-run-store.js").ModelRunNativeInput[];
+        nextCursor: number | null;
+        runStatus: import("./index.js").ModelRunStatus;
+    }>;
+    appendToolTrace: (input: Parameters<typeof appendToolTraceInAdapter>[1]) => Promise<import("./index.js").ToolTraceRecord>;
+    listToolTracesForRun: (modelRunId: Parameters<typeof listToolTracesForRunInAdapter>[1]) => Promise<import("./index.js").ToolTraceRecord[]>;
+    listToolTraces: (input: Parameters<typeof listToolTracesInAdapter>[1]) => Promise<import("./index.js").ToolTracePage>;
+    readToolTrace: (traceId: Parameters<typeof readToolTraceInAdapter>[1], scope: Parameters<typeof readToolTraceInAdapter>[2]) => Promise<import("./index.js").ToolTraceRecord | null>;
+    saveCheckpoint: (summary: string, openFiles?: string[], nextSteps?: string, recentConversation?: any[]) => Promise<number | bigint>;
+    loadCheckpoint: () => Promise<CheckpointRow | null>;
+    recall: (topic: string, options?: RecallOptions) => Promise<string | RecallGraphResult>;
+    expandWithGraph: (candidates: SearchCandidate[]) => Promise<SearchCandidate[]>;
+};
+export type MamaApi = ReturnType<typeof createMamaApi>;
 declare const mama: {
     save: typeof save;
-    saveWithTrustedProvenance: typeof saveWithTrustedProvenance;
     suggest: typeof suggest;
     saveMemory: typeof saveMemory;
-    saveMemoryWithTrustedProvenance: typeof saveMemoryWithTrustedProvenance;
     recallMemory: typeof recallMemory;
     list: typeof listDecisions;
     listCheckpoints: typeof listCheckpoints;
     updateOutcome: typeof updateOutcome;
     buildProfile: typeof buildProfile;
     ingestMemory: typeof ingestMemory;
-    ingestWithTrustedProvenance: typeof ingestWithTrustedProvenance;
     ingestConversation: typeof ingestConversation;
-    ingestConversationWithTrustedProvenance: typeof ingestConversationWithTrustedProvenance;
     evolveMemory: typeof evolveMemory;
     buildMemoryBootstrap: typeof buildMemoryBootstrap;
     createAuditAck: typeof createAuditAck;
@@ -1074,13 +433,9 @@ declare const mama: {
     listMemoryEventsForMemory: typeof listMemoryEventsForMemory;
     listRecentMemoryEvents: typeof listRecentMemoryEvents;
     beginModelRun: typeof beginModelRun;
-    beginModelRunInAdapter: typeof beginModelRunInAdapter;
     commitModelRun: typeof commitModelRun;
-    commitModelRunInAdapter: typeof commitModelRunInAdapter;
     failModelRun: typeof failModelRun;
-    failModelRunInAdapter: typeof failModelRunInAdapter;
     getModelRun: typeof getModelRun;
-    getModelRunInAdapter: typeof getModelRunInAdapter;
     appendToolTrace: typeof appendToolTrace;
     listToolTracesForRun: typeof listToolTracesForRun;
     listToolTraces: typeof listToolTraces;
@@ -1088,27 +443,8 @@ declare const mama: {
     saveCheckpoint: typeof saveCheckpoint;
     loadCheckpoint: typeof loadCheckpoint;
     recall: typeof recall;
-    proposeLink: typeof proposeLink;
-    approveLink: typeof approveLink;
-    rejectLink: typeof rejectLink;
-    getPendingLinks: typeof getPendingLinks;
-    deprecateAutoLinks: typeof deprecateAutoLinks;
-    calculateCoverage: typeof calculateCoverage;
-    calculateQuality: typeof calculateQuality;
-    generateQualityReport: typeof generateQualityReport;
-    logRestartAttempt: typeof logRestartAttempt;
-    calculateRestartSuccessRate: typeof calculateRestartSuccessRate;
-    calculateRestartLatency: typeof calculateRestartLatency;
-    getRestartMetrics: typeof getRestartMetrics;
-    scanAutoLinks: typeof scanAutoLinks;
-    createLinkBackup: typeof createLinkBackup;
-    generatePreCleanupReport: typeof generatePreCleanupReport;
-    restoreLinkBackup: typeof restoreLinkBackup;
-    verifyBackupExists: typeof verifyBackupExists;
-    deleteAutoLinks: typeof deleteAutoLinks;
-    validateCleanupResult: typeof validateCleanupResult;
     expandWithGraph: typeof expandWithGraph;
 };
-export { save, saveWithTrustedProvenance, suggest, annotateTopicCurrency, saveMemory, saveMemoryWithTrustedProvenance, recallMemory, listDecisions as list, listCheckpoints, updateOutcome, buildProfile, ingestMemory, ingestWithTrustedProvenance, ingestConversation, ingestConversationWithTrustedProvenance, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary, listOpenAuditFindings, createAuditFinding, getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, listMemoryEventsForMemory, listRecentMemoryEvents, beginModelRun, beginModelRunInAdapter, commitModelRun, commitModelRunInAdapter, failModelRun, failModelRunInAdapter, getModelRun, getModelRunInAdapter, appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace, saveCheckpoint, loadCheckpoint, recall, proposeLink, approveLink, rejectLink, getPendingLinks, deprecateAutoLinks, calculateCoverage, calculateQuality, generateQualityReport, logRestartAttempt, calculateRestartSuccessRate, calculateRestartLatency, getRestartMetrics, scanAutoLinks, createLinkBackup, generatePreCleanupReport, restoreLinkBackup, verifyBackupExists, deleteAutoLinks, validateCleanupResult, expandWithGraph, };
+export { save, suggest, saveMemory, recallMemory, listDecisions as list, listCheckpoints, updateOutcome, buildProfile, ingestMemory, ingestConversation, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary, listOpenAuditFindings, createAuditFinding, getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, listMemoryEventsForMemory, listRecentMemoryEvents, beginModelRun, commitModelRun, failModelRun, getModelRun, appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace, saveCheckpoint, loadCheckpoint, recall, expandWithGraph, };
 export default mama;
 //# sourceMappingURL=mama-api.d.ts.map