Frontmatter as a Y.Map #49

New issue

Closed

opened 2026-09-21 18:03:45 +01:00 by cruelacid · 1 comment

cruelacid commented

2026-09-21 18:03:45 +01:00

Owner

Part of #37.

What Relay does

Frontmatter synced as a Yjs Map with visual-property-editor support since 0.7.0.
Worth knowing they hit real trouble here: their issues #116 (a frontmatter append
loop, a Y.Text↔Y.Map deadlock) and open PR #127 (gating frontmatter Map
writes on provider sync) are both in this exact area.

What we do today

Frontmatter is part of the markdown Y.Text, so concurrent property edits merge
character-wise. Usually fine; occasionally produces YAML that is syntactically
wrong in the way blob-policy.ts already warns about for JSON.

What changes

A second root on the file's document holding frontmatter as a Y.Map, with
the body staying in Y.Text. This is where Relay's deadlock came from, so the
ordering between the two roots needs to be designed rather than discovered —
CLAUDE.md names async ordering as a recurring hazard here, with at least four
bugs already attributed to it.

Risk

risk:additive. A new root on an existing document; older clients replicate it
without acting on it, exactly as with Y.Map('blobs') from Phase 8. Gate with
MIN_PLUGIN_VERSION if the transition proves awkward.

Verification

Concurrent property edits from two vaults; the file always parses. Invert the
ordering rule and confirm the test fails.

Part of #37. ## What Relay does Frontmatter synced as a Yjs Map with visual-property-editor support since 0.7.0. Worth knowing they hit real trouble here: their issues #116 (a frontmatter append loop, a `Y.Text`↔`Y.Map` deadlock) and open PR #127 (gating frontmatter Map writes on provider sync) are both in this exact area. ## What we do today Frontmatter is part of the markdown `Y.Text`, so concurrent property edits merge character-wise. Usually fine; occasionally produces YAML that is syntactically wrong in the way `blob-policy.ts` already warns about for JSON. ## What changes A second root on the **file's** document holding frontmatter as a `Y.Map`, with the body staying in `Y.Text`. This is where Relay's deadlock came from, so the ordering between the two roots needs to be designed rather than discovered — `CLAUDE.md` names async ordering as a recurring hazard here, with at least four bugs already attributed to it. ## Risk `risk:additive`. A new root on an existing document; older clients replicate it without acting on it, exactly as with `Y.Map('blobs')` from Phase 8. Gate with `MIN_PLUGIN_VERSION` if the transition proves awkward. ## Verification Concurrent property edits from two vaults; the file always parses. Invert the ordering rule and confirm the test fails.

cruelacid added this to the Phase 17 - Structured documents milestone

2026-09-21 18:03:45 +01:00

cruelacid added the

labels

2026-09-21 18:03:45 +01:00

cruelacid referenced this issue

2026-09-21 18:08:51 +01:00

Relay feature parity, with end-to-end encryption (tracking) #37