Note Primitives & Vault I O

Relevant source files

• src-tauri/src/company.rs
• src-tauri/src/note.rs
• src-tauri/src/watcher.rs
• src/lib/vaultSync.ts

This page details the core logic for interacting with the Markdown-based vault. Lodestar treats the file system as its primary database, using Markdown files with YAML frontmatter to store all entities (Companies, Jobs, Checks, etc.). The primitives in src-tauri/src/note.rs provide a robust, round-trip-safe way to manipulate these files without corrupting human-edited content.

Note Architecture

Lodestar notes follow a strict structural convention: an opening --- fence, a YAML block, a closing --- fence, and a Markdown body. The system is designed to allow both automated app writes and manual user edits (e.g., in Obsidian) to coexist.

Note Data Flow & Entity Space

The following diagram illustrates how raw file content is transformed into structured Rust entities and how updates are safely persisted back to the vault.

Note Transformation Pipeline

Sources: src-tauri/src/note.rs#1-3src-tauri/src/note.rs#56-65src-tauri/src/company.rs#136-166

Frontmatter & Body Manipulation

The system avoids full-file re-serialization whenever possible to preserve user formatting, comments, and specific YAML styles.

Field-Level Round-Trips

Instead of parsing the entire YAML block and re-emitting it for every small change, Lodestar uses set_frontmatter_field to perform byte-for-byte replacement of specific keys.

• split_frontmatter: Identifies the YAML block by looking for the first \n--- after the opening fence src-tauri/src/note.rs#56-65
• set_frontmatter_field: Finds the specific key: line within the frontmatter and replaces it, or appends it before the closing fence if missing src-tauri/src/note.rs#69-84
• set_body: Replaces everything after the closing frontmatter fence while strictly preserving the YAML block src-tauri/src/note.rs#88-93

YAML Encoding Safety

To ensure that strings containing colons, quotes, or special characters do not break the YAML structure, the app provides specialized encoders:

• yaml_scalar: Uses serde_yaml to encode a single string into a safe, one-line YAML scalar src-tauri/src/note.rs#99-105
• yaml_flow_seq: Encodes a list of strings into a flow sequence (e.g., ["a", "b"]) where every item is double-quoted and escaped src-tauri/src/note.rs#110-119

Vault I/O & The Write Choke Point

To maintain synchronization between the disk and the UI, Lodestar implements a "self-write tracking" mechanism. This prevents the app from reacting to its own file writes as if they were external changes.

Self-Write Tracking

Every write operation in the backend must pass through write_note. This function acts as the single choke point for vault persistence.

1. write_note: Writes the file to disk and immediately records the canonicalized path and timestamp in a global SELF_WRITES map src-tauri/src/note.rs#25-31
2. was_self_write: When the file watcher (watcher.rs) detects a change, it calls this function. If the path exists in the map and hasn't expired (TTL of 5 seconds), the event is ignored src-tauri/src/note.rs#36-44src-tauri/src/note.rs#20

Vault I/O Interaction

Sources: src-tauri/src/note.rs#15-31src-tauri/src/watcher.rs#74-95

Note Eligibility & Slugs

The system uses a strict rule to determine if a file is an "entity note" versus a template or sidecar file.

• note_slug Rule: A file is only considered an entity note if it ends in .md and does not start with an underscore (_) src-tauri/src/note.rs#147-152
• Classification: The classify_change function in watcher.rs uses this rule to determine if a change in a directory like companies/ or jobs/ should trigger a UI reload src-tauri/src/watcher.rs#55-60

Path	Eligible?	Reason
companies/stripe.md	Yes	Valid entity note
companies/_template.md	No	Starts with underscore (Template)
companies/_jd/listing.md	No	Nested in underscored directory
jobs/notes.txt	No	Wrong extension

Sources: src-tauri/src/note.rs#147-152src-tauri/src/watcher.rs#137-144

Lenient Parsing & Sanitization

Because users can edit files manually, Lodestar implements "lenient parsing" to prevent a single malformed field from breaking the entire app.

• sanitize_typed_fields: This utility takes a YAML mapping and ensures that specific fields match their expected types (integers or lists). If a field is malformed (e.g., a string where a list is expected), it removes or clears that specific field and returns a warning instead of failing the entire parse src-tauri/src/note.rs#141-147
• parse_front_lenient: Used by entities like Company to attempt a strict parse first, falling back to a sanitized parse if the YAML is valid but the schema is violated src-tauri/src/company.rs#118-134

Sources: src-tauri/src/note.rs#141-147src-tauri/src/company.rs#118-134