fix: preserve frontmatter datetimes verbatim via string-preserving YAML engine

[aliasunder]

Problem

vault_update_properties, vault_patch_note, and vault_replace_in_note rewrite a note's frontmatter on every edit and convert offset-form ISO 8601 datetimes to UTC-Z:

created: 2026-05-13T20:00:00-04:00   # before any edit
created: 2026-05-14T00:00:00.000Z    # after a body patch or unrelated property update

Same instant, wrong representation — and created should never change after stamping. vault_write_note (merge path), vault_update_memory, and vault_delete_memory had the same latent bug.

Root cause

gray-matter's default engine is js-yaml with the YAML 1.1 schema, which parses timestamp-shaped scalars into JS Date objects; matter.stringify then re-serializes them via toISOString(). No upstream fix exists — gray-matter 4.0.3 is the latest release, and its documented solution is the built-in engines option.

Fix

Swap the YAML engine to the yaml package (eemeli, already in the dependency tree as a transitive dep). The YAML 1.2 core schema has no timestamp type: datetimes parse as plain strings and dump back unquoted, so untouched frontmatter values round-trip byte-identically.

All gray-matter calls in vault-filesystem, vault-patcher, and memory-store are routed through new parseNote() / stringifyNote() wrappers in frontmatter.ts, which close over the engine options — a future call site can't accidentally fall back to the default engine and reintroduce the bug.

js-yaml itself can't be the replacement engine — even with a string-preserving schema, its dumper single-quotes colon-containing scalars (created: '2026-…-04:00').

search-index.ts keeps the default engine and a direct gray-matter import: it's read-only (never writes files back) and already converts parsed Dates to ISO strings for DB storage.

Behavioral notes

• New memory files now stamp created: unquoted (js-yaml single-quoted it because of the colons).
• vault_read_note with properties_only now returns datetime properties as their original strings instead of UTC-Z-serialized Dates.
• YAML 1.1 → 1.2 scalar semantics: yes/no/on/off now parse as strings, not booleans — more faithful to the file bytes.
• Flow arrays (tags: [a, b]) still re-dump in block style when frontmatter is re-serialized — js-yaml did the same, no regression.

Testing

• New byte-identity tests: writeNote body-only, updateProperties of an unrelated key, patchNote append, replaceInNote, memory update/delete round-trips — all assert the exact created: …-04:00 byte sequence survives.
• readNoteProperties returns datetimes as original strings.
• New memory-file created: stamp asserted unquoted and offset-form (never Z-suffixed).
• Mutation audit: reverting the wrappers to the default js-yaml engine fails exactly the 8 new/strengthened tests and nothing else — every assertion requires the fixed behavior.
• ✓ 504/504 tests pass, lint clean, tsc clean.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request consolidates gray-matter YAML parsing and serialization across vault operations by introducing shared MATTER_OPTIONS configuration that replaces the default js-yaml engine with the yaml package, ensuring datetime frontmatter fields with local offsets survive parse-stringify cycles byte-identically.

Changes

YAML Configuration Consolidation

Layer / File(s)	Summary
MATTER_OPTIONS foundation and dependency package.json, src/vault-mcp/vault-operations/matter-options.ts	Adds the yaml package (2.8.4) and exports MATTER_OPTIONS, which configures gray-matter to use the yaml package for YAML parsing and stringification, with parse fallback to {} for empty input and folding disabled (lineWidth: 0).
Memory store gray-matter consolidation src/vault-mcp/vault-operations/memory-store.ts, src/vault-mcp/vault-operations/__tests__/memory-store.test.ts	Memory-store.ts applies MATTER_OPTIONS to all gray-matter parse and stringify calls in getMemory, buildNewMemoryFile, updateMemory, listMemoryFiles, and deleteMemory. Tests verify local-offset datetime created fields survive round-trip serialization byte-identically in auto-created files, deletion workflows, and appends.
Vault filesystem gray-matter consolidation src/vault-mcp/vault-operations/vault-filesystem.ts, src/vault-mcp/vault-operations/__tests__/vault-filesystem.test.ts	Vault-filesystem.ts applies MATTER_OPTIONS in serializeNote, readNoteProperties, and updateProperties. Tests verify datetime frontmatter fields remain as strings rather than Date objects and that local-offset timestamps survive when updating content or metadata separately.
Vault patcher gray-matter consolidation src/vault-mcp/vault-operations/vault-patcher.ts, src/vault-mcp/vault-operations/__tests__/vault-patcher.test.ts	Vault-patcher.ts applies MATTER_OPTIONS in readNoteForPatch and writePatchedNote. Tests verify frontmatter with local-offset datetimes remain byte-identical when patching/appending to sections and when replacing note body text.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A yaml engine swap with grace,
Gray-matter finds its rightful place,
Timezones rest without a fret,
Round-trip bytes—no format debt!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main objective: replacing the YAML engine to preserve datetime frontmatter as unquoted strings rather than converting them to Date objects.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/frontmatter-datetime-utc-z

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}