@cello-protocol/daemon 0.0.225 → 0.0.227

package/dist/retry-queue.d.ts

@@ -1,203 +0,0 @@
-/**
- * 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

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