@jungjaehoon/mama-core 1.4.2 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. package/README.md +48 -10
  2. package/db/migrations/026-create-canonical-entity-tables.sql +99 -0
  3. package/db/migrations/027-create-entity-review-support.sql +44 -0
  4. package/db/migrations/028-create-entity-audit-tables.sql +45 -0
  5. package/db/migrations/029-extend-entity-observations-observation-type.sql +60 -0
  6. package/db/migrations/030-case-first-memory-substrate.sql +901 -0
  7. package/db/migrations/031-wiki-page-index-provenance-columns.sql +2 -0
  8. package/db/migrations/032-add-memory-provenance-columns.sql +21 -0
  9. package/db/migrations/033-create-model-runs-and-tool-traces.sql +53 -0
  10. package/db/migrations/034-add-connector-event-scope-columns.sql +14 -0
  11. package/db/migrations/035-create-twin-edges.sql +63 -0
  12. package/db/migrations/036-create-agent-situation-packets.sql +61 -0
  13. package/dist/agent-graph/alias-write.d.ts +3 -0
  14. package/dist/agent-graph/alias-write.js +231 -0
  15. package/dist/agent-graph/entity-resolve.d.ts +3 -0
  16. package/dist/agent-graph/entity-resolve.js +275 -0
  17. package/dist/agent-graph/errors.d.ts +4 -0
  18. package/dist/agent-graph/errors.js +11 -0
  19. package/dist/agent-graph/graph-query.d.ts +5 -0
  20. package/dist/agent-graph/graph-query.js +359 -0
  21. package/dist/agent-graph/index.d.ts +6 -0
  22. package/dist/agent-graph/index.js +22 -0
  23. package/dist/agent-graph/types.d.ts +162 -0
  24. package/dist/agent-graph/types.js +3 -0
  25. package/dist/agent-situation/builder.d.ts +8 -0
  26. package/dist/agent-situation/builder.js +239 -0
  27. package/dist/agent-situation/cache-key.d.ts +4 -0
  28. package/dist/agent-situation/cache-key.js +64 -0
  29. package/dist/agent-situation/index.d.ts +7 -0
  30. package/dist/agent-situation/index.js +28 -0
  31. package/dist/agent-situation/packet-store.d.ts +27 -0
  32. package/dist/agent-situation/packet-store.js +228 -0
  33. package/dist/agent-situation/ranking-policy.d.ts +18 -0
  34. package/dist/agent-situation/ranking-policy.js +75 -0
  35. package/dist/agent-situation/source-readers.d.ts +52 -0
  36. package/dist/agent-situation/source-readers.js +300 -0
  37. package/dist/agent-situation/types.d.ts +195 -0
  38. package/dist/agent-situation/types.js +3 -0
  39. package/dist/canonicalize.d.ts +38 -0
  40. package/dist/canonicalize.js +106 -0
  41. package/dist/cases/case-links.d.ts +116 -0
  42. package/dist/cases/case-links.js +794 -0
  43. package/dist/cases/composition-overrides.d.ts +90 -0
  44. package/dist/cases/composition-overrides.js +724 -0
  45. package/dist/cases/corrections.d.ts +156 -0
  46. package/dist/cases/corrections.js +1045 -0
  47. package/dist/cases/freshness.d.ts +57 -0
  48. package/dist/cases/freshness.js +283 -0
  49. package/dist/cases/live-state.d.ts +48 -0
  50. package/dist/cases/live-state.js +256 -0
  51. package/dist/cases/membership-explain.d.ts +56 -0
  52. package/dist/cases/membership-explain.js +140 -0
  53. package/dist/cases/membership-matcher.d.ts +23 -0
  54. package/dist/cases/membership-matcher.js +193 -0
  55. package/dist/cases/merge-split.d.ts +61 -0
  56. package/dist/cases/merge-split.js +368 -0
  57. package/dist/cases/role-inference.d.ts +10 -0
  58. package/dist/cases/role-inference.js +85 -0
  59. package/dist/cases/search-rollup.d.ts +27 -0
  60. package/dist/cases/search-rollup.js +309 -0
  61. package/dist/cases/sqlite-transaction.d.ts +10 -0
  62. package/dist/cases/sqlite-transaction.js +62 -0
  63. package/dist/cases/store.d.ts +74 -0
  64. package/dist/cases/store.js +816 -0
  65. package/dist/cases/target-ref.d.ts +25 -0
  66. package/dist/cases/target-ref.js +22 -0
  67. package/dist/cases/timeline-range.d.ts +6 -0
  68. package/dist/cases/timeline-range.js +322 -0
  69. package/dist/cases/tombstone-sweeper.d.ts +13 -0
  70. package/dist/cases/tombstone-sweeper.js +128 -0
  71. package/dist/cases/types.d.ts +244 -0
  72. package/dist/cases/types.js +47 -0
  73. package/dist/cases/wiki-page-index.d.ts +50 -0
  74. package/dist/cases/wiki-page-index.js +350 -0
  75. package/dist/connectors/event-index.d.ts +45 -0
  76. package/dist/connectors/event-index.js +381 -0
  77. package/dist/connectors/raw-query.d.ts +18 -0
  78. package/dist/connectors/raw-query.js +305 -0
  79. package/dist/connectors/types.d.ts +109 -0
  80. package/dist/connectors/types.js +3 -0
  81. package/dist/db-adapter/node-sqlite-adapter.d.ts +6 -0
  82. package/dist/db-adapter/node-sqlite-adapter.js +131 -0
  83. package/dist/db-manager.d.ts +12 -1
  84. package/dist/db-manager.js +60 -5
  85. package/dist/decision-formatter.d.ts +2 -0
  86. package/dist/decision-formatter.js +11 -8
  87. package/dist/edges/ref-validation.d.ts +8 -0
  88. package/dist/edges/ref-validation.js +262 -0
  89. package/dist/edges/store.d.ts +10 -0
  90. package/dist/edges/store.js +343 -0
  91. package/dist/edges/types.d.ts +86 -0
  92. package/dist/edges/types.js +18 -0
  93. package/dist/embedding-server/mobile/daemon.d.ts +1 -0
  94. package/dist/embedding-server/mobile/daemon.js +11 -1
  95. package/dist/embeddings.js +13 -0
  96. package/dist/entities/audit-metrics.d.ts +73 -0
  97. package/dist/entities/audit-metrics.js +128 -0
  98. package/dist/entities/candidate-generator.d.ts +9 -0
  99. package/dist/entities/candidate-generator.js +436 -0
  100. package/dist/entities/entity-impact.d.ts +41 -0
  101. package/dist/entities/entity-impact.js +140 -0
  102. package/dist/entities/entity-linked-decision-counts.d.ts +2 -0
  103. package/dist/entities/entity-linked-decision-counts.js +29 -0
  104. package/dist/entities/entity-list.d.ts +23 -0
  105. package/dist/entities/entity-list.js +99 -0
  106. package/dist/entities/entity-orphan-list.d.ts +26 -0
  107. package/dist/entities/entity-orphan-list.js +91 -0
  108. package/dist/entities/entity-search.d.ts +21 -0
  109. package/dist/entities/entity-search.js +150 -0
  110. package/dist/entities/errors.d.ts +65 -0
  111. package/dist/entities/errors.js +124 -0
  112. package/dist/entities/exact-merge-backfill.d.ts +11 -0
  113. package/dist/entities/exact-merge-backfill.js +161 -0
  114. package/dist/entities/lineage-backfill.d.ts +12 -0
  115. package/dist/entities/lineage-backfill.js +101 -0
  116. package/dist/entities/lineage-store.d.ts +51 -0
  117. package/dist/entities/lineage-store.js +308 -0
  118. package/dist/entities/normalization.d.ts +14 -0
  119. package/dist/entities/normalization.js +63 -0
  120. package/dist/entities/policy-store.d.ts +17 -0
  121. package/dist/entities/policy-store.js +263 -0
  122. package/dist/entities/policy-types.d.ts +72 -0
  123. package/dist/entities/policy-types.js +59 -0
  124. package/dist/entities/projection.d.ts +8 -0
  125. package/dist/entities/projection.js +82 -0
  126. package/dist/entities/provenance-query.d.ts +33 -0
  127. package/dist/entities/provenance-query.js +167 -0
  128. package/dist/entities/read-identity.d.ts +31 -0
  129. package/dist/entities/read-identity.js +264 -0
  130. package/dist/entities/recall-bridge.d.ts +5 -0
  131. package/dist/entities/recall-bridge.js +171 -0
  132. package/dist/entities/resolution-engine.d.ts +15 -0
  133. package/dist/entities/resolution-engine.js +69 -0
  134. package/dist/entities/rollback-preview.d.ts +39 -0
  135. package/dist/entities/rollback-preview.js +235 -0
  136. package/dist/entities/source-locator.d.ts +3 -0
  137. package/dist/entities/source-locator.js +32 -0
  138. package/dist/entities/store.d.ts +75 -0
  139. package/dist/entities/store.js +465 -0
  140. package/dist/entities/types.d.ts +162 -0
  141. package/dist/entities/types.js +30 -0
  142. package/dist/index.d.ts +62 -3
  143. package/dist/index.js +116 -26
  144. package/dist/mama-api.d.ts +53 -35
  145. package/dist/mama-api.js +437 -78
  146. package/dist/memory/api.d.ts +26 -38
  147. package/dist/memory/api.js +772 -68
  148. package/dist/memory/event-store.d.ts +3 -0
  149. package/dist/memory/event-store.js +21 -2
  150. package/dist/memory/provenance-audit.d.ts +22 -0
  151. package/dist/memory/provenance-audit.js +112 -0
  152. package/dist/memory/provenance-query.d.ts +11 -0
  153. package/dist/memory/provenance-query.js +193 -0
  154. package/dist/memory/provenance.d.ts +29 -0
  155. package/dist/memory/provenance.js +136 -0
  156. package/dist/memory/scope-backfill.d.ts +17 -0
  157. package/dist/memory/scope-backfill.js +77 -0
  158. package/dist/memory/types.d.ts +97 -16
  159. package/dist/model-runs/store.d.ts +13 -0
  160. package/dist/model-runs/store.js +457 -0
  161. package/dist/model-runs/tool-trace-store.d.ts +4 -0
  162. package/dist/model-runs/tool-trace-store.js +114 -0
  163. package/dist/model-runs/types.d.ts +69 -0
  164. package/dist/model-runs/types.js +5 -0
  165. package/dist/runtime/trusted-provenance.d.ts +3 -0
  166. package/dist/runtime/trusted-provenance.js +6 -0
  167. package/dist/search/feedback-store.d.ts +59 -0
  168. package/dist/search/feedback-store.js +211 -0
  169. package/dist/search/question-type.d.ts +5 -0
  170. package/dist/search/question-type.js +41 -0
  171. package/dist/search/ranker-features.d.ts +23 -0
  172. package/dist/search/ranker-features.js +104 -0
  173. package/dist/search/ranker-rescore.d.ts +31 -0
  174. package/dist/search/ranker-rescore.js +226 -0
  175. package/dist/search/ranker-trainer.d.ts +94 -0
  176. package/dist/search/ranker-trainer.js +860 -0
  177. package/dist/search/search-quality.d.ts +36 -0
  178. package/dist/search/search-quality.js +29 -0
  179. package/dist/test-utils.d.ts +14 -0
  180. package/dist/test-utils.js +52 -0
  181. package/package.json +28 -3
@@ -0,0 +1,275 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.resolveEntity = resolveEntity;
4
+ const ref_validation_js_1 = require("../edges/ref-validation.js");
5
+ const normalization_js_1 = require("../entities/normalization.js");
6
+ const store_js_1 = require("../entities/store.js");
7
+ const types_js_1 = require("../edges/types.js");
8
+ const errors_js_1 = require("./errors.js");
9
+ const TWIN_REF_KIND_SET = new Set(types_js_1.TWIN_REF_KINDS);
10
+ function hasScopes(scopes) {
11
+ return Array.isArray(scopes) && scopes.length > 0;
12
+ }
13
+ function normalizeLabel(value) {
14
+ try {
15
+ return (0, normalization_js_1.normalizeEntityLabel)(value).normalized;
16
+ }
17
+ catch (error) {
18
+ throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
19
+ }
20
+ }
21
+ function entityVisible(entity, scopes) {
22
+ if (!hasScopes(scopes)) {
23
+ return true;
24
+ }
25
+ return scopes.some((scope) => entity.scope_kind === scope.kind && entity.scope_id === scope.id);
26
+ }
27
+ function isAtOrBeforeAsOf(value, asOfMs) {
28
+ return typeof asOfMs !== 'number' || value <= asOfMs;
29
+ }
30
+ function scopeVisible(scopeKind, scopeId, scopes) {
31
+ if (!hasScopes(scopes)) {
32
+ return true;
33
+ }
34
+ return scopes.some((scope) => scope.kind === scopeKind && scope.id === scopeId);
35
+ }
36
+ function connectorVisible(connector, connectors) {
37
+ return !connectors || connectors.length === 0 || connectors.includes(connector);
38
+ }
39
+ function hasProjectOrTenantFilter(visibility) {
40
+ return ((Array.isArray(visibility.projectRefs) && visibility.projectRefs.length > 0) ||
41
+ (typeof visibility.tenantId === 'string' && visibility.tenantId.length > 0));
42
+ }
43
+ function refsVisible(adapter, refs, visibility) {
44
+ if (refs.length === 0) {
45
+ return true;
46
+ }
47
+ try {
48
+ (0, ref_validation_js_1.assertTwinRefsVisible)(adapter, refs, visibility);
49
+ return true;
50
+ }
51
+ catch {
52
+ return false;
53
+ }
54
+ }
55
+ function parseSourceRefs(value, context) {
56
+ if (value === undefined || value === null) {
57
+ return [];
58
+ }
59
+ if (!Array.isArray(value)) {
60
+ throw new Error(`${context}.source_refs must be an array.`);
61
+ }
62
+ const refs = [];
63
+ for (const item of value) {
64
+ if (item === null ||
65
+ typeof item !== 'object' ||
66
+ typeof item.kind !== 'string' ||
67
+ typeof item.id !== 'string') {
68
+ throw new Error(`${context}.source_refs entries must be TwinRef objects.`);
69
+ }
70
+ const kind = item.kind;
71
+ const id = item.id.trim();
72
+ if (!TWIN_REF_KIND_SET.has(kind) || id.length === 0) {
73
+ throw new Error(`${context}.source_refs contains an invalid TwinRef.`);
74
+ }
75
+ refs.push({ kind, id });
76
+ }
77
+ return refs;
78
+ }
79
+ function aliasSourceRefs(adapter, aliasId, entityId) {
80
+ const rows = adapter
81
+ .prepare(`
82
+ SELECT relation_attrs_json
83
+ FROM twin_edges
84
+ WHERE edge_type = 'alias_of'
85
+ AND subject_kind = 'entity'
86
+ AND subject_id = ?
87
+ AND object_kind = 'entity'
88
+ AND object_id = ?
89
+ AND relation_attrs_json IS NOT NULL
90
+ ORDER BY created_at DESC, edge_id ASC
91
+ `)
92
+ .all(entityId, entityId);
93
+ const refs = [];
94
+ const seen = new Set();
95
+ for (const row of rows) {
96
+ if (!row.relation_attrs_json) {
97
+ continue;
98
+ }
99
+ const parsed = JSON.parse(row.relation_attrs_json);
100
+ if (parsed === null ||
101
+ typeof parsed !== 'object' ||
102
+ parsed.alias_id !== aliasId) {
103
+ continue;
104
+ }
105
+ for (const ref of parseSourceRefs(parsed.source_refs, `alias ${aliasId}`)) {
106
+ const key = `${ref.kind}:${ref.id}`;
107
+ if (!seen.has(key)) {
108
+ seen.add(key);
109
+ refs.push(ref);
110
+ }
111
+ }
112
+ }
113
+ return refs;
114
+ }
115
+ function aliasVisible(adapter, row, visibility, asOfMs) {
116
+ if (!isAtOrBeforeAsOf(row.created_at, asOfMs)) {
117
+ return false;
118
+ }
119
+ const sourceRefs = aliasSourceRefs(adapter, row.id, row.entity_id);
120
+ if (row.source_type === 'agent' && sourceRefs.length === 0) {
121
+ return false;
122
+ }
123
+ return refsVisible(adapter, sourceRefs, visibility);
124
+ }
125
+ function rawRefForObservation(adapter, row) {
126
+ const raw = adapter
127
+ .prepare(`
128
+ SELECT event_index_id
129
+ FROM connector_event_index
130
+ WHERE event_index_id = ?
131
+ OR (source_connector = ? AND source_id = ?)
132
+ ORDER BY CASE WHEN event_index_id = ? THEN 0 ELSE 1 END
133
+ LIMIT 1
134
+ `)
135
+ .get(row.source_raw_record_id, row.source_connector, row.source_raw_record_id, row.source_raw_record_id);
136
+ return raw ? { kind: 'raw', id: raw.event_index_id } : null;
137
+ }
138
+ function observationVisible(adapter, row, visibility, asOfMs) {
139
+ if (!isAtOrBeforeAsOf(row.timestamp_observed ?? row.created_at, asOfMs)) {
140
+ return false;
141
+ }
142
+ if (!scopeVisible(row.scope_kind, row.scope_id, visibility.scopes)) {
143
+ return false;
144
+ }
145
+ if (!connectorVisible(row.source_connector, visibility.connectors)) {
146
+ return false;
147
+ }
148
+ const rawRef = rawRefForObservation(adapter, row);
149
+ if (!rawRef) {
150
+ return !hasProjectOrTenantFilter(visibility);
151
+ }
152
+ return refsVisible(adapter, [rawRef], visibility);
153
+ }
154
+ function canonicalEntity(adapter, entityId) {
155
+ try {
156
+ const canonicalId = (0, store_js_1.resolveCanonicalEntityId)(adapter, entityId);
157
+ const entity = (0, store_js_1.getEntityNode)(canonicalId, adapter);
158
+ return entity && entity.status === 'active' ? entity : null;
159
+ }
160
+ catch (error) {
161
+ if (error instanceof store_js_1.EntityMergeError) {
162
+ throw new errors_js_1.AgentGraphValidationError(`${error.code}: ${error.message}`);
163
+ }
164
+ throw error;
165
+ }
166
+ }
167
+ function contextBoost(adapter, entityId, contextRefs, visibility, asOfMs) {
168
+ if (!contextRefs || contextRefs.length === 0) {
169
+ return 0;
170
+ }
171
+ const edges = (0, ref_validation_js_1.listVisibleTwinEdgesForRefs)(adapter, contextRefs, {
172
+ scopes: visibility.scopes,
173
+ connectors: visibility.connectors,
174
+ projectRefs: visibility.projectRefs,
175
+ tenantId: visibility.tenantId,
176
+ asOfMs,
177
+ });
178
+ return edges.some((edge) => (edge.subject_ref.kind === 'entity' && edge.subject_ref.id === entityId) ||
179
+ (edge.object_ref.kind === 'entity' && edge.object_ref.id === entityId))
180
+ ? 0.2
181
+ : 0;
182
+ }
183
+ function resolveEntity(adapter, input) {
184
+ const normalized = normalizeLabel(input.label);
185
+ const limit = Math.max(1, Math.floor(input.limit ?? 5));
186
+ const visibility = {
187
+ scopes: input.scopes,
188
+ connectors: input.connectors,
189
+ projectRefs: input.project_refs,
190
+ tenantId: input.tenant_id,
191
+ asOfMs: input.as_of_ms,
192
+ };
193
+ if (input.context_refs && input.context_refs.length > 0) {
194
+ try {
195
+ (0, ref_validation_js_1.assertTwinRefsVisible)(adapter, input.context_refs, visibility);
196
+ }
197
+ catch (error) {
198
+ throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
199
+ }
200
+ }
201
+ const candidates = new Map();
202
+ const recordCandidate = (entityId, matchedLabel, matchSource, baseScore) => {
203
+ const entity = canonicalEntity(adapter, entityId);
204
+ if (!entity ||
205
+ !entityVisible(entity, input.scopes) ||
206
+ !isAtOrBeforeAsOf(entity.created_at, input.as_of_ms)) {
207
+ return;
208
+ }
209
+ const score = baseScore + contextBoost(adapter, entity.id, input.context_refs, visibility, input.as_of_ms);
210
+ const existing = candidates.get(entity.id);
211
+ if (!existing || score > existing.score) {
212
+ candidates.set(entity.id, {
213
+ entity,
214
+ matched_label: matchedLabel,
215
+ match_source: matchSource,
216
+ score,
217
+ });
218
+ }
219
+ };
220
+ const nodeRows = adapter
221
+ .prepare(`
222
+ SELECT id, preferred_label
223
+ FROM entity_nodes
224
+ WHERE status = 'active'
225
+ `)
226
+ .all();
227
+ for (const row of nodeRows) {
228
+ if (normalizeLabel(row.preferred_label) === normalized) {
229
+ recordCandidate(row.id, row.preferred_label, 'preferred_label', 1);
230
+ }
231
+ }
232
+ const aliasRows = adapter
233
+ .prepare(`
234
+ SELECT id, entity_id, label, normalized_label, source_type, created_at
235
+ FROM entity_aliases
236
+ WHERE status = 'active'
237
+ `)
238
+ .all();
239
+ for (const row of aliasRows) {
240
+ if (aliasVisible(adapter, row, visibility, input.as_of_ms) &&
241
+ (row.normalized_label === normalized || normalizeLabel(row.label) === normalized)) {
242
+ recordCandidate(row.entity_id, row.label, 'alias', 0.95);
243
+ }
244
+ }
245
+ const observationRows = adapter
246
+ .prepare(`
247
+ SELECT
248
+ l.canonical_entity_id, o.surface_form, o.normalized_form,
249
+ o.scope_kind, o.scope_id, o.source_connector, o.source_raw_record_id,
250
+ o.timestamp_observed, o.created_at
251
+ FROM entity_lineage_links l
252
+ JOIN entity_observations o ON o.id = l.entity_observation_id
253
+ WHERE l.status = 'active'
254
+ `)
255
+ .all();
256
+ for (const row of observationRows) {
257
+ if (observationVisible(adapter, row, visibility, input.as_of_ms) &&
258
+ (row.normalized_form === normalized || normalizeLabel(row.surface_form) === normalized)) {
259
+ recordCandidate(row.canonical_entity_id, row.surface_form, 'observation', 0.85);
260
+ }
261
+ }
262
+ const sorted = Array.from(candidates.values())
263
+ .sort((left, right) => {
264
+ if (right.score !== left.score) {
265
+ return right.score - left.score;
266
+ }
267
+ return left.entity.id.localeCompare(right.entity.id);
268
+ })
269
+ .slice(0, limit);
270
+ return {
271
+ entity: sorted[0]?.entity ?? null,
272
+ candidates: sorted,
273
+ };
274
+ }
275
+ //# sourceMappingURL=entity-resolve.js.map
@@ -0,0 +1,4 @@
1
+ export declare class AgentGraphValidationError extends Error {
2
+ constructor(message: string);
3
+ }
4
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1,11 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AgentGraphValidationError = void 0;
4
+ class AgentGraphValidationError extends Error {
5
+ constructor(message) {
6
+ super(message);
7
+ this.name = 'AgentGraphValidationError';
8
+ }
9
+ }
10
+ exports.AgentGraphValidationError = AgentGraphValidationError;
11
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1,5 @@
1
+ import type { AgentGraphAdapter, AgentGraphResult, GraphNeighborhoodInput, GraphPathsInput, GraphPathsResult, GraphTimelineInput, GraphTimelineResult } from './types.js';
2
+ export declare function getGraphNeighborhood(adapter: AgentGraphAdapter, input: GraphNeighborhoodInput): AgentGraphResult;
3
+ export declare function getGraphPaths(adapter: AgentGraphAdapter, input: GraphPathsInput): GraphPathsResult;
4
+ export declare function getGraphTimeline(adapter: AgentGraphAdapter, input: GraphTimelineInput): GraphTimelineResult;
5
+ //# sourceMappingURL=graph-query.d.ts.map
@@ -0,0 +1,359 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.getGraphNeighborhood = getGraphNeighborhood;
4
+ exports.getGraphPaths = getGraphPaths;
5
+ exports.getGraphTimeline = getGraphTimeline;
6
+ const ref_validation_js_1 = require("../edges/ref-validation.js");
7
+ const store_js_1 = require("../entities/store.js");
8
+ const errors_js_1 = require("./errors.js");
9
+ const DEFAULT_GRAPH_LIMIT = 100;
10
+ const DEFAULT_PATH_LIMIT = 10;
11
+ const MAX_DEPTH = 5;
12
+ function refKey(ref) {
13
+ return `${ref.kind}:${ref.id}`;
14
+ }
15
+ function edgeKey(edge) {
16
+ return edge.edge_id;
17
+ }
18
+ function eventKey(event) {
19
+ if (event.kind === 'edge') {
20
+ return event.edge.edge_id;
21
+ }
22
+ return `${event.ref.kind}:${event.ref.id}`;
23
+ }
24
+ function eventKindRank(kind) {
25
+ if (kind === 'entity') {
26
+ return 0;
27
+ }
28
+ if (kind === 'memory') {
29
+ return 1;
30
+ }
31
+ if (kind === 'raw') {
32
+ return 2;
33
+ }
34
+ if (kind === 'case') {
35
+ return 3;
36
+ }
37
+ return 4;
38
+ }
39
+ function normalizeDepth(value, fallback) {
40
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
41
+ return fallback;
42
+ }
43
+ return Math.max(0, Math.min(MAX_DEPTH, Math.floor(value)));
44
+ }
45
+ function normalizeLimit(value, fallback) {
46
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
47
+ return fallback;
48
+ }
49
+ return Math.max(1, Math.floor(value));
50
+ }
51
+ function addNode(nodes, seen, ref) {
52
+ const key = refKey(ref);
53
+ if (!seen.has(key)) {
54
+ seen.add(key);
55
+ nodes.push(ref);
56
+ }
57
+ }
58
+ function addRef(refs, seen, ref) {
59
+ if (ref.kind === 'edge' || ref.kind === 'report') {
60
+ return;
61
+ }
62
+ const key = refKey(ref);
63
+ if (!seen.has(key)) {
64
+ seen.add(key);
65
+ refs.push(ref);
66
+ }
67
+ }
68
+ function oppositeRef(edge, current) {
69
+ const currentKey = refKey(current);
70
+ const refs = [];
71
+ if (refKey(edge.subject_ref) !== currentKey) {
72
+ refs.push(edge.subject_ref);
73
+ }
74
+ if (refKey(edge.object_ref) !== currentKey) {
75
+ refs.push(edge.object_ref);
76
+ }
77
+ if (refs.length === 0) {
78
+ refs.push(edge.object_ref);
79
+ }
80
+ return refs;
81
+ }
82
+ function listFilteredEdges(adapter, refs, input) {
83
+ return (0, ref_validation_js_1.listVisibleTwinEdgesForRefs)(adapter, refs, {
84
+ scopes: input.visibility.scopes,
85
+ connectors: input.visibility.connectors,
86
+ projectRefs: input.visibility.projectRefs,
87
+ tenantId: input.visibility.tenantId,
88
+ edgeTypes: input.edge_filters?.edge_types,
89
+ asOfMs: input.as_of_ms,
90
+ limit: input.limit,
91
+ });
92
+ }
93
+ function assertRefsVisible(adapter, refs, visibility, asOfMs) {
94
+ try {
95
+ (0, ref_validation_js_1.assertTwinRefsVisible)(adapter, refs, { ...visibility, asOfMs });
96
+ }
97
+ catch (error) {
98
+ throw new errors_js_1.AgentGraphValidationError(error instanceof Error ? error.message : String(error));
99
+ }
100
+ }
101
+ function graphVisibility(input) {
102
+ return {
103
+ scopes: input.scopes,
104
+ connectors: input.connectors,
105
+ projectRefs: input.project_refs,
106
+ tenantId: input.tenant_id,
107
+ };
108
+ }
109
+ function numberMs(value, field, refId) {
110
+ if (typeof value === 'number' && Number.isFinite(value)) {
111
+ return Math.floor(value);
112
+ }
113
+ throw new Error(`Invalid ${field} timestamp for graph timeline ref ${refId}.`);
114
+ }
115
+ function nullableNumberMs(value, field, refId) {
116
+ if (value === null || value === undefined) {
117
+ return null;
118
+ }
119
+ return numberMs(value, field, refId);
120
+ }
121
+ function parseTimestampMs(value, field, refId) {
122
+ if (typeof value === 'number' && Number.isFinite(value)) {
123
+ return Math.floor(value);
124
+ }
125
+ if (typeof value === 'string') {
126
+ const parsed = Date.parse(value);
127
+ if (Number.isFinite(parsed)) {
128
+ return parsed;
129
+ }
130
+ }
131
+ throw new Error(`Invalid ${field} timestamp for graph timeline ref ${refId}.`);
132
+ }
133
+ function timelineWindow(input) {
134
+ const upperBounds = [input.to_ms, input.as_of_ms].filter((value) => typeof value === 'number');
135
+ return {
136
+ fromMs: input.from_ms,
137
+ toMs: upperBounds.length > 0 ? Math.min(...upperBounds) : undefined,
138
+ };
139
+ }
140
+ function isInTimelineWindow(atMs, window) {
141
+ return ((window.fromMs === undefined || atMs >= window.fromMs) &&
142
+ (window.toMs === undefined || atMs <= window.toMs));
143
+ }
144
+ function loadTimelineRecordEvent(adapter, ref) {
145
+ if (ref.kind === 'entity') {
146
+ const entity = (0, store_js_1.getEntityNode)(ref.id, adapter);
147
+ if (!entity || entity.status !== 'active') {
148
+ return null;
149
+ }
150
+ return { kind: 'entity', at_ms: entity.created_at, ref, entity };
151
+ }
152
+ if (ref.kind === 'memory') {
153
+ const row = adapter
154
+ .prepare(`
155
+ SELECT id, topic, decision, created_at, event_datetime
156
+ FROM decisions
157
+ WHERE id = ?
158
+ LIMIT 1
159
+ `)
160
+ .get(ref.id);
161
+ if (!row) {
162
+ return null;
163
+ }
164
+ const eventDatetime = nullableNumberMs(row.event_datetime, 'decisions.event_datetime', ref.id);
165
+ const createdAt = numberMs(row.created_at, 'decisions.created_at', ref.id);
166
+ return {
167
+ kind: 'memory',
168
+ at_ms: eventDatetime ?? createdAt,
169
+ ref,
170
+ memory: {
171
+ id: row.id,
172
+ topic: row.topic,
173
+ decision: row.decision,
174
+ created_at: createdAt,
175
+ event_datetime: eventDatetime,
176
+ },
177
+ };
178
+ }
179
+ if (ref.kind === 'raw') {
180
+ const row = adapter
181
+ .prepare(`
182
+ SELECT
183
+ event_index_id, source_connector, source_type, source_id, source_locator,
184
+ title, event_datetime, source_timestamp_ms
185
+ FROM connector_event_index
186
+ WHERE event_index_id = ?
187
+ LIMIT 1
188
+ `)
189
+ .get(ref.id);
190
+ if (!row) {
191
+ return null;
192
+ }
193
+ const eventDatetime = nullableNumberMs(row.event_datetime, 'connector_event_index.event_datetime', ref.id);
194
+ const sourceTimestampMs = numberMs(row.source_timestamp_ms, 'connector_event_index.source_timestamp_ms', ref.id);
195
+ return {
196
+ kind: 'raw',
197
+ at_ms: eventDatetime ?? sourceTimestampMs,
198
+ ref,
199
+ raw: {
200
+ event_index_id: row.event_index_id,
201
+ source_connector: row.source_connector,
202
+ source_type: row.source_type,
203
+ source_id: row.source_id,
204
+ source_locator: row.source_locator,
205
+ title: row.title,
206
+ event_datetime: eventDatetime,
207
+ source_timestamp_ms: sourceTimestampMs,
208
+ },
209
+ };
210
+ }
211
+ if (ref.kind === 'case') {
212
+ const row = adapter
213
+ .prepare(`
214
+ SELECT case_id, title, status, last_activity_at, created_at, updated_at
215
+ FROM case_truth
216
+ WHERE case_id = ?
217
+ LIMIT 1
218
+ `)
219
+ .get(ref.id);
220
+ if (!row) {
221
+ return null;
222
+ }
223
+ return {
224
+ kind: 'case',
225
+ at_ms: parseTimestampMs(row.last_activity_at ?? row.updated_at, 'case_truth.updated_at', ref.id),
226
+ ref,
227
+ case: {
228
+ case_id: row.case_id,
229
+ title: row.title,
230
+ status: row.status,
231
+ created_at: row.created_at,
232
+ updated_at: row.updated_at,
233
+ last_activity_at: row.last_activity_at,
234
+ },
235
+ };
236
+ }
237
+ return null;
238
+ }
239
+ function getGraphNeighborhood(adapter, input) {
240
+ const depth = normalizeDepth(input.depth, 1);
241
+ const limit = normalizeLimit(input.limit, DEFAULT_GRAPH_LIMIT);
242
+ const visibility = graphVisibility(input);
243
+ assertRefsVisible(adapter, [input.ref], visibility, input.as_of_ms);
244
+ const nodes = [];
245
+ const edges = [];
246
+ const seenNodes = new Set();
247
+ const seenEdges = new Set();
248
+ addNode(nodes, seenNodes, input.ref);
249
+ let frontier = [input.ref];
250
+ for (let currentDepth = 0; currentDepth < depth && frontier.length > 0; currentDepth++) {
251
+ const found = listFilteredEdges(adapter, frontier, {
252
+ visibility,
253
+ edge_filters: input.edge_filters,
254
+ as_of_ms: input.as_of_ms,
255
+ limit,
256
+ });
257
+ const nextFrontier = [];
258
+ const nextKeys = new Set();
259
+ for (const edge of found) {
260
+ if (seenEdges.size >= limit) {
261
+ break;
262
+ }
263
+ if (!seenEdges.has(edgeKey(edge))) {
264
+ seenEdges.add(edgeKey(edge));
265
+ edges.push(edge);
266
+ }
267
+ for (const endpoint of [edge.subject_ref, edge.object_ref]) {
268
+ const before = seenNodes.size;
269
+ addNode(nodes, seenNodes, endpoint);
270
+ if (seenNodes.size > before && !nextKeys.has(refKey(endpoint))) {
271
+ nextKeys.add(refKey(endpoint));
272
+ nextFrontier.push(endpoint);
273
+ }
274
+ }
275
+ }
276
+ frontier = nextFrontier;
277
+ }
278
+ return { nodes, edges };
279
+ }
280
+ function getGraphPaths(adapter, input) {
281
+ const maxDepth = normalizeDepth(input.max_depth, 3);
282
+ const limit = normalizeLimit(input.limit, DEFAULT_PATH_LIMIT);
283
+ const visibility = graphVisibility(input);
284
+ assertRefsVisible(adapter, [input.from_ref, input.to_ref], visibility, input.as_of_ms);
285
+ const targetKey = refKey(input.to_ref);
286
+ const queue = [{ refs: [input.from_ref], edges: [] }];
287
+ const paths = [];
288
+ while (queue.length > 0 && paths.length < limit) {
289
+ const path = queue.shift();
290
+ if (!path) {
291
+ break;
292
+ }
293
+ const current = path.refs[path.refs.length - 1];
294
+ if (!current || path.edges.length >= maxDepth) {
295
+ continue;
296
+ }
297
+ const edges = listFilteredEdges(adapter, [current], {
298
+ visibility,
299
+ edge_filters: input.edge_filters,
300
+ as_of_ms: input.as_of_ms,
301
+ });
302
+ for (const edge of edges) {
303
+ for (const next of oppositeRef(edge, current)) {
304
+ if (path.refs.some((ref) => refKey(ref) === refKey(next))) {
305
+ continue;
306
+ }
307
+ const nextPath = { refs: [...path.refs, next], edges: [...path.edges, edge] };
308
+ if (refKey(next) === targetKey) {
309
+ paths.push(nextPath);
310
+ if (paths.length >= limit) {
311
+ break;
312
+ }
313
+ }
314
+ else {
315
+ queue.push(nextPath);
316
+ }
317
+ }
318
+ if (paths.length >= limit) {
319
+ break;
320
+ }
321
+ }
322
+ }
323
+ return { paths };
324
+ }
325
+ function getGraphTimeline(adapter, input) {
326
+ const visibility = graphVisibility(input);
327
+ assertRefsVisible(adapter, [input.ref], visibility, input.as_of_ms);
328
+ const limit = normalizeLimit(input.limit, DEFAULT_GRAPH_LIMIT);
329
+ const window = timelineWindow(input);
330
+ const edges = listFilteredEdges(adapter, [input.ref], {
331
+ visibility,
332
+ edge_filters: input.edge_filters,
333
+ as_of_ms: input.as_of_ms,
334
+ }).filter((edge) => isInTimelineWindow(edge.created_at, window));
335
+ const refs = [];
336
+ const seenRefs = new Set();
337
+ addRef(refs, seenRefs, input.ref);
338
+ for (const edge of edges) {
339
+ addRef(refs, seenRefs, edge.subject_ref);
340
+ addRef(refs, seenRefs, edge.object_ref);
341
+ }
342
+ const events = [];
343
+ for (const ref of refs) {
344
+ const event = loadTimelineRecordEvent(adapter, ref);
345
+ if (event && isInTimelineWindow(event.at_ms, window)) {
346
+ events.push(event);
347
+ }
348
+ }
349
+ events.push(...edges.map((edge) => ({ kind: 'edge', at_ms: edge.created_at, edge })));
350
+ return {
351
+ ref: input.ref,
352
+ events: events
353
+ .sort((left, right) => left.at_ms - right.at_ms ||
354
+ eventKindRank(left.kind) - eventKindRank(right.kind) ||
355
+ eventKey(left).localeCompare(eventKey(right)))
356
+ .slice(0, limit),
357
+ };
358
+ }
359
+ //# sourceMappingURL=graph-query.js.map
@@ -0,0 +1,6 @@
1
+ export * from './types.js';
2
+ export * from './errors.js';
3
+ export * from './entity-resolve.js';
4
+ export * from './graph-query.js';
5
+ export * from './alias-write.js';
6
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,22 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ __exportStar(require("./types.js"), exports);
18
+ __exportStar(require("./errors.js"), exports);
19
+ __exportStar(require("./entity-resolve.js"), exports);
20
+ __exportStar(require("./graph-query.js"), exports);
21
+ __exportStar(require("./alias-write.js"), exports);
22
+ //# sourceMappingURL=index.js.map