@jungjaehoon/mama-core 2.4.0 → 2.4.1

package/db/migrations/068-tool-trace-diagnostics.sql

@@ -0,0 +1,13 @@
+-- TG-03/04/05: additive diagnostic evidence, scoped by host metadata.
+-- The migration runner reconciles existing MetricsStore scope columns idempotently.
+-- NULL scope preserves legacy records without granting discovery access.
+ALTER TABLE tool_traces ADD COLUMN diagnostic_json TEXT;
+ALTER TABLE tool_traces ADD COLUMN evidence_json TEXT;
+ALTER TABLE tool_traces ADD COLUMN catalog_revision TEXT;
+ALTER TABLE tool_traces ADD COLUMN owner_scope TEXT;
+ALTER TABLE tool_traces ADD COLUMN project_id TEXT;
+ALTER TABLE tool_traces ADD COLUMN channel_id TEXT;
+CREATE INDEX IF NOT EXISTS idx_tool_traces_scope_recency
+  ON tool_traces(owner_scope, project_id, created_at DESC, trace_id DESC);
+CREATE INDEX IF NOT EXISTS idx_tool_traces_channel_recency
+  ON tool_traces(owner_scope, project_id, channel_id, created_at DESC, trace_id DESC);

package/dist/db-adapter/node-sqlite-adapter.d.ts

@@ -66,6 +66,8 @@ export declare class NodeSQLiteAdapter extends DatabaseAdapter {
     private hasOperatorMemoryCommitIntentClaimInvariant;
     private assertMigration040BaseComplete;
     private assertMigration041Complete;
+    private needsToolTraceDiagnosticsRepair068;
+    private recoverToolTraceDiagnosticsMigration068;
     private recoverMemoryProvenanceMigration032;
     private assertMigration032Complete;
     private recoverConnectorEventScopeMigration034;

package/dist/db-adapter/node-sqlite-adapter.js

@@ -376,6 +376,18 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
             if (version <= currentVersion) {
                 continue;
             }
+            // Runtime MetricsStore may already own project_id/channel_id. Reconcile
+            // this additive migration atomically instead of accepting a duplicate skip.
+            if (version === 68) {
+                if (!this.tableExists('tool_traces')) {
+                    // Legacy version ledgers can have skipped 033; the structural repair
+                    // below creates its table before reconciling 068. Do not stamp it yet.
+                    continue;
+                }
+                this.recoverToolTraceDiagnosticsMigration068();
+                (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Migration ${file} reconciled successfully`);
+                continue;
+            }
             const migrationPath = path_1.default.join(migrationsDir, file);
             const migrationSQL = fs_1.default.readFileSync(migrationPath, 'utf8');
             (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Applying migration: ${file}`);
@@ -479,6 +491,14 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
         if (!this.tableExists('model_runs') || !this.tableExists('tool_traces')) {
             this.applyRepairMigration(migrationsDir, '033-create-model-runs-and-tool-traces.sql', 'model run provenance');
         }
+        // Also repairs databases already stamped 68 by the former generic duplicate
+        // skip, which rolled back the new columns before advancing schema_version.
+        // Only enter the recovery transaction when something is actually missing —
+        // a complete database must not take the write path on every runMigrations().
+        if (fs_1.default.existsSync(path_1.default.join(migrationsDir, '068-tool-trace-diagnostics.sql')) &&
+            this.needsToolTraceDiagnosticsRepair068()) {
+            this.recoverToolTraceDiagnosticsMigration068();
+        }
         if (this.tableExists('connector_event_index')) {
             const connectorColumns = this.tableColumns('connector_event_index');
             const hasMissingConnectorScopeColumn = [
@@ -647,6 +667,65 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
             throw new Error('Migration 041 recovery failed: incompatible operator_memory_commit_intents table definition missing claim invariant');
         }
     }
+    needsToolTraceDiagnosticsRepair068() {
+        if (!this.tableExists('tool_traces')) {
+            // The table itself is missing: let the recovery helper fail loudly.
+            return true;
+        }
+        const columns = this.tableColumns('tool_traces');
+        const hasMissingColumn = [
+            'diagnostic_json',
+            'evidence_json',
+            'catalog_revision',
+            'owner_scope',
+            'project_id',
+            'channel_id',
+        ].some((column) => !columns.has(column));
+        const hasMissingIndex = [
+            'idx_tool_traces_scope_recency',
+            'idx_tool_traces_channel_recency',
+        ].some((indexName) => !this.indexExists(indexName));
+        return hasMissingColumn || hasMissingIndex || !this.schemaVersionExists(68);
+    }
+    recoverToolTraceDiagnosticsMigration068() {
+        this.transaction(() => {
+            if (!this.tableExists('tool_traces')) {
+                throw new Error('Migration 068 recovery failed: missing table tool_traces');
+            }
+            const expectedColumns = [
+                'diagnostic_json',
+                'evidence_json',
+                'catalog_revision',
+                'owner_scope',
+                'project_id',
+                'channel_id',
+            ];
+            const columns = this.tableColumns('tool_traces');
+            for (const column of expectedColumns) {
+                if (!columns.has(column)) {
+                    this.exec(`ALTER TABLE tool_traces ADD COLUMN ${column} TEXT`);
+                }
+            }
+            this.exec(`
+        CREATE INDEX IF NOT EXISTS idx_tool_traces_scope_recency
+          ON tool_traces(owner_scope, project_id, created_at DESC, trace_id DESC);
+        CREATE INDEX IF NOT EXISTS idx_tool_traces_channel_recency
+          ON tool_traces(owner_scope, project_id, channel_id, created_at DESC, trace_id DESC);
+      `);
+            const actualColumns = this.tableColumns('tool_traces');
+            for (const column of expectedColumns) {
+                if (!actualColumns.has(column)) {
+                    throw new Error(`Migration 068 recovery failed: missing tool_traces.${column}`);
+                }
+            }
+            for (const index of ['idx_tool_traces_scope_recency', 'idx_tool_traces_channel_recency']) {
+                if (!this.indexExists(index)) {
+                    throw new Error(`Migration 068 recovery failed: missing index ${index}`);
+                }
+            }
+            this.prepare('INSERT OR IGNORE INTO schema_version (version) VALUES (?)').run(68);
+        });
+    }
     recoverMemoryProvenanceMigration032() {
         this.transaction(() => {
             const expectedDecisionColumns = [

package/dist/index.d.ts

@@ -25,9 +25,9 @@ export { createTrustedProvenanceCapability, assertTrustedProvenanceCapability, t
 export { getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, } from './memory/provenance-query.js';
 export { type BackfillResult, type ConnectorEventScopeBackfillInput, } from './memory/scope-backfill.js';
 export { getMemoryProvenanceAudit, listMemoryProvenanceAudit, type MemoryProvenanceAuditRecord, type MemoryProvenanceAuditListOptions, } from './memory/provenance-audit.js';
-export { MODEL_RUN_STATUSES, type ModelRunStatus, type BeginModelRunInput, type ModelRunRecord, type AppendToolTraceInput, type ToolTraceRecord, } from './model-runs/types.js';
+export { MODEL_RUN_STATUSES, type ModelRunStatus, type BeginModelRunInput, type ModelRunRecord, type AppendToolTraceInput, type ToolTraceRecord, type ToolTraceScope, type ListToolTracesInput, type ToolTracePage, } from './model-runs/types.js';
 export { beginModelRun, beginModelRunInAdapter, commitModelRun, commitModelRunInAdapter, failModelRun, failModelRunInAdapter, getModelRun, getModelRunInAdapter, } from './model-runs/store.js';
-export { appendToolTrace, listToolTracesForRun } from './model-runs/tool-trace-store.js';
+export { appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace, } from './model-runs/tool-trace-store.js';
 export { TWIN_EDGE_SOURCES, TWIN_EDGE_TYPES, TWIN_REF_KINDS, type InsertTwinEdgeInput, type ListVisibleTwinEdgesOptions, type TwinEdgeRecord, type TwinEdgeSource, type TwinEdgeType, type TwinRef, type TwinRefKind, type TwinScopeRef, } from './edges/types.js';
 export { getTwinEdge, listTwinEdgesForRefs, mapTwinEdgeRow } from './edges/store.js';
 export { listVisibleTwinEdgesForRefs } from './edges/ref-validation.js';

package/dist/index.js

@@ -27,9 +27,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestWithTrustedProvenance = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.promoteMemoryStatus = exports.saveMemoryWithTrustedProvenance = exports.saveMemory = exports.createEmptyRecallBundle = exports.MEMORY_EDGE_TYPES = exports.MEMORY_STATUSES = exports.MEMORY_KINDS = exports.MEMORY_SCOPE_KINDS = exports.mama = exports.DEFAULT_DB_PATH = exports.LEGACY_DB_PATH = exports.DB_DIR = exports.DB_PATH = exports.traverseDecisionChain = exports.SQLiteAdapter = exports.DatabaseAdapter = exports.createAdapter = exports.fts5Search = exports.getDbPath = exports.getPreparedStmt = exports.updateDecisionOutcome = exports.querySemanticEdges = exports.queryDecisionGraph = exports.insertDecisionWithEmbedding = exports.queryVectorSearch = exports.vectorSearch = exports.insertEmbedding = exports.closeDB = exports.getAdapter = exports.getDB = exports.initDB = exports.TIMEOUT_MS = exports.HOST = exports.DEFAULT_PORT = exports.getServerPort = exports.EmbeddingCache = exports.EMBEDDING_PREFIX_SCHEME = exports.MODEL_NAME = exports.EMBEDDING_DIM = exports.embeddingCache = exports.cosineSimilarity = exports.generateEnhancedEmbedding = exports.generateEmbedding = void 0;
-exports.getConfigPath = exports.updateConfig = exports.getCacheDir = exports.getEmbeddingDim = exports.getModelName = exports.loadConfig = exports.CanonicalizeError = exports.targetRefHash = exports.canonicalizeJSON = exports.listVisibleTwinEdgesForRefs = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.getTwinEdge = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.listToolTracesForRun = exports.appendToolTrace = exports.getModelRunInAdapter = exports.getModelRun = exports.failModelRunInAdapter = exports.failModelRun = exports.commitModelRunInAdapter = exports.commitModelRun = exports.beginModelRunInAdapter = exports.beginModelRun = exports.MODEL_RUN_STATUSES = exports.listMemoryProvenanceAudit = exports.getMemoryProvenanceAudit = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.assertTrustedProvenanceCapability = exports.createTrustedProvenanceCapability = exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = exports.insertMemoryEventInTransaction = exports.appendMemoryEvent = exports.listOpenAuditFindings = exports.createAuditFinding = exports.queryRelevantTruth = exports.parseExtractionResponse = exports.buildExtractionPrompt = exports.getChannelSummary = exports.upsertChannelSummary = exports.setExtractionFn = exports.ingestConversationWithTrustedProvenance = exports.ingestConversation = exports.recordMemoryAudit = void 0;
-exports.formatTrustContext = exports.formatList = exports.formatRecall = exports.formatLegacyContext = exports.formatContext = exports.isMAMAError = exports.wrapError = exports.ErrorCodes = exports.TimeoutError = exports.RateLimitError = exports.LinkError = exports.ConfigurationError = exports.EmbeddingError = exports.DatabaseError = exports.ValidationError = exports.NotFoundError = exports.MAMAError = exports.formatTimeAgo = exports.DebugLogger = exports.error = exports.warn = exports.info = exports.debug = exports.logSearching = exports.logLoading = exports.logError = exports.logFailed = exports.logComplete = exports.logProgress = exports.getTierDescription = exports.checkDatabase = exports.checkEmbeddings = exports.checkSQLite = exports.checkNodeVersion = exports.VALID_EDGE_TYPES = exports.updateConfidence = exports.createEdgesFromReasoning = exports.parseReasoningForRelationships = exports.detectRefinement = exports.calculateCombinedConfidence = exports.markSuperseded = exports.createSupersedesEdge = exports.createEdge = exports.getPreviousDecision = exports.generateDecisionId = exports.learnDecision = exports.formatTopNContext = exports.selectTopDecisions = exports.calculateRelevance = exports.DEFAULT_CONFIG = void 0;
-exports.notifyInsight = exports.FALLBACK_MODEL = exports.DEFAULT_MODEL = exports.listModels = exports.isAvailable = exports.generate = exports.analyzeIntent = exports.RECENT_WINDOW_MS = exports.PARTIAL_INDICATORS = exports.SUCCESS_INDICATORS = exports.FAILURE_INDICATORS = exports.markOutcome = exports.getEvidenceImpact = exports.calculateDurationDays = exports.getRecentDecision = exports.extractFailureReason = exports.matchesPartialIndicators = exports.matchesSuccessIndicators = exports.matchesFailureIndicators = exports.analyzeOutcome = exports.extractCodeExample = exports.extractQuickAnswer = exports.estimateTokens = exports.ensureTokenBudget = void 0;
+exports.getCacheDir = exports.getEmbeddingDim = exports.getModelName = exports.loadConfig = exports.CanonicalizeError = exports.targetRefHash = exports.canonicalizeJSON = exports.listVisibleTwinEdgesForRefs = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.getTwinEdge = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.readToolTrace = exports.listToolTraces = exports.listToolTracesForRun = exports.appendToolTrace = exports.getModelRunInAdapter = exports.getModelRun = exports.failModelRunInAdapter = exports.failModelRun = exports.commitModelRunInAdapter = exports.commitModelRun = exports.beginModelRunInAdapter = exports.beginModelRun = exports.MODEL_RUN_STATUSES = exports.listMemoryProvenanceAudit = exports.getMemoryProvenanceAudit = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.assertTrustedProvenanceCapability = exports.createTrustedProvenanceCapability = exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = exports.insertMemoryEventInTransaction = exports.appendMemoryEvent = exports.listOpenAuditFindings = exports.createAuditFinding = exports.queryRelevantTruth = exports.parseExtractionResponse = exports.buildExtractionPrompt = exports.getChannelSummary = exports.upsertChannelSummary = exports.setExtractionFn = exports.ingestConversationWithTrustedProvenance = exports.ingestConversation = exports.recordMemoryAudit = void 0;
+exports.formatRecall = exports.formatLegacyContext = exports.formatContext = exports.isMAMAError = exports.wrapError = exports.ErrorCodes = exports.TimeoutError = exports.RateLimitError = exports.LinkError = exports.ConfigurationError = exports.EmbeddingError = exports.DatabaseError = exports.ValidationError = exports.NotFoundError = exports.MAMAError = exports.formatTimeAgo = exports.DebugLogger = exports.error = exports.warn = exports.info = exports.debug = exports.logSearching = exports.logLoading = exports.logError = exports.logFailed = exports.logComplete = exports.logProgress = exports.getTierDescription = exports.checkDatabase = exports.checkEmbeddings = exports.checkSQLite = exports.checkNodeVersion = exports.VALID_EDGE_TYPES = exports.updateConfidence = exports.createEdgesFromReasoning = exports.parseReasoningForRelationships = exports.detectRefinement = exports.calculateCombinedConfidence = exports.markSuperseded = exports.createSupersedesEdge = exports.createEdge = exports.getPreviousDecision = exports.generateDecisionId = exports.learnDecision = exports.formatTopNContext = exports.selectTopDecisions = exports.calculateRelevance = exports.DEFAULT_CONFIG = exports.getConfigPath = exports.updateConfig = void 0;
+exports.notifyInsight = exports.FALLBACK_MODEL = exports.DEFAULT_MODEL = exports.listModels = exports.isAvailable = exports.generate = exports.analyzeIntent = exports.RECENT_WINDOW_MS = exports.PARTIAL_INDICATORS = exports.SUCCESS_INDICATORS = exports.FAILURE_INDICATORS = exports.markOutcome = exports.getEvidenceImpact = exports.calculateDurationDays = exports.getRecentDecision = exports.extractFailureReason = exports.matchesPartialIndicators = exports.matchesSuccessIndicators = exports.matchesFailureIndicators = exports.analyzeOutcome = exports.extractCodeExample = exports.extractQuickAnswer = exports.estimateTokens = exports.ensureTokenBudget = exports.formatTrustContext = exports.formatList = void 0;
 var embeddings_js_1 = require("./embeddings.js");
 Object.defineProperty(exports, "generateEmbedding", { enumerable: true, get: function () { return embeddings_js_1.generateEmbedding; } });
 Object.defineProperty(exports, "generateEnhancedEmbedding", { enumerable: true, get: function () { return embeddings_js_1.generateEnhancedEmbedding; } });
@@ -133,6 +133,8 @@ Object.defineProperty(exports, "getModelRunInAdapter", { enumerable: true, get:
 var tool_trace_store_js_1 = require("./model-runs/tool-trace-store.js");
 Object.defineProperty(exports, "appendToolTrace", { enumerable: true, get: function () { return tool_trace_store_js_1.appendToolTrace; } });
 Object.defineProperty(exports, "listToolTracesForRun", { enumerable: true, get: function () { return tool_trace_store_js_1.listToolTracesForRun; } });
+Object.defineProperty(exports, "listToolTraces", { enumerable: true, get: function () { return tool_trace_store_js_1.listToolTraces; } });
+Object.defineProperty(exports, "readToolTrace", { enumerable: true, get: function () { return tool_trace_store_js_1.readToolTrace; } });
 var types_js_3 = require("./edges/types.js");
 Object.defineProperty(exports, "TWIN_EDGE_SOURCES", { enumerable: true, get: function () { return types_js_3.TWIN_EDGE_SOURCES; } });
 Object.defineProperty(exports, "TWIN_EDGE_TYPES", { enumerable: true, get: function () { return types_js_3.TWIN_EDGE_TYPES; } });

package/dist/mama-api.d.ts

@@ -25,7 +25,7 @@ import { listMemoryEventsForMemory, listRecentMemoryEvents } from './memory/even
 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 } from './model-runs/tool-trace-store.js';
+import { appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace } from './model-runs/tool-trace-store.js';
 import { type SearchHitDiagnostics, type SearchQualityOptions } from './search/search-quality.js';
 /**
  * Parameters for mama.save()
@@ -1083,6 +1083,8 @@ declare const mama: {
     getModelRunInAdapter: typeof getModelRunInAdapter;
     appendToolTrace: typeof appendToolTrace;
     listToolTracesForRun: typeof listToolTracesForRun;
+    listToolTraces: typeof listToolTraces;
+    readToolTrace: typeof readToolTrace;
     saveCheckpoint: typeof saveCheckpoint;
     loadCheckpoint: typeof loadCheckpoint;
     recall: typeof recall;
@@ -1107,6 +1109,6 @@ declare const mama: {
     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, 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, 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 default mama;
 //# sourceMappingURL=mama-api.d.ts.map

package/dist/mama-api.js

@@ -22,7 +22,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listToolTracesForRun = exports.appendToolTrace = exports.getModelRunInAdapter = exports.getModelRun = exports.failModelRunInAdapter = exports.failModelRun = exports.commitModelRunInAdapter = exports.commitModelRun = exports.beginModelRunInAdapter = exports.beginModelRun = exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.createAuditFinding = exports.listOpenAuditFindings = exports.getChannelSummary = exports.upsertChannelSummary = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestConversationWithTrustedProvenance = exports.ingestConversation = exports.ingestWithTrustedProvenance = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.saveMemoryWithTrustedProvenance = exports.saveMemory = void 0;
+exports.readToolTrace = exports.listToolTraces = exports.listToolTracesForRun = exports.appendToolTrace = exports.getModelRunInAdapter = exports.getModelRun = exports.failModelRunInAdapter = exports.failModelRun = exports.commitModelRunInAdapter = exports.commitModelRun = exports.beginModelRunInAdapter = exports.beginModelRun = exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.createAuditFinding = exports.listOpenAuditFindings = exports.getChannelSummary = exports.upsertChannelSummary = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestConversationWithTrustedProvenance = exports.ingestConversation = exports.ingestWithTrustedProvenance = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.saveMemoryWithTrustedProvenance = exports.saveMemory = void 0;
 exports.save = save;
 exports.saveWithTrustedProvenance = saveWithTrustedProvenance;
 exports.suggest = suggest;
@@ -106,6 +106,8 @@ Object.defineProperty(exports, "getModelRunInAdapter", { enumerable: true, get:
 const tool_trace_store_js_1 = require("./model-runs/tool-trace-store.js");
 Object.defineProperty(exports, "appendToolTrace", { enumerable: true, get: function () { return tool_trace_store_js_1.appendToolTrace; } });
 Object.defineProperty(exports, "listToolTracesForRun", { enumerable: true, get: function () { return tool_trace_store_js_1.listToolTracesForRun; } });
+Object.defineProperty(exports, "listToolTraces", { enumerable: true, get: function () { return tool_trace_store_js_1.listToolTraces; } });
+Object.defineProperty(exports, "readToolTrace", { enumerable: true, get: function () { return tool_trace_store_js_1.readToolTrace; } });
 const search_rollup_js_1 = require("./cases/search-rollup.js");
 const ranker_rescore_js_1 = require("./search/ranker-rescore.js");
 const ranker_features_js_1 = require("./search/ranker-features.js");
@@ -2832,6 +2834,8 @@ const mama = {
     getModelRunInAdapter: store_js_1.getModelRunInAdapter,
     appendToolTrace: tool_trace_store_js_1.appendToolTrace,
     listToolTracesForRun: tool_trace_store_js_1.listToolTracesForRun,
+    listToolTraces: tool_trace_store_js_1.listToolTraces,
+    readToolTrace: tool_trace_store_js_1.readToolTrace,
     saveCheckpoint,
     loadCheckpoint,
     // Legacy functions (retained for internal use, not exposed via MCP)

package/dist/model-runs/tool-trace-store.d.ts

@@ -1,4 +1,8 @@
-import type { AppendToolTraceInput, ToolTraceRecord } from './types.js';
+import type { AppendToolTraceInput, ToolTraceRecord, ToolTraceScope, ListToolTracesInput, ToolTracePage } from './types.js';
 export declare function appendToolTrace(input: AppendToolTraceInput): Promise<ToolTraceRecord>;
 export declare function listToolTracesForRun(modelRunId: string): Promise<ToolTraceRecord[]>;
+/** Access is exact host-derived scope; knowing a trace ID never grants access. */
+export declare function readToolTrace(traceId: string, scope: ToolTraceScope): Promise<ToolTraceRecord | null>;
+/** Bounded metadata discovery; detailed evidence is read explicitly by trace ID. */
+export declare function listToolTraces(input: ListToolTracesInput): Promise<ToolTracePage>;
 //# sourceMappingURL=tool-trace-store.d.ts.map

package/dist/model-runs/tool-trace-store.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.appendToolTrace = appendToolTrace;
 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() {
@@ -47,8 +49,33 @@ function requiredNonNegativeInteger(value, field) {
     }
     return normalized;
 }
+function nullableJsonObject(value, field) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`tool_traces.${field} must be a JSON object string`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error(`tool_traces.${field} contains malformed JSON`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`tool_traces.${field} must contain a JSON object`);
+    }
+    return value;
+}
 function mapToolTraceRow(row) {
     return {
+        diagnostic_json: nullableJsonObject(row.diagnostic_json, 'diagnostic_json'),
+        evidence_json: nullableJsonObject(row.evidence_json, 'evidence_json'),
+        catalog_revision: nullableString(row.catalog_revision),
+        owner_scope: nullableString(row.owner_scope),
+        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'),
         gateway_call_id: nullableString(row.gateway_call_id),
@@ -72,7 +99,7 @@ function selectToolTrace(adapter, id) {
         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
+          created_at, diagnostic_json, evidence_json, catalog_revision, owner_scope, project_id, channel_id
         FROM tool_traces
         WHERE trace_id = ?
       `)
@@ -92,11 +119,11 @@ async function appendToolTrace(input) {
         INSERT INTO tool_traces (
           trace_id, model_run_id, gateway_call_id, tool_name, input_summary,
           output_summary, execution_status, duration_ms, envelope_hash, failure_code,
-          created_at
+          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));
+        .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));
     return selectToolTrace(adapter, id);
 }
 async function listToolTracesForRun(modelRunId) {
@@ -107,7 +134,7 @@ async function listToolTracesForRun(modelRunId) {
         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
+          created_at, diagnostic_json, evidence_json, catalog_revision, owner_scope, project_id, channel_id
         FROM tool_traces
         WHERE model_run_id = ?
         ORDER BY created_at DESC, rowid DESC
@@ -115,4 +142,82 @@ async function listToolTracesForRun(modelRunId) {
         .all(id);
     return rows.map(mapToolTraceRow);
 }
+function scopedWhere(scope) {
+    const clauses = ['owner_scope = ?', 'project_id = ?'];
+    const values = [
+        requiredString(scope.owner_scope, 'owner_scope'),
+        requiredString(scope.project_id, 'project_id'),
+    ];
+    if (scope.channel_id !== undefined) {
+        clauses.push('channel_id = ?');
+        values.push(requiredString(scope.channel_id, 'channel_id'));
+    }
+    return { clauses, values };
+}
+/** Access is exact host-derived scope; knowing a trace ID never grants access. */
+async function readToolTrace(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) {
+    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');
+    }
+    if (input.evidence_only === true) {
+        clauses.push('evidence_json IS NOT NULL');
+    }
+    const limit = input.limit ?? 20;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+        throw new Error('tool_traces.limit must be an integer between 1 and 100');
+    }
+    for (const field of ['model_run_id', 'tool_name']) {
+        if (input[field] !== undefined) {
+            clauses.push(`${field} = ?`);
+            values.push(requiredString(input[field], field));
+        }
+    }
+    if (input.cursor !== undefined) {
+        let cursor;
+        try {
+            cursor = JSON.parse(Buffer.from(input.cursor, 'base64url').toString('utf8'));
+        }
+        catch {
+            throw new Error('tool_traces.cursor is malformed');
+        }
+        if (!Array.isArray(cursor) || cursor.length !== 2) {
+            throw new Error('tool_traces.cursor is malformed');
+        }
+        const [cursorCreatedAt, cursorTraceId] = cursor;
+        if (typeof cursorCreatedAt !== 'number' ||
+            !Number.isSafeInteger(cursorCreatedAt) ||
+            typeof cursorTraceId !== 'string' ||
+            cursorTraceId.length === 0) {
+            throw new Error('tool_traces.cursor is malformed');
+        }
+        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,
+    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 ')}
+    ORDER BY created_at DESC, trace_id DESC LIMIT ?`)
+        .all(...values, limit + 1);
+    const traces = rows.slice(0, limit).map(mapToolTraceRow);
+    const last = traces.at(-1);
+    const next_cursor = rows.length > limit && last
+        ? Buffer.from(JSON.stringify([last.created_at, last.trace_id])).toString('base64url')
+        : null;
+    return { traces, next_cursor };
+}
 //# sourceMappingURL=tool-trace-store.js.map

package/dist/model-runs/types.d.ts

@@ -43,6 +43,13 @@ export interface ModelRunRecord {
     completed_at: number | null;
 }
 export interface AppendToolTraceInput {
+    /** Host-derived access scope; legacy rows remain unscoped. */
+    owner_scope?: string | null;
+    project_id?: string | null;
+    channel_id?: string | null;
+    diagnostic_json?: string | null;
+    evidence_json?: string | null;
+    catalog_revision?: string | null;
     trace_id?: string;
     model_run_id: string;
     gateway_call_id?: string | null;
@@ -57,6 +64,13 @@ export interface AppendToolTraceInput {
     created_at?: number;
 }
 export interface ToolTraceRecord {
+    /** Host-derived access scope; legacy rows remain unscoped. */
+    owner_scope?: string | null;
+    project_id?: string | null;
+    channel_id?: string | null;
+    diagnostic_json?: string | null;
+    evidence_json?: string | null;
+    catalog_revision?: string | null;
     trace_id: string;
     model_run_id: string;
     gateway_call_id: string | null;
@@ -69,4 +83,21 @@ export interface ToolTraceRecord {
     failure_code: string | null;
     created_at: number;
 }
+export interface ToolTraceScope {
+    owner_scope: string;
+    project_id: string;
+    channel_id?: string;
+}
+export interface ListToolTracesInput extends ToolTraceScope {
+    evidence_only?: boolean;
+    model_run_id?: string;
+    tool_name?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface ToolTracePage {
+    /** Metadata only: evidence_json is null. Read a scoped trace for details. */
+    traces: ToolTraceRecord[];
+    next_cursor: string | null;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-core",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "MAMA Core - Shared modules for Memory-Augmented MCP Assistant",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",