fedipod-server 0.11.0 → 0.13.0

package/lib/core/publisher/notes.mjs

@@ -0,0 +1,188 @@
+// notes.mjs — a note of the actor's own going up: the containers it needs
+// (media, and the owner-only one private posts live in), who it mentions,
+// publishing it, and editing it afterwards.
+
+import crypto from 'node:crypto';
+import * as wire from '../wire.mjs';
+import * as containers from '../../pod/containers.mjs';
+import * as podNotes from '../../pod/notes.mjs';
+
+// Media container on the remote pod — public-Read like notes, created lazily
+// at first upload (idempotent; the flag only saves round-trips).
+// Ask before writing. `_mediaReady` is per PROCESS, and a service worker is
+// restarted whenever the browser feels like it — so on the browser build this
+// re-created a container that has existed since sign-up, and rewrote its ACL,
+// on every restart. A HEAD is one request and usually the only one.
+export async function ensureMediaContainer(publisher) {
+  if (publisher._mediaReady) return;
+  if (await containers.exists(publisher.remote, publisher.urls.media)) { publisher._mediaReady = true; return; }
+  await containers.provisionPublic(publisher.remote, publisher.urls.media);
+  publisher._mediaReady = true;
+}
+
+// Whether the canary this class writes is already there. Only a definite
+// "yes" counts: anything else falls through to the write, which is
+// idempotent anyway, so a failed probe costs a request and never correctness.
+export function containerExists(publisher, base) { return containers.exists(publisher.remote, base); }
+
+// The owner-only container that followers-only and direct posts live in.
+// Its ACL is set once; every note under it inherits.
+export async function ensurePrivateContainer(publisher) {
+  if (publisher._privateContainer) return;
+  // Same reasoning as ensureMediaContainer: probe before provisioning, so a
+  // worker restart is not a re-provision. The ACL is NOT skipped on the
+  // strength of the container existing alone — ensurePrivateAcls re-checks
+  // that separately on every connect, which is the control that matters here.
+  if (await containers.exists(publisher.remote, publisher.urls.privateNotes)) { publisher._privateContainer = true; return; }
+  await containers.provisionOwnerOnly(publisher.remote, publisher.urls.privateNotes);
+  publisher._privateContainer = true;
+}
+
+// Whether the pod actually enforces that ACL: a bare, unauthenticated read
+// of the private container's canary must be refused. Returns true, or the
+// reason private posts stay off. A definite answer is cached for the run; a
+// network failure is not, so a pod that was briefly unreachable is asked
+// again rather than refused forever.
+export async function privateReady(publisher) {
+  if (publisher._privateVerdict !== undefined) return publisher._privateVerdict;
+  try {
+    await publisher.ensurePrivateContainer();
+    // The probe is credential-free and bypasses RemotePod's url map, so a
+    // fronted identity must map the advertised private container back to the
+    // pod itself — the ACL we are testing is the pod's.
+    const pn = publisher.urls.toPod ? publisher.urls.toPod(publisher.urls.privateNotes) : publisher.urls.privateNotes;
+    const verdict = await containers.probePrivateEnforcement(publisher.probeFetch || fetch, pn + '.keep');
+    publisher._privateVerdict = verdict === true ? true : `${verdict} — private posts stay off it`;
+    return publisher._privateVerdict;
+  } catch (e) {
+    return `could not verify that the pod protects private posts (${e.message})`;
+  }
+}
+
+// Compose → wire note on remote pod + RDF truth locally + deliver Create.
+// Who this text mentions, resolved. A mention nobody can resolve stays plain
+// text rather than failing the post. The text itself decides: trim a handle
+// out and that person is not notified, which is what every fediverse client
+// leads people to expect. A Group named in the parent is the one thing
+// carried forward regardless — drop it and the group stops carrying the
+// thread.
+export async function mentionsFor(publisher, content, inReplyTo) {
+  const inText = new Set(wire.mentionsIn(content));
+  const carried = inReplyTo
+    ? (publisher.store.getStatuses().find(s => s.noteId === inReplyTo)?.mentions || [])
+      .map(m => String(m.name || '').replace(/^@/, '')).filter(Boolean)
+    : [];
+  const mentions = [];
+  for (const handle of [...new Set([...inText, ...carried])]) {
+    if (!publisher.resolveMention) break;
+    const doc = await publisher.resolveMention(handle).catch(() => null);
+    if (!doc?.id) { publisher.log(`mention @${handle} did not resolve — left as text`); continue; }
+    if (!inText.has(handle) && doc.type !== 'Group') continue;   // author trimmed them out
+    mentions.push({ handle, actor: doc.id, page: doc.url || null, inbox: doc.endpoints?.sharedInbox || doc.inbox });
+  }
+  return mentions;
+}
+
+export async function publishNote(publisher, content, { inReplyTo, attachments, visibility = 'public', spoilerText = null } = {}) {
+  const { urls } = publisher;
+  const priv = visibility === 'private' || visibility === 'direct';
+  if (priv) {
+    const ready = await publisher.privateReady();
+    if (ready !== true) throw new Error(ready);
+  }
+  const published = new Date().toISOString();
+  const slug = published.slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex');
+  const mentions = await publisher._mentionsFor(content, inReplyTo);
+  const note = wire.noteDoc({ urls, slug, content, published, inReplyTo, attachments, mentions,
+    visibility, summary: spoilerText, container: priv ? urls.privateNotes : urls.notes });
+
+  await podNotes.write(publisher.remote, note.id, note);
+  // Empty, but present: a dangling `replies` that 404s is worse than none.
+  await podNotes.writeEmptyReplies(publisher.remote, wire.repliesId(note.id),
+    wire.collection(wire.repliesId(note.id), []));
+  // The outbox is the PUBLIC index; a private or direct post is not in it.
+  if (!priv) await publisher.recordOutbox(note.id);
+
+  publisher.store.addStatus({
+    noteId: note.id, actor: urls.actor, content: note.content, published, inReplyTo,
+    kind: 'post', slug, text: content, visibility,
+    ...(spoilerText ? { spoiler: spoilerText } : {}),
+    ...(attachments?.length ? { attachments } : {}),
+    ...(note.tag?.length ? { mentions: note.tag.map(t => ({ href: t.href, name: t.name })) } : {}),
+  });
+
+  const create = wire.createActivity(note, urls);
+  // Published as its own document: a group that carries this post wraps the
+  // whole activity, and the receiving server resolves it by fetching this id.
+  // It inherits the notes container's public-Read acl:default.
+  await podNotes.writeCreate(publisher.remote, create.id, create);
+  const contacts = publisher.store.getContacts();
+  // A direct post goes to the people it names and to nobody else.
+  const inboxes = [...new Set([
+    ...(visibility === 'direct' ? [] : contacts.followers.map(f => f.sharedInbox || f.inbox)),
+    ...mentions.map(m => m.inbox),
+  ].filter(Boolean))];
+  await publisher.deliverer.deliverToAll(inboxes, create);
+  publisher.log(`note published: ${note.id} → ${inboxes.length} inbox(es)`);
+
+  // Bluesky mirror: PUBLIC posts only — unlisted, followers-only and direct
+  // are never carried off the fediverse. A mirror failure never fails the
+  // post; it is logged and recorded on the status for the admin page.
+  if (visibility === 'public' && publisher.atproto?.connected()
+    && publisher.store.getConfig()?.atproto?.crossPost) {
+    try {
+      const mirror = await publisher.atproto.crossPost(
+        { text: content, published, attachments }, { noteUrl: note.id });
+      publisher.store.updateStatus(note.id, { atproto: mirror });
+      publisher.log(`cross-posted to bluesky: ${mirror.uri}${mirror.truncated ? ' (truncated, links back)' : ''}`);
+    } catch (e) {
+      publisher.store.updateStatus(note.id, { atproto: { error: e.message } });
+      publisher.log(`bluesky cross-post failed: ${e.message}`);
+    }
+  }
+  return note;
+}
+
+// An edit keeps the note's id, slug and published time; `updated` is the
+// edit's own stamp. The pod documents are overwritten in place — the Create
+// too, so a group's Announce resolves to the edited text — and an Update
+// goes everywhere the Create went.
+export async function updateNote(publisher, s, { content, spoilerText = null, attachments = null } = {}) {
+  const { urls } = publisher;
+  const updated = new Date().toISOString();
+  const inText = new Set(wire.mentionsIn(content));
+  const mentions = [];
+  for (const handle of inText) {
+    if (!publisher.resolveMention) break;
+    const doc = await publisher.resolveMention(handle).catch(() => null);
+    if (!doc?.id) { publisher.log(`mention @${handle} did not resolve — left as text`); continue; }
+    mentions.push({ handle, actor: doc.id, page: doc.url || null, inbox: doc.endpoints?.sharedInbox || doc.inbox });
+  }
+  const atts = attachments ?? s.attachments ?? [];
+  // The note stays in the container its visibility put it in; a recovered
+  // post may carry no slug, but the note id already contains it.
+  const container = String(s.noteId).startsWith(urls.privateNotes) ? urls.privateNotes : urls.notes;
+  const slug = s.slug || String(s.noteId).slice(container.length);
+  const note = wire.noteDoc({
+    urls, slug, content, published: s.published, inReplyTo: s.inReplyTo,
+    attachments: atts, mentions, visibility: s.visibility || 'public',
+    summary: spoilerText, updated, container,
+  });
+  await podNotes.write(publisher.remote, note.id, note);
+  await podNotes.writeCreate(publisher.remote, wire.createActivityId(note.id), wire.createActivity(note, urls));
+  const patched = publisher.store.updateStatus(s.noteId, {
+    content: note.content, text: content, editedAt: updated,
+    spoiler: spoilerText || undefined,
+    attachments: atts.length ? atts : undefined,
+    mentions: note.tag?.length ? note.tag.map(t => ({ href: t.href, name: t.name })) : undefined,
+  });
+  const update = wire.updateActivity(note, urls);
+  const contacts = publisher.store.getContacts();
+  const inboxes = [...new Set([
+    ...(s.visibility === 'direct' ? [] : contacts.followers.map(f => f.sharedInbox || f.inbox)),
+    ...mentions.map(m => m.inbox),
+  ].filter(Boolean))];
+  await publisher.deliverer.deliverToAll(inboxes, update);
+  publisher.log(`note edited: ${note.id} → ${inboxes.length} inbox(es)`);
+  return patched;
+}

package/lib/core/publisher/questions.mjs

@@ -0,0 +1,233 @@
+  // questions.mjs — polls.
+  //
+  // A poll is published as a Question and answered by ordinary replies naming
+  // an option, so the count is ours to keep and ours to republish. The roster
+  // of who chose what lives in agent state (polls.VOTES_DOC); the tallies on
+  // the status row and in the pod document are always derived from it.
+
+import crypto from 'node:crypto';
+import * as wire from '../wire.mjs';
+import * as polls from '../polls.mjs';
+import * as podNotes from '../../pod/notes.mjs';
+
+// How long a poll gathers votes before its Question is rewritten. Every vote
+// changes a number other servers re-read, and rewriting per vote would make a
+// busy poll a steady write stream against the pod. A burst costs one rewrite
+// and one Update instead.
+const POLL_REWRITE_MS = 10_000;
+
+/**
+ * Publish a poll. `options` is a list of choice titles, `multiple` lets a
+ * voter pick more than one, and `expiresAt` is when voting stops.
+ */
+export async function publishQuestion(publisher, content, { options = [], multiple = false, expiresAt = null,
+  inReplyTo = undefined, visibility = 'public', spoilerText = null } = {}) {
+  const { urls } = publisher;
+  const priv = visibility === 'private' || visibility === 'direct';
+  if (priv) {
+    const ready = await publisher.privateReady();
+    if (ready !== true) throw new Error(ready);
+  }
+  const titles = [].concat(options).map(o => String(o ?? '').trim()).filter(Boolean);
+  if (titles.length < 2) throw new Error('a poll needs at least two options');
+  // Options are matched BY NAME when a vote arrives — that is the whole of
+  // the convention — so two options reading the same are one option that
+  // cannot be told apart.
+  if (new Set(titles).size !== titles.length) throw new Error('a poll’s options must differ from one another');
+  // Bounded here as well as at the client API, because the outbox is a
+  // second way in and an unbounded poll is a document a stranger sizes.
+  if (titles.length > polls.MAX_OPTIONS) throw new Error(`a poll takes at most ${polls.MAX_OPTIONS} options`);
+  if (titles.some(t => t.length > polls.MAX_OPTION_CHARS)) {
+    throw new Error(`a poll option is at most ${polls.MAX_OPTION_CHARS} characters`);
+  }
+  if (expiresAt) {
+    const ends = Date.parse(expiresAt);
+    if (!Number.isFinite(ends)) throw new Error('the closing time is not a date');
+    const seconds = (ends - Date.now()) / 1000;
+    if (seconds < polls.MIN_SECONDS || seconds > polls.MAX_SECONDS) {
+      throw new Error(`a poll runs between ${polls.MIN_SECONDS} and ${polls.MAX_SECONDS} seconds`);
+    }
+  }
+
+  const published = new Date().toISOString();
+  const slug = published.slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex');
+  const mentions = await publisher._mentionsFor(content, inReplyTo);
+  const poll = {
+    multiple: !!multiple,
+    expiresAt: expiresAt || null,
+    closed: null,
+    options: titles.map(title => ({ title, votes: 0 })),
+    votersCount: 0,
+    // Resolved once, here: a tally rewrite must not cost a webfinger lookup
+    // per vote for people the poll named.
+    mentionInboxes: [...new Set(mentions.map(m => m.inbox).filter(Boolean))],
+  };
+  const question = wire.questionDoc({
+    urls, slug, content, published, inReplyTo, attachments: [], mentions,
+    visibility, summary: spoilerText,
+    container: priv ? urls.privateNotes : urls.notes,
+    options: poll.options, multiple: poll.multiple, endTime: poll.expiresAt, votersCount: 0,
+  });
+
+  await podNotes.write(publisher.remote, question.id, question);
+  // Empty, but present: a dangling `replies` that 404s is worse than none.
+  await podNotes.writeEmptyReplies(publisher.remote, wire.repliesId(question.id),
+    wire.collection(wire.repliesId(question.id), []));
+  if (!priv) await publisher.recordOutbox(question.id);
+  publisher.store.addStatus({
+    noteId: question.id, actor: urls.actor, content: question.content, published,
+    kind: 'post', slug, text: content, visibility, poll, inReplyTo,
+    ...(spoilerText ? { spoiler: spoilerText } : {}),
+    ...(question.tag?.length ? { mentions: question.tag.map(t => ({ href: t.href, name: t.name })) } : {}),
+  });
+
+  const create = publisher._pollActivity('Create', question, wire.createActivityId(question.id));
+  await podNotes.writeCreate(publisher.remote, create.id, create);
+  const contacts = publisher.store.getContacts();
+  const inboxes = [...new Set([
+    ...(visibility === 'direct' ? [] : contacts.followers.map(f => f.sharedInbox || f.inbox)),
+    ...poll.mentionInboxes,
+  ].filter(Boolean))];
+  await publisher.deliverer.deliverToAll(inboxes, create);
+  publisher.log(`poll published: ${question.id} (${titles.length} options) → ${inboxes.length} inbox(es)`);
+  return question;
+}
+
+// The Create or Update carrying a Question. The context is hoisted onto the
+// activity and the embedded object keeps none: a nested @context is legal
+// JSON-LD but not every server reads one, and votersCount is declared there.
+export function pollActivity(publisher, type, question, id) {
+  const { '@context': ctx, ...object } = question;
+  return {
+    '@context': ctx, id, type,
+    actor: publisher.urls.actor,
+    published: question.published,
+    to: question.to, cc: question.cc,
+    object,
+  };
+}
+
+/**
+ * One vote on one of OUR polls, named by the option's title. Returns true
+ * when it counted — a second answer to a single-choice poll, an option we do
+ * not offer, or a poll that has closed all count for nothing.
+ */
+export async function recordVote(publisher, questionId, actor, optionName) {
+  const s = publisher.store.getStatuses().find(x => x.noteId === questionId);
+  if (!s?.poll || s.kind !== 'post' || s.actor !== publisher.urls.actor) return false;
+  if (polls.pollClosed(s.poll)) return false;
+  const index = polls.optionIndex(s.poll, optionName);
+  if (index < 0) return false;
+  const all = publisher.store.read(polls.VOTES_DOC, {});
+  const { roster, changed } = polls.addVote(all[questionId] || {}, polls.voterKey(actor), index,
+    { multiple: !!s.poll.multiple });
+  if (!changed) return false;
+  publisher.store.write(polls.VOTES_DOC, { ...all, [questionId]: roster });
+  publisher.store.updateStatus(questionId, { poll: polls.withTally(s.poll, roster) });
+  publisher._pollDirty(questionId);
+  return true;
+}
+
+// Open the rewrite window for a poll whose count moved. Already open is
+// already enough: the whole point is that a burst costs one rewrite.
+export function pollDirty(publisher, questionId) {
+  if (publisher.pollTimers.has(questionId)) return;
+  const t = setTimeout(() => {
+    publisher.pollTimers.delete(questionId);
+    publisher.republishPoll(questionId).catch(e => publisher.log(`poll rewrite: ${e.message}`));
+  }, POLL_REWRITE_MS);
+  t.unref?.();
+  publisher.pollTimers.set(questionId, t);
+}
+
+/**
+ * Write the poll's current count back to the pod and tell everyone who has
+ * it. `closing` stamps it shut, which is a one-way door.
+ */
+export async function republishPoll(publisher, questionId, { closing = null } = {}) {
+  const s = publisher.store.getStatuses().find(x => x.noteId === questionId);
+  if (!s?.poll) return null;
+  const { urls } = publisher;
+  const roster = publisher.store.read(polls.VOTES_DOC, {})[questionId] || {};
+  // A shut poll whose roster has been retired keeps the counts on its row:
+  // deriving them from an empty roster would publish a poll nobody voted in.
+  const shut = closing || s.poll.closed;
+  const counted = shut && !Object.keys(roster).length ? s.poll : polls.withTally(s.poll, roster);
+  const poll = { ...counted, ...(closing ? { closed: closing } : {}) };
+  const container = String(s.noteId).startsWith(urls.privateNotes) ? urls.privateNotes : urls.notes;
+  const slug = s.slug || String(s.noteId).slice(container.length);
+  const mentions = (s.mentions || []).map(m => ({
+    handle: String(m.name || '').replace(/^@/, ''), actor: m.href, page: null, inbox: null,
+  }));
+  const question = wire.questionDoc({
+    urls, slug, content: s.text ?? '', published: s.published, inReplyTo: s.inReplyTo,
+    attachments: [], mentions,
+    visibility: s.visibility || 'public', summary: s.spoiler || null, container,
+    options: poll.options, multiple: !!poll.multiple, endTime: poll.expiresAt,
+    closed: poll.closed, votersCount: poll.votersCount || 0,
+  });
+  await podNotes.write(publisher.remote, question.id, question);
+  // The Create is overwritten too, so a group's Announce resolves to the
+  // current count rather than to the one the poll opened with.
+  await podNotes.writeCreate(publisher.remote, wire.createActivityId(question.id),
+    publisher._pollActivity('Create', question, wire.createActivityId(question.id)));
+  publisher.store.updateStatus(questionId, { poll });
+
+  // Not `updated`: a changed count is not an edit, and stamping one would
+  // have every client show the poll as edited each time somebody voted.
+  //
+  // The Update is named after the STATE it carries rather than the moment it
+  // was sent. A clock only tells two rewrites apart when they fall in
+  // different milliseconds, and a receiving server that has seen an activity
+  // id drops the next one wearing it — which would quietly freeze the count.
+  // Naming the state means an id changes exactly when there is something new
+  // to say, and two sends of the same numbers are the duplicate they look
+  // like.
+  const stamp = crypto.createHash('sha256').update(JSON.stringify([
+    poll.options.map(o => o.votes || 0), poll.votersCount || 0, poll.closed || '',
+  ])).digest('hex').slice(0, 12);
+  const update = publisher._pollActivity('Update', question, `${question.id}#poll-${stamp}`);
+  const contacts = publisher.store.getContacts();
+  const inboxes = [...new Set([
+    ...(s.visibility === 'direct' ? [] : contacts.followers.map(f => f.sharedInbox || f.inbox)),
+    ...(s.poll.mentionInboxes || []),
+  ].filter(Boolean))];
+  await publisher.deliverer.deliverToAll(inboxes, update);
+  publisher.log(`poll ${closing ? 'closed' : 'count published'}: ${question.id} → ${inboxes.length} inbox(es)`);
+  return poll;
+}
+
+/**
+ * Shut any poll whose time is up. Called from the agent's sweep. Closing is
+ * recorded BEFORE the republish, so a failed republish cannot leave a poll
+ * open and collecting votes it has already refused.
+ */
+export async function closeDuePolls(publisher, now = Date.now()) {
+  const due = publisher.store.getStatuses().filter(s => s.kind === 'post' && s.poll
+    && !s.poll.closed && s.poll.expiresAt && Date.parse(s.poll.expiresAt) <= now);
+  for (const s of due) {
+    const closed = new Date(Math.min(now, Date.parse(s.poll.expiresAt) || now)).toISOString();
+    clearTimeout(publisher.pollTimers.get(s.noteId));
+    publisher.pollTimers.delete(s.noteId);
+    publisher.store.updateStatus(s.noteId, { poll: { ...s.poll, closed } });
+    const done = await publisher.republishPoll(s.noteId, { closing: closed })
+      .catch(e => { publisher.log(`poll close ${s.noteId}: ${e.message}`); return null; });
+    // The roster only ever answered one question — has this person already
+    // voted — and a shut poll has stopped asking it. Dropping it keeps a
+    // document we serialize whole from carrying every poll's voters forever.
+    if (done) {
+      const all = publisher.store.read(polls.VOTES_DOC, {});
+      if (all[s.noteId]) {
+        delete all[s.noteId];
+        publisher.store.write(polls.VOTES_DOC, all);
+      }
+    }
+  }
+  return due.length;
+}
+
+/** Stop the pending rewrite windows. Called at shutdown. */
+export function stopPolls(publisher) {
+  for (const t of publisher.pollTimers.values()) clearTimeout(t);
+  publisher.pollTimers.clear();
+}

package/lib/core/publisher/restore.mjs

@@ -0,0 +1,199 @@
+// restore.mjs — a machine that is behind the pod catching up: followers and
+// outbox entries the pod carries and this machine never heard of, and the
+// actor's own posts rebuilt from the published outbox.
+
+import * as wire from '../wire.mjs';
+import * as podNotes from '../../pod/notes.mjs';
+import { readLenient } from '../as2.mjs';
+
+const ACCEPT_AP = 'application/activity+json, application/ld+json; profile="https://www.w3.org/ns/activitystreams"';
+const REBUILD_MAX_PER_RUN = 200;
+
+// Anyone the pod says follows us that we have no record of, and never
+// deliberately removed. In the steady state there is nobody: the pod's list is
+// written from this one. They appear when the local half is BEHIND the pod —
+// a restored backup, a home copied off a dead machine — and republishing
+// blindly would delete them from the wire and, worse, stop delivering to them.
+//
+// Removals are what makes this safe to do unconditionally: `dropFollower`
+// records every unfollow, ejection and account deletion, so a returning name
+// is either genuinely still a follower or genuinely a mistake we made.
+export async function reconcileFollowers(publisher, contacts) {
+  let published = [];
+  try {
+    published = (await publisher.readPublishedFollowers()) || [];   // walks pages
+  } catch { return 0; }                       // no list to reconcile against
+
+  const known = new Set(contacts.followers.map(f => f.actor));
+  const removed = new Set((contacts.removedFollowers || []).map(r => r.actor));
+  const missing = published.filter(a => typeof a === 'string' && !known.has(a) && !removed.has(a));
+  if (!missing.length) return 0;
+
+  // An inbox is what delivery needs, and only the actor document has it — so
+  // recovering a follower costs one fetch each. Capped: a list this wrong is
+  // a restore, and the rest catch up on the next publish.
+  let recovered = 0;
+  for (const actor of missing.slice(0, 200)) {
+    try {
+      const res = await publisher.deliverer.signedFetch(actor, { headers: { accept: ACCEPT_AP } });
+      if (!res.ok) continue;
+      // The graph, not the compacted copy: `inbox` is `ldp:inbox` rather than
+      // an `as:` term, and what is wanted here is the statement, not a key.
+      const { doc, view, degraded } = await readLenient(await res.json());
+      const actorDoc = view ?? doc;
+      if (degraded) publisher.log?.(`actor ${actor} grounded to read: ${degraded}`);
+      if (!actorDoc?.inbox) continue;
+      contacts.followers.push({
+        actor, inbox: actorDoc.inbox, sharedInbox: actorDoc.endpoints?.sharedInbox || null, recovered: true,
+        // Said explicitly, because onUndo reads it: the pod publishes WHO
+        // follows, never the id of the Follow that did it, so a recovered
+        // record has nothing an Undo can be matched against and must not be
+        // evictable by one naming anything at all.
+        followId: null,
+      });
+      recovered++;
+    } catch { /* unreachable now; it will be there next time */ }
+  }
+  if (recovered) {
+    publisher.store.setContacts(contacts);
+    publisher.log(`reconciled ${recovered} follower(s) the pod knew about and this machine did not `
+      + '— a restored or copied state was behind');
+  }
+  return recovered;
+}
+
+// The same argument as reconcileFollowers, for the other published list. It
+// matters more: the outbox is the INDEX a statuses rebuild reads, so a
+// republish from a restored-and-behind machine would destroy the record of
+// everything this actor ever posted — and destroy it before anyone noticed
+// there was anything to recover.
+//
+// Safe for the same reason: `unrecordOutbox` leaves a tombstone, so an entry
+// the pod still carries is one this machine has not heard of, never one it
+// deliberately took back.
+export async function reconcileOutbox(publisher, outbox) {
+  let published = [];
+  try {
+    published = await publisher.readPublishedOutbox() || [];
+  } catch { return 0; }
+  if (!Array.isArray(published) || !published.length) return 0;
+
+  const idOf = (i) => (typeof i === 'string' ? i : i?.id || null);
+  const known = new Set(outbox.map(idOf).filter(Boolean));
+  const removed = new Set((publisher.store.read('outbox-removed.json', [])).map(r => r.id));
+  const missing = published.filter((i) => {
+    const id = idOf(i);
+    return id && !known.has(id) && !removed.has(id);
+  });
+  if (!missing.length) return 0;
+  // Newest first, like recordOutbox leaves it; the pod's copy is already in
+  // that order, so appending the tail is enough to keep both sorted.
+  outbox.push(...missing);
+  publisher.store.write('outbox.json', outbox);
+  publisher.log(`reconciled ${missing.length} outbox entr(ies) the pod carried and this machine did not`);
+  return missing.length;
+}
+
+// Recover this actor's own posts from the pod's public face. The private half
+// lives on this machine now, so a restored backup or a replaced machine loses
+// statuses.json while the pod still serves every note. Followers already come
+// back; this is the other half of the same gap.
+//
+// The INDEX is ap/outbox, not the ap/notes/ listing, and that difference is
+// the safety argument. Deleting a post rewrites the outbox in one PUT, so an
+// entry still there is a post that still stands. The note DOCUMENT can outlive
+// its own deletion — deleteNote's `remote.delete` is a request that can fail —
+// so walking the container can bring back something its author took down.
+// `fromNotes` is for when you would rather have that than lose the post; it is
+// not the default, and it says so where it is offered.
+//
+// MERGE ONLY. A status this machine already holds is left exactly as it is:
+// it carries local facts — favourited, reblogged, the activities an Undo has
+// to name — that the pod knows nothing about. That is also what makes the
+// failure modes harmless: a listing that fails returns nothing, and nothing
+// is what an empty listing recovers.
+export async function rebuildStatuses(publisher, { fromNotes = false } = {}) {
+  const { urls } = publisher;
+  const ids = new Set();
+  const boosts = [];
+  let indexed = false;
+
+  const published = await publisher.readPublishedOutbox().catch(() => null);
+  if (published) {
+    indexed = true;
+    for (const item of published) {
+      if (typeof item === 'string') { if (item.startsWith(urls.notes)) ids.add(item); }
+      else if (item?.type === 'Announce') boosts.push(item);
+    }
+  }
+  if (fromNotes) {
+    // Three documents are published per post — the note, `-create` and
+    // `-replies` — plus a `.keep`. Which is which is settled by reading the
+    // document below, not by its name: a slug is a date and eight hex
+    // characters and says nothing about what it holds.
+    for (const child of await podNotes.list(publisher.remote, urls).catch(() => [])) {
+      ids.add(child.url);
+    }
+    indexed = true;
+  }
+  if (!indexed) return { indexed: 0, recovered: 0, reblogs: 0, landed: false, why: 'the pod would not answer for its outbox' };
+
+  const statuses = publisher.store.getStatuses();
+  const have = new Set(statuses.map(s => s.noteId));
+  const removed = new Set(publisher.store.read('outbox-removed.json', []).map(r => r.id));
+  const recovered = [];
+  // Capped per run: a long-lived actor's rebuild is otherwise one pod request
+  // per post it has ever made, in one burst. What is left is picked up by
+  // running it again — the merge is idempotent, so that is safe to repeat.
+  let budget = REBUILD_MAX_PER_RUN;
+  for (const id of ids) {
+    if (budget <= 0) { publisher.log(`rebuild: stopping at ${REBUILD_MAX_PER_RUN} this run — run it again for the rest`); break; }
+    if (have.has(id) || removed.has(id)) continue;
+    budget--;
+    const note = await podNotes.read(publisher.remote, id).catch(() => null);
+    if (note?.type !== 'Note' || note.id !== id || note.attributedTo !== urls.actor) continue;
+    const attachments = wire.attachmentsOf(note);
+    const mentions = (Array.isArray(note.tag) ? note.tag : [])
+      .filter(t => t?.type === 'Mention' && t.href)
+      .map(t => ({ href: t.href, name: t.name }));
+    recovered.push({
+      noteId: note.id, actor: urls.actor, content: note.content || '',
+      published: note.published || null,
+      ...(note.inReplyTo ? { inReplyTo: note.inReplyTo } : {}),
+      kind: 'post', slug: note.id.slice(urls.notes.length),
+      ...(attachments.length ? { attachments } : {}),
+      ...(mentions.length ? { mentions } : {}),
+      recovered: true,
+    });
+  }
+
+  // A boost is only recoverable for a post we can name — the Announce carries
+  // the activity a later Undo needs, but not the boosted post's text, which
+  // belongs to whoever wrote it.
+  const merged = [...statuses, ...recovered];
+  let reblogs = 0;
+  for (const act of boosts) {
+    const object = typeof act.object === 'string' ? act.object : act.object?.id;
+    const s = object && merged.find(x => x.noteId === object);
+    if (!s || s.reblogged) continue;
+    s.reblogged = true;
+    s.announceActivity = act;
+    reblogs++;
+  }
+  if (!recovered.length && !reblogs) return { indexed: ids.size, recovered: 0, reblogs: 0, landed: true };
+
+  // Written whole and sorted: addStatus unshifts and fires the streaming
+  // event, so a loop of it would arrive backwards and push every recovered
+  // post at connected clients as new.
+  merged.sort((a, b) => String(b.published || '').localeCompare(String(a.published || '')));
+  const kept = merged.slice(0, 1000);
+  publisher.store.write('statuses.json', kept);
+  const landed = await publisher.store.commit();
+
+  publisher.log(`rebuilt ${recovered.length} post(s) and ${reblogs} boost(s) from the pod`
+    + `${landed ? '' : ' — THE STATE WRITE DID NOT LAND'}`);
+  return {
+    indexed: ids.size, recovered: recovered.length, reblogs, landed,
+    dropped: Math.max(0, merged.length - kept.length),
+  };
+}