Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): record Observer A baselines on the router-comparable surface (#1749)

Nick Gomeze15d8ae0381e
diff --git a/.changeset/observer-a-baseline-routing.md b/.changeset/observer-a-baseline-routing.md
new file mode 100644
index 000000000..4ee5d1759
--- /dev/null
+++ b/.changeset/observer-a-baseline-routing.md
@@ -0,0 +1,9 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fixed: the first WYSIWYG edit to a freshly loaded document no longer misroutes through a concurrent-edit merge that falsely reported divergence, and byte-unsafe constructs the canonical serializer would rewrite (un-padded GFM tables, inline-math delimiter form, PUA sentinels, multi-blank-line runs) are now preserved across WYSIWYG edits and editor mount — visually editing such a document no longer rewrites untouched constructs, and a mere editor mount no longer mutates the file on disk. Whitespace-only differences within bridge tolerance on untouched lines (e.g. the blank line between the frontmatter closer and the body that most real-world docs carry) are normalized on that first WYSIWYG edit — the documented transition behavior of the Y.Text-is-truth contract's architectural floor.
+
+For maintainers — mechanism: the sync baseline previously recorded the canonical serialization where the router strict-compares raw Y.Text bytes, so the first WYSIWYG edit after loading a non-round-trip-byte-stable doc (and after any source-mode edit Observer B absorbed) misrouted through Path B's three-way merge with telemetry falsely asserting `ytextDiverged: true`. The baseline is now split into two witnesses — canonical serialization for the fragment-unchanged short-circuit; raw Y.Text bytes for the router and the divergence-merge base — and the in-sync leg splits on residual tolerance: within tolerance routes Path A's canonical rewrite; beyond tolerance applies only the fragment's canonical-space delta onto the raw bytes via a canonical-base three-way merge. Source-mode edits within bridge tolerance (e.g. trailing whitespace) are still real divergence and still merge byte-preservingly through Path B.
+
+For operators: `observer-a-path-b-fired` and the `observerAPathBFires` / `observerAPathBFiresSuppressed` counters are now scoped strictly to real unabsorbed Y.Text divergence, and the event's `ytextDiverged` attribute is derived from the routing decision instead of hardcoded — dashboards keyed on the event will see the rate drop on residual-bearing docs whose first-edit fires were previously misclassified. The in-sync canonical-base residual merge is not a divergence fire; its volume is visible via the new `observerAResidualMergeRuns` counter and the `observer.a.path` span attribute (`path-a` | `residual-merge` | `path-b`).
diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.ts
index 8dcf99d54..d79dc2d0a 100644
--- a/packages/server/src/metrics.ts
+++ b/packages/server/src/metrics.ts
@@ -160,6 +160,17 @@ export interface ReconciliationMetrics {
* Path-B rate via `actual_rate = observerAPathBFires +
* observerAPathBFiresSuppressed`. */
observerAPathBFiresSuppressed: number;
+ /** Y.Text-is-truth contract — count of Observer A in-sync canonical-base
+ * residual merges: the byte-preserving slow path on docs whose settled
+ * bytes sit beyond `normalizeBridge` tolerance of the canonical witness.
+ * NOT a Path B fire — `observerAPathBFires`/`...Suppressed` stay scoped
+ * to real divergence. Increments on every run with no rate-limiter
+ * (there is no per-fire console event to flood), so growth on every
+ * WYSIWYG-edit drain of a beyond-tolerance doc is expected — this is the
+ * "merge machinery is hot on this doc class" volume signal operators
+ * need when triaging editor latency, which the divergence-scoped Path B
+ * counters deliberately exclude. */
+ observerAResidualMergeRuns: number;
/** Y.Text-is-truth contract (precedent #38) — count of Observer A
* settlement checks that detected a drain settling split-brain (Y.Text
* vs serialize(fragment) divergence beyond `normalizeBridge` tolerance)
@@ -337,6 +348,7 @@ const counters: ReconciliationMetrics = {
bridgeToleranceApplied: {},
observerAPathBFires: 0,
observerAPathBFiresSuppressed: 0,
+ observerAResidualMergeRuns: 0,
bridgeSplitBrainRederives: 0,
bridgeSplitBrainRederivesSuppressed: 0,
persistenceReconciliationFailures: 0,
@@ -468,6 +480,10 @@ export function incrementObserverAPathBFiresSuppressed(): void {
counters.observerAPathBFiresSuppressed++;
}
+export function incrementObserverAResidualMergeRuns(): void {
+ counters.observerAResidualMergeRuns++;
+}
+
export function incrementBridgeSplitBrainRederives(): void {
counters.bridgeSplitBrainRederives++;
}
@@ -603,6 +619,7 @@ export function resetMetrics(): void {
counters.bridgeToleranceApplied = {};
counters.observerAPathBFires = 0;
counters.observerAPathBFiresSuppressed = 0;
+ counters.observerAResidualMergeRuns = 0;
counters.bridgeSplitBrainRederives = 0;
counters.bridgeSplitBrainRederivesSuppressed = 0;
counters.persistenceReconciliationFailures = 0;
diff --git a/packages/server/src/server-observers.test.ts b/packages/server/src/server-observers.test.ts
index b3a44a4c3..8d0427a26 100644
--- a/packages/server/src/server-observers.test.ts
+++ b/packages/server/src/server-observers.test.ts
@@ -24,6 +24,7 @@ import type { LocalTransactionOrigin } from '@hocuspocus/server';
import {
MarkdownManager,
normalizeBridge,
+ prependFrontmatter,
readFmMap,
sharedExtensions,
stripFrontmatter,
@@ -33,6 +34,7 @@ import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-ti
import * as Y from 'yjs';
import { AGENT_WRITE_ORIGIN } from './agent-sessions.ts';
import { MANAGED_RENAME_ORIGIN, ROLLBACK_ORIGIN } from './api-extension.ts';
+import { composeAndWriteRawBody } from './bridge-intake.ts';
import { __resetBridgeWatchdogForTests } from './bridge-watchdog.ts';
import { FILE_WATCHER_ORIGIN } from './external-change.ts';
import { getMetrics, resetMetrics } from './metrics.ts';
@@ -886,6 +888,62 @@ describe('Server Observer B — error recovery paths', () => {
cleanup();
});
+
+ test('outer-catch recovery on a beyond-tolerance doc clears witness coherence: next in-sync fragment edit does not run a cross-generation residual merge', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const ngRaw =
+ '---\ntitle: NG recovery fixture\n---\n\n# Hello\n\nInline math: $a + b$ stays.\n\nBody text stays.\n';
+ const doc = new Y.Doc();
+ const xmlFragment = doc.getXmlFragment('default');
+ const ytext = doc.getText('source');
+ doc.transact(() => {
+ composeAndWriteRawBody(doc, ngRaw, 'file-watcher');
+ }, FILE_WATCHER_ORIGIN);
+
+ const stub = createMdManagerStub();
+ const recorder = createDispatchRecorder();
+ const cleanup = setupServerObservers(
+ setupOpts({
+ doc,
+ xmlFragment,
+ ytext,
+ recorder,
+ mdManager: stub.mdManager,
+ docName: 'recovery-ng-coherence',
+ }),
+ );
+ expect(ytext.toString()).toBe(ngRaw);
+
+ const originalConsoleError = console.error;
+ console.error = () => {};
+ stub.setParseThrow(new Error('unexpected parse failure'));
+ doc.transact(() => {
+ ytext.insert(ytext.length, '\nUnabsorbed line.\n');
+ });
+ stub.setParseThrow(null);
+ console.error = originalConsoleError;
+
+ doc.transact(() => {
+ ytext.delete(0, ytext.length);
+ ytext.insert(0, ngRaw);
+ }, OBSERVER_SYNC_ORIGIN);
+ expect(ytext.toString()).toBe(ngRaw);
+
+ const body = mdManager.serialize(
+ yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON(),
+ );
+ populateFragment(doc, xmlFragment, `${body}\nPost-recovery edit.\n`);
+
+ expect(getMetrics().observerAResidualMergeRuns).toBe(0);
+ expect(getMetrics().observerAPathBFires + getMetrics().observerAPathBFiresSuppressed).toBe(0);
+ const finalText = ytext.toString();
+ expect(finalText).toContain('Post-recovery edit.');
+ expect(finalText).not.toContain('Unabsorbed line.');
+
+ cleanup();
+ });
});
@@ -985,3 +1043,428 @@ describe('Server Observer B — Y.Text-is-truth contract (FR-31)', () => {
cleanup();
});
});
+
+
+describe('Observer A routing — Path B fires iff Y.Text holds unabsorbed changes (FR-3)', () => {
+
+ const RESIDUAL_RAW = '---\ntitle: Routing fixture\n---\n\n# Hello\n\nBody text stays.\n';
+
+ function canonicalOf(raw: string): string {
+ const { frontmatter, body } = stripFrontmatter(raw);
+ return prependFrontmatter(frontmatter, mdManager.serialize(mdManager.parseWithFallback(body)));
+ }
+
+ function seedThenAttach(raw: string, docName: string) {
+ const doc = new Y.Doc();
+ const xmlFragment = doc.getXmlFragment('default');
+ const ytext = doc.getText('source');
+ doc.transact(() => {
+ composeAndWriteRawBody(doc, raw, 'file-watcher');
+ }, FILE_WATCHER_ORIGIN);
+ const recorder = createDispatchRecorder();
+ const cleanup = setupServerObservers(setupOpts({ doc, xmlFragment, ytext, recorder, docName }));
+ return { doc, xmlFragment, ytext, recorder, cleanup };
+ }
+
+ function serializeFragmentBody(xmlFragment: Y.XmlFragment): string {
+ return mdManager.serialize(yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON());
+ }
+
+ function capturePathBEvents(fn: () => void): Record<string, unknown>[] {
+ const originalWarn = console.warn;
+ const warnings: string[] = [];
+ console.warn = (...args: unknown[]) => {
+ warnings.push(args.map(String).join(' '));
+ };
+ try {
+ fn();
+ } finally {
+ console.warn = originalWarn;
+ }
+ return warnings
+ .map((w) => {
+ try {
+ return JSON.parse(w);
+ } catch {
+ return null;
+ }
+ })
+ .filter((e): e is Record<string, unknown> => e !== null)
+ .filter((e) => e.event === 'observer-a-path-b-fired');
+ }
+
+ /** Total Path B fires — emit-gated counter + suppressed counter covers
+ * every fire even when the per-doc rate-limiter closes. */
+ const totalPathBFires = (): number =>
+ getMetrics().observerAPathBFires + getMetrics().observerAPathBFiresSuppressed;
+
+ test('residual-bearing doc seeded production-order: first fragment change does not fire Path B and converges', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ expect(canonicalOf(RESIDUAL_RAW)).not.toBe(RESIDUAL_RAW);
+ expect(normalizeBridge(canonicalOf(RESIDUAL_RAW))).toBe(normalizeBridge(RESIDUAL_RAW));
+
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(
+ RESIDUAL_RAW,
+ 'routing-residual-first-edit',
+ );
+ expect(ytext.toString()).toBe(RESIDUAL_RAW);
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ populateFragment(
+ doc,
+ xmlFragment,
+ `${serializeFragmentBody(xmlFragment)}\nUser WYSIWYG edit.\n`,
+ );
+ });
+
+ expect(events).toHaveLength(0);
+ expect(totalPathBFires()).toBe(firesBefore);
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('User WYSIWYG edit.');
+ expect(finalText).toContain('Body text stays.');
+ expect(finalText).toContain('# Hello');
+ expect(finalText).toContain('title: Routing fixture');
+
+ cleanup();
+ });
+
+ test('after Observer B fully absorbs a raw-form source edit, the next fragment change does not fire Path B', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const canon = canonicalOf(RESIDUAL_RAW);
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(canon, 'routing-post-absorb');
+
+ doc.transact(() => {
+ ytext.insert(ytext.length, '## Added via source\n');
+ });
+ expect(serializeFragmentBody(xmlFragment)).toContain('Added via source');
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ populateFragment(
+ doc,
+ xmlFragment,
+ `${serializeFragmentBody(xmlFragment)}\nWysiwyg paragraph.\n`,
+ );
+ });
+
+ expect(events).toHaveLength(0);
+ expect(totalPathBFires()).toBe(firesBefore);
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('Added via source');
+ expect(finalText).toContain('Wysiwyg paragraph.');
+ expect(finalText).toContain('Body text stays.');
+
+ cleanup();
+ });
+
+ test('control: parse-invisible source edit is real unabsorbed divergence — next fragment change MUST fire Path B', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const canon = canonicalOf(RESIDUAL_RAW);
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(canon, 'routing-real-divergence');
+
+ const spaceAt = canon.indexOf('# Hello') + '# Hello'.length;
+ doc.transact(() => {
+ ytext.insert(spaceAt, ' ');
+ });
+ expect(ytext.toString()).toContain('# Hello \n');
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ populateFragment(
+ doc,
+ xmlFragment,
+ `${serializeFragmentBody(xmlFragment)}\nAnother wysiwyg edit.\n`,
+ );
+ });
+
+ expect(totalPathBFires()).toBeGreaterThan(firesBefore);
+ expect(events.length).toBeGreaterThanOrEqual(1);
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('# Hello \n');
+ expect(finalText).toContain('Another wysiwyg edit.');
+
+ cleanup();
+ });
+
+ test('gate 1: serialization-neutral fragment event on a residual doc settles with zero observer writes', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const { doc, xmlFragment, ytext, recorder, cleanup } = seedThenAttach(
+ RESIDUAL_RAW,
+ 'routing-gate1-neutral',
+ );
+ expect(ytext.toString()).toBe(RESIDUAL_RAW);
+ const bodyBefore = serializeFragmentBody(xmlFragment);
+
+ let observerWrites = 0;
+ doc.on('afterTransaction', (tx: Y.Transaction) => {
+ if (tx.origin === OBSERVER_SYNC_ORIGIN) observerWrites++;
+ });
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ doc.transact(() => {
+ const replacement = new Y.XmlElement('paragraph');
+ const text = new Y.XmlText();
+ text.insert(0, 'Body text stays.');
+ replacement.insert(0, [text]);
+ xmlFragment.insert(xmlFragment.length, [replacement]);
+ xmlFragment.delete(xmlFragment.length - 2, 1);
+ });
+ });
+
+ expect(recorder.dispatches).toContain('a');
+ expect(serializeFragmentBody(xmlFragment)).toBe(bodyBefore);
+
+ expect(observerWrites).toBe(0);
+ expect(events).toHaveLength(0);
+ expect(totalPathBFires()).toBe(firesBefore);
+ expect(ytext.toString()).toBe(RESIDUAL_RAW);
+
+ cleanup();
+ });
+
+ test('gate 1: stale canonical witness after a paired-write reset does NOT short-circuit a fragment edit that re-matches it (CB-CONTRACT-10 regression)', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const IMG = '<img src="x.png" alt="x" />\n';
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(IMG, 'gate1-stale-canonical');
+
+ const emptyRaw = '\n';
+ const emptyJson = mdManager.parse(emptyRaw);
+ const emptyNode = schema.nodeFromJSON(emptyJson);
+ doc.transact(() => {
+ const meta = { mapping: new Map(), isOMark: new Map() };
+ updateYFragment(doc, xmlFragment, emptyNode, meta);
+ ytext.delete(0, ytext.length);
+ ytext.insert(0, mdManager.serialize(emptyJson));
+ }, AGENT_WRITE_ORIGIN);
+ expect(ytext.toString().includes('<img')).toBe(false);
+
+ populateFragment(doc, xmlFragment, IMG);
+
+ expect(ytext.toString()).toContain('<img');
+ expect(ytext.toString()).toContain('src="x.png"');
+
+ cleanup();
+ });
+
+ test('control: round-trip-stable doc seeded production-order — first fragment change does not fire Path B', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const canon = canonicalOf(RESIDUAL_RAW);
+ expect(canonicalOf(canon)).toBe(canon);
+
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(canon, 'routing-stable-control');
+ expect(ytext.toString()).toBe(canon);
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ populateFragment(
+ doc,
+ xmlFragment,
+ `${serializeFragmentBody(xmlFragment)}\nPlain wysiwyg edit.\n`,
+ );
+ });
+
+ expect(events).toHaveLength(0);
+ expect(totalPathBFires()).toBe(firesBefore);
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('Plain wysiwyg edit.');
+ expect(finalText).toContain('Body text stays.');
+
+ cleanup();
+ });
+
+ const NG_RAW =
+ '---\ntitle: NG routing fixture\n---\n\n# Hello\n\nInline math: $a + b$ stays.\n\nBody text stays.\n';
+
+ test('in-sync doc with beyond-tolerance residual: fragment change preserves NG bytes without a Path B fire', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ expect(canonicalOf(NG_RAW)).not.toBe(NG_RAW);
+ expect(normalizeBridge(canonicalOf(NG_RAW))).not.toBe(normalizeBridge(NG_RAW));
+
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(NG_RAW, 'routing-ng-in-sync');
+ expect(ytext.toString()).toBe(NG_RAW);
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ populateFragment(
+ doc,
+ xmlFragment,
+ `${serializeFragmentBody(xmlFragment)}\nUser WYSIWYG edit.\n`,
+ );
+ });
+
+ expect(events).toHaveLength(0);
+ expect(totalPathBFires()).toBe(firesBefore);
+ expect(getMetrics().observerAResidualMergeRuns).toBe(1);
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('User WYSIWYG edit.');
+ expect(finalText).toContain('Inline math: $a + b$ stays.');
+ expect(finalText).not.toContain('$$a + b$$');
+ expect(finalText).toContain('Body text stays.');
+
+ cleanup();
+ });
+
+ test('control: real divergence on a beyond-tolerance doc fires Path B — divergence beats the residual merge', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(NG_RAW, 'routing-ng-divergence');
+
+ const spaceAt = NG_RAW.indexOf('# Hello') + '# Hello'.length;
+ doc.transact(() => {
+ ytext.insert(spaceAt, ' ');
+ });
+ expect(ytext.toString()).toContain('# Hello \n');
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ populateFragment(
+ doc,
+ xmlFragment,
+ `${serializeFragmentBody(xmlFragment)}\nAnother wysiwyg edit.\n`,
+ );
+ });
+
+ expect(totalPathBFires()).toBeGreaterThan(firesBefore);
+ expect(events.length).toBeGreaterThanOrEqual(1);
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('# Hello \n');
+ expect(finalText).toContain('Another wysiwyg edit.');
+
+ cleanup();
+ });
+
+ test('consecutive in-sync fragment edits on a beyond-tolerance doc each run the residual merge: the post-merge settlement restores coherence', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ expect(normalizeBridge(canonicalOf(NG_RAW))).not.toBe(normalizeBridge(NG_RAW));
+
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(NG_RAW, 'routing-ng-consecutive');
+ expect(ytext.toString()).toBe(NG_RAW);
+
+ const firesBefore = totalPathBFires();
+
+ const events1 = capturePathBEvents(() => {
+ populateFragment(doc, xmlFragment, `${serializeFragmentBody(xmlFragment)}\nFirst edit.\n`);
+ });
+ expect(events1).toHaveLength(0);
+ expect(getMetrics().observerAResidualMergeRuns).toBe(1);
+ expect(ytext.toString()).toContain('Inline math: $a + b$ stays.');
+ expect(ytext.toString()).not.toContain('$$a + b$$');
+
+ const events2 = capturePathBEvents(() => {
+ populateFragment(doc, xmlFragment, `${serializeFragmentBody(xmlFragment)}\nSecond edit.\n`);
+ });
+ expect(events2).toHaveLength(0);
+ expect(getMetrics().observerAResidualMergeRuns).toBe(2);
+ expect(totalPathBFires()).toBe(firesBefore);
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('First edit.');
+ expect(finalText).toContain('Second edit.');
+ expect(finalText).toContain('Inline math: $a + b$ stays.');
+ expect(finalText).not.toContain('$$a + b$$');
+
+ cleanup();
+ });
+
+ test('paired write on a beyond-tolerance doc clears coherence: the next in-sync fragment edit takes the Path-A fallback, not the residual merge', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const { doc, xmlFragment, ytext, recorder, cleanup } = seedThenAttach(
+ NG_RAW,
+ 'routing-ng-paired-clears-coherence',
+ );
+ expect(ytext.toString()).toBe(NG_RAW);
+
+ const pairedRaw =
+ '---\ntitle: NG routing fixture\n---\n\n# Hello\n\nInline math: $a + b$ stays.\n\nPaired body.\n';
+ expect(normalizeBridge(canonicalOf(pairedRaw))).not.toBe(normalizeBridge(pairedRaw));
+ const pairedJson = mdManager.parse(stripFrontmatter(pairedRaw).body);
+ const pairedNode = schema.nodeFromJSON(pairedJson);
+ doc.transact(() => {
+ const meta = { mapping: new Map(), isOMark: new Map() };
+ updateYFragment(doc, xmlFragment, pairedNode, meta);
+ ytext.delete(0, ytext.length);
+ ytext.insert(0, pairedRaw);
+ }, AGENT_WRITE_ORIGIN);
+ expect(recorder.dispatches.filter((k) => k !== 'none')).toHaveLength(0);
+ expect(ytext.toString()).toBe(pairedRaw);
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ populateFragment(
+ doc,
+ xmlFragment,
+ `${serializeFragmentBody(xmlFragment)}\nPost-paired edit.\n`,
+ );
+ });
+
+ expect(getMetrics().observerAResidualMergeRuns).toBe(0);
+ expect(events).toHaveLength(0);
+ expect(totalPathBFires()).toBe(firesBefore);
+ expect(ytext.toString()).toContain('Post-paired edit.');
+
+ cleanup();
+ });
+
+ test('diverged attach: next fragment change routes Path B against the fragment-canonical base and Y.Text-only content survives exactly once', () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+
+ const doc = new Y.Doc();
+ const xmlFragment = doc.getXmlFragment('default');
+ const ytext = doc.getText('source');
+ populateFragment(doc, xmlFragment, '# Hello\n\nFragment body.\n');
+ doc.transact(() => {
+ ytext.insert(0, '# Hello\n\nYtext-only line.\n\nFragment body.\n');
+ });
+ const recorder = createDispatchRecorder();
+ const cleanup = setupServerObservers(
+ setupOpts({ doc, xmlFragment, ytext, recorder, docName: 'routing-diverged-attach' }),
+ );
+
+ const firesBefore = totalPathBFires();
+ const events = capturePathBEvents(() => {
+ populateFragment(
+ doc,
+ xmlFragment,
+ `${serializeFragmentBody(xmlFragment)}\nUser WYSIWYG edit.\n`,
+ );
+ });
+
+ expect(totalPathBFires()).toBeGreaterThan(firesBefore);
+ expect(events.length).toBeGreaterThanOrEqual(1);
+
+ const finalText = ytext.toString();
+ expect(finalText.split('Ytext-only line.').length).toBe(2);
+ expect(finalText).toContain('User WYSIWYG edit.');
+ expect(finalText).toContain('Fragment body.');
+
+ cleanup();
+ });
+});
diff --git a/packages/server/src/server-observers.ts b/packages/server/src/server-observers.ts
index c85e14a54..8086d8df0 100644
--- a/packages/server/src/server-observers.ts
+++ b/packages/server/src/server-observers.ts
@@ -27,11 +27,12 @@ import {
incrementBridgeMergeContentLoss,
incrementBridgeSplitBrainRederives,
incrementObserverAPathBFires,
+ incrementObserverAResidualMergeRuns,
incrementServerObserverError,
incrementServerObserverFire,
} from './metrics.ts';
import { type ShadowHandle, saveInMemoryCheckpoint } from './shadow-repo.ts';
-import { withSpanSync } from './telemetry.ts';
+import { setActiveSpanAttributes, withSpanSync } from './telemetry.ts';
export const OBSERVER_SYNC_ORIGIN = {
@@ -47,7 +48,7 @@ export type PairedWriteOrigin = LocalTransactionOrigin & {
};
};
-export const isPairedWriteOrigin = (origin: unknown): boolean => {
+export const isPairedWriteOrigin = (origin: unknown): origin is PairedWriteOrigin => {
if (origin == null || typeof origin !== 'object') return false;
const ctx = (origin as { context?: { paired?: boolean } }).context;
return ctx?.paired === true;
@@ -157,24 +158,70 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
}
};
- let lastSyncedXmlMd = '';
+ let lastSyncedCanonicalMd = '';
+ let lastSyncedYTextBytes = '';
+ let canonicalWitnessCoherent = false;
let xmlDirty = false;
let textDirty = false;
+ const refreshYTextWitness = (): void => {
+ lastSyncedYTextBytes = ytext.toString();
+ canonicalWitnessCoherent = false;
+ };
+
+ const recordSettledBaselines = (canonicalMd: string): void => {
+ lastSyncedCanonicalMd = canonicalMd;
+ refreshYTextWitness();
+ canonicalWitnessCoherent = canonicalMd !== '';
+ };
+
+ const recordDivergedAttachBaselines = (canonicalMd: string): void => {
+ lastSyncedCanonicalMd = canonicalMd;
+ lastSyncedYTextBytes = canonicalMd;
+ canonicalWitnessCoherent = false;
+ };
+
+ const refreshCanonicalWitnessOnly = (canonicalMd: string): void => {
+ lastSyncedCanonicalMd = canonicalMd;
+ canonicalWitnessCoherent = false;
+ };
+
+ const recordSplitBrainRecoveryBaselines = (canonicalMd: string): void => {
+ lastSyncedCanonicalMd = canonicalMd;
+ lastSyncedYTextBytes = ytext.toString();
+ canonicalWitnessCoherent = true;
+ };
+
const readCurrentFm = (): string => stripFrontmatter(ytext.toString()).frontmatter;
try {
const initialJson = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
const initialBody = mdManager.serialize(initialJson);
const initialFrontmatter = readCurrentFm();
- lastSyncedXmlMd = prependFrontmatter(initialFrontmatter, initialBody);
+ const canonicalInit = prependFrontmatter(initialFrontmatter, initialBody);
+ const initParseOpts =
+ opts.resolveEmbed && opts.docName
+ ? {
+ resolveEmbed: opts.resolveEmbed,
+ resolveSize: opts.resolveSize,
+ sourcePath: opts.docName,
+ }
+ : undefined;
+ const ytextCanonicalBody = mdManager.serialize(
+ mdManager.parseWithFallback(stripFrontmatter(ytext.toString()).body, initParseOpts),
+ );
+ if (ytextCanonicalBody === initialBody) {
+ recordSettledBaselines(canonicalInit);
+ } else {
+ recordDivergedAttachBaselines(canonicalInit);
+ }
} catch (err) {
incrementServerObserverError('a');
console.warn(
'[Server Observer A] Baseline init failed — starting from empty snapshot:',
err instanceof Error ? err.message : String(err),
);
- lastSyncedXmlMd = '';
+ recordSettledBaselines('');
}
const runObserverASyncImpl = (): void => {
@@ -184,10 +231,14 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const frontmatter = readCurrentFm();
const md = prependFrontmatter(frontmatter, body);
- if (lastSyncedXmlMd === md) {
+ if (canonicalWitnessCoherent && lastSyncedCanonicalMd === md) {
if (settlesSplitBrain(ytext.toString(), md)) {
+ recordDivergedAttachBaselines(md);
textDirty = true;
recordSplitBrainRederive('identity-gate');
+ setActiveSpanAttributes({ 'observer.a.path': 'gated-fragment-unchanged-rederive' });
+ } else {
+ setActiveSpanAttributes({ 'observer.a.path': 'gated-fragment-unchanged' });
}
return;
}
@@ -195,18 +246,32 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const currentText = ytext.toString();
if (normalizeBridge(currentText) === normalizeBridge(md)) {
- lastSyncedXmlMd = md;
+ setActiveSpanAttributes({ 'observer.a.path': 'gated-in-sync' });
+ recordSettledBaselines(md);
return;
}
- const preMergeBaseline = lastSyncedXmlMd;
+ const preMergeBaseline = lastSyncedYTextBytes;
+ const ytextInSync = currentText === lastSyncedYTextBytes;
+ const residualInTolerance =
+ lastSyncedYTextBytes === lastSyncedCanonicalMd ||
+ normalizeBridge(lastSyncedYTextBytes) === normalizeBridge(lastSyncedCanonicalMd);
+ const residualMergeEligible = canonicalWitnessCoherent && !residualInTolerance;
+ setActiveSpanAttributes({
+ 'observer.a.path': ytextInSync
+ ? residualMergeEligible
+ ? 'residual-merge'
+ : 'path-a'
+ : 'path-b',
+ });
const pathBState: { mergedText: string | null } = { mergedText: null };
doc.transact(() => {
- if (currentText === lastSyncedXmlMd) {
+ if (ytextInSync && !residualMergeEligible) {
applyIncrementalDiff(ytext, currentText, md);
} else {
+ const mergeBase = ytextInSync ? lastSyncedCanonicalMd : preMergeBaseline;
try {
- const mergedText = mergeThreeWay(lastSyncedXmlMd, md, currentText);
+ const mergedText = mergeThreeWay(mergeBase, md, currentText);
applyFastDiff(ytext, currentText, mergedText);
pathBState.mergedText = mergedText;
} catch (mergeErr) {
@@ -219,7 +284,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
}
}, OBSERVER_SYNC_ORIGIN);
- if (pathBState.mergedText !== null) {
+ if (pathBState.mergedText !== null && !ytextInSync) {
if (emitObserverAPathBFired(opts.docName)) {
incrementObserverAPathBFires();
console.warn(
@@ -227,23 +292,28 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
event: 'observer-a-path-b-fired',
'doc.name': opts.docName ?? null,
xmlFragmentAdvanced: true,
- ytextDiverged: true,
+ ytextDiverged: !ytextInSync,
mergeBytesChanged: Math.abs(pathBState.mergedText.length - currentText.length),
}),
);
}
}
+ if (pathBState.mergedText !== null && ytextInSync) {
+ incrementObserverAResidualMergeRuns();
+ }
+
incrementServerObserverFire('a');
- const settledText = ytext.toString();
- if (settlesSplitBrain(settledText, md)) {
- lastSyncedXmlMd = md;
+ recordSettledBaselines(md);
+
+ if (settlesSplitBrain(ytext.toString(), md)) {
textDirty = true;
recordSplitBrainRederive('post-merge');
- } else {
- lastSyncedXmlMd = settledText;
}
} catch (err) {
+ if (err instanceof BridgeMergeContentLossError) {
+ throw err;
+ }
incrementServerObserverError('a');
console.error('[Server Observer A] Failed to sync tree→text:', err);
try {
@@ -251,11 +321,11 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const recoveryBody = mdManager.serialize(recoveryJson);
const recoveryMd = prependFrontmatter(readCurrentFm(), recoveryBody);
if (settlesSplitBrain(ytext.toString(), recoveryMd)) {
- lastSyncedXmlMd = recoveryMd;
+ recordSplitBrainRecoveryBaselines(recoveryMd);
textDirty = true;
recordSplitBrainRederive('error-recovery');
} else {
- lastSyncedXmlMd = ytext.toString();
+ recordSettledBaselines(recoveryMd);
}
} catch (innerErr) {
console.warn(
@@ -266,7 +336,9 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
recoveryError: innerErr instanceof Error ? innerErr.message : String(innerErr),
}),
);
- lastSyncedXmlMd = '';
+ lastSyncedCanonicalMd = '';
+ lastSyncedYTextBytes = '';
+ canonicalWitnessCoherent = false;
}
}
};
@@ -285,7 +357,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
if (isPairedWriteOrigin(transaction.origin)) {
try {
const frontmatter = readCurrentFm();
- lastSyncedXmlMd = ytext.toString();
+ refreshYTextWitness();
priorFmForTelemetry = frontmatter;
} catch (err) {
incrementServerObserverError('a');
@@ -310,11 +382,11 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
doc.transact(() => {
ytext.insert(0, md);
}, OBSERVER_SYNC_ORIGIN);
- lastSyncedXmlMd = md;
+ recordSettledBaselines(md);
} catch (err) {
incrementServerObserverError('a');
console.error('[Server Observer A] Failed initial sync:', err);
- lastSyncedXmlMd = '';
+ recordSettledBaselines('');
}
}
@@ -325,7 +397,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const md = ytext.toString();
const { frontmatter, body } = stripFrontmatter(md);
- if (normalizeBridge(lastSyncedXmlMd) === normalizeBridge(md)) {
+ if (normalizeBridge(lastSyncedYTextBytes) === normalizeBridge(md)) {
if (priorFmForTelemetry !== frontmatter) {
recordFrontmatterEditSurface('source-mode');
priorFmForTelemetry = frontmatter;
@@ -364,7 +436,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
site: 'observer-b',
docName: opts.docName,
});
- lastSyncedXmlMd = canonicalYText;
+ recordSettledBaselines(canonicalYText);
} catch (reserializeErr) {
if (reserializeErr instanceof BridgeInvariantViolationError) {
throw reserializeErr;
@@ -373,7 +445,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
'[Server Observer B] Post-sync re-serialization failed — using input body as baseline:',
reserializeErr,
);
- lastSyncedXmlMd = prependFrontmatter(frontmatter, body);
+ recordSettledBaselines(prependFrontmatter(frontmatter, body));
}
} catch (err) {
if (err instanceof BridgeInvariantViolationError) {
@@ -385,7 +457,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
const postJson = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
const postBody = mdManager.serialize(postJson);
const fm = readCurrentFm();
- lastSyncedXmlMd = prependFrontmatter(fm, postBody);
+ refreshCanonicalWitnessOnly(prependFrontmatter(fm, postBody));
} catch (innerErr) {
if (innerErr instanceof BridgeInvariantViolationError) {
throw innerErr;
@@ -409,7 +481,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
if (isPairedWriteOrigin(transaction.origin)) {
try {
const frontmatter = readCurrentFm();
- lastSyncedXmlMd = ytext.toString();
+ refreshYTextWitness();
priorFmForTelemetry = frontmatter;
} catch (err) {
incrementServerObserverError('b');