@ultimat3/query 4.1.0 → 5.0.1

package/CLAUDE.md

@@ -21,7 +21,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `naming.ts` | export name → `/_x/query/<kebab>`. Pure string math. **Paths only** — no tool name |
 | `registry.ts` | export-name registration, `describeQueries()`, and the `registerPrimitiveRegistrar('query', …)` announcement |
 | `live.ts` | `LiveQuery` descriptor + cursor arithmetic |
-| `matcher.ts` | change event → minimal patch, or `X_MATCHER_UNSUPPORTED` |
+| `matcher.ts` | change event → minimal patch, `refill` when the window cannot place the row, or `X_MATCHER_UNSUPPORTED` |
 | `pagination.ts` | `paginate()` over core's cursor codec — no offset, ever |
 | `cursor-value.ts` | what a sort value becomes inside a cursor, and what it becomes again |
 | `input-shape.ts` | what a read's `input:` may be, given that its route is a query STRING |
@@ -445,3 +445,22 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 bun test packages/query
 bun run typecheck
 ```
+
+**A position is decided against the rows the WINDOW holds, so a window that cannot answer gets a
+`refill` rather than a guess** — `unprojectedOrderKey`, `As of 2026-08-20`. A result set is whatever
+the query's `sql` returned, and a PROJECTION that drops an ordering column left `compareRows`
+measuring the change row's real value against nothing: never equal on the update path, so every
+change read as a move, and arbitrary on the insert path, so a row created last landed wherever
+`undefined` sorted. `examples/dummy`'s feed ordered by `createdAt` and projected without it, and one
+publish became a `remove` + `insert` whose re-inserted row was the raw table row (#230).
+
+The discriminator is **`Object.hasOwn`, never a value check**: a nullable column that IS null still
+carries its key, and everywhere else in this package an absent key and a SQL NULL are one absence
+(`isNull` says so). Here they are different facts — "this row's value is nothing" versus "this shape
+cannot answer" — and only the key tells them apart. Asked of the row the window holds and never of
+the change row, which comes off the table and can always answer. A **delete** never reaches the rule:
+it is addressed by the index its id was found at, so a projected query still removes incrementally.
+
+The rule generalises what `assertSeekable` already applies to a cursor: **a sort key has to be
+readable on the row.** A live query whose rows omit one still works — it re-reads instead of
+patching — which is correct and slower, and the fix is to project the key.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "4.1.0",
+  "version": "5.0.1",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "4.1.0",
-    "@ultimat3/core": "4.1.0",
-    "@ultimat3/http": "4.1.0",
-    "@ultimat3/policy": "4.1.0",
-    "@ultimat3/schema": "4.1.0"
+    "@ultimat3/cache": "5.0.1",
+    "@ultimat3/core": "5.0.1",
+    "@ultimat3/http": "5.0.1",
+    "@ultimat3/policy": "5.0.1",
+    "@ultimat3/schema": "5.0.1"
   }
 }

package/src/matcher.ts

@@ -64,6 +64,23 @@ export function match<TRow extends object>(
     return inSet ? removeAt(shape, index, id, true, rows.length) : [];
   }
   if (!belongs) return [];
+
+  // Everything below this line decides a POSITION, and a position is decided against the rows the
+  // window HOLDS. A result set is whatever the query's `sql` returned, so a PROJECTION that drops an
+  // ordering column leaves `compareRows` measuring the change row's real value against nothing —
+  // never equal on the update path, so every change read as a move, and arbitrary on the insert
+  // path, so a new row landed wherever `undefined` sorted. In `examples/dummy` that turned one
+  // publish into a `remove` + `insert` whose re-inserted row was the raw table row (#230).
+  //
+  // Refusing to decide is the honest answer, and `refill` already means it: "the window is a guess,
+  // re-read it". The node turns it into one read plus a re-snapshot. A DELETE never reaches here —
+  // it is addressed by the index the id was found at, which needs no ordering — so a projected
+  // query still removes rows incrementally.
+  const sample = rows[0];
+  if (sample !== undefined && unprojectedOrderKey(shape, sample) !== undefined) {
+    return [{ kind: 'refill', from: 0 }];
+  }
+
   if (!inSet) return insert(shape, rows, event.row);
 
   // Present and still matching: a change to an ordering column is a move, not an update.
@@ -110,6 +127,25 @@ function insert<TRow extends object>(
   return patches;
 }
 
+/**
+ * The first `orderBy` column the result set's own rows do not carry, or `undefined` when every one
+ * of them is readable there.
+ *
+ * `Object.hasOwn`, never a value check: a nullable column that IS null still has its key, and
+ * `isNull` deliberately treats an absent key and a SQL NULL as one absence everywhere else. Here
+ * they are different facts — "this row's value is nothing" versus "this shape cannot answer" — and
+ * only the key tells them apart.
+ *
+ * Asked of the row the WINDOW holds, never of the change row: the change row comes off the table
+ * and carries every column, so it can always answer. What decides is whether the client's copy can.
+ */
+export function unprojectedOrderKey(shape: QueryShape, held: object): string | undefined {
+  for (const key of shape.orderBy) {
+    if (!Object.hasOwn(held, key.column)) return key.column;
+  }
+  return undefined;
+}
+
 /**
  * `held` is how many rows the window actually holds, and it is the whole condition on the refill.
  *