@abloatai/ablo 0.34.1 → 0.36.0

package/dist/wire/frames.d.ts

@@ -1,197 +0,0 @@
-/**
- * The write-path message shapes for the sync protocol. These cover the frames
- * a client sends to commit work — {@link CommitMessage}, a batch of raw
- * operations — and the server's {@link MutationResultMessage}
- * acknowledgement. The same frames flow over a WebSocket connection and over
- * the HTTP commit endpoint.
- *
- * Both the client and the server import these definitions from here, so the two
- * sides cannot drift. Each interface is paired with a Zod validator
- * ({@link commitOperationSchema}, {@link commitPayloadSchema}) pinned to it at
- * compile time, so the runtime check and the type stay in lockstep. Changing
- * any shape in this file changes the wire contract and requires the client and
- * server to update together.
- */
-import { z } from 'zod';
-import type { OnStaleMode, ReadDependency, TrackDependency } from '../coordination/index.js';
-import type { MutationResultMessageWire } from './commit.js';
-/**
- * A single operation within a {@link CommitMessage} batch. Each operation is
- * the smallest unit the server applies atomically — one create, update,
- * delete, archive, or unarchive against one model row.
- */
-export interface CommitOperation {
-    type: 'CREATE' | 'UPDATE' | 'DELETE' | 'ARCHIVE' | 'UNARCHIVE';
-    model: string;
-    id?: string | null;
-    input?: Record<string, unknown> | null;
-    /**
-     * A client-generated transaction id for this one operation. The server
-     * stamps it onto the `sync_deltas.transaction_id` column so the originating
-     * client can recognize the resulting broadcast as an echo of its own
-     * optimistic write. This is distinct from the batch-level `clientTxId` on
-     * {@link CommitMessage}, which the server uses to deduplicate retried batches.
-     */
-    transactionId?: string | null;
-    /**
-     * A read watermark captured when the client last read this row. The server
-     * checks whether the target has changed since this point; if it has, the
-     * operation's {@link CommitOperation.onStale} mode decides what happens.
-     */
-    readAt?: number | null;
-    /**
-     * What to do when the server detects the row changed since
-     * {@link CommitOperation.readAt}. `'reject'` (the default) fails the
-     * operation with a stale-context error; `'overwrite'` applies the write
-     * regardless; `'notify'` holds the write and returns a
-     * {@link StaleNotification} for the caller to resolve.
-     */
-    onStale?: OnStaleMode | null;
-    /**
-     * Write even when another participant holds a claim on this row. The default
-     * (`false`) rejects the operation with a claimed-entity error while a claim
-     * is held. Setting `bypass` overrides that, and the override is recorded. It
-     * is honored only for participants the claim guard trusts, such as human and
-     * framework identities; a bypass requested by an agent is ignored.
-     */
-    bypass?: boolean | null;
-    /**
-     * The monotonic fencing token of the held claim this write was issued under
-     * ({@link https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html Kleppmann fencing}).
-     * The server rejects the write if a later holder already advanced this
-     * entity's persisted high-water past the token — closing the "lapsed holder
-     * resumes after its successor came and went" residual that the live-lease
-     * claim guard cannot see. Absent on every unclaimed write.
-     */
-    fenceToken?: number | null;
-}
-/**
- * Runtime validator for {@link CommitOperation}. Both commit transports — the
- * WebSocket `commit` frame and the HTTP `/v1/commits` endpoint — run this check
- * on every operation before it is applied, so a malformed operation is rejected
- * at the edge. It builds on the shared coordination schema, widening `bypass`
- * to also accept `null` so the validator and the interface match exactly. Note
- * that `readAt` must be a number: it feeds the server's stale-check comparison,
- * so a non-numeric watermark is refused here.
- */
-export declare const commitOperationSchema: z.ZodObject<{
-    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-        reject: "reject";
-        overwrite: "overwrite";
-        notify: "notify";
-    }>>>;
-    type: z.ZodEnum<{
-        CREATE: "CREATE";
-        UPDATE: "UPDATE";
-        DELETE: "DELETE";
-        ARCHIVE: "ARCHIVE";
-        UNARCHIVE: "UNARCHIVE";
-    }>;
-    model: z.ZodString;
-    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    bypass: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
-}, z.core.$strip>;
-/**
- * A client-to-server frame that asks the server to commit a batch of operations
- * atomically. It carries a list of {@link CommitOperation} entries plus the
- * batch metadata below.
- */
-export interface CommitMessage {
-    type: 'commit';
-    payload: {
-        operations: CommitOperation[];
-        clientTxId: string;
-        /**
-         * Optional lineage id linking this batch to the task that caused it. When
-         * present, the server validates it and records it on the delta's
-         * `caused_by_task_id` column for audit trails; when omitted or `null`, the
-         * batch simply carries no task attribution.
-         */
-        causedByTaskId?: string | null;
-        /**
-         * The reads this batch's writes were premised on. Each entry names either a
-         * specific row (`{ model, id, readAt, fields? }`) or a sync group
-         * (`{ group, readAt }`) that must not have changed since its `readAt`
-         * watermark. The server checks every entry and applies its `onStale`
-         * disposition to the whole batch if one moved. When omitted, only the rows
-         * being written are checked for staleness.
-         */
-        reads?: ReadDependency[] | null;
-        /**
-         * Durable read-dependencies to register for this batch's participant. Each
-         * entry — a row (`{ model, id }`) or a sync group (`{ group }`) — is persisted
-         * and re-checked against every future delta; a later match surfaces a
-         * `StaleNotification` on the participant's next commit. Distinct from `reads`,
-         * which is checked once here and discarded.
-         */
-        track?: TrackDependency[] | null;
-    };
-}
-/**
- * Runtime validator for the payload of {@link CommitMessage}. It checks every
- * field the server acts on — `operations`, `clientTxId`, `causedByTaskId`, and
- * `reads` — validating each operation with {@link commitOperationSchema} and
- * each read dependency with the shared read-dependency schema.
- */
-export declare const commitPayloadSchema: z.ZodObject<{
-    operations: z.ZodArray<z.ZodObject<{
-        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-            reject: "reject";
-            overwrite: "overwrite";
-            notify: "notify";
-        }>>>;
-        type: z.ZodEnum<{
-            CREATE: "CREATE";
-            UPDATE: "UPDATE";
-            DELETE: "DELETE";
-            ARCHIVE: "ARCHIVE";
-            UNARCHIVE: "UNARCHIVE";
-        }>;
-        model: z.ZodString;
-        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        bypass: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
-    }, z.core.$strip>>;
-    clientTxId: z.ZodString;
-    causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        model: z.ZodString;
-        id: z.ZodString;
-        readAt: z.ZodNumber;
-        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        onStale: z.ZodOptional<z.ZodEnum<{
-            reject: "reject";
-            overwrite: "overwrite";
-            notify: "notify";
-        }>>;
-    }, z.core.$strip>, z.ZodObject<{
-        group: z.ZodString;
-        readAt: z.ZodNumber;
-        onStale: z.ZodOptional<z.ZodEnum<{
-            reject: "reject";
-            overwrite: "overwrite";
-            notify: "notify";
-        }>>;
-    }, z.core.$strip>]>>>>;
-    track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        model: z.ZodString;
-        id: z.ZodString;
-        readAt: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>, z.ZodObject<{
-        group: z.ZodString;
-        readAt: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>]>>>>;
-}, z.core.$strip>;
-/**
- * The server's acknowledgement of a {@link CommitMessage}. Runtime shape and
- * TypeScript type are both owned by `wire/commit.ts`; HTTP, WebSocket, and
- * cached replay no longer maintain parallel receipt declarations.
- */
-export type MutationResultMessage = MutationResultMessageWire;

package/dist/wire/frames.js

@@ -1,49 +0,0 @@
-/**
- * The write-path message shapes for the sync protocol. These cover the frames
- * a client sends to commit work — {@link CommitMessage}, a batch of raw
- * operations — and the server's {@link MutationResultMessage}
- * acknowledgement. The same frames flow over a WebSocket connection and over
- * the HTTP commit endpoint.
- *
- * Both the client and the server import these definitions from here, so the two
- * sides cannot drift. Each interface is paired with a Zod validator
- * ({@link commitOperationSchema}, {@link commitPayloadSchema}) pinned to it at
- * compile time, so the runtime check and the type stay in lockstep. Changing
- * any shape in this file changes the wire contract and requires the client and
- * server to update together.
- */
-import { z } from 'zod';
-// The runtime schema primitives are imported straight from the coordination
-// schema module to keep this file's runtime dependencies limited to Zod.
-import { commitOperationSchema as coordinationCommitOperationSchema, readDependencySchema, trackDependencySchema, } from '../coordination/schema.js';
-/**
- * Runtime validator for {@link CommitOperation}. Both commit transports — the
- * WebSocket `commit` frame and the HTTP `/v1/commits` endpoint — run this check
- * on every operation before it is applied, so a malformed operation is rejected
- * at the edge. It builds on the shared coordination schema, widening `bypass`
- * to also accept `null` so the validator and the interface match exactly. Note
- * that `readAt` must be a number: it feeds the server's stale-check comparison,
- * so a non-numeric watermark is refused here.
- */
-export const commitOperationSchema = coordinationCommitOperationSchema.extend({
-    bypass: z.boolean().nullish(),
-});
-// Pins the schema to the interface: this fails to compile if either side drifts.
-const _commitOperationContract = true;
-void _commitOperationContract;
-/**
- * Runtime validator for the payload of {@link CommitMessage}. It checks every
- * field the server acts on — `operations`, `clientTxId`, `causedByTaskId`, and
- * `reads` — validating each operation with {@link commitOperationSchema} and
- * each read dependency with the shared read-dependency schema.
- */
-export const commitPayloadSchema = z.object({
-    operations: z.array(commitOperationSchema),
-    clientTxId: z.string(),
-    causedByTaskId: z.string().nullish(),
-    reads: z.array(readDependencySchema).nullish(),
-    track: z.array(trackDependencySchema).nullish(),
-});
-// Pins the schema to the payload type: fails to compile if either side drifts.
-const _commitPayloadContract = true;
-void _commitPayloadContract;

package/dist/wire/listEnvelope.js

@@ -1,18 +0,0 @@
-/**
- * Wraps an already-fetched page of rows in the uniform {@link ListEnvelope}.
- *
- * Pagination stays the caller's job — fetch one more row than the limit to
- * decide `hasMore`, and derive the cursor from the last row's sort key. This
- * helper only applies the envelope so no endpoint has to build the shape by
- * hand. The defaults describe a small, unpaginated collection
- * (`has_more: false`, `next_cursor: null`); a paginated endpoint passes both
- * explicitly.
- */
-export function listEnvelope(data, opts = {}) {
-    return {
-        object: 'list',
-        data,
-        has_more: opts.hasMore ?? false,
-        next_cursor: opts.nextCursor ?? null,
-    };
-}

package/docs/interaction-model.md

@@ -1,97 +0,0 @@
-# Interaction Model
-
-When a person, a server action, and an AI agent can all write to the same row,
-you need one write path that stops them from clobbering each other. Ablo gives
-you exactly one: load the row, claim it while you work, update it, and wait for
-confirmation. This page walks through that path and the few primitives behind it.
-
-Here's the whole path in one block — claim a row, update it inside the claim, and
-let the claim release when your callback returns:
-
-```ts
-const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
-
-await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
-await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' }, wait: 'confirmed' });
-```
-
-Claims don't lock. If another writer holds the row, `claim` waits for them,
-re-reads the fresh row, then hands it to you — so two writers serialize instead
-of clobbering.
-
-## Primitives
-
-| Primitive | Plane | Purpose |
-|---|---|---|
-| `Schema` | State | Declares typed models the app and agents can read and write. |
-| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async server reads), `get`/`getAll`/`getCount` (synchronous local reads), `create`, `update`, and `delete`. |
-| `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral — never persisted. |
-| `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
-| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
-
-### Why each primitive is separate
-
-Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
-does a job the others can't. If you're coming from Replicache or Yjs you'd
-expect just `Commit`; here's what the other two buy you over that minimum:
-
-- **`Claim` is not a read lock.** Reads stay open. Claims serialize
-  acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
-  from fresh state.
-- **`Receipt` is not a `200 OK`.** It's the durable artifact a commit
-  produced — accepted commit id, server-assigned timestamps, stale-check
-  outcome — addressable after the fact and replayable into a different
-  client. A status code can't be re-read by a sub-agent that wasn't on
-  the original call.
-
-## Run Loop
-
-A normal schema-backed run is:
-
-```ts
-const report = await ablo.weatherReports.retrieve({ id });
-const active = ablo.weatherReports.claim.state({ id });
-await using claim = await ablo.weatherReports.claim({ id });
-await ablo.weatherReports.update({ id: claim.data.id, data: patch, wait: 'confirmed' });
-```
-
-`retrieve({ id })` is an async server read (await it). `claim.state({ id })` is a
-synchronous local read of who currently holds the row — it never blocks.
-
-## Coordination
-
-> Loop view only. Full claim reference — methods, the claim-state object, the
-> `claim.queue`, errors — is [Coordination](./coordination.md).
-
-Claims broadcast across the org. Call `claim({ id })`, do your writes with the
-normal `update` inside the `await using` scope, and the claim releases
-automatically when the scope exits:
-
-```ts
-await using claim = await ablo.weatherReports.claim({
-  id: 'report_stockholm',
-  description: 'editing',
-});
-await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // rejected if the row changed under the claim
-```
-
-`ablo.weatherReports.claim.state({ id: 'report_stockholm' })` reads the live claim (or
-`null`) without blocking. Claims don't lock: if another participant holds the
-row, `claim` waits for them to finish, re-reads, and then hands you the fresh
-row. The same signal is visible to every schema client through `claim.state({ id })`
-and the live claim stream.
-
-## Conflict resolution
-
-Schema updates can carry `readAt` and `onStale`. If the state advanced past
-`readAt`, Ablo applies the `onStale` policy:
-
-- `reject` — fail the commit (first writer wins).
-- `notify` — accept the write, but flag it for product review.
-- `overwrite` — apply the write unconditionally.
-
-The choice is per-commit. No CRDT default; the policy is explicit.
-
-## The contract in one sentence
-
-Declare schema, load state, coordinate a claim, update the model, and wait for confirmation.