keri-ts 0.6.0 → 0.7.0

package/esm/keri/src/app/forwarding.js

@@ -25,6 +25,7 @@ import { closeResponseBody, fetchResponseHandle, fetchResponseHandleOrNull } fro
 import { parseMailboxSse, readMailboxSseBody } from "./mailbox-sse.js";
 import { directDeliveryEndpoints, firstSortedEndpoint, getOutboxer, mailboxDeliveryEndpoints, mailboxPollEndpoints, mailboxTopicKey, } from "./mailboxing.js";
 import { Organizer } from "./organizing.js";
+import { defaultRuntimeServices } from "./runtime-services.js";
 import { runtimeTurn } from "./runtime-turn.js";
 /**
  * Mailbox-first postman for outbound EXN transport.
@@ -37,7 +38,7 @@ import { runtimeTurn } from "./runtime-turn.js";
  * - persist sender-side mailbox retry state per mailbox endpoint
  */
 export class Poster {
-    constructor(hby, { mailboxer, outboxer, } = {}) {
+    constructor(hby, options = {}) {
         Object.defineProperty(this, "hby", {
             enumerable: true,
             configurable: true,
@@ -62,10 +63,18 @@ export class Poster {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "services", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const { mailboxer, outboxer, services = defaultRuntimeServices } = options;
         this.hby = hby;
         this.mailboxer = mailboxer ?? null;
         this.outboxer = outboxer ?? getOutboxer(hby);
         this.organizer = new Organizer(hby);
+        this.services = services;
     }
     /**
      * Resolve one CLI or user recipient input into the actual destination prefix.
@@ -164,7 +173,7 @@ export class Poster {
         const directEndpoints = directDeliveryEndpoints(hab, recipient);
         if (directEndpoints.length > 0) {
             for (const endpoint of directEndpoints) {
-                yield* postCesrMessage(endpoint.url, message, this.hby.cesrBodyMode, endpoint.eid);
+                yield* postCesrMessage(endpoint.url, message, this.hby.cesrBodyMode, endpoint.eid, this.services);
                 deliveries.push(endpoint.url);
             }
             return { serder, deliveries, queued };
@@ -241,7 +250,7 @@ export class Poster {
         const directEndpoints = directDeliveryEndpoints(hab, recipient);
         if (directEndpoints.length > 0) {
             for (const endpoint of directEndpoints) {
-                yield* postCesrMessage(endpoint.url, args.message, this.hby.cesrBodyMode, endpoint.eid);
+                yield* postCesrMessage(endpoint.url, args.message, this.hby.cesrBodyMode, endpoint.eid, this.services);
                 deliveries.push(endpoint.url);
             }
             return { deliveries, queued };
@@ -329,7 +338,7 @@ export class Poster {
             topic,
             message,
         });
-        yield* postCesrMessage(endpoint.url, concatBytes(introduce(hab, endpoint.eid), forwarded), this.hby.cesrBodyMode, endpoint.eid);
+        yield* postCesrMessage(endpoint.url, concatBytes(introduce(hab, endpoint.eid), forwarded), this.hby.cesrBodyMode, endpoint.eid, this.services);
     }
     /** Require provider mailbox storage for local mailbox-target delivery. */
     requireMailboxer() {
@@ -418,6 +427,9 @@ Object.defineProperty(ForwardHandler, "resource", {
     value: "/fwd"
 });
 function hostCanStoreForwardRecipient(hby, recipient, recipientKever, hostAid) {
+    // A local host may store forwarded traffic only when it is an authorized
+    // witness/mailbox/agent for the recipient. This keeps mailbox storage from
+    // becoming a generic unauthenticated relay.
     if (recipientKever.wits.includes(hostAid)) {
         return true;
     }
@@ -430,6 +442,8 @@ function hostCanStoreForwardRecipient(hby, recipient, recipientKever, hostAid) {
     return false;
 }
 function hasLocalStoreForwardHost(hby, recipient, recipientKever) {
+    // Check all local prefixes because a multi-role runtime can host a mailbox
+    // AID that is distinct from the controller currently processing the EXN.
     for (const hostAid of hby.db.prefixes) {
         if (hostCanStoreForwardRecipient(hby, recipient, recipientKever, hostAid)) {
             return true;
@@ -446,7 +460,7 @@ function hasLocalStoreForwardHost(hby, recipient, recipientKever) {
  * - ingests retrieved payloads back through the shared `Reactor`
  */
 export class MailboxPoller {
-    constructor(hby, mailboxDirector, { timeouts, } = {}) {
+    constructor(hby, mailboxDirector, options = {}) {
         Object.defineProperty(this, "hby", {
             enumerable: true,
             configurable: true,
@@ -465,15 +479,30 @@ export class MailboxPoller {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "services", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pollTransport", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "localCursors", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: new Map()
         });
+        const { timeouts, services = defaultRuntimeServices, pollTransport = defaultMailboxPollTransport, } = options;
         this.hby = hby;
         this.mailboxDirector = mailboxDirector;
         this.timeoutPolicy = normalizeMailboxPollingTimeoutPolicy(timeouts);
+        this.services = services;
+        this.pollTransport = pollTransport;
     }
     /** Configure mailbox polling state for future expansion; currently a no-op. */
     configure(_args = {}) {
@@ -498,7 +527,7 @@ export class MailboxPoller {
             return [];
         }
         const batches = [];
-        const deadline = Date.now() + positiveTimeoutMs(budgetMs, this.timeoutPolicy.commandLocalBudgetMs);
+        const deadline = this.services.clock.now() + positiveTimeoutMs(budgetMs, this.timeoutPolicy.commandLocalBudgetMs);
         for (const pre of this.hby.prefixes) {
             const local = this.readLocalMailbox(pre, topics);
             if (local.length > 0) {
@@ -508,7 +537,7 @@ export class MailboxPoller {
         for (const hab of this.hby.habs.values()) {
             const remoteEndpoints = mailboxPollEndpoints(this.hby, hab);
             for (const endpoint of remoteEndpoints) {
-                const remainingBudgetMs = deadline - Date.now();
+                const remainingBudgetMs = deadline - this.services.clock.now();
                 if (remainingBudgetMs <= 0) {
                     return batches;
                 }
@@ -588,7 +617,14 @@ export class MailboxPoller {
      */
     *pollRemoteEndpointOnce(hab, endpoint, budgetMs) {
         const cursor = this.mailboxDirector.remoteQueryCursor(hab.pre, endpoint.eid);
-        const messages = yield* fetchMailboxMessages(hab, endpoint.eid, endpoint.url, cursor, this.hby.cesrBodyMode, mailboxFetchTimeoutPolicy(this.timeoutPolicy, budgetMs));
+        const messages = yield* this.pollTransport.poll({
+            hab,
+            endpoint,
+            topics: cursor,
+            bodyMode: this.hby.cesrBodyMode,
+            timeouts: mailboxFetchTimeoutPolicy(this.timeoutPolicy, budgetMs),
+            services: this.services,
+        });
         if (messages.length === 0) {
             return null;
         }
@@ -766,6 +802,8 @@ function extractForwardedMessage(serder, attachments) {
     if (!evt || typeof evt !== "object" || Array.isArray(evt)) {
         return null;
     }
+    // Rebuild the embedded event from SAD plus only the attachment material
+    // pathed to `/e/evt`; other pathed groups belong to the outer `/fwd` message.
     const embedded = new SerderKERI({ sad: evt });
     const messageParts = [embedded.raw];
     for (const attachment of attachments) {
@@ -794,15 +832,20 @@ function forwardedAttachmentForPath(raw, path) {
     }
     return raw.slice(offset + pather.fullSize);
 }
+const defaultMailboxPollTransport = {
+    *poll(args) {
+        return yield* fetchMailboxMessages(args.hab, args.endpoint.eid, args.endpoint.url, args.topics, args.bodyMode, args.timeouts, args.services);
+    },
+};
 /**
  * Query one remote mailbox endpoint and parse any returned mailbox SSE events.
  *
  * The query cursor values are "next wanted" ordinals, matching `mbx`
  * semantics.
  */
-function* fetchMailboxMessages(hab, src, url, topics, bodyMode, timeouts) {
+function* fetchMailboxMessages(hab, src, url, topics, bodyMode, timeouts, services = defaultRuntimeServices) {
     const query = hab.query(hab.pre, src, { topics }, "mbx");
-    const handle = yield* fetchMailboxQueryResponse(url, query, bodyMode, src, timeouts.requestOpenTimeoutMs);
+    const handle = yield* fetchMailboxQueryResponse(url, query, bodyMode, src, timeouts.requestOpenTimeoutMs, services);
     if (!handle) {
         return [];
     }
@@ -814,6 +857,7 @@ function* fetchMailboxMessages(hab, src, url, topics, bodyMode, timeouts) {
     const text = yield* readMailboxSseBody(response, controller, {
         idleTimeoutMs: timeouts.readIdleTimeoutMs,
         maxDurationMs: timeouts.maxReadDurationMs,
+        services,
     });
     return parseMailboxSse(text);
 }
@@ -827,7 +871,7 @@ function* fetchMailboxMessages(hab, src, url, topics, bodyMode, timeouts) {
  *
  * Message parsing and SSE body policy remain with `fetchMailboxMessages(...)`.
  */
-function* fetchMailboxQueryResponse(url, query, bodyMode, destination, timeoutMs) {
+function* fetchMailboxQueryResponse(url, query, bodyMode, destination, timeoutMs, services = defaultRuntimeServices) {
     const request = buildCesrRequest(query, {
         bodyMode,
         destination,
@@ -836,7 +880,7 @@ function* fetchMailboxQueryResponse(url, query, bodyMode, destination, timeoutMs
         method: "POST",
         headers: request.headers,
         body: request.body,
-    }, { timeoutMs });
+    }, { timeoutMs, services });
 }
 function normalizeMailboxPollingTimeoutPolicy(overrides) {
     const defaults = MailboxPoller.DefaultTimeoutPolicy;
@@ -870,7 +914,7 @@ function positiveTimeoutMs(value, fallback) {
  * Body-mode policy:
  * - send the whole provided payload in the request body
  */
-export function* postCesrMessage(url, body, bodyMode, destination) {
+export function* postCesrMessage(url, body, bodyMode, destination, services = defaultRuntimeServices) {
     const requests = bodyMode === "header" ? splitCesrStream(body) : [body];
     for (const currentBody of requests) {
         const request = buildCesrRequest(currentBody, {
@@ -881,6 +925,8 @@ export function* postCesrMessage(url, body, bodyMode, destination) {
             method: "POST",
             headers: request.headers,
             body: request.body,
+        }, {
+            services,
         });
         yield* closeResponseBody(response);
         if (!response.ok) {

package/esm/keri/src/app/habbing.js

@@ -409,6 +409,7 @@ export class Hab {
             algo,
             salt,
             tier,
+            temp: this.ks.temp,
         });
         if (!transferable && verfers.length === 1) {
             prefixCode = verfers[0].code;

package/esm/keri/src/app/httping.js

@@ -1,4 +1,5 @@
 import { action } from "effection";
+import { defaultRuntimeServices } from "./runtime-services.js";
 /**
  * Fetch one HTTP response under Effection cancellation control.
  *
@@ -8,8 +9,9 @@ import { action } from "effection";
  * - hand the caller both the `Response` and the controller when body policy
  *   needs later abort access, such as mailbox SSE long-poll reads
  */
-export function* fetchResponseHandle(url, init = {}) {
-    const handle = yield* fetchResponseHandleInternal(url, init);
+export function* fetchResponseHandle(url, init = {}, options = {}) {
+    const { services = defaultRuntimeServices } = options;
+    const handle = yield* fetchResponseHandleInternal(url, init, { services });
     if (!handle) {
         throw new Error("HTTP response handle unexpectedly resolved to null.");
     }
@@ -21,10 +23,12 @@ export function* fetchResponseHandle(url, init = {}) {
  * This is for callers such as mailbox polling that treat request timeout as a
  * normal "no response yet" outcome instead of as an exception.
  */
-export function* fetchResponseHandleOrNull(url, init = {}, { timeoutMs, } = {}) {
+export function* fetchResponseHandleOrNull(url, init = {}, options = {}) {
+    const { timeoutMs, services = defaultRuntimeServices } = options;
     return yield* fetchResponseHandleInternal(url, init, {
         timeoutMs,
         nullOnAbort: true,
+        services,
     });
 }
 /**
@@ -43,21 +47,22 @@ export function* closeResponseBody(response) {
         return () => { };
     });
 }
-function* fetchResponseHandleInternal(url, init, { timeoutMs, nullOnAbort = false, } = {}) {
+function* fetchResponseHandleInternal(url, init, options = {}) {
+    const { timeoutMs, nullOnAbort = false, services = defaultRuntimeServices, } = options;
     return yield* action((resolve, reject) => {
         const controller = new AbortController();
         let settled = false;
         let timedOut = false;
-        const timeoutId = timeoutMs === undefined ? undefined : setTimeout(() => {
+        const timeoutId = timeoutMs === undefined ? undefined : services.clock.setTimeout(() => {
             timedOut = true;
             controller.abort();
         }, timeoutMs);
         const clearTimer = () => {
             if (timeoutId !== undefined) {
-                clearTimeout(timeoutId);
+                services.clock.clearTimeout(timeoutId);
             }
         };
-        fetch(url, { ...init, signal: controller.signal }).then((response) => {
+        services.http.fetch(url, { ...init, signal: controller.signal }).then((response) => {
             settled = true;
             clearTimer();
             resolve({ response, controller });

package/esm/keri/src/app/keeping.js

@@ -551,9 +551,9 @@ export class Manager {
                 ridx: lot.ridx,
                 kidx: lot.kidx + offset,
                 transferable: verfer.transferable,
-                // Persisted keeper parameters do not retain temp/stretch mode, so
-                // derived signing must use the normal persisted-sequence behavior.
-                temp: false,
+                // Temp keepers create temp-derived keys, so path re-derivation must
+                // mirror the active keeper mode. Durable keepers remain production-cost.
+                temp: this.ks.temp,
             })[0];
             if (!signer || signer.verfer.qb64 !== pub) {
                 throw new Error(`Derived signer mismatch for pre=${pre} ri=${lot.ridx} kidx=${lot.kidx + offset}.`);

package/esm/keri/src/app/mailbox-sse.js

@@ -1,4 +1,5 @@
 import { action } from "effection";
+import { defaultRuntimeServices } from "./runtime-services.js";
 /** Shared encoder for mailbox SSE parsing. */
 const textEncoder = new TextEncoder();
 const DEFAULT_READ_IDLE_TIMEOUT_MS = 500;
@@ -10,7 +11,8 @@ const DEFAULT_MAX_READ_DURATION_MS = 30_000;
  * callers use an explicit read budget and idle timeout instead of waiting for
  * `response.text()` to resolve.
  */
-export function* readMailboxSseBody(response, controller, { idleTimeoutMs = DEFAULT_READ_IDLE_TIMEOUT_MS, maxDurationMs = DEFAULT_MAX_READ_DURATION_MS, } = {}) {
+export function* readMailboxSseBody(response, controller, options = {}) {
+    const { idleTimeoutMs = DEFAULT_READ_IDLE_TIMEOUT_MS, maxDurationMs = DEFAULT_MAX_READ_DURATION_MS, services = defaultRuntimeServices, } = options;
     const body = response.body;
     if (!body) {
         return "";
@@ -18,14 +20,14 @@ export function* readMailboxSseBody(response, controller, { idleTimeoutMs = DEFA
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let text = "";
-    const deadline = Date.now() + maxDurationMs;
+    const deadline = services.clock.now() + maxDurationMs;
     const timedOut = Symbol("timedOut");
     try {
-        while (Date.now() < deadline) {
-            const remaining = Math.max(1, Math.min(idleTimeoutMs, deadline - Date.now()));
+        while (services.clock.now() < deadline) {
+            const remaining = Math.max(1, Math.min(idleTimeoutMs, deadline - services.clock.now()));
             const next = yield* action((resolve, reject) => {
                 let settled = false;
-                const timeoutId = setTimeout(() => {
+                const timeoutId = services.clock.setTimeout(() => {
                     settled = true;
                     resolve(timedOut);
                 }, remaining);
@@ -34,23 +36,23 @@ export function* readMailboxSseBody(response, controller, { idleTimeoutMs = DEFA
                         return;
                     }
                     settled = true;
-                    clearTimeout(timeoutId);
+                    services.clock.clearTimeout(timeoutId);
                     resolve(result);
                 }).catch((error) => {
                     if (settled) {
                         return;
                     }
                     settled = true;
-                    clearTimeout(timeoutId);
+                    services.clock.clearTimeout(timeoutId);
                     reject(error);
                 });
                 return () => {
-                    clearTimeout(timeoutId);
+                    services.clock.clearTimeout(timeoutId);
                 };
             });
             if (next === timedOut) {
                 if (parseMailboxSse(text).length > 0
-                    || Date.now() + idleTimeoutMs >= deadline) {
+                    || services.clock.now() + idleTimeoutMs >= deadline) {
                     controller.abort();
                     break;
                 }

package/esm/keri/src/app/notifying.js

@@ -14,6 +14,7 @@ export function notice(attrs, options = {}) {
         },
     });
 }
+/** Derive sidecar-open options from the owning `Habery` path/layout settings. */
 export function noterOptionsForHabery(hby, options = {}) {
     return {
         name: hby.name,
@@ -26,11 +27,16 @@ export function noterOptionsForHabery(hby, options = {}) {
         ...options,
     };
 }
+/** Open the notification sidecar that belongs to one `Habery`. */
 export function* openNoterForHabery(hby, options = {}) {
     return yield* createNoter(noterOptionsForHabery(hby, options));
 }
 /**
  * Signed durable controller notifications with transient `/notification` pings.
+ *
+ * The detached signature is verified on every read/mutation path so operators
+ * can trust CLI output even though notification payloads are intentionally
+ * application-specific maps.
  */
 export class Notifier {
     constructor(hby, { noter, signaler, }) {
@@ -56,6 +62,7 @@ export class Notifier {
         this.noter = noter;
         this.signaler = signaler ?? new Signaler();
     }
+    /** Add one unread signed notice and emit a transient add signal. */
     add(attrs) {
         const signator = this.requireSignator();
         const note = notice(attrs);
@@ -66,12 +73,15 @@ export class Notifier {
         this.emitSignal("add", note);
         return true;
     }
+    /** List verified notices in durable datetime order. */
     list(start = 0, limit = 25) {
         return this.noter.listNotices(start, limit).map(([note, cigar]) => this.requireVerifiedNotice(note, cigar));
     }
+    /** Count durable notices without verifying each payload. */
     count() {
         return this.noter.countNotices();
     }
+    /** Mark one notice read and re-sign its updated pad. */
     markRead(rid) {
         const [note] = this.requireNoticePair(rid);
         if (note.read) {
@@ -86,6 +96,7 @@ export class Notifier {
         this.emitSignal("mar", note);
         return true;
     }
+    /** Remove one verified notice and emit a transient remove signal. */
     remove(rid) {
         const [note] = this.requireNoticePair(rid);
         if (!this.noter.removeNotice(rid)) {

package/esm/keri/src/app/oobiery.js

@@ -8,6 +8,7 @@ import { Roles } from "../core/roles.js";
 import { acceptReplyDecision, unverifiedReplyDecision } from "../core/routing.js";
 import { closeResponseBody, fetchResponseHandle } from "./httping.js";
 import { persistResolvedContact } from "./organizing.js";
+import { defaultRuntimeServices } from "./runtime-services.js";
 import { runtimeTurn } from "./runtime-turn.js";
 export const OOBI_REQUEST_ROUTE = "/oobis";
 /**
@@ -24,7 +25,7 @@ export const OOBI_REQUEST_ROUTE = "/oobis";
  *   leak back to the `AgentRuntime` root
  */
 export class Oobiery {
-    constructor(hby, reactor, { cues } = {}) {
+    constructor(hby, reactor, options = {}) {
         Object.defineProperty(this, "hby", {
             enumerable: true,
             configurable: true,
@@ -43,9 +44,17 @@ export class Oobiery {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "services", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const { cues, services = defaultRuntimeServices } = options;
         this.hby = hby;
         this.reactor = reactor;
         this.cues = cues ?? new Deck();
+        this.services = services;
     }
     /** Register `/introduce` on the shared reply router. */
     registerReplyRoutes(router = this.reactor.router) {
@@ -149,7 +158,7 @@ export class Oobiery {
             said: meta.said ?? null,
         };
         this.pinQueueStore(kind, url, queuedRecord);
-        const response = yield* fetchOobiResponse(url);
+        const response = yield* fetchOobiResponse(url, this.services);
         if (!response.ok) {
             yield* closeResponseBody(response);
             this.remQueueStore(kind, url);
@@ -532,8 +541,10 @@ export { OOBI_MAILBOX_TOPIC };
  * This is the real promise-adaptation boundary for remote OOBI retrieval. The
  * surrounding runtime stays operation-native.
  */
-function* fetchOobiResponse(url) {
-    const { response } = yield* fetchResponseHandle(url);
+function* fetchOobiResponse(url, services = defaultRuntimeServices) {
+    const { response } = yield* fetchResponseHandle(url, {}, {
+        services,
+    });
     return response;
 }
 /**

package/esm/keri/src/app/query-transport.js

@@ -62,6 +62,8 @@ function* postQueryMessage(runtime, url, body, bodyMode, destination) {
             method: "POST",
             headers: request.headers,
             body: request.body,
+        }, {
+            services: runtime.services,
         });
         if (!response.ok) {
             throw new ValidationError(`Query delivery to ${url} failed with HTTP ${response.status}.`);
@@ -72,6 +74,7 @@ function* postQueryMessage(runtime, url, body, bodyMode, destination) {
             const text = yield* readMailboxSseBody(response, controller, {
                 idleTimeoutMs: 500,
                 maxDurationMs: 5_000,
+                services: runtime.services,
             });
             for (const message of parseMailboxSse(text)) {
                 if (message.msg.length > 0) {

package/esm/keri/src/app/runtime-services.js

@@ -0,0 +1,22 @@
+/** Production clock backed by the JavaScript runtime. */
+export const defaultRuntimeClock = Object.freeze({
+    now: () => Date.now(),
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (timer) => clearTimeout(timer),
+});
+/** Production HTTP client backed by global `fetch`. */
+export const defaultRuntimeHttpClient = Object.freeze({
+    fetch: (url, init) => fetch(url, init),
+});
+/** Production runtime services. */
+export const defaultRuntimeServices = Object.freeze({
+    clock: defaultRuntimeClock,
+    http: defaultRuntimeHttpClient,
+});
+/** Resolve partial runtime service overrides against production defaults. */
+export function resolveRuntimeServices(services = {}) {
+    return Object.freeze({
+        clock: services.clock ?? defaultRuntimeClock,
+        http: services.http ?? defaultRuntimeHttpClient,
+    });
+}

package/esm/keri/src/app/version.js

@@ -1,11 +1,14 @@
 /**
- * Generated by scripts/generate_versions.ts.
- * Do not edit by hand.
+ * Template used by scripts/generate_versions.ts for package version modules.
+ *
+ * The generator token-replaces the string placeholders below, then formats and
+ * compares the rendered output during version checks. Do not edit generated
+ * `src/version.ts` files by hand; edit this template instead.
  */
 /** Package semantic version copied from the owning package manifest. */
-export const PACKAGE_VERSION = "0.6.0";
+export const PACKAGE_VERSION = "0.7.0";
 /** Optional build metadata stamp injected by release/CI workflows. */
-export const BUILD_METADATA = "build.9.11f27f1a6176caac7b15d7fba862023af598592f";
+export const BUILD_METADATA = "build.12.6aeea4790568f27066636c48ec39d2f098e3c26d";
 /** User-facing version string with build metadata appended when present. */
 export const DISPLAY_VERSION = BUILD_METADATA
     ? `${PACKAGE_VERSION}+${BUILD_METADATA}`

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

@@ -172,6 +172,10 @@ export class Kevery {
                 else if (sn !== null && !this.db.fullyWitnessed(kever.serder)) {
                     return escrowQuery("notFullyWitnessed");
                 }
+                // Reopened validators may have accepted a delegated event before its
+                // `.aess` source-seal hint was learned. Repair that hint before replay
+                // so downstream receivers get the same delegation attachment KERIpy
+                // would clone from persisted delegating-event state.
                 this.repairReplaySourceSeal(kever);
                 const msgs = [...this.db.clonePreIter(pre, fn)];
                 if (kever.delpre) {
@@ -557,6 +561,9 @@ export class Kevery {
             return this.makeEscrowDecision("duplicitous", init, `Likely duplicitous inception for ${pre}; existing SAID=${kever.said}, got ${said}.`);
         }
         const duplicateSaid = this.db.kels.getLast(pre, sn);
+        // A duplicate accepted event may still carry late source-seal or receipt
+        // attachments. Preserve those through the duplicate path instead of
+        // rejecting the whole replay as already-seen.
         if (duplicateSaid && duplicateSaid === said && sn <= kever.sn) {
             return this.buildDuplicateDecision(kever, init);
         }
@@ -929,6 +936,9 @@ export class Kevery {
     emitAcceptanceCues(kever, serder, local) {
         const habord = this.db.getHab(kever.pre);
         if (habord?.mid) {
+            // Group habitats can be learned through remote traffic after reopen.
+            // Keep the live group-prefix indexes synchronized with durable habitat
+            // records before protected-party cue policy runs.
             this.db.prefixes.add(kever.pre);
             this.db.groups.add(kever.pre);
         }
@@ -1941,6 +1951,13 @@ export class Kevery {
             duplicate: "sameSaid",
         };
     }
+    /**
+     * Decide whether a duplicate event's attached source seal is safe to store.
+     *
+     * Duplicate replay is intentionally narrow: only an existing delegated
+     * establishment event may learn a late source seal, and the seal must name
+     * the exact delegator event already known to anchor this delegate event.
+     */
     validDuplicateSourceSeal(kever, serder, sourceSeal) {
         const pre = serder.pre;
         const said = serder.said;
@@ -1956,6 +1973,14 @@ export class Kevery {
         return anchoring?.snh === sourceSeal.s.numh
             && anchoring.said === sourceSeal.d.qb64;
     }
+    /**
+     * Backfill `.aess` for an accepted delegated establishment before replay.
+     *
+     * KERIpy clones delegation attachments from durable state during replay.
+     * `keri-ts` keeps replay construction decoupled, so this helper repairs the
+     * accepted source-seal index from the delegator's sealing event when the
+     * event body was accepted before the hint was persisted.
+     */
     repairReplaySourceSeal(kever) {
         const serder = kever.serder;
         const pre = serder.pre;
@@ -1981,6 +2006,14 @@ export class Kevery {
             new Diger({ qb64: anchoring.said }),
         ]);
     }
+    /**
+     * Repair accepted delegated events after a delegator event is accepted.
+     *
+     * When the newly accepted event contains delegation anchors, any already
+     * stored delegate establishment it names can learn the corresponding
+     * source-seal hint immediately. This keeps later duplicate/replay handling
+     * deterministic without rerunning full event acceptance.
+     */
     repairAnchoredDelegationSourceSeals(serder) {
         const delpre = serder.pre;
         const said = serder.said;
@@ -2011,6 +2044,13 @@ export class Kevery {
             }
         }
     }
+    /**
+     * Repair source-seal hints for escrowed delegated establishment events.
+     *
+     * Escrow reprocessing may encounter a delegate event after the approving
+     * delegator event was already accepted. This helper converts that discovered
+     * anchor into the same `.aess` hint carried by live source-seal attachments.
+     */
     repairEscrowDelegationSourceSeal(serder) {
         const pre = serder.pre;
         const said = serder.said;

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

@@ -1037,6 +1037,9 @@ export class Kever {
         // for escrow. Misfit checks come first so locally protected events do not
         // leak into a more permissive partial-signature or partial-delegation
         // class.
+        // A local delegator reviewing someone else's delegated establishment is a
+        // protected-party case, but it must enter `delegables` until the local
+        // approval interaction/rotation is actually attached as a source seal.
         const localDelegatorApprovalCandidate = (input.serder.ilk === Ilks.dip || input.serder.ilk === Ilks.drt)
             && this.locallyDelegated(delpre)
             && !this.locallyOwned();
@@ -1158,6 +1161,9 @@ export class Kever {
         // A local delegator without an attached approval seal is not a generic
         // partial-delegation case. It is specifically waiting for local
         // out-of-band approval to be attached and reprocessed.
+        // Local approval is represented by a real, already accepted delegator
+        // event. The attached source seal is only authoritative when it resolves
+        // to that accepted event and that event's anchors name this delegate event.
         const sourceSealApprovesEvent = input.sourceSeal
             ? this.lookupAcceptedDelegatingEvent(delpre, input.sourceSeal, input.serder) !== null
             : false;
@@ -1403,6 +1409,9 @@ export class Kever {
         if (!candidate || !candidate.said || candidate.sn === null) {
             return null;
         }
+        // Accepted first-seen state is the primary signal, but restored KELs may
+        // have authoritative sequence membership before first-seen metadata has
+        // been reconstructed. Accept either durable signal for approval lookup.
         const accepted = !!this.db.fons.get(dgKey(delpre, candidate.said))
             || this.db.kels.getLast(delpre, candidate.sn) === candidate.said;
         if (!accepted)