@uxland/primary-shell 7.45.17 → 7.46.1

package/dist/primary/shell/src/api/broker/primaria-broker.d.ts

@@ -2,6 +2,8 @@ import { HarmonixBroker } from '@uxland/harmonix';
 import { BrokerEvents } from './broker-events';
 export interface PrimariaBroker extends HarmonixBroker {
     events: BrokerEvents;
+    /** Internal: removes every registration (shell teardown only). */
+    _clear(): void;
 }
 export type { HarmonixBroker, IEvent, IEventClass, IRequest, IRequestClass, } from '@uxland/harmonix';
 export type { BrokerDisposableHandler } from '@uxland/harmonix';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxland/primary-shell",
-  "version": "7.45.17",
+  "version": "7.46.1",
   "description": "Primaria Shell",
   "author": "UXLand <dev@uxland.es>",
   "homepage": "https://github.com/uxland/harmonix/tree/app#readme",
@@ -42,7 +42,6 @@
     "inversify-inject-decorators": "^3.1.0",
     "jwt-decode": "^4.0.0",
     "lit": "^3.1.0",
-    "mediatr-ts": "^1.2.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "reflect-metadata": "^0.2.2",

package/src/api/broker/factory.test.ts

@@ -126,4 +126,248 @@ describe("Broker test", () => {
       });
     });
   });
+
+  describe("Disposal and re-registration", () => {
+    class MyRequest implements IRequest<string> {
+      constructor(public greeting: string) {}
+    }
+
+    it("disposing a request handler lets the same request be registered again (teardown + bootstrap)", () => {
+      const disposable = sut.registerRequest(MyRequest, () => "first");
+      disposable.dispose();
+      // Re-registering after dispose must NOT throw (the dispose-bug regression).
+      expect(() => sut.registerRequest(MyRequest, () => "second")).not.toThrow();
+    });
+
+    it("routes to the handler registered after a dispose/re-register cycle", async () => {
+      const first = vi.fn().mockResolvedValue("first");
+      const second = vi.fn().mockResolvedValue("second");
+      const disposable = sut.registerRequest(MyRequest, first);
+      disposable.dispose();
+      sut.registerRequest(MyRequest, second);
+
+      const result = await sut.send(new MyRequest("hi"));
+
+      expect(result).toBe("second");
+      expect(first).not.toHaveBeenCalled();
+      expect(second).toHaveBeenCalledWith({ greeting: "hi" });
+    });
+
+    it("sending a request with no handler registered throws", async () => {
+      await expect(sut.send(new MyRequest("hi"))).rejects.toThrow();
+    });
+
+    it("sending after the only handler was disposed throws", async () => {
+      const disposable = sut.registerRequest(MyRequest, () => "x");
+      disposable.dispose();
+      await expect(sut.send(new MyRequest("hi"))).rejects.toThrow();
+    });
+
+    it("a stale disposer does not drop a newer registration for the same request", async () => {
+      const first = vi.fn().mockResolvedValue("first");
+      const second = vi.fn().mockResolvedValue("second");
+      const firstDisposable = sut.registerRequest(MyRequest, first);
+      firstDisposable.dispose();
+      sut.registerRequest(MyRequest, second);
+      // Disposing the already-disposed first handler must not remove `second`.
+      firstDisposable.dispose();
+
+      const result = await sut.send(new MyRequest("hi"));
+      expect(result).toBe("second");
+    });
+  });
+
+  describe("Event subscription disposal", () => {
+    class MyEvent implements IEvent {
+      constructor(public greeting: string) {}
+    }
+
+    it("a disposed subscriber stops receiving events while the rest keep receiving them", async () => {
+      const kept = vi.fn();
+      const removed = vi.fn();
+      sut.subscribe(MyEvent, kept);
+      const disposable = sut.subscribe(MyEvent, removed);
+
+      disposable.dispose();
+      await sut.publish(new MyEvent("Hello"));
+
+      expect(kept).toHaveBeenCalledWith({ greeting: "Hello" });
+      expect(removed).not.toHaveBeenCalled();
+    });
+
+    it("publishing an event instance with no subscribers does not throw", () => {
+      expect(() => sut.publish(new MyEvent("Hello"))).not.toThrow();
+    });
+
+    it("the same handler can re-subscribe after disposing", async () => {
+      const handler = vi.fn();
+      const disposable = sut.subscribe("MyEvent", handler);
+      disposable.dispose();
+      sut.subscribe("MyEvent", handler);
+
+      await sut.publish("MyEvent", { greeting: "Hello" });
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler).toHaveBeenCalledWith({ greeting: "Hello" });
+    });
+  });
+
+  describe("_clear", () => {
+    class MyRequest implements IRequest<string> {}
+
+    it("removes all registrations so the registry can be reused cleanly", () => {
+      sut.registerRequest(MyRequest, () => "x");
+      sut._clear();
+      // After a clear, registering the same request again must not throw.
+      expect(() => sut.registerRequest(MyRequest, () => "y")).not.toThrow();
+    });
+  });
+
+  describe("Request handler semantics", () => {
+    class MyRequest implements IRequest<string> {
+      constructor(public greeting: string) {}
+    }
+
+    it("rejects when the handler throws synchronously", async () => {
+      sut.registerRequest(MyRequest, () => {
+        throw new Error("boom");
+      });
+      await expect(sut.send(new MyRequest("x"))).rejects.toThrow("boom");
+    });
+
+    it("rejects when the handler returns a rejected promise", async () => {
+      sut.registerRequest(MyRequest, async () => {
+        throw new Error("async boom");
+      });
+      await expect(sut.send(new MyRequest("x"))).rejects.toThrow("async boom");
+    });
+
+    it("resolves a synchronous (non-promise) handler return value", async () => {
+      sut.registerRequest(MyRequest, () => "sync-value");
+      await expect(sut.send(new MyRequest("x"))).resolves.toBe("sync-value");
+    });
+  });
+
+  describe("Publish semantics", () => {
+    it("resolves only after async subscribers have completed", async () => {
+      let completed = false;
+      sut.subscribe("evt", async () => {
+        await Promise.resolve();
+        completed = true;
+      });
+      await sut.publish("evt", {});
+      expect(completed).toBe(true);
+    });
+
+    it("isolates a throwing subscriber: the others are still notified and publish does not reject", async () => {
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      const before = vi.fn();
+      const after = vi.fn();
+      sut.subscribe("evt", before);
+      sut.subscribe("evt", () => {
+        throw new Error("bad subscriber");
+      });
+      sut.subscribe("evt", () => Promise.reject(new Error("bad async subscriber")));
+      sut.subscribe("evt", after);
+
+      await expect(sut.publish("evt", { a: 1 })).resolves.toBeUndefined();
+
+      expect(before).toHaveBeenCalledWith({ a: 1 });
+      expect(after).toHaveBeenCalledWith({ a: 1 });
+      expect(errorSpy).toHaveBeenCalledTimes(2);
+      errorSpy.mockRestore();
+    });
+
+    it("a subscriber added during dispatch is not invoked in the same round (snapshot)", async () => {
+      const added = vi.fn();
+      const adder = vi.fn(() => {
+        sut.subscribe("evt", added);
+      });
+      sut.subscribe("evt", adder);
+
+      await sut.publish("evt", {});
+      expect(adder).toHaveBeenCalledTimes(1);
+      expect(added).not.toHaveBeenCalled();
+
+      await sut.publish("evt", {});
+      expect(added).toHaveBeenCalledTimes(1);
+    });
+
+    it("a subscriber that disposes itself during dispatch is still called that round but not the next", async () => {
+      let disposable: ReturnType<typeof sut.subscribe>;
+      const handler = vi.fn(() => disposable.dispose());
+      disposable = sut.subscribe("evt", handler);
+
+      await sut.publish("evt", {});
+      await sut.publish("evt", {});
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("Namespace isolation", () => {
+    it("event class keys and event string keys are independent", async () => {
+      class Evt implements IEvent {}
+      const classHandler = vi.fn();
+      const stringHandler = vi.fn();
+      sut.subscribe(Evt, classHandler);
+      sut.subscribe("Evt", stringHandler);
+
+      await sut.publish(new Evt());
+      expect(classHandler).toHaveBeenCalledTimes(1);
+      expect(stringHandler).not.toHaveBeenCalled();
+
+      await sut.publish("Evt", {});
+      expect(stringHandler).toHaveBeenCalledTimes(1);
+      expect(classHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it("the request registry and the event registry do not collide for the same name", async () => {
+      const requestHandler = vi.fn().mockResolvedValue("r");
+      const eventHandler = vi.fn();
+      sut.registerRequest("Shared", requestHandler);
+      sut.subscribe("Shared", eventHandler);
+
+      await sut.send("Shared", { v: 1 });
+      expect(requestHandler).toHaveBeenCalledWith({ v: 1 });
+      expect(eventHandler).not.toHaveBeenCalled();
+
+      await sut.publish("Shared", { v: 2 });
+      expect(eventHandler).toHaveBeenCalledWith({ v: 2 });
+      expect(requestHandler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("Constructor-identity keying", () => {
+    it("keys requests by constructor identity, not by class name (two same-named classes coexist)", async () => {
+      const makeDup = () => class Dup implements IRequest<string> {};
+      const A = makeDup();
+      const B = makeDup();
+      expect(A.name).toBe(B.name); // both named "Dup"
+
+      const handlerA = vi.fn().mockResolvedValue("A");
+      const handlerB = vi.fn().mockResolvedValue("B");
+      sut.registerRequest(A, handlerA);
+      // The old name-based registry would have thrown here; identity keying must not.
+      expect(() => sut.registerRequest(B, handlerB)).not.toThrow();
+
+      await expect(sut.send(new A())).resolves.toBe("A");
+      await expect(sut.send(new B())).resolves.toBe("B");
+    });
+  });
+
+  describe("Idempotent disposal", () => {
+    class MyRequest implements IRequest<string> {}
+
+    it("disposing a request handler twice is safe", () => {
+      const disposable = sut.registerRequest(MyRequest, () => "x");
+      disposable.dispose();
+      expect(() => disposable.dispose()).not.toThrow();
+    });
+
+    it("disposing an event subscription twice is safe", () => {
+      const disposable = sut.subscribe("evt", () => {});
+      disposable.dispose();
+      expect(() => disposable.dispose()).not.toThrow();
+    });
+  });
 });

package/src/api/broker/factory.ts

@@ -1,170 +1,138 @@
 import { IEvent, IEventClass, IRequest, IRequestClass } from "@uxland/harmonix";
-import { Mediator, mediatorSettings, notificationHandler, requestHandler } from "mediatr-ts";
 import { BROKER_EVENTS } from "./broker-events";
-import { type PrimariaBroker, type BrokerDisposableHandler } from "./primaria-broker";
+import type { BrokerDisposableHandler, PrimariaBroker } from "./primaria-broker";
+
+/**
+ * In-process message broker.
+ *
+ * The whole plugin system runs in a single JS heap (plugins are ES modules,
+ * no postMessage / workers / serialization), so dispatch is a plain map lookup.
+ *
+ * A message is keyed either by its **class constructor** (typed, intra-plugin
+ * requests/events) or by a **string name** (decoupled, cross-plugin events).
+ * Both live in the same map: `send(new Foo())` keys on `instance.constructor`,
+ * which is the very class passed to `registerRequest(Foo, …)`, so identity
+ * matches without any reflection or dynamically generated classes.
+ *
+ * - Requests (request/response): exactly one handler per key.
+ * - Events (publish/subscribe): any number of subscribers per key.
+ *
+ * Handlers receive a shallow copy of the message data (`{ ...instance }` for a
+ * class, or the raw payload for the string API), matching the previous
+ * behaviour exactly.
+ */
+
+// biome-ignore lint/complexity/noBannedTypes: a class constructor is a Function, used here as a map key
+type MessageKey = Function | string;
+
+// biome-ignore lint/suspicious/noExplicitAny: handlers are typed at the public-interface boundary
+type Handler = (message: any) => unknown;
 
-type messageHandler = (payload: unknown) => unknown | Promise<unknown>;
-
-const disposableFactory = (handler: any) => {
-  return {
-    dispose: () => {
-      mediatorSettings.resolver.remove(handler.name);
-      const mappingIndex = mediatorSettings.dispatcher.notifications._mappings.findIndex(
-        (mapping) => mapping.handler.name === handler.name,
-      );
-      mappingIndex > -1 &&
-        mediatorSettings.dispatcher.notifications._mappings.splice(mappingIndex, 1);
-    },
-  };
-};
 class Broker implements PrimariaBroker {
   public readonly events = BROKER_EVENTS;
-  private mediator: Mediator;
-  constructor() {
-    this.mediator = new Mediator();
-    mediatorSettings.resolver.clear();
-  }
-  // biome-ignore lint/complexity/noBannedTypes: <explanation>
-  private eventConstructorMap: Map<string, Function> = new Map();
 
-  // biome-ignore lint/complexity/noBannedTypes: <explanation>
-  private requestConstructorMap: Map<string, Function> = new Map();
+  /** One handler per request type (request/response). */
+  private readonly requestHandlers = new Map<MessageKey, Handler>();
+
+  /** Many subscribers per event type (publish/subscribe). */
+  private readonly eventSubscribers = new Map<MessageKey, Set<Handler>>();
+
+  // ---- Request / response ---------------------------------------------------
 
   send<TRequest extends IRequest<TResponse>, TResponse>(message: TRequest): Promise<TResponse>;
   send<TPayload, TResponse>(requestName: string, payload: TPayload): Promise<TResponse>;
-  send<TResponse>(request: IRequest<TResponse> | string, payload?: unknown): Promise<TResponse> {
-    const eventPayload =
-      typeof request === "string"
-        ? this.getRequest<TResponse>(request as string, payload)
-        : request;
-    return this.mediator.send(eventPayload);
-  }
-  publish<TEvent extends IEvent>(event: TEvent): Promise<void>;
-  publish<TPayload>(eventName: string, payload: TPayload): Promise<void>;
-  publish(event: string | IEvent, payload?: unknown): Promise<void> {
-    const eventPayload =
-      typeof event === "string" ? this.getEvent(event as string, payload) : event;
-    const classConstructor =
-      eventPayload.constructor || Object.getPrototypeOf(eventPayload).constructor;
-    const handlerSubscriptions = mediatorSettings.dispatcher.notifications._mappings.filter(
-      (m) => m.notification === classConstructor,
-    );
-    if (!handlerSubscriptions.length) return Promise.resolve();
-    return this.mediator.publish(eventPayload);
-  }
-  subscribe<TEvent extends IEvent>(
-    event: TEvent,
-    handler: (message: TEvent) => void,
-  ): BrokerDisposableHandler;
-  subscribe<TPayload>(
-    eventName: string,
-    handler: (message: TPayload) => void,
-  ): BrokerDisposableHandler;
-  subscribe(event: string | IEventClass, handler: messageHandler): BrokerDisposableHandler {
-    const eventType = typeof event === "function" ? event : this.getEventType(event as string);
-    const wrappedHandler = createDynamicEventHandler(handler);
-    notificationHandler(eventType)(wrappedHandler);
-    return disposableFactory(wrappedHandler);
+  async send<TResponse>(request: IRequest<TResponse> | string, payload?: unknown): Promise<TResponse> {
+    const key: MessageKey = typeof request === "string" ? request : request.constructor;
+    const handler = this.requestHandlers.get(key);
+    if (!handler) {
+      const name = typeof request === "string" ? request : request.constructor?.name;
+      throw new Error(`Broker: no request handler registered for "${name}".`);
+    }
+    const message = typeof request === "string" ? { ...(payload as object) } : { ...request };
+    return (await handler(message)) as TResponse;
   }
+
   registerRequest<TRequest extends IRequest<TResponse>, TResponse>(
-    request: TRequest,
-    handler: (message: TRequest) => TResponse,
+    request: IRequestClass<TRequest>,
+    handler: (message: TRequest) => TResponse | Promise<TResponse>,
   ): BrokerDisposableHandler;
   registerRequest<TPayload, TResponse>(
     requestName: string,
-    handler: (message: TPayload) => TResponse,
+    handler: (message: TPayload) => TResponse | Promise<TResponse>,
   ): BrokerDisposableHandler;
-  registerRequest(
-    request: string | IRequestClass<unknown>,
-    handler: messageHandler,
-  ): BrokerDisposableHandler {
-    const requestType =
-      typeof request === "function" ? request : this.getRequestType(request as string);
-    const wrappedHandler = createDynamicRequestHandler(handler);
-    requestHandler(requestType)(wrappedHandler);
-    return disposableFactory(wrappedHandler);
-  }
-
-  private getEvent(eventName: string, payload: unknown): IEvent {
-    const eventConstructor = this.getEventType(eventName);
-    return new eventConstructor(payload) as IEvent;
+  registerRequest(request: IRequestClass<unknown> | string, handler: Handler): BrokerDisposableHandler {
+    if (this.requestHandlers.has(request)) {
+      const name = typeof request === "string" ? request : request.name;
+      throw new Error(`Broker: a request handler is already registered for "${name}".`);
+    }
+    this.requestHandlers.set(request, handler);
+    return {
+      dispose: () => {
+        // Identity-guarded: a stale/duplicate dispose must not drop a handler
+        // registered later under the same key (after a teardown + bootstrap).
+        if (this.requestHandlers.get(request) === handler) {
+          this.requestHandlers.delete(request);
+        }
+      },
+    };
   }
 
-  private getRequest<TResponse>(requestName: string, payload: unknown): IRequest<TResponse> {
-    const requestConstructor = this.getRequestType(requestName);
-    return new requestConstructor(payload) as IRequest<unknown>;
-  }
+  // ---- Publish / subscribe --------------------------------------------------
 
-  private getEventType(eventName: string): IEventClass {
-    if (!this.eventConstructorMap.has(eventName)) {
-      const clazz = createDynamicEventClass(eventName);
-      this.eventConstructorMap.set(eventName, clazz);
-    }
-    return this.eventConstructorMap.get(eventName) as IEventClass;
+  publish<TEvent extends IEvent>(event: TEvent): Promise<void>;
+  publish<TPayload>(eventName: string, payload: TPayload): Promise<void>;
+  async publish(event: IEvent | string, payload?: unknown): Promise<void> {
+    const key: MessageKey = typeof event === "string" ? event : event.constructor;
+    const subscribers = this.eventSubscribers.get(key);
+    if (!subscribers || subscribers.size === 0) return;
+    const message = typeof event === "string" ? payload : { ...event };
+    const name = typeof event === "string" ? event : event.constructor?.name;
+    // Snapshot the set: a subscriber may subscribe/dispose while we iterate.
+    // Each subscriber is isolated: a throwing/rejecting subscriber is logged but
+    // never blocks the others nor rejects publish() (fire-and-forget event bus).
+    await Promise.all(
+      [...subscribers].map(async (handler) => {
+        try {
+          await handler(message);
+        } catch (error) {
+          console.error(`Broker: a subscriber for event "${name}" threw and was isolated.`, error);
+        }
+      }),
+    );
   }
 
-  private getRequestType(requestName: string): IRequestClass<unknown> {
-    if (!this.requestConstructorMap.has(requestName)) {
-      const clazz = createDynamicRequestClass(requestName);
-      this.requestConstructorMap.set(requestName, clazz);
+  subscribe<TEvent extends IEvent>(
+    event: IEventClass,
+    handler: (message: TEvent) => void | Promise<void>,
+  ): BrokerDisposableHandler;
+  subscribe<TPayload>(eventName: string, handler: (message: TPayload) => void | Promise<void>): BrokerDisposableHandler;
+  subscribe(event: IEventClass | string, handler: Handler): BrokerDisposableHandler {
+    let subscribers = this.eventSubscribers.get(event);
+    if (!subscribers) {
+      subscribers = new Set();
+      this.eventSubscribers.set(event, subscribers);
     }
-    return this.requestConstructorMap.get(requestName) as IRequestClass<unknown>;
+    subscribers.add(handler);
+    return {
+      dispose: () => {
+        const current = this.eventSubscribers.get(event);
+        if (!current) return;
+        current.delete(handler);
+        if (current.size === 0) this.eventSubscribers.delete(event);
+      },
+    };
   }
-}
-
-const createDynamicEventClass = (eventName: string) => {
-  return new Function(`return class Event_${eventName} {
-    constructor(payload) {
-            this.payload = payload;
-        }
-    }`)();
-};
-
-const createDynamicRequestClass = (requestName: string) => {
-  return new Function(`return class Request_${requestName} {
-    constructor(payload) {
-            Object.assign(this, payload);
-        }
-    }`)();
-};
 
-const usedSuffixes = new Set();
+  // ---- Lifecycle ------------------------------------------------------------
 
-function generateUniqueRandomSuffix() {
-  let suffix;
-  do {
-    suffix = Math.floor(Math.random() * 10000);
-  } while (usedSuffixes.has(suffix));
-
-  usedSuffixes.add(suffix);
-  return suffix;
+  /**
+   * Removes every registration. Used on shell teardown so a re-initialization
+   * starts from a clean registry (the broker is a module-level singleton).
+   */
+  _clear(): void {
+    this.requestHandlers.clear();
+    this.eventSubscribers.clear();
+  }
 }
 
-const createDynamicRequestHandler = (handler: messageHandler) => {
-  const className = `RequestHandler_${generateUniqueRandomSuffix()}`;
-  return new Function(
-    "handler",
-    `return class ${className}{
-        handle(notification){
-            const handlerResult = handler({...notification});
-            return handlerResult instanceof Promise ? handlerResult : Promise.resolve(handlerResult);
-        }
-    }`,
-  )(handler);
-};
-
-const createDynamicEventHandler = (handler: messageHandler) => {
-  const className = `EventHandler_${generateUniqueRandomSuffix()}`;
-  return new Function(
-    "handler",
-    `return class ${className}{
-        handle(notification){
-            const payload = notification.payload !== undefined ? notification.payload : {...notification};
-            const handlerResult = handler(payload);
-            return handlerResult instanceof Promise ? handlerResult : Promise.resolve(handlerResult);
-        }
-    }`,
-  )(handler);
-};
-
-export const createBroker = (): PrimariaBroker => new Broker(); 
+export const createBroker = (): PrimariaBroker => new Broker();

package/src/api/broker/primaria-broker.ts

@@ -3,6 +3,8 @@ import { type BrokerEvents } from "./broker-events";
 
 export interface PrimariaBroker extends HarmonixBroker {
   events: BrokerEvents;
+  /** Internal: removes every registration (shell teardown only). */
+  _clear(): void;
 }
 
 export type {

package/src/features/bootstrapper.ts

@@ -1,4 +1,3 @@
-import { mediatorSettings } from "mediatr-ts";
 import { PrimariaApi } from "../api/api";
 import { container } from "../infrastructure/ioc/container";
 import { TYPES } from "../infrastructure/ioc/types";
@@ -18,5 +17,5 @@ export const disposeFeatures = (api: PrimariaApi) => {
   disposeExitShell();
   container.unbindAll();
   api.regionManager._destroy();
-  mediatorSettings.resolver.clear();
+  api.broker._clear();
 };

package/src/handle-plugins.ts

@@ -22,20 +22,41 @@ interface PrimariaBootstrappedPlugin extends BootstrappedPlugin<PrimariaApi> {
   importedPlugin: PrimariaPlugin;
 }
 
-const internalPlugins: PluginDefinition[] = [
-  {
-    pluginId: "activity-history",
-    importer: () =>
-      Promise.resolve({
-        initialize: activityHistoryInitialize,
-        dispose: activityHistoryDispose,
-      }),
-  },
-];
+const CORE_FIRST_ID = "activity-history";
+
+// activity-history must finish initializing before any other plugin: it
+// registers the broker requests the rest depend on. In production it is loaded
+// from the plugin store (versioned/uploadable) like any other plugin; this
+// bundled copy is the fallback used when the caller does not provide it — e.g.
+// third-party sandboxes that install primary-shell without a plugin store.
+const bundledActivityHistory: PluginDefinition = {
+  pluginId: CORE_FIRST_ID,
+  importer: () =>
+    Promise.resolve({
+      initialize: activityHistoryInitialize,
+      dispose: activityHistoryDispose,
+    }),
+};
 
 export const bootstrapPlugins = async (plugins: PluginDefinition[], startup?: PrimariaStartupPlugin) => {
-  const finalPlugins = internalPlugins.concat(plugins || []);
-  bootstrappedPlugins = (await pluginBootstrapper(finalPlugins, primariaApiFactory)) as BootstrappedPlugin<PrimariaApi>[];
+  const incoming = plugins ?? [];
+  const provided = incoming.filter((plugin) => plugin.pluginId === CORE_FIRST_ID);
+  const rest = incoming.filter((plugin) => plugin.pluginId !== CORE_FIRST_ID);
+
+  // Prefer the store/sandbox-provided activity-history; fall back to the bundled
+  // copy. Either way it is bootstrapped — and fully initialized — before the
+  // rest, which run in parallel as before.
+  const corePlugins = provided.length ? provided : [bundledActivityHistory];
+
+  const coreBootstrapped = (await pluginBootstrapper(
+    corePlugins,
+    primariaApiFactory,
+  )) as BootstrappedPlugin<PrimariaApi>[];
+  const restBootstrapped = rest.length
+    ? ((await pluginBootstrapper(rest, primariaApiFactory)) as BootstrappedPlugin<PrimariaApi>[])
+    : [];
+
+  bootstrappedPlugins = [...coreBootstrapped, ...restBootstrapped];
   handleStartupPlugin(bootstrappedPlugins as PrimariaBootstrappedPlugin[], startup);
 };