@abloatai/ablo 0.10.0 → 0.11.0

package/dist/sync/{createIntentStream.js → createClaimStream.js}

@@ -1,37 +1,38 @@
 /**
- * Transport-driven IntentStream factory.
+ * Transport-driven ClaimStream factory.
  *
  * Mirrors `createPresenceStream` — built directly on `SyncWebSocket`,
- * no SyncAgent wrapper. Intents derive their `others` view from the
+ * no SyncAgent wrapper. Claims derive their `others` view from the
  * same `presence_update` frames the presence stream consumes (the
- * Hub piggybacks `activeIntents` on every presence frame). Outbound
- * announce/revoke ride the same socket via `intent_begin` /
- * `intent_abandon` frames.
+ * Hub piggybacks `activeClaims` on every presence frame). Outbound
+ * announce/revoke ride the same socket via `claim_begin` /
+ * `claim_abandon` frames.
  *
  * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'intent_begin', payload: { intentId,
+ *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
  *       entityType, entityId, action, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'intent_abandon', payload: { intentId,
+ *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
  *       entityType?, entityId? } }`
- *   • Inbound (via presence): `event.activeIntents: IntentClaim[]`
+ *   • Inbound (via presence): `event.activeClaims: Claim[]`
  *     stamped with `declaredAt`, `expiresAt`.
- *   • Inbound: `intent_rejected` event with conflict metadata.
+ *   • Inbound: `claim_rejected` event with conflict metadata.
  *
  * After the dual-engine collapse (step #36), this is the only
- * IntentStream factory in the SDK; the older compatibility path
+ * ClaimStream factory in the SDK; the older compatibility path
  * deletes.
  */
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { toMs } from '../utils/duration.js';
-export function createIntentStream(config, transport = null) {
+import { descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+export function createClaimStream(config, transport = null) {
     const { participantId } = config;
-    // ── State: others' open intents, keyed by intentId ───────────────
-    const activeByIntentId = new Map();
-    let intentsSnapshot = Object.freeze([]);
-    // ── State: our own open intents (for re-announce on reconnect) ───
-    const ownIntents = new Map();
-    // ── State: per-entity wait queues, from `intent_queue` frames ────
-    // Keyed `type:id`; the value is the FIFO line of queued intents. Powers
+    // ── State: others' open claims, keyed by claimId ───────────────
+    const activeByClaimId = new Map();
+    let claimsSnapshot = Object.freeze([]);
+    // ── State: our own open claims (for re-announce on reconnect) ───
+    const ownClaims = new Map();
+    // ── State: per-entity wait queues, from `claim_queue` frames ────
+    // Keyed `type:id`; the value is the FIFO line of queued claims. Powers
     // the reactive `queue(target)` read — who's waiting and what they intend.
     const queueByEntity = new Map();
     const entityKey = (type, id) => `${type}:${id}`;
@@ -41,7 +42,7 @@ export function createIntentStream(config, transport = null) {
     const rejectionListeners = new Set();
     const lostListeners = new Set();
     const notifyListeners = () => {
-        intentsSnapshot = Object.freeze(Array.from(activeByIntentId.values()));
+        claimsSnapshot = Object.freeze(Array.from(activeByClaimId.values()));
         for (const l of listeners) {
             try {
                 l();
@@ -59,9 +60,9 @@ export function createIntentStream(config, transport = null) {
             return;
         attached = t;
         // (1) Inbound presence frames carry every participant's full
-        //     active-intent set. Prune previous claims by holder, then
+        //     active-claim set. Prune previous claims by holder, then
         //     re-add from the frame — the frame is authoritative for that
-        //     participant's open intents at that moment.
+        //     participant's open claims at that moment.
         unsubs.push(t.subscribe('presence_update', (event) => {
             if (!event.userId)
                 return;
@@ -69,9 +70,9 @@ export function createIntentStream(config, transport = null) {
                 return;
             let mutated = false;
             if (event.kind === 'leave') {
-                for (const [id, intent] of activeByIntentId) {
-                    if (intent.heldBy === event.userId) {
-                        activeByIntentId.delete(id);
+                for (const [id, claim] of activeByClaimId) {
+                    if (claim.heldBy === event.userId) {
+                        activeByClaimId.delete(id);
                         mutated = true;
                     }
                 }
@@ -79,13 +80,13 @@ export function createIntentStream(config, transport = null) {
                     notifyListeners();
                 return;
             }
-            for (const [id, intent] of activeByIntentId) {
-                if (intent.heldBy === event.userId) {
-                    activeByIntentId.delete(id);
+            for (const [id, claim] of activeByClaimId) {
+                if (claim.heldBy === event.userId) {
+                    activeByClaimId.delete(id);
                     mutated = true;
                 }
             }
-            for (const claim of event.activeIntents ?? []) {
+            for (const claim of event.activeClaims ?? []) {
                 // Terminal-status entries (committed / expired / canceled) are
                 // one-shot "this claim ended" signals. The holder sweep above
                 // already removed the prior active entry; skipping the re-add
@@ -93,13 +94,11 @@ export function createIntentStream(config, transport = null) {
                 // `settled()`. Absent status means active (wire back-compat).
                 if (claim.status && claim.status !== 'active')
                     continue;
-                const description = typeof claim.meta?.description === 'string'
-                    ? claim.meta.description
-                    : undefined;
-                activeByIntentId.set(claim.intentId, {
-                    id: claim.intentId,
+                const description = descriptionFromMeta(claim.meta);
+                activeByClaimId.set(claim.claimId, {
+                    id: claim.claimId,
                     heldBy: event.userId,
-                    participantKind: event.isAgent ? 'agent' : 'human',
+                    participantKind: participantKindFromWire(event.participantKind, event.isAgent),
                     target: {
                         type: claim.entityType,
                         id: claim.entityId,
@@ -111,8 +110,8 @@ export function createIntentStream(config, transport = null) {
                     reason: claim.action,
                     ...(description ? { description } : {}),
                     ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
-                    announcedAt: new Date(claim.declaredAt).toISOString(),
-                    expiresAt: new Date(claim.expiresAt).toISOString(),
+                    announcedAt: claim.declaredAt,
+                    expiresAt: claim.expiresAt,
                 });
                 mutated = true;
             }
@@ -120,14 +119,13 @@ export function createIntentStream(config, transport = null) {
                 notifyListeners();
         }));
         // (2) Server-side rejection frames.
-        unsubs.push(t.subscribe('intent_rejected', (payload) => {
-            const rejection = payload;
-            if (!rejection.intentId)
+        unsubs.push(t.subscribe('claim_rejected', (rejection) => {
+            if (!rejection.claimId)
                 return;
             // Drop the rejected own-claim so reconnect doesn't re-announce
             // a claim the server already rejected (would just spam both
             // sides with conflicts).
-            ownIntents.delete(rejection.intentId);
+            ownClaims.delete(rejection.claimId);
             for (const l of rejectionListeners) {
                 try {
                     l(rejection);
@@ -139,13 +137,13 @@ export function createIntentStream(config, transport = null) {
         }));
         // (2a) Server-side LOSS frames — you held it, then lost it (preempted /
         //      expired). Distinct from a rejection (a claim the server refused).
-        unsubs.push(t.subscribe('intent_lost', (payload) => {
+        unsubs.push(t.subscribe('claim_lost', (payload) => {
             const lost = payload;
-            if (!lost.intentId)
+            if (!lost.claimId)
                 return;
             // Drop the lost own-claim so reconnect doesn't re-announce a lease we
             // no longer hold.
-            ownIntents.delete(lost.intentId);
+            ownClaims.delete(lost.claimId);
             for (const l of lostListeners) {
                 try {
                     l(lost);
@@ -158,7 +156,7 @@ export function createIntentStream(config, transport = null) {
         // (2b) Per-entity wait-queue snapshots. The server fans the full line
         //      out on every queue mutation; we replace our cached line for that
         //      entity and notify so `queue(target)` reads reactively.
-        unsubs.push(t.subscribe('intent_queue', (payload) => {
+        unsubs.push(t.subscribe('claim_queue', (payload) => {
             const p = payload;
             if (!p.target?.type || !p.target.id)
                 return;
@@ -171,34 +169,34 @@ export function createIntentStream(config, transport = null) {
             notifyListeners();
         }));
         // (3) On reconnect, re-announce every open self-claim — the
-        //     server's intent state is in-memory and is lost across
+        //     server's claim state is in-memory and is lost across
         //     restarts. Without this, peers would see our claims vanish
         //     whenever the connection blipped.
         unsubs.push(t.subscribe('connected', () => {
-            for (const [intentId, intent] of ownIntents) {
-                sendBegin(intentId, intent);
+            for (const [claimId, claim] of ownClaims) {
+                sendBegin(claimId, claim);
             }
         }));
     }
     if (transport)
         attach(transport);
     // ── Outbound ────────────────────────────────────────────────────
-    function sendBegin(intentId, intent) {
+    function sendBegin(claimId, claim) {
         if (!attached?.isConnected())
             return;
         attached.send({
-            type: 'intent_begin',
+            type: 'claim_begin',
             payload: {
-                intentId,
-                entityType: intent.entityType,
-                entityId: intent.entityId,
-                path: intent.path,
-                range: intent.range,
-                action: intent.action,
-                field: intent.field,
-                meta: intent.meta,
-                estimatedMs: intent.estimatedMs,
-                queue: intent.queue,
+                claimId,
+                entityType: claim.entityType,
+                entityId: claim.entityId,
+                path: claim.path,
+                range: claim.range,
+                action: claim.action,
+                field: claim.field,
+                meta: claim.meta,
+                estimatedMs: claim.estimatedMs,
+                queue: claim.queue,
             },
         });
     }
@@ -206,28 +204,28 @@ export function createIntentStream(config, transport = null) {
         if (!attached?.isConnected())
             return;
         attached.send({
-            type: 'intent_reorder',
+            type: 'claim_reorder',
             payload: {
                 entityType,
                 entityId,
-                // The wire shape identifies a waiter by heldBy + intentId; map the
-                // ergonomic `Intent[]` (what `queueFor` returns) down to that.
-                order: order.map((i) => ({ heldBy: i.heldBy, intentId: i.id })),
+                // The wire shape identifies a waiter by heldBy + claimId; map the
+                // ergonomic `Claim[]` (what `queueFor` returns) down to that.
+                order: order.map((i) => ({ heldBy: i.heldBy, claimId: i.id })),
             },
         });
     }
-    function sendAbandon(intentId, intent) {
+    function sendAbandon(claimId, claim) {
         if (!attached?.isConnected())
             return;
         // Carry the target so the server can dequeue us if we were only *waiting*
         // (a queued claim isn't in the holder set it would otherwise scan). Held
-        // claims are found by intentId regardless; the target is harmless there.
+        // claims are found by claimId regardless; the target is harmless there.
         attached.send({
-            type: 'intent_abandon',
+            type: 'claim_abandon',
             payload: {
-                intentId,
-                entityType: intent?.entityType,
-                entityId: intent?.entityId,
+                claimId,
+                entityType: claim?.entityType,
+                entityId: claim?.entityId,
             },
         });
     }
@@ -237,9 +235,9 @@ export function createIntentStream(config, transport = null) {
         return { ...(meta ?? {}), description };
     }
     function mintHandle(args) {
-        const intentId = crypto.randomUUID();
+        const claimId = crypto.randomUUID();
         const estimatedMs = args.ttl !== undefined ? toMs(args.ttl) : undefined;
-        const intent = {
+        const claim = {
             entityType: args.entityType,
             entityId: args.entityId,
             path: args.path,
@@ -250,18 +248,31 @@ export function createIntentStream(config, transport = null) {
             estimatedMs,
             queue: args.queue,
         };
-        ownIntents.set(intentId, intent);
-        sendBegin(intentId, intent);
+        ownClaims.set(claimId, claim);
+        sendBegin(claimId, claim);
         let revoked = false;
         const revoke = () => {
             if (revoked)
                 return;
             revoked = true;
-            ownIntents.delete(intentId);
-            sendAbandon(intentId, intent);
+            ownClaims.delete(claimId);
+            sendAbandon(claimId, claim);
         };
         return {
-            id: intentId,
+            object: 'claim',
+            claimId,
+            action: args.action,
+            target: {
+                model: args.entityType,
+                id: args.entityId,
+                path: args.path,
+                range: args.range,
+                field: args.field,
+                meta: args.meta,
+            },
+            release: async () => {
+                revoke();
+            },
             revoke,
             [Symbol.asyncDispose]: async () => {
                 revoke();
@@ -289,7 +300,7 @@ export function createIntentStream(config, transport = null) {
             });
         },
         get others() {
-            return intentsSnapshot;
+            return claimsSnapshot;
         },
         queueFor(target) {
             const ref = resolveTarget(target);
@@ -323,7 +334,7 @@ export function createIntentStream(config, transport = null) {
                 return () => {
                     listeners.delete(onChange);
                 };
-            }, () => intentsSnapshot);
+            }, () => claimsSnapshot);
         },
         attach,
         dispose() {
@@ -333,10 +344,10 @@ export function createIntentStream(config, transport = null) {
             listeners.clear();
             rejectionListeners.clear();
             lostListeners.clear();
-            activeByIntentId.clear();
-            ownIntents.clear();
+            activeByClaimId.clear();
+            ownClaims.clear();
             queueByEntity.clear();
-            intentsSnapshot = Object.freeze([]);
+            claimsSnapshot = Object.freeze([]);
             attached = null;
         },
     };

package/dist/sync/createPresenceStream.js

@@ -22,11 +22,12 @@
  *   • Inbound:  same frame, with `kind: 'enter' | 'update' | 'leave'`.
  */
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
+import { participantKindFromWire } from '../coordination/schema.js';
 export function createPresenceStream(config, transport = null) {
     const { participantId, label, syncGroups, isAgent = false } = config;
     // ── Self ─────────────────────────────────────────────────────────
     const self = {
-        participantKind: isAgent ? 'agent' : 'human',
+        participantKind: isAgent ? 'agent' : 'user',
         participantId,
         label,
         syncGroups: [...syncGroups],
@@ -84,7 +85,7 @@ export function createPresenceStream(config, transport = null) {
                 case 'update':
                 case undefined: {
                     const entry = {
-                        participantKind: event.isAgent ? 'agent' : 'human',
+                        participantKind: participantKindFromWire(event.participantKind, event.isAgent),
                         participantId: event.userId,
                         syncGroups: event.syncGroups ?? [],
                         activity: event.activity

package/dist/sync/participants.d.ts

@@ -1,6 +1,6 @@
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
-import type { ActiveIntent, Activity, EntityRef, Claim, IntentStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
+import type { ActiveClaim, Activity, EntityRef, ClaimHandle, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
 /**
  * Scope accepted by participant APIs. The normal SDK shape is an
  * entity target (`{ type, id }`). Raw sync-group strings remain an
@@ -14,7 +14,7 @@ export type ParticipantScope = EntityRef | readonly EntityRef[] | string | reado
 export type ParticipantStatus = 'idle' | 'connecting' | 'connected' | 'error' | 'disconnected';
 export interface EngineParticipant {
     readonly presence: PresenceStream;
-    readonly intents: IntentStream;
+    readonly claims: ClaimStream;
 }
 export interface ParticipantJoinOptions {
     /**
@@ -65,17 +65,17 @@ export interface ScopedClaimOptions {
     /** TTL — server auto-expires the claim after this. */
     readonly ttl?: import('../types/streams.js').Duration;
 }
-export interface ScopedIntents {
+export interface ScopedClaims {
     readonly focus: EntityRef | null;
-    readonly others: ReadonlyArray<ActiveIntent>;
+    readonly others: ReadonlyArray<ActiveClaim>;
     /**
-     * Claim an exclusive intent on the participant's focus target (or
+     * Claim an exclusive claim on the participant's focus target (or
      * an explicit override via `opts.target`). Single verb — the old
      * `editing / writing / announce / claim(reason, opts)` overloads
      * collapsed into this one method.
      */
-    claim(opts?: ScopedClaimOptions): Claim;
-    onRejected(listener: Parameters<IntentStream['onRejected']>[0]): () => void;
+    claim(opts?: ScopedClaimOptions): ClaimHandle;
+    onRejected(listener: Parameters<ClaimStream['onRejected']>[0]): () => void;
     onChange(listener: () => void): () => void;
 }
 export interface ParticipantFocusOptions {
@@ -89,9 +89,9 @@ export interface JoinedParticipant {
     /** Transport scopes this participant is joined to for visibility/fan-out. */
     readonly syncGroups: readonly string[];
     readonly presence: ScopedPresence;
-    readonly intents: ScopedIntents;
+    readonly claims: ScopedClaims;
     readonly peers: ReadonlyArray<Peer>;
-    readonly claims: ReadonlyArray<ActiveIntent>;
+    readonly activeClaims: ReadonlyArray<ActiveClaim>;
     focus(target: PresenceTarget, options?: ParticipantFocusOptions): JoinedParticipant;
     leave(): void;
     [Symbol.asyncDispose](): Promise<void>;
@@ -104,7 +104,7 @@ export interface ParticipantManagerConfig {
     readonly ready: () => Promise<void>;
     readonly getTransport: () => SyncWebSocket | null;
     readonly presence: PresenceStream;
-    readonly intents: IntentStream;
+    readonly claims: ClaimStream;
     readonly schema?: Schema<SchemaRecord>;
 }
 export declare function createParticipantManager(config: ParticipantManagerConfig): ParticipantManager;

package/dist/sync/participants.js

@@ -26,7 +26,7 @@ export function createParticipantManager(config) {
                 claimId,
                 transport,
                 presence: config.presence,
-                intents: config.intents,
+                claims: config.claims,
             });
             if (target && options.activity !== false) {
                 const activity = options.activity ?? 'reading';
@@ -219,7 +219,14 @@ function createJoinedParticipant(args) {
     const track = (handle) => {
         ownHandles.add(handle);
         return {
-            id: handle.id,
+            object: 'claim',
+            claimId: handle.claimId,
+            action: handle.action,
+            target: handle.target,
+            async release() {
+                ownHandles.delete(handle);
+                await handle.release();
+            },
             revoke() {
                 ownHandles.delete(handle);
                 handle.revoke();
@@ -230,24 +237,24 @@ function createJoinedParticipant(args) {
             },
         };
     };
-    const scopedIntents = {
+    const scopedClaims = {
         get focus() {
             return currentTarget;
         },
         get others() {
-            return args.intents.others.filter((intent) => currentTarget ? targetsOverlap(intent.target, currentTarget) : true);
+            return args.claims.others.filter((claim) => currentTarget ? targetsOverlap(claim.target, currentTarget) : true);
         },
         claim(opts) {
-            return track(args.intents.claim(requireTarget(opts?.target), {
+            return track(args.claims.claim(requireTarget(opts?.target), {
                 reason: opts?.reason,
                 ttl: opts?.ttl,
             }));
         },
         onRejected(listener) {
-            return args.intents.onRejected(listener);
+            return args.claims.onRejected(listener);
         },
         onChange(listener) {
-            return args.intents.onChange(listener);
+            return args.claims.onChange(listener);
         },
     };
     const leave = () => {
@@ -272,12 +279,12 @@ function createJoinedParticipant(args) {
         },
         syncGroups: [...args.syncGroups],
         presence: scopedPresence,
-        intents: scopedIntents,
+        claims: scopedClaims,
         get peers() {
             return scopedPresence.others;
         },
-        get claims() {
-            return scopedIntents.others;
+        get activeClaims() {
+            return scopedClaims.others;
         },
         focus: setFocus,
         leave,

package/dist/sync/schemas.d.ts

@@ -8,24 +8,24 @@ import { z } from 'zod';
 export declare const ServerDeltaSchema: z.ZodObject<{
     id: z.ZodNumber;
     operation: z.ZodOptional<z.ZodEnum<{
-        A: "A";
         I: "I";
         U: "U";
         D: "D";
+        A: "A";
+        V: "V";
         C: "C";
         G: "G";
         S: "S";
-        V: "V";
     }>>;
     action: z.ZodOptional<z.ZodEnum<{
-        A: "A";
         I: "I";
         U: "U";
         D: "D";
+        A: "A";
+        V: "V";
         C: "C";
         G: "G";
         S: "S";
-        V: "V";
     }>>;
     modelName: z.ZodString;
     entityId: z.ZodOptional<z.ZodString>;
@@ -43,24 +43,24 @@ export declare const BootstrapResponseSchema: z.ZodObject<{
     deltas: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
         operation: z.ZodOptional<z.ZodEnum<{
-            A: "A";
             I: "I";
             U: "U";
             D: "D";
+            A: "A";
+            V: "V";
             C: "C";
             G: "G";
             S: "S";
-            V: "V";
         }>>;
         action: z.ZodOptional<z.ZodEnum<{
-            A: "A";
             I: "I";
             U: "U";
             D: "D";
+            A: "A";
+            V: "V";
             C: "C";
             G: "G";
             S: "S";
-            V: "V";
         }>>;
         modelName: z.ZodString;
         entityId: z.ZodOptional<z.ZodString>;

package/dist/transactions/TransactionQueue.d.ts

@@ -36,6 +36,8 @@ export interface Transaction {
     priorityScore: number;
     writeOptions?: WriteOptions;
     batchId?: string;
+    /** Completed locally without a server operation; no sync echo will arrive. */
+    localOnly?: boolean;
     /** LINEAR PATTERN: syncId threshold - transaction confirms when delta.id >= this value */
     syncIdNeededForCompletion?: number;
     /**
@@ -130,11 +132,21 @@ export declare class TransactionQueue extends EventEmitter {
     private commitScheduled;
     private inFlightByModel;
     private pendingMergeByModel;
+    private deferredDeletesByCreate;
     private commitLane;
     private commitStore;
     private commitProcessing;
     private computePriorityScore;
     private ensureDerivedFields;
+    private entityKey;
+    private isTransactionForModel;
+    private resolveConfirmation;
+    private takeUnsentCreateForModel;
+    private cancelUnsentCreateForDelete;
+    private findCreateBarrierForDelete;
+    private completeLocalDelete;
+    private deferDeleteUntilCreateSettles;
+    private releaseDeferredDeletesForCreate;
     private mergeUpdateData;
     private config;
     private executingCount;