@interncom/diplomatic 0.8.0 → 0.8.2

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

@@ -1,12 +1,13 @@
 import { Status } from "../../shared/consts";
 import { IHostConnectionInfo, IHostMetadata } from "../../shared/types";
-import type { IHostRow, IHostStore } from "../../types";
+import type { HostStatsUpdate, IHostRow, IHostStore } from "../../types";
 export declare class IDBHostStore implements IHostStore<URL> {
     db: IDBDatabase;
     constructor(db: IDBDatabase);
     add(info: IHostConnectionInfo<URL>): Promise<void>;
     private put;
     touch(label: string, seq: number): Promise<void>;
+    recordStats(label: string, u: HostStatsUpdate): Promise<void>;
     get(label: string): Promise<IHostRow<URL> | undefined>;
     set(label: string, meta: IHostMetadata): Promise<Status.Success | Status.NotFound | Status.DatabaseError>;
     del(label: string): Promise<void>;

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 { ApldState, IMessageStore, IStorableMessage, IStoredMessage } from "../../types";
+import { ApldState, IMessageStore, IStorableMessage, IStoredMessage, ListMsgsOpts } from "../../types";
 export declare class IDBMessageStore implements IMessageStore {
     private crypto;
     db: IDBDatabase;
@@ -10,7 +10,8 @@ export declare class IDBMessageStore implements IMessageStore {
     del(keys: Iterable<Hash>): Promise<void>;
     get(key: Hash): Promise<IStoredMessage | undefined>;
     has(key: Hash): Promise<boolean>;
-    list(apld?: ApldState): Promise<IStoredMessage[]>;
+    list(opts?: ListMsgsOpts): Promise<IStoredMessage[]>;
+    count(apld?: ApldState): Promise<number>;
     listKeys(): Promise<Hash[]>;
     last(eid: EntityID): Promise<IStoredMessage | undefined>;
     markApplied(keys: Iterable<Hash>): Promise<void>;

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

@@ -1,10 +1,13 @@
 import { Status } from "../../shared/consts";
 import { HostHandle, IHostConnectionInfo, IHostMetadata } from "../../shared/types";
-import type { IHostRow, IHostStore } from "../../types";
+import type { HostStatsUpdate, IHostRow, IHostStore } from "../../types";
 export declare class MemoryHostStore<Handle extends HostHandle> implements IHostStore<Handle> {
     hosts: Map<string, IHostRow<Handle>>;
+    /** Serializes recordStats so concurrent peeks do not drop bag/dupe deltas. */
+    private statsChain;
     add(info: IHostConnectionInfo<Handle>): Promise<void>;
     touch(label: string, seq: number): Promise<void>;
+    recordStats(label: string, u: HostStatsUpdate): Promise<void>;
     get(label: string): Promise<IHostRow<Handle> | undefined>;
     set(label: string, meta: IHostMetadata): Promise<Status.Success | Status.NotFound>;
     del(label: string): Promise<void>;

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

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

package/dist/web/sync.d.ts

@@ -4,7 +4,7 @@ import { Enclave } from "./shared/crypto/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";
+import { IDownloadMessage, IHostRow, IMsgParts, IStore, type IStoredMessageWrite, type ReconcileOpts, type ReconcileResult } 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;
@@ -82,3 +82,13 @@ export declare function msg2StoredMsgData({ head, body }: IMsgParts): IStoredMes
  * `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>;
+/**
+ * Full host inventory (PEEK from seq 0): set absolute numBags/numDupes/lastSeq,
+ * and optionally enqueue downloads (msgs on host missing locally) and/or
+ * uploads (local msgs missing on host). Does not pull/push network beyond
+ * peek — caller should sync() to drain queues.
+ *
+ * lastSeq is set to the max bag seq in the inventory (0 if empty), including
+ * rewind when the host has fewer bags than a prior cursor believed.
+ */
+export declare function reconcileHost<Handle extends HostHandle>(params: ISyncParams<Handle>, opts?: ReconcileOpts): Promise<ValStat<ReconcileResult>>;

package/dist/web/types.d.ts

@@ -36,7 +36,39 @@ export interface ISeedStore {
 }
 export interface IHostRow<Handle extends HostHandle> extends IHostConnectionInfo<Handle>, Partial<IHostMetadata> {
     lastSeq: number;
+    /**
+     * Bags known on this host (full reconcile sets absolute; incremental peek
+     * adds newly seen seqs).
+     */
+    numBags: number;
+    /**
+     * Extra bags beyond one per msg (`Σ max(0, bags_for_msg − 1)`). Absolute on
+     * reconcile; +delta on peek when a new duplicate bag for a known msg is seen.
+     */
+    numDupes: number;
 }
+/**
+ * Atomic host cursor + bag/dupe stats update (one store transaction).
+ * Absolute fields replace; deltas add. `lastSeq` only advances; use
+ * `setLastSeq` for a full-inventory absolute cursor (reconcile).
+ */
+export type HostStatsUpdate = {
+    /** New lastSeq if greater than current (incremental peek/push). */
+    lastSeq?: number;
+    /** Absolute lastSeq, including rewind (full inventory). */
+    setLastSeq?: number;
+    /** Absolute bag count (full inventory). */
+    numBags?: number;
+    /** Absolute dupe count (full inventory). */
+    numDupes?: number;
+    /** Count of newly peeked bags to add to numBags. */
+    bagDelta?: number;
+    /**
+     * Count of newly seen extra bags for a msg already on the host (duplicate
+     * bags for the same msg) to add to numDupes.
+     */
+    dupeDelta?: number;
+};
 export interface IHostStore<Handle extends HostHandle> {
     add: (host: IHostConnectionInfo<Handle>) => Promise<void>;
     get: (label: string) => Promise<IHostRow<Handle> | undefined>;
@@ -45,7 +77,40 @@ export interface IHostStore<Handle extends HostHandle> {
     list: () => Promise<Iterable<IHostRow<Handle>>>;
     wipe: () => Promise<void>;
     touch: (label: string, seq: number) => Promise<void>;
+    /**
+     * Apply lastSeq / numBags / numDupes in one transaction so counts do not
+     * drift vs the cursor under concurrent peek/push.
+     */
+    recordStats: (label: string, u: HostStatsUpdate) => Promise<void>;
 }
+/** Options for {@link IClient.reconcile}. */
+export type ReconcileOpts = {
+    /** Enqueue downloads for msgs on host missing locally. Default true. */
+    pull?: boolean;
+    /** Enqueue uploads for local archive msgs missing on host. Default false. */
+    push?: boolean;
+    /**
+     * After inventory, run {@link IClient.sync} to drain upload/download queues.
+     * Default true. Pass false for inventory-only (counts + checksum).
+     */
+    sync?: boolean;
+};
+/** Internal result of a full host inventory (not the public client API). */
+export type ReconcileResult = {
+    /**
+     * Set-checksum of distinct msgs on the host (archive keys; same construction
+     * as {@link IClient.msgcheck}). Ephemeral — not stored on the host row.
+     */
+    msgcheck: Hash;
+    bagCount: number;
+    /** Distinct msgs among bags (dup bags for the same msg count once). */
+    uniqueMsgs: number;
+    numDupes: number;
+    /** Msgs on host not in local archive. */
+    missingLocal: number;
+    /** Local archive msgs not seen on host. */
+    missingHost: number;
+};
 export interface IUploadQueue {
     enq: (host: string, hshs: Iterable<Hash>) => Promise<void>;
     deq: (host: string, hshs: Iterable<Hash>) => Promise<void>;
@@ -147,18 +212,35 @@ export declare function isTerminalApplyFailure(st: Status): boolean;
  * 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>;
+/**
+ * Options for archive list / client diagnostics.
+ * `body` defaults to **true**. Pass `body: false` for heads + apld + err only.
+ */
+export type ListMsgsOpts = {
+    /** Filter by apply lifecycle; omit for all archive rows. */
+    apld?: ApldState;
+    /**
+     * Include msg bodies and derive `head.hsh` from them.
+     * Default `true`. Pass `false` to omit body and `hsh` (cheaper diagnostics);
+     * `head.len` still reflects stored size.
+     */
+    body?: boolean;
+};
+export declare function toStoredMessage(hash: Hash, data: IStoredMessageData, crypto: ICrypto, opts?: {
+    body?: boolean;
+}): 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 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 archive rows. Filter with `apld` (e.g. {@link APLD_ERROR}).
+     * Bodies included by default; pass `body: false` to omit.
      */
-    list: (apld?: ApldState) => Promise<IStoredMessage[]>;
+    list: (opts?: ListMsgsOpts) => Promise<IStoredMessage[]>;
+    /** Count archive rows; optional apld filter (IDB index when available). */
+    count: (apld?: ApldState) => Promise<number>;
     /** Archive keys only (head hashes). Prefer over {@link list} for checksums. */
     listKeys: () => Promise<Hash[]>;
     last: (eid: EntityID) => Promise<IStoredMessage | undefined>;
@@ -219,6 +301,24 @@ export interface IClient<Handle extends HostHandle> {
      * Key encoding (e.g. b64 in IDB) is independent of this definition.
      */
     msgcheck(): Promise<Hash>;
+    /**
+     * List local archive rows for diagnostics (failed apply, pending drain, dump).
+     * Bodies included by default; pass `body: false` for lighter listings.
+     */
+    listMsgs(opts?: ListMsgsOpts): Promise<IStoredMessage[]>;
+    /**
+     * Count archive rows; optional apld filter.
+     * Prefer over list+length for badges.
+     */
+    countMsgs(apld?: ApldState): Promise<number>;
+    /**
+     * Full host inventory (peek from seq 0): set numBags/numDupes/lastSeq on the
+     * host row; optionally enqueue downloads (`pull`) and/or uploads (`push`).
+     * Returns ephemeral host msg checksum (distinct msgs on host; same as
+     * {@link msgcheck}) for UI comparison with local archive. Call
+     * {@link sync} to drain queues. Read counts via {@link hosts}.
+     */
+    reconcile(hostLabel: string, opts?: ReconcileOpts): Promise<ValStat<Hash>>;
     wipe(): Promise<void>;
     import(file: File): Promise<Status>;
     export(filename: string, extension?: string): Promise<Status>;

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

@@ -1,8 +1,8 @@
 import { IClock } from "../shared/clock";
 import { Status } from "../shared/consts";
 import type { EntityID, Hash, 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";
+import { type ValStat } from "../shared/valstat";
+import type { ApldState, IClient, IDiplomaticClientState, IDiplomaticClientXferState, IHostRow, IStateEmitter, IStore, IStoredMessage, ListMsgsOpts, ReconcileOpts } from "../types";
 /**
  * Options for attaching to an app-owned sync Worker.
  *
@@ -116,6 +116,14 @@ export declare class WorkerClient implements IClient<URL> {
     rebuild(options?: {
         checkHost?: boolean;
     }): Promise<Status>;
+    /** Shared message IDB on main — no worker RPC. */
+    listMsgs(opts?: ListMsgsOpts): Promise<IStoredMessage[]>;
+    countMsgs(apld?: ApldState): Promise<number>;
+    /**
+     * Full host inventory on the worker (network + crypto off main).
+     * Returns ephemeral host msg checksum; host row stats in shared IDB.
+     */
+    reconcile(hostLabel: string, opts?: ReconcileOpts): Promise<ValStat<Hash>>;
     /** Archive checksum via worker (listKeys + sort + blake3 off main). */
     msgcheck(): Promise<Hash>;
     /**

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

@@ -38,6 +38,13 @@ export type WorkerCmd = {
     id: number;
     op: "rebuild";
     checkHost?: boolean;
+} | {
+    id: number;
+    op: "reconcile";
+    hostLabel: string;
+    pull?: boolean;
+    push?: boolean;
+    sync?: boolean;
 } | {
     id: number;
     op: "msgcheck";