@interncom/diplomatic 0.4.5 → 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/stores/idb/msgs.d.ts

@@ -1,7 +1,7 @@
 import { Status } from "../../shared/consts";
 import { ICrypto } from "../../shared/types";
 import { EntityID, Hash } from "../../shared/types";
-import { IMessageStore, IStorableMessage, IStoredMessage } from "../../types";
+import { ApldState, IMessageStore, IStorableMessage, IStoredMessage } from "../../types";
 export declare class IDBMessageStore implements IMessageStore {
     private crypto;
     db: IDBDatabase;
@@ -10,9 +10,12 @@ export declare class IDBMessageStore implements IMessageStore {
     del(keys: Iterable<Hash>): Promise<void>;
     get(key: Hash): Promise<IStoredMessage | undefined>;
     has(key: Hash): Promise<boolean>;
-    list(): Promise<Iterable<IStoredMessage>>;
+    list(apld?: ApldState): Promise<IStoredMessage[]>;
     last(eid: EntityID): Promise<IStoredMessage | undefined>;
-    listUnapplied(): Promise<IStoredMessage[]>;
     markApplied(keys: Iterable<Hash>): Promise<void>;
+    markFailed(entries: Iterable<{
+        key: Hash;
+        err: Status;
+    }>): Promise<void>;
     wipe(): Promise<void>;
 }

package/dist/web/stores/idb/store.d.ts

@@ -11,8 +11,9 @@ export declare const UPLOAD_QUEUE_TABLE = "uploadQueue";
 export declare const DOWNLOAD_QUEUE_TABLE = "downloadQueue";
 export declare const MESSAGES_TABLE = "messages";
 /**
- * Index on messages.apld. Values are "f" (pending) / "t" (applied) —
- * booleans are not valid IndexedDB keys; single-char strings keep keys compact.
+ * Index on messages.apld ({@link APLD_PENDING} / {@link APLD_APPLIED} /
+ * {@link APLD_ERROR}). Booleans are not valid IndexedDB keys; single-char
+ * strings keep keys compact.
  */
 export declare const MESSAGES_APLD_INDEX = "apld";
 /** Schema version: v3 adds messages.apld index for the apply queue. */

package/dist/web/stores/memory/msgs.d.ts

@@ -1,6 +1,6 @@
 import { ICrypto } from "../../shared/types";
 import { EntityID, Hash } from "../../shared/types";
-import { IMessageStore, IStorableMessage, IStoredMessage, IStoredMessageData } from "../../types";
+import { ApldState, IMessageStore, IStorableMessage, IStoredMessage, IStoredMessageData } from "../../types";
 import { Status } from "../../shared/consts";
 export declare class MemoryMessageStore implements IMessageStore {
     private crypto;
@@ -10,9 +10,12 @@ export declare class MemoryMessageStore implements IMessageStore {
     del(keys: Iterable<Hash>): Promise<void>;
     get(key: Hash): Promise<IStoredMessage | undefined>;
     has(key: Hash): Promise<boolean>;
-    list(): Promise<Iterable<IStoredMessage>>;
+    list(apld?: ApldState): Promise<IStoredMessage[]>;
     last(eid: EntityID): Promise<IStoredMessage | undefined>;
-    listUnapplied(): Promise<IStoredMessage[]>;
     markApplied(keys: Iterable<Hash>): Promise<void>;
+    markFailed(entries: Iterable<{
+        key: Hash;
+        err: Status;
+    }>): Promise<void>;
     wipe(): Promise<void>;
 }

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>;
@@ -74,10 +75,18 @@ export interface IDownloadQueue {
     count: () => Promise<number>;
     wipe(): Promise<void>;
 }
+/**
+ * Apply lifecycle values for archive rows (IDB-indexable single-char strings;
+ * booleans are not valid IndexedDB keys). Defined first so {@link ApldState}
+ * is only those three literals.
+ */
+export declare const APLD_PENDING: "f";
+export declare const APLD_APPLIED: "t";
+export declare const APLD_ERROR: "e";
+/** Only {@link APLD_PENDING}, {@link APLD_APPLIED}, or {@link APLD_ERROR}. */
+export type ApldState = typeof APLD_PENDING | typeof APLD_APPLIED | typeof APLD_ERROR;
 /**
  * Archive fields shared by read and write.
- * `apld`: true once the msg has been applied by the application state manager;
- * false while still pending apply.
  */
 export interface IStoredMessageFields {
     eid: EntityID;
@@ -87,19 +96,23 @@ export interface IStoredMessageFields {
 }
 /**
  * What may come back from storage (pre-apld rows can omit the field).
- * IDB stores "t"|"f" (booleans are not valid IndexedDB index keys).
- * Prefer {@link normalizeStoredMessageData} before use.
+ * Typed rows use only {@link ApldState}; {@link apldFromStored} coerces
+ * legacy boolean / unknown values at the storage boundary.
  */
 export interface IStoredMessageData extends IStoredMessageFields {
-    apld?: boolean | "t" | "f";
+    apld?: ApldState;
+    /** Status code when apld is {@link APLD_ERROR}. */
+    err?: number;
 }
 /**
  * Required shape for every put into the message archive (app/API layer).
- * Callers must set `apld` (false until applied, then true).
- * The IDB adapter persists this as "t"|"f" for indexing.
+ * `apld` is required and must be one of the three {@link ApldState} values.
+ * Omit optional fields (`off`, `ctr`, `body`, `err`) rather than storing empties.
  */
 export type IStoredMessageWrite = IStoredMessageFields & {
-    apld: boolean;
+    apld: ApldState;
+    /** Status code when apld is {@link APLD_ERROR}. */
+    err?: number;
 };
 export interface IStorableMessage {
     key: Hash;
@@ -109,29 +122,51 @@ export interface IStoredMessage {
     hash: Hash;
     head: IMessageHead;
     body?: EncodedMessage;
-    applied: boolean;
+    /** Apply lifecycle — same {@link ApldState} as the archive row. */
+    apld: ApldState;
+    /** Status code when apld is {@link APLD_ERROR}. */
+    err?: number;
 }
+/** True only for the three legal {@link ApldState} values. */
+export declare function isApldState(v: unknown): v is ApldState;
 /**
- * Coerce stored `apld` to boolean.
- * Applied: true | "t". Pending: false | "f" | missing.
+ * Coerce raw storage values to {@link ApldState}.
+ * Applied: true | APLD_APPLIED. Failed: APLD_ERROR.
+ * Pending: false | APLD_PENDING | missing | anything else.
  */
-export declare function apldFromStored(v: unknown): boolean;
-/** Coerce storage rows to the write shape with boolean apld. */
-export declare function normalizeStoredMessageData(data: IStoredMessageData): IStoredMessageWrite;
-/** Pending apply when not yet marked applied. */
+export declare function apldFromStored(v: unknown): ApldState;
+/** Pending apply when not yet applied or terminally failed. */
 export declare function isPendingApply(data: IStoredMessageData): boolean;
+/**
+ * Apply failures that should not be retried (poison / protocol / shape).
+ * Transient storage errors stay pending ({@link APLD_PENDING}) for a later drain.
+ */
+export declare function isTerminalApplyFailure(st: Status): boolean;
+/**
+ * Mutate a stored row's apply state in place (no copy).
+ * Clears `err` unless setting {@link APLD_ERROR}.
+ */
+export declare function setApld(data: IStoredMessageData, apld: ApldState, err?: Status): void;
 export declare function toStoredMessage(hash: Hash, data: IStoredMessageData, crypto: ICrypto): Promise<IStoredMessage>;
 export interface IMessageStore {
     add: (messages: IStorableMessage[]) => Promise<Status[]>;
     get: (key: Hash) => Promise<IStoredMessage | undefined>;
     has: (key: Hash) => Promise<boolean>;
     del: (keys: Iterable<Hash>) => Promise<void>;
-    list: () => Promise<Iterable<IStoredMessage>>;
+    /**
+     * List archive rows. Pass {@link ApldState} to filter by apply lifecycle
+     * (e.g. {@link APLD_PENDING} for the apply queue, {@link APLD_ERROR} for
+     * diagnostics). Omit for all messages.
+     */
+    list: (apld?: ApldState) => Promise<IStoredMessage[]>;
     last: (eid: EntityID) => Promise<IStoredMessage | undefined>;
-    /** Messages stored but not yet applied (apld === false). */
-    listUnapplied: () => Promise<IStoredMessage[]>;
-    /** Mark archive rows as applied (apld = true). */
+    /** Mark archive rows as applied ({@link APLD_APPLIED}). */
     markApplied: (keys: Iterable<Hash>) => Promise<void>;
+    /** Mark archive rows as terminal apply failure ({@link APLD_ERROR}). */
+    markFailed: (entries: Iterable<{
+        key: Hash;
+        err: Status;
+    }>) => Promise<void>;
     wipe(): Promise<void>;
 }
 export interface IStore<Handle extends HostHandle> {
@@ -157,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;