@sema-agent/mods-kernel 7.55.0 → 7.56.0

package/README.md

@@ -26,7 +26,8 @@ Two copies of the kernel interoperate on plain objects (no `instanceof`, no modu
 one copy beside another compares `KERNEL_CONTRACT_VERSION` for equality. Nothing in the kernel or the engine reads it,
 so two copies that differ are told apart only by a host that compares them. The number is an integer independent of the
 package version; it moves only when the chain semantics, the registration form, the event closed set (names and
-`side`) or the failure columns (failure, abort, pinned keys — which keys, and how a pinned key is judged) change.
+`side`) or the failure columns (failure, abort, pinned keys, an event's own budget ceiling, whether `$` may call it)
+change — once per release, however many of them change in it.
 
 ## Which side raises an event
 
@@ -51,12 +52,13 @@ contract; a removed or re-kinded export is named as breaking in the `@sema-agent
 | Group | Names |
 | --- | --- |
 | Contract and closed sets | `KERNEL_CONTRACT_VERSION` `MOD_TIERS` `MOD_SEATS` `MOD_EVENT_SIDES` `MOD_FAILURE_ANSWERS` `MOD_ABORT_POSTURES` `NEXT_TO_TABLE` `SEAT_TIER_TABLE` |
-| Event table and readers | `MOD_EVENT_TABLE` `isModEventName` `expandModPattern` `stationOn` `readOnSide` `nextToRefusal` |
+| Event table and readers | `MOD_EVENT_TABLE` `isModEventName` `expandModPattern` `expandOnSide` `stationOn` `readOnSide` `failureRefuses` `nextToRefusal` |
 | Event table types | `ModTier` `ModRegistrationTier` `ModSeat` `ModEventSide` `ModBusSide` `ModFailureAnswer` `ModAbortPosture` `ModStation` `ModEventRow` `ModEventName` |
 | Budgets | `DEFAULT_MOD_BUDGET_MS` `CATCH_BUDGET_MS` `RUNAWAY_AFTER_MS` `POST_ABORT_GRACE_MS` `MAX_TIMER_MS` `resolveModBudgetMs` `ModBudgetReading` |
-| Failure causes and site rules | `MOD_FAILURE_CAUSES` `ModFailureCause` `ModEventPayload` `ModAnswerCheck` `ModAnswerer` `ModMatcher` `ModSkip` |
+| Failure causes and site rules | `MOD_FAILURE_CAUSES` `ModFailureCause` `ModEventPayload` `ModAnswerCheck` `ModAnswerRanks` `ModDispatchRun` `ModAnswerer` `ModMatcher` `ModSkip` |
 | Registration | `ENGINE_ORIGIN` `MODS_INVALID_CODE` `MODS_REGISTRATION_REFUSED_CODE` `MOD_TRACE_OUTCOMES` `ModTraceOutcome` `ModUses` `ModOrigin` `ModPluginFacts` `ModDollarBase` `ModTraceEntry` `ModCaughtError` `ModNext` `ModHandler` `ModHandlerOptions` `On` `ModRegistration` `ModAdmissionRecord` `ModSeats` |
-| Admission and the bus | `admitMods` `ModFrame` `ModBottomContext` `ModMethodBottom` `ModMethodSeat` `ModMethodBottoms` `ModDispatchOutcome` `ModDispatchOptions` `ModBus` `ModMountedHandler` `ModBusInput` |
+| Typed event maps | `ModEventPair` `ModEventMap` `ModTypedNext` `ModTypedHandler` `MappedOn` |
+| Admission and the bus | `admitMods` `ModFrame` `ModBottomContext` `ModMethodBottom` `ModMethodSeat` `ModMethodBottoms` `ModCallEntry` `ModCallEntries` `ModDispatchOutcome` `ModDispatchOptions` `ModBus` `ModMountedHandler` `ModBusInput` |
 
 ## License
 

package/dist/dispatch.d.ts

@@ -1,6 +1,6 @@
 import { type ModBusSide, type ModEventName, type ModSeat } from "./events.js";
 import { type ModAdmissionRecord, type ModDollarBase, type ModOrigin, type ModSeats } from "./registration.js";
-import { type ModAnswerCheck, type ModEventPayload, type ModFailureCause, type ModMatcher, type ModSkip, type ProxyProbe } from "./site-rules.js";
+import { type ModAnswerCheck, type ModAnswerRanks, type ModEventPayload, type ModFailureCause, type ModMatcher, type ModSkip, type ProxyProbe } from "./site-rules.js";
 export type ModFrame = {
     readonly kind: "dollar";
     readonly plugin: string;
@@ -20,6 +20,8 @@ export interface ModMethodSeat {
     readonly enter?: (args: ModEventPayload) => ModEventPayload;
 }
 export type ModMethodBottoms = Partial<Record<ModEventName, ModMethodSeat>>;
+export type ModCallEntry = (args: ModEventPayload, ctx: ModBottomContext) => unknown;
+export type ModCallEntries = Partial<Record<ModEventName, ModCallEntry>>;
 export type ModDispatchOutcome = {
     readonly kind: "answered";
     readonly answer: unknown;
@@ -33,6 +35,7 @@ export type ModDispatchOutcome = {
     readonly skipped: readonly ModSkip[];
 } | {
     readonly kind: "aborted";
+    readonly bottomStarted?: true;
 };
 export interface ModParticipant {
     readonly plugin: string;
@@ -45,6 +48,7 @@ export interface ModDispatchOptions {
     readonly frames?: readonly ModFrame[];
     readonly origin?: ModOrigin;
     readonly checkAnswer?: ModAnswerCheck;
+    readonly ranks?: ModAnswerRanks;
     readonly participant?: (p: ModParticipant) => boolean;
 }
 export interface ModMountedHandler {
@@ -59,12 +63,13 @@ export interface ModBus {
     readonly records: readonly ModAdmissionRecord[];
     mounted(): readonly ModMountedHandler[];
     hasHandlers(event: ModEventName, participant?: (p: ModParticipant) => boolean): boolean;
-    dispatch(event: ModEventName, e: ModEventPayload, options: ModDispatchOptions): Promise<ModDispatchOutcome>;
+    dispatch(event: ModEventName, e: object, options: ModDispatchOptions): Promise<ModDispatchOutcome>;
 }
 export interface ModBusInput<D extends ModDollarBase = ModDollarBase> {
     readonly side: ModBusSide;
     readonly seats: ModSeats<D>;
     readonly bottoms: ModMethodBottoms;
+    readonly entries?: ModCallEntries;
     readonly report: (err: Error, classification?: "observational-hook-verdict-ignored") => void;
     readonly describeThrown: (err: unknown) => string;
     readonly isProxy?: ProxyProbe;

package/dist/dispatch.js

@@ -1,7 +1,7 @@
 import { CATCH_BUDGET_MS, createSelfBudget, POST_ABORT_GRACE_MS, RUNAWAY_AFTER_MS, unrefTimer, watchRunaway } from "./budget.js";
-import { expandModPattern, isModEventName, MOD_SEATS, nextToRefusal, stationOn } from "./events.js";
+import { expandOnSide, failureRefuses, isModEventName, MOD_SEATS, nextToRefusal, stationOn } from "./events.js";
 import { ENGINE_ORIGIN, modsInvalid, screenModSeats, } from "./registration.js";
-import { answerUpward, answerViolation, detachedCopy, engineObjectsOnce, handedOn, matcherMatches, matcherViolation, methodAnswerViolation, NEXT_IN_FLIGHT, receiveAnswer, receiveEvent, receivePayload, } from "./site-rules.js";
+import { answerUpward, answerViolation, detachedCopy, engineObjectsOnce, handedOn, matcherMatches, matcherViolation, methodAnswerViolation, NEXT_IN_FLIGHT, receiveAnswer, receiveEvent, receivePayload, sealedObjects, } from "./site-rules.js";
 const TIER_RANK = { prepend: 0, user: 1, append: 2, builtin: 3, core: 4 };
 const bypassed = (floors, tier) => floors.some((f) => TIER_RANK[f.from] < TIER_RANK[tier] && TIER_RANK[tier] < TIER_RANK[f.to]);
 export async function admitMods(input) {
@@ -10,7 +10,7 @@ export async function admitMods(input) {
     const mounted = [];
     const records = [];
     const describe = safeDescribe(input.describeThrown);
-    const bus = createBus(input.side, mounted, input.bottoms, report, records, describe, input.isProxy);
+    const bus = createBus(input.side, mounted, input.bottoms, input.entries ?? {}, report, records, describe, input.isProxy);
     const admitted = Object.freeze({ admitted: true });
     for (const cand of screened) {
         if (input.signal?.aborted === true)
@@ -24,14 +24,10 @@ export async function admitMods(input) {
         });
         const outcome = await bus.dispatch("plugin.register", e, {
             bottom: () => admitted,
+            ranks: ADMISSION_RANKS,
             ...(input.signal !== undefined ? { signal: input.signal } : {}),
-            checkAnswer: (a, judged, by) => a === admitted
-                ? undefined
-                : refusalOf(a) === undefined
-                    ? "takes next(e) or { refuse: <reason> }"
-                    : MOD_SEATS.indexOf(by.seat) > MOD_SEATS.findIndex((s) => s === judged["seat"])
-                        ? `a ${by.seat} registration may not refuse a ${String(judged["seat"])} registration`
-                        : undefined,
+            participant: (p) => MOD_SEATS.indexOf(p.seat) <= MOD_SEATS.indexOf(cand.seat),
+            checkAnswer: (a) => (a === admitted || refusalOf(a) !== undefined ? undefined : "takes next(e) or { refuse: <reason> }"),
         });
         if (outcome.kind === "aborted")
             throw input.signal?.reason ?? new Error("admission aborted");
@@ -59,6 +55,7 @@ export async function admitMods(input) {
     }
     return bus;
 }
+const ADMISSION_RANKS = Object.freeze({ of: (a) => (refusalOf(a) !== undefined ? 1 : 0), top: 1 });
 function refusalOf(a) {
     if (typeof a !== "object" || a === null || !Object.prototype.hasOwnProperty.call(a, "refuse"))
         return undefined;
@@ -113,7 +110,7 @@ function mountOne(cand, side, describe) {
         const parsed = handlerOptions(opts);
         if (typeof parsed === "string")
             fail(`on("${String(pattern)}"): ${parsed}`);
-        const expanded = expandModPattern(pattern);
+        const expanded = expandOnSide(pattern, side);
         if ("refusal" in expanded)
             return void fail(`on(): ${expanded.refusal}`);
         const outside = expanded.names.filter((n) => !cand.eventsBound.has(n));
@@ -178,16 +175,23 @@ function handlerOptions(opts) {
 }
 const HA = "skipped; what is below it ran in its place";
 const MA = "skipped; its last next() run's result stands";
-function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
-    const methods = [];
+function createBus(side, mounted, bottoms, entries, report, records, describe, isProxy) {
+    const reaches = new Map();
     for (const name of Object.keys(bottoms)) {
-        if (!isModEventName(name) || bottoms[name] === undefined)
+        if (!isModEventName(name))
             continue;
+        const seat = bottoms[name];
         const st = stationOn(name, side);
-        if (st?.method === undefined)
+        if (seat !== undefined && st?.method !== undefined)
+            reaches.set(name, { kind: "method", st, seat, pauses: st.method.pausesCallerBudget });
+    }
+    for (const name of Object.keys(entries)) {
+        if (!isModEventName(name))
             continue;
-        const dot = name.indexOf(".");
-        methods.push({ event: name, ns: name.slice(0, dot), method: name.slice(dot + 1), pauses: st.method.pausesCallerBudget });
+        const entry = entries[name];
+        const st = stationOn(name, side);
+        if (entry !== undefined && st?.call !== undefined)
+            reaches.set(name, { kind: "call", entry, pauses: st.call.pausesCallerBudget });
     }
     const bus = {
         records,
@@ -215,26 +219,26 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
         const inFrames = (fs, h) => fs.some((f) => f.plugin === h.reg.name && (f.kind === "dollar" || f.handler === h.index));
         const caller = frames.slice(-1);
         const above = frames.slice(0, -1);
-        const out = [];
+        const all = [];
+        const guards = [];
         for (const h of mounted) {
             if (!h.events.has(event) || !admits(participant, h) || !matcherMatches(h.matcher, e))
                 continue;
             if (inFrames(caller, h))
                 continue;
             if (!inFrames(above, h))
-                out.push({ h, reentry: false });
-            else if (h.onCatch !== undefined && !h.observe)
-                out.push({ h, reentry: true });
+                all.push({ h, reentry: false });
+            else if (h.observe)
+                continue;
+            else if (h.onCatch !== undefined)
+                all.push({ h, reentry: true });
+            else
+                guards.push(h);
         }
-        return out;
+        return { all, guards };
     }
-    async function callMethod(event, args, caller) {
-        const seat = bottoms[event];
-        if (seat === undefined)
-            throw new Error(`${caller.origin.plugin}: $.${event}: no implementation on the ${side} bus`);
-        const st = stationOn(event, side);
-        if (st === undefined)
-            throw new Error(`${caller.origin.plugin}: $.${event}: not raised on the ${side} bus`);
+    async function callMethod(event, reach, args, caller) {
+        const { seat, st } = reach;
         let e0 = args;
         if (seat.enter !== undefined) {
             const shaped = receivePayload(seat.enter(args), isProxy, engineObjectsOnce(args)());
@@ -249,10 +253,6 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             signal: caller.signal,
             checkAnswer: methodAnswerViolation,
         });
-        if (outcome.kind !== "aborted")
-            for (const s of outcome.skipped)
-                if (s.cause === "violation")
-                    report(new Error(`${s.registration}: $.${event}: ${s.reason} — skipped`));
         if (outcome.kind === "aborted")
             throw new Error(`${caller.origin.plugin}: $.${event}: aborted`);
         if (outcome.kind === "failed")
@@ -265,24 +265,28 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
     }
     function dollarFor(reg, frames, budget, signal, engines) {
         const origin = Object.freeze({ plugin: reg.name, tier: reg.tier });
-        const callerFrames = Object.freeze([...frames, Object.freeze({ kind: "dollar", plugin: reg.name })]);
+        const caller = Object.freeze({ frames: Object.freeze([...frames, Object.freeze({ kind: "dollar", plugin: reg.name })]), origin, signal });
         const namespaces = new Map();
-        for (const m of methods) {
-            const ns = namespaces.get(m.ns) ?? {};
-            namespaces.set(m.ns, ns);
-            ns[m.method] = async (args) => {
-                if (!reg.callsBound.has(m.event))
-                    throw new Error(`${reg.name}: $.${m.event}: not declared in uses.calls`);
+        for (const event of new Set([...reaches.keys(), ...reg.callsBound])) {
+            const dot = event.indexOf(".");
+            const ns = namespaces.get(event.slice(0, dot)) ?? {};
+            namespaces.set(event.slice(0, dot), ns);
+            ns[event.slice(dot + 1)] = async (args) => {
+                if (!reg.callsBound.has(event))
+                    throw new Error(`${reg.name}: $.${event}: not declared in uses.calls`);
+                const reach = reaches.get(event);
+                if (reach === undefined)
+                    throw new Error(`${reg.name}: $.${event}: not callable on the ${side} bus in this version`);
                 const received = receivePayload(args === undefined ? {} : args, isProxy, engines());
                 if ("refusal" in received)
-                    throw new TypeError(`${reg.name}: $.${m.event}: takes one object — ${received.refusal}`);
-                if (m.pauses)
+                    throw new TypeError(`${reg.name}: $.${event}: takes one object — ${received.refusal}`);
+                if (reach.pauses)
                     budget.pause();
                 try {
-                    return await callMethod(m.event, received.payload, { frames: callerFrames, origin, signal });
+                    return reach.kind === "method" ? await callMethod(event, reach, received.payload, caller) : await reach.entry(received.payload, caller);
                 }
                 finally {
-                    if (m.pauses)
+                    if (reach.pauses)
                         budget.resume();
                 }
             };
@@ -290,12 +294,25 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
         const out = {};
         for (const [ns, fns] of namespaces)
             out[ns] = Object.freeze(fns);
-        return Object.freeze({ ...out, plugin: Object.freeze({ name: reg.name }) });
+        return Object.freeze({ ...out, plugin: Object.freeze({ ...(namespaces.get("plugin") ?? {}), name: reg.name }) });
     }
     function runDispatch(event, st, e0, options) {
         const frames = options.frames ?? [];
         const origin = options.origin ?? ENGINE_ORIGIN;
-        const all = participants(event, e0, frames, options.participant);
+        const refusing = failureRefuses(st.failure);
+        const engineFault = (reason) => {
+            report(new Error(`engine: ${event}: ${reason} — the dispatch was not run`));
+            return Promise.resolve(Object.freeze({ kind: "failed", registration: ENGINE_ORIGIN.plugin, cause: "violation", reason: `${event}: ${reason}`, skipped: Object.freeze([]) }));
+        };
+        if (refusing && options.ranks === undefined)
+            return engineFault("a dispatch of an event whose failure column refuses names no answer ranks (the seat-trust law reads them)");
+        const { all, guards } = participants(event, e0, frames, options.participant);
+        const guard = refusing ? guards[0] : undefined;
+        if (guard !== undefined) {
+            const reason = "not run: the dispatch re-entered a frame it is part of, and it has no .catch to answer for it — a guard that cannot answer refuses";
+            report(new Error(`${guard.reg.name}: ${event}: ${reason} — failed closed: the dispatch ends here`));
+            return Promise.resolve(Object.freeze({ kind: "failed", registration: guard.reg.name, cause: "reentry", reason, skipped: Object.freeze([]) }));
+        }
         const observers = all.filter((p) => !p.reentry && p.h.observe).map((p) => p.h);
         const chain = all.filter((p) => !p.h.observe).map((p) => p.h);
         const reentered = new Set(all.filter((p) => p.reentry).map((p) => p.h));
@@ -305,6 +322,8 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
         const dispatchAc = new AbortController();
         const terminal = { kind: "terminal" };
         let settled = false;
+        let bottomStarted = false;
+        const ownMs = (ms) => (st.budgetMs === undefined ? ms : Math.min(ms, st.budgetMs));
         let graceTimer;
         let resolveOut = () => { };
         let rejectOut = () => { };
@@ -313,15 +332,16 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             rejectOut = rej;
         });
         const signal = options.signal;
+        const aborted = () => (bottomStarted ? { kind: "aborted", bottomStarted: true } : { kind: "aborted" });
         const onAbort = () => {
             if (settled)
                 return;
             if (st.abort === "grace") {
-                graceTimer ??= setTimeout(() => finish({ kind: "aborted" }), POST_ABORT_GRACE_MS);
+                graceTimer ??= setTimeout(() => finish(aborted()), POST_ABORT_GRACE_MS);
                 unrefTimer(graceTimer);
             }
             else
-                finish({ kind: "aborted" });
+                finish(aborted());
         };
         function finish(o) {
             if (settled)
@@ -348,23 +368,66 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             run.then(drop, drop);
         };
         const engines = engineObjectsOnce(e0);
+        const eventSealed = (() => {
+            let found;
+            return () => (found ??= sealedObjects([e0]));
+        })();
         const handOn = (passed) => {
             if (passed === e0)
                 return { snap: e0 };
             const handed = handedOn(st.pinned, e0, passed, engines(), isProxy);
             return "violation" in handed ? handed : { snap: handed.payload };
         };
-        const takeAnswer = (answer, s, e, h) => {
+        const trustFloors = new Map();
+        const NO_FLOOR = Object.freeze(MOD_SEATS.map(() => 0));
+        const seatRank = (seat) => MOD_SEATS.indexOf(seat);
+        const seatTrust = (taken, s, h, i, tiers) => {
+            const ranks = options.ranks;
+            if (ranks === undefined)
+                return undefined;
+            const mine = seatRank(h.reg.seat);
+            let rank;
+            try {
+                rank = ranks.of(taken);
+            }
+            catch {
+                return "returned an answer the station cannot rank";
+            }
+            const answered = s.pending === 0 && s.answers.length > 0;
+            let floor;
+            if (answered) {
+                const inherited = trustFloors.get(s.answers[s.answers.length - 1]) ?? NO_FLOOR;
+                if (rank < (inherited[mine] ?? 0))
+                    return `answered less strictly than a more trusted seat's handler below it did — a ${h.reg.seat} answer never stands over a stricter one of a more trusted seat`;
+                floor = inherited;
+            }
+            else {
+                const unrun = chain.slice(i + 1).filter((m) => !bypassed(tiers, m.reg.tier)).map((m) => seatRank(m.reg.seat));
+                const trusted = unrun.length > 0 ? Math.min(...unrun) : MOD_SEATS.length;
+                if (trusted < mine && rank < ranks.top) {
+                    return `answered ${s.called ? "while its next(e) still ran" : "without calling next(e)"}, with a ${MOD_SEATS[trusted]} handler below it that did not judge — a ${h.reg.seat} answer stands in place of theirs only when it refuses outright`;
+                }
+                floor = NO_FLOOR.map((_, k) => (k > trusted ? ranks.top : 0));
+            }
+            trustFloors.set(taken, floor.map((f, k) => (mine < k ? rank : f)));
+            return undefined;
+        };
+        const takeAnswer = (answer, s, e, h, i, tiers) => {
+            const handedUp = s.answers.some((a) => Object.is(a, answer));
             let taken = answer;
-            if (!s.answers.some((a) => Object.is(a, answer))) {
-                const received = receiveAnswer(answer, engines(), isProxy);
+            if (!handedUp) {
+                const held = { has: (v) => eventSealed().has(v) || s.sealed?.has(v) === true };
+                const received = receiveAnswer(answer, held, isProxy);
                 if ("refusal" in received)
                     return { violation: received.refusal };
                 taken = received.answer;
             }
             const below = s.pending > 0 ? [...s.answers, NEXT_IN_FLIGHT] : s.answers;
-            const why = answerViolation(taken, options.checkAnswer, e, answererOf(h), below);
-            return why !== undefined ? { violation: why } : { answer: taken };
+            const why = answerViolation(taken, options.checkAnswer, e, answererOf(h), below, Object.freeze({ bottomStarted }));
+            if (why !== undefined)
+                return { violation: why };
+            const trust = handedUp ? undefined : seatTrust(taken, s, h, i, tiers);
+            return trust !== undefined ? { violation: trust } : { answer: taken };
         };
         const traceOf = (sink, index, plugin, tier, outcome, ms) => {
             sink.push(Object.freeze({ index, plugin, tier, outcome, ms }));
@@ -383,6 +446,7 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             run.then((v) => {
                 state.lastValue = { v };
                 state.answers.push(v);
+                state.sealed = new Set([...(state.sealed ?? []), ...sealedObjects([v])]);
                 stopCounting();
             }, (err) => {
                 state.belowError = err;
@@ -397,8 +461,9 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             const h = chain[i];
             if (h === undefined) {
                 const t0 = Date.now();
+                bottomStarted = true;
                 try {
-                    const v = answerUpward(await options.bottom(e, Object.freeze({ frames: fr, signal: dispatchAc.signal, origin })));
+                    const v = answerUpward(await options.bottom(e, Object.freeze({ frames: fr, signal: dispatchAc.signal, origin })), isProxy);
                     traceOf(sink, i, "core", "core", "returned", Date.now() - t0);
                     return v;
                 }
@@ -432,7 +497,8 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             const name = h.reg.name;
             const ac = new AbortController();
             live.add(ac);
-            const budget = createSelfBudget(h.reg.budgetMs, () => ac.abort(new Error(`${name} ran past its ${h.reg.budgetMs}ms budget`)));
+            const budgetMs = ownMs(h.reg.budgetMs);
+            const budget = createSelfBudget(budgetMs, () => ac.abort(new Error(`${name} ran past its ${budgetMs}ms budget`)));
             const myFrames = Object.freeze([...fr, Object.freeze({ kind: "handler", plugin: name, handler: h.index })]);
             const state = {
                 pending: 0,
@@ -475,9 +541,9 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
                 try {
                     const raced = await Promise.race([handlerP, budget.expired]);
                     if (raced === "expired" && budget.isExpired())
-                        failure = { cause: "timeout", reason: `ran past its ${h.reg.budgetMs}ms budget` };
+                        failure = { cause: "timeout", reason: `ran past its ${budgetMs}ms budget` };
                     else {
-                        const taken = takeAnswer(raced, state, e, h);
+                        const taken = takeAnswer(raced, state, e, h, i, floors);
                         if ("violation" in taken)
                             failure = { cause: "violation", reason: state.violated ?? taken.violation };
                         else if (state.violated !== undefined)
@@ -521,11 +587,14 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
                 return caught.answer;
             }
             if (failure.cause === "threw" && state.belowError !== undefined && failure.error === state.belowError) {
+                if (caught !== undefined)
+                    report(new Error(`${name}: ${event}: ${caught.problem} — what the run below threw stands`));
                 traceOf(sink, i, name, h.reg.tier, "rejected", ms);
                 throw failure.error;
             }
             const reason = caught !== undefined ? `${failure.reason}; ${caught.problem}` : failure.reason;
-            if (st.failure === "refuse") {
+            const effectStands = st.failure === "refuse_until_run" && bottomStarted && state.last !== undefined;
+            if (refusing && !effectStands) {
                 if (failure.cause !== "violation")
                     report(new Error(`${name}: ${event}: ${reason} — failed closed: the dispatch ends here`));
                 traceOf(sink, i, name, h.reg.tier, "rejected", ms);
@@ -534,8 +603,7 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             }
             skipped.push(Object.freeze({ registration: name, cause: failure.cause, reason }));
             const effect = state.last !== undefined ? MA : HA;
-            if (failure.cause !== "violation")
-                report(new Error(`${name}: ${event}: ${reason} — ${effect}`));
+            report(new Error(`${name}: ${event}: ${reason} — ${effect}`));
             if (state.last !== undefined) {
                 traceOf(sink, i, name, h.reg.tier, failure.cause === "timeout" ? "expired" : "kept", ms);
                 return state.last;
@@ -549,7 +617,8 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
                 return { problem: "no .catch" };
             const ac = new AbortController();
             live.add(ac);
-            const budget = createSelfBudget(CATCH_BUDGET_MS, () => ac.abort(new Error(`${h.reg.name}: its .catch ran past its ${CATCH_BUDGET_MS}ms budget`)));
+            const catchMs = ownMs(CATCH_BUDGET_MS);
+            const budget = createSelfBudget(catchMs, () => ac.abort(new Error(`${h.reg.name}: its .catch ran past its ${catchMs}ms budget`)));
             let done = false;
             let violated;
             const replay = (passed, nextFloors) => {
@@ -570,7 +639,7 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
                 return startBelow(state, budget, i, handed.snap, nextFloors, myFrames);
             };
             const message = failure.cause === "threw" ? describe(failure.error) : failure.cause === "violation" ? failure.reason : undefined;
-            const error = Object.freeze({ kind: failure.cause, ...(message !== undefined ? { message } : {}), budget: CATCH_BUDGET_MS });
+            const error = Object.freeze({ kind: failure.cause, ...(message !== undefined ? { message } : {}), budget: catchMs });
             const next = makeNext({ budget, signal: ac.signal, trace: () => Object.freeze([...state.below]) }, (x) => replay(x, floors), (x, tier) => {
                 const why = nextToRefusal(h.reg.tier, tier);
                 return why !== undefined ? Promise.reject(new Error(`${h.reg.name}: ${why}`)) : replay(x, [...floors, { from: h.reg.tier, to: tier }]);
@@ -578,10 +647,10 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             try {
                 const raced = await Promise.race([invokeNow(() => onCatch(dollarFor(h.reg, myFrames, budget, ac.signal, engines), e, next)), budget.expired]);
                 if (raced === "expired" && budget.isExpired())
-                    return { problem: `its .catch ran past its ${CATCH_BUDGET_MS}ms budget` };
+                    return { problem: `its .catch ran past its ${catchMs}ms budget` };
                 if (violated !== undefined)
                     return { problem: `its .catch ${violated}` };
-                const taken = takeAnswer(raced, state, e, h);
+                const taken = takeAnswer(raced, state, e, h, i, floors);
                 return "violation" in taken ? { problem: `its .catch ${taken.violation}` } : { answer: taken.answer };
             }
             catch (err) {
@@ -598,7 +667,8 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             const name = h.reg.name;
             const ac = new AbortController();
             live.add(ac);
-            const budget = createSelfBudget(h.reg.budgetMs, () => ac.abort(new Error(`${name} ran past its ${h.reg.budgetMs}ms budget`)));
+            const budgetMs = ownMs(h.reg.budgetMs);
+            const budget = createSelfBudget(budgetMs, () => ac.abort(new Error(`${name} ran past its ${budgetMs}ms budget`)));
             const myFrames = Object.freeze([...fr, Object.freeze({ kind: "handler", plugin: name, handler: h.index })]);
             const refuse = () => Promise.reject(new Error(`${name}: an observe handler is not in the chain; next() is unavailable`));
             const next = makeNext({ budget, signal: ac.signal, trace: () => Object.freeze([]) }, refuse, refuse);
@@ -610,7 +680,7 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             try {
                 const raced = await Promise.race([invokeNow(() => h.fn(dollarFor(h.reg, myFrames, budget, ac.signal, engines), detachedCopy(e0), next)), budget.expired]);
                 if (raced === "expired" && budget.isExpired())
-                    throw new Error(`ran past its ${h.reg.budgetMs}ms budget`);
+                    throw new Error(`ran past its ${budgetMs}ms budget`);
                 verdict(raced);
             }
             catch (err) {
@@ -623,9 +693,10 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
                     budget.clear();
                     const cac = new AbortController();
                     live.add(cac);
-                    const catchBudget = createSelfBudget(CATCH_BUDGET_MS, () => cac.abort(new Error(`${name}: its .catch ran past its ${CATCH_BUDGET_MS}ms budget`)));
+                    const catchMs = ownMs(CATCH_BUDGET_MS);
+                    const catchBudget = createSelfBudget(catchMs, () => cac.abort(new Error(`${name}: its .catch ran past its ${catchMs}ms budget`)));
                     const cnext = makeNext({ budget: catchBudget, signal: cac.signal, trace: () => Object.freeze([]) }, refuse, refuse, {
-                        error: Object.freeze({ kind: cause, ...(cause === "threw" ? { message: describe(err) } : {}), budget: CATCH_BUDGET_MS }),
+                        error: Object.freeze({ kind: cause, ...(cause === "threw" ? { message: describe(err) } : {}), budget: catchMs }),
                         called: false,
                     });
                     try {
@@ -662,7 +733,7 @@ function createBus(side, mounted, bottoms, report, records, describe, isProxy) {
             if (settled)
                 return;
             const answer = await invoke(0, e0, [], frames, root);
-            while (st.failure === "refuse" && pendingRuns.size > 0 && !settled)
+            while (refusing && pendingRuns.size > 0 && !settled)
                 await Promise.allSettled([...pendingRuns]);
             finish({ kind: "answered", answer, ...(producers.has(answer) ? { answeredBy: producers.get(answer) } : {}), skipped: Object.freeze([...skipped]) });
         })().catch((err) => {

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-export declare const KERNEL_CONTRACT_VERSION = 2;
+export declare const KERNEL_CONTRACT_VERSION = 3;
 export declare const MOD_TIERS: readonly ["prepend", "user", "append", "builtin", "core"];
 export type ModTier = (typeof MOD_TIERS)[number];
 export type ModRegistrationTier = Exclude<ModTier, "builtin" | "core">;
@@ -7,8 +7,9 @@ export type ModSeat = (typeof MOD_SEATS)[number];
 export declare const MOD_EVENT_SIDES: readonly ["engine", "surface", "both"];
 export type ModEventSide = (typeof MOD_EVENT_SIDES)[number];
 export type ModBusSide = Exclude<ModEventSide, "both">;
-export declare const MOD_FAILURE_ANSWERS: readonly ["refuse", "skip"];
+export declare const MOD_FAILURE_ANSWERS: readonly ["refuse", "skip", "refuse_until_run"];
 export type ModFailureAnswer = (typeof MOD_FAILURE_ANSWERS)[number];
+export declare function failureRefuses(failure: ModFailureAnswer): boolean;
 export declare const MOD_ABORT_POSTURES: readonly ["immediate", "grace", "caller"];
 export type ModAbortPosture = (typeof MOD_ABORT_POSTURES)[number];
 export declare const NEXT_TO_TABLE: Readonly<{
@@ -36,6 +37,10 @@ export interface ModStation {
     readonly method?: {
         readonly pausesCallerBudget: boolean;
     };
+    readonly call?: {
+        readonly pausesCallerBudget: boolean;
+    };
+    readonly budgetMs?: number;
 }
 export interface ModEventRow {
     readonly side: ModEventSide;
@@ -197,4 +202,9 @@ export declare function expandModPattern(pattern: unknown): {
 } | {
     readonly refusal: string;
 };
+export declare function expandOnSide(pattern: unknown, side: ModBusSide): {
+    readonly names: readonly ModEventName[];
+} | {
+    readonly refusal: string;
+};
 export declare function describe(value: unknown): string;