@atolis-hq/corum 0.1.43 → 0.1.45

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
@@ -42,6 +42,12 @@ This creates `.corum/config.yaml`, scaffolds a graph at `.corum/graph/`, and dow
42
42
  corum mcp
43
43
  ```
44
44
 
45
+ If you only want the web UI:
46
+
47
+ ```bash
48
+ corum web
49
+ ```
50
+
45
51
  ## Commands
46
52
 
47
53
  ### `corum mcp`
@@ -53,10 +59,14 @@ corum mcp [options]
53
59
 
54
60
  Options:
55
61
  --no-web Suppress the web UI
56
- --watch Reload graph on file changes
62
+ --watch Reload file-backed graphs on local file changes
57
63
  --graph <path> Override the graph directory
58
64
  ```
59
65
 
66
+ Notes:
67
+ - `corum mcp` starts the web UI unless you pass `--no-web`.
68
+ - `--watch` applies to filesystem graphs. Git-backed graphs reload through polling instead.
69
+
60
70
  ### `corum web`
61
71
 
62
72
  Start the web UI only.
@@ -69,6 +79,21 @@ Options:
69
79
  --graph <path> Override the graph directory
70
80
  ```
71
81
 
82
+ Notes:
83
+ - Filesystem graphs can be watched for local YAML changes with `CORUM_FILE_WATCHER=true` or `CORUM_WATCH=true`.
84
+ - Git-backed graphs reload through polling when `git_poll_seconds` / `CORUM_GIT_POLL_SECONDS` is set.
85
+
86
+ ### `corum lint`
87
+
88
+ Lint the graph and report diagnostics.
89
+
90
+ ```bash
91
+ corum lint [options]
92
+
93
+ Options:
94
+ --graph <path> Override the graph directory
95
+ ```
96
+
72
97
  ### `corum init`
73
98
 
74
99
  Scaffold a `.corum/` project structure and install the four default template packs (`core`, `domain`, `rest`, `messaging`). Skips any step where the target already exists.
@@ -205,7 +230,7 @@ Options:
205
230
  --graph <path> Override the graph directory
206
231
  ```
207
232
 
208
- The interchange format is self-describing — no component mapping strategy is needed. Node IDs, template names, and field references are already corum-native. Gaps reported by the extractor (unresolved types, name collisions) are surfaced as warnings.
233
+ The interchange format is self-describing - no component mapping strategy is needed. Node IDs, template names, and field references are already corum-native. Gaps reported by the extractor (unresolved types, name collisions) are surfaced as warnings.
209
234
 
210
235
  Requires the `extract` pack to be active in your graph:
211
236
 
@@ -226,20 +251,28 @@ imports:
226
251
 
227
252
  Run `corum init` to generate a `.corum/config.yaml` with all available options. Corum walks up from the current directory to find it, so you can place it at your project root.
228
253
 
229
- **Precedence (highest to lowest):** CLI flags → environment variables → `.corum/config.yaml`
254
+ **Precedence (highest to lowest):** CLI flags -> environment variables -> `.corum/config.yaml`
230
255
 
231
256
  | Config key | Environment variable | Description |
232
257
  |---|---|---|
233
258
  | `pack_registry` | - | URL of the pack registry YAML (set by `corum init`) |
234
- | `source` | `CORUM_SOURCE` | `file` (default) or `git` |
259
+ | `source` | `CORUM_SOURCE` | Source mode: `file` / `filesystem` / `fs` (default) or `git` |
235
260
  | `graph` | `CORUM_GRAPH_PATH` | Path to the graph directory |
236
261
  | `git_local_path` | `CORUM_GIT_LOCAL_PATH` | Local git repo path |
237
262
  | `git_remote_url` | `CORUM_GIT_REMOTE_URL` | Remote git repo URL |
238
- | `git_branch` | `CORUM_GIT_BRANCH` | Branch to load |
239
- | `git_poll_seconds` | `CORUM_GIT_POLL_SECONDS` | Polling interval for remote git |
263
+ | `git_branch` | `CORUM_GIT_BRANCH` | Default branch ref used when loading a git-backed graph |
264
+ | `git_poll_seconds` | `CORUM_GIT_POLL_SECONDS` | Poll interval, in seconds, for git-backed web reloads |
240
265
  | `git_token` | `CORUM_GIT_TOKEN` | Auth token for private repos |
241
266
  | `git_username` | `CORUM_GIT_USERNAME` | Auth username (default: `x-access-token`) |
242
267
 
268
+ Additional environment-only runtime settings:
269
+
270
+ | Environment variable | Description |
271
+ |---|---|
272
+ | `CORUM_WEB_PORT` | Default port for `corum web` |
273
+ | `CORUM_FILE_WATCHER` | Enable local file watching for filesystem graphs when running the web UI |
274
+ | `CORUM_WATCH` | Alias for `CORUM_FILE_WATCHER` |
275
+
243
276
  ### File source (default)
244
277
 
245
278
  ```yaml
@@ -248,6 +281,8 @@ source: file
248
281
  graph: .corum/graph
249
282
  ```
250
283
 
284
+ Use this when the graph lives directly on the local filesystem with no git source abstraction.
285
+
251
286
  ### Git source
252
287
 
253
288
  ```yaml
@@ -258,6 +293,20 @@ git_branch: main
258
293
  git_poll_seconds: 30
259
294
  ```
260
295
 
296
+ Or for a local git repository:
297
+
298
+ ```yaml
299
+ # .corum/config.yaml
300
+ source: git
301
+ git_local_path: /path/to/repo
302
+ git_branch: main
303
+ ```
304
+
305
+ Rules:
306
+ - Set exactly one of `git_local_path` or `git_remote_url`.
307
+ - `git_branch` selects the default branch Corum loads for read operations and the web UI.
308
+ - `git_poll_seconds` is only used for git-backed web reloads.
309
+
261
310
  For private repositories, set `CORUM_GIT_TOKEN` as an environment variable rather than storing it in the config file.
262
311
 
263
312
  ## MCP Client Configuration
@@ -310,6 +359,18 @@ Or if installed globally:
310
359
  | `get_linked_fields` | Return `maps-to` edges touching fields owned by a root node |
311
360
  | `list_branches` | List available branches and their load status from the configured source |
312
361
  | `diff_branch` | Diff a branch against the default branch |
362
+ | `start_changes` | Open a working mutation session |
363
+ | `apply_cluster` | Upsert a cluster-style document in `merge` or `replace` mode |
364
+ | `create_node` | Create a root cluster or owned child node |
365
+ | `update_node` | Patch node properties, state, or stability |
366
+ | `rename_node` | Rename a node while preserving identity trail metadata |
367
+ | `delete_node` | Soft-delete or hard-delete a node subtree |
368
+ | `create_edge` | Create an explicit edge |
369
+ | `update_edge` | Patch an explicit edge |
370
+ | `delete_edge` | Delete an explicit edge |
371
+ | `pending_changes` | Show the open session's journal and summary diff |
372
+ | `discard_changes` | Abort the working session |
373
+ | `commit_changes` | Lint, serialize, and persist the session's changes |
313
374
 
314
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.
315
376
 
@@ -320,20 +381,60 @@ Common notes:
320
381
  - `list_nodes` is a breaking-change surface from older builds: use `filter.templates` instead of top-level `template`.
321
382
  - `search_nodes` accepts `queries: string[]`.
322
383
  - `get_graph_metadata` should usually be your first call. Use `edge_types_in_use` to avoid traversing edge types that do not exist in the current graph.
384
+ - `get_graph_metadata` returns `valid_edge_types`, `states`, `stabilities`, `lineage_directions`, and `output_formats` when you pass `include_static_enums: true`.
323
385
  - Prefer `search_nodes` over `list_nodes` for discovery. Use `list_nodes` when you need a full inventory under explicit filters.
324
386
  - `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, `reads_outbound_only`, `lean`, and `include_edges`.
325
387
  - `get_lineage` defaults to `lean: true` and `include_edges: false`. Lean lineage nodes contain only `id`, `origin_id`, `depth`, `via_edge_type`, and `via_node_id`.
326
388
  - Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.
327
389
  - Use `get_cluster` only when you need full structural contents for one node. By default it returns compact `schemas` and `enums` blocks on the root rather than individual field nodes, which keeps response size manageable for large aggregates. Use `get_lineage` for relationship traversal.
390
+ - Read tools reflect the open working session while one exists. Unbranched reads, and branch-scoped reads for that same session branch, show uncommitted changes.
328
391
  - The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists; agents should treat naming and schema similarity as hypotheses and then verify via cluster inspection or source material.
329
392
 
393
+ ## MCP Write Workflow
394
+
395
+ Corum's write tools are session-based:
396
+
397
+ 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`.
399
+ 3. Inspect the session with `pending_changes`.
400
+ 4. Finish with `commit_changes` or abort with `discard_changes`.
401
+
402
+ Important behavior:
403
+ - No write tool works without an open session.
404
+ - `rename_node` is the only rename path. `apply_cluster` and imports never infer renames.
405
+ - `apply_cluster` `replace` mode is authoritative for the root's owned sections: absent children are deleted, and an absent owned section means "empty section".
406
+ - `delete_node` defaults to soft delete for nodes that already exist on the default branch, and hard delete for branch-local design work.
407
+ - `discard_changes` closes the session. On file-backed autosave sessions it does not roll back mutations already written through to disk.
408
+
409
+ Source-mode defaults:
410
+ - Filesystem source: `start_changes` defaults `autosave` on. Each mutation writes through immediately; `commit_changes` mainly lint-gates and closes the session.
411
+ - Git source: `start_changes` defaults `autosave` off. Changes stay in memory until `commit_changes`.
412
+ - Git source with `autosave: true`: each mutation creates a `corum-wip:` checkpoint commit; `commit_changes` squashes that run when no external commit interleaved.
413
+
414
+ Typical sequence:
415
+
416
+ ```yaml
417
+ start_changes:
418
+ branch: feat/order-design
419
+ create: true
420
+
421
+ rename_node:
422
+ id: orders.Schema.invoice
423
+ new_name: bill
424
+
425
+ pending_changes: {}
426
+
427
+ commit_changes:
428
+ message: rename invoice schema to bill
429
+ ```
430
+
330
431
  ## MCP Prompts
331
432
 
332
433
  The server also exposes a discoverable MCP prompt:
333
434
 
334
435
  | Prompt | Description |
335
436
  |---|---|
336
- | `usage-guide` | Orientation guide covering graph structure, recommended tool workflow, output-format choices, graph-completeness caveats, and inference guidance |
437
+ | `usage-guide` | Orientation guide covering graph structure, read and write workflow, output-format choices, graph-completeness caveats, and inference guidance |
337
438
 
338
439
  ## Contributing
339
440
 
@@ -1,6 +1,22 @@
1
1
  import { QueryError } from '../schema/index.js';
2
2
  import { CORE_EDGE_TYPE_MAP } from '../loader/constants.js';
3
+ import { buildAliasMap, resolveAlias } from '../mutate/alias.js';
3
4
  import { getDataTemplates, getStructuralTemplates, templateHasRole } from './roles.js';
5
+ /**
6
+ * Lazily-built alias resolver over a graph's `renamed-from` trail edges
7
+ * (design §5): retired IDs resolve to their live node. Live IDs
8
+ * short-circuit without building the map; the map is built at most once per
9
+ * resolver — create one per query call, never per edge.
10
+ */
11
+ export function createAliasResolver(graph) {
12
+ let aliasMap;
13
+ return (id) => {
14
+ if (graph.nodesById.has(id))
15
+ return id;
16
+ aliasMap ??= buildAliasMap(graph);
17
+ return resolveAlias(graph, aliasMap, id);
18
+ };
19
+ }
4
20
  /** Templates whose nodes are structural children, derived from declared template roles. */
5
21
  export function getStructuralNodeTemplates(graph) {
6
22
  return getStructuralTemplates(graph.templates);
@@ -178,22 +194,33 @@ export function expandExternalNodes(graph, externalIds) {
178
194
  .filter((node) => node !== undefined);
179
195
  }
180
196
  export function getLinkedFields(graph, nodeId) {
181
- const root = graph.nodesById.get(nodeId);
197
+ const resolveLive = createAliasResolver(graph);
198
+ const rootId = resolveLive(nodeId);
199
+ const root = graph.nodesById.get(rootId);
182
200
  if (!root)
183
201
  throw new QueryError(`Node not found: ${nodeId}`);
184
- const prefix = `${nodeId}.`;
202
+ const prefix = `${rootId}.`;
185
203
  const ownedFieldIds = new Set([...graph.nodesById.entries()]
186
204
  .filter(([id, node]) => id.startsWith(prefix) && templateHasRole(graph.templates, node.template, 'field'))
187
205
  .map(([id]) => id));
188
206
  const edges = [];
189
207
  const nodeIds = new Set();
190
208
  const seen = new Set();
191
- for (const fieldId of ownedFieldIds) {
192
- for (const edge of graph.edgesByFrom.get(fieldId) ?? []) {
193
- collectMapsTo(edge, edges, nodeIds, seen);
194
- }
195
- for (const edge of graph.edgesByTo.get(fieldId) ?? []) {
196
- collectMapsTo(edge, edges, nodeIds, seen);
209
+ // Scan maps-to edges with alias-resolved endpoints (design §5): an edge
210
+ // still referencing a retired field ID links to the live field rather than
211
+ // dangling. Edges are returned as authored; node IDs are the live ones.
212
+ for (const edgeList of graph.edgesByFrom.values()) {
213
+ for (const edge of edgeList) {
214
+ if (edge.type !== 'maps-to' || seen.has(edge.id))
215
+ continue;
216
+ const from = resolveLive(edge.from);
217
+ const to = resolveLive(edge.to);
218
+ if (!ownedFieldIds.has(from) && !ownedFieldIds.has(to))
219
+ continue;
220
+ edges.push(edge);
221
+ seen.add(edge.id);
222
+ nodeIds.add(from);
223
+ nodeIds.add(to);
197
224
  }
198
225
  }
199
226
  return {
@@ -220,14 +247,6 @@ function findParent(graph, nodeId) {
220
247
  }
221
248
  return undefined;
222
249
  }
223
- function collectMapsTo(edge, edges, nodeIds, seen) {
224
- if (edge.type !== 'maps-to' || seen.has(edge.id))
225
- return;
226
- edges.push(edge);
227
- nodeIds.add(edge.from);
228
- nodeIds.add(edge.to);
229
- seen.add(edge.id);
230
- }
231
250
  const OVERLAY_EXCLUDED = new Set(['local', 'shared']);
232
251
  export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRootId) {
233
252
  const overlay = multi.overlay(viewingRef);
@@ -377,6 +396,10 @@ export function getLineage(graph, startNodeIds, options = {}) {
377
396
  return !excludedTemplates.has(node.template);
378
397
  return true;
379
398
  }
399
+ // Alias resolution (design §5): retired IDs — stale start IDs and edge
400
+ // endpoints referencing pre-rename names — resolve to the live node instead
401
+ // of dangling. The resolver builds the alias map at most once per call.
402
+ const resolveLive = createAliasResolver(graph);
380
403
  const annotations = new Map();
381
404
  const originSets = new Map();
382
405
  function tryRecord(nodeId, originId, resultDepth, viaEdgeType, viaNodeId, dir) {
@@ -391,7 +414,7 @@ export function getLineage(graph, startNodeIds, options = {}) {
391
414
  originSets.get(nodeId)?.add(originId);
392
415
  return true;
393
416
  }
394
- const validStartIds = startNodeIds.filter(id => graph.nodesById.has(id));
417
+ const validStartIds = [...new Set(startNodeIds.map(resolveLive))].filter(id => graph.nodesById.has(id));
395
418
  const startSet = new Set(validStartIds);
396
419
  function runDownstream() {
397
420
  const visited = new Set(startSet);
@@ -405,16 +428,17 @@ export function getLineage(graph, startNodeIds, options = {}) {
405
428
  for (const edge of graph.edgesByFrom.get(current.id) ?? []) {
406
429
  if (!edgeTypeSet.has(edge.type))
407
430
  continue;
408
- const node = graph.nodesById.get(edge.to);
431
+ const toId = resolveLive(edge.to);
432
+ const node = graph.nodesById.get(toId);
409
433
  if (!node || !isIncluded(node))
410
434
  continue;
411
- if (visited.has(edge.to)) {
412
- originSets.get(edge.to)?.add(current.originId);
435
+ if (visited.has(toId)) {
436
+ originSets.get(toId)?.add(current.originId);
413
437
  continue;
414
438
  }
415
- visited.add(edge.to);
416
- tryRecord(edge.to, current.originId, current.distance + 1, edge.type, current.id, 'downstream');
417
- queue.push({ id: edge.to, originId: current.originId, distance: current.distance + 1 });
439
+ visited.add(toId);
440
+ tryRecord(toId, current.originId, current.distance + 1, edge.type, current.id, 'downstream');
441
+ queue.push({ id: toId, originId: current.originId, distance: current.distance + 1 });
418
442
  }
419
443
  }
420
444
  }
@@ -430,16 +454,17 @@ export function getLineage(graph, startNodeIds, options = {}) {
430
454
  for (const edge of graph.edgesByTo.get(current.id) ?? []) {
431
455
  if (!inboundTypeSet.has(edge.type))
432
456
  continue;
433
- const node = graph.nodesById.get(edge.from);
457
+ const fromId = resolveLive(edge.from);
458
+ const node = graph.nodesById.get(fromId);
434
459
  if (!node || !isIncluded(node))
435
460
  continue;
436
- if (visited.has(edge.from)) {
437
- originSets.get(edge.from)?.add(current.originId);
461
+ if (visited.has(fromId)) {
462
+ originSets.get(fromId)?.add(current.originId);
438
463
  continue;
439
464
  }
440
- visited.add(edge.from);
441
- tryRecord(edge.from, current.originId, current.distance + 1, edge.type, current.id, 'upstream');
442
- queue.push({ id: edge.from, originId: current.originId, distance: current.distance + 1 });
465
+ visited.add(fromId);
466
+ tryRecord(fromId, current.originId, current.distance + 1, edge.type, current.id, 'upstream');
467
+ queue.push({ id: fromId, originId: current.originId, distance: current.distance + 1 });
443
468
  }
444
469
  const parentId = findParent(graph, current.id);
445
470
  if (parentId) {
@@ -464,22 +489,27 @@ export function getLineage(graph, startNodeIds, options = {}) {
464
489
  const combinedSet = new Set([...startSet, ...resultNodeIds]);
465
490
  const edges = [];
466
491
  const seenEdgeIds = new Set();
492
+ const nodesWithEdges = new Set();
467
493
  for (const id of combinedSet) {
468
494
  for (const edge of graph.edgesByFrom.get(id) ?? []) {
469
495
  if (seenEdgeIds.has(edge.id) || !edgeTypeSet.has(edge.type))
470
496
  continue;
471
- if (combinedSet.has(edge.from) && combinedSet.has(edge.to)) {
497
+ // Endpoints resolve through the alias map so an edge referencing a
498
+ // retired ID still connects to the live node it was traversed to.
499
+ const from = resolveLive(edge.from);
500
+ const to = resolveLive(edge.to);
501
+ if (combinedSet.has(from) && combinedSet.has(to)) {
472
502
  edges.push(edge);
473
503
  seenEdgeIds.add(edge.id);
504
+ nodesWithEdges.add(from);
505
+ nodesWithEdges.add(to);
474
506
  }
475
507
  }
476
508
  }
477
- const nodesWithEdges = new Set();
478
- for (const edge of edges) {
479
- nodesWithEdges.add(edge.from);
480
- nodesWithEdges.add(edge.to);
481
- }
482
- const prunedIds = new Set([...resultNodeIds].filter(id => nodesWithEdges.has(id)));
509
+ // Keep parent-hop ancestors even when they were reached through the
510
+ // synthetic upstream parent traversal and therefore have no concrete edge
511
+ // object in the result edge set.
512
+ const prunedIds = new Set([...resultNodeIds].filter(id => nodesWithEdges.has(id) || annotations.get(id)?.viaEdgeType === 'parent'));
483
513
  let danglingEdges;
484
514
  if (includeDanglingEdges) {
485
515
  danglingEdges = [];
@@ -490,7 +520,9 @@ export function getLineage(graph, startNodeIds, options = {}) {
490
520
  continue;
491
521
  if (!edgeTypeSet.has(edge.type))
492
522
  continue;
493
- const otherId = edge.from === id ? edge.to : edge.from;
523
+ const from = resolveLive(edge.from);
524
+ const to = resolveLive(edge.to);
525
+ const otherId = from === id ? to : from;
494
526
  if (!combinedSet.has(otherId)) {
495
527
  danglingEdges.push(edge);
496
528
  danglingSeenIds.add(edge.id);
@@ -1,14 +1,35 @@
1
1
  import { QueryError } from '../schema/index.js';
2
+ import { createAliasResolver, getEdgeTypeDef } from './index.js';
2
3
  export function computeOverlay(viewingRef, defaultBranch, allBranches) {
3
4
  const branches = uniqueBranches([defaultBranch, ...allBranches]);
4
- if (!branches.some(branch => branch.ref === viewingRef)) {
5
+ const viewingBranch = branches.find(branch => branch.ref === viewingRef);
6
+ if (!viewingBranch) {
5
7
  throw new QueryError(`branch '${viewingRef}' not found in loaded branches`);
6
8
  }
9
+ // Foreign IDs resolve through the viewing branch's alias map (design §5/§14b)
10
+ // so a branch still holding a retired ID overlays onto the renamed node.
11
+ const resolve = createAliasResolver(viewingBranch.graph);
12
+ // Per-branch node index keyed by canonical (viewing-resolved) ID.
13
+ const nodeIndexes = new Map();
14
+ const canonicalNodeIds = new Set();
15
+ for (const branch of branches) {
16
+ const index = new Map();
17
+ for (const [id, node] of branch.graph.nodesById) {
18
+ const canonicalId = branch.ref === viewingRef ? id : resolve(id);
19
+ // On collision (branch holds both a retired and its live ID), the node
20
+ // whose literal ID matches the canonical ID wins.
21
+ const existing = index.get(canonicalId);
22
+ if (existing === undefined || node.id === canonicalId)
23
+ index.set(canonicalId, node);
24
+ canonicalNodeIds.add(canonicalId);
25
+ }
26
+ nodeIndexes.set(branch.ref, index);
27
+ }
7
28
  const nodes = new Map();
8
- for (const id of collectNodeIds(branches)) {
29
+ for (const id of canonicalNodeIds) {
9
30
  const presence = new Map();
10
31
  for (const branch of branches) {
11
- const node = branch.graph.nodesById.get(id);
32
+ const node = nodeIndexes.get(branch.ref)?.get(id);
12
33
  if (node)
13
34
  presence.set(branch.ref, node);
14
35
  }
@@ -18,11 +39,33 @@ export function computeOverlay(viewingRef, defaultBranch, allBranches) {
18
39
  ghostState: classifyPresence(viewingRef, defaultBranch.ref, presence, nodesEqual),
19
40
  });
20
41
  }
42
+ // Per-branch edge index keyed by canonical edge ID: endpoints are resolved
43
+ // through the viewing branch's alias map and the composite ID recomputed, so
44
+ // a foreign edge whose endpoints are retired IDs matches the viewing
45
+ // branch's rewritten edge. Hidden edge types (renamed-from bookkeeping) keep
46
+ // their literal IDs — their `to` is a retired ID by design.
47
+ const edgeIndexes = new Map();
48
+ const canonicalEdgeIds = new Set();
49
+ for (const branch of branches) {
50
+ const index = new Map();
51
+ for (const edgeList of branch.graph.edgesByFrom.values()) {
52
+ for (const edge of edgeList) {
53
+ const canonicalId = branch.ref === viewingRef
54
+ ? edge.id
55
+ : canonicalEdgeId(viewingBranch.graph, edge, resolve);
56
+ const existing = index.get(canonicalId);
57
+ if (existing === undefined || edge.id === canonicalId)
58
+ index.set(canonicalId, edge);
59
+ canonicalEdgeIds.add(canonicalId);
60
+ }
61
+ }
62
+ edgeIndexes.set(branch.ref, index);
63
+ }
21
64
  const edges = new Map();
22
- for (const id of collectEdgeIds(branches)) {
65
+ for (const id of canonicalEdgeIds) {
23
66
  const presence = new Map();
24
67
  for (const branch of branches) {
25
- const edge = findEdge(branch, id);
68
+ const edge = edgeIndexes.get(branch.ref)?.get(id);
26
69
  if (edge)
27
70
  presence.set(branch.ref, edge);
28
71
  }
@@ -34,24 +77,54 @@ export function computeOverlay(viewingRef, defaultBranch, allBranches) {
34
77
  }
35
78
  return { viewingRef, nodes, edges };
36
79
  }
80
+ function canonicalEdgeId(viewingGraph, edge, resolve) {
81
+ if (getEdgeTypeDef(viewingGraph, edge.type)?.hidden === true)
82
+ return edge.id;
83
+ const from = resolve(edge.from);
84
+ const to = resolve(edge.to);
85
+ if (from === edge.from && to === edge.to)
86
+ return edge.id;
87
+ return `${from}__${edge.type}__${to}`;
88
+ }
37
89
  export function computeDiff(branch, defaultBranch) {
38
90
  const added = [];
39
91
  const modified = [];
40
92
  const removed = [];
93
+ const warnings = [];
94
+ // Branch IDs resolve through the viewing (default) graph's alias map
95
+ // (design §5/§14b): a branch still holding a retired ID diffs against the
96
+ // renamed node instead of appearing as unrelated add+remove.
97
+ const resolve = createAliasResolver(defaultBranch.graph);
98
+ const matchedDefaultIds = new Set();
41
99
  for (const [id, node] of branch.graph.nodesById) {
42
- const defaultNode = defaultBranch.graph.nodesById.get(id);
100
+ const resolvedId = resolve(id);
101
+ const defaultNode = defaultBranch.graph.nodesById.get(resolvedId);
43
102
  if (!defaultNode) {
44
103
  added.push(node);
104
+ continue;
45
105
  }
46
- else if (!nodesEqual(node, defaultNode)) {
106
+ matchedDefaultIds.add(resolvedId);
107
+ const equal = nodesEqual(node, defaultNode);
108
+ if (!equal) {
47
109
  modified.push(node);
110
+ if (resolvedId !== id) {
111
+ warnings.push({
112
+ kind: 'retired-name-edit',
113
+ branchId: id,
114
+ resolvedId,
115
+ message: `branch edits retired name '${id}' (renamed to '${resolvedId}' on the default branch) — rebase or apply the rename`,
116
+ });
117
+ }
48
118
  }
49
119
  }
50
120
  for (const [id, node] of defaultBranch.graph.nodesById) {
51
- if (!branch.graph.nodesById.has(id))
121
+ if (!branch.graph.nodesById.has(id) && !matchedDefaultIds.has(id))
52
122
  removed.push(node);
53
123
  }
54
- return { added, modified, removed };
124
+ const diff = { added, modified, removed };
125
+ if (warnings.length > 0)
126
+ diff.warnings = warnings;
127
+ return diff;
55
128
  }
56
129
  function classifyPresence(viewingRef, defaultRef, presence, equal) {
57
130
  const viewingItem = presence.get(viewingRef);
@@ -72,16 +145,39 @@ function classifyPresence(viewingRef, defaultRef, presence, equal) {
72
145
  return first && otherItems.every(item => equal(first, item)) ? 'ghost-consensus' : 'ghost-conflict';
73
146
  }
74
147
  function nodesEqual(a, b) {
75
- return deepEqual(a.properties, b.properties)
148
+ return deepEqual(comparableProperties(a), comparableProperties(b))
149
+ && deepEqual(comparableCorum(a), comparableCorum(b))
76
150
  && a.state === b.state
77
151
  && a.stability === b.stability;
78
152
  }
153
+ /**
154
+ * `corum.identity.previousIds` is system-owned rename bookkeeping (design §3): a branch
155
+ * predating a rename lacks it, and that alone must not read as a content
156
+ * difference — an untouched carry-over stays equal to the renamed node.
157
+ */
158
+ function comparableProperties(node) {
159
+ return node.properties;
160
+ }
79
161
  function edgesEqual(a, b) {
80
162
  return a.type === b.type
81
163
  && a.state === b.state
82
164
  && a.stability === b.stability
83
165
  && a.notes === b.notes;
84
166
  }
167
+ // Return the subset of Corum-owned bookkeeping that should count for overlay equality.
168
+ // Rename history (`corum.identity.previousIds`) is intentionally excluded so pre/post-rename
169
+ // branches do not look content-different when the user-authored node data is otherwise identical.
170
+ function comparableCorum(node) {
171
+ if (node.corum === undefined)
172
+ return undefined;
173
+ const identity = node.corum.identity === undefined
174
+ ? undefined
175
+ : Object.fromEntries(Object.entries(node.corum.identity).filter(([key]) => key !== 'previousIds'));
176
+ const rest = Object.fromEntries(Object.entries(node.corum).filter(([key]) => key !== 'identity'));
177
+ if (identity !== undefined && Object.keys(identity).length > 0)
178
+ rest.identity = identity;
179
+ return Object.keys(rest).length > 0 ? rest : undefined;
180
+ }
85
181
  function deepEqual(a, b) {
86
182
  if (Object.is(a, b))
87
183
  return true;
@@ -108,29 +204,3 @@ function uniqueBranches(branches) {
108
204
  }
109
205
  return [...byRef.values()];
110
206
  }
111
- function collectNodeIds(branches) {
112
- const ids = new Set();
113
- for (const branch of branches) {
114
- for (const id of branch.graph.nodesById.keys())
115
- ids.add(id);
116
- }
117
- return ids;
118
- }
119
- function collectEdgeIds(branches) {
120
- const ids = new Set();
121
- for (const branch of branches) {
122
- for (const edgeList of branch.graph.edgesByFrom.values()) {
123
- for (const edge of edgeList)
124
- ids.add(edge.id);
125
- }
126
- }
127
- return ids;
128
- }
129
- function findEdge(branch, edgeId) {
130
- for (const edgeList of branch.graph.edgesByFrom.values()) {
131
- const edge = edgeList.find(item => item.id === edgeId);
132
- if (edge)
133
- return edge;
134
- }
135
- return undefined;
136
- }
@@ -4,7 +4,8 @@ import { loadGraph } from '../loader/index.js';
4
4
  import { isStructuralEdgeType } from '../graph/index.js';
5
5
  import { serializeGraph } from '../writer/graph-writer.js';
6
6
  import { getAdapter } from '../adapters/index.js';
7
- import { diffNodes } from '../reconcile/index.js';
7
+ import { diffNodes, detectPossibleRenames, resolveIncomingAliases } from '../reconcile/index.js';
8
+ import { buildAliasMap } from '../mutate/alias.js';
8
9
  import { deduplicateResults } from './dedup.js';
9
10
  import { buildExistingSchemaIndex, detectSchemaPromotions, rewritePromotedSchemaEdges } from './schema-promotion.js';
10
11
  import { resolveEdgeCasing } from './edge-casing.js';
@@ -68,6 +69,16 @@ export async function runImport(config, runtimeConfig, options = {}) {
68
69
  allDiagnostics.push(...diagnostics);
69
70
  entryResults.splice(0, entryResults.length, ...deduped);
70
71
  }
72
+ // Design §6a: resolve incoming IDs through the target graph's rename-trail
73
+ // alias map before diffing, so specs still using retired names merge into
74
+ // the renamed nodes (reported as in-flight drift, not add+remove).
75
+ const aliasMap = buildAliasMap(graph);
76
+ for (const er of entryResults) {
77
+ const { nodes, edges, diagnostics } = resolveIncomingAliases(graph, aliasMap, er.nodes, er.edges, er.specPath);
78
+ er.nodes = nodes;
79
+ er.edges = edges;
80
+ allDiagnostics.push(...diagnostics);
81
+ }
71
82
  const newlyCreatedSchemaIds = new Set();
72
83
  for (const er of entryResults) {
73
84
  for (const node of er.nodes) {
@@ -79,8 +90,11 @@ export async function runImport(config, runtimeConfig, options = {}) {
79
90
  // Merge every entry's nodes first, so casing resolution below sees the
80
91
  // fully-merged node set regardless of import order among entries.
81
92
  for (const er of entryResults) {
82
- const { toAdd, toUpdate, toRemove } = diffNodes(er.nodes, graph.nodesById, er.specPath);
83
- for (const node of [...toAdd, ...toUpdate, ...toRemove]) {
93
+ const diff = diffNodes(er.nodes, graph.nodesById, er.specPath);
94
+ // Design §6a: warning-only rename suggestion (delete+add, same parent +
95
+ // template). Renames stay explicit via rename_node.
96
+ allDiagnostics.push(...detectPossibleRenames(diff, er.specPath));
97
+ for (const node of [...diff.toAdd, ...diff.toUpdate, ...diff.toRemove]) {
84
98
  graph.nodesById.set(node.id, node);
85
99
  }
86
100
  }