@abloatai/ablo 0.10.1 → 0.11.1

package/dist/transactions/TransactionQueue.js

@@ -225,6 +225,7 @@ export class TransactionQueue extends EventEmitter {
     // Per-model in-flight tracking and merge buffer
     inFlightByModel = new Set();
     pendingMergeByModel = new Map();
+    deferredDeletesByCreate = new Map();
     // Commit lane: pre-built atomic multi-op envelopes from `ablo.commits.create()`.
     // Drained serially (one envelope at a time) since each is atomic; no
     // coalescing with model-proxy transactions.
@@ -242,6 +243,102 @@ export class TransactionQueue extends EventEmitter {
             transaction.priorityScore = this.computePriorityScore(transaction.type, transaction.modelName);
         }
     }
+    entityKey(modelName, modelId) {
+        return `${modelName}:${modelId}`;
+    }
+    isTransactionForModel(transaction, modelName, modelId) {
+        return transaction.modelName === modelName && transaction.modelId === modelId;
+    }
+    resolveConfirmation(transaction) {
+        const resolver = this.confirmationResolvers.get(transaction.id);
+        if (!resolver)
+            return;
+        this.confirmationResolvers.delete(transaction.id);
+        resolver.resolve();
+    }
+    takeUnsentCreateForModel(modelName, modelId) {
+        const isUnsentCreate = (tx) => tx.type === 'create' &&
+            tx.status === 'pending' &&
+            tx.attempts === 0 &&
+            this.isTransactionForModel(tx, modelName, modelId);
+        const stagedIndex = this.createdTransactions.findIndex(isUnsentCreate);
+        if (stagedIndex >= 0) {
+            return this.createdTransactions.splice(stagedIndex, 1)[0];
+        }
+        const queuedIndex = this.executionQueue.findIndex(isUnsentCreate);
+        if (queuedIndex >= 0) {
+            return this.executionQueue.splice(queuedIndex, 1)[0];
+        }
+        return this.store.getByStatus('pending').find(isUnsentCreate);
+    }
+    async cancelUnsentCreateForDelete(transaction) {
+        this.store.updateStatus(transaction.id, 'rolled_back');
+        if (this.config.enableOptimistic) {
+            await this.rollbackOptimistic(transaction, 'model_cancelled');
+        }
+        this.resolveConfirmation(transaction);
+    }
+    findCreateBarrierForDelete(modelName, modelId) {
+        const liveCreates = [
+            ...this.store.getByStatus('pending'),
+            ...this.store.getByStatus('executing'),
+            ...this.store.getByStatus('awaiting_delta'),
+        ].filter((tx) => tx.type === 'create' &&
+            this.isTransactionForModel(tx, modelName, modelId) &&
+            // A never-attempted pending create can be cancelled instead. Once the
+            // create has been sent, even a retry-pending state is a causal barrier:
+            // the server may already have applied it and only the response was lost.
+            (tx.status !== 'pending' || tx.attempts > 0));
+        return liveCreates.sort((a, b) => b.createdAt - a.createdAt)[0];
+    }
+    completeLocalDelete(model, context, writeOptions) {
+        const actualModelName = model.getModelName();
+        const modelKey = normalizeModelKey(actualModelName);
+        const transaction = {
+            id: this.generateId(),
+            type: 'delete',
+            modelName: actualModelName,
+            modelId: model.id,
+            modelKey,
+            priorityScore: this.computePriorityScore('delete', actualModelName),
+            previousData: model.toJSON ? model.toJSON() : { ...model },
+            context,
+            status: 'completed',
+            createdAt: Date.now(),
+            attempts: 0,
+            priority: 'high',
+            writeOptions,
+            localOnly: true,
+        };
+        this.attachConfirmation(transaction);
+        this.store.add(transaction);
+        if (this.config.enableOptimistic) {
+            this.applyOptimisticDelete(model, transaction);
+        }
+        this.emit('transaction:created', transaction);
+        this.emit('transaction:completed', transaction);
+        this.emit(`transaction:completed:${transaction.id}`, transaction);
+        this.optimisticUpdates.delete(transaction.id);
+        return transaction;
+    }
+    deferDeleteUntilCreateSettles(createTransaction, deleteTransaction) {
+        const key = this.entityKey(createTransaction.modelName, createTransaction.modelId);
+        const deferred = this.deferredDeletesByCreate.get(key) ?? [];
+        deferred.push(deleteTransaction);
+        this.deferredDeletesByCreate.set(key, deferred);
+    }
+    releaseDeferredDeletesForCreate(createTransaction) {
+        const key = this.entityKey(createTransaction.modelName, createTransaction.modelId);
+        const deferred = this.deferredDeletesByCreate.get(key);
+        if (!deferred || deferred.length === 0)
+            return;
+        this.deferredDeletesByCreate.delete(key);
+        for (const deleteTransaction of deferred) {
+            if (this.store.get(deleteTransaction.id)?.status !== 'pending')
+                continue;
+            this.enqueue(deleteTransaction);
+        }
+    }
     // Merge two GraphQL update payloads with special handling for metadata fields
     mergeUpdateData(left, right, _modelName) {
         const out = { ...(left || {}) };
@@ -374,6 +471,9 @@ export class TransactionQueue extends EventEmitter {
                 this.confirmationResolvers.delete(tx.id);
                 r.resolve();
             }
+            if (tx.type === 'create') {
+                this.releaseDeferredDeletesForCreate(tx);
+            }
         });
         this.on('transaction:failed', ({ transaction, error }) => {
             const r = this.confirmationResolvers.get(transaction.id);
@@ -381,6 +481,9 @@ export class TransactionQueue extends EventEmitter {
                 this.confirmationResolvers.delete(transaction.id);
                 r.reject(error);
             }
+            if (transaction.type === 'create') {
+                this.releaseDeferredDeletesForCreate(transaction);
+            }
         });
     }
     /**
@@ -670,6 +773,15 @@ export class TransactionQueue extends EventEmitter {
             ? this.mapChangesToInput(actualModelName, precomputedChanges)
             : this.extractUpdateData(model);
         const previousData = this.extractPreviousData(model, updateInput);
+        // Advance the per-field baseline for the keys we just froze into this
+        // transaction. `Model.propertyChanged` is first-old-wins and only cleared on
+        // sync-ack, so without this a SECOND update to the same field before the
+        // first acks would re-capture the original `.old` (the pre-session value)
+        // instead of THIS update's result — corrupting the stream-recorded undo
+        // inverse (the second move's "before" would point all the way back). The
+        // wire payload is already frozen in `transaction.data`, so dropping the
+        // consumed entries is safe. Mirrors `RecordingTransaction.consumeModifiedFields`.
+        this.consumeModifiedFields(model, updateInput);
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('update', actualModelName);
         const transaction = {
@@ -726,6 +838,7 @@ export class TransactionQueue extends EventEmitter {
                 attempts: 0,
                 priority: 'high',
                 writeOptions,
+                localOnly: true,
                 // Activity deletes complete synchronously (audit-record skip path).
                 // Pre-resolved so consumers can still `await tx.confirmation` uniformly.
                 confirmation: Promise.resolve(),
@@ -740,6 +853,11 @@ export class TransactionQueue extends EventEmitter {
         }
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('delete', actualModelName);
+        const unsentCreate = this.takeUnsentCreateForModel(actualModelName, model.id);
+        if (unsentCreate) {
+            await this.cancelUnsentCreateForDelete(unsentCreate);
+            return this.completeLocalDelete(model, context, writeOptions);
+        }
         const transaction = {
             id: this.generateId(),
             type: 'delete',
@@ -760,15 +878,22 @@ export class TransactionQueue extends EventEmitter {
         // Cancel any pending/in-flight updates for this model to prevent "no rows" errors
         // when the delete executes before the update (race condition fix)
         this.cancelTransactionsForModel(model.id, 'update');
-        this.pendingMergeByModel.delete(`${actualModelName}:${model.id}`);
-        this.inFlightByModel.delete(`${actualModelName}:${model.id}`);
+        const entityKey = this.entityKey(actualModelName, model.id);
+        this.pendingMergeByModel.delete(entityKey);
+        this.inFlightByModel.delete(entityKey);
         // Apply optimistic delete
         if (this.config.enableOptimistic) {
             this.applyOptimisticDelete(model, transaction);
         }
-        // LINEAR PATTERN: Stage transaction for microtask commit
-        // All deletes in same event loop will be batched together
-        this.stageTransaction(transaction);
+        const createBarrier = this.findCreateBarrierForDelete(actualModelName, model.id);
+        if (createBarrier) {
+            this.deferDeleteUntilCreateSettles(createBarrier, transaction);
+        }
+        else {
+            // LINEAR PATTERN: Stage transaction for microtask commit
+            // All deletes in same event loop will be batched together
+            this.stageTransaction(transaction);
+        }
         this.emit('transaction:created', transaction);
         return transaction;
     }
@@ -1015,7 +1140,7 @@ export class TransactionQueue extends EventEmitter {
                             tx.syncIdNeededForCompletion = lastSyncId;
                             // Safety net: when lastSyncId is 0, DELETE transactions should be confirmed
                             // immediately. DELETEs are idempotent — if no delta was emitted, the entity
-                            // is already gone and the intent was achieved. Parking DELETEs in awaiting_delta
+                            // is already gone and the claim was achieved. Parking DELETEs in awaiting_delta
                             // with threshold 0 causes 30s reconciliation delays.
                             if (lastSyncId === 0 && tx.type === 'delete') {
                                 this.store.updateStatus(tx.id, 'completed');
@@ -1110,14 +1235,14 @@ export class TransactionQueue extends EventEmitter {
                         });
                         // LINEAR PATTERN: Handle "no rows in result set" gracefully
                         // This error means the entity was already deleted - for UPDATE/DELETE ops, this is success
-                        // The intent was achieved (the data doesn't exist), so treat as completed
+                        // The claim was achieved (the data doesn't exist), so treat as completed
                         if (errorMessage.includes('no rows in result set')) {
                             getContext().logger.info('[TransactionQueue] Graceful handling: entity already deleted', {
                                 batchSize: batchOps.length,
                             });
                             for (const { tx, op } of batchOps) {
                                 if (op.type === 'UPDATE' || op.type === 'DELETE') {
-                                    // Entity gone = intent achieved, mark as completed
+                                    // Entity gone = claim achieved, mark as completed
                                     this.store.updateStatus(tx.id, 'completed');
                                     this.emit('transaction:completed', tx);
                                     getContext().logger.debug('[TransactionQueue] Orphaned transaction treated as success', {
@@ -1875,16 +2000,63 @@ export class TransactionQueue extends EventEmitter {
     // expose a typed `getPreviousData()` accessor on Model and call that.
     extractPreviousData(model, updateInput) {
         const prev = { id: model.id };
-        if (model.modifiedProperties instanceof Map && model.modifiedProperties.size > 0) {
-            for (const [key, change] of model.modifiedProperties) {
-                // Only include keys that are part of this update if provided
-                if (updateInput && !(key in updateInput))
+        const modified = model.modifiedProperties instanceof Map ? model.modifiedProperties : null;
+        // When the update's written keys are known, capture a before-image for
+        // EXACTLY those keys so the recorded undo inverse can revert them and only
+        // them (a full-row inverse would clobber concurrent edits to unrelated
+        // fields). Resolution order mirrors `RecordingTransaction.snapshotFields`:
+        //   1. `modifiedProperties.old` — first-old-wins pre-session baseline, set
+        //      whenever the caller mutated the field in place before committing.
+        //   2. `getOriginalSnapshot()` — the last loaded/acked row, the correct
+        //      before-image for a key written WITHOUT a prior in-place mutation
+        //      (e.g. a `precomputedChanges` write).
+        // Without (2) such a key yields an empty `previousData`, and `buildUndoOps`
+        // nulls the inverse entirely — making updates silently un-undoable where a
+        // create's `delete(id)` inverse never is. This closes that asymmetry.
+        if (updateInput) {
+            const original = model.getOriginalSnapshot();
+            for (const key of Object.keys(updateInput)) {
+                if (key === 'id')
                     continue;
+                const mod = modified?.get(key);
+                if (mod) {
+                    prev[key] = mod.old;
+                }
+                else if (original && key in original) {
+                    prev[key] = original[key];
+                }
+            }
+            return prev;
+        }
+        if (modified && modified.size > 0) {
+            for (const [key, change] of modified) {
                 prev[key] = change.old;
             }
         }
         return prev;
     }
+    /**
+     * Re-baseline `modifiedProperties` for the fields a freshly-staged update just
+     * committed. Called right after {@link extractPreviousData} freezes their
+     * `.old` into the transaction, so the NEXT update to the same field sees this
+     * update's result as its baseline rather than the stale pre-session `.old`
+     * preserved by `Model.propertyChanged`'s first-old-wins policy. Only consumes
+     * keys present in this update — untouched fields keep their baselines. Safe
+     * because the wire payload lives on `transaction.data` and rollback restores
+     * from `transaction.previousData`; neither re-reads `modifiedProperties`.
+     */
+    consumeModifiedFields(model, updateInput) {
+        if (!(model.modifiedProperties instanceof Map) || model.modifiedProperties.size === 0) {
+            return;
+        }
+        for (const key of [...model.modifiedProperties.keys()]) {
+            if (key === 'id')
+                continue;
+            if (updateInput && !(key in updateInput))
+                continue;
+            model.modifiedProperties.delete(key);
+        }
+    }
     /**
      * Public API
      */
@@ -1973,6 +2145,8 @@ export class TransactionQueue extends EventEmitter {
         this.store.clear();
         this.optimisticUpdates.clear();
         this.executionQueue = [];
+        this.createdTransactions = [];
+        this.deferredDeletesByCreate.clear();
         // Clear event listeners
         this.removeAllListeners();
         // Reset state

package/dist/types/global.d.ts

@@ -1,9 +1,9 @@
 /**
  * Type registration point for SDK consumers.
  *
- * A consumer registers their Schema, Presence, Intents, and UserMeta ONCE by
+ * A consumer registers their Schema, Presence, Claims, and UserMeta ONCE by
  * augmenting the {@link Register} interface, and every SDK hook — `useAblo`,
- * `useQuery`, `useOne`, `usePresence`, `useIntent` — reads its types from the
+ * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from the
  * resolved registration. No generics at call sites, no `schema` arg per call.
  *
  * Registration is done via **module augmentation** of `@abloatai/ablo` —
@@ -12,17 +12,22 @@
  * global, not prefixed). It's a language feature, not a library trick: any file
  * in the compilation can augment it and every resolver below picks it up.
  *
- * Consumer example:
+ * Consumer example (`npx ablo init` scaffolds this as `ablo/register.ts`, a
+ * sibling of `ablo/schema.ts`). It's a regular `.ts` module, NOT a hand-authored
+ * `.d.ts`: the top-level `import type { schema }` makes the `declare module`
+ * block MERGE (augment) this interface rather than collide with it — the same
+ * shape TanStack Router uses in `src/router.tsx`. Any `.ts` file in the
+ * `tsconfig` `include` works; it never needs to be imported.
  *
  * ```ts
- * // apps/your-app/src/ablo.d.ts
- * import type { schema } from './your-schema';
+ * // ablo/register.ts
+ * import type { schema } from './schema';
  *
  * declare module '@abloatai/ablo' {
  *   interface Register {
  *     Schema: typeof schema;
  *     Presence: { cursor: { x: number; y: number } | null };
- *     Intents: { editLayer: { layerId: string } };
+ *     Claims: { editLayer: { layerId: string } };
  *     UserMeta: { id: string; email: string };
  *   }
  * }
@@ -44,7 +49,7 @@ export interface DefaultSyncShape {
         readonly models: Record<string, unknown>;
     };
     readonly Presence: Record<string, unknown>;
-    readonly Intents: Record<string, unknown>;
+    readonly Claims: Record<string, unknown>;
     readonly UserMeta: {
         readonly id: string;
     };
@@ -75,13 +80,13 @@ export type ResolvePresence = Register extends {
     Presence: infer P;
 } ? P : DefaultSyncShape['Presence'];
 /**
- * The consumer's intent vocabulary, or the default if unregistered. Keys are
- * intent names; values are the claim payload for each intent. Used by
- * `useIntent(intentName)`.
+ * The consumer's claim vocabulary, or the default if unregistered. Keys are
+ * claim names; values are the claim payload for each claim. Used by
+ * `useClaim(claimName)`.
  */
-export type ResolveIntents = Register extends {
-    Intents: infer I;
-} ? I : DefaultSyncShape['Intents'];
+export type ResolveClaims = Register extends {
+    Claims: infer I;
+} ? I : DefaultSyncShape['Claims'];
 /**
  * The consumer's user-metadata shape, or the default if unregistered. Carries
  * identity info the consumer trusts from their auth layer — not SDK-validated.

package/dist/types/global.js

@@ -1,9 +1,9 @@
 /**
  * Type registration point for SDK consumers.
  *
- * A consumer registers their Schema, Presence, Intents, and UserMeta ONCE by
+ * A consumer registers their Schema, Presence, Claims, and UserMeta ONCE by
  * augmenting the {@link Register} interface, and every SDK hook — `useAblo`,
- * `useQuery`, `useOne`, `usePresence`, `useIntent` — reads its types from the
+ * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from the
  * resolved registration. No generics at call sites, no `schema` arg per call.
  *
  * Registration is done via **module augmentation** of `@abloatai/ablo` —
@@ -12,17 +12,22 @@
  * global, not prefixed). It's a language feature, not a library trick: any file
  * in the compilation can augment it and every resolver below picks it up.
  *
- * Consumer example:
+ * Consumer example (`npx ablo init` scaffolds this as `ablo/register.ts`, a
+ * sibling of `ablo/schema.ts`). It's a regular `.ts` module, NOT a hand-authored
+ * `.d.ts`: the top-level `import type { schema }` makes the `declare module`
+ * block MERGE (augment) this interface rather than collide with it — the same
+ * shape TanStack Router uses in `src/router.tsx`. Any `.ts` file in the
+ * `tsconfig` `include` works; it never needs to be imported.
  *
  * ```ts
- * // apps/your-app/src/ablo.d.ts
- * import type { schema } from './your-schema';
+ * // ablo/register.ts
+ * import type { schema } from './schema';
  *
  * declare module '@abloatai/ablo' {
  *   interface Register {
  *     Schema: typeof schema;
  *     Presence: { cursor: { x: number; y: number } | null };
- *     Intents: { editLayer: { layerId: string } };
+ *     Claims: { editLayer: { layerId: string } };
  *     UserMeta: { id: string; email: string };
  *   }
  * }

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@
  * Foundational type definitions for the model-driven sync architecture.
  * These types define how properties are tracked, loaded, and synchronized.
  */
+import type { FieldMeta } from '../schema/field.js';
 /**
  * Model Scope - lifecycle filter for queries.
  * Controls whether live, archived, or all entities are returned.
@@ -108,14 +109,15 @@ export interface ModelMetadata {
      * JSON-typed values) inside the transaction queue.
      *
      * Populated by `registerModelsFromSchema`. Each entry carries the
-     * sync-engine type tag (`'string' | 'number' | 'boolean' | 'date' |
-     * 'enum' | 'json'`), which tells the wire serializer how to handle
-     * the value. Missing → projection becomes identity pass-through
-     * (back-compat for models registered outside the schema path).
+     * sync-engine type tag (the canonical {@link FieldMeta.type} union),
+     * which tells the wire serializer how to handle the value. Missing →
+     * projection becomes identity pass-through (back-compat for models
+     * registered outside the schema path).
+     *
+     * Narrowed to the canonical union via `Pick` rather than re-declared —
+     * a hand-rolled copy silently drifts when a new field type lands.
      */
-    fields?: Readonly<Record<string, {
-        type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'json';
-    }>>;
+    fields?: Readonly<Record<string, Pick<FieldMeta, 'type'>>>;
     /**
      * Fields to back-fill from the sync client identity when missing
      * during IndexedDB self-healing. Populated from

package/dist/types/index.js

@@ -65,6 +65,6 @@ export var MutationOperationType;
 })(MutationOperationType || (MutationOperationType = {}));
 // Re-export stream + snapshot + principal types for the engine surface
 // (PresenceStream,
-// IntentStream, Snapshot, etc.) consumed by `Ablo({...}).presence`,
-// `.intents`, `.snapshot()`.
+// ClaimStream, Snapshot, etc.) consumed by `Ablo({...}).presence`,
+// `.claims`, `.snapshot()`.
 export * from "./streams.js";