keri-ts 0.11.0 → 2.0.0

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

@@ -1,638 +0,0 @@
-import { call, resource, spawn } from "effection";
-import { createRegery as createAcdcRegery } from "../acdc/registraring.js";
-import { CueDeck } from "../core/cue-admission.js";
-import { DatabaseNotOpenError } from "../core/errors.js";
-import { CREDENTIAL_MAILBOX_TOPIC, DELEGATE_MAILBOX_TOPIC, RECEIPT_MAILBOX_TOPIC, REPLAY_MAILBOX_TOPIC, REPLY_MAILBOX_TOPIC, } from "../core/mailbox-topics.js";
-import { Mailboxer } from "../db/mailboxing.js";
-import { Noter } from "../db/noting.js";
-import { createReger, Reger } from "../db/reger.js";
-import { Regery as VdrRegery } from "../vdr/credentialing.js";
-import { Tevery } from "../vdr/eventing.js";
-import { Authenticator } from "./authenticating.js";
-import { loadChallengeHandlers } from "./challenging.js";
-import { cueDo, processCuesOnce } from "./cue-runtime.js";
-import { Anchorer, loadDelegationHandlers } from "./delegating.js";
-import { ForwardHandler, MailboxPoller, mailboxTopicForRoute, Poster, } from "./forwarding.js";
-import { loadMultisigHandlers } from "./grouping.js";
-import { loadIpexHandlers } from "./ipexing.js";
-import { MailboxDirector } from "./mailbox-director.js";
-import { mailboxerOptionsForHabery } from "./mailboxing.js";
-import { noterOptionsForHabery, Notifier } from "./notifying.js";
-import { isWellKnownOobiUrl, loadOobiHandlers, Oobiery, parseOobiUrl } from "./oobiery.js";
-import { QueryCoordinator } from "./querying.js";
-import { Reactor } from "./reactor.js";
-import { ReplyStreams } from "./reply-streams.js";
-import { Respondant } from "./respondant.js";
-import { RuntimeDeliveries } from "./runtime-deliveries.js";
-import { resolveRuntimeServices } from "./runtime-services.js";
-import { runtimeTurn } from "./runtime-turn.js";
-import { Signaler } from "./signaling.js";
-import { Verifier } from "./verifying.js";
-/**
- * Create the shared runtime composition root used by CLI commands and
- * `tufa agent`.
- *
- * Construction rule:
- * - every host mode uses the same shared cue deck and the same component
- *   classes
- * - hosting style changes where the runtime is run, not what it is
- */
-export function* createAgentRuntime(hby, options = {}) {
-    const resources = hby.db.resources;
-    if ((options.resources && options.resources !== resources)
-        || (options.services?.resources && options.services.resources !== resources)) {
-        throw new RangeError("AgentRuntime requires the Habery Baser resource policy; supply it when opening Habery");
-    }
-    const injectedSignaler = options.signaler ?? options.notifier?.signaler;
-    if ((injectedSignaler && injectedSignaler.resources !== resources)
-        || (options.notifier && options.notifier.hby !== hby)
-        || (options.signaler && options.notifier && options.signaler !== options.notifier.signaler)) {
-        throw new RangeError("AgentRuntime notification services require its exact Habery and resource policy");
-    }
-    const mode = options.mode ?? "local";
-    const services = resolveRuntimeServices({ ...options.services, resources });
-    const enableMailboxStore = options.enableMailboxStore ?? mode === "indirect";
-    const mailboxer = options.mailboxer
-        ?? (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({ resources });
-            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
-        ?? (noter && signaler ? new Notifier(hby, { noter, signaler }) : null);
-    const vdr = { ...(options.vdr ?? {}) };
-    let ownsReger = false;
-    if (!vdr.reger && !hby.readonly) {
-        vdr.reger = yield* openRegerForHabery(hby);
-        ownsReger = true;
-    }
-    const reger = vdr.reger instanceof Reger ? vdr.reger : null;
-    const acdc = { ...(options.acdc ?? {}) };
-    let ownsAcdcRegery = false;
-    if (acdc.rgy == null && !hby.readonly) {
-        acdc.rgy = yield* openAcdcRegeryForHabery(hby);
-        ownsAcdcRegery = true;
-    }
-    const acdcRegery = acdc.rgy;
-    // Acquire after stores, before processors/consumers: reverse teardown joins consumers, clears cues, closes stores.
-    const cues = yield* resource(function* (provide) {
-        const owned = new CueDeck(resources);
-        try {
-            yield* provide(owned);
-        }
-        finally {
-            owned.clear();
-        }
-    });
-    if (reger && !vdr.tvy) {
-        vdr.tvy = new Tevery({ db: hby.db, reger, cues });
-    }
-    if (reger && !vdr.vry) {
-        vdr.vry = new Verifier(hby, { reger, cues });
-    }
-    if (reger && vdr.tvy instanceof Tevery && vdr.vry instanceof Verifier && !vdr.rgy) {
-        vdr.rgy = new VdrRegery(hby, {
-            reger,
-            tvy: vdr.tvy,
-            vry: vdr.vry,
-            cues,
-        });
-    }
-    // Reverse scope teardown joins borrowed output evidence before its backing stores close.
-    const replyStreams = yield* resource(function* (provide) {
-        const streams = new ReplyStreams(options.replyLimits, resources);
-        try {
-            yield* provide(streams);
-        }
-        finally {
-            streams.close();
-        }
-    });
-    const deliveries = yield* resource(function* (provide) {
-        const deliveries = new RuntimeDeliveries(resources);
-        try {
-            yield* provide(deliveries);
-        }
-        finally {
-            yield* deliveries.close();
-        }
-    });
-    const reactor = new Reactor(hby, {
-        cues,
-        vdr,
-        resources,
-        acdc,
-        messagePolicy: options.messagePolicy,
-        kram: options.kram,
-        now: () => services.clock.now(),
-    });
-    yield* resource(function* (provide) {
-        try {
-            yield* provide();
-        }
-        finally {
-            reactor.clearIngress();
-        }
-    });
-    loadChallengeHandlers(hby.db, reactor.exchanger);
-    loadDelegationHandlers(hby, reactor.exchanger, notifier);
-    loadOobiHandlers(hby, reactor.exchanger, notifier);
-    loadMultisigHandlers(hby, reactor.exchanger, { notifier });
-    loadIpexHandlers(hby, reactor.exchanger, {
-        notifier,
-        registry: acdc.rgy?.store ?? null,
-    });
-    const mailboxDirector = yield* resource(function* (provide) {
-        const director = new MailboxDirector(hby, {
-            ...(mailboxer ? { mailboxer } : {}),
-            resources,
-            streamLimits: options.mailboxStreamLimits,
-        });
-        try {
-            yield* provide(director);
-        }
-        finally {
-            yield* call(() => director.close());
-        }
-    });
-    const poster = new Poster(hby, { mailboxer, services });
-    const respondant = new Respondant(hby, { poster, mailboxDirector });
-    if (mailboxer) {
-        reactor.exchanger.addHandler(new ForwardHandler(mailboxDirector));
-    }
-    for (const route of reactor.exchanger.routes.keys()) {
-        if (route === ForwardHandler.resource) {
-            continue;
-        }
-        const topic = mailboxTopicForRoute(route);
-        if (topic.length > 0) {
-            mailboxDirector.registerTopic(topic);
-        }
-    }
-    const mailboxPoller = new MailboxPoller(hby, mailboxDirector, {
-        services,
-        pollTransport: options.mailboxPollTransport,
-        mailboxAdmission: options.mailboxAdmission,
-    });
-    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 coordinator = new QueryCoordinator(hby);
-        try {
-            yield* provide(coordinator);
-        }
-        finally {
-            yield* coordinator.close();
-        }
-    });
-    const delegating = new Anchorer(hby, { poster, querying, services });
-    const oobiery = new Oobiery(hby, reactor, { cues, services });
-    oobiery.registerReplyRoutes(reactor.router);
-    const authenticator = new Authenticator(hby, { services });
-    return {
-        hby,
-        resources,
-        mode,
-        mailboxer,
-        noter,
-        notifier,
-        signaler,
-        cues,
-        reactor,
-        oobiery,
-        authenticator,
-        mailboxDirector,
-        respondant,
-        mailboxPoller,
-        poster,
-        delegating,
-        querying,
-        replyStreams,
-        deliveries,
-        vdr,
-        acdc,
-        services,
-        *close() {
-            reactor.clearIngress();
-            const failures = [];
-            const cleanup = [
-                function* () {
-                    yield* querying.close();
-                },
-                function* () {
-                    if (ownsSignaler)
-                        signaler?.close();
-                },
-                function* () {
-                    yield* deliveries.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. */
-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. */
-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. */
-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. */
-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 CESR/KERI message byte sequence for runtime parsing.
- *
- * This is the supported ingress seam for both local synthetic messages and
- * remotely fetched OOBI material.
- */
-export function ingestKeriBytes(runtime, bytes) {
-    runtime.reactor.ingest(bytes);
-}
-/**
- * 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.
- */
-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
- */
-export function* settleRuntimeIngress(runtime, messages, { local, mailboxAid, } = {}) {
-    for (const message of messages) {
-        yield* runtime.reactor.processBytes(message, { local, mailboxAid });
-    }
-    yield* runtime.reactor.processEscrowsOnce();
-}
-/**
- * Settle one mailbox retrieval batch while preserving per-source boundaries.
- *
- * Local and remote poll results are intentionally processed batch-by-batch so
- * follow-on escrow progress can occur before the next source is consumed.
- */
-export function* settleMailboxPollBatch(runtime, batch) {
-    for (const message of batch.messages) {
-        yield* runtime.reactor.processBytes(message);
-    }
-    yield* runtime.reactor.processEscrowsOnce();
-}
-/**
- * Drain one bounded mailbox polling turn and settle each returned batch.
- *
- * This keeps mailbox polling ownership inside the shared runtime surface so
- * commands do not need to know how mailbox ingress is parsed and escrowed.
- */
-export function* processMailboxTurn(runtime, options = {}) {
-    runtime.mailboxPoller.configure({ hab: options.hab });
-    const batches = yield* runtime.mailboxPoller.processOnce({
-        budgetMs: options.budgetMs,
-    });
-    for (const batch of batches) {
-        yield* settleMailboxPollBatch(runtime, batch);
-    }
-    return batches;
-}
-/**
- * Drain one bounded runtime turn by delegating to component-owned flows.
- *
- * Turn order:
- * 1. `Reactor.processOnce()` drains queued ingress
- * 2. `Oobiery.processOnce()` resolves at most one durable OOBI record
- * 3. `Authenticator.processOnce()` advances one well-known auth step
- * 4. `processCuesOnce()` emits cues from fresh ingress/OOBI work into
- *    `QueryCoordinator`
- * 5. `QueryCoordinator.processPending()` resolves any newly correspondence-ready
- *    query work
- * 6. `Reactor.processEscrowsOnce()` runs KEL and reply escrow passes
- * 7. `processCuesOnce()` emits cues created during escrow progress
- * 8. `QueryCoordinator.processPending()` resolves any follow-on query work
- *
- * This helper remains because command-local CLI flows and focused tests need a
- * single deterministic step without having to spawn the long-lived doers.
- */
-export function* processRuntimeTurn(runtime, options = {}) {
-    runtime.querying.configure({ hab: options.hab, sink: options.sink });
-    yield* runtime.reactor.processOnce();
-    yield* runtime.oobiery.processOnce();
-    yield* runtime.authenticator.processOnce();
-    yield* runtime.poster.processPending(runtime);
-    yield* runtime.delegating.processAllOnce(runtime);
-    runtime.signaler?.processOnce();
-    if (options.pollMailbox ?? true) {
-        yield* processMailboxTurn(runtime, { hab: options.hab });
-    }
-    yield* processCuesOnce(runtime, { ...options, sink: runtime.querying });
-    yield* runtime.querying.processPending(runtime);
-    yield* runtime.reactor.processEscrowsOnce();
-    yield* runtime.delegating.processAllOnce(runtime);
-    yield* processCuesOnce(runtime, { ...options, sink: runtime.querying });
-    yield* runtime.querying.processPending(runtime);
-    yield* runtime.deliveries.process(runtime);
-}
-/**
- * Return the current pending-work summary for bounded command-local hosts.
- *
- * `queriesPending` is part of convergence because query continuations may still
- * owe a follow-on `logs` query or local catch-up wait after normal cue decks
- * and ingress have drained.
- */
-export function runtimePendingState(runtime) {
-    return {
-        ingress: runtime.reactor.hasIngress,
-        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,
-        outboxPending: runtime.poster.hasPendingWork(),
-        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.deliveries.hasPending,
-    };
-}
-/** Return true when any command-local runtime work remains in flight. */
-export function runtimeHasPendingWork(runtime) {
-    const state = runtimePendingState(runtime);
-    return state.ingress || state.cues || state.replyEscrow
-        || state.oobiQueued || state.oobiInFlight || state.multiPending
-        || state.authQueued || state.authInFlight || state.outboxPending
-        || state.delegationPending
-        || state.queriesPending
-        || state.deliveriesPending;
-}
-/** Return true when a well-known URL has been authorized into `wkas.`. */
-export function runtimeHasWellKnownAuth(runtime, url) {
-    const cid = parseOobiUrl(url).cid;
-    if (!cid) {
-        return false;
-    }
-    return runtime.hby.db.wkas.get(cid).some((record) => record.url === url);
-}
-/** Return the current terminal state projection for one requested OOBI URL. */
-export function runtimeOobiTerminalState(runtime, url) {
-    if (isWellKnownOobiUrl(url)) {
-        const record = runtime.hby.db.rmfa.get(url);
-        if (!record) {
-            return { status: "pending", via: "none", record: null };
-        }
-        return {
-            status: record.state === "resolved" ? "resolved" : "failed",
-            via: "rmfa",
-            record,
-        };
-    }
-    const failed = runtime.hby.db.eoobi.get(url);
-    if (failed) {
-        return { status: "failed", via: "eoobi", record: failed };
-    }
-    const resolved = runtime.hby.db.roobi.get(url);
-    if (resolved) {
-        return { status: "resolved", via: "roobi", record: resolved };
-    }
-    return { status: "pending", via: "none", record: null };
-}
-/**
- * Return true once one requested OOBI has reached a terminal state and all
- * related runtime work has drained.
- */
-export function runtimeOobiConverged(runtime, url) {
-    return runtimeOobiTerminalState(runtime, url).status !== "pending"
-        && !runtimeHasPendingWork(runtime);
-}
-/**
- * Drive the shared runtime until the caller-provided completion predicate
- * succeeds or the bounded turn budget is exhausted.
- */
-export function* processRuntimeUntil(runtime, done, options = {}) {
-    const maxTurns = options.maxTurns ?? 64;
-    for (let turn = 0; turn < maxTurns; turn++) {
-        if (done()) {
-            return;
-        }
-        yield* processRuntimeTurn(runtime, options);
-        if (done()) {
-            return;
-        }
-        if (!runtimeHasPendingWork(runtime)) {
-            yield* runtimeTurn();
-        }
-    }
-    throw new Error(`Runtime did not converge within ${maxTurns} turns.`);
-}
-/**
- * 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";
-/**
- * Run the shared runtime continuously until the surrounding host halts it.
- *
- * Component/doer model:
- * - `Reactor.msgDo()` owns continuous ingress draining
- * - `Reactor.escrowDo()` owns continuous escrow reprocessing
- * - `Oobiery.oobiDo()` owns durable OOBI resolution
- * - `Authenticator.authDo()` owns well-known auth convergence
- * - `QueryCoordinator.queryDo()` owns deferred query correspondence work
- *
- * The root itself now acts as a composition host: it starts the component
- * doers and stays alive until the surrounding Effection scope halts.
- */
-export function* runAgentRuntime(runtime, options = {}) {
-    runtime.querying.configure({ hab: options.hab, sink: options.sink });
-    runtime.mailboxPoller.configure({ hab: options.hab });
-    const tasks = [
-        yield* spawn(function* () {
-            while (true) {
-                yield* runtime.deliveries.process(runtime);
-                yield* runtimeTurn();
-            }
-        }),
-        yield* spawn(function* () {
-            yield* runtime.reactor.msgDo();
-        }),
-        yield* spawn(function* () {
-            yield* cueDo(runtime, { ...options, sink: runtime.querying });
-        }),
-        yield* spawn(function* () {
-            yield* runtime.reactor.escrowDo();
-        }),
-        yield* spawn(function* () {
-            yield* runtime.oobiery.oobiDo();
-        }),
-        yield* spawn(function* () {
-            yield* runtime.authenticator.authDo();
-        }),
-        ...(runtime.signaler
-            ? [
-                yield* spawn(function* () {
-                    yield* runtime.signaler.signalDo();
-                }),
-            ]
-            : []),
-        yield* spawn(function* () {
-            while (true) {
-                yield* runtime.poster.processPending(runtime);
-                yield* runtimeTurn();
-            }
-        }),
-        yield* spawn(function* () {
-            yield* runtime.mailboxPoller.pollDo((batch) => settleMailboxPollBatch(runtime, batch));
-        }),
-        yield* spawn(function* () {
-            while (true) {
-                yield* runtime.delegating.processAllOnce(runtime);
-                yield* runtimeTurn();
-            }
-        }),
-        yield* spawn(function* () {
-            yield* runtime.querying.queryDo(runtime);
-        }),
-    ];
-    try {
-        while (true) {
-            yield* runtimeTurn();
-        }
-    }
-    finally {
-        for (const task of tasks.reverse()) {
-            yield* task.halt();
-        }
-    }
-}