keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/app/runtime/agent-runtime.js

@@ -0,0 +1,633 @@
+import { WireParseError } from "cesr-ts";
+import { call, resource, spawn, suspend } from "effection";
+import { Dhke } from "../../acdc/dhking.js";
+import { RegistryObserver } from "../../acdc/observing.js";
+import { createRegery as createAcdcRegery } from "../../acdc/registraring.js";
+import { RegistryRoot } from "../../acdc/salting.js";
+import { Unblind } from "../../acdc/unblinding.js";
+import { Deck } from "../../core/deck.js";
+import { DatabaseNotOpenError, ValidationError } from "../../core/errors.js";
+import { Kevery } from "../../core/kel/eventing.js";
+import { Kramer } from "../../core/mailbox/kraming.js";
+import { CREDENTIAL_MAILBOX_TOPIC, DELEGATE_MAILBOX_TOPIC, RECEIPT_MAILBOX_TOPIC, REPLAY_MAILBOX_TOPIC, REPLY_MAILBOX_TOPIC, } from "../../core/mailbox/mailbox-topics.js";
+import { Revery } from "../../core/routing.js";
+import { Mailboxer } from "../../db/mailbox/mailboxing.js";
+import { Noter } from "../../db/noting.js";
+import { createReger } from "../../db/reger.js";
+import { Regery as VdrRegery } from "../../vdr/credentialing.js";
+import { Tevery } from "../../vdr/eventing.js";
+import { Authenticator } from "../bootstrap/authenticating.js";
+import { loadOobiHandlers, Oobiery, oobiTerminalState } from "../bootstrap/oobiery.js";
+import { publishPendingTel } from "../credentials/tel-publishing.js";
+import { Poster } from "../delivery/forwarding.js";
+import { ReplyStreams } from "../delivery/reply-streams.js";
+import { Respondant } from "../delivery/respondant.js";
+import { Exchanger, RouteRefuser } from "../exchanges/exchanging.js";
+import { loadChallengeHandlers } from "../identity/challenging.js";
+import { Anchorer, loadDelegationHandlers } from "../identity/delegating.js";
+import { loadIpexHandlers } from "../ipex/ipexing.js";
+import { ForwardHandler } from "../mailbox/forward-handler.js";
+import { MailboxDirector } from "../mailbox/mailbox-director.js";
+import { MailboxPoller } from "../mailbox/mailbox-poller.js";
+import { mailboxerOptionsForHabery } from "../mailbox/mailboxing.js";
+import { mailboxTopicForRoute } from "../mailbox/topic-routing.js";
+import { loadMultisigHandlers } from "../multisig/grouping.js";
+import { noterOptionsForHabery, Notifier } from "../notifications/notifying.js";
+import { Signaler } from "../notifications/signaling.js";
+import { ProtocolProcessor } from "../protocol/protocol-processing.js";
+import { Reactor } from "../protocol/reactor.js";
+import { QueryReplies } from "../queries/query-replies.js";
+import { WitnessInquisitor } from "../queries/witness-inquisitor.js";
+import { Receiptor } from "../witness/receipting.js";
+import { cueDo } from "./cue-runtime.js";
+import { runtimeTurn } from "./runtime-turn.js";
+/**
+ * Create the shared runtime composition root used by CLI commands and
+ * `tufa agent`.
+ *
+ * Construction rule:
+ * - application roots supply HTTP, clock and mailbox transport explicitly
+ * - hosts choose concrete optional stores and borrow supplied dependencies
+ * - the composition owns only stores it constructs
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param http Borrowed HTTP implementation selected by composition.
+ * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+ * @param options Optional borrowed stores and protocol policy; omitted writable stores follow the documented acquisition rules.
+ * @returns A composed runtime within the enclosing Effection scope; workers are started separately.
+ * @throws Dependency mismatch/acquisition errors propagate after owned resource cleanup.
+ */
+export function* createAgentRuntime(hby, http, clock, options = {}) {
+    const selected = options.ipexAuxiliary;
+    if (selected) {
+        if (options.kram?.enabled !== true) {
+            throw new ValidationError("IPEX auxiliary runtime requires explicitly enabled KRAM");
+        }
+        if (!selected.hab.pre || hby.habs.get(selected.hab.pre) !== selected.hab) {
+            throw new ValidationError("IPEX auxiliary runtime requires its actual local habitat");
+        }
+    }
+    const injectedSignaler = options.signaler ?? options.notifier?.signaler;
+    if ((options.notifier && options.notifier.signator !== hby.signator)
+        || (options.noter && options.notifier && options.noter !== options.notifier.noter)
+        || (options.signaler && options.notifier && options.signaler !== options.notifier.signaler)) {
+        throw new RangeError("AgentRuntime notification services require its exact Signator, Noter and Signaler");
+    }
+    const mailboxer = options.mailboxer
+        ?? (options.enableMailboxStore ? (yield* openRuntimeMailboxer(hby)) : null);
+    const ownsMailboxer = options.mailboxer === undefined && mailboxer !== null;
+    const ownsSignaler = injectedSignaler === undefined && hby.signator !== null;
+    const signaler = injectedSignaler ?? (ownsSignaler
+        ? (yield* resource(function* (provide) {
+            const owned = new Signaler();
+            try {
+                yield* provide(owned);
+            }
+            finally {
+                owned.close();
+            }
+        }))
+        : null);
+    const noter = options.noter
+        ?? options.notifier?.noter
+        ?? (!hby.readonly && hby.signator ? (yield* openRuntimeNoter(hby)) : null);
+    const ownsNoter = options.noter === undefined
+        && options.notifier === undefined
+        && noter !== null;
+    const notifier = options.notifier
+        ?? (hby.signator && noter && signaler ? new Notifier(hby.signator, { noter, signaler }) : null);
+    const reger = options.reger ?? (!hby.readonly ? (yield* openRegerForHabery(hby)) : null);
+    const ownsReger = options.reger === undefined && reger !== null;
+    const acdc = options.acdc ?? (!hby.readonly ? (yield* openAcdcRegeryForHabery(hby)) : null);
+    const ownsAcdcRegery = options.acdc === undefined && acdc !== null;
+    const acdcRegery = acdc;
+    if (selected && !acdc)
+        throw new ValidationError("IPEX auxiliary runtime requires a v2 registry");
+    // Acquire after stores, before processors/consumers: reverse teardown joins consumers, clears cues, closes stores.
+    const cues = yield* resource(function* (provide) {
+        const owned = new Deck();
+        try {
+            yield* provide(owned);
+        }
+        finally {
+            owned.clear();
+        }
+    });
+    const protocolCues = new Deck();
+    const revery = new Revery(hby.db, { cues: protocolCues });
+    const tvy = reger ? new Tevery({ db: hby.db, reger, cues: protocolCues, rvy: revery }) : undefined;
+    const vdr = reger ? new VdrRegery(hby, { reger, cues: protocolCues, tvy }) : null;
+    // Reverse scope teardown joins borrowed output evidence before its backing stores close.
+    const replyStreams = yield* resource(function* (provide) {
+        const streams = new ReplyStreams();
+        try {
+            yield* provide(streams);
+        }
+        finally {
+            streams.close();
+        }
+    });
+    // Compose the shared semantic handlers before input owners or network delivery.
+    /** Preserve the composed clock receiver when passing a plain epoch-time callback. */
+    const now = () => clock.now();
+    const kramer = options.kram ? new Kramer(hby.db, { config: options.kram, cues: protocolCues, now }) : undefined;
+    const kvy = new Kevery(hby.db, { cues: protocolCues, rvy: revery, messagePolicy: options.messagePolicy, kramer });
+    const exc = new Exchanger(hby, { cues: protocolCues, now });
+    const registry = acdc ? new RegistryObserver(hby.db, acdc.store) : null;
+    const ipexAuxiliary = selected && registry
+        ? yield* resource(function* (provide) {
+            const auxiliary = selected.kind === "dhke"
+                ? { kind: "dhke", owner: new Dhke({ hab: selected.hab, exc, registryStore: registry.store, rvy: revery, now }) }
+                : {
+                    kind: "unblind",
+                    owner: new Unblind({ hab: selected.hab, exc, registry, states: selected.states, rvy: revery, now }),
+                };
+            try {
+                revery.rtr.addRoute(auxiliary.kind === "dhke" ? Dhke.Route : Unblind.Route, auxiliary.owner);
+                yield* provide(auxiliary);
+            }
+            finally {
+                auxiliary.owner.close();
+            }
+        })
+        : null;
+    const replies = new QueryReplies(cues);
+    const protocol = new ProtocolProcessor(kvy, revery, exc, vdr?.tvy ?? null, vdr?.vry ?? null, registry, protocolCues, cues, replies, ipexAuxiliary?.owner);
+    const reactor = new Reactor(protocol);
+    loadChallengeHandlers(hby.db, exc);
+    loadDelegationHandlers(hby, exc, notifier);
+    loadOobiHandlers(hby, exc, notifier);
+    const mux = loadMultisigHandlers(hby, exc, { notifier, registry: protocol.registry, messageKevery: protocol.kvy });
+    loadIpexHandlers(hby, exc, {
+        notifier,
+        registry: acdc?.store ?? null,
+    });
+    // Construction adopts stored copies an earlier handler-less Exchanger left unescrowed.
+    const registryRoot = options.registryRoots !== "refuse" && acdc ? new RegistryRoot(hby, acdc, notifier) : null;
+    if (registryRoot)
+        exc.addHandler(registryRoot);
+    const mailboxDirector = yield* resource(function* (provide) {
+        const director = new MailboxDirector(hby, {
+            ...(mailboxer ? { mailboxer } : {}),
+        });
+        try {
+            yield* provide(director);
+        }
+        finally {
+            yield* call(() => director.close());
+        }
+    });
+    const postman = yield* resource(function* (provide) {
+        const postman = new Poster(hby, mailboxer, protocol, http, clock);
+        try {
+            yield* provide(postman);
+        }
+        finally {
+            yield* postman.close();
+        }
+    });
+    const respondant = new Respondant(hby, postman);
+    if (mailboxer) {
+        exc.addHandler(new ForwardHandler(mailboxDirector));
+    }
+    for (const route of exc.routes.keys()) {
+        if (route === ForwardHandler.resource) {
+            continue;
+        }
+        const topic = mailboxTopicForRoute(route);
+        if (topic.length > 0) {
+            mailboxDirector.registerTopic(topic);
+        }
+    }
+    // Copies ride the credential topic; the refuser adds no mailbox topic of its own.
+    if (options.registryRoots === "refuse")
+        exc.addHandler(new RouteRefuser(RegistryRoot.Route));
+    const mailboxPoller = new MailboxPoller(hby, mailboxDirector, http, clock, {});
+    for (const topic of [
+        DELEGATE_MAILBOX_TOPIC,
+        CREDENTIAL_MAILBOX_TOPIC,
+        RECEIPT_MAILBOX_TOPIC,
+        REPLAY_MAILBOX_TOPIC,
+        REPLY_MAILBOX_TOPIC,
+    ]) {
+        mailboxDirector.registerTopic(topic);
+    }
+    const querying = yield* resource(function* (provide) {
+        const inquisitor = new WitnessInquisitor(hby, protocol, http, clock);
+        try {
+            yield* provide(inquisitor);
+        }
+        finally {
+            yield* inquisitor.close();
+        }
+    });
+    const delegating = new Anchorer(hby, postman, querying, protocol, http, clock);
+    const oobiery = new Oobiery(hby, protocol, revery, http, cues);
+    oobiery.registerReplyRoutes(revery.rtr);
+    const authenticator = new Authenticator(hby, http);
+    return {
+        hby,
+        mailboxer,
+        noter,
+        notifier,
+        signaler,
+        cues,
+        reactor,
+        protocol,
+        replies,
+        exc,
+        mux,
+        ipexAuxiliary,
+        oobiery,
+        authenticator,
+        mailboxDirector,
+        respondant,
+        mailboxPoller,
+        postman,
+        delegating,
+        querying,
+        replyStreams,
+        vdr,
+        acdc,
+        registryRoot,
+        http,
+        clock,
+        /**
+         * Close runtime-owned resources after stopping their dependent I/O.
+         * Callers must halt host workers before explicit close. Query/Poster operations and
+         * response readers close before owned stores; injected stores and Habery remain
+         * borrowed. Continue remaining cleanups after a failure and preserve all failures.
+         */
+        *close() {
+            const failures = [];
+            const cleanup = [
+                function* () {
+                    ipexAuxiliary?.owner.close();
+                },
+                function* () {
+                    yield* querying.close();
+                },
+                function* () {
+                    if (ownsSignaler)
+                        signaler?.close();
+                },
+                function* () {
+                    yield* postman.close();
+                },
+                function* () {
+                    yield* call(() => Promise.resolve(replyStreams.close()));
+                },
+                function* () {
+                    yield* call(() => mailboxDirector.close());
+                },
+                function* () {
+                    cues.clear();
+                },
+                function* () {
+                    if (ownsNoter && noter?.opened)
+                        yield* noter.close(hby.temp);
+                },
+                function* () {
+                    if (ownsMailboxer && mailboxer?.opened)
+                        yield* mailboxer.close(hby.temp);
+                },
+                function* () {
+                    if (ownsAcdcRegery && acdcRegery?.store.opened)
+                        yield* acdcRegery.close();
+                },
+                function* () {
+                    if (ownsReger && reger?.opened)
+                        yield* reger.close(hby.temp);
+                },
+            ];
+            for (const close of cleanup) {
+                try {
+                    yield* close();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length)
+                throw new AggregateError(failures, "Runtime cleanup failed");
+        },
+    };
+}
+/**
+ * Own the runtime notification store before its cancellable open can yield.
+ *
+ * @param hby Habery supplying name/path/temp policy; this helper does not close it.
+ * @returns New store/manager owned by the current scope, including failed-open cleanup.
+ */
+function* openRuntimeNoter(hby) {
+    return yield* resource(function* (provide) {
+        const options = noterOptionsForHabery(hby);
+        const store = new Noter(options);
+        try {
+            if (!(yield* store.reopen(options)))
+                throw new DatabaseNotOpenError("Failed to open runtime Noter");
+            yield* provide(store);
+        }
+        finally {
+            yield* store.close(hby.temp);
+        }
+    });
+}
+/**
+ * Own the provider mailbox store through acquisition failure and runtime scope exit.
+ *
+ * @param hby Habery supplying name/path/temp policy; this helper does not close it.
+ * @returns New store/manager owned by the current scope, including failed-open cleanup.
+ */
+function* openRuntimeMailboxer(hby) {
+    return yield* resource(function* (provide) {
+        const options = mailboxerOptionsForHabery(hby);
+        const store = new Mailboxer(options);
+        try {
+            if (!(yield* store.reopen(options)))
+                throw new DatabaseNotOpenError("Failed to open runtime Mailboxer");
+            yield* provide(store);
+        }
+        finally {
+            yield* store.close(hby.temp);
+        }
+    });
+}
+/**
+ * Open v2 registry services owned by the current Effection scope.
+ *
+ * @param hby Habery supplying name/path/temp policy; this helper does not close it.
+ * @returns New store/manager owned by the current scope, including failed-open cleanup.
+ */
+function* openAcdcRegeryForHabery(hby) {
+    return yield* resource(function* (provide) {
+        const rgy = yield* call(() => createAcdcRegery({ hby }));
+        try {
+            yield* provide(rgy);
+        }
+        finally {
+            yield* rgy.close();
+        }
+    });
+}
+/**
+ * Open the runtime's default TEL store with the same scope-owned lifetime.
+ *
+ * @param hby Habery supplying name/path/temp policy; this helper does not close it.
+ * @returns New store/manager owned by the current scope, including failed-open cleanup.
+ */
+function* openRegerForHabery(hby) {
+    return yield* resource(function* (provide) {
+        const store = yield* call(() => createReger({
+            name: hby.name,
+            base: hby.base,
+            temp: hby.temp,
+            headDirPath: hby.headDirPath,
+            compat: hby.compat,
+        }));
+        try {
+            yield* provide(store);
+        }
+        finally {
+            if (store.opened)
+                yield* store.close(hby.temp);
+        }
+    });
+}
+/**
+ * Queue one OOBI resolution job through the durable OOBI component.
+ *
+ * Unlike the older bootstrap runtime, this no longer stages jobs on a root
+ * in-memory deck. The authoritative queue is the `oobis.` database family.
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @param job URL and optional alias admitted to the durable OOBI owner.
+ */
+export function enqueueOobi(runtime, job) {
+    runtime.oobiery.resolve(job.url, job.alias);
+}
+/**
+ * Parse and settle one or more complete KERI/CESR records immediately.
+ *
+ * This is the shared ingress-settlement seam for mailbox-delivered batches and
+ * HTTP request payloads that should advance parser and escrow state together.
+ *
+ * Maintainer mental model:
+ * - this helper is intentionally route-policy-free
+ * - callers decide whether a message should be treated as `local` or ordinary
+ *   remote ingress before calling it
+ * - once called, it always does the same two things: finish each record and run
+ *   one escrow replay turn
+ *
+ * Why `local` matters:
+ * - `local` is not an HTTP transport detail
+ * - it is a parser/runtime semantic switch used when the host is acting as the
+ *   local controller or local witness for the received message
+ * - witness hosting relies on that distinction so accepted witness-targeted
+ *   events emit witness cues rather than ordinary remote receipt cues
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @param messages Complete resident wire records, processed in iterable order.
+ * @param options Optional local-controller/witness policy and receiving mailbox endpoint provenance.
+ */
+export function* settleRuntimeIngress(runtime, messages, { local, mailboxAid, } = {}) {
+    for (const message of messages) {
+        yield* runtime.reactor.processBytes(message, { local, mailboxAid });
+    }
+    yield* runtime.protocol.processEscrowsOnce();
+}
+/**
+ * Process one remote mailbox batch and its follow-on escrow work.
+ *
+ * The poller awaits this operation before recording the provider cursor or
+ * reading the next event. Protocol completion can accept, escrow or reject input;
+ * it does not acknowledge the message to the provider or delete its stored row.
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @param batch Ordered wire messages for one mailbox subject and provider AID; each is processed before the final escrow pass.
+ */
+export function* settleMailboxPollBatch(runtime, batch) {
+    for (const message of batch.messages) {
+        try {
+            yield* runtime.reactor.processBytes(message);
+        }
+        catch (error) {
+            // A malformed wire frame a mailbox returns must not stall the poll loop: skip it so
+            // the batch completes and the provider cursor advances past it. Only WireParseError
+            // (malformed wire input) is skipped; a dispatch-side ParserError from processing a
+            // valid frame against corrupt stored state, and every non-parse error, still propagate.
+            if (error instanceof WireParseError) {
+                console.error("skipped an unparseable mailbox frame", error);
+                continue;
+            }
+            throw error;
+        }
+    }
+    yield* runtime.protocol.processEscrowsOnce();
+}
+/**
+ * Return the current pending-work summary for bounded command-local hosts.
+ *
+ * `queriesPending` describes the background sender only. A concrete workflow
+ * remains active in its invoking operation until its accepted-state predicate holds.
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @returns Current selected work summary; retained Poster failures/completion cues do not imply pending delivery.
+ */
+export function runtimePendingState(runtime) {
+    return {
+        cues: !runtime.cues.empty,
+        replyEscrow: runtime.hby.db.rpes.cnt() > 0,
+        oobiQueued: runtime.hby.db.oobis.cnt() > 0,
+        oobiInFlight: runtime.hby.db.coobi.cnt() > 0,
+        multiPending: runtime.hby.db.moobi.cnt() > 0,
+        authQueued: runtime.hby.db.woobi.cnt() > 0,
+        authInFlight: runtime.hby.db.mfa.cnt() > 0,
+        delegationPending: runtime.hby.db.dpwe.cnt() > 0
+            || runtime.hby.db.dune.cnt() > 0
+            || runtime.hby.db.dpub.cnt() > 0,
+        queriesPending: runtime.querying.hasPendingWork(),
+        deliveriesPending: runtime.querying.hasPendingDelivery || runtime.postman.hasPending,
+    };
+}
+/**
+ * Return true when any command-local runtime work remains in flight.
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @returns Whether any category in runtimePendingState is pending.
+ */
+export function runtimeHasPendingWork(runtime) {
+    const state = runtimePendingState(runtime);
+    return state.cues || state.replyEscrow
+        || state.oobiQueued || state.oobiInFlight || state.multiPending
+        || state.authQueued || state.authInFlight
+        || state.delegationPending
+        || state.queriesPending
+        || state.deliveriesPending;
+}
+/**
+ * Return true once OOBI acceptance and its ingress/query dependencies settle.
+ * Background receipt delivery is not remote acknowledgement of OOBI acceptance;
+ * static OOBI servers may refuse unsolicited posts. Runtime close still joins I/O.
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @param url Exact requested OOBI/well-known URL whose durable state is inspected.
+ * @returns Whether the documented authentication/convergence predicate currently holds.
+ */
+export function runtimeOobiConverged(runtime, url) {
+    const pending = runtimePendingState(runtime);
+    return oobiTerminalState(runtime.hby.db, url).status !== "pending"
+        && !pending.cues && !pending.replyEscrow
+        && !pending.oobiQueued && !pending.oobiInFlight && !pending.multiPending
+        && !pending.authQueued && !pending.authInFlight && !pending.delegationPending
+        && !pending.queriesPending;
+}
+/**
+ * Run host workers until the caller's predicate succeeds or its deadline expires.
+ * The deadline uses Date.now wall time in the current implementation. The worker
+ * is halted and joined on success, timeout, failure or cancellation before the
+ * caller can release stores. A true predicate at entry starts no worker.
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @param done Synchronous accepted-state/completion predicate, checked before worker startup and each turn.
+ * @param options Required timeoutMs plus optional signer and mailbox polling selection.
+ * @throws Timeout or worker/cleanup failure propagates.
+ */
+export function* runAgentRuntimeUntil(runtime, done, options) {
+    if (done())
+        return;
+    const { timeoutMs, ...workerOptions } = options;
+    const deadline = Date.now() + timeoutMs;
+    const worker = yield* spawn(() => runAgentRuntime(runtime, workerOptions));
+    try {
+        while (!done()) {
+            if (Date.now() >= deadline)
+                throw new Error(`Runtime did not converge within ${timeoutMs}ms.`);
+            yield* runtimeTurn();
+        }
+    }
+    finally {
+        yield* worker.halt();
+    }
+}
+/**
+ * Yield cooperatively back to the host scheduler between runtime turns.
+ *
+ * Re-exported here because earlier Gate E helpers imported the scheduler
+ * boundary from `agent-runtime.ts`, and the boundary still conceptually belongs
+ * to the shared runtime surface even though components use it internally too.
+ */
+export { runtimeTurn } from "./runtime-turn.js";
+/**
+ * Start the independently progressing runtime workers and suspend until halted.
+ * Compose query delivery, Poster delivery, cue routing,
+ * ProtocolProcessor escrows, OOBI/authentication, optional notice/mailbox workers,
+ * delegation and ordinary query sending. The finalizer halts children in reverse
+ * order; store ownership remains with the composition scope.
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @param options Optional default query/cue signer, remote pollMailbox switch
+ * (default true) and command-owned queryCues Deck. Wire queryCues before starting
+ * workers; the application cue owner transfers saved notices to its sole noticer.
+ * Provider storage never enables local consumption.
+ */
+export function* runAgentRuntime(runtime, options = {}) {
+    runtime.querying.configure({ hab: options.hab });
+    const telReceiptor = runtime.vdr ? new Receiptor(runtime.hby, runtime.protocol, runtime.http, runtime.clock) : null;
+    const tasks = [
+        yield* spawn(() => runtime.querying.deliverDo()),
+        yield* spawn(() => runtime.postman.deliverDo()),
+        ...(runtime.vdr && telReceiptor
+            ? [
+                yield* spawn(function* () {
+                    while (true) {
+                        yield* publishPendingTel(runtime.hby, runtime.vdr.publication, telReceiptor, runtime.http, runtime.clock);
+                        yield* runtimeTurn();
+                    }
+                }),
+            ]
+            : []),
+        yield* spawn(function* () {
+            yield* cueDo(runtime, options);
+        }),
+        yield* spawn(function* () {
+            yield* runtime.protocol.escrowDo();
+        }),
+        yield* spawn(function* () {
+            yield* runtime.oobiery.oobiDo();
+        }),
+        yield* spawn(function* () {
+            yield* runtime.authenticator.authDo();
+        }),
+        ...(runtime.signaler
+            ? [
+                yield* spawn(function* () {
+                    yield* runtime.signaler.signalDo();
+                }),
+            ]
+            : []),
+        ...(options.pollMailbox ?? true
+            ? [
+                yield* spawn(function* () {
+                    yield* runtime.mailboxPoller.pollDo((batch) => settleMailboxPollBatch(runtime, batch));
+                }),
+            ]
+            : []),
+        yield* spawn(function* () {
+            while (true) {
+                yield* runtime.delegating.processAllOnce();
+                yield* runtimeTurn();
+            }
+        }),
+    ];
+    try {
+        return yield* suspend();
+    }
+    finally {
+        for (const task of tasks.reverse()) {
+            yield* task.halt();
+        }
+    }
+}

package/esm/keri/npm/src/app/runtime/cue-runtime.js

@@ -0,0 +1,61 @@
+import { runtimeTurn } from "./runtime-turn.js";
+/**
+ * Use an explicitly selected or sole local habitat; never guess among hosted identities.
+ *
+ * @param runtime Borrowed composed runtime containing the actual cue consumers.
+ * @param hab Explicit signing habitat; omission requires a sole local habitat.
+ * @returns Explicit or sole habitat, otherwise null.
+ */
+function resolveCueHab(runtime, hab) {
+    if (hab)
+        return hab;
+    const habitats = runtime.hby.habs.values();
+    const first = habitats.next();
+    return first.done || !habitats.next().done ? null : first.value;
+}
+/**
+ * Route one initial cue batch to its concrete owners before removing source records.
+ *
+ * Transfer query instructions to the sender, stream cues to mailbox correlation
+ * and produced responder messages to Poster. No network delivery runs inline.
+ * Saved key-state facts transfer once to the command's optional query Deck;
+ * its noticer never competes with this worker over the runtime source Deck.
+ * Admission and source removal run synchronously within this finite batch.
+ *
+ * @param runtime Borrowed composed runtime containing the actual cue consumers.
+ * @param options Explicit signer and optional command-owned query cue destination.
+ * Without a query destination, saved notices retain the ordinary unhandled-cue behavior.
+ */
+export function* processCuesOnce(runtime, { hab, queryCues } = {}) {
+    const interpreter = resolveCueHab(runtime, hab);
+    const count = runtime.cues.length;
+    for (let index = 0; index < count; index++) {
+        const cue = runtime.cues.peekHead();
+        if (!cue)
+            break;
+        if (cue.kin === "query") {
+            runtime.querying.enqueueCue(cue, interpreter);
+        }
+        else if (cue.kin === "stream") {
+            runtime.mailboxDirector.retainQueryCue(cue);
+        }
+        else if (interpreter && runtime.respondant.enqueueCue(interpreter, runtime.cues, hab)) {
+            continue;
+        }
+        runtime.cues.pull();
+        if (cue.kin === "keyStateSaved")
+            queryCues?.append(cue);
+    }
+}
+/**
+ * Continuous cue worker; network output belongs to the concrete query and reply workers.
+ *
+ * @param runtime Borrowed composed runtime containing the actual cue consumers.
+ * @param options Explicit signer and optional command-owned query cue destination.
+ */
+export function* cueDo(runtime, options = {}) {
+    while (true) {
+        yield* processCuesOnce(runtime, options);
+        yield* runtimeTurn();
+    }
+}