kitcn 0.18.0 → 0.20.0

package/dist/{where-clause-compiler-B1weGkP4.d.ts → where-clause-compiler-BGBNBNit.d.ts}

@@ -2539,15 +2539,25 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * The where-clause compiler is built from declared indexes only, and `_id` is
    * never one of them, so an `id` filter can never be index-selected: it lands
    * in the post-filters and the stream walks the creation-time index until it
-   * happens on the row. `db.get()` reads exactly the rows asked for, so the ids
-   * are fetched directly and replayed as a creation-time-ordered stream — the
-   * order the scan would have produced, so stage order and cursors are the same.
+   * happens on the row. `db.get()` reads exactly the rows asked for.
+   *
+   * Rows come back in the order the ids were given, one read at a time. Missing
+   * or policy-filtered ids still cost a read, but a page does not reread the
+   * complete list. An `orderBy` on creation time is the exception: an id carries
+   * no creation time, so every id must be read before the first row is placed.
    *
    * Returns null when something else already owns the read: a pinned index, an
    * index the compiler did select, a `where(predicate)`, or an `orderBy` that
    * walks a different index.
    */
   private _buildIdLookupStream;
+  /**
+   * The declared index a stream read can walk to emit `field` in order.
+   *
+   * A stream orders by the index it scans, so only an index that leads with
+   * the field produces that order.
+   */
+  private _findStreamOrderIndex;
   private _buildBasePipelineStream;
   /**
    * Stream equivalent of the `db.query(...)` chain, used when a post-fetch
@@ -4367,7 +4377,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_state: ConvexTableWithColumns<{
     name: "aggregate_state";
     columns: {
-      kind: ConvexTextBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4377,7 +4387,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "kind";
+          fieldName: "status";
         };
       };
       cursor: ConvexTextBuilderInitial<""> & {
@@ -4389,7 +4399,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      kind: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4399,10 +4409,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "kind";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4412,10 +4422,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4425,10 +4435,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4438,10 +4448,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyDefinitionHash";
+          fieldName: "indexName";
         };
       };
-      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
+      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4451,10 +4461,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "metricDefinitionHash";
+          fieldName: "keyDefinitionHash";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
+      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4464,7 +4474,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "metricDefinitionHash";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {
@@ -4516,43 +4526,44 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
     by_creation_time: ["_creationTime"];
     by_kind_table_index: ["kind", "tableKey", "indexName", "_creationTime"];
     by_kind_status: ["kind", "status", "_creationTime"];
+    by_table_status: ["tableKey", "status", "_creationTime"];
   }, {}, {}, {}>;
 }>, SchemaExtension<{
   readonly migration_state: ConvexTableWithColumns<{
     name: "migration_state";
     columns: {
-      cursor: ConvexTextBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "status";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "cursor";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "direction";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4562,7 +4573,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "updatedAt";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {
@@ -4675,7 +4686,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly migration_run: ConvexTableWithColumns<{
     name: "migration_run";
     columns: {
-      direction: ConvexTextBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4685,10 +4696,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "status";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4698,10 +4709,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "direction";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4711,7 +4722,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "updatedAt";
         };
       };
       startedAt: ConvexNumberBuilderInitial<""> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",

package/skills/kitcn/references/features/aggregates.md

@@ -54,7 +54,7 @@ Windowed count: `count({ where, orderBy, skip, take, cursor })` counts rows with
 | Error                      | Cause                                        |
 | -------------------------- | -------------------------------------------- |
 | `COUNT_NOT_INDEXED`        | No `aggregateIndex` matches the filter shape |
-| `COUNT_FILTER_UNSUPPORTED` | Uses unsupported operators                   |
+| `COUNT_FILTER_UNSUPPORTED` | Unsupported operators, or a range count/aggregate over `aggregateWorkBudget` work units |
 | `COUNT_INDEX_BUILDING`     | Index still backfilling                      |
 | `COUNT_RLS_UNSUPPORTED`    | Called in RLS-restricted context             |
 
@@ -310,6 +310,15 @@ If rank or aggregate state gets out of sync:
 kitcn aggregate rebuild
 ```
 
+Rebuild clears stored state in scheduled batches. Indexes report `CLEARING`
+while draining and `BUILDING` while recomputing; wait for `READY`.
+Writes targeting a declared index in `CLEARING` fail before the document write;
+retry them after the index advances to `BUILDING` or `READY`.
+Automatic pruning follows aggregate lifecycle state, so kickoff reads stay
+bounded as the backing tables grow. For state-less storage, call
+`aggregateBackfill` in `prune` mode with exact `tableName` and `indexName`
+arguments.
+
 ## When to Use
 
 | Need                   | Use                                                             |

package/skills/kitcn/references/features/orm.md

@@ -721,7 +721,7 @@ const filtered = results.filter((a) => a.publishedAt >= startDate);
 ### Performance
 
 1. **Index first** — constrain leading index fields. Compound indexes follow prefix rules. Put the `orderBy` column right after the constrained prefix so the scan is already sorted and `limit` bounds the read.
-2. **Bound scans** — use `maxScan` for predicate `where` (cursor mode only).
+2. **Bound scans** — use `maxScan` for predicate `where` (cursor mode only). A `.select()` ID-list query with `orderBy` needs a single field that an index leads with.
 3. **Limit results** — always use `limit` or cursor pagination.
 4. **Cursor stability** — keep same `where`/`orderBy` between page requests.
 5. **`allowFullScan`** — non-cursor only. Cursor mode uses `maxScan` instead.