@atolis-hq/corum 0.1.45 → 0.1.47

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
@@ -1,6 +1,47 @@
1
- # Corum
2
-
3
- Corum is a Git-native design graph for service architecture. It models components (APIs, domain models, schemas, fields) as nodes with typed edges, and exposes the graph through MCP tools so AI assistants can reason about your architecture.
1
+ <div align="center">
2
+
3
+
4
+ <img src="https://raw.githubusercontent.com/atolis-hq/corum/refs/heads/main/assets/corum-logo.svg" alt="logo" width="200" height="auto" />
5
+ <h1>Corum</h1>
6
+
7
+ <p>
8
+ Unified system design surface, built for agents and humans.
9
+ </p>
10
+
11
+
12
+ <!-- Badges -->
13
+ <p>
14
+ <a href="https://github.com/atolis-hq/corum/commits/main">
15
+ <img src="https://img.shields.io/github/last-commit/atolis-hq/corum" alt="last update" />
16
+ </a>
17
+ <a href="https://github.com/atolis-hq/corum/actions/workflows/ci-cd.yml">
18
+ <img src="https://github.com/atolis-hq/corum/actions/workflows/ci-cd.yml/badge.svg" alt="CI/CD status" />
19
+ </a>
20
+ <!-- <a href="https://github.com/atolis-hq/corum/network/members">
21
+ <img src="https://img.shields.io/github/forks/atolis-hq/corum" alt="forks" />
22
+ </a>
23
+ <a href="https://github.com/atolis-hq/corum/stargazers">
24
+ <img src="https://img.shields.io/github/stars/atolis-hq/corum" alt="stars" />
25
+ </a> -->
26
+ <a href="https://github.com/atolis-hq/corum/issues/">
27
+ <img src="https://img.shields.io/github/issues/atolis-hq/corum" alt="open issues" />
28
+ </a>
29
+ <a href="https://github.com/atolis-hq/corum/blob/main/LICENSE">
30
+ <img src="https://img.shields.io/github/license/atolis-hq/corum.svg" alt="license" />
31
+ </a>
32
+ <a href="https://github.com/atolis-hq/corum/tags">
33
+ <img src="https://img.shields.io/github/v/tag/atolis-hq/corum" alt="latest tag" />
34
+ </a>
35
+ <a href="https://www.npmjs.com/package/@atolis-hq/corum">
36
+ <img src="https://img.shields.io/npm/v/%40atolis-hq%2Fcorum" alt="npm version" />
37
+ </a>
38
+ </p>
39
+ </div>
40
+
41
+ <br />
42
+
43
+
44
+ Corum is a Git-native, extensible design graph for software architecture. It models components as nodes with typed edges, and exposes the graph through MCP tools so AI assistants can reason about and evolve your architecture. Corum provides several out of the box schemas (such as APIs, domain models, events, schemas, fields) but can be customised to model any data structure. The graph enables modelling data lineage at object and field level, and the branching model enables multiple simultaneous designs with cross branch impact analysis.
4
45
 
5
46
  ## Install
6
47
 
@@ -365,14 +406,15 @@ Or if installed globally:
365
406
  | `update_node` | Patch node properties, state, or stability |
366
407
  | `rename_node` | Rename a node while preserving identity trail metadata |
367
408
  | `delete_node` | Soft-delete or hard-delete a node subtree |
368
- | `create_edge` | Create an explicit edge |
409
+ | `create_edges` | Batch-create explicit edges as one atomic operation |
369
410
  | `update_edge` | Patch an explicit edge |
370
411
  | `delete_edge` | Delete an explicit edge |
412
+ | `create_fields` | Batch-create fields across schemas (grouped and applied per parent) |
371
413
  | `pending_changes` | Show the open session's journal and summary diff |
372
414
  | `discard_changes` | Abort the working session |
373
415
  | `commit_changes` | Lint, serialize, and persist the session's changes |
374
416
 
375
- All tools accept an optional `format` argument: `yaml` (default), `json`, or `toon`. All tools also accept `compact_keys: true` to shorten common keys before serialization, reducing token usage.
417
+ All tools accept an optional `format` argument: `toon` (default; leanest for the LLM), `yaml`, or `json`. All tools also accept `compact_keys: true` to shorten common keys before serialization, reducing token usage further.
376
418
 
377
419
  All node-returning MCP tools accept `include_provenance: true` to include `extractedFrom`, `lastModifiedAt`, `derivation`, and `derivedBy`. These fields are omitted by default. `schemaVersion` is never returned by MCP.
378
420
 
@@ -395,7 +437,7 @@ Common notes:
395
437
  Corum's write tools are session-based:
396
438
 
397
439
  1. Call `start_changes`.
398
- 2. Make one or more mutations with `apply_cluster`, `create_node`, `update_node`, `rename_node`, `delete_node`, `create_edge`, `update_edge`, or `delete_edge`.
440
+ 2. Make one or more mutations with `apply_cluster`, `create_node`, `update_node`, `rename_node`, `delete_node`, `create_edges`, `update_edge`, `delete_edge`, or `create_fields`.
399
441
  3. Inspect the session with `pending_changes`.
400
442
  4. Finish with `commit_changes` or abort with `discard_changes`.
401
443
 
@@ -9,7 +9,7 @@ import { QueryError } from '../schema/index.js';
9
9
  import { MutationError, getActiveSession, startSession } from '../mutate/index.js';
10
10
  import { createGraphRuntimeConfig } from '../source/config.js';
11
11
  import { createMultiGraphCache, replaceGraph, startGraphFileWatcher, startWebServer } from '../web/server.js';
12
- import { USAGE_GUIDE_PROMPT } from './prompts/usage-guide.js';
12
+ import { buildUsageGuidePrompt } from './prompts/usage-guide.js';
13
13
  import { collapseClusterSchemas } from '../graph/schema-collapse.js';
14
14
  import { compactKeys, getSerializer } from './serializers.js';
15
15
  const STATE_VALUES = ['draft', 'proposed', 'agreed', 'future', 'removed', 'implemented'];
@@ -194,12 +194,9 @@ export function createMcpHandlers(graph, source, cache) {
194
194
  };
195
195
  const wantFull = args.full_nodes === true;
196
196
  const incProv = includesProvenance(args);
197
- const results = searchNodes(targetGraph, queries, options).map(result => ({
198
- score: result.score,
199
- node: wantFull
200
- ? fullNode(result.node, incProv)
201
- : summarizeNode(result.node, incProv),
202
- }));
197
+ const results = searchNodes(targetGraph, queries, options).map(result => wantFull
198
+ ? fullNode(result.node, incProv)
199
+ : summarizeNode(result.node, incProv));
203
200
  return formatResult(results, args.format, getCompactKeys(args));
204
201
  };
205
202
  if (hasBranch(args) && source) {
@@ -269,7 +266,7 @@ export function createMcpHandlers(graph, source, cache) {
269
266
  const includeProvenance = includesProvenance(args);
270
267
  const collapseSchemas = args.collapse_schemas !== false;
271
268
  const includeEdges = args.include_edges === true;
272
- const includeDescendants = args.include_descendants !== false;
269
+ const includeDescendants = args.include_descendants === true;
273
270
  const nodeTypes = toStringArray(args.node_types);
274
271
  const edgeOptions = getEdgeOutputOptions(args);
275
272
  let clusterPayload;
@@ -587,19 +584,89 @@ export function createMcpHandlers(graph, source, cache) {
587
584
  return errorResult(err, args.format);
588
585
  }
589
586
  },
590
- async create_edge(args) {
587
+ async create_fields(args) {
591
588
  try {
592
589
  const session = requireSession();
593
- const result = await session.createEdge({
594
- from: requireString(args.from, 'from'),
595
- to: requireString(args.to, 'to'),
596
- type: requireString(args.type, 'type'),
597
- state: args.state,
598
- stability: args.stability,
599
- notes: typeof args.notes === 'string' ? args.notes : undefined,
600
- properties: isPlainObject(args.properties) ? args.properties : undefined,
590
+ if (!Array.isArray(args.fields)) {
591
+ throw new QueryError('fields is required and must be an array');
592
+ }
593
+ // Group by parent so fields sharing a root/schema become one merged
594
+ // document: one applyCluster call per parent (atomic per parent),
595
+ // instead of one call per field.
596
+ const documentsByParent = new Map();
597
+ const order = [];
598
+ const fieldPaths = [];
599
+ args.fields.forEach((field, index) => {
600
+ if (!isPlainObject(field)) {
601
+ throw new QueryError(`fields[${index}] must be an object`);
602
+ }
603
+ const parentId = requireString(pickDefined(field.parent_id, field.parentId), `fields[${index}].parent_id`);
604
+ const schemaName = requireString(pickDefined(field.schema_name, field.schemaName), `fields[${index}].schema_name`);
605
+ const fieldName = requireString(field.name, `fields[${index}].name`);
606
+ const fieldDef = {
607
+ type: requireString(field.type, `fields[${index}].type`),
608
+ };
609
+ if (field.nullable !== undefined) {
610
+ if (typeof field.nullable !== 'boolean') {
611
+ throw new QueryError(`fields[${index}].nullable must be a boolean`);
612
+ }
613
+ fieldDef.nullable = field.nullable;
614
+ }
615
+ if (typeof field.description === 'string') {
616
+ fieldDef.description = field.description;
617
+ }
618
+ if (field.state !== undefined)
619
+ fieldDef.state = field.state;
620
+ if (field.stability !== undefined)
621
+ fieldDef.stability = field.stability;
622
+ let document = documentsByParent.get(parentId);
623
+ if (!document) {
624
+ document = { id: parentId, schemas: {} };
625
+ documentsByParent.set(parentId, document);
626
+ order.push(parentId);
627
+ }
628
+ const schemas = document.schemas;
629
+ const schema = (schemas[schemaName] ??= { fields: {} });
630
+ const fields = schema.fields;
631
+ fields[fieldName] = fieldDef;
632
+ fieldPaths.push({ parentId, schemaName, fieldName });
601
633
  });
602
- return formatResult(result, args.format, getCompactKeys(args));
634
+ const results = [];
635
+ for (const parentId of order) {
636
+ const result = await session.applyCluster(documentsByParent.get(parentId), 'merge');
637
+ results.push({ parentId, summary: result.summary, createdIds: result.createdIds, warnings: result.warnings });
638
+ }
639
+ return formatResult({ created: fieldPaths.length, fields: fieldPaths, applied: results }, args.format, getCompactKeys(args));
640
+ }
641
+ catch (err) {
642
+ return errorResult(err, args.format);
643
+ }
644
+ },
645
+ async create_edges(args) {
646
+ try {
647
+ const session = requireSession();
648
+ if (!Array.isArray(args.edges)) {
649
+ throw new QueryError('edges is required and must be an array');
650
+ }
651
+ const inputs = args.edges.map((edge, index) => {
652
+ if (!isPlainObject(edge)) {
653
+ throw new QueryError(`edges[${index}] must be an object`);
654
+ }
655
+ return {
656
+ from: requireString(edge.from, `edges[${index}].from`),
657
+ to: requireString(edge.to, `edges[${index}].to`),
658
+ type: requireString(edge.type, `edges[${index}].type`),
659
+ state: edge.state,
660
+ stability: edge.stability,
661
+ notes: typeof edge.notes === 'string' ? edge.notes : undefined,
662
+ properties: isPlainObject(edge.properties) ? edge.properties : undefined,
663
+ };
664
+ });
665
+ // Validated and applied as a single atomic batch (session.createEdges):
666
+ // any invalid edge aborts the whole call before any edge is created.
667
+ const result = await session.createEdges(inputs);
668
+ const edges = result.edges.map(edge => ({ edge }));
669
+ return formatResult({ created: edges.length, edges, summary: result.summary, warnings: result.warnings }, args.format, getCompactKeys(args));
603
670
  }
604
671
  catch (err) {
605
672
  return errorResult(err, args.format);
@@ -674,6 +741,10 @@ export function createMcpHandlers(graph, source, cache) {
674
741
  },
675
742
  };
676
743
  }
744
+ /** Prefers `primary` over `secondary`, falling back only when `primary` is absent (not merely falsy/empty). */
745
+ function pickDefined(primary, secondary) {
746
+ return primary !== undefined ? primary : secondary;
747
+ }
677
748
  function requireString(value, name) {
678
749
  if (typeof value !== 'string' || value.length === 0) {
679
750
  throw new QueryError(`${name} is required`);
@@ -728,7 +799,7 @@ export async function ensureGraphLoaded(graph, loadError, loader, onReload) {
728
799
  }
729
800
  function formatResult(value, format, compact = false) {
730
801
  const payload = compact === true ? compactKeys(value) : value;
731
- return { content: [{ type: 'text', text: getSerializer(format).serialize(payload) }] };
802
+ return { content: [{ type: 'text', text: getSerializer(format ?? 'toon').serialize(payload) }] };
732
803
  }
733
804
  function getCompactKeys(args) {
734
805
  return args.compact_keys === true || args.compactKeys === true;
@@ -747,7 +818,7 @@ function errorResult(err, format) {
747
818
  };
748
819
  let text;
749
820
  try {
750
- text = getSerializer(format).serialize(payload);
821
+ text = getSerializer(format ?? 'toon').serialize(payload);
751
822
  }
752
823
  catch {
753
824
  text = getSerializer(undefined).serialize(payload);
@@ -757,108 +828,89 @@ function errorResult(err, format) {
757
828
  const message = err instanceof QueryError ? err.message : String(err);
758
829
  return { content: [{ type: 'text', text: message }], isError: true };
759
830
  }
831
+ // Shared parameter schemas — these appear on nearly every tool, so factoring
832
+ // them out keeps the always-loaded tool definitions lean and consistent. Deep
833
+ // guidance (compact_keys mapping, toon rationale, workflows) lives in the
834
+ // on-demand usage-guide prompt, not here.
835
+ const FORMAT_PARAM = { type: 'string', enum: [...OUTPUT_FORMATS], description: 'Default toon (lean, self-describing). yaml for humans, json for conventional parsing.' };
836
+ const COMPACT_KEYS_PARAM = { type: 'boolean', description: 'Abbreviate field-name keys to save tokens (see usage-guide). Default false.' };
837
+ const BRANCH_READ_PARAM = { type: 'string', description: 'Branch ref to read from. Default: open session or source default.' };
838
+ const PROVENANCE_PARAM = { type: 'boolean', description: 'Include node provenance (source/derivation). Default false.' };
839
+ const EDGE_IDS_PARAM = { type: 'boolean', description: 'Include edge ids in edge output. Default false.' };
840
+ const STATE_PARAM = { type: 'string', enum: [...STATE_VALUES], description: 'Lifecycle state.' };
841
+ const STABILITY_PARAM = { type: 'string', enum: [...STABILITY_VALUES], description: 'Stability.' };
842
+ const IO_PARAMS = { format: FORMAT_PARAM, compact_keys: COMPACT_KEYS_PARAM };
760
843
  export function getMcpToolDefinitions() {
761
844
  return [
762
845
  {
763
846
  name: 'list_nodes',
764
- description: 'List nodes in the graph. Returns id, template, component, state, stability for each matched node.',
847
+ description: 'Root nodes matching a filter, as slim summaries. Prefer search_nodes for keyword discovery; use this for exhaustive filtered inventories.',
765
848
  inputSchema: {
766
849
  type: 'object',
767
850
  properties: {
768
851
  filter: {
769
852
  type: 'object',
770
- description: 'Filter criteria',
771
853
  properties: {
772
- templates: {
773
- type: 'array',
774
- items: { type: 'string' },
775
- description: 'Include only these template types (OR semantics)',
776
- },
777
- exclude_templates: {
778
- type: 'array',
779
- items: { type: 'string' },
780
- description: 'Exclude these template types',
781
- },
782
- component: { type: 'string', description: 'Filter by component name' },
783
- state: {
784
- description: 'Filter by lifecycle state as a string or array',
785
- oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
786
- },
787
- stability: {
788
- description: 'Filter by stability as a string or array',
789
- oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
790
- },
854
+ templates: { type: 'array', items: { type: 'string' }, description: 'Include only these templates (OR).' },
855
+ exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these templates.' },
856
+ component: { type: 'string', description: 'Filter by component.' },
857
+ state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
858
+ stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
791
859
  },
792
860
  },
793
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
794
- branch: { type: 'string', description: 'Branch ref to load nodes from' },
795
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
796
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
861
+ include_provenance: PROVENANCE_PARAM,
862
+ branch: BRANCH_READ_PARAM,
863
+ ...IO_PARAMS,
797
864
  },
798
865
  },
799
866
  },
800
867
  {
801
868
  name: 'list_templates',
802
- description: 'List loaded graph templates. Returns name, version, core, abstract, extends, and description for each template.',
869
+ description: 'List loaded templates with summary metadata (name, version, core, abstract, extends, description).',
803
870
  inputSchema: {
804
871
  type: 'object',
805
872
  properties: {
806
- branch: { type: 'string', description: 'Branch ref to load templates from' },
807
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
808
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
873
+ branch: BRANCH_READ_PARAM,
874
+ ...IO_PARAMS,
809
875
  },
810
876
  },
811
877
  },
812
878
  {
813
879
  name: 'get_template',
814
- description: 'Get full details for a loaded graph template.',
880
+ description: 'Full definition of one template: property schema, owned sections, edge-type constraints, role.',
815
881
  inputSchema: {
816
882
  type: 'object',
817
883
  required: ['name'],
818
884
  properties: {
819
- name: { type: 'string', description: 'Template name' },
820
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
821
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
885
+ name: { type: 'string', description: 'Template name.' },
886
+ ...IO_PARAMS,
822
887
  },
823
888
  },
824
889
  },
825
890
  {
826
891
  name: 'get_cluster',
827
- 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.',
892
+ description: 'Structural detail of ONE node. Returns the root with its collapsed schemas/enums (compact JSON-schema form, not child nodes) by default. Owned descendants (operations, commands, events) are opt-in via include_descendants:true and can be large — narrow with node_types. To follow relationships across nodes use get_lineage instead.',
828
893
  inputSchema: {
829
894
  type: 'object',
830
895
  required: ['node_id'],
831
896
  properties: {
832
- node_id: { type: 'string', description: 'Fully qualified node ID' },
833
- edge_types: {
834
- type: 'array',
835
- items: { type: 'string' },
836
- description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
837
- },
838
- 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.' },
839
- include_descendants: { type: 'boolean', description: 'Include descendant nodes (operations, commands, events, and cross-component nodes). Default true.' },
840
- node_types: {
841
- type: 'array',
842
- items: { type: 'string' },
843
- description: 'Allowlist of node templates to include in the descendant set. Useful for limiting to specific types (e.g. ["DomainOperation", "DomainEvent"]).',
844
- },
845
- include_edges: { type: 'boolean', description: 'Include the edge list in the response. Default false.' },
846
- include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
847
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
848
- branch: { type: 'string', description: 'Branch ref to load the cluster from' },
849
- overlay_refs: {
850
- type: 'array',
851
- items: { type: 'string' },
852
- description: 'Branch refs to overlay. Returns ghost field data alongside the cluster.',
853
- },
854
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
855
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
897
+ node_id: { type: 'string', description: 'Fully qualified node ID.' },
898
+ edge_types: { type: 'array', items: { type: 'string' }, description: 'External-node edge types to follow. Default: all semantic.' },
899
+ collapse_schemas: { type: 'boolean', description: 'Collapse schema/enum children into compact schemas+enums blocks on the root. Default true.' },
900
+ include_descendants: { type: 'boolean', description: 'Include owned descendants (operations, commands, events). Opt-in; can be large. Default false.' },
901
+ node_types: { type: 'array', items: { type: 'string' }, description: 'Restrict descendants to these templates.' },
902
+ include_edges: { type: 'boolean', description: 'Include the edge list. Default false.' },
903
+ include_edge_ids: EDGE_IDS_PARAM,
904
+ include_provenance: PROVENANCE_PARAM,
905
+ branch: BRANCH_READ_PARAM,
906
+ overlay_refs: { type: 'array', items: { type: 'string' }, description: 'Branch refs to overlay as ghost field data.' },
907
+ ...IO_PARAMS,
856
908
  },
857
909
  },
858
910
  },
859
911
  {
860
912
  name: 'get_graph',
861
- description: 'Return semantic nodes (and optionally edges) across the graph. Excludes structural templates and structural edge types by default. Pass include_edges: true to include the semantic edge list.',
913
+ description: 'Semantic nodes across the whole graph (structural templates/edges excluded); include_edges adds semantic edges. Whole-graph payload is large — prefer search_nodes or get_lineage for targeted work.',
862
914
  inputSchema: {
863
915
  type: 'object',
864
916
  properties: {
@@ -872,303 +924,314 @@ export function getMcpToolDefinitions() {
872
924
  stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
873
925
  },
874
926
  },
875
- include_edges: { type: 'boolean', description: 'Include the semantic edge list in the response. Default false.' },
876
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
877
- branch: { type: 'string', description: 'Branch ref to load the graph from' },
878
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
879
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
927
+ include_edges: { type: 'boolean', description: 'Include semantic edges. Default false.' },
928
+ include_provenance: PROVENANCE_PARAM,
929
+ branch: BRANCH_READ_PARAM,
930
+ ...IO_PARAMS,
880
931
  },
881
932
  },
882
933
  },
883
934
  {
884
935
  name: 'get_graph_metadata',
885
- description: 'Return discoverable graph metadata: template names, node templates in use, edge types in use. Call this first before making traversal queries. The edge_types_in_use field tells you which edge types are actually modelled in the current graph - there is no value traversing edge types that have no entries. Pass include_static_enums: true to also receive valid_edge_types, states, stabilities, lineage_directions, and output_formats.',
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.',
886
937
  inputSchema: {
887
938
  type: 'object',
888
939
  properties: {
889
- include_static_enums: { type: 'boolean', description: 'Include static enum reference fields (valid_edge_types, states, stabilities, lineage_directions, output_formats). Default false.' },
890
- branch: { type: 'string', description: 'Branch ref to load metadata from' },
891
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
892
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
940
+ include_static_enums: { type: 'boolean', description: 'Also return valid edge types, states, stabilities, directions, formats. Default false.' },
941
+ branch: BRANCH_READ_PARAM,
942
+ ...IO_PARAMS,
893
943
  },
894
944
  },
895
945
  },
896
946
  {
897
947
  name: 'get_lineage',
898
- description: 'Traverse the graph from one or more origin nodes via BFS and return annotated lineage results. Pass multiple node_ids to expand all origins in parallel in a single call rather than making separate calls - results are merged and deduplicated automatically.\n\nCommon patterns:\n- Event fan-out - direction: downstream, depth: 2 from an event node to see all triggered commands and the operations they invoke.\n- Find all writers to an aggregate - direction: upstream from a DomainModel node to see every command and operation that writes to it.\n- Full event chain - direction: downstream, depth: 3 or more to trace event -> command -> operation -> produced event chains.',
948
+ description: 'BFS traversal from origin node(s); returns reachable nodes annotated with depth and the edge/node they arrived via. Batch multiple node_ids in one call — results merge and dedupe. Lean by default; scope with direction, depth, and edge_types.',
899
949
  inputSchema: {
900
950
  type: 'object',
901
951
  required: ['node_ids'],
902
952
  properties: {
903
- node_ids: {
904
- type: 'array',
905
- items: { type: 'string' },
906
- description: 'Fully-qualified IDs of origin nodes. All expand in parallel.',
907
- },
953
+ node_ids: { type: 'array', items: { type: 'string' }, description: 'Origin node IDs; all expand in parallel.' },
908
954
  depth: { type: 'number', description: 'Max hops. Default 2.' },
909
- direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Traversal direction. Default downstream.' },
955
+ direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Default downstream.' },
910
956
  edge_types: { type: 'array', items: { type: 'string' }, description: 'Edge types to traverse. Default: all non-structural.' },
911
- node_types: { type: 'array', items: { type: 'string' }, description: 'Allowlist of node templates.' },
912
- exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
913
- include_dangling_edges: { type: 'boolean', description: 'Include dangling edges in the response when present. Default false.' },
914
- reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads/uses-type edges in upstream traversal. Default true.' },
915
- lean: { type: 'boolean', description: 'Return minimal lineage node shape. Default true.' },
916
- include_edges: { type: 'boolean', description: 'Include the edges list in the response. Default false.' },
917
- include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
918
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
919
- branch: { type: 'string', description: 'Branch ref to load the lineage from' },
920
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
921
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
957
+ node_types: { type: 'array', items: { type: 'string' }, description: 'Template allowlist.' },
958
+ exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Template denylist.' },
959
+ include_dangling_edges: { type: 'boolean', description: 'Include dangling edges. Default false.' },
960
+ reads_outbound_only: { type: 'boolean', description: 'Skip inbound reads/uses-type in upstream traversal. Default true.' },
961
+ lean: { type: 'boolean', description: 'Minimal node shape (ids + traversal annotations only). Default true.' },
962
+ include_edges: { type: 'boolean', description: 'Include edges. Default false.' },
963
+ include_edge_ids: EDGE_IDS_PARAM,
964
+ include_provenance: PROVENANCE_PARAM,
965
+ branch: BRANCH_READ_PARAM,
966
+ ...IO_PARAMS,
922
967
  },
923
968
  },
924
969
  },
925
970
  {
926
971
  name: 'get_linked_fields',
927
- description: 'Get all maps-to edges touching fields owned by the given root node.',
972
+ description: 'All maps-to edges touching fields owned by the given root node.',
928
973
  inputSchema: {
929
974
  type: 'object',
930
975
  required: ['node_id'],
931
976
  properties: {
932
- node_id: { type: 'string', description: 'Fully qualified root node ID' },
933
- include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
934
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
935
- branch: { type: 'string', description: 'Branch ref to load linked fields from' },
936
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
937
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
977
+ node_id: { type: 'string', description: 'Fully qualified root node ID.' },
978
+ include_edge_ids: EDGE_IDS_PARAM,
979
+ include_provenance: PROVENANCE_PARAM,
980
+ branch: BRANCH_READ_PARAM,
981
+ ...IO_PARAMS,
938
982
  },
939
983
  },
940
984
  },
941
985
  {
942
986
  name: 'get_graph_summary',
943
- description: 'Return high-level statistics: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
987
+ description: 'High-level stats: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
944
988
  inputSchema: {
945
989
  type: 'object',
946
990
  properties: {
947
- branch: { type: 'string', description: 'Branch ref to load the summary from' },
948
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
949
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
991
+ branch: BRANCH_READ_PARAM,
992
+ ...IO_PARAMS,
950
993
  },
951
994
  },
952
995
  },
953
996
  {
954
997
  name: 'search_nodes',
955
- description: 'Fuzzy search for root-level nodes by ID segments. Returns slim node summaries (id, template, component, state, stability) by default. Pass full_nodes: true to include properties. Prefer this over list_nodes when you have a domain term to search for - it returns ranked, targeted results without noise. Use list_nodes only when you need a complete inventory of nodes matching specific filter criteria.',
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.',
956
999
  inputSchema: {
957
1000
  type: 'object',
958
1001
  required: ['queries'],
959
1002
  properties: {
960
- queries: {
961
- type: 'array',
962
- items: { type: 'string' },
963
- description: 'Search terms. OR semantics; any matching term qualifies the node.',
964
- },
965
- templates: { type: 'array', items: { type: 'string' }, description: 'Include only these template types.' },
966
- exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these template types.' },
967
- page_size: { type: 'number', description: 'Max results to return. Default 10.' },
968
- offset: { type: 'number', description: 'Result offset for pagination. Default 0.' },
969
- search_properties: { type: 'boolean', description: 'Also match name, description, and x-aka properties.' },
970
- full_nodes: { type: 'boolean', description: 'Include properties on each result node. Default false.' },
971
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
972
- branch: { type: 'string', description: 'Branch ref to search within' },
973
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
974
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1003
+ queries: { type: 'array', items: { type: 'string' }, description: 'Search terms (OR).' },
1004
+ templates: { type: 'array', items: { type: 'string' }, description: 'Template allowlist.' },
1005
+ exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Template denylist.' },
1006
+ page_size: { type: 'number', description: 'Max results. Default 10.' },
1007
+ offset: { type: 'number', description: 'Pagination offset. Default 0.' },
1008
+ search_properties: { type: 'boolean', description: 'Also match name/description/x-aka. Default false.' },
1009
+ full_nodes: { type: 'boolean', description: 'Add every property to each result — far larger output; leave off unless you need the bodies. Default false.' },
1010
+ include_provenance: PROVENANCE_PARAM,
1011
+ branch: BRANCH_READ_PARAM,
1012
+ ...IO_PARAMS,
975
1013
  },
976
1014
  },
977
1015
  },
978
1016
  {
979
1017
  name: 'list_branches',
980
- description: 'List branches available from the configured graph source and their load status.',
1018
+ description: 'List branches available from the graph source and their load status.',
981
1019
  inputSchema: {
982
1020
  type: 'object',
983
1021
  properties: {
984
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
985
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1022
+ ...IO_PARAMS,
986
1023
  },
987
1024
  },
988
1025
  },
989
1026
  {
990
1027
  name: 'diff_branch',
991
- description: 'Diff a branch against the default branch. Rename-aware: branch IDs are resolved through the default branch\'s rename trail before matching, so a branch still holding an old name overlays onto the renamed node instead of appearing as add+remove. The result\'s warnings field flags branches that modify a node under a retired name ("edits a retired name") — rebase the branch or apply the rename.',
1028
+ description: 'Diff a branch against the default branch. Rename-aware: old IDs resolve through the rename trail, so a branch holding an old name overlays the renamed node rather than showing add+remove. warnings flags branches editing a retired name — rebase the branch or apply the rename.',
992
1029
  inputSchema: {
993
1030
  type: 'object',
994
1031
  required: ['branch'],
995
1032
  properties: {
996
- branch: { type: 'string', description: 'Branch ref to diff against the default branch' },
997
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
998
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1033
+ branch: { type: 'string', description: 'Branch ref to diff against the default branch.' },
1034
+ ...IO_PARAMS,
999
1035
  },
1000
1036
  },
1001
1037
  },
1002
1038
  {
1003
1039
  name: 'start_changes',
1004
- description: 'Open a working session for graph mutations. All other write tools require an open session; while a session is open, read tools reflect the working (uncommitted) state. Mutations stay in the session until commit_changes; discard_changes aborts. autosave defaults OFF for both file and git sources — prefer leaving it off unless you explicitly want per-mutation checkpoints. When autosave is ON, file sources write through to disk immediately and git sources land a "corum-wip:" checkpoint commit per mutation; commit_changes squashes the WIP run into a single commit when no external commit interleaved. Git default branches are read-only for writes: pass a writable branch explicitly or use create: true to fork one from the default branch head. Starting while a session with pending changes is open is an error — commit_changes or discard_changes first; with no pending changes the old session is reset cleanly.',
1040
+ description: 'Open a write session — required before any mutation; while open, reads reflect uncommitted state. Mutations persist only at commit_changes; discard_changes aborts. autosave defaults OFF. Git default branches are read-only: pass a writable branch or create:true to fork from default head. Errors if a session with pending changes is already open (commit or discard first).',
1005
1041
  inputSchema: {
1006
1042
  type: 'object',
1007
1043
  properties: {
1008
- branch: { type: 'string', description: 'Branch to load and commit to. Defaults to the source\'s default branch.' },
1009
- create: { type: 'boolean', description: 'Fork a new branch from the default branch head (git sources only). Default false.' },
1010
- autosave: { type: 'boolean', description: 'Override the autosave default (OFF by default. When ON: file sources write through immediately; git sources create WIP checkpoint commits).' },
1011
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1012
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1044
+ branch: { type: 'string', description: 'Branch to load and commit to. Default: source default.' },
1045
+ create: { type: 'boolean', description: 'Fork a new branch from default head (git only). Default false.' },
1046
+ autosave: { type: 'boolean', description: 'Persist each mutation (file: write-through; git: WIP checkpoint commit). Default false.' },
1047
+ ...IO_PARAMS,
1013
1048
  },
1014
1049
  },
1015
1050
  },
1016
1051
  {
1017
1052
  name: 'apply_cluster',
1018
- description: 'Upsert a cluster-style nested document — the same shape as cluster YAML: root node fields (id, template, properties, state/stability) plus owned sections keyed by child local name, with child properties flattened at the top level of each child. Requires an open session (start_changes).\n\nmode "merge": updates only what the document mentions — absent children and absent owned sections are left untouched (a null property value clears that key).\n\nmode "replace": WARNING — the document becomes AUTHORITATIVE for every owned section of the root\'s template. Children absent from the document are DELETED, and an ABSENT owned section means an EMPTY section: ALL of its children are DELETED (soft delete with state removed when the node exists on the default branch, hard purge otherwise). Only use replace with the complete intended contents of the cluster.\n\nA changed child key is NEVER treated as a rename: it is delete+add, and the response carries a possible-rename warning when a replace deletes and creates children with the same template under the same parent. To rename, use rename_node — it is the only rename path. Sections the template does not declare as owned are never touched.',
1053
+ description: 'Upsert a cluster-style nested document (same shape as cluster YAML: root fields + owned sections of named children). merge: patch only what is present (null property clears a key). replace: WARNING document is AUTHORITATIVE — children and owned sections absent from it are DELETED (an absent section means an empty section). A changed child key is delete+add, never a rename — use rename_node. Needs an open session.',
1019
1054
  inputSchema: {
1020
1055
  type: 'object',
1021
1056
  required: ['document', 'mode'],
1022
1057
  properties: {
1023
- document: { type: 'object', description: 'Cluster-style document (root node plus owned sections with named children).' },
1024
- mode: { type: 'string', enum: ['merge', 'replace'], description: 'merge: update what is present, leave the rest. replace: document is authoritative for owned sections — absent children/sections are DELETED.' },
1025
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1026
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1058
+ document: { type: 'object', description: 'Root node plus owned sections with named children.' },
1059
+ mode: { type: 'string', enum: ['merge', 'replace'], description: 'merge: patch present fields. replace: authoritative — absent children/sections DELETED.' },
1060
+ ...IO_PARAMS,
1027
1061
  },
1028
1062
  },
1029
1063
  },
1030
1064
  {
1031
1065
  name: 'create_node',
1032
- description: 'Create a root cluster (omit parent_id; document requires id and template) or an owned child under an existing parent (pass parent_id, section, and name; document holds the child body with properties flattened at the top level). Nested owned children in the document are created in the same call and structural edges (has-field, has-value) generate automatically. Defaults: state "proposed", stability "unstable". Requires an open session (start_changes).',
1066
+ description: 'Create a root cluster (omit parent_id; document needs id+template) or an owned child (pass parent_id+section+name; document is the child body). Nested owned children and structural edges (has-field, has-value) generate automatically. Defaults: state proposed, stability unstable. Needs an open session.',
1033
1067
  inputSchema: {
1034
1068
  type: 'object',
1035
1069
  required: ['document'],
1036
1070
  properties: {
1037
- document: { type: 'object', description: 'Cluster-style document. Roots: { id, template, properties?, ...ownedSections }. Owned children: the child body (properties flattened, optional nested owned sections).' },
1038
- parent_id: { type: 'string', description: 'Owning parent node ID — omit to create a root cluster.' },
1039
- section: { type: 'string', description: 'Owned section under the parent (e.g. "fields", "schemas"); required with parent_id.' },
1040
- name: { type: 'string', description: 'Local name for the new owned child; required with parent_id.' },
1041
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1042
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1071
+ document: { type: 'object', description: 'Root: {id, template, properties?, ...ownedSections}. Child: the body (properties flattened, optional nested sections).' },
1072
+ parent_id: { type: 'string', description: 'Owning parent ID — omit for a root cluster.' },
1073
+ section: { type: 'string', description: 'Owned section under parent (e.g. fields, schemas); required with parent_id.' },
1074
+ name: { type: 'string', description: 'Local name of the new child; required with parent_id.' },
1075
+ ...IO_PARAMS,
1043
1076
  },
1044
1077
  },
1045
1078
  },
1046
1079
  {
1047
1080
  name: 'update_node',
1048
- description: 'Patch a node\'s properties, state, or stability. properties is a patch: only the keys given are changed, and a null value clears that key. Cannot change the node\'s name — that is rename_node (names are identity, never a property edit). Requires an open session (start_changes).',
1081
+ description: 'Patch a node\'s properties/state/stability (properties is a patch; null clears a key). Cannot rename — use rename_node. Needs an open session.',
1049
1082
  inputSchema: {
1050
1083
  type: 'object',
1051
1084
  required: ['id'],
1052
1085
  properties: {
1053
- id: { type: 'string', description: 'Fully qualified node ID' },
1054
- properties: { type: 'object', description: 'Property patch — null clears a key.' },
1055
- state: { type: 'string', enum: [...STATE_VALUES], description: 'New lifecycle state.' },
1056
- stability: { type: 'string', enum: [...STABILITY_VALUES], description: 'New stability.' },
1057
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1058
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1086
+ id: { type: 'string', description: 'Fully qualified node ID.' },
1087
+ properties: { type: 'object', description: 'Property patch; null clears a key.' },
1088
+ state: STATE_PARAM,
1089
+ stability: STABILITY_PARAM,
1090
+ ...IO_PARAMS,
1059
1091
  },
1060
1092
  },
1061
1093
  },
1062
1094
  {
1063
1095
  name: 'rename_node',
1064
- description: 'Rename a node (replace the last segment of its ID with new_name). Descendant IDs, parentId fields, and every edge endpoint are rewritten automatically; renaming a cluster root also moves its file at commit. Trail: by default, a rename records corum.identity.previousIds plus a renamed-from edge iff the node exists on the default branch head (i.e. the old name is shared history); record_trail forces (true) or suppresses (false) the trail. This is the ONLY rename path — apply_cluster and imports never infer renames. Requires an open session (start_changes).',
1096
+ description: 'Rename a node (replace the last ID segment). Descendant IDs, parentId, and edge endpoints rewrite automatically; a cluster root\'s file moves at commit. Records a rename trail (previousIds + renamed-from edge) when the old name is shared history on default; record_trail overrides. The ONLY rename path — apply_cluster and imports never infer renames. Needs an open session.',
1065
1097
  inputSchema: {
1066
1098
  type: 'object',
1067
1099
  required: ['id', 'new_name'],
1068
1100
  properties: {
1069
- id: { type: 'string', description: 'Fully qualified node ID to rename' },
1070
- new_name: { type: 'string', description: 'New last segment (ID grammar: [A-Za-z0-9_-], no dots).' },
1071
- record_trail: { type: 'boolean', description: 'Override the trail threshold: true forces recording corum.identity.previousIds + renamed-from; false suppresses it.' },
1072
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1073
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1101
+ id: { type: 'string', description: 'Node ID to rename.' },
1102
+ new_name: { type: 'string', description: 'New last segment (grammar [A-Za-z0-9_-], no dots).' },
1103
+ record_trail: { type: 'boolean', description: 'Force (true) or suppress (false) the rename trail.' },
1104
+ ...IO_PARAMS,
1074
1105
  },
1075
1106
  },
1076
1107
  },
1077
1108
  {
1078
1109
  name: 'delete_node',
1079
- description: 'Delete a node and its owned subtree. Two tiers: soft delete sets state "removed" on the subtree (nodes stay in YAML and remain queryable); hard delete removes the subtree and every edge touching it. Default tier: soft when the node exists on the default branch head (shared history), hard otherwise (pure design work leaves no tombstones). purge: true always hard-deletes; record_trail overrides the threshold (true forces soft, false forces hard). Requires an open session (start_changes).',
1110
+ description: 'Delete a node and its owned subtree. Soft delete (state removed, stays queryable) when the node is shared history on default; hard delete (removes subtree + touching edges) otherwise. purge:true forces hard; record_trail overrides (true soft, false hard). Needs an open session.',
1080
1111
  inputSchema: {
1081
1112
  type: 'object',
1082
1113
  required: ['id'],
1083
1114
  properties: {
1084
- id: { type: 'string', description: 'Fully qualified node ID to delete' },
1085
- purge: { type: 'boolean', description: 'Force hard delete of the subtree and all touching edges. Default false.' },
1086
- record_trail: { type: 'boolean', description: 'Override the soft/hard threshold: true forces soft delete, false forces hard delete.' },
1087
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1088
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1115
+ id: { type: 'string', description: 'Node ID to delete.' },
1116
+ purge: { type: 'boolean', description: 'Force hard delete. Default false.' },
1117
+ record_trail: { type: 'boolean', description: 'true forces soft delete, false forces hard.' },
1118
+ ...IO_PARAMS,
1119
+ },
1120
+ },
1121
+ },
1122
+ {
1123
+ name: 'create_fields',
1124
+ description: 'Batch create multiple fields across schemas in one operation. Each field becomes a proper Field node with structural edges. Fields sharing a parent_id/schema_name are merged and applied together atomically; fields under different parents are applied as separate atomic groups (a failure in one parent\'s group does not roll back another parent\'s group). Defaults: state proposed, stability unstable. Needs an open session.',
1125
+ inputSchema: {
1126
+ type: 'object',
1127
+ required: ['fields'],
1128
+ properties: {
1129
+ fields: {
1130
+ type: 'array',
1131
+ description: 'Array of field definitions',
1132
+ items: {
1133
+ type: 'object',
1134
+ required: ['parent_id', 'schema_name', 'name', 'type'],
1135
+ properties: {
1136
+ parent_id: { type: 'string', description: 'Root node ID (e.g. orders.DomainModel.order).' },
1137
+ schema_name: { type: 'string', description: 'Schema name within the root (e.g. order, order-placed-payload).' },
1138
+ name: { type: 'string', description: 'Field name.' },
1139
+ type: { type: 'string', description: 'Field type (e.g. uuid, decimal, string).' },
1140
+ nullable: { type: 'boolean', description: 'Whether field is nullable. Default false.' },
1141
+ description: { type: 'string', description: 'Optional field description.' },
1142
+ state: STATE_PARAM,
1143
+ stability: STABILITY_PARAM,
1144
+ },
1145
+ },
1146
+ },
1147
+ ...IO_PARAMS,
1089
1148
  },
1090
1149
  },
1091
1150
  },
1092
1151
  {
1093
- name: 'create_edge',
1094
- description: 'Create an explicit edge between two nodes. Validated against endpoint existence and the pack edge-type vocabulary; edge-type constraint violations are returned as warnings. Defaults: state "proposed", stability "unstable". Requires an open session (start_changes).',
1152
+ name: 'create_edges',
1153
+ description: 'Batch create multiple edges as one atomic operation: every edge is validated (including duplicates within the batch) before any edge is created, so an invalid edge aborts the whole call with no partial writes. Same per-edge validation as a single edge create (see delete_edge/update_edge). Needs an open session.',
1095
1154
  inputSchema: {
1096
1155
  type: 'object',
1097
- required: ['from', 'to', 'type'],
1156
+ required: ['edges'],
1098
1157
  properties: {
1099
- from: { type: 'string', description: 'Source node ID' },
1100
- to: { type: 'string', description: 'Target node ID' },
1101
- type: { type: 'string', description: 'Edge type (see get_graph_metadata valid_edge_types).' },
1102
- state: { type: 'string', enum: [...STATE_VALUES], description: 'Lifecycle state. Default "proposed".' },
1103
- stability: { type: 'string', enum: [...STABILITY_VALUES], description: 'Stability. Default "unstable".' },
1104
- notes: { type: 'string', description: 'Free-text notes on the edge.' },
1105
- properties: { type: 'object', description: 'Edge properties (validated against the pack edge-type schema).' },
1106
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1107
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1158
+ edges: {
1159
+ type: 'array',
1160
+ description: 'Array of edge definitions',
1161
+ items: {
1162
+ type: 'object',
1163
+ required: ['from', 'to', 'type'],
1164
+ properties: {
1165
+ from: { type: 'string', description: 'Source node ID.' },
1166
+ to: { type: 'string', description: 'Target node ID.' },
1167
+ type: { type: 'string', description: 'Edge type.' },
1168
+ state: STATE_PARAM,
1169
+ stability: STABILITY_PARAM,
1170
+ notes: { type: 'string', description: 'Free-text note.' },
1171
+ properties: { type: 'object', description: 'Edge properties.' },
1172
+ },
1173
+ },
1174
+ },
1175
+ ...IO_PARAMS,
1108
1176
  },
1109
1177
  },
1110
1178
  },
1111
1179
  {
1112
1180
  name: 'update_edge',
1113
- description: 'Patch an explicit edge\'s state, stability, notes, or properties. Endpoints and type are IMMUTABLE — delete_edge and create_edge instead. notes: null clears the notes; a null property value clears that key. Requires an open session (start_changes).',
1181
+ description: 'Patch an edge\'s state/stability/notes/properties (null clears notes or a property key). Endpoints and type are immutable — delete+create to change them. Needs an open session.',
1114
1182
  inputSchema: {
1115
1183
  type: 'object',
1116
1184
  required: ['id'],
1117
1185
  properties: {
1118
- id: { type: 'string', description: 'Edge ID ({from}__{type}__{to})' },
1119
- state: { type: 'string', enum: [...STATE_VALUES], description: 'New lifecycle state.' },
1120
- stability: { type: 'string', enum: [...STABILITY_VALUES], description: 'New stability.' },
1186
+ id: { type: 'string', description: 'Edge ID ({from}__{type}__{to}).' },
1187
+ state: STATE_PARAM,
1188
+ stability: STABILITY_PARAM,
1121
1189
  notes: { description: 'New notes; null clears them.' },
1122
- properties: { type: 'object', description: 'Property patch — null clears a key.' },
1123
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1124
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1190
+ properties: { type: 'object', description: 'Property patch; null clears a key.' },
1191
+ ...IO_PARAMS,
1125
1192
  },
1126
1193
  },
1127
1194
  },
1128
1195
  {
1129
1196
  name: 'delete_edge',
1130
- description: 'Delete an edge. Always a hard removal — edges carry no subtree. To soft-remove a relationship instead, use update_edge with state "removed". Requires an open session (start_changes).',
1197
+ description: 'Hard-delete an edge (edges carry no subtree). To soft-remove, use update_edge with state removed. Needs an open session.',
1131
1198
  inputSchema: {
1132
1199
  type: 'object',
1133
1200
  required: ['id'],
1134
1201
  properties: {
1135
- id: { type: 'string', description: 'Edge ID ({from}__{type}__{to})' },
1136
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1137
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1202
+ id: { type: 'string', description: 'Edge ID ({from}__{type}__{to}).' },
1203
+ ...IO_PARAMS,
1138
1204
  },
1139
1205
  },
1140
1206
  },
1141
1207
  {
1142
1208
  name: 'pending_changes',
1143
- description: 'Show the open session\'s change journal and a summary diff (added/modified/removed node and edge counts) of the working graph against the session base. Requires an open session (start_changes).',
1209
+ description: 'Show the session\'s change journal and a summary diff (added/modified/removed counts) vs base. Needs an open session.',
1144
1210
  inputSchema: {
1145
1211
  type: 'object',
1146
1212
  properties: {
1147
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1148
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1213
+ ...IO_PARAMS,
1149
1214
  },
1150
1215
  },
1151
1216
  },
1152
1217
  {
1153
1218
  name: 'discard_changes',
1154
- description: 'Abort the working session without committing. With the default autosave OFF, this drops the in-memory session changes. Note: if autosave was turned ON for a file source, mutations already written to disk are NOT rolled back. Requires an open session (start_changes).',
1219
+ description: 'Abort the session without committing, dropping in-memory changes. Autosaved file-source writes are NOT rolled back. Needs an open session.',
1155
1220
  inputSchema: {
1156
1221
  type: 'object',
1157
1222
  properties: {
1158
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1159
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1223
+ ...IO_PARAMS,
1160
1224
  },
1161
1225
  },
1162
1226
  },
1163
1227
  {
1164
1228
  name: 'commit_changes',
1165
- description: 'Lint, serialise, and commit the working graph, then close the session. The full linter runs first: error diagnostics BLOCK the commit (the session stays open to fix and retry); warnings ride along. Default message summarises the journal. Git autosave sessions squash their "corum-wip:" checkpoint run into a single commit when no external commit interleaved (otherwise the final commit lands on top and checkpoints are preserved); file-source autosave sessions have already persisted each mutation, so commit_changes just closes the session. Fails if the branch head moved externally since session start.',
1229
+ description: 'Lint, serialise, and commit the working graph, then close the session. Error diagnostics BLOCK the commit (session stays open to fix); warnings ride along. Git autosave WIP checkpoints squash into one commit unless an external commit interleaved. Fails if the branch head moved externally. Needs an open session.',
1166
1230
  inputSchema: {
1167
1231
  type: 'object',
1168
1232
  properties: {
1169
- message: { type: 'string', description: 'Commit message. Default: a summary of the session journal.' },
1170
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
1171
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
1233
+ message: { type: 'string', description: 'Commit message. Default: journal summary.' },
1234
+ ...IO_PARAMS,
1172
1235
  },
1173
1236
  },
1174
1237
  },
@@ -1229,7 +1292,7 @@ export async function startMcpServer(options = {}) {
1229
1292
  return {
1230
1293
  description: 'Corum graph query orientation guide',
1231
1294
  messages: [
1232
- { role: 'user', content: { type: 'text', text: USAGE_GUIDE_PROMPT } },
1295
+ { role: 'user', content: { type: 'text', text: buildUsageGuidePrompt([...graph.templates.keys()].sort()) } },
1233
1296
  ],
1234
1297
  };
1235
1298
  });
@@ -1279,8 +1342,10 @@ export async function startMcpServer(options = {}) {
1279
1342
  return await handlers.rename_node(args);
1280
1343
  case 'delete_node':
1281
1344
  return await handlers.delete_node(args);
1282
- case 'create_edge':
1283
- return await handlers.create_edge(args);
1345
+ case 'create_fields':
1346
+ return await handlers.create_fields(args);
1347
+ case 'create_edges':
1348
+ return await handlers.create_edges(args);
1284
1349
  case 'update_edge':
1285
1350
  return await handlers.update_edge(args);
1286
1351
  case 'delete_edge':
@@ -1,93 +1,63 @@
1
- export const USAGE_GUIDE_PROMPT = `
1
+ /**
2
+ * The orientation guide is built per-graph so the Concepts section can name the
3
+ * templates actually loaded, instead of hard-coding pack-specific examples that
4
+ * mislead when a different pack is in use. Pass the loaded template names; with
5
+ * none, it defers to get_graph_metadata.
6
+ */
7
+ export function buildUsageGuidePrompt(templateNames = []) {
8
+ const templatesLine = templateNames.length
9
+ ? templateNames.join(', ')
10
+ : '(call get_graph_metadata to list them)';
11
+ return `
2
12
  # Corum graph - orientation guide
3
13
 
4
- Corum models service architecture as a typed graph. Nodes are design artifacts; edges are typed relationships between them.
14
+ Corum models service architecture as a typed graph, stored in Git.
5
15
 
6
- ## Node IDs
7
-
8
- IDs encode the ownership hierarchy as a dot-separated path:
16
+ ## Concepts
9
17
 
10
- {component}.{Template}.{name} - root node
11
- {component}.{Template}.{name}.{section}.{child} - owned child (for example operations, schemas, fields)
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.
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).
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
+ - **Edge**: a typed, directed relationship between two nodes.
23
+ - *Structural* edges (has-field, has-value, renamed-from) are auto-generated from ownership and excluded from traversal by default.
24
+ - *Semantic* edges (triggers, produces, reads, calls, implements, maps-to, derived-from) are the modeled relationships that get_lineage / get_cluster traverse. These are the core types; packs may add more.
25
+ - Call get_graph_metadata for the templates and edge types actually present in this graph.
12
26
 
13
- Examples:
14
- orders.DomainModel.order
15
- orders.DomainModel.order.operations.place
16
- orders.APIEndpoint.create-order
17
-
18
- search_nodes and list_nodes only return root nodes.
27
+ ## Node IDs
19
28
 
20
- ## Edge types
29
+ A dot path encoding the ownership hierarchy:
21
30
 
22
- Semantic (traversed by default in get_lineage / get_cluster):
23
- triggers, produces, reads, calls, implements, maps-to, derived-from
31
+ {component}.{Template}.{name} - root node
32
+ {component}.{Template}.{name}.{section}.{child} - owned child
24
33
 
25
- Structural (excluded from traversal by default):
26
- has-field, has-value, renamed-from
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.
27
35
 
28
36
  ## Graph completeness
29
37
 
30
- The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists.
31
-
32
- When likely relationships are absent, treat naming, shared component context, schema similarity, and lineage adjacency as hypotheses. Then verify by inspecting the relevant nodes, clusters, and source material.
33
-
34
- ## Minimal-output defaults
35
-
36
- Prefer the smallest response that answers the question.
37
-
38
- - Keep include_provenance off unless you need source traceability.
39
- - For get_lineage, keep lean: true, include_edges: false, and use the smallest depth possible.
40
- - Add edge_types, node_types, or exclude_node_types to narrow lineage before increasing depth.
41
- - For search_nodes, avoid full_nodes: true unless summaries are insufficient.
42
- - For get_cluster, start with collapse_schemas: true and leave include_edges and full structural expansion off unless needed.
43
- - Avoid branch, overlay_refs, and include_static_enums unless the task explicitly requires them.
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.
44
39
 
45
40
  ## Recommended workflow
46
41
 
47
- 1. Call get_graph_metadata first to discover which edge types are in use and what node templates exist.
48
-
49
- 2. Use search_nodes with domain terms to find relevant starting nodes. Avoid list_nodes for discovery - it returns full inventories rather than ranked matches.
50
-
51
- 3. Call get_lineage with multiple node_ids batched together rather than separate calls per node.
52
-
53
- 4. Use direction "downstream" with a bounded depth when you need to see what a node leads to next.
42
+ 1. Call get_graph_metadata first — learn which templates and edge types actually exist. Only traverse edge types listed in edge_types_in_use.
43
+ 2. search_nodes with domain terms to find starting nodes. Avoid list_nodes for discovery — it returns full inventories rather than ranked matches.
44
+ 3. get_lineage with node_ids batched together in one call. direction "downstream" for what a node leads to, "upstream" for what leads into it, "both" for full flow. Bound with the smallest depth that answers the question; narrow with edge_types / node_types before increasing depth.
45
+ 4. get_cluster only when you need one node's structural detail, not for traversal.
46
+ 5. Add include_provenance: true only to bridge a finding back to source code.
54
47
 
55
- 5. Use direction "upstream" when you need to find what leads into or influences a node.
48
+ ## Token economy
56
49
 
57
- 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.
58
-
59
- 7. Add include_provenance: true only when you need to bridge a finding to the source codebase.
60
-
61
- ## Write workflow
62
-
63
- When the task is to change the graph rather than inspect it:
64
-
65
- 1. Call start_changes first. No write tool works without an open session.
66
- - Prefer autosave: false unless you explicitly want per-mutation checkpoints.
67
- - With autosave: true on file sources, every mutation writes through immediately and may create granular history/noisy diffs.
68
-
69
- 2. Use the write tools deliberately:
70
- - apply_cluster for cluster-style upserts
71
- - create_node / update_node / rename_node / delete_node for explicit node edits
72
- - create_edge / update_edge / delete_edge for explicit edge edits
73
-
74
- 3. Use pending_changes before commit_changes to inspect the journal and summary diff.
75
-
76
- 4. Finish with commit_changes or discard_changes.
77
- - discard_changes only rolls back in-memory session state; it does not undo file-source mutations that were autosaved write-through.
78
-
79
- Important mutation rules:
80
- - rename_node is the only rename path. apply_cluster and imports never infer renames.
81
- - apply_cluster mode "replace" is authoritative for owned sections: absent children are deleted, and an absent owned section means an empty section.
82
- - delete_node may soft-delete or hard-delete depending on whether the node is already shared history on the default branch.
83
- - While a session is open, normal read tools reflect the working graph for that session branch.
84
-
85
-
86
- ## Output format and token efficiency
50
+ Prefer the smallest response that answers the question.
87
51
 
88
- Start with format "toon" and compact_keys true. TOON is the most token-efficient machine-readable format and compact_keys shortens common field names. Fall back to format "yaml" if a downstream consumer needs human-readable output, or format "json" if it needs conventional structured parsing.
52
+ - Responses default to format "toon" (lean, self-describing). Use format "yaml" for human-readable output, format "json" for conventional parsing. Add compact_keys: true to further shorten envelope keys (mapping below).
53
+ - Expensive tools — bound them:
54
+ - get_graph returns the whole graph; prefer search_nodes or get_lineage for anything targeted.
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.
57
+ - Keep include_provenance and include_edges off unless needed.
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.
89
59
 
90
- When compact_keys is true the following field names are shortened in the response:
60
+ When compact_keys is true these keys are shortened:
91
61
 
92
62
  id -> i template -> t component -> cp
93
63
  state -> s stability -> st properties -> p
@@ -99,35 +69,33 @@ When compact_keys is true the following field names are shortened in the respons
99
69
  via_node_id -> vni lastModifiedAt -> lm extractedFrom -> xf
100
70
  derivation -> dv derivedBy -> db
101
71
 
102
- - get_lineage is lean by default: it returns only id (i), origin_id (oi), depth (d), via_edge_type (vet), and via_node_id (vni) unless lean is set to false.
103
- - get_lineage omits edges by default; add include_edges true when you need graph reconstruction or edge-level auditing.
104
-
105
72
  ## Common patterns
106
73
 
107
- All nodes of selected templates in a component:
108
- list_nodes - filter { templates: ["TemplateA", "TemplateB"], component: "component-name" }, format: "toon", compact_keys: true
74
+ (all default to toon; add compact_keys: true to shrink further)
109
75
 
110
- What does this node produce?
111
- get_lineage - node_ids: ["component.Template.node"], direction: "downstream", edge_types: ["produces"], depth: 1, lean: true, include_edges: false, format: "toon", compact_keys: true
76
+ - Nodes of given templates in a component: list_nodes, filter { templates: [...], component: "..." }.
77
+ - What does this node produce? get_lineage, direction "downstream", edge_types ["produces"], depth 1.
78
+ - What triggers this node? get_lineage, direction "upstream", edge_types ["triggers"], depth 1.
79
+ - Full flow around a node: get_lineage, direction "both", depth 3.
80
+ - Field-level mappings: get_linked_fields for maps-to edges on fields owned by a root node.
81
+ - Schema / field detail: get_cluster (collapse_schemas true, the default) returns each schema as a compact map of field name to { type?, $ref?, collection?, nullable?, edges? } — not child nodes. Local refs use $ref: '#/schemas/name' or '#/enums/name'. Map fields appear as { type: map, key, value }. Cross-cluster field edges (maps-to, derived-from) appear in the field's edges block. Set collapse_schemas false only to get the raw child nodes instead.
112
82
 
113
- What triggers this node?
114
- get_lineage - node_ids: ["component.Template.node"], direction: "upstream", edge_types: ["triggers"], depth: 1, lean: true, include_edges: false, format: "toon", compact_keys: true
115
-
116
- Full relationship flow around a node:
117
- get_lineage - node_ids: ["component.Template.node"], direction: "both", depth: 3, lean: true, include_edges: false, format: "toon", compact_keys: true
83
+ ## Write workflow
118
84
 
119
- Field-level mappings between nodes:
120
- get_linked_fields - id plus connected maps-to edges for fields owned by a root node; keep format: "toon", compact_keys: true
85
+ Mutations require an open session; no write tool works without one.
121
86
 
122
- Schema / field details:
123
- get_cluster - root includes compact schemas and enums blocks by default. Each schema entry
124
- is a map of field name to { type?, $ref?, collection?, nullable?, edges? }. Local references
125
- use $ref: '#/schemas/name' or $ref: '#/enums/name' pointing into the same blocks. Mapping
126
- fields appear as { type: map, key: string, value: { ... } } inline on the field. Field-level
127
- cross-cluster edges (maps-to, derived-from) appear as an edges block on the field. Pass
128
- collapse_schemas: false only when the compact root.schemas / root.enums view is insufficient. Start with
129
- format: "toon", compact_keys: true, collapse_schemas: true.
87
+ 1. start_changes first. Prefer autosave: false unless you want per-mutation checkpoints (on file sources autosave writes through immediately, producing granular/noisy history).
88
+ 2. Mutate: apply_cluster (cluster-style upserts); create_node / update_node / rename_node / delete_node; create_edges / update_edge / delete_edge; create_fields (batch field creation).
89
+ 3. pending_changes to inspect the journal and summary diff before committing.
90
+ 4. commit_changes (error diagnostics block it; session stays open to fix) or discard_changes.
130
91
 
131
- Mutation session:
132
- start_changes -> one or more write calls -> pending_changes -> commit_changes
92
+ Key rules:
93
+ - rename_node is the only rename path. apply_cluster and imports never infer renames.
94
+ - apply_cluster mode "replace" is authoritative: children absent from the document are deleted, and an absent owned section means an empty section.
95
+ - delete_node soft-deletes (state removed, still queryable) when the node is shared history on the default branch, else hard-deletes; purge:true forces hard.
96
+ - discard_changes only rolls back in-memory state, not autosaved file-source writes.
97
+ - While a session is open, reads reflect its working graph.
133
98
  `.trim();
99
+ }
100
+ /** Base guide with no graph-specific template list; prefer buildUsageGuidePrompt(templateNames). */
101
+ export const USAGE_GUIDE_PROMPT = buildUsageGuidePrompt();
@@ -137,25 +137,67 @@ export class WorkingSession {
137
137
  */
138
138
  async createEdge(input) {
139
139
  this.assertOpen();
140
+ const { edge, errors } = this.planEdge(input, new Set());
141
+ if (errors.length > 0)
142
+ throw new MutationError(errors);
143
+ const warnings = lintEdge(this.graph, edge).filter(d => d.severity === 'warning');
144
+ insertEdgeIntoIndexes(this.graph, edge);
145
+ const summary = `create edge ${edge.id}`;
146
+ await this.record('create_edge', { from: input.from, to: input.to, type: input.type }, summary);
147
+ return { edge: edge, warnings, summary };
148
+ }
149
+ /**
150
+ * Batch-create explicit edges as a single atomic operation: every input is
151
+ * validated (including duplicate-within-batch detection) before any edge is
152
+ * applied, so a failing item leaves the working graph untouched rather than
153
+ * partially applying earlier items. One journal entry for the whole batch.
154
+ */
155
+ async createEdges(inputs) {
156
+ this.assertOpen();
157
+ const seenIds = new Set();
158
+ const errors = [];
159
+ const candidates = [];
160
+ inputs.forEach((input, index) => {
161
+ const planned = this.planEdge(input, seenIds, index);
162
+ if (planned.errors.length > 0)
163
+ errors.push(...planned.errors);
164
+ else
165
+ candidates.push(planned.edge);
166
+ });
167
+ if (errors.length > 0)
168
+ throw new MutationError(errors);
169
+ const warnings = [];
170
+ for (const edge of candidates) {
171
+ warnings.push(...lintEdge(this.graph, edge).filter(d => d.severity === 'warning'));
172
+ insertEdgeIntoIndexes(this.graph, edge);
173
+ }
174
+ const summary = `create ${candidates.length} edge${candidates.length === 1 ? '' : 's'}`;
175
+ await this.record('create_edges', { ids: candidates.map(e => e.id) }, summary);
176
+ return { edges: candidates, warnings, summary };
177
+ }
178
+ /** Pure validation + edge construction (no mutation) shared by `createEdge` and `createEdges`. */
179
+ planEdge(input, seenIds, index) {
140
180
  const errors = [];
181
+ const prefix = index !== undefined ? `edges[${index}]: ` : '';
141
182
  const edgeTypes = this.graph.edgeTypes ?? CORE_EDGE_TYPE_MAP;
142
183
  const typeDef = edgeTypes.get(input.type);
143
184
  if (!typeDef) {
144
- errors.push(mutationDiagnostic('error', `unknown edge type '${input.type}'`));
185
+ errors.push(mutationDiagnostic('error', `${prefix}unknown edge type '${input.type}'`));
145
186
  }
146
187
  if (!this.graph.nodesById.has(input.from)) {
147
- errors.push(mutationDiagnostic('error', `cannot create edge: 'from' node not found: ${input.from}`, input.from));
188
+ errors.push(mutationDiagnostic('error', `${prefix}cannot create edge: 'from' node not found: ${input.from}`, input.from));
148
189
  }
149
190
  if (!this.graph.nodesById.has(input.to) && typeDef?.hidden !== true) {
150
- errors.push(mutationDiagnostic('error', `cannot create edge: 'to' node not found: ${input.to}`, input.to));
191
+ errors.push(mutationDiagnostic('error', `${prefix}cannot create edge: 'to' node not found: ${input.to}`, input.to));
151
192
  }
152
193
  validateStateStability(input.state, input.stability, errors);
153
194
  const id = `${input.from}__${input.type}__${input.to}`;
154
- if (findEdgeById(this.graph, id)) {
155
- errors.push(mutationDiagnostic('error', `edge already exists: ${id}`));
195
+ if (findEdgeById(this.graph, id) || seenIds.has(id)) {
196
+ errors.push(mutationDiagnostic('error', `${prefix}edge already exists: ${id}`));
156
197
  }
157
198
  if (errors.length > 0)
158
- throw new MutationError(errors);
199
+ return { errors };
200
+ seenIds.add(id);
159
201
  const edge = {
160
202
  id,
161
203
  from: input.from,
@@ -166,11 +208,7 @@ export class WorkingSession {
166
208
  ...(input.notes !== undefined && { notes: input.notes }),
167
209
  ...(input.properties !== undefined && { properties: { ...input.properties } }),
168
210
  };
169
- const warnings = lintEdge(this.graph, edge).filter(d => d.severity === 'warning');
170
- insertEdgeIntoIndexes(this.graph, edge);
171
- const summary = `create edge ${id}`;
172
- await this.record('create_edge', { from: input.from, to: input.to, type: input.type }, summary);
173
- return { edge, warnings, summary };
211
+ return { edge, errors };
174
212
  }
175
213
  /** Patch an explicit edge. Endpoints and type are immutable (delete + create instead). */
176
214
  async updateEdge(id, patch) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.45",
3
+ "version": "0.1.47",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",