Address frontmatter guard review

Author: kavinsood

engineering/frontmatter-integrity-rfc.md

@@ -13,11 +13,18 @@ It is intentionally grounded in the 2026-04-09 incident logs:
 
 ## Status
 
-P0 and the first P1 containment pass are implemented.
+P0 and the first P1 containment pass are implemented:
+
+- bound-file recovery now uses non-writing binding repair after disk-authority
+  recovery
+- the frontmatter guard blocks obvious duplicate/malformed/growth-burst states
+  in both disk-to-CRDT and CRDT-to-disk directions
+- blocked transitions are traced, surfaced with a throttled user notice, and can
+  be opted out from Advanced settings for troubleshooting
 
 Still proposed:
 
-- persisted quarantine state and user-facing recovery UI
+- persisted quarantine state and full recovery UI
 - structure-aware frontmatter sidecar
 - canonical YAML rendering
 
@@ -271,9 +278,15 @@ The extractor should return:
 This does not require parsing YAML yet. It is a cheap structural boundary for
 guards and diagnostics.
 
-### 5. Add YAML parse validation
+### 5. Add frontmatter validation
+
+The first containment pass uses a cheap structural classifier. It blocks only
+obvious hazards such as duplicate top-level keys, repeated bare-key bursts,
+malformed frontmatter fences, and isolated frontmatter growth bursts.
 
-Use a real YAML parser rather than ad hoc string manipulation.
+That first pass is an emergency brake, not a complete YAML policy. The durable
+implementation should use a real YAML parser rather than ad hoc string
+manipulation.
 
 The validator should detect:
 
@@ -305,7 +318,7 @@ For `block`, YAOS should:
 
 - leave body sync available when the body can be separated safely
 - record a diagnostic
-- optionally notify the user with short copy
+- notify the user with short copy
 
 ### 7. Gate outbound CRDT-to-disk frontmatter writes
 
@@ -339,7 +352,9 @@ The quarantine should be clearable when:
 - the user chooses the local disk state
 - the user disables the guard for the path
 
-The first implementation can be trace-only plus skip behavior. UI can follow.
+The first implementation is skip behavior plus trace/log diagnostics, a
+throttled notice, and a global opt-out. Persisted per-file quarantine state and
+explicit accept/keep recovery controls should follow.
 
 ## P2: Structure-aware frontmatter sync
 

src/main.ts

@@ -87,6 +87,7 @@ const FAST_RECONNECT_MIN_INTERVAL_MS = 2_000;
 const MARKDOWN_DIRTY_SETTLE_MS = 350;
 const OPEN_FILE_EXTERNAL_EDIT_IDLE_GRACE_MS = 1200;
 const BOUND_RECOVERY_LOCK_MS = 1500;
+const FRONTMATTER_GUARD_NOTICE_MS = 30_000;
 const CAPABILITY_REFRESH_INTERVAL_MS = 30_000;
 const UPDATE_MANIFEST_URLS = [
 	"https://github.com/kavinsood/yaos/releases/latest/download/update-manifest.json",
@@ -284,6 +285,7 @@ export default class VaultCrdtSyncPlugin extends Plugin {
 	private legacyServerNoticeShown = false;
 	private commandsRegistered = false;
 	private idbDegradedHandled = false;
+	private frontmatterGuardNoticeAt = new Map<string, number>();
 
 	/**
 	 * True when startup timed out waiting for provider sync.
@@ -446,6 +448,8 @@ export default class VaultCrdtSyncPlugin extends Plugin {
 				this.editorBindings,
 				this.settings.debug,
 				(source, msg, details) => this.trace(source, msg, details),
+				() => this.settings.frontmatterGuardEnabled,
+				(path, direction) => this.showFrontmatterGuardNotice(path, direction),
 			);
 			this.diskMirror.startMapObservers();
 
@@ -2160,6 +2164,8 @@ export default class VaultCrdtSyncPlugin extends Plugin {
 		nextContent: string,
 		reason: string,
 	): boolean {
+		if (!this.settings.frontmatterGuardEnabled) return false;
+
 		const validation = validateFrontmatterTransition(previousContent, nextContent);
 		if (!isFrontmatterBlocked(validation)) return false;
 
@@ -2175,9 +2181,27 @@ export default class VaultCrdtSyncPlugin extends Plugin {
 			`Frontmatter ingest blocked for "${path}" ` +
 			`(${validation.reasons.join(", ") || validation.risk})`,
 		);
+		this.showFrontmatterGuardNotice(path, "disk-to-crdt");
 		return true;
 	}
 
+	private showFrontmatterGuardNotice(
+		path: string,
+		direction: "disk-to-crdt" | "crdt-to-disk",
+	): void {
+		const key = `${direction}:${path}`;
+		const now = Date.now();
+		if ((this.frontmatterGuardNoticeAt.get(key) ?? 0) + FRONTMATTER_GUARD_NOTICE_MS > now) {
+			return;
+		}
+
+		this.frontmatterGuardNoticeAt.set(key, now);
+		new Notice(
+			`YAOS paused a properties update in "${path}" because the frontmatter looked unsafe. Check diagnostics before accepting the change.`,
+			12_000,
+		);
+	}
+
 	private traceFrontmatterQuarantine(
 		path: string,
 		direction: "disk-to-crdt" | "crdt-to-disk",

src/settings.ts

@@ -17,6 +17,8 @@ export interface VaultSyncSettings {
 	deviceName: string;
 	/** Enable verbose console.log output for debugging. */
 	debug: boolean;
+	/** Pause propagation of suspicious YAML frontmatter transitions. */
+	frontmatterGuardEnabled: boolean;
 	/** Comma-separated path prefixes to exclude from sync. */
 	excludePatterns: string;
 	/** Maximum file size in KB to sync via CRDT. Files larger are skipped. */
@@ -50,6 +52,7 @@ export const DEFAULT_SETTINGS: VaultSyncSettings = {
 	vaultId: "",
 	deviceName: "",
 	debug: false,
+	frontmatterGuardEnabled: true,
 	excludePatterns: "",
 	maxFileSizeKB: 2048,
 	externalEditPolicy: "always",
@@ -691,6 +694,18 @@ export class VaultSyncSettingTab extends PluginSettingTab {
 					}),
 			);
 
+		new Setting(advancedBody)
+			.setName("Frontmatter safety guard")
+			.setDesc("Pause suspicious YAML property updates before they spread. Disable only while troubleshooting valid frontmatter that is being blocked.")
+			.addToggle((toggle) =>
+				toggle
+					.setValue(this.plugin.settings.frontmatterGuardEnabled)
+					.onChange(async (value) => {
+						this.plugin.settings.frontmatterGuardEnabled = value;
+						await this.plugin.saveSettings();
+					}),
+			);
+
 		new Setting(advancedBody)
 			.setName("Debug logging")
 			.setDesc("Enable verbose console logs for troubleshooting.")

src/sync/diskMirror.ts

@@ -9,6 +9,7 @@ import { formatUnknown, yTextToString } from "../utils/format";
 import {
 	isFrontmatterBlocked,
 	validateFrontmatterTransition,
+	type FrontmatterValidationResult,
 } from "./frontmatterGuard";
 
 /**
@@ -102,6 +103,12 @@ export class DiskMirror {
 		private editorBindings: EditorBindingManager,
 		debug: boolean,
 		private trace?: TraceRecord,
+		private frontmatterGuardEnabled: () => boolean = () => true,
+		private onFrontmatterBlocked?: (
+			path: string,
+			direction: "crdt-to-disk",
+			validation: FrontmatterValidationResult,
+		) => void,
 	) {
 		this.debug = debug;
 	}
@@ -479,6 +486,8 @@ export class DiskMirror {
 		previousContent: string | null,
 		nextContent: string,
 	): boolean {
+		if (!this.frontmatterGuardEnabled()) return false;
+
 		const validation = validateFrontmatterTransition(previousContent, nextContent);
 		if (!isFrontmatterBlocked(validation)) return false;
 
@@ -497,6 +506,7 @@ export class DiskMirror {
 			`frontmatter write blocked for "${path}" ` +
 			`(${validation.reasons.join(", ") || validation.risk})`,
 		);
+		this.onFrontmatterBlocked?.(path, "crdt-to-disk", validation);
 		return true;
 	}
 

tests/bound-recovery-regressions.mjs

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import * as Y from "yjs";
 
 const diffModule = await import("../src/sync/diff.ts");
@@ -70,17 +69,40 @@ console.log("\n--- Test 1: bound-file recovery applies one content authority ---
 	oldAmplifier.doc.destroy();
 }
 
-console.log("\n--- Test 2: local-only recovery branch uses non-writing repair ---");
+console.log("\n--- Test 2: repeated disk-authority recovery does not amplify stale editor state ---");
 {
-	const mainSource = readFileSync(new URL("../src/main.ts", import.meta.url), "utf8");
-	const localOnlyStart = mainSource.indexOf("const localOnlyViews = viewStates.filter");
-	const crdtOnlyStart = mainSource.indexOf("const crdtOnlyViews = viewStates.filter");
-	const branch = mainSource.slice(localOnlyStart, crdtOnlyStart);
+	const crdt = [
+		"---",
+		"timeEstimate: 2",
+		"kind: op",
+		"---",
+		"",
+	].join("\n");
+	const disk = [
+		"---",
+		"timeEstimate: 20",
+		"kind: op",
+		"---",
+		"",
+	].join("\n");
+	const staleEditor = [
+		"---",
+		"timeEstimate: 200",
+		"kind: op",
+		"---",
+		"",
+	].join("\n");
+
+	const state = makeText(crdt);
+	for (let i = 0; i < 5; i++) {
+		const before = state.ytext.toString();
+		applyDiffToYText(state.ytext, before, disk, "disk-sync-recover-bound");
+	}
 
-	assert(localOnlyStart > -1 && crdtOnlyStart > localOnlyStart, "local-only recovery branch found");
-	assert(branch.includes("editorBindings?.repair("), "local-only recovery repairs binding without content heal");
-	assert(!branch.includes("editorBindings?.heal("), "local-only recovery does not call content-writing heal");
-	assert(branch.includes('"disk-sync-recover-bound"'), "local-only recovery still applies disk-selected CRDT diff");
+	assert(state.ytext.toString() === disk, "repeated disk-authority recovery stays at disk content");
+	assert(state.ytext.toString() !== staleEditor, "stale editor content is not reapplied during repair-only recovery");
+	assert(state.ytext.toString().length === disk.length, "repeated repair-only recovery does not grow content");
+	state.doc.destroy();
 }
 
 console.log(`\n${"-".repeat(50)}`);