keri-ts 2.1.0 → 2.2.0

package/esm/keri/npm/src/app/mailbox/ipex-arrival.js

@@ -0,0 +1,103 @@
+import { sleep } from "effection";
+import { credentialSaidFromGrant, processCredentialPresentationArtifacts, storedGrantArtifacts, } from "../ipex/ipex-credentialing.js";
+import { IPEX_GRANT_ROUTE } from "../ipex/ipexing.js";
+import { systemClock } from "../runtime/runtime-clock.js";
+/**
+ * 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 class MailboxIntakeTally {
+    constructor() {
+        Object.defineProperty(this, "receiving", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "batches", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "messages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+    }
+    /** Run the host's settle step for one batch, counting it when settled. */
+    *track(batch, settle) {
+        this.receiving++;
+        try {
+            yield* settle();
+            this.batches++;
+            this.messages += batch.messages.length;
+        }
+        finally {
+            this.receiving--;
+        }
+    }
+}
+function accepted(deps) {
+    return [...deps.hby.db.exns.getTopItemIter()].map(([, exn]) => exn);
+}
+function savedSaids(deps) {
+    return [...deps.reger.saved.getTopItemIter()].map(([keys]) => keys[0]).filter((key) => !!key);
+}
+/** Snapshot the said sets that later arrivals are measured against. */
+export function ipexBaseline(deps) {
+    return {
+        exns: new Set(accepted(deps).map((exn) => exn.said).filter((said) => typeof said === "string")),
+        saved: new Set(savedSaids(deps)),
+    };
+}
+/** Pure read of what arrived since `baseline`. Starts nothing and writes nothing. */
+export function ipexArrivalStatus(deps, baseline, tally) {
+    const ipex = accepted(deps).filter((exn) => !!exn.said && !baseline.exns.has(exn.said) && (exn.route ?? "").startsWith("/ipex/"));
+    const saved = [...new Set(savedSaids(deps))].filter((said) => !baseline.saved.has(said));
+    const receiving = (tally?.receiving ?? 0) > 0;
+    return {
+        state: !receiving && (ipex.length > 0 || saved.length > 0) ? "arrived" : "waiting",
+        ipex,
+        saved,
+        receiving,
+    };
+}
+/**
+ * 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 function* settleStoredGrants(deps, gvrsn) {
+    for (const [, grant] of deps.hby.db.exns.getTopItemIter()) {
+        if (grant.route !== IPEX_GRANT_ROUTE)
+            continue;
+        const credentialSaid = credentialSaidFromGrant(grant);
+        if (!credentialSaid || deps.reger.saved.get([credentialSaid]))
+            continue;
+        yield* processCredentialPresentationArtifacts(deps.protocol, storedGrantArtifacts(deps.hby, grant, gvrsn));
+    }
+}
+/**
+ * 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 function* waitForIpexArrival(deps, baseline, { timeoutMs, tally, pollMs = 250, clock = systemClock }) {
+    const deadline = clock.now() + timeoutMs;
+    while (true) {
+        if (deps.settle)
+            yield* deps.settle();
+        const status = ipexArrivalStatus(deps, baseline, tally);
+        if (status.state === "arrived")
+            return { outcome: "settled", status };
+        const remaining = deadline - clock.now();
+        if (remaining <= 0)
+            return { outcome: "timed-out", status, timeoutMs };
+        yield* sleep(Math.min(pollMs, remaining));
+    }
+}

package/esm/keri/npm/src/app/mailbox/kel-publisher.js

@@ -0,0 +1,322 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _KelPublisher_instances, _KelPublisher_deps, _KelPublisher_budgets, _KelPublisher_inflight, _KelPublisher_dirty, _KelPublisher_owed, _KelPublisher_statusOf, _KelPublisher_budget, _KelPublisher_attempt, _KelPublisher_derive, _KelPublisher_deriveFor, _KelPublisher_prune;
+import { Deck } from "../../core/deck.js";
+import { dgKey } from "../../db/core/keys.js";
+import { doEvery } from "../runtime/doing.js";
+import { observeUntil } from "../runtime/workflow-contract.js";
+import { holdsHeads, KEL_PUBLISH_HEADER_TIMEOUT_MS, kelHeads, pinKelPublished, postKelToMailbox, } from "./kel-publishing.js";
+import { authorizedMailboxes, fetchEndpointUrls, preferredUrl } from "./mailboxing.js";
+/** Most posts one `processOnce` attempts, so a first pass over a large store cannot stall the fiber. */
+export const KelSendsPerPass = 4;
+/** Delay after a post's first failure; doubles per attempt up to {@link KEL_PUBLISH_MAX_DELAY_MS}. */
+export const KEL_PUBLISH_BASE_MS = 1_000;
+export const KEL_PUBLISH_MAX_DELAY_MS = 60_000;
+/** Give up when the next attempt would start more than this long after the first. */
+export const KEL_PUBLISH_BUDGET_MS = 300_000;
+/** The production retry policy of KEL posts: `boundMs` is the budget. */
+export const DEFAULT_KEL_PUBLISH_RETRY = Object.freeze({
+    baseMs: KEL_PUBLISH_BASE_MS,
+    maxMs: KEL_PUBLISH_MAX_DELAY_MS,
+    boundMs: KEL_PUBLISH_BUDGET_MS,
+});
+/** Milliseconds between publisher passes; retries start at one second, so a finer tock buys nothing. */
+export const KEL_PUBLISHER_TOCK_MS = 250;
+/** Tocks between full sweeps of every identifier: 240 tocks of 250 ms is a minute. */
+export const KEL_PUBLISHER_SWEEP_TOCKS = 240;
+/** The production pacing of the publisher fiber. */
+export const KEL_PUBLISHER_PACING = Object.freeze({
+    tockMs: KEL_PUBLISHER_TOCK_MS,
+    sweepTocks: KEL_PUBLISHER_SWEEP_TOCKS,
+});
+const idOf = (pre, mailbox) => `${pre}/${mailbox}`;
+/** Derives, sends and records the KEL posts a wallet's identifiers owe their mailboxes. */
+export class KelPublisher {
+    constructor(deps) {
+        _KelPublisher_instances.add(this);
+        /** Completion points push here; the next tock gives that identifier's entries a fresh budget. */
+        Object.defineProperty(this, "rotated", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Deck()
+        });
+        /** A failure that escapes a pass is counted and kept here; the fiber keeps running. */
+        Object.defineProperty(this, "health", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: { faults: 0, last: null }
+        });
+        _KelPublisher_deps.set(this, void 0);
+        _KelPublisher_budgets.set(this, new Map());
+        _KelPublisher_inflight.set(this, new Set());
+        /** Identifiers to re-derive on the next tock; the sweep adds every identifier. */
+        _KelPublisher_dirty.set(this, new Set());
+        /** Identifiers with something owed, re-derived each tock so a cleared hold is seen. */
+        _KelPublisher_owed.set(this, new Set());
+        __classPrivateFieldSet(this, _KelPublisher_deps, deps, "f");
+    }
+    /**
+     * 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, mailbox) {
+        if (mailbox !== undefined) {
+            const id = idOf(pre, mailbox);
+            if (!__classPrivateFieldGet(this, _KelPublisher_budgets, "f").get(id)?.expired)
+                return;
+            __classPrivateFieldGet(this, _KelPublisher_budgets, "f").delete(id);
+        }
+        else {
+            for (const id of [...__classPrivateFieldGet(this, _KelPublisher_budgets, "f").keys()])
+                if (id.startsWith(`${pre}/`))
+                    __classPrivateFieldGet(this, _KelPublisher_budgets, "f").delete(id);
+        }
+        __classPrivateFieldGet(this, _KelPublisher_dirty, "f").add(pre);
+    }
+    /**
+     * 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, mailbox) {
+        const { hby } = __classPrivateFieldGet(this, _KelPublisher_deps, "f"), record = hby.db.kpub.get([pre, mailbox]);
+        if (!hby.readonly && record?.d)
+            hby.db.kpub.pin([pre, mailbox], { d: null, dt: record.dt });
+        __classPrivateFieldGet(this, _KelPublisher_budgets, "f").delete(idOf(pre, mailbox));
+        __classPrivateFieldGet(this, _KelPublisher_dirty, "f").add(pre);
+    }
+    /**
+     * 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() {
+        const { hby } = __classPrivateFieldGet(this, _KelPublisher_deps, "f");
+        if (hby.readonly)
+            return;
+        __classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_prune).call(this);
+        for (const hab of hby.habs.values())
+            if (hab.pre)
+                __classPrivateFieldGet(this, _KelPublisher_dirty, "f").add(hab.pre);
+    }
+    /**
+     * 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 = KEL_PUBLISH_HEADER_TIMEOUT_MS } = {}) {
+        const { clock, hby } = __classPrivateFieldGet(this, _KelPublisher_deps, "f");
+        for (let cue = this.rotated.pull(); cue; cue = this.rotated.pull())
+            this.prompt(cue.pre);
+        if (hby.readonly)
+            return [];
+        const owed = [];
+        for (const pre of new Set([...__classPrivateFieldGet(this, _KelPublisher_dirty, "f"), ...__classPrivateFieldGet(this, _KelPublisher_owed, "f")])) {
+            const entries = __classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_deriveFor).call(this, pre).filter((entry) => !entry.published);
+            if (entries.length)
+                __classPrivateFieldGet(this, _KelPublisher_owed, "f").add(pre);
+            else
+                __classPrivateFieldGet(this, _KelPublisher_owed, "f").delete(pre);
+            owed.push(...entries);
+        }
+        __classPrivateFieldGet(this, _KelPublisher_dirty, "f").clear();
+        const live = new Set(owed.map((entry) => idOf(entry.pre, entry.mailbox)));
+        for (const id of [...__classPrivateFieldGet(this, _KelPublisher_budgets, "f").keys()]) {
+            const pre = id.slice(0, id.indexOf("/"));
+            if (!live.has(id) && !__classPrivateFieldGet(this, _KelPublisher_owed, "f").has(pre))
+                __classPrivateFieldGet(this, _KelPublisher_budgets, "f").delete(id);
+        }
+        const results = [];
+        for (const entry of owed) {
+            if (results.length >= KelSendsPerPass)
+                break;
+            const id = idOf(entry.pre, entry.mailbox), budget = __classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_budget).call(this, id, entry.said);
+            if (entry.hold || !entry.url || budget.expired || budget.retryAt > clock.now() || __classPrivateFieldGet(this, _KelPublisher_inflight, "f").has(id)) {
+                continue;
+            }
+            __classPrivateFieldGet(this, _KelPublisher_inflight, "f").add(id);
+            try {
+                results.push(yield* __classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_attempt).call(this, entry, entry.url, budget, timeoutMs));
+            }
+            finally {
+                __classPrivateFieldGet(this, _KelPublisher_inflight, "f").delete(id);
+            }
+        }
+        return results;
+    }
+    /** A sweep and a pass: what a one-shot host, or a test, runs once. */
+    *processOnce(options = {}) {
+        this.sweep();
+        return yield* this.processDue(options);
+    }
+    /** Pure read of every (identifier, mailbox) pair and where it stands. */
+    status() {
+        if (__classPrivateFieldGet(this, _KelPublisher_deps, "f").hby.readonly)
+            return { entries: [] };
+        return { entries: __classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_derive).call(this).map((entry) => __classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_statusOf).call(this, entry)) };
+    }
+    /** Pure read of one identifier's mailboxes; the cheap read for a wait on a single identifier. */
+    statusOf(pre) {
+        if (__classPrivateFieldGet(this, _KelPublisher_deps, "f").hby.readonly)
+            return [];
+        return __classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_deriveFor).call(this, pre).map((entry) => __classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_statusOf).call(this, entry));
+    }
+    /**
+     * 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, { timeoutMs, pollMs = 50 }) {
+        __classPrivateFieldGet(this, _KelPublisher_dirty, "f").add(pre);
+        const settled = () => this.statusOf(pre).every((entry) => entry.state === "published" || entry.state === "timed-out");
+        const done = yield* observeUntil(settled, { timeoutMs, pollMs, clock: __classPrivateFieldGet(this, _KelPublisher_deps, "f").clock });
+        const status = this.status();
+        return done ? { outcome: "settled", status } : { outcome: "timed-out", status, timeoutMs };
+    }
+}
+_KelPublisher_deps = new WeakMap(), _KelPublisher_budgets = new WeakMap(), _KelPublisher_inflight = new WeakMap(), _KelPublisher_dirty = new WeakMap(), _KelPublisher_owed = new WeakMap(), _KelPublisher_instances = new WeakSet(), _KelPublisher_statusOf = function _KelPublisher_statusOf(entry) {
+    const base = { pre: entry.pre, mailbox: entry.mailbox, said: entry.said };
+    if (entry.published)
+        return { ...base, state: "published", attempts: 0 };
+    const budget = __classPrivateFieldGet(this, _KelPublisher_budgets, "f").get(idOf(entry.pre, entry.mailbox));
+    const failed = __classPrivateFieldGet(this, _KelPublisher_deps, "f").hby.db.kpub.get([entry.pre, entry.mailbox])?.failed;
+    if (entry.hold)
+        return { ...base, state: "waiting", attempts: budget?.attempts ?? 0, lastFailure: entry.hold };
+    if (budget?.expired) {
+        return {
+            ...base,
+            state: "timed-out",
+            attempts: failed?.attempts ?? budget.attempts,
+            lastFailure: failed?.reason ?? budget.lastFailure ?? undefined,
+        };
+    }
+    return {
+        ...base,
+        state: "pending",
+        attempts: budget?.attempts ?? 0,
+        ...(budget?.lastFailure ? { lastFailure: budget.lastFailure } : {}),
+        ...(budget?.attempts ? { retryAt: new Date(budget.retryAt).toISOString() } : {}),
+    };
+}, _KelPublisher_budget = function _KelPublisher_budget(id, said) {
+    let budget = __classPrivateFieldGet(this, _KelPublisher_budgets, "f").get(id);
+    if (!budget || budget.said !== said) {
+        budget = { said, firstAt: null, attempts: 0, lastFailure: null, retryAt: 0, expired: false };
+        __classPrivateFieldGet(this, _KelPublisher_budgets, "f").set(id, budget);
+    }
+    return budget;
+}, _KelPublisher_attempt = function
+/** Post once, then record: the record on 2xx (or a host that cannot take the stream), a delay or give-up otherwise. */
+* _KelPublisher_attempt(entry, url, budget, timeoutMs) {
+    const { clock, changes, hby } = __classPrivateFieldGet(this, _KelPublisher_deps, "f"), id = idOf(entry.pre, entry.mailbox);
+    budget.firstAt ??= clock.now();
+    const result = yield* postKelToMailbox(__classPrivateFieldGet(this, _KelPublisher_deps, "f"), entry.pre, { eid: entry.mailbox, url }, { timeoutMs });
+    const unsupported = result.outcome === "failed" && (result.status === 400 || result.status === 406);
+    if (result.outcome === "told" || unsupported) {
+        pinKelPublished(hby.db, entry.pre, entry.mailbox, { d: entry.said, m: entry.member }, clock);
+        __classPrivateFieldGet(this, _KelPublisher_budgets, "f").delete(id);
+    }
+    else {
+        budget.attempts += 1;
+        budget.lastFailure = result.reason;
+        const retry = __classPrivateFieldGet(this, _KelPublisher_deps, "f").retry ?? DEFAULT_KEL_PUBLISH_RETRY;
+        const delay = Math.min(retry.baseMs * 2 ** (budget.attempts - 1), retry.maxMs);
+        budget.retryAt = clock.now() + delay;
+        if (budget.retryAt - budget.firstAt > retry.boundMs) {
+            budget.expired = true;
+            const record = hby.db.kpub.get([entry.pre, entry.mailbox]);
+            hby.db.kpub.pin([entry.pre, entry.mailbox], {
+                d: record?.d ?? null,
+                ...(record?.m ? { m: record.m } : {}),
+                dt: record?.dt ?? new Date(clock.now()).toISOString(),
+                failed: {
+                    d: entry.said,
+                    dt: new Date(clock.now()).toISOString(),
+                    attempts: budget.attempts,
+                    reason: result.reason,
+                },
+            });
+        }
+    }
+    changes?.push({ kind: "event", id: `${entry.pre}:${entry.sn}` });
+    return result;
+}, _KelPublisher_derive = function _KelPublisher_derive() {
+    const derived = [];
+    for (const hab of __classPrivateFieldGet(this, _KelPublisher_deps, "f").hby.habs.values())
+        if (hab.pre)
+            derived.push(...__classPrivateFieldGet(this, _KelPublisher_instances, "m", _KelPublisher_deriveFor).call(this, hab.pre));
+    return derived;
+}, _KelPublisher_deriveFor = function _KelPublisher_deriveFor(pre) {
+    const { hby } = __classPrivateFieldGet(this, _KelPublisher_deps, "f"), db = hby.db, derived = [];
+    const hab = hby.habs.get(pre), kever = hab?.kever;
+    if (!hab || !kever)
+        return derived;
+    const heads = kelHeads(hby, pre);
+    if (!heads)
+        return derived;
+    const said = heads.d;
+    for (const mailbox of authorizedMailboxes(db, pre)) {
+        const url = preferredUrl(fetchEndpointUrls(hby, mailbox)) ?? null;
+        const established = db.getEvtSerder(pre, said);
+        let hold = null;
+        if (!url)
+            hold = "no-url";
+        else if (!established || !db.fullyWitnessed(established))
+            hold = "unwitnessed";
+        else if (kever.delegated && !db.aess.get(dgKey(pre, said)))
+            hold = "unanchored";
+        derived.push({
+            pre,
+            mailbox,
+            url,
+            said,
+            member: heads.m,
+            sn: kever.sn,
+            published: holdsHeads(db.kpub.get([pre, mailbox]), heads),
+            hold,
+        });
+    }
+    return derived;
+}, _KelPublisher_prune = function _KelPublisher_prune() {
+    const { hby } = __classPrivateFieldGet(this, _KelPublisher_deps, "f"), db = hby.db;
+    const wanted = new Set();
+    for (const hab of hby.habs.values()) {
+        if (hab.pre)
+            for (const mailbox of authorizedMailboxes(db, hab.pre))
+                wanted.add(idOf(hab.pre, mailbox));
+    }
+    for (const [[pre, mailbox]] of [...db.kpub.getTopItemIter()]) {
+        if (!wanted.has(idOf(pre, mailbox)))
+            db.kpub.rem([pre, mailbox]);
+    }
+};
+/**
+ * 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 function* kelPublisherDo(publisher, clock, pacing = KEL_PUBLISHER_PACING) {
+    return yield* doEvery(clock, pacing.tockMs, function* (tock) {
+        try {
+            if (tock % pacing.sweepTocks === 0)
+                publisher.sweep();
+            yield* publisher.processDue();
+        }
+        catch (error) {
+            publisher.health.faults++;
+            publisher.health.last = { error, at: clock.now() };
+        }
+    });
+}

package/esm/keri/npm/src/app/mailbox/kel-publishing.js

@@ -0,0 +1,65 @@
+/**
+ * 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 { scoped } from "effection";
+import { localGroupMember } from "../multisig/group-members.js";
+import { buildCesrStreamRequest } from "../transport/cesr-http.js";
+import { requestWithHeaderTimeout } from "../transport/httping.js";
+import { collectKelSubmission } from "./kel-submission.js";
+/** Longest a mailbox may take to answer the post, in milliseconds. */
+export const KEL_PUBLISH_HEADER_TIMEOUT_MS = 10_000;
+/**
+ * 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 function* postKelToMailbox({ hby, http, clock }, pre, endpoint, { timeoutMs = KEL_PUBLISH_HEADER_TIMEOUT_MS } = {}) {
+    const { replay } = collectKelSubmission(hby, pre);
+    const request = buildCesrStreamRequest(replay, { destination: endpoint.eid });
+    try {
+        return yield* scoped(function* () {
+            const response = yield* requestWithHeaderTimeout(http, clock, endpoint.url, { method: "POST", headers: request.headers, body: request.body }, timeoutMs);
+            if (!response)
+                return { mailbox: endpoint.eid, outcome: "failed", reason: `no answer within ${timeoutMs} ms` };
+            return response.ok
+                ? { mailbox: endpoint.eid, outcome: "told" }
+                : { mailbox: endpoint.eid, outcome: "failed", reason: `HTTP ${response.status}`, status: response.status };
+        });
+    }
+    catch (error) {
+        return { mailbox: endpoint.eid, outcome: "failed", reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * 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 function kelHeads(hby, pre) {
+    const kever = hby.db.getKever(pre);
+    if (!kever)
+        return null;
+    if (!hby.db.getHab(pre)?.mid)
+        return { d: kever.lastEst.d };
+    const member = localGroupMember(hby, pre).kever;
+    return member ? { d: kever.lastEst.d, m: member.lastEst.d } : { d: kever.lastEst.d };
+}
+/**
+ * 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 function pinKelPublished(db, pre, mailbox, heads, clock) {
+    db.kpub.pin([pre, mailbox], {
+        d: heads.d,
+        ...(heads.m ? { m: heads.m } : {}),
+        dt: new Date(clock.now()).toISOString(),
+    });
+}
+/** Whether `record` shows the mailbox holds `heads`. */
+export function holdsHeads(record, heads) {
+    return record?.d === heads.d && (heads.m === undefined || record.m === heads.m);
+}

package/esm/keri/npm/src/app/mailbox/kel-submission.js

@@ -0,0 +1,24 @@
+/** The KEL of a local identifier as bytes to post to a mailbox host that must learn its key state. */
+import { concatBytes } from "cesr-ts";
+import { localGroupMember } from "../multisig/group-members.js";
+/**
+ * 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 function collectKelSubmission(hby, pre) {
+    const parts = [...(hby.db.getHab(pre)?.mid ? [localGroupMember(hby, pre).pre] : []), pre].map((each) => {
+        const kever = hby.db.getKever(each);
+        return {
+            delkel: kever ? concatBytes(...hby.db.cloneDelegation(kever)) : new Uint8Array(),
+            kel: concatBytes(...hby.db.clonePreIter(each)),
+        };
+    });
+    const delkel = concatBytes(...parts.map((part) => part.delkel));
+    const kel = concatBytes(...parts.map((part) => part.kel));
+    const replay = concatBytes(...parts.flatMap((part) => [part.delkel, part.kel]));
+    return { replay, kel, delkel };
+}