@interncom/diplomatic 0.19.0 → 0.19.1

package/dist/web/client.d.ts

@@ -61,10 +61,14 @@ export declare class SyncClient<Handle extends HostHandle> implements IClient<Ha
     /**
      * Persist msgs (APLD_PENDING), exec into app state, then optionally enq upload.
      *
-     * Order (crash-safe):
-     * 1) durable archive  2) exec + APLD_APPLIED/APLD_ERROR  3) upload queue
-     * Exec is where the app validates the msg; only successes are pushed.
-     * Crash between 1–2 → drainApplyQueue / exec stage recovers.
+     * Order (do not invert — UI notify depends on it):
+     * 1) Kick off state.apply (CachedEntDB emits in the sync prefix of apply;
+     *    the returned Promise is durable EntDB + reconcile).
+     * 2) Durable archive (messages.add).
+     * 3) Await apply + mark APLD_APPLIED/APLD_ERROR.
+     * 4) Upload queue.
+     * Crash between 2–3 → drainApplyQueue recovers.
+     * Awaiting apply before archive makes the UI wait on EntDB IDB.
      *
      * Serialized on applyChain (with local mutates).
      */
@@ -95,6 +99,8 @@ export declare class SyncClient<Handle extends HostHandle> implements IClient<Ha
      * without validating length alignment.
      */
     private applyStored;
+    /** Mark archive rows APPLIED / ERROR from apply stats (aligned with keys). */
+    private markApplyStats;
     insertRaw(bod: EncodedMessage): Promise<ValStat<IMessageHead>>;
     /**
      * Build the next update/delete msg from prior. Pure: no archive I/O.

package/dist/web/entdb/cached.d.ts

@@ -15,14 +15,23 @@ export type OpenEntDBOptions = {
      * Ignored when `cache` is false.
      */
     indexes?: boolean;
+    /**
+     * Notify UI as soon as mem is patched, before durable IDB (default true).
+     * Set false to notify only after durable commit. Ignored when `cache` is false.
+     */
+    optimistic?: boolean;
 };
 export type CachedEntDBOptions = {
     /** Secondary mem indexes (default true). See {@link OpenEntDBOptions.indexes}. */
     indexes?: boolean;
+    /** Immediate mem notify (default true). See {@link OpenEntDBOptions.optimistic}. */
+    optimistic?: boolean;
 };
 /**
  * Open EntDB for the app (or worker). Single entry point.
- * Default: cached with mem indexes. Pass `{ cache: false }` for durable IDB only.
+ * Default: cached with mem indexes and optimistic notify.
+ * Pass `{ cache: false }` for durable IDB only.
+ * Pass `{ optimistic: false }` to notify only after durable commit.
  */
 export declare function openEntDB(opts?: OpenEntDBOptions): Promise<IEntDB>;
 export declare class CachedEntDB implements IEntDB {
@@ -31,6 +40,7 @@ export declare class CachedEntDB implements IEntDB {
     private warmed;
     private listeners;
     private chain;
+    private optimistic;
     constructor(durable: IEntDB, init?: IEntity[], opts?: CachedEntDBOptions);
     /** UI / StateManager: fired when mem changes (immediate apply or durable ingest). */
     subscribe(listener: EntChangeListener): () => void;
@@ -39,8 +49,8 @@ export declare class CachedEntDB implements IEntDB {
     /**
      * Fan-out write: mem (immediate notify) + durable, then reconcile mem
      * from durable for the ops' eids (second notify only if something moved).
-     * Mem patch+emit is synchronous so notify does not wait on IDB (new insert
-     * included). Persist stays on the write chain.
+     * Not `async`: the mem patch+emit below must run before any await.
+     * `{ optimistic: false }`: skip the sync prefix; notify after durable.
      */
     apply(ops: IOp[]): Promise<import("./entdb").ApplyResult>;
     clear(): Promise<Status>;
@@ -52,8 +62,9 @@ export declare class CachedEntDB implements IEntDB {
     /**
      * Install durable truth for each eid into mem (live or tombstone).
      * When `snap` is set (post-apply reconcile), skip eids whose mem stamp
-     * moved — a later apply owns them. Without snap (ingest), do not clobber
-     * a newer in-flight mem row.
+     * moved — a later apply owns them. Always skip if mem is newer than
+     * durable (overlapping optimistic apply). Never replace a newer in-flight
+     * mem row with older durable truth.
      */
     private pullEids;
     private warmType;

package/dist/web/entdb/manager.d.ts

@@ -3,6 +3,8 @@ import type { IEntDB } from "./entdb";
 /**
  * Build a StateManager for an EntDB.
  * When `edb` is a {@link CachedEntDB}, type notifies come from the cache
- * (immediate apply + durable reconcile / peer ingest).
+ * subscribe path (optimistic apply + durable reconcile / peer ingest).
+ * cacheDriven: StateManager.apply must not emit after the applier Promise
+ * settles — that would delay UI until durable IDB. Subscribe is the notify.
  */
 export declare function entStateManager(edb: IEntDB): StateManager;