@gaganref/confect-server 10.3.1-fork.5 → 10.3.1-fork.50

package/src/QueryStream.ts

@@ -70,7 +70,16 @@ import * as QueryStreamPagination from "./QueryStreamPagination.js";
 import * as QueryStreamReadBudget from "./QueryStreamReadBudget.js";
 
 /**
- * A page exhausted its read budget without a safe logical continuation.
+ * Default physical row budget for `paginate` and `collect`. Supply an explicit
+ * `maximumRowsRead` to override it. Plain Effect Stream consumers use their
+ * enclosing budget and remain unlimited when none is provided.
+ *
+ * @experimental
+ */
+export const DEFAULT_MAXIMUM_ROWS_READ = 2_000;
+
+/**
+ * A query stream exhausted its read budget before its consumer could finish.
  *
  * @experimental
  */
@@ -79,7 +88,7 @@ export class ReadBudgetExceededError extends Schema.TaggedError<ReadBudgetExceed
   { rowsRead: Schema.Natural, bytesRead: Schema.Natural },
 ) {
   override get message() {
-    return "The read budget was exhausted before a safe page boundary; increase the budget or simplify the query";
+    return "The read budget was exhausted before the query stream completed; increase the budget or simplify the query";
   }
 }
 
@@ -441,6 +450,89 @@ export const empty =
     return make(orderDirection);
   };
 
+/**
+ * A deferred stream's resolved direction or layout differs from its
+ * declaration. The check runs on consumption, before the resolved source is
+ * pulled.
+ *
+ * @experimental
+ */
+export class DeferredStreamMismatchError extends Data.TaggedError(
+  "DeferredStreamMismatchError",
+)<{
+  readonly expectedOrderDirection: QueryStreamOrderDirection.QueryStreamOrderDirection;
+  readonly actualOrderDirection: QueryStreamOrderDirection.QueryStreamOrderDirection;
+  readonly expectedKeyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout;
+  readonly actualKeyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout;
+}> {}
+
+/**
+ * Defer an effect that checks access or constructs a query stream until it is
+ * pulled. Supply its layout and direction without reading documents. This lets
+ * `flatMap` build and narrow an inner stream before running its checks.
+ *
+ * The effect runs afresh on each consumption, seek, or reversal. Failures and
+ * service requirements are preserved. Its stream must match the declared layout
+ * and direction, or consumption dies with `DeferredStreamMismatchError`.
+ *
+ * @experimental
+ */
+export const defer = <
+  Doc,
+  KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels,
+  OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection,
+  E = never,
+  R = never,
+  E2 = never,
+  R2 = never,
+>(
+  options: {
+    readonly keyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout<KeyLabels>;
+    readonly orderDirection: OrderDirection;
+  },
+  make: Effect.Effect<
+    QueryStream<Doc, KeyLabels, NoInfer<OrderDirection>, E, R>,
+    E2,
+    R2
+  >,
+): QueryStream<Doc, KeyLabels, OrderDirection, E | E2, R | R2> => {
+  const checked = Effect.map(make, (stream) => {
+    if (
+      stream.orderDirection !== options.orderDirection ||
+      !QueryStreamKeyLayout.Equivalence(stream.keyLayout, options.keyLayout)
+    ) {
+      throw new DeferredStreamMismatchError({
+        expectedOrderDirection: options.orderDirection,
+        actualOrderDirection: stream.orderDirection,
+        expectedKeyLayout: options.keyLayout,
+        actualKeyLayout: stream.keyLayout,
+      });
+    }
+    return stream;
+  });
+  return new QueryStream(
+    options.orderDirection,
+    options.keyLayout,
+    Stream.unwrap(Effect.map(checked, (stream) => stream.annotated)),
+    undefined,
+    (bounds) =>
+      defer(
+        options,
+        Effect.map(checked, (stream) => narrowByParsedBounds(stream, bounds)),
+      ),
+    () =>
+      defer(
+        {
+          ...options,
+          orderDirection: QueryStreamOrderDirection.flip(
+            options.orderDirection,
+          ),
+        },
+        Effect.map(checked, reverse),
+      ),
+  );
+};
+
 // -----------------------------------------------------------------------------
 // Constructors
 // -----------------------------------------------------------------------------
@@ -742,6 +834,21 @@ const fillMergeSource = <Doc, E>(
     BudgetLimited: () => Effect.succeed(source),
   });
 
+const consumeMergeHead = <Doc, E>(
+  source: MergeSource<Doc, E>,
+): MergeSource<Doc, E> =>
+  source._tag === "Buffered"
+    ? Option.match(Chunk.head(source.tail), {
+        onNone: () => MergeSource.NeedsPull({ pull: source.pull }),
+        onSome: (head) =>
+          MergeSource.Buffered({
+            pull: source.pull,
+            head,
+            tail: Chunk.drop(source.tail, 1),
+          }),
+      })
+    : source;
+
 /**
  * One step of the k-way merge as a pure unfold: fill every source, emit the
  * earliest head (ties go to the earliest source, keeping the merge stable), and
@@ -749,7 +856,10 @@ const fillMergeSource = <Doc, E>(
  * exhausted or an input stopped before its next key was known.
  */
 const mergeStep =
-  <Doc, E>(keyOrder: Order.Order<QueryStreamKeyValues.QueryStreamKeyValues>) =>
+  <Doc, E>(
+    keyOrder: Order.Order<QueryStreamKeyValues.QueryStreamKeyValues>,
+    dedupe: boolean,
+  ) =>
   (
     sources: ReadonlyArray<MergeSource<Doc, E>>,
   ): Effect.Effect<
@@ -791,36 +901,73 @@ const mergeStep =
           ),
       );
 
-      return Option.getOrUndefined(
-        Option.map(earliest, ({ index, element }) =>
-          Tuple.make(
-            element,
-            Array.map(filled, (source, sourceIndex) =>
-              sourceIndex === index && source._tag === "Buffered"
-                ? Option.match(Chunk.head(source.tail), {
-                    onNone: () => MergeSource.NeedsPull({ pull: source.pull }),
-                    onSome: (head) =>
-                      MergeSource.Buffered({
-                        pull: source.pull,
-                        head,
-                        tail: Chunk.drop(source.tail, 1),
-                      }),
-                  })
-                : source,
-            ),
+      if (Option.isNone(earliest)) return undefined;
+      if (!dedupe) {
+        const { index, element } = earliest.value;
+        return Tuple.make(
+          element,
+          Array.map(filled, (source, sourceIndex) =>
+            sourceIndex === index ? consumeMergeHead(source) : source,
           ),
-        ),
-      );
+        );
+      }
+      const keyValues = earliest.value.element.keyValues;
+      const matches = (source: MergeSource<Doc, E>) =>
+        source._tag === "Buffered" &&
+        keyOrder(source.head.keyValues, keyValues) === 0;
+      let representative = earliest.value;
+      let remaining = filled;
+      // Resolve the entire equal-key group before publishing its boundary.
+      // A budget stop leaves it for the next page, including any visible copy.
+      for (;;) {
+        representative = Array.reduce(
+          remaining,
+          representative,
+          (best, source, index) =>
+            source._tag === "Buffered" &&
+            matches(source) &&
+            Option.isSome(source.head.doc) &&
+            (Option.isNone(best.element.doc) || index < best.index)
+              ? new MergeCandidate({ index, element: source.head })
+              : best,
+        );
+        remaining = yield* Effect.forEach(
+          Array.map(remaining, (source) =>
+            matches(source) ? consumeMergeHead(source) : source,
+          ),
+          fillMergeSource,
+          { concurrency: (yield* readBudget.isUnlimited) ? "unbounded" : 1 },
+        );
+        if (
+          remaining.some((source) => MergeSource.$is("BudgetLimited")(source))
+        )
+          return undefined;
+        if (!remaining.some(matches))
+          return Tuple.make(representative.element, remaining);
+      }
     });
 
+/**
+ * Optional merge behavior. With `dedupe`, equal complete stored keys, including
+ * ID tiebreakers, emit once. The first visible copy in source order wins; a
+ * filtered copy cannot suppress a visible one. Different keys remain distinct.
+ *
+ * @experimental
+ */
+export interface MergeOptions {
+  readonly dedupe?: boolean;
+}
+
 /**
  * Combine streams sharing a key layout into one stream in key order. Use this
  * to query several index ranges at once, such as notes by multiple roles.
  *
  * The merge emits the smallest next key when ascending and the largest when
- * descending. Unlike `Stream.merge`, it does not interleave by arrival time.
- * Overlapping inputs are not deduplicated: a document matched twice appears
- * twice. Supply at least one input; use `empty` for an empty dynamic list.
+ * descending. Unlike `Stream.merge`, it does not interleave by arrival time. By
+ * default, a document matched twice appears twice. Pass `{ dedupe: true }` to
+ * coalesce equal complete keys, including ID tiebreakers. Resolving a group can
+ * prefetch the next key from each input; all such reads count against the
+ * shared budget. Supply at least one input; use `empty` for an empty list.
  *
  * Inputs need compatible document types and identical key layouts and
  * directions. TypeScript rejects known mismatches; runtime mismatches throw
@@ -842,6 +989,7 @@ export const merge = <
       QueryStream<Doc, KeyLabels, NoInfer<OrderDirection>, E, R>
     >,
   ],
+  options?: MergeOptions,
 ): QueryStream<Doc, KeyLabels, OrderDirection, E, R> => {
   const head = Array.headNonEmpty(streams);
   const incompatible = Array.findFirst(
@@ -858,7 +1006,7 @@ export const merge = <
       actualKeyLayout: incompatible.value.keyLayout,
     });
   }
-  return mergeUnchecked(streams);
+  return mergeUnchecked(streams, options);
 };
 
 /**
@@ -877,6 +1025,7 @@ const mergeUnchecked = <
     QueryStream<Doc, KeyLabels, OrderDirection, E, R>,
     ...ReadonlyArray<QueryStream<Doc, KeyLabels, OrderDirection, E, R>>,
   ],
+  options?: MergeOptions,
 ): QueryStream<Doc, KeyLabels, OrderDirection, E, R> => {
   const head = Array.headNonEmpty(streams);
   const annotated: Stream.Stream<
@@ -889,7 +1038,10 @@ const mergeUnchecked = <
       (pulls) =>
         Stream.unfold(
           Array.map(pulls, (pull) => MergeSource.NeedsPull({ pull })),
-          mergeStep<Doc, E>(QueryStreamKeyValues.Order(head.orderDirection)),
+          mergeStep<Doc, E>(
+            QueryStreamKeyValues.Order(head.orderDirection),
+            options?.dedupe === true,
+          ),
         ),
     ),
   );
@@ -903,17 +1055,25 @@ const mergeUnchecked = <
     // key space, so each branch converts them to its own index-key
     // space itself.
     (parsedBounds) =>
-      mergeUnchecked([
-        narrowByParsedBounds(head, parsedBounds),
-        ...Array.map(Array.tailNonEmpty(streams), (stream) =>
-          narrowByParsedBounds(stream, parsedBounds),
-        ),
-      ]),
+      mergeUnchecked(
+        [
+          narrowByParsedBounds(head, parsedBounds),
+          ...Array.map(Array.tailNonEmpty(streams), (stream) =>
+            narrowByParsedBounds(stream, parsedBounds),
+          ),
+        ],
+        options,
+      ),
     () =>
-      mergeUnchecked([
-        reverse(head),
-        ...Array.map(Array.tailNonEmpty(streams), (stream) => reverse(stream)),
-      ]),
+      mergeUnchecked(
+        [
+          reverse(head),
+          ...Array.map(Array.tailNonEmpty(streams), (stream) =>
+            reverse(stream),
+          ),
+        ],
+        options,
+      ),
   );
 };
 
@@ -2140,6 +2300,98 @@ const narrowInMemory = <
 // Sinks
 // -----------------------------------------------------------------------------
 
+/**
+ * Read limits for `collect`. These count underlying index reads, including
+ * filtered rows and join inputs, rather than just emitted values. At either
+ * limit, one extra row may be read to distinguish completion from an overrun;
+ * it counts toward reported reads but is never emitted. This also applies at
+ * zero, so an empty stream completes under a zero budget.
+ *
+ * @experimental
+ */
+export interface CollectOptions {
+  readonly maximumRowsRead?: number;
+  readonly maximumBytesRead?: number;
+}
+
+/**
+ * Collect the whole query stream or fail with `ReadBudgetExceededError` when a
+ * read budget stops it. No partial array reaches the caller. Arbitrary I/O in
+ * callbacks is not counted. Use `paginate` for data that can grow without
+ * bound.
+ *
+ * With explicit options, each run gets a fresh budget. Without options, use the
+ * enclosing budget if present, or the default row budget.
+ *
+ * @experimental
+ */
+export const collect: {
+  (
+    options?: CollectOptions,
+  ): <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R>(
+    self: QueryStream<
+      Doc,
+      KeyLabels,
+      QueryStreamOrderDirection.QueryStreamOrderDirection,
+      E,
+      R
+    >,
+  ) => Effect.Effect<Array<Doc>, E | ReadBudgetExceededError, R>;
+  <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R>(
+    self: QueryStream<
+      Doc,
+      KeyLabels,
+      QueryStreamOrderDirection.QueryStreamOrderDirection,
+      E,
+      R
+    >,
+    options?: CollectOptions,
+  ): Effect.Effect<Array<Doc>, E | ReadBudgetExceededError, R>;
+} = dual(
+  (args) => isQueryStream(args[0]),
+  Effect.fn("QueryStream.collect")(function* <
+    Doc,
+    KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels,
+    E,
+    R,
+  >(
+    self: QueryStream<
+      Doc,
+      KeyLabels,
+      QueryStreamOrderDirection.QueryStreamOrderDirection,
+      E,
+      R
+    >,
+    options?: CollectOptions,
+  ) {
+    const makeBudget = Schema.decodeEffect(QueryStreamReadBudget.Limits)({
+      maximumRowsRead: DEFAULT_MAXIMUM_ROWS_READ,
+      ...options,
+    }).pipe(
+      Effect.catchTag("SchemaError", (cause) =>
+        Effect.die(new QueryStreamReadBudget.InvalidReadLimitError({ cause })),
+      ),
+      Effect.flatMap(QueryStreamReadBudget.make),
+    );
+    const budget = yield* options === undefined
+      ? Effect.serviceOption(QueryStreamReadBudget.QueryStreamReadBudget).pipe(
+          Effect.flatMap(
+            Option.match({ onNone: () => makeBudget, onSome: Effect.succeed }),
+          ),
+        )
+      : makeBudget;
+    const rows = yield* Stream.runCollect(self.toStream()).pipe(
+      Effect.provideService(
+        QueryStreamReadBudget.QueryStreamReadBudget,
+        budget,
+      ),
+    );
+    if (yield* budget.isStopped)
+      return yield* new ReadBudgetExceededError(yield* budget.getReadCounts);
+    return rows;
+  }),
+);
+
 /**
  * `unique` found at least two emitted values. Narrow the query if at most one
  * value was expected, or use another consumer to handle multiple results.
@@ -2189,6 +2441,27 @@ export const unique = Effect.fn("QueryStream.unique")(
 // Pagination
 // -----------------------------------------------------------------------------
 
+/**
+ * Caller-owned envelope for every pagination cursor, including end sentinels.
+ * `open` validates a received cursor and returns `None` on a mismatch; paginate
+ * then dies with `ConvexError({ paginationError: "InvalidCursor" })` before
+ * decoding or reading. `seal` wraps every outgoing continuation and split.
+ * `seal` must return the same string for equal inputs so cursor equality stays
+ * stable.
+ *
+ * Use this to bind cursors to query semantics or sign them. Both callbacks may
+ * use Effect services. Confect owns no keys, fingerprints, or encryption
+ * policy.
+ *
+ * @experimental
+ */
+export interface CursorEnvelope<R = never> {
+  readonly open: (
+    cursor: string,
+  ) => Effect.Effect<Option.Option<string>, never, R>;
+  readonly seal: (cursor: string) => Effect.Effect<string, never, R>;
+}
+
 /**
  * Convex pagination options interpreted over a query stream's stored keys. Pass
  * a paginated query handler's `paginationOpts` directly to `paginate`.
@@ -2200,17 +2473,27 @@ export const unique = Effect.fn("QueryStream.unique")(
  * - `endCursor`: optional inclusive boundary returned by a previous page. Pins
  *   the page to a key range regardless of how many values it holds.
  * - `maximumRowsRead`: optional budget for physical document reads from
- *   underlying query-stream indexes, including filtered documents.
+ *   underlying query-stream indexes, including filtered documents. Defaults to
+ *   2,000; an explicit limit overrides the default.
  * - `maximumBytesRead`: optional budget charging estimated document size on every
  *   read, not Convex's exact billed bytes. The final document can take the
  *   total over the limit because its size is known only after reading it.
+ * - `cursorEnvelope`: optional caller-owned validation and sealing. Both input
+ *   cursors are opened before decoding, including an end sentinel. Every output
+ *   cursor is sealed. A refused envelope ends in `InvalidCursor`.
+ *
+ * At either read limit, including zero, one extra row may be read to
+ * distinguish completion from an overrun. It is counted but never emitted. An
+ * empty stream completes under a zero budget.
  *
  * With `numItems: 0`, an existing cursor is returned unchanged with an empty
  * page and `isDone: false`; a null cursor dies with `EmptyInitialPageError`.
  *
  * @experimental
  */
-export type PaginateOptions = ConvexPaginationOptions;
+export type PaginateOptions<R = never> = ConvexPaginationOptions & {
+  readonly cursorEnvelope?: CursorEnvelope<R>;
+};
 
 /**
  * One page in Convex's pagination result shape. Return the whole result to
@@ -2264,9 +2547,9 @@ export type PaginationResult<Doc> = ConvexPaginationResult<Doc>;
  * query semantics change, even if an old cursor is still accepted.
  *
  * Cursors expose boundary field names and key values, including document IDs.
- * They are neither opaque nor signed: clients can read or craft them. Do not
- * publicly paginate over sensitive indexed fields unless pinned with `eq`.
- * Never construct cursors from documents or decode them into `narrow` bounds.
+ * Without a `cursorEnvelope`, clients can read or craft them. Do not publicly
+ * paginate over sensitive indexed fields unless pinned with `eq`. Never
+ * construct cursors from documents or decode them into `narrow` bounds.
  *
  * Return the whole result to reactive clients. React's
  * `useStreamPaginatedQuery` handles pinning, splitting, and invalid-cursor
@@ -2276,8 +2559,8 @@ export type PaginationResult<Doc> = ConvexPaginationResult<Doc>;
  * @experimental
  */
 export const paginate: {
-  (
-    options: PaginateOptions,
+  <R2 = never>(
+    options: PaginateOptions<R2>,
   ): <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R>(
     self: QueryStream<
       Doc,
@@ -2286,8 +2569,18 @@ export const paginate: {
       E,
       R
     >,
-  ) => Effect.Effect<PaginationResult<Doc>, E | ReadBudgetExceededError, R>;
-  <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R>(
+  ) => Effect.Effect<
+    PaginationResult<Doc>,
+    E | ReadBudgetExceededError,
+    R | R2
+  >;
+  <
+    Doc,
+    KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels,
+    E,
+    R,
+    R2 = never,
+  >(
     self: QueryStream<
       Doc,
       KeyLabels,
@@ -2295,8 +2588,8 @@ export const paginate: {
       E,
       R
     >,
-    options: PaginateOptions,
-  ): Effect.Effect<PaginationResult<Doc>, E | ReadBudgetExceededError, R>;
+    options: PaginateOptions<R2>,
+  ): Effect.Effect<PaginationResult<Doc>, E | ReadBudgetExceededError, R | R2>;
 } = dual(
   2,
   Effect.fn("QueryStream.paginate")(
@@ -2307,10 +2600,37 @@ export const paginate: {
       R,
       OrderDirection extends
         QueryStreamOrderDirection.QueryStreamOrderDirection,
+      R2 = never,
     >(
       self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>,
-      options: PaginateOptions,
+      options: PaginateOptions<R2>,
     ) {
+      const seal = (cursor: string): Effect.Effect<string, never, R2> =>
+        options.cursorEnvelope === undefined
+          ? Effect.succeed(cursor)
+          : options.cursorEnvelope.seal(cursor);
+      const open = (cursor: string): Effect.Effect<string, never, R2> =>
+        options.cursorEnvelope === undefined
+          ? Effect.succeed(cursor)
+          : options.cursorEnvelope.open(cursor).pipe(
+              Effect.flatMap(
+                Option.match({
+                  onNone: () =>
+                    Effect.die(
+                      new ConvexError({ paginationError: "InvalidCursor" }),
+                    ),
+                  onSome: Effect.succeed,
+                }),
+              ),
+            );
+      const opened = yield* Effect.all({
+        start:
+          options.cursor === null ? Effect.succeed(null) : open(options.cursor),
+        end:
+          options.endCursor == null
+            ? Effect.succeed(null)
+            : open(options.endCursor),
+      });
       const cursorSchema = QueryStreamCursor.fromKeyLayout(self.keyLayout);
       const encodeCursor = Schema.encodeEffect(cursorSchema);
       const decodeCursor = Schema.decodeEffect(cursorSchema);
@@ -2320,7 +2640,7 @@ export const paginate: {
           identity,
         );
       const decoded = yield* Effect.all({
-        start: Option.match(Option.fromNullOr(options.cursor), {
+        start: Option.match(Option.fromNullOr(opened.start), {
           onNone: () => Effect.succeed(QueryStreamPagination.Start.Beginning()),
           onSome: (cursor) =>
             Effect.map(decodeCursor(cursor), (key) =>
@@ -2330,7 +2650,7 @@ export const paginate: {
               }),
             ),
         }),
-        range: Option.match(Option.fromNullishOr(options.endCursor), {
+        range: Option.match(Option.fromNullishOr(opened.end), {
           onNone: () => Effect.succeed(QueryStreamPagination.Range.Unpinned()),
           onSome: (cursor) =>
             cursor === QueryStreamCursor.END_CURSOR
@@ -2361,7 +2681,7 @@ export const paginate: {
         return {
           page: [],
           isDone: false,
-          continueCursor: request.cursor,
+          continueCursor: yield* seal(request.cursor),
         } satisfies PaginationResult<Doc>;
       }
       const start = Option.map(request.after, (key) => ({
@@ -2396,7 +2716,7 @@ export const paginate: {
           () => QueryStreamPagination.initial<Doc>(),
           (state) => state._tag === "Reading",
           (state, { doc, keyValues }: Element<Doc>) =>
-            Effect.map(readBudget.isExhausted, (hitLimit) =>
+            Effect.map(readBudget.isStopped, (hitLimit) =>
               QueryStreamPagination.record(
                 request,
                 state,
@@ -2414,7 +2734,10 @@ export const paginate: {
         return yield* new ReadBudgetExceededError(counts);
       }
       const encode = (key: QueryStreamKey.Complete) =>
-        encodeCursor(key).pipe(Effect.catchTag("SchemaError", Effect.die));
+        encodeCursor(key).pipe(
+          Effect.catchTag("SchemaError", Effect.die),
+          Effect.flatMap(seal),
+        );
       const encodeSplit = (
         result: Extract<
           QueryStreamPagination.Outcome<Doc>,
@@ -2424,7 +2747,7 @@ export const paginate: {
         Effect.gen(function* () {
           const continueCursor = yield* Match.value(result.continuation).pipe(
             Match.tagsExhaustive({
-              End: () => Effect.succeed(QueryStreamCursor.END_CURSOR),
+              End: () => seal(QueryStreamCursor.END_CURSOR),
               Key: ({ key }) => encode(key),
             }),
           );
@@ -2439,11 +2762,15 @@ export const paginate: {
       return yield* Match.value(outcome.success).pipe(
         Match.tagsExhaustive({
           Done: ({ page }) =>
-            Effect.succeed({
-              page: Array.fromIterable(page),
-              isDone: true,
-              continueCursor: QueryStreamCursor.END_CURSOR,
-            } satisfies PaginationResult<Doc>),
+            Effect.map(
+              seal(QueryStreamCursor.END_CURSOR),
+              (continueCursor) =>
+                ({
+                  page: Array.fromIterable(page),
+                  isDone: true,
+                  continueCursor,
+                }) satisfies PaginationResult<Doc>,
+            ),
           Continue: ({ page, key }) =>
             Effect.map(
               encode(key),
@@ -2463,7 +2790,10 @@ export const paginate: {
       Effect.provideServiceEffect(
         effect,
         QueryStreamReadBudget.QueryStreamReadBudget,
-        Schema.decodeEffect(QueryStreamReadBudget.Limits)(options).pipe(
+        Schema.decodeEffect(QueryStreamReadBudget.Limits)({
+          maximumRowsRead: DEFAULT_MAXIMUM_ROWS_READ,
+          ...options,
+        }).pipe(
           Effect.catchTag("SchemaError", (cause) =>
             Effect.die(
               new QueryStreamReadBudget.InvalidReadLimitError({ cause }),

package/src/QueryStreamReadBudget.ts

@@ -22,8 +22,9 @@ export interface QueryStreamReadBudget {
   readonly getReadCounts: Effect.Effect<ReadCounts>;
   /**
    * Returns a stream that records reads against this budget and stops
-   * requesting further batches once exhausted. Apply directly to the document
-   * source before buffering, filtering, or combining its output.
+   * requesting further batches once exhausted, except for one limit-boundary
+   * lookahead to detect completion. Apply directly to the document source
+   * before buffering, filtering, or combining its output.
    */
   readonly accountFor: (
     encodedDocuments: Stream.Stream<unknown>,
@@ -133,10 +134,22 @@ export const make = Effect.fnUntraced(function* (
         SynchronizedRef.modifyEffect(stateRef, (state) =>
           Effect.gen(function* () {
             if (isExhausted(state, limits)) {
-              return Tuple.make(
-                Option.none(),
-                State.Stopped(readCounts(state)),
-              );
+              const canProbeEnd =
+                State.$is("Active")(state) &&
+                !Option.exists(
+                  limits.maximumRowsRead,
+                  (limit) => state.rowsRead > limit,
+                ) &&
+                !Option.exists(
+                  limits.maximumBytesRead,
+                  (limit) => state.bytesRead > limit,
+                );
+              // Iterators expose completion only through a pull. Count a
+              // lookahead row, but never publish it beyond either limit.
+              const counts = canProbeEnd
+                ? record(state, yield* pull)
+                : readCounts(state);
+              return Tuple.make(Option.none(), State.Stopped(counts));
             }
             const documents = yield* pull;
             return Tuple.make(