kaafil-js 0.7.0 → 0.8.0

package/dist/client-entry.d.cts

@@ -1017,6 +1017,31 @@ interface CreateDrainerOptions {
     /** Fed every observed `meta.serverTime` so the share layer can age a token
      * without a device clock (`06 §8`). */
     readonly onServerTime?: (serverTime: string) => void;
+    /**
+     * Called with the lanes a pass actually APPLIED something on, so the engine
+     * can pull them straight afterwards.
+     *
+     * ── WHY A DRAIN HAS TO BE FOLLOWED BY A PULL ──────────────────────────────
+     *
+     * A write leaves the snapshot alone unless it was enqueued with an
+     * `entity`/`optimistic` pairing, and several deliberately are not: a write
+     * whose response carries server-assigned fields no client can compute
+     * (`floatMovementId`, a resolved `receiptRequired` threshold, whether a
+     * payment cleared a negative-float guard) is better left unguessed than
+     * painted wrong and silently corrected later. Those writes reach the server
+     * correctly and the snapshot simply does not know yet.
+     *
+     * Until now nothing closed that gap: `sync.drained` was emitted and the pass
+     * ended. A host reading a snapshot-backed list saw its own successful write
+     * missing from it — indefinitely, since nothing else schedules a pull — and
+     * the fix was to reopen the screen. Observed in the field: an expense logged
+     * against a trip's float moved the balance and stayed absent from the list
+     * beside it.
+     *
+     * A callback rather than a direct dependency on `./pull.ts`, so this module
+     * keeps knowing nothing about pulling and stays testable without one.
+     */
+    readonly onLanesApplied?: (lanes: readonly string[]) => void;
 }
 declare function createDrainer(options: CreateDrainerOptions): Drainer;
 

package/dist/client-entry.d.ts

@@ -1017,6 +1017,31 @@ interface CreateDrainerOptions {
     /** Fed every observed `meta.serverTime` so the share layer can age a token
      * without a device clock (`06 §8`). */
     readonly onServerTime?: (serverTime: string) => void;
+    /**
+     * Called with the lanes a pass actually APPLIED something on, so the engine
+     * can pull them straight afterwards.
+     *
+     * ── WHY A DRAIN HAS TO BE FOLLOWED BY A PULL ──────────────────────────────
+     *
+     * A write leaves the snapshot alone unless it was enqueued with an
+     * `entity`/`optimistic` pairing, and several deliberately are not: a write
+     * whose response carries server-assigned fields no client can compute
+     * (`floatMovementId`, a resolved `receiptRequired` threshold, whether a
+     * payment cleared a negative-float guard) is better left unguessed than
+     * painted wrong and silently corrected later. Those writes reach the server
+     * correctly and the snapshot simply does not know yet.
+     *
+     * Until now nothing closed that gap: `sync.drained` was emitted and the pass
+     * ended. A host reading a snapshot-backed list saw its own successful write
+     * missing from it — indefinitely, since nothing else schedules a pull — and
+     * the fix was to reopen the screen. Observed in the field: an expense logged
+     * against a trip's float moved the balance and stayed absent from the list
+     * beside it.
+     *
+     * A callback rather than a direct dependency on `./pull.ts`, so this module
+     * keeps knowing nothing about pulling and stays testable without one.
+     */
+    readonly onLanesApplied?: (lanes: readonly string[]) => void;
 }
 declare function createDrainer(options: CreateDrainerOptions): Drainer;
 

package/dist/client-entry.js

@@ -2875,6 +2875,9 @@ function createDrainer(options) {
       remaining: report.remaining,
       usedBatchTransport: report.usedBatchTransport
     });
+    if (report.applied > 0) {
+      options.onLanesApplied?.(report.lanes);
+    }
     return report;
   }
   let kickTimer;
@@ -3598,22 +3601,45 @@ function createOfflineEngine(options) {
       ...options.share.monotonic !== void 0 ? { monotonic: options.share.monotonic } : {}
     });
   }
+  const pull = createPullCoordinator({
+    snapshot,
+    transport: options.transport,
+    events,
+    onServerTime
+  });
   const drainer = createDrainer({
     outbox,
     snapshot,
     transport: options.transport,
     events,
     onServerTime,
+    /*
+     * A DRAIN IS FOLLOWED BY A PULL, for the lanes it actually changed.
+     *
+     * Not every write rebases the snapshot: one enqueued without an
+     * `entity`/`optimistic` pairing — deliberately, wherever the response
+     * carries server-assigned fields a client cannot compute — reaches the
+     * server and leaves the local snapshot untouched. Nothing used to close
+     * that gap, so a host reading a snapshot-backed list saw its own
+     * successful write missing from it until something reopened the screen.
+     *
+     * Failures are swallowed on purpose. This is a background reconcile behind
+     * a write that has already succeeded; a pull that cannot reach the server
+     * changes nothing the caller needs to hear about, and `pullTrip` has
+     * already emitted whatever the host subscribes to. Rethrowing here would
+     * surface a sync failure as if the WRITE had failed, which is the one
+     * reading of it that is untrue.
+     */
+    onLanesApplied: (lanes) => {
+      for (const tripRef of lanes) {
+        void pull.pullTrip({ tripRef }).catch(() => {
+        });
+      }
+    },
     ...options.conflictResolver !== void 0 ? { conflictResolver: options.conflictResolver } : {},
     ...options.now !== void 0 ? { now: options.now } : {},
     ...options.random !== void 0 ? { random: options.random } : {}
   });
-  const pull = createPullCoordinator({
-    snapshot,
-    transport: options.transport,
-    events,
-    onServerTime
-  });
   const blobs = options.blob === void 0 ? void 0 : createBlobLane({
     storage: options.storage,
     keyPrefix,