@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/view/ShadowEnv.js

@@ -46,18 +46,54 @@ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read fr
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
-var _proxyReady_dec, _viewReady_dec, _comCtx, _shaObjEnvProxy, _syncScheduled, _syncAfterContextCreated, _syncWaitForConfirmation, _afterNextSync, _init, _viewReady, _proxyReady, _isDestroyed, _whenDestroyed, _rejectWhenDestroyed, _ShadowEnv_instances, destroyedSignal_fn, _syncIfScheduled, syncNow_fn, onMessageToView_fn, onProxyFailed_fn;
-import { emit, off, on, onceAsync, Priority, retain, retainClear } from "@spearwolf/eventize";
-import { createEffect, createSignal, destroyObjectSignals, findObjectSignalByName } from "@spearwolf/signalize";
+var __privateWrapper = (obj, member, setter, getter) => ({
+  set _(value) {
+    __privateSet(obj, member, value, setter);
+  },
+  get _() {
+    return __privateGet(obj, member, getter);
+  }
+});
+var _proxyReady_dec, _viewReady_dec, _comCtx, _shaObjEnvProxy, _syncScheduled, _syncAfterContextCreated, _syncWaitForConfirmation, _nextSyncCycle, _logger, _init, _viewReady, _proxyReady, _isDestroyed, _contextEffect, _ShadowEnv_instances, ensureContextEffect_fn, releaseNamespace_fn, _proxyGeneration, _whenDestroyed, _rejectWhenDestroyed, destroyedSignal_fn, openSyncCycle_fn, _syncIfScheduled, syncNow_fn, commitSyncCycle_fn, announceContext_fn, endSyncCycle_fn, onMessageToView_fn, onProxyFailed_fn;
+import { emitStrict, off, on, onceAsync, Priority, retain, retainClear } from "@spearwolf/eventize";
+import {
+  createEffect,
+  createSignal,
+  destroyObjectSignals,
+  findObjectSignalByName,
+  hibernate
+} from "@spearwolf/signalize";
 import { signal } from "@spearwolf/signalize/decorators";
+import { ChangeTrailRefusedError } from "../ChangeTrailRefusedError.js";
+import { GlobalNS } from "../constants.js";
+import { createViewSnapshot } from "../inspect/createViewSnapshot.js";
 import { ConsoleLogger } from "../utils/ConsoleLogger.js";
 import { ComponentContext } from "./ComponentContext.js";
+import { RemoteWorkerEnv } from "./RemoteWorkerEnv.js";
 class ShadowEnvDestroyedError extends Error {
   constructor(message = "the shadow environment has been destroyed") {
     super(message);
     this.name = "ShadowEnvDestroyedError";
   }
 }
+const namespaceAsString = (ns) => typeof ns === "symbol" ? ns.description ?? String(ns) : ns ?? "";
+const errorInfo = (error) => error instanceof Error ? { name: error.name, message: error.message } : { name: "Error", message: String(error) };
+const abortRace = (signal2) => {
+  let onAbort;
+  const promise = new Promise((_, reject) => {
+    onAbort = () => reject(signal2.reason);
+    signal2.addEventListener("abort", onAbort, { once: true });
+  });
+  promise.catch(() => {
+  });
+  return { promise, dispose: () => signal2.removeEventListener("abort", onAbort) };
+};
+const proxyKind = (proxy) => {
+  if (proxy === void 0) return "none";
+  if (proxy.isLocalEnv === true) return "local";
+  if (proxy instanceof RemoteWorkerEnv) return "worker";
+  return "custom";
+};
 _viewReady_dec = [signal()], _proxyReady_dec = [signal()];
 const _ShadowEnv = class _ShadowEnv {
   constructor() {
@@ -67,12 +103,22 @@ const _ShadowEnv = class _ShadowEnv {
     __privateAdd(this, _syncScheduled, false);
     __privateAdd(this, _syncAfterContextCreated, false);
     __privateAdd(this, _syncWaitForConfirmation, false);
-    __privateAdd(this, _afterNextSync);
-    this.logger = new ConsoleLogger("ShadowEnv");
+    __privateAdd(this, _nextSyncCycle);
+    __privateAdd(this, _logger, new ConsoleLogger("ShadowEnv"));
+    /**
+     * The namespace of the {@link ComponentContext} this environment observes, and `undefined`
+     * while it observes none. The `view` setter writes it, so it carries the name
+     * {@link ShadowEnv.get} finds this environment under, unless another environment has since
+     * taken that namespace over; a `destroy()` leaves it on `undefined`.
+     */
     this.ns$ = createSignal();
     __privateAdd(this, _viewReady, __runInitializers(_init, 8, this, false)), __runInitializers(_init, 11, this);
     __privateAdd(this, _proxyReady, __runInitializers(_init, 12, this, false)), __runInitializers(_init, 15, this);
     __privateAdd(this, _isDestroyed, false);
+    __privateAdd(this, _contextEffect);
+    // Each assignment to `envProxy` opens a generation. A start that finishes outside the generation
+    // it belongs to speaks for a proxy this environment has already let go, and is discarded.
+    __privateAdd(this, _proxyGeneration, 0);
     __privateAdd(this, _whenDestroyed);
     __privateAdd(this, _rejectWhenDestroyed);
     /**
@@ -92,27 +138,45 @@ const _ShadowEnv = class _ShadowEnv {
     });
     const self = this;
     retain(self, _ShadowEnv.ContextCreated);
-    on(self, _ShadowEnv.ContextLost, Priority.AAA, () => {
+    on(self, _ShadowEnv.ContextLost, Priority.Critical, () => {
       retainClear(self, _ShadowEnv.ContextCreated);
     });
-    createEffect(() => {
-      if (this.viewReady && this.proxyReady) {
-        this.view.reCreateChanges();
-        emit(self, _ShadowEnv.ContextCreated, self);
-        if (__privateGet(this, _syncAfterContextCreated)) {
-          __privateSet(this, _syncAfterContextCreated, false);
-          __privateMethod(this, _ShadowEnv_instances, syncNow_fn).call(this);
-        }
-        return () => {
-          emit(self, _ShadowEnv.ContextLost, self);
-        };
-      }
-    }, [findObjectSignalByName(this, "viewReady"), findObjectSignalByName(this, "proxyReady")]);
   }
   static get(ns) {
     if (ns == null) return void 0;
     return globalThis.__shadowEnvs?.get(ns);
   }
+  /**
+   * Every environment that holds a namespace, in registration order, each described by
+   * {@link ShadowEnv.inspect}. One environment that cannot answer costs its own entry and not the
+   * list: the per-environment failures are reported under `error`, and an environment destroyed
+   * while it answers drops out of the list. Rejects only for the caller's reasons -- an aborted
+   * signal.
+   *
+   * `only` narrows the list before anything is asked: it is called with the namespace an
+   * environment is registered under, and an environment it refuses is neither inspected nor
+   * listed. That is what lets a caller keep an environment out of a picture without touching it.
+   */
+  static async inspectAll(request = {}, signal2, only) {
+    const envs = [];
+    for (const [ns, env] of globalThis.__shadowEnvs?.entries() ?? []) {
+      if (only === void 0 || only(ns)) envs.push(env);
+    }
+    const settled = await Promise.all(
+      envs.map(
+        (env) => env.inspect(request, signal2).catch((error) => {
+          if (signal2?.aborted) throw signal2.reason;
+          if (error instanceof ShadowEnvDestroyedError) return void 0;
+          throw error;
+        })
+      )
+    );
+    return settled.filter((snapshot) => snapshot !== void 0);
+  }
+  /** The logger this environment reports through. */
+  get logger() {
+    return __privateGet(this, _logger);
+  }
   get isDestroyed() {
     return __privateGet(this, _isDestroyed);
   }
@@ -121,23 +185,17 @@ const _ShadowEnv = class _ShadowEnv {
   }
   set view(ctx) {
     if (ctx !== __privateGet(this, _comCtx)) {
-      if (__privateGet(this, _comCtx)?.ns && globalThis.__shadowEnvs) {
-        globalThis.__shadowEnvs.delete(__privateGet(this, _comCtx).ns);
-      }
+      if (ctx) __privateMethod(this, _ShadowEnv_instances, ensureContextEffect_fn).call(this);
+      __privateMethod(this, _ShadowEnv_instances, releaseNamespace_fn).call(this, __privateGet(this, _comCtx)?.ns);
       __privateSet(this, _comCtx, ctx ?? void 0);
       if (__privateGet(this, _comCtx)?.ns) {
         globalThis.__shadowEnvs ??= /* @__PURE__ */ new Map();
         if (globalThis.__shadowEnvs.has(__privateGet(this, _comCtx).ns) && globalThis.__shadowEnvs.get(__privateGet(this, _comCtx).ns) !== this) {
-          if (this.logger.isWarn) {
-            this.logger.warn(
-              "overwrite a namespace already in use",
-              __privateGet(this, _comCtx).ns,
-              globalThis.__shadowEnvs.get(__privateGet(this, _comCtx).ns)
-            );
-          }
+          this.logger.warn("overwrite a namespace already in use", __privateGet(this, _comCtx).ns, globalThis.__shadowEnvs.get(__privateGet(this, _comCtx).ns));
         }
         globalThis.__shadowEnvs.set(__privateGet(this, _comCtx).ns, this);
       }
+      this.ns$.set(__privateGet(this, _comCtx)?.ns);
       this.viewReady = Boolean(ctx);
     }
   }
@@ -146,19 +204,27 @@ const _ShadowEnv = class _ShadowEnv {
   }
   set envProxy(proxy) {
     if (proxy !== __privateGet(this, _shaObjEnvProxy)) {
+      if (proxy) __privateMethod(this, _ShadowEnv_instances, ensureContextEffect_fn).call(this);
       const prevProxy = __privateGet(this, _shaObjEnvProxy);
       __privateSet(this, _shaObjEnvProxy, proxy ?? void 0);
+      const generation = ++__privateWrapper(this, _proxyGeneration)._;
       if (__privateGet(this, _shaObjEnvProxy)) {
         __privateGet(this, _shaObjEnvProxy).onMessageToView = __privateMethod(this, _ShadowEnv_instances, onMessageToView_fn).bind(this);
         __privateGet(this, _shaObjEnvProxy).onProxyFailed = __privateMethod(this, _ShadowEnv_instances, onProxyFailed_fn).bind(this);
       }
       if (prevProxy) {
         prevProxy.destroy();
+        prevProxy.onProxyFailed = void 0;
+        queueMicrotask(() => {
+          prevProxy.onMessageToView = void 0;
+        });
       }
       this.proxyReady = false;
       proxy?.start().then(() => {
+        if (generation !== __privateGet(this, _proxyGeneration)) return;
         this.proxyReady = true;
       }).catch((error) => {
+        if (generation !== __privateGet(this, _proxyGeneration)) return;
         this.logger.error("failed to start envProxy", error);
         this.proxyReady = false;
       });
@@ -167,6 +233,21 @@ const _ShadowEnv = class _ShadowEnv {
   get isReady() {
     return Boolean(__privateGet(this, _comCtx) && __privateGet(this, _shaObjEnvProxy) && this.proxyReady && !this.isDestroyed);
   }
+  /**
+   * Send the change trail without asking the Shadow Environment to confirm it --
+   * {@link ShadowEnv.syncWait} is the call that asks.
+   *
+   * What becomes of a refusal is then the proxy's decision, and the two shipped ones differ.
+   * `LocalShadowObjectEnv` runs the Kernel synchronously, inside the call the environment makes to
+   * the proxy -- one microtask after `sync()` returned, not inside the call to `sync()` itself --
+   * and rejects with what it threw, so a refusal reaches {@link ShadowEnv.SyncFailed} here as well,
+   * carrying its number.
+   * `RemoteWorkerEnv` sends no serial without a confirmation and gets no answer back, so a
+   * refusal stays in the worker: it is written to the console there, `SyncFailed` stays silent, and
+   * the whole trail is booked as applied.
+   *
+   * {@link ShadowEnv.syncWait} is the way both proxies answer on.
+   */
   sync() {
     if (__privateGet(this, _isDestroyed)) return;
     if (!this.isReady) {
@@ -180,27 +261,91 @@ const _ShadowEnv = class _ShadowEnv {
   /**
    * Like {@link ShadowEnv.sync}, but resolves with the change trail once the cycle completed.
    *
-   * @throws {ShadowEnvDestroyedError} if the environment is destroyed before that happens
+   * A cycle whose change trail the Shadow Environment could not apply rejects instead, with the
+   * reason the proxy gave. Where the Kernel itself refused the trail that reason is a
+   * {@link ChangeTrailRefusedError}: it names how many entries the Kernel applied, this side folds
+   * exactly those into its bookkeeping, and everything behind that line stays pending and goes out
+   * again with the next cycle. A trail whose cause of refusal stays put is refused every time, which
+   * is what {@link ShadowEnv.SyncFailed} is the place to act on.
+   *
+   * A reason that says nothing about how far the Kernel got -- a confirmation window that ran out,
+   * a proxy whose environment is gone -- counts the whole trail as applied, because a Shadow
+   * Environment that fell silent may well hold all of it. Then the trail is gone, and only a
+   * re-creation from the Component Memory brings it back. That re-creation belongs to a fresh
+   * proxy: an environment that still holds the entities refuses a creation for a uuid it already
+   * has. Handing {@link ShadowEnv.envProxy} a new proxy is therefore the way back -- the Shadow
+   * Environment calls {@link ComponentContext.reCreateChanges} itself once the new proxy is ready.
+   * Making that call is the consumer's decision, the same way recovering from a
+   * {@link ShadowEnv.ProxyFailed} is.
+   *
+   * Which cycle a caller gets is decided when the change trail is built. Everyone who arrives
+   * before that point waits on the same promise -- they all ride the same trail. From the build
+   * on the trail is fixed, and a call after it belongs to the next cycle, the one that carries
+   * the changes made since. That holds inside a listener of {@link ShadowEnv.AfterSync} or
+   * {@link ShadowEnv.SyncFailed} as well: the cycle it was told about is over, so the call opens
+   * the one behind it.
+   *
+   * @throws {ShadowEnvDestroyedError} if the environment is destroyed before the cycle completes
    */
   syncWait() {
     if (__privateGet(this, _isDestroyed)) return Promise.reject(new ShadowEnvDestroyedError());
     __privateSet(this, _syncWaitForConfirmation, true);
     this.sync();
-    if (__privateGet(this, _afterNextSync)) return __privateGet(this, _afterNextSync);
-    __privateSet(this, _afterNextSync, Promise.race([
-      onceAsync(this, _ShadowEnv.AfterSync),
-      __privateMethod(this, _ShadowEnv_instances, destroyedSignal_fn).call(this)
-    ]).then(
-      (changeTrail) => {
-        __privateSet(this, _afterNextSync, void 0);
-        return changeTrail;
-      },
-      (error) => {
-        __privateSet(this, _afterNextSync, void 0);
-        throw error;
+    __privateGet(this, _nextSyncCycle) ?? __privateSet(this, _nextSyncCycle, __privateMethod(this, _ShadowEnv_instances, openSyncCycle_fn).call(this));
+    return __privateGet(this, _nextSyncCycle).promise;
+  }
+  /**
+   * Describe this environment: the View's component tree and, where the proxy is ready and
+   * implements `inspect`, the Kernel's Entity Tree behind it.
+   *
+   * Never rejects for a reason inside the environment -- a proxy that cannot answer, a Kernel that
+   * threw, a View snapshot that threw -- and reports those under `error`, with the half that failed
+   * absent. Where both halves fail, `error` carries the View's reason. A proxy that is not ready yet
+   * is not an error either: `state.proxyReady` says so, and `kernel` is simply absent. It rejects
+   * only for a reason of the caller's: an aborted signal, or an environment that is destroyed
+   * before or while the proxy answers. The signal is raced here as well, so an abort settles the
+   * call whether or not the proxy honours the signal it was handed.
+   *
+   * A caller that wants the View and the Kernel to agree after its own change awaits
+   * {@link ShadowEnv.syncWait} first; the View snapshot reads the committed Component Memory,
+   * not the pending changes.
+   */
+  async inspect(request = {}, signal2) {
+    if (__privateGet(this, _isDestroyed)) throw new ShadowEnvDestroyedError();
+    if (signal2?.aborted) throw signal2.reason;
+    const ns = __privateGet(this, _comCtx)?.ns;
+    const proxy = __privateGet(this, _shaObjEnvProxy);
+    const snapshot = {
+      namespace: namespaceAsString(ns),
+      isGlobalNamespace: ns === GlobalNS,
+      kind: proxyKind(proxy),
+      state: { viewReady: this.viewReady, proxyReady: this.proxyReady, isReady: this.isReady, isDestroyed: __privateGet(this, _isDestroyed) }
+    };
+    if (__privateGet(this, _comCtx)) {
+      try {
+        snapshot.view = createViewSnapshot(__privateGet(this, _comCtx), request);
+      } catch (error) {
+        snapshot.error = errorInfo(error);
       }
-    ));
-    return __privateGet(this, _afterNextSync);
+    }
+    if (proxy === void 0 || !this.proxyReady) return snapshot;
+    if (typeof proxy.inspect !== "function") {
+      snapshot.error = { name: "NotInspectable", message: "the environment proxy does not implement inspect()" };
+      return snapshot;
+    }
+    const aborted = signal2 === void 0 ? void 0 : abortRace(signal2);
+    const contenders = [proxy.inspect(request, signal2), __privateMethod(this, _ShadowEnv_instances, destroyedSignal_fn).call(this)];
+    if (aborted !== void 0) contenders.push(aborted.promise);
+    try {
+      snapshot.kernel = await Promise.race(contenders);
+    } catch (error) {
+      if (__privateGet(this, _isDestroyed)) throw new ShadowEnvDestroyedError();
+      if (signal2?.aborted) throw signal2.reason;
+      if (snapshot.error === void 0) snapshot.error = errorInfo(error);
+    } finally {
+      aborted?.dispose();
+    }
+    return snapshot;
   }
   /**
    * Tear the environment down: the proxy is destroyed, the namespace is released, all signals
@@ -215,15 +360,12 @@ const _ShadowEnv = class _ShadowEnv {
     __privateSet(this, _syncScheduled, false);
     __privateSet(this, _syncAfterContextCreated, false);
     __privateSet(this, _syncWaitForConfirmation, false);
-    const ns = __privateGet(this, _comCtx)?.ns;
     this.envProxy = void 0;
     this.view = void 0;
-    const shadowEnvs = globalThis.__shadowEnvs;
-    if (ns && shadowEnvs?.get(ns) === this) {
-      shadowEnvs.delete(ns);
-    }
     (_a = __privateGet(this, _rejectWhenDestroyed)) == null ? void 0 : _a.call(this, new ShadowEnvDestroyedError());
-    __privateSet(this, _afterNextSync, void 0);
+    __privateSet(this, _nextSyncCycle, void 0);
+    __privateGet(this, _contextEffect)?.destroy();
+    __privateSet(this, _contextEffect, void 0);
     destroyObjectSignals(this);
     off(this);
     Object.freeze(this);
@@ -235,13 +377,52 @@ _shaObjEnvProxy = new WeakMap();
 _syncScheduled = new WeakMap();
 _syncAfterContextCreated = new WeakMap();
 _syncWaitForConfirmation = new WeakMap();
-_afterNextSync = new WeakMap();
+_nextSyncCycle = new WeakMap();
+_logger = new WeakMap();
 _viewReady = new WeakMap();
 _proxyReady = new WeakMap();
 _isDestroyed = new WeakMap();
+_contextEffect = new WeakMap();
+_ShadowEnv_instances = new WeakSet();
+/**
+ * Builds the effect that reports {@link ShadowEnv.ContextCreated} and {@link ShadowEnv.ContextLost}
+ * once, on the first half of the environment that arrives.
+ */
+ensureContextEffect_fn = function() {
+  if (__privateGet(this, _isDestroyed) || __privateGet(this, _contextEffect) != null) return;
+  const self = this;
+  hibernate(() => {
+    __privateSet(this, _contextEffect, createEffect(() => {
+      if (this.viewReady && this.proxyReady) {
+        this.view.reCreateChanges();
+        __privateMethod(this, _ShadowEnv_instances, announceContext_fn).call(this, _ShadowEnv.ContextCreated, self);
+        if (__privateGet(this, _syncAfterContextCreated)) {
+          __privateSet(this, _syncAfterContextCreated, false);
+          __privateMethod(this, _ShadowEnv_instances, syncNow_fn).call(this);
+        }
+        return () => {
+          __privateMethod(this, _ShadowEnv_instances, announceContext_fn).call(this, _ShadowEnv.ContextLost, self);
+        };
+      }
+    }, [findObjectSignalByName(this, "viewReady"), findObjectSignalByName(this, "proxyReady")]));
+  });
+};
+/**
+ * Releases the namespace registration, but only while this environment holds it. A namespace
+ * carries one environment at a time, and an assignment that displaces another one leaves that
+ * other environment registered under nothing -- taking its entry along on the way out would
+ * make `ShadowEnv.get()` answer `undefined` for an environment that is very much alive.
+ */
+releaseNamespace_fn = function(ns) {
+  if (!ns) return;
+  const shadowEnvs = globalThis.__shadowEnvs;
+  if (shadowEnvs?.get(ns) === this) {
+    shadowEnvs.delete(ns);
+  }
+};
+_proxyGeneration = new WeakMap();
 _whenDestroyed = new WeakMap();
 _rejectWhenDestroyed = new WeakMap();
-_ShadowEnv_instances = new WeakSet();
 /**
  * A promise that rejects the moment this environment is destroyed.
  *
@@ -259,6 +440,23 @@ destroyedSignal_fn = function() {
   }
   return __privateGet(this, _whenDestroyed);
 };
+/**
+ * The cycle settles this promise by hand rather than through `AfterSync` / `SyncFailed`. A
+ * subscription made here would stand in line behind the listeners the application registered
+ * during setup, and an eventize emit stops at the first listener that throws -- everything
+ * behind it, this promise included, would be left waiting forever. Settling by hand also
+ * spares the bookkeeping a subscription per call would need: a cycle produces one of the two
+ * events, and the subscriber of the other one would stay behind and pile up.
+ */
+openSyncCycle_fn = function() {
+  let resolve;
+  let reject;
+  const outcome = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise: Promise.race([outcome, __privateMethod(this, _ShadowEnv_instances, destroyedSignal_fn).call(this)]), resolve, reject };
+};
 _syncIfScheduled = new WeakMap();
 syncNow_fn = async function() {
   __privateSet(this, _syncScheduled, false);
@@ -267,7 +465,9 @@ syncNow_fn = async function() {
     __privateSet(this, _syncAfterContextCreated, true);
     return;
   }
-  const data = this.view.buildChangeTrails();
+  const data = this.view.buildChangeTrails(false);
+  const cycle = __privateGet(this, _nextSyncCycle);
+  __privateSet(this, _nextSyncCycle, void 0);
   const waitForConfirmation = __privateGet(this, _syncWaitForConfirmation);
   __privateSet(this, _syncWaitForConfirmation, false);
   try {
@@ -275,22 +475,85 @@ syncNow_fn = async function() {
       await this.envProxy.applyChangeTrail(data, waitForConfirmation);
     }
   } catch (error) {
+    if (__privateGet(this, _isDestroyed)) return;
     this.logger.error("failed to apply change trail", error);
-  } finally {
-    emit(this, _ShadowEnv.AfterSync, data);
+    __privateMethod(this, _ShadowEnv_instances, commitSyncCycle_fn).call(this, data, error);
+    __privateMethod(this, _ShadowEnv_instances, endSyncCycle_fn).call(this, data, cycle, { reason: error });
+    return;
   }
+  if (__privateGet(this, _isDestroyed)) return;
+  __privateMethod(this, _ShadowEnv_instances, commitSyncCycle_fn).call(this, data);
+  __privateMethod(this, _ShadowEnv_instances, endSyncCycle_fn).call(this, data, cycle);
 };
-onMessageToView_fn = function(event) {
-  if (this.logger.isDebug) {
-    this.logger.debug("onMessageToView", event.type, event.data);
+/**
+ * Draws the line between what the Shadow Environment applied and what it still owes, and hands
+ * it to the view. Runs ahead of {@link ShadowEnv.#endSyncCycle} so that a `SyncFailed` listener
+ * and a waiting {@link ShadowEnv.syncWait} caller find bookkeeping that already holds.
+ *
+ * An empty change trail is settled as well: the build may have retired components even without
+ * writing an entry for any of them.
+ */
+commitSyncCycle_fn = function(changeTrail, reason) {
+  const appliedCount = reason instanceof ChangeTrailRefusedError ? reason.appliedCount : changeTrail.length;
+  this.view?.commitChangeTrail(appliedCount, changeTrail);
+};
+/**
+ * Sends one of the two context events and keeps a listener that throws to itself.
+ *
+ * Both go out from inside the effect that watches `viewReady` and `proxyReady` -- `ContextLost`
+ * from its cleanup -- so a throw would leave through whatever signal write set that effect
+ * going, and reach code that has nothing to do with either event. `emitStrict()` serves every
+ * listener whatever the one before it did, and what they threw is reported here and travels no
+ * further.
+ */
+announceContext_fn = function(eventName, self) {
+  try {
+    emitStrict(self, eventName, self);
+  } catch (error) {
+    this.logger.error(`a ${eventName} listener threw`, error);
   }
+};
+/**
+ * Ends a synchronization cycle in exactly one of its two outcomes. A cycle the Shadow
+ * Environment applied resolves {@link ShadowEnv.syncWait} and emits {@link ShadowEnv.AfterSync};
+ * a cycle whose change trail it refused rejects and emits {@link ShadowEnv.SyncFailed}. Only a
+ * listener that can tell the two apart can react to either, so no cycle ever sends both.
+ *
+ * The waiting caller is settled before the event goes out, and the emit is the last thing that
+ * happens: a settlement that travelled as a listener of its own would sit behind whatever the
+ * application registered during setup, and this method is the wrong place to make a promise
+ * depend on the order consumers subscribe in. The dispatch is `emitStrict()`, so every listener
+ * hears about the cycle whatever the one before it did, and what they threw arrives here
+ * afterwards -- one of them unchanged, several as an `AggregateError` in dispatch order. It ends
+ * here as well: `#syncNow()` runs unawaited, and an error escaping it becomes an unhandled
+ * rejection rather than a report anybody reads.
+ *
+ * Which cycle is being ended arrives as an argument: the caller carries it from the moment its
+ * change trail was built, so a cycle that is still in flight cannot be settled by the one behind it.
+ */
+endSyncCycle_fn = function(changeTrail, cycle, failure) {
+  try {
+    if (failure) {
+      cycle?.reject(failure.reason);
+      emitStrict(this, _ShadowEnv.SyncFailed, failure.reason, changeTrail, this);
+    } else {
+      cycle?.resolve(changeTrail);
+      emitStrict(this, _ShadowEnv.AfterSync, changeTrail);
+    }
+  } catch (error) {
+    this.logger.error("a sync cycle listener threw", error);
+  }
+};
+onMessageToView_fn = function(event) {
+  this.logger.debug("onMessageToView", event.type, event.data);
   this.view?.dispatchMessage(event.uuid, event.type, event.data, event.traverseChildren);
 };
 onProxyFailed_fn = function(reason) {
   if (__privateGet(this, _isDestroyed)) return;
   this.logger.error("the environment proxy failed", reason);
+  ++__privateWrapper(this, _proxyGeneration)._;
   try {
-    emit(this, _ShadowEnv.ProxyFailed, reason, this);
+    emitStrict(this, _ShadowEnv.ProxyFailed, reason, this);
   } finally {
     this.proxyReady = false;
   }
@@ -299,6 +562,7 @@ __decorateElement(_init, 4, "viewReady", _viewReady_dec, _ShadowEnv, _viewReady)
 __decorateElement(_init, 4, "proxyReady", _proxyReady_dec, _ShadowEnv, _proxyReady);
 __decoratorMetadata(_init, _ShadowEnv);
 _ShadowEnv.AfterSync = "afterSync";
+_ShadowEnv.SyncFailed = "syncFailed";
 _ShadowEnv.ContextLost = "contextLost";
 _ShadowEnv.ContextCreated = "contextCreated";
 _ShadowEnv.ProxyFailed = "proxyFailed";