Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
/**
* Lives in its own module because precedent #13(b) bans wall-clock SCHEDULING (`setTimeout`,
* `setInterval`) in `server-observers.ts` — see `bridge-no-wallclock.test.ts` for the enforced
* gate's `FORBIDDEN` regex array.
*/
import type { MarkdownManager } from '@inkeep/open-knowledge-core';
import {
type BridgeInvariantSite,
type BridgeInvariantViolation,
BridgeInvariantViolationError,
type BridgeToleranceSignal,
detectAppliedToleranceClasses,
emitToleranceFire,
isParseEquivalentBridge,
locateBridgeDivergence,
normalizeBridge,
PARSE_EQUIVALENCE_TOLERANCE,
toBridgeInvariantLog,
} from '@inkeep/open-knowledge-core';
import { getLogger } from './logger.ts';
import {
incrementBridgeInvariantViolations,
incrementBridgeInvariantViolationsSuppressed,
incrementBridgeSplitBrainRederivesSuppressed,
incrementBridgeToleranceApplied,
incrementObserverAPathBFiresSuppressed,
} from './metrics.ts';
const log = getLogger('bridge-watchdog');
const DEFAULT_DEBOUNCE_S = 60;
const lastEmitMs = new Map<string, number>();
const MAX_VIOLATION_RATE_TUPLES = 1024;
const lastToleranceEmitMs = new Map<string, number>();
const lastPathBEmitMs = new Map<string, number>();
export type BridgeSplitBrainSite =
| 'identity-gate'
| 'post-merge'
| 'error-recovery'
| 'duplication-guard';
const lastSplitBrainEmitMs = new Map<string, number>();
function toleranceRateKey(site: BridgeInvariantSite, cls: BridgeToleranceSignal): string {
return `${site}::${cls}`;
}
function readDebounceMs(): number {
const raw = process.env.OK_BRIDGE_VIOLATION_DEBOUNCE_S;
if (raw === undefined) return DEFAULT_DEBOUNCE_S * 1000;
const parsed = Number.parseInt(raw, 10);
if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_DEBOUNCE_S * 1000;
return parsed * 1000;
}
function rateKey(site: BridgeInvariantSite, docName: string | undefined): string {
return `${site}::${docName ?? '__nodoc__'}`;
}
export function shouldEmitBridgeInvariantViolation(
site: BridgeInvariantSite,
docName: string | undefined,
nowMs: number = Date.now(),
): boolean {
const key = rateKey(site, docName);
const last = lastEmitMs.get(key);
const debounceMs = readDebounceMs();
if (last !== undefined && nowMs - last < debounceMs) return false;
if (lastEmitMs.size >= MAX_VIOLATION_RATE_TUPLES) {
for (const [k, lastMs] of lastEmitMs) {
if (nowMs - lastMs >= debounceMs) lastEmitMs.delete(k);
}
}
lastEmitMs.set(key, nowMs);
return true;
}
export function shouldEmitBridgeToleranceApplied(
site: BridgeInvariantSite,
toleranceClass: BridgeToleranceSignal,
nowMs: number = Date.now(),
): boolean {
const key = toleranceRateKey(site, toleranceClass);
const last = lastToleranceEmitMs.get(key);
const debounceMs = readDebounceMs();
if (last !== undefined && nowMs - last < debounceMs) return false;
lastToleranceEmitMs.set(key, nowMs);
return true;
}
export function shouldEmitObserverAPathBFired(
docName: string | undefined,
nowMs: number = Date.now(),
): boolean {
const key = docName ?? '__nodoc__';
const last = lastPathBEmitMs.get(key);
const debounceMs = readDebounceMs();
if (last !== undefined && nowMs - last < debounceMs) return false;
if (lastPathBEmitMs.size >= MAX_VIOLATION_RATE_TUPLES) {
for (const [k, lastMs] of lastPathBEmitMs) {
if (nowMs - lastMs >= debounceMs) lastPathBEmitMs.delete(k);
}
}
lastPathBEmitMs.set(key, nowMs);
return true;
}
export function emitObserverAPathBFired(docName: string | undefined, nowMs?: number): boolean {
const shouldEmit = shouldEmitObserverAPathBFired(docName, nowMs);
if (!shouldEmit) {
incrementObserverAPathBFiresSuppressed();
} else {
log.debug(
{ docName },
'[bridge-watchdog] Observer A Path B fired (slow-path Y.Text divergence merge)',
);
}
return shouldEmit;
}
export function shouldEmitBridgeSplitBrainRederive(
site: BridgeSplitBrainSite,
docName: string | undefined,
nowMs: number = Date.now(),
): boolean {
const key = `${site}::${docName ?? '__nodoc__'}`;
const last = lastSplitBrainEmitMs.get(key);
const debounceMs = readDebounceMs();
if (last !== undefined && nowMs - last < debounceMs) return false;
if (lastSplitBrainEmitMs.size >= MAX_VIOLATION_RATE_TUPLES) {
for (const [k, lastMs] of lastSplitBrainEmitMs) {
if (nowMs - lastMs >= debounceMs) lastSplitBrainEmitMs.delete(k);
}
}
lastSplitBrainEmitMs.set(key, nowMs);
return true;
}
export function emitBridgeSplitBrainRederive(
site: BridgeSplitBrainSite,
docName: string | undefined,
nowMs?: number,
): boolean {
const shouldEmit = shouldEmitBridgeSplitBrainRederive(site, docName, nowMs);
if (!shouldEmit) {
incrementBridgeSplitBrainRederivesSuppressed();
} else {
log.debug({ site, docName }, '[bridge-watchdog] split-brain re-derive detected');
}
return shouldEmit;
}
export function __resetBridgeWatchdogForTests(): void {
lastEmitMs.clear();
lastToleranceEmitMs.clear();
lastPathBEmitMs.clear();
lastSplitBrainEmitMs.clear();
}
export function __getViolationRateTupleCountForTests(): number {
return lastEmitMs.size;
}
export function __getSplitBrainRateTupleCountForTests(): number {
return lastSplitBrainEmitMs.size;
}
export function shouldThrowOnBridgeInvariantViolation(
env: NodeJS.ProcessEnv = process.env,
): boolean {
return env.NODE_ENV === 'test' || env.OK_BRIDGE_THROW_ON_VIOLATION === '1';
}
type DocParseSurface = Pick<
NonNullable<Parameters<MarkdownManager['parseWithFallback']>[1]>,
'resolveEmbed' | 'resolveSize'
> & { docName?: string };
export function createDocCanonicalizer(
mdManager: MarkdownManager,
opts: DocParseSurface,
): (body: string) => string {
const parseOpts =
opts.resolveEmbed && opts.docName
? {
resolveEmbed: opts.resolveEmbed,
resolveSize: opts.resolveSize,
sourcePath: opts.docName,
}
: undefined;
return (body: string): string =>
mdManager.serialize(mdManager.parseWithFallback(body, parseOpts));
}
interface AssertBridgeInvariantOpts {
site: BridgeInvariantSite;
docName?: string;
origin?: unknown;
nowMs?: number;
suppressDevThrow?: boolean;
/**
* Parse-equivalence fallback: when inputs diverge beyond every `normalizeBridge` byte class,
* canonicalize the ytext body through the caller's own parse-serialize pipeline and accept a
* match, since the fragment then IS `parse(ytext)` (precedent #38). Bind the doc's own options.
*/
canonicalizeBody?: (body: string) => string;
}
export function assertBridgeInvariant(
ytextSnapshot: string,
fragmentMdSnapshot: string,
opts: AssertBridgeInvariantOpts,
): boolean {
const reportTolerated = (classes: readonly BridgeToleranceSignal[]): void => {
const emittedClasses = classes.filter((cls) =>
shouldEmitBridgeToleranceApplied(opts.site, cls, opts.nowMs),
);
if (classes.length > 0) {
emitToleranceFire(classes, ytextSnapshot, fragmentMdSnapshot, opts.docName);
}
if (emittedClasses.length > 0) {
log.debug(
{ site: opts.site, docName: opts.docName, classes: emittedClasses },
'[bridge-watchdog] tolerance classes applied',
);
}
for (const cls of emittedClasses) {
incrementBridgeToleranceApplied(cls);
console.warn(
JSON.stringify({
event: 'bridge-tolerance-applied',
site: opts.site,
class: cls,
}),
);
}
};
const ytextNorm = normalizeBridge(ytextSnapshot);
const fragNorm = normalizeBridge(fragmentMdSnapshot);
if (ytextNorm === fragNorm) {
if (ytextSnapshot !== fragmentMdSnapshot) {
reportTolerated(detectAppliedToleranceClasses(ytextSnapshot, fragmentMdSnapshot));
}
return true;
}
if (
opts.canonicalizeBody &&
isParseEquivalentBridge(ytextSnapshot, fragmentMdSnapshot, opts.canonicalizeBody)
) {
reportTolerated([
...detectAppliedToleranceClasses(ytextSnapshot, fragmentMdSnapshot),
PARSE_EQUIVALENCE_TOLERANCE,
]);
return true;
}
const violation: BridgeInvariantViolation = {
site: opts.site,
origin: opts.origin,
docName: opts.docName,
ytextSnapshot,
fragmentMdSnapshot,
unifiedDiff: ` ytext: ${ytextNorm.slice(0, 300)}\n frag: ${fragNorm.slice(0, 300)}`,
stack: new Error().stack,
};
if (shouldThrowOnBridgeInvariantViolation() && !opts.suppressDevThrow) {
throw new BridgeInvariantViolationError(violation);
}
const shouldEmit = shouldEmitBridgeInvariantViolation(opts.site, opts.docName, opts.nowMs);
if (!shouldEmit) {
incrementBridgeInvariantViolationsSuppressed();
return false;
}
incrementBridgeInvariantViolations();
const divergence = locateBridgeDivergence(ytextNorm, fragNorm);
log.warn(
{
site: opts.site,
docName: opts.docName,
ytextBytes: ytextSnapshot.length,
fragmentBytes: fragmentMdSnapshot.length,
normalizedYtextBytes: ytextNorm.length,
normalizedFragmentBytes: fragNorm.length,
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}'` : ''
}`,
);
const verbose = process.env.OK_TELEMETRY_VERBOSE === '1';
console.warn(JSON.stringify(toBridgeInvariantLog(violation, { verbose })));
return false;
}