@pattern-stack/codegen 0.26.1 → 0.27.0

package/dist/src/index.js

@@ -47,14 +47,18 @@ import {
   validatePatternProject
 } from "../chunk-K4BQQ2NN.js";
 import "../chunk-KVOWSC5S.js";
+import "../chunk-VCXOPBYY.js";
 import "../chunk-PRWIX6UW.js";
-import "../chunk-7XDB4OMR.js";
-import "../chunk-QXYKV4CE.js";
+import "../chunk-W4JYZSQK.js";
 import "../chunk-EO2QPOKH.js";
-import "../chunk-HLURWFIT.js";
+import "../chunk-SQDOBLBP.js";
+import "../chunk-YIVQ7KLS.js";
+import "../chunk-LG57S2SC.js";
+import "../chunk-IASPGFFK.js";
+import "../chunk-S5G3HO7N.js";
+import "../chunk-MZ6GV4YF.js";
 import "../chunk-HNWZFNKP.js";
 import "../chunk-AHV4GDYM.js";
-import "../chunk-SQDOBLBP.js";
 import "../chunk-43SBT72G.js";
 import "../chunk-4MF3HKJA.js";
 import "../chunk-TIZXQU26.js";
@@ -62,10 +66,6 @@ import "../chunk-JEINYUJH.js";
 import "../chunk-5TK7MEN4.js";
 import "../chunk-4KNXX6TI.js";
 import "../chunk-3CJFPU6Q.js";
-import "../chunk-QO35B6BN.js";
-import "../chunk-MZ6GV4YF.js";
-import "../chunk-LG57S2SC.js";
-import "../chunk-S5G3HO7N.js";
 import "../chunk-U64T4YZE.js";
 import "../chunk-2E224ZSN.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/http/pagination.ts

@@ -0,0 +1,233 @@
+/**
+ * Pagination envelope + ListQuery contract for generated entity list endpoints
+ * (pagination-by-default).
+ *
+ * Every generated `GET /<entities>` returns a {@link Page} envelope instead of
+ * a bare `T[]`. The request shape is {@link ListQuery} (page/cursor/pageSize +
+ * default sort) merged with arbitrary where-filters at the controller.
+ *
+ * Mirrors the in-repo precedent: the jobs subsystem's `JobRunPage`
+ * (`{ items, nextCursor }`) and its opaque keyset cursor codec
+ * (`runtime/subsystems/jobs/job-run-keyset-cursor.ts`). The entity envelope
+ * EXTENDS that minimal shape with `page/pageCount/total/pageSize` so a numbered
+ * UI (jump-to-page) works while `nextCursor` stays contract-stable for the
+ * later keyset upgrade.
+ *
+ * ENGINE NOTE (v1): the list use-case fetches by OFFSET (page-based). The
+ * `nextCursor` is computed from the last row and emitted from day one so the
+ * contract never changes, but cursor-REQUEST honoring (keyset seek) is a
+ * DEFERRED seam — see the TODO in the generated list use-case / the repository
+ * query branch. `ListQuery.cursor` is ACCEPTED (no validation error) even
+ * though v1 ignores it for fetching.
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Defaults + clamp
+// ============================================================================
+
+/** Default page size when `pageSize` is omitted. */
+export const DEFAULT_PAGE_SIZE = 50;
+/** Hard upper bound on page size to keep a single read bounded. */
+export const MAX_PAGE_SIZE = 200;
+/** Default page (1-based) when `page` is omitted. */
+export const DEFAULT_PAGE = 1;
+/** Default sort column. */
+export const DEFAULT_SORT_BY = 'created_at';
+/** Default sort direction. */
+export const DEFAULT_SORT_ORDER = 'desc' as const;
+
+/** Clamp a caller-supplied `pageSize` into `[1, MAX_PAGE_SIZE]`. */
+export function clampPageSize(pageSize: number | undefined): number {
+  if (typeof pageSize !== 'number' || !Number.isFinite(pageSize)) {
+    return DEFAULT_PAGE_SIZE;
+  }
+  const floored = Math.floor(pageSize);
+  if (floored < 1) return 1;
+  if (floored > MAX_PAGE_SIZE) return MAX_PAGE_SIZE;
+  return floored;
+}
+
+/** Clamp a caller-supplied `page` to a 1-based integer (floor 1). */
+export function clampPage(page: number | undefined): number {
+  if (typeof page !== 'number' || !Number.isFinite(page)) {
+    return DEFAULT_PAGE;
+  }
+  const floored = Math.floor(page);
+  return floored < 1 ? 1 : floored;
+}
+
+// ============================================================================
+// ListQuery schema (request)
+// ============================================================================
+
+/**
+ * Zod schema for the universal list query string. All keys optional —
+ * pagination works fully UNFILTERED (the default mode). `pageSize` is clamped
+ * (default 50, max 200) and `sort_order` defaults to `desc`. Arbitrary where
+ * filters are NOT modeled here (they're parsed/passed through at the controller
+ * via `.passthrough()`); this schema owns ONLY the pagination + sort knobs so
+ * the defaults + clamp land in one place.
+ *
+ * `cursor` is accepted but v1 ignores it for fetching (offset engine) — the
+ * keyset seek is the deferred seam. Passing a `nextCursor` back never errors.
+ */
+export const ListQuerySchema = z
+  .object({
+    page: z.coerce.number().int().optional(),
+    cursor: z.string().optional(),
+    pageSize: z.coerce.number().int().optional(),
+    sort_by: z.string().optional(),
+    sort_order: z.enum(['asc', 'desc']).optional(),
+  })
+  .passthrough();
+
+/** Parsed list query (pre-clamp). Use {@link resolveListQuery} to normalize. */
+export type ListQuery = z.infer<typeof ListQuerySchema>;
+
+/**
+ * Normalized pagination options resolved from a raw {@link ListQuery}: clamped
+ * `page`/`pageSize`, computed `offset`, and a defaulted sort. The generated
+ * list use-case feeds these straight into `service.list({ limit, offset, ... })`.
+ */
+export interface ResolvedListQuery {
+  page: number;
+  pageSize: number;
+  /** `(page - 1) * pageSize`. */
+  offset: number;
+  sortBy: string;
+  sortOrder: 'asc' | 'desc';
+  /** Opaque cursor as passed by the caller (v1: not honored — deferred seam). */
+  cursor?: string;
+}
+
+/**
+ * Resolve a raw list query into normalized, clamped pagination options.
+ * Defaults: page 1, pageSize 50 (max 200), sort `created_at desc`.
+ */
+export function resolveListQuery(query: ListQuery | undefined): ResolvedListQuery {
+  const page = clampPage(query?.page);
+  const pageSize = clampPageSize(query?.pageSize);
+  return {
+    page,
+    pageSize,
+    offset: (page - 1) * pageSize,
+    sortBy: query?.sort_by ?? DEFAULT_SORT_BY,
+    sortOrder: query?.sort_order ?? DEFAULT_SORT_ORDER,
+    cursor: query?.cursor,
+  };
+}
+
+// ============================================================================
+// Page envelope (response)
+// ============================================================================
+
+/**
+ * One page of a paginated list response. EXTENDS the jobs subsystem's minimal
+ * `{ items, nextCursor }` shape with the numbered-UI fields:
+ *
+ *   - `page`       — 1-based page number of THIS page.
+ *   - `pageCount`  — total number of pages (`ceil(total / pageSize)`, min 1).
+ *   - `total`      — total matching rows (reflects any where-filter).
+ *   - `pageSize`   — the (clamped) page size used.
+ *   - `nextCursor` — opaque keyset cursor of the LAST row, or `null` on the
+ *                    last page / empty result. Contract-stable from day one;
+ *                    v1 emits it but fetches by offset.
+ */
+export interface Page<T> {
+  items: T[];
+  page: number;
+  pageCount: number;
+  total: number;
+  pageSize: number;
+  nextCursor: string | null;
+}
+
+// ============================================================================
+// Opaque cursor codec (encodes (createdAt, id))
+// ============================================================================
+
+/** Keyset tuple a {@link Page.nextCursor} encodes. */
+export interface PageKeyset {
+  /** `created_at` of the last row on this page. */
+  createdAt: Date;
+  /** `id` (UUID) tie-break of the last row on this page. */
+  id: string;
+}
+
+/**
+ * Encode a `(createdAt, id)` keyset into an opaque, base64url cursor. The shape
+ * (a JSON tuple) is an implementation detail — never parse it outside this
+ * module. Mirrors `encodeKeysetCursor` in the jobs subsystem.
+ */
+export function encodeCursor(keyset: PageKeyset): string {
+  const tuple = [keyset.createdAt.toISOString(), keyset.id];
+  return Buffer.from(JSON.stringify(tuple), 'utf8').toString('base64url');
+}
+
+/**
+ * Decode an opaque cursor back into its `(createdAt, id)` keyset. Returns
+ * `null` for a malformed cursor so a caller can treat garbage as "start from
+ * the beginning" rather than throw on user-supplied data.
+ */
+export function decodeCursor(cursor: string): PageKeyset | null {
+  try {
+    const json = Buffer.from(cursor, 'base64url').toString('utf8');
+    const parsed = JSON.parse(json) as unknown;
+    if (!Array.isArray(parsed) || parsed.length !== 2) return null;
+    const [iso, id] = parsed;
+    if (typeof iso !== 'string' || typeof id !== 'string') return null;
+    const createdAt = new Date(iso);
+    if (Number.isNaN(createdAt.getTime())) return null;
+    return { createdAt, id };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute the `nextCursor` for a page of rows: the opaque cursor of the LAST
+ * row when more pages remain, else `null`. A row is expected to carry
+ * `createdAt: Date` and `id: string` (the default-sort keyset). Rows missing
+ * either field yield `null` (cursor not derivable — caller falls back to offset
+ * paging, which is the v1 engine anyway).
+ *
+ * @param rows      the items on this page (already fetched, in sort order)
+ * @param hasMore   whether more rows exist beyond this page
+ *                  (`offset + rows.length < total`)
+ */
+export function computeNextCursor(
+  rows: ReadonlyArray<unknown>,
+  hasMore: boolean,
+): string | null {
+  if (!hasMore || rows.length === 0) return null;
+  const last = rows[rows.length - 1] as { createdAt?: unknown; id?: unknown };
+  const createdAt = last?.createdAt;
+  const id = last?.id;
+  if (!(createdAt instanceof Date) || typeof id !== 'string') return null;
+  return encodeCursor({ createdAt, id });
+}
+
+/**
+ * Assemble a {@link Page} envelope from a fetched page of rows + the total
+ * matching count + the resolved query. Computes `pageCount` and `nextCursor`.
+ * The single place the envelope shape is constructed, so the generated list
+ * use-case stays a thin call.
+ */
+export function buildPage<T>(
+  items: T[],
+  total: number,
+  resolved: Pick<ResolvedListQuery, 'page' | 'pageSize' | 'offset'>,
+): Page<T> {
+  const pageCount = total === 0 ? 1 : Math.ceil(total / resolved.pageSize);
+  const hasMore = resolved.offset + items.length < total;
+  return {
+    items,
+    page: resolved.page,
+    pageCount,
+    total,
+    pageSize: resolved.pageSize,
+    nextCursor: computeNextCursor(items as ReadonlyArray<unknown>, hasMore),
+  };
+}

package/templates/entity/new/clean-lite-ps/controller.ejs.t

@@ -4,8 +4,12 @@ skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
 <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
-import { Controller, Get<% if (generateWrites) { %>, Post, Patch, Delete, Body, Headers<% } %>, NotFoundException, Param, ParseUUIDPipe } from '@nestjs/common';
-import { ApiBearerAuth, <% if (generateWrites) { %>ApiBody, <% } %>ApiOperation, ApiParam, ApiResponse } from '@nestjs/swagger';
+import { Controller, Get<% if (generateWrites) { %>, Post, Patch, Delete, Body, Headers<% } %>, NotFoundException, Param, ParseUUIDPipe, Query } from '@nestjs/common';
+import { ApiBearerAuth, <% if (generateWrites) { %>ApiBody, <% } %>ApiOperation, ApiParam, ApiQuery, ApiResponse } from '@nestjs/swagger';
+import { ZodValidationPipe } from '<%= typeof zodValidationPipeImport !== 'undefined' ? zodValidationPipeImport : '@shared/pipes/zod-validation.pipe' %>';
+import type { Page } from '<%= typeof paginationImport !== 'undefined' ? paginationImport : '@shared/http/pagination' %>';
+import { <%= classNames.listQuerySchema %> } from './dto/list-<%= entityNamePlural %>.query';
+import type { <%= classNames.listQueryDto %> } from './dto/list-<%= entityNamePlural %>.query';
 import { <%= classNames.findByIdUseCase %> } from './use-cases/find-<%= entityName %>-by-id.use-case';
 import { <%= classNames.listUseCase %> } from './use-cases/list-<%= entityNamePlural %>.use-case';
 <% if (eavEnabled) { -%>
@@ -13,7 +17,6 @@ import { <%= classNames.findByIdWithFieldsUseCase %> } from './use-cases/find-<%
 import { <%= classNames.listWithFieldsUseCase %> } from './use-cases/list-<%= entityNamePlural %>-with-fields.use-case';
 <% } -%>
 <% if (generateWrites) { -%>
-import { ZodValidationPipe } from '<%= typeof zodValidationPipeImport !== 'undefined' ? zodValidationPipeImport : '@shared/pipes/zod-validation.pipe' %>';
 import { <%= classNames.createUseCase %> } from './use-cases/create-<%= entityName %>.use-case';
 import { <%= classNames.updateUseCase %> } from './use-cases/update-<%= entityName %>.use-case';
 import { <%= classNames.deleteUseCase %> } from './use-cases/delete-<%= entityName %>.use-case';
@@ -47,14 +50,32 @@ export class <%= classNames.controller %> {
   ) {}
 
   @ApiOperation({ summary: 'List <%= entityNamePlural %>', operationId: 'list<%= classNames.entity %>s' })
+  @ApiQuery({ name: 'page', required: false, type: 'integer', description: '1-based page number (default 1).' })
+  @ApiQuery({ name: 'pageSize', required: false, type: 'integer', description: 'Page size (default 50, max 200).' })
+  @ApiQuery({ name: 'cursor', required: false, type: 'string', description: 'Opaque keyset cursor (accepted; v1 paginates by offset).' })
+  @ApiQuery({ name: 'sort_by', required: false, type: 'string', description: "Sort column (default 'created_at')." })
+  @ApiQuery({ name: 'sort_order', required: false, enum: ['asc', 'desc'], description: "Sort direction (default 'desc')." })
   @ApiResponse({
     status: 200,
-    schema: { type: 'array', items: { $ref: '#/components/schemas/<%= classNames.outputDto %>' } },
+    schema: {
+      type: 'object',
+      properties: {
+        items: { type: 'array', items: { $ref: '#/components/schemas/<%= classNames.outputDto %>' } },
+        page: { type: 'integer' },
+        pageCount: { type: 'integer' },
+        total: { type: 'integer' },
+        pageSize: { type: 'integer' },
+        nextCursor: { type: 'string', nullable: true },
+      },
+      required: ['items', 'page', 'pageCount', 'total', 'pageSize', 'nextCursor'],
+    },
   })
   @ApiResponse({ status: 401, schema: { $ref: '#/components/schemas/ErrorResponseDto' } })
   @Get()
-  async getAll(): Promise<<%= classNames.entity %>[]> {
-    return this.listUseCase.execute();
+  async getAll(
+    @Query(new ZodValidationPipe(<%= classNames.listQuerySchema %>)) query: <%= classNames.listQueryDto %>,
+  ): Promise<Page<<%= classNames.entity %>>> {
+    return this.listUseCase.execute(query);
   }
 <% if (eavEnabled) { %>
   @ApiOperation({

package/templates/entity/new/clean-lite-ps/dto/list-query.ejs.t

@@ -0,0 +1,22 @@
+---
+to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.listQueryDto : null %>"
+skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
+force: true
+---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
+import { z } from 'zod';
+import { ListQuerySchema } from '<%= typeof paginationImport !== 'undefined' ? paginationImport : '@shared/http/pagination' %>';
+
+/**
+ * List query DTO for `GET /<%= entityNamePlural %>` (pagination-by-default).
+ *
+ * Re-exports the shared `ListQuerySchema` (page/cursor/pageSize/sort_by/
+ * sort_order + `.passthrough()` for arbitrary where-filters). pageSize is
+ * clamped (default 50, max 200) and the default sort is `created_at desc, id
+ * desc` — both applied in the list use-case via `resolveListQuery`. `cursor` is
+ * accepted but v1 ignores it for fetching (offset engine); the keyset seek is a
+ * deferred seam.
+ */
+export const <%= classNames.listQuerySchema %> = ListQuerySchema;
+
+export type <%= classNames.listQueryDto %> = z.infer<typeof <%= classNames.listQuerySchema %>>;

package/templates/entity/new/clean-lite-ps/index.ejs.t

@@ -19,3 +19,4 @@ export type { <%= classNames.entity %> } from './<%= entityName %>.entity';
 export type { <%= classNames.createDto %> } from './dto/create-<%= entityName %>.dto';
 export type { <%= classNames.updateDto %> } from './dto/update-<%= entityName %>.dto';
 export type { <%= classNames.outputDto %> } from './dto/<%= entityName %>-output.dto';
+export type { <%= classNames.listQueryDto %> } from './dto/list-<%= entityNamePlural %>.query';

package/templates/entity/new/clean-lite-ps/prompt-extension.js

@@ -1296,6 +1296,9 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     createDto: `${moduleGroupDir}/${entityNamePlural}/dto/create-${entityName}.dto.ts`,
     updateDto: `${moduleGroupDir}/${entityNamePlural}/dto/update-${entityName}.dto.ts`,
     outputDto: `${moduleGroupDir}/${entityNamePlural}/dto/${entityName}-output.dto.ts`,
+    // Pagination-by-default: the universal list query DTO (page/cursor/pageSize
+    // + sort). Always emitted — the list endpoint is unconditional.
+    listQueryDto: `${moduleGroupDir}/${entityNamePlural}/dto/list-${entityNamePlural}.query.ts`,
     searchUseCase: searchQueryResolved
       ? `${moduleGroupDir}/${entityNamePlural}/use-cases/search-${entityNamePlural}.use-case.ts`
       : null,
@@ -1347,6 +1350,10 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     createSchema: `Create${entityNamePascal}Schema`,
     updateSchema: `Update${entityNamePascal}Schema`,
     outputSchema: `${entityNamePascal}OutputSchema`,
+    // Pagination-by-default: list query DTO + schema (re-export of the shared
+    // ListQuerySchema). Named per-entity so the controller import is unambiguous.
+    listQueryDto: `List${entityNamePluralPascal}QueryDto`,
+    listQuerySchema: `List${entityNamePluralPascal}QuerySchema`,
   };
 
   // Fields for create DTO: exclude id, behavior-managed fields, and FK fields
@@ -1413,6 +1420,12 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     baseLocals?.drizzleTokenImport ?? '@shared/constants/tokens';
   const drizzleTypeImport =
     baseLocals?.drizzleTypeImport ?? '@shared/types/drizzle';
+  // Pagination contract (pagination-by-default). Package mode → the runtime
+  // module `@pattern-stack/codegen/runtime/http/pagination`; vendored / default
+  // → the consumer-owned `@shared/http/pagination`. Threaded from prompt.js;
+  // unit tests that call buildCleanLitePsLocals directly get the @shared default.
+  const paginationImport =
+    baseLocals?.paginationImport ?? '@shared/http/pagination';
 
   return {
     // Clean-Lite-PS identity
@@ -1431,6 +1444,7 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     typedEventBusImport,
     drizzleTokenImport,
     drizzleTypeImport,
+    paginationImport,
 
     // Pattern — registry-driven (ADR-031)
     patternName,

package/templates/entity/new/clean-lite-ps/use-cases/list.ejs.t

@@ -4,14 +4,67 @@ force: true
 ---
 <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable } from '@nestjs/common';
+import { asc, desc, sql, type SQL } from 'drizzle-orm';
+import { buildPage, resolveListQuery, type ListQuery, type Page } from '<%= typeof paginationImport !== 'undefined' ? paginationImport : '@shared/http/pagination' %>';
 import { <%= classNames.service %> } from '../<%= entityName %>.service';
-import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';
+import { <%= entityNamePlural %>, type <%= classNames.entity %> } from '../<%= entityName %>.entity';
 
+/**
+ * Paginated list use-case for <%= entityNamePlural %> (pagination-by-default).
+ *
+ * Composes `service.list({ where, limit, offset, orderBy })` + `service.count(where)`
+ * into a `Page<<%- classNames.entity %>>` envelope. Defaults: page 1,
+ * pageSize 50 (max 200), sort `created_at desc, id desc`. `total`/`pageCount`
+ * reflect the (optionally filtered) set, so pagination composes with where
+ * filters orthogonally — it works fully unfiltered too.
+ *
+ * v1 ENGINE = OFFSET. `nextCursor` is computed from the last row and emitted
+ * (contract-stable), but cursor-REQUEST honoring (keyset seek) is DEFERRED:
+ * `resolved.cursor` is accepted and ignored here. The keyset swap belongs in
+ * the marked seam below — fetch by `WHERE (created_at, id) < decodeCursor(cursor)`
+ * instead of `offset` — and is otherwise invisible to the controller/UI.
+ */
 @Injectable()
 export class <%= classNames.listUseCase %> {
   constructor(private readonly service: <%= classNames.service %>) {}
 
-  async execute(): Promise<<%= classNames.entity %>[]> {
-    return this.service.list();
+  async execute(query?: ListQuery): Promise<Page<<%= classNames.entity %>>> {
+    const resolved = resolveListQuery(query);
+
+    // Default sort: `created_at desc, id desc` (id is the stable keyset
+    // tie-break). A caller `sort_by` that names a real column is honored in the
+    // requested direction with the id tie-break appended; an unknown column
+    // falls back to the default. Composed as a single SQL fragment because the
+    // base repository's `orderBy` takes one expression.
+    const dir = resolved.sortOrder === 'asc' ? asc : desc;
+    const col = (<%= entityNamePlural %> as unknown as Record<string, unknown>)[
+      resolved.sortBy.replace(/_([a-z])/g, (_m: string, c: string) => c.toUpperCase())
+    ];
+    const orderBy: SQL =
+      col === undefined
+        ? sql`${desc(<%= entityNamePlural %>.createdAt)}, ${desc(<%= entityNamePlural %>.id)}`
+        : sql`${dir(col as never)}, ${desc(<%= entityNamePlural %>.id)}`;
+
+    // Arbitrary where-filters are NOT modeled in v1 (the ListQuery owns only
+    // pagination + sort); `where` stays undefined so the list is unfiltered by
+    // default. A future filter seam ANDs predicates here and passes the same
+    // `where` to both `list` and `count` so `total`/`pageCount` stay accurate.
+    const where: SQL | undefined = undefined;
+
+    // KEYSET SEAM (deferred — v1 fetches by offset). When the keyset upgrade
+    // lands, branch here on `resolved.cursor`: decode it and fetch by
+    // `WHERE (created_at, id) < (cursorCreatedAt, cursorId)` LIMIT pageSize,
+    // dropping the offset. The envelope + nextCursor below are unchanged.
+    const [items, total] = await Promise.all([
+      this.service.list({
+        where,
+        limit: resolved.pageSize,
+        offset: resolved.offset,
+        orderBy,
+      }),
+      this.service.count(where),
+    ]);
+
+    return buildPage(items, total, resolved);
   }
 }

package/templates/entity/new/prompt.js

@@ -1380,6 +1380,22 @@ export default {
     const typedEventBusImport = subsystemsImport(runtimeMode, 'events');
     const drizzleTokenImport = runtimeImport(runtimeMode, 'constants/tokens');
     const drizzleTypeImport = runtimeImport(runtimeMode, 'types/drizzle');
+    // Pagination contract (pagination-by-default). ASYMMETRIC by mode:
+    //   - package  → `@pattern-stack/codegen/runtime/http/pagination` (Page<T>,
+    //     ListQuerySchema, resolveListQuery, buildPage, cursor codec) — the
+    //     package-published runtime; swe-brain consumes this green.
+    //   - vendored → `@shared/http/page` (vendored to `src/shared/http/page.ts`
+    //     by project init's VENDORED_RUNTIME_FILES). DISTINCT from the consumer's
+    //     OPTIONAL `@shared/http/pagination` search contract ({items,total,limit,
+    //     offset}) — vendoring the Page<T> envelope to `/pagination` would
+    //     clobber it, so the list envelope lives at `/page`.
+    // Unlike most @shared/http/* files (which the package never owns), THIS one
+    // IS package-published — the list endpoint is unconditional, so its contract
+    // must ship with codegen (package mode) and be vendored (vendored mode).
+    const paginationImport =
+      runtimeMode === 'vendored'
+        ? '@shared/http/page'
+        : runtimeImport(runtimeMode, 'http/pagination');
     // Integration subsystem barrel (ADR-033.1 inline-sync `integration-source`
     // module — emitted only for entities with an inline `detection:` block).
     const integrationSubsystemImport = subsystemsImport(runtimeMode, 'integration');
@@ -1602,6 +1618,7 @@ export default {
       typedEventBusImport,
       drizzleTokenImport,
       drizzleTypeImport,
+      paginationImport,
       integrationSubsystemImport,
       withAnalyticsImport,
       integrationUpsertConfigImport,