@jungjaehoon/mama-core 2.2.3 → 2.4.0

package/db/migrations/066-create-awareness-operational-issues.sql

@@ -0,0 +1,32 @@
+-- 066: awareness_operational_issues (One MAMA Phase 3 Task 2).
+--
+-- Failures become first-class evidence: gateway tool failures, envelope scope
+-- mismatches, dead owner-event batches and ledger stagnation are recorded here,
+-- aggregated by (surface, signature), and read into every packet so the agent
+-- sees its own failures. The shape below is the exact shape the owner's
+-- installed database already carries from the retired 043-060 chain, plus
+-- `occurrences`. A fresh install gets the whole table here; an installed table
+-- WITHOUT `occurrences` gets the column added at runtime (pragma-guarded ALTER
+-- in packages/standalone/src/observability/operational-issues.ts), because
+-- SQLite has no ADD COLUMN IF NOT EXISTS and this chain is plain SQL.
+--
+-- `status` carries no CHECK on purpose: the installed column has none, and a
+-- CHECK would force a table rebuild for no gain. Values used: open,
+-- repair_requested, closed - validated in TypeScript.
+CREATE TABLE IF NOT EXISTS awareness_operational_issues (
+  issue_id TEXT PRIMARY KEY,
+  dedupe_key TEXT UNIQUE NOT NULL,
+  surface TEXT NOT NULL,
+  severity TEXT NOT NULL,
+  status TEXT NOT NULL,
+  source_delta_id TEXT,
+  first_seen_at INTEGER NOT NULL CHECK (first_seen_at >= 0),
+  last_seen_at INTEGER NOT NULL CHECK (last_seen_at >= first_seen_at),
+  next_retry_at INTEGER,
+  last_error TEXT,
+  owner_agent TEXT,
+  occurrences INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE INDEX IF NOT EXISTS idx_awareness_operational_issues_status_seen
+  ON awareness_operational_issues(status, last_seen_at DESC);

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/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

@@ -70,6 +70,8 @@ export declare class NodeSQLiteAdapter extends DatabaseAdapter {
     private assertMigration032Complete;
     private recoverConnectorEventScopeMigration034;
     private assertMigration034Complete;
+    private recoverConnectorEventSourceEntityIdMigration067;
+    private assertMigration067Complete;
     private recoverConnectorEventOperatorSeqMigration039;
     private assertMigration039Complete;
     private recoverConnectorEventSequencesMigration062;

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

@@ -409,6 +409,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 +423,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);
@@ -515,6 +525,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');
@@ -743,6 +760,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/package.json

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