keri-ts 2.1.0 → 2.2.1

package/esm/keri/npm/src/app/runtime/operation-owners.js

@@ -0,0 +1,151 @@
+import { BaserDerivedUpdateStore } from "../../acdc/custody.js";
+import { RootReplicator } from "../credentials/root-replicator.js";
+import { GroupIpexOperations } from "../ipex/group-ipex.js";
+import { IssuanceOperations, posterDelivery } from "../ipex/issuance.js";
+import { PresentationOperations } from "../ipex/presenting.js";
+import { UnblindingOperations } from "../ipex/unblinding-workflow.js";
+import { doEvery } from "./doing.js";
+/** Milliseconds between owner passes; the cadence of the CLI drivers the loop replaced. */
+export const OWNER_TOCK_MS = 50;
+/** Tocks between the replicator's full rotation checks: 1200 tocks of 50 ms is a minute. */
+export const OWNER_SWEEP_TOCKS = 1200;
+/** The production pacing of the owner loop. */
+export const OWNER_PACING = Object.freeze({
+    tockMs: OWNER_TOCK_MS,
+    sweepTocks: OWNER_SWEEP_TOCKS,
+});
+/**
+ * Failures of the owner loop itself. A failure of one operation (a delivery that throws, an unreadable stored
+ * Grant) ends that operation as `failed` and is never recorded here; this records only what escaped an owner
+ * pass, which the loop survives so that the other owners keep running. `faults` counts them and `last` keeps
+ * the latest. Nothing clears it: a host reads it and decides.
+ */
+export class OwnerHealth {
+    constructor() {
+        Object.defineProperty(this, "faults", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "last", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+}
+/** Construct the owners over their in-memory tables; the derivation store defaults to the registry database. */
+export function composeOwners(parts, stores = {}) {
+    const { hby, acdc, exc, protocol, reactor, postman, receiptor, ipex, clock, registryRoot, mux, counselor } = parts;
+    const changes = stores.changes ?? parts.changes, delivery = posterDelivery(postman);
+    const issuance = {
+        hby,
+        rgy: acdc,
+        exc,
+        receiptor,
+        dhkes: ipex,
+        reactor,
+        protocol,
+        delivery,
+        derived: stores.derived ?? new BaserDerivedUpdateStore(acdc.store.baser),
+        clock,
+        changes,
+        retry: parts.retry,
+        queryResendMs: parts.queryResendMs,
+        group: { mux, registry: { hby, protocol, postman, counselor, registryStore: acdc.store } },
+    };
+    const operations = {
+        issuance: new IssuanceOperations(issuance),
+        groupIpex: new GroupIpexOperations({
+            hby,
+            rgy: acdc,
+            exc,
+            protocol,
+            postman,
+            clock,
+            registry: { hby, protocol, postman, counselor, registryStore: acdc.store },
+            changes,
+        }),
+        presentation: new PresentationOperations({
+            hby,
+            rgy: acdc,
+            exc,
+            receiptor,
+            reactor,
+            protocol,
+            delivery,
+            clock,
+            derived: issuance.derived,
+            views: stores.views,
+            retry: parts.retry,
+            changes,
+        }),
+        health: new OwnerHealth(),
+        unblinding: new UnblindingOperations({
+            hby,
+            exc,
+            unblinds: ipex,
+            group: { mux, protocol },
+            delivery,
+            clock,
+            retry: parts.retry,
+            changes,
+        }),
+    };
+    const rootReplicator = registryRoot ? new RootReplicator({ root: registryRoot, postman, clock, changes }) : null;
+    return { operations, rootReplicator };
+}
+/**
+ * Run every owner on one fiber until halted, as a fixed-tock doer (`./doing.ts`): each tock runs an owner that
+ * has live work, then the replicator (after prompting it with the live DH owners' `replicated` cues), and then
+ * the loop waits one tock. Work begun between tocks is seen on the next one; nothing wakes the loop early.
+ *
+ * Idle cost, per tock: four constant-time table checks, one in-memory walk of the Unblind owners for an owed
+ * reply, one drain of each DH owner's cue deck, and the replicator's emptiness checks. The replicator's
+ * rotation check (the establishment SAID of each local group, one keyed read per local identifier) runs on
+ * tock 0 and every `pacing.sweepTocks`. No owner reads a protocol store. Only the first pass, once, scans the
+ * pending exchange escrow for resumable Grants.
+ *
+ * A failure that escapes an owner pass is recorded in `operations.health` and the loop keeps running, so
+ * one owner's fault never stops the others. The owners run one after another, so a delivery that does not return holds the others up until it fails or
+ * its Grant deadline passes; operations already bound each delivery by that deadline.
+ */
+export function* operationOwnersDo(owners, pacing = OWNER_PACING) {
+    const { operations, rootReplicator, ipex, clock } = owners, { health } = operations;
+    const guarded = function* (owner, pass) {
+        try {
+            yield* pass();
+        }
+        catch (error) {
+            health.faults++;
+            health.last = {
+                owner,
+                error: error instanceof Error ? error.message : String(error),
+                at: new Date(clock.now()).toISOString(),
+            };
+        }
+    };
+    return yield* doEvery(clock, pacing.tockMs, function* (tock) {
+        if (operations.issuance.active())
+            yield* guarded("issuance", () => operations.issuance.processOnce());
+        if (operations.groupIpex.active())
+            yield* guarded("groupIpex", () => operations.groupIpex.processOnce());
+        if (operations.presentation.active())
+            yield* guarded("presentation", () => operations.presentation.processOnce());
+        if (operations.unblinding.active())
+            yield* guarded("unblinding", () => operations.unblinding.processOnce());
+        if (rootReplicator) {
+            yield* guarded("replicator", function* () {
+                for (const dh of ipex.dhkeOwners()) {
+                    while (dh.replicated.length)
+                        rootReplicator.replicate(dh.replicated.pull());
+                }
+                if (tock % pacing.sweepTocks === 0)
+                    rootReplicator.sweep();
+                yield* rootReplicator.processDue();
+            });
+        }
+    });
+}

package/esm/keri/npm/src/app/runtime/retry-backoff.js

@@ -0,0 +1,93 @@
+/**
+ * Retry state for a transient delivery failure inside a live operation.
+ *
+ * A member that is briefly offline is normal, so an owner keeps the unsent work, waits with a doubling delay and
+ * tries again on a later pass instead of ending the operation at the first error. The owner decides when retrying
+ * stops: an operation with a deadline ends at the deadline, and one without ends once failures have lasted the
+ * bound it states.
+ */
+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 __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 _RetryBackoff_next;
+/** Delay after the first failure; it doubles per consecutive failure up to {@link RETRY_MAX_MS}. */
+export const RETRY_BASE_MS = 1_000;
+/** Longest delay between attempts. */
+export const RETRY_MAX_MS = 30_000;
+/** How long failures may last before an owner with no deadline of its own gives up. */
+export const RETRY_BOUND_MS = 600_000;
+/** The production delays of delivery retries. */
+export const DEFAULT_RETRY_POLICY = Object.freeze({
+    baseMs: RETRY_BASE_MS,
+    maxMs: RETRY_MAX_MS,
+    boundMs: RETRY_BOUND_MS,
+});
+/** Consecutive-failure counter with a next-attempt time; memory only. */
+export class RetryBackoff {
+    constructor(policy = DEFAULT_RETRY_POLICY) {
+        Object.defineProperty(this, "policy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: policy
+        });
+        /** Consecutive failures since the last success. */
+        Object.defineProperty(this, "attempts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /** Time of the first failure of the current run (host clock, ms); 0 when none. */
+        Object.defineProperty(this, "since", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /** Error of the latest failure. */
+        Object.defineProperty(this, "last", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        _RetryBackoff_next.set(this, 0);
+    }
+    /** Host-clock time (ms) of the next attempt. */
+    get next() {
+        return __classPrivateFieldGet(this, _RetryBackoff_next, "f");
+    }
+    /** Whether an attempt may be made at `now`. */
+    due(now) {
+        return now >= __classPrivateFieldGet(this, _RetryBackoff_next, "f");
+    }
+    /** Record a failure at `now` and schedule the next attempt. */
+    failed(now, error) {
+        if (this.attempts === 0)
+            this.since = now;
+        this.attempts++;
+        this.last = error;
+        __classPrivateFieldSet(this, _RetryBackoff_next, now + Math.min(this.policy.baseMs * 2 ** (this.attempts - 1), this.policy.maxMs), "f");
+    }
+    /** Whether failures have lasted at least `boundMs` by `now`. */
+    exhausted(now, boundMs) {
+        return this.attempts > 0 && now - this.since >= boundMs;
+    }
+    /** Forget failures after a success. */
+    succeeded() {
+        this.attempts = 0;
+        this.since = 0;
+        this.last = null;
+        __classPrivateFieldSet(this, _RetryBackoff_next, 0, "f");
+    }
+}
+_RetryBackoff_next = new WeakMap();

package/esm/keri/npm/src/app/runtime/workflow-contract.js

@@ -0,0 +1,80 @@
+/**
+ * Shared pieces of the library workflow contract.
+ *
+ * Library workflows follow one shape: `begin*` is an explicit operation that
+ * returns after local commit, `*Status` is a pure synchronous read, and
+ * `waitFor*` only observes. A wait never starts runtime workers: a host that
+ * already runs a runtime must not get a second poller and escrow loop. One-shot
+ * hosts such as the CLI run the runtime around the wait themselves
+ * (`cli/common/runtime-workers.ts`). Remote and time-driven outcomes, including
+ * an expired wait, are returned values; only caller-contract, invariant and
+ * infrastructure failures throw.
+ */
+import { action, sleep } from "effection";
+import { systemClock } from "./runtime-clock.js";
+import { runtimeTurn } from "./runtime-turn.js";
+/** In-memory sink that records changes in order. */
+export class MemoryChangeSink {
+    constructor() {
+        Object.defineProperty(this, "changes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+    }
+    push(change) {
+        this.changes.push({ kind: change.kind, id: change.id });
+    }
+}
+/**
+ * Back a sink with the host's transient `Signaler`. Publishing needs no polling:
+ * `push` is a synchronous append that collapses repeats of one workflow into a
+ * single signal (collapse key `kind:id`). Delivery is pull-based, though: the
+ * Signaler has no subscriber hook, so the consumer must read `signaler.list()`.
+ * A closed or failing Signaler drops the change instead of throwing: a hint must
+ * never break the workflow that published it.
+ */
+export function signalerChangeSink(signaler) {
+    return {
+        push: ({ kind, id }) => {
+            try {
+                signaler.push({ id }, `/workflow/${kind}`, { ckey: `${kind}:${id}` });
+            }
+            catch {
+                // Dropped on purpose; consumers re-read status and tolerate a missed hint.
+            }
+        },
+    };
+}
+/**
+ * Observe-only wait: poll `done`, yielding to the scheduler between checks,
+ * until it holds or the deadline passes. Starts no worker and has no effects of
+ * its own.
+ *
+ * @param done Synchronous status read; checked before the first yield.
+ * @param pollMs Elapsed milliseconds between checks. Omitted: yield one scheduler turn.
+ * @returns True when `done` held, false when `timeoutMs` elapsed first.
+ */
+export function* observeUntil(done, { timeoutMs, clock = systemClock, pollMs }) {
+    const deadline = clock.now() + timeoutMs;
+    while (!done()) {
+        const remaining = deadline - clock.now();
+        if (remaining <= 0)
+            return false;
+        if (pollMs === undefined)
+            yield* runtimeTurn();
+        else
+            yield* sleep(Math.min(pollMs, remaining));
+    }
+    return true;
+}
+/**
+ * Wait `milliseconds` on the host's clock, so a fake clock drives it and cancellation releases the timer.
+ */
+export function* waitOnClock(clock, milliseconds) {
+    yield* action((resolve) => {
+        const timer = clock.setTimeout(resolve, milliseconds);
+        return () => clock.clearTimeout(timer);
+    });
+}

package/esm/keri/npm/src/app/transport/http-client.js

@@ -4,6 +4,21 @@ import { ValidationError } from "../../core/errors.js";
 import { abortable } from "../runtime/abortable.js";
 import { collectBytes } from "./byte-source.js";
 import { TransportError } from "./transport-error.js";
+/**
+ * Native requests and signals that a pending `fetch` still needs. WebKit links an in-flight fetch to
+ * its abort signal only weakly: once the `Request`, or an `AbortSignal.any` composite, is garbage
+ * collected, `abort()` neither rejects the fetch nor closes the connection, so a halted caller waits
+ * forever on a request that WebKit will never settle. A strong reference until the request scope
+ * ends keeps the link alive; engines that hold it themselves are unaffected.
+ */
+const inFlight = new Set();
+/**
+ * Whether `cause` is the rejection an abort of `signal` produces. Chromium rejects with `signal.reason`;
+ * Node 20 and WebKit reject with a fresh native `AbortError`, which is the same cancellation.
+ */
+function isAbort(cause, signal) {
+    return cause === signal.reason || (cause instanceof DOMException && cause.name === "AbortError");
+}
 /**
  * Own the native Request, fetch and response reader for one attempt.
  * Construction errors remain outside network classification. Native fetch/read
@@ -44,6 +59,7 @@ export class FetchHttpClient {
             const controller = new AbortController();
             const signal = init.signal ? AbortSignal.any([controller.signal, init.signal]) : controller.signal;
             // These handles let scope teardown join native work before releasing the reader.
+            let request;
             let fetching;
             let reader;
             let reading;
@@ -57,7 +73,9 @@ export class FetchHttpClient {
              * @param message Operation detail to combine with the endpoint URL.
              * @returns Original cancellation reason or a TransportError retaining cause.
              */
-            const transportFailure = (cause, message) => signal.aborted && cause === signal.reason ? cause : new TransportError(`${message} for ${url}`, { cause });
+            const transportFailure = (cause, message) => signal.aborted && isAbort(cause, signal)
+                ? signal.reason
+                : new TransportError(`${message} for ${url}`, { cause });
             try {
                 signal.throwIfAborted();
                 const endpoint = new URL(url);
@@ -65,7 +83,8 @@ export class FetchHttpClient {
                     throw new ValidationError("HTTP output requires an HTTP(S) URL without credentials");
                 }
                 // Construction errors are caller errors, before native network classification.
-                const request = new Request(url, { ...init, signal, body: init.body });
+                request = new Request(url, { ...init, signal, body: init.body });
+                inFlight.add(request).add(signal);
                 fetching = fetch(request).catch((cause) => {
                     throw transportFailure(cause, "HTTP request failed");
                 });
@@ -99,9 +118,6 @@ export class FetchHttpClient {
                                         signal.throwIfAborted();
                                         reading = reader.read().catch((cause) => {
                                             // Node 20 Fetch replaces the supplied reason with a native AbortError during body reads.
-                                            if (signal.aborted && cause instanceof DOMException && cause.name === "AbortError") {
-                                                throw signal.reason;
-                                            }
                                             throw transportFailure(cause, "HTTP response body failed");
                                         });
                                         let result;
@@ -144,7 +160,7 @@ export class FetchHttpClient {
                             await pending;
                         }
                         catch (error) {
-                            if (error !== signal.reason && error !== failure?.error)
+                            if (!isAbort(error, signal) && error !== failure?.error)
                                 cleanup.push(error);
                         }
                     }
@@ -156,6 +172,9 @@ export class FetchHttpClient {
                     }
                     bodySignal?.removeEventListener("abort", abortBody);
                 });
+                if (request)
+                    inFlight.delete(request);
+                inFlight.delete(signal);
                 // Throw outside the Promise leaf so Effection teardown preserves genuine cleanup failures.
                 if (cleanup.length) {
                     if (failure && failure.error !== signal.reason)

package/esm/keri/npm/src/app/witness/http-endpoints.js

@@ -1,5 +1,5 @@
 /** Witness HTTP semantic policies for receipts, log queries and endorsed key state; adapters format decisions. */
-import { Ilks, Vrsn_2_0 } from "cesr-ts";
+import { Ilks } from "cesr-ts";
 import { receipt as receiptEvent, reply as replyEvent } from "../../core/protocol-eventing.js";
 import { dgKey } from "../../db/core/keys.js";
 import { inspectCesrRequest } from "../transport/cesr-http.js";
@@ -178,8 +178,8 @@ export function witnessKeyStateGet(serviceHab, query) {
         status: 200,
         body: serviceHab.endorse(replyEvent(`/ksn/${serviceHab.pre}`, kever.state().asDict(), {
             pre: serviceHab.pre,
-            pvrsn: Vrsn_2_0,
-            gvrsn: Vrsn_2_0,
-        }), { gvrsn: Vrsn_2_0 }),
+            pvrsn: serviceHab.kelVersion,
+            gvrsn: serviceHab.kelVersion,
+        }), { gvrsn: serviceHab.kelVersion }),
     };
 }

package/esm/keri/npm/src/cli/common/event-completion.js

@@ -0,0 +1,49 @@
+import { completeEvent } from "../../app/identity/event-completion.js";
+import { KelPublisher } from "../../app/mailbox/kel-publisher.js";
+import { createProtocolProcessor } from "../../app/protocol/protocol-processing.js";
+import { createAgentRuntime } from "../../app/runtime/agent-runtime.js";
+import { systemClock } from "../../app/runtime/runtime-clock.js";
+import { withRuntimeWorkers } from "./runtime-workers.js";
+/**
+ * Compose event-completion dependencies for one CLI command.
+ *
+ * A short-lived runtime is created only when a delegated event needs workers.
+ * It is lent to the library for that one scope with its workers running around
+ * the library's observe-only wait, and closed on every exit path.
+ */
+export function cliEventCompletionDeps(hby, http) {
+    // A command has no running runtime, so it carries the publisher whose pass `completeEventOrThrow` runs.
+    const publisher = new KelPublisher({ hby, http, clock: systemClock });
+    return {
+        hby,
+        publisher,
+        rotated: publisher.rotated,
+        protocol: createProtocolProcessor(hby),
+        http,
+        clock: systemClock,
+        *withDelegation(hab, use) {
+            const runtime = yield* createAgentRuntime(hby, http, systemClock);
+            try {
+                return yield* withRuntimeWorkers(runtime, { hab, pollMailbox: true }, () => use({ anchorer: runtime.delegating }));
+            }
+            finally {
+                yield* runtime.close();
+            }
+        },
+    };
+}
+/**
+ * `completeEvent` for commands: an expired delegation wait fails the command with
+ * the text the CLI has always printed, then the caller sees the usual result.
+ */
+export function* completeEventOrThrow(deps, ...args) {
+    const completion = yield* completeEvent(deps, ...args);
+    if (completion.outcome === "timed-out") {
+        throw new Error(`Runtime did not converge within ${completion.timeoutMs}ms.`);
+    }
+    // No fiber runs the publisher in a one-shot command: tell the mailboxes of a completed rotation now. A
+    // mailbox that cannot be reached stays owed in the marker and the poller repairs it.
+    if (!deps.publisher.rotated.empty)
+        yield* deps.publisher.processOnce();
+    return completion;
+}

package/esm/keri/npm/src/cli/common/runtime-workers.js

@@ -0,0 +1,23 @@
+import { spawn } from "effection";
+import { runAgentRuntime } from "../../app/runtime/agent-runtime.js";
+/**
+ * Run the runtime workers around one observe-only library call.
+ *
+ * Library workflows only observe (see `app/runtime/workflow-contract.ts`); a
+ * one-shot CLI command has no running runtime, so it supplies the workers here.
+ * The worker is halted and joined on success, failure and cancellation before
+ * the caller can release stores.
+ *
+ * @param runtime Borrowed composed runtime; the command owns its lifetime.
+ * @param options Signer, mailbox polling and command-owned query cue Deck.
+ * @param use Observe-only operation that depends on the workers' progress.
+ */
+export function* withRuntimeWorkers(runtime, options, use) {
+    const worker = yield* spawn(() => runAgentRuntime(runtime, options));
+    try {
+        return yield* use();
+    }
+    finally {
+        yield* worker.halt();
+    }
+}