keri-ts 0.11.0 → 2.0.0

package/types/app/exchanging.d.ts

@@ -1,245 +0,0 @@
-import { type CesrFrame, Cigar, type EssrPayload, Prefixer, ResourcePolicy, type SealEvent, type SealSource, type SerderKERI } from "cesr-ts";
-import { type Operation } from "effection";
-import type { AgentCue } from "../core/cues.js";
-import { Deck } from "../core/deck.js";
-import { PathedMaterialGroup, TransIdxSigGroup, type TransLastIdxSigGroup } from "../core/dispatch.js";
-import { type ExchangeFactors, type MissingExchangeState } from "../core/exchange-proofing.js";
-import { type KramReceipt } from "../core/kraming.js";
-import type { Hab, Habery } from "./habbing.js";
-/** Delivery mode used when choosing a remote exchange transport endpoint. */
-export type ExchangeTransport = "auto" | "direct" | "indirect";
-/** Pathed attachment projection exposed to exchange-route handlers. */
-export interface ExchangeAttachment {
-    raw: Uint8Array;
-    text: string;
-}
-/** Typed proof/schema dependencies follow authentication; schema is a complete missing resource SAID. */
-export type ExchangeRouteVerification = boolean | {
-    kind: "escrow";
-    reason: string;
-    schema?: string;
-};
-/** Route-handler contract for accepted exchange messages. */
-export interface ExchangeRouteHandler {
-    readonly resource: string;
-    /** Optional protocol-major specialization; omitted handlers remain the route default. */
-    readonly protocolMajor?: number;
-    /** Opt in only after route-specific child validation and durable replay are implemented. */
-    readonly acceptsNests?: boolean;
-    /** Opt in to verified sender source coordinates required by the v2 IPEX workflow. */
-    readonly acceptsSscs?: boolean;
-    /** Permit selected supplemental factors in verify(), independently of the selection hook. */
-    readonly acceptsEvidence?: boolean;
-    /** Only routes with optional supplemental evidence may query and drop missing factors. */
-    readonly acceptsMissingEvidence?: boolean;
-    /** Select from independently verified non-sender factors; null permanently rejects the route. */
-    verifyEvidence?(args: {
-        serder: SerderKERI;
-        factors: Required<ExchangeFactors>;
-        invalid: boolean;
-        /** Present only when acceptsMissingEvidence is enabled, including an empty list. */
-        missing?: readonly MissingExchangeState[];
-    }): ExchangeFactors | null | Operation<ExchangeFactors | null>;
-    /** Validate route policy before publishing accepted evidence. */
-    verify?(args: {
-        serder: SerderKERI;
-        /** Selected supplemental proofs; each factor authenticates this body only. */
-        evidence?: Required<ExchangeFactors>;
-        /** Valid sender-implied source couples, only for opted-in routes. */
-        sscs?: readonly SealSource[];
-        attachments: ExchangeAttachment[];
-        /** Borrowed payload views valid for this route invocation. */
-        essr?: EssrPayload;
-        /** Borrowed children, with evidence kept on its original message. */
-        nests?: readonly CesrFrame[];
-        /** Hosted endpoint provenance, distinct from the signed sender. */
-        mailboxAid?: string | null;
-        /** Qualified first receiver receipt, retained through dependency retry. */
-        receiverTime?: string;
-    }): ExchangeRouteVerification | Operation<ExchangeRouteVerification>;
-    /** Consume already durable evidence within the caller's Effection scope. */
-    handle(args: {
-        serder: SerderKERI;
-        /** Valid sender-implied source couples, only for opted-in routes. */
-        sscs?: readonly SealSource[];
-        attachments: ExchangeAttachment[];
-        /** Borrowed payload views valid for this route invocation. */
-        essr?: EssrPayload;
-        /** Borrowed children, with evidence kept on its original message. */
-        nests?: readonly CesrFrame[];
-        /** Hosted endpoint provenance, distinct from the signed sender. */
-        mailboxAid?: string | null;
-        /** Qualified first receiver receipt, retained through dependency retry. */
-        receiverTime?: string;
-    }): void | Operation<void>;
-}
-/** One signed exchange and its bounded attachment views at runtime admission. */
-export interface ExchangeInput {
-    /** Signed exchange body, including any ESSR byte commitment. */
-    serder: SerderKERI;
-    /** Transferable sender endorsements. */
-    tsgs?: readonly TransIdxSigGroup[];
-    /** Nontransferable sender endorsements. */
-    cigars?: readonly Cigar[];
-    /** Last-establishment references must freeze to historical coordinates before escrow. */
-    lsgs?: readonly TransLastIdxSigGroup[];
-    /** Foreign last references unresolved at their original receipt. */
-    unresolvedLast?: readonly Prefixer[];
-    /** Sender-implied source coordinates from parser normalization. */
-    sscs?: readonly SealSource[];
-    /** Explicit anchoring AID and historical source coordinates. */
-    sourceSeals?: readonly SealEvent[];
-    /** Ordinary bounded pathed attachments. */
-    ptds?: readonly PathedMaterialGroup[];
-    /** Caller-owned wire; successful publication transfers local file ownership. */
-    essr?: EssrPayload;
-    /** Parent-owned children; admission borrows and snapshots their original wire. */
-    nests?: readonly CesrFrame[];
-    /** Hosted endpoint provenance, retained across escrow. */
-    mailboxAid?: string | null;
-    /** Private scoped KRAM authority; callers cannot supply a timestamp override. */
-    receipt?: KramReceipt;
-}
-/** Result of this attempt; complete(said) separately reports any earlier durable acceptance. */
-export type ExchangeDecision = {
-    kind: "accept";
-    said: string;
-} | {
-    kind: "escrow";
-    reason: string;
-    said: string;
-} | {
-    kind: "reject";
-    reason: string;
-    said: string;
-    /** MissingSignatureError preserves an existing escrow but does not authorize creating one. */
-    preserveEscrow?: true;
-};
-/**
- * Peer-to-peer `exn` processor for one `Habery`.
- *
- * Responsibilities:
- * - verify exchange-message signatures against accepted sender state
- * - persist accepted exchange artifacts in the dedicated exchange stores
- * - escrow partially verifiable exchange traffic in `epse.` / `epsd.`
- * - dispatch accepted messages to route-specific handlers such as challenge
- *
- * TypeScript design rule:
- * - use typed `accept` / `escrow` / `reject` outcomes instead of KERIpy's
- *   exception-only control flow for ordinary branch results
- */
-export declare class Exchanger {
-    readonly hby: Habery;
-    readonly cues: Deck<AgentCue>;
-    readonly routes: Map<string, ExchangeRouteHandler>;
-    private readonly versionedRoutes;
-    /** At most one active admission; the runtime owns bounded waiting and backpressure. */
-    private processing;
-    /** Borrow the runtime ledger; standalone defaults do not establish a process-wide bound. */
-    readonly resources: ResourcePolicy;
-    /** Finite decoded-byte limit, independent of total stream length. */
-    private readonly maxEssrBytes;
-    /** Finite token count, including empty Texters. */
-    private readonly maxEssrItems;
-    /** Borrow the runtime clock for escrow deadlines and retries. */
-    private readonly now;
-    /** Bind route handlers and explicit per-message resource budgets to one habitat database. */
-    constructor(hby: Habery, { handlers, cues, maxEssrBytes, maxEssrItems, resources, now, }?: {
-        handlers?: readonly ExchangeRouteHandler[];
-        cues?: Deck<AgentCue>;
-        maxEssrBytes?: number;
-        maxEssrItems?: number;
-        resources?: ResourcePolicy;
-        now?: () => number;
-    });
-    /** Register one route handler for accepted exchange messages. */
-    addHandler(handler: ExchangeRouteHandler): void;
-    /**
-     * Verify, persist, and dispatch one inbound `exn`.
-     *
-     * Accepted messages are durably logged before any route-specific side
-     * effects run so later reopen and verification paths can reuse the same
-     * stored evidence.
-     */
-    processEvent(args: ExchangeInput): Operation<ExchangeDecision>;
-    /** Hold one exchange mutation until its child I/O and payload cleanup have finished. */
-    private admission;
-    /** Isolate admission cleanup so cancelling it cannot resume the caller after delegation. */
-    private admit;
-    /** Retry escrows using their persisted payload references and mailbox provenance. */
-    processEscrows(): Operation<void>;
-    /** Retry each bounded escrow inside one structured child scope. */
-    private retryEscrows;
-    /** Close each bounded cursor before replay; newly discovered dependencies wait for the next finite pass. */
-    private retryEscrowType;
-    /** Share parent metadata and ESSR credit across all retained child rows. */
-    private nestBudget;
-    /** Stream accepted evidence; reopened child ESSR stages survive until output cancellation or completion. */
-    replay(said: string, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
-    /** Admit cooperating nested copies before materializing the first row or serializer. */
-    private reserveNestedCopies;
-    /** Return true once the named exchange SAID is durably stored as accepted. */
-    complete(said: string): boolean;
-    /**
-     * Return true when this local habitat is elected to externally send an EXN.
-     *
-     * KERIpy uses the lowest collected group-signature index as the lead for a
-     * completed multisig business EXN. Single-sig habitats are always the lead.
-     */
-    lead(hab: Hab, said: string): boolean;
-    /** Freeze last-establishment groups and expand sender-implied seals before durable admission. */
-    private resolveProofs;
-    /** Match sender-factor precedence and let the registered route select supplemental evidence. */
-    private authenticate;
-    /** Match _cueMissingKeyState's coordinate deduplication within this invocation. */
-    private cueMissingStates;
-    /** Reattach the persisted verifier to each nontransferable signature before replay or retry. */
-    private storedCigars;
-    /** Restore source triples without losing the anchoring AID or its historical ordinal. */
-    private storedSeals;
-    /** Classify sender endorsements without publishing exchange or payload ownership. */
-    private verifySignatures;
-    /** Retain incomplete endorsements and the original expiration clock for retry. */
-    private escrowPartialSigned;
-    /** Persist the same independently authenticated evidence for signature and schema dependencies. */
-    private storeEscrowEvidence;
-    /** One absolute deadline spans sequential schema dependencies; receiver receipt is not the TMSC opener. */
-    private escrowMissingSchema;
-    /** Trusted clock failures remain infrastructure errors rather than expiring remote work. */
-    private nowMicros;
-    /** Persist protocol evidence inside the admission transaction before route handling. */
-    private logAcceptedEvent;
-    private rebuildEscrowedGroups;
-    /** Clear pending metadata, preserving wire evidence during the acceptance transaction. */
-    private clearEscrow;
-    /** Remove pending ownership only; accepted wire evidence always remains retained. */
-    private dropEscrow;
-}
-/**
- * Create and deliver one signed exchange message through the selected
- * controller-to-controller transport path.
- */
-export declare function sendSignedExchangeMessage(hab: Hab, args: {
-    route: string;
-    payload: Record<string, unknown>;
-    recipient: string;
-    transport?: ExchangeTransport;
-    modifiers?: Record<string, unknown>;
-    date?: string;
-    dig?: string;
-}): Operation<{
-    serder: SerderKERI;
-    url: string;
-}>;
-/**
- * Choose the remote URL that should receive one outbound exchange message.
- *
- * Current transport policy:
- * - `direct` sends to the recipient controller location
- * - `indirect` sends to an authorized mailbox endpoint, then falls back to
- *   agent endpoints when no mailbox URL is available
- * - `auto` prefers direct delivery because this codebase has not yet landed
- *   full witness-forwarding mailbox orchestration
- */
-export declare function resolveExchangeTransportUrl(hab: Hab, recipient: string, transport: ExchangeTransport): string | null;
-//# sourceMappingURL=exchanging.d.ts.map

package/types/app/exchanging.d.ts.map

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

package/types/app/forwarding.d.ts

@@ -1,411 +0,0 @@
-/**
- * Mailbox-first forwarding and polling support.
- *
- * KERIpy correspondence:
- * - ports the conceptual roles of `Poster`, `StreamPoster`, `ForwardHandler`,
- *   and mailbox polling/query handling from `keri.app.forwarding` and
- *   `keri.app.indirecting`
- *
- * Current `keri-ts` difference:
- * - delivery and polling are synchronous Effection operations instead of HIO
- *   doers
- * - sender retry durability is optional via `Outboxer`
- * - HTTP posting honors both KERIpy header mode and the Tufa-only body mode
- */
-import { type CesrFrame, ResourceAdmissionError, SerderKERI } from "cesr-ts";
-import { type Operation } from "effection";
-import { type MailboxDelivery, type MailboxInboxLimits } from "../db/mailbox-inbox.js";
-import type { Mailboxer } from "../db/mailboxing.js";
-import type { OutboxerLike } from "../db/outboxing.js";
-import type { AgentRuntime } from "./agent-runtime.js";
-import { type CesrHttpRefusal } from "./cesr-egress.js";
-import { type CesrBodyMode } from "./cesr-http.js";
-import type { ExchangeAttachment, ExchangeRouteHandler } from "./exchanging.js";
-import type { Hab, Habery } from "./habbing.js";
-import type { MailboxDirector } from "./mailbox-director.js";
-import { type MailboxSseMessage } from "./mailbox-sse.js";
-import type { OobiReplyLimits } from "./oobi-replies.js";
-import { Organizer } from "./organizing.js";
-import { type RuntimeServices } from "./runtime-services.js";
-/** Delivery preference accepted by CLI and runtime exchange send helpers. */
-export type ExchangeDeliveryPreference = "auto" | "direct" | "indirect";
-/** Result summary for one EXN send attempt across all resolved destinations. */
-export interface ExchangeSendResult {
-    serder: SerderKERI;
-    deliveries: string[];
-    queued: string[];
-}
-/** Result summary for one raw CESR delivery attempt. */
-export interface RawCesrSendResult {
-    deliveries: string[];
-    queued: string[];
-}
-/** Recipient policy captured during a short guarded preparation turn. */
-export interface RawCesrRoute {
-    readonly sender: string;
-    readonly recipient: string;
-    readonly topic: string;
-    readonly kind: "mailbox" | "local" | "direct" | "witness";
-    readonly targets: readonly {
-        eid: string;
-        url: string;
-    }[];
-    readonly bodyMode: CesrBodyMode;
-}
-/** Prepared wire borrows its bytes until the transport operation and cleanup finish. */
-export type PreparedCesrTarget = {
-    readonly kind: "stored";
-} | {
-    readonly kind: "tcp";
-    readonly url: string;
-    readonly destination: string;
-    readonly message: Uint8Array;
-} | {
-    readonly kind: "http";
-    readonly url: string;
-    readonly destination: string;
-    readonly message: Uint8Array;
-    readonly bodyMode: CesrBodyMode;
-};
-/** Deliver prepared wire; explicit runtime lends same-socket intake, otherwise TCP drains output only. */
-export declare function sendPreparedCesrTarget(target: PreparedCesrTarget, services: RuntimeServices, signal?: AbortSignal, onHttpRefusal?: (error: CesrHttpRefusal) => void, onAdmissionRefusal?: (error: ResourceAdmissionError) => void, runtime?: AgentRuntime): Operation<void>;
-/** Join a prepared target attempt; local completion/refusal/busy never implies protocol acceptance. */
-export declare function attemptPreparedCesrTarget(target: PreparedCesrTarget, services: RuntimeServices, signal?: AbortSignal, runtime?: AgentRuntime): Operation<"complete" | "refused" | "busy">;
-interface PosterOptions {
-    mailboxer?: Mailboxer | null;
-    outboxer?: OutboxerLike;
-    services?: RuntimeServices;
-}
-interface MailboxPollerOptions {
-    mailboxAdmission?: {
-        mode: "durable";
-        limits?: Partial<MailboxInboxLimits>;
-    };
-    timeouts?: Partial<MailboxPollingTimeoutPolicy>;
-    services?: RuntimeServices;
-    pollTransport?: MailboxPollTransport;
-}
-/**
- * Mailbox-first postman for outbound EXN transport.
- *
- * Responsibilities:
- * - resolve recipient aliases against organizer/contact state
- * - route to all currently authorized recipient mailbox endpoints when present
- * - fall back to direct controller/agent endpoints, then one witness endpoint,
- *   when no mailbox exists
- * - persist sender-side mailbox retry state per mailbox endpoint
- */
-export declare class Poster {
-    readonly hby: Habery;
-    readonly mailboxer: Mailboxer | null;
-    readonly outboxer: OutboxerLike;
-    readonly organizer: Organizer;
-    readonly services: RuntimeServices;
-    constructor(hby: Habery, options?: PosterOptions);
-    /**
-     * Resolve one CLI or user recipient input into the actual destination prefix.
-     *
-     * Resolution order matches the mailbox CLI mental model:
-     * - exact known prefix wins
-     * - otherwise exact organizer alias lookup is required
-     */
-    resolveRecipient(recipient: string): string;
-    /**
-     * Send one EXN through the mailbox-first delivery policy.
-     *
-     * Default policy:
-     * - if recipient mailboxes exist, broadcast to all mailbox endpoints
-     * - if no mailbox exists, send directly to controller/agent endpoints
-     * - if no direct endpoints exist, fall back to one witness endpoint
-     * - failed mailbox deliveries are queued durably for retry
-     *
-     * Current `keri-ts` difference:
-     * - KERIpy `Poster` is queue/doer based
-     * - here the caller drives one explicit operation and gets a structured
-     *   result back immediately
-     * - optional runtime lends same-socket TCP intake; standalone TCP is transmit-only
-     * - public callers own synchronous route/signing preparation and wire retention
-     */
-    sendExchange(hab: Hab, args: {
-        recipient: string;
-        route: string;
-        payload: Record<string, unknown>;
-        topic?: string;
-        exchangeRecipient?: string | null;
-        modifiers?: Record<string, unknown>;
-        date?: string;
-        dig?: string;
-        embeds?: Record<string, Uint8Array>;
-        delivery?: ExchangeDeliveryPreference;
-    }, runtime?: AgentRuntime): Operation<ExchangeSendResult>;
-    /**
-     * Send one raw CESR message through the same mailbox-first transport policy.
-     *
-     * This is used by delegation workflows where correctness depends on the
-     * actual KEL bytes reaching the delegator or delegate, not on an EXN wrapper.
-     * Optional runtime lends TCP intake; caller owns preparation/retention before transport.
-     */
-    sendBytes(hab: Hab, args: {
-        recipient: string;
-        message: Uint8Array;
-        topic?: string;
-        delivery?: ExchangeDeliveryPreference;
-    }, runtime?: AgentRuntime): Operation<RawCesrSendResult>;
-    /** Snapshot mailbox/direct/witness policy without opening transport or reading message bytes. */
-    resolveBytesRoute(hab: Hab, args: {
-        recipient: string;
-        topic?: string;
-        delivery?: ExchangeDeliveryPreference;
-    }): RawCesrRoute;
-    /** Same policy; parsed-prefix lookup bypasses aliases, absence is explicit, other failures propagate. */
-    findBytesRoute(hab: Hab, args: {
-        recipient: string;
-        topic?: string;
-        delivery?: ExchangeDeliveryPreference;
-        recipientIsPrefix?: boolean;
-    }): RawCesrRoute | null;
-    /** Guarded preparation; an explicit finite cap copies direct wire for independently credited retention. */
-    prepareBytesTarget(hab: Hab, route: RawCesrRoute, index: number, message: Uint8Array, maxBytes?: number): PreparedCesrTarget;
-    /**
-     * Retry any pending mailbox-target deliveries using current recipient state.
-     *
-     * Retry behavior is per mailbox endpoint, not per logical message. A removed
-     * mailbox cancels only that endpoint's target row. Runtime route/signing and
-     * outcome publication use short turns; transport cleanup joins outside the guard.
-     * Runtime scans require pre-copy bounded reads and retain admitted copies through joined cleanup.
-     * Standalone/custom iteration retains its caller-owned preparation and retention contract.
-     */
-    processPending(runtime?: AgentRuntime): Operation<void>;
-    /** Return whether any sender retry work still remains. */
-    hasPendingWork(): boolean;
-    /** Cancel all pending retry targets for one mailbox AID. */
-    cancelMailbox(eid: string): void;
-    /**
-     * Deliver one message to one mailbox endpoint.
-     *
-     * Delivery modes:
-     * - if the mailbox AID is local to this habery, store directly in
-     *   `Mailboxer`
-     * - otherwise wrap in `/fwd` and post to the remote mailbox URL
-     */
-    private deliverMailboxTarget;
-    /**
-     * Deliver one message using the recipient's witness as a store-and-forward
-     * fallback when no mailbox or direct endpoint exists.
-     */
-    private deliverWitnessTarget;
-    /**
-     * Deliver one `/fwd`-wrapped payload to a mailbox or witness endpoint.
-     *
-     * Local hosted targets store directly in `Mailboxer`; remote targets receive
-     * KERIpy-style introduction material ahead of the forwarded payload.
-     */
-    private deliverForwardedTarget;
-    /** Local mailbox writes and signed introductions finish before any network work starts. */
-    private prepareForwardedTarget;
-    /** Require provider mailbox storage for local mailbox-target delivery. */
-    private requireMailboxer;
-}
-/**
- * Accepted `/fwd` route handler that stores embedded payloads in mailbox topics.
- *
- * This is the `keri-ts` mailbox-storage analogue to KERIpy's `ForwardHandler`.
- *
- * Authorization rule:
- * - the request-scoped mailbox AID passed with this message must currently be
- *   authorized for the addressed recipient
- */
-export declare class ForwardHandler implements ExchangeRouteHandler {
-    static readonly resource = "/fwd";
-    readonly resource = "/fwd";
-    /** This route binds a single v2 child body; recipient processors authenticate its evidence. */
-    readonly acceptsNests = true;
-    readonly mailboxDirector: MailboxDirector;
-    constructor(mailboxDirector: MailboxDirector);
-    /**
-     * Verify that the embedded exchange has the mailbox modifiers and one
-     * extractable forwarded payload.
-     */
-    verify(args: {
-        serder: SerderKERI;
-        attachments: ExchangeAttachment[];
-        nests?: readonly CesrFrame[];
-    }): boolean;
-    /**
-     * Store one forwarded payload when the receiving host is allowed to act as
-     * the recipient's async correspondence store.
-     *
-     * Accepted host shapes:
-     * - explicit mailbox provider authorized in `ends.`
-     * - recipient witness host from the accepted KEL witness set
-     * - recipient agent host authorized in `ends.`
-     *
-     * Controller endpoints stay excluded here because they are direct
-     * correspondence destinations, not store-and-forward hosts.
-     */
-    handle(args: {
-        serder: SerderKERI;
-        attachments: ExchangeAttachment[];
-        /** Borrowed child wire remains live for this awaited handler operation. */
-        nests?: readonly CesrFrame[];
-        /** Receiving hosted endpoint whose authority must cover the addressed recipient. */
-        mailboxAid?: string | null;
-    }): void | Operation<void>;
-}
-/**
- * Local/remote mailbox consumer for forwarded EXN topics.
- *
- * Current scope:
- * - replays locally stored mailbox topics for the active habitat prefix
- * - polls configured remote mailbox or witness endpoints with `mbx` queries
- * - ingests retrieved payloads back through the shared `Reactor`
- */
-export declare class MailboxPoller {
-    static readonly DefaultTimeoutPolicy: Readonly<MailboxPollingTimeoutPolicy>;
-    static readonly ReadIdleTimeoutMs = 500;
-    readonly hby: Habery;
-    readonly mailboxDirector: MailboxDirector;
-    readonly timeoutPolicy: Readonly<MailboxPollingTimeoutPolicy>;
-    readonly services: RuntimeServices;
-    readonly pollTransport: MailboxPollTransport;
-    private readonly delivered;
-    readonly inboxLimits: MailboxInboxLimits;
-    private readonly durableAdmission;
-    private readonly localCursors;
-    /** One bounded command-local resume position; endpoint/habitat metadata stays borrowed. */
-    private readonly nextRemotePoll;
-    constructor(hby: Habery, mailboxDirector: MailboxDirector, options?: MailboxPollerOptions);
-    /** Configure mailbox polling state for future expansion; currently a no-op. */
-    configure(_args?: {
-        hab?: Hab;
-    }): void;
-    /** Register one mailbox topic that this poller should retrieve. */
-    registerTopic(topic: string): void;
-    /**
-     * Drain one polling turn:
-     * - replay locally hosted mailbox traffic first
-     * - then query remote mailbox or witness endpoints using `mbx`
-     *
-     * The returned batches preserve per-source boundaries so callers can ingest
-     * one local or remote result set and run follow-on escrow/cue work before
-     * moving to the next source.
-     */
-    processOnce({ budgetMs, }?: {
-        budgetMs?: number;
-    }): Operation<MailboxPollBatch[]>;
-    /**
-     * Poll forever, streaming typed batches into one sink.
-     *
-     * Long-lived runtime polling stays callback-based because concurrent remote
-     * workers do not have a natural finite return value.
-     */
-    pollDo(onBatch: (batch: MailboxPollBatch) => void | Operation<void>): Operation<never>;
-    /**
-     * Read locally stored mailbox traffic from the shared `Mailboxer`.
-     *
-     * Local cursors are in-memory only because they are scoped to the current
-     * runtime process, unlike remote mailbox progress tracked in `tops.`.
-     */
-    private readLocalMailbox;
-    /** Return the in-memory local mailbox cursor map for one local prefix. */
-    private localCursor;
-    /**
-     * Poll one remote mailbox or witness endpoint once and return one batch.
-     *
-     * Timeout ownership:
-     * - bounded callers pass their remaining command-local budget
-     * - long-lived workers pass the normal mailbox long-poll duration
-     */
-    private pollRemoteEndpointOnce;
-    /** Deliver retained ingress once per poller lifetime; consumers explicitly dispose durable outcomes. */
-    private replayRetained;
-    /** Mark successful handoff only, never selection before later network work or a throwing sink. */
-    private handOff;
-    /** Keep one long-lived worker running for each currently configured remote endpoint. */
-    private syncRemoteWorkers;
-    /**
-     * Poll one remote endpoint continuously in the long-lived runtime shape.
-     *
-     * This keeps KERIpy's "one poller per endpoint" behavior while preserving
-     * `keri-ts`'s split between mailbox transport and runtime parser ownership.
-     */
-    private remoteEndpointWorker;
-    private remotePollTargets;
-    private pollSignerHab;
-}
-/**
- * Borrow a Hab/store for lazy introduction output, preserving target KEL, oldest
- * delegator first, then endpoint/location replies. Capture begins on iteration.
- * No source is opened when a witness/receipt already makes introduction unnecessary.
- * Native proof/key copies and the large-history transport caller remain separately qualified.
- */
-export declare function introductionMessages(hab: Hab, remote: string, limits?: OobiReplyLimits): Iterable<Uint8Array>;
-/**
- * Collect a finite introduction under a configurable 8 MiB default; explicit
- * Infinity is misuse. Admit every message before retention and the final join.
- * Remaining credit may be zero when witness/receipt suppression produces no output.
- * This convenience collector does not establish a shared runtime memory bound.
- */
-export declare function introduce(hab: Hab, remote: string, maxBytes?: number, limits?: OobiReplyLimits): Uint8Array;
-/**
- * Public helper for deriving mailbox topic defaults from one EXN route.
- *
- * This stays exported because CLI and runtime call sites both need one shared
- * answer for "which mailbox topic should this route land in by default?"
- */
-export declare function mailboxTopicForRoute(route: string): string;
-/** Explicit mailbox polling timeout policy for one runtime poller. */
-export interface MailboxPollingTimeoutPolicy {
-    /** Abort the HTTP request when no response headers arrive before this deadline. */
-    requestOpenTimeoutMs: number;
-    /** Stop reading one mailbox SSE response after this long-poll window. */
-    maxPollDurationMs: number;
-    /** Bound one command-local polling turn across sequential remote endpoints. */
-    commandLocalBudgetMs: number;
-}
-/** One mailbox retrieval batch whose message boundaries should stay together. */
-export interface MailboxPollBatch {
-    /** Stable IDs for retained remote bytes; parser return does not acknowledge them. */
-    deliveries?: MailboxDelivery[];
-    source: "local" | "remote";
-    pre: string;
-    eid?: string;
-    messages: Uint8Array[];
-}
-export interface MailboxFetchTimeoutPolicy {
-    requestOpenTimeoutMs: number;
-    maxReadDurationMs: number;
-    readIdleTimeoutMs: number;
-}
-export interface MailboxPollTransportRequest {
-    hab: Hab;
-    targetPre: string;
-    endpoint: {
-        eid: string;
-        url: string;
-    };
-    topics: Record<string, number>;
-    bodyMode: "header" | "body";
-    timeouts: MailboxFetchTimeoutPolicy;
-    services: RuntimeServices;
-}
-export interface MailboxPollTransport {
-    /** Await each complete event consumer; false ends the poll without reading ahead. */
-    poll(args: MailboxPollTransportRequest, consume: (message: MailboxSseMessage) => Operation<boolean | void>): Operation<void>;
-}
-/** Post finite mailbox/EXN caller bytes through the shared progressive, scope-owned sender. */
-export declare function postCesrMessage(url: string, body: Uint8Array, bodyMode: "header" | "body", destination?: string, services?: RuntimeServices, signal?: AbortSignal, onHttpRefusal?: (error: CesrHttpRefusal) => void, onAdmissionRefusal?: (error: ResourceAdmissionError) => void): Operation<void>;
-/** Shared EXN send helper used by CLI commands that want KERIpy-style behavior. */
-export declare function sendExchangeMessage(hby: Habery, hab: Hab, args: {
-    recipient: string;
-    route: string;
-    payload: Record<string, unknown>;
-    topic?: string;
-    modifiers?: Record<string, unknown>;
-    date?: string;
-    dig?: string;
-    embeds?: Record<string, Uint8Array>;
-    delivery?: ExchangeDeliveryPreference;
-}): Operation<ExchangeSendResult>;
-export {};
-//# sourceMappingURL=forwarding.d.ts.map