1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
//! Caller-authored SQL sources for the explicit multi-request pager.
//!
//! A [`SqlPageSource`] owns an exclusive DBAPI [`Session`] and a caller's [`SqlPagePlan`]. It
//! requests one page at a time, applies the plan's typed parameters, and publishes rows only after
//! the complete single-result-set request has finished. It does not rewrite SQL, classify a
//! statement as read-only, infer a continuation, retry, replay, prefetch, or create a task.
//!
//! The caller supplies:
//!
//! - the complete provider-specific statement, with its native placeholders;
//! - the typed parameters for each request, including the requested row limit;
//! - the continuation token and its scope, tenant binding, expiry, and validation;
//! - the [`SqlPageAssertion`] that the statement is read-only, replay-safe, and authorized.
//!
//! The adapter computes an effective page size of `min(page_size, remaining_rows)`, asks for exactly
//! one extra lookahead row, applies a hard [`RowLimit`] covering those rows and a caller-supplied
//! portable byte allowance, removes the lookahead before publication, and rejects a page whose
//! continuation state disagrees with the lookahead. The pager still enforces the aggregate
//! [`PageBudget`](super::PageBudget) and page size.
//!
//! # Provider SQL
//!
//! Nothing here rewrites the statement. The plan must author the provider's own form, for example:
//!
//! ```sql
//! -- SQLite and libSQL
//! SELECT tenant, seq, body FROM events
//! WHERE (tenant, seq) > (?, ?) ORDER BY tenant, seq LIMIT ?;
//!
//! -- PostgreSQL
//! SELECT tenant, seq, body FROM events
//! WHERE (tenant, seq) > ($1, $2) ORDER BY tenant, seq LIMIT $3;
//!
//! -- MySQL and MariaDB
//! SELECT tenant, seq, body FROM events
//! WHERE (tenant, seq) > (?, ?) ORDER BY tenant, seq LIMIT ?;
//!
//! -- SQL Server (row-value comparison is not available; expand the keyset predicate)
//! SELECT TOP (@P3) tenant, seq, body FROM events
//! WHERE tenant > @P1 OR (tenant = @P1 AND seq > @P2) ORDER BY tenant, seq;
//!
//! -- ClickHouse 24.8
//! SELECT tenant, seq, body FROM events
//! WHERE (tenant, seq) > ({p1:Int64}, {p2:Int64})
//! ORDER BY tenant, seq LIMIT {p3:Int64};
//! ```
//!
//! These are placeholder-shape examples, not live conformance claims. Only the SQLite form is
//! exercised against a real server in this tree; the other providers may have different ordering,
//! limit, or type requirements that the caller must confirm for its schema.
//!
//! # Bounds, completion, and replay
//!
//! The plan must return at most `lookahead` rows in a total order. The adapter passes the same
//! count to the plan so it can bind a provider `LIMIT`/`TOP`/native limit parameter. `source_bytes`
//! is a separate allowance for the portable [`Row::encoded_bytes`] total of the rows accepted for
//! one request, including the lookahead row. It is not a provider allocation, buffering, or
//! driver-overhead bound; a provider that does not enforce `RowLimit` may materialize more before
//! the adapter's post-check.
//!
//! The adapter rejects an additional result set, a later statement error, and a continuation that
//! disagrees with the lookahead before publishing the page. The `Reader` contract has no observable
//! "zero result sets" state: a no-row batch is one empty set. The caller must dispatch a
//! single-result-set statement; `read_single_set` cannot prove that a provider sent zero sets. It
//! does not promise a snapshot or distributed consistency across requests.
//!
//! # Retry and cancellation
//!
//! Direct [`Session::fetch_async`] operations do not retry. The adapter rejects an explicit enabled
//! `RetrySetting::Use(RetryPolicy::Enabled { .. })` override or a retry runtime in the plan's
//! options with [`ErrorKind::Unsupported`]. `RetrySetting::Off` is accepted, and every request is
//! set to `RetrySetting::Off`; a disabled `Use` override is also accepted and normalized to `Off`.
//! A page request is terminal on error. Dropping the page future or the containing stream is not
//! proof that a statement did not write; the assertion is the caller's, and the adapter cannot
//! verify it.
use fmt;
use ;
use crate::;
/// The caller's explicit paging-safety assertion.
///
/// Constructing this value is the assertion; the adapter cannot verify it. The caller asserts that
/// every request the plan can issue is one caller-authored read-only statement, that repeating it is
/// safe, and that the caller is authorized for every tenant or row scope the statement can reach.
/// Binding an authorization predicate separately from the cursor remains the plan's responsibility.
/// A caller-owned plan for one provider-specific SQL page request.
///
/// The plan owns SQL, parameters, keyset or offset logic, and continuation validation. The adapter
/// calls it only when a page is requested and never retries or replays a failed call.
///
/// # Statement
///
/// [`SqlPagePlan::sql`] is captured once when the source is constructed. It must be the complete
/// native statement; the adapter never appends, rewrites, or classifies it. It must be a
/// single-result-set statement: the `Reader` contract reports a no-row batch as one empty set, so
/// the adapter cannot prove that a provider sent zero sets.
///
/// # Bounds
///
/// [`SqlPagePlan::options`] receives the effective lookahead count
/// (`min(page_size, remaining_rows) + 1`). The statement must return no more than that many rows in a
/// total order. The adapter replaces the fetch limit with its own hard [`RowLimit`], so a plan that
/// sets a limit is rejected rather than silently overridden.
///
/// # Continuation
///
/// [`SqlPagePlan::next_continuation`] must return `Some` exactly when the lookahead row exists. A
/// continuation belongs to the plan: it must reject tokens it did not issue, a token for another
/// query, and a cursor outside its authorized tenant. The adapter passes the token back unchanged
/// and never prints it.
/// A [`PageSource`] over a caller-authored SQL statement and an exclusive session.
///
/// The session may borrow caller state for `'session`; the source does not require `'static`.
/// See the [module documentation](self) for the plan obligations, bounds, and no-retry behavior.