Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Instrument the bridge divergence repair path (PRD-7973) (#3473)
Andrew Mikofalvy944020458466
diff --git a/.changeset/bridge-divergence-diagnosability.md b/.changeset/bridge-divergence-diagnosability.mdnew file mode 100644index 000000000..ac885a3dd--- /dev/null+++ b/.changeset/bridge-divergence-diagnosability.md@@ -0,0 +1,10 @@+---+"@inkeep/open-knowledge": patch+---++Bug reports about a document whose editor view keeps changing underneath you now carry enough evidence to diagnose it. Some documents contain a construct whose visual-editor view cannot be expressed back as the exact markdown behind it, and the bridge rebuilds that view on every save for as long as the document exists. The repair was already recorded, but not in a way that answered the two questions a report actually raises — how often it is happening, and what construct is causing it. Nothing about the repair itself changed; this is diagnostics only, and every field added is a number or a fixed label, never document text.++- Bridge divergence warnings now name the constructs that disagree — a bullet list against a paragraph, a table row against a heading, and what precedes them — instead of only a character offset. Previously the offending construct could not be identified without asking the reporter for their file, which is usually where the investigation stopped.+- A repair that rebuilds the editor view is recorded every time it runs. Recovery snapshots are deduplicated so one stuck document cannot crowd out everyone else's, which meant a document repairing itself hundreds of times looked identical to one that repaired once. The rebuild rate is now readable directly from a bug bundle, including the case where a document fails to serialize at all and no snapshot is taken.+- When the safety net at the merge boundary fires, its verdict is recorded: whether content went missing, was reordered, or was duplicated. Duplicated content reads to a user as text appearing rather than vanishing — the opposite complaint from the same underlying event — and that distinction previously survived only as an in-process counter that no bug report carried.+- Repair records now say whether the guard that protects un-propagated typing was able to run at all, separating "the guard could not evaluate this" from "the guard evaluated it and declined" — two different faults with two different fixes.diff --git a/knip.config.ts b/knip.config.tsindex 78162ec09..f9179f2d4 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -123,7 +123,9 @@ export default {'packages/server': {entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],project: 'src/**',- ignoreDependencies: ['@types/shell-quote'],+ ignoreDependencies: [+ '@types/shell-quote',+ ],},'packages/cli': {entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.tsindex d7a845280..dfd95ef49 100644--- a/packages/core/src/bridge/bind-frontmatter-doc.ts+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts@@ -1,3 +1,4 @@+import type * as Y from 'yjs';import type { Err, Ok, Result } from '../config/result.ts';import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.tsindex 005627195..8bfdb40cd 100644--- a/packages/core/src/bridge/bridge-invariant.ts+++ b/packages/core/src/bridge/bridge-invariant.ts@@ -1,3 +1,4 @@+import { fnv1aDigest } from './hash-util.ts';export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.tsindex f4cc8a286..2a597ec3d 100644--- a/packages/core/src/bridge/compose.ts+++ b/packages/core/src/bridge/compose.ts@@ -1,3 +1,4 @@+import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';diff --git a/packages/core/src/bridge/divergence-locate.ts b/packages/core/src/bridge/divergence-locate.tsnew file mode 100644index 000000000..d979f4b39--- /dev/null+++ b/packages/core/src/bridge/divergence-locate.ts@@ -0,0 +1,103 @@++import { findFirstDivergenceIndex } from './tolerance-telemetry.ts';++export const BRIDGE_LINE_KINDS = [+ 'blank',+ 'frontmatter-fence',+ 'heading',+ 'thematic-break',+ 'fence',+ 'blockquote',+ 'bullet-list-item',+ 'ordered-list-item',+ 'table-row',+ 'jsx-tag',+ 'html-block',+ 'paragraph',+ 'absent',+] as const;++export type BridgeLineKind = (typeof BRIDGE_LINE_KINDS)[number];++export interface BridgeDivergenceLocation {+ index: number;+ normalizedLine: number;+ normalizedColumn: number;+ ytextLineKind: BridgeLineKind;+ fragmentLineKind: BridgeLineKind;+ precedingLineKind: BridgeLineKind;+}++function divergenceOffset(a: string, b: string): number {+ const found = findFirstDivergenceIndex(a, b);+ return found === -1 ? Math.min(a.length, b.length) : found;+}++export function classifyBridgeLine(line: string, isFirstLine = false): BridgeLineKind {+ if (line.trim() === '') return 'blank';+ const t = line.trimStart();+ if (isFirstLine && /^-{3,}\s*$/.test(t)) return 'frontmatter-fence';+ if (/^#{1,6}(\s|$)/.test(t)) return 'heading';+ if (/^(?:`{3,}|~{3,})/.test(t)) return 'fence';+ if (t.startsWith('>')) return 'blockquote';+ if (/^(?:-{3,}|\*{3,}|_{3,})\s*$/.test(t)) return 'thematic-break';+ if (/^[-+*](\s|$)/.test(t)) return 'bullet-list-item';+ if (/^\d+[.)](\s|$)/.test(t)) return 'ordered-list-item';+ if (t.startsWith('|')) return 'table-row';+ if (/^<\/?[A-Z]/.test(t)) return 'jsx-tag';+ if (/^<[a-z!/]/i.test(t)) return 'html-block';+ return 'paragraph';+}++export function locateBridgeDivergence(+ ytextNorm: string,+ fragmentNorm: string,+): BridgeDivergenceLocation {+ const index = divergenceOffset(ytextNorm, fragmentNorm);++ let line = 1;+ let lastNewline = -1;+ for (let i = 0; i < index; i++) {+ if (ytextNorm[i] === '\n') {+ line++;+ lastNewline = i;+ }+ }++ return {+ index,+ normalizedLine: line,+ normalizedColumn: index - lastNewline,+ ytextLineKind: lineKindAt(ytextNorm, index, line),+ fragmentLineKind: lineKindAt(fragmentNorm, index, line),+ precedingLineKind: precedingKindAt(ytextNorm, index, line),+ };+}++function lineAt(s: string, index: number): string | null {+ if (index > s.length) return null;+ if (index === s.length && s.length > 0 && index > 0) return null;+ const start = s.lastIndexOf('\n', Math.max(0, index - 1)) + 1;+ const end = s.indexOf('\n', index);+ return s.slice(start, end === -1 ? s.length : end);+}++function lineKindAt(s: string, index: number, lineOrdinal: number): BridgeLineKind {+ const line = lineAt(s, index);+ if (line === null) return 'absent';+ return classifyBridgeLine(line, lineOrdinal === 1);+}++function precedingKindAt(s: string, index: number, lineOrdinal: number): BridgeLineKind {+ if (lineOrdinal <= 1 || index > s.length) return 'absent';+ let cursor = s.lastIndexOf('\n', Math.max(0, index - 1));+ let ordinal = lineOrdinal;+ while (cursor > 0) {+ const start = s.lastIndexOf('\n', cursor - 1) + 1;+ const candidate = s.slice(start, cursor);+ ordinal--;+ if (candidate.trim() !== '') return classifyBridgeLine(candidate, ordinal === 1);+ cursor = start - 1;+ }+ return 'absent';+}diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex 8fb428b90..01ef76a9f 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,3 +1,4 @@+import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.tsindex 9d9c244b0..463e89595 100644--- a/packages/core/src/bridge/growth-detect.ts+++ b/packages/core/src/bridge/growth-detect.ts@@ -1,3 +1,4 @@+const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;diff --git a/packages/core/src/bridge/index.ts b/packages/core/src/bridge/index.tsindex 4b1bdbffb..d16e2da50 100644--- a/packages/core/src/bridge/index.ts+++ b/packages/core/src/bridge/index.ts@@ -30,6 +30,13 @@ export {composeWithDerivedFrontmatter,} from './compose.ts';export { type DiffChange, diffLinesFast } from './diff-lines.ts';+export {+ BRIDGE_LINE_KINDS,+ type BridgeDivergenceLocation,+ type BridgeLineKind,+ classifyBridgeLine,+ locateBridgeDivergence,+} from './divergence-locate.ts';export {bodyEdgeEmpties,createMergeBoundarySpace,diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.tsindex c43fdd7e7..0939885bb 100644--- a/packages/core/src/bridge/intraline-predicate.ts+++ b/packages/core/src/bridge/intraline-predicate.ts@@ -1,3 +1,4 @@+export function rawLineCounts(doc: string): Map<string, number> {const counts = new Map<string, number>();for (const line of doc.split('\n')) {diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.tsindex 251560a35..c0dc65705 100644--- a/packages/core/src/bridge/merge-three-way.ts+++ b/packages/core/src/bridge/merge-three-way.ts@@ -65,6 +65,7 @@ export function tryLineLevelCombine(return { clean: true, merged };}+export type BridgeMergeContentLossSide = 'user' | 'agent';export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.tsindex 01ac80099..dcc5b0690 100644--- a/packages/core/src/bridge/normalize.ts+++ b/packages/core/src/bridge/normalize.ts@@ -1,3 +1,4 @@+import { stripFrontmatter } from '../extensions/frontmatter.ts';import { bodyEdgeEmpties } from './doc-boundary-space.ts';diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.tsindex 754dc5cc2..0be5203e4 100644--- a/packages/core/src/bridge/pm-structural-equivalence.ts+++ b/packages/core/src/bridge/pm-structural-equivalence.ts@@ -32,6 +32,7 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };const BR_LITERAL_RE = /^<br\s*\/?>$/i;+interface DegradeEntry {readonly label: string;readonly severity: ToleranceClassSeverity;@@ -127,6 +128,7 @@ export interface ComparePmStructuralOptions {ignoreAttrs?: (attrKey: string) => boolean;}+/** Rebuild a node with `fn` applied to each child; identity when childless.* Shared by the degrade canonicalizers so none re-implements the walk. */function mapChildren(@@ -248,6 +250,7 @@ function applyDegrades(tree: PmStructuralNode): {return { normalized: current, fired };}+export function comparePmStructural(expected: PmStructuralNode,actual: PmStructuralNode,diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.tsindex af20de1e2..dca644141 100644--- a/packages/core/src/bridge/subsequence.ts+++ b/packages/core/src/bridge/subsequence.ts@@ -1,3 +1,4 @@+/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):* insertions in `haystack` are free; any dropped or substituted `needle` byte* fails. */diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 2d8c092ae..e68fd34c2 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -1499,12 +1499,15 @@ export {applyRenameToFm,applyReorderToFm,assertContentPreservation,+ BRIDGE_LINE_KINDS,BRIDGE_TOLERANCE_CLASSES,type BridgeComposition,+ type BridgeDivergenceLocation,type BridgeInvariantLogPayload,type BridgeInvariantSite,type BridgeInvariantViolation,BridgeInvariantViolationError,+ type BridgeLineKind,BridgeMergeContentLossError,type BridgeMergeContentLossInfo,type BridgeMergeContentLossLogPayload,@@ -1516,6 +1519,7 @@ export {bodyEdgeEmpties,type ComparePmStructuralOptions,type ComposeAdjustment,+ classifyBridgeLine,classifySeverity,comparePmStructural,compareRoundTripStructural,@@ -1553,6 +1557,7 @@ export {fragmentHoldsPendingContent,type InvariantViolation,isParseEquivalentBridge,+ locateBridgeDivergence,MAX_FM_REGION_BYTES,type MergeBoundarySpace,mergeThreeWay,diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.tsindex 83d47404a..a363dfd54 100644--- a/packages/core/src/markdown/callout-transformer.ts+++ b/packages/core/src/markdown/callout-transformer.ts@@ -1,3 +1,4 @@+import type { Blockquote, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.tsindex 9807a7e82..4499dbc92 100644--- a/packages/core/src/markdown/code-fence.ts+++ b/packages/core/src/markdown/code-fence.ts@@ -1,3 +1,4 @@+export function selectFenceChar(info: string): '`' | '~' {return info.includes('`') ? '~' : '`';}diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex 7415c474a..34704165b 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.tsindex ece5c02a1..b6299a948 100644--- a/packages/core/src/markdown/dedent-block-jsx-close.ts+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts@@ -1,3 +1,4 @@+import { findFencedRegions, isInsideFence } from './fence-regions.ts';const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.tsindex 54774764a..acd398aa6 100644--- a/packages/core/src/markdown/details-accordion-promoter.ts+++ b/packages/core/src/markdown/details-accordion-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.tsindex 43ecdc709..ba9b56384 100644--- a/packages/core/src/markdown/div-align-promoter.ts+++ b/packages/core/src/markdown/div-align-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.tsindex 6d3f3643e..4513da9bb 100644--- a/packages/core/src/markdown/fence-regions.ts+++ b/packages/core/src/markdown/fence-regions.ts@@ -1,3 +1,4 @@+const FENCE_RE = /^(`{3,}|~{3,})/gm;export function findFencedRegions(src: string): Array<[number, number]> {diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.tsindex 00f5771ee..6931623c7 100644--- a/packages/core/src/markdown/fixtures/index.ts+++ b/packages/core/src/markdown/fixtures/index.ts@@ -1,3 +1,4 @@+import { readFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {return resolve(FIXTURES_DIR, ...segments);}+interface GfmExample {section: string;markdown: string;@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];}+interface MdxCrashEntry {id: string;input: string;@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {) as LargeEmbedFixture[];}+export function loadPrd6955Before(): string {return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');}@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');}+export interface NgPinnedCase {id: string;name: string;@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {) as NgPinnedCase[];}+export function loadLargeRealistic(): string {return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');}diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.tsindex 8b1eb8519..daa3ef82b 100644--- a/packages/core/src/markdown/fixtures/perf/generate.ts+++ b/packages/core/src/markdown/fixtures/perf/generate.ts@@ -1,3 +1,4 @@+import { writeFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;const SEED = 0xf1de1117;+function mulberry32(seed: number): () => number {let a = seed >>> 0;return () => {@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {return items[items.length - 1][0];}+const WORDS = ['lorem','ipsum',@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;}+type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';const MIX: readonly [BlockKind, number][] = [@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {return `${blocks.join('\n\n')}\n`;}+function main(): void {for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {const doc = generateDocument(count, SEED);diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.tsindex 420dc0fe5..32c055c5b 100644--- a/packages/core/src/markdown/guard-flanking-matrix.ts+++ b/packages/core/src/markdown/guard-flanking-matrix.ts@@ -7,6 +7,7 @@ import {import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';+export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;export type FlankClass = 'whitespace' | 'punctuation' | 'other';diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.tsindex 2653473da..283913255 100644--- a/packages/core/src/markdown/handler-shadow-audit.ts+++ b/packages/core/src/markdown/handler-shadow-audit.ts@@ -1,3 +1,4 @@+export interface HandlerShadowWitness {input: string;expect: 'byte' | 'byte-and-reparse-type';diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.tsindex da0a81d23..5d1000cc4 100644--- a/packages/core/src/markdown/highlight-promoter.ts+++ b/packages/core/src/markdown/highlight-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.tsindex 787315157..9681c0056 100644--- a/packages/core/src/markdown/html-to-mdast.ts+++ b/packages/core/src/markdown/html-to-mdast.ts@@ -1,3 +1,4 @@+import type { Element as HastElement, Root as HastRoot } from 'hast';import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';import rehypeParse from 'rehype-parse';@@ -128,7 +129,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRothrow new HtmlPayloadTooLargeError(html.length, maxBytes);}- const processor = unified().use(rehypeParse, { fragment: true });+ const processor = unified()+ .use(rehypeParse, { fragment: true });for (const plugin of cleanupPlugins) {processor.use(plugin);diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.tsindex 706fa9afb..994eb6917 100644--- a/packages/core/src/markdown/image-promoter.ts+++ b/packages/core/src/markdown/image-promoter.ts@@ -1,3 +1,4 @@+import type { Image, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.tsindex 779e27500..ec1ac1b7e 100644--- a/packages/core/src/markdown/index.ts+++ b/packages/core/src/markdown/index.ts@@ -1,3 +1,4 @@+import {type FromProseMirrorOptions,fromPmMark,@@ -206,6 +207,7 @@ export class MarkdownManager {}}+const registry = createRegistry();function destructureAttrs(@@ -254,6 +256,7 @@ function destructureAttrs(return result;}+function hasDirtyDescendant(node: PmNode): boolean {let found = false;node.descendants((child) => {@@ -276,6 +279,7 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChecreturn freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;}+function isEmptyMdastParagraph(node: MdastNodes): boolean {if (node.type !== 'paragraph') return false;const children = node.children ?? [];@@ -344,6 +348,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {return out;}+import {AUDIO_EXTENSIONS,FILE_ATTACHMENT_EXTENSIONS,@@ -596,6 +601,7 @@ function buildMdastToPmHandlers(}));}+if (m.emphasis) {handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({sourceDelimiter: node.data?.sourceDelimiter ?? '*',@@ -676,6 +682,7 @@ function buildMdastToPmHandlers(}));}+if (m.link) {const sourceLiteralMark = m.sourceLiteral;handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {@@ -973,6 +980,7 @@ function buildMdastToPmHandlers(};}+const blockUnknownHandler = (node: {type: string;position?: { start: { offset: number }; end: { offset: number } };@@ -1098,6 +1106,7 @@ function buildMdastToPmHandlers(return handlers as RemarkProseMirrorOptions['handlers'];}+function buildPmToMdastHandlers(schema: Schema,freshness: FreshnessCheckerHolder,diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.tsindex fa0be9e86..b79e9aef7 100644--- a/packages/core/src/markdown/lint/applies-to.ts+++ b/packages/core/src/markdown/lint/applies-to.ts@@ -1,3 +1,4 @@+import picomatch from 'picomatch';import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.tsindex 312c9c74b..94b34dee1 100644--- a/packages/core/src/markdown/lint/config-files.ts+++ b/packages/core/src/markdown/lint/config-files.ts@@ -1,3 +1,4 @@+const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set(['.markdownlint.json','.markdownlint.jsonc',diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.tsindex c400441b2..1e3ad29c6 100644--- a/packages/core/src/markdown/lint/config-schemas.ts+++ b/packages/core/src/markdown/lint/config-schemas.ts@@ -39,6 +39,7 @@ const fullPluginShape = Object.fromEntries(LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),) as z.ZodRawShape;+export const LinterConfigSchema = z.object({enabled: z.boolean(),plugins: z.object(fullPluginShape),diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.tsindex d48eea5e4..a51f2ffb0 100644--- a/packages/core/src/markdown/lint/default-config.ts+++ b/packages/core/src/markdown/lint/default-config.ts@@ -6,6 +6,7 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSettingMD013: false,};+export function resolveMarkdownlintConfig(rules: Record<string, MarkdownlintRuleSetting> | undefined,): Configuration {diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.tsindex ef478e268..9c9542661 100644--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts@@ -1,3 +1,4 @@+import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';export interface FrontmatterFieldConstraint {diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.tsindex 0d4c9a0df..b96d19182 100644--- a/packages/core/src/markdown/lint/frontmatter-validate.ts+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts@@ -1,3 +1,4 @@+import Ajv, { type ValidateFunction } from 'ajv';import Ajv2019 from 'ajv/dist/2019.js';import Ajv2020 from 'ajv/dist/2020.js';diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.tsindex af38c2ae2..1ca263610 100644--- a/packages/core/src/markdown/lint/index.ts+++ b/packages/core/src/markdown/lint/index.ts@@ -1,3 +1,4 @@+import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';import type { LintDiagnostic } from './types.ts';diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.tsindex 5e832aa19..be5871ed9 100644--- a/packages/core/src/markdown/lint/plugins.ts+++ b/packages/core/src/markdown/lint/plugins.ts@@ -1,3 +1,4 @@+import { z } from 'zod';import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';import {@@ -13,6 +14,7 @@ import {type MarkdownlintSlice,} from './types.ts';+const MarkdownlintRuleSettingSchema = z.union([z.boolean(),z.enum(MARKDOWNLINT_RULE_SEVERITIES),diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.tsindex 01ce4a5af..3dae5c031 100644--- a/packages/core/src/markdown/lint/types.ts+++ b/packages/core/src/markdown/lint/types.ts@@ -1,3 +1,4 @@+import type { BrokenLinkReason } from '../../schemas/api/agent-write.ts';export const LINT_PLUGIN_IDS = ['markdownlint', 'frontmatter'] as const;@@ -98,6 +99,7 @@ export interface FrontmatterSlice {schemas: ResolvedFrontmatterSchemaEntry[];}+interface RuleOptionSpecBase {key: string;description: string;diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.tsindex 98238656e..437cc539a 100644--- a/packages/core/src/markdown/lint/validation-counts.ts+++ b/packages/core/src/markdown/lint/validation-counts.ts@@ -1,3 +1,4 @@+export interface ValidationSourceCounts {errorCount: number;warningCount: number;diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.tsindex a5b511f25..bd79424c7 100644--- a/packages/core/src/markdown/math-promoter.ts+++ b/packages/core/src/markdown/math-promoter.ts@@ -1,3 +1,4 @@+import type { Code, Root } from 'mdast';import type { Math as MdastMath } from 'mdast-util-math';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.tsindex ed89371d0..00fbc0035 100644--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts@@ -1,3 +1,4 @@+import type { Comment, Element, ElementContent, Properties } from 'hast';import type { FootnoteDefinition, FootnoteReference } from 'mdast';import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.tsindex 8ce2b2492..df788a80d 100644--- a/packages/core/src/markdown/mdast-to-html.ts+++ b/packages/core/src/markdown/mdast-to-html.ts@@ -1,3 +1,4 @@+import type { Element, Root as HastRoot, Text as HastText } from 'hast';import type { Root as MdastRoot, Text as MdastText } from 'mdast';import type { Handler } from 'mdast-util-to-hast';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex bfd7e3109..fa3cfcd86 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.tsindex 1a897fca8..17ed2b829 100644--- a/packages/core/src/markdown/mermaid-promoter.ts+++ b/packages/core/src/markdown/mermaid-promoter.ts@@ -1,3 +1,4 @@+import type { Code, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.tsindex d988f4b8b..4aa0490c4 100644--- a/packages/core/src/markdown/parse-with-fallback.ts+++ b/packages/core/src/markdown/parse-with-fallback.ts@@ -168,6 +168,7 @@ export function parseRecursive(}}+interface VFilePlace {offset?: number;start?: { offset?: number };@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {return undefined;}+interface Region {start: number;end: number;@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {return null;}+export interface TagEvent {kind: 'open' | 'close' | 'self-close';name: string;@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {return { start: blockStart, end: blockEnd };}+interface SourceBlock {src: string;start: number;@@ -452,6 +456,7 @@ function tryPerBlockFallback(};}+function wholeDocRawText(source: string): JSONContent {return {type: 'doc',diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.tsindex e6ab4fd57..43d420187 100644--- a/packages/core/src/markdown/parser-drop-closure.ts+++ b/packages/core/src/markdown/parser-drop-closure.ts@@ -1,3 +1,4 @@+export type DroppedTokenAdjudication =| {kind: 'format-dof-axis';diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.tsindex 0e3224206..55736041c 100644--- a/packages/core/src/markdown/pipeline.ts+++ b/packages/core/src/markdown/pipeline.ts@@ -1,3 +1,4 @@+import {type FromProseMirrorOptions,fromProseMirror,diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.tsindex 91cdf658f..ccf06e94d 100644--- a/packages/core/src/markdown/position-aware-join.ts+++ b/packages/core/src/markdown/position-aware-join.ts@@ -1,3 +1,4 @@+import type { Join } from 'mdast-util-to-markdown';import type { Position } from 'unist';import { isBlankLineParagraph } from './zero-emission-blocks.ts';diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.tsindex 0f399d34c..e5b4c9eba 100644--- a/packages/core/src/markdown/position-slice.ts+++ b/packages/core/src/markdown/position-slice.ts@@ -1,3 +1,4 @@+import type { Nodes, Root } from 'mdast';import { visit } from 'unist-util-visit';import type { VFile } from 'vfile';@@ -476,7 +477,8 @@ export function applyPositionSliceToNode(const first = source[startOff];if (first !== '[' && first !== '<' && !node.title) {node.data.sourceStyle = 'gfm-autolink';- } else if (first === '[') {+ }+ else if (first === '[') {const slice = source.slice(startOff, endOff);const closeBracketIdx = slice.lastIndexOf('](');if (closeBracketIdx !== -1) {diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.tsindex db10fa54b..ca225ce9b 100644--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts@@ -1,3 +1,4 @@+import type { Comment, Element, Root, Text } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.tsindex 34068d103..3a2524a9a 100644--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.tsindex 93151d43b..2279a0189 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.tsindex 188f02d83..a0f467c42 100644--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.tsindex 4ba2c3418..4e8542a21 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.tsindex 1a74b1272..a3c96b24a 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.tsindex de35e7b79..e95cf43d6 100644--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts@@ -1,3 +1,4 @@+import type { Comment, Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.tsindex b4be1b2ea..ffdb4d5b5 100644--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.tsindex 3c8d88b7c..e2a96d1a7 100644--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.tsindex cf2c9da8e..0389575ac 100644--- a/packages/core/src/markdown/resolve-image-url.ts+++ b/packages/core/src/markdown/resolve-image-url.ts@@ -1,3 +1,4 @@+import { isRelativeUrl } from './safe-url.ts';function isDevDiagnosticContext(): boolean {diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 4d3250d3a..8be632ba4 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,3 +1,4 @@+export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.tsindex 0dd54070e..96304e7a5 100644--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts@@ -1,3 +1,4 @@+import type { JSONContent } from '@tiptap/core';import type { Nodes } from 'mdast';import { expect } from 'vitest';diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.tsindex 7cac5b042..93798cf83 100644--- a/packages/core/src/markdown/serialize-helpers.ts+++ b/packages/core/src/markdown/serialize-helpers.ts@@ -1,3 +1,4 @@+import type { Node as PmNode } from '@tiptap/pm/model';import type {MdxJsxAttribute,diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.tsindex b012a5aff..8c08b7a04 100644--- a/packages/core/src/markdown/single-dollar-math-promoter.ts+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts@@ -1,3 +1,4 @@+import type { PhrasingContent, Root, Text } from 'mdast';import type { InlineMath } from 'mdast-util-math';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.tsindex 3e79f8cb6..959cc0bd2 100644--- a/packages/core/src/markdown/to-markdown-handlers.ts+++ b/packages/core/src/markdown/to-markdown-handlers.ts@@ -1,3 +1,4 @@+import type { Nodes, Parents } from 'mdast';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { Handle, Info, State } from 'mdast-util-to-markdown';diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.tsindex 0f1b0f27d..6e6d73400 100644--- a/packages/core/src/markdown/underline-promoter.ts+++ b/packages/core/src/markdown/underline-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, Root } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.tsindex 1a082bda7..932d7d2a8 100644--- a/packages/core/src/markdown/unknown-mdast-guard.ts+++ b/packages/core/src/markdown/unknown-mdast-guard.ts@@ -1,3 +1,4 @@+import type { Root as MdastRoot } from 'mdast';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.tsindex d578476a7..ac9f5239b 100644--- a/packages/core/src/markdown/whitespace-char-ref.ts+++ b/packages/core/src/markdown/whitespace-char-ref.ts@@ -1,3 +1,4 @@+const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([[0x20, ' '],[0x09, '\t'],diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.tsindex 6dad26200..afd9936fe 100644--- a/packages/core/src/markdown/wiki-link-micromark.ts+++ b/packages/core/src/markdown/wiki-link-micromark.ts@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {}}+const CODE_BANG = 33; // !const CODE_LBRACKET = 91; // [const CODE_RBRACKET = 93; // ]@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {};}+function enterWikiLink(this: CompileContext, token: Token) {this.enter({@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {unsafe: [{ character: '[', inConstruct: ['phrasing'] }],};+const MICROMARK_EXT = wikiLinkSyntax();export function remarkWikiLink(this: Processor) {diff --git a/packages/server/src/bridge-watchdog.ts b/packages/server/src/bridge-watchdog.tsindex 9f9e48519..32691c6e0 100644--- a/packages/server/src/bridge-watchdog.ts+++ b/packages/server/src/bridge-watchdog.ts@@ -49,6 +49,7 @@ import {detectAppliedToleranceClasses,emitToleranceFire,isParseEquivalentBridge,+ locateBridgeDivergence,normalizeBridge,PARSE_EQUIVALENCE_TOLERANCE,toBridgeInvariantLog,@@ -484,14 +485,6 @@ export function createDocCanonicalizer(// Watchdog assertion// ─────────────────────────────────────────────────────────────-/** Offset of the first differing character (== min length when one input is a prefix of the other). */-function firstDivergenceIndex(a: string, b: string): number {- const max = Math.min(a.length, b.length);- let i = 0;- while (i < max && a[i] === b[i]) i++;- return i;-}-interface AssertBridgeInvariantOpts {site: BridgeInvariantSite;/** Doc name for log attribution + rate-limiter scoping. */@@ -670,9 +663,16 @@ export function assertBridgeInvariant(return false;}incrementBridgeInvariantViolations();- // Content-free divergence summary — lengths + first-divergence offset- // only. Snapshot bytes are user content and must not reach the file sink- // (the redaction posture the hash-only console event already takes).+ // Content-free divergence summary — lengths, offset, and the BLOCK-CONSTRUCT+ // kinds meeting at the divergence. Snapshot bytes are user content and must+ // not reach the file sink (the redaction posture the hash-only console event+ // already takes), but a construct kind is drawn from a closed vocabulary and+ // discloses shape rather than words. An offset alone cannot name what broke:+ // a document that trips here on every drain is otherwise undiagnosable+ // without asking its owner for the file, which is where such an+ // investigation usually stops. The line ordinal is in NORMALIZED comparison+ // space, not the user's file — see `locateBridgeDivergence`.+ const divergence = locateBridgeDivergence(ytextNorm, fragNorm);log.warn({site: opts.site,@@ -681,7 +681,12 @@ export function assertBridgeInvariant(fragmentBytes: fragmentMdSnapshot.length,normalizedYtextBytes: ytextNorm.length,normalizedFragmentBytes: fragNorm.length,- firstDivergenceIndex: firstDivergenceIndex(ytextNorm, fragNorm),+ firstDivergenceIndex: divergence.index,+ normalizedLine: divergence.normalizedLine,+ normalizedColumn: divergence.normalizedColumn,+ ytextLineKind: divergence.ytextLineKind,+ fragmentLineKind: divergence.fragmentLineKind,+ precedingLineKind: divergence.precedingLineKind,},`[bridge-watchdog] bridge invariant violation at ${opts.site}${opts.docName ? ` for '${opts.docName}'` : ''diff --git a/packages/server/src/loss-capture.test.ts b/packages/server/src/loss-capture.test.tsindex 014ac76e4..f945ae0e2 100644--- a/packages/server/src/loss-capture.test.ts+++ b/packages/server/src/loss-capture.test.ts@@ -10,6 +10,7 @@ import {LOSS_EVENT_GUARD_DEFER,LOSS_EVENT_KINDS,LOSS_EVENT_PERSISTENCE_HOLD,+ LOSS_EVENT_REPAIR_REBUILD,type LossCaptureEvent,LossCaptureEventSchema,LossCaptureRing,@@ -83,8 +84,9 @@ describe('LossCaptureRing.record', () => {it('produces one distinguishable kind per loss-class mechanism', async () => {// The kinds must never alias — a bundle reader distinguishes a deferred// re-derive from a tripped detector/backstop from a written checkpoint from- // a tolerated persistence hold by this field alone.- expect(new Set(LOSS_EVENT_KINDS).size).toBe(5);+ // a tolerated persistence hold from an executed destructive rebuild by this+ // field alone.+ expect(new Set(LOSS_EVENT_KINDS).size).toBe(6);const ring = new LossCaptureRing({ projectDir, maxBytes: 1_000_000, now: () => 1 });for (const kind of LOSS_EVENT_KINDS) {@@ -99,8 +101,9 @@ describe('LossCaptureRing.record', () => {LOSS_EVENT_BACKSTOP_TRIP,LOSS_EVENT_CHECKPOINT_WRITE,LOSS_EVENT_PERSISTENCE_HOLD,+ LOSS_EVENT_REPAIR_REBUILD,]);- expect(new Set(kinds).size).toBe(5);+ expect(new Set(kinds).size).toBe(6);});it('keeps the newest events when the file rotates at its cap', async () => {@@ -155,6 +158,7 @@ describe('LossCaptureEventSchema (content-free BY SCHEMA)', () => {const keys = Object.keys(LossCaptureEventSchema.shape).sort();expect(keys).toEqual(['checkpointSha',+ 'connections','digest','direction','docName',@@ -164,6 +168,8 @@ describe('LossCaptureEventSchema (content-free BY SCHEMA)', () => {'seq','site','ts',+ 'which',+ 'witnessAvailable','writerId',]);// Belt-and-suspenders: none of the fields is a content-bearing name. The@@ -196,6 +202,9 @@ describe('LossCaptureEventSchema (content-free BY SCHEMA)', () => {lostLen: 88,digest: 'abc123',checkpointSha: 'f00dcafe',+ which: 'growth',+ witnessAvailable: false,+ connections: 2,};const roundTripped = LossCaptureEventSchema.parse(JSON.parse(JSON.stringify(event)));expect(roundTripped).toEqual(event);diff --git a/packages/server/src/loss-capture.ts b/packages/server/src/loss-capture.tsindex dbd347879..3bda3682c 100644--- a/packages/server/src/loss-capture.ts+++ b/packages/server/src/loss-capture.ts@@ -18,6 +18,7 @@*/import { join } from 'node:path';+import type { BridgeMergeContentLossWhich } from '@inkeep/open-knowledge-core';import { z } from 'zod';import { getLogger } from './logger.ts';import { RotatingAppender } from './telemetry-file-sink.ts';@@ -46,6 +47,15 @@ export const LOSS_EVENT_CHECKPOINT_WRITE = 'checkpoint-write';// so a bundle reader can tell "the hygiene layer tolerated a divergence" from// "a detector tripped", which are opposite outcomes at the same boundary.export const LOSS_EVENT_PERSISTENCE_HOLD = 'persistence-hold';+// A destructive fragment rebuild actually ran. Distinct from+// `checkpoint-write`, which reports that a restore ANCHOR was minted: the two+// are not 1:1, because the anchor mint is deduped per document against its last+// payload and is skipped entirely when serialization produced no fragment view.+// A document whose fragment view diverges on every write-back therefore rebuilds+// indefinitely while emitting at most one anchor, so without its own kind the+// rebuild RATE — the thing that distinguishes a one-off repair from a document+// stuck in a permanent repair loop — is absent from the ring.+export const LOSS_EVENT_REPAIR_REBUILD = 'repair-rebuild';export const LOSS_EVENT_KINDS = [LOSS_EVENT_GUARD_DEFER,@@ -53,6 +63,7 @@ export const LOSS_EVENT_KINDS = [LOSS_EVENT_BACKSTOP_TRIP,LOSS_EVENT_CHECKPOINT_WRITE,LOSS_EVENT_PERSISTENCE_HOLD,+ LOSS_EVENT_REPAIR_REBUILD,] as const;type LossEventKind = (typeof LOSS_EVENT_KINDS)[number];@@ -87,6 +98,32 @@ export const LossCaptureEventSchema = z.object({digest: z.string().optional(),/** Git sha of the checkpoint that preserved the content, when one was written. */checkpointSha: z.string().optional(),+ /**+ * Which arm of a content-preservation post-condition failed — content went+ * missing, content was reordered, or content was over-multiplied. Recovery is+ * identical for all of them, so nothing else in-process tells them apart per+ * occurrence, and the over-multiplication arm is the field signature of+ * duplicated content: to a user that reads as content APPEARING rather than+ * vanishing, the opposite complaint from the same event. Open string on read+ * so a future verdict parses on an older reader.+ */+ which: z.string().optional(),+ /**+ * Whether a converged fragment witness was published when a tolerance+ * decision was made. Separates "observers published no witness, so the+ * tolerance could not be evaluated at all" from "the guard ran against a real+ * witness and declined to protect the content" — two different defects with+ * two different fixes, previously indistinguishable from the ring alone.+ */+ witnessAvailable: z.boolean().optional(),+ /**+ * Client connections attached to the document when the event fired. A+ * destructive repair with nobody attached is invisible background hygiene;+ * the same repair under an attached editor is the instant a user's view+ * changes underneath them. Not a focus signal — the server cannot observe+ * focus — so it bounds the blast radius rather than proving impact.+ */+ connections: z.number().optional(),});export type LossCaptureEvent = z.infer<typeof LossCaptureEventSchema>;@@ -106,6 +143,14 @@ export interface LossCaptureEventInput {lostLen?: number;digest?: string;checkpointSha?: string;+ /**+ * Closed producer vocabulary bound to the merge post-condition's own verdict+ * type, so a new arm there is a compile error here rather than a silently+ * unrecorded one; the read schema keeps it an open string.+ */+ which?: BridgeMergeContentLossWhich;+ witnessAvailable?: boolean;+ connections?: number;}const LOSS_CAPTURE_SUBDIR = ['.ok', 'local', 'loss-capture'] as const;@@ -200,6 +245,9 @@ export class LossCaptureRing {...(input.lostLen !== undefined ? { lostLen: input.lostLen } : {}),...(input.digest !== undefined ? { digest: input.digest } : {}),...(input.checkpointSha !== undefined ? { checkpointSha: input.checkpointSha } : {}),+ ...(input.which !== undefined ? { which: input.which } : {}),+ ...(input.witnessAvailable !== undefined ? { witnessAvailable: input.witnessAvailable } : {}),+ ...(input.connections !== undefined ? { connections: input.connections } : {}),};return this.#appender.append(`${JSON.stringify(event)}\n`).catch((err: unknown) => {log.warn({ event: input.event, err }, '[loss-capture] failed to write loss-class event');diff --git a/packages/server/src/persistence-defer-hold.test.ts b/packages/server/src/persistence-defer-hold.test.tsindex 3dba2b8be..834f7c896 100644--- a/packages/server/src/persistence-defer-hold.test.ts+++ b/packages/server/src/persistence-defer-hold.test.ts@@ -449,11 +449,24 @@ describe('persistence pre-write divergence arms', () => {expect(row?.checkpoint?.kind).toBe('persistence-reconcile-loss');expect(row?.checkpoint?.metadata).toEqual({ atRiskLines: 1, witnessAvailable: true });- const writes = (await h.readRing()).filter(+ const ring = await h.readRing();+ const writes = ring.filter((e) => e.event === 'checkpoint-write' && e.site === 'persistence-prewrite',);expect(writes.some((e) => e.checkpointSha === sha)).toBe(true);expect(writes.every((e) => e.lostLen === STALE_FRAGMENT_ONLY_LINE.length)).toBe(true);+ // The witness verdict reaches the RING, not only the checkpoint metadata:+ // a bundle without the shadow repo still has to separate "no witness was+ // published" from "the guard ran and declined".+ expect(writes.every((e) => e.witnessAvailable === true)).toBe(true);++ // The rebuild itself is breadcrumbed, distinctly from the anchor mint.+ const rebuilds = ring.filter((e) => e.event === 'repair-rebuild');+ expect(rebuilds).toHaveLength(1);+ expect(rebuilds[0]?.site).toBe('persistence-prewrite');+ expect(rebuilds[0]?.direction).toBe('b');+ expect(typeof rebuilds[0]?.connections).toBe('number');+ expect(JSON.stringify(rebuilds)).not.toContain(STALE_FRAGMENT_ONLY_LINE);} finally {await h.cleanup();}@@ -482,6 +495,18 @@ describe('persistence pre-write divergence arms', () => {// Negative bound: give a second mint every chance to appear, then assert// the ref set never grew.expect(await awaitMints(h, 2)).toEqual([firstSha]);++ // ...and the ring still shows BOTH rebuilds. This is the whole point of a+ // per-rebuild breadcrumb: a document that diverges at this boundary on+ // every write-back repairs forever while minting one anchor, so an+ // anchor-shaped record alone reports a permanent repair loop as a single+ // one-off repair. Only one `checkpoint-write` — the dedup suppressed the+ // second mint, and the rebuild record is what carries the rate.+ const ring = await h.readRing();+ expect(ring.filter((e) => e.event === 'repair-rebuild')).toHaveLength(2);+ expect(+ ring.filter((e) => e.event === 'checkpoint-write' && e.site === 'persistence-prewrite'),+ ).toHaveLength(1);} finally {await h.cleanup();}@@ -506,6 +531,13 @@ describe('persistence pre-write divergence arms', () => {const hist = await getDocumentHistory(h.shadow, { docName: h.docName }, '');const row = hist.entries.find((e) => e.sha === sha);expect(row?.checkpoint?.metadata).toEqual({ atRiskLines: 1, witnessAvailable: false });+ // The same verdict on the ring. Paired with the arm above, these two+ // tests are what make the field discriminating rather than decorative.+ const writes = (await h.readRing()).filter(+ (e) => e.event === 'checkpoint-write' && e.site === 'persistence-prewrite',+ );+ expect(writes.length).toBeGreaterThan(0);+ expect(writes.every((e) => e.witnessAvailable === false)).toBe(true);} finally {await h.cleanup();}@@ -536,6 +568,13 @@ describe('persistence pre-write divergence arms', () => {// a branch where the tolerance is unknowable.expect(h.wired.serializeFragment()).not.toContain(WIRED_PENDING_LINE);expect(h.diskBytes()).toBe(h.wired.ytextString());+ // This arm mints nothing and increments no reconcile counter, so before+ // the per-rebuild breadcrumb a rebuild here reached no durable artifact at+ // all — the one arm where the fragment is destroyed with the least+ // evidence. It is now represented like every other rebuild.+ const rebuilds = (await h.readRing()).filter((e) => e.event === 'repair-rebuild');+ expect(rebuilds).toHaveLength(1);+ expect(rebuilds[0]?.site).toBe('persistence-prewrite');} finally {await h.cleanup();}diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.tsindex f9a5f7131..75d3a5643 100644--- a/packages/server/src/persistence.ts+++ b/packages/server/src/persistence.ts@@ -79,6 +79,7 @@ import {LOSS_EVENT_CHECKPOINT_WRITE,LOSS_EVENT_DETECTOR_TRIP,LOSS_EVENT_PERSISTENCE_HOLD,+ LOSS_EVENT_REPAIR_REBUILD,type LossCaptureRing,} from './loss-capture.ts';import {@@ -507,6 +508,27 @@ export function normalizedSourceForm(rawYText: string): string {const { frontmatter, body } = stripFrontmatter(rawYText);return normalizeBridge(prependFrontmatter(frontmatter, body));}+/**+ * Attached client count for a document, or 0 when the runtime does not expose+ * one. Hocuspocus hands its hooks a `Document` that carries the count, but the+ * bridge and persistence internals thread it as a bare `Y.Doc` — and the unit+ * rigs pass a genuine `Y.Doc` that has no such method — so the probe is+ * structural rather than a signature widening that would break those callers.+ * Absence reports as 0 (indistinguishable from "nobody attached"), which keeps+ * the field an attached-clients LOWER bound and never an overstatement.+ */+function connectionCount(document: Y.Doc): number {+ const probe = (document as Y.Doc & { getConnectionsCount?: () => number }).getConnectionsCount;+ if (typeof probe !== 'function') return 0;+ try {+ const n = probe.call(document);+ return typeof n === 'number' && Number.isFinite(n) ? n : 0;+ } catch {+ /* diagnostic-only: a throwing probe must never break a repair path */+ return 0;+ }+}+/*** Extract a {@link StoreFailure} from a thrown value without touching it in a* way that can itself throw. Disk-write rejections are normally@@ -1123,6 +1145,23 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis}function reconcileFragmentNow(document: Y.Doc, body: string, documentName: string): void {+ // Breadcrumb the rebuild ITSELF, not just the anchor mint that sometimes+ // precedes it. The mint is deduped per document against its last payload and+ // is skipped outright when serialization produced no fragment view, so on a+ // document that diverges at this boundary on every write-back the rebuild+ // recurs indefinitely while the ring shows at most one record. That is the+ // difference between "a repair ran once" and "this document is stuck in a+ // permanent repair loop", and only the latter explains a fragment that keeps+ // changing under a user. Recorded before the work so a throw inside the+ // rebuild cannot swallow the evidence that it was attempted.+ void options?.getLossRing?.()?.record({+ event: LOSS_EVENT_REPAIR_REBUILD,+ docName: documentName,+ writerId: null,+ direction: 'b',+ site: PERSISTENCE_PREWRITE_SITE,+ connections: connectionCount(document),+ });try {const xmlFragment = document.getXmlFragment('default');const parseOpts = options?.resolveEmbed@@ -1235,6 +1274,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persisdirection: 'b',site: PERSISTENCE_PREWRITE_SITE,lostLen,+ witnessAvailable,});return;}@@ -1257,6 +1297,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persisdirection: 'b',site: PERSISTENCE_PREWRITE_SITE,lostLen,+ witnessAvailable,checkpointSha: sha,});console.warn(@@ -1279,6 +1320,20 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis{ documentName, err: e },'[persistence] reconcile-loss checkpoint write failed',);+ // The anchor failed but the rebuild still went ahead — emit the+ // sha-less breadcrumb (mirroring the no-shadow branch) so the trip is+ // never absent from the ring. Without it a shadow-repo outage reads as+ // "this boundary never fired" at exactly the moment the destroyed+ // fragment view has no restore anchor.+ void ring?.record({+ event: LOSS_EVENT_CHECKPOINT_WRITE,+ docName: documentName,+ writerId: null,+ direction: 'b',+ site: PERSISTENCE_PREWRITE_SITE,+ lostLen,+ witnessAvailable,+ });});});}diff --git a/packages/server/src/server-observers.ts b/packages/server/src/server-observers.tsindex a5eff19ef..6bd60bca2 100644--- a/packages/server/src/server-observers.ts+++ b/packages/server/src/server-observers.ts@@ -279,6 +279,15 @@ const MAX_DERIVE_TIMING_DEFERS = 8;*/const MAX_REDERIVE_ROUNDS = 8;+/**+ * Ring `site` for the Observer A Path B merge post-condition. Named apart from+ * the apply-arm detector (`observer-a-apply`) because the two fail for opposite+ * reasons at different boundaries: the apply arm drops content while writing+ * bytes it already holds, whereas this one is the three-way merge itself+ * failing to preserve both sides' edits.+ */+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) {@@ -818,8 +827,33 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => voidif (err.info.which === 'growth') incrementBridgeMergeContentGrowth();else incrementBridgeMergeContentLoss();+ // The verdict has to reach a DURABLE artifact, not just a counter and a+ // console line. Counters are process-scoped and a bundle carries them only+ // as totals, so after the fact nobody can tell which document produced them+ // or whether the boundary tripped once or forty times — and `growth` is the+ // signature of duplicated content, which is what this failure looks like to+ // a user. The ring is the only per-occurrence, per-document sink that+ // survives into a bug report.+ const which = err.info.which;+ // On the over-multiplication arm `lostSubstrings` holds the DOUBLED line+ // rather than a missing one, so this length is "bytes implicated in the+ // verdict", not "bytes lost" — the ring's `lostLen` carries the same+ // at-risk framing at its sibling sites.+ const lostLen = err.info.lostSubstrings.reduce((n, s) => n + s.length, 0);+const shadow = opts.shadow?.();- if (!shadow || !opts.docName) return;+ 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(() => {@@ -833,6 +867,16 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void}).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',@@ -851,6 +895,19 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void{ err, 'doc.name': opts.docName ?? null, branch, kind: 'bridge-merge-loss' },'checkpoint write failed',);+ // The anchor failed but the boundary still tripped and the merge was+ // still applied as-computed — emit the sha-less event (mirroring the+ // no-shadow branch) so the trip is never absent from the ring. Without+ // it a checkpoint-write outage reads as "the boundary never fired".+ void opts.lossRing?.record({+ event: LOSS_EVENT_DETECTOR_TRIP,+ docName: opts.docName as string,+ writerId: null,+ direction: 'a',+ site: MERGE_BOUNDARY_SITE,+ lostLen,+ which,+ });});});};