stack( ) → void

push(kind: string, meta: any?) → void

Push an origin span.

pop( ) → void

with(kind: string, fn: (...any) → void

Run `fn` inside a `kind` span, popping even on error. Returns fn's results.

current( ) → string

The current origin: explicit top-of-stack span wins; else infer scene-load from `__scene_load.inProgress()`; else the agent's `execute` context.

cache( ) → void

attrSetter( ) → any

tagEntity(id: string, kind: string?) → void

Stamp `id` with the current origin (or an explicit `kind`). Idempotent.

entityOrigin(id: string) → string

Read an entity's origin: cache first, then the durable attribute, then nil (untagged == created before tagging / by a path we don't wrap == treat as non-execute by callers).

isReproducedContext(origin: string?) → boolean

The reproduced-by-code contexts: an entity created here is re-created on the next load — by the entrypoint / scene construction, by a component callback, or by an engine-driven path (an assetType behavior composing an avatar, a bundle exploding its hierarchy) — so persist must NOT freeze it, else it duplicates.

shouldFreeze(id: string) → boolean

True iff persist should freeze this entity (gate by CREATION context). Saves everything EXCEPT reproduced-context creations. Untagged (execute, or any creation path we don't wrap) => saved. "What you see is what you get."

componentOrigin(entityId: string, componentType: string) → string

An entity's origin answers "who created this entity". A component instance carries its own answer: an entity the author placed can pick up components that CODE attached to it — a camera behavior a `Camera.behavior` write reconciles, the character-controller expansion an avatar bundle materializes on its host. Those re-attach from the same source on every load, so the authored scene record leaves them out; the engine records the attach context and reports it here. The recorded attach context of one component instance, or nil when an authoring path (the agent's `execute`, an editor tool) attached it.

componentDrivenFields(entityId: string) → void

The component fields on this entity whose live value a component callback wrote while the engine was in play, keyed by resolved component type name. A lamp component writing `Light.intensity` every frame puts `intensity` under `Light`; an authoring call writing that same field takes it back off. The values name the running simulation's state, which the play to edit flip restores from the scene, so a comparison of authored intent leaves them out.

shouldFreezeComponent(entityId: string, componentType: string) → boolean

True iff this component instance belongs in the authored scene record. Code-attached instances are reproduced on load, so recording them would duplicate them; everything else — including every instance attached before the record existed — is authored. Untagged means authored, so the failure mode is a redundant record rather than a silently dropped component.

tagAsset(ref: any, kind: string?) → void

Loose textures / meshes / materials forked under /runtime carry their origin in `.metadata` so persist's asset converter can tell which ones were made by the agent (and need promotion to /source) vs reproduced on load.

assetOrigin(ref: any) → string

installWrappers(entityNs: any) → void

Wrap the entity creation APIs so every creation is stamped with the origin of the context that created it. This drives "what you see is what you get": persist FREEZES everything by default and excludes only the provably code-reproduced (scene/onLoad- or component-spawned), so a tool/module that spawns 10 entities from the agent's execute() call still gets captured — it never silently disappears. We stamp the CURRENT origin (execute / scene / component). The freeze filter then keeps execute + untagged (the agent's work, via any path) and drops only fresh-id scene/component creations. Tagging is via `tagEntity` (cache + best-effort `__origin` attribute, `_`-prefixed so it never bakes into scene.json). A spawn that RESTORES an explicit id replays a record a store already holds, so it keeps that record's provenance rather than the replaying context's. Idempotent + fully guarded: a wrap failure (e.g. a sealed namespace) degrades to "no auto-tag for that fn" and never breaks engine boot.

tagCurrent(id: any) → void

idOf(value: any) → string

Read the id off a creation result. The creation calls answer in two shapes: `spawn` / `spawnSynced` hand back an entity PROXY, which keeps its id in a raw `__id` slot, and `duplicate` / `batchSpawn` / `instantiate` hand back the id string(s). One reader covers both, so a call that changes which shape it answers with stays tagged.

restoresId(a: any, b: any) → boolean

True when this spawn call restores an id: `entity.spawn(name, opts)` / `entity.spawn(opts)` with `opts.id` set. The id then belongs to a record some store already holds — the scene body the loader is replaying, a relay snapshot — so the record's own provenance stands and the context replaying it leaves the stamp alone.

wrapSpawn(name: string) → void

wrapId(name: string) → void

wrapIds(name: string) → void