keri-ts 2.2.4 → 2.2.6

package/esm/keri/npm/src/core/errors.js

@@ -32,6 +32,34 @@ export class ValidationError extends AppError {
         });
     }
 }
+/**
+ * A caller asked to treat a KRAM refusal as a failure. Carries the refused message SAID and the refusal decision;
+ * the message names the reason and, when the refusal has one, the last instant the message was acceptable.
+ */
+export class KramRefusedError extends ValidationError {
+    constructor(said, refusal) {
+        super(`KRAM refused message ${said}: ${refusal.reason}`
+            + (refusal.deadline ? ` (acceptable until ${refusal.deadline})` : ""));
+        Object.defineProperty(this, "said", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: said
+        });
+        Object.defineProperty(this, "refusal", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: refusal
+        });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "KramRefusedError"
+        });
+    }
+}
 /** Filesystem or path-resolution failure from path-managed resources. */
 export class PathError extends AppError {
     constructor() {
@@ -120,3 +148,48 @@ export class DatabaseOperationError extends DatabaseError {
         });
     }
 }
+/**
+ * Local durable state that the store's own records say must exist is missing or contradicts itself: a local group
+ * names a member habitat the store does not hold, for example. Never a remote outcome: no peer message removes a
+ * local record, so a long-running loop does not survive it and lets it end the runtime. Recovery is repairing or
+ * replacing the store, not retrying.
+ */
+export class MissingDurableStateError extends DatabaseError {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "MissingDurableStateError"
+        });
+    }
+}
+/**
+ * A browser composition's persistence queue gave up on a write after its retries (ADR-0015 rule 3), so it accepts
+ * no more commits and reports this from every later commit, flush and close. The cause is the write's first failure.
+ * The latch is terminal for that composition; recovery is closing it and opening a new one.
+ */
+export class PersistenceLatchedError extends DatabaseOperationError {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "PersistenceLatchedError"
+        });
+    }
+}
+/** A task passed to `PersistenceQueue.read` failed. Only its caller sees it; the queue does not latch. */
+export class PersistenceReadError extends DatabaseOperationError {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "PersistenceReadError"
+        });
+    }
+}

package/esm/keri/npm/src/core/kel/delegation-ancestry.js

@@ -1,8 +1,17 @@
 import { dgKey } from "../../db/core/keys.js";
 import { ValidationError } from "../errors.js";
-/** Whether one accepted delegator event carries the exact `{i,s,d}` seal of a delegated inception. */
+import { readEventSeal } from "../wire-fields.js";
+/**
+ * Whether one accepted delegator event carries the exact `{i,s,d}` seal of a delegated inception.
+ *
+ * The delegator's seals are remote-authored and unchecked at acceptance; other shapes and undecodable values are
+ * skipped (`readEventSeal`), never thrown.
+ */
 function approves(event, dip) {
-    return event.eventSeals.some((seal) => seal.i.qb64 === dip.pre && seal.s.numh === dip.snh && seal.d.qb64 === dip.said);
+    return event.seals.some((raw) => {
+        const seal = readEventSeal(raw);
+        return seal !== null && seal.i.qb64 === dip.pre && seal.s.numh === dip.snh && seal.d.qb64 === dip.said;
+    });
 }
 /**
  * Find the delegator's accepted approval of `dip`.

package/esm/keri/npm/src/core/kel/eventing.js

@@ -8,6 +8,7 @@ import { normalizeMbxTopicCursor } from "../mailbox/mailbox-topics.js";
 import { reply as replyEvent } from "../protocol-eventing.js";
 import { KeyStateRecord, ObservedRecord } from "../records.js";
 import { acceptReplyDecision, unverifiedReplyDecision } from "../routing.js";
+import { kelEventFieldDefect, readDater, readDiger, readOrdinal, readPrefixer, readSequenceNumber, } from "../wire-fields.js";
 import { acceptEscrow, acceptQuery, acceptReceipt, dropEscrow, dropQuery, dropReceipt, escrowQuery, escrowReceipt, ignoreReceipt, keepEscrow, logEscrowDecision, } from "./kever-decisions.js";
 import { Kever } from "./kever.js";
 import { deriveRotatedWitnessSet, hasUniqueWitnesses } from "./witnesses.js";
@@ -365,14 +366,15 @@ export class Kevery {
     processReceipt(envelope) {
         const serder = envelope.serder;
         const pre = serder.pre;
-        const sn = serder.sn;
+        // Decided before any escrow: a remote receipt's sn and prefix are read through the guarded readers.
+        const sn = readSequenceNumber(serder);
         const said = serder.said;
         const local = envelope.local ?? this.local;
-        if (!pre || sn === null || !said) {
+        if (!pre || !readPrefixer(pre) || sn === null || !said) {
             this.cues.push({
                 kin: "invalid",
                 serder,
-                reason: "Receipt message is missing receipted pre, sn, or said.",
+                reason: "Receipt message is missing a valid receipted pre, hex sn, or said.",
             });
             return;
         }
@@ -611,23 +613,22 @@ export class Kevery {
         const pre = serder.pre;
         const ilk = serder.ilk;
         const said = serder.said;
-        const sn = serder.sn;
+        // Every remote field value is decided here, before any escrow or store write: escrow replay re-enters through
+        // this method, so a row stored with a malformed value is rejected and removed instead of failing every pass.
+        const sn = readSequenceNumber(serder);
         if (!pre || !ilk || !said || sn === null) {
             return {
                 kind: "reject",
                 code: !pre ? "invalidPre" : !ilk ? "invalidIlk" : "invalidSn",
-                message: "KEL event must include pre, ilk, said, and sn.",
+                message: `KEL event must include pre, ilk, said, and a hex sn of at most ${Number.MAX_SAFE_INTEGER}.`,
             };
         }
-        try {
-            new Prefixer({ qb64: pre });
+        if (!readPrefixer(pre)) {
+            return { kind: "reject", code: "invalidPre", message: `Invalid pre=${pre} for event ${said}.` };
         }
-        catch (error) {
-            return {
-                kind: "reject",
-                code: "invalidPre",
-                message: `Invalid pre=${pre} for event ${said}: ${error instanceof Error ? error.message : String(error)}`,
-            };
+        const defect = kelEventFieldDefect(serder);
+        if (defect) {
+            return { kind: "reject", code: "malformedField", message: `Malformed ${defect} in event ${said} for ${pre}.` };
         }
         const local = envelope.local ?? this.local;
         const init = this.makeKeverEventInit(envelope, local);
@@ -939,16 +940,18 @@ export class Kevery {
             throw new ValidationError(`Unsupported route=${args.route} in ${Ilks.rpy} reply.`);
         }
         const ksn = KeyStateRecord.fromDict(args.serder.ked?.a);
-        const pre = typeof ksn.i === "string" ? ksn.i : null;
-        const sn = typeof ksn.s === "string" ? parseInt(ksn.s, 16) : null;
-        const said = typeof ksn.d === "string" ? ksn.d : null;
-        const dt = typeof ksn.dt === "string" ? ksn.dt : null;
-        if (!pre || sn === null || Number.isNaN(sn) || !said || !dt) {
+        // Decide the notice's field values before decideReply can escrow it.
+        const pre = readPrefixer(ksn.i)?.qb64 ?? null;
+        const sn = typeof ksn.s === "string" ? readOrdinal(ksn.s) : null;
+        const saider = readDiger(ksn.d);
+        const dater = readDater(ksn.dt);
+        if (!pre || sn === null || !saider || !dater) {
             throw new ValidationError("Malformed key state notice reply body.");
         }
+        const said = saider.qb64;
         if (!this.lax) {
             const watchers = this.configuredWatchers();
-            const backers = ksn.b ?? [];
+            const backers = Array.isArray(ksn.b) ? ksn.b : [];
             // In non-lax mode, only the controller, a reported KSN backer, or a
             // locally configured watcher may advance saved key state.
             const trusted = args.aid === pre
@@ -986,8 +989,6 @@ export class Kevery {
         if (ldig && ldig !== said) {
             throw new ValidationError(`Mismatch key state at sn=${sn} with accepted event log for ${pre}.`);
         }
-        const saider = new Diger({ qb64: said });
-        const dater = new Dater({ qb64: encodeDateTimeToDater(dt) });
         const cues = [{ kin: "keyStateSaved", ksn }];
         this.rvy.writeReply(reply);
         this.updateKeyState(args.aid, ksn, saider, dater);
@@ -1025,15 +1026,11 @@ export class Kevery {
             throw new ValidationError(`Unsupported route=${args.route} in ${Ilks.rpy} reply.`);
         }
         const data = args.serder.ked?.a;
-        const cid = typeof data?.cid === "string"
-            ? new Prefixer({ qb64: data.cid }).qb64
-            : null;
-        const oid = typeof data?.oid === "string"
-            ? new Prefixer({ qb64: data.oid }).qb64
-            : null;
+        const cid = readPrefixer(data?.cid)?.qb64 ?? null;
+        const oid = readPrefixer(data?.oid)?.qb64 ?? null;
         const oobi = typeof data?.oobi === "string" ? data.oobi : null;
         if (!cid || !oid) {
-            throw new ValidationError("Missing one of cid/oid in /watcher reply.");
+            throw new ValidationError("Missing or malformed one of cid/oid in /watcher reply.");
         }
         const keys = [cid, args.aid, oid];
         let osaider = this.db.wwas.get(keys);

package/esm/keri/npm/src/core/kel/kever.js

@@ -1,8 +1,9 @@
-import { Dater, Diger, Ilks, NumberPrimitive, Prefixer, SealSource, Siger, Tholder, Verfer, } from "cesr-ts";
+import { Dater, Diger, Ilks, NumberPrimitive, Prefixer, SealEvent, SealSource, Siger, Tholder, Verfer, } from "cesr-ts";
 import { dgKey } from "../../db/core/keys.js";
 import { encodeDateTimeToDater, makeNowIso8601 } from "../../time/mod.js";
 import { ValidationError } from "../errors.js";
 import { KeyStateRecord } from "../records.js";
+import { readEventSeal } from "../wire-fields.js";
 import { deriveRotatedWitnessSet } from "./witnesses.js";
 /**
  * Convert one integer into the Huge-number CESR family used for durable replay
@@ -1434,16 +1435,21 @@ export class Kever {
         }
         return this.db.getState(pre)?.di || null;
     }
-    /** Return the zero-based index of the matching event seal or `-1`. */
+    /**
+     * Return the zero-based index of the matching event seal among the candidate's event-shaped seals, or `-1`.
+     *
+     * The candidate is an accepted delegator event, which is remote-authored: its `a` may hold any seal shape and
+     * undecodable values. Like KERIpy, the index counts entries with the `{i, s, d}` field shape; other shapes and
+     * malformed values never match (`readEventSeal`).
+     */
     eventAnchorSealIndex(candidate, serder) {
-        for (const [index, seal] of candidate.eventSeals.entries()) {
-            if (seal.i.qb64 === serder.pre
+        return candidate.seals.filter((raw) => SealEvent.isSad(raw)).findIndex((raw) => {
+            const seal = readEventSeal(raw);
+            return seal !== null
+                && seal.i.qb64 === serder.pre
                 && seal.s.numh === serder.snh
-                && seal.d.qb64 === serder.said) {
-                return index;
-            }
-        }
-        return -1;
+                && seal.d.qb64 === serder.said;
+        });
     }
     /**
      * Verify one indexed-signature set against a given verifier list.

package/esm/keri/npm/src/core/mailbox/kram-policy.js

@@ -29,6 +29,22 @@ function storedCacheType(db, ilk, route) {
 export function singleKeyQueryWindow(db, route) {
     return storedCacheType(db, "qry", route)?.sl ?? null;
 }
+/**
+ * How long a multi-key (group threshold) query on `route` stays timely under the windows this store was configured
+ * with, in milliseconds: the multi-key lag. A group sender uses its own windows as the estimate of its peer's, as
+ * {@link singleKeyQueryWindow} does. Null when this store has no KRAM cache types (KRAM never ran on it).
+ */
+export function multiKeyQueryWindow(db, route) {
+    return storedCacheType(db, "qry", route)?.ll ?? null;
+}
+/**
+ * How long an exchange of a message of `ilk` on `route` stays open after its opener under the windows this store
+ * is configured with now, in milliseconds: the exchange lag `xl`. Null when this store has no KRAM cache types
+ * (KRAM never ran on it).
+ */
+export function exchangeWindow(db, ilk, route) {
+    return storedCacheType(db, ilk, route)?.xl ?? null;
+}
 /** Validate caller configuration before any durable policy mutation. */
 function windows(value, transitional = false) {
     if (!Array.isArray(value) || value.length !== 7 || value.some((v) => !Number.isSafeInteger(v) || v < 0)) {

package/esm/keri/npm/src/core/mailbox/kram-pruning.js

@@ -2,11 +2,12 @@
 import { b } from "cesr-ts";
 import { removeKramFactors } from "../../db/mailbox/kram-factors.js";
 import { timestampMicros } from "../../time/mod.js";
+import { consoleLogger } from "../logger.js";
 import { TxnMsgCacheRecord } from "../records.js";
 import { kramCacheValues } from "./kram-time.js";
 /** Prune stored windows, then prove orphan XIDs with restartable finite existence scans. */
 export class KramPruner {
-    constructor(db, policy) {
+    constructor(db, policy, logger = consoleLogger) {
         Object.defineProperty(this, "db", {
             enumerable: true,
             configurable: true,
@@ -19,6 +20,12 @@ export class KramPruner {
             writable: true,
             value: policy
         });
+        Object.defineProperty(this, "logger", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: logger
+        });
         Object.defineProperty(this, "bound", {
             enumerable: true,
             configurable: true,
@@ -95,7 +102,14 @@ export class KramPruner {
             throw new Error("Invalid KRAM pruning receiver clock");
         if (!Number.isSafeInteger(maxRows) || maxRows < 1)
             throw new RangeError("Invalid KRAM pruning batch");
-        const result = { kind: "pruned", visited: 0, removed: 0, openers: 0, passComplete: false };
+        const result = {
+            kind: "pruned",
+            visited: 0,
+            removed: 0,
+            openers: 0,
+            partials: 0,
+            passComplete: false,
+        };
         if (!this.db.opened)
             throw new Error("KRAM pruning database is closed");
         if (this.bound !== this.db.msgc.sdb) {
@@ -114,15 +128,20 @@ export class KramPruner {
                     continue;
                 }
                 const keys = this.keys(physical, this.phase + 2), table = this.phase ? this.db.tmsc : this.db.msgc;
-                this.db.transaction(() => {
+                const partial = this.db.transaction(() => {
                     const record = table.get(keys);
                     if (!record || !this.expired(record, when))
-                        return;
+                        return null;
                     table.rem(keys);
-                    const partial = [keys[0], keys.at(-1)];
-                    removeKramFactors(this.db, partial);
+                    const owner = [keys[0], keys.at(-1)], incomplete = this.db.pmkm.get(owner) !== null;
+                    removeKramFactors(this.db, owner);
                     result.removed++;
+                    return incomplete ? owner : null;
                 });
+                if (partial) {
+                    result.partials++;
+                    this.logger.warn("KRAM expired incomplete multi-signature message", { sender: partial[0], said: partial[1] });
+                }
                 scan.start = this.after(physical);
                 result.visited++;
                 continue;

package/esm/keri/npm/src/core/mailbox/kram-time.js

@@ -1,5 +1,16 @@
-import { timestampMicros } from "../../time/mod.js";
+import { timestampFromMicros, timestampMicros } from "../../time/mod.js";
 import { MsgCacheRecord, TxnMsgCacheRecord } from "../records.js";
+import { readDater, readDiger } from "../wire-fields.js";
+/**
+ * Whether a drop reason means an authenticated message arrived too late or outside a live exchange.
+ *
+ * `timestamp`, `exchangeId`, `replay` and `authentication` are reachable by anyone who can post bytes (see
+ * kram-staging.ts), so callers that report or signal a refusal to anyone beyond the log must restrict themselves to
+ * these.
+ */
+export function isKramLateReason(reason) {
+    return reason === "timeliness" || reason === "lifetime" || reason === "unknownThread";
+}
 /** Validate durable cache values without turning corruption into remote refusal. */
 export function kramCacheValues(cache) {
     const { mdt, d, ml, pml, xl, pxl } = cache;
@@ -10,9 +21,19 @@ export function kramCacheValues(cache) {
         throw new Error("Corrupt KRAM timeliness cache");
     return { mdt: mdt, d: d, ml: ml, pml: pml, xl: xl, pxl: pxl };
 }
+/** Exchange id KRAM threads a message by: the `xip` SAID or the v2 `exn` `x` field; empty when it has none. */
+export function kramExchangeId(body) {
+    const said = body.said;
+    return body.ilk === "xip" ? said ?? "" : body.ilk === "exn" && body.pvrsn.major >= 2 ? String(body.ked?.x ?? "") : "";
+}
 /**
  * Inspect frozen message/xid routing and strict completed-message replay rules.
  * Only an incomplete multi-signature message retains partial state.
+ *
+ * The stamp and exchange id are remote-authored and become durable values: an exchange message's stamp can be stored
+ * as its thread opener (a Dater, which needs the fixed-width form), and the exchange id is a cache key part (a value
+ * that is not one qualified digest, such as one containing `.`, would make a key the pruner cannot split). Both are
+ * refused here, before any store write.
  */
 export function inspectKramReplay(db, body) {
     const mdt = timestampMicros(body.stamp);
@@ -22,7 +43,11 @@ export function inspectKramReplay(db, body) {
     if (!sender || !said)
         throw new Error("KRAM replay inspection requires sender and message SAID");
     const key = [sender, said];
-    const xid = body.ilk === "xip" ? said : body.ilk === "exn" && body.pvrsn.major >= 2 ? String(body.ked?.x ?? "") : "";
+    const xid = kramExchangeId(body);
+    if (xid && readDiger(xid)?.qb64 !== xid)
+        return { kind: "drop", reason: "exchangeId" };
+    if (xid && !readDater(body.stamp))
+        return { kind: "drop", reason: "timestamp" };
     const cacheKey = xid ? [sender, xid, said] : key;
     const cache = xid ? db.tmsc.get(cacheKey) : db.msgc.get(cacheKey);
     const partial = db.pmkm.get(key) !== null;
@@ -54,8 +79,9 @@ export function evaluateKramTime(db, policy, inspection, authentication, receive
     else {
         const type = policy.cacheType(body.ilk, body.route), multi = authentication.kind === "multi";
         const ml = multi ? type.ll : type.sl, pml = multi ? type.pll : type.psl;
-        if (!within(mdt, receipt - (BigInt(type.d) + BigInt(ml)) * 1000n, receipt + BigInt(type.d) * 1000n)) {
-            return { kind: "drop", reason: "timeliness" };
+        const reach = (BigInt(type.d) + BigInt(ml)) * 1000n;
+        if (!within(mdt, receipt - reach, receipt + BigInt(type.d) * 1000n)) {
+            return { kind: "drop", reason: "timeliness", deadline: timestampFromMicros(mdt + reach) };
         }
         values = { mdt: body.stamp, d: type.d, ml, pml, xl: type.xl, pxl: type.pxl };
     }
@@ -79,8 +105,10 @@ export function evaluateKramTime(db, policy, inspection, authentication, receive
     const opener = timestampMicros(xdt);
     if (opener === null)
         throw new Error("Corrupt KRAM transaction opener");
-    if (!cache && !within(mdt, opener, opener + BigInt(values.xl) * 1000n))
-        return { kind: "drop", reason: "lifetime" };
+    const closing = opener + BigInt(values.xl) * 1000n;
+    if (!cache && !within(mdt, opener, closing)) {
+        return { kind: "drop", reason: "lifetime", deadline: timestampFromMicros(closing) };
+    }
     const complete = authentication.kind !== "multi" || authentication.complete;
     const rdt = cache instanceof TxnMsgCacheRecord && cache.rdt ? cache.rdt : complete ? receiverTime : "";
     return {

package/esm/keri/npm/src/core/mailbox/kraming.js

@@ -1,19 +1,27 @@
 import { makeNowIso8601, timestampMicros } from "../../time/mod.js";
 import { Deck } from "../deck.js";
+import { consoleLogger } from "../logger.js";
 import { KramPolicy } from "./kram-policy.js";
 import { KramPruner } from "./kram-pruning.js";
 import { stageKram } from "./kram-staging.js";
+import { isKramLateReason, kramExchangeId } from "./kram-time.js";
 /** Explicit receiver-owned cache and exemption configuration. */
 export { DEFAULT_KRAM_CACHES } from "./kram-policy.js";
 /** Optional receiver intake returns ordinary decisions without owning parser input. */
 export class Kramer {
-    constructor(db, { config = {}, cues = new Deck(), now = Date.now } = {}) {
+    constructor(db, { config = {}, cues = new Deck(), now = Date.now } = {}, logger = consoleLogger) {
         Object.defineProperty(this, "db", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: db
         });
+        Object.defineProperty(this, "logger", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: logger
+        });
         /** Shared runtime cues, or the standalone caller's drainable receiver-state notifications. */
         Object.defineProperty(this, "cues", {
             enumerable: true,
@@ -42,7 +50,7 @@ export class Kramer {
         this.now = now;
         this.policy = new KramPolicy(db, config, now);
         this.cues = cues;
-        this.pruner = new KramPruner(db, this.policy);
+        this.pruner = new KramPruner(db, this.policy, logger);
     }
     /** Decide intake synchronously; protocol dispatch consumes the returned evidence. */
     intake(envelope) {
@@ -64,8 +72,56 @@ export class Kramer {
                 q: result.sn === null ? {} : { s: result.sn.toString(16) },
             });
         }
+        if (result.kind === "drop") {
+            this.report(envelope, result);
+            const cue = this.refusedCue(envelope, result);
+            if (cue)
+                this.cues.push(cue);
+        }
         return result;
     }
+    /**
+     * Describe a refusal the application may want to hear about, or null. Staging has already committed. A local
+     * caller receives its own refusal, and only the reasons KRAM decides after authentication are safe to signal:
+     * `timestamp`, `replay` and `authentication` are reachable by anyone who can post bytes.
+     */
+    refusedCue(envelope, refusal) {
+        if (envelope.local || !isKramLateReason(refusal.reason))
+            return null;
+        const { serder } = envelope;
+        const xid = kramExchangeId(serder), deadline = "deadline" in refusal ? refusal.deadline : undefined;
+        return {
+            kin: "kramRefused",
+            said: serder.said,
+            sender: serder.pre,
+            ilk: serder.ilk,
+            route: serder.route,
+            reason: refusal.reason,
+            stamp: serder.stamp,
+            ...(deadline === undefined ? {} : { deadline }),
+            ...(xid ? { xid } : {}),
+        };
+    }
+    /**
+     * Report one refused message. Replay is routine (every duplicate delivery lands here), so it logs at debug;
+     * the other reasons mean a sender or clock is misbehaving and log at warn. Dispatch does not log again.
+     */
+    report(envelope, refusal) {
+        const { serder } = envelope;
+        const fields = {
+            said: serder.said,
+            sender: serder.pre,
+            ilk: serder.ilk,
+            route: serder.route,
+            reason: refusal.reason,
+            stamp: serder.stamp,
+            deadline: "deadline" in refusal ? refusal.deadline : undefined,
+        };
+        if (refusal.reason === "replay")
+            this.logger.debug("KRAM refused message", fields);
+        else
+            this.logger.warn("KRAM refused message", fields);
+    }
     /** Reconfigure cache windows through the durable policy transition facility. */
     changeConfig(caches, delay) {
         this.policy.change(caches, delay);

package/esm/keri/npm/src/core/missing-anchor-query.js

@@ -0,0 +1,20 @@
+/**
+ * Name the issuer KEL events still missing for a pending event, or null when more KEL cannot supply the anchor.
+ *
+ * @param pre Issuer whose KEL holds the anchoring seal.
+ * @param accepted Sequence number of the issuer's accepted KEL here, or null when the issuer is unknown.
+ * @param anchor Sequence number of the anchoring event when a source seal names it, otherwise null.
+ * @returns The query, or null when the accepted KEL already reaches a known anchor sequence number: the anchor was
+ *   found wanting rather than missing, and replay cannot change that.
+ */
+export function missingAnchorQuery(pre, accepted, anchor) {
+    if (accepted !== null && anchor !== null && accepted >= anchor)
+        return null;
+    const fn = (accepted === null ? 0n : accepted + 1n).toString(16);
+    return anchor === null ? { pre, fn } : { pre, fn, s: anchor.toString(16) };
+}
+/** The routed query cue that asks for `query`; the existing query path sends it. */
+export function missingAnchorCue(query) {
+    const { pre, fn, s } = query;
+    return { kin: "query", pre, route: "logs", q: s === undefined ? { fn } : { fn, s } };
+}

package/esm/keri/npm/src/core/routing.js

@@ -1,11 +1,12 @@
-import { Dater, Diger, NumberPrimitive, Prefixer, Siger } from "cesr-ts";
-import { encodeDateTimeToDater, timestampMicros } from "../time/mod.js";
+import { Diger, NumberPrimitive, Prefixer, Siger } from "cesr-ts";
+import { timestampMicros } from "../time/mod.js";
 import { Deck } from "./deck.js";
 import { TransIdxSigGroup } from "./dispatch.js";
 import { ValidationError } from "./errors.js";
 import { acceptEscrow, dropEscrow, keepEscrow, logEscrowDecision, } from "./kel/kever-decisions.js";
 import { EndpointRecord, LocationRecord } from "./records.js";
 import { isRole } from "./roles.js";
+import { readDater, readPrefixer, readUrl } from "./wire-fields.js";
 /** Builder for one accepted live reply decision. */
 export function acceptReplyDecision() {
     return { kind: "accept" };
@@ -276,6 +277,7 @@ Object.defineProperty(Router, "defaultResourceFunc", {
  * - persist accepted reply artifacts into `sdts.`, `rpys.`, `scgs.`, `ssgs.`
  * - escrow partially verifiable transferable replies into `rpes.`
  * - emit `query` cues when missing signer state blocks verification
+ * - emit an `endRoleSaved` cue after an accepted `/end/role` reply commits (TypeScript-only; KERIpy has no consumer)
  *
  * Current `keri-ts` differences:
  * - only the Gate E bootstrap reply families are currently routed
@@ -321,17 +323,6 @@ export class Revery {
             writable: true,
             value: void 0
         });
-        /**
-         * Told after an `/end/role` reply is accepted, with the controller, role, endpoint and whether the role is
-         * allowed. The runtime uses it to have the mailbox poller and KEL publisher look at a controller whose mailbox
-         * role just changed, rather than at their next sweep.
-         */
-        Object.defineProperty(this, "onEndRole", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         this.db = db;
         this.rtr = rtr ?? new Router();
         this.cues = cues ?? new Deck();
@@ -404,11 +395,10 @@ export class Revery {
         // Same-call groups see the last staged pin exactly as they previously saw the durable write.
         const staged = new Map();
         const groupKey = (pre, snh, said) => `${pre}.${snh}.${said}`;
-        const daterText = args.serder.ked?.dt;
-        if (typeof daterText !== "string") {
-            throw new ValidationError("Reply message is missing 'dt'.");
+        const dater = readDater(args.serder.ked?.dt);
+        if (!dater) {
+            throw new ValidationError("Reply message is missing a valid 'dt'.");
         }
-        const dater = new Dater({ qb64: encodeDateTimeToDater(daterText) });
         const odater = args.osaider ? this.db.sdts.get([args.osaider.qb64]) : null;
         let pending = false;
         const escrow = (material) => {
@@ -802,7 +792,8 @@ export class BasicReplyRouteHandler {
      * - derives the BADA route base `/end/role`
      * - applies same-SAID idempotence before acceptance
      * - evaluates proof and updates proof/`eans.`/`ends.` in its own transaction
-     * - publishes queries only after that commit; caller-owned writers are refused
+     * - publishes queries, then an `endRoleSaved` cue for an accepted reply, only after that commit; caller-owned
+     *   writers are refused
      */
     processReplyEndRole(args) {
         const allowed = args.route.startsWith("/end/role/add")
@@ -817,11 +808,11 @@ export class BasicReplyRouteHandler {
         if (!data || typeof data !== "object" || Array.isArray(data)) {
             throw new ValidationError("Missing one of cid/role/eid in /end/role reply.");
         }
-        const cid = "cid" in data && typeof data.cid === "string" ? new Prefixer({ qb64: data.cid }).qb64 : null;
+        const cid = "cid" in data ? readPrefixer(data.cid)?.qb64 ?? null : null;
         const role = "role" in data && typeof data.role === "string" ? data.role : null;
-        const eid = "eid" in data && typeof data.eid === "string" ? new Prefixer({ qb64: data.eid }).qb64 : null;
+        const eid = "eid" in data ? readPrefixer(data.eid)?.qb64 ?? null : null;
         if (!cid || !role || !eid) {
-            throw new ValidationError("Missing one of cid/role/eid in /end/role reply.");
+            throw new ValidationError("Missing or malformed one of cid/role/eid in /end/role reply.");
         }
         if (!isRole(role)) {
             throw new ValidationError(`Invalid endpoint role ${role}.`);
@@ -855,7 +846,7 @@ export class BasicReplyRouteHandler {
         if (queryCues.length)
             this.rvy.cues.extend(queryCues);
         if (decision.kind === "accept")
-            this.rvy.onEndRole?.(cid, role, eid, allowed);
+            this.rvy.cues.push({ kin: "endRoleSaved", cid, role, eid, allowed });
         return decision;
     }
     /**
@@ -877,14 +868,16 @@ export class BasicReplyRouteHandler {
         if (!data || typeof data !== "object" || Array.isArray(data)) {
             throw new ValidationError("Missing one of eid/scheme/url in /loc/scheme reply.");
         }
-        const eid = "eid" in data && typeof data.eid === "string" ? new Prefixer({ qb64: data.eid }).qb64 : null;
+        const eid = "eid" in data ? readPrefixer(data.eid)?.qb64 ?? null : null;
         const scheme = "scheme" in data && typeof data.scheme === "string" ? data.scheme : null;
         const url = "url" in data && typeof data.url === "string" ? data.url : null;
         if (!eid || !scheme || url === null) {
-            throw new ValidationError("Missing one of eid/scheme/url in /loc/scheme reply.");
+            throw new ValidationError("Missing or malformed one of eid/scheme/url in /loc/scheme reply.");
         }
         if (url) {
-            const parsed = new URL(url);
+            const parsed = readUrl(url);
+            if (!parsed)
+                throw new ValidationError(`Unparseable URL ${url} in /loc/scheme reply.`);
             if (parsed.protocol && parsed.protocol.slice(0, -1) !== scheme) {
                 throw new ValidationError(`URL ${url} does not match declared scheme ${scheme}.`);
             }