Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

57.4 KB
Raw Blame
/**
 * Client observer cross-CRDT write paths are deleted (not gated) — see precedent #14. Dispatch
 * model (precedent #13(b)): the observers use `doc.on('afterAllTransactions', ...)` — per-drain,
 * not per-transaction, and not a wall-clock `setTimeout` debounce.
 */

import type { LocalTransactionOrigin } from '@hocuspocus/server';
import type {
  BridgeComposition,
  MarkdownManager,
  PmStructuralNode,
  StructuralDivergenceReason,
} from '@inkeep/open-knowledge-core';
import {
  addsBlankLines,
  applyFastDiff,
  applyIncrementalDiff,
  BridgeInvariantViolationError,
  BridgeMergeContentLossError,
  comparePmStructural,
  composeWithDerivedBody,
  createMergeBoundarySpace,
  DUPLICATION_GATE_MIN_LINE_LENGTH,
  docEdgeRunsDiffer,
  documentBodyLineEnding,
  findDroppedSourceContentInRange,
  fnv1aDigest,
  fragmentHoldsPendingContent,
  isParseEquivalentBridge,
  mergeThreeWay,
  normalizeBridge,
  overMultipliedBodyLines,
  pendingContentLines,
  prependFrontmatter,
  spellLineEndings,
  splitFmBoundarySlot,
  stripFrontmatter,
} from '@inkeep/open-knowledge-core';
import type { JSONContent } from '@tiptap/core';
import type { Schema } from '@tiptap/pm/model';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import * as Y from 'yjs';
import { detectApplyArmDrop } from './bridge-loss-detector.ts';
import { attachQuiescenceTracker } from './bridge-quiescence.ts';
import {
  assertBridgeInvariant,
  type BridgeSplitBrainSite,
  createDocCanonicalizer,
  emitBridgeSplitBrainRederive,
  emitObserverAPathBFired,
} from './bridge-watchdog.ts';
import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';
import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
import { getLogger } from './logger.ts';
import {
  LOSS_EVENT_BACKSTOP_TRIP,
  LOSS_EVENT_CHECKPOINT_WRITE,
  LOSS_EVENT_DETECTOR_TRIP,
  LOSS_EVENT_GUARD_DEFER,
  type LossCaptureRing,
} from './loss-capture.ts';
import {
  computeMapDrivenBodySplice,
  createEditorMdastMemo,
  type EditorMdastMemo,
  type SerializedEditorBody,
  serializeEditorBody,
} from './map-driven-splice.ts';
import {
  incrementBridgeMergeCheckpointCreated,
  incrementBridgeMergeContentGrowth,
  incrementBridgeMergeContentLoss,
  incrementBridgeSplitBrainRederives,
  incrementDeriveTimingDeferForceResolved,
  incrementMapDrivenSpliceApplied,
  incrementMapDrivenSpliceFallback,
  incrementMapDrivenSpliceMemoHit,
  incrementMapDrivenSpliceMemoSkip,
  incrementObserverAApplyLoss,
  incrementObserverAApplyLossCheckpointCreated,
  incrementObserverADuplicationCheckpointCreated,
  incrementObserverADuplicationRederives,
  incrementObserverAPathBFires,
  incrementObserverAResidualMergeRuns,
  incrementObserverAResidualMergeSpliceBlockedLossy,
  incrementObserverAResidualMergeSpliceLanded,
  incrementObserverAResidualMergeSpliceUnavailable,
  incrementProducerGuardCheckpointCreated,
  incrementProducerGuardFires,
  incrementProducerGuardFiresSuppressed,
  incrementReDeriveBackstopTripped,
  incrementServerObserverError,
  incrementServerObserverFire,
  type MapDrivenSpliceFallbackReason,
  type ResidualMergeSpliceUnavailableReason,
} from './metrics.ts';
import {
  type PreDrainController,
  type PreDrainOpInput,
  type PreDrainVerdict,
  planPreDrain,
} from './pre-drain-discriminator.ts';
import { registerBridgeDirtyProbe } from './server-workload-telemetry.ts';
import { type ShadowHandle, saveInMemoryCheckpoint } from './shadow-repo.ts';
import { setActiveSpanAttributes, withSpanSync } from './telemetry.ts';

const log = getLogger('server-observers');

const checkpointLog = getLogger('server-observers');

/**
 * Transaction origin for server observer cross-CRDT writes: an object reference per precedent #1,
 * because identity matching in `Set.has`, `trackedOrigins` and the bridge watcher's enforcing sets
 * needs the exact ref. `skipStoreHooks` breaks the observer-persistence-watcher feedback loop.
 */
export const OBSERVER_SYNC_ORIGIN = {
  source: 'local',
  skipStoreHooks: true,
  context: { origin: 'observer-sync' },
} as const satisfies LocalTransactionOrigin;

/** Compile-time extension of precedent #1. */
export type PairedWriteOrigin = LocalTransactionOrigin & {
  readonly context: {
    readonly origin: string;
    readonly paired: true;
  };
};

/** Semantic match (precedent #1 extension). */
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;
};

const isConnectionOrigin = (origin: unknown): boolean =>
  origin != null &&
  typeof origin === 'object' &&
  (origin as { source?: unknown }).source === 'connection';

export function shouldRethrowBridgeMergeLoss(env: NodeJS.ProcessEnv = process.env): boolean {
  return env.NODE_ENV === 'test' || env.OK_RETHROW_BRIDGE_LOSS === '1';
}

export interface ProducerGuardViolationInfo {
  docName?: string;
  reason: StructuralDivergenceReason;
  detail: string;
}

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;
  }
}

const PRODUCER_GUARD_DANGER_TYPES = new Set(['jsxComponent', 'table', 'tableCell', 'tableHeader']);

/**
 * Drain-count based, so it stays honest under the no-wall-clock rule (precedent #13(b)): the bound
 * is "how many re-derive drains have been withheld," never elapsed time.
 */
const MAX_DERIVE_TIMING_DEFERS = 8;

/** Drain-count based (never wall-clock, precedent #13(b)). */
const MAX_REDERIVE_ROUNDS = 8;

const MERGE_BOUNDARY_SITE = 'merge-boundary';

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;
}

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(',');
}

interface YTextMapDrivenSplice {
  readonly spliceStart: number;
  readonly spliceEnd: number;
  readonly newSlice: string;
}

interface TryComputeMapDrivenSpliceArgs {
  readonly currentText: string;
  readonly lastSyncedXmlMd: string;
  readonly mdManager: MarkdownManager;
  readonly docName: string | undefined;
  readonly mdastMemo: EditorMdastMemo;
  readonly serializedNewPm: SerializedEditorBody;
  readonly onResidualFallback?: (reason: MapDrivenSpliceFallbackReason) => void;
}

let mapDrivenParseErrorWarned = false;

export function __resetMapDrivenParseErrorWarnForTests(): void {
  mapDrivenParseErrorWarned = false;
}

function warnOnceMapDrivenParseError(docName: string | undefined, err: unknown): void {
  if (mapDrivenParseErrorWarned) return;
  mapDrivenParseErrorWarned = true;
  log.warn(
    { docName: docName ?? 'unknown', err: err instanceof Error ? err : new Error(String(err)) },
    `[Server Observer A] Map-driven splice parse/serialize threw (doc: ${docName ?? 'unknown'}); drains fall back to the incremental diff (warned once; further failures count in mapDrivenSpliceFallback only)`,
  );
}

let memoComposeFailureWarned = false;

export function __resetMemoComposeFailureWarnForTests(): void {
  memoComposeFailureWarned = false;
}

function warnOnceMemoComposeFailure(docName: string | undefined, err: unknown): void {
  if (memoComposeFailureWarned) return;
  memoComposeFailureWarned = true;
  log.warn(
    { docName: docName ?? 'unknown', err: err instanceof Error ? err : new Error(String(err)) },
    `[Server Observer A] Spliced-body memo composition threw (doc: ${docName ?? 'unknown'}); the splice is unaffected and the next drain re-parses (warned once; further failures count in mapDrivenSpliceMemoSkips only)`,
  );
}

function tryComputeMapDrivenSplice(
  args: TryComputeMapDrivenSpliceArgs,
): YTextMapDrivenSplice | null {
  const {
    currentText,
    lastSyncedXmlMd,
    mdManager,
    docName,
    mdastMemo,
    serializedNewPm,
    onResidualFallback,
  } = args;
  const countsSpliceMetrics = onResidualFallback === undefined;
  const countFallback = (reason: MapDrivenSpliceFallbackReason): void => {
    if (onResidualFallback) onResidualFallback(reason);
    else incrementMapDrivenSpliceFallback(reason);
  };
  const newPmJson = serializedNewPm.json;
  if (currentText !== lastSyncedXmlMd) {
    countFallback('text-mismatch');
    return null;
  }
  if (docName !== undefined && (isSystemDoc(docName) || isConfigDoc(docName))) {
    countFallback('synthetic-doc');
    return null;
  }

  const { body: oldBody } = stripFrontmatter(currentText);
  const bodyOffset = currentText.length - oldBody.length;
  const splice = computeMapDrivenBodySplice(oldBody, newPmJson, mdManager, {
    onFallback: (reason, err) => {
      countFallback(reason);
      if (reason === 'parse-error') warnOnceMapDrivenParseError(docName, err);
    },
    onMemoHit: () => {
      if (countsSpliceMetrics) incrementMapDrivenSpliceMemoHit();
    },
    onMemoSkip: (reason, err) => {
      if (countsSpliceMetrics) incrementMapDrivenSpliceMemoSkip(reason);
      if (reason === 'compose-failed') warnOnceMemoComposeFailure(docName, err);
    },
    memo: mdastMemo,
    serializedNewPm,
    lineEnding: documentBodyLineEnding(currentText),
  });
  if (!splice) return null;

  return {
    spliceStart: bodyOffset + splice.spliceStart,
    spliceEnd: bodyOffset + splice.spliceEnd,
    newSlice: splice.newSlice,
  };
}

function applyMapDrivenSplice(ytext: Y.Text, splice: YTextMapDrivenSplice): void {
  const deleteLength = splice.spliceEnd - splice.spliceStart;
  if (deleteLength > 0) ytext.delete(splice.spliceStart, deleteLength);
  if (splice.newSlice.length > 0) ytext.insert(splice.spliceStart, splice.newSlice);
}

const preDrainControllers = new WeakMap<Y.Doc, PreDrainController>();

export function getPreDrainController(doc: Y.Doc): PreDrainController | undefined {
  return preDrainControllers.get(doc);
}

const convergedFragmentWitnesses = new WeakMap<Y.Doc, () => string>();

export function getConvergedFragmentWitness(doc: Y.Doc): string | undefined {
  return convergedFragmentWitnesses.get(doc)?.();
}

const externalEditorRecencies = new WeakMap<Y.Doc, () => number | undefined>();

export function getLastExternalEditorChangeMs(doc: Y.Doc): number | undefined {
  return externalEditorRecencies.get(doc)?.();
}

type ShadowAccessor = () => ShadowHandle | undefined;

type BranchAccessor = () => string;

export type ObserverDispatchKind = 'none' | 'a' | 'b';

type ObserverDispatchHook = (kind: ObserverDispatchKind) => void;

export interface SetupServerObserversOpts {
  doc: Y.Doc;
  xmlFragment: Y.XmlFragment;
  ytext: Y.Text;
  mdManager: MarkdownManager;
  schema: Schema;
  docName?: string;
  shadow?: ShadowAccessor;
  getBranch?: BranchAccessor;
  contentRoot?: string;
  resolveEmbed?: (basename: string, sourcePath: string) => string | null;
  resolveSize?: (basename: string, sourcePath: string) => number | null;
  onDispatch?: ObserverDispatchHook;
  mergeThreeWay?: typeof mergeThreeWay;
  deferGuardEnabled?: boolean;
  lossDetectorEnabled?: boolean;
  fixedPointBackstopEnabled?: boolean;
  preDrainEnabled?: boolean;
  lossRing?: Pick<LossCaptureRing, 'record'>;
  onDeriveTimingDefer?: (snapshot: { canonicalWitness: string; rawWitness: string }) => void;
  onReDeriveBackstop?: (rounds: number) => void;
  __testApplyLossInjector?: (ytext: Y.Text) => void;
}

/**
 * Split-brain settlement predicate (the precedent #38 comparison): true when a drain is about to
 * settle with Y.Text and the canonical fragment serialization (`md`) diverged beyond
 * `normalizeBridge` tolerance.
 */
function settlesSplitBrain(
  settledText: string,
  md: string,
  normMdPre?: string,
  normSettledPre?: string,
): boolean {
  return (
    settledText !== md &&
    (normSettledPre ?? normalizeBridge(settledText)) !== (normMdPre ?? normalizeBridge(md))
  );
}

function carrierKind(child: Y.XmlElement | Y.XmlText | Y.XmlHook): string {
  if (child instanceof Y.XmlElement) return child.nodeName;
  if (child instanceof Y.XmlText) return '#text';
  return '#hook';
}

function mintingClientId(child: Y.XmlElement | Y.XmlText | Y.XmlHook): number | undefined {
  return (child as { _item?: { id?: { client: number } } | null })._item?.id?.client;
}

const collapseSpaces = (s: string): string => s.replace(/\s+/g, ' ').trim();

const stripInlineMarkerChars = (s: string): string => s.replace(/[*_~`]+/g, '');

function xmlBareText(s: string): string {
  return collapseSpaces(
    stripInlineMarkerChars(
      s
        .replace(/<[^>]*>/g, '')
        .replace(/&lt;/g, '<')
        .replace(/&gt;/g, '>')
        .replace(/&quot;/g, '"')
        .replace(/&amp;/g, '&'),
    ),
  );
}

function markdownBareText(line: string): string {
  return collapseSpaces(
    stripInlineMarkerChars(
      line.replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/\\([\\`*_{}[\]()#+\-.!><])/g, '$1'),
    ),
  );
}

export function findRaceDuplicatedSpans(
  xmlFragment: Y.XmlFragment,
  serverClientId: number,
  overMultipliedLines: readonly string[],
): boolean {
  if (overMultipliedLines.length === 0) return false;
  const children = xmlFragment.toArray();
  const childBareTexts = children.map((child) => xmlBareText(child.toString()));
  for (const line of overMultipliedLines) {
    const bareLine = markdownBareText(line);
    if (bareLine.length < DUPLICATION_GATE_MIN_LINE_LENGTH) continue;
    const serverKinds = new Set<string>();
    const foreignKinds = new Set<string>();
    for (let i = 0; i < children.length; i++) {
      const child = children[i];
      if (child === undefined || !childBareTexts[i]?.includes(bareLine)) continue;
      const client = mintingClientId(child);
      if (client === undefined) continue;
      if (client === serverClientId) serverKinds.add(carrierKind(child));
      else foreignKinds.add(carrierKind(child));
    }
    for (const s of serverKinds) {
      for (const f of foreignKinds) {
        if (s !== f) return true;
      }
    }
  }
  return false;
}

/** Dispatch (precedent #13(b)): Observer callbacks only flag dirty state. */
export function setupServerObservers(opts: SetupServerObserversOpts): () => void {
  const { doc, xmlFragment, ytext, mdManager, schema } = opts;

  const handleBridgeMergeLoss = (
    err: BridgeMergeContentLossError,
    preMergeBaseline: string,
  ): void => {
    const verbose = process.env.OK_TELEMETRY_VERBOSE === '1';
    console.warn(
      JSON.stringify({
        ...err.toLog({ verbose }),
        docName: opts.docName ?? null,
        timestamp: new Date().toISOString(),
      }),
    );
    if (err.info.which === 'growth') incrementBridgeMergeContentGrowth();
    else incrementBridgeMergeContentLoss();

    const which = err.info.which;
    const lostLen = err.info.lostSubstrings.reduce((n, s) => n + s.length, 0);

    const shadow = opts.shadow?.();
    if (!shadow || !opts.docName) {
      void opts.lossRing?.record({
        event: LOSS_EVENT_DETECTOR_TRIP,
        docName: opts.docName ?? '',
        writerId: null,
        direction: 'a',
        site: MERGE_BOUNDARY_SITE,
        lostLen,
        which,
      });
      return;
    }
    const branch = opts.getBranch?.() ?? 'main';
    const contentRoot = opts.contentRoot ?? '';
    queueMicrotask(() => {
      saveInMemoryCheckpoint(shadow, contentRoot, {
        kind: 'bridge-merge-loss',
        docName: opts.docName as string,
        contents: preMergeBaseline,
        label: `Before concurrent merge @ ${new Date().toISOString()}`,
        branch,
        metadata: { lostSubstrings: err.info.lostSubstrings, which: err.info.which },
      })
        .then((sha) => {
          incrementBridgeMergeCheckpointCreated();
          void opts.lossRing?.record({
            event: LOSS_EVENT_DETECTOR_TRIP,
            docName: opts.docName as string,
            writerId: null,
            direction: 'a',
            site: MERGE_BOUNDARY_SITE,
            lostLen,
            which,
            checkpointSha: sha,
          });
          console.warn(
            JSON.stringify({
              event: 'bridge-merge-checkpoint-created',
              docName: opts.docName,
              sha,
              kind: 'bridge-merge-loss',
              timestamp: new Date().toISOString(),
            }),
          );
        })
        .catch((checkpointErr: unknown) => {
          const err =
            checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
          log.warn({ err }, '[Server Observer A] Silent checkpoint write failed');
          checkpointLog.warn(
            { err, 'doc.name': opts.docName ?? null, branch, kind: 'bridge-merge-loss' },
            'checkpoint write failed',
          );
          void opts.lossRing?.record({
            event: LOSS_EVENT_DETECTOR_TRIP,
            docName: opts.docName as string,
            writerId: null,
            direction: 'a',
            site: MERGE_BOUNDARY_SITE,
            lostLen,
            which,
          });
        });
    });
  };

  const recordSplitBrainRederive = (site: BridgeSplitBrainSite): void => {
    drainDidCorrectiveWork = true;
    pendingSplitBrainRederive = true;
    try {
      if (emitBridgeSplitBrainRederive(site, opts.docName)) {
        incrementBridgeSplitBrainRederives();
        console.warn(
          JSON.stringify({
            event: 'bridge-split-brain-rederive',
            'doc.name': opts.docName ?? null,
            site,
          }),
        );
      }
    } catch (telErr) {
      log.warn({ err: telErr }, '[Server Observer A] Split-brain telemetry failed');
    }
  };

  const recordGuardDefer = (pendingLines: readonly string[]): void => {
    void opts.lossRing?.record({
      event: LOSS_EVENT_GUARD_DEFER,
      docName: opts.docName ?? '',
      writerId: null,
      direction: 'b',
      lostLen: pendingLines.reduce((n, line) => n + line.length, 0),
    });
  };

  const saveDuplicationCheckpoint = (contents: string, duplicatedLineCount: number): void => {
    const shadow = opts.shadow?.();
    if (!shadow || !opts.docName) return;
    const branch = opts.getBranch?.() ?? 'main';
    const contentRoot = opts.contentRoot ?? '';
    const docName = opts.docName;
    queueMicrotask(() => {
      saveInMemoryCheckpoint(shadow, contentRoot, {
        kind: 'observer-a-duplication',
        docName,
        contents,
        label: `Before duplication re-derive @ ${new Date().toISOString()}`,
        branch,
        metadata: { duplicatedLineCount },
      })
        .then((sha) => {
          incrementObserverADuplicationCheckpointCreated();
          console.warn(
            JSON.stringify({
              event: 'observer-a-duplication-checkpoint-created',
              docName,
              sha,
              kind: 'observer-a-duplication',
              timestamp: new Date().toISOString(),
            }),
          );
        })
        .catch((checkpointErr: unknown) => {
          const e =
            checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
          log.warn({ docName, err: e }, '[Server Observer A] Duplication checkpoint write failed');
          checkpointLog.warn(
            { err: e, 'doc.name': docName, branch, kind: 'observer-a-duplication' },
            'checkpoint write failed',
          );
        });
    });
  };

  const detectObserverAApplyLoss = (
    intendedMd: string,
    normIntended: string,
    appliedYText: string,
    normApplied: string,
  ): void => {
    if (opts.lossDetectorEnabled === false) return;
    const dropped = detectApplyArmDrop(intendedMd, normIntended, appliedYText, normApplied);
    if (dropped.length === 0) return;
    incrementObserverAApplyLoss();
    const lostLen = dropped.reduce((n, s) => n + s.length, 0);
    const digest = fnv1aDigest(dropped.join('\n'));
    const shadow = opts.shadow?.();
    if (!shadow || !opts.docName) {
      void opts.lossRing?.record({
        event: LOSS_EVENT_DETECTOR_TRIP,
        docName: opts.docName ?? '',
        writerId: null,
        direction: 'a',
        site: 'observer-a-apply',
        lostLen,
        digest,
      });
      return;
    }
    const branch = opts.getBranch?.() ?? 'main';
    const contentRoot = opts.contentRoot ?? '';
    const docName = opts.docName;
    queueMicrotask(() => {
      saveInMemoryCheckpoint(shadow, contentRoot, {
        kind: 'observer-a-apply-loss',
        docName,
        contents: intendedMd,
        label: `Before Observer-A apply content-loss @ ${new Date().toISOString()}`,
        branch,
        metadata: { lostSubstrings: dropped },
      })
        .then((sha) => {
          incrementObserverAApplyLossCheckpointCreated();
          void opts.lossRing?.record({
            event: LOSS_EVENT_DETECTOR_TRIP,
            docName,
            writerId: null,
            direction: 'a',
            site: 'observer-a-apply',
            lostLen,
            digest,
            checkpointSha: sha,
          });
          console.warn(
            JSON.stringify({
              event: 'observer-a-apply-loss-checkpoint-created',
              docName,
              sha,
              kind: 'observer-a-apply-loss',
              timestamp: new Date().toISOString(),
            }),
          );
        })
        .catch((checkpointErr: unknown) => {
          const e =
            checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
          log.warn({ docName, err: e }, '[Server Observer A] Apply-loss checkpoint write failed');
          checkpointLog.warn(
            { err: e, 'doc.name': docName, branch, kind: 'observer-a-apply-loss' },
            'checkpoint write failed',
          );
          void opts.lossRing?.record({
            event: LOSS_EVENT_DETECTOR_TRIP,
            docName,
            writerId: null,
            direction: 'a',
            site: 'observer-a-apply',
            lostLen,
            digest,
          });
        });
    });
  };

  const forceResolveExhaustedDefer = (
    preResolveFragmentMd: string,
    deferCount: number,
    pendingLines: readonly string[],
  ): void => {
    incrementDeriveTimingDeferForceResolved();
    const lostLen = pendingLines.reduce((n, line) => n + line.length, 0);
    const shadow = opts.shadow?.();
    const docName = opts.docName;
    if (!shadow || !docName) {
      void opts.lossRing?.record({
        event: LOSS_EVENT_CHECKPOINT_WRITE,
        docName: docName ?? '',
        writerId: null,
        direction: 'b',
        site: 'derive-timing-exhaustion',
        lostLen,
      });
      return;
    }
    const branch = opts.getBranch?.() ?? 'main';
    const contentRoot = opts.contentRoot ?? '';
    queueMicrotask(() => {
      saveInMemoryCheckpoint(shadow, contentRoot, {
        kind: 'defer-exhaustion-loss',
        docName,
        contents: preResolveFragmentMd,
        label: `Before derive-defer force-resolve @ ${new Date().toISOString()}`,
        branch,
        metadata: { deferCount },
      })
        .then((sha) => {
          void opts.lossRing?.record({
            event: LOSS_EVENT_CHECKPOINT_WRITE,
            docName,
            writerId: null,
            direction: 'b',
            site: 'derive-timing-exhaustion',
            lostLen,
            checkpointSha: sha,
          });
          console.warn(
            JSON.stringify({
              event: 'derive-defer-exhaustion-checkpoint-created',
              docName,
              sha,
              kind: 'defer-exhaustion-loss',
              timestamp: new Date().toISOString(),
            }),
          );
        })
        .catch((checkpointErr: unknown) => {
          const e =
            checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
          log.warn(
            { docName, err: e },
            '[Server Observer B] Derive-defer exhaustion checkpoint write failed',
          );
          checkpointLog.warn(
            { err: e, 'doc.name': docName, branch, kind: 'defer-exhaustion-loss' },
            'checkpoint write failed',
          );
          void opts.lossRing?.record({
            event: LOSS_EVENT_CHECKPOINT_WRITE,
            docName,
            writerId: null,
            direction: 'b',
            site: 'derive-timing-exhaustion',
            lostLen,
          });
        });
    });
  };

  const tripReDeriveBackstop = (rounds: number): void => {
    bDirectionFrozen = true;
    incrementReDeriveBackstopTripped();
    opts.onReDeriveBackstop?.(rounds);
    const frozenYText = ytext.toString();
    const shadow = opts.shadow?.();
    const docName = opts.docName;
    if (!shadow || !docName) {
      void opts.lossRing?.record({
        event: LOSS_EVENT_BACKSTOP_TRIP,
        docName: docName ?? '',
        writerId: null,
        direction: 'b',
        site: 'rederive-backstop',
      });
      return;
    }
    const branch = opts.getBranch?.() ?? 'main';
    const contentRoot = opts.contentRoot ?? '';
    queueMicrotask(() => {
      saveInMemoryCheckpoint(shadow, contentRoot, {
        kind: 'bridge-backstop-trip',
        docName,
        contents: frozenYText,
        label: `Before re-derive backstop freeze @ ${new Date().toISOString()}`,
        branch,
        metadata: { rounds },
      })
        .then((sha) => {
          void opts.lossRing?.record({
            event: LOSS_EVENT_BACKSTOP_TRIP,
            docName,
            writerId: null,
            direction: 'b',
            site: 'rederive-backstop',
            checkpointSha: sha,
          });
          console.warn(
            JSON.stringify({
              event: 'bridge-rederive-backstop-checkpoint-created',
              docName,
              sha,
              kind: 'bridge-backstop-trip',
              timestamp: new Date().toISOString(),
            }),
          );
        })
        .catch((checkpointErr: unknown) => {
          const e =
            checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
          log.warn(
            { docName, err: e },
            '[Server Observer B] Re-derive backstop checkpoint write failed',
          );
          checkpointLog.warn(
            { err: e, 'doc.name': docName, branch, kind: 'bridge-backstop-trip' },
            'checkpoint write failed',
          );
          void opts.lossRing?.record({
            event: LOSS_EVENT_BACKSTOP_TRIP,
            docName,
            writerId: null,
            direction: 'b',
            site: 'rederive-backstop',
          });
        });
    });
  };

  let lastSyncedCanonicalMd = '';
  let lastSyncedYTextBytes = '';
  const mdastMemo = createEditorMdastMemo();
  let canonicalWitnessCoherent = false;
  let xmlDirty = false;
  let textDirty = false;
  let lastExternalYtextChangeMs = 0;
  let lastExternalEditorChangeMs = 0;

  const deferGuardEnabled = opts.deferGuardEnabled !== false;
  let lastConvergedFragmentMd = '';
  let fragmentMutatedSinceConverge = false;
  let consecutiveDeriveTimingDefers = 0;
  let pendingDuplicationRecovery = false;
  let pendingSplitBrainRederive = false;

  const fixedPointBackstopEnabled = opts.fixedPointBackstopEnabled !== false;
  const preDrainEnabled = opts.preDrainEnabled !== false;
  const REDERIVE_DIGEST_RING = MAX_REDERIVE_ROUNDS;
  const recentSettledDigests: string[] = [];
  let oscillationRun = 0;
  let bDirectionFrozen = false;
  let drainDidCorrectiveWork = false;
  let drainReachedRawFixedPoint = false;
  let drainDeferred = false;

  /**
   * STOP: the Path A/B router strict-compares this witness against
   * `ytext.toString()`, and `mergeThreeWay`'s diverged-branch base must be a
   * true Y.Text ancestor. It must only ever hold a real Y.Text byte
   * snapshot — never assign a serialized/recomposed string here.
   */
  const refreshYTextWitness = (): void => {
    lastSyncedYTextBytes = ytext.toString();
    canonicalWitnessCoherent = false;
  };

  const recordSettledBaselines = (canonicalMd: string): void => {
    lastSyncedCanonicalMd = canonicalMd;
    refreshYTextWitness();
    canonicalWitnessCoherent = canonicalMd !== '';
    if (fixedPointBackstopEnabled && canonicalMd !== '' && lastSyncedYTextBytes === canonicalMd) {
      drainReachedRawFixedPoint = true;
    }
  };

  const recordDivergedAttachBaselines = (canonicalMd: string): void => {
    lastSyncedCanonicalMd = canonicalMd;
    lastSyncedYTextBytes = canonicalMd;
    canonicalWitnessCoherent = false;
  };

  const refreshCanonicalWitnessOnly = (canonicalMd: string): void => {
    lastSyncedCanonicalMd = canonicalMd;
    canonicalWitnessCoherent = false;
  };

  /**
   * The same-drain Observer B re-derive the caller enqueues then rebuilds the fragment from Y.Text
   * (Y.Text-is-truth, precedent #38), so the split-brain state converges.
   */
  const recordSplitBrainRecoveryBaselines = (canonicalMd: string): void => {
    lastSyncedCanonicalMd = canonicalMd;
    lastSyncedYTextBytes = ytext.toString();
    canonicalWitnessCoherent = true;
  };

  const readCurrentFm = (): string => stripFrontmatter(ytext.toString()).frontmatter;

  const composeDerivedBodyMd = (frontmatter: string, derivedBody: string): BridgeComposition => {
    const { slot } = splitFmBoundarySlot(frontmatter, stripFrontmatter(ytext.toString()).body);
    return composeWithDerivedBody(frontmatter, slot + derivedBody);
  };

  const spellDerivedBody = (composition: BridgeComposition, currentText: string): string =>
    composition.frontmatter +
    spellLineEndings(composition.body, documentBodyLineEnding(currentText));

  const observerParseOpts =
    opts.resolveEmbed && opts.docName
      ? {
          resolveEmbed: opts.resolveEmbed,
          resolveSize: opts.resolveSize,
          sourcePath: opts.docName,
        }
      : undefined;

  const canonicalizeBody = createDocCanonicalizer(mdManager, {
    resolveEmbed: opts.resolveEmbed,
    resolveSize: opts.resolveSize,
    docName: opts.docName,
  });

  let memoParseEquivalentLeft = '';
  let memoParseEquivalentRight = '';
  let hasParseEquivalentMemo = false;
  const isRestingParseEquivalent = (left: string, right: string): boolean => {
    if (
      hasParseEquivalentMemo &&
      left === memoParseEquivalentLeft &&
      right === memoParseEquivalentRight
    ) {
      return true;
    }
    const equivalent = isParseEquivalentBridge(left, right, canonicalizeBody);
    if (equivalent) {
      memoParseEquivalentLeft = left;
      memoParseEquivalentRight = right;
      hasParseEquivalentMemo = true;
    }
    return equivalent;
  };

  const settlesSplitBrainChecked = (
    settledText: string,
    md: string,
    normMdPre?: string,
    normSettledPre?: string,
  ): boolean =>
    settlesSplitBrain(settledText, md, normMdPre, normSettledPre) &&
    !isRestingParseEquivalent(settledText, md);

  try {
    const initialJson = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
    const initialBody = mdManager.serialize(initialJson);
    const initialFrontmatter = readCurrentFm();
    const canonicalInit = composeDerivedBodyMd(initialFrontmatter, initialBody).md;
    if (isRestingParseEquivalent(ytext.toString(), canonicalInit)) {
      recordSettledBaselines(canonicalInit);
    } else {
      recordDivergedAttachBaselines(canonicalInit);
    }
    lastConvergedFragmentMd = canonicalInit;
  } catch (err) {
    incrementServerObserverError('a');
    log.warn(
      { err: err instanceof Error ? err : new Error(String(err)) },
      '[Server Observer A] Baseline init failed — starting from empty snapshot',
    );
    recordSettledBaselines('');
  }

  let lastGuardedBody: string | undefined;
  const PRODUCER_GUARD_LOG_COOLDOWN_MS = 5_000;
  const FRESHNESS_QUIESCENCE_MS = 2_000;
  const guardLogState = new Map<string, { lastMs: number; suppressed: number }>();
  const guardCheckpointedPreLoss = new Map<string, string>();

  /**
   * Never throws, never corrective-writes (precedent #38): the drain still persists the bytes
   * as-computed.
   */
  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;
    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) => {
          if (guardCheckpointedPreLoss.get(key) === preLossSource) {
            guardCheckpointedPreLoss.delete(key);
          }
          const e =
            checkpointErr instanceof Error ? checkpointErr : new Error(String(checkpointErr));
          log.warn({ err: e }, '[Server Observer A] Producer-guard checkpoint write failed');
          checkpointLog.warn(
            { err: e, 'doc.name': docName, branch, kind: 'producer-guard-loss' },
            'checkpoint write failed',
          );
        });
    });
  };

  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, { rawSourceSide: 'expected' });
    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));
  };

  const runObserverASyncImpl = (): void => {
    try {
      const json = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
      const rawWitnessCoherent = ytext.toString() === lastSyncedYTextBytes;
      const ytextQuiescent = Date.now() - lastExternalYtextChangeMs >= FRESHNESS_QUIESCENCE_MS;
      const freshnessSafe = rawWitnessCoherent && ytextQuiescent;
      const serializedNewPm = serializeEditorBody(mdManager, json as JSONContent, {
        skipFreshnessDerive: !freshnessSafe,
      });
      const body = serializedNewPm.body;
      if (freshnessSafe) runProducerGuard(json as PmStructuralNode, body);
      const frontmatter = readCurrentFm();
      const composition = composeDerivedBodyMd(frontmatter, body);
      const md = composition.md;
      const currentText = ytext.toString();

      const overMultiplied = overMultipliedBodyLines(
        md,
        currentText,
        DUPLICATION_GATE_MIN_LINE_LENGTH,
      );
      if (
        overMultiplied.length > 0 &&
        findRaceDuplicatedSpans(xmlFragment, doc.clientID, overMultiplied)
      ) {
        recordDivergedAttachBaselines(md);
        textDirty = true;
        pendingDuplicationRecovery = true;
        recordSplitBrainRederive('duplication-guard');
        incrementObserverADuplicationRederives();
        saveDuplicationCheckpoint(md, overMultiplied.length);
        setActiveSpanAttributes({ 'observer.a.path': 'gated-duplication-rederive' });
        return;
      }

      if (freshnessSafe) {
        lastConvergedFragmentMd = md;
        fragmentMutatedSinceConverge = false;
        consecutiveDeriveTimingDefers = 0;
      }

      if (canonicalWitnessCoherent && lastSyncedCanonicalMd === md) {
        if (settlesSplitBrainChecked(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;
      }

      const normCurrent = normalizeBridge(currentText);
      const normMd = normalizeBridge(md);
      if (
        normCurrent === normMd &&
        !addsBlankLines(currentText, md) &&
        !docEdgeRunsDiffer(currentText, md)
      ) {
        setActiveSpanAttributes({
          'observer.a.path': 'gated-in-sync',
          'observer.a.gate_reason': currentText === md ? 'bytes-identical' : 'tolerance-equivalent',
        });
        recordSettledBaselines(md);
        return;
      }

      const preMergeBaseline = lastSyncedYTextBytes;
      const ytextInSync = currentText === lastSyncedYTextBytes;
      const residualMergeEligible =
        ytextInSync &&
        canonicalWitnessCoherent &&
        lastSyncedYTextBytes !== lastSyncedCanonicalMd &&
        normCurrent !== normalizeBridge(lastSyncedCanonicalMd);
      setActiveSpanAttributes({
        'observer.a.path': ytextInSync
          ? residualMergeEligible
            ? 'residual-merge'
            : 'path-a'
          : 'path-b',
      });
      const pathBState: { mergedText: string | null } = { mergedText: null };

      const computeSplice = (
        onResidualFallback?: (reason: ResidualMergeSpliceUnavailableReason) => void,
      ): YTextMapDrivenSplice | null => {
        if (composition.adjusted !== 'none') {
          onResidualFallback?.('composition-adjusted');
          return null;
        }
        if (docEdgeRunsDiffer(currentText, md)) {
          onResidualFallback?.('doc-edge-runs');
          return null;
        }
        return tryComputeMapDrivenSplice({
          currentText,
          lastSyncedXmlMd: lastSyncedYTextBytes,
          mdManager,
          docName: opts.docName,
          mdastMemo,
          serializedNewPm,
          onResidualFallback,
        });
      };
      const landResidualMerge = (merged: string): string => {
        if (!residualMergeEligible || !settlesSplitBrainChecked(merged, md, normMd)) return merged;
        let unavailable: ResidualMergeSpliceUnavailableReason = 'not-settled';
        const splice = computeSplice((reason) => {
          unavailable = reason;
        });
        if (splice !== null) {
          const spliced =
            currentText.slice(0, splice.spliceStart) +
            splice.newSlice +
            currentText.slice(splice.spliceEnd);
          if (!settlesSplitBrainChecked(spliced, md, normMd)) {
            const droppedSourceContent = findDroppedSourceContentInRange(
              lastSyncedCanonicalMd,
              currentText,
              { start: splice.spliceStart, end: splice.spliceEnd },
              splice.newSlice,
            );
            if (droppedSourceContent.length > 0) {
              incrementObserverAResidualMergeSpliceBlockedLossy();
              setActiveSpanAttributes({
                'observer.a.residual_merge_fallback': 'splice-blocked-lossy',
              });
              return merged;
            }
            incrementObserverAResidualMergeSpliceLanded();
            setActiveSpanAttributes({ 'observer.a.residual_merge_fallback': 'map-driven-splice' });
            return spliced;
          }
        }
        incrementObserverAResidualMergeSpliceUnavailable(unavailable);
        setActiveSpanAttributes({
          'observer.a.residual_merge_fallback': 'splice-unavailable',
          'observer.a.residual_merge_fallback_reason': unavailable,
        });
        return merged;
      };

      const spliceComputeStart = performance.now();
      const mapDrivenSplice = residualMergeEligible ? null : computeSplice();
      if (mapDrivenSplice) {
        setActiveSpanAttributes({
          'observer.a.path': 'map-driven-splice',
          'observer.a.splice.compute_ms': Math.round(performance.now() - spliceComputeStart),
        });
      }

      doc.transact(() => {
        if (mapDrivenSplice) {
          applyMapDrivenSplice(ytext, mapDrivenSplice);
        } else if (ytextInSync && !residualMergeEligible) {
          applyIncrementalDiff(ytext, currentText, spellDerivedBody(composition, currentText));
        } else {
          const mergeBase = ytextInSync ? lastSyncedCanonicalMd : preMergeBaseline;
          const boundarySpace = createMergeBoundarySpace(body);
          const projectMerged = (merged: string): string =>
            boundarySpace.unproject(merged, currentText);
          const mergeThreeWayFn = opts.mergeThreeWay ?? mergeThreeWay;
          try {
            const mergedText = landResidualMerge(
              projectMerged(
                mergeThreeWayFn(
                  boundarySpace.project(mergeBase),
                  boundarySpace.project(md),
                  boundarySpace.project(currentText),
                ),
              ),
            );
            applyFastDiff(ytext, currentText, mergedText);
            pathBState.mergedText = mergedText;
          } catch (mergeErr) {
            if (!(mergeErr instanceof BridgeMergeContentLossError)) throw mergeErr;
            handleBridgeMergeLoss(mergeErr, preMergeBaseline);
            if (shouldRethrowBridgeMergeLoss()) throw mergeErr;
            const asComputed = projectMerged(mergeErr.info.result);
            applyFastDiff(ytext, currentText, asComputed);
            pathBState.mergedText = asComputed;
          }
        }
        opts.__testApplyLossInjector?.(ytext);
      }, OBSERVER_SYNC_ORIGIN);

      if (mapDrivenSplice) incrementMapDrivenSpliceApplied();

      const appliedYText = ytext.toString();
      const normApplied = normalizeBridge(appliedYText);
      if (mapDrivenSplice || (ytextInSync && !residualMergeEligible)) {
        detectObserverAApplyLoss(md, normMd, appliedYText, normApplied);
      }

      if (pathBState.mergedText !== null && !ytextInSync) {
        if (emitObserverAPathBFired(opts.docName)) {
          incrementObserverAPathBFires();
          console.warn(
            JSON.stringify({
              event: 'observer-a-path-b-fired',
              'doc.name': opts.docName ?? null,
              xmlFragmentAdvanced: true,
              ytextDiverged: !ytextInSync,
              mergeBytesChanged: Math.abs(pathBState.mergedText.length - currentText.length),
            }),
          );
        }
      }

      if (pathBState.mergedText !== null && ytextInSync) {
        incrementObserverAResidualMergeRuns();
      }

      incrementServerObserverFire('a');
      recordSettledBaselines(md);

      if (settlesSplitBrainChecked(appliedYText, md, normMd, normApplied)) {
        if (appliedYText === preMergeBaseline) recordDivergedAttachBaselines(md);
        textDirty = true;
        recordSplitBrainRederive('post-merge');
      }
    } catch (err) {
      if (err instanceof BridgeMergeContentLossError) {
        throw err;
      }
      if (err instanceof ProducerGuardViolationError) {
        throw err;
      }
      incrementServerObserverError('a');
      log.error({ err }, '[Server Observer A] Failed to sync tree→text');
      try {
        const recoveryJson = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
        const recoveryBody = mdManager.serialize(recoveryJson);
        const recoveryMd = composeDerivedBodyMd(readCurrentFm(), recoveryBody).md;
        if (settlesSplitBrainChecked(ytext.toString(), recoveryMd)) {
          recordSplitBrainRecoveryBaselines(recoveryMd);
          textDirty = true;
          recordSplitBrainRederive('error-recovery');
        } else {
          recordSettledBaselines(recoveryMd);
        }
      } catch (innerErr) {
        log.warn(
          {
            docName: opts.docName ?? null,
            originalError: err instanceof Error ? err.message : String(err),
            recoveryError: innerErr instanceof Error ? innerErr.message : String(innerErr),
          },
          '[Server Observer A] Baseline recovery also failed',
        );
        lastSyncedCanonicalMd = '';
        lastSyncedYTextBytes = '';
        canonicalWitnessCoherent = false;
      }
    }
  };

  const runObserverASync = (): void => {
    withSpanSync(
      'observer.runASync',
      { attributes: { 'doc.name': opts.docName ?? '' } },
      runObserverASyncImpl,
    );
  };

  const observerA = (_events: Y.YEvent<Y.XmlFragment>[], transaction: Y.Transaction) => {
    if (transaction.origin === OBSERVER_SYNC_ORIGIN) return;

    if (isPairedWriteOrigin(transaction.origin)) {
      try {
        const frontmatter = readCurrentFm();
        refreshYTextWitness();
        lastConvergedFragmentMd = lastSyncedYTextBytes;
        fragmentMutatedSinceConverge = false;
        consecutiveDeriveTimingDefers = 0;
        priorFmForTelemetry = frontmatter;
      } catch (err) {
        incrementServerObserverError('a');
        log.warn(
          { err: err instanceof Error ? err : new Error(String(err)) },
          '[Server Observer A] Paired-write baseline refresh failed — falling through to settlement',
        );
        xmlDirty = true;
      }
      return;
    }

    if (isConnectionOrigin(transaction.origin)) lastExternalEditorChangeMs = Date.now();

    xmlDirty = true;
    fragmentMutatedSinceConverge = true;
  };

  if (xmlFragment.length > 0 && ytext.length === 0) {
    try {
      const json = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
      const body = mdManager.serialize(json);
      const frontmatter = readCurrentFm();
      const md = composeDerivedBodyMd(frontmatter, body).md;
      doc.transact(() => {
        ytext.insert(0, md);
      }, OBSERVER_SYNC_ORIGIN);
      recordSettledBaselines(md);
    } catch (err) {
      incrementServerObserverError('a');
      log.error({ err }, '[Server Observer A] Failed initial sync');
      recordSettledBaselines('');
    }
  }

  let priorFmForTelemetry = readCurrentFm();
  const runObserverBSyncImpl = (): void => {
    try {
      const md = ytext.toString();

      const { frontmatter, body } = stripFrontmatter(md);
      const { slot: fmBoundarySlot, body: parseBody } = splitFmBoundarySlot(frontmatter, body);

      if (
        !pendingSplitBrainRederive &&
        normalizeBridge(lastSyncedYTextBytes) === normalizeBridge(md) &&
        !docEdgeRunsDiffer(lastSyncedYTextBytes, md)
      ) {
        if (priorFmForTelemetry !== frontmatter) {
          recordFrontmatterEditSurface('source-mode');
          priorFmForTelemetry = frontmatter;
        }
        if (fixedPointBackstopEnabled && canonicalWitnessCoherent && lastSyncedCanonicalMd === md) {
          drainReachedRawFixedPoint = true;
        }
        return;
      }

      if (bDirectionFrozen) {
        setActiveSpanAttributes({ 'observer.b.path': 'backstop-frozen' });
        return;
      }

      if (pendingDuplicationRecovery) {
        pendingDuplicationRecovery = false;
      } else if (deferGuardEnabled && fragmentMutatedSinceConverge) {
        const freshFragmentBody = mdManager.serialize(
          yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON(),
        );
        const freshFragmentMd = composeDerivedBodyMd(frontmatter, freshFragmentBody).md;
        if (fragmentHoldsPendingContent(freshFragmentMd, md, lastConvergedFragmentMd)) {
          if (consecutiveDeriveTimingDefers >= MAX_DERIVE_TIMING_DEFERS) {
            forceResolveExhaustedDefer(
              freshFragmentMd,
              consecutiveDeriveTimingDefers,
              pendingContentLines(freshFragmentMd, md, lastConvergedFragmentMd),
            );
            consecutiveDeriveTimingDefers = 0;
            setActiveSpanAttributes({ 'observer.b.path': 'derive-timing-force-resolve' });
          } else {
            consecutiveDeriveTimingDefers += 1;
            xmlDirty = true;
            textDirty = true;
            recordGuardDefer(pendingContentLines(freshFragmentMd, md, lastConvergedFragmentMd));
            opts.onDeriveTimingDefer?.({
              canonicalWitness: lastSyncedCanonicalMd,
              rawWitness: lastSyncedYTextBytes,
            });
            drainDeferred = true;
            setActiveSpanAttributes({ 'observer.b.path': 'derive-timing-defer' });
            return;
          }
        }
      }

      const parsedJson = mdManager.parseWithFallback(parseBody, observerParseOpts);

      const pmNode = opts.schema.nodeFromJSON(parsedJson);

      doc.transact(() => {
        const meta = { mapping: new Map(), isOMark: new Map() };
        updateYFragment(doc, xmlFragment, pmNode, meta);
      }, OBSERVER_SYNC_ORIGIN);
      pendingSplitBrainRederive = false;

      if (fixedPointBackstopEnabled) drainDidCorrectiveWork = true;

      if (priorFmForTelemetry !== frontmatter) {
        recordFrontmatterEditSurface('source-mode');
        priorFmForTelemetry = frontmatter;
      }

      incrementServerObserverFire('b');

      try {
        const canonicalBody = mdManager.serialize(parsedJson);
        const canonicalYText = prependFrontmatter(frontmatter, fmBoundarySlot + canonicalBody);
        assertBridgeInvariant(ytext.toString(), canonicalYText, {
          site: 'observer-b',
          docName: opts.docName,
          canonicalizeBody: (b) =>
            b === body ? fmBoundarySlot + canonicalBody : canonicalizeBody(b),
        });
        recordSettledBaselines(canonicalYText);
        lastConvergedFragmentMd = canonicalYText;
        fragmentMutatedSinceConverge = false;
        consecutiveDeriveTimingDefers = 0;
      } catch (reserializeErr) {
        if (reserializeErr instanceof BridgeInvariantViolationError) {
          throw reserializeErr;
        }
        log.warn(
          { err: reserializeErr },
          '[Server Observer B] Post-sync re-serialization failed — using input body as baseline',
        );
        recordSettledBaselines(prependFrontmatter(frontmatter, body));
      }
    } catch (err) {
      if (err instanceof BridgeInvariantViolationError) {
        throw err;
      }
      incrementServerObserverError('b');
      log.error({ err }, '[Server Observer B] Failed to sync text→tree');
      try {
        const postJson = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
        const postBody = mdManager.serialize(postJson);
        const fm = readCurrentFm();
        refreshCanonicalWitnessOnly(composeDerivedBodyMd(fm, postBody).md);
      } catch (innerErr) {
        if (innerErr instanceof BridgeInvariantViolationError) {
          throw innerErr;
        }
        log.warn({ err: innerErr }, '[Server Observer B] Baseline recovery also failed');
      }
    }
  };

  const runObserverBSync = (): void => {
    withSpanSync(
      'observer.runBSync',
      { attributes: { 'doc.name': opts.docName ?? '' } },
      runObserverBSyncImpl,
    );
  };

  const observerB = (_event: Y.YTextEvent, transaction: Y.Transaction) => {
    if (transaction.origin === OBSERVER_SYNC_ORIGIN) return;

    if (isPairedWriteOrigin(transaction.origin)) {
      try {
        const frontmatter = readCurrentFm();
        refreshYTextWitness();
        priorFmForTelemetry = frontmatter;
      } catch (err) {
        incrementServerObserverError('b');
        log.warn(
          { err: err instanceof Error ? err : new Error(String(err)) },
          '[Server Observer B] Paired-write baseline refresh failed — falling through to settlement',
        );
        textDirty = true;
      }
      return;
    }

    if (isConnectionOrigin(transaction.origin)) lastExternalEditorChangeMs = Date.now();

    lastExternalYtextChangeMs = Date.now();
    textDirty = true;
  };

  // ─── Settlement dispatcher (precedent #13(b)) ────────
  const afterAll = (_doc: Y.Doc, transactions: Y.Transaction[]): void => {
    withSpanSync(
      'observer.dispatch',
      { attributes: { 'doc.name': opts.docName ?? '' } },
      (span) => {
        if (!xmlDirty && !textDirty) {
          span.setAttribute('observer.dispatch', 'none');
          opts.onDispatch?.('none');
          return;
        }
        if (transactions.every((t) => t.origin === OBSERVER_SYNC_ORIGIN)) {
          xmlDirty = false;
          textDirty = false;
          span.setAttribute('observer.dispatch', 'none');
          opts.onDispatch?.('none');
          return;
        }

        drainDidCorrectiveWork = false;
        drainReachedRawFixedPoint = false;
        drainDeferred = false;

        const ranA = xmlDirty;
        if (xmlDirty) {
          xmlDirty = false;
          opts.onDispatch?.('a');
          runObserverASync();
        }
        const ranB = textDirty;
        if (textDirty) {
          textDirty = false;
          opts.onDispatch?.('b');
          runObserverBSync();
        }

        if (fixedPointBackstopEnabled && !drainDeferred) {
          if (drainReachedRawFixedPoint) {
            oscillationRun = 0;
            recentSettledDigests.length = 0;
            bDirectionFrozen = false;
          } else if (drainDidCorrectiveWork) {
            const digest = fnv1aDigest(ytext.toString());
            if (recentSettledDigests.includes(digest)) {
              oscillationRun += 1;
              if (oscillationRun >= MAX_REDERIVE_ROUNDS && !bDirectionFrozen) {
                tripReDeriveBackstop(oscillationRun);
              }
            } else {
              oscillationRun = 0;
            }
            recentSettledDigests.push(digest);
            if (recentSettledDigests.length > REDERIVE_DIGEST_RING) recentSettledDigests.shift();
          }
        }

        span.setAttribute(
          'observer.dispatch',
          ranA && ranB ? 'a-then-b' : ranA ? 'a' : ranB ? 'b' : 'none',
        );
      },
    );
  };

  xmlFragment.observeDeep(observerA);
  ytext.observe(observerB);
  doc.on('afterAllTransactions', afterAll);
  const unregisterDirtyProbe = registerBridgeDirtyProbe(() => xmlDirty || textDirty);
  const detachQuiescence = attachQuiescenceTracker(doc);

  const preDrainController: PreDrainController = {
    preDrain(op: PreDrainOpInput): PreDrainVerdict {
      if (!preDrainEnabled) return { preDrain: false, reason: 'skip-disabled' };
      if (!fragmentMutatedSinceConverge) return { preDrain: false, reason: 'skip-no-pending' };

      try {
        const json = yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON();
        const fullMd = ytext.toString();
        const { body } = stripFrontmatter(fullMd);
        const fmPrefixLen = fullMd.length - body.length;

        const { preDrain, verdict, splice } = planPreDrain({
          pendingDirty: true,
          body,
          fragmentPmJson: json,
          witnessMatched: fullMd === lastSyncedYTextBytes,
          fmPrefixLen,
          lineEnding: documentBodyLineEnding(fullMd),
          op:
            op.kind === 'agent-undo'
              ? { kind: 'agent-undo', ytext, stackItem: op.stackItem }
              : { kind: 'agent-write', writeKind: op.writeKind },
          mdManager,
        });
        if (!preDrain) return verdict;

        const flushComposition = composeDerivedBodyMd(readCurrentFm(), mdManager.serialize(json));
        if (flushComposition.adjusted !== 'none') {
          return { preDrain: false, reason: 'checkpoint-fm-ambiguous' };
        }

        const bodyOffset = fullMd.length - body.length;
        doc.transact(() => {
          applyMapDrivenSplice(ytext, {
            spliceStart: bodyOffset + splice.spliceStart,
            spliceEnd: bodyOffset + splice.spliceEnd,
            newSlice: splice.newSlice,
          });
        }, OBSERVER_SYNC_ORIGIN);
        const canonicalMd = flushComposition.md;
        recordSettledBaselines(canonicalMd);
        lastConvergedFragmentMd = canonicalMd;
        fragmentMutatedSinceConverge = false;
        consecutiveDeriveTimingDefers = 0;
        return verdict;
      } catch (err) {
        incrementServerObserverError('a');
        log.warn(
          { err: err instanceof Error ? err : new Error(String(err)), docName: opts.docName },
          '[Server pre-drain] Discrimination threw — routing to the checkpoint floor',
        );
        return { preDrain: false, reason: 'checkpoint-witness-mismatch' };
      }
    },
  };
  preDrainControllers.set(doc, preDrainController);
  convergedFragmentWitnesses.set(doc, () => lastConvergedFragmentMd);
  externalEditorRecencies.set(doc, () =>
    lastExternalEditorChangeMs > 0 ? lastExternalEditorChangeMs : undefined,
  );

  return () => {
    unregisterDirtyProbe();
    detachQuiescence();
    preDrainControllers.delete(doc);
    convergedFragmentWitnesses.delete(doc);
    externalEditorRecencies.delete(doc);
    doc.off('afterAllTransactions', afterAll);
    xmlFragment.unobserveDeep(observerA);
    ytext.unobserve(observerB);
  };
}