Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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-tiimport * 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.tsindex 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): () => voidconst 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): () => voidconst 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): () => voidevent: '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): () => voidconst 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): () => voidrecoveryError: innerErr instanceof Error ? innerErr.message : String(innerErr),}),);- lastSyncedXmlMd = '';+ lastSyncedCanonicalMd = '';+ lastSyncedYTextBytes = '';+ canonicalWitnessCoherent = false;}}};@@ -285,7 +357,7 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidif (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): () => voiddoc.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): () => voidconst 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): () => voidsite: '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): () => voidconst 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): () => voidif (isPairedWriteOrigin(transaction.origin)) {try {const frontmatter = readCurrentFm();- lastSyncedXmlMd = ytext.toString();+ refreshYTextWitness();priorFmForTelemetry = frontmatter;} catch (err) {incrementServerObserverError('b');