@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/view/RemoteWorkerEnv.d.ts

@@ -1,3 +1,4 @@
+import type { InspectRequest, KernelSnapshot } from '../inspect/types.js';
 import type { ChangeTrailType } from '../types.js';
 import { ConsoleLogger } from '../utils/ConsoleLogger.js';
 import type { IShadowObjectEnvProxy } from './IShadowObjectEnvProxy.js';
@@ -17,6 +18,45 @@ export declare class WorkerFailedError extends Error {
 export declare class WorkerDestroyedError extends Error {
     constructor(message?: string);
 }
+/**
+ * The reason a request is rejected with when the worker reported a failure of its own -- a
+ * module that would not import, a change trail its Kernel refused. An error does not survive
+ * structured cloning as the object it is, so the two fields that do are rebuilt here, and
+ * `name` is the name the error called itself inside the worker: a caller reads it the same
+ * way it reads the name of an error a `LocalShadowObjectEnv` hands it. A name that is missing
+ * or empty names no class, and `Error` is what such a reason is called -- the same name a
+ * plain `new Error(message)` carries on the local side.
+ *
+ * What does not come across is the class and everything it added. `instanceof EntityUuidInUseError`
+ * is `false` here and there is no `uuid` field, whatever `name` says; `instanceof WorkerReportedError`
+ * is what tells such a reason apart from one raised on this side.
+ */
+export declare class WorkerReportedError extends Error {
+    constructor(name: string | undefined, message: string);
+}
+/**
+ * How long a {@link RemoteWorkerEnv} waits for each of the five replies a worker owes it,
+ * in milliseconds.
+ */
+export interface WorkerTimeouts {
+    /** the `Loaded` handshake at the start */
+    loadTimeout: number;
+    /** the `ImportedModule` reply to an `importScript()` */
+    configureTimeout: number;
+    /** the `AppliedChangeTrail` confirmation of a change trail sent with `waitForConfirmation` */
+    changeTrailTimeout: number;
+    /** the `Inspected` answer to an `inspect()` */
+    inspectTimeout: number;
+    /** the `Destroyed` acknowledgement of a teardown */
+    destroyTimeout: number;
+}
+/**
+ * What {@link RemoteWorkerEnv} takes. Every value left out keeps its default — the five
+ * `Worker*Timeout` constants. A value that is not a number of milliseconds from 1 to
+ * 2147483647 — close to 25 days, the longest delay a timer keeps — is reported through the
+ * logger and the default applies.
+ */
+export type RemoteWorkerEnvOptions = Partial<WorkerTimeouts>;
 /** What {@link RemoteWorkerEnv.WorkerFailed} carries. */
 export interface WorkerFailedEvent {
     /** the environment whose worker failed */
@@ -34,7 +74,14 @@ export declare class RemoteWorkerEnv implements IShadowObjectEnvProxy {
     #private;
     static WorkerLoaded: string;
     static WorkerFailed: string;
-    readonly logger: ConsoleLogger;
+    /** The logger this environment reports through. */
+    get logger(): ConsoleLogger;
+    /**
+     * The five 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(): Readonly<WorkerTimeouts>;
     get isDestroyed(): boolean;
     /**
      * Resolves once the worker is up.
@@ -44,17 +91,73 @@ export declare class RemoteWorkerEnv implements IShadowObjectEnvProxy {
      * `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(): Promise<RemoteWorkerEnv>;
-    constructor();
+    constructor(options?: RemoteWorkerEnvOptions);
     start(): Promise<void>;
     applyChangeTrail(changeTrail: ChangeTrailType, waitForConfirmation: boolean): Promise<void>;
     importScript(url: URL | string): Promise<void>;
+    /**
+     * Asks the worker for a snapshot of its Kernel. The request travels as an `Inspect` message
+     * under a serial of its own, and the `Inspected` answer that carries the same serial settles
+     * the call: with the snapshot, or with a `WorkerReportedError` rebuilt from the failure the
+     * worker described. An answer that stays out past `inspectTimeout` rejects with a
+     * `WorkerTimeoutError`; a worker that failed or an environment that was torn down rejects right
+     * away, before or while the answer is awaited.
+     *
+     * The caller's `signal` ends the wait with its own reason. The worker is not told: an answer
+     * that arrives afterwards carries a serial nobody waits for any more and is discarded like any
+     * other unmatched message.
+     *
+     * The message runs through the same queue as the change trails, so the snapshot reflects every
+     * trail posted before this call and none posted after it.
+     */
+    inspect(request?: InspectRequest, signal?: AbortSignal): Promise<KernelSnapshot>;
     destroy(): void;
-    private onWorkerError;
-    private onWorkerMessageError;
+    private readonly onWorkerError;
+    private readonly onWorkerMessageError;
     private handleWorkerFailure;
-    private onMessageFromWorker;
+    /**
+     * 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.
+     */
+    private announceLoaded;
+    /**
+     * 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.
+     */
+    private announceFailure;
+    private readonly onMessageFromWorker;
+    /**
+     * 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.
+     */
+    private stopListeningTo;
     private configureConsoleLogger;
+    /**
+     * 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.
+     */
+    private readWorkerConfig;
 }
 //# sourceMappingURL=RemoteWorkerEnv.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"RemoteWorkerEnv.d.ts","sourceRoot":"","sources":["../../../src/view/RemoteWorkerEnv.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAA0B,eAAe,EAAyC,MAAM,aAAa,CAAC;AAClH,OAAO,EAAiB,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAGxE,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,4BAA4B,CAAC;AAqBtE;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,sHAAsH;IACtH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;gBAE5B,IAAI,EAAE,OAAO,GAAG,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpF;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,SAA8C;CAIlE;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,GAAG,EAAE,eAAe,CAAC;IACrB,+BAA+B;IAC/B,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IAC/B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,iBAAiB,CAAC;IAC1B,iDAAiD;IACjD,KAAK,EAAE,UAAU,GAAG,YAAY,CAAC;CAClC;AAED,qBAAa,eAAgB,YAAW,qBAAqB;;IAC3D,MAAM,CAAC,YAAY,SAAkB;IACrC,MAAM,CAAC,YAAY,SAAkB;IAYrC,QAAQ,CAAC,MAAM,gBAAwC;IAEvD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;;;;OAQG;IACH,IAAI,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC,CA4B3C;;IAQK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiE5B,gBAAgB,CAAC,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC3F,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB9C,OAAO,IAAI,IAAI;IAef,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,mBAAmB;IAsC3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,sBAAsB;CAkB/B"}
+{"version":3,"file":"RemoteWorkerEnv.d.ts","sourceRoot":"","sources":["../../../src/view/RemoteWorkerEnv.ts"],"names":[],"mappings":"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"}

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,
@@ -6,32 +7,35 @@ import {
   Destroy,
   Destroyed,
   ImportedModule,
+  Inspect,
+  Inspected,
   Loaded,
   MessageToView,
   WorkerChangeTrailTimeout,
   WorkerConfigureTimeout,
   WorkerDestroyTimeout,
+  WorkerInspectTimeout,
   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 +50,61 @@ 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,
+  inspectTimeout: WorkerInspectTimeout,
+  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;
+    this.#inspectSerial = 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);
   }
@@ -68,7 +117,22 @@ class RemoteWorkerEnv {
   #worker;
   #isDestroyed;
   #changeTrailSerial;
+  #inspectSerial;
   #workerFailure;
+  #logger;
+  /** The logger this environment reports through. */
+  get logger() {
+    return this.#logger;
+  }
+  #timeouts;
+  /**
+   * The five 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 +144,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 +172,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 +181,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 +210,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 +247,72 @@ 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
     );
   }
+  /**
+   * Asks the worker for a snapshot of its Kernel. The request travels as an `Inspect` message
+   * under a serial of its own, and the `Inspected` answer that carries the same serial settles
+   * the call: with the snapshot, or with a `WorkerReportedError` rebuilt from the failure the
+   * worker described. An answer that stays out past `inspectTimeout` rejects with a
+   * `WorkerTimeoutError`; a worker that failed or an environment that was torn down rejects right
+   * away, before or while the answer is awaited.
+   *
+   * The caller's `signal` ends the wait with its own reason. The worker is not told: an answer
+   * that arrives afterwards carries a serial nobody waits for any more and is discarded like any
+   * other unmatched message.
+   *
+   * The message runs through the same queue as the change trails, so the snapshot reflects every
+   * trail posted before this call and none posted after it.
+   */
+  inspect(request = {}, signal) {
+    const { signal: failure } = this.#workerFailure;
+    if (failure.aborted) return Promise.reject(failure.reason);
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    const worker = this.#worker;
+    if (worker == null) return Promise.reject(new WorkerDestroyedError());
+    const serial = ++this.#inspectSerial;
+    const message = { type: Inspect, serial, request };
+    worker.postMessage(message);
+    let snapshot;
+    return waitForMessageOfType(
+      worker,
+      Inspected,
+      this.timeouts.inspectTimeout,
+      (data) => {
+        if (data.serial !== serial) return false;
+        if (data.error) throw new WorkerReportedError(data.errorName, data.error);
+        snapshot = data.snapshot;
+        return true;
+      },
+      signal === void 0 ? failure : AbortSignal.any([failure, signal])
+    ).then(() => {
+      if (snapshot === void 0) {
+        throw new WorkerReportedError(void 0, "the worker answered the inspection without a snapshot");
+      }
+      return snapshot;
+    });
+  }
   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 +322,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 +330,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 +393,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