@atolis-hq/corum 0.1.62 → 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',
@@ -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,4 +1,5 @@
1
1
  import { NODE_ROOT_DIR } from '../source/graph-paths.js';
2
+ import { getNamespaces } from '../graph/index.js';
2
3
  import { getEdgeTypeConstraints } from '../graph/roles.js';
3
4
  import { CORE_EDGE_TYPE_MAP } from '../loader/constants.js';
4
5
  import { validateNodeId } from '../loader/id-grammar.js';
@@ -41,6 +42,7 @@ export function lintGraph(graph) {
41
42
  lintEdgeProperties(graph, diagnostics);
42
43
  lintHiddenEdgeLiveEnds(graph, diagnostics);
43
44
  lintInlineStandaloneSchemaCollisions(graph, diagnostics);
45
+ lintKindExpectedTemplates(graph, diagnostics);
44
46
  return diagnostics;
45
47
  }
46
48
  /**
@@ -83,7 +85,7 @@ function lintInlineStandaloneSchemaCollisions(graph, diagnostics) {
83
85
  if (parts.length < 3 || parts[parts.length - 2] !== 'schemas')
84
86
  continue;
85
87
  const name = parts[parts.length - 1];
86
- const standaloneId = `${node.component}.Schema.${name}`;
88
+ const standaloneId = `${node.namespace}.Schema.${name}`;
87
89
  const standalone = graph.nodesById.get(standaloneId);
88
90
  if (!standalone || standalone.state === 'removed')
89
91
  continue;
@@ -356,3 +358,29 @@ function describeType(value) {
356
358
  return 'null';
357
359
  return typeof value;
358
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,4 @@
1
+ import { isNamespaceDeclaration } from './namespace-loader.js';
1
2
  import { NODE_ROOT_DIR } from '../source/graph-paths.js';
2
3
  import { parse as parseYaml } from 'yaml';
3
4
  import { getOwnedSections } from './pack-loader.js';
@@ -14,6 +15,8 @@ const STRUCTURAL_EDGE_BY_ROLE = {
14
15
  export function loadClusters(content, templates, diagnostics) {
15
16
  const result = { nodes: new Map(), edgesByFrom: new Map(), edgesByTo: new Map() };
16
17
  for (const key of listYamlKeys(content, NODE_ROOT_DIR)) {
18
+ if (isNamespaceDeclaration(key))
19
+ continue;
17
20
  let raw;
18
21
  try {
19
22
  raw = parseYaml(readYaml(content, key));
@@ -41,7 +44,7 @@ export function loadClusters(content, templates, diagnostics) {
41
44
  const root = {
42
45
  id: record.id,
43
46
  template: record.template,
44
- component: meta.component,
47
+ namespace: record.id.split('.')[0],
45
48
  state: asState(meta.state, 'proposed', diagnostics, key, record.id),
46
49
  stability: asStability(meta.stability, 'unstable', diagnostics, key, record.id),
47
50
  schemaVersion: record.schemaVersion,
@@ -138,7 +141,7 @@ export function materialiseChildren(result, parent, clusterRoot, source, templat
138
141
  id: childId,
139
142
  parentId: parent.id,
140
143
  template: childTemplateName,
141
- component: parent.component,
144
+ namespace: parent.namespace,
142
145
  state: asState(value.state, parent.state, diagnostics, filePath, childId),
143
146
  stability: asStability(value.stability, parent.stability, diagnostics, filePath, childId),
144
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',
@@ -209,7 +209,7 @@ export function materialiseRootDocument(document, templates) {
209
209
  doc.metadata = metadata;
210
210
  const parts = id.split('.');
211
211
  if (parts.length < 3) {
212
- 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)]);
213
213
  }
214
214
  const filePath = `${NODE_ROOT_DIR}/${parts[0]}/${parts[1]}s/${parts.slice(2).join('/')}.yaml`;
215
215
  const diagnostics = [];
@@ -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]);
@@ -6,7 +6,7 @@ import { existsSync, readFileSync, readdirSync, watch } from 'node:fs';
6
6
  import { readdir } from 'node:fs/promises';
7
7
  import { fileURLToPath, pathToFileURL } from 'node:url';
8
8
  import { parse as parseYaml } from 'yaml';
9
- import { computeClusterOverlay, getClusterView, getGraphSummary, expandExternalNodes, getLineage, getStructuralNodeTemplates, isVisibleEdgeType, listNodes, searchNodes, } from '../graph/index.js';
9
+ import { computeClusterOverlay, getClusterView, getGraphSummary, expandExternalNodes, getKindLabel, getKindRegistry, getLineage, getNamespaces, getStructuralNodeTemplates, isVisibleEdgeType, listNodes, searchNodes, } from '../graph/index.js';
10
10
  import { loadGraph, loadMultiGraph } from '../loader/index.js';
11
11
  import { CORE_EDGE_TYPES } from '../loader/constants.js';
12
12
  import { getOwnedSections } from '../loader/pack-loader.js';
@@ -170,6 +170,8 @@ export function replaceGraph(target, source) {
170
170
  target.templates = source.templates;
171
171
  target.diagnostics = source.diagnostics;
172
172
  target.edgeTypes = source.edgeTypes;
173
+ target.namespaceDeclarations = source.namespaceDeclarations;
174
+ target.kinds = source.kinds;
173
175
  target.sourceContent = source.sourceContent;
174
176
  }
175
177
  function isFileWatcherEnabled(options) {
@@ -303,7 +305,7 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
303
305
  res.json(templates);
304
306
  });
305
307
  app.get('/api/nodes', async (req, res) => {
306
- const { component, state, stability } = req.query;
308
+ const { namespace, kind, state, stability } = req.query;
307
309
  const includeCore = req.query.includeCore === 'true';
308
310
  const singleTemplate = typeof req.query.template === 'string' && req.query.template
309
311
  ? [req.query.template]
@@ -315,7 +317,8 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
315
317
  : undefined;
316
318
  const filter = {
317
319
  templates: multiTemplates ?? singleTemplate,
318
- component: typeof component === 'string' ? component : undefined,
320
+ namespace: typeof namespace === 'string' ? namespace : undefined,
321
+ kind: typeof kind === 'string' ? kind : undefined,
319
322
  state: typeof state === 'string' ? state : undefined,
320
323
  stability: typeof stability === 'string' ? stability : undefined,
321
324
  };
@@ -323,6 +326,7 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
323
326
  if (typeof req.query.ref === 'string' && multiCache) {
324
327
  targetGraph = await getGraphForRef(req.query.ref, multiCache, graph);
325
328
  }
329
+ const namespaces = getNamespaces(targetGraph);
326
330
  const nodes = listNodes(targetGraph, filter)
327
331
  .filter(node => includeCore || !targetGraph.templates.get(node.template)?.info?.core)
328
332
  .map(node => {
@@ -330,7 +334,8 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
330
334
  return {
331
335
  id: ownership.id,
332
336
  template: ownership.template,
333
- component: ownership.component,
337
+ namespace: ownership.namespace,
338
+ kind: namespaces.get(ownership.namespace)?.kind ?? 'component',
334
339
  state: ownership.state,
335
340
  stability: ownership.stability,
336
341
  parentId: ownership.parentId,
@@ -358,6 +363,7 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
358
363
  : filterExcludeTemplates?.length
359
364
  ? new Set(filterExcludeTemplates)
360
365
  : getStructuralNodeTemplates(targetGraph);
366
+ const namespaces = getNamespaces(targetGraph);
361
367
  const nodes = [];
362
368
  for (const node of targetGraph.nodesById.values()) {
363
369
  if (filterTemplates?.length && !filterTemplates.includes(node.template))
@@ -368,7 +374,8 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
368
374
  nodes.push({
369
375
  id: node.id,
370
376
  template: node.template,
371
- component: node.component,
377
+ namespace: node.namespace,
378
+ kind: namespaces.get(node.namespace)?.kind ?? 'component',
372
379
  state: node.state,
373
380
  stability: node.stability,
374
381
  parentId: ownership?.parentId ?? null,
@@ -396,6 +403,19 @@ export function createApp(graph, reloadEvents = createReloadEvents(), source, mu
396
403
  res.status(500).json({ error: String(err) });
397
404
  }
398
405
  });
406
+ app.get('/api/kinds', async (req, res) => {
407
+ let targetGraph = graph;
408
+ if (typeof req.query.ref === 'string' && multiCache) {
409
+ targetGraph = await getGraphForRef(req.query.ref, multiCache, graph);
410
+ }
411
+ const namespaces = getNamespaces(targetGraph);
412
+ res.json({
413
+ kinds: getKindRegistry(targetGraph),
414
+ namespaces: [...namespaces]
415
+ .sort(([a], [b]) => a.localeCompare(b))
416
+ .map(([name, ns]) => ({ namespace: name, kind: ns.kind, label: getKindLabel(targetGraph, ns.kind) })),
417
+ });
418
+ });
399
419
  app.get('/api/stats', async (req, res) => {
400
420
  let targetGraph = graph;
401
421
  if (typeof req.query.ref === 'string' && multiCache) {
@@ -1,3 +1,4 @@
1
+ import { isNamespaceDeclaration } from '../loader/namespace-loader.js';
1
2
  import { NODE_ROOT_DIR } from '../source/graph-paths.js';
2
3
  import fs from 'node:fs';
3
4
  import path from 'node:path';
@@ -11,6 +12,11 @@ const YAML_STRINGIFY_OPTIONS = { singleQuote: true };
11
12
  export function serializeGraph(graph, options = {}) {
12
13
  const map = new Map();
13
14
  map.set('graph.yaml', buildGraphYaml(graph, options));
15
+ // Preserve declarations verbatim; never synthesize undeclared namespaces.
16
+ for (const [key, content] of graph.sourceContent ?? []) {
17
+ if (isNamespaceDeclaration(key))
18
+ map.set(key, content);
19
+ }
14
20
  for (const root of getRootNodes(graph)) {
15
21
  map.set(clusterPath(root), stringifyGraphYaml(toClusterDocument(graph, root)));
16
22
  }
@@ -64,7 +70,7 @@ function normalizeContentKey(value) {
64
70
  function toClusterDocument(graph, root) {
65
71
  const sourceDoc = loadSourceClusterDocument(graph, root);
66
72
  const metadata = {
67
- component: root.component,
73
+ component: root.namespace,
68
74
  state: root.state,
69
75
  stability: root.stability,
70
76
  lastModifiedAt: root.lastModifiedAt,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.62",
3
+ "version": "0.1.63",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",