Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.tsx
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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: string
export 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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(/&lt;/g, '<')
+ .replace(/&gt;/g, '>')
+ .replace(/&quot;/g, '"')
+ .replace(/&amp;/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): () => void
timestamp: 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): () => void
contents: 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): () => void
if (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): () => void
return;
}
- 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 a
diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.ts
index 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 checkpoint
maxProducerGuardLoss: 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.ts
index 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,