T-4DO2-vault-note-crate-golden-files

State: planning/draft · Impact: high · Complexity: large

Goal

Build the note format from D-PVNF-pumice-vault-note-format as a pumice-local crate with no pumice types in its API, so the writer task and the ops call one thing and the format is proven byte for byte before any engine wiring exists.

Today

Location	Role today
apps/pumice/crates/pumice/src/vault.rs	Tera whole-file template with a yaml_str filter for title and profile, {date}-NNN.md naming, write_cas create-only with epoch-suffix fallback
docs/planning/decisions/D-PVNF-pumice-vault-note-format/examples/	the golden files this crate must reproduce
packages/rust/markdown-util/src/lib.rs	split / compose
packages/rust/yaml-splice/src/edit.rs	edit_yaml with Set / Remove; adds absent keys
packages/rust/yaml-splice/src/render.rs	canonical value emitter
packages/rust/atomic-write/src/lib.rs	write_cas
packages/rust/dir-aspect/src/lib.rs	detect_aspects, detect_obsidian_vault_id; no registry listing
solutions/determined/apps/todo-sync/src/note.ts	the managed-section upsert to port

Proposed

apps/pumice/crates/vault-note with modules frontmatter, body, layout, daily, write, exposing NoteRecord (interval incl. Tracked, optional title, optional end), NoteLayout, NoteWriteResult, NoteWriteError, write_note(record, layout, root) -> NoteWriteResult, upsert_daily_line(...), upsert_daily_entry(...) for the daily-list mode, note_path(record, layout), render_preview(...). Frontmatter is built from the property rows: pumice_id and pumice_schema always, then every enabled row (vault rows, then the profile’s, profile wins by key), each value rendered through the typed tokens: a lone token keeps its type, anything else is a string, as_text quotes. The .base text is generated from the same rows. dir-aspect gains list_obsidian_vaults(). Golden tests read the decision’s examples/ directory directly.

Approach

1. Scaffold the crate; add it to docs/LIBRARIES.md tier 0.
2. layout::note_path and the flavor resolver.
3. frontmatter::emit (canonical, omit-when-null, as_vault_str for the four interval kinds and the status and completion sets) and frontmatter::splice (edit_yaml Set/Remove plus the tags merge rule).
4. body: token template substitution, managed regions, tracker block with semantic no-op on equal instants.
5. daily: moment-format to chrono translation, seeding from .obsidian/daily-notes.json and periodic-notes data, region upsert.
6. write: create/update discipline with etag retry and the deleted-note rule.
7. Golden tests over examples/; property tests for user-edit survival.
8. dir_aspect::list_obsidian_vaults.

Areas

Area	Note
apps/pumice/crates/vault-note/	the crate
packages/rust/dir-aspect/src/lib.rs	list_obsidian_vaults
docs/LIBRARIES.md	tier-0 row; dir-aspect entry
Cargo.toml	nothing if the glob covers it; otherwise the member

Acceptance criteria

• Golden tests reproduce every file under the decision’s examples/ byte for byte.
• A note with user prose under ## Notes and a user-added property survives a splice unchanged outside the pumice keys and regions.
• A daily note with unrelated content gains only the managed region and keeps its frontmatter byte-identical.
• In daily-list mode a second write of the same session replaces its entry region only; a multi-line {{notes}} stays inside the list item.
• A row project: {{title}} with as_text on a tracked record lands as a quoted string; a row when: {{date}} {{start}} lands as a string; {{duration_secs}} alone lands as a number and {{session_tags}} alone as a list; a duplicate key is refused.
• Renaming pumice_date to day writes day on the next note and leaves an older note’s pumice_date untouched.
• With three rows enabled, the note carries exactly those three keys plus pumice_id and pumice_schema; an update removes a key whose row was turned off.
• The tracker block is not rewritten when the plugin has re-spelled equal instants.
• A tracked record whose title holds a colon, a quote or a newline emits frontmatter that edit_yaml and Obsidian both read back unchanged.
• cargo test -p vault-note -p dir-aspect green; moon run pumice:check green.

Out of scope

• Engine wiring, the writer task, and the DB columns (T-C4B1-vault-writer-task-exports-sessions).
• Any ontogen op or UI.
• The Logseq flavor (T-1IWS-vault-logseq-flavor) and the Timekeep tracker variant (T-JGEH-vault-timekeep-tracker-block).
• Publishing dir-aspect to crates.io; the in-repo path dependency is enough here.

---

← Back to Tasks