@abloatai/transaction 0.51.0 → 0.53.0

package/src/auth/index.ts

@@ -12,6 +12,8 @@
 import {
   type EphemeralKeyResponse,
   type IdentityResolveResponse,
+  type SessionCredentialMetadata,
+  type SessionCredentialRevocationRequest,
   parseCapabilityMintResponse,
   parseEphemeralKeyResponse,
   parseIdentityResolveResponse,
@@ -27,7 +29,17 @@ export {
   ABLO_HOSTED_API_DOMAIN,
   ABLO_HOSTED_HTTP_BASE_URL,
 } from './hostedEndpoints.js';
-export { normalizeAbloHostedBaseUrl } from './apiKey.js';
+export { normalizeAbloBaseUrl } from './baseUrl.js';
+// A re-export does not bind the name in this module; the alias below needs it.
+import { normalizeAbloBaseUrl } from './baseUrl.js';
+
+/**
+ * @deprecated Renamed to {@link normalizeAbloBaseUrl}. Removed in 0.54.0.
+ * The "hosted" spelling named a rewrite of retired hosted hostnames that no
+ * longer exists; both spellings resolve through the one function, so a caller
+ * on the old name gets the same refusals of unsafe credential destinations.
+ */
+export const normalizeAbloHostedBaseUrl = normalizeAbloBaseUrl;
 
 /**
  * @deprecated Use {@link CapabilityMintResponse}. This is a type-only,
@@ -39,6 +51,26 @@ export type CapabilityExchangeResponse = CapabilityMintResponse;
 export type {
   EphemeralKeyResponse,
   IdentityResolveResponse,
+  SessionCredentialMetadata,
+  SessionCredentialRevocationRequest,
+} from './schemas.js';
+export {
+  buildSessionIssuanceMacMessage,
+  canonicalizeSessionIssuanceBody,
+  opaqueSessionFingerprintSchema,
+  sha256HexSchema,
+  SESSION_ISSUANCE_HEADERS,
+  SESSION_ISSUANCE_MAC_VERSION,
+  SESSION_ISSUANCE_PATHS,
+  SESSION_ISSUANCE_SLOT_VERSION,
+  sessionIssuanceMacHeadersSchema,
+  sessionIssuanceMacMessageSchema,
+  type SessionIssuanceMacHeaders,
+  type SessionIssuanceMacMessage,
+} from './sessionIssuanceProtocol.js';
+export {
+  SessionCredentialMetadataSchema,
+  SessionCredentialRevocationRequestSchema,
 } from './schemas.js';
 export { parseCapabilityMintResponse } from './schemas.js';
 export {
@@ -99,6 +131,10 @@ export type {
 // A re-export does not bind the name in this module, and the mint request type
 // below needs it.
 import type { CapabilityOperation } from './capability.js';
+import {
+  ephemeralKeyRequestSchema,
+  type EphemeralKeyRequest,
+} from '../wire/auth.js';
 
 export interface ExchangeApiKeyRequest {
   readonly apiKey: string;
@@ -265,6 +301,30 @@ export type MintUserSessionRequest = MintUserSessionBase & {
   readonly controlPlaneOnly?: true;
 };
 
+/** Canonical wire projection shared by the SDK and first-party issuer. */
+export function buildMintUserSessionRequest(
+  options: MintUserSessionRequest,
+): EphemeralKeyRequest {
+  return ephemeralKeyRequestSchema.parse({
+    user: { id: options.userId },
+    ...(options.organizationId ? { organizationId: options.organizationId } : {}),
+    ...(options.schemaProject
+      ? {
+          schemaProjectId: options.schemaProject.projectId,
+          schemaOwnerOrgId: options.schemaProject.organizationId,
+        }
+      : {}),
+    ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
+    ...(options.controlPlaneOnly
+      ? { controlPlaneOnly: true }
+      : options.operations
+        ? { operations: options.operations }
+        : { activeSchemaOperations: options.activeSchemaOperations }),
+    ttlSeconds: options.ttlSeconds,
+    ...(options.label ? { label: options.label } : {}),
+  });
+}
+
 /**
  * Mints an end-user session key (an `ek_` key) by calling
  * `POST /v1/ephemeral_keys`, using your secret key as authorization. Your
@@ -322,26 +382,7 @@ export async function mintUserSessionKey(
         'Content-Type': 'application/json',
         Authorization: `Bearer ${options.apiKey}`,
       },
-      body: JSON.stringify({
-        user: { id: options.userId },
-        ...(options.organizationId ? { organizationId: options.organizationId } : {}),
-        // The public option is project-centric; map it to the flat wire keys the
-        // endpoint expects.
-        ...(options.schemaProject
-          ? {
-              schemaProjectId: options.schemaProject.projectId,
-              schemaOwnerOrgId: options.schemaProject.organizationId,
-            }
-          : {}),
-        ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
-        ...(options.controlPlaneOnly
-          ? { controlPlaneOnly: true }
-          : options.operations
-            ? { operations: options.operations }
-            : { activeSchemaOperations: options.activeSchemaOperations }),
-        ttlSeconds: options.ttlSeconds,
-        ...(options.label ? { label: options.label } : {}),
-      }),
+      body: JSON.stringify(buildMintUserSessionRequest(options)),
       signal: controller.signal,
     });
   } catch (err) {

package/src/auth/schemas.ts

@@ -9,6 +9,7 @@ import {
 import { AbloAuthenticationError } from '../errors.js';
 import { authTokenSchema } from './token.js';
 import { deliveryPartitionRouteSchema } from './deliveryPartition.js';
+import { opaqueSessionFingerprintSchema } from './sessionIssuanceProtocol.js';
 
 // Not a second enum. The auth responses carry the same participant vocabulary
 // the coordination plane parses, so they validate against the same schema — a
@@ -40,10 +41,9 @@ export type IdentityResolveResponse = z.infer<typeof IdentityResolveResponseSche
  * block. It still echoes the effective operations stored on the key so the
  * client reports enforced authority rather than reconstructing it from input.
  */
-export const EphemeralKeyResponseSchema = z.object({
+export const SessionCredentialMetadataSchema = z.object({
   object: z.literal('ephemeral_key').optional(),
   id: z.string().min(1),
-  token: authTokenSchema,
   expiresAt: z.string().min(1),
   organizationId: z.string().min(1),
   participantId: z.string().min(1),
@@ -67,6 +67,20 @@ export const EphemeralKeyResponseSchema = z.object({
   },
 );
 
+/** Persistable/replayable projection of the canonical mint response. */
+export type SessionCredentialMetadata = z.infer<typeof SessionCredentialMetadataSchema>;
+
+export const SessionCredentialRevocationRequestSchema = z.object({
+  parentSessionHash: opaqueSessionFingerprintSchema,
+});
+export type SessionCredentialRevocationRequest = z.infer<
+  typeof SessionCredentialRevocationRequestSchema
+>;
+
+export const EphemeralKeyResponseSchema = SessionCredentialMetadataSchema.safeExtend({
+  token: authTokenSchema,
+});
+
 export type EphemeralKeyResponse = z.infer<typeof EphemeralKeyResponseSchema>;
 
 function formatIssues(error: z.ZodError): string {

package/src/auth/sessionIssuanceProtocol.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { stableStringify } from '../utils/json.js';
+
+/** Bump only with a coordinated MAC-message protocol rollout. */
+export const SESSION_ISSUANCE_MAC_VERSION = 'v1' as const;
+/** Bump whenever canonical mint semantics change incompatibly. */
+export const SESSION_ISSUANCE_SLOT_VERSION = 'v1' as const;
+
+export const SESSION_ISSUANCE_PATHS = {
+  mint: '/api/v1/ephemeral_keys',
+  revoke: '/api/v1/internal/session-credentials/revoke',
+} as const;
+
+export const SESSION_ISSUANCE_HEADERS = {
+  slotKey: 'ablo-session-slot',
+  parentSessionHash: 'ablo-parent-session',
+  timestamp: 'ablo-session-issuance-timestamp',
+  mac: 'ablo-session-issuance-mac',
+} as const;
+
+export const sha256HexSchema = z.string().regex(/^[a-f0-9]{64}$/);
+export const opaqueSessionFingerprintSchema = sha256HexSchema;
+
+export const sessionIssuanceMacHeadersSchema = z.object({
+  timestamp: z.string().regex(/^\d{13}$/),
+  mac: sha256HexSchema,
+});
+export type SessionIssuanceMacHeaders = z.infer<typeof sessionIssuanceMacHeadersSchema>;
+
+export const sessionIssuanceMacMessageSchema = z.object({
+  method: z.enum(['POST']),
+  path: z.enum([SESSION_ISSUANCE_PATHS.mint, SESSION_ISSUANCE_PATHS.revoke]),
+  timestamp: z.string().regex(/^\d{13}$/),
+  bodySha256: sha256HexSchema,
+  slotKey: opaqueSessionFingerprintSchema.optional(),
+  parentSessionHash: opaqueSessionFingerprintSchema,
+});
+export type SessionIssuanceMacMessage = z.infer<typeof sessionIssuanceMacMessageSchema>;
+
+/** One canonical JSON representation for slot derivation and request MACs. */
+export function canonicalizeSessionIssuanceBody(body: unknown): string {
+  return stableStringify(body);
+}
+
+/** Canonical, bounded KMS GenerateMac/VerifyMac message (well below 4 KiB). */
+export function buildSessionIssuanceMacMessage(input: SessionIssuanceMacMessage): Uint8Array {
+  const value = sessionIssuanceMacMessageSchema.parse(input);
+  return new TextEncoder().encode([
+    `ablo-session-issuance:${SESSION_ISSUANCE_MAC_VERSION}`,
+    value.method,
+    value.path,
+    value.timestamp,
+    value.bodySha256,
+    value.slotKey ?? '',
+    value.parentSessionHash,
+  ].join('\n'));
+}

package/src/auth/sessionMint.ts

@@ -13,8 +13,8 @@
  *                 participant with `invalid_participant_kind`.
  *   `{ agent }` → POST /v1/capabilities, returning an `rk_` key scoped to exactly
  *                 the operations named in `can`. For example
- *                 `can: { tasks: ['update'] }` becomes the wire allowlist entry
- *                 `tasks.update`, which the server matches against the model's
+ *                 `can: { items: ['update'] }` becomes the wire allowlist entry
+ *                 `items.update`, which the server matches against the model's
  *                 registered names.
  *
  * The caller supplies the already-resolved secret key and base URL in

package/src/branches.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { listEnvelopeSchema } from './wire/listEnvelope.js';
 
 /**
  * A branch handle is for people and URLs. Durable routing always uses the
@@ -47,10 +48,7 @@ export const branchResponseSchema = z.object({
 });
 export type BranchResponse = z.infer<typeof branchResponseSchema>;
 
-export const branchListResponseSchema = z.object({
-  object: z.literal('list'),
-  data: z.array(branchResponseSchema).readonly(),
-});
+export const branchListResponseSchema = listEnvelopeSchema(branchResponseSchema);
 export type BranchListResponse = z.infer<typeof branchListResponseSchema>;
 
 export const createBranchRequestSchema = z.object({

package/src/coordination/schema.ts

@@ -61,7 +61,7 @@ export function part(name: string): ClaimPart {
  * The wire spelling of a part name, from whichever spelling the caller used.
  *
  * Three, because they are three different promises. A {@link FieldRef} —
- * `schema.fields.tasks.status` — is a field the schema declares, so a name that
+ * `schema.fields.items.status` — is a field the schema declares, so a name that
  * does not exist never compiles. `part('B2')` is a name the schema does not
  * know and says so. A bare string is neither, and survives only because the
  * erased `SchemaRecord` view and untyped callers still need it.
@@ -330,7 +330,7 @@ const syncIdSchema = z.number().int().nonnegative();
  *
  *   • `self`       — the row that moved IS the group's scope root.
  *   • `parent`     — it sits one declared containment edge below the root.
- *   • `transitive` — the root is ≥2 hops up (`comment → task → project`).
+ *   • `transitive` — the root is ≥2 hops up (`comment → item → project`).
  */
 export const stalePropagationSchema = z
   .object({
@@ -1417,6 +1417,11 @@ export const commitOperationSchema = writeGuardSchema.extend({
   model: z.string(),
   id: z.string().nullish(),
   input: z.record(z.string(), z.unknown()).nullish(),
+  /** Equality conditions evaluated atomically by the writing database. */
+  where: z
+    .record(z.string().min(1), z.unknown())
+    .refine((value) => Object.keys(value).length > 0, 'where must name at least one field')
+    .nullish(),
   /** Per-op client tx id, echoed on the broadcast delta. */
   transactionId: z.string().nullish(),
   /**

package/src/errorCodes.ts

@@ -39,7 +39,7 @@ import { z } from 'zod';
  * error documentation and returned on the `Ablo-Version` response header, so a
  * consumer can detect when its expected contract has drifted from the server's.
  */
-export const ERROR_CONTRACT_VERSION = '2026-08-04';
+export const ERROR_CONTRACT_VERSION = '2026-08-15';
 
 /** A coarse grouping of error codes, used to organize metrics and documentation. */
 export type ErrorCategory =
@@ -604,6 +604,12 @@ export const ERROR_CODES = {
     false,
     'An earlier attempt under this idempotency key was pinned to a different source transport. Restore that route and retry the same key; Ablo will not switch a possibly committed write.'
   ),
+  precondition_failed: wire(
+    'conflict',
+    409,
+    false,
+    'A conditional operation did not match the current database row. The complete atomic commit was rejected and no operation in the batch was applied.'
+  ),
   idempotency_key_too_long: wire(
     'validation',
     400,
@@ -815,11 +821,11 @@ export const ERROR_CODES = {
     false,
     'The branch has no endpoint Data Source for this connector to serve. Run `ablo dev --local` with the current CLI, which registers the connector-only source before opening the socket.'
   ),
-  task_id_missing: wire(
+  item_id_missing: wire(
     'server',
     502,
     true,
-    'The task-create response arrived without a task id, so the result cannot be used. Retry the request.'
+    'The item-create response arrived without an item id, so the result cannot be used. Retry the request.'
   ),
 
   // ── data integrity / database constraints ──────────────────────────
@@ -864,6 +870,12 @@ export const ERROR_CODES = {
     false,
     'A structured (JSON) value was written to a column whose database type cannot hold it. Ablo adapts a json field to either a jsonb column (native) or a text column (serialized) — but a scalar column (integer, boolean, uuid, timestamp, …) cannot store a JSON object or array. Use a jsonb or text column for this field. Ablo adapts to your column; it does not alter your schema.'
   ),
+  column_value_out_of_range: wire(
+    'validation',
+    400,
+    false,
+    'A stored value is outside the range the field was declared to hold. A number field reads back as a JavaScript number, which represents integers exactly only up to 9,007,199,254,740,991; a bigint column holding more than that would come back rounded. Declare the field as text to read those values digit for digit.'
+  ),
 
   // ── tenant / unknown model (400) ───────────────────────────────────
   server_execute_unknown_model: wire(
@@ -918,7 +930,7 @@ export const ERROR_CODES = {
   ),
   schema_reserved_field: client(
     'schema',
-    'A model redeclared a reserved base field (id, createdAt, updatedAt, organizationId, createdBy) that the SDK provides automatically.'
+    'A model declared `id`, the one universal field Ablo supplies. Remove it from the declared application fields.'
   ),
   schema_grants_shape_invalid: wire(
     'schema',
@@ -1611,6 +1623,18 @@ export const ERROR_CODES = {
     false,
     'The query contained an invalid identifier.'
   ),
+  query_relation_expansion_too_large: wire(
+    'validation',
+    400,
+    false,
+    'A requested relation expansion exceeds the bounded nested-row budget. Query the related model as its own paginated collection instead.'
+  ),
+  organization_disabled: wire(
+    'permission',
+    403,
+    false,
+    'This organization has been disabled by an operator. Contact support before retrying.'
+  ),
   org_id_required: wire(
     'validation',
     400,
@@ -1647,7 +1671,7 @@ export const ERROR_CODES = {
     false,
     'Uploads are not configured on this deployment: the upload storage bucket and CDN domain are unset.'
   ),
-  task_id_required: wire('validation', 400, false, 'A task id is required for this request.'),
+  item_id_required: wire('validation', 400, false, 'An item id is required for this request.'),
   claim_id_required: wire('validation', 400, false, 'A claim id is required for this request.'),
   commit_operation_action_required: wire(
     'validation',

package/src/errors.ts

@@ -67,7 +67,7 @@ export class AbloError extends Error {
   /** Opaque id of the exact private observation associated with this error. */
   readonly eventId?: string;
   /** The specific input that caused the error, as a model or field path such as
-   *  `'dataroomMember.grants.subject'`, so tooling can point at the exact
+   *  `'archiveMember.grants.subject'`, so tooling can point at the exact
    *  offending value. */
   readonly param?: string;
   /** A link to the documentation for this error's {@link code}. When not set

package/src/index.ts

@@ -35,6 +35,8 @@ export type {
   HttpModelClient,
   HttpModelMutationParams,
 } from './transport/httpClient.js';
+/** What `ablo.<model>.list()` resolves to: the rows, and where the page ends. */
+export type { ModelList } from './resources/httpResources.js';
 export type {
   FunctionalUpdateOptions,
   /** @deprecated Use `FunctionalUpdateOptions`. */

package/src/resources/httpResources.ts

@@ -101,9 +101,51 @@ export interface HttpTransportRead<T = Record<string, unknown>> {
 /** @internal Exact collection envelope retained until the typed facade captures evidence. */
 export interface HttpTransportList<T = Record<string, unknown>> {
   readonly data: readonly T[];
+  /**
+   * Whether the collection continues past this page. A list read is always a
+   * page — the server applies a default size and caps the largest one — so a
+   * caller that treats `data` as the whole set is right only while this is
+   * `false`. It used to be dropped on the floor here, which made a truncated
+   * read indistinguishable from a complete one.
+   */
+  readonly hasMore: boolean;
+  /**
+   * The cursor to pass back as `cursor` for the next page, or `null` at the end
+   * of the collection.
+   */
+  readonly nextCursor: string | null;
   readonly evidence?: readonly ModelListEvidence[];
 }
 
+/**
+ * What a collection read hands back: the rows, and where the collection stands.
+ *
+ * It is an array, so it maps, filters, spreads, and iterates like the rows it
+ * always was. `hasMore` and `nextCursor` ride along as non-enumerable
+ * properties, which keeps `JSON.stringify` and a spread producing exactly the
+ * array they produced before.
+ *
+ * They ride along because a list read is a page: the server applies a default
+ * size and caps the largest one. Returning only the rows made a truncated read
+ * and a complete one the same value, so the caller with 500 matching rows got
+ * 20 and no way to find out.
+ */
+export type ModelList<T> = T[] & Pick<HttpTransportList<T>, 'hasMore' | 'nextCursor'>;
+
+/**
+ * Attach the page state to the rows. Non-enumerable so the result stays
+ * indistinguishable from a plain array everywhere the properties aren't read.
+ */
+export function modelList<T>(
+  rows: readonly T[],
+  page: Pick<HttpTransportList<unknown>, 'hasMore' | 'nextCursor'>,
+): ModelList<T> {
+  return Object.defineProperties([...rows], {
+    hasMore: { value: page.hasMore, enumerable: false },
+    nextCursor: { value: page.nextCursor, enumerable: false },
+  }) as ModelList<T>;
+}
+
 export type IfClaimedPolicy = 'return' | 'fail';
 
 export interface ClaimedOptions {
@@ -170,6 +212,7 @@ export interface CommitOperationInput {
   readonly model: string;
   readonly id?: string | null;
   readonly data?: Record<string, unknown> | null;
+  readonly where?: Record<string, unknown> | null;
   readonly transactionId?: string | null;
   /** Claim identity derived from a held claim; not an application id. */
   readonly claimId?: string | null;
@@ -432,8 +475,8 @@ export interface CreateUserSessionParams<S extends SchemaRecord> {
 
 /** Mint params for a scoped **agent** session — mints a restricted `rk_` token
  *  gated to exactly the operations named in `can`. `can` is typed off your
- *  schema (no magic `'task.update'` strings): `{ Task: ['update'], Report: ['read'] }`
- *  — the SDK serializes each entry to the wire allowlist (`task.update`). */
+ *  schema (no magic `'item.update'` strings): `{ Item: ['update'], Report: ['read'] }`
+ *  — the SDK serializes each entry to the wire allowlist (`item.update`). */
 export interface CreateAgentSessionParams<S extends SchemaRecord> {
   /** Your agent. `id` becomes the token's `participantId`. */
   agent: { id: string };

package/src/resources/modelOperations.ts

@@ -205,7 +205,19 @@ export interface ServerReadOptions<T> {
    */
   where?: LoadWhere<T>;
   orderBy?: { [K in keyof T]?: 'asc' | 'desc' };
+  /**
+   * Rows per page. The server has its own ceiling and applies a default when
+   * this is omitted, so a collection larger than one page always comes back as
+   * a page: read `hasMore` on the result before treating it as the whole set.
+   */
   limit?: number;
+  /**
+   * Where to resume: the `nextCursor` from the previous page. Pass it back with
+   * the same `where` and `orderBy` to walk a collection; the cursor encodes the
+   * sort position it was issued for, so it is an opaque token rather than a row
+   * id, and a read that changes either starts a new walk.
+   */
+  cursor?: string;
   /**
    * `complete` waits for the server. `unknown` returns whatever is local
    * immediately and refreshes in the background.
@@ -256,7 +268,7 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
 
   /**
    * Narrow the claim to Zod-declared fields of the row. Return one field
-   * directly or an array for several: `fields: (task) => task.status`.
+   * directly or an array for several: `fields: (item) => item.status`.
    *
    * Exclusion follows the target: claims on the same row conflict only where
    * their sets intersect, so a holder on `['title']` and a holder on
@@ -313,7 +325,7 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
    * @deprecated Prefer `contention: { signal }`.
    *
    * Abort a pending wait from outside — the same signal that cancels
-   * everything else in the program, so a cancelled agent task or an unmounted
+   * everything else in the program, so a cancelled agent item or an unmounted
    * component takes its queued claim with it. Rejects with
    * {@link AbloClaimedError} (`claim_wait_aborted`); over HTTP the abort also
    * leaves the line. Ignored once the grant has arrived — a held lease is
@@ -327,7 +339,7 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
   ttl?: Duration;
   /**
    * Keep the lease alive for the duration of real work by beating on a
-   * cadence — the pattern for background workers whose task outlives the
+   * cadence — the pattern for background workers whose item outlives the
    * crash-cleanup TTL. `true` beats every third of the TTL (so two beats can
    * fail before the lease is at risk, and a crashed worker's lease still
    * lapses within one beat window); a duration such as `'2m'` sets the
@@ -431,12 +443,12 @@ export type ClaimSkipOptions<T = Record<string, unknown>> =
  * write and the SDK acquires/releases around that one mutation:
  *
  * ```ts
- * await ablo.tasks.update({
+ * await ablo.items.update({
  *   id,
  *   data: { title },
  *   claim: {
- *     fields: (task) => task.title,
- *     description: 'Renaming the task to match the project brief.',
+ *     fields: (item) => item.title,
+ *     description: 'Renaming the item to match the project brief.',
  *   },
  * });
  * ```

package/src/resources/where.ts

@@ -18,7 +18,13 @@ import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
 
 /** Primitive operand types allowed in a where clause. */
-export type WherePrimitive = string | number | boolean | null;
+export const wherePrimitiveSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+export type WherePrimitive = z.infer<typeof wherePrimitiveSchema>;
 
 /**
  * The comparison operators a {@link WhereClause} may use: equality and
@@ -93,6 +99,22 @@ export const WHERE_LIKE_OPS: ReadonlySet<WhereOp> = new Set<WhereOp>([
  * Returns the classification the caller needs next, so the check and the branch
  * are the same statement rather than two that can disagree.
  */
+/**
+ * Whether an operand is the array form the set operators take.
+ *
+ * `Array.isArray` answers this at runtime but not in the type system: its
+ * signature narrows to `any[]`, which drops both the `readonly` and the element
+ * type, so a compiler that reached for it lost the operand type it had just
+ * finished validating and handed `any` to everything downstream. Declared here
+ * because operand shape is this module's vocabulary — the same reason
+ * {@link classifyWhereOperand} lives here rather than in either plane.
+ */
+export function isWhereOperandList(
+  value: WherePrimitive | readonly WherePrimitive[] | undefined,
+): value is readonly WherePrimitive[] {
+  return Array.isArray(value);
+}
+
 export function classifyWhereOperand(
   op: WhereOp,
   value: unknown,
@@ -134,10 +156,27 @@ export function classifyWhereOperand(
  *
  * The value is a single primitive for scalar operators and an array of
  * primitives for IN/NOT IN.
+ *
+ * This is a schema rather than a bare type because the grammar crosses a
+ * boundary: a filtered read arrives at the collection route as text, and the
+ * route has to decide whether what it received is a clause before compiling it
+ * to SQL. Declaring the shape twice — once to check at the edge, once to type
+ * the interior — is how the two planes came to disagree about `IN`.
  */
-export type WhereClause =
-  | readonly [col: string, value: WherePrimitive]
-  | readonly [col: string, op: WhereOp, value: WherePrimitive | readonly WherePrimitive[]];
+export const whereClauseSchema = z.union([
+  z.tuple([z.string(), wherePrimitiveSchema]).readonly(),
+  z
+    .tuple([
+      z.string(),
+      whereOpSchema,
+      z.union([wherePrimitiveSchema, z.array(wherePrimitiveSchema).readonly()]),
+    ])
+    .readonly(),
+]);
+export type WhereClause = z.infer<typeof whereClauseSchema>;
+
+/** A whole filter as it travels: the AND-combined list of conditions. */
+export const whereClausesSchema = z.array(whereClauseSchema).readonly();
 
 /**
  * Client-facing where shape for `load({where})` and `deleteMany({where})`.
@@ -158,3 +197,30 @@ export type LoadWhere<T> =
   | Partial<T>
   | { [K in keyof T]?: T[K] | readonly T[K][] }
   | readonly WhereClause[];
+
+/**
+ * Collapse either accepted {@link LoadWhere} form to the canonical clause list.
+ * Tuple input passes through; object input becomes one `['col', '=', val]` per
+ * key, or `['col', 'IN', vals]` where the value is an array.
+ *
+ * Detection: an array is tuple form, an object is object form.
+ *
+ * Every transport funnels through this. It used to live beside the WebSocket
+ * loader, which left the HTTP transport to walk `Object.entries` itself — and
+ * that copy dropped any value it found to be an object, so an `IN` filter and
+ * every tuple-form clause were discarded in silence and the read came back
+ * unfiltered.
+ */
+export function normalizeWhere(where: unknown): readonly WhereClause[] {
+  if (where == null) return [];
+  // Tuple form — assumed to already use server-side column names.
+  if (Array.isArray(where)) return where as readonly WhereClause[];
+  if (typeof where === 'object') {
+    return Object.entries(where as Record<string, unknown>).map(([key, value]) =>
+      Array.isArray(value)
+        ? ([key, 'IN', value as readonly WherePrimitive[]] as WhereClause)
+        : ([key, value as WherePrimitive] as WhereClause),
+    );
+  }
+  return [];
+}