@abloatai/ablo 0.26.0 → 0.28.0

package/dist/transactions/deltaConfirmation.js

@@ -1,25 +1,22 @@
 /**
- * Delta-confirmation tracking — the queue's "did my write's echo arrive?"
- * machinery, lifted out of `TransactionQueue.ts` as a stateful leaf.
- *
- * Owns the ack watermark (via the shared `SyncPosition`), the per-transaction
- * confirmation timeout map, and the retry-with-backoff/reconciliation policy
- * for `awaiting_delta` transactions. Talks back to the queue through the
- * minimal `DeltaConfirmationContext` interface (never the host class type),
- * so the leaf stays cycle-free and testable in isolation.
+ * Tracks whether the confirming delta for a write has arrived. It holds the
+ * acknowledgement watermark (through the shared {@link SyncPosition}), the
+ * per-transaction confirmation timeouts, and the retry-with-backoff and
+ * reconciliation policy for transactions in the `awaiting_delta` status. It
+ * reaches back to {@link TransactionQueue} only through the small
+ * {@link DeltaConfirmationContext} interface, not the queue class itself, so it
+ * has no cyclic dependency and can be tested on its own.
  */
 import { getContext } from '../context.js';
 export class DeltaConfirmationTracker {
     ctx;
-    // Delta confirmation retry config (Replicache-style exponential backoff)
-    // Max retries before requesting full reconciliation
+    // Retry configuration for delta confirmation, using exponential backoff.
+    // Maximum retries before requesting a full reconciliation.
     static DELTA_MAX_RETRIES = 5;
-    // Initial timeout (first attempt)
-    static DELTA_INITIAL_TIMEOUT_MS = 30_000;
-    // Max timeout cap (like Replicache's maxDelayMs of 60s)
+    // Upper bound on the backoff timeout.
     static DELTA_MAX_TIMEOUT_MS = 120_000;
-    // LINEAR PATTERN: Track delta confirmation timeouts for awaiting_delta transactions
-    // Following Replicache/PowerSync pattern: retry with backoff instead of rolling back
+    // Pending confirmation timeouts for transactions awaiting their delta. On
+    // timeout the tracker retries with backoff rather than rolling back.
     deltaConfirmationTimeouts = new Map();
     // Track retry attempts per transaction for exponential backoff
     deltaConfirmationRetries = new Map();
@@ -34,12 +31,12 @@ export class DeltaConfirmationTracker {
         this.ctx.position.noteAck(lastSyncId);
     }
     /**
-     * LINEAR PATTERN: Confirm all awaiting transactions when delta with syncId >= threshold arrives.
-     * This replaces clientMutationId echoing - transactions are confirmed by sync ID threshold.
-     * @param syncId - The sync ID of the received delta
+     * Confirms every awaiting transaction whose sync-id threshold this delta
+     * meets or exceeds.
+     * @param syncId - The sync id of the received delta.
      */
     onDeltaReceived(syncId) {
-        // Cursor advancing happens where the delta is APPLIED (the store calls
+        // The cursor advances where the delta is applied (the store calls
         // position.advanceApplied / advancePersisted); this hook only resolves
         // confirmation thresholds against the incoming id.
         const awaitingTxs = this.ctx.store.getByStatus('awaiting_delta');
@@ -82,7 +79,7 @@ export class DeltaConfirmationTracker {
         }
         // Log batch summary only if we confirmed something
         if (confirmedCount > 0) {
-            // Use warn for staging visibility when transactions confirm
+            // Leave a breadcrumb when transactions confirm.
             getContext().observability.breadcrumb('Transactions confirmed via delta', 'sync.transaction', 'info', {
                 count: confirmedCount,
                 syncId,
@@ -90,15 +87,16 @@ export class DeltaConfirmationTracker {
             });
         }
     }
-    // REPLICACHE/POWERSYNC PATTERN: Schedule delta confirmation with retry + reconciliation
-    // Instead of rolling back on timeout (which destroys confirmed server state),
-    // retry with exponential backoff and request reconciliation to catch up on missed deltas.
-    // Only rollback on explicit server rejection, never on timeout.
+    // Schedule the confirmation wait for a transaction. On timeout the tracker
+    // retries with exponential backoff and requests reconciliation to catch up on
+    // missed deltas, rather than rolling back, which would discard state the
+    // server has already confirmed. A rollback happens only on an explicit server
+    // rejection, never on a timeout.
     scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
         // Cancel any existing timeout for this transaction
         this.cancelDeltaConfirmationTimeout(tx.id);
-        // NB: deliberately NOT an async callback — the body is fully synchronous,
-        // and `setTimeout(async …)` turns any throw into an unhandled promise
+        // Deliberately not an async callback: the body is fully synchronous, and
+        // `setTimeout(async …)` would turn any throw into an unhandled promise
         // rejection instead of a catchable synchronous error.
         const timeoutHandle = setTimeout(() => {
             const currentTx = this.ctx.store.get(tx.id);
@@ -119,12 +117,6 @@ export class DeltaConfirmationTracker {
                 return;
             }
             const retryCount = this.deltaConfirmationRetries.get(tx.id) ?? 0;
-            const diagnosis = this.lastSeenSyncId === 0
-                ? 'No deltas received - delta pipeline may be broken'
-                : currentTx.syncIdNeededForCompletion &&
-                    this.lastSeenSyncId < currentTx.syncIdNeededForCompletion
-                    ? 'Delta not yet received - may be lost or delayed'
-                    : 'Delta should have confirmed - possible race condition';
             getContext().observability.captureReconciliation({
                 reason: 'delta_timeout',
                 model: tx.modelName,
@@ -135,14 +127,15 @@ export class DeltaConfirmationTracker {
                 connectionState: this.ctx.isConnected() ? 'connected' : 'disconnected',
             });
             if (retryCount < DeltaConfirmationTracker.DELTA_MAX_RETRIES) {
-                // RETRY: Request reconciliation and re-schedule with exponential backoff
-                // The server already committed this mutation — we just need the delta to arrive
+                // Retry: request reconciliation and re-schedule with exponential
+                // backoff. The server has already committed the mutation; only the
+                // delta is outstanding.
                 this.deltaConfirmationRetries.set(tx.id, retryCount + 1);
                 this.deltaConfirmationTimeouts.delete(tx.id);
                 // Exponential backoff: 30s → 60s → 120s → 120s → 120s (capped)
                 const nextTimeout = Math.min(timeoutMs * 2, DeltaConfirmationTracker.DELTA_MAX_TIMEOUT_MS);
-                // Emit reconciliation request so SyncedStore can cycle the WebSocket
-                // to trigger delta catch-up from the server
+                // Request reconciliation so the client can cycle the connection and
+                // catch up on missed deltas from the server.
                 this.ctx.emit('reconciliation:needed', {
                     reason: 'delta_confirmation_timeout',
                     txId: tx.id,
@@ -163,10 +156,10 @@ export class DeltaConfirmationTracker {
                 this.scheduleDeltaConfirmationTimeout(tx, nextTimeout);
             }
             else {
-                // LINEAR PATTERN: Retries exhausted — persist to IndexedDB instead of rolling back.
-                // The transaction succeeded on the server (HTTP 200), so the data exists server-side.
-                // Persist the awaiting state so it survives tab close. On next session, the WebSocket
-                // reconnect + delta catch-up will naturally confirm it (like Linear's IndexedDB caching).
+                // Retries exhausted: persist the awaiting state instead of rolling back.
+                // The commit succeeded on the server, so the data exists there. Saving
+                // the awaiting state lets it survive the page closing; on the next
+                // session, reconnecting and catching up on deltas will confirm it.
                 this.deltaConfirmationRetries.delete(tx.id);
                 this.deltaConfirmationTimeouts.delete(tx.id);
                 getContext().observability.captureDeltaRetryExhausted({
@@ -176,7 +169,7 @@ export class DeltaConfirmationTracker {
                     retryCount: DeltaConfirmationTracker.DELTA_MAX_RETRIES,
                     syncIdNeeded: currentTx.syncIdNeededForCompletion,
                 });
-                // Emit persist event — SyncClient handles the IDB write
+                // Emit the persist event; the client performs the write to local storage.
                 this.ctx.emit('transaction:persist_awaiting', {
                     txId: tx.id,
                     model: tx.modelName,
@@ -208,10 +201,9 @@ export class DeltaConfirmationTracker {
         this.deltaConfirmationRetries.delete(id);
     }
     /**
-     * Tear down every armed confirmation timer (30–120s each, one per
-     * in-flight transaction). Called from `TransactionQueue.dispose()` —
-     * without it a disposed queue kept the Node process alive and fired
-     * callbacks against an already-cleared store (T1.19).
+     * Clears every armed confirmation timer, one per in-flight transaction.
+     * {@link TransactionQueue.dispose} calls this; without it a disposed queue
+     * would keep the process alive and fire callbacks against a cleared store.
      */
     dispose() {
         for (const timeoutHandle of this.deltaConfirmationTimeouts.values()) {

package/dist/transactions/httpCommitEnvelope.d.ts

@@ -0,0 +1,43 @@
+/** Crash-durable exact HTTP request used by the stateless agent client. */
+import { z } from 'zod';
+export declare const HTTP_COMMIT_ENVELOPE_VERSION: 1;
+export declare const HTTP_COMMIT_ENVELOPE_PREFIX = "http-commit-envelope:";
+/** Stay one hour inside the server's 24-hour idempotency retention window. */
+export declare const HTTP_COMMIT_REPLAY_WINDOW_MS: number;
+/** Apply normal JSON semantics once, then make object-key order canonical. */
+export declare function canonicalHttpCommitBody(value: unknown): string;
+export declare const durableHttpCommitEnvelopeSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"http_commit_envelope">;
+    storageVersion: z.ZodLiteral<1>;
+    idempotencyKey: z.core.$ZodBranded<z.ZodString, "IdempotencyKey", "out">;
+    request: z.ZodObject<{
+        method: z.ZodEnum<{
+            DELETE: "DELETE";
+            POST: "POST";
+            PATCH: "PATCH";
+        }>;
+        path: z.ZodString;
+        body: z.ZodString;
+    }, z.core.$strict>;
+    scopeNamespace: z.ZodString;
+    createdAt: z.ZodNumber;
+    sealedAt: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodNumber;
+}, z.core.$strict>;
+export type DurableHttpCommitEnvelope = z.infer<typeof durableHttpCommitEnvelopeSchema>;
+export declare function httpCommitEnvelopeRecordId(idempotencyKey: string, scopeNamespace?: string): string;
+export declare function createDurableHttpCommitEnvelope(input: {
+    idempotencyKey: string;
+    request: {
+        method: 'POST' | 'PATCH' | 'DELETE';
+        path: string;
+        body: unknown;
+    };
+    scopeNamespace: string;
+    createdAt?: number;
+    sealedAt?: number;
+    sequence?: number;
+}): DurableHttpCommitEnvelope;
+export declare function isHttpCommitReplayExpired(envelope: Pick<DurableHttpCommitEnvelope, 'sealedAt'>, now?: number): boolean;

package/dist/transactions/httpCommitEnvelope.js

@@ -0,0 +1,179 @@
+/** Crash-durable exact HTTP request used by the stateless agent client. */
+import { z } from 'zod';
+import { v5 as uuidv5 } from 'uuid';
+import { idempotencyKeySchema } from '../commit/contract.js';
+import { stableStringify } from '../utils/json.js';
+export const HTTP_COMMIT_ENVELOPE_VERSION = 1;
+export const HTTP_COMMIT_ENVELOPE_PREFIX = 'http-commit-envelope:';
+/** Stay one hour inside the server's 24-hour idempotency retention window. */
+export const HTTP_COMMIT_REPLAY_WINDOW_MS = 23 * 60 * 60 * 1000;
+const HTTP_COMMIT_SCOPE_ID_NAMESPACE = '043e8f73-86fc-5f62-af46-935d68fca729';
+const commitPathSchema = z.literal('/v1/commits');
+const modelCollectionPathSchema = z.string().regex(/^\/v1\/models\/[^/]+$/);
+const modelEntityPathSchema = z.string().regex(/^\/v1\/models\/[^/]+\/[^/]+$/);
+function hasSafeModelPathSegments(path) {
+    if (!path.startsWith('/v1/models/'))
+        return true;
+    try {
+        return path
+            .slice('/v1/models/'.length)
+            .split('/')
+            .every((segment) => {
+            const decoded = decodeURIComponent(segment);
+            return (decoded.length > 0 &&
+                decoded !== '.' &&
+                decoded !== '..' &&
+                !decoded.includes('/') &&
+                !decoded.includes('\\'));
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/** Apply normal JSON semantics once, then make object-key order canonical. */
+export function canonicalHttpCommitBody(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+        throw new TypeError('HTTP commit body is not JSON serializable');
+    }
+    return stableStringify(JSON.parse(serialized));
+}
+export const durableHttpCommitEnvelopeSchema = z
+    .strictObject({
+    id: z.string().startsWith(HTTP_COMMIT_ENVELOPE_PREFIX),
+    type: z.literal('http_commit_envelope'),
+    storageVersion: z.literal(HTTP_COMMIT_ENVELOPE_VERSION),
+    idempotencyKey: idempotencyKeySchema,
+    request: z.strictObject({
+        method: z.enum(['POST', 'PATCH', 'DELETE']),
+        path: z.string().startsWith('/'),
+        body: z.string().refine((body) => {
+            try {
+                JSON.parse(body);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }, 'HTTP commit body must be valid JSON'),
+    }),
+    scopeNamespace: z.string().min(1),
+    createdAt: z.number().int().nonnegative(),
+    sealedAt: z.number().int().nonnegative(),
+    /** Monotonic within one client; disambiguates writes sealed in the same ms. */
+    sequence: z.number().int().nonnegative().optional(),
+    timestamp: z.number().int().nonnegative(),
+})
+    .superRefine((envelope, context) => {
+    const legacyId = httpCommitEnvelopeRecordId(envelope.idempotencyKey);
+    const scopedId = httpCommitEnvelopeRecordId(envelope.idempotencyKey, envelope.scopeNamespace);
+    if (envelope.id !== legacyId && envelope.id !== scopedId) {
+        context.addIssue({
+            code: 'custom',
+            path: ['id'],
+            message: 'HTTP envelope id must be derived from its idempotency key',
+        });
+    }
+    if (envelope.sealedAt < envelope.createdAt) {
+        context.addIssue({
+            code: 'custom',
+            path: ['sealedAt'],
+            message: 'HTTP envelope cannot be sealed before it is created',
+        });
+    }
+    const { method, path } = envelope.request;
+    const allowedPath = method === 'POST'
+        ? commitPathSchema.safeParse(path).success ||
+            modelCollectionPathSchema.safeParse(path).success
+        : modelEntityPathSchema.safeParse(path).success;
+    if (!allowedPath || !hasSafeModelPathSegments(path)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'path'],
+            message: 'HTTP outbox records may target only commit or model-mutation routes',
+        });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(envelope.request.body);
+    }
+    catch {
+        return; // The field-level JSON refinement reports this.
+    }
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'body'],
+            message: 'HTTP commit body must be a JSON object',
+        });
+        return;
+    }
+    const record = body;
+    if (record.idempotencyKey !== envelope.idempotencyKey) {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'body', 'idempotencyKey'],
+            message: 'HTTP body idempotency key must match its envelope',
+        });
+    }
+    if (path === '/v1/commits') {
+        if (record.clientTxId !== envelope.idempotencyKey ||
+            !Array.isArray(record.operations) ||
+            record.operations.length === 0) {
+            context.addIssue({
+                code: 'custom',
+                path: ['request', 'body'],
+                message: 'Commit-route body must carry the same clientTxId and operations',
+            });
+        }
+    }
+    else if (method === 'POST' && typeof record.id !== 'string') {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'body', 'id'],
+            message: 'Model-create body must carry its entity id',
+        });
+    }
+    else if (method === 'PATCH' &&
+        (typeof record.data !== 'object' || record.data === null || Array.isArray(record.data))) {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'body', 'data'],
+            message: 'Model-update body must carry a JSON object patch',
+        });
+    }
+});
+export function httpCommitEnvelopeRecordId(idempotencyKey, scopeNamespace) {
+    if (!scopeNamespace) {
+        return `${HTTP_COMMIT_ENVELOPE_PREFIX}${idempotencyKey}`;
+    }
+    const scopeId = uuidv5(scopeNamespace, HTTP_COMMIT_SCOPE_ID_NAMESPACE);
+    return `${HTTP_COMMIT_ENVELOPE_PREFIX}${scopeId}:${idempotencyKey}`;
+}
+export function createDurableHttpCommitEnvelope(input) {
+    const now = Date.now();
+    const createdAt = input.createdAt ?? now;
+    const sealedAt = input.sealedAt ?? now;
+    const body = canonicalHttpCommitBody(input.request.body);
+    return durableHttpCommitEnvelopeSchema.parse({
+        id: httpCommitEnvelopeRecordId(input.idempotencyKey, input.scopeNamespace),
+        type: 'http_commit_envelope',
+        storageVersion: HTTP_COMMIT_ENVELOPE_VERSION,
+        idempotencyKey: input.idempotencyKey,
+        request: {
+            method: input.request.method,
+            path: input.request.path,
+            body,
+        },
+        scopeNamespace: input.scopeNamespace,
+        createdAt,
+        sealedAt,
+        ...(input.sequence !== undefined ? { sequence: input.sequence } : {}),
+        timestamp: sealedAt,
+    });
+}
+export function isHttpCommitReplayExpired(envelope, now = Date.now()) {
+    return now - envelope.sealedAt >= HTTP_COMMIT_REPLAY_WINDOW_MS;
+}

package/dist/transactions/optimisticApply.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Local-first apply and rollback bookkeeping for pending mutations.
+ *
+ * When a change is written before the server confirms it, these functions
+ * record it in a ledger and emit an `optimistic:*` event; separate listeners
+ * apply the change to the in-memory data and, on rollback, restore the value
+ * it replaced. Each function takes the ledger and a small event emitter rather
+ * than any larger object, so the rules have no dependencies of their own and
+ * can be tested in isolation.
+ */
+import type { Model } from '../Model.js';
+import type { MutationInput, Transaction } from './commitPayload.js';
+/**
+ * One tracked optimistic mutation: the live model plus the value it held
+ * before the change, kept so a rollback can restore it.
+ */
+export interface OptimisticUpdateEntry {
+    model: Model;
+    previousState: MutationInput | null | undefined;
+    transaction: Transaction;
+}
+/**
+ * The event emitter these functions use to announce each optimistic change and
+ * its rollback. You supply the implementation.
+ */
+export interface OptimisticEmitter {
+    emit(event: string, payload: unknown): void;
+}
+/**
+ * Record an optimistic create and announce it. There is no prior value to
+ * restore, so the rollback pre-image is `null`.
+ */
+export declare function applyOptimisticCreate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+/**
+ * Record an optimistic update and announce it, keeping the row's prior value so
+ * a rollback can put it back.
+ */
+export declare function applyOptimisticUpdate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+/**
+ * Record an optimistic delete and announce it, keeping the deleted row so a
+ * rollback can restore it.
+ */
+export declare function applyOptimisticDelete(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+/**
+ * Undo an optimistic mutation by its transaction id: emit `optimistic:rollback`
+ * with the saved pre-image so listeners can restore the prior value, then drop
+ * the ledger entry. Does nothing if the transaction was never tracked.
+ */
+export declare function rollbackOptimistic(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, transaction: Transaction, reason?: string, error?: Error): Promise<void>;

package/dist/transactions/optimisticApply.js

@@ -0,0 +1,65 @@
+/**
+ * Local-first apply and rollback bookkeeping for pending mutations.
+ *
+ * When a change is written before the server confirms it, these functions
+ * record it in a ledger and emit an `optimistic:*` event; separate listeners
+ * apply the change to the in-memory data and, on rollback, restore the value
+ * it replaced. Each function takes the ledger and a small event emitter rather
+ * than any larger object, so the rules have no dependencies of their own and
+ * can be tested in isolation.
+ */
+/**
+ * Record an optimistic create and announce it. There is no prior value to
+ * restore, so the rollback pre-image is `null`.
+ */
+export function applyOptimisticCreate(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: null,
+        transaction,
+    });
+    emitter.emit('optimistic:create', { model, transaction });
+}
+/**
+ * Record an optimistic update and announce it, keeping the row's prior value so
+ * a rollback can put it back.
+ */
+export function applyOptimisticUpdate(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: transaction.previousData,
+        transaction,
+    });
+    emitter.emit('optimistic:update', { model, transaction });
+}
+/**
+ * Record an optimistic delete and announce it, keeping the deleted row so a
+ * rollback can restore it.
+ */
+export function applyOptimisticDelete(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: transaction.previousData,
+        transaction,
+    });
+    emitter.emit('optimistic:delete', { model, transaction });
+}
+/**
+ * Undo an optimistic mutation by its transaction id: emit `optimistic:rollback`
+ * with the saved pre-image so listeners can restore the prior value, then drop
+ * the ledger entry. Does nothing if the transaction was never tracked.
+ */
+export function rollbackOptimistic(optimisticUpdates, emitter, transaction, reason, error) {
+    const optimistic = optimisticUpdates.get(transaction.id);
+    if (!optimistic)
+        return Promise.resolve();
+    emitter.emit('optimistic:rollback', {
+        model: optimistic.model,
+        previousState: optimistic.previousState,
+        transaction,
+        reason: reason ?? 'unknown',
+        error,
+    });
+    optimisticUpdates.delete(transaction.id);
+    return Promise.resolve();
+}