Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Harden JSX serialization fidelity and unregistered-JSX coverage (#2451)

Nick Gomez4f8f09f4b2c9
diff --git a/.changeset/jsx-interior-edit-freshness.md b/.changeset/jsx-interior-edit-freshness.md
new file mode 100644
index 000000000..20e69bd10
--- /dev/null
+++ b/.changeset/jsx-interior-edit-freshness.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Editing inside a Callout, tab, accordion, or table cell in the visual editor now always reaches collaborators and reopens with exactly the content you see. Previously the editor could hold a cached copy of a component's original source and, when the inside was edited, serialize those stale bytes for everyone else — your own editor looked right while a teammate (or a fresh reopen) got the pre-edit content, or in rare cases structurally-broken markdown. The server now re-derives a component's markdown whenever its live contents diverge from that cached source, regardless of which surface made the edit, so what you see is what everyone gets. A drain-time legality check backs this up: if a serialization would still lose content, it is caught at the moment the bytes are written and a recoverable snapshot is kept instead of shipping the corruption.
diff --git a/packages/app/package.json b/packages/app/package.json
index 4ac432fef..5b9b286ab 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -26,7 +26,7 @@
"measure:fuzz": "bash scripts/measure-fuzz.sh",
"measure:stress": "bash scripts/measure-stress.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/file-tree-compact-folders.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/sidebar-search-pill.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",
+ "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/file-tree-compact-folders.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/sidebar-search-pill.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",
"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",
@@ -51,7 +51,7 @@
{
"name": "all JS chunks combined (gzipped)",
"path": "dist/assets/*.js",
- "limit": "3.05 MB",
+ "limit": "3.06 MB",
"gzip": true,
"running": false
},
diff --git a/packages/app/src/editor/extensions/raw-mdx-nested-copy-version-pin.test.ts b/packages/app/src/editor/extensions/raw-mdx-nested-copy-version-pin.test.ts
new file mode 100644
index 000000000..cfcbcc1e9
--- /dev/null
+++ b/packages/app/src/editor/extensions/raw-mdx-nested-copy-version-pin.test.ts
@@ -0,0 +1,86 @@
+/**
+ * Version-pin guard for copy-out-of-the-nested-CodeMirror-box behavior.
+ *
+ * Why a version pin and not a browser E2E:
+ *
+ * A real-browser probe copied a sub-selection out of an unregistered
+ * component's nested rawMdxFallback CodeMirror box and observed that the
+ * clipboard is POPULATED — the ProseMirror #1068
+ * empty-clipboard-under-mouse-focus class does not reproduce here, even
+ * though the outer ProseMirror holds a NodeSelection on the raw box while the
+ * selection lives inside the nested editable (the exact #1068 topology).
+ *
+ * The behavior is owned entirely by third-party code: CodeMirror's own copy
+ * handler writes the sub-selection to `text/plain`, and prosemirror-view's DOM
+ * copy handler declines to overwrite it. No Open-Knowledge-owned lever
+ * reproduces the empty-clipboard class — flipping the raw box NodeView's
+ * `stopEvent` does not change the outcome. A browser E2E asserting "clipboard
+ * populated" would therefore be non-falsifiable by any in-repo regression, and
+ * the exact copied text is word-wrap-dependent (visual-line selection), so an
+ * exact-string assertion would flake. Both make such an E2E a permanently-
+ * green smoke check rather than a guard.
+ *
+ * What genuinely gates the observed-good behavior is the resolved version of
+ * the two packages that own the copy handlers: prosemirror-view (transitive
+ * via @tiptap/pm — no direct dep to bump) and @codemirror/view (direct dep).
+ * This guard floors both at the versions the probe verified. A downgrade below
+ * either — e.g. a @tiptap/pm bump that pulls an older prosemirror-view, or a
+ * @codemirror/view downgrade — trips the guard so someone re-runs the browser
+ * probe before shipping. Forward drift within the floor passes untouched.
+ *
+ * This follows the same resolve-and-assert shape other version-floor guards
+ * in the repo use.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+/**
+ * Versions the nested-box copy behavior was verified working at. A resolved
+ * version below any of these means the copy-handler ownership may have shifted
+ * — re-run the browser probe (select inside `.raw-mdx-fallback-wrapper
+ * .cm-content`, copy, confirm `text/plain` is populated) before raising them.
+ */
+// The floor equals the exact resolved versions, so it has zero headroom: an
+// unrelated transitive-dep bump can trip it with no direct-dep fix (re-run the
+// browser probe to re-baseline). Uses Bun-lenient require.resolve of a package
+// subpath (Node would throw ERR_PACKAGE_PATH_NOT_EXPORTED) — fine in this Bun subtree.
+const VERIFIED_FLOOR = {
+ 'prosemirror-view': '1.41.8',
+ '@codemirror/view': '6.41.0',
+} as const;
+
+const require_ = createRequire(import.meta.url);
+
+function resolvedVersion(pkg: string): string {
+ const pkgJsonPath = require_.resolve(`${pkg}/package.json`);
+ const parsed = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) as { version: string };
+ return parsed.version;
+}
+
+/** Return true when `actual` is >= `floor` by numeric major.minor.patch order. */
+function meetsFloor(actual: string, floor: string): boolean {
+ const toParts = (v: string): number[] =>
+ v
+ .split('-')[0] // drop any prerelease suffix
+ .split('.')
+ .map((n) => Number.parseInt(n, 10));
+ const a = toParts(actual);
+ const f = toParts(floor);
+ for (let i = 0; i < 3; i++) {
+ const av = a[i] ?? 0;
+ const fv = f[i] ?? 0;
+ if (av !== fv) return av > fv;
+ }
+ return true; // equal
+}
+
+describe('nested rawMdxFallback copy — third-party copy-handler version floor', () => {
+ for (const [pkg, floor] of Object.entries(VERIFIED_FLOOR)) {
+ test(`${pkg} resolves at or above the probe-verified ${floor}`, () => {
+ const actual = resolvedVersion(pkg);
+ expect(meetsFloor(actual, floor)).toBe(true);
+ });
+ }
+});
diff --git a/packages/app/src/editor/extensions/source-dirty-flip.dom.test.tsx b/packages/app/src/editor/extensions/source-dirty-flip.dom.test.tsx
new file mode 100644
index 000000000..4b093bb07
--- /dev/null
+++ b/packages/app/src/editor/extensions/source-dirty-flip.dom.test.tsx
@@ -0,0 +1,143 @@
+/**
+ * Interior-content flip pin — the real-engine (mounted-editor) rung.
+ *
+ * The source-dirty observer's `contentChanged` branch is the sole guardian of
+ * registered PM-editable interiors: when a user edits INSIDE a pristine
+ * jsxComponent (Callout/Accordion/Tabs), the flip is what re-routes serialize
+ * off the verbatim-sourceRaw fast path onto the fresh re-derive path. If that
+ * branch ever stops firing, the editor keeps showing the edit while every
+ * fresh parser (teammate, reopen, disk) sees the stale pre-edit bytes.
+ *
+ * The origin-guard suite drives the plugin against a hand-rolled EditorState;
+ * this drives a mounted `new Editor` so the flip is exercised through the same
+ * dispatch → appendTransaction path production uses. The edit is content-only
+ * (no prop change) so the pin isolates the `contentChanged` term specifically:
+ * reverting only that term turns this test red.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { sharedExtensions as coreExtensions, MarkdownManager } from '@inkeep/open-knowledge-core';
+import { cleanup } from '@testing-library/react';
+import { Editor, type JSONContent } from '@tiptap/core';
+// The app extensions carry the SourceDirtyObserver plugin + jsxComponent
+// NodeView; the mounted editor must use these, not core's (which omit the
+// observer). Serialization still goes through core's MarkdownManager — the
+// same server-side path that turns app-editor JSON into persisted bytes.
+import { sharedExtensions } from './shared';
+
+const mdManager = new MarkdownManager({ extensions: coreExtensions });
+
+const CALLOUT_SOURCE_RAW = '<Callout title="A">\n\nA body\n\n</Callout>';
+
+/** A doc with one pristine (sourceDirty:false) Callout carrying authoritative
+ * sourceRaw + a paragraph child — the shape mdast→PM parse handlers emit. */
+function pristineCalloutDoc(): JSONContent {
+ return {
+ type: 'doc',
+ content: [
+ {
+ type: 'jsxComponent',
+ attrs: {
+ content: '',
+ componentName: 'Callout',
+ kind: 'element',
+ attributes: [],
+ sourceRaw: CALLOUT_SOURCE_RAW,
+ sourceDirty: false,
+ props: { title: 'A' },
+ },
+ content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A body' }] }],
+ },
+ ],
+ };
+}
+
+function mountEditor(content: JSONContent): { editor: Editor; container: HTMLElement } {
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ const editor = new Editor({
+ element: container,
+ content,
+ extensions: sharedExtensions,
+ editable: true,
+ });
+ return { editor, container };
+}
+
+/** First jsxComponent position + a text position inside its interior. */
+function locateCalloutInterior(editor: Editor): { calloutPos: number; interiorTextPos: number } {
+ let calloutPos = -1;
+ let interiorTextPos = -1;
+ editor.state.doc.descendants((node, pos) => {
+ if (node.type.name === 'jsxComponent' && calloutPos === -1) {
+ calloutPos = pos;
+ return true; // descend into the component
+ }
+ if (calloutPos !== -1 && node.isText && interiorTextPos === -1) {
+ interiorTextPos = pos + 1; // inside the text run
+ return false;
+ }
+ return true;
+ });
+ if (calloutPos === -1 || interiorTextPos === -1) {
+ throw new Error('Callout interior text not found');
+ }
+ return { calloutPos, interiorTextPos };
+}
+
+function calloutSourceDirty(editor: Editor): boolean {
+ let dirty = false;
+ editor.state.doc.descendants((node) => {
+ if (node.type.name === 'jsxComponent') {
+ dirty = Boolean(node.attrs.sourceDirty);
+ return false;
+ }
+ return true;
+ });
+ return dirty;
+}
+
+describe('interior-content edit flips sourceDirty and re-derives serialization', () => {
+ afterEach(() => {
+ cleanup();
+ });
+
+ test('an in-place interior edit flips sourceDirty and the serializer re-derives fresh bytes', () => {
+ const { editor, container } = mountEditor(pristineCalloutDoc());
+ try {
+ // The Callout mounts pristine — a fresh-insert with authoritative
+ // sourceRaw must not be pre-marked dirty, or the pin proves nothing.
+ expect(calloutSourceDirty(editor)).toBe(false);
+
+ const { interiorTextPos } = locateCalloutInterior(editor);
+ editor.commands.insertContentAt(interiorTextPos, 'ZZZ');
+
+ // Same dispatch: reading editor.state after the single command reflects
+ // both the content mutation and the appended sourceDirty flip.
+ expect(calloutSourceDirty(editor)).toBe(true);
+
+ // The serializer must re-derive from the fragment: the edited token
+ // reaches the bytes, and the output is no longer the verbatim sourceRaw.
+ const serialized = mdManager.serialize(editor.getJSON());
+ expect(serialized).toContain('ZZZ');
+ expect(serialized).not.toBe(CALLOUT_SOURCE_RAW);
+ } finally {
+ editor.destroy();
+ container.remove();
+ }
+ });
+
+ test('serialize stays on the verbatim-sourceRaw fast path when the interior is untouched', () => {
+ // The complement of the flip pin: an unedited pristine Callout must emit
+ // its sourceRaw verbatim (no ZZZ, no re-derive). Together the two tests
+ // show the flip is what moves serialize between the two paths.
+ const { editor, container } = mountEditor(pristineCalloutDoc());
+ try {
+ expect(calloutSourceDirty(editor)).toBe(false);
+ const serialized = mdManager.serialize(editor.getJSON());
+ expect(serialized.trim()).toBe(CALLOUT_SOURCE_RAW.trim());
+ } finally {
+ editor.destroy();
+ container.remove();
+ }
+ });
+});
diff --git a/packages/app/src/editor/extensions/source-dirty-fold-atomicity.dom.test.tsx b/packages/app/src/editor/extensions/source-dirty-fold-atomicity.dom.test.tsx
new file mode 100644
index 000000000..bc2074ef5
--- /dev/null
+++ b/packages/app/src/editor/extensions/source-dirty-fold-atomicity.dom.test.tsx
@@ -0,0 +1,202 @@
+/**
+ * Fold-atomicity anti-race pin (Observer-A altitude, real-engine rung).
+ *
+ * A prior evaluation hypothesized a drain race: the interior content mutation
+ * and the sourceDirty flip could reach the bridge as two separate Y.Doc
+ * transactions, letting Observer A serialize a half-updated fragment between
+ * them — the first serialize firing while the component is still pristine
+ * (sourceDirty:false) would emit the stale verbatim sourceRaw, dropping the
+ * edit for every fresh parser until the second drain re-derived it.
+ *
+ * This pins why that race is unreachable. The source-dirty observer folds the
+ * flip into the SAME ProseMirror dispatch as the content edit (an
+ * appendTransaction, not a deferred one), so y-prosemirror's ySyncPlugin syncs
+ * both in ONE Y.Doc transaction, which settles as exactly ONE Observer-A
+ * serialize. The folded case drives a mounted editor bound through
+ * Collaboration (the production ySyncPlugin path) so the full
+ * dispatch -> ySyncPlugin -> Observer-A chain is exercised, not modelled.
+ *
+ * Observation is the precise Observer-A dispatch tally (`onDispatch('a')`), not
+ * bare PM-state counting — the tally is blind to nothing but the drains that
+ * are Observer-A serializes. The tally is validated against a deliberate
+ * two-transaction control on a plain doc: the SAME content edit and flip,
+ * applied as two Y.Doc transactions, fire two 'a' drains, proving the probe is
+ * not vacuously counting one.
+ *
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { sharedExtensions as coreExtensions, MarkdownManager } from '@inkeep/open-knowledge-core';
+import { type ObserverDispatchKind, setupServerObservers } from '@inkeep/open-knowledge-server';
+import { cleanup } from '@testing-library/react';
+import { Editor, getSchema, type JSONContent } from '@tiptap/core';
+import Collaboration from '@tiptap/extension-collaboration';
+import { updateYFragment } from '@tiptap/y-tiptap';
+import * as Y from 'yjs';
+import { sharedExtensions } from './shared';
+
+// Server-side bridge uses core's extensions (no React NodeViews) exactly like
+// production and the integration harness — the fragment is generic XML, so a
+// core-schema observer reads what an app-schema editor wrote.
+const coreMd = new MarkdownManager({ extensions: coreExtensions });
+const coreSchema = getSchema(coreExtensions);
+
+const CALLOUT_SOURCE_RAW = '<Callout title="A">\n\nA body\n\n</Callout>';
+
+/** Pristine (sourceDirty:false) Callout carrying authoritative sourceRaw + a
+ * paragraph child — the shape mdast->PM parse handlers emit. */
+function pristineCalloutJSON(bodyText: string): JSONContent {
+ return {
+ type: 'doc',
+ content: [
+ {
+ type: 'jsxComponent',
+ attrs: {
+ content: '',
+ componentName: 'Callout',
+ kind: 'element',
+ attributes: [],
+ sourceRaw: CALLOUT_SOURCE_RAW,
+ sourceDirty: false,
+ props: { title: 'A' },
+ },
+ content: [{ type: 'paragraph', content: [{ type: 'text', text: bodyText }] }],
+ },
+ ],
+ };
+}
+
+/** A doc + bridge observers + an Observer-A dispatch tally. The tally counts
+ * only 'a' drains (Observer A serializes the fragment into Y.Text); Observer
+ * A's own Y.Text write settles as a separate OBSERVER_SYNC_ORIGIN drain the
+ * dispatcher classifies 'none', so it never inflates the count. */
+function observedDoc() {
+ const doc = new Y.Doc();
+ const xmlFragment = doc.getXmlFragment('default');
+ const ytext = doc.getText('source');
+ const dispatches: ObserverDispatchKind[] = [];
+ const cleanupObservers = setupServerObservers({
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager: coreMd,
+ schema: coreSchema,
+ onDispatch: (kind) => dispatches.push(kind),
+ });
+ return {
+ doc,
+ xmlFragment,
+ ytext,
+ observerADrains: () => dispatches.filter((k) => k === 'a').length,
+ resetTally: () => {
+ dispatches.length = 0;
+ },
+ cleanupObservers,
+ };
+}
+
+/** Seed a fragment from a PM doc JSON in ONE transaction (the paired-write seed
+ * altitude — observers attach afterward against a settled baseline). */
+function seedFragment(doc: Y.Doc, xmlFragment: Y.XmlFragment, json: JSONContent): void {
+ const node = coreSchema.nodeFromJSON(json);
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, node, { mapping: new Map(), isOMark: new Map() });
+ });
+}
+
+/** First jsxComponent's interior text position + its dirty flag, read off a
+ * live editor state (mirrors the interior-content flip pin). */
+function calloutInterior(editor: Editor): { interiorTextPos: number; sourceDirty: boolean } {
+ let calloutPos = -1;
+ let interiorTextPos = -1;
+ let sourceDirty = false;
+ editor.state.doc.descendants((node, pos) => {
+ if (node.type.name === 'jsxComponent' && calloutPos === -1) {
+ calloutPos = pos;
+ sourceDirty = Boolean(node.attrs.sourceDirty);
+ return true;
+ }
+ if (calloutPos !== -1 && node.isText && interiorTextPos === -1) {
+ interiorTextPos = pos + 1;
+ return false;
+ }
+ return true;
+ });
+ if (interiorTextPos === -1) throw new Error('Callout interior text not found');
+ return { interiorTextPos, sourceDirty };
+}
+
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+describe('interior edit + sourceDirty flip fold into ONE Observer-A drain', () => {
+ afterEach(() => {
+ cleanup();
+ });
+
+ test('one interior edit through the real ySyncPlugin path settles as exactly ONE Observer-A serialize', async () => {
+ const { doc, xmlFragment, ytext, observerADrains, resetTally, cleanupObservers } =
+ observedDoc();
+ // Seed the pristine Callout, then attach the editor via Collaboration so
+ // ySyncPlugin owns the fragment (no `content` option — Collaboration is the
+ // source of truth). The tally starts after mount so init/prewarm drains
+ // don't contaminate it.
+ seedFragment(doc, xmlFragment, pristineCalloutJSON('A body'));
+
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ const editor = new Editor({
+ element: container,
+ extensions: [...sharedExtensions, Collaboration.configure({ document: doc })],
+ editable: true,
+ });
+
+ try {
+ await tick();
+ resetTally();
+
+ const before = calloutInterior(editor);
+ expect(before.sourceDirty).toBe(false); // pristine — the fold must do the flip
+
+ editor.commands.insertContentAt(before.interiorTextPos, 'ZZZ');
+ // A deferred (separate-dispatch) flip would surface as a SECOND 'a' drain
+ // after this tick; the fold keeps it to one.
+ await tick();
+
+ const after = calloutInterior(editor);
+ expect(after.sourceDirty).toBe(true); // content + flip landed together
+ expect(observerADrains()).toBe(1);
+ expect(ytext.toString()).toContain('ZZZ'); // the one serialize emitted fresh bytes
+ } finally {
+ editor.destroy();
+ container.remove();
+ cleanupObservers();
+ doc.destroy();
+ }
+ });
+
+ test('CONTROL: the same content edit + flip as two transactions fire TWO Observer-A drains', () => {
+ const { doc, xmlFragment, ytext, observerADrains, resetTally, cleanupObservers } =
+ observedDoc();
+ seedFragment(doc, xmlFragment, pristineCalloutJSON('A body'));
+ resetTally();
+
+ // Transaction 1 — the content edit alone (still sourceDirty:false). This is
+ // the half-updated state the fold makes unreachable: Observer A serializes
+ // the pristine-flagged component here, emitting the stale sourceRaw.
+ const editedNode = coreSchema.nodeFromJSON(pristineCalloutJSON('A bodyZZZ'));
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, editedNode, { mapping: new Map(), isOMark: new Map() });
+ });
+ expect(ytext.toString()).not.toContain('ZZZ'); // stale window: verbatim sourceRaw, no edit
+
+ // Transaction 2 — the flip, in its own transaction.
+ doc.transact(() => {
+ (xmlFragment.get(0) as Y.XmlElement).setAttribute('sourceDirty', 'true');
+ });
+
+ expect(observerADrains()).toBe(2); // two transactions => two 'a' drains (probe discriminates)
+ expect(ytext.toString()).toContain('ZZZ'); // second drain re-derived the fresh bytes
+
+ cleanupObservers();
+ doc.destroy();
+ });
+});
diff --git a/packages/app/src/editor/extensions/source-dirty-observer.origin-guard.test.ts b/packages/app/src/editor/extensions/source-dirty-observer.origin-guard.test.ts
index 38c16a3f3..a8139151f 100644
--- a/packages/app/src/editor/extensions/source-dirty-observer.origin-guard.test.ts
+++ b/packages/app/src/editor/extensions/source-dirty-observer.origin-guard.test.ts
@@ -131,6 +131,40 @@ function applyWithAppend(
return intermediate.apply(appended);
}
+/**
+ * Positions of every jsxComponent in the doc, in document order. Re-locating
+ * blocks after an edit shifts their positions lets an assertion on the
+ * untouched sibling read the right node instead of a stale offset.
+ */
+function componentPositions(state: EditorState): number[] {
+ const positions: number[] = [];
+ state.doc.descendants((node, p) => {
+ if (node.type.name === 'jsxComponent') positions.push(p);
+ });
+ return positions;
+}
+
+/**
+ * Apply an in-place text edit inside the first jsxComponent's paragraph child —
+ * the interior-content route, distinct from the prop-edit route the other cases
+ * drive via setNodeMarkup. `firstComponentPos + 2` is the start of the paragraph's
+ * inline content: +1 enters the jsxComponent, +1 enters the paragraph. Passing
+ * `syncMeta` stamps the transaction as CRDT-origin so the deny-list treats it as
+ * non-user-intent.
+ */
+function editInteriorText(
+ plugin: Plugin,
+ state: EditorState,
+ text: string,
+ syncMeta?: unknown,
+): EditorState {
+ const innerTextPos = firstComponentPos(state) + 2;
+ return applyWithAppend(plugin, state, (tr) => {
+ if (syncMeta !== undefined) tr.setMeta(ySyncPluginKey, syncMeta);
+ return tr.insertText(text, innerTextPos);
+ });
+}
+
describe('SourceDirtyObserver origin guard', () => {
test('user-intent prop edit marks only the mutated jsxComponent dirty', () => {
const plugin = getPlugin();
@@ -284,4 +318,64 @@ describe('SourceDirtyObserver origin guard', () => {
// content AND non-empty props.
expect(isDirty(next, insertPos)).toBe(false);
});
+
+ test('deny-list gates the interior-content route by origin, not by content', () => {
+ const plugin = getPlugin();
+
+ // User-intent interior text edit (no ySyncPluginKey meta): the deny-list's
+ // hasUserTransaction check must admit it, and the contentChanged branch must
+ // flip the edited component dirty while leaving the untouched sibling pristine.
+ {
+ const initial = buildInitialState(plugin);
+ const next = editInteriorText(plugin, initial, 'X');
+ const [firstPos, secondPos] = componentPositions(next);
+ expect(isDirty(next, firstPos)).toBe(true);
+ expect(isDirty(next, secondPos)).toBe(false);
+ }
+
+ // The SAME content mutation stamped CRDT-origin is suppressed by the deny-list.
+ // This control proves the flip above is the guard admitting a genuine user
+ // transaction, not interior edits flipping unconditionally.
+ {
+ const initial = buildInitialState(plugin);
+ const next = editInteriorText(plugin, initial, 'X', { isChangeOrigin: true });
+ const [firstPos] = componentPositions(next);
+ expect(isDirty(next, firstPos)).toBe(false);
+ }
+ });
+
+ test('freshly-inserted component stays pristine on insert, but its first interior edit flips', () => {
+ const plugin = getPlugin();
+ const initial = buildInitialState(plugin);
+ const insertPos = initial.doc.content.size;
+
+ // Insert a fresh registered component carrying an authoritative sourceRaw:
+ // the fresh-insert guard preserves it verbatim (pristine, not dirty).
+ const afterInsert = applyWithAppend(plugin, initial, (tr) => {
+ const node = schema.node(
+ 'jsxComponent',
+ {
+ content: '',
+ componentName: 'Callout',
+ kind: 'element',
+ attributes: [],
+ sourceRaw: '<Callout type="info">\n\nfresh\n\n</Callout>',
+ sourceDirty: false,
+ props: { type: 'info' },
+ },
+ [schema.node('paragraph', null, [schema.text('fresh')])],
+ );
+ return tr.insert(insertPos, node);
+ });
+ expect(isDirty(afterInsert, insertPos)).toBe(false);
+
+ // A genuine interior edit on the now-existing component: the fresh-insert
+ // guard is one-shot at insert time (oldNode is now a jsxComponent, so
+ // isFreshInsert is false), so the edit re-derives and must flip dirty. A
+ // guard keyed on sourceRaw alone would wrongly keep it pristine here.
+ const afterEdit = applyWithAppend(plugin, afterInsert, (tr) =>
+ tr.insertText('!', insertPos + 2),
+ );
+ expect(isDirty(afterEdit, insertPos)).toBe(true);
+ });
});
diff --git a/packages/app/src/editor/extensions/source-dirty-observer.test.ts b/packages/app/src/editor/extensions/source-dirty-serialize.test.ts
similarity index 93%
rename from packages/app/src/editor/extensions/source-dirty-observer.test.ts
rename to packages/app/src/editor/extensions/source-dirty-serialize.test.ts
index 13d99ec06..335cff09f 100644
--- a/packages/app/src/editor/extensions/source-dirty-observer.test.ts
+++ b/packages/app/src/editor/extensions/source-dirty-serialize.test.ts
@@ -1,19 +1,15 @@
/**
- * Source-dirty observer origin-guard tests.
+ * Source-dirty SERIALIZATION tests.
*
- * Tests the γ pattern's dirty-tracking correctness via the MarkdownManager
- * parse/serialize round-trip. Since the source-dirty observer is a PM plugin
- * that operates inside a TipTap editor instance, and testing full editor instances
- * is done in integration tests, these tests verify the serialization behavior
- * that the dirty flag controls:
+ * These pin the serialization behavior the `sourceDirty` flag controls, via
+ * the MarkdownManager parse/serialize round-trip — NOT the observer that sets
+ * the flag (that plugin's origin-guard truth table lives in
+ * source-dirty-observer.origin-guard.test.ts; a real-editor interior-edit pin
+ * lives in source-dirty-flip.dom.test.tsx):
*
* - Pristine (sourceDirty:false) → sourceRaw emitted (byte-identical)
* - Dirty (sourceDirty:true) → reconstruction path emitted
* - effectiveDirty (descendant dirty) → parent reconstructs
- *
- * The actual origin-guard behavior (which PM transactions mark dirty) is
- * tested in integration/bridge-matrix tests where real editor instances
- * exist.
*/
import { describe, expect, test } from 'bun:test';
import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
diff --git a/packages/app/tests/dom/jsx-interior-input-rule-suppression.dom.test.tsx b/packages/app/tests/dom/jsx-interior-input-rule-suppression.dom.test.tsx
new file mode 100644
index 000000000..7e5e2e73e
--- /dev/null
+++ b/packages/app/tests/dom/jsx-interior-input-rule-suppression.dom.test.tsx
@@ -0,0 +1,146 @@
+/**
+ * Markdown input-rule behavior at jsxComponent boundaries, on a real mounted
+ * editor. Two facts are pinned:
+ *
+ * 1. A markdown shortcut ("- ") typed inside a REGISTERED jsxComponent's
+ * editable interior fires its input rule and forms a list — interiors are
+ * ordinary editable ProseMirror content.
+ *
+ * 2. The same input rule cannot restructure a rawMdxFallback raw-source box.
+ *
+ * The suppression in (2) has two independent guards. In the running editor the
+ * box hosts a nested CodeMirror view whose NodeView swallows every DOM event,
+ * so a keystroke typed there never reaches ProseMirror's input pipeline — that
+ * capture depends on real focus and real key events and lives in the
+ * browser-tier suite. This test pins the SECOND guard, which holds even if a
+ * keystroke did reach the pipeline: a rawMdxFallback is `text*` content and
+ * `listItem` requires a paragraph as its first child, so `findWrapping` refuses
+ * to wrap the box. Injecting the rule directly at a raw-box caret is therefore
+ * inert and the raw source survives verbatim.
+ *
+ * The two assertions pin a genuine difference — rule active in an interior,
+ * inert in the box — not a constant: breaking the list input rule reddens (1);
+ * making `listItem` accept a non-paragraph first child reddens (2).
+ *
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { cleanup } from '@testing-library/react';
+import { Editor, type JSONContent } from '@tiptap/core';
+import type { Node as PMNode } from '@tiptap/pm/model';
+import type { EditorView } from '@tiptap/pm/view';
+import { sharedExtensions } from '../../src/editor/extensions/shared';
+
+type TextInputHandler = (view: EditorView, from: number, to: number, text: string) => boolean;
+
+function mountEditor(content: JSONContent): { editor: Editor; container: HTMLDivElement } {
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ const editor = new Editor({
+ element: container,
+ content,
+ extensions: sharedExtensions,
+ editable: true,
+ });
+ return { editor, container };
+}
+
+function teardown(editor: Editor, container: HTMLDivElement): void {
+ editor.destroy();
+ container.remove();
+}
+
+/** Locate the first node of a given type, with its absolute position. */
+function findNode(editor: Editor, typeName: string): { pos: number; node: PMNode } | null {
+ let found: { pos: number; node: PMNode } | null = null;
+ editor.state.doc.descendants((node, pos) => {
+ if (!found && node.type.name === typeName) found = { pos, node };
+ return !found;
+ });
+ return found;
+}
+
+/** Caret position immediately after the first text node in the document. */
+function caretAfterFirstText(editor: Editor): number {
+ let pos = -1;
+ editor.state.doc.descendants((node, at) => {
+ if (pos < 0 && node.isText) {
+ pos = at + node.nodeSize;
+ return false;
+ }
+ return pos < 0;
+ });
+ return pos;
+}
+
+/**
+ * Fire ProseMirror's input-rule pipeline the way the view fires it on real text
+ * input: it walks each plugin's `handleTextInput(view, from, to, text)` until one
+ * returns truthy. Passing the callback to `someProp` reproduces that walk (a bare
+ * `someProp('handleTextInput')` would stop at the first plugin's handler).
+ */
+function typeSpace(editor: Editor, at: number): boolean {
+ return (
+ editor.view.someProp('handleTextInput', (handler) =>
+ (handler as TextInputHandler)(editor.view, at, at, ' '),
+ ) ?? false
+ );
+}
+
+describe('Markdown input rules at jsxComponent boundaries', () => {
+ afterEach(() => cleanup());
+
+ test('a list input rule fires inside a registered jsxComponent interior', () => {
+ const content: JSONContent = {
+ type: 'doc',
+ content: [
+ {
+ type: 'jsxComponent',
+ attrs: { componentName: 'Callout', kind: 'element' },
+ content: [{ type: 'paragraph', content: [{ type: 'text', text: '-' }] }],
+ },
+ ],
+ };
+ const { editor, container } = mountEditor(content);
+ try {
+ const handled = typeSpace(editor, caretAfterFirstText(editor));
+ expect(handled).toBe(true);
+
+ // A list formed, and it formed INSIDE the Callout interior (not at doc root).
+ const callout = findNode(editor, 'jsxComponent');
+ expect(callout).not.toBeNull();
+ let listInsideCallout = false;
+ callout?.node.descendants((n) => {
+ if (n.type.name === 'list') listInsideCallout = true;
+ return !listInsideCallout;
+ });
+ expect(listInsideCallout).toBe(true);
+ } finally {
+ teardown(editor, container);
+ }
+ });
+
+ test('the same list input rule does not restructure a rawMdxFallback raw box', () => {
+ const content: JSONContent = {
+ type: 'doc',
+ content: [
+ {
+ type: 'rawMdxFallback',
+ attrs: { reason: 'unregistered-component' },
+ content: [{ type: 'text', text: '-' }],
+ },
+ ],
+ };
+ const { editor, container } = mountEditor(content);
+ try {
+ typeSpace(editor, caretAfterFirstText(editor));
+
+ // No list was produced anywhere, and the raw box kept its source verbatim.
+ expect(findNode(editor, 'list')).toBeNull();
+ const raw = findNode(editor, 'rawMdxFallback');
+ expect(raw).not.toBeNull();
+ expect(raw?.node.textContent).toBe('-');
+ } finally {
+ teardown(editor, container);
+ }
+ });
+});
diff --git a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
index bf6fa59ad..c18788593 100644
--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
@@ -22,16 +22,21 @@
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment } from '@tiptap/y-tiptap';
import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
import {
agentWriteMd,
+ assertAllConverged,
awaitDocQuiescence,
createTestClient,
+ createTestClients,
createTestServer,
getServerState,
mdManager,
+ pollDiskContentStable,
schema,
type TestClient,
type TestServer,
@@ -144,3 +149,478 @@ describe('bug #3 — source-mode write-back guard (re-indent facet closed by #19
}
});
});
+
+const FENCE = '`'.repeat(3);
+
+// A pristine seed lands, then a genuine WYSIWYG-side commit fires Observer A;
+// returns the RAW persisted Y.Text bytes for the tolerance-aware oracle.
+async function seedAndEdit(docName: string, seed: string, edited: string): Promise<string> {
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ const ytext = client.doc.getText('source');
+ await awaitDocQuiescence(client.doc);
+ expect(ytext.toString()).toBe(seed);
+ applyWysiwygEdit(client, edited);
+ await awaitDocQuiescence(client.doc);
+ return getServerState(server, docName)?.ytext.toString() ?? '';
+ } finally {
+ await client.cleanup();
+ }
+}
+
+describe('QA canary — Steps live-edit fidelity (Observer-A altitude)', () => {
+ /**
+ * Fence interiors are phrasing-gated OUT of boundary-whitespace encoding: a
+ * 4-space interior line must serialize verbatim (no `&#x20;`/`&#x9;` char-ref
+ * injection, no code-flip) even when the fence lives inside a <Step>.
+ *
+ */
+ test('fenced code block with 4-space interior inside a Step survives a WYSIWYG edit', async () => {
+ const seed = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ 'Intro one.',
+ '',
+ `${FENCE}js`,
+ 'const x = 1;',
+ ' deepIndented();',
+ FENCE,
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'Content two.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+ ].join('\n');
+ const edited = seed.replace('Content two.', 'Content two, edited.');
+ const after = await seedAndEdit(`canary-fence-${crypto.randomUUID()}`, seed, edited);
+
+ expect(after).toContain('Content two, edited.'); // non-vacuous: edit landed
+ expect(after).toContain('\n deepIndented();'); // 4-space interior preserved verbatim
+ expect(after).not.toContain('&#x20;deepIndented'); // no char-ref injection in fence
+ expect(after).not.toContain('&#x9;'); // no tab char-ref injection
+ expect(after).not.toMatch(INDENTED_STEP); // tags stay flush-left
+ expect(after).not.toMatch(INDENTED_STEPS);
+ expect((after.match(/```/g) ?? []).length).toBe(2); // exactly one fence pair (no dup)
+ });
+
+ /**
+ * `encodeAttentionBoundaries` wraps ~~/== so a boundary space can't drop the
+ * mark — strike and highlight inside a <Step> must survive the round-trip.
+ *
+ */
+ test('strike and highlight marks inside a Step are not silently dropped', async () => {
+ const seed = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ 'Plain intro.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'Has ~~struck~~ and ==marked== words.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+ ].join('\n');
+ const edited = seed.replace('Plain intro.', 'Plain intro, edited.');
+ const after = await seedAndEdit(`canary-marks-${crypto.randomUUID()}`, seed, edited);
+
+ expect(after).toContain('Plain intro, edited.'); // non-vacuous
+ expect(after).toContain('~~struck~~'); // strike mark survived round-trip
+ expect(after).toContain('==marked=='); // highlight mark survived round-trip
+ expect(after).not.toMatch(INDENTED_STEP);
+ });
+
+ /**
+ * List-marker indent is canonically normalized, so the oracle is tolerance-
+ * aware: assert no item LOSS or duplication and flush-left tags — never raw
+ * byte-identity of the list indentation.
+ *
+ */
+ test('ordered list inside a Step: no item loss or duplication, tags stay flush-left', async () => {
+ const seed = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ 'Do these:',
+ '',
+ '1. first',
+ '2. second',
+ '3. third',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'After.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+ ].join('\n');
+ const edited = seed.replace('After.', 'After, edited.');
+ const after = await seedAndEdit(`canary-list-${crypto.randomUUID()}`, seed, edited);
+
+ expect(after).toContain('After, edited.'); // non-vacuous
+ expect(after).toContain('first');
+ expect(after).toContain('second');
+ expect(after).toContain('third');
+ // no duplication: each item text appears exactly once
+ expect((after.match(/\bfirst\b/g) ?? []).length).toBe(1);
+ expect((after.match(/\bsecond\b/g) ?? []).length).toBe(1);
+ expect((after.match(/\bthird\b/g) ?? []).length).toBe(1);
+ expect(after).not.toMatch(INDENTED_STEP);
+ expect(after).not.toMatch(INDENTED_STEPS);
+ });
+
+ /**
+ * The canonical github-sync shape: 4 flush-left <Step> tags with 4-space-
+ * indented bodies. Edit one body via WYSIWYG; assert no tag re-indent, no
+ * growth, no duplicate <Steps>.
+ *
+ */
+ test('github-sync 4-Step shape (flush-left tags, indented bodies): edit one body, no corruption', async () => {
+ const seed = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ '### Connect',
+ '',
+ ' Link your repo to start syncing.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ '### Configure',
+ '',
+ ' Choose a branch and a folder.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ '### Sync',
+ '',
+ ' Changes flow both ways.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ '### Done',
+ '',
+ ' Your docs are live.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+ ].join('\n');
+ const edited = seed.replace(
+ 'Choose a branch and a folder.',
+ 'Choose a branch and a folder to sync.',
+ );
+ const before = mdManager.serialize(mdManager.parse(seed));
+ const after = await seedAndEdit(`canary-gh-${crypto.randomUUID()}`, before, edited);
+
+ expect(after).toContain('Choose a branch and a folder to sync.'); // non-vacuous
+ expect((after.match(/<Steps>/g) ?? []).length).toBe(1); // no duplicate container
+ expect((after.match(/<Step>/g) ?? []).length).toBe(4); // all four steps, once each
+ expect(after).not.toMatch(INDENTED_STEP); // tags not re-indented
+ // no runaway growth (duplication blows length up multiplicatively)
+ expect(after.length).toBeLessThan(before.length + 64);
+ });
+});
+
+describe('QA canary — cold-reopen / concurrent-peer / idempotence (Observer-A altitude)', () => {
+ /**
+ * TRUE cold reopen: edit fires Observer A, then read the PERSISTED DISK bytes
+ * (what a fresh reader/reopen parses) and confirm no corruption + disk==memory.
+ *
+ */
+ test('cold reopen: 4-Step github-sync shape edited via WYSIWYG, disk bytes uncorrupted + match memory', async () => {
+ const docName = `canary-cold-${crypto.randomUUID()}`;
+ const seed = mdManager.serialize(
+ mdManager.parse(
+ [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ '### Connect',
+ '',
+ 'Link your repo.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ '### Configure',
+ '',
+ 'Choose a branch.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ '### Sync',
+ '',
+ 'Changes flow both ways.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+ ].join('\n'),
+ ),
+ );
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ applyWysiwygEdit(client, seed.replace('Choose a branch.', 'Choose a branch and folder.'));
+ await awaitDocQuiescence(client.doc);
+
+ const diskPath = join(server.contentDir, `${docName}.md`);
+ const disk = await pollDiskContentStable(diskPath, (c) =>
+ c.includes('Choose a branch and folder.'),
+ );
+ const memory = getServerState(server, docName)?.ytext.toString() ?? '';
+
+ expect(disk).toContain('Choose a branch and folder.'); // edit persisted
+ expect(disk).not.toMatch(INDENTED_STEP); // tags not re-indented on disk
+ expect((disk.match(/<Steps>/g) ?? []).length).toBe(1);
+ expect((disk.match(/<Step>/g) ?? []).length).toBe(3);
+ expect(disk.length).toBeLessThan(seed.length + 64); // no runaway growth
+ expect(disk.trimEnd()).toBe(memory.trimEnd()); // disk == memory: no persist drift
+ } finally {
+ await client.cleanup();
+ }
+ });
+
+ /**
+ * Concurrent-peer convergence on a <Steps> doc: two clients type into
+ * different Steps; both edits survive, structure intact, no duplication.
+ *
+ */
+ test('concurrent peers typing into different Steps converge with both edits, no dup', async () => {
+ const docName = `canary-concurrent-${crypto.randomUUID()}`;
+ const seed = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ 'Content one.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'Content two.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+ ].join('\n');
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await wait(300);
+ const clients = await createTestClients(server.port, { count: 2, docName });
+ try {
+ await assertAllConverged(clients, { timeout: 5000 });
+ const a = clients[0].ytext;
+ const b = clients[1].ytext;
+ clients[0].doc.transact(() =>
+ a.insert(a.toString().indexOf('Content one.') + 'Content one'.length, ' (A)'),
+ );
+ clients[1].doc.transact(() =>
+ b.insert(b.toString().indexOf('Content two.') + 'Content two'.length, ' (B)'),
+ );
+ await assertAllConverged(clients, { timeout: 5000 });
+
+ const after = clients[0].ytext.toString();
+ expect(after).toContain('(A)');
+ expect(after).toContain('(B)');
+ expect((after.match(/<Step>/g) ?? []).length).toBe(2); // both steps, once each
+ expect((after.match(/Content one/g) ?? []).length).toBe(1);
+ expect((after.match(/Content two/g) ?? []).length).toBe(1);
+ expect(after).not.toMatch(INDENTED_STEP);
+ } finally {
+ await Promise.all(clients.map((c) => c.cleanup()));
+ }
+ });
+
+ /**
+ * Idempotence: a second identical-shape WYSIWYG drain produces no growth or
+ * drift beyond the first.
+ *
+ */
+ test('repeated identical WYSIWYG drain on a <Steps> doc is idempotent (no growth/drift)', async () => {
+ const docName = `canary-idem-${crypto.randomUUID()}`;
+ const seed = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ 'Alpha.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'Beta.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+ ].join('\n');
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ const edited = seed.replace('Alpha.', 'Alpha, edited.');
+ applyWysiwygEdit(client, edited);
+ await awaitDocQuiescence(client.doc);
+ const s1 = getServerState(server, docName)?.ytext.toString() ?? '';
+ applyWysiwygEdit(client, edited); // identical drain again
+ await awaitDocQuiescence(client.doc);
+ const s2 = getServerState(server, docName)?.ytext.toString() ?? '';
+
+ expect(s1).toContain('Alpha, edited.');
+ expect(s2).toBe(s1); // idempotent: no drift, no growth on repeated identical drain
+ expect((s2.match(/<Step>/g) ?? []).length).toBe(2);
+ } finally {
+ await client.cleanup();
+ }
+ });
+});
+
+// Real repo docs as fixtures (not reconstructions) — the highest-fidelity
+// canary: the exact files a user edits. Paths resolve from this test file up to
+// the OK root, then into docs/. Re-verify shape (docs evolve) as a fixture-drift
+// guard inside the load test.
+const OK_ROOT = join(import.meta.dirname, '..', '..', '..', '..');
+const GITHUB_SYNC = join(OK_ROOT, 'docs', 'content', 'features', 'github-sync.mdx');
+const QUICKSTART = join(OK_ROOT, 'docs', 'content', 'get-started', 'quickstart.mdx');
+
+describe('QA canary — real repo docs with <Steps>', () => {
+ /**
+ * The real github-sync.mdx loads byte-clean through the bridge, with a
+ * fixture-drift precondition (title / 4 flush-left <Step> / 4-space bodies)
+ * so a doc rewrite that changes the canonical shape reddens here.
+ *
+ */
+ test('github-sync.mdx loads byte-clean through the bridge (frontmatter + Callout + Steps intact)', async () => {
+ const md = readFileSync(GITHUB_SYNC, 'utf-8');
+ // Fixture-drift guard: the real doc must still carry the canonical shape.
+ expect(md).toContain('title: GitHub sync');
+ expect((md.match(/^<Step>$/gm) ?? []).length).toBe(4); // flush-left <Step> tags
+ expect(md).toMatch(/^<Steps>$/m);
+ expect(md).toMatch(/\n {4}### /); // 4-space-indented Step body headings
+ expect(md).not.toMatch(INDENTED_STEP); // tags flush-left at rest
+
+ const docName = `real-gh-load-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, md, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ const ytext = client.doc.getText('source').toString();
+ expect(ytext).toContain('title: GitHub sync'); // frontmatter survived
+ expect(ytext).toContain('<Callout type="warn">'); // sibling JSX survived
+ expect((ytext.match(/^<Step>$/gm) ?? []).length).toBe(4);
+ expect(ytext).not.toMatch(INDENTED_STEP); // tags not re-indented on load
+ expect(ytext).toMatch(/\n {4}### Open the clone dialog/); // body indent preserved
+ // bridge fixed point: re-serializing the parsed source drifts nothing beyond tolerance
+ expect(mdManager.serialize(mdManager.parse(ytext))).toBe(
+ mdManager.serialize(mdManager.parse(md)),
+ );
+ } finally {
+ await client.cleanup();
+ }
+ });
+
+ /**
+ * Live source keystroke inside a real Step fires no Observer-A re-indent, and
+ * the persisted disk bytes a fresh reopen parses stay clean (disk == memory).
+ *
+ */
+ test('live source edit inside a real Step fires no Observer-A re-indent; disk cold-reopen clean', async () => {
+ const md = readFileSync(GITHUB_SYNC, 'utf-8');
+ const docName = `real-gh-edit-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, md, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ const ytext = client.doc.getText('source');
+ await awaitDocQuiescence(client.doc);
+ const anchor = 'Paste a repository URL';
+ const at = ytext.toString().indexOf(anchor) + anchor.length;
+ expect(at).toBeGreaterThan(anchor.length); // anchor exists in the real doc
+ client.doc.transact(() => ytext.insert(at, ' (edited)'));
+ await awaitDocQuiescence(client.doc);
+
+ const memory = getServerState(server, docName)?.ytext.toString() ?? '';
+ expect(memory).toContain('Paste a repository URL (edited)'); // edit landed
+ expect(memory).not.toMatch(INDENTED_STEP); // NO re-indent write-back
+ expect((memory.match(/^<Step>$/gm) ?? []).length).toBe(4);
+ expect(memory).toContain('title: GitHub sync'); // frontmatter untouched
+ expect(memory.length).toBeLessThan(md.length + 32); // no growth
+
+ const disk = await pollDiskContentStable(join(server.contentDir, `${docName}.md`), (c) =>
+ c.includes('Paste a repository URL (edited)'),
+ );
+ expect(disk).not.toMatch(INDENTED_STEP);
+ expect((disk.match(/^<Step>$/gm) ?? []).length).toBe(4);
+ expect(disk.trimEnd()).toBe(memory.trimEnd()); // disk == memory: no persist drift
+ } finally {
+ await client.cleanup();
+ }
+ });
+
+ /**
+ * A real mixed Steps + Tabs doc (quickstart.mdx) loads byte-clean and is a
+ * bridge fixed point.
+ *
+ */
+ test('quickstart.mdx (Steps + Tabs) loads byte-clean through the bridge', async () => {
+ const md = readFileSync(QUICKSTART, 'utf-8');
+ const docName = `real-qs-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, md, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ const ytext = client.doc.getText('source').toString();
+ expect(ytext).toMatch(/^<Steps>$/m);
+ expect(ytext).not.toMatch(INDENTED_STEP);
+ expect(mdManager.serialize(mdManager.parse(ytext))).toBe(
+ mdManager.serialize(mdManager.parse(md)),
+ );
+ } finally {
+ await client.cleanup();
+ }
+ });
+});
diff --git a/packages/app/tests/integration/c15-dual-embed-divergence.test.ts b/packages/app/tests/integration/c15-dual-embed-divergence.test.ts
index 394a10ff1..e5cc5d3a0 100644
--- a/packages/app/tests/integration/c15-dual-embed-divergence.test.ts
+++ b/packages/app/tests/integration/c15-dual-embed-divergence.test.ts
@@ -23,6 +23,7 @@ import * as Y from 'yjs';
import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
import {
agentWriteMd,
+ assertAllConverged,
assertBridgeInvariant,
createTestClients,
createTestServer,
@@ -166,3 +167,58 @@ describe('C15: dual html-preview embeds under divergence', () => {
}
}, 30_000);
});
+
+const FENCE = '`'.repeat(3);
+
+describe('QA canary — html-preview <script> embed under concurrent source edits', () => {
+ /**
+ * A single large html-preview embed with a <script> body; two peers edit
+ * distinct prose regions concurrently. The embed must survive as exactly one
+ * copy — no triplication, no astral-brace injection into the script head.
+ *
+ */
+ test('concurrent edits around an html-preview <script> embed do not duplicate or brace-inject', async () => {
+ const docName = `canary-embed-${crypto.randomUUID()}`;
+ const seed = [
+ '# Demo',
+ '',
+ 'Para A.',
+ '',
+ 'Para B.',
+ '',
+ `${FENCE}html`,
+ '<div id="app"></div>',
+ '<script>',
+ 'const greeting = "hello world";',
+ 'document.getElementById("app").textContent = greeting;',
+ '</script>',
+ FENCE,
+ '',
+ ].join('\n');
+ await agentWriteMd(server.port, seed, { docName, position: 'replace' });
+ await wait(300);
+ const clients = await createTestClients(server.port, { count: 2, docName });
+ try {
+ await assertAllConverged(clients, { timeout: 5000 });
+ // Concurrent source-side edits in distinct prose regions (W2 path per peer).
+ const a = clients[0].ytext;
+ const b = clients[1].ytext;
+ const ia = a.toString().indexOf('Para A.') + 'Para A.'.length;
+ clients[0].doc.transact(() => a.insert(ia, ' edit-A'));
+ const ib = b.toString().indexOf('Para B.') + 'Para B.'.length;
+ clients[1].doc.transact(() => b.insert(ib, ' edit-B'));
+ await assertAllConverged(clients, { timeout: 5000 });
+
+ const after = clients[0].ytext.toString();
+ expect(after).toContain('edit-A');
+ expect(after).toContain('edit-B');
+ expect((after.match(/<script>/g) ?? []).length).toBe(1); // no triplication
+ expect((after.match(/const greeting/g) ?? []).length).toBe(1);
+ expect(after).not.toContain('{onst'); // no astral-brace injection
+ expect(after).not.toContain('{ons{');
+ expect(after.length).toBeLessThan(seed.length + 64); // no growth blow-up
+ } finally {
+ await Promise.all(clients.map((c) => c.cleanup()));
+ }
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/interior-edit-freshness.test.ts b/packages/app/tests/integration/interior-edit-freshness.test.ts
new file mode 100644
index 000000000..74ff661c4
--- /dev/null
+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts
@@ -0,0 +1,167 @@
+/**
+ * Interior-edit freshness through the real Observer-A drain.
+ *
+ * A registered PM-editable component (Callout) serializes via its pristine
+ * `sourceRaw` byte cache while `sourceDirty` is false; an interior edit inside
+ * its NodeViewContent flips `sourceDirty` so the serializer IGNORES the now-stale
+ * `sourceRaw` and re-derives from the edited children. This drives that wire
+ * state (interior text mutated + the enclosing Callout's `sourceDirty` flipped,
+ * `sourceRaw` deliberately left stale) through a REAL Hocuspocus server and reads
+ * the persisted `Y.Text('source')` bytes at the Observer-A altitude — the same
+ * bytes a reopen or a teammate receives.
+ *
+ * The freshness is non-vacuous by construction: `sourceRaw` still holds the
+ * pre-edit source, so bytes carrying the edit can only have come from
+ * re-derivation. The second case drops the client flip entirely: the
+ * server-side structural-freshness derivation detects that the children no
+ * longer match the stale `sourceRaw` and re-derives anyway — the producer-side
+ * backstop for the exact stale-bytes corruption a deny-listed (non-user)
+ * transform would otherwise emit, regardless of whether the client flip fired.
+ *
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { setTimeout as wait } from 'node:timers/promises';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentWriteMd,
+ awaitDocQuiescence,
+ createTestClient,
+ createTestServer,
+ getServerState,
+ schema,
+ type TestClient,
+ type TestServer,
+} from './test-harness';
+
+// A registered Callout whose interior is a real paragraph (the NodeViewContent
+// hole an author types into). Blank-line delimited so it lifts to a jsxComponent.
+const SEED = ['<Callout type="info">', '', 'Original interior body.', '', '</Callout>', ''].join(
+ '\n',
+);
+
+type PmNodeJson = {
+ type?: string;
+ text?: string;
+ attrs?: Record<string, unknown>;
+ content?: PmNodeJson[];
+ marks?: unknown[];
+};
+
+/** The doc tree currently in a client's XmlFragment (synced from the server). */
+function currentTree(client: TestClient): PmNodeJson {
+ return yXmlFragmentToProseMirrorRootNode(client.fragment, schema).toJSON() as PmNodeJson;
+}
+
+/**
+ * Reproduce a WYSIWYG interior edit as its settled wire state: rewrite the
+ * interior text, and (when `flipDirty`) mark the enclosing Callout dirty exactly
+ * as the client SourceDirtyObserver would. `sourceRaw` is never touched, so a
+ * dirty Callout carries a genuinely stale byte cache.
+ */
+function planInteriorEdit(
+ tree: PmNodeJson,
+ find: string,
+ replace: string,
+ flipDirty: boolean,
+): PmNodeJson {
+ const next = structuredClone(tree);
+ const walk = (node: PmNodeJson): void => {
+ if (flipDirty && node.type === 'jsxComponent' && node.attrs?.componentName === 'Callout') {
+ node.attrs = { ...node.attrs, sourceDirty: true };
+ }
+ if (typeof node.text === 'string' && node.text.includes(find)) {
+ node.text = node.text.replace(find, replace);
+ }
+ node.content?.forEach(walk);
+ };
+ walk(next);
+ return next;
+}
+
+/** Commit a target doc tree into the client fragment with null origin — the same
+ * channel a local WYSIWYG mutation publishes through (Observer A sees a real
+ * fragment change, xmlDirty=true). */
+function commitFragment(client: TestClient, tree: PmNodeJson): void {
+ const pmNode = schema.nodeFromJSON(tree);
+ client.doc.transact(() => {
+ updateYFragment(client.doc, client.fragment, pmNode, {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ });
+}
+
+const INDENTED_CALLOUT = /\n[ \t]+<\/?Callout\b/; // a <Callout>/</Callout> tag gaining leading indent
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+describe('interior-edit freshness — Observer-A drain re-derives a dirty registered component', () => {
+ test('an interior edit reaches the persisted Y.Text bytes via re-derivation', async () => {
+ const docName = `interior-edit-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, SEED, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ const seeded = client.doc.getText('source').toString();
+ // Non-vacuity floor: the edit marker is genuinely absent before the edit.
+ expect(seeded).toContain('Original interior body');
+ expect(seeded).not.toContain('EDITED');
+
+ commitFragment(client, planInteriorEdit(currentTree(client), 'Original', 'EDITED', true));
+ await awaitDocQuiescence(client.doc);
+
+ const after = getServerState(server, docName)?.ytext.toString() ?? '';
+ // The edit reached the persisted bytes a reopen or teammate receives.
+ expect(after).toContain('EDITED interior body');
+ // No re-indent, no growth, no duplication of the container tags.
+ expect(after).not.toMatch(INDENTED_CALLOUT);
+ expect(after).not.toMatch(/^[ \t]+<Callout\b/m);
+ expect(after.match(/<Callout\b/g)).toHaveLength(1);
+ expect(after.match(/<\/Callout>/g)).toHaveLength(1);
+ // The registered component's props survived the re-derivation.
+ expect(after).toContain('type="info"');
+ } finally {
+ await client.cleanup();
+ }
+ });
+
+ test('without the client flip, the server structural-freshness derivation re-derives fresh bytes', async () => {
+ const docName = `interior-edit-noflip-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, SEED, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ expect(client.doc.getText('source').toString()).toContain('Original interior body');
+
+ // The children move but the Callout is left flagged pristine (sourceDirty
+ // stays false) — the deny-listed-origin divergence the client flip misses.
+ commitFragment(client, planInteriorEdit(currentTree(client), 'Original', 'EDITED', false));
+ await awaitDocQuiescence(client.doc);
+
+ const after = getServerState(server, docName)?.ytext.toString() ?? '';
+ // The server derivation caught children ≠ parse(sourceRaw) and re-derived,
+ // so the fresh bytes reach persistence even with no client flip — the
+ // stale-bytes class is structurally eliminated, not merely detected.
+ expect(after).toContain('EDITED interior body');
+ expect(after).not.toContain('Original interior body');
+ // Still fresh through re-derivation, not a mangled container.
+ expect(after).not.toMatch(INDENTED_CALLOUT);
+ expect(after.match(/<Callout\b/g)).toHaveLength(1);
+ expect(after).toContain('type="info"');
+ } finally {
+ await client.cleanup();
+ }
+ });
+});
diff --git a/packages/app/tests/integration/jsx-interior-paste.test.ts b/packages/app/tests/integration/jsx-interior-paste.test.ts
new file mode 100644
index 000000000..67c4f0e97
--- /dev/null
+++ b/packages/app/tests/integration/jsx-interior-paste.test.ts
@@ -0,0 +1,187 @@
+/**
+ * WYSIWYG paste INTO a jsxComponent interior — registered + unregistered.
+ *
+ * The unit tests in `handle-paste.test.ts` and the reorder tests in
+ * `clipboard-dispatcher-reorder.test.ts` drive the dispatcher against a fake
+ * view whose `tr.replaceSelection` only CAPTURES the produced slice — the
+ * caret always sits at the doc body and the slice is never fitted against a
+ * real document. They confirm which branch fired and what slice shape it
+ * produced, but structurally cannot observe how that slice lands when the
+ * caret is inside an isolating `jsxComponent` content hole.
+ *
+ * This file closes that gap: it seeds a real EditorState from parsed markdown,
+ * places a collapsed caret inside the interior of a registered (`Callout`) and
+ * an unregistered (`Steps`) component, then runs the REAL dispatcher against a
+ * view backed by that real state — so `replaceSelection` performs real PM
+ * slice-fitting across the isolating boundary. The assertion is on the
+ * resulting document: the pasted block nests as a child of the component
+ * interior, the component container survives with its identity, and the
+ * pre-existing interior content is preserved.
+ *
+ * Registered and unregistered components are the same `jsxComponent` node at
+ * the schema level (isolating, `block*`) — the interior-fit path is identical,
+ * which is why both are exercised over the same three payloads.
+ *
+ * No DOM: the dispatcher only touches `view.state` and `view.dispatch`, so a
+ * plain object wrapping a real EditorState reaches the production code path
+ * without a TipTap EditorView (same constraint the selection-state harness
+ * works around).
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { EditorState, TextSelection, type Transaction } from '@tiptap/pm/state';
+import { mdManager, schema } from './test-harness';
+
+// paste-failure-toast pulls in sonner; stub it so module load + any
+// degradation path is inert in the node test runtime.
+mock.module('sonner', () => ({ toast: { error: mock(() => {}) } }));
+
+// Imported after the sonner mock so the dispatcher's transitive sonner import
+// resolves to the stub.
+let createHandlePaste: typeof import('../../src/editor/clipboard/handle-paste.ts').createHandlePaste;
+beforeEach(async () => {
+ ({ createHandlePaste } = await import('../../src/editor/clipboard/handle-paste.ts'));
+});
+
+let origWarn: typeof console.warn;
+beforeEach(() => {
+ origWarn = console.warn;
+ console.warn = () => {};
+});
+afterEach(() => {
+ console.warn = origWarn;
+});
+
+function fakeDT(data: Record<string, string>): ClipboardEvent {
+ return {
+ clipboardData: { types: Object.keys(data), getData: (k: string) => data[k] ?? '' },
+ } as unknown as ClipboardEvent;
+}
+
+/** A view whose state is a real EditorState — dispatch applies for real, so
+ * `tr.replaceSelection` runs PM's actual slice-fitting against the doc. */
+function realStateView(initial: EditorState) {
+ let state = initial;
+ return {
+ get state() {
+ return state;
+ },
+ dispatch(tr: Transaction) {
+ state = state.apply(tr);
+ },
+ current: () => state,
+ };
+}
+
+/** Seed a doc from markdown and return a state whose collapsed caret sits at
+ * the first text position inside the first jsxComponent's interior. */
+function seedWithInteriorCaret(md: string): EditorState {
+ const doc = schema.nodeFromJSON(mdManager.parse(md));
+ const base = EditorState.create({ doc, schema });
+ let jsxPos = -1;
+ base.doc.descendants((node, pos) => {
+ if (jsxPos === -1 && node.type.name === 'jsxComponent') {
+ jsxPos = pos;
+ return false;
+ }
+ return true;
+ });
+ expect(jsxPos).toBeGreaterThanOrEqual(0);
+ // jsxPos = component open; +1 enters the interior; +2 lands inside the first
+ // interior paragraph's text (mirrors selection-state.test.ts T4).
+ const interiorCaret = jsxPos + 2;
+ return base.apply(base.tr.setSelection(TextSelection.create(base.doc, interiorCaret)));
+}
+
+const REGISTERED_SEED = '<Callout type="info">\n\nbody\n\n</Callout>\n';
+const UNREGISTERED_SEED = '<Steps>\n\nbody\n\n</Steps>\n';
+const SEEDS: ReadonlyArray<{ label: string; md: string; name: string }> = [
+ { label: 'registered Callout', md: REGISTERED_SEED, name: 'Callout' },
+ { label: 'unregistered Steps', md: UNREGISTERED_SEED, name: 'Steps' },
+];
+
+/** Run the dispatcher into an interior caret and return the container
+ * jsxComponent from the resulting doc (asserting the isolating boundary was
+ * preserved — the paste nested INTO the component, not beside it). */
+function pasteIntoInterior(seedMd: string, expectedName: string, dt: ClipboardEvent) {
+ const paste = createHandlePaste({ mdManager });
+ const view = realStateView(seedWithInteriorCaret(seedMd));
+ const handled = paste(view as never, dt);
+ const doc = view.current().doc;
+ expect(handled).toBe(true);
+ // Container survived as the sole top-level node with its identity intact —
+ // the pasted slice did not split or escape the isolating component.
+ expect(doc.childCount).toBe(1);
+ const container = doc.firstChild;
+ expect(container?.type.name).toBe('jsxComponent');
+ expect(container?.attrs.componentName).toBe(expectedName);
+ return container as NonNullable<typeof container>;
+}
+
+/** Component-interior children by node-type name (direct children only). */
+function interiorChildTypes(container: ReturnType<typeof pasteIntoInterior>): string[] {
+ const types: string[] = [];
+ container.forEach((child) => {
+ types.push(child.type.name);
+ });
+ return types;
+}
+
+describe('WYSIWYG paste into a jsxComponent interior', () => {
+ test('markdown pastes as nested blocks inside registered + unregistered interiors', () => {
+ for (const seed of SEEDS) {
+ const container = pasteIntoInterior(
+ seed.md,
+ seed.name,
+ fakeDT({ 'text/plain': '## Head\n\n- one\n- two\n' }),
+ );
+ const childTypes = interiorChildTypes(container);
+ // Pasted heading + list nested as the interior's leading blocks.
+ expect(childTypes[0]).toBe('heading');
+ expect(childTypes).toContain('list');
+ const heading = container.child(0);
+ expect(heading.textContent).toBe('Head');
+ // Pre-existing interior body preserved as the trailing block.
+ expect(container.lastChild?.type.name).toBe('paragraph');
+ expect(container.lastChild?.textContent).toBe('body');
+ }
+ });
+
+ test('an HTML table pastes as a nested table inside registered + unregistered interiors', () => {
+ for (const seed of SEEDS) {
+ const container = pasteIntoInterior(
+ seed.md,
+ seed.name,
+ fakeDT({
+ 'text/plain': 'a\tb\nc\td',
+ 'text/html': '<table><tr><th>a</th><th>b</th></tr><tr><td>c</td><td>d</td></tr></table>',
+ }),
+ );
+ const childTypes = interiorChildTypes(container);
+ // Table nested as a direct interior child (not escaped to doc root).
+ expect(childTypes[0]).toBe('table');
+ expect(container.child(0).childCount).toBeGreaterThan(0); // rows present
+ // Pre-existing interior body preserved.
+ expect(container.lastChild?.type.name).toBe('paragraph');
+ expect(container.lastChild?.textContent).toBe('body');
+ }
+ });
+
+ test('a nested JSX block pastes as a nested jsxComponent inside registered + unregistered interiors', () => {
+ for (const seed of SEEDS) {
+ const container = pasteIntoInterior(
+ seed.md,
+ seed.name,
+ fakeDT({ 'text/plain': '<Callout type="note">\n\nnested body\n\n</Callout>\n' }),
+ );
+ const childTypes = interiorChildTypes(container);
+ // Nested component landed as a child jsxComponent, distinct identity.
+ expect(childTypes[0]).toBe('jsxComponent');
+ expect(container.child(0).attrs.componentName).toBe('Callout');
+ expect(container.child(0).textContent).toBe('nested body');
+ // Pre-existing interior body preserved.
+ expect(container.lastChild?.type.name).toBe('paragraph');
+ expect(container.lastChild?.textContent).toBe('body');
+ }
+ });
+});
diff --git a/packages/app/tests/integration/jsx-isolating-join.test.ts b/packages/app/tests/integration/jsx-isolating-join.test.ts
new file mode 100644
index 000000000..8da10bb74
--- /dev/null
+++ b/packages/app/tests/integration/jsx-isolating-join.test.ts
@@ -0,0 +1,145 @@
+/**
+ * Isolating-join Backspace/Delete contract at the jsxComponent boundary.
+ *
+ * `jsx-component.test.ts` pins the schema flag `isolating: true` statically.
+ * This file pins the BEHAVIOR that flag governs: the ProseMirror join commands
+ * the base keymap binds to Backspace/Delete must NOT merge content across the
+ * isolating boundary — so a keystroke at the edge of the component can never
+ * fold the neighbouring block into (or out of) the component's content hole.
+ *
+ * Exercised for a registered (`Callout`) AND an unregistered (`Steps`)
+ * component: both are the same `jsxComponent` node at the schema level, so the
+ * join decision is name-independent — the unregistered arm has no coverage
+ * today.
+ *
+ * Command-rung, not a real browser: `joinBackward` / `joinForward` read only
+ * `state.selection` + the doc, so a plain `EditorState` plus a capturing
+ * dispatch drives the exact code path the keymap runs. A jsdom native
+ * Backspace can't reach this decision — with no layout, PM's `endOfTextblock`
+ * probe can't confirm the caret is at the block edge, so the join is never
+ * attempted and the boundary looks inert for the wrong reason. Invoking the
+ * command directly removes that confound.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+ joinBackward,
+ joinForward,
+ selectNodeBackward,
+ selectNodeForward,
+} from '@tiptap/pm/commands';
+import { EditorState, NodeSelection, TextSelection } from '@tiptap/pm/state';
+import { mdManager, schema } from './test-harness';
+
+type PmCommand = (state: EditorState, dispatch?: (tr: EditorState['tr']) => void) => boolean;
+
+function seedDoc(md: string): EditorState {
+ const doc = schema.nodeFromJSON(mdManager.parse(md));
+ return EditorState.create({ doc, schema });
+}
+
+/** Position + node of the first jsxComponent in the doc. */
+function findJsx(state: EditorState): { pos: number; nodeSize: number } {
+ let pos = -1;
+ let nodeSize = 0;
+ state.doc.descendants((node, p) => {
+ if (pos === -1 && node.type.name === 'jsxComponent') {
+ pos = p;
+ nodeSize = node.nodeSize;
+ return false;
+ }
+ return true;
+ });
+ expect(pos).toBeGreaterThanOrEqual(0);
+ return { pos, nodeSize };
+}
+
+/** Collapsed caret at the START of the block that follows the jsxComponent —
+ * the "just after the node" position Backspace acts from. */
+function caretAfterNode(state: EditorState): EditorState {
+ const { pos, nodeSize } = findJsx(state);
+ const caret = pos + nodeSize + 1; // +nodeSize → following block open; +1 → its offset 0
+ const $caret = state.doc.resolve(caret);
+ expect($caret.parent.isTextblock).toBe(true);
+ expect($caret.parentOffset).toBe(0); // at the block's leading edge
+ return state.apply(state.tr.setSelection(TextSelection.create(state.doc, caret)));
+}
+
+/** Collapsed caret at the END of the block that precedes the jsxComponent —
+ * the "just before the node" position Delete acts from. */
+function caretBeforeNode(state: EditorState): EditorState {
+ const { pos } = findJsx(state);
+ const caret = pos - 1; // one inside the preceding block, at its trailing edge
+ const $caret = state.doc.resolve(caret);
+ expect($caret.parent.isTextblock).toBe(true);
+ expect($caret.parentOffset).toBe($caret.parent.content.size); // at the block's trailing edge
+ return state.apply(state.tr.setSelection(TextSelection.create(state.doc, caret)));
+}
+
+/** Run a PM command with a capturing dispatch; report result + whether it
+ * produced a transaction + the resulting state. */
+function run(state: EditorState, cmd: PmCommand) {
+ let dispatched = false;
+ let next = state;
+ const result = cmd(state, (tr) => {
+ dispatched = true;
+ next = state.apply(tr);
+ });
+ return { result, dispatched, next };
+}
+
+const SEEDS: ReadonlyArray<{ label: string; name: string; backward: string; forward: string }> = [
+ {
+ label: 'registered Callout',
+ name: 'Callout',
+ backward: '<Callout type="info">\n\nbody\n\n</Callout>\n\nafter\n',
+ forward: 'before\n\n<Callout type="info">\n\nbody\n\n</Callout>\n',
+ },
+ {
+ label: 'unregistered Steps',
+ name: 'Steps',
+ backward: '<Steps>\n\nbody\n\n</Steps>\n\nafter\n',
+ forward: 'before\n\n<Steps>\n\nbody\n\n</Steps>\n',
+ },
+];
+
+describe('isolating-join contract at the jsxComponent boundary', () => {
+ for (const seed of SEEDS) {
+ test(`joinBackward is a no-op just after a ${seed.label}`, () => {
+ const state = caretAfterNode(seedDoc(seed.backward));
+ const { result, dispatched } = run(state, joinBackward);
+ // The isolating boundary refuses the join: no merge, no transaction.
+ expect(result).toBe(false);
+ expect(dispatched).toBe(false);
+ });
+
+ test(`joinForward is a no-op just before a ${seed.label}`, () => {
+ const state = caretBeforeNode(seedDoc(seed.forward));
+ const { result, dispatched } = run(state, joinForward);
+ expect(result).toBe(false);
+ expect(dispatched).toBe(false);
+ });
+
+ /**
+ * Characterization of the full Backspace/Delete chain fallback: after the
+ * join refuses, the base keymap tries selectNode*, which SELECTS the whole
+ * component (a non-destructive block NodeSelection) rather than merging
+ * across the boundary. Pinned so a regression that turned this into a
+ * content-merging join would be caught here too.
+ *
+ */
+ test(`Backspace/Delete chain selects (never joins) a ${seed.label} at its edges`, () => {
+ const backward = run(caretAfterNode(seedDoc(seed.backward)), selectNodeBackward);
+ expect(backward.result).toBe(true);
+ expect(backward.next.selection).toBeInstanceOf(NodeSelection);
+ expect((backward.next.selection as NodeSelection).node.type.name).toBe('jsxComponent');
+ expect((backward.next.selection as NodeSelection).node.attrs.componentName).toBe(seed.name);
+
+ const forward = run(caretBeforeNode(seedDoc(seed.forward)), selectNodeForward);
+ expect(forward.result).toBe(true);
+ expect(forward.next.selection).toBeInstanceOf(NodeSelection);
+ expect((forward.next.selection as NodeSelection).node.type.name).toBe('jsxComponent');
+ expect((forward.next.selection as NodeSelection).node.attrs.componentName).toBe(seed.name);
+ });
+ }
+});
diff --git a/packages/app/tests/integration/jsx-unregistered-cell-flatten-loss.test.ts b/packages/app/tests/integration/jsx-unregistered-cell-flatten-loss.test.ts
new file mode 100644
index 000000000..70aed9bb8
--- /dev/null
+++ b/packages/app/tests/integration/jsx-unregistered-cell-flatten-loss.test.ts
@@ -0,0 +1,205 @@
+/**
+ * Unregistered component in a table cell — the confirmed-lossy serialize path.
+ *
+ * A table cell's PM schema is `block+` and a jsxComponent is `group: block`, so
+ * an unregistered component is schema-valid inside a cell and reaches one through
+ * the ordinary WYSIWYG paste route with no insert-time guard. But a GFM cell is
+ * phrasing-only on one physical line, so the PM→markdown serializer flattens a
+ * cell's block content (`flattenCellBlocks`, packages/core/src/markdown/
+ * table-cell-flatten.ts). A jsxComponent's mdast form is an `mdxJsxFlowElement`
+ * whose name, props, and source spelling live outside the `children`/`value`
+ * the flattener can project, so a component in a cell is dropped whole and only
+ * a `table-cell-flatten-dropped-block` diagnostic marks the loss.
+ *
+ * These tests PIN that current lossy behavior end to end — real paste dispatcher
+ * places the component, real serializer drops it. This is a characterization of
+ * reality, not a target. The loss is component-general (a registered component
+ * flattens the same way); the unregistered slice is pinned here. Preserving a
+ * component's source spelling in a cell instead of dropping it is a
+ * serialize-time product decision; if that fix lands these expectations flip and
+ * must be updated.
+ *
+ * No DOM: the dispatcher only touches `view.state`/`view.dispatch`, so a plain
+ * object over a real EditorState reaches the production paste path.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import type { Node as PmNode } from '@tiptap/pm/model';
+import { EditorState, TextSelection, type Transaction } from '@tiptap/pm/state';
+import { mdManager, schema } from './test-harness';
+
+// paste-failure-toast pulls in sonner; stub it so module load stays inert.
+mock.module('sonner', () => ({ toast: { error: mock(() => {}) } }));
+
+let createHandlePaste: typeof import('../../src/editor/clipboard/handle-paste.ts').createHandlePaste;
+beforeEach(async () => {
+ ({ createHandlePaste } = await import('../../src/editor/clipboard/handle-paste.ts'));
+});
+
+/** The structured diagnostic `flattenCellBlocks` emits for a content-losing drop. */
+const DROP_EVENT = 'table-cell-flatten-dropped-block';
+
+/** A 2x2 GFM table; the caret seeds into the first data cell (text "c"). */
+const TABLE_MD = '| a | b |\n| - | - |\n| c | d |\n';
+
+function fakeDT(data: Record<string, string>): ClipboardEvent {
+ return {
+ clipboardData: { types: Object.keys(data), getData: (k: string) => data[k] ?? '' },
+ } as unknown as ClipboardEvent;
+}
+
+/** A view whose state is a real EditorState — dispatch applies for real, so the
+ * paste's `replaceSelection` runs PM's actual slice-fitting into the cell. */
+function realStateView(initial: EditorState) {
+ let state = initial;
+ return {
+ get state() {
+ return state;
+ },
+ dispatch(tr: Transaction) {
+ state = state.apply(tr);
+ },
+ current: () => state,
+ };
+}
+
+/** Seed the table doc with a collapsed caret inside the first data cell's text. */
+function seedWithCellCaret(): EditorState {
+ const doc = schema.nodeFromJSON(mdManager.parse(TABLE_MD));
+ const base = EditorState.create({ doc, schema });
+ let cellPos = -1;
+ base.doc.descendants((node, pos) => {
+ if (cellPos === -1 && node.type.name === 'tableCell') {
+ cellPos = pos;
+ return false;
+ }
+ return true;
+ });
+ expect(cellPos).toBeGreaterThanOrEqual(0);
+ // cellPos = cell open; +1 enters the cell paragraph; +2 lands in its text.
+ const caret = cellPos + 2;
+ expect(base.doc.resolve(caret).parent.type.name).toBe('paragraph');
+ return base.apply(base.tr.setSelection(TextSelection.create(base.doc, caret)));
+}
+
+/** Paste `payload` (text/plain markdown) into the cell caret; return the doc. */
+function pasteIntoCell(payload: string): PmNode {
+ const view = realStateView(seedWithCellCaret());
+ const handled = createHandlePaste({ mdManager })(
+ view as never,
+ fakeDT({ 'text/plain': payload }),
+ );
+ expect(handled).toBe(true);
+ return view.current().doc;
+}
+
+/** The first jsxComponent that is a descendant of a tableCell, or null. */
+function componentInCell(doc: PmNode): PmNode | null {
+ let found: PmNode | null = null;
+ doc.descendants((node, _pos, parent) => {
+ if (found) return false;
+ if (node.type.name === 'jsxComponent' && parent?.type.name === 'tableCell') {
+ found = node;
+ return false;
+ }
+ return true;
+ });
+ return found;
+}
+
+/** Serialize `doc`, capturing every `console.warn` line emitted during the run. */
+function serializeCapturingWarns(doc: PmNode): { md: string; warns: string[] } {
+ const warns: string[] = [];
+ const orig = console.warn;
+ console.warn = (...args: unknown[]) => {
+ warns.push(args.map(String).join(' '));
+ };
+ try {
+ return { md: mdManager.serialize(doc.toJSON()), warns };
+ } finally {
+ console.warn = orig;
+ }
+}
+
+let origWarn: typeof console.warn;
+beforeEach(() => {
+ origWarn = console.warn;
+});
+afterEach(() => {
+ console.warn = origWarn;
+});
+
+describe('unregistered component in a table cell drops on serialize', () => {
+ // Serializing the untouched table is the oracle for "the component
+ // contributed nothing": a total drop makes the pasted-doc output
+ // byte-identical to this, independent of table formatting details.
+ const baselineMd = mdManager.serialize(schema.nodeFromJSON(mdManager.parse(TABLE_MD)).toJSON());
+
+ test('a self-closing component pastes into a cell then serializes to nothing + a drop warn', () => {
+ const doc = pasteIntoCell('<CustomWidget foo="bar" />');
+
+ // Reachability: the component genuinely reached the cell (no insert guard).
+ const comp = componentInCell(doc);
+ expect(comp?.attrs.componentName).toBe('CustomWidget');
+ expect(comp?.childCount).toBe(0);
+
+ const { md, warns } = serializeCapturingWarns(doc);
+
+ // Loss: the name and props are gone from the serialized markdown.
+ expect(md).not.toContain('CustomWidget');
+ expect(md).not.toContain('foo');
+ // The component contributed zero bytes — output equals the untouched table.
+ expect(md).toBe(baselineMd);
+ // Surrounding cells survive, so the drop is scoped, not a table-wide loss.
+ expect(md).toContain('| c | d |');
+
+ const drops = warns.map((w) => tryParseDrop(w)).filter((d): d is DropWarn => d !== null);
+ expect(drops).toContainEqual({ event: DROP_EVENT, nodeType: 'mdxJsxFlowElement' });
+ });
+
+ test('a component WITH interior content in a cell drops the interior too', () => {
+ const doc = pasteIntoCell('<CustomWidget>\n\ninside\n\n</CustomWidget>\n');
+
+ const comp = componentInCell(doc);
+ expect(comp?.attrs.componentName).toBe('CustomWidget');
+ // The interior body is present in the document before serialize...
+ expect(comp?.textContent).toBe('inside');
+
+ const { md, warns } = serializeCapturingWarns(doc);
+
+ // ...yet the wrapper AND its interior vanish on serialize — the loss is not
+ // limited to childless components.
+ expect(md).not.toContain('CustomWidget');
+ expect(md).not.toContain('inside');
+ expect(md).toBe(baselineMd);
+
+ const drops = warns.map((w) => tryParseDrop(w)).filter((d): d is DropWarn => d !== null);
+ expect(drops).toContainEqual({ event: DROP_EVENT, nodeType: 'mdxJsxFlowElement' });
+ });
+});
+
+interface DropWarn {
+ event: string;
+ nodeType: string;
+}
+
+/** Parse a captured warn line as the structured drop diagnostic, or null. */
+function tryParseDrop(line: string): DropWarn | null {
+ try {
+ const parsed: unknown = JSON.parse(line);
+ if (
+ typeof parsed === 'object' &&
+ parsed !== null &&
+ 'event' in parsed &&
+ 'nodeType' in parsed &&
+ typeof (parsed as Record<string, unknown>).event === 'string' &&
+ typeof (parsed as Record<string, unknown>).nodeType === 'string'
+ ) {
+ const { event, nodeType } = parsed as { event: string; nodeType: string };
+ return { event, nodeType };
+ }
+ } catch {
+ // Non-JSON warn lines (unrelated diagnostics) are not drop events.
+ }
+ return null;
+}
diff --git a/packages/app/tests/integration/jsx-unregistered-rawbox-undo-characterization.test.ts b/packages/app/tests/integration/jsx-unregistered-rawbox-undo-characterization.test.ts
new file mode 100644
index 000000000..e02efac08
--- /dev/null
+++ b/packages/app/tests/integration/jsx-unregistered-rawbox-undo-characterization.test.ts
@@ -0,0 +1,217 @@
+/**
+ * Undo of an unregistered raw-box (rawMdxFallback) edit at the bridge rung.
+ *
+ * The predecessor undo test (jsx-undo-roundtrip) drives edits through the agent
+ * Y.Text write path (agentWriteMd) — a Y.Text-FIRST transaction. A raw-box edit
+ * is XmlFragment-FIRST: forwardUpdate dispatches tr.replaceWith / tr.delete on the
+ * rawMdxFallback's content range (RawMdxFallbackCMView), which the server's
+ * Observer A re-derives into Y.Text. This test reproduces that XmlFragment-first
+ * edit at the Y.XmlFragment layer — the layer y-prosemirror writes to when that PM
+ * transaction dispatches — because the nested CodeMirror NodeView is browser-tier
+ * and does not mount in-process. The edit is a wholesale content replace, matching
+ * forwardUpdate's replaceWith shape. The seam under test (Observer A → Y.Text →
+ * session UndoManager → applyAgentUndo) runs with real production components.
+ *
+ * An in-harness rawMdxFallback is reached via invalid MDX; the valid-unregistered
+ * rAF-conversion box is a client browser NodeView, unreachable in-process. Both are
+ * the same PM node with the same forwardUpdate edit path, so the undo seam is
+ * identical for either origin of the box.
+ *
+ * Observed and PINNED (the reachability/loss record for the product triage):
+ * 1. A raw-box (XmlFragment-first) edit propagates to Y.Text but is NOT captured by
+ * the agent session UndoManager — structurally, because Observer A re-origins
+ * every XmlFragment→Y.Text write to OBSERVER_SYNC_ORIGIN, which the UM does not
+ * track. Not agent-origin-dependent: even an XmlFragment edit made under
+ * session.origin lands in Y.Text under OBSERVER_SYNC_ORIGIN and is not captured.
+ * A direct Y.Text edit under session.origin IS captured (the control).
+ * 2. When the agent undoes its own SEPARATE edit, the raw-box edit SURVIVES and the
+ * Y.Text round-trips (heading + raw-box-edited body + trailing intact; the agent
+ * edit cleanly removed), with the rawMdxFallback Y.XmlElement identity preserved.
+ * Item-preservation holds — no content or attribution loss (not a corruption finding).
+ *
+ * Consequence for any future undo surface: a raw-box (WYSIWYG-class) edit is the
+ * human client's to undo (editor.commands.undo), not the agent Y.Text undo's — the
+ * agent undo neither reverts it nor corrupts it.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { setTimeout as wait } from 'node:timers/promises';
+import * as Y from 'yjs';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { agentUndo, agentWriteMd, createTestServer, type TestServer } from './test-harness';
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+/** First rawMdxFallback element in the fragment (mirrors raw-mdx-fallback-multi-client). */
+function findRawMdxFallback(fragment: Y.XmlFragment): Y.XmlElement | null {
+ for (let i = 0; i < fragment.length; i++) {
+ const child = fragment.get(i);
+ if (child instanceof Y.XmlElement && child.nodeName === 'rawMdxFallback') return child;
+ }
+ return null;
+}
+
+/** First Y.XmlText child inside a Y.XmlElement (the raw box's editable content). */
+function getFirstXmlText(el: Y.XmlElement): Y.XmlText | null {
+ for (let i = 0; i < el.length; i++) {
+ const child = el.get(i);
+ if (child instanceof Y.XmlText) return child;
+ }
+ return null;
+}
+
+/** Reproduce forwardUpdate's wholesale replace of the raw box content at the Y layer. */
+function replaceRawBoxContent(
+ sess: { dc: { document: Y.Doc } },
+ xmlText: Y.XmlText,
+ newSource: string,
+ origin?: unknown,
+): void {
+ sess.dc.document.transact(() => {
+ xmlText.delete(0, xmlText.length);
+ xmlText.insert(0, newSource);
+ }, origin);
+}
+
+// <Steps> is an unregistered component name; the mismatched close makes the block
+// invalid MDX so parseWithFallback yields a rawMdxFallback raw box.
+const SEED = '# Heading\n\n<Steps>RAWBOX-SEED-BODY</Stepz>\n\nTrailing paragraph.\n';
+
+describe('FR-M7 — undo of an unregistered raw-box edit at the bridge rung', () => {
+ test('a raw-box XmlFragment-first edit propagates to Y.Text but is not captured by the agent undo stack', async () => {
+ const docName = `rawbox-undo-boundary-${crypto.randomUUID()}`;
+ const agentSuffix = `rb-${crypto.randomUUID().slice(0, 8)}`;
+ const connectionId = `agent-${agentSuffix}`;
+ const sm = server.instance.sessionManager;
+ try {
+ await agentWriteMd(server.port, SEED, {
+ docName,
+ agentId: agentSuffix,
+ agentName: `A-${agentSuffix}`,
+ position: 'replace',
+ });
+ await wait(600);
+
+ const sess = await sm.getSession(docName, connectionId);
+ const ytext = sess.dc.document.getText('source');
+ const fragment = sess.dc.document.getXmlFragment('default');
+
+ const rawBox = findRawMdxFallback(fragment);
+ expect(rawBox).not.toBeNull();
+ // biome-ignore lint/style/noNonNullAssertion: asserted above
+ const xmlText = getFirstXmlText(rawBox!);
+ expect(xmlText).not.toBeNull();
+ expect(ytext.toString()).toContain('RAWBOX-SEED-BODY');
+
+ const stackAfterSeed = sess.um.undoStack.length;
+ expect(stackAfterSeed).toBeGreaterThan(0);
+
+ // The raw-box edit (undefined origin — a local WYSIWYG/CM dispatch).
+ // biome-ignore lint/style/noNonNullAssertion: asserted above
+ replaceRawBoxContent(sess, xmlText!, '<Steps>RAWBOX-EDITED-BODY</Stepz>');
+ await wait(600);
+
+ // Observer A propagated the XmlFragment edit into Y.Text …
+ expect(ytext.toString()).toContain('RAWBOX-EDITED-BODY');
+ expect(ytext.toString()).not.toContain('RAWBOX-SEED-BODY');
+ // … but the agent UndoManager did NOT capture it (Observer A re-origins the
+ // Y.Text write to OBSERVER_SYNC_ORIGIN, which the UM does not track).
+ expect(sess.um.undoStack.length).toBe(stackAfterSeed);
+
+ // Control (b): the boundary is structural, not origin-dependent — an
+ // XmlFragment edit made under session.origin still lands in Y.Text under
+ // OBSERVER_SYNC_ORIGIN, so it is still not captured.
+ // biome-ignore lint/style/noNonNullAssertion: asserted above
+ replaceRawBoxContent(sess, xmlText!, '<Steps>RAWBOX-ORIGIN-B</Stepz>', sess.origin);
+ await wait(400);
+ expect(sess.um.undoStack.length).toBe(stackAfterSeed);
+
+ // Control (c): a DIRECT Y.Text edit under session.origin IS captured — proving
+ // the stack is live, so the raw-box non-capture above is meaningful, not frozen.
+ sess.dc.document.transact(() => {
+ ytext.insert(ytext.length, '\nDIRECT-YTEXT-EDIT\n');
+ }, sess.origin);
+ await wait(400);
+ expect(sess.um.undoStack.length).toBe(stackAfterSeed + 1);
+ } finally {
+ await sm.closeSession(docName, connectionId).catch(() => {});
+ }
+ }, 30_000);
+
+ test('agent-undo of a separate agent edit preserves the raw-box edit and round-trips', async () => {
+ const docName = `rawbox-undo-preserve-${crypto.randomUUID()}`;
+ const agentSuffix = `rb-${crypto.randomUUID().slice(0, 8)}`;
+ const connectionId = `agent-${agentSuffix}`;
+ const sm = server.instance.sessionManager;
+ try {
+ // StackItem 1: seed the raw-box doc.
+ await agentWriteMd(server.port, SEED, {
+ docName,
+ agentId: agentSuffix,
+ agentName: `A-${agentSuffix}`,
+ position: 'replace',
+ });
+ await wait(600);
+
+ const sess = await sm.getSession(docName, connectionId);
+ const ytext = sess.dc.document.getText('source');
+ const fragment = sess.dc.document.getXmlFragment('default');
+ const rawBox = findRawMdxFallback(fragment);
+ expect(rawBox).not.toBeNull();
+ // biome-ignore lint/style/noNonNullAssertion: asserted above
+ const rawItemBefore = rawBox!._item;
+ // An integrated Y.XmlElement has a non-null `_item`; assert it so the
+ // identity check below is a real comparison, not a vacuous null === null.
+ expect(rawItemBefore).not.toBeNull();
+ // biome-ignore lint/style/noNonNullAssertion: asserted above
+ const xmlText = getFirstXmlText(rawBox!);
+ expect(xmlText).not.toBeNull();
+
+ // StackItem 2: the agent's own edit — the burst the undo will revert.
+ await agentWriteMd(server.port, '\n\nAGENT-SECOND-EDIT paragraph.\n', {
+ docName,
+ agentId: agentSuffix,
+ agentName: `A-${agentSuffix}`,
+ position: 'append',
+ });
+ await wait(600);
+ expect(ytext.toString()).toContain('AGENT-SECOND-EDIT');
+
+ // Concurrent raw-box edit (WYSIWYG-class, XmlFragment-first).
+ // biome-ignore lint/style/noNonNullAssertion: asserted above
+ replaceRawBoxContent(sess, xmlText!, '<Steps>RAWBOX-EDITED-BODY</Stepz>');
+ await wait(600);
+ expect(ytext.toString()).toContain('RAWBOX-EDITED-BODY');
+
+ // Undo the agent's own edit (scope last).
+ await agentUndo(server.port, { docName, connectionId, scope: 'last' });
+ await wait(400);
+
+ const afterUndo = ytext.toString();
+ // The agent's edit is cleanly reverted …
+ expect(afterUndo).not.toContain('AGENT-SECOND-EDIT');
+ // … while the raw-box edit and the untouched seed content all survive.
+ expect(afterUndo).toContain('RAWBOX-EDITED-BODY');
+ expect(afterUndo).toContain('# Heading');
+ expect(afterUndo).toContain('Trailing paragraph.');
+ expect(afterUndo).not.toContain('RAWBOX-SEED-BODY');
+
+ // Item-preservation: the rawMdxFallback Y.XmlElement identity is stable across
+ // the whole cycle — the undo did not delete+reinsert the raw box.
+ const rawBoxAfter = findRawMdxFallback(fragment);
+ expect(rawBoxAfter).not.toBeNull();
+ // biome-ignore lint/style/noNonNullAssertion: asserted above
+ expect(rawBoxAfter!._item).toBe(rawItemBefore);
+ } finally {
+ await sm.closeSession(docName, connectionId).catch(() => {});
+ }
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/jsx-unregistered-redo-characterization.test.ts b/packages/app/tests/integration/jsx-unregistered-redo-characterization.test.ts
new file mode 100644
index 000000000..8f089704c
--- /dev/null
+++ b/packages/app/tests/integration/jsx-unregistered-redo-characterization.test.ts
@@ -0,0 +1,127 @@
+/**
+ * Redo reachability at the bridge rung, on an unregistered-component doc.
+ *
+ * The agent API is undo-only; there is no redo product surface. This test
+ * executes the real `applyAgentUndo` and then characterizes what the underlying
+ * Y.UndoManager redo stack looks like — a gap the existing undo round-trip test
+ * leaves open (it asserts undo, never touches redo).
+ *
+ * Observed and PINNED here: after a real agent-undo the redo stack is EMPTY, so
+ * redo is structurally unreachable at this rung. The reason is architectural,
+ * not a settle race: `applyAgentUndo` wraps `um.undo()` in an outer
+ * `document.transact(fn, session.undoOrigin)` so Observer A/B short-circuit on
+ * the paired write. Y.js merges the UndoManager's own nested undo transaction
+ * into that outer one, so the inverse fires under `undoOrigin` instead of the
+ * UndoManager instance — and the UndoManager only captures a redo entry when the
+ * transaction origin is itself. The paired-write wrapping that undo needs is
+ * exactly what prevents redo capture.
+ *
+ * This is a characterization of current reality, not a bug fix — no redo surface
+ * exists to regress. If a redo product surface is ever added it cannot naively
+ * call `um.redo()`; that is the finding this test records.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { setTimeout as wait } from 'node:timers/promises';
+import { normalizeBridge } from '@inkeep/open-knowledge-core';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentUndo,
+ agentWriteMd,
+ assertBridgeInvariant,
+ createTestServer,
+ type TestServer,
+} from './test-harness';
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+// <Steps>/<Step> are unregistered component names (registry.has() is false), so
+// this doc exercises the wildcard/unregistered class through the undo bridge.
+const SEED = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ 'STEP-ONE-BODY first.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'STEP-TWO-BODY second.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+].join('\n');
+
+const STEP_MARKERS = ['STEP-ONE-BODY', 'STEP-TWO-BODY'];
+
+describe('redo at the bridge rung on an unregistered-component doc', () => {
+ test('after a real agent-undo the redo stack is empty and redo does not restore the edit', async () => {
+ const docName = `redo-jsx-${crypto.randomUUID()}`;
+ const agentSuffix = `redo-${crypto.randomUUID().slice(0, 8)}`;
+ const connectionId = `agent-${agentSuffix}`;
+ const sm = server.instance.sessionManager;
+ try {
+ await agentWriteMd(server.port, SEED, {
+ docName,
+ agentId: agentSuffix,
+ agentName: `A-${agentSuffix}`,
+ position: 'replace',
+ });
+ await wait(600);
+
+ const sess = await sm.getSession(docName, connectionId);
+ const ytext = sess.dc.document.getText('source');
+ const preEdit = ytext.toString();
+ for (const m of STEP_MARKERS) expect(preEdit).toContain(m);
+
+ // Undoable edit as a distinct StackItem (spaced past the 500ms capture window).
+ await agentWriteMd(server.port, '\n\nREDO-CHAR-EDIT paragraph.\n', {
+ docName,
+ agentId: agentSuffix,
+ agentName: `A-${agentSuffix}`,
+ position: 'append',
+ });
+ await wait(600);
+ expect(ytext.toString()).toContain('REDO-CHAR-EDIT');
+
+ // Real undo of the last burst — round-trips the source to the pre-edit state.
+ await agentUndo(server.port, { docName, connectionId, scope: 'last' });
+ await wait(400);
+ const afterUndo = ytext.toString();
+ expect(afterUndo).not.toContain('REDO-CHAR-EDIT');
+ expect(normalizeBridge(afterUndo)).toBe(normalizeBridge(preEdit));
+
+ // Characterization: the paired-write undo leaves NO redo entry, so redo is
+ // structurally unreachable — an undo remains on the stack, but nothing to redo.
+ expect(sess.um.redoStack.length).toBe(0);
+ expect(sess.um.undoStack.length).toBeGreaterThan(0);
+
+ // A faithful bridge-rung redo (redo wrapped in the same paired transact the
+ // undo path uses) is a no-op: the empty redo stack means the edit does not
+ // come back and the source stays at the pre-edit state.
+ sess.dc.document.transact(() => {
+ sess.um.redo();
+ }, sess.undoOrigin);
+ await wait(200);
+ const afterRedoAttempt = ytext.toString();
+ expect(afterRedoAttempt).not.toContain('REDO-CHAR-EDIT');
+ expect(normalizeBridge(afterRedoAttempt)).toBe(normalizeBridge(preEdit));
+ // The bridge stays settled — Y.Text is within tolerance of the re-derived fragment.
+ assertBridgeInvariant(ytext, sess.dc.document.getXmlFragment('default'));
+ } finally {
+ await sm.closeSession(docName, connectionId).catch(() => {});
+ }
+ }, 30_000);
+});
diff --git a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
new file mode 100644
index 000000000..db210a2a7
--- /dev/null
+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
@@ -0,0 +1,515 @@
+/**
+ * Keystroke-cadence fidelity inside registered danger-space components.
+ *
+ * The Observer-A producer guard and the server-side structural-freshness
+ * derivation each run once per Observer-A drain. The existing tests exercise
+ * them with single-shot programmatic edits, and the only char-by-char coverage
+ * types into an UNREGISTERED <Steps> (wildcard raw-source), which bypasses both.
+ * This closes that gap: it drives REAL per-keystroke cadence into a registered
+ * danger-space interior — a Callout (jsxComponent → producer guard + structural
+ * freshness) and a table cell (table / tableCell → producer guard) — through the
+ * transient intermediate states typing passes through.
+ *
+ * Cadence model: each character is its own null-origin transaction with a
+ * quiescence + server-drain settle before the next, so every keystroke is an
+ * independent Observer-A drain that fires the guard and the freshness check.
+ * Under `bun test` the guard is in its loud (throw) posture, so a false-fire
+ * aborts that drain BEFORE the Y.Text write — the per-keystroke assertion that
+ * the growing text reached the persisted server Y.Text then fails AT the
+ * keystroke that fired, before the next keystroke's full re-serialize can heal
+ * it. Freshness runs on the no-flip cases (a stale `sourceRaw` vs the live
+ * children), so those drains re-derive fresh bytes per keystroke.
+ *
+ * Oracles are tolerance-aware — structure + survival, never raw byte-identity:
+ * the typed text survives, container tags stay singular and un-re-indented, and
+ * a pristine registered sibling is not re-derived while another node is typed
+ * into. Multi-client convergence proves the read-only guard does not perturb the
+ * observer seam for a remote peer.
+ *
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { setTimeout as wait } from 'node:timers/promises';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentWriteMd,
+ assertAllConverged,
+ awaitDocQuiescence,
+ createTestClient,
+ createTestClients,
+ createTestServer,
+ getServerState,
+ mdManager,
+ schema,
+ type TestClient,
+ type TestServer,
+} from './test-harness';
+
+// A registered Callout whose interior is a real paragraph (the NodeViewContent
+// hole an author types into). Blank-line delimited so it lifts to a jsxComponent.
+const CALLOUT_SEED = ['<Callout type="info">', '', 'Note:', '', '</Callout>', ''].join('\n');
+// A GFM table: the body cell is a tableCell (danger space), the header a
+// tableHeader — the finder targets the body cell only.
+const TABLE_SEED = ['| Head |', '| --- |', '| seed |', ''].join('\n');
+// Two sibling Callouts: type into the first, prove the second (pristine,
+// untouched) is never re-derived while the freshness check runs on both.
+const TWO_CALLOUTS = [
+ '<Callout type="info">',
+ '',
+ 'AAA',
+ '',
+ '</Callout>',
+ '',
+ '<Callout type="warning">',
+ '',
+ 'BBB',
+ '',
+ '</Callout>',
+ '',
+].join('\n');
+
+const INDENTED_CALLOUT = /\n[ \t]+<\/?Callout\b/; // a <Callout>/</Callout> tag gaining leading indent
+const KEYSTROKE_TEST_TIMEOUT_MS = 30_000;
+
+type PmNodeJson = {
+ type?: string;
+ text?: string;
+ attrs?: Record<string, unknown>;
+ content?: PmNodeJson[];
+ marks?: unknown[];
+};
+
+/** The doc tree currently in a client's XmlFragment (synced from the server). */
+function currentTree(client: TestClient): PmNodeJson {
+ return yXmlFragmentToProseMirrorRootNode(client.fragment, schema).toJSON() as PmNodeJson;
+}
+
+/** First descendant text node (the leaf a keystroke lands in), or undefined. */
+function firstTextNode(node: PmNodeJson): PmNodeJson | undefined {
+ if (typeof node.text === 'string') return node;
+ for (const child of node.content ?? []) {
+ const found = firstTextNode(child);
+ if (found) return found;
+ }
+ return undefined;
+}
+
+/** Concatenated text of a subtree — the survival stream a faithful round-trip
+ * must not lose. Whitespace-preserving (callers compare exact interior text). */
+function subtreeText(node: PmNodeJson): string {
+ let acc = node.text ?? '';
+ for (const child of node.content ?? []) acc += subtreeText(child);
+ return acc;
+}
+
+const isCallout = (n: PmNodeJson): boolean =>
+ n.type === 'jsxComponent' && n.attrs?.componentName === 'Callout';
+const isBodyCell = (n: PmNodeJson): boolean => n.type === 'tableCell';
+
+/**
+ * Reproduce one keystroke as its settled wire state: set the first text node
+ * inside the first container matching `isContainer` (disambiguated by
+ * `whenFirstText` on its current interior) to `nextText`. When `flipDirty`, mark
+ * the container `sourceDirty` exactly as the client SourceDirtyObserver would;
+ * otherwise leave it pristine so `sourceRaw` goes stale and the server-side
+ * structural-freshness derivation must catch the divergence. `sourceRaw` is
+ * never touched, so a dirty/diverged container carries a genuinely stale cache.
+ */
+function editInterior(
+ tree: PmNodeJson,
+ isContainer: (n: PmNodeJson) => boolean,
+ whenFirstText: (t: string) => boolean,
+ nextText: string,
+ flipDirty: boolean,
+): PmNodeJson {
+ const next = structuredClone(tree);
+ let done = false;
+ const walk = (node: PmNodeJson): void => {
+ if (done) return;
+ if (isContainer(node)) {
+ const leaf = firstTextNode(node);
+ if (leaf && whenFirstText(leaf.text as string)) {
+ leaf.text = nextText;
+ if (flipDirty) node.attrs = { ...node.attrs, sourceDirty: true };
+ done = true;
+ return;
+ }
+ }
+ node.content?.forEach(walk);
+ };
+ walk(next);
+ if (!done) throw new Error('editInterior: no matching container found in the tree');
+ return next;
+}
+
+/** Commit a target doc tree into the client fragment with null origin — the same
+ * channel a local WYSIWYG mutation publishes through. `updateYFragment` diffs to
+ * a minimal delta, so growing/shrinking one text node commits a single-char
+ * edit: Observer A sees a real fragment change (xmlDirty=true) per keystroke. */
+function commitFragment(client: TestClient, tree: PmNodeJson): void {
+ const pmNode = schema.nodeFromJSON(tree);
+ client.doc.transact(() => {
+ updateYFragment(client.doc, client.fragment, pmNode, {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ });
+}
+
+/** Whitespace-normalized form — collapse internal runs, trim ends. Markdown
+ * serialization legitimately strips trailing spaces and collapses blank runs,
+ * so the survival oracle compares content modulo whitespace, never raw bytes. */
+function normalizeWs(s: string): string {
+ return s.replace(/\s+/g, ' ').trim();
+}
+
+/** Text of the first node matching `isTarget`, reconstructed from the persisted
+ * source. Table cells escape markdown-significant characters on serialize (a
+ * literal `|` becomes `\|`), and re-derivation re-flows whitespace, so the
+ * survival oracle reparses and reads the interior text — tolerance-aware
+ * structure+survival, never a raw-byte match. */
+function reparsedInteriorText(source: string, isTarget: (n: PmNodeJson) => boolean): string {
+ const json = mdManager.parseWithFallback(source) as PmNodeJson;
+ let text = '';
+ let found = false;
+ const walk = (n: PmNodeJson): void => {
+ if (found) return;
+ if (isTarget(n)) {
+ text = subtreeText(n);
+ found = true;
+ return;
+ }
+ n.content?.forEach(walk);
+ };
+ walk(json);
+ return text;
+}
+
+const firstBodyCellText = (source: string): string => reparsedInteriorText(source, isBodyCell);
+const firstCalloutInteriorText = (source: string): string =>
+ reparsedInteriorText(source, isCallout);
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+/** Persisted server-side Y.Text (the bytes a reopen or teammate receives). */
+function serverText(docName: string): string {
+ return getServerState(server, docName)?.ytext.toString() ?? '';
+}
+
+/** Wait for the keystroke's server drain to land (or abort). Polling the SERVER
+ * doc both asserts survival AND enforces per-drain granularity — the next
+ * keystroke is not committed until this one's drain has settled. A timeout means
+ * the drain never wrote the byte: the guard threw (aborted) or the derivation
+ * mangled it. Returns a real boolean (the harness `pollUntil` throws on timeout
+ * and returns void on success — unusable for a distinguishing assertion). */
+async function pollFor(predicate: () => boolean, budgetMs = 6_000, stepMs = 40): Promise<boolean> {
+ const start = Date.now();
+ while (Date.now() - start < budgetMs) {
+ if (predicate()) return true;
+ await wait(stepMs);
+ }
+ return predicate();
+}
+
+async function expectPersisted(
+ docName: string,
+ predicate: (s: string) => boolean,
+ ctx: string,
+): Promise<void> {
+ const ok = await pollFor(() => predicate(serverText(docName)));
+ if (!ok) {
+ throw new Error(
+ `${ctx}\n survival oracle unmet within budget — the drain never persisted the byte ` +
+ `(a producer-guard abort or a mangled re-derivation).\n current server bytes: ${JSON.stringify(
+ serverText(docName),
+ )}`,
+ );
+ }
+}
+
+describe('keystroke-cadence fidelity — registered danger-space, per-drain guard + freshness', () => {
+ /**
+ * Type into a pristine Callout interior char-by-char WITHOUT the client dirty
+ * flip. Each keystroke leaves `sourceRaw` stale against the grown children, so
+ * the server structural-freshness derivation must detect divergence and
+ * re-derive fresh bytes — while the producer guard (danger space present) must
+ * stay silent on every legal intermediate.
+ *
+ */
+ test(
+ 'Callout interior, no dirty flip: freshness re-derives every keystroke, guard silent',
+ async () => {
+ const docName = `keystroke-callout-noflip-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, CALLOUT_SEED, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ expect(serverText(docName)).toContain('Note:');
+
+ const typed = ' incident summary';
+ let interior = 'Note:';
+ for (let i = 0; i < typed.length; i++) {
+ interior += typed[i];
+ commitFragment(
+ client,
+ editInterior(
+ currentTree(client),
+ isCallout,
+ (t) => t.startsWith('Note:'),
+ interior,
+ false,
+ ),
+ );
+ await awaitDocQuiescence(client.doc);
+ const prefix = interior;
+ await expectPersisted(
+ docName,
+ (s) => normalizeWs(firstCalloutInteriorText(s)) === normalizeWs(prefix),
+ `Callout no-flip keystroke #${i + 1} (${JSON.stringify(typed[i])}) → interior ${JSON.stringify(prefix)}`,
+ );
+ const s = serverText(docName);
+ expect(s.match(/<Callout\b/g)).toHaveLength(1);
+ expect(s.match(/<\/Callout>/g)).toHaveLength(1);
+ expect(s).not.toMatch(INDENTED_CALLOUT);
+ }
+
+ const final = serverText(docName);
+ expect(normalizeWs(firstCalloutInteriorText(final))).toBe('Note: incident summary');
+ expect(final).toContain('type="info"');
+ } finally {
+ await client.cleanup();
+ }
+ },
+ KEYSTROKE_TEST_TIMEOUT_MS,
+ );
+
+ /**
+ * Same interior, WITH the client dirty flip each keystroke — the provenance
+ * fast path a real user edit takes. Exercises the producer guard on the dirty
+ * re-derive route (freshness short-circuited by the flip).
+ *
+ */
+ test(
+ 'Callout interior, dirty flip: guard stays silent across the burst',
+ async () => {
+ const docName = `keystroke-callout-flip-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, CALLOUT_SEED, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ const typed = ' urgent';
+ let interior = 'Note:';
+ for (let i = 0; i < typed.length; i++) {
+ interior += typed[i];
+ commitFragment(
+ client,
+ editInterior(
+ currentTree(client),
+ isCallout,
+ (t) => t.startsWith('Note:'),
+ interior,
+ true,
+ ),
+ );
+ await awaitDocQuiescence(client.doc);
+ const prefix = interior;
+ await expectPersisted(
+ docName,
+ (s) => normalizeWs(firstCalloutInteriorText(s)) === normalizeWs(prefix),
+ `Callout flip keystroke #${i + 1} → interior ${JSON.stringify(prefix)}`,
+ );
+ expect(serverText(docName).match(/<Callout\b/g)).toHaveLength(1);
+ }
+ const final = serverText(docName);
+ expect(normalizeWs(firstCalloutInteriorText(final))).toBe('Note: urgent');
+ expect(final).toContain('type="info"');
+ expect(final).not.toMatch(INDENTED_CALLOUT);
+ } finally {
+ await client.cleanup();
+ }
+ },
+ KEYSTROKE_TEST_TIMEOUT_MS,
+ );
+
+ /**
+ * Type markdown-significant characters (`|`, `*`, backtick) into a table body
+ * cell char-by-char. The cell is danger space (guard runs on every drain), and
+ * a literal pipe must escape on serialize and reparse to the same literal —
+ * the survival oracle compares the reparsed cell text, so an escaping regress
+ * that dropped a character would fail it.
+ *
+ */
+ test(
+ 'Table cell: escaping-hot characters typed char-by-char survive, guard silent',
+ async () => {
+ const docName = `keystroke-tablecell-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, TABLE_SEED, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+ expect(firstBodyCellText(serverText(docName))).toBe('seed');
+
+ const typed = 'a|b*c`d';
+ let cell = 'seed';
+ for (let i = 0; i < typed.length; i++) {
+ cell += typed[i];
+ commitFragment(
+ client,
+ editInterior(currentTree(client), isBodyCell, (t) => t.startsWith('seed'), cell, false),
+ );
+ await awaitDocQuiescence(client.doc);
+ const expected = cell;
+ await expectPersisted(
+ docName,
+ (s) => firstBodyCellText(s) === expected,
+ `Table cell keystroke #${i + 1} (${JSON.stringify(typed[i])}) → cell ${JSON.stringify(expected)}`,
+ );
+ // The table structure stays intact: one header separator row.
+ expect(serverText(docName)).toMatch(/\|\s*-+\s*\|/);
+ }
+ expect(firstBodyCellText(serverText(docName))).toBe('seeda|b*c`d');
+ } finally {
+ await client.cleanup();
+ }
+ },
+ KEYSTROKE_TEST_TIMEOUT_MS,
+ );
+
+ /**
+ * Adversarial grow → shrink (backspace-correct) → regrow inside a pristine
+ * Callout interior. Every step is its own drain (including the shrinking ones a
+ * single-shot edit never produces), and freshness must re-derive each without
+ * the guard firing on any transient.
+ *
+ */
+ test(
+ 'Callout interior: grow, backspace-correct, regrow — no guard fire on any transient',
+ async () => {
+ const docName = `keystroke-correct-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, CALLOUT_SEED, { docName, position: 'replace' });
+ await wait(300);
+ const client = await createTestClient(server.port, docName);
+ try {
+ await awaitDocQuiescence(client.doc);
+
+ // Walk a deterministic sequence of interior states: type "abc", delete
+ // back to "a", then type "XYZ". Each entry is one settled drain.
+ const states = [
+ 'Note:a',
+ 'Note:ab',
+ 'Note:abc',
+ 'Note:ab',
+ 'Note:a',
+ 'Note:aX',
+ 'Note:aXY',
+ 'Note:aXYZ',
+ ];
+ for (let i = 0; i < states.length; i++) {
+ const interior = states[i];
+ commitFragment(
+ client,
+ editInterior(
+ currentTree(client),
+ isCallout,
+ (t) => t.startsWith('Note:'),
+ interior,
+ false,
+ ),
+ );
+ await awaitDocQuiescence(client.doc);
+ await expectPersisted(
+ docName,
+ (s) => normalizeWs(firstCalloutInteriorText(s)) === normalizeWs(interior),
+ `correct step #${i + 1} → interior ${JSON.stringify(interior)}`,
+ );
+ const s = serverText(docName);
+ expect(s.match(/<Callout\b/g)).toHaveLength(1);
+ expect(s).not.toMatch(INDENTED_CALLOUT);
+ }
+ expect(normalizeWs(firstCalloutInteriorText(serverText(docName)))).toBe('Note:aXYZ');
+ } finally {
+ await client.cleanup();
+ }
+ },
+ KEYSTROKE_TEST_TIMEOUT_MS,
+ );
+
+ /**
+ * Sibling isolation: type into the first Callout char-by-char (the realistic
+ * user-edit path — the client dirty flip on each keystroke) while the second
+ * Callout sits pristine and untouched. The freshness check still runs on the
+ * pristine sibling on every serialize pass: it must return NOT-diverged for it,
+ * so its exact seed bytes survive byte-stable — a false-divergence would
+ * re-derive (and could re-indent) a node the user never touched. Two clients
+ * converge on the result, proving the read-only guard does not perturb the
+ * observer seam for a remote peer.
+ *
+ */
+ test(
+ 'sibling pristine Callout stays byte-stable while the other is typed into; peers converge',
+ async () => {
+ const docName = `keystroke-sibling-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, TWO_CALLOUTS, { docName, position: 'replace' });
+ await wait(300);
+ const [a, b] = await createTestClients(server.port, { count: 2, docName });
+ try {
+ await awaitDocQuiescence(a.doc);
+ await awaitDocQuiescence(b.doc);
+ await assertAllConverged([a, b]);
+
+ const seedText = serverText(docName);
+ const bMatch = seedText.match(/<Callout type="warning">[\s\S]*?<\/Callout>/);
+ expect(bMatch).toBeTruthy();
+ const bSlice = (bMatch as RegExpMatchArray)[0];
+ expect(bSlice).toContain('BBB');
+
+ const typed = ' first';
+ let interiorA = 'AAA';
+ for (let i = 0; i < typed.length; i++) {
+ interiorA += typed[i];
+ commitFragment(
+ a,
+ editInterior(currentTree(a), isCallout, (t) => t.startsWith('AAA'), interiorA, true),
+ );
+ await awaitDocQuiescence(a.doc);
+ const prefix = interiorA;
+ await expectPersisted(
+ docName,
+ (s) => normalizeWs(firstCalloutInteriorText(s)) === normalizeWs(prefix),
+ `sibling: Callout A keystroke #${i + 1} → interior ${JSON.stringify(prefix)}`,
+ );
+ const s = serverText(docName);
+ // The untouched sibling's exact seed slice survives — no re-derive,
+ // no re-indent, no false-divergence.
+ expect(s).toContain(bSlice);
+ expect(s.match(/<Callout\b/g)).toHaveLength(2);
+ expect(s).not.toMatch(INDENTED_CALLOUT);
+ }
+
+ // The remote peer received the same fresh bytes: the read-only guard did
+ // not perturb convergence, and the pristine sibling is intact there too.
+ await awaitDocQuiescence(a.doc);
+ await awaitDocQuiescence(b.doc);
+ await assertAllConverged([a, b]);
+ const bText = b.doc.getText('source').toString();
+ expect(normalizeWs(firstCalloutInteriorText(bText))).toBe('AAA first');
+ expect(bText).toContain(bSlice);
+ } finally {
+ await Promise.all([a.cleanup(), b.cleanup()]);
+ }
+ },
+ KEYSTROKE_TEST_TIMEOUT_MS,
+ );
+});
diff --git a/packages/app/tests/integration/producer-guard-wiring.test.ts b/packages/app/tests/integration/producer-guard-wiring.test.ts
new file mode 100644
index 000000000..8bb2273a6
--- /dev/null
+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts
@@ -0,0 +1,119 @@
+/**
+ * Producer guard — wired into the real server, silent on legal edits.
+ *
+ * The Observer-A producer guard runs on every server drain that carries a
+ * danger-space node (jsxComponent / table). This pins the OTHER half of its
+ * contract from the server-side unit test (which faults the serializer to prove
+ * it FIRES): here the serializer is real, so a legal interior edit inside a
+ * registered component must round-trip cleanly and the guard must stay silent.
+ *
+ * Under `bun test` the guard is in its loud (throw) posture, so a false-fire on
+ * this legal edit would abort the server-side Observer-A sync and the edit would
+ * never reach the persisted bytes — the freshness assertion below would go red.
+ * Two clients converge on the fresh bytes, exercising the observer seam
+ * multi-client (a read-only guard must not perturb convergence).
+ *
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { setTimeout as wait } from 'node:timers/promises';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import {
+ agentWriteMd,
+ assertAllConverged,
+ awaitDocQuiescence,
+ createTestClients,
+ createTestServer,
+ getServerState,
+ schema,
+ type TestClient,
+ type TestServer,
+} from './test-harness';
+
+const SEED = ['<Callout type="info">', '', 'Original interior body.', '', '</Callout>', ''].join(
+ '\n',
+);
+
+type PmNodeJson = {
+ type?: string;
+ text?: string;
+ attrs?: Record<string, unknown>;
+ content?: PmNodeJson[];
+ marks?: unknown[];
+};
+
+function currentTree(client: TestClient): PmNodeJson {
+ return yXmlFragmentToProseMirrorRootNode(client.fragment, schema).toJSON() as PmNodeJson;
+}
+
+/** A legal WYSIWYG interior edit as its settled wire state: rewrite the interior
+ * text and flip the enclosing Callout dirty exactly as the client
+ * SourceDirtyObserver would, so Observer A re-derives from the edited children. */
+function planInteriorEdit(tree: PmNodeJson, find: string, replace: string): PmNodeJson {
+ const next = structuredClone(tree);
+ const walk = (node: PmNodeJson): void => {
+ if (node.type === 'jsxComponent' && node.attrs?.componentName === 'Callout') {
+ node.attrs = { ...node.attrs, sourceDirty: true };
+ }
+ if (typeof node.text === 'string' && node.text.includes(find)) {
+ node.text = node.text.replace(find, replace);
+ }
+ node.content?.forEach(walk);
+ };
+ walk(next);
+ return next;
+}
+
+function commitFragment(client: TestClient, tree: PmNodeJson): void {
+ const pmNode = schema.nodeFromJSON(tree);
+ client.doc.transact(() => {
+ updateYFragment(client.doc, client.fragment, pmNode, {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ });
+}
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+describe('producer guard (FR6) — wired, silent on a legal danger-space edit', () => {
+ test('a legal interior edit round-trips through the guarded drain; two clients converge on the fresh bytes', async () => {
+ const docName = `producer-guard-wiring-${crypto.randomUUID()}`;
+ await agentWriteMd(server.port, SEED, { docName, position: 'replace' });
+ await wait(300);
+ const [a, b] = await createTestClients(server.port, { count: 2, docName });
+ try {
+ await awaitDocQuiescence(a.doc);
+ await awaitDocQuiescence(b.doc);
+ await assertAllConverged([a, b]);
+ expect(a.doc.getText('source').toString()).toContain('Original interior body');
+
+ // Client A edits the Callout interior. The drain serializes the danger
+ // space (jsxComponent present → the guard runs) and, on legal content,
+ // must NOT throw — so the fresh bytes reach Y.Text and both peers.
+ commitFragment(a, planInteriorEdit(currentTree(a), 'Original', 'EDITED'));
+ await awaitDocQuiescence(a.doc);
+ await awaitDocQuiescence(b.doc);
+ await assertAllConverged([a, b]);
+
+ const persisted = getServerState(server, docName)?.ytext.toString() ?? '';
+ expect(persisted).toContain('EDITED interior body');
+ expect(persisted).toContain('type="info"');
+ expect(persisted.match(/<Callout\b/g)).toHaveLength(1);
+ // The remote peer received the same fresh bytes — the read-only guard did
+ // not perturb convergence.
+ expect(b.doc.getText('source').toString()).toContain('EDITED interior body');
+ } finally {
+ await Promise.all([a.cleanup(), b.cleanup()]);
+ }
+ });
+});
diff --git a/packages/app/tests/integration/structural-freshness-real-docs.test.ts b/packages/app/tests/integration/structural-freshness-real-docs.test.ts
new file mode 100644
index 000000000..53f167cf6
--- /dev/null
+++ b/packages/app/tests/integration/structural-freshness-real-docs.test.ts
@@ -0,0 +1,109 @@
+/**
+ * Structural-freshness derivation — zero false-dirty on the real docs corpus.
+ *
+ * The spike proved the comparator is false-dirty-free on real pristine
+ * components (14→0 once the 3-key volatile set is stripped). This commits that
+ * as a standing regression: parse every authored doc under `docs/content/**`,
+ * check every pristine component with the freshness checker, and assert NONE
+ * reads as diverged — a false-dirty would force a spurious re-derive and churn
+ * convergence. The must-fire half plants real structural mutations and asserts
+ * they are caught, so the zero is a live instrument, not a vacuous pass.
+ *
+ * This is a property test of the checker's false-positive rate, not a
+ * write-surface × construct byte-preservation matrix, so it carries no `@covers`
+ * tags and is listed in DEFAULT_TEST_EXCLUDE_GLOBS.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createStructuralFreshnessChecker, stripFrontmatter } from '@inkeep/open-knowledge-core';
+import { mdManager } from './test-harness';
+
+type PmNodeJson = {
+ type?: string;
+ text?: string;
+ attrs?: Record<string, unknown>;
+ content?: PmNodeJson[];
+};
+
+const CONTENT_DIR = resolve(import.meta.dir, '../../../../docs/content');
+
+function corpusFiles(): string[] {
+ return readdirSync(CONTENT_DIR, { recursive: true, encoding: 'utf8' })
+ .filter((rel) => rel.endsWith('.md') || rel.endsWith('.mdx'))
+ .map((rel) => join(CONTENT_DIR, rel));
+}
+
+/** Parse a doc's body (frontmatter stripped) exactly as the server load path
+ * does — never-throwing, so a stray MDX edge cannot fail the corpus scan. */
+function parseDocBody(path: string): PmNodeJson {
+ const raw = readFileSync(path, 'utf8');
+ const body = stripFrontmatter(raw).body;
+ return mdManager.parseWithFallback(body) as PmNodeJson;
+}
+
+const checker = createStructuralFreshnessChecker({
+ parse: (sourceRaw) => mdManager.parseWithFallback(sourceRaw) as PmNodeJson,
+});
+
+function allComponents(root: PmNodeJson): PmNodeJson[] {
+ const out: PmNodeJson[] = [];
+ const walk = (node: PmNodeJson): void => {
+ if (node.type === 'jsxComponent') out.push(node);
+ if (node.content) for (const c of node.content) walk(c);
+ };
+ walk(root);
+ return out;
+}
+
+describe('structural-freshness derivation — real docs corpus', () => {
+ test('zero false-dirty: no pristine component in docs/content diverges', () => {
+ const files = corpusFiles();
+ expect(files.length).toBeGreaterThan(0);
+
+ let totalComponents = 0;
+ const offenders: Array<{ file: string; component: unknown }> = [];
+ for (const file of files) {
+ const tree = parseDocBody(file);
+ const comps = allComponents(tree);
+ totalComponents += comps.length;
+ for (const comp of comps) {
+ if (checker.isDiverged(comp))
+ offenders.push({ file, component: comp.attrs?.componentName });
+ }
+ }
+
+ // Non-vacuity: the corpus must actually contain the danger space — a corpus
+ // with no components would pass zero-false-dirty vacuously.
+ expect(totalComponents).toBeGreaterThanOrEqual(20);
+ expect(offenders).toEqual([]);
+ });
+
+ test('must-fire: a planted structural mutation in a real doc is caught', () => {
+ // Pick the first corpus doc that carries a component with a text leaf.
+ let target: PmNodeJson | undefined;
+ for (const file of corpusFiles()) {
+ const tree = parseDocBody(file);
+ const comp = allComponents(tree)[0];
+ if (!comp) continue;
+ const mutate = (node: PmNodeJson): boolean => {
+ if (node.text !== undefined && node.text.trim().length > 0) {
+ node.text = `${node.text} [planted divergence]`;
+ return true;
+ }
+ for (const c of node.content ?? []) if (mutate(c)) return true;
+ return false;
+ };
+ if (mutate(comp)) {
+ target = comp;
+ break;
+ }
+ }
+ expect(target).toBeDefined();
+ if (!target) return;
+
+ // The mutation left sourceRaw stale, so the checker must catch the divergence.
+ expect(checker.isDiverged(target)).toBe(true);
+ });
+});
diff --git a/packages/app/tests/stress/jsx-unregistered-backspace-delete.e2e.ts b/packages/app/tests/stress/jsx-unregistered-backspace-delete.e2e.ts
new file mode 100644
index 000000000..57d35da0a
--- /dev/null
+++ b/packages/app/tests/stress/jsx-unregistered-backspace-delete.e2e.ts
@@ -0,0 +1,189 @@
+/**
+ * Unregistered-JSX Backspace/Delete keyboard surface — Playwright E2E.
+ *
+ * The registered-component delete surface (NodeSelected wrapper + native
+ * Backspace/Delete deletes the block; caret-inside-body deletes one char) is
+ * pinned in `jsx-backspace-delete.e2e.ts` against Callout/Accordion. The
+ * UNREGISTERED path had zero native-keyboard coverage: an unregistered
+ * `<UnknownWidget>` auto-converts to a nested-CodeMirror `rawMdxFallback`
+ * box, a different NodeView (`stopEvent: () => true`, `contentEditable=false`
+ * wrapper) whose delete behaviors are its own.
+ *
+ * Two behaviors are pinned here:
+ *
+ * 1. delete-the-wrapper — with the box NodeSelected and DOM focus on the
+ * outer ProseMirror, native Backspace (and Delete) removes the whole
+ * rawMdxFallback block.
+ * 2. delete-to-empty — with DOM focus inside the nested CodeMirror, native
+ * per-char delete empties the raw source; the container survives as a
+ * blank rawMdxFallback (the `jsx-container-boundary-blank` tolerated
+ * state), it is not removed. This routes CM keystrokes through
+ * `forwardUpdate`'s empty-source branch (`tr.delete`), which jsdom
+ * cannot exercise — the app CodeMirror NodeView needs the React portal
+ * infra that only mounts in a real browser.
+ *
+ * Real Chromium is required: collapsed-caret native delete and nested-CM
+ * focus/keystroke routing do not replay deterministically under jsdom (no
+ * layout; the CM NodeView never mounts).
+ *
+ * Not in the CI `test:e2e` subset historically for JSX-editor tests, but this
+ * file IS in the subset so the unregistered browser tier runs under
+ * `check:full:parallel`.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { Page } from '@playwright/test';
+import type { ApiHelpers } from './_helpers';
+import { expect, test } from './_helpers';
+
+interface FallbackNode {
+ type: { name: string };
+ attrs: Record<string, unknown>;
+ textContent: string;
+}
+
+async function setupDoc(page: Page, api: ApiHelpers, markdown: string): Promise<string> {
+ const docName = `unreg-del-${randomUUID().slice(0, 8)}`;
+ await api.createPage(`${docName}.md`);
+ await api.testReset(docName);
+ await api.replaceDoc(docName, markdown);
+ await page.goto(`/#/${docName}`);
+ await page.waitForFunction(() => Boolean(window.__activeProvider?.isSynced), null, {
+ timeout: 15_000,
+ });
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ return docName;
+}
+
+/** Wait for the unregistered component to auto-convert to a rawMdxFallback. */
+async function waitForFallback(page: Page, componentName: string): Promise<void> {
+ await page.waitForFunction(
+ (name) => {
+ const ed = window.__activeEditor;
+ if (!ed) return false;
+ let fallback = false;
+ let residualJsx = false;
+ ed.state.doc.descendants((n: FallbackNode) => {
+ const reason = n.attrs?.reason as string | undefined;
+ const cn = n.attrs?.componentName as string | undefined;
+ if (n.type.name === 'rawMdxFallback' && reason?.includes(name)) fallback = true;
+ if (n.type.name === 'jsxComponent' && cn === name) residualJsx = true;
+ });
+ return fallback && !residualJsx;
+ },
+ componentName,
+ { timeout: 8_000 },
+ );
+}
+
+/** Count rawMdxFallback nodes and read the first one's text content. */
+async function fallbackState(page: Page): Promise<{ count: number; text: string | null }> {
+ return page.evaluate(() => {
+ const ed = window.__activeEditor;
+ if (!ed) return { count: 0, text: null };
+ let count = 0;
+ let text: string | null = null;
+ ed.state.doc.descendants((n: FallbackNode) => {
+ if (n.type.name === 'rawMdxFallback') {
+ count += 1;
+ if (text === null) text = n.textContent;
+ }
+ });
+ return { count, text };
+ });
+}
+
+/** NodeSelect the first rawMdxFallback, then give DOM focus to the outer PM. */
+async function nodeSelectFallbackAndFocusPm(page: Page): Promise<void> {
+ await page.evaluate(() => {
+ const ed = window.__activeEditor;
+ if (!ed) throw new Error('window.__activeEditor not set');
+ let pos = -1;
+ ed.state.doc.descendants((n: FallbackNode, p: number) => {
+ if (pos !== -1) return false;
+ if (n.type.name === 'rawMdxFallback') {
+ pos = p;
+ return false;
+ }
+ return true;
+ });
+ if (pos === -1) throw new Error('rawMdxFallback not found');
+ ed.chain().focus().setNodeSelection(pos).run();
+ });
+ // page.keyboard.press delivers to whatever owns DOM focus; a doc-load +
+ // NodeView mount cycle can leave that elsewhere. Anchor it on the outer PM.
+ await page.evaluate(() => {
+ const pm = document.querySelector(
+ '.ProseMirror:not(.composer-prosemirror)',
+ ) as HTMLElement | null;
+ pm?.focus();
+ });
+}
+
+// ── delete-the-wrapper: NodeSelected unregistered box + native key removes it ─
+
+for (const key of ['Backspace', 'Delete'] as const) {
+ test(`FR-B2 delete-the-wrapper: ${key} removes a NodeSelected unregistered box`, async ({
+ page,
+ api,
+ }) => {
+ await setupDoc(
+ page,
+ api,
+ '<UnknownWidget foo="bar">\n\nchildren remain editable\n\n</UnknownWidget>\n\nafter\n',
+ );
+ await waitForFallback(page, 'UnknownWidget');
+ expect((await fallbackState(page)).count).toBe(1);
+
+ await nodeSelectFallbackAndFocusPm(page);
+ await page.keyboard.press(key);
+
+ // The whole rawMdxFallback block is removed.
+ await expect.poll(() => fallbackState(page).then((s) => s.count), { timeout: 2_000 }).toBe(0);
+ });
+}
+
+// ── delete-to-empty: per-char native delete inside the nested CM empties the
+// source; the container survives as a blank rawMdxFallback ──
+
+test('FR-B2 delete-to-empty: native per-char delete inside the CM empties the box, container survives as blank', async ({
+ page,
+ api,
+}) => {
+ await setupDoc(page, api, '<UnknownWidget foo="bar">\n\nHI\n\n</UnknownWidget>\n\nafter\n');
+ await waitForFallback(page, 'UnknownWidget');
+
+ const before = await fallbackState(page);
+ expect(before.count).toBe(1);
+ const srcLen = before.text?.length ?? 0;
+ expect(srcLen).toBeGreaterThan(0);
+
+ // Focus the nested CodeMirror content directly (a plain click on the box
+ // resolves to a NodeSelection via the focus-change listener, not a CM
+ // caret; JS focus lands DOM focus inside `.cm-content` deterministically).
+ await page.evaluate(() => {
+ const cm = document.querySelector(
+ '.raw-mdx-fallback-wrapper .cm-content',
+ ) as HTMLElement | null;
+ if (!cm) throw new Error('.raw-mdx-fallback-wrapper .cm-content not found');
+ cm.focus();
+ });
+ await expect
+ .poll(() =>
+ page.evaluate(() =>
+ Boolean(document.activeElement?.closest('.raw-mdx-fallback-wrapper .cm-content')),
+ ),
+ )
+ .toBe(true);
+
+ // Delete forward then backward so the whole CM doc empties regardless of the
+ // initial caret position — no reliance on line structure or Mod-chords
+ // (Mod-a select-all leaks focus back to the outer PM). Each native keystroke
+ // routes through CodeMirror → forwardUpdate; the terminal empty source hits
+ // forwardUpdate's `tr.delete` branch.
+ for (let i = 0; i < srcLen + 5; i++) await page.keyboard.press('Delete');
+ for (let i = 0; i < srcLen + 5; i++) await page.keyboard.press('Backspace');
+
+ // The container is preserved (count still 1) but its source is empty.
+ await expect.poll(() => fallbackState(page), { timeout: 2_000 }).toEqual({ count: 1, text: '' });
+});
diff --git a/packages/app/tests/stress/jsx-unregistered-ime-concurrent.e2e.ts b/packages/app/tests/stress/jsx-unregistered-ime-concurrent.e2e.ts
new file mode 100644
index 000000000..05f9375b5
--- /dev/null
+++ b/packages/app/tests/stress/jsx-unregistered-ime-concurrent.e2e.ts
@@ -0,0 +1,287 @@
+/**
+ * IME composition into the nested-CodeMirror raw box under concurrent mutation
+ * — Playwright + CDP `Input.imeSetComposition`.
+ *
+ * An unregistered `<CustomWidget>` auto-converts to a `rawMdxFallback` box: a
+ * live nested CodeMirror editor whose NodeView sets `stopEvent: () => true`, so
+ * ProseMirror never sees keystrokes typed inside it. Real IME composition
+ * (CJK/accents) lands directly on that nested `.cm-content`, and CodeMirror's
+ * DOM path — not ProseMirror's — owns the composition. The seam of interest is
+ * the PM→CM content sync in `RawMdxFallbackCMView.tsx`: when the box's PM
+ * `textContent` changes externally (a remote/Observer-B edit, an agent write),
+ * a `useEffect` dispatches the delta straight into the live CodeMirror view
+ * with no `composing` gate. This exercises what happens when that external
+ * dispatch (or a full remount) lands WHILE the user is mid-composition.
+ *
+ * Requires a real browser + CDP: there is no jsdom path to a live IME
+ * composition, and the app CodeMirror NodeView only mounts under the React
+ * portal infra a real browser provides. `Input.imeSetComposition` +
+ * `Input.insertText` is the only way to drive a genuine composition
+ * (`view.composing === true` at dispatch time) rather than a synthetic
+ * keystroke, which would not set the composing flag and so would not exercise
+ * the seam at all.
+ *
+ * Two concurrent-mutation shapes are exercised, because they reach the box by
+ * different code paths:
+ * - An INCREMENTAL in-place Y.Text edit (what a remote peer's delta becomes
+ * after CRDT sync — the Observer-B path). This preserves the box's element
+ * identity, so the NodeView is NOT remounted and the live PM→CM `useEffect`
+ * fires INTO the composing CodeMirror view. This is the direct seam.
+ * - A full-document agent `replaceDoc`. Its reparse hands the box a new
+ * element, so the whole NodeView remounts mid-composition.
+ *
+ * Both are asserted at real fidelity via the CRDT convergence oracle
+ * (`getText('source')`): the composed glyph must survive exactly once (no drop,
+ * no duplication) and the concurrent write must survive too.
+ *
+ * This file IS in the CI `test:e2e` subset (the unregistered browser tier runs
+ * under `check:full:parallel`).
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { CDPSession, Page } from '@playwright/test';
+import type { ApiHelpers } from './_helpers';
+import { expect, test } from './_helpers';
+
+interface FallbackNode {
+ type: { name: string };
+ attrs: Record<string, unknown>;
+ textContent: string;
+}
+
+// A CJK string chosen so a dropped, duplicated, or truncated composition is
+// unambiguous in the serialized source. The concurrent marker is ASCII and
+// disjoint from the glyph so their presence is independently observable.
+const GLYPH = '日本語';
+const MARKER = 'CONCURRENTZZZ';
+
+async function setupBox(page: Page, api: ApiHelpers): Promise<string> {
+ const docName = `ime-${randomUUID().slice(0, 8)}`;
+ await api.createPage(`${docName}.md`);
+ await api.testReset(docName);
+ await api.replaceDoc(docName, '<CustomWidget>\n\nAAA\n\n</CustomWidget>\n');
+ await page.goto(`/#/${docName}`);
+ await page.waitForFunction(() => Boolean(window.__activeProvider?.isSynced), null, {
+ timeout: 15_000,
+ });
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ await page.waitForFunction(
+ () => {
+ const ed = window.__activeEditor;
+ if (!ed) return false;
+ let ok = false;
+ ed.state.doc.descendants((n: FallbackNode) => {
+ if (
+ n.type.name === 'rawMdxFallback' &&
+ (n.attrs?.reason as string)?.includes('CustomWidget')
+ )
+ ok = true;
+ });
+ return ok;
+ },
+ null,
+ { timeout: 8_000 },
+ );
+ return docName;
+}
+
+async function readYtext(page: Page): Promise<string> {
+ return page.evaluate(
+ () => window.__activeProvider?.document?.getText('source')?.toString() ?? '',
+ );
+}
+
+/** Occurrences of `needle` in `haystack` — 0 = dropped, 1 = clean, ≥2 = duplicated. */
+function occurrences(haystack: string, needle: string): number {
+ return haystack.split(needle).length - 1;
+}
+
+/**
+ * Focus the nested CodeMirror content and place a collapsed caret at the very
+ * end. A plain click resolves to a ProseMirror NodeSelection (the box's
+ * focus-change listener), so the caret is placed via the DOM Selection API,
+ * which CodeMirror's DOMObserver syncs into its own selection state.
+ */
+async function focusCmAtEnd(page: Page): Promise<void> {
+ await page.evaluate(() => {
+ const cm = document.querySelector(
+ '.raw-mdx-fallback-wrapper .cm-content',
+ ) as HTMLElement | null;
+ if (!cm) throw new Error('.raw-mdx-fallback-wrapper .cm-content not found');
+ cm.focus();
+ const range = document.createRange();
+ range.selectNodeContents(cm);
+ range.collapse(false);
+ const sel = window.getSelection();
+ sel?.removeAllRanges();
+ sel?.addRange(range);
+ });
+ await expect
+ .poll(() =>
+ page.evaluate(() =>
+ Boolean(document.activeElement?.closest('.raw-mdx-fallback-wrapper .cm-content')),
+ ),
+ )
+ .toBe(true);
+}
+
+/**
+ * Track composition start/end so a test can prove the nested editable is
+ * genuinely mid-composition when the concurrent write fires — not settled. A
+ * document-level capture listener catches the `compositionstart` CDP
+ * `Input.imeSetComposition` dispatches on the focused `.cm-content` and
+ * survives a NodeView remount. Without this, "the glyph survived once" could
+ * green on a benign path where the composition had already ended before the
+ * external dispatch, so the unguarded PM→CM seam was never actually exercised.
+ */
+async function installCompositionProbe(page: Page): Promise<void> {
+ await page.evaluate(() => {
+ const w = window as unknown as { __imeDepth: number };
+ w.__imeDepth = 0;
+ document.addEventListener('compositionstart', () => (w.__imeDepth += 1), true);
+ document.addEventListener('compositionend', () => (w.__imeDepth -= 1), true);
+ });
+}
+
+/** True while an IME composition is in flight (an unmatched compositionstart). */
+async function composing(page: Page): Promise<boolean> {
+ return page.evaluate(() => (window as unknown as { __imeDepth: number }).__imeDepth > 0);
+}
+
+/** Begin a marked IME composition at the current caret (not yet committed). */
+async function beginComposition(cdp: CDPSession): Promise<void> {
+ await cdp.send('Input.imeSetComposition', {
+ text: GLYPH,
+ selectionStart: GLYPH.length,
+ selectionEnd: GLYPH.length,
+ });
+}
+
+/** Commit the in-flight composition (fires compositionend). */
+async function commitComposition(cdp: CDPSession): Promise<void> {
+ await cdp.send('Input.insertText', { text: GLYPH });
+}
+
+test('FR-B3 baseline: CDP IME composes CJK into the nested raw box (harness + observable control)', async ({
+ page,
+ api,
+}) => {
+ await setupBox(page, api);
+ await focusCmAtEnd(page);
+ await installCompositionProbe(page);
+ const cdp = await page.context().newCDPSession(page);
+ try {
+ await beginComposition(cdp);
+ // Non-vacuity: the harness drives a genuine composition (an unmatched
+ // compositionstart is in flight), not an instant insert.
+ expect(await composing(page)).toBe(true);
+ await commitComposition(cdp);
+
+ await expect.poll(() => readYtext(page)).toContain(GLYPH);
+ const yt = await readYtext(page);
+ // Harness proof: the composition lands exactly once.
+ expect(occurrences(yt, GLYPH)).toBe(1);
+ // Control: with no concurrent write, the marker is absent — so the
+ // "marker survives" assertion in the concurrent arms below is reading the
+ // real write, not a string that is always present.
+ expect(yt.includes(MARKER)).toBe(false);
+ } finally {
+ await cdp.detach();
+ }
+});
+
+test('FR-B3 Observer-B edit mid-composition: box stays mounted (live PM→CM seam), no glyph drop/dup, concurrent survives', async ({
+ page,
+ api,
+}) => {
+ await setupBox(page, api);
+
+ // Tag the mounted CodeMirror element. If the box remounts, this element (and
+ // its tag) is replaced; if it survives, the live [textContent] useEffect —
+ // the unguarded PM→CM dispatch — is the path that ran.
+ await page.evaluate(() => {
+ const cm = document.querySelector('.raw-mdx-fallback-wrapper .cm-content');
+ if (cm) (cm as HTMLElement).dataset.imeProbe = 'MOUNTED';
+ });
+
+ await focusCmAtEnd(page);
+ await installCompositionProbe(page);
+ const cdp = await page.context().newCDPSession(page);
+ try {
+ await beginComposition(cdp);
+ // Non-vacuity gate: the composition is in flight, so the incremental Y.Text
+ // edit below dispatches through the unguarded PM→CM useEffect INTO a
+ // composing view — the exact seam. Without this the arm could green on a
+ // benign already-settled composition.
+ expect(await composing(page)).toBe(true);
+
+ // Incremental in-place Y.Text edit adjacent to the composition anchor —
+ // what a remote peer's delta becomes after CRDT sync. Inserting right
+ // before the closing tag keeps the box a rawMdxFallback while changing its
+ // source, driving the Observer-B → node.textContent → live useEffect path.
+ await page.evaluate((mark) => {
+ const yt = window.__activeProvider?.document?.getText('source');
+ if (!yt) throw new Error('no Y.Text');
+ yt.insert(yt.toString().indexOf('</CustomWidget>'), `${mark} `);
+ }, MARKER);
+ await page.waitForFunction(
+ (m) => window.__activeProvider?.document?.getText('source')?.toString()?.includes(m),
+ MARKER,
+ { timeout: 5_000 },
+ );
+
+ // The box stayed mounted through the external edit — the dispatch went into
+ // the live composing view, not a fresh mount — and the composition is still
+ // in flight, so the dispatch genuinely landed mid-composition.
+ const tag = await page.evaluate(
+ () =>
+ (document.querySelector('.raw-mdx-fallback-wrapper .cm-content') as HTMLElement | null)
+ ?.dataset.imeProbe ?? null,
+ );
+ expect(tag).toBe('MOUNTED');
+ expect(await composing(page)).toBe(true);
+
+ await commitComposition(cdp);
+
+ await expect.poll(() => readYtext(page)).toContain(GLYPH);
+ const yt = await readYtext(page);
+ expect(occurrences(yt, GLYPH)).toBe(1); // no drop, no duplication
+ expect(yt.includes(MARKER)).toBe(true); // the concurrent write survives
+ } finally {
+ await cdp.detach();
+ }
+});
+
+test('FR-B3 agent write mid-composition: no glyph drop/dup, concurrent survives (box remounts)', async ({
+ page,
+ api,
+}) => {
+ const docName = await setupBox(page, api);
+ await focusCmAtEnd(page);
+ await installCompositionProbe(page);
+ const cdp = await page.context().newCDPSession(page);
+ try {
+ await beginComposition(cdp);
+ // Non-vacuity: the agent write below lands while a composition is in flight
+ // (the remount happens mid-composition, not after it settled).
+ expect(await composing(page)).toBe(true);
+
+ // A full-document agent write mid-composition. Its reparse hands the box a
+ // new element (remount), a different path from the incremental edit above.
+ await api.replaceDoc(docName, `<CustomWidget>\n\nAAA ${MARKER}\n\n</CustomWidget>\n`);
+ await page.waitForFunction(
+ (m) => window.__activeProvider?.document?.getText('source')?.toString()?.includes(m),
+ MARKER,
+ { timeout: 10_000 },
+ );
+
+ await commitComposition(cdp);
+
+ await expect.poll(() => readYtext(page)).toContain(GLYPH);
+ const yt = await readYtext(page);
+ expect(occurrences(yt, GLYPH)).toBe(1); // no drop, no duplication
+ expect(yt.includes(MARKER)).toBe(true); // the concurrent write survives
+ } finally {
+ await cdp.detach();
+ }
+});
diff --git a/packages/app/tests/stress/keystroke-cadence-danger-space.e2e.ts b/packages/app/tests/stress/keystroke-cadence-danger-space.e2e.ts
new file mode 100644
index 000000000..bb490d621
--- /dev/null
+++ b/packages/app/tests/stress/keystroke-cadence-danger-space.e2e.ts
@@ -0,0 +1,184 @@
+/**
+ * Keystroke-cadence browser probe — real per-keystroke typing INTO a registered
+ * Callout interior in WYSIWYG.
+ *
+ * The integration tier drives the Observer-A producer guard and the structural
+ * freshness derivation with a text-leaf wire model; this exercises the same
+ * per-drain checks through the REAL editor path — ProseMirror input, the
+ * Callout's NodeViewContent hole, the client SourceDirtyObserver flip, and a
+ * live caret — one character at a time.
+ *
+ * This worker's dev server runs in the producer guard's loud (throw) posture
+ * (OK_RETHROW_BRIDGE_LOSS=1, dedicated worker via workerServerEnv). A guard
+ * false-fire on any keystroke aborts that server drain before the Y.Text write,
+ * so the character never echoes back to the client: the per-keystroke assertion
+ * that the growing interior text reached the persisted source then fails AT the
+ * keystroke that fired, before a later keystroke's full re-serialize can heal it.
+ *
+ * Oracle: the typed text survives contiguously, the container tags stay singular
+ * and un-re-indented, the registered prop survives, and no critical console /
+ * page error surfaces across the burst.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { Page } from '@playwright/test';
+import {
+ expect,
+ filterCriticalErrors,
+ type LogEntry,
+ test,
+ waitForActiveProviderSynced as waitForProvider,
+} from './_helpers';
+
+// Dedicated worker in the producer guard's throw posture: a false-fire surfaces
+// as an aborted drain (lost keystroke), not a silent packaged-posture log.
+test.use({ workerServerEnv: { OK_RETHROW_BRIDGE_LOSS: '1' } });
+
+const CALLOUT = ['<Callout type="info">', '', 'Note:', '', '</Callout>', ''].join('\n');
+const INDENTED_CALLOUT = /\n[ \t]+<\/?Callout\b/;
+
+const readSource = (page: Page): Promise<string> =>
+ page.evaluate(() => window.__activeProvider?.document?.getText('source')?.toString() ?? '');
+
+/** Place the caret at the end of the Callout's editable interior by clicking the
+ * rendered interior text (the NodeViewContent hole), then End. Clicking the text
+ * places a TextSelection inside the paragraph; a position-math selection near the
+ * jsxComponent boundary snaps to a NodeSelection on the wrapper instead. */
+async function placeCaretInCalloutInterior(page: Page): Promise<void> {
+ await page
+ .locator('.ProseMirror:not(.composer-prosemirror)')
+ .getByText('Note:', { exact: false })
+ .first()
+ .click();
+ await page.keyboard.press('End');
+ // Confirm the caret is a text cursor inside the interior, not a NodeSelection
+ // on the Callout wrapper (which would make the next keystrokes replace/miss).
+ await page.waitForFunction(
+ () => {
+ const sel = window.__activeEditor?.state.selection;
+ return Boolean(sel?.empty && sel.$from.parent.type.name === 'paragraph');
+ },
+ null,
+ { timeout: 5_000 },
+ );
+}
+
+/** Wait until the persisted source contains `needle` and its length has settled
+ * (the Observer-A write-back finished). Condition-based, with a fail-fast tick
+ * ceiling — `page.waitForTimeout` is banned by the e2e STOP rule. */
+async function settleSource(page: Page, needle: string): Promise<void> {
+ await page.evaluate(
+ (n) =>
+ new Promise<void>((resolve, reject) => {
+ let last = -1;
+ let stableTicks = 0;
+ let totalTicks = 0;
+ const POLL_MS = 100;
+ const REQUIRED_STABLE_TICKS = 3;
+ const MAX_TICKS = 80; // ~8s ceiling — fail fast, never run to Playwright's default
+ const tick = (): void => {
+ totalTicks += 1;
+ if (totalTicks > MAX_TICKS) {
+ reject(
+ new Error(
+ `settleSource: ${JSON.stringify(n)} did not land + settle within ${MAX_TICKS * POLL_MS}ms — ` +
+ `a producer-guard abort would strand the keystroke here`,
+ ),
+ );
+ return;
+ }
+ const s = window.__activeProvider?.document?.getText('source')?.toString() ?? '';
+ if (s.includes(n) && s.length === last) {
+ stableTicks += 1;
+ if (stableTicks >= REQUIRED_STABLE_TICKS) {
+ resolve();
+ return;
+ }
+ } else {
+ stableTicks = 0;
+ last = s.length;
+ }
+ setTimeout(tick, POLL_MS);
+ };
+ setTimeout(tick, POLL_MS);
+ }),
+ needle,
+ );
+}
+
+let docName: string;
+let errors: LogEntry[];
+
+test.beforeEach(async ({ page, api }) => {
+ errors = [];
+ page.on('console', (msg) => {
+ if (msg.type() === 'error') errors.push({ type: 'error', text: msg.text() });
+ });
+ page.on('pageerror', (err) => {
+ errors.push({ type: 'uncaught', text: err.message });
+ });
+
+ docName = `keystroke-danger-${randomUUID().slice(0, 8)}`;
+ await api.createPage(`${docName}.md`);
+ await page.goto(`/#/${docName}`);
+ await waitForProvider(page);
+ await page.waitForSelector('.ProseMirror:not(.composer-prosemirror)');
+ await api.replaceDoc(docName, CALLOUT);
+ // Wait for the Callout to render and the live editor handle to be exposed.
+ await page.waitForFunction(
+ () => Boolean(window.__activeEditor) && (document.body.textContent ?? '').includes('Note:'),
+ null,
+ { timeout: 10_000 },
+ );
+});
+
+test.describe('keystroke-cadence browser probe — registered Callout interior (throw posture)', () => {
+ test('per-keystroke typing into a Callout interior lands contiguous, guard never aborts a drain', async ({
+ page,
+ }) => {
+ await placeCaretInCalloutInterior(page);
+
+ // Type character by character; settle + assert after EACH so a transient
+ // guard abort is caught at the keystroke it fires on (before a later
+ // keystroke's full re-serialize can heal it). Non-whitespace chars keep the
+ // survival substring exact (no markdown whitespace normalization ambiguity).
+ const typed = 'ALERT42';
+ let expected = 'Note:';
+ for (const ch of typed) {
+ await page.keyboard.type(ch, { delay: 55 });
+ expected += ch;
+ await settleSource(page, expected);
+ const src = await readSource(page);
+ expect(src).toContain(expected); // contiguous — the keystroke landed
+ expect((src.match(/<Callout\b/g) ?? []).length).toBe(1);
+ expect((src.match(/<\/Callout>/g) ?? []).length).toBe(1);
+ expect(src).not.toMatch(INDENTED_CALLOUT); // no Observer-A re-indent write-back
+ }
+
+ const finalSrc = await readSource(page);
+ expect(finalSrc).toContain('Note:ALERT42');
+ expect(finalSrc).toContain('type="info"'); // registered prop survived
+ expect(filterCriticalErrors(errors)).toEqual([]);
+ });
+
+ test('a second burst after the first keeps the interior intact, tags singular', async ({
+ page,
+ }) => {
+ await placeCaretInCalloutInterior(page);
+ await page.keyboard.type('ONE', { delay: 55 });
+ await settleSource(page, 'Note:ONE');
+
+ // Re-anchor the caret (the node view may have re-rendered) and type again.
+ await placeCaretInCalloutInterior(page);
+ await page.keyboard.type('TWO', { delay: 55 });
+ await settleSource(page, 'Note:ONETWO');
+
+ const src = await readSource(page);
+ expect(src).toContain('Note:ONETWO');
+ expect((src.match(/<Callout\b/g) ?? []).length).toBe(1);
+ expect((src.match(/<\/Callout>/g) ?? []).length).toBe(1);
+ expect(src).not.toMatch(INDENTED_CALLOUT);
+ expect(src).toContain('type="info"');
+ expect(filterCriticalErrors(errors)).toEqual([]);
+ });
+});
diff --git a/packages/app/tests/stress/qa-canary-authoring-both-modes.e2e.ts b/packages/app/tests/stress/qa-canary-authoring-both-modes.e2e.ts
new file mode 100644
index 000000000..d59820f30
--- /dev/null
+++ b/packages/app/tests/stress/qa-canary-authoring-both-modes.e2e.ts
@@ -0,0 +1,247 @@
+/** QA canary — authoring nested <Steps> across BOTH editor modes, from scratch,
+ * keystroke by keystroke through the transient-invalid states.
+ *
+ * As-built model: <Steps>/<Step> are unregistered (componentMap) -> they render
+ * via the wildcard editable raw-source view even when VALID. There is no client
+ * "freeze": server parseWithFallback never throws, so an invalid span renders as
+ * rawMdxFallback (client cross-CRDT write paths are deleted, precedent #14).
+ * Transient state = rawMdxFallback, NOT a freeze.
+ *
+ * Covers all three real typing surfaces: source CM, WYSIWYG ProseMirror (prose
+ * around Steps), WYSIWYG wildcard CM (the Step itself), plus a mode-flip mid-build.
+ * Includes a JITTER probe: typing in clean prose must not flash the Steps render.
+ *
+ * ORACLE NOTE: CM source-mode auto-indents JSX tags on Enter while authoring. The
+ * indented shape is a stable, lossless serialize fixed point, and the bridge never
+ * re-indents (3-layer isolation). Assertions therefore check STRUCTURE + CONTENT
+ * INTEGRITY, never flush-left tags, for authored-from-scratch content; only SEEDED
+ * Steps assert flush-left.
+ */
+
+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' });
+const INDENTED_STEP = /\n[ \t]+<\/?Step\b/;
+// A GLOBAL re-indent write-back (the bug this suite guards) would indent the
+// OUTER <Steps> container too. The wildcard raw-source box's own commit path may
+// locally re-emit the inner <Step> with standard nested-JSX indentation (lossless,
+// stable fixed point) — that is not the corruption class. Guard the outer tag.
+const INDENTED_STEPS = /\n[ \t]+<\/?Steps\b/;
+
+const readSource = (page: Page) =>
+ page.evaluate(() => window.__activeProvider?.document?.getText('source')?.toString() ?? '');
+
+async function structure(page: Page) {
+ return page.evaluate(() => {
+ const pm = document.querySelector('.ProseMirror');
+ return {
+ h2: pm?.querySelectorAll('h2').length ?? 0,
+ p: pm?.querySelectorAll('p').length ?? 0,
+ rawFallback: document.querySelectorAll('[data-raw-mdx-fallback]').length,
+ wildcardCm: document.querySelectorAll('.cm-editor').length,
+ };
+ });
+}
+
+let docName: string;
+test.beforeEach(async ({ page, api }) => {
+ docName = `qa-author-${randomUUID().slice(0, 8)}`;
+ await api.createPage(`${docName}.md`);
+ await page.goto(`/#/${docName}`);
+ await waitForProvider(page);
+ await page.waitForSelector('.ProseMirror');
+});
+
+// KNOWN PRE-EXISTING CORRUPTION (quarantined tripwires): three of these
+// canaries detect a real source-typing duplication/re-indent race in the
+// authoritative Y.Text that PRE-DATES this suite — a 2026-07 forensic bisect
+// reproduced the same failures at ~30-50% per fully-contended run on pure
+// origin/main with these canary files copied in (8 canary failures across 3
+// runs), on this branch with `deriveStructuralFreshness` verifiably OFF in
+// the built dist, and on this branch as-shipped. Only full-suite CPU
+// contention trips it; single-file runs pass. The corruption is real
+// (duplicated bytes read from `provider.document.getText('source')`, never
+// the DOM). The affected tests are `test.fixme` so a pre-existing production
+// bug does not lottery every PR's e2e lane; they are the ORACLE for the
+// follow-up fix and must be un-fixme'd by it. The full forensic evidence
+// (run matrix, mechanism map, reproduction procedure) lives in the
+// quarantining commit's message and its PR discussion.
+test.describe('QA canary — authoring <Steps> across both modes', () => {
+ // T1 — SOURCE: author the whole nested <Steps> from EMPTY, char-by-char, through
+ // the unclosed-container transient, landing valid. Surrounding heading preserved.
+ test.fixme('source: author nested <Steps> from empty; no whole-doc collapse, recovers to valid', async ({
+ page,
+ api,
+ }) => {
+ await api.replaceDoc(docName, '## Guide\n\nIntro paragraph.\n');
+ await page.waitForFunction(
+ () => document.querySelector('.ProseMirror')?.textContent?.includes('Guide'),
+ null,
+ { timeout: 10_000 },
+ );
+ await sourceToggle(page).click();
+ await page.waitForSelector('.cm-content');
+ await page.locator('.cm-content:visible').click();
+ await page.keyboard.press('ControlOrMeta+End');
+ // Author the construct character-by-character (Enter via \n, real per-key delay).
+ await page.keyboard.type('\n<Steps>\n\n<Step>\n\nStep one body.\n\n', { delay: 12 });
+ // PAUSE mid-build: <Steps> + <Step> both unclosed — transient invalid.
+ const mid = await readSource(page);
+ expect(mid).toContain('<Steps>');
+ expect(mid).toContain('Step one body.'); // live source shows what was typed
+ // Finish closing both tags.
+ await page.keyboard.type('</Step>\n\n</Steps>\n', { delay: 12 });
+ await page.waitForFunction(
+ () => window.__activeProvider?.document?.getText('source')?.toString()?.includes('</Steps>'),
+ null,
+ { timeout: 10_000 },
+ );
+ const src = await readSource(page);
+ expect(src).toContain('## Guide'); // surrounding heading NOT collapsed/lost
+ expect((src.match(/Step one body\./g) ?? []).length).toBe(1); // body present, once (no dup)
+ expect((src.match(/<Steps>/g) ?? []).length).toBe(1);
+ expect((src.match(/<\/Steps>/g) ?? []).length).toBe(1);
+ expect((src.match(/<Step>/g) ?? []).length).toBe(1);
+ // NOTE: CM source-mode auto-indents tags on Enter while authoring nested JSX.
+ // The indented shape is a stable serialize fixed point (parses as jsxComponent,
+ // lossless) and the bridge never re-indents. So we assert structure + content
+ // integrity, NOT flush-left tags — asserting flush-left here would be a false
+ // oracle (indentation = CM UX, not corruption).
+ });
+
+ // T2 — WYSIWYG ProseMirror + JITTER PROBE: with a valid <Steps> + surrounding
+ // prose, type a burst into a sibling paragraph; the Steps render must NOT flash
+ // (fallback/CM count stable across the burst).
+ test.fixme('wysiwyg: typing in prose adjacent to <Steps> does not flash the Steps render (jitter)', async ({
+ page,
+ api,
+ }) => {
+ await api.replaceDoc(
+ docName,
+ '## Heading\n\nEditable paragraph.\n\n<Steps>\n\n<Step>\n\nStep body.\n\n</Step>\n\n</Steps>\n\nTrailing paragraph.\n',
+ );
+ await page.waitForFunction(
+ () => document.querySelector('.ProseMirror')?.textContent?.includes('Editable paragraph'),
+ null,
+ { timeout: 10_000 },
+ );
+ // Ensure WYSIWYG (visual) mode.
+ await visualToggle(page).click();
+ await page.waitForSelector('.ProseMirror:visible');
+ const before = await structure(page);
+ // Type into the editable paragraph (ProseMirror), char-by-char, sampling the
+ // Steps render stability after each key.
+ await page.getByText('Editable paragraph.', { exact: false }).first().click();
+ await page.keyboard.press('End');
+ let maxFallback = before.rawFallback;
+ let minWildcard = before.wildcardCm;
+ for (const ch of 'NEWTEXT') {
+ await page.keyboard.type(ch, { delay: 60 });
+ const s = await structure(page);
+ maxFallback = Math.max(maxFallback, s.rawFallback);
+ minWildcard = Math.min(minWildcard, s.wildcardCm);
+ }
+ const after = await structure(page);
+ // Jitter oracle: the Steps wildcard-CM count never dropped (no unmount/flash)
+ // and no NEW parse-error rawMdxFallback chrome appeared mid-burst.
+ expect(minWildcard).toBe(before.wildcardCm); // Steps render never unmounted mid-type
+ expect(maxFallback).toBe(before.rawFallback); // no parse-error fallback flashed in
+ expect(after.h2).toBe(before.h2); // surrounding heading stable
+ const src = await readSource(page);
+ expect(src).toContain('Editable paragraph.NEWTEXT'); // edit landed contiguous
+ expect((src.match(/<Step>/g) ?? []).length).toBe(1); // Steps intact
+ expect(src).not.toMatch(INDENTED_STEP); // SEEDED Steps stay flush-left (no bridge re-indent)
+ });
+
+ // T3 — WYSIWYG wildcard CM: edit INSIDE the Step's raw-source box (the only
+ // Step-editing surface in WYSIWYG), then assert it persists with no corruption.
+ test('wysiwyg: editing inside the Step wildcard raw-source box persists, no corruption', async ({
+ page,
+ api,
+ }) => {
+ const seed = '## Heading\n\n<Steps>\n\n<Step>\n\nOriginal step body.\n\n</Step>\n\n</Steps>\n';
+ await api.replaceDoc(docName, seed);
+ await page.waitForFunction(
+ () => document.querySelector('.ProseMirror')?.textContent?.includes('Original step body'),
+ null,
+ { timeout: 10_000 },
+ );
+ await visualToggle(page).click();
+ await page.waitForSelector('.ProseMirror:visible');
+ // The Step renders via the wildcard raw-source CM inside WYSIWYG.
+ await page.getByText('Original step body.', { exact: false }).first().click();
+ await page.keyboard.press('End');
+ await page.keyboard.type(' EDITED', { delay: 40 });
+ // Blur to trigger any upgrade/commit, then read the source bytes.
+ await page.keyboard.press('Escape');
+ await page.waitForFunction(
+ () => window.__activeProvider?.document?.getText('source')?.toString()?.includes('EDITED'),
+ null,
+ { timeout: 10_000 },
+ );
+ const src = await readSource(page);
+ expect(src).toContain('Original step body. EDITED'); // edit landed, content preserved
+ expect((src.match(/<Step>/g) ?? []).length).toBe(1); // no duplication
+ expect((src.match(/<Steps>/g) ?? []).length).toBe(1);
+ expect(src).toContain('## Heading'); // surrounding preserved
+ // Committing the wildcard raw-source box re-serializes the Step subtree; the MDX
+ // serializer emits nested-JSX children with standard 2-space indentation. That is
+ // a lossless, stable serialize fixed point (content + structure round-trip
+ // identically) — not corruption. The corruption to reject is a GLOBAL re-indent
+ // write-back (the OUTER container gaining indentation) and content growth/dup:
+ expect(src).not.toMatch(INDENTED_STEPS); // no write-back re-indent of the outer <Steps>
+ expect(src.length).toBeLessThan(seed.length + 32); // no growth / duplication
+ });
+
+ // T4 — MODE-FLIP mid-build: type a partial (unclosed) <Steps> in source, flip to
+ // WYSIWYG while broken, flip back, finish. No collapse, no corruption, recovers.
+ test.fixme('mode-flip mid-build: unclosed <Steps> survives a WYSIWYG round-trip and recovers', async ({
+ page,
+ api,
+ }) => {
+ await api.replaceDoc(docName, '## Title\n\nBefore.\n');
+ await page.waitForFunction(
+ () => document.querySelector('.ProseMirror')?.textContent?.includes('Title'),
+ null,
+ { timeout: 10_000 },
+ );
+ await sourceToggle(page).click();
+ await page.waitForSelector('.cm-content');
+ await page.locator('.cm-content:visible').click();
+ await page.keyboard.press('ControlOrMeta+End');
+ await page.keyboard.type('\n<Steps>\n\n<Step>\n\nMid build.\n', { delay: 12 }); // UNCLOSED
+ await page.waitForFunction(
+ () =>
+ window.__activeProvider?.document?.getText('source')?.toString()?.includes('Mid build.'),
+ null,
+ { timeout: 10_000 },
+ );
+ // Flip to WYSIWYG while the JSX is unclosed — must not collapse the doc.
+ await visualToggle(page).click();
+ await page.waitForSelector('.ProseMirror:visible');
+ const broken = await readSource(page);
+ expect(broken).toContain('## Title'); // surrounding heading survived the flip
+ expect(broken).toContain('Mid build.'); // typed content survived
+ // Flip back to source and finish closing the tags.
+ await sourceToggle(page).click();
+ await page.waitForSelector('.cm-content');
+ await page.locator('.cm-content:visible').click();
+ await page.keyboard.press('ControlOrMeta+End');
+ await page.keyboard.type('\n</Step>\n\n</Steps>\n', { delay: 12 });
+ await page.waitForFunction(
+ () => window.__activeProvider?.document?.getText('source')?.toString()?.includes('</Steps>'),
+ null,
+ { timeout: 10_000 },
+ );
+ const src = await readSource(page);
+ expect(src).toContain('## Title'); // surrounding heading survived flip + finish
+ expect((src.match(/Mid build\./g) ?? []).length).toBe(1); // content present, once
+ expect((src.match(/<Steps>/g) ?? []).length).toBe(1);
+ expect((src.match(/<\/Steps>/g) ?? []).length).toBe(1);
+ expect((src.match(/<Step>/g) ?? []).length).toBe(1);
+ // CM auto-indent (stable, lossless fixed point) — assert integrity, not flush-left.
+ });
+});
diff --git a/packages/app/tests/stress/qa-canary-live-typing.e2e.ts b/packages/app/tests/stress/qa-canary-live-typing.e2e.ts
new file mode 100644
index 000000000..12c3b55da
--- /dev/null
+++ b/packages/app/tests/stress/qa-canary-live-typing.e2e.ts
@@ -0,0 +1,200 @@
+/** QA canary — browser tier: real per-keystroke LIVE typing on <Steps> in source
+ * mode (the residual the integration rung cannot reach). Exercises per-char Y.Text
+ * deltas against the live bridge WITH the hidden-but-mounted WYSIWYG binding active
+ * — would an Observer-A write-back re-indent the doc and yank the caret mid-burst?
+ *
+ * Cursor-jump oracle = TYPED-BURST CONTIGUITY: a 5-char burst typed character by
+ * character must land as one contiguous run. If the caret jumps mid-burst (a
+ * write-back remap), the run fragments — caught without reaching into CM internals.
+ *
+ * Per-worker isolated server + tmpdir (playwright.config has no webServer) — does
+ * not touch a dev server on 5173.
+ */
+
+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 INDENTED_STEP = /\n[ \t]+<\/?Step\b/;
+
+const STEPS = [
+ '<Steps>',
+ '',
+ '<Step>',
+ '',
+ 'Content one.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'Content two.',
+ '',
+ '</Step>',
+ '',
+ '<Step>',
+ '',
+ 'Content three.',
+ '',
+ '</Step>',
+ '',
+ '</Steps>',
+ '',
+].join('\n');
+
+const readSource = (page: Page) =>
+ page.evaluate(() => window.__activeProvider?.document?.getText('source')?.toString() ?? '');
+
+// Wait for the burst to land AND the source length to settle (Observer write-back
+// finished). Polls inside the page with setTimeout — page.waitForTimeout is banned
+// by the e2e STOP rule as a fixed-delay anti-flake smell; a condition-based poll
+// with a fail-fast tick ceiling is the sanctioned replacement.
+async function settleSource(page: Page, mustInclude: string) {
+ await page.evaluate(
+ (needle) =>
+ new Promise<void>((resolve, reject) => {
+ let last = -1;
+ let stableTicks = 0;
+ let totalTicks = 0;
+ const POLL_MS = 100;
+ const REQUIRED_STABLE_TICKS = 3;
+ const MAX_TICKS = 100; // ~10s ceiling — fail fast, don't run to Playwright's 120s
+ const tick = () => {
+ totalTicks += 1;
+ if (totalTicks > MAX_TICKS) {
+ reject(
+ new Error(
+ `settleSource: "${needle}" did not land + settle within ${MAX_TICKS * POLL_MS}ms`,
+ ),
+ );
+ return;
+ }
+ const s = window.__activeProvider?.document?.getText('source')?.toString() ?? '';
+ if (s.includes(needle) && s.length === last) {
+ stableTicks += 1;
+ if (stableTicks >= REQUIRED_STABLE_TICKS) {
+ resolve();
+ return;
+ }
+ } else {
+ stableTicks = 0;
+ last = s.length;
+ }
+ setTimeout(tick, POLL_MS);
+ };
+ setTimeout(tick, POLL_MS);
+ }),
+ mustInclude,
+ );
+}
+
+let docName: string;
+test.beforeEach(async ({ page, api }) => {
+ docName = `qa-livetype-${randomUUID().slice(0, 8)}`;
+ await api.createPage(`${docName}.md`);
+ await page.goto(`/#/${docName}`);
+ await waitForProvider(page);
+ await page.waitForSelector('.ProseMirror');
+ await api.replaceDoc(docName, STEPS);
+ await page.waitForFunction(
+ () => document.querySelector('.ProseMirror')?.textContent?.includes('Content one'),
+ null,
+ { timeout: 10_000 },
+ );
+});
+
+// KNOWN PRE-EXISTING CORRUPTION (quarantined tripwire): B1 below detects a
+// real source-typing race in the authoritative Y.Text that PRE-DATES this
+// suite (reproduced on pure origin/main under full-suite contention — see
+// the forensic note atop qa-canary-authoring-both-modes.e2e.ts; the full
+// evidence lives in the quarantining commit's message and its PR
+// discussion). It is `test.fixme` so the pre-existing bug does not lottery
+// every PR's e2e lane; the follow-up fix must un-fixme it.
+test.describe('QA canary — live per-keystroke typing on <Steps> (browser, source mode)', () => {
+ // B1 — live burst inside a Step body: caret stays put (burst contiguous), no re-indent.
+ test.fixme('typing a burst into a Step body lands contiguous, no re-indent, no growth', async ({
+ page,
+ }) => {
+ await sourceToggle(page).click();
+ await page.waitForSelector('.cm-content');
+ await page
+ .locator('.cm-content:visible')
+ .getByText('Content one.', { exact: false })
+ .first()
+ .click();
+ await page.keyboard.press('End'); // end of the "Content one." line
+ await page.keyboard.type('ZZZZZ', { delay: 45 }); // per-char live burst
+ await settleSource(page, 'ZZZZZ');
+
+ const src = await readSource(page);
+ expect(src).toContain('Content one.ZZZZZ'); // contiguous => caret did NOT jump mid-burst
+ expect(src).not.toMatch(INDENTED_STEP); // no Observer-A re-indent write-back
+ expect((src.match(/<Step>/g) ?? []).length).toBe(3);
+ expect((src.match(/<Steps>/g) ?? []).length).toBe(1);
+ expect(src.length).toBeLessThan(STEPS.length + 32); // no growth/duplication
+ });
+
+ // B2 — live burst at a body-start boundary (right after the <Step> open tag).
+ test('typing a burst at a Step body-start boundary lands contiguous, tags intact', async ({
+ page,
+ }) => {
+ await sourceToggle(page).click();
+ await page.waitForSelector('.cm-content');
+ await page
+ .locator('.cm-content:visible')
+ .getByText('Content two.', { exact: false })
+ .first()
+ .click();
+ await page.keyboard.press('Home'); // start of the "Content two." line
+ await page.keyboard.type('QQQQQ', { delay: 45 });
+ await settleSource(page, 'QQQQQ');
+
+ const src = await readSource(page);
+ expect(src).toContain('QQQQQContent two.'); // contiguous at the boundary
+ expect(src).not.toMatch(INDENTED_STEP);
+ expect((src.match(/<Step>/g) ?? []).length).toBe(3);
+ expect(src.length).toBeLessThan(STEPS.length + 32);
+ });
+
+ // B3 — in-browser reopen: edit, navigate away + back (client recycle + re-sync),
+ // assert the edit survived with no corruption.
+ test('in-browser reopen after a live edit preserves bytes, no corruption', async ({
+ page,
+ api,
+ }) => {
+ await sourceToggle(page).click();
+ await page.waitForSelector('.cm-content');
+ await page
+ .locator('.cm-content:visible')
+ .getByText('Content three.', { exact: false })
+ .first()
+ .click();
+ await page.keyboard.press('End');
+ await page.keyboard.type('RRRRR', { delay: 45 });
+ await settleSource(page, 'RRRRR');
+
+ // Navigate away to a different doc, then back — evicts the editor + re-syncs.
+ const other = `qa-other-${randomUUID().slice(0, 8)}`;
+ await api.createPage(`${other}.md`);
+ await page.goto(`/#/${other}`);
+ await waitForProvider(page);
+ // Editor mode persists (localStorage 'ok-editor-mode-v1') — after the source
+ // toggle above, the fresh doc opens in SOURCE mode, so .ProseMirror is hidden.
+ // Wait for the source surface, not WYSIWYG.
+ await page.waitForSelector('.cm-content');
+ await page.goto(`/#/${docName}`);
+ await waitForProvider(page);
+ await page.waitForFunction(
+ () => window.__activeProvider?.document?.getText('source')?.toString()?.includes('RRRRR'),
+ null,
+ { timeout: 10_000 },
+ );
+
+ const src = await readSource(page);
+ expect(src).toContain('Content three.RRRRR'); // edit survived the reopen, contiguous
+ expect(src).not.toMatch(INDENTED_STEP);
+ expect((src.match(/<Step>/g) ?? []).length).toBe(3);
+ expect(src.length).toBeLessThan(STEPS.length + 32);
+ });
+});
diff --git a/packages/core/src/bridge/index.ts b/packages/core/src/bridge/index.ts
index 1606e7531..9ff048816 100644
--- a/packages/core/src/bridge/index.ts
+++ b/packages/core/src/bridge/index.ts
@@ -71,7 +71,22 @@ export {
isParseEquivalentBridge,
PARSE_EQUIVALENCE_TOLERANCE,
} from './parse-equivalence.ts';
+export {
+ type ComparePmStructuralOptions,
+ comparePmStructural,
+ compareRoundTripStructural,
+ type PmStructuralNode,
+ type StructuralDegradeLabel,
+ type StructuralDivergenceReason,
+ type StructuralEquivalenceResult,
+ structuralDivergence,
+} from './pm-structural-equivalence.ts';
export { defaultScheduler, type Scheduler } from './scheduler.ts';
+export {
+ createStructuralFreshnessChecker,
+ type StructuralFreshnessChecker,
+ type StructuralFreshnessCheckerOptions,
+} from './structural-freshness.ts';
export {
classifySeverity,
emitToleranceFire,
diff --git a/packages/core/src/bridge/parse-equivalence.ts b/packages/core/src/bridge/parse-equivalence.ts
index 46cb6a6d8..9e5ad7dd4 100644
--- a/packages/core/src/bridge/parse-equivalence.ts
+++ b/packages/core/src/bridge/parse-equivalence.ts
@@ -1,5 +1,6 @@
import { stripFrontmatter } from '../extensions/frontmatter.ts';
import type { BridgeToleranceClass } from './normalize.ts';
+import { isSubsequence } from './subsequence.ts';
export const PARSE_EQUIVALENCE_TOLERANCE = 'parse-equivalence' as const;
@@ -36,17 +37,6 @@ function contentSkeleton(body: string): string {
const warnedCanonicalizeErrors = new Set<string>();
const MAX_WARNED_CANONICALIZE_ERRORS = 8;
-/** True when `needle` appears in `haystack` as a subsequence (two-pointer,
- * O(n+m)). Insertions in `haystack` are free; any dropped or substituted
- * `needle` byte fails. */
-function isSubsequence(needle: string, haystack: string): boolean {
- let i = 0;
- for (let j = 0; j < haystack.length && i < needle.length; j++) {
- if (needle[i] === haystack[j]) i++;
- }
- return i === needle.length;
-}
-
export function isParseEquivalentBridge(
left: string,
right: string,
diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.ts
new file mode 100644
index 000000000..754dc5cc2
--- /dev/null
+++ b/packages/core/src/bridge/pm-structural-equivalence.ts
@@ -0,0 +1,354 @@
+import { isSubsequence } from './subsequence.ts';
+import type { ToleranceClassSeverity } from './tolerance-telemetry.ts';
+
+export interface PmStructuralNode {
+ type?: string;
+ attrs?: Record<string, unknown>;
+ content?: PmStructuralNode[];
+ text?: string;
+ marks?: Array<{ type: string; attrs?: Record<string, unknown> }>;
+}
+
+const VOLATILE_ATTRS = new Set(['sourceRaw', 'sourceDirty', 'position']);
+
+const CONTAINER_TYPES = new Set([
+ 'jsxComponent',
+ 'table',
+ 'tableRow',
+ 'tableCell',
+ 'tableHeader',
+ 'list',
+ 'listItem',
+ 'blockquote',
+ 'codeBlock',
+ 'heading',
+]);
+
+/** Canonical marker for a hard line break, the join token every cell-flatten
+ * and void-`<br/>` degrade collapses toward so the three source spellings
+ * (a `hardBreak` node, a block boundary inside a cell, a literal `<br/>`
+ * text run) compare equal. */
+const BR_SENTINEL: PmStructuralNode = { type: '__br__' };
+
+const BR_LITERAL_RE = /^<br\s*\/?>$/i;
+
+interface DegradeEntry {
+ readonly label: string;
+ readonly severity: ToleranceClassSeverity;
+ readonly rationale: string;
+ readonly proofPointer: string;
+ readonly canonicalize: (tree: PmStructuralNode) => PmStructuralNode;
+}
+
+function flattenTableCells(node: PmStructuralNode): PmStructuralNode {
+ const next = mapChildren(node, flattenTableCells);
+ if ((next.type === 'tableCell' || next.type === 'tableHeader') && next.content) {
+ return { ...next, content: flattenBlocksToInline(next.content) };
+ }
+ return next;
+}
+
+function flattenBlocksToInline(blocks: PmStructuralNode[]): PmStructuralNode[] {
+ const out: PmStructuralNode[] = [];
+ for (const block of blocks) {
+ const leaves = inlineLeavesOf(block);
+ if (leaves.length === 0) continue;
+ if (out.length > 0) out.push(BR_SENTINEL);
+ out.push(...leaves);
+ }
+ return out;
+}
+
+/** Inline leaves of a node in document order. Text and inline atoms return
+ * themselves; a block with block children flattens (boundaries → `<br/>`);
+ * a block with inline children returns those children. */
+function inlineLeavesOf(node: PmStructuralNode): PmStructuralNode[] {
+ if (node.text !== undefined || node.type === 'hardBreak' || node.type === 'jsxInline') {
+ return [node];
+ }
+ if (!node.content || node.content.length === 0) return [];
+ const childrenAreBlocks = node.content.some(
+ (c) => c.text === undefined && c.type !== 'hardBreak' && c.type !== 'jsxInline' && !!c.content,
+ );
+ return childrenAreBlocks ? flattenBlocksToInline(node.content) : node.content;
+}
+
+function unifyHardBreaks(node: PmStructuralNode): PmStructuralNode {
+ if (node.type === 'hardBreak' || node.type === BR_SENTINEL.type) return BR_SENTINEL;
+ if (node.text !== undefined && BR_LITERAL_RE.test(node.text.trim())) return BR_SENTINEL;
+ return mapChildren(node, unifyHardBreaks);
+}
+
+const STRUCTURAL_DEGRADE_REGISTRY = [
+ {
+ label: 'table-cell-block-flatten',
+ severity: 'pm-model-caused',
+ rationale:
+ 'GFM table cells have no block spelling; a block placed in a cell is flattened to inline on serialize, so a cell-with-blocks and a cell-with-inline describe the same persisted document.',
+ proofPointer:
+ 'markdown/table-cell-flatten.ts flattenCellBlocks (table-cell-flatten-dropped-block event)',
+ canonicalize: flattenTableCells,
+ },
+ {
+ label: 'void-hardbreak-br',
+ severity: 'serializer-caused',
+ rationale:
+ 'A void hardBreak inside a table cell or heading serializes to a literal <br /> that a fresh parse keeps as text; the node form and the literal form are the same break.',
+ proofPointer: 'markdown/void-br-promoter.ts + markdown/to-markdown-handlers.ts break handler',
+ canonicalize: unifyHardBreaks,
+ },
+] as const satisfies readonly DegradeEntry[];
+
+/** The degrade labels this module can report — derived from the registry, so a
+ * new tolerance is one registry entry, never a scattered string literal. */
+export type StructuralDegradeLabel = (typeof STRUCTURAL_DEGRADE_REGISTRY)[number]['label'];
+
+export type StructuralDivergenceReason =
+ | 'content-loss'
+ | 'structural-shatter'
+ | 'structural-divergence'
+ | 'pipeline-threw';
+
+export type StructuralEquivalenceResult =
+ | {
+ equivalent: true;
+ level: 'L1' | 'L2';
+ appliedDegrades: StructuralDegradeLabel[];
+ }
+ | {
+ equivalent: false;
+ level: 'L1' | 'L2';
+ reason: StructuralDivergenceReason;
+ detail: string;
+ appliedDegrades: StructuralDegradeLabel[];
+ };
+
+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(
+ node: PmStructuralNode,
+ fn: (child: PmStructuralNode) => PmStructuralNode,
+): PmStructuralNode {
+ if (!node.content) return node;
+ return { ...node, content: node.content.map(fn) };
+}
+
+/** Comparison-form of a node: volatile + empty attrs dropped, marks sorted,
+ * empty content elided. Two nodes are structurally equal iff their reduced
+ * forms stable-stringify identically. `ignoreAttrs` drops caller-nominated
+ * attr keys on top of the fixed volatile set (see ComparePmStructuralOptions). */
+function reduce(node: PmStructuralNode, ignoreAttrs?: (key: string) => boolean): unknown {
+ const out: Record<string, unknown> = {};
+ if (node.type !== undefined) out.type = node.type;
+ if (node.text !== undefined) out.text = node.text;
+ const attrs = reduceAttrs(node.attrs, ignoreAttrs);
+ if (attrs) out.attrs = attrs;
+ if (node.marks && node.marks.length > 0) {
+ out.marks = [...node.marks]
+ .map((m) => ({ type: m.type, attrs: reduceAttrs(m.attrs, ignoreAttrs) }))
+ .sort((a, b) => stableStringify(a).localeCompare(stableStringify(b)));
+ }
+ if (node.content && node.content.length > 0)
+ out.content = node.content.map((child) => reduce(child, ignoreAttrs));
+ return out;
+}
+
+function reduceAttrs(
+ attrs: Record<string, unknown> | undefined,
+ ignoreAttrs?: (key: string) => boolean,
+): Record<string, unknown> | null {
+ if (!attrs) return null;
+ const out: Record<string, unknown> = {};
+ for (const key of Object.keys(attrs).sort()) {
+ if (VOLATILE_ATTRS.has(key)) continue;
+ if (ignoreAttrs?.(key)) continue;
+ const value = attrs[key];
+ if (value === undefined || value === null) continue;
+ out[key] = ignoreAttrs ? deepDropKeys(value, ignoreAttrs) : value;
+ }
+ return Object.keys(out).length > 0 ? out : null;
+}
+
+/** Recursively strip every object key the predicate matches, at any depth.
+ * Only invoked when a caller passes `ignoreAttrs`; a plain comparison leaves
+ * attr values untouched. Object keys only — a matched string that appears as a
+ * VALUE (e.g. an mdast attribute `{ name: 'src', value }` whose key is `name`)
+ * is preserved, so the raw authored attribute survives while its
+ * render-derived projection is dropped. */
+function deepDropKeys(value: unknown, ignoreAttrs: (key: string) => boolean): unknown {
+ if (Array.isArray(value)) return value.map((entry) => deepDropKeys(entry, ignoreAttrs));
+ if (value && typeof value === 'object') {
+ const out: Record<string, unknown> = {};
+ for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+ if (ignoreAttrs(key)) continue;
+ out[key] = deepDropKeys(entry, ignoreAttrs);
+ }
+ return out;
+ }
+ return value;
+}
+
+function stableStringify(value: unknown): string {
+ return JSON.stringify(value, (_k, v) => {
+ if (v && typeof v === 'object' && !Array.isArray(v)) {
+ const sorted: Record<string, unknown> = {};
+ for (const key of Object.keys(v as Record<string, unknown>).sort()) {
+ sorted[key] = (v as Record<string, unknown>)[key];
+ }
+ return sorted;
+ }
+ return v;
+ });
+}
+
+/** Concatenated, whitespace-stripped text of a tree — the byte stream a
+ * faithful round-trip must not LOSE. Compared as a subsequence so a degrade
+ * that INSERTS tokens (a `<br/>` literal) never reads as loss. */
+function textSkeleton(node: PmStructuralNode): string {
+ let acc = '';
+ const walk = (n: PmStructuralNode): void => {
+ if (n.text !== undefined) acc += n.text;
+ if (n.content) for (const child of n.content) walk(child);
+ };
+ walk(node);
+ return acc.replace(/\s+/g, '');
+}
+
+/** Sorted multiset of container identities; `jsxComponent` carries its
+ * componentName so a same-count container substitution still diverges. */
+function containerSignature(node: PmStructuralNode): string[] {
+ const sig: string[] = [];
+ const walk = (n: PmStructuralNode): void => {
+ if (n.type && CONTAINER_TYPES.has(n.type)) {
+ const name = n.type === 'jsxComponent' ? String(n.attrs?.componentName ?? '') : '';
+ sig.push(name ? `${n.type}:${name}` : n.type);
+ }
+ if (n.content) for (const child of n.content) walk(child);
+ };
+ walk(node);
+ return sig.sort();
+}
+
+function applyDegrades(tree: PmStructuralNode): {
+ normalized: PmStructuralNode;
+ fired: StructuralDegradeLabel[];
+} {
+ let current = tree;
+ const fired: StructuralDegradeLabel[] = [];
+ for (const entry of STRUCTURAL_DEGRADE_REGISTRY) {
+ const before = stableStringify(current);
+ const after = entry.canonicalize(current);
+ if (stableStringify(after) !== before) fired.push(entry.label);
+ current = after;
+ }
+ return { normalized: current, fired };
+}
+
+export function comparePmStructural(
+ expected: PmStructuralNode,
+ actual: PmStructuralNode,
+ opts: ComparePmStructuralOptions = {},
+): StructuralEquivalenceResult {
+ const e = applyDegrades(expected);
+ const a = applyDegrades(actual);
+ const appliedDegrades = [...new Set([...e.fired, ...a.fired])];
+
+ if (!isSubsequence(textSkeleton(e.normalized), textSkeleton(a.normalized))) {
+ return {
+ equivalent: false,
+ level: 'L1',
+ reason: 'content-loss',
+ appliedDegrades,
+ detail: 'authored text did not survive the round-trip',
+ };
+ }
+
+ const expectedSig = containerSignature(e.normalized);
+ const actualSig = containerSignature(a.normalized);
+ if (stableStringify(expectedSig) !== stableStringify(actualSig)) {
+ return {
+ equivalent: false,
+ level: 'L1',
+ reason: 'structural-shatter',
+ appliedDegrades,
+ detail: `container multiset diverged: [${expectedSig.join(', ')}] vs [${actualSig.join(', ')}]`,
+ };
+ }
+
+ const reducedExpected = reduce(e.normalized, opts.ignoreAttrs);
+ const reducedActual = reduce(a.normalized, opts.ignoreAttrs);
+ if (stableStringify(reducedExpected) === stableStringify(reducedActual)) {
+ return {
+ equivalent: true,
+ level: appliedDegrades.length > 0 ? 'L2' : 'L1',
+ appliedDegrades,
+ };
+ }
+ return {
+ equivalent: false,
+ level: 'L2',
+ reason: 'structural-divergence',
+ appliedDegrades,
+ detail: firstStructuralDivergence(reducedExpected, reducedActual),
+ };
+}
+
+/** Best-effort locator naming the first structurally diverging node path — a
+ * red result should name the construct, not dump a tree. Falls back to a
+ * coarse message when the divergence is deep. */
+function firstStructuralDivergence(expected: unknown, actual: unknown, path = 'doc'): string {
+ const ex = expected as Record<string, unknown> | undefined;
+ const ac = actual as Record<string, unknown> | undefined;
+ if (!ex || !ac) return `${path}: node presence differs`;
+ if (ex.type !== ac.type) return `${path}: type ${String(ex.type)} vs ${String(ac.type)}`;
+ const exContent = (ex.content as unknown[]) ?? [];
+ const acContent = (ac.content as unknown[]) ?? [];
+ if (exContent.length !== acContent.length) {
+ return `${path}(${String(ex.type)}): child count ${exContent.length} vs ${acContent.length}`;
+ }
+ for (let i = 0; i < exContent.length; i++) {
+ if (stableStringify(exContent[i]) !== stableStringify(acContent[i])) {
+ return firstStructuralDivergence(
+ exContent[i],
+ acContent[i],
+ `${path}>${String(ex.type)}[${i}]`,
+ );
+ }
+ }
+ return `${path}(${String(ex.type)}): attrs or marks differ`;
+}
+
+export function compareRoundTripStructural(
+ doc: PmStructuralNode,
+ io: {
+ serialize: (doc: PmStructuralNode) => string;
+ parse: (body: string) => PmStructuralNode;
+ },
+ opts: ComparePmStructuralOptions = {},
+): StructuralEquivalenceResult {
+ let actual: PmStructuralNode;
+ try {
+ actual = io.parse(io.serialize(doc));
+ } catch (err) {
+ return {
+ equivalent: false,
+ level: 'L1',
+ reason: 'pipeline-threw',
+ appliedDegrades: [],
+ detail: `serialize/parse threw: ${err instanceof Error ? err.message : String(err)}`,
+ };
+ }
+ return comparePmStructural(doc, actual, opts);
+}
+
+export function structuralDivergence(
+ fromSource: PmStructuralNode,
+ fromFragment: PmStructuralNode,
+ ignoreAttrs?: (attrKey: string) => boolean,
+): boolean {
+ return !comparePmStructural(fromSource, fromFragment, { ignoreAttrs }).equivalent;
+}
diff --git a/packages/core/src/bridge/structural-freshness.ts b/packages/core/src/bridge/structural-freshness.ts
new file mode 100644
index 000000000..59c699482
--- /dev/null
+++ b/packages/core/src/bridge/structural-freshness.ts
@@ -0,0 +1,109 @@
+import { type PmStructuralNode, structuralDivergence } from './pm-structural-equivalence.ts';
+
+const RESOLVER_DERIVED_ATTRS = new Set(['src', 'href', 'size']);
+const WIKI_EMBED_COMPONENTS = new Set([
+ 'WikiEmbedImage',
+ 'WikiEmbedVideo',
+ 'WikiEmbedAudio',
+ 'WikiEmbedFile',
+]);
+
+function deepDropResolverKeys<T>(value: T): T {
+ if (Array.isArray(value)) {
+ return value.map((entry) => deepDropResolverKeys(entry)) as unknown as T;
+ }
+ if (value && typeof value === 'object') {
+ const out: Record<string, unknown> = {};
+ for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+ if (RESOLVER_DERIVED_ATTRS.has(key)) continue;
+ out[key] = deepDropResolverKeys(entry);
+ }
+ return out as T;
+ }
+ return value;
+}
+
+/** Comparison-form of a tree with resolver-derived keys dropped inside every
+ * WikiEmbed* subtree (and only there — see `RESOLVER_DERIVED_ATTRS`). */
+function stripResolverDerivedAttrs(node: PmStructuralNode): PmStructuralNode {
+ if (
+ node.type === 'jsxComponent' &&
+ typeof node.attrs?.componentName === 'string' &&
+ WIKI_EMBED_COMPONENTS.has(node.attrs.componentName)
+ ) {
+ return deepDropResolverKeys(node);
+ }
+ if (!node.content) return node;
+ return { ...node, content: node.content.map(stripResolverDerivedAttrs) };
+}
+
+function stripMdastPositions<T>(value: T): T {
+ if (Array.isArray(value)) {
+ return value.map((entry) => stripMdastPositions(entry)) as unknown as T;
+ }
+ if (value && typeof value === 'object') {
+ const out: Record<string, unknown> = {};
+ for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+ if (key === 'position') continue;
+ out[key] = stripMdastPositions(entry);
+ }
+ return out as T;
+ }
+ return value;
+}
+
+/** First `jsxComponent` in document order, or undefined. `parse(sourceRaw)` of
+ * a single component's bytes yields a document whose first (and only top-level)
+ * jsxComponent is that component's reconstruction. */
+function firstJsxComponent(root: PmStructuralNode): PmStructuralNode | undefined {
+ if (root.type === 'jsxComponent') return root;
+ if (root.content) {
+ for (const child of root.content) {
+ const found = firstJsxComponent(child);
+ if (found) return found;
+ }
+ }
+ return undefined;
+}
+
+export interface StructuralFreshnessCheckerOptions {
+ parse: (sourceRaw: string) => PmStructuralNode;
+ cacheLimit?: number;
+}
+
+export interface StructuralFreshnessChecker {
+ isDiverged(node: PmStructuralNode): boolean;
+}
+
+export function createStructuralFreshnessChecker(
+ opts: StructuralFreshnessCheckerOptions,
+): StructuralFreshnessChecker {
+ const cacheLimit = opts.cacheLimit ?? 2048;
+ const reparseCache = new Map<string, PmStructuralNode | null>();
+
+ const reparsedStripped = (sourceRaw: string): PmStructuralNode | null => {
+ const cached = reparseCache.get(sourceRaw);
+ if (cached !== undefined) return cached;
+ const found = firstJsxComponent(opts.parse(sourceRaw));
+ const value = found ? stripResolverDerivedAttrs(stripMdastPositions(found)) : null;
+ if (reparseCache.size >= cacheLimit) {
+ const oldest = reparseCache.keys().next().value;
+ if (oldest !== undefined) reparseCache.delete(oldest);
+ }
+ reparseCache.set(sourceRaw, value);
+ return value;
+ };
+
+ return {
+ isDiverged(node) {
+ if (node.type !== 'jsxComponent' || !node.attrs || node.attrs.kind === 'expression') {
+ return false;
+ }
+ const sourceRaw = node.attrs.sourceRaw;
+ if (typeof sourceRaw !== 'string' || sourceRaw.length === 0) return false;
+ const reparsed = reparsedStripped(sourceRaw);
+ if (!reparsed) return false;
+ return structuralDivergence(reparsed, stripResolverDerivedAttrs(stripMdastPositions(node)));
+ },
+ };
+}
diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.ts
new file mode 100644
index 000000000..af20de1e2
--- /dev/null
+++ b/packages/core/src/bridge/subsequence.ts
@@ -0,0 +1,10 @@
+/** 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. */
+export function isSubsequence(needle: string, haystack: string): boolean {
+ let i = 0;
+ for (let j = 0; j < haystack.length && i < needle.length; j++) {
+ if (needle[i] === haystack[j]) i++;
+ }
+ return i === needle.length;
+}
diff --git a/packages/core/src/extensions/jsx-component.ts b/packages/core/src/extensions/jsx-component.ts
index 1cee940e1..f03cc9da8 100644
--- a/packages/core/src/extensions/jsx-component.ts
+++ b/packages/core/src/extensions/jsx-component.ts
@@ -15,7 +15,8 @@ declare module '@tiptap/core' {
*
* Children are recursively-walked mdast children from mdxJsxFlowElement.
* Descriptor dispatch at render time determines the NodeView branch
- * (registered → live React, wildcard → UnregisteredBadge, error → nested CM).
+ * (registered → live React; wildcard and render error both auto-convert to
+ * the rawMdxFallback nested CodeMirror source editor — Precedent #28/#30).
*
* Attrs:
* - componentName: the JSX tag name (e.g., 'Callout', 'Accordion')
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index affc3828d..9dee65883 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -381,7 +381,7 @@ export {
htmlToMdast,
mdastToMarkdown,
} from './markdown/html-to-mdast.ts';
-export { MarkdownManager } from './markdown/index.ts';
+export { MarkdownManager, type SerializeCallOptions } from './markdown/index.ts';
export { markdownToHtml, mdastToHtml } from './markdown/mdast-to-html.ts';
export { normalizeDocRelativeAssetUrl } from './markdown/resolve-image-url.ts';
export {
@@ -974,7 +974,11 @@ export {
type BridgeToleranceClass,
type BridgeToleranceSignal,
bindFrontmatterDoc,
+ type ComparePmStructuralOptions,
classifySeverity,
+ comparePmStructural,
+ compareRoundTripStructural,
+ createStructuralFreshnessChecker,
type DiffChange,
type DocBoundarySplit,
defaultScheduler,
@@ -1006,6 +1010,7 @@ export {
normalizeBridge,
PARSE_EQUIVALENCE_TOLERANCE,
type ParsedFmRegion,
+ type PmStructuralNode,
parseFencedFmRegion,
parseFmRegion,
projectMergeBoundarySpace,
@@ -1014,8 +1019,14 @@ export {
readFmRegionWithError,
reattachLeadingDocBoundary,
type Scheduler,
+ type StructuralDegradeLabel,
+ type StructuralDivergenceReason,
+ type StructuralEquivalenceResult,
+ type StructuralFreshnessChecker,
+ type StructuralFreshnessCheckerOptions,
setToleranceTelemetryHook,
splitLeadingDocBoundary,
+ structuralDivergence,
type ToleranceClassSeverity,
type ToleranceFireRecord,
type ToleranceTelemetryHook,
diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.ts
index 58a810193..cdbc4c874 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -49,6 +49,10 @@ import type {
MdxTextExpression,
} from 'mdast-util-mdx';
import type { Processor } from 'unified';
+import {
+ createStructuralFreshnessChecker,
+ type StructuralFreshnessChecker,
+} from '../bridge/structural-freshness.ts';
import { isValidSourceLiteralRaw } from '../extensions/source-literal-mark.ts';
import { createRegistry } from '../registry/index.ts';
import type { PropDef } from '../registry/types.ts';
@@ -83,6 +87,18 @@ import './mdast-augmentation.ts';
interface MarkdownManagerOptions {
extensions: Extensions;
+ deriveStructuralFreshness?: boolean;
+}
+
+export interface SerializeCallOptions {
+ skipFreshnessDerive?: boolean;
+}
+
+/** Holder for the freshness checker so a `serialize()` call can suppress it
+ * for its own synchronous duration (same pattern as `ParseContextHolder`:
+ * handlers close over the holder, not the value). */
+interface FreshnessCheckerHolder {
+ checker: StructuralFreshnessChecker | undefined;
}
interface ParseContext {
@@ -101,11 +117,20 @@ export class MarkdownManager {
private parseProcessor: Processor;
private serializeProcessor: Processor;
private parseCtx: ParseContextHolder = { current: {} };
+ private freshnessHolder: FreshnessCheckerHolder = { checker: undefined };
constructor(options: MarkdownManagerOptions) {
this.schema = getSchema(options.extensions);
this.handlers = buildMdastToPmHandlers(this.schema, this.parseCtx);
- const { nodeHandlers, markHandlers } = buildPmToMdastHandlers(this.schema);
+ this.freshnessHolder.checker = options.deriveStructuralFreshness
+ ? createStructuralFreshnessChecker({
+ parse: (sourceRaw) => this.parseWithFallback(sourceRaw),
+ })
+ : undefined;
+ const { nodeHandlers, markHandlers } = buildPmToMdastHandlers(
+ this.schema,
+ this.freshnessHolder,
+ );
this.pmNodeHandlers = nodeHandlers;
this.pmMarkHandlers = markHandlers;
@@ -148,7 +173,7 @@ export class MarkdownManager {
return parseWithFallback(markdown, { parse: (md) => this.parse(md, opts) });
}
- serialize(json: JSONContent): string {
+ serialize(json: JSONContent, opts?: SerializeCallOptions): string {
let doc: PmNode;
try {
doc = this.schema.nodeFromJSON(json) as PmNode;
@@ -156,11 +181,17 @@ export class MarkdownManager {
const msg = `MarkdownManager.serialize() failed: schema rejected JSONContent (type=${json.type}, childCount=${json.content?.length ?? 0})`;
throw new Error(msg, { cause: err });
}
- return serializeMd(doc, this.serializeProcessor, {
- schema: this.schema,
- pmNodeHandlers: this.pmNodeHandlers,
- pmMarkHandlers: this.pmMarkHandlers,
- });
+ const heldChecker = this.freshnessHolder.checker;
+ if (opts?.skipFreshnessDerive) this.freshnessHolder.checker = undefined;
+ try {
+ return serializeMd(doc, this.serializeProcessor, {
+ schema: this.schema,
+ pmNodeHandlers: this.pmNodeHandlers,
+ pmMarkHandlers: this.pmMarkHandlers,
+ });
+ } finally {
+ this.freshnessHolder.checker = heldChecker;
+ }
}
}
@@ -226,8 +257,9 @@ function hasDirtyDescendant(node: PmNode): boolean {
return found;
}
-function effectiveDirty(node: PmNode): boolean {
- return node.attrs.sourceDirty || hasDirtyDescendant(node);
+function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChecker): boolean {
+ if (node.attrs.sourceDirty || hasDirtyDescendant(node)) return true;
+ return freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;
}
function isEmptyMdastParagraph(node: MdastNodes): boolean {
@@ -1029,7 +1061,10 @@ function buildMdastToPmHandlers(
return handlers as RemarkProseMirrorOptions['handlers'];
}
-function buildPmToMdastHandlers(schema: Schema): {
+function buildPmToMdastHandlers(
+ schema: Schema,
+ freshness: FreshnessCheckerHolder,
+): {
nodeHandlers: FromProseMirrorOptions<string, string>['nodeHandlers'];
markHandlers: FromProseMirrorOptions<string, string>['markHandlers'];
} {
@@ -1280,7 +1315,7 @@ function buildPmToMdastHandlers(schema: Schema): {
? (pmNode.attrs.attributes as Array<MdxJsxAttribute | MdxJsxExpressionAttribute>)
: [];
- if (!effectiveDirty(pmNode) && pmNode.attrs.sourceRaw) {
+ if (!effectiveDirty(pmNode, freshness.checker) && pmNode.attrs.sourceRaw) {
return {
type: 'mdxJsxFlowElement' as const,
name: componentName,
diff --git a/packages/core/src/shadow-repo-layout.test.ts b/packages/core/src/shadow-repo-layout.test.ts
index 82e56464f..0d497c3e0 100644
--- a/packages/core/src/shadow-repo-layout.test.ts
+++ b/packages/core/src/shadow-repo-layout.test.ts
@@ -761,6 +761,29 @@ describe('parseCheckpoint / formatCheckpointBodyLine (bridge-correctness SPEC §
}
});
+ test('round-trips producer-guard-loss with its construct locator', () => {
+ const line = formatCheckpointBodyLine({
+ kind: 'producer-guard-loss',
+ docName: 'notes/table.md',
+ size: 128,
+ metadata: { construct: 'jsxComponent,tableCell' },
+ });
+ const body = `checkpoint: Before producer-guard content-loss\n\n${line}`;
+ const parsed = parseCheckpoint(body);
+ expect(parsed?.kind).toBe('producer-guard-loss');
+ if (parsed?.kind === 'producer-guard-loss') {
+ expect(parsed.metadata.construct).toBe('jsxComponent,tableCell');
+ expect(parsed.docName).toBe('notes/table.md');
+ expect(parsed.size).toBe(128);
+ }
+ });
+
+ test('producer-guard-loss with a non-string construct is rejected (unknown-shape fallback)', () => {
+ const body =
+ 'checkpoint: X\n\nok-checkpoint-v1: {"kind":"producer-guard-loss","metadata":{"construct":5}}';
+ expect(parseCheckpoint(body)).toBe(null);
+ });
+
test('backward-compat: pre-enrichment body without docName/size returns nulls', () => {
// Simulates a checkpoint commit written before the docName/size enrichment.
// The rescue read path's fallback
diff --git a/packages/core/src/shadow-repo-layout.ts b/packages/core/src/shadow-repo-layout.ts
index 095a8f65f..6407cab15 100644
--- a/packages/core/src/shadow-repo-layout.ts
+++ b/packages/core/src/shadow-repo-layout.ts
@@ -606,6 +606,19 @@ export type ParsedCheckpoint =
size: number | null;
metadata: { lostSubstrings: string[] };
}
+ | {
+ // Observer A's producer guard detected serialize output that fails
+ // structural legality (a fresh parse loses authored content) at the
+ // serialize boundary — distinct from `bridge-merge-loss` (a Path B merge
+ // drop) so the two detection sites keep separate retention budgets and
+ // TimelinePanel can tell serializer-corruption from merge-drop. `construct`
+ // is a bounded, content-free locator of the danger-space node types
+ // present (e.g. `jsxComponent,tableCell`), never raw content.
+ kind: 'producer-guard-loss';
+ docName: string | null;
+ size: number | null;
+ metadata: { construct: string };
+ }
| {
kind: 'external-change-rescue';
docName: string | null;
@@ -668,6 +681,18 @@ export function parseCheckpoint(body: string): ParsedCheckpoint | null {
}
return null;
}
+ if (kind === 'producer-guard-loss') {
+ const m = metadata as { construct?: unknown };
+ if (typeof m.construct === 'string') {
+ return {
+ kind: 'producer-guard-loss',
+ docName,
+ size,
+ metadata: { construct: m.construct },
+ };
+ }
+ return null;
+ }
if (kind === 'external-change-rescue') {
const m = metadata as { incomingDiskSha?: unknown };
if (typeof m.incomingDiskSha === 'string') {
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index d257f0e24..45cd79b33 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -418,7 +418,10 @@ export {
export {
isPairedWriteOrigin,
OBSERVER_SYNC_ORIGIN,
+ type ObserverDispatchKind,
type PairedWriteOrigin,
+ type SetupServerObserversOpts,
+ setupServerObservers,
} from './server-observers.ts';
export {
buildWipTree,
diff --git a/packages/server/src/md-manager.ts b/packages/server/src/md-manager.ts
index 7692137da..ab489807e 100644
--- a/packages/server/src/md-manager.ts
+++ b/packages/server/src/md-manager.ts
@@ -23,8 +23,21 @@
import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
import { getSchema } from '@tiptap/core';
-/** Shared server-side MarkdownManager instance. */
-export const mdManager = new MarkdownManager({ extensions: sharedExtensions });
+/**
+ * Shared server-side MarkdownManager instance.
+ *
+ * `deriveStructuralFreshness` is on for the server: every server serialize
+ * (Observer A's byte-fate write, persistence's fragment serialize, the
+ * watchdog's canonicalizer) runs through this one instance, so promoting
+ * state-divergence into the serialize decision here keeps them all agreeing on
+ * the fresh bytes — a node whose children have diverged from a stale `sourceRaw`
+ * re-derives instead of emitting the stale slice, and the bridge invariant
+ * (`serialize(fragment)` === Y.Text) holds because both sides re-derive.
+ */
+export const mdManager = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+});
/** Shared server-side ProseMirror schema, derived from sharedExtensions. */
export const schema = getSchema(sharedExtensions);
diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.ts
index 429c69e08..a301f22cc 100644
--- a/packages/server/src/metrics.ts
+++ b/packages/server/src/metrics.ts
@@ -60,6 +60,27 @@ export interface ReconciliationMetrics {
* checkpoints written via saveInMemoryCheckpoint. Bounds the rate a user
* might see in TimelinePanel; if high, coalescing becomes worth adding. */
bridgeMergeCheckpointCreated: number;
+ /** Bridge-correctness — count of Observer A producer-guard fires: the bytes
+ * about to persist failed structural legality (a fresh parse loses authored
+ * content). Separate rate accounting from `bridgeMergeContentLoss` — the
+ * guard is an independent detection site at the serialize boundary, not a
+ * Path B merge-drop. The counter increments only on emit; the companion
+ * `producerGuardFiresSuppressed` counts fires the per-doc log throttle
+ * dropped, so `actual_rate = fires + suppressed`. */
+ producerGuardFires: number;
+ /** Companion to `producerGuardFires` — count of producer-guard fires whose
+ * structured log the per-doc cooldown suppressed. The recovery checkpoint is
+ * written regardless of this throttle (it gates only the log), so a
+ * suppressed fire still leaves a restore anchor. */
+ producerGuardFiresSuppressed: number;
+ /** Bridge-correctness — count of producer-guard recovery checkpoints written
+ * via saveInMemoryCheckpoint on the `producer-guard-loss` path. Kept
+ * separate from `bridgeMergeCheckpointCreated` so an operator dashboarding on
+ * checkpoint rate can distinguish producer-guard recoveries (serialize-
+ * boundary content-loss) from Path-B merge-drop recoveries; the rest of the
+ * feature is likewise separately observable (`producerGuardFires` /
+ * `producerGuardFiresSuppressed`). */
+ producerGuardCheckpointCreated: number;
/** Y.Text-is-truth contract — count of bridge invariant violation events
* emitted by the watchdog (Observer B post-Phase-1, the persistence
* pre-write sanity check, and any test-harness watcher).
@@ -382,6 +403,9 @@ const counters: ReconciliationMetrics = {
persistenceDiskWrites: 0,
bridgeMergeContentLoss: 0,
bridgeMergeCheckpointCreated: 0,
+ producerGuardFires: 0,
+ producerGuardFiresSuppressed: 0,
+ producerGuardCheckpointCreated: 0,
bridgeInvariantViolations: 0,
bridgeInvariantViolationsSuppressed: 0,
persistenceSkipNonQuiescent: 0,
@@ -506,6 +530,18 @@ export function incrementBridgeMergeCheckpointCreated(): void {
counters.bridgeMergeCheckpointCreated++;
}
+export function incrementProducerGuardCheckpointCreated(): void {
+ counters.producerGuardCheckpointCreated++;
+}
+
+export function incrementProducerGuardFires(): void {
+ counters.producerGuardFires++;
+}
+
+export function incrementProducerGuardFiresSuppressed(): void {
+ counters.producerGuardFiresSuppressed++;
+}
+
export function incrementBridgeInvariantViolations(): void {
counters.bridgeInvariantViolations++;
}
@@ -734,6 +770,9 @@ export function resetMetrics(): void {
counters.persistenceDiskWrites = 0;
counters.bridgeMergeContentLoss = 0;
counters.bridgeMergeCheckpointCreated = 0;
+ counters.producerGuardFires = 0;
+ counters.producerGuardFiresSuppressed = 0;
+ counters.producerGuardCheckpointCreated = 0;
counters.bridgeInvariantViolations = 0;
counters.bridgeInvariantViolationsSuppressed = 0;
counters.persistenceSkipNonQuiescent = 0;
diff --git a/packages/server/src/server-observers.path-b-respell.test.ts b/packages/server/src/server-observers.path-b-respell.test.ts
new file mode 100644
index 000000000..ef06e8f58
--- /dev/null
+++ b/packages/server/src/server-observers.path-b-respell.test.ts
@@ -0,0 +1,231 @@
+/**
+ * Observer A — freshness-respell suppression on diverged-baseline drains (the
+ * `<Steps>` source-authoring duplication class).
+ *
+ * The race: during rapid source-mode typing, the hidden WYSIWYG editor's
+ * y-sync writeback fires Observer A with a fragment whose jsxComponent
+ * children reflect newer text than their stamped `sourceRaw`, while a
+ * concurrent keystroke has already advanced Y.Text past Observer A's settled
+ * raw witness. If serialize re-derives the diverged component (the freshness
+ * backstop), it emits the INDENTED nested-JSX respelling of the same block
+ * Y.Text holds FLUSH-LEFT — de-anchoring the write from the raw history that
+ * every downstream convergence mechanism (the fragment-unchanged gate, the
+ * normalize gate, the splice text-match, Path B's diff3, CRDT merge against
+ * concurrent keystrokes) line-matches on. Under full-suite contention the
+ * de-anchored write lands the block TWICE in the authoritative bytes
+ * (`Step one body.` duplicated — the browser canary failure).
+ *
+ * The fix is drain-scoped: Observer A reads raw-witness coherence before
+ * serializing and passes `skipFreshnessDerive: true` on diverged drains, so
+ * the emission stays byte-aligned with the pristine `sourceRaw` (freshness is
+ * a standing state check — the divergence re-derives on the next settled
+ * drain, so G1 still holds). The producer guard is also skipped on suppressed
+ * drains: the emission is knowingly historical, and a content-loss verdict
+ * against it would be a false alarm.
+ *
+ * The diverged drain is staged deterministically: one transaction carries
+ * BOTH the echo-shaped fragment mutation AND the Y.Text advance, so the
+ * settlement drain sees `currentText !== lastSyncedYTextBytes` — the exact
+ * interleaving contention produces. Byte-level corruption itself only
+ * manifests under real cross-peer concurrency (the browser canaries own that
+ * rung); these tests pin the suppression WIRING and the drain's clean
+ * convergence.
+ */
+import { describe, expect, spyOn, test } from 'bun:test';
+import {
+ type JSONContent,
+ MarkdownManager,
+ type SerializeCallOptions,
+ sharedExtensions,
+} from '@inkeep/open-knowledge-core';
+import { getSchema } from '@tiptap/core';
+import { updateYFragment } from '@tiptap/y-tiptap';
+import * as Y from 'yjs';
+import { type SetupServerObserversOpts, setupServerObservers } from './server-observers.ts';
+
+const schema = getSchema(sharedExtensions);
+
+// One generation behind: the settled state whose sourceRaw stamps the echo carries.
+const GEN1 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one bod\n\n</Step>\n\n</Steps>\n';
+// The advanced truth: the user's next keystroke landed in Y.Text (flush-left).
+const GEN2 =
+ '## Guide\n\nIntro paragraph.\n\n<Steps>\n\n<Step>\n\nStep one body.\n\n</Step>\n\n</Steps>\n';
+
+type J = { type?: string; text?: string; attrs?: Record<string, unknown>; content?: J[] };
+
+function mutateFirstText(node: J, from: string, to: string): boolean {
+ if (typeof node.text === 'string' && node.text === from) {
+ node.text = to;
+ return true;
+ }
+ for (const child of node.content ?? []) {
+ if (mutateFirstText(child, from, to)) return true;
+ }
+ return false;
+}
+
+/** Freshness-ON manager (the server posture, packages/server/src/md-manager.ts)
+ * wrapped to record the per-call serialize options Observer A passes. */
+function makeRecordingManager(): {
+ manager: MarkdownManager;
+ serializeOpts: Array<SerializeCallOptions | undefined>;
+} {
+ const real = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+ });
+ const serializeOpts: Array<SerializeCallOptions | undefined> = [];
+ const manager = new Proxy(real, {
+ get(target, prop, receiver) {
+ if (prop === 'serialize') {
+ return (json: JSONContent, opts?: SerializeCallOptions) => {
+ serializeOpts.push(opts);
+ return target.serialize(json, opts);
+ };
+ }
+ const value = Reflect.get(target, prop, receiver);
+ return typeof value === 'function' ? value.bind(target) : value;
+ },
+ });
+ return { manager, serializeOpts };
+}
+
+describe('Observer A — freshness suppression on diverged-baseline drains', () => {
+ test('settled drain serializes WITH freshness; diverged drain suppresses it; bytes converge to truth', () => {
+ const { manager, serializeOpts } = makeRecordingManager();
+ const doc = new Y.Doc();
+ const xmlFragment = doc.getXmlFragment('default');
+ const ytext = doc.getText('source');
+ const cleanup = setupServerObservers({
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager: manager,
+ schema,
+ docName: 'respell-suppression.md',
+ } as SetupServerObserversOpts);
+ try {
+ // Settlement drain: raw witness coherent → freshness ACTIVE (the
+ // feature's designed domain — G1 depends on it).
+ const gen1Node = schema.nodeFromJSON(manager.parse(GEN1));
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, gen1Node, { mapping: new Map(), isOMark: new Map() });
+ }, null);
+ expect(ytext.toString()).toContain('Step one bod');
+ // The drain's top-level serialize passed an explicit non-suppressed
+ // option (internal helpers — e.g. the splice's per-block serializes —
+ // also land in the recording without options, so match by presence).
+ expect(serializeOpts.some((o) => o?.skipFreshnessDerive === false)).toBe(true);
+ expect(serializeOpts.some((o) => o?.skipFreshnessDerive === true)).toBe(false);
+
+ // The echo shape: children advanced to GEN2's interior, sourceRaw left
+ // at GEN1's stamps (parse(GEN1) stamped them; the JSON mutation below
+ // touches only the text leaf).
+ const echoTree = manager.parse(GEN1) as J;
+ if (!mutateFirstText(echoTree, 'Step one bod', 'Step one body.')) {
+ throw new Error('staging failed: interior leaf not found');
+ }
+ const echoNode = schema.nodeFromJSON(echoTree as JSONContent);
+
+ // ONE transaction: fragment echo-writeback + concurrent Y.Text
+ // keystroke → the drain sees a diverged raw witness.
+ const before = serializeOpts.length;
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, echoNode, { mapping: new Map(), isOMark: new Map() });
+ ytext.delete(0, ytext.length);
+ ytext.insert(0, GEN2);
+ }, null);
+
+ // The diverged drain's serialize was SUPPRESSED.
+ const divergedCalls = serializeOpts.slice(before);
+ expect(divergedCalls.length).toBeGreaterThan(0);
+ expect(divergedCalls.some((o) => o?.skipFreshnessDerive === true)).toBe(true);
+
+ // And the authoritative bytes converge to the typed truth: the block
+ // exactly once, flush-left, no character mangling, no respell.
+ const finalText = ytext.toString();
+ expect((finalText.match(/Step one body\./g) ?? []).length).toBe(1);
+ expect((finalText.match(/<Steps>/g) ?? []).length).toBe(1);
+ expect((finalText.match(/<Step>/g) ?? []).length).toBe(1);
+ expect(finalText).not.toContain('body.y');
+ expect(/\n[ \t]+<Step\b/.test(finalText)).toBe(false);
+ } finally {
+ cleanup();
+ }
+ });
+
+ test('a recent EXTERNAL Y.Text write suppresses freshness even on a witness-coherent drain, until the quiescence window passes', () => {
+ // The in-flight variant: client keystrokes can race a re-derived write at
+ // the CRDT level even when the raw witness looks coherent at drain time,
+ // so witness coherence alone cannot certify the re-derive. Any external
+ // Y.Text write inside the quiescence window defers freshness; a drain
+ // after the window re-arms it.
+ let clock = 1_000_000;
+ const nowSpy = spyOn(Date, 'now').mockImplementation(() => clock);
+ const { manager, serializeOpts } = makeRecordingManager();
+ const doc = new Y.Doc();
+ const xmlFragment = doc.getXmlFragment('default');
+ const ytext = doc.getText('source');
+ const cleanup = setupServerObservers({
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager: manager,
+ schema,
+ docName: 'quiescence.md',
+ } as SetupServerObserversOpts);
+ try {
+ // Settle GEN1 (fragment-only seed — no external ytext write).
+ const gen1Node = schema.nodeFromJSON(manager.parse(GEN1));
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, gen1Node, { mapping: new Map(), isOMark: new Map() });
+ }, null);
+
+ // External Y.Text write (a collab keystroke): resets the quiescence
+ // clock and settles back through Observer B.
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nTrailing.\n');
+ }, 'external-peer');
+
+ // A fragment-only drain INSIDE the window: witness is coherent (the
+ // external write settled through B), but the doc is not quiescent →
+ // freshness suppressed.
+ clock += 500;
+ const insideWindowStart = serializeOpts.length;
+ const echoTree = manager.parse(ytext.toString()) as J;
+ if (!mutateFirstText(echoTree, 'Step one bod', 'Step one bod!')) {
+ throw new Error('staging failed: interior leaf not found');
+ }
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, schema.nodeFromJSON(echoTree as JSONContent), {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ }, null);
+ const insideWindow = serializeOpts.slice(insideWindowStart);
+ expect(insideWindow.length).toBeGreaterThan(0);
+ expect(insideWindow.some((o) => o?.skipFreshnessDerive === true)).toBe(true);
+
+ // Past the window, a fragment-only drain re-arms freshness.
+ clock += 10_000;
+ const afterWindowStart = serializeOpts.length;
+ const laterTree = manager.parse(ytext.toString()) as J;
+ if (!mutateFirstText(laterTree, 'Step one bod', 'Step one bod?')) {
+ throw new Error('staging failed: interior leaf not found (second)');
+ }
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, schema.nodeFromJSON(laterTree as JSONContent), {
+ mapping: new Map(),
+ isOMark: new Map(),
+ });
+ }, null);
+ const afterWindow = serializeOpts.slice(afterWindowStart);
+ expect(afterWindow.length).toBeGreaterThan(0);
+ expect(afterWindow.some((o) => o?.skipFreshnessDerive === false)).toBe(true);
+ } finally {
+ nowSpy.mockRestore();
+ cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/server-observers.producer-guard.test.ts b/packages/server/src/server-observers.producer-guard.test.ts
new file mode 100644
index 000000000..ab969a683
--- /dev/null
+++ b/packages/server/src/server-observers.producer-guard.test.ts
@@ -0,0 +1,538 @@
+/**
+ * Producer guard — the read-only structural-legality watchdog at the
+ * Observer-A serialize (the moment byte-fate is decided). A fresh parse of the
+ * bytes about to be persisted must reconstruct the same authored content;
+ * markdown never legitimately drops text on a round-trip, so a content-loss
+ * verdict means the serializer emitted corrupt bytes only a fresh parser sees.
+ *
+ * Drives the real `setupServerObservers` drain (not the comparator in
+ * isolation). A serializer that silently loses content is injected at the
+ * MarkdownManager boundary via a Proxy — no module mock, no internal-call
+ * assertions.
+ *
+ * dev/test posture (default `bun test` NODE_ENV=test) → throw loud.
+ * packaged posture (NODE_ENV=production) → rate-limited structured log +
+ * silent checkpoint of the pre-loss source, never a throw, never a
+ * corrective write.
+ */
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import { mkdirSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
+import { getSchema } from '@tiptap/core';
+import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import simpleGit from 'simple-git';
+import * as Y from 'yjs';
+import { getMetrics } from './metrics.ts';
+import {
+ ProducerGuardViolationError,
+ type SetupServerObserversOpts,
+ setupServerObservers,
+} from './server-observers.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+
+const mdManager = new MarkdownManager({ extensions: sharedExtensions });
+const schema = getSchema(sharedExtensions);
+
+// A word the losing serializer drops. Never appears in a bounded-cardinality
+// log payload, so the packaged-posture test can also assert redaction.
+const LOSS_SENTINEL = 'ZZLOSSZZ';
+
+// Mirrors the internal per-doc log cooldown (`PRODUCER_GUARD_LOG_COOLDOWN_MS`
+// in server-observers.ts) — not exported, so the throttle test pins the same
+// window via a controllable clock.
+const PRODUCER_GUARD_COOLDOWN_MS = 5_000;
+
+// A table whose one body cell carries the sentinel plus a keeper word: a
+// serializer that drops the sentinel loses cell text while the table structure
+// and the keeper survive — a pure content-loss, not a container shatter.
+const DANGER_TABLE_MD = `| Col |\n| --- |\n| ${LOSS_SENTINEL} keep |\n`;
+// Same danger space, nothing to lose — the non-vacuity control.
+const LEGAL_TABLE_MD = `| Col |\n| --- |\n| keep only |\n`;
+// Plain (non-danger) doc — exercises the danger-space gate even under a losing
+// serializer, because plain block content is not round-trip-lossy.
+const PLAIN_MD = `${LOSS_SENTINEL} plain paragraph\n`;
+
+function createDoc() {
+ const doc = new Y.Doc();
+ return { doc, xmlFragment: doc.getXmlFragment('default'), ytext: doc.getText('source') };
+}
+
+/** Seed the fragment in one null-origin drain so Observer A sees xmlDirty. A
+ * guard throw inside the settlement handler propagates out of this call. */
+function seedFragment(doc: Y.Doc, xmlFragment: Y.XmlFragment, md: string): void {
+ const pmNode = schema.nodeFromJSON(mdManager.parse(md));
+ doc.transact(() => {
+ updateYFragment(doc, xmlFragment, pmNode, { mapping: new Map(), isOMark: new Map() });
+ }, null);
+}
+
+/** MarkdownManager whose `serialize` drops every `dropText` run from its output
+ * — a serializer that silently loses content, faulted at the system boundary. */
+function makeContentLosingManager(dropText: string): MarkdownManager {
+ return new Proxy(mdManager, {
+ get(target, prop, receiver) {
+ if (prop === 'serialize') {
+ return (json: Parameters<MarkdownManager['serialize']>[0]) =>
+ target.serialize(json).split(dropText).join('');
+ }
+ return Reflect.get(target, prop, receiver);
+ },
+ });
+}
+
+/** MarkdownManager whose `serialize` strips the `<Callout>` wrapper lines,
+ * leaving the interior text. A fresh parse of that output reconstructs the
+ * text as a plain paragraph — the container vanishes but no text is lost: a
+ * structural SHATTER, not a content-loss. The guard fires ONLY on content-loss,
+ * so this must stay silent. */
+function makeContainerShatteringManager(): MarkdownManager {
+ return new Proxy(mdManager, {
+ get(target, prop, receiver) {
+ if (prop === 'serialize') {
+ return (json: Parameters<MarkdownManager['serialize']>[0]) =>
+ target
+ .serialize(json)
+ .split('\n')
+ .filter((line) => !/^\s*<\/?Callout/.test(line))
+ .join('\n');
+ }
+ return Reflect.get(target, prop, receiver);
+ },
+ });
+}
+
+function baseOpts(
+ o: { doc: Y.Doc; xmlFragment: Y.XmlFragment; ytext: Y.Text } & Partial<SetupServerObserversOpts>,
+): SetupServerObserversOpts {
+ const { doc, xmlFragment, ytext, ...rest } = o;
+ return { doc, xmlFragment, ytext, mdManager, schema, ...rest };
+}
+
+function fragmentJsonString(xmlFragment: Y.XmlFragment): string {
+ return JSON.stringify(yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON());
+}
+
+/** Poll for a committed checkpoint ref (the checkpoint is queued via
+ * `queueMicrotask` then written by an async git commit chain). Bounded — a
+ * timeout returns empty so the assertion fails loudly rather than hanging. */
+async function waitForCheckpointRefs(shadow: ShadowHandle, timeoutMs = 3000): Promise<string[]> {
+ const sg = shadowGit(shadow);
+ const deadline = Date.now() + timeoutMs;
+ for (;;) {
+ const out = (await sg.raw('for-each-ref', '--format=%(refname)', 'refs/checkpoints/')).trim();
+ if (out) return out.split('\n');
+ if (Date.now() >= deadline) return [];
+ await new Promise((r) => setTimeout(r, 25));
+ }
+}
+
+describe('Producer guard (FR6) — dev/test posture throws (M2)', () => {
+ test('content-losing serialize on a danger-space doc throws ProducerGuardViolationError at the drain', () => {
+ const { doc, xmlFragment, ytext } = createDoc();
+ const losing = makeContentLosingManager(LOSS_SENTINEL);
+ const cleanup = setupServerObservers(
+ baseOpts({ doc, xmlFragment, ytext, mdManager: losing, docName: 'loss.md' }),
+ );
+ try {
+ let thrown: unknown;
+ try {
+ seedFragment(doc, xmlFragment, DANGER_TABLE_MD);
+ } catch (err) {
+ thrown = err;
+ }
+ expect(thrown).toBeInstanceOf(ProducerGuardViolationError);
+ expect((thrown as ProducerGuardViolationError).info.reason).toBe('content-loss');
+ } finally {
+ cleanup();
+ }
+ });
+
+ test('faithful serialize on the same danger space does NOT fire (non-vacuity control)', () => {
+ const { doc, xmlFragment, ytext } = createDoc();
+ const cleanup = setupServerObservers(
+ baseOpts({ doc, xmlFragment, ytext, docName: 'legal.md' }),
+ );
+ try {
+ expect(() => seedFragment(doc, xmlFragment, LEGAL_TABLE_MD)).not.toThrow();
+ } finally {
+ cleanup();
+ }
+ });
+
+ test('danger-space gate: a content-losing serialize on a plain doc is skipped (no fire)', () => {
+ const { doc, xmlFragment, ytext } = createDoc();
+ const losing = makeContentLosingManager(LOSS_SENTINEL);
+ const cleanup = setupServerObservers(
+ baseOpts({ doc, xmlFragment, ytext, mdManager: losing, docName: 'plain.md' }),
+ );
+ try {
+ expect(() => seedFragment(doc, xmlFragment, PLAIN_MD)).not.toThrow();
+ } finally {
+ cleanup();
+ }
+ });
+
+ test('a container-shatter (text preserved, container gone) does NOT fire — silent on shatter', () => {
+ // Pins "fire on content-loss, silent on shatter": the serializer drops the
+ // Callout wrapper but keeps its text, so a fresh parse shatters the container
+ // without losing content. The guard fires only on content-loss, so no throw
+ // and no producer-guard-violation event.
+ const { doc, xmlFragment, ytext } = createDoc();
+ const shattering = makeContainerShatteringManager();
+ const warn = spyOn(console, 'warn').mockImplementation(() => {});
+ const cleanup = setupServerObservers(
+ baseOpts({ doc, xmlFragment, ytext, mdManager: shattering, docName: 'shatter.md' }),
+ );
+ try {
+ expect(() =>
+ seedFragment(doc, xmlFragment, '<Callout type="info">\n\nkeep this text\n\n</Callout>\n'),
+ ).not.toThrow();
+ const fired = warn.mock.calls
+ .map((call) => String(call[0]))
+ .some((line) => line.includes('producer-guard-violation'));
+ expect(fired).toBe(false);
+ } finally {
+ warn.mockRestore();
+ cleanup();
+ }
+ });
+});
+
+describe('Producer guard (FR6) — packaged posture logs + checkpoints, never throws/corrects (QA-010)', () => {
+ const SAVED_ENV = ['NODE_ENV', 'OK_RETHROW_BRIDGE_LOSS'] as const;
+ let savedEnv: Partial<Record<(typeof SAVED_ENV)[number], string | undefined>>;
+ let projectRoot: string;
+ let shadow: ShadowHandle;
+
+ beforeEach(async () => {
+ savedEnv = {};
+ for (const key of SAVED_ENV) savedEnv[key] = process.env[key];
+ process.env.NODE_ENV = 'production';
+ delete process.env.OK_RETHROW_BRIDGE_LOSS;
+
+ projectRoot = await mkdtemp(resolve(tmpdir(), 'ok-producer-guard-'));
+ mkdirSync(resolve(projectRoot, 'content'), { recursive: true });
+ const git = simpleGit(projectRoot);
+ await git.init();
+ await git.raw('config', 'user.name', 'Test');
+ await git.raw('config', 'user.email', '[email protected]');
+ shadow = await initShadowRepo(projectRoot);
+ });
+
+ afterEach(async () => {
+ for (const key of SAVED_ENV) {
+ const value = savedEnv[key];
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+ await rm(projectRoot, { recursive: true, force: true });
+ });
+
+ test('detects content-loss without throwing: structured log + silent checkpoint, no corrective write', async () => {
+ const { doc, xmlFragment, ytext } = createDoc();
+ const losing = makeContentLosingManager(LOSS_SENTINEL);
+ const warn = spyOn(console, 'warn').mockImplementation(() => {});
+ const cleanup = setupServerObservers(
+ baseOpts({
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager: losing,
+ docName: 'loss.md',
+ shadow: () => shadow,
+ contentRoot: 'content',
+ getBranch: () => 'main',
+ }),
+ );
+ try {
+ // Packaged posture: the drain completes without a throw.
+ expect(() => seedFragment(doc, xmlFragment, DANGER_TABLE_MD)).not.toThrow();
+
+ // Structured detection event, bounded cardinality, no raw content.
+ const event = warn.mock.calls
+ .map((call) => String(call[0]))
+ .find((line) => line.includes('producer-guard-violation'));
+ expect(event).toBeDefined();
+ expect(event as string).not.toContain(LOSS_SENTINEL);
+ const parsed = JSON.parse(event as string);
+ expect(parsed).toMatchObject({
+ event: 'producer-guard-violation',
+ docName: 'loss.md',
+ reason: 'content-loss',
+ });
+ // The construct locator is a bounded danger-space enum, never raw content.
+ expect(typeof parsed.construct).toBe('string');
+ expect(parsed.construct.length).toBeGreaterThan(0);
+ expect(parsed.construct).not.toContain(LOSS_SENTINEL);
+
+ // Never corrective: the guard did not re-inject the lost text. The
+ // fragment still carries it (untouched); Y.Text holds the as-computed
+ // lossy body.
+ expect(fragmentJsonString(xmlFragment)).toContain(LOSS_SENTINEL);
+ expect(ytext.toString()).not.toContain(LOSS_SENTINEL);
+
+ // Silent checkpoint queued + committed.
+ const refs = await waitForCheckpointRefs(shadow);
+ expect(refs.length).toBeGreaterThan(0);
+ } finally {
+ warn.mockRestore();
+ cleanup();
+ }
+ });
+
+ test('two distinct losses in the cooldown: one log suppressed, BOTH checkpointed, next emit carries the suppressed count', async () => {
+ const { doc, xmlFragment, ytext } = createDoc();
+ const losing = makeContentLosingManager(LOSS_SENTINEL);
+ const warn = spyOn(console, 'warn').mockImplementation(() => {});
+ // Controllable clock so the cooldown window is deterministic (the throttle
+ // reads Date.now); the checkpoint label uses `new Date()`, unaffected. The
+ // checkpoint poll below is Date.now-independent, so the mock can stay live.
+ let clock = 1_000_000;
+ const nowSpy = spyOn(Date, 'now').mockImplementation(() => clock);
+ const cleanup = setupServerObservers(
+ baseOpts({
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager: losing,
+ docName: 'throttle.md',
+ shadow: () => shadow,
+ contentRoot: 'content',
+ getBranch: () => 'main',
+ }),
+ );
+ const violations = (): Array<{ suppressedSincePrevious: number }> =>
+ warn.mock.calls
+ .map((call) => String(call[0]))
+ .filter((line) => line.includes('producer-guard-violation'))
+ .map((line) => JSON.parse(line));
+ // Bounded poll that does NOT read Date.now (which the test mocks), so the
+ // deadline logic can't stall under the frozen clock.
+ const pollCheckpointRefs = async (minCount: number, tries = 80): Promise<string[]> => {
+ const sg = shadowGit(shadow);
+ let refs: string[] = [];
+ for (let i = 0; i < tries; i++) {
+ const out = (
+ await sg.raw('for-each-ref', '--format=%(refname)', 'refs/checkpoints/')
+ ).trim();
+ refs = out ? out.split('\n') : [];
+ if (refs.length >= minCount) return refs;
+ await new Promise((r) => setTimeout(r, 25));
+ }
+ return refs;
+ };
+ const cell = (keep: string): string => `| Col |\n| --- |\n| ${LOSS_SENTINEL} ${keep} |\n`;
+ try {
+ // Loss 1 (distinct body A) fires + logs.
+ seedFragment(doc, xmlFragment, cell('keepA'));
+ // Loss 2 (distinct body B, distinct pre-loss) inside the cooldown: the log
+ // is suppressed, but Major 2a requires the checkpoint to still be written.
+ seedFragment(doc, xmlFragment, cell('keepB'));
+ expect(violations()).toHaveLength(1);
+ expect(violations()[0]?.suppressedSincePrevious).toBe(0);
+
+ // The load-bearing Major 2a assertion: BOTH losses are anchored even though
+ // only one logged. Pre-fix (checkpoint gated by the same cooldown), the
+ // suppressed loss 2 wrote no checkpoint and this stays at one ref.
+ const refs = await pollCheckpointRefs(2);
+ expect(refs.length).toBeGreaterThanOrEqual(2);
+
+ // Advance past the cooldown; loss 3 emits and carries the one suppressed.
+ clock += PRODUCER_GUARD_COOLDOWN_MS + 1;
+ seedFragment(doc, xmlFragment, cell('keepC'));
+ const v = violations();
+ expect(v).toHaveLength(2);
+ expect(v[1]?.suppressedSincePrevious).toBe(1);
+ // Settle loss 3's checkpoint before cleanup so its async write (and
+ // counter increment) cannot straggle into a later test's window.
+ expect((await pollCheckpointRefs(3)).length).toBeGreaterThanOrEqual(3);
+ } finally {
+ nowSpy.mockRestore();
+ warn.mockRestore();
+ cleanup();
+ }
+ });
+
+ test('without a shadow repo, the violation log still fires (detection is not gated on checkpointing)', () => {
+ // In production the shadow repo initializes asynchronously; a doc opened
+ // before init completes hits the `!shadow` early return. Only the CHECKPOINT
+ // is gated on shadow availability — the structured detection event must
+ // fire regardless, or a shadow-less session loses the signal entirely.
+ const { doc, xmlFragment, ytext } = createDoc();
+ const losing = makeContentLosingManager(LOSS_SENTINEL);
+ const warn = spyOn(console, 'warn').mockImplementation(() => {});
+ const cleanup = setupServerObservers(
+ baseOpts({ doc, xmlFragment, ytext, mdManager: losing, docName: 'no-shadow.md' }),
+ );
+ try {
+ expect(() => seedFragment(doc, xmlFragment, DANGER_TABLE_MD)).not.toThrow();
+ const event = warn.mock.calls
+ .map((call) => String(call[0]))
+ .find((line) => line.includes('producer-guard-violation'));
+ expect(event).toBeDefined();
+ expect(JSON.parse(event as string)).toMatchObject({
+ event: 'producer-guard-violation',
+ docName: 'no-shadow.md',
+ reason: 'content-loss',
+ });
+ } finally {
+ warn.mockRestore();
+ cleanup();
+ }
+ });
+
+ // A repeated pre-loss source is only reachable when Y.Text returns to a prior
+ // value BETWEEN losing drains — sequentially, each fire's pre-loss is the
+ // previous fire's lossy body, and an identical body dedups upstream via
+ // `lastGuardedBody`. The restore below stages the concurrent scenario the
+ // dedup map exists for: a remote peer (external origin) putting the last-good
+ // source back while the serializer keeps emitting distinct losing bodies.
+ const cellBody = (keep: string): string => `| Col |\n| --- |\n| ${LOSS_SENTINEL} ${keep} |\n`;
+ function restoreYtext(o: { doc: Y.Doc; ytext: Y.Text }, contents: string): void {
+ o.doc.transact(() => {
+ o.ytext.delete(0, o.ytext.length);
+ o.ytext.insert(0, contents);
+ }, 'test-external-peer');
+ }
+
+ test('an identical pre-loss source is checkpointed once — the dedup map holds (one ref, one counter)', async () => {
+ const { doc, xmlFragment, ytext } = createDoc();
+ const losing = makeContentLosingManager(LOSS_SENTINEL);
+ const warn = spyOn(console, 'warn').mockImplementation(() => {});
+ // The external Y.Text restore below resets the freshness-quiescence clock,
+ // which also defers the producer guard (a suppressed drain's emission is
+ // knowingly historical). Advance a controlled clock past the window so the
+ // post-restore drain is guard-adjudicated and the dedup map is what
+ // decides — the semantics this test pins.
+ let clock = 1_000_000;
+ const nowSpy = spyOn(Date, 'now').mockImplementation(() => clock);
+ const cleanup = setupServerObservers(
+ baseOpts({
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager: losing,
+ docName: 'dedup.md',
+ shadow: () => shadow,
+ contentRoot: 'content',
+ getBranch: () => 'main',
+ }),
+ );
+ // Per-test signal (the warn spy is fresh per test; the metrics counter is
+ // module-global, so it is asserted as a DELTA below).
+ const createdEvents = (): number =>
+ warn.mock.calls
+ .map((call) => String(call[0]))
+ .filter((line) => line.includes('producer-guard-checkpoint-created')).length;
+ // The git ref becomes visible before the write promise's .then (which emits
+ // the event + increments the counter) runs, so poll rather than asserting
+ // immediately after the ref appears — the gap is wide on loaded CI runners.
+ const waitForCreatedEvents = async (count: number, tries = 120): Promise<number> => {
+ for (let i = 0; i < tries; i++) {
+ if (createdEvents() >= count) return createdEvents();
+ await new Promise((r) => setTimeout(r, 25));
+ }
+ return createdEvents();
+ };
+ try {
+ // Establish a non-empty last-good source without firing (plain = no danger).
+ seedFragment(doc, xmlFragment, PLAIN_MD);
+ const lastGood = ytext.toString();
+ // Loss 1: pre-loss = lastGood → checkpoint 1.
+ seedFragment(doc, xmlFragment, cellBody('keepA'));
+ expect((await waitForCheckpointRefs(shadow)).length).toBe(1);
+ expect(await waitForCreatedEvents(1)).toBe(1);
+ const counterAfterFirst = getMetrics().producerGuardCheckpointCreated;
+ // Remote peer restores the last-good source, then a DISTINCT losing body
+ // fires with the SAME pre-loss — the dedup map must skip the re-write.
+ restoreYtext({ doc, ytext }, lastGood);
+ expect(ytext.toString()).toBe(lastGood);
+ // Past the freshness-quiescence window: the post-restore drain must be
+ // guard-adjudicated so the dedup map (not the quiescence defer) decides.
+ clock += 2_001;
+ seedFragment(doc, xmlFragment, cellBody('keepB'));
+ // Negative wait: give a (wrong) second checkpoint time to land.
+ await new Promise((r) => setTimeout(r, 400));
+ expect((await waitForCheckpointRefs(shadow)).length).toBe(1);
+ expect(createdEvents()).toBe(1);
+ expect(getMetrics().producerGuardCheckpointCreated).toBe(counterAfterFirst);
+ } finally {
+ nowSpy.mockRestore();
+ warn.mockRestore();
+ cleanup();
+ }
+ });
+
+ test('a FAILED checkpoint write reopens the retry window (dedup entry cleared on failure)', async () => {
+ // Regression for the dedup-before-write hole: the dedup entry is set
+ // synchronously (so concurrent drains dedup), but a failed write must clear
+ // it — otherwise a transient failure (disk pressure, shadow handle race)
+ // permanently closes the recovery window for that pre-loss content.
+ const { doc, xmlFragment, ytext } = createDoc();
+ const losing = makeContentLosingManager(LOSS_SENTINEL);
+ const warn = spyOn(console, 'warn').mockImplementation(() => {});
+ // A shadow whose backing directory is gone: every git op (and thus the
+ // checkpoint write) rejects. Swapped for the good shadow after the failure.
+ const brokenRoot = await mkdtemp(resolve(tmpdir(), 'ok-producer-guard-broken-'));
+ mkdirSync(resolve(brokenRoot, 'content'), { recursive: true });
+ const brokenGit = simpleGit(brokenRoot);
+ await brokenGit.init();
+ await brokenGit.raw('config', 'user.name', 'Test');
+ await brokenGit.raw('config', 'user.email', '[email protected]');
+ const brokenShadow = await initShadowRepo(brokenRoot);
+ await rm(brokenRoot, { recursive: true, force: true });
+ let activeShadow = brokenShadow;
+ const cleanup = setupServerObservers(
+ baseOpts({
+ doc,
+ xmlFragment,
+ ytext,
+ mdManager: losing,
+ docName: 'retry.md',
+ shadow: () => activeShadow,
+ contentRoot: 'content',
+ getBranch: () => 'main',
+ }),
+ );
+ const failureLogged = async (tries = 120): Promise<boolean> => {
+ for (let i = 0; i < tries; i++) {
+ const hit = warn.mock.calls
+ .map((call) => String(call[0]))
+ .some((line) => line.includes('checkpoint write failed'));
+ if (hit) return true;
+ await new Promise((r) => setTimeout(r, 25));
+ }
+ return false;
+ };
+ try {
+ seedFragment(doc, xmlFragment, PLAIN_MD);
+ const lastGood = ytext.toString();
+ // Loss 1 against the broken shadow: the write fails; the dedup entry for
+ // this pre-loss must be cleared so the content stays recoverable.
+ seedFragment(doc, xmlFragment, cellBody('keepA'));
+ expect(await failureLogged()).toBe(true);
+ // Shadow recovers; the same pre-loss recurs via the remote-peer restore.
+ activeShadow = shadow;
+ restoreYtext({ doc, ytext }, lastGood);
+ // Past the freshness-quiescence window (the restore reset it): the
+ // retry drain must be guard-adjudicated for the re-write to be
+ // attempted at all.
+ const retryClockBase = Date.now();
+ const retryNowSpy = spyOn(Date, 'now').mockImplementation(() => retryClockBase + 2_001);
+ try {
+ seedFragment(doc, xmlFragment, cellBody('keepB'));
+ } finally {
+ retryNowSpy.mockRestore();
+ }
+ // Pre-fix (entry never cleared) this stays empty forever — the recovery
+ // window is permanently closed and the assertion fails.
+ expect((await waitForCheckpointRefs(shadow)).length).toBeGreaterThanOrEqual(1);
+ } finally {
+ warn.mockRestore();
+ cleanup();
+ }
+ });
+});
diff --git a/packages/server/src/server-observers.ts b/packages/server/src/server-observers.ts
index af2f4b517..2876f84c0 100644
--- a/packages/server/src/server-observers.ts
+++ b/packages/server/src/server-observers.ts
@@ -23,12 +23,17 @@
*/
import type { LocalTransactionOrigin } from '@hocuspocus/server';
-import type { MarkdownManager } from '@inkeep/open-knowledge-core';
+import type {
+ MarkdownManager,
+ PmStructuralNode,
+ StructuralDivergenceReason,
+} from '@inkeep/open-knowledge-core';
import {
applyFastDiff,
applyIncrementalDiff,
BridgeInvariantViolationError,
BridgeMergeContentLossError,
+ comparePmStructural,
isParseEquivalentBridge,
mergeThreeWay,
normalizeBridge,
@@ -60,6 +65,9 @@ import {
incrementMapDrivenSpliceFallback,
incrementObserverAPathBFires,
incrementObserverAResidualMergeRuns,
+ incrementProducerGuardCheckpointCreated,
+ incrementProducerGuardFires,
+ incrementProducerGuardFiresSuppressed,
incrementServerObserverError,
incrementServerObserverFire,
} from './metrics.ts';
@@ -167,6 +175,69 @@ export function shouldRethrowBridgeMergeLoss(env: NodeJS.ProcessEnv = process.en
return env.NODE_ENV === 'test' || env.OK_RETHROW_BRIDGE_LOSS === '1';
}
+/**
+ * The producer-guard violation payload — parity with `BridgeMergeContentLossInfo`
+ * so both bridge-content-loss detection sites carry a named, structured shape
+ * rather than an inlined object literal.
+ */
+export interface ProducerGuardViolationInfo {
+ docName?: string;
+ reason: StructuralDivergenceReason;
+ detail: string;
+}
+
+/**
+ * Raised by the Observer-A producer guard when the bytes about to be persisted
+ * fail structural legality — a fresh parse loses authored content. Distinct
+ * class so the sync-impl's soft-recovery catch can pass it through (like
+ * `BridgeMergeContentLossError`) to reach the dev/test runner instead of
+ * swallowing it as a recoverable observer fault. Never thrown in the packaged
+ * posture (there the guard logs + checkpoints and returns).
+ */
+export class ProducerGuardViolationError extends Error {
+ readonly info: ProducerGuardViolationInfo;
+ constructor(info: ProducerGuardViolationInfo) {
+ super(
+ `Observer-A producer guard: serialize output failed structural legality (${info.reason}: ${info.detail})`,
+ );
+ this.name = 'ProducerGuardViolationError';
+ this.info = info;
+ }
+}
+
+/**
+ * Node types where the ProseMirror space exceeds what markdown can spell — the
+ * only place block-in-cell / stale-jsx-interior content-loss is representable.
+ * A fragment carrying none of these round-trips by construction, so the
+ * producer-guard parse is skipped for it, bounding the detection cost to the
+ * danger space in every posture.
+ */
+const PRODUCER_GUARD_DANGER_TYPES = new Set(['jsxComponent', 'table', 'tableCell', 'tableHeader']);
+
+function fragmentContainsDangerSpace(node: PmStructuralNode): boolean {
+ if (node.type && PRODUCER_GUARD_DANGER_TYPES.has(node.type)) return true;
+ if (node.content) {
+ for (const child of node.content) {
+ if (fragmentContainsDangerSpace(child)) return true;
+ }
+ }
+ return false;
+}
+
+/** Content-free locator for a guard fire: the sorted set of danger-space node
+ * types present in the fragment (e.g. `jsxComponent,tableCell`). Bounded
+ * cardinality (a subset of the four danger types), never raw content — safe on
+ * a log field and a persisted checkpoint metadata line. */
+function dangerSpaceLocator(node: PmStructuralNode): string {
+ const present = new Set<string>();
+ const walk = (n: PmStructuralNode): void => {
+ if (n.type && PRODUCER_GUARD_DANGER_TYPES.has(n.type)) present.add(n.type);
+ if (n.content) for (const child of n.content) walk(child);
+ };
+ walk(node);
+ return [...present].sort().join(',');
+}
+
/**
* Y.Text-relative splice — translated from `MapDrivenSplice`'s body-relative
* offsets by the frontmatter prefix length so the caller can apply directly
@@ -519,6 +590,14 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
let canonicalWitnessCoherent = false;
let xmlDirty = false;
let textDirty = false;
+ // Timestamp of the last EXTERNAL Y.Text change (user typing via collab, an
+ // agent's raw write — anything that is not our own cross-CRDT write). The
+ // freshness re-derive is gated on this being quiet (the quiescence gate in
+ // `runObserverASyncImpl`): during an active typing burst, in-flight client
+ // ops can race a re-derived (respelled) write at the CRDT level even when
+ // the raw witness LOOKS coherent at drain time, so witness coherence alone
+ // cannot certify that de-anchoring the emission is safe.
+ let lastExternalYtextChangeMs = 0;
/**
* STOP: the Path A/B router strict-compares this witness against
@@ -706,6 +785,162 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
recordSettledBaselines('');
}
+ // Producer guard (read-only). Caps the check at one parse per distinct
+ // serialization; a stuck doc re-emitting the same illegal bytes every drain
+ // only parses once.
+ let lastGuardedBody: string | undefined;
+ // Per-doc trailing throttle for the packaged-posture LOG so a doc stuck
+ // re-emitting illegal bytes cannot flood the local diagnostics; the throttled
+ // count rides the next emit (`fires + suppressed` = actual rate). The throttle
+ // gates only the log — the recovery checkpoint is written regardless.
+ const PRODUCER_GUARD_LOG_COOLDOWN_MS = 5_000;
+ // Quiescence window for the freshness re-derive (see the gate in
+ // `runObserverASyncImpl`): an external Y.Text write inside this window marks
+ // the doc as actively edited, and the re-derive defers to the next quiet
+ // drain. Sized to cover a typing burst's inter-keystroke gaps plus sync
+ // jitter under load; costs only re-derive LATENCY on a doc being actively
+ // typed into (where the pristine emission is the anchored, safe one anyway).
+ const FRESHNESS_QUIESCENCE_MS = 2_000;
+ const guardLogState = new Map<string, { lastMs: number; suppressed: number }>();
+ // Per-doc last pre-loss source already checkpointed. `lastGuardedBody` dedups
+ // identical serializations upstream, but distinct losing bodies can share the
+ // same last-good Y.Text; keying the checkpoint on the pre-loss source anchors
+ // that state once instead of re-writing an identical checkpoint per body. The
+ // entry is set synchronously (before the async write) so concurrent drains
+ // and a stuck doc re-emitting the same body dedup to one checkpoint, but it is
+ // cleared again if that write fails — a transient failure must not permanently
+ // close the recovery window for the pre-loss content.
+ const guardCheckpointedPreLoss = new Map<string, string>();
+
+ /**
+ * Report a producer-guard content-loss in the packaged posture: a rate-limited
+ * structured event (bounded cardinality — doc.name + reason/degrade enums + a
+ * construct locator, never raw content) plus a silent checkpoint of the
+ * pre-loss source so the state stays user-recoverable. Never throws, never
+ * corrective-writes (precedent #38): the drain still persists the bytes
+ * as-computed. The guard is a second DETECTION site for the bridge-content-loss
+ * class, not a second `BridgeMergeContentLossError` recovery — it uses its own
+ * `producer-guard-loss` checkpoint kind and its own fire/suppressed counters.
+ *
+ * The log throttle and the checkpoint are independent: throttling the log must
+ * not drop the recovery anchor, so the checkpoint always attempts (deduped on
+ * the pre-loss source) even when the log is suppressed.
+ */
+ const reportProducerGuardViolation = (
+ verdict: Extract<ReturnType<typeof comparePmStructural>, { equivalent: false }>,
+ construct: string,
+ ): void => {
+ const key = opts.docName ?? '__nodoc__';
+ const now = Date.now();
+ const prev = guardLogState.get(key);
+ const throttled = prev !== undefined && now - prev.lastMs < PRODUCER_GUARD_LOG_COOLDOWN_MS;
+ if (throttled) {
+ prev.suppressed += 1;
+ incrementProducerGuardFiresSuppressed();
+ } else {
+ const suppressedSincePrevious = prev?.suppressed ?? 0;
+ guardLogState.set(key, { lastMs: now, suppressed: 0 });
+ incrementProducerGuardFires();
+ console.warn(
+ JSON.stringify({
+ event: 'producer-guard-violation',
+ docName: opts.docName ?? null,
+ reason: verdict.reason,
+ construct,
+ appliedDegrades: verdict.appliedDegrades,
+ suppressedSincePrevious,
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ }
+
+ const shadow = opts.shadow?.();
+ if (!shadow || !opts.docName) return;
+ // Y.Text still holds the last-good source at this point — Observer A writes
+ // the (lossy) delta later in the drain — so it is the pre-loss restore
+ // anchor, mirroring Path B's pre-merge baseline.
+ const preLossSource = ytext.toString();
+ if (guardCheckpointedPreLoss.get(key) === preLossSource) return;
+ guardCheckpointedPreLoss.set(key, preLossSource);
+ const branch = opts.getBranch?.() ?? 'main';
+ const contentRoot = opts.contentRoot ?? '';
+ const docName = opts.docName;
+ queueMicrotask(() => {
+ saveInMemoryCheckpoint(shadow, contentRoot, {
+ kind: 'producer-guard-loss',
+ docName,
+ contents: preLossSource,
+ label: `Before producer-guard content-loss @ ${new Date().toISOString()}`,
+ branch,
+ metadata: { construct },
+ })
+ .then((sha) => {
+ incrementProducerGuardCheckpointCreated();
+ console.warn(
+ JSON.stringify({
+ event: 'producer-guard-checkpoint-created',
+ docName,
+ sha,
+ kind: 'producer-guard-loss',
+ timestamp: new Date().toISOString(),
+ }),
+ );
+ })
+ .catch((checkpointErr: unknown) => {
+ // The write failed, so the pre-loss content was NOT actually
+ // checkpointed. Reopen the retry window by clearing our dedup entry —
+ // only if a later, different pre-loss body has not since replaced it —
+ // so the next guard violation on this body attempts the write again
+ // instead of permanently skipping via the line-843 early return. The
+ // synchronous set() above still dedups concurrent drains and a stuck
+ // doc re-emitting the same body while a write is in flight.
+ if (guardCheckpointedPreLoss.get(key) === preLossSource) {
+ guardCheckpointedPreLoss.delete(key);
+ }
+ const e =
+ checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
+ console.warn('[Server Observer A] Producer-guard checkpoint write failed:', {
+ name: e.name,
+ message: e.message,
+ stack: e.stack?.split('\n').slice(0, 4).join('\n'),
+ });
+ });
+ });
+ };
+
+ /**
+ * Producer guard at the moment byte-fate is decided (the Observer-A
+ * serialize). A fresh parse of the bytes we are about to persist must
+ * reconstruct the same authored CONTENT: markdown never legitimately drops
+ * text on a round-trip, so a content-loss verdict means the serializer emitted
+ * corrupt bytes that only a fresh parser sees. Container-shatter is
+ * deliberately NOT a fire condition — some shatters are inherent CommonMark
+ * round-trip limits (a blockquote nested in a Callout re-merges on parse), a
+ * fidelity gap the offline I22 property test owns; firing on them here would
+ * cry wolf on legal-but-lossy nestings. Dev/test throw loud; packaged reports.
+ */
+ const runProducerGuard = (json: PmStructuralNode, body: string): void => {
+ if (body === lastGuardedBody) return;
+ lastGuardedBody = body;
+ if (!fragmentContainsDangerSpace(json)) return;
+
+ const reparsed = mdManager.parseWithFallback(body, observerParseOpts) as PmStructuralNode;
+ const verdict = comparePmStructural(json, reparsed);
+ // Narrow to the failure branch, then to the one reason the guard fires on.
+ // The union makes `reason`/`detail` reachable only here, and `detail`
+ // required — no optional-fallback crutch.
+ if (verdict.equivalent || verdict.reason !== 'content-loss') return;
+
+ if (shouldRethrowBridgeMergeLoss()) {
+ throw new ProducerGuardViolationError({
+ docName: opts.docName,
+ reason: verdict.reason,
+ detail: verdict.detail,
+ });
+ }
+ reportProducerGuardViolation(verdict, dangerSpaceLocator(json));
+ };
+
/**
* Observer A sync work. Computes delta between the settled baselines and
* current XmlFragment, applies ONLY that delta to Y.Text.
@@ -713,7 +948,36 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const runObserverASyncImpl = (): void => {
try {
const json = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
- const body = mdManager.serialize(json);
+ // Freshness-safety, read BEFORE serialize (the drain is synchronous).
+ // The freshness re-derive RESPELLS pristine components (indented nested
+ // JSX vs the flush-left bytes the raw history holds), and every
+ // convergence mechanism this serialization feeds (the fragment-unchanged
+ // gate, the normalize gate, the splice text-match, Path B's line-based
+ // diff3, CRDT merge against concurrent keystrokes) anchors on serialize
+ // output matching raw-history bytes. A de-anchored write racing live
+ // typing duplicates the block in the authoritative bytes (the `<Steps>`
+ // source-authoring corruption), so the re-derive is allowed only when
+ // BOTH hold:
+ // 1. the raw witness is coherent (Y.Text has not visibly advanced past
+ // the settlement this drain anchors on), AND
+ // 2. Y.Text is QUIESCENT (no external write within the window) — a
+ // typing burst's in-flight ops can race the write at the CRDT level
+ // even when the witness looks coherent at drain time.
+ // Freshness is a standing state check, not an edge trigger: a suppressed
+ // divergence is re-observed on the next safe drain, so a genuinely stale
+ // component still re-derives (G1 holds) — the deny-listed-origin edits
+ // freshness exists for land on fragment-only transactions that never
+ // reset the quiescence clock. Only racy drains defer.
+ const rawWitnessCoherent = ytext.toString() === lastSyncedYTextBytes;
+ const ytextQuiescent = Date.now() - lastExternalYtextChangeMs >= FRESHNESS_QUIESCENCE_MS;
+ const freshnessSafe = rawWitnessCoherent && ytextQuiescent;
+ const body = mdManager.serialize(json, { skipFreshnessDerive: !freshnessSafe });
+ // The guard adjudicates the bytes ONLY when they are current-intent: on a
+ // suppressed drain the emission is knowingly historical (pristine
+ // sourceRaw a generation behind the live children), so a content-loss
+ // verdict would be a false alarm — the next safe drain re-runs the
+ // guard against the re-derived bytes.
+ if (freshnessSafe) runProducerGuard(json as PmStructuralNode, body);
const frontmatter = readCurrentFm();
const md = prependFrontmatter(frontmatter, body);
@@ -1061,6 +1325,12 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
if (err instanceof BridgeMergeContentLossError) {
throw err;
}
+ // Same passthrough for the producer guard's dev/test loud-failure throw —
+ // it fires before any Y.Text write, so there is nothing to recover; let
+ // the test runner see it. Packaged posture never throws here.
+ if (err instanceof ProducerGuardViolationError) {
+ throw err;
+ }
incrementServerObserverError('a');
console.error('[Server Observer A] Failed to sync tree→text:', err);
// Reset the witnesses so the next retry computes a fresh delta instead
@@ -1424,6 +1694,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
return;
}
+ lastExternalYtextChangeMs = Date.now();
textDirty = true;
};
diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.ts
index ec826fe1e..6a94280c3 100644
--- a/packages/server/src/shadow-repo.test.ts
+++ b/packages/server/src/shadow-repo.test.ts
@@ -1014,6 +1014,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
const result = await gcCheckpointRefs(shadow, 'main', {
maxBridgeMergeLoss: 3,
+ maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 0, // disable TTL; only count-based cap applies
@@ -1033,6 +1034,52 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
expect(remaining).toHaveLength(3);
});
+ test('keeps only the most-recent N producer-guard-loss refs per branch', async () => {
+ // The producer-guard kind has its own retention budget
+ // (maxProducerGuardLoss), independent of maxBridgeMergeLoss — a stuck
+ // serializer must not evict merge-drop recovery anchors (or vice versa).
+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');
+ for (let i = 0; i < 7; i++) {
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind: 'producer-guard-loss',
+ docName: `doc-${i}.md`,
+ contents: `contents ${i}\n`,
+ label: `guard loss ${i}`,
+ metadata: { construct: 'table' },
+ });
+ }
+ // One bridge-merge-loss alongside: its budget (50) must shield it from the
+ // producer-guard cap.
+ await saveInMemoryCheckpoint(shadow, 'content/docs', {
+ kind: 'bridge-merge-loss',
+ docName: 'merge.md',
+ contents: '# pre-merge\n',
+ label: 'merge loss',
+ metadata: { lostSubstrings: ['x'] },
+ });
+
+ const result = await gcCheckpointRefs(shadow, 'main', {
+ maxBridgeMergeLoss: 50,
+ maxProducerGuardLoss: 3,
+ maxExternalChangeRescue: 50,
+ maxAutoConsolidation: 2,
+ ttlMs: 0, // disable TTL; only count-based cap applies
+ });
+
+ expect(result.scanned).toBe(8);
+ expect(result.deletedProducerGuardLoss).toBe(4); // 7 - 3 kept
+ expect(result.deletedBridgeMergeLoss).toBe(0);
+
+ const sg = shadowGit(shadow);
+ const remaining = (
+ await sg.raw('for-each-ref', '--format=%(refname)', 'refs/checkpoints/main/')
+ )
+ .trim()
+ .split('\n')
+ .filter(Boolean);
+ expect(remaining).toHaveLength(4); // 3 producer-guard + 1 bridge-merge
+ });
+
test('applies TTL independently of the count cap', async () => {
// Write 2 checkpoints with a TTL of 0 ms to force both past the deadline.
for (let i = 0; i < 2; i++) {
@@ -1050,6 +1097,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
const result = await gcCheckpointRefs(shadow, 'main', {
maxBridgeMergeLoss: 50,
+ maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 1, // everything older than 1 ms is eligible
@@ -1094,6 +1142,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
const result = await gcCheckpointRefs(shadow, 'main', {
maxBridgeMergeLoss: 0, // forces deletion of the typed checkpoint
+ maxProducerGuardLoss: 0,
maxExternalChangeRescue: 0,
maxAutoConsolidation: 2,
ttlMs: 0,
@@ -1170,6 +1219,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
const result = await gcCheckpointRefs(shadow, 'main', {
maxBridgeMergeLoss: 50,
+ maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 0,
@@ -1201,6 +1251,7 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)
// a dormant repo could lose the anchor the chained history hangs from.
const result = await gcCheckpointRefs(shadow, 'main', {
maxBridgeMergeLoss: 50,
+ maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 1,
diff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.ts
index 0099ecab8..a07885247 100644
--- a/packages/server/src/shadow-repo.ts
+++ b/packages/server/src/shadow-repo.ts
@@ -719,6 +719,11 @@ export async function safetyCheckpoint(
* content-preservation post-condition flagged the result, and we want a
* silent Notion-style restore artifact on the timeline. `contents` is the
* pre-merge baseline (the state the user saw before the conflict merge).
+ * - `producer-guard-loss` — Observer A's producer guard detected serialize
+ * output that fails structural legality (a fresh parse loses authored
+ * content) at the serialize boundary. `contents` is the pre-loss source (the
+ * last-good Y.Text); `construct` is a bounded, content-free locator of the
+ * danger-space node types present.
* - `external-change-rescue` — an external disk write (reconcile-delete or
* branch-switch path) would otherwise have discarded dirty Y.Doc content.
* `contents` is the rescued in-memory markdown; `incomingDiskSha` names
@@ -733,6 +738,14 @@ export type InMemoryCheckpointParams =
branch?: string;
metadata: { lostSubstrings: string[] };
}
+ | {
+ kind: 'producer-guard-loss';
+ docName: string;
+ contents: string;
+ label: string;
+ branch?: string;
+ metadata: { construct: string };
+ }
| {
kind: 'external-change-rescue';
docName: string;
@@ -780,20 +793,35 @@ export async function saveInMemoryCheckpoint(
// read path can render the listing without spawning a per-ref `git ls-tree`
// subprocess.
const size = Buffer.byteLength(params.contents, 'utf-8');
- const parsed: ParsedCheckpoint =
- params.kind === 'bridge-merge-loss'
- ? {
- kind: 'bridge-merge-loss',
- docName: params.docName,
- size,
- metadata: params.metadata,
- }
- : {
- kind: 'external-change-rescue',
- docName: params.docName,
- size,
- metadata: params.metadata,
- };
+ // Reconstruct the parsed shape per kind so each metadata type stays bound to
+ // its own discriminant (the switch is exhaustive over InMemoryCheckpointParams).
+ let parsed: ParsedCheckpoint;
+ switch (params.kind) {
+ case 'bridge-merge-loss':
+ parsed = {
+ kind: 'bridge-merge-loss',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
+ case 'producer-guard-loss':
+ parsed = {
+ kind: 'producer-guard-loss',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
+ case 'external-change-rescue':
+ parsed = {
+ kind: 'external-change-rescue',
+ docName: params.docName,
+ size,
+ metadata: params.metadata,
+ };
+ break;
+ }
const bodyLine = formatCheckpointBodyLine(parsed);
const message = `checkpoint: ${params.label}\n\n${bodyLine}`;
@@ -962,6 +990,13 @@ export interface CheckpointRetentionPolicy {
* written on every Observer A Path B post-condition violation. Default 50.
*/
maxBridgeMergeLoss: number;
+ /**
+ * Maximum `producer-guard-loss` checkpoints to keep per branch. Written when
+ * Observer A's producer guard detects illegal serialize output. Its own
+ * budget so a stuck serializer cannot evict merge-drop recovery anchors (and
+ * vice versa). Default 50.
+ */
+ maxProducerGuardLoss: number;
/**
* Maximum `external-change-rescue` checkpoints to keep per branch. These
* are written on reconcile-delete / branch-switch disk-overrode-memory
@@ -991,6 +1026,7 @@ export interface CheckpointRetentionPolicy {
export const DEFAULT_CHECKPOINT_RETENTION: CheckpointRetentionPolicy = {
maxBridgeMergeLoss: 50,
+ maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 30 * 24 * 60 * 60 * 1000,
@@ -999,6 +1035,7 @@ export const DEFAULT_CHECKPOINT_RETENTION: CheckpointRetentionPolicy = {
export interface CheckpointGcResult {
scanned: number;
deletedBridgeMergeLoss: number;
+ deletedProducerGuardLoss: number;
deletedExternalChangeRescue: number;
deletedAutoConsolidation: number;
retained: number;
@@ -1022,6 +1059,7 @@ export async function gcCheckpointRefs(
const result: CheckpointGcResult = {
scanned: 0,
deletedBridgeMergeLoss: 0,
+ deletedProducerGuardLoss: 0,
deletedExternalChangeRescue: 0,
deletedAutoConsolidation: 0,
retained: 0,
@@ -1073,7 +1111,11 @@ export async function gcCheckpointRefs(
return result;
}
- type TypedKind = 'bridge-merge-loss' | 'external-change-rescue' | 'auto-consolidation';
+ type TypedKind =
+ | 'bridge-merge-loss'
+ | 'producer-guard-loss'
+ | 'external-change-rescue'
+ | 'auto-consolidation';
interface Entry {
sha: string;
timestamp: number; // ms since epoch
@@ -1097,6 +1139,7 @@ export async function gcCheckpointRefs(
// kind to the parser without adding it here is the bug this guards against.
const byKind: Record<TypedKind, Entry[]> = {
'bridge-merge-loss': [],
+ 'producer-guard-loss': [],
'external-change-rescue': [],
'auto-consolidation': [],
};
@@ -1114,7 +1157,11 @@ export async function gcCheckpointRefs(
const planDeletions = (
list: Entry[],
limit: number,
- counter: 'deletedBridgeMergeLoss' | 'deletedExternalChangeRescue' | 'deletedAutoConsolidation',
+ counter:
+ | 'deletedBridgeMergeLoss'
+ | 'deletedProducerGuardLoss'
+ | 'deletedExternalChangeRescue'
+ | 'deletedAutoConsolidation',
// auto-consolidation is count-only: TTL must never be able to reap every
// surviving auto-checkpoint, or the chained consolidated history it anchors
// becomes unreachable. Pass false to disable the TTL lower bound.
@@ -1138,6 +1185,11 @@ export async function gcCheckpointRefs(
}
};
planDeletions(byKind['bridge-merge-loss'], policy.maxBridgeMergeLoss, 'deletedBridgeMergeLoss');
+ planDeletions(
+ byKind['producer-guard-loss'],
+ policy.maxProducerGuardLoss,
+ 'deletedProducerGuardLoss',
+ );
planDeletions(
byKind['external-change-rescue'],
policy.maxExternalChangeRescue,