Knowledge-Graph Merge

The failure it prevents

Every system that extracts facts from documents eventually writes the same entity twice — two emails, two PDFs, two extractors, a human typing over the top.

The naive merge is `{...existing, ...incoming}`. The last writer wins, so a low-confidence guess pulled from a page-three footer silently overwrites a fact a person entered by hand. Nothing errors. Nothing logs. The only trace is that the answer is different now.

The rules it enforces

1. Aliases and source references are append-only. Evidence accumulates; a merge never trades it away. 2. High confidence is never overwritten by low. 3. Human-entered data outranks any extractor — and `createdBy` is immutable, because a later automated write that relabels the record would switch the rule off for exactly the rows it exists for. 4. A real disagreement is recorded, not resolved. Two high-confidence sources that differ keep the existing value and append a conflict record for a human. 5. Confidence is monotonically non-decreasing. One low-confidence touch cannot downgrade a well-attested node out from under everything that thresholds on it. 6. Visibility narrows, never widens. The most restrictive wins — the one rule here with a disclosure consequence, so it fails closed. 7. A pinned node still accumulates provenance. Declaring a node canonical freezes its name and properties, not the evidence trail that lets anyone check it.

Your ontology, not ours

Node and edge type vocabularies are plain strings. None of the merge rules read them — a conflict between two confidence values resolves the same whether the node is a person or a parcel — so you narrow them in your own code instead of adopting someone else's nouns.

What it does not do

It does not decide that two different ids are the same entity; resolution is a separate problem, and it throws on an id or type mismatch rather than welding two entities together. And it does not resolve conflicts — it records them. A merge that adjudicates disputed facts on its own is the thing this replaces.

Verified

25 tests, and 10 deliberate defects applied to the real source — all 10 caught, including last-write-wins, widening visibility, a rewritten `createdBy`, and conflicts computed and then dropped on the floor. The set ships in the source.

Delivery

Source delivered as a private repository invite within 24 hours of purchase. Single-product commercial license: use and modify in any number of products; no redistribution or resale of the source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function mergeGraphNodes( existing: GraphNodeShape, incoming: GraphNodeWrite, now: Date = new Date(), opts?:;
  export function mergeGraphEdges( existing: GraphEdgeShape, incoming: GraphEdgeWrite, now: Date = new Date(), ): GraphEdgeShape;