@sema-agent/core 7.51.2 → 7.52.0

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

@@ -0,0 +1,242 @@
+/**
+ * The mods kernel's closed vocabulary: tiers, seats, sides, the `next.to` allow table, the seat × tier
+ * table, and the ONE event table every other rule reads (which events exist, which side's bus raises
+ * them, and — for the ones a station raises — the failure, abort and pinned-key columns).
+ *
+ * Zero-dependency on purpose: this folder is compiled on its own into `@sema-agent/mods-kernel`, so the
+ * engine and the shell run the same rules. It imports nothing outside the folder.
+ */
+/**
+ * The kernel CONTRACT number — a monotonic integer, independent of the package version (the package is
+ * cut with core every release; this number is not). Every party that loads a kernel copy compares it for
+ * EQUALITY. 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).
+ */
+export declare const KERNEL_CONTRACT_VERSION = 1;
+/** 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];
+/** The tiers a registration may stand in. */
+export type ModRegistrationTier = Exclude<ModTier, "builtin" | "core">;
+/** Where a registration came from: the deployment's deps or the task's spec — listed most trusted first. */
+export declare const MOD_SEATS: readonly ["deployment", "task"];
+export type ModSeat = (typeof MOD_SEATS)[number];
+/** Which bus raises an event: the engine's, the shell's, or each its own. */
+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"];
+export type ModFailureAnswer = (typeof MOD_FAILURE_ANSWERS)[number];
+/** 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];
+/** `next.to(e, to)` from a handler in tier `from` is allowed iff `to` is in `NEXT_TO_TABLE[from]` (CC `pvt`). */
+export declare const NEXT_TO_TABLE: Readonly<{
+    prepend: readonly ["append", "builtin", "core"];
+    user: readonly [];
+    append: readonly ["core"];
+    builtin: readonly [];
+    core: readonly [];
+}>;
+/** Why `next.to(e, to)` from `from` is refused, or undefined when the table allows it. */
+export declare function nextToRefusal(from: ModTier, to: unknown): string | undefined;
+/** Which tiers each seat may declare, and whether it must declare one (absent ⇒ the first listed). */
+export declare const SEAT_TIER_TABLE: Readonly<{
+    deployment: Readonly<{
+        declared: "required";
+        tiers: readonly ["prepend", "user", "append"];
+    }>;
+    task: Readonly<{
+        declared: "optional";
+        tiers: readonly ["user"];
+    }>;
+}>;
+/** The station columns of an event a bus raises. `method` marks a `$` method (the event a `$` call raises). */
+export interface ModStation {
+    readonly failure: ModFailureAnswer;
+    readonly abort: ModAbortPosture;
+    /** Keys a handler may not change when it passes `e` on through `next`. */
+    readonly pinned: readonly string[];
+    readonly method?: {
+        readonly pausesCallerBudget: boolean;
+    };
+}
+/** One event: its side, and its station when a bus raises it in this version (absent ⇒ named, not raised). */
+export interface ModEventRow {
+    readonly side: ModEventSide;
+    readonly station?: ModStation;
+}
+/**
+ * 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.
+ */
+export declare const MOD_EVENT_TABLE: Readonly<{
+    "classic.PreToolUse": ModEventRow;
+    "classic.PostToolUse": ModEventRow;
+    "classic.PostToolUseFailure": ModEventRow;
+    "classic.PostToolBatch": ModEventRow;
+    "classic.Notification": ModEventRow;
+    "classic.UserPromptSubmit": ModEventRow;
+    "classic.UserPromptExpansion": ModEventRow;
+    "classic.SessionStart": ModEventRow;
+    "classic.SessionEnd": ModEventRow;
+    "classic.Stop": ModEventRow;
+    "classic.StopFailure": ModEventRow;
+    "classic.SubagentStart": ModEventRow;
+    "classic.SubagentStop": ModEventRow;
+    "classic.PreCompact": ModEventRow;
+    "classic.PostCompact": ModEventRow;
+    "classic.PreModelSwitch": ModEventRow;
+    "classic.PostModelSwitch": ModEventRow;
+    "classic.PermissionRequest": ModEventRow;
+    "classic.PermissionDenied": ModEventRow;
+    "classic.Setup": ModEventRow;
+    "classic.TeammateIdle": ModEventRow;
+    "classic.TaskCreated": ModEventRow;
+    "classic.TaskCompleted": ModEventRow;
+    "classic.Elicitation": ModEventRow;
+    "classic.ElicitationResult": ModEventRow;
+    "classic.ConfigChange": ModEventRow;
+    "classic.WorktreeCreate": ModEventRow;
+    "classic.WorktreeRemove": ModEventRow;
+    "classic.InstructionsLoaded": ModEventRow;
+    "classic.CwdChanged": ModEventRow;
+    "classic.FileChanged": ModEventRow;
+    "classic.DirectoryAdded": ModEventRow;
+    "classic.MessageDisplay": ModEventRow;
+    "tool.call": ModEventRow;
+    "tool.check": ModEventRow;
+    "ui.render": ModEventRow;
+    "ui.resolve": ModEventRow;
+    "ui.press": ModEventRow;
+    "ui.input": ModEventRow;
+    "ui.select": ModEventRow;
+    "ui.message": ModEventRow;
+    "ui.fault": ModEventRow;
+    "ui.scroll": ModEventRow;
+    "ui.focus": ModEventRow;
+    "agent.offer": ModEventRow;
+    "agent.spawn": ModEventRow;
+    "prompt.submit": ModEventRow;
+    "prompt.fill": ModEventRow;
+    "prompt.suggest": ModEventRow;
+    "prompt.edit": ModEventRow;
+    "prompt.autocomplete": ModEventRow;
+    "prompt.section": ModEventRow;
+    "prompt.context": ModEventRow;
+    "prompt.attachment": ModEventRow;
+    "prompt.mention": ModEventRow;
+    "prompt.compose": ModEventRow;
+    "tool.describe": ModEventRow;
+    "command.run": ModEventRow;
+    "command.describe": ModEventRow;
+    "config.set": ModEventRow;
+    "config.describe": ModEventRow;
+    "telemetry.log": ModEventRow;
+    "telemetry.mark": ModEventRow;
+    "skill.prompt": ModEventRow;
+    "attribution.text": ModEventRow;
+    "session.start": ModEventRow;
+    "session.receive": ModEventRow;
+    "session.append": ModEventRow;
+    "session.send": ModEventRow;
+    "session.compact": ModEventRow;
+    "session.attach": ModEventRow;
+    "session.detach": ModEventRow;
+    "session.measure": ModEventRow;
+    "session.end": ModEventRow;
+    "plugin.register": Readonly<{
+        side: "both";
+        station: ModStation;
+    }>;
+    "turn.start": ModEventRow;
+    "turn.step": ModEventRow;
+    "turn.complete": ModEventRow;
+    "engine.create": ModEventRow;
+    "model.complete": ModEventRow;
+    "model.classify": ModEventRow;
+    "model.fork": ModEventRow;
+    "audio.play": ModEventRow;
+    "audio.speak": ModEventRow;
+    "mcp.call": ModEventRow;
+    "mcp.connect": ModEventRow;
+    "session.cwd": ModEventRow;
+    "session.root": ModEventRow;
+    "session.model": ModEventRow;
+    "session.turns": ModEventRow;
+    "session.id": ModEventRow;
+    "session.messages": ModEventRow;
+    "session.repo": ModEventRow;
+    "session.surface": ModEventRow;
+    "session.surfaces": ModEventRow;
+    "session.authorize": ModEventRow;
+    "session.usage": ModEventRow;
+    "session.version": ModEventRow;
+    "turn.abort": ModEventRow;
+    "prompt.read": ModEventRow;
+    "flag.value": ModEventRow;
+    "tool.list": ModEventRow;
+    "tool.register": ModEventRow;
+    "command.list": ModEventRow;
+    "command.register": ModEventRow;
+    "config.list": ModEventRow;
+    "agent.list": ModEventRow;
+    "agent.register": ModEventRow;
+    "ui.toast": ModEventRow;
+    "ui.status": ModEventRow;
+    "ui.log": ModEventRow;
+    "ui.notice": ModEventRow;
+    "ui.invalidate": ModEventRow;
+    "ui.open": ModEventRow;
+    "ui.close": ModEventRow;
+    "ui.panes": ModEventRow;
+    "ui.selection": ModEventRow;
+    "ui.copy": ModEventRow;
+    "ui.notify": ModEventRow;
+    "ui.blit": ModEventRow;
+    "fs.read": ModEventRow;
+    "fs.write": ModEventRow;
+    "fs.list": ModEventRow;
+    "fs.exists": ModEventRow;
+    "fs.stat": ModEventRow;
+    "fs.ancestors": ModEventRow;
+    "store.get": ModEventRow;
+    "store.set": ModEventRow;
+    "store.delete": ModEventRow;
+    "store.keys": ModEventRow;
+    "state.get": ModEventRow;
+    "state.set": ModEventRow;
+    "clock.now": ModEventRow;
+    "clock.sleep": ModEventRow;
+    "clock.after": ModEventRow;
+    "clock.every": ModEventRow;
+    "http.fetch": ModEventRow;
+    "process.run": ModEventRow;
+    "process.spawn": ModEventRow;
+    "settings.read": ModEventRow;
+    "env.get": ModEventRow;
+    "env.set": ModEventRow;
+}>;
+export type ModEventName = keyof typeof MOD_EVENT_TABLE;
+export declare function isModEventName(name: unknown): name is ModEventName;
+/** The row's station when a bus of `side` raises it; undefined otherwise. */
+export declare function stationOn(name: ModEventName, side: ModBusSide): ModStation | undefined;
+/** Whether a bus of `side` reads `name` at all (its own side or both). */
+export declare function readOnSide(name: ModEventName, side: ModBusSide): boolean;
+/**
+ * The known names a pattern selects: an exact name, or `<prefix>.*` for every name under the prefix.
+ * A pattern that selects no known name is refused (a typo is not an empty declaration).
+ */
+export declare function expandModPattern(pattern: unknown): {
+    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;

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

@@ -0,0 +1,210 @@
+export const KERNEL_CONTRACT_VERSION = 1;
+export const MOD_TIERS = Object.freeze(["prepend", "user", "append", "builtin", "core"]);
+export const MOD_SEATS = Object.freeze(["deployment", "task"]);
+export const MOD_EVENT_SIDES = Object.freeze(["engine", "surface", "both"]);
+export const MOD_FAILURE_ANSWERS = Object.freeze(["refuse", "skip"]);
+export const MOD_ABORT_POSTURES = Object.freeze(["immediate", "grace", "caller"]);
+export const NEXT_TO_TABLE = Object.freeze({
+    prepend: Object.freeze(["append", "builtin", "core"]),
+    user: Object.freeze([]),
+    append: Object.freeze(["core"]),
+    builtin: Object.freeze([]),
+    core: Object.freeze([]),
+});
+const CONTINUABLE = NEXT_TO_TABLE.prepend;
+export function nextToRefusal(from, to) {
+    const allowed = NEXT_TO_TABLE[from];
+    const named = CONTINUABLE.find((t) => t === to);
+    if (named === undefined)
+        return `next.to names ${describe(to)}, which is not a tier a dispatch continues at (${CONTINUABLE.join(", ")})`;
+    if (allowed.length === 0)
+        return `next.to is available to prepend and append handlers only, not to a ${from} handler`;
+    if (!allowed.includes(named))
+        return `next.to("${named}") skips nothing from ${from}; a ${from} handler may continue at ${allowed.join(", ")}`;
+    return undefined;
+}
+export const SEAT_TIER_TABLE = Object.freeze({
+    deployment: Object.freeze({ declared: "required", tiers: Object.freeze(["prepend", "user", "append"]) }),
+    task: Object.freeze({ declared: "optional", tiers: Object.freeze(["user"]) }),
+});
+const station = (failure, abort, pinned = []) => Object.freeze({ failure, abort, pinned: Object.freeze([...pinned]) });
+const method = (pausesCallerBudget) => Object.freeze({ failure: "skip", abort: "caller", pinned: Object.freeze([]), method: Object.freeze({ pausesCallerBudget }) });
+const engine = (s) => Object.freeze(s === undefined ? { side: "engine" } : { side: "engine", station: s });
+const surface = Object.freeze({ side: "surface" });
+export const MOD_EVENT_TABLE = Object.freeze({
+    "classic.PreToolUse": engine(station("refuse", "immediate", ["tool", "tool_use_id", "agentId", "input"])),
+    "classic.PostToolUse": engine(station("skip", "grace")),
+    "classic.PostToolUseFailure": engine(station("skip", "grace")),
+    "classic.PostToolBatch": engine(station("skip", "grace")),
+    "classic.Notification": engine(),
+    "classic.UserPromptSubmit": engine(station("refuse", "immediate", ["source", "inputId", "actor", "prompt"])),
+    "classic.UserPromptExpansion": engine(),
+    "classic.SessionStart": engine(),
+    "classic.SessionEnd": engine(),
+    "classic.Stop": engine(station("skip", "immediate")),
+    "classic.StopFailure": engine(station("skip", "grace")),
+    "classic.SubagentStart": engine(),
+    "classic.SubagentStop": engine(station("skip", "immediate")),
+    "classic.PreCompact": engine(station("skip", "grace")),
+    "classic.PostCompact": engine(station("skip", "grace")),
+    "classic.PreModelSwitch": engine(),
+    "classic.PostModelSwitch": engine(),
+    "classic.PermissionRequest": engine(),
+    "classic.PermissionDenied": engine(station("skip", "grace")),
+    "classic.Setup": engine(),
+    "classic.TeammateIdle": engine(),
+    "classic.TaskCreated": engine(),
+    "classic.TaskCompleted": engine(),
+    "classic.Elicitation": engine(),
+    "classic.ElicitationResult": engine(),
+    "classic.ConfigChange": engine(),
+    "classic.WorktreeCreate": engine(),
+    "classic.WorktreeRemove": engine(),
+    "classic.InstructionsLoaded": engine(),
+    "classic.CwdChanged": engine(),
+    "classic.FileChanged": engine(),
+    "classic.DirectoryAdded": engine(),
+    "classic.MessageDisplay": engine(),
+    "tool.call": engine(),
+    "tool.check": engine(station("refuse", "immediate", ["tool", "input", "tool_use_id", "agentId", "ceiling"])),
+    "ui.render": surface,
+    "ui.resolve": surface,
+    "ui.press": surface,
+    "ui.input": surface,
+    "ui.select": surface,
+    "ui.message": surface,
+    "ui.fault": surface,
+    "ui.scroll": surface,
+    "ui.focus": surface,
+    "agent.offer": engine(),
+    "agent.spawn": engine(),
+    "prompt.submit": engine(),
+    "prompt.fill": surface,
+    "prompt.suggest": surface,
+    "prompt.edit": surface,
+    "prompt.autocomplete": surface,
+    "prompt.section": engine(station("skip", "grace", ["name", "key", "mountedTools"])),
+    "prompt.context": engine(),
+    "prompt.attachment": engine(),
+    "prompt.mention": surface,
+    "prompt.compose": engine(station("skip", "grace", ["model"])),
+    "tool.describe": engine(),
+    "command.run": surface,
+    "command.describe": surface,
+    "config.set": surface,
+    "config.describe": surface,
+    "telemetry.log": engine(),
+    "telemetry.mark": engine(),
+    "skill.prompt": engine(),
+    "attribution.text": engine(),
+    "session.start": engine(),
+    "session.receive": engine(),
+    "session.append": engine(),
+    "session.send": engine(),
+    "session.compact": engine(),
+    "session.attach": engine(),
+    "session.detach": engine(),
+    "session.measure": engine(),
+    "session.end": engine(),
+    "plugin.register": Object.freeze({ side: "both", station: station("skip", "immediate", ["name", "seat", "tier", "uses"]) }),
+    "turn.start": engine(),
+    "turn.step": engine(),
+    "turn.complete": engine(),
+    "engine.create": engine(),
+    "model.complete": engine(method(true)),
+    "model.classify": engine(),
+    "model.fork": engine(),
+    "audio.play": surface,
+    "audio.speak": surface,
+    "mcp.call": engine(),
+    "mcp.connect": engine(),
+    "session.cwd": engine(method(true)),
+    "session.root": engine(method(true)),
+    "session.model": engine(method(true)),
+    "session.turns": engine(),
+    "session.id": engine(method(true)),
+    "session.messages": engine(method(true)),
+    "session.repo": engine(),
+    "session.surface": engine(),
+    "session.surfaces": engine(),
+    "session.authorize": engine(),
+    "session.usage": engine(),
+    "session.version": engine(),
+    "turn.abort": engine(),
+    "prompt.read": surface,
+    "flag.value": engine(),
+    "tool.list": engine(method(true)),
+    "tool.register": engine(),
+    "command.list": surface,
+    "command.register": surface,
+    "config.list": surface,
+    "agent.list": engine(method(true)),
+    "agent.register": engine(),
+    "ui.toast": surface,
+    "ui.status": surface,
+    "ui.log": surface,
+    "ui.notice": surface,
+    "ui.invalidate": surface,
+    "ui.open": surface,
+    "ui.close": surface,
+    "ui.panes": surface,
+    "ui.selection": surface,
+    "ui.copy": surface,
+    "ui.notify": surface,
+    "ui.blit": surface,
+    "fs.read": engine(),
+    "fs.write": engine(),
+    "fs.list": engine(),
+    "fs.exists": engine(),
+    "fs.stat": engine(),
+    "fs.ancestors": engine(),
+    "store.get": engine(),
+    "store.set": engine(),
+    "store.delete": engine(),
+    "store.keys": engine(),
+    "state.get": engine(),
+    "state.set": engine(),
+    "clock.now": engine(method(false)),
+    "clock.sleep": engine(method(false)),
+    "clock.after": engine(),
+    "clock.every": engine(),
+    "http.fetch": engine(),
+    "process.run": engine(method(true)),
+    "process.spawn": engine(),
+    "settings.read": engine(),
+    "env.get": engine(),
+    "env.set": engine(),
+});
+const EVENT_NAMES = Object.freeze(Object.keys(MOD_EVENT_TABLE).filter(isModEventName));
+export function isModEventName(name) {
+    return typeof name === "string" && Object.prototype.hasOwnProperty.call(MOD_EVENT_TABLE, name);
+}
+export function stationOn(name, side) {
+    const row = MOD_EVENT_TABLE[name];
+    return row.side === side || row.side === "both" ? row.station : undefined;
+}
+export function readOnSide(name, side) {
+    const row = MOD_EVENT_TABLE[name];
+    return row.side === side || row.side === "both";
+}
+export function expandModPattern(pattern) {
+    if (typeof pattern !== "string" || pattern === "")
+        return { refusal: `${describe(pattern)} is not an event name or a "<prefix>.*" pattern` };
+    if (pattern.endsWith(".*")) {
+        const prefix = pattern.slice(0, -2);
+        if (prefix === "" || prefix.includes("*"))
+            return { refusal: `"${pattern}" is not an event name or a "<prefix>.*" pattern` };
+        const names = EVENT_NAMES.filter((n) => n.startsWith(`${prefix}.`));
+        return names.length > 0 ? { names } : { refusal: `"${pattern}" selects no event` };
+    }
+    return isModEventName(pattern) ? { names: [pattern] } : { refusal: `"${pattern}" is not an event` };
+}
+export function describe(value) {
+    if (typeof value === "string")
+        return `"${value}"`;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (value === null)
+        return "null";
+    return typeof value === "object" ? (Array.isArray(value) ? "an array" : "an object") : typeof value;
+}

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

@@ -0,0 +1,6 @@
+/** The package entry of `@sema-agent/mods-kernel`; core reads the same modules directly. */
+export { KERNEL_CONTRACT_VERSION, MOD_TIERS, MOD_SEATS, MOD_EVENT_SIDES, MOD_FAILURE_ANSWERS, MOD_ABORT_POSTURES, NEXT_TO_TABLE, SEAT_TIER_TABLE, MOD_EVENT_TABLE, nextToRefusal, expandModPattern, isModEventName, stationOn, readOnSide, type ModTier, type ModRegistrationTier, type ModSeat, type ModEventSide, type ModBusSide, type ModFailureAnswer, type ModAbortPosture, type ModStation, type ModEventRow, type ModEventName, } from "./events.js";
+export { DEFAULT_MOD_BUDGET_MS, CATCH_BUDGET_MS, RUNAWAY_AFTER_MS, POST_ABORT_GRACE_MS, MAX_TIMER_MS, resolveModBudgetMs, type ModBudgetReading, } from "./budget.js";
+export { MOD_FAILURE_CAUSES, type ModFailureCause, type ModEventPayload, type ModAnswerCheck, type ModAnswerer, type ModMatcher, type ModSkip } from "./site-rules.js";
+export { ENGINE_ORIGIN, MODS_INVALID_CODE, MODS_REGISTRATION_REFUSED_CODE, MOD_TRACE_OUTCOMES, type ModTraceOutcome, type ModUses, type ModOrigin, type ModPluginFacts, type ModDollarBase, type ModTraceEntry, type ModCaughtError, type ModNext, type ModHandler, type ModHandlerOptions, type On, type ModRegistration, type ModAdmissionRecord, type ModSeats, } from "./registration.js";
+export { admitMods, type ModFrame, type ModBottomContext, type ModMethodBottom, type ModMethodSeat, type ModMethodBottoms, type ModDispatchOutcome, type ModDispatchOptions, type ModBus, type ModMountedHandler, type ModBusInput, } from "./dispatch.js";

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

@@ -0,0 +1,5 @@
+export { KERNEL_CONTRACT_VERSION, MOD_TIERS, MOD_SEATS, MOD_EVENT_SIDES, MOD_FAILURE_ANSWERS, MOD_ABORT_POSTURES, NEXT_TO_TABLE, SEAT_TIER_TABLE, MOD_EVENT_TABLE, nextToRefusal, expandModPattern, isModEventName, stationOn, readOnSide, } from "./events.js";
+export { DEFAULT_MOD_BUDGET_MS, CATCH_BUDGET_MS, RUNAWAY_AFTER_MS, POST_ABORT_GRACE_MS, MAX_TIMER_MS, resolveModBudgetMs, } from "./budget.js";
+export { MOD_FAILURE_CAUSES } from "./site-rules.js";
+export { ENGINE_ORIGIN, MODS_INVALID_CODE, MODS_REGISTRATION_REFUSED_CODE, MOD_TRACE_OUTCOMES, } from "./registration.js";
+export { admitMods, } from "./dispatch.js";

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

@@ -0,0 +1,65 @@
+/**
+ * The ONE receipt of a caller's object: how a value someone else's code built becomes a value the receiver owns.
+ * Every reader of a caller's object reads it here — a constructor's configuration (`new Runner`'s deps, a brain's
+ * config), a station's answer record, a mods handler's payload and answer — each with its own mode, never its own
+ * copy of the walk.
+ *
+ * The walk: a primitive is itself. A CONTAINER — an ordinary record (prototype `Object.prototype` or none) or an
+ * ordinary array — within `depth` levels is copied member by member off its own property descriptors, captured in
+ * one call before any of the caller's code can run; each member lands as an enumerable data property of the copy (a
+ * defined property, never an assignment, so an own `__proto__` key stays a plain key). Anything else — a function, an
+ * object of another prototype, a container past `depth` — is handed as it is or refused, by `others`, which also
+ * says whether cycles and shared references keep their shape or are refused / walked again.
+ *
+ * Zero-dependency on purpose (this folder compiles on its own): a Proxy cannot be recognised from here, so the
+ * host passes its probe (`isProxy`); with a probe, a Proxy is refused before anything is asked of it.
+ */
+/** How a receipt reads. */
+export interface ReceiptMode {
+    /**
+     * `call-once`: every own string-keyed member is read — a data property's value, or an accessor's getter called exactly
+     * once on the object (a getter that throws refuses the receipt; one that moves the object's prototype refuses it).
+     * `refuse`: only own enumerable string-keyed DATA properties are members; an accessor, a non-enumerable property or
+     * a symbol-keyed one refuses the receipt (no getter ever runs).
+     */
+    readonly accessors: "call-once" | "refuse";
+    /** How many levels of containers are copied (`Infinity` = every level). */
+    readonly depth: number;
+    /** What a value that is not copied is (a function, another prototype, a container past `depth`, a symbol or a
+     *  bigint): handed as it is, or a refusal of the receipt. Shared references keep their shape in the copy (one copy
+     *  each); under `as-is` a cycle does too, under `refuse` a cycle is refused and a shared reference must fit `depth`
+     *  where it sits each time it is met. */
+    readonly others: "as-is" | "refuse";
+    /** Every container the copy makes is frozen (a received value cannot be changed after it was received). */
+    readonly freeze?: boolean;
+    /** The host's Proxy probe. */
+    readonly isProxy?: (value: object) => boolean;
+}
+/** Why a receipt was refused. */
+export declare const RECEIPT_FAULTS: readonly ["proxy", "accessor", "hidden", "getter-threw", "prototype-moved", "not-data", "cycle", "too-deep", "uncopyable"];
+export type ReceiptFaultKind = (typeof RECEIPT_FAULTS)[number];
+/** A refusal and where in the value it was met (member names from the top). */
+export interface ReceiptFault {
+    readonly kind: ReceiptFaultKind;
+    readonly path: readonly string[];
+}
+export type Receipt = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly fault: ReceiptFault;
+};
+/** Whether `v` is an ordinary record: an object whose prototype is `Object.prototype` or none (an array is not one). */
+export declare function isPlainRecord(v: unknown): v is Record<string, unknown>;
+/**
+ * Receive `value` by `mode`. `held` names objects the reader already owns: met in the walk, each is kept as itself
+ * (not received again) — so a member handed back unchanged keeps its identity.
+ */
+export declare function receive(value: unknown, mode: ReceiptMode, held?: Iterable<unknown>): Receipt;
+/** The mods bus's mode: a payload and an answer received whole — no accessor runs, no depth limit, cycles and shared
+ *  references kept, a function or a class instance handed as it is, every copied container frozen (so a member the
+ *  bus holds cannot be changed under it by a handler that holds it too). */
+export declare const MODS_PAYLOAD_MODE: ReceiptMode;
+/** One clause naming a fault for a sentence ("an accessor at input.deep.x"). */
+export declare function describeFault(fault: ReceiptFault): string;

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

@@ -0,0 +1,123 @@
+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();
+    if (held !== undefined)
+        for (const h of held)
+            if (typeof h === "object" && h !== null)
+                seen.set(h, h);
+    const path = [];
+    const open = new Set();
+    const heights = new Map();
+    const refuse = (kind) => {
+        throw { refused: Object.freeze({ kind, path: Object.freeze([...path]) }) };
+    };
+    const other = (v, kind) => (mode.others === "as-is" ? v : refuse(kind));
+    const walk = (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 (seen.has(v)) {
+            if (open.has(v))
+                return mode.others === "refuse" ? refuse("cycle") : seen.get(v);
+            if (mode.others === "refuse" && level + (heights.get(v) ?? 1) > mode.depth)
+                return refuse("too-deep");
+            return seen.get(v);
+        }
+        if (level >= mode.depth)
+            return other(v, "too-deep");
+        if (mode.isProxy?.(v) === true)
+            return refuse("proxy");
+        const list = isOrdinaryArray(v);
+        if (!list && !isPlainRecord(v))
+            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);
+        let height = 1;
+        if (mode.accessors === "refuse" && Object.getOwnPropertySymbols(captured).length > 0)
+            refuse("hidden");
+        for (const key of Object.getOwnPropertyNames(captured)) {
+            if (list && key === "length")
+                continue;
+            const d = captured[key];
+            path.push(key);
+            let member;
+            if (Object.hasOwn(d, "value")) {
+                if (mode.accessors === "refuse" && d.enumerable !== true)
+                    refuse("hidden");
+                member = d.value;
+            }
+            else {
+                if (mode.accessors === "refuse")
+                    refuse("accessor");
+                const get = Object.hasOwn(d, "get") ? d.get : undefined;
+                try {
+                    member = get === undefined ? undefined : get.call(v);
+                }
+                catch {
+                    return refuse("getter-threw");
+                }
+            }
+            Object.defineProperty(out, key, { value: walk(member, level + 1), enumerable: true, writable: true, configurable: true });
+            if (typeof member === "object" && member !== null)
+                height = Math.max(height, (heights.get(member) ?? 0) + 1);
+            path.pop();
+        }
+        heights.set(v, height);
+        if (mode.accessors === "call-once" && Object.getPrototypeOf(v) !== proto)
+            refuse("prototype-moved");
+        if (Array.isArray(out)) {
+            const length = captured["length"]?.value;
+            if (typeof length === "number")
+                out.length = length;
+        }
+        if (mode.freeze === true)
+            Object.freeze(out);
+        open.delete(v);
+        return out;
+    };
+    try {
+        return { ok: true, value: walk(value, 0) };
+    }
+    catch (err) {
+        if (typeof err === "object" && err !== null && "refused" in err)
+            return { ok: false, fault: err.refused };
+        return { ok: false, fault: Object.freeze({ kind: "uncopyable", path: Object.freeze([...path]) }) };
+    }
+}
+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}`;
+    }
+}