chore(storage): pre-merge polish from final review (easy minors)

Six low-risk follow-ups from the final pre-merge review. Nothing here
changes behaviour beyond error wording and JSDoc; the public API
surface tightens slightly.

#4 Hide cursor format internals from the public API.
   `common.ts` switches the Cursor module from `export *` to a
   selective re-export of `PageCursor`, `encodeCursor`, `decodeCursor`,
   `assertCursorMatches`, and `MAX_CURSOR_LENGTH`. `CursorPayload`
   (the wire shape) and `CURSOR_VERSION` (the format integer) are now
   internal-only — callers can't depend on the encoding format, which
   keeps it free to evolve. The unit test inlines the version constant.

#6 ScopedTabularStorage emits `query` from `getPage`/`queryPage`.
   Cache invalidators that listen for tabular reads were missing
   page reads. Switching a caller from `query` to `getPage` would
   silently invalidate their invalidation logic. The emitted criteria
   is the user-facing criteria (without our injected `kb_id`).

#7 Document `pages()` defensive `.slice()`.
   The async generator yields a fresh copy of `Page.items` per page so
   callers can't poison subsequent iterations by mutating the yielded
   array. JSDoc now says so.

#8 Cursor JSON-roundtrip test.
   Pins the contract that cursors are safe to persist and re-load
   across process boundaries (URLs, durable queues, etc). The codec is
   pure so this should always work, but a one-line test locks it in.

#10 Hoist the `jsToSqlValue` coupling note.
   `ITabularStorage.query` JSDoc now spells out the third-party-backend
   implementation contract: bind SearchCondition values through the
   same conversion path as row values going *into* the store, so the
   cursor pagination machinery's round-trip comparison works.

#11 More actionable `StorageInvalidLimitError` message.
   Says "must be a positive integer, got X" instead of "must be greater
   than 0, got X" so a user staring at `limit: 1.5` knows fractional
   values are the problem.

914 vitest storage / 934 bun-native / 22 scoped storage / 322 queue
tests pass. Pre-existing build issues on `chrome-ai` (from main's
`bootstrapWorkglow` refactor) and the `KnowledgeBaseRegistry`
`registerInputResolver` arity mismatch are unaffected and unchanged.

Author: claude

packages/knowledge-base/src/knowledge-base/ScopedTabularStorage.ts

@@ -183,6 +183,12 @@ export class ScopedTabularStorage<
     const scopedCriteria = { ...((criteria ?? {}) as any), kb_id: this.kbId };
     const innerPage = await this.inner.queryPage(scopedCriteria, request as any);
     const items = innerPage.items.map((row: any) => this.strip(row)) as Entity[];
+    // Emit `query` for parity with `ScopedTabularStorage.query`. Cache
+    // invalidators that listen for tabular reads need to see page reads
+    // too; otherwise switching a caller from `query` to `getPage` would
+    // silently invalidate their invalidation logic. The emitted criteria
+    // is the *user-facing* criteria (without our injected `kb_id`).
+    this.events.emit("query", (criteria ?? {}) as Partial<Entity>, items);
     return { items, nextCursor: innerPage.nextCursor };
   }
 

packages/storage/src/common.ts

@@ -14,7 +14,13 @@ export type {
   PickCoveringIndexInput,
   PickedIndex,
 } from "./tabular/coveringIndexPicker";
-export * from "./tabular/Cursor";
+// Cursor codec: the public surface is the opaque type, the codec
+// functions, the length cap, and the cross-arity assertion. The
+// payload shape and version constant are implementation details —
+// keep them out of `@workglow/storage`'s public API so callers can't
+// depend on the encoding format and we stay free to evolve it.
+export { encodeCursor, decodeCursor, assertCursorMatches, MAX_CURSOR_LENGTH } from "./tabular/Cursor";
+export type { PageCursor } from "./tabular/Cursor";
 export * from "./tabular/HuggingFaceTabularStorage";
 export * from "./tabular/InMemoryTabularStorage";
 export * from "./tabular/ITabularStorage";

packages/storage/src/tabular/BaseTabularStorage.ts

@@ -463,6 +463,9 @@ export abstract class BaseTabularStorage<
    * Async generator that yields pages of records.
    *
    * Backed by cursor-based pagination — stable under concurrent writes.
+   * Each yielded array is a fresh copy of `Page.items`; mutating the
+   * yielded array won't affect the underlying storage or subsequent
+   * pages, at the cost of one allocation per page.
    *
    * @param pageSize - Number of records per page (default: 100)
    */

packages/storage/src/tabular/ITabularStorage.ts

@@ -360,6 +360,15 @@ export interface ITabularStorage<
    * Queries entries matching the specified search criteria with optional ordering, limit, and offset.
    * Uses optimized index paths when possible, falls back to full scan otherwise.
    *
+   * Implementation contract for third-party backends: when binding a
+   * `SearchCondition` value into the underlying datastore, run it
+   * through the same conversion path as a row value going *into* the
+   * store (e.g. `jsToSqlValue` for SQL backends — Date → ISO string,
+   * etc.). The cursor pagination machinery in {@link getPage} relies
+   * on this round-trip to compare a row's stored representation
+   * against a cursor's decoded value; any backend that skips the
+   * conversion would silently mis-page on Date or other rich types.
+   *
    * @param criteria - Object with column names as keys and values or SearchConditions
    * @param options - Optional ordering, limit, and offset options
    * @returns Array of matching entities or undefined if no matches found

packages/storage/src/tabular/StorageError.ts

@@ -24,7 +24,12 @@ export class StorageEmptyCriteriaError extends StorageValidationError {
 export class StorageInvalidLimitError extends StorageValidationError {
   static override readonly type: string = "StorageInvalidLimitError";
   constructor(limit: number) {
-    super(`Query limit must be greater than 0, got ${limit}`);
+    // Message names both constraints (positive AND integer) so callers
+    // hitting the error from `runPage` (which rejects non-integer limits)
+    // see the same wording as offset paths — and a user staring at
+    // `limit: 1.5` isn't left guessing that fractional values are the
+    // problem.
+    super(`Query limit must be a positive integer, got ${limit}`);
   }
 }
 

packages/test/src/test/storage-tabular/Cursor.test.ts

@@ -6,13 +6,17 @@
 
 import { describe, expect, it } from "vitest";
 import {
-  CURSOR_VERSION,
   MAX_CURSOR_LENGTH,
   decodeCursor,
   encodeCursor,
   StorageValidationError,
 } from "@workglow/storage";
 
+// Pinned in the unit test rather than imported from `@workglow/storage`:
+// the cursor format version is an implementation detail of the codec
+// (kept out of the package's public API to leave room for evolution).
+const CURSOR_FORMAT_VERSION = 1;
+
 describe("Cursor codec", () => {
   it("round-trips a payload through encode → decode", () => {
     const payload = {
@@ -104,7 +108,7 @@ describe("Cursor codec", () => {
       .replace(/=+$/, "");
     expect(() => decodeCursor(future)).toThrow(StorageValidationError);
     expect(() => decodeCursor(future)).toThrow(
-      new RegExp(`expected v${CURSOR_VERSION}`)
+      new RegExp(`expected v${CURSOR_FORMAT_VERSION}`)
     );
   });
 
@@ -125,4 +129,19 @@ describe("Cursor codec", () => {
     const cursor = encodeCursor({ v: 1, n: ["x", "y"], c: [null, "z"] });
     expect(decodeCursor(cursor)).toEqual({ v: 1, n: ["x", "y"], c: [null, "z"] });
   });
+
+  it("survives a JSON.stringify → JSON.parse round-trip", () => {
+    // Cursors are designed to be safe to persist and re-load across
+    // process boundaries (URLs, durable queues, etc). The codec is pure
+    // — no in-memory state — so transport via JSON should be lossless.
+    // Pin that contract here.
+    const original = encodeCursor({
+      v: 1,
+      n: ["createdAt", "id"],
+      c: ["2026-01-02T03:04:05.000Z", "abc"],
+    });
+    const transported = JSON.parse(JSON.stringify({ cursor: original })).cursor;
+    expect(transported).toBe(original);
+    expect(decodeCursor(transported)).toEqual(decodeCursor(original));
+  });
 });