@3sln/trove 0.0.2

package/packages/core/src/search/vectorize.js

@@ -0,0 +1,249 @@
+// VectorizeVectorStore — an adapter over Cloudflare Vectorize, proving the
+// VectorStore contract fits a serverless, metadata-filtered ANN index. Two
+// access modes share one code path:
+//   • Workers binding — `new VectorizeVectorStore({ binding: env.VECTORIZE, dimensions })`.
+//     Calls the binding RPC surface directly (upsert/query/deleteByIds/getByIds).
+//   • REST API      — `new VectorizeVectorStore({ accountId, apiKey, indexName, dimensions })`.
+//     Talks to the v2 REST endpoints over fetch (works on Node, Bun, Workers).
+//
+// Two quirks the interface must paper over:
+//   1. Vector ids are capped at 64 bytes, so a docId longer than that collapses
+//      to a deterministic SHA-256 hex; the original docId always lives in
+//      metadata so query results and remove(docId) still round-trip.
+//   2. Vectorize has NO delete-by-filter — only deleteByIds. So the wholesale
+//      removes (by node / indexer) are implemented query-then-delete: query a
+//      zero vector with a metadata filter, collect the matched ids, delete them,
+//      and repeat until a query comes back empty. This needs metadata indexes on
+//      the filtered properties, which we create lazily on first use (REST) or
+//      assume are provisioned out-of-band (binding).
+
+import { VectorStore } from './vectorStore.js';
+import { TroveError, wrapError } from '../errors.js';
+import { withRetry } from '../retry.js';
+
+// Reserved metadata keys — the routing columns, never treated as user fields.
+const RESERVED = ['docId', 'nodeId', 'indexerId'];
+// Vectorize caps topK at 20 when returnMetadata is "all" (full metadata is only
+// returned for the top slice), so both querying and pagination stay within it.
+const MAX_TOPK = 20;
+
+export class VectorizeVectorStore extends VectorStore {
+  /**
+   * @param {object} cfg
+   * @param {number} cfg.dimensions       vector dimensionality (required)
+   * @param {object} [cfg.binding]        Workers Vectorize binding (binding mode)
+   * @param {string} [cfg.accountId]      Cloudflare account id (REST mode)
+   * @param {string} [cfg.apiKey]         API token, sent as Bearer (REST mode)
+   * @param {string} [cfg.indexName]      Vectorize index name (REST mode)
+   * @param {string} [cfg.namespace]      optional query namespace (REST mode)
+   */
+  constructor(cfg = {}) {
+    super();
+    if (!cfg.dimensions) throw TroveError.invalid('VectorizeVectorStore requires "dimensions"');
+    this._dimensions = cfg.dimensions;
+    this.binding = cfg.binding || null;
+    if (!this.binding) {
+      for (const k of ['accountId', 'apiKey', 'indexName']) {
+        if (!cfg[k]) throw TroveError.invalid(`VectorizeVectorStore (REST mode) requires "${k}"`);
+      }
+      this._baseUrl = `https://api.cloudflare.com/client/v4/accounts/${cfg.accountId}/vectorize/v2/indexes/${cfg.indexName}`;
+    }
+    this.cfg = cfg;
+    this._ready = null;
+  }
+
+  // --- transport ----------------------------------------------------------
+
+  /** One REST call. Cloudflare wraps every response as { success, result, errors }. */
+  async #req(path, body, { ndjson } = {}) {
+    return withRetry(
+      async () => {
+        let res;
+        try {
+          res = await fetch(this._baseUrl + path, {
+            method: 'POST',
+            headers: {
+              authorization: `Bearer ${this.cfg.apiKey}`,
+              'content-type': ndjson ? 'application/x-ndjson' : 'application/json',
+            },
+            body: ndjson ? body : body !== undefined ? JSON.stringify(body) : undefined,
+          });
+        } catch (err) {
+          throw wrapError(err);
+        }
+        if (res.status === 429 || res.status >= 500) throw TroveError.transient(`Vectorize ${res.status}`);
+        const json = await res.json().catch(() => ({}));
+        if (!res.ok || json.success === false) {
+          const msg = json?.errors?.map?.((e) => e.message).filter(Boolean).join('; ') || res.status;
+          throw TroveError.internal(`Vectorize ${path} failed: ${msg}`);
+        }
+        return json.result ?? {};
+      },
+      { retries: 3 },
+    );
+  }
+
+  /** One binding RPC. Retried on transient classification; errors normalised. */
+  async #binding(fn) {
+    return withRetry(
+      async () => {
+        try {
+          return await fn();
+        } catch (err) {
+          throw wrapError(err);
+        }
+      },
+      { retries: 3 },
+    );
+  }
+
+  /** Ensure the metadata indexes deletes rely on exist (idempotent). */
+  async #ensure() {
+    if (!this._ready) {
+      this._ready = (async () => {
+        // Binding mode: metadata indexes are provisioned out-of-band (wrangler),
+        // so there is nothing to create — just proceed.
+        if (this.binding) return;
+        for (const propertyName of ['nodeId', 'indexerId']) {
+          await this.#req('/metadata_index/create', { propertyName, indexType: 'string' }).catch((e) => {
+            // Tolerate a metadata index that already exists; surface real errors.
+            if (!/already|exist/i.test(e.message)) throw e;
+          });
+        }
+      })();
+    }
+    return this._ready;
+  }
+
+  // --- writes -------------------------------------------------------------
+
+  async add(docs) {
+    if (!docs.length) return;
+    await this.#ensure();
+    const vectors = await Promise.all(
+      docs.map(async (d) => ({
+        id: await vectorId(d.id),
+        values: Array.from(d.vector),
+        metadata: buildMetadata(d),
+      })),
+    );
+    if (this.binding) {
+      await this.#binding(() => this.binding.upsert(vectors));
+    } else {
+      // Upsert body is NDJSON: one JSON vector object per line.
+      const body = vectors.map((v) => JSON.stringify(v)).join('\n');
+      await this.#req('/upsert', body, { ndjson: true });
+    }
+  }
+
+  async remove(docId) {
+    await this.#ensure();
+    await this.#deleteByIds([await vectorId(docId)]);
+  }
+
+  async removeByNode(nodeId) {
+    await this.#purge({ nodeId: { $eq: nodeId } });
+  }
+  async removeByIndexer(indexerId) {
+    await this.#purge({ indexerId: { $eq: indexerId } });
+  }
+  async removeByNodeIndexer(nodeId, indexerId) {
+    await this.#purge({ nodeId: { $eq: nodeId }, indexerId: { $eq: indexerId } });
+  }
+
+  /**
+   * Query-then-delete: Vectorize can't delete by filter, so page through the
+   * matching vectors (topK capped at MAX_TOPK) and delete their ids until a
+   * query returns nothing — so a file with many chunks is fully cleared.
+   */
+  async #purge(filter) {
+    await this.#ensure();
+    const zero = new Array(this._dimensions).fill(0);
+    // Bounded loop guards against an eventually-consistent delete looping forever.
+    for (let page = 0; page < 10000; page++) {
+      const matches = await this.#queryRaw(zero, { topK: MAX_TOPK, filter });
+      if (!matches.length) break;
+      await this.#deleteByIds(matches.map((m) => m.id));
+    }
+  }
+
+  async #deleteByIds(ids) {
+    if (!ids.length) return;
+    if (this.binding) await this.#binding(() => this.binding.deleteByIds(ids));
+    else await this.#req('/delete_by_ids', { ids });
+  }
+
+  // --- reads --------------------------------------------------------------
+
+  async query(vector, opts = {}) {
+    await this.#ensure();
+    const limit = opts.limit ?? 20;
+    // Over-fetch a little (limit*4) but never past the returnMetadata="all" cap.
+    const topK = Math.min(limit * 4, MAX_TOPK);
+    const filter = opts.indexers?.length ? { indexerId: { $in: opts.indexers } } : undefined;
+    const matches = await this.#queryRaw(vector, { topK, filter });
+    return matches.slice(0, limit).map(toResult);
+  }
+
+  /** Raw nearest-neighbour lookup. Normalises the two match-envelope shapes. */
+  async #queryRaw(vector, { topK, filter }) {
+    const values = Array.from(vector);
+    let res;
+    if (this.binding) {
+      res = await this.#binding(() =>
+        this.binding.query(values, {
+          topK,
+          returnValues: false,
+          returnMetadata: 'all',
+          ...(filter ? { filter } : {}),
+        }),
+      );
+    } else {
+      res = await this.#req('/query', {
+        vector: values,
+        topK,
+        returnValues: false,
+        returnMetadata: 'all',
+        ...(filter ? { filter } : {}),
+        ...(this.cfg.namespace ? { namespace: this.cfg.namespace } : {}),
+      });
+    }
+    // Both { matches } and { count, matches } are accepted.
+    return res?.matches || [];
+  }
+}
+
+// --- helpers --------------------------------------------------------------
+
+/**
+ * Vector id: ids must be ≤ 64 bytes. A short docId passes through so it stays
+ * human-readable; a longer one collapses to a deterministic SHA-256 hex (64
+ * chars) so remove(docId) recomputes the same id. The original docId always
+ * lives in metadata regardless (see buildMetadata).
+ */
+async function vectorId(docId) {
+  const bytes = new TextEncoder().encode(docId);
+  if (bytes.length <= 64) return docId;
+  const buf = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
+  return [...buf].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Metadata = routing keys + the flat, primitive user fields Vectorize can index. */
+function buildMetadata(doc) {
+  const md = { docId: doc.id, nodeId: doc.nodeId, indexerId: doc.indexerId };
+  for (const [k, v] of Object.entries(doc.fields || {})) {
+    if (RESERVED.includes(k) || v == null) continue; // never let a field shadow a routing key
+    const t = typeof v;
+    // Vectorize metadata only stores flat primitives; skip nested objects/arrays.
+    if (t === 'string' || t === 'number' || t === 'boolean') md[k] = v;
+  }
+  return md;
+}
+
+/** Map a Vectorize match to the VectorStore result shape (fields = non-reserved metadata). */
+function toResult(m) {
+  const md = m.metadata || {};
+  const fields = {};
+  for (const [k, v] of Object.entries(md)) if (!RESERVED.includes(k)) fields[k] = v;
+  return { docId: md.docId, nodeId: md.nodeId, indexerId: md.indexerId, score: m.score, fields };
+}

package/packages/core/src/sidecar/document.js

@@ -0,0 +1,213 @@
+// The per-file sidecar document — a small CRDT that holds everything mutable and
+// social about a file WITHOUT touching the file bytes: its conversation
+// (threaded comments + reactions), its tags, its per-indexer facet data (scoped
+// to the indexer that produced it), and who's subscribed to the thread.
+//
+// It's designed to live as cold JSON in object storage and be merged whenever
+// it's read-before-write, so two servers (or a stale hot copy vs the cold one)
+// converge without a lock or a conflict. Every field is a CRDT register:
+//   • tags   — LWW-Element-Set (add/remove wins by Lamport stamp)
+//   • facets — per-indexer LWW register
+//   • comments — grow-only map; body edit & deletion are LWW registers; reactions
+//     are an OR-map (per user, per emoji, LWW on/off)
+//   • subscribers — LWW register (subscribed / muted)
+// A Lamport `clock` orders concurrent ops; ties break on the actor id, so merges
+// are deterministic and commutative.
+
+export const SIDECAR_VERSION = 1;
+
+export function emptyDoc(nodeId) {
+  return { v: SIDECAR_VERSION, nodeId, clock: 0, tags: {}, facets: {}, comments: {}, subscribers: {} };
+}
+
+// A stamp orders and tie-breaks a write. Higher clock wins; equal clock → higher
+// actor string wins (arbitrary but total and deterministic).
+function newer(a, b) {
+  if (!a) return false;
+  if (!b) return true;
+  if (a.at !== b.at) return a.at > b.at;
+  return String(a.actor) >= String(b.actor);
+}
+function tick(doc) {
+  doc.clock = (doc.clock || 0) + 1;
+  return doc.clock;
+}
+function stamp(doc, actor, at) {
+  return { at: at ?? tick(doc), actor: actor || 'system' };
+}
+
+// ---- mutators (each returns the affected entity) ---------------------------
+
+export function addComment(doc, { id, parentId = null, author, body, mentions = [], actor, at, ts }) {
+  const s = stamp(doc, actor ?? author?.id, at);
+  const comment = {
+    id, parentId, author, body: { text: body, ...s },
+    // `at` (Lamport) orders/merges; `createdAt` (wall clock) is for display only.
+    mentions, createdAt: ts ?? wallClock(), reactions: {}, deleted: null, ...s,
+  };
+  doc.comments[id] = comment;
+  subscribe(doc, author?.id, { actor: author?.id, at: s.at });
+  return comment;
+}
+
+function wallClock() {
+  try {
+    return Date.now();
+  } catch {
+    return 0;
+  }
+}
+
+export function editComment(doc, id, { body, actor, at }) {
+  const c = doc.comments[id];
+  if (!c) return null;
+  const s = stamp(doc, actor, at);
+  if (newer(s, c.body)) c.body = { text: body, ...s };
+  return c;
+}
+
+export function deleteComment(doc, id, { actor, at } = {}) {
+  const c = doc.comments[id];
+  if (!c) return null;
+  const s = stamp(doc, actor, at);
+  if (newer(s, c.deleted)) c.deleted = s;
+  return c;
+}
+
+export function react(doc, id, emoji, userId, on = true, { at } = {}) {
+  const c = doc.comments[id];
+  if (!c) return null;
+  const s = stamp(doc, userId, at);
+  const map = (c.reactions[emoji] ??= {});
+  const cur = map[userId];
+  if (newer(s, cur)) map[userId] = { on, ...s };
+  return c;
+}
+
+export function setTag(doc, name, { value = true, actor, at } = {}) {
+  const s = stamp(doc, actor, at);
+  const cur = doc.tags[name];
+  if (newer(s, cur)) doc.tags[name] = { present: true, value, ...s };
+  return doc.tags[name];
+}
+export function removeTag(doc, name, { actor, at } = {}) {
+  const s = stamp(doc, actor, at);
+  const cur = doc.tags[name];
+  if (newer(s, cur)) doc.tags[name] = { present: false, value: cur?.value, ...s };
+}
+
+export function setFacet(doc, indexerId, data, { actor, at } = {}) {
+  const s = stamp(doc, actor ?? indexerId, at);
+  const cur = doc.facets[indexerId];
+  if (newer(s, cur)) doc.facets[indexerId] = { data, ...s };
+}
+
+export function subscribe(doc, userId, { muted = false, actor, at } = {}) {
+  if (!userId) return;
+  const s = stamp(doc, actor ?? userId, at);
+  const cur = doc.subscribers[userId];
+  if (newer(s, cur)) doc.subscribers[userId] = { subscribed: true, muted, ...s };
+}
+export function unsubscribe(doc, userId, { actor, at } = {}) {
+  if (!userId) return;
+  const s = stamp(doc, actor ?? userId, at);
+  const cur = doc.subscribers[userId];
+  if (newer(s, cur)) doc.subscribers[userId] = { subscribed: false, muted: cur?.muted, ...s };
+}
+
+// ---- merge (CRDT join) -----------------------------------------------------
+
+export function mergeDoc(a, b) {
+  if (!a) return structuredCloneSafe(b);
+  if (!b) return structuredCloneSafe(a);
+  const out = { v: SIDECAR_VERSION, nodeId: a.nodeId || b.nodeId, clock: Math.max(a.clock || 0, b.clock || 0), tags: {}, facets: {}, comments: {}, subscribers: {} };
+
+  for (const key of union(a.tags, b.tags)) out.tags[key] = pick(a.tags[key], b.tags[key]);
+  for (const key of union(a.facets, b.facets)) out.facets[key] = pick(a.facets[key], b.facets[key]);
+  for (const key of union(a.subscribers, b.subscribers)) out.subscribers[key] = pick(a.subscribers[key], b.subscribers[key]);
+
+  for (const id of union(a.comments, b.comments)) {
+    out.comments[id] = mergeComment(a.comments[id], b.comments[id]);
+  }
+  return out;
+}
+
+function mergeComment(x, y) {
+  if (!x) return structuredCloneSafe(y);
+  if (!y) return structuredCloneSafe(x);
+  const base = newer({ at: x.at, actor: x.actor }, { at: y.at, actor: y.actor }) ? x : y;
+  const out = { ...structuredCloneSafe(base) };
+  out.body = pick(x.body, y.body);
+  out.deleted = pick(x.deleted, y.deleted);
+  out.reactions = {};
+  for (const emoji of union(x.reactions, y.reactions)) {
+    out.reactions[emoji] = {};
+    const users = union(x.reactions?.[emoji], y.reactions?.[emoji]);
+    for (const u of users) out.reactions[emoji][u] = pick(x.reactions?.[emoji]?.[u], y.reactions?.[emoji]?.[u]);
+  }
+  return out;
+}
+
+function pick(a, b) {
+  return newer(a, b) ? a : b;
+}
+function union(a = {}, b = {}) {
+  return new Set([...Object.keys(a || {}), ...Object.keys(b || {})]);
+}
+function structuredCloneSafe(o) {
+  return JSON.parse(JSON.stringify(o));
+}
+
+// ---- view (derive a UI-friendly shape) -------------------------------------
+
+export function viewDoc(doc) {
+  const tags = Object.entries(doc.tags || {})
+    .filter(([, t]) => t.present)
+    .map(([name, t]) => ({ name, value: t.value === true ? null : t.value }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)); // canonical order
+
+  const all = Object.values(doc.comments || {}).map((c) => ({
+    id: c.id, parentId: c.parentId, author: c.author,
+    body: c.deleted ? null : c.body?.text, deleted: !!c.deleted,
+    // Edited iff the body's Lamport stamp advanced past the comment's own.
+    edited: !!c.body && c.body.at !== c.at, createdAt: c.createdAt, at: c.at,
+    mentions: c.mentions || [],
+    reactions: summariseReactions(c.reactions),
+  }));
+  all.sort((x, y) => x.createdAt - y.createdAt || (x.id < y.id ? -1 : 1)); // stable, canonical
+
+  // Thread into a tree.
+  const byId = new Map(all.map((c) => [c.id, { ...c, replies: [] }]));
+  const roots = [];
+  for (const c of byId.values()) {
+    if (c.parentId && byId.has(c.parentId)) byId.get(c.parentId).replies.push(c);
+    else roots.push(c);
+  }
+  const facets = Object.fromEntries(Object.entries(doc.facets || {}).map(([k, v]) => [k, v.data]));
+  const subscribers = Object.entries(doc.subscribers || {}).filter(([, s]) => s.subscribed).map(([id]) => id).sort();
+  return { nodeId: doc.nodeId, tags, comments: roots, commentCount: all.filter((c) => !c.deleted).length, facets, subscribers };
+}
+
+function summariseReactions(reactions = {}) {
+  const out = {};
+  for (const [emoji, users] of Object.entries(reactions)) {
+    const on = Object.entries(users).filter(([, r]) => r.on).map(([u]) => u);
+    if (on.length) out[emoji] = on;
+  }
+  return out;
+}
+
+// Extract mentioned user ids from a body. Supports rich `@[Name](id)` tokens
+// (from a mention picker) and bare `@handle` tokens (handy when the identity is
+// an email/handle and there's no user directory — BYO-IdP deployments).
+export function extractMentions(body) {
+  const ids = new Set();
+  let text = String(body || '');
+  const rich = /@\[[^\]]+\]\(([^)]+)\)/g;
+  let m;
+  while ((m = rich.exec(text))) ids.add(m[1]);
+  text = text.replace(rich, ' '); // remove rich tokens before scanning bare ones
+  const bare = /(?:^|\s)@([a-zA-Z0-9._@-]{2,})/g;
+  while ((m = bare.exec(text))) ids.add(m[1].replace(/[.@-]+$/, ''));
+  return [...ids];
+}

package/packages/core/src/sidecar/index.js

@@ -0,0 +1,174 @@
+// SidecarService — the API surface over sidecar documents: conversations
+// (threaded comments, edits, reactions), tags, per-indexer facets, and thread
+// subscriptions. It resolves the acting Principal into comment authorship,
+// extracts @mentions, auto-subscribes participants, and emits mention events to
+// a callback (wired to the notification batcher). Routes call these methods.
+
+import { SidecarStore } from './store.js';
+import { SidecarManager } from './manager.js';
+import {
+  addComment, editComment, deleteComment, react, setTag, removeTag, setFacet,
+  subscribe, unsubscribe, viewDoc, extractMentions,
+} from './document.js';
+import { newId } from '../util.js';
+import { TroveError } from '../errors.js';
+
+export class SidecarService {
+  /**
+   * @param {object} deps
+   * @param {import('../storage/interface.js').StorageBackend} deps.storage
+   * @param {(mentions: Array) => void} [deps.onMentions]  batch-notify sink
+   * @param {SidecarManager} [deps.manager]
+   * @param {import('../issues.js').IssueRegistry} [deps.issues] so a write-back that
+   *   keeps failing becomes a standing problem rather than a console line
+   */
+  constructor({ storage, onMentions, manager, issues } = {}) {
+    this.store = new SidecarStore({ storage });
+    this.manager = manager ?? new SidecarManager({ store: this.store, issues });
+    this.onMentions = onMentions ?? (() => {});
+  }
+
+  async view(nodeId) {
+    return viewDoc(await this.manager.get(nodeId));
+  }
+
+  /**
+   * Flush and evict idle documents — the maintenance timer's entry point.
+   *
+   * It called `sidecar.sweep?.()`, which did not exist here; the optional call swallowed
+   * it, so nothing ever evicted and every sidecar ever loaded (one per file opened,
+   * commented on, or tagged) stayed resident for the life of the process. Delegating
+   * makes the name the caller already uses the real one.
+   */
+  sweep() {
+    return this.manager.sweep();
+  }
+  /** Write back everything still holding unsaved changes (shutdown). */
+  flushAll() {
+    return this.manager.flushAll();
+  }
+
+  // --- conversation ----------------------------------------------------------
+
+  /**
+   * @param {string} nodeId
+   * @param {{ body: string, parentId?: string, mentions?: string[] }} input
+   * @param {object} principal  { id, name, picture }
+   */
+  async addComment(nodeId, input, principal) {
+    if (!principal?.id) throw TroveError.unauthorized('Sign in to comment');
+    if (!input.body?.trim()) throw TroveError.invalid('Comment body is required');
+    const id = newId('cmt');
+    const author = { id: principal.id, name: principal.name || principal.id, picture: principal.picture || null };
+    const mentions = uniq([...(input.mentions || []), ...extractMentions(input.body)]).filter((m) => m !== principal.id);
+
+    const comment = await this.manager.mutate(nodeId, (doc) => {
+      const c = addComment(doc, { id, parentId: input.parentId || null, author, body: input.body, mentions, actor: principal.id });
+      // Auto-subscribe mentioned users and the parent author to the thread.
+      for (const uid of mentions) subscribe(doc, uid, { actor: principal.id });
+      if (input.parentId && doc.comments[input.parentId]) subscribe(doc, doc.comments[input.parentId].author?.id, { actor: principal.id });
+      return c;
+    });
+
+    if (mentions.length) {
+      this.onMentions(mentions.map((userId) => ({
+        userId, nodeId, commentId: id, by: author, at: Date.now(),
+        excerpt: excerpt(input.body),
+      })));
+    }
+    return this.#commentView(nodeId, comment.id);
+  }
+
+  async editComment(nodeId, commentId, body, principal) {
+    await this.#assertAuthor(nodeId, commentId, principal);
+    await this.manager.mutate(nodeId, (doc) => editComment(doc, commentId, { body, actor: principal.id }));
+    return this.#commentView(nodeId, commentId);
+  }
+
+  async deleteComment(nodeId, commentId, principal) {
+    await this.#assertAuthor(nodeId, commentId, principal);
+    await this.manager.mutate(nodeId, (doc) => deleteComment(doc, commentId, { actor: principal.id }));
+    return { ok: true };
+  }
+
+  async react(nodeId, commentId, emoji, on, principal) {
+    if (!principal?.id) throw TroveError.unauthorized('Sign in to react');
+    await this.manager.mutate(nodeId, (doc) => react(doc, commentId, emoji, principal.id, on));
+    return this.#commentView(nodeId, commentId);
+  }
+
+  // --- tags ------------------------------------------------------------------
+
+  async setTag(nodeId, name, value, principal) {
+    await this.manager.mutate(nodeId, (doc) => setTag(doc, name, { value: value ?? true, actor: principal?.id }));
+    return this.view(nodeId);
+  }
+  async removeTag(nodeId, name, principal) {
+    await this.manager.mutate(nodeId, (doc) => removeTag(doc, name, { actor: principal?.id }));
+    return this.view(nodeId);
+  }
+
+  // --- facets (indexer-scoped) ----------------------------------------------
+
+  /** Write an indexer's facet into the sidecar, namespaced under indexerId. */
+  async setFacet(nodeId, indexerId, data) {
+    await this.manager.mutate(nodeId, (doc) => setFacet(doc, indexerId, data, { actor: indexerId }));
+    return { ok: true };
+  }
+
+  // --- subscriptions ---------------------------------------------------------
+
+  async subscribe(nodeId, principal, muted = false) {
+    if (!principal?.id) throw TroveError.unauthorized('Sign in to follow');
+    await this.manager.mutate(nodeId, (doc) => subscribe(doc, principal.id, { muted, actor: principal.id }));
+    return { ok: true };
+  }
+  async unsubscribe(nodeId, principal) {
+    if (!principal?.id) throw TroveError.unauthorized('Sign in');
+    await this.manager.mutate(nodeId, (doc) => unsubscribe(doc, principal.id, { actor: principal.id }));
+    return { ok: true };
+  }
+
+  /** Delete a file's sidecar (called when the file is deleted). */
+  async remove(nodeId) {
+    await this.store.remove(nodeId);
+    this.manager.hot.delete(nodeId);
+  }
+
+  async dispose() {
+    await this.manager.dispose();
+  }
+
+  // --- helpers ---------------------------------------------------------------
+
+  async #assertAuthor(nodeId, commentId, principal) {
+    if (!principal?.id) throw TroveError.unauthorized('Sign in');
+    const doc = await this.manager.get(nodeId);
+    const c = doc.comments[commentId];
+    if (!c) throw TroveError.notFound('Comment');
+    if (c.author?.id !== principal.id) throw TroveError.forbidden('You can only edit your own comments');
+  }
+
+  async #commentView(nodeId, commentId) {
+    const view = viewDoc(await this.manager.get(nodeId));
+    const find = (list) => {
+      for (const c of list) {
+        if (c.id === commentId) return c;
+        const inner = find(c.replies || []);
+        if (inner) return inner;
+      }
+      return null;
+    };
+    return find(view.comments) || { id: commentId };
+  }
+}
+
+function uniq(arr) {
+  return [...new Set(arr)];
+}
+function excerpt(body, n = 140) {
+  const clean = body.replace(/@\[([^\]]+)\]\([^)]+\)/g, '@$1').replace(/\s+/g, ' ').trim();
+  return clean.length > n ? clean.slice(0, n) + '…' : clean;
+}
+
+export { SidecarStore, SidecarManager };