docs(adr): ADR-0003 — node-anchored wikitext editing for content actions

[tieguy]

Summary

SP42's two content-edit actions — InlineEdit and TagCitationNeeded — currently apply edits via first-occurrence literal String::replacen(…, 1) (sp42-server/src/action_routes.rs:378, :411-423). That's fine for patrol/revert, but it can target the wrong occurrence, is brittle to whitespace/TOCTOU, can't express structural edits, and on a whole-page save a mis-located swap silently corrupts an article.

ADR-0003 proposes replacing that with node-anchored editing behind a new WikitextEditor trait (consistent with ADR-0001 §7 trait-DI), Parsoid-backed via the parsoid crate, plus an immediate, parser-independent hardening: swap blind replacen(…, 1) for an exactly-one-occurrence guard, closing the wrong-target / silent-corruption risk now.

Motivation: an incoming collaboration (with @schiste — discussed beforehand) bringing LLM-assisted, human-confirmed citation verification & repair onto SP42, which needs structural, anti-drift edits replacen cannot express.

This is a Proposed ADR for discussion per CONSTITUTION §4 — docs only, no code yet. It records the decision and the one protected contract change (a node locator on SessionActionExecutionRequest).

Why Parsoid-first, in SP42's terms

• HTTP edge behind a trait (ADR-0001 §7); no new language (§1); SP42 already depends on EventStreams / LiftWing / the Action API.
• Outsources round-trip fidelity to MediaWiki's own parser rather than reinventing it.
• Vehicle: the parsoid crate (mwbot-rs, GPL-3.0) — typed cite/Reference/Template API, Rust-native, no JS engine. A WASM build of wikiparser-node is documented as the offline fallback; the trait seam makes the choice reversible.

Validation evidence (2026-06-04, AI-assisted)

Round-trip spike against en.wikipedia Cosmic latte (rev 1357330394), via the Parsoid REST transform with ?stash=true + If-Match:

• No-op round-trip: byte-for-byte identical (selective serialization disturbs nothing untouched).
• Param modify + param add on real {{cite}} templates: re-serialized only the edited template; all other refs/templates/prose byte-identical; the new param inserted in the template's existing |key=val style. Residual: light whitespace normalization within the edited template only.
• Source read of the parsoid crate (parsoid/src/api.rs): it transforms via core REST with flavor=edit HTML but without the explicit stash/If-Match selser flow — so its byte-level cleanliness isn't yet proven equal to the raw spike's (acceptance gate 2 below).

Acceptance gates (resolve in review, before merge)

0. GPL: confirm that this is acceptable. [See below.]
1. ✅ Bare-URL-wrap round-trip — confirm inserting a new node (wrap a bare-URL <ref> body into {{cite web|url=…}}) round-trips cleanly; the spike covered param modify/add only. [Update: I've validated these.]
2. ✅ parsoid-crate serialization fidelity — does transform_to_wikitext preserve untouched wikitext byte-for-byte, or normalize more than selser? If it under-preserves: contribute explicit selser upstream, or pair the crate's manipulation with a bespoke stash/If-Match transform (record in Decision 6). [Update: I've validated these.]
3. Locator shape — model both the <ref> and cite-template ordinal spaces in the locator union now, or ship <ref> first and extend? (fold into Decision 3).
4. Stash-expiry fallback — behaviour when an If-Match stash has aged out (pass the full original in the POST body).

Per ADR hygiene these gates live in this PR (not the ADR body); their resolutions get folded into the body before merge so the immutable record carries no open TODOs.

---

Transparency: the ADR draft and the validation spike were AI-assisted (Claude). The spike was read-only — it used the stateless Parsoid HTML→wikitext transform and never wrote to any wiki.

🤖 Generated with Claude Code

[tieguy]

On the GPL question

the parsoid crate is GPL-3.0-or-later, and a Cargo dependency is statically linked. Rust has no dynamic-linking / runtime-classpath separation, so the crate is compiled into the final binary — making any SP42 distributed binary that links it a GPL-3.0 combined work.

Three ways through it:

1. Relicense SP42 to GPL-3.0. Apache-2.0 → GPL-3.0 is allowed (one-way). Cleanest if copyleft is acceptable — keeps the crate's typed ergonomics.
2. Bespoke permissive Parsoid-REST client. Skip the crate; reimplement the (small) wire calls — GET …/page/{title}/html?flavor=edit, POST …/transform/html/to/wikitext — plus DOM manipulation via a permissive HTML lib (html5ever/scraper, MIT). Same serialization fidelity — it's Parsoid's, server-side; the byte-lossless result is client-independent (my earlier bespoke curl spike got the same). Cost: hand-writing the typed cite/ref/template helpers the crate gives for free. Keeps SP42 Apache-2.0 / deny.toml clean.
3. Isolate the editor in a separate GPL process. A small GPL sidecar doing the parsoid-crate work, called over IPC/HTTP; SP42 core stays Apache. Recreates the arms-length boundary but adds a process — somewhat ironic given Parsoid is already remote, so docs(prd): introduce Product Requirements Documents (PRDs) #2 usually dominates this.

The same GPL reality applies to the documented WASM-wikiparser-node fallback (also GPL, also linked-in), so #2 (bespoke client) is the only permissive option. The trade is purely typed-crate ergonomics + GPL vs more code + permissive — fidelity is identical across all three.

My read: if SP42-goes-GPL is on the table, #1 is simplest and keeps the best ergonomics; if SP42 must stay permissive, #2 is the path. Either way the WikitextEditor trait seam (Decision 1) makes the vehicle a swappable implementation, so this licensing call doesn't block the trait/contract decision the ADR is really asking you to ratify.

[schiste]

On the GPL question

the parsoid crate is GPL-3.0-or-later, and a Cargo dependency is statically linked. Rust has no dynamic-linking / runtime-classpath separation, so the crate is compiled into the final binary — making any SP42 distributed binary that links it a GPL-3.0 combined work.

Three ways through it:

1. Relicense SP42 to GPL-3.0. Apache-2.0 → GPL-3.0 is allowed (one-way). Cleanest if copyleft is acceptable — keeps the crate's typed ergonomics.

Relicensed done per : 766f154 if you prefer another or even recommend a dual license I'm happy to do it. Copyleft is absolutely fine here.

[schiste]

I'm merging PR with ADR as is but in implementing we will need to update the citation feature to keep it working.