@interncom/diplomatic 0.5.0 → 0.6.0

package/dist/web/shared/types.d.ts

@@ -39,11 +39,32 @@ export type IOp = IDeleteOp | IMutateOp;
 export declare function isDeleteOp(op: IOp): op is IDeleteOp;
 export declare function isMutateOp(op: IOp): op is IMutateOp;
 export interface IInsertParams<T> extends IMsgEntBody<T> {
+    /** Optional 8-byte id material for the new eid; else random. */
     id?: Uint8Array;
 }
-export interface IUpsertParams<T> extends IMsgEntBody<T> {
-    eid?: EntityID;
-}
+/**
+ * Revision of an ent used as the base for update/delete.
+ * Apps almost always already hold this (the row being edited).
+ */
+export interface IEntRev {
+    eid: EntityID;
+    ctr: number;
+    /** Last-write time of this rev (eid.ts + off of the latest msg for this eid). */
+    updatedAt: Date;
+}
+export interface IUpdateParams<T> extends IMsgEntBody<T> {
+    prior: IEntRev;
+    /** Clock-skew recovery; default client-wide (usually true). */
+    force?: boolean;
+}
+/** Prefer `{ prior }`; `{ eid }` loads prior from the message archive. */
+export type IDeleteParams = {
+    prior: IEntRev;
+    force?: boolean;
+} | {
+    eid: EntityID;
+    force?: boolean;
+};
 export interface IStorage {
     addUser: (pubKey: PublicKey) => Promise<ValStat<void>>;
     hasUser: (pubKey: PublicKey) => Promise<ValStat<boolean>>;
@@ -172,6 +193,12 @@ export interface IStateManager {
      * updated shared application state in IndexedDB).
      */
     notify: (types: Iterable<string>) => void;
+    /**
+     * Peer wrote durable application state for these eids (e.g. sync worker).
+     * With CachedEntDB: pull those eids from durable; type-level UI notifies
+     * fire only if mem changed.
+     */
+    refresh: (eids: Iterable<EntityID>) => Promise<void>;
     on: (type: string, listener: () => void) => void;
     off: (type: string, listener: () => void) => void;
 }

package/dist/web/state.d.ts

@@ -1,23 +1,42 @@
 import { Status } from "./shared/consts";
-import { IMessage, IMsgEntBody, IOp, IStateManager } from "./shared/types";
+import { EntityID, IMessage, IMsgEntBody, IOp, IStateManager } from "./shared/types";
 import { ValStat } from "./shared/valstat";
 import type { Applier } from "./types";
 export declare function isMsgEntBody(bodDec: unknown): bodDec is IMsgEntBody;
 export declare function msgToOp(msg: IMessage): ValStat<IOp>;
+type PeerIngestFn = (eids: Iterable<EntityID>) => Promise<void>;
 export declare class StateManager implements IStateManager {
     applier: Applier;
     private emitter;
     private clearer;
-    private onTypes;
+    /** Worker / peer: eids successfully applied to durable EntDB. */
+    private onDirtyEids;
+    /**
+     * When set (CachedEntDB), type events are driven by the cache's subscribe
+     * path (immediate + durable ingest). apply() does not re-emit.
+     */
+    private cacheDriven;
+    private peerIngest;
     constructor(applier: Applier, clearer: () => Promise<Status>, 
-    /** Optional hook after a successful apply batch (e.g. worker dirty signal). */
-    onTypes?: (types: Set<string>) => void);
+    /**
+     * Called with eids that successfully applied (e.g. worker posts dirty).
+     */
+    onDirtyEids?: (eids: EntityID[]) => void, opts?: {
+        cacheDriven?: boolean;
+        peerIngest?: PeerIngestFn;
+    });
     apply: (msgs: IMessage[]) => Promise<Status[]>;
     /** Clear application state and notify all type subscribers. */
     clear: () => Promise<Status>;
-    /** Notify type subscribers without applying msgs (shared-IDB peer updates). */
+    /** Notify type subscribers without applying msgs. */
     notify: (types: Iterable<string>) => void;
+    /**
+     * Peer (e.g. sync worker) updated durable EntDB for these eids.
+     * Cache pulls those rows; apps still hear type-level events via subscribe.
+     */
+    refresh: (eids: Iterable<EntityID>) => Promise<void>;
     on: (opType: string, listener: () => void) => void;
     off: (opType: string, listener: () => void) => void;
 }
 export declare const nullStateManager: IStateManager;
+export {};

package/dist/web/types.d.ts

@@ -2,7 +2,7 @@ import type { SyncProgressEvent } from "./progress";
 import { Status } from "./shared/consts";
 import type { Enclave } from "./shared/enclave";
 import type { EncodedMessage } from "./shared/message";
-import type { EntityID, Hash, HostHandle, IHostConnectionInfo, IHostMetadata, IInsertParams, IMessageHead, IOp, IUpsertParams, MasterSeed, SerializedContent } from "./shared/types";
+import type { EntityID, Hash, HostHandle, IDeleteParams, IEntRev, IHostConnectionInfo, IHostMetadata, IInsertParams, IMessageHead, IOp, IUpdateParams, MasterSeed, SerializedContent } from "./shared/types";
 import { ValStat } from "./shared/valstat";
 import { ICrypto } from "./shared/types";
 export interface IMsgParts {
@@ -27,6 +27,7 @@ export interface IDiplomaticClientXferState {
 export type Applier = (ops: IOp[]) => Promise<{
     stats: Status[];
     types: Set<string>;
+    eids: EntityID[];
 }>;
 export interface ISeedStore {
     save: (seed: MasterSeed) => Promise<Enclave>;
@@ -191,10 +192,13 @@ export interface IClient<Handle extends HostHandle> {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     insertRaw(content: SerializedContent): Promise<ValStat<IMessageHead>>;
-    upsertRaw(eid: EntityID, content: SerializedContent, force?: boolean): Promise<ValStat<IMessageHead>>;
+    updateRaw(prior: IEntRev, content: SerializedContent | undefined, force?: boolean): Promise<ValStat<IMessageHead>>;
     insert<T = unknown>(op: IInsertParams<T>): Promise<ValStat<IMessageHead>>;
-    upsert<T = unknown>(op: IUpsertParams<T>, force?: boolean): Promise<ValStat<IMessageHead>>;
-    delete(eid: EntityID): Promise<ValStat<IMessageHead>>;
+    update<T = unknown>(op: IUpdateParams<T>): Promise<ValStat<IMessageHead>>;
+    /**
+     * Delete by `{ prior }` (preferred) or `{ eid }` (archive lookup).
+     */
+    delete(op: IDeleteParams): Promise<ValStat<IMessageHead>>;
     /** Allocate an entity id (optional 8-byte id material; else random). */
     genEID(id?: Uint8Array): Promise<ValStat<EntityID>>;
     sync(): Promise<Status>;

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

@@ -1,6 +1,6 @@
 import { IClock } from "../shared/clock";
 import { Status } from "../shared/consts";
-import type { EntityID, IHostConnectionInfo, IInsertParams, IMessageHead, IStateManager, IUpsertParams, MasterSeed, SerializedContent } from "../shared/types";
+import type { EntityID, IDeleteParams, IEntRev, IHostConnectionInfo, IInsertParams, IMessageHead, IStateManager, IUpdateParams, MasterSeed, SerializedContent } from "../shared/types";
 import type { ValStat } from "../shared/valstat";
 import type { IClient, IDiplomaticClientState, IDiplomaticClientXferState, IHostRow, IStateEmitter, IStore } from "../types";
 /**
@@ -13,6 +13,11 @@ import type { IClient, IDiplomaticClientState, IDiplomaticClientXferState, IHost
  * 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).
+ *
+ * After the ready barrier, connect hydrates `clientState` / `xferState` from the
+ * shared main-thread store (and recovers via getClientState/getXferState if the
+ * unsolicited events were dropped). Without that, the façade defaults to
+ * `hasSeed: false` and apps flash the unauthenticated UI until a later event.
  */
 export type WorkerClientOptions = {
     /** Already-constructed module Worker running `@interncom/diplomatic/worker`. */
@@ -60,8 +65,23 @@ export declare class WorkerClient implements IClient<URL> {
      * 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`.
+     *
+     * Then hydrate client/xfer state from the shared store (and RPC) so
+     * `clientState.get()` is correct before connect returns — unsolicited
+     * `clientState` events are often lost when the Worker starts before
+     * `onmessage` is attached.
      */
     static connect(state: IStateManager, store: IStore<URL>, opts: WorkerClientOptions): Promise<WorkerClient>;
+    /**
+     * Snapshot seed/host/queues from the shared main-thread store.
+     * `connected` stays false until the worker reports otherwise.
+     */
+    private hydrateStateFromStore;
+    /**
+     * Request current client/xfer state from the worker. Recovers when unsolicited
+     * `clientState` / `xferState` events fired before `onmessage` was set.
+     */
+    private pullRemoteState;
     /** Resolve the ready barrier (idempotent). */
     private markReady;
     /**
@@ -85,12 +105,12 @@ export declare class WorkerClient implements IClient<URL> {
     hosts(): Promise<IHostRow<URL>[]>;
     connect(listen?: boolean, sync?: boolean): Promise<void>;
     disconnect(): Promise<void>;
-    /** Local UI write: archive + apply on main (fast UI); upload/sync via worker. */
+    /** Local UI write: archive + apply on main (cache notifies UI); sync via worker. */
     insertRaw(content: SerializedContent): Promise<ValStat<IMessageHead>>;
-    upsertRaw(eid: EntityID, content: SerializedContent | undefined, force?: boolean): Promise<ValStat<IMessageHead>>;
+    updateRaw(prior: IEntRev, content: SerializedContent | undefined, force?: boolean): Promise<ValStat<IMessageHead>>;
     insert<T = unknown>(op: IInsertParams<T>): Promise<ValStat<IMessageHead>>;
-    upsert<T = unknown>(op: IUpsertParams<T>, force?: boolean): Promise<ValStat<IMessageHead>>;
-    delete(eid: EntityID): Promise<ValStat<IMessageHead>>;
+    update<T = unknown>(op: IUpdateParams<T>): Promise<ValStat<IMessageHead>>;
+    delete(op: IDeleteParams): Promise<ValStat<IMessageHead>>;
     genEID(id?: Uint8Array): Promise<ValStat<EntityID>>;
     sync(): Promise<Status>;
     wipe(): Promise<void>;

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

@@ -1,5 +1,4 @@
 import type { Status } from "../shared/consts";
-import type { IMessageHead } from "../shared/types";
 import type { SyncProgressEvent } from "../progress";
 import type { IDiplomaticClientState, IDiplomaticClientXferState } from "../types";
 /** Host identity as plain data (URL → string for structured clone). */
@@ -38,40 +37,6 @@ export type WorkerCmd = {
 } | {
     id: number;
     op: "wipe";
-} | {
-    id: number;
-    op: "insertRaw";
-    body: Uint8Array;
-} | {
-    id: number;
-    op: "upsertRaw";
-    eid: Uint8Array;
-    body?: Uint8Array;
-    force?: boolean;
-} | {
-    id: number;
-    op: "insert";
-    params: {
-        type: string;
-        body: unknown;
-        gid?: string;
-        pid?: Uint8Array;
-    };
-} | {
-    id: number;
-    op: "upsert";
-    params: {
-        type: string;
-        body: unknown;
-        eid?: Uint8Array;
-        gid?: string;
-        pid?: Uint8Array;
-    };
-    force?: boolean;
-} | {
-    id: number;
-    op: "delete";
-    eid: Uint8Array;
 } | {
     id: number;
     op: "import";
@@ -108,17 +73,19 @@ export type WorkerEvent = {
     kind: "xferState";
     state: IDiplomaticClientXferState;
 }
-/** Application state (e.g. EntDB) changed for these op types; re-read IDB. */
+/**
+ * Application state (e.g. EntDB) changed for these eids.
+ * Main cache pulls only those rows from shared IDB, then notifies by type.
+ */
  | {
     kind: "dirty";
-    types: string[];
+    eids: Uint8Array[];
 } | {
     kind: "wiped";
 } | WorkerReply;
 export declare function isWorkerEvent(data: unknown): data is WorkerEvent;
 export declare function isWorkerCmd(data: unknown): data is WorkerCmd;
 /** Narrow helpers for typed replies (avoid casts at call sites). */
-export declare function headFromUnknown(v: unknown): IMessageHead | undefined;
 export declare function statusFromUnknown(v: unknown): Status | undefined;
 export declare function clientStateFromUnknown(v: unknown): IDiplomaticClientState | undefined;
 export declare function progressFromUnknown(v: unknown): SyncProgressEvent | undefined;