@ultimat3/query 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -229,6 +229,17 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   `"null"`. Refused: a structural member (`object`, `record`, `money`, or an array/union of one),
   a REQUIRED nullable member, and a top-level input that is not an object. A schema
   `tryIntrospect` cannot read is left alone, or `configureSchemaProvider` would be unusable.
+- **A refill is owed by a FULL window and by nothing else** (`matcher.ts`, `As of 2026-08`).
+  `removeAt` pushed one whenever `shape.limit !== null`, with no reference to how many rows the
+  window holds: three rows under `limit: 50`, delete one, and the patch list was
+  `[{remove, position:1}, {refill, from:49}]` — a position no two-row result set has. It is not a
+  harmless extra: `@ultimat3/realtime`'s `matcher-bridge` folds any refill into
+  `BridgeResult.refill`, and `live-fanout` then sends **no patch frame at all** that round, marking
+  every subscriber desynced instead — so on a quiet feed the deleted row stays rendered until some
+  other change to the same query id arrives, and on a busy one it is a full DB re-read plus one
+  snapshot per subscriber per delete. A window under `limit` has no unknown tail: the source served
+  fewer rows than it was allowed to, so what the client holds IS the result set. `held >=
+  shape.limit` is the gate, and it is `wasFull` one branch away, already written.
 - **A move OUT of a full window is a `refill`, never an `add`** (`matcher.ts`). `insert()` places a
   moved row among the `limit - 1` rows the client still holds, so its position can never reach
   `shape.limit` and the `position >= shape.limit` bail is unreachable on that path — the row was

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "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": "2.0.0",
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/http": "2.0.0",
-    "@ultimat3/policy": "2.0.0",
-    "@ultimat3/schema": "2.0.0"
+    "@ultimat3/cache": "3.0.0",
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/http": "3.0.0",
+    "@ultimat3/policy": "3.0.0",
+    "@ultimat3/schema": "3.0.0"
   }
 }

package/src/matcher.ts

@@ -61,7 +61,7 @@ export function match<TRow extends object>(
   const belongs = event.op !== 'delete' && matchesFilters(event.row, shape.filters);
 
   if (event.op === 'delete' || (inSet && !belongs)) {
-    return inSet ? removeAt(shape, index, id, true) : [];
+    return inSet ? removeAt(shape, index, id, true, rows.length) : [];
   }
   if (!belongs) return [];
   if (!inSet) return insert(shape, rows, event.row);
@@ -84,9 +84,12 @@ export function match<TRow extends object>(
   // too, so the refill covers both.
   const wasFull = shape.limit !== null && rows.length >= shape.limit;
   if (wasFull && positionFor(shape, without, event.row) >= without.length) {
-    return removeAt<TRow>(shape, index, id, true);
+    return removeAt<TRow>(shape, index, id, true, rows.length);
   }
-  return [...removeAt<TRow>(shape, index, id, false), ...insert(shape, without, event.row)];
+  return [
+    ...removeAt<TRow>(shape, index, id, false, rows.length),
+    ...insert(shape, without, event.row),
+  ];
 }
 
 function insert<TRow extends object>(
@@ -107,15 +110,28 @@ function insert<TRow extends object>(
   return patches;
 }
 
+/**
+ * `held` is how many rows the window actually holds, and it is the whole condition on the refill.
+ *
+ * A refill says the tail is unknown to the client, and it is answered by a full re-read: the bridge
+ * folds it into `BridgeResult.refill`, and the fanout then sends NO patch frame that round —
+ * suppressing the `remove` beside it and leaving a deleted row on screen until the next change to
+ * the same query. A window under `limit` has no unknown tail: the source served fewer rows than it
+ * was allowed to, so what the client holds IS the result set. Unconditional, this also named a
+ * position no result set has — `limit: 50` over three rows emitted `{ refill, from: 49 }`.
+ */
 function removeAt<TRow extends object>(
   shape: QueryShape,
   index: number,
   id: string,
   refill: boolean,
+  held: number,
 ): readonly Patch<TRow>[] {
   const patches: Patch<TRow>[] = [{ kind: 'remove', position: index, id }];
-  // A limited window may now be one row short, and the tail lives on the server.
-  if (refill && shape.limit !== null) patches.push({ kind: 'refill', from: shape.limit - 1 });
+  // A window that WAS full is now one row short, and that row lives on the server.
+  if (refill && shape.limit !== null && held >= shape.limit) {
+    patches.push({ kind: 'refill', from: shape.limit - 1 });
+  }
   return patches;
 }