@interncom/diplomatic 0.8.4 → 0.9.0

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

@@ -1,7 +1,7 @@
 import { Status } from "../shared/consts";
 import { EntityID, Hash, ICrypto, IOp } from "../shared/types";
 import { ValStat } from "../shared/valstat";
-import { EntitiesQuery, IEntDB, IEntity } from "./entdb";
+import { EntitiesQuery, IEntDB, IEntity, IEntRow } from "./entdb";
 export type EntChangeListener = (types: Set<string>) => void;
 export type OpenEntDBOptions = {
     /**
@@ -48,12 +48,13 @@ export declare class CachedEntDB implements IEntDB {
      */
     ingestFromDurable(eids: Iterable<EntityID>): Promise<Status>;
     /**
-     * Install durable truth for each eid into mem.
-     * Always writes mem from durable; notifies types only when the full ent
-     * identity differs from what mem had (or the row was deleted).
+     * Install durable truth for each eid into mem (live or tombstone).
+     * Always writes mem from durable; notifies types only when the full row
+     * identity differs from what mem had (or the row appeared/vanished).
      */
     private pullEids;
     private warmType;
+    getRow<T>(eid: EntityID): Promise<ValStat<IEntRow<T> | undefined>>;
     getEnt<T>(eid: EntityID): Promise<ValStat<IEntity<T> | undefined>>;
     getEntities<T>(query: EntitiesQuery): Promise<ValStat<IEntity<T>[]>>;
     countEntities({ type }: {

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

@@ -9,6 +9,23 @@ export interface IEntity<T = unknown> extends Omit<IMsgEntBody<T>, "body"> {
     ctr: number;
     body: T;
 }
+/**
+ * Deleted eid's LWW frontier: eid + updatedAt + ctr only (no type/body/…).
+ * Permanent — pruning would allow obsolete mutates to resurrect the ent.
+ * `type?: never` is type-only so IEntity is not assignable to ITombstone.
+ */
+export interface ITombstone {
+    eid: EntityID;
+    updatedAt: Date;
+    ctr: number;
+    type?: never;
+}
+/** Live ent or tombstone (what the store holds per eid). */
+export type IEntRow<T = unknown> = IEntity<T> | ITombstone;
+/** Live ent (has `type`). */
+export declare function isLiveEnt<T>(row: IEntRow<T>): row is IEntity<T>;
+/** Tombstone frontier (no `type`). */
+export declare function isTombstone(row: IEntRow): row is ITombstone;
 export interface IDateRange {
     start: Date;
     end: Date;
@@ -44,20 +61,28 @@ export type ApplyResult = {
 export interface IEntDB {
     apply: (ops: IOp[]) => Promise<ApplyResult>;
     clear: () => Promise<Status>;
+    /**
+     * Live ent only. Tombstones and missing eids both yield undefined.
+     * Use {@link getRow} when LWW / cache reconcile needs the frontier.
+     */
     getEnt<T>(eid: EntityID): Promise<ValStat<IEntity<T> | undefined>>;
+    /** Live ent or permanent tombstone. */
+    getRow<T>(eid: EntityID): Promise<ValStat<IEntRow<T> | undefined>>;
     getEntities<T>(query: EntitiesQuery): Promise<ValStat<IEntity<T>[]>>;
     countEntities({ type }: {
         type: string;
     }): Promise<ValStat<number>>;
     /**
-     * Frontier checksum of live rows: eid + updatedAt + ctr per ent
+     * Frontier checksum of all rows (live + tombstone): eid + updatedAt + ctr
      * (see encodeEntRev / checksumEntRevs). Not a content hash of bodies.
      */
     checksum(crypto: ICrypto): Promise<ValStat<Hash>>;
 }
-/** Prior rev from a loaded entity (typical update/delete input). */
-export declare function revFromEntity(ent: IEntity): IEntRev;
+/** Prior rev from a live ent or tombstone. */
+export declare function revFromEntity(ent: IEntRow): IEntRev;
 /** Prior rev from a msg head returned by insert/update/delete. */
 export declare function revFromHead(head: IMessageHead): ValStat<IEntRev>;
-export declare function applyOp(curr: IEntity | undefined, op: IOp): ValStat<IEntity | undefined>;
+export declare function applyOp(curr: IEntRow | undefined, op: IOp): ValStat<IEntRow | undefined>;
+/** Types to notify when curr → next after a successful apply. */
+export declare function typesChanged(curr: IEntRow | undefined, next: IEntRow): string[];
 export declare const nullEntDB: IEntDB;

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

@@ -1,7 +1,7 @@
 import { Status } from "../shared/consts";
 import { EntityID, GroupID, Hash, ICrypto, IOp } from "../shared/types";
 import { ValStat } from "../shared/valstat.ts";
-import { EntitiesQuery, IEntDB, IEntity } from "./entdb";
+import { EntitiesQuery, IEntDB, IEntity, IEntRow } from "./entdb";
 export declare const entityTableName = "entities";
 export declare const typeIndexName = "entity_type_created_at";
 export declare const typeUpdatedAtIndexName = "entity_type_updated_at";
@@ -30,6 +30,7 @@ export declare class EntIDB implements IEntDB {
         eids: EntityID[];
     }>;
     clear(): Promise<Status>;
+    getRow<T>(eid: EntityID): Promise<ValStat<IEntRow<T> | undefined>>;
     getEnt<T>(eid: EntityID): Promise<ValStat<IEntity<T> | undefined>>;
     getAllOfTypeUpdatedBetween<T>(opType: string, start: Date, end: Date): Promise<ValStat<IEntity<T>[]>>;
     getGroupMembers<T>(opType: string, gid: GroupID): Promise<ValStat<IEntity<T>[]>>;

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

@@ -1,4 +1,4 @@
-import { IEntDB, IEntity } from "./entdb";
+import { IEntDB, IEntity, IEntRow } from "./entdb";
 import { Status } from "../shared/consts";
 import { EntityID, GroupID, Hash, ICrypto, IOp } from "../shared/types";
 import { ValStat } from "../shared/valstat.ts";
@@ -22,7 +22,8 @@ export type EntDBMemoryOptions = {
     indexes?: boolean;
 };
 export declare class EntDBMemory implements IEntDB {
-    ents: Map<string, IEntity>;
+    /** Live ents and permanent tombstones. */
+    ents: Map<string, IEntRow>;
     private readonly useIndex;
     /** type → eidKey → ent */
     private byType;
@@ -33,8 +34,8 @@ export declare class EntDBMemory implements IEntDB {
     /** type → tag → eidKey → ent */
     private byTypeTag;
     constructor(initEnts?: IEntity[], opts?: EntDBMemoryOptions);
-    /** Install or replace an entity; keeps secondary indexes in sync. */
-    put(ent: IEntity): void;
+    /** Install or replace a row; live ents are indexed, tombstones are not. */
+    put(row: IEntRow): void;
     /** Remove by eid key; keeps secondary indexes in sync. */
     del(key: string): void;
     private index;
@@ -47,6 +48,7 @@ export declare class EntDBMemory implements IEntDB {
         eids: EntityID[];
     }>;
     clear(): Promise<Status>;
+    getRow<T>(eid: EntityID): Promise<ValStat<IEntRow<T> | undefined>>;
     getEnt<T>(eid: EntityID): Promise<ValStat<IEntity<T> | undefined>>;
     private getAllEntities;
     getEntities<T>(query: EntitiesQuery): Promise<ValStat<IEntity<T>[]>>;

package/dist/web/hlc.d.ts

@@ -12,9 +12,9 @@ export declare function headUpdatedAtMs(head: IHlcHead): number | undefined;
  * Higher updatedAt first; tie-break higher ctr (later update at same ms).
  * Unknown/unparseable eids sort last.
  *
- * EntDB/StateManager already no-ops obsolete msgs (LWW). Sorting newest-first
- * is so app state converges to its final view early in a large apply, not to
- * save work on the later NoChange applies.
+ * EntDB LWW no-ops obsolete msgs against the current row, including permanent
+ * tombstones after delete. Newest-first is so app state converges early in a
+ * large apply, not to save work on later NoChange applies.
  */
 export declare function compareHeadHlcDesc(a: IHlcHead, b: IHlcHead): number;
 /** Stable copy sorted newest-first by HLC. */

package/dist/web/index.d.ts

@@ -1,7 +1,7 @@
 import { SyncClient } from "./client";
 import crypto from "./crypto";
 import { CachedEntDB, type CachedEntDBOptions, openEntDB, type OpenEntDBOptions } from "./entdb/cached";
-import { EntitiesQuery, entStateManager, IEntDB, IEntity, normalizeTags, nullEntDB, revFromEntity, revFromHead } from "./entdb/entdb";
+import { EntitiesQuery, entStateManager, IEntDB, IEntity, IEntRow, isLiveEnt, isTombstone, ITombstone, normalizeTags, nullEntDB, revFromEntity, revFromHead } from "./entdb/entdb";
 import { EntIDB } from "./entdb/idb";
 import { EntDBMemory, type EntDBMemoryOptions } from "./entdb/memory";
 import { useClient, useClientState, useClientXferState, useSyncOnResume } from "./react/useClient";
@@ -30,5 +30,5 @@ export declare function genWebClient(stateMgr: IStateManager, url: URL): Promise
     client: SyncClient<URL>;
     setSeed: (seedHex: string) => Promise<void>;
 }>;
-export { APLD_APPLIED, APLD_ERROR, APLD_PENDING, apldFromStored, b64tob, btob64, btoh, CachedEntDB, checksumEntRevs, checksumSet, Clock, cmpBytes, crypto, Decoder, defaultPeekProgressEvery, eidCodec, encodeEntRev, Encoder, EntDBMemory, EntIDB, EntitiesQuery, EntityID, entStateManager, genSingletonEID, GroupID, hostHTTPTransport, htob, HTTPTransport, IDBStore, idleProgress, IEntDB, IEntity, isApldState, isPendingApply, isTerminalApplyFailure, IStore, MasterSeed, MemoryStore, normalizeTags, nullEntDB, nullStateManager, openDiplomaticClient, openEntDB, openIDBStore, revFromEntity, revFromHead, setApld, shouldEmitItemProgress, SingletonStateManager, StateManager, Status, SyncClient, TypedEventEmitter, useClient, useClientState, useClientXferState, useStateWatcher, useStateWatcherSuspense, useSyncOnResume, WorkerClient, };
-export type { ApldState, Applier, CachedEntDBOptions, EntDBMemoryOptions, HostHandle, HostStatsUpdate, IClient, ICrypto, IDeleteParams, IDiplomaticClientState, IEntRev, IHostConnectionInfo, IHostRow, IMessage, IMutateOp, IOp, IStateManager, IStoredMessage, IStoredMessageData, IStoredMessageWrite, ITransport, IUpdateParams, ListMsgsOpts, OpenDiplomaticClientMainOptions, OpenDiplomaticClientOptions, OpenDiplomaticClientWorkerOptions, OpenedDiplomaticClient, OpenEntDBOptions, ReconcileOpts, ReconcileReport, SyncProgressEvent, WorkerClientOptions, };
+export { APLD_APPLIED, APLD_ERROR, APLD_PENDING, apldFromStored, b64tob, btob64, btoh, CachedEntDB, checksumEntRevs, checksumSet, Clock, cmpBytes, crypto, Decoder, defaultPeekProgressEvery, eidCodec, encodeEntRev, Encoder, EntDBMemory, EntIDB, EntitiesQuery, EntityID, entStateManager, genSingletonEID, GroupID, hostHTTPTransport, htob, HTTPTransport, IDBStore, idleProgress, IEntDB, IEntity, isApldState, isLiveEnt, isPendingApply, isTerminalApplyFailure, isTombstone, IStore, MasterSeed, MemoryStore, normalizeTags, nullEntDB, nullStateManager, openDiplomaticClient, openEntDB, openIDBStore, revFromEntity, revFromHead, setApld, shouldEmitItemProgress, SingletonStateManager, StateManager, Status, SyncClient, TypedEventEmitter, useClient, useClientState, useClientXferState, useStateWatcher, useStateWatcherSuspense, useSyncOnResume, WorkerClient, };
+export type { ApldState, Applier, CachedEntDBOptions, EntDBMemoryOptions, HostHandle, HostStatsUpdate, IClient, ICrypto, IDeleteParams, IDiplomaticClientState, IEntRev, IEntRow, IHostConnectionInfo, IHostRow, IMessage, IMutateOp, IOp, IStateManager, IStoredMessage, IStoredMessageData, IStoredMessageWrite, ITombstone, ITransport, IUpdateParams, ListMsgsOpts, OpenDiplomaticClientMainOptions, OpenDiplomaticClientOptions, OpenDiplomaticClientWorkerOptions, OpenedDiplomaticClient, OpenEntDBOptions, ReconcileOpts, ReconcileReport, SyncProgressEvent, WorkerClientOptions, };