Anchor model and re-anchoring algorithm

[vdvman1]

Question

What is the anchor model, and what algorithm re-anchors annotations when an article revision changes?

The hardest decision on this map. Everything about annotations depends on it.

Settled going in: a redundant selector set (structural path + text quote + character offset), tried in order, with fuzzy matching on section headings. Failures orphan to the margin, stay visible with their quoted text, and permalink to the revision they were written against. Re-anchoring runs on every article regardless of age.

Decide:

• The stored anchor shape. Which selectors, in what form, and what each one is relative to. The structural path presumably references the section tree from the article schema — pin down exactly how (section id? index? both?), and how a range within a block is expressed.
• Resolution order and fallback ladder. Which selector is authoritative, what each fallback costs in false-positive risk, and where the ladder stops and declares a failure.
• Fuzzy matching parameters. For headings: how much heading-text drift is tolerated before a section is considered a different section, given article section order is very unlikely to change. For quotes: what match tolerance, and what happens on multiple candidate matches.
• What counts as failure, and how confident a match must be before it is accepted. Getting this wrong in the permissive direction silently relocates a correction onto unrelated text — worse than orphaning it.
• Robustness to processorVersion changes, not just content changes. If the parser changes how blocks split or how heading ids are generated, existing anchors must still resolve.
• When re-anchoring runs — synchronously in the ingest mutation, as a follow-up action, incrementally? What happens to an annotation written against revision N while revision N+1 is being ingested?
• Ranges spanning structure. Can an anchor cross a block or heading boundary? What happens to a selection inside a syntax-highlighted code block, where the DOM is generated by shiki rather than by Mojang?

Blocked on the anchoring prior-art research and the article schema. Use /domain-modeling.

[vdvman1]

Findings from #36 (anchoring prior art). This is the fact base this ticket was waiting on — 883 lines, every claim cited, plus measurements across all 403 Mojang articles. Read it before deciding: docs/research/annotation-anchoring-prior-art.md

Recommended selector set — quote {exact, prefix, suffix} with 32-char context as the source of truth; sectionPath (index path + verbatim heading text, not the kebab id) as scope; position {start, end} as a fast path and proximity hint only; plus textVersion, processorVersion, revisionId. Explicitly not stored: any CSS or XPath path into the rendered DOM, and the derived heading id.

Recommended ladder — identity → position fast path → section-scoped fuzzy quote → document-wide fuzzy quote → low-confidence "best guess" band → orphan. Matcher: approx-string-match (Myers bit-parallel), ~25% error budget.

Four corrections to the map's settled design:

1. "Tried in order" is not sufficient — this is a real correction. Read literally it is the W3C rule (alternatives, first that resolves; the spec says "MUST pick one"). Hypothesis deliberately does not do that: both fast paths pipe through maybeAssertQuote, a strict range.toString() !== quote.exact check that throws and falls through. After a deleted paragraph, both the DOM path and the character offset still resolve — to the wrong text. Every leg of the ladder must be gated on a quote match, not merely on resolving.
2. The structural leg must be the section tree, never a DOM path. Our pipeline mutates the DOM in four places while leaving text intact, and measurement found 42% of articles have unbalanced <li> and 44% unbalanced <p> — so the baseline tree is partly a parser-error-recovery artefact, and two parser versions can legitimately disagree about it.
3. Split the version counter. Introduce textVersion (normalisation only) separate from processorVersion (rendering). Quotes and section paths then survive every rendering bump for free. Extract plain text from the sanitised source, not the rendered output. Raised on Article and revision schema in Convex #37 as well.
4. Add a low-confidence band before orphaning. Brush et al. (CHI 2001 / MSR-TR-2001-107) found orphan satisfaction rises with modification (median 7.0 for total deletion) while confident-but-wrong scores at the floor (median 1.0). Note Hypothesis's matchQuote has no minimum score threshold despite its JSDoc claiming one — do not copy that.

Two numbers that settle parameters:

• 9.19% of quotes are non-unique within their own article, dropping to ≤0.76% with 32-char context. That validates contextLen = 32 and warns against Hypothesis's 50% error budget.
• Quote length is p50 48, p90 100 — and diff-match-patch's match_main throws above 32 chars. diff-match-patch is disqualified outright; do not evaluate it further.

Blocking prerequisite surfaced: the current section tree carries no character offsets, which it needs in order to scope a quote match. That is a requirement on #37.