@reventlessdev/reventless-postgres 3.0.0-alpha.5 → 3.0.0-alpha.6

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.6 (2026-07-06)
+
+### Features
+
+* **reventless-postgres,reventless-aws:** items (sub-id connection) resolver for Postgres reads (B3.2c) ([2477220](https://github.com/ReventlessDev/reventless-core/commit/247722062913f5d0bcb5895b152f05033d8297d8))
+
+
 # 3.0.0-alpha.5 (2026-07-06)
 
 ### Features

package/lib/bs/.compiler.log

@@ -1,2 +1,2 @@
-#Start(1783298008858)
-#Done(1783298010813)
+#Start(1783334804845)
+#Done(1783334806753)

package/lib/bs/compiler-info.json

@@ -4,5 +4,5 @@
   "bsc_hash": "75e3a59c95cc953608fd3dd6ea6ed68141bba4414a20a52f114261b8a48385fa",
   "rescript_config_hash": "48ea15db3d741cf15a2ff49dd0b47d86badf2b548ecb3859a896faf1e3a82a15",
   "runtime_path": "/home/runner/work/reventless-core/reventless-core/node_modules/@rescript/runtime",
-  "generated_at": "1783298010821"
+  "generated_at": "1783334806766"
 }

package/lib/bs/src/QueryEnginePostgres.res

@@ -297,6 +297,90 @@ module Make = (P: {let pool: PgDriver.pool}) => {
     }
   }
 
+  // Sub-id connection push-down: the `{single}Items(id, filter, first/after/
+  // last/before)` query. Keyset over `sub_key` WITHIN one partition — a page
+  // reads only what it returns. Reproduces QueryDbResolvers_GraphQL's items
+  // resolver (SortKey_Filter + forward/backward keyset), entirely in SQL since
+  // sub_key IS the sort key. Cursor = base64 of the sub_key value; comparisons
+  // use COLLATE "C" (byte order) to match JS string `<`. Unlike the main list
+  // there is no declined-shape fallback — every items shape maps to SQL.
+  let itemsPage = async (
+    ~readModelName,
+    ~subIdField as _: string,
+    ~id: string,
+    ~argsDict: dict<JSON.t>,
+  ): JSON.t => {
+    let table = QueryDbStorage_Postgres.tableName(readModelName)
+    let filterDict =
+      argsDict->Dict.get("filter")->Option.flatMap(JSON.Decode.object)->Option.getOr(Dict.make())
+    let fstr = k => filterDict->Dict.get(k)->Option.flatMap(JSON.Decode.string)
+    let orderDesc = fstr("order")->Option.mapOr(false, o => o == "DESC")
+    let last = argsDict->Dict.get("last")->Option.flatMap(JSON.Decode.float)->Option.map(Float.toInt)
+    let first = argsDict->Dict.get("first")->Option.flatMap(JSON.Decode.float)->Option.map(Float.toInt)
+    let after = argsDict->Dict.get("after")->Option.flatMap(JSON.Decode.string)
+    let before = argsDict->Dict.get("before")->Option.flatMap(JSON.Decode.string)
+    let isBackward = last->Option.isSome
+
+    let sk = `sub_key COLLATE "C"`
+    let b = {params: []}
+    let where = [`partition_key = ${b->param(JSON.Encode.string(id))}`, notExpired]
+    fstr("prefix")->Option.forEach(p =>
+      where->Array.push(`starts_with(sub_key, ${b->param(JSON.Encode.string(p))})`)
+    )
+    fstr("from")->Option.forEach(f => where->Array.push(`${sk} >= ${b->param(JSON.Encode.string(f))}`))
+    fstr("to")->Option.forEach(t => where->Array.push(`${sk} <= ${b->param(JSON.Encode.string(t))}`))
+    fstr("eq")->Option.forEach(e => where->Array.push(`${sk} = ${b->param(JSON.Encode.string(e))}`))
+    // Keyset: forward excludes ≤ after; backward excludes ≥ before.
+    switch (isBackward, after, before) {
+    | (false, Some(c), _) =>
+      where->Array.push(`${sk} > ${b->param(JSON.Encode.string(ReventlessCore.QueryDbListQuery.decodeCursor(c)))}`)
+    | (true, _, Some(c)) =>
+      where->Array.push(`${sk} < ${b->param(JSON.Encode.string(ReventlessCore.QueryDbListQuery.decodeCursor(c)))}`)
+    | _ => ()
+    }
+    // Page-fetch direction is the LOGICAL order forward, and its OPPOSITE
+    // backward (take the N nearest `before`, then reverse to logical) — mirrors
+    // the resolver's `reverse = isBackward ? !orderDesc : orderDesc`.
+    let fetchDesc = isBackward ? !orderDesc : orderDesc
+    let pageSize = (isBackward ? last : first)->Option.getOr(ReventlessCore.QueryDbListQuery.defaultListPageSize)
+    let sql = `SELECT partition_key, sub_key, item FROM ${table} WHERE ${where->Array.join(
+        " AND ",
+      )} ORDER BY ${sk} ${fetchDesc ? "DESC" : "ASC"} LIMIT ${b->param(JSON.Encode.int(pageSize + 1))}`
+    let rows = await P.pool->PgDriver.query(sql, b.params)
+    let hasMore = rows->Array.length > pageSize
+    let taken = rows->Array.slice(~start=0, ~end=pageSize)
+    // Backward fetched in reverse-logical order → flip back to logical.
+    let logical = isBackward ? taken->Array.toReversed : taken
+    let pageItems = logical->Array.map(decodeRow(~withId=false, ...))
+    // Cursor = the row's sub_key (== the item's subIdField value).
+    let subKeyOf = (row: dict<JSON.t>) =>
+      switch row->Dict.get("sub_key") {
+      | Some(JSON.String(s)) => s
+      | _ => ""
+      }
+    let cursors = logical->Array.map(subKeyOf)
+    let edges =
+      pageItems->Array.mapWithIndex((item, i) =>
+        Obj.magic({
+          "node": item,
+          "cursor": ReventlessCore.QueryDbListQuery.encodeCursor(cursors->Array.getUnsafe(i)),
+        })
+      )
+    let startCursor =
+      cursors->Array.get(0)->Option.map(ReventlessCore.QueryDbListQuery.encodeCursor)
+    let endCursor =
+      cursors->Array.get(cursors->Array.length - 1)->Option.map(ReventlessCore.QueryDbListQuery.encodeCursor)
+    Obj.magic({
+      "edges": edges,
+      "pageInfo": {
+        "hasNextPage": !isBackward && hasMore,
+        "hasPreviousPage": isBackward && hasMore,
+        "startCursor": startCursor->Nullable.fromOption,
+        "endCursor": endCursor->Nullable.fromOption,
+      },
+    })
+  }
+
   let make: QueryDb_Adapter.queryEngineMaker = _allQueryDbs =>
     Pulumi.Output.make({QueryEngine.scan, query})
 }

package/lib/bs/src/QueryEnginePostgres.res.mjs

@@ -3,6 +3,7 @@
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Pulumi from "@pulumi/pulumi";
+import * as Stdlib_Nullable from "@rescript/runtime/lib/es6/Stdlib_Nullable.js";
 import * as PgDriver$ReventlessPostgres from "./PgDriver.res.mjs";
 import * as QueryDbListQuery$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/QueryDbListQuery.res.mjs";
 import * as QueryDbStorage_Postgres$ReventlessPostgres from "./QueryDbStorage_Postgres.res.mjs";
@@ -231,6 +232,78 @@ function Make(P) {
     let cursorValueOf = item => Stdlib_Option.getOr(QueryDbListQuery$ReventlessCore.getFieldString(item, cursorField), QueryDbListQuery$ReventlessCore.getId(item));
     return QueryDbListQuery$ReventlessCore.buildConnection(pageItems, hasMore, false, cursorValueOf);
   };
+  let itemsPage = async (readModelName, param$1, id, argsDict) => {
+    let table = QueryDbStorage_Postgres$ReventlessPostgres.tableName(readModelName);
+    let filterDict = Stdlib_Option.getOr(Stdlib_Option.flatMap(argsDict["filter"], Stdlib_JSON.Decode.object), {});
+    let fstr = k => Stdlib_Option.flatMap(filterDict[k], Stdlib_JSON.Decode.string);
+    let orderDesc = Stdlib_Option.mapOr(fstr("order"), false, o => o === "DESC");
+    let last = Stdlib_Option.map(Stdlib_Option.flatMap(argsDict["last"], Stdlib_JSON.Decode.float), prim => prim | 0);
+    let first = Stdlib_Option.map(Stdlib_Option.flatMap(argsDict["first"], Stdlib_JSON.Decode.float), prim => prim | 0);
+    let after = Stdlib_Option.flatMap(argsDict["after"], Stdlib_JSON.Decode.string);
+    let before = Stdlib_Option.flatMap(argsDict["before"], Stdlib_JSON.Decode.string);
+    let isBackward = Stdlib_Option.isSome(last);
+    let sk = `sub_key COLLATE "C"`;
+    let b = {
+      params: []
+    };
+    let where = [
+      `partition_key = ` + param(b, id),
+      QueryDbStorage_Postgres$ReventlessPostgres.notExpiredClause
+    ];
+    Stdlib_Option.forEach(fstr("prefix"), p => {
+      where.push(`starts_with(sub_key, ` + param(b, p) + `)`);
+    });
+    Stdlib_Option.forEach(fstr("from"), f => {
+      where.push(sk + ` >= ` + param(b, f));
+    });
+    Stdlib_Option.forEach(fstr("to"), t => {
+      where.push(sk + ` <= ` + param(b, t));
+    });
+    Stdlib_Option.forEach(fstr("eq"), e => {
+      where.push(sk + ` = ` + param(b, e));
+    });
+    if (isBackward) {
+      if (before !== undefined) {
+        where.push(sk + ` < ` + param(b, QueryDbListQuery$ReventlessCore.decodeCursor(before)));
+      }
+    } else if (after !== undefined) {
+      where.push(sk + ` > ` + param(b, QueryDbListQuery$ReventlessCore.decodeCursor(after)));
+    }
+    let fetchDesc = isBackward ? !orderDesc : orderDesc;
+    let pageSize = Stdlib_Option.getOr(isBackward ? last : first, QueryDbListQuery$ReventlessCore.defaultListPageSize);
+    let sql = `SELECT partition_key, sub_key, item FROM ` + table + ` WHERE ` + where.join(" AND ") + ` ORDER BY ` + sk + ` ` + (
+      fetchDesc ? "DESC" : "ASC"
+    ) + ` LIMIT ` + param(b, pageSize + 1 | 0);
+    let rows = await PgDriver$ReventlessPostgres.query(P.pool, sql, b.params);
+    let hasMore = rows.length > pageSize;
+    let taken = rows.slice(0, pageSize);
+    let logical = isBackward ? taken.toReversed() : taken;
+    let pageItems = logical.map(extra => decodeRow(false, extra));
+    let subKeyOf = row => {
+      let match = row["sub_key"];
+      if (typeof match === "string") {
+        return match;
+      } else {
+        return "";
+      }
+    };
+    let cursors = logical.map(subKeyOf);
+    let edges = pageItems.map((item, i) => ({
+      node: item,
+      cursor: QueryDbListQuery$ReventlessCore.encodeCursor(cursors[i])
+    }));
+    let startCursor = Stdlib_Option.map(cursors[0], QueryDbListQuery$ReventlessCore.encodeCursor);
+    let endCursor = Stdlib_Option.map(cursors[cursors.length - 1 | 0], QueryDbListQuery$ReventlessCore.encodeCursor);
+    return {
+      edges: edges,
+      pageInfo: {
+        hasNextPage: !isBackward && hasMore,
+        hasPreviousPage: isBackward && hasMore,
+        startCursor: Stdlib_Nullable.fromOption(startCursor),
+        endCursor: Stdlib_Nullable.fromOption(endCursor)
+      }
+    };
+  };
   let make = _allQueryDbs => Pulumi.output({
     scan: scan,
     query: query
@@ -243,6 +316,7 @@ function Make(P) {
     idExprC: idExprC,
     jsonTextC: jsonTextC,
     listPage: listPage,
+    itemsPage: itemsPage,
     make: make
   };
 }

package/lib/bs/tests/QueryEnginePostgresListPageTest.res

@@ -233,4 +233,80 @@ switch processEnv->Dict.get("PG_URL") {
       expect(items->Array.length)->toBe(0)
     })
   })
+
+  // ── itemsPage (sub-id connection) ─────────────────────────────────────────
+  // A sub-id read model: partition "order-1" holds 5 lines keyed by `seq`.
+  let itemsName = "itemsparity"
+  let mkLine = seq => {
+    let o = Dict.make()
+    o->Dict.set("id", JSON.Encode.string("order-1"))
+    o->Dict.set("seq", JSON.Encode.string(seq))
+    JSON.Encode.object(o)
+  }
+  let seqs = ["a", "b", "c", "d", "e"]
+  beforeAllAsync(async () => {
+    let ops = QueryDbStorage_Postgres.makeOperations(
+      ~pool,
+      ~name=itemsName,
+      ~indexes=[],
+      ~subIdField=Some("seq"),
+    )
+    for i in 0 to seqs->Array.length - 1 {
+      let _ = await ops.save("order-1", mkLine(seqs->Array.getUnsafe(i)), QueryDb.Any, None)
+    }
+  })
+
+  // Extract node `seq` values in edge order.
+  let itemSeqs = (conn: JSON.t) =>
+    conn
+    ->field("edges")
+    ->Option.flatMap(JSON.Decode.array)
+    ->Option.getOr([])
+    ->Array.filterMap(e => e->field("node")->Option.flatMap(n => n->str("seq")))
+
+  let pageInfoBool = (conn, key) =>
+    conn->field("pageInfo")->Option.getOr(JSON.Encode.null)->field(key)->Option.flatMap(JSON.Decode.bool)->Option.getOr(false)
+
+  let itemsPage = args =>
+    Eng.itemsPage(~readModelName=itemsName, ~subIdField="seq", ~id="order-1", ~argsDict=argsOf(args))
+
+  describe("QueryEnginePostgres itemsPage (sub-id keyset)", () => {
+    testPromise("bare → all lines ASC, no next page", async () => {
+      let r = await itemsPage([])
+      expect(r->itemSeqs)->toEqual(["a", "b", "c", "d", "e"])
+      expect(pageInfoBool(r, "hasNextPage"))->toBe(false)
+    })
+    testPromise("first:2 → [a,b], hasNextPage", async () => {
+      let r = await itemsPage([("first", JSON.Encode.int(2))])
+      expect(r->itemSeqs)->toEqual(["a", "b"])
+      expect(pageInfoBool(r, "hasNextPage"))->toBe(true)
+    })
+    testPromise("first:2 after b → [c,d]", async () => {
+      let r = await itemsPage([("first", JSON.Encode.int(2)), ("after", JSON.Encode.string(cur("b")))])
+      expect(r->itemSeqs)->toEqual(["c", "d"])
+    })
+    testPromise("order DESC → [e..a]", async () => {
+      let r = await itemsPage([("filter", filterOf([("order", JSON.Encode.string("DESC"))]))])
+      expect(r->itemSeqs)->toEqual(["e", "d", "c", "b", "a"])
+    })
+    testPromise("filter eq c → [c]", async () => {
+      let r = await itemsPage([("filter", filterOf([("eq", JSON.Encode.string("c"))]))])
+      expect(r->itemSeqs)->toEqual(["c"])
+    })
+    testPromise("filter from b to d → [b,c,d]", async () => {
+      let r = await itemsPage([
+        ("filter", filterOf([("from", JSON.Encode.string("b")), ("to", JSON.Encode.string("d"))])),
+      ])
+      expect(r->itemSeqs)->toEqual(["b", "c", "d"])
+    })
+    testPromise("prefix c → [c]", async () => {
+      let r = await itemsPage([("filter", filterOf([("prefix", JSON.Encode.string("c"))]))])
+      expect(r->itemSeqs)->toEqual(["c"])
+    })
+    testPromise("backward last:2 before d → [b,c] (logical ASC)", async () => {
+      let r = await itemsPage([("last", JSON.Encode.int(2)), ("before", JSON.Encode.string(cur("d")))])
+      expect(r->itemSeqs)->toEqual(["b", "c"])
+      expect(pageInfoBool(r, "hasPreviousPage"))->toBe(true)
+    })
+  })
 }

package/lib/bs/tests/QueryEnginePostgresListPageTest.res.mjs

@@ -300,6 +300,142 @@ if (url !== undefined) {
       globalThis.expect(items.length).toBe(0);
     });
   });
+  let itemsName = "itemsparity";
+  let mkLine = seq => {
+    let o = {};
+    o["id"] = "order-1";
+    o["seq"] = seq;
+    return o;
+  };
+  let seqs = [
+    "a",
+    "b",
+    "c",
+    "d",
+    "e"
+  ];
+  globalThis.beforeAll(async () => {
+    let ops = QueryDbStorage_Postgres$ReventlessPostgres.makeOperations(pool, itemsName, [], "seq");
+    for (let i = 0, i_finish = seqs.length; i < i_finish; ++i) {
+      await ops.save("order-1", mkLine(seqs[i]), "Any", undefined);
+    }
+  });
+  let itemSeqs = conn => Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(field(conn, "edges"), Stdlib_JSON.Decode.array), []), e => Stdlib_Option.flatMap(field(e, "node"), n => str(n, "seq")));
+  let pageInfoBool = (conn, key) => Stdlib_Option.getOr(Stdlib_Option.flatMap(field(Stdlib_Option.getOr(field(conn, "pageInfo"), null), key), Stdlib_JSON.Decode.bool), false);
+  let itemsPage = args => Eng.itemsPage(itemsName, "seq", "order-1", Object.fromEntries(args));
+  globalThis.describe("QueryEnginePostgres itemsPage (sub-id keyset)", () => {
+    globalThis.test("bare → all lines ASC, no next page", async () => {
+      let r = await itemsPage([]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "a",
+        "b",
+        "c",
+        "d",
+        "e"
+      ]);
+      globalThis.expect(pageInfoBool(r, "hasNextPage")).toBe(false);
+    });
+    globalThis.test("first:2 → [a,b], hasNextPage", async () => {
+      let r = await itemsPage([[
+          "first",
+          2
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "a",
+        "b"
+      ]);
+      globalThis.expect(pageInfoBool(r, "hasNextPage")).toBe(true);
+    });
+    globalThis.test("first:2 after b → [c,d]", async () => {
+      let r = await itemsPage([
+        [
+          "first",
+          2
+        ],
+        [
+          "after",
+          QueryDbListQuery$ReventlessCore.encodeCursor("b")
+        ]
+      ]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "c",
+        "d"
+      ]);
+    });
+    globalThis.test("order DESC → [e..a]", async () => {
+      let r = await itemsPage([[
+          "filter",
+          Object.fromEntries([[
+              "order",
+              "DESC"
+            ]])
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "e",
+        "d",
+        "c",
+        "b",
+        "a"
+      ]);
+    });
+    globalThis.test("filter eq c → [c]", async () => {
+      let r = await itemsPage([[
+          "filter",
+          Object.fromEntries([[
+              "eq",
+              "c"
+            ]])
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual(["c"]);
+    });
+    globalThis.test("filter from b to d → [b,c,d]", async () => {
+      let r = await itemsPage([[
+          "filter",
+          Object.fromEntries([
+            [
+              "from",
+              "b"
+            ],
+            [
+              "to",
+              "d"
+            ]
+          ])
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "b",
+        "c",
+        "d"
+      ]);
+    });
+    globalThis.test("prefix c → [c]", async () => {
+      let r = await itemsPage([[
+          "filter",
+          Object.fromEntries([[
+              "prefix",
+              "c"
+            ]])
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual(["c"]);
+    });
+    globalThis.test("backward last:2 before d → [b,c] (logical ASC)", async () => {
+      let r = await itemsPage([
+        [
+          "last",
+          2
+        ],
+        [
+          "before",
+          QueryDbListQuery$ReventlessCore.encodeCursor("d")
+        ]
+      ]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "b",
+        "c"
+      ]);
+      globalThis.expect(pageInfoBool(r, "hasPreviousPage")).toBe(true);
+    });
+  });
 } else {
   globalThis.test("Postgres list push-down parity (skipped — set PG_URL to run)", () => {
     globalThis.expect(true).toBe(true);

package/lib/ocaml/.compiler.log

@@ -1,2 +1,2 @@
-#Start(1783298008858)
-#Done(1783298010813)
+#Start(1783334804845)
+#Done(1783334806753)

package/lib/ocaml/QueryEnginePostgres.res

@@ -297,6 +297,90 @@ module Make = (P: {let pool: PgDriver.pool}) => {
     }
   }
 
+  // Sub-id connection push-down: the `{single}Items(id, filter, first/after/
+  // last/before)` query. Keyset over `sub_key` WITHIN one partition — a page
+  // reads only what it returns. Reproduces QueryDbResolvers_GraphQL's items
+  // resolver (SortKey_Filter + forward/backward keyset), entirely in SQL since
+  // sub_key IS the sort key. Cursor = base64 of the sub_key value; comparisons
+  // use COLLATE "C" (byte order) to match JS string `<`. Unlike the main list
+  // there is no declined-shape fallback — every items shape maps to SQL.
+  let itemsPage = async (
+    ~readModelName,
+    ~subIdField as _: string,
+    ~id: string,
+    ~argsDict: dict<JSON.t>,
+  ): JSON.t => {
+    let table = QueryDbStorage_Postgres.tableName(readModelName)
+    let filterDict =
+      argsDict->Dict.get("filter")->Option.flatMap(JSON.Decode.object)->Option.getOr(Dict.make())
+    let fstr = k => filterDict->Dict.get(k)->Option.flatMap(JSON.Decode.string)
+    let orderDesc = fstr("order")->Option.mapOr(false, o => o == "DESC")
+    let last = argsDict->Dict.get("last")->Option.flatMap(JSON.Decode.float)->Option.map(Float.toInt)
+    let first = argsDict->Dict.get("first")->Option.flatMap(JSON.Decode.float)->Option.map(Float.toInt)
+    let after = argsDict->Dict.get("after")->Option.flatMap(JSON.Decode.string)
+    let before = argsDict->Dict.get("before")->Option.flatMap(JSON.Decode.string)
+    let isBackward = last->Option.isSome
+
+    let sk = `sub_key COLLATE "C"`
+    let b = {params: []}
+    let where = [`partition_key = ${b->param(JSON.Encode.string(id))}`, notExpired]
+    fstr("prefix")->Option.forEach(p =>
+      where->Array.push(`starts_with(sub_key, ${b->param(JSON.Encode.string(p))})`)
+    )
+    fstr("from")->Option.forEach(f => where->Array.push(`${sk} >= ${b->param(JSON.Encode.string(f))}`))
+    fstr("to")->Option.forEach(t => where->Array.push(`${sk} <= ${b->param(JSON.Encode.string(t))}`))
+    fstr("eq")->Option.forEach(e => where->Array.push(`${sk} = ${b->param(JSON.Encode.string(e))}`))
+    // Keyset: forward excludes ≤ after; backward excludes ≥ before.
+    switch (isBackward, after, before) {
+    | (false, Some(c), _) =>
+      where->Array.push(`${sk} > ${b->param(JSON.Encode.string(ReventlessCore.QueryDbListQuery.decodeCursor(c)))}`)
+    | (true, _, Some(c)) =>
+      where->Array.push(`${sk} < ${b->param(JSON.Encode.string(ReventlessCore.QueryDbListQuery.decodeCursor(c)))}`)
+    | _ => ()
+    }
+    // Page-fetch direction is the LOGICAL order forward, and its OPPOSITE
+    // backward (take the N nearest `before`, then reverse to logical) — mirrors
+    // the resolver's `reverse = isBackward ? !orderDesc : orderDesc`.
+    let fetchDesc = isBackward ? !orderDesc : orderDesc
+    let pageSize = (isBackward ? last : first)->Option.getOr(ReventlessCore.QueryDbListQuery.defaultListPageSize)
+    let sql = `SELECT partition_key, sub_key, item FROM ${table} WHERE ${where->Array.join(
+        " AND ",
+      )} ORDER BY ${sk} ${fetchDesc ? "DESC" : "ASC"} LIMIT ${b->param(JSON.Encode.int(pageSize + 1))}`
+    let rows = await P.pool->PgDriver.query(sql, b.params)
+    let hasMore = rows->Array.length > pageSize
+    let taken = rows->Array.slice(~start=0, ~end=pageSize)
+    // Backward fetched in reverse-logical order → flip back to logical.
+    let logical = isBackward ? taken->Array.toReversed : taken
+    let pageItems = logical->Array.map(decodeRow(~withId=false, ...))
+    // Cursor = the row's sub_key (== the item's subIdField value).
+    let subKeyOf = (row: dict<JSON.t>) =>
+      switch row->Dict.get("sub_key") {
+      | Some(JSON.String(s)) => s
+      | _ => ""
+      }
+    let cursors = logical->Array.map(subKeyOf)
+    let edges =
+      pageItems->Array.mapWithIndex((item, i) =>
+        Obj.magic({
+          "node": item,
+          "cursor": ReventlessCore.QueryDbListQuery.encodeCursor(cursors->Array.getUnsafe(i)),
+        })
+      )
+    let startCursor =
+      cursors->Array.get(0)->Option.map(ReventlessCore.QueryDbListQuery.encodeCursor)
+    let endCursor =
+      cursors->Array.get(cursors->Array.length - 1)->Option.map(ReventlessCore.QueryDbListQuery.encodeCursor)
+    Obj.magic({
+      "edges": edges,
+      "pageInfo": {
+        "hasNextPage": !isBackward && hasMore,
+        "hasPreviousPage": isBackward && hasMore,
+        "startCursor": startCursor->Nullable.fromOption,
+        "endCursor": endCursor->Nullable.fromOption,
+      },
+    })
+  }
+
   let make: QueryDb_Adapter.queryEngineMaker = _allQueryDbs =>
     Pulumi.Output.make({QueryEngine.scan, query})
 }

package/lib/ocaml/QueryEnginePostgresListPageTest.res

@@ -233,4 +233,80 @@ switch processEnv->Dict.get("PG_URL") {
       expect(items->Array.length)->toBe(0)
     })
   })
+
+  // ── itemsPage (sub-id connection) ─────────────────────────────────────────
+  // A sub-id read model: partition "order-1" holds 5 lines keyed by `seq`.
+  let itemsName = "itemsparity"
+  let mkLine = seq => {
+    let o = Dict.make()
+    o->Dict.set("id", JSON.Encode.string("order-1"))
+    o->Dict.set("seq", JSON.Encode.string(seq))
+    JSON.Encode.object(o)
+  }
+  let seqs = ["a", "b", "c", "d", "e"]
+  beforeAllAsync(async () => {
+    let ops = QueryDbStorage_Postgres.makeOperations(
+      ~pool,
+      ~name=itemsName,
+      ~indexes=[],
+      ~subIdField=Some("seq"),
+    )
+    for i in 0 to seqs->Array.length - 1 {
+      let _ = await ops.save("order-1", mkLine(seqs->Array.getUnsafe(i)), QueryDb.Any, None)
+    }
+  })
+
+  // Extract node `seq` values in edge order.
+  let itemSeqs = (conn: JSON.t) =>
+    conn
+    ->field("edges")
+    ->Option.flatMap(JSON.Decode.array)
+    ->Option.getOr([])
+    ->Array.filterMap(e => e->field("node")->Option.flatMap(n => n->str("seq")))
+
+  let pageInfoBool = (conn, key) =>
+    conn->field("pageInfo")->Option.getOr(JSON.Encode.null)->field(key)->Option.flatMap(JSON.Decode.bool)->Option.getOr(false)
+
+  let itemsPage = args =>
+    Eng.itemsPage(~readModelName=itemsName, ~subIdField="seq", ~id="order-1", ~argsDict=argsOf(args))
+
+  describe("QueryEnginePostgres itemsPage (sub-id keyset)", () => {
+    testPromise("bare → all lines ASC, no next page", async () => {
+      let r = await itemsPage([])
+      expect(r->itemSeqs)->toEqual(["a", "b", "c", "d", "e"])
+      expect(pageInfoBool(r, "hasNextPage"))->toBe(false)
+    })
+    testPromise("first:2 → [a,b], hasNextPage", async () => {
+      let r = await itemsPage([("first", JSON.Encode.int(2))])
+      expect(r->itemSeqs)->toEqual(["a", "b"])
+      expect(pageInfoBool(r, "hasNextPage"))->toBe(true)
+    })
+    testPromise("first:2 after b → [c,d]", async () => {
+      let r = await itemsPage([("first", JSON.Encode.int(2)), ("after", JSON.Encode.string(cur("b")))])
+      expect(r->itemSeqs)->toEqual(["c", "d"])
+    })
+    testPromise("order DESC → [e..a]", async () => {
+      let r = await itemsPage([("filter", filterOf([("order", JSON.Encode.string("DESC"))]))])
+      expect(r->itemSeqs)->toEqual(["e", "d", "c", "b", "a"])
+    })
+    testPromise("filter eq c → [c]", async () => {
+      let r = await itemsPage([("filter", filterOf([("eq", JSON.Encode.string("c"))]))])
+      expect(r->itemSeqs)->toEqual(["c"])
+    })
+    testPromise("filter from b to d → [b,c,d]", async () => {
+      let r = await itemsPage([
+        ("filter", filterOf([("from", JSON.Encode.string("b")), ("to", JSON.Encode.string("d"))])),
+      ])
+      expect(r->itemSeqs)->toEqual(["b", "c", "d"])
+    })
+    testPromise("prefix c → [c]", async () => {
+      let r = await itemsPage([("filter", filterOf([("prefix", JSON.Encode.string("c"))]))])
+      expect(r->itemSeqs)->toEqual(["c"])
+    })
+    testPromise("backward last:2 before d → [b,c] (logical ASC)", async () => {
+      let r = await itemsPage([("last", JSON.Encode.int(2)), ("before", JSON.Encode.string(cur("d")))])
+      expect(r->itemSeqs)->toEqual(["b", "c"])
+      expect(pageInfoBool(r, "hasPreviousPage"))->toBe(true)
+    })
+  })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-postgres",
-  "version": "3.0.0-alpha.5",
+  "version": "3.0.0-alpha.6",
   "description": "Postgres storage backend for Reventless (classic + DCB event logs, query DB, change feed). Connection-string only — RDS/Aurora, any managed provider, or a local container.",
   "license": "Apache-2.0",
   "jest": {
@@ -22,11 +22,11 @@
   "dependencies": {
     "pg": "^8.13.1",
     "sury": "11.0.0-alpha.4",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.6",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.25",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
     "@reventlessdev/reventless-core": "3.0.0-alpha.143",
     "@reventlessdev/reventless-infra": "3.0.0-alpha.89",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.6",
     "@reventlessdev/reventless-spec": "3.0.0-alpha.67"
   },
   "devDependencies": {

package/src/QueryEnginePostgres.res

@@ -297,6 +297,90 @@ module Make = (P: {let pool: PgDriver.pool}) => {
     }
   }
 
+  // Sub-id connection push-down: the `{single}Items(id, filter, first/after/
+  // last/before)` query. Keyset over `sub_key` WITHIN one partition — a page
+  // reads only what it returns. Reproduces QueryDbResolvers_GraphQL's items
+  // resolver (SortKey_Filter + forward/backward keyset), entirely in SQL since
+  // sub_key IS the sort key. Cursor = base64 of the sub_key value; comparisons
+  // use COLLATE "C" (byte order) to match JS string `<`. Unlike the main list
+  // there is no declined-shape fallback — every items shape maps to SQL.
+  let itemsPage = async (
+    ~readModelName,
+    ~subIdField as _: string,
+    ~id: string,
+    ~argsDict: dict<JSON.t>,
+  ): JSON.t => {
+    let table = QueryDbStorage_Postgres.tableName(readModelName)
+    let filterDict =
+      argsDict->Dict.get("filter")->Option.flatMap(JSON.Decode.object)->Option.getOr(Dict.make())
+    let fstr = k => filterDict->Dict.get(k)->Option.flatMap(JSON.Decode.string)
+    let orderDesc = fstr("order")->Option.mapOr(false, o => o == "DESC")
+    let last = argsDict->Dict.get("last")->Option.flatMap(JSON.Decode.float)->Option.map(Float.toInt)
+    let first = argsDict->Dict.get("first")->Option.flatMap(JSON.Decode.float)->Option.map(Float.toInt)
+    let after = argsDict->Dict.get("after")->Option.flatMap(JSON.Decode.string)
+    let before = argsDict->Dict.get("before")->Option.flatMap(JSON.Decode.string)
+    let isBackward = last->Option.isSome
+
+    let sk = `sub_key COLLATE "C"`
+    let b = {params: []}
+    let where = [`partition_key = ${b->param(JSON.Encode.string(id))}`, notExpired]
+    fstr("prefix")->Option.forEach(p =>
+      where->Array.push(`starts_with(sub_key, ${b->param(JSON.Encode.string(p))})`)
+    )
+    fstr("from")->Option.forEach(f => where->Array.push(`${sk} >= ${b->param(JSON.Encode.string(f))}`))
+    fstr("to")->Option.forEach(t => where->Array.push(`${sk} <= ${b->param(JSON.Encode.string(t))}`))
+    fstr("eq")->Option.forEach(e => where->Array.push(`${sk} = ${b->param(JSON.Encode.string(e))}`))
+    // Keyset: forward excludes ≤ after; backward excludes ≥ before.
+    switch (isBackward, after, before) {
+    | (false, Some(c), _) =>
+      where->Array.push(`${sk} > ${b->param(JSON.Encode.string(ReventlessCore.QueryDbListQuery.decodeCursor(c)))}`)
+    | (true, _, Some(c)) =>
+      where->Array.push(`${sk} < ${b->param(JSON.Encode.string(ReventlessCore.QueryDbListQuery.decodeCursor(c)))}`)
+    | _ => ()
+    }
+    // Page-fetch direction is the LOGICAL order forward, and its OPPOSITE
+    // backward (take the N nearest `before`, then reverse to logical) — mirrors
+    // the resolver's `reverse = isBackward ? !orderDesc : orderDesc`.
+    let fetchDesc = isBackward ? !orderDesc : orderDesc
+    let pageSize = (isBackward ? last : first)->Option.getOr(ReventlessCore.QueryDbListQuery.defaultListPageSize)
+    let sql = `SELECT partition_key, sub_key, item FROM ${table} WHERE ${where->Array.join(
+        " AND ",
+      )} ORDER BY ${sk} ${fetchDesc ? "DESC" : "ASC"} LIMIT ${b->param(JSON.Encode.int(pageSize + 1))}`
+    let rows = await P.pool->PgDriver.query(sql, b.params)
+    let hasMore = rows->Array.length > pageSize
+    let taken = rows->Array.slice(~start=0, ~end=pageSize)
+    // Backward fetched in reverse-logical order → flip back to logical.
+    let logical = isBackward ? taken->Array.toReversed : taken
+    let pageItems = logical->Array.map(decodeRow(~withId=false, ...))
+    // Cursor = the row's sub_key (== the item's subIdField value).
+    let subKeyOf = (row: dict<JSON.t>) =>
+      switch row->Dict.get("sub_key") {
+      | Some(JSON.String(s)) => s
+      | _ => ""
+      }
+    let cursors = logical->Array.map(subKeyOf)
+    let edges =
+      pageItems->Array.mapWithIndex((item, i) =>
+        Obj.magic({
+          "node": item,
+          "cursor": ReventlessCore.QueryDbListQuery.encodeCursor(cursors->Array.getUnsafe(i)),
+        })
+      )
+    let startCursor =
+      cursors->Array.get(0)->Option.map(ReventlessCore.QueryDbListQuery.encodeCursor)
+    let endCursor =
+      cursors->Array.get(cursors->Array.length - 1)->Option.map(ReventlessCore.QueryDbListQuery.encodeCursor)
+    Obj.magic({
+      "edges": edges,
+      "pageInfo": {
+        "hasNextPage": !isBackward && hasMore,
+        "hasPreviousPage": isBackward && hasMore,
+        "startCursor": startCursor->Nullable.fromOption,
+        "endCursor": endCursor->Nullable.fromOption,
+      },
+    })
+  }
+
   let make: QueryDb_Adapter.queryEngineMaker = _allQueryDbs =>
     Pulumi.Output.make({QueryEngine.scan, query})
 }

package/src/QueryEnginePostgres.res.mjs

@@ -3,6 +3,7 @@
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Pulumi from "@pulumi/pulumi";
+import * as Stdlib_Nullable from "@rescript/runtime/lib/es6/Stdlib_Nullable.js";
 import * as PgDriver$ReventlessPostgres from "./PgDriver.res.mjs";
 import * as QueryDbListQuery$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/QueryDbListQuery.res.mjs";
 import * as QueryDbStorage_Postgres$ReventlessPostgres from "./QueryDbStorage_Postgres.res.mjs";
@@ -231,6 +232,78 @@ function Make(P) {
     let cursorValueOf = item => Stdlib_Option.getOr(QueryDbListQuery$ReventlessCore.getFieldString(item, cursorField), QueryDbListQuery$ReventlessCore.getId(item));
     return QueryDbListQuery$ReventlessCore.buildConnection(pageItems, hasMore, false, cursorValueOf);
   };
+  let itemsPage = async (readModelName, param$1, id, argsDict) => {
+    let table = QueryDbStorage_Postgres$ReventlessPostgres.tableName(readModelName);
+    let filterDict = Stdlib_Option.getOr(Stdlib_Option.flatMap(argsDict["filter"], Stdlib_JSON.Decode.object), {});
+    let fstr = k => Stdlib_Option.flatMap(filterDict[k], Stdlib_JSON.Decode.string);
+    let orderDesc = Stdlib_Option.mapOr(fstr("order"), false, o => o === "DESC");
+    let last = Stdlib_Option.map(Stdlib_Option.flatMap(argsDict["last"], Stdlib_JSON.Decode.float), prim => prim | 0);
+    let first = Stdlib_Option.map(Stdlib_Option.flatMap(argsDict["first"], Stdlib_JSON.Decode.float), prim => prim | 0);
+    let after = Stdlib_Option.flatMap(argsDict["after"], Stdlib_JSON.Decode.string);
+    let before = Stdlib_Option.flatMap(argsDict["before"], Stdlib_JSON.Decode.string);
+    let isBackward = Stdlib_Option.isSome(last);
+    let sk = `sub_key COLLATE "C"`;
+    let b = {
+      params: []
+    };
+    let where = [
+      `partition_key = ` + param(b, id),
+      QueryDbStorage_Postgres$ReventlessPostgres.notExpiredClause
+    ];
+    Stdlib_Option.forEach(fstr("prefix"), p => {
+      where.push(`starts_with(sub_key, ` + param(b, p) + `)`);
+    });
+    Stdlib_Option.forEach(fstr("from"), f => {
+      where.push(sk + ` >= ` + param(b, f));
+    });
+    Stdlib_Option.forEach(fstr("to"), t => {
+      where.push(sk + ` <= ` + param(b, t));
+    });
+    Stdlib_Option.forEach(fstr("eq"), e => {
+      where.push(sk + ` = ` + param(b, e));
+    });
+    if (isBackward) {
+      if (before !== undefined) {
+        where.push(sk + ` < ` + param(b, QueryDbListQuery$ReventlessCore.decodeCursor(before)));
+      }
+    } else if (after !== undefined) {
+      where.push(sk + ` > ` + param(b, QueryDbListQuery$ReventlessCore.decodeCursor(after)));
+    }
+    let fetchDesc = isBackward ? !orderDesc : orderDesc;
+    let pageSize = Stdlib_Option.getOr(isBackward ? last : first, QueryDbListQuery$ReventlessCore.defaultListPageSize);
+    let sql = `SELECT partition_key, sub_key, item FROM ` + table + ` WHERE ` + where.join(" AND ") + ` ORDER BY ` + sk + ` ` + (
+      fetchDesc ? "DESC" : "ASC"
+    ) + ` LIMIT ` + param(b, pageSize + 1 | 0);
+    let rows = await PgDriver$ReventlessPostgres.query(P.pool, sql, b.params);
+    let hasMore = rows.length > pageSize;
+    let taken = rows.slice(0, pageSize);
+    let logical = isBackward ? taken.toReversed() : taken;
+    let pageItems = logical.map(extra => decodeRow(false, extra));
+    let subKeyOf = row => {
+      let match = row["sub_key"];
+      if (typeof match === "string") {
+        return match;
+      } else {
+        return "";
+      }
+    };
+    let cursors = logical.map(subKeyOf);
+    let edges = pageItems.map((item, i) => ({
+      node: item,
+      cursor: QueryDbListQuery$ReventlessCore.encodeCursor(cursors[i])
+    }));
+    let startCursor = Stdlib_Option.map(cursors[0], QueryDbListQuery$ReventlessCore.encodeCursor);
+    let endCursor = Stdlib_Option.map(cursors[cursors.length - 1 | 0], QueryDbListQuery$ReventlessCore.encodeCursor);
+    return {
+      edges: edges,
+      pageInfo: {
+        hasNextPage: !isBackward && hasMore,
+        hasPreviousPage: isBackward && hasMore,
+        startCursor: Stdlib_Nullable.fromOption(startCursor),
+        endCursor: Stdlib_Nullable.fromOption(endCursor)
+      }
+    };
+  };
   let make = _allQueryDbs => Pulumi.output({
     scan: scan,
     query: query
@@ -243,6 +316,7 @@ function Make(P) {
     idExprC: idExprC,
     jsonTextC: jsonTextC,
     listPage: listPage,
+    itemsPage: itemsPage,
     make: make
   };
 }

package/tests/QueryEnginePostgresListPageTest.res

@@ -233,4 +233,80 @@ switch processEnv->Dict.get("PG_URL") {
       expect(items->Array.length)->toBe(0)
     })
   })
+
+  // ── itemsPage (sub-id connection) ─────────────────────────────────────────
+  // A sub-id read model: partition "order-1" holds 5 lines keyed by `seq`.
+  let itemsName = "itemsparity"
+  let mkLine = seq => {
+    let o = Dict.make()
+    o->Dict.set("id", JSON.Encode.string("order-1"))
+    o->Dict.set("seq", JSON.Encode.string(seq))
+    JSON.Encode.object(o)
+  }
+  let seqs = ["a", "b", "c", "d", "e"]
+  beforeAllAsync(async () => {
+    let ops = QueryDbStorage_Postgres.makeOperations(
+      ~pool,
+      ~name=itemsName,
+      ~indexes=[],
+      ~subIdField=Some("seq"),
+    )
+    for i in 0 to seqs->Array.length - 1 {
+      let _ = await ops.save("order-1", mkLine(seqs->Array.getUnsafe(i)), QueryDb.Any, None)
+    }
+  })
+
+  // Extract node `seq` values in edge order.
+  let itemSeqs = (conn: JSON.t) =>
+    conn
+    ->field("edges")
+    ->Option.flatMap(JSON.Decode.array)
+    ->Option.getOr([])
+    ->Array.filterMap(e => e->field("node")->Option.flatMap(n => n->str("seq")))
+
+  let pageInfoBool = (conn, key) =>
+    conn->field("pageInfo")->Option.getOr(JSON.Encode.null)->field(key)->Option.flatMap(JSON.Decode.bool)->Option.getOr(false)
+
+  let itemsPage = args =>
+    Eng.itemsPage(~readModelName=itemsName, ~subIdField="seq", ~id="order-1", ~argsDict=argsOf(args))
+
+  describe("QueryEnginePostgres itemsPage (sub-id keyset)", () => {
+    testPromise("bare → all lines ASC, no next page", async () => {
+      let r = await itemsPage([])
+      expect(r->itemSeqs)->toEqual(["a", "b", "c", "d", "e"])
+      expect(pageInfoBool(r, "hasNextPage"))->toBe(false)
+    })
+    testPromise("first:2 → [a,b], hasNextPage", async () => {
+      let r = await itemsPage([("first", JSON.Encode.int(2))])
+      expect(r->itemSeqs)->toEqual(["a", "b"])
+      expect(pageInfoBool(r, "hasNextPage"))->toBe(true)
+    })
+    testPromise("first:2 after b → [c,d]", async () => {
+      let r = await itemsPage([("first", JSON.Encode.int(2)), ("after", JSON.Encode.string(cur("b")))])
+      expect(r->itemSeqs)->toEqual(["c", "d"])
+    })
+    testPromise("order DESC → [e..a]", async () => {
+      let r = await itemsPage([("filter", filterOf([("order", JSON.Encode.string("DESC"))]))])
+      expect(r->itemSeqs)->toEqual(["e", "d", "c", "b", "a"])
+    })
+    testPromise("filter eq c → [c]", async () => {
+      let r = await itemsPage([("filter", filterOf([("eq", JSON.Encode.string("c"))]))])
+      expect(r->itemSeqs)->toEqual(["c"])
+    })
+    testPromise("filter from b to d → [b,c,d]", async () => {
+      let r = await itemsPage([
+        ("filter", filterOf([("from", JSON.Encode.string("b")), ("to", JSON.Encode.string("d"))])),
+      ])
+      expect(r->itemSeqs)->toEqual(["b", "c", "d"])
+    })
+    testPromise("prefix c → [c]", async () => {
+      let r = await itemsPage([("filter", filterOf([("prefix", JSON.Encode.string("c"))]))])
+      expect(r->itemSeqs)->toEqual(["c"])
+    })
+    testPromise("backward last:2 before d → [b,c] (logical ASC)", async () => {
+      let r = await itemsPage([("last", JSON.Encode.int(2)), ("before", JSON.Encode.string(cur("d")))])
+      expect(r->itemSeqs)->toEqual(["b", "c"])
+      expect(pageInfoBool(r, "hasPreviousPage"))->toBe(true)
+    })
+  })
 }

package/tests/QueryEnginePostgresListPageTest.res.mjs

@@ -300,6 +300,142 @@ if (url !== undefined) {
       globalThis.expect(items.length).toBe(0);
     });
   });
+  let itemsName = "itemsparity";
+  let mkLine = seq => {
+    let o = {};
+    o["id"] = "order-1";
+    o["seq"] = seq;
+    return o;
+  };
+  let seqs = [
+    "a",
+    "b",
+    "c",
+    "d",
+    "e"
+  ];
+  globalThis.beforeAll(async () => {
+    let ops = QueryDbStorage_Postgres$ReventlessPostgres.makeOperations(pool, itemsName, [], "seq");
+    for (let i = 0, i_finish = seqs.length; i < i_finish; ++i) {
+      await ops.save("order-1", mkLine(seqs[i]), "Any", undefined);
+    }
+  });
+  let itemSeqs = conn => Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(field(conn, "edges"), Stdlib_JSON.Decode.array), []), e => Stdlib_Option.flatMap(field(e, "node"), n => str(n, "seq")));
+  let pageInfoBool = (conn, key) => Stdlib_Option.getOr(Stdlib_Option.flatMap(field(Stdlib_Option.getOr(field(conn, "pageInfo"), null), key), Stdlib_JSON.Decode.bool), false);
+  let itemsPage = args => Eng.itemsPage(itemsName, "seq", "order-1", Object.fromEntries(args));
+  globalThis.describe("QueryEnginePostgres itemsPage (sub-id keyset)", () => {
+    globalThis.test("bare → all lines ASC, no next page", async () => {
+      let r = await itemsPage([]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "a",
+        "b",
+        "c",
+        "d",
+        "e"
+      ]);
+      globalThis.expect(pageInfoBool(r, "hasNextPage")).toBe(false);
+    });
+    globalThis.test("first:2 → [a,b], hasNextPage", async () => {
+      let r = await itemsPage([[
+          "first",
+          2
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "a",
+        "b"
+      ]);
+      globalThis.expect(pageInfoBool(r, "hasNextPage")).toBe(true);
+    });
+    globalThis.test("first:2 after b → [c,d]", async () => {
+      let r = await itemsPage([
+        [
+          "first",
+          2
+        ],
+        [
+          "after",
+          QueryDbListQuery$ReventlessCore.encodeCursor("b")
+        ]
+      ]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "c",
+        "d"
+      ]);
+    });
+    globalThis.test("order DESC → [e..a]", async () => {
+      let r = await itemsPage([[
+          "filter",
+          Object.fromEntries([[
+              "order",
+              "DESC"
+            ]])
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "e",
+        "d",
+        "c",
+        "b",
+        "a"
+      ]);
+    });
+    globalThis.test("filter eq c → [c]", async () => {
+      let r = await itemsPage([[
+          "filter",
+          Object.fromEntries([[
+              "eq",
+              "c"
+            ]])
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual(["c"]);
+    });
+    globalThis.test("filter from b to d → [b,c,d]", async () => {
+      let r = await itemsPage([[
+          "filter",
+          Object.fromEntries([
+            [
+              "from",
+              "b"
+            ],
+            [
+              "to",
+              "d"
+            ]
+          ])
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "b",
+        "c",
+        "d"
+      ]);
+    });
+    globalThis.test("prefix c → [c]", async () => {
+      let r = await itemsPage([[
+          "filter",
+          Object.fromEntries([[
+              "prefix",
+              "c"
+            ]])
+        ]]);
+      globalThis.expect(itemSeqs(r)).toEqual(["c"]);
+    });
+    globalThis.test("backward last:2 before d → [b,c] (logical ASC)", async () => {
+      let r = await itemsPage([
+        [
+          "last",
+          2
+        ],
+        [
+          "before",
+          QueryDbListQuery$ReventlessCore.encodeCursor("d")
+        ]
+      ]);
+      globalThis.expect(itemSeqs(r)).toEqual([
+        "b",
+        "c"
+      ]);
+      globalThis.expect(pageInfoBool(r, "hasPreviousPage")).toBe(true);
+    });
+  });
 } else {
   globalThis.test("Postgres list push-down parity (skipped — set PG_URL to run)", () => {
     globalThis.expect(true).toBe(true);