Skip to main content

menger_notes/
marks.rs

1//! NOTES-5: **marks** — what an agent leaves on a note without writing in
2//! it (the owner, 2026-11-15: *"I want to make sure that agents can listen
3//! in on notes, and underline sections, add links, and write components
4//! into the docuemtn itself."*). A mark is a range of the note's characters
5//! carrying a link, one line of state, or both; the page underlines it.
6//!
7//! **Anchored as a question is** ([`crate::threads`]): two Yjs relative
8//! positions in the note's CRDT, resolved now to character offsets of the
9//! markdown `notes.get` answers (`from`, `to`), so the mark follows its
10//! words through every hand's edit; every character deleted, it is
11//! **detached** — kept, listed last, drawn nowhere. **Nothing here writes
12//! the note's text**: the CRDT is read, never changed, and the note's
13//! revision does not move.
14//!
15//! **Stored** in the notes file, `note_marks` (a table of its own, made by
16//! the store's open on a file from before: such a file opens with no
17//! marks): a row per mark — its anchor, the words it held when made, its
18//! link and label, who and when, who changed it last — and (NOTES-5's
19//! third requirement, after NOTES-4) a component placed under its passage:
20//! `component`, `version` (the kept version's whole hash, which the ui
21//! service said holds it) and `props` (a JSON object, held to 64 KiB as a
22//! slot's are). Those three columns were made nullable by the first pass,
23//! so a file from before reads them as none: no migration rewrote a row. Said on the
24//! channel for `watch`: `mark_changed` (made or changed, the mark whole) and
25//! `mark_removed`.
26
27use crate::crdt::{b64, text_of};
28use crate::events::{Anchor, Mark};
29use crate::store::{live_doc, now_ms, Change, NotesStore, StoreError};
30use crate::threads::{anchored, placed, slice, Anchored, Hand};
31use rusqlite::{params, Connection, OptionalExtension};
32use serde_json::{Map, Value};
33use std::sync::Arc;
34
35/// The table.
36pub const TABLES: &str = "
37        CREATE TABLE IF NOT EXISTS note_marks (
38            mark        TEXT PRIMARY KEY,
39            id          TEXT NOT NULL,
40            from_rel    BLOB NOT NULL,
41            to_rel      BLOB NOT NULL,
42            quote       TEXT NOT NULL,
43            link        TEXT,
44            label       TEXT,
45            by          TEXT NOT NULL,
46            principal   TEXT NOT NULL,
47            at          INTEGER NOT NULL,
48            changed_at  INTEGER,
49            changed_by  TEXT,
50            component   TEXT,
51            version     TEXT,
52            props       TEXT
53        );
54        CREATE INDEX IF NOT EXISTS note_marks_id ON note_marks (id);
55    ";
56
57/// What a mark carries, as a call gives it: each part `None` stays as it
58/// is (a new mark: none), `Some("")` takes a link or a label off.
59#[derive(Debug, Clone, Default)]
60pub struct Remark {
61    pub link: Option<String>,
62    pub label: Option<String>,
63    /// A component placed under the passage: its name and the version's
64    /// whole hash, as the ui service said it holds it.
65    pub placed: Option<(String, String)>,
66    /// Its props whole (replacing what it held).
67    pub props: Option<Map<String, Value>>,
68}
69
70/// `props` written as the column holds them, held to [`crate::vocab::PROPS_MAX`].
71fn props_text(props: Map<String, Value>) -> Result<String, StoreError> {
72    let text = Value::Object(props).to_string();
73    match text.len() <= crate::vocab::PROPS_MAX {
74        true => Ok(text),
75        false => Err(StoreError::TooLarge(format!("the mark's props would be {} bytes written as JSON; they are held to {} (nothing was written)", text.len(), crate::vocab::PROPS_MAX))),
76    }
77}
78
79/// A stored row, before its anchor is resolved.
80struct Row {
81    mark: String,
82    id: String,
83    from_rel: Vec<u8>,
84    to_rel: Vec<u8>,
85    quote: String,
86    link: Option<String>,
87    label: Option<String>,
88    by: String,
89    principal: String,
90    at: i64,
91    changed_at: Option<i64>,
92    changed_by: Option<String>,
93    component: Option<String>,
94    version: Option<String>,
95    props: Option<String>,
96}
97
98const COLUMNS: &str = "mark, id, from_rel, to_rel, quote, link, label, by, principal, at, changed_at, changed_by, component, version, props";
99
100fn row_of(r: &rusqlite::Row<'_>) -> rusqlite::Result<Row> {
101    Ok(Row {
102        mark: r.get(0)?,
103        id: r.get(1)?,
104        from_rel: r.get(2)?,
105        to_rel: r.get(3)?,
106        quote: r.get(4)?,
107        link: r.get(5)?,
108        label: r.get(6)?,
109        by: r.get(7)?,
110        principal: r.get(8)?,
111        at: r.get(9)?,
112        changed_at: r.get(10)?,
113        changed_by: r.get(11)?,
114        component: r.get(12)?,
115        version: r.get(13)?,
116        props: r.get(14)?,
117    })
118}
119
120/// `text` as a column: none when empty.
121fn kept(text: Option<String>) -> Option<String> {
122    text.filter(|t| !t.is_empty())
123}
124
125/// `row` made a [`Mark`]: its anchor resolved in `crdt` now.
126fn dressed(crdt: &yrs::Doc, row: Row) -> Mark {
127    let text = text_of(crdt);
128    let at = placed(crdt, &text, &row.from_rel, &row.to_rel, false);
129    Mark {
130        mark: row.mark,
131        id: row.id,
132        anchor: Anchor { from: b64(&row.from_rel), to: b64(&row.to_rel) },
133        from: at.map(|(f, _)| f),
134        to: at.map(|(_, t)| t),
135        detached: at.is_none(),
136        words: at.map(|(f, t)| slice(&text, f, t).to_string()).unwrap_or_default(),
137        quote: row.quote,
138        link: row.link,
139        label: row.label,
140        by: row.by,
141        principal: row.principal,
142        at: row.at,
143        changed_at: row.changed_at,
144        changed_by: row.changed_by,
145        props: row.component.as_ref().map(|_| row.props.as_deref().and_then(|p| serde_json::from_str(p).ok()).unwrap_or_default()),
146        component: row.component,
147        version: row.version,
148    }
149}
150
151impl NotesStore {
152    /// The mark `mark` of the live note `id`, dressed.
153    fn mark_now(&self, conn: &Connection, id: &str, mark: &str) -> Result<Mark, StoreError> {
154        let row = conn
155            .query_row(&format!("SELECT {COLUMNS} FROM note_marks WHERE mark = ?1 AND id = ?2"), params![mark, id], row_of)
156            .optional()?
157            .ok_or_else(|| StoreError::NoMark(mark.to_string()))?;
158        let crdt = self.crdt(conn, id)?;
159        let crdt = crdt.lock().unwrap_or_else(|p| p.into_inner());
160        Ok(dressed(&crdt, row))
161    }
162
163    /// `notes.mark`: a mark on the characters `from..to` of `id`'s text now,
164    /// anchored in its CRDT (which it does not change), with its `link` and
165    /// `label` (empty: none), by `hand`.
166    pub async fn mark(self: &Arc<Self>, id: &str, from: u32, to: u32, of: Remark, hand: Hand) -> Result<Mark, StoreError> {
167        let Remark { link, label, placed, props } = of;
168        let (component, version) = placed.unzip();
169        let props = match component {
170            Some(_) => Some(props_text(props.unwrap_or_default())?),
171            None => None,
172        };
173        let id = id.to_string();
174        let (mark, org) = self
175            .blocking(move |s| {
176                let conn = s.lock();
177                let doc = live_doc(&conn, &id)?;
178                let crdt = s.crdt(&conn, &id)?;
179                let crdt = crdt.lock().unwrap_or_else(|p| p.into_inner());
180                if from >= to {
181                    return Err(StoreError::BadRange(format!("a mark is on some characters: from {from} is not before to {to}")));
182                }
183                let Anchored { from_rel, to_rel, quote } = anchored(&crdt, from, to)?;
184                if quote.is_empty() {
185                    return Err(StoreError::BadRange(format!("{from}..{to} is past the end of the text")));
186                }
187                let mark = crate::vocab::mint(|m| conn.query_row("SELECT 1 FROM note_marks WHERE mark = ?1", [m], |_| Ok(())).optional().ok().flatten().is_some());
188                conn.execute(
189                    &format!("INSERT INTO note_marks ({COLUMNS}) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, NULL, NULL, ?11, ?12, ?13)"),
190                    params![mark, doc.id, from_rel, to_rel, quote, kept(link), kept(label), hand.name, hand.principal, now_ms(), component, version, props],
191                )?;
192                let row = conn.query_row(&format!("SELECT {COLUMNS} FROM note_marks WHERE mark = ?1"), [&mark], row_of)?;
193                Ok((dressed(&crdt, row), doc.org))
194            })
195            .await?;
196        self.said(Change::Marked { org, mark: mark.clone() });
197        Ok(mark)
198    }
199
200    /// `notes.mark { mark }`: the mark `mark` of `id` changed as `to` says, by `hand`.
201    pub async fn remark(self: &Arc<Self>, id: &str, mark: &str, to: Remark, hand: Hand) -> Result<Mark, StoreError> {
202        let (id, mark) = (id.to_string(), mark.to_string());
203        let (m, org) = self
204            .blocking(move |s| {
205                let conn = s.lock();
206                let doc = live_doc(&conn, &id)?;
207                s.mark_now(&conn, &id, &mark)?;
208                let set = |column: &str, value: Option<String>| -> Result<(), StoreError> {
209                    if let Some(v) = value {
210                        conn.execute(&format!("UPDATE note_marks SET {column} = ?2 WHERE mark = ?1"), params![mark, kept(Some(v))])?;
211                    }
212                    Ok(())
213                };
214                set("link", to.link)?;
215                set("label", to.label)?;
216                if let Some((component, version)) = to.placed {
217                    conn.execute("UPDATE note_marks SET component = ?2, version = ?3, props = COALESCE(props, '{}') WHERE mark = ?1", params![mark, component, version])?;
218                }
219                if let Some(props) = to.props {
220                    let has: Option<String> = conn.query_row("SELECT component FROM note_marks WHERE mark = ?1", [&mark], |r| r.get(0))?;
221                    if has.is_none() {
222                        return Err(StoreError::NoComponent(mark));
223                    }
224                    conn.execute("UPDATE note_marks SET props = ?2 WHERE mark = ?1", params![mark, props_text(props)?])?;
225                }
226                conn.execute("UPDATE note_marks SET changed_at = ?2, changed_by = ?3 WHERE mark = ?1", params![mark, now_ms(), hand.name])?;
227                Ok((s.mark_now(&conn, &id, &mark)?, doc.org))
228            })
229            .await?;
230        self.said(Change::Marked { org, mark: m.clone() });
231        Ok(m)
232    }
233
234    /// `notes.mark_props`: `patch` merged into the props of the mark `mark`
235    /// of `id` (a `null` takes its key away), held to 64 KiB, by `hand`.
236    pub async fn mark_props(self: &Arc<Self>, id: &str, mark: &str, patch: Map<String, Value>, hand: Hand) -> Result<Mark, StoreError> {
237        let (id, mark) = (id.to_string(), mark.to_string());
238        let (m, org) = self
239            .blocking(move |s| {
240                let conn = s.lock();
241                let tx = conn.unchecked_transaction()?;
242                let doc = live_doc(&tx, &id)?;
243                let was = s.mark_now(&tx, &id, &mark)?;
244                if was.component.is_none() {
245                    return Err(StoreError::NoComponent(mark));
246                }
247                let text = props_text(crate::slot::merged(was.props.unwrap_or_default(), patch))?;
248                tx.execute("UPDATE note_marks SET props = ?2, changed_at = ?3, changed_by = ?4 WHERE mark = ?1", params![mark, text, now_ms(), hand.name])?;
249                tx.commit()?;
250                Ok((s.mark_now(&conn, &id, &mark)?, doc.org))
251            })
252            .await?;
253        self.said(Change::Marked { org, mark: m.clone() });
254        Ok(m)
255    }
256
257    /// `notes.unmark`: the mark `mark` taken off `id`.
258    pub async fn unmark(self: &Arc<Self>, id: &str, mark: &str) -> Result<(), StoreError> {
259        let (id, mark) = (id.to_string(), mark.to_string());
260        let note = id.clone();
261        let (gone, org) = self
262            .blocking(move |s| {
263                let conn = s.lock();
264                let doc = live_doc(&conn, &id)?;
265                match conn.execute("DELETE FROM note_marks WHERE mark = ?1 AND id = ?2", params![mark, id])? {
266                    0 => Err(StoreError::NoMark(mark)),
267                    _ => Ok((mark, doc.org)),
268                }
269            })
270            .await?;
271        self.said(Change::Unmarked { id: note, org, mark: gone });
272        Ok(())
273    }
274
275    /// `notes.marks`: `id`'s marks, by where they stand in the text — the
276    /// detached ones at the end, each by when it was made.
277    pub async fn marks(self: &Arc<Self>, id: &str) -> Result<Vec<Mark>, StoreError> {
278        let id = id.to_string();
279        self.blocking(move |s| {
280            let conn = s.lock();
281            live_doc(&conn, &id)?;
282            let rows = {
283                let mut stmt = conn.prepare(&format!("SELECT {COLUMNS} FROM note_marks WHERE id = ?1 ORDER BY at"))?;
284                let rows = stmt.query_map([&id], row_of)?.collect::<Result<Vec<_>, _>>()?;
285                rows
286            };
287            let crdt = s.crdt(&conn, &id)?;
288            let crdt = crdt.lock().unwrap_or_else(|p| p.into_inner());
289            let mut out: Vec<Mark> = rows.into_iter().map(|r| dressed(&crdt, r)).collect();
290            out.sort_by_key(|m| (m.detached, m.from.unwrap_or(u32::MAX), m.at));
291            Ok(out)
292        })
293        .await
294    }
295}