Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): WYSIWYG fragment duplication race during source typing (#2596)
Nick Gomez2720e78311f4
diff --git a/.changeset/fix-contended-typing-fragment-duplication.md b/.changeset/fix-contended-typing-fragment-duplication.mdnew file mode 100644index 000000000..a300f43ef--- /dev/null+++ b/.changeset/fix-contended-typing-fragment-duplication.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Fixed a rare corruption where typing into a document with unregistered JSX components (like `<Steps>`/`<Step>`) in source mode could duplicate or re-indent a block in the saved document. Under CPU load, a background editor could issue a structural rewrite of the same block the server was rebuilding keystroke-by-keystroke, and both copies survived into the authoritative document. The editor no longer issues those background rewrites while it is hidden in source mode, and the server now detects and discards a duplicated block instead of persisting it, so the typed content stays intact.diff --git a/packages/app/src/editor/extensions/JsxComponentView.tsx b/packages/app/src/editor/extensions/JsxComponentView.tsxindex ec2a98303..62112b293 100644--- a/packages/app/src/editor/extensions/JsxComponentView.tsx+++ b/packages/app/src/editor/extensions/JsxComponentView.tsx@@ -84,6 +84,7 @@ import { ALIGNABLE_DESCRIPTOR_NAMES } from '../utils/alignable-descriptors.ts';import { formatContainerAriaLabel } from '../utils/editor-strings.ts';import { reconstructSource } from '../utils/reconstruct-source.ts';import { sanitizeComponentProps } from '../utils/sanitize-url.ts';+import { autonomousFragmentEditAllowed } from './autonomous-fragment-edit.ts';// ── Error Boundary ──────────────────────────────────────────────────────//@@ -522,6 +523,17 @@ export function JsxComponentView({ node, editor, extension, getPos, selected }:const dispatchOnce = () => {if (cancelled) return;+ // In source mode this WYSIWYG editor is hidden; an autonomous structural+ // replace here races Observer B's per-keystroke re-derive and doubles the+ // span. Skip WITHOUT flipping convertedRef or scheduling a retry.+ // Re-conversion after a flip back to WYSIWYG rides on the next NodeView+ // re-render (typically Observer B's re-derive of the span or any+ // transaction touching it) — the mode flip itself does not remount the+ // hidden editor or re-run this effect, so a fully quiescent doc can sit+ // on the placeholder until the next transaction. Accepted trade-off:+ // the placeholder is inert and any edit re-triggers conversion, while+ // dispatching from the hidden editor corrupts the authoritative bytes.+ if (!autonomousFragmentEditAllowed(editor)) return;try {editor.view.dispatch(editor.state.tr.replaceWith(p, p + node.nodeSize, fallbackNode));convertedRef.current = true;diff --git a/packages/app/src/editor/extensions/RawMdxFallbackCMView.tsx b/packages/app/src/editor/extensions/RawMdxFallbackCMView.tsxindex 87d8aa35e..c43e73a18 100644--- a/packages/app/src/editor/extensions/RawMdxFallbackCMView.tsx+++ b/packages/app/src/editor/extensions/RawMdxFallbackCMView.tsx@@ -32,6 +32,7 @@ import { getEditorView } from '../utils/get-editor-view';import { getYDoc } from '../utils/get-ydoc';import { getSharedMarkdownManager } from '../utils/md-singleton';import { classifySeverity, SEVERITY_STYLES } from '../utils/severity';+import { autonomousFragmentEditAllowed } from './autonomous-fragment-edit.ts';import { createNestedCMExtensions, darkTheme, lightTheme } from './nested-cm-extensions';/**@@ -454,6 +455,11 @@ export function RawMdxFallbackView({ node, editor, getPos }: NodeViewProps) {if (!pmView) return;const currentNode = pmView.state.doc.nodeAt(pos);if (!currentNode || currentNode.type.name !== 'rawMdxFallback') return;+ // No autonomous structural fragment rewrite from a source-mode-hidden+ // editor — it races Observer B's re-derive (shared with the+ // auto-convert). The live nodeAt type-check above is the per-site+ // stale-position defense the auto-convert lacks; this is additional.+ if (!autonomousFragmentEditAllowed(editor)) return;const source = update.view.state.doc.toString();const replacement = tryParseUpgrade(source, pmView.state.schema);diff --git a/packages/app/src/editor/extensions/autonomous-fragment-edit.test.ts b/packages/app/src/editor/extensions/autonomous-fragment-edit.test.tsnew file mode 100644index 000000000..ddfa1efb9--- /dev/null+++ b/packages/app/src/editor/extensions/autonomous-fragment-edit.test.ts@@ -0,0 +1,43 @@+import { describe, expect, test } from 'bun:test';+import type { Editor } from '@tiptap/core';+import { autonomousFragmentEditAllowed } from './autonomous-fragment-edit.ts';+import { setEditorSourceMode } from './editor-mode-context.ts';++/**+ * The single enforcement boundary the autonomous structural dispatchers route+ * through (JsxComponentView auto-convert + retries, RawMdxFallbackCMView+ * blur-commit). Keyed on the Editor instance via the same WeakMap the+ * source-mode signal uses, so a bare object stands in for an editor.+ */+function fakeEditor(): Editor {+ return {} as Editor;+}++describe('autonomousFragmentEditAllowed', () => {+ test('allows autonomous structural edits in WYSIWYG mode (default)', () => {+ // Default-false source mode = visible WYSIWYG = the authoritative surface.+ expect(autonomousFragmentEditAllowed(fakeEditor())).toBe(true);+ });++ test('blocks autonomous structural edits when the editor is source-mode-hidden', () => {+ const editor = fakeEditor();+ setEditorSourceMode(editor, true);+ expect(autonomousFragmentEditAllowed(editor)).toBe(false);+ });++ test('re-allows when the editor flips back to WYSIWYG', () => {+ const editor = fakeEditor();+ setEditorSourceMode(editor, true);+ expect(autonomousFragmentEditAllowed(editor)).toBe(false);+ setEditorSourceMode(editor, false);+ expect(autonomousFragmentEditAllowed(editor)).toBe(true);+ });++ test('tracks each editor independently (per-instance signal)', () => {+ const hidden = fakeEditor();+ const visible = fakeEditor();+ setEditorSourceMode(hidden, true);+ expect(autonomousFragmentEditAllowed(hidden)).toBe(false);+ expect(autonomousFragmentEditAllowed(visible)).toBe(true);+ });+});diff --git a/packages/app/src/editor/extensions/autonomous-fragment-edit.ts b/packages/app/src/editor/extensions/autonomous-fragment-edit.tsnew file mode 100644index 000000000..33ba62421--- /dev/null+++ b/packages/app/src/editor/extensions/autonomous-fragment-edit.ts@@ -0,0 +1,19 @@+/**+ * An autonomous (non-user-initiated) structural fragment rewrite issued from a+ * source-mode-hidden WYSIWYG editor races Observer B's per-keystroke re-derive+ * and double-materializes the span at the Y.XmlFragment CRDT level (precedent+ * #14: Observer B is the sole fragment writer during source typing). Gate every+ * autonomous structural dispatch on the editor being the visible/authoritative+ * surface — in source mode the WYSIWYG is hidden, so its structural rewrites+ * serve no user and only create the double-write race.+ *+ * Checked at DISPATCH time (not effect entry): the mode can flip between+ * scheduling a rAF/timeout and its firing, and a stale-scheduled dispatch is+ * exactly the hazard.+ */+import type { Editor } from '@tiptap/core';+import { getEditorSourceMode } from './editor-mode-context.ts';++export function autonomousFragmentEditAllowed(editor: Editor): boolean {+ return !getEditorSourceMode(editor);+}diff --git a/packages/app/tests/integration/contended-typing-fragment-duplication.test.ts b/packages/app/tests/integration/contended-typing-fragment-duplication.test.tsnew file mode 100644index 000000000..0d7f50e37--- /dev/null+++ b/packages/app/tests/integration/contended-typing-fragment-duplication.test.ts@@ -0,0 +1,159 @@+/**+ * A stale client structural fragment replace must never end up as duplicated+ * authoritative Y.Text bytes.+ *+ * The race: while a user types per-keystroke into `Y.Text('source')`, server+ * Observer B rewrites the `Y.XmlFragment('default')` on every keystroke drain.+ * The keystroke that closes an unregistered `<Steps>`/`<Step>` block flips the+ * span's parse from a rawMdxFallback node to a valid wildcard jsxComponent — a+ * STRUCTURAL delete+insert of the span, not an item-preserving content update.+ * Concurrently, the hidden-but-mounted client WYSIWYG editor's wildcard+ * JsxComponentView auto-convert dispatches its own plain client-origin+ * `replaceWith` (also a structural delete+insert) of the SAME span, computed+ * against a fragment state that has lagged the server's rewrites. At the+ * Y.XmlFragment CRDT level the two concurrent delete+insert pairs merge as one+ * agreed delete plus BOTH inserts surviving, so the Step subtree materializes+ * twice. Observer A then serializes the doubled fragment and faithfully+ * persists the duplicated bytes into the authoritative Y.Text.+ *+ * Why raw Y.js emulation instead of driving the React editor: the invariant+ * under test is server-side — a stale client structural fragment replace must+ * not survive into authoritative Y.Text, regardless of which client surface+ * minted it. Emulating the auto-convert directly at the `client.fragment`+ * delete/insert level pins that server/bridge contract without coupling the+ * test to JsxComponentView's rAF scheduling, its per-instance idempotence+ * guard, or any editor mount lifecycle. It is the stronger contract: any+ * client that issues a concurrent structural replace of a bridge-derived span+ * reproduces this, not just the one dispatcher that happens to exist today.+ *+ * Why the assertion is at the server Y.Text level: that is the authoritative+ * source persisted to disk and converged to every peer (precedent #38,+ * Y.Text-is-truth). The corruption is real bytes there, self-stabilizing, with+ * no downstream self-heal — so the server Y.Text multiplicity is the invariant+ * that matters.+ *+ * The interleave is staged deterministically with syncControl: the client+ * pauses INBOUND sync (so it never sees Observer B's rewrites — the stale+ * replica), types the closing tags per-keystroke (outbound still flows, so the+ * server rewrites the span per keystroke), then performs the+ * auto-convert-equivalent structural replace against its stale fragment. On+ * resume the server fragment holds two copies of the Step subtree and the+ * authoritative Y.Text duplicates the typed body line.+ */+import { afterAll, beforeAll, expect, test } from 'bun:test';+import * as Y from 'yjs';+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';+import {+ awaitDocQuiescence,+ createTestClient,+ createTestServer,+ getServerState,+ type TestClient,+ type TestServer,+} from './test-harness';++// Seeded UNCLOSED — the fragment materializes a rawMdxFallback (parse-error)+// node for the span. Typing the closing tags flips the parse to a valid+// wildcard jsxComponent, which is a STRUCTURAL replace by Observer B (not an+// item-preserving content update) — one side of the concurrent replace pair.+const STEPS_UNCLOSED = [+ '## Guide',+ '',+ 'Intro paragraph.',+ '',+ '<Steps>',+ '',+ '<Step>',+ '',+ 'Step one body.',+ '',+].join('\n');+const CLOSING = '</Step>\n\n</Steps>\n';++let server: TestServer;+let client: TestClient;++beforeAll(async () => {+ server = await createTestServer();+}, HARNESS_BOOT_TIMEOUT_MS);++afterAll(async () => {+ await client?.cleanup();+ await server?.cleanup();+});++test('concurrent client structural replace vs Observer-B rewrite must not duplicate the Step subtree', async () => {+ client = await createTestClient(server.port, undefined, {+ syncControl: true,+ // We deliberately drive divergence — the watcher would throw first.+ skipInvariantWatcher: true,+ });++ // Seed the doc UNCLOSED through the client Y.Text (source-mode surface, W2).+ client.doc.transact(() => {+ client.ytext.insert(0, STEPS_UNCLOSED);+ });+ await awaitDocQuiescence(client.doc, { timeoutMs: 10_000, idleTicks: 5 });++ const pre = getServerState(server, client.docName);+ expect(pre).not.toBeNull();+ expect(pre?.ytext.toString().match(/Step one body\./g)?.length).toBe(1);++ // ── Open the concurrency window ──────────────────────────────────────+ // Client stops SEEING server-side Observer-B fragment rewrites (inbound+ // paused), exactly like a CPU-starved renderer whose WS deltas lag.+ client.pauseSync();++ // Type the CLOSING tags per-keystroke (outbound flows). At the final+ // keystrokes the server-side parse flips the span from rawMdxFallback to+ // a valid wildcard jsxComponent — Observer B performs a STRUCTURAL+ // delete+insert on the span.+ let at = client.ytext.length;+ for (const ch of CLOSING) {+ client.doc.transact(() => {+ client.ytext.insert(at, ch);+ });+ at += 1;+ }++ // Auto-convert-equivalent structural replace, computed against the+ // client's STALE fragment (paused inbound — it still holds the seed-era+ // paragraphs for the unclosed span; the server has meanwhile folded the+ // span into one jsxComponent). Mirrors the JsxComponentView auto-convert+ // replaceWith: delete the stale span items and insert ONE rawMdxFallback+ // element whose text is the stale source snapshot — the exact byte-shape+ // observed as the surviving orphan copy in the corrupted drains. Plain+ // client origin, like the real dispatch. Inbound is paused, so the client+ // fragment never changes after seed; only its Y.Text advanced. The stale+ // span is the paragraphs at indices 2..4.+ expect(client.fragment.length).toBeGreaterThanOrEqual(5);+ const fallback = new Y.XmlElement('rawMdxFallback');+ fallback.setAttribute('reason', 'Unregistered component: Step');+ fallback.insert(0, [new Y.XmlText('<Step>\n\nStep one body.\n\n</Step>')]);+ client.doc.transact(() => {+ client.fragment.delete(2, 3);+ client.fragment.insert(2, [fallback]);+ });++ // ── Close the window: let the server's queued rewrites reach the client+ // and the final settlement run. ──────────────────────────────────────+ client.resumeSync();+ await awaitDocQuiescence(client.doc, { timeoutMs: 15_000, idleTicks: 10 });++ const post = getServerState(server, client.docName);+ expect(post).not.toBeNull();+ const bytes = post?.ytext.toString() ?? '';++ // INVARIANT (the duplication-gate recovery upholds this): the typed body+ // line appears exactly once and the container tags stay singular in the+ // authoritative bytes.+ expect(bytes.match(/Step one body\./g)?.length ?? 0).toBe(1);+ expect(bytes.match(/<Step>/g)?.length ?? 0).toBe(1);+ expect(bytes.match(/<Steps>/g)?.length ?? 0).toBe(1);++ // Post-recovery bridge coherence: the re-derived server fragment must agree+ // with Y.Text (a recovery that fixed the bytes but left a doubled fragment+ // would just re-trip the gate on the next drain).+ expect(post?.md.match(/Step one body\./g)?.length ?? 0).toBe(1);+ expect(post?.md.match(/<Step>/g)?.length ?? 0).toBe(1);+}, 30_000);diff --git a/packages/app/tests/integration/single-client-paste-duplication.test.ts b/packages/app/tests/integration/single-client-paste-duplication.test.tsnew file mode 100644index 000000000..5bd2850eb--- /dev/null+++ b/packages/app/tests/integration/single-client-paste-duplication.test.ts@@ -0,0 +1,138 @@+/**+ * The Observer-A duplication gate must recover a server-vs-client CRDT race but+ * NEVER touch a legitimate same-client duplication: recovery re-derives the+ * fragment from Y.Text, so a false positive would silently drop the user's+ * paste. Provenance is the discriminator — a legitimate duplication is minted+ * entirely by the one editing client (no copy carries the server's own+ * clientID), so the gate's server-plus-foreign signature does not match and the+ * router forward-propagates the second copy into Y.Text.+ *+ * Emulated at the raw Y.js level (a single client inserting two content-equal+ * paragraphs into the fragment) to pin the server/bridge contract independent+ * of any editor surface.+ */+import { afterAll, beforeAll, expect, test } from 'bun:test';+import * as Y from 'yjs';+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';+import {+ awaitDocQuiescence,+ createTestClient,+ createTestServer,+ getServerState,+ type TestClient,+ type TestServer,+} from './test-harness';++const PARA = 'This is a pasted body paragraph.';++function paragraph(text: string): Y.XmlElement {+ const el = new Y.XmlElement('paragraph');+ el.insert(0, [new Y.XmlText(text)]);+ return el;+}++let server: TestServer;+let client: TestClient;++beforeAll(async () => {+ server = await createTestServer();+}, HARNESS_BOOT_TIMEOUT_MS);++afterAll(async () => {+ await client?.cleanup();+ await server?.cleanup();+});++test('a single client duplicating a paragraph forward-propagates both copies into Y.Text', async () => {+ client = await createTestClient(server.port, undefined, { skipInvariantWatcher: true });++ // Author one paragraph in WYSIWYG (client-minted in the fragment), let it+ // settle through to Y.Text.+ client.doc.transact(() => {+ client.fragment.insert(client.fragment.length, [paragraph(PARA)]);+ });+ await awaitDocQuiescence(client.doc, { timeoutMs: 10_000, idleTicks: 5 });++ const mid = getServerState(server, client.docName);+ expect(mid?.ytext.toString().match(/This is a pasted body paragraph\./g)?.length).toBe(1);++ // Paste a second copy — same client, so both carriers share one (foreign to+ // the server) clientID. The fragment now holds the line twice while Y.Text+ // still holds it once, so the growth pre-filter fires; the provenance walk+ // must classify it as a legitimate duplication (no server-minted copy) and+ // let Observer A forward-propagate it.+ client.doc.transact(() => {+ client.fragment.insert(client.fragment.length, [paragraph(PARA)]);+ });+ await awaitDocQuiescence(client.doc, { timeoutMs: 15_000, idleTicks: 10 });++ const post = getServerState(server, client.docName);+ expect(post).not.toBeNull();+ const bytes = post?.ytext.toString() ?? '';+ // The paste survives into authoritative Y.Text — the gate did not fire.+ expect(bytes.match(/This is a pasted body paragraph\./g)?.length ?? 0).toBe(2);+}, 30_000);++test('pasting a duplicate of a SERVER-DERIVED component block forward-propagates (shape agrees)', async () => {+ // Component-shaped variant of the shape-agreement guard: the server derives+ // a jsxComponent under its own clientID; the client then inserts a clone of+ // that element (foreign clientID, SAME node shape). The provenance split+ // matches the race signature but the shapes agree, so the gate must let the+ // router forward-propagate the duplicate block.+ const client3 = await createTestClient(server.port, undefined, { skipInvariantWatcher: true });+ const steps = '<Steps>\n\n<Step>\n\nCloned step body content.\n\n</Step>\n\n</Steps>\n';+ try {+ client3.doc.transact(() => client3.ytext.insert(0, steps));+ await awaitDocQuiescence(client3.doc, { timeoutMs: 10_000, idleTicks: 5 });++ const seeded = getServerState(server, client3.docName);+ expect(seeded?.ytext.toString().match(/Cloned step body content\./g)?.length).toBe(1);++ const component = client3.fragment+ .toArray()+ .find((child) => child instanceof Y.XmlElement && child.nodeName === 'jsxComponent');+ expect(component).toBeInstanceOf(Y.XmlElement);+ client3.doc.transact(() => {+ client3.fragment.insert(client3.fragment.length, [(component as Y.XmlElement).clone()]);+ });+ await awaitDocQuiescence(client3.doc, { timeoutMs: 15_000, idleTicks: 10 });++ const post = getServerState(server, client3.docName);+ const bytes = post?.ytext.toString() ?? '';+ expect(bytes.match(/Cloned step body content\./g)?.length ?? 0).toBe(2);+ expect(bytes.match(/<Steps>/g)?.length ?? 0).toBe(2);+ } finally {+ await client3.cleanup();+ }+}, 30_000);++test('pasting a duplicate of SERVER-DERIVED content still forward-propagates (shape agrees)', async () => {+ // The harder false-positive: the original was authored in source mode, so+ // Observer B derived the fragment copy under the SERVER clientID. Pasting a+ // duplicate then yields a server-minted + a foreign-minted carrier of the+ // SAME node shape. The provenance split alone would misfire and drop the+ // paste; the shape-agreement guard keeps it (a real race is a shape+ // disagreement, not agreement).+ const client2 = await createTestClient(server.port, undefined, { skipInvariantWatcher: true });+ const marker = 'This is a source-authored body paragraph.';+ try {+ client2.doc.transact(() => client2.ytext.insert(0, `${marker}\n`));+ await awaitDocQuiescence(client2.doc, { timeoutMs: 10_000, idleTicks: 5 });++ const seeded = getServerState(server, client2.docName);+ expect(seeded?.ytext.toString().match(/source-authored body paragraph/g)?.length).toBe(1);++ client2.doc.transact(() => {+ const el = new Y.XmlElement('paragraph');+ el.insert(0, [new Y.XmlText(marker)]);+ client2.fragment.insert(client2.fragment.length, [el]);+ });+ await awaitDocQuiescence(client2.doc, { timeoutMs: 15_000, idleTicks: 10 });++ const post = getServerState(server, client2.docName);+ const n = post?.ytext.toString().match(/source-authored body paragraph/g)?.length ?? 0;+ expect(n).toBe(2);+ } finally {+ await client2.cleanup();+ }+}, 30_000);diff --git a/packages/app/tests/stress/qa-canary-authoring-both-modes.e2e.ts b/packages/app/tests/stress/qa-canary-authoring-both-modes.e2e.tsindex d59820f30..b3b58f25d 100644--- a/packages/app/tests/stress/qa-canary-authoring-both-modes.e2e.ts+++ b/packages/app/tests/stress/qa-canary-authoring-both-modes.e2e.ts@@ -55,24 +55,20 @@ test.beforeEach(async ({ page, api }) => {await page.waitForSelector('.ProseMirror');});-// KNOWN PRE-EXISTING CORRUPTION (quarantined tripwires): three of these-// canaries detect a real source-typing duplication/re-indent race in the-// authoritative Y.Text that PRE-DATES this suite — a 2026-07 forensic bisect-// reproduced the same failures at ~30-50% per fully-contended run on pure-// origin/main with these canary files copied in (8 canary failures across 3-// runs), on this branch with `deriveStructuralFreshness` verifiably OFF in-// the built dist, and on this branch as-shipped. Only full-suite CPU-// contention trips it; single-file runs pass. The corruption is real-// (duplicated bytes read from `provider.document.getText('source')`, never-// the DOM). The affected tests are `test.fixme` so a pre-existing production-// bug does not lottery every PR's e2e lane; they are the ORACLE for the-// follow-up fix and must be un-fixme'd by it. The full forensic evidence-// (run matrix, mechanism map, reproduction procedure) lives in the-// quarantining commit's message and its PR discussion.+// These canaries are the field oracle for the source-typing+// duplication/re-indent race in the authoritative Y.Text: a source-mode-hidden+// WYSIWYG editor issuing an autonomous structural fragment replace of a+// <Steps>/<Step> span while server Observer B re-derives that span per+// keystroke, both inserts surviving the CRDT merge (duplicated bytes read from+// `provider.document.getText('source')`, never the DOM). The fix is symmetric:+// the client no longer mints the autonomous structural write from a hidden+// editor, and the server refuses to persist a provenance-confirmed doubled+// span. The race only surfaces under CPU contention (client apply-lag vs typing+// cadence), so validate these under load, not single-file.test.describe('QA canary — authoring <Steps> across both modes', () => {// T1 — SOURCE: author the whole nested <Steps> from EMPTY, char-by-char, through// the unclosed-container transient, landing valid. Surrounding heading preserved.- test.fixme('source: author nested <Steps> from empty; no whole-doc collapse, recovers to valid', async ({+ test('source: author nested <Steps> from empty; no whole-doc collapse, recovers to valid', async ({page,api,}) => {@@ -115,7 +111,7 @@ test.describe('QA canary — authoring <Steps> across both modes', () => {// T2 — WYSIWYG ProseMirror + JITTER PROBE: with a valid <Steps> + surrounding// prose, type a burst into a sibling paragraph; the Steps render must NOT flash// (fallback/CM count stable across the burst).- test.fixme('wysiwyg: typing in prose adjacent to <Steps> does not flash the Steps render (jitter)', async ({+ test('wysiwyg: typing in prose adjacent to <Steps> does not flash the Steps render (jitter)', async ({page,api,}) => {@@ -198,7 +194,7 @@ test.describe('QA canary — authoring <Steps> across both modes', () => {// T4 — MODE-FLIP mid-build: type a partial (unclosed) <Steps> in source, flip to// WYSIWYG while broken, flip back, finish. No collapse, no corruption, recovers.- test.fixme('mode-flip mid-build: unclosed <Steps> survives a WYSIWYG round-trip and recovers', async ({+ test('mode-flip mid-build: unclosed <Steps> survives a WYSIWYG round-trip and recovers', async ({page,api,}) => {diff --git a/packages/app/tests/stress/qa-canary-live-typing.e2e.ts b/packages/app/tests/stress/qa-canary-live-typing.e2e.tsindex 12c3b55da..2bb8fb893 100644--- a/packages/app/tests/stress/qa-canary-live-typing.e2e.ts+++ b/packages/app/tests/stress/qa-canary-live-typing.e2e.ts@@ -104,16 +104,16 @@ test.beforeEach(async ({ page, api }) => {);});-// KNOWN PRE-EXISTING CORRUPTION (quarantined tripwire): B1 below detects a-// real source-typing race in the authoritative Y.Text that PRE-DATES this-// suite (reproduced on pure origin/main under full-suite contention — see-// the forensic note atop qa-canary-authoring-both-modes.e2e.ts; the full-// evidence lives in the quarantining commit's message and its PR-// discussion). It is `test.fixme` so the pre-existing bug does not lottery-// every PR's e2e lane; the follow-up fix must un-fixme it.+// B1 detects the source-typing double-materialization race in the+// authoritative Y.Text: a source-mode-hidden WYSIWYG editor issuing an+// autonomous structural fragment replace while server Observer B re-derives the+// same span per keystroke, both inserts surviving the CRDT merge. The client+// trigger is now gated (no autonomous structural write from a hidden editor)+// and the server refuses to persist a provenance-confirmed doubled span, so the+// burst lands contiguous. Contention-dependent, so validate under load.test.describe('QA canary — live per-keystroke typing on <Steps> (browser, source mode)', () => {// B1 — live burst inside a Step body: caret stays put (burst contiguous), no re-indent.- test.fixme('typing a burst into a Step body lands contiguous, no re-indent, no growth', async ({+ test('typing a burst into a Step body lands contiguous, no re-indent, no growth', async ({page,}) => {await sourceToggle(page).click();diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.tsnew file mode 100644index 000000000..463e89595--- /dev/null+++ b/packages/core/src/bridge/growth-detect.ts@@ -0,0 +1,48 @@++const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;++export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;++export function isSubstantiveBodyLine(+ line: string,+ minLength: number = DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH,+): boolean {+ const trimmed = line.trim();+ if (trimmed.length < minLength) return false;+ return !(trimmed.startsWith('<') || trimmed.startsWith('```') || trimmed.startsWith('|'));+}++export function substantiveLineCounts(+ doc: string,+ minLength: number = DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH,+): Map<string, number> {+ const counts = new Map<string, number>();+ for (const raw of doc.split('\n')) {+ if (!isSubstantiveBodyLine(raw, minLength)) continue;+ const line = raw.trim();+ counts.set(line, (counts.get(line) ?? 0) + 1);+ }+ return counts;+}++export function maxBodyLineOccurrence(+ doc: string,+ minLength: number = DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH,+): number {+ let max = 0;+ for (const c of substantiveLineCounts(doc, minLength).values()) if (c > max) max = c;+ return max;+}++export function overMultipliedBodyLines(+ candidate: string,+ reference: string,+ minLength: number = DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH,+): string[] {+ const refCounts = substantiveLineCounts(reference, minLength);+ const out: string[] = [];+ for (const [line, count] of substantiveLineCounts(candidate, minLength)) {+ if (count >= 2 && count > (refCounts.get(line) ?? 0)) out.push(line);+ }+ return out;+}diff --git a/packages/core/src/bridge/index.ts b/packages/core/src/bridge/index.tsindex 9ff048816..29455914e 100644--- a/packages/core/src/bridge/index.ts+++ b/packages/core/src/bridge/index.ts@@ -50,6 +50,7 @@ export {readFmMap,readFmRegionWithError,} from './frontmatter-region.ts';+export { DUPLICATION_GATE_MIN_LINE_LENGTH, overMultipliedBodyLines } from './growth-detect.ts';export { fnv1aDigest } from './hash-util.ts';export {assertContentPreservation,diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.tsindex 864bc7245..3c927eb47 100644--- a/packages/core/src/bridge/merge-three-way.ts+++ b/packages/core/src/bridge/merge-three-way.ts@@ -1,5 +1,6 @@import DiffMatchPatch from 'diff-match-patch';import { diff3Merge } from 'node-diff3';+import { substantiveLineCounts } from './growth-detect.ts';import { fnv1aDigest } from './hash-util.ts';const dmp = new DiffMatchPatch();@@ -40,7 +41,7 @@ function mergeThreeWayImpl(baseline: string, userText: string, agentText: stringexport type BridgeMergeContentLossSide = 'user' | 'agent';-export type BridgeMergeContentLossWhich = 'substring' | 'order';+export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';export interface BridgeMergeContentLossInfo {baseline: string;@@ -202,6 +203,29 @@ export function assertContentPreservation(side: 'agent',});}++ const baselineCounts = substantiveLineCounts(baseline);+ const userCounts = substantiveLineCounts(userText);+ const agentCounts = substantiveLineCounts(agentText);+ for (const [line, count] of substantiveLineCounts(result)) {+ if (count < 2) continue;+ const maxInput = Math.max(+ baselineCounts.get(line) ?? 0,+ userCounts.get(line) ?? 0,+ agentCounts.get(line) ?? 0,+ );+ if (count > maxInput) {+ throw new BridgeMergeContentLossError({+ baseline,+ userText,+ agentText,+ result,+ lostSubstrings: [line],+ which: 'growth',+ side: 'user',+ });+ }+ }}function mergeConflictRegion(base: string, user: string, agent: string): string {diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 39557170b..aa7647d82 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -983,6 +983,7 @@ export {createStructuralFreshnessChecker,type DiffChange,type DocBoundarySplit,+ DUPLICATION_GATE_MIN_LINE_LENGTH,defaultScheduler,detectAppliedToleranceClasses,detectFmRegion,@@ -1010,6 +1011,7 @@ export {MAX_FM_REGION_BYTES,mergeThreeWay,normalizeBridge,+ overMultipliedBodyLines,PARSE_EQUIVALENCE_TOLERANCE,type ParsedFmRegion,type PmStructuralNode,diff --git a/packages/core/src/shadow-repo-layout.ts b/packages/core/src/shadow-repo-layout.tsindex 6407cab15..dbb65ebfe 100644--- a/packages/core/src/shadow-repo-layout.ts+++ b/packages/core/src/shadow-repo-layout.ts@@ -601,10 +601,14 @@ export type AutoConsolidationTrigger = 'dead-chain' | 'session-close' | 'boot' |export type ParsedCheckpoint =| {+ // `which` distinguishes the post-condition verdict class ('substring' /+ // 'order' losses vs 'growth' gains) within the one merge checkpoint+ // kind. Optional: checkpoints written before the field existed parse+ // without it.kind: 'bridge-merge-loss';docName: string | null;size: number | null;- metadata: { lostSubstrings: string[] };+ metadata: { lostSubstrings: string[]; which?: string };}| {// Observer A's producer guard detected serialize output that fails@@ -619,6 +623,19 @@ export type ParsedCheckpoint =size: number | null;metadata: { construct: string };}+ | {+ // Observer A's duplication gate detected a CRDT double-materialization of+ // a bridge-derived span (a substantive body line present in the fragment+ // more times than Y.Text justified, provenance-confirmed as a+ // server-vs-client race) and re-derived the fragment from Y.Text before+ // it could persist. `contents` is the pre-recovery doubled fragment+ // serialization — the anchor if the re-derive was wrong.+ // `duplicatedLineCount` is a content-free count, never raw content.+ kind: 'observer-a-duplication';+ docName: string | null;+ size: number | null;+ metadata: { duplicatedLineCount: number };+ }| {kind: 'external-change-rescue';docName: string | null;@@ -693,6 +710,18 @@ export function parseCheckpoint(body: string): ParsedCheckpoint | null {}return null;}+ if (kind === 'observer-a-duplication') {+ const m = metadata as { duplicatedLineCount?: unknown };+ if (typeof m.duplicatedLineCount === 'number' && Number.isFinite(m.duplicatedLineCount)) {+ return {+ kind: 'observer-a-duplication',+ docName,+ size,+ metadata: { duplicatedLineCount: m.duplicatedLineCount },+ };+ }+ return null;+ }if (kind === 'external-change-rescue') {const m = metadata as { incomingDiskSha?: unknown };if (typeof m.incomingDiskSha === 'string') {diff --git a/packages/server/src/bridge-watchdog.ts b/packages/server/src/bridge-watchdog.tsindex 729880f39..210eb48ba 100644--- a/packages/server/src/bridge-watchdog.ts+++ b/packages/server/src/bridge-watchdog.ts@@ -142,17 +142,23 @@ const lastToleranceEmitMs = new Map<string, number>();const lastPathBEmitMs = new Map<string, number>();/** Observer A settlement-check site that detected a drain settling- * split-brain. Three production sites in `server-observers.ts`: the+ * split-brain. Four production sites in `server-observers.ts`: the* identity gate (fragment changed but its serialization didn't move),- * the post-merge baseline check (after a Path A/B Y.Text write), and- * the error-recovery catch (sync work threw before the settlement check,- * so the baseline reset must not witness a divergent Y.Text). */-export type BridgeSplitBrainSite = 'identity-gate' | 'post-merge' | 'error-recovery';+ * the post-merge baseline check (after a Path A/B Y.Text write), the+ * error-recovery catch (sync work threw before the settlement check, so the+ * baseline reset must not witness a divergent Y.Text), and the duplication+ * guard (a provenance-confirmed CRDT double-materialization of a+ * bridge-derived span, re-derived from clean Y.Text before it can persist). */+export type BridgeSplitBrainSite =+ | 'identity-gate'+ | 'post-merge'+ | 'error-recovery'+ | 'duplication-guard';/** Map<rateKey, last-emit-Unix-ms> for the bridge-split-brain-rederive* event. rateKey = `${site}::${docName ?? '__nodoc__'}` — per-(site, doc)- * so a chatty doc can't suppress signal from quieter docs and the three- * detection sites surface independently. Bounded: 3 sites × docs, with+ * so a chatty doc can't suppress signal from quieter docs and the four+ * detection sites surface independently. Bounded: 4 sites × docs, with* the same lazy prune as `lastEmitMs`.** WARN: same module-level state caveat as `lastEmitMs` above. */diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.tsindex a301f22cc..bfb7f0036 100644--- a/packages/server/src/metrics.ts+++ b/packages/server/src/metrics.ts@@ -56,6 +56,8 @@ export interface ReconciliationMetrics {* content-preservation post-condition violations. Calibration signal* for the parallel single-CRDT-collapse exploration. */bridgeMergeContentLoss: number;+ /** Path B growth verdicts (`which: 'growth'`) — content GAIN events, counted apart from loss so the two failure classes chart independently. */+ bridgeMergeContentGrowth: number;/** Bridge-correctness — count of successful silent rescue* checkpoints written via saveInMemoryCheckpoint. Bounds the rate a user* might see in TimelinePanel; if high, coalescing becomes worth adding. */@@ -232,6 +234,17 @@ export interface ReconciliationMetrics {* need when triaging editor latency, which the divergence-scoped Path B* counters deliberately exclude. */observerAResidualMergeRuns: number;+ /** Count of Observer A duplication-gate recoveries — a substantive body+ * line materialized more times in the fragment than clean Y.Text justified,+ * provenance-confirmed as a server-vs-client CRDT double-materialization+ * (one copy minted by Observer B under the server's own clientID, another+ * by a foreign client), and re-derived from Y.Text before it could persist+ * (precedent #38, Y.Text-is-truth). Counter only, incremented once per+ * confirmed recovery; the rate-limited `bridge-split-brain-rederive`+ * console event under site `duplication-guard` carries the per-doc signal. */+ observerADuplicationRederives: number;+ /** Successful duplication-recovery checkpoint writes — the forensic anchor for a destructive re-derive; divergence from `observerADuplicationRederives` means anchors are being lost. */+ observerADuplicationCheckpointCreated: number;/** Y.Text-is-truth contract (precedent #38) — count of Observer A* settlement checks that detected a drain settling split-brain (Y.Text* vs serialize(fragment) divergence beyond `normalizeBridge` tolerance)@@ -402,6 +415,7 @@ const counters: ReconciliationMetrics = {serverObserverErrorsB: 0,persistenceDiskWrites: 0,bridgeMergeContentLoss: 0,+ bridgeMergeContentGrowth: 0,bridgeMergeCheckpointCreated: 0,producerGuardFires: 0,producerGuardFiresSuppressed: 0,@@ -426,6 +440,8 @@ const counters: ReconciliationMetrics = {mapDrivenSpliceApplied: 0,mapDrivenSpliceFallback: {},observerAResidualMergeRuns: 0,+ observerADuplicationRederives: 0,+ observerADuplicationCheckpointCreated: 0,bridgeSplitBrainRederives: 0,bridgeSplitBrainRederivesSuppressed: 0,persistenceReconciliationFailures: 0,@@ -514,6 +530,10 @@ export function incrementBridgeMergeContentLoss(): void {counters.bridgeMergeContentLoss++;}+export function incrementBridgeMergeContentGrowth(): void {+ counters.bridgeMergeContentGrowth++;+}+export function incrementAgentWriteCalls(): void {counters.agentWriteCalls++;}@@ -602,6 +622,14 @@ export function incrementObserverAResidualMergeRuns(): void {counters.observerAResidualMergeRuns++;}+export function incrementObserverADuplicationRederives(): void {+ counters.observerADuplicationRederives++;+}++export function incrementObserverADuplicationCheckpointCreated(): void {+ counters.observerADuplicationCheckpointCreated++;+}+export function incrementBridgeSplitBrainRederives(): void {counters.bridgeSplitBrainRederives++;}@@ -769,6 +797,7 @@ export function resetMetrics(): void {counters.serverObserverErrorsB = 0;counters.persistenceDiskWrites = 0;counters.bridgeMergeContentLoss = 0;+ counters.bridgeMergeContentGrowth = 0;counters.bridgeMergeCheckpointCreated = 0;counters.producerGuardFires = 0;counters.producerGuardFiresSuppressed = 0;@@ -793,6 +822,8 @@ export function resetMetrics(): void {counters.mapDrivenSpliceApplied = 0;counters.mapDrivenSpliceFallback = {};counters.observerAResidualMergeRuns = 0;+ counters.observerADuplicationRederives = 0;+ counters.observerADuplicationCheckpointCreated = 0;counters.bridgeSplitBrainRederives = 0;counters.bridgeSplitBrainRederivesSuppressed = 0;counters.persistenceReconciliationFailures = 0;diff --git a/packages/server/src/server-observers-duplication-gate.test.ts b/packages/server/src/server-observers-duplication-gate.test.tsnew file mode 100644index 000000000..b5b36bf7b--- /dev/null+++ b/packages/server/src/server-observers-duplication-gate.test.ts@@ -0,0 +1,115 @@+import { describe, expect, test } from 'bun:test';+import * as Y from 'yjs';+import { findRaceDuplicatedSpans } from './server-observers.ts';++/** A top-level fragment child (element name + text content). */+function makeChild(nodeName: string, text: string): Y.XmlElement {+ const el = new Y.XmlElement(nodeName);+ el.insert(0, [new Y.XmlText(text)]);+ return el;+}++/**+ * Merge one doc's fragment inserts into another so the received structs retain+ * their originating clientID — the same way a client's fragment write reaches+ * the server doc carrying a foreign clientID.+ */+function mergeInto(target: Y.Doc, source: Y.Doc): void {+ Y.applyUpdate(target, Y.encodeStateAsUpdate(source));+}++describe('findRaceDuplicatedSpans', () => {+ const LINE = 'Step one body line.';++ test('server-minted jsxComponent + foreign-minted rawMdxFallback carrying the same line is a race', () => {+ const server = new Y.Doc();+ const client = new Y.Doc();+ const sFrag = server.getXmlFragment('default');+ // Observer B mints the re-derived span under the server doc's clientID.+ server.transact(() => sFrag.insert(0, [makeChild('jsxComponent', LINE)]));+ // The stale client mints its auto-convert snapshot under a foreign clientID.+ client.transact(() =>+ client.getXmlFragment('default').insert(0, [makeChild('rawMdxFallback', LINE)]),+ );+ mergeInto(server, client);++ expect(sFrag.length).toBe(2);+ expect(findRaceDuplicatedSpans(sFrag, server.clientID, [LINE])).toBe(true);+ });++ test('two foreign-minted carriers (paste-twice shape) is NOT a race', () => {+ const server = new Y.Doc();+ const c1 = new Y.Doc();+ const c2 = new Y.Doc();+ const sFrag = server.getXmlFragment('default');+ // Both copies minted entirely by clients — the server never typed either.+ c1.transact(() => c1.getXmlFragment('default').insert(0, [makeChild('paragraph', LINE)]));+ c2.transact(() => c2.getXmlFragment('default').insert(0, [makeChild('paragraph', LINE)]));+ mergeInto(server, c1);+ mergeInto(server, c2);++ expect(sFrag.length).toBe(2);+ // Recovery re-derives from Y.Text, so firing here would drop a legitimate+ // client duplication — it must not fire.+ expect(findRaceDuplicatedSpans(sFrag, server.clientID, [LINE])).toBe(false);+ });++ test('server-minted + foreign-minted carriers of the SAME node type is NOT a race', () => {+ // A stale-view race is a parse-shape disagreement; agreeing shapes mean an+ // intentional client duplication (a paste of a server-derived component+ // block). Item-preservation would have deduped a matching re-derivation, so+ // a surviving same-shape duplication is never this race.+ const server = new Y.Doc();+ const client = new Y.Doc();+ const sFrag = server.getXmlFragment('default');+ server.transact(() => sFrag.insert(0, [makeChild('jsxComponent', LINE)]));+ client.transact(() =>+ client.getXmlFragment('default').insert(0, [makeChild('jsxComponent', LINE)]),+ );+ mergeInto(server, client);++ expect(sFrag.length).toBe(2);+ expect(findRaceDuplicatedSpans(sFrag, server.clientID, [LINE])).toBe(false);+ });++ test('inline-formatted line still attributes carriers (markdown vs XML normalization agrees)', () => {+ // The over-multiplied line arrives in MARKDOWN spelling (from the fragment+ // serialization) while carriers are matched against the child's XML bare+ // text. Inline code and literal underscores spell differently on the two+ // sides; the shared marker-char reduction must keep them attributable.+ const mdLine = 'Run `code_with_underscore` on the snake_case_name path now.';+ const xmlText = 'Run code_with_underscore on the snake_case_name path now.';+ const server = new Y.Doc();+ const client = new Y.Doc();+ const sFrag = server.getXmlFragment('default');+ server.transact(() => sFrag.insert(0, [makeChild('jsxComponent', xmlText)]));+ client.transact(() =>+ client.getXmlFragment('default').insert(0, [makeChild('rawMdxFallback', xmlText)]),+ );+ mergeInto(server, client);++ expect(sFrag.length).toBe(2);+ expect(findRaceDuplicatedSpans(sFrag, server.clientID, [mdLine])).toBe(true);+ });++ test('a lone server-minted carrier is NOT a race (no foreign sibling)', () => {+ const server = new Y.Doc();+ const sFrag = server.getXmlFragment('default');+ server.transact(() => sFrag.insert(0, [makeChild('jsxComponent', LINE)]));+ expect(findRaceDuplicatedSpans(sFrag, server.clientID, [LINE])).toBe(false);+ });++ test('empty over-multiplied line set short-circuits to NOT a race', () => {+ const server = new Y.Doc();+ const client = new Y.Doc();+ const sFrag = server.getXmlFragment('default');+ server.transact(() => sFrag.insert(0, [makeChild('jsxComponent', LINE)]));+ client.transact(() =>+ client.getXmlFragment('default').insert(0, [makeChild('rawMdxFallback', LINE)]),+ );+ mergeInto(server, client);+ // The provenance walk only runs on the pre-filter's over-multiplied lines;+ // an empty set means the growth pre-filter found nothing to adjudicate.+ expect(findRaceDuplicatedSpans(sFrag, server.clientID, [])).toBe(false);+ });+});diff --git a/packages/server/src/server-observers.ts b/packages/server/src/server-observers.tsindex 2876f84c0..85e2bb9be 100644--- a/packages/server/src/server-observers.ts+++ b/packages/server/src/server-observers.ts@@ -34,9 +34,11 @@ import {BridgeInvariantViolationError,BridgeMergeContentLossError,comparePmStructural,+ DUPLICATION_GATE_MIN_LINE_LENGTH,isParseEquivalentBridge,mergeThreeWay,normalizeBridge,+ overMultipliedBodyLines,prependFrontmatter,projectMergeBoundarySpace,reattachLeadingDocBoundary,@@ -45,7 +47,9 @@ import {} from '@inkeep/open-knowledge-core';import type { Schema } from '@tiptap/pm/model';import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';-import type * as Y from 'yjs';+// Value import (not `import type`): `carrierKind` uses `instanceof Y.XmlElement`+// to read a top-level child's node shape for the duplication gate.+import * as Y from 'yjs';import { attachQuiescenceTracker } from './bridge-quiescence.ts';import {assertBridgeInvariant,@@ -59,10 +63,13 @@ import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';import { computeMapDrivenBodySplice } from './map-driven-splice.ts';import {incrementBridgeMergeCheckpointCreated,+ incrementBridgeMergeContentGrowth,incrementBridgeMergeContentLoss,incrementBridgeSplitBrainRederives,incrementMapDrivenSpliceApplied,incrementMapDrivenSpliceFallback,+ incrementObserverADuplicationCheckpointCreated,+ incrementObserverADuplicationRederives,incrementObserverAPathBFires,incrementObserverAResidualMergeRuns,incrementProducerGuardCheckpointCreated,@@ -441,6 +448,138 @@ function settlesSplitBrain(settledText: string, md: string, normMdPre?: string):return settledText !== md && normalizeBridge(settledText) !== (normMdPre ?? normalizeBridge(md));}+/** Node-shape discriminant for a top-level fragment child. */+function carrierKind(child: Y.XmlElement | Y.XmlText | Y.XmlHook): string {+ if (child instanceof Y.XmlElement) return child.nodeName;+ if (child instanceof Y.XmlText) return '#text';+ return '#hook';+}++/**+ * Minting provenance of a fragment child. Y.js stores clientID+clock per+ * struct but NOT the transaction origin on the materialized item, so the+ * `_item` internal is the only recoverable provenance (y-tiptap /+ * y-prosemirror depend on the same internal). Isolated here so a Y.js+ * upgrade that changes the struct shape has exactly one site to re-verify;+ * `undefined` (unintegrated child or shape change) means "cannot attribute"+ * and callers must fail safe toward no destructive recovery.+ */+function mintingClientId(child: Y.XmlElement | Y.XmlText | Y.XmlHook): number | undefined {+ return (child as { _item?: { id?: { client: number } } | null })._item?.id?.client;+}++const collapseSpaces = (s: string): string => s.replace(/\s+/g, ' ').trim();++/**+ * Shared final reduction for carrier attribution: both bare-text forms drop+ * the inline-marker character set entirely. The markdown side cannot tell a+ * syntax marker from a literal char without parsing (`snake_case` vs+ * `_emphasis_`), and the XML side keeps literals — the only way the two+ * reductions agree on every input is to delete the marker chars from BOTH.+ * Attribution only needs a stable common form, not lossless text.+ */+const stripInlineMarkerChars = (s: string): string => s.replace(/[*_~`]+/g, '');++/**+ * Fragment-child XML serialization reduced to bare text: tags dropped, basic+ * entities unescaped, inline-marker chars dropped (shared reduction).+ * Carrier attribution compares markdown-derived lines against fragment+ * children, and the two serializations spell inline formatting differently+ * (`**bold**` vs `<strong>bold</strong>`), so both sides reduce to the same+ * plain-text form before the substring test.+ */+function xmlBareText(s: string): string {+ return collapseSpaces(+ stripInlineMarkerChars(+ s+ .replace(/<[^>]*>/g, '')+ .replace(/</g, '<')+ .replace(/>/g, '>')+ .replace(/"/g, '"')+ .replace(/&/g, '&'),+ ),+ );+}++/** Markdown body line reduced to bare text: link/image syntax keeps its label, escapes unwrap, inline-marker chars drop (shared reduction). */+function markdownBareText(line: string): string {+ return collapseSpaces(+ stripInlineMarkerChars(+ line.replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/\\([\\`*_{}[\]()#+\-.!><])/g, '$1'),+ ),+ );+}++/**+ * Provenance confirm for the Observer A duplication gate — the discriminator+ * between a server-vs-client CRDT race (recover) and a legitimate client+ * duplication such as a WYSIWYG paste of existing content (leave for+ * forward-propagation; recovery re-derives from Y.Text and would silently drop+ * the paste).+ *+ * Given the substantive body lines the growth pre-filter found over-multiplied+ * in the fragment relative to Y.Text, walk the top-level fragment children and+ * confirm the race by TWO joint signatures on the carriers of an over-multiplied+ * line:+ *+ * 1. Provenance split — the carriers span BOTH the server's own `doc.clientID`+ * (Observer B's re-derivation under `OBSERVER_SYNC_ORIGIN`) AND at least+ * one foreign clientID (a client insert). A duplicate can only form when+ * Observer B's re-derive of a span races a client insert of the same+ * content, so a genuine race always carries this split.+ * 2. Shape disagreement — the server carrier and the foreign carrier have+ * DIFFERENT node types. This is the load-bearing discriminator: the race is+ * a stale-view parse disagreement (the server sees the closed span as a+ * valid `jsxComponent`, the stale client sees it as a `rawMdxFallback`),+ * and item-preservation (bridge invariant: matching items are never+ * replaced) means a SAME-shape duplication would have deduped rather than+ * survived — so a surviving duplication with agreeing shapes is an+ * intentional client duplication (a paste), never this race. Anchoring on+ * shape (not `child.toString()` byte-equality — the carriers are+ * content-equivalent but never byte-equal) keeps the gate from dropping a+ * user's paste of a server-derived paragraph or component block.+ *+ * Provenance is read via `mintingClientId` (the `_item.id.client` internal —+ * see that helper for the upgrade-fragility note). A child that cannot be+ * attributed is skipped and the gate fails safe toward "not a race" — no+ * destructive recovery on an unresolvable provenance.+ */+export function findRaceDuplicatedSpans(+ xmlFragment: Y.XmlFragment,+ serverClientId: number,+ overMultipliedLines: readonly string[],+): boolean {+ if (overMultipliedLines.length === 0) return false;+ const children = xmlFragment.toArray();+ const childBareTexts = children.map((child) => xmlBareText(child.toString()));+ for (const line of overMultipliedLines) {+ // Both sides reduced to bare text so inline formatting (bold, code,+ // links) cannot hide a carrier. Stripping can shorten a line below the+ // substantive threshold ("**Go!**" -> "Go!"); such lines no longer+ // identify a span reliably, so they are skipped (fail-safe: no+ // destructive recovery on a weak anchor).+ const bareLine = markdownBareText(line);+ if (bareLine.length < DUPLICATION_GATE_MIN_LINE_LENGTH) continue;+ const serverKinds = new Set<string>();+ const foreignKinds = new Set<string>();+ for (let i = 0; i < children.length; i++) {+ const child = children[i];+ if (child === undefined || !childBareTexts[i]?.includes(bareLine)) continue;+ const client = mintingClientId(child);+ if (client === undefined) continue;+ if (client === serverClientId) serverKinds.add(carrierKind(child));+ else foreignKinds.add(carrierKind(child));+ }+ // Race iff a server carrier and a foreign carrier DISAGREE on node shape.+ for (const s of serverKinds) {+ for (const f of foreignKinds) {+ if (s !== f) return true;+ }+ }+ }+ return false;+}+/*** Set up server-side bidirectional observers between Y.XmlFragment and Y.Text.*@@ -491,7 +630,17 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidtimestamp: new Date().toISOString(),}),);- incrementBridgeMergeContentLoss();+ // Loss and growth verdicts share this handler (same error, same single+ // catch site) but chart on separate counters: growth is a content-GAIN+ // event and hiding it under the loss rate would mask which failure class+ // is moving. The recovery below (apply as-computed) is deliberately the+ // same for both: at the merge boundary there is no provenance, so a+ // doubled line may be two writers legitimately adding the same content —+ // discarding the merge would drop one side's edit. Preserve-everything ++ // alarm is the recovery; the provenance-confirmed duplication gate+ // earlier in the drain owns destructive recovery for the race case.+ if (err.info.which === 'growth') incrementBridgeMergeContentGrowth();+ else incrementBridgeMergeContentLoss();const shadow = opts.shadow?.();if (!shadow || !opts.docName) return;@@ -504,7 +653,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidcontents: preMergeBaseline,label: `Before concurrent merge @ ${new Date().toISOString()}`,branch,- metadata: { lostSubstrings: err.info.lostSubstrings },+ metadata: { lostSubstrings: err.info.lostSubstrings, which: err.info.which },}).then((sha) => {incrementBridgeMergeCheckpointCreated();@@ -567,6 +716,53 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void}};+ /**+ * Silent recovery-anchor checkpoint for a duplication-gate recovery. Mirrors+ * the producer-guard checkpoint shape: fire-and-forget, bounded-cardinality+ * metadata (a count, never content). `contents` is the pre-recovery doubled+ * fragment serialization, so the discarded doubled state stays on the+ * timeline if the re-derive were ever wrong.+ */+ const saveDuplicationCheckpoint = (contents: string, duplicatedLineCount: number): void => {+ const shadow = opts.shadow?.();+ if (!shadow || !opts.docName) return;+ const branch = opts.getBranch?.() ?? 'main';+ const contentRoot = opts.contentRoot ?? '';+ const docName = opts.docName;+ queueMicrotask(() => {+ saveInMemoryCheckpoint(shadow, contentRoot, {+ kind: 'observer-a-duplication',+ docName,+ contents,+ label: `Before duplication re-derive @ ${new Date().toISOString()}`,+ branch,+ metadata: { duplicatedLineCount },+ })+ .then((sha) => {+ incrementObserverADuplicationCheckpointCreated();+ console.warn(+ JSON.stringify({+ event: 'observer-a-duplication-checkpoint-created',+ docName,+ sha,+ kind: 'observer-a-duplication',+ timestamp: new Date().toISOString(),+ }),+ );+ })+ .catch((checkpointErr: unknown) => {+ const e =+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));+ console.warn('[Server Observer A] Duplication checkpoint write failed:', {+ docName,+ name: e.name,+ message: e.message,+ stack: e.stack?.split('\n').slice(0, 4).join('\n'),+ });+ });+ });+ };+// ─── Observer A: XmlFragment → Y.Text ─────────────────────// Two witnesses, one lifecycle. A single baseline variable here previously// conflated two incompatible surface contracts: gate 1 needs the canonical@@ -980,6 +1176,50 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidif (freshnessSafe) runProducerGuard(json as PmStructuralNode, body);const frontmatter = readCurrentFm();const md = prependFrontmatter(frontmatter, body);+ const currentText = ytext.toString();++ // Duplication gate (precedent #38, Y.Text-is-truth). A CRDT+ // double-materialization of a bridge-derived span (two writers+ // structurally replacing the same span, both inserts surviving the Y.js+ // merge) leaves the fragment serialization carrying a substantive body+ // line more times than the live Y.Text justifies; without this gate+ // Observer A serializes and persists the doubled bytes as authoritative+ // truth. The cheap growth pre-filter runs on every drain whose fragment+ // moved; only when it fires do we pay the O(children) provenance walk+ // that separates a server-vs-client race (recover) from a legitimate+ // same-client duplication such as a WYSIWYG paste-twice (leave for the+ // router to forward-propagate — recovery would drop the user's paste).+ //+ // On a confirmed race, move BOTH witnesses to the doubled `md` (the+ // diverged-attach witness shape) and enqueue a same-drain Observer B:+ // B's early-exit comparand no longer matches the clean Y.Text, so it+ // rebuilds the single-copy fragment from `parse(Y.Text)` and the doubled+ // `md` is never written to Y.Text. This runs BEFORE Gate 1 so it+ // pre-empts every write path uniformly (the field splice drains have+ // `md !== lastSyncedCanonicalMd`, so Gate 1 would not short-circuit them+ // anyway), and independently of the producer guard's freshness gate+ // (skipped on non-fresh drains) so it covers the drains the loss guard+ // never sees. STOP: this detects structurally and routes to re-derive —+ // it raises and catches no `BridgeMergeContentLossError`; its+ // observability is the `duplication-guard` split-brain site + the+ // dedicated counter + the `observer-a-duplication` checkpoint.+ const overMultiplied = overMultipliedBodyLines(+ md,+ currentText,+ DUPLICATION_GATE_MIN_LINE_LENGTH,+ );+ if (+ overMultiplied.length > 0 &&+ findRaceDuplicatedSpans(xmlFragment, doc.clientID, overMultiplied)+ ) {+ recordDivergedAttachBaselines(md);+ textDirty = true;+ recordSplitBrainRederive('duplication-guard');+ incrementObserverADuplicationRederives();+ saveDuplicationCheckpoint(md, overMultiplied.length);+ setActiveSpanAttributes({ 'observer.a.path': 'gated-duplication-rederive' });+ return;+ }// Gate 1 (fragment-unchanged): the fragment's canonical serialization is// identical to the recorded canonical witness. Two concerns split here.@@ -1050,7 +1290,9 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidreturn;}- const currentText = ytext.toString();+ // `currentText` was read once above the duplication gate; Y.Text is not+ // mutated between there and here (the gates above only read it), so the+ // snapshot is still current.// Already-in-sync gate: if Y.Text already matches XmlFragment (after// bridge normalization), just update baselines — the gate certifies adiff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.tsindex 5ea94dd72..dbcd1fd8a 100644--- a/packages/server/src/shadow-repo.test.ts+++ b/packages/server/src/shadow-repo.test.ts@@ -1092,6 +1092,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)}const result = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,maxBridgeMergeLoss: 3,maxProducerGuardLoss: 50,maxExternalChangeRescue: 50,@@ -1138,6 +1139,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)});const result = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,maxBridgeMergeLoss: 50,maxProducerGuardLoss: 3,maxExternalChangeRescue: 50,@@ -1175,6 +1177,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)const { gcCheckpointRefs } = await import('./shadow-repo.ts');const result = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,maxBridgeMergeLoss: 50,maxProducerGuardLoss: 50,maxExternalChangeRescue: 50,@@ -1220,6 +1223,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)});const result = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,maxBridgeMergeLoss: 0, // forces deletion of the typed checkpointmaxProducerGuardLoss: 0,maxExternalChangeRescue: 0,@@ -1297,6 +1301,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)}const result = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,maxBridgeMergeLoss: 50,maxProducerGuardLoss: 50,maxExternalChangeRescue: 50,@@ -1329,6 +1334,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)// refs must survive purely on the count cap (2), never the TTL — otherwise// a dormant repo could lose the anchor the chained history hangs from.const result = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,maxBridgeMergeLoss: 50,maxProducerGuardLoss: 50,maxExternalChangeRescue: 50,diff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.tsindex ac6dd13ee..de2542651 100644--- a/packages/server/src/shadow-repo.ts+++ b/packages/server/src/shadow-repo.ts@@ -725,6 +725,11 @@ export async function safetyCheckpoint(* content) at the serialize boundary. `contents` is the pre-loss source (the* last-good Y.Text); `construct` is a bounded, content-free locator of the* danger-space node types present.+ * - `observer-a-duplication` — Observer A's duplication gate found a+ * provenance-confirmed CRDT double-materialization of a bridge-derived span+ * and re-derived the fragment from Y.Text before it could persist.+ * `contents` is the pre-recovery doubled fragment serialization (the anchor+ * if the re-derive was wrong); `duplicatedLineCount` is a content-free count.* - `external-change-rescue` — an external disk write (reconcile-delete or* branch-switch path) would otherwise have discarded dirty Y.Doc content.* `contents` is the rescued in-memory markdown; `incomingDiskSha` names@@ -737,7 +742,7 @@ export type InMemoryCheckpointParams =contents: string;label: string;branch?: string;- metadata: { lostSubstrings: string[] };+ metadata: { lostSubstrings: string[]; which?: string };}| {kind: 'producer-guard-loss';@@ -747,6 +752,14 @@ export type InMemoryCheckpointParams =branch?: string;metadata: { construct: string };}+ | {+ kind: 'observer-a-duplication';+ docName: string;+ contents: string;+ label: string;+ branch?: string;+ metadata: { duplicatedLineCount: number };+ }| {kind: 'external-change-rescue';docName: string;@@ -814,6 +827,14 @@ export async function saveInMemoryCheckpoint(metadata: params.metadata,};break;+ case 'observer-a-duplication':+ parsed = {+ kind: 'observer-a-duplication',+ docName: params.docName,+ size,+ metadata: params.metadata,+ };+ break;case 'external-change-rescue':parsed = {kind: 'external-change-rescue',@@ -994,6 +1015,13 @@ export interface CheckpointRetentionPolicy {* vice versa). Default 50.*/maxProducerGuardLoss: number;+ /**+ * Maximum `observer-a-duplication` checkpoints to keep per branch. Written+ * when Observer A's duplication gate recovers a provenance-confirmed CRDT+ * double-materialization. Its own budget so a stuck race cannot evict+ * merge-drop or serializer-corruption recovery anchors. Default 50.+ */+ maxObserverADuplication: number;/*** Maximum `external-change-rescue` checkpoints to keep per branch. These* are written on reconcile-delete / branch-switch disk-overrode-memory@@ -1024,6 +1052,7 @@ export interface CheckpointRetentionPolicy {export const DEFAULT_CHECKPOINT_RETENTION: CheckpointRetentionPolicy = {maxBridgeMergeLoss: 50,maxProducerGuardLoss: 50,+ maxObserverADuplication: 50,maxExternalChangeRescue: 50,maxAutoConsolidation: 2,ttlMs: 30 * 24 * 60 * 60 * 1000,@@ -1033,6 +1062,7 @@ export interface CheckpointGcResult {scanned: number;deletedBridgeMergeLoss: number;deletedProducerGuardLoss: number;+ deletedObserverADuplication: number;deletedExternalChangeRescue: number;deletedAutoConsolidation: number;retained: number;@@ -1057,6 +1087,7 @@ export async function gcCheckpointRefs(scanned: 0,deletedBridgeMergeLoss: 0,deletedProducerGuardLoss: 0,+ deletedObserverADuplication: 0,deletedExternalChangeRescue: 0,deletedAutoConsolidation: 0,retained: 0,@@ -1111,6 +1142,7 @@ export async function gcCheckpointRefs(type TypedKind =| 'bridge-merge-loss'| 'producer-guard-loss'+ | 'observer-a-duplication'| 'external-change-rescue'| 'auto-consolidation';interface Entry {@@ -1137,6 +1169,7 @@ export async function gcCheckpointRefs(const byKind: Record<TypedKind, Entry[]> = {'bridge-merge-loss': [],'producer-guard-loss': [],+ 'observer-a-duplication': [],'external-change-rescue': [],'auto-consolidation': [],};@@ -1157,6 +1190,7 @@ export async function gcCheckpointRefs(counter:| 'deletedBridgeMergeLoss'| 'deletedProducerGuardLoss'+ | 'deletedObserverADuplication'| 'deletedExternalChangeRescue'| 'deletedAutoConsolidation',// auto-consolidation is count-only: TTL must never be able to reap every@@ -1187,6 +1221,11 @@ export async function gcCheckpointRefs(policy.maxProducerGuardLoss,'deletedProducerGuardLoss',);+ planDeletions(+ byKind['observer-a-duplication'],+ policy.maxObserverADuplication,+ 'deletedObserverADuplication',+ );planDeletions(byKind['external-change-rescue'],policy.maxExternalChangeRescue,