[Kernel] [Pagination] New Pagination API (delta-io#4836)

## 🥞 Stacked PR
Use this [link](https://github.com/delta-io/delta/pull/4836/files) to
review incremental changes.
-
[**stack/pagination-api**](delta-io#4836)
[[Files changed](https://github.com/delta-io/delta/pull/4836/files)]
- [stack/read-page1](delta-io#4837)
[[Files
changed](https://github.com/delta-io/delta/pull/4837/files/9d95b4dc82006d2883eb11cee98caeb6899aa4e1..ab5ebd100df54e220cabfbc89eb94a520f3c2db3)]
- [stack/skipJSON](delta-io#4844) [[Files
changed](https://github.com/delta-io/delta/pull/4844/files/ab5ebd100df54e220cabfbc89eb94a520f3c2db3..971a98d84f12031099aa35a77e39a8e87a69b05f)]
- [stack/multi-CP](delta-io#4845) [[Files
changed](https://github.com/delta-io/delta/pull/4845/files/971a98d84f12031099aa35a77e39a8e87a69b05f..40c4d7d7e0924a7d8225b6a44db7ddbf60b70de6)]
- [stack/sidecar](delta-io#4846) [[Files
changed](https://github.com/delta-io/delta/pull/4846/files/40c4d7d7e0924a7d8225b6a44db7ddbf60b70de6..8cbb470df1ab57e1fd8c95c3ecd4c9f0db466390)]

---------
<!--
Thanks for sending a pull request!  Here are some tips for you:
1. If this is your first time, please read our contributor guidelines:
https://github.com/delta-io/delta/blob/master/CONTRIBUTING.md
2. If the PR is unfinished, add '[WIP]' in your PR title, e.g., '[WIP]
Your PR title ...'.
  3. Be sure to keep the PR description updated to reflect all changes.
  4. Please write your PR title to summarize what this PR proposes.
5. If possible, provide a concise example to reproduce the issue for a
faster review.
6. If applicable, include the corresponding issue number in the PR title
and link it in the body.
-->

#### Which Delta project/connector is this regarding?
<!--
Please add the component selected below to the beginning of the pull
request title
For example: [Spark] Title of my pull request
-->

- [ ] Spark
- [ ] Standalone
- [ ] Flink
- [x] Kernel
- [ ] Other (fill in here)

## Description

<!--
- Describe what this PR changes.
- Describe why we need the change.
 
If this PR resolves an issue be sure to include "Resolves #XXX" to
correctly link and close the issue upon merge.
-->
This PR introduces new API for Kernel Pagination Support.

## How was this patch tested?

<!--
If tests were added, say they were added here. Please make sure to test
the changes thoroughly including negative and positive cases if
possible.
If the changes were tested in any way other than unit tests, please
clarify how you tested step by step (ideally copy and paste-able, so
that other reviewers can test and check, and descendants can verify in
the future).
If the changes were not tested, please explain why.
-->
No implementation yet, no tests. 

## Does this PR introduce _any_ user-facing changes?

<!--
If yes, please clarify the previous behavior and the change this PR
proposes - provide the console output, description and/or an example to
show the behavior difference if possible.
If possible, please also clarify if this is a user-facing change
compared to the released Delta Lake versions or within the unreleased
branches such as master.
If no, write 'No'.
-->
Yes.

Author: mmmyr

kernel/kernel-api/src/main/java/io/delta/kernel/PaginatedScan.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (2025) The Delta Lake Project Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.delta.kernel;
+
+import io.delta.kernel.data.FilteredColumnarBatch;
+import io.delta.kernel.engine.Engine;
+
+/**
+ * Extension of {@link Scan} that supports pagination.
+ *
+ * <p>This interface allows consumers to retrieve scan results in discrete, ordered pages rather
+ * than all at once. This is particularly useful for large datasets where materializing the full
+ * result set would be expensive in terms of memory or compute resources.
+ *
+ * <p>Pagination is achieved via a combination of {@code pageSize} and {@code pageToken}. The {@code
+ * pageSize} controls how many Scan files are returned in each page, while the {@code pageToken}
+ * encodes the location of next batch to read and is used to resume the scan from exactly where the
+ * last page ended. For the first page, the {@code pageToken} should be {@code Optional.empty()}.
+ *
+ * <p>Consumers typically use {@link PaginatedScan} in a loop: they call {@code getScanFiles()} to
+ * retrieve an iterator over the current page's scan files. After consuming the iterator, users
+ * should call {@link PaginatedScanFilesIterator#getCurrentPageToken} to retrieve a token to pass
+ * into the next page request. This allows users to scan the dataset incrementally, resuming from
+ * where they left off.
+ */
+public interface PaginatedScan extends Scan {
+
+  /**
+   * Get a paginated iterator of Scan files for the current page.
+   *
+   * @param engine {@link Engine} instance to use in Delta Kernel.
+   * @return iterator of {@link FilteredColumnarBatch}s for the current page.
+   */
+  @Override
+  PaginatedScanFilesIterator getScanFiles(Engine engine);
+}

kernel/kernel-api/src/main/java/io/delta/kernel/PaginatedScanFilesIterator.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (2025) The Delta Lake Project Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.delta.kernel;
+
+import io.delta.kernel.data.FilteredColumnarBatch;
+import io.delta.kernel.data.Row;
+import io.delta.kernel.utils.CloseableIterator;
+
+/**
+ * An iterator over {@link FilteredColumnarBatch}, each representing a batch of Scan Files in a
+ * paginated scan. This iterator also exposes the page token that can be used to resume the scan
+ * from the exact position current page ends in a subsequent request.
+ *
+ * <p>This interface extends {@link CloseableIterator} and should be closed when the iteration is
+ * complete.
+ */
+public interface PaginatedScanFilesIterator extends CloseableIterator<FilteredColumnarBatch> {
+  /**
+   * Returns a page token representing the starting position of next page. This token is used to
+   * resume the scan from the exact position current page ends in a subsequent request. Page token
+   * also contains metadata for validation purpose, such as detecting changes in query parameters or
+   * the underlying log files.
+   *
+   * <p>The page token represents the position of current iterator at the time it's called. If the
+   * iterator is only partially consumed, the returned token will always point to the beginning of
+   * the next unconsumed {@link FilteredColumnarBatch}. This method will return Option.empty() if
+   * all data in the Scan is consumed (no more non-empty pages remain).
+   */
+  Row getCurrentPageToken();
+}

kernel/kernel-api/src/main/java/io/delta/kernel/ScanBuilder.java

@@ -17,9 +17,11 @@
 package io.delta.kernel;
 
 import io.delta.kernel.annotation.Evolving;
+import io.delta.kernel.data.Row;
 import io.delta.kernel.engine.Engine;
 import io.delta.kernel.expressions.Predicate;
 import io.delta.kernel.types.StructType;
+import java.util.Optional;
 
 /**
  * Builder to construct {@link Scan} object.
@@ -65,4 +67,14 @@ public interface ScanBuilder {
 
   /** @return Build the {@link Scan instance} */
   Scan build();
+
+  /**
+   * Build a Paginated Scan with a required page size and an optional page token.
+   *
+   * @param pageSize Maximum number of Scan Files to return in this page.
+   * @param pageToken Optional page token representing the current scan position; empty to start
+   *     from the beginning.
+   * @return A {@link PaginatedScan} configured for pagination.
+   */
+  PaginatedScan buildPaginated(long pageSize, Optional<Row> pageToken);
 }

kernel/kernel-api/src/main/java/io/delta/kernel/internal/ScanBuilderImpl.java

@@ -16,8 +16,10 @@
 
 package io.delta.kernel.internal;
 
+import io.delta.kernel.PaginatedScan;
 import io.delta.kernel.Scan;
 import io.delta.kernel.ScanBuilder;
+import io.delta.kernel.data.Row;
 import io.delta.kernel.expressions.Predicate;
 import io.delta.kernel.internal.actions.Metadata;
 import io.delta.kernel.internal.actions.Protocol;
@@ -85,4 +87,9 @@ public Scan build() {
         dataPath,
         snapshotReport);
   }
+
+  @Override
+  public PaginatedScan buildPaginated(long pageSize, Optional<Row> pageToken) {
+    throw new UnsupportedOperationException("not implemented");
+  }
 }