keri-ts 0.11.0 → 2.0.0

package/types/app/mailbox/mailbox-poller.d.ts

@@ -0,0 +1,149 @@
+/** Recipient mailbox polling: signed queries, awaited SSE intake and persisted cursor progression. */
+import { type Operation } from "effection";
+import type { Habery } from "../identity/habbing.js";
+import type { RuntimeClock } from "../runtime/runtime-clock.js";
+import type { HttpClient } from "../transport/http-client.js";
+import type { MailboxDirector } from "./mailbox-director.js";
+/**
+ * Scalar polling policy overrides; dependencies are constructor arguments.
+ */
+interface MailboxPollerOptions {
+    /**
+     * Optional millisecond header and poll-window overrides.
+     */
+    timeouts?: Partial<MailboxPollingTimeoutPolicy>;
+}
+/**
+ * Retrieve recipient messages from remote mailbox or witness endpoints over HTTP/SSE.
+ *
+ * Each endpoint has an independent worker and durable progress in the director.
+ * Retrieved records are lent to the awaited consumer; protocol intake stays outside.
+ * A provider store in the same runtime is never scanned for local recipient input.
+ */
+export declare class MailboxPoller {
+    /**
+     * Default header acquisition (5 seconds) and absolute poll window (30 seconds).
+     */
+    static readonly DefaultTimeoutPolicy: Readonly<MailboxPollingTimeoutPolicy>;
+    /**
+     * Idle read window after the first complete event, in milliseconds.
+     */
+    static readonly ReadIdleTimeoutMs = 500;
+    /** Borrowed habitat collection used to select mailbox signers. */
+    readonly hby: Habery;
+    /** Shared provider topics and persisted remote cursors. */
+    readonly mailboxDirector: MailboxDirector;
+    /** Existing request-open and SSE-window settings, normalized once. */
+    readonly timeoutPolicy: Readonly<MailboxPollingTimeoutPolicy>;
+    /** Borrowed HTTP client passed to each polling attempt. */
+    readonly http: HttpClient;
+    /** Borrowed clock for this owner's actual network deadlines. */
+    readonly clock: RuntimeClock;
+    /**
+     * Bind polling inputs and dependencies without starting workers or acquiring stores.
+     *
+     * @param hby Borrowed local identities and accepted-state stores.
+     * @param mailboxDirector Borrowed provider/topic/cursor owner.
+     * @param http Borrowed HTTP implementation selected by composition.
+     * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+     * @param options Optional timeout overrides; finite positive values are floored with a 1 ms minimum. Missing/nonpositive/nonfinite values use 5-second headers and 30-second poll windows.
+     */
+    constructor(hby: Habery, mailboxDirector: MailboxDirector, http: HttpClient, clock: RuntimeClock, options?: MailboxPollerOptions);
+    /**
+     * Register one mailbox topic that this poller should retrieve.
+     *
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     */
+    registerTopic(topic: string): void;
+    /**
+     * Poll forever, streaming typed batches into one sink.
+     *
+     * Each remote endpoint progresses independently, and awaits the consumer before
+     * reading the next event or advancing its persisted cursor.
+     *
+     * @param onBatch Awaited endpoint-batch consumer; the durable event cursor advances only after it succeeds. Failure or cancellation leaves that event available for later retrieval.
+     * @throws Consumer/transport failures propagate; endpoint workers are joined on scope exit.
+     */
+    pollDo(onBatch: (batch: MailboxPollBatch) => void | Operation<void>): Operation<never>;
+    /**
+     * Stream one remote response through its consumer before recording cursor progress.
+     *
+     * @param target Mailbox subject habitat plus the actual local signer (a member for groups).
+     * @param endpoint Selected remote endpoint AID and HTTP(S) URL.
+     * @param onBatch Awaited consumer; successful completion precedes durable cursor advancement.
+     */
+    private pollRemoteEndpointOnce;
+    /**
+     * Keep one long-lived worker running for each currently configured remote endpoint.
+     *
+     * @param remoteWorkers Owned worker map, mutated to match current endpoint selection.
+     * @param onBatch Shared awaited consumer used independently by each endpoint worker.
+     * @param topics Current registered topics; no topics means no remote workers.
+     */
+    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.
+     *
+     * @param target Mailbox subject habitat plus the actual local signer (a member for groups).
+     * @param endpoint Selected remote endpoint AID and HTTP(S) URL.
+     * @param onBatch Awaited consumer; successful completion precedes durable cursor advancement.
+     */
+    private remoteEndpointWorker;
+    /**
+     * Select locally pollable subjects without substituting the group for its member signer.
+     *
+     * @returns Local subject/signing pairs; groups without an available local member are omitted.
+     */
+    private remotePollTargets;
+    /**
+     * Choose the actual local signer for a subject's mailbox query.
+     *
+     * @param hab Local subject habitat, possibly a group.
+     * @returns The habitat itself, or its available local group member; null when unresolved.
+     */
+    private pollSignerHab;
+}
+/** Mailbox polling windows in milliseconds; the poller floors positive overrides with a 1 ms minimum. */
+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;
+}
+/** One remote mailbox batch, consumed before its provider cursor advances. */
+export interface MailboxPollBatch {
+    /**
+     * Mailbox subject AID, possibly distinct from the signing member.
+     */
+    pre: string;
+    /**
+     * Mailbox provider AID that supplied this batch; distinct from the subject and query signer.
+     */
+    eid: string;
+    /**
+     * Complete wire messages passed to the awaited batch consumer in order.
+     */
+    messages: Uint8Array[];
+}
+/**
+ * Per-attempt header and SSE window settings in milliseconds.
+ */
+export interface MailboxFetchTimeoutPolicy {
+    /**
+     * Header acquisition deadline in milliseconds.
+     */
+    requestOpenTimeoutMs: number;
+    /**
+     * Absolute SSE read window in milliseconds.
+     */
+    maxReadDurationMs: number;
+    /**
+     * Idle read deadline after a complete event, in milliseconds.
+     */
+    readIdleTimeoutMs: number;
+}
+export {};
+//# sourceMappingURL=mailbox-poller.d.ts.map

package/types/app/mailbox/mailbox-poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-poller.d.ts","sourceRoot":"","sources":["../../../src/app/mailbox/mailbox-poller.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,OAAO,EAAQ,KAAK,SAAS,EAA4B,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAO,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAIhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAI7D;;GAEG;AACH,UAAU,oBAAoB;IAC5B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACjD;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,EAAE,QAAQ,CAAC,2BAA2B,CAAC,CAGxE;IACH;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,iBAAiB,OAAO;IAExC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,2BAA2B,CAAC,CAAC;IAC9D,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;;;;;;;OAQG;gBAED,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,eAAe,EAChC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,oBAAyB;IAUpC;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC;;;;;;;;OAQG;IACF,MAAM,CACL,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,GAC3D,SAAS,CAAC,KAAK,CAAC;IAiBnB;;;;;;OAMG;IACH,OAAO,CAAE,sBAAsB;IA2B/B;;;;;;OAMG;IACH,OAAO,CAAE,iBAAiB;IA8B1B;;;;;;;;;OASG;IACH,OAAO,CAAE,oBAAoB;IAW7B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;CAUtB;AAoBD,yGAAyG;AACzG,MAAM,WAAW,2BAA2B;IAC1C,mFAAmF;IACnF,oBAAoB,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B"}

package/types/app/mailbox/mailbox-sse.d.ts

@@ -0,0 +1,63 @@
+import { type Operation } from "effection";
+import { type RuntimeClock } from "../runtime/runtime-clock.js";
+import type { HttpStreamResponse } from "../transport/http-client.js";
+/** One parsed mailbox SSE payload with its ordered topic metadata. */
+export interface MailboxSseMessage {
+    /**
+     * Nonnegative insertion ordinal supplied by the provider SSE id.
+     */
+    idx: number;
+    /**
+     * UTF-8 bytes from the complete joined SSE data fields.
+     */
+    msg: Uint8Array;
+    /**
+     * Provider event/topic name associated with the ordinal.
+     */
+    topic: string;
+}
+/** Poll timing and cancellation; complete events are delivered to the awaited consumer. */
+export interface MailboxSseOptions {
+    /** End an idle poll after its first complete event; default 500 ms. */
+    idleTimeoutMs?: number;
+    /** Absolute lifetime of one long poll, including its first event; default 30 seconds. */
+    maxDurationMs?: number;
+    /** External cancellation remains separate from a successful poll timeout. */
+    signal?: AbortSignal;
+}
+/**
+ * Consume complete mailbox events with backpressure from the awaited consumer.
+ * Returning false stops the poll without acknowledging an unread event. Timeout,
+ * EOF, and cancellation discard an incomplete final event so its cursor can retry.
+ * The consumer is immediately awaited in this read owner, not scheduled or queued.
+ * Keeping consumer failure inside this scope lets cleanup retain both failures;
+ * a borrowed pull iterator alone cannot observe a later consumer exception.
+ *
+ * @param response Borrowed streaming HTTP response; caller keeps its scope open through this operation.
+ * @param controller Body cancellation owner aborted when the poll window ends.
+ * @param consume Awaited complete-event consumer; false stops the poll and errors propagate before remote cursor advancement.
+ * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+ * @param options Positive idle/absolute windows in milliseconds and optional upstream signal; defaults 500 and 30000.
+ * @throws External cancellation and genuine read/consumer/cleanup errors remain visible; owned window expiry ends the poll.
+ */
+export declare function consumeMailboxSse(response: HttpStreamResponse, controller: AbortController, consume: (message: MailboxSseMessage) => Operation<boolean | void>, clock: RuntimeClock, options?: MailboxSseOptions): Operation<void>;
+/**
+ * Collect a raw SSE diagnostic report for one poll window. Production polling
+ * uses consumeMailboxSse to deliver complete events as they arrive.
+ *
+ * @param response Borrowed streaming HTTP response; caller keeps its scope open through this operation.
+ * @param controller Body cancellation owner aborted when the poll window ends.
+ * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+ * @param options Positive idle/absolute windows in milliseconds and optional upstream signal; defaults 500 and 30000.
+ * @returns Collected text from this bounded diagnostic window.
+ * @throws External cancellation and genuine read/consumer/cleanup errors remain visible; owned window expiry ends the poll.
+ */
+export declare function readMailboxSseBody(response: HttpStreamResponse, controller: AbortController, clock: RuntimeClock, options?: MailboxSseOptions): Operation<string>;
+/**
+ * Parse only terminated events from an already finite diagnostic report.
+ *
+ * @param text Finite diagnostic response text; an unterminated final block is ignored.
+ * @returns Complete valid mailbox events in received order.
+ */
+export declare function parseMailboxSse(text: string): MailboxSseMessage[];
+//# sourceMappingURL=mailbox-sse.d.ts.map

package/types/app/mailbox/mailbox-sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-sse.d.ts","sourceRoot":"","sources":["../../../src/app/mailbox/mailbox-sse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,SAAS,EAAY,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAKtE,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC;IAChB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2FAA2F;AAC3F,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAgDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,EAClE,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,iBAAsB,GAC9B,SAAS,CAAC,IAAI,CAAC,CAyCjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,eAAe,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,iBAAsB,GAC9B,SAAS,CAAC,MAAM,CAAC,CAgCnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAIjE"}

package/types/app/{mailboxing.d.ts → mailbox/mailboxing.d.ts}

@@ -16,14 +16,17 @@
  *   layer serves both root and non-root mailbox/OOBI paths
  */
 import type { Operation } from "effection";
-import { type Mailboxer, type MailboxerOptions } from "../db/mailboxing.js";
-import type { OutboxerLike } from "../db/outboxing.js";
-import type { Hab, Habery } from "./habbing.js";
+import { type Mailboxer, type MailboxerOptions } from "../../db/mailbox/mailboxing.js";
+import type { Hab, Habery } from "../identity/habbing.js";
 /**
  * Derive mailbox open options from one existing habery.
  *
  * This is the supported bridge from core habery state to the additive
  * provider-side mailbox store lifecycle.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param options Explicit store options overriding the Habery-derived name/path/temp/read-only settings.
+ * @returns Derived open settings.
  */
 export declare function mailboxerOptionsForHabery(hby: Habery, options?: Partial<MailboxerOptions>): MailboxerOptions;
 /**
@@ -32,15 +35,21 @@ export declare function mailboxerOptionsForHabery(hby: Habery, options?: Partial
  * Ownership rule:
  * - this helper only derives open settings from habery state
  * - the caller that opens the mailboxer owns its lifecycle
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param options Explicit store options overriding the Habery-derived name/path/temp/read-only settings.
+ * @returns Provider sidecar whose acquisition/lifetime belongs to the caller scope.
  */
 export declare function openMailboxerForHabery(hby: Habery, options?: Partial<MailboxerOptions>): Operation<Mailboxer>;
-/** Return the habery-owned sender retry sidecar when enabled. */
-export declare function getOutboxer(hby: Habery): OutboxerLike;
 /**
  * Build the stored mailbox topic key used by KERIpy-style mailbox storage.
  *
  * Topic buckets are normalized as `pre/topic`, with `topic` already carrying
  * the leading slash when it is a protocol mailbox topic like `/challenge`.
+ *
+ * @param pre AID whose mailbox or accepted state is addressed.
+ * @param topic Protocol mailbox topic; leading slash is normalized where required.
+ * @returns Storage key joining the AID and one slash-prefixed topic.
  */
 export declare function mailboxTopicKey(pre: string, topic: string): string;
 /**
@@ -48,6 +57,12 @@ export declare function mailboxTopicKey(pre: string, topic: string): string;
  *
  * Cursor records store the last seen ordinal, while mailbox queries ask for
  * the next ordinal wanted.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param pre AID whose mailbox or accepted state is addressed.
+ * @param witness Remote endpoint AID used in the durable cursor key.
+ * @param topics Topics requested by the poller.
+ * @returns Next-wanted ordinal map, derived from last-consumed rows plus one.
  */
 export declare function mailboxQueryTopics(hby: Habery, pre: string, witness: string, topics: Iterable<string>): Record<string, number>;
 /**
@@ -55,55 +70,55 @@ export declare function mailboxQueryTopics(hby: Habery, pre: string, witness: st
  *
  * These cursors live in `Baser.tops` because they describe the consumer's
  * remote poll progress, not the provider's stored inbox contents.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param pre AID whose mailbox or accepted state is addressed.
+ * @param witness Remote endpoint AID.
+ * @param topic Protocol mailbox topic; leading slash is normalized where required.
+ * @param idx Last successfully consumed provider ordinal.
  */
 export declare function updateMailboxRemoteCursor(hby: Habery, pre: string, witness: string, topic: string, idx: number): void;
 /**
- * Return the remote mailbox or witness endpoints a local habitat should poll.
+ * Enumerate authorized mailbox providers and the subject's current KEL witnesses.
  *
- * KERIpy parity rule:
- * - mailbox role endpoints take precedence when authorized
- * - otherwise poll one witness mailbox endpoint
- * - SSE uses HTTP(S) only; a TCP-only mailbox keeps role precedence while awaiting HTTP
+ * Both sets are polled, as in KERIpy MailboxDirector. A provider in both roles
+ * shares one history and cursor, so it gets one worker. Locally controlled AIDs
+ * remain eligible for HTTP polling; provider storage is never scanned directly.
+ * Missing HTTP(S) locations produce no poll target until a location is available.
  *
- * The result is intentionally already flattened to one preferred URL per
- * endpoint identifier so runtime pollers can stay focused on mailbox protocol
- * work instead of URL selection policy.
+ * @param hab Mailbox subject habitat supplying accepted roles and current witnesses.
+ * @returns One HTTPS-preferred HTTP target per provider AID, with stable worker keys.
  */
-export declare function mailboxPollEndpoints(hby: Habery, hab: Hab): Array<{
+export declare function mailboxPollEndpoints(hab: Hab): Array<{
     key: string;
     eid: string;
     url: string;
 }>;
-/**
- * Return the currently authorized mailbox endpoints for one remote recipient.
- *
- * `Poster` treats this as the mailbox-first broadcast target set.
- */
-export declare function mailboxDeliveryEndpoints(hab: Hab, recipient: string): Array<{
-    eid: string;
-    url: string;
-}>;
-/**
- * Return the direct controller and agent endpoints for one remote recipient.
- *
- * These are fallback transport targets only when no mailbox endpoints are
- * configured or when the caller explicitly forces direct delivery.
- */
-export declare function directDeliveryEndpoints(hab: Hab, recipient: string): Array<{
-    eid: string;
-    url: string;
-}>;
 /**
  * Read one endpoint's currently stored URLs directly from shared DB state.
  *
  * This stays DB-oriented on purpose so CLI, server, and forwarding code can
  * inspect authoritative location state without carrying a second cache.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param eid Endpoint AID whose accepted location replies are loaded.
+ * @param scheme Optional scheme filter; omission returns all recorded schemes.
+ * @returns Scheme-to-URL map from accepted location state.
  */
 export declare function fetchEndpointUrls(hby: Habery, eid: string, scheme?: string): Record<string, string>;
 /** One locally hosted endpoint plus its advertised preferred URL and base path. */
 export interface HostedEndpoint {
+    /**
+     * Hosted local endpoint AID selected from accepted location state.
+     */
     eid: string;
+    /**
+     * Preferred advertised URL for this endpoint.
+     */
     url: string;
+    /**
+     * Normalized path prefix under which this endpoint is served.
+     */
     basePath: string;
 }
 /**
@@ -113,6 +128,9 @@ export interface HostedEndpoint {
  * and OOBI resources without reparsing the original absolute request path.
  */
 export interface HostedEndpointPathMatch extends HostedEndpoint {
+    /**
+     * Slash-prefixed request path beneath the endpoint's base path.
+     */
     relativePath: string;
 }
 /**
@@ -128,8 +146,17 @@ export interface HostedEndpointPathMatch extends HostedEndpoint {
  * than one hosted AID" mean the same thing. They do not.
  */
 export interface HostedRouteResolution {
+    /**
+     * Whether no endpoint, one endpoint or an ambiguous longest-prefix match was found.
+     */
     kind: "none" | "one" | "ambiguous";
+    /**
+     * Selected endpoint only when kind is one; otherwise null.
+     */
     endpoint: HostedEndpointPathMatch | null;
+    /**
+     * Request-relative path only when one endpoint was selected.
+     */
     relativePath: string | null;
 }
 /**
@@ -140,6 +167,12 @@ export interface HostedRouteResolution {
  * - optionally append a resource suffix like `/mailboxes`
  * - when more than one local endpoint matches, the caller must treat that as
  *   ambiguous instead of guessing
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param pathname Incoming URL pathname to compare against accepted endpoint base paths.
+ * @param resourceSuffix Protocol resource suffix sought beneath the hosted base path.
+ * @param eids Optional explicit hosted-AID filter; do not infer host eligibility from all local identities.
+ * @returns Matching hosted endpoint projection; ambiguity follows this helper's documented selection policy.
  */
 export declare function hostedEndpointMatches(hby: Habery, pathname: string, resourceSuffix?: string, eids?: Iterable<string>): HostedEndpoint[];
 /**
@@ -147,6 +180,12 @@ export declare function hostedEndpointMatches(hby: Habery, pathname: string, res
  *
  * Callers that need ambiguity details should use `hostedEndpointPathMatches()`
  * directly.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param pathname Incoming URL pathname to compare against accepted endpoint base paths.
+ * @param resourceSuffix Protocol resource suffix sought beneath the hosted base path.
+ * @param eids Optional explicit hosted-AID filter; do not infer host eligibility from all local identities.
+ * @returns Matching hosted endpoint projection; ambiguity follows this helper's documented selection policy.
  */
 export declare function hostedEndpointForPath(hby: Habery, pathname: string, resourceSuffix?: string, eids?: Iterable<string>): HostedEndpoint | null;
 /**
@@ -158,6 +197,11 @@ export declare function hostedEndpointForPath(hby: Habery, pathname: string, res
  * - non-root endpoints match their exact base path or any subpath beneath it
  * - callers should prefer the longest matching base path and treat ties as
  *   ambiguous instead of guessing
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param pathname Incoming URL pathname to compare against accepted endpoint base paths.
+ * @param eids Optional explicit hosted-AID filter; do not infer host eligibility from all local identities.
+ * @returns Matching hosted endpoint projection; ambiguity follows this helper's documented selection policy.
  */
 export declare function hostedEndpointPathMatches(hby: Habery, pathname: string, eids?: Iterable<string>): HostedEndpointPathMatch[];
 /**
@@ -170,6 +214,12 @@ export declare function hostedEndpointPathMatches(hby: Habery, pathname: string,
  * hit?" Keeping it here means `protocol-handler.ts` can reason in terms of
  * explicit route matches while `server.ts` stays out of endpoint-selection
  * policy entirely.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param pathname Incoming URL pathname to compare against accepted endpoint base paths.
+ * @param resourceSuffix Protocol resource suffix sought beneath the hosted base path.
+ * @param eids Optional explicit hosted-AID filter; do not infer host eligibility from all local identities.
+ * @returns Matching hosted endpoint projection; ambiguity follows this helper's documented selection policy.
  */
 export declare function resolveHostedEndpointPath(hby: Habery, pathname: string, resourceSuffix?: string, eids?: Iterable<string>): HostedRouteResolution;
 /**
@@ -177,26 +227,22 @@ export declare function resolveHostedEndpointPath(hby: Habery, pathname: string,
  *
  * This converts stored end-role location shape into the transport-ready tuples
  * used by forwarding and polling logic.
+ *
+ * @param roleUrls Accepted endpoint-AID to scheme/URL map for one role, possibly absent.
+ * @returns All endpoint/preferred-URL pairs.
  */
 export declare function flattenRoleUrls(roleUrls?: Record<string, Record<string, string>>): Array<{
     eid: string;
     url: string;
 }>;
-/**
- * Return the deterministic first preferred endpoint from one role map.
- *
- * Witness polling intentionally uses a stable choice instead of a randomized
- * one so local cursor progression is deterministic.
- */
-export declare function firstSortedEndpoint(roleUrls?: Record<string, Record<string, string>>): {
-    eid: string;
-    url: string;
-} | null;
 /**
  * Return the preferred URL for one endpoint location set.
  *
  * HTTPS wins when present because mailbox and admin URLs are externally
  * advertised endpoints.
+ *
+ * @param urls Accepted scheme-to-URL map for one endpoint.
+ * @returns HTTPS, then HTTP, then TCP; null when no supported location is recorded.
  */
 export declare function preferredUrl(urls: Record<string, string>): string | null;
 /**
@@ -204,6 +250,9 @@ export declare function preferredUrl(urls: Record<string, string>): string | nul
  *
  * Mailbox and OOBI hosts serve routes relative to this base path, not only
  * from `/`.
+ *
+ * @param url Advertised endpoint URL; its pathname defines hosted routing.
+ * @returns Normalized base pathname.
  */
 export declare function endpointBasePath(url: string): string;
 //# sourceMappingURL=mailboxing.d.ts.map

package/types/app/mailbox/mailboxing.d.ts.map

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

package/types/app/mailbox/topic-routing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * KERIpy `/fwd` modifiers use the bare topic name, e.g. `multisig`.
+ *
+ * @param topic Protocol mailbox topic; leading slash is normalized where required.
+ * @returns Bare /fwd modifier topic.
+ */
+export declare function transportMailboxTopic(topic: string): string;
+/**
+ * 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?"
+ *
+ * @param route Exchange route whose first nonempty segment chooses the mailbox topic.
+ * @returns Derived topic under the existing route mapping.
+ */
+export declare function mailboxTopicForRoute(route: string): string;
+//# sourceMappingURL=topic-routing.d.ts.map

package/types/app/mailbox/topic-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-routing.d.ts","sourceRoot":"","sources":["../../../src/app/mailbox/topic-routing.ts"],"names":[],"mappings":"AAwCA;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/types/app/multisig/group-members.d.ts

@@ -0,0 +1,60 @@
+import type { SerderKERI, Verfer } from "cesr-ts";
+import { TransIdxSigGroup } from "../../core/dispatch.js";
+import type { Baser } from "../../db/basing.js";
+import type { Hab, Habery } from "../identity/habbing.js";
+/** True when the selected habitat is a local group habitat. */
+export declare function isLocalGroupHab(hby: Habery, hab: Hab): boolean;
+/** Return the local member habitat for a persisted group identifier. */
+export declare function localGroupMember(hby: Habery, groupPre: string): Hab;
+/** Find the member's latest accepted single-key contribution to the supplied group keys. */
+export declare function latestGroupContribution(db: Baser, member: string, verfers: readonly Verfer[]): {
+    event: SerderKERI;
+    index: number;
+    verfer: Verfer;
+} | null;
+/** Exact accepted group event that supplies the ordinary witnesser election. */
+export interface GroupCoordinator {
+    sn: number;
+    said: string;
+}
+/**
+ * Verify an accepted coordinator against its historical establishment threshold.
+ * index is the initial election; a frozen operation rechecks indices without
+ * replacing its earlier choice when more valid signatures arrive.
+ */
+export declare function groupWitnesserSelection(db: Baser, group: string, { sn, said }: GroupCoordinator): {
+    establishment: SerderKERI;
+    index: number;
+    indices: number[];
+} | null;
+/** Return current group signing member AIDs in signing-index order. */
+export declare function groupSigningMembers(hby: Habery, groupPre: string): string[];
+/** Return the first locally available habitat from `members`, if any. */
+export declare function findLocalGroupMember(hby: Habery, members: readonly string[]): Hab | null;
+/** Return unique non-empty member AIDs while preserving first-seen order. */
+export declare function uniqueMembers(members: readonly string[]): string[];
+/** Match a group signing key to one member's accepted establishment history, including retired keys. */
+export declare function groupMemberHasKey(db: Baser, member: string, key: string): boolean;
+/**
+ * Select only a cryptographically valid local partial at an accepted group establishment.
+ * The shared esigs table can hold unverified escrow candidates, so a matching
+ * index or an authenticated parent wrapper alone is not recorded child approval.
+ */
+export declare function localIpexContribution(db: Baser, member: string, embedded: SerderKERI, proofs: readonly TransIdxSigGroup[]): TransIdxSigGroup | null;
+/** Members of a group's latest accepted establishment event, ordered by key index. */
+export interface AcceptedGroupMembers {
+    event: SerderKERI;
+    smids: string[];
+    rmids: string[];
+}
+/**
+ * Derive the members of `group`'s latest accepted establishment event from
+ * local KELs, as KERIpy `GroupHab.acceptedMembers`.
+ *
+ * Each signing key is attributed to the candidate whose latest contributing
+ * establishment event supplied it, and each next-key digest to the candidate
+ * whose establishment event committed to it. Returns null when the event is
+ * missing or any key cannot be attributed to exactly one candidate.
+ */
+export declare function acceptedGroupMembers(db: Baser, group: string, candidates: Iterable<string>): AcceptedGroupMembers | null;
+//# sourceMappingURL=group-members.d.ts.map

package/types/app/multisig/group-members.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-members.d.ts","sourceRoot":"","sources":["../../../src/app/multisig/group-members.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAE1D,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAE9D;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAOnE;AAED,4FAA4F;AAC5F,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,KAAK,EACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAe7D;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,KAAK,EACT,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,gBAAgB,GAC7B;IAAE,aAAa,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAkBxE;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAO3E;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,GAAG,IAAI,CAQxF;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAElE;AAED,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAMjF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,KAAK,EACT,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAClC,gBAAgB,GAAG,IAAI,CAczB;AAED,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,KAAK,EACT,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC3B,oBAAoB,GAAG,IAAI,CAqC7B"}