@voltro/plugin-comments 0.53.0

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+import { ColumnBuilder } from '@voltro/database';
+import { DataStore } from '@voltro/database';
+import { FieldDefinitions } from '@voltro/database';
+import { ReactivityChannel } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Table } from '@voltro/database';
+import { VoltroPlugin } from '@voltro/protocol';
+
+export declare interface CommentAccessInput {
+    /** The thread's anchor, verbatim as the app wrote it. */
+    readonly anchor: string;
+    readonly subject: {
+        readonly id: string | null;
+        readonly tenantId: string | null;
+        readonly scopes: ReadonlyArray<string>;
+    };
+    /** The app's data store — how the rule reads the anchored entity's own row
+     *  (existence, soft-delete flag, ownership). `undefined` only while the
+     *  store is still binding at boot; answer false then (fail-closed). */
+    readonly store: DataStore | undefined;
+}
+
+/** The anchor's access check refused the caller — or no access rule is
+ *  declared at all (fail-closed: undeclared access is a refusal, not a pass).
+ *  Also the answer for a thread whose anchor row no longer resolves (a
+ *  soft-deleted entity): already-delivered mention notifications keep
+ *  pointing here, and this is what they find — "no longer available", not a
+ *  leak and not a crash. */
+export declare class CommentAccessRefused extends CommentAccessRefused_base {
+}
+
+declare const CommentAccessRefused_base: Schema.TaggedErrorClass<CommentAccessRefused, "CommentAccessRefused", {
+    readonly _tag: Schema.tag<"CommentAccessRefused">;
+} & {
+    anchor: typeof Schema.String;
+    reason: typeof Schema.String;
+}>;
+
+/** The thread / comment id resolves to nothing the caller may see. */
+export declare class CommentNotFound extends CommentNotFound_base {
+}
+
+declare const CommentNotFound_base: Schema.TaggedErrorClass<CommentNotFound, "CommentNotFound", {
+    readonly _tag: Schema.tag<"CommentNotFound">;
+} & {
+    id: typeof Schema.String;
+}>;
+
+/** Only the author edits or deletes their own comment (a `comments:moderate`
+ *  scope overrides for delete). */
+export declare class CommentNotYours extends CommentNotYours_base {
+}
+
+declare const CommentNotYours_base: Schema.TaggedErrorClass<CommentNotYours, "CommentNotYours", {
+    readonly _tag: Schema.tag<"CommentNotYours">;
+} & {
+    id: typeof Schema.String;
+}>;
+
+export declare const commentReactionsTable: Table<"_voltro_comment_reactions", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly commentId: ColumnBuilder<string, "text", boolean>;
+    readonly subjectId: ColumnBuilder<string, "text", boolean>;
+    readonly emoji: ColumnBuilder<string, "text", boolean>;
+}>, true, "byReactionComment">;
+
+export declare const commentReadsTable: Table<"_voltro_comment_reads", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly threadId: ColumnBuilder<string, "text", boolean>;
+    readonly subjectId: ColumnBuilder<string, "text", boolean>;
+    readonly lastReadAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+/** One push channel for the whole surface: every comment write publishes, and
+ *  `comments.list` re-runs for subscribers. Table-granular by design for now —
+ *  the read-set work (plan 01 P3) is the named narrowing. */
+export declare const commentsFeed: ReactivityChannel;
+
+export declare const commentsPlugin: (options?: CommentsPluginOptions) => VoltroPlugin;
+
+declare interface CommentsPluginOptions {
+    /**
+     * WHO may read and write a given anchor's threads. Exactly one of:
+     *
+     *  - `viaEntity` — guard delegation: the app resolves the anchor to its own
+     *    entity and answers with its own rules (the same guard its queries use).
+     *    A row the guard cannot read — including a soft-deleted one — is a
+     *    refusal, which is precisely the fail-closed semantic wanted there.
+     *  - `scope` — one scope every comment reader/writer must hold, for apps
+     *    whose comments are team-internal rather than entity-scoped.
+     *
+     * UNDECLARED IS REFUSED. A comments surface with no access rule serves
+     * nobody rather than everybody.
+     */
+    readonly access?: {
+        readonly viaEntity?: (input: CommentAccessInput) => Promise<boolean>;
+        readonly scope?: string;
+    };
+    /**
+     * Resolve an @-mention autocomplete query to subjects. The default returns
+     * NOTHING (there is no framework-wide user directory to leak); an app wires
+     * its own directory here. Whatever it returns is additionally filtered to
+     * the caller's tenant unless `crossTenant: true` is set — the seam is
+     * tenant-safe by construction, not by every implementor remembering.
+     */
+    readonly resolveMentions?: (input: MentionSearchInput) => Promise<ReadonlyArray<{
+        readonly subjectId: string;
+        readonly label: string;
+        readonly tenantId?: string | null;
+    }>>;
+    /** Allow mention resolution across tenants (single-tenant apps, admin
+     *  surfaces). Default false. */
+    readonly crossTenant?: boolean;
+    /** Notification category for mention sends. Default `mention`. */
+    readonly mentionCategory?: string;
+    /** Namespace for rpc tags + inspect endpoints. Default `comments`. */
+    readonly alias?: string;
+    /** Second-installation discriminator. */
+    readonly name?: string;
+}
+export { CommentsPluginOptions as CommentsOptions }
+export { CommentsPluginOptions }
+
+export declare const commentsTable: Table<"_voltro_comments", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly threadId: ColumnBuilder<string, "text", boolean>;
+    readonly body: ColumnBuilder<string, "text", boolean>;
+    readonly authorSubjectId: ColumnBuilder<string, "text", boolean>;
+    readonly mentions: ColumnBuilder<readonly string[], "json", boolean>;
+    readonly editedAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+    readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
+}>, true, "byCommentThread">;
+
+export declare const commentThreadsTable: Table<"_voltro_comment_threads", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    /** Free string key (`order:123`, `doc:abc#section-2`) — the app decides the
+     *  vocabulary; the access rule receives it verbatim. */
+    readonly anchor: ColumnBuilder<string, "text", boolean>;
+    readonly status: ColumnBuilder<string, "text", true>;
+    readonly createdBy: ColumnBuilder<string, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+    readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
+}>, true, "byThreadAnchor">;
+
+export declare interface MentionSearchInput {
+    readonly query: string;
+    /** The CALLING subject — REQUIRED in the seam signature so no implementation
+     *  can forget it: the default filters to its tenantId, and without that the
+     *  autocomplete leaks existence + names across the tenant boundary. */
+    readonly subject: {
+        readonly id: string | null;
+        readonly tenantId: string | null;
+    };
+}
+
+/** Placeholder export kept for the scaffold's smoke import — the plugin above
+ *  is the API. */
+export declare const pluginComments: () => string;
+
+export { }

package/dist/index.js

@@ -0,0 +1,364 @@
+import { CommentAccessRefused as e, CommentNotFound as t, CommentNotYours as n } from "./errors.js";
+import { commentsFeed as r, commentsRpcClientImports as i, createDescriptor as a, deleteDescriptor as o, editDescriptor as s, listDescriptor as c, markReadDescriptor as l, mentionSearchDescriptor as u, reactDescriptor as d, resolveDescriptor as f } from "./rpc.js";
+import { Effect as p, Option as m } from "effect";
+import { and as h, eq as g, generateId as _, id as v, json as y, table as b, text as x, timestamp as S } from "@voltro/database";
+import { definePlugin as C, pluginInstanceName as w, publishReactivity as T } from "@voltro/protocol";
+import { NotificationService as E } from "@voltro/plugin-notifications";
+//#region src/index.ts
+var D = b("_voltro_comment_threads", {
+	id: v({ prefix: "cmtthr" }),
+	anchor: x(),
+	status: x().default("open"),
+	createdBy: x(),
+	createdAt: S().default("now"),
+	tenantId: x().nullable()
+}).index("byThreadAnchor", ["anchor", "tenantId"]), O = b("_voltro_comments", {
+	id: v({ prefix: "cmt" }),
+	threadId: x(),
+	body: x(),
+	authorSubjectId: x(),
+	mentions: y(),
+	editedAt: S().nullable(),
+	createdAt: S().default("now"),
+	tenantId: x().nullable()
+}).index("byCommentThread", ["threadId"]), k = b("_voltro_comment_reactions", {
+	id: v({ prefix: "cmtrx" }),
+	commentId: x(),
+	subjectId: x(),
+	emoji: x()
+}).unique("byReactionIdentity", [
+	"commentId",
+	"subjectId",
+	"emoji"
+]).index("byReactionComment", ["commentId"]), A = b("_voltro_comment_reads", {
+	id: v({ prefix: "cmtread" }),
+	threadId: x(),
+	subjectId: x(),
+	lastReadAt: S()
+}).unique("byReadThreadSubject", ["threadId", "subjectId"]), j = "@voltro/plugin-comments", M = (e) => {
+	let t = e.request.subject ?? {};
+	return {
+		id: t.id ?? null,
+		tenantId: t.tenantId ?? null,
+		scopes: t.scopes ?? []
+	};
+}, N = (v = {}) => {
+	let y = w({
+		base: j,
+		alias: v.alias,
+		instance: v.name
+	}), b, x, S = async (e, t, n) => b === void 0 ? [] : b.query({
+		table: e,
+		predicate: t,
+		order: [],
+		take: n,
+		skip: void 0,
+		projection: void 0
+	}), N = () => {
+		T(x, r);
+	}, P = (t, n) => p.gen(function* () {
+		let r = M(n);
+		return v.access?.viaEntity === void 0 ? v.access?.scope === void 0 ? yield* p.fail(new e({
+			anchor: t,
+			reason: "no access rule declared — set commentsPlugin({ access: { viaEntity } }) or { access: { scope } }"
+		})) : r.scopes.includes(v.access.scope) ? void 0 : yield* p.fail(new e({
+			anchor: t,
+			reason: `missing scope '${v.access.scope}'`
+		})) : (yield* p.promise(async () => {
+			try {
+				return await v.access.viaEntity({
+					anchor: t,
+					subject: r,
+					store: b
+				});
+			} catch {
+				return !1;
+			}
+		})) ? void 0 : yield* p.fail(new e({
+			anchor: t,
+			reason: "the anchored entity is not readable by this caller (or no longer available)"
+		}));
+	}), F = async (e) => (await S("_voltro_comment_threads", g("id", e), 1))[0], I = (e) => e instanceof Date ? e.toISOString() : typeof e == "string" ? e : "", L = (e) => p.gen(function* () {
+		if (e.mentions.length === 0) return;
+		let t = yield* p.serviceOption(E);
+		if (m.isNone(t)) {
+			yield* p.logInfo("comments: mention recorded without notification — @voltro/plugin-notifications is not configured");
+			return;
+		}
+		for (let n of e.mentions) n !== e.author && (yield* p.promise(() => t.value.send({
+			to: n,
+			category: v.mentionCategory ?? "mention",
+			title: "You were mentioned",
+			body: e.body.length > 200 ? `${e.body.slice(0, 200)}…` : e.body,
+			data: {
+				anchor: e.anchor,
+				threadId: e.threadId
+			},
+			tenantId: e.tenantId
+		}).then(() => void 0).catch(() => void 0)));
+	}), R = async (e, t) => {
+		if (e.length === 0 || v.resolveMentions === void 0) return [];
+		let n = [];
+		for (let r of [...new Set(e)].slice(0, 20)) {
+			let e = (await v.resolveMentions({
+				query: r,
+				subject: t
+			}).catch(() => [])).find((e) => e.subjectId === r);
+			e !== void 0 && (v.crossTenant === !0 || e.tenantId === void 0 || e.tenantId === null || e.tenantId === t.tenantId) && n.push(r);
+		}
+		return n;
+	}, z = async (e, t, n) => {
+		let r = await S("_voltro_comment_threads", h(g("anchor", e), g("tenantId", t))), i = [];
+		for (let e of r) {
+			let t = [...await S("_voltro_comments", g("threadId", String(e.id)))];
+			t.sort((e, t) => I(e.createdAt) < I(t.createdAt) ? -1 : 1);
+			let r = n === null ? [] : await S("_voltro_comment_reads", h(g("threadId", String(e.id)), g("subjectId", n)), 1), a = r[0] ? I(r[0].lastReadAt) : "", o = [];
+			for (let e of t) {
+				let t = await S("_voltro_comment_reactions", g("commentId", String(e.id))), r = /* @__PURE__ */ new Map();
+				for (let e of t) {
+					let t = r.get(String(e.emoji)) ?? {
+						count: 0,
+						mine: !1
+					};
+					t.count += 1, String(e.subjectId) === n && (t.mine = !0), r.set(String(e.emoji), t);
+				}
+				o.push({
+					id: String(e.id),
+					threadId: String(e.threadId),
+					body: String(e.body),
+					authorSubjectId: String(e.authorSubjectId),
+					mentions: e.mentions ?? [],
+					editedAt: e.editedAt == null ? null : I(e.editedAt),
+					createdAt: I(e.createdAt),
+					reactions: [...r.entries()].map(([e, t]) => ({
+						emoji: e,
+						count: t.count,
+						mine: t.mine
+					}))
+				});
+			}
+			i.push({
+				id: String(e.id),
+				anchor: String(e.anchor),
+				status: e.status === "resolved" ? "resolved" : "open",
+				createdBy: String(e.createdBy),
+				createdAt: I(e.createdAt),
+				comments: o,
+				unreadCount: o.filter((e) => String(e.authorSubjectId) !== n && String(e.createdAt) > a).length
+			});
+		}
+		return i.sort((e, t) => String(e.createdAt) < String(t.createdAt) ? -1 : 1), i;
+	}, B = "comments:moderate", V = [
+		{
+			...c,
+			description: "Threads + comments + reactions + unread for one anchor, live.",
+			execute: (e, t) => p.gen(function* () {
+				let { anchor: n } = e;
+				yield* P(n, t);
+				let r = M(t);
+				return yield* p.promise(() => z(n, r.tenantId, r.id));
+			})
+		},
+		{
+			...a,
+			description: "Comment on an anchor — a reply into a thread, or a new thread.",
+			execute: (e, n) => p.gen(function* () {
+				let r = e;
+				yield* P(r.anchor, n);
+				let i = M(n), a = i.id ?? "anonymous", o = b;
+				if (o === void 0) return yield* p.fail(new t({ id: r.anchor }));
+				let s = r.threadId;
+				if (s !== void 0) {
+					let e = yield* p.promise(() => F(s));
+					if (e === void 0 || String(e.anchor) !== r.anchor) return yield* p.fail(new t({ id: s }));
+				} else s = _({
+					kind: "typeid",
+					prefix: "cmtthr"
+				}, "_voltro_comment_threads"), yield* p.promise(() => o.insert("_voltro_comment_threads", {
+					id: s,
+					anchor: r.anchor,
+					status: "open",
+					createdBy: a,
+					createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+					tenantId: i.tenantId
+				}));
+				let c = yield* p.promise(() => R(r.mentions ?? [], i)), l = _({
+					kind: "typeid",
+					prefix: "cmt"
+				}, "_voltro_comments");
+				return yield* p.promise(() => o.insert("_voltro_comments", {
+					id: l,
+					threadId: s,
+					body: r.body,
+					authorSubjectId: a,
+					mentions: c,
+					editedAt: null,
+					createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+					tenantId: i.tenantId
+				})), N(), yield* L({
+					mentions: c,
+					author: a,
+					anchor: r.anchor,
+					threadId: s,
+					body: r.body,
+					tenantId: i.tenantId
+				}), {
+					threadId: s,
+					commentId: l
+				};
+			})
+		},
+		{
+			...s,
+			description: "Edit your own comment.",
+			execute: (e, r) => p.gen(function* () {
+				let i = e, a = (yield* p.promise(() => S("_voltro_comments", g("id", i.commentId), 1)))[0];
+				if (a === void 0) return yield* p.fail(new t({ id: i.commentId }));
+				let o = yield* p.promise(() => F(String(a.threadId)));
+				return o === void 0 ? yield* p.fail(new t({ id: i.commentId })) : (yield* P(String(o.anchor), r), String(a.authorSubjectId) === (M(r).id ?? "anonymous") ? (yield* p.promise(() => b.update("_voltro_comments", i.commentId, {
+					body: i.body,
+					editedAt: (/* @__PURE__ */ new Date()).toISOString()
+				})), N(), { ok: !0 }) : yield* p.fail(new n({ id: i.commentId })));
+			})
+		},
+		{
+			...f,
+			description: "Resolve or reopen a thread.",
+			execute: (e, n) => p.gen(function* () {
+				let r = e, i = yield* p.promise(() => F(r.threadId));
+				return i === void 0 ? yield* p.fail(new t({ id: r.threadId })) : (yield* P(String(i.anchor), n), yield* p.promise(() => b.update("_voltro_comment_threads", r.threadId, { status: r.resolved ? "resolved" : "open" })), N(), { ok: !0 });
+			})
+		},
+		{
+			...o,
+			description: "Delete your own comment (comments:moderate deletes any).",
+			execute: (e, r) => p.gen(function* () {
+				let i = e, a = (yield* p.promise(() => S("_voltro_comments", g("id", i.commentId), 1)))[0];
+				if (a === void 0) return yield* p.fail(new t({ id: i.commentId }));
+				let o = yield* p.promise(() => F(String(a.threadId)));
+				if (o === void 0) return yield* p.fail(new t({ id: i.commentId }));
+				yield* P(String(o.anchor), r);
+				let s = M(r);
+				return String(a.authorSubjectId) !== (s.id ?? "anonymous") && !s.scopes.includes(B) ? yield* p.fail(new n({ id: i.commentId })) : (yield* p.promise(async () => {
+					for (let e of await S("_voltro_comment_reactions", g("commentId", i.commentId))) await b.delete("_voltro_comment_reactions", String(e.id));
+					await b.delete("_voltro_comments", i.commentId);
+				}), N(), { ok: !0 });
+			})
+		},
+		{
+			...d,
+			description: "Toggle an emoji reaction on a comment.",
+			execute: (e, n) => p.gen(function* () {
+				let r = e, i = (yield* p.promise(() => S("_voltro_comments", g("id", r.commentId), 1)))[0];
+				if (i === void 0) return yield* p.fail(new t({ id: r.commentId }));
+				let a = yield* p.promise(() => F(String(i.threadId)));
+				if (a === void 0) return yield* p.fail(new t({ id: r.commentId }));
+				yield* P(String(a.anchor), n);
+				let o = M(n).id ?? "anonymous", s = (yield* p.promise(() => S("_voltro_comment_reactions", h(g("commentId", r.commentId), h(g("subjectId", o), g("emoji", r.emoji))), 1)))[0];
+				if (s !== void 0) return yield* p.promise(() => b.delete("_voltro_comment_reactions", String(s.id))), N(), { reacted: !1 };
+				let c = _({
+					kind: "typeid",
+					prefix: "cmtrx"
+				}, "_voltro_comment_reactions");
+				return yield* p.promise(() => b.insert("_voltro_comment_reactions", {
+					id: c,
+					commentId: r.commentId,
+					subjectId: o,
+					emoji: r.emoji
+				})), N(), { reacted: !0 };
+			})
+		},
+		{
+			...l,
+			description: "Stamp the caller's read marker for a thread.",
+			execute: (e, n) => p.gen(function* () {
+				let r = e;
+				if ((yield* p.promise(() => F(r.threadId))) === void 0) return yield* p.fail(new t({ id: r.threadId }));
+				let i = M(n).id ?? "anonymous", a = _({
+					kind: "typeid",
+					prefix: "cmtread"
+				}, "_voltro_comment_reads");
+				return yield* p.promise(() => b.upsert("_voltro_comment_reads", {
+					id: a,
+					threadId: r.threadId,
+					subjectId: i,
+					lastReadAt: (/* @__PURE__ */ new Date()).toISOString()
+				}, {
+					conflictColumns: ["threadId", "subjectId"],
+					update: ["lastReadAt"]
+				})), { ok: !0 };
+			})
+		},
+		{
+			...u,
+			description: "@-mention autocomplete over the app-declared directory, tenant-filtered.",
+			execute: (e, t) => p.promise(async () => {
+				let { query: n } = e;
+				if (v.resolveMentions === void 0) return [];
+				let r = M(t);
+				return (await v.resolveMentions({
+					query: n,
+					subject: {
+						id: r.id,
+						tenantId: r.tenantId
+					}
+				}).catch(() => [])).filter((e) => v.crossTenant === !0 || e.tenantId === void 0 || e.tenantId === null || e.tenantId === r.tenantId).map((e) => ({
+					subjectId: e.subjectId,
+					label: e.label
+				}));
+			})
+		}
+	], H = (e) => ({
+		kind: "json",
+		data: e
+	});
+	return C({
+		name: y,
+		baseName: j,
+		description: "Comment threads on any app entity — replies, resolve/reopen, @-mentions with notifications, reactions, unread — live over the reactive engine.",
+		permissions: ["inspect:read", "store:write"],
+		declaredScopes: [B],
+		extendSchema: { tables: [
+			D,
+			O,
+			k,
+			A
+		] },
+		routes: V,
+		rpcClientDescriptors: i,
+		inspectEndpoints: [{
+			method: "GET",
+			path: "/threads",
+			description: "Thread volume + the most recent threads (operator surface).",
+			handler: () => p.promise(async () => {
+				let e = await S("_voltro_comment_threads", void 0), t = await S("_voltro_comments", void 0), n = [...e].sort((e, t) => I(e.createdAt) > I(t.createdAt) ? -1 : 1).slice(0, 50).map((e) => ({
+					id: String(e.id),
+					anchor: String(e.anchor),
+					status: String(e.status),
+					createdBy: String(e.createdBy),
+					createdAt: I(e.createdAt),
+					comments: t.filter((t) => String(t.threadId) === String(e.id)).length
+				}));
+				return H({
+					stats: {
+						threads: e.length,
+						open: e.filter((e) => e.status !== "resolved").length,
+						comments: t.length
+					},
+					recent: n
+				});
+			})
+		}],
+		bindDataStore: (e) => {
+			b = e, x = e;
+		},
+		onActivate: (e) => p.sync(() => {
+			v.access?.viaEntity === void 0 && v.access?.scope === void 0 && e.logger.warn("comments: no access rule declared — EVERY read and write will be refused (fail-closed). Set commentsPlugin({ access: { viaEntity } }) or { access: { scope } }."), e.logger.info("comments active", { mentions: v.resolveMentions !== void 0 });
+		}),
+		onDeactivate: () => p.sync(() => {
+			b = void 0, x = void 0;
+		})
+	});
+}, P = () => "plugin-comments";
+//#endregion
+export { e as CommentAccessRefused, t as CommentNotFound, n as CommentNotYours, k as commentReactionsTable, A as commentReadsTable, D as commentThreadsTable, r as commentsFeed, N as commentsPlugin, O as commentsTable, P as pluginComments };

package/dist/rpc.d.ts

@@ -0,0 +1,129 @@
+import { MutationProcedureDescriptor } from '@voltro/protocol';
+import { PluginRpcClientDescriptor } from '@voltro/protocol';
+import { QueryProcedureDescriptor } from '@voltro/protocol';
+import { ReactivityChannel } from '@voltro/protocol';
+import { Schema } from 'effect';
+
+/** The anchor's access check refused the caller — or no access rule is
+ *  declared at all (fail-closed: undeclared access is a refusal, not a pass).
+ *  Also the answer for a thread whose anchor row no longer resolves (a
+ *  soft-deleted entity): already-delivered mention notifications keep
+ *  pointing here, and this is what they find — "no longer available", not a
+ *  leak and not a crash. */
+declare class CommentAccessRefused extends CommentAccessRefused_base {
+}
+
+declare const CommentAccessRefused_base: Schema.TaggedErrorClass<CommentAccessRefused, "CommentAccessRefused", {
+    readonly _tag: Schema.tag<"CommentAccessRefused">;
+} & {
+    anchor: typeof Schema.String;
+    reason: typeof Schema.String;
+}>;
+
+/** The thread / comment id resolves to nothing the caller may see. */
+declare class CommentNotFound extends CommentNotFound_base {
+}
+
+declare const CommentNotFound_base: Schema.TaggedErrorClass<CommentNotFound, "CommentNotFound", {
+    readonly _tag: Schema.tag<"CommentNotFound">;
+} & {
+    id: typeof Schema.String;
+}>;
+
+/** Only the author edits or deletes their own comment (a `comments:moderate`
+ *  scope overrides for delete). */
+declare class CommentNotYours extends CommentNotYours_base {
+}
+
+declare const CommentNotYours_base: Schema.TaggedErrorClass<CommentNotYours, "CommentNotYours", {
+    readonly _tag: Schema.tag<"CommentNotYours">;
+} & {
+    id: typeof Schema.String;
+}>;
+
+/** One push channel for the whole surface: every comment write publishes, and
+ *  `comments.list` re-runs for subscribers. Table-granular by design for now —
+ *  the read-set work (plan 01 P3) is the named narrowing. */
+export declare const commentsFeed: ReactivityChannel;
+
+export declare const commentsRpcClientImports: ReadonlyArray<PluginRpcClientDescriptor>;
+
+export declare const createDescriptor: MutationProcedureDescriptor<"comments.create", Schema.Struct<{
+    anchor: typeof Schema.String;
+    body: typeof Schema.String;
+    /** Reply into an existing thread; absent opens a new thread. */
+    threadId: Schema.optional<typeof Schema.String>;
+    mentions: Schema.optional<Schema.Array$<typeof Schema.String>>;
+}>, Schema.Struct<{
+    threadId: typeof Schema.String;
+    commentId: typeof Schema.String;
+}>, Schema.Union<[typeof CommentAccessRefused, typeof CommentNotFound]>>;
+
+export declare const deleteDescriptor: MutationProcedureDescriptor<"comments.delete", Schema.Struct<{
+    commentId: typeof Schema.String;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, Schema.Union<[typeof CommentAccessRefused, typeof CommentNotFound, typeof CommentNotYours]>>;
+
+export declare const editDescriptor: MutationProcedureDescriptor<"comments.edit", Schema.Struct<{
+    commentId: typeof Schema.String;
+    body: typeof Schema.String;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, Schema.Union<[typeof CommentAccessRefused, typeof CommentNotFound, typeof CommentNotYours]>>;
+
+export declare const listDescriptor: QueryProcedureDescriptor<"comments.list", Schema.Struct<{
+    anchor: typeof Schema.String;
+}>, Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    anchor: typeof Schema.String;
+    status: Schema.Literal<["open", "resolved"]>;
+    createdBy: typeof Schema.String;
+    createdAt: typeof Schema.String;
+    comments: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        threadId: typeof Schema.String;
+        body: typeof Schema.String;
+        authorSubjectId: typeof Schema.String;
+        mentions: Schema.Array$<typeof Schema.String>;
+        editedAt: Schema.NullOr<typeof Schema.String>;
+        createdAt: typeof Schema.String;
+        reactions: Schema.Array$<Schema.Struct<{
+            emoji: typeof Schema.String;
+            count: typeof Schema.Number;
+            /** Whether the CALLER reacted with this emoji (drives the toggle UI). */
+            mine: typeof Schema.Boolean;
+        }>>;
+    }>>;
+    /** Comments newer than the caller's `lastReadAt` for this thread. */
+    unreadCount: typeof Schema.Number;
+}>>, typeof CommentAccessRefused>;
+
+export declare const markReadDescriptor: MutationProcedureDescriptor<"comments.markRead", Schema.Struct<{
+    threadId: typeof Schema.String;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, typeof CommentNotFound>;
+
+export declare const mentionSearchDescriptor: QueryProcedureDescriptor<"comments.mentionSearch", Schema.Struct<{
+    query: typeof Schema.String;
+}>, Schema.Array$<Schema.Struct<{
+    subjectId: typeof Schema.String;
+    label: typeof Schema.String;
+}>>, typeof Schema.Never>;
+
+export declare const reactDescriptor: MutationProcedureDescriptor<"comments.react", Schema.Struct<{
+    commentId: typeof Schema.String;
+    emoji: typeof Schema.String;
+}>, Schema.Struct<{
+    reacted: typeof Schema.Boolean;
+}>, Schema.Union<[typeof CommentAccessRefused, typeof CommentNotFound]>>;
+
+export declare const resolveDescriptor: MutationProcedureDescriptor<"comments.resolve", Schema.Struct<{
+    threadId: typeof Schema.String;
+    resolved: typeof Schema.Boolean;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, Schema.Union<[typeof CommentAccessRefused, typeof CommentNotFound]>>;
+
+export { }