keri-ts 2.1.0 → 2.2.0

package/esm/keri/npm/src/app/runtime/delivery-outbox.js

@@ -0,0 +1,87 @@
+import { DEFAULT_RETRY_POLICY, RetryBackoff } from "./retry-backoff.js";
+/** Flatten an error and its `cause` chain to one line of text, so a reader sees the transport's own reason. */
+export function describeFailure(error) {
+    const parts = [];
+    for (let e = error, depth = 0; e !== undefined && e !== null && depth < 8; depth++) {
+        parts.push(e instanceof Error ? (e.message || e.name) : String(e));
+        e = e instanceof Error ? e.cause : undefined;
+    }
+    return parts.join(" <- ");
+}
+/** The queue and its retry state for one live operation. */
+export class DeliveryOutbox {
+    constructor(policy = DEFAULT_RETRY_POLICY) {
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "backoff", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Destinations the transport reported for everything delivered so far. */
+        Object.defineProperty(this, "delivered", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        this.backoff = new RetryBackoff(policy);
+    }
+    /** Messages still waiting. */
+    get length() {
+        return this.queue.length;
+    }
+    /** Consecutive delivery failures of the head message. */
+    get attempts() {
+        return this.backoff.attempts;
+    }
+    /** The latest delivery error, or null. */
+    get lastError() {
+        return this.backoff.last;
+    }
+    /** The retry state of the head message, or null while nothing is failing. */
+    get failure() {
+        return this.backoff.attempts === 0
+            ? null
+            : {
+                attempts: this.backoff.attempts,
+                reason: describeFailure(this.backoff.last),
+                retryAt: new Date(this.backoff.next).toISOString(),
+            };
+    }
+    /** Queue a message behind the others. */
+    enqueue(message) {
+        this.queue.push(message);
+    }
+    /**
+     * Deliver the queued messages in order. A failure keeps the message and schedules a retry; it throws only when
+     * `boundMs` is given and failures have lasted that long.
+     *
+     * @returns True when the queue is empty, false while a message waits for its retry.
+     */
+    *drain(transport, clock, boundMs) {
+        while (this.queue.length) {
+            const now = clock.now();
+            if (!this.backoff.due(now))
+                return false;
+            try {
+                const { src, dest, msg, topic } = this.queue[0];
+                this.delivered.push(...yield* transport.deliver({ src, dest, msg: typeof msg === "function" ? msg() : msg, topic }));
+                this.queue.shift();
+                this.backoff.succeeded();
+            }
+            catch (error) {
+                this.backoff.failed(now, error);
+                if (boundMs !== undefined && this.backoff.exhausted(now, boundMs))
+                    throw error;
+                return false;
+            }
+        }
+        return true;
+    }
+}

package/esm/keri/npm/src/app/runtime/doing.js

@@ -0,0 +1,17 @@
+import { waitOnClock } from "./workflow-contract.js";
+/** Milliseconds between passes of the protocol-facing background loops: KERIpy's Doist cycle, as the escrow loop uses. */
+export const PROTOCOL_TOCK_MS = 31.25;
+/** Tocks between full sweeps of a loop that has one: 1920 tocks of 31.25 ms is a minute. */
+export const PROTOCOL_SWEEP_TOCKS = 1920;
+/** The production pacing of the protocol-facing background loops. */
+export const PROTOCOL_PACING = Object.freeze({
+    tockMs: PROTOCOL_TOCK_MS,
+    sweepTocks: PROTOCOL_SWEEP_TOCKS,
+});
+/** Run `pass` forever: pass 0, wait `tockMs` on `clock`, pass 1, and so on. A thrown error ends the doer. */
+export function* doEvery(clock, tockMs, pass) {
+    for (let tock = 0;; tock++) {
+        yield* pass(tock);
+        yield* waitOnClock(clock, tockMs);
+    }
+}

package/esm/keri/npm/src/app/runtime/ipex-auxiliaries.js

@@ -0,0 +1,207 @@
+import { Dhke } from "../../acdc/dhking.js";
+import { Unblind } from "../../acdc/unblinding.js";
+import { ValidationError } from "../../core/errors.js";
+import { isLocalGroupHab } from "../multisig/group-members.js";
+/** Per-identifier DH and Unblind owners behind one query receiver and one reply route each. */
+export class IpexAuxiliaries {
+    /**
+     * @param exc Exchanger shared by every owner.
+     * @param registry Public registry observer shared by every owner.
+     * @param rvy Reply verifier whose router the owners' routes are registered on.
+     * @param now Receiver clock shared by every owner.
+     * @param kram Whether KRAM is enabled; with it off, `approve` of either owner throws.
+     */
+    constructor(exc, registry, rvy, now, 
+    /** Whether the runtime's KRAM is on; DH and Unblind approval need the rows only KRAM writes. */
+    kram) {
+        Object.defineProperty(this, "exc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: exc
+        });
+        Object.defineProperty(this, "registry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: registry
+        });
+        Object.defineProperty(this, "rvy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: rvy
+        });
+        Object.defineProperty(this, "now", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: now
+        });
+        Object.defineProperty(this, "kram", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: kram
+        });
+        /** Unused: `claims` decides which queries this receiver takes. */
+        Object.defineProperty(this, "resource", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "/ipex"
+        });
+        Object.defineProperty(this, "dhkes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "unblinds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "restored", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+    }
+    /** Every live DH owner, for hosts draining their completion cues. */
+    dhkeOwners() {
+        return this.dhkes.values();
+    }
+    /** Every live Unblind owner, for hosts delivering the replies they owe. */
+    unblindOwners() {
+        if (!this.restored) {
+            // A request persisted before a restart is owed its reply by an owner nothing has created yet.
+            this.restored = true;
+            const owed = new Set([...this.exc.hby.db.heldu.getTopItemIter()].map(([[pre]]) => pre));
+            for (const pre of owed) {
+                const hab = this.exc.hby.habs.get(pre);
+                if (!hab)
+                    continue;
+                try {
+                    this.unblind(hab);
+                }
+                catch (error) {
+                    if (!(error instanceof ValidationError))
+                        throw error;
+                }
+            }
+        }
+        return this.unblinds.values();
+    }
+    /** Register the DH and Unblind reply routes once; owners are looked up on each reply. */
+    registerReplyRoutes(rtr) {
+        rtr.addRoute(Dhke.Route, { processReply: (args) => this.reply("dhke", args) });
+        rtr.addRoute(Unblind.Route, { processReply: (args) => this.reply("unblind", args) });
+    }
+    /** The DH owner for `hab`, created on first use and recreated when `hab` is no longer the owner's object. */
+    dhke(hab) {
+        const current = this.dhkes.get(hab.pre);
+        if (current?.hab === hab)
+            return current;
+        const owner = new Dhke({
+            hab,
+            exc: this.exc,
+            registryStore: this.registry.store,
+            rvy: this.rvy,
+            now: this.now,
+            kram: this.kram,
+        });
+        current?.close();
+        this.dhkes.set(hab.pre, owner);
+        return owner;
+    }
+    /** The Unblind owner for `hab`, created on first use and recreated when `hab` is no longer the owner's object. */
+    unblind(hab) {
+        const current = this.unblinds.get(hab.pre);
+        if (current?.hab === hab)
+            return current;
+        const owner = new Unblind({ hab, exc: this.exc, registry: this.registry, rvy: this.rvy, kram: this.kram });
+        current?.close();
+        this.unblinds.set(hab.pre, owner);
+        return owner;
+    }
+    /** Close and unregister both owners of `pre`; process-local approvals and retries are cleared. */
+    release(pre) {
+        this.restored = false;
+        for (const owners of [this.dhkes, this.unblinds]) {
+            owners.get(pre)?.close();
+            owners.delete(pre);
+        }
+    }
+    /** Close every owner; the runtime calls this on explicit close and scope exit. */
+    close() {
+        for (const owner of [...this.dhkes.values(), ...this.unblinds.values()])
+            owner.close();
+        this.dhkes.clear();
+        this.unblinds.clear();
+    }
+    claims(serder) {
+        return this.select(serder) !== null;
+    }
+    processQuery(envelope) {
+        return this.select(envelope.serder)?.processQuery(envelope) ?? { kind: "drop", reason: "missingProcessor" };
+    }
+    reply(kind, args) {
+        const owner = this.claimant(kind, args.serder.pre, args.serder.sad?.a?.x);
+        if (!owner)
+            throw new ValidationError(`No resource is registered to handle route ${args.route}`);
+        return owner.processReply(args);
+    }
+    select(serder) {
+        const kind = serder.route === Dhke.Route ? "dhke" : serder.route === Unblind.Route ? "unblind" : null;
+        return kind && this.claimant(kind, serder.pre, serder.sad?.q?.x);
+    }
+    /**
+     * The owner of the one local identifier party to the transaction, created now if needed; absent or
+     * ambiguous means unowned. Parties come from live owners (approved operations) and from the store.
+     */
+    claimant(kind, sender, xid) {
+        if (!sender || typeof xid !== "string")
+            return null;
+        const owners = kind === "dhke" ? this.dhkes : this.unblinds;
+        const habs = this.exc.hby.habs;
+        const parties = new Set();
+        for (const [pre, owner] of owners)
+            if (owner.inTransaction(sender, xid))
+                parties.add(pre);
+        if (kind === "dhke") {
+            for (const recipient of Dhke.recipients(this.exc.hby.db, sender, xid)) {
+                if (habs.has(recipient))
+                    parties.add(recipient);
+            }
+        }
+        else {
+            for (const pre of habs.keys()) {
+                if (Unblind.recipients(this.exc.hby.db, pre, xid).includes(sender))
+                    parties.add(pre);
+            }
+        }
+        const group = habs.get(sender);
+        if (group && isLocalGroupHab(this.exc.hby, group))
+            parties.add(sender);
+        if (parties.size !== 1)
+            return null;
+        const [pre] = parties;
+        const hab = habs.get(pre);
+        if (!hab) {
+            this.release(pre);
+            return null;
+        }
+        try {
+            return kind === "dhke" ? this.dhke(hab) : this.unblind(hab);
+        }
+        catch (error) {
+            // A group without a local signing member cannot own the route.
+            if (error instanceof ValidationError)
+                return null;
+            throw error;
+        }
+    }
+}

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);
+    });
+}