From f3b25f91863e96cfdf6ed3d60da818e314e33069 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 21 Jul 2026 18:20:04 -0700
Subject: [PATCH 1/2] refactor: paginate album/artist/author list endpoints via
 parsePagination (#2840)

---
 .changelog/NEXT.md            |  1 +
 server/routes/albums.js       |  8 +++++---
 server/routes/albums.test.js  | 13 +++++++++++++
 server/routes/artists.js      |  8 +++++---
 server/routes/artists.test.js | 13 +++++++++++++
 server/routes/authors.js      |  8 +++++---
 server/routes/authors.test.js | 13 +++++++++++++
 7 files changed, 55 insertions(+), 9 deletions(-)

diff --git a/.changelog/NEXT.md b/.changelog/NEXT.md
index 766bc5e51b..2c12a49986 100644
--- a/.changelog/NEXT.md
+++ b/.changelog/NEXT.md
@@ -35,6 +35,7 @@
 
 ## Internal
 
+- **[issue-2840] Paginate album/artist/author list endpoints** — `GET /api/albums`, `/api/artists`, and `/api/authors` now accept `limit`/`offset` via the shared `parsePagination`/`paginateArray` helpers, returning the same `{ items, total, limit, offset }` envelope the notes/mood-board/loras list endpoints use when a pagination param is present. Unparameterized requests still return the full array, so existing callers are unaffected.
 - **[issue-2832] Split the boot-schema DDL into per-domain modules** — the ~1265-line inline `CREATE TABLE`/`CREATE INDEX`/trigger block in `ensureSchemaImpl()` (`server/lib/db.js`) is extracted into per-domain modules under `server/lib/db/schema/` (catalog, media, universes, writers-room, pipeline, privacy, tribe, audit, …), each exporting a statement array; `ensureSchemaImpl` is now a thin composer. Statement text and order are byte-identical, so the composed schema is unchanged.
 - **[issue-2834] Split the ~1990-line `VideoGen.jsx` into hooks + subcomponents** — the client-side batch-queue orchestration moves into `useVideoGenQueue`, the pure model-memory / FFLF frame-budget / mode-compat helpers into `lib/videoGenParams.js`, and four presentational blocks into `components/videoGen/` (`RuntimeFingerprint`, `ModelRepairBanner`, `VideoPreviewPanel`, `VideoGenGallery`). The inline runtime-status `fetch()` now routes through a `getVideoGenRuntimeStatus` service wrapper, and the Seed input gains a proper `<label htmlFor>`/`id` pairing. Behavior and deep-link routing are unchanged.
 - **[issue-2835] Split the ~2875-line `ArcCanvas.jsx` into per-component files** — each of the 32 subcomponents/helpers (ArcHeader, EditorialRoadmapPanel, SeasonRow, IssueRow, VolumeCoversPanel, …) now lives in its own file under `client/src/components/pipeline/arcCanvas/`, with the shared severity-color map in `arcCanvas/shared.js`. `ArcCanvas.jsx` (default export) is now a thin 122-line composer and still re-exports `ArcRoadmapChart` so its public import path is unchanged. Pure mechanical, behavior-preserving refactor — no rendered-output change.
diff --git a/server/routes/albums.js b/server/routes/albums.js
index 7e27a01f90..f208e55e0a 100644
--- a/server/routes/albums.js
+++ b/server/routes/albums.js
@@ -14,7 +14,7 @@
 import { Router } from 'express';
 import { z } from 'zod';
 import { asyncHandler, ServerError } from '../lib/errorHandler.js';
-import { validateRequest } from '../lib/validation.js';
+import { validateRequest, isPaginationRequested, paginateArray } from '../lib/validation.js';
 import * as albums from '../services/albums/index.js';
 import * as tracks from '../services/tracks/index.js';
 
@@ -104,8 +104,10 @@ async function reconcileAlbumMembership(album) {
   }));
 }
 
-router.get('/', asyncHandler(async (_req, res) => {
-  res.json(await albums.listAlbums());
+router.get('/', asyncHandler(async (req, res) => {
+  const list = await albums.listAlbums();
+  if (!isPaginationRequested(req.query)) return res.json(list);
+  res.json(paginateArray(list, req.query, { defaultLimit: 50, maxLimit: 500 }));
 }));
 
 router.post('/', asyncHandler(async (req, res) => {
diff --git a/server/routes/albums.test.js b/server/routes/albums.test.js
index fbb61528dc..618b50f26e 100644
--- a/server/routes/albums.test.js
+++ b/server/routes/albums.test.js
@@ -49,6 +49,19 @@ describe('albums routes', () => {
     expect(r.body).toEqual([{ id: 'album-1', title: 'Debut' }]);
   });
 
+  it('GET / returns a bounded envelope when pagination is requested', async () => {
+    albums.listAlbums.mockResolvedValueOnce(
+      Array.from({ length: 5 }, (_, i) => ({ id: `album-${i}`, title: `T${i}` }))
+    );
+    const r = await request(app).get('/api/albums?limit=2&offset=1');
+    expect(r.status).toBe(200);
+    expect(r.body.items).toHaveLength(2);
+    expect(r.body.items[0].id).toBe('album-1');
+    expect(r.body.total).toBe(5);
+    expect(r.body.limit).toBe(2);
+    expect(r.body.offset).toBe(1);
+  });
+
   it('POST / creates an album', async () => {
     const r = await request(app).post('/api/albums').send({ title: 'Debut', genre: 'folk' });
     expect(r.status).toBe(201);
diff --git a/server/routes/artists.js b/server/routes/artists.js
index 7137a73503..a8f74d4406 100644
--- a/server/routes/artists.js
+++ b/server/routes/artists.js
@@ -15,7 +15,7 @@
 import { Router } from 'express';
 import { z } from 'zod';
 import { asyncHandler, ServerError } from '../lib/errorHandler.js';
-import { validateRequest } from '../lib/validation.js';
+import { validateRequest, isPaginationRequested, paginateArray } from '../lib/validation.js';
 import * as artists from '../services/artists/index.js';
 
 const router = Router();
@@ -48,8 +48,10 @@ const patchSchema = z.object({
   portraitImageUrl: portraitImageUrlField.optional(),
 }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' });
 
-router.get('/', asyncHandler(async (_req, res) => {
-  res.json(await artists.listArtists());
+router.get('/', asyncHandler(async (req, res) => {
+  const list = await artists.listArtists();
+  if (!isPaginationRequested(req.query)) return res.json(list);
+  res.json(paginateArray(list, req.query, { defaultLimit: 50, maxLimit: 500 }));
 }));
 
 router.post('/', asyncHandler(async (req, res) => {
diff --git a/server/routes/artists.test.js b/server/routes/artists.test.js
index a342b63957..82b3d19289 100644
--- a/server/routes/artists.test.js
+++ b/server/routes/artists.test.js
@@ -43,6 +43,19 @@ describe('artists routes', () => {
     expect(r.body).toEqual([{ id: 'artist-1', name: 'Nova' }]);
   });
 
+  it('GET / returns a bounded envelope when pagination is requested', async () => {
+    artists.listArtists.mockResolvedValueOnce(
+      Array.from({ length: 5 }, (_, i) => ({ id: `artist-${i}`, name: `N${i}` }))
+    );
+    const r = await request(app).get('/api/artists?limit=2&offset=1');
+    expect(r.status).toBe(200);
+    expect(r.body.items).toHaveLength(2);
+    expect(r.body.items[0].id).toBe('artist-1');
+    expect(r.body.total).toBe(5);
+    expect(r.body.limit).toBe(2);
+    expect(r.body.offset).toBe(1);
+  });
+
   it('POST / creates an artist', async () => {
     const r = await request(app).post('/api/artists').send({ name: 'Nova', genre: 'indie folk' });
     expect(r.status).toBe(201);
diff --git a/server/routes/authors.js b/server/routes/authors.js
index 6d9eb7fc7d..a52e681133 100644
--- a/server/routes/authors.js
+++ b/server/routes/authors.js
@@ -11,7 +11,7 @@
 import { Router } from 'express';
 import { z } from 'zod';
 import { asyncHandler, ServerError } from '../lib/errorHandler.js';
-import { validateRequest } from '../lib/validation.js';
+import { validateRequest, isPaginationRequested, paginateArray } from '../lib/validation.js';
 import * as authors from '../services/authors/index.js';
 
 const router = Router();
@@ -41,8 +41,10 @@ const patchSchema = z.object({
   headshotImageUrl: headshotImageUrlField.optional(),
 }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' });
 
-router.get('/', asyncHandler(async (_req, res) => {
-  res.json(await authors.listAuthors());
+router.get('/', asyncHandler(async (req, res) => {
+  const list = await authors.listAuthors();
+  if (!isPaginationRequested(req.query)) return res.json(list);
+  res.json(paginateArray(list, req.query, { defaultLimit: 50, maxLimit: 500 }));
 }));
 
 router.post('/', asyncHandler(async (req, res) => {
diff --git a/server/routes/authors.test.js b/server/routes/authors.test.js
index ff9955477d..c1b10a705e 100644
--- a/server/routes/authors.test.js
+++ b/server/routes/authors.test.js
@@ -42,6 +42,19 @@ describe('authors routes', () => {
     expect(r.body).toEqual([{ id: 'auth-1', name: 'Jane' }]);
   });
 
+  it('GET / returns a bounded envelope when pagination is requested', async () => {
+    authors.listAuthors.mockResolvedValueOnce(
+      Array.from({ length: 5 }, (_, i) => ({ id: `auth-${i}`, name: `A${i}` }))
+    );
+    const r = await request(app).get('/api/authors?limit=2&offset=1');
+    expect(r.status).toBe(200);
+    expect(r.body.items).toHaveLength(2);
+    expect(r.body.items[0].id).toBe('auth-1');
+    expect(r.body.total).toBe(5);
+    expect(r.body.limit).toBe(2);
+    expect(r.body.offset).toBe(1);
+  });
+
   it('POST / creates an author', async () => {
     const r = await request(app).post('/api/authors').send({ name: 'Jane', bio: 'blurb' });
     expect(r.status).toBe(201);

From b91013d61bd301ae1fd4d69953f81122ee1c0bb2 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Wed, 22 Jul 2026 07:37:53 -0700
Subject: [PATCH 2/2] document the opt-in pagination contract on
 album/artist/author lists and guard the bare-array default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The paginated envelope is opt-in (only when limit/offset is present) because
every client caller — AlbumsManager, TracksManager, ArtistsManager,
ArtistPicker, the Authors page, AuthorPicker — calls list*() with no query
params and renders the response as a bare array. Add the same intent comment
loras.js/moodBoard.js carry so the conditional isn't 'simplified' away, note
the query params in each route-header surface listing, and add a regression
test per route asserting an unparameterized request still returns the full
unbounded array.
---
 server/routes/albums.js       |  6 +++++-
 server/routes/albums.test.js  | 13 +++++++++++++
 server/routes/artists.js      |  6 +++++-
 server/routes/artists.test.js | 13 +++++++++++++
 server/routes/authors.js      |  6 +++++-
 server/routes/authors.test.js | 13 +++++++++++++
 6 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/server/routes/albums.js b/server/routes/albums.js
index f208e55e0a..fe25fa8816 100644
--- a/server/routes/albums.js
+++ b/server/routes/albums.js
@@ -1,7 +1,8 @@
 /**
  * Music album routes.
  *
- *   GET    /api/albums        → Album[]   (live, sorted by title)
+ *   GET    /api/albums        → Album[]   (live, sorted by title; `?limit`/`?offset`
+ *                                          switches to the bounded envelope)
  *   POST   /api/albums        → Album
  *   GET    /api/albums/:id     → Album
  *   PATCH  /api/albums/:id     → Album
@@ -104,6 +105,9 @@ async function reconcileAlbumMembership(album) {
   }));
 }
 
+// Backward-compatible by default: returns the full albums array. When a client
+// passes `limit`/`offset`, the response becomes the bounded
+// `{ items, total, limit, offset }` envelope every paginated PortOS list shares.
 router.get('/', asyncHandler(async (req, res) => {
   const list = await albums.listAlbums();
   if (!isPaginationRequested(req.query)) return res.json(list);
diff --git a/server/routes/albums.test.js b/server/routes/albums.test.js
index 618b50f26e..08423d23f7 100644
--- a/server/routes/albums.test.js
+++ b/server/routes/albums.test.js
@@ -49,6 +49,19 @@ describe('albums routes', () => {
     expect(r.body).toEqual([{ id: 'album-1', title: 'Debut' }]);
   });
 
+  // Regression guard: every client caller (AlbumsManager, TracksManager) calls
+  // listAlbums() with no query params. If this ever returns an envelope instead
+  // of a bare array, those lists silently render empty.
+  it('GET / without pagination params returns the unbounded bare array', async () => {
+    albums.listAlbums.mockResolvedValueOnce(
+      Array.from({ length: 120 }, (_, i) => ({ id: `album-${i}`, title: `T${i}` }))
+    );
+    const r = await request(app).get('/api/albums');
+    expect(r.status).toBe(200);
+    expect(Array.isArray(r.body)).toBe(true);
+    expect(r.body).toHaveLength(120);
+  });
+
   it('GET / returns a bounded envelope when pagination is requested', async () => {
     albums.listAlbums.mockResolvedValueOnce(
       Array.from({ length: 5 }, (_, i) => ({ id: `album-${i}`, title: `T${i}` }))
diff --git a/server/routes/artists.js b/server/routes/artists.js
index a8f74d4406..c0cefe6b7e 100644
--- a/server/routes/artists.js
+++ b/server/routes/artists.js
@@ -1,7 +1,8 @@
 /**
  * Music artist routes.
  *
- *   GET    /api/artists        → Artist[]   (live, sorted by name)
+ *   GET    /api/artists        → Artist[]   (live, sorted by name; `?limit`/`?offset`
+ *                                            switches to the bounded envelope)
  *   POST   /api/artists        → Artist
  *   GET    /api/artists/:id     → Artist
  *   PATCH  /api/artists/:id     → Artist
@@ -48,6 +49,9 @@ const patchSchema = z.object({
   portraitImageUrl: portraitImageUrlField.optional(),
 }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' });
 
+// Backward-compatible by default: returns the full artists array. When a client
+// passes `limit`/`offset`, the response becomes the bounded
+// `{ items, total, limit, offset }` envelope every paginated PortOS list shares.
 router.get('/', asyncHandler(async (req, res) => {
   const list = await artists.listArtists();
   if (!isPaginationRequested(req.query)) return res.json(list);
diff --git a/server/routes/artists.test.js b/server/routes/artists.test.js
index 82b3d19289..ed37e4a98f 100644
--- a/server/routes/artists.test.js
+++ b/server/routes/artists.test.js
@@ -43,6 +43,19 @@ describe('artists routes', () => {
     expect(r.body).toEqual([{ id: 'artist-1', name: 'Nova' }]);
   });
 
+  // Regression guard: every client caller (ArtistsManager, ArtistPicker) calls
+  // listArtists() with no query params. If this ever returns an envelope instead
+  // of a bare array, those lists silently render empty.
+  it('GET / without pagination params returns the unbounded bare array', async () => {
+    artists.listArtists.mockResolvedValueOnce(
+      Array.from({ length: 120 }, (_, i) => ({ id: `artist-${i}`, name: `N${i}` }))
+    );
+    const r = await request(app).get('/api/artists');
+    expect(r.status).toBe(200);
+    expect(Array.isArray(r.body)).toBe(true);
+    expect(r.body).toHaveLength(120);
+  });
+
   it('GET / returns a bounded envelope when pagination is requested', async () => {
     artists.listArtists.mockResolvedValueOnce(
       Array.from({ length: 5 }, (_, i) => ({ id: `artist-${i}`, name: `N${i}` }))
diff --git a/server/routes/authors.js b/server/routes/authors.js
index a52e681133..929f02335b 100644
--- a/server/routes/authors.js
+++ b/server/routes/authors.js
@@ -1,7 +1,8 @@
 /**
  * Author persona routes.
  *
- *   GET    /api/authors        → Author[]   (live, sorted by name)
+ *   GET    /api/authors        → Author[]   (live, sorted by name; `?limit`/`?offset`
+ *                                            switches to the bounded envelope)
  *   POST   /api/authors        → Author
  *   GET    /api/authors/:id     → Author
  *   PATCH  /api/authors/:id     → Author
@@ -41,6 +42,9 @@ const patchSchema = z.object({
   headshotImageUrl: headshotImageUrlField.optional(),
 }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' });
 
+// Backward-compatible by default: returns the full authors array. When a client
+// passes `limit`/`offset`, the response becomes the bounded
+// `{ items, total, limit, offset }` envelope every paginated PortOS list shares.
 router.get('/', asyncHandler(async (req, res) => {
   const list = await authors.listAuthors();
   if (!isPaginationRequested(req.query)) return res.json(list);
diff --git a/server/routes/authors.test.js b/server/routes/authors.test.js
index c1b10a705e..4066ebe1d4 100644
--- a/server/routes/authors.test.js
+++ b/server/routes/authors.test.js
@@ -42,6 +42,19 @@ describe('authors routes', () => {
     expect(r.body).toEqual([{ id: 'auth-1', name: 'Jane' }]);
   });
 
+  // Regression guard: every client caller (Authors page, AuthorPicker) calls
+  // listAuthors() with no query params. If this ever returns an envelope instead
+  // of a bare array, those lists silently render empty.
+  it('GET / without pagination params returns the unbounded bare array', async () => {
+    authors.listAuthors.mockResolvedValueOnce(
+      Array.from({ length: 120 }, (_, i) => ({ id: `auth-${i}`, name: `A${i}` }))
+    );
+    const r = await request(app).get('/api/authors');
+    expect(r.status).toBe(200);
+    expect(Array.isArray(r.body)).toBe(true);
+    expect(r.body).toHaveLength(120);
+  });
+
   it('GET / returns a bounded envelope when pagination is requested', async () => {
     authors.listAuthors.mockResolvedValueOnce(
       Array.from({ length: 5 }, (_, i) => ({ id: `auth-${i}`, name: `A${i}` }))