@abloatai/ablo 0.29.3 → 0.30.0

package/dist/transactions/commitEnvelope.d.ts

@@ -33,6 +33,7 @@ export declare const durableCommitOperationSchema: z.ZodObject<{
         overwrite: "overwrite";
         notify: "notify";
     }>>>;
+    fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     model: z.ZodString;
     id: z.ZodString;
     input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -78,6 +79,7 @@ export declare const durableCommitEnvelopeSchema: z.ZodObject<{
             overwrite: "overwrite";
             notify: "notify";
         }>>>;
+        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         model: z.ZodString;
         id: z.ZodString;
         input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -117,6 +119,8 @@ export declare const durableCommitEnvelopeSchema: z.ZodObject<{
     }, z.core.$strict>>;
     createdAt: z.ZodNumber;
     sealedAt: z.ZodNumber;
+    acceptedAt: z.ZodOptional<z.ZodNumber>;
+    correlationId: z.ZodOptional<z.ZodString>;
     sequence: z.ZodOptional<z.ZodNumber>;
     timestamp: z.ZodNumber;
 }, z.core.$strict>;

package/dist/transactions/commitEnvelope.js

@@ -9,6 +9,7 @@
 import { z } from 'zod';
 import { readDependencySchema } from '../coordination/schema.js';
 import { commitOperationSchema } from '../wire/frames.js';
+import { correlationIdSchema } from '../wire/commit.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
 export const COMMIT_ENVELOPE_VERSION = 1;
 export const COMMIT_ENVELOPE_RECORD_PREFIX = 'commit-envelope:';
@@ -32,6 +33,7 @@ export const durableCommitOperationSchema = commitOperationSchema
     transactionId: true,
     readAt: true,
     onStale: true,
+    fenceToken: true,
 })
     .extend({
     model: z.string().min(1),
@@ -74,6 +76,14 @@ export const durableCommitEnvelopeSchema = z
     scope: commitOutboxScopeSchema.optional(),
     createdAt: z.number().int().nonnegative(),
     sealedAt: z.number().int().nonnegative(),
+    /**
+     * Monotonic evidence that a connected source accepted this exact request.
+     * Its server and customer idempotency keys are permanent, so an accepted
+     * envelope remains replayable until the WAL echo confirms it.
+     */
+    acceptedAt: z.number().int().nonnegative().optional(),
+    /** Opaque server-derived source-batch identity paired with `acceptedAt`. */
+    correlationId: correlationIdSchema.optional(),
     /** Monotonic within one client; disambiguates writes sealed in the same ms. */
     sequence: z.number().int().nonnegative().optional(),
     timestamp: z.number().int().nonnegative(),
@@ -93,6 +103,21 @@ export const durableCommitEnvelopeSchema = z
             message: 'Source mutation ids must be unique',
         });
     }
+    if ((envelope.acceptedAt === undefined) !== (envelope.correlationId === undefined)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['acceptedAt'],
+            message: 'Accepted commit envelopes require both acceptedAt and correlationId',
+        });
+    }
+    if (envelope.acceptedAt !== undefined &&
+        envelope.acceptedAt < envelope.sealedAt) {
+        context.addIssue({
+            code: 'custom',
+            path: ['acceptedAt'],
+            message: 'Commit envelope cannot be accepted before it is sealed',
+        });
+    }
     if (envelope.origin === 'model_batch') {
         const transactionIds = envelope.operations.map((operation) => operation.transactionId);
         if (transactionIds.some((id) => typeof id !== 'string' || id.length === 0)) {

package/dist/transactions/commitPayload.d.ts

@@ -72,16 +72,33 @@ export interface Transaction {
     localOnly?: boolean;
     /** Sync-id threshold: the transaction confirms once a delta with an id at least this value arrives. */
     syncIdNeededForCompletion?: number;
+    /**
+     * Opaque customer-side batch identity returned with a queued source receipt.
+     * It is retained durably and is the only identity a live WAL delta may use
+     * to settle this pending commit. Server-side replay additionally proves the
+     * complete stored operation-id set before returning `confirmed`.
+     */
+    correlationId?: string;
+    /**
+     * A queued forward has no authoritative sync-id watermark yet. It may only
+     * confirm when a WAL delta carries its opaque server-derived correlation;
+     * unrelated deltas must never satisfy it by advancing the global watermark.
+     */
+    requiresCorrelatedDelta?: boolean;
     /**
      * Resolves once the server has confirmed this transaction, whether by a delta
-     * or an HTTP acknowledgement, and rejects with the originating error if the
-     * transaction is permanently rolled back. It gives a caller one place to await
-     * the answer to "did my write land?", matching the
+     * or an HTTP acknowledgement. It rejects with the originating error if the
+     * transaction is permanently rolled back; for a source-forwarded write it
+     * also rejects with `replication_lag_timeout` when the accepted write's WAL
+     * echo misses the confirmation deadline. That timeout does not roll back or
+     * fail the transaction: it remains pending and may confirm when replication
+     * recovers. This gives a caller one place to await the answer to "did my write
+     * land?", matching the
      * `commits.create({ wait: 'confirmed' })` and
      * {@link TransactionQueue.waitForConfirmation} vocabulary, so a failure
      * surfaces at the call site instead of only as a silent local rollback. The
-     * rejection value is the same {@link AbloError} carried on the queue's
-     * `transaction:failed` event.
+     * permanent-rejection value is the same {@link AbloError} carried on the
+     * queue's `transaction:failed` event.
      */
     confirmation?: Promise<void>;
 }
@@ -108,6 +125,7 @@ export declare function hasCommitCoalescingBarrier(options?: WriteOptions): bool
 export interface WriteOperationFields {
     readAt?: number | null;
     onStale?: 'reject' | 'overwrite' | 'notify' | null;
+    fenceToken?: number | null;
     options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
 }
 /**

package/dist/transactions/commitPayload.js

@@ -131,6 +131,9 @@ export function applyWriteOptions(op, transaction) {
     if (writeOptions.onStale !== undefined) {
         operation.onStale = writeOptions.onStale;
     }
+    if (writeOptions.fenceToken !== undefined) {
+        operation.fenceToken = writeOptions.fenceToken;
+    }
     if (writeOptions.idempotencyKey != null || writeOptions.label !== undefined) {
         operation.options = {
             ...(writeOptions.idempotencyKey != null

package/dist/transactions/deltaConfirmation.d.ts

@@ -40,13 +40,14 @@ export declare class DeltaConfirmationTracker {
     constructor(ctx: DeltaConfirmationContext);
     /** Applied-cursor alias, kept so the read sites below stay legible. */
     private get lastSeenSyncId();
+    private matchesSourceEcho;
     noteAck(lastSyncId: number | undefined): void;
     /**
      * Confirms every awaiting transaction whose sync-id threshold this delta
      * meets or exceeds.
      * @param syncId - The sync id of the received delta.
      */
-    onDeltaReceived(syncId: number): void;
+    onDeltaReceived(syncId: number, correlationId?: string): void;
     scheduleDeltaConfirmationTimeout(tx: Transaction, timeoutMs: number): void;
     private cancelDeltaConfirmationTimeout;
     /**

package/dist/transactions/deltaConfirmation.js

@@ -27,6 +27,11 @@ export class DeltaConfirmationTracker {
     get lastSeenSyncId() {
         return this.ctx.position.applied;
     }
+    matchesSourceEcho(tx, correlationId) {
+        return (correlationId !== undefined &&
+            tx.correlationId !== undefined &&
+            correlationId === tx.correlationId);
+    }
     noteAck(lastSyncId) {
         this.ctx.position.noteAck(lastSyncId);
     }
@@ -35,7 +40,7 @@ export class DeltaConfirmationTracker {
      * meets or exceeds.
      * @param syncId - The sync id of the received delta.
      */
-    onDeltaReceived(syncId) {
+    onDeltaReceived(syncId, correlationId) {
         // The cursor advances where the delta is applied (the store calls
         // position.advanceApplied / advancePersisted); this hook only resolves
         // confirmation thresholds against the incoming id.
@@ -52,7 +57,11 @@ export class DeltaConfirmationTracker {
                     txId: tx.id.slice(0, 8),
                     model: tx.modelName,
                     needed: tx.syncIdNeededForCompletion,
-                    willConfirm: tx.syncIdNeededForCompletion !== undefined && syncId >= tx.syncIdNeededForCompletion,
+                    requiresCorrelatedDelta: tx.requiresCorrelatedDelta === true,
+                    willConfirm: tx.requiresCorrelatedDelta === true
+                        ? this.matchesSourceEcho(tx, correlationId)
+                        : tx.syncIdNeededForCompletion !== undefined &&
+                            syncId >= tx.syncIdNeededForCompletion,
                 })),
             });
         }
@@ -61,8 +70,16 @@ export class DeltaConfirmationTracker {
             return;
         let confirmedCount = 0;
         for (const tx of awaitingTxs) {
-            // Confirm if this delta's ID meets or exceeds the threshold
-            if (tx.syncIdNeededForCompletion !== undefined && syncId >= tx.syncIdNeededForCompletion) {
+            // Queued forward receipts deliberately have no watermark. They confirm
+            // only when the authoritative source echoes the receipt's opaque,
+            // authenticated-scope batch identity; the legacy anomaly path continues
+            // to use its sync-id threshold.
+            const confirmedByCorrelation = tx.requiresCorrelatedDelta === true &&
+                this.matchesSourceEcho(tx, correlationId);
+            const confirmedByThreshold = tx.requiresCorrelatedDelta !== true &&
+                tx.syncIdNeededForCompletion !== undefined &&
+                syncId >= tx.syncIdNeededForCompletion;
+            if (confirmedByCorrelation || confirmedByThreshold) {
                 this.cancelDeltaConfirmationTimeout(tx.id);
                 this.ctx.store.updateStatus(tx.id, 'completed');
                 this.ctx.emit('transaction:completed', tx);
@@ -74,6 +91,7 @@ export class DeltaConfirmationTracker {
                     model: tx.modelName,
                     neededSyncId: tx.syncIdNeededForCompletion,
                     receivedSyncId: syncId,
+                    confirmation: confirmedByCorrelation ? 'source_correlation' : 'sync_id',
                 });
             }
         }

package/dist/transactions/durableWriteStore.d.ts

@@ -30,6 +30,7 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
             overwrite: "overwrite";
             notify: "notify";
         }>>>;
+        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         model: z.ZodString;
         id: z.ZodString;
         input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -69,6 +70,8 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strict>>;
     createdAt: z.ZodNumber;
     sealedAt: z.ZodNumber;
+    acceptedAt: z.ZodOptional<z.ZodNumber>;
+    correlationId: z.ZodOptional<z.ZodString>;
     sequence: z.ZodOptional<z.ZodNumber>;
     timestamp: z.ZodNumber;
 }, z.core.$strict>, z.ZodObject<{
@@ -89,6 +92,8 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
     scopeNamespace: z.ZodString;
     createdAt: z.ZodNumber;
     sealedAt: z.ZodNumber;
+    acceptedAt: z.ZodOptional<z.ZodNumber>;
+    correlationId: z.ZodOptional<z.ZodString>;
     sequence: z.ZodOptional<z.ZodNumber>;
     timestamp: z.ZodNumber;
 }, z.core.$strict>]>;
@@ -105,7 +110,9 @@ export interface DurableWriteStore {
     /**
      * Atomically reserve a pending write and consume the staged records it owns.
      * The same id + same request is idempotent; the same id + a different request
-     * must be rejected.
+     * must be rejected. For a source-accepted envelope, a re-seal may add the
+     * monotonic `acceptedAt`/`correlationId` evidence and the store must preserve
+     * that upgrade atomically rather than ignoring it.
      */
     seal(write: PendingWrite, consumedRecordIds: readonly string[]): Promise<void>;
     /** Load all unacknowledged writes. Stored data is treated as untrusted. */

package/dist/transactions/httpCommitEnvelope.d.ts

@@ -24,6 +24,8 @@ export declare const durableHttpCommitEnvelopeSchema: z.ZodObject<{
     scopeNamespace: z.ZodString;
     createdAt: z.ZodNumber;
     sealedAt: z.ZodNumber;
+    acceptedAt: z.ZodOptional<z.ZodNumber>;
+    correlationId: z.ZodOptional<z.ZodString>;
     sequence: z.ZodOptional<z.ZodNumber>;
     timestamp: z.ZodNumber;
 }, z.core.$strict>;
@@ -41,4 +43,4 @@ export declare function createDurableHttpCommitEnvelope(input: {
     sealedAt?: number;
     sequence?: number;
 }): DurableHttpCommitEnvelope;
-export declare function isHttpCommitReplayExpired(envelope: Pick<DurableHttpCommitEnvelope, 'sealedAt'>, now?: number): boolean;
+export declare function isHttpCommitReplayExpired(envelope: Pick<DurableHttpCommitEnvelope, 'sealedAt' | 'acceptedAt'>, now?: number): boolean;

package/dist/transactions/httpCommitEnvelope.js

@@ -2,6 +2,7 @@
 import { z } from 'zod';
 import { v5 as uuidv5 } from 'uuid';
 import { stableStringify } from '../utils/json.js';
+import { correlationIdSchema } from '../wire/commit.js';
 import { PROTOCOL_VERSION } from '../wire/protocolVersion.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
 export const HTTP_COMMIT_ENVELOPE_VERSION = 1;
@@ -67,6 +68,15 @@ export const durableHttpCommitEnvelopeSchema = z
     scopeNamespace: z.string().min(1),
     createdAt: z.number().int().nonnegative(),
     sealedAt: z.number().int().nonnegative(),
+    /**
+     * Monotonic evidence that the server accepted this exact request for a
+     * connected source. Such server keys are permanent, so this envelope must
+     * remain replayable past the ordinary hosted 24-hour window until its WAL
+     * echo confirms.
+     */
+    acceptedAt: z.number().int().nonnegative().optional(),
+    /** Opaque server-derived source-batch identity paired with `acceptedAt`. */
+    correlationId: correlationIdSchema.optional(),
     /** Monotonic within one client; disambiguates writes sealed in the same ms. */
     sequence: z.number().int().nonnegative().optional(),
     timestamp: z.number().int().nonnegative(),
@@ -88,6 +98,21 @@ export const durableHttpCommitEnvelopeSchema = z
             message: 'HTTP envelope cannot be sealed before it is created',
         });
     }
+    if ((envelope.acceptedAt === undefined) !== (envelope.correlationId === undefined)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['acceptedAt'],
+            message: 'Accepted HTTP envelopes require both acceptedAt and correlationId',
+        });
+    }
+    if (envelope.acceptedAt !== undefined &&
+        envelope.acceptedAt < envelope.sealedAt) {
+        context.addIssue({
+            code: 'custom',
+            path: ['acceptedAt'],
+            message: 'HTTP envelope cannot be accepted before it is sealed',
+        });
+    }
     const { method, path } = envelope.request;
     const allowedPath = method === 'POST'
         ? commitPathSchema.safeParse(path).success ||
@@ -177,5 +202,10 @@ export function createDurableHttpCommitEnvelope(input) {
     });
 }
 export function isHttpCommitReplayExpired(envelope, now = Date.now()) {
+    // Connected-source mutation-log and customer idempotency keys are
+    // permanent. Once acceptance is durable, age can no longer make replay
+    // ambiguous; only the matching WAL echo may settle the envelope.
+    if (envelope.acceptedAt !== undefined)
+        return false;
     return now - envelope.sealedAt >= HTTP_COMMIT_REPLAY_WINDOW_MS;
 }

package/dist/transactions/replayValidation.d.ts

@@ -62,6 +62,7 @@ export declare const persistedTransactionSchema: z.ZodObject<{
         }>>>;
         idempotencyKey: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
+        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$loose>>;
     localOnly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>;
@@ -104,6 +105,7 @@ export declare const persistedMutationSchema: z.ZodObject<{
         }>>>;
         idempotencyKey: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
+        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
 export type PersistedQueuedMutation = z.infer<typeof persistedMutationSchema>;
@@ -139,6 +141,7 @@ export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
             }>>>;
             idempotencyKey: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$loose>>;
         mutationId: z.ZodString;
     }, z.core.$loose>;
@@ -173,6 +176,7 @@ export declare const pendingMutationRecordSchema: z.ZodObject<{
             }>>>;
             idempotencyKey: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$loose>>;
         mutationId: z.ZodString;
     }, z.core.$loose>;

package/dist/transactions/replayValidation.js

@@ -24,6 +24,12 @@ const persistedWriteOptionsSchema = z
     onStale: z.enum(['reject', 'overwrite', 'notify']).nullable().optional(),
     idempotencyKey: z.string().optional(),
     label: z.string().optional(),
+    // Aligned with the `WriteOptions` type: a claimed write persisted offline
+    // must replay carrying its fencing token (Option B), or a queued write that
+    // survives a reload would lose its fence and could land as a stale blind
+    // write. Declared (not just loose-passthrough) so it is validated as a
+    // number on rehydration.
+    fenceToken: z.number().nullable().optional(),
 })
     .loose();
 /**

package/dist/types/streams.d.ts

@@ -289,16 +289,11 @@ export interface ClaimLeaseOptions {
 export type Duration = import('../utils/duration.js').Duration;
 export interface ClaimOptions extends ClaimLeaseOptions {
     /**
-     * Free-form reason describing why you're claiming. Surfaces in conflict
-     * messages and the activity overlay. Defaults to `'editing'`. Common
-     * values: `'editing'`, `'writing'`, `'reviewing'`, custom strings for
-     * app-specific phases.
-     */
-    readonly reason?: string;
-    /**
-     * Peer-visible explanation of the exact work being performed. This is more
-     * specific than `reason`: `reason` is the phase (`'renaming'`), while
-     * `description` is the instruction other agents should see.
+     * Peer-visible description of the work you're doing — the sentence another
+     * participant reads to decide whether to wait, work elsewhere, or move on
+     * (`'rewriting the risk section to match Q3'`). Surfaces in conflict
+     * messages and the activity overlay, and rides back in the rejection a
+     * blocked writer receives. Defaults to `'editing'`.
      */
     readonly description?: string;
     /**
@@ -318,7 +313,7 @@ export interface ClaimStream {
     readonly others: readonly Claim[];
     /**
      * A reactive view of the wait queue on one target — the ordered line of
-     * queued claims behind the current holder, each carrying its `reason`,
+     * queued claims behind the current holder, each carrying its `description`,
      * `heldBy`, and `position`. Empty when no one is waiting. Pair it with
      * `onChange(...)` for change notifications.
      */
@@ -410,13 +405,11 @@ export interface Claim<T = Record<string, unknown>> {
     /** What is being coordinated. */
     readonly target: ClaimTarget;
     /**
-     * Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
-     * field on every claim surface; distinct from the CRUD operation. Defaults to
-     * `'editing'`.
+     * 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,
+     * defaulting to `'editing'` when a claim carries no description.
      */
-    readonly reason: string;
-    /** Peer-visible explanation of the work being performed. */
-    readonly description?: string;
+    readonly description: string;
     /** Participant holding it. Absent on a handle you hold for yourself. */
     readonly heldBy?: string;
     /**
@@ -451,6 +444,15 @@ export interface Claim<T = Record<string, unknown>> {
      * uses it as the `readAt` staleness guard. Present on a claim you hold.
      */
     readonly readAt?: number;
+    /**
+     * The monotonic fencing token the server minted for this grant (Option B). A
+     * write made under this claim carries it, and the server rejects the write if
+     * a later holder already advanced this entity past the token — closing the
+     * "my claim lapsed and its successor came and went" lost-update window that
+     * `readAt` alone cannot (a blind write with no read basis has nothing to
+     * compare). Present on a claim you hold that was granted a token.
+     */
+    readonly fenceToken?: number;
     /** Row snapshot under the lease — present on a claim you hold. */
     readonly data?: T;
     /**
@@ -508,3 +510,13 @@ export interface ClaimHeartbeat {
  * `AsyncDisposable`.
  */
 export type HeldClaim<T = Record<string, unknown>> = Claim<T> & Required<Pick<Claim<T>, '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
+ * {@link HeldClaim} minus `.data`: the same lease controls (`release`, `revoke`,
+ * `heartbeat`, and the `await using` disposer are all required and behave
+ * identically), only without a snapshot, because the row lives solely in the
+ * customer's own database and was never replicated into the local pool. Use it
+ * to serialize work against a key you know by id alone.
+ */
+export type HeldLease = Omit<HeldClaim, 'data'>;