margin 0.2.1__py3-none-any.whl

margin/pinch_check.py

@@ -0,0 +1,363 @@
+"""`margin pinch-check`: run a fold page's pinch on a real Android phone and judge it by measurement.
+
+A fold page moves one level for each pinch and keeps the paragraph under the fingers in place
+(fold.page). Whether it does that on a phone was a question for a person until 2026-10-26, and a page
+sent to a person to try by hand is the wrong way round: the phone can be driven over adb. This
+serves the page to the phone only (`adb reverse`, the phone's own localhost), opens it in the phone's
+Chromium browser, pinches it with two fingers through the browser's own synthetic gesture
+(claude-human's `android_browser.pinch`, which feeds touch events into the browser's view, since a
+phone with SELinux enforcing refuses the shell a write to its touch screen) behind the same checks as
+a tap (the app has focus, no banner or call, nobody touched the phone for a few seconds), reads the
+page after each pinch through the browser's debugging socket and judges four limits:
+
+  - the level moves by exactly one, in the pinch's direction (none at the end of the scale);
+  - the point of the paragraph that was under the fingers is less than 24 CSS pixels from where it was;
+  - the browser's own zoom stays at 1, during the gesture and after it;
+  - no frame takes longer than 50 ms from the gesture's start until the change has settled.
+
+It records the screen meanwhile (screen captures twice a second, made into an mp4 with ffmpeg) and writes a table (markdown) and the readings (JSON) beside the
+recording. Exit 0 only when every pinch passed.
+
+    margin pinch-check page.html --serial HOST:PORT [--package com.brave.browser] [--out DIR] [--wait-unlock S]
+
+The test never unlocks the phone (a PIN or a fingerprint is the person's own). With --wait-unlock it
+waits, up to that many seconds, until the phone is awake, unlocked and untouched for a minute, so it
+can run detached and start by itself when the person has the phone unlocked but is not using it.
+"""
+from __future__ import annotations
+
+import http.server
+import json
+import socket
+import subprocess
+import threading
+import time
+from functools import partial
+from pathlib import Path
+
+#: the four limits
+MAX_SHIFT_PX, MAX_FRAME_MS = 24.0, 50.0
+#: the levels a fold page has
+LOWEST, HIGHEST = 1, 5
+#: where on the page each round of pinches happens, as a share of how far it scrolls
+PLACES = (0.1, 0.5, 0.85)
+
+#: what the page reports at the start of each two-finger gesture, and the frames it draws
+LISTENER = r"""(() => {
+  if (window.__pc) return 'ready';
+  const pc = window.__pc = {starts: [], frames: [], maxScale: 1};
+  let last = 0;
+  const tick = t => { if (last) pc.frames.push([t, t - last]); last = t;
+    if (pc.frames.length > 6000) pc.frames.splice(0, 3000); requestAnimationFrame(tick); };
+  requestAnimationFrame(tick);
+  const pick = (at, next, x, y) => {
+    const a = at && ((next < 5 && at.closest('.u')) || at.closest('section'));
+    if (!a) return null;
+    if (!a.dataset.pc) a.dataset.pc = 'a' + Math.random().toString(36).slice(2);
+    const r = a.getBoundingClientRect();
+    return {id: a.dataset.pc, top: r.top, height: r.height,
+            frac: r.height ? Math.min(1, Math.max(0, (y - r.top) / r.height)) : 0};
+  };
+  addEventListener('touchstart', e => {
+    if (e.touches.length !== 2) return;
+    const x = (e.touches[0].clientX + e.touches[1].clientX) / 2, y = (e.touches[0].clientY + e.touches[1].clientY) / 2;
+    const at = document.elementFromPoint(x, y), level = +document.body.dataset.l;
+    pc.maxScale = visualViewport.scale;
+    pc.starts.push({t: performance.now(), x, y, level, pinches: window.pinches || 0,
+                    up: pick(at, level - 1, x, y), down: pick(at, level + 1, x, y)});
+  }, {capture: true, passive: true});
+  visualViewport.addEventListener('resize', () => { pc.maxScale = Math.max(pc.maxScale, visualViewport.scale); });
+  return 'ready';
+})()"""
+
+#: what happened since the last gesture began
+READ = r"""(() => {
+  const pc = window.__pc; if (!pc || !pc.starts.length) return null;
+  const s = pc.starts[pc.starts.length - 1], level = +document.body.dataset.l;
+  const which = level > s.level ? s.down : level < s.level ? s.up : null;
+  let after = null;
+  if (which) { const a = document.querySelector(`[data-pc="${which.id}"]`);
+    if (a && a.offsetParent) { const r = a.getBoundingClientRect(); after = {top: r.top, height: r.height}; } }
+  const gaps = pc.frames.filter(([t]) => t >= s.t && t <= s.t + 1500).map(([, d]) => d);
+  return {before: s.level, level, y: s.y, anchor: which, after, scale: visualViewport.scale,
+          max_scale: pc.maxScale, max_frame_ms: gaps.length ? Math.max(...gaps) : null,
+          starts: pc.starts.length, pinches: window.pinches || 0};
+})()"""
+
+
+def expected(before: int, direction: str) -> int:
+    """Pure. The level a pinch should end on: in folds one more, out opens one, within the scale."""
+    return min(HIGHEST, max(LOWEST, before + (1 if direction == "in" else -1)))
+
+
+def judge(reading: dict | None, direction: str) -> list[str]:
+    """Pure. Why this pinch failed, one reason per limit it broke; [] when it passed."""
+    if not reading:
+        return ["the page reported no two-finger gesture"]
+    why = []
+    want = expected(reading["before"], direction)
+    if reading["level"] != want:
+        why.append(f"level {reading['before']} went to {reading['level']}, not {want}")
+    if reading["level"] != reading["before"]:
+        a, after = reading.get("anchor"), reading.get("after")
+        if not a or not after:
+            why.append("the paragraph under the fingers could not be found after the change")
+        else:
+            shift = abs(after["top"] + a["frac"] * after["height"] - reading["y"])
+            if shift >= MAX_SHIFT_PX:
+                why.append(f"the paragraph under the fingers moved {shift:.0f} px")
+    zoom = max(reading.get("scale") or 1, reading.get("max_scale") or 1)
+    if abs(zoom - 1) > 0.001:
+        why.append(f"the browser zoomed to {zoom:.2f}")
+    frame = reading.get("max_frame_ms")
+    if frame is None:
+        why.append("no frame was drawn while it changed")
+    elif frame > MAX_FRAME_MS:
+        why.append(f"a frame took {frame:.0f} ms")
+    return why
+
+
+def table(rows: list[dict]) -> str:
+    """Pure. The results as a markdown table, one row a pinch."""
+    out = ["| # | place | pinch | speed | level | shift px | zoom | slowest frame ms | result |",
+           "|---|---|---|---|---|---|---|---|---|"]
+    for i, r in enumerate(rows, 1):
+        rd = r.get("reading") or {}
+        a, after = rd.get("anchor"), rd.get("after")
+        shift = (f"{abs(after['top'] + a['frac'] * after['height'] - rd['y']):.0f}" if a and after else "")
+        zoom = max(rd.get("scale") or 1, rd.get("max_scale") or 1) if rd else ""
+        frame = rd.get("max_frame_ms")
+        out.append(f"| {i} | {r['place']:.0%} | {r['direction']} | {'slow' if r['slow'] else 'quick'} | "
+                   f"{rd.get('before', '')} to {rd.get('level', '')} | {shift} | {zoom if zoom == '' else f'{zoom:.2f}'} | "
+                   f"{'' if frame is None else f'{frame:.0f}'} | "
+                   f"{'pass' if not r['why'] else 'FAIL ' + '; '.join(r['why'])} |")
+    return "\n".join(out)
+
+
+def plan() -> list[tuple[float, str, bool]]:
+    """Pure. Each pinch to make, as (place, direction, slow): at each place two in and two out quick,
+    then one in and one out slow; first of all one out at level 1, which must change nothing."""
+    steps = [(PLACES[0], "out", False)]
+    for place in PLACES:
+        steps += [(place, "in", False), (place, "in", False), (place, "out", False), (place, "out", False),
+                  (place, "in", True), (place, "out", True)]
+    return steps
+
+
+#: the phone's wakefulness and its last input, as dumpsys power prints them
+WAKEFULNESS = "dumpsys power | grep -E 'mWakefulness=|mLastUserActivityTime|ms ago'"
+#: seconds nobody may have touched the phone before the test takes its screen
+QUIET = 60.0
+#: and after an attempt the person interrupted (another app came to the front), since they are
+#: using the phone: five minutes untouched before the next attempt
+QUIET_AFTER_LOSS = 300.0
+
+
+def ready(power: str, locked: bool, idle: float | None, quiet: float = QUIET) -> bool:
+    """Pure. Whether the phone can take the test now: awake, past its lock screen, and untouched for
+    `quiet` seconds (`idle`, from claude_human.android.idle_s), so the browser does not take the
+    screen from a person who is using the phone."""
+    return "mWakefulness=Awake" in (power or "") and not locked and idle is not None and idle >= quiet
+
+
+class Page:
+    """The page in the phone's browser, through its debugging socket forwarded over adb. When the port
+    stops answering (adb's connection to the phone dropped and came back, which removes its forwards),
+    `eval` forwards it again and tries once more. `ab` is claude_human.android_browser."""
+
+    def __init__(self, ab, serial: str, package: str, url: str, run_adb):
+        self.ab, self.serial, self.package, self.url, self.run = ab, serial, package, url, run_adb
+        self.port = ab.forward(serial, package, run_adb)
+
+    def eval(self, js: str):
+        try:
+            return self.ab.evaluate(self.port, self.url, js)
+        except self.ab.BrowserError as e:
+            if "did not answer" not in str(e):
+                raise
+            self.ab.unforward(self.serial, self.port, self.run)
+            self.port = self.ab.forward(self.serial, self.package, self.run)
+            return self.ab.evaluate(self.port, self.url, js)
+
+    def pinch(self, x: float, y: float, scale: float, speed: float) -> None:
+        try:
+            return self.ab.pinch(self.port, self.url, x, y, scale, speed=speed)
+        except self.ab.BrowserError as e:
+            if "did not answer" not in str(e):
+                raise
+            self.ab.unforward(self.serial, self.port, self.run)
+            self.port = self.ab.forward(self.serial, self.package, self.run)
+            return self.ab.pinch(self.port, self.url, x, y, scale, speed=speed)
+
+    def close(self) -> None:
+        self.ab.unforward(self.serial, self.port, self.run)
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class PhoneLost(RuntimeError):
+    """The phone left adb, or its browser's debugging socket went, in the middle of a run."""
+
+
+def run(page: Path, serial: str, *, package: str = "com.brave.browser", out: Path | None = None,
+        adb: str = "adb", wait_unlock: float = 0.0, attempts: int = 8, sleep=time.sleep,
+        clock=time.monotonic) -> int:
+    """Serve `page` to the phone, pinch it as plan() says, judge each pinch, and write the results.
+    A phone that is lost in the middle (it left adb, its browser closed) is waited for again, within
+    `wait_unlock`, and the run starts over, up to `attempts` times. Exit 0 when every pinch passed,
+    1 when one failed, 2 when the test could not run."""
+    from claude_human import android, android_browser as ab   # noqa: PLC0415
+    out = Path(out or Path("/tmp/margin-pinch-check"))
+    out.mkdir(parents=True, exist_ok=True)
+    run_adb = android._runner(adb, None)
+    end = clock() + wait_unlock
+
+    def wait_ready(quiet: float = QUIET) -> bool:
+        said = False
+        while True:
+            power = android._read(serial, run_adb, WAKEFULNESS) or ""
+            if ready(power, android.locked(serial, run_adb), android.idle_s(power), quiet):
+                break
+            if clock() >= end:
+                return False
+            if not said:
+                print(f"{time.strftime('%H:%M')} waiting for the phone to be awake, unlocked and untouched for "
+                      f"{quiet:g} s", flush=True)
+                said = True
+            sleep(30)
+        return True
+
+    port = _free_port()
+    handler = partial(http.server.SimpleHTTPRequestHandler, directory=str(page.parent))
+    server = http.server.ThreadingHTTPServer(("127.0.0.1", port), handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    url = f"http://127.0.0.1:{port}/{page.name}"
+    rows: list[dict] | None = None
+    try:
+        for n in range(1, max(1, attempts) + 1):
+            if not wait_ready(QUIET if n == 1 else QUIET_AFTER_LOSS):
+                print("REFUSED: the phone is locked, asleep or off adb; it is never unlocked for the test "
+                      "(--wait-unlock waits)")
+                return 2
+            print(f"{time.strftime('%H:%M')} the phone is awake, unlocked and idle: attempt {n}", flush=True)
+            try:
+                rows = _attempt(serial, package, url, port, out, adb, run_adb)
+                break
+            except (PhoneLost, ab.BrowserError) as e:
+                print(f"{time.strftime('%H:%M')} attempt {n} lost the phone ({str(e)[:160]}); waiting for it again",
+                      flush=True)
+                rows = None
+        if rows is None:
+            print(f"REFUSED: the phone was lost in each of {attempts} attempts")
+            return 2
+    finally:
+        server.shutdown()
+    (out / "readings.json").write_text(json.dumps(rows, indent=1))
+    (out / "results.md").write_text(table(rows) + "\n")
+    print(table(rows))
+    failed = [r for r in rows if r["why"]]
+    print(f"\n{len(rows) - len(failed)} of {len(rows)} pinches passed; results in {out}")
+    return 1 if failed or not rows else 0
+
+
+#: how far a pinch moves the fingers (their end distance over their start) and how fast (CSS px/s)
+SCALE = {"in": 0.4, "out": 2.5}
+SPEED = {False: 800.0, True: 200.0}
+
+
+class Frames:
+    """The phone's screen, captured about twice a second while the test runs (screencap works where
+    screenrecord may not write a file), and made into an mp4 with ffmpeg when it stops."""
+
+    def __init__(self, adb: str, serial: str, folder: Path, gap: float = 0.5):
+        self.adb, self.serial, self.folder, self.gap = adb, serial, folder, gap
+        self.folder.mkdir(parents=True, exist_ok=True)
+        self.stop_flag = threading.Event()
+        self.n = 0
+        self.thread = threading.Thread(target=self._loop, daemon=True)
+        self.thread.start()
+
+    def _loop(self) -> None:
+        while not self.stop_flag.is_set():
+            r = subprocess.run([self.adb, "-s", self.serial, "exec-out", "screencap", "-p"], capture_output=True,
+                               timeout=30)
+            if r.returncode == 0 and r.stdout.startswith(b"\x89PNG"):
+                self.n += 1
+                (self.folder / f"{self.n:04d}.png").write_bytes(r.stdout)
+            self.stop_flag.wait(self.gap)
+
+    def stop(self, mp4: Path) -> bool:
+        self.stop_flag.set()
+        self.thread.join(timeout=40)
+        if not self.n:
+            return False
+        r = subprocess.run(["ffmpeg", "-y", "-loglevel", "error", "-framerate", "2", "-i",
+                            str(self.folder / "%04d.png"), "-vf", "scale=540:-2", "-pix_fmt", "yuv420p", str(mp4)],
+                           capture_output=True)
+        return r.returncode == 0 and mp4.exists()
+
+
+def _attempt(serial: str, package: str, url: str, port: int, out: Path, adb: str, run_adb) -> list[dict]:
+    """One run of the plan on the phone, each pinch made through the browser (android_browser.pinch)
+    after the same checks as a tap (android.why_not: the browser has focus, no banner or call, nobody
+    touched the phone for 3 s). Raises PhoneLost when the phone or its browser goes."""
+    from claude_human import android, android_browser as ab   # noqa: PLC0415
+    rows: list[dict] = []
+    if run_adb(["-s", serial, "reverse", f"tcp:{port}", f"tcp:{port}"])[0] != 0:
+        raise PhoneLost("adb could not reverse the port to the phone")
+    frames = None
+    try:
+        if not ab.open_url(serial, package, url, run_adb):
+            raise PhoneLost(f"could not open the page in {package}")
+        page = Page(ab, serial, package, url, run_adb)
+        try:
+            for _ in range(30):
+                try:
+                    if page.eval("document.readyState") == "complete":
+                        break
+                except ab.BrowserError:
+                    pass
+                time.sleep(1)
+            page.eval(LISTENER)
+            page.eval("set('1')")
+            view = page.eval("({w: innerWidth, h: innerHeight, dpr: devicePixelRatio})")
+            x, y = view["w"] / 2, view["h"] * 0.45
+            frames = Frames(adb, serial, out / "frames")
+            last_place = None
+            for place, direction, slow in plan():
+                if place != last_place:
+                    page.eval(f"scrollTo(0, {place} * (document.documentElement.scrollHeight - innerHeight))")
+                    time.sleep(1)
+                    last_place = place
+                end = time.monotonic() + 120
+                said = None
+                while (why := android.why_not(serial, package, int(y * view["dpr"]), run_adb, idle=3.0,
+                                              still=False)) is not None:
+                    if "focus" in why or "locked" in why:
+                        raise PhoneLost(f"not pinched: {why}")
+                    if why != said:
+                        print(f"{time.strftime('%H:%M')} waiting to pinch: {why}", flush=True)
+                        said = why
+                    if time.monotonic() > end:
+                        break
+                    time.sleep(1)
+                if why is not None:
+                    rows.append({"place": place, "direction": direction, "slow": slow, "reading": None,
+                                 "why": [f"not pinched: {why}"]})
+                    continue
+                page.pinch(x, y, SCALE[direction], SPEED[slow])
+                time.sleep(1.2)
+                reading = page.eval(READ)
+                rows.append({"place": place, "direction": direction, "slow": slow, "reading": reading,
+                             "why": judge(reading, direction)})
+        finally:
+            page.close()
+    finally:
+        if frames is not None:
+            frames.stop(out / "pinch.mp4")
+        run_adb(["-s", serial, "reverse", "--remove", f"tcp:{port}"])
+    return rows

margin/skills/margin/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: margin
+description: Use whenever you write or change documentation, a plan, a spec, a design, a report, notes or any markdown a person is meant to read, and whenever a message says "new comment(s) in Outline". margin publishes repository markdown to Outline, where the person reads it and comments on it, and brings the comments back to you. Covers where a document goes, publishing it, giving the person its link, and answering comments.
+---
+
+# margin
+
+Documentation lives as markdown files in the repository that owns the subject. margin publishes
+those files to Outline, where the person reads them in a browser or on a phone and comments on a
+piece of text. Each repository is one Outline collection, its folders are parent pages, and a
+folder's `README.md` is that folder's page. The comments come back to you in batches.
+
+This is the default way to give the person any document. Do not deliver a plan, a spec or a
+design only as chat text, an artifact or a file outside a published repository, unless the person
+asks for that.
+
+## Where a document goes
+
+The folder structure in the repository is the structure the person sees in Outline, so it has to
+stay right.
+
+1. **Pick the repository that owns the subject.** That is the repository whose code or decision it
+   is about. When a subject spans several repositories, it goes in the one that owns the decision,
+   and the others link to it. When no repository owns it, use the notes collection if the
+   configuration has one.
+2. **Follow that repository's own conventions.** Read its `CLAUDE.md` and its `README.md` first.
+   Put the file next to documents of the same kind (plans with plans, specs with specs). Never
+   start a second docs tree beside the one that exists.
+3. **Name and title it properly.** The file name is lowercase words joined by dashes, with a date
+   prefix when the folder already uses one. The first `# Heading` becomes the page title, so make
+   it a real name for the document.
+4. **A new folder needs a reason.** When you do create one, give it a `README.md` that says what
+   the folder holds, because that file is the folder's page.
+
+## Publishing, and giving the person the link
+
+After you create or change a document, publish it and hand over the link.
+
+```bash
+margin link path/to/doc.md [more files...]
+```
+
+It publishes those files at once and prints one Markdown link per file. A file in a git
+worktree of a published repository works too: margin finds the repository through git, and keeps
+publishing the worktree's version (the sync pass does not put the main folder's older text back)
+until the main folder has the same text, or the worktree file is gone. **Put every link it
+prints in your reply to the person**, so they can open each document you wrote or changed. Use only
+links margin printed. Never build an Outline address yourself. If margin prints "not published",
+tell the person which file and why, and fix it (move the file into a published repository, or ask
+for the repository to be added to the configuration). "not published: ... is conflict" (or
+`cannot-patch`, `drift`, `outline-edited`) means the document still has an older text, and `margin
+link` exits non-zero: the document is not published until the conflict is settled (below).
+
+To show a picture, save it next to the document (for example in a `shots/` folder beside it) and
+refer to it by a relative path, `![What it shows](shots/name.png)`. margin uploads it to the
+document and keeps it in sync; a changed picture republishes the document. Never paste an
+Outline attachment address into a file.
+
+Do not put a link or a code span inside bold text, as in `**A follow-up, [#581](url).**`. Outline
+rewrites it as `**A follow-up,** [**#581**](url)**.**`, so the document can never equal the file and
+every update of it fails. Put the link after the bold label: `**A follow-up.** [#581](url)`.
+
+## Answering a batch of comments
+
+1. Read the whole batch first. Several comments are often about one change.
+2. For each comment, decide what it asks for. It can be an answer, a change to the document, or both.
+3. If it asks for a change, edit the repository file (the path is under the document's title),
+   then run `margin link` on it. Never edit the document in Outline directly.
+4. Answer every comment in its own thread, even when the answer is only "changed it", so the person
+   can see what happened without asking. Use `margin reply <comment-id> "..."`.
+5. Run `margin resolve <comment-id>` only when the person's question is fully settled. When you are
+   not sure, leave it open.
+
+Use `margin thread <comment-id>` to read the whole thread when a comment is a reply.
+
+## Rules
+
+- Your replies are posted as the agent's own Outline user. Write them as yourself, in plain words.
+- Keep edits small. A comment attached to text you rewrite loses its highlight. margin patches only
+  the words that changed, so a comment on words you keep stays highlighted, even in a paragraph you
+  edited. Change only what the comment is about.
+- Never replace a whole document, never delete or move one, and never share one publicly. Sharing
+  is the person's decision. Moving a page is done by moving its file.
+- If `margin sync` or `margin link` reports `cannot-patch` or `drift`, nobody edited the document:
+  margin could not patch it into the file's text. Run `margin accept-file <file>`, which publishes
+  the file (it checks that only margin has edited the document), and do not ask the person about it.
+- If `margin sync` or `margin link` reports `conflict` or `outline-edited`, run
+  `margin accept-file <file>`. It lets the file win only when nobody but margin edited the
+  document since the last sync and it has no comments, and otherwise it refuses and names who
+  edited it. When it refuses, the person changed the document in Outline: do not force your
+  version. Read the document (Outline's MCP `fetch`), copy their edit into the file, and run
+  `margin accept-merged <file>`. It publishes only when every line they added or changed is in
+  the file and no line they removed is, and otherwise refuses and names the line. When their
+  edit and yours cannot both stand, tell them which document it is and ask.
+- Say a document is published only when `margin link` printed its link in this turn.

margin/store.py

@@ -0,0 +1,186 @@
+"""margin's state: one SQLite file. What was synced, which comments arrived, which were delivered.
+
+Nothing here is a second copy of the documents. `doc` keeps, per file, the text both sides had at the
+last sync, which is exactly what is needed to tell "only the repo changed" from "both changed".
+"""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import sqlite3
+import threading
+import time
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS doc (
+  repo TEXT NOT NULL, path TEXT NOT NULL,          -- path relative to the repo, '' for the repo root
+  doc_id TEXT NOT NULL, collection_id TEXT NOT NULL,
+  base_repo TEXT,                                  -- the repo file's text at the last sync
+  base_outline TEXT,                               -- Outline's text right after the last sync
+  status TEXT NOT NULL DEFAULT 'ok',               -- ok | conflict | cannot-patch | missing-file
+  detail TEXT, synced_at REAL,
+  PRIMARY KEY (repo, path)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS doc_by_id ON doc(doc_id);
+CREATE TABLE IF NOT EXISTS comment (
+  id TEXT PRIMARY KEY, document_id TEXT NOT NULL, parent_id TEXT,
+  author_id TEXT, author TEXT, text TEXT, anchor TEXT,
+  created_at TEXT NOT NULL, received_at REAL NOT NULL,
+  mentions_agent INTEGER NOT NULL DEFAULT 0,
+  route TEXT,                                      -- NULL when the document is not one margin syncs
+  via TEXT NOT NULL,                               -- webhook | poll
+  delivered_at REAL, batch_id TEXT,
+  resolved_at TEXT,                                -- when the thread was resolved, if it was
+  anchor_before TEXT,                              -- the words before the passage in its paragraph
+  anchor_lost INTEGER NOT NULL DEFAULT 0           -- 1 when its passage has no mark left in the text
+);
+CREATE INDEX IF NOT EXISTS comment_pending ON comment(route) WHERE delivered_at IS NULL;
+CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT);
+"""
+
+
+class _Locked:
+    """The connection's execute family, each call under the store's lock."""
+
+    def __init__(self, db, lock):
+        self._d, self._l = db, lock
+
+    def execute(self, *a):
+        with self._l:
+            return _Rows(self._d.execute(*a))
+
+    def executemany(self, *a):
+        with self._l:
+            return self._d.executemany(*a)
+
+    def executescript(self, *a):
+        with self._l:
+            return self._d.executescript(*a)
+
+
+class _Rows:
+    """A finished cursor: rows fetched while the lock was held."""
+
+    def __init__(self, cur):
+        self.rowcount = cur.rowcount
+        self._rows = cur.fetchall() if cur.description else []
+
+    def fetchone(self):
+        return self._rows[0] if self._rows else None
+
+    def fetchall(self):
+        return self._rows
+
+
+class Store:
+    def __init__(self, path: Path):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.path = path
+        # One connection shared by the webhook thread and the main loop, so every statement
+        # goes through one lock.
+        self._db = sqlite3.connect(str(path), isolation_level=None, timeout=30,
+                                   check_same_thread=False)
+        self._db.row_factory = sqlite3.Row
+        self.lock = threading.RLock()
+        self.db = _Locked(self._db, self.lock)
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.executescript(SCHEMA)
+        # a store made before a column existed gains it
+        cols = {r["name"] for r in self.db.execute("PRAGMA table_info(comment)").fetchall()}
+        for col, kind in (("resolved_at", "TEXT"), ("anchor_before", "TEXT"),
+                          ("anchor_lost", "INTEGER NOT NULL DEFAULT 0")):
+            if col not in cols:
+                self.db.execute(f"ALTER TABLE comment ADD COLUMN {col} {kind}")
+
+    # ---- docs
+    def doc(self, repo: str, path: str):
+        return self.db.execute("SELECT * FROM doc WHERE repo=? AND path=?", (repo, path)).fetchone()
+
+    def doc_by_id(self, doc_id: str):
+        return self.db.execute("SELECT * FROM doc WHERE doc_id=?", (doc_id,)).fetchone()
+
+    def docs(self, repo: str | None = None):
+        if repo:
+            return self.db.execute("SELECT * FROM doc WHERE repo=? ORDER BY path", (repo,)).fetchall()
+        return self.db.execute("SELECT * FROM doc ORDER BY repo, path").fetchall()
+
+    def save_doc(self, repo, path, doc_id, collection_id, base_repo, base_outline,
+                 status="ok", detail=None):
+        self.db.execute(
+            "INSERT INTO doc(repo,path,doc_id,collection_id,base_repo,base_outline,status,detail,"
+            "synced_at) VALUES(?,?,?,?,?,?,?,?,?) ON CONFLICT(repo,path) DO UPDATE SET "
+            "doc_id=excluded.doc_id, collection_id=excluded.collection_id, "
+            "base_repo=excluded.base_repo, base_outline=excluded.base_outline, "
+            "status=excluded.status, detail=excluded.detail, synced_at=excluded.synced_at",
+            (repo, path, doc_id, collection_id, base_repo, base_outline, status, detail, time.time()))
+
+    def mark(self, repo, path, status, detail=None):
+        self.db.execute("UPDATE doc SET status=?, detail=? WHERE repo=? AND path=?",
+                        (status, detail, repo, path))
+
+    # ---- comments
+    def add_comment(self, c: dict) -> bool:
+        """Record a comment once. Returns True when it is new. A comment stored with
+        `delivered_at` set is kept for reading and never handed on as work."""
+        cur = self.db.execute(
+            "INSERT OR IGNORE INTO comment(id,document_id,parent_id,author_id,author,text,anchor,"
+            "created_at,received_at,mentions_agent,route,via,delivered_at,resolved_at,anchor_before) "
+            "VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+            (c["id"], c["document_id"], c.get("parent_id"), c.get("author_id"), c.get("author"),
+             c.get("text"), c.get("anchor"), c["created_at"], time.time(),
+             int(bool(c.get("mentions_agent"))), c.get("route"), c["via"], c.get("delivered_at"),
+             c.get("resolved_at"), c.get("anchor_before")))
+        return cur.rowcount == 1
+
+    def set_place(self, comment_id: str, before: str | None) -> None:
+        """Where a comment's passage sits: the words before it in its paragraph ("" when it opens
+        it), or None when the text has no mark for it any more (anchor_lost)."""
+        self.db.execute("UPDATE comment SET anchor_before=?, anchor_lost=? WHERE id=?",
+                        (before, int(before is None), comment_id))
+
+    def anchored(self, document_id: str) -> list[str]:
+        """The comments that open a thread on a passage of the document."""
+        return [r["id"] for r in self.db.execute(
+            "SELECT id FROM comment WHERE document_id=? AND parent_id IS NULL AND anchor IS NOT NULL "
+            "AND anchor <> ''", (document_id,)).fetchall()]
+
+    def without_anchor_before(self):
+        """Comments on a passage whose place in the document is not recorded yet."""
+        return self.db.execute("SELECT id, document_id FROM comment WHERE parent_id IS NULL AND "
+                               "anchor IS NOT NULL AND anchor <> '' AND anchor_before IS NULL "
+                               "AND anchor_lost = 0 ORDER BY document_id").fetchall()
+
+    def set_resolved(self, comment_id: str, at: str | None) -> None:
+        """When a thread was resolved, or None when it was opened again."""
+        self.db.execute("UPDATE comment SET resolved_at=? WHERE id=?", (at, comment_id))
+
+    def pending(self):
+        return self.db.execute("SELECT * FROM comment WHERE delivered_at IS NULL AND route IS NOT "
+                               "NULL ORDER BY received_at").fetchall()
+
+    def delivered(self, ids: list[str], batch_id: str):
+        self.db.executemany("UPDATE comment SET delivered_at=?, batch_id=? WHERE id=?",
+                            [(time.time(), batch_id, i) for i in ids])
+
+    # ---- small values (watermarks)
+    def get(self, k: str, default: str | None = None) -> str | None:
+        row = self.db.execute("SELECT v FROM kv WHERE k=?", (k,)).fetchone()
+        return row["v"] if row else default
+
+    def put(self, k: str, v: str):
+        self.db.execute("INSERT INTO kv(k,v) VALUES(?,?) ON CONFLICT(k) DO UPDATE SET v=excluded.v",
+                        (k, v))
+
+
+@contextlib.contextmanager
+def repo_lock(store: "Store", repo: str):
+    """One writer per repo across processes: the serve loop and a chat's `margin link` both sync,
+    and two passes that both see "no document yet" would each create one."""
+    lock = store.path.parent / f"{store.path.stem}.{repo}.lock"
+    with open(lock, "w") as fh:
+        fcntl.flock(fh, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(fh, fcntl.LOCK_UN)