@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/resources/modelOperations.d.ts

@@ -0,0 +1,427 @@
+/**
+ * The request contract for `ablo.<model>` — the option and parameter shapes a
+ * caller passes to a read, a write, or a claim.
+ *
+ * These types describe the *change or the query being requested*, never a local
+ * copy of the rows it touches, so they sit in the settlement core and are shared
+ * by every transport and every caller (ADR 0013 §4, ADR 0016). The factory that
+ * binds them to reactive model instances — `createModelProxy` — stays with the
+ * reactive consumer, along with `ModelOperations` and `ModelCollaboration`,
+ * which reference the live participant handle.
+ */
+import type { ModelScope } from '../types/index.js';
+import type { ResolveClaimMeta } from '../types/global.js';
+import type { ClaimPart, StaleNotification, TrackDependency } from '../coordination/schema.js';
+import type { ClaimHeartbeatPlan } from '../coordination/claimHeartbeatLoop.js';
+import type { Duration } from '../utils/duration.js';
+import type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, TargetRange } from '../types/streams.js';
+import type { MutationOptions } from './mutationOptions.js';
+import type { LoadWhere } from './where.js';
+/**
+ * A lifecycle filter, accepted either as the enum or as its bare string. The
+ * string arm is a template projection of the enum rather than a second list, so
+ * a scope added to {@link ModelScope} is spellable both ways at once.
+ */
+export type ModelListScope = ModelScope | `${ModelScope}`;
+/**
+ * Options for `track({ id })` — register a durable premise on a row.
+ *
+ * Derived from the wire's row-form {@link TrackDependency} rather than restated
+ * beside it: the caller names the row and, optionally, the watermark it is
+ * premised on, while `model` comes from the proxy the call was made on. Adding
+ * a field to the dependency therefore reaches this surface automatically, and
+ * removing one stops the callers compiling.
+ *
+ * On `readAt`: omit it to baseline at the current head — "tell me about
+ * anything from here on". Pass a known watermark (the one you read the row at)
+ * to also catch a change that landed between that read and this call.
+ */
+export type ModelTrackParams = Omit<Extract<TrackDependency, {
+    model: string;
+}>, 'model'>;
+/** The result of `track({ id })`. */
+export interface ModelTrackResult {
+    /**
+     * Tracks that had ALREADY fired at registration time — a change matching an
+     * open track that landed before this call. Present only when something was
+     * already stale; the ongoing signal arrives on the receipts of later commits.
+     */
+    notifications?: StaleNotification[];
+}
+/** Options for the synchronous local-graph reads `local.list` and `onChange` —
+ *  a JavaScript `filter`, an equality `where`, and a lifecycle `state`. This is
+ *  the local, reactive axis; contrast {@link ServerReadOptions}, the
+ *  asynchronous server axis. */
+export interface LocalReadOptions<T> {
+    where?: Partial<T>;
+    /** Arbitrary local predicate. Applied after `where`. */
+    filter?: (entity: T) => boolean;
+    orderBy?: {
+        [K in keyof T]?: 'asc' | 'desc';
+    };
+    limit?: number;
+    offset?: number;
+    /** Lifecycle filter — `live` (the default), `archived`, or `all`. Named
+     *  `state` so it does not collide with the sync-group `scope`. */
+    state?: ModelListScope;
+}
+export type LocalCountOptions<T> = Pick<LocalReadOptions<T>, 'where' | 'filter' | 'state'>;
+/** Options for the asynchronous server reads `retrieve` and `list` — the
+ *  operator `where` filter, `type`, and `expand`. This is the server axis;
+ *  contrast {@link LocalReadOptions}, the local, reactive axis. */
+export interface ServerReadOptions<T> {
+    /**
+     * Filter for the lookup. Accepts two forms:
+     *   - object form — `{ name: 'foo' }`: equality, where an array value means `IN`
+     *   - tuple form — `[['name', 'ILIKE', '%Goldman%']]`: explicit operators
+     *
+     * See {@link LoadWhere} for the full grammar. The wire protocol matches on AND
+     * only; for OR semantics, run two `list()` calls and union the results.
+     */
+    where?: LoadWhere<T>;
+    orderBy?: {
+        [K in keyof T]?: 'asc' | 'desc';
+    };
+    limit?: number;
+    /**
+     * `complete` waits for the server. `unknown` returns whatever is local
+     * immediately and refreshes in the background.
+     */
+    type?: 'complete' | 'unknown';
+    /**
+     * Schema-declared relation names to hydrate alongside the primary
+     * rows. The server's compiler resolves each name via the schema's
+     * relation metadata (`relation.belongsTo` / `relation.hasMany`)
+     * and emits the JOIN.
+     */
+    expand?: readonly string[];
+}
+/** Options for the single-row async server read `retrieve({ id })`. A subset of
+ *  {@link ServerReadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
+export type ServerRetrieveOptions = Pick<ServerReadOptions<unknown>, 'type' | 'expand'>;
+/**
+ * A claimable part of a row: one of the model's own fields, an app-defined name
+ * marked with {@link part}, or any other string.
+ *
+ * The third arm is the one that matters, and it is not a TypeScript
+ * limitation. Function parameters are contravariant, so a claim accepting
+ * `'title' | 'status'` is not assignable to one accepting `string` — and the
+ * legacy `useAblo<R>()` path erases a concrete schema to `SchemaRecord`
+ * (`AbloProvider.tsx`: `engine as Ablo<SchemaRecord>`) and restores it, which
+ * is exactly that assignment. While that path exists this union must stay open,
+ * and `fields: ['titel']` therefore compiles, is granted, excludes nobody, and
+ * leaves the write of `title` unguarded — the conflict rule compares names as
+ * opaque strings, so an invented one matches no other claim and nothing reports
+ * it.
+ *
+ * The replacement already exists: `createAbloReact(schema)` creates its context
+ * after the schema is known, so nothing is erased and nothing is restored — the
+ * same shape as `createTRPCReact<AppRouter>()`. What remains is retiring the
+ * generic provider in favour of it; the callers are enumerated in
+ * docs/plans/typed-react-binding.md. When they have moved, this arm goes, and
+ * `fields: ['titel']` stops compiling with no change at any call site.
+ */
+export type ClaimField<T> = Extract<keyof T, string> | ClaimPart | (string & {});
+/**
+ * The options on a claim, in four axes — each answers one question, and no
+ * member sits in two:
+ *
+ * - **what you claim** — `field` / `fields` / `path` / `range`, the target
+ *   narrowed below the row;
+ * - **what others see** — `description` / `meta`, the presence half;
+ * - **how you wait** — `queue` / `maxQueueDepth` / `waitTimeoutMs` /
+ *   `signal`, admission to the line;
+ * - **how long you hold** — `ttl` / `heartbeat`, the lease.
+ */
+export interface ClaimTargetOptions<T = Record<string, unknown>> {
+    /**
+     * @deprecated Say it as a set: `fields: ['title']`. Removed in 0.37.0.
+     *
+     * One member for a set of one, beside another for a set of any size, is two
+     * ways to say one thing — and the singular is the one that misleads. A caller
+     * needing two parts reached for the member named `field` and packed
+     * `'b_3,b_7'` into it, which compares as a single unrelated name, so both
+     * writers were granted the same part and one update was lost. That spelling
+     * is refused now, and this member is going with it.
+     *
+     * The wire keeps reading `field` — it is frozen, and an older client emits it
+     * — so this is a change of what you write, not of what is understood.
+     */
+    field?: ClaimField<T>;
+    /**
+     * Narrow the claim to named parts of the row — one or several.
+     *
+     * Exclusion follows the target: claims on the same row conflict only where
+     * their sets intersect, so a holder on `['title']` and a holder on
+     * `['status']` proceed concurrently, while a whole-row claim (no target)
+     * conflicts with both. The per-field claimed-state badge is a consequence of
+     * the narrower lease, not its purpose.
+     */
+    fields?: readonly ClaimField<T>[];
+    /**
+     * @deprecated Claim the field the position lives in — `fields: ['content']`.
+     * Removed in 0.37.0.
+     *
+     * A claim may not be finer than the smallest thing the write path can
+     * address, and today that is a field: nothing writes part of a value. Two
+     * holders of `/content/3` and `/content/7` therefore contend, because either
+     * one committing takes the whole `content` field — so naming the position
+     * bought exclusion it could not deliver, and this member read as a peer of
+     * `fields` while being nothing of the kind.
+     *
+     * For a UI that draws a rail per block, put the block id in `meta`: that is
+     * the open bag for describing your work to peers, it renders exactly as well,
+     * and it promises nothing about exclusion. The wire keeps parsing `path`, so
+     * an older client is unaffected.
+     */
+    path?: string;
+    /**
+     * @deprecated Claim the field the span lives in — `fields: ['content']`.
+     * Removed in 0.37.0.
+     *
+     * Same rule as {@link path}: a span of a value is not separately writable, so
+     * two disjoint spans of one field contend. Unlike `path` this one has a
+     * future — a mergeable field makes an operation the write unit, at which
+     * point a span inside it is addressable and this becomes enforceable. It
+     * returns then, for code rather than prose, and it returns working.
+     */
+    range?: TargetRange;
+    /** Peer-visible description of the work being performed — the sentence a
+     *  contending participant reads to decide whether to wait, work elsewhere, or
+     *  move on. Defaults to `'editing'`. The same field on every claim surface. */
+    description?: string;
+    /**
+     * App-defined structured metadata, carried verbatim to every participant
+     * that observes the claim. Declare its shape once, on `Register`'s
+     * `ClaimMeta` slot, and what you write here is what every reader is typed to
+     * find — the write side and the read side are the same declaration.
+     */
+    meta?: ResolveClaimMeta;
+    /**
+     * Behavior under contention. `true` (the default) queues behind the current
+     * holder and resolves once the row is yours. `false` is fail-fast: if another
+     * participant already holds the row, it rejects immediately with
+     * {@link AbloClaimedError} instead of waiting. Use `false` to deduplicate
+     * distributed work ("if someone else has this job, skip it"), where waiting
+     * would mean double-processing.
+     */
+    queue?: boolean;
+    /**
+     * Backpressure: queue, but not behind too many others. If the server reports a
+     * position at or beyond `maxQueueDepth` when the client joins the line, it
+     * rejects with {@link AbloClaimedError} (`queue_too_deep`) instead of waiting.
+     * Omit to wait however deep the queue is.
+     */
+    maxQueueDepth?: number;
+    /**
+     * Cap on how long a queued claim waits for its grant before rejecting with
+     * {@link AbloClaimedError} (`grant_timeout`). Omit to wait as long as the
+     * line takes. Same meaning on both transports; on the stateless HTTP client
+     * a timed-out wait also leaves the line, so the slot is not left to expire.
+     */
+    waitTimeoutMs?: number;
+    /**
+     * Abort a pending wait from outside — the same signal that cancels
+     * everything else in the program, so a cancelled agent task 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
+     * never torn down by a late abort; release it instead.
+     */
+    signal?: AbortSignal;
+    /** Crash-cleanup TTL — the claim auto-releases if the holder dies. */
+    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
+     * 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
+     * cadence explicitly; the structured {@link ClaimHeartbeatPlan} carries the
+     * cadence and both callbacks in one place —
+     * `heartbeat: { every: '2m', onBeat, onLost }`. The loop stops on release.
+     * You can also beat manually with `held.heartbeat()`.
+     */
+    heartbeat?: true | Duration | ClaimHeartbeatPlan;
+}
+/** Options for `claim({ id, ... })`. */
+export interface ClaimParams<T = Record<string, unknown>> extends ClaimTargetOptions<T> {
+    readonly id: string;
+}
+export interface ClaimLookupParams<T = Record<string, unknown>> {
+    readonly id: string;
+    /** @deprecated Say it as a set: `fields: ['title']`. Removed in 0.37.0. */
+    readonly field?: ClaimField<T>;
+    /** Read the claim state of named parts of the row rather than the row. */
+    readonly fields?: readonly ClaimField<T>[];
+}
+export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLookupParams<T> {
+    readonly order: readonly Claim[];
+}
+/**
+ * A claim handle: the held entity data plus an explicit release hook.
+ *
+ * ```ts
+ * const claim = await ablo.weatherReports.claim({
+ *   id: 'report_stockholm',
+ *   description: 'Fetching current weather before writing the forecast.',
+ * });
+ * try {
+ *   await ablo.weatherReports.update({
+ *     id: claim.target.id,
+ *     data: { status: 'ready' },
+ *     claim,
+ *   });
+ * } finally {
+ *   await claim.release();
+ * }
+ * ```
+ *
+ * `data` is a snapshot taken after the lease is held. Write through the flat
+ * `ablo.<model>.update({ id, data, claim })` verb — the handle carries the
+ * lease id and snapshot watermark for attribution and stale-write protection.
+ */
+export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease };
+export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
+/**
+ * The coordination surface for a model, exposed as a callable namespace.
+ *
+ * Most callers do not need this namespace directly. Put `claim: { ... }` on a
+ * write and the SDK acquires/releases around that one mutation:
+ *
+ * ```ts
+ * await ablo.tasks.update({
+ *   id,
+ *   data: { title },
+ *   claim: {
+ *     field: 'title',
+ *     description: 'Renaming the task to match the project brief.',
+ *   },
+ * });
+ * ```
+ *
+ * Use `claim({ id, ... })` when a tool spans multiple writes and needs one
+ * handle. `state`, `queue`, and `reorder` are coordination reads/scheduler
+ * controls for UI and operators.
+ */
+/**
+ * The coordination reads and scheduler controls on a claim namespace, in their
+ * reactive (synchronous) form: `state`, `queue`, and `reorder` resolve against
+ * the local pool with no round-trip, which is what lets a reactive selector read
+ * coordination state inside a React render.
+ *
+ * This is the single source of truth for the claim read surface. The stateless
+ * HTTP client exposes the awaited projection of exactly these methods (derived
+ * via {@link AwaitedClaimMethod}), so the two transports cannot drift — change a
+ * signature here and the HTTP surface follows.
+ */
+export interface ClaimReadApi<T = Record<string, unknown>> {
+    /**
+     * Current holder for a row, or `null` when free. Use this for UI badges and
+     * preflight checks, not for the normal write path.
+     *
+     * `target.meta` reads as the shape declared on `Register`'s `ClaimMeta`
+     * slot, so no read of it needs a guard. Pass `M` only to override that
+     * declaration for one call — `state<OtherMeta>({ id })` — which a program
+     * carrying more than one meta shape occasionally needs.
+     */
+    state<M = ResolveClaimMeta>(params: ClaimLookupParams<T>): Claim<Record<string, unknown>, M> | null;
+    /**
+     * Every holder of a row, not just one.
+     *
+     * A claim that names a narrower target — a `path`, a `range`, a `field` or
+     * `fields` — excludes only what it overlaps, so several participants hold
+     * disjoint parts of one row at the same time and
+     * {@link ClaimReadApi.state} answers with one of them. This is the read
+     * behind a per-region UI: a rail for each claimed block, a chip for each
+     * participant. Synchronous and reactive off the same snapshot as `state`,
+     * so a render reads it inline.
+     *
+     * Own claim first when this client holds one, then peers. Takes the same
+     * `meta` parameter as {@link ClaimReadApi.state}.
+     */
+    list<M = ResolveClaimMeta>(params: ClaimLookupParams<T>): {
+        readonly object: 'list';
+        readonly data: readonly Claim<Record<string, unknown>, M>[];
+    };
+    /**
+     * FIFO wait line behind the current holder. Advanced: useful for operator
+     * UIs and schedulers. Takes the same `meta` parameter as
+     * {@link ClaimReadApi.state}.
+     */
+    queue<M = ResolveClaimMeta>(params: ClaimLookupParams<T>): {
+        readonly object: 'list';
+        readonly data: readonly Claim<Record<string, unknown>, M>[];
+    };
+    /**
+     * Re-rank the wait line. Advanced and permission-gated.
+     */
+    reorder(params: ClaimReorderParams<T>): void;
+    /** Release a manual claim handle early. Single-write claims auto-release. */
+    release(params: ClaimLookupParams<T> | Claim<T>): Promise<void>;
+}
+/**
+ * The awaited form of a claim method: a synchronous return becomes a `Promise`,
+ * an already-async one (`release`) is left untouched. Used to derive the
+ * stateless HTTP claim surface from the reactive {@link ClaimReadApi}.
+ */
+export type AwaitedClaimMethod<F> = F extends (...args: infer A) => infer R ? R extends Promise<unknown> ? (...args: A) => R : (...args: A) => Promise<R> : F;
+export interface ClaimApi<T> extends ClaimReadApi<T> {
+    /**
+     * The try-claim: `queue: false` treats a held target as an expected outcome,
+     * not an error — it resolves `null`, so claim-or-skip dedup reads
+     * `if (!claim) return` with no try/catch. Who holds it, and why, stays
+     * readable through `claim.state({ id })`. (A write to a row someone else
+     * holds still rejects with `entity_claimed` — a failed write is an error;
+     * a declined try is not.)
+     */
+    (params: ClaimParams<T> & {
+        queue: false;
+    }): Promise<HeldClaim<T> | null>;
+    /**
+     * Takes a claim and returns an explicit held-work handle — a {@link HeldClaim}.
+     * `data`, `release`, `revoke`, and the async disposer are always present (this
+     * call re-reads the row under the lease), so callers can use `handle.data`
+     * directly and `await using` works without a guard.
+     */
+    (params: ClaimParams<T>): Promise<HeldClaim<T>>;
+    /** The row-free try-claim — `null` when the key is already held. */
+    (id: string, opts: ClaimOptions<T> & {
+        queue: false;
+    }): Promise<HeldLease | null>;
+    /**
+     * Takes a claim by id alone, for a row that lives only in the customer's own
+     * database — Ablo has never seen it, so there is nothing to re-read. Returns a
+     * {@link HeldLease}: the same lease controls as {@link HeldClaim}
+     * (`release`, `revoke`, `heartbeat`, `await using`) but no `.data`. Locking a
+     * key you know by id is exactly this — serialize writers without first
+     * syncing the row into Ablo.
+     */
+    (id: string, opts?: ClaimOptions<T>): Promise<HeldLease>;
+}
+export interface ModelRetrieveParams extends ServerRetrieveOptions {
+    readonly id: string;
+}
+export interface ModelCreateParams<T, CreateInput> extends MutationOptions {
+    readonly data: CreateInput;
+    readonly id?: string | null;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
+}
+export interface ModelUpdateParams<T> extends MutationOptions {
+    readonly id: string;
+    readonly data: Partial<T>;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
+}
+export interface ModelDeleteParams<T> extends MutationOptions {
+    readonly id: string;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
+}
+/** Options for the WebSocket-only `ablo.<model>.join(ids, options?)`. */
+export interface JoinOptions {
+    /**
+     * Lease TTL for the underlying presence claim — the participant
+     * auto-releases after this if the holder dies. Compact duration string
+     * (`'5m'`) or ms number, mirroring the claim `ttl`.
+     */
+    ttl?: Duration;
+}

package/dist/transaction/resources/modelOperations.js

@@ -0,0 +1,12 @@
+/**
+ * The request contract for `ablo.<model>` — the option and parameter shapes a
+ * caller passes to a read, a write, or a claim.
+ *
+ * These types describe the *change or the query being requested*, never a local
+ * copy of the rows it touches, so they sit in the settlement core and are shared
+ * by every transport and every caller (ADR 0013 §4, ADR 0016). The factory that
+ * binds them to reactive model instances — `createModelProxy` — stays with the
+ * reactive consumer, along with `ModelOperations` and `ModelCollaboration`,
+ * which reference the live participant handle.
+ */
+export {};

package/dist/transaction/resources/mutationOptions.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Per-call options accepted by any mutation.
+ *
+ * Every field here defines, orders, settles, or authorises *the change itself*
+ * — request identity, commit disposition, fencing, and the premise it rests on.
+ * None of it touches a local copy of rows, so it belongs with the settlement
+ * core rather than the reactive consumer (ADR 0013 §4, ADR 0016).
+ */
+import type { CommitWait } from '../wire/commit.js';
+import type { OnStaleMode, ReadDependency, TrackDependency } from '../coordination/schema.js';
+/**
+ * Per-call options accepted by any mutation, passed as the last argument.
+ * Every field is optional; omitted fields fall back to sensible defaults.
+ *
+ * - `idempotencyKey` — when set, the server caches the response for 24 hours and
+ *   returns the cached result on any retry using the same key. When omitted, the
+ *   SDK generates a fresh UUID per mutation, so every call is retry-safe by
+ *   default. `null` is retained for source compatibility and is treated like
+ *   omission; write retries never opt out of request identity.
+ * - `label` — a human-readable tag recorded with the mutation for debugging, such
+ *   as "nightly cleanup" or "user click".
+ */
+export interface MutationOptions {
+    idempotencyKey?: string | null;
+    label?: string;
+    wait?: CommitWait;
+    readAt?: number | null;
+    onStale?: OnStaleMode | null;
+    /**
+     * The fencing token (Option B) of the held claim this write belongs to. The
+     * server validates it against the entity's persisted high-water and rejects a
+     * stale token. Sourced from the claim handle, never set by hand.
+     */
+    fenceToken?: number | null;
+    /** The id (or `{ id }`) of the claim this write belongs to. This is the
+     *  low-level reference the commit carries so the write is attributed to a claim
+     *  and can pass the holder's own lock. It is distinct from the `claim` handle on
+     *  the model write parameters, which is the higher-level object you usually pass. */
+    claimRef?: string | {
+        readonly id: string;
+    } | null;
+    /**
+     * The batch premise — the answer to "did anything I looked at change?" Each
+     * entry is a row (`{ model, id, readAt, fields? }`) or a sync group
+     * (`{ group, readAt }`) that this write was premised on. The server checks
+     * that none of them moved since their `readAt` and applies the entry's
+     * `onStale` behavior to the whole batch. This is distinct from the per-operation
+     * `readAt`, which guards only the row being written.
+     *
+     * See `packages/sync-engine/docs/concurrency-convention.md` (§3 the two
+     * premises, §4 the batch premise) for the governing convention.
+     */
+    reads?: ReadDependency[] | null;
+    /**
+     * Durable premises — what this write (or the record it produces) should
+     * keep watching. Unlike `reads`, which is checked once at commit and discarded,
+     * each `track` entry is persisted and re-checked against every future delta; a
+     * later matching change opens a `StaleNotification` for the tracking participant,
+     * delivered at their next commit or live to a held claim. Each entry is a row
+     * (`{ model, id }`) or a sync group (`{ group }`), optionally pinned to a `readAt`
+     * baseline (defaults to this commit's watermark).
+     *
+     * See `packages/sync-engine/docs/groups.md` for how `track` drives propagation.
+     */
+    track?: TrackDependency[] | null;
+}

package/dist/transaction/resources/mutationOptions.js

@@ -0,0 +1,9 @@
+/**
+ * Per-call options accepted by any mutation.
+ *
+ * Every field here defines, orders, settles, or authorises *the change itself*
+ * — request identity, commit disposition, fencing, and the premise it rests on.
+ * None of it touches a local copy of rows, so it belongs with the settlement
+ * core rather than the reactive consumer (ADR 0013 §4, ADR 0016).
+ */
+export {};

package/dist/transaction/resources/where.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The where-clause grammar carried by a filtered read.
+ *
+ * A `where` is a flat list of `[column, operator, value]` conditions combined
+ * with AND. The protocol carries no model-specific logic: the server compiles a
+ * condition against your schema, so adding a model or relation is a schema
+ * change rather than a server change.
+ *
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every block whose `sectionId` falls in a set of ids.
+ *
+ * These types describe the *request*, not any local copy of the rows it returns,
+ * so they live with the settlement core rather than the reactive consumer.
+ */
+import { z } from 'zod';
+/** Primitive operand types allowed in a where clause. */
+export type WherePrimitive = string | number | boolean | null;
+/**
+ * The comparison operators a {@link WhereClause} may use: equality and
+ * inequality, ordering, set membership (`IN` / `NOT IN`), null checks
+ * (`IS` / `IS NOT`), and case-sensitive or case-insensitive pattern
+ * matching (`LIKE`, `ILIKE`, and their negations).
+ */
+export declare const whereOpSchema: z.ZodEnum<{
+    "=": "=";
+    "!=": "!=";
+    "<": "<";
+    "<=": "<=";
+    ">": ">";
+    ">=": ">=";
+    IN: "IN";
+    "NOT IN": "NOT IN";
+    IS: "IS";
+    "IS NOT": "IS NOT";
+    LIKE: "LIKE";
+    "NOT LIKE": "NOT LIKE";
+    ILIKE: "ILIKE";
+    "NOT ILIKE": "NOT ILIKE";
+}>;
+export type WhereOp = z.infer<typeof whereOpSchema>;
+/**
+ * How each operator binds its operand — the classification a compiler needs
+ * before it can render or evaluate a condition: a scalar on the right, an array
+ * to expand, or a null check with no operand at all. `LIKE_OPS` is the subset
+ * whose operand is a pattern and therefore needs pattern validation.
+ *
+ * These live here, beside the operators, because every consumer of the grammar
+ * needs the same split and there is more than one consumer: a where clause is
+ * compiled to SQL on a hosted plane and evaluated in memory against the log on
+ * a source plane. Two hand-maintained copies of this split meant the same
+ * request could be accepted by one plane and rejected by the other — and the
+ * pattern-safety set existed on only one of them.
+ */
+export declare const WHERE_SCALAR_OPS: ReadonlySet<WhereOp>;
+export declare const WHERE_ARRAY_OPS: ReadonlySet<WhereOp>;
+export declare const WHERE_NULL_OPS: ReadonlySet<WhereOp>;
+export declare const WHERE_LIKE_OPS: ReadonlySet<WhereOp>;
+/**
+ * Does this operator accept this operand? The rule the sets above imply, stated
+ * once and thrown once.
+ *
+ * The sets were collapsed here because two copies of the split let one plane
+ * accept a request the other refused. The check that consumes them stayed
+ * duplicated — the SQL compiler and the log-plane evaluator each carried their
+ * own arity tests and their own wording — which leaves the same gap one step
+ * further along: relax `IN` in one evaluator and a request succeeds against a
+ * hosted plane and fails against a connected one, with no test in a position to
+ * notice.
+ *
+ * Returns the classification the caller needs next, so the check and the branch
+ * are the same statement rather than two that can disagree.
+ */
+export declare function classifyWhereOperand(op: WhereOp, value: unknown): 'null' | 'array' | 'scalar';
+/**
+ * A single condition. Two supported shapes:
+ *
+ *   - `[col, value]` — shortcut for `[col, '=', value]`
+ *   - `[col, op, value]` — explicit operator
+ *
+ * The value is a single primitive for scalar operators and an array of
+ * primitives for IN/NOT IN.
+ */
+export type WhereClause = readonly [col: string, value: WherePrimitive] | readonly [col: string, op: WhereOp, value: WherePrimitive | readonly WherePrimitive[]];
+/**
+ * Client-facing where shape for `load({where})` and `deleteMany({where})`.
+ *
+ * Two shapes accepted, both AND-combined:
+ *
+ *   - Object form: `{ name: 'foo', orgId: '1' }` — each entry is an `=`
+ *     clause; array values become `IN`. Ergonomic for the common case.
+ *   - Tuple form: `[['name', 'ILIKE', '%Goldman%'], ['orgId', '1']]` —
+ *     explicit operators (LIKE/ILIKE/<=/etc.). Matches the wire
+ *     `WhereClause[]` 1:1, so no translation layer.
+ *
+ * The two forms compose: pass tuple form when you need an operator,
+ * object form otherwise. For OR semantics, run two `load()` calls and
+ * union client-side — keeps the protocol AND-only.
+ */
+export type LoadWhere<T> = Partial<T> | {
+    [K in keyof T]?: T[K] | readonly T[K][];
+} | readonly WhereClause[];