@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/retry-queue.d.ts

@@ -0,0 +1,203 @@
+/**
+ * CELLO Daemon — RetryQueue
+ *
+ * Per-session FIFO queue of messages awaiting delivery. When a send over a
+ * session node stream fails, the message envelope is added to the queue. When
+ * the peer reconnects, the daemon drains the queue in FIFO order.
+ *
+ * Persistence: SQLCipher table `retry_queue`.
+ * Cap: 1,000 messages per session. On overflow the OLDEST is evicted.
+ *
+ * FIFO invariant: a drain HALTS on the first failure. M3 must never arrive before M2.
+ */
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+/** Per-session cap. On overflow the OLDEST entry is evicted. */
+export declare const RETRY_QUEUE_CAP = 1000;
+export interface RetryQueueEntry {
+    sessionId: string;
+    nonceHex: string;
+    contentBlob: Uint8Array;
+    queuedAt: number;
+    attempts: number;
+    position: number;
+}
+/** Result of a resend attempt during drain. */
+export type ResendResult = {
+    delivered: true;
+} | {
+    delivered: false;
+    error: string;
+};
+export type ResendFn = (contentBlob: Uint8Array) => Promise<ResendResult>;
+/**
+ * An un-acked content entry awaiting a `persisted` delivery ACK. Stored in the SAME retry_queue
+ * table (awaiting_ack = 1) — no second table. Drains to the relay store-and-forward queue (park
+ * target) instead of direct-P2P resend.
+ */
+export interface AwaitingContentEntry {
+    /** The OWNING agent — the original sender. Two of the operator's agents can hold awaiting content
+     *  for the SAME session_id on one daemon (loopback), so the entry is keyed by (agentId, sessionId),
+     *  not sessionId alone.
+     *  This is the STABLE agent_id, never the mutable agent_name — a retire frees the name for reuse,
+     *  and awaiting content must never be handed to the keypair that inherited it. */
+    agentId: string;
+    sessionId: string;
+    contentHashHex: string;
+    contentBlob: Uint8Array;
+    /**
+     * 034-CARRYLEAF — the AUTHOR's signature over `structure1Cbor`, and the leaf DOMAIN.
+     *
+     * A message re-parked after a restart must reach its recipient in a shape they can WITNESS on the
+     * sender's behalf, or a crash re-opens the withholding hole on the mailbox route: the recipient
+     * gets the content, cannot prove the ordering claim to the relay, and the message can never enter
+     * a receipt. Both are persisted for the same reason the ordering record is — the in-memory copy
+     * is gone by the time this row is read.
+     */
+    structure1Signature?: Uint8Array;
+    leafKind?: number;
+    /** M12-P12 (review F2): the relay's signed ordering record, carried so a RE-park is self-ordering
+     *  exactly like the live park. Without it `recoverParkedFromRelay` falls back to the in-memory
+     *  #witnessedSeq map, which is empty after a receiver restart — the content then appends at its
+     *  ARRIVAL index instead of its witnessed sequence, and the session tree diverges at seal.
+     *  Nullable: rows written before this column existed, and the agent-less direct-retry rows,
+     *  legitimately have none. */
+    /**
+     * `DOD-M15-SEALWIRE-1` part B2b — WHICH content-hash algorithm `contentHashHex` was produced
+     * under, so a RE-park names the same one the original frame did.
+     *
+     * The crash-backstop producer has no other source: it runs at the next boot, the frame is long
+     * gone, and re-deriving it from the session's current row would be a fact about what THIS side
+     * holds now, not about how this message was actually hashed.
+     *
+     * Nullable, and `undefined` is meaningful rather than a gap — it is what `resolveContentHashAlg`
+     * reads as "predates the field", the only value meaning legacy. Never defaulted to `"sha256"`.
+     */
+    contentHashAlg?: string;
+    structure1Cbor?: Uint8Array;
+    structure2Cbor?: Uint8Array;
+    queuedAt: number;
+    position: number;
+}
+/** Result of a park attempt during the awaiting-ACK drain. */
+/**
+ * ⚠️ `retryAfterMs` on the FAILURE member — `DOD-M15-RELAYABUSE-1`, review HIGH-2.
+ *
+ * The relay tells us exactly when a throttle clears, and until now only the LIVE send path could
+ * hear it: the drain path returned `{parked:false, error}` and dropped the number on the floor. With
+ * a backlog larger than one window that is the whole feature undone — the relay allows N per window,
+ * the drain deposits N, every remaining item is refused carrying a fresh delay, and all of them fall
+ * back to waiting for an unrelated reconnect. Which is precisely the condition the retry timer was
+ * added to fix.
+ *
+ * It sits on the failure member for the same reason `sequenceNumber` does elsewhere: a refusal still
+ * carries information the caller needs, and dropping it because the operation failed is how a
+ * value ends up with no reader.
+ */
+export type ParkResult = {
+    parked: true;
+} | {
+    parked: false;
+    error: string;
+    retryAfterMs?: number;
+};
+export type ParkFn = (entry: AwaitingContentEntry) => Promise<ParkResult>;
+export declare class RetryQueue {
+    #private;
+    constructor(db: DaemonDatabase, logger: Logger);
+    /**
+     * Load all retry queue entries from SQLCipher into memory.
+     * Must complete BEFORE the IPC socket opens.
+     */
+    loadFromDb(): void;
+    enqueue(sessionId: string, nonce: Uint8Array, contentBlob: Uint8Array): void;
+    /**
+     * Drain the session's retry queue in FIFO order.
+     * Halts immediately on first failure (FIFO invariant: no out-of-order delivery).
+     * Returns the number of successfully delivered messages.
+     */
+    drainSession(sessionId: string, sendFn: ResendFn): Promise<number>;
+    /**
+     * Remove the DIRECT-resend entries (awaiting_ack = 0) of a session that can never drain again.
+     *
+     * Removal is authorised by ONE thing: the session reached a status from which no resend can
+     * succeed. Never by age — "old" is not "undeliverable", and an age sweep discards live content
+     * on a slow link (the DOD-SESSION-REAP-1 rule).
+     *
+     * Awaiting-ACK rows are deliberately left alone. They drain through `drainAwaitingToPark`, which
+     * the startup flush really calls, so they are not stranded; their terminal disposition is a
+     * separate concern. Deleting them here would discard content that path still owes delivery on.
+     *
+     * @returns how many entries were removed — 0 is the normal case and is silent.
+     */
+    reapTerminalSession(sessionId: string, terminalStatus: "sealed" | "abandoned"): number;
+    /**
+     * DOD-RETRYQ-STRAND-1: reconcile at startup. The terminal-transition hook only covers sessions
+     * that go terminal while THIS daemon is running. A session that was already sealed/abandoned
+     * before boot never transitions again — `cello_close_session` returns `already_abandoned`
+     * without reaching `abandonSession` — so its rows would strand forever with no path that could
+     * ever clear them. That is the shape of the row found on the live daemon.
+     *
+     * Still evidence-gated: the session's terminal status is the evidence, read from the DB. Nothing
+     * here consults age.
+     *
+     * @returns total entries reaped across all already-terminal sessions.
+     */
+    reapAlreadyTerminalSessions(): number;
+    /** Total retry queue depth across all sessions. */
+    getTotalDepth(): number;
+    /** Retry queue depth for a specific session. */
+    getSessionDepth(sessionId: string): number;
+    /** Get all entries for a session (FIFO ordered, defensive copy). Used by drain_session IPC. */
+    getSessionEntries(sessionId: string): RetryQueueEntry[];
+    /**
+     * Record un-acked content awaiting a `persisted` delivery ACK. Persisted to the SAME
+     * retry_queue table (awaiting_ack = 1) so a crash before the relay park confirms is
+     * recoverable at startup. Idempotent on (agentId, sessionId, contentHash).
+     */
+    /**
+     * Returns TRUE only when this copy is actually queued. M12-P13 (review HIGH-1): the dedupe branch
+     * below DROPS the content, and the caller now commits a hash-chain leaf on the strength of this
+     * answer — so "I dropped it" must be reportable, not merely logged. A void return made the drop
+     * indistinguishable from a successful enqueue at the call site, which is how a leaf could be
+     * committed for content that no longer existed anywhere.
+     */
+    /**
+     * `contentHashAlg` — `DOD-M15-SEALWIRE-1` part B2b. WHICH algorithm `contentHash` was produced
+     * under, carried because the crash-backstop park producer has NO OTHER SOURCE for it: it runs at
+     * the next boot, long after the frame is gone, and re-parking under the wrong algorithm gets the
+     * message refused by the recipient and re-pulled forever.
+     *
+     * Optional and stored as NULL when absent, never defaulted to the literal `"sha256"` — absent is
+     * what `resolveContentHashAlg` reads as "predates the field", and that distinction is the one B1
+     * and B2a each had to restore after it was collapsed.
+     */
+    enqueueAwaitingContent(agentId: string, sessionId: string, contentHash: Uint8Array, contentBlob: Uint8Array, structure1Cbor: Uint8Array | undefined, structure2Cbor: Uint8Array | undefined, contentHashAlg: string | undefined, structure1Signature?: Uint8Array, leafKind?: number): boolean;
+    /** Remove an awaiting-ACK entry once its `persisted` ACK arrives. */
+    markContentAcked(agentId: string, sessionId: string, contentHash: Uint8Array): void;
+    /** Awaiting-ACK depth for a session (un-acked content count). */
+    getAwaitingDepth(agentId: string, sessionId: string): number;
+    /** All (agent, session) pairs that currently hold awaiting-ACK content (for the startup flush). */
+    getAwaitingSessions(): Array<{
+        agentId: string;
+        sessionId: string;
+    }>;
+    /**
+     * Drain a session's awaiting-ACK content to the relay park target. Each item is
+     * independent — unlike the direct FIFO resend, a park failure does NOT halt the rest;
+     * the failed item stays queued for the next reconnect / startup flush. Returns the
+     * number of entries successfully parked.
+     */
+    drainAwaitingToPark(agentId: string, sessionId: string, parkFn: ParkFn, 
+    /**
+     * DOD-M15-RELAYABUSE-1 review HIGH-2: called ONCE per pass with the largest retry delay any
+     * refusal in that pass reported, or never if none did.
+     *
+     * ⚠️ Per PASS, not per item, and that is the whole point. A backlog larger than one rate-limit
+     * window produces a refusal per remaining item, each carrying its own delay; scheduling on each
+     * would be one timer per message — the flood the limiter exists to prevent, generated by the
+     * code that respects it. The largest delay is the one that is actually true for the window.
+     */
+    onRetryAfter?: (retryAfterMs: number) => void): Promise<number>;
+}
+//# sourceMappingURL=retry-queue.d.ts.map

package/dist/retry-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-queue.d.ts","sourceRoot":"","sources":["../src/retry-queue.ts"],"names":[],"mappings":"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"}