@cello-protocol/daemon 0.0.183 → 0.0.185

package/dist/submission-retry.d.ts

@@ -0,0 +1,208 @@
+/**
+ * DOD-M15-ENDORSE-RETRY-1 — a sealed submission survives the directory node going away.
+ *
+ * An operator mints a trust signal, the one directory node this daemon holds a signaling stream to
+ * is down or restarting, and the command fails and it is over: nothing queues the submission,
+ * nothing retries it, and the operator has to notice and run it again. The consortium has three
+ * nodes, and surviving one of them being unavailable is the entire reason there are three.
+ *
+ * THIS IS THE RETRY, NOT THE ROUTING, AND THAT DISTINCTION IS RULED. `sendSealedSubmission` says so
+ * in its own header: the daemon holds ONE signaling stream, registration already works this way
+ * (the client sends to the connected node and the DIRECTORY fans out), and inventing a client-side
+ * multi-node write here would duplicate the SignalingManager's reconnect. So the failover mechanism
+ * is that existing reconnect — this module never chooses a node, never holds an endpoint, and never
+ * learns which node answered. It waits to be told the stream is up again and sends the same bytes.
+ *
+ * WHY A RETRY IS SAFE, and it is the load-bearing fact for the whole design: `submission_id` is
+ * sha256 of the SIGNED PLAINTEXT body, so the same submission produces the same id however many
+ * times it is sent. A node stores it once (`ON CONFLICT DO NOTHING` on the id) and the portal mints
+ * once (`processed_submissions`, checked before the mint path). Nothing here may ever re-COMPOSE a
+ * submission: the sealed bytes are captured at compose time and re-sent verbatim, because a re-seal
+ * is randomised and a re-compose could pick up a different `issued_at` — which changes the id, and
+ * a changed id is a second endorsement rather than a retry.
+ *
+ * SERIAL AND STAGGERED, on the `RestartSealResolver`'s pattern, and one of its lessons is carried
+ * over wholesale: a refusal that is a precondition OF OURS is not a verdict on the submission, so it
+ * must not spend the attempt budget. There the population was `standing_receiver_unavailable` on a
+ * fresh boot; here it is a signaling stream that is reconnecting. Production turns that stream over
+ * roughly every 70 seconds, so charging each reconnect an attempt would burn a five-attempt budget
+ * in six minutes and give up on a submission whose only problem was that the network moved.
+ *
+ * IN MEMORY, FOR THE LIFE OF THE PROCESS, and stated rather than implied. The queue holds sealed
+ * ciphertext, and persisting it would mean a new table, a client-side migration, and a blob at rest
+ * whose retention outlives the intake key it is sealed to. A daemon restart therefore loses the
+ * pending retries — the operator sees them disappear from `cello_attestations_issued` rather than
+ * seeing a lie, they are NAMED in the log on the way out (`retry.dropped_on_shutdown`), and
+ * re-submitting is safe by the same content-derived id.
+ *
+ * THE INTAKE KEY IS CHECKED BY THE CALLER, not assumed here. An earlier version of this paragraph
+ * asserted that the retry window "is far shorter than any manifest validity window, so a queued
+ * blob cannot outlive the intake key it was sealed to" — which is only true when the manifest has
+ * more than a window left at compose time. The enqueue site in `daemon.ts` holds the manifest and
+ * refuses to hold a submission whose intake key would expire inside the window; see
+ * `DEFAULT_RETRY_WINDOW_MS` below for what goes wrong when nothing checks.
+ */
+import type { SubmissionOp } from "@cello-protocol/protocol-types";
+import type { SendSubmissionResult, SubmissionSendFailure } from "./signal-submission.js";
+import type { Logger } from "./types.js";
+export declare function isRetryableSendFailure(reason: SubmissionSendFailure): boolean;
+/**
+ * Why a retry stopped. FOUR names, because they lead to four different operator actions and this is
+ * the field a machine consumer branches on.
+ *
+ * `refused_by_node` and `agent_unloaded` exist because of review H3: a refusal arriving on retry
+ * attempt 1 used to be stamped `attempts_exhausted` with `attempts: 0` printed beside it. The
+ * node's own words survived in `guidance`, but EVERY machine-readable field said transport — so an
+ * operator grepping the log for exhaustion found a quota refusal, and one grepping for refusals
+ * found it filed under a transport give-up. The work order's recorded trap is exactly this: *"the
+ * operator must be able to tell 'the network is flaky, hold on' from 'the directory said no.'"*
+ */
+export type SubmissionGiveUpReason = 
+/** Failures that REACHED a node and got no usable answer, until the budget ran out. */
+"attempts_exhausted"
+/** Only ever local preconditions — the stream never came back inside the window. */
+ | "retry_window_elapsed"
+/** A node decoded it, evaluated it, and said no. Nothing about waiting changes that. */
+ | "refused_by_node"
+/** This daemon can no longer sign as the submitting agent, so nobody can send these bytes. */
+ | "agent_unloaded";
+/** One submission this daemon composed, sealed, and has not yet handed to a directory node. */
+export interface PendingSubmission {
+    agentName: string;
+    /** The STABLE key. `agentName` is a display label and is reusable after a retire; the surface
+     *  that lists these is scoped by id. */
+    agentId: string;
+    /** Content-derived. Never recomputed here — see the header. */
+    submissionId: string;
+    intakeKeyId: string;
+    /** The sealed blob, re-sent verbatim. */
+    ciphertext: Uint8Array;
+    op: SubmissionOp;
+    subject: string;
+}
+export type SubmissionDelivery = {
+    state: "retrying";
+    attempts: number;
+    lastReason: SubmissionSendFailure;
+    nextAttemptAt: number;
+    guidance: string;
+} | {
+    state: "gave_up";
+    attempts: number;
+    lastReason: SubmissionSendFailure;
+    gaveUpBecause: SubmissionGiveUpReason;
+    guidance: string;
+};
+export interface PendingSubmissionView {
+    submissionId: string;
+    op: SubmissionOp;
+    subject: string;
+    intakeKeyId: string;
+    delivery: SubmissionDelivery;
+}
+export interface ScheduledTask {
+    cancel: () => void;
+}
+export interface SubmissionRetryQueueDeps {
+    logger: Logger;
+    /**
+     * Re-send THESE bytes on whatever stream the agent's SignalingManager currently holds. The queue
+     * does not know or care which node that is — that is the point of the ruling in the header.
+     */
+    send: (item: PendingSubmission) => Promise<SendSubmissionResult>;
+    /**
+     * A retry landed. The caller writes the same local record a first-pass send writes, or a later
+     * withdrawal has no handle to name. Called on the retry path only; the first-pass send records
+     * its own.
+     */
+    onAccepted: (item: PendingSubmission, stored: boolean) => void;
+    now?: () => number;
+    schedule?: (fn: () => void, ms: number) => ScheduledTask;
+    /** Gap between two attempts, so a queue of submissions is not a burst of frames. */
+    staggerMs?: number;
+    /** Ceiling on attempts that reached a node. */
+    maxAttempts?: number;
+    /** Wall-clock ceiling for a submission whose failures were all local preconditions. */
+    retryWindowMs?: number;
+    /**
+     * Gap before re-trying a LOCAL PRECONDITION failure. Injectable because it and `baseBackoffMs`
+     * were the only two intervals a test could not vary — which is why the live wiring test's green
+     * depended on a real reconnect ladder racing a real 5-second timer.
+     */
+    localPreconditionRetryMs?: number;
+    /** First non-local backoff; doubles from here. */
+    baseBackoffMs?: number;
+    /** Ceiling on pending submissions held at once, across all agents. */
+    queueCap?: number;
+}
+/**
+ * One hour. Chosen against the intake key, not against patience: the queued blob is sealed to the
+ * intake key the manifest published at compose time, and a manifest window is measured in weeks.
+ *
+ * THIS COMMENT USED TO ASSERT THAT AN HOUR "CANNOT OUTLIVE THE KEY", AND THAT WAS AN UNCHECKED
+ * CLAIM (review M4). It holds only when the manifest has more than an hour left at compose time.
+ * `composeSealedSubmission` refuses an already-expired manifest, but nothing stopped a submission
+ * composed one minute before expiry from being held and re-sent for the next fifty-nine — and the
+ * portal's rotated-key retention does not cover it either, because that rule keeps a retired key
+ * "until no undrained row references it" (M10B-D11) and a HELD submission has no row at any node.
+ * The result is exactly the state the expiry gate exists to prevent: a blob the portal cannot open
+ * and cannot attribute, arriving as poison with no reply possible — while the operator has been
+ * told it is held and needs nothing from them.
+ *
+ * So the CALLER checks rather than this comment asserting. See the enqueue site in `daemon.ts`,
+ * which has the manifest in hand and refuses to hold a submission whose intake key would expire
+ * inside this window.
+ */
+export declare const DEFAULT_RETRY_WINDOW_MS: number;
+/**
+ * The retry queue. One per daemon; keyed by (agentId, submissionId) because two agents on one
+ * daemon can each submit about the same subject and the rows are per-agent facts.
+ */
+export declare class SubmissionRetryQueue {
+    #private;
+    constructor(deps: SubmissionRetryQueueDeps);
+    /**
+     * Take ownership of a submission whose send failed for a retryable reason.
+     *
+     * Returns `false` when the queue is full, and the caller then reports the plain failure — an
+     * operator who is told "the daemon has it" about a submission the daemon dropped is worse off
+     * than one who is told it failed, because only the second knows to act.
+     */
+    enqueue(item: PendingSubmission, lastReason: SubmissionSendFailure): boolean;
+    /**
+     * The agent's directory signaling stream reached 'connected' — the first connect and every
+     * reconnect after a drop. THIS IS THE FAILOVER. Which node it landed on is not this module's
+     * business and is deliberately not read.
+     */
+    onSignalingConnected(agentName: string): void;
+    /**
+     * What this agent still has in flight, and what was given up on. Read by `wallet_list_issued`,
+     * which is the surface behind `cello_attestations_issued` — the verb whose whole question is
+     * "what happened to what I sent?".
+     */
+    list(agentId: string): PendingSubmissionView[];
+    /**
+     * A submission finally landed by some other route — the operator re-issued it, and the
+     * first-pass send succeeded. Drop any give-up recorded for it (review L9).
+     *
+     * The id is content-derived, so re-issuing the SAME words about the SAME subject produces the
+     * SAME id: this is precisely the "I wrote it again and it worked" case. Without it the operator
+     * sees the old failure and the new accepted row side by side for the life of the daemon, with no
+     * way to dismiss the one that is no longer true.
+     */
+    clearGaveUp(agentId: string, submissionId: string): void;
+    /**
+     * Stop, and start nothing further.
+     *
+     * EVERY DROPPED SUBMISSION IS NAMED (review H2). The queue is in memory by design, but the
+     * operator was told in as many words "you do NOT need to run this again" — and before this, a
+     * restart left no durable trace anywhere naming what had been lost. A comment in the composition
+     * root asserting "in memory by design" is not a record; these lines are.
+     *
+     * The SUBJECT is logged and the body is not: the subject is a pubkey or a signal hash, and the
+     * body is the operator's own words about a third party, which this whole path exists to keep out
+     * of the clear on disk.
+     */
+    stop(): void;
+}
+//# sourceMappingURL=submission-retry.d.ts.map

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

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