@cello-protocol/daemon 0.0.167 → 0.0.169

package/dist/document-delivery.d.ts

@@ -1,229 +0,0 @@
-/**
- * DOD-DOC-DELIVERY-1 — daemon-autonomous delivery (§16.4).
- *
- * Publish writes the envelope to the log and returns. Delivery is somebody else's job, and that
- * somebody is this worker: it derives what is pending FROM THE LOG, checks the peer is reachable
- * before dialing, opens or reuses a session itself, delivers, and records the ack — with zero agent
- * attention on either end. Two agents in opposite time zones sync overnight without either agent
- * doing anything.
- *
- * ── PENDING IS DERIVED, NEVER HELD ────────────────────────────────────────────────────────────
- *
- * "Unacknowledged envelopes I authored" is a WHERE clause over the log, and that is the whole
- * definition. A queue in memory does not survive a restart — the daemon is a long-running local
- * process that gets restarted routinely — and a queue in its own table is a second source of truth
- * that can disagree with the log about what was sent. The attempt counter and the next-attempt
- * time live on the envelope row for the same reason: a backoff that resets on restart is not a
- * backoff, and a daemon restarting in a reconnect loop would hammer an unreachable peer at full
- * rate forever.
- *
- * ── WHY LOOKUP BEFORE DIAL ────────────────────────────────────────────────────────────────────
- *
- * §16.4's design is presence-driven push, but there is no presence subscription today (parked,
- * M14-P4). Without one, the honest substitute is: ask the directory whether the peer is reachable,
- * and if it is not, do not burn a dial — schedule a retry on a capped backoff. Dialing an offline
- * peer to find out it is offline is the same information at much higher cost, and it is the cost
- * that would be paid on every pending envelope, on every tick, for as long as the peer is away.
- */
-import type { DocumentStore, DocumentEnvelopeRow } from "./document-store.js";
-import type { Logger } from "./types.js";
-/**
- * The transport seam. Narrow on purpose (M4 rule: add to an interface only when a failing test or
- * a production behaviour requires it) — the worker's job is scheduling and bookkeeping, and every
- * dial-level concern belongs to the adapter behind this.
- */
-export interface DocumentDeliveryTransport {
-    /**
-     * Is the peer reachable right now? `discovery_lookup` today. Returns false rather than throwing
-     * for an ordinary "not online"; a throw means the LOOKUP failed, which is a different fact and
-     * must not be recorded as the peer being away.
-     */
-    isPeerReachable(peerAgentId: string, correlationId: string): Promise<{
-        reachable: boolean;
-        unknownAgent: boolean;
-    }>;
-    /**
-     * Deliver one envelope over a session the transport opens or reuses (§16.4: daemon-chooses by
-     * default; `sessionHint` is the one case with audit value — the agent is mid-conversation about
-     * the document and wants the discussion and the change in one sealed record).
-     */
-    /**
-     * `ok` means the peer's daemon ANSWERED about this envelope — it is not "the peer liked it".
-     * `admitted: false` is a rejection (§3.2's `0x05`), and a rejection IS an ack for delivery
-     * purposes: the peer has decided, so there is nothing left to retry. Without the distinction the
-     * adapter has to map a rejection onto one of two lies — `ok: true` makes the delivery record say
-     * the peer admitted content it refused, and `ok: false` redelivers an envelope the peer has
-     * already ruled on, forever, re-triggering their gate and their retry counter until the document
-     * stalls for reasons the operator cannot see.
-     *
-     * `sessionOpened` distinguishes a session this delivery opened from one it reused — the audit
-     * distinction §16.4 cares about, and unrecoverable after the fact.
-     */
-    /**
-     * Send already-encoded bytes to a peer over the same open-or-reuse-then-seal path `deliver` uses.
-     *
-     * Exists for the frames that are NOT in the envelope log and therefore have no delivery record to
-     * schedule: a proposal (there is no document yet), an ack, a rejection. Those still have to reach
-     * the peer, and the alternative — a second implementation of session acquisition — would drift on
-     * exactly the things that matter here: which session gets reused, and whether one this daemon
-     * opened gets sealed.
-     *
-     * `documentId` is for the log line only; nothing about the send depends on it.
-     */
-    sendBytes(input: {
-        peerAgentId: string;
-        documentId: string;
-        bytes: Uint8Array;
-        sessionHint?: string;
-        correlationId: string;
-        /**
-         * The witnessed leaf DOMAIN. Defaults to the document kind (0x04); a refusal passes 0x05.
-         * Only the caller knows which frame it is holding, and the directory's legibility rules
-         * discriminate on it — see `DOCUMENT_LEAF_KIND` in document-delivery-transport.ts.
-         */
-        leafKind?: number;
-    }): Promise<{
-        ok: true;
-        sessionId: string;
-        sessionOpened: boolean;
-        /**
-         * The relay took it because the holder had no live counterparty — it is NOT with them yet.
-         * Only a caller that has no ack frame needs this, and for those `ok` alone is a lie.
-         */
-        parked?: boolean;
-    } | {
-        ok: false;
-        reason: string;
-        detail?: string;
-    }>;
-    deliver(input: {
-        peerAgentId: string;
-        documentId: string;
-        envelope: DocumentEnvelopeRow;
-        sessionHint?: string;
-        correlationId: string;
-        /**
-         * How long THIS envelope may hold an opened session waiting for the peer's ack.
-         *
-         * A BUDGET SPENT ACROSS THE PASS, not a per-envelope allowance. The wait is awaited inside
-         * three nested sequential loops — agents, then documents, then envelopes — so a fixed 10s each
-         * meant a backlog of 100 to one silent peer could burn ~1000 seconds during which NO other
-         * agent's documents were swept at all. And a peer that never acks is the ordinary case during a
-         * version rollout, which this repo does continuously because both sides float `latest`.
-         *
-         * Zero means do not wait. The seal still happens; only the grace is skipped.
-         */
-        ackGraceMs: number;
-    }): Promise<{
-        ok: true;
-        sessionId: string;
-        sessionOpened: boolean;
-        /**
-         * `true` admitted, `false` rejected — both are ACKS, the peer has decided. `null` means the
-         * envelope LEFT (or was parked for an offline peer) and no answer has come back yet.
-         *
-         * The third state is not hedging; both two-valued answers are dishonest for a send whose
-         * outcome is unknown. `true` marks the envelope acknowledged in the log while the peer may
-         * never have applied it — and the log being right about what the peer holds is the entire
-         * reason pending is derived from it. `false` counts a send that WORKED as a failure and
-         * re-sends content already in flight.
-         */
-        admitted: boolean | null;
-        /**
-         * The relay took it because the peer had no live counterparty on that session.
-         *
-         * Distinct from `admitted: null`, which covers both a live send awaiting an answer and this.
-         * The two want different retry schedules and were given the same one — see the scheduling
-         * branch in `#run`.
-         */
-        parked: boolean;
-        rejectionReason?: string;
-    } | {
-        ok: false;
-        reason: string;
-        detail?: string;
-    }>;
-}
-/**
- * Backoff schedule in ms: ~1s, 5s, 30s, 2m, 10m, then the last entry repeats.
- *
- * The final entry IS the cap — there is no separate ceiling constant. There was one, set to 900s,
- * and it was unreachable: the index clamp meant the schedule never produced a value above 600s, so
- * the exported "cap" was a number the code could not emit and the tests were using it as a synonym
- * for "much later". A documented limit the implementation cannot reach is worse than none.
- *
- * Capped at all because the peer coming back online is the event we are waiting for and it can
- * happen at any moment — an uncapped curve leaves a peer that returned after a long absence waiting
- * hours for a delivery that has been ready the whole time.
- */
-/**
- * Total ack-grace one sweep pass may spend, across every agent, document and envelope in it.
- *
- * The wait exists so a session we opened is not torn down before the peer's answer arrives. It is
- * capped as a PASS budget because the loops it sits inside are sequential: a per-envelope allowance
- * meant one silent peer with a backlog could hold the sweep for the better part of an hour, and the
- * only symptom would be other agents' documents quietly not syncing.
- *
- * 30s ≈ three full graces. Enough for the ordinary case (one or two opened sessions per pass, ack
- * back in well under a second) without letting an unresponsive peer own the pass.
- */
-export declare const DELIVERY_ACK_GRACE_BUDGET_MS = 30000;
-export declare const DELIVERY_BACKOFF_MS: readonly [1000, 5000, 30000, 120000, 600000];
-export declare const DELIVERY_BACKOFF_CAP_MS: 5000 | 1000 | 30000 | 120000 | 600000;
-/**
- * How long to wait for an ACK after a SUCCESSFUL send, before sending again.
- *
- * Deliberately NOT the failure backoff. "How long do I wait after a failure" and "how long do I
- * wait for an answer" are different questions, and reusing the first for the second re-sent a
- * successfully-delivered envelope one second later — and every resend is not free: `sendContent`
- * witnesses a message-leaf hash to the relay and appends a leaf to the session chain, so a
- * never-acked envelope would pollute the peer's sealed conversation record forever.
- */
-export declare const DELIVERY_ACK_TIMEOUT_MS: 5000 | 1000 | 30000 | 120000 | 600000;
-/**
- * How many times an envelope may be SENT without ever being acknowledged before the document
- * stalls.
- *
- * A peer that will never answer must eventually stop being treated as a transient. Without a
- * ceiling, an envelope sent to a peer whose client cannot ack — which is every peer until the
- * inbound handler ships on both sides — is re-sent forever and is indistinguishable, in the log
- * and in `list`, from one that is about to land.
- */
-export declare const DELIVERY_MAX_UNACKED_SENDS = 5;
-/**
- * A document whose peer cannot be resolved is not transient, so it gets the cap immediately rather
- * than climbing to it — but it DOES get scheduled. See the `no_peer` branch.
- */
-export declare const DELIVERY_UNRESOLVABLE_RETRY_MS: 5000 | 1000 | 30000 | 120000 | 600000;
-export declare function backoffFor(attempts: number): number;
-export interface DeliveryTickResult {
-    attempted: number;
-    delivered: number;
-    /** Sent (or parked) with no answer yet — in flight, neither done nor failed. */
-    sent: number;
-    /** Answered but refused. Acked all the same — the peer has decided. */
-    rejected: number;
-    deferred: number;
-    failed: number;
-}
-export declare class DocumentDelivery {
-    #private;
-    constructor(store: DocumentStore, transport: DocumentDeliveryTransport, logger: Logger);
-    /**
-     * One pass over what is due. Returns counts rather than throwing on a per-envelope failure: one
-     * unreachable peer must not stop delivery to every other peer, which is precisely the "works
-     * only when all nodes are healthy" shape the project forbids.
-     */
-    /**
-     * One pass over what is due, PER (document, holder). Returns counts rather than throwing on a
-     * per-target failure: one unreachable HOLDER must not stop delivery to any other — the same
-     * "works only when all nodes are healthy" shape the project forbids, now per holder.
-     */
-    tick(ownerAgentId: string, holdersFor: (documentId: string) => string[] | null, nowMs: number, opts?: {
-        sessionHints?: ReadonlyMap<string, string>;
-        correlationId?: string;
-        /** Our own wire sender id. Defaults to the owner key for callers whose ids coincide. */
-        senderAgentId?: string;
-    }): Promise<DeliveryTickResult>;
-}
-//# sourceMappingURL=document-delivery.d.ts.map

package/dist/document-delivery.d.ts.map

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