Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): spurious split-brain telemetry on space keystrokes (#2418)

Nick Gomez41fb8cd622cd
diff --git a/.changeset/typing-rederive-telemetry.md b/.changeset/typing-rederive-telemetry.md
new file mode 100644
index 000000000..97c8a5d44
--- /dev/null
+++ b/.changeset/typing-rederive-telemetry.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Typing into a document that carries organic markdown forms (like a list whose next paragraph starts without a blank line) no longer emits spurious `bridge-split-brain-rederive` telemetry on space keystrokes. The bridge health check now treats trailing line whitespace — a byte shape the serializer already declares insignificant — as the documented normalization it is, while genuine divergence keeps failing loud. Keystroke-granularity coverage (per-character transactions, zero-gap bursts, two-peer concurrent typing) is now part of the integration and fuzz suites.
diff --git a/packages/app/tests/integration/keystroke-granularity.test.ts b/packages/app/tests/integration/keystroke-granularity.test.ts
new file mode 100644
index 000000000..e759d0f79
--- /dev/null
+++ b/packages/app/tests/integration/keystroke-granularity.test.ts
@@ -0,0 +1,265 @@
+/**
+ * Keystroke-granularity bridge health — char-by-char edits through the live
+ * server observers with warn-channel-silence assertions.
+ *
+ * Character-granularity editing creates intermediate states single-shot
+ * test edits never produce: every keystroke is its own transaction, drain,
+ * and settlement. A paragraph momentarily ending in a just-typed space has
+ * no round-trip-stable byte spelling (the serializer deliberately emits
+ * paragraph-trailing spaces raw; parse strips them), so on docs resting
+ * beyond byte tolerance the settlement's parse-equivalence rescue must
+ * treat trailing line whitespace as the normalization the byte layer and
+ * serializer already declare it to be — otherwise every space keystroke on
+ * an organic lazy-continuation doc reports split-brain.
+ *
+ * No other tier reaches this combination: the fuzz generator's
+ * type-chars op also types char-by-char but asserts only convergence and
+ * content preservation — not warn-channel silence — e2e keystrokes cannot
+ * observe the server-side warn channels, and the single-shot integration
+ * suites settle exactly once.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { setTimeout as wait } from 'node:timers/promises';
+import * as Y from 'yjs';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ createTestClients,
+ createTestServer,
+ pollUntil,
+ type TestClient,
+ type TestServer,
+} from './test-harness';
+
+let server: TestServer;
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+const HEALTH_EVENT_RE = /bridge-invariant-violation|bridge-split-brain-rederive/;
+
+const LAZY_DOC = `# Keystroke granularity
+
+**Why not now:**
+- First bullet
+- Second bullet
+- Third bullet
+**Trigger to revisit:** This bold-label paragraph immediately follows the list.
+`;
+const LAZY_SLICE = '- Third bullet\n**Trigger to revisit:**';
+
+const CANONICAL_DOC = '# Keystroke granularity\n\nA plain paragraph.\n';
+
+/** Health events for one docName while `fn` runs (console.warn capture). */
+async function captureHealthEvents(docName: string, fn: () => Promise<void>): Promise<string[]> {
+ const origWarn = console.warn;
+ const lines: string[] = [];
+ console.warn = ((...args: unknown[]) => {
+ lines.push(args.map(String).join(' '));
+ origWarn(...args);
+ }) as typeof console.warn;
+ try {
+ await fn();
+ } finally {
+ console.warn = origWarn;
+ }
+ return lines.filter((l) => HEALTH_EVENT_RE.test(l) && l.includes(docName));
+}
+
+/** Append a paragraph and type the rest of `text` one char per transaction. */
+async function typeNewParagraph(client: TestClient, text: string, gapMs: number): Promise<void> {
+ const p = new Y.XmlElement('paragraph');
+ const t = new Y.XmlText();
+ t.applyDelta([{ insert: text.slice(0, 1) }]);
+ p.insert(0, [t]);
+ client.fragment.push([p]);
+ for (const ch of text.slice(1)) {
+ if (gapMs > 0) await wait(gapMs);
+ client.doc.transact(() => {
+ t.applyDelta([{ retain: t.length }, { insert: ch }]);
+ });
+ }
+}
+
+/** Plain text of a Y.XmlText from its delta — `.toString()` renders inline
+ * marks as XML tags, so indexOf on it does NOT map to a Yjs retain offset. */
+function plainText(t: Y.XmlText): string {
+ let s = '';
+ for (const op of t.toDelta() as Array<{ insert?: unknown }>) {
+ if (typeof op.insert === 'string') s += op.insert;
+ else if (op.insert !== undefined) s += '';
+ }
+ return s;
+}
+
+function findXmlText(node: Y.XmlFragment | Y.XmlElement, needle: string): Y.XmlText | null {
+ for (let i = 0; i < node.length; i++) {
+ const child = node.get(i);
+ if (child instanceof Y.XmlText) {
+ if (child.toString().includes(needle)) return child;
+ } else if (child instanceof Y.XmlElement) {
+ const found = findXmlText(child, needle);
+ if (found) return found;
+ }
+ }
+ return null;
+}
+
+async function seedLazyDoc(client: TestClient): Promise<void> {
+ client.doc.transact(() => {
+ client.ytext.insert(0, LAZY_DOC);
+ });
+ await pollUntil(() => client.ytext.toString().includes('Trigger to revisit'), 5000);
+ await wait(500);
+}
+
+describe('keystroke granularity: resting beyond-tolerance docs', () => {
+ test('char-by-char append typing settles without health-channel noise', async () => {
+ const clients = await createTestClients(server.port, { count: 1 });
+ try {
+ await seedLazyDoc(clients[0]);
+ const events = await captureHealthEvents(clients[0].docName, async () => {
+ await typeNewParagraph(clients[0], 'Vetted live typing.', 30);
+ await pollUntil(() => clients[0].ytext.toString().includes('Vetted live typing.'), 5000);
+ await wait(600);
+ });
+ expect(events).toHaveLength(0);
+ expect(clients[0].ytext.toString()).toContain(LAZY_SLICE);
+ } finally {
+ for (const c of clients) c.cleanup();
+ }
+ });
+
+ test('a zero-gap keystroke burst settles without health-channel noise', async () => {
+ const clients = await createTestClients(server.port, { count: 1 });
+ try {
+ await seedLazyDoc(clients[0]);
+ const events = await captureHealthEvents(clients[0].docName, async () => {
+ await typeNewParagraph(clients[0], 'burst typed words here.', 0);
+ await pollUntil(
+ () => clients[0].ytext.toString().includes('burst typed words here.'),
+ 5000,
+ );
+ await wait(600);
+ });
+ expect(events).toHaveLength(0);
+ expect(clients[0].ytext.toString()).toContain(LAZY_SLICE);
+ } finally {
+ for (const c of clients) c.cleanup();
+ }
+ });
+
+ test('two peers typing concurrently converge without health-channel noise', async () => {
+ const clients = await createTestClients(server.port, { count: 2 });
+ try {
+ await seedLazyDoc(clients[0]);
+ await pollUntil(() => clients[1].ytext.toString().includes('Trigger to revisit'), 5000);
+ const events = await captureHealthEvents(clients[0].docName, async () => {
+ await Promise.all([
+ typeNewParagraph(clients[0], 'peer one typed this sentence.', 25),
+ typeNewParagraph(clients[1], 'peer two typed another one.', 35),
+ ]);
+ for (const c of clients) {
+ await pollUntil(
+ () =>
+ c.ytext.toString().includes('peer one typed this sentence.') &&
+ c.ytext.toString().includes('peer two typed another one.'),
+ 8000,
+ );
+ }
+ await wait(600);
+ });
+ expect(events).toHaveLength(0);
+ const [a, b] = clients.map((c) => c.ytext.toString());
+ expect(a).toBe(b);
+ expect(a).toContain(LAZY_SLICE);
+ } finally {
+ for (const c of clients) c.cleanup();
+ }
+ });
+
+ test('mid-paragraph insertion via delta offsets stays clean and byte-faithful', async () => {
+ const clients = await createTestClients(server.port, { count: 1 });
+ try {
+ await seedLazyDoc(clients[0]);
+ const t = findXmlText(clients[0].fragment, 'glued');
+ const target = t ?? findXmlText(clients[0].fragment, 'immediately follows');
+ expect(target).not.toBeNull();
+ if (!target) return;
+ const offset = plainText(target).indexOf('immediately');
+ expect(offset).toBeGreaterThan(-1);
+ const events = await captureHealthEvents(clients[0].docName, async () => {
+ for (const [i, ch] of Array.from('INS ').entries()) {
+ if (i > 0) await wait(25);
+ clients[0].doc.transact(() => {
+ target.applyDelta([{ retain: offset + i }, { insert: ch }]);
+ });
+ }
+ await pollUntil(() => clients[0].ytext.toString().includes('INS immediately'), 5000);
+ await wait(600);
+ });
+ expect(events).toHaveLength(0);
+ expect(clients[0].ytext.toString()).toContain(LAZY_SLICE);
+ } finally {
+ for (const c of clients) c.cleanup();
+ }
+ });
+});
+
+describe('keystroke granularity: canonical docs (controls)', () => {
+ test('char typing of markdown-significant literals stays clean and escapes correctly', async () => {
+ const clients = await createTestClients(server.port, { count: 1 });
+ try {
+ clients[0].doc.transact(() => {
+ clients[0].ytext.insert(0, CANONICAL_DOC);
+ });
+ await pollUntil(() => clients[0].ytext.toString().includes('plain paragraph'), 5000);
+ await wait(400);
+ const events = await captureHealthEvents(clients[0].docName, async () => {
+ for (const literal of ['**bold**', '| pipe | row |', '<br />']) {
+ await typeNewParagraph(clients[0], literal, 0);
+ }
+ await pollUntil(() => clients[0].ytext.toString().includes('pipe'), 5000);
+ await wait(600);
+ });
+ expect(events).toHaveLength(0);
+ // Typed literals survive as literals through a fresh parse: the bytes
+ // must not have become live constructs.
+ const bytes = clients[0].ytext.toString();
+ expect(bytes).toContain('bold');
+ expect(bytes).toContain('pipe');
+ } finally {
+ for (const c of clients) c.cleanup();
+ }
+ });
+
+ test('char-by-char source-side deletion back through a table row stays clean', async () => {
+ const clients = await createTestClients(server.port, { count: 1 });
+ try {
+ const md = '# Del\n\n| a |\n| - |\n| b |\n';
+ clients[0].doc.transact(() => {
+ clients[0].ytext.insert(0, md);
+ });
+ await pollUntil(() => clients[0].ytext.toString().includes('| b |'), 5000);
+ await wait(400);
+ const events = await captureHealthEvents(clients[0].docName, async () => {
+ // Delete the last row one char per transaction (backspace cadence).
+ for (let i = 0; i < '| b |\n'.length; i++) {
+ await wait(20);
+ clients[0].doc.transact(() => {
+ clients[0].ytext.delete(clients[0].ytext.length - 1, 1);
+ });
+ }
+ await wait(600);
+ });
+ expect(events).toHaveLength(0);
+ expect(clients[0].ytext.toString()).toContain('| - |');
+ } finally {
+ for (const c of clients) c.cleanup();
+ }
+ });
+});
diff --git a/packages/app/tests/stress/bridge-convergence.fuzz.test.ts b/packages/app/tests/stress/bridge-convergence.fuzz.test.ts
index d519b958c..401e73f33 100644
--- a/packages/app/tests/stress/bridge-convergence.fuzz.test.ts
+++ b/packages/app/tests/stress/bridge-convergence.fuzz.test.ts
@@ -95,6 +95,7 @@ type Rng = ReturnType<typeof createPRNG>;
type Op =
| { kind: 'wysiwyg-type'; clientIdx: number; text: string; marker: string }
+ | { kind: 'type-chars'; clientIdx: number; text: string; marker: string }
| { kind: 'source-type'; clientIdx: number; text: string; marker: string }
| {
kind: 'agent-write';
@@ -146,7 +147,7 @@ function randomShortText(rng: Rng): string {
/**
* Generate ops at the rebalanced distribution (server-authoritative):
- * wysiwyg:25%, source:15%, agent-write:15%, agent-patch:8%, agent-undo:3%,
+ * wysiwyg:17%, type-chars:8%, source:15%, agent-write:15%, agent-patch:8%, agent-undo:3%,
* external-change:8%, chunked-source-paste:3%, jsx-block:3%, large-embed:3%,
* sync-pause:6%, sync-resume:8%, wait:3%. Source-type and external-change
* elevated from theatre rates (0.5% each) to validate the symmetric Observer B
@@ -167,10 +168,18 @@ function generateOps(rng: Rng, clientCount: number, opCount: number): Op[] {
// Rebalanced distribution (server-authoritative) — see the
// function docblock for the full per-kind percentages (jsx-block +
// large-embed added at 3% each for the corrupting constructs).
- if (roll < 0.25) {
- // wysiwyg-type (25%): append a paragraph to XmlFragment
+ if (roll < 0.17) {
+ // wysiwyg-type (17%): append a paragraph to XmlFragment
const marker = `M${markerIdx++}-${randomShortText(rng)}`;
ops.push({ kind: 'wysiwyg-type', clientIdx, text: marker, marker });
+ } else if (roll < 0.25) {
+ // type-chars (8%, carved from wysiwyg-type): the same paragraph
+ // append delivered one character per transaction, keystroke-style.
+ // Multi-word marker text guarantees trailing-space transients — the
+ // states whole-block ops structurally never produce and the
+ // settlement health checks must absorb on resting-divergent docs.
+ const marker = `M${markerIdx++}-${randomShortText(rng)}`;
+ ops.push({ kind: 'type-chars', clientIdx, text: marker, marker });
} else if (roll < 0.4) {
// source-type (15%): Y.Text write simulating CodeMirror input.
// Elevated from 0.5% to exercise symmetric Observer B path under
@@ -293,6 +302,24 @@ async function applyOp(
client.fragment.push([paragraph]);
break;
}
+ case 'type-chars': {
+ const client = clients[op.clientIdx];
+ if (!client) return;
+ const paragraph = new Y.XmlElement('paragraph');
+ const ytext = new Y.XmlText();
+ ytext.applyDelta([{ insert: op.text.slice(0, 1) }]);
+ paragraph.insert(0, [ytext]);
+ client.fragment.push([paragraph]);
+ for (const ch of op.text.slice(1)) {
+ // Separate transactions with a yield between them so each keystroke
+ // gets its own drain + settlement instead of coalescing into one.
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ client.doc.transact(() => {
+ ytext.applyDelta([{ retain: ytext.length }, { insert: ch }]);
+ });
+ }
+ break;
+ }
case 'source-type': {
const client = clients[op.clientIdx];
if (!client) return;
@@ -569,6 +596,7 @@ function snapshotClients(clients: TestClient[]): Array<{ ytext: string; fragment
const ALL_OP_KINDS = [
'wysiwyg-type',
+ 'type-chars',
'source-type',
'agent-write',
'agent-patch',
@@ -587,7 +615,7 @@ const WRITE_SURFACE_TO_OP_KIND: Record<string, readonly string[]> = {
'agent-write-md': ['agent-write'],
'agent-patch': ['agent-patch'],
'agent-undo': ['agent-undo'],
- 'observer-a-sync': ['wysiwyg-type'],
+ 'observer-a-sync': ['wysiwyg-type', 'type-chars'],
'observer-b-sync': ['source-type'],
'file-watcher': ['external-change'],
// Chunked Source paste: same source-codemirror-typing write surface as source-type, but a
@@ -836,6 +864,7 @@ describe('bridge-convergence fuzzer (FR-17)', () => {
const updateExpectedBody = (op: Op): void => {
switch (op.kind) {
case 'wysiwyg-type':
+ case 'type-chars':
case 'source-type':
// Observer A (wysiwyg) / Observer B (source) serializes the new
// paragraph with a double-newline separator after the existing body.
@@ -917,6 +946,7 @@ describe('bridge-convergence fuzzer (FR-17)', () => {
// Update marker tracking AFTER the op succeeds (oracle d prefix set).
if (
op.kind === 'wysiwyg-type' ||
+ op.kind === 'type-chars' ||
op.kind === 'source-type' ||
op.kind === 'agent-write'
) {
diff --git a/packages/core/src/bridge/parse-equivalence.ts b/packages/core/src/bridge/parse-equivalence.ts
index 27ff79a38..46cb6a6d8 100644
--- a/packages/core/src/bridge/parse-equivalence.ts
+++ b/packages/core/src/bridge/parse-equivalence.ts
@@ -9,6 +9,10 @@ function stripDocBoundary(body: string): string {
return body.replace(/^\n+/, '').replace(/\n+$/, '');
}
+function stripTrailingLineWhitespace(body: string): string {
+ return body.replace(/[ \t]+$/gm, '');
+}
+
/** Leading ordered-list marker digits (after optional indent), canonicalized
* before skeletonizing so remark-stringify's lazy-list renumbering
* (`1.`/`1.` → `1.`/`2.`) doesn't read as a content substitution in the
@@ -69,7 +73,10 @@ export function isParseEquivalentBridge(
}
return false;
}
- if (stripDocBoundary(canonicalLeftBody) !== stripDocBoundary(rightSplit.body)) {
+ if (
+ stripDocBoundary(stripTrailingLineWhitespace(canonicalLeftBody)) !==
+ stripDocBoundary(stripTrailingLineWhitespace(rightSplit.body))
+ ) {
return false;
}
return isSubsequence(contentSkeleton(leftSplit.body), contentSkeleton(canonicalLeftBody));