@interncom/diplomatic 0.3.3 → 0.4.0

package/dist/web/openClient.d.ts

@@ -13,6 +13,16 @@ import type { IClient, IStore } from "./types";
  * (built as `worker.mjs` in the published package). It must run as a
  * **module** worker (`type: "module"`).
  *
+ * ## Handshake (race-safe)
+ *
+ * The worker posts an unsolicited `{ kind: "ready" }` after init. Apps often
+ * construct the Worker at module load (or before `openDiplomaticClient` finishes
+ * opening IndexedDB), so that event can fire before the library sets
+ * `onmessage`. **That is fine:** connect also probes with a request/response
+ * `ping`. The worker holds commands until init completes, so the probe succeeds
+ * even if `ready` was dropped. Do **not** reimplement message buffering in the
+ * app unless you need it for other reasons.
+ *
  * ## Vite (recommended for SPA templates)
  *
  * ```ts
@@ -23,6 +33,7 @@ import type { IClient, IStore } from "./types";
  *
  * `?worker` makes Vite emit a real worker asset and a constructor. Create the
  * instance once (module scope or `useMemo`/`useRef`) — not on every render.
+ * Early construction is supported; the handshake recovers if `ready` is missed.
  *
  * ## webpack / Rollup / esbuild / Parcel (`new URL` + import.meta.url)
  *

package/dist/web/progress.d.ts

@@ -2,7 +2,7 @@
  *
  * Exposed only via `IDiplomaticClientXferState.progress` on `client.xferState`
  * (get + listen / `useClientXferState`). There is no separate progress channel. */
-export type SyncPhase = "peek" | "push" | "pull" | "apply" | "import" | "idle";
+export type SyncPhase = "peek" | "pull" | "open" | "exec" | "push" | "import" | "idle";
 export interface SyncProgressEvent {
     phase: SyncPhase;
     /** Host label when the work is host-scoped. */

package/dist/web/react/useClient.d.ts

@@ -19,11 +19,16 @@ type UseClientBase = {
  *   import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
  *   const syncWorker = new DiplomaticWorker();
  *   useClient({ worker: syncWorker, seed, host });
+ *
+ * Handshake is race-safe (ready event and/or probe ping). See
+ * `openDiplomaticClient` for bundler recipes and handshake notes.
  */
 export type UseClientWorkerOptions = UseClientBase & {
     /**
      * App-constructed sync Worker. Create once (module scope or useMemo/useRef),
-     * not each render. See `openDiplomaticClient` for instantiation recipes.
+     * not each render. Early construction before `useClient` opens IDB is OK —
+     * the library does not require catching the unsolicited `ready` event.
+     * See `openDiplomaticClient` for instantiation recipes.
      */
     worker: Worker;
     store?: never;

package/dist/web/sync.d.ts

@@ -1,19 +1,25 @@
 import DiplomaticClientAPI from "./shared/client";
-import { IClock } from "./shared/clock";
 import { Status } from "./shared/consts";
 import { Enclave } from "./shared/enclave";
 import { Hash, HostHandle, IBag, ICrypto } from "./shared/types";
+import { ValStat } from "./shared/valstat";
 import { ProgressFn } from "./progress";
 import { IDownloadMessage, IHostRow, IMsgParts, IStore, type IStoredMessageWrite } from "./types";
 /** Default soft cap for one push/pull request (~1 MiB). Apps with large
  * payloads (e.g. media) should raise maxPushBytes / maxPullBytes. */
 export declare const defaultMaxPushBytes: number;
 export declare const defaultMaxPullBytes: number;
+/** Pull result held in memory until open (not durable). */
+export type IPulled = {
+    dl: IDownloadMessage;
+    bodyCph?: Uint8Array;
+};
+/** Host connection methods used by sync phases. */
+export type SyncConn<Handle extends HostHandle> = Pick<DiplomaticClientAPI<Handle>, "pull" | "push" | "peek" | "seal" | "keys">;
 export interface ISyncParams<Handle extends HostHandle> {
-    conn: DiplomaticClientAPI<Handle>;
+    conn: SyncConn<Handle>;
     store: IStore<Handle>;
     enclave: Enclave;
-    clock: IClock;
     host: IHostRow<Handle>;
     crypto: ICrypto;
     /** Soft max sealed-bag bytes per push request. Oversized bags go alone. */
@@ -27,19 +33,33 @@ export interface ISyncParams<Handle extends HostHandle> {
 }
 /** Push one batch of sealed bags; deq successes; advance lastSeq from store. */
 export declare function pushBatch<Handle extends HostHandle>(conn: Pick<DiplomaticClientAPI<Handle>, "push">, store: IStore<Handle>, hostLabel: string, bags: IBag[], hashes: Hash[]): Promise<Status>;
-/** Pull one batch of download-queue items; store, deq, apply. */
-export declare function pullBatch<Handle extends HostHandle>(conn: Pick<DiplomaticClientAPI<Handle>, "pull">, store: IStore<Handle>, enclave: Enclave, hostLabel: string, crypto: ICrypto, items: IDownloadMessage[], apply: (parts: IMsgParts[], options?: {
-    enqueueUpload: boolean;
-    triggerUpload: boolean;
-}) => Promise<Status[]>): Promise<Status>;
+/** pull: network only. Download-queue items → ciphertext (still enqueued). */
+export declare function pullBodies<Handle extends HostHandle>(conn: Pick<DiplomaticClientAPI<Handle>, "pull">, items: IDownloadMessage[]): Promise<ValStat<IPulled[]>>;
+export type IOpened = {
+    parts: IMsgParts[];
+    hashes: Hash[];
+};
+/**
+ * open: decrypt pulled bodies → msg archive (apld=false), deq downloads.
+ * Bad bags are dequeued and skipped (not retry-able).
+ * Does not exec or push.
+ */
+export declare function openPulled<Handle extends HostHandle>(store: IStore<Handle>, enclave: Enclave, crypto: ICrypto, items: IPulled[]): Promise<ValStat<IOpened>>;
+/** Discover unseen bags and enqueue download work; advance host lastSeq. */
 export declare function syncPeek<Handle extends HostHandle>({ conn, store, enclave, host, crypto, onProgress, peekProgressEvery, }: ISyncParams<Handle>): Promise<Status>;
+/** Seal and upload pending msgs; list once so concurrent enqs wait for next sync. */
 export declare function syncPush<Handle extends HostHandle>({ conn, store, host, maxPushBytes, onProgress }: ISyncParams<Handle>): Promise<Status>;
-export declare function syncPull<Handle extends HostHandle>({ conn, store, enclave, host, crypto, maxPullBytes, onProgress, }: ISyncParams<Handle>, apply: (parts: IMsgParts[], options?: {
-    enqueueUpload: boolean;
-    triggerUpload: boolean;
-}) => Promise<Status[]>): Promise<Status>;
+/**
+ * Pull + open for one host, depth-1 pipelined:
+ *   await pull(i); start pull(i+1); open(i); afterOpen? (exec)
+ * Ciphertext only in the in-flight Promise, never IDB.
+ */
+export declare function syncPull<Handle extends HostHandle>({ conn, store, enclave, host, crypto, maxPullBytes, onProgress, }: ISyncParams<Handle>, 
+/** After each opened pull batch (e.g. drainApplyQueue / exec). */
+afterOpen?: () => Promise<void>): Promise<Status>;
 export declare function msg2StoredMsgData({ head, body }: IMsgParts): IStoredMessageWrite;
-export declare function handleNotif<Handle extends HostHandle>(bytes: Uint8Array, { conn, store, enclave, host, crypto, clock, maxPullBytes, maxPushBytes, onProgress, peekProgressEvery, }: ISyncParams<Handle>, apply: (parts: IMsgParts[], options?: {
-    enqueueUpload: boolean;
-    triggerUpload: boolean;
-}) => Promise<Status[]>, scheduleSync: () => void): Promise<void>;
+/**
+ * notif → open inline bodies into archive; enq incomplete → scheduleSync.
+ * `scheduleSync` runs full peek/push/pull (or worker handoff).
+ */
+export declare function handleNotif<Handle extends HostHandle>(bytes: Uint8Array, { conn, store, enclave, host, crypto, onProgress, }: ISyncParams<Handle>, scheduleSync: () => void): Promise<void>;

package/dist/web/worker/client.d.ts

@@ -8,11 +8,19 @@ import type { IClient, IDiplomaticClientState, IDiplomaticClientXferState, IHost
  *
  * Provide a live `Worker` — the library never constructs one. See
  * `openDiplomaticClient` for bundler/CDN instantiation recipes.
+ *
+ * Handshake is race-safe: the worker posts unsolicited `{ kind: "ready" }`, but
+ * connect also probes with `ping`. Early construction (module scope) is fine even
+ * if `ready` fired before `onmessage` was set — the ping still succeeds once the
+ * worker has finished init (cmds are held until then on the worker side).
  */
 export type WorkerClientOptions = {
     /** Already-constructed module Worker running `@interncom/diplomatic/worker`. */
     worker: Worker;
-    /** Max wait for worker `ready` (default 15s). Failures throw; no fallback. */
+    /**
+     * Max wait for handshake (`ready` event or probe ping; default 15s).
+     * Failures throw; no fallback.
+     */
     readyTimeoutMs?: number;
     clock?: IClock;
     /**
@@ -48,8 +56,19 @@ export declare class WorkerClient implements IClient<URL> {
      * Attach to an app-provided Worker. `store` is the shared protocol IDB (main
      * connection) used for local msg writes; worker opens its own connection.
      * Throws if the worker never becomes ready — does not fall back to main thread.
+     *
+     * Handshake: wait for unsolicited `ready` **or** a successful probe `ping`.
+     * The probe covers the common case where the app started the Worker early and
+     * `ready` was dropped before this thread set `onmessage`.
      */
     static connect(state: IStateManager, store: IStore<URL>, opts: WorkerClientOptions): Promise<WorkerClient>;
+    /** Resolve the ready barrier (idempotent). */
+    private markReady;
+    /**
+     * Active handshake: post ping without waiting for the ready event.
+     * On pong, mark ready so connect can proceed even if `ready` was missed.
+     */
+    private probeReady;
     /** Lightweight RPC check after connect. */
     ping(): Promise<void>;
     /** Terminate the worker (drops protocol DB connection in that thread). */

package/dist/web/worker/runtime.d.ts

@@ -4,8 +4,14 @@ export type PostFn = (msg: WorkerEvent, transfer?: Transferable[]) => void;
 export declare class WorkerRuntime {
     private client;
     private post;
+    /** Resolves when init finishes (success or failure). Cmds wait on this. */
+    private whenReady;
+    private resolveReady;
+    private rejectReady;
     constructor(post: PostFn);
     init(): Promise<void>;
+    private markReady;
+    private failReady;
     private requireClient;
     private emitClientState;
     private emitXferState;