@tinycloud/courier 0.6.0-beta.33 → 0.6.0-beta.34

package/dist/watch.d.ts

@@ -12,6 +12,8 @@ export interface PendingWake {
     approvals?: WakeApproval[];
     firstSeenAt: number;
     lastSeenAt: number;
+    /** When an authority check first gave no verdict for this wake; cleared by a verdict. */
+    deferredSince?: number;
 }
 interface NoticeRetry {
     /** Six digits while dispatching, otherwise six dashes; independent of the display count. */
@@ -34,6 +36,15 @@ interface PauseEpisode extends NoticeRetry {
     /** Fixed-width saturating count of additional transitions represented by this slot. */
     repeats: string;
 }
+/**
+ * A peer whose authority checks give no verdict: since when, and once that lasts `DEFERRAL_LIMIT_MS`, the one notice
+ * (`eventId`) its human gets for this outage. A verdict ends the outage; a later one notifies again.
+ */
+interface UnverifiedPeer extends NoticeRetry {
+    since: number;
+    eventId: string;
+    notified: boolean;
+}
 /** Allocated only from our own thread/wake/pause records, never from incoming notice ids. */
 interface ThreadNoticeState {
     ourPaused: boolean;
@@ -75,7 +86,33 @@ export interface WatchState {
     noticeGlobalLog: number[];
     /** Every dispatch attempt, success or failure, per peer for the shared rolling-hour cap. */
     noticeLog: Record<string, number[]>;
+    /** Paired peers whose authority checks currently give no verdict. */
+    unverified: Record<string, UnverifiedPeer>;
+}
+/**
+ * What a watcher already knows and need not ask the node again, kept on this machine across runs: a `--once` loop
+ * starts fresh each time. Losing it only costs the calls it saves.
+ */
+export interface LocalWatchCache {
+    v: 1;
+    /** When wake claims were last pruned (hourly). */
+    claimsPrunedAt?: number;
+    /** When each peer's renewal marker was last read. */
+    markerReadAt: Record<string, number>;
+    /** Per peer, its `meta.json` keys already mirrored (create-only). Two peers may use the same name for us, so keys alone are ambiguous. */
+    metaMirrored: Record<string, string[]>;
+    /** Per peer, `thread/message` ids its receipts already list (receipts only grow). */
+    receipted: Record<string, string[]>;
+    /** Per peer, the identity (DID, space, session) its facts above were learned under; facts without one are dropped. */
+    identities: Record<string, PeerIdentity>;
+}
+export interface PeerIdentity {
+    did: string;
+    space: string;
+    session: string | null;
 }
+export declare const peerIdentity: (peer: StoredPeer) => PeerIdentity;
+export declare const sameIdentity: (a: PeerIdentity | undefined, b: PeerIdentity) => boolean;
 /** `tries`: notification dispatch attempts (max 3), or failed inform attempts (max 8). */
 export type OutboxItem = {
     id: string;
@@ -86,6 +123,7 @@ export type OutboxItem = {
     pauseId?: string;
     tries?: number;
     nextAttemptAt?: number;
+    deferredSince?: number;
 } | {
     id: string;
     kind: 'notify';
@@ -155,6 +193,11 @@ export interface WatchDeps {
     notificationHome?: string;
     /** D mode mirrors and receipts, then notifies without invoking a wake adapter. */
     notifyOnly?: boolean;
+    /** This machine's copy of what the watcher already knows (see `LocalWatchCache`). Default: none, kept in memory. */
+    localCache?: {
+        load(): LocalWatchCache | undefined;
+        save(cache: LocalWatchCache): void;
+    };
     /**
      * Who this watcher is, for wake claims. `profileId` is stable for this profile on this machine (a restart keeps it,
      * a second profile or machine differs); `pid` and `isAlive` tell a restarted watcher its predecessor is dead.
@@ -189,7 +232,6 @@ export declare class Watcher {
     private readonly profileId;
     private readonly pid;
     private readonly isAlive;
-    private lastClaimPrune;
     /** Set when another watcher is writing this profile's state: this one stops and `run` throws it. */
     private fatalError;
     /** Set once `run` is told to stop: nothing new is woken after that. */
@@ -197,8 +239,17 @@ export declare class Watcher {
     private onFatal;
     /** Etag of this agent's watch.json as this watcher last saw it: null = absent, undefined = unknown (fetch before writing). */
     private stateEtag;
+    /** Per `<peer handle>\n<peer task key>`: two peers may use the same name for us, so a key alone is ambiguous. */
     private readonly taskCache;
+    /** Peer keys whose value is over the batch cap: reported once and not read again by this process. */
+    private readonly tooLarge;
     private readonly metaMirrored;
+    private readonly markerReadAt;
+    private claimsPrunedAt;
+    /** Per peer, the identity the facts above were learned under: a peer that changed identity starts with none. */
+    private readonly factIdentity;
+    /** The local cache changed since it was last saved. */
+    private localDirty;
     private readonly syncing;
     /** Peers whose last sync did not finish: a cycle between full catch-ups lists only these again. */
     private readonly dirtyPeers;
@@ -215,6 +266,12 @@ export declare class Watcher {
     private readonly now;
     private readonly keys;
     constructor(deps: WatchDeps, opts?: WatchOptions);
+    /**
+     * Before using or learning facts about a peer: if the peer is now a different agent, space or session than the one
+     * the facts were learned under, they are dropped, so a new peer's delivery is never skipped on an old peer's facts.
+     */
+    private bindFacts;
+    private saveLocal;
     /**
      * Before TC-2917 every agent of the owner shared `me/state/`. On an agent's first start its own keys get a copy of
      * what concerns its own configured peers (eligible now or not): pause markers first, then watch.json, whose existence
@@ -222,7 +279,11 @@ export declare class Watcher {
      * keys are left in place.
      */
     private migrateLegacyState;
-    loadState(): Promise<void>;
+    /** `preloaded`: this agent's watch.json as just read (saves reading it twice at startup). */
+    loadState(preloaded?: {
+        value: WatchState;
+        etag: string | null;
+    }): Promise<void>;
     snapshot(): WatchState;
     /**
      * Serialised: callers mutate `this.state` inside `fn`, then it is written with if-match against the etag this
@@ -246,8 +307,8 @@ export declare class Watcher {
     private claimWake;
     /** Drops this run's own claim (best effort): a failed wake must not keep the thread from being woken. */
     private releaseClaim;
-    /** Claim markers are only needed while a double wake is possible; drop those older than two days. */
-    private pruneClaims;
+    /** Claim markers are only needed while a double wake is possible; once an hour, drop those older than two days. */
+    private pruneClaimsIfDue;
     /**
      * Serialises syncs per peer; a request that arrives mid-sync reruns once after it. `pausedListed`: the caller has
      * just listed the pause markers for this cycle, so the sync shares that listing instead of making its own.
@@ -263,6 +324,14 @@ export declare class Watcher {
      * a cached one: the 300 s schedule only bounds how soon an idle revocation is noticed. False once the peer is gone.
      */
     private authorized;
+    /**
+     * A check gave no verdict for this peer: the outage starts now if it isn't already running. Once it has lasted
+     * `DEFERRAL_LIMIT_MS`, the peer's human is told once (Naomi's TC-2951 ruling: imports keep retrying; wakes and informs
+     * deferred that long are dropped). Only configured paired peers allocate a record.
+     */
+    private noteUnverified;
+    /** A verdict ends the outage; a notice not yet sent for it is withdrawn. Called inside mutate. */
+    private endUnverified;
     /** The scheduled renewal and authority check for every peer; each peer's next sync also reads its renewal marker. */
     private checkAuthority;
     private syncPeer;