@tinycloud/courier 0.2.0-beta.38 → 0.2.0-beta.40

package/dist/watch.d.ts

@@ -13,6 +13,38 @@ export interface PendingWake {
     firstSeenAt: number;
     lastSeenAt: number;
 }
+interface NoticeRetry {
+    /** Six digits while dispatching, otherwise six dashes; independent of the display count. */
+    dispatchArrivals: string;
+    tries: number;
+    nextAttemptAt: number;
+    logged: boolean;
+}
+type NeedsKind = 'message' | 'approval';
+interface NeedsSlot extends NoticeRetry {
+    threadId: string;
+    eventId: string;
+    count: string;
+    firstSeenAt: string;
+    arrivalFirstSeenAt: string;
+}
+interface PauseEpisode extends NoticeRetry {
+    kind: '' | 'paused' | 'peer-paused';
+    eventId: string;
+    /** Fixed-width saturating count of additional transitions represented by this slot. */
+    repeats: string;
+}
+/** Allocated only from our own thread/wake/pause records, never from incoming notice ids. */
+interface ThreadNoticeState {
+    ourPaused: boolean;
+    peerPaused: boolean;
+    lastPeerNoticeId: string;
+    lastNoticeSentAt: string;
+    ourMarkerId: string;
+    episodes: [PauseEpisode, PauseEpisode];
+    informPending: boolean;
+    informText: string;
+}
 export interface WatchState {
     v: 1;
     /** Keyed `<peer>/<threadId>`. */
@@ -24,21 +56,34 @@ export interface WatchState {
     wakes: Record<string, number[]>;
     /** Threads this watcher has seen paused; a marker that vanishes from this list means the human resumed it. */
     paused: string[];
+    /** Failed wake count and completion-based backoff, retained across watcher restarts. */
+    wakeRetries: Record<string, {
+        failures: number;
+        nextAttemptAt: number;
+    }>;
+    approvalRetries: Record<string, {
+        failures: number;
+        nextAttemptAt: number;
+    }>;
     /** Posts and notifications that must happen exactly-ish once and survive a restart (retried until they succeed). */
     outbox: OutboxItem[];
     held: Record<string, HeldBacklog>;
-    /** UTC day of the last notification per kind/peer/thread: one of each kind per day. */
-    peerPausedDay: Record<string, number>;
-    /** Times of recent notifications per peer, for the shared per-hour cap. */
+    /** One fixed record per locally known thread. Peer ids are values, never keys. */
+    threadNotices: Record<string, ThreadNoticeState>;
+    /** Two coalescing needs-you slots per locally paired peer, allocated only from local configuration. */
+    peerNotices: Record<string, Record<NeedsKind, NeedsSlot>>;
+    noticeGlobalLog: number[];
+    /** Every dispatch attempt, success or failure, per peer for the shared rolling-hour cap. */
     noticeLog: Record<string, number[]>;
 }
-/** `tries` counts failed attempts; an item that keeps failing is dropped (see `MAX_OUTBOX_TRIES`). */
+/** `tries`: notification dispatch attempts (max 3), or failed inform attempts (max 8). */
 export type OutboxItem = {
     id: string;
     kind: 'inform';
     peer: string;
     threadId: string;
     text: string;
+    pauseId?: string;
     tries?: number;
     nextAttemptAt?: number;
 } | {
@@ -87,12 +132,12 @@ export interface WatchDeps {
     wake: Waker;
     log: WatchLog;
     /** Posts the `thread-paused` inform to a peer (own space, `to/<peer>/threads/<id>/msg/`). Default: nothing. */
-    postInform?(peer: string, threadId: string, text: string): Promise<void>;
+    postInform?(peer: string, threadId: string, text: string, pauseId?: string): Promise<void>;
     /** Tells this side's human without a model (desktop notification or operator command). Default: log only. */
     notify?: Notifier;
     /** Local bounded notification log; omitted by library callers that want no disk output. */
     notificationHome?: string;
-    /** D mode: mirror/receipt and notify the human, never invoke the wake adapter or spend its budget. */
+    /** D mode mirrors and receipts, then notifies without invoking a wake adapter. */
     notifyOnly?: boolean;
     /**
      * Who this watcher is, for wake claims. `profileId` is stable for this profile on this machine (a restart keeps it,
@@ -121,7 +166,6 @@ export declare class Watcher {
     private pausedKeys;
     /** Serialises everything that reads or writes pause markers, so a stale listing cannot drop a pause just written. */
     private pausedLock;
-    private readonly wakeFailures;
     private readonly outboxBusy;
     private approvalsAgain;
     /** Unique to this run: a claim with this id is this process's own. */
@@ -172,6 +216,8 @@ export declare class Watcher {
     /** Serialises syncs per peer; a request that arrives mid-sync reruns once after it. */
     sync(peer: StoredPeer, via: Via): Promise<void>;
     private syncPeer;
+    /** Only locally authored meta/messages/tasks, or a local wake/pause witness, establish a known thread. */
+    private syncKnownThreads;
     private mirrorCreate;
     /**
      * meta.json is immutable (create-only); tasks are mutable, so copy the latest until they are terminal. Runs after
@@ -197,8 +243,26 @@ export declare class Watcher {
     private exclusive;
     /** Called inside `mutate`: parks a message that arrived while its thread is paused (bounded). */
     private hold;
-    /** Called inside `mutate`: queues an inform or notification; the outbox is bounded, the oldest item goes first. */
+    /** Two episode values per known thread. Additional transitions coalesce, without allocating another slot. */
+    private queueEpisode;
+    /** Only the paired handles in our local configuration allocate needs-you state. */
+    private syncNoticePeers;
+    /** Bounded values only: a later delivery updates the same paired-peer slot. Called inside mutate. */
+    private queueNeeds;
+    private noticeSlot;
+    private rememberNotice;
+    /** Earliest rolling-hour retry under the global allowance and each paired peer's share. */
+    private noticeRateDeadline;
+    /** -1 appends; a nonnegative index yields that place; undefined leaves the pending slot alone. */
+    private admissionIndex;
+    /** Queue places can yield; the two fixed episode records retain all retry metadata. */
     private enqueue;
+    private outboxCandidates;
+    /** Admit local work first, allowing eligible peers to pass deferred entries in a full queue. */
+    private fillOutbox;
+    private fairOutbox;
+    /** Completion matches both the fixed slot and episode ULID; another queued episode is independent. */
+    private finishOutbox;
     /**
      * Markers under me/state/paused/ are the truth. A marker that disappeared means the human resumed: the budget starts
      * over and what arrived meanwhile wakes the agent once. Serialised, so overlapping calls never apply a stale listing.
@@ -206,7 +270,7 @@ export declare class Watcher {
     syncPaused(): Promise<void>;
     /** State that only matters for a day or an hour is dropped, so it cannot grow without bound. */
     private pruneState;
-    /** Informs and notifications queued in state; failures back off (1, 2, 4 ... 15 minutes) and give up after MAX_OUTBOX_TRIES. */
+    /** Informs and notifications queued in state; failures back off (1, 2, 4 ... 15 minutes) and give up after 3 notification attempts or 8 inform failures. */
     private runOutbox;
     pollOnce(via: Via): Promise<void>;
     /**