@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/in-the-dark/Kernel.js

@@ -1,19 +1,15 @@
-import { emit, eventize, off, on, once, Priority } from "@spearwolf/eventize";
-import {
-  batch,
-  createEffect,
-  createMemo,
-  createSignal,
-  destroySignal,
-  isSignal,
-  link
-} from "@spearwolf/signalize";
+import { emitSafe, emitStrict, eventize, off, on } from "@spearwolf/eventize";
+import { batch } from "@spearwolf/signalize";
+import { ChangeTrailRefusedError } from "../ChangeTrailRefusedError.js";
 import { ComponentChangeType, MessageToView } from "../constants.js";
+import { EntityUuidInUseError } from "../EntityUuidInUseError.js";
 import { ConsoleLogger } from "../utils/ConsoleLogger.js";
-import { toMaybe } from "../utils/toMaybe.js";
+import { runGuarded } from "../utils/runGuarded.js";
+import { getDisplayName } from "./displayName.js";
 import { Entity } from "./Entity.js";
 import { onCreate, onDestroy, onParentChanged, onViewEvent } from "./events.js";
 import { Registry } from "./Registry.js";
+import { ShadowObjectCreationScope } from "./ShadowObjectCreationScope.js";
 import { SignalsPath } from "./SignalsPath.js";
 var ShadowObjectAction = /* @__PURE__ */ ((ShadowObjectAction2) => {
   ShadowObjectAction2[ShadowObjectAction2["CreateAndDestroy"] = 0] = "CreateAndDestroy";
@@ -21,38 +17,69 @@ var ShadowObjectAction = /* @__PURE__ */ ((ShadowObjectAction2) => {
   ShadowObjectAction2[ShadowObjectAction2["DestroyOnly"] = 2] = "DestroyOnly";
   return ShadowObjectAction2;
 })(ShadowObjectAction || {});
-const getDisplayName = (construct) => construct.displayName || construct.name;
-let provideContextOptionsDeprecatedShown = false;
-let provideGlobalContextOptionsDeprecatedShown = false;
-let useContextOptionsDeprecatedShown = false;
-let useParentContextOptionsDeprecatedShown = false;
-let usePropertyOptionsDeprecatedShown = false;
+const LIFECYCLE_HOOKS = [
+  ["onCreate", onCreate],
+  ["onDestroy", onDestroy],
+  ["onParentChanged", onParentChanged],
+  ["onViewEvent", onViewEvent]
+];
 class Kernel {
+  #logger = new ConsoleLogger("Kernel");
+  /** The logger this Kernel reports through. */
+  get logger() {
+    return this.#logger;
+  }
+  #entities = /* @__PURE__ */ new Map();
+  #rootEntities = /* @__PURE__ */ new Set();
+  #allEntities = [];
+  #allEntitiesReversed = [];
+  #allEntitiesNeedUpdate = true;
+  #rootContexts = /* @__PURE__ */ new Map();
+  /**
+   * The creation scope of a shadow-object, keyed by the shadow-object itself.
+   *
+   * `#destroyShadowObject()` needs to reach the scope from the outside when a shadow-object leaves the
+   * constructor set of an entity that stays alive. The scope removes its own entry when it tears down,
+   * so nothing here outlives the shadow-object it belongs to.
+   *
+   * The key is the shadow-object instance, which assumes one instance per construction. A
+   * constructor handing out the same instance twice — to a second entity, or to the same one
+   * under another token — leaves only the later scope reachable from here; the earlier one
+   * still tears down when its entity is destroyed.
+   */
+  #shadowObjectScopes = /* @__PURE__ */ new WeakMap();
+  // The member names whose deprecation report this kernel has already made, one entry each. Handed
+  // to every creation scope this kernel builds, which is what gives the report the lifetime of the
+  // kernel rather than that of this module: an application running two shadow environments would
+  // otherwise report the deprecated call form to whichever of them got there first and to no other.
+  // One entry per name rather than a single flag, because a flag would swallow the reports of the
+  // four members that come after the first. `destroy()` leaves the set alone -- a kernel that has
+  // said it once has said it.
+  #shownDeprecations = /* @__PURE__ */ new Set();
   constructor(registry) {
-    this.logger = new ConsoleLogger("Kernel");
-    this.#entities = /* @__PURE__ */ new Map();
-    this.#rootEntities = /* @__PURE__ */ new Set();
-    this.#allEntities = [];
-    this.#allEntitiesReversed = [];
-    this.#allEntitiesNeedUpdate = true;
-    this.#rootContexts = /* @__PURE__ */ new Map();
     eventize(this);
     this.registry = Registry.get(registry);
   }
-  #entities;
-  #rootEntities;
-  #allEntities;
-  #allEntitiesReversed;
-  #allEntitiesNeedUpdate;
-  #rootContexts;
   getEntity(uuid) {
     return this.#requireEntry(uuid).entity;
   }
+  /**
+   * The entity behind a uuid, or `undefined` when the kernel does not hold one.
+   *
+   * The counterpart to `getEntity()`, which throws. Which of the two a caller wants follows from what an
+   * absent entity means to it: a change that describes the entity tree -- a new parent, a new order, new
+   * properties -- names an entity the view believes to be there, and a uuid the kernel does not know is a
+   * disagreement the caller has to hear about. An event is the other case: it carries no structure, and the
+   * entity it was meant for may have been torn down between the two sides.
+   */
+  findEntity(uuid) {
+    return this.#entities.get(uuid)?.entity;
+  }
   /**
    * The entry for an entity that is expected to exist.
    *
    * The uuid is the caller's responsibility: `getEntity()` hands the throw on to its own
-   * callers, and `updateShadowObjects()` is reached only for an entity the caller has just
+   * callers, and `#updateShadowObjects()` is reached only for an entity the caller has just
    * confirmed. Failing here names the uuid instead of failing later on an undefined field.
    */
   #requireEntry(uuid) {
@@ -65,14 +92,46 @@ class Kernel {
   hasEntity(uuid) {
     return this.#entities.has(uuid);
   }
+  /** The token of the entity behind `uuid`, or `undefined` when the kernel does not hold one. */
+  tokenOf(uuid) {
+    return this.#entities.get(uuid)?.token;
+  }
+  /**
+   * How many entities the kernel is holding, one count per store, read without waiting on a garbage
+   * collector: a test can destroy a kernel and see that it let go of every one of them, rather than
+   * inferring it from what a collector happened to do. The two traversal counts are the cached
+   * breadth-first order and its reverse.
+   *
+   * @internal
+   */
+  get debugEntityCounts() {
+    return {
+      entities: this.#entities.size,
+      rootEntities: this.#rootEntities.size,
+      traversal: this.#allEntities.length,
+      traversalReversed: this.#allEntitiesReversed.length
+    };
+  }
   /**
    * @returns all entities in breadth-first order
+   *
+   * The list belongs to the caller: sorting or reversing it changes nothing about what the next call
+   * hands out. The walk behind it visits every entity once, which also carries it over a children list
+   * that points back at an ancestor -- `Entity.addChild()` writes such a list without touching the parent
+   * link, so no check along the parent chain can cover it.
+   *
+   * A uuid the kernel no longer holds drops out, and what hangs below it with it -- `getEntityGraph()`
+   * walks the same tree by the same rule.
    */
   traverseLevelOrderBFS(reverse = false) {
     if (this.#allEntitiesNeedUpdate) {
       const lvl = /* @__PURE__ */ new Map();
+      const visited = /* @__PURE__ */ new Set();
       const traverse = (uuid, depth) => {
-        const e = this.getEntity(uuid);
+        if (visited.has(uuid)) return;
+        visited.add(uuid);
+        const e = this.findEntity(uuid);
+        if (e === void 0) return;
         const entities = lvl.get(depth);
         if (entities) {
           entities.push(e);
@@ -90,46 +149,84 @@ class Kernel {
       this.#allEntitiesReversed = this.#allEntities.slice().reverse();
       this.#allEntitiesNeedUpdate = false;
     }
-    return reverse ? this.#allEntitiesReversed : this.#allEntities;
+    return reverse ? this.#allEntitiesReversed.slice() : this.#allEntities.slice();
   }
+  /**
+   * The entity tree as nested nodes, one node per entity. The visited set is what makes that count
+   * hold: a children list that points back at an ancestor would otherwise be walked forever, and this
+   * is the one traversal a caller reaches for while debugging a tree that is already broken. A child
+   * the walk leaves out is named at its parent under `omittedChildren`, with the reason -- a uuid the
+   * kernel does not hold, or one the walk has already placed elsewhere in the graph. A root the walk
+   * has already reached through another root's children falls off the top level without a note; it
+   * still stands in the graph, just at the other position.
+   */
   getEntityGraph() {
-    return Array.from(this.#rootEntities).map((uuid) => this.getEntityGraphNode(uuid)).filter((node) => node !== void 0);
+    const visited = /* @__PURE__ */ new Set();
+    return Array.from(this.#rootEntities).map((uuid) => this.#getEntityGraphNode(uuid, visited)).filter((node) => node !== void 0);
   }
-  getEntityGraphNode(uuid) {
+  #getEntityGraphNode(uuid, visited, omitted) {
     const entry = this.#entities.get(uuid);
-    if (entry === void 0) return void 0;
+    if (entry === void 0) {
+      omitted?.push({ uuid, reason: "not-in-kernel" });
+      return void 0;
+    }
+    if (visited.has(uuid)) {
+      omitted?.push({ uuid, reason: "already-in-graph" });
+      return void 0;
+    }
+    visited.add(uuid);
     const { token, entity } = entry;
+    const omittedChildren = [];
+    const children = entity.children.map((child) => this.#getEntityGraphNode(child.uuid, visited, omittedChildren)).filter((node) => node !== void 0);
     return {
       token,
       entity,
       props: Object.fromEntries(entity.propEntries()),
-      // A node the kernel no longer holds drops out of the graph.
-      children: entity.children.map((child) => this.getEntityGraphNode(child.uuid)).filter((node) => node !== void 0)
+      children,
+      ...omittedChildren.length > 0 ? { omittedChildren } : {}
     };
   }
   upgradeEntities() {
     const entityConstructors = /* @__PURE__ */ new Map();
     for (const entity of this.traverseLevelOrderBFS(true)) {
       if (!this.hasEntity(entity.uuid)) continue;
-      entityConstructors.set(entity.uuid, this.updateShadowObjects(entity.uuid, 2 /* DestroyOnly */));
+      entityConstructors.set(entity.uuid, this.#updateShadowObjects(entity.uuid, 2 /* DestroyOnly */));
     }
     for (const entity of this.traverseLevelOrderBFS(false)) {
       if (!this.hasEntity(entity.uuid)) continue;
-      this.updateShadowObjects(entity.uuid, 1 /* JustCreate */, entityConstructors.get(entity.uuid));
+      this.#updateShadowObjects(entity.uuid, 1 /* JustCreate */, entityConstructors.get(entity.uuid));
     }
     entityConstructors.clear();
   }
+  /**
+   * Apply a change trail, entry by entry, and say how far it got if it cannot be applied in full.
+   *
+   * The loop ends at the entry that throws, so what the kernel holds afterwards is a prefix of the
+   * trail; the {@link ChangeTrailRefusedError} names its length. The counter sits behind
+   * `#parse` and therefore counts only entries that returned normally.
+   *
+   * An effect the batch defers belongs to no single entry: the batch releases it once the loop is
+   * through, and a throw from there arrives with every entry already counted. `appliedCount` then
+   * equals `entryCount` — everything was applied, something failed nevertheless, and both
+   * statements are true at once.
+   *
+   * @throws {ChangeTrailRefusedError} if any entry, or any effect the batch deferred, threw
+   */
   run(event) {
-    if (this.logger.isDebug) {
-      this.logger.debug("sync", event);
+    this.logger.debug("sync", event);
+    let appliedCount = 0;
+    try {
+      batch(() => {
+        for (const entry of event.changeTrail) {
+          this.#parse(entry);
+          appliedCount++;
+        }
+      });
+    } catch (error) {
+      throw new ChangeTrailRefusedError(appliedCount, event.changeTrail.length, { cause: error });
     }
-    batch(() => {
-      for (const entry of event.changeTrail) {
-        this.parse(entry);
-      }
-    });
   }
-  parse(entry) {
+  #parse(entry) {
     switch (entry.type) {
       case ComponentChangeType.CreateEntities:
         this.createEntity(
@@ -140,19 +237,15 @@ class Kernel {
           entry.properties,
           entry.autoDestructionOnParentRemoval
         );
-        this.#allEntitiesNeedUpdate = true;
         break;
       case ComponentChangeType.DestroyEntities:
         this.destroyEntity(entry.uuid);
-        this.#allEntitiesNeedUpdate = true;
         break;
       case ComponentChangeType.SetParent:
         this.setParent(entry.uuid, entry.parentUuid, entry.order);
-        this.#allEntitiesNeedUpdate = true;
         break;
       case ComponentChangeType.UpdateOrder:
         this.updateOrder(entry.uuid, entry.order);
-        this.#allEntitiesNeedUpdate = true;
         break;
       case ComponentChangeType.ChangeProperties:
         this.changeProperties(entry.uuid, entry.properties);
@@ -166,41 +259,94 @@ class Kernel {
     }
   }
   createEntity(uuid, token, parentUuid, order = 0, properties, autoDestructionOnParentRemoval = false) {
+    if (this.#entities.has(uuid)) {
+      throw new EntityUuidInUseError(uuid);
+    }
     const e = new Entity(this, uuid);
     e.order = order;
     const entry = { token, entity: e, usedConstructors: /* @__PURE__ */ new Map() };
     this.#entities.set(uuid, entry);
-    if (parentUuid) {
-      e.parentUuid = parentUuid;
-    }
-    e.autoDestructionOnParentRemoval = autoDestructionOnParentRemoval;
-    if (!e.hasParent) {
-      this.#rootEntities.add(uuid);
-    }
-    if (properties) {
-      e.setProperties(properties);
+    this.noteEntityTreeChange(uuid);
+    try {
+      if (parentUuid) {
+        e.parentUuid = parentUuid;
+      }
+      e.autoDestructionOnParentRemoval = autoDestructionOnParentRemoval;
+      if (properties) {
+        e.setProperties(properties);
+      }
+      this.#createShadowObjects(entry);
+    } catch (error) {
+      this.#rollbackFailedCreation(uuid);
+      throw error;
     }
-    this.createShadowObjects(entry);
+  }
+  /**
+   * Takes back what a creation managed before it failed. The teardown is the regular one, so a
+   * shadow-object that already stands hears its `onDestroy` and its creation scope ends the way
+   * it would on any other destruction; the entry, the root registration and the link to the
+   * parent go with it. `destroyEntity()` clears the bookkeeping of the entity whatever a callback
+   * along the way does, so there is nothing left here to take back by hand; only a failure of the
+   * teardown itself is reported, because the creation error is the one the caller is waiting for.
+   *
+   * The rollback reaches this one entity, not the kernel around it. What a constructor did to other
+   * entities before it threw stands, and the teardown even adds to it, because `destroyEntity()` walks
+   * the children list: an entity the constructor hung under this one survives as a root, and one it
+   * moved under this one is taken off the parent it came from -- or destroyed outright, where it
+   * carries `autoDestructionOnParentRemoval`. Both leave an entity in a state that is neither the one
+   * before the call nor the one the constructor built. A rollback that covers those cases needs a
+   * snapshot of the kernel, which this path does not take.
+   */
+  #rollbackFailedCreation(uuid) {
+    runGuarded(
+      this.logger,
+      () => this.destroyEntity(uuid),
+      "rollback of a failed entity creation could not destroy the entity:",
+      uuid
+    );
   }
   destroyEntity(uuid) {
     const entry = this.#entities.get(uuid);
     if (entry === void 0) return;
     const { entity, usedConstructors } = entry;
-    const childrenSnapshot = [...entity.children];
-    for (const child of childrenSnapshot) {
-      if (child.autoDestructionOnParentRemoval) {
-        this.destroyEntity(child.uuid);
-      } else {
-        child.removeFromParent();
-        this.#rootEntities.add(child.uuid);
+    try {
+      const childrenSnapshot = [...entity.children];
+      for (const child of childrenSnapshot) {
+        runGuarded(
+          this.logger,
+          () => {
+            if (child.autoDestructionOnParentRemoval) {
+              this.destroyEntity(child.uuid);
+            } else {
+              child.removeFromParent();
+            }
+          },
+          "child of a destroyed entity could not be handed on:",
+          child.uuid
+        );
+      }
+      runGuarded(this.logger, () => entity.removeFromParent(), "entity could not be detached from its parent:", entity.uuid);
+      const shadowObjects = this.findShadowObjects(entity.uuid);
+      for (const shadowObject of shadowObjects) {
+        off(entity, shadowObject);
+        this.#notifyShadowObjectDestroy(shadowObject, entity);
       }
+      runGuarded(this.logger, () => emitStrict(entity, onDestroy, entity), "entity onDestroy notification failed:", entity.uuid);
+      for (const shadowObject of shadowObjects) {
+        runGuarded(
+          this.logger,
+          () => this.#shadowObjectScopes.get(shadowObject)?.tearDown(),
+          "creation scope teardown of a destroyed entity failed:",
+          entity.uuid
+        );
+      }
+      runGuarded(this.logger, () => entity[onDestroy](), "entity release failed:", entity.uuid);
+    } finally {
+      usedConstructors.clear();
+      this.#entities.delete(entity.uuid);
+      this.#rootEntities.delete(entity.uuid);
+      this.#allEntitiesNeedUpdate = true;
     }
-    entity.removeFromParent();
-    emit(entity, onDestroy, entity);
-    usedConstructors.clear();
-    this.#entities.delete(entity.uuid);
-    this.#rootEntities.delete(entity.uuid);
-    this.#allEntitiesNeedUpdate = true;
   }
   /**
    * @param order the new order, or `undefined` to keep the current one. A set-parent change
@@ -214,59 +360,93 @@ class Kernel {
     if (parentUuid && !this.#entities.has(parentUuid)) {
       throw new Error(`entity with uuid "${parentUuid}" not found!`);
     }
-    e.removeFromParent();
+    if (parentUuid) {
+      e.assertAttachableTo(this.getEntity(parentUuid));
+    }
+    e.removeFromParent(parentUuid == null);
     e.order = nextOrder;
     e.parentUuid = parentUuid;
-    if (e.hasParent) {
+    this.logger.debug("entity.onParentChanged", { uuid, parentUuid, order: nextOrder, entity: e });
+    runGuarded(this.logger, () => emitStrict(e, onParentChanged, e), "entity onParentChanged notification failed:", uuid);
+  }
+  updateOrder(uuid, order) {
+    this.getEntity(uuid).order = order;
+  }
+  /**
+   * Records that an entity has changed its place in the entity tree: it took a parent, lost one,
+   * or moved among its siblings. Two pieces of bookkeeping follow from that -- the cached
+   * traversal is dropped, and an entity without a parent joins the set of root entities while one
+   * with a parent leaves it.
+   *
+   * `Entity` reports here from every write that moves it, because those writes are reachable from
+   * a shadow-object with no kernel call in between: `entity.parent`, `entity.parentUuid`,
+   * `entity.order` and `entity.removeFromParent()`. The state is read off the entity rather than
+   * taken as an argument, so a caller cannot describe a move the entity did not make.
+   *
+   * A uuid the kernel does not hold reaches the cache and stops there: an entity joins the root
+   * set when the kernel takes it in and leaves it when the kernel lets go.
+   *
+   * That such a uuid passes in silence, where `setParent()` and `updateOrder()` throw at one, is the
+   * difference between a request and a report. Those two are asked to move an entity and cannot do it
+   * without one, so an unknown uuid is a disagreement the caller has to hear about. This is an entity
+   * saying where it stands, and it says so while the kernel is still taking it in: `createEntity()`
+   * writes the order on the entity before the entry is registered, so an entity created with an order
+   * of its own reports once before the kernel holds it. A throw there would cost the creation its own
+   * bookkeeping, and there is nothing to disagree about -- dropping the cache is right either way.
+   */
+  noteEntityTreeChange(uuid) {
+    this.#allEntitiesNeedUpdate = true;
+    const entry = this.#entities.get(uuid);
+    if (entry === void 0) return;
+    if (entry.entity.hasParent) {
       this.#rootEntities.delete(uuid);
     } else {
       this.#rootEntities.add(uuid);
     }
-    e.reSubscribeToParentContexts();
-    queueMicrotask(() => {
-      if (this.logger.isDebug) {
-        this.logger.debug("entity.onParentChanged", { uuid, parentUuid, order: nextOrder, entity: e });
-      }
-      emit(e, onParentChanged, e);
-    });
-  }
-  updateOrder(uuid, order) {
-    this.getEntity(uuid).order = order;
   }
   dispatchEventsToEntity(uuid, events) {
-    this.getEntity(uuid)?.dispatchViewEvents(events);
+    this.findEntity(uuid)?.dispatchViewEvents(events);
   }
   changeProperties(uuid, properties) {
     this.getEntity(uuid).setProperties(properties);
-    this.updateShadowObjects(uuid);
+    this.#updateShadowObjects(uuid);
   }
   changeToken(uuid, token) {
     const entry = this.#entities.get(uuid);
     if (entry === void 0) return;
     if (entry.token === token) return;
+    const previousToken = entry.token;
     entry.token = token;
-    this.updateShadowObjects(uuid);
+    this.#updateShadowObjects(uuid, 0 /* CreateAndDestroy */, void 0, previousToken);
   }
   dispatchMessageToView(message) {
     queueMicrotask(() => {
-      emit(this, MessageToView, message);
+      emitSafe(this, MessageToView, message);
     });
   }
   /**
    * Create or destroy the shadow-objects of an entity using the registered constructors.
    * After a token change or registry changes, an entity may be given different shadow-objects.
+   *
+   * @param previousToken the token the entry carried before the caller wrote the new one, or
+   *   `undefined` where the caller left the token alone. A rebuild that does not get through puts it
+   *   back before it restores the shadow-objects, so an entity is never built against a token it does
+   *   not carry.
    */
-  updateShadowObjects(uuid, action = 0 /* CreateAndDestroy */, nextConstructors) {
+  #updateShadowObjects(uuid, action = 0 /* CreateAndDestroy */, nextConstructors, previousToken) {
     const entry = this.#requireEntry(uuid);
     nextConstructors ??= new Set(this.registry.findConstructors(entry.token, entry.entity.truthyProps()));
     const shouldDestroy = action === 0 /* CreateAndDestroy */ || action === 2 /* DestroyOnly */;
     const shouldCreate = action === 0 /* CreateAndDestroy */ || action === 1 /* JustCreate */;
+    const removed = [];
+    const created = [];
     if (shouldDestroy) {
       for (const [construct, shadowObjects] of entry.usedConstructors) {
         if (!nextConstructors.has(construct)) {
           entry.usedConstructors.delete(construct);
+          removed.push({ construct, count: shadowObjects.size });
           for (const obj of shadowObjects) {
-            this.destroyShadowObject(obj, entry.entity);
+            this.#destroyShadowObject(obj, entry.entity);
           }
         }
       }
@@ -274,304 +454,110 @@ class Kernel {
     if (shouldCreate) {
       for (const construct of nextConstructors) {
         if (!entry.usedConstructors.has(construct)) {
-          this.constructShadowObject(construct, entry);
+          try {
+            created.push(this.#constructShadowObject(construct, entry));
+          } catch (error) {
+            this.#rollbackFailedShadowObjectUpdate(entry, created, removed, previousToken);
+            throw error;
+          }
         }
       }
     }
     return nextConstructors;
   }
-  constructShadowObject(construct, entry) {
-    const unsubscribePrimary = /* @__PURE__ */ new Set();
-    const unsubscribeSecondary = /* @__PURE__ */ new Set();
-    const contextReaders = /* @__PURE__ */ new Map();
-    const contextReaderCompares = /* @__PURE__ */ new Map();
-    const contextParentReaders = /* @__PURE__ */ new Map();
-    const contextParentReaderCompares = /* @__PURE__ */ new Map();
-    const contextProviders = /* @__PURE__ */ new Map();
-    const contextRootProviders = /* @__PURE__ */ new Map();
-    const propertyReaders = /* @__PURE__ */ new Map();
-    const propertyCompares = /* @__PURE__ */ new Map();
-    const getUseProperty = (name, options) => {
-      if (!usePropertyOptionsDeprecatedShown && options != null && typeof options === "function") {
-        console.warn(
-          '[shadow-objects] Deprecation Warning: The "isEqual" option of "useProperty()" is now passed as {compare} argument. Please update your code accordingly.'
-        );
-        usePropertyOptionsDeprecatedShown = true;
-      }
-      const opts = typeof options === "function" ? { compare: options } : options;
-      let propReader = propertyReaders.get(name);
-      if (propReader === void 0) {
-        propReader = createSignal(void 0, opts).get;
-        propertyReaders.set(name, propReader);
-        propertyCompares.set(name, opts?.compare);
-        const con = link(entry.entity.getPropertyReader(name), propReader);
-        unsubscribeSecondary.add(con.destroy.bind(con));
-      } else if (opts?.compare != null && propertyCompares.get(name) !== opts.compare) {
-        console.warn(
-          `[shadow-objects] useProperty("${name}"): the cached signal already exists with a different (or no) {compare} function \u2014 the new options are ignored. Pass options only on the first call per property.`
+  /**
+   * Takes a rebuild of the shadow-objects of one entity back to where the call found it.
+   *
+   * The identity check comes first, because a constructor may destroy the entity it is coming to life
+   * on. Where the kernel no longer holds this entry -- including where another entry stands under the
+   * same uuid by now -- `destroyEntity()` has already notified every shadow-object of the entry and
+   * cleared `usedConstructors`; both halves of the rollback would find nothing to work with.
+   *
+   * The token before the shadow-objects: what is rebuilt is built against the token the entity carries
+   * afterwards.
+   *
+   * Backwards down, forwards up: the new shadow-objects leave before the previous ones come back, so
+   * the two sets never stand on the entity at the same time.
+   *
+   * Every step behind a guard of its own and nothing re-thrown -- the caller is waiting for the error
+   * of the construction, not for one from the way back.
+   *
+   * What the rollback does not reach is named rather than passed over. `changeProperties()` has written its
+   * properties before it gets here, and they stay written -- a constructor restored below can therefore
+   * stand on an entity whose properties no longer route to it, until the next re-resolution of the set
+   * leaves it out and takes it down. And `upgradeEntities()` takes its shadow-objects down in one pass over
+   * the entity tree and builds in the next, so a rollback in the second pass knows nothing of what the first
+   * one took -- at this entity as much as at any other; the entity keeps the token it came in with, an
+   * upgrade having written none, and is left with whatever the first pass spared. Both would need a snapshot
+   * of the kernel, which this path does not take.
+   */
+  #rollbackFailedShadowObjectUpdate(entry, created, removed, previousToken) {
+    if (this.#entities.get(entry.entity.uuid) !== entry) return;
+    if (previousToken !== void 0) {
+      entry.token = previousToken;
+    }
+    for (let i = created.length - 1; i >= 0; i--) {
+      runGuarded(
+        this.logger,
+        () => this.#destroyShadowObject(created[i], entry.entity),
+        "rollback of a failed shadow-object update could not remove a new shadow-object:",
+        entry.entity.uuid
+      );
+    }
+    for (const { construct, count } of removed) {
+      for (let i = 0; i < count; i++) {
+        runGuarded(
+          this.logger,
+          () => this.#constructShadowObject(construct, entry),
+          "rollback of a failed shadow-object update could not restore a shadow-object:",
+          getDisplayName(construct),
+          entry.entity.uuid
         );
       }
-      return propReader;
-    };
-    const shadowObject = eventize(
-      new construct({
-        entity: entry.entity,
-        provideContext(name, sourceOrInitialValue, options) {
-          if (!provideContextOptionsDeprecatedShown && options != null && typeof options === "function") {
-            console.warn(
-              '[shadow-objects] Deprecation Warning: The "isEqual" option of "provideContext()" is now passed as {compare} argument. Please update your code accordingly.'
-            );
-            provideContextOptionsDeprecatedShown = true;
-          }
-          const opts = typeof options === "function" ? { compare: options } : options;
-          let ctxProvider = contextProviders.get(name);
-          if (ctxProvider == null) {
-            const isSig = isSignal(sourceOrInitialValue);
-            const initialValue = isSig ? void 0 : toMaybe(sourceOrInitialValue);
-            ctxProvider = createSignal(initialValue, opts?.compare ? { compare: opts.compare } : void 0);
-            if (isSig) {
-              const ln2 = link(sourceOrInitialValue, ctxProvider);
-              unsubscribeSecondary.add(ln2.destroy.bind(ln2));
-            }
-            const ln = link(ctxProvider, entry.entity.provideContext(name));
-            unsubscribeSecondary.add(ln.destroy.bind(ln));
-            contextProviders.set(name, ctxProvider);
-          }
-          if (ctxProvider != null && (opts?.clearOnDestroy ?? true)) {
-            unsubscribeSecondary.add(() => {
-              ctxProvider.set(void 0);
-            });
-          }
-          return ctxProvider;
-        },
-        provideGlobalContext(name, sourceOrInitialValue, options) {
-          if (!provideGlobalContextOptionsDeprecatedShown && options != null && typeof options === "function") {
-            console.warn(
-              '[shadow-objects] Deprecation Warning: The "isEqual" option of "provideGlobalContext()" is now passed as {compare} argument. Please update your code accordingly.'
-            );
-            provideGlobalContextOptionsDeprecatedShown = true;
-          }
-          const opts = typeof options === "function" ? { compare: options } : options;
-          let ctxProvider = contextRootProviders.get(name);
-          if (ctxProvider == null) {
-            const isSig = isSignal(sourceOrInitialValue);
-            const initialValue = isSig ? void 0 : toMaybe(sourceOrInitialValue);
-            ctxProvider = createSignal(initialValue, opts?.compare ? { compare: opts.compare } : void 0);
-            if (isSig) {
-              const ln2 = link(sourceOrInitialValue, ctxProvider);
-              unsubscribeSecondary.add(ln2.destroy.bind(ln2));
-            }
-            const ln = link(ctxProvider, entry.entity.provideGlobalContext(name));
-            unsubscribeSecondary.add(ln.destroy.bind(ln));
-            contextRootProviders.set(name, ctxProvider);
-          }
-          if (ctxProvider != null && (opts?.clearOnDestroy ?? true)) {
-            unsubscribeSecondary.add(() => {
-              ctxProvider.set(void 0);
-            });
-          }
-          return ctxProvider;
-        },
-        useContext(name, options) {
-          if (!useContextOptionsDeprecatedShown && options != null && typeof options === "function") {
-            console.warn(
-              '[shadow-objects] Deprecation Warning: The "isEqual" option of "useContext()" is now passed as {compare} argument. Please update your code accordingly.'
-            );
-            useContextOptionsDeprecatedShown = true;
-          }
-          const opts = typeof options === "function" ? { compare: options } : options;
-          let ctxReader = contextReaders.get(name);
-          if (ctxReader === void 0) {
-            ctxReader = createSignal(void 0, opts).get;
-            contextReaders.set(name, ctxReader);
-            contextReaderCompares.set(name, opts?.compare);
-            const ln = link(entry.entity.useContext(name), ctxReader);
-            unsubscribeSecondary.add(ln.destroy.bind(ln));
-          } else if (opts?.compare != null && contextReaderCompares.get(name) !== opts.compare) {
-            console.warn(
-              `[shadow-objects] useContext("${String(name)}"): the cached signal already exists with a different (or no) {compare} function \u2014 the new options are ignored. Pass options only on the first call per context.`
-            );
-          }
-          return ctxReader;
-        },
-        useParentContext(name, options) {
-          if (!useParentContextOptionsDeprecatedShown && options != null && typeof options === "function") {
-            console.warn(
-              '[shadow-objects] Deprecation Warning: The "isEqual" option of "useParentContext()" is now passed as {compare} argument. Please update your code accordingly.'
-            );
-            useParentContextOptionsDeprecatedShown = true;
-          }
-          const opts = typeof options === "function" ? { compare: options } : options;
-          let ctxReader = contextParentReaders.get(name);
-          if (ctxReader === void 0) {
-            ctxReader = createSignal(void 0, opts).get;
-            contextParentReaders.set(name, ctxReader);
-            contextParentReaderCompares.set(name, opts?.compare);
-            const ln = link(entry.entity.useParentContext(name), ctxReader);
-            unsubscribeSecondary.add(ln.destroy.bind(ln));
-          } else if (opts?.compare != null && contextParentReaderCompares.get(name) !== opts.compare) {
-            console.warn(
-              `[shadow-objects] useParentContext("${String(name)}"): the cached signal already exists with a different (or no) {compare} function \u2014 the new options are ignored. Pass options only on the first call per parent context.`
-            );
-          }
-          return ctxReader;
-        },
-        dispatchMessageToView(type, data, transferables, traverseChildren = false) {
-          entry.entity.dispatchMessageToView(type, data, transferables, traverseChildren);
-        },
-        useProperty: getUseProperty,
-        useProperties(props) {
-          const result = {};
-          for (const key in props) {
-            if (Object.hasOwn(props, key)) {
-              result[key] = getUseProperty(props[key]);
-            }
-          }
-          return result;
-        },
-        createResource(factory, cleanup) {
-          const resourceSignal = createSignal();
-          const effect = createEffect(() => {
-            const resource = toMaybe(factory());
-            resourceSignal.set(resource);
-            if (resource !== void 0 && cleanup) {
-              return () => {
-                cleanup(resource);
-                resourceSignal.set(void 0);
-              };
-            }
-            return () => {
-              resourceSignal.set(void 0);
-            };
-          });
-          unsubscribeSecondary.add(() => {
-            effect.destroy();
-            resourceSignal.set(void 0);
-            destroySignal(resourceSignal);
-          });
-          return resourceSignal;
-        },
-        createEffect(...args) {
-          const effect = createEffect(...args);
-          unsubscribeSecondary.add(effect.destroy);
-          return effect;
-        },
-        createSignal(...args) {
-          const sig = createSignal(...args);
-          unsubscribeSecondary.add(() => {
-            destroySignal(sig);
-          });
-          return sig;
-        },
-        createMemo(...args) {
-          const sig = createMemo(...args);
-          unsubscribeSecondary.add(() => {
-            destroySignal(sig);
-          });
-          return sig;
-        },
-        on(...args) {
-          const [firstArg] = args;
-          if (typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg)) {
-            const unsub2 = on(entry.entity, ...args);
-            unsubscribeSecondary.add(unsub2);
-            return unsub2;
-          }
-          const unsub = on(...args);
-          unsubscribeSecondary.add(unsub);
-          return Object.assign(() => {
-            unsubscribeSecondary.delete(unsub);
-            unsub();
-          }, unsub);
-        },
-        once(...args) {
-          const [firstArg] = args;
-          if (typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg)) {
-            const unsub2 = once(entry.entity, ...args);
-            unsubscribeSecondary.add(unsub2);
-            return unsub2;
-          }
-          const unsub = once(...args);
-          unsubscribeSecondary.add(unsub);
-          return Object.assign(() => {
-            unsubscribeSecondary.delete(unsub);
-            unsub();
-          }, unsub);
-        },
-        emit(...args) {
-          const [firstArg] = args;
-          if (typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg)) {
-            emit(entry.entity, ...args);
-          } else {
-            emit(...args);
-          }
-        },
-        onViewEvent(callback) {
-          const unsub = on(entry.entity, onViewEvent, (type, data) => {
-            callback(type, data);
-          });
-          unsubscribeSecondary.add(unsub);
-        },
-        onDestroy(callback) {
-          unsubscribePrimary.add(callback);
-        }
-      })
-    );
-    if (this.logger.isInfo) {
-      this.logger.info("create shadow-object", getDisplayName(construct), { shadowObject, entity: entry.entity });
     }
-    once(entry.entity, onDestroy, Priority.Low, () => {
-      if (this.logger.isInfo) {
-        this.logger.info("destroy shadow-object", getDisplayName(construct), { shadowObject, entity: entry.entity });
-      }
-      for (const callback of unsubscribePrimary) {
-        callback();
-      }
-      for (const callback of unsubscribeSecondary) {
-        callback();
-      }
-      for (const sig of contextReaders.values()) {
-        destroySignal(sig);
-      }
-      for (const sig of contextParentReaders.values()) {
-        destroySignal(sig);
-      }
-      for (const sig of propertyReaders.values()) {
-        destroySignal(sig);
-      }
-      for (const sig of contextProviders.values()) {
-        destroySignal(sig);
-      }
-      for (const sig of contextRootProviders.values()) {
-        destroySignal(sig);
-      }
-      unsubscribePrimary.clear();
-      unsubscribeSecondary.clear();
-      contextReaders.clear();
-      contextParentReaders.clear();
-      propertyReaders.clear();
-      contextProviders.clear();
-      contextRootProviders.clear();
-      const otherShadowObjects = entry.usedConstructors.get(construct);
-      if (otherShadowObjects) {
-        otherShadowObjects.delete(shadowObject);
-        if (otherShadowObjects.size === 0) {
-          entry.usedConstructors.delete(construct);
+  }
+  #constructShadowObject(construct, entry) {
+    const scope = new ShadowObjectCreationScope(entry.entity, this.logger, getDisplayName(construct), this.#shownDeprecations);
+    let shadowObject;
+    try {
+      shadowObject = eventize(new construct(scope.createAPI()));
+    } catch (error) {
+      scope.tearDown();
+      throw error;
+    }
+    this.#shadowObjectScopes.set(shadowObject, scope);
+    scope.bindTo(
+      shadowObject,
+      () => {
+        this.#shadowObjectScopes.delete(shadowObject);
+      },
+      () => {
+        const otherShadowObjects = entry.usedConstructors.get(construct);
+        if (otherShadowObjects) {
+          otherShadowObjects.delete(shadowObject);
+          if (otherShadowObjects.size === 0) {
+            entry.usedConstructors.delete(construct);
+          }
         }
       }
-    });
+    );
     const createdBy = entry.usedConstructors.get(construct);
     if (createdBy) {
       createdBy.add(shadowObject);
     } else {
       entry.usedConstructors.set(construct, /* @__PURE__ */ new Set([shadowObject]));
     }
-    this.attachShadowObject(shadowObject, entry.entity);
+    try {
+      this.#attachShadowObject(shadowObject, entry.entity);
+    } catch (error) {
+      this.#destroyShadowObject(shadowObject, entry.entity);
+      throw error;
+    }
     return shadowObject;
   }
-  createShadowObjects(entry) {
+  #createShadowObjects(entry) {
     this.registry.findConstructors(entry.token, entry.entity.truthyProps())?.forEach((construct) => {
-      this.constructShadowObject(construct, entry);
+      this.#constructShadowObject(construct, entry);
     });
   }
   findShadowObjects(uuid) {
@@ -580,17 +566,90 @@ class Kernel {
     const { usedConstructors } = entry;
     return Array.from(new Set(Array.from(usedConstructors.values()).flatMap((objs) => Array.from(objs))));
   }
-  attachShadowObject(shadowObject, entity) {
+  /**
+   * One description per Shadow Object of the entity, in the order `findShadowObjects()` lists them:
+   * what the creation scope knows (display name, the five name lists), the tokens the constructor is
+   * defined under in this kernel's registry, and which of the four lifecycle hooks the instance
+   * implements. `[]` for a uuid the kernel does not hold. Reads only; a scope that is already gone
+   * contributes its display name and empty lists.
+   */
+  describeShadowObjects(uuid) {
+    const entry = this.#entities.get(uuid);
+    if (entry === void 0) return [];
+    const seen = /* @__PURE__ */ new Set();
+    const descriptions = [];
+    for (const [construct, shadowObjects] of entry.usedConstructors) {
+      for (const shadowObject of shadowObjects) {
+        if (seen.has(shadowObject)) continue;
+        seen.add(shadowObject);
+        const scope = this.#shadowObjectScopes.get(shadowObject);
+        const hooks = LIFECYCLE_HOOKS.filter(([, symbol]) => typeof shadowObject[symbol] === "function").map(
+          ([name]) => name
+        );
+        descriptions.push({
+          ...scope?.describe() ?? {
+            displayName: getDisplayName(construct),
+            usesProperties: [],
+            usesContexts: [],
+            usesParentContexts: [],
+            providesContexts: [],
+            providesGlobalContexts: []
+          },
+          definedUnder: this.registry.tokensOf(construct),
+          hooks
+        });
+      }
+    }
+    return descriptions;
+  }
+  #attachShadowObject(shadowObject, entity) {
+    for (const [name, symbol] of LIFECYCLE_HOOKS) {
+      if (typeof shadowObject[name] === "function" && typeof shadowObject[symbol] !== "function") {
+        const displayName = this.#shadowObjectScopes.get(shadowObject)?.displayName;
+        this.logger.error(
+          `the "${name}" lifecycle hook is a plain method and is never called; use the [${name}] symbol from "@spearwolf/shadow-objects/shadow-objects.js":`,
+          displayName
+        );
+      }
+    }
     on(entity, shadowObject);
     if (typeof shadowObject[onCreate] === "function") {
       shadowObject[onCreate](entity);
     }
   }
-  destroyShadowObject(shadowObject, entity) {
+  /**
+   * Tells one shadow-object that it is about to end, in both halves the notification has: the
+   * class-side `[onDestroy]` hook and the event other objects can listen for.
+   *
+   * Each half stands behind a guard of its own rather than a shared one, because neither is allowed to
+   * cost the other: a hook that throws still lets the event go out, and a listener that throws leaves
+   * the hook it came after untouched. Within the event half the same rule holds one level down, through
+   * `emitStrict()`: a listener that throws costs no other listener its turn. Nothing is re-thrown -- the
+   * shadow-objects of one entity reach their end in one sweep, and a failure at one of them may not take
+   * the sweep with it. Reports are
+   * keyed by the name the scope carries rather than the one the instance would give -- see
+   * `ShadowObjectCreationScope.displayName` for where the two part ways.
+   */
+  #notifyShadowObjectDestroy(shadowObject, entity) {
+    const displayName = this.#shadowObjectScopes.get(shadowObject)?.displayName;
     if (typeof shadowObject[onDestroy] === "function") {
-      shadowObject[onDestroy](entity);
+      runGuarded(
+        this.logger,
+        () => shadowObject[onDestroy](entity),
+        "shadow-object onDestroy hook failed:",
+        displayName
+      );
     }
-    emit(shadowObject, onDestroy, entity);
+    runGuarded(
+      this.logger,
+      () => emitStrict(shadowObject, onDestroy, entity),
+      "shadow-object onDestroy notification failed:",
+      displayName
+    );
+  }
+  #destroyShadowObject(shadowObject, entity) {
+    this.#notifyShadowObjectDestroy(shadowObject, entity);
+    this.#shadowObjectScopes.get(shadowObject)?.tearDown();
     off(entity, shadowObject);
   }
   findOrCreateRootContext(name) {
@@ -601,14 +660,42 @@ class Kernel {
     }
     return ctx;
   }
+  /** The names of the kernel-wide context chains -- every name a root entity uses or any entity provides globally. */
+  rootContextNames() {
+    return Array.from(this.#rootContexts.keys());
+  }
+  /**
+   * One kernel-wide context chain: what it resolves to, and its members in chain order. The members
+   * are the signals the entities contributed -- `Entity.describeGlobalContext()` hands out the same
+   * objects, so a caller can match them by identity. `undefined` for a name the kernel holds no
+   * chain for; asking does not create one.
+   */
+  describeRootContext(name) {
+    const path = this.#rootContexts.get(name);
+    if (path === void 0) return void 0;
+    return { value: path.value, signals: path.signals };
+  }
   destroy() {
+    for (const entity of this.traverseLevelOrderBFS(true)) {
+      runGuarded(
+        this.logger,
+        () => this.destroyEntity(entity.uuid),
+        "entity teardown during kernel destroy failed:",
+        entity.uuid
+      );
+    }
+    this.#entities.clear();
+    this.#rootEntities.clear();
+    this.#allEntities.length = 0;
+    this.#allEntitiesReversed.length = 0;
+    this.#allEntitiesNeedUpdate = true;
     for (const ctx of this.#rootContexts.values()) {
       ctx.dispose();
     }
     this.#rootContexts.clear();
-    for (const entity of this.traverseLevelOrderBFS().reverse()) {
-      this.destroyEntity(entity.uuid);
-    }
+    queueMicrotask(() => {
+      off(this);
+    });
   }
 }
 export {