@abloatai/ablo 0.34.1 → 0.35.0

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

@@ -0,0 +1,319 @@
+/**
+ * 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 { AbloClaimedError } from '../errors.js';
+import type { StaleNotification, TrackDependency } from '../coordination/schema.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'>;
+export interface ClaimTargetOptions<T = Record<string, unknown>> {
+    /** 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;
+    /** Field-level target, for fine-grained claimed-state badges. */
+    field?: string;
+    /**
+     * Several named parts of the row at once. Claims conflict where their sets
+     * intersect, so two holders on disjoint parts do not wait for each other.
+     * Prefer this to packing names into `field`, which compares as one opaque
+     * string and lets overlapping sets both be granted.
+     */
+    fields?: readonly string[];
+    /** Optional path for document/file-like targets. */
+    path?: string;
+    /** Optional range for document/file-like targets. */
+    range?: TargetRange;
+    /**
+     * 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;
+    /** Crash-cleanup TTL — the claim auto-releases if the holder dies. */
+    ttl?: Duration;
+    /**
+     * 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.
+     *
+     * The high-level typed claim defaults this on because it serializes writers;
+     * the low-level lease and the HTTP client default it off, since they resolve
+     * immediately and cannot transparently wait for a grant.
+     */
+    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;
+    /**
+     * 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 loop stops on release. A beat answered with a
+     * definitive loss stops the loop and calls {@link onHeartbeatLost}; you can
+     * also beat manually with `held.heartbeat()`.
+     */
+    heartbeat?: true | Duration;
+    /**
+     * Called once if the auto-heartbeat learns the lease is no longer yours
+     * (expired and possibly granted onward). The loop has already stopped;
+     * abandon the work or re-claim. Any write attempted under the old lease is
+     * independently rejected by its `readAt` guard.
+     */
+    onHeartbeatLost?: (error: AbloClaimedError) => void;
+    /**
+     * Called after every successful beat (manual or auto) with the server's
+     * answer — chiefly `queueDepth`, the number of participants waiting in
+     * line behind this lease. A worker that can checkpoint may read pressure
+     * here and release early when others wait.
+     */
+    onHeartbeat?(beat: ClaimHeartbeat): void;
+}
+/** 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;
+    readonly field?: string;
+}
+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;
+    /**
+     * 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> {
+    /**
+     * 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>>;
+    /**
+     * 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,85 @@
+/**
+ * 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>;
+/**
+ * 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[];

package/dist/transaction/resources/where.js

@@ -0,0 +1,70 @@
+/**
+ * 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';
+/**
+ * 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 const whereOpSchema = z.enum([
+    '=',
+    '!=',
+    '<',
+    '<=',
+    '>',
+    '>=',
+    'IN',
+    'NOT IN',
+    'IS',
+    'IS NOT',
+    'LIKE',
+    'NOT LIKE',
+    'ILIKE',
+    'NOT ILIKE',
+]);
+/**
+ * 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 const WHERE_SCALAR_OPS = new Set([
+    '=',
+    '!=',
+    '<',
+    '<=',
+    '>',
+    '>=',
+    'LIKE',
+    'NOT LIKE',
+    'ILIKE',
+    'NOT ILIKE',
+]);
+export const WHERE_ARRAY_OPS = new Set(['IN', 'NOT IN']);
+export const WHERE_NULL_OPS = new Set(['IS', 'IS NOT']);
+export const WHERE_LIKE_OPS = new Set([
+    'LIKE',
+    'NOT LIKE',
+    'ILIKE',
+    'NOT ILIKE',
+]);

package/dist/{client → transaction/resources}/writeOptionsSchema.d.ts

@@ -16,11 +16,8 @@
  * asserts the shape rather than replacing the value with a parsed copy.
  */
 import { z } from 'zod';
-export declare const onStaleModeSchema: z.ZodEnum<{
-    reject: "reject";
-    overwrite: "overwrite";
-    notify: "notify";
-}>;
+import { onStaleModeSchema } from '../coordination/schema.js';
+export { onStaleModeSchema };
 export declare const writeOptionsSchema: z.ZodObject<{
     idempotencyKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     label: z.ZodOptional<z.ZodString>;
@@ -38,7 +35,6 @@ export declare const writeOptionsSchema: z.ZodObject<{
     claim: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         id: z.ZodString;
     }, z.core.$loose>]>>>;
-    causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type WriteOptionsInput = z.infer<typeof writeOptionsSchema>;
 /**

package/dist/{client → transaction/resources}/writeOptionsSchema.js

@@ -17,8 +17,14 @@
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
-import { commitStatusSchema } from '../wire/commit.js';
-export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
+import { commitWaitSchema } from '../wire/commit.js';
+import { onStaleModeSchema } from '../coordination/schema.js';
+// Re-exported, not redeclared. `coordination/schema.ts` owns this enum — it is
+// what the wire schemas and the server validate against — while the published
+// SDK barrel exports the name from this module. Declaring it twice put a second
+// object behind the public export that agreed with the canonical one only by
+// both happening to list the same three strings.
+export { onStaleModeSchema };
 export const writeOptionsSchema = z.object({
     /** Idempotency key the server records in `mutation_log` to make retries
      *  safe; `null` opts out of that protection. */
@@ -26,7 +32,7 @@ export const writeOptionsSchema = z.object({
     /** Human-readable audit tag, persisted to `mutation_log.label`. */
     label: z.string().max(255).optional(),
     /** Resolve when queued locally (default) or once the server confirms. */
-    wait: commitStatusSchema.optional(),
+    wait: commitWaitSchema.optional(),
     /** Stale guard: the sync watermark the caller's reasoning was based on. */
     readAt: z.number().int().nonnegative().nullish(),
     /** What the server does when the target moved past `readAt`. */
@@ -39,8 +45,6 @@ export const writeOptionsSchema = z.object({
     /** The claim this write belongs to — either a claim id, or a live claim
      *  handle whose `release`/`revoke` functions are preserved untouched. */
     claim: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
-    /** Reserved wire-compatibility field; current clients always send `null`. */
-    causedByTaskId: z.string().nullish(),
 });
 /**
  * Validates a write-options object against {@link writeOptionsSchema}. On

package/dist/{schema → transaction/schema}/field.d.ts

@@ -103,18 +103,18 @@ export declare const field: {
      *
      * Example:
      * ```ts
-     * const slideDecks = model({
+     * const reports = model({
      *   metadata: field.json({
-     *     icon: z.string().default('presentation'),
+     *     icon: z.string().default('report'),
      *     color: z.string().default('#F59E0B'),
      *     summary: z.string().optional(),
      *   }),
      * });
      *
      * // At runtime:
-     * deck.metadata       // raw JSON string (unchanged)
-     * deck.metadataJson   // { icon: 'presentation', color: '#F59E0B', summary: undefined }
-     * deck.metadataJson.icon  // 'presentation' (typed, with default)
+     * report.metadata       // raw JSON string (unchanged)
+     * report.metadataJson   // { icon: 'report', color: '#F59E0B', summary: undefined }
+     * report.metadataJson.icon  // 'report' (typed, with default)
      * ```
      */
     readonly json: <T extends z.ZodType = z.ZodUnknown>(schemaOrShape?: T | z.ZodRawShape) => FieldBuilder<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;

package/dist/{schema → transaction/schema}/field.js

@@ -219,18 +219,18 @@ export const field = {
      *
      * Example:
      * ```ts
-     * const slideDecks = model({
+     * const reports = model({
      *   metadata: field.json({
-     *     icon: z.string().default('presentation'),
+     *     icon: z.string().default('report'),
      *     color: z.string().default('#F59E0B'),
      *     summary: z.string().optional(),
      *   }),
      * });
      *
      * // At runtime:
-     * deck.metadata       // raw JSON string (unchanged)
-     * deck.metadataJson   // { icon: 'presentation', color: '#F59E0B', summary: undefined }
-     * deck.metadataJson.icon  // 'presentation' (typed, with default)
+     * report.metadata       // raw JSON string (unchanged)
+     * report.metadataJson   // { icon: 'report', color: '#F59E0B', summary: undefined }
+     * report.metadataJson.icon  // 'report' (typed, with default)
      * ```
      */
     json(schemaOrShape) {