@atolis-hq/corum 0.1.44 → 0.1.46
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 +111 -9
- package/dist/src/graph/index.js +69 -37
- package/dist/src/graph/overlay.js +106 -36
- package/dist/src/import/runner.js +17 -3
- package/dist/src/linter/index.js +242 -106
- package/dist/src/loader/cluster-loader.js +36 -3
- package/dist/src/loader/edge-loader.js +8 -2
- package/dist/src/mcp/index.js +633 -142
- package/dist/src/mcp/prompts/usage-guide.js +73 -65
- package/dist/src/mutate/alias.js +68 -0
- package/dist/src/mutate/apply-cluster.js +255 -0
- package/dist/src/mutate/delete.js +47 -0
- package/dist/src/mutate/errors.js +14 -0
- package/dist/src/mutate/index.js +11 -0
- package/dist/src/mutate/rename.js +135 -0
- package/dist/src/mutate/session.js +551 -0
- package/dist/src/mutate/util.js +62 -0
- package/dist/src/reconcile/index.js +126 -3
- package/dist/src/source/file-source.js +64 -15
- package/dist/src/source/git-source.js +121 -31
- package/dist/src/writer/graph-writer.js +64 -10
- package/package.json +2 -1
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
|
|
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
|
|
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
|
|
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` |
|
|
239
|
-
| `git_poll_seconds` | `CORUM_GIT_POLL_SECONDS` |
|
|
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,8 +359,21 @@ 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 |
|
|
313
|
-
|
|
314
|
-
|
|
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_edges` | Batch-create explicit edges as one atomic operation |
|
|
369
|
+
| `update_edge` | Patch an explicit edge |
|
|
370
|
+
| `delete_edge` | Delete an explicit edge |
|
|
371
|
+
| `create_fields` | Batch-create fields across schemas (grouped and applied per parent) |
|
|
372
|
+
| `pending_changes` | Show the open session's journal and summary diff |
|
|
373
|
+
| `discard_changes` | Abort the working session |
|
|
374
|
+
| `commit_changes` | Lint, serialize, and persist the session's changes |
|
|
375
|
+
|
|
376
|
+
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.
|
|
315
377
|
|
|
316
378
|
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.
|
|
317
379
|
|
|
@@ -320,20 +382,60 @@ Common notes:
|
|
|
320
382
|
- `list_nodes` is a breaking-change surface from older builds: use `filter.templates` instead of top-level `template`.
|
|
321
383
|
- `search_nodes` accepts `queries: string[]`.
|
|
322
384
|
- `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.
|
|
385
|
+
- `get_graph_metadata` returns `valid_edge_types`, `states`, `stabilities`, `lineage_directions`, and `output_formats` when you pass `include_static_enums: true`.
|
|
323
386
|
- Prefer `search_nodes` over `list_nodes` for discovery. Use `list_nodes` when you need a full inventory under explicit filters.
|
|
324
387
|
- `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
388
|
- `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
389
|
- Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.
|
|
327
390
|
- 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.
|
|
391
|
+
- 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
392
|
- 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
393
|
|
|
394
|
+
## MCP Write Workflow
|
|
395
|
+
|
|
396
|
+
Corum's write tools are session-based:
|
|
397
|
+
|
|
398
|
+
1. Call `start_changes`.
|
|
399
|
+
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`.
|
|
400
|
+
3. Inspect the session with `pending_changes`.
|
|
401
|
+
4. Finish with `commit_changes` or abort with `discard_changes`.
|
|
402
|
+
|
|
403
|
+
Important behavior:
|
|
404
|
+
- No write tool works without an open session.
|
|
405
|
+
- `rename_node` is the only rename path. `apply_cluster` and imports never infer renames.
|
|
406
|
+
- `apply_cluster` `replace` mode is authoritative for the root's owned sections: absent children are deleted, and an absent owned section means "empty section".
|
|
407
|
+
- `delete_node` defaults to soft delete for nodes that already exist on the default branch, and hard delete for branch-local design work.
|
|
408
|
+
- `discard_changes` closes the session. On file-backed autosave sessions it does not roll back mutations already written through to disk.
|
|
409
|
+
|
|
410
|
+
Source-mode defaults:
|
|
411
|
+
- Filesystem source: `start_changes` defaults `autosave` on. Each mutation writes through immediately; `commit_changes` mainly lint-gates and closes the session.
|
|
412
|
+
- Git source: `start_changes` defaults `autosave` off. Changes stay in memory until `commit_changes`.
|
|
413
|
+
- Git source with `autosave: true`: each mutation creates a `corum-wip:` checkpoint commit; `commit_changes` squashes that run when no external commit interleaved.
|
|
414
|
+
|
|
415
|
+
Typical sequence:
|
|
416
|
+
|
|
417
|
+
```yaml
|
|
418
|
+
start_changes:
|
|
419
|
+
branch: feat/order-design
|
|
420
|
+
create: true
|
|
421
|
+
|
|
422
|
+
rename_node:
|
|
423
|
+
id: orders.Schema.invoice
|
|
424
|
+
new_name: bill
|
|
425
|
+
|
|
426
|
+
pending_changes: {}
|
|
427
|
+
|
|
428
|
+
commit_changes:
|
|
429
|
+
message: rename invoice schema to bill
|
|
430
|
+
```
|
|
431
|
+
|
|
330
432
|
## MCP Prompts
|
|
331
433
|
|
|
332
434
|
The server also exposes a discoverable MCP prompt:
|
|
333
435
|
|
|
334
436
|
| Prompt | Description |
|
|
335
437
|
|---|---|
|
|
336
|
-
| `usage-guide` | Orientation guide covering graph structure,
|
|
438
|
+
| `usage-guide` | Orientation guide covering graph structure, read and write workflow, output-format choices, graph-completeness caveats, and inference guidance |
|
|
337
439
|
|
|
338
440
|
## Contributing
|
|
339
441
|
|
package/dist/src/graph/index.js
CHANGED
|
@@ -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
|
|
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 = `${
|
|
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
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
for (const edge of
|
|
196
|
-
|
|
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
|
|
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(
|
|
412
|
-
originSets.get(
|
|
435
|
+
if (visited.has(toId)) {
|
|
436
|
+
originSets.get(toId)?.add(current.originId);
|
|
413
437
|
continue;
|
|
414
438
|
}
|
|
415
|
-
visited.add(
|
|
416
|
-
tryRecord(
|
|
417
|
-
queue.push({ id:
|
|
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
|
|
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(
|
|
437
|
-
originSets.get(
|
|
461
|
+
if (visited.has(fromId)) {
|
|
462
|
+
originSets.get(fromId)?.add(current.originId);
|
|
438
463
|
continue;
|
|
439
464
|
}
|
|
440
|
-
visited.add(
|
|
441
|
-
tryRecord(
|
|
442
|
-
queue.push({ id:
|
|
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
|
-
|
|
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
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
29
|
+
for (const id of canonicalNodeIds) {
|
|
9
30
|
const presence = new Map();
|
|
10
31
|
for (const branch of branches) {
|
|
11
|
-
const node = branch.
|
|
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
|
|
65
|
+
for (const id of canonicalEdgeIds) {
|
|
23
66
|
const presence = new Map();
|
|
24
67
|
for (const branch of branches) {
|
|
25
|
-
const edge =
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
83
|
-
|
|
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
|
}
|