[fm-var] Add preview and explicit-write synchronization

[DandyLyons]

Problem / outcome

Add synchronization that previews exact RFC 001 Rev 3 cache-only edits and writes only under explicit authorization, preserving unrelated bytes and guarding against concurrent changes.

Epic: #111. Milestone: 4 — CLI workflows.

In scope

• Synchronize selected files/content trees using the shared projection/query/evaluation pipeline and host limits.
• Provide non-writing preview/dry-run output with exact changes and structured results.
• Require explicit write/apply mode.
• Apply successful cache edits to each immutable source snapshot in reverse byte-range order.
• Preserve failed elements unchanged while defining/reporting partial-file behavior.
• Revision-check and atomically replace each changed file; skip unchanged files.

Relevant specification sections

• §3.1 YAML authority.
• §3.6–3.7 result/cardinality/fallback and per-element atomicity.
• §3.9 secure serialization.
• §7 whitespace preservation.

Dependencies and blockers

• Blocked by [fm-var] Add non-mutating validation and stable diagnostics #116 and transitively by Milestones 1–3.
• Partial-file behavior must be explicit while preserving per-element atomicity.

Implementation considerations

• Never call full MarkdownDocument.render(); use exact UTF-8 cache ranges.
• Generalize/reuse revision comparison and atomic replacement behavior.
• Detect overlapping/invalid edits and apply highest-to-lowest offsets.
• Separate preview, edit planning, and commit for testing/future consumers.
• Referenced src documents remain read-only and are never synchronized transitively.

Acceptance Criteria

• No explicit write authorization means no file changes.
• Preview reports exact changes, unchanged references, zero/null fallbacks, nodelist/cardinality/query failures, and other failures in human/structured forms.
• Write mode changes only caches of successfully evaluated references.
• Unrelated UTF-8 bytes, frontmatter, attributes/order/quotes, whitespace, and LF/CRLF remain byte-identical.
• Failed references retain complete prior caches; valid references follow documented partial-file policy.
• Revision mismatch aborts the file; replacement is atomic; unchanged files are not rewritten.

Test requirements

• Golden fixtures for inline/block/multiple edits, reverse application, CRLF, Unicode, no-op, partial failure, both fallback classes, query/cardinality failure, injection, revision mismatch, and directory scans.
• Process tests for preview/write flags and exit status; filesystem assertions for atomic/no-write behavior.

Documentation / CLI-help impact

• Preview/write safety contract, Rev 3 fallback/query examples, partial-failure semantics, backup/version-control advice, and automation usage.

Explicitly deferred

• Updating authoritative YAML, transitive synchronization, watching files, editor UI, daemons, and general-purpose templating.