Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.jsonindex 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsindex 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.tssimilarity index 93%rename from packages/app/src/editor/extensions/source-dirty-observer.test.tsrename to packages/app/src/editor/extensions/source-dirty-serialize.test.tsindex 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.tsxnew file mode 100644index 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.tsindex 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 ` `/`	` 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(' deepIndented'); // no char-ref injection in fence+ expect(after).not.toContain('	'); // 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 fallbackdiff --git a/packages/core/src/shadow-repo-layout.ts b/packages/core/src/shadow-repo-layout.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.enreturn 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): () => voidlet 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): () => voidrecordSettledBaselines('');}+ // 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): () => voidconst 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): () => voidif (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): () => voidreturn;}+ lastExternalYtextChangeMs = Date.now();textDirty = true;};diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.tsindex 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.tsindex 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,