@rebasepro/client 0.13.1-canary.gf57a27e → 0.14.0

package/dist/offline-connectivity.d.ts

@@ -12,6 +12,13 @@
  */
 /** The request never reached the server, so nothing was decided by it. */
 export declare function isNetworkError(error: unknown): boolean;
+/**
+ * Is the server still answering an earlier attempt of this same write?
+ *
+ * The only correct response is to ask again — which is exactly what the
+ * server's own message says, and exactly what this SDK used not to do.
+ */
+export declare function isIdempotencyInProgressError(error: unknown): boolean;
 /** Is this failure worth another attempt later? */
 export declare function isRetryableError(error: unknown): boolean;
 /**
@@ -24,6 +31,11 @@ export declare function isRetryableError(error: unknown): boolean;
  * The queue uses this to recognise its own earlier attempt. A create whose
  * response was lost is replayed, and for a row carrying an id the SDK generated
  * the server can only be rejecting it because the first attempt actually landed.
+ *
+ * Which is why the status alone cannot decide it: `IDEMPOTENCY_KEY_IN_PROGRESS`
+ * is a 409 that means the opposite — the row may not exist at all. Read as a
+ * duplicate, the queue looked for a row that was never written, found nothing,
+ * concluded there was nothing left to do and deleted the write from the queue.
  */
 export declare function isDuplicateKeyError(error: unknown): boolean;
 export interface ConnectivityOptions {

package/dist/offline-query.d.ts

@@ -60,7 +60,48 @@ export declare function resolvePagination(params?: FindParams): {
  * `include` pulls in rows from other collections that this evaluator never
  * sees, and `searchString` is only approximated — both make the local answer a
  * best effort rather than an equivalent one.
+ *
+ * **Ordering comparisons are refused, and that is the interesting one.**
+ * `compareValues` falls back to an `Intl.Collator` for operands it cannot read
+ * as numbers or instants. PostgreSQL orders text by the *database's* collation,
+ * which is a property of the server this process has never been told: under the
+ * C collation `'apple' < 'Banana'` is false, under `en_US.UTF-8` it is true,
+ * and the collator says true. So `["<", "Banana"]` selects a different set here
+ * than it does there — silently, and in whichever direction the deployment
+ * happens to have been created.
+ *
+ * The refusal covers *every* ordering comparison rather than only the ones with
+ * a string operand, because the operand type does not settle it: a numeric
+ * bound against a text column (`["<", 10]` on a `varchar`) also reaches the
+ * collator, and nothing in `params` says what the column holds. Conservative on
+ * purpose — the cost is that a query combining an ordering filter with
+ * *unsynced local writes* stops placing those writes optimistically, which is a
+ * degraded answer rather than a wrong one. Claiming exactness we do not have is
+ * the other way round.
+ *
+ * This says nothing about ordering *results*; that is a separate claim with a
+ * separate answer, because a sort changes which rows come first and not which
+ * rows match. See {@link isLocallySortable}.
  */
 export declare function isExactlyEvaluable(params?: FindParams): boolean;
+/**
+ * Would sorting `rows` locally reproduce the order the server would have sent?
+ *
+ * Asked of the rows rather than of the query, because unlike a filter this one
+ * *is* decidable from the data in hand: {@link compareValues} reaches the
+ * collator only when it cannot read both operands as numbers, and `toComparable`
+ * has already turned dates and relations into numbers and ids by then. If every
+ * value on the sort column normalises to a number, the collator is unreachable
+ * and the local order is the server's order.
+ *
+ * A text column is therefore refused — see {@link isExactlyEvaluable} for why
+ * the two cannot be made to agree — and so is a column this page happens to see
+ * only as strings, which is the same thing from here.
+ *
+ * Nulls are fine either way: they are ordered by an explicit rule (last
+ * ascending, first descending) that matches Postgres and never reaches the
+ * comparator.
+ */
+export declare function isLocallySortable(rows: readonly Record<string, unknown>[], orderBy?: OrderByTuple): boolean;
 /** Run a full query — filter, sort, paginate — over a set of rows. */
 export declare function runLocalQuery<M extends Record<string, unknown>>(rows: M[], params?: FindParams): FindResult<M>;

package/dist/query-contract.types.d.ts

@@ -23,7 +23,7 @@
  * generated SDK — where `M` is a concrete row type — the documented call was a
  * compile error. Nothing in this repo noticed; a downstream application did.
  */
-import type { FindParams, FindResult, SDKQueryBuilderInterface } from "@rebasepro/types";
+import type { FindParams, FindResult, SDKQueryBuilderInterface, WhereFilterOp } from "@rebasepro/types";
 /**
  * A row shaped the way a **generated** SDK shapes one: a type alias with a
  * finite key set.
@@ -42,6 +42,20 @@ type ContractRow = {
     id: string;
     title: string;
     created_at: string;
+    /** An `array` property, which codegen emits as `Array<X>`. */
+    tags: string[];
+    age: number;
+    deleted_at: string | null;
+};
+/** A to-many relation, which codegen emits as `Array<TargetRow>`. */
+type TagRow = {
+    id: string;
+    label: string;
+};
+type PostRow = {
+    id: string;
+    title: string;
+    tags: TagRow[];
 };
 /** The documented relevance sort must compile. */
 export declare const orderByScore: FindParams<ContractRow>;
@@ -58,6 +72,52 @@ export declare const fluentColumn: (qb: SDKQueryBuilderInterface<ContractRow>) =
 export declare const fluentTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
 /** Vector search must be reachable from the builder, and chain. */
 export declare const fluentVector: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/**
+ * `array-contains` takes an **element** of the column, not the column.
+ *
+ * This was the second `_score`: documented in `docs/sdk/querying.md`, accepted
+ * by the runtime, and a compile error on a generated SDK — because
+ * `WhereValue<T> = T | T[] | null` was one value type for all sixteen
+ * operators, so on `tags: string[]` it wanted a `string[]`. The spelling that
+ * did compile, `["featured"]`, builds `@> ARRAY[$1]` with the whole array bound
+ * as the single element and matches nothing, forever, with no error anywhere.
+ */
+export declare const fluentArrayContains: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentArrayContainsWrapped: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/**
+ * Same defect, and the case the relation compiler was specifically built for:
+ * a to-many relation is emitted as `Array<TargetRow>`, and the compiler answers
+ * `array-contains` on it by comparing **ids**. So the id must be accepted even
+ * though it is not the element type.
+ */
+export declare const fluentRelationContains: (qb: SDKQueryBuilderInterface<PostRow>, tagId: string) => SDKQueryBuilderInterface<PostRow>;
+export declare const fluentRelationIn: (qb: SDKQueryBuilderInterface<PostRow>, tagIds: string[]) => SDKQueryBuilderInterface<PostRow>;
+export declare const fluentRelationTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
+/** The list operators take a list of elements — or one, read as a one-element list. */
+export declare const fluentInList: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentInScalar: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentInNested: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/** A comparison takes one value. `eq(column, ["a","b"])` is not a query anyone meant. */
+export declare const fluentEqArray: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/**
+ * A pattern is a string on every column type. The driver casts, so refusing
+ * `"%3%"` on a numeric column was the type being stricter than the runtime.
+ */
+export declare const fluentLikeOnNumber: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/** The null operators ignore their value; `null` is the conventional spelling. */
+export declare const fluentIsNull: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/**
+ * A caller holding an unnarrowed operator — a dynamic filter UI — must keep
+ * compiling. `WhereValueFor` distributes over the operator, so this is the
+ * union of every branch rather than a `never`.
+ */
+export declare const fluentDynamicOp: (qb: SDKQueryBuilderInterface<ContractRow>, op: WhereFilterOp) => SDKQueryBuilderInterface<ContractRow>;
+/** Two conditions on one column: the shape the Mongo compiler used to drop. */
+export declare const fluentRange: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/** The object form must accept exactly what the fluent form accepts. */
+export declare const paramsArrayContains: FindParams<ContractRow>;
+/** …and the array-of-tuples form the builder produces from two `.where()` calls. */
+export declare const paramsRange: FindParams<ContractRow>;
 /**
  * Sorting by relevance and then being unable to read it was the other half of
  * the same bug — the e2e cast around it, which should have been the tell.

package/dist/sdk_query_builder.d.ts

@@ -1,4 +1,4 @@
-import { FindResult, LogicalCondition, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValue, type ComputedSortField } from "@rebasepro/types";
+import { FindResult, LogicalCondition, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValueFor, type ComputedSortField } from "@rebasepro/types";
 /**
  * SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
  * Entity-wrapped results (`FindResponse<M>`).
@@ -21,7 +21,7 @@ export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<
      * @example
      * client.data.users.where('age', '>=', 18).find()
      */
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     /**
      * Order the results by a specific column.

package/dist/websocket.d.ts

@@ -13,9 +13,11 @@ export interface RebaseWebSocketConfig {
  *
  * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
  * manages this internally (exposed as `client.ws`, typed by the minimal
- * `RebaseWebSocket` contract in `@rebasepro/types`). It is re-exported from the
- * package root only because the `@rebasepro/client-postgres` driver
- * instantiates it directly; its surface may change without a major bump.
+ * `RebaseWebSocket` contract in `@rebasepro/types`). It stays exported from the
+ * package root for the same reason it always was — a data-source driver may
+ * instantiate it directly — but nothing in this repo does since
+ * `@rebasepro/client-postgres` was removed; its surface may change without a
+ * major bump.
  */
 export declare class RebaseWebSocketClient {
     private websocketUrl;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.13.1-canary.gf57a27e",
+  "version": "0.14.0",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,9 +29,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/common": "0.13.1-canary.gf57a27e",
-    "@rebasepro/utils": "0.13.1-canary.gf57a27e",
-    "@rebasepro/types": "0.13.1-canary.gf57a27e"
+    "@rebasepro/types": "0.14.0",
+    "@rebasepro/common": "0.14.0",
+    "@rebasepro/utils": "0.14.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/collection.ts

@@ -8,7 +8,7 @@ import {
     SDKCollectionClient,
     SDKQueryBuilderInterface,
     WhereFilterOp,
-    WhereValue,
+    WhereValueFor,
     WriteOptions,
     type ComputedSortField
 } from "@rebasepro/types";
@@ -381,7 +381,7 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
             if (typeof columnOrCondition === "object") {
                 return builder.where(columnOrCondition);
             }
-            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValue<M[keyof M & string]>);
+            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValueFor<WhereFilterOp, M[keyof M & string]>);
         },
         orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc") {
             return new SDKQueryBuilder<M>(client).orderBy(column, direction);

package/src/index.ts

@@ -85,8 +85,8 @@ export type {
 export type { FunctionInvokeOptions, FunctionsClient } from "./functions";
 
 // Realtime: the WebSocket client class is internal to `createRebaseClient()`,
-// but re-exported (see @internal on the class) because the `client-postgres`
-// driver constructs it directly. Not a stable app-facing API.
+// but re-exported (see @internal on the class) so a data-source driver can
+// construct it directly. Not a stable app-facing API.
 export { RebaseWebSocketClient } from "./websocket";
 export { RebaseRealtimeChannel } from "./realtime-channel";
 export type {

package/src/offline-connectivity.test.ts

@@ -1,4 +1,9 @@
-import { ConnectivityMonitor, isNetworkError, isRetryableError } from "./offline-connectivity";
+import {
+    ConnectivityMonitor,
+    isDuplicateKeyError,
+    isNetworkError,
+    isRetryableError
+} from "./offline-connectivity";
 import { RebaseApiError } from "./transport";
 
 /**
@@ -35,6 +40,35 @@ describe("network error classification", () => {
         // blip, and retrying it forever jams every write queued behind it.
         expect(isRetryableError(new RebaseApiError("boom", { status: 500 }))).toBe(false);
     });
+
+    it("retries a write the server is still answering, and only that 409", () => {
+        // The server's own message says to retry — "its result will be
+        // replayed" — and a key whose claim outlived the process that took it
+        // is refused until the lease expires. Giving up instead rolls back a
+        // write that retrying would have completed.
+        expect(isRetryableError(new RebaseApiError("in progress", {
+            status: 409, code: "IDEMPOTENCY_KEY_IN_PROGRESS"
+        }))).toBe(true);
+        // Every other 409 is a real conflict and stays fatal.
+        expect(isRetryableError(new RebaseApiError("row exists", { status: 409, code: "23505" }))).toBe(false);
+        expect(isRetryableError(new RebaseApiError("conflict", { status: 409 }))).toBe(false);
+        expect(isRetryableError(new RebaseApiError("reused", {
+            status: 422, code: "IDEMPOTENCY_KEY_REUSED"
+        }))).toBe(false);
+    });
+
+    it("does not read an unanswered write as a row that is already there", () => {
+        // The status alone cannot decide it. Read as a duplicate, the queue
+        // went looking for a row that was never written, found nothing,
+        // concluded there was nothing left to do and deleted the write.
+        expect(isDuplicateKeyError(new RebaseApiError("in progress", {
+            status: 409, code: "IDEMPOTENCY_KEY_IN_PROGRESS"
+        }))).toBe(false);
+
+        expect(isDuplicateKeyError(new RebaseApiError("dup", { status: 400, code: "23505" }))).toBe(true);
+        expect(isDuplicateKeyError(new RebaseApiError("conflict", { status: 409 }))).toBe(true);
+        expect(isDuplicateKeyError(new RebaseApiError("gone", { status: 404 }))).toBe(false);
+    });
 });
 
 describe("ConnectivityMonitor", () => {

package/src/offline-connectivity.ts

@@ -38,11 +38,37 @@ export function isNetworkError(error: unknown): boolean {
  */
 const RETRYABLE_STATUSES = new Set([408, 425, 429, 502, 503, 504]);
 
+/**
+ * The server holds this key for a request it has not answered yet.
+ *
+ * It is a 409 like a duplicate row is a 409, and nothing but the code separates
+ * them — one means "your write is already there", the other means "your write
+ * may not have happened at all, ask again".
+ */
+const IDEMPOTENCY_IN_PROGRESS = "IDEMPOTENCY_KEY_IN_PROGRESS";
+
+/**
+ * Is the server still answering an earlier attempt of this same write?
+ *
+ * The only correct response is to ask again — which is exactly what the
+ * server's own message says, and exactly what this SDK used not to do.
+ */
+export function isIdempotencyInProgressError(error: unknown): boolean {
+    return error instanceof RebaseApiError
+        && error.status === 409
+        && error.code === IDEMPOTENCY_IN_PROGRESS;
+}
+
 /** Is this failure worth another attempt later? */
 export function isRetryableError(error: unknown): boolean {
     if (isNetworkError(error)) return true;
-    if (error instanceof RebaseApiError) return error.status !== undefined && RETRYABLE_STATUSES.has(error.status);
-    return false;
+    if (!(error instanceof RebaseApiError)) return false;
+    // The one 409 that resolves on its own. A key whose claim outlived the
+    // request that took it — the process was killed between the write and the
+    // answer — is refused until the claim's lease expires, and giving up on it
+    // means dropping a write that retrying would have completed.
+    if (isIdempotencyInProgressError(error)) return true;
+    return error.status !== undefined && RETRYABLE_STATUSES.has(error.status);
 }
 
 /**
@@ -55,10 +81,16 @@ export function isRetryableError(error: unknown): boolean {
  * The queue uses this to recognise its own earlier attempt. A create whose
  * response was lost is replayed, and for a row carrying an id the SDK generated
  * the server can only be rejecting it because the first attempt actually landed.
+ *
+ * Which is why the status alone cannot decide it: `IDEMPOTENCY_KEY_IN_PROGRESS`
+ * is a 409 that means the opposite — the row may not exist at all. Read as a
+ * duplicate, the queue looked for a row that was never written, found nothing,
+ * concluded there was nothing left to do and deleted the write from the queue.
  */
 export function isDuplicateKeyError(error: unknown): boolean {
     if (!(error instanceof RebaseApiError)) return false;
-    return error.code === "23505" || error.status === 409;
+    if (error.code === "23505") return true;
+    return error.status === 409 && !isIdempotencyInProgressError(error);
 }
 
 export interface ConnectivityOptions {

package/src/offline-query.test.ts

@@ -1,6 +1,7 @@
 import {
     compareValues,
     isExactlyEvaluable,
+    isLocallySortable,
     looseEquals,
     matchesLogical,
     matchesOperator,
@@ -255,6 +256,93 @@ describe("local query engine", () => {
             expect(isExactlyEvaluable({ include: ["author"] })).toBe(false);
             expect(isExactlyEvaluable({ include: [] })).toBe(true);
         });
+
+        /**
+         * An ordering comparison is answered here by `compareValues`, which
+         * falls back to an `Intl.Collator`, and by Postgres using the
+         * *database's* collation — a property of the server this process has
+         * never been told. `'apple' < 'Banana'` is false under the C collation
+         * and true under `en_US.UTF-8`; the collator says true. So the two
+         * select different sets, in whichever direction the deployment happened
+         * to be created.
+         */
+        it("refuses an ordering comparison, whose answer depends on the server's collation", () => {
+            for (const op of ["<", "<=", ">", ">="] as const) {
+                expect({ op, exact: isExactlyEvaluable({ where: { name: [op, "Banana"] } }) })
+                    .toEqual({ op, exact: false });
+            }
+            // Equality, membership and pattern matching are unaffected — all
+            // verified against a real database in
+            // `server-postgres/test/e2e/offline-query-agreement.test.ts`.
+            for (const op of ["==", "!=", "in", "not-in", "like", "ilike"] as const) {
+                expect({ op, exact: isExactlyEvaluable({ where: { name: [op, "x"] } }) })
+                    .toEqual({ op, exact: true });
+            }
+            expect(isExactlyEvaluable({ where: { a: ["is-null", null] } })).toBe(true);
+        });
+
+        it("refuses a numeric range too, because the operand type does not settle it", () => {
+            // `compareValues` deliberately reads numeric strings as numbers, so
+            // it cannot tell an integer column from a text column of digits —
+            // and on the latter Postgres orders "10" before "9" while this
+            // orders 9 before 10. Conservative on purpose; the schema would be
+            // needed to do better.
+            expect(isExactlyEvaluable({ where: { qty: [">", 10] } })).toBe(false);
+        });
+
+        it("looks inside and/or groups, not just the top-level where", () => {
+            expect(isExactlyEvaluable({
+                logical: { type: "or", conditions: [
+                    { column: "a", operator: "==", value: 1 },
+                    { column: "b", operator: "==", value: 2 }
+                ] }
+            } as never)).toBe(true);
+            expect(isExactlyEvaluable({
+                logical: { type: "or", conditions: [
+                    { column: "a", operator: "==", value: 1 },
+                    { type: "and", conditions: [{ column: "b", operator: "<", value: "m" }] }
+                ] }
+            } as never)).toBe(false);
+        });
+
+        it("still refuses several conditions on one field when any of them orders", () => {
+            expect(isExactlyEvaluable({ where: { a: [["==", 1], ["<", "m"]] } } as never)).toBe(false);
+            expect(isExactlyEvaluable({ where: { a: [["==", 1], ["!=", 2]] } } as never)).toBe(true);
+        });
+    });
+
+    describe("isLocallySortable", () => {
+        /**
+         * Asked of the rows rather than the query, because unlike a filter this
+         * one is decidable from the data in hand: the collator is reachable
+         * only when a value cannot be read as a number.
+         */
+        it("accepts a column this page holds only as numbers", () => {
+            expect(isLocallySortable([{ id: 1, n: 3 }, { id: 2, n: 10 }], ["n", "asc"])).toBe(true);
+            // The wire's type erasure is already undone by `compareValues`.
+            expect(isLocallySortable([{ id: 1, n: "3" }, { id: 2, n: "10" }], ["n", "asc"])).toBe(true);
+            // Dates normalise to instants before any comparison happens.
+            expect(isLocallySortable(
+                [{ id: 1, at: new Date(1) }, { id: 2, at: new Date(2) }], ["at", "desc"]
+            )).toBe(true);
+        });
+
+        it("refuses a column holding text, whose order is the database's to decide", () => {
+            expect(isLocallySortable([{ id: 1, name: "apple" }, { id: 2, name: "Banana" }], ["name", "asc"]))
+                .toBe(false);
+            // One text value is enough — a column is one type, and the page that
+            // happens to be cached does not get to vote.
+            expect(isLocallySortable([{ id: 1, n: 3 }, { id: 2, n: "x" }], ["n", "asc"])).toBe(false);
+        });
+
+        it("ignores nulls, which are ordered by an explicit rule", () => {
+            expect(isLocallySortable([{ id: 1, n: null }, { id: 2, n: 5 }], ["n", "asc"])).toBe(true);
+            expect(isLocallySortable([{ id: 1 }, { id: 2 }], ["missing", "asc"])).toBe(true);
+        });
+
+        it("is vacuously true with no sort", () => {
+            expect(isLocallySortable([{ id: 1, name: "a" }], undefined)).toBe(true);
+        });
     });
 
     describe("primitives", () => {

package/src/offline-query.ts

@@ -347,6 +347,28 @@ export function resolvePagination(params?: FindParams): { limit: number; offset:
     return { limit, offset };
 }
 
+/** `<`, `<=`, `>`, `>=` — the operators whose answer depends on a collation. */
+const ORDERING_OPS = new Set<WhereFilterOp>(["<", "<=", ">", ">="]);
+
+/** Does any condition in this `where` clause order its operands? */
+function whereOrders(where: FilterValues<string> | undefined): boolean {
+    if (!where) return false;
+    for (const condition of Object.values(where)) {
+        const tuples = isTuple(condition) ? [condition] : (condition as unknown[]).filter(isTuple);
+        if (tuples.some(([op]) => ORDERING_OPS.has(op))) return true;
+    }
+    return false;
+}
+
+/** The same question, through an `and(...)`/`or(...)` tree. */
+function logicalOrders(condition: LogicalCondition | FilterCondition | undefined, depth = 0): boolean {
+    if (!condition || depth > 32) return false;
+    if ("type" in condition) {
+        return (condition.conditions ?? []).some((c) => logicalOrders(c, depth + 1));
+    }
+    return ORDERING_OPS.has(condition.operator);
+}
+
 /**
  * Can a locally evaluated answer to `params` be trusted to match the server's,
  * assuming the cache holds every row of the collection?
@@ -354,6 +376,28 @@ export function resolvePagination(params?: FindParams): { limit: number; offset:
  * `include` pulls in rows from other collections that this evaluator never
  * sees, and `searchString` is only approximated — both make the local answer a
  * best effort rather than an equivalent one.
+ *
+ * **Ordering comparisons are refused, and that is the interesting one.**
+ * `compareValues` falls back to an `Intl.Collator` for operands it cannot read
+ * as numbers or instants. PostgreSQL orders text by the *database's* collation,
+ * which is a property of the server this process has never been told: under the
+ * C collation `'apple' < 'Banana'` is false, under `en_US.UTF-8` it is true,
+ * and the collator says true. So `["<", "Banana"]` selects a different set here
+ * than it does there — silently, and in whichever direction the deployment
+ * happens to have been created.
+ *
+ * The refusal covers *every* ordering comparison rather than only the ones with
+ * a string operand, because the operand type does not settle it: a numeric
+ * bound against a text column (`["<", 10]` on a `varchar`) also reaches the
+ * collator, and nothing in `params` says what the column holds. Conservative on
+ * purpose — the cost is that a query combining an ordering filter with
+ * *unsynced local writes* stops placing those writes optimistically, which is a
+ * degraded answer rather than a wrong one. Claiming exactness we do not have is
+ * the other way round.
+ *
+ * This says nothing about ordering *results*; that is a separate claim with a
+ * separate answer, because a sort changes which rows come first and not which
+ * rows match. See {@link isLocallySortable}.
  */
 export function isExactlyEvaluable(params?: FindParams): boolean {
     if (!params) return true;
@@ -364,6 +408,45 @@ export function isExactlyEvaluable(params?: FindParams): boolean {
     // nearest of what happens to be cached while looking like the nearest there
     // are — a wrong answer that is indistinguishable from a right one.
     if (params.vectorSearch) return false;
+    if (whereOrders(params.where)) return false;
+    if (logicalOrders(params.logical)) return false;
+    return true;
+}
+
+/**
+ * Would sorting `rows` locally reproduce the order the server would have sent?
+ *
+ * Asked of the rows rather than of the query, because unlike a filter this one
+ * *is* decidable from the data in hand: {@link compareValues} reaches the
+ * collator only when it cannot read both operands as numbers, and `toComparable`
+ * has already turned dates and relations into numbers and ids by then. If every
+ * value on the sort column normalises to a number, the collator is unreachable
+ * and the local order is the server's order.
+ *
+ * A text column is therefore refused — see {@link isExactlyEvaluable} for why
+ * the two cannot be made to agree — and so is a column this page happens to see
+ * only as strings, which is the same thing from here.
+ *
+ * Nulls are fine either way: they are ordered by an explicit rule (last
+ * ascending, first descending) that matches Postgres and never reaches the
+ * comparator.
+ */
+export function isLocallySortable(
+    rows: readonly Record<string, unknown>[],
+    orderBy?: OrderByTuple
+): boolean {
+    if (!orderBy) return true;
+    const [field] = orderBy;
+    for (const row of rows) {
+        const value = toComparable(row[field]);
+        if (isNullish(value)) continue;
+        if (typeof value === "number" || typeof value === "boolean") continue;
+        if (typeof value === "bigint") continue;
+        // A numeric string is compared as a number, so it is safe too — this is
+        // the wire's type erasure, which `compareValues` already undoes.
+        if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) continue;
+        return false;
+    }
     return true;
 }
 

package/src/offline.test.ts

@@ -14,7 +14,7 @@ type Row = Record<string, unknown>;
  * online/offline decision logic rather than a mock of it.
  */
 function createFakeServer() {
-    const state = { online: true };
+    const state: { online: boolean; rejectNextCreate?: Error; rejectEveryCreate?: Error } = { online: true };
     const tables = new Map<string, Map<string, Row>>();
     const log: { collection: string; op: string; id?: unknown; ids?: unknown[]; upsert?: boolean }[] = [];
 
@@ -41,6 +41,13 @@ function createFakeServer() {
             },
             async create(data: Partial<Row>, id?: string | number) {
                 assertOnline();
+                // Lets a test answer the first replay the way a server does
+                // when it is still holding this write's idempotency key.
+                const injected = state.rejectNextCreate ?? state.rejectEveryCreate;
+                if (injected) {
+                    state.rejectNextCreate = undefined;
+                    throw injected;
+                }
                 const rowId = id ?? data.id ?? `srv-${table(slug).size + 1}`;
                 log.push({ collection: slug, op: "create", id: rowId });
                 const row = { ...data, id: rowId };
@@ -311,6 +318,64 @@ describe("OfflineManager", () => {
             expect(server.table("posts").get("p9")).toMatchObject({ title: "kept" });
         });
 
+        it("keeps a write the server is still answering, and lands it on the next flush", async () => {
+            // `IDEMPOTENCY_KEY_IN_PROGRESS` means the server holds this write's
+            // key and has not answered yet — the row may not exist at all. Read
+            // as any other 409 it looked like "your row is already there": the
+            // queue looked the row up, found nothing, decided there was nothing
+            // left to do and deleted the write. The record survived only in the
+            // local store and disappeared at the next reconciliation, silently.
+            const server = createFakeServer();
+            const onSyncError = jest.fn<(error: Error, mutation: PendingMutation) => void>();
+            const { manager, wrap } = createManager(server, { onSyncError });
+
+            server.state.online = false;
+            await wrap("posts").create({ title: "queued" });
+
+            server.state.online = true;
+            server.state.rejectNextCreate = new RebaseApiError("still in progress", {
+                status: 409,
+                code: "IDEMPOTENCY_KEY_IN_PROGRESS"
+            });
+
+            const refused = await manager.sync();
+            expect(refused).toEqual({ flushed: 0, remaining: 1 });
+            expect(onSyncError).not.toHaveBeenCalled();
+            expect(server.table("posts").size).toBe(0);
+
+            // The claim expired (or its request finally answered): the same
+            // queued write goes through untouched.
+            const settled = await manager.sync();
+            expect(settled).toEqual({ flushed: 1, remaining: 0 });
+            expect([...server.table("posts").values()]).toMatchObject([{ title: "queued" }]);
+        });
+
+        it("outlasts the claim's lease rather than giving up on the default retry budget", async () => {
+            // Retries double from a second, so the five a busy server gets are
+            // spent inside half a minute — less than the lease the server gives
+            // a claim whose process died. Spending them here would roll back
+            // the write a few seconds before the key became free again.
+            const server = createFakeServer();
+            const onSyncError = jest.fn<(error: Error, mutation: PendingMutation) => void>();
+            const { manager, wrap } = createManager(server, { onSyncError });
+
+            server.state.online = false;
+            await wrap("posts").create({ title: "queued" });
+
+            server.state.online = true;
+            server.state.rejectEveryCreate = new RebaseApiError("still in progress", {
+                status: 409,
+                code: "IDEMPOTENCY_KEY_IN_PROGRESS"
+            });
+            for (let attempt = 0; attempt < 8; attempt++) await manager.sync();
+
+            expect(onSyncError).not.toHaveBeenCalled();
+            expect(await manager.api.pending()).toHaveLength(1);
+
+            server.state.rejectEveryCreate = undefined;
+            expect(await manager.sync()).toEqual({ flushed: 1, remaining: 0 });
+        });
+
         it("notifies queue-size listeners as writes queue and drain", async () => {
             const server = createFakeServer();
             const { manager, wrap } = createManager(server);