Class ExecutionContextApi

Defensive check for the immediate caller's class. Throws SecurityError on mismatch. Useful as belt-and-braces inside sensitive method bodies that already carry @CallSecurity.

Pretty-print the call stack for debugging. Intentionally human-formatted; do not parse this output.

Walk the stack top-to-bottom looking for the most recent frame tagged with kind. Returns null when no such frame exists.

Generic primitive that all kind-specific helpers wrap; reach for this directly when you want a custom walk (e.g., "find the topmost Command frame whose target is admin-flagged").

The principal on whose behalf the current work runs — the acting author — resolved transport-agnostically for authorship attribution, NEVER taken from a caller-supplied value (the only inputs are frames the framework itself stamps):

• in-game (command) path — the command-frame stack's giver, but only when the chain is non-forced and a single, consistent giver. A forced dispatch (CommandApi.forceCommand) or a cross-actor cascade (A's command triggering B) fails closed → null. This is "look at the giver AND the stack around it": the bare top giver is not trusted on its own.
• REST / CMS path — no Command frame, so the dispatched principal is whatever a transport boundary stamped via tagActingAuthor (the Avatar a session ran the op as). The stamp rides frame metadata, decoupled from the frame's security target, so a REST boundary can name its author without disturbing what downstream @CallSecurity gates resolve as the caller.

Returns the principal object (a Stuff) or null. The caller validates it is a real authoring identity (a durable templatePath). The deliberate centralization the provenance write relies on: one resolver, both transports, no trust in a passed argument.

Look up the immediate caller — the caller of the frame at the top of the stack. Returns null if there's no stack (called outside a run/runRoot wrapper) or if the top frame has a null caller.

Read the entire call stack as a frozen, read-only snapshot. Always returns an array (empty if no context).

Walk the call stack outermost-to-innermost and return every Command frame's contextual data. The returned tuples carry the frame's CommandContext (already includes commandId and executionId) plus the forced flag — true for system-fired commands invoked through CommandApi.forceCommand, false (or absent) for player-typed input.

Use this for "is the current command nested inside a forced command?" patterns: walk the result, check the forced flag, decide whether to short-circuit (e.g., a cinematic-locked NPC blocking auto-look). For the common "what fired me" question the sugar helper getParentCommandContext skips the boilerplate.

causingCommandId is deliberately NOT in the per-frame return — every Command frame's causingCommandId equals its own commandId by construction, so including it would mislead callers into using it as a parent-pointer (which it isn't). The async-boundary "originating command id" use case is served by the existing getCurrentCausingCommandId.

Walk the call stack top-down and return the first metadata.causingCommandId we hit. Set on the Command frame by CommandGiverMixin.executeCommand, and re-planted on a fresh Root frame by ScheduleApi when a propagating callback fires — either way, the live "originating command id" surfaces here.

The active CommandContext stamped onto the current Command frame's metadata, or null outside a command's synchronous span. Read by Scene.send() / MudlogApi to stamp meta.commandId and default the recipient to the command giver.

The most recent CommandGiver on the stack — the actor whose executeCommand body is currently running. Returns null outside any command pipeline.

Cross-pause caveat: command frames live inside the synchronous call chain. After a prompt resume / scheduled tick / cross-actor message, the chain rebuilds fresh and this returns null.

Look up the current target — the target of the frame at the top of the stack. Useful inside guarded method bodies to confirm this matches the framework's view.

Synchronous-stack relationship: the CommandContext of the command that fired the currently running command, or null when the current command is the outermost.

Distinct from causingCommandId. causingCommandId is the originating-command-id snapshot designed to propagate across async boundaries (ScheduleApi replants it on a fresh Root frame when a deferred callback fires). The parent context, by contrast, only exists while both commands share a synchronous span — once the outer command's executeCommand returns, no parent is reachable.

Push a frame and run fn with that frame on top of the stack.

If there's no enclosing context, this also creates a fresh stack; call sites that always need a root should use runRoot instead so the intent is explicit.

Used by:

• the Proxy, when intercepting a method call (no opts);
• StuffApi.#registerAndInit for the synthetic constructor frame ({ kind: FrameKind.Constructor }).

Body-side tagging (e.g., CommandGiver.executeCommand declaring "this frame is a command frame") goes through tagCurrentFrame(FrameKind.Command) instead — it mutates the proxy-pushed frame in place rather than stacking a redundant second frame.

Plant a synthetic root frame whose caller is null and run fn inside it. Used by Backend at the network → Application boundary so that Application's own entry-method frames appear above a well-defined root. Inside runRoot, getCaller() at the root level returns null.

Distinct from run() so the call-site intent is unambiguous: this is "I am the boundary, plant a root here," not "I'm pushing a frame on whatever happens to be on the stack."

Stamp the acting author — the principal (an Avatar) on whose behalf a non-command transport boundary is running — onto the current frame's metadata, where getActingAuthor reads it for the REST/CMS path.

The seam a REST boundary calls right after planting its runRoot frame (e.g. the CMS run-as-session-player bridge): it dispatches the execution context as a specific Avatar for authorship, WITHOUT making that Avatar the frame's security target (so downstream @CallSecurity gates are unaffected). Gated by the same frame-mutator allowlist as updateCurrentFrameMetadata — only framework / backend/ code may stamp. Throws when called outside any frame.

Stamp the top-of-stack frame with kind. Used by method bodies that want to declare "this frame, the one the proxy already pushed for me, has a recognised role." Throws SecurityError when called outside any frame context — tagging nothing is almost certainly a bug, fail loud.

Idempotent for the same kind. Re-tagging with a different kind overwrites; the framework doesn't enforce single-tag uniqueness because we don't yet have a use case for one frame carrying multiple roles.

Merge patch into the top-of-stack frame's metadata. Allocates a metadata object if one isn't already present. Used by the command lifecycle in CommandGiverMixin to stamp commandContext and causingCommandId onto its own (proxy-pushed) frame, and by ScheduleApi to plant attribution onto the Root frame it just created.

Gated by the same allowlist as tagCurrentFrame — only framework files may mutate frame metadata. Throws when called outside any frame context (mutating "no frame" is almost certainly a bug).