@abloatai/ablo 0.34.1 → 0.35.0

package/dist/transaction/types/assertExact.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A compile-time proof that two types are the same type, in both directions.
+ *
+ * This is how a derived shape is pinned to the shape it derives from. A plain
+ * `extends` check only proves one side is assignable to the other, which a
+ * schema that has grown a field still satisfies; both directions catch the
+ * addition. Instantiating it at a value binding turns the mismatch into a
+ * compile error at the definition site rather than at some distant caller.
+ *
+ * ```ts
+ * const _contract: AssertExact<z.infer<typeof participantRefSchema>, ParticipantRef> = true;
+ * ```
+ *
+ * The tuple wrappers stop a union operand from distributing, so a union is
+ * compared whole rather than member by member.
+ */
+export type AssertExact<A, B> = [A] extends [B] ? ([B] extends [A] ? true : never) : never;

package/dist/transaction/types/assertExact.js

@@ -0,0 +1 @@
+export {};

package/dist/{types → transaction/types}/global.d.ts

@@ -1,7 +1,7 @@
 /**
  * The single place where you tell the SDK about your application's types.
  *
- * You register your Schema and UserMeta once by augmenting the
+ * You register your Schema, UserMeta and ClaimMeta once by augmenting the
  * {@link Register} interface. From then on the typed SDK surface reads its
  * types from that registration, so you never pass a generic or a `schema`
  * argument at a call site.
@@ -27,6 +27,7 @@
  *   interface Register {
  *     Schema: typeof schema;
  *     UserMeta: { id: string; email: string };
+ *     ClaimMeta: { blocks: string[] };
  *   }
  * }
  * export {};
@@ -51,11 +52,13 @@ export interface DefaultSyncShape {
     readonly UserMeta: {
         readonly id: string;
     };
+    readonly ClaimMeta: Record<string, unknown>;
 }
 /**
  * The registration interface you augment to declare your application's types.
  * Add keys inside a `declare module '@abloatai/ablo'` block — for example
- * `interface Register { Schema: ...; UserMeta: ...; }`. It is empty by default,
+ * `interface Register { Schema: ...; UserMeta: ...; ClaimMeta: ...; }`. It is
+ * empty by default,
  * so any key you omit falls back to {@link DefaultSyncShape}. It is exported
  * from the package root so your augmentation merges into this declaration.
  *
@@ -82,6 +85,18 @@ export type ResolveSchema = Register extends {
 export type ResolveUserMeta = Register extends {
     UserMeta: infer U;
 } ? U : DefaultSyncShape['UserMeta'];
+/**
+ * The application metadata your claims carry, or the default when none is
+ * registered. It rides along on a claim's target — the SDK transports it
+ * verbatim, never interprets it, and never validates it, so the shape is
+ * yours to declare and yours alone to keep true.
+ *
+ * Declaring it here is what makes `claim.state({ id })?.target.meta` readable
+ * without a `typeof` guard, on every claim surface at once.
+ */
+export type ResolveClaimMeta = Register extends {
+    ClaimMeta: infer M;
+} ? M : DefaultSyncShape['ClaimMeta'];
 /**
  * The union of your schema's model names. `useQuery(modelKey)` narrows its
  * first argument to this union, so a misspelled or unknown model name fails at

package/dist/{types → transaction/types}/global.js

@@ -1,7 +1,7 @@
 /**
  * The single place where you tell the SDK about your application's types.
  *
- * You register your Schema and UserMeta once by augmenting the
+ * You register your Schema, UserMeta and ClaimMeta once by augmenting the
  * {@link Register} interface. From then on the typed SDK surface reads its
  * types from that registration, so you never pass a generic or a `schema`
  * argument at a call site.
@@ -27,6 +27,7 @@
  *   interface Register {
  *     Schema: typeof schema;
  *     UserMeta: { id: string; email: string };
+ *     ClaimMeta: { blocks: string[] };
  *   }
  * }
  * export {};

package/dist/{types → transaction/types}/index.d.ts

@@ -5,6 +5,7 @@
  * is loaded, and how changes are represented on the wire as they synchronize.
  */
 import type { FieldMeta } from '../schema/field.js';
+import { LoadStrategy } from '../schema/loadStrategy.js';
 /**
  * A lifecycle filter for queries: whether to return live entities, archived
  * ones, or both.
@@ -35,21 +36,7 @@ export declare enum PropertyType {
     /** An array of foreign-key ids — a many-to-many relationship. */
     referenceArray = "referenceArray"
 }
-/**
- * When and how a model's data is loaded from the server.
- */
-export declare enum LoadStrategy {
-    /** Loaded during startup, before it is first used — for models needed right away. */
-    instant = "instant",
-    /** Loaded all at once the first time it is needed — for secondary models. */
-    lazy = "lazy",
-    /** Loaded on demand in subsets — for large collections. */
-    partial = "partial",
-    /** Loaded only when the application asks for it — for optional data. */
-    explicitlyRequested = "explicitlyRequested",
-    /** Never synced with the server; kept only on the client — for local-only state. */
-    local = "local"
-}
+export { LoadStrategy };
 /**
  * The resolved configuration for a single model property.
  */
@@ -101,8 +88,6 @@ export interface ModelMetadata {
     loadStrategy: LoadStrategy;
     syncGroup?: string;
     tableName?: string;
-    partialLoadMode?: 'full' | 'regular' | 'lowPriority';
-    usedForPartialIndexes?: boolean;
     schemaVersion?: number;
     /**
      * The schema-declared fields for this model, keyed by field name. When a
@@ -156,13 +141,6 @@ export interface ReferenceOptions {
     indexed?: boolean;
     nullable?: boolean;
 }
-/**
- * A GraphQL mutation: its query text and the variables to run it with.
- */
-export interface GraphQLMutation {
-    mutationText: string;
-    variables: Record<string, unknown>;
-}
 /**
  * A request to load model rows by an indexed key. When the load completes,
  * `resolve` is called with the matching rows.
@@ -174,27 +152,17 @@ export interface LoadRequest {
     resolve?: (value: unknown[]) => void;
 }
 /**
- * The one-letter code identifying what kind of change a sync action carries.
- */
-export type SyncActionType = 'I' | 'U' | 'A' | 'D' | 'C' | 'G' | 'S' | 'V';
-/**
- * A single change to one model row, as carried on the sync stream.
- */
-export interface SyncAction {
-    id: number;
-    modelName: string;
-    modelId: string;
-    action: SyncActionType;
-    data: unknown;
-    __class: 'SyncAction';
-}
-/**
- * A batch of sync actions delivered together.
- */
-export type DeltaPacket = SyncAction[];
-/**
- * The kind of initial data load performed when a client starts: a full load, a
- * partial subset, or local-only.
+ * How a session establishes its baseline state at startup.
+ *
+ * 'full' — Fetch a complete snapshot from the server, clear the local store,
+ *   load the snapshot, and adopt its `lastSyncId`.
+ *
+ * 'partial' — Fetch only the deltas since the stored `lastSyncId` and apply
+ *   them on top of the existing local data.
+ *
+ * 'local' — Skip the server entirely: hydrate the instance cache from the local
+ *   store, connect the WebSocket with the stored `lastSyncId`, and receive
+ *   deltas from there onward. Used when offline with valid local data.
  */
 export type BootstrapType = 'full' | 'partial' | 'local';
 /**
@@ -234,4 +202,4 @@ export interface PartialIndexInfo {
     depth: number;
     path: string[];
 }
-export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind, ParticipantRef, JsonValue, ConfirmationState, AgentDelta, Snapshot, ContextChange, ClaimTarget, PresenceTarget, PresenceStream, Activity, Peer, PresenceUpdatePayload, ClaimLeaseOptions, Duration, ClaimOptions, ClaimStream, ClaimLost, ClaimStatus, ClaimWaitOptions, Claim, HeldClaim, } from './streams.js';
+export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind, ParticipantRef, JsonValue, ConfirmationState, Delta, AgentDelta, Snapshot, ContextChange, ClaimTarget, PresenceTarget, PresenceStream, Activity, Peer, PresenceUpdatePayload, ClaimLeaseOptions, Duration, ClaimOptions, ClaimStream, ClaimLost, ClaimStatus, ClaimWaitOptions, Claim, HeldClaim, } from './streams.js';

package/dist/{types → transaction/types}/index.js

@@ -4,6 +4,10 @@
  * These types describe how a model's properties are declared, when their data
  * is loaded, and how changes are represented on the wire as they synchronize.
  */
+// Bound locally as well as re-exported below: a bare `export … from` forwards
+// the name to consumers without binding it in this module, so the annotations
+// further down would not resolve.
+import { LoadStrategy } from '../schema/loadStrategy.js';
 /**
  * A lifecycle filter for queries: whether to return live entities, archived
  * ones, or both.
@@ -36,22 +40,9 @@ export var PropertyType;
     /** An array of foreign-key ids — a many-to-many relationship. */
     PropertyType["referenceArray"] = "referenceArray";
 })(PropertyType || (PropertyType = {}));
-/**
- * When and how a model's data is loaded from the server.
- */
-export var LoadStrategy;
-(function (LoadStrategy) {
-    /** Loaded during startup, before it is first used — for models needed right away. */
-    LoadStrategy["instant"] = "instant";
-    /** Loaded all at once the first time it is needed — for secondary models. */
-    LoadStrategy["lazy"] = "lazy";
-    /** Loaded on demand in subsets — for large collections. */
-    LoadStrategy["partial"] = "partial";
-    /** Loaded only when the application asks for it — for optional data. */
-    LoadStrategy["explicitlyRequested"] = "explicitlyRequested";
-    /** Never synced with the server; kept only on the client — for local-only state. */
-    LoadStrategy["local"] = "local";
-})(LoadStrategy || (LoadStrategy = {}));
+// When and how a model's data is loaded from the server. Defined in
+// `../schema/loadStrategy.ts`, which the authoring surface reads from too.
+export { LoadStrategy };
 /**
  * The operation a batch mutation performs on a model row.
  */

package/dist/{types → transaction/types}/streams.d.ts

@@ -9,8 +9,9 @@
  * layer underneath.
  */
 import type { InferModel, Schema } from '../schema/schema.js';
-import type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, ClaimLost, PresenceKind, ParticipantKind } from '../coordination/schema.js';
-export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, ClaimLost, PresenceKind, ParticipantKind, };
+import type { ResolveClaimMeta } from './global.js';
+import type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, ClaimLost, PresenceKind, ParticipantKind, PublicClaimStatus, PresenceUpdatePayload } from '../coordination/schema.js';
+export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, ClaimLost, PresenceKind, ParticipantKind, PresenceUpdatePayload, };
 /**
  * Any JSON-serializable value. Used where the SDK accepts free-form metadata
  * that is stored or transported as JSON — more precise than `unknown` while
@@ -19,37 +20,15 @@ export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, ClaimLost, Pr
 export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
-import type { ParticipantRef } from './participant.js';
 export type { ParticipantRef } from './participant.js';
+import type { Delta } from '../wire/delta.js';
+export type { ConfirmationState, Delta } from '../wire/delta.js';
 /**
- * Whether a person explicitly approved a change. If you don't track approval,
- * leave it at the default of `'auto'`.
+ * @deprecated Renamed to {@link Delta} — the authoritative change feed serves
+ * every participant, not only agents, and the seam names it plainly.
+ * Removed in 0.36.0.
  */
-export type ConfirmationState = 'auto' | 'previewed' | 'approved' | 'required_human_approval' | 'auto_historical';
-/**
- * The wire shape of a single change on the sync stream. Alongside the change
- * itself, it carries attribution fields — `actor`, `onBehalfOf`,
- * `capabilityId`, and `confirmationState` — recorded on each row for auditing.
- */
-export interface AgentDelta {
-    id: number;
-    actionType: 'I' | 'U' | 'D' | 'A';
-    modelName: string;
-    modelId: string;
-    data: Record<string, unknown>;
-    previousData?: Record<string, unknown>;
-    /** Who performed the action. */
-    actor?: ParticipantRef | null;
-    /** The participant on whose authority the actor acted. */
-    onBehalfOf?: ParticipantRef | null;
-    /** The capability that authorized this commit. */
-    capabilityId?: string | null;
-    /** Whether a person explicitly approved the change. */
-    confirmationState?: ConfirmationState | null;
-    /** The id of the agent task that caused this commit, if any. */
-    causedByTaskId?: string | null;
-    createdAt: string;
-}
+export type AgentDelta = Delta;
 /**
  * A flat, point-in-time view of application data returned by
  * `participant.snapshot(...)`. Capture it before long-running AI work, then
@@ -95,13 +74,40 @@ export interface ContextChange {
  * general-purpose hints for finer-grained coordination in tools like code
  * editors, document editors, and design tools.
  */
-export interface ClaimTarget {
+export interface ClaimTarget<M = ResolveClaimMeta> {
     readonly type: string;
     readonly id: string;
     readonly path?: string;
     readonly range?: TargetRange;
     readonly field?: string;
-    readonly meta?: Record<string, unknown>;
+    /**
+     * Several named parts of the row at once — three sections of a document, two
+     * cells of a table. Claims conflict where their sets intersect, so two
+     * holders working on disjoint parts of one row do not wait for each other.
+     *
+     * Use this instead of packing names into `field`: a delimited string compares
+     * as one opaque value, so `'b_1,b_2'` and `'b_2,b_3'` read as unrelated
+     * targets and both holders are granted `b_2`.
+     */
+    readonly fields?: readonly string[];
+    /**
+     * Application metadata, carried verbatim and never interpreted.
+     *
+     * The protocol does not know what is in here — the caller does, so the
+     * caller says so once, where the schema is already registered:
+     *
+     * ```ts
+     * declare module '@abloatai/ablo' {
+     *   interface Register { ClaimMeta: { blocks: string[] } }
+     * }
+     * ```
+     *
+     * From then on every claim surface reads this field as that shape and no
+     * read of it needs a `typeof` guard. The `M` parameter remains for a program
+     * carrying more than one meta shape — `claim.state<OtherMeta>({ id })`
+     * overrides the registration for that one call.
+     */
+    readonly meta?: M;
 }
 /**
  * A pointer to the entity a participant is acting on. Either a
@@ -146,7 +152,7 @@ export interface PresenceStream {
      *
      * You can drop `presence.others` into an LLM's system prompt so the model
      * reasons about what other agents are doing right now — for example,
-     * "copy-bot is generating a new title for slide 5; don't duplicate that work."
+     * "copy-bot is generating a new title for section 5; don't duplicate that work."
      */
     readonly others: readonly Peer[];
     /** Subset of `others` filtered to a specific sync group. */
@@ -203,7 +209,7 @@ export interface PresenceStream {
  * participants see the change in real time.
  */
 export interface Activity {
-    /** Entity type the participant is focused on (e.g. "Slide", "Document"). */
+    /** Entity type the participant is focused on (e.g. "Section", "Document"). */
     readonly entityType: string;
     /** Specific entity id. */
     readonly entityId: string;
@@ -213,6 +219,14 @@ export interface Activity {
     readonly range?: TargetRange;
     /** Optional field/property path for field-level coordination. */
     readonly field?: string;
+    /**
+     * Several named parts of the row at once — the same member
+     * {@link ClaimTarget} carries, and the one the presence frame has always
+     * declared. It was missing here, so a set-scoped participant announced
+     * itself as holding the whole row and the overlap filter compared it as if
+     * it named no parts at all.
+     */
+    readonly fields?: readonly string[];
     /** App-defined structured metadata. Display-only unless app policy uses it. */
     readonly meta?: Record<string, unknown>;
     /**
@@ -222,7 +236,7 @@ export interface Activity {
      * phases.
      */
     readonly action: string;
-    /** Human-readable detail — "slide 3", "cell A1:B5", etc. */
+    /** Human-readable detail — "section 3", "cell A1:B5", etc. */
     readonly detail?: string;
     /**
      * A backpressure signal in the range `[0.0, 1.0]`. When set, orchestrator
@@ -257,12 +271,6 @@ export interface Peer {
     /** The claims this participant currently holds. */
     readonly activeClaims?: readonly Claim[];
 }
-/** Outbound `presence_update` payload. */
-export interface PresenceUpdatePayload {
-    readonly status: 'online' | 'away' | 'offline' | (string & {});
-    readonly activity?: Activity;
-    readonly isAgent?: boolean;
-}
 /**
  * A claim is a broadcast that says "I'm about to work on this entity." Claims
  * travel on the same connection as presence, so every participant sees them in
@@ -296,6 +304,16 @@ export interface ClaimOptions extends ClaimLeaseOptions {
      * blocked writer receives. Defaults to `'editing'`.
      */
     readonly description?: string;
+    /**
+     * @deprecated Renamed to {@link ClaimOptions.description}. Still accepted —
+     * `description` wins when both are given — and removed in 0.36.0.
+     *
+     * The rename shipped without this line, so the server went on accepting
+     * `reason` while the type stopped offering it. Code written against the older
+     * shape kept working at runtime and stopped type-checking, with nothing
+     * saying why.
+     */
+    readonly reason?: string;
     /**
      * On contention, join the server's fair first-in-first-out queue instead of
      * being rejected. The grant then arrives asynchronously — immediately if the
@@ -385,14 +403,14 @@ export interface ClaimStream {
  * `position`. The remaining states are terminal and drop the claim from the
  * synced set.
  */
-export type ClaimStatus = 'active' | 'queued' | 'committed' | 'expired' | 'canceled';
+export type ClaimStatus = PublicClaimStatus;
 /** Options for waiting on a target to become free. */
 export interface ClaimWaitOptions {
     readonly timeout?: number;
     readonly pollInterval?: number;
     readonly signal?: AbortSignal;
 }
-export interface Claim<T = Record<string, unknown>> {
+export interface Claim<T = Record<string, unknown>, M = ResolveClaimMeta> {
     readonly object: 'claim';
     /** This claim's id. */
     readonly id: string;
@@ -403,7 +421,7 @@ export interface Claim<T = Record<string, unknown>> {
      */
     readonly status?: ClaimStatus;
     /** What is being coordinated. */
-    readonly target: ClaimTarget;
+    readonly target: ClaimTarget<M>;
     /**
      * Peer-visible description of the work being done — the same field on every
      * claim surface. Always present: the SDK resolves it as it decodes the frame,
@@ -509,7 +527,7 @@ export interface ClaimHeartbeat {
  * typecheck, since `Claim`'s optional dispose hook is not assignable to
  * `AsyncDisposable`.
  */
-export type HeldClaim<T = Record<string, unknown>> = Claim<T> & Required<Pick<Claim<T>, 'data' | 'release' | 'revoke' | 'heartbeat' | typeof Symbol.asyncDispose>>;
+export type HeldClaim<T = Record<string, unknown>, M = ResolveClaimMeta> = Claim<T, M> & Required<Pick<Claim<T, M>, 'data' | 'release' | 'revoke' | 'heartbeat' | typeof Symbol.asyncDispose>>;
 /**
  * A held advisory lease you took on a key whose row Ablo does not hold — the
  * resolved value of the row-free `ablo.<model>.claim(id)` overload. It is a

package/dist/{utils → transaction/utils}/json.d.ts

@@ -28,6 +28,24 @@
  * `text` column instead of `jsonb` — Ablo's adaptive codec serializes verbatim
  * there, matching Postgres's `json` type behavior.)
  */
+import type { JsonValue } from '../types/streams.js';
+/**
+ * Takes an immutable, plain snapshot at a JSON persistence/wire boundary.
+ *
+ * Traversal intentionally creates fresh objects and arrays instead of relying
+ * on a framework-specific unwrapping API. That makes Proxy-wrapped plain data
+ * (including MobX observables) safe for IndexedDB's structured-clone algorithm
+ * while keeping the settlement core independent of any reactive framework.
+ *
+ * The accepted contract is deliberately narrower than `JSON.stringify`:
+ * values that JSON would silently corrupt (`NaN` to `null`, `Map` to `{}`) or
+ * cannot encode are rejected with a stable, path-aware validation error.
+ * Valid dates retain normal JSON semantics and become ISO strings. Undefined
+ * object properties are omitted for compatibility with optional object keys;
+ * root/array `undefined` and sparse arrays are rejected rather than becoming
+ * an ambiguous `null`.
+ */
+export declare function snapshotJsonValue(value: unknown, path?: string): JsonValue;
 /** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
 export declare function deepEqual(a: unknown, b: unknown): boolean;
 /**