@atolis-hq/corum 0.1.61 → 0.1.63

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.
@@ -404,7 +404,7 @@ function makeNode(template, component, specPath, id, parentId) {
404
404
  id,
405
405
  ...(parentId !== undefined && { parentId }),
406
406
  template,
407
- component,
407
+ namespace: component,
408
408
  state: 'implemented',
409
409
  stability: 'unstable',
410
410
  schemaVersion: '1',
@@ -557,7 +557,7 @@ function makeNode(template, component, specPath, id, provenance, properties, par
557
557
  id,
558
558
  ...(parentId !== undefined && { parentId }),
559
559
  template,
560
- component,
560
+ namespace: component,
561
561
  state: 'implemented',
562
562
  stability: 'unstable',
563
563
  schemaVersion: '1',
@@ -314,7 +314,7 @@ function makeNode(template, component, specPath, id, parentId) {
314
314
  id,
315
315
  ...(parentId !== undefined && { parentId }),
316
316
  template,
317
- component,
317
+ namespace: component,
318
318
  state: 'implemented',
319
319
  stability: 'unstable',
320
320
  schemaVersion: '1',
@@ -1,4 +1,5 @@
1
1
  #!/usr/bin/env node
2
+ import { NODE_ROOT_DIR } from '../source/graph-paths.js';
2
3
  import { Command } from 'commander';
3
4
  import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
4
5
  import { readFile as fsReadFile } from 'node:fs/promises';
@@ -146,7 +147,7 @@ program
146
147
  else {
147
148
  mkdirSync(path.dirname(graphPath), { recursive: true });
148
149
  writeFileSync(graphPath, GRAPH_TEMPLATE);
149
- mkdirSync(path.join(corumDir, 'graph', 'components'), { recursive: true });
150
+ mkdirSync(path.join(corumDir, 'graph', NODE_ROOT_DIR), { recursive: true });
150
151
  mkdirSync(path.join(corumDir, 'graph', 'edges'), { recursive: true });
151
152
  process.stdout.write('Created .corum/graph/graph.yaml\n');
152
153
  }
@@ -45,12 +45,15 @@ export function getVisibleEdgeTypes(graph) {
45
45
  .map(def => def.name);
46
46
  }
47
47
  export function listNodes(graph, filter = {}) {
48
+ const namespaces = filter.kind !== undefined ? getNamespaces(graph) : undefined;
48
49
  return [...graph.nodesById.values()].filter(node => {
49
50
  if (filter.templates?.length && !filter.templates.includes(node.template))
50
51
  return false;
51
52
  if (filter.excludeTemplates?.length && filter.excludeTemplates.includes(node.template))
52
53
  return false;
53
- if (filter.component !== undefined && node.component !== filter.component)
54
+ if (filter.namespace !== undefined && node.namespace !== filter.namespace)
55
+ return false;
56
+ if (namespaces !== undefined && namespaces.get(node.namespace)?.kind !== filter.kind)
54
57
  return false;
55
58
  if (filter.state !== undefined) {
56
59
  const states = Array.isArray(filter.state) ? filter.state : [filter.state];
@@ -278,20 +281,23 @@ export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRoo
278
281
  return fields.length === 0 ? null : { viewingRef, overlayRefs, fields };
279
282
  }
280
283
  export function getGraphSummary(graph) {
281
- const components = new Set();
282
- const nodesByComponent = {};
284
+ const nodesByNamespace = {};
283
285
  const nodesByTemplate = {};
284
286
  const nodesByState = {};
285
287
  const nodesByStability = {};
286
288
  for (const node of graph.nodesById.values()) {
287
- if (node.component) {
288
- components.add(node.component);
289
- nodesByComponent[node.component] = (nodesByComponent[node.component] ?? 0) + 1;
289
+ if (node.namespace) {
290
+ nodesByNamespace[node.namespace] = (nodesByNamespace[node.namespace] ?? 0) + 1;
290
291
  }
291
292
  nodesByTemplate[node.template] = (nodesByTemplate[node.template] ?? 0) + 1;
292
293
  nodesByState[node.state] = (nodesByState[node.state] ?? 0) + 1;
293
294
  nodesByStability[node.stability] = (nodesByStability[node.stability] ?? 0) + 1;
294
295
  }
296
+ const namespaces = getNamespaces(graph);
297
+ const namespacesByKind = {};
298
+ for (const ns of namespaces.values()) {
299
+ namespacesByKind[ns.kind] = (namespacesByKind[ns.kind] ?? 0) + 1;
300
+ }
295
301
  const nodesWithEdges = new Set();
296
302
  const edgesByType = {};
297
303
  for (const edgeList of graph.edgesByFrom.values()) {
@@ -313,8 +319,9 @@ export function getGraphSummary(graph) {
313
319
  }
314
320
  return {
315
321
  nodeCount: graph.nodesById.size,
316
- componentCount: components.size,
317
- nodesByComponent,
322
+ namespaceCount: namespaces.size,
323
+ namespacesByKind,
324
+ nodesByNamespace,
318
325
  nodesByTemplate,
319
326
  nodesByState,
320
327
  nodesByStability,
@@ -563,3 +570,27 @@ export function getLineage(graph, startNodeIds, options = {}) {
563
570
  result.dangling_edges = danglingEdges;
564
571
  return result;
565
572
  }
573
+ /** Display label for a kind; unknown kinds fall back to the kind id. */
574
+ export function getKindLabel(graph, kind) {
575
+ return graph.kinds?.get(kind)?.label ?? (kind === 'component' ? 'Component' : kind);
576
+ }
577
+ /** Kind registry (id, label); always includes the default component kind. */
578
+ export function getKindRegistry(graph) {
579
+ const registry = new Map();
580
+ registry.set('component', { id: 'component', label: getKindLabel(graph, 'component') });
581
+ for (const kind of graph.kinds?.values() ?? []) {
582
+ registry.set(kind.id, { id: kind.id, label: getKindLabel(graph, kind.id) });
583
+ }
584
+ return [...registry.values()];
585
+ }
586
+ /** Derive membership from current nodes, retaining declarations for empty namespaces. */
587
+ export function getNamespaces(graph) {
588
+ const namespaces = new Map();
589
+ for (const id of graph.nodesById.keys()) {
590
+ namespaces.set(id.split('.')[0], { kind: 'component' });
591
+ }
592
+ for (const [name, declaration] of graph.namespaceDeclarations ?? []) {
593
+ namespaces.set(name, { ...declaration });
594
+ }
595
+ return namespaces;
596
+ }
@@ -1,3 +1,5 @@
1
+ import { NODE_ROOT_DIR } from '../source/graph-paths.js';
2
+ import { getNamespaces } from '../graph/index.js';
1
3
  import { getEdgeTypeConstraints } from '../graph/roles.js';
2
4
  import { CORE_EDGE_TYPE_MAP } from '../loader/constants.js';
3
5
  import { validateNodeId } from '../loader/id-grammar.js';
@@ -40,6 +42,7 @@ export function lintGraph(graph) {
40
42
  lintEdgeProperties(graph, diagnostics);
41
43
  lintHiddenEdgeLiveEnds(graph, diagnostics);
42
44
  lintInlineStandaloneSchemaCollisions(graph, diagnostics);
45
+ lintKindExpectedTemplates(graph, diagnostics);
43
46
  return diagnostics;
44
47
  }
45
48
  /**
@@ -82,7 +85,7 @@ function lintInlineStandaloneSchemaCollisions(graph, diagnostics) {
82
85
  if (parts.length < 3 || parts[parts.length - 2] !== 'schemas')
83
86
  continue;
84
87
  const name = parts[parts.length - 1];
85
- const standaloneId = `${node.component}.Schema.${name}`;
88
+ const standaloneId = `${node.namespace}.Schema.${name}`;
86
89
  const standalone = graph.nodesById.get(standaloneId);
87
90
  if (!standalone || standalone.state === 'removed')
88
91
  continue;
@@ -335,7 +338,7 @@ function approxFilePath(graph, node) {
335
338
  if (parts.length < 2)
336
339
  return current.id;
337
340
  const [component, template, ...rest] = parts;
338
- return `components/${component}/${template}s/${rest.join('/') || template}.yaml`;
341
+ return `${NODE_ROOT_DIR}/${component}/${template}s/${rest.join('/') || template}.yaml`;
339
342
  }
340
343
  function valueMatchesType(value, type) {
341
344
  switch (type) {
@@ -355,3 +358,29 @@ function describeType(value) {
355
358
  return 'null';
356
359
  return typeof value;
357
360
  }
361
+ /** Advisory only: namespaces of a kind that lists templates should own just those. */
362
+ function lintKindExpectedTemplates(graph, diagnostics) {
363
+ if (!graph.kinds)
364
+ return;
365
+ const namespaces = getNamespaces(graph);
366
+ const reported = new Set();
367
+ for (const node of graph.nodesById.values()) {
368
+ if (node.parentId)
369
+ continue;
370
+ const ns = node.id.split('.')[0];
371
+ const kind = namespaces.get(ns)?.kind;
372
+ const expected = kind !== undefined && kind !== 'component' ? graph.kinds.get(kind)?.templates : undefined;
373
+ if (!expected || expected.includes(node.template))
374
+ continue;
375
+ const key = ns + ':' + node.template;
376
+ if (reported.has(key))
377
+ continue;
378
+ reported.add(key);
379
+ diagnostics.push({
380
+ severity: 'warning',
381
+ file: NODE_ROOT_DIR + '/' + ns,
382
+ nodeId: node.id,
383
+ message: `namespace '${ns}' of kind '${kind}' owns template '${node.template}', expected one of: ${expected.join(', ')}`,
384
+ });
385
+ }
386
+ }
@@ -1,3 +1,5 @@
1
+ import { isNamespaceDeclaration } from './namespace-loader.js';
2
+ import { NODE_ROOT_DIR } from '../source/graph-paths.js';
1
3
  import { parse as parseYaml } from 'yaml';
2
4
  import { getOwnedSections } from './pack-loader.js';
3
5
  import { listYamlKeys, readYaml } from '../source/content-utils.js';
@@ -12,7 +14,9 @@ const STRUCTURAL_EDGE_BY_ROLE = {
12
14
  };
13
15
  export function loadClusters(content, templates, diagnostics) {
14
16
  const result = { nodes: new Map(), edgesByFrom: new Map(), edgesByTo: new Map() };
15
- for (const key of listYamlKeys(content, 'components')) {
17
+ for (const key of listYamlKeys(content, NODE_ROOT_DIR)) {
18
+ if (isNamespaceDeclaration(key))
19
+ continue;
16
20
  let raw;
17
21
  try {
18
22
  raw = parseYaml(readYaml(content, key));
@@ -40,7 +44,7 @@ export function loadClusters(content, templates, diagnostics) {
40
44
  const root = {
41
45
  id: record.id,
42
46
  template: record.template,
43
- component: meta.component,
47
+ namespace: record.id.split('.')[0],
44
48
  state: asState(meta.state, 'proposed', diagnostics, key, record.id),
45
49
  stability: asStability(meta.stability, 'unstable', diagnostics, key, record.id),
46
50
  schemaVersion: record.schemaVersion,
@@ -137,7 +141,7 @@ export function materialiseChildren(result, parent, clusterRoot, source, templat
137
141
  id: childId,
138
142
  parentId: parent.id,
139
143
  template: childTemplateName,
140
- component: parent.component,
144
+ namespace: parent.namespace,
141
145
  state: asState(value.state, parent.state, diagnostics, filePath, childId),
142
146
  stability: asStability(value.stability, parent.stability, diagnostics, filePath, childId),
143
147
  schemaVersion: parent.schemaVersion,
@@ -1,3 +1,5 @@
1
+ import { loadKinds } from './kind-loader.js';
2
+ import { loadNamespaceDeclarations } from './namespace-loader.js';
1
3
  import { FileGraphSource } from '../source/file-source.js';
2
4
  import { SourceError } from '../source/index.js';
3
5
  import { LoadError, QueryError } from '../schema/index.js';
@@ -19,6 +21,7 @@ export async function loadGraph(options) {
19
21
  const packContent = await source.loadPackContent(defaultRef);
20
22
  const templates = loadPacks(packContent, diagnostics);
21
23
  const edgeTypes = loadEdgeTypes(packContent, diagnostics);
24
+ const kinds = loadKinds(packContent, diagnostics);
22
25
  const graphContent = await source.loadGraphContent(ref);
23
26
  const clusterResult = loadClusters(graphContent, templates, diagnostics);
24
27
  const edgeResult = loadEdges(graphContent, clusterResult.nodes, diagnostics, edgeTypes);
@@ -27,6 +30,8 @@ export async function loadGraph(options) {
27
30
  mergeEdgeMaps(edgesByFrom, edgeResult.edgesByFrom);
28
31
  mergeEdgeMaps(edgesByTo, edgeResult.edgesByTo);
29
32
  const graph = {
33
+ namespaceDeclarations: loadNamespaceDeclarations(graphContent, clusterResult.nodes, diagnostics, kinds),
34
+ kinds,
30
35
  nodesById: clusterResult.nodes,
31
36
  edgesByFrom,
32
37
  edgesByTo,
@@ -0,0 +1,63 @@
1
+ import { parse as parseYaml } from 'yaml';
2
+ import { listYamlKeys, readYaml } from '../source/content-utils.js';
3
+ export const DEFAULT_KIND = 'component';
4
+ /** The built-in registry: only the default kind, regardless of packs. */
5
+ export function builtinKinds() {
6
+ return new Map([[DEFAULT_KIND, { id: DEFAULT_KIND, label: 'Component' }]]);
7
+ }
8
+ function sameKind(a, b) {
9
+ return a.label === b.label && JSON.stringify(a.templates ?? null) === JSON.stringify(b.templates ?? null);
10
+ }
11
+ /**
12
+ * Build the kind registry: the built-in default plus any `kinds.yaml` declared
13
+ * by loaded packs. Conflicting redeclarations are errors (first kept);
14
+ * identical redeclarations are accepted. Malformed files never abort loading.
15
+ */
16
+ export function loadKinds(packContent, diagnostics) {
17
+ const kinds = builtinKinds();
18
+ const keys = listYamlKeys(packContent, '').filter(key => key === 'kinds.yaml' || key.endsWith('/kinds.yaml'));
19
+ for (const key of keys) {
20
+ let raw;
21
+ try {
22
+ raw = parseYaml(readYaml(packContent, key));
23
+ }
24
+ catch (err) {
25
+ diagnostics.push({ severity: 'error', file: key, message: `failed to parse YAML: ${err}` });
26
+ continue;
27
+ }
28
+ const declared = raw?.kinds;
29
+ if (typeof declared !== 'object' || declared === null || Array.isArray(declared)) {
30
+ diagnostics.push({ severity: 'error', file: key, message: `kinds.yaml must declare a 'kinds' map` });
31
+ continue;
32
+ }
33
+ for (const [id, defRaw] of Object.entries(declared)) {
34
+ if (typeof defRaw !== 'object' || defRaw === null || Array.isArray(defRaw)) {
35
+ diagnostics.push({ severity: 'error', file: key, message: `kind '${id}' must be an object` });
36
+ continue;
37
+ }
38
+ const def = defRaw;
39
+ if (typeof def.label !== 'string' || def.label.trim() === '') {
40
+ diagnostics.push({ severity: 'error', file: key, message: `kind '${id}' must have a non-empty string 'label'` });
41
+ continue;
42
+ }
43
+ let templates;
44
+ if (def.templates !== undefined) {
45
+ if (!Array.isArray(def.templates) || !def.templates.every(t => typeof t === 'string')) {
46
+ diagnostics.push({ severity: 'error', file: key, message: `kind '${id}' templates must be a list of strings` });
47
+ continue;
48
+ }
49
+ templates = def.templates;
50
+ }
51
+ const kind = { id, label: def.label, ...(templates && { templates }) };
52
+ const existing = kinds.get(id);
53
+ if (existing) {
54
+ if (!sameKind(existing, kind)) {
55
+ diagnostics.push({ severity: 'error', file: key, message: `kind '${id}' is already declared with a different definition` });
56
+ }
57
+ continue;
58
+ }
59
+ kinds.set(id, kind);
60
+ }
61
+ }
62
+ return kinds;
63
+ }
@@ -0,0 +1,36 @@
1
+ import { parse as parseYaml } from 'yaml';
2
+ import { NODE_ROOT_DIR } from '../source/graph-paths.js';
3
+ export function isNamespaceDeclaration(key) {
4
+ return new RegExp(`^${NODE_ROOT_DIR}/[^/]+/namespace\\.yaml$`).test(key);
5
+ }
6
+ export function loadNamespaceDeclarations(content, nodes, diagnostics, kinds) {
7
+ const declarations = new Map();
8
+ const populated = new Set([...nodes.keys()].map(id => id.split('.')[0]));
9
+ for (const [file, text] of content) {
10
+ if (!isNamespaceDeclaration(file))
11
+ continue;
12
+ const name = file.split('/')[1];
13
+ try {
14
+ const doc = parseYaml(text);
15
+ if (!doc || typeof doc !== 'object' || Array.isArray(doc))
16
+ throw new Error('expected a mapping');
17
+ const record = doc;
18
+ const unknownKeys = Object.keys(record).filter(key => key !== 'kind' && key !== 'description');
19
+ if (unknownKeys.length)
20
+ throw new Error(`unknown declaration key(s): ${unknownKeys.join(', ')}`);
21
+ if (typeof record.kind !== 'string')
22
+ throw new Error('kind must be a string');
23
+ if (record.description !== undefined && typeof record.description !== 'string')
24
+ throw new Error('description must be a string');
25
+ if (!populated.has(name))
26
+ diagnostics.push({ severity: 'warning', file, message: 'namespace declaration contains no nodes' });
27
+ declarations.set(name, { kind: record.kind, ...(record.description !== undefined ? { description: record.description } : {}) });
28
+ if (!kinds.has(record.kind))
29
+ diagnostics.push({ severity: 'warning', file, message: `unrecognised kind '${record.kind}', falling back to generic display` });
30
+ }
31
+ catch (err) {
32
+ diagnostics.push({ severity: 'error', file, message: `invalid namespace declaration: ${err}` });
33
+ }
34
+ }
35
+ return declarations;
36
+ }
@@ -3,7 +3,7 @@ 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, expandExternalNodes, getClusterView, getGraphSummary, getLineage, getLinkedFields, getStructuralNodeTemplates, getVisibleEdgeTypes, isVisibleEdgeType, listNodes, searchNodes, } from '../graph/index.js';
6
+ import { computeClusterOverlay, expandExternalNodes, getClusterView, getGraphSummary, getLineage, getLinkedFields, getKindRegistry, getNamespaces, getStructuralNodeTemplates, getVisibleEdgeTypes, isVisibleEdgeType, listNodes, searchNodes, } from '../graph/index.js';
7
7
  import { loadGraph, loadMultiGraph } from '../loader/index.js';
8
8
  import { QueryError } from '../schema/index.js';
9
9
  import { MutationError, getActiveSession, startSession } from '../mutate/index.js';
@@ -39,7 +39,8 @@ function parseListNodesFilter(value) {
39
39
  return {
40
40
  templates: toStringArray(filterArg.templates),
41
41
  excludeTemplates: toStringArray(filterArg.exclude_templates),
42
- component: typeof filterArg.component === 'string' ? filterArg.component : undefined,
42
+ namespace: typeof filterArg.namespace === 'string' ? filterArg.namespace : undefined,
43
+ kind: typeof filterArg.kind === 'string' ? filterArg.kind : undefined,
43
44
  state: typeof filterArg.state === 'string'
44
45
  ? filterArg.state
45
46
  : toStringArray(filterArg.state),
@@ -55,7 +56,7 @@ function summarizeNode(node, includeProvenance) {
55
56
  return {
56
57
  id: node.id,
57
58
  template: node.template,
58
- component: node.component,
59
+ namespace: node.namespace,
59
60
  state: node.state,
60
61
  stability: node.stability,
61
62
  ...(includeProvenance ? withProvenance(node) : {}),
@@ -73,7 +74,7 @@ function fullNode(node, includeProvenance) {
73
74
  return {
74
75
  id: node.id,
75
76
  template: node.template,
76
- component: node.component,
77
+ namespace: node.namespace,
77
78
  state: node.state,
78
79
  stability: node.stability,
79
80
  ...(node.corum !== undefined ? { corum: node.corum } : {}),
@@ -117,7 +118,7 @@ function mapLineageNode(node, includeProvenance, lean) {
117
118
  return {
118
119
  ...base,
119
120
  template: String(node.template),
120
- component: String(node.component),
121
+ namespace: String(node.namespace),
121
122
  state: String(node.state),
122
123
  stability: String(node.stability),
123
124
  properties: (node.properties ?? {}),
@@ -379,6 +380,8 @@ export function createMcpHandlers(graph, source, cache) {
379
380
  template_names: [...targetGraph.templates.keys()].sort(),
380
381
  node_templates_in_use: [...nodeTemplatesInUse].sort(),
381
382
  edge_types_in_use: [...edgeTypesInUse].sort(),
383
+ kinds: getKindRegistry(targetGraph),
384
+ namespaces: [...getNamespaces(targetGraph)].sort(([a], [b]) => a.localeCompare(b)).map(([name, ns]) => ({ namespace: name, kind: ns.kind })),
382
385
  ...(includeStatic ? {
383
386
  valid_edge_types: [...(targetGraph.edgeTypes?.keys() ?? [])],
384
387
  states: [...STATE_VALUES],
@@ -853,7 +856,8 @@ export function getMcpToolDefinitions() {
853
856
  properties: {
854
857
  templates: { type: 'array', items: { type: 'string' }, description: 'Include only these templates (OR).' },
855
858
  exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these templates.' },
856
- component: { type: 'string', description: 'Filter by component.' },
859
+ namespace: { type: 'string', description: 'Filter by namespace (first ID segment).' },
860
+ kind: { type: 'string', description: 'Filter by namespace kind (exact match, e.g. component).' },
857
861
  state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
858
862
  stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
859
863
  },
@@ -919,7 +923,8 @@ export function getMcpToolDefinitions() {
919
923
  properties: {
920
924
  templates: { type: 'array', items: { type: 'string' } },
921
925
  exclude_templates: { type: 'array', items: { type: 'string' } },
922
- component: { type: 'string' },
926
+ namespace: { type: 'string' },
927
+ kind: { type: 'string' },
923
928
  state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
924
929
  stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
925
930
  },
@@ -933,7 +938,7 @@ export function getMcpToolDefinitions() {
933
938
  },
934
939
  {
935
940
  name: 'get_graph_metadata',
936
- description: 'Discover graph contents: template names, node templates in use, edge types in use. Call first; only traverse edge types listed in edge_types_in_use. include_static_enums:true adds valid edge types, states, stabilities, directions, formats.',
941
+ description: 'Discover graph contents: template names, node templates in use, edge types in use, the kind registry and each namespace\'s kind. Call first; only traverse edge types listed in edge_types_in_use. include_static_enums:true adds valid edge types, states, stabilities, directions, formats.',
937
942
  inputSchema: {
938
943
  type: 'object',
939
944
  properties: {
@@ -984,7 +989,7 @@ export function getMcpToolDefinitions() {
984
989
  },
985
990
  {
986
991
  name: 'get_graph_summary',
987
- description: 'High-level stats: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
992
+ description: 'High-level stats: node count, namespace count and counts by kind, orphan breakdown, edge counts by type, diagnostic count.',
988
993
  inputSchema: {
989
994
  type: 'object',
990
995
  properties: {
@@ -995,7 +1000,7 @@ export function getMcpToolDefinitions() {
995
1000
  },
996
1001
  {
997
1002
  name: 'search_nodes',
998
- description: 'Ranked fuzzy search for root nodes by ID segment. Returns slim summaries (id, template, component, state, stability). Preferred discovery entry point; use list_nodes only for exhaustive filtered inventories.',
1003
+ description: 'Ranked fuzzy search for root nodes by ID segment. Returns slim summaries (id, template, namespace, state, stability). Preferred discovery entry point; use list_nodes only for exhaustive filtered inventories.',
999
1004
  inputSchema: {
1000
1005
  type: 'object',
1001
1006
  required: ['queries'],
@@ -15,9 +15,9 @@ Corum models service architecture as a typed graph, stored in Git.
15
15
 
16
16
  ## Concepts
17
17
 
18
- - **Node**: a design artifact whose type is one of this graph's templates (listed below). Each has a template, component, lifecycle state, stability, and properties.
18
+ - **Node**: a design artifact whose type is one of this graph's templates (listed below). Each has a template, namespace, lifecycle state, stability, and properties.
19
19
  - **Template**: a node's type. Defines its property schema, which sections it owns, and which edge types it may use; templates can extend others. Templates in this graph: ${templatesLine}.
20
- - **Component**: the top-level grouping a node belongs to (the first id segment).
20
+ - **Namespace**: the top-level grouping a node belongs to (the first id segment). Each namespace has exactly one **kind** (default \`component\`; packs may define others). get_graph_metadata lists the kinds and each namespace's kind.
21
21
  - **Cluster**: one root node plus the owned-child subtree its template materializes (e.g. a model owns schemas, which own fields). One YAML file = one cluster.
22
22
  - **Edge**: a typed, directed relationship between two nodes.
23
23
  - *Structural* edges (has-field, has-value, renamed-from) are auto-generated from ownership and excluded from traversal by default.
@@ -28,14 +28,14 @@ Corum models service architecture as a typed graph, stored in Git.
28
28
 
29
29
  A dot path encoding the ownership hierarchy:
30
30
 
31
- {component}.{Template}.{name} - root node
32
- {component}.{Template}.{name}.{section}.{child} - owned child
31
+ {namespace}.{Template}.{name} - root node
32
+ {namespace}.{Template}.{name}.{section}.{child} - owned child
33
33
 
34
- The Template segment is one of this graph's templates, so a root id already tells you its component and template. search_nodes and list_nodes return root nodes only.
34
+ The Template segment is one of this graph's templates, so a root id already tells you its namespace and template. search_nodes and list_nodes return root nodes only.
35
35
 
36
36
  ## Graph completeness
37
37
 
38
- The graph reflects modeled relationships, not guaranteed-complete truth. Missing edges do not prove no relationship exists. Treat naming, shared component context, schema similarity, and lineage adjacency as hypotheses, then verify against the relevant nodes, clusters, and source.
38
+ The graph reflects modeled relationships, not guaranteed-complete truth. Missing edges do not prove no relationship exists. Treat naming, shared namespace context, schema similarity, and lineage adjacency as hypotheses, then verify against the relevant nodes, clusters, and source.
39
39
 
40
40
  ## Recommended workflow
41
41
 
@@ -53,13 +53,13 @@ Prefer the smallest response that answers the question.
53
53
  - Expensive tools — bound them:
54
54
  - get_graph returns the whole graph; prefer search_nodes or get_lineage for anything targeted.
55
55
  - get_cluster returns the root with its collapsed schemas/enums; owned descendants are opt-in (include_descendants: true) and can be large. Narrow with node_types.
56
- - search_nodes returns slim summaries (id, template, component, state, stability); full_nodes: true adds every property and is far larger — leave it off unless you need the bodies. Bound with page_size.
56
+ - search_nodes returns slim summaries (id, template, namespace, state, stability); full_nodes: true adds every property and is far larger — leave it off unless you need the bodies. Bound with page_size.
57
57
  - Keep include_provenance and include_edges off unless needed.
58
58
  - get_lineage is lean by default (only i, oi, d, vet, vni per node) and omits edges; set lean:false / include_edges:true only when you need full nodes or edge-level detail.
59
59
 
60
60
  When compact_keys is true these keys are shortened:
61
61
 
62
- id -> i template -> t component -> cp
62
+ id -> i template -> t namespace -> ns
63
63
  state -> s stability -> st properties -> p
64
64
  nodes -> n edges -> e root -> r
65
65
  children -> ch from -> fr to -> to
@@ -73,7 +73,7 @@ When compact_keys is true these keys are shortened:
73
73
 
74
74
  (all default to toon; add compact_keys: true to shrink further)
75
75
 
76
- - Nodes of given templates in a component: list_nodes, filter { templates: [...], component: "..." }.
76
+ - Nodes of given templates in a namespace: list_nodes, filter { templates: [...], namespace: "..." }. Use filter { kind: "..." } for all namespaces of a kind.
77
77
  - What does this node produce? get_lineage, direction "downstream", edge_types ["produces"], depth 1.
78
78
  - What triggers this node? get_lineage, direction "upstream", edge_types ["triggers"], depth 1.
79
79
  - Full flow around a node: get_lineage, direction "both", depth 3.
@@ -34,7 +34,7 @@ export function getSerializer(format) {
34
34
  const COMPACT_KEY_MAP = {
35
35
  id: 'i',
36
36
  template: 't',
37
- component: 'cp',
37
+ namespace: 'ns',
38
38
  state: 's',
39
39
  stability: 'st',
40
40
  schemaVersion: 'sv',
@@ -1,3 +1,4 @@
1
+ import { NODE_ROOT_DIR } from '../source/graph-paths.js';
1
2
  import { stringify as stringifyYaml } from 'yaml';
2
3
  import { loadClusters, materialiseChildren } from '../loader/cluster-loader.js';
3
4
  import { getOwnedSections } from '../loader/pack-loader.js';
@@ -208,9 +209,9 @@ export function materialiseRootDocument(document, templates) {
208
209
  doc.metadata = metadata;
209
210
  const parts = id.split('.');
210
211
  if (parts.length < 3) {
211
- throw new MutationError([mutationDiagnostic('error', `create node: '${id}' is not a valid cluster root id (component.Template.name)`, id)]);
212
+ throw new MutationError([mutationDiagnostic('error', `create node: '${id}' is not a valid cluster root id (namespace.Template.name)`, id)]);
212
213
  }
213
- const filePath = `components/${parts[0]}/${parts[1]}s/${parts.slice(2).join('/')}.yaml`;
214
+ const filePath = `${NODE_ROOT_DIR}/${parts[0]}/${parts[1]}s/${parts.slice(2).join('/')}.yaml`;
214
215
  const diagnostics = [];
215
216
  const result = loadClusters(new Map([[filePath, stringifyYaml(doc)]]), templates, diagnostics);
216
217
  if (diagnostics.some(d => d.severity === 'error'))
@@ -145,7 +145,7 @@ export function resolveIncomingAliases(graph, aliasMap, incoming, incomingEdges,
145
145
  export function detectPossibleRenames(diff, specPath) {
146
146
  const diagnostics = [];
147
147
  const addedByGroup = new Map();
148
- const groupKey = (node) => `${node.template}|${node.parentId ?? node.component}`;
148
+ const groupKey = (node) => `${node.template}|${node.parentId ?? node.namespace}`;
149
149
  for (const added of diff.toAdd) {
150
150
  const key = groupKey(added);
151
151
  addedByGroup.set(key, [...(addedByGroup.get(key) ?? []), added]);
@@ -1,3 +1,4 @@
1
+ import { isManagedGraphYamlKey } from './graph-paths.js';
1
2
  import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
2
3
  import { createHash } from 'node:crypto';
3
4
  import fs from 'node:fs';
@@ -251,9 +252,6 @@ function walkManagedGraphYamlIntoMap(baseDir, currentDir, map, excludeDirs = new
251
252
  map.set(key, content);
252
253
  }
253
254
  }
254
- function isManagedGraphYamlKey(key) {
255
- return key === 'graph.yaml' || key.startsWith('components/') || key.startsWith('edges/');
256
- }
257
255
  function normalizeContentKey(key) {
258
256
  return key.split(path.sep).join('/');
259
257
  }
@@ -1,3 +1,4 @@
1
+ import { isManagedGraphYamlKey } from './graph-paths.js';
1
2
  import fs from 'node:fs';
2
3
  import path from 'node:path';
3
4
  import * as git from 'isomorphic-git';
@@ -161,7 +162,7 @@ export class GitGraphSource {
161
162
  const commitSha = await this.resolveBranchOid(ref);
162
163
  const prefix = this.graphDir.endsWith('/') ? this.graphDir : `${this.graphDir}/`;
163
164
  const allFiles = await git.listFiles({ fs, dir, ref: commitSha });
164
- for (const filePath of allFiles.filter(file => file.startsWith(prefix) && file.endsWith('.yaml'))) {
165
+ for (const filePath of allFiles.filter(file => file.startsWith(prefix) && file.endsWith('.yaml') && isManagedGraphYamlKey(file.slice(prefix.length)))) {
165
166
  try {
166
167
  const { blob } = await git.readBlob({ fs, dir, oid: commitSha, filepath: filePath });
167
168
  map.set(filePath.slice(prefix.length), Buffer.from(blob).toString('utf-8'));
@@ -0,0 +1,6 @@
1
+ /** Root directory for graph node cluster files. */
2
+ export const NODE_ROOT_DIR = 'nodes';
3
+ /** Graph YAML owned by loaders and graph replacement. */
4
+ export function isManagedGraphYamlKey(key) {
5
+ return key === 'graph.yaml' || key.startsWith(`${NODE_ROOT_DIR}/`) || key.startsWith('edges/');
6
+ }