@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/mods/extension-call.js

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { ENGINE_ORIGIN } from "./kernel/index.js";
+const store = new AsyncLocalStorage();
+export function extensionCallOf(bus, toolCallId) {
+    const c = store.getStore();
+    return c !== undefined && c.live && c.bus === bus && (toolCallId === undefined || c.toolCallId === toolCallId) ? c : undefined;
+}
+export function requesterOf(bus, toolCallId) {
+    const c = extensionCallOf(bus, toolCallId);
+    return c !== undefined ? { requestedBy: Object.freeze({ kind: "extension", name: c.caller.origin.plugin }) } : {};
+}
+export function noteExtensionCallDenied(bus, toolCallId) {
+    const c = store.getStore();
+    if (c !== undefined && c.live && c.bus === bus && c.toolCallId === toolCallId)
+        c.denied = true;
+}
+export async function runExtensionCall(bus, toolCallId, caller, pipeline) {
+    const call = { bus, toolCallId, caller, live: true, denied: false };
+    try {
+        return await store.run(call, () => pipeline(call));
+    }
+    finally {
+        call.live = false;
+    }
+}
+export function legBusOf(bus, report) {
+    const leg = {
+        records: bus.records,
+        mounted: () => bus.mounted(),
+        hasHandlers: (event, participant) => bus.hasHandlers(event, participant),
+        dispatch: (event, e, options) => {
+            const c = store.getStore();
+            if (c === undefined || c.bus !== leg || options.frames !== undefined)
+                return bus.dispatch(event, e, options);
+            if (c.live)
+                return bus.dispatch(event, e, { ...options, frames: c.caller.frames, origin: c.caller.origin });
+            const reason = `${event}: raised under extension "${c.caller.origin.plugin}"'s call ${c.toolCallId}, which has ended — an event is not raised under a call that is over`;
+            report(new Error(`engine: ${reason} — the dispatch was not run`));
+            return Promise.resolve(Object.freeze({ kind: "failed", registration: ENGINE_ORIGIN.plugin, cause: "violation", reason, skipped: Object.freeze([]) }));
+        },
+    };
+    return leg;
+}

package/dist/core/mods/kernel/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";
 /** A frame on the dispatch stack: a registration's own `$` call, or one of its handlers running. */
 export type ModFrame = {
     readonly kind: "dollar";
@@ -28,6 +28,13 @@ export interface ModMethodSeat {
     readonly enter?: (args: ModEventPayload) => ModEventPayload;
 }
 export type ModMethodBottoms = Partial<Record<ModEventName, ModMethodSeat>>;
+/**
+ * A callable event's host entry: what a `$` call of the event reaches. It runs whatever stands before the event and
+ * raises the event once at its own station, under `ctx.frames` and `ctx.origin` (so the caller's own handlers stay out
+ * of that raise); its answer is the call's answer (a `{ deny }` is returned, not thrown) and its throw the caller's.
+ */
+export type ModCallEntry = (args: ModEventPayload, ctx: ModBottomContext) => unknown;
+export type ModCallEntries = Partial<Record<ModEventName, ModCallEntry>>;
 export type ModDispatchOutcome = {
     readonly kind: "answered";
     readonly answer: unknown;
@@ -39,8 +46,12 @@ export type ModDispatchOutcome = {
     readonly cause: ModFailureCause;
     readonly reason: string;
     readonly skipped: readonly ModSkip[];
-} | {
+}
+/** `bottomStarted`: the chain's bottom had started when the dispatch was cancelled — on an effect event, what it did is
+ *  not known from here. */
+ | {
     readonly kind: "aborted";
+    readonly bottomStarted?: true;
 };
 /** What a participant filter sees of one mounted handler: its registration, that registration's seat, and whether it only observes. */
 export interface ModParticipant {
@@ -57,6 +68,9 @@ export interface ModDispatchOptions {
     readonly origin?: ModOrigin;
     /** The raiser's reading of an answer; an answer it refuses is a violation of the site. */
     readonly checkAnswer?: ModAnswerCheck;
+    /** The station's ranking of its answers — named by every dispatch of an event whose failure column refuses (one that
+     *  names none is not run), and read by the seat-trust law. */
+    readonly ranks?: ModAnswerRanks;
     /** Which mounted handlers take part (absent ⇒ every handler on the event). A handler it leaves out neither runs nor observes. */
     readonly participant?: (p: ModParticipant) => boolean;
 }
@@ -76,12 +90,15 @@ export interface ModBus {
     mounted(): readonly ModMountedHandler[];
     /** Whether any mounted handler hangs on `event` (among those `participant` admits) — no handler, no dispatch (the station skips the call). */
     hasHandlers(event: ModEventName, participant?: (p: ModParticipant) => boolean): boolean;
-    dispatch(event: ModEventName, e: ModEventPayload, options: ModDispatchOptions): Promise<ModDispatchOutcome>;
+    /** Raise `event` with the raiser's `e` (an object the bus receives whole, an event map's `e` as it is). */
+    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;
+    /** The host's entries of the callable events its bus raises (absent ⇒ none: a `$` call of such an event throws). */
+    readonly entries?: ModCallEntries;
     /** Where handler failures go (the host's error channel). Never throws back into the bus. */
     readonly report: (err: Error, classification?: "observational-hook-verdict-ignored") => void;
     /** The host's one rule for turning a THROWN value into text (a handler, a `.catch` or a `register` may throw

package/dist/core/mods/kernel/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/core/mods/kernel/events.d.ts

@@ -10,12 +10,19 @@
  * The kernel CONTRACT number — a monotonic integer, independent of the package version (the package is
  * cut with core every release; this number is not). It is exported for a host that loads a kernel copy
  * beside another one to compare for EQUALITY; nothing in this folder or in the engine reads it, so two
- * copies that differ are not detected here. It is raised when, and only when, one of four things changes:
- * the chain semantics (`next`, `next.to`, origin, trace, re-entry frames), the registration form (`ModRegistration`, `on`, `uses`),
- * the event closed set (names and their `side`), or the failure columns (failure, abort, pinned keys — which keys,
- * and how a pinned key is judged: by value since 2).
+ * copies that differ are not detected here. It is raised when, and only when, one of four things changes —
+ * once per release, however many of them change in it:
+ * the chain semantics (`next`, `next.to`, origin, trace, re-entry frames, what a `$` call reaches — a method's
+ * chain or a callable event's host entry — what a dispatch records of its run, how answers are received and which
+ * seat's answer may stand over which), the registration form (`ModRegistration`, `on`, `uses` and which names a side
+ * takes in it), the event closed set (names and their `side`), or the failure columns (failure, abort, pinned keys,
+ * an event's own budget ceiling, whether `$` may call it — which keys, and how a pinned key is judged: by value since 2).
+ * 3: the shell's events have stations, the event-level budget and `call` columns, a `$` call of a callable event
+ * reaches the host's entry, the dispatch records whether its bottom started, a re-entered guard with no `.catch`
+ * refuses, the one side lock over `uses` and `on`, answers received as data, the seat-trust law, `prompt.mention`
+ * on the engine's side, and `tool.call` with the `refuse_until_run` failure answer, callable.
  */
-export declare const KERNEL_CONTRACT_VERSION = 2;
+export declare const KERNEL_CONTRACT_VERSION = 3;
 /** The five tiers in run order (CC names). `builtin` and `core` are the engine's own. */
 export declare const MOD_TIERS: readonly ["prepend", "user", "append", "builtin", "core"];
 export type ModTier = (typeof MOD_TIERS)[number];
@@ -29,9 +36,15 @@ export declare const MOD_EVENT_SIDES: readonly ["engine", "surface", "both"];
 export type ModEventSide = (typeof MOD_EVENT_SIDES)[number];
 /** A bus is one side. */
 export type ModBusSide = Exclude<ModEventSide, "both">;
-/** What a handler's failure means for the dispatch: the station's refusal (final), or skip the handler. */
-export declare const MOD_FAILURE_ANSWERS: readonly ["refuse", "skip"];
+/**
+ * What a handler's failure means for the dispatch: the station's refusal (final); skip the handler; or — on an event
+ * whose chain bottom is an effect (a tool runs) — the refusal while the bottom has not started and, once it has, what
+ * the bottom did stands (the failure is reported beside the real result, which it never replaces).
+ */
+export declare const MOD_FAILURE_ANSWERS: readonly ["refuse", "skip", "refuse_until_run"];
 export type ModFailureAnswer = (typeof MOD_FAILURE_ANSWERS)[number];
+/** Whether a failure column refuses: the events a station judges on (or runs an effect behind) fail closed. */
+export declare function failureRefuses(failure: ModFailureAnswer): boolean;
 /** What a cancel does to a dispatch: end it now, give it one second, or follow the calling handler. */
 export declare const MOD_ABORT_POSTURES: readonly ["immediate", "grace", "caller"];
 export type ModAbortPosture = (typeof MOD_ABORT_POSTURES)[number];
@@ -56,7 +69,12 @@ export declare const SEAT_TIER_TABLE: Readonly<{
         tiers: readonly ["user"];
     }>;
 }>;
-/** The station columns of an event a bus raises. `method` marks a `$` method (the event a `$` call raises). */
+/**
+ * The station columns of an event a bus raises. `method` marks a `$` method (the event a `$` call raises; its chain
+ * bottom is the host's seat). `call` marks an event `$` may call: the call goes to the host's entry for the event,
+ * which runs whatever stands before it and raises it once at its own station. A row is a method, a callable event, or
+ * neither — never both.
+ */
 export interface ModStation {
     readonly failure: ModFailureAnswer;
     readonly abort: ModAbortPosture;
@@ -66,6 +84,12 @@ export interface ModStation {
     readonly method?: {
         readonly pausesCallerBudget: boolean;
     };
+    readonly call?: {
+        readonly pausesCallerBudget: boolean;
+    };
+    /** The event's own ceiling on a handler's time: every clock a handler runs under on this event (its body, its
+     *  `.catch`, an observer) is the smaller of its own and this — a registration's budget never widens it. */
+    readonly budgetMs?: number;
 }
 /** One event: its side, and its station when a bus raises it in this version (absent ⇒ named, not raised). */
 export interface ModEventRow {
@@ -75,9 +99,10 @@ export interface ModEventRow {
 /**
  * Every event the kernel knows: the reference's closed set of 142 names (CC 2.1.296 `J3e` (cli296.js:238573) — its 33 `classic.*` names,
  * its 46 engine events and its 63 `$` methods, in its own order). The shell's names (`ui.*`, `command.*`,
- * `config.*`, `audio.*`, the prompt-box events and `prompt.read`) carry `side: "surface"`, so one table serves both
- * buses and the shell fills their stations. A row with a station is raised on its side in this version; a name with
- * none is named, not raised, and a registration that selects only such names is refused.
+ * `config.*`, `audio.*`, the prompt-box events and `prompt.read`) carry `side: "surface"`: one table serves both
+ * buses, and the shell's stations are its rows here, raised by the shell where their chain bottoms are. A row with a
+ * station is raised on its side in this version; a name with none is named, not raised, and a registration that
+ * selects only such names is refused.
  */
 export declare const MOD_EVENT_TABLE: Readonly<{
     "classic.PreToolUse": ModEventRow;
@@ -241,5 +266,16 @@ export declare function expandModPattern(pattern: unknown): {
 } | {
     readonly refusal: string;
 };
+/**
+ * The names a pattern selects on a bus of `side` — the ONE side lock, read alike by `uses.events`, `uses.calls` and
+ * `on()`: an exact name the other side's bus reads (neither this side nor `both`) is refused (it is that bus's name, never
+ * usable here); a `<prefix>.*` pattern selects the names under the prefix this side reads and must select one. A name
+ * of this side that no station raises in this version is selected all the same (a forward declaration).
+ */
+export declare function expandOnSide(pattern: unknown, side: ModBusSide): {
+    readonly names: readonly ModEventName[];
+} | {
+    readonly refusal: string;
+};
 /** A safe one-word description of a host value for a sentence (never calls the value's own toString). */
 export declare function describe(value: unknown): string;