@jungjaehoon/mama-core 2.3.0 → 2.4.1

package/db/migrations/067-add-connector-event-source-entity-id.sql

@@ -0,0 +1,14 @@
+-- Migration 067: give connector_event_index a first-class source_entity_id so an agent can read an
+-- entity's change history (the revisions save() preserves) through the same grant-bounded core index
+-- it already searches. Previously sourceEntityId lived only inside metadata_json, with no by-entity
+-- query. Additive and backward-compatible: existing rows are backfilled from metadata_json.
+ALTER TABLE connector_event_index ADD COLUMN source_entity_id TEXT;
+
+UPDATE connector_event_index
+  SET source_entity_id = json_extract(metadata_json, '$.sourceEntityId')
+  WHERE source_entity_id IS NULL
+    AND metadata_json IS NOT NULL
+    AND json_extract(metadata_json, '$.sourceEntityId') IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_connector_event_source_entity
+  ON connector_event_index(source_connector, source_entity_id);

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/connectors/event-index.js

@@ -135,15 +135,16 @@ function upsertConnectorEventIndex(adapter, input) {
         adapter
             .prepare(`
           INSERT INTO connector_event_index (
-            event_index_id, source_connector, source_type, source_id, source_locator,
-            channel, author, title, content, event_datetime, event_date, source_timestamp_ms,
-            source_cursor, tenant_id, project_id, memory_scope_kind, memory_scope_id,
-            metadata_json, artifact_locator, artifact_title, content_hash, indexed_at, updated_at,
-            expires_at
+            event_index_id, source_connector, source_type, source_id, source_entity_id,
+            source_locator, channel, author, title, content, event_datetime, event_date,
+            source_timestamp_ms, source_cursor, tenant_id, project_id, memory_scope_kind,
+            memory_scope_id, metadata_json, artifact_locator, artifact_title, content_hash,
+            indexed_at, updated_at, expires_at
           )
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
           ON CONFLICT(source_connector, source_id) DO UPDATE SET
             source_type = excluded.source_type,
+            source_entity_id = excluded.source_entity_id,
             source_locator = excluded.source_locator,
             channel = excluded.channel,
             author = excluded.author,
@@ -182,7 +183,7 @@ function upsertConnectorEventIndex(adapter, input) {
               ELSE connector_event_index.operator_observation_seq
             END
         `)
-            .run(eventIndexId, input.source_connector, input.source_type, input.source_id, input.source_locator ?? null, input.channel ?? null, input.author ?? null, input.title ?? null, input.content, eventDatetime, eventDate, sourceTimestampMs, input.source_cursor ?? null, input.tenant_id ?? null, input.project_id ?? null, input.memory_scope_kind ?? null, input.memory_scope_id ?? null, metadataJson, input.artifact_locator ?? null, input.artifact_title ?? null, contentHash, input.indexed_at ?? timestamp, timestamp, input.expires_at ?? null);
+            .run(eventIndexId, input.source_connector, input.source_type, input.source_id, input.source_entity_id ?? input.source_id, input.source_locator ?? null, input.channel ?? null, input.author ?? null, input.title ?? null, input.content, eventDatetime, eventDate, sourceTimestampMs, input.source_cursor ?? null, input.tenant_id ?? null, input.project_id ?? null, input.memory_scope_kind ?? null, input.memory_scope_id ?? null, metadataJson, input.artifact_locator ?? null, input.artifact_title ?? null, contentHash, input.indexed_at ?? timestamp, timestamp, input.expires_at ?? null);
         const saved = getConnectorEventIndexRecord(adapter, input.source_connector, input.source_id);
         if (!saved) {
             throw new Error(`Failed to read connector_event_index row after upsert: ${input.source_connector}/${input.source_id}`);

package/dist/connectors/raw-query.d.ts

@@ -1,5 +1,5 @@
 import type { DatabaseAdapter } from '../db-manager.js';
-import type { RawSearchHit, RawSearchInput, RawSearchResult, RawSearchScopeFilter } from './types.js';
+import type { RawSearchHit, RawDocument, RawSearchInput, RawSearchResult, RawSearchScopeFilter } from './types.js';
 type RawQueryAdapter = Pick<DatabaseAdapter, 'prepare'>;
 interface RawWindowInput {
     connectors?: string[];
@@ -9,10 +9,32 @@ interface RawWindowInput {
 }
 export declare function searchRaw(adapter: RawQueryAdapter, input: RawSearchInput): RawSearchResult;
 export declare function searchAllRaw(adapter: RawQueryAdapter, input: RawSearchInput): RawSearchResult;
-export declare function getRawById(adapter: RawQueryAdapter, rawId: string, visibility: Pick<RawSearchInput, 'connectors' | 'scopes'>): RawSearchHit | null;
+export declare function getRawById(adapter: RawQueryAdapter, rawId: string, visibility: Pick<RawSearchInput, 'connectors' | 'scopes'>): RawDocument | null;
 export declare function getRawWindow(adapter: RawQueryAdapter, rawId: string, input: RawWindowInput): {
     target: RawSearchHit;
     items: RawSearchHit[];
 } | null;
+export interface RawHistoryInput {
+    /** The entity whose revisions to read. Provide this OR `rawId`. */
+    entityId?: string;
+    /**
+     * A raw event id (event_index_id) to anchor on: its entity is resolved under the SAME
+     * visibility, then that entity's revisions are returned. An anchor the caller may not see
+     * resolves to nothing, so a rawId cannot widen what the caller can read.
+     */
+    rawId?: string;
+    connectors?: string[];
+    scopes?: RawSearchScopeFilter[];
+    fromMs?: number;
+    toMs?: number;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Chronological change history of one upstream entity (rows sharing source_entity_id), bounded by
+ * the SAME connector/scope visibility as search - a citation must not out-read reading. Oldest first,
+ * cursor-paged. Rows with a NULL source_entity_id (no revision grouping) never match an entity query.
+ */
+export declare function getRawHistory(adapter: RawQueryAdapter, input: RawHistoryInput): RawSearchResult;
 export type { RawSearchHit, RawSearchInput, RawSearchResult, RawSearchScopeFilter, } from './types.js';
 //# sourceMappingURL=raw-query.d.ts.map

package/dist/connectors/raw-query.js

@@ -4,6 +4,7 @@ exports.searchRaw = searchRaw;
 exports.searchAllRaw = searchAllRaw;
 exports.getRawById = getRawById;
 exports.getRawWindow = getRawWindow;
+exports.getRawHistory = getRawHistory;
 const types_js_1 = require("../memory/types.js");
 const event_index_js_1 = require("./event-index.js");
 const DEFAULT_RAW_LIMIT = 25;
@@ -220,7 +221,7 @@ function getRawById(adapter, rawId, visibility) {
         LIMIT 1
       `)
         .get(...params);
-    return row ? toRawHit(row) : null;
+    return row ? { ...toRawHit(row), content: String(row.content) } : null;
 }
 function getRawWindow(adapter, rawId, input) {
     const targetParams = [rawId];
@@ -302,4 +303,110 @@ function afterWindowRows(adapter, target, input, limit) {
       `)
         .all(...params, limit);
 }
+// The entity a raw event belongs to, plus its connector. source_entity_id is unique only WITHIN a
+// connector, so history must carry the connector too or two connectors sharing an id would merge.
+function resolveEntityAnchor(adapter, rawId, visibility) {
+    const clauses = ['e.event_index_id = ?'];
+    const params = [rawId];
+    appendFilters(clauses, params, { query: '*', ...visibility });
+    const row = adapter
+        .prepare(`SELECT source_entity_id, source_connector FROM connector_event_index e WHERE ${clauses.join(' AND ')} LIMIT 1`)
+        .get(...params);
+    return row &&
+        typeof row.source_entity_id === 'string' &&
+        row.source_entity_id.length > 0 &&
+        typeof row.source_connector === 'string' &&
+        row.source_connector.length > 0
+        ? { entityId: row.source_entity_id, connector: row.source_connector }
+        : null;
+}
+function singleConnector(connectors) {
+    const normalized = normalizeConnectors(connectors);
+    return normalized.length === 1 ? normalized[0] : null;
+}
+function encodeHistoryCursor(row) {
+    return Buffer.from(JSON.stringify({ timestampMs: row.source_timestamp_ms, rawId: row.event_index_id }), 'utf8').toString('base64url');
+}
+function decodeHistoryCursor(cursor) {
+    if (!cursor) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (typeof parsed.timestampMs !== 'number' ||
+            !Number.isFinite(parsed.timestampMs) ||
+            typeof parsed.rawId !== 'string' ||
+            parsed.rawId.length === 0) {
+            throw new Error('invalid shape');
+        }
+        return { timestampMs: parsed.timestampMs, rawId: parsed.rawId };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid raw history cursor: ${message}`);
+    }
+}
+/**
+ * Chronological change history of one upstream entity (rows sharing source_entity_id), bounded by
+ * the SAME connector/scope visibility as search - a citation must not out-read reading. Oldest first,
+ * cursor-paged. Rows with a NULL source_entity_id (no revision grouping) never match an entity query.
+ */
+function getRawHistory(adapter, input) {
+    // Revision identity is connector-scoped. The rawId path takes the anchor's own connector; the
+    // entityId path requires the caller to name exactly one connector, since an entity id alone is
+    // ambiguous across connectors.
+    const trimmedEntityId = input.entityId?.trim() ?? '';
+    const anchor = trimmedEntityId.length > 0
+        ? (() => {
+            const connector = singleConnector(input.connectors);
+            return connector ? { entityId: trimmedEntityId, connector } : null;
+        })()
+        : input.rawId && input.rawId.trim().length > 0
+            ? resolveEntityAnchor(adapter, input.rawId.trim(), {
+                connectors: input.connectors,
+                scopes: input.scopes,
+            })
+            : null;
+    if (!anchor) {
+        return { hits: [], next_cursor: null };
+    }
+    const limit = normalizeLimit(input.limit);
+    if (limit === 0) {
+        return { hits: [], next_cursor: null };
+    }
+    const clauses = ['e.source_entity_id = ?'];
+    const params = [anchor.entityId];
+    appendFilters(clauses, params, {
+        query: '*',
+        connectors: [anchor.connector],
+        scopes: input.scopes,
+        fromMs: input.fromMs,
+        toMs: input.toMs,
+    });
+    const cursor = decodeHistoryCursor(input.cursor);
+    if (cursor) {
+        clauses.push('(e.source_timestamp_ms > ? OR (e.source_timestamp_ms = ? AND e.event_index_id > ?))');
+        params.push(cursor.timestampMs, cursor.timestampMs, cursor.rawId);
+    }
+    const rows = adapter
+        .prepare(`
+        SELECT e.*, 0 AS rank
+        FROM connector_event_index e
+        WHERE ${clauses.join(' AND ')}
+        ORDER BY e.source_timestamp_ms ASC, e.event_index_id ASC
+        LIMIT ?
+      `)
+        .all(...params, limit + 1);
+    const pageRows = rows.slice(0, limit);
+    const nextRow = rows.length > limit ? pageRows[pageRows.length - 1] : undefined;
+    return {
+        hits: pageRows.map(toRawHit),
+        next_cursor: nextRow
+            ? encodeHistoryCursor({
+                source_timestamp_ms: Number(nextRow.source_timestamp_ms),
+                event_index_id: String(nextRow.event_index_id),
+            })
+            : null,
+    };
+}
 //# sourceMappingURL=raw-query.js.map

package/dist/connectors/types.d.ts

@@ -32,6 +32,8 @@ export interface UpsertConnectorEventIndexInput {
     source_connector: string;
     source_type: string;
     source_id: string;
+    /** Stable upstream entity across revisions; enables grant-bounded change-history reads. */
+    source_entity_id?: string | null;
     source_locator?: string | null;
     channel?: string | null;
     author?: string | null;
@@ -103,6 +105,10 @@ export interface RawSearchHit {
     source_ref: string | null;
     metadata: Record<string, unknown>;
 }
+/** Explicit detail access includes the complete source; search results remain bounded previews. */
+export interface RawDocument extends RawSearchHit {
+    content: string;
+}
 export interface RawSearchResult {
     hits: RawSearchHit[];
     next_cursor: string | null;

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

@@ -66,10 +66,14 @@ export declare class NodeSQLiteAdapter extends DatabaseAdapter {
     private hasOperatorMemoryCommitIntentClaimInvariant;
     private assertMigration040BaseComplete;
     private assertMigration041Complete;
+    private needsToolTraceDiagnosticsRepair068;
+    private recoverToolTraceDiagnosticsMigration068;
     private recoverMemoryProvenanceMigration032;
     private assertMigration032Complete;
     private recoverConnectorEventScopeMigration034;
     private assertMigration034Complete;
+    private recoverConnectorEventSourceEntityIdMigration067;
+    private assertMigration067Complete;
     private recoverConnectorEventOperatorSeqMigration039;
     private assertMigration039Complete;
     private recoverConnectorEventSequencesMigration062;

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}`);
@@ -409,6 +421,11 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
                     (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Migration ${file} recovered successfully`);
                     continue;
                 }
+                if (message.includes('duplicate column') && version === 67) {
+                    this.recoverConnectorEventSourceEntityIdMigration067();
+                    (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Migration ${file} recovered successfully`);
+                    continue;
+                }
                 if (message.includes('no such column') && version === 62) {
                     (0, debug_logger_js_1.warn)(`[node-sqlite-adapter] Migration ${file} deferred until connector structure recovery (${message})`);
                     continue;
@@ -418,6 +435,11 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
                     (0, debug_logger_js_1.warn)(`[node-sqlite-adapter] Migration ${file} deferred until connector structure recovery (${message})`);
                     continue;
                 }
+                if (version === 67 &&
+                    (message.includes('no such column') || message.includes('no such table'))) {
+                    (0, debug_logger_js_1.warn)(`[node-sqlite-adapter] Migration ${file} deferred until connector structure recovery (${message})`);
+                    continue;
+                }
                 if (message.includes('duplicate column')) {
                     (0, debug_logger_js_1.warn)(`[node-sqlite-adapter] Migration ${file} skipped (duplicate column - already applied)`);
                     this.prepare('INSERT OR IGNORE INTO schema_version (version) VALUES (?)').run(version);
@@ -469,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 = [
@@ -515,6 +545,13 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
                     (0, debug_logger_js_1.info)('[node-sqlite-adapter] Repaired skipped legacy connector event refresh migration');
                 }
             }
+            const hasMissingSourceEntityIdFeature = !this.tableColumns('connector_event_index').has('source_entity_id') ||
+                !this.indexExists('idx_connector_event_source_entity') ||
+                !this.schemaVersionExists(67);
+            if (hasMissingSourceEntityIdFeature) {
+                this.recoverConnectorEventSourceEntityIdMigration067();
+                (0, debug_logger_js_1.info)('[node-sqlite-adapter] Repaired skipped connector event source_entity_id migration');
+            }
         }
         if (!this.tableExists('twin_edges')) {
             this.applyRepairMigration(migrationsDir, '035-create-twin-edges.sql', 'twin edge ledger');
@@ -630,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 = [
@@ -743,6 +839,40 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
             }
         }
     }
+    recoverConnectorEventSourceEntityIdMigration067() {
+        this.transaction(() => {
+            const columns = this.tableColumns('connector_event_index');
+            if (!columns.has('source_entity_id')) {
+                this.exec('ALTER TABLE connector_event_index ADD COLUMN source_entity_id TEXT');
+            }
+            // Backfill only when metadata_json exists; a legacy/minimal table rebuilt by the repair path
+            // may not have it yet. New rows carry source_entity_id at write time regardless.
+            if (columns.has('metadata_json')) {
+                this.exec(`
+          UPDATE connector_event_index
+            SET source_entity_id = json_extract(metadata_json, '$.sourceEntityId')
+            WHERE source_entity_id IS NULL
+              AND metadata_json IS NOT NULL
+              AND json_extract(metadata_json, '$.sourceEntityId') IS NOT NULL
+        `);
+            }
+            this.exec(`
+        CREATE INDEX IF NOT EXISTS idx_connector_event_source_entity
+          ON connector_event_index(source_connector, source_entity_id)
+      `);
+            this.assertMigration067Complete();
+            this.prepare('INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)').run(67, 'Add connector_event_index source_entity_id');
+        });
+    }
+    assertMigration067Complete() {
+        const columns = this.tableColumns('connector_event_index');
+        if (!columns.has('source_entity_id')) {
+            throw new Error('Migration 067 recovery failed: missing connector_event_index.source_entity_id');
+        }
+        if (!this.indexExists('idx_connector_event_source_entity')) {
+            throw new Error('Migration 067 recovery failed: missing index idx_connector_event_source_entity');
+        }
+    }
     recoverConnectorEventOperatorSeqMigration039() {
         this.transaction(() => {
             const columns = this.tableColumns('connector_event_index');

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.3.0",
+  "version": "2.4.1",
   "description": "MAMA Core - Shared modules for Memory-Augmented MCP Assistant",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",