keri-ts 2.0.1 → 2.2.0

package/types/app/ipex/unblinding-workflow.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Runtime-owned operations for single-signature IPEX Unblind (proof release for one live presentation).
+ *
+ * One explicit consent step, the disclosee's. The disclosee calls `requestUnblind`: it approves the exact live
+ * Grant, signs the query for the missing public suffix and returns after local commit. The discloser has no
+ * approval step: it consented by signing the Grant, so an owner that authenticated a peer query for a live
+ * Grant its identifier sent replies on its own, and `processOnce` adopts and delivers that reply under the
+ * Grant's deadline (KERIpy keeps a local approve gate; the wire is unchanged).
+ * `UnblindingOperations.processOnce` also sends and resends the unchanged query each second, finishes the
+ * Grant once the authenticated reply is complete, and ends the operation at the Grant's original exchange
+ * deadline. The only signing outside the Grant's own scope is the requester's query. A record that is active
+ * with no live operation reads `interrupted` (or `expired` past the deadline) and nothing is sent for it
+ * after a restart; a repeated peer query is answered again from stored state.
+ *
+ * Workflow-contract shape (`app/runtime/workflow-contract.ts`): `requestUnblind` returns after local
+ * commit and never wait for the peer, `unblindingStatus` is a pure read, `waitForUnblinding` only observes
+ * and returns a `WaitResult`, `abandonUnblinding` is local. Completion creates no Admit.
+ *
+ * There is no operation store; status is the live table plus what the stores prove. Durable: the Grant and
+ * its deadline, and the finished proof view. A requester whose Grant's proofs are current reads `done`; one
+ * whose Grant is still live with proofs missing and no live operation reads `interrupted` (request it
+ * again), and past the deadline `expired`. A responder is driven entirely by a peer's query, so a
+ * responder's operation exists only while live: its `done`, `failed` and `expired` readings, like every
+ * requester `abandoned` and `failed` reading, are remembered only until the process ends, and a responder
+ * Grant with no live operation throws. Memory only: the owner's approval and frozen query/reply, resend
+ * timers, the consent time. Per-identifier {@link Unblind} owners come through a narrow interface (`runtime.ipex`). Group identifiers
+ * are refused; group Unblind belongs to the group proposal API.
+ */
+import { type CesrFrame, SerderKERI } from "cesr-ts";
+import { type Operation } from "effection";
+import { Unblind } from "../../acdc/unblinding.js";
+import type { Exchanger, ExchangeRouteHandler } from "../exchanges/exchanging.js";
+import type { Hab, Habery } from "../identity/habbing.js";
+import { type Multiplexor } from "../multisig/grouping.js";
+import type { ProtocolProcessor } from "../protocol/protocol-processing.js";
+import { type DeliveryFailure, DeliveryOutbox } from "../runtime/delivery-outbox.js";
+import type { RetryPolicy } from "../runtime/retry-backoff.js";
+import type { RuntimeClock } from "../runtime/runtime-clock.js";
+import { type ChangeSink, type WaitResult } from "../runtime/workflow-contract.js";
+import type { IssuanceDelivery } from "./issuance.js";
+/** Milliseconds between resends of the unchanged disclosee query, as `tufa ipex unblind` does. */
+export declare const UNBLIND_QUERY_RESEND_MS = 1000;
+/** Which side of the presentation the local identifier is. */
+export type UnblindingRole = "requester" | "responder";
+/** Terminal states that are not completion; each carries a reason. */
+export type UnblindingEndState = "abandoned" | "interrupted" | "expired" | "failed";
+/** Where an active Unblind is. */
+export type UnblindingPhase = "awaitingReply" | "proving";
+/** Status of one Unblind, discriminated on `state`. A pure read. */
+export type UnblindingStatus = {
+    state: "active";
+    role: UnblindingRole;
+    phase: UnblindingPhase;
+    deadline: string;
+    failure?: DeliveryFailure;
+} | {
+    state: "done";
+    role: UnblindingRole;
+} | {
+    state: UnblindingEndState;
+    role: UnblindingRole;
+    reason: string;
+};
+/** Collaborators only a group needs; an owner without them unblinds as an individual alone. */
+export interface GroupUnblindDeps {
+    /** Where the Unblind child wrappers (`/multisig/qry`, `/multisig/rpy`) are delegated; one owner per runtime registers. */
+    readonly mux: Pick<Multiplexor, "addChildHandler" | "removeChildHandler">;
+    /** Local intake of this member's own contribution and of the other members'. */
+    readonly protocol: Pick<ProtocolProcessor, "dispatch">;
+}
+/** Narrow collaborators of the Unblind owner. Hosts adapt their runtime to this once. */
+export interface UnblindingDeps {
+    readonly hby: Habery;
+    readonly exc: Pick<Exchanger, "retainedInput" | "exchangeDeadline" | "complete" | "verifyGrantProofs">;
+    /** Collaborators of group Unblind; absent, this owner refuses group identifiers. */
+    readonly group?: GroupUnblindDeps;
+    /** Per-identifier Unblind owners (`runtime.ipex`), so several identifiers can unblind on one runtime. */
+    readonly unblinds: {
+        unblind(hab: Hab): Unblind;
+        unblindOwners(): Iterable<Unblind>;
+    };
+    readonly delivery: IssuanceDelivery;
+    /** Same clock the exchanger and Unblind owners were composed with. */
+    readonly clock: RuntimeClock;
+    /** Delivery retry delays; the production policy when absent. */
+    readonly retry?: Readonly<RetryPolicy>;
+    readonly changes?: ChangeSink;
+}
+/** One operation the user consented to or the discloser owes; exists only while its approval is live in memory. */
+interface LiveUnblinding {
+    /** SAID of the live Grant. */
+    readonly grant: string;
+    /** Presentation transaction id. */
+    readonly xid: string;
+    readonly role: UnblindingRole;
+    /** The Grant's original exchange deadline (ISO 8601). */
+    readonly deadline: string;
+    readonly hab: Hab;
+    readonly owner: Unblind;
+    /** The discloser of the Grant: where the query goes. */
+    readonly peer: string;
+    readonly expires: bigint;
+    /** Requester: the frozen signed query, resent unchanged. */
+    query?: Uint8Array;
+    /** When {@link query} was signed (host clock, ms); it is re-dated once older than the single-key window. */
+    queryAt: number;
+    nextQuery: number;
+    /** Group party state; such an operation never re-dates its threshold query. */
+    group?: GroupUnblind;
+    phase: UnblindingPhase;
+    /** Signed bytes the steps decided to send; a peer briefly offline is retried until the Grant deadline. */
+    readonly outbox: DeliveryOutbox;
+    /** The steps are done; the operation ends once the outbox is empty. */
+    finished: boolean;
+    /** A step is running; overlapping `processOnce` calls skip it. */
+    busy: boolean;
+}
+/** Per-operation state of a group party; memory only. */
+declare class GroupUnblind {
+    readonly member: Hab;
+    readonly proposer: string;
+    readonly pending: Map<string, {
+        parent: SerderKERI;
+        child: CesrFrame;
+    }>;
+    readonly seen: Set<string>;
+    /** The exact DH-style body this member contributes to, once frozen. */
+    frozen?: Uint8Array;
+    contributed: boolean;
+    finished: boolean;
+    started: boolean;
+    constructor(member: Hab, proposer: string);
+}
+/** What a consent step selected. */
+export interface UnblindingBegun {
+    grant: string;
+    xid: string;
+    role: UnblindingRole;
+}
+/** Choices of a consent to Unblind; the party is the live Grant's recipient (request) or sender (answer). */
+export interface UnblindingOptions {
+    /** A group requires the current signing member that authors the query (disclosee) or the reply (discloser). */
+    proposer?: string;
+    /** Ordinary state labels the owner treats as the credential-state vocabulary; omitted uses the owner's default. */
+    states?: readonly string[];
+}
+/** What an operation that finished or ended in this process reports until the process ends. */
+type SettledUnblinding = {
+    role: UnblindingRole;
+    state: "done";
+} | {
+    role: UnblindingRole;
+    state: UnblindingEndState;
+    reason: string;
+};
+/** The live operations table and its driver. One per host runtime; every identifier may unblind through it. */
+export declare class UnblindingOperations {
+    readonly deps: UnblindingDeps;
+    /** Operations whose approval is live in this process. Internal to this module's functions. */
+    readonly live: Map<string, LiveUnblinding>;
+    /** Operations that finished or ended in this process; not durable, see the module doc. */
+    readonly settled: Map<string, SettledUnblinding>;
+    /** The Unblind child handlers registered on the multiplexor, once a group operation began. */
+    groupRoutes: Array<[string, ExchangeRouteHandler]> | null;
+    constructor(deps: UnblindingDeps);
+    /**
+     * Whether a pass has work: a live operation, or an owner holds an authenticated peer query whose reply is
+     * owed (an in-memory walk of the owners, no store read).
+     */
+    active(): boolean;
+    /** Advance every live operation by one pass, each bounded by its Grant deadline. */
+    processOnce(): Operation<void>;
+    /**
+     * Take on the replies the owners owe. The discloser has no consent step: an owner that authenticated a
+     * peer query for a live Grant its identifier sent holds the operation, and this delivers its reply
+     * under the Grant's deadline. Decided from the owners' state, so a restarted process re-answers a
+     * repeated query.
+     */
+    private adopt;
+    /** End a live operation: release the approval, remember why until the process ends, tell the sink. */
+    end(op: LiveUnblinding, state: UnblindingEndState, reason: string): void;
+    /** Drop the live entry and the owner's approval and frozen messages; delivered bytes stay the peer's. */
+    private release;
+    private finished;
+    private timer;
+    private setPhase;
+    /**
+     * One pass of a group party, in the order of the CLI loop it replaces: take in the members' wrappers, contribute
+     * this member's signature once to the frozen body, publish it to the other members, and finish.
+     */
+    private stepGroup;
+    /** One pass, in the order of the CLI loop it replaces. */
+    private step;
+    /**
+     * The query to send now: the signed bytes unchanged while they are timely, and a re-dated one
+     * (`Unblind.requery`: same frozen request, new `dt`, SAID and signatures) once they are older than the
+     * single-key window, which the discloser's KRAM would drop as stale. Re-signing happens only here, inside
+     * the consent that began the operation; a registry head that moved since fails the operation instead. A
+     * group threshold query cannot be re-dated by one member; group Unblind is not run here.
+     */
+    private current;
+    private finishedStep;
+    /** One pass: send what is queued, step only once the queue is empty, send what the step queued. */
+    private advance;
+}
+/**
+ * The disclosee's consent to request the missing proofs for one live Grant: approves the Grant, signs the
+ * query over the missing accepted public suffix and records it. Returns after local commit; `processOnce`
+ * sends and resends it. A Grant whose proofs are already current reads `done` at once.
+ *
+ * @throws ValidationError for a Grant that is not live and addressed to a local identifier, a group without a
+ * current signing member as proposer, or an Unblind already begun for it.
+ */
+export declare function requestUnblind(ops: UnblindingOperations, grant: string, options?: UnblindingOptions): UnblindingBegun;
+/**
+ * A group discloser member's consent to answer a live presentation: approves the Grant, so that this member
+ * contributes its signature to the one threshold reply (the proposer authors the reply once the disclosee's
+ * authenticated query arrives; the others contribute to it). Returns after local commit; `processOnce` does
+ * the rest. An individual discloser needs no consent: its owner answers an authenticated query by itself.
+ *
+ * @throws ValidationError for an individual identifier, a Grant the group did not send, a proposer that is not a
+ * current signing member, or an Unblind already begun.
+ */
+export declare function answerUnblind(ops: UnblindingOperations, grant: string, options?: UnblindingOptions): UnblindingBegun;
+/**
+ * Pure read of one Unblind: what finished or ended in this process, the live table, and otherwise what the
+ * stores prove for the requester (see the module doc for what a reload loses). A requester's Grant whose
+ * proofs are not current and that no live operation holds reads `interrupted`, or `expired` past the Grant
+ * deadline; that is a statement, not a write.
+ *
+ * @throws ValidationError when `grant` is not a Grant a local identifier is the disclosee of, and no
+ * operation for it is live or remembered.
+ */
+export declare function unblindingStatus(ops: UnblindingOperations, grant: string): UnblindingStatus;
+/** Options for {@link waitForUnblinding}. */
+export interface UnblindingWaitOptions {
+    /** Wall-clock budget. */
+    timeoutMs: number;
+    clock?: RuntimeClock;
+}
+/**
+ * Observe until the Unblind is done or ended, or the budget expires. Starts no worker and drives nothing:
+ * someone else must call `processOnce`.
+ */
+export declare function waitForUnblinding(ops: UnblindingOperations, grant: string, { timeoutMs, clock }: UnblindingWaitOptions): Operation<WaitResult<UnblindingStatus>>;
+/**
+ * Local abandon: release the approval and frozen messages and read `abandoned` until the process ends. Does
+ * not message the peer and does not undo proofs already finished. Does nothing to an Unblind that is already
+ * done or ended.
+ *
+ * @throws ValidationError when no Unblind was begun for `grant`.
+ */
+export declare function abandonUnblinding(ops: UnblindingOperations, grant: string, reason?: string): void;
+export {};
+//# sourceMappingURL=unblinding-workflow.d.ts.map

package/types/app/ipex/unblinding-workflow.d.ts.map

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

package/types/app/mailbox/ipex-arrival.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Poll-and-settle for credential IPEX traffic: what arrived through the mailbox,
+ * settling the grants already stored, and waiting for new state to appear.
+ *
+ * The pieces follow the workflow contract. `settleStoredGrants` is the explicit
+ * operation: it replays stored grant artifacts that have not yet saved their
+ * credential. `ipexArrivalStatus` is a pure synchronous read of durable state
+ * (accepted `exns` and `reger.saved`) against a baseline taken earlier.
+ * `waitForIpexArrival` only observes: it starts no worker and returns a
+ * {@link WaitResult} instead of throwing on its deadline.
+ *
+ * How hosts use it:
+ * - A wallet's runtime already polls its mailboxes continuously, so it takes a
+ *   baseline, then calls `ipexArrivalStatus` from its UI or `waitForIpexArrival`
+ *   (passing `settle` bound to `settleStoredGrants` when it wants stored grants
+ *   replayed). It runs no workers and no poller of its own.
+ * - `tufa ipex poll` has no running runtime, so it runs the workers itself
+ *   (`withRuntimeWorkers` plus a mailbox poller whose batches pass through
+ *   {@link MailboxIntakeTally.track}) around the same wait.
+ *
+ * Dependencies are narrow collaborators, not an AgentRuntime (ADR-0013).
+ */
+import type { SerderKERI, Versionage } from "cesr-ts";
+import { type Operation } from "effection";
+import type { Reger } from "../../db/reger.js";
+import type { Habery } from "../identity/habbing.js";
+import type { ProtocolProcessor } from "../protocol/protocol-processing.js";
+import { type RuntimeClock } from "../runtime/runtime-clock.js";
+import type { WaitResult } from "../runtime/workflow-contract.js";
+import type { MailboxPollBatch } from "./mailbox-poller.js";
+/** Stores the status read inspects. A `Habery` and a `Reger` fit. */
+export interface IpexArrivalDeps {
+    /** Accepted exchange messages. */
+    readonly hby: Pick<Habery, "db">;
+    /** Saved credential index. */
+    readonly reger: Pick<Reger, "saved">;
+}
+/** Collaborators for replaying stored grants. */
+export interface StoredGrantSettleDeps extends IpexArrivalDeps {
+    /** Needs the full `Habery`: stored artifacts are rebuilt from its escrow paths. */
+    readonly hby: Habery;
+    /** Receive processor that accepts the replayed grant artifacts. */
+    readonly protocol: ProtocolProcessor;
+}
+/** Said sets taken before waiting; arrivals are everything beyond them. */
+export interface IpexBaseline {
+    readonly exns: ReadonlySet<string>;
+    readonly saved: ReadonlySet<string>;
+}
+/**
+ * Counts mailbox batches a host has consumed and whether one is still settling.
+ * Process-local: it describes this host's intake, so it is not part of any durable
+ * status. A wallet that does not track batches simply omits it.
+ */
+export declare class MailboxIntakeTally {
+    receiving: number;
+    batches: number;
+    messages: number;
+    /** Run the host's settle step for one batch, counting it when settled. */
+    track(batch: MailboxPollBatch, settle: () => Operation<void>): Operation<void>;
+}
+/** What arrived since the baseline. `arrived` once new state exists and no batch is mid-settle. */
+export interface IpexArrivalStatus {
+    state: "waiting" | "arrived";
+    /** New accepted `/ipex/` exchange messages, in store order. */
+    ipex: SerderKERI[];
+    /** Said of each newly saved credential. */
+    saved: string[];
+    /** True while the host's tally has a batch mid-settle (state may be partially visible). */
+    receiving: boolean;
+}
+/** Options for {@link waitForIpexArrival}. */
+export interface WaitForIpexArrivalOptions {
+    /** Wall-clock budget. */
+    timeoutMs: number;
+    /** Host intake tally; when omitted no batch is ever considered mid-settle. */
+    tally?: MailboxIntakeTally;
+    /** Elapsed milliseconds between reads. */
+    pollMs?: number;
+    clock?: RuntimeClock;
+}
+/** Deps and host hook for {@link waitForIpexArrival}. */
+export interface IpexArrivalWaitDeps extends IpexArrivalDeps {
+    /** Host-supplied step run before each read, such as `settleStoredGrants`. */
+    readonly settle?: () => Operation<void>;
+}
+/** Snapshot the said sets that later arrivals are measured against. */
+export declare function ipexBaseline(deps: IpexArrivalDeps): IpexBaseline;
+/** Pure read of what arrived since `baseline`. Starts nothing and writes nothing. */
+export declare function ipexArrivalStatus(deps: IpexArrivalDeps, baseline: IpexBaseline, tally?: MailboxIntakeTally): IpexArrivalStatus;
+/**
+ * Replay accepted grant artifacts whose credential is not yet saved, so a grant
+ * stored before the credential arrived settles once its evidence is complete.
+ */
+export declare function settleStoredGrants(deps: StoredGrantSettleDeps, gvrsn?: Versionage): Operation<void>;
+/**
+ * Observe until new IPEX state has arrived and settled, or the budget expires.
+ * Runs `deps.settle` before each read; starts no worker.
+ *
+ * @returns `settled` with the arrival, or `timed-out` with the last read (which
+ * may already hold arrivals that were still mid-settle).
+ */
+export declare function waitForIpexArrival(deps: IpexArrivalWaitDeps, baseline: IpexBaseline, { timeoutMs, tally, pollMs, clock }: WaitForIpexArrivalOptions): Operation<WaitResult<IpexArrivalStatus>>;
+//# sourceMappingURL=ipex-arrival.d.ts.map

package/types/app/mailbox/ipex-arrival.d.ts.map

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

package/types/app/mailbox/kel-publisher.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Pushing an identifier's KEL to its mailboxes as a runtime reaction: after a rotation completes, every
+ * configured, active mailbox is told the new key state, because a mailbox authenticates the owner's polls
+ * against the KEL it holds.
+ *
+ * The durable state is one record per (identifier, mailbox), `Baser.kpub`: the establishment event whose KEL
+ * the mailbox last answered 2xx for, and, when publishing used up its budget, the event it gave up on. A
+ * pass derives what is owed: for each local identifier (groups included) and each mailbox it has an
+ * authorized role with and a URL for, a post is owed unless the record shows the identifier's latest
+ * establishment event. A {@link RotatedCue} only marks the identifier for the next tock, so a lost cue, a bare `Hab.rotate`, a
+ * member that did not sign a group event, a crash and a one-shot CLI host are all found by derivation. A
+ * crash between the post and the record costs one harmless resend, since a host drops duplicate events.
+ *
+ * An event is published only once it is complete: fully witnessed and, for a delegated identifier, its
+ * authorizing source seal is stored (`Baser.aess`). Witnesses are not told; receipting already gives them
+ * the event.
+ *
+ * A failed post is retried with a doubling delay up to {@link KEL_PUBLISH_MAX_DELAY_MS}, in memory, and given
+ * up when the next attempt would start more than {@link KEL_PUBLISH_BUDGET_MS} after the first. Giving up
+ * writes `failed` to the record and a change to the sink. A timed-out entry is not retried on its own: a new
+ * rotation, a successful poll of that mailbox (the mailbox is evidently back), a successful 403 repair, a
+ * `prompt`, or the next runtime open (memory starts empty, so each owed entry gets a fresh budget) re-arms it.
+ * A host that cannot take a multi-message stream (KERIpy answers 400 or 406) is recorded as told: it does
+ * not authenticate polls, so nothing is lost.
+ */
+import { type Operation } from "effection";
+import type { RotatedCue } from "../../core/cues.js";
+import { Deck } from "../../core/deck.js";
+import { type DoerPacing } from "../runtime/doing.js";
+import type { RetryPolicy } from "../runtime/retry-backoff.js";
+import type { RuntimeClock } from "../runtime/runtime-clock.js";
+import { type ChangeSink, type WaitResult } from "../runtime/workflow-contract.js";
+import { type KelPublishingDeps, type MailboxPublication } from "./kel-publishing.js";
+/** Most posts one `processOnce` attempts, so a first pass over a large store cannot stall the fiber. */
+export declare const KelSendsPerPass = 4;
+/** Delay after a post's first failure; doubles per attempt up to {@link KEL_PUBLISH_MAX_DELAY_MS}. */
+export declare const KEL_PUBLISH_BASE_MS = 1000;
+export declare const KEL_PUBLISH_MAX_DELAY_MS = 60000;
+/** Give up when the next attempt would start more than this long after the first. */
+export declare const KEL_PUBLISH_BUDGET_MS = 300000;
+/** The production retry policy of KEL posts: `boundMs` is the budget. */
+export declare const DEFAULT_KEL_PUBLISH_RETRY: Readonly<RetryPolicy>;
+/** Milliseconds between publisher passes; retries start at one second, so a finer tock buys nothing. */
+export declare const KEL_PUBLISHER_TOCK_MS = 250;
+/** Tocks between full sweeps of every identifier: 240 tocks of 250 ms is a minute. */
+export declare const KEL_PUBLISHER_SWEEP_TOCKS = 240;
+/** The production pacing of the publisher fiber. */
+export declare const KEL_PUBLISHER_PACING: Readonly<DoerPacing>;
+/** Collaborators of the publisher. */
+export interface KelPublisherDeps extends KelPublishingDeps {
+    /** Optional sink told `{kind:"event", id:"<pre>:<sn>"}` after each attempt and when a publication is given up. */
+    readonly changes?: ChangeSink;
+    /** Retry delays of a failed post, and the budget after which it is given up; {@link DEFAULT_KEL_PUBLISH_RETRY} when absent. */
+    readonly retry?: Readonly<RetryPolicy>;
+}
+/**
+ * Where one (identifier, mailbox) stands: `published` (the record shows the latest establishment event),
+ * `pending` (owed, being sent or waiting out a retry delay), `waiting` (owed but gated: unwitnessed,
+ * unanchored or no URL) or `timed-out` (given up in this process; see the module comment for what re-arms it).
+ */
+export interface KelPublicationStatus {
+    readonly pre: string;
+    readonly mailbox: string;
+    readonly state: "published" | "pending" | "waiting" | "timed-out";
+    /** The establishment event the identifier's mailboxes should hold. */
+    readonly said: string;
+    readonly attempts: number;
+    readonly lastFailure?: string;
+    /** When the next attempt is due (ISO-8601), for a pending entry that has failed. */
+    readonly retryAt?: string;
+}
+/** Every (identifier, mailbox) pair, derived from the stores at the time of the read. */
+export interface KelPublisherStatus {
+    readonly entries: readonly KelPublicationStatus[];
+}
+/** Derives, sends and records the KEL posts a wallet's identifiers owe their mailboxes. */
+export declare class KelPublisher {
+    #private;
+    /** Completion points push here; the next tock gives that identifier's entries a fresh budget. */
+    readonly rotated: Deck<RotatedCue>;
+    /** A failure that escapes a pass is counted and kept here; the fiber keeps running. */
+    readonly health: {
+        faults: number;
+        last: {
+            error: unknown;
+            at: number;
+        } | null;
+    };
+    constructor(deps: KelPublisherDeps);
+    /**
+     * Give `pre`'s entries a fresh budget and derive them on the next tock; with `mailbox`, re-arm only that mailbox's
+     * entry, and only if it timed out (the poller calls this after a successful poll).
+     */
+    prompt(pre: string, mailbox?: string): void;
+    /**
+     * A mailbox refused the owner's poll with 403: whatever the record says it holds, it cannot authenticate
+     * the owner (it lost its state, or accepted a post it then escrowed). Forget what it was given, so the next
+     * pass posts the KEL again, and give the entry a fresh budget. The poller calls this at most once per backoff
+     * period, which is also the most this posts; a mailbox that never recovers is given up on like any other.
+     */
+    repair(pre: string, mailbox: string): void;
+    /**
+     * The full check: forget records of mailboxes no longer authorized, and mark every identifier for derivation.
+     * A walk of all identifiers, so a host runs it at open and every many tocks.
+     */
+    sweep(): void;
+    /**
+     * The fixed-tock pass: drain the cues, derive the marked identifiers and those still owed, then send up to
+     * {@link KelSendsPerPass} due posts, each within `timeoutMs` for the mailbox's answer. An idle pass reads no
+     * store. A post is recorded when the mailbox answers 2xx; a failure is retried on the schedule until the budget
+     * is used up. Never throws on a remote failure; every attempt is returned.
+     */
+    processDue({ timeoutMs }?: {
+        timeoutMs?: number;
+    }): Operation<MailboxPublication[]>;
+    /** A sweep and a pass: what a one-shot host, or a test, runs once. */
+    processOnce(options?: {
+        timeoutMs?: number;
+    }): Operation<MailboxPublication[]>;
+    /** Pure read of every (identifier, mailbox) pair and where it stands. */
+    status(): KelPublisherStatus;
+    /** Pure read of one identifier's mailboxes; the cheap read for a wait on a single identifier. */
+    statusOf(pre: string): KelPublicationStatus[];
+    /**
+     * Observe until every mailbox of `pre` is `published` or `timed-out`, or the deadline passes. Starts no
+     * worker: the runtime's publisher fiber (or a host's own `processOnce`) makes the progress. A waiting entry
+     * (unwitnessed, unanchored, no URL) keeps the wait open.
+     */
+    waitForPublication(pre: string, { timeoutMs, pollMs }: {
+        timeoutMs: number;
+        pollMs?: number;
+    }): Operation<WaitResult<KelPublisherStatus>>;
+}
+/**
+ * Run the publisher on its own fiber until halted, as a fixed-tock doer: a sweep on tock 0 and every
+ * `pacing.sweepTocks`, a pass on every tock, then a wait of one tock. A mailbox that hangs holds up only this
+ * fiber, never the operation owners. A failure that escapes a pass is counted in `publisher.health` and the
+ * loop keeps running.
+ */
+export declare function kelPublisherDo(publisher: KelPublisher, clock: RuntimeClock, pacing?: Readonly<DoerPacing>): Operation<never>;
+//# sourceMappingURL=kel-publisher.d.ts.map

package/types/app/mailbox/kel-publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kel-publisher.d.ts","sourceRoot":"","sources":["../../../src/app/mailbox/kel-publisher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C,OAAO,EAAE,KAAK,UAAU,EAAW,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,KAAK,UAAU,EAAgB,KAAK,UAAU,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EAGxB,MAAM,qBAAqB,CAAC;AAG7B,wGAAwG;AACxG,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,sGAAsG;AACtG,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AACzC,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAC7C,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,WAAW,CAI1D,CAAC;AACH,wGAAwG;AACxG,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,UAAU,CAGpD,CAAC;AAEH,sCAAsC;AACtC,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,kHAAkH;IAClH,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,+HAA+H;IAC/H,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAClE,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,yFAAyF;AACzF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACnD;AA0BD,2FAA2F;AAC3F,qBAAa,YAAY;;IACvB,iGAAiG;IACjG,QAAQ,CAAC,OAAO,mBAA0B;IAC1C,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAE,KAAK,EAAE,OAAO,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAA6B;gBASjG,IAAI,EAAE,gBAAgB;IAIlC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAW3C;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAO1C;;;OAGG;IACH,KAAK,IAAI,IAAI;IAOb;;;;;OAKG;IACF,UAAU,CAAC,EAAE,SAAyC,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,SAAS,CAChG,kBAAkB,EAAE,CACrB;IAkCD,sEAAsE;IACrE,WAAW,CAAC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,SAAS,CAAC,kBAAkB,EAAE,CAAC;IAKnF,yEAAyE;IACzE,MAAM,IAAI,kBAAkB;IAK5B,iGAAiG;IACjG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,EAAE;IA4B7C;;;;OAIG;IACF,kBAAkB,CACjB,GAAG,EAAE,MAAM,EACX,EAAE,SAAS,EAAE,MAAW,EAAE,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACjE,SAAS,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;CAqG7C;AAED;;;;;GAKG;AACH,wBAAiB,cAAc,CAC7B,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,YAAY,EACnB,MAAM,GAAE,QAAQ,CAAC,UAAU,CAAwB,GAClD,SAAS,CAAC,KAAK,CAAC,CAUlB"}

package/types/app/mailbox/kel-publishing.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Telling a mailbox host an identifier's KEL. A host authenticates a mailbox poll against the key state it
+ * holds, which is only as new as the last KEL it was given, so a rotation it has not been told about makes it
+ * refuse the owner's polls. The publisher (`KelPublisher`) and the poller's repair of a refusing mailbox use
+ * the one post below and record it in the same marker, `Baser.kpub`.
+ */
+import { type Operation } from "effection";
+import type { Baser } from "../../db/basing.js";
+import type { Habery } from "../identity/habbing.js";
+import type { RuntimeClock } from "../runtime/runtime-clock.js";
+import type { HttpClient } from "../transport/http-client.js";
+/** Longest a mailbox may take to answer the post, in milliseconds. */
+export declare const KEL_PUBLISH_HEADER_TIMEOUT_MS = 10000;
+/** What posting the KEL to one mailbox came to; a failure carries its reason (and status) and is never thrown. */
+export type MailboxPublication = {
+    readonly mailbox: string;
+    readonly outcome: "told";
+} | {
+    readonly mailbox: string;
+    readonly outcome: "failed";
+    readonly reason: string;
+    readonly status?: number;
+};
+/** Collaborators the post needs; nothing else is reachable from here. */
+export interface KelPublishingDeps {
+    /** Borrowed identities and accepted-state stores. */
+    readonly hby: Habery;
+    /** Borrowed HTTP implementation. */
+    readonly http: HttpClient;
+    /** Borrowed clock for the header deadline. */
+    readonly clock: RuntimeClock;
+}
+/**
+ * Post the KEL replay of `pre` (delegation chain, KEL and the receipts stored for it) to one mailbox's CESR
+ * ingress, with `CESR-DESTINATION` selecting the hosted mailbox. A separate request, never prefixed to a poll:
+ * a host answers with the response to the first message of a body.
+ */
+export declare function postKelToMailbox({ hby, http, clock }: KelPublishingDeps, pre: string, endpoint: {
+    eid: string;
+    url: string;
+}, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Operation<MailboxPublication>;
+/**
+ * The establishment events a mailbox must hold to authenticate `pre`: the identifier's own latest one and, for
+ * a local group, the local signing member's, because the member signs the group's polls and the host needs its
+ * key state to verify them. `collectKelSubmission` is the one place that decides what the post carries; these
+ * heads are what the record is compared with.
+ */
+export declare function kelHeads(hby: Habery, pre: string): {
+    d: string;
+    m?: string;
+} | null;
+/**
+ * Record that `mailbox` was given the KEL of `pre` up to `heads`, and clear any earlier give-up. The record holds
+ * coordinates only; the publisher derives what is owed by comparing it with the identifier's current heads.
+ */
+export declare function pinKelPublished(db: Baser, pre: string, mailbox: string, heads: {
+    d: string;
+    m?: string;
+}, clock: Pick<RuntimeClock, "now">): void;
+/** Whether `record` shows the mailbox holds `heads`. */
+export declare function holdsHeads(record: {
+    d: string | null;
+    m?: string;
+} | null, heads: {
+    d: string;
+    m?: string;
+}): boolean;
+//# sourceMappingURL=kel-publishing.d.ts.map

package/types/app/mailbox/kel-publishing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kel-publishing.d.ts","sourceRoot":"","sources":["../../../src/app/mailbox/kel-publishing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,SAAS,EAAU,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D,sEAAsE;AACtE,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,kHAAkH;AAClH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhH,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAiB,gBAAgB,CAC/B,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,iBAAiB,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACtC,EAAE,SAAyC,EAAE,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACzE,SAAS,CAAC,kBAAkB,CAAC,CAoB/B;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMnF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAChC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,GAC/B,IAAI,CAMN;AAED,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,MAAM,EAAE;IAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAAE,KAAK,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAErH"}

package/types/app/mailbox/kel-submission.d.ts

@@ -0,0 +1,18 @@
+import type { Habery } from "../identity/habbing.js";
+/** Replay material in both the normalized and legacy multipart shapes. */
+export interface KelSubmission {
+    /** Verifier-ready stream for the raw CESR body: delegation chain then KEL, with the receipts stored for it. */
+    readonly replay: Uint8Array;
+    readonly kel: Uint8Array;
+    readonly delkel: Uint8Array;
+}
+/**
+ * Collect the accepted KEL of `pre`, and its delegation chain, from the local stores. When `pre` is a local
+ * group the KEL of the local member that signs for it comes first, so a host that authenticates the member's
+ * mailbox polls learns the member's key state, including a rotation of its own, along with the group's.
+ *
+ * `replay` is the verifier-ready stream used by raw CESR ingress. `kel`/`delkel` preserve the legacy
+ * multipart wrapper contract used by existing KERIpy mailbox admin hosts.
+ */
+export declare function collectKelSubmission(hby: Habery, pre: string): KelSubmission;
+//# sourceMappingURL=kel-submission.d.ts.map

package/types/app/mailbox/kel-submission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kel-submission.d.ts","sourceRoot":"","sources":["../../../src/app/mailbox/kel-submission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGrD,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,+GAA+G;IAC/G,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAY5E"}