@atolis-hq/corum 0.1.34 → 0.1.36

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.
@@ -1,25 +1,67 @@
1
1
  import { printBanner } from '../banner.js';
2
2
  import { Server } from '@modelcontextprotocol/sdk/server/index.js';
3
3
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
- import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
4
+ import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
5
5
  import { pathToFileURL } from 'node:url';
6
- import { computeClusterOverlay, getCluster, getLinkedFields, listNodes } from '../graph/index.js';
6
+ import { computeClusterOverlay, getClusterView, getGraphSummary, getLineage, getLinkedFields, listNodes, SEMANTIC_EDGE_TYPES, searchNodes, STRUCTURAL_NODE_TEMPLATES, } from '../graph/index.js';
7
7
  import { loadGraph, loadMultiGraph } from '../loader/index.js';
8
8
  import { QueryError } from '../schema/index.js';
9
9
  import { createGraphRuntimeConfig } from '../source/config.js';
10
10
  import { startGraphFileWatcher, startWebServer } from '../web/server.js';
11
+ import { USAGE_GUIDE_PROMPT } from './prompts/usage-guide.js';
11
12
  import { compactKeys, getSerializer } from './serializers.js';
13
+ const EDGE_TYPES = [
14
+ 'triggers',
15
+ 'produces',
16
+ 'reads',
17
+ 'calls',
18
+ 'implements',
19
+ 'maps-to',
20
+ 'derived-from',
21
+ 'renamed-from',
22
+ 'has-field',
23
+ 'has-value',
24
+ ];
25
+ const EDGE_TYPE_SET = new Set(EDGE_TYPES);
26
+ const STATE_VALUES = ['draft', 'proposed', 'agreed', 'future', 'removed', 'implemented'];
27
+ const STABILITY_VALUES = ['unstable', 'stable', 'deprecated'];
28
+ const LINEAGE_DIRECTIONS = ['downstream', 'upstream', 'both'];
29
+ const OUTPUT_FORMATS = ['yaml', 'json', 'toon'];
30
+ function toStringArray(value) {
31
+ return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : undefined;
32
+ }
33
+ function parseEdgeTypes(value) {
34
+ const requested = toStringArray(value);
35
+ if (!requested)
36
+ return undefined;
37
+ const invalid = requested.filter(type => !EDGE_TYPE_SET.has(type));
38
+ if (invalid.length > 0) {
39
+ throw new QueryError(`Unknown edge type: ${invalid.join(', ')}`);
40
+ }
41
+ return requested;
42
+ }
43
+ function parseListNodesFilter(value) {
44
+ const filterArg = typeof value === 'object' && value !== null
45
+ ? value
46
+ : {};
47
+ return {
48
+ templates: toStringArray(filterArg.templates),
49
+ excludeTemplates: toStringArray(filterArg.exclude_templates),
50
+ component: typeof filterArg.component === 'string' ? filterArg.component : undefined,
51
+ state: typeof filterArg.state === 'string'
52
+ ? filterArg.state
53
+ : toStringArray(filterArg.state),
54
+ stability: typeof filterArg.stability === 'string'
55
+ ? filterArg.stability
56
+ : toStringArray(filterArg.stability),
57
+ };
58
+ }
12
59
  export function createMcpHandlers(graph, source, cache) {
13
60
  const resolveMulti = (src) => cache ? cache.get() : loadMultiGraph({ source: src });
14
61
  return {
15
62
  list_nodes(args) {
16
63
  const run = (targetGraph) => {
17
- const filter = {
18
- template: typeof args.template === 'string' ? args.template : undefined,
19
- component: typeof args.component === 'string' ? args.component : undefined,
20
- state: typeof args.state === 'string' ? args.state : undefined,
21
- stability: typeof args.stability === 'string' ? args.stability : undefined,
22
- };
64
+ const filter = parseListNodesFilter(args.filter);
23
65
  const summaries = listNodes(targetGraph, filter).map(node => ({
24
66
  id: node.id,
25
67
  template: node.template,
@@ -39,6 +81,44 @@ export function createMcpHandlers(graph, source, cache) {
39
81
  return errorResult(err);
40
82
  }
41
83
  },
84
+ get_graph_summary(args) {
85
+ const run = (targetGraph) => formatResult(getGraphSummary(targetGraph), args.format, getCompactKeys(args));
86
+ if (hasBranch(args) && source) {
87
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
88
+ }
89
+ try {
90
+ return run(graph);
91
+ }
92
+ catch (err) {
93
+ return errorResult(err);
94
+ }
95
+ },
96
+ search_nodes(args) {
97
+ const queries = Array.isArray(args.queries)
98
+ ? args.queries.filter((query) => typeof query === 'string')
99
+ : [];
100
+ if (queries.length === 0)
101
+ return errorResult(new QueryError('queries is required'));
102
+ const run = (targetGraph) => {
103
+ const options = {
104
+ templates: toStringArray(args.templates),
105
+ excludeTemplates: toStringArray(args.exclude_templates),
106
+ limit: typeof args.page_size === 'number' ? args.page_size : 10,
107
+ offset: typeof args.offset === 'number' ? args.offset : 0,
108
+ searchProperties: args.search_properties === true,
109
+ };
110
+ return formatResult(searchNodes(targetGraph, queries, options), args.format, getCompactKeys(args));
111
+ };
112
+ if (hasBranch(args) && source) {
113
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
114
+ }
115
+ try {
116
+ return run(graph);
117
+ }
118
+ catch (err) {
119
+ return errorResult(err);
120
+ }
121
+ },
42
122
  list_templates(args) {
43
123
  const run = (targetGraph) => {
44
124
  const summaries = [...targetGraph.templates.values()]
@@ -81,7 +161,9 @@ export function createMcpHandlers(graph, source, cache) {
81
161
  ? args.overlay_refs.filter((ref) => typeof ref === 'string')
82
162
  : [];
83
163
  const run = async (targetGraph, branchRef) => {
84
- const cluster = getCluster(targetGraph, String(args.node_id));
164
+ const edgeTypes = parseEdgeTypes(args.edge_types)
165
+ ?? [...SEMANTIC_EDGE_TYPES];
166
+ const cluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
85
167
  if (overlayRefs.length === 0 || !source || !branchRef) {
86
168
  return formatResult(cluster, args.format, getCompactKeys(args));
87
169
  }
@@ -95,6 +177,103 @@ export function createMcpHandlers(graph, source, cache) {
95
177
  }
96
178
  return run(graph).catch(err => errorResult(err));
97
179
  },
180
+ get_graph(args) {
181
+ const run = (targetGraph) => {
182
+ const filter = parseListNodesFilter(args.filter);
183
+ const effectiveFilter = (!filter.templates?.length && !filter.excludeTemplates?.length)
184
+ ? { ...filter, excludeTemplates: [...STRUCTURAL_NODE_TEMPLATES] }
185
+ : filter;
186
+ const nodes = listNodes(targetGraph, effectiveFilter)
187
+ .map(node => ({
188
+ id: node.id,
189
+ template: node.template,
190
+ component: node.component,
191
+ state: node.state,
192
+ stability: node.stability,
193
+ }));
194
+ const nodeIds = new Set(nodes.map(node => node.id));
195
+ const edges = [];
196
+ for (const edgeList of targetGraph.edgesByFrom.values()) {
197
+ for (const edge of edgeList) {
198
+ if (!SEMANTIC_EDGE_TYPES.has(edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
199
+ continue;
200
+ edges.push({ id: edge.id, from: edge.from, to: edge.to, type: edge.type });
201
+ }
202
+ }
203
+ return formatResult({ nodes, edges }, args.format, getCompactKeys(args));
204
+ };
205
+ if (hasBranch(args) && source) {
206
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
207
+ }
208
+ try {
209
+ return run(graph);
210
+ }
211
+ catch (err) {
212
+ return errorResult(err);
213
+ }
214
+ },
215
+ get_graph_metadata(args) {
216
+ const run = (targetGraph) => {
217
+ const nodeTemplatesInUse = new Set();
218
+ for (const node of targetGraph.nodesById.values())
219
+ nodeTemplatesInUse.add(node.template);
220
+ const edgeTypesInUse = new Set();
221
+ for (const edgeList of targetGraph.edgesByFrom.values()) {
222
+ for (const edge of edgeList)
223
+ edgeTypesInUse.add(edge.type);
224
+ }
225
+ return formatResult({
226
+ template_names: [...targetGraph.templates.keys()].sort(),
227
+ node_templates_in_use: [...nodeTemplatesInUse].sort(),
228
+ edge_types_in_use: [...edgeTypesInUse].sort(),
229
+ valid_edge_types: [...EDGE_TYPES],
230
+ states: [...STATE_VALUES],
231
+ stabilities: [...STABILITY_VALUES],
232
+ lineage_directions: [...LINEAGE_DIRECTIONS],
233
+ output_formats: [...OUTPUT_FORMATS],
234
+ }, args.format, getCompactKeys(args));
235
+ };
236
+ if (hasBranch(args) && source) {
237
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
238
+ }
239
+ try {
240
+ return run(graph);
241
+ }
242
+ catch (err) {
243
+ return errorResult(err);
244
+ }
245
+ },
246
+ get_lineage(args) {
247
+ const nodeIds = Array.isArray(args.node_ids)
248
+ ? args.node_ids.filter((id) => typeof id === 'string')
249
+ : [];
250
+ if (nodeIds.length === 0)
251
+ return errorResult(new QueryError('node_ids is required'));
252
+ const run = (targetGraph) => {
253
+ const direction = ['downstream', 'upstream', 'both'].includes(args.direction)
254
+ ? args.direction
255
+ : 'downstream';
256
+ const options = {
257
+ depth: typeof args.depth === 'number' ? args.depth : 2,
258
+ direction,
259
+ edgeTypes: parseEdgeTypes(args.edge_types),
260
+ nodeTypes: toStringArray(args.node_types),
261
+ excludeNodeTypes: toStringArray(args.exclude_node_types),
262
+ includeDanglingEdges: args.include_dangling_edges === true,
263
+ readsOutboundOnly: args.reads_outbound_only !== false,
264
+ };
265
+ return formatResult(getLineage(targetGraph, nodeIds, options), args.format, getCompactKeys(args));
266
+ };
267
+ if (hasBranch(args) && source) {
268
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
269
+ }
270
+ try {
271
+ return run(graph);
272
+ }
273
+ catch (err) {
274
+ return errorResult(err);
275
+ }
276
+ },
98
277
  get_linked_fields(args) {
99
278
  const run = (targetGraph) => formatResult(getLinkedFields(targetGraph, String(args.node_id)), args.format, getCompactKeys(args));
100
279
  if (hasBranch(args)) {
@@ -197,7 +376,26 @@ export async function startMcpServer(options = {}) {
197
376
  else if (watch && config.fileWatcherGraphPath) {
198
377
  startGraphFileWatcher(graph, { graphPath: config.fileWatcherGraphPath });
199
378
  }
200
- const server = new Server({ name: 'corum', version: '0.1.0' }, { capabilities: { tools: {} } });
379
+ const server = new Server({ name: 'corum', version: '0.1.0' }, { capabilities: { tools: {}, prompts: {} } });
380
+ server.setRequestHandler(ListPromptsRequestSchema, async () => ({
381
+ prompts: [
382
+ {
383
+ name: 'usage-guide',
384
+ description: 'Orientation guide - recommended workflow, node ID format, edge types, output formats, and common query patterns.',
385
+ },
386
+ ],
387
+ }));
388
+ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
389
+ if (request.params.name !== 'usage-guide') {
390
+ throw new Error(`Unknown prompt: ${request.params.name}`);
391
+ }
392
+ return {
393
+ description: 'Corum graph query orientation guide',
394
+ messages: [
395
+ { role: 'user', content: { type: 'text', text: USAGE_GUIDE_PROMPT } },
396
+ ],
397
+ };
398
+ });
201
399
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
202
400
  tools: [
203
401
  {
@@ -206,10 +404,31 @@ export async function startMcpServer(options = {}) {
206
404
  inputSchema: {
207
405
  type: 'object',
208
406
  properties: {
209
- template: { type: 'string', description: 'Filter by template name' },
210
- component: { type: 'string', description: 'Filter by component name' },
211
- state: { type: 'string', description: 'Filter by lifecycle state' },
212
- stability: { type: 'string', description: 'Filter by stability' },
407
+ filter: {
408
+ type: 'object',
409
+ description: 'Filter criteria',
410
+ properties: {
411
+ templates: {
412
+ type: 'array',
413
+ items: { type: 'string' },
414
+ description: 'Include only these template types (OR semantics)',
415
+ },
416
+ exclude_templates: {
417
+ type: 'array',
418
+ items: { type: 'string' },
419
+ description: 'Exclude these template types',
420
+ },
421
+ component: { type: 'string', description: 'Filter by component name' },
422
+ state: {
423
+ description: 'Filter by lifecycle state as a string or array',
424
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
425
+ },
426
+ stability: {
427
+ description: 'Filter by stability as a string or array',
428
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
429
+ },
430
+ },
431
+ },
213
432
  branch: { type: 'string', description: 'Branch ref to load nodes from' },
214
433
  format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
215
434
  compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
@@ -249,6 +468,13 @@ export async function startMcpServer(options = {}) {
249
468
  required: ['node_id'],
250
469
  properties: {
251
470
  node_id: { type: 'string', description: 'Fully qualified node ID' },
471
+ edge_types: {
472
+ type: 'array',
473
+ items: { type: 'string' },
474
+ description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
475
+ },
476
+ include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
477
+ reads_outbound_only: { type: 'boolean', description: 'Restrict reads edges to outbound only. Default true.' },
252
478
  branch: { type: 'string', description: 'Branch ref to load the cluster from' },
253
479
  overlay_refs: {
254
480
  type: 'array',
@@ -260,6 +486,65 @@ export async function startMcpServer(options = {}) {
260
486
  },
261
487
  },
262
488
  },
489
+ {
490
+ name: 'get_graph',
491
+ description: 'Return all semantic nodes and edges. Excludes structural templates and structural edge types by default.',
492
+ inputSchema: {
493
+ type: 'object',
494
+ properties: {
495
+ filter: {
496
+ type: 'object',
497
+ properties: {
498
+ templates: { type: 'array', items: { type: 'string' } },
499
+ exclude_templates: { type: 'array', items: { type: 'string' } },
500
+ component: { type: 'string' },
501
+ state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
502
+ stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
503
+ },
504
+ },
505
+ branch: { type: 'string', description: 'Branch ref to load the graph from' },
506
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
507
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
508
+ },
509
+ },
510
+ },
511
+ {
512
+ name: 'get_graph_metadata',
513
+ description: 'Return discoverable graph metadata: template names, node templates in use, edge types, and valid enum values.',
514
+ inputSchema: {
515
+ type: 'object',
516
+ properties: {
517
+ branch: { type: 'string', description: 'Branch ref to load metadata from' },
518
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
519
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
520
+ },
521
+ },
522
+ },
523
+ {
524
+ name: 'get_lineage',
525
+ description: 'Traverse the graph from one or more origin nodes via BFS and return annotated lineage results.',
526
+ inputSchema: {
527
+ type: 'object',
528
+ required: ['node_ids'],
529
+ properties: {
530
+ node_ids: {
531
+ type: 'array',
532
+ items: { type: 'string' },
533
+ description: 'Fully-qualified IDs of origin nodes. All expand in parallel.',
534
+ },
535
+ depth: { type: 'number', description: 'Max hops. Default 2.' },
536
+ direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Traversal direction. Default downstream.' },
537
+ edge_types: { type: 'array', items: { type: 'string' }, description: 'Edge types to traverse. Default: all non-structural.' },
538
+ node_types: { type: 'array', items: { type: 'string' }, description: 'Allowlist of node templates.' },
539
+ exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
540
+ include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the result set. Default false.' },
541
+ reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
542
+ branch: { type: 'string', description: 'Branch ref to load the lineage from' },
543
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
544
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
545
+ },
546
+ },
547
+ },
263
548
  {
264
549
  name: 'get_linked_fields',
265
550
  description: 'Get all maps-to edges touching fields owned by the given root node.',
@@ -274,6 +559,41 @@ export async function startMcpServer(options = {}) {
274
559
  },
275
560
  },
276
561
  },
562
+ {
563
+ name: 'get_graph_summary',
564
+ description: 'Return high-level statistics: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
565
+ inputSchema: {
566
+ type: 'object',
567
+ properties: {
568
+ branch: { type: 'string', description: 'Branch ref to load the summary from' },
569
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
570
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
571
+ },
572
+ },
573
+ },
574
+ {
575
+ name: 'search_nodes',
576
+ description: 'Fuzzy search for root-level nodes by ID segments. Returns ranked results with score.',
577
+ inputSchema: {
578
+ type: 'object',
579
+ required: ['queries'],
580
+ properties: {
581
+ queries: {
582
+ type: 'array',
583
+ items: { type: 'string' },
584
+ description: 'Search terms. OR semantics; any matching term qualifies the node.',
585
+ },
586
+ templates: { type: 'array', items: { type: 'string' }, description: 'Include only these template types.' },
587
+ exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these template types.' },
588
+ page_size: { type: 'number', description: 'Max results to return. Default 10.' },
589
+ offset: { type: 'number', description: 'Result offset for pagination. Default 0.' },
590
+ search_properties: { type: 'boolean', description: 'Also match name, description, and x-aka properties.' },
591
+ branch: { type: 'string', description: 'Branch ref to search within' },
592
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
593
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
594
+ },
595
+ },
596
+ },
277
597
  {
278
598
  name: 'list_branches',
279
599
  description: 'List branches available from the configured graph source and their load status.',
@@ -314,8 +634,18 @@ export async function startMcpServer(options = {}) {
314
634
  return await handlers.get_template(args);
315
635
  case 'get_cluster':
316
636
  return await handlers.get_cluster(args);
637
+ case 'get_graph':
638
+ return await handlers.get_graph(args);
639
+ case 'get_graph_metadata':
640
+ return await handlers.get_graph_metadata(args);
641
+ case 'get_lineage':
642
+ return await handlers.get_lineage(args);
317
643
  case 'get_linked_fields':
318
644
  return await handlers.get_linked_fields(args);
645
+ case 'get_graph_summary':
646
+ return await handlers.get_graph_summary(args);
647
+ case 'search_nodes':
648
+ return await handlers.search_nodes(args);
319
649
  case 'list_branches':
320
650
  return await handlers.list_branches(args);
321
651
  case 'diff_branch':
@@ -0,0 +1,74 @@
1
+ export const USAGE_GUIDE_PROMPT = `
2
+ # Corum graph - orientation guide
3
+
4
+ Corum models service architecture as a typed graph. Nodes are design artifacts; edges are typed relationships between them.
5
+
6
+ ## Node IDs
7
+
8
+ IDs encode the ownership hierarchy as a dot-separated path:
9
+
10
+ {component}.{Template}.{name} - root node
11
+ {component}.{Template}.{name}.{section}.{child} - owned child (for example operations, schemas, fields)
12
+
13
+ Examples:
14
+ orders.DomainModel.order
15
+ orders.DomainModel.order.operations.place
16
+ orders.APIEndpoint.create-order
17
+
18
+ search_nodes and list_nodes only return root nodes.
19
+
20
+ ## Edge types
21
+
22
+ Semantic (traversed by default in get_lineage / get_cluster):
23
+ triggers, produces, reads, calls, implements, maps-to, derived-from
24
+
25
+ Structural (excluded from traversal by default):
26
+ has-field, has-value, renamed-from
27
+
28
+ ## Graph completeness
29
+
30
+ The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists.
31
+
32
+ When likely relationships are absent, treat naming, shared component context, schema similarity, and lineage adjacency as hypotheses. Then verify by inspecting the relevant nodes, clusters, and source material.
33
+
34
+ ## Recommended workflow
35
+
36
+ 1. Orient - call get_graph_summary first. Returns node count, component count, orphan count, edge counts by type, and diagnostic count.
37
+
38
+ 2. Discover valid values - call get_graph_metadata when you need the available template names, edge types, or enum values for filters and traversal options.
39
+
40
+ 3. Find nodes - use search_nodes with one or more terms (OR semantics). It fuzzy-matches node IDs and, when search_properties is enabled, names, descriptions, and x-aka aliases. Pass templates to restrict to a type, for example ["DomainModel"].
41
+
42
+ 4. Inspect a node - use get_cluster with a fully-qualified node ID. Returns the root, its owned descendants, and included semantic neighbors.
43
+
44
+ 5. Trace relationships - use get_lineage from one or more node IDs. Default: depth 2 downstream. Use direction "both" and a higher depth to see event flow around a node. Each result node carries origin_id, depth, via_edge_type, and via_node_id. When multiple origins reach the same node, origins lists all origin IDs.
45
+
46
+ 6. Broad scan - use get_graph or list_nodes with filters to fetch nodes across the graph. get_graph supports templates, exclude_templates, component, state, and stability filters.
47
+
48
+ ## Output format tips
49
+
50
+ - Default format is YAML.
51
+ - Use format "json" when you want conventional structured output for downstream parsing.
52
+ - Use format "toon" when you want the most token-efficient machine-readable output, especially for large node or edge lists.
53
+ - Add compact_keys true to shorten common keys (id->i, template->t, component->cp, state->s, stability->st).
54
+
55
+ ## Common patterns
56
+
57
+ All events in a component:
58
+ list_nodes - filter { templates: ["DomainEvent", "IntegrationEvent"], component: "orders" }
59
+
60
+ What does an operation produce?
61
+ get_lineage - node_ids: ["orders.DomainModel.order.operations.place"], direction: "downstream"
62
+
63
+ What triggers an operation?
64
+ get_lineage - node_ids: ["orders.DomainModel.order.operations.complete"], direction: "upstream"
65
+
66
+ Full event flow around a node:
67
+ get_lineage - node_ids: ["orders.DomainEvent.order-placed"], direction: "both", depth: 3
68
+
69
+ Field-level mappings between nodes:
70
+ get_linked_fields - returns all maps-to edges touching fields owned by a root node
71
+
72
+ Schema / field details:
73
+ get_cluster - descendants include owned schemas, fields, and enum values
74
+ `.trim();