@interncom/diplomatic 0.4.4 → 0.5.0

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;
@@ -9,11 +9,13 @@ export declare class IDBMessageStore implements IMessageStore {
     add(messages: IStorableMessage[]): Promise<Status[]>;
     del(keys: Iterable<Hash>): Promise<void>;
     get(key: Hash): Promise<IStoredMessage | undefined>;
-    getMany(keys: Iterable<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/idb/uplds.d.ts

@@ -1,11 +1,11 @@
 import { Hash } from "../../shared/types";
-import { IUploadEntry, IUploadQueue } from "../../types";
+import { IUploadQueue } from "../../types";
 export declare class IDBUploadQueue implements IUploadQueue {
     db: IDBDatabase;
     constructor(db: IDBDatabase);
-    enq(host: string, entries: Iterable<IUploadEntry>): Promise<void>;
+    enq(host: string, hshs: Iterable<Hash>): Promise<void>;
     deq(host: string, hshs: Iterable<Hash>): Promise<void>;
-    list(host: string): Promise<IUploadEntry[]>;
+    list(host: string): Promise<Hash[]>;
     count(): Promise<number>;
     wipe(): 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 { 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;
@@ -9,11 +9,13 @@ export declare class MemoryMessageStore implements IMessageStore {
     add(messages: IStorableMessage[]): Promise<Status[]>;
     del(keys: Iterable<Hash>): Promise<void>;
     get(key: Hash): Promise<IStoredMessage | undefined>;
-    getMany(keys: Iterable<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/memory/uplds.d.ts

@@ -1,11 +1,10 @@
 import { Hash } from "../../shared/types";
-import { IUploadEntry, IUploadQueue } from "../../types";
+import { IUploadQueue } from "../../types";
 export declare class MemoryUploadQueue implements IUploadQueue {
-    /** host → (hashHex → bodyLen) */
-    queue: Map<string, Map<string, number>>;
-    enq(host: string, entries: Iterable<IUploadEntry>): Promise<void>;
+    queue: Map<string, Set<string>>;
+    enq(host: string, hshs: Iterable<Hash>): Promise<void>;
     deq(host: string, hshs: Iterable<Hash>): Promise<void>;
-    list(host: string): Promise<IUploadEntry[]>;
+    list(host: string): Promise<Hash[]>;
     count(): Promise<number>;
     wipe(): Promise<void>;
 }

package/dist/web/sync.d.ts

@@ -62,13 +62,8 @@ export declare function openPulled<Handle extends HostHandle>(store: IStore<Hand
 export declare function deqDownloadsForHeadHashes<Handle extends HostHandle>(store: Pick<IStore<Handle>, "downloads">, hashes: Iterable<Hash>, crypto: ICrypto): Promise<void>;
 /** Discover unseen bags and enqueue download work; advance host lastSeq. */
 export declare function syncPeek<Handle extends HostHandle>({ conn, store, enclave, host, crypto, onProgress, peekProgressEvery, peekConcurrency, }: ISyncParams<Handle>): Promise<Status>;
-/**
- * Soft max plaintext body bytes per messages.getMany (IDB load bound).
- * Sealed bags are larger; push still uses maxPushBytes on bag size.
- */
-export declare const defaultMaxGetBodyBytes: number;
 /** 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 syncPush<Handle extends HostHandle>({ conn, store, host, maxPushBytes, onProgress }: ISyncParams<Handle>): Promise<Status>;
 /**
  * Pull + open for one host, depth-1 pipelined:
  *   await pull(i); start pull(i+1); open(i); afterOpen? (exec)

package/dist/web/types.d.ts

@@ -45,16 +45,10 @@ export interface IHostStore<Handle extends HostHandle> {
     wipe: () => Promise<void>;
     touch: (label: string, seq: number) => Promise<void>;
 }
-/** Pending upload: archive key + plaintext body size for IDB get batching. */
-export interface IUploadEntry {
-    hash: Hash;
-    /** Body byte length (0 if unknown / empty). */
-    bodyLen: number;
-}
 export interface IUploadQueue {
-    enq: (host: string, entries: Iterable<IUploadEntry>) => Promise<void>;
+    enq: (host: string, hshs: Iterable<Hash>) => Promise<void>;
     deq: (host: string, hshs: Iterable<Hash>) => Promise<void>;
-    list: (host: string) => Promise<IUploadEntry[]>;
+    list: (host: string) => Promise<Hash[]>;
     count: () => Promise<number>;
     wipe(): Promise<void>;
 }
@@ -80,10 +74,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;
@@ -93,19 +95,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;
@@ -115,34 +121,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>;
-    /**
-     * Batch load by archive keys (one store round-trip when possible).
-     * Result aligned with input order; missing keys are undefined.
-     */
-    getMany: (keys: Iterable<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> {