# Plan: Edge Semantics (provenance + typed rel- edges) - IMPLEMENTED (branch edge-semantics, 2026-07-13) Fills the "Edge semantics: give edges more information" roadmap gap from the 2026-07-13 knowledge-layer analysis. Implemented in one changeset on branch `edge-semantics`; awaiting commit + PR. ## What shipped Two halves, zero server/protocol/store changes: 1. **Edge provenance**: every crawled edge carries the link's label text, the source section anchor it appears under, and an occurrence count. Duplicate links between the same pair aggregate into one counted edge; first non-empty label wins. 2. **Typed relations**: publisher-metadata convention `rel-` (hyphen, never colon; metadata keys allow only `[a-z0-9-]`), CSV values resolved against the doc URL, ingested by both crawlers as typed edges. Malformed refs, self-refs, and empty predicates are skipped silently. ## Design decisions - Edge identity is {From, To, Rel}; plain body links have Rel "". A plain link and a typed relation between the same pair are two distinct edges. - Store Merge is last-crawl-wins for Label/Anchor/Count (mirrors node upserts): idempotent, counts never inflate. - graph.json schema stays v1 (new StoredEdge fields are omitempty; legacy files load with Count normalized to 1). - /graph.md Edges table widened to `| From | To | Rel | Label | Anchor | Count |`; ParseExport accepts both this and the legacy 2-column row. - One shared annotation renderer `graph.EdgeAnnotation` (` [supersedes]`, ` ("Getting started", #intro, x3)`) used by client MCP, broker MCP, and both backlink lists; pinned-literal tests on both sides guard drift. - Fetch callback widened to a struct returning `(graph.FetchResult, error)` with a Metadata field; this also paid the /debt.md "Crawl fetcher callback returns four positional values" item and deleted the caller-less `graph.ClientFetcher` adapter. - Shared enriched extraction lives in `client/mdoutline.AnchoredLinks` (mdoutline already imports links, so links could not host it without a cycle). ## Touched surfaces client/mdoutline (new AnchoredLinks), client/graph (Edge fields, AddEdgeInfo aggregation, EdgeAnnotation, RelEdges parser, crawl enrichment), client/graphstore (StoredEdge, Merge, BacklinkEntry enrichment, dual-format export/parse), client/internal/fedcrawl (recordEdges via AnchoredLinks + RelEdges with existing loopback/normalize filters), demarkus-mcp (formatGraph, backlinks, explore, tool descriptions), broker (same surfaces + MCP-API.md), docs (ADR 0004, DESIGN.md, agent-cookbook). ## Verification done - Full test suites green in client and tools modules; `bash pre-commit.sh` clean. - Live e2e: dev server on :6399, published `adr.md` with `-meta rel-supersedes=/old.md` and a twice-linked doc under a `## Context` heading; crawl produced `| adr.md | design.md | | design doc | context | 2 |` and `| adr.md | old.md | supersedes | | | 1 |`. - Legacy compat live: the real pre-change ~/.mark/graph.json (133 nodes / 190 edges) loads and exports through the new binary with Count normalized to 1. ## Follow-ups - Surface labels/rels in the TUI graph view (deliberately deferred this round). - When publish-time edge extraction lands in the store backends, capture the same fields; conformance suite first per the backend-parity principle. - Consider a curated rel- predicate vocabulary in the plugins (supersedes, implements, depends-on, derived-from). See repo `docs/adr/0004-edge-semantics-rel-convention.md` for the full decision record. ## PR 251 review round (CodeRabbit, 2026-07-13) Four of five findings addressed, one declined: - Fixed: RelEdges now rejects any internal whitespace via unicode.IsSpace (newlines from a hostile or broken remote server no longer pass). - Fixed (the sharp one): Merge now replaces the stored outgoing edge set for every source the crawl actually fetched, so deleted links and dropped rel- predicates no longer linger in backlink queries. External/error sources keep their stored edges. This stale-edge behavior predated the PR but the enrichment made it worth fixing here. ADR 0004 updated. - Fixed: empty-label links keep section provenance; LinkInfo gains BlockStart (enclosing block start, valid even when brackets are unknown; headings cannot split a block, so it is section-accurate). Bracket positions stay -1 so the TUI marker-injection contract is untouched. - Fixed: AnchoredLinks heading attribution is now a binary search per link instead of a rescan. - Declined: bumping graph.json schemaVersion to 2 for the enriched edges. The file is a rebuildable crawl cache, not a source of truth; an old binary reading a new file degrades gracefully (drops enrichment, output identical to pre-feature) and any loss is repaired by the next crawl, while a version bump would make every old binary hard-reject the file. The version exists for breaking shape changes, and this one is additive. ## PR 251 review round 2 (CodeRabbit, 2026-07-13) - Fixed (critical, real): the BlockStart ancestor walk called p.Lines() on inline parents, and goldmark's BaseInline.Lines() panics by contract, so any link wrapped in emphasis (`**[text](url)**`) crashed extraction. Guard with p.Type() == ast.TypeBlock. Reproduced the panic against the committed code with a new test before fixing (test fails pre-fix, passes post-fix). Regression coverage added at all three levels: links (link inside bold), mdoutline (bold and italic wrapped links), crawl (bold link records label and anchor). - Declined: debug-level log for skipped malformed rel- refs. RelEdges is a pure function with no logging dependency; the skip rules are deterministic and documented in code and ADR 0004; CodeRabbit itself rated it low value. - Duplicate schema-bump comment: prior decline stands (rebuildable cache, additive omitempty fields, hard version bump is the worse failure mode). Lesson: when a helper walks AST ancestors, test links nested inside inline formatting; the first review's tests only covered formatting inside links, not links inside formatting.