From 02c3bdf02838c7f0e38888e1e3d4f2e1ac2f3243 Mon Sep 17 00:00:00 2001
From: Philipinho <16838612+Philipinho@users.noreply.github.com>
Date: Sun, 19 Apr 2026 22:35:56 +0100
Subject: [PATCH] docs(base): add implementation plan for duckdb query cache

---
 .../plans/2026-04-19-duckdb-query-cache.md    | 1561 +++++++++++++++++
 1 file changed, 1561 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-04-19-duckdb-query-cache.md

diff --git a/docs/superpowers/plans/2026-04-19-duckdb-query-cache.md b/docs/superpowers/plans/2026-04-19-duckdb-query-cache.md
new file mode 100644
index 00000000..23673fcc
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-19-duckdb-query-cache.md
@@ -0,0 +1,1561 @@
+# DuckDB-Backed Query Cache for Bases Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make sort + filter + search on large bases (≥25K live rows) fast and index-backed by routing qualifying `POST /bases/rows` requests to an in-process DuckDB cache instead of the JSONB-extracting Postgres path. Small bases and all writes keep their current path.
+
+**Architecture:** A new NestJS module `BaseQueryCacheModule` owns a per-process `Map<baseId, LoadedCollection>` where each collection is a DuckDB in-memory database with one typed row table keyed by the base's user-defined properties plus the system columns (`id`, `position`, `created_at`, `updated_at`, `last_updated_by_id`, `deleted_at`, `search_text`). Typed btree indexes are built on every sortable property. Writes still commit to Postgres first; the existing `EventEmitter2` row/property events are mirrored onto a dedicated Redis pub/sub channel so each node patches its own copy of the affected collection. If a collection is absent or its `schema_version` is stale, the loader rebuilds it from Postgres via the existing `BaseRowRepo.streamByBaseId` generator. Phase-1 routing is single-node local; phase-2 multi-node routing is sketched but not implemented.
+
+**Tech Stack:** NestJS 11 + Fastify, Kysely + postgres.js, ioredis (via `@nestjs-labs/nestjs-ioredis`), BullMQ, existing `@nestjs/event-emitter` pattern, DuckDB via `@duckdb/node-api` (official high-level binding, depends on `@duckdb/node-bindings`). Jest + ts-jest for tests.
+
+**Scope (v1, this plan):**
+- Server-side only. Client behavior is unchanged — same `listRows` endpoint, same DTO, same cursor shape.
+- Feature flag `BASE_QUERY_CACHE_ENABLED` defaults to `false`. When off, zero behavior change.
+- Threshold: a collection becomes a candidate when its live row count is `>= BASE_QUERY_CACHE_MIN_ROWS` (default `25000`) AND it has at least one sort / filter / search in the incoming query (the fast list-by-position path stays on Postgres regardless).
+- Correctness invariant: for any query that the cache would answer, the returned page MUST equal what `BaseRowService.list` returns from Postgres (same row ids in same order, same cursor behavior). A diff test on a 10K seed base enforces this.
+- LRU eviction when `BASE_QUERY_CACHE_MAX_COLLECTIONS` (default `500`) is reached. Evict by least-recently-used access timestamp.
+- Warm-on-boot: a small Redis sorted set tracks recently-accessed baseIds. On `onApplicationBootstrap`, load the top N (default `50`, env `BASE_QUERY_CACHE_WARM_TOP_N`).
+- Any loader/patcher failure falls through to the existing Postgres path and is logged. A DuckDB error must never surface to the client.
+
+**Non-goals (v1, explicitly deferred):**
+- Multi-node consistent-hash routing (phase 2, sketched only).
+- Rollups, materialized groupings, or column-type narrowing beyond what the loader does directly.
+- Client "ship everything for small bases" tier-0 optimization (separate future plan).
+- Migrating the existing no-filter/no-sort list fast path (it's already index-backed in Postgres).
+- Any change to the write path, write validation, or event shape.
+
+---
+
+## Background
+
+### The current hot path and why it stalls
+
+On a 100K-row base with a property sort, the server currently runs (simplified):
+
+```sql
+SELECT id, cells, position, ..., COALESCE(base_cell_text(cells, '<propertyId>'::uuid), chr(1114111)) AS s0
+FROM base_rows
+WHERE base_id = $1 AND workspace_id = $2 AND deleted_at IS NULL
+  AND (<keyset cursor>)
+ORDER BY s0 ASC, position COLLATE "C" ASC, id ASC
+LIMIT 101;
+```
+
+`base_cell_text(cells, <uuid>)` is the function extractor in `apps/server/src/core/base/engine/extractors.ts`. The expression is opaque to any per-column index, so Postgres falls back to `Parallel Seq Scan` + `top-N heapsort`. Observed: ~112 ms warm, ~10 s cold, shared buffers ~400 MB touched per page. The sort cannot be pre-indexed without per-property expression indexes — infeasible multi-tenant (write amplification, storage blowup, DDL under load). See `apps/server/src/core/base/engine/sort.ts` for all sort-build sites.
+
+### Why DuckDB (decided, not re-litigated here)
+
+- Embedded library; no new daemon, no new container. Just an npm dep.
+- Real typed columns with btree indexes and a proper planner.
+- Native JSON ingest so we can bulk-load from Postgres JSONB without reshaping.
+- Cheap point updates (`INSERT OR REPLACE`, `UPDATE ... WHERE id = ?`) — fits per-cell write cadence.
+- Alternatives rejected: ClickHouse/chDB (poor point updates), shadow cells table in Postgres (write fanout pathological at bulk import), on-the-fly expression indexes (write amplification + DDL under load), external search stores (breaks self-host simplicity).
+
+### DuckDB state is derived, not replicated
+
+Postgres remains source of truth. Any node can die, any collection can be evicted, state regenerates on demand from the existing `BaseRowRepo.streamByBaseId` generator (already used by type-conversion, cell-gc, CSV export). This is why the rollout is safe: worst case, a bug in the cache path makes the system slow (falls back to Postgres); it cannot corrupt user data.
+
+---
+
+## Data flow at a glance
+
+### Read path — small base
+
+`BaseRowController.list` → `BaseRowService.list` → `BaseRowRepo.list` → Postgres. Unchanged.
+
+### Read path — large base with filter/sort/search
+
+`BaseRowController.list` → `BaseRowService.list` → `BaseQueryRouter.route(baseId, query)` →
+
+- If flag off OR row count below threshold OR query has no filter/sort/search → Postgres path (unchanged).
+- Else → `BaseQueryCacheService.list(baseId, query, pagination)`:
+  1. If collection isn't resident: call `CollectionLoader.load(baseId)`, which reads `bases.schema_version`, fetches all properties, streams all live rows from Postgres, creates the DuckDB database + typed row table + indexes, and inserts the rows. Record the access in the LRU and in the Redis warm-set.
+  2. If resident but `schema_version` mismatches the loaded version: reload.
+  3. Translate the engine's filter/sort/search spec into DuckDB SQL via `DuckDbQueryBuilder`. Apply the keyset cursor (same `(sort-field…, position, id)` ordering the Postgres engine uses).
+  4. Run the query, shape the result into the same `CursorPaginationResult<BaseRow>` shape the Postgres path returns.
+  5. Touch LRU access timestamp + Redis warm-set.
+
+### Write path
+
+Unchanged at the storage layer. After `BaseRowService` emits a `BaseRow*Event`, a new in-process listener `BaseQueryCacheWriteConsumer` publishes a compact change envelope on Redis channel `base-query-cache:changes:{baseId}`. On every node, `BaseQueryCacheSubscriber` receives the envelope and, if that collection is resident locally, applies the patch (`INSERT OR REPLACE`, `UPDATE`, soft-delete, or property-schema-change ⇒ invalidate collection). Originating node included — consistent behavior across publishers and subscribers.
+
+### Warm-up path
+
+On `onApplicationBootstrap`, `BaseQueryCacheService.warmUp()` reads `ZREVRANGE base-query-cache:recent 0 N-1` and loads each (non-blocking, firing the loader sequentially to avoid thundering-herd on Postgres). Warm-up is best-effort; any failure is logged, the boot sequence continues.
+
+### Eviction path
+
+Every `list` call updates an LRU timestamp on the collection's entry. When `Map.size > MAX_COLLECTIONS`, the least-recently-accessed collection is closed (`connection.closeSync()` + `db.closeSync()`) and removed. Closed collections on next access re-load.
+
+---
+
+## Column-type mapping
+
+Derived from `PropertyKind` in `apps/server/src/core/base/engine/kinds.ts` and the extractor semantics in `extractors.ts`.
+
+| `BasePropertyType` | `PropertyKind` | DuckDB column type | Index? | Value sourced from |
+|---|---|---|---|---|
+| `text`, `url`, `email` | `TEXT` | `VARCHAR` | btree | `cells->>propertyId` as text |
+| `number` | `NUMERIC` | `DOUBLE` | btree | JSON number → double |
+| `date` | `DATE` | `TIMESTAMPTZ` | btree | ISO string → `TIMESTAMPTZ` |
+| `checkbox` | `BOOL` | `BOOLEAN` | btree | JSON bool |
+| `select`, `status` | `SELECT` | `VARCHAR` (choice uuid as text) | btree | `cells->>propertyId` |
+| `multiSelect` | `MULTI` | `JSON` (raw) | none | JSON array of uuids — filter via `json_array_contains`, sort not supported |
+| `person` (single) | `PERSON` | `VARCHAR` | btree | single uuid string |
+| `person` (multi, `typeOptions.allowMultiple`) | `PERSON` | `JSON` | none | uuid array |
+| `file` | `FILE` | `JSON` | none | array of file descriptors; filter only (isEmpty/isNotEmpty/any) |
+| `createdAt` | system | `TIMESTAMPTZ NOT NULL` | btree | `base_rows.created_at` |
+| `lastEditedAt` | system | `TIMESTAMPTZ NOT NULL` | btree | `base_rows.updated_at` |
+| `lastEditedBy` | `SYS_USER` | `VARCHAR` | btree | `base_rows.last_updated_by_id` |
+
+Plus fixed system columns every collection has:
+- `id VARCHAR NOT NULL PRIMARY KEY` (uuid7 text; btree-indexed via PK)
+- `position VARCHAR NOT NULL` (btree; fractional-index string, compared with BINARY collation to mirror `COLLATE "C"` in Postgres)
+- `search_text VARCHAR` (btree + LIKE index where supported — initial impl uses plain `VARCHAR` + `LIKE '%…%'`; full-text is v1 out-of-scope and falls through to Postgres for `mode: 'fts'`)
+- `deleted_at TIMESTAMPTZ` (rows with `deleted_at != NULL` are filtered on every query; the loader only inserts live rows so this stays NULL in steady state — kept only so soft-delete invalidation via Redis can be handled as an `UPDATE` without a shape change)
+
+Column naming in DuckDB uses the property's `id` (uuid) verbatim, wrapped in double-quotes (`"019c69a3-dd47-7014-8b87-ec8f167577ee"`). This keeps rename-safe and removes any identifier collision with system columns.
+
+---
+
+## Redis channel naming
+
+- **Change stream (per-base):** `base-query-cache:changes:{baseId}` — published on every row/property/view mutation that affects a cached collection. Payload is a minimal JSON envelope (see task 7 for schema).
+- **Warm-up sorted set:** `base-query-cache:recent` — `ZADD` with timestamp score each time a collection is accessed; on boot, pull top N with `ZREVRANGE`. Capped weekly by a trim on writes (`ZREMRANGEBYRANK` to keep ≤ 10×MAX_COLLECTIONS entries).
+- **Ownership lease (phase 2 only):** `base-query-cache:owner:{baseId}` — reserved, NOT used by phase 1. Phase 1 runs all nodes as potential owners.
+
+Channel prefix `base-query-cache:` is chosen to be unambiguous and discoverable with `KEYS base-query-cache:*` during debugging, consistent with existing `presence:base:` / `typesense:` prefixes.
+
+---
+
+## File Structure
+
+**New files:**
+
+- `apps/server/src/core/base/query-cache/query-cache.module.ts` — NestJS module with all providers + `OnApplicationBootstrap` warm-up hook.
+- `apps/server/src/core/base/query-cache/query-cache.types.ts` — `LoadedCollection`, `ChangeEnvelope`, `ColumnSpec`, type aliases.
+- `apps/server/src/core/base/query-cache/query-cache.config.ts` — reads `BASE_QUERY_CACHE_*` env vars, exposes typed config.
+- `apps/server/src/core/base/query-cache/column-types.ts` — pure property-type → DuckDB column-spec mapping (mirror of table above). Unit-testable.
+- `apps/server/src/core/base/query-cache/duckdb-query-builder.ts` — pure translator from `FilterNode` / `SortSpec[]` / `SearchSpec` to DuckDB SQL fragments + parameter array. Unit-testable.
+- `apps/server/src/core/base/query-cache/collection-loader.ts` — loads one base from Postgres into a DuckDB database (schema creation, row streaming, index builds).
+- `apps/server/src/core/base/query-cache/base-query-cache.service.ts` — owns the `Map<baseId, LoadedCollection>`, LRU, `list()`, `invalidate()`, `applyChange()`, `warmUp()`.
+- `apps/server/src/core/base/query-cache/base-query-router.ts` — decision logic: should this query go to cache or Postgres?
+- `apps/server/src/core/base/query-cache/base-query-cache.write-consumer.ts` — `@OnEvent(...)` listener that publishes change envelopes to Redis.
+- `apps/server/src/core/base/query-cache/base-query-cache.subscriber.ts` — Redis subscriber that receives envelopes and calls `applyChange()`.
+- `apps/server/src/core/base/query-cache/column-types.spec.ts` — unit tests for the mapping.
+- `apps/server/src/core/base/query-cache/duckdb-query-builder.spec.ts` — unit tests for translation.
+- `apps/server/src/core/base/query-cache/base-query-router.spec.ts` — unit tests for the routing decision (pure, no DB).
+- `apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts` — integration tests against real Postgres + real DuckDB (Redis stubbed out with `EventEmitter2` loopback for determinism). Enabled only when `INTEGRATION_DB_URL` is set.
+
+**Modified files:**
+
+- `apps/server/src/core/base/base.module.ts` — import `BaseQueryCacheModule`.
+- `apps/server/src/core/base/services/base-row.service.ts` — delegate the decision in `list()` to `BaseQueryRouter`. Everything else unchanged.
+- `apps/server/src/database/repos/base/base-row.repo.ts` — add `countActiveRows(baseId, workspaceId)` used by the router to decide "large base?"; add no other changes.
+- `apps/server/src/integrations/environment/environment.service.ts` — getters for the four new env vars.
+- `apps/server/package.json` — add `@duckdb/node-api` dep.
+
+---
+
+## Task 1: Add DuckDB dependency + environment getters
+
+**Files:**
+- Modify: `apps/server/package.json`
+- Modify: `apps/server/src/integrations/environment/environment.service.ts`
+
+- [ ] **Step 1: Install `@duckdb/node-api`**
+
+From repo root:
+```bash
+pnpm --filter server add @duckdb/node-api@^1.5.0
+```
+
+Expected: `@duckdb/node-api` appears in `apps/server/package.json` under `dependencies` at `^1.5.x` (this is the official high-level DuckDB Node.js binding; it depends transitively on `@duckdb/node-bindings` which is the low-level C-API wrapper — a single top-level dep is correct).
+
+- [ ] **Step 2: Verify server still builds**
+
+```bash
+pnpm nx run server:build
+```
+
+Expected: build succeeds, no type errors.
+
+- [ ] **Step 3: Add four new env-var getters**
+
+Append to `apps/server/src/integrations/environment/environment.service.ts`, grouped with other feature-flag getters:
+
+```ts
+  getBaseQueryCacheEnabled(): boolean {
+    return this.configService.get<string>('BASE_QUERY_CACHE_ENABLED', 'false') === 'true';
+  }
+
+  getBaseQueryCacheMinRows(): number {
+    return parseInt(
+      this.configService.get<string>('BASE_QUERY_CACHE_MIN_ROWS', '25000'),
+      10,
+    );
+  }
+
+  getBaseQueryCacheMaxCollections(): number {
+    // Default is intentionally low (50) because a single-node self-host with
+    // ~100 MB per collection can pin ~5 GB RSS at the cap. SaaS/larger
+    // deployments can raise via env. See Appendix.
+    return parseInt(
+      this.configService.get<string>('BASE_QUERY_CACHE_MAX_COLLECTIONS', '50'),
+      10,
+    );
+  }
+
+  getBaseQueryCacheWarmTopN(): number {
+    return parseInt(
+      this.configService.get<string>('BASE_QUERY_CACHE_WARM_TOP_N', '50'),
+      10,
+    );
+  }
+```
+
+- [ ] **Step 4: Commit**
+
+This workspace uses a single root lockfile (`/Users/lite/WebstormProjects/docmost-base/pnpm-lock.yaml`, confirmed by `ls`). `pnpm --filter server add ...` still mutates only that root lockfile — no `apps/server/pnpm-lock.yaml` is created — so the staged path below is the repo-root lockfile.
+
+```bash
+git add apps/server/package.json pnpm-lock.yaml apps/server/src/integrations/environment/environment.service.ts
+git commit -m "chore(server): add duckdb dependency and query-cache env getters"
+```
+
+---
+
+## Task 2: Pure column-type mapping with unit tests
+
+**Files:**
+- Create: `apps/server/src/core/base/query-cache/column-types.ts`
+- Create: `apps/server/src/core/base/query-cache/column-types.spec.ts`
+- Create: `apps/server/src/core/base/query-cache/query-cache.types.ts`
+
+- [ ] **Step 1: Define shared types**
+
+Create `apps/server/src/core/base/query-cache/query-cache.types.ts`:
+
+```ts
+import type { DuckDBConnection, DuckDBInstance } from '@duckdb/node-api';
+import type { BaseProperty } from '@docmost/db/types/entity.types';
+
+export type DuckDbColumnType =
+  | 'VARCHAR'
+  | 'DOUBLE'
+  | 'BOOLEAN'
+  | 'TIMESTAMPTZ'
+  | 'JSON';
+
+export type ColumnSpec = {
+  // The uuid of the property (user-defined props) or a stable literal
+  // ('id', 'position', 'created_at', 'updated_at', 'last_updated_by_id',
+  //  'deleted_at', 'search_text') for system columns.
+  column: string;
+  ddlType: DuckDbColumnType;
+  indexable: boolean;
+  // For user-defined props we keep the source BaseProperty so callers can
+  // resolve the extraction rule from JSON.
+  property?: Pick<BaseProperty, 'id' | 'type' | 'typeOptions'>;
+};
+
+export type LoadedCollection = {
+  baseId: string;
+  schemaVersion: number;
+  columns: ColumnSpec[];
+  instance: DuckDBInstance;
+  connection: DuckDBConnection;
+  lastAccessedAt: number;
+};
+
+export type ChangeEnvelope =
+  | { kind: 'row-upsert'; baseId: string; row: Record<string, unknown> }
+  | { kind: 'row-delete'; baseId: string; rowId: string }
+  | { kind: 'rows-delete'; baseId: string; rowIds: string[] }
+  | { kind: 'row-reorder'; baseId: string; rowId: string; position: string }
+  | { kind: 'schema-invalidate'; baseId: string; schemaVersion: number };
+```
+
+- [ ] **Step 2: Write failing tests for the mapping**
+
+Create `apps/server/src/core/base/query-cache/column-types.spec.ts`:
+
+```ts
+import { BasePropertyType } from '../base.schemas';
+import { buildColumnSpecs, SYSTEM_COLUMNS } from './column-types';
+
+const p = (type: string, extra: Record<string, unknown> = {}) => ({
+  id: `prop-${type}`,
+  type,
+  typeOptions: extra,
+}) as any;
+
+describe('buildColumnSpecs', () => {
+  it('includes the fixed system columns first', () => {
+    const specs = buildColumnSpecs([]);
+    expect(specs.map((s) => s.column)).toEqual(SYSTEM_COLUMNS.map((s) => s.column));
+  });
+
+  it('maps text / url / email to VARCHAR indexable', () => {
+    for (const t of [BasePropertyType.TEXT, BasePropertyType.URL, BasePropertyType.EMAIL]) {
+      const specs = buildColumnSpecs([p(t)]);
+      const user = specs[specs.length - 1];
+      expect(user.ddlType).toBe('VARCHAR');
+      expect(user.indexable).toBe(true);
+    }
+  });
+
+  it('maps number to DOUBLE indexable', () => {
+    const specs = buildColumnSpecs([p(BasePropertyType.NUMBER)]);
+    const user = specs[specs.length - 1];
+    expect(user.ddlType).toBe('DOUBLE');
+    expect(user.indexable).toBe(true);
+  });
+
+  it('maps date to TIMESTAMPTZ indexable', () => {
+    const specs = buildColumnSpecs([p(BasePropertyType.DATE)]);
+    const user = specs[specs.length - 1];
+    expect(user.ddlType).toBe('TIMESTAMPTZ');
+    expect(user.indexable).toBe(true);
+  });
+
+  it('maps checkbox to BOOLEAN indexable', () => {
+    const specs = buildColumnSpecs([p(BasePropertyType.CHECKBOX)]);
+    const user = specs[specs.length - 1];
+    expect(user.ddlType).toBe('BOOLEAN');
+  });
+
+  it('maps select / status to VARCHAR indexable', () => {
+    for (const t of [BasePropertyType.SELECT, BasePropertyType.STATUS]) {
+      const specs = buildColumnSpecs([p(t)]);
+      const user = specs[specs.length - 1];
+      expect(user.ddlType).toBe('VARCHAR');
+      expect(user.indexable).toBe(true);
+    }
+  });
+
+  it('maps multiSelect / file / multi-person to JSON non-indexable', () => {
+    for (const t of [BasePropertyType.MULTI_SELECT, BasePropertyType.FILE]) {
+      const specs = buildColumnSpecs([p(t)]);
+      const user = specs[specs.length - 1];
+      expect(user.ddlType).toBe('JSON');
+      expect(user.indexable).toBe(false);
+    }
+    const specs = buildColumnSpecs([p(BasePropertyType.PERSON, { allowMultiple: true })]);
+    expect(specs[specs.length - 1].ddlType).toBe('JSON');
+  });
+
+  it('maps single-person to VARCHAR indexable when allowMultiple=false', () => {
+    const specs = buildColumnSpecs([p(BasePropertyType.PERSON, { allowMultiple: false })]);
+    const user = specs[specs.length - 1];
+    expect(user.ddlType).toBe('VARCHAR');
+    expect(user.indexable).toBe(true);
+  });
+
+  it('skips unknown property types', () => {
+    const specs = buildColumnSpecs([p('unknown-type-x')]);
+    expect(specs.length).toBe(SYSTEM_COLUMNS.length);
+  });
+});
+```
+
+Run:
+```bash
+pnpm --filter server exec jest src/core/base/query-cache/column-types.spec.ts
+```
+
+Expected: tests fail — `column-types.ts` doesn't exist yet.
+
+- [ ] **Step 3: Implement**
+
+Create `apps/server/src/core/base/query-cache/column-types.ts`:
+
+```ts
+import { BasePropertyType, BasePropertyTypeValue } from '../base.schemas';
+import { ColumnSpec } from './query-cache.types';
+import type { BaseProperty } from '@docmost/db/types/entity.types';
+
+export const SYSTEM_COLUMNS: ColumnSpec[] = [
+  { column: 'id', ddlType: 'VARCHAR', indexable: false },
+  { column: 'position', ddlType: 'VARCHAR', indexable: true },
+  { column: 'created_at', ddlType: 'TIMESTAMPTZ', indexable: true },
+  { column: 'updated_at', ddlType: 'TIMESTAMPTZ', indexable: true },
+  { column: 'last_updated_by_id', ddlType: 'VARCHAR', indexable: true },
+  { column: 'deleted_at', ddlType: 'TIMESTAMPTZ', indexable: false },
+  { column: 'search_text', ddlType: 'VARCHAR', indexable: false },
+];
+
+type PropertyLike = Pick<BaseProperty, 'id' | 'type' | 'typeOptions'>;
+
+export function buildColumnSpecs(properties: PropertyLike[]): ColumnSpec[] {
+  const out: ColumnSpec[] = [...SYSTEM_COLUMNS];
+  for (const prop of properties) {
+    const spec = buildUserColumn(prop);
+    if (spec) out.push(spec);
+  }
+  return out;
+}
+
+function buildUserColumn(prop: PropertyLike): ColumnSpec | null {
+  const t = prop.type as BasePropertyTypeValue;
+  switch (t) {
+    case BasePropertyType.TEXT:
+    case BasePropertyType.URL:
+    case BasePropertyType.EMAIL:
+      return { column: prop.id, ddlType: 'VARCHAR', indexable: true, property: prop };
+    case BasePropertyType.NUMBER:
+      return { column: prop.id, ddlType: 'DOUBLE', indexable: true, property: prop };
+    case BasePropertyType.DATE:
+      return { column: prop.id, ddlType: 'TIMESTAMPTZ', indexable: true, property: prop };
+    case BasePropertyType.CHECKBOX:
+      return { column: prop.id, ddlType: 'BOOLEAN', indexable: true, property: prop };
+    case BasePropertyType.SELECT:
+    case BasePropertyType.STATUS:
+      return { column: prop.id, ddlType: 'VARCHAR', indexable: true, property: prop };
+    case BasePropertyType.MULTI_SELECT:
+    case BasePropertyType.FILE:
+      return { column: prop.id, ddlType: 'JSON', indexable: false, property: prop };
+    case BasePropertyType.PERSON: {
+      const allowMultiple = !!(prop.typeOptions as any)?.allowMultiple;
+      return allowMultiple
+        ? { column: prop.id, ddlType: 'JSON', indexable: false, property: prop }
+        : { column: prop.id, ddlType: 'VARCHAR', indexable: true, property: prop };
+    }
+    // System types are modelled as system columns on base_rows — do not add
+    // a per-property column for them. They're already in SYSTEM_COLUMNS.
+    case BasePropertyType.CREATED_AT:
+    case BasePropertyType.LAST_EDITED_AT:
+    case BasePropertyType.LAST_EDITED_BY:
+      return null;
+    default:
+      return null;
+  }
+}
+```
+
+Run the same jest command. Expected: `Tests: 9 passed, 9 total` (one per `it(...)` block in the spec).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/
+git commit -m "feat(server): add property-type to DuckDB column-spec mapping"
+```
+
+---
+
+## Task 3: Scaffold the query-cache module (wired but dormant)
+
+**Files:**
+- Create: `apps/server/src/core/base/query-cache/query-cache.config.ts`
+- Create: `apps/server/src/core/base/query-cache/base-query-cache.service.ts` (stub)
+- Create: `apps/server/src/core/base/query-cache/base-query-router.ts` (stub returning "use postgres")
+- Create: `apps/server/src/core/base/query-cache/query-cache.module.ts`
+- Modify: `apps/server/src/core/base/base.module.ts`
+
+Purpose: get the module imported and providers resolvable end-to-end with the flag off. No DuckDB code path yet. This is the "ship it dark" commit.
+
+- [ ] **Step 1: Write the config provider**
+
+Create `apps/server/src/core/base/query-cache/query-cache.config.ts`:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { EnvironmentService } from '../../../integrations/environment/environment.service';
+
+export type QueryCacheConfig = {
+  enabled: boolean;
+  minRows: number;
+  maxCollections: number;
+  warmTopN: number;
+};
+
+@Injectable()
+export class QueryCacheConfigProvider {
+  readonly config: QueryCacheConfig;
+  constructor(env: EnvironmentService) {
+    this.config = {
+      enabled: env.getBaseQueryCacheEnabled(),
+      minRows: env.getBaseQueryCacheMinRows(),
+      maxCollections: env.getBaseQueryCacheMaxCollections(),
+      warmTopN: env.getBaseQueryCacheWarmTopN(),
+    };
+  }
+}
+```
+
+- [ ] **Step 2: Write the service stub**
+
+Create `apps/server/src/core/base/query-cache/base-query-cache.service.ts`:
+
+```ts
+import { Injectable, Logger } from '@nestjs/common';
+import { OnApplicationBootstrap, OnModuleDestroy } from '@nestjs/common';
+import { QueryCacheConfigProvider } from './query-cache.config';
+
+@Injectable()
+export class BaseQueryCacheService
+  implements OnApplicationBootstrap, OnModuleDestroy
+{
+  private readonly logger = new Logger(BaseQueryCacheService.name);
+
+  constructor(private readonly configProvider: QueryCacheConfigProvider) {}
+
+  async onApplicationBootstrap(): Promise<void> {
+    const { enabled } = this.configProvider.config;
+    this.logger.log(
+      `BaseQueryCacheService bootstrapped (enabled=${enabled}).`,
+    );
+    // Real warm-up is added in task 9.
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    // Real cleanup is added in task 5.
+  }
+}
+```
+
+- [ ] **Step 3: Write the router stub**
+
+Create `apps/server/src/core/base/query-cache/base-query-router.ts`:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { QueryCacheConfigProvider } from './query-cache.config';
+
+export type RouteDecision = 'postgres' | 'cache';
+
+@Injectable()
+export class BaseQueryRouter {
+  constructor(private readonly configProvider: QueryCacheConfigProvider) {}
+
+  // Stubbed: routes always to postgres in this commit so the existing
+  // behavior is preserved. Real decision logic is added in task 6.
+  decide(_args: unknown): RouteDecision {
+    if (!this.configProvider.config.enabled) return 'postgres';
+    return 'postgres';
+  }
+}
+```
+
+- [ ] **Step 4: Write the module**
+
+Create `apps/server/src/core/base/query-cache/query-cache.module.ts`:
+
+```ts
+import { Module } from '@nestjs/common';
+import { QueryCacheConfigProvider } from './query-cache.config';
+import { BaseQueryCacheService } from './base-query-cache.service';
+import { BaseQueryRouter } from './base-query-router';
+
+@Module({
+  providers: [QueryCacheConfigProvider, BaseQueryCacheService, BaseQueryRouter],
+  exports: [BaseQueryCacheService, BaseQueryRouter, QueryCacheConfigProvider],
+})
+export class BaseQueryCacheModule {}
+```
+
+- [ ] **Step 5: Import into BaseModule**
+
+Modify `apps/server/src/core/base/base.module.ts` — add the new module to `imports`:
+
+```ts
+import { BaseQueryCacheModule } from './query-cache/query-cache.module';
+// ...
+@Module({
+  imports: [
+    BullModule.registerQueue({ name: QueueName.BASE_QUEUE }),
+    BaseQueryCacheModule,
+  ],
+  // ... controllers, providers, exports unchanged
+})
+export class BaseModule {}
+```
+
+- [ ] **Step 6: Build and boot (no run)**
+
+```bash
+pnpm nx run server:build
+```
+
+Expected: build succeeds. The module compiles and providers resolve. (The `enabled=false` boot log is only observable when the server is actually run, which is out of scope for this build-only step.)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/ apps/server/src/core/base/base.module.ts
+git commit -m "feat(server): scaffold base query-cache module behind feature flag"
+```
+
+---
+
+## Task 4: Pure DuckDB query builder (translate engine specs to DuckDB SQL)
+
+**Files:**
+- Create: `apps/server/src/core/base/query-cache/duckdb-query-builder.ts`
+- Create: `apps/server/src/core/base/query-cache/duckdb-query-builder.spec.ts`
+
+This is the second pure, unit-testable component. No DuckDB runtime required; we just produce a `{ sql, params }` pair that the service will execute later.
+
+- [ ] **Step 1: Test contract**
+
+The builder takes:
+- A column set (`ColumnSpec[]` from `buildColumnSpecs`).
+- A `FilterNode | undefined`, `SortSpec[] | undefined`, `SearchSpec | undefined` (from `core/base/engine/schema.zod`).
+- A `{ limit, afterKeys? }` pagination block, where `afterKeys` is the decoded cursor from the existing `makeCursor` helper.
+
+It returns `{ sql: string; params: unknown[] }`. The SQL must:
+- Always project columns in the canonical `BaseRow` shape (id, base_id, cells-as-synthesized-json, position, creator_id, last_updated_by_id, workspace_id, created_at, updated_at, deleted_at, plus each sort-field alias `s0/s1/...` for cursor pagination).
+- Filter `deleted_at IS NULL`.
+- Apply search / filter / sort via the same precedence the Postgres engine uses.
+- Order by `(s0, s1, ..., position, id)` ascending by default, with sort direction honored per field.
+- For keyset pagination, emit the lexicographic OR-chain that `cursor-pagination.ts` builds.
+- `LIMIT ? + 1` so the caller can detect `hasNextPage`.
+
+Create `apps/server/src/core/base/query-cache/duckdb-query-builder.spec.ts` with the following test cases (write them first, then implement):
+
+```ts
+import { buildColumnSpecs } from './column-types';
+import { buildDuckDbListQuery } from './duckdb-query-builder';
+import { BasePropertyType } from '../base.schemas';
+
+const numericProp = {
+  id: '00000000-0000-0000-0000-000000000001',
+  type: BasePropertyType.NUMBER,
+  typeOptions: {},
+} as any;
+const textProp = {
+  id: '00000000-0000-0000-0000-000000000002',
+  type: BasePropertyType.TEXT,
+  typeOptions: {},
+} as any;
+
+const columns = buildColumnSpecs([numericProp, textProp]);
+
+describe('buildDuckDbListQuery', () => {
+  it('renders no-filter, no-sort, no-search as live-rows-paginated-by-position', () => {
+    const { sql, params } = buildDuckDbListQuery({
+      columns,
+      pagination: { limit: 100 },
+    });
+    expect(sql).toMatch(/FROM rows/);
+    expect(sql).toMatch(/deleted_at IS NULL/);
+    expect(sql).toMatch(/ORDER BY position ASC, id ASC/);
+    expect(sql).toMatch(/LIMIT 101/);
+    expect(params).toEqual([]);
+  });
+
+  it('renders numeric gt filter with parameterized value', () => {
+    const { sql, params } = buildDuckDbListQuery({
+      columns,
+      filter: {
+        op: 'and',
+        children: [{ propertyId: numericProp.id, op: 'gt', value: 42 }],
+      },
+      pagination: { limit: 100 },
+    });
+    expect(sql).toMatch(new RegExp(`"${numericProp.id}" > \\?`));
+    expect(params).toContain(42);
+  });
+
+  it('renders text contains with ILIKE and escaped wildcards', () => {
+    const { sql, params } = buildDuckDbListQuery({
+      columns,
+      filter: {
+        op: 'and',
+        children: [{ propertyId: textProp.id, op: 'contains', value: 'a_b%c' }],
+      },
+      pagination: { limit: 100 },
+    });
+    expect(sql).toMatch(/ILIKE \?/);
+    expect(params).toContain('%a\\_b\\%c%');
+  });
+
+  it('renders sort with sentinel wrapping and cursor keyset', () => {
+    const { sql } = buildDuckDbListQuery({
+      columns,
+      sorts: [{ propertyId: numericProp.id, direction: 'asc' }],
+      pagination: {
+        limit: 50,
+        afterKeys: { s0: 10, position: 'A0', id: '00000000-0000-0000-0000-0000000000aa' },
+      },
+    });
+    expect(sql).toMatch(/COALESCE\("[0-9a-f-]+", '?[Ii]nfinity'?::[A-Z]+\) AS s0/);
+    expect(sql).toMatch(/ORDER BY s0 ASC, position ASC, id ASC/);
+    // keyset OR-chain
+    expect(sql).toMatch(/s0 > \?/);
+  });
+
+  it('renders search in trgm mode as ILIKE on search_text', () => {
+    const { sql, params } = buildDuckDbListQuery({
+      columns,
+      search: { mode: 'trgm', query: 'hello' },
+      pagination: { limit: 10 },
+    });
+    expect(sql).toMatch(/search_text ILIKE \?/);
+    expect(params).toContain('%hello%');
+  });
+});
+```
+
+Run:
+```bash
+pnpm --filter server exec jest src/core/base/query-cache/duckdb-query-builder.spec.ts
+```
+
+Expected: fails (builder not implemented).
+
+- [ ] **Step 2: Implement the builder**
+
+Create `apps/server/src/core/base/query-cache/duckdb-query-builder.ts`. The implementation mirrors the Postgres engine in `apps/server/src/core/base/engine/predicate.ts`, `sort.ts`, `search.ts`, but emits DuckDB SQL with `?` positional params.
+
+Structure (no code dump — follow the Postgres engine's kind-dispatch exactly):
+
+- `buildDuckDbListQuery(opts)` entry point.
+- `buildFilter(node, columns, params) -> string` — recurse into FilterGroup, emit `(A AND B)` / `(A OR B)`, or call `buildCondition`.
+- `buildCondition(cond, col, params) -> string` — kind-dispatch on `col.property.type` via `propertyKind`, with the same operator tables as predicate.ts but using DuckDB syntax:
+  - text contains / startsWith / endsWith → `ILIKE ?` with the `escapeIlike` helper already in `engine/extractors.ts` (reuse it verbatim).
+  - numeric / date comparisons → `<op> ?`.
+  - bool `eq` / `neq` → `<op> ?`.
+  - select `any` → `"col" IN (?, ?, ?)`.
+  - multi/file `any` → `json_array_contains(<col>, ?)` OR chain.
+  - multi/file `all` → repeated `json_array_contains` AND chain.
+  - isEmpty / isNotEmpty → `IS NULL` / `IS NOT NULL` (+ the empty-string leg for text).
+- `buildSort(sorts, columns) -> {select: string[], orderBy: string}`:
+  - Mirror `sort.ts wrapWithSentinel` — wrap each sort expression in `COALESCE(<col>, <sentinel>)` aliased `sN`. Sentinels: numeric → `'Infinity'::DOUBLE` / `'-Infinity'::DOUBLE`; date → `'9999-12-31 23:59:59+00'::TIMESTAMPTZ` / `'0001-01-01 00:00:00+00'::TIMESTAMPTZ`; bool → `TRUE` / `FALSE`; text → `CHR(1114111)` / `''`.
+  - Append tail `position, id` — unchanged.
+- `buildSearch(search) -> string` — `trgm` → `search_text ILIKE ?` with the escape; `fts` → throw a typed sentinel exception `FtsNotSupportedInCache` so the router falls through to Postgres.
+- `buildKeyset(afterKeys, sortAliases, columns) -> string` — the same OR-chain `cursor-pagination.ts` produces, but in DuckDB SQL with `?` params. Important: the cursor key names (`s0, s1, ..., position, id`) match the engine.
+
+DuckDB parameter placeholder is `?` (positional) via `@duckdb/node-api` — no named params needed.
+
+Run jest again; all tests should pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/duckdb-query-builder.ts apps/server/src/core/base/query-cache/duckdb-query-builder.spec.ts
+git commit -m "feat(server): add DuckDB SQL builder for base list queries"
+```
+
+---
+
+## Task 5: Collection loader + in-memory cache + list() path (still off by default)
+
+**Files:**
+- Create: `apps/server/src/core/base/query-cache/collection-loader.ts`
+- Modify: `apps/server/src/core/base/query-cache/base-query-cache.service.ts`
+- Create: `apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts`
+
+This is the first real DuckDB code path. The integration spec needs a real Postgres (via the existing `DATABASE_URL`) and does not need Redis (we don't wire the subscriber here). Gate the spec on `process.env.INTEGRATION_DB_URL` being set so CI can run the whole suite and local devs can run just unit tests.
+
+- [ ] **Step 1: Add `BaseRowRepo.countActiveRows`**
+
+Modify `apps/server/src/database/repos/base/base-row.repo.ts` — append:
+
+```ts
+  async countActiveRows(
+    baseId: string,
+    opts: WorkspaceOpts,
+  ): Promise<number> {
+    const db = dbOrTx(this.db, opts.trx);
+    const row = await db
+      .selectFrom('baseRows')
+      .select((eb) => eb.fn.countAll<number>().as('count'))
+      .where('baseId', '=', baseId)
+      .where('workspaceId', '=', opts.workspaceId)
+      .where('deletedAt', 'is', null)
+      .executeTakeFirst();
+    return Number(row?.count ?? 0);
+  }
+```
+
+- [ ] **Step 2: Implement `CollectionLoader`**
+
+Create `apps/server/src/core/base/query-cache/collection-loader.ts`:
+
+- Inject `BasePropertyRepo`, `BaseRowRepo`, `BaseRepo`.
+- Expose one method: `async load(baseId: string, workspaceId: string): Promise<LoadedCollection>`.
+- Implementation outline:
+  1. Fetch `bases.schemaVersion` + all properties.
+  2. `const specs = buildColumnSpecs(properties);`
+  3. `const instance = await DuckDBInstance.create(':memory:');` then `const connection = await instance.connect();`.
+  4. `CREATE TABLE rows (<specs mapped to DDL>, PRIMARY KEY (id))`. Wrap each column name in `"..."`.
+  5. Bulk-insert rows using the **DuckDB Appender API** (`connection.createAppender('rows')`). The appender is DuckDB's idiomatic high-throughput insert path — it skips SQL parsing per row, accepts typed column values positionally in declared column order, and flushes on `closeSync()`. Prepared `INSERT` with re-binding works too but is 5–10× slower for wide tables; the appender is the right default for cold load of 100K rows.
+
+     Stream rows via `baseRowRepo.streamByBaseId(baseId, { workspaceId, chunkSize: 5000 })`. For each row:
+
+     ```ts
+     // appender column order matches specs[] order (CREATE TABLE declared order)
+     for (const spec of specs) {
+       const raw = readFromRow(row, spec); // system field or row.cells[prop.id]
+       if (raw == null) {
+         appender.appendNull();
+         continue;
+       }
+       switch (spec.ddlType) {
+         case 'VARCHAR':
+           appender.appendVarchar(String(raw));
+           break;
+         case 'DOUBLE': {
+           const n = Number(raw);
+           if (Number.isNaN(n)) { appender.appendNull(); break; }
+           appender.appendDouble(n);
+           break;
+         }
+         case 'BOOLEAN':
+           appender.appendBoolean(Boolean(raw));
+           break;
+         case 'TIMESTAMPTZ': {
+           // bindTimestampTZ / appendTimestampTZ take DuckDBTimestampTZValue.
+           // Cheapest path is to format as ISO8601 and append as VARCHAR into
+           // a TIMESTAMPTZ column — DuckDB casts implicitly. If profiling
+           // shows this is a bottleneck, switch to DuckDBTimestampTZValue via
+           // `new DuckDBTimestampTZValue(microsSinceEpoch)`.
+           const d = raw instanceof Date ? raw : new Date(String(raw));
+           if (Number.isNaN(d.getTime())) { appender.appendNull(); break; }
+           appender.appendVarchar(d.toISOString());
+           break;
+         }
+         case 'JSON':
+           // JSON columns in DuckDB accept a VARCHAR containing JSON text.
+           appender.appendVarchar(JSON.stringify(raw));
+           break;
+       }
+     }
+     appender.endRow();
+     ```
+
+     After the stream drains: `appender.flushSync(); appender.closeSync();`.
+
+     Notes:
+     - System columns: use the row's direct fields (`id`, `position`, `createdAt`, `updatedAt`, `lastUpdatedById`, `null` for `deleted_at`, `''` for `search_text` — we leave `search_text` unpopulated in v1; search stays on Postgres until task 4's `FtsNotSupportedInCache` sentinel drives us back, and even trgm search against an unpopulated column returns no rows — so route trgm search to Postgres as well in v1, see task 6).
+     - Malformed values log at debug level and become `null`.
+  6. For each indexable column: `CREATE INDEX idx_<safeCol> ON rows ("<col>");`. The PK already indexes `id`.
+  7. Return `{ baseId, schemaVersion, columns: specs, instance, connection, lastAccessedAt: Date.now() }`.
+
+Rationale for `:memory:` DuckDB per base: isolation, easy eviction (just close the instance), no disk file management. Memory overhead per collection is roughly `(columns * rows * avgBytes)` — a 100K-row base with 15 indexed columns is well under 100 MB.
+
+- [ ] **Step 3: Wire cache service**
+
+Replace the stub in `base-query-cache.service.ts` with a real Map + LRU + `list()` method:
+
+- Private `collections = new Map<string, LoadedCollection>()`.
+- Public `list(baseId: string, workspaceId: string, engineOpts: EngineListOpts): Promise<CursorPaginationResult<BaseRow>>` — calls `ensureLoaded`, builds SQL + positional params via `buildDuckDbListQuery`, then executes via the DuckDB Neo prepared-statement API (DuckDB Neo's `runAndReadAll` on a `DuckDBConnection` does NOT take a params array — parameterization goes through `connection.prepare(sql)` and per-type `bind*` calls). The shape is:
+
+  ```ts
+  const prepared = await collection.connection.prepare(sql);
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i];
+    const oneBased = i + 1;
+    if (p === null || p === undefined) {
+      prepared.bindNull(oneBased);
+    } else if (typeof p === 'string') {
+      prepared.bindVarchar(oneBased, p);
+    } else if (typeof p === 'number') {
+      prepared.bindDouble(oneBased, p);
+    } else if (typeof p === 'boolean') {
+      prepared.bindBoolean(oneBased, p);
+    } else if (p instanceof Date) {
+      // ISO string into a TIMESTAMPTZ column casts implicitly; see the
+      // loader's TIMESTAMPTZ handling above for the rationale.
+      prepared.bindVarchar(oneBased, p.toISOString());
+    } else {
+      // Fallback: serialize complex values as JSON text for JSON columns.
+      prepared.bindVarchar(oneBased, JSON.stringify(p));
+    }
+  }
+  const reader = await prepared.runAndReadAll();
+  const rows = reader.getRowObjects(); // use getRowObjects consistently so the
+                                       // row-shaping code can read by column name
+  ```
+
+  Then shape rows into `BaseRow[]`, handle `LIMIT+1` → `hasNextPage`, and encode cursors using the existing `makeCursor` helper so the output is byte-identical to Postgres.
+- Private `ensureLoaded(baseId, workspaceId)` — hit map, compare `schemaVersion` from a cheap `bases.findById` against the cached one; on miss or stale, call loader. Update `lastAccessedAt`. On cap exceeded, evict least-recently-used (single-pass scan of map is fine for ≤1000 entries; a `LinkedHashMap` is overkill).
+- Public `invalidate(baseId)` — close the connection + instance if resident; remove from map.
+- `onModuleDestroy` closes all collections.
+
+- [ ] **Step 4a: Extract a reusable seeding helper**
+
+The seed script currently runs as a standalone process (`apps/server/src/scripts/seed-base-rows.ts`). Before writing the integration spec, extract its base + property + row generation into a module-exportable helper that both the script and the test can call. This is a prerequisite — no such helper exists in the repo today (verified 2026-04-19 — the repo has no `*.integration.spec.ts` files and no test-seeding helpers under `apps/server/test/`).
+
+Create `apps/server/src/core/base/query-cache/testing/seed-base.ts`:
+
+```ts
+import type { Kysely } from 'kysely';
+import { v7 as uuid7 } from 'uuid';
+import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
+// Re-use the deterministic generators from seed-base-rows.ts by exporting
+// them from that file (move WORDS/COLORS/randomWords etc. above a new
+// `export` keyword, leaving the top-level script body intact).
+
+export type SeedBaseOptions = {
+  db: Kysely<any>;
+  workspaceId: string;
+  spaceId: string;
+  creatorUserId: string;
+  rows: number;
+  name?: string;
+};
+
+export type SeededBase = {
+  baseId: string;
+  propertyIds: {
+    text: string;
+    number: string;
+    status: string;
+    date: string;
+    // ... whichever props the script emits
+  };
+};
+
+export async function seedBase(opts: SeedBaseOptions): Promise<SeededBase> {
+  // Move the guts of the existing seed-base-rows.ts top-level body here.
+  // Keep the RNG deterministic (seed with opts.name + opts.rows) so tests
+  // are reproducible across machines.
+}
+
+export async function deleteSeededBase(
+  db: Kysely<any>,
+  baseId: string,
+): Promise<void> {
+  // DELETE rows first, then properties, views, then the base, matching
+  // the hard-delete order the existing cleanup script uses.
+}
+```
+
+Also update `apps/server/src/scripts/seed-base-rows.ts` to be a thin wrapper that calls `seedBase({ ... })` so `TOTAL_ROWS=10000 tsx src/scripts/seed-base-rows.ts` still works.
+
+- [ ] **Step 4b: Integration test — single-collection loader round-trip**
+
+Create `apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts`:
+
+```ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { ConfigModule } from '@nestjs/config';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { KyselyModule, InjectKysely } from '@docmost/db/kysely';
+import { BaseModule } from '../base.module';
+import { BaseQueryCacheService } from './base-query-cache.service';
+import { BaseRowService } from '../services/base-row.service';
+import { seedBase, deleteSeededBase } from './testing/seed-base';
+
+// Skip the suite when no integration DB is wired. Run locally with:
+//   INTEGRATION_DB_URL=$DATABASE_URL pnpm --filter server exec jest \
+//     src/core/base/query-cache/base-query-cache.integration.spec.ts
+const describeIfIntegration = process.env.INTEGRATION_DB_URL
+  ? describe
+  : describe.skip;
+
+describeIfIntegration('BaseQueryCacheService (integration)', () => {
+  let module: TestingModule;
+  let cache: BaseQueryCacheService;
+  let rowService: BaseRowService;
+  let db: any;
+  let workspaceId: string;
+  let spaceId: string;
+  let userId: string;
+  let seededBaseId: string;
+
+  beforeAll(async () => {
+    // Minimal real-module bootstrap. We import BaseModule (which now
+    // imports BaseQueryCacheModule via Task 3) plus the infra modules it
+    // depends on. We rely on process.env.INTEGRATION_DB_URL (aliased to
+    // DATABASE_URL) being set; without it the whole describe is skipped.
+    process.env.DATABASE_URL = process.env.INTEGRATION_DB_URL;
+    process.env.BASE_QUERY_CACHE_ENABLED = 'true';
+    process.env.BASE_QUERY_CACHE_MIN_ROWS = '100'; // so a 10K seed counts as "large"
+
+    module = await Test.createTestingModule({
+      imports: [
+        ConfigModule.forRoot({ isGlobal: true }),
+        EventEmitterModule.forRoot(),
+        KyselyModule.forRoot(), // uses DATABASE_URL
+        BaseModule,
+      ],
+    }).compile();
+
+    cache = module.get(BaseQueryCacheService);
+    rowService = module.get(BaseRowService);
+    db = module.get('KYSELY_DB'); // the token the repo uses for InjectKysely
+
+    // These three IDs must exist in the test database. Prefer to seed them
+    // in a one-time `globalSetup` script if the CI DB is empty; for a
+    // developer machine pointing at their dev DB, look them up from any
+    // existing workspace/space/user.
+    const anyWorkspace = await db
+      .selectFrom('workspaces')
+      .select(['id'])
+      .limit(1)
+      .executeTakeFirstOrThrow();
+    const anySpace = await db
+      .selectFrom('spaces')
+      .select(['id'])
+      .where('workspaceId', '=', anyWorkspace.id)
+      .limit(1)
+      .executeTakeFirstOrThrow();
+    const anyUser = await db
+      .selectFrom('users')
+      .select(['id'])
+      .where('workspaceId', '=', anyWorkspace.id)
+      .limit(1)
+      .executeTakeFirstOrThrow();
+    workspaceId = anyWorkspace.id;
+    spaceId = anySpace.id;
+    userId = anyUser.id;
+
+    const seeded = await seedBase({
+      db,
+      workspaceId,
+      spaceId,
+      creatorUserId: userId,
+      rows: 10_000,
+      name: 'query-cache-integration',
+    });
+    seededBaseId = seeded.baseId;
+  }, /* boot + seed timeout */ 120_000);
+
+  afterAll(async () => {
+    if (seededBaseId) await deleteSeededBase(db, seededBaseId);
+    await module?.close();
+  });
+
+  it('paginates a numeric sort identically to Postgres', async () => {
+    const numberPropId = /* look up from seeded.propertyIds.number */ '';
+    const args = {
+      sorts: [{ propertyId: numberPropId, direction: 'asc' as const }],
+      pagination: { limit: 500 },
+    };
+
+    const pgPages: string[] = [];
+    let cursor: string | undefined;
+    do {
+      const page = await rowService.list(
+        { baseId: seededBaseId, ...args },
+        { limit: args.pagination.limit, cursor },
+        workspaceId,
+      );
+      pgPages.push(...page.items.map((r) => r.id));
+      cursor = page.nextCursor;
+    } while (cursor);
+
+    const dkPages: string[] = [];
+    cursor = undefined;
+    do {
+      const page = await cache.list(seededBaseId, workspaceId, {
+        ...args,
+        pagination: { limit: args.pagination.limit, cursor },
+      });
+      dkPages.push(...page.items.map((r) => r.id));
+      cursor = page.nextCursor;
+    } while (cursor);
+
+    expect(dkPages).toEqual(pgPages);
+    expect(dkPages.length).toBe(10_000);
+  }, /* query timeout */ 60_000);
+});
+```
+
+Two things the executor MUST verify before running the test:
+1. The `KyselyModule` / `InjectKysely` token and the `'KYSELY_DB'` string literal above are placeholders — the real token is defined in `packages/db/src/kysely/` (or wherever `@docmost/db` lives); look it up and substitute.
+2. `rowService.list` signature above matches the real one after Task 6's edits; re-check argument shape at test-write time.
+
+Run with:
+
+```bash
+INTEGRATION_DB_URL=$DATABASE_URL pnpm --filter server exec jest src/core/base/query-cache/base-query-cache.integration.spec.ts
+```
+
+Expected: `Tests: 1 passed, 1 total`. Without `INTEGRATION_DB_URL` the whole describe is skipped, so local unit-test runs stay fast.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/collection-loader.ts \
+        apps/server/src/core/base/query-cache/base-query-cache.service.ts \
+        apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts \
+        apps/server/src/core/base/query-cache/testing/seed-base.ts \
+        apps/server/src/database/repos/base/base-row.repo.ts \
+        apps/server/src/scripts/seed-base-rows.ts
+git commit -m "feat(server): load bases into DuckDB and serve list queries from cache"
+```
+
+---
+
+## Task 6: Router — decide between Postgres and DuckDB paths; wire into BaseRowService
+
+**Files:**
+- Modify: `apps/server/src/core/base/query-cache/base-query-router.ts`
+- Create: `apps/server/src/core/base/query-cache/base-query-router.spec.ts`
+- Modify: `apps/server/src/core/base/services/base-row.service.ts`
+
+- [ ] **Step 1: Write failing unit tests for the router**
+
+Create `apps/server/src/core/base/query-cache/base-query-router.spec.ts`. Cases (all pure, no DB — use a fake config provider and a fake row-count function):
+
+```ts
+describe('BaseQueryRouter.decide', () => {
+  it('returns postgres when flag is off', () => { /* ... */ });
+  it('returns postgres when row count < minRows', () => { /* ... */ });
+  it('returns postgres when query has no filter/sort/search', () => { /* ... */ });
+  it('returns postgres when search.mode === "fts" even for large base', () => { /* ... */ });
+  it('returns cache when flag on + rows >= minRows + has filter', () => { /* ... */ });
+  it('returns cache when flag on + rows >= minRows + has sort', () => { /* ... */ });
+  it('returns cache when flag on + rows >= minRows + has trgm search', () => { /* ... */ });
+});
+```
+
+Run:
+```bash
+pnpm --filter server exec jest src/core/base/query-cache/base-query-router.spec.ts
+```
+
+Expected: fails (router still stubbed).
+
+- [ ] **Step 2: Implement the real router**
+
+Replace stub in `base-query-router.ts`:
+
+```ts
+@Injectable()
+export class BaseQueryRouter {
+  constructor(
+    private readonly configProvider: QueryCacheConfigProvider,
+    private readonly baseRowRepo: BaseRowRepo,
+  ) {}
+
+  async decide(args: {
+    baseId: string;
+    workspaceId: string;
+    filter?: FilterNode;
+    sorts?: SortSpec[];
+    search?: SearchSpec;
+  }): Promise<RouteDecision> {
+    const { enabled, minRows } = this.configProvider.config;
+    if (!enabled) return 'postgres';
+
+    const hasFilter = !!args.filter;
+    const hasSorts = !!args.sorts && args.sorts.length > 0;
+    const hasSearch = !!args.search;
+    if (!hasFilter && !hasSorts && !hasSearch) return 'postgres';
+
+    // v1: full-text search stays on Postgres. Trgm search also stays on
+    // Postgres until we populate search_text in DuckDB; re-evaluate after
+    // the loader gains search-column population.
+    if (args.search) return 'postgres';
+
+    const count = await this.baseRowRepo.countActiveRows(args.baseId, {
+      workspaceId: args.workspaceId,
+    });
+    if (count < minRows) return 'postgres';
+
+    return 'cache';
+  }
+}
+```
+
+Clarification: trgm search is gated off in v1 because the loader in task 5 does not populate `search_text`. If/when we decide to support trgm in the cache, the loader populates it and this branch relaxes. This is explicitly called out so the executor doesn't implement trgm + loader-population in the same commit and get cross-branch test failures.
+
+- [ ] **Step 3: Wire into `BaseRowService.list`**
+
+Modify `apps/server/src/core/base/services/base-row.service.ts`:
+
+```ts
+constructor(
+  @InjectKysely() private readonly db: KyselyDB,
+  private readonly baseRowRepo: BaseRowRepo,
+  private readonly basePropertyRepo: BasePropertyRepo,
+  private readonly baseViewRepo: BaseViewRepo,
+  private readonly eventEmitter: EventEmitter2,
+  private readonly queryRouter: BaseQueryRouter,
+  private readonly queryCache: BaseQueryCacheService,
+) {}
+
+async list(dto: ListRowsDto, pagination: PaginationOptions, workspaceId: string) {
+  const properties = await this.basePropertyRepo.findByBaseId(dto.baseId);
+  const schema: PropertySchema = new Map(properties.map((p) => [p.id, p]));
+
+  const filter = this.normaliseFilter(dto);
+  const search = this.normaliseSearch(dto.search);
+  const sorts = dto.sorts?.map((s) => ({
+    propertyId: s.propertyId,
+    direction: s.direction,
+  }));
+
+  const decision = await this.queryRouter.decide({
+    baseId: dto.baseId,
+    workspaceId,
+    filter,
+    sorts,
+    search,
+  });
+
+  if (decision === 'cache') {
+    try {
+      return await this.queryCache.list(dto.baseId, workspaceId, {
+        filter,
+        sorts,
+        search,
+        schema,
+        pagination,
+      });
+    } catch (err) {
+      // Clean fall-through: cache must never surface to the client.
+      // Log and let Postgres handle it.
+      this.logger.warn(
+        `Cache list failed for base ${dto.baseId}, falling back to Postgres`,
+        err as Error,
+      );
+    }
+  }
+
+  return this.baseRowRepo.list({
+    baseId: dto.baseId,
+    workspaceId,
+    filter,
+    sorts,
+    search,
+    schema,
+    pagination,
+  });
+}
+```
+
+Before the `try/catch` above, ensure `BaseRowService` declares `private readonly logger = new Logger(BaseRowService.name);` as a class field (import `Logger` from `@nestjs/common`). If it doesn't already have one, add it in this same edit — the `this.logger.warn(...)` call in the catch block requires it and we do NOT fall back to optional chaining (`this.logger?.warn?.`) because defensive optional chaining on a class-owned field hides wiring bugs (CLAUDE.md C-7). Also ensure `BaseQueryCacheModule` is imported by `BaseModule` so both providers resolve (done in task 3).
+
+- [ ] **Step 4: Verify router tests pass**
+
+```bash
+pnpm --filter server exec jest src/core/base/query-cache/base-query-router.spec.ts
+```
+
+Expected: `Tests: 7 passed, 7 total` (one per `it(...)` block in the spec above).
+
+- [ ] **Step 5: Verify build**
+
+```bash
+pnpm nx run server:build
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/base-query-router.ts \
+        apps/server/src/core/base/query-cache/base-query-router.spec.ts \
+        apps/server/src/core/base/services/base-row.service.ts
+git commit -m "feat(server): route large base list queries through the duckdb cache"
+```
+
+---
+
+## Task 7: Publish change envelopes to Redis, apply on subscribe
+
+**Files:**
+- Create: `apps/server/src/core/base/query-cache/base-query-cache.write-consumer.ts`
+- Create: `apps/server/src/core/base/query-cache/base-query-cache.subscriber.ts`
+- Modify: `apps/server/src/core/base/query-cache/base-query-cache.service.ts` (add `applyChange`)
+- Modify: `apps/server/src/core/base/query-cache/query-cache.module.ts`
+
+Pattern matches `BaseWsConsumers` (in-process `@OnEvent` listener) + `BasePresenceService` (ioredis via `RedisService`).
+
+- [ ] **Step 1: Write the Redis publisher**
+
+Create `apps/server/src/core/base/query-cache/base-query-cache.write-consumer.ts`:
+
+All `EventName` identifiers below are defined in `apps/server/src/common/events/event.contants.ts` (verified 2026-04-19). Exact line references: `BASE_ROW_CREATED` L23, `BASE_ROW_UPDATED` L24, `BASE_ROW_DELETED` L25, `BASE_ROWS_DELETED` L26, `BASE_ROW_REORDERED` L28, `BASE_PROPERTY_CREATED` L30, `BASE_PROPERTY_UPDATED` L31, `BASE_PROPERTY_DELETED` L32, `BASE_SCHEMA_BUMPED` L39. No new events need to be added for Task 7.
+
+- Imports `RedisService` from `@nestjs-labs/nestjs-ioredis`; resolves the client in constructor via `redisService.getOrThrow()` (same as `apps/server/src/core/base/realtime/base-presence.service.ts`).
+- `@OnEvent(EventName.BASE_ROW_CREATED)` → publish `{ kind: 'row-upsert', baseId, row }`.
+- `@OnEvent(EventName.BASE_ROW_UPDATED)` → fetch the updated row from Postgres (full row needed — `patch` alone doesn't carry all columns) and publish `{ kind: 'row-upsert', baseId, row }`. Optimization deferred: pass the row through the event payload (requires an additive tweak to `BaseRowUpdatedEvent` — out of scope for v1; instead, call `baseRowRepo.findById` here).
+- `@OnEvent(EventName.BASE_ROW_DELETED)` → `{ kind: 'row-delete', baseId, rowId }`.
+- `@OnEvent(EventName.BASE_ROWS_DELETED)` → `{ kind: 'rows-delete', baseId, rowIds }`.
+- `@OnEvent(EventName.BASE_ROW_REORDERED)` → `{ kind: 'row-reorder', baseId, rowId, position }`.
+- `@OnEvent(EventName.BASE_SCHEMA_BUMPED)` and `@OnEvent(EventName.BASE_PROPERTY_UPDATED)` / `BASE_PROPERTY_CREATED` / `BASE_PROPERTY_DELETED` → `{ kind: 'schema-invalidate', baseId, schemaVersion }`.
+
+Channel: `base-query-cache:changes:${baseId}`. Payload: `JSON.stringify(envelope)`.
+
+Guard with `if (!configProvider.config.enabled) return;` at the top of each handler so the flag-off path pays zero.
+
+- [ ] **Step 2: Write the Redis subscriber**
+
+Create `apps/server/src/core/base/query-cache/base-query-cache.subscriber.ts`:
+
+- Implement `OnApplicationBootstrap` + `OnModuleDestroy`.
+- On bootstrap (if flag enabled): create a dedicated ioredis client (NOT the shared one — ioredis pub/sub clients enter subscriber-only mode). `apps/server/src/core/base/realtime/base-presence.service.ts` shows the "shared client" pattern used for regular ops; for a dedicated subscriber use `new Redis(parseRedisUrl(env.getRedisUrl()))` mirroring `apps/server/src/ws/adapter/ws-redis.adapter.ts:16` (`parseRedisUrl` itself is exported from `apps/server/src/common/helpers/utils.ts:35`).
+- `PSUBSCRIBE base-query-cache:changes:*`.
+- On message: parse envelope, call `cacheService.applyChange(envelope)`. Catch-and-log any parse error.
+- On destroy: `quit()` the client.
+
+- [ ] **Step 3: Add `applyChange` to the cache service**
+
+Modify `base-query-cache.service.ts`:
+
+```ts
+async applyChange(env: ChangeEnvelope): Promise<void> {
+  const collection = this.collections.get(env.baseId);
+  if (!collection) return; // not resident on this node, ignore
+  try {
+    switch (env.kind) {
+      case 'schema-invalidate':
+        if (env.schemaVersion > collection.schemaVersion) {
+          await this.invalidate(env.baseId);
+        }
+        return;
+      case 'row-upsert':
+        await this.upsertRow(collection, env.row);
+        return;
+      case 'row-delete':
+        await this.deleteRow(collection, env.rowId);
+        return;
+      case 'rows-delete':
+        for (const id of env.rowIds) await this.deleteRow(collection, id);
+        return;
+      case 'row-reorder':
+        await this.updatePosition(collection, env.rowId, env.position);
+        return;
+    }
+  } catch (err) {
+    // On any patch failure, nuke the collection; next read reloads from
+    // Postgres. Much safer than running with a partially-patched cache.
+    this.logger.warn(`applyChange failed for ${env.baseId}; invalidating`, err);
+    await this.invalidate(env.baseId);
+  }
+}
+```
+
+`upsertRow` / `deleteRow` / `updatePosition` use the prepare/bind/run pattern documented in Task 5 Step 3 (DuckDB Neo API):
+- `upsertRow`: `INSERT OR REPLACE INTO rows VALUES (?, ?, …)` — prepare once per call, bind each column's value per `specs[i].ddlType` (same coercion table as the loader), then `await prepared.run()`.
+- `deleteRow`: only "live rows" are cached; soft-delete → remove. `DELETE FROM rows WHERE id = ?` with `prepared.bindVarchar(1, rowId); await prepared.run();`.
+- `updatePosition`: `UPDATE rows SET position = ? WHERE id = ?` with `prepared.bindVarchar(1, position); prepared.bindVarchar(2, rowId); await prepared.run();`.
+
+No params-array shorthand is used anywhere — that signature doesn't exist on `DuckDBConnection`.
+
+- [ ] **Step 4: Register in the module**
+
+Modify `query-cache.module.ts` providers list:
+
+```ts
+providers: [
+  QueryCacheConfigProvider,
+  BaseQueryCacheService,
+  BaseQueryRouter,
+  CollectionLoader,
+  BaseQueryCacheWriteConsumer,
+  BaseQueryCacheSubscriber,
+],
+```
+
+- [ ] **Step 5: Integration test — round-trip of a row-update event**
+
+Extend `base-query-cache.integration.spec.ts` with a test that:
+
+1. Seeds a base.
+2. Forces a load via `cache.list(...)`.
+3. Directly emits `EventName.BASE_ROW_UPDATED` through the `EventEmitter2` (bypasses Redis — acceptable since the write-consumer still fires, publishing onto Redis, and the subscriber on the same node receives the event).
+4. Reads via `cache.list(...)` again, asserts the updated row reflects the patch.
+
+For pure determinism, consider adding a secondary path where `applyChange` is called directly in the test without Redis, but the whole-loop test (Redis included) catches channel-name typos.
+
+Run:
+```bash
+INTEGRATION_DB_URL=$DATABASE_URL REDIS_URL=$REDIS_URL pnpm --filter server exec jest src/core/base/query-cache/base-query-cache.integration.spec.ts
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/base-query-cache.write-consumer.ts \
+        apps/server/src/core/base/query-cache/base-query-cache.subscriber.ts \
+        apps/server/src/core/base/query-cache/base-query-cache.service.ts \
+        apps/server/src/core/base/query-cache/query-cache.module.ts \
+        apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts
+git commit -m "feat(server): propagate row mutations to duckdb cache via redis pubsub"
+```
+
+---
+
+## Task 8: LRU eviction — tested with a tight cap
+
+**Files:**
+- Modify: `apps/server/src/core/base/query-cache/base-query-cache.service.ts`
+- Modify: `apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts`
+
+Eviction logic from task 5 already scaffolded. This task is about tightening and test coverage.
+
+- [ ] **Step 1: Ensure eviction path is deterministic**
+
+In `ensureLoaded`, after inserting a new collection into the map, if `this.collections.size > this.config.maxCollections`, find the entry with the smallest `lastAccessedAt` and call `invalidate(baseId)` on it. Single loop over map entries (N ≤ 500, trivially cheap).
+
+- [ ] **Step 2: Integration test with cap=2**
+
+Add a test case that:
+
+1. Temporarily creates a cache service instance with `maxCollections = 2` (use a test module override on `QueryCacheConfigProvider`).
+2. Seeds 3 bases.
+3. Loads all 3 in sequence. After each, verify `collections.size <= 2` and that the eldest-accessed base is NOT resident anymore.
+4. Loads the evicted base again — verify it reloads cleanly (schemaVersion comes back, basic query returns rows).
+
+Run:
+```bash
+INTEGRATION_DB_URL=$DATABASE_URL pnpm --filter server exec jest src/core/base/query-cache/base-query-cache.integration.spec.ts
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/base-query-cache.service.ts \
+        apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts
+git commit -m "feat(server): evict least-recently-used duckdb collections when cap exceeded"
+```
+
+---
+
+## Task 9: Warm-on-boot using recent-access Redis sorted set
+
+**Files:**
+- Modify: `apps/server/src/core/base/query-cache/base-query-cache.service.ts`
+
+- [ ] **Step 1: Record access**
+
+In `ensureLoaded`, after a successful load or a successful hit, call `this.recordAccess(baseId)` which issues:
+
+```
+ZADD base-query-cache:recent <now-ms> <baseId>
+ZREMRANGEBYRANK base-query-cache:recent 0 -(maxCollections * 10 + 1)
+```
+
+(Fire-and-forget; errors swallowed with debug log.)
+
+- [ ] **Step 2: `onApplicationBootstrap` warm-up**
+
+Replace the stub from task 3:
+
+```ts
+async onApplicationBootstrap(): Promise<void> {
+  const { enabled, warmTopN } = this.configProvider.config;
+  if (!enabled) return;
+  try {
+    const ids = await this.redis.zrevrange('base-query-cache:recent', 0, warmTopN - 1);
+    for (const baseId of ids) {
+      try {
+        const base = await this.baseRepo.findById(baseId);
+        if (!base) continue;
+        await this.ensureLoaded(baseId, base.workspaceId);
+      } catch (err) {
+        this.logger.debug(`warm-up skipped ${baseId}: ${(err as Error).message}`);
+      }
+    }
+    this.logger.log(`Warmed ${ids.length} collections on boot`);
+  } catch (err) {
+    this.logger.warn('Warm-up failed', err as Error);
+  }
+}
+```
+
+Warm-up is sequential intentionally: parallel warming of 50 bases each reading 25K rows from Postgres overwhelms the pool on boot.
+
+- [ ] **Step 3: Integration test**
+
+Add a test case:
+
+1. Access base A via `cache.list` (forces a ZADD).
+2. Destroy the service instance (simulating node restart).
+3. New instance with warm-up enabled. Assert base A is resident in the Map before any explicit `list` call.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/base-query-cache.service.ts \
+        apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts
+git commit -m "feat(server): warm duckdb collections on boot from redis recent-access set"
+```
+
+---
+
+## Task 10: End-to-end correctness — 100K seed base, cache vs postgres row-for-row
+
+**Files:**
+- Modify: `apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts`
+
+This is the correctness gate for merge.
+
+- [ ] **Step 1: Add the scale test, skipped by default**
+
+```ts
+const itIfScale = process.env.INTEGRATION_DB_URL && process.env.SCALE_TEST === 'true' ? it : it.skip;
+
+itIfScale('100K base: cache and postgres return identical rows for common queries', async () => {
+  // Reuses the `seedBase` helper extracted in Task 5 Step 4a
+  // (apps/server/src/core/base/query-cache/testing/seed-base.ts).
+  const { baseId } = await seedBase({
+    db,
+    workspaceId: WS,
+    spaceId: SPACE,
+    creatorUserId: USER,
+    rows: 100_000,
+    name: 'query-cache-scale',
+  });
+  const queries = [
+    { sorts: [{ propertyId: PROP_NUMBER, direction: 'asc' }] },
+    { sorts: [{ propertyId: PROP_TEXT, direction: 'desc' }] },
+    { filter: { op: 'and', children: [{ propertyId: PROP_STATUS, op: 'eq', value: DONE_ID }] } },
+    {
+      filter: { op: 'and', children: [{ propertyId: PROP_BUDGET, op: 'gt', value: 5000 }] },
+      sorts: [{ propertyId: PROP_DATE, direction: 'desc' }],
+    },
+  ];
+  for (const q of queries) {
+    const pgAll = await collectAllPages(() => baseRowService.list(q /*, postgres-forced */));
+    const dkAll = await collectAllPages(() => cacheService.list(baseId, WS, q));
+    expect(dkAll.map(r => r.id)).toEqual(pgAll.map(r => r.id));
+  }
+}, /* 5min timeout */ 300_000);
+```
+
+Run:
+```bash
+INTEGRATION_DB_URL=$DATABASE_URL SCALE_TEST=true pnpm --filter server exec jest src/core/base/query-cache/base-query-cache.integration.spec.ts
+```
+
+Expected: passes; typical run-time 2–5 min (seed + 4 full-traversal comparisons).
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add apps/server/src/core/base/query-cache/base-query-cache.integration.spec.ts
+git commit -m "test(server): assert duckdb cache matches postgres on a 100K-row base"
+```
+
+---
+
+## Rollout checklist
+
+Phased exposure. Each phase is its own PR-sized change — do NOT skip ahead.
+
+1. **Ship dark.** Merge all tasks above with `BASE_QUERY_CACHE_ENABLED=false` in production env. Verify in metrics that `POST /bases/rows` latency and error rate are unchanged (this is the "does the scaffold actually cost nothing when off" check). Wait one full week of production traffic.
+
+2. **Opt-in per workspace.** Before enabling globally, wire a check in `BaseQueryRouter.decide` that consults a small allow-list of workspace IDs (env var `BASE_QUERY_CACHE_WORKSPACE_IDS=ws1,ws2`). Set it to one internal workspace. Monitor:
+   - p50/p95/p99 latency of `/bases/rows` for the pilot workspace.
+   - Cache hit rate (log `decision === 'cache'` counter).
+   - Any log line from `BaseRowService.list`'s cache-path catch block (should be zero under normal operation).
+
+3. **Enable globally.** Drop the allow-list, set `BASE_QUERY_CACHE_ENABLED=true` everywhere. Watch `/bases/rows` p99, memory RSS (DuckDB pages stay in-process), and Redis pub/sub throughput. If RSS climbs beyond expectations, reduce `BASE_QUERY_CACHE_MAX_COLLECTIONS`.
+
+4. **Raise or lower threshold.** After a week of global-on, revisit `BASE_QUERY_CACHE_MIN_ROWS`. The 25K default is a conservative guess — the actual crossover where DuckDB starts winning on cold load may be lower. Adjust from metrics.
+
+5. **Phase 2 prep (not this plan).** Design consistent-hash routing using the `base-query-cache:owner:{baseId}` lease key so only one node holds a given collection. This is a separate plan.
+
+Rollback: set `BASE_QUERY_CACHE_ENABLED=false` and restart. No state cleanup required (DuckDB lives in-process; Redis keys auto-expire via the warm-set trim, but can be dropped with `DEL base-query-cache:recent` if desired).
+
+---
+
+## Appendix: open questions flagged for user confirmation
+
+These are guesses embedded in the plan that the executor should confirm before moving past the commits that encode them:
+
+- **`BASE_QUERY_CACHE_MIN_ROWS = 25000`** — threshold for "large." Derived from the observation that the Postgres path stays below 200ms up to ~30K rows. Confirm from real metrics after task 10.
+- **`BASE_QUERY_CACHE_MAX_COLLECTIONS = 50`** — memory cap, lowered from an earlier 500 draft to a self-host-safe default. At ~100 MB/collection this implies a ~5 GB RSS ceiling, which fits typical self-host boxes. Larger deployments should raise it explicitly via env. Confirm with user.
+- **`BASE_QUERY_CACHE_WARM_TOP_N = 50`** — boot-warm size. Chosen to balance boot time (50 × 10–15s = 8–12 min sequential) vs steady-state cache freshness. Confirm.
+- **Trgm search routes to Postgres** — v1 doesn't populate `search_text` in DuckDB. Cheap to add (loader just copies `row.searchText`), but untested against the trigger-maintained `f_unaccent` normalization in Postgres. Leave on Postgres in v1; revisit later.
+- **`@duckdb/node-api@^1.5.x`** — official high-level binding, latest as of writing is 1.5.2. Confirm npm registry pin at task 1 time.
+- **Redis channel prefix `base-query-cache:`** — consistent with existing `presence:base:` and `typesense:` naming. If there's a house convention for "infra cache" keys, align here before committing task 7.