fedipod-bb 0.2.0

package/src/publish.mjs

@@ -0,0 +1,244 @@
+// publish.mjs — writing the forum's documents to the pod, and only the ones
+// that changed. Every paged collection keeps the digest of each page it last
+// wrote, as FediPod's outbox does, so a sealed page is never re-PUT and a
+// republish of an unchanged forum writes nothing.
+//
+// A call takes `{ remote, store, urls }`: the pod transport, the owner-only
+// state (a PodStore), and the category's or forum's urls.
+
+import crypto from 'node:crypto';
+import * as collection from 'fedipod/pod/collection.mjs';
+import * as podNotes from 'fedipod/pod/notes.mjs';
+import { sanitizeHtml, orderedCollection } from 'fedipod/core/wire.mjs';
+import * as fwire from './wire.mjs';
+import * as topics from './topics.mjs';
+
+export const digestOf = (doc) => crypto.createHash('sha256').update(JSON.stringify(doc)).digest('hex').slice(0, 16);
+
+// One topic: its pages and its head. Returns how many documents were written.
+export async function publishTopic({ remote, store, urls }, tid, { force = false } = {}) {
+  const doc = topics.get(store, tid);
+  if (!doc) throw new Error(`publishTopic: no such topic ${tid}`);
+  const id = urls.topic(tid);
+  const { index, pages } = fwire.topicPaging(doc.posts.map(p => p.id), doc.index);
+  const before = force ? {} : (doc.pages || {});
+  const after = {};
+  let wrote = 0;
+  for (let i = 0; i < pages.length; i++) {
+    const n = i + 1;
+    const page = fwire.topicPage({ id, n, items: pages[i], pageCount: pages.length });
+    const digest = digestOf(page);
+    after[n] = digest;
+    if (before[n] === digest) continue;
+    // The topic container is public-Read; a page inherits it.
+    await collection.writePage(remote, urls.topicPage(tid, n), page);
+    wrote++;
+  }
+  for (const n of Object.keys(doc.pages || {}).map(Number).filter(n => n > pages.length)) {
+    await collection.dropPage(remote, urls.topicPage(tid, n));
+  }
+  const entry = topics.list(store).find(t => t.tid === tid);
+  const head = fwire.topicHead({
+    id, name: doc.title, category: urls.actor, total: doc.posts.length, pageCount: pages.length,
+    closed: store.read('topics.json', []).find(t => t.tid === tid)?.locked ? (doc.closedAt || new Date().toISOString()) : null,
+    published: entry?.created || doc.posts[0]?.published || null,
+    updated: doc.posts.length > 1 ? (entry?.last || null) : null,
+  });
+  const headDigest = digestOf(head);
+  if (force || headDigest !== doc.headDigest) {
+    await collection.writeHead(remote, id, head);
+    wrote++;
+  }
+  store.write(topics.topicDoc(tid), { ...doc, index, pages: after, headDigest });
+  return wrote;
+}
+
+// The category's topic list. Oldest first in the record; the pages read
+// newest first. Kept in `published.json` beside the group's own digests.
+export async function publishTopicIndex({ remote, store, urls }, { force = false } = {}) {
+  const seen = store.read('published.json', {});
+  const order = topics.list(store).map(t => urls.topic(t.tid));
+  const { index, pages } = fwire.topicsPaging(order, seen.topicsIndex || []);
+  const before = force ? {} : (seen.topicsPages || {});
+  const after = {};
+  let wrote = 0;
+  for (let i = 0; i < pages.length; i++) {
+    const n = i + 1;
+    const page = fwire.topicsPage({ id: urls.topics, n, items: pages[i] });
+    const digest = digestOf(page);
+    after[n] = digest;
+    if (before[n] === digest) continue;
+    // Under ap/ directly, whose container is owner-only: the rule is set when
+    // a page is first created, as the outbox does.
+    await collection.writePage(remote, urls.topicsPage(n), page, { publicRead: !before[n] || force });
+    wrote++;
+  }
+  for (const n of Object.keys(seen.topicsPages || {}).map(Number).filter(n => n > pages.length)) {
+    await collection.dropPage(remote, urls.topicsPage(n));
+  }
+  const head = fwire.topicsHead({ id: urls.topics, category: urls.actor, total: order.length, pageCount: pages.length });
+  const headDigest = digestOf(head);
+  if (force || headDigest !== seen.topicsHead) {
+    await collection.writeHead(remote, urls.topics, head, { publicRead: !seen.topicsHead || force });
+    wrote++;
+  }
+  store.write('published.json', { ...store.read('published.json', {}), topicsPages: after, topicsIndex: index, topicsHead: headDigest });
+  return wrote;
+}
+
+// The forum's two flat lists, each written only when it changed.
+export async function publishCategories({ remote, store, urls }, actorIds, { force = false } = {}) {
+  return flat({ remote, store }, 'categories', urls.categories, fwire.categoriesCollection(urls.categories, actorIds), force);
+}
+
+// How many of the newest posts the forum keeps an index of.
+// How many of the newest posts the forum keeps an index of. A page shows
+// thirty at a time and asks for more; this is the whole of what it can ask
+// for, and the topics themselves hold everything older.
+export const LATEST_MAX = 500;
+
+export async function publishLatest({ remote, store, urls }, { force = false } = {}) {
+  const items = store.read('latest.json', []).slice(0, LATEST_MAX).map(e => e.copy);
+  return flat({ remote, store }, 'latest', urls.latest, fwire.latestCollection(urls.latest, items), force);
+}
+
+export async function publishAdministrators({ remote, store, urls }, actorIds, { force = false } = {}) {
+  return flat({ remote, store }, 'administrators', urls.administrators, fwire.administratorsCollection(urls.administrators, actorIds), force);
+}
+
+// The reader list of a private category, written where only those readers can
+// read it. This is the document a member's own pod copies into the access rule
+// on the container it writes that category's posts into: the forum cannot
+// write rules on somebody else's pod, so it publishes who the rule must name
+// and each member's own browser writes it.
+//
+// An open category has no list. If it had one it is taken down, so a category
+// turned open cannot leave a stale one behind for a member's browser to copy.
+export async function publishMembers(cat, readers, { force = false } = {}) {
+  const url = cat.urls.members;
+  const seen = cat.store.read('published.json', {});
+  if (!readers) {
+    if (!seen.members) return 0;
+    await cat.remote.delete(url).catch(() => {});
+    cat.store.write('published.json', { ...cat.store.read('published.json', {}), members: null });
+    return 0;
+  }
+  const doc = fwire.membersCollection(url, readers);
+  const digest = digestOf(doc);
+  if (!force && seen.members === digest) return 0;
+  await cat.remote.putJson(url, doc);
+  // Not public, and not owner-only either: the people named are the people who
+  // may read it.
+  await cat.remote.setAcl(url, [], { readAgents: readers });
+  cat.store.write('published.json', { ...cat.store.read('published.json', {}), members: digest });
+  return readers.length;
+}
+
+// `force` republishes the document; the rule beside it is written once, when
+// the document first is. Forcing used to rewrite the rule too, so every post,
+// edit and vote was two writes where one would do.
+async function flat({ remote, store }, key, url, doc, force) {
+  const seen = store.read('published.json', {});
+  const digest = digestOf(doc);
+  if (!force && seen[key] === digest) return 0;
+  await collection.writeFlat(remote, url, doc, { publicRead: !seen[key] });
+  store.write('published.json', { ...store.read('published.json', {}), [key]: digest });
+  return 1;
+}
+
+// The category's pinned topics, as its featured collection. The category's
+// own publisher writes a featured list too, of its pinned POSTS, which a
+// forum has none of: a forced profile publish wrote that empty list over the
+// pinned topics. This one is written after it, from the topics' flags.
+export async function publishPinnedTopics(cat) {
+  const ids = topics.list(cat.store).filter(t => t.pinned).map(t => cat.urls.topic(t.tid));
+  await collection.writeFlat(cat.remote, cat.urls.featured, orderedCollection(cat.urls.featured, ids), { publicRead: true });
+  return ids;
+}
+
+// A member's post, as verified at its origin, made readable for the website.
+// Content is sanitised again on the way in; nothing else is changed, so the
+// copy says what the author said, under the author's own id. Returns the
+// copy's url.
+export async function cachePost({ remote, urls }, note, { topic = null, replies = null, likes = null, dislikes = null } = {}) {
+  const copy = { ...note };
+  if (topic) copy.context = topic;
+  if (!copy.audience) copy.audience = urls.actor;
+  // How many answered THIS post, as the forum counts them (FEP-7458 shape).
+  // The author's own replies collection is theirs and says something else:
+  // this is what the forum holds, in the topic it placed the post in.
+  if (Number.isFinite(replies)) copy.replies = { type: 'Collection', totalItems: replies };
+  // How many said they liked it (AS2 `likes`), and how many voted it down.
+  // A Dislike is an activity AS2 has; a property for a count of them is not,
+  // so `dislikes` is the forum's own word, shaped like `likes`, in the copy
+  // the forum's page reads. Read here, the page no longer asks the pod for a
+  // count beside every post it shows.
+  if (Number.isFinite(likes)) copy.likes = { type: 'Collection', totalItems: likes };
+  if (Number.isFinite(dislikes)) copy.dislikes = { type: 'Collection', totalItems: dislikes };
+  if (typeof copy.content === 'string') copy.content = sanitizeHtml(copy.content);
+  if (!copy['@context']) copy['@context'] = 'https://www.w3.org/ns/activitystreams';
+  const url = urls.cached(note.id);
+  await podNotes.write(remote, url, copy);
+  return url;
+}
+
+// How many voted a post DOWN. ActivityStreams has the Dislike activity and no
+// property to publish a count of them, so none is invented here: the count is
+// an ordinary Collection published beside the post's copy, at that copy's
+// address with `-dislikes` after it. Only terms already in use appear in it.
+export async function publishDislikes({ remote, urls }, postId, n) {
+  const url = urls.cached(postId) + '-dislikes';
+  if (!n) { await remote.delete(url).catch(() => {}); return 0; }
+  await podNotes.write(remote, url, {
+    '@context': 'https://www.w3.org/ns/activitystreams',
+    id: url, type: 'Collection', totalItems: n,
+    summary: 'How many disliked the post this is named for',
+  });
+  return n;
+}
+
+// Who wrote a post, for the website: the author's actor as the host fetched
+// it, cut down to what a reader shows — name, handle, picture — filed beside
+// the posts under the digest of the actor's id. A FediPod actor's id does
+// not carry its handle; this is where a browser learns it.
+export async function cacheAuthor({ remote, urls }, actor) {
+  if (!actor?.id) return null;
+  const icon = typeof actor.icon === 'string' ? actor.icon : actor.icon?.url;
+  const card = {
+    '@context': 'https://www.w3.org/ns/activitystreams',
+    id: actor.id, type: actor.type || 'Person',
+    ...(actor.preferredUsername ? { preferredUsername: String(actor.preferredUsername).slice(0, 100) } : {}),
+    ...(actor.name ? { name: String(actor.name).slice(0, 200) } : {}),
+    ...(icon && /^https?:\/\//u.test(icon) ? { icon: { type: 'Image', url: String(icon).slice(0, 2048) } } : {}),
+    ...(actor.url && typeof actor.url === 'string' ? { url: actor.url } : {}),
+  };
+  const url = urls.cached(actor.id);
+  await podNotes.write(remote, url, card);
+  return url;
+}
+
+// The copy of a post that is gone: a Tombstone in its place.
+export async function tombstoneCached({ remote, urls }, postId, { formerType = 'Note' } = {}) {
+  const url = urls.cached(postId);
+  await podNotes.write(remote, url, fwire.cachedTombstone({ id: url, formerType }));
+  return url;
+}
+
+// A public sign of life: when the forum was last hosted, and by which
+// version. The website reads it to say how current the forum is, since the
+// lease that really says so is owner-only.
+const heartbeatRuled = new WeakSet();   // remotes whose heartbeat rule this process has stated
+export async function publishHeartbeat({ remote, urls }, { version = null, at = new Date().toISOString() } = {}) {
+  // Under the advertised face, like every read document, so a fronted forum's
+  // reader finds it at the front and the transport lands it on the pod.
+  // Typed and named like the actor: a pod refuses to hand a plain-JSON
+  // document to a reader asking for ActivityPub, and the front asks that way.
+  const url = urls.actor.replace(/ap\/actor$/u, '') + 'ap/heartbeat';
+  await remote.putJson(url, { at, ...(version ? { version } : {}) }, 'application/activity+json');
+  // The rule never changes: stated once per process, and only if it differs.
+  if (!heartbeatRuled.has(remote)) {
+    await remote.setAcl(url, ['Read'], { ifChanged: true });
+    heartbeatRuled.add(remote);
+  }
+  return url;
+}

package/src/run.mjs

@@ -0,0 +1,52 @@
+// run.mjs — running a forum on this machine: connect, with retries while the
+// pod is not answering, then host or watch until the process is told to stop.
+
+import fs from 'node:fs';
+import { ForumAgent } from './forum-agent.mjs';
+
+export async function runForum({ home, log = (...a) => console.log('[bb]', ...a) } = {}) {
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  const agent = new ForumAgent({ home, log });
+
+  let up = false;
+  for (let attempt = 1; !up; attempt++) {
+    try {
+      up = await agent.connect();
+      if (!up) { log('nothing to host — run init first'); return null; }
+    } catch (e) {
+      // The attempt that just died may have taken the lease on its way in.
+      // Give it back, or the next attempt finds the forum held by a process
+      // that is this one, and waits five minutes to be told it may act. The
+      // release is a pod write too, and a pod that refused the start is
+      // usually still refusing: try it until it takes.
+      for (let i = 0; i < 4; i++) {
+        try { await agent.lease?.release(); break; } catch { await new Promise(r => { setTimeout(r, 8000); }); }
+      }
+      const wait = Math.min(15 * attempt, 120);
+      log(`start failed (${e.message}) — trying again in ${wait}s`);
+      await new Promise(r => { setTimeout(r, wait * 1000); });
+    }
+  }
+
+  // Every timer in the agent is unreferenced; nothing else would hold the
+  // process open, and the host exited quietly once the push socket went
+  // idle. This holds it.
+  const hold = setInterval(() => {}, 1 << 30);
+  const shutdown = () => {
+    clearInterval(hold);
+    agent.stop().finally(() => process.exit(0));
+    setTimeout(() => process.exit(0), 3000).unref();
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  return agent;
+}
+
+// Whether a home holds a forum rather than a person or a group. The credential
+// names the root its documents live under, and a forum's is its own.
+export function isForumHome(home) {
+  try {
+    const cred = JSON.parse(fs.readFileSync(`${home.replace(/\/$/u, '')}/credential.json`, 'utf8'));
+    return typeof cred.root === 'string' && cred.root.replace(/\/$/u, '') === 'fedipod-bb';
+  } catch { return false; }
+}

package/src/settings.mjs

@@ -0,0 +1,186 @@
+// settings.mjs — changing what the forum IS, asked for the way everything
+// else is asked for: a moderator publishes the request at their own pod and
+// the forum fetches it back from there before acting (FEP-fe34).
+//
+// Every request is ordinary ActivityStreams. A category is created by a
+// Create of a Group naming the forum; a name is changed by an Update; who
+// moderates and who may read are Add and Remove naming the collection they
+// belong to. Nothing here invents a word.
+
+const idOf = (v) => (typeof v === 'string' ? v : v?.id);
+const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/u;
+
+// A page reading the forum through a Gateway names what it asks about by the
+// address it read there; read from the pod it names the pod's own. The queue
+// container has no published address at all, since nothing about it is
+// published. So both sides are put in the same space before they are compared,
+// and an ask means what it says whichever address it arrived under.
+const onPod = (forum, u) => (typeof u === 'string' && forum?.toPod ? forum.toPod(u) : u);
+const same = (forum, a, b) => { if (!a || !b) return false; if (a === b) return true; const pa = onPod(forum, a); return !!pa && pa === onPod(forum, b); };
+
+// Which of these a delivered activity is, if any. The forum's own actor or
+// one of its collections has to be named, or it is somebody else's business.
+export function isSettingsAsk(forum, activity) {
+  const t = activity?.type;
+  const target = idOf(activity?.target);
+  const object = activity?.object;
+  const site = forum.site;
+  if (t === 'Create' && object && typeof object === 'object' && object.type === 'Group') {
+    return same(forum, idOf(activity.target), site.actor);
+  }
+  if (t === 'Update' && object && typeof object === 'object') {
+    const id = idOf(object);
+    return same(forum, id, site.actor) || forum.categories.some(c => same(forum, c.urls.actor, id));
+  }
+  if (t === 'Add' || t === 'Remove') {
+    if (!target) return false;
+    if (same(forum, target, site.administrators) || same(forum, target, site.mod)) return true;
+    return forum.categories.some(c => same(forum, target, c.urls.moderators) || same(forum, target, c.urls.members));
+  }
+  return false;
+}
+
+// Apply one. Returns what changed, for the record the moderators read.
+export async function applySettings(forum, activity) {
+  const t = activity?.type;
+  const object = activity?.object;
+  const target = idOf(activity?.target);
+  const site = forum.site;
+  const cfg = () => forum.store.getConfig();
+  // The record on the pod IS the forum: everything published is written from
+  // it, and a start reads it back. A change that never reached it was still
+  // published, and the next start quietly republished the old lists over the
+  // top — a moderator added, announced, and gone again with nothing said. So
+  // the change is written first, and a write that fails puts memory back and
+  // says so instead of going on to publish.
+  const save = async (next) => {
+    const before = cfg();
+    forum.store.setConfig({ ...before, ...next });
+    forum.config = forum.store.getConfig();
+    try {
+      await forum.store.flush();
+    } catch (e) {
+      forum.store.setConfig(before);
+      forum.config = forum.store.getConfig();
+      throw new Error(`the forum's own record could not be written (${e.message}) — nothing was changed`);
+    }
+  };
+
+  if (t === 'Create' && object?.type === 'Group') {
+    const slug = String(object.preferredUsername || '').toLowerCase();
+    if (!SLUG.test(slug)) throw new Error(`not a category slug: ${slug}`);
+    const cats = cfg().categories || [];
+    if (cats.some(c => c.slug === slug)) return { unchanged: slug };
+    // Private: joining is approved by a moderator (AS2's own
+    // manuallyApprovesFollowers) and only those admitted may read it. It
+    // starts readable by the moderators, since a category nobody can read is
+    // a category nobody can moderate.
+    const priv = object.manuallyApprovesFollowers === true;
+    const next = {
+      categories: [...cats, { slug, name: String(object.name || slug).slice(0, 200), private: priv }],
+      republish: true,
+    };
+    if (priv) {
+      next.membersOnly = [...new Set([...(cfg().membersOnly || []), slug])];
+      next.memberWebIds = { ...(cfg().memberWebIds || {}), [slug]: [...(cfg().moderatorWebIds || [])] };
+      next.reprovision = true;
+    }
+    await save(next);
+    return { category: slug, private: priv };
+  }
+
+  if (t === 'Update' && object && typeof object === 'object') {
+    const id = idOf(object);
+    const name = typeof object.name === 'string' ? object.name.trim().slice(0, 200) : '';
+    if (same(forum, id, site.actor)) {
+      if (!name) return {};
+      await save({ name, republish: true });
+      return { forum: name };
+    }
+    const cat = forum.categories.find(c => same(forum, c.urls.actor, id));
+    if (!cat) return {};
+    const out = {};
+    if (name) {
+      await save({ categories: (cfg().categories || []).map(c => (c.slug === cat.slug ? { ...c, name } : c)), republish: true });
+      out.category = cat.slug;
+      out.name = name;
+    }
+    // Open or private is the forum's OWN setting, and this is the only thing
+    // that changes it: not who joins, not who is named a member, not how many
+    // of either there are. AS2 already says it on a Group — a private
+    // category approves each join — so `manuallyApprovesFollowers` is the
+    // word for it, and the actor the forum publishes carries the same one.
+    if ('manuallyApprovesFollowers' in object) {
+      const priv = object.manuallyApprovesFollowers === true;
+      const closed = new Set(cfg().membersOnly || []);
+      if (priv) closed.add(cat.slug); else closed.delete(cat.slug);
+      // Turning a category private with nobody named yet leaves its
+      // moderators able to read it: a category nobody can read is a category
+      // nobody can moderate.
+      const named = { ...(cfg().memberWebIds || {}) };
+      if (priv && !(named[cat.slug] || []).length) named[cat.slug] = [...(cfg().moderatorWebIds || [])];
+      await save({
+        membersOnly: [...closed], memberWebIds: named,
+        categories: (cfg().categories || []).map(c => (c.slug === cat.slug ? { ...c, private: priv } : c)),
+        republish: true, reprovision: true,
+      });
+      out.category = cat.slug;
+      out.private = priv;
+    }
+    return out;
+  }
+
+  const who = idOf(object);
+  if ((t === 'Add' || t === 'Remove') && who) {
+    const on = t === 'Add';
+    // Who moderates: an actor id, which is what the wire and FEP-1b12 use.
+    const cat = forum.categories.find(c => same(forum, target, c.urls.moderators) || same(forum, target, c.urls.members));
+    if (same(forum, target, site.administrators) || (cat && same(forum, target, cat.urls.moderators))) {
+      const held = new Set(cfg().moderators || []);
+      if (on) held.add(who); else held.delete(who);
+      await save({ moderators: [...held], republish: true });
+      // The forum's own list is what the website reads, so it is written now
+      // rather than at the next start.
+      await forum.republishAdministrators?.().catch(() => {});
+      return { moderators: held.size };
+    }
+    // Who may read a members-only category, and who may read the queue: a
+    // WebID, because only a WebID can be named in a pod's own access rule.
+    // A member named by their Fediverse actor rather than their WebID: what
+    // a moderator has in front of them when they admit a join request. The
+    // WebID is the pod the actor lives on, checked against that pod's own
+    // profile before it is granted anything.
+    if (cat && same(forum, target, cat.urls.members) && !/#|\/profile\//u.test(who)) {
+      const webid = await forum.webIdOf(who).catch(() => null);
+      if (!webid) throw new Error(`no WebID could be found for ${who}`);
+      return applySettings(forum, { ...activity, object: webid });
+    }
+    if (cat && same(forum, target, cat.urls.members)) {
+      const named = { ...(cfg().memberWebIds || {}) };
+      const held = new Set(named[cat.slug] || []);
+      if (on) held.add(who); else held.delete(who);
+      named[cat.slug] = [...held];
+      // Naming a member says NOTHING about whether the category is open or
+      // private. That is the forum's own setting and only an Update changes
+      // it; in an open category this list simply sits there unused.
+      await save({ memberWebIds: named, republish: true, reprovision: true });
+      return { category: cat.slug, members: held.size };
+    }
+    // Who may read the queue, named the way every moderator is named: by
+    // their Fediverse actor. The rule that holds the queue is the pod's own
+    // and can only name a WebID, so the pod behind the actor is looked up
+    // here; an account with no pod cannot be granted it at all.
+    if (same(forum, target, site.mod) && !/#|\/profile\//u.test(who)) {
+      const webid = await forum.webIdOf(who).catch(() => null);
+      if (!webid) throw new Error(`no WebID could be found for ${who}`);
+      return applySettings(forum, { ...activity, object: webid });
+    }
+    if (same(forum, target, site.mod)) {
+      const held = new Set(cfg().moderatorWebIds || []);
+      if (on) held.add(who); else held.delete(who);
+      await save({ moderatorWebIds: [...held], republish: true, reprovision: true });
+      return { moderatorWebIds: held.size };
+    }
+  }
+  return {};
+}

package/src/topics.mjs

@@ -0,0 +1,165 @@
+// topics.mjs — a category's topic record: what the host knows about its
+// topics and their posts, kept in the category's owner-only state as one
+// document per topic and one list of them. The published collections are
+// built from this record; the record is never rebuilt from them.
+//
+// `topics.json`      [{ tid, title, op, author, created, last, count, pinned, locked }]
+// `topics/<tid>.json` { tid, title, posts: [{ id, author, published, inReplyTo, cached }],
+//                       index: [[ids]], pages: { n: digest }, headDigest }
+
+import { isTid } from './urls.mjs';
+
+export const TOPICS = 'topics.json';
+// Flat, not `topics/<tid>.json`: state is loaded by listing ONE container and
+// reading the .json in it, so a document in a folder below it is written, never
+// read back, and the forum loses every topic when it restarts.
+export const topicDoc = (tid) => `topic-${tid}.json`;
+export const topicDocOld = (tid) => `topics/${tid}.json`;
+
+// A title becomes the tail of a topic id: lower case, letters digits and
+// hyphens, at most eighty characters, never empty.
+export function slugOfTitle(title) {
+  const s = String(title || '').toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/gu, '').slice(0, 79)
+    .replace(/-+$/u, '');
+  return s || 'topic';
+}
+
+// A topic id that is not yet taken in this category.
+export function mintTid(store, title, published = new Date().toISOString()) {
+  const month = String(published).slice(0, 7);
+  const base = `${month}-${slugOfTitle(title)}`;
+  const taken = new Set(list(store).map(t => t.tid));
+  let tid = base;
+  for (let n = 2; taken.has(tid); n++) tid = `${base.slice(0, 76)}-${n}`;
+  return tid;
+}
+
+export function list(store) { return store.read(TOPICS, []); }
+
+export function get(store, tid) {
+  if (!isTid(tid)) return null;
+  return store.read(topicDoc(tid), null);
+}
+
+// Which topic holds a post, by the post's id.
+export function topicOf(store, postId) {
+  for (const t of list(store)) {
+    const doc = get(store, t.tid);
+    if (doc?.posts?.some(p => p.id === postId)) return t.tid;
+  }
+  return null;
+}
+
+// Open a topic with its first post. Returns the topic id.
+export function open(store, { title, post, tid = null }) {
+  const id = tid || mintTid(store, title, post.published);
+  if (get(store, id)) throw new Error(`topic already open: ${id}`);
+  const entry = { tid: id, title: String(title), op: post.id, author: post.author,
+    created: post.published, last: post.published, count: 1, pinned: false, locked: false };
+  store.write(TOPICS, [...list(store), entry]);
+  store.write(topicDoc(id), { tid: id, title: entry.title, posts: [post], index: [], pages: {}, headDigest: null });
+  return id;
+}
+
+// Add a post to a topic. A post already there is not added twice.
+export function append(store, tid, post) {
+  const doc = get(store, tid);
+  if (!doc) throw new Error(`no such topic: ${tid}`);
+  if (doc.posts.some(p => p.id === post.id)) return false;
+  doc.posts.push(post);
+  store.write(topicDoc(tid), doc);
+  const topics = list(store).map(t => (t.tid === tid
+    ? { ...t, count: doc.posts.length, last: post.published > t.last ? post.published : t.last } : t));
+  store.write(TOPICS, topics);
+  return true;
+}
+
+// Take a post out of a topic. Its page stays one short (wire.topicPaging).
+export function remove(store, tid, postId) {
+  const doc = get(store, tid);
+  if (!doc) return false;
+  const before = doc.posts.length;
+  doc.posts = doc.posts.filter(p => p.id !== postId);
+  if (doc.posts.length === before) return false;
+  store.write(topicDoc(tid), doc);
+  store.write(TOPICS, list(store).map(t => (t.tid === tid ? { ...t, count: doc.posts.length } : t)));
+  return true;
+}
+
+export function setTitle(store, tid, title) {
+  const doc = get(store, tid);
+  if (!doc) return null;
+  store.write(topicDoc(tid), { ...doc, title });
+  store.write(TOPICS, list(store).map(t => (t.tid === tid ? { ...t, title } : t)));
+  return title;
+}
+
+export function setFlags(store, tid, { pinned, locked } = {}) {
+  store.write(TOPICS, list(store).map(t => (t.tid === tid
+    ? { ...t, ...(pinned !== undefined ? { pinned: !!pinned } : {}), ...(locked !== undefined ? { locked: !!locked } : {}) } : t)));
+}
+
+// ── placing a carried post ─────────────────────────────────────────────
+const idOf = (v) => (typeof v === 'string' ? v : v?.id);
+const MAX_PARENT_HOPS = 20;
+
+// A post's title: what it says it is, else its first words.
+export function titleOf(note) {
+  if (typeof note?.name === 'string' && note.name.trim()) return note.name.trim().slice(0, 200);
+  const text = String(note?.content || '').replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
+  const words = text.split(' ').slice(0, 12).join(' ');
+  return (words.length < text.length ? words + '…' : words) || 'Untitled';
+}
+
+// Which topic a carried post belongs to, and put it there. In order: the
+// topic its `context` names; the topic its reply chain leads to, walking up
+// through parents fetched at their origins; else a new topic with this post
+// as its opening. Returns the topic id.
+export async function assign({ store, urls, fetchAP }, note, activity = null) {
+  const post = {
+    id: note.id,
+    author: idOf([].concat(note.attributedTo || [])[0]) || null,
+    published: note.published || new Date().toISOString(),
+    inReplyTo: idOf(note.inReplyTo) || null,
+    cached: urls.cached(note.id),
+  };
+  const named = idOf(note.context);
+  if (named && named.startsWith(urls.topicContainer)) {
+    const tail = named.slice(urls.topicContainer.length);
+    const tid = get(store, tail) ? tail : tail.replace(/-\d+$/u, '');
+    if (get(store, tid)) { append(store, tid, post); return tid; }
+  }
+  let parent = post.inReplyTo;
+  for (let hop = 0; parent && hop < MAX_PARENT_HOPS; hop++) {
+    const tid = topicOf(store, parent);
+    if (tid) { append(store, tid, post); return tid; }
+    const doc = await fetchAP(parent).catch(() => null);
+    // A post whose own conversation is one of ours: the walk can stop, even
+    // though the post in hand said nothing about it. This is what lets a
+    // reply written on a server that knows about conversations but not about
+    // us — and any post quoting another's `context` — land where it belongs
+    // (FEP-7888, and the reading half of FEP-f228).
+    const theirs = idOf(doc?.context);
+    if (theirs && theirs.startsWith(urls.topicContainer)) {
+      const tail = theirs.slice(urls.topicContainer.length);
+      const named = get(store, tail) ? tail : tail.replace(/-\d+$/u, '');
+      if (get(store, named)) { append(store, named, post); return named; }
+    }
+    parent = idOf(doc?.inReplyTo) || null;
+  }
+  // The name of a new topic, in order: what the opening activity called it —
+  // a client here asks for a topic BY NAME, which is a different thing from
+  // the post's own title — then the post's title, then its first words, for
+  // everything arriving from servers that have no notion of a topic.
+  const asked = typeof activity?.name === 'string' ? activity.name.trim().slice(0, 200) : '';
+  return open(store, { title: asked || titleOf(note), post });
+}
+
+// A topic gone from the record: its list entry and its document.
+export function drop(store, tid) {
+  if (!get(store, tid)) return false;
+  store.write(TOPICS, list(store).filter(t => t.tid !== tid));
+  store.remove?.(topicDoc(tid));
+  return true;
+}