keri-ts 1.0.0 → 2.0.1

package/esm/keri/npm/src/app/{query-replies.js → queries/query-replies.js}

@@ -1,6 +1,16 @@
-/** Reserve direct query replies before any background cue consumer can take them. */
+/**
+ * Capture connection-owned proof/reply cues before background output consumes them.
+ * Direct TCP queries and request-owned event receipts need this correlation;
+ * ordinary HTTP queries use independent output/receive paths instead. Reserving
+ * a SAID creates a lifetime slot, never authorization to read a mailbox or proof
+ * that protocol processing accepted the request. Each borrower must close its slot.
+ */
 export class QueryReplies {
-    /** Borrow the application output flow so a late request claims matching queued replies synchronously. */
+    /**
+     * Borrow the application output flow so a late request claims matching queued replies synchronously.
+     *
+     * @param published Borrowed application cue Deck, synchronously scanned when a late request reserves a slot.
+     */
     constructor(published) {
         Object.defineProperty(this, "published", {
             enumerable: true,
@@ -16,15 +26,31 @@ export class QueryReplies {
             value: new Map()
         });
     }
-    /** Reserve one response; duplicate arrivals never add another retained batch. */
+    /**
+     * Reserve one response; duplicate arrivals never add another retained batch.
+     *
+     * @param said Query SAID used for correlation, never sufficient proof of request authorization.
+     * @returns A new request-owned slot; close it on request completion/cancellation.
+     */
     reserve(said) {
         return this.reserveKey(`query:${said}`);
     }
-    /** A connection owns only receipts for its exact event; unrelated runtime cues stay routed normally. */
+    /**
+     * A connection owns only receipts for its exact event; unrelated runtime cues stay routed normally.
+     *
+     * @param pre Subject event AID.
+     * @param said Exact event SAID whose receipt/witness output belongs to the connection.
+     * @returns A request-owned event-proof slot.
+     */
     reserveEvent(pre, said) {
         return this.reserveKey(`event:${pre}:${said}`);
     }
-    /** Reuse the request slot for queries and accepted-event proofs. */
+    /**
+     * Reuse the request slot for queries and accepted-event proofs.
+     *
+     * @param said Internal query:/event: correlation key.
+     * @returns An independent slot, immediately capturing any already-published matching output.
+     */
     reserveKey(said) {
         const slot = { reply: undefined, companion: undefined };
         const group = this.active.get(said) ?? new Set();
@@ -33,9 +59,20 @@ export class QueryReplies {
         let closed = false;
         this.capture(this.published);
         return {
+            /**
+             * Expose whether this request has captured evidence.
+             *
+             * @returns True when a first reply is retained; does not itself authorize the request.
+             */
             get ready() {
                 return slot.reply !== undefined;
             },
+            /**
+             * Install the sole readiness observer for this slot.
+             *
+             * @param notify Synchronous wake-up callback; invoked immediately if ready or closed.
+             * @returns A function removing this observer without closing the request slot.
+             */
             observeReady(notify) {
                 if (slot.notify)
                     throw new Error("Reply slot already has a readiness observer");
@@ -47,11 +84,21 @@ export class QueryReplies {
                         slot.notify = undefined;
                 };
             },
+            /**
+             * Inspect evidence without consuming it so callers can finish construction first.
+             *
+             * @returns Borrowed ordered cue batch, or undefined without a first reply.
+             */
             peekAll() {
                 if (!slot.reply)
                     return;
                 return { cues: slot.companion ? [slot.reply, slot.companion] : [slot.reply] };
             },
+            /**
+             * Consume this slot only after its caller has prepared the complete output.
+             *
+             * @returns Current batch, clearing this slot's retained references.
+             */
             takeAll() {
                 const batch = this.peekAll();
                 slot.reply = slot.companion = undefined;
@@ -70,7 +117,11 @@ export class QueryReplies {
             },
         };
     }
-    /** Capture correlated reply pairs and share their ordinary records among matching requests. */
+    /**
+     * Capture correlated reply pairs and share their ordinary records among matching requests.
+     *
+     * @param source Cue Deck to scan through its initial extent; unmatched cues retain their order.
+     */
     capture(source) {
         const count = source.length;
         for (let i = 0; i < count; i++) {

package/esm/keri/npm/src/app/queries/querying.js

@@ -0,0 +1,306 @@
+import { runtimeTurn } from "../runtime/runtime-turn.js";
+/** Snapshot the caller's attester list before the workflow starts. */
+function copyOptions(options) {
+    return { signer: options.signer, wits: options.wits ? [...options.wits] : undefined };
+}
+/** Preserve the existing nonnegative hex query ordinal convention. */
+function hexOrdinal(value) {
+    return Math.max(0, value).toString(16);
+}
+/** Wait for an accepted KEL sequence, never for transport or queue completion. */
+function* awaitSequence(db, pre, sn) {
+    while (true) {
+        const local = db.getKever(pre);
+        if (local && local.sn >= sn)
+            return;
+        yield* runtimeTurn();
+    }
+}
+/**
+ * Ask an attester for current key state and recover the KEL if its notice is ahead.
+ *
+ * A saved KSN is a remote statement, not acceptance of the referenced KEL. A
+ * matching notice completes immediately only when the local Kever has reached
+ * its sequence. Otherwise a LogQuerier waits for that accepted sequence. The
+ * first usable matching notice fixes this operation's target; later notices stay
+ * queued rather than introducing moving-target task replacement.
+ * The subject needs a local Kever before a notice can drive this comparison;
+ * initial evidence discovery belongs to OOBI/bootstrap composition.
+ *
+ * keyStateSaved denotes a validated, persisted remote notice. Ordinary KEL
+ * acceptance alone cannot satisfy the initial notice wait. Queued notices are
+ * not correlated to a particular request or filtered for request-time freshness.
+ */
+export class KeyStateNoticer {
+    /**
+     * Bind borrowed collaborators without starting I/O or consuming cues yet.
+     *
+     * @param db Baser receiving accepted KEL updates from the independently running intake.
+     * @param inquisitor Query sender over that same state; its delivery worker must run concurrently.
+     * @param pre Subject AID, distinct from the local signer and selected attester.
+     * @param cues Command-owned input Deck; this noticer is its sole consumer. The
+     * application cue owner must be wired to transfer saved notices here before I/O.
+     * @param options Local signer and optional remote attesters, never transport preferences.
+     */
+    constructor(db, inquisitor, pre, cues, options = {}) {
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: db
+        });
+        Object.defineProperty(this, "inquisitor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: inquisitor
+        });
+        Object.defineProperty(this, "pre", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: pre
+        });
+        Object.defineProperty(this, "cues", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: cues
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.options = copyOptions(options);
+    }
+    /**
+     * Enqueue `ksn`, then pull/match/append one cue per cooperative turn, following
+     * KERIpy's noticer model. Unrelated cues and matching notices without local
+     * state remain queued. No queue scan, broadcast or request freshness is implied.
+     * Once a usable notice selects a target, directly await accepted catch-up.
+     * The caller supervises sibling sender/receiver failures and owns cancellation;
+     * stopping this operation does not withdraw already enqueued requests.
+     */
+    *queryDo() {
+        const { db, inquisitor, pre, cues, options } = this;
+        inquisitor.enqueue({ pre, route: "ksn", q: { fn: "0", s: "0" }, ...options });
+        while (true) {
+            const cue = cues.pull();
+            if (cue) {
+                const local = db.getKever(pre);
+                if (cue.kin !== "keyStateSaved" || cue.ksn.i !== pre || !local) {
+                    cues.append(cue);
+                }
+                else {
+                    const ordinal = cue.ksn.s;
+                    const targetSn = typeof ordinal === "string" && ordinal.length ? parseInt(ordinal, 16) : NaN;
+                    if (!Number.isNaN(targetSn)) {
+                        if (local.sn < targetSn)
+                            yield* new LogQuerier(db, inquisitor, pre, targetSn, options).queryDo();
+                        return;
+                    }
+                }
+            }
+            yield* runtimeTurn();
+        }
+    }
+}
+/**
+ * Recover a KEL through the target sequence learned from a remote key-state notice.
+ * Like KERIpy LogQuerier, request logs from the beginning (`fn=0`, `s=0`) and
+ * finish when the local Kever reaches the target. This is a minimum sequence
+ * condition, not a promise that the remote peer has no newer events.
+ */
+export class LogQuerier {
+    /**
+     * @param db Borrowed accepted-state store, kept open for the operation's lifetime.
+     * @param inquisitor Concurrently running sender; this workflow does not drive it.
+     * @param pre Subject whose KEL should catch up.
+     * @param targetSn Minimum accepted sequence, as a number rather than wire hex text.
+     * @param options Local signing AID and optional remote attester overrides.
+     */
+    constructor(db, inquisitor, pre, targetSn, options = {}) {
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: db
+        });
+        Object.defineProperty(this, "inquisitor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: inquisitor
+        });
+        Object.defineProperty(this, "pre", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: pre
+        });
+        Object.defineProperty(this, "targetSn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: targetSn
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.options = copyOptions(options);
+    }
+    /** Send the initial request once and remain active until accepted state reaches the target. */
+    *queryDo() {
+        this.inquisitor.enqueue({ pre: this.pre, route: "logs", q: { fn: "0", s: "0" }, ...this.options });
+        yield* awaitSequence(this.db, this.pre, this.targetSn);
+    }
+}
+/**
+ * Request logs starting at selected KEL and first-seen ordinals.
+ *
+ * `s` selects the event sequence and `fn` selects first-seen replay position;
+ * they are different coordinates. As in KERIpy SeqNoQuerier, completion depends
+ * on accepted KEL sequence reaching targetSn, not on a first-seen cursor or a
+ * transport outcome. Even an already satisfied target still enqueues the request.
+ */
+export class SeqNoQuerier {
+    /**
+     * @param db Borrowed accepted-state store updated by independent protocol intake.
+     * @param inquisitor Concurrent sender borrowing the same accepted state.
+     * @param pre Subject AID whose KEL is requested.
+     * @param targetSn Numeric sequence used both in the query and the completion predicate.
+     * @param options Numeric first-seen start (default zero), local signer and remote attesters.
+     * Wire ordinals use lowercase hex; the existing encoder clamps negatives to zero.
+     */
+    constructor(db, inquisitor, pre, targetSn, { fn = 0, ...options } = {}) {
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: db
+        });
+        Object.defineProperty(this, "inquisitor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: inquisitor
+        });
+        Object.defineProperty(this, "pre", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: pre
+        });
+        Object.defineProperty(this, "targetSn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: targetSn
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.fn = fn;
+        this.options = copyOptions(options);
+    }
+    /** Complete only from an accepted KEL at or beyond the requested sequence. */
+    *queryDo() {
+        this.inquisitor.enqueue({
+            pre: this.pre,
+            route: "logs",
+            q: { fn: hexOrdinal(this.fn), s: hexOrdinal(this.targetSn) },
+            ...this.options,
+        });
+        yield* awaitSequence(this.db, this.pre, this.targetSn);
+    }
+}
+/**
+ * Find an accepted KEL event containing the exact supplied event seal.
+ *
+ * `pre` identifies the sealing KEL; anchor.i/s/d identify the event sealed in it.
+ * Mere knowledge of the subject's latest sequence does not satisfy this wait.
+ * Existing accepted sealing evidence completes without sending. Otherwise one
+ * request is enqueued per current eligible attester, preserving the bounded
+ * candidate pass needed when a retired witness never learned the anchor. This
+ * differs deliberately from KERIpy's single randomly selected attester.
+ */
+export class AnchorQuerier {
+    /**
+     * @param db Borrowed store containing accepted sealing events and their indexes.
+     * @param inquisitor Concurrent sender; candidates are selected when queryDo starts.
+     * @param pre AID whose KEL must contain the seal.
+     * @param anchor Exact event-seal fields, copied so later caller mutation cannot change the query.
+     * @param options Local signing AID and optional remote attesters.
+     */
+    constructor(db, inquisitor, pre, anchor, options = {}) {
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: db
+        });
+        Object.defineProperty(this, "inquisitor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: inquisitor
+        });
+        Object.defineProperty(this, "pre", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: pre
+        });
+        Object.defineProperty(this, "anchor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.anchor = { i: anchor.i, s: anchor.s, d: anchor.d };
+        this.options = copyOptions(options);
+    }
+    /**
+     * Ask the finite candidate set once, then observe accepted sealing evidence.
+     * No available candidate leaves unresolved work with the sender; it is not
+     * success. The caller supplies a deadline or cancels this otherwise open wait.
+     */
+    *queryDo() {
+        if (this.db.fetchLastSealingEventByEventSeal(this.pre, this.anchor))
+            return;
+        // Deliberate difference from KERIpy's single random choice: a retired witness
+        // may never learn the seal. Preserve the tested, finite current-candidate pass.
+        const attesters = this.inquisitor.attestersFor(this.pre, this.options);
+        for (const src of attesters.length ? attesters : [undefined]) {
+            this.inquisitor.enqueue({
+                pre: this.pre,
+                route: "logs",
+                q: { fn: "0", s: "0", a: { ...this.anchor } },
+                src,
+                ...this.options,
+            });
+        }
+        while (!this.db.fetchLastSealingEventByEventSeal(this.pre, this.anchor))
+            yield* runtimeTurn();
+    }
+}