Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): doc-edge blank-run parity across observer gates (#3187)

Nick Gomezc7f9b6170670
diff --git a/.changeset/doc-edge-blank-run-parity.md b/.changeset/doc-edge-blank-run-parity.md
new file mode 100644
index 000000000..3a1b70f4e
--- /dev/null
+++ b/.changeset/doc-edge-blank-run-parity.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Blank lines at the very top or bottom of a document now stay in sync between the visual editor and markdown source in both directions. Previously they only propagated when added in the visual editor: blank lines typed in source mode (or arriving from disk or an agent) never appeared in any collaborator's visual editor, deleting them in source mode left phantom blank paragraphs behind, and deleting them in the visual editor never reached the file. On frontmatter-bearing documents, blank lines added above the first paragraph now survive too, with the separator line below the frontmatter kept intact. This also fixes a lock-up where a document whose two representations disagreed about an edge blank line would silently stop showing source-mode edits in the visual editor and revert visual-editor deletions.
diff --git a/knip.config.ts b/knip.config.ts
index 13582ee18..f004e6bc3 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -123,7 +123,9 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
project: 'src/**',
- ignoreDependencies: ['@types/shell-quote'],
+ ignoreDependencies: [
+ '@types/shell-quote',
+ ],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
diff --git a/packages/app/package.json b/packages/app/package.json
index 41f1d2238..440cc8e66 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -27,7 +27,7 @@
"measure:stress": "bash scripts/measure-stress.sh",
"measure:sweep": "bash scripts/measure-sweep.sh",
"perf:compare": "bash scripts/perf-compare.sh",
- "test:e2e": "playwright test tests/stress/ux-interactions.e2e.ts tests/stress/file-tree-create.e2e.ts tests/stress/file-tree-drag-to-root.e2e.ts tests/stress/file-tree-deselect-to-root.e2e.ts tests/stress/create-then-rename-editable.e2e.ts tests/stress/find-replace.e2e.ts tests/stress/editor-tabs.e2e.ts tests/stress/editor-split-view.e2e.ts tests/stress/crdt-stress.e2e.ts tests/stress/slash-command.e2e.ts tests/stress/paste-fidelity.e2e.ts tests/stress/fr-7a-disconnect-source-mode.e2e.ts tests/stress/docs-open.e2e.ts tests/stress/frozen-table-headers.e2e.ts tests/stress/asset-embed.e2e.ts tests/stress/asset-embed-advanced.e2e.ts tests/stress/asset-click-dispatch.e2e.ts tests/stress/handoff.e2e.ts tests/stress/multi-agent-presence.e2e.ts tests/stress/editor-mode-persistence.e2e.ts tests/stress/lint-config-toggle.e2e.ts tests/stress/plugin-enable-notice.e2e.ts tests/stress/schema-edit-fields-view.e2e.ts tests/stress/sidebar-search-pill.e2e.ts tests/stress/navigation-history.e2e.ts tests/stress/command-palette-semantic.e2e.ts tests/stress/agent-activity-panel.e2e.ts tests/stress/drop-pipeline-auto-open.e2e.ts tests/stress/command-palette-flicker.e2e.ts tests/stress/cm6-list-hanging-indent.e2e.ts tests/stress/ng7-rapid-nav-coherence.e2e.ts tests/stress/reveal-on-activate.e2e.ts tests/stress/selection-indicator.e2e.ts tests/stress/new-file-cross-doc-bleed.e2e.ts tests/stress/editor-mode-flip-cross-doc-bleed.e2e.ts tests/stress/editor-area-viewport-resize.e2e.ts tests/stress/qa-sidebar-responsive.e2e.ts tests/stress/prd-6955-reassertion-repro.e2e.ts tests/stress/prd-6955-reassertion-wedge.e2e.ts tests/stress/prd-6914-repro.e2e.ts tests/stress/showall-lazy-tree.e2e.ts tests/stress/tabs-component-strip.e2e.ts tests/stress/source-find-scroll.e2e.ts tests/stress/harness-app-warmth.e2e.ts tests/stress/qa-canary-authoring-both-modes.e2e.ts tests/stress/qa-canary-live-typing.e2e.ts tests/stress/keystroke-cadence-danger-space.e2e.ts tests/stress/jsx-unregistered-backspace-delete.e2e.ts tests/stress/jsx-unregistered-ime-concurrent.e2e.ts tests/stress/jsx-backspace-delete.e2e.ts tests/stress/link-authoring-bytes.e2e.ts tests/stress/link-authoring-apex.e2e.ts tests/stress/command-palette-parity.e2e.ts tests/stress/settings-search.e2e.ts tests/stress/chip-popover-positioning.e2e.ts tests/stress/docs-open-scroll-restore.e2e.ts tests/stress/file-tree-decoration-chip-strip-repro.e2e.ts tests/stress/grip-click-nodeselect.e2e.ts tests/stress/jsx-halo-semantics.e2e.ts tests/stress/jsx-image-body-click.e2e.ts tests/stress/jsx-prop-panel-placeholder.e2e.ts tests/stress/jsx-range-encompass-halo.e2e.ts tests/stress/jsx-wildcard-convert.e2e.ts tests/stress/markdown-lint.e2e.ts tests/stress/frontmatter-schema-badge.e2e.ts tests/stress/unified-problems.e2e.ts tests/stress/mid-type-recovery.e2e.ts tests/stress/observer-a-multi-client.e2e.ts tests/stress/outline-toolbar-occlusion.e2e.ts tests/stress/quiet-tree-hidden-doc.e2e.ts tests/stress/raw-mdx-fallback-onblur-upgrade.e2e.ts tests/stress/rename-noext-probe.e2e.ts tests/stress/show-ok-folders.e2e.ts tests/stress/source-polish.e2e.ts tests/stress/warm-skeleton-scroll-restore.e2e.ts tests/stress/props-toggle-scroll-preserve.e2e.ts tests/stress/yjs-no-dual-import.e2e.ts tests/stress/slash-command-auto-open.e2e.ts tests/stress/graph-panel-surfaces.e2e.ts tests/stress/clipboard-relative-url-source-fallback.e2e.ts tests/stress/asset-embed-real-fidelity.e2e.ts tests/stress/prop-upload.e2e.ts tests/stress/rename-content-preservation.e2e.ts tests/stress/rename-consolidation.e2e.ts tests/stress/outline-active-heading.e2e.ts tests/stress/outline-navigation.e2e.ts tests/stress/prd-7627-default-swatch.e2e.ts tests/stress/clipboard-dollar-math-source-fallback.e2e.ts tests/stress/source-mode-undo-keymap.e2e.ts tests/stress/timeline-recovered-restore.e2e.ts tests/stress/blank-line-preservation.e2e.ts tests/stress/landing-helpers.e2e.ts tests/stress/mode-switch-landing.e2e.ts tests/stress/mode-switch-ordinal-divergence.e2e.ts tests/stress/comment-annotation-visibility.e2e.ts",
+ "test:e2e": "playwright test tests/stress/ux-interactions.e2e.ts tests/stress/file-tree-create.e2e.ts tests/stress/file-tree-drag-to-root.e2e.ts tests/stress/file-tree-deselect-to-root.e2e.ts tests/stress/create-then-rename-editable.e2e.ts tests/stress/find-replace.e2e.ts tests/stress/editor-tabs.e2e.ts tests/stress/crdt-stress.e2e.ts tests/stress/slash-command.e2e.ts tests/stress/paste-fidelity.e2e.ts tests/stress/fr-7a-disconnect-source-mode.e2e.ts tests/stress/docs-open.e2e.ts tests/stress/frozen-table-headers.e2e.ts tests/stress/asset-embed.e2e.ts tests/stress/asset-embed-advanced.e2e.ts tests/stress/asset-click-dispatch.e2e.ts tests/stress/handoff.e2e.ts tests/stress/multi-agent-presence.e2e.ts tests/stress/editor-mode-persistence.e2e.ts tests/stress/lint-config-toggle.e2e.ts tests/stress/plugin-enable-notice.e2e.ts tests/stress/schema-edit-fields-view.e2e.ts tests/stress/sidebar-search-pill.e2e.ts tests/stress/navigation-history.e2e.ts tests/stress/command-palette-semantic.e2e.ts tests/stress/agent-activity-panel.e2e.ts tests/stress/drop-pipeline-auto-open.e2e.ts tests/stress/command-palette-flicker.e2e.ts tests/stress/cm6-list-hanging-indent.e2e.ts tests/stress/ng7-rapid-nav-coherence.e2e.ts tests/stress/reveal-on-activate.e2e.ts tests/stress/selection-indicator.e2e.ts tests/stress/new-file-cross-doc-bleed.e2e.ts tests/stress/editor-mode-flip-cross-doc-bleed.e2e.ts tests/stress/editor-area-viewport-resize.e2e.ts tests/stress/qa-sidebar-responsive.e2e.ts tests/stress/prd-6955-reassertion-repro.e2e.ts tests/stress/prd-6955-reassertion-wedge.e2e.ts tests/stress/prd-6914-repro.e2e.ts tests/stress/showall-lazy-tree.e2e.ts tests/stress/tabs-component-strip.e2e.ts tests/stress/source-find-scroll.e2e.ts tests/stress/harness-app-warmth.e2e.ts tests/stress/qa-canary-authoring-both-modes.e2e.ts tests/stress/qa-canary-live-typing.e2e.ts tests/stress/keystroke-cadence-danger-space.e2e.ts tests/stress/jsx-unregistered-backspace-delete.e2e.ts tests/stress/jsx-unregistered-ime-concurrent.e2e.ts tests/stress/jsx-backspace-delete.e2e.ts tests/stress/link-authoring-bytes.e2e.ts tests/stress/link-authoring-apex.e2e.ts tests/stress/command-palette-parity.e2e.ts tests/stress/settings-search.e2e.ts tests/stress/chip-popover-positioning.e2e.ts tests/stress/docs-open-scroll-restore.e2e.ts tests/stress/file-tree-decoration-chip-strip-repro.e2e.ts tests/stress/grip-click-nodeselect.e2e.ts tests/stress/jsx-halo-semantics.e2e.ts tests/stress/jsx-image-body-click.e2e.ts tests/stress/jsx-prop-panel-placeholder.e2e.ts tests/stress/jsx-range-encompass-halo.e2e.ts tests/stress/jsx-wildcard-convert.e2e.ts tests/stress/markdown-lint.e2e.ts tests/stress/frontmatter-schema-badge.e2e.ts tests/stress/unified-problems.e2e.ts tests/stress/mid-type-recovery.e2e.ts tests/stress/observer-a-multi-client.e2e.ts tests/stress/outline-toolbar-occlusion.e2e.ts tests/stress/quiet-tree-hidden-doc.e2e.ts tests/stress/raw-mdx-fallback-onblur-upgrade.e2e.ts tests/stress/rename-noext-probe.e2e.ts tests/stress/show-ok-folders.e2e.ts tests/stress/source-polish.e2e.ts tests/stress/warm-skeleton-scroll-restore.e2e.ts tests/stress/props-toggle-scroll-preserve.e2e.ts tests/stress/yjs-no-dual-import.e2e.ts tests/stress/graph-panel-surfaces.e2e.ts tests/stress/asset-embed-real-fidelity.e2e.ts tests/stress/rename-content-preservation.e2e.ts tests/stress/rename-consolidation.e2e.ts tests/stress/outline-active-heading.e2e.ts tests/stress/outline-navigation.e2e.ts tests/stress/prd-7627-default-swatch.e2e.ts tests/stress/clipboard-dollar-math-source-fallback.e2e.ts tests/stress/source-mode-undo-keymap.e2e.ts tests/stress/timeline-recovered-restore.e2e.ts tests/stress/blank-line-preservation.e2e.ts tests/stress/landing-helpers.e2e.ts tests/stress/mode-switch-landing.e2e.ts tests/stress/mode-switch-ordinal-divergence.e2e.ts tests/stress/comment-annotation-visibility.e2e.ts tests/stress/qa-miles-edge-blanks.e2e.ts",
"test:e2e:install-browsers": "playwright install chromium webkit firefox",
"test:visual": "playwright test --config playwright.visual.config.ts",
"test:visual:update": "playwright test --config playwright.visual.config.ts --update-snapshots",
diff --git a/packages/app/tests/integration/doc-edge-blank-runs.test.ts b/packages/app/tests/integration/doc-edge-blank-runs.test.ts
index 461806354..2373ac46f 100644
--- a/packages/app/tests/integration/doc-edge-blank-runs.test.ts
+++ b/packages/app/tests/integration/doc-edge-blank-runs.test.ts
@@ -226,13 +226,13 @@ describe('doc-edge blank runs on the CRDT path', () => {
// not hold a doc-start run, so a run only the fragment has is precisely
// what it was never asked to carry, and it was dropped here.
//
- // The concurrent Y.Text keystroke is scaffolding to force that window, and
- // it does not reach the fragment under this gesture. That is a property of
- // the gesture, not of the blank run: the interior arm is the identical
- // transaction one index over, and it strands the keystroke exactly the same
- // way while its own run survives. Both arms assert every surface byte-exact
- // so a change to either behaviour fails loudly instead of passing over a
- // lost run.
+ // The concurrent Y.Text keystroke is scaffolding to force that window,
+ // and the settlement's enqueued re-derive carries it back into the
+ // fragment in the same drain (the split-brain request survives the
+ // witness tautology), so every surface converges byte-exact — the run
+ // AND the keystroke on both peers and disk. Both arms assert every
+ // surface byte-exact so a change to either behaviour fails loudly
+ // instead of passing over a lost run.
async function mergeSeam(insertAt: number, ytext: string, fragment: string): Promise<void> {
const clients = await seedDocument('Above.\n\nBelow.\n');
try {
@@ -262,8 +262,8 @@ describe('doc-edge blank runs on the CRDT path', () => {
}
}
- await mergeSeam(0, '\n\nAbove.\n\nBelow.!\n', '\n\nAbove.\n\nBelow.\n');
- await mergeSeam(1, 'Above.\n\n\n\nBelow.!\n', 'Above.\n\n\n\nBelow.\n');
+ await mergeSeam(0, '\n\nAbove.\n\nBelow.!\n', '\n\nAbove.\n\nBelow.!\n');
+ await mergeSeam(1, 'Above.\n\n\n\nBelow.!\n', 'Above.\n\n\n\nBelow.!\n');
});
test('an external write that carries a trailing run lands it in every fragment', async () => {
diff --git a/packages/app/tests/integration/qa-controls-probe.test.ts b/packages/app/tests/integration/qa-controls-probe.test.ts
new file mode 100644
index 000000000..b1690d5b1
--- /dev/null
+++ b/packages/app/tests/integration/qa-controls-probe.test.ts
@@ -0,0 +1,128 @@
+/**
+ * QA controls: classify the four FWD failures.
+ * C1: agent undo WITHOUT edge runs (was FWD-04's '' an edge-run effect?)
+ * C2: WYSIWYG DELETE (not undo) of a W1-authored tail run — does the
+ * deletion half of the doc-edge class propagate at all?
+ * C3: WYSIWYG last-paragraph delete on an IN-SYNC doc (DESTROY-A baseline).
+ */
+
+import { appendFileSync } from 'node:fs';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentWriteMd,
+ createTestClients,
+ createTestServer,
+ pollUntil,
+ serializeFragment,
+ 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 DIAG = process.env.QA_DIAG_OUT;
+function diag(probe: string, data: Record<string, unknown>): void {
+ if (!DIAG) return;
+ appendFileSync(DIAG, `${JSON.stringify({ probe, ...data })}\n`);
+}
+
+const para = () => new Y.XmlElement('paragraph');
+
+function countBlankLineNodes(fragment: Y.XmlFragment): number {
+ let count = 0;
+ for (let i = 0; i < fragment.length; i++) {
+ if (String(fragment.get(i)) === '<paragraph></paragraph>') count += 1;
+ }
+ return count;
+}
+
+async function settle(predicate: () => boolean, timeoutMs: number): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return true;
+ await wait(25);
+ }
+ return false;
+}
+
+async function seedDocument(raw: string): Promise<TestClient[]> {
+ const docName = `qa-ctrl-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ await agentWriteMd(server.port, raw, { docName, position: 'replace' });
+ await pollUntil(() => clients.every((c) => c.ytext.toString() === raw), 10_000);
+ return clients;
+}
+
+describe('classification controls', () => {
+ test('C2: WYSIWYG delete of a W1-authored tail run propagates to the source bytes', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ a.doc.transact(() => {
+ a.fragment.insert(a.fragment.length, [para(), para()]);
+ });
+ const withRun = 'Above.\n\nBelow.\n\n\n';
+ expect(
+ await settle(() => clients.every((c) => c.ytext.toString() === withRun), 6000),
+ 'precondition: run landed',
+ ).toBe(true);
+
+ // Select-and-delete the two empty paragraphs in the WYSIWYG.
+ a.doc.transact(() => {
+ a.fragment.delete(a.fragment.length - 2, 2);
+ });
+ const back = 'Above.\n\nBelow.\n';
+ const converged = await settle(() => clients.every((c) => c.ytext.toString() === back), 6000);
+ diag('C2', {
+ converged,
+ ytext: clients.map((c) => c.ytext.toString()),
+ blanks: clients.map((c) => countBlankLineNodes(c.fragment)),
+ });
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'WYSIWYG delete of the run reaches the bytes').toBe(back);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('C3: WYSIWYG delete of the last paragraph on an in-sync doc propagates normally', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const b = clients[1];
+ b.doc.transact(() => {
+ b.fragment.delete(b.fragment.length - 1, 1);
+ });
+ const expected = 'Above.\n';
+ const converged = await settle(
+ () => clients.every((c) => c.ytext.toString() === expected),
+ 6000,
+ );
+ diag('C3', {
+ converged,
+ ytext: clients.map((c) => c.ytext.toString()),
+ fragment: clients.map((c) => serializeFragment(c.fragment)),
+ });
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'in-sync paragraph delete baseline').toBe(expected);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/qa-fwd-regression-probe.test.ts b/packages/app/tests/integration/qa-fwd-regression-probe.test.ts
new file mode 100644
index 000000000..0624762e6
--- /dev/null
+++ b/packages/app/tests/integration/qa-fwd-regression-probe.test.ts
@@ -0,0 +1,386 @@
+/**
+ * QA probes: #3132 forward-direction verification + regressions the fix could
+ * plausibly have introduced (write-surface matrix, FM separator, floor-guard
+ * hazards, degenerate docs, concurrency, undo), plus the inverse-destruction
+ * mirror of the original Miles report.
+ */
+
+import { appendFileSync } from 'node:fs';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentWriteMd,
+ createTestClient,
+ createTestClients,
+ createTestServer,
+ pollUntil,
+ readTestDoc,
+ serializeFragment,
+ 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 DIAG = process.env.QA_DIAG_OUT;
+function diag(probe: string, data: Record<string, unknown>): void {
+ if (!DIAG) return;
+ appendFileSync(DIAG, `${JSON.stringify({ probe, ...data })}\n`);
+}
+
+const para = () => new Y.XmlElement('paragraph');
+
+function countBlankLineNodes(fragment: Y.XmlFragment): number {
+ let count = 0;
+ for (let i = 0; i < fragment.length; i++) {
+ if (String(fragment.get(i)) === '<paragraph></paragraph>') count += 1;
+ }
+ return count;
+}
+
+async function settle(predicate: () => boolean, timeoutMs: number): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return true;
+ await wait(25);
+ }
+ return false;
+}
+
+async function seedDocument(raw: string, fragmentBody = raw): Promise<TestClient[]> {
+ const docName = `qa-fwd-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ await agentWriteMd(server.port, raw, { docName, position: 'replace' });
+ await pollUntil(
+ () =>
+ clients.every(
+ (c) => c.ytext.toString() === raw && serializeFragment(c.fragment) === fragmentBody,
+ ),
+ 10_000,
+ );
+ return clients;
+}
+
+describe('#3132 forward verification + regression checks', () => {
+ test('FWD-02: one Enter at the tail stays below the carry floor; the second Enter carries both', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ a.doc.transact(() => {
+ a.fragment.insert(a.fragment.length, [para()]);
+ });
+ await wait(1500);
+ const afterOne = clients.map((c) => c.ytext.toString());
+ diag('FWD-02:one-enter', { afterOne });
+ for (const yt of afterOne) {
+ expect(yt, 'single Enter is affordance-ambiguous and must not write bytes').toBe(
+ 'Above.\n\nBelow.\n',
+ );
+ }
+ a.doc.transact(() => {
+ a.fragment.insert(a.fragment.length, [para()]);
+ });
+ const expected = 'Above.\n\nBelow.\n\n\n';
+ const converged = await settle(
+ () => clients.every((c) => c.ytext.toString() === expected),
+ 6000,
+ );
+ diag('FWD-02:two-enters', { converged, ytext: clients.map((c) => c.ytext.toString()) });
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'second Enter crosses the floor and carries the run').toBe(
+ expected,
+ );
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('FWD-03: an agent write carrying head AND tail runs lands verbatim on every surface', async () => {
+ const raw = '\n\nHead.\n\nTail.\n\n\n';
+ const docName = `qa-fwd-w3-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ try {
+ await agentWriteMd(server.port, raw, { docName, position: 'replace' });
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === raw &&
+ serializeFragment(c.fragment) === raw &&
+ countBlankLineNodes(c.fragment) === 4,
+ ),
+ 8000,
+ );
+ diag('FWD-03', {
+ converged,
+ ytext: clients.map((c) => c.ytext.toString()),
+ fragment: clients.map((c) => serializeFragment(c.fragment)),
+ blanks: clients.map((c) => countBlankLineNodes(c.fragment)),
+ });
+ for (const c of clients) {
+ expect(c.ytext.toString()).toBe(raw);
+ expect(serializeFragment(c.fragment)).toBe(raw);
+ expect(countBlankLineNodes(c.fragment), 'head 2 + tail 2').toBe(4);
+ }
+ expect(await settle(() => readTestDoc(server.contentDir, docName) === raw, 10_000)).toBe(
+ true,
+ );
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('FWD-05: FM-bearing docs keep the separator distinct from authored head runs', async () => {
+ const seed = '---\ntitle: Edge\n---\n\nAbove.\n';
+ const clients = await seedDocument(seed, 'Above.\n');
+ try {
+ const a = clients[0];
+ a.doc.transact(() => {
+ a.fragment.insert(0, [para(), para()]);
+ });
+ // The head-run bytes on an FM doc: separator stays, run rides after it.
+ // Settle on the exact byte state so the later source nudge cannot race
+ // the still-in-flight run write (a weaker predicate returns at the
+ // pre-broadcast state and the concurrent keystroke CRDT-interleaves
+ // with the run insertion).
+ const stableState = await settle(() => {
+ const y = clients[0].ytext.toString();
+ return (
+ y === '---\ntitle: Edge\n---\n\n\n\nAbove.\n' &&
+ countBlankLineNodes(clients[0].fragment) === 2 &&
+ clients.every((c) => c.ytext.toString() === y)
+ );
+ }, 8000);
+ const afterAuthor = clients[0].ytext.toString();
+ diag('FWD-05:authored', {
+ stableState,
+ afterAuthor,
+ fragment: serializeFragment(clients[0].fragment),
+ });
+ expect(stableState, 'head-run authoring on an FM doc converges with FM intact').toBe(true);
+ expect(afterAuthor.startsWith('---\ntitle: Edge\n---\n'), 'FM region intact').toBe(true);
+ expect(afterAuthor.endsWith('Above.\n')).toBe(true);
+
+ // Round-trip stability: a forced full re-derive must not move a byte.
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.toString().indexOf('Above'), 'Q');
+ });
+ const nudged = afterAuthor.replace('Above.', 'QAbove.');
+ const nudgeConverged = await settle(
+ () =>
+ clients.every(
+ (c) => c.ytext.toString() === nudged && countBlankLineNodes(c.fragment) === 2,
+ ),
+ 8000,
+ );
+ diag('FWD-05:nudged', { nudgeConverged, ytext: clients[0].ytext.toString() });
+ expect(nudgeConverged, 'full re-derive keeps FM + head run byte-stable').toBe(true);
+
+ // WYSIWYG delete of the head run returns exactly to the nudged seed shape.
+ a.doc.transact(() => {
+ a.fragment.delete(0, 2);
+ });
+ const expectedBack = seed.replace('Above.', 'QAbove.');
+ const deleted = await settle(
+ () => clients.every((c) => c.ytext.toString() === expectedBack),
+ 8000,
+ );
+ diag('FWD-05:deleted', { deleted, ytext: clients[0].ytext.toString() });
+ expect(deleted, 'deleting the head run restores the separator-only shape').toBe(true);
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 40_000);
+
+ test('FWD-06: floor hazards guarded — heading-final mount mints nothing; a 2-empties doc does not creep', async () => {
+ const headingDoc = `qa-fwd-floor-a-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, '## Head\n', { docName: headingDoc, position: 'replace' });
+ const c1 = await createTestClient(server.port, headingDoc, { skipInvariantWatcher: true });
+ await pollUntil(() => c1.ytext.toString() === '## Head\n', 10_000);
+ await wait(4000);
+ const headingDisk = readTestDoc(server.contentDir, headingDoc);
+ const headingYtext = c1.ytext.toString();
+ diag('FWD-06:heading-final', {
+ headingDisk,
+ headingYtext,
+ fragment: serializeFragment(c1.fragment),
+ });
+ expect(headingYtext, 'no phantom blank from the type-here affordance').toBe('## Head\n');
+ expect(headingDisk).toBe('## Head\n');
+ // NOTE: cleanup() truncates the file via test-reset by design; read disk first.
+ await c1.cleanup();
+
+ const twoEmpties = `qa-fwd-floor-b-${crypto.randomUUID()}`;
+ const raw = 'Body.\n\n\n';
+ await agentWriteMd(server.port, raw, { docName: twoEmpties, position: 'replace' });
+ const c2 = await createTestClient(server.port, twoEmpties, { skipInvariantWatcher: true });
+ await pollUntil(() => c2.ytext.toString() === raw, 10_000);
+ await wait(4000);
+ const twoDisk = readTestDoc(server.contentDir, twoEmpties);
+ const twoYtext = c2.ytext.toString();
+ diag('FWD-06:two-empties', { twoDisk, twoYtext, blanks: countBlankLineNodes(c2.fragment) });
+ expect(twoYtext, 'floor stability: no third empty walks in').toBe(raw);
+ expect(twoDisk).toBe(raw);
+ await c2.cleanup();
+ }, 40_000);
+
+ test('FWD-08: degenerate docs (empty, single newline, all-blank) are stable', async () => {
+ for (const raw of ['', '\n', '\n\n\n']) {
+ const docName = `qa-fwd-degen-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ try {
+ await agentWriteMd(server.port, raw, { docName, position: 'replace' });
+ const converged = await settle(
+ () => clients.every((c) => c.ytext.toString() === raw),
+ 6000,
+ );
+ const frag0 = clients.map((c) => serializeFragment(c.fragment));
+ await wait(1500);
+ const frag1 = clients.map((c) => serializeFragment(c.fragment));
+ const yt = clients.map((c) => c.ytext.toString());
+ diag('FWD-08', { raw: JSON.stringify(raw), converged, yt, frag0, frag1 });
+ for (const c of clients) {
+ expect(c.ytext.toString(), `bytes stable for ${JSON.stringify(raw)}`).toBe(raw);
+ }
+ expect(frag1, 'no observer churn on degenerate docs').toEqual(frag0);
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }
+ }, 60_000);
+
+ test('FWD-10: simultaneous head-run and tail-run authoring on different peers both survive', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ const b = clients[1];
+ a.doc.transact(() => {
+ a.fragment.insert(0, [para(), para()]);
+ });
+ b.doc.transact(() => {
+ b.fragment.insert(b.fragment.length, [para(), para()]);
+ });
+ const expected = '\n\nAbove.\n\nBelow.\n\n\n';
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === expected &&
+ serializeFragment(c.fragment) === expected &&
+ countBlankLineNodes(c.fragment) === 4,
+ ),
+ 8000,
+ );
+ diag('FWD-10', {
+ converged,
+ ytext: clients.map((c) => c.ytext.toString()),
+ fragment: clients.map((c) => serializeFragment(c.fragment)),
+ blanks: clients.map((c) => countBlankLineNodes(c.fragment)),
+ });
+ for (const c of clients) {
+ expect(c.ytext.toString()).toBe(expected);
+ expect(serializeFragment(c.fragment)).toBe(expected);
+ expect(countBlankLineNodes(c.fragment)).toBe(4);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('FWD-12: human undo of a WYSIWYG-authored edge run removes it everywhere', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ const undoManager = new Y.UndoManager(a.fragment);
+ a.doc.transact(() => {
+ a.fragment.insert(a.fragment.length, [para(), para()]);
+ });
+ const withRun = 'Above.\n\nBelow.\n\n\n';
+ expect(
+ await settle(() => clients.every((c) => c.ytext.toString() === withRun), 6000),
+ 'precondition: run landed',
+ ).toBe(true);
+
+ undoManager.undo();
+ const back = 'Above.\n\nBelow.\n';
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) => c.ytext.toString() === back && countBlankLineNodes(c.fragment) === 0,
+ ),
+ 6000,
+ );
+ diag('FWD-12', {
+ converged,
+ ytext: clients.map((c) => c.ytext.toString()),
+ blanks: clients.map((c) => countBlankLineNodes(c.fragment)),
+ });
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'undo removes the run from the source bytes').toBe(back);
+ expect(countBlankLineNodes(c.fragment)).toBe(0);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('DESTROY-A: a WYSIWYG paragraph delete beside a source-only tail run does not destroy the run', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ const b = clients[1];
+ // Source-authored tail run (invisible to the WYSIWYG per the S1 finding).
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.length, '\n\n');
+ });
+ await settle(
+ () => clients.every((c) => c.ytext.toString() === 'Above.\n\nBelow.\n\n\n'),
+ 5000,
+ );
+
+ // The other peer deletes the last CONTENT paragraph in the WYSIWYG —
+ // the mirror of the Miles destruction gesture. The run is visible in
+ // the fragment (two trailing empties), so the content paragraph beside
+ // it is index 1, not the last child.
+ b.doc.transact(() => {
+ b.fragment.delete(1, 1);
+ });
+ await settle(() => clients.every((c) => c.ytext.toString() === 'Above.\n\n\n'), 8000);
+ const finalYtexts = clients.map((c) => c.ytext.toString());
+ diag('DESTROY-A', {
+ finalYtexts,
+ fragment: clients.map((c) => serializeFragment(c.fragment)),
+ });
+ for (const yt of finalYtexts) {
+ expect(yt, 'the source-authored run survives the adjacent WYSIWYG delete').toBe(
+ 'Above.\n\n\n',
+ );
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/qa-healing-probe.test.ts b/packages/app/tests/integration/qa-healing-probe.test.ts
new file mode 100644
index 000000000..75dbbb360
--- /dev/null
+++ b/packages/app/tests/integration/qa-healing-probe.test.ts
@@ -0,0 +1,379 @@
+/**
+ * QA probes round 3: healing bounds + corrected restart lifecycle.
+ *
+ * HEAL-A/B: the stranded states (source-authored edge run invisible to the
+ * WYSIWYG; merge-seam keystroke) — drive up to 10 further source-side drains
+ * and record per-round whether the fragment ever converges (the derive-timing
+ * defer guard force-resolves after MAX_DERIVE_TIMING_DEFERS=8 deferring
+ * drains, IF the defer path is what strands them).
+ *
+ * INV-04b: phantom-blank state after a source delete — does a later WYSIWYG
+ * edit resurrect the deleted run into Y.Text?
+ *
+ * RESTART: clean + crash-sim restarts WITHOUT the harness testReset (which
+ * truncates the doc file by design and invalidated the first restart probe).
+ */
+
+import { appendFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import { describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+import {
+ agentWriteMd,
+ createRestartableServer,
+ createTestClient,
+ createTestClients,
+ createTestServer,
+ pollUntil,
+ readTestDoc,
+ serializeFragment,
+ type TestClient,
+} from './test-harness';
+
+const DIAG = process.env.QA_DIAG_OUT;
+function diag(probe: string, data: Record<string, unknown>): void {
+ if (!DIAG) return;
+ appendFileSync(DIAG, `${JSON.stringify({ probe, ...data })}\n`);
+}
+
+const para = () => new Y.XmlElement('paragraph');
+
+function countBlankLineNodes(fragment: Y.XmlFragment): number {
+ let count = 0;
+ for (let i = 0; i < fragment.length; i++) {
+ if (String(fragment.get(i)) === '<paragraph></paragraph>') count += 1;
+ }
+ return count;
+}
+
+async function settle(predicate: () => boolean, timeoutMs: number): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return true;
+ await wait(25);
+ }
+ return false;
+}
+
+/** Destroy the local client WITHOUT the harness testReset (which truncates the doc file by design). */
+function detachClient(c: TestClient): void {
+ c.provider.destroy();
+ c.doc.destroy();
+}
+
+describe('healing bounds for the stranded states', () => {
+ test('HEAL-A: repeated source-side drains eventually surface a source-authored edge run in the WYSIWYG', async () => {
+ const server = await createTestServer();
+ const docName = `qa-heal-a-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ try {
+ const seed = 'Above.\n\nBelow.\n';
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await pollUntil(() => clients.every((c) => c.ytext.toString() === seed), 10_000);
+ const a = clients[0];
+ const b = clients[1];
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.length, '\n\n');
+ });
+ await settle(
+ () => clients.every((c) => c.ytext.toString() === 'Above.\n\nBelow.\n\n\n'),
+ 5000,
+ );
+ // Make the fragment dirty once (the INV-09 reproduction shape).
+ b.doc.transact(() => {
+ const first = b.fragment.get(0) as { get(i: number): unknown };
+ (first.get(0) as { insert(i: number, s: string): void }).insert(0, 'Z');
+ });
+ await wait(1000);
+
+ const rounds: Array<Record<string, unknown>> = [];
+ let healedAt = -1;
+ for (let r = 0; r < 10; r++) {
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.toString().indexOf('Above'), 'w');
+ });
+ await wait(800);
+ const blanks = clients.map((c) => countBlankLineNodes(c.fragment));
+ const frag = serializeFragment(a.fragment);
+ const yt = a.ytext.toString();
+ rounds.push({ r, blanks, fragHasAllEdits: frag === yt });
+ if (blanks.every((n) => n === 2) && frag === yt) {
+ healedAt = r;
+ break;
+ }
+ }
+ diag('HEAL-A', {
+ healedAt,
+ rounds,
+ finalYtext: clients[0].ytext.toString(),
+ finalFragment: serializeFragment(clients[0].fragment),
+ });
+ expect(
+ healedAt,
+ 'WYSIWYG converged to the full source state within 10 further drains',
+ ).toBeGreaterThanOrEqual(0);
+ } finally {
+ for (const c of clients) await c.cleanup();
+ await server.cleanup();
+ }
+ }, 90_000);
+
+ test('HEAL-B: repeated source-side drains eventually surface the merge-seam stranded keystroke', async () => {
+ const server = await createTestServer();
+ const docName = `qa-heal-b-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ try {
+ const seed = 'Above.\n\nBelow.\n';
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await pollUntil(() => clients.every((c) => c.ytext.toString() === seed), 10_000);
+ const a = clients[0];
+ a.doc.transact(() => {
+ a.fragment.insert(0, [para(), para()]);
+ a.ytext.insert(a.ytext.toString().length - 1, '!');
+ });
+ await settle(
+ () => clients.every((c) => c.ytext.toString() === '\n\nAbove.\n\nBelow.!\n'),
+ 8000,
+ );
+
+ const rounds: Array<Record<string, unknown>> = [];
+ let healedAt = -1;
+ for (let r = 0; r < 10; r++) {
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.toString().indexOf('Above'), 'w');
+ });
+ await wait(800);
+ const frag = serializeFragment(a.fragment);
+ rounds.push({
+ r,
+ fragHasBang: frag.includes('!'),
+ fragHasAllEdits: frag === a.ytext.toString(),
+ });
+ if (frag === a.ytext.toString()) {
+ healedAt = r;
+ break;
+ }
+ }
+ diag('HEAL-B', {
+ healedAt,
+ rounds,
+ finalYtext: clients[0].ytext.toString(),
+ finalFragment: serializeFragment(clients[0].fragment),
+ });
+ expect(
+ healedAt,
+ 'WYSIWYG converged to the full source state within 10 further drains',
+ ).toBeGreaterThanOrEqual(0);
+ } finally {
+ for (const c of clients) await c.cleanup();
+ await server.cleanup();
+ }
+ }, 90_000);
+
+ test('INV-04b: the phantom fragment run does not resurrect into Y.Text on a later WYSIWYG edit', async () => {
+ const server = await createTestServer();
+ const docName = `qa-heal-c-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ try {
+ const seed = 'Above.\n\nBelow.\n';
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await pollUntil(() => clients.every((c) => c.ytext.toString() === seed), 10_000);
+ const a = clients[0];
+ const b = clients[1];
+ a.doc.transact(() => {
+ a.fragment.insert(a.fragment.length, [para(), para()]);
+ });
+ await settle(
+ () => clients.every((c) => c.ytext.toString() === 'Above.\n\nBelow.\n\n\n'),
+ 6000,
+ );
+ a.doc.transact(() => {
+ a.ytext.delete(a.ytext.length - 2, 2);
+ });
+ await settle(() => clients.every((c) => c.ytext.toString() === 'Above.\n\nBelow.\n'), 5000);
+ const phantomBlanks = clients.map((c) => countBlankLineNodes(c.fragment));
+
+ b.doc.transact(() => {
+ const first = b.fragment.get(0) as { get(i: number): unknown };
+ (first.get(0) as { insert(i: number, s: string): void }).insert(0, 'Z');
+ });
+ await wait(1500);
+ const finalYtexts = clients.map((c) => c.ytext.toString());
+ diag('INV-04b', { phantomBlanks, finalYtexts, fragment: serializeFragment(b.fragment) });
+ for (const yt of finalYtexts) {
+ expect(yt, 'deleted run must not resurrect into the source bytes').toBe(
+ 'ZAbove.\n\nBelow.\n',
+ );
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ await server.cleanup();
+ }
+ }, 60_000);
+});
+
+describe('restart lifecycle (corrected: no testReset truncation)', () => {
+ test('RESTART-CLEAN: a source-authored edge run survives a clean server restart and re-derives', async () => {
+ const contentDir = mkdtempSync(join(tmpdir(), 'qa-restart-clean-'));
+ const docName = `qa-restart-${crypto.randomUUID()}`;
+ const withRun = 'Above.\n\nBelow.\n\n\n';
+
+ const s1 = await createTestServer({ contentDir, keepContentDir: true });
+ const c1 = await createTestClient(s1.port, docName, { skipInvariantWatcher: true });
+ await agentWriteMd(s1.port, 'Above.\n\nBelow.\n', { docName, position: 'replace' });
+ await pollUntil(() => c1.ytext.toString() === 'Above.\n\nBelow.\n', 10_000);
+ c1.doc.transact(() => {
+ c1.ytext.insert(c1.ytext.length, '\n\n');
+ });
+ expect(
+ await settle(() => readTestDoc(contentDir, docName) === withRun, 15_000),
+ 'flushed pre-restart',
+ ).toBe(true);
+ detachClient(c1);
+ await s1.cleanup();
+ const diskAfterShutdown = readTestDoc(contentDir, docName);
+
+ const s2 = await createTestServer({ contentDir, keepContentDir: true });
+ const c2 = await createTestClient(s2.port, docName, { skipInvariantWatcher: true });
+ try {
+ const loaded = await settle(
+ () => c2.ytext.toString() === withRun && serializeFragment(c2.fragment) === withRun,
+ 10_000,
+ );
+ await wait(3000);
+ const result = {
+ diskAfterShutdown,
+ loaded,
+ ytext: c2.ytext.toString(),
+ fragment: serializeFragment(c2.fragment),
+ blanks: countBlankLineNodes(c2.fragment),
+ diskFinal: readTestDoc(contentDir, docName),
+ };
+ diag('RESTART-CLEAN', result);
+ expect(diskAfterShutdown, 'clean shutdown preserves bytes').toBe(withRun);
+ expect(c2.ytext.toString(), 'reload restores bytes').toBe(withRun);
+ expect(serializeFragment(c2.fragment), 'reload re-derives the run into the fragment').toBe(
+ withRun,
+ );
+ expect(countBlankLineNodes(c2.fragment)).toBe(2);
+ expect(readTestDoc(contentDir, docName), 'no creep after a reload store cycle').toBe(withRun);
+ } finally {
+ detachClient(c2);
+ await s2.cleanup();
+ }
+ }, 90_000);
+
+ test('RESTART-CRASH: a flushed edge run survives a crash-simulated fast restart', async () => {
+ let restartable = await createRestartableServer({ keepContentDir: true });
+ try {
+ const docName = `qa-crash-${crypto.randomUUID()}`;
+ await agentWriteMd(restartable.port, 'Above.\n\nBelow.\n', { docName, position: 'replace' });
+ const c1 = await createTestClient(restartable.port, docName, { skipInvariantWatcher: true });
+ await pollUntil(() => c1.ytext.toString() === 'Above.\n\nBelow.\n', 10_000);
+ c1.doc.transact(() => {
+ c1.ytext.insert(c1.ytext.length, '\n\n');
+ });
+ const withRun = 'Above.\n\nBelow.\n\n\n';
+ expect(
+ await settle(() => readTestDoc(restartable.contentDir, docName) === withRun, 15_000),
+ 'flushed pre-crash',
+ ).toBe(true);
+ detachClient(c1);
+
+ restartable = await restartable.killAndRestartOnSamePort({ downtimeMs: 5000 });
+ const c2 = await createTestClient(restartable.port, docName, { skipInvariantWatcher: true });
+ try {
+ const reloaded = await settle(
+ () =>
+ c2.ytext.toString() === withRun &&
+ serializeFragment(c2.fragment) === withRun &&
+ countBlankLineNodes(c2.fragment) === 2,
+ 10_000,
+ );
+ diag('RESTART-CRASH', {
+ reloaded,
+ ytext: c2.ytext.toString(),
+ fragment: serializeFragment(c2.fragment),
+ blanks: countBlankLineNodes(c2.fragment),
+ disk: readTestDoc(restartable.contentDir, docName),
+ });
+ expect(c2.ytext.toString()).toBe(withRun);
+ expect(serializeFragment(c2.fragment)).toBe(withRun);
+ expect(countBlankLineNodes(c2.fragment)).toBe(2);
+ expect(readTestDoc(restartable.contentDir, docName)).toBe(withRun);
+ } finally {
+ detachClient(c2);
+ }
+ } finally {
+ await restartable.shutdown();
+ }
+ }, 120_000);
+});
+
+describe('defer-guard innocence under the honest early-exit', () => {
+ test('C17: a pending WYSIWYG paragraph and a concurrent source keystroke both survive', async () => {
+ const server = await createTestServer();
+ const docName = `qa-c17-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ try {
+ const seed = 'Alpha.\n\nOmega.\n';
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await pollUntil(() => clients.every((c) => c.ytext.toString() === seed), 10_000);
+ const a = clients[0];
+ // One transaction: un-propagated WYSIWYG content in the fragment plus a
+ // source keystroke in Y.Text — the defer guard must protect the pending
+ // paragraph while the source edit still lands, and the re-derive that
+ // follows must not discard either.
+ a.doc.transact(() => {
+ const p = new Y.XmlElement('paragraph');
+ const t = new Y.XmlText();
+ t.insert(0, 'Mid.');
+ p.insert(0, [t]);
+ a.fragment.insert(1, [p]);
+ a.ytext.insert(a.ytext.toString().length - 1, '!');
+ });
+ const converged = await settle(
+ () =>
+ clients.every((c) => {
+ const y = c.ytext.toString();
+ return (
+ y.includes('Mid.') &&
+ y.includes('Omega.!') &&
+ serializeFragment(c.fragment).includes('Mid.') &&
+ serializeFragment(c.fragment).includes('Omega.!') &&
+ clients.every((o) => o.ytext.toString() === y)
+ );
+ }),
+ 8000,
+ );
+ diag('C17', {
+ ytext: clients.map((c) => c.ytext.toString()),
+ fragment: clients.map((c) => serializeFragment(c.fragment)),
+ });
+ expect(converged, 'both the pending paragraph and the keystroke survive everywhere').toBe(
+ true,
+ );
+ } finally {
+ for (const c of clients) await c.cleanup();
+ await server.cleanup();
+ }
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/qa-inverse-direction-probe.test.ts b/packages/app/tests/integration/qa-inverse-direction-probe.test.ts
new file mode 100644
index 000000000..fc63b7188
--- /dev/null
+++ b/packages/app/tests/integration/qa-inverse-direction-probe.test.ts
@@ -0,0 +1,565 @@
+/**
+ * QA probe: the INVERSE direction of the #3132 doc-edge blank-run fix.
+ *
+ * #3132 fixed WYSIWYG -> source (Observer A). Nobody adversarially checked the
+ * mirror: source mode -> WYSIWYG (Observer B full re-derive) and disk -> both
+ * surfaces (file-watcher paired write). These probes assert the DESIRED
+ * user-visible behavior; a failure here is a QA finding, not necessarily a
+ * regression, because the shipped tolerance deliberately rests on some of
+ * these divergences. Every observation also lands in the QA_DIAG_OUT sink so
+ * the evidence survives a passing run (vitest suppresses console on pass).
+ *
+ * Multi-client on purpose: the server is the sole cross-CRDT writer, and the
+ * WYSIWYG every peer renders is the fragment Observer B maintains. Raw-byte
+ * assertions only (the bridge comparator tolerance swallows exactly the
+ * diffs under test).
+ */
+
+import { appendFileSync } from 'node:fs';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentWriteMd,
+ createTestClient,
+ createTestClients,
+ createTestServer,
+ pollUntil,
+ serializeFragment,
+ 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 DIAG = process.env.QA_DIAG_OUT;
+function diag(probe: string, data: Record<string, unknown>): void {
+ if (!DIAG) return;
+ appendFileSync(DIAG, `${JSON.stringify({ probe, ...data })}\n`);
+}
+
+const para = () => new Y.XmlElement('paragraph');
+
+function countBlankLineNodes(fragment: Y.XmlFragment): number {
+ let count = 0;
+ for (let i = 0; i < fragment.length; i++) {
+ if (String(fragment.get(i)) === '<paragraph></paragraph>') count += 1;
+ }
+ return count;
+}
+
+async function settle(predicate: () => boolean, timeoutMs: number): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return true;
+ await wait(25);
+ }
+ return false;
+}
+
+async function seedDocument(raw: string, fragmentBody = raw): Promise<TestClient[]> {
+ const docName = `qa-inv-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ await agentWriteMd(server.port, raw, { docName, position: 'replace' });
+ await pollUntil(
+ () =>
+ clients.every(
+ (c) => c.ytext.toString() === raw && serializeFragment(c.fragment) === fragmentBody,
+ ),
+ 10_000,
+ );
+ return clients;
+}
+
+function snapshot(clients: TestClient[]): Record<string, unknown> {
+ return {
+ ytext: clients.map((c) => c.ytext.toString()),
+ fragment: clients.map((c) => serializeFragment(c.fragment)),
+ blanks: clients.map((c) => countBlankLineNodes(c.fragment)),
+ };
+}
+
+describe('inverse direction: source mode -> WYSIWYG', () => {
+ test('INV-01: a tail blank run typed in source mode reaches every WYSIWYG', async () => {
+ for (const b of [2, 3, 5]) {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ // Enter pressed b times at the very end of the source view: a direct
+ // Y.Text append, which is exactly what CodeMirror does.
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.length, '\n'.repeat(b));
+ });
+ const expected = `Above.\n\nBelow.\n${'\n'.repeat(b)}`;
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === expected &&
+ serializeFragment(c.fragment) === expected &&
+ countBlankLineNodes(c.fragment) === b,
+ ),
+ 6000,
+ );
+ diag('INV-01', { b, converged, ...snapshot(clients) });
+ for (const c of clients) {
+ expect(c.ytext.toString(), `b=${b} ytext`).toBe(expected);
+ expect(serializeFragment(c.fragment), `b=${b} fragment`).toBe(expected);
+ expect(countBlankLineNodes(c.fragment), `b=${b} blanks`).toBe(b);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }
+ }, 60_000);
+
+ test('INV-02: a head blank run typed in source mode reaches every WYSIWYG', async () => {
+ for (const b of [2, 3, 5]) {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ a.doc.transact(() => {
+ a.ytext.insert(0, '\n'.repeat(b));
+ });
+ const expected = `${'\n'.repeat(b)}Above.\n\nBelow.\n`;
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === expected &&
+ serializeFragment(c.fragment) === expected &&
+ countBlankLineNodes(c.fragment) === b,
+ ),
+ 6000,
+ );
+ diag('INV-02', { b, converged, ...snapshot(clients) });
+ for (const c of clients) {
+ expect(c.ytext.toString(), `b=${b} ytext`).toBe(expected);
+ expect(serializeFragment(c.fragment), `b=${b} fragment`).toBe(expected);
+ expect(countBlankLineNodes(c.fragment), `b=${b} blanks`).toBe(b);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }
+ }, 60_000);
+
+ test('INV-04: deleting a carried edge run in source mode empties the WYSIWYG run and it never resurrects', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ const b = clients[1];
+ // Seed the carried run through the FIXED forward path so both surfaces hold it.
+ a.doc.transact(() => {
+ a.fragment.insert(a.fragment.length, [para(), para()]);
+ });
+ const withRun = 'Above.\n\nBelow.\n\n\n';
+ expect(
+ await settle(
+ () =>
+ clients.every(
+ (c) => c.ytext.toString() === withRun && countBlankLineNodes(c.fragment) === 2,
+ ),
+ 6000,
+ ),
+ 'precondition: forward path landed the run',
+ ).toBe(true);
+
+ // Source-mode delete of the whole run.
+ a.doc.transact(() => {
+ a.ytext.delete(a.ytext.length - 2, 2);
+ });
+ const withoutRun = 'Above.\n\nBelow.\n';
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === withoutRun &&
+ serializeFragment(c.fragment) === withoutRun &&
+ countBlankLineNodes(c.fragment) === 0,
+ ),
+ 6000,
+ );
+ diag('INV-04:after-delete', { converged, ...snapshot(clients) });
+ for (const c of clients) {
+ expect(c.ytext.toString()).toBe(withoutRun);
+ expect(serializeFragment(c.fragment), 'fragment after source delete').toBe(withoutRun);
+ expect(countBlankLineNodes(c.fragment), 'phantom blanks after source delete').toBe(0);
+ }
+
+ // A later WYSIWYG edit on the OTHER peer must not resurrect the deleted run.
+ b.doc.transact(() => {
+ const first = b.fragment.get(0) as { get(i: number): unknown };
+ (first.get(0) as { insert(i: number, s: string): void }).insert(0, 'Z');
+ });
+ const edited = 'ZAbove.\n\nBelow.\n';
+ const convergedEdit = await settle(
+ () => clients.every((c) => c.ytext.toString() === edited),
+ 6000,
+ );
+ diag('INV-04:after-wysiwyg-edit', { convergedEdit, ...snapshot(clients) });
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'no resurrection of the deleted run').toBe(edited);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('INV-08: concurrent source content edit + WYSIWYG edge run both survive', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ const b = clients[1];
+ // Same event-loop turn on two different peers: a real settlement race.
+ a.doc.transact(() => {
+ a.ytext.insert(0, 'X');
+ });
+ b.doc.transact(() => {
+ b.fragment.insert(b.fragment.length, [para(), para()]);
+ });
+ const expected = 'XAbove.\n\nBelow.\n\n\n';
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === expected &&
+ serializeFragment(c.fragment) === expected &&
+ countBlankLineNodes(c.fragment) === 2,
+ ),
+ 8000,
+ );
+ diag('INV-08', { converged, ...snapshot(clients) });
+ for (const c of clients) {
+ expect(c.ytext.toString()).toBe(expected);
+ expect(serializeFragment(c.fragment)).toBe(expected);
+ expect(countBlankLineNodes(c.fragment)).toBe(2);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('INV-07: a full re-derive inverts the edge arithmetic exactly and repeated cycles do not creep', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.length, '\n\n\n');
+ });
+ // Out-of-tolerance nudge forces Observer B off the early-exit, so the
+ // fragment MUST rebuild from parse(Y.Text) including the tail run.
+ a.doc.transact(() => {
+ a.ytext.insert(0, 'Q');
+ });
+ const withNudge = 'QAbove.\n\nBelow.\n\n\n\n';
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === withNudge &&
+ serializeFragment(c.fragment) === withNudge &&
+ countBlankLineNodes(c.fragment) === 3,
+ ),
+ 8000,
+ );
+ diag('INV-07:nudged', { converged, ...snapshot(clients) });
+ for (const c of clients) {
+ expect(c.ytext.toString()).toBe(withNudge);
+ expect(serializeFragment(c.fragment), 'tail b=3 blank lines <=> 3 empties, exact').toBe(
+ withNudge,
+ );
+ expect(countBlankLineNodes(c.fragment)).toBe(3);
+ }
+
+ // Three more full re-derive cycles: byte state must be a fixed point.
+ for (let i = 0; i < 3; i++) {
+ a.doc.transact(() => {
+ a.ytext.delete(0, 1);
+ });
+ const removed = 'Above.\n\nBelow.\n\n\n\n';
+ expect(
+ await settle(
+ () =>
+ clients.every(
+ (c) => c.ytext.toString() === removed && serializeFragment(c.fragment) === removed,
+ ),
+ 6000,
+ ),
+ `cycle ${i} remove converged`,
+ ).toBe(true);
+ a.doc.transact(() => {
+ a.ytext.insert(0, 'Q');
+ });
+ expect(
+ await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === withNudge && serializeFragment(c.fragment) === withNudge,
+ ),
+ 6000,
+ ),
+ `cycle ${i} re-add converged`,
+ ).toBe(true);
+ }
+ diag('INV-07:cycles', snapshot(clients));
+ for (const c of clients) {
+ expect(countBlankLineNodes(c.fragment), 'no creep across re-derive cycles').toBe(3);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 60_000);
+
+ test('INV-09: a source-authored edge run is not permanently invisible to the WYSIWYG (healing probes)', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ const b = clients[1];
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.length, '\n\n');
+ });
+ const direct = await settle(
+ () => clients.every((c) => countBlankLineNodes(c.fragment) === 2),
+ 5000,
+ );
+ diag('INV-09:direct', { direct, ...snapshot(clients) });
+
+ // Healing probe (a): an unrelated WYSIWYG edit on the other peer.
+ b.doc.transact(() => {
+ const first = b.fragment.get(0) as { get(i: number): unknown };
+ (first.get(0) as { insert(i: number, s: string): void }).insert(0, 'Z');
+ });
+ const afterWysiwyg = await settle(
+ () => clients.every((c) => countBlankLineNodes(c.fragment) === 2),
+ 5000,
+ );
+ diag('INV-09:after-wysiwyg', { afterWysiwyg, ...snapshot(clients) });
+
+ // Healing probe (b): an unrelated source edit.
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.toString().indexOf('Above'), 'W');
+ });
+ const afterSource = await settle(
+ () => clients.every((c) => countBlankLineNodes(c.fragment) === 2),
+ 5000,
+ );
+ diag('INV-09:after-source', { afterSource, ...snapshot(clients) });
+
+ // Healing probe (c): a brand-new client (fresh WYSIWYG mount on the live server).
+ const fresh = await createTestClient(server.port, a.docName, {
+ skipInvariantWatcher: true,
+ });
+ try {
+ const freshSees = await settle(() => countBlankLineNodes(fresh.fragment) === 2, 5000);
+ diag('INV-09:fresh-client', {
+ freshSees,
+ fragment: serializeFragment(fresh.fragment),
+ blanks: countBlankLineNodes(fresh.fragment),
+ });
+ // The user-visible contract: by the END of the probe ladder the run is
+ // visible in the WYSIWYG. Which rung healed it is diagnostic detail.
+ expect(
+ afterSource || freshSees,
+ 'run still invisible to WYSIWYG after WYSIWYG edit + source edit + fresh mount',
+ ).toBe(true);
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'authored bytes survive throughout').toContain('\n\n\n');
+ }
+ } finally {
+ await fresh.cleanup();
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 60_000);
+
+ test('INV-10: content stranded by the merge seam eventually reaches the WYSIWYG', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ // The #3132-pinned gesture: fragment edge run + Y.Text keystroke in ONE transaction.
+ a.doc.transact(() => {
+ a.fragment.insert(0, [para(), para()]);
+ a.ytext.insert(a.ytext.toString().length - 1, '!');
+ });
+ const ytextSettled = '\n\nAbove.\n\nBelow.!\n';
+ expect(
+ await settle(() => clients.every((c) => c.ytext.toString() === ytextSettled), 8000),
+ 'precondition: pinned merge-seam Y.Text state reached',
+ ).toBe(true);
+ const strandedAtSettle = clients.map((c) => serializeFragment(c.fragment).includes('!'));
+ diag('INV-10:settled', { strandedAtSettle, ...snapshot(clients) });
+
+ // Healing probe: an unrelated source edit forces a full B re-derive.
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.toString().indexOf('Above'), 'W');
+ });
+ const healed = await settle(
+ () => clients.every((c) => serializeFragment(c.fragment).includes('!')),
+ 6000,
+ );
+ diag('INV-10:after-source-edit', { healed, ...snapshot(clients) });
+ expect(healed, 'the stranded keystroke reached the WYSIWYG after a source-side drain').toBe(
+ true,
+ );
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('INV-05: whitespace-polluted blank lines at the tail hold safe, stable state', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ // A "blank" line carrying a single space, inside a tail run.
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.length, '\n \n');
+ });
+ const expected = 'Above.\n\nBelow.\n\n \n';
+ await settle(() => clients.every((c) => c.ytext.toString() === expected), 5000);
+ // Byte stability under two further settle windows (loop detector).
+ const frag0 = clients.map((c) => serializeFragment(c.fragment));
+ await wait(1500);
+ const frag1 = clients.map((c) => serializeFragment(c.fragment));
+ diag('INV-05', { frag0, frag1, ...snapshot(clients) });
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'polluted bytes preserved verbatim').toBe(expected);
+ }
+ expect(frag1, 'fragment stable across settle windows (no loop)').toEqual(frag0);
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+
+ test('INV-03: a sub-floor single blank line survives in bytes across a later WYSIWYG edit', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ const b = clients[1];
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.length, '\n');
+ });
+ const withSubFloor = 'Above.\n\nBelow.\n\n';
+ expect(
+ await settle(() => clients.every((c) => c.ytext.toString() === withSubFloor), 5000),
+ 'sub-floor byte propagation to peers',
+ ).toBe(true);
+
+ b.doc.transact(() => {
+ const first = b.fragment.get(0) as { get(i: number): unknown };
+ (first.get(0) as { insert(i: number, s: string): void }).insert(0, 'Z');
+ });
+ const edited = 'ZAbove.\n\nBelow.\n\n';
+ const converged = await settle(
+ () => clients.every((c) => c.ytext.toString() === edited),
+ 6000,
+ );
+ diag('INV-03', { converged, ...snapshot(clients) });
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'sub-floor blank line not destroyed by WYSIWYG edit').toBe(
+ edited,
+ );
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+});
+
+describe('inverse direction on frontmatter-bearing documents', () => {
+ test('INV-13: a head run typed in source mode below the FM separator reaches every WYSIWYG and deletes back out', async () => {
+ const seed = '---\ntitle: Edge\n---\n\nAbove.\n';
+ const clients = await seedDocument(seed, 'Above.\n');
+ try {
+ const a = clients[0];
+ // Two blank lines authored after the separator: separator stays a
+ // boundary slot, the run rides after it.
+ a.doc.transact(() => {
+ a.ytext.insert(a.ytext.toString().indexOf('Above'), '\n\n');
+ });
+ const authored = '---\ntitle: Edge\n---\n\n\n\nAbove.\n';
+ const gained = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === authored &&
+ countBlankLineNodes(c.fragment) === 2 &&
+ serializeFragment(c.fragment) === '\n\nAbove.\n',
+ ),
+ 8000,
+ );
+ diag('INV-13:gained', { gained, ...snapshot(clients) });
+ expect(gained, 'source-authored FM head run reaches every WYSIWYG').toBe(true);
+
+ // Source-delete the run; the separator survives, the empties leave.
+ a.doc.transact(() => {
+ const idx = a.ytext.toString().indexOf('\n\n\n');
+ a.ytext.delete(idx, 2);
+ });
+ const dropped = await settle(
+ () =>
+ clients.every(
+ (c) =>
+ c.ytext.toString() === seed &&
+ countBlankLineNodes(c.fragment) === 0 &&
+ serializeFragment(c.fragment) === 'Above.\n',
+ ),
+ 8000,
+ );
+ diag('INV-13:dropped', { dropped, ...snapshot(clients) });
+ expect(dropped, 'source-deleting the run restores the separator-only shape everywhere').toBe(
+ true,
+ );
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+});
+
+describe('split-brain settlements converge at rest', () => {
+ test('INV-14: the merge-seam settlement reaches every WYSIWYG without a healing edit', async () => {
+ const clients = await seedDocument('Above.\n\nBelow.\n');
+ try {
+ const a = clients[0];
+ // The merge-seam gesture: fragment edge run + Y.Text keystroke in ONE
+ // transaction. The settlement merges both into Y.Text; the fragment
+ // must then converge on its own — no later edit may be required to
+ // surface the keystroke in the WYSIWYG.
+ a.doc.transact(() => {
+ a.fragment.insert(0, [para(), para()]);
+ a.ytext.insert(a.ytext.toString().length - 1, '!');
+ });
+ const converged = await settle(
+ () =>
+ clients.every((c) => {
+ const y = c.ytext.toString();
+ return (
+ y.includes('Below.!') &&
+ serializeFragment(c.fragment) === y &&
+ clients.every((o) => o.ytext.toString() === y)
+ );
+ }),
+ 8000,
+ );
+ diag('INV-14', snapshot(clients));
+ expect(converged, 'the seam keystroke reaches every WYSIWYG at rest').toBe(true);
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/qa-isolation-probe.test.ts b/packages/app/tests/integration/qa-isolation-probe.test.ts
new file mode 100644
index 000000000..2b7d6e454
--- /dev/null
+++ b/packages/app/tests/integration/qa-isolation-probe.test.ts
@@ -0,0 +1,92 @@
+/**
+ * QA isolation probes for two anomalies the inverse-direction suite surfaced:
+ *
+ * 1. INV-06: a live external disk edit never reached Y.Text within 15s.
+ * Trajectory probe: poll ytext + disk every second for 30s, fire the
+ * test-rescan rescue at 10s, and record whether persistence clobbers the
+ * external edit back to the pre-edit bytes.
+ *
+ * 2. INV-09c: after killAndRestartOnSamePort the doc loaded EMPTY and the
+ * disk file was truncated. Variant probes: clean shutdown restart vs
+ * crash-sim restart, recording disk bytes at every step.
+ */
+
+import { appendFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+import { describe, expect, test } from 'vitest';
+import {
+ agentWriteMd,
+ createTestClients,
+ createTestServer,
+ pollUntil,
+ readTestDoc,
+ serializeFragment,
+} from './test-harness';
+
+const DIAG = process.env.QA_DIAG_OUT;
+function diag(probe: string, data: Record<string, unknown>): void {
+ if (!DIAG) return;
+ appendFileSync(DIAG, `${JSON.stringify({ probe, ...data })}\n`);
+}
+
+async function settle(predicate: () => boolean, timeoutMs: number): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return true;
+ await wait(25);
+ }
+ return false;
+}
+
+describe('isolation: external disk edit trajectory', () => {
+ test('ISO-06: a live disk edit adding edge runs reaches Y.Text (30s trajectory + rescue)', async () => {
+ const server = await createTestServer();
+ const docName = `qa-iso-${crypto.randomUUID()}`;
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ try {
+ const seed = 'Above.\n\nBelow.\n';
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await pollUntil(() => clients.every((c) => c.ytext.toString() === seed), 10_000);
+ expect(await settle(() => readTestDoc(server.contentDir, docName) === seed, 12_000)).toBe(
+ true,
+ );
+ // Give the persistence debounce a beat so the external write cannot be
+ // mistaken for our own store echo.
+ await wait(1500);
+
+ const withRuns = '\n\nAbove.\n\nBelow.\n\n\n';
+ writeFileSync(join(server.contentDir, `${docName}.md`), withRuns, 'utf-8');
+ const trajectory: Array<Record<string, unknown>> = [];
+ let rescued = false;
+ for (let s = 0; s < 30; s++) {
+ await wait(1000);
+ const state = {
+ t: s + 1,
+ ytext: clients[0].ytext.toString(),
+ disk: readTestDoc(server.contentDir, docName),
+ };
+ trajectory.push(state);
+ if (state.ytext === withRuns) break;
+ if (s === 9 && !rescued) {
+ rescued = true;
+ await fetch(`http://127.0.0.1:${server.port}/api/test-rescan-files`, {
+ method: 'POST',
+ }).catch(() => null);
+ }
+ }
+ diag('ISO-06', { trajectory, rescued, fragment: serializeFragment(clients[0].fragment) });
+ expect(clients[0].ytext.toString(), 'external edit reached Y.Text').toBe(withRuns);
+ expect(readTestDoc(server.contentDir, docName), 'external edit not clobbered on disk').toBe(
+ withRuns,
+ );
+ } finally {
+ for (const c of clients) await c.cleanup();
+ await server.cleanup();
+ }
+ }, 90_000);
+});
diff --git a/packages/app/tests/integration/qa-undo-fixed-probe.test.ts b/packages/app/tests/integration/qa-undo-fixed-probe.test.ts
new file mode 100644
index 000000000..5e2384e10
--- /dev/null
+++ b/packages/app/tests/integration/qa-undo-fixed-probe.test.ts
@@ -0,0 +1,87 @@
+/**
+ * QA probe: FWD-04 corrected — agent undo across an edge-run write, with the
+ * 600ms captureTimeout gap between writes the shipped C11 suite uses (the
+ * first attempt coalesced both writes into one StackItem, a probe artifact).
+ */
+
+import { appendFileSync } from 'node:fs';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentUndo,
+ agentWriteMd,
+ createTestClients,
+ createTestServer,
+ pollUntil,
+ serializeFragment,
+ type TestServer,
+} from './test-harness';
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+const DIAG = process.env.QA_DIAG_OUT;
+function diag(probe: string, data: Record<string, unknown>): void {
+ if (!DIAG) return;
+ appendFileSync(DIAG, `${JSON.stringify({ probe, ...data })}\n`);
+}
+
+async function settle(predicate: () => boolean, timeoutMs: number): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return true;
+ await wait(25);
+ }
+ return false;
+}
+
+describe('W5 agent undo across an edge-run write (corrected timing)', () => {
+ test('FWD-04b: undo restores pre-write bytes and fragments on every peer', async () => {
+ const docName = `qa-undo-${crypto.randomUUID()}`;
+ const rawId = crypto.randomUUID().replace(/-/g, '').slice(0, 12);
+ const connectionId = `agent-${rawId}`;
+ const original = 'Original.\n';
+ const withRuns = '\n\nHead.\n\nTail.\n\n\n';
+ const clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { skipInvariantWatcher: true },
+ });
+ try {
+ await agentWriteMd(server.port, original, { docName, position: 'replace', agentId: rawId });
+ await pollUntil(() => clients.every((c) => c.ytext.toString() === original), 10_000);
+ await wait(600);
+ await agentWriteMd(server.port, withRuns, { docName, position: 'replace', agentId: rawId });
+ await pollUntil(() => clients.every((c) => c.ytext.toString() === withRuns), 10_000);
+ await wait(600);
+
+ await agentUndo(server.port, { docName, connectionId, scope: 'last' });
+ const converged = await settle(
+ () =>
+ clients.every(
+ (c) => c.ytext.toString() === original && serializeFragment(c.fragment) === original,
+ ),
+ 8000,
+ );
+ diag('FWD-04b', {
+ converged,
+ ytext: clients.map((c) => c.ytext.toString()),
+ fragment: clients.map((c) => serializeFragment(c.fragment)),
+ });
+ for (const c of clients) {
+ expect(c.ytext.toString(), 'undo restores pre-write bytes').toBe(original);
+ expect(serializeFragment(c.fragment), 'undo re-derives fragments').toBe(original);
+ }
+ } finally {
+ for (const c of clients) await c.cleanup();
+ }
+ }, 60_000);
+});
diff --git a/packages/app/tests/stress/e2e-ci-ledger.ts b/packages/app/tests/stress/e2e-ci-ledger.ts
index 38db31748..a232cb8ce 100644
--- a/packages/app/tests/stress/e2e-ci-ledger.ts
+++ b/packages/app/tests/stress/e2e-ci-ledger.ts
@@ -25,6 +25,34 @@ export interface E2eCiLedgerEntry {
}
export const E2E_CI_EXCLUSIONS: readonly E2eCiLedgerEntry[] = [
+ {
+ file: 'prop-upload.e2e.ts',
+ reason:
+ 'pins live bug inkeep/agents-private#3225: the three image-upload render tests (src replace + disk landing, subdir <img> asset fetch, 0-byte 400 toast) fail deterministically on current origin/main; same image-placeholder root suspect as the clipboard suite. Promote in the fix PR.',
+ evidence:
+ 'origin/main 1dd5d73a8a locally (darwin, retries=0): the 3 image tests fail at 2-3s each while 2 siblings pass; linux CI three-striked the same tests on PR #3187 run 30955628815',
+ },
+ {
+ file: 'slash-command-auto-open.e2e.ts',
+ reason:
+ 'pins live bug inkeep/agents-private#3225: the placeholder-fill-dismisses test (real img renders after src fill) fails deterministically on current origin/main; same image-placeholder root suspect. The suite rides the quarantine because exclusion is per-file. Promote in the fix PR.',
+ evidence:
+ 'origin/main 1dd5d73a8a locally (darwin, retries=0, repeat-each=2): 2/2 failures; linux CI three-striked it on PR #3187 run 30955628815',
+ },
+ {
+ file: 'clipboard-relative-url-source-fallback.e2e.ts',
+ reason:
+ 'pins live bug inkeep/agents-private#3225: the relative-URL IMAGE source-fallback tests (standalone image paragraph, mixed selection per-element, 50-element slow-op budget, callout-nested descriptor boundary) fail deterministically on current origin/main at assertion speed; prime suspect is the image-src failure placeholder change merged the same day. Promote in the fix PR.',
+ evidence:
+ 'origin/main 1dd5d73a8a locally (darwin, retries=0): 4 tests fail in 2-4s each while the siblings pass; identical failures on this branch after merging that main; linux CI three-striked the same tests in run 30954078770',
+ },
+ {
+ file: 'editor-split-view.e2e.ts',
+ reason:
+ 'pins live bug inkeep/agents-private#3200: the four-pane layout-restore test finds at least one editor portal absent after restore (portalGeneration() returns absent). Deterministic on plain origin/main locally and three-striked two CI runs on an unrelated PR, red-flagging the required aggregate for every OK PR. Promote in the fix PR.',
+ evidence:
+ 'detached worktree at origin/main fe17885411, fresh install: the restore test fails 3/3 with retries=0 while the 5 sibling tests pass; PR #3187 CI runs 30932855568 and 30935260763 each failed it 3-strikes',
+ },
{
file: 'frontmatter-edit.e2e.ts',
reason:
diff --git a/packages/app/tests/stress/qa-miles-edge-blanks.e2e.ts b/packages/app/tests/stress/qa-miles-edge-blanks.e2e.ts
new file mode 100644
index 000000000..f238f4203
--- /dev/null
+++ b/packages/app/tests/stress/qa-miles-edge-blanks.e2e.ts
@@ -0,0 +1,115 @@
+/**
+ * Browser-rung QA probes for the doc-edge blank-run class (#3132 audit).
+ *
+ * FWD-11: real Enter keypresses at the very top and bottom of the WYSIWYG
+ * reach the source bytes and survive a mode toggle + reload (the forward
+ * fix at user fidelity, edges instead of the shipped interior case).
+ *
+ * INV-11: blank lines typed at the document tail in real CodeMirror source
+ * mode appear as blank paragraphs when toggling to the visual editor (the
+ * inverse direction at user fidelity).
+ */
+import { randomUUID } from 'node:crypto';
+import type { Page } from '@playwright/test';
+import { expect, test, waitForActiveProviderSynced as waitForProvider } from './_helpers';
+
+const sourceToggle = (page: Page) => page.getByRole('radio', { name: 'Markdown source' });
+const visualToggle = (page: Page) => page.getByRole('radio', { name: 'Visual editor' });
+
+function readSource(page: Page): Promise<string> {
+ return page.evaluate(() => window.__activeProvider?.document.getText('source').toString() ?? '');
+}
+
+function countBlankParagraphs(page: Page): Promise<number> {
+ return page.evaluate(() => {
+ const editor = document.querySelector('.ProseMirror:not(.composer-prosemirror)');
+ if (!editor) return -1;
+ return [...editor.children].filter(
+ (child) => child.tagName === 'P' && (child.textContent ?? '') === '',
+ ).length;
+ });
+}
+
+test.describe('doc-edge blank runs at browser fidelity', () => {
+ let docName: string;
+
+ test.beforeEach(async ({ page, api }) => {
+ docName = `test-qa-edge-${randomUUID().slice(0, 8)}`;
+ await api.createPage(`${docName}.md`);
+ await api.replaceDoc(docName, 'Above.\n\nBelow.\n');
+ await page.goto(`/#/${docName}`);
+ await waitForProvider(page);
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ await page.waitForFunction(
+ () =>
+ document
+ .querySelector('.ProseMirror:not(.composer-prosemirror)')
+ ?.textContent?.includes('Above'),
+ null,
+ { timeout: 10_000 },
+ );
+ });
+
+ test('FWD-11: Enters at the very top and bottom reach the source bytes and survive toggle + reload', async ({
+ page,
+ }) => {
+ // Deterministic caret placement via the exposed editor handle (the
+ // grip-click suite's pattern) — keyboard-only navigation proved unable to
+ // reach the document edges under automation. The focus() commit is
+ // asynchronous relative to the evaluate's return, so each placement
+ // waits for the view to actually hold focus before any key is pressed —
+ // a press racing the focus commit lands outside the editor and reads as
+ // a minted-nothing keymap defect that does not exist.
+ await page.evaluate(() => {
+ const editor = window.__activeEditor;
+ if (!editor) throw new Error('window.__activeEditor not set');
+ editor.chain().focus().setTextSelection(1).run();
+ });
+ await page.waitForFunction(() => window.__activeEditor?.view.hasFocus() === true);
+ await page.keyboard.press('Enter');
+ await page.keyboard.press('Enter');
+ await page.evaluate(() => {
+ const editor = window.__activeEditor;
+ if (!editor) throw new Error('window.__activeEditor not set');
+ editor.chain().focus().setTextSelection(editor.state.doc.content.size).run();
+ });
+ await page.waitForFunction(() => window.__activeEditor?.view.hasFocus() === true);
+ await page.keyboard.press('Enter');
+ await page.keyboard.press('Enter');
+
+ const expected = '\n\nAbove.\n\nBelow.\n\n\n';
+ await expect.poll(() => readSource(page), { timeout: 10_000 }).toBe(expected);
+
+ await sourceToggle(page).click();
+ await page.waitForSelector('.cm-content', { timeout: 10_000 });
+ await visualToggle(page).click();
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ await expect.poll(() => countBlankParagraphs(page), { timeout: 10_000 }).toBe(4);
+ expect(await readSource(page)).toBe(expected);
+
+ await page.reload();
+ await waitForProvider(page);
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ await expect.poll(() => countBlankParagraphs(page), { timeout: 10_000 }).toBe(4);
+ expect(await readSource(page)).toBe(expected);
+ });
+
+ test('INV-11: blank lines typed at the tail in source mode appear in the visual editor', async ({
+ page,
+ }) => {
+ await sourceToggle(page).click();
+ await page.waitForSelector('.cm-content', { timeout: 10_000 });
+ await page.locator('.cm-content').click();
+ await page.keyboard.press('ControlOrMeta+End');
+ await page.keyboard.press('Enter');
+ await page.keyboard.press('Enter');
+
+ const expected = 'Above.\n\nBelow.\n\n\n';
+ await expect.poll(() => readSource(page), { timeout: 10_000 }).toBe(expected);
+
+ await visualToggle(page).click();
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ await expect.poll(() => countBlankParagraphs(page), { timeout: 10_000 }).toBe(2);
+ expect(await readSource(page), 'source bytes survive the toggle').toBe(expected);
+ });
+});
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index d7a845280..dfd95ef49 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts
@@ -1,3 +1,4 @@
+
import type * as Y from 'yjs';
import type { Err, Ok, Result } from '../config/result.ts';
import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';
diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.ts
index 005627195..8bfdb40cd 100644
--- a/packages/core/src/bridge/bridge-invariant.ts
+++ b/packages/core/src/bridge/bridge-invariant.ts
@@ -1,3 +1,4 @@
+
import { fnv1aDigest } from './hash-util.ts';
export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index a1dff381b..01ef76a9f 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,5 +1,6 @@
+
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
-import { carriedEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
+import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
const LEADING_BOUNDARY_RE = /^(?:\r?\n)+/;
@@ -64,3 +65,29 @@ export function unprojectMergeBoundarySpace(
splitLeadingDocBoundary(raw, carriesDocStartRun).boundary,
);
}
+
+export interface FmBoundarySlotSplit {
+ slot: string;
+ body: string;
+}
+
+export function splitFmBoundarySlot(frontmatter: string, body: string): FmBoundarySlotSplit {
+ if (frontmatter === '') return { slot: '', body };
+ const match = body.match(/^\r?\n/);
+ if (!match) return { slot: '', body };
+ return { slot: match[0], body: body.slice(match[0].length) };
+}
+
+export function bodyEdgeEmpties(text: string): DocEdgeEmpties {
+ const { frontmatter, body } = stripFrontmatter(text);
+ if (frontmatter === '') return carriedEdgeEmpties(text);
+ const slotStripped = splitFmBoundarySlot(frontmatter, body).body;
+ if (/^\n*$/.test(slotStripped)) return carriedEdgeEmpties(text);
+ return carriedEdgeEmpties(slotStripped);
+}
+
+export function docEdgeRunsDiffer(a: string, b: string): boolean {
+ const edgesA = bodyEdgeEmpties(a);
+ const edgesB = bodyEdgeEmpties(b);
+ return edgesA.leading !== edgesB.leading || edgesA.trailing !== edgesB.trailing;
+}
diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.ts
index 9d9c244b0..463e89595 100644
--- a/packages/core/src/bridge/growth-detect.ts
+++ b/packages/core/src/bridge/growth-detect.ts
@@ -1,3 +1,4 @@
+
const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;
export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;
diff --git a/packages/core/src/bridge/index.ts b/packages/core/src/bridge/index.ts
index 84b7b4604..4b1bdbffb 100644
--- a/packages/core/src/bridge/index.ts
+++ b/packages/core/src/bridge/index.ts
@@ -31,8 +31,12 @@ export {
} from './compose.ts';
export { type DiffChange, diffLinesFast } from './diff-lines.ts';
export {
+ bodyEdgeEmpties,
createMergeBoundarySpace,
+ docEdgeRunsDiffer,
+ type FmBoundarySlotSplit,
type MergeBoundarySpace,
+ splitFmBoundarySlot,
} from './doc-boundary-space.ts';
export {
applyPatchToFm,
diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.ts
index c43fdd7e7..0939885bb 100644
--- a/packages/core/src/bridge/intraline-predicate.ts
+++ b/packages/core/src/bridge/intraline-predicate.ts
@@ -1,3 +1,4 @@
+
export function rawLineCounts(doc: string): Map<string, number> {
const counts = new Map<string, number>();
for (const line of doc.split('\n')) {
diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.ts
index 251560a35..c0dc65705 100644
--- a/packages/core/src/bridge/merge-three-way.ts
+++ b/packages/core/src/bridge/merge-three-way.ts
@@ -65,6 +65,7 @@ export function tryLineLevelCombine(
return { clean: true, merged };
}
+
export type BridgeMergeContentLossSide = 'user' | 'agent';
export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';
diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.ts
index 650461462..dcc5b0690 100644
--- a/packages/core/src/bridge/normalize.ts
+++ b/packages/core/src/bridge/normalize.ts
@@ -1,4 +1,6 @@
-import { carriedEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
+
+import { stripFrontmatter } from '../extensions/frontmatter.ts';
+import { bodyEdgeEmpties } from './doc-boundary-space.ts';
const COMMONMARK_ESCAPE_RE = /\\([!"#$%&'()*+,\-./:;<=>?@[\]^_`{|}~])/g;
@@ -230,12 +232,12 @@ function interiorBlankRunLengths(s: string): number[] {
}
export function addsBlankLines(baseline: string, candidate: string): boolean {
- const beforeEdges = carriedEdgeEmpties(baseline);
- const afterEdges = carriedEdgeEmpties(candidate);
+ const beforeEdges = bodyEdgeEmpties(baseline);
+ const afterEdges = bodyEdgeEmpties(candidate);
if (afterEdges.leading > beforeEdges.leading) return true;
if (afterEdges.trailing > beforeEdges.trailing) return true;
- const before = interiorBlankRunLengths(baseline);
- const after = interiorBlankRunLengths(candidate);
+ const before = interiorBlankRunLengths(stripFrontmatter(baseline).body);
+ const after = interiorBlankRunLengths(stripFrontmatter(candidate).body);
if (before.length !== after.length) return false;
return after.some((length, i) => length > (before[i] ?? 0));
}
diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.ts
index 754dc5cc2..0be5203e4 100644
--- a/packages/core/src/bridge/pm-structural-equivalence.ts
+++ b/packages/core/src/bridge/pm-structural-equivalence.ts
@@ -32,6 +32,7 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };
const BR_LITERAL_RE = /^<br\s*\/?>$/i;
+
interface DegradeEntry {
readonly label: string;
readonly severity: ToleranceClassSeverity;
@@ -127,6 +128,7 @@ export interface ComparePmStructuralOptions {
ignoreAttrs?: (attrKey: string) => boolean;
}
+
/** Rebuild a node with `fn` applied to each child; identity when childless.
* Shared by the degrade canonicalizers so none re-implements the walk. */
function mapChildren(
@@ -248,6 +250,7 @@ function applyDegrades(tree: PmStructuralNode): {
return { normalized: current, fired };
}
+
export function comparePmStructural(
expected: PmStructuralNode,
actual: PmStructuralNode,
diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.ts
index af20de1e2..dca644141 100644
--- a/packages/core/src/bridge/subsequence.ts
+++ b/packages/core/src/bridge/subsequence.ts
@@ -1,3 +1,4 @@
+
/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):
* insertions in `haystack` are free; any dropped or substituted `needle` byte
* fails. */
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e25463ef3..e09c459d9 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1397,6 +1397,7 @@ export {
type BridgeToleranceClass,
type BridgeToleranceSignal,
bindFrontmatterDoc,
+ bodyEdgeEmpties,
type ComparePmStructuralOptions,
type ComposeAdjustment,
classifySeverity,
@@ -1412,7 +1413,9 @@ export {
detectAppliedToleranceClasses,
detectFmRegion,
diffLinesFast,
+ docEdgeRunsDiffer,
emitToleranceFire,
+ type FmBoundarySlotSplit,
type FmEditError,
type FmEditResult,
FORM_WRITE_ORIGIN,
@@ -1455,6 +1458,7 @@ export {
type StructuralFreshnessChecker,
type StructuralFreshnessCheckerOptions,
setToleranceTelemetryHook,
+ splitFmBoundarySlot,
structuralDivergence,
type ToleranceClassSeverity,
type ToleranceFireRecord,
diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.ts
index 83d47404a..a363dfd54 100644
--- a/packages/core/src/markdown/callout-transformer.ts
+++ b/packages/core/src/markdown/callout-transformer.ts
@@ -1,3 +1,4 @@
+
import type { Blockquote, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.ts
index 9807a7e82..4499dbc92 100644
--- a/packages/core/src/markdown/code-fence.ts
+++ b/packages/core/src/markdown/code-fence.ts
@@ -1,3 +1,4 @@
+
export function selectFenceChar(info: string): '`' | '~' {
return info.includes('`') ? '~' : '`';
}
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index 7415c474a..34704165b 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.ts
index ece5c02a1..b6299a948 100644
--- a/packages/core/src/markdown/dedent-block-jsx-close.ts
+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts
@@ -1,3 +1,4 @@
+
import { findFencedRegions, isInsideFence } from './fence-regions.ts';
const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;
diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.ts
index 54774764a..acd398aa6 100644
--- a/packages/core/src/markdown/details-accordion-promoter.ts
+++ b/packages/core/src/markdown/details-accordion-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.ts
index 43ecdc709..ba9b56384 100644
--- a/packages/core/src/markdown/div-align-promoter.ts
+++ b/packages/core/src/markdown/div-align-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.ts
index 6d3f3643e..4513da9bb 100644
--- a/packages/core/src/markdown/fence-regions.ts
+++ b/packages/core/src/markdown/fence-regions.ts
@@ -1,3 +1,4 @@
+
const FENCE_RE = /^(`{3,}|~{3,})/gm;
export function findFencedRegions(src: string): Array<[number, number]> {
diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.ts
index 00f5771ee..6931623c7 100644
--- a/packages/core/src/markdown/fixtures/index.ts
+++ b/packages/core/src/markdown/fixtures/index.ts
@@ -1,3 +1,4 @@
+
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {
return resolve(FIXTURES_DIR, ...segments);
}
+
interface GfmExample {
section: string;
markdown: string;
@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {
return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];
}
+
interface MdxCrashEntry {
id: string;
input: string;
@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {
) as LargeEmbedFixture[];
}
+
export function loadPrd6955Before(): string {
return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');
}
@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {
return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');
}
+
export interface NgPinnedCase {
id: string;
name: string;
@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {
) as NgPinnedCase[];
}
+
export function loadLargeRealistic(): string {
return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');
}
diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.ts
index 8b1eb8519..daa3ef82b 100644
--- a/packages/core/src/markdown/fixtures/perf/generate.ts
+++ b/packages/core/src/markdown/fixtures/perf/generate.ts
@@ -1,3 +1,4 @@
+
import { writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;
const SEED = 0xf1de1117;
+
function mulberry32(seed: number): () => number {
let a = seed >>> 0;
return () => {
@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {
return items[items.length - 1][0];
}
+
const WORDS = [
'lorem',
'ipsum',
@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {
return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;
}
+
type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';
const MIX: readonly [BlockKind, number][] = [
@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {
return `${blocks.join('\n\n')}\n`;
}
+
function main(): void {
for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {
const doc = generateDocument(count, SEED);
diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.ts
index 420dc0fe5..32c055c5b 100644
--- a/packages/core/src/markdown/guard-flanking-matrix.ts
+++ b/packages/core/src/markdown/guard-flanking-matrix.ts
@@ -7,6 +7,7 @@ import {
import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';
import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';
+
export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;
export type FlankClass = 'whitespace' | 'punctuation' | 'other';
diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.ts
index 2653473da..283913255 100644
--- a/packages/core/src/markdown/handler-shadow-audit.ts
+++ b/packages/core/src/markdown/handler-shadow-audit.ts
@@ -1,3 +1,4 @@
+
export interface HandlerShadowWitness {
input: string;
expect: 'byte' | 'byte-and-reparse-type';
diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.ts
index da0a81d23..5d1000cc4 100644
--- a/packages/core/src/markdown/highlight-promoter.ts
+++ b/packages/core/src/markdown/highlight-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.ts
index 787315157..9681c0056 100644
--- a/packages/core/src/markdown/html-to-mdast.ts
+++ b/packages/core/src/markdown/html-to-mdast.ts
@@ -1,3 +1,4 @@
+
import type { Element as HastElement, Root as HastRoot } from 'hast';
import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';
import rehypeParse from 'rehype-parse';
@@ -128,7 +129,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRo
throw new HtmlPayloadTooLargeError(html.length, maxBytes);
}
- const processor = unified().use(rehypeParse, { fragment: true });
+ const processor = unified()
+ .use(rehypeParse, { fragment: true });
for (const plugin of cleanupPlugins) {
processor.use(plugin);
diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.ts
index 706fa9afb..994eb6917 100644
--- a/packages/core/src/markdown/image-promoter.ts
+++ b/packages/core/src/markdown/image-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Image, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.ts
index 9075aa7f1..69221627d 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromPmMark,
@@ -206,6 +207,7 @@ export class MarkdownManager {
}
}
+
const registry = createRegistry();
function destructureAttrs(
@@ -254,6 +256,7 @@ function destructureAttrs(
return result;
}
+
function hasDirtyDescendant(node: PmNode): boolean {
let found = false;
node.descendants((child) => {
@@ -276,6 +279,7 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChec
return freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;
}
+
function isEmptyMdastParagraph(node: MdastNodes): boolean {
if (node.type !== 'paragraph') return false;
const children = node.children ?? [];
@@ -344,6 +348,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {
return out;
}
+
import {
AUDIO_EXTENSIONS,
FILE_ATTACHMENT_EXTENSIONS,
@@ -596,6 +601,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.emphasis) {
handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({
sourceDelimiter: node.data?.sourceDelimiter ?? '*',
@@ -676,6 +682,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.link) {
const sourceLiteralMark = m.sourceLiteral;
handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {
@@ -973,6 +980,7 @@ function buildMdastToPmHandlers(
};
}
+
const blockUnknownHandler = (node: {
type: string;
position?: { start: { offset: number }; end: { offset: number } };
@@ -1098,6 +1106,7 @@ function buildMdastToPmHandlers(
return handlers as RemarkProseMirrorOptions['handlers'];
}
+
function buildPmToMdastHandlers(
schema: Schema,
freshness: FreshnessCheckerHolder,
diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.ts
index fa0be9e86..b79e9aef7 100644
--- a/packages/core/src/markdown/lint/applies-to.ts
+++ b/packages/core/src/markdown/lint/applies-to.ts
@@ -1,3 +1,4 @@
+
import picomatch from 'picomatch';
import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';
diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.ts
index 312c9c74b..94b34dee1 100644
--- a/packages/core/src/markdown/lint/config-files.ts
+++ b/packages/core/src/markdown/lint/config-files.ts
@@ -1,3 +1,4 @@
+
const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set([
'.markdownlint.json',
'.markdownlint.jsonc',
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index 0ba33b7d8..e413367ef 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -38,6 +38,7 @@ const fullPluginShape = Object.fromEntries(
LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),
) as z.ZodRawShape;
+
export const LinterConfigSchema = z.object({
enabled: z.boolean(),
plugins: z.object(fullPluginShape),
diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.ts
index d48eea5e4..a51f2ffb0 100644
--- a/packages/core/src/markdown/lint/default-config.ts
+++ b/packages/core/src/markdown/lint/default-config.ts
@@ -6,6 +6,7 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSetting
MD013: false,
};
+
export function resolveMarkdownlintConfig(
rules: Record<string, MarkdownlintRuleSetting> | undefined,
): Configuration {
diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
index ef478e268..9c9542661 100644
--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
@@ -1,3 +1,4 @@
+
import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';
export interface FrontmatterFieldConstraint {
diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.ts
index 0d4c9a0df..b96d19182 100644
--- a/packages/core/src/markdown/lint/frontmatter-validate.ts
+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts
@@ -1,3 +1,4 @@
+
import Ajv, { type ValidateFunction } from 'ajv';
import Ajv2019 from 'ajv/dist/2019.js';
import Ajv2020 from 'ajv/dist/2020.js';
diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.ts
index 00d08265a..48d260ed6 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -1,3 +1,4 @@
+
import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';
import type { LintDiagnostic } from './types.ts';
diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.ts
index 5e832aa19..be5871ed9 100644
--- a/packages/core/src/markdown/lint/plugins.ts
+++ b/packages/core/src/markdown/lint/plugins.ts
@@ -1,3 +1,4 @@
+
import { z } from 'zod';
import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';
import {
@@ -13,6 +14,7 @@ import {
type MarkdownlintSlice,
} from './types.ts';
+
const MarkdownlintRuleSettingSchema = z.union([
z.boolean(),
z.enum(MARKDOWNLINT_RULE_SEVERITIES),
diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.ts
index 3918e657c..833c3a727 100644
--- a/packages/core/src/markdown/lint/types.ts
+++ b/packages/core/src/markdown/lint/types.ts
@@ -1,3 +1,4 @@
+
export const LINT_PLUGIN_IDS = ['markdownlint', 'frontmatter'] as const;
export type LintPluginId = (typeof LINT_PLUGIN_IDS)[number];
@@ -71,6 +72,7 @@ export interface FrontmatterSlice {
schemas: ResolvedFrontmatterSchemaEntry[];
}
+
interface RuleOptionSpecBase {
key: string;
description: string;
diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.ts
index 98238656e..437cc539a 100644
--- a/packages/core/src/markdown/lint/validation-counts.ts
+++ b/packages/core/src/markdown/lint/validation-counts.ts
@@ -1,3 +1,4 @@
+
export interface ValidationSourceCounts {
errorCount: number;
warningCount: number;
diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.ts
index a5b511f25..bd79424c7 100644
--- a/packages/core/src/markdown/math-promoter.ts
+++ b/packages/core/src/markdown/math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { Math as MdastMath } from 'mdast-util-math';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.ts
index ed89371d0..00fbc0035 100644
--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts
+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Properties } from 'hast';
import type { FootnoteDefinition, FootnoteReference } from 'mdast';
import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.ts
index 8ce2b2492..df788a80d 100644
--- a/packages/core/src/markdown/mdast-to-html.ts
+++ b/packages/core/src/markdown/mdast-to-html.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root as HastRoot, Text as HastText } from 'hast';
import type { Root as MdastRoot, Text as MdastText } from 'mdast';
import type { Handler } from 'mdast-util-to-hast';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.ts
index 1a897fca8..17ed2b829 100644
--- a/packages/core/src/markdown/mermaid-promoter.ts
+++ b/packages/core/src/markdown/mermaid-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.ts
index d988f4b8b..4aa0490c4 100644
--- a/packages/core/src/markdown/parse-with-fallback.ts
+++ b/packages/core/src/markdown/parse-with-fallback.ts
@@ -168,6 +168,7 @@ export function parseRecursive(
}
}
+
interface VFilePlace {
offset?: number;
start?: { offset?: number };
@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {
return undefined;
}
+
interface Region {
start: number;
end: number;
@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {
return null;
}
+
export interface TagEvent {
kind: 'open' | 'close' | 'self-close';
name: string;
@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {
return { start: blockStart, end: blockEnd };
}
+
interface SourceBlock {
src: string;
start: number;
@@ -452,6 +456,7 @@ function tryPerBlockFallback(
};
}
+
function wholeDocRawText(source: string): JSONContent {
return {
type: 'doc',
diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.ts
index e6ab4fd57..43d420187 100644
--- a/packages/core/src/markdown/parser-drop-closure.ts
+++ b/packages/core/src/markdown/parser-drop-closure.ts
@@ -1,3 +1,4 @@
+
export type DroppedTokenAdjudication =
| {
kind: 'format-dof-axis';
diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.ts
index 449e6f12f..5af2f05f5 100644
--- a/packages/core/src/markdown/pipeline.ts
+++ b/packages/core/src/markdown/pipeline.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromProseMirror,
diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.ts
index 91cdf658f..ccf06e94d 100644
--- a/packages/core/src/markdown/position-aware-join.ts
+++ b/packages/core/src/markdown/position-aware-join.ts
@@ -1,3 +1,4 @@
+
import type { Join } from 'mdast-util-to-markdown';
import type { Position } from 'unist';
import { isBlankLineParagraph } from './zero-emission-blocks.ts';
diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.ts
index 0f399d34c..e5b4c9eba 100644
--- a/packages/core/src/markdown/position-slice.ts
+++ b/packages/core/src/markdown/position-slice.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Root } from 'mdast';
import { visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
@@ -476,7 +477,8 @@ export function applyPositionSliceToNode(
const first = source[startOff];
if (first !== '[' && first !== '<' && !node.title) {
node.data.sourceStyle = 'gfm-autolink';
- } else if (first === '[') {
+ }
+ else if (first === '[') {
const slice = source.slice(startOff, endOff);
const closeBracketIdx = slice.lastIndexOf('](');
if (closeBracketIdx !== -1) {
diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
index db10fa54b..ca225ce9b 100644
--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, Root, Text } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
index 34068d103..3a2524a9a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
index 93151d43b..2279a0189 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
index 188f02d83..a0f467c42 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
index 4ba2c3418..4e8542a21 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
index 1a74b1272..a3c96b24a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
index de35e7b79..e95cf43d6 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
index b4be1b2ea..ffdb4d5b5 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
index 3c8d88b7c..e2a96d1a7 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.ts
index cf2c9da8e..0389575ac 100644
--- a/packages/core/src/markdown/resolve-image-url.ts
+++ b/packages/core/src/markdown/resolve-image-url.ts
@@ -1,3 +1,4 @@
+
import { isRelativeUrl } from './safe-url.ts';
function isDevDiagnosticContext(): boolean {
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
index 0dd54070e..96304e7a5 100644
--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts
+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
@@ -1,3 +1,4 @@
+
import type { JSONContent } from '@tiptap/core';
import type { Nodes } from 'mdast';
import { expect } from 'vitest';
diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.ts
index 7cac5b042..93798cf83 100644
--- a/packages/core/src/markdown/serialize-helpers.ts
+++ b/packages/core/src/markdown/serialize-helpers.ts
@@ -1,3 +1,4 @@
+
import type { Node as PmNode } from '@tiptap/pm/model';
import type {
MdxJsxAttribute,
diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.ts
index b012a5aff..8c08b7a04 100644
--- a/packages/core/src/markdown/single-dollar-math-promoter.ts
+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { PhrasingContent, Root, Text } from 'mdast';
import type { InlineMath } from 'mdast-util-math';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.ts
index 3e79f8cb6..959cc0bd2 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parents } from 'mdast';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import type { Handle, Info, State } from 'mdast-util-to-markdown';
diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.ts
index 0f1b0f27d..6e6d73400 100644
--- a/packages/core/src/markdown/underline-promoter.ts
+++ b/packages/core/src/markdown/underline-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.ts
index 1a082bda7..932d7d2a8 100644
--- a/packages/core/src/markdown/unknown-mdast-guard.ts
+++ b/packages/core/src/markdown/unknown-mdast-guard.ts
@@ -1,3 +1,4 @@
+
import type { Root as MdastRoot } from 'mdast';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.ts
index d578476a7..ac9f5239b 100644
--- a/packages/core/src/markdown/whitespace-char-ref.ts
+++ b/packages/core/src/markdown/whitespace-char-ref.ts
@@ -1,3 +1,4 @@
+
const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([
[0x20, ' '],
[0x09, '\t'],
diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.ts
index 6dad26200..afd9936fe 100644
--- a/packages/core/src/markdown/wiki-link-micromark.ts
+++ b/packages/core/src/markdown/wiki-link-micromark.ts
@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {
}
}
+
const CODE_BANG = 33; // !
const CODE_LBRACKET = 91; // [
const CODE_RBRACKET = 93; // ]
@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {
};
}
+
function enterWikiLink(this: CompileContext, token: Token) {
this.enter(
{
@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {
unsafe: [{ character: '[', inConstruct: ['phrasing'] }],
};
+
const MICROMARK_EXT = wikiLinkSyntax();
export function remarkWikiLink(this: Processor) {
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index cbc848739..8a1d1a34e 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -8930,6 +8930,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
const doc = hocuspocus.documents.get(docName);
if (doc) await (forceUnloadDocument ?? hocuspocus.unloadDocument.bind(hocuspocus))(doc);
+ // Truncates the doc file to '' BY DESIGN — reset means empty. A test
+ // or probe that reads the on-disk bytes after `client.cleanup()` (which
+ // calls this route) observes the truncation, not data loss; read the
+ // file BEFORE cleanup, or detach the provider directly instead.
writeFileSync(filePath, '', 'utf-8');
await derivedDocumentIndex?.testOnly?.resetDocumentForTest(docName);
diff --git a/packages/server/src/server-observers.test.ts b/packages/server/src/server-observers.test.ts
index 924114c66..34d4b38eb 100644
--- a/packages/server/src/server-observers.test.ts
+++ b/packages/server/src/server-observers.test.ts
@@ -1722,6 +1722,32 @@ describe('Observer A routing — Path B fires iff Y.Text holds unabsorbed change
cleanup();
});
+ test('a merge-seam settlement converges the fragment in its own drain: the enqueued re-derive survives the witness tautology', () => {
+ // The post-merge settlement refreshes the raw witness from the ytext the
+ // enqueued same-drain Observer B fire reads, so without an explicit
+ // request flag the early-exit compares Y.Text against its own snapshot
+ // and drops the rebuild — the fragment then shows the merged keystroke
+ // only after some later drain happens to route through a repair path.
+ // Same-drain convergence is the enqueue's contract; pin it synchronously.
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(
+ 'Above.\n\nBelow.\n',
+ 'routing-seam-same-drain',
+ );
+
+ doc.transact(() => {
+ xmlFragment.insert(0, [new Y.XmlElement('paragraph'), new Y.XmlElement('paragraph')]);
+ ytext.insert(ytext.toString().length - 1, '!');
+ });
+
+ expect(ytext.toString()).toBe('\n\nAbove.\n\nBelow.!\n');
+ expect(serializeFragmentBody(xmlFragment)).toBe('\n\nAbove.\n\nBelow.!\n');
+
+ cleanup();
+ });
+
test('consecutive in-sync fragment edits on a beyond-tolerance doc each run the residual merge: the post-merge settlement restores coherence', () => {
// The settlement primitive (`recordSettledBaselines(md)`) at the end of a
// residual merge re-records BOTH witnesses and re-sets coherence, so the
diff --git a/packages/server/src/server-observers.ts b/packages/server/src/server-observers.ts
index 7ec07e7ea..a5eff19ef 100644
--- a/packages/server/src/server-observers.ts
+++ b/packages/server/src/server-observers.ts
@@ -24,6 +24,7 @@
import type { LocalTransactionOrigin } from '@hocuspocus/server';
import type {
+ BridgeComposition,
MarkdownManager,
PmStructuralNode,
StructuralDivergenceReason,
@@ -38,6 +39,7 @@ import {
composeWithDerivedBody,
createMergeBoundarySpace,
DUPLICATION_GATE_MIN_LINE_LENGTH,
+ docEdgeRunsDiffer,
fnv1aDigest,
fragmentHoldsPendingContent,
isParseEquivalentBridge,
@@ -46,6 +48,7 @@ import {
overMultipliedBodyLines,
pendingContentLines,
prependFrontmatter,
+ splitFmBoundarySlot,
stripFrontmatter,
} from '@inkeep/open-knowledge-core';
import type { Schema } from '@tiptap/pm/model';
@@ -872,6 +875,13 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// same-drain Observer B re-derive is enqueued. Mark the drain so the
// backstop can count it toward the re-derive-loop bound.
drainDidCorrectiveWork = true;
+ // The enqueue is an explicit request Observer B must not early-exit away.
+ // Split-brain settlements refresh the raw witness from this very ytext, so
+ // the early-exit's comparison is tautological on the enqueued drain — the
+ // request flag is what carries "the fragment needs rebuilding" across it.
+ // Cleared only when the re-derive actually runs; a defer or backstop
+ // freeze keeps it pending for the next drain.
+ pendingSplitBrainRederive = true;
// No-throw is structural, not incidental: every call site runs inside
// runObserverASyncImpl's try, after the state-critical witness writes and
// the `textDirty = true` B-enqueue. A throw escaping here would route
@@ -1311,6 +1321,15 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// in the same synchronous dispatch (no keystroke can interleave), so deferring
// it would strand the doubled fragment permanently.
let pendingDuplicationRecovery = false;
+ // Standing request from a split-brain settlement site: the fragment does not
+ // derive from current Y.Text and Observer B must rebuild it. Set by
+ // `recordSplitBrainRederive` (every enqueue site), cleared when the
+ // re-derive actually runs. Exists because those settlements refresh the raw
+ // witness from the same ytext the enqueued B fire will read, making the
+ // early-exit comparison a tautology exactly when the rebuild matters most —
+ // the interlock that let a diverged document swallow every later
+ // source-mode edit. A stale flag costs one idempotent re-derive.
+ let pendingSplitBrainRederive = false;
// Re-derive-loop fixed-point backstop. The re-derive cycle terminates
// on a RAW-BYTE fixed point: a drain whose settled Y.Text raw-equals the
@@ -1441,6 +1460,24 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
*/
const readCurrentFm = (): string => stripFrontmatter(ytext.toString()).frontmatter;
+ /**
+ * Compose a fragment-derived body into full-document bytes with the FM
+ * boundary slot restored from the CURRENT authored Y.Text bytes. Every
+ * fragment-derived compose in this observer pair MUST route through here
+ * (a direct `composeWithDerivedBody` / `prependFrontmatter` call on a
+ * fragment-derived body silently breaks slot consistency): the
+ * serializer emits the authored head run only (j empty paragraphs -> j
+ * newlines), while an FM document's authored bytes spell that run as
+ * slot + j newlines — a slot-less spelling at any one seam would disagree
+ * with the others in exactly the doc-edge dimension the gates compare,
+ * reading as a permanent phantom edge divergence. The slot is restored,
+ * never invented: a separator-less document composes without one.
+ */
+ const composeDerivedBodyMd = (frontmatter: string, derivedBody: string): BridgeComposition => {
+ const { slot } = splitFmBoundarySlot(frontmatter, stripFrontmatter(ytext.toString()).body);
+ return composeWithDerivedBody(frontmatter, slot + derivedBody);
+ };
+
/** Parse options for THIS doc's text→tree derivations. One shape shared by
* Observer B's full fire, the attach-time settlement check, and the
* parse-equivalence canonicalizer, so every parse of this doc resolves
@@ -1516,7 +1553,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const initialJson = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
const initialBody = mdManager.serialize(initialJson);
const initialFrontmatter = readCurrentFm();
- const canonicalInit = composeWithDerivedBody(initialFrontmatter, initialBody).md;
+ const canonicalInit = composeDerivedBodyMd(initialFrontmatter, initialBody).md;
// Observers normally attach after the persistence paired-write seed, so
// fragment = parse(ytext) and attach is a true settlement point — the raw
// witness then captures the seed bytes so the first fragment change on a
@@ -1748,7 +1785,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// leading rule when — and only when — the composition is genuinely
// ambiguous. Every witness and predicate below composes the same way, or
// the surplus line reads as pending content and defer-loops the doc.
- const composition = composeWithDerivedBody(frontmatter, body);
+ const composition = composeDerivedBodyMd(frontmatter, body);
const md = composition.md;
const currentText = ytext.toString();
@@ -1898,9 +1935,18 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// the WYSIWYG normalizes away and this gate would certify a settlement
// that drops it. The fragment is the authority for its own blank lines;
// the reverse direction (source richer than the fragment) stays
- // tolerated, since that is the container-interior case the fragment
- // cannot represent.
- if (normCurrent === normMd && !addsBlankLines(currentText, md)) {
+ // tolerated for the container INTERIOR, the case the fragment cannot
+ // represent. The document edges are their own dimension: a run worth
+ // carrying is representable on both sides, so an edge disagreement in
+ // EITHER direction (the fragment gained a run Y.Text lacks, or dropped
+ // one Y.Text still carries) is an ordinary un-propagated edit and the
+ // gate must not certify over it — a WYSIWYG deletion of a carried edge
+ // run read as tolerated residual would strand the bytes forever.
+ if (
+ normCurrent === normMd &&
+ !addsBlankLines(currentText, md) &&
+ !docEdgeRunsDiffer(currentText, md)
+ ) {
// Why the gate certified, as a two-value enum. Both outcomes stamp the
// same path, so a settlement over bytes the tolerance set swallowed is
// indistinguishable in traces from one where the sides genuinely
@@ -1980,7 +2026,16 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// once Y.Text holds the guarded bytes the serializer preserves them
// via sourceRaw, the composition is unambiguous, and the splice —
// the more byte-preserving path — runs again.
- (ytextInSync && residualMergeEligible) || composition.adjusted !== 'none'
+ // Doc-edge-run drains decline the splice for the same reason the
+ // guarded-respell transition does: the splice is a pure body-space
+ // rewrite computed straight off the fragment, blind to the FM
+ // boundary-slot dimension `md` carries — on a head-run deletion it
+ // would consume the separator newline along with the run. The
+ // md-based paths below spell the slot correctly, and edge-run drains
+ // are rare enough that the splice's byte-preservation is not missed.
+ (ytextInSync && residualMergeEligible) ||
+ composition.adjusted !== 'none' ||
+ docEdgeRunsDiffer(currentText, md)
? null
: tryComputeMapDrivenSplice({
currentText,
@@ -2235,7 +2290,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
try {
const recoveryJson = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
const recoveryBody = mdManager.serialize(recoveryJson);
- const recoveryMd = composeWithDerivedBody(readCurrentFm(), recoveryBody).md;
+ const recoveryMd = composeDerivedBodyMd(readCurrentFm(), recoveryBody).md;
if (settlesSplitBrainChecked(ytext.toString(), recoveryMd)) {
recordSplitBrainRecoveryBaselines(recoveryMd);
textDirty = true;
@@ -2323,6 +2378,23 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
try {
const frontmatter = readCurrentFm();
refreshYTextWitness();
+ // A paired write is a both-sides settlement by construction: the
+ // primitive landed fragment = parse(md) and Y.Text = md in ONE
+ // transaction, so there is no un-propagated WYSIWYG content and the
+ // written bytes hold every line the fragment now serializes to
+ // (modulo respell, which the three-way predicate tolerates the same
+ // way it tolerates freshness respells). Recording the convergence
+ // here is what keeps the defer guard's witness from going stale-empty
+ // across paired-write-seeded docs — a stale witness reads every stale
+ // fragment line as pending and defers the very re-derive that would
+ // repair a later divergence, up to the exhaustion bound. This is NOT
+ // the freshness-suppressed-settlement case the witness comment warns
+ // about: the fragment is exactly AT the written content, not ahead of
+ // its stamped sourceRaw. Raw bytes, not serialize(fragment) — the
+ // O(N) serialize stays off the paired hot path.
+ lastConvergedFragmentMd = lastSyncedYTextBytes;
+ fragmentMutatedSinceConverge = false;
+ consecutiveDeriveTimingDefers = 0;
// Refresh the FM telemetry baseline alongside the bridge baseline.
// Without this, an agent paired-write that changes FM advances
// the raw witness but leaves `priorFmForTelemetry` stale; the
@@ -2360,7 +2432,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// Same ambiguity as the drain, one seed earlier: a fragment carrying a
// doc-start rule pair would seed bytes an empty Y.Text can never
// re-derive from.
- const md = composeWithDerivedBody(frontmatter, body).md;
+ const md = composeDerivedBodyMd(frontmatter, body).md;
doc.transact(() => {
ytext.insert(0, md);
}, OBSERVER_SYNC_ORIGIN);
@@ -2395,7 +2467,16 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const runObserverBSyncImpl = (): void => {
try {
const md = ytext.toString();
+
const { frontmatter, body } = stripFrontmatter(md);
+ // The FM boundary slot is split off before the frontmatter-blind parser
+ // sees the body, so the separator line never mints an empty paragraph:
+ // an FM document spells j authored head empties as slot + j newlines,
+ // and handing the parser the raw body would mint j + 1. The slot is
+ // restored on every fragment-derived compose (`composeDerivedBodyMd`
+ // and the canonical forms below), keeping both spellings of the same
+ // document byte-consistent across the gates' edge comparisons.
+ const { slot: fmBoundarySlot, body: parseBody } = splitFmBoundarySlot(frontmatter, body);
// Early-exit: if Y.Text already matches the last settled Y.Text
// snapshot (via normalizeBridge), tree and text are in sync.
@@ -2408,7 +2489,24 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// WITHOUT refreshing any witness, so the router still sees it as
// real divergence and routes the next fragment change through the
// byte-preserving Path B merge.
- if (normalizeBridge(lastSyncedYTextBytes) === normalizeBridge(md)) {
+ //
+ // Two carve-outs, each a case where "Y.Text unchanged since settlement"
+ // does NOT mean "fragment in sync":
+ // - A pending split-brain re-derive request: the settlement that
+ // enqueued this fire refreshed the raw witness from this very
+ // `ytext`, so the comparison is tautological and exiting on it
+ // strands the diverged fragment permanently (and with it every
+ // later source-mode edit).
+ // - The doc-edge dimension: an edge run gained or lost by Y.Text
+ // relative to the settled snapshot rests INSIDE the normalize
+ // tolerance by construction, and only this re-derive can move it
+ // into (or out of) the fragment — early-exiting over it is what
+ // made source-authored edge runs invisible to every WYSIWYG.
+ if (
+ !pendingSplitBrainRederive &&
+ normalizeBridge(lastSyncedYTextBytes) === normalizeBridge(md) &&
+ !docEdgeRunsDiffer(lastSyncedYTextBytes, md)
+ ) {
// Tree and text are already in sync. FM region is already where it
// should be (Y.Text is the source of truth). Just emit telemetry if
// the FM changed.
@@ -2475,7 +2573,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// comparand here reads the re-spelled rule as a surplus line, defers
// every drain, and force-resolves an innocent doc at the exhaustion
// bound.
- const freshFragmentMd = composeWithDerivedBody(frontmatter, freshFragmentBody).md;
+ const freshFragmentMd = composeDerivedBodyMd(frontmatter, freshFragmentBody).md;
if (fragmentHoldsPendingContent(freshFragmentMd, md, lastConvergedFragmentMd)) {
if (consecutiveDeriveTimingDefers >= MAX_DERIVE_TIMING_DEFERS) {
// Exhaustion. The keystroke has stayed un-propagated across the full
@@ -2529,7 +2627,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// Y.Text-is-truth; "sole writer" is scoped to the server process, not the
// whole system. The "always-live" contract here means no client sees
// frozen WYSIWYG when another peer is mid-typing a broken MDX tag.
- const parsedJson = mdManager.parseWithFallback(body, observerParseOpts);
+ const parsedJson = mdManager.parseWithFallback(parseBody, observerParseOpts);
const pmNode = opts.schema.nodeFromJSON(parsedJson);
@@ -2537,6 +2635,12 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const meta = { mapping: new Map(), isOMark: new Map() };
updateYFragment(doc, xmlFragment, pmNode, meta);
}, OBSERVER_SYNC_ORIGIN);
+ // The rebuild has landed — only now is any standing split-brain request
+ // served. `nodeFromJSON` / `updateYFragment` above can throw, and the
+ // outer catch's witness refresh leaves the raw comparand tautological
+ // for the split-brain case; a pre-rebuild clear would hand the next
+ // fire exactly the early-exit this flag exists to block.
+ pendingSplitBrainRederive = false;
// The re-derive is corrective reconciliation work; whether it reached a
// raw-byte fixed point is decided by the post-sync convergence check
@@ -2578,7 +2682,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// unreachable on this leg and the two composes are byte-equal. The
// bridge compose module's tests pin that no-op rather than assuming
// it, so this stays a checked coincidence and not a lucky one.
- const canonicalYText = prependFrontmatter(frontmatter, canonicalBody);
+ const canonicalYText = prependFrontmatter(frontmatter, fmBoundarySlot + canonicalBody);
assertBridgeInvariant(ytext.toString(), canonicalYText, {
site: 'observer-b',
docName: opts.docName,
@@ -2586,7 +2690,8 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// the watchdog's fallback canonicalizes the SAME body B parsed
// above, and re-running parse+serialize per fire is exactly the
// extra O(N) pass the parsedJson reuse note above exists to avoid.
- canonicalizeBody: (b) => (b === body ? canonicalBody : canonicalizeBody(b)),
+ canonicalizeBody: (b) =>
+ b === body ? fmBoundarySlot + canonicalBody : canonicalizeBody(b),
});
// Maintain Observer A's witnesses — B just absorbed Y.Text into the
// fragment, a true settlement point. The canonical witness records
@@ -2638,7 +2743,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const postJson = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
const postBody = mdManager.serialize(postJson);
const fm = readCurrentFm();
- refreshCanonicalWitnessOnly(composeWithDerivedBody(fm, postBody).md);
+ refreshCanonicalWitnessOnly(composeDerivedBodyMd(fm, postBody).md);
} catch (innerErr) {
// Mirror the two `instanceof BridgeInvariantViolationError` catches
// above — preserve `BridgeInvariantViolationError` throws past this
@@ -2891,7 +2996,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
// Observer A drain applies the guard properly. Steady state is
// unaffected — once Y.Text holds the re-spelled rule the serializer
// preserves it via sourceRaw and the composition is unambiguous again.
- const flushComposition = composeWithDerivedBody(readCurrentFm(), mdManager.serialize(json));
+ const flushComposition = composeDerivedBodyMd(readCurrentFm(), mdManager.serialize(json));
if (flushComposition.adjusted !== 'none') {
return { preDrain: false, reason: 'checkpoint-fm-ambiguous' };
}