agentic-comments 0.6.1 → 0.8.0

package/dist/{chunk-VAVKBAHM.js → chunk-4G5BDTBA.js}

@@ -1,16 +1,13 @@
 // src/errors.ts
 var CommentsError = class extends Error {
-  constructor(code, message) {
-    super(message);
+  constructor(code, message, options) {
+    super(message, options);
     this.code = code;
     this.name = "CommentsError";
   }
   code;
 };
 
-// src/anchor.ts
-import * as Y from "yjs";
-
 // src/text.ts
 var HIDDEN = /[\p{Cc}\p{Cf}]/u;
 var ID = /^[\w-]{1,64}$/;
@@ -21,6 +18,7 @@ var shown = (value) => JSON.stringify(safeId(value));
 var safeText = (value) => String(value).replace(/[^\p{L}\p{N}\p{P}\p{S} ]/gu, "?").slice(0, 200);
 
 // src/anchor.ts
+import * as Y from "yjs";
 var MAX_QUOTE = 2e3;
 var MAX_ANCHOR = 4096;
 var MAX_KEY = 256;
@@ -180,521 +178,179 @@ var strictCopy = (value) => JSON.parse(
   })
 );
 
-// src/suggestions.ts
+// src/threads.ts
 import * as Y2 from "yjs";
-var ACCEPT_SCOPE = "comments:accept";
-var MAX_CHANGE = 64e3;
-var MAX_RECEIPT = 16e3;
-var MAX_SUMMARY = 1e3;
-var SUGGESTIONS = "comments.suggestions";
-var APPLIED = "comments.suggestion-applied";
-var REJECTED = "comments.suggestion-rejected";
-var decidesOwn = (author, decider) => author.name !== ERASED_NAME && author.kind !== "human" && decider.kind !== "human" && author.name === decider.name;
-var clientOf = (text) => /^(0|[1-9]\d{0,9})$/.test(text) && Number(text) <= 4294967295 ? Number(text) : void 0;
-var thenable = (value) => typeof value?.then === "function";
-var Suggestions = class {
-  constructor(comments, host) {
-    this.comments = comments;
-    this.host = host;
-    if (typeof host?.apply !== "function" || typeof host.revert !== "function" && host.idempotent !== true) {
-      invalid("a host needs apply, and either revert or idempotent: true, so two accepts at once cannot apply a change twice");
-    }
-    void [this.map, this.applied, this.rejected];
-    this.onTransaction = (tr) => {
-      if (!tr.local && [this.applied, this.map].some((type) => tr.changedParentTypes.has(type))) this.settle();
-    };
-    this.ydoc.on("afterTransaction", this.onTransaction);
-    this.settle();
+var MODERATE_SCOPE = "comments:moderate";
+var ERASED_BODY = "[erased]";
+var THREADS = "comments.threads";
+var MAX_BODY = 1e4;
+var MAX_MENTIONS = 50;
+var MAX_MESSAGES = 1e3;
+var READ_LIMIT = 2 * MAX_MESSAGES;
+var STATUSES = ["open", "resolved"];
+var ANCHOR_STATES = ["attached", "edited", "orphaned", "unknown"];
+var HANDLE = /^[\p{L}\p{N}](?:[\p{L}\p{N}\p{M}_.-]{0,62}[\p{L}\p{N}\p{M}])?$/u;
+var MENTION = /(?<![\p{L}\p{N}_@.])@([\p{L}\p{N}][\p{L}\p{N}\p{M}_.-]*)(?![\p{L}\p{N}\p{M}_.-]|\/)/gu;
+function body(value) {
+  if (typeof value !== "string" || value.trim() === "" || value.length > MAX_BODY || BODY_FORBIDDEN.test(value)) {
+    invalid(`a body must be text of 1 to ${MAX_BODY} characters, with no control, invisible, or direction characters`);
   }
-  comments;
-  host;
-  onTransaction;
-  failures = [];
-  /** Stop listening to the document. */
-  close() {
-    this.ydoc.off("afterTransaction", this.onTransaction);
+  return value;
+}
+var handle = (value) => value.normalize("NFC").replace(/^@+/, "").toLowerCase().normalize("NFC");
+var okHandle = (value) => HANDLE.test(value) && !VARIATION.test(value);
+var validHandle = (value) => typeof value === "string" && okHandle(value) && handle(value) === value;
+function mentionsOf(text, explicit) {
+  const prose = text.replace(/`[^`]*`/g, " ");
+  const found = [...prose.matchAll(MENTION)].map((m) => {
+    const name = m[1].replace(/[._-]+$/, "");
+    if (!okHandle(handle(name))) invalid(`"@${name.slice(0, 20)}" is not a valid handle: use up to 64 characters`);
+    return handle(name);
+  });
+  let listed = [];
+  if (explicit !== void 0) {
+    const snapshot = Array.isArray(explicit) ? Array.from(explicit) : [];
+    const ok = Array.isArray(explicit) && snapshot.length <= MAX_MENTIONS && snapshot.every((m) => typeof m === "string" && okHandle(handle(m)));
+    if (!ok) invalid(`mentions must be a list of up to ${MAX_MENTIONS} handles of letters, digits, and . _ -`);
+    listed = snapshot.map(handle);
   }
-  get ydoc() {
-    return this.comments.ydoc;
+  const all = [.../* @__PURE__ */ new Set([...found, ...listed])];
+  if (all.length > MAX_MENTIONS) invalid(`a message can mention up to ${MAX_MENTIONS} handles`);
+  return all;
+}
+var Comments = class {
+  /** Every replica of a document must register the same custom anchor kinds. Others read those threads as malformed. */
+  constructor(ydoc, options = {}) {
+    this.ydoc = ydoc;
+    if (typeof options !== "object" || options === null || options.now !== void 0 && typeof options.now !== "function" || options.anchors !== void 0 && !Array.isArray(options.anchors) || options.exists !== void 0 && typeof options.exists !== "function") {
+      invalid("options must be an object with an optional now function, anchors list, and exists function");
+    }
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.exists = options.exists;
+    for (const kind of [...BUILT_IN_KINDS, ...options.anchors ?? []]) {
+      if (typeof kind?.type !== "string" || kind.type === "" || typeof kind.parse !== "function" || this.kinds.has(kind.type)) {
+        throw new CommentsError("INVALID_ANCHOR", `the anchor type "${String(kind?.type)}" is empty, has no parse, or is already defined`);
+      }
+      this.kinds.set(kind.type, kind);
+    }
   }
+  ydoc;
+  kinds = /* @__PURE__ */ new Map();
+  now;
+  exists;
   get map() {
-    return this.ydoc.getMap(SUGGESTIONS);
+    return this.ydoc.getMap(THREADS);
   }
-  /** The three Yjs maps that hold suggestions and their decisions. `Notifications` watches them. */
-  get maps() {
-    return { suggestions: this.map, applied: this.applied, rejected: this.rejected };
+  /** The Yjs map that holds the threads. `Notifications` watches it. */
+  get threadsMap() {
+    return this.map;
   }
-  get applied() {
-    return this.ydoc.getMap(APPLIED);
+  /** The clock, as an ISO time. Used by `Suggestions`. */
+  time() {
+    const at = this.now();
+    const text = at instanceof Date && !Number.isNaN(at.getTime()) ? at.toISOString() : "";
+    if (!ISO_TIME.test(text)) invalid("the clock must return a date between the years 0000 and 9999");
+    return text;
   }
-  get rejected() {
-    return this.ydoc.getMap(REJECTED);
+  /** Whether the content under an anchor is still there. This never throws. */
+  anchorState(anchor) {
+    if (anchor.type === "text") return textState(anchor, this.ydoc);
+    if (!this.exists) return { state: "unknown" };
+    try {
+      const answer = this.exists(anchor);
+      return answer === true ? { state: "attached" } : answer === false ? { state: "orphaned" } : { state: "unknown" };
+    } catch {
+      return { state: "unknown" };
+    }
   }
-  change(raw, anchor) {
-    let clean;
+  /** Read an anchor from stored data. This does not check the document. */
+  parseAnchor(raw) {
+    const type = raw?.type;
+    const kind = typeof raw === "object" && raw !== null && !Array.isArray(raw) && typeof type === "string" ? this.kinds.get(type) : void 0;
+    if (!kind) throw new CommentsError("INVALID_ANCHOR", `an anchor needs a type: ${[...this.kinds.keys()].join(", ")}`);
     try {
-      clean = strictCopy(raw);
-      if (this.host.parse) clean = strictCopy(this.host.parse(copy(clean), { anchor: copy(anchor) }));
+      const parsed = copy(kind.parse(strictCopy(raw)));
+      if (JSON.stringify(parsed).length > MAX_ANCHOR) throw new Error(`an anchor holds up to ${MAX_ANCHOR} characters of JSON`);
+      if (parsed?.type !== kind.type) throw new Error(`the "${kind.type}" kind must return an anchor of its own type`);
+      return parsed;
     } catch (error) {
-      return invalid(`the change is refused: ${safeText(error instanceof Error ? error.message : error)}`);
+      if (error instanceof CommentsError) throw error;
+      throw new CommentsError("INVALID_ANCHOR", error instanceof Error ? error.message : String(error));
     }
-    if (JSON.stringify(clean).length > MAX_CHANGE) invalid(`a change holds up to ${MAX_CHANGE} characters of JSON`);
-    return clean;
   }
-  /**
-   * Records of one kind for one suggestion, in client order. A record that is not valid is not counted:
-   * one with no author or time, a receipt that is not small JSON, or a decider who decided their own work.
-   */
-  records(entries, id2, author) {
-    const out = [];
-    for (const [key2, raw] of entries) {
-      const client = clientOf(key2.slice(id2.length + 1));
-      const r = raw ?? {};
-      const by = readAuthor(r.by);
-      if (client === void 0 || !by || !validDate(r.at) || !author || decidesOwn(author, by)) continue;
-      let receipt = null;
+  /** Parse an anchor from input and check it against this document. Throws `INVALID_ANCHOR` when it fails. */
+  checkAnchor(raw) {
+    const anchor = this.parseAnchor(raw);
+    if (JSON.stringify(this.parseAnchor(anchor)) !== JSON.stringify(anchor)) {
+      throw new CommentsError("INVALID_ANCHOR", "an anchor kind must parse its own output to the same anchor");
+    }
+    this.checkInDocument(anchor);
+    return anchor;
+  }
+  /** A text anchor must name text in this document, in order, and match its quote. */
+  checkInDocument(anchor) {
+    if (anchor.type !== "text") return;
+    const at = (json) => {
       try {
-        receipt = r.receipt === void 0 ? null : strictCopy(r.receipt);
-        if (JSON.stringify(receipt).length > MAX_RECEIPT) continue;
+        return Y2.createAbsolutePositionFromRelativePosition(Y2.createRelativePositionFromJSON(json), this.ydoc);
       } catch {
-        continue;
+        return null;
       }
-      out.push({ client, by, at: r.at, receipt });
-    }
-    return out.sort((a, b) => Number(a.receipt !== null) - Number(b.receipt !== null) || a.client - b.client);
-  }
-  /** Group the entries of a decision map by suggestion id in one pass, so a read does not scan the map per suggestion. */
-  index(map) {
-    const groups = /* @__PURE__ */ new Map();
-    for (const entry of map.entries()) {
-      const id2 = entry[0].slice(0, entry[0].lastIndexOf(":"));
-      const group = groups.get(id2);
-      if (group) group.push(entry);
-      else groups.set(id2, [entry]);
+    };
+    const from = at(anchor.start);
+    const to = at(anchor.end);
+    const unit = from?.type;
+    if (!(unit instanceof Y2.Text) || !from || !to || to.type !== unit || to.index <= from.index || textOf(unit).slice(from.index, to.index) !== anchor.text) {
+      throw new CommentsError("INVALID_ANCHOR", "a text anchor must name text in this document, in order, matching its quoted text");
     }
-    return groups;
   }
-  read(id2, fields, indexes = { applied: this.index(this.applied), rejected: this.index(this.rejected) }) {
+  /** Build a message, and refuse it unless a read would show it back. Nothing is written yet. */
+  message(text, explicit, actor) {
+    const message = {
+      id: globalThis.crypto.randomUUID(),
+      at: this.time(),
+      author: { kind: actor.kind, name: actor.name },
+      body: text,
+      mentions: mentionsOf(text, explicit)
+    };
     try {
-      if (!ID.test(id2)) throw new Error("the suggestion id is not short and plain");
-      if (!(fields instanceof Y2.Map)) throw new Error("the suggestion is not a map");
-      const author = readAuthor(fields.get("author"));
-      const createdAt = fields.get("createdAt");
-      const summary = fields.get("summary");
-      const change = fields.get("change");
-      if (!author || !validDate(createdAt)) throw new Error("the suggestion has no valid author or time");
-      if (summary !== void 0 && !(typeof summary === "string" && summary.trim() !== "" && summary.length <= MAX_SUMMARY && !BODY_FORBIDDEN.test(summary))) {
-        throw new Error("the summary is not valid");
-      }
-      if (change === void 0 || JSON.stringify(strictCopy(change)).length > MAX_CHANGE) throw new Error("the change is missing or too large");
-      const won = this.records(indexes.applied.get(id2) ?? [], id2, author)[0];
-      const refused = this.records(indexes.rejected.get(id2) ?? [], id2, author)[0];
-      const decision = won ? { status: "accepted", ...won } : refused ? { status: "rejected", ...refused } : void 0;
-      const anchor = this.comments.parseAnchor(fields.get("anchor"));
-      return {
-        id: id2,
-        anchor,
-        anchorState: this.comments.anchorState(anchor),
-        change: copy(change),
-        ...summary === void 0 ? {} : { summary },
-        author,
-        createdAt,
-        status: decision?.status ?? "pending",
-        ...decision ? { decidedBy: decision.by, decidedAt: decision.at } : {}
-      };
+      return this.readMessage(copy(message));
     } catch (error) {
-      throw new CommentsError("CORRUPT", `suggestion ${shown(id2)} is malformed: ${safeText(error instanceof Error ? error.message : error)}`);
+      return invalid(`the message cannot be stored: ${error.message}`);
     }
   }
-  fields(id2) {
-    if (typeof id2 !== "string" || !ID.test(id2) || !this.map.has(id2)) throw new CommentsError("NO_SUGGESTION", `no suggestion with id ${shown(id2)}`);
-    return { id: id2, fields: this.map.get(id2) };
-  }
-  /**
-   * The suggestions a person wrote, and the decisions they made, in this document. `unread` counts stored
-   * suggestions and decision records with their name that this export cannot show: a suggestion that cannot
-   * be read, a decision that lost a merge, a refused decision, or a decision with no suggestion. When it is not
-   * 0 the export is not complete. A person may export their own data.
-   */
-  exportPerson(person, actor) {
-    const { match } = this.comments.checkPerson(person, actor);
-    const all = this.list();
-    const authored = all.filter((s) => match(s.author));
-    const decided = all.flatMap((s) => s.decidedBy && s.decidedAt && s.status !== "pending" && match(s.decidedBy) ? [{ id: s.id, status: s.status, at: s.decidedAt }] : []);
-    let found = 0;
-    for (const fields of this.map.values()) if (fields instanceof Y2.Map && this.named(fields.get("author"), match)) found++;
-    for (const map of [this.applied, this.rejected]) for (const raw of map.values()) if (this.named(raw?.by, match)) found++;
-    return { authored, decided, unread: Math.max(0, found - authored.length - decided.length) };
-  }
-  named(value, match) {
-    const author = readAuthor(value);
-    return author !== void 0 && match(author);
-  }
-  /**
-   * Give every suggestion a person wrote a tombstone author and drop its summary. An accepted one keeps its
-   * change, because that change is already part of the content. A pending or rejected one loses its change, and
-   * can no longer be accepted. A decision they made gets a tombstone decider. A decision that a read refuses (a
-   * principal that decided its own work) is deleted, so erase never turns it into a valid one. Returns how many
-   * suggestions and decisions it changed.
-   */
-  erasePerson(person, actor) {
-    const { match } = this.comments.checkPerson(person, actor);
-    const out = { suggestions: 0, decisions: 0 };
-    const authors = /* @__PURE__ */ new Map();
-    for (const [id2, fields] of this.map.entries()) {
-      const author = fields instanceof Y2.Map ? readAuthor(fields.get("author")) : void 0;
-      if (author) authors.set(id2, author);
-    }
-    const status = new Map(this.list().map((s) => [s.id, s.status]));
-    this.ydoc.transact(() => {
-      for (const map of [this.applied, this.rejected]) {
-        for (const [key2, raw] of [...map.entries()]) {
-          const by = readAuthor(raw?.by);
-          const author = authors.get(key2.slice(0, key2.lastIndexOf(":")));
-          if (!by || !(match(by) || author && match(author))) continue;
-          if (author && decidesOwn(author, by)) map.delete(key2);
-          else if (match(by)) {
-            map.set(key2, { ...raw, by: { kind: by.kind, name: ERASED_NAME } });
-            out.decisions++;
-          }
-        }
-      }
-      for (const [id2, author] of authors) {
-        if (!match(author)) continue;
-        const fields = this.map.get(id2);
-        fields.set("author", { kind: author.kind, name: ERASED_NAME });
-        fields.delete("summary");
-        if (status.get(id2) !== "accepted") fields.set("change", null);
-        out.suggestions++;
-      }
-    });
-    return out;
-  }
-  /** Propose a change. Anyone can suggest. The host stamps the author. */
-  add(input, actor) {
-    const who = assertActor(actor);
-    const given = exact(input, ["anchor", "change", "summary"], "a new suggestion");
-    const anchor = this.comments.checkAnchor(given.anchor);
-    const change = this.change(given.change, anchor);
-    const summary = given.summary;
-    if (summary !== void 0 && !(typeof summary === "string" && summary.trim() !== "" && summary.length <= MAX_SUMMARY && !BODY_FORBIDDEN.test(summary))) {
-      invalid(`a summary must be text of 1 to ${MAX_SUMMARY} characters, with no control or invisible characters`);
-    }
-    const id2 = globalThis.crypto.randomUUID();
-    const createdAt = this.comments.time();
-    this.ydoc.transact(() => {
-      const fields = new Y2.Map();
-      this.map.set(id2, fields);
-      fields.set("anchor", anchor);
-      fields.set("change", change);
-      if (summary !== void 0) fields.set("summary", summary);
-      fields.set("author", { kind: who.kind, name: who.name });
-      fields.set("createdAt", createdAt);
-    });
-    return this.get(id2);
-  }
-  /** A person decides. An agent needs the accept scope, and never decides its own suggestion. */
-  mayDecide(who, s, verb) {
-    const ok = !decidesOwn(s.author, who) && (who.kind === "human" || who.scopes.includes(ACCEPT_SCOPE));
-    if (!ok) throw new CommentsError("FORBIDDEN", `${who.kind}:${shown(who.name)} cannot ${verb} this suggestion: a signed-in person, or a principal with the ${ACCEPT_SCOPE} scope that did not write it, can`);
-    if (verb === "accept" && s.author.name === ERASED_NAME && s.status !== "accepted") throw new CommentsError("FORBIDDEN", "an erased suggestion has no change left and cannot be accepted");
-  }
-  /**
-   * Apply the change as the accepting author and record the decision, in one step. Accepting an
-   * accepted suggestion changes nothing. When `apply` throws, the suggestion stays pending.
-   */
-  accept(suggestionId, actor) {
-    const who = assertActor(actor);
-    if (this.ydoc._transaction !== null) {
-      throw new CommentsError("APPLY_FAILED", "accept cannot run inside another Yjs transaction, such as an observer or an apply hook");
-    }
-    const { id: id2, fields } = this.fields(suggestionId);
-    const s = this.read(id2, fields);
-    this.mayDecide(who, s, "accept");
-    if (s.status === "accepted") return s;
-    if (s.status === "rejected") throw new CommentsError("ALREADY_DECIDED", `suggestion ${shown(id2)} is already rejected`);
-    const by = { kind: who.kind, name: who.name };
-    const at = this.comments.time();
-    this.ydoc.transact((tr) => {
-      const edited = () => tr.changed.size > 0 || tr.deleteSet.clients.size > 0;
-      let receipt = null;
-      let failure;
-      try {
-        if (s.anchorState.state === "orphaned" || s.anchorState.state === "edited") {
-          throw new Error(s.anchorState.state === "orphaned" ? "the anchored content is gone" : "the anchored content has changed since the suggestion was made");
-        }
-        this.comments.checkAnchor(s.anchor);
-        const change = this.change(s.change, s.anchor);
-        receipt = this.host.apply(change, { suggestionId: id2, anchor: copy(s.anchor), author: Object.freeze({ ...s.author }), by: Object.freeze({ ...by }), ydoc: this.ydoc });
-        if (thenable(receipt)) throw new Error("apply must finish at once and cannot return a promise");
-        receipt = receipt === void 0 ? null : strictCopy(receipt);
-        if (JSON.stringify(receipt).length > MAX_RECEIPT) throw new Error(`a receipt holds up to ${MAX_RECEIPT} characters of JSON`);
-      } catch (error) {
-        failure = error;
-        receipt = null;
-      }
-      if (failure !== void 0) {
-        const reason = safeText(failure instanceof Error ? failure.message : failure);
-        if (!edited()) throw new CommentsError("APPLY_FAILED", `the change could not be applied: ${reason}`);
-        this.failures.push({ id: safeId(id2), reason: `apply failed after it edited the document, so the decision is recorded without a receipt: ${reason}` });
-      }
-      this.applied.set(`${id2}:${this.ydoc.clientID}`, { by, at, receipt });
-    });
-    return this.get(id2);
-  }
-  /** Same right as accept. A person can withdraw their own suggestion. */
-  reject(suggestionId, actor) {
-    const who = assertActor(actor);
-    const { id: id2, fields } = this.fields(suggestionId);
-    const s = this.read(id2, fields);
-    this.mayDecide(who, s, "reject");
-    if (s.status === "rejected") return s;
-    if (s.status === "accepted") throw new CommentsError("ALREADY_DECIDED", `suggestion ${shown(id2)} is already accepted`);
-    this.rejected.set(`${id2}:${this.ydoc.clientID}`, { by: { kind: who.kind, name: who.name }, at: this.comments.time() });
-    return this.get(id2);
-  }
-  get(suggestionId) {
-    const { id: id2, fields } = this.fields(suggestionId);
-    return this.read(id2, fields);
-  }
-  /** In the order they were made. A malformed suggestion is skipped, and `problems()` names it. */
-  list(filter = {}) {
-    const given = exact(filter, ["status", "anchorState"], "a filter");
-    if (given.anchorState !== void 0 && !["attached", "edited", "orphaned", "unknown"].includes(given.anchorState)) invalid("anchorState must be attached, edited, orphaned, or unknown");
-    if (given.status !== void 0 && !["pending", "accepted", "rejected"].includes(given.status)) invalid("status must be pending, accepted, or rejected");
-    return this.readAll().suggestions.filter((s) => given.status === void 0 || s.status === given.status).filter((s) => given.anchorState === void 0 || s.anchorState.state === given.anchorState).sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-  }
-  /** Suggestions that could not be read, and reverts that failed. */
-  problems() {
-    return [...this.readAll().problems, ...this.failures];
-  }
-  readAll() {
-    const suggestions = [];
-    const problems = [];
-    const indexes = { applied: this.index(this.applied), rejected: this.index(this.rejected) };
-    for (const [id2, fields] of this.map.entries()) {
-      try {
-        suggestions.push(this.read(id2, fields, indexes));
-      } catch (error) {
-        problems.push({ id: safeId(id2), reason: error.message });
-      }
-    }
-    return { suggestions, problems };
-  }
-  /**
-   * Two replicas can accept one suggestion before they meet. After a merge, the application of the
-   * lowest client id stays, and the host reverts each other one. Every replica reaches the same result.
-   * A revert that throws leaves its record, so the next merge tries again.
-   */
-  settle() {
-    const groups = this.index(this.applied);
-    const indexes = { applied: groups, rejected: this.index(this.rejected) };
-    this.failures = this.failures.filter((f) => f.reason.startsWith("apply failed") || f.reason.startsWith("a duplicate application has no receipt"));
-    this.ydoc.transact(() => {
-      for (const [id2, entries] of groups) {
-        if (entries.length < 2 || !ID.test(id2) || !this.map.has(id2)) continue;
-        let s;
-        try {
-          s = this.read(id2, this.map.get(id2), indexes);
-        } catch {
-          continue;
-        }
-        for (const loser of this.records(entries, id2, s.author).slice(1)) {
-          const key2 = `${id2}:${loser.client}`;
-          if (this.host.idempotent) {
-            this.applied.delete(key2);
-            continue;
-          }
-          if (loser.receipt === null) {
-            this.failures.push({ id: safeId(id2), reason: "a duplicate application has no receipt, so its edit cannot be undone and stays in the document" });
-            this.applied.delete(key2);
-            continue;
-          }
-          try {
-            this.host.revert?.(loser.receipt, { suggestionId: id2, anchor: copy(s.anchor), author: Object.freeze({ ...s.author }), by: Object.freeze({ ...loser.by }), ydoc: this.ydoc });
-            this.applied.delete(key2);
-          } catch (error) {
-            this.failures.push({ id: safeId(id2), reason: `a duplicate application could not be reverted: ${safeText(error instanceof Error ? error.message : error)}` });
-          }
-        }
-      }
-    });
-  }
-};
-
-// src/threads.ts
-import * as Y3 from "yjs";
-var MODERATE_SCOPE = "comments:moderate";
-var ERASED_BODY = "[erased]";
-var THREADS = "comments.threads";
-var MAX_BODY = 1e4;
-var MAX_MENTIONS = 50;
-var MAX_MESSAGES = 1e3;
-var READ_LIMIT = 2 * MAX_MESSAGES;
-var STATUSES = ["open", "resolved"];
-var ANCHOR_STATES = ["attached", "edited", "orphaned", "unknown"];
-var HANDLE = /^[\p{L}\p{N}](?:[\p{L}\p{N}\p{M}_.-]{0,62}[\p{L}\p{N}\p{M}])?$/u;
-var MENTION = /(?<![\p{L}\p{N}_@.])@([\p{L}\p{N}][\p{L}\p{N}\p{M}_.-]*)(?![\p{L}\p{N}\p{M}_.-]|\/)/gu;
-function body(value) {
-  if (typeof value !== "string" || value.trim() === "" || value.length > MAX_BODY || BODY_FORBIDDEN.test(value)) {
-    invalid(`a body must be text of 1 to ${MAX_BODY} characters, with no control, invisible, or direction characters`);
-  }
-  return value;
-}
-var handle = (value) => value.normalize("NFC").replace(/^@+/, "").toLowerCase().normalize("NFC");
-var okHandle = (value) => HANDLE.test(value) && !VARIATION.test(value);
-var validHandle = (value) => typeof value === "string" && okHandle(value) && handle(value) === value;
-function mentionsOf(text, explicit) {
-  const prose = text.replace(/`[^`]*`/g, " ");
-  const found = [...prose.matchAll(MENTION)].map((m) => {
-    const name = m[1].replace(/[._-]+$/, "");
-    if (!okHandle(handle(name))) invalid(`"@${name.slice(0, 20)}" is not a valid handle: use up to 64 characters`);
-    return handle(name);
-  });
-  let listed = [];
-  if (explicit !== void 0) {
-    const snapshot = Array.isArray(explicit) ? Array.from(explicit) : [];
-    const ok = Array.isArray(explicit) && snapshot.length <= MAX_MENTIONS && snapshot.every((m) => typeof m === "string" && okHandle(handle(m)));
-    if (!ok) invalid(`mentions must be a list of up to ${MAX_MENTIONS} handles of letters, digits, and . _ -`);
-    listed = snapshot.map(handle);
-  }
-  const all = [.../* @__PURE__ */ new Set([...found, ...listed])];
-  if (all.length > MAX_MENTIONS) invalid(`a message can mention up to ${MAX_MENTIONS} handles`);
-  return all;
-}
-var Comments = class {
-  /** Every replica of a document must register the same custom anchor kinds. Others read those threads as malformed. */
-  constructor(ydoc, options = {}) {
-    this.ydoc = ydoc;
-    if (typeof options !== "object" || options === null || options.now !== void 0 && typeof options.now !== "function" || options.anchors !== void 0 && !Array.isArray(options.anchors) || options.exists !== void 0 && typeof options.exists !== "function") {
-      invalid("options must be an object with an optional now function, anchors list, and exists function");
-    }
-    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
-    this.exists = options.exists;
-    for (const kind of [...BUILT_IN_KINDS, ...options.anchors ?? []]) {
-      if (typeof kind?.type !== "string" || kind.type === "" || typeof kind.parse !== "function" || this.kinds.has(kind.type)) {
-        throw new CommentsError("INVALID_ANCHOR", `the anchor type "${String(kind?.type)}" is empty, has no parse, or is already defined`);
-      }
-      this.kinds.set(kind.type, kind);
-    }
-  }
-  ydoc;
-  kinds = /* @__PURE__ */ new Map();
-  now;
-  exists;
-  get map() {
-    return this.ydoc.getMap(THREADS);
-  }
-  /** The Yjs map that holds the threads. `Notifications` watches it. */
-  get threadsMap() {
-    return this.map;
-  }
-  /** The clock, as an ISO time. Used by `Suggestions`. */
-  time() {
-    const at = this.now();
-    const text = at instanceof Date && !Number.isNaN(at.getTime()) ? at.toISOString() : "";
-    if (!ISO_TIME.test(text)) invalid("the clock must return a date between the years 0000 and 9999");
-    return text;
-  }
-  /** Whether the content under an anchor is still there. This never throws. */
-  anchorState(anchor) {
-    if (anchor.type === "text") return textState(anchor, this.ydoc);
-    if (!this.exists) return { state: "unknown" };
-    try {
-      const answer = this.exists(anchor);
-      return answer === true ? { state: "attached" } : answer === false ? { state: "orphaned" } : { state: "unknown" };
-    } catch {
-      return { state: "unknown" };
-    }
-  }
-  /** Read an anchor from stored data. This does not check the document. */
-  parseAnchor(raw) {
-    const type = raw?.type;
-    const kind = typeof raw === "object" && raw !== null && !Array.isArray(raw) && typeof type === "string" ? this.kinds.get(type) : void 0;
-    if (!kind) throw new CommentsError("INVALID_ANCHOR", `an anchor needs a type: ${[...this.kinds.keys()].join(", ")}`);
-    try {
-      const parsed = copy(kind.parse(strictCopy(raw)));
-      if (JSON.stringify(parsed).length > MAX_ANCHOR) throw new Error(`an anchor holds up to ${MAX_ANCHOR} characters of JSON`);
-      if (parsed?.type !== kind.type) throw new Error(`the "${kind.type}" kind must return an anchor of its own type`);
-      return parsed;
-    } catch (error) {
-      if (error instanceof CommentsError) throw error;
-      throw new CommentsError("INVALID_ANCHOR", error instanceof Error ? error.message : String(error));
-    }
-  }
-  /** Parse an anchor from input and check it against this document. Throws `INVALID_ANCHOR` when it fails. */
-  checkAnchor(raw) {
-    const anchor = this.parseAnchor(raw);
-    if (JSON.stringify(this.parseAnchor(anchor)) !== JSON.stringify(anchor)) {
-      throw new CommentsError("INVALID_ANCHOR", "an anchor kind must parse its own output to the same anchor");
-    }
-    this.checkInDocument(anchor);
-    return anchor;
-  }
-  /** A text anchor must name text in this document, in order, and match its quote. */
-  checkInDocument(anchor) {
-    if (anchor.type !== "text") return;
-    const at = (json) => {
-      try {
-        return Y3.createAbsolutePositionFromRelativePosition(Y3.createRelativePositionFromJSON(json), this.ydoc);
-      } catch {
-        return null;
-      }
-    };
-    const from = at(anchor.start);
-    const to = at(anchor.end);
-    const unit = from?.type;
-    if (!(unit instanceof Y3.Text) || !from || !to || to.type !== unit || to.index <= from.index || textOf(unit).slice(from.index, to.index) !== anchor.text) {
-      throw new CommentsError("INVALID_ANCHOR", "a text anchor must name text in this document, in order, matching its quoted text");
-    }
-  }
-  /** Build a message, and refuse it unless a read would show it back. Nothing is written yet. */
-  message(text, explicit, actor) {
-    const message = {
-      id: globalThis.crypto.randomUUID(),
-      at: this.time(),
-      author: { kind: actor.kind, name: actor.name },
-      body: text,
-      mentions: mentionsOf(text, explicit)
-    };
-    try {
-      return this.readMessage(copy(message));
-    } catch (error) {
-      return invalid(`the message cannot be stored: ${error.message}`);
-    }
-  }
-  readMessage(raw) {
-    const m = raw ?? {};
-    const author = readAuthor(m.author);
-    if (typeof m.id !== "string" || !ID.test(m.id) || !validDate(m.at) || !author || typeof m.body !== "string" || m.body.trim() === "" || m.body.length > MAX_BODY || BODY_FORBIDDEN.test(m.body)) {
-      throw new Error("a message has no id, ISO time, valid author, or body");
-    }
-    if (!Array.isArray(m.mentions) || m.mentions.length > MAX_MENTIONS || !m.mentions.every(validHandle)) throw new Error("a message has bad mentions");
-    const editor = m.editedBy === void 0 ? void 0 : readAuthor(m.editedBy);
-    if (m.editedAt === void 0 !== (m.editedBy === void 0) || m.editedAt !== void 0 && !validDate(m.editedAt) || m.editedBy !== void 0 && !editor) {
-      throw new Error("a message has a bad edit stamp");
-    }
-    if (m.erased !== void 0 && (m.erased !== true || m.body !== ERASED_BODY || author.name !== ERASED_NAME || m.mentions.length > 0)) throw new Error("a message has a bad erased flag");
-    return {
-      id: m.id,
-      at: m.at,
-      author,
-      body: m.body,
-      mentions: [...m.mentions],
-      ...editor ? { editedAt: m.editedAt, editedBy: editor } : {},
-      ...m.erased ? { erased: true } : {}
-    };
+  readMessage(raw) {
+    const m = raw ?? {};
+    const author = readAuthor(m.author);
+    if (typeof m.id !== "string" || !ID.test(m.id) || !validDate(m.at) || !author || typeof m.body !== "string" || m.body.trim() === "" || m.body.length > MAX_BODY || BODY_FORBIDDEN.test(m.body)) {
+      throw new Error("a message has no id, ISO time, valid author, or body");
+    }
+    if (!Array.isArray(m.mentions) || m.mentions.length > MAX_MENTIONS || !m.mentions.every(validHandle)) throw new Error("a message has bad mentions");
+    const editor = m.editedBy === void 0 ? void 0 : readAuthor(m.editedBy);
+    if (m.editedAt === void 0 !== (m.editedBy === void 0) || m.editedAt !== void 0 && !validDate(m.editedAt) || m.editedBy !== void 0 && !editor) {
+      throw new Error("a message has a bad edit stamp");
+    }
+    if (m.erased !== void 0 && (m.erased !== true || m.body !== ERASED_BODY || author.name !== ERASED_NAME || m.mentions.length > 0)) throw new Error("a message has a bad erased flag");
+    return {
+      id: m.id,
+      at: m.at,
+      author,
+      body: m.body,
+      mentions: [...m.mentions],
+      ...editor ? { editedAt: m.editedAt, editedBy: editor } : {},
+      ...m.erased ? { erased: true } : {}
+    };
   }
   /** A thread with a bad anchor or status is malformed. A bad message is skipped and named in `issues`. */
   read(id2, fields) {
     try {
       if (!ID.test(id2)) throw new Error("the thread id is not short and plain");
-      if (!(fields instanceof Y3.Map)) throw new Error("the thread is not a map");
+      if (!(fields instanceof Y2.Map)) throw new Error("the thread is not a map");
       const state = fields.get("state") ?? {};
       const by = readAuthor(state.by);
       if (!STATUSES.includes(state.status) || !by || !validDate(state.at)) throw new Error("the thread status is not valid");
       const list = fields.get("messages");
-      if (!(list instanceof Y3.Array)) throw new Error("the thread has no message list");
+      if (!(list instanceof Y2.Array)) throw new Error("the thread has no message list");
       const messages = [];
       const issues = [];
       const raw = list.toArray();
@@ -753,11 +409,11 @@ var Comments = class {
     const first = this.message(body(given.body), given.mentions, who);
     const id2 = globalThis.crypto.randomUUID();
     this.ydoc.transact(() => {
-      const fields = new Y3.Map();
+      const fields = new Y2.Map();
       this.map.set(id2, fields);
       fields.set("anchor", anchor);
       fields.set("state", { status: "open", by: copy(first.author), at: first.at });
-      const messages = new Y3.Array();
+      const messages = new Y2.Array();
       fields.set("messages", messages);
       messages.push([copy(first)]);
     });
@@ -902,7 +558,7 @@ var Comments = class {
   }
   /** The raw stored threads, for the code that must see data a read hides. `list` is missing when the message field is bad. */
   stored() {
-    return [...this.map.entries()].flatMap(([id2, fields]) => fields instanceof Y3.Map ? [{ id: id2, fields, list: fields.get("messages") instanceof Y3.Array ? fields.get("messages") : void 0 }] : []);
+    return [...this.map.entries()].flatMap(([id2, fields]) => fields instanceof Y2.Map ? [{ id: id2, fields, list: fields.get("messages") instanceof Y2.Array ? fields.get("messages") : void 0 }] : []);
   }
   /**
    * What a person wrote in this document: their messages, the status change of theirs that stands, and the
@@ -911,115 +567,458 @@ var Comments = class {
    * lost a merge. When it is not 0 the export is not complete. A person may export their own data.
    */
   exportPerson(person, actor) {
-    const { name, match } = this.checkPerson(person, actor);
-    const threads = [];
-    const edits = [];
-    let shownCount = 0;
-    for (const thread of this.list()) {
-      const messages = thread.messages.filter((m) => match(m.author));
-      shownCount += messages.length;
-      const status = match(thread.statusBy);
-      if (status) shownCount++;
-      for (const m of thread.messages) if (m.editedBy && match(m.editedBy) && !match(m.author)) edits.push({ threadId: thread.id, messageId: m.id, at: m.editedAt });
-      if (messages.length === 0 && !status) continue;
-      threads.push({
-        threadId: thread.id,
-        anchor: copy(thread.anchor),
-        messages: copy(messages),
-        ...status ? { statusChange: { status: thread.status, at: thread.statusAt, by: copy(thread.statusBy) } } : {}
-      });
-    }
+    const { name, match } = this.checkPerson(person, actor);
+    const threads = [];
+    const edits = [];
+    let shownCount = 0;
+    for (const thread of this.list()) {
+      const messages = thread.messages.filter((m) => match(m.author));
+      shownCount += messages.length;
+      const status = match(thread.statusBy);
+      if (status) shownCount++;
+      for (const m of thread.messages) if (m.editedBy && match(m.editedBy) && !match(m.author)) edits.push({ threadId: thread.id, messageId: m.id, at: m.editedAt });
+      if (messages.length === 0 && !status) continue;
+      threads.push({
+        threadId: thread.id,
+        anchor: copy(thread.anchor),
+        messages: copy(messages),
+        ...status ? { statusChange: { status: thread.status, at: thread.statusAt, by: copy(thread.statusBy) } } : {}
+      });
+    }
+    let found = 0;
+    const named = (value) => {
+      const author = readAuthor(value);
+      return author !== void 0 && match(author);
+    };
+    for (const { fields, list } of this.stored()) {
+      for (const raw of list?.toArray() ?? []) if (named(raw?.author) || named(raw?.editedBy)) found++;
+      if (named(fields.get("state")?.by)) found++;
+    }
+    return { person: name, exportedAt: this.time(), threads, edits, unread: Math.max(0, found - shownCount - edits.length) };
+  }
+  /**
+   * Replace every message a person wrote with a tombstone: the body becomes "[erased]", the author name
+   * becomes "erased", and the mentions go. The author kind stays, so machine-made work stays marked. Thread
+   * shape, order, and times stay. A status change of theirs, and their name as the editor of another person's
+   * message, get the tombstone name. It works on the stored entries, so it reaches a bad message, a message past
+   * the read limit, a thread that cannot be read, and every copy that a merge hid. Names inside other people's
+   * messages are not touched. Returns how many messages, status changes, and edit stamps it erased.
+   */
+  erasePerson(person, actor) {
+    const { match } = this.checkPerson(person, actor);
+    const tomb = (a) => ({ kind: a.kind, name: ERASED_NAME });
+    const out = { messages: 0, statuses: 0, edits: 0 };
+    this.ydoc.transact(() => {
+      for (const { fields, list } of this.stored()) {
+        const entries = list?.toArray() ?? [];
+        for (let i = entries.length - 1; i >= 0; i--) {
+          const raw = entries[i];
+          if (typeof raw !== "object" || raw === null) continue;
+          const author = readAuthor(raw.author);
+          const editor = readAuthor(raw.editedBy);
+          let next;
+          if (author && match(author)) {
+            const id2 = typeof raw.id === "string" && ID.test(raw.id) ? raw.id : globalThis.crypto.randomUUID();
+            const at = validDate(raw.at) ? raw.at : this.time();
+            next = { id: id2, at, author: tomb(author), body: ERASED_BODY, mentions: [], editedAt: this.time(), editedBy: tomb(author), erased: true };
+            out.messages++;
+          } else if (editor && match(editor)) {
+            next = { ...raw, editedBy: tomb(editor) };
+            out.edits++;
+          }
+          if (!next) continue;
+          list.delete(i, 1);
+          list.insert(i, [next]);
+        }
+        const state = fields.get("state");
+        const by = readAuthor(state?.by);
+        if (state && by && match(by)) {
+          fields.set("state", { ...state, by: tomb(by) });
+          out.statuses++;
+        }
+      }
+    });
+    return out;
+  }
+  get(threadId) {
+    const { id: id2, fields } = this.fields(threadId);
+    return this.read(id2, fields).thread;
+  }
+  /** Threads in the order they were started. A malformed thread is skipped; `problems()` names it. */
+  list(filter = {}) {
+    const given = exact(filter, ["status", "anchorType", "mentioning", "anchorState"], "a filter");
+    if (given.status !== void 0 && !STATUSES.includes(given.status)) invalid(`status must be ${STATUSES.join(" or ")}`);
+    if (given.anchorType !== void 0 && typeof given.anchorType !== "string") invalid("anchorType must be text");
+    if (given.mentioning !== void 0 && typeof given.mentioning !== "string") invalid("mentioning must be text");
+    if (given.anchorState !== void 0 && !ANCHOR_STATES.includes(given.anchorState)) invalid(`anchorState must be ${ANCHOR_STATES.join(", ")}`);
+    const wanted = given.mentioning === void 0 ? void 0 : handle(given.mentioning);
+    return this.readAll().threads.filter((t) => given.status === void 0 || t.status === given.status).filter((t) => given.anchorType === void 0 || t.anchor.type === given.anchorType).filter((t) => given.anchorState === void 0 || t.anchorState.state === given.anchorState).filter((t) => wanted === void 0 || t.messages.some((m) => m.mentions.includes(wanted))).sort((a, b) => Date.parse(a.messages[0].at) - Date.parse(b.messages[0].at) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  }
+  /** Threads or messages that could not be read, for example from a replica that wrote bad data. */
+  problems() {
+    return this.readAll().problems;
+  }
+  readAll() {
+    const threads = [];
+    const problems = [];
+    for (const [id2, fields] of this.map.entries()) {
+      try {
+        const { thread, issues } = this.read(id2, fields);
+        threads.push(thread);
+        for (const reason of issues) problems.push({ id: safeId(id2), reason });
+      } catch (error) {
+        problems.push({ id: safeId(id2), reason: error.message });
+      }
+    }
+    return { threads, problems };
+  }
+};
+
+// src/suggestions.ts
+import * as Y3 from "yjs";
+var ACCEPT_SCOPE = "comments:accept";
+var MAX_CHANGE = 64e3;
+var MAX_RECEIPT = 16e3;
+var MAX_SUMMARY = 1e3;
+var SUGGESTIONS = "comments.suggestions";
+var APPLIED = "comments.suggestion-applied";
+var REJECTED = "comments.suggestion-rejected";
+var decidesOwn = (author, decider) => author.name !== ERASED_NAME && author.kind !== "human" && decider.kind !== "human" && author.name === decider.name;
+var clientOf = (text) => /^(0|[1-9]\d{0,9})$/.test(text) && Number(text) <= 4294967295 ? Number(text) : void 0;
+var thenable = (value) => typeof value?.then === "function";
+var Suggestions = class {
+  constructor(comments, host) {
+    this.comments = comments;
+    this.host = host;
+    if (typeof host?.apply !== "function" || typeof host.revert !== "function" && host.idempotent !== true) {
+      invalid("a host needs apply, and either revert or idempotent: true, so two accepts at once cannot apply a change twice");
+    }
+    void [this.map, this.applied, this.rejected];
+    this.onTransaction = (tr) => {
+      if (!tr.local && [this.applied, this.map].some((type) => tr.changedParentTypes.has(type))) this.settle();
+    };
+    this.ydoc.on("afterTransaction", this.onTransaction);
+    this.settle();
+  }
+  comments;
+  host;
+  onTransaction;
+  failures = [];
+  /** Stop listening to the document. */
+  close() {
+    this.ydoc.off("afterTransaction", this.onTransaction);
+  }
+  get ydoc() {
+    return this.comments.ydoc;
+  }
+  get map() {
+    return this.ydoc.getMap(SUGGESTIONS);
+  }
+  /** The three Yjs maps that hold suggestions and their decisions. `Notifications` watches them. */
+  get maps() {
+    return { suggestions: this.map, applied: this.applied, rejected: this.rejected };
+  }
+  get applied() {
+    return this.ydoc.getMap(APPLIED);
+  }
+  get rejected() {
+    return this.ydoc.getMap(REJECTED);
+  }
+  change(raw, anchor) {
+    let clean;
+    try {
+      clean = strictCopy(raw);
+      if (this.host.parse) clean = strictCopy(this.host.parse(copy(clean), { anchor: copy(anchor) }));
+    } catch (error) {
+      return invalid(`the change is refused: ${safeText(error instanceof Error ? error.message : error)}`);
+    }
+    if (JSON.stringify(clean).length > MAX_CHANGE) invalid(`a change holds up to ${MAX_CHANGE} characters of JSON`);
+    return clean;
+  }
+  /**
+   * Records of one kind for one suggestion, in client order. A record that is not valid is not counted:
+   * one with no author or time, a receipt that is not small JSON, or a decider who decided their own work.
+   */
+  records(entries, id2, author) {
+    const out = [];
+    for (const [key2, raw] of entries) {
+      const client = clientOf(key2.slice(id2.length + 1));
+      const r = raw ?? {};
+      const by = readAuthor(r.by);
+      if (client === void 0 || !by || !validDate(r.at) || !author || decidesOwn(author, by)) continue;
+      let receipt = null;
+      try {
+        receipt = r.receipt === void 0 ? null : strictCopy(r.receipt);
+        if (JSON.stringify(receipt).length > MAX_RECEIPT) continue;
+      } catch {
+        continue;
+      }
+      out.push({ client, by, at: r.at, receipt });
+    }
+    return out.sort((a, b) => Number(a.receipt !== null) - Number(b.receipt !== null) || a.client - b.client);
+  }
+  /** Group the entries of a decision map by suggestion id in one pass, so a read does not scan the map per suggestion. */
+  index(map) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const entry of map.entries()) {
+      const id2 = entry[0].slice(0, entry[0].lastIndexOf(":"));
+      const group = groups.get(id2);
+      if (group) group.push(entry);
+      else groups.set(id2, [entry]);
+    }
+    return groups;
+  }
+  read(id2, fields, indexes = { applied: this.index(this.applied), rejected: this.index(this.rejected) }) {
+    try {
+      if (!ID.test(id2)) throw new Error("the suggestion id is not short and plain");
+      if (!(fields instanceof Y3.Map)) throw new Error("the suggestion is not a map");
+      const author = readAuthor(fields.get("author"));
+      const createdAt = fields.get("createdAt");
+      const summary = fields.get("summary");
+      const change = fields.get("change");
+      if (!author || !validDate(createdAt)) throw new Error("the suggestion has no valid author or time");
+      if (summary !== void 0 && !(typeof summary === "string" && summary.trim() !== "" && summary.length <= MAX_SUMMARY && !BODY_FORBIDDEN.test(summary))) {
+        throw new Error("the summary is not valid");
+      }
+      if (change === void 0 || JSON.stringify(strictCopy(change)).length > MAX_CHANGE) throw new Error("the change is missing or too large");
+      const won = this.records(indexes.applied.get(id2) ?? [], id2, author)[0];
+      const refused = this.records(indexes.rejected.get(id2) ?? [], id2, author)[0];
+      const decision = won ? { status: "accepted", ...won } : refused ? { status: "rejected", ...refused } : void 0;
+      const anchor = this.comments.parseAnchor(fields.get("anchor"));
+      return {
+        id: id2,
+        anchor,
+        anchorState: this.comments.anchorState(anchor),
+        change: copy(change),
+        ...summary === void 0 ? {} : { summary },
+        author,
+        createdAt,
+        status: decision?.status ?? "pending",
+        ...decision ? { decidedBy: decision.by, decidedAt: decision.at } : {}
+      };
+    } catch (error) {
+      throw new CommentsError("CORRUPT", `suggestion ${shown(id2)} is malformed: ${safeText(error instanceof Error ? error.message : error)}`);
+    }
+  }
+  fields(id2) {
+    if (typeof id2 !== "string" || !ID.test(id2) || !this.map.has(id2)) throw new CommentsError("NO_SUGGESTION", `no suggestion with id ${shown(id2)}`);
+    return { id: id2, fields: this.map.get(id2) };
+  }
+  /**
+   * The suggestions a person wrote, and the decisions they made, in this document. `unread` counts stored
+   * suggestions and decision records with their name that this export cannot show: a suggestion that cannot
+   * be read, a decision that lost a merge, a refused decision, or a decision with no suggestion. When it is not
+   * 0 the export is not complete. A person may export their own data.
+   */
+  exportPerson(person, actor) {
+    const { match } = this.comments.checkPerson(person, actor);
+    const all = this.list();
+    const authored = all.filter((s) => match(s.author));
+    const decided = all.flatMap((s) => s.decidedBy && s.decidedAt && s.status !== "pending" && match(s.decidedBy) ? [{ id: s.id, status: s.status, at: s.decidedAt }] : []);
     let found = 0;
-    const named = (value) => {
-      const author = readAuthor(value);
-      return author !== void 0 && match(author);
-    };
-    for (const { fields, list } of this.stored()) {
-      for (const raw of list?.toArray() ?? []) if (named(raw?.author) || named(raw?.editedBy)) found++;
-      if (named(fields.get("state")?.by)) found++;
-    }
-    return { person: name, exportedAt: this.time(), threads, edits, unread: Math.max(0, found - shownCount - edits.length) };
+    for (const fields of this.map.values()) if (fields instanceof Y3.Map && this.named(fields.get("author"), match)) found++;
+    for (const map of [this.applied, this.rejected]) for (const raw of map.values()) if (this.named(raw?.by, match)) found++;
+    return { authored, decided, unread: Math.max(0, found - authored.length - decided.length) };
+  }
+  named(value, match) {
+    const author = readAuthor(value);
+    return author !== void 0 && match(author);
   }
   /**
-   * Replace every message a person wrote with a tombstone: the body becomes "[erased]", the author name
-   * becomes "erased", and the mentions go. The author kind stays, so machine-made work stays marked. Thread
-   * shape, order, and times stay. A status change of theirs, and their name as the editor of another person's
-   * message, get the tombstone name. It works on the stored entries, so it reaches a bad message, a message past
-   * the read limit, a thread that cannot be read, and every copy that a merge hid. Names inside other people's
-   * messages are not touched. Returns how many messages, status changes, and edit stamps it erased.
+   * Give every suggestion a person wrote a tombstone author and drop its summary. An accepted one keeps its
+   * change, because that change is already part of the content. A pending or rejected one loses its change, and
+   * can no longer be accepted. A decision they made gets a tombstone decider. A decision that a read refuses (a
+   * principal that decided its own work) is deleted, so erase never turns it into a valid one. Returns how many
+   * suggestions and decisions it changed.
    */
   erasePerson(person, actor) {
-    const { match } = this.checkPerson(person, actor);
-    const tomb = (a) => ({ kind: a.kind, name: ERASED_NAME });
-    const out = { messages: 0, statuses: 0, edits: 0 };
+    const { match } = this.comments.checkPerson(person, actor);
+    const out = { suggestions: 0, decisions: 0 };
+    const authors = /* @__PURE__ */ new Map();
+    for (const [id2, fields] of this.map.entries()) {
+      const author = fields instanceof Y3.Map ? readAuthor(fields.get("author")) : void 0;
+      if (author) authors.set(id2, author);
+    }
+    const status = new Map(this.list().map((s) => [s.id, s.status]));
     this.ydoc.transact(() => {
-      for (const { fields, list } of this.stored()) {
-        const entries = list?.toArray() ?? [];
-        for (let i = entries.length - 1; i >= 0; i--) {
-          const raw = entries[i];
-          if (typeof raw !== "object" || raw === null) continue;
-          const author = readAuthor(raw.author);
-          const editor = readAuthor(raw.editedBy);
-          let next;
-          if (author && match(author)) {
-            const id2 = typeof raw.id === "string" && ID.test(raw.id) ? raw.id : globalThis.crypto.randomUUID();
-            const at = validDate(raw.at) ? raw.at : this.time();
-            next = { id: id2, at, author: tomb(author), body: ERASED_BODY, mentions: [], editedAt: this.time(), editedBy: tomb(author), erased: true };
-            out.messages++;
-          } else if (editor && match(editor)) {
-            next = { ...raw, editedBy: tomb(editor) };
-            out.edits++;
+      for (const map of [this.applied, this.rejected]) {
+        for (const [key2, raw] of [...map.entries()]) {
+          const by = readAuthor(raw?.by);
+          const author = authors.get(key2.slice(0, key2.lastIndexOf(":")));
+          if (!by || !(match(by) || author && match(author))) continue;
+          if (author && decidesOwn(author, by)) map.delete(key2);
+          else if (match(by)) {
+            map.set(key2, { ...raw, by: { kind: by.kind, name: ERASED_NAME } });
+            out.decisions++;
           }
-          if (!next) continue;
-          list.delete(i, 1);
-          list.insert(i, [next]);
-        }
-        const state = fields.get("state");
-        const by = readAuthor(state?.by);
-        if (state && by && match(by)) {
-          fields.set("state", { ...state, by: tomb(by) });
-          out.statuses++;
         }
       }
+      for (const [id2, author] of authors) {
+        if (!match(author)) continue;
+        const fields = this.map.get(id2);
+        fields.set("author", { kind: author.kind, name: ERASED_NAME });
+        fields.delete("summary");
+        if (status.get(id2) !== "accepted") fields.set("change", null);
+        out.suggestions++;
+      }
     });
     return out;
   }
-  get(threadId) {
-    const { id: id2, fields } = this.fields(threadId);
-    return this.read(id2, fields).thread;
+  /** Propose a change. Anyone can suggest. The host stamps the author. */
+  add(input, actor) {
+    const who = assertActor(actor);
+    const given = exact(input, ["anchor", "change", "summary"], "a new suggestion");
+    const anchor = this.comments.checkAnchor(given.anchor);
+    const change = this.change(given.change, anchor);
+    const summary = given.summary;
+    if (summary !== void 0 && !(typeof summary === "string" && summary.trim() !== "" && summary.length <= MAX_SUMMARY && !BODY_FORBIDDEN.test(summary))) {
+      invalid(`a summary must be text of 1 to ${MAX_SUMMARY} characters, with no control or invisible characters`);
+    }
+    const id2 = globalThis.crypto.randomUUID();
+    const createdAt = this.comments.time();
+    this.ydoc.transact(() => {
+      const fields = new Y3.Map();
+      this.map.set(id2, fields);
+      fields.set("anchor", anchor);
+      fields.set("change", change);
+      if (summary !== void 0) fields.set("summary", summary);
+      fields.set("author", { kind: who.kind, name: who.name });
+      fields.set("createdAt", createdAt);
+    });
+    return this.get(id2);
   }
-  /** Threads in the order they were started. A malformed thread is skipped; `problems()` names it. */
+  /** A person decides. An agent needs the accept scope, and never decides its own suggestion. */
+  mayDecide(who, s, verb) {
+    const ok = !decidesOwn(s.author, who) && (who.kind === "human" || who.scopes.includes(ACCEPT_SCOPE));
+    if (!ok) throw new CommentsError("FORBIDDEN", `${who.kind}:${shown(who.name)} cannot ${verb} this suggestion: a signed-in person, or a principal with the ${ACCEPT_SCOPE} scope that did not write it, can`);
+    if (verb === "accept" && s.author.name === ERASED_NAME && s.status !== "accepted") throw new CommentsError("FORBIDDEN", "an erased suggestion has no change left and cannot be accepted");
+  }
+  /**
+   * Apply the change as the accepting author and record the decision, in one step. Accepting an
+   * accepted suggestion changes nothing. When `apply` throws, the suggestion stays pending.
+   */
+  accept(suggestionId, actor) {
+    const who = assertActor(actor);
+    if (this.ydoc._transaction !== null) {
+      throw new CommentsError("APPLY_FAILED", "accept cannot run inside another Yjs transaction, such as an observer or an apply hook");
+    }
+    const { id: id2, fields } = this.fields(suggestionId);
+    const s = this.read(id2, fields);
+    this.mayDecide(who, s, "accept");
+    if (s.status === "accepted") return s;
+    if (s.status === "rejected") throw new CommentsError("ALREADY_DECIDED", `suggestion ${shown(id2)} is already rejected`);
+    const by = { kind: who.kind, name: who.name };
+    const at = this.comments.time();
+    this.ydoc.transact((tr) => {
+      const edited = () => tr.changed.size > 0 || tr.deleteSet.clients.size > 0;
+      let receipt = null;
+      let failure;
+      try {
+        if (s.anchorState.state === "orphaned" || s.anchorState.state === "edited") {
+          throw new Error(s.anchorState.state === "orphaned" ? "the anchored content is gone" : "the anchored content has changed since the suggestion was made");
+        }
+        this.comments.checkAnchor(s.anchor);
+        const change = this.change(s.change, s.anchor);
+        receipt = this.host.apply(change, { suggestionId: id2, anchor: copy(s.anchor), author: Object.freeze({ ...s.author }), by: Object.freeze({ ...by }), ydoc: this.ydoc });
+        if (thenable(receipt)) throw new Error("apply must finish at once and cannot return a promise");
+        receipt = receipt === void 0 ? null : strictCopy(receipt);
+        if (JSON.stringify(receipt).length > MAX_RECEIPT) throw new Error(`a receipt holds up to ${MAX_RECEIPT} characters of JSON`);
+      } catch (error) {
+        failure = error;
+        receipt = null;
+      }
+      if (failure !== void 0) {
+        const reason = safeText(failure instanceof Error ? failure.message : failure);
+        if (!edited()) throw new CommentsError("APPLY_FAILED", `the change could not be applied: ${reason}`);
+        this.failures.push({ id: safeId(id2), reason: `apply failed after it edited the document, so the decision is recorded without a receipt: ${reason}` });
+      }
+      this.applied.set(`${id2}:${this.ydoc.clientID}`, { by, at, receipt });
+    });
+    return this.get(id2);
+  }
+  /** Same right as accept. A person can withdraw their own suggestion. */
+  reject(suggestionId, actor) {
+    const who = assertActor(actor);
+    const { id: id2, fields } = this.fields(suggestionId);
+    const s = this.read(id2, fields);
+    this.mayDecide(who, s, "reject");
+    if (s.status === "rejected") return s;
+    if (s.status === "accepted") throw new CommentsError("ALREADY_DECIDED", `suggestion ${shown(id2)} is already accepted`);
+    this.rejected.set(`${id2}:${this.ydoc.clientID}`, { by: { kind: who.kind, name: who.name }, at: this.comments.time() });
+    return this.get(id2);
+  }
+  get(suggestionId) {
+    const { id: id2, fields } = this.fields(suggestionId);
+    return this.read(id2, fields);
+  }
+  /** In the order they were made. A malformed suggestion is skipped, and `problems()` names it. */
   list(filter = {}) {
-    const given = exact(filter, ["status", "anchorType", "mentioning", "anchorState"], "a filter");
-    if (given.status !== void 0 && !STATUSES.includes(given.status)) invalid(`status must be ${STATUSES.join(" or ")}`);
-    if (given.anchorType !== void 0 && typeof given.anchorType !== "string") invalid("anchorType must be text");
-    if (given.mentioning !== void 0 && typeof given.mentioning !== "string") invalid("mentioning must be text");
-    if (given.anchorState !== void 0 && !ANCHOR_STATES.includes(given.anchorState)) invalid(`anchorState must be ${ANCHOR_STATES.join(", ")}`);
-    const wanted = given.mentioning === void 0 ? void 0 : handle(given.mentioning);
-    return this.readAll().threads.filter((t) => given.status === void 0 || t.status === given.status).filter((t) => given.anchorType === void 0 || t.anchor.type === given.anchorType).filter((t) => given.anchorState === void 0 || t.anchorState.state === given.anchorState).filter((t) => wanted === void 0 || t.messages.some((m) => m.mentions.includes(wanted))).sort((a, b) => Date.parse(a.messages[0].at) - Date.parse(b.messages[0].at) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const given = exact(filter, ["status", "anchorState"], "a filter");
+    if (given.anchorState !== void 0 && !["attached", "edited", "orphaned", "unknown"].includes(given.anchorState)) invalid("anchorState must be attached, edited, orphaned, or unknown");
+    if (given.status !== void 0 && !["pending", "accepted", "rejected"].includes(given.status)) invalid("status must be pending, accepted, or rejected");
+    return this.readAll().suggestions.filter((s) => given.status === void 0 || s.status === given.status).filter((s) => given.anchorState === void 0 || s.anchorState.state === given.anchorState).sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   }
-  /** Threads or messages that could not be read, for example from a replica that wrote bad data. */
+  /** Suggestions that could not be read, and reverts that failed. */
   problems() {
-    return this.readAll().problems;
+    return [...this.readAll().problems, ...this.failures];
   }
   readAll() {
-    const threads = [];
+    const suggestions = [];
     const problems = [];
+    const indexes = { applied: this.index(this.applied), rejected: this.index(this.rejected) };
     for (const [id2, fields] of this.map.entries()) {
       try {
-        const { thread, issues } = this.read(id2, fields);
-        threads.push(thread);
-        for (const reason of issues) problems.push({ id: safeId(id2), reason });
+        suggestions.push(this.read(id2, fields, indexes));
       } catch (error) {
         problems.push({ id: safeId(id2), reason: error.message });
       }
     }
-    return { threads, problems };
+    return { suggestions, problems };
+  }
+  /**
+   * Two replicas can accept one suggestion before they meet. After a merge, the application of the
+   * lowest client id stays, and the host reverts each other one. Every replica reaches the same result.
+   * A revert that throws leaves its record, so the next merge tries again.
+   */
+  settle() {
+    const groups = this.index(this.applied);
+    const indexes = { applied: groups, rejected: this.index(this.rejected) };
+    this.failures = this.failures.filter((f) => f.reason.startsWith("apply failed") || f.reason.startsWith("a duplicate application has no receipt"));
+    this.ydoc.transact(() => {
+      for (const [id2, entries] of groups) {
+        if (entries.length < 2 || !ID.test(id2) || !this.map.has(id2)) continue;
+        let s;
+        try {
+          s = this.read(id2, this.map.get(id2), indexes);
+        } catch {
+          continue;
+        }
+        for (const loser of this.records(entries, id2, s.author).slice(1)) {
+          const key2 = `${id2}:${loser.client}`;
+          if (this.host.idempotent) {
+            this.applied.delete(key2);
+            continue;
+          }
+          if (loser.receipt === null) {
+            this.failures.push({ id: safeId(id2), reason: "a duplicate application has no receipt, so its edit cannot be undone and stays in the document" });
+            this.applied.delete(key2);
+            continue;
+          }
+          try {
+            this.host.revert?.(loser.receipt, { suggestionId: id2, anchor: copy(s.anchor), author: Object.freeze({ ...s.author }), by: Object.freeze({ ...loser.by }), ydoc: this.ydoc });
+            this.applied.delete(key2);
+          } catch (error) {
+            this.failures.push({ id: safeId(id2), reason: `a duplicate application could not be reverted: ${safeText(error instanceof Error ? error.message : error)}` });
+          }
+        }
+      }
+    });
   }
 };
 
 export {
   CommentsError,
+  shown,
   textOf,
   textAnchor,
   textRange,
@@ -1027,14 +1026,15 @@ export {
   ERASED_NAME,
   Actor,
   stamp,
+  assertActor,
   readAuthor,
   authorLabel,
   invalid,
   exact,
   validDate,
-  ACCEPT_SCOPE,
-  Suggestions,
   MODERATE_SCOPE,
   ERASED_BODY,
-  Comments
+  Comments,
+  ACCEPT_SCOPE,
+  Suggestions
 };