@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/db/migrations/031-wiki-page-index-provenance-columns.sql

@@ -0,0 +1,2 @@
+ALTER TABLE wiki_page_index ADD COLUMN source_ids TEXT;
+ALTER TABLE wiki_page_index ADD COLUMN entity_refs TEXT;

package/db/migrations/032-add-memory-provenance-columns.sql

@@ -0,0 +1,21 @@
+ALTER TABLE decisions ADD COLUMN agent_id TEXT;
+ALTER TABLE decisions ADD COLUMN model_run_id TEXT;
+ALTER TABLE decisions ADD COLUMN envelope_hash TEXT;
+ALTER TABLE decisions ADD COLUMN gateway_call_id TEXT;
+ALTER TABLE decisions ADD COLUMN source_refs_json TEXT;
+ALTER TABLE decisions ADD COLUMN provenance_json TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_decisions_envelope_hash
+  ON decisions(envelope_hash);
+
+CREATE INDEX IF NOT EXISTS idx_decisions_model_run_id
+  ON decisions(model_run_id);
+
+CREATE INDEX IF NOT EXISTS idx_decisions_gateway_call_id
+  ON decisions(gateway_call_id);
+
+CREATE INDEX IF NOT EXISTS idx_memory_events_memory_created
+  ON memory_events(memory_id, created_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (32, 'Add nullable memory provenance columns');

package/db/migrations/033-create-model-runs-and-tool-traces.sql

@@ -0,0 +1,53 @@
+CREATE TABLE IF NOT EXISTS model_runs (
+  model_run_id TEXT PRIMARY KEY,
+  model_id TEXT,
+  model_provider TEXT,
+  prompt_version TEXT,
+  tool_manifest_version TEXT,
+  output_schema_version TEXT,
+  agent_id TEXT,
+  instance_id TEXT,
+  envelope_hash TEXT,
+  parent_model_run_id TEXT,
+  input_snapshot_ref TEXT,
+  input_refs_json TEXT,
+  completion_summary TEXT,
+  status TEXT NOT NULL CHECK (status IN ('running', 'committed', 'failed', 'legacy')),
+  error_summary TEXT,
+  token_count INTEGER DEFAULT 0,
+  cost_estimate REAL,
+  created_at INTEGER NOT NULL,
+  completed_at INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_model_runs_envelope_hash
+  ON model_runs(envelope_hash);
+
+CREATE INDEX IF NOT EXISTS idx_model_runs_status_created
+  ON model_runs(status, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_model_runs_agent_created
+  ON model_runs(agent_id, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS tool_traces (
+  trace_id TEXT PRIMARY KEY,
+  model_run_id TEXT NOT NULL,
+  gateway_call_id TEXT,
+  tool_name TEXT NOT NULL,
+  input_summary TEXT,
+  output_summary TEXT,
+  execution_status TEXT,
+  duration_ms INTEGER DEFAULT 0,
+  envelope_hash TEXT,
+  created_at INTEGER NOT NULL,
+  FOREIGN KEY (model_run_id) REFERENCES model_runs(model_run_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_tool_traces_model_run_id
+  ON tool_traces(model_run_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_tool_traces_gateway_call_id
+  ON tool_traces(gateway_call_id);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (33, 'Create model runs and tool traces');

package/db/migrations/034-add-connector-event-scope-columns.sql

@@ -0,0 +1,14 @@
+ALTER TABLE connector_event_index ADD COLUMN source_cursor TEXT;
+ALTER TABLE connector_event_index ADD COLUMN tenant_id TEXT;
+ALTER TABLE connector_event_index ADD COLUMN project_id TEXT;
+ALTER TABLE connector_event_index ADD COLUMN memory_scope_kind TEXT;
+ALTER TABLE connector_event_index ADD COLUMN memory_scope_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_connector_event_scope
+  ON connector_event_index(tenant_id, project_id, memory_scope_kind, memory_scope_id);
+
+CREATE INDEX IF NOT EXISTS idx_connector_event_source_cursor
+  ON connector_event_index(source_connector, source_cursor);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (34, 'Add connector event scope columns');

package/db/migrations/035-create-twin-edges.sql

@@ -0,0 +1,63 @@
+CREATE TABLE IF NOT EXISTS twin_edges (
+  edge_id TEXT PRIMARY KEY,
+  edge_type TEXT NOT NULL CHECK (
+    edge_type IN (
+      'supersedes',
+      'builds_on',
+      'debates',
+      'synthesizes',
+      'mentions',
+      'derived_from',
+      'case_member',
+      'alias_of',
+      'next_action_for',
+      'blocks'
+    )
+  ),
+  subject_kind TEXT NOT NULL CHECK (
+    subject_kind IN ('memory', 'case', 'entity', 'report', 'edge')
+  ),
+  subject_id TEXT NOT NULL,
+  object_kind TEXT NOT NULL CHECK (
+    object_kind IN ('memory', 'case', 'entity', 'report', 'edge', 'raw')
+  ),
+  object_id TEXT NOT NULL,
+  relation_attrs_json TEXT,
+  confidence REAL NOT NULL DEFAULT 1.0 CHECK (confidence >= 0.0 AND confidence <= 1.0),
+  source TEXT NOT NULL CHECK (source IN ('agent', 'human', 'code')),
+  agent_id TEXT,
+  model_run_id TEXT,
+  envelope_hash TEXT,
+  human_actor_id TEXT,
+  human_actor_role TEXT,
+  authority_scope_json TEXT,
+  reason_classification TEXT,
+  reason_text TEXT,
+  evidence_refs_json TEXT,
+  request_idempotency_key TEXT,
+  edge_idempotency_key TEXT,
+  content_hash BLOB NOT NULL CHECK(length(content_hash)=32),
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_twin_edges_subject
+  ON twin_edges(subject_kind, subject_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_twin_edges_object
+  ON twin_edges(object_kind, object_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_twin_edges_model_run_id
+  ON twin_edges(model_run_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_twin_edges_request_idempotency
+  ON twin_edges(model_run_id, request_idempotency_key, created_at DESC)
+  WHERE model_run_id IS NOT NULL
+    AND request_idempotency_key IS NOT NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS ux_twin_edges_model_run_edge_idempotency
+  ON twin_edges(model_run_id, edge_idempotency_key)
+  WHERE model_run_id IS NOT NULL
+    AND edge_idempotency_key IS NOT NULL;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (35, 'Create first-class twin edge ledger');

package/db/migrations/036-create-agent-situation-packets.sql

@@ -0,0 +1,61 @@
+CREATE TABLE IF NOT EXISTS agent_situation_packets (
+  packet_id TEXT PRIMARY KEY,
+  cache_key TEXT NOT NULL,
+  scope_json TEXT NOT NULL,
+  scope_hash TEXT NOT NULL,
+  range_start_ms INTEGER NOT NULL CHECK (range_start_ms >= 0),
+  range_end_ms INTEGER NOT NULL CHECK (range_end_ms >= range_start_ms),
+  focus_json TEXT NOT NULL,
+  envelope_hash TEXT NOT NULL,
+  envelope_effective_filters_json TEXT NOT NULL,
+  envelope_effective_filters_hash TEXT NOT NULL,
+  ranking_policy_version TEXT NOT NULL,
+  generated_at INTEGER NOT NULL CHECK (generated_at >= 0),
+  expires_at INTEGER NOT NULL CHECK (expires_at >= generated_at),
+  ttl_seconds INTEGER NOT NULL CHECK (ttl_seconds > 0),
+  freshness_json TEXT NOT NULL,
+  source_coverage_json TEXT NOT NULL,
+  briefing_json TEXT NOT NULL,
+  ranked_items_json TEXT NOT NULL,
+  top_memory_refs_json TEXT NOT NULL,
+  pending_human_questions_json TEXT NOT NULL,
+  entity_clusters_json TEXT NOT NULL,
+  recommended_next_tools_json TEXT NOT NULL,
+  generated_from_slice_ids_json TEXT NOT NULL DEFAULT '[]',
+  caveats_json TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  model_run_id TEXT NOT NULL,
+  input_snapshot_ref TEXT NOT NULL,
+  source_refs_json TEXT NOT NULL DEFAULT '[]',
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  project_id TEXT NOT NULL,
+  memory_scope_kind TEXT NOT NULL,
+  memory_scope_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_cache_fresh
+  ON agent_situation_packets(cache_key, ranking_policy_version, expires_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_envelope
+  ON agent_situation_packets(envelope_hash, generated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_model_run
+  ON agent_situation_packets(model_run_id, generated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_scope
+  ON agent_situation_packets(tenant_id, project_id, memory_scope_kind, memory_scope_id, generated_at DESC);
+
+CREATE TABLE IF NOT EXISTS agent_situation_refresh_leases (
+  cache_key TEXT PRIMARY KEY,
+  ranking_policy_version TEXT NOT NULL,
+  lease_owner TEXT NOT NULL,
+  lease_expires_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_situation_leases_expiry
+  ON agent_situation_refresh_leases(lease_expires_at);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (36, 'Create agent situation packet cache');

package/dist/agent-graph/alias-write.d.ts

@@ -0,0 +1,3 @@
+import type { AgentGraphAdapter, AttachEntityAliasWithEdgeInput, AttachEntityAliasWithEdgeResult } from './types.js';
+export declare function attachEntityAliasWithEdge(adapter: AgentGraphAdapter, input: AttachEntityAliasWithEdgeInput): AttachEntityAliasWithEdgeResult;
+//# sourceMappingURL=alias-write.d.ts.map

package/dist/agent-graph/alias-write.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachEntityAliasWithEdge = attachEntityAliasWithEdge;
+const node_crypto_1 = require("node:crypto");
+const canonicalize_js_1 = require("../canonicalize.js");
+const ref_validation_js_1 = require("../edges/ref-validation.js");
+const store_js_1 = require("../edges/store.js");
+const types_js_1 = require("../edges/types.js");
+const normalization_js_1 = require("../entities/normalization.js");
+const store_js_2 = require("../entities/store.js");
+const errors_js_1 = require("./errors.js");
+const TWIN_REF_KIND_SET = new Set(types_js_1.TWIN_REF_KINDS);
+function stableAliasId(input, normalizedLabel) {
+    const replayKey = replayIdempotencyKey(input);
+    if (replayKey) {
+        const hash = (0, node_crypto_1.createHash)('sha256')
+            .update(`${input.entity_id}\0${normalizedLabel}\0${replayKey}`, 'utf8')
+            .digest('hex')
+            .slice(0, 32);
+        return `alias_${hash}`;
+    }
+    return `alias_${(0, node_crypto_1.randomUUID)().replace(/-/g, '')}`;
+}
+function replayIdempotencyKey(input) {
+    return input.edge_idempotency_key ?? input.request_idempotency_key;
+}
+function loadAlias(adapter, aliasId) {
+    const row = adapter.prepare('SELECT * FROM entity_aliases WHERE id = ?').get(aliasId);
+    if (!row) {
+        throw new Error(`Entity alias was not written: ${aliasId}`);
+    }
+    return {
+        id: String(row.id),
+        entity_id: String(row.entity_id),
+        label: String(row.label),
+        normalized_label: String(row.normalized_label),
+        lang: typeof row.lang === 'string' ? row.lang : null,
+        script: typeof row.script === 'string' ? row.script : null,
+        label_type: row.label_type,
+        source_type: String(row.source_type),
+        source_ref: typeof row.source_ref === 'string' ? row.source_ref : null,
+        confidence: typeof row.confidence === 'number' ? row.confidence : null,
+        status: row.status,
+        created_at: Number(row.created_at),
+    };
+}
+function normalizeConfidence(value) {
+    if (value === undefined || value === null) {
+        return 1;
+    }
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1) {
+        return value;
+    }
+    throw new errors_js_1.AgentGraphValidationError(`confidence must be between 0 and 1: ${String(value)}`);
+}
+function selectExistingAliasEdge(adapter, modelRunId, edgeIdempotencyKey) {
+    if (!edgeIdempotencyKey) {
+        return null;
+    }
+    const row = adapter
+        .prepare(`
+        SELECT *
+        FROM twin_edges
+        WHERE model_run_id = ?
+          AND edge_idempotency_key = ?
+        LIMIT 1
+      `)
+        .get(modelRunId, edgeIdempotencyKey);
+    return row ? (0, store_js_1.mapTwinEdgeRow)(row) : null;
+}
+function normalizeSourceRefs(sourceRefs) {
+    if (!sourceRefs || sourceRefs.length === 0) {
+        return [];
+    }
+    const refs = [];
+    const seen = new Set();
+    for (const ref of sourceRefs) {
+        if (!ref ||
+            typeof ref !== 'object' ||
+            typeof ref.kind !== 'string' ||
+            typeof ref.id !== 'string' ||
+            ref.id.trim().length === 0 ||
+            !TWIN_REF_KIND_SET.has(ref.kind)) {
+            throw new errors_js_1.AgentGraphValidationError('source_refs must be TwinRef objects with kind and id.');
+        }
+        const normalized = { kind: ref.kind, id: ref.id.trim() };
+        const key = `${normalized.kind}:${normalized.id}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            refs.push(normalized);
+        }
+    }
+    return refs.sort((left, right) => `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`));
+}
+function expectedRelationAttrs(alias, sourceRefs) {
+    const attrs = {
+        alias_id: alias.id,
+        label: alias.label,
+        normalized_label: alias.normalized_label,
+        lang: alias.lang,
+        script: alias.script,
+        label_type: alias.label_type,
+    };
+    if (sourceRefs.length > 0) {
+        attrs.source_refs = sourceRefs.map((ref) => ({ kind: ref.kind, id: ref.id }));
+    }
+    return attrs;
+}
+function assertAliasReplayMatches(alias, input, normalized, confidence) {
+    const expectedScript = input.script ?? normalized.script;
+    const expectedLabelType = input.label_type ?? 'alt';
+    const expectedSourceRef = input.source_ref ?? null;
+    const matches = alias.entity_id === input.entity_id &&
+        alias.label === input.label &&
+        alias.normalized_label === normalized.normalized &&
+        alias.lang === (input.lang ?? null) &&
+        alias.script === expectedScript &&
+        alias.label_type === expectedLabelType &&
+        alias.source_type === input.source_type &&
+        alias.source_ref === expectedSourceRef &&
+        alias.confidence === confidence &&
+        alias.status === 'active';
+    if (!matches) {
+        throw new errors_js_1.AgentGraphValidationError(`Conflicting entity alias replay for request idempotency key: ${replayIdempotencyKey(input)}`);
+    }
+}
+function assertAliasEdgeReplayMatches(edge, input, alias, confidence, edgeIdempotencyKey, sourceRefs) {
+    const matches = edge.edge_type === 'alias_of' &&
+        edge.subject_ref.kind === 'entity' &&
+        edge.subject_ref.id === input.entity_id &&
+        edge.object_ref.kind === 'entity' &&
+        edge.object_ref.id === input.entity_id &&
+        edge.relation_attrs_json === (0, canonicalize_js_1.canonicalizeJSON)(expectedRelationAttrs(alias, sourceRefs)) &&
+        edge.confidence === confidence &&
+        edge.source === 'agent' &&
+        edge.agent_id === input.agent_id &&
+        edge.model_run_id === input.model_run_id &&
+        edge.envelope_hash === input.envelope_hash &&
+        edge.request_idempotency_key === (input.request_idempotency_key ?? null) &&
+        edge.edge_idempotency_key === (edgeIdempotencyKey ?? null);
+    if (!matches) {
+        throw new errors_js_1.AgentGraphValidationError(`Conflicting alias edge replay for request idempotency key: ${replayIdempotencyKey(input)}`);
+    }
+}
+function insertAliasEdge(adapter, input, alias, confidence, sourceRefs) {
+    const edgeIdempotencyKey = replayIdempotencyKey(input);
+    const existing = selectExistingAliasEdge(adapter, input.model_run_id, edgeIdempotencyKey);
+    const edgeId = `edge_${(0, node_crypto_1.randomUUID)().replace(/-/g, '')}`;
+    const relationAttrs = expectedRelationAttrs(alias, sourceRefs);
+    const relationAttrsJson = (0, canonicalize_js_1.canonicalizeJSON)(relationAttrs);
+    if (existing) {
+        assertAliasEdgeReplayMatches(existing, input, alias, confidence, edgeIdempotencyKey, sourceRefs);
+        return existing;
+    }
+    const contentHash = (0, node_crypto_1.createHash)('sha256')
+        .update((0, canonicalize_js_1.canonicalizeJSON)({
+        edge_type: 'alias_of',
+        subject_ref: { kind: 'entity', id: input.entity_id },
+        object_ref: { kind: 'entity', id: input.entity_id },
+        relation_attrs_json: relationAttrsJson,
+        confidence,
+        source: 'agent',
+        agent_id: input.agent_id,
+        model_run_id: input.model_run_id,
+        envelope_hash: input.envelope_hash,
+    }), 'utf8')
+        .digest();
+    adapter
+        .prepare(`
+        INSERT INTO twin_edges (
+          edge_id, edge_type, subject_kind, subject_id, object_kind, object_id,
+          relation_attrs_json, confidence, source, agent_id, model_run_id, envelope_hash,
+          request_idempotency_key, edge_idempotency_key, content_hash, created_at
+        )
+        VALUES (?, 'alias_of', 'entity', ?, 'entity', ?, ?, ?, 'agent', ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(edgeId, input.entity_id, input.entity_id, relationAttrsJson, confidence, input.agent_id, input.model_run_id, input.envelope_hash, input.request_idempotency_key ?? null, edgeIdempotencyKey ?? null, contentHash, Date.now());
+    const row = adapter.prepare('SELECT * FROM twin_edges WHERE edge_id = ?').get(edgeId);
+    if (!row) {
+        throw new Error(`Entity alias edge was not written: ${edgeId}`);
+    }
+    return (0, store_js_1.mapTwinEdgeRow)(row);
+}
+function attachEntityAliasWithEdge(adapter, input) {
+    const entity = (0, store_js_2.getEntityNode)(input.entity_id, adapter);
+    if (!entity || entity.status !== 'active') {
+        throw new errors_js_1.AgentGraphValidationError(`Active entity not found: ${input.entity_id}`);
+    }
+    const visibility = {
+        scopes: input.scopes,
+        connectors: input.connectors,
+        projectRefs: input.project_refs,
+        tenantId: input.tenant_id,
+    };
+    const sourceRefs = normalizeSourceRefs(input.source_refs);
+    if (sourceRefs.length === 0) {
+        throw new errors_js_1.AgentGraphValidationError('source_refs must include at least one visible source.');
+    }
+    try {
+        (0, ref_validation_js_1.assertTwinRefsVisible)(adapter, [{ kind: 'entity', id: input.entity_id }, ...sourceRefs], visibility);
+    }
+    catch (error) {
+        throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
+    }
+    let normalized;
+    try {
+        normalized = (0, normalization_js_1.normalizeEntityLabel)(input.label);
+    }
+    catch (error) {
+        throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
+    }
+    const confidence = normalizeConfidence(input.confidence);
+    const aliasId = stableAliasId(input, normalized.normalized);
+    const createdAt = Date.now();
+    return adapter.transaction(() => {
+        adapter
+            .prepare(`
+          INSERT OR IGNORE INTO entity_aliases (
+            id, entity_id, label, normalized_label, lang, script, label_type,
+            source_type, source_ref, confidence, status, created_at
+          )
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?)
+        `)
+            .run(aliasId, input.entity_id, input.label, normalized.normalized, input.lang ?? null, input.script ?? normalized.script, input.label_type ?? 'alt', input.source_type, input.source_ref ?? null, confidence, createdAt);
+        const alias = loadAlias(adapter, aliasId);
+        assertAliasReplayMatches(alias, input, normalized, confidence);
+        const edge = insertAliasEdge(adapter, input, alias, confidence, sourceRefs);
+        return { alias, edge };
+    });
+}
+//# sourceMappingURL=alias-write.js.map

package/dist/agent-graph/entity-resolve.d.ts

@@ -0,0 +1,3 @@
+import type { AgentGraphAdapter, ResolveEntityInput, ResolveEntityResult } from './types.js';
+export declare function resolveEntity(adapter: AgentGraphAdapter, input: ResolveEntityInput): ResolveEntityResult;
+//# sourceMappingURL=entity-resolve.d.ts.map