@atolis-hq/corum 0.1.37 → 0.1.39

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.
package/README.md CHANGED
@@ -301,7 +301,7 @@ Or if installed globally:
301
301
  | `list_nodes` | List graph nodes using a `filter` object with `templates`, `exclude_templates`, `component`, `state`, and `stability` |
302
302
  | `list_templates` | List loaded templates with summary metadata |
303
303
  | `get_template` | Return full details for a template |
304
- | `get_cluster` | Return a root node, its descendants, included external nodes, and edges for one node's full structural detail |
304
+ | `get_cluster` | Return a node's structural contents. By default, schema and enum child nodes are collapsed into compact `schemas` and `enums` blocks on the root. Pass `collapse_schemas: false` to restore the full node-per-field representation |
305
305
  | `get_graph` | Return the semantic graph as `{ nodes, edges }`, excluding structural templates and structural edges by default |
306
306
  | `get_graph_metadata` | Return discoverable metadata: template names, node templates in use, edge types, and valid enum values |
307
307
  | `get_lineage` | Traverse lineage from one or more start nodes. Lean nodes and no `edges` by default; opt in to fuller payloads when needed |
@@ -324,7 +324,7 @@ Common notes:
324
324
  - `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, `reads_outbound_only`, `lean`, and `include_edges`.
325
325
  - `get_lineage` defaults to `lean: true` and `include_edges: false`. Lean lineage nodes contain only `id`, `origin_id`, `depth`, `via_edge_type`, and `via_node_id`.
326
326
  - Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.
327
- - Use `get_cluster` only when you need full structural contents for one node such as schemas and fields. Use `get_lineage` for relationship traversal.
327
+ - Use `get_cluster` only when you need full structural contents for one node. By default it returns compact `schemas` and `enums` blocks on the root rather than individual field nodes, which keeps response size manageable for large aggregates. Use `get_lineage` for relationship traversal.
328
328
  - The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists; agents should treat naming and schema similarity as hypotheses and then verify via cluster inspection or source material.
329
329
 
330
330
  ## MCP Prompts
@@ -2,6 +2,7 @@ const VALID_EDGE_TYPES = new Set([
2
2
  'triggers', 'produces', 'reads', 'calls', 'implements',
3
3
  'maps-to', 'derived-from', 'renamed-from', 'has-field', 'has-value',
4
4
  ]);
5
+ const UNRESOLVED_COMPONENT = '_unresolved';
5
6
  export function mapDocument(document, specPath) {
6
7
  const nodes = [];
7
8
  const edges = [];
@@ -9,6 +10,10 @@ export function mapDocument(document, specPath) {
9
10
  const allSchemas = (document.components?.schemas ?? {});
10
11
  // Maps #/components/schemas/X and #/components/schemas/X/properties/Y to materialized node IDs
11
12
  const refToNodeId = new Map();
13
+ const rootNodeIds = getRootNodeIds(document.nodes);
14
+ // Pre-pass: determine canonical component for each schema (shared if referenced by 2+ components)
15
+ const schemaComponents = computeSchemaComponents(document, allSchemas);
16
+ const schemaUsage = computeSchemaUsage(document, allSchemas, rootNodeIds);
12
17
  for (const gap of document.gaps ?? []) {
13
18
  const msg = gap.nodeId
14
19
  ? `[${gap.kind}] ${gap.nodeId}: ${gap.reason ?? ''}`
@@ -20,7 +25,8 @@ export function mapDocument(document, specPath) {
20
25
  diagnostics.push({ severity: 'warning', file: specPath, message: 'Node missing id or type — skipping' });
21
26
  continue;
22
27
  }
23
- const component = nodeId.split('.')[0];
28
+ const normalizedNodeId = normalizeNodeId(nodeId);
29
+ const component = componentFromNodeId(normalizedNodeId);
24
30
  const properties = {};
25
31
  let schemaName;
26
32
  if (entry.schema?.$ref) {
@@ -34,50 +40,40 @@ export function mapDocument(document, specPath) {
34
40
  if (entry['x-aka']?.length) {
35
41
  properties['x-aka'] = entry['x-aka'];
36
42
  }
37
- const node = makeNode(entry.type, component, specPath, nodeId, entry.provenance, properties);
43
+ const node = makeNode(entry.type, component, specPath, normalizedNodeId, entry.provenance, properties);
38
44
  nodes.push(node);
39
45
  if (schemaName) {
40
46
  const expanded = new Map();
41
- expandSchema(schemaName, nodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
47
+ expandSchema(schemaName, normalizedNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
42
48
  }
43
49
  }
44
- // Expand schemas referenced in edges that weren't reachable via any node's schema ref.
45
- // Uses schema name as its own synthetic root so IDs are self-contained and don't collide.
46
- // Enum schemas register their enum values as field nodes so edge refs to them can resolve.
47
- const orphanExpanded = new Set();
48
- for (const raw of document.edges ?? []) {
49
- for (const endpoint of [raw.from, raw.to]) {
50
- const schemaName = extractSchemaName(endpoint);
51
- if (!schemaName)
52
- continue;
53
- const schemaRef = `#/components/schemas/${schemaName}`;
54
- if (refToNodeId.has(schemaRef) || orphanExpanded.has(schemaName))
55
- continue;
56
- orphanExpanded.add(schemaName);
57
- const schemaLocalName = schemaName.includes('.')
58
- ? schemaName.slice(schemaName.lastIndexOf('.') + 1)
59
- : schemaName;
60
- const schemaId = `${schemaLocalName}.schemas.${schemaLocalName}`;
61
- refToNodeId.set(schemaRef, schemaId);
62
- nodes.push(makeNode('Schema', '_', specPath, schemaId, undefined, {}));
63
- const schemaDef = allSchemas[schemaName];
64
- for (const fieldName of Object.keys(schemaDef?.properties ?? {})) {
65
- const fieldId = `${schemaId}.fields.${fieldName}`;
66
- refToNodeId.set(`${schemaRef}/properties/${fieldName}`, fieldId);
67
- nodes.push(makeNode('Field', '_', specPath, fieldId, undefined, {}));
68
- edges.push(makeHasFieldEdge(schemaId, fieldId));
69
- }
70
- if (Array.isArray(schemaDef?.enum)) {
71
- for (const value of schemaDef.enum) {
72
- if (typeof value !== 'string')
73
- continue;
74
- const fieldId = `${schemaId}.values.${value}`;
75
- refToNodeId.set(`${schemaRef}/properties/${value}`, fieldId);
76
- nodes.push(makeNode('EnumValue', '_', specPath, fieldId, undefined, { value }));
77
- edges.push(makeHasFieldEdge(schemaId, fieldId));
78
- }
79
- }
50
+ for (const schemaName of Object.keys(allSchemas)) {
51
+ const schemaRef = `#/components/schemas/${schemaName}`;
52
+ if (refToNodeId.has(schemaRef))
53
+ continue;
54
+ const ownership = determineSchemaOwnership(schemaName, schemaUsage);
55
+ if (ownership.kind === 'unused') {
56
+ diagnostics.push({
57
+ severity: 'warning',
58
+ file: specPath,
59
+ message: `Skipping unused schema '${schemaName}' because no node or edge refers to it`,
60
+ });
61
+ continue;
80
62
  }
63
+ if (ownership.kind === 'unresolved') {
64
+ diagnostics.push({
65
+ severity: 'warning',
66
+ file: specPath,
67
+ message: `Schema '${schemaName}' is only referenced by unresolved schema edges; keeping it under ${UNRESOLVED_COMPONENT}`,
68
+ });
69
+ materializeStandaloneSchema(schemaName, UNRESOLVED_COMPONENT, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents);
70
+ continue;
71
+ }
72
+ if (ownership.kind === 'inline') {
73
+ expandSchema(schemaName, ownership.rootNodeId, allSchemas, nodes, edges, specPath, ownership.component, new Map(), refToNodeId, schemaComponents);
74
+ continue;
75
+ }
76
+ materializeStandaloneSchema(schemaName, ownership.component, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents);
81
77
  }
82
78
  // Build case-insensitive fallback index to handle PascalCase/camelCase mismatches
83
79
  // between edge field refs and actual schema property names
@@ -91,8 +87,8 @@ export function mapDocument(document, specPath) {
91
87
  });
92
88
  continue;
93
89
  }
94
- const from = refToNodeId.get(raw.from) ?? refToNodeIdLower.get(raw.from.toLowerCase()) ?? raw.from;
95
- const to = refToNodeId.get(raw.to) ?? refToNodeIdLower.get(raw.to.toLowerCase()) ?? raw.to;
90
+ const from = refToNodeId.get(raw.from) ?? refToNodeIdLower.get(raw.from.toLowerCase()) ?? normalizeNodeId(raw.from);
91
+ const to = refToNodeId.get(raw.to) ?? refToNodeIdLower.get(raw.to.toLowerCase()) ?? normalizeNodeId(raw.to);
96
92
  if (from.startsWith('#/') || to.startsWith('#/')) {
97
93
  diagnostics.push({
98
94
  severity: 'warning',
@@ -105,6 +101,153 @@ export function mapDocument(document, specPath) {
105
101
  }
106
102
  return { nodes, edges, diagnostics };
107
103
  }
104
+ // Pre-pass: walk every node's schema tree to determine which component each schema belongs to.
105
+ // If a schema is referenced by nodes in 2+ different components it is assigned 'shared'.
106
+ function computeSchemaComponents(document, allSchemas) {
107
+ const result = new Map();
108
+ for (const [nodeId, entry] of Object.entries(document.nodes)) {
109
+ const rootName = entry.schema?.$ref ? schemaRefName(entry.schema.$ref) : undefined;
110
+ if (!rootName)
111
+ continue;
112
+ const component = componentFromNodeId(normalizeNodeId(nodeId));
113
+ const visited = new Set();
114
+ collectSchemaRefNames(rootName, allSchemas, visited);
115
+ for (const name of visited) {
116
+ const existing = result.get(name);
117
+ if (!existing)
118
+ result.set(name, component);
119
+ else if (existing !== component)
120
+ result.set(name, 'shared');
121
+ }
122
+ }
123
+ return result;
124
+ }
125
+ function getRootNodeIds(nodes) {
126
+ const nodeIds = Object.keys(nodes).map(normalizeNodeId);
127
+ return nodeIds
128
+ .filter(nodeId => !nodeIds.some(other => other !== nodeId && nodeId.startsWith(`${other}.`)))
129
+ .sort((a, b) => b.length - a.length);
130
+ }
131
+ function computeSchemaUsage(document, allSchemas, rootNodeIds) {
132
+ const usage = {
133
+ rootsBySchema: new Map(),
134
+ directEdgeSchemas: new Set(),
135
+ };
136
+ const schemaLinks = new Map();
137
+ for (const [nodeId, entry] of Object.entries(document.nodes)) {
138
+ const rootName = entry.schema?.$ref ? schemaRefName(entry.schema.$ref) : undefined;
139
+ if (!rootName)
140
+ continue;
141
+ const normalizedNodeId = normalizeNodeId(nodeId);
142
+ const visited = new Set();
143
+ collectSchemaRefNames(rootName, allSchemas, visited);
144
+ for (const name of visited)
145
+ addSchemaUsage(usage, name, normalizedNodeId);
146
+ }
147
+ for (const [schemaName, rawSchema] of Object.entries(allSchemas)) {
148
+ for (const refName of collectDirectSchemaRefs(rawSchema)) {
149
+ addSchemaLink(schemaLinks, schemaName, refName);
150
+ }
151
+ }
152
+ for (const edge of document.edges ?? []) {
153
+ const fromSchema = extractSchemaName(edge.from);
154
+ const toSchema = extractSchemaName(edge.to);
155
+ if (fromSchema && toSchema) {
156
+ usage.directEdgeSchemas.add(fromSchema);
157
+ usage.directEdgeSchemas.add(toSchema);
158
+ addSchemaLink(schemaLinks, fromSchema, toSchema);
159
+ continue;
160
+ }
161
+ if (fromSchema) {
162
+ usage.directEdgeSchemas.add(fromSchema);
163
+ const owner = resolveOwningRootNodeId(normalizeNodeId(edge.to), rootNodeIds);
164
+ if (owner)
165
+ addSchemaUsage(usage, fromSchema, owner);
166
+ }
167
+ if (toSchema) {
168
+ usage.directEdgeSchemas.add(toSchema);
169
+ const owner = resolveOwningRootNodeId(normalizeNodeId(edge.from), rootNodeIds);
170
+ if (owner)
171
+ addSchemaUsage(usage, toSchema, owner);
172
+ }
173
+ }
174
+ let changed = true;
175
+ while (changed) {
176
+ changed = false;
177
+ for (const [schemaName, linkedNames] of schemaLinks) {
178
+ const ownUsage = usage.rootsBySchema.get(schemaName);
179
+ if (!ownUsage)
180
+ continue;
181
+ for (const linkedName of linkedNames) {
182
+ const beforeSize = usage.rootsBySchema.get(linkedName)?.size ?? 0;
183
+ for (const rootNodeId of ownUsage)
184
+ addSchemaUsage(usage, linkedName, rootNodeId);
185
+ if ((usage.rootsBySchema.get(linkedName)?.size ?? 0) !== beforeSize)
186
+ changed = true;
187
+ }
188
+ }
189
+ }
190
+ return usage;
191
+ }
192
+ function collectSchemaRefNames(schemaName, allSchemas, visited) {
193
+ if (visited.has(schemaName))
194
+ return;
195
+ visited.add(schemaName);
196
+ const def = allSchemas[schemaName];
197
+ for (const prop of Object.values(def?.properties ?? {})) {
198
+ const p = prop;
199
+ const ref = typeof p.$ref === 'string' ? schemaRefName(p.$ref) : undefined;
200
+ if (ref)
201
+ collectSchemaRefNames(ref, allSchemas, visited);
202
+ if (p.type === 'array') {
203
+ const items = p.items;
204
+ const itemRef = items && typeof items.$ref === 'string' ? schemaRefName(items.$ref) : undefined;
205
+ if (itemRef)
206
+ collectSchemaRefNames(itemRef, allSchemas, visited);
207
+ }
208
+ }
209
+ }
210
+ function collectDirectSchemaRefs(value) {
211
+ const refs = new Set();
212
+ collectDirectSchemaRefsInto(value, refs);
213
+ return refs;
214
+ }
215
+ function collectDirectSchemaRefsInto(value, refs) {
216
+ if (!value || typeof value !== 'object')
217
+ return;
218
+ if (Array.isArray(value)) {
219
+ for (const item of value)
220
+ collectDirectSchemaRefsInto(item, refs);
221
+ return;
222
+ }
223
+ const record = value;
224
+ const refName = typeof record.$ref === 'string' ? schemaRefName(record.$ref) : undefined;
225
+ if (refName)
226
+ refs.add(refName);
227
+ collectDirectSchemaRefsInto(record.properties, refs);
228
+ collectDirectSchemaRefsInto(record.items, refs);
229
+ collectDirectSchemaRefsInto(record.additionalProperties, refs);
230
+ collectDirectSchemaRefsInto(record.allOf, refs);
231
+ collectDirectSchemaRefsInto(record.anyOf, refs);
232
+ collectDirectSchemaRefsInto(record.oneOf, refs);
233
+ }
234
+ function addSchemaUsage(usage, schemaName, rootNodeId) {
235
+ const roots = usage.rootsBySchema.get(schemaName) ?? new Set();
236
+ roots.add(rootNodeId);
237
+ usage.rootsBySchema.set(schemaName, roots);
238
+ }
239
+ function addSchemaLink(schemaLinks, from, to) {
240
+ if (from === to)
241
+ return;
242
+ const fromSet = schemaLinks.get(from) ?? new Set();
243
+ fromSet.add(to);
244
+ schemaLinks.set(from, fromSet);
245
+ }
246
+ function resolveOwningRootNodeId(nodeId, rootNodeIds) {
247
+ if (nodeId.startsWith('#/'))
248
+ return undefined;
249
+ return rootNodeIds.find(rootNodeId => nodeId === rootNodeId || nodeId.startsWith(`${rootNodeId}.`));
250
+ }
108
251
  function schemaRefName(ref) {
109
252
  const prefix = '#/components/schemas/';
110
253
  if (!ref.startsWith(prefix))
@@ -117,7 +260,82 @@ function extractSchemaName(endpoint) {
117
260
  return undefined;
118
261
  return endpoint.slice(prefix.length).split('/')[0];
119
262
  }
120
- function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId) {
263
+ function normalizeNodeId(nodeId) {
264
+ if (nodeId.startsWith('#/'))
265
+ return nodeId;
266
+ const parts = nodeId.split('.');
267
+ if (parts.length === 0)
268
+ return nodeId;
269
+ parts[0] = normalizeComponent(parts[0]);
270
+ return parts.join('.');
271
+ }
272
+ function componentFromNodeId(nodeId) {
273
+ return normalizeComponent(nodeId.split('.')[0] ?? '');
274
+ }
275
+ function normalizeComponent(component) {
276
+ return component === '_' || component.trim() === '' ? UNRESOLVED_COMPONENT : component;
277
+ }
278
+ function determineSchemaOwnership(schemaName, usage) {
279
+ const rootNodeIds = [...(usage.rootsBySchema.get(schemaName) ?? [])];
280
+ if (rootNodeIds.length === 0) {
281
+ return usage.directEdgeSchemas.has(schemaName) ? { kind: 'unresolved' } : { kind: 'unused' };
282
+ }
283
+ if (rootNodeIds.length === 1) {
284
+ return {
285
+ kind: 'inline',
286
+ rootNodeId: rootNodeIds[0],
287
+ component: componentFromNodeId(rootNodeIds[0]),
288
+ };
289
+ }
290
+ const components = new Set(rootNodeIds.map(componentFromNodeId));
291
+ return {
292
+ kind: 'shared',
293
+ component: components.size === 1 ? [...components][0] : 'shared',
294
+ };
295
+ }
296
+ function localSchemaName(schemaName) {
297
+ return schemaName.includes('.')
298
+ ? schemaName.slice(schemaName.lastIndexOf('.') + 1)
299
+ : schemaName;
300
+ }
301
+ function materializeStandaloneSchema(schemaName, component, allSchemas, nodes, edges, specPath, refToNodeId, schemaComponents) {
302
+ const schemaLocalName = localSchemaName(schemaName);
303
+ const schemaDef = allSchemas[schemaName];
304
+ const isEnumSchema = Array.isArray(schemaDef?.enum) && !schemaDef?.properties;
305
+ const template = isEnumSchema ? 'EnumDefinition' : 'Schema';
306
+ const schemaId = `${component}.${template}.${schemaLocalName}`;
307
+ const schemaRef = `#/components/schemas/${schemaName}`;
308
+ if (refToNodeId.has(schemaRef))
309
+ return refToNodeId.get(schemaRef);
310
+ refToNodeId.set(schemaRef, schemaId);
311
+ nodes.push(makeNode(template, component, specPath, schemaId, undefined, {}));
312
+ if (isEnumSchema) {
313
+ for (const value of schemaDef.enum) {
314
+ if (typeof value !== 'string')
315
+ continue;
316
+ const valueId = `${schemaId}.values.${value}`;
317
+ refToNodeId.set(`${schemaRef}/properties/${value}`, valueId);
318
+ nodes.push(makeNode('EnumValue', component, specPath, valueId, undefined, { value }));
319
+ edges.push(makeHasValueEdge(schemaId, valueId));
320
+ }
321
+ return schemaId;
322
+ }
323
+ const expanded = new Map([[schemaName, schemaId]]);
324
+ const localMappings = new Map();
325
+ for (const [fieldName, rawProp] of Object.entries(schemaDef?.properties ?? {})) {
326
+ const fieldId = `${schemaId}.fields.${fieldName}`;
327
+ const fieldRef = `${schemaRef}/properties/${fieldName}`;
328
+ if (!refToNodeId.has(fieldRef))
329
+ refToNodeId.set(fieldRef, fieldId);
330
+ const fieldNode = makeNode('Field', component, specPath, fieldId, undefined, {});
331
+ const required = Array.isArray(schemaDef?.required) && schemaDef.required.includes(fieldName);
332
+ fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, schemaId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
333
+ nodes.push(fieldNode);
334
+ edges.push(makeHasFieldEdge(schemaId, fieldId));
335
+ }
336
+ return schemaId;
337
+ }
338
+ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents = new Map()) {
121
339
  const existing = expanded.get(schemaName);
122
340
  if (existing)
123
341
  return existing;
@@ -125,17 +343,36 @@ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath
125
343
  // (e.g. "workers.ReactToPersonCreatedCommand"). Strip the prefix so the local segment
126
344
  // in the node ID is a simple identifier — graph serialization rejects local names
127
345
  // that contain dots because it uses dots as a hierarchy separator.
128
- const schemaLocalName = schemaName.includes('.')
129
- ? schemaName.slice(schemaName.lastIndexOf('.') + 1)
130
- : schemaName;
346
+ const schemaLocalName = localSchemaName(schemaName);
347
+ const schemaDef = allSchemas[schemaName];
348
+ const isEnumSchema = Array.isArray(schemaDef?.enum) && !schemaDef?.properties;
349
+ const schemaRef = `#/components/schemas/${schemaName}`;
350
+ if (isEnumSchema) {
351
+ // Enum schemas become standalone EnumDefinition cluster roots, matching the OpenAPI/AsyncAPI
352
+ // adapters. Using refToNodeId as shared dedup so only one node is created per mapDocument call
353
+ // even though `expanded` is scoped per parent node.
354
+ const enumComponent = schemaComponents.get(schemaName) ?? component;
355
+ const enumId = `${enumComponent}.EnumDefinition.${schemaLocalName}`;
356
+ expanded.set(schemaName, enumId);
357
+ if (!refToNodeId.has(schemaRef)) {
358
+ refToNodeId.set(schemaRef, enumId);
359
+ nodes.push(makeNode('EnumDefinition', enumComponent, specPath, enumId, undefined, {}));
360
+ for (const value of schemaDef.enum) {
361
+ if (typeof value !== 'string')
362
+ continue;
363
+ const valueId = `${enumId}.values.${value}`;
364
+ refToNodeId.set(`${schemaRef}/properties/${value}`, valueId);
365
+ nodes.push(makeNode('EnumValue', enumComponent, specPath, valueId, undefined, { value }));
366
+ edges.push(makeHasValueEdge(enumId, valueId));
367
+ }
368
+ }
369
+ return refToNodeId.get(schemaRef);
370
+ }
131
371
  const schemaId = `${rootNodeId}.schemas.${schemaLocalName}`;
132
372
  expanded.set(schemaName, schemaId);
133
- const schemaRef = `#/components/schemas/${schemaName}`;
134
373
  if (!refToNodeId.has(schemaRef))
135
374
  refToNodeId.set(schemaRef, schemaId);
136
- const schemaDef = allSchemas[schemaName];
137
- const schemaNode = makeNode('Schema', component, specPath, schemaId, undefined, {});
138
- nodes.push(schemaNode);
375
+ nodes.push(makeNode('Schema', component, specPath, schemaId, undefined, {}));
139
376
  edges.push(makeHasFieldEdge(rootNodeId, schemaId));
140
377
  const localMappings = new Map();
141
378
  for (const [fieldName, rawProp] of Object.entries(schemaDef?.properties ?? {})) {
@@ -145,32 +382,18 @@ function expandSchema(schemaName, rootNodeId, allSchemas, nodes, edges, specPath
145
382
  refToNodeId.set(fieldRef, fieldId);
146
383
  const fieldNode = makeNode('Field', component, specPath, fieldId, undefined, {});
147
384
  const required = Array.isArray(schemaDef?.required) && schemaDef.required.includes(fieldName);
148
- fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
385
+ fieldNode.properties = resolveFieldProperties(fieldName, rawProp, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
149
386
  nodes.push(fieldNode);
150
387
  edges.push(makeHasFieldEdge(schemaId, fieldId));
151
388
  }
152
- // Register enum values as field refs so edges referencing them (as /properties/{value}) can resolve
153
- if (Array.isArray(schemaDef?.enum)) {
154
- for (const value of schemaDef.enum) {
155
- if (typeof value !== 'string')
156
- continue;
157
- const fieldRef = `${schemaRef}/properties/${value}`;
158
- if (!refToNodeId.has(fieldRef)) {
159
- const fieldId = `${schemaId}.values.${value}`;
160
- refToNodeId.set(fieldRef, fieldId);
161
- nodes.push(makeNode('EnumValue', component, specPath, fieldId, undefined, { value }));
162
- edges.push(makeHasFieldEdge(schemaId, fieldId));
163
- }
164
- }
165
- }
166
389
  return schemaId;
167
390
  }
168
- function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId) {
391
+ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents) {
169
392
  const nullable = !required;
170
393
  if (typeof prop.$ref === 'string') {
171
394
  const refName = schemaRefName(prop.$ref);
172
395
  if (refName) {
173
- const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
396
+ const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
174
397
  return { $ref: refId, nullable, collection: 'one' };
175
398
  }
176
399
  return { type: 'string', nullable, collection: 'one' };
@@ -181,7 +404,7 @@ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId,
181
404
  if (items && typeof items.$ref === 'string') {
182
405
  const refName = schemaRefName(items.$ref);
183
406
  if (refName) {
184
- const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
407
+ const refId = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
185
408
  return { $ref: refId, nullable, collection: 'array' };
186
409
  }
187
410
  }
@@ -189,13 +412,13 @@ function resolveFieldProperties(fieldName, prop, required, schemaId, rootNodeId,
189
412
  return { type: itemType, nullable, collection: 'array' };
190
413
  }
191
414
  if (type === 'object' && prop.additionalProperties !== undefined) {
192
- createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
415
+ createMapping(fieldName, prop.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
193
416
  return { $ref: `#/mappings/${fieldName}`, nullable, collection: 'one' };
194
417
  }
195
418
  const scalarType = mapScalar(type ?? 'string', prop.format);
196
419
  return { type: scalarType, nullable, collection: 'one' };
197
420
  }
198
- function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId) {
421
+ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents) {
199
422
  const existing = localMappings.get(mappingName);
200
423
  if (existing)
201
424
  return existing;
@@ -211,7 +434,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
211
434
  if (typeof addl.$ref === 'string') {
212
435
  const refName = schemaRefName(addl.$ref);
213
436
  if (refName) {
214
- props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
437
+ props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
215
438
  }
216
439
  else {
217
440
  props.type = 'string';
@@ -223,7 +446,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
223
446
  if (items && typeof items.$ref === 'string') {
224
447
  const refName = schemaRefName(items.$ref);
225
448
  if (refName) {
226
- props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId);
449
+ props.$ref = expandSchema(refName, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, refToNodeId, schemaComponents);
227
450
  }
228
451
  else {
229
452
  props.type = 'string';
@@ -235,7 +458,7 @@ function createMapping(mappingName, addlDef, schemaId, rootNodeId, allSchemas, n
235
458
  }
236
459
  else if (addl.type === 'object' && addl.additionalProperties !== undefined) {
237
460
  const innerName = `${mappingName}-values`;
238
- props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId);
461
+ props.$ref = createMapping(innerName, addl.additionalProperties, schemaId, rootNodeId, allSchemas, nodes, edges, specPath, component, expanded, localMappings, refToNodeId, schemaComponents);
239
462
  }
240
463
  else {
241
464
  props.type = mapScalar(addl.type ?? 'string', addl.format);
@@ -290,6 +513,18 @@ function makeHasFieldEdge(from, to) {
290
513
  derivedBy: 'adapter:corum',
291
514
  };
292
515
  }
516
+ function makeHasValueEdge(from, to) {
517
+ return {
518
+ id: `${from}__has-value__${to}`,
519
+ from,
520
+ to,
521
+ type: 'has-value',
522
+ state: 'implemented',
523
+ stability: 'unstable',
524
+ derivation: 'determined',
525
+ derivedBy: 'adapter:corum',
526
+ };
527
+ }
293
528
  function mapEdge(raw) {
294
529
  return {
295
530
  id: `${raw.from}__${raw.type}__${raw.to}`,
@@ -50,6 +50,11 @@ export function getCluster(graph, nodeId) {
50
50
  }
51
51
  return { root, children, edges };
52
52
  }
53
+ // Shared data-type templates whose structural children (fields, values) and referenced types
54
+ // are included when expanding external node references into a cluster view.
55
+ // Operational templates (DomainEvent, Command, APIEndpoint, etc.) are excluded — callers get
56
+ // only their root metadata, not their internal schema trees.
57
+ const DATA_NODE_TEMPLATES = new Set(['Schema', 'EnumDefinition']);
53
58
  export function getClusterView(graph, nodeId, includeEdgeTypes = []) {
54
59
  const cluster = getCluster(graph, nodeId);
55
60
  if (includeEdgeTypes.length === 0) {
@@ -65,40 +70,93 @@ export function getClusterView(graph, nodeId, includeEdgeTypes = []) {
65
70
  // reads edges are directional (consumer → type); only follow outbound so viewing a shared
66
71
  // Schema doesn't pull in every endpoint that references it
67
72
  const inboundTypes = new Set([...requestedTypes].filter(t => t !== 'reads'));
68
- const includedNodeIds = new Set();
69
73
  const edges = [...cluster.edges];
70
74
  const seen = new Set(cluster.edges.map(edge => edge.id));
71
75
  for (const id of clusterIds) {
72
76
  for (const edge of graph.edgesByFrom.get(id) ?? []) {
73
- collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph);
77
+ if (!requestedTypes.has(edge.type) || seen.has(edge.id))
78
+ continue;
79
+ edges.push(edge);
80
+ seen.add(edge.id);
74
81
  }
75
82
  for (const edge of graph.edgesByTo.get(id) ?? []) {
76
- collectIncludedEdge(edge, inboundTypes, clusterIds, includedNodeIds, edges, seen, graph);
77
- }
78
- }
79
- // BFS over included nodes (outbound only) to transitively pull in referenced schemas
80
- const processedOutbound = new Set(clusterIds);
81
- let prevSize = 0;
82
- while (includedNodeIds.size > prevSize) {
83
- prevSize = includedNodeIds.size;
84
- for (const id of includedNodeIds) {
85
- if (processedOutbound.has(id))
83
+ if (!inboundTypes.has(edge.type) || seen.has(edge.id))
86
84
  continue;
87
- processedOutbound.add(id);
88
- for (const edge of graph.edgesByFrom.get(id) ?? []) {
89
- collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph);
90
- }
85
+ edges.push(edge);
86
+ seen.add(edge.id);
91
87
  }
92
88
  }
93
89
  return {
94
90
  root: cluster.root,
95
91
  descendants: cluster.children,
96
- includedNodes: [...includedNodeIds]
97
- .map(id => graph.nodesById.get(id))
98
- .filter((node) => node !== undefined),
92
+ // includedNodes is intentionally empty — callers compose this from the dangling edges
93
+ // using expandExternalNodes so each layer can apply its own inclusion policy.
94
+ includedNodes: [],
99
95
  edges,
100
96
  };
101
97
  }
98
+ /**
99
+ * Expands a set of external node IDs (typically from dangling semantic edges) into a flat
100
+ * list of nodes suitable for use as `includedNodes` in a cluster view response.
101
+ *
102
+ * Each ID is first resolved to its cluster root so that structural child IDs from
103
+ * edges like `maps-to` (which point to e.g. `Schema.X.fields.Y`) are collapsed to
104
+ * the owning cluster root (`Schema.X`) before processing.
105
+ *
106
+ * Policy:
107
+ * - Schema and EnumDefinition nodes: include structural children (fields/values) and
108
+ * follow their outbound `reads` edges one hop to collect referenced data types.
109
+ * - All other templates: include only the root node (metadata for connectivity panels).
110
+ */
111
+ export function expandExternalNodes(graph, externalIds) {
112
+ const result = new Set();
113
+ const dataQueue = [];
114
+ for (const rawId of externalIds) {
115
+ const immediateParent = findParent(graph, rawId);
116
+ if (immediateParent !== undefined) {
117
+ // rawId is a structural child (field/value targeted by maps-to).
118
+ // Include just this specific node — don't walk up and expand the entire parent tree.
119
+ if (!graph.nodesById.has(rawId) || result.has(rawId))
120
+ continue;
121
+ result.add(rawId);
122
+ continue;
123
+ }
124
+ // rawId has no structural parent — it's a root or standalone node (reads/calls/etc. target).
125
+ if (!graph.nodesById.has(rawId) || result.has(rawId))
126
+ continue;
127
+ result.add(rawId);
128
+ const node = graph.nodesById.get(rawId);
129
+ if (DATA_NODE_TEMPLATES.has(node.template))
130
+ dataQueue.push(rawId);
131
+ }
132
+ for (const id of dataQueue) {
133
+ // Include structural children (fields, values, mappings)
134
+ const prefix = `${id}.`;
135
+ for (const childId of graph.nodesById.keys()) {
136
+ if (childId.startsWith(prefix))
137
+ result.add(childId);
138
+ }
139
+ // Follow outbound reads one hop to collect referenced enum/schema types
140
+ for (const edge of graph.edgesByFrom.get(id) ?? []) {
141
+ if (edge.type !== 'reads' || result.has(edge.to))
142
+ continue;
143
+ const target = graph.nodesById.get(edge.to);
144
+ if (!target)
145
+ continue;
146
+ result.add(edge.to);
147
+ if (DATA_NODE_TEMPLATES.has(target.template)) {
148
+ const targetPrefix = `${edge.to}.`;
149
+ for (const childId of graph.nodesById.keys()) {
150
+ if (childId.startsWith(targetPrefix))
151
+ result.add(childId);
152
+ }
153
+ }
154
+ }
155
+ }
156
+ return [...result]
157
+ .map(id => graph.nodesById.get(id))
158
+ .filter((node) => node !== undefined);
159
+ }
102
160
  export function getLinkedFields(graph, nodeId) {
103
161
  const root = graph.nodesById.get(nodeId);
104
162
  if (!root)
@@ -144,22 +202,6 @@ function collectMapsTo(edge, edges, nodeIds, seen) {
144
202
  nodeIds.add(edge.to);
145
203
  seen.add(edge.id);
146
204
  }
147
- function collectIncludedEdge(edge, requestedTypes, clusterIds, includedNodeIds, edges, seen, graph) {
148
- if (!requestedTypes.has(edge.type) || seen.has(edge.id))
149
- return;
150
- edges.push(edge);
151
- seen.add(edge.id);
152
- for (const endId of [edge.from, edge.to]) {
153
- if (clusterIds.has(endId))
154
- continue;
155
- includedNodeIds.add(endId);
156
- const prefix = `${endId}.`;
157
- for (const id of graph.nodesById.keys()) {
158
- if (id.startsWith(prefix))
159
- includedNodeIds.add(id);
160
- }
161
- }
162
- }
163
205
  const OVERLAY_EXCLUDED = new Set(['local', 'shared']);
164
206
  export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRootId) {
165
207
  const overlay = multi.overlay(viewingRef);
@@ -0,0 +1,188 @@
1
+ import { STRUCTURAL_EDGE_TYPES, STRUCTURAL_NODE_TEMPLATES } from './index.js';
2
+ const FIELD_EDGE_TYPES = new Set(['maps-to', 'derived-from']);
3
+ export function collapseClusterSchemas(graph, cluster) {
4
+ const rootId = cluster.root.id;
5
+ const rootPrefix = `${rootId}.`;
6
+ // Indexes keyed by local name or parent ID
7
+ const schemaChildIds = new Set();
8
+ const schemaNames = new Map(); // localName → exists
9
+ const enumNames = new Map(); // localName → exists
10
+ const fieldsByParentId = new Map(); // parentId → fieldName → Node
11
+ const valuesByEnumId = new Map(); // enumId → value names
12
+ const valuesBySchemaId = new Map(); // schemaId → value names (enum-like schemas)
13
+ const mappingsByParentId = new Map(); // parentSchemaId → mapName → Node
14
+ const semanticDescendants = [];
15
+ for (const n of cluster.descendants) {
16
+ if (!n.id.startsWith(rootPrefix)) {
17
+ semanticDescendants.push(n);
18
+ continue;
19
+ }
20
+ const suffix = n.id.slice(rootPrefix.length);
21
+ if (n.template === 'Schema') {
22
+ const m = /^schemas\.([^.]+)$/.exec(suffix);
23
+ if (m) {
24
+ schemaNames.set(m[1], true);
25
+ schemaChildIds.add(n.id);
26
+ continue;
27
+ }
28
+ }
29
+ if (n.template === 'EnumDefinition') {
30
+ const m = /^enums\.([^.]+)$/.exec(suffix);
31
+ if (m) {
32
+ enumNames.set(m[1], true);
33
+ schemaChildIds.add(n.id);
34
+ continue;
35
+ }
36
+ }
37
+ if (n.template === 'Field') {
38
+ const m = /^(.+)\.fields\.([^.]+)$/.exec(suffix);
39
+ if (m) {
40
+ const parentId = `${rootId}.${m[1]}`;
41
+ const existing = fieldsByParentId.get(parentId) ?? new Map();
42
+ existing.set(m[2], n);
43
+ fieldsByParentId.set(parentId, existing);
44
+ schemaChildIds.add(n.id);
45
+ continue;
46
+ }
47
+ }
48
+ if (n.template === 'EnumValue') {
49
+ const enumM = /^enums\.([^.]+)\.values\.([^.]+)$/.exec(suffix);
50
+ if (enumM) {
51
+ const enumId = `${rootId}.enums.${enumM[1]}`;
52
+ const values = valuesByEnumId.get(enumId) ?? [];
53
+ values.push(typeof n.properties.name === 'string' ? n.properties.name : enumM[2]);
54
+ valuesByEnumId.set(enumId, values);
55
+ schemaChildIds.add(n.id);
56
+ continue;
57
+ }
58
+ // Also handle EnumValue nodes under schemas section (enum-like schemas)
59
+ const schemaM = /^schemas\.([^.]+)\.values\.([^.]+)$/.exec(suffix);
60
+ if (schemaM) {
61
+ const schemaId = `${rootId}.schemas.${schemaM[1]}`;
62
+ const values = valuesBySchemaId.get(schemaId) ?? [];
63
+ values.push(typeof n.properties.name === 'string' ? n.properties.name : schemaM[2]);
64
+ valuesBySchemaId.set(schemaId, values);
65
+ schemaChildIds.add(n.id);
66
+ continue;
67
+ }
68
+ }
69
+ if (n.template === 'Mapping') {
70
+ const m = /^schemas\.([^.]+)\.mappings\.([^.]+)$/.exec(suffix);
71
+ if (m) {
72
+ const parentId = `${rootId}.schemas.${m[1]}`;
73
+ const existing = mappingsByParentId.get(parentId) ?? new Map();
74
+ existing.set(m[2], n);
75
+ mappingsByParentId.set(parentId, existing);
76
+ schemaChildIds.add(n.id);
77
+ continue;
78
+ }
79
+ }
80
+ semanticDescendants.push(n);
81
+ }
82
+ // Build schemas output
83
+ const schemas = {};
84
+ const schemaEnums = {};
85
+ for (const localName of schemaNames.keys()) {
86
+ const schemaId = `${rootId}.schemas.${localName}`;
87
+ const fields = fieldsByParentId.get(schemaId) ?? new Map();
88
+ // Enum-like schema: has EnumValue children but no Field children
89
+ const schemaValues = valuesBySchemaId.get(schemaId);
90
+ if (schemaValues && fields.size === 0) {
91
+ schemaEnums[localName] = { values: schemaValues };
92
+ continue;
93
+ }
94
+ const mappings = mappingsByParentId.get(schemaId) ?? new Map();
95
+ const entry = {};
96
+ for (const [fieldName, fieldNode] of fields) {
97
+ entry[fieldName] = buildField(fieldNode, graph, rootId, mappings);
98
+ }
99
+ schemas[localName] = entry;
100
+ }
101
+ // Build enums output
102
+ const enums = {};
103
+ for (const localName of enumNames.keys()) {
104
+ const enumId = `${rootId}.enums.${localName}`;
105
+ enums[localName] = { values: valuesByEnumId.get(enumId) ?? [] };
106
+ }
107
+ // Filter edges: drop structural edge types and any edge originating from a schema child
108
+ const filteredEdges = cluster.edges.filter(e => !STRUCTURAL_EDGE_TYPES.has(e.type) && !schemaChildIds.has(e.from));
109
+ // Filter includedNodes: drop structural template nodes
110
+ const filteredIncludedNodes = cluster.includedNodes.filter(n => !STRUCTURAL_NODE_TEMPLATES.has(n.template));
111
+ return {
112
+ root: cluster.root,
113
+ schemas,
114
+ schemaEnums,
115
+ enums,
116
+ descendants: semanticDescendants,
117
+ edges: filteredEdges,
118
+ includedNodes: filteredIncludedNodes,
119
+ };
120
+ }
121
+ function buildField(fieldNode, graph, rootId, parentMappings) {
122
+ const props = fieldNode.properties;
123
+ const isArray = props.collection === 'array';
124
+ const isNullable = props.nullable === true;
125
+ let field = {};
126
+ const ref = typeof props.$ref === 'string' ? props.$ref : undefined;
127
+ if (ref?.startsWith('#/mappings/')) {
128
+ const mapName = ref.slice('#/mappings/'.length);
129
+ const mapNode = parentMappings.get(mapName);
130
+ if (mapNode) {
131
+ field = buildMappingField(mapNode, graph);
132
+ }
133
+ else {
134
+ field = { $ref: ref };
135
+ }
136
+ }
137
+ else if (ref) {
138
+ field = { $ref: ref };
139
+ if (isArray)
140
+ field.collection = 'array';
141
+ }
142
+ else if (typeof props.type === 'string') {
143
+ field = { type: props.type };
144
+ if (isArray)
145
+ field.collection = 'array';
146
+ }
147
+ if (isNullable)
148
+ field.nullable = true;
149
+ // Gather outbound field edges that cross the cluster boundary
150
+ const clusterPrefix = `${rootId}.`;
151
+ const fieldEdges = {};
152
+ for (const e of graph.edgesByFrom.get(fieldNode.id) ?? []) {
153
+ if (!FIELD_EDGE_TYPES.has(e.type))
154
+ continue;
155
+ if (e.to.startsWith(clusterPrefix))
156
+ continue;
157
+ const targets = fieldEdges[e.type] ?? [];
158
+ targets.push(e.to);
159
+ fieldEdges[e.type] = targets;
160
+ }
161
+ if (Object.keys(fieldEdges).length > 0)
162
+ field.edges = fieldEdges;
163
+ return field;
164
+ }
165
+ function buildMappingField(mapNode, graph) {
166
+ const props = mapNode.properties;
167
+ const key = typeof props['key-type'] === 'string' ? props['key-type'] : 'string';
168
+ const isArrayValue = props['value-collection'] === 'array';
169
+ let valueField = {};
170
+ if (typeof props.type === 'string') {
171
+ valueField = { type: props.type };
172
+ }
173
+ else if (typeof props.$ref === 'string') {
174
+ const ref = props.$ref;
175
+ const refNode = graph.nodesById.get(ref);
176
+ if (refNode?.template === 'Mapping') {
177
+ // Nested mapping — recurse once (no further recursion guard needed for realistic depths)
178
+ valueField = buildMappingField(refNode, graph);
179
+ }
180
+ else {
181
+ valueField = { $ref: ref };
182
+ }
183
+ }
184
+ const value = isArrayValue
185
+ ? { type: 'array', items: valueField }
186
+ : valueField;
187
+ return { type: 'map', key, value };
188
+ }
@@ -3,12 +3,13 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
3
3
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
4
  import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
5
5
  import { pathToFileURL } from 'node:url';
6
- import { computeClusterOverlay, getClusterView, getGraphSummary, getLineage, getLinkedFields, listNodes, SEMANTIC_EDGE_TYPES, searchNodes, STRUCTURAL_NODE_TEMPLATES, } from '../graph/index.js';
6
+ import { computeClusterOverlay, expandExternalNodes, 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
11
  import { USAGE_GUIDE_PROMPT } from './prompts/usage-guide.js';
12
+ import { collapseClusterSchemas } from '../graph/schema-collapse.js';
12
13
  import { compactKeys, getSerializer } from './serializers.js';
13
14
  const EDGE_TYPES = [
14
15
  'triggers',
@@ -88,18 +89,16 @@ function fullNode(node, includeProvenance) {
88
89
  ...(includeProvenance ? withProvenance(node) : {}),
89
90
  };
90
91
  }
91
- function mapEdge(edge, includeProvenance) {
92
- const out = {
93
- id: edge.id,
94
- from: edge.from,
95
- to: edge.to,
96
- type: edge.type,
97
- state: edge.state,
98
- stability: edge.stability,
99
- };
92
+ function mapEdge(edge, options = {}) {
93
+ const out = {};
94
+ if (options.includeId)
95
+ out.id = edge.id;
96
+ out.from = edge.from;
97
+ out.to = edge.to;
98
+ out.type = edge.type;
100
99
  if (edge.notes !== undefined)
101
100
  out.notes = edge.notes;
102
- if (includeProvenance) {
101
+ if (options.includeProvenance) {
103
102
  if (edge.derivation !== undefined)
104
103
  out.derivation = edge.derivation;
105
104
  if (edge.derivedBy !== undefined)
@@ -107,6 +106,12 @@ function mapEdge(edge, includeProvenance) {
107
106
  }
108
107
  return out;
109
108
  }
109
+ function getEdgeOutputOptions(args) {
110
+ return {
111
+ includeProvenance: includesProvenance(args),
112
+ includeId: args.include_edge_ids === true,
113
+ };
114
+ }
110
115
  function mapLineageNode(node, includeProvenance, lean) {
111
116
  const base = {
112
117
  id: String(node.id),
@@ -244,14 +249,71 @@ export function createMcpHandlers(graph, source, cache) {
244
249
  const run = async (targetGraph, branchRef) => {
245
250
  const edgeTypes = parseEdgeTypes(args.edge_types)
246
251
  ?? [...SEMANTIC_EDGE_TYPES];
247
- const cluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
252
+ const rawCluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
253
+ const clusterIds = new Set([rawCluster.root.id, ...rawCluster.descendants.map(n => n.id)]);
254
+ const externalIds = new Set();
255
+ for (const edge of rawCluster.edges) {
256
+ if (!clusterIds.has(edge.from))
257
+ externalIds.add(edge.from);
258
+ if (!clusterIds.has(edge.to))
259
+ externalIds.add(edge.to);
260
+ }
261
+ const cluster = { ...rawCluster, includedNodes: expandExternalNodes(targetGraph, externalIds) };
248
262
  const includeProvenance = includesProvenance(args);
249
- const clusterPayload = {
250
- root: fullNode(cluster.root, includeProvenance),
251
- descendants: cluster.descendants.map(node => fullNode(node, includeProvenance)),
252
- includedNodes: cluster.includedNodes.map(node => fullNode(node, includeProvenance)),
253
- edges: cluster.edges.map(e => mapEdge(e, includeProvenance)),
254
- };
263
+ const collapseSchemas = args.collapse_schemas !== false;
264
+ const includeEdges = args.include_edges === true;
265
+ const includeDescendants = args.include_descendants !== false;
266
+ const nodeTypes = toStringArray(args.node_types);
267
+ const edgeOptions = getEdgeOutputOptions(args);
268
+ let clusterPayload;
269
+ if (collapseSchemas) {
270
+ const collapsed = collapseClusterSchemas(targetGraph, cluster);
271
+ let filteredDescendants = collapsed.descendants;
272
+ let filteredIncludedNodes = collapsed.includedNodes;
273
+ if (!includeDescendants) {
274
+ filteredDescendants = [];
275
+ filteredIncludedNodes = [];
276
+ }
277
+ else if (nodeTypes) {
278
+ const typeSet = new Set(nodeTypes);
279
+ filteredDescendants = filteredDescendants.filter(n => typeSet.has(n.template));
280
+ filteredIncludedNodes = filteredIncludedNodes.filter(n => typeSet.has(n.template));
281
+ }
282
+ const mergedSchemas = { ...collapsed.schemas, ...collapsed.schemaEnums };
283
+ clusterPayload = {
284
+ root: {
285
+ ...fullNode(collapsed.root, includeProvenance),
286
+ ...(Object.keys(mergedSchemas).length > 0 ? { schemas: mergedSchemas } : {}),
287
+ ...(Object.keys(collapsed.enums).length > 0 ? { enums: collapsed.enums } : {}),
288
+ },
289
+ ...(includeDescendants ? {
290
+ descendants: filteredDescendants.map(node => fullNode(node, includeProvenance)),
291
+ includedNodes: filteredIncludedNodes.map(node => fullNode(node, includeProvenance)),
292
+ } : {}),
293
+ ...(includeEdges ? { edges: collapsed.edges.map(e => mapEdge(e, edgeOptions)) } : {}),
294
+ };
295
+ }
296
+ else {
297
+ let filteredDescendants = cluster.descendants;
298
+ let filteredIncludedNodes = cluster.includedNodes;
299
+ if (!includeDescendants) {
300
+ filteredDescendants = [];
301
+ filteredIncludedNodes = [];
302
+ }
303
+ else if (nodeTypes) {
304
+ const typeSet = new Set(nodeTypes);
305
+ filteredDescendants = filteredDescendants.filter(n => typeSet.has(n.template));
306
+ filteredIncludedNodes = filteredIncludedNodes.filter(n => typeSet.has(n.template));
307
+ }
308
+ clusterPayload = {
309
+ root: fullNode(cluster.root, includeProvenance),
310
+ ...(includeDescendants ? {
311
+ descendants: filteredDescendants.map(node => fullNode(node, includeProvenance)),
312
+ includedNodes: filteredIncludedNodes.map(node => fullNode(node, includeProvenance)),
313
+ } : {}),
314
+ ...(includeEdges ? { edges: cluster.edges.map(e => mapEdge(e, edgeOptions)) } : {}),
315
+ };
316
+ }
255
317
  if (overlayRefs.length === 0 || !source || !branchRef) {
256
318
  return formatResult(clusterPayload, args.format, getCompactKeys(args));
257
319
  }
@@ -355,11 +417,12 @@ export function createMcpHandlers(graph, source, cache) {
355
417
  const lean = args.lean !== false;
356
418
  const includeEdges = args.include_edges === true;
357
419
  const includeProvenance = includesProvenance(args);
420
+ const edgeOptions = getEdgeOutputOptions(args);
358
421
  const payload = {
359
422
  nodes: lineage.nodes.map(node => mapLineageNode(node, includeProvenance, lean)),
360
423
  };
361
424
  if (includeEdges)
362
- payload.edges = lineage.edges.map(e => mapEdge(e, includeProvenance));
425
+ payload.edges = lineage.edges.map(e => mapEdge(e, edgeOptions));
363
426
  if (args.include_dangling_edges === true && lineage.dangling_edges)
364
427
  payload.dangling_edges = lineage.dangling_edges;
365
428
  return formatResult(payload, args.format, getCompactKeys(args));
@@ -378,8 +441,9 @@ export function createMcpHandlers(graph, source, cache) {
378
441
  const run = (targetGraph) => {
379
442
  const linked = getLinkedFields(targetGraph, String(args.node_id));
380
443
  const incProv = includesProvenance(args);
444
+ const edgeOptions = getEdgeOutputOptions(args);
381
445
  return formatResult({
382
- edges: linked.edges.map(e => mapEdge(e, incProv)),
446
+ edges: linked.edges.map(e => mapEdge(e, edgeOptions)),
383
447
  nodes: linked.nodes.map(node => fullNode(node, incProv)),
384
448
  }, args.format, getCompactKeys(args));
385
449
  };
@@ -521,7 +585,7 @@ export function getMcpToolDefinitions() {
521
585
  },
522
586
  {
523
587
  name: 'get_cluster',
524
- description: 'Use when you need the full structural contents of a single node - its schema, fields, and owned children. Not suited for following relationships across the graph; use get_lineage for that. Note: large aggregates may exceed response size limits.',
588
+ description: 'Use when you need the full structural contents of a single node - its schema, fields, and owned children. Not suited for following relationships across the graph; use get_lineage for that.\n\nBy default returns only the root node with its collapsed schema and enums blocks (descendants and edges excluded). Pass include_descendants: true to include owned operations/commands/events. Pass include_edges: true to include the edge list.',
525
589
  inputSchema: {
526
590
  type: 'object',
527
591
  required: ['node_id'],
@@ -532,8 +596,15 @@ export function getMcpToolDefinitions() {
532
596
  items: { type: 'string' },
533
597
  description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
534
598
  },
535
- include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
536
- reads_outbound_only: { type: 'boolean', description: 'Restrict reads edges to outbound only. Default true.' },
599
+ collapse_schemas: { type: 'boolean', description: 'Collapse schema/enum child nodes into compact schemas and enums blocks on the root. Structural edges and schema child nodes are removed from descendants. Default true.' },
600
+ include_descendants: { type: 'boolean', description: 'Include descendant nodes (operations, commands, events, and cross-component nodes). Default true.' },
601
+ node_types: {
602
+ type: 'array',
603
+ items: { type: 'string' },
604
+ description: 'Allowlist of node templates to include in the descendant set. Useful for limiting to specific types (e.g. ["DomainOperation", "DomainEvent"]).',
605
+ },
606
+ include_edges: { type: 'boolean', description: 'Include the edge list in the response. Default false.' },
607
+ include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
537
608
  include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
538
609
  branch: { type: 'string', description: 'Branch ref to load the cluster from' },
539
610
  overlay_refs: {
@@ -604,6 +675,7 @@ export function getMcpToolDefinitions() {
604
675
  reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
605
676
  lean: { type: 'boolean', description: 'Return minimal lineage node shape. Default true.' },
606
677
  include_edges: { type: 'boolean', description: 'Include the edges list in the response. Default false.' },
678
+ include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
607
679
  include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
608
680
  branch: { type: 'string', description: 'Branch ref to load the lineage from' },
609
681
  format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
@@ -619,6 +691,7 @@ export function getMcpToolDefinitions() {
619
691
  required: ['node_id'],
620
692
  properties: {
621
693
  node_id: { type: 'string', description: 'Fully qualified root node ID' },
694
+ include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
622
695
  include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
623
696
  branch: { type: 'string', description: 'Branch ref to load linked fields from' },
624
697
  format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
@@ -43,7 +43,7 @@ When likely relationships are absent, treat naming, shared component context, sc
43
43
 
44
44
  5. Use direction "upstream" from a DomainModel node to find all writers to that aggregate.
45
45
 
46
- 6. Avoid get_cluster for traversal questions - use it only when you need a node's full structural detail (schema, fields). Prefer get_lineage for following relationships.
46
+ 6. Avoid get_cluster for traversal questions - use it only when you need a node's full structural detail. Prefer get_lineage for following relationships.
47
47
 
48
48
  7. Add include_provenance: true only when you need to bridge a finding to the source codebase.
49
49
 
@@ -84,5 +84,10 @@ Field-level mappings between nodes:
84
84
  get_linked_fields - returns all maps-to edges touching fields owned by a root node
85
85
 
86
86
  Schema / field details:
87
- get_cluster - descendants include owned schemas, fields, and enum values
87
+ get_cluster - root includes compact schemas and enums blocks by default. Each schema entry
88
+ is a map of field name to { type?, $ref?, collection?, nullable?, edges? }. Local references
89
+ use $ref: '#/schemas/name' or $ref: '#/enums/name' pointing into the same blocks. Mapping
90
+ fields appear as { type: map, key: string, value: { ... } } inline on the field. Field-level
91
+ cross-cluster edges (maps-to, derived-from) appear as an edges block on the field. Pass
92
+ collapse_schemas: false to get the full structural node-per-field representation instead.
88
93
  `.trim();
@@ -5,7 +5,7 @@ import { existsSync, readFileSync, readdirSync, watch } from 'node:fs';
5
5
  import { readdir } from 'node:fs/promises';
6
6
  import { fileURLToPath, pathToFileURL } from 'node:url';
7
7
  import { parse as parseYaml } from 'yaml';
8
- import { computeClusterOverlay, getClusterView, getGraphSummary, getLineage, listNodes, searchNodes, } from '../graph/index.js';
8
+ import { computeClusterOverlay, getClusterView, getGraphSummary, expandExternalNodes, getLineage, listNodes, searchNodes, } from '../graph/index.js';
9
9
  import { loadGraph, loadMultiGraph } from '../loader/index.js';
10
10
  import { VALID_EDGE_TYPE_SET } from '../loader/constants.js';
11
11
  import { getOwnedSections } from '../loader/pack-loader.js';
@@ -514,10 +514,22 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
514
514
  const multi = await multiCache.get();
515
515
  overlay = computeClusterOverlay(multi, req.query.ref, overlayRefs, nodeId);
516
516
  }
517
+ // Compute included nodes from dangling semantic edges: data-type nodes (Schema,
518
+ // EnumDefinition) are expanded with structural children; operational nodes get
519
+ // root metadata only (for connectivity panels).
520
+ const clusterIds = new Set([cluster.root.id, ...cluster.descendants.map(n => n.id)]);
521
+ const externalIds = new Set();
522
+ for (const edge of cluster.edges) {
523
+ if (!clusterIds.has(edge.from))
524
+ externalIds.add(edge.from);
525
+ if (!clusterIds.has(edge.to))
526
+ externalIds.add(edge.to);
527
+ }
528
+ const includedNodes = expandExternalNodes(targetGraph, externalIds);
517
529
  res.json({
518
530
  root: summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, cluster.root)),
519
531
  descendants: cluster.descendants.map(child => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, child))),
520
- includedNodes: cluster.includedNodes.map(node => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, node))),
532
+ includedNodes: includedNodes.map(node => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, node))),
521
533
  edges: cluster.edges,
522
534
  overlay,
523
535
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.37",
3
+ "version": "0.1.39",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
package/web/app.jsx CHANGED
@@ -843,8 +843,12 @@ function NodePage({ nodeId, templates, onNavigate, refreshToken, viewingRef, ove
843
843
  const childDisplayEntries = [...displayChildren.entries()]
844
844
  .filter(([templateName]) => templateName !== 'Field' && templateName !== 'EnumValue' && templateName !== 'Mapping');
845
845
  const displayEntries = [...rootSpecializedNodes, ...childDisplayEntries];
846
- const includedSchemaNodes = includedNodes.filter(n => n.template === 'Schema');
847
- const includedEnumNodes = includedNodes.filter(n => n.template === 'EnumDefinition');
846
+ // includedNodes now contains only directly-connected external nodes:
847
+ // - Schema / EnumDefinition: with structural children (fields/values) and referenced types
848
+ // - All other templates (DomainEvent, Command, etc.): root metadata only for connectivity panel
849
+ // This is computed server-side via expandExternalNodes, so no client-side filtering is needed.
850
+ const includedSchemaNodes = includedNodes.filter(n => n.template === 'Schema' && !n.parentId);
851
+ const includedEnumNodes = includedNodes.filter(n => n.template === 'EnumDefinition' && !n.parentId);
848
852
 
849
853
  function handlePropertyNavigate(targetNodeId) {
850
854
  if (displayedNodeIds.has(targetNodeId)) {
@@ -472,7 +472,8 @@ function SchemaFieldRows({ schemaNodeId, model, prefix = '', depth = 0, visited
472
472
  const childSchemaNode = !canExpandMapping
473
473
  ? (refNodeId ? (model.schemasById?.get(refNodeId) ?? null) : (localRef ? (model.schemasByName.get(localRef) ?? null) : null))
474
474
  : null;
475
- const canExpand = !!childSchemaNode && !visited.has(childSchemaNode.id);
475
+ const childHasFields = childSchemaNode ? (model.fieldsBySchema.get(childSchemaNode.id) ?? []).length > 0 : false;
476
+ const canExpand = !!childSchemaNode && !visited.has(childSchemaNode.id) && childHasFields;
476
477
  const isExpandable = canExpand || canExpandMapping;
477
478
  const childGhostFields = childSchemaNode ? overlayFieldsForSchema(overlayFields, childSchemaNode.id) : [];
478
479
  const c = field.properties?.collection;