@takosjp/yurucommu-core 3.0.1 → 3.0.3

package/migrations/0018_actor_notes.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS actor_notes (
+  actor_ap_id TEXT PRIMARY KEY,
+  content TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  expires_at TEXT NOT NULL,
+  deleted_at TEXT,
+  FOREIGN KEY (actor_ap_id) REFERENCES actors(ap_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS actor_notes_expires_idx
+  ON actor_notes(expires_at);
+
+CREATE INDEX IF NOT EXISTS actor_notes_updated_idx
+  ON actor_notes(updated_at);
+
+CREATE INDEX IF NOT EXISTS actor_notes_deleted_idx
+  ON actor_notes(deleted_at);

package/migrations/README.md

@@ -83,17 +83,6 @@ file name (not the numeric version) in `yurucommu_migrations`.
    credentials come from the same reviewed Provider Connection used by the
    OpenTofu run.
 
-   In the fallback path where the Worker script is not managed by OpenTofu,
-   `takosumi_release.post_apply` runs `bun run takosumi:release` as an opaque
-   operator release command. It reads non-secret outputs from `TAKOSUMI_OUTPUTS_JSON`,
-   writes a temporary Wrangler config, runs `bun install --frozen-lockfile`,
-   runs `bun run build:takos-worker`, applies D1 migrations through
-   `wrangler d1 execute` without explicit SQL transaction wrappers, and deploys
-   with `wrangler deploy`.
-   Provider credentials and app-specific secrets come from the selected
-   operator release activator boundary through
-   `TAKOSUMI_RELEASE_COMMAND_ENV_ALLOWLIST`.
-
    Common operator env names:
 
    ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-core",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "workspaces": [
@@ -29,6 +29,7 @@
     "packages/api/src/lib/api/follow.ts",
     "packages/api/src/lib/api/media.ts",
     "packages/api/src/lib/api/moderation.ts",
+    "packages/api/src/lib/api/notes.ts",
     "packages/api/src/lib/api/normalize.ts",
     "packages/api/src/lib/api/notifications.ts",
     "packages/api/src/lib/api/posts.ts",
@@ -59,6 +60,7 @@
     "test:backend": "bun test src/backend/",
     "build": "bun run build:api",
     "build:api": "cd packages/api && bun run build",
+    "prepublishOnly": "bun scripts/check-publish-version-discipline.mjs .",
     "pack:core": "npm pack --dry-run",
     "pack:api": "cd packages/api && bun run pack:dry",
     "app:activate": "bun scripts/apply-takosumi-migrations.ts",

package/packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-api",
-  "version": "3.0.0",
+  "version": "3.0.3",
   "description": "Typed client SDK and public API contract for yurucommu-server clients.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -19,6 +19,7 @@
   "scripts": {
     "check": "tsc --noEmit -p tsconfig.json",
     "build": "rm -rf dist && bun build src/index.ts --target browser --format esm --outfile dist/index.js && bunx tsc -p tsconfig.build.json && bun scripts/rewrite-dts-imports.mjs",
+    "prepublishOnly": "bun ../../scripts/check-publish-version-discipline.mjs .",
     "pack:dry": "npm pack --dry-run"
   },
   "devDependencies": {

package/packages/api/src/lib/api/normalize.ts

@@ -1,6 +1,7 @@
 import {
   Actor,
   ActorStories,
+  ActorNote,
   Notification,
   Post,
   Story,
@@ -63,6 +64,11 @@ export const normalizeActorStories = (stories: ActorStories): ActorStories => ({
   stories: (stories.stories || []).map(normalizeStory),
 });
 
+export const normalizeActorNote = (note: ActorNote): ActorNote => ({
+  ...note,
+  actor: normalizeActor(note.actor),
+});
+
 export const normalizeNotification = (
   notification: Notification,
 ): Notification => ({

package/packages/api/src/lib/api/notes.ts

@@ -0,0 +1,25 @@
+import type { ActorNote } from "../../types/index.ts";
+import { normalizeActorNote } from "./normalize.ts";
+import { apiDelete, apiFetch, apiPost, assertOk } from "./fetch.ts";
+
+export async function fetchNotes(): Promise<ActorNote[]> {
+  const res = await apiFetch("/api/notes");
+  await assertOk(res, "Failed to fetch notes");
+  const data = (await res.json()) as { notes?: ActorNote[] };
+  return (data.notes || []).map(normalizeActorNote);
+}
+
+export async function createNote(data: {
+  content: string;
+  expires_in_hours?: number;
+}): Promise<ActorNote> {
+  const res = await apiPost("/api/notes", data);
+  await assertOk(res, "Failed to create note");
+  const result = (await res.json()) as { note: ActorNote };
+  return normalizeActorNote(result.note);
+}
+
+export async function deleteMyNote(): Promise<void> {
+  const res = await apiDelete("/api/notes/me");
+  await assertOk(res, "Failed to delete note");
+}

package/packages/api/src/lib/api/stories.ts

@@ -1,4 +1,9 @@
-import type { ActorStories, Story, StoryOverlay } from "../../types/index.ts";
+import type {
+  ActorStories,
+  Story,
+  StoryOverlay,
+  StoryViewersResponse,
+} from "../../types/index.ts";
 import { normalizeActorStories, normalizeStory } from "./normalize.ts";
 import { apiDelete, apiFetch, apiPost, assertOk } from "./fetch.ts";
 
@@ -78,3 +83,13 @@ export async function shareStory(
   await assertOk(res, "Failed to share story");
   return (await res.json()) as { shared: boolean; share_count: number };
 }
+
+// Author-only "seen by" list for a story. GETs the same id-encoded path the
+// sibling like/share routes use.
+export async function getStoryViewers(
+  apId: string,
+): Promise<StoryViewersResponse> {
+  const res = await apiFetch(`/api/stories/${encodeURIComponent(apId)}/views`);
+  await assertOk(res, "Failed to fetch story viewers");
+  return (await res.json()) as StoryViewersResponse;
+}

package/packages/api/src/lib/api.ts

@@ -10,6 +10,7 @@ export * from "./api/notifications.ts";
 export * from "./api/search.ts";
 export * from "./api/media.ts";
 export * from "./api/stories.ts";
+export * from "./api/notes.ts";
 export * from "./api/recommendations.ts";
 export * from "./api/moderation.ts";
 export * from "./api/normalize.ts";

package/packages/api/src/types/index.ts

@@ -150,7 +150,6 @@ export interface StoryOverlay {
   // Question-specific
   name?: string; // Question text
   oneOf?: Array<{ type: string; name: string }>; // Options
-  closed?: string; // Close time
   // Link-specific
   href?: string;
   // Generic
@@ -183,3 +182,26 @@ export interface ActorStories {
   stories: Story[];
   has_unviewed: boolean;
 }
+
+// A single viewer in a story's "seen by" list (author-only).
+export interface StoryViewer {
+  actor: PostAuthor;
+  viewed_at: string;
+}
+
+// Response of GET /api/stories/:id/views (author-only "seen by").
+export interface StoryViewersResponse {
+  view_count: number;
+  viewers: StoryViewer[];
+}
+
+// Short-lived actor status note. This is the Instagram-Notes-style current
+// status surface, not the ActivityPub `Note` object used for normal posts.
+export interface ActorNote {
+  actor: PostAuthor;
+  content: string;
+  created_at: string;
+  updated_at: string;
+  expires_at: string;
+  is_mine: boolean;
+}

package/src/backend/index.ts

@@ -14,6 +14,7 @@ import actorsRoutes from "./routes/actors.ts";
 import followRoutes from "./routes/follow.ts";
 import timelineRoutes from "./routes/timeline.ts";
 import postsRoutes from "./routes/posts.ts";
+import notesRoutes from "./routes/notes.ts";
 import notificationsRoutes from "./routes/notifications.ts";
 import storiesRoutes from "./routes/stories.ts";
 import searchRoutes from "./routes/search.ts";
@@ -218,7 +219,8 @@ function buildSocialServerDiscovery(
     ...DEFAULT_DISCOVERY_OPTIONS,
     ...options,
     clients: options.clients ?? DEFAULT_DISCOVERY_OPTIONS.clients,
-    capabilities: options.capabilities ?? DEFAULT_DISCOVERY_OPTIONS.capabilities,
+    capabilities:
+      options.capabilities ?? DEFAULT_DISCOVERY_OPTIONS.capabilities,
   };
   return {
     product: discovery.product,
@@ -599,6 +601,8 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
   app.use("/media/*", rateLimit(RateLimitConfigs.mediaUpload));
   app.use("/api/dm/*", rateLimit(RateLimitConfigs.dm));
   app.post("/api/posts", rateLimit(RateLimitConfigs.postCreate));
+  app.post("/api/notes", rateLimit(RateLimitConfigs.postCreate));
+  app.delete("/api/notes/me", rateLimit(RateLimitConfigs.postCreate));
   // Like/repost are federated WRITES (they sign + deliver activities to remote
   // inboxes), so bound them at the write budget rather than the general read
   // budget to limit mass-interaction delivery storms.
@@ -676,6 +680,7 @@ function mountCoreRoutes(app: YurucommuApp): void {
   app.route("/api/follow", followRoutes);
   app.route("/api/timeline", timelineRoutes);
   app.route("/api/posts", postsRoutes);
+  app.route("/api/notes", notesRoutes);
 
   app.get("/api/bookmarks", async (c) => {
     const url = new URL(c.req.url);
@@ -702,23 +707,35 @@ function mountCoreRoutes(app: YurucommuApp): void {
 
 function mountStaticFallback(app: YurucommuApp): void {
   app.all("*", async (c) => {
+    const url = new URL(c.req.url);
     // A request that reaches the static fallback under a backend route prefix
     // means no API / AP / media route matched it — return a genuine JSON 404
     // instead of the SPA HTML shell. Without this, the Cloudflare ASSETS binding
     // (single-page-application mode) served index.html with a 200 for unmatched
     // /api/* paths, so an API client (or our own fetch) got HTML 200 instead of
     // a 404 — the Bun runtime already guarded this; share one source of truth.
-    if (isBackendPath(new URL(c.req.url).pathname)) {
+    if (isBackendPath(url.pathname)) {
       return c.json({ error: "Not Found", code: "NOT_FOUND" }, 404);
     }
 
     if (c.env.ASSETS) {
-      return c.env.ASSETS.fetch(c.req.raw);
+      const response = await c.env.ASSETS.fetch(c.req.raw);
+      const method = c.req.method.toUpperCase();
+      if (
+        response.status === 404 &&
+        (method === "GET" || method === "HEAD") &&
+        !url.pathname.includes(".")
+      ) {
+        const indexUrl = new URL(c.req.url);
+        indexUrl.pathname = "/index.html";
+        indexUrl.search = "";
+        return c.env.ASSETS.fetch(new Request(indexUrl, c.req.raw));
+      }
+      return response;
     }
 
     const storage = (c.env as { STORAGE?: R2Bucket }).STORAGE;
     if (storage) {
-      const url = new URL(c.req.url);
       let assetPath = url.pathname;
 
       if (assetPath === "/" || assetPath === "") {

package/src/backend/middleware/cache.ts

@@ -319,7 +319,20 @@ async function handleCloudflareCache(
   const url = new URL(c.req.url);
   const fullCacheKey = new Request(`${url.origin}/_cache${cacheKey}`);
 
-  const cachedResponse = await cache.match(fullCacheKey);
+  let cachedResponse: Response | undefined;
+  try {
+    cachedResponse = await cache.match(fullCacheKey);
+  } catch (error) {
+    if (isDefaultCacheUnavailable(error)) {
+      log.warn("Cloudflare default cache is unavailable; using memory cache", {
+        event: "cache.default_unavailable",
+        cacheKey,
+        error,
+      });
+      return handleMemoryCache(c, next, cacheKey, config);
+    }
+    throw error;
+  }
 
   if (cachedResponse) {
     const etag = cachedResponse.headers.get("ETag");
@@ -371,6 +384,18 @@ async function handleCloudflareCache(
   c.res = responseToCache;
 }
 
+function isDefaultCacheUnavailable(error: unknown): boolean {
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : "";
+  return /not permitted to access the default cache|default cache.*(?:not|un)available|Cache API.*not available/i.test(
+    message,
+  );
+}
+
 async function handleMemoryCache(
   c: HonoContext,
   next: Next,

package/src/backend/routes/notes.ts

@@ -0,0 +1,218 @@
+import { Hono } from "hono";
+import { and, desc, eq, gt, inArray, isNull, or } from "drizzle-orm";
+import type { SQL } from "drizzle-orm";
+
+import { actorNotes, actors, follows, type Database } from "../../db/index.ts";
+import type { Env, Variables } from "../types.ts";
+import { formatUsername } from "../federation-helpers.ts";
+import { excludeBlockedMutedAuthors } from "../lib/feed-exclude.ts";
+
+const notes = new Hono<{ Bindings: Env; Variables: Variables }>();
+
+const MAX_NOTE_CONTENT_LENGTH = 80;
+const DEFAULT_NOTE_TTL_HOURS = 24;
+const MIN_NOTE_TTL_HOURS = 1;
+const MAX_NOTE_TTL_HOURS = 24;
+const MAX_NOTE_FEED_ITEMS = 60;
+
+type NoteRow = {
+  actorApId: string;
+  content: string;
+  createdAt: string;
+  updatedAt: string;
+  expiresAt: string;
+  preferredUsername: string;
+  name: string | null;
+  iconUrl: string | null;
+};
+
+type NoteResponse = {
+  actor: {
+    ap_id: string;
+    username: string;
+    preferred_username: string;
+    name: string | null;
+    icon_url: string | null;
+  };
+  content: string;
+  created_at: string;
+  updated_at: string;
+  expires_at: string;
+  is_mine: boolean;
+};
+
+function sanitizeContent(input: unknown): string | null {
+  if (typeof input !== "string") return null;
+  const content = input.trim();
+  if (content.length === 0 || content.length > MAX_NOTE_CONTENT_LENGTH) {
+    return null;
+  }
+  return content;
+}
+
+function ttlHours(input: unknown): number {
+  if (typeof input !== "number" || !Number.isFinite(input)) {
+    return DEFAULT_NOTE_TTL_HOURS;
+  }
+  return Math.min(
+    MAX_NOTE_TTL_HOURS,
+    Math.max(MIN_NOTE_TTL_HOURS, Math.floor(input)),
+  );
+}
+
+function formatNote(row: NoteRow, viewerApId: string): NoteResponse {
+  return {
+    actor: {
+      ap_id: row.actorApId,
+      username: formatUsername(row.actorApId),
+      preferred_username: row.preferredUsername,
+      name: row.name,
+      icon_url: row.iconUrl,
+    },
+    content: row.content,
+    created_at: row.createdAt,
+    updated_at: row.updatedAt,
+    expires_at: row.expiresAt,
+    is_mine: row.actorApId === viewerApId,
+  };
+}
+
+async function loadActiveNotes(
+  db: Database,
+  viewerApId: string,
+): Promise<NoteRow[]> {
+  const now = new Date().toISOString();
+  const followingSubquery = db
+    .select({ id: follows.followingApId })
+    .from(follows)
+    .where(
+      and(eq(follows.followerApId, viewerApId), eq(follows.status, "accepted")),
+    );
+
+  const filters: SQL[] = [
+    isNull(actorNotes.deletedAt),
+    isNull(actors.deletedAt),
+    gt(actorNotes.expiresAt, now),
+    or(
+      eq(actorNotes.actorApId, viewerApId),
+      inArray(actorNotes.actorApId, followingSubquery),
+    )!,
+  ];
+  const excludeAuthors = excludeBlockedMutedAuthors(
+    db,
+    viewerApId,
+    actorNotes.actorApId,
+  );
+  if (excludeAuthors) filters.push(excludeAuthors);
+
+  return await db
+    .select({
+      actorApId: actorNotes.actorApId,
+      content: actorNotes.content,
+      createdAt: actorNotes.createdAt,
+      updatedAt: actorNotes.updatedAt,
+      expiresAt: actorNotes.expiresAt,
+      preferredUsername: actors.preferredUsername,
+      name: actors.name,
+      iconUrl: actors.iconUrl,
+    })
+    .from(actorNotes)
+    .innerJoin(actors, eq(actorNotes.actorApId, actors.apId))
+    .where(and(...filters))
+    .orderBy(desc(actorNotes.updatedAt))
+    .limit(MAX_NOTE_FEED_ITEMS);
+}
+
+notes.get("/", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "Unauthorized" }, 401);
+
+  const rows = await loadActiveNotes(c.get("db"), actor.ap_id);
+  return c.json({ notes: rows.map((row) => formatNote(row, actor.ap_id)) });
+});
+
+notes.post("/", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "Unauthorized" }, 401);
+
+  const body = await c.req.json().catch(() => null);
+  if (!body || typeof body !== "object") {
+    return c.json({ error: "JSON body required" }, 400);
+  }
+
+  const content = sanitizeContent((body as { content?: unknown }).content);
+  if (!content) {
+    return c.json(
+      {
+        error: `content must be 1-${MAX_NOTE_CONTENT_LENGTH} characters`,
+      },
+      400,
+    );
+  }
+
+  const now = new Date().toISOString();
+  const expiresAt = new Date(
+    Date.now() +
+      ttlHours((body as { expires_in_hours?: unknown }).expires_in_hours) *
+        60 *
+        60 *
+        1000,
+  ).toISOString();
+  const db = c.get("db");
+
+  await db
+    .insert(actorNotes)
+    .values({
+      actorApId: actor.ap_id,
+      content,
+      createdAt: now,
+      updatedAt: now,
+      expiresAt,
+      deletedAt: null,
+    })
+    .onConflictDoUpdate({
+      target: actorNotes.actorApId,
+      set: {
+        content,
+        createdAt: now,
+        updatedAt: now,
+        expiresAt,
+        deletedAt: null,
+      },
+    });
+
+  return c.json(
+    {
+      note: formatNote(
+        {
+          actorApId: actor.ap_id,
+          content,
+          createdAt: now,
+          updatedAt: now,
+          expiresAt,
+          preferredUsername: actor.preferred_username,
+          name: actor.name,
+          iconUrl: actor.icon_url,
+        },
+        actor.ap_id,
+      ),
+    },
+    201,
+  );
+});
+
+notes.delete("/me", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "Unauthorized" }, 401);
+
+  const now = new Date().toISOString();
+  await c
+    .get("db")
+    .update(actorNotes)
+    .set({ deletedAt: now, updatedAt: now, expiresAt: now })
+    .where(eq(actorNotes.actorApId, actor.ap_id));
+
+  return c.json({ success: true });
+});
+
+export default notes;

package/src/backend/routes/recommendations.ts

@@ -2,10 +2,12 @@ import { Hono } from "hono";
 import { sql } from "drizzle-orm";
 import type { Env, Variables } from "../types.ts";
 import { formatUsername } from "../federation-helpers.ts";
+import { logger } from "../lib/logger.ts";
 import { CacheTags, CacheTTL, withCache } from "../middleware/cache.ts";
 import { batchLoadActorInfo } from "./communities/membership-shared.ts";
 
 const recommendations = new Hono<{ Bindings: Env; Variables: Variables }>();
+const log = logger.child({ component: "recommendations" });
 
 /**
  * GET /api/recommendations/users
@@ -28,60 +30,69 @@ recommendations.get(
     const db = c.get("db");
     const myApId = actor.ap_id;
 
-    const candidates = await db.all<{ ap_id: string; mutual_count: number }>(
-      sql`
-      SELECT f2.following_ap_id AS ap_id, COUNT(DISTINCT f2.follower_ap_id) AS mutual_count
-      FROM follows f1
-      JOIN follows f2 ON f1.following_ap_id = f2.follower_ap_id AND f2.status = 'accepted'
-      WHERE f1.follower_ap_id = ${myApId}
-        AND f1.status = 'accepted'
-        AND f2.following_ap_id != ${myApId}
-        AND f2.following_ap_id NOT IN (
-          SELECT following_ap_id FROM follows
-          WHERE follower_ap_id = ${myApId} AND status IN ('accepted', 'pending')
-        )
-        AND f2.following_ap_id NOT IN (
-          SELECT blocked_ap_id FROM blocks WHERE blocker_ap_id = ${myApId}
-        )
-        AND f2.following_ap_id NOT IN (
-          SELECT muted_ap_id FROM mutes WHERE muter_ap_id = ${myApId}
-        )
-        AND f2.following_ap_id NOT IN (
-          -- Hide deleted AND private/locked (is_private = 1) accounts. A locked
-          -- account opted out of discovery (discoverable:false), and every other
-          -- actor-discovery surface (search.actors, takos-tools searchUsers /
-          -- getUserProfile) excludes is_private = 1 — this friends-of-friends
-          -- panel must match or it leaks the locked account's handle/name/icon.
-          -- is_private lives only on the LOCAL actors table; remote candidates
-          -- (actorCache) are unaffected, same scope as the other surfaces.
-          SELECT ap_id FROM actors WHERE deleted_at IS NOT NULL OR is_private = 1
-        )
-      GROUP BY f2.following_ap_id
-      ORDER BY mutual_count DESC
-      LIMIT 5
-    `,
-    );
+    try {
+      const candidates = await db.all<{ ap_id: string; mutual_count: number }>(
+        sql`
+        SELECT f2.following_ap_id AS ap_id, COUNT(DISTINCT f2.follower_ap_id) AS mutual_count
+        FROM follows f1
+        JOIN follows f2 ON f1.following_ap_id = f2.follower_ap_id AND f2.status = 'accepted'
+        WHERE f1.follower_ap_id = ${myApId}
+          AND f1.status = 'accepted'
+          AND f2.following_ap_id != ${myApId}
+          AND f2.following_ap_id NOT IN (
+            SELECT following_ap_id FROM follows
+            WHERE follower_ap_id = ${myApId} AND status IN ('accepted', 'pending')
+          )
+          AND f2.following_ap_id NOT IN (
+            SELECT blocked_ap_id FROM blocks WHERE blocker_ap_id = ${myApId}
+          )
+          AND f2.following_ap_id NOT IN (
+            SELECT muted_ap_id FROM mutes WHERE muter_ap_id = ${myApId}
+          )
+          AND f2.following_ap_id NOT IN (
+            -- Hide deleted AND private/locked (is_private = 1) accounts. A locked
+            -- account opted out of discovery (discoverable:false), and every other
+            -- actor-discovery surface (search.actors, takos-tools searchUsers /
+            -- getUserProfile) excludes is_private = 1 — this friends-of-friends
+            -- panel must match or it leaks the locked account's handle/name/icon.
+            -- is_private lives only on the LOCAL actors table; remote candidates
+            -- (actorCache) are unaffected, same scope as the other surfaces.
+            SELECT ap_id FROM actors WHERE deleted_at IS NOT NULL OR is_private = 1
+          )
+        GROUP BY f2.following_ap_id
+        ORDER BY mutual_count DESC
+        LIMIT 5
+      `,
+      );
 
-    if (candidates.length === 0) return c.json({ users: [] });
+      if (candidates.length === 0) return c.json({ users: [] });
 
-    const actorMap = await batchLoadActorInfo(
-      db,
-      candidates.map((r) => r.ap_id),
-    );
+      const actorMap = await batchLoadActorInfo(
+        db,
+        candidates.map((r) => r.ap_id),
+      );
 
-    const users = candidates.map((row) => {
-      const info = actorMap.get(row.ap_id);
-      return {
-        ap_id: row.ap_id,
-        preferred_username: info?.preferredUsername ?? null,
-        name: info?.name ?? null,
-        icon_url: info?.iconUrl ?? null,
-        username: formatUsername(row.ap_id),
-        mutual_count: Number(row.mutual_count),
-      };
-    });
+      const users = candidates.map((row) => {
+        const info = actorMap.get(row.ap_id);
+        return {
+          ap_id: row.ap_id,
+          preferred_username: info?.preferredUsername ?? null,
+          name: info?.name ?? null,
+          icon_url: info?.iconUrl ?? null,
+          username: formatUsername(row.ap_id),
+          mutual_count: Number(row.mutual_count),
+        };
+      });
 
-    return c.json({ users });
+      return c.json({ users });
+    } catch (error) {
+      log.warn("Recommendations failed; returning empty suggestions", {
+        event: "recommendations.failed",
+        actorApId: myApId,
+        error,
+      });
+      return c.json({ users: [] });
+    }
   },
 );
 

package/src/backend/routes/stories/interactions.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { and, eq, gt, sql } from "drizzle-orm";
+import { and, count, desc, eq, gt, sql } from "drizzle-orm";
 import type { Env, Variables } from "../../types.ts";
 import {
   activities,
@@ -18,12 +18,14 @@ import {
   safeJsonParse,
 } from "../../federation-helpers.ts";
 import {
+  buildAuthor,
   canViewerReadStory,
   findStory,
   getVoteCounts,
   resolveStoryApId,
   sumVotes,
 } from "./query-helpers.ts";
+import { loadActorInfoMap } from "../actors-helpers.ts";
 import { enqueueDeliveryToActor } from "../../lib/delivery/queue.ts";
 import { actorIsBlockedBy } from "../../lib/post-visibility.ts";
 import { rateLimit, RateLimitConfigs } from "../../middleware/rate-limit.ts";
@@ -573,4 +575,66 @@ stories.get("/:id/votes", async (c) => {
   return c.json({ votes, total: sumVotes(votes), user_vote });
 });
 
+// Cap the returned viewer list most-recent-first. `view_count` stays the true
+// total (the author sees the real number even when the list is truncated).
+const STORY_VIEWERS_LIMIT = 200;
+
+// Get the "seen by" viewer list for a story (author-only).
+stories.get("/:id/views", async (c) => {
+  const db = c.get("db");
+  const actor = c.get("actor");
+  const baseUrl = c.env.APP_URL;
+  // Resolve the id the same way every sibling /:id/* route does.
+  const apId = resolveStoryApId(c.req.param("id"), baseUrl);
+
+  const story = await findStory(db, apId);
+  if (!story) return c.json({ error: "Story not found" }, 404);
+
+  // Author-only: only the story author may see WHO viewed. Anyone else
+  // (including anonymous) gets 404 so the viewer list isn't disclosed and the
+  // endpoint isn't a story-existence oracle for non-authors.
+  if (!actor || actor.ap_id !== story.attributedTo) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+  // Mirror the /:id/votes expiry gate: don't serve the list for an expired
+  // story before the reaper runs.
+  if (story.endTime && story.endTime < new Date().toISOString()) {
+    return c.json({ error: "Story has expired" }, 410);
+  }
+
+  // True total (uncapped) — stays accurate even when the list below is capped.
+  const totalRow = await db
+    .select({ value: count() })
+    .from(storyViews)
+    .where(eq(storyViews.storyApId, apId))
+    .get();
+  const view_count = totalRow?.value ?? 0;
+
+  // Most-recent-first page of viewers, capped.
+  const rows = await db
+    .select({
+      actorApId: storyViews.actorApId,
+      viewedAt: storyViews.viewedAt,
+    })
+    .from(storyViews)
+    .where(eq(storyViews.storyApId, apId))
+    .orderBy(desc(storyViews.viewedAt))
+    .limit(STORY_VIEWERS_LIMIT);
+
+  // Hydrate ap_id → PostAuthor via the same batch loader the follower/story
+  // lists use (local `actors` + `actor_cache`, local wins). A remote viewer
+  // absent from both degrades to a best-effort author in `buildAuthor`.
+  const infoMap = await loadActorInfoMap(
+    db,
+    rows.map((r) => r.actorApId),
+    "author",
+  );
+  const viewers = rows.map((r) => ({
+    actor: buildAuthor(r.actorApId, infoMap.get(r.actorApId)),
+    viewed_at: r.viewedAt,
+  }));
+
+  return c.json({ view_count, viewers });
+});
+
 export default stories;

package/src/backend/routes/stories/query-helpers.ts

@@ -11,7 +11,11 @@ import {
   storyVotes,
 } from "../../../db/index.ts";
 import type { IObjectStorage } from "../../runtime/types.ts";
-import { objectApId, safeJsonParse } from "../../federation-helpers.ts";
+import {
+  formatUsername,
+  objectApId,
+  safeJsonParse,
+} from "../../federation-helpers.ts";
 import {
   deleteObjectCascade,
   purgeMediaBlobs,
@@ -271,6 +275,49 @@ export async function fetchActorCache(
   );
 }
 
+// ---------------------------------------------------------------------------
+// Author projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Public author projection for a story author / viewer (the `PostAuthor` shape
+ * used across the feed / story surfaces). Shared by the story feed and the
+ * viewer ("seen by") list so both hydrate an ap_id → author identically.
+ */
+export type StoryAuthor = {
+  ap_id: string;
+  username: string;
+  preferred_username: string | null;
+  name: string | null;
+  icon_url: string | null;
+};
+
+/**
+ * Build a StoryAuthor from available data sources. A remote actor with no local
+ * `actors` / `actor_cache` row (`data` undefined) degrades gracefully to a
+ * best-effort `username` derived from the ap_id plus null fields, so a viewer is
+ * never dropped just because its profile isn't cached locally.
+ */
+export function buildAuthor(
+  apId: string,
+  data:
+    | {
+        preferredUsername?: string | null;
+        name?: string | null;
+        iconUrl?: string | null;
+      }
+    | null
+    | undefined,
+): StoryAuthor {
+  return {
+    ap_id: apId,
+    username: formatUsername(apId),
+    preferred_username: data?.preferredUsername || null,
+    name: data?.name || null,
+    icon_url: data?.iconUrl || null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Story data cleanup & transformation
 // ---------------------------------------------------------------------------

package/src/backend/routes/stories/routes.ts

@@ -21,7 +21,6 @@ import type { IObjectStorage } from "../../runtime/types.ts";
 import {
   activityApId,
   actorApId,
-  formatUsername,
   generateId,
   objectApId,
 } from "../../federation-helpers.ts";
@@ -31,10 +30,12 @@ import { maybeReapDrainedTombstones } from "../actors.ts";
 import { checkCommunityPostPermission } from "../posts/post-helpers.ts";
 import { rateLimit, RateLimitConfigs } from "../../middleware/rate-limit.ts";
 import {
+  buildAuthor,
   cleanupExpiredStories,
   fetchActorCache,
   fetchBatchVotes,
   fetchBlockedAndMutedIds,
+  type StoryAuthor,
   sumVotes,
   transformStoryData,
   validateOverlays,
@@ -101,14 +102,6 @@ stories.post("/delete", storyWriteLimiter);
 
 type VoteResults = Record<number, number>;
 
-type StoryAuthor = {
-  ap_id: string;
-  username: string;
-  preferred_username: string | null;
-  name: string | null;
-  icon_url: string | null;
-};
-
 type StoryResponse = {
   ap_id: string;
   author: StoryAuthor;
@@ -160,27 +153,6 @@ const MAX_STORY_CAPTION_LENGTH = 500;
 // feed page; a busy instance simply shows the 90 most recent.
 const MAX_STORY_FEED_ITEMS = 90;
 
-/** Build a StoryAuthor from available data sources. */
-function buildAuthor(
-  apId: string,
-  data:
-    | {
-        preferredUsername?: string | null;
-        name?: string | null;
-        iconUrl?: string | null;
-      }
-    | null
-    | undefined,
-): StoryAuthor {
-  return {
-    ap_id: apId,
-    username: formatUsername(apId),
-    preferred_username: data?.preferredUsername || null,
-    name: data?.name || null,
-    icon_url: data?.iconUrl || null,
-  };
-}
-
 /** Build a StoryResponse from a story object row and pre-fetched data. */
 function buildStoryResponse(
   s: {

package/src/db/schema/index.ts

@@ -12,6 +12,7 @@ export * from "./social.ts";
 export * from "./reports.ts";
 export * from "./communities.ts";
 export * from "./stories.ts";
+export * from "./notes.ts";
 export * from "./messaging.ts";
 export * from "./mobile.ts";
 export * from "./relations.ts";

package/src/db/schema/notes.ts

@@ -0,0 +1,26 @@
+/**
+ * Short-lived actor status notes.
+ */
+
+import { index, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { nowIso } from "./date-utils.ts";
+
+export const actorNotes = sqliteTable(
+  "actor_notes",
+  {
+    actorApId: text("actor_ap_id").primaryKey(),
+    content: text("content").notNull(),
+    createdAt: text("created_at").notNull().$defaultFn(nowIso),
+    updatedAt: text("updated_at")
+      .notNull()
+      .$defaultFn(nowIso)
+      .$onUpdateFn(nowIso),
+    expiresAt: text("expires_at").notNull(),
+    deletedAt: text("deleted_at"),
+  },
+  (t) => [
+    index("actor_notes_expires_idx").on(t.expiresAt),
+    index("actor_notes_updated_idx").on(t.updatedAt),
+    index("actor_notes_deleted_idx").on(t.deletedAt),
+  ],
+);