@spearwolf/shadow-objects 0.33.0 → 0.34.0

package/src/view/RemoteWorkerEnv.js

@@ -1,4 +1,5 @@
-import { emit, once, retain } from "@spearwolf/eventize";
+import { emitStrict, once, retain } from "@spearwolf/eventize";
+import { ChangeTrailRefusedError } from "../ChangeTrailRefusedError.js";
 import {
   AppliedChangeTrail,
   ChangeTrail,
@@ -14,24 +15,24 @@ import {
   WorkerLoadTimeout
 } from "../constants.js";
 import createWorker from "../create-worker.js";
-import { CONSOLE_LOGGER, ConsoleLogger } from "../utils/ConsoleLogger.js";
+import { CONSOLE_LOGGER, ConsoleLogger, consoleLoggerConfigKey, loadConsoleLoggerConfig } from "../utils/ConsoleLogger.js";
 import { toUrlString } from "../utils/toUrlString.js";
-import { waitForMessageOfType } from "../utils/waitForMessageOfType.js";
-const removeTransferables = (changeTrail) => {
+import { isTimeout, MaxWorkerTimeout, waitForMessageOfType } from "../utils/waitForMessageOfType.js";
+const splitTransferables = (changeTrail) => {
+  if (!Array.isArray(changeTrail)) return { changeTrail };
+  let outbound;
   let transferables;
-  if (changeTrail != null && Array.isArray(changeTrail)) {
-    for (const changeItem of changeTrail) {
-      if (changeItem.transferables) {
-        if (!transferables) {
-          transferables = changeItem.transferables;
-        } else {
-          transferables = [...transferables, ...changeItem.transferables];
-        }
-        delete changeItem.transferables;
-      }
+  for (let i = 0; i < changeTrail.length; i++) {
+    const changeItem = changeTrail[i];
+    if (changeItem?.transferables) {
+      transferables = transferables ? [...transferables, ...changeItem.transferables] : [...changeItem.transferables];
+      outbound ??= [...changeTrail];
+      const withoutTransferables = { ...changeItem };
+      delete withoutTransferables.transferables;
+      outbound[i] = withoutTransferables;
     }
   }
-  return transferables;
+  return { changeTrail: outbound ?? changeTrail, transferables };
 };
 class WorkerFailedError extends Error {
   constructor(type, message, options) {
@@ -46,16 +47,59 @@ class WorkerDestroyedError extends Error {
     this.name = "WorkerDestroyedError";
   }
 }
+class WorkerReportedError extends Error {
+  constructor(name, message) {
+    super(message);
+    this.name = name || "Error";
+  }
+}
+const DefaultWorkerTimeouts = {
+  loadTimeout: WorkerLoadTimeout,
+  configureTimeout: WorkerConfigureTimeout,
+  changeTrailTimeout: WorkerChangeTrailTimeout,
+  destroyTimeout: WorkerDestroyTimeout
+};
+const resolveTimeouts = (options, logger) => {
+  const resolved = { ...DefaultWorkerTimeouts };
+  if (options == null) return resolved;
+  for (const key of Object.keys(DefaultWorkerTimeouts)) {
+    if (!Object.hasOwn(options, key)) continue;
+    const value = options[key];
+    if (value === void 0) continue;
+    if (isTimeout(value)) {
+      resolved[key] = value;
+    } else {
+      logger.error(`ignoring the ${key} option: expected a number of milliseconds from 1 to ${MaxWorkerTimeout}, got`, value);
+    }
+  }
+  return resolved;
+};
 class RemoteWorkerEnv {
-  constructor() {
+  constructor(options) {
     this.#isDestroyed = false;
     this.#changeTrailSerial = 0;
     /**
-     * Aborted exactly once, with the {@link WorkerFailedError} that describes the failure.
+     * Aborted exactly once, with the error that ends this environment: a {@link WorkerFailedError}
+     * when the worker broke down, a {@link WorkerDestroyedError} when it was torn down. Whichever
+     * comes first keeps the signal, so a teardown never buries the failure that provoked it.
      * It settles every request already waiting for a reply and turns away every later one.
      */
     this.#workerFailure = new AbortController();
-    this.logger = new ConsoleLogger("RemoteWorkerEnv");
+    this.#logger = new ConsoleLogger("RemoteWorkerEnv");
+    this.onWorkerError = (event) => {
+      this.handleWorkerFailure("error", event, event.message || "the worker reported an error");
+    };
+    this.onWorkerMessageError = (event) => {
+      this.handleWorkerFailure("messageerror", event, "the worker sent a message that could not be deserialized");
+    };
+    this.onMessageFromWorker = (event) => {
+      if (event.data?.type === MessageToView) {
+        this.onMessageToView?.(event.data.data);
+      } else {
+        this.logger.debug("message from worker", event);
+      }
+    };
+    this.#timeouts = Object.freeze(resolveTimeouts(options, this.logger));
     retain(this, RemoteWorkerEnv.WorkerLoaded);
     retain(this, RemoteWorkerEnv.WorkerFailed);
   }
@@ -69,6 +113,20 @@ class RemoteWorkerEnv {
   #isDestroyed;
   #changeTrailSerial;
   #workerFailure;
+  #logger;
+  /** The logger this environment reports through. */
+  get logger() {
+    return this.#logger;
+  }
+  #timeouts;
+  /**
+   * The four timeouts this environment holds itself to, resolved once when it is built. The
+   * object is frozen and the slot holds no setter, so the constructor is the one way in --
+   * and `resolveTimeouts()` vets every value that goes through it.
+   */
+  get timeouts() {
+    return this.#timeouts;
+  }
   get isDestroyed() {
     return this.#isDestroyed;
   }
@@ -80,6 +138,8 @@ class RemoteWorkerEnv {
    * `catch()` — otherwise a worker failure surfaces as an unhandled rejection.
    *
    * @throws {WorkerFailedError} if the worker fails before or after that happens
+   * @throws {WorkerDestroyedError} once the environment has been torn down — including every
+   *   read after a load that had already succeeded, because there is no environment left to hand out
    */
   get workerLoaded() {
     const { signal } = this.#workerFailure;
@@ -106,11 +166,8 @@ class RemoteWorkerEnv {
   async start() {
     const { signal } = this.#workerFailure;
     if (signal.aborted) throw signal.reason;
-    if (this.#isDestroyed) throw new WorkerDestroyedError();
     if (this.#worker) {
-      if (this.logger.isWarn) {
-        this.logger.warn("already started");
-      }
+      this.logger.warn("already started");
       return this.workerLoaded.then(() => {
         if (this.isDestroyed) {
           throw new WorkerDestroyedError();
@@ -118,22 +175,23 @@ class RemoteWorkerEnv {
       });
     }
     const worker = this.#worker = createWorker();
-    worker.addEventListener("error", this.onWorkerError.bind(this));
-    worker.addEventListener("messageerror", this.onWorkerMessageError.bind(this));
+    worker.addEventListener("error", this.onWorkerError);
+    worker.addEventListener("messageerror", this.onWorkerMessageError);
     this.configureConsoleLogger(worker);
     try {
-      await waitForMessageOfType(worker, Loaded, WorkerLoadTimeout, void 0, signal);
+      await waitForMessageOfType(worker, Loaded, this.timeouts.loadTimeout, void 0, signal);
       if (this.isDestroyed) {
-        throw new WorkerDestroyedError();
+        throw signal.aborted ? signal.reason : new WorkerDestroyedError();
       }
-      worker.addEventListener("message", this.onMessageFromWorker.bind(this));
+      worker.addEventListener("message", this.onMessageFromWorker);
       queueMicrotask(() => {
-        emit(this, RemoteWorkerEnv.WorkerLoaded, this);
+        this.announceLoaded();
       });
     } catch (error) {
       if (error !== signal.reason) {
         this.logger.error("failed to start", error);
       }
+      this.stopListeningTo(worker);
       this.#worker = void 0;
       if (!this.#isDestroyed) {
         worker.terminate();
@@ -146,27 +204,32 @@ class RemoteWorkerEnv {
     if (signal.aborted) return Promise.reject(signal.reason);
     const worker = this.#worker;
     if (worker == null) return Promise.reject(new WorkerDestroyedError());
-    const transferables = removeTransferables(changeTrail);
-    const message = { type: ChangeTrail, changeTrail };
-    const serial = ++this.#changeTrailSerial;
-    if (waitForConfirmation) {
-      message.serial = serial;
-    }
-    worker.postMessage(message, transferables ?? []);
-    if (waitForConfirmation) {
-      return waitForMessageOfType(
-        worker,
-        AppliedChangeTrail,
-        WorkerChangeTrailTimeout,
-        (data) => {
-          if (data.error) throw data.error;
-          return data.serial === serial;
-        },
-        signal
-      );
-    } else {
+    const { changeTrail: outbound, transferables } = splitTransferables(changeTrail);
+    const message = { type: ChangeTrail, changeTrail: outbound };
+    if (!waitForConfirmation) {
+      worker.postMessage(message, transferables ?? []);
       return Promise.resolve();
     }
+    const serial = ++this.#changeTrailSerial;
+    message.serial = serial;
+    worker.postMessage(message, transferables ?? []);
+    return waitForMessageOfType(
+      worker,
+      AppliedChangeTrail,
+      this.timeouts.changeTrailTimeout,
+      (data) => {
+        if (data.serial !== serial) return false;
+        if (data.error) {
+          const reason = new WorkerReportedError(data.errorName, data.error);
+          if (typeof data.appliedCount === "number") {
+            throw new ChangeTrailRefusedError(data.appliedCount, changeTrail.length, { cause: reason });
+          }
+          throw reason;
+        }
+        return true;
+      },
+      signal
+    );
   }
   importScript(url) {
     const { signal } = this.#workerFailure;
@@ -178,30 +241,29 @@ class RemoteWorkerEnv {
     return waitForMessageOfType(
       worker,
       ImportedModule,
-      WorkerConfigureTimeout,
+      this.timeouts.configureTimeout,
       (data) => {
-        if (data.error) throw data.error;
-        return data.url === url;
+        if (data.url !== url) return false;
+        if (data.error) throw new WorkerReportedError(data.errorName, data.error);
+        return true;
       },
       signal
     );
   }
   destroy() {
-    if (!this.#worker) return;
+    this.#isDestroyed = true;
     const worker = this.#worker;
     this.#worker = void 0;
-    this.#isDestroyed = true;
+    this.#workerFailure.abort(new WorkerDestroyedError());
+    if (worker == null) return;
+    this.stopListeningTo(worker);
     worker.postMessage({ type: Destroy });
-    waitForMessageOfType(worker, Destroyed, WorkerDestroyTimeout).finally(() => {
+    waitForMessageOfType(worker, Destroyed, this.timeouts.destroyTimeout).catch((error) => {
+      this.logger.warn("the worker did not acknowledge the teardown", error);
+    }).finally(() => {
       worker.terminate();
     });
   }
-  onWorkerError(event) {
-    this.handleWorkerFailure("error", event, event.message || "the worker reported an error");
-  }
-  onWorkerMessageError(event) {
-    this.handleWorkerFailure("messageerror", event, "the worker sent a message that could not be deserialized");
-  }
   handleWorkerFailure(type, event, message) {
     if (this.#isDestroyed) return;
     this.#isDestroyed = true;
@@ -211,6 +273,7 @@ class RemoteWorkerEnv {
     this.logger.error(message, event);
     const worker = this.#worker;
     this.#worker = void 0;
+    if (worker != null) this.stopListeningTo(worker);
     this.#workerFailure.abort(reason);
     worker?.terminate();
     try {
@@ -218,27 +281,59 @@ class RemoteWorkerEnv {
     } catch (error) {
       this.logger.error("the proxy-failed callback threw", error);
     }
-    emit(this, RemoteWorkerEnv.WorkerFailed, {
-      env: this,
-      type,
-      message,
-      reason,
-      event
-    });
+    this.announceFailure({ env: this, type, message, reason, event });
   }
-  onMessageFromWorker(event) {
-    if (event.data?.type === MessageToView) {
-      this.onMessageToView?.(event.data.data);
-    } else if (this.logger.isDebug) {
-      this.logger.debug("message from worker", event);
+  /**
+   * Announces the completed handshake to the consumers.
+   *
+   * `emitStrict()` rather than `emit()`, and the retain policy is what decides it. `workerLoaded`
+   * reads the retained value, and eventize writes that value only once the dispatch has run
+   * through: under the plain dispatch a single listener that throws would take the replay for
+   * every later subscriber with it, and every later read of `workerLoaded` would wait for a
+   * failure or a teardown instead of resolving. The guarded dispatch serves every listener and
+   * writes the retained value, because the event was delivered.
+   *
+   * What the listeners threw arrives here afterwards -- one of them unchanged, several as an
+   * `AggregateError` in dispatch order -- and is reported. It goes no further: this runs from a
+   * microtask, where a throw has no caller left to reach and would surface as an unhandled error.
+   */
+  announceLoaded() {
+    try {
+      emitStrict(this, RemoteWorkerEnv.WorkerLoaded, this);
+    } catch (error) {
+      this.logger.error("a workerLoaded listener threw", error);
     }
   }
-  configureConsoleLogger(worker) {
-    const workerConfigKey = `${CONSOLE_LOGGER}.RemoteWorkerEnv.workerConfig`;
-    const workerConfig = JSON.parse(localStorage.getItem(workerConfigKey) ?? "{}");
-    if (this.logger.isInfo) {
-      this.logger.info("load console-logger worker config", { localStorageKey: workerConfigKey, workerConfig });
+  /**
+   * Announces the failure to the consumers. The same guarded dispatch as
+   * {@link RemoteWorkerEnv.announceLoaded}, for the same reason: `WorkerFailed` is documented as
+   * retained, and a consumer that subscribes only after the failure has to be able to hear about
+   * it. Every listener is served, the retained value is written, and whatever was thrown is
+   * reported here and reaches no caller.
+   */
+  announceFailure(payload) {
+    try {
+      emitStrict(this, RemoteWorkerEnv.WorkerFailed, payload);
+    } catch (error) {
+      this.logger.error("a workerFailed listener threw", error);
     }
+  }
+  /**
+   * Takes every listener of this environment off a worker. Whoever registered them takes them
+   * off again -- between the teardown and the `terminate()` that ends it the worker stays
+   * alive, and through its listeners it keeps this environment and everything it references
+   * reachable for exactly that long.
+   */
+  stopListeningTo(worker) {
+    worker.removeEventListener("error", this.onWorkerError);
+    worker.removeEventListener("messageerror", this.onWorkerMessageError);
+    worker.removeEventListener("message", this.onMessageFromWorker);
+  }
+  configureConsoleLogger(worker) {
+    const configKey = ["RemoteWorkerEnv", "workerConfig"];
+    const storageKey = consoleLoggerConfigKey(configKey);
+    const workerConfig = this.readWorkerConfig(configKey, storageKey);
+    this.logger.info("load console-logger worker config", { storageKey, workerConfig });
     worker.postMessage({
       type: CONSOLE_LOGGER,
       config: {
@@ -249,10 +344,33 @@ class RemoteWorkerEnv {
       }
     });
   }
+  /**
+   * The console-logger config for the worker, read from the storage key this environment
+   * announces. The key is a diagnostic switch, set by hand and sharing its namespace with
+   * everything else on this origin, so its content decides nothing about whether the worker
+   * comes up: anything that is not a plain JSON object counts as no config at all, exactly
+   * like an absent key.
+   */
+  readWorkerConfig(configKey, storageKey) {
+    const stored = loadConsoleLoggerConfig(configKey, "{}");
+    let parsed;
+    try {
+      parsed = JSON.parse(stored);
+    } catch (error) {
+      this.logger.error(`ignoring the unreadable console-logger worker config at "${storageKey}"`, stored, error);
+      return {};
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      this.logger.error(`ignoring the console-logger worker config at "${storageKey}": expected a JSON object`, stored);
+      return {};
+    }
+    return parsed;
+  }
 }
 export {
   RemoteWorkerEnv,
   WorkerDestroyedError,
-  WorkerFailedError
+  WorkerFailedError,
+  WorkerReportedError
 };
 //# sourceMappingURL=RemoteWorkerEnv.js.map

package/src/view/RemoteWorkerEnv.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/view/RemoteWorkerEnv.ts"],
-  "sourcesContent": ["import {emit, once, retain} from '@spearwolf/eventize';\nimport {\n  AppliedChangeTrail,\n  ChangeTrail,\n  Configure,\n  Destroy,\n  Destroyed,\n  ImportedModule,\n  Loaded,\n  MessageToView,\n  WorkerChangeTrailTimeout,\n  WorkerConfigureTimeout,\n  WorkerDestroyTimeout,\n  WorkerLoadTimeout,\n} from '../constants.js';\nimport createWorker from '../create-worker.js';\nimport type {AppliedChangeTrailEvent, ChangeTrailType, ImportedModuleEvent, TransferablesType} from '../types.js';\nimport {CONSOLE_LOGGER, ConsoleLogger} from '../utils/ConsoleLogger.js';\nimport {toUrlString} from '../utils/toUrlString.js';\nimport {waitForMessageOfType} from '../utils/waitForMessageOfType.js';\nimport type {IShadowObjectEnvProxy} from './IShadowObjectEnvProxy.js';\n\nconst removeTransferables = (changeTrail: ChangeTrailType): TransferablesType | undefined => {\n  let transferables: TransferablesType | undefined;\n\n  if (changeTrail != null && Array.isArray(changeTrail)) {\n    for (const changeItem of changeTrail) {\n      if (changeItem.transferables) {\n        if (!transferables) {\n          transferables = changeItem.transferables;\n        } else {\n          transferables = [...transferables, ...changeItem.transferables];\n        }\n        delete changeItem.transferables;\n      }\n    }\n  }\n\n  return transferables;\n};\n\n/**\n * The reason every pending and every later worker request is rejected with\n * once the worker has failed.\n */\nexport class WorkerFailedError extends Error {\n  /** `'error'` when the worker itself threw, `'messageerror'` when it sent something that could not be deserialized. */\n  readonly type: 'error' | 'messageerror';\n\n  constructor(type: 'error' | 'messageerror', message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'WorkerFailedError';\n    this.type = type;\n  }\n}\n\n/**\n * The reason a request is rejected with once the environment has been torn down\n * with {@link RemoteWorkerEnv.destroy}. The worker is gone; no reply can arrive.\n */\nexport class WorkerDestroyedError extends Error {\n  constructor(message = 'the worker environment has been destroyed') {\n    super(message);\n    this.name = 'WorkerDestroyedError';\n  }\n}\n\n/** What {@link RemoteWorkerEnv.WorkerFailed} carries. */\nexport interface WorkerFailedEvent {\n  /** the environment whose worker failed */\n  env: RemoteWorkerEnv;\n  /** what the worker reported */\n  type: 'error' | 'messageerror';\n  /** a readable description of the failure */\n  message: string;\n  /** the error every pending and every later request is rejected with */\n  reason: WorkerFailedError;\n  /** the worker event the failure was read from */\n  event: ErrorEvent | MessageEvent;\n}\n\nexport class RemoteWorkerEnv implements IShadowObjectEnvProxy {\n  static WorkerLoaded = 'workerLoaded';\n  static WorkerFailed = 'workerFailed';\n\n  #worker?: Worker;\n  #isDestroyed = false;\n  #changeTrailSerial = 0;\n\n  /**\n   * Aborted exactly once, with the {@link WorkerFailedError} that describes the failure.\n   * It settles every request already waiting for a reply and turns away every later one.\n   */\n  readonly #workerFailure = new AbortController();\n\n  readonly logger = new ConsoleLogger('RemoteWorkerEnv');\n\n  get isDestroyed(): boolean {\n    return this.#isDestroyed;\n  }\n\n  /**\n   * Resolves once the worker is up.\n   *\n   * Every read hands out a promise that can reject, so a caller that only wants to\n   * kick the environment off and never awaits the result should still attach a\n   * `catch()` \u2014 otherwise a worker failure surfaces as an unhandled rejection.\n   *\n   * @throws {WorkerFailedError} if the worker fails before or after that happens\n   */\n  get workerLoaded(): Promise<RemoteWorkerEnv> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    return new Promise<RemoteWorkerEnv>((resolve, reject) => {\n      let unsubscribeLoaded: (() => void) | undefined;\n      let settled = false;\n\n      const onFailure = () => {\n        if (settled) return;\n        settled = true;\n        unsubscribeLoaded?.();\n        reject(signal.reason);\n      };\n\n      unsubscribeLoaded = once(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded, (env: RemoteWorkerEnv) => {\n        if (settled) return;\n        settled = true;\n        signal.removeEventListener('abort', onFailure);\n        resolve(env);\n      });\n\n      // a retained WorkerLoaded is replayed inside once(), before it returns \u2014\n      // then there is nothing left to wait for and no abort listener to attach\n      if (settled) return;\n\n      signal.addEventListener('abort', onFailure, {once: true});\n    });\n  }\n\n  constructor() {\n    retain(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded);\n    // a consumer that subscribes only after the failure still gets to hear about it\n    retain(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerFailed);\n  }\n\n  async start(): Promise<void> {\n    // both guards are needed, and in this order: a failure aborts the signal *and* marks the\n    // environment destroyed, so asking about the teardown first would bury the more precise\n    // reason \u2014 while a teardown leaves the signal untouched and would slip past it\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) throw signal.reason;\n\n    // a torn-down environment must not spawn a worker: nothing would ever reach it, and\n    // nothing would ever shut it down again\n    if (this.#isDestroyed) throw new WorkerDestroyedError();\n\n    if (this.#worker) {\n      if (this.logger.isWarn) {\n        this.logger.warn('already started');\n      }\n\n      return this.workerLoaded.then((): void => {\n        if (this.isDestroyed) {\n          throw new WorkerDestroyedError();\n        }\n      });\n    }\n\n    const worker = (this.#worker = createWorker());\n\n    // registered before the load handshake begins: a worker that dies while it is\n    // still coming up must not leave the caller waiting for the load timeout\n    worker.addEventListener('error', this.onWorkerError.bind(this));\n    worker.addEventListener('messageerror', this.onWorkerMessageError.bind(this));\n\n    this.configureConsoleLogger(worker);\n\n    try {\n      await waitForMessageOfType(worker, Loaded, WorkerLoadTimeout, undefined, signal);\n\n      if (this.isDestroyed) {\n        throw new WorkerDestroyedError();\n      }\n\n      worker.addEventListener('message', this.onMessageFromWorker.bind(this));\n\n      queueMicrotask(() => {\n        emit(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded, this);\n      });\n    } catch (error) {\n      // the failure path reports with the worker event in hand; anything else is on us\n      if (error !== signal.reason) {\n        this.logger.error('failed to start', error);\n      }\n\n      this.#worker = undefined;\n\n      // only a start that nobody else is unwinding owns this worker: the reference is gone,\n      // nobody can reach it any more, and leaving it running would keep a thread open for an\n      // environment that never started. A failure has already terminated it, and a teardown\n      // in flight is waiting for its Destroyed reply \u2014 cutting that short here would leave\n      // destroy() to sit out its timeout and skip the worker-side teardown entirely.\n      if (!this.#isDestroyed) {\n        worker.terminate();\n      }\n\n      throw error;\n    }\n  }\n\n  applyChangeTrail(changeTrail: ChangeTrailType, waitForConfirmation: boolean): Promise<void> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    const worker = this.#worker;\n    if (worker == null) return Promise.reject(new WorkerDestroyedError());\n\n    const transferables = removeTransferables(changeTrail);\n    const message = {type: ChangeTrail, changeTrail} as any;\n\n    const serial = ++this.#changeTrailSerial;\n    if (waitForConfirmation) {\n      message.serial = serial;\n    }\n\n    worker.postMessage(message, transferables ?? []);\n\n    if (waitForConfirmation) {\n      return waitForMessageOfType(\n        worker,\n        AppliedChangeTrail,\n        WorkerChangeTrailTimeout,\n        (data: AppliedChangeTrailEvent) => {\n          if (data.error) throw data.error;\n          return data.serial === serial;\n        },\n        signal,\n      );\n    } else {\n      return Promise.resolve();\n    }\n  }\n\n  importScript(url: URL | string): Promise<void> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    const worker = this.#worker;\n    if (worker == null) return Promise.reject(new WorkerDestroyedError());\n\n    url = toUrlString(url);\n    worker.postMessage({type: Configure, importModule: url});\n    return waitForMessageOfType(\n      worker,\n      ImportedModule,\n      WorkerConfigureTimeout,\n      (data: ImportedModuleEvent) => {\n        if (data.error) throw data.error;\n        return data.url === url;\n      },\n      signal,\n    );\n  }\n\n  destroy(): void {\n    if (!this.#worker) return;\n\n    const worker = this.#worker;\n    this.#worker = undefined;\n\n    this.#isDestroyed = true;\n\n    worker.postMessage({type: Destroy});\n\n    waitForMessageOfType(worker, Destroyed, WorkerDestroyTimeout).finally(() => {\n      worker.terminate();\n    });\n  }\n\n  private onWorkerError(event: ErrorEvent) {\n    this.handleWorkerFailure('error', event, event.message || 'the worker reported an error');\n  }\n\n  private onWorkerMessageError(event: MessageEvent) {\n    this.handleWorkerFailure('messageerror', event, 'the worker sent a message that could not be deserialized');\n  }\n\n  private handleWorkerFailure(type: 'error' | 'messageerror', event: ErrorEvent | MessageEvent, message: string): void {\n    // a deliberate teardown, or a failure that was already reported: the first one wins\n    if (this.#isDestroyed) return;\n\n    this.#isDestroyed = true;\n\n    const reason = new WorkerFailedError(type, message, {\n      cause: type === 'error' ? ((event as ErrorEvent).error ?? event) : event,\n    });\n\n    this.logger.error(message, event);\n\n    const worker = this.#worker;\n    this.#worker = undefined;\n\n    // settle everyone waiting for a reply before the worker goes away \u2014 it can no longer arrive\n    this.#workerFailure.abort(reason);\n\n    worker?.terminate();\n\n    // the ShadowEnv is told first, so that the state it derives from this is already\n    // settled when consumers hear about it. Whatever happens down that path stays\n    // there \u2014 the public event is announced either way\n    try {\n      (this as IShadowObjectEnvProxy).onProxyFailed?.(reason);\n    } catch (error) {\n      this.logger.error('the proxy-failed callback threw', error);\n    }\n\n    emit(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerFailed, {\n      env: this,\n      type,\n      message,\n      reason,\n      event,\n    } as WorkerFailedEvent);\n  }\n\n  private onMessageFromWorker(event: MessageEvent) {\n    if (event.data?.type === MessageToView) {\n      (this as IShadowObjectEnvProxy).onMessageToView?.(event.data.data);\n    } else if (this.logger.isDebug) {\n      this.logger.debug('message from worker', event);\n    }\n  }\n\n  private configureConsoleLogger(worker: Worker) {\n    const workerConfigKey = `${CONSOLE_LOGGER}.RemoteWorkerEnv.workerConfig`;\n    const workerConfig = JSON.parse(localStorage.getItem(workerConfigKey) ?? '{}');\n\n    if (this.logger.isInfo) {\n      this.logger.info('load console-logger worker config', {localStorageKey: workerConfigKey, workerConfig});\n    }\n\n    worker.postMessage({\n      type: CONSOLE_LOGGER,\n      config: {\n        ...ConsoleLogger.sharedConfig,\n        enable: this.logger.isEnabled,\n        ...workerConfig,\n        ...(ConsoleLogger.isEnabled ? {} : {enable: false}),\n      },\n    });\n  }\n}"],
-  "mappings": "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",
+  "sourcesContent": ["import {emitStrict, once, retain} from '@spearwolf/eventize';\nimport {ChangeTrailRefusedError} from '../ChangeTrailRefusedError.js';\nimport {\n  AppliedChangeTrail,\n  ChangeTrail,\n  Configure,\n  Destroy,\n  Destroyed,\n  ImportedModule,\n  Loaded,\n  MessageToView,\n  WorkerChangeTrailTimeout,\n  WorkerConfigureTimeout,\n  WorkerDestroyTimeout,\n  WorkerLoadTimeout,\n} from '../constants.js';\nimport createWorker from '../create-worker.js';\nimport type {AppliedChangeTrailEvent, ChangeTrailType, ImportedModuleEvent, SyncEvent, TransferablesType} from '../types.js';\nimport {CONSOLE_LOGGER, ConsoleLogger, consoleLoggerConfigKey, loadConsoleLoggerConfig} from '../utils/ConsoleLogger.js';\nimport {toUrlString} from '../utils/toUrlString.js';\nimport {isTimeout, MaxWorkerTimeout, waitForMessageOfType} from '../utils/waitForMessageOfType.js';\nimport type {IShadowObjectEnvProxy} from './IShadowObjectEnvProxy.js';\n\n/**\n * Splits the transferables out of a change trail without writing to it. The trail handed in is a\n * snapshot that travels on after this call -- to the `ShadowEnv.AfterSync` consumers when the\n * environment applies it, to the `ShadowEnv.SyncFailed` consumers when it refuses it -- so an\n * entry carrying transferables is replaced by a shallow copy without them and every other\n * entry is passed through as it is. A trail that carries none is handed back object for\n * object.\n */\nconst splitTransferables = (\n  changeTrail: ChangeTrailType,\n): {changeTrail: ChangeTrailType; transferables?: TransferablesType | undefined} => {\n  if (!Array.isArray(changeTrail)) return {changeTrail};\n\n  let outbound: ChangeTrailType | undefined;\n  let transferables: TransferablesType | undefined;\n\n  for (let i = 0; i < changeTrail.length; i++) {\n    const changeItem = changeTrail[i];\n    if (changeItem?.transferables) {\n      transferables = transferables ? [...transferables, ...changeItem.transferables] : [...changeItem.transferables];\n\n      outbound ??= [...changeTrail];\n      const withoutTransferables = {...changeItem};\n      delete withoutTransferables.transferables;\n      outbound[i] = withoutTransferables;\n    }\n  }\n\n  return {changeTrail: outbound ?? changeTrail, transferables};\n};\n\n/**\n * What actually goes on the wire for a `ChangeTrail` message. `SyncEvent` describes the shape a\n * change trail carries once it is inside the worker, without the `type` discriminant that gets\n * it there \u2014 its two neighbors on the wire (`ImportedModuleEvent`, `AppliedChangeTrailEvent`)\n * both require that field, so adding it to `SyncEvent` itself would either make it mandatory\n * where `LocalShadowObjectEnv` never sets it, or optional on a public type whose neighbors need\n * it required. Kept local instead: it says exactly what this message is without touching the\n * exported type surface.\n */\ninterface ChangeTrailMessage extends SyncEvent {\n  type: typeof ChangeTrail;\n}\n\n/**\n * The reason every pending and every later worker request is rejected with\n * once the worker has failed.\n */\nexport class WorkerFailedError extends Error {\n  /** `'error'` when the worker itself threw, `'messageerror'` when it sent something that could not be deserialized. */\n  readonly type: 'error' | 'messageerror';\n\n  constructor(type: 'error' | 'messageerror', message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'WorkerFailedError';\n    this.type = type;\n  }\n}\n\n/**\n * The reason a request is rejected with once the environment has been torn down\n * with {@link RemoteWorkerEnv.destroy}. The worker is gone; no reply can arrive.\n */\nexport class WorkerDestroyedError extends Error {\n  constructor(message = 'the worker environment has been destroyed') {\n    super(message);\n    this.name = 'WorkerDestroyedError';\n  }\n}\n\n/**\n * The reason a request is rejected with when the worker reported a failure of its own -- a\n * module that would not import, a change trail its Kernel refused. An error does not survive\n * structured cloning as the object it is, so the two fields that do are rebuilt here, and\n * `name` is the name the error called itself inside the worker: a caller reads it the same\n * way it reads the name of an error a `LocalShadowObjectEnv` hands it. A name that is missing\n * or empty names no class, and `Error` is what such a reason is called -- the same name a\n * plain `new Error(message)` carries on the local side.\n *\n * What does not come across is the class and everything it added. `instanceof EntityUuidInUseError`\n * is `false` here and there is no `uuid` field, whatever `name` says; `instanceof WorkerReportedError`\n * is what tells such a reason apart from one raised on this side.\n */\nexport class WorkerReportedError extends Error {\n  constructor(name: string | undefined, message: string) {\n    super(message);\n    this.name = name || 'Error';\n  }\n}\n\n/**\n * How long a {@link RemoteWorkerEnv} waits for each of the four replies a worker owes it,\n * in milliseconds.\n */\nexport interface WorkerTimeouts {\n  /** the `Loaded` handshake at the start */\n  loadTimeout: number;\n  /** the `ImportedModule` reply to an `importScript()` */\n  configureTimeout: number;\n  /** the `AppliedChangeTrail` confirmation of a change trail sent with `waitForConfirmation` */\n  changeTrailTimeout: number;\n  /** the `Destroyed` acknowledgement of a teardown */\n  destroyTimeout: number;\n}\n\n/**\n * What {@link RemoteWorkerEnv} takes. Every value left out keeps its default \u2014 the four\n * `Worker*Timeout` constants. A value that is not a number of milliseconds from 1 to\n * 2147483647 \u2014 close to 25 days, the longest delay a timer keeps \u2014 is reported through the\n * logger and the default applies.\n */\nexport type RemoteWorkerEnvOptions = Partial<WorkerTimeouts>;\n\nconst DefaultWorkerTimeouts: WorkerTimeouts = {\n  loadTimeout: WorkerLoadTimeout,\n  configureTimeout: WorkerConfigureTimeout,\n  changeTrailTimeout: WorkerChangeTrailTimeout,\n  destroyTimeout: WorkerDestroyTimeout,\n};\n\n/**\n * Resolves the options against the defaults. A timeout is a number of milliseconds from 1 to\n * {@link MaxWorkerTimeout}; anything else is refused and reported, and the default stays.\n *\n * Zero and Infinity are refused along with the rest, and that is the point of the rule rather\n * than an oversight: `waitForMessageOfType()` arms no timer for either of them, so a teardown\n * given one of the two would wait for an acknowledgement a dead worker never sends \u2014 and the\n * `terminate()` that ends the teardown hangs on that very chain. One rule for all four values\n * is easier to hold on to than three that allow it and one that does not, and {@link MaxWorkerTimeout}\n * \u2014 close to 25 days \u2014 is as long as a wait can honestly be made.\n */\nconst resolveTimeouts = (options: RemoteWorkerEnvOptions | undefined, logger: ConsoleLogger): WorkerTimeouts => {\n  const resolved: WorkerTimeouts = {...DefaultWorkerTimeouts};\n  if (options == null) return resolved;\n\n  for (const key of Object.keys(DefaultWorkerTimeouts) as (keyof WorkerTimeouts)[]) {\n    // own keys only: what an object inherits from its prototype is not what its author wrote down\n    if (!Object.hasOwn(options, key)) continue;\n\n    const value = options[key];\n    if (value === undefined) continue;\n\n    if (isTimeout(value)) {\n      resolved[key] = value;\n    } else {\n      logger.error(`ignoring the ${key} option: expected a number of milliseconds from 1 to ${MaxWorkerTimeout}, got`, value);\n    }\n  }\n\n  return resolved;\n};\n\n/** What {@link RemoteWorkerEnv.WorkerFailed} carries. */\nexport interface WorkerFailedEvent {\n  /** the environment whose worker failed */\n  env: RemoteWorkerEnv;\n  /** what the worker reported */\n  type: 'error' | 'messageerror';\n  /** a readable description of the failure */\n  message: string;\n  /** the error every pending and every later request is rejected with */\n  reason: WorkerFailedError;\n  /** the worker event the failure was read from */\n  event: ErrorEvent | MessageEvent;\n}\n\nexport class RemoteWorkerEnv implements IShadowObjectEnvProxy {\n  static WorkerLoaded = 'workerLoaded';\n  static WorkerFailed = 'workerFailed';\n\n  #worker?: Worker | undefined;\n  #isDestroyed = false;\n  #changeTrailSerial = 0;\n\n  /**\n   * Aborted exactly once, with the error that ends this environment: a {@link WorkerFailedError}\n   * when the worker broke down, a {@link WorkerDestroyedError} when it was torn down. Whichever\n   * comes first keeps the signal, so a teardown never buries the failure that provoked it.\n   * It settles every request already waiting for a reply and turns away every later one.\n   */\n  readonly #workerFailure = new AbortController();\n\n  readonly #logger = new ConsoleLogger('RemoteWorkerEnv');\n\n  /** The logger this environment reports through. */\n  get logger(): ConsoleLogger {\n    return this.#logger;\n  }\n\n  readonly #timeouts: Readonly<WorkerTimeouts>;\n\n  /**\n   * The four timeouts this environment holds itself to, resolved once when it is built. The\n   * object is frozen and the slot holds no setter, so the constructor is the one way in --\n   * and `resolveTimeouts()` vets every value that goes through it.\n   */\n  get timeouts(): Readonly<WorkerTimeouts> {\n    return this.#timeouts;\n  }\n\n  get isDestroyed(): boolean {\n    return this.#isDestroyed;\n  }\n\n  /**\n   * Resolves once the worker is up.\n   *\n   * Every read hands out a promise that can reject, so a caller that only wants to\n   * kick the environment off and never awaits the result should still attach a\n   * `catch()` \u2014 otherwise a worker failure surfaces as an unhandled rejection.\n   *\n   * @throws {WorkerFailedError} if the worker fails before or after that happens\n   * @throws {WorkerDestroyedError} once the environment has been torn down \u2014 including every\n   *   read after a load that had already succeeded, because there is no environment left to hand out\n   */\n  get workerLoaded(): Promise<RemoteWorkerEnv> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    return new Promise<RemoteWorkerEnv>((resolve, reject) => {\n      let unsubscribeLoaded: (() => void) | undefined;\n      let settled = false;\n\n      const onFailure = () => {\n        if (settled) return;\n        settled = true;\n        unsubscribeLoaded?.();\n        reject(signal.reason);\n      };\n\n      unsubscribeLoaded = once(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded, (env: RemoteWorkerEnv) => {\n        if (settled) return;\n        settled = true;\n        signal.removeEventListener('abort', onFailure);\n        resolve(env);\n      });\n\n      // a retained WorkerLoaded is replayed inside once(), before it returns \u2014\n      // then there is nothing left to wait for and no abort listener to attach\n      if (settled) return;\n\n      signal.addEventListener('abort', onFailure, {once: true});\n    });\n  }\n\n  constructor(options?: RemoteWorkerEnvOptions) {\n    // the logger is a field initializer and is therefore already in place\n    this.#timeouts = Object.freeze(resolveTimeouts(options, this.logger));\n\n    retain(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded);\n    // a consumer that subscribes only after the failure still gets to hear about it\n    retain(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerFailed);\n  }\n\n  async start(): Promise<void> {\n    // both endings of this environment abort the signal, and it keeps the reason of whichever\n    // came first. A finished environment must not spawn a worker: nothing would ever reach it,\n    // and nothing would ever shut it down again\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) throw signal.reason;\n\n    if (this.#worker) {\n      this.logger.warn('already started');\n\n      return this.workerLoaded.then((): void => {\n        if (this.isDestroyed) {\n          throw new WorkerDestroyedError();\n        }\n      });\n    }\n\n    const worker = (this.#worker = createWorker());\n\n    // registered before the load handshake begins: a worker that dies while it is\n    // still coming up must not leave the caller waiting for the load timeout\n    worker.addEventListener('error', this.onWorkerError);\n    worker.addEventListener('messageerror', this.onWorkerMessageError);\n\n    this.configureConsoleLogger(worker);\n\n    try {\n      await waitForMessageOfType(worker, Loaded, this.timeouts.loadTimeout, undefined, signal);\n\n      // the handshake completed but the environment ended while its reply was on the way here.\n      // The reason of that ending is what the caller gets \u2014 a fresh error of our own would read\n      // as a start that went wrong, and the catch below would report it as one\n      if (this.isDestroyed) {\n        throw signal.aborted ? signal.reason : new WorkerDestroyedError();\n      }\n\n      worker.addEventListener('message', this.onMessageFromWorker);\n\n      queueMicrotask(() => {\n        this.announceLoaded();\n      });\n    } catch (error) {\n      // the failure path reports with the worker event in hand; anything else is on us\n      if (error !== signal.reason) {\n        this.logger.error('failed to start', error);\n      }\n\n      this.stopListeningTo(worker);\n      this.#worker = undefined;\n\n      // only a start that nobody else is unwinding owns this worker: the reference is gone,\n      // nobody can reach it any more, and leaving it running would keep a thread open for an\n      // environment that never started. A failure has already terminated it, and a teardown\n      // in flight is waiting for its Destroyed reply \u2014 cutting that short here would leave\n      // destroy() to sit out its timeout and skip the worker-side teardown entirely.\n      if (!this.#isDestroyed) {\n        worker.terminate();\n      }\n\n      throw error;\n    }\n  }\n\n  applyChangeTrail(changeTrail: ChangeTrailType, waitForConfirmation: boolean): Promise<void> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    const worker = this.#worker;\n    if (worker == null) return Promise.reject(new WorkerDestroyedError());\n\n    const {changeTrail: outbound, transferables} = splitTransferables(changeTrail);\n    const message: ChangeTrailMessage = {type: ChangeTrail, changeTrail: outbound};\n\n    if (!waitForConfirmation) {\n      worker.postMessage(message, transferables ?? []);\n      return Promise.resolve();\n    }\n\n    // the counter moves only where a number actually goes on the wire: it is the sole link\n    // between a request and its confirmation, and a sequence with invisible jumps in it tells\n    // a later diagnosis nothing\n    const serial = ++this.#changeTrailSerial;\n    message.serial = serial;\n\n    worker.postMessage(message, transferables ?? []);\n\n    return waitForMessageOfType(\n      worker,\n      AppliedChangeTrail,\n      this.timeouts.changeTrailTimeout,\n      (data: AppliedChangeTrailEvent) => {\n        // the serial decides who a confirmation concerns -- an error belonging to another\n        // trail would otherwise reject the request that happens to be waiting here\n        if (data.serial !== serial) return false;\n        if (data.error) {\n          const reason = new WorkerReportedError(data.errorName, data.error);\n          // Only a confirmation that names the count can move the line the view draws between\n          // applied and pending; one that does not carries no more than the reason itself, and\n          // is handed on as that reason.\n          if (typeof data.appliedCount === 'number') {\n            throw new ChangeTrailRefusedError(data.appliedCount, changeTrail.length, {cause: reason});\n          }\n          throw reason;\n        }\n        return true;\n      },\n      signal,\n    );\n  }\n\n  importScript(url: URL | string): Promise<void> {\n    const {signal} = this.#workerFailure;\n    if (signal.aborted) return Promise.reject(signal.reason);\n\n    const worker = this.#worker;\n    if (worker == null) return Promise.reject(new WorkerDestroyedError());\n\n    url = toUrlString(url);\n    worker.postMessage({type: Configure, importModule: url});\n    return waitForMessageOfType(\n      worker,\n      ImportedModule,\n      this.timeouts.configureTimeout,\n      (data: ImportedModuleEvent) => {\n        if (data.url !== url) return false;\n        if (data.error) throw new WorkerReportedError(data.errorName, data.error);\n        return true;\n      },\n      signal,\n    );\n  }\n\n  destroy(): void {\n    // the teardown counts even when there is no worker to tear down: everything that comes\n    // afterwards has to meet an environment that is gone\n    this.#isDestroyed = true;\n\n    // releasing the reference here is what makes the teardown idempotent: a repeated call finds\n    // nothing left, sends no second Destroy and terminates nothing twice\n    const worker = this.#worker;\n    this.#worker = undefined;\n\n    // settles everything still waiting for a reply: a start() in the middle of its load handshake\n    // would otherwise sit out its load timeout, and workerLoaded would never hear anything again\n    this.#workerFailure.abort(new WorkerDestroyedError());\n\n    if (worker == null) return;\n\n    this.stopListeningTo(worker);\n\n    worker.postMessage({type: Destroy});\n\n    waitForMessageOfType(worker, Destroyed, this.timeouts.destroyTimeout)\n      .catch((error) => {\n        // `.finally()` passes a rejection on, so without this the silence of a worker ends as an\n        // unhandled rejection once the destroy timeout is up. It is terminated either way, and\n        // by then there is nobody left to hand the error to\n        this.logger.warn('the worker did not acknowledge the teardown', error);\n      })\n      .finally(() => {\n        worker.terminate();\n      });\n  }\n\n  private readonly onWorkerError = (event: ErrorEvent): void => {\n    this.handleWorkerFailure('error', event, event.message || 'the worker reported an error');\n  };\n\n  private readonly onWorkerMessageError = (event: MessageEvent): void => {\n    this.handleWorkerFailure('messageerror', event, 'the worker sent a message that could not be deserialized');\n  };\n\n  private handleWorkerFailure(type: 'error' | 'messageerror', event: ErrorEvent | MessageEvent, message: string): void {\n    // a deliberate teardown, or a failure that was already reported: the first one wins\n    if (this.#isDestroyed) return;\n\n    this.#isDestroyed = true;\n\n    const reason = new WorkerFailedError(type, message, {\n      cause: type === 'error' ? ((event as ErrorEvent).error ?? event) : event,\n    });\n\n    this.logger.error(message, event);\n\n    const worker = this.#worker;\n    this.#worker = undefined;\n\n    if (worker != null) this.stopListeningTo(worker);\n\n    // settle everyone waiting for a reply before the worker goes away \u2014 it can no longer arrive\n    this.#workerFailure.abort(reason);\n\n    worker?.terminate();\n\n    // the ShadowEnv is told first, so that the state it derives from this is already\n    // settled when consumers hear about it. Whatever happens down that path stays\n    // there \u2014 the public event is announced either way\n    try {\n      (this as IShadowObjectEnvProxy).onProxyFailed?.(reason);\n    } catch (error) {\n      this.logger.error('the proxy-failed callback threw', error);\n    }\n\n    this.announceFailure({env: this, type, message, reason, event});\n  }\n\n  /**\n   * Announces the completed handshake to the consumers.\n   *\n   * `emitStrict()` rather than `emit()`, and the retain policy is what decides it. `workerLoaded`\n   * reads the retained value, and eventize writes that value only once the dispatch has run\n   * through: under the plain dispatch a single listener that throws would take the replay for\n   * every later subscriber with it, and every later read of `workerLoaded` would wait for a\n   * failure or a teardown instead of resolving. The guarded dispatch serves every listener and\n   * writes the retained value, because the event was delivered.\n   *\n   * What the listeners threw arrives here afterwards -- one of them unchanged, several as an\n   * `AggregateError` in dispatch order -- and is reported. It goes no further: this runs from a\n   * microtask, where a throw has no caller left to reach and would surface as an unhandled error.\n   */\n  private announceLoaded(): void {\n    try {\n      emitStrict(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerLoaded, this);\n    } catch (error) {\n      this.logger.error('a workerLoaded listener threw', error);\n    }\n  }\n\n  /**\n   * Announces the failure to the consumers. The same guarded dispatch as\n   * {@link RemoteWorkerEnv.announceLoaded}, for the same reason: `WorkerFailed` is documented as\n   * retained, and a consumer that subscribes only after the failure has to be able to hear about\n   * it. Every listener is served, the retained value is written, and whatever was thrown is\n   * reported here and reaches no caller.\n   */\n  private announceFailure(payload: WorkerFailedEvent): void {\n    try {\n      emitStrict(this as RemoteWorkerEnv, RemoteWorkerEnv.WorkerFailed, payload);\n    } catch (error) {\n      this.logger.error('a workerFailed listener threw', error);\n    }\n  }\n\n  private readonly onMessageFromWorker = (event: MessageEvent): void => {\n    if (event.data?.type === MessageToView) {\n      (this as IShadowObjectEnvProxy).onMessageToView?.(event.data.data);\n    } else {\n      this.logger.debug('message from worker', event);\n    }\n  };\n\n  /**\n   * Takes every listener of this environment off a worker. Whoever registered them takes them\n   * off again -- between the teardown and the `terminate()` that ends it the worker stays\n   * alive, and through its listeners it keeps this environment and everything it references\n   * reachable for exactly that long.\n   */\n  private stopListeningTo(worker: Worker): void {\n    worker.removeEventListener('error', this.onWorkerError);\n    worker.removeEventListener('messageerror', this.onWorkerMessageError);\n    worker.removeEventListener('message', this.onMessageFromWorker);\n  }\n\n  private configureConsoleLogger(worker: Worker) {\n    const configKey = ['RemoteWorkerEnv', 'workerConfig'];\n    const storageKey = consoleLoggerConfigKey(configKey);\n    const workerConfig = this.readWorkerConfig(configKey, storageKey);\n\n    this.logger.info('load console-logger worker config', {storageKey, workerConfig});\n\n    worker.postMessage({\n      type: CONSOLE_LOGGER,\n      config: {\n        ...ConsoleLogger.sharedConfig,\n        enable: this.logger.isEnabled,\n        ...workerConfig,\n        ...(ConsoleLogger.isEnabled ? {} : {enable: false}),\n      },\n    });\n  }\n\n  /**\n   * The console-logger config for the worker, read from the storage key this environment\n   * announces. The key is a diagnostic switch, set by hand and sharing its namespace with\n   * everything else on this origin, so its content decides nothing about whether the worker\n   * comes up: anything that is not a plain JSON object counts as no config at all, exactly\n   * like an absent key.\n   */\n  private readWorkerConfig(configKey: string[], storageKey: string): Record<string, unknown> {\n    const stored = loadConsoleLoggerConfig(configKey, '{}');\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(stored);\n    } catch (error) {\n      // error, not warn: whoever writes this key wants the worker to talk, and a silent\n      // fallback would send them looking for the reason inside the worker\n      this.logger.error(`ignoring the unreadable console-logger worker config at \"${storageKey}\"`, stored, error);\n      return {};\n    }\n\n    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n      this.logger.error(`ignoring the console-logger worker config at \"${storageKey}\": expected a JSON object`, stored);\n      return {};\n    }\n\n    return parsed as Record<string, unknown>;\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/src/view/ShadowEnv.d.ts

@@ -15,11 +15,19 @@ export declare class ShadowEnvDestroyedError extends Error {
 export declare class ShadowEnv {
     #private;
     static AfterSync: string;
+    static SyncFailed: string;
     static ContextLost: string;
     static ContextCreated: string;
     static ProxyFailed: string;
     static get(ns: NamespaceType): ShadowEnv | undefined;
-    readonly logger: ConsoleLogger;
+    /** The logger this environment reports through. */
+    get logger(): ConsoleLogger;
+    /**
+     * 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`.
+     */
     readonly ns$: import("@spearwolf/signalize").Signal<NamespaceType | undefined>;
     accessor viewReady: boolean;
     accessor proxyReady: boolean;
@@ -36,11 +44,50 @@ export declare class ShadowEnv {
      * @throws {ShadowEnvDestroyedError} if the environment is destroyed before that happens
      */
     readonly ready: () => Promise<ShadowEnv>;
+    /**
+     * 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(): void;
     /**
      * 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(): Promise<ChangeTrailType>;
     /**

package/src/view/ShadowEnv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadowEnv.d.ts","sourceRoot":"","sources":["../../../src/view/ShadowEnv.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,eAAe,EAAE,aAAa,EAAC,MAAM,aAAa,CAAC;AAChE,OAAO,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAC,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAEtE,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,SAA8C;CAIlE;AAED,qBAAa,SAAS;;IACpB,MAAM,CAAC,SAAS,SAAe;IAC/B,MAAM,CAAC,WAAW,SAAiB;IACnC,MAAM,CAAC,cAAc,SAAoB;IACzC,MAAM,CAAC,WAAW,SAAiB;IAEnC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS;IAYpD,QAAQ,CAAC,MAAM,gBAAkC;IAEjD,QAAQ,CAAC,GAAG,mEAA6C;IAE/C,QAAQ,CAAC,SAAS,UAAS;IAC3B,QAAQ,CAAC,UAAU,UAAS;IAItC,IAAI,WAAW,YAEd;;IA2BD,IAAI,IAAI,IAAI,gBAAgB,GAAG,SAAS,CAEvC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAwBhD;IAED,IAAI,QAAQ,IAAI,qBAAqB,GAAG,SAAS,CAEhD;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,EA0B3D;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAuBD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,QAAa,OAAO,CAAC,SAAS,CAAC,CAI3C;IAEF,IAAI,IAAI,IAAI;IAWZ;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC;IAyBpC;;;;;OAKG;IACH,OAAO;CAwFR"}
+{"version":3,"file":"ShadowEnv.d.ts","sourceRoot":"","sources":["../../../src/view/ShadowEnv.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,eAAe,EAAE,aAAa,EAAC,MAAM,aAAa,CAAC;AAChE,OAAO,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAC,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAEtE,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAO,SAA8C,EAGhE;CACF;AAcD,qBAAa,SAAS;;IACpB,MAAM,CAAC,SAAS,SAAe;IAC/B,MAAM,CAAC,UAAU,SAAgB;IACjC,MAAM,CAAC,WAAW,SAAiB;IACnC,MAAM,CAAC,cAAc,SAAoB;IACzC,MAAM,CAAC,WAAW,SAAiB;IAEnC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS,CAGnD;IAWD,mDAAmD;IACnD,IAAI,MAAM,IAAI,aAAa,CAE1B;IAED;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,mEAA6C;IAE/C,QAAQ,CAAC,SAAS,UAAS;IAC3B,QAAQ,CAAC,UAAU,UAAS;IAItC,IAAI,WAAW,YAEd;IAED,cAWC;IAoDD,IAAI,IAAI,IAAI,gBAAgB,GAAG,SAAS,CAEvC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EA0BhD;IAkBD,IAAI,QAAQ,IAAI,qBAAqB,GAAG,SAAS,CAEhD;IAMD,IAAI,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,EA+C3D;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAuBD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,QAAa,OAAO,CAAC,SAAS,CAAC,CAI3C;IAEF;;;;;;;;;;;;;;OAcG;IACH,IAAI,IAAI,IAAI,CASX;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC,CAanC;IAwBD;;;;;OAKG;IACH,OAAO,SAgCN;CA2JF"}