@interncom/diplomatic 0.4.5 → 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;
@@ -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

@@ -74,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;
@@ -87,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;
@@ -109,29 +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>;
     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> {