@jungjaehoon/mama-core 2.4.1 → 4.0.0

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