@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/mods/kernel/receive.js

@@ -0,0 +1,188 @@
+export const RECEIPT_FAULTS = Object.freeze(["proxy", "accessor", "hidden", "getter-threw", "prototype-moved", "not-data", "cycle", "too-deep", "uncopyable"]);
+export function isPlainRecord(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+function isOrdinaryArray(v) {
+    return Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype;
+}
+export function receive(value, mode, held) {
+    const seen = new Map();
+    const path = [];
+    const open = new Set();
+    const heights = new Map();
+    const faults = [];
+    const refusedAt = new Map();
+    const stack = [];
+    const refusals = new Set();
+    const refuse = (kind) => {
+        const fault = Object.freeze({ kind, path: Object.freeze([...path]) });
+        refusals.add(fault);
+        throw fault;
+    };
+    const faultOf = (err) => typeof err === "object" && err !== null && refusals.has(err) ? err : Object.freeze({ kind: "uncopyable", path: Object.freeze([...path]) });
+    const other = (v, kind) => (mode.others === "as-is" ? v : refuse(kind));
+    const refuseContainer = (v, kind) => {
+        if (mode.contain === true) {
+            refusedAt.set(v, kind);
+            open.delete(v);
+        }
+        return refuse(kind);
+    };
+    const memberOf = (v, d) => {
+        if (Object.hasOwn(d, "value")) {
+            if (mode.accessors === "refuse" && d.enumerable !== true)
+                refuse("hidden");
+            return d.value;
+        }
+        if (mode.accessors === "refuse")
+            refuse("accessor");
+        const get = Object.hasOwn(d, "get") ? d.get : undefined;
+        try {
+            return get === undefined ? undefined : Reflect.apply(get, v, []);
+        }
+        catch {
+            return refuse("getter-threw");
+        }
+    };
+    const measured = mode.past === "refuse" || mode.others !== "as-is";
+    const heightOf = (v) => heights.get(v) ?? (open.has(v) || (held?.has(v) === true && mode.isProxy?.(v) !== true && (isOrdinaryArray(v) || isPlainRecord(v))) ? 1 : 0);
+    const pastDepth = (v, level) => measured && level + heightOf(v) > mode.depth;
+    const meet = (v, level) => {
+        if (v === null || v === undefined || typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+            return v;
+        if (typeof v !== "object")
+            return other(v, "not-data");
+        if (held?.has(v) === true)
+            return pastDepth(v, level) ? refuse("too-deep") : v;
+        if (seen.has(v)) {
+            if (refusedAt.has(v))
+                return refuse(refusedAt.get(v));
+            if (open.has(v) && mode.others !== "as-is")
+                return refuse("cycle");
+            return pastDepth(v, level) ? refuse("too-deep") : seen.get(v);
+        }
+        if (level >= mode.depth && mode.past === "refuse") {
+            if (mode.isProxy?.(v) === true)
+                return refuse("proxy");
+            if (isOrdinaryArray(v) || isPlainRecord(v))
+                return refuse("too-deep");
+        }
+        if (level >= mode.depth)
+            return other(v, "too-deep");
+        if (mode.isProxy?.(v) === true)
+            return refuse("proxy");
+        const list = isOrdinaryArray(v) || (mode.others === "copy" && Array.isArray(v));
+        if (!list && !isPlainRecord(v) && mode.others !== "copy")
+            return other(v, "not-data");
+        const proto = Object.getPrototypeOf(v);
+        const captured = Object.getOwnPropertyDescriptors(v);
+        const out = list ? [] : {};
+        seen.set(v, out);
+        open.add(v);
+        if (mode.accessors === "refuse" && Object.getOwnPropertySymbols(captured).length > 0)
+            refuseContainer(v, "hidden");
+        stack.push({ v, out, list, proto, captured, keys: Object.getOwnPropertyNames(captured), level, next: 0, height: 1, key: "", member: undefined });
+        return out;
+    };
+    const land = (f, key, copy, member) => {
+        if (measured && typeof member === "object" && member !== null)
+            f.height = Math.max(f.height, heightOf(member) + 1);
+        Object.defineProperty(f.out, key, { value: copy, enumerable: true, writable: true, configurable: true });
+        path.length = f.level;
+    };
+    const finish = (f) => {
+        heights.set(f.v, f.height);
+        if (mode.accessors === "call-once" && mode.others !== "copy" && Object.getPrototypeOf(f.v) !== f.proto)
+            refuseContainer(f.v, "prototype-moved");
+        if (Array.isArray(f.out)) {
+            const length = f.captured["length"]?.value;
+            if (typeof length === "number")
+                f.out.length = length;
+        }
+        if (mode.freeze === true)
+            Object.freeze(f.out);
+        open.delete(f.v);
+        return f.out;
+    };
+    const received = (copy) => (mode.contain === true ? { ok: true, value: copy, faults: Object.freeze(faults) } : { ok: true, value: copy });
+    try {
+        const copy = meet(value, 0);
+        if (stack.length === 0)
+            return received(copy);
+    }
+    catch (err) {
+        return { ok: false, fault: faultOf(err) };
+    }
+    for (;;) {
+        const f = stack[stack.length - 1];
+        if (f.next < f.keys.length) {
+            const key = f.keys[f.next++];
+            if (f.list && key === "length")
+                continue;
+            path.push(key);
+            try {
+                const member = memberOf(f.v, f.captured[key]);
+                const frames = stack.length;
+                const copy = meet(member, f.level + 1);
+                if (stack.length > frames) {
+                    f.key = key;
+                    f.member = member;
+                }
+                else
+                    land(f, key, copy, member);
+            }
+            catch (err) {
+                if (mode.contain !== true)
+                    return { ok: false, fault: faultOf(err) };
+                faults.push(faultOf(err));
+                path.length = f.level;
+            }
+            continue;
+        }
+        let copy;
+        try {
+            copy = finish(f);
+        }
+        catch (err) {
+            stack.pop();
+            const holder = stack[stack.length - 1];
+            if (mode.contain !== true || holder === undefined)
+                return { ok: false, fault: faultOf(err) };
+            faults.push(faultOf(err));
+            path.length = holder.level;
+            continue;
+        }
+        stack.pop();
+        const holder = stack[stack.length - 1];
+        if (holder === undefined)
+            return received(copy);
+        land(holder, holder.key, copy, holder.member);
+    }
+}
+export const MODS_PAYLOAD_MODE = Object.freeze({ accessors: "refuse", depth: Infinity, others: "as-is", freeze: true });
+export function describeFault(fault) {
+    const at = fault.path.length > 0 ? ` at ${fault.path.join(".")}` : "";
+    switch (fault.kind) {
+        case "proxy":
+            return `a Proxy${at}`;
+        case "accessor":
+            return `an accessor${at} (a getter is never run)`;
+        case "hidden":
+            return `a member that is not an enumerable data property${at}`;
+        case "getter-threw":
+            return `a getter that threw${at}`;
+        case "prototype-moved":
+            return `a prototype that moved while it was read${at}`;
+        case "not-data":
+            return `a value that is not data${at}`;
+        case "cycle":
+            return `a cycle${at}`;
+        case "too-deep":
+            return `a value nested too deep${at}`;
+        case "uncopyable":
+            return `a value that could not be copied whole${at}`;
+    }
+}

package/dist/core/mods/kernel/registration.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The registration form, the two seats, and the screen every registration passes before admission:
+ * shape, unique name, the seat × tier table, the `uses` declaration, and the `budgetMs` fallback.
+ */
+import { type ModBusSide, type ModEventName, type ModRegistrationTier, type ModSeat, type ModTier } from "./events.js";
+import { type ModBudgetReading } from "./budget.js";
+import type { ModEventPayload, ModFailureCause, ModMatcher, ModSkip } from "./site-rules.js";
+/** The configuration refusal: a registration the kernel cannot take refuses the whole prepare. */
+export declare const MODS_INVALID_CODE = "config.mods_invalid";
+/** The notice an admission refusal becomes (the run goes on without the refused registration). */
+export declare const MODS_REGISTRATION_REFUSED_CODE = "mods.registration_refused";
+/** What a registration declares it will touch — the upper bound the kernel holds it to. */
+export interface ModUses {
+    /** Events it hangs handlers on (names or `<prefix>.*`). */
+    readonly events: readonly string[];
+    /** `$` methods it calls (method event names). */
+    readonly calls: readonly string[];
+}
+/** Who raised a dispatch: a registration (through its `$`), or the engine (`{plugin: "engine", tier: "core"}`). */
+export interface ModOrigin {
+    readonly plugin: string;
+    readonly tier: ModTier;
+}
+/** The engine's own origin; its `plugin` word is reserved (no registration may take it). */
+export declare const ENGINE_ORIGIN: ModOrigin;
+/** The facts `$.plugin` carries. */
+export interface ModPluginFacts {
+    readonly name: string;
+}
+/** The part of `$` every bus gives; each side adds its methods (`$.<noun>.<method>`). */
+export interface ModDollarBase {
+    readonly plugin: ModPluginFacts;
+}
+/** One entry of `next.trace`: a handler (or the core) that ran beneath, and how it ended. */
+export interface ModTraceEntry {
+    readonly index: number;
+    readonly plugin: string;
+    readonly tier: ModTier;
+    readonly outcome: ModTraceOutcome;
+    readonly ms: number;
+}
+/** How a chain member ended (CC words). */
+export declare const MOD_TRACE_OUTCOMES: readonly ["returned", "passed", "rejected", "caught", "expired", "kept", "skipped", "bypassed"];
+export type ModTraceOutcome = (typeof MOD_TRACE_OUTCOMES)[number];
+/** What a `.catch` reads off `next.error`. */
+export interface ModCaughtError {
+    readonly kind: ModFailureCause;
+    readonly message?: string;
+    readonly budget: number;
+}
+/** The third argument of a handler: continue the chain, or jump (prepend / append only). */
+export interface ModNext {
+    (e: ModEventPayload): Promise<unknown>;
+    to(e: ModEventPayload, tier: ModTier): Promise<unknown>;
+    readonly origin: ModOrigin;
+    readonly signal: AbortSignal;
+    /** What ran beneath this handler's last `next`. */
+    readonly trace: readonly ModTraceEntry[];
+    readonly budget: ModBudgetReading;
+    /** Present on a `.catch`'s `next` only. */
+    readonly error?: ModCaughtError;
+    /** Present on a `.catch`'s `next` only: whether the failed handler had called `next`. */
+    readonly called?: boolean;
+}
+export type ModHandler<D extends ModDollarBase = ModDollarBase> = ($: D, e: ModEventPayload, next: ModNext) => unknown;
+export interface ModHandlerOptions<D extends ModDollarBase = ModDollarBase> {
+    /** Answers for the handler when it throws, runs out of budget or breaks the site's contract. */
+    readonly catch?: ModHandler<D>;
+    /** Watch only: a detached `e`, outside the chain, its answer refused and disclosed. */
+    readonly observe?: boolean;
+}
+/** `on(pattern, handler, options?)` or `on(pattern, matcher, handler, options?)`. */
+export interface On<D extends ModDollarBase = ModDollarBase> {
+    (pattern: string, handler: ModHandler<D>, options?: ModHandlerOptions<D>): void;
+    (pattern: string, matcher: ModMatcher, handler: ModHandler<D>, options?: ModHandlerOptions<D>): void;
+}
+export interface ModRegistration<D extends ModDollarBase = ModDollarBase> {
+    /** Unique in the run; names the registration everywhere (origin, trace, disclosures, admission). */
+    readonly name: string;
+    /** Deployment seat: required. Task seat: absent or `user`. */
+    readonly tier?: ModRegistrationTier;
+    readonly uses: ModUses;
+    /** The host's provenance label, handed to admission as given. */
+    readonly provenance?: string;
+    /** Each handler's own time; default 10 000 ms. */
+    readonly budgetMs?: number;
+    readonly options?: unknown;
+    register(on: On<D>, options: unknown): void;
+}
+/** One admission result: mounted (with the patterns it actually hung) or refused (by whom, why). */
+export type ModAdmissionRecord = {
+    readonly name: string;
+    readonly seat: ModSeat;
+    readonly tier: ModTier;
+    readonly events: readonly string[];
+    readonly observe?: readonly string[];
+    /** Judges skipped while this registration was judged (their failure or site violation), as the dispatch listed them. */
+    readonly skipped?: readonly ModSkip[];
+} | {
+    readonly name: string;
+    readonly seat: ModSeat;
+    readonly tier: ModTier;
+    readonly refusedBy: string;
+    readonly reason: string;
+};
+/** The two seats as a bus receives them; a seat is a list of registrations or absent. Screened as untrusted input. */
+export interface ModSeats<D extends ModDollarBase = ModDollarBase> {
+    readonly deployment?: readonly ModRegistration<D>[];
+    readonly task?: readonly ModRegistration<D>[];
+}
+/** A registration that passed the screen, in run order. */
+export interface ScreenedRegistration<D extends ModDollarBase = ModDollarBase> {
+    readonly registration: ModRegistration<D>;
+    readonly name: string;
+    readonly seat: ModSeat;
+    readonly tier: ModRegistrationTier;
+    readonly budgetMs: number;
+    readonly uses: ModUses;
+    readonly provenance?: string;
+    readonly eventsBound: ReadonlySet<ModEventName>;
+    readonly callsBound: ReadonlySet<ModEventName>;
+}
+export declare function modsInvalid(message: string): Error & {
+    readonly code: string;
+};
+/**
+ * Screen both seats and put the registrations in run order: by tier, then deployment before task, then
+ * each seat's own order. Throws `config.mods_invalid` for anything the kernel cannot take; a bad
+ * `budgetMs` is reported and replaced by the default instead.
+ */
+export declare function screenModSeats<D extends ModDollarBase>(seats: ModSeats<D>, side: ModBusSide, report: (err: Error) => void): ScreenedRegistration<D>[];

package/dist/core/mods/kernel/registration.js

@@ -0,0 +1,102 @@
+import { describe, expandModPattern, MOD_SEATS, readOnSide, SEAT_TIER_TABLE, } from "./events.js";
+import { resolveModBudgetMs } from "./budget.js";
+export const MODS_INVALID_CODE = "config.mods_invalid";
+export const MODS_REGISTRATION_REFUSED_CODE = "mods.registration_refused";
+export const ENGINE_ORIGIN = Object.freeze({ plugin: "engine", tier: "core" });
+export const MOD_TRACE_OUTCOMES = Object.freeze(["returned", "passed", "rejected", "caught", "expired", "kept", "skipped", "bypassed"]);
+export function modsInvalid(message) {
+    return Object.assign(new Error(message), { code: MODS_INVALID_CODE });
+}
+const TIER_ORDER = ["prepend", "user", "append"];
+export function screenModSeats(seats, side, report) {
+    const out = [];
+    const names = new Set();
+    for (const seat of MOD_SEATS) {
+        const list = seats[seat];
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list))
+            throw modsInvalid(`the ${seat} seat's mods must be a list of registrations, not ${describe(list)}`);
+        for (const item of list) {
+            const screened = screenOne(item, seat, side, report);
+            if (names.has(screened.name))
+                throw modsInvalid(`two registrations are named "${screened.name}" — a registration name is unique in the run`);
+            names.add(screened.name);
+            out.push(screened);
+        }
+    }
+    return out.sort((a, b) => TIER_ORDER.indexOf(a.tier) - TIER_ORDER.indexOf(b.tier));
+}
+function isRegistration(v) {
+    return typeof v === "object" && v !== null && typeof Reflect.get(v, "name") === "string" && typeof Reflect.get(v, "register") === "function";
+}
+function screenOne(item, seat, side, report) {
+    if (!isRegistration(item))
+        throw modsInvalid(`a ${seat} mods entry is ${describe(item)}; a registration has a name and a register function`);
+    const name = item.name;
+    if (name === "")
+        throw modsInvalid(`a ${seat} registration has an empty name`);
+    if (name === ENGINE_ORIGIN.plugin)
+        throw modsInvalid(`a ${seat} registration is named "${name}", the engine's own origin word — choose another name`);
+    const tier = tierOf(item.tier, seat, name);
+    const uses = usesOf(item.uses, name);
+    if (item.provenance !== undefined && typeof item.provenance !== "string")
+        throw modsInvalid(`${name}: provenance is ${describe(item.provenance)}; it is a label (a string)`);
+    const eventsBound = new Set();
+    for (const p of uses.events)
+        for (const n of namesOf(p, name, "uses.events"))
+            eventsBound.add(n);
+    const callsBound = new Set();
+    for (const c of uses.calls)
+        for (const n of namesOf(c, name, "uses.calls"))
+            if (readOnSide(n, side))
+                callsBound.add(n);
+    return {
+        registration: item,
+        name,
+        seat,
+        tier,
+        budgetMs: resolveModBudgetMs(item.budgetMs, report, name),
+        uses,
+        ...(item.provenance !== undefined ? { provenance: item.provenance } : {}),
+        eventsBound,
+        callsBound,
+    };
+}
+function tierOf(declared, seat, name) {
+    const row = SEAT_TIER_TABLE[seat];
+    const allowed = row.tiers;
+    if (declared === undefined) {
+        if (row.declared === "required")
+            throw modsInvalid(`${name}: a ${seat} registration declares its tier (${allowed.join(", ")})`);
+        return allowed[0];
+    }
+    const tier = allowed.find((t) => t === declared);
+    if (tier === undefined)
+        throw modsInvalid(`${name}: a ${seat} registration's tier is ${allowed.join(" or ")}, not ${describe(declared)}`);
+    return tier;
+}
+function usesOf(uses, name) {
+    if (typeof uses !== "object" || uses === null)
+        throw modsInvalid(`${name}: uses is ${describe(uses)}; it declares { events, calls }`);
+    const events = stringList(Reflect.get(uses, "events"), name, "uses.events");
+    const calls = stringList(Reflect.get(uses, "calls"), name, "uses.calls");
+    return Object.freeze({ events, calls });
+}
+function stringList(v, name, field) {
+    if (!Array.isArray(v))
+        throw modsInvalid(`${name}: ${field} is ${describe(v)}; it is a list of event names`);
+    const out = [];
+    for (const x of v) {
+        if (typeof x !== "string")
+            throw modsInvalid(`${name}: ${field} holds ${describe(x)}; it is a list of event names`);
+        out.push(x);
+    }
+    return Object.freeze(out);
+}
+function namesOf(pattern, name, field) {
+    const expanded = expandModPattern(pattern);
+    if ("refusal" in expanded)
+        throw modsInvalid(`${name}: ${field}: ${expanded.refusal}`);
+    return expanded.names;
+}

package/dist/core/mods/kernel/site-rules.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Site rules: what a handler may hand on and answer. A handler that changes a pinned key on the way down,
+ * or answers outside the station's answer form, breaks the site's contract — a VIOLATION, judged by the
+ * failure column like a crash but never reported as one (no code crashed).
+ */
+import { type ModSeat, type ModTier } from "./events.js";
+/** The host's Proxy probe (this folder cannot recognise a Proxy on its own): with one, a handler's Proxy is refused
+ *  before any of its traps runs; without one, it is read like any object. */
+export type ProxyProbe = (value: object) => boolean;
+/**
+ * The one depth the bus holds a handler's values to: how many container levels a value may have below a payload member
+ * or an answer's top (1 = the member itself). Every value a handler gives the bus — what it hands to `next`, a `$`
+ * call's arguments, its answer — is received in a mode bounded by it (a shared reference measured again where it sits
+ * each time it is met), so a value nested deeper is refused by the first walk that meets it before that
+ * walk goes any deeper. Every walk keeps its own stack, so neither the platform nor the caller's stack depth decides.
+ * The pinned-key comparison is held to the same depth. A container is one level wherever it is met, so the verdict
+ * does not depend on member order for a value without a cycle; through a cycle, depth is measured on the walk's way (a
+ * container still being walked counts as one level where it is met again). The engine's own event is received at any
+ * depth, and its objects — handed back anywhere in what a handler hands on, answers or passes to a `$` call — are taken
+ * as themselves, never walked: one of its containers is one level where it sits, whatever it holds.
+ */
+export declare const MODS_VALUE_DEPTH = 1000;
+/** Why a handler did not answer for itself: it threw, it ran past its budget, it broke the site's contract, or it was
+ *  not run because the dispatch re-entered a frame it is part of (its `.catch` answers for it — CC 296 form, (cli296.js:242947) "hasCatch"). */
+export declare const MOD_FAILURE_CAUSES: readonly ["threw", "timeout", "violation", "reentry"];
+export type ModFailureCause = (typeof MOD_FAILURE_CAUSES)[number];
+/** A handler the dispatch skipped (a failure on a skip event), and why. */
+export interface ModSkip {
+    readonly registration: string;
+    readonly cause: ModFailureCause;
+    readonly reason: string;
+}
+/** An event payload as the kernel carries it: an object, top level frozen by the bus. */
+export type ModEventPayload = Readonly<Record<string, unknown>>;
+/** The registration whose handler gave an answer, as the station's answer check sees it. */
+export interface ModAnswerer {
+    readonly plugin: string;
+    readonly seat: ModSeat;
+    readonly tier: ModTier;
+}
+/** What an answer check reads, in `below`, for a `next` the handler started that has not answered yet (no `deny`, no `value`). */
+export declare const NEXT_IN_FLIGHT: Readonly<{
+    inFlight: true;
+}>;
+/** The station's own reading of an answer: undefined when it is one the station takes, else why not. `below` is every
+ *  answer the handler's `next` resolved with, plus `NEXT_IN_FLIGHT` while its `next` is still in flight —
+ *  empty when it never called `next`. */
+export type ModAnswerCheck = (answer: unknown, e: ModEventPayload, by: ModAnswerer, below: readonly unknown[]) => string | undefined;
+/** A matcher: top-level fields of `e` that must equal these values exactly. */
+export type ModMatcher = Readonly<Record<string, string | number | boolean>>;
+/** Why a pinned key of what a handler handed on is not taken: it holds another value, or it is a copy the comparison
+ *  could not walk to the end (`unproven` says why) — refused all the same, since only a copy proven the same is taken. */
+export interface PinnedKeyBreak {
+    readonly key: string;
+    readonly unproven?: string;
+}
+/**
+ * The first pinned key `next` did not hand on as the engine's fact, or undefined. A pinned value is compared by value
+ * ({@link sameModValue}): the engine's own fact handed on as is, or a copy of it, is not a change.
+ */
+export declare function pinnedKeyChanged(pinned: readonly string[], received: ModEventPayload, passed: ModEventPayload): PinnedKeyBreak | undefined;
+/** {@link engineObjects} of a dispatch's own event, found the first time it is asked and the same set every time after:
+ *  the event is frozen, so one finding serves every receipt of the dispatch. */
+export declare function engineObjectsOnce(held: ModEventPayload): () => ReadonlySet<object>;
+/**
+ * What the next handler reads when a handler hands `passed` to `next` (not the dispatch's own e): `passed` received
+ * whole in the mode held to {@link MODS_VALUE_DEPTH} (every object of the dispatch's own e in it — `engines`, found once
+ * per dispatch by {@link engineObjectsOnce} — kept as itself), then {@link pinnedHandOn}. A value nested past the depth
+ * is refused by the receipt, before any deeper walk — under a pinned key in the comparison's own words (too deep to
+ * compare), under any other member as the payload holding it.
+ */
+export declare function handedOn(pinned: readonly string[], held: ModEventPayload, passed: unknown, engines: ReadonlySet<object>, isProxy?: ProxyProbe): {
+    readonly payload: ModEventPayload;
+} | {
+    readonly violation: string;
+};
+/**
+ * What the next handler reads when a handler hands on `passed` (already received whole): the payload with every
+ * pinned key the engine's own member — the same object `held` carries, or no member where `held` has none — so a
+ * handler below a copy-forwarder reads the engine's fact, not the copy's shape (a member that is `undefined`, a
+ * member order, a −0 the comparison does not count). A pinned key the copy did not hand on as the engine's fact
+ * ({@link pinnedKeyChanged}) breaks the site instead. The comparison decides only whether to refuse; what travels down
+ * for a pinned key is the engine's member, always. The payload keeps the shape it was received in: a reference inside
+ * it to the payload itself is a reference to what is handed on (a cycle stays a cycle), and one to any object inside
+ * what the handler handed on under a pinned key — the copy itself, a member of it, an element of one of its lists, at
+ * any depth — is a reference to the engine's object it was proven the same as (a shared reference stays shared; an
+ * object of the copy standing for two of the engine's goes to the one the comparison met first). `engines`: every
+ * object of `held` (found here when not given).
+ */
+export declare function pinnedHandOn(pinned: readonly string[], held: ModEventPayload, passed: ModEventPayload, engines?: ReadonlySet<object>): {
+    readonly payload: ModEventPayload;
+} | {
+    readonly violation: string;
+};
+/** Why a handler's answer breaks the site, or undefined. No answer at all is never an answer. */
+export declare function answerViolation(answer: unknown, check: ModAnswerCheck | undefined, e: ModEventPayload, by: ModAnswerer, below: readonly unknown[]): string | undefined;
+/**
+ * A `$` method's answer form: `{ value }` (the call's result) or `{ deny }` (the call throws). A `{ deny }` given after
+ * the handler's `next` was answered with something that is not a deny — or while that `next` is still running — breaks
+ * the form (the deny would stand in place of a call that already ran or is running) — a deny handed up from below is
+ * no such thing. A `{ value }` given while that `next` is still running stands in place of the same running call, so it
+ * breaks the form too; one given after `next` answered is the handler rewriting what it read, and stands. Counting the
+ * running `next` is stricter than the reference, which reads answered runs only.
+ */
+export declare function methodAnswerViolation(answer: unknown, _e?: ModEventPayload, _by?: ModAnswerer, below?: readonly unknown[]): string | undefined;
+/** Why `m` is not a matcher, or undefined. */
+export declare function matcherViolation(m: unknown): string | undefined;
+/** Whether every matcher field equals `e`'s own top-level field exactly. */
+export declare function matcherMatches(m: ModMatcher | undefined, e: ModEventPayload): boolean;
+/** A record a handler gives the bus other than through `next` — a `$` call's arguments, and a method's `enter` shaping
+ *  of them — received held to {@link MODS_VALUE_DEPTH}; an object of `held` ({@link engineObjectsOnce} of what the bus
+ *  already holds: the dispatch the handler runs in, or the call's received arguments) is kept as itself, never walked. */
+export declare function receivePayload(v: unknown, isProxy?: ProxyProbe, held?: ReadonlySet<object>): {
+    readonly payload: ModEventPayload;
+} | {
+    readonly refusal: string;
+};
+/** The engine's own event at a dispatch's entry, received whole at any depth (one the receipt cannot copy whole —
+ *  reading it threw where none of its getters runs, or it holds more objects than one receipt can index — is refused,
+ *  never handed on shorter). */
+export declare function receiveEvent(e: unknown): {
+    readonly payload: ModEventPayload;
+} | {
+    readonly refusal: string;
+};
+/**
+ * The bottom's answer as it starts up the chain: its top level frozen, so no handler can turn the answer it got from
+ * `next` into another one (a deny in place of a result that already ran). A plain record or array the bottom made is
+ * copied once and frozen; an answer already frozen (an engine sentinel) or not a plain container is itself.
+ */
+export declare function answerUpward(v: unknown): unknown;
+/** A handler's answer, received by the same receipt held to {@link MODS_VALUE_DEPTH} (an answer need not be a record; a
+ *  primitive is itself); an object of the dispatch's own event in it (`engines`, {@link engineObjectsOnce}) is kept as
+ *  itself, never walked. */
+export declare function receiveAnswer(answer: unknown, engines: ReadonlySet<object>, isProxy?: ProxyProbe): {
+    readonly answer: unknown;
+} | {
+    readonly refusal: string;
+};
+/**
+ * A copy for an observe handler, made by the one receipt (its own stack, so no depth of the event decides whether an
+ * observer runs — the event it observes was received at any depth too): every data container (a plain object, an
+ * ordinary array) detached at any depth; then every other object the copy holds — a tool result's `Map`, `Date` or
+ * typed array — detached by a structured clone of that object alone (one clone per object, so a shared one stays shared),
+ * and one the clone refuses (a function, a handle, a class instance holding one) handed as is. The engine's own event
+ * holds data properties only, so the copy is whole; a receipt that could not make it (a Proxy whose trap throws, on a bus
+ * given no probe) is the observer's failure, reported like any other.
+ */
+export declare function detachedCopy(e: ModEventPayload): Record<string, unknown>;