keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/app/cue-preparation.js

@@ -1,124 +0,0 @@
-/** Synchronous admitted cue interpretation; destination owners provide retention and joined delivery. */
-import { ResourceAdmissionError, ResourceLimitError } from "cesr-ts";
-import { CueDeck, reserveCueBytes } from "../core/cue-admission.js";
-// Local finite policy matches RuntimeDeliveries' 8 MiB retained wire plus 24 MiB preparation allowance.
-const wireBytes = 8 * 1024 ** 2, preparationBytes = 3 * wireBytes;
-/**
- * Caller preflights its existing destination item slot under the guard. Accept must
- * immediately and atomically retain this owner, or throw without publishing it;
- * async acceptance, source mutation and early release are forbidden. Optional local
- * transformation runs within preparation credit and the final finite output check.
- * Failed preparation leaves the original cue/credit
- * available for retry. Replay metadata stays borrowed and unopened, never collected.
- * This is logical copy/retention allowance, not a decoded/capture/native allocation bound.
- */
-export function prepareCueEmission(hab, cues, resources, accept, onAdmissionRefusal, transformEmission) {
-    const cue = cues.peekHead();
-    if (!cue)
-        return false;
-    if (cues instanceof CueDeck && cues.resourcePolicy !== resources) {
-        throw new RangeError("Cue interpretation requires the source deck's exact policy");
-    }
-    const refuse = (error) => {
-        onAdmissionRefusal?.(error);
-        throw error;
-    };
-    const heldInput = cues instanceof CueDeck ? cues.headRetentionBytes() : 0;
-    if (heldInput + wireBytes + preparationBytes > resources.limits.bytes) {
-        refuse(new ResourceAdmissionError("Cue interpretation exceeds shared byte capacity", "limit"));
-    }
-    let input, output;
-    let preparation, original;
-    let inputBytes = heldInput;
-    let published = false, live = true;
-    let emission;
-    try {
-        if (!(cues instanceof CueDeck)) {
-            const before = resources.used.bytes;
-            input = reserveCueBytes(resources, [cue], undefined, onAdmissionRefusal);
-            inputBytes = resources.used.bytes - before;
-            // Synchronous inspection has no yield; classify this operation's own combined floor before contention.
-            if (resources.used.bytes - before + wireBytes + preparationBytes > resources.limits.bytes) {
-                refuse(new ResourceAdmissionError("Cue retention and interpretation exceed shared capacity", "limit"));
-            }
-        }
-        const retained = resources.reserve({ bytes: wireBytes });
-        if (retained.kind === "refuse")
-            refuse(new ResourceAdmissionError("Cue output admission refused", retained.reason));
-        output = retained.reservation;
-        const temporary = resources.reserve({ bytes: preparationBytes });
-        if (temporary.kind === "refuse") {
-            refuse(new ResourceAdmissionError("Cue interpretation admission refused", temporary.reason));
-        }
-        preparation = temporary.reservation;
-        if (cues instanceof CueDeck)
-            original = cues.takeOwned();
-        emission = hab ? hab.interpretCue(cue) : {
-            cue,
-            messages: [],
-            kind: cue.kin === "stream" ? "transport" : "notify",
-        };
-        if (emission && transformEmission)
-            emission = transformEmission(emission);
-        if (emission && Array.isArray(emission.messages)) {
-            const backing = new Set();
-            let size = 0;
-            for (let index = 0; index < emission.messages.length; index++) {
-                const message = emission.messages[index];
-                if (!(message instanceof Uint8Array))
-                    throw new TypeError("Cue output must be binary");
-                if (!backing.has(message.buffer)) {
-                    backing.add(message.buffer);
-                    size += message.buffer.byteLength;
-                }
-            }
-            if (size > wireBytes)
-                throw new ResourceLimitError("Cue output exceeds finite interpretation limit");
-        }
-        const owner = {
-            retainedBytes: inputBytes + wireBytes,
-            resourcePolicy: resources,
-            get emission() {
-                if (!live)
-                    throw new Error("Cue emission owner is released");
-                return emission;
-            },
-            release() {
-                if (!live)
-                    return;
-                if (!published)
-                    throw new Error("Cue emission has not transferred");
-                live = false;
-                emission = undefined;
-                original?.release();
-                input?.release();
-                output.release();
-            },
-        };
-        const accepted = accept(owner);
-        if (accepted !== undefined)
-            throw new TypeError("Cue acceptance must be synchronous and return void");
-        if (!(cues instanceof CueDeck)) {
-            if (cues.peekHead() !== cue)
-                throw new Error("Cue head changed during acceptance");
-            cues.pull();
-        }
-        published = true;
-        return true;
-    }
-    finally {
-        preparation?.release();
-        if (!published) {
-            live = false;
-            emission = undefined;
-            try {
-                if (original && cues instanceof CueDeck)
-                    cues.requeue(original);
-            }
-            finally {
-                input?.release();
-                output?.release();
-            }
-        }
-    }
-}

package/esm/keri/npm/src/app/cue-route.js

@@ -1,64 +0,0 @@
-/** Finite synchronous route capture; transfer its credit into the existing delivery owner. */
-import { ResourceAdmissionError, ResourceLimitError } from "cesr-ts";
-const routeBytes = 1024 ** 2, interpretationBytes = 24 * 1024 ** 2;
-/** Borrow captured routing only while its independent metadata credit remains live. */
-export class PreparedCueRoute {
-    constructor(value, credit) {
-        Object.defineProperty(this, "value", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: value
-        });
-        Object.defineProperty(this, "credit", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: credit
-        });
-    }
-    get route() {
-        if (!this.value)
-            throw new Error("Cue route owner is released");
-        return this.value;
-    }
-    release() {
-        this.value = undefined;
-        this.credit.release();
-    }
-}
-/**
- * Borrow the live cue owner's exact policy under its synchronous guarded turn.
- * Admit metadata before endpoint resolution; never open replay or wait here.
- * This finite logical allowance does not qualify native/decoded row allocations.
- */
-export function prepareCueRoute(resources, owner, resolve, onAdmissionRefusal) {
-    const refuse = (error) => {
-        onAdmissionRefusal?.(error);
-        throw error;
-    };
-    void owner.emission;
-    if (owner.resourcePolicy !== resources)
-        throw new RangeError("Cue route requires the owner's exact policy");
-    if (owner.retainedBytes + interpretationBytes + routeBytes > resources.limits.bytes) {
-        refuse(new ResourceAdmissionError("Cue route retention exceeds shared capacity", "limit"));
-    }
-    const admitted = resources.reserve({ bytes: routeBytes });
-    if (admitted.kind === "refuse")
-        refuse(new ResourceAdmissionError("Cue routes are busy", admitted.reason));
-    try {
-        const route = resolve();
-        let size = 2 * (route.sender.length + route.recipient.length + route.topic.length);
-        if (route.targets.length > 4096)
-            throw new ResourceLimitError("Cue target count exceeds limit");
-        for (const target of route.targets)
-            size += 128 + 2 * (target.eid.length + target.url.length);
-        if (size > routeBytes)
-            throw new ResourceLimitError("Cue route metadata exceeds limit");
-        return new PreparedCueRoute(route, admitted.reservation);
-    }
-    catch (error) {
-        admitted.reservation.release();
-        throw error;
-    }
-}

package/esm/keri/npm/src/app/cue-runtime.js

@@ -1,104 +0,0 @@
-import { call, resource } from "effection";
-import { prepareCueEmission } from "./cue-preparation.js";
-import { runtimeTurn } from "./runtime-turn.js";
-function* ignoreEmission(_emission) {
-    return;
-}
-/** Default cue sink used when the host does not care about cue side effects. */
-export const ignoreCueSink = { send: ignoreEmission };
-/**
- * Resolve the habitat used to interpret habitat-owned cue semantics.
- *
- * Rule:
- * - prefer an explicitly supplied habitat
- * - otherwise use the sole local habitat when the habery owns exactly one
- * - otherwise return `null` so the runtime can preserve the cue as a host
- *   notification without guessing which local habitat should sign for it
- */
-function resolveCueHab(runtime, hab) {
-    if (hab) {
-        return hab;
-    }
-    const habitats = runtime.hby.habs.values();
-    const first = habitats.next();
-    return first.done || !habitats.next().done ? null : first.value;
-}
-/**
- * Drain one bounded cue-processing pass for a shared runtime host.
- *
- * Eligible sinks immediately transfer admitted work before source removal.
- * Ineligible/custom cues acquire independent input/output ownership in a short turn;
- * sink waits run outside the guard and retain ownership through joined cleanup.
- * Only the initial bounded batch is drained. When no habitat can be resolved, cues are still
- * surfaced to the host as notify/transport emissions instead of being dropped.
- */
-export function processCuesOnce(runtime, { hab, sink = ignoreCueSink, onAdmissionRefusal, } = {}) {
-    return call(function* () {
-        let cueHab = null, count = 0;
-        yield* runtime.reactor.settle(undefined, {}, function* () {
-            cueHab = resolveCueHab(runtime, hab);
-            count = runtime.cues.length;
-        });
-        for (let index = 0; index < count; index++) {
-            const more = yield* call(function* () {
-                let owner;
-                // Register before the sink's children: reverse teardown joins them before releasing retained evidence.
-                yield* resource(function* (provide) {
-                    try {
-                        yield* provide();
-                    }
-                    finally {
-                        owner?.release();
-                    }
-                });
-                const result = { admission: "ineligible" };
-                let refused;
-                try {
-                    yield* runtime.reactor.settle(undefined, {}, function* () {
-                        result.admission = sink.admitCue?.(runtime, cueHab) ?? "ineligible";
-                        if (result.admission === "transferred" || result.admission === "busy")
-                            return;
-                        if (result.admission !== "ineligible")
-                            throw new TypeError("Invalid immediate cue admission");
-                        prepareCueEmission(cueHab, runtime.cues, runtime.resources, (prepared) => {
-                            owner = prepared;
-                            return undefined;
-                        }, (error) => {
-                            refused = { error };
-                            onAdmissionRefusal?.(error);
-                        }, (emission) => sink.prepareEmission?.(emission) ?? emission);
-                    });
-                    if (result.admission === "busy")
-                        return false;
-                    if (result.admission === "transferred")
-                        return true;
-                    if (!owner)
-                        return false;
-                    const emission = owner.emission;
-                    if (emission)
-                        yield* (sink.sendPrepared ?? sink.send).call(sink, emission);
-                    return true;
-                }
-                catch (error) {
-                    if (refused && refused.error === error && refused.error.reason === "busy")
-                        return false;
-                    throw error;
-                }
-            });
-            if (!more)
-                break;
-        }
-    });
-}
-/**
- * Continuous cue doer for long-lived runtime hosts.
- *
- * This is the Effection analogue of the KERIpy `cueDo` loop: interpret any
- * pending cues, hand them to the host sink, yield, and repeat forever.
- */
-export function* cueDo(runtime, options = {}) {
-    while (true) {
-        yield* processCuesOnce(runtime, options);
-        yield* runtimeTurn();
-    }
-}

package/esm/keri/npm/src/app/direct-reply-delivery.js

@@ -1,282 +0,0 @@
-/** One interpreted reply batch owned by delivery and a borrowed HTTP/witness consumer until both close. */
-import { ResourceAdmissionError } from "cesr-ts";
-import { reserveCueBytes } from "../core/cue-admission.js";
-import { Deck } from "../core/deck.js";
-import { CueDelivery } from "./cue-delivery.js";
-import { prepareCueEmission } from "./cue-preparation.js";
-import { prepareCueRoute } from "./cue-route.js";
-/** Queue-only or two-consumer reply lifetime; consumers cannot retain bytes after cleanup. */
-export class DirectReplyDelivery {
-    constructor() {
-        Object.defineProperty(this, "index", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: 0
-        });
-        Object.defineProperty(this, "borrowDone", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "deliveryDone", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "published", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "owners", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
-        Object.defineProperty(this, "routes", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
-        Object.defineProperty(this, "deliveries", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
-        Object.defineProperty(this, "releaseInput", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-    }
-    /** All acquisition/publication is synchronous under the guard; no replay reader opens here. */
-    static prepare(runtime, hab, reply, publish, onAdmissionRefusal) {
-        return this.prepareBatch(runtime, hab, reply, publish, undefined, onAdmissionRefusal);
-    }
-    /** Transfer an earlier query batch to delivery only, without reserving an HTTP response permit. */
-    static prepareQueued(runtime, hab, reply, accept, onAdmissionRefusal) {
-        let transferred = false;
-        this.prepareBatch(runtime, hab, reply, undefined, (delivery) => {
-            accept(delivery);
-            transferred = true;
-        }, onAdmissionRefusal);
-        return transferred;
-    }
-    /** Share one admitted cue between queued targets and a scoped witness consumer; neither reinterprets it. */
-    static prepareCue(runtime, hab, cues, resolve, accept, onAdmissionRefusal) {
-        const batch = new DirectReplyDelivery();
-        try {
-            const prepared = prepareCueEmission(hab, cues, runtime.resources, (owner) => {
-                batch.owners.push(owner);
-                if (owner.emission?.kind === "wire") {
-                    const route = prepareCueRoute(runtime.resources, owner, () => resolve(owner.emission) ?? {
-                        sender: hab.pre,
-                        recipient: "",
-                        topic: "",
-                        bodyMode: runtime.hby.cesrBodyMode,
-                        kind: "direct",
-                        targets: [],
-                    }, onAdmissionRefusal);
-                    batch.routes.push(route);
-                    if (route.route.targets.length) {
-                        batch.deliveries.push(new CueDelivery({
-                            get emission() {
-                                return owner.emission;
-                            },
-                            retainedBytes: owner.retainedBytes,
-                            resourcePolicy: owner.resourcePolicy,
-                            release() { },
-                        }, runtime.hby.habs.get(route.route.sender) ?? hab, route));
-                    }
-                }
-                let live = true;
-                accept(batch, {
-                    get emission() {
-                        if (!live)
-                            throw new Error("Witness cue borrow is released");
-                        return owner.emission;
-                    },
-                    retainedBytes: owner.retainedBytes,
-                    resourcePolicy: owner.resourcePolicy,
-                    release() {
-                        if (!live)
-                            return;
-                        live = false;
-                        batch.closeBorrow();
-                    },
-                });
-                return undefined;
-            }, onAdmissionRefusal);
-            batch.published = prepared;
-            batch.finish([]);
-            return prepared;
-        }
-        finally {
-            if (!batch.published)
-                for (const route of batch.routes)
-                    route.release();
-        }
-    }
-    /** One atomic wire preparation serves either queue-only delivery or the existing two consumers. */
-    static prepareBatch(runtime, hab, reply, publish, enqueue, onAdmissionRefusal) {
-        const batch = new DirectReplyDelivery();
-        batch.borrowDone = !publish;
-        const responseBytes = publish ? runtime.replyStreams.preparationByteFloor : 0;
-        let stream = null;
-        try {
-            reply.admit((cues, release) => {
-                batch.releaseInput = release;
-                const before = runtime.resources.used.bytes;
-                const input = reserveCueBytes(runtime.resources, cues, undefined, onAdmissionRefusal, {
-                    additionalBytes: reply.retainedBytes + responseBytes
-                        + cues.length * 33 * 1024 ** 2,
-                    maxBytes: 8 * 1024 ** 2,
-                });
-                let response;
-                try {
-                    // One synchronous combined preflight guarantees all internal acquisitions before signing.
-                    const combined = runtime.resources.reserve({
-                        streams: publish ? 1 : 0,
-                        bytes: responseBytes + cues.length * 33 * 1024 ** 2
-                            + 2 * (runtime.resources.used.bytes - before),
-                    });
-                    if (combined.kind === "refuse") {
-                        const refusal = new ResourceAdmissionError("Direct reply preparation refused", combined.reason);
-                        onAdmissionRefusal?.(refusal);
-                        throw refusal;
-                    }
-                    combined.reservation.release();
-                    if (publish)
-                        response = runtime.replyStreams.prepare(onAdmissionRefusal);
-                    const prepare = (index) => {
-                        if (index === cues.length) {
-                            if (publish) {
-                                stream = publish(batch, () => response.open({
-                                    *[Symbol.iterator]() {
-                                        for (const owner of batch.owners)
-                                            yield* owner.emission.messages;
-                                    },
-                                }, () => batch.closeBorrow()));
-                            }
-                            else
-                                enqueue(batch);
-                            batch.published = true;
-                            return;
-                        }
-                        prepareCueEmission(hab, new Deck([cues[index]]), runtime.resources, (owner) => {
-                            if (owner.emission?.kind !== "wire")
-                                throw new RangeError("Direct reply requires wire");
-                            batch.owners.push(owner);
-                            const route = prepareCueRoute(runtime.resources, owner, () => {
-                                const cue = owner.emission.cue;
-                                const sender = ("src" in cue && cue.src ? runtime.hby.habs.get(cue.src) : undefined) ?? hab;
-                                return ("dest" in cue && cue.dest
-                                    ? runtime.poster.findBytesRoute(sender, {
-                                        recipient: cue.dest,
-                                        recipientIsPrefix: true,
-                                        topic: cue.kin === "replay" ? "/replay" : "/reply",
-                                    })
-                                    : null)
-                                    ?? {
-                                        sender: sender.pre,
-                                        recipient: "",
-                                        topic: "",
-                                        bodyMode: runtime.hby.cesrBodyMode,
-                                        kind: "direct",
-                                        targets: [],
-                                    };
-                            }, onAdmissionRefusal);
-                            batch.routes.push(route);
-                            if (route.route.targets.length) {
-                                const sender = runtime.hby.habs.get(route.route.sender) ?? hab;
-                                batch.deliveries.push(new CueDelivery({
-                                    get emission() {
-                                        return owner.emission;
-                                    },
-                                    retainedBytes: owner.retainedBytes,
-                                    resourcePolicy: owner.resourcePolicy,
-                                    release() { },
-                                }, sender, route));
-                            }
-                            prepare(index + 1);
-                            return undefined;
-                        }, onAdmissionRefusal);
-                    };
-                    prepare(0);
-                }
-                finally {
-                    response?.release();
-                    input.release();
-                }
-                return undefined;
-            });
-            // Queue-only no-target cleanup must wait until every nested preparation and the reply slot transfer finish.
-            batch.finish([]);
-            return stream;
-        }
-        finally {
-            if (!batch.published)
-                for (const route of batch.routes)
-                    route.release();
-        }
-    }
-    get hasTargets() {
-        return this.deliveries.length > 0;
-    }
-    /** One target per pass, preserving the queue's bounded sibling fairness and exact failed packets. */
-    *step(runtime, signal, retainFailed) {
-        const current = this.deliveries[this.index];
-        if (!current)
-            return "done";
-        const result = yield* current.step(runtime, signal, retainFailed);
-        if (result === "done") {
-            this.index++;
-            return "more";
-        }
-        return result;
-    }
-    /** Queue cleanup joins network before marking its half complete; attempt every independent owner. */
-    release() {
-        if (this.deliveryDone)
-            return;
-        this.deliveryDone = true;
-        const cleanups = this.deliveries.map((delivery) => () => delivery.release());
-        this.deliveries.length = 0;
-        this.finish(cleanups);
-    }
-    closeBorrow() {
-        this.borrowDone = true;
-        if (this.published)
-            this.finish([]);
-    }
-    finish(cleanups) {
-        if (this.published && this.borrowDone && this.deliveryDone) {
-            const releaseInput = this.releaseInput;
-            cleanups.push(...this.routes.map((route) => () => route.release()), ...this.owners.map((owner) => () => owner.release()), () => releaseInput?.());
-            this.routes.length = this.owners.length = 0;
-            this.releaseInput = undefined;
-        }
-        const errors = [];
-        for (const cleanup of cleanups) {
-            try {
-                cleanup();
-            }
-            catch (error) {
-                if (!errors.includes(error))
-                    errors.push(error);
-            }
-        }
-        if (errors.length === 1)
-            throw errors[0];
-        if (errors.length)
-            throw new AggregateError(errors, "Direct reply cleanup failed");
-    }
-}