md quick-scan and semantic extraction mint duplicate document nodes for the same file: bare slug vs slug_doc

[jerp86]

Summary

When a corpus file has been through semantic extraction (producing a document node with the _doc suffix, e.g. docs_xmap_language_reference_doc) and a later graphify update runs the markdown quick-scan over the same corpus, the quick-scan mints a second file-level node under the bare slug (docs_xmap_language_reference) instead of reusing the existing _doc node. Every markdown document ends up as two disconnected nodes with the graph's edges split between them.

Environment

• graphify 0.9.12 (reproduced today after upgrading from 0.9.9, where it also occurred)
• macOS, TS/React repo with docs/*.md corpus previously extracted semantically (host-agent pipeline, no API key)

Reproduction

1. Full build with semantic extraction over a repo containing docs/xmap/*.md → each doc becomes <slug>_doc (e.g. docs_xmap_readme_doc), with semantic references edges to code.
2. Run graphify update . (AST-only path).
3. Inspect graph.json:

docs_xmap_language_reference: bare=YES | _doc=YES
docs_xmap_readme:             bare=YES | _doc=YES
docs_xmap_quickstart:         bare=YES | _doc=YES
docs_xmap_style_reference:    bare=YES | _doc=YES

4/4 markdown docs checked are duplicated (systematic, not incidental).

Observed edge split

The two nodes partition the file's relationships:

• the bare node receives the md quick-scan's cross-link edges (e.g. docs_xmap_readme → docs_xmap_language_reference, docs_xmap_quickstart → docs_xmap_language_reference, plus fragment edges like docs_xmap_language_reference → docs_xmap_language_reference_referência_da_linguagem_xmap);
• the _doc node keeps the semantic-extraction edges (references to real code symbols, membership in hyperedges such as a documentation reading-path).

Consequences: path/query traversals starting from one twin miss the other twin's neighborhood (a docs→code path query dead-ends on the bare node), community detection clusters the twins separately, and doc-file degree/centrality is split roughly in half.

Expected

The quick-scan should resolve to the existing _doc node (or both extractors should agree on one canonical ID scheme for file-level document nodes), so a document file is one node regardless of which pipeline touched it last.

Notes

• Searched existing issues for duplicates (doc suffix id, duplicate document node, markdown link extractor) — closest matches (Extraction noise: scope-blind identifier collision + over-eager markdown fragment nodes #1077 fragment nodes, [Feature Request] Cross-domain edge generation: AST↔semantic subgraph bridging (+ alignment solution) #1254 AST↔semantic bridging) describe different problems.
• Possibly related in spirit to build_from_json(): non-AST ghost-node merge picks winner via set iteration order (non-deterministic across process runs) #1753's ghost-node merge determinism work, since this is also a "two IDs for one entity" class of issue, but the mismatch here is deterministic by design (two extractors, two schemes).

[safishamsi]

Fixed on v8 (0.9.13), credited to you. build_from_json now merges the markdown quick-scan's bare <slug> node into the semantic <slug>_doc node when both share the same source_file and are file_type: document, consolidating their edges (and hyperedges) onto one canonical node — so a document is one node regardless of which pipeline touched it last, and a docs->code path query no longer dead-ends on the bare twin. Kept it safe: an unrelated code symbol foo / foo_doc won't merge (gated to document twins for the same file). Verified on your bare-vs-_doc scenario + a code-symbol control; regression tests added. Thanks for the precise breakdown of the edge split.