@kernl-sdk/turbopuffer 0.1.5 → 0.1.7

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @kernl-sdk/turbopuffer@0.1.5 build /home/runner/work/kernl/kernl/packages/storage/turbopuffer
+> @kernl-sdk/turbopuffer@0.1.7 build /home/runner/work/kernl/kernl/packages/storage/turbopuffer
 > tsc && tsc-alias --resolve-full-paths
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @kernl-sdk/turbopuffer
 
+## 0.1.7
+
+### Patch Changes
+
+- @kernl-sdk/retrieval@0.1.6
+
+## 0.1.6
+
+### Patch Changes
+
+- Updated dependencies [25e46e7]
+  - @kernl-sdk/shared@0.3.1
+  - @kernl-sdk/retrieval@0.1.5
+
 ## 0.1.5
 
 ### Patch Changes

package/README.md

@@ -44,7 +44,7 @@ await docs.upsert({
 // query with vector search
 const hits = await docs.query({
   query: [{ vector: [0.1, 0.2, ...] }],
-  topK: 10,
+  limit: 10,
   filter: { category: "greeting" },
   include: ["content", "category"], // fields to include in the response
 });

package/dist/__tests__/convert.test.js

@@ -248,7 +248,7 @@ describe("convert", () => {
         it("encodes vector search query", () => {
             const result = QUERY.encode({
                 query: [{ vector: [0.1, 0.2, 0.3] }],
-                topK: 10,
+                limit: 10,
             });
             expect(result.rank_by).toEqual(["vector", "ANN", [0.1, 0.2, 0.3]]);
             expect(result.top_k).toBe(10);
@@ -256,7 +256,7 @@ describe("convert", () => {
         it("encodes text search query", () => {
             const result = QUERY.encode({
                 query: [{ content: "hello world" }],
-                topK: 5,
+                limit: 5,
             });
             expect(result.rank_by).toEqual(["content", "BM25", "hello world"]);
             expect(result.top_k).toBe(5);
@@ -264,7 +264,7 @@ describe("convert", () => {
         it("encodes multi-field text search as Sum", () => {
             const result = QUERY.encode({
                 query: [{ title: "search term" }, { body: "search term" }],
-                topK: 10,
+                limit: 10,
             });
             expect(result.rank_by).toEqual([
                 "Sum",
@@ -277,7 +277,7 @@ describe("convert", () => {
         it("encodes filter", () => {
             const result = QUERY.encode({
                 query: [{ vector: [0.1] }],
-                topK: 5,
+                limit: 5,
                 filter: { category: { $eq: "news" } },
             });
             expect(result.filters).toEqual(["category", "Eq", "news"]);
@@ -285,7 +285,7 @@ describe("convert", () => {
         it("encodes include fields array", () => {
             const result = QUERY.encode({
                 query: [{ vector: [0.1] }],
-                topK: 5,
+                limit: 5,
                 include: ["title", "content"],
             });
             expect(result.include_attributes).toEqual(["title", "content"]);
@@ -293,7 +293,7 @@ describe("convert", () => {
         it("encodes include as boolean", () => {
             const result = QUERY.encode({
                 query: [{ vector: [0.1] }],
-                topK: 5,
+                limit: 5,
                 include: true,
             });
             expect(result.include_attributes).toBe(true);

package/dist/__tests__/integration/filters.integration.test.js

@@ -162,7 +162,7 @@ describe("Filter integration tests", () => {
     async function queryIds(filter) {
         const hits = await ns.query({
             query: [{ vector: QUERY_VECTOR }],
-            topK: 100,
+            limit: 100,
             filter,
         });
         return hits.map((h) => h.id).sort();
@@ -440,7 +440,7 @@ describe("Filter integration tests", () => {
         it("filtered results have correct field values", async () => {
             const hits = await ns.query({
                 query: [{ vector: QUERY_VECTOR }],
-                topK: 100,
+                limit: 100,
                 filter: { status: "pending" },
                 include: ["status", "flag", "num"],
             });
@@ -456,7 +456,7 @@ describe("Filter integration tests", () => {
         it("complex filter returns expected documents with correct data", async () => {
             const hits = await ns.query({
                 query: [{ vector: QUERY_VECTOR }],
-                topK: 100,
+                limit: 100,
                 filter: {
                     $and: [{ num: { $gte: 20, $lte: 50 } }, { flag: true }],
                 },

package/dist/__tests__/integration/integration.test.js

@@ -139,7 +139,7 @@ describe("TurbopufferSearchIndex integration", () => {
             // Verify via query
             const hits = await index.query({
                 query: [{ vector: vec }],
-                topK: 10,
+                limit: 10,
                 include: ["category"],
             });
             expect(hits.length).toBeGreaterThanOrEqual(1);
@@ -160,7 +160,7 @@ describe("TurbopufferSearchIndex integration", () => {
             // Verify via query
             const hits = await index.query({
                 query: [{ vector: vec }],
-                topK: 10,
+                limit: 10,
                 include: ["category"],
             });
             const doc = hits.find((h) => h.id === "doc-1");
@@ -188,7 +188,7 @@ describe("TurbopufferSearchIndex integration", () => {
             // Verify via query with filter
             const hits = await index.query({
                 query: [{ vector: new Array(384).fill(0.3) }],
-                topK: 10,
+                limit: 10,
                 filter: { category: "test" },
                 include: true,
             });
@@ -208,7 +208,7 @@ describe("TurbopufferSearchIndex integration", () => {
             const index = tpuf.index(testIndexId);
             const hits = await index.query({
                 query: [{ vector: new Array(384).fill(0.1) }],
-                topK: 5,
+                limit: 5,
             });
             expect(hits.length).toBeGreaterThan(0);
             expect(hits[0]).toHaveProperty("id");
@@ -219,7 +219,7 @@ describe("TurbopufferSearchIndex integration", () => {
             const index = tpuf.index(testIndexId);
             const hits = await index.query({
                 query: [{ vector: new Array(384).fill(0.1) }],
-                topK: 5,
+                limit: 5,
                 include: ["content", "category"],
             });
             expect(hits.length).toBeGreaterThan(0);
@@ -231,7 +231,7 @@ describe("TurbopufferSearchIndex integration", () => {
             const index = tpuf.index(testIndexId);
             const hits = await index.query({
                 query: [{ vector: new Array(384).fill(0.3) }],
-                topK: 10,
+                limit: 10,
                 filter: { category: "test" },
                 include: ["category"],
             });
@@ -244,7 +244,7 @@ describe("TurbopufferSearchIndex integration", () => {
             const index = tpuf.index(testIndexId);
             const hits = await index.query({
                 query: [{ vector: new Array(384).fill(0.3) }],
-                topK: 10,
+                limit: 10,
                 filter: {
                     $and: [
                         { category: "test" },
@@ -273,7 +273,7 @@ describe("TurbopufferSearchIndex integration", () => {
             // Verify it exists
             let hits = await index.query({
                 query: [{ vector: vec }],
-                topK: 10,
+                limit: 10,
                 filter: { id: "doc-to-delete" },
             });
             expect(hits.some((h) => h.id === "doc-to-delete")).toBe(true);
@@ -282,7 +282,7 @@ describe("TurbopufferSearchIndex integration", () => {
             // Verify it's gone
             hits = await index.query({
                 query: [{ vector: vec }],
-                topK: 10,
+                limit: 10,
                 filter: { id: "doc-to-delete" },
             });
             expect(hits.some((h) => h.id === "doc-to-delete")).toBe(false);
@@ -310,7 +310,7 @@ describe("TurbopufferSearchIndex integration", () => {
             // Verify they exist
             let hits = await index.query({
                 query: [{ vector: vec }],
-                topK: 10,
+                limit: 10,
                 filter: { category: "bulk-delete" },
             });
             expect(hits.length).toBeGreaterThanOrEqual(2);
@@ -319,7 +319,7 @@ describe("TurbopufferSearchIndex integration", () => {
             // Verify they're gone
             hits = await index.query({
                 query: [{ vector: vec }],
-                topK: 10,
+                limit: 10,
                 filter: { category: "bulk-delete" },
             });
             expect(hits.some((h) => h.id === "bulk-del-1")).toBe(false);

package/dist/__tests__/integration/lifecycle.integration.test.js

@@ -149,7 +149,7 @@ describe("Lifecycle edge cases integration tests", () => {
             // Query and verify final state
             const hits = await index.query({
                 query: [{ vector: [0.3, 0.3, 0.3, 0.3] }],
-                topK: 10,
+                limit: 10,
                 filter: { id: "overwrite-test" },
                 include: ["content", "count"],
             });
@@ -167,7 +167,7 @@ describe("Lifecycle edge cases integration tests", () => {
             await new Promise((r) => setTimeout(r, 500));
             const hits = await index.query({
                 query: [{ vector: [0.1, 0.1, 0.1, 0.1] }],
-                topK: 10,
+                limit: 10,
                 filter: { id: "minimal-doc" },
             });
             expect(hits.some((h) => h.id === "minimal-doc")).toBe(true);
@@ -252,7 +252,7 @@ describe("Lifecycle edge cases integration tests", () => {
             // Verify exists
             let hits = await index.query({
                 query: [{ vector: [0.9, 0.9, 0.9, 0.9] }],
-                topK: 10,
+                limit: 10,
                 filter: { id: "to-delete" },
             });
             expect(hits.length).toBe(1);
@@ -262,7 +262,7 @@ describe("Lifecycle edge cases integration tests", () => {
             // Verify gone
             hits = await index.query({
                 query: [{ vector: [0.9, 0.9, 0.9, 0.9] }],
-                topK: 10,
+                limit: 10,
                 filter: { id: "to-delete" },
             });
             expect(hits.length).toBe(0);
@@ -294,7 +294,7 @@ describe("Lifecycle edge cases integration tests", () => {
             const index = tpuf.index(indexId);
             const hits = await index.query({
                 query: [{ vector: [0.1, 0.2, 0.3, 0.4] }],
-                topK: 10,
+                limit: 10,
             });
             expect(hits).toEqual([]);
         });
@@ -310,16 +310,16 @@ describe("Lifecycle edge cases integration tests", () => {
             // Query with filter that matches nothing
             const hits = await index.query({
                 query: [{ vector: [0.1, 0.1, 0.1, 0.1] }],
-                topK: 10,
+                limit: 10,
                 filter: { id: "nonexistent-id" },
             });
             expect(hits).toEqual([]);
         });
-        it("topK of 0 throws", async () => {
+        it("limit of 0 throws", async () => {
             const index = tpuf.index(indexId);
             await expect(index.query({
                 query: [{ vector: [0.1, 0.1, 0.1, 0.1] }],
-                topK: 0,
+                limit: 0,
             })).rejects.toThrow();
         });
     });
@@ -361,7 +361,7 @@ describe("Lifecycle edge cases integration tests", () => {
             // Query with wrong dimension
             await expect(index.query({
                 query: [{ vector: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] }], // 8 dims
-                topK: 10,
+                limit: 10,
             })).rejects.toThrow();
             await tpuf.deleteIndex(indexId);
         });

package/dist/__tests__/integration/memory.integration.test.js

@@ -183,7 +183,7 @@ describe.sequential("Memory Integration with Turbopuffer", { timeout: 60000 }, (
         expect(results.length).toBe(1);
         expect(results[0].document?.id).toBe(id1);
     });
-    it("respects topK limit", async () => {
+    it("respects limit", async () => {
         const ns = uid("ns");
         await agent.memories.create({
             namespace: ns,

package/dist/__tests__/integration/query.integration.test.d.ts

@@ -2,7 +2,7 @@
  * Comprehensive query modes integration tests.
  *
  * Tests vector search, BM25 text search, hybrid queries, fusion modes,
- * topK behavior, include semantics, and rank ordering against real Turbopuffer API.
+ * limit behavior, include semantics, and rank ordering against real Turbopuffer API.
  */
 export {};
 //# sourceMappingURL=query.integration.test.d.ts.map

package/dist/__tests__/integration/query.integration.test.js

@@ -2,7 +2,7 @@
  * Comprehensive query modes integration tests.
  *
  * Tests vector search, BM25 text search, hybrid queries, fusion modes,
- * topK behavior, include semantics, and rank ordering against real Turbopuffer API.
+ * limit behavior, include semantics, and rank ordering against real Turbopuffer API.
  */
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import { TurbopufferSearchIndex } from "../../search.js";
@@ -111,7 +111,7 @@ describe("Query modes integration tests", () => {
             // Query with basis vector 1 - should match vec-1 best
             const hits = await index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-                topK: 10,
+                limit: 10,
             });
             expect(hits.length).toBeGreaterThan(0);
             expect(hits[0].id).toBe("vec-1");
@@ -120,7 +120,7 @@ describe("Query modes integration tests", () => {
             // Query with basis vector 2
             const hits = await index.query({
                 query: [{ vector: [0.0, 1.0, 0.0, 0.0] }],
-                topK: 10,
+                limit: 10,
             });
             expect(hits.length).toBeGreaterThan(0);
             expect(hits[0].id).toBe("vec-2");
@@ -133,35 +133,35 @@ describe("Query modes integration tests", () => {
             // Query with mix of basis 1 and 2 - should prefer vec-5 which has [0.5, 0.5, 0, 0]
             const hits = await index.query({
                 query: [{ vector: [0.5, 0.5, 0.0, 0.0] }],
-                topK: 10,
+                limit: 10,
             });
             expect(hits.length).toBeGreaterThan(0);
             expect(hits[0].id).toBe("vec-5");
         });
     });
     // ============================================================
-    // TOPK BEHAVIOR
+    // LIMIT BEHAVIOR
     // ============================================================
-    describe("topK behavior", () => {
-        it("topK smaller than doc count returns exactly topK", async () => {
+    describe("limit behavior", () => {
+        it("limit smaller than doc count returns exactly limit", async () => {
             const hits = await index.query({
                 query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-                topK: 3,
+                limit: 3,
             });
             expect(hits.length).toBe(3);
         });
-        it("topK larger than doc count returns all docs", async () => {
+        it("limit larger than doc count returns all docs", async () => {
             const hits = await index.query({
                 query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-                topK: 100,
+                limit: 100,
             });
             // We have 6 docs
             expect(hits.length).toBe(6);
         });
-        it("topK of 1 returns single best match", async () => {
+        it("limit of 1 returns single best match", async () => {
             const hits = await index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-                topK: 1,
+                limit: 1,
             });
             expect(hits.length).toBe(1);
             expect(hits[0].id).toBe("vec-1");
@@ -174,7 +174,7 @@ describe("Query modes integration tests", () => {
         it("single field text query finds matching docs", async () => {
             const hits = await index.query({
                 query: [{ title: "neural" }],
-                topK: 10,
+                limit: 10,
                 include: ["title"],
             });
             expect(hits.length).toBeGreaterThan(0);
@@ -185,7 +185,7 @@ describe("Query modes integration tests", () => {
         it("content field text query finds matching docs", async () => {
             const hits = await index.query({
                 query: [{ content: "transformer" }],
-                topK: 10,
+                limit: 10,
                 include: ["content"],
             });
             expect(hits.length).toBeGreaterThan(0);
@@ -195,7 +195,7 @@ describe("Query modes integration tests", () => {
         it("multi-field text query searches both fields", async () => {
             const hits = await index.query({
                 query: [{ title: "database" }, { content: "database" }],
-                topK: 10,
+                limit: 10,
                 include: ["title", "content"],
             });
             expect(hits.length).toBeGreaterThan(0);
@@ -206,7 +206,7 @@ describe("Query modes integration tests", () => {
         it("text query with no matches returns empty", async () => {
             const hits = await index.query({
                 query: [{ content: "xyznonexistentkeyword123" }],
-                topK: 10,
+                limit: 10,
             });
             expect(hits.length).toBe(0);
         });
@@ -218,7 +218,7 @@ describe("Query modes integration tests", () => {
         it("throws error for vector + text hybrid fusion", async () => {
             await expect(index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }, { content: "search" }],
-                topK: 10,
+                limit: 10,
             })).rejects.toThrow(/does not support hybrid/);
         });
         it("throws error for multi-vector fusion", async () => {
@@ -227,7 +227,7 @@ describe("Query modes integration tests", () => {
                     { vector: [1.0, 0.0, 0.0, 0.0] },
                     { vector: [0.0, 1.0, 0.0, 0.0] },
                 ],
-                topK: 10,
+                limit: 10,
             })).rejects.toThrow(/does not support multi-vector/);
         });
     });
@@ -238,7 +238,7 @@ describe("Query modes integration tests", () => {
         it("Sum fusion combines multiple BM25 signals", async () => {
             const hits = await index.query({
                 query: [{ title: "database" }, { content: "database" }],
-                topK: 10,
+                limit: 10,
                 include: ["title", "content"],
             });
             expect(hits.length).toBeGreaterThan(0);
@@ -249,7 +249,7 @@ describe("Query modes integration tests", () => {
         it("Max fusion takes best BM25 signal per doc", async () => {
             const hits = await index.query({
                 max: [{ title: "neural" }, { content: "neural" }],
-                topK: 10,
+                limit: 10,
                 include: ["title", "content"],
             });
             expect(hits.length).toBeGreaterThan(0);
@@ -265,7 +265,7 @@ describe("Query modes integration tests", () => {
         it("include: true returns all attributes", async () => {
             const hits = await index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-                topK: 1,
+                limit: 1,
                 include: true,
             });
             expect(hits.length).toBe(1);
@@ -278,7 +278,7 @@ describe("Query modes integration tests", () => {
         it("include: false returns only id", async () => {
             const hits = await index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-                topK: 1,
+                limit: 1,
                 include: false,
             });
             expect(hits.length).toBe(1);
@@ -289,7 +289,7 @@ describe("Query modes integration tests", () => {
         it("include: [fields] returns only specified fields", async () => {
             const hits = await index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-                topK: 1,
+                limit: 1,
                 include: ["title", "category"],
             });
             expect(hits.length).toBe(1);
@@ -303,7 +303,7 @@ describe("Query modes integration tests", () => {
         it("include: [] returns only id", async () => {
             const hits = await index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-                topK: 1,
+                limit: 1,
                 include: [],
             });
             expect(hits.length).toBe(1);
@@ -319,7 +319,7 @@ describe("Query modes integration tests", () => {
         it("filter by category", async () => {
             const hits = await index.query({
                 query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-                topK: 10,
+                limit: 10,
                 filter: { category: "ml" },
                 include: ["category"],
             });
@@ -331,7 +331,7 @@ describe("Query modes integration tests", () => {
         it("filter by priority range", async () => {
             const hits = await index.query({
                 query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-                topK: 10,
+                limit: 10,
                 filter: { priority: { $gte: 3, $lte: 5 } },
                 include: ["priority"],
             });
@@ -344,7 +344,7 @@ describe("Query modes integration tests", () => {
         it("filter with $or", async () => {
             const hits = await index.query({
                 query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-                topK: 10,
+                limit: 10,
                 filter: {
                     $or: [{ category: "ml" }, { category: "search" }],
                 },
@@ -363,7 +363,7 @@ describe("Query modes integration tests", () => {
         it("results have required fields", async () => {
             const hits = await index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-                topK: 1,
+                limit: 1,
             });
             expect(hits.length).toBe(1);
             expect(hits[0]).toHaveProperty("id");
@@ -375,7 +375,7 @@ describe("Query modes integration tests", () => {
         it("score is a valid number", async () => {
             const hits = await index.query({
                 query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-                topK: 5,
+                limit: 5,
             });
             for (const hit of hits) {
                 expect(typeof hit.score).toBe("number");

package/dist/__tests__/query.test.js

@@ -161,25 +161,25 @@ describe("QUERY", () => {
     // QUERY OPTIONS
     // ============================================================
     describe("query options", () => {
-        describe("topK", () => {
-            it("encodes topK as top_k", () => {
+        describe("limit", () => {
+            it("encodes limit as top_k", () => {
                 const result = QUERY.encode({
                     query: [{ vector: [0.1] }],
-                    topK: 10,
+                    limit: 10,
                 });
                 expect(result.top_k).toBe(10);
             });
-            it("encodes topK of 1", () => {
+            it("encodes limit of 1", () => {
                 const result = QUERY.encode({
                     query: [{ vector: [0.1] }],
-                    topK: 1,
+                    limit: 1,
                 });
                 expect(result.top_k).toBe(1);
             });
-            it("encodes large topK", () => {
+            it("encodes large limit", () => {
                 const result = QUERY.encode({
                     query: [{ vector: [0.1] }],
-                    topK: 10000,
+                    limit: 10000,
                 });
                 expect(result.top_k).toBe(10000);
             });
@@ -267,7 +267,7 @@ describe("QUERY", () => {
             it("encodes all options together", () => {
                 const result = QUERY.encode({
                     query: [{ vector: [0.1, 0.2] }],
-                    topK: 20,
+                    limit: 20,
                     filter: { category: "news" },
                     include: ["title", "summary"],
                 });
@@ -315,14 +315,14 @@ describe("QUERY", () => {
             // Direct codec call with empty array returns params without rank_by.
             const result = QUERY.encode({
                 query: [],
-                topK: 10,
+                limit: 10,
             });
             expect(result.rank_by).toBeUndefined();
             expect(result.top_k).toBe(10);
         });
         it("returns params without rank_by when no query or max", () => {
             const result = QUERY.encode({
-                topK: 10,
+                limit: 10,
                 filter: { status: "active" },
             });
             expect(result.rank_by).toBeUndefined();

package/dist/convert/query.js

@@ -15,9 +15,9 @@ export const QUERY = {
         if (signals && signals.length > 0) {
             params.rank_by = buildRankBy(signals, query.max !== undefined);
         }
-        // top K
-        if (query.topK !== undefined) {
-            params.top_k = query.topK;
+        // limit
+        if (query.limit !== undefined) {
+            params.top_k = query.limit;
         }
         // filters
         if (query.filter) {

package/dist/search.d.ts

@@ -33,7 +33,7 @@ import { TurbopufferConfig } from "./types.js";
  *
  * const hits = await docs.query({
  *   query: [{ vector: [0.1, 0.2, ...] }],
- *   topK: 10,
+ *   limit: 10,
  * });
  * ```
  */

package/dist/search.js

@@ -34,7 +34,7 @@ import { INDEX_SCHEMA, SIMILARITY } from "./convert/index.js";
  *
  * const hits = await docs.query({
  *   query: [{ vector: [0.1, 0.2, ...] }],
- *   topK: 10,
+ *   limit: 10,
  * });
  * ```
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernl-sdk/turbopuffer",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Turbopuffer search index adapter for kernl",
   "keywords": [
     "kernl",
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "@turbopuffer/turbopuffer": "^0.10.0",
-    "@kernl-sdk/retrieval": "0.1.4",
-    "@kernl-sdk/shared": "0.3.0"
+    "@kernl-sdk/retrieval": "0.1.6",
+    "@kernl-sdk/shared": "0.3.1"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",
@@ -41,10 +41,10 @@
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
-    "@kernl-sdk/ai": "0.3.1",
-    "@kernl-sdk/pg": "0.1.24",
-    "@kernl-sdk/protocol": "0.3.0",
-    "kernl": "0.9.0"
+    "@kernl-sdk/ai": "0.3.3",
+    "@kernl-sdk/protocol": "0.4.0",
+    "@kernl-sdk/pg": "0.1.26",
+    "kernl": "0.10.0"
   },
   "scripts": {
     "build": "tsc && tsc-alias --resolve-full-paths",

package/src/__tests__/convert.test.ts

@@ -296,7 +296,7 @@ describe("convert", () => {
     it("encodes vector search query", () => {
       const result = QUERY.encode({
         query: [{ vector: [0.1, 0.2, 0.3] }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(result.rank_by).toEqual(["vector", "ANN", [0.1, 0.2, 0.3]]);
@@ -306,7 +306,7 @@ describe("convert", () => {
     it("encodes text search query", () => {
       const result = QUERY.encode({
         query: [{ content: "hello world" }],
-        topK: 5,
+        limit: 5,
       });
 
       expect(result.rank_by).toEqual(["content", "BM25", "hello world"]);
@@ -316,7 +316,7 @@ describe("convert", () => {
     it("encodes multi-field text search as Sum", () => {
       const result = QUERY.encode({
         query: [{ title: "search term" }, { body: "search term" }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(result.rank_by).toEqual([
@@ -331,7 +331,7 @@ describe("convert", () => {
     it("encodes filter", () => {
       const result = QUERY.encode({
         query: [{ vector: [0.1] }],
-        topK: 5,
+        limit: 5,
         filter: { category: { $eq: "news" } },
       });
 
@@ -341,7 +341,7 @@ describe("convert", () => {
     it("encodes include fields array", () => {
       const result = QUERY.encode({
         query: [{ vector: [0.1] }],
-        topK: 5,
+        limit: 5,
         include: ["title", "content"],
       });
 
@@ -351,7 +351,7 @@ describe("convert", () => {
     it("encodes include as boolean", () => {
       const result = QUERY.encode({
         query: [{ vector: [0.1] }],
-        topK: 5,
+        limit: 5,
         include: true,
       });
 

package/src/__tests__/integration/filters.integration.test.ts

@@ -191,7 +191,7 @@ describe("Filter integration tests", () => {
   async function queryIds(filter: Filter): Promise<string[]> {
     const hits = await ns.query({
       query: [{ vector: QUERY_VECTOR }],
-      topK: 100,
+      limit: 100,
       filter,
     });
     return hits.map((h) => h.id).sort();
@@ -518,7 +518,7 @@ describe("Filter integration tests", () => {
     it("filtered results have correct field values", async () => {
       const hits = await ns.query({
         query: [{ vector: QUERY_VECTOR }],
-        topK: 100,
+        limit: 100,
         filter: { status: "pending" },
         include: ["status", "flag", "num"],
       });
@@ -537,7 +537,7 @@ describe("Filter integration tests", () => {
     it("complex filter returns expected documents with correct data", async () => {
       const hits = await ns.query({
         query: [{ vector: QUERY_VECTOR }],
-        topK: 100,
+        limit: 100,
         filter: {
           $and: [{ num: { $gte: 20, $lte: 50 } }, { flag: true }],
         },

package/src/__tests__/integration/integration.test.ts

@@ -176,7 +176,7 @@ describe("TurbopufferSearchIndex integration", () => {
       // Verify via query
       const hits = await index.query({
         query: [{ vector: vec }],
-        topK: 10,
+        limit: 10,
         include: ["category"],
       });
 
@@ -201,7 +201,7 @@ describe("TurbopufferSearchIndex integration", () => {
       // Verify via query
       const hits = await index.query({
         query: [{ vector: vec }],
-        topK: 10,
+        limit: 10,
         include: ["category"],
       });
 
@@ -233,7 +233,7 @@ describe("TurbopufferSearchIndex integration", () => {
       // Verify via query with filter
       const hits = await index.query({
         query: [{ vector: new Array(384).fill(0.3) }],
-        topK: 10,
+        limit: 10,
         filter: { category: "test" },
         include: true,
       });
@@ -257,7 +257,7 @@ describe("TurbopufferSearchIndex integration", () => {
 
       const hits = await index.query({
         query: [{ vector: new Array(384).fill(0.1) }],
-        topK: 5,
+        limit: 5,
       });
 
       expect(hits.length).toBeGreaterThan(0);
@@ -271,7 +271,7 @@ describe("TurbopufferSearchIndex integration", () => {
 
       const hits = await index.query({
         query: [{ vector: new Array(384).fill(0.1) }],
-        topK: 5,
+        limit: 5,
         include: ["content", "category"],
       });
 
@@ -286,7 +286,7 @@ describe("TurbopufferSearchIndex integration", () => {
 
       const hits = await index.query({
         query: [{ vector: new Array(384).fill(0.3) }],
-        topK: 10,
+        limit: 10,
         filter: { category: "test" },
         include: ["category"],
       });
@@ -302,7 +302,7 @@ describe("TurbopufferSearchIndex integration", () => {
 
       const hits = await index.query({
         query: [{ vector: new Array(384).fill(0.3) }],
-        topK: 10,
+        limit: 10,
         filter: {
           $and: [
             { category: "test" },
@@ -335,7 +335,7 @@ describe("TurbopufferSearchIndex integration", () => {
       // Verify it exists
       let hits = await index.query({
         query: [{ vector: vec }],
-        topK: 10,
+        limit: 10,
         filter: { id: "doc-to-delete" },
       });
       expect(hits.some((h) => h.id === "doc-to-delete")).toBe(true);
@@ -346,7 +346,7 @@ describe("TurbopufferSearchIndex integration", () => {
       // Verify it's gone
       hits = await index.query({
         query: [{ vector: vec }],
-        topK: 10,
+        limit: 10,
         filter: { id: "doc-to-delete" },
       });
       expect(hits.some((h) => h.id === "doc-to-delete")).toBe(false);
@@ -377,7 +377,7 @@ describe("TurbopufferSearchIndex integration", () => {
       // Verify they exist
       let hits = await index.query({
         query: [{ vector: vec }],
-        topK: 10,
+        limit: 10,
         filter: { category: "bulk-delete" },
       });
       expect(hits.length).toBeGreaterThanOrEqual(2);
@@ -388,7 +388,7 @@ describe("TurbopufferSearchIndex integration", () => {
       // Verify they're gone
       hits = await index.query({
         query: [{ vector: vec }],
-        topK: 10,
+        limit: 10,
         filter: { category: "bulk-delete" },
       });
       expect(hits.some((h) => h.id === "bulk-del-1")).toBe(false);

package/src/__tests__/integration/lifecycle.integration.test.ts

@@ -182,7 +182,7 @@ describe("Lifecycle edge cases integration tests", () => {
       // Query and verify final state
       const hits = await index.query({
         query: [{ vector: [0.3, 0.3, 0.3, 0.3] }],
-        topK: 10,
+        limit: 10,
         filter: { id: "overwrite-test" },
         include: ["content", "count"],
       });
@@ -205,7 +205,7 @@ describe("Lifecycle edge cases integration tests", () => {
 
       const hits = await index.query({
         query: [{ vector: [0.1, 0.1, 0.1, 0.1] }],
-        topK: 10,
+        limit: 10,
         filter: { id: "minimal-doc" },
       });
 
@@ -311,7 +311,7 @@ describe("Lifecycle edge cases integration tests", () => {
       // Verify exists
       let hits = await index.query({
         query: [{ vector: [0.9, 0.9, 0.9, 0.9] }],
-        topK: 10,
+        limit: 10,
         filter: { id: "to-delete" },
       });
       expect(hits.length).toBe(1);
@@ -324,7 +324,7 @@ describe("Lifecycle edge cases integration tests", () => {
       // Verify gone
       hits = await index.query({
         query: [{ vector: [0.9, 0.9, 0.9, 0.9] }],
-        topK: 10,
+        limit: 10,
         filter: { id: "to-delete" },
       });
       expect(hits.length).toBe(0);
@@ -361,7 +361,7 @@ describe("Lifecycle edge cases integration tests", () => {
 
       const hits = await index.query({
         query: [{ vector: [0.1, 0.2, 0.3, 0.4] }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits).toEqual([]);
@@ -382,20 +382,20 @@ describe("Lifecycle edge cases integration tests", () => {
       // Query with filter that matches nothing
       const hits = await index.query({
         query: [{ vector: [0.1, 0.1, 0.1, 0.1] }],
-        topK: 10,
+        limit: 10,
         filter: { id: "nonexistent-id" },
       });
 
       expect(hits).toEqual([]);
     });
 
-    it("topK of 0 throws", async () => {
+    it("limit of 0 throws", async () => {
       const index = tpuf.index(indexId);
 
       await expect(
         index.query({
           query: [{ vector: [0.1, 0.1, 0.1, 0.1] }],
-          topK: 0,
+          limit: 0,
         }),
       ).rejects.toThrow();
     });
@@ -453,7 +453,7 @@ describe("Lifecycle edge cases integration tests", () => {
       await expect(
         index.query({
           query: [{ vector: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] }], // 8 dims
-          topK: 10,
+          limit: 10,
         }),
       ).rejects.toThrow();
 

package/src/__tests__/integration/memory.integration.test.ts

@@ -229,7 +229,7 @@ describe.sequential(
       expect(results[0].document?.id).toBe(id1);
     });
 
-    it("respects topK limit", async () => {
+    it("respects limit", async () => {
       const ns = uid("ns");
 
       await agent.memories.create({

package/src/__tests__/integration/query.integration.test.ts

@@ -2,7 +2,7 @@
  * Comprehensive query modes integration tests.
  *
  * Tests vector search, BM25 text search, hybrid queries, fusion modes,
- * topK behavior, include semantics, and rank ordering against real Turbopuffer API.
+ * limit behavior, include semantics, and rank ordering against real Turbopuffer API.
  */
 
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
@@ -138,7 +138,7 @@ describe("Query modes integration tests", () => {
       // Query with basis vector 1 - should match vec-1 best
       const hits = await index.query({
         query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBeGreaterThan(0);
@@ -149,7 +149,7 @@ describe("Query modes integration tests", () => {
       // Query with basis vector 2
       const hits = await index.query({
         query: [{ vector: [0.0, 1.0, 0.0, 0.0] }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBeGreaterThan(0);
@@ -165,7 +165,7 @@ describe("Query modes integration tests", () => {
       // Query with mix of basis 1 and 2 - should prefer vec-5 which has [0.5, 0.5, 0, 0]
       const hits = await index.query({
         query: [{ vector: [0.5, 0.5, 0.0, 0.0] }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBeGreaterThan(0);
@@ -174,33 +174,33 @@ describe("Query modes integration tests", () => {
   });
 
   // ============================================================
-  // TOPK BEHAVIOR
+  // LIMIT BEHAVIOR
   // ============================================================
 
-  describe("topK behavior", () => {
-    it("topK smaller than doc count returns exactly topK", async () => {
+  describe("limit behavior", () => {
+    it("limit smaller than doc count returns exactly limit", async () => {
       const hits = await index.query({
         query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 3,
+        limit: 3,
       });
 
       expect(hits.length).toBe(3);
     });
 
-    it("topK larger than doc count returns all docs", async () => {
+    it("limit larger than doc count returns all docs", async () => {
       const hits = await index.query({
         query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 100,
+        limit: 100,
       });
 
       // We have 6 docs
       expect(hits.length).toBe(6);
     });
 
-    it("topK of 1 returns single best match", async () => {
+    it("limit of 1 returns single best match", async () => {
       const hits = await index.query({
         query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
       });
 
       expect(hits.length).toBe(1);
@@ -216,7 +216,7 @@ describe("Query modes integration tests", () => {
     it("single field text query finds matching docs", async () => {
       const hits = await index.query({
         query: [{ title: "neural" }],
-        topK: 10,
+        limit: 10,
         include: ["title"],
       });
 
@@ -231,7 +231,7 @@ describe("Query modes integration tests", () => {
     it("content field text query finds matching docs", async () => {
       const hits = await index.query({
         query: [{ content: "transformer" }],
-        topK: 10,
+        limit: 10,
         include: ["content"],
       });
 
@@ -243,7 +243,7 @@ describe("Query modes integration tests", () => {
     it("multi-field text query searches both fields", async () => {
       const hits = await index.query({
         query: [{ title: "database" }, { content: "database" }],
-        topK: 10,
+        limit: 10,
         include: ["title", "content"],
       });
 
@@ -256,7 +256,7 @@ describe("Query modes integration tests", () => {
     it("text query with no matches returns empty", async () => {
       const hits = await index.query({
         query: [{ content: "xyznonexistentkeyword123" }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBe(0);
@@ -272,7 +272,7 @@ describe("Query modes integration tests", () => {
       await expect(
         index.query({
           query: [{ vector: [1.0, 0.0, 0.0, 0.0] }, { content: "search" }],
-          topK: 10,
+          limit: 10,
         }),
       ).rejects.toThrow(/does not support hybrid/);
     });
@@ -284,7 +284,7 @@ describe("Query modes integration tests", () => {
             { vector: [1.0, 0.0, 0.0, 0.0] },
             { vector: [0.0, 1.0, 0.0, 0.0] },
           ],
-          topK: 10,
+          limit: 10,
         }),
       ).rejects.toThrow(/does not support multi-vector/);
     });
@@ -298,7 +298,7 @@ describe("Query modes integration tests", () => {
     it("Sum fusion combines multiple BM25 signals", async () => {
       const hits = await index.query({
         query: [{ title: "database" }, { content: "database" }],
-        topK: 10,
+        limit: 10,
         include: ["title", "content"],
       });
 
@@ -311,7 +311,7 @@ describe("Query modes integration tests", () => {
     it("Max fusion takes best BM25 signal per doc", async () => {
       const hits = await index.query({
         max: [{ title: "neural" }, { content: "neural" }],
-        topK: 10,
+        limit: 10,
         include: ["title", "content"],
       });
 
@@ -330,7 +330,7 @@ describe("Query modes integration tests", () => {
     it("include: true returns all attributes", async () => {
       const hits = await index.query({
         query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
         include: true,
       });
 
@@ -345,7 +345,7 @@ describe("Query modes integration tests", () => {
     it("include: false returns only id", async () => {
       const hits = await index.query({
         query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
         include: false,
       });
 
@@ -358,7 +358,7 @@ describe("Query modes integration tests", () => {
     it("include: [fields] returns only specified fields", async () => {
       const hits = await index.query({
         query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
         include: ["title", "category"],
       });
 
@@ -374,7 +374,7 @@ describe("Query modes integration tests", () => {
     it("include: [] returns only id", async () => {
       const hits = await index.query({
         query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
         include: [],
       });
 
@@ -393,7 +393,7 @@ describe("Query modes integration tests", () => {
     it("filter by category", async () => {
       const hits = await index.query({
         query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
         filter: { category: "ml" },
         include: ["category"],
       });
@@ -407,7 +407,7 @@ describe("Query modes integration tests", () => {
     it("filter by priority range", async () => {
       const hits = await index.query({
         query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
         filter: { priority: { $gte: 3, $lte: 5 } },
         include: ["priority"],
       });
@@ -422,7 +422,7 @@ describe("Query modes integration tests", () => {
     it("filter with $or", async () => {
       const hits = await index.query({
         query: [{ vector: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
         filter: {
           $or: [{ category: "ml" }, { category: "search" }],
         },
@@ -444,7 +444,7 @@ describe("Query modes integration tests", () => {
     it("results have required fields", async () => {
       const hits = await index.query({
         query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
       });
 
       expect(hits.length).toBe(1);
@@ -458,7 +458,7 @@ describe("Query modes integration tests", () => {
     it("score is a valid number", async () => {
       const hits = await index.query({
         query: [{ vector: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 5,
+        limit: 5,
       });
 
       for (const hit of hits) {

package/src/__tests__/query.test.ts

@@ -210,29 +210,29 @@ describe("QUERY", () => {
   // ============================================================
 
   describe("query options", () => {
-    describe("topK", () => {
-      it("encodes topK as top_k", () => {
+    describe("limit", () => {
+      it("encodes limit as top_k", () => {
         const result = QUERY.encode({
           query: [{ vector: [0.1] }],
-          topK: 10,
+          limit: 10,
         });
 
         expect(result.top_k).toBe(10);
       });
 
-      it("encodes topK of 1", () => {
+      it("encodes limit of 1", () => {
         const result = QUERY.encode({
           query: [{ vector: [0.1] }],
-          topK: 1,
+          limit: 1,
         });
 
         expect(result.top_k).toBe(1);
       });
 
-      it("encodes large topK", () => {
+      it("encodes large limit", () => {
         const result = QUERY.encode({
           query: [{ vector: [0.1] }],
-          topK: 10000,
+          limit: 10000,
         });
 
         expect(result.top_k).toBe(10000);
@@ -342,7 +342,7 @@ describe("QUERY", () => {
       it("encodes all options together", () => {
         const result = QUERY.encode({
           query: [{ vector: [0.1, 0.2] }],
-          topK: 20,
+          limit: 20,
           filter: { category: "news" },
           include: ["title", "summary"],
         });
@@ -405,7 +405,7 @@ describe("QUERY", () => {
       // Direct codec call with empty array returns params without rank_by.
       const result = QUERY.encode({
         query: [],
-        topK: 10,
+        limit: 10,
       });
 
       expect(result.rank_by).toBeUndefined();
@@ -414,7 +414,7 @@ describe("QUERY", () => {
 
     it("returns params without rank_by when no query or max", () => {
       const result = QUERY.encode({
-        topK: 10,
+        limit: 10,
         filter: { status: "active" },
       });
 

package/src/convert/query.ts

@@ -31,9 +31,9 @@ export const QUERY = {
       params.rank_by = buildRankBy(signals, query.max !== undefined);
     }
 
-    // top K
-    if (query.topK !== undefined) {
-      params.top_k = query.topK;
+    // limit
+    if (query.limit !== undefined) {
+      params.top_k = query.limit;
     }
 
     // filters

package/src/search.ts

@@ -49,7 +49,7 @@ import { INDEX_SCHEMA, SIMILARITY } from "./convert";
  *
  * const hits = await docs.query({
  *   query: [{ vector: [0.1, 0.2, ...] }],
- *   topK: 10,
+ *   limit: 10,
  * });
  * ```
  */