Skip to main content

menger_notes/
threads.rs

1//! V2-30: **asking on a selection** — a question anchored to a range of a
2//! note, answered in a thread beside it by a person or an agent (the
3//! owner, 2026-11-02: *"I want to have the ability to highlight a line in a
4//! doc and ask a question … these docs are really important and will be key
5//! locations for paired work."*).
6//!
7//! **The anchor follows the text.** A thread's range is two Yjs relative
8//! positions in the note's CRDT ([`yrs::StickyIndex`], the browser's
9//! `Y.RelativePosition` byte for byte): the start sticks to the character
10//! after it, the end to the character before it, so every hand's edit —
11//! around the range, inside it — moves them with the text. Resolved now,
12//! they are the range's offsets in characters (`from`, `to`); a range whose
13//! text was deleted whole resolves to nothing and the thread is
14//! **detached** (kept, listed at the end). The browser resolves the same
15//! positions in its own copy (`anchor`, base64), so the margin is exact.
16//!
17//! **Stored** in the notes file: `doc_threads` (a row per question: its
18//! anchor, the text it quoted, the question, to whom, who and when, and
19//! when it was resolved) and `doc_replies` (a row per answer). Said on the
20//! channel for `watch`: `asked`, `replied`, `resolved`, each with the
21//! thread whole.
22
23use crate::crdt::{b64, text_of, unb64, BODY};
24use crate::events::{Anchor, Reply, Resolution, Thread};
25use crate::store::{live_doc, now_ms, Change, NotesStore, StoreError};
26use rusqlite::{params, Connection, OptionalExtension};
27use std::sync::Arc;
28use yrs::updates::decoder::Decode;
29use yrs::updates::encoder::Encode;
30use yrs::{Assoc, IndexedSequence, StickyIndex, Transact};
31
32/// The tables.
33pub const TABLES: &str = "
34        CREATE TABLE IF NOT EXISTS doc_threads (
35            thread       TEXT PRIMARY KEY,
36            id           TEXT NOT NULL,
37            from_rel     BLOB NOT NULL,
38            to_rel       BLOB NOT NULL,
39            quote        TEXT NOT NULL,
40            question     TEXT NOT NULL,
41            to_whom      TEXT,
42            by           TEXT NOT NULL,
43            principal    TEXT NOT NULL,
44            at           INTEGER NOT NULL,
45            resolved_at  INTEGER,
46            resolved_by  TEXT
47        );
48        CREATE INDEX IF NOT EXISTS doc_threads_id ON doc_threads (id);
49        CREATE TABLE IF NOT EXISTS doc_replies (
50            thread     TEXT NOT NULL,
51            n          INTEGER NOT NULL,
52            body       TEXT NOT NULL,
53            by         TEXT NOT NULL,
54            principal  TEXT NOT NULL,
55            at         INTEGER NOT NULL,
56            PRIMARY KEY (thread, n)
57        );
58    ";
59
60/// Who asked or answered.
61#[derive(Debug, Clone)]
62pub struct Hand {
63    pub name: String,
64    pub principal: String,
65}
66
67/// The byte offset of character `chars` in `text` (its end past the last).
68fn byte_at(text: &str, chars: usize) -> usize {
69    text.char_indices().nth(chars).map_or(text.len(), |(i, _)| i)
70}
71
72/// The character offset of byte `bytes` in `text`.
73fn chars_at(text: &str, bytes: usize) -> usize {
74    text[..bytes.min(text.len())].chars().count()
75}
76
77/// A range anchored in a note's CRDT: its two relative positions, and the
78/// text it held then — what a question and (NOTES-5) a mark keep.
79pub(crate) struct Anchored {
80    pub from_rel: Vec<u8>,
81    pub to_rel: Vec<u8>,
82    pub quote: String,
83}
84
85/// The characters `from..to` of `crdt`'s text now (clamped to its end),
86/// anchored: the start sticks to the character after it, the end to the
87/// one before it, so both follow the text through every edit.
88pub(crate) fn anchored(crdt: &yrs::Doc, from: u32, to: u32) -> Result<Anchored, StoreError> {
89    let text = text_of(crdt);
90    let n = text.chars().count() as u32;
91    let (from, to) = (from.min(n), to.min(n));
92    if from > to {
93        return Err(StoreError::BadRange(format!("from {from} is past to {to}")));
94    }
95    let (fb, tb) = (byte_at(&text, from as usize), byte_at(&text, to as usize));
96    let body = crdt.get_or_insert_text(BODY);
97    let (from_rel, to_rel) = {
98        let txn = crdt.transact();
99        let at = |b: usize, assoc| body.sticky_index(&txn, b as u32, assoc).map(|s| s.encode_v1());
100        (at(fb, Assoc::After), at(tb, Assoc::Before))
101    };
102    let (from_rel, to_rel) = from_rel.zip(to_rel).ok_or_else(|| StoreError::BadRange(format!("{from}..{to} is not in the text")))?;
103    Ok(Anchored { from_rel, to_rel, quote: text[fb..tb].to_string() })
104}
105
106/// Where an anchored range stands in `crdt` now (`text`, its text): its
107/// character offsets, or none when it is detached — its text deleted
108/// whole (`empty_ok`: a range of nothing never is).
109pub(crate) fn placed(crdt: &yrs::Doc, text: &str, from_rel: &[u8], to_rel: &[u8], empty_ok: bool) -> Option<(u32, u32)> {
110    let resolve = |bytes: &[u8]| -> Option<usize> {
111        let sticky = StickyIndex::decode_v1(bytes).ok()?;
112        let txn = crdt.transact();
113        sticky.get_offset(&txn).map(|o| chars_at(text, o.index as usize))
114    };
115    match (resolve(from_rel), resolve(to_rel)) {
116        (Some(f), Some(t)) if t > f || (empty_ok && t == f) => Some((f as u32, t as u32)),
117        _ => None,
118    }
119}
120
121/// The characters `from..to` of `text`.
122pub(crate) fn slice(text: &str, from: u32, to: u32) -> &str {
123    &text[byte_at(text, from as usize)..byte_at(text, to as usize)]
124}
125
126/// What the stored row of a thread holds before its anchor is resolved.
127struct Row {
128    thread: String,
129    id: String,
130    from_rel: Vec<u8>,
131    to_rel: Vec<u8>,
132    quote: String,
133    question: String,
134    to_whom: Option<String>,
135    by: String,
136    principal: String,
137    at: i64,
138    resolved: Option<Resolution>,
139}
140
141const COLUMNS: &str = "thread, id, from_rel, to_rel, quote, question, to_whom, by, principal, at, resolved_at, resolved_by";
142
143fn row_of(r: &rusqlite::Row<'_>) -> rusqlite::Result<Row> {
144    let resolved_at: Option<i64> = r.get(10)?;
145    let resolved_by: Option<String> = r.get(11)?;
146    Ok(Row {
147        thread: r.get(0)?,
148        id: r.get(1)?,
149        from_rel: r.get(2)?,
150        to_rel: r.get(3)?,
151        quote: r.get(4)?,
152        question: r.get(5)?,
153        to_whom: r.get(6)?,
154        by: r.get(7)?,
155        principal: r.get(8)?,
156        at: r.get(9)?,
157        resolved: resolved_at.map(|at| Resolution { at, by: resolved_by.unwrap_or_default() }),
158    })
159}
160
161impl NotesStore {
162    /// `row` made a [`Thread`]: its anchor resolved in `crdt` now, its replies read.
163    fn dressed(&self, conn: &Connection, crdt: &yrs::Doc, row: Row) -> Result<Thread, StoreError> {
164        let text = text_of(crdt);
165        let (from, to, detached) = match placed(crdt, &text, &row.from_rel, &row.to_rel, row.quote.is_empty()) {
166            Some((f, t)) => (Some(f), Some(t), false),
167            None => (None, None, true),
168        };
169        let mut stmt = conn.prepare("SELECT n, body, by, principal, at FROM doc_replies WHERE thread = ?1 ORDER BY n")?;
170        let replies = stmt
171            .query_map([&row.thread], |r| Ok(Reply { n: r.get(0)?, body: r.get(1)?, by: r.get(2)?, principal: r.get(3)?, at: r.get(4)? }))?
172            .collect::<Result<Vec<_>, _>>()?;
173        Ok(Thread {
174            thread: row.thread,
175            id: row.id,
176            anchor: Anchor { from: b64(&row.from_rel), to: b64(&row.to_rel) },
177            from,
178            to,
179            detached,
180            quote: row.quote,
181            question: row.question,
182            to_whom: row.to_whom,
183            by: row.by,
184            principal: row.principal,
185            at: row.at,
186            resolved: row.resolved,
187            replies,
188        })
189    }
190
191    /// The thread `thread` of the live note `id`, dressed.
192    fn thread_now(&self, conn: &Connection, id: &str, thread: &str) -> Result<Thread, StoreError> {
193        let row = conn
194            .query_row(&format!("SELECT {COLUMNS} FROM doc_threads WHERE thread = ?1 AND id = ?2"), params![thread, id], row_of)
195            .optional()?
196            .ok_or_else(|| StoreError::NoThread(thread.to_string()))?;
197        let crdt = self.crdt(conn, id)?;
198        let crdt = crdt.lock().unwrap_or_else(|p| p.into_inner());
199        self.dressed(conn, &crdt, row)
200    }
201
202    /// `notes.ask`: a question on the characters `from..to` of `id`'s text
203    /// now, anchored in its CRDT, to `to_whom` when it says, by `hand`.
204    pub async fn ask(self: &Arc<Self>, id: &str, from: u32, to: u32, question: &str, to_whom: Option<String>, hand: Hand) -> Result<Thread, StoreError> {
205        let (id, question) = (id.to_string(), question.to_string());
206        let thread = self
207            .blocking(move |s| {
208                // V2-39: one question held for the asker before it is kept,
209                // committed once it is, released if it is not.
210                let quota = s.quota();
211                let held = quota.reserve_question(&hand.principal).map_err(StoreError::Allowance)?;
212                let kept = (|| {
213                    let conn = s.lock();
214                    let doc = live_doc(&conn, &id)?;
215                    let crdt = s.crdt(&conn, &id)?;
216                    let crdt = crdt.lock().unwrap_or_else(|p| p.into_inner());
217                    let Anchored { from_rel, to_rel, quote } = anchored(&crdt, from, to)?;
218                    let thread = crate::vocab::mint(|t| conn.query_row("SELECT 1 FROM doc_threads WHERE thread = ?1", [t], |_| Ok(())).optional().ok().flatten().is_some());
219                    conn.execute(
220                        &format!("INSERT INTO doc_threads ({COLUMNS}) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, NULL, NULL)"),
221                        params![thread, doc.id, from_rel, to_rel, quote, question, to_whom, hand.name, hand.principal, now_ms()],
222                    )?;
223                    let row = conn.query_row(&format!("SELECT {COLUMNS} FROM doc_threads WHERE thread = ?1"), [&thread], row_of)?;
224                    Ok((s.dressed(&conn, &crdt, row)?, doc.org))
225                })();
226                match kept {
227                    Ok(k) => {
228                        quota.commit(held);
229                        Ok(k)
230                    }
231                    Err(e) => {
232                        quota.release(held);
233                        Err(e)
234                    }
235                }
236            })
237            .await?;
238        self.said(Change::Asked { org: thread.1, thread: thread.0.clone() });
239        Ok(thread.0)
240    }
241
242    /// `notes.reply`: `body` under the thread, by `hand`.
243    pub async fn reply(self: &Arc<Self>, id: &str, thread: &str, body: &str, hand: Hand) -> Result<Thread, StoreError> {
244        let (id, thread, body) = (id.to_string(), thread.to_string(), body.to_string());
245        let (t, org) = self
246            .blocking(move |s| {
247                let conn = s.lock();
248                let doc = live_doc(&conn, &id)?;
249                s.thread_now(&conn, &id, &thread)?;
250                let n: u32 = conn.query_row("SELECT coalesce(max(n), 0) + 1 FROM doc_replies WHERE thread = ?1", [&thread], |r| r.get(0))?;
251                conn.execute("INSERT INTO doc_replies (thread, n, body, by, principal, at) VALUES (?1, ?2, ?3, ?4, ?5, ?6)", params![thread, n, body, hand.name, hand.principal, now_ms()])?;
252                Ok((s.thread_now(&conn, &id, &thread)?, doc.org))
253            })
254            .await?;
255        self.said(Change::Replied { org, thread: t.clone() });
256        Ok(t)
257    }
258
259    /// `notes.resolve`: the thread folded, by `hand` (again: it opens).
260    pub async fn resolve(self: &Arc<Self>, id: &str, thread: &str, open: bool, hand: Hand) -> Result<Thread, StoreError> {
261        let (id, thread) = (id.to_string(), thread.to_string());
262        let (t, org) = self
263            .blocking(move |s| {
264                let conn = s.lock();
265                let doc = live_doc(&conn, &id)?;
266                s.thread_now(&conn, &id, &thread)?;
267                match open {
268                    false => conn.execute("UPDATE doc_threads SET resolved_at = ?2, resolved_by = ?3 WHERE thread = ?1", params![thread, now_ms(), hand.name])?,
269                    true => conn.execute("UPDATE doc_threads SET resolved_at = NULL, resolved_by = NULL WHERE thread = ?1", [&thread])?,
270                };
271                Ok((s.thread_now(&conn, &id, &thread)?, doc.org))
272            })
273            .await?;
274        self.said(Change::Resolved { org, thread: t.clone() });
275        Ok(t)
276    }
277
278    /// `notes.threads`: `id`'s threads, by where they stand in the text —
279    /// the detached ones at the end, each by when it was asked.
280    pub async fn threads(self: &Arc<Self>, id: &str) -> Result<Vec<Thread>, StoreError> {
281        let id = id.to_string();
282        self.blocking(move |s| {
283            let conn = s.lock();
284            live_doc(&conn, &id)?;
285            let rows = {
286                let mut stmt = conn.prepare(&format!("SELECT {COLUMNS} FROM doc_threads WHERE id = ?1 ORDER BY at"))?;
287                let rows = stmt.query_map([&id], row_of)?.collect::<Result<Vec<_>, _>>()?;
288                rows
289            };
290            let crdt = s.crdt(&conn, &id)?;
291            let crdt = crdt.lock().unwrap_or_else(|p| p.into_inner());
292            let mut out = rows.into_iter().map(|r| s.dressed(&conn, &crdt, r)).collect::<Result<Vec<_>, _>>()?;
293            out.sort_by_key(|t| (t.detached, t.from.unwrap_or(u32::MAX), t.at));
294            Ok(out)
295        })
296        .await
297    }
298
299    /// `notes.waiting`: the open threads asked of someone (`to_whom`) in the
300    /// notes of `orgs`, oldest first — `to` keeping those asked of it.
301    pub async fn waiting(self: &Arc<Self>, orgs: Vec<String>, to: Option<String>) -> Result<Vec<Thread>, StoreError> {
302        self.blocking(move |s| {
303            let conn = s.lock();
304            if orgs.is_empty() {
305                return Ok(Vec::new());
306            }
307            let sql = format!(
308                "SELECT t.{} FROM doc_threads t JOIN docs d ON d.id = t.id WHERE d.deleted_at IS NULL AND t.resolved_at IS NULL AND t.to_whom IS NOT NULL AND d.org IN ({}) ORDER BY t.at",
309                COLUMNS.replace(", ", ", t."),
310                vec!["?"; orgs.len()].join(", ")
311            );
312            let rows = {
313                let mut stmt = conn.prepare(&sql)?;
314                let rows = stmt.query_map(rusqlite::params_from_iter(orgs.iter()), row_of)?.collect::<Result<Vec<_>, _>>()?;
315                rows
316            };
317            let mut out = Vec::new();
318            for r in rows.into_iter().filter(|r| to.as_deref().is_none_or(|w| r.to_whom.as_deref() == Some(w))) {
319                let crdt = s.crdt(&conn, &r.id)?;
320                let crdt = crdt.lock().unwrap_or_else(|p| p.into_inner());
321                out.push(s.dressed(&conn, &crdt, r)?);
322            }
323            Ok(out)
324        })
325        .await
326    }
327}
328
329/// A thread's anchor from base64 — for a client resolving it itself.
330pub fn anchor_bytes(text: &str) -> Result<Vec<u8>, StoreError> {
331    unb64(text)
332}