keri-ts 1.0.0 → 2.0.1

package/esm/keri/npm/src/app/witnessing.js

@@ -1,914 +0,0 @@
-/**
- * Witness host and controller-side receipting helpers.
- *
- * This module ports the missing operational slice around already-landed
- * receipt-core behavior:
- * - witness receipt/query decision helpers
- * - witness-local ingress processing
- * - synchronous witness receipt endpoints
- * - controller-side witness submission, catchup, and receipt fanout
- *
- * Architectural rules:
- * - normal receipt/escrow decisions stay in `Kevery` and friends
- * - parser/router ownership stays inside the shared runtime/parser seams
- * - concrete listener ownership lives in `tufa`; this module stays on the
- *   protocol/runtime side of that boundary
- */
-import { concatBytes, Counter, CtrDexV1, Ilks, parse, parseBytes } from "cesr-ts";
-import { action, call, ensure } from "effection";
-import { ValidationError } from "../core/errors.js";
-import { receipt as receiptEvent, reply as replyEvent } from "../core/protocol-eventing.js";
-import { Schemes } from "../core/schemes.js";
-import { dgKey } from "../db/core/keys.js";
-import { abortable, rethrowCleanupFailure } from "./abortable.js";
-import { chunkBytes, collectBytes, streamBytes } from "./byte-source.js";
-import { postCesr } from "./cesr-egress.js";
-import { buildCesrRequest, CESR_CONTENT_TYPE, inspectCesrRequest, KERIPY_CESR_JSON_CONTENT_TYPE } from "./cesr-http.js";
-import { acceptedEventReplayMessage } from "./habbing.js";
-import { closeResponseBody, fetchResponseHandle } from "./httping.js";
-import { envelopeFromFrame } from "./parsering.js";
-import { Reactor } from "./reactor.js";
-import { defaultRuntimeServices } from "./runtime-services.js";
-import { converseCesrTcp } from "./tcp-conversation.js";
-import { sendCesrTcp } from "./tcp-egress.js";
-const WitnessReceiptPollAttempts = 20;
-const WitnessReceiptPollDelayMs = 100;
-const KERI_V1 = Object.freeze({ major: 1, minor: 0 });
-const KERIPY_CONTENT_TYPE_ERROR = "content type";
-const WITNESS_HTTP_CONTENT_TYPES = [
-    CESR_CONTENT_TYPE,
-    KERIPY_CESR_JSON_CONTENT_TYPE,
-];
-/** Build one attached `rct` message carrying detached receipt material. */
-function buildDetachedReceiptMessage(serder, { wigers = [], cigars = [] }) {
-    if (wigers.length === 0 && cigars.length === 0) {
-        return serder.raw;
-    }
-    const attachments = [];
-    if (wigers.length > 0) {
-        attachments.push(new Counter({
-            code: CtrDexV1.WitnessIdxSigs,
-            count: wigers.length,
-            version: KERI_V1,
-        }).qb64b, ...wigers.map((wiger) => wiger.qb64b));
-    }
-    if (cigars.length > 0) {
-        attachments.push(new Counter({
-            code: CtrDexV1.NonTransReceiptCouples,
-            count: cigars.length,
-            version: KERI_V1,
-        }).qb64b, ...cigars.flatMap((cigar) => {
-            const verfer = cigar.verfer;
-            if (!verfer) {
-                throw new ValidationError("Detached non-transferable receipt is missing verifier context.");
-            }
-            return [verfer.qb64b, cigar.qb64b];
-        }));
-    }
-    const atc = concatBytes(...attachments);
-    if (atc.length % 4 !== 0) {
-        throw new ValidationError("Witness receipt attachment group is not quadlet aligned.");
-    }
-    return concatBytes(serder.raw, new Counter({
-        code: CtrDexV1.AttachmentGroup,
-        count: atc.length / 4,
-        version: KERI_V1,
-    }).qb64b, atc);
-}
-/**
- * Build one KERIpy-style endpoint `rct` message without an attachment-group
- * wrapper.
- *
- * KERIpy's witness `/receipts` endpoints return `rct + counter + material`
- * directly. KLI's receiptor depends on that exact shape when it re-fans the
- * returned receipt material out to the other witnesses.
- */
-function buildEndpointDetachedReceiptMessage(serder, { wigers = [], cigars = [] }) {
-    const parts = [serder.raw];
-    if (wigers.length > 0) {
-        parts.push(new Counter({
-            code: CtrDexV1.WitnessIdxSigs,
-            count: wigers.length,
-            version: KERI_V1,
-        }).qb64b, ...wigers.map((wiger) => wiger.qb64b));
-    }
-    if (cigars.length > 0) {
-        parts.push(new Counter({
-            code: CtrDexV1.NonTransReceiptCouples,
-            count: cigars.length,
-            version: KERI_V1,
-        }).qb64b, ...cigars.flatMap((cigar) => {
-            const verfer = cigar.verfer;
-            if (!verfer) {
-                throw new ValidationError("Endpoint receipt couple is missing verifier context.");
-            }
-            return [verfer.qb64b, cigar.qb64b];
-        }));
-    }
-    return concatBytes(...parts);
-}
-/** Build one attached `rct` message carrying witness indexed signatures. */
-function buildWitnessReceiptMessage(serder, wigers) {
-    return buildEndpointDetachedReceiptMessage(serder, { wigers });
-}
-/** Inspect one complete receipt; hydrated proof values have no asynchronous lifetime. */
-function inspectReceiptMessage(bytes) {
-    const frames = parseBytes(bytes);
-    if (frames.length !== 1)
-        throw new ValidationError("Expected one witness receipt message.");
-    const envelope = envelopeFromFrame(frames[0], false);
-    return { serder: envelope.serder, wigers: envelope.wigers, cigars: envelope.cigars };
-}
-/** Receipt endpoints return one finite proof; cancellation joins the reader before leaving this operation. */
-function* readResponseBytes(response) {
-    return yield* abortable((signal) => collectBytes(streamBytes(response.body, { signal })));
-}
-/** Sleep for one short polling interval while staying cancellable. */
-function* sleepMs(ms) {
-    yield* action((resolve) => {
-        const timeoutId = setTimeout(() => resolve(undefined), ms);
-        return () => clearTimeout(timeoutId);
-    });
-}
-/** Return the active wire-message habitat or `null` when selection is ambiguous. */
-function cueHab(runtime, serviceHab) {
-    if (serviceHab) {
-        return serviceHab;
-    }
-    const habitats = runtime.hby.habs.values();
-    const first = habitats.next();
-    return first.done || !habitats.next().done ? null : first.value;
-}
-/**
- * Consume a finite runtime cue pass outside Reactor, using the selected habitat.
- *
- * The host keeps mailbox side effects here so synchronous HTTP/TCP route
- * handlers can inspect witness/receipt wire emissions before the outer runtime
- * loop sees them. Returned snapshots copy the initial cue pass; streaming source
- * callbacks consume each emission without collecting the complete response.
- */
-export function* drainWitnessCues(runtime, serviceHab, cues, { deliver = true } = {}) {
-    return yield* finiteWitnessEmissions((consume) => consumeWitnessCues(runtime, serviceHab, cues, deliver, consume));
-}
-/** Copy finite wrapper output and close each actual replay iterator before returning. */
-function finiteWitnessEmissions(process) {
-    return call(function* () {
-        const emissions = [];
-        yield* process(function* (emission) {
-            const messages = [];
-            const source = emission.messages[Symbol.iterator]();
-            let failure;
-            try {
-                while (true) {
-                    const next = source.next();
-                    if (next.done)
-                        break;
-                    const message = next.value;
-                    if (!(message instanceof Uint8Array))
-                        throw new TypeError("Witness output must be binary");
-                    messages.push(new Uint8Array(message));
-                }
-            }
-            catch (error) {
-                failure = { error };
-            }
-            try {
-                source.return?.();
-            }
-            catch (error) {
-                if (failure && failure.error !== error) {
-                    throw new AggregateError([failure.error, error], "Witness output cleanup failed");
-                }
-                throw error;
-            }
-            if (failure)
-                throw failure.error;
-            emissions.push({
-                ...emission,
-                messages,
-                cue: emission.cue.kin === "replay" ? { ...emission.cue, messages } : emission.cue,
-            });
-        });
-        return emissions;
-    });
-}
-/** Transfer a finite source pass, borrowing emissions only through joined callback cleanup outside Reactor. */
-function* consumeWitnessCues(runtime, serviceHab, cues, deliver, consume) {
-    if (cues !== runtime.cues)
-        throw new RangeError("Witness cue drain requires the runtime source deck");
-    const hab = cueHab(runtime, serviceHab);
-    if (!hab) {
-        return;
-    }
-    const count = cues.length;
-    for (let index = 0; index < count; index++) {
-        const more = yield* call(function* () {
-            let emission, prepared = false;
-            if (deliver) {
-                prepared = !cues.empty;
-                const cue = cues.peekHead();
-                if (cue) {
-                    if (cue.kin === "query") {
-                        runtime.querying.enqueueCue(cue, hab);
-                        runtime.querying.observeCue(cue);
-                    }
-                    else
-                        emission = hab.interpretCue(cue);
-                    if (emission?.kind === "wire")
-                        runtime.respondant.enqueueEmission(hab, emission);
-                    else if (emission?.kind === "transport" && emission.cue.kin === "stream") {
-                        runtime.mailboxDirector.retainQueryCue(emission.cue);
-                    }
-                    cues.pull();
-                }
-            }
-            else {
-                const cue = cues.peekHead();
-                if (cue) {
-                    emission = hab.interpretCue(cue);
-                    cues.pull();
-                    prepared = true;
-                }
-            }
-            if (emission)
-                runtime.querying.observeCue(emission.cue);
-            if (!prepared) {
-                return false;
-            }
-            if (emission && consume)
-                yield* consume(emission);
-            return true;
-        });
-        if (deliver) {
-            yield* runtime.querying.deliverOnce();
-            yield* runtime.respondant.process();
-        }
-        if (!more)
-            break;
-    }
-}
-/**
- * Own one witness input and settle each frame before requesting more input.
- * Consume emissions individually, without retaining an aggregate result. The callback
- * borrows emission iterators outside Reactor until consumption and cleanup finish.
- * Source abort and cleanup belong to this input scope.
- * Queued delivery and the callback share one interpretation until both finish.
- */
-export function* processWitnessIngressSource(runtime, serviceHab, source, { local = false, deliver = true } = {}, consume) {
-    yield* call(function* () {
-        const controller = new AbortController();
-        const signal = controller.signal;
-        try {
-            signal.throwIfAborted();
-            const frames = parse(source(signal));
-            let pending;
-            // The earlier resource joins the read after processing children stop.
-            yield* ensure(function* () {
-                try {
-                    if (pending) {
-                        try {
-                            yield* call(() => pending);
-                        }
-                        catch (error) {
-                            rethrowCleanupFailure(error, signal);
-                        }
-                    }
-                }
-                finally {
-                    yield* call(() => frames.return());
-                }
-            });
-            while (true) {
-                signal.throwIfAborted();
-                pending = frames.next();
-                let result;
-                try {
-                    result = yield* call(() => pending);
-                }
-                catch (error) {
-                    pending = undefined;
-                    throw error;
-                }
-                pending = undefined;
-                signal.throwIfAborted();
-                if (result.done)
-                    break;
-                const frame = result.value;
-                yield* runtime.reactor.dispatch(frame, { local, escrows: true });
-                yield* consumeWitnessCues(runtime, serviceHab, runtime.cues, deliver, consume);
-            }
-        }
-        finally {
-            controller.abort();
-        }
-    });
-}
-/**
- * Parse and settle one inbound witness-host payload.
- *
- * This is the witness-host counterpart to generic runtime ingress.
- *
- * Responsibilities:
- * - settle one inbound CESR payload with the correct witness-local semantics
- * - immediately drain the resulting cues through the hosted witness habitat
- * - return those cue emissions so the caller can make any request-scoped
- *   response decision
- *
- * Returned snapshots contain finite wire arrays. Source callbacks instead borrow
- * each emission's iterator through consumption and cleanup.
- *
- * `local=true` is the crucial switch for the witness receipt path: accepted
- * events that list the hosted witness emit `witness` cues instead of ordinary
- * `receipt` cues.
- *
- * Durable routing rule:
- * - TCP witness ingress, witness `/receipts`, and ordinary HTTP root ingress
- *   that targets the hosted witness AID should all reach this seam when the
- *   host is acting as that witness
- * - generic runtime ingress should remain separate for mailbox streaming,
- *   `/ksn` replay publication, and other non-witness-root policies
- */
-export function* processWitnessIngress(runtime, serviceHab, bytes, options = {}) {
-    return yield* finiteWitnessEmissions((consume) => processWitnessIngressSource(runtime, serviceHab, (signal) => chunkBytes(bytes, { signal }), options, consume));
-}
-/** Authorize the hosted witness against the accepted event, retaining pending dependencies in escrow. */
-function witnessReceiptEligibility(serviceHab, serder) {
-    const pre = serder.pre;
-    const said = serder.said;
-    if (!pre || said === null) {
-        return {
-            kind: "reject",
-            message: "Receipted event must expose pre, sn, and said.",
-        };
-    }
-    const acceptedSaid = serder.sn === null ? null : serviceHab.db.kels.getLast(pre, serder.sn);
-    if (!acceptedSaid)
-        return { kind: "escrow" };
-    if (acceptedSaid !== said)
-        return { kind: "reject", message: "Receipted event is not the accepted KEL event." };
-    const witnesses = serviceHab.db.acceptedEventWitnesses(serder);
-    if (!witnesses)
-        return { kind: "escrow" };
-    if (!witnesses.includes(serviceHab.pre)) {
-        return {
-            kind: "reject",
-            message: `${serviceHab.pre} is not an authorized witness for ${pre}:${said}: wits=${JSON.stringify(witnesses)}.`,
-        };
-    }
-    return { kind: "accept", accepted: serder };
-}
-/** Handle the synchronous witness receipt POST policy. */
-export function* witnessReceiptPost(runtime, serviceHab, bytes) {
-    const serder = inspectCesrRequest(bytes);
-    if (!serder) {
-        return { kind: "reject", status: 400, message: "Invalid CESR request" };
-    }
-    if (serder.ilk !== Ilks.icp
-        && serder.ilk !== Ilks.rot
-        && serder.ilk !== Ilks.ixn
-        && serder.ilk !== Ilks.dip
-        && serder.ilk !== Ilks.drt) {
-        return {
-            kind: "reject",
-            status: 400,
-            message: `invalid event type (${serder.ilk}) for receipting`,
-        };
-    }
-    yield* processWitnessIngress(runtime, serviceHab, bytes, {
-        local: true,
-        deliver: false,
-    });
-    const eligibility = witnessReceiptEligibility(serviceHab, serder);
-    if (eligibility.kind === "reject") {
-        return { kind: "reject", status: 400, message: eligibility.message };
-    }
-    if (eligibility.kind === "escrow") {
-        return { kind: "escrow", status: 202 };
-    }
-    const inspected = inspectReceiptMessage(serviceHab.receipt(eligibility.accepted));
-    const body = buildEndpointDetachedReceiptMessage(inspected.serder, {
-        wigers: inspected.wigers,
-        cigars: inspected.cigars,
-    });
-    return { kind: "accepted", status: 200, body };
-}
-/** Handle `GET /receipts` witness retrieval. */
-export function witnessReceiptGet(serviceHab, query) {
-    const pre = query.pre ?? null;
-    if (!pre) {
-        return {
-            kind: "reject",
-            status: 400,
-            message: "query param 'pre' is required",
-        };
-    }
-    let said = query.said ?? null;
-    if (query.sn === null && !said) {
-        return {
-            kind: "reject",
-            status: 400,
-            message: "either 'sn' or 'said' query param is required",
-        };
-    }
-    if (query.sn !== null && query.sn !== undefined) {
-        said = serviceHab.db.kels.getLast(pre, query.sn);
-    }
-    if (!said) {
-        return {
-            kind: "reject",
-            status: 404,
-            message: `event for ${pre} at ${String(query.sn ?? "")} (${String(said)}) not found`,
-        };
-    }
-    const serder = serviceHab.db.getEvtSerder(pre, said);
-    if (!serder) {
-        return {
-            kind: "reject",
-            status: 404,
-            message: `Missing event for dig=${said}.`,
-        };
-    }
-    const wits = serviceHab.db.acceptedEventWitnesses(serder);
-    if (!wits || !wits.includes(serviceHab.pre)) {
-        return {
-            kind: "reject",
-            status: 400,
-            message: `${serviceHab.pre} is not a valid witness for ${pre} event at ${serder.sn}.`,
-        };
-    }
-    const reserder = receiptEvent(pre, serder.sn ?? 0, said);
-    const body = buildWitnessReceiptMessage(reserder, serviceHab.db.wigs.get(dgKey(pre, said)));
-    return { kind: "accepted", status: 200, body };
-}
-/** Handle `GET /query` witness log replay. */
-export function witnessQueryGet(serviceHab, query) {
-    const typ = query.typ ?? null;
-    if (!typ) {
-        return {
-            kind: "reject",
-            status: 400,
-            message: "'typ' query param is required",
-        };
-    }
-    if (typ === "kel") {
-        const pre = query.pre ?? null;
-        if (!pre) {
-            return {
-                kind: "reject",
-                status: 400,
-                message: "'pre' query param is required",
-            };
-        }
-        if (query.sn !== null && query.sn !== undefined) {
-            const first = serviceHab.db.kels.getLast(pre, query.sn);
-            if (!first) {
-                return {
-                    kind: "reject",
-                    status: 400,
-                    message: `non-existent event at seq-num ${query.sn}`,
-                };
-            }
-        }
-        return {
-            kind: "accepted",
-            status: 200,
-            messages: serviceHab.db.witnessReplay(pre, query.sn ?? null) ?? [],
-        };
-    }
-    if (typ === "tel") {
-        return {
-            kind: "reject",
-            status: 501,
-            message: "TEL witness query replay is not yet available in tufa.",
-        };
-    }
-    return {
-        kind: "reject",
-        status: 400,
-        message: "unknown query type.",
-    };
-}
-/** Return the full advertised scheme map for one witness endpoint. */
-function witnessUrls(hab, witness) {
-    return hab.fetchUrls(witness);
-}
-/** Resolve the HTTP or HTTPS witness endpoint when available. */
-function witnessHttpUrl(hab, witness) {
-    const urls = witnessUrls(hab, witness);
-    return urls[Schemes.https] ?? urls[Schemes.http] ?? null;
-}
-/** Resolve the TCP witness endpoint when available. */
-function witnessTcpUrl(hab, witness) {
-    const urls = witnessUrls(hab, witness);
-    return urls[Schemes.tcp] ?? null;
-}
-/** Choose the generic witness transport URL: HTTP first, TCP fallback second. */
-function preferredWitnessTransportUrl(hab, witness) {
-    return witnessHttpUrl(hab, witness) ?? witnessTcpUrl(hab, witness);
-}
-/** Build one `loc/scheme` replay bundle for witness introductions. */
-function witnessSchemeReplies(hab, eids) {
-    const replies = eids
-        .map((eid) => hab.loadLocScheme(eid))
-        .filter((msg) => msg.length > 0);
-    return replies.length === 0 ? new Uint8Array() : concatBytes(...replies);
-}
-/**
- * Send via HTTP first; an explicit Reactor processes same-socket TCP replies.
- * Without a Reactor TCP reports local transmission only. Actual socket/parser
- * cleanup finishes before this borrowed protocol processor can be released.
- */
-export function* sendWitnessMessage(hab, witness, bytes, auth, services, reactor) {
-    const url = preferredWitnessTransportUrl(hab, witness);
-    if (!url) {
-        throw new ValidationError(`Unable to find a valid endpoint for witness ${witness}.`);
-    }
-    const parsed = new URL(url);
-    if (parsed.protocol === "tcp:") {
-        yield* call(function* () {
-            if (reactor) {
-                yield* converseCesrTcp(url, bytes, {
-                    clock: services?.clock,
-                    replies: { reactor, local: true },
-                });
-            }
-            else {
-                yield* sendCesrTcp(url, bytes, { clock: services?.clock });
-            }
-        });
-        return;
-    }
-    yield* postCesr(url, (signal) => chunkBytes(bytes, { signal }), {
-        bodyMode: "header",
-        destination: witness,
-        headers: auth ? { Authorization: auth } : undefined,
-        services: services ?? defaultRuntimeServices,
-    });
-}
-function isKeripyContentTypeRejection(status, contentType, responseText) {
-    return status === 406
-        && contentType === CESR_CONTENT_TYPE
-        && responseText.toLowerCase().includes(KERIPY_CONTENT_TYPE_ERROR);
-}
-/** Poll one witness `GET /receipts` endpoint until the receipt becomes available. */
-function* pollWitnessReceipt(hab, witness, pre, sn, said) {
-    const httpUrl = witnessHttpUrl(hab, witness);
-    if (!httpUrl) {
-        return {
-            kind: "reject",
-            status: 400,
-            message: `Witness ${witness} does not advertise an HTTP(S) endpoint for receipt polling.`,
-        };
-    }
-    for (let attempt = 0; attempt < WitnessReceiptPollAttempts; attempt += 1) {
-        const response = yield* call(() => getWitnessReceiptEndpoint(hab, witness, {
-            pre,
-            sn,
-            said,
-        }));
-        if (response.kind === "accepted") {
-            return response;
-        }
-        if (response.kind === "reject" && response.status !== 404) {
-            return response;
-        }
-        yield* sleepMs(WitnessReceiptPollDelayMs);
-    }
-    return {
-        kind: "reject",
-        status: 408,
-        message: `Timed out waiting for witness receipt from ${witness}.`,
-    };
-}
-/** Request one witness receipt via `POST /receipts`. */
-function* postWitnessReceiptEndpoint(hab, witness, message, auth) {
-    const url = witnessHttpUrl(hab, witness);
-    if (!url) {
-        return {
-            kind: "reject",
-            status: 400,
-            message: `Witness ${witness} does not advertise an HTTP(S) receipt endpoint.`,
-        };
-    }
-    const responseUrl = new URL(url);
-    responseUrl.pathname = `${responseUrl.pathname.replace(/\/+$/, "") || ""}/receipts`;
-    let lastStatus = 0;
-    let lastText = "";
-    for (const contentType of WITNESS_HTTP_CONTENT_TYPES) {
-        const request = buildCesrRequest(message, {
-            contentType,
-            destination: witness,
-        });
-        const { response } = yield* fetchResponseHandle(responseUrl.toString(), {
-            method: "POST",
-            headers: {
-                ...request.headers,
-                ...(auth ? { Authorization: auth } : {}),
-            },
-            body: request.body,
-        });
-        if (response.status === 202) {
-            yield* closeResponseBody(response);
-            return { kind: "escrow", status: 202 };
-        }
-        if (response.status === 200) {
-            const body = yield* readResponseBytes(response);
-            const inspected = inspectReceiptMessage(body);
-            return {
-                kind: "accepted",
-                status: 200,
-                body,
-                wigers: inspected.wigers,
-                cigars: inspected.cigars,
-            };
-        }
-        const body = yield* readResponseBytes(response);
-        lastStatus = response.status;
-        lastText = new TextDecoder().decode(body);
-        if (isKeripyContentTypeRejection(response.status, contentType, lastText)) {
-            continue;
-        }
-        return { kind: "reject", status: response.status, message: lastText };
-    }
-    return {
-        kind: "reject",
-        status: lastStatus,
-        message: lastText,
-    };
-}
-/** Request one stored witness receipt via `GET /receipts`. */
-function* getWitnessReceiptEndpoint(hab, witness, query) {
-    const url = witnessHttpUrl(hab, witness);
-    if (!url) {
-        return {
-            kind: "reject",
-            status: 400,
-            message: `Witness ${witness} does not advertise an HTTP(S) receipt endpoint.`,
-        };
-    }
-    const endpoint = new URL(url);
-    endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, "") || ""}/receipts`;
-    endpoint.searchParams.set("pre", query.pre);
-    if (query.sn !== undefined) {
-        endpoint.searchParams.set("sn", String(query.sn));
-    }
-    if (query.said) {
-        endpoint.searchParams.set("said", query.said);
-    }
-    const { response } = yield* fetchResponseHandle(endpoint.toString(), {
-        method: "GET",
-    });
-    if (response.status !== 200) {
-        const body = yield* readResponseBytes(response);
-        return {
-            kind: "reject",
-            status: response.status,
-            message: new TextDecoder().decode(body),
-        };
-    }
-    const body = yield* readResponseBytes(response);
-    const inspected = inspectReceiptMessage(body);
-    return {
-        kind: "accepted",
-        status: 200,
-        body,
-        wigers: inspected.wigers,
-        cigars: inspected.cigars,
-    };
-}
-/**
- * Controller-side synchronous witness receipt orchestration.
- *
- * Responsibilities:
- * - publish through HTTP receipt endpoints (generic submission opts into TCP reply intake)
- * - catch up newly added witnesses before receipting
- * - persist returned receipts locally through the protocol processor
- * - fan witness receipts out to the complementary witnesses
- */
-export class Receiptor {
-    /** Borrow the protocol processor or create one over the caller's existing Habery; no stores or workers are opened. */
-    constructor(hby, { reactor, services = defaultRuntimeServices } = {}) {
-        Object.defineProperty(this, "hby", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "reactor", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "services", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        if (reactor && reactor.hby !== hby)
-            throw new RangeError("Receiptor Reactor must own the same Habery");
-        this.hby = hby;
-        this.reactor = reactor ?? new Reactor(hby);
-        this.services = services;
-    }
-    /** Submit the latest or specified event to all witnesses and gather receipts. */
-    *receipt(pre, { sn, auths = {}, allowTcp = false } = {}) {
-        return yield* call(() => this.receiptOnce(pre, { sn, auths }, allowTcp));
-    }
-    /** One scoped attempt joins actual receipt HTTP/TCP work before returning. */
-    *receiptOnce(pre, { sn, auths }, allowTcp) {
-        const hab = this.hby.habs.get(pre) ?? null;
-        if (!hab) {
-            throw new ValidationError(`${pre} not a valid local AID.`);
-        }
-        const kever = hab.kever;
-        if (!kever) {
-            throw new ValidationError(`Missing accepted key state for ${pre}.`);
-        }
-        const eventSn = sn ?? kever.sn;
-        const { serder, message } = acceptedEventReplayMessage(this.hby, pre, eventSn);
-        const witnesses = this.hby.db.acceptedEventWitnesses(serder);
-        if (witnesses.length === 0) {
-            return { witnesses: [], statuses: {} };
-        }
-        if (serder.ilk === Ilks.rot || serder.ilk === Ilks.drt) {
-            for (const witness of serder.adds) {
-                yield* this.catchup(pre, witness);
-            }
-        }
-        const receiptGroups = new Map();
-        const statuses = {};
-        const said = serder.said;
-        if (!said) {
-            throw new ValidationError("Local event must expose a SAID before witness receipting.");
-        }
-        for (const witness of witnesses) {
-            if (kever.delegated) {
-                for (const dmsg of this.hby.db.cloneDelegation(kever)) {
-                    yield* sendWitnessMessage(hab, witness, dmsg, undefined, this.services, this.reactor);
-                }
-            }
-            if (allowTcp && !witnessHttpUrl(hab, witness) && witnessTcpUrl(hab, witness)) {
-                yield* sendWitnessMessage(hab, witness, message, undefined, this.services, this.reactor);
-                statuses[witness] = 200;
-            }
-            else {
-                // A single receipt attempt owns its response until parsing and collection finish.
-                let response = yield* call(() => postWitnessReceiptEndpoint(hab, witness, message, auths[witness]));
-                if (response.kind === "escrow") {
-                    response = yield* pollWitnessReceipt(hab, witness, pre, eventSn, said);
-                }
-                statuses[witness] = response.status;
-                if (response.kind !== "accepted") {
-                    const detail = response.kind === "reject" ? response.message : "receipt remained escrowed";
-                    throw new ValidationError(`Witness ${witness} failed to receipt ${pre}:${eventSn.toString(16)}: ${detail}`);
-                }
-                yield* this.reactor.processBytes(response.body, { local: false });
-                yield* this.reactor.processEscrowsOnce();
-            }
-            // HTTP status and socket drain are transport facts; only accepted witness proof counts.
-            const index = witnesses.indexOf(witness);
-            const wigers = this.hby.db.wigs.get(dgKey(pre, said)).filter((siger) => siger.index === index);
-            if (wigers.length === 0) {
-                throw new ValidationError(`Witness ${witness} did not receipt ${pre}:${eventSn.toString(16)}.`);
-            }
-            receiptGroups.set(witness, wigers);
-        }
-        for (const witness of witnesses) {
-            const otherWigers = [...receiptGroups.entries()]
-                .flatMap(([current, wigers]) => current === witness ? [] : [...wigers]);
-            if (otherWigers.length === 0) {
-                continue;
-            }
-            const introWitnesses = witnesses.filter((current) => current !== witness && receiptGroups.has(current));
-            const parts = [];
-            if (serder.ilk === Ilks.icp
-                || serder.ilk === Ilks.dip
-                || ((serder.ilk === Ilks.rot || serder.ilk === Ilks.drt)
-                    && serder.adds.includes(witness))) {
-                const schemes = witnessSchemeReplies(hab, introWitnesses);
-                if (schemes.length > 0) {
-                    parts.push(schemes);
-                }
-            }
-            parts.push(buildDetachedReceiptMessage(receiptEvent(pre, eventSn, said), { wigers: otherWigers }));
-            yield* sendWitnessMessage(hab, witness, concatBytes(...parts), undefined, this.services, this.reactor);
-        }
-        return { witnesses, statuses };
-    }
-    /** Query a stored witness receipt and apply it to local state when found. */
-    *get(pre, { sn, said } = {}) {
-        const hab = this.hby.habs.get(pre) ?? null;
-        if (!hab) {
-            throw new ValidationError(`${pre} not a valid local AID.`);
-        }
-        const kever = hab.kever;
-        if (!kever) {
-            throw new ValidationError(`Missing accepted key state for ${pre}.`);
-        }
-        const eventSn = sn ?? kever.sn;
-        const knownSaid = this.hby.db.kels.getLast(pre, eventSn);
-        const known = knownSaid ? this.hby.db.getEvtSerder(pre, knownSaid) : null;
-        const witnesses = known ? this.hby.db.acceptedEventWitnesses(known) : kever.wits;
-        const witness = [...witnesses].sort()[0];
-        if (!witness) {
-            return false;
-        }
-        const response = yield* call(() => getWitnessReceiptEndpoint(hab, witness, { pre, sn: eventSn, said }));
-        if (response.kind !== "accepted") {
-            return false;
-        }
-        yield* this.reactor.processBytes(response.body, { local: false });
-        yield* this.reactor.processEscrowsOnce();
-        const expectedSaid = this.hby.db.kels.getLast(pre, eventSn);
-        const accepted = expectedSaid ? this.hby.db.getEvtSerder(pre, expectedSaid) : null;
-        const index = accepted ? this.hby.db.acceptedEventWitnesses(accepted)?.indexOf(witness) : -1;
-        return !!expectedSaid && (said === undefined || said === expectedSaid)
-            && this.hby.db.wigs.get(dgKey(pre, expectedSaid)).some((siger) => siger.index === index);
-    }
-    /** Catch one witness up through the same protocol processor used for receipt intake. */
-    *catchup(pre, witness) {
-        const hab = this.hby.habs.get(pre) ?? null;
-        if (!hab) {
-            throw new ValidationError(`${pre} not a valid local AID.`);
-        }
-        const kever = hab.kever;
-        if (kever?.delegated) {
-            for (const msg of this.hby.db.cloneDelegation(kever)) {
-                yield* sendWitnessMessage(hab, witness, msg, undefined, this.services, this.reactor);
-            }
-        }
-        for (const msg of this.hby.db.clonePreIter(pre)) {
-            yield* sendWitnessMessage(hab, witness, msg, undefined, this.services, this.reactor);
-        }
-    }
-}
-/**
- * Higher-level full witness submission helper.
- *
- * HTTP uses finite receipt endpoints; TCP uses same-socket local reply intake
- * and requires the requested witness signature to be persisted before fanout.
- */
-export class WitnessReceiptor {
-    constructor(hby, { force = false, reactor, services } = {}) {
-        Object.defineProperty(this, "receiptor", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "hby", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "force", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.hby = hby;
-        this.force = force;
-        this.receiptor = new Receiptor(hby, { reactor, services });
-    }
-    /** Ensure the current event reaches full witness receipt convergence. */
-    *submit(pre, { sn, auths = {} } = {}) {
-        const hab = this.hby.habs.get(pre) ?? null;
-        if (!hab) {
-            throw new ValidationError(`${pre} not a valid local AID.`);
-        }
-        const kever = hab.kever;
-        if (!kever) {
-            throw new ValidationError(`Missing accepted key state for ${pre}.`);
-        }
-        const eventSn = sn ?? kever.sn;
-        const { serder } = acceptedEventReplayMessage(this.hby, pre, eventSn);
-        const witnesses = this.hby.db.acceptedEventWitnesses(serder);
-        const currentWitnessCount = this.hby.db.wigs.get(dgKey(pre, serder.said)).length;
-        if (!this.force && currentWitnessCount >= witnesses.length) {
-            const statuses = Object.fromEntries(witnesses.map((witness) => [witness, 200]));
-            return { witnesses, statuses };
-        }
-        return yield* this.receiptor.receipt(pre, { sn: eventSn, auths, allowTcp: true });
-    }
-}
-/** Return an actual signed KERI reply; unknown or incompletely witnessed state is not advertised. */
-export function witnessKeyStateGet(serviceHab, query) {
-    if (!query.destination || query.destination !== serviceHab.pre) {
-        return { kind: "reject", status: 400, message: "Recognized CESR destination required" };
-    }
-    if (!query.pre)
-        return { kind: "reject", status: 400, message: "'pre' query param is required" };
-    const kever = serviceHab.db.getKever(query.pre, { refresh: true });
-    if (!kever || !serviceHab.db.fullyWitnessed(kever.serder)) {
-        return { kind: "reject", status: 404, message: "Fully witnessed key state not found" };
-    }
-    return {
-        kind: "accepted",
-        status: 200,
-        body: serviceHab.endorse(replyEvent(`/ksn/${serviceHab.pre}`, kever.state().asDict())),
-    };
-}