keri-ts 2.2.4 → 2.2.5

package/esm/keri/npm/src/app/multisig/multisig-workflows.js

@@ -184,21 +184,6 @@ function* publishVdrProposal(hby, protocol, postman, member, recipients, proposa
     return groupSendResult(outcomes);
 }
 /** True when a KEL event is accepted locally. */
-/**
- * Commit the members of a locally accepted group establishment event.
- *
- * Only the current latest establishment event commits; replaying an older
- * approval must not restore historical group membership. Returns whether the
- * members were committed.
- */
-export function commitAcceptedGroupMembers(hby, serder, smids, rmids) {
-    const pre = serder.pre;
-    if (!pre || !eventAccepted(hby, serder) || hby.db.getKever(pre)?.lastEst.d !== serder.said) {
-        return false;
-    }
-    hby.commitGroupHabMembers(pre, smids, rmids.length > 0 ? rmids : smids);
-    return true;
-}
 export function eventAccepted(hby, serder) {
     const pre = serder.pre;
     const said = serder.said;
@@ -383,9 +368,9 @@ export function* approveKelProposal(hby, runtime, exn, route, options) {
     // approval must reuse its proposal's wrapper version for the proposer to merge it.
     exn.pvrsn);
     const accepted = eventAccepted(hby, serder);
-    if (proposal.route !== MULTISIG_IXN_ROUTE) {
-        commitAcceptedGroupMembers(hby, serder, smids, proposal.attrs.rmids);
-    }
+    // An establishment event this approval completed: the members follow accepted state now, not the proposal's lists.
+    if (accepted && proposal.route !== MULTISIG_IXN_ROUTE)
+        hby.alignGroupMembers(groupPre);
     return { route, said: wrapperSaid, embedded: embeddedSaid ?? "", group: groupPre, accepted, ...publication };
 }
 /**

package/esm/keri/npm/src/app/multisig/proposing.js

@@ -4,7 +4,7 @@ import { createCredential, inceptCredentialRegistry, } from "../credentials/cred
 import { groupSigningMembers, localGroupMember, uniqueMembers } from "./group-members.js";
 import { MULTISIG_ICP_ROUTE, MULTISIG_IXN_ROUTE, MULTISIG_ROT_ROUTE } from "./grouping.js";
 import { remoteGroupMembers } from "./multisig-messaging.js";
-import { approveAcdcV2Registry, commitAcceptedGroupMembers, publishAcdcV2Registry, publishProposal, } from "./multisig-workflows.js";
+import { approveAcdcV2Registry, publishAcdcV2Registry, publishProposal, } from "./multisig-workflows.js";
 /** Propose a new group: create this member's inception and publish it. */
 export function* proposeGroupInception(deps, member, alias, { smids, rmids = smids, ...args }, inputs) {
     // Publishing needs a route to every other member. Refuse before the group habitat exists, so a call that could
@@ -44,21 +44,6 @@ export function* proposeGroupInteraction(deps, group, data, inputs, version) {
     const sent = yield* publishProposal(hby, deps.protocol, deps.postman, localGroupMember(hby, created.hab.pre), smids, { route: MULTISIG_IXN_ROUTE, attrs: { gid: created.hab.pre, smids } }, created.message);
     return { ...sent, route: MULTISIG_IXN_ROUTE, group: created.hab.pre, event, smids, rmids: [] };
 }
-/**
- * Commit the members a proposed rotation named, once the rotation is accepted and
- * is the group's latest establishment event. Idempotent; false until then, so a
- * proposed newcomer is never adopted early. Other event kinds commit nothing.
- *
- * @throws ValidationError when the event is not an accepted event body held locally.
- */
-export function settleProposedRotation(deps, result) {
-    if (result.route !== MULTISIG_ROT_ROUTE)
-        return false;
-    const serder = deps.hby.db.getEvtSerder(result.event.pre, result.event.said);
-    if (!serder)
-        throw new ValidationError(`No rotation ${result.event.said} is held for ${result.event.pre}.`);
-    return commitAcceptedGroupMembers(deps.hby, serder, result.smids, result.rmids);
-}
 /**
  * Propose an ACDC v2 registry event (`rip` or `bup`): author the group anchor
  * that seals it, process this member's own contribution, hand the anchor to the

package/esm/keri/npm/src/app/multisig/rejoin-group.js

@@ -0,0 +1,99 @@
+import { ValidationError } from "../../core/errors.js";
+import { beginOobi, oobiStatus } from "../bootstrap/oobi-resolving.js";
+import { observeUntil } from "../runtime/workflow-contract.js";
+import { acceptedGroupMembers, isAcceptedGroupMember } from "./group-members.js";
+/**
+ * Resolve `input.oobi`, wait for the group's accepted key state, and record the group with `input.member` as
+ * its local member, using the accepted members. Then the mailbox poller, the KEL publisher and the root
+ * replicator are prompted for the group, so each acts for it on its next tock. Creates no event and signs
+ * nothing. Observe-only: the host must already run the runtime's workers (see `workflow-contract.ts`).
+ *
+ * A record that already names `member` returns `joined` at once with `written: false`, with no OOBI and no write.
+ *
+ * @throws ValidationError for misuse: `member` is not a local single-signature habitat, `group` is a local
+ * single-signature habitat, the group already has a local record naming a different member (use
+ * `replaceGroupMember`), or `alias` is bound to another prefix.
+ */
+export function* rejoinGroup(deps, input) {
+    const { hby } = deps, { group, member, alias, timeoutMs, domain } = input;
+    const recorded = rejoinedRecord(hby, input);
+    if (recorded)
+        return recorded;
+    beginOobi(deps, input.oobi);
+    const read = () => readRejoin(hby.db, input.oobi, group, member.pre);
+    yield* observeUntil(() => read().kind !== "waiting", { timeoutMs, clock: deps.clock });
+    const reading = read();
+    switch (reading.kind) {
+        case "waiting":
+            return { outcome: "timed-out", group, timeoutMs, waiting: reading.waiting };
+        case "oobi-failed":
+            return { outcome: "oobi-failed", group, reason: reading.reason };
+        case "not-member":
+            return { outcome: "not-member", group, member: member.pre };
+    }
+    const { smids, rmids } = reading.members;
+    if (!smids.includes(member.pre) && !rmids.includes(member.pre)) {
+        return { outcome: "not-member", group, member: member.pre };
+    }
+    hby.joinGroupHab(group, alias, member, smids, rmids, domain);
+    deps.mailboxPoller.prompt(group);
+    deps.kelPublisher.prompt(group);
+    deps.rootReplicator?.prompt(group);
+    deps.changes?.push({ kind: "group", id: group });
+    return { outcome: "joined", group, alias, smids, rmids, written: true };
+}
+/**
+ * Refuse misuse before any I/O, and return `joined` for a record that already names the member.
+ * Null when the group has no local record yet.
+ */
+function rejoinedRecord(hby, { group, member, alias, domain }) {
+    if (!group)
+        throw new ValidationError("Group prefix is required.");
+    if (!alias)
+        throw new ValidationError("Group alias is required.");
+    const pre = member.pre;
+    if (!pre || hby.habs.get(pre) !== member) {
+        throw new ValidationError(`Member ${pre} is not a habitat of this Habery.`);
+    }
+    if (hby.db.getHab(pre)?.mid) {
+        throw new ValidationError(`Member ${pre} is a group identifier; a group rejoins through a single-signature member.`);
+    }
+    const record = hby.db.getHab(group);
+    if (record && !record.mid) {
+        throw new ValidationError(`${group} is a local single-signature identifier, not a group.`);
+    }
+    if (record?.mid && record.mid !== pre) {
+        throw new ValidationError(`Group ${group} is already recorded with local member ${record.mid}; use replaceGroupMember to change it.`);
+    }
+    if (record?.mid) {
+        return {
+            outcome: "joined",
+            group,
+            alias: record.name ?? alias,
+            smids: [...(record.smids ?? [])],
+            rmids: [...(record.rmids ?? [])],
+            written: false,
+        };
+    }
+    const bound = hby.db.getName(domain ?? "", alias);
+    if (bound && bound !== group)
+        throw new ValidationError(`Alias ${alias} is already bound to ${bound}.`);
+    return null;
+}
+/** Read the OOBI, the group's accepted key state and its members, in that order. */
+function readRejoin(db, oobi, group, member) {
+    const status = oobiStatus({ db }, oobi);
+    if (status.state === "pending")
+        return { kind: "waiting", waiting: "oobi" };
+    if (!db.getKever(group)) {
+        return status.state === "failed"
+            ? { kind: "oobi-failed", reason: status.reason }
+            : { kind: "waiting", waiting: "group-key-state" };
+    }
+    // Every list member is an accepted member, so this answers `not-member` before the other members' KELs arrive.
+    if (!isAcceptedGroupMember(db, group, member))
+        return { kind: "not-member" };
+    const candidates = [...db.states.getTopItemIter()].map(([keys]) => keys.join("."));
+    const members = acceptedGroupMembers(db, group, candidates);
+    return members ? { kind: "members", members } : { kind: "waiting", waiting: "member-key-state" };
+}

package/esm/keri/npm/src/app/multisig/replace-member.js

@@ -1,16 +1,27 @@
 /**
- * Replace a local group's recorded member after a rotation removed it, and end the runtime's work bound to it.
+ * Replace a local group's recorded member after a rotation removed it, end the runtime's work bound to it, and
+ * retire it when nothing else needs it.
  *
  * `Habery.joinGroupHab` re-points the record and clears the durable rows addressed to the old member. The
  * runtime owns the live operations, so this is the one call that also ends them: an issuance whose party
  * member or frozen DH custodian is the old member, and an Unblind holding it. Each ends through its owner's
  * own end path, which releases the approval and drops the held `heldq`/`heldu` rows. Group IPEX messages and
  * presentations keep no member binding (their contributions are already signed and the member is read live),
- * so they are left to run. Nothing is signed and no event is made.
+ * so they are left to run. It then prompts the mailbox poller, the KEL publisher and the root replicator for the
+ * group, so each acts as the new member on its next tock instead of at its next sweep. Nothing is signed and no
+ * event is made.
+ *
+ * Last, the old member is retired with `retireIdentifier` (its stored keys deleted, its mailbox workers
+ * stopped, every KEL and BADA record about it kept) unless the caller set `keepPrevious` or
+ * `retireIdentifierRefusal` names a reason to keep it: it is a member of another local group, a delegator, a
+ * registry issuer, or has live work. A kept member does not fail the replacement; the result says why it was
+ * kept.
  */
 import { ValidationError } from "../../core/errors.js";
+import { retireIdentifier, retireIdentifierRefusal } from "../identity/retire-identifier.js";
 /**
- * Replace the local member of `input.group`, then end live operations bound to the previous one.
+ * Replace the local member of `input.group`, end live operations bound to the previous one, then retire the
+ * previous one unless it is kept (see the module doc).
  *
  * @throws ValidationError when `joinGroupHab` refuses: the group has no accepted state, the previous member is
  * still a member of it, or the new one is not.
@@ -25,10 +36,20 @@ export function replaceGroupMember(runtime, input) {
         throw new ValidationError(`Member ${previous} is already the local member of ${group}.`);
     hby.joinGroupHab(group, alias, member, input.smids, input.rmids ?? input.smids, record.domain);
     const reason = `Local member ${previous} of group ${group} was replaced by ${member.pre}`;
+    runtime.mailboxPoller.prompt(group);
+    runtime.kelPublisher.prompt(group);
+    runtime.rootReplicator?.prompt(group);
     const ops = runtime.operations;
-    return {
-        previous,
-        issuance: ops?.issuance.endBoundToMember(group, previous, reason) ?? [],
-        unblinding: ops?.unblinding.endBoundToMember(group, previous, reason) ?? [],
-    };
+    const issuance = ops?.issuance.endBoundToMember(group, previous, reason) ?? [];
+    const unblinding = ops?.unblinding.endBoundToMember(group, previous, reason) ?? [];
+    return { previous, issuance, unblinding, previousMember: retirePrevious(runtime, previous, input.keepPrevious) };
+}
+/** Retire the replaced member, or say why it is kept. */
+function retirePrevious(runtime, previous, keep = false) {
+    if (keep)
+        return { kind: "kept", reason: "The caller asked to keep the previous member." };
+    const refusal = retireIdentifierRefusal(runtime, previous);
+    if (refusal)
+        return { kind: "kept", reason: refusal };
+    return { kind: "retired", retired: retireIdentifier(runtime, previous) };
 }

package/esm/keri/npm/src/app/protocol/parsering.js

@@ -1,7 +1,9 @@
-import { BlindState, BoundState, Cigar, concatBytes, Counter, Dater, Diger, FirstSeen, Ilks, isCounterGroupLike, isGroupTuple, Labeler, Noncer, NumberPrimitive, parseBytes, parseSerder, Prefixer, requireFlatFrame, SealEvent, SealKind, SealSource, SerderACDC, SerderKERI, Siger, Texter, TypeMedia, Verfer, Verser, } from "cesr-ts";
+import { BlindState, BoundState, Cigar, concatBytes, Counter, Dater, Diger, FirstSeen, Ilks, isCounterGroupLike, isGroupTuple, Labeler, Noncer, NumberPrimitive, parseBytes, parseSerder, Prefixer, SealEvent, SealKind, SealSource, SerderACDC, SerderKERI, Siger, Texter, TypeMedia, Verfer, Verser, } from "cesr-ts";
 import { KeriDispatchEnvelope, PathedMaterialGroup, TransIdxSigGroup, TransLastIdxSigGroup, TransReceiptQuadruple, } from "../../core/dispatch.js";
+import { ValidationError } from "../../core/errors.js";
 import { nestedIpexRoute, supportsNestedExchange } from "../../core/exchange/protocol-exchanging.js";
 import { serializeMessage } from "../../core/protocol-serialization.js";
+import { readPrefixer } from "../../core/wire-fields.js";
 /**
  * Convert one or more already-parsed CESR frames into KERI dispatch envelopes.
  *
@@ -29,12 +31,14 @@ export function envelopesFromFrames(frames, local = false) {
  * @param messageKevery Authoritative shared message-policy/KRAM processor when distinct from input Kevery.
  * @param registry V2 registry intake over accepted public KEL state, without requiring a local alias.
  * @param qvy Optional auxiliary query owner; receives full evidence after v2 message admission.
+ * @param retained Whether this is retained history from a finite local import (`DispatchOptions.retained`): a v2
+ *   `exn`/`xip` then skips KRAM intake and reaches the Exchanger marked retained. Network intake never sets it.
  * @returns The processed envelope and protocol-specific decision data.
  * @throws Unsupported input and infrastructure/handler failures follow their owning processor contracts.
  */
 export function* dispatchEnvelope(envelope, revery, kevery, exchanger, tevery, verifier, mailboxAid, 
 /** Long-lived v2 message policy/KRAM owner; input-specific Kevery handles KEL and legacy traffic. */
-messageKevery = kevery, registry, qvy) {
+messageKevery = kevery, registry, qvy, retained = false) {
     const serder = envelope.serder;
     if (serder instanceof SerderACDC) {
         // Historical upd bytes remain decodable, but cannot enter live registry processing.
@@ -59,7 +63,7 @@ messageKevery = kevery, registry, qvy) {
     }
     if (serder.pvrsn.major >= 2
         && [Ilks.qry, Ilks.rpy, Ilks.exn, Ilks.xip, Ilks.pro, Ilks.bar].some((ilk) => ilk === serder.ilk)) {
-        return yield* dispatchMessage(envelope, revery, messageKevery, exchanger, tevery, mailboxAid, qvy);
+        return yield* dispatchMessage(envelope, revery, messageKevery, exchanger, tevery, mailboxAid, qvy, retained);
     }
     switch (serder.ilk) {
         case Ilks.rpy:
@@ -132,8 +136,9 @@ messageKevery = kevery, registry, qvy) {
  * processMsg boundary: sender policy precedes optional KRAM and proof
  * prerequisites and delegation. Downstream processors authenticate their own
  * evidence; this layer borrows the envelope and never owns its payloads.
+ * A retained exchange (finite local import) skips only the KRAM step.
  */
-function* dispatchMessage(envelope, revery, kevery, exchanger, tevery, mailboxAid, qvy) {
+function* dispatchMessage(envelope, revery, kevery, exchanger, tevery, mailboxAid, qvy, retained = false) {
     const serder = envelope.serder;
     const sender = serder.pre;
     if (sender !== null) {
@@ -147,15 +152,18 @@ function* dispatchMessage(envelope, revery, kevery, exchanger, tevery, mailboxAi
         && !(qvy?.claims ? qvy.claims(serder) : qvy?.resource === serder.route)) {
         return { envelope, decision: { kind: "drop", reason: "missingProcessor" } };
     }
-    const result = kevery.kramer?.intake(envelope);
+    // Retained history was KRAM-admitted where it was first received; its window here has passed by design. Queries
+    // and replies are never retained history and always pass KRAM.
+    const history = retained && (serder.ilk === Ilks.exn || serder.ilk === Ilks.xip);
+    const result = history ? undefined : kevery.kramer?.intake(envelope);
     if (result && result.kind !== "ready")
         return { envelope, decision: result };
     const ready = result?.kind === "ready" ? result.envelope : envelope;
-    const decision = yield* dispatchReadyMessage(ready, revery, kevery, exchanger, tevery, mailboxAid, result?.kind === "ready" ? result.receiverTime : undefined, qvy);
+    const decision = yield* dispatchReadyMessage(ready, revery, kevery, exchanger, tevery, mailboxAid, result?.kind === "ready" ? result.receiverTime : undefined, qvy, history);
     return { envelope: ready, decision };
 }
 /** Delegate accepted evidence; downstream processors verify their own proof owners. */
-function* dispatchReadyMessage(envelope, revery, kevery, exchanger, tevery, mailboxAid, receiverTime, qvy) {
+function* dispatchReadyMessage(envelope, revery, kevery, exchanger, tevery, mailboxAid, receiverTime, qvy, retained = false) {
     const serder = envelope.serder;
     switch (serder.ilk) {
         case Ilks.qry: {
@@ -186,7 +194,7 @@ function* dispatchReadyMessage(envelope, revery, kevery, exchanger, tevery, mail
             }
             if (!exchanger)
                 return { kind: "drop", reason: "missingProcessor" };
-            return yield* dispatchExchange(envelope, exchanger, mailboxAid, receiverTime);
+            return yield* dispatchExchange(envelope, exchanger, mailboxAid, receiverTime, retained);
         default:
             // processPro/processBar remain pass stubs at the selected reference.
             return { kind: "drop", reason: "referenceStub" };
@@ -201,7 +209,7 @@ function dispatchTelQuery(query, tevery) {
     return tevery.processQuery(query);
 }
 /** Await the route owner while preserving parent, child and mailbox provenance. */
-function* dispatchExchange(envelope, exchanger, mailboxAid, receiverTime) {
+function* dispatchExchange(envelope, exchanger, mailboxAid, receiverTime, retained = false) {
     return yield* exchanger.processEvent({
         serder: envelope.serder,
         tsgs: envelope.tsgs,
@@ -216,6 +224,7 @@ function* dispatchExchange(envelope, exchanger, mailboxAid, receiverTime) {
         nests: envelope.nests,
         mailboxAid,
         receiverTime,
+        ...(retained ? { retained } : {}),
     });
 }
 function telEnvelopeFromDispatch(envelope, serder) {
@@ -439,14 +448,32 @@ function collectAttachments(group, envelope) {
             return;
     }
 }
-/** Project one complete frame for message routing without an intermediate event array. */
-export function envelopeFromFrame(message, local = false) {
-    // Only completed consumers may retain parent-owned children through normalization.
+/**
+ * Whether a frame carries nested messages that no completed consumer owns.
+ *
+ * Only supported exchange routes, IPEX disclosure `xip`s and the v2 Unblind query retain parent-owned children; any
+ * other frame with children is unsupported input. A remote frame is refused as one invalid message
+ * (`ProtocolProcessor.dispatch`); {@link envelopeFromFrame} refuses it with a `ValidationError`.
+ */
+export function hasUnsupportedNests(message) {
+    if (!message.nests?.length)
+        return false;
     const route = String(message.body.ked?.r ?? "");
     const unblindQuery = message.body.ilk === "qry" && message.body.pvrsn.major === 2 && route === "/ipex/unblind";
-    if (!unblindQuery && ((message.body.ilk !== "exn" && !(message.body.ilk === "xip" && nestedIpexRoute(route)))
-        || !supportsNestedExchange(route, message.body.pvrsn.major))) {
-        requireFlatFrame(message, "KERI runtime normalization");
+    return !unblindQuery && ((message.body.ilk !== "exn" && !(message.body.ilk === "xip" && nestedIpexRoute(route)))
+        || !supportsNestedExchange(route, message.body.pvrsn.major));
+}
+/**
+ * Project one complete frame for message routing without an intermediate event array.
+ *
+ * Only completed consumers may retain parent-owned children through normalization. A frame with children no consumer
+ * owns is usually a remote child nested inside a parent (a BUP inside an Unblind query, an event inside a multisig or
+ * IPEX exchange): it is refused with a `ValidationError`, which the parent's processor reports as its own typed
+ * refusal (an invalid-message drop, a rejected escrow row), never a fault that ends the runtime.
+ */
+export function envelopeFromFrame(message, local = false) {
+    if (hasUnsupportedNests(message)) {
+        throw new ValidationError(`KERI runtime normalization does not yet support nested message trees (${message.body.ilk ?? "unknown"} frame).`);
     }
     const serder = (message.body instanceof SerderKERI || message.body instanceof SerderACDC)
         ? message.body
@@ -516,8 +543,9 @@ export function restoreAuxiliaryQuery(wire, local = false) {
 export function queryEnvelopeFromDispatch(envelope) {
     const lastSsg = envelope.ssgs.at(-1);
     // V2 processMsg falls back to the claimed sender only when raw sigers exist.
-    const rawSource = !lastSsg && envelope.serder.pvrsn.major >= 2 && envelope.sigers.length && envelope.serder.pre
-        ? new Prefixer({ qb64: envelope.serder.pre })
+    // A claimed sender that is not a prefix authenticates nothing; the query is then refused as unauthenticated.
+    const rawSource = !lastSsg && envelope.serder.pvrsn.major >= 2 && envelope.sigers.length
+        ? readPrefixer(envelope.serder.pre) ?? undefined
         : undefined;
     return {
         serder: envelope.serder,

package/esm/keri/npm/src/app/protocol/protocol-processing.js

@@ -6,9 +6,10 @@ import { consoleLogger } from "../../core/logger.js";
 import { BasicReplyRouteHandler, Revery } from "../../core/routing.js";
 import { Exchanger } from "../exchanges/exchanging.js";
 import { QueryReplies } from "../queries/query-replies.js";
+import { relayRefreshCue } from "../queries/relay-refresh.js";
 import { doEveryOnWrite, PROTOCOL_PACING } from "../runtime/doing.js";
 import { systemClock } from "../runtime/runtime-clock.js";
-import { dispatchEnvelope, envelopeFromFrame, queryEnvelopeFromDispatch, } from "./parsering.js";
+import { dispatchEnvelope, envelopeFromFrame, hasUnsupportedNests, queryEnvelopeFromDispatch, } from "./parsering.js";
 /**
  * Wait after every escrow pass, as KERIpy's Doist cycle (`tock` 0.03125 s, app/directing.py) paces its `escrowDo`,
  * which runs one full pass per cycle. A pass is never skipped or shortened; this is the time others get between passes.
@@ -25,6 +26,24 @@ export const ESCROW_TOCK_MS = 31.25;
 function isInvalidMessageError(error) {
     return error instanceof ValidationError;
 }
+/** Why a remote frame whose nested children no consumer owns is refused. */
+const NESTED_REFUSAL = "KERI runtime normalization does not yet support nested message trees";
+/**
+ * Report and describe the refusal of one extracted message, so its input continues with the next frame.
+ *
+ * @param envelope The refused message's own body and attachments.
+ * @param detail Why validation refused it.
+ * @returns The `invalidMessage` drop for this envelope.
+ */
+function invalidMessage(envelope, detail) {
+    consoleLogger.warn("Skipping invalid message", {
+        said: envelope.serder.said,
+        ilk: envelope.serder.ilk,
+        route: envelope.serder.route,
+        detail,
+    });
+    return { envelope, decision: { kind: "drop", reason: "invalidMessage", detail } };
+}
 /**
  * Dispatch to synchronous semantic owners and publish their committed output.
  *
@@ -48,6 +67,8 @@ export class ProtocolProcessor {
      * @param cues Application output Deck consumed by the composed cue router.
      * @param replies Shared live request correlations captured before application publication.
      * @param qvy Optional caller-owned auxiliary query receiver; owns its authorization and lifecycle.
+     * @param relaying Whether this domain is a relaying host's (the agent side of relay mode): a served sender's query
+     *   about a remote subject then also publishes the host's own refresh query cue (see `relayRefreshCue`).
      * @throws TypeError for inconsistent stores or cue bindings.
      */
     constructor(
@@ -68,7 +89,9 @@ export class ProtocolProcessor {
     /** Ordinary application cues; the composed cue router is the consumer. */
     cues, 
     /** Shared live request correlations; each requesting connection owns its slots. */
-    replies, qvy) {
+    replies, qvy, 
+    /** Relaying host: served senders' queries about remote subjects refresh this host's own view of them. */
+    relaying = false) {
         Object.defineProperty(this, "kvy", {
             enumerable: true,
             configurable: true,
@@ -129,6 +152,12 @@ export class ProtocolProcessor {
             writable: true,
             value: qvy
         });
+        Object.defineProperty(this, "relaying", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: relaying
+        });
         if (protocolCues === cues || kvy.cues !== protocolCues || rvy.cues !== protocolCues
             || exc.cues !== protocolCues || kvy.db !== rvy.db || exc.hby.db !== kvy.db || kvy.rvy !== rvy) {
             throw new TypeError("Protocol processors require one store and a distinct shared protocol cue flow");
@@ -156,14 +185,15 @@ export class ProtocolProcessor {
      * Process one frame and publish its committed protocol cues before returning decision data.
      *
      * @param frame Complete hydrated frame whose evidence remains valid for this operation.
-     * @param options Local intake policy, hosted mailbox provenance and whether to advance escrows.
+     * @param options Local intake policy, hosted mailbox provenance, whether to advance escrows, and whether the frame is
+     *   retained history from a finite local import.
      * @param kvy Input-specific Kevery in this domain; defaults to the shared owner.
      * @returns Exact dispatch result and current mailbox authorization at its synchronous query decision.
      *   A message refused by validation after extraction is an `invalidMessage` drop, so the caller
      *   continues with the next frame as KERIpy's parser does.
      * @throws Domain mismatch, infrastructure/handler or cleanup errors propagate; publication still runs in the dispatch finalizer.
      */
-    dispatch(frame, { local = this.kvy.local, mailboxAid, escrows = false } = {}, kvy = this.kvy) {
+    dispatch(frame, { local = this.kvy.local, mailboxAid, escrows = false, retained = false } = {}, kvy = this.kvy) {
         // A short-lived input processor must publish into this owner's private cue flow.
         if (kvy.db !== this.kvy.db || kvy.cues !== this.protocolCues || kvy.rvy !== this.rvy) {
             throw new TypeError("Kevery belongs to another protocol processing domain");
@@ -172,27 +202,28 @@ export class ProtocolProcessor {
         const self = this;
         return call(function* () {
             try {
-                const envelope = envelopeFromFrame(frame, local);
+                // Children no consumer owns make the frame one invalid message; its own body and attachments remain evidence.
+                const nested = hasUnsupportedNests(frame);
+                const envelope = envelopeFromFrame(nested ? { ...frame, nests: [] } : frame, local);
                 let result;
                 let invalid = false;
                 try {
-                    result = yield* dispatchEnvelope(envelope, self.rvy, kvy, self.exc, self.tvy ?? undefined, self.vry ?? undefined, mailboxAid, self.kvy, // One authoritative v2 sender policy and KRAM intake across all inputs.
-                    self.registry ?? undefined, self.qvy);
+                    result = nested ? invalidMessage(envelope, NESTED_REFUSAL) : yield* dispatchEnvelope(envelope, self.rvy, kvy, self.exc, self.tvy ?? undefined, self.vry ?? undefined, mailboxAid, self.kvy, // One authoritative v2 sender policy and KRAM intake across all inputs.
+                    self.registry ?? undefined, self.qvy, retained);
+                    invalid = nested;
                 }
                 catch (error) {
                     if (!isInvalidMessageError(error))
                         throw error;
                     invalid = true;
-                    consoleLogger.warn("Skipping invalid message", {
-                        said: envelope.serder.said,
-                        ilk: envelope.serder.ilk,
-                        route: envelope.serder.route,
-                        detail: error.message,
-                    });
-                    result = { envelope, decision: { kind: "drop", reason: "invalidMessage", detail: error.message } };
+                    result = invalidMessage(envelope, error.message);
                 }
                 const mailboxQueryAuthorized = !invalid && result.envelope.serder.route === "mbx"
                     && kvy.isMailboxQueryAuthorized(queryEnvelopeFromDispatch(result.envelope));
+                // Published with this query's own cues; the cue router hands it to this host's querier.
+                const refresh = self.relaying && !invalid ? relayRefreshCue(self.exc.hby, result, mailboxAid ?? null) : null;
+                if (refresh)
+                    self.protocolCues.push(refresh);
                 // Capture this request's facts before optional escrows can suspend or change key state.
                 self.publishCues();
                 if (escrows)
@@ -206,14 +237,9 @@ export class ProtocolProcessor {
     }
     /** Capture direct replies before handing ordinary protocol records to the application consumer. */
     publishCues() {
-        // Readiness observers may synchronously reenter dispatch. Own this committed
-        // batch before notifying them so nested publication cannot take its records.
-        const committed = new Deck();
+        this.replies.capture(this.protocolCues);
         while (!this.protocolCues.empty)
-            committed.push(this.protocolCues.pull());
-        this.replies.capture(committed);
-        while (!committed.empty)
-            this.cues.push(committed.pull());
+            this.cues.push(this.protocolCues.pull());
     }
     /** Advance configured escrow owners; each scan joins its own I/O and handler cleanup. */
     *processEscrowsOnce() {

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

@@ -67,23 +67,6 @@ export class QueryReplies {
             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");
-                slot.notify = notify;
-                if (slot.reply || closed)
-                    notify();
-                return () => {
-                    if (slot.notify === notify)
-                        slot.notify = undefined;
-                };
-            },
             /**
              * Inspect evidence without consuming it so callers can finish construction first.
              *
@@ -112,8 +95,6 @@ export class QueryReplies {
                 group.delete(slot);
                 if (group.size === 0)
                     this.active.delete(said);
-                slot.notify?.();
-                slot.notify = undefined;
             },
         };
     }
@@ -142,9 +123,6 @@ export class QueryReplies {
                     && cue.kin === "reply" && cue.route === "/tsn/credential"
                     || slot.reply.kin === "receipt" && cue.kin === "witness"))
                     slot.companion = cue;
-                else
-                    continue;
-                slot.notify?.();
             }
         }
     }

package/esm/keri/npm/src/app/queries/relay-refresh.js

@@ -0,0 +1,81 @@
+/**
+ * Agent side of relay mode: refresh the agent's own view of a subject when a served edge asks about it.
+ *
+ * An edge's only view of third-party key state is its agent's: every edge query is addressed to the agent, which
+ * answers from its own store. That store may be stale for an identifier the agent has no reason of its own to
+ * follow. So when a relaying agent receives a `logs` or `ksn` query from a sender it serves about a subject that is
+ * not one of its own, it also issues its own ordinary `logs` query for that subject, as an ordinary `query` cue its
+ * own querier consumes. The agent is a forwarder, so that query goes directly to the subject's controller, agent or
+ * witness endpoint. This is on demand only, as KERIA queries for its Signify clients: no watching, no subscription
+ * list, no new store.
+ *
+ * What the edge sees: the answer to the query that caused the refresh comes from what the agent held then, unless
+ * the query names a sequence number or anchor the agent lacks, in which case the agent escrows it (query-not-found)
+ * and answers once the refresh lands. A later edge query returns the refreshed state.
+ */
+import { Ilks } from "cesr-ts";
+import { Kever } from "../../core/kel/kever.js";
+import { servingHost } from "../mailbox/forward-handler.js";
+import { queryEnvelopeFromDispatch } from "../protocol/parsering.js";
+import { addressableAttesters } from "./witness-inquisitor.js";
+/**
+ * The requester of a query whose attached signatures satisfy its current signing threshold, or null.
+ *
+ * `logs` and `ksn` answers are public, so the KEL query path does not authenticate the requester (nor does KERIpy).
+ * A refresh spends the agent's own traffic on the requester's behalf, so it needs the requester proven: a
+ * transferable source whose KEL the agent holds and whose current keys signed this query to threshold.
+ *
+ * @param hby Borrowed accepted-state store holding the requester's KEL.
+ * @param query Normalized query envelope with its requester source and indexed signatures.
+ * @returns The authenticated requester AID, or null.
+ */
+function authenticatedRequester(hby, query) {
+    const source = query.source?.qb64;
+    if (!source)
+        return null;
+    const kever = hby.db.getKever(source);
+    if (!kever?.tholder)
+        return null;
+    const verified = Kever.verifyIndexedSignatures(query.serder.raw, query.sigers ?? [], kever.verfers);
+    return kever.tholder.satisfy(verified.indices) ? source : null;
+}
+/**
+ * Decide whether one processed query makes a relaying host refresh its view of the subject, and return the query cue
+ * that does it.
+ *
+ * Every condition must hold:
+ * - the message is a remote (not local) `logs` or `ksn` query the KEL owner accepted or escrowed;
+ * - its subject `q.i` is not a prefix of this Habery;
+ * - its requester is authenticated (see {@link authenticatedRequester}) and served by a local host under the shared
+ *   `servingHost` rule (an accepted mailbox or agent end role naming the host);
+ * - the host can address an attester for the subject now ({@link addressableAttesters}: one with an accepted
+ *   location), so the request is sent on the querier's next pass instead of waiting in its queue.
+ *
+ * The cue is `{ route: "logs", q: {} }` for the subject, signed by the serving host: one full replay from the
+ * attester covers both routes, since `ksn` is answered from the same key state. A `tels` query is not refreshed:
+ * its wire body names the registry and credential but not the issuer the querier selects attesters by.
+ *
+ * @param hby Borrowed habitats and accepted-state store of the relaying host.
+ * @param result Processed envelope and the decision its owner made.
+ * @param mailboxAid Receiving hosted endpoint AID, or null when the request named none.
+ * @returns The refresh query cue, or null when this query refreshes nothing.
+ */
+export function relayRefreshCue(hby, result, mailboxAid) {
+    const { envelope, decision } = result;
+    const serder = envelope.serder;
+    if (envelope.local || serder.ilk !== Ilks.qry || (serder.route !== "logs" && serder.route !== "ksn"))
+        return null;
+    if (!decision || (decision.kind !== "accept" && decision.kind !== "escrow"))
+        return null;
+    const subject = serder.ked?.q?.i;
+    if (typeof subject !== "string" || hby.db.prefixes.has(subject))
+        return null;
+    const requester = authenticatedRequester(hby, queryEnvelopeFromDispatch(envelope));
+    if (!requester)
+        return null;
+    const host = servingHost(hby, { sender: requester, origin: null }, mailboxAid);
+    const hab = host ? hby.habs.get(host) : undefined;
+    if (!hab || addressableAttesters(hab, subject).length === 0)
+        return null;
+    return { kin: "query", pre: subject, route: "logs", q: {}, signer: hab.pre };
+}