@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/knowledge/decision-edges.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertDecisionEdge = upsertDecisionEdge;
+exports.proposeDecisionEdge = proposeDecisionEdge;
+exports.approveDecisionEdge = approveDecisionEdge;
+exports.rejectDecisionEdge = rejectDecisionEdge;
+exports.deprecateAutoDecisionEdges = deprecateAutoDecisionEdges;
+exports.deleteDecisionEdgesWithAudit = deleteDecisionEdgesWithAudit;
+/**
+ * Insert-or-replace one decision edge row with explicit governance columns.
+ * Used by the public createEdge API (createdBy 'llm', approvedByUser 1) and by
+ * the backup-restore path (columns replayed from the backup file).
+ */
+function upsertDecisionEdge(adapter, edge) {
+    adapter
+        .prepare(`INSERT OR REPLACE INTO decision_edges
+       (from_id, to_id, relationship, reason, created_by, approved_by_user, decision_id, evidence, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(edge.fromId, edge.toId, edge.relationship, edge.reason, edge.createdBy, edge.approvedByUser, edge.decisionId, edge.evidence, edge.createdAt);
+}
+/**
+ * Record a proposed edge pending user approval, plus its 'proposed' audit row.
+ */
+function proposeDecisionEdge(adapter, edge) {
+    adapter.transaction(() => {
+        adapter
+            .prepare(`INSERT INTO decision_edges
+         (from_id, to_id, relationship, reason, created_by, approved_by_user, decision_id, evidence, created_at)
+         VALUES (?, ?, ?, ?, 'llm', 0, ?, ?, ?)`)
+            .run(edge.fromId, edge.toId, edge.relationship, edge.reason, edge.decisionId, edge.evidence, Date.now());
+        adapter
+            .prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, reason, created_at)
+         VALUES (?, ?, ?, 'proposed', 'llm', ?, ?)`)
+            .run(edge.fromId, edge.toId, edge.relationship, edge.reason, Date.now());
+    });
+}
+/**
+ * Approve a pending edge, plus its 'approved' audit row.
+ */
+function approveDecisionEdge(adapter, key) {
+    adapter.transaction(() => {
+        adapter
+            .prepare(`UPDATE decision_edges
+         SET approved_by_user = 1, approved_at = ?
+         WHERE from_id = ? AND to_id = ? AND relationship = ?`)
+            .run(Date.now(), key.fromId, key.toId, key.relationship);
+        adapter
+            .prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, created_at)
+         VALUES (?, ?, ?, 'approved', 'user', ?)`)
+            .run(key.fromId, key.toId, key.relationship, Date.now());
+    });
+}
+/**
+ * Reject a proposed edge: the 'rejected' audit row is written before the edge
+ * is deleted, in the same transaction.
+ */
+function rejectDecisionEdge(adapter, key, reason) {
+    adapter.transaction(() => {
+        adapter
+            .prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, reason, created_at)
+         VALUES (?, ?, ?, 'rejected', 'user', ?, ?)`)
+            .run(key.fromId, key.toId, key.relationship, reason, Date.now());
+        adapter
+            .prepare(`DELETE FROM decision_edges
+         WHERE from_id = ? AND to_id = ? AND relationship = ?`)
+            .run(key.fromId, key.toId, key.relationship);
+    });
+}
+/**
+ * Remove the auto-generated edge population (created_by='user' with no
+ * proposal context) and record one 'deprecated' audit row per removed link.
+ * `links` is the already-scanned target set; it only feeds the audit rows.
+ */
+function deprecateAutoDecisionEdges(adapter, links, reason) {
+    adapter.transaction(() => {
+        adapter
+            .prepare(`DELETE FROM decision_edges WHERE created_by = 'user' AND decision_id IS NULL`)
+            .run();
+        const auditStmt = adapter.prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, reason, created_at)
+       VALUES (?, ?, ?, 'deprecated', 'system', ?, ?)`);
+        const timestamp = Date.now();
+        for (const link of links) {
+            auditStmt.run(link.fromId, link.toId, link.relationship, reason, timestamp);
+        }
+    });
+}
+/**
+ * Delete one batch of edges, writing a 'deprecated' audit row for each. A
+ * per-link failure is collected and the batch continues, matching the cleanup
+ * tool's accounting; a failure of the batch itself throws to the caller.
+ */
+function deleteDecisionEdgesWithAudit(adapter, links, reason) {
+    const deleteStmt = adapter.prepare(`DELETE FROM decision_edges
+     WHERE from_id = ? AND to_id = ? AND relationship = ?`);
+    const auditStmt = adapter.prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, reason, created_at)
+     VALUES (?, ?, ?, 'deprecated', 'system', ?, ?)`);
+    let deleted = 0;
+    const failures = [];
+    const processLinks = () => {
+        for (const link of links) {
+            try {
+                deleteStmt.run(link.fromId, link.toId, link.relationship);
+                auditStmt.run(link.fromId, link.toId, link.relationship, reason, Date.now());
+                deleted++;
+            }
+            catch (error) {
+                failures.push({
+                    link: `${link.fromId}->${link.toId}`,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    };
+    // Use transaction if available, otherwise run directly
+    if (adapter.transaction) {
+        adapter.transaction(processLinks);
+    }
+    else {
+        processLinks();
+    }
+    return { deleted, failures };
+}
+//# sourceMappingURL=decision-edges.js.map

package/dist/{agent-graph/types.d.ts → knowledge/graph-query.d.ts}

@@ -1,41 +1,59 @@
-import type { DatabaseAdapter } from '../db-manager.js';
-import type { EntityAlias, EntityAliasLabelType, EntityNode } from '../entities/types.js';
-import type { TwinEdgeRecord, TwinEdgeType, TwinProjectRef, TwinRef, TwinScopeRef } from '../edges/types.js';
+/**
+ * Knowledge graph queries: how a topic got to where it is, and what else it
+ * argues with. Two surfaces live here: the decision-chain graph (supersedes /
+ * decision_edges) and the twin-edge graph (neighborhood, paths, timeline over
+ * `twin_edges`).
+ *
+ * Every function takes the adapter it reads through, so a caller cannot walk a
+ * graph in a database it did not open.
+ *
+ * @module knowledge/graph-query
+ */
+import type { DatabaseAdapter, DecisionRecord, SemanticEdges } from '../db-manager.js';
+import { type JudgmentAccess } from './judgments.js';
+import type { WorkGraphPage, WorkGraphQuery } from '../memory/judgment-types.js';
+import type { TwinEdgeRecord, TwinEdgeType, TwinProjectRef, TwinRef, TwinScopeRef } from '../knowledge/twin-edge-types.js';
+/**
+ * Walk a topic's supersedes chain with a recursive CTE.
+ *
+ * @param adapter - Database to read through
+ * @param topic - Decision topic to query
+ * @param anchorId - Start from this decision instead of the topic's current head
+ * @returns Decisions ordered by recency, each carrying its approved edges
+ */
+export declare function queryDecisionGraph(adapter: DatabaseAdapter, topic: string, anchorId?: string): Promise<DecisionRecord[]>;
+/**
+ * Outgoing and incoming semantic edges for a set of decisions.
+ *
+ * @param adapter - Database to read through
+ * @param decisionIds - Decision IDs to query edges for
+ * @returns Edges categorized by relationship and direction
+ */
+export declare function querySemanticEdges(adapter: DatabaseAdapter, decisionIds: string[]): Promise<SemanticEdges>;
+export declare class AgentGraphValidationError extends Error {
+    constructor(message: string);
+}
 export type AgentGraphAdapter = Pick<DatabaseAdapter, 'prepare' | 'transaction'>;
 export interface AgentGraphEdgeFilters {
     edge_types?: TwinEdgeType[];
 }
-export interface ResolveEntityInput {
-    label: string;
-    scopes?: TwinScopeRef[];
-    connectors?: string[];
-    project_refs?: TwinProjectRef[];
-    /**
-     * Which channels of each connector may be read. Carried on every graph input for the
-     * same reason it is carried on the reader's boundary: a raw ref reached through an edge
-     * must satisfy the same rule as a row the reader would have returned.
-     */
-    channels?: Record<string, readonly string[]>;
-    tenant_id?: string | null;
-    context_refs?: TwinRef[];
-    limit?: number;
-    as_of_ms?: number | null;
-}
-export interface ResolvedEntityCandidate {
-    entity: EntityNode;
-    matched_label: string;
-    match_source: 'preferred_label' | 'alias' | 'observation';
-    score: number;
-}
-export interface ResolveEntityResult {
-    entity: EntityNode | null;
-    candidates: ResolvedEntityCandidate[];
-}
 export interface GraphNeighborhoodInput {
     ref: TwinRef;
     depth?: number;
+    /**
+     * Which edge orientation, seen from the expanding frontier, belongs to the walk.
+     * 'out' follows edges whose subject is on the frontier, 'in' whose object is, and
+     * 'both' either — the absence of a direction means the undirected neighborhood.
+     */
+    direction?: 'in' | 'out' | 'both';
+    /**
+     * 'all' reads replaced records as history; absent or 'current' reads only
+     * what currently stands. Authority checks apply in both modes.
+     */
+    history?: 'current' | 'all';
     scopes?: TwinScopeRef[];
     connectors?: string[];
+    connector_wide_read?: string[];
     project_refs?: TwinProjectRef[];
     /**
      * Which channels of each connector may be read. Carried on every graph input for the
@@ -44,6 +62,8 @@ export interface GraphNeighborhoodInput {
      */
     channels?: Record<string, readonly string[]>;
     tenant_id?: string | null;
+    principal_id?: string;
+    agent_id?: string;
     edge_filters?: AgentGraphEdgeFilters;
     as_of_ms?: number | null;
     limit?: number;
@@ -51,13 +71,23 @@ export interface GraphNeighborhoodInput {
 export interface AgentGraphResult {
     nodes: TwinRef[];
     edges: TwinEdgeRecord[];
+    current_projection: AgentGraphCurrentProjection[];
+}
+export interface AgentGraphCurrentProjection {
+    edge_id: string;
+    endpoint: 'from' | 'to';
+    original_ref: TwinRef;
+    current_ref: TwinRef | null;
 }
 export interface GraphPathsInput {
     from_ref: TwinRef;
     to_ref: TwinRef;
     max_depth?: number;
+    /** 'all' reads replaced records as history; 'current' is the default. */
+    history?: 'current' | 'all';
     scopes?: TwinScopeRef[];
     connectors?: string[];
+    connector_wide_read?: string[];
     project_refs?: TwinProjectRef[];
     /**
      * Which channels of each connector may be read. Carried on every graph input for the
@@ -66,6 +96,8 @@ export interface GraphPathsInput {
      */
     channels?: Record<string, readonly string[]>;
     tenant_id?: string | null;
+    principal_id?: string;
+    agent_id?: string;
     edge_filters?: AgentGraphEdgeFilters;
     as_of_ms?: number | null;
     limit?: number;
@@ -76,11 +108,16 @@ export interface AgentGraphPath {
 }
 export interface GraphPathsResult {
     paths: AgentGraphPath[];
+    limit_reached: boolean;
+    current_projection: AgentGraphCurrentProjection[];
 }
 export interface GraphTimelineInput {
     ref: TwinRef;
+    /** 'all' reads replaced records as history; 'current' is the default. */
+    history?: 'current' | 'all';
     scopes?: TwinScopeRef[];
     connectors?: string[];
+    connector_wide_read?: string[];
     project_refs?: TwinProjectRef[];
     /**
      * Which channels of each connector may be read. Carried on every graph input for the
@@ -89,9 +126,13 @@ export interface GraphTimelineInput {
      */
     channels?: Record<string, readonly string[]>;
     tenant_id?: string | null;
+    principal_id?: string;
+    agent_id?: string;
     edge_filters?: AgentGraphEdgeFilters;
     from_ms?: number;
     to_ms?: number;
+    recorded_from_ms?: number;
+    recorded_to_ms?: number;
     as_of_ms?: number | null;
     limit?: number;
 }
@@ -124,14 +165,6 @@ export interface AgentGraphTimelineCaseEvent {
         last_activity_at: string | null;
     };
 }
-export interface AgentGraphTimelineEntityEvent {
-    kind: 'entity';
-    at_ms: number;
-    ref: Extract<TwinRef, {
-        kind: 'entity';
-    }>;
-    entity: EntityNode;
-}
 export interface AgentGraphTimelineRawEvent {
     kind: 'raw';
     at_ms: number;
@@ -147,6 +180,7 @@ export interface AgentGraphTimelineRawEvent {
         title: string | null;
         event_datetime: number | null;
         source_timestamp_ms: number;
+        observation_ref: string | null;
     };
 }
 export interface AgentGraphTimelineEdgeEvent {
@@ -154,39 +188,15 @@ export interface AgentGraphTimelineEdgeEvent {
     at_ms: number;
     edge: TwinEdgeRecord;
 }
-export type AgentGraphTimelineEvent = AgentGraphTimelineMemoryEvent | AgentGraphTimelineCaseEvent | AgentGraphTimelineEntityEvent | AgentGraphTimelineRawEvent | AgentGraphTimelineEdgeEvent;
+export type AgentGraphTimelineEvent = AgentGraphTimelineMemoryEvent | AgentGraphTimelineCaseEvent | AgentGraphTimelineRawEvent | AgentGraphTimelineEdgeEvent;
 export interface GraphTimelineResult {
     ref: TwinRef;
     events: AgentGraphTimelineEvent[];
-}
-export interface AttachEntityAliasWithEdgeInput {
-    entity_id: string;
-    label: string;
-    label_type?: EntityAliasLabelType;
-    lang?: string | null;
-    script?: string | null;
-    confidence?: number | null;
-    source_type: string;
-    source_ref?: string | null;
-    source_refs?: TwinRef[];
-    agent_id: string;
-    model_run_id: string;
-    envelope_hash: string;
-    request_idempotency_key?: string;
-    edge_idempotency_key?: string;
-    scopes?: TwinScopeRef[];
-    connectors?: string[];
-    project_refs?: TwinProjectRef[];
-    /**
-     * Which channels of each connector may be read. Carried on every graph input for the
-     * same reason it is carried on the reader's boundary: a raw ref reached through an edge
-     * must satisfy the same rule as a row the reader would have returned.
-     */
-    channels?: Record<string, readonly string[]>;
-    tenant_id?: string | null;
-}
-export interface AttachEntityAliasWithEdgeResult {
-    alias: EntityAlias;
-    edge: TwinEdgeRecord;
-}
-//# sourceMappingURL=types.d.ts.map
+    has_more: boolean;
+    current_projection: AgentGraphCurrentProjection[];
+}
+export declare function getGraphNeighborhood(adapter: AgentGraphAdapter, input: GraphNeighborhoodInput): AgentGraphResult;
+export declare function getGraphPaths(adapter: AgentGraphAdapter, input: GraphPathsInput): GraphPathsResult;
+export declare function getGraphTimeline(adapter: AgentGraphAdapter, input: GraphTimelineInput): GraphTimelineResult;
+export declare function queryGraph(adapter: AgentGraphAdapter, query: WorkGraphQuery, access: JudgmentAccess): WorkGraphPage;
+//# sourceMappingURL=graph-query.d.ts.map