every-plugin 2.10.1 → 3.0.0-rc.3

package/src/dev/watch-kill.ts

@@ -0,0 +1,58 @@
+interface KillableChild {
+  pid?: number | undefined;
+  kill: (signal?: NodeJS.Signals) => void;
+  exitCode: number | null;
+  killed: boolean;
+  addListener: (event: "exit", listener: () => void) => unknown;
+  removeListener: (event: "exit", listener: () => void) => unknown;
+}
+
+const waitForExit = (child: KillableChild, timeoutMs: number): Promise<boolean> =>
+  new Promise((resolve) => {
+    if (child.exitCode !== null) {
+      resolve(true);
+      return;
+    }
+    const onExit = () => {
+      clearTimeout(timer);
+      resolve(true);
+    };
+    const timer = setTimeout(() => {
+      child.removeListener("exit", onExit);
+      resolve(false);
+    }, timeoutMs);
+    child.addListener("exit", onExit);
+  });
+
+export const killChildEscalating = async (
+  child: KillableChild,
+  terminateMs = 2000,
+): Promise<void> => {
+  if (child.exitCode !== null || child.killed) return;
+  child.kill("SIGTERM");
+  const exited = await waitForExit(child, terminateMs);
+  if (!exited) child.kill("SIGKILL");
+};
+
+export interface WatchParentDeathOptions {
+  intervalMs?: number;
+  getPpid?: () => number;
+  onParentDeath?: () => void | Promise<void>;
+}
+
+export const watchParentDeath = (
+  onParentDeath: () => void | Promise<void>,
+  opts?: Omit<WatchParentDeathOptions, "onParentDeath">,
+): { stop: () => void } => {
+  const getPpid = opts?.getPpid ?? (() => process.ppid);
+  const intervalMs = opts?.intervalMs ?? 200;
+  const initialPpid = getPpid();
+  const timer = setInterval(() => {
+    if (getPpid() !== initialPpid) {
+      clearInterval(timer);
+      void onParentDeath();
+    }
+  }, intervalMs);
+  timer.unref?.();
+  return { stop: () => clearInterval(timer) };
+};

package/src/effect-helpers.ts

@@ -0,0 +1,25 @@
+import { Context, Effect, Layer, type Scope } from "effect";
+
+/**
+ * Builds a layer with the current scope and returns the built context.
+ *
+ * Resources are released when the plugin's scope closes. Use inside
+ * `initialize` for multi-service layers; resolve individual services from
+ * the returned context with `Context.get`.
+ */
+export const buildScopedContext = <A, E, R>(
+  layer: Layer.Layer<A, E, R>,
+): Effect.Effect<Context.Context<A>, E, Scope.Scope | R> =>
+  Effect.flatMap(Effect.scope, (scope) => Layer.buildWithScope(layer, scope));
+
+/**
+ * Builds a layer with the current scope and resolves one service from it.
+ *
+ * Equivalent to `buildScopedContext` + `Context.get` for single-service
+ * layers: `const db = yield* buildScoped(DatabaseTag, DatabaseLive(url))`.
+ */
+export const buildScoped = <Identifier, Shape, E, R>(
+  tag: Context.Service<Identifier, Shape>,
+  layer: Layer.Layer<Identifier, E, R>,
+): Effect.Effect<Shape, E, Scope.Scope | R> =>
+  buildScopedContext(layer).pipe(Effect.map((context) => Context.get(context, tag)));

package/src/errors.ts

@@ -1,18 +1,5 @@
-import { z } from "./zod";
-
-/**
- * Error pattern constants for categorizing infrastructure errors
- */
-export const ERROR_PATTERNS = {
-  CONNECTION_REFUSED: ["ECONNREFUSED"],
-  HOST_NOT_FOUND: ["ENOTFOUND", "EHOSTUNREACH"],
-  TIMEOUT: ["ETIMEDOUT", "ESOCKETTIMEDOUT", "timeout"],
-  CONNECTION_RESET: ["ECONNRESET", "EPIPE"],
-  PERMISSION: ["EACCES", "EPERM", "permission denied"],
-  AUTH: ["401", "unauthorized", "authentication failed"],
-  RATE_LIMITED: ["429", "too many requests", "rate limit"],
-  SERVICE_UNAVAILABLE: ["503", "service unavailable"],
-} as const;
+import { COMMON_ERROR_STATUS_MAP } from "@orpc/server";
+import { z } from "zod";
 
 /**
  * Common error schemas for plugin contracts.
@@ -124,14 +111,26 @@ export const PluginErrors = {
 } as const;
 
 /**
- * @deprecated Use individual imports or PluginErrors instead
+ * Error-code -> HTTP-status map for handlers.
+ *
+ * oRPC v2 resolves statuses at the handler boundary via `errorStatusMap`
+ * (default `COMMON_ERROR_STATUS_MAP`, where TIMEOUT is 408). Providing a
+ * map REPLACES the default entirely, so the standard codes must be spread
+ * back in. These custom entries preserve the v1 wire behavior:
+ * TIMEOUT -> 504, CONNECTION_ERROR -> 502.
  */
-export const CommonPluginErrors = PluginErrors;
+export const PLUGIN_ERROR_STATUS_MAP: Record<string, number> = {
+  ...COMMON_ERROR_STATUS_MAP,
+  TIMEOUT: 504,
+  CONNECTION_ERROR: 502,
+} as const;
 
+export type { PluginLoadFailureInfo, PluginWarningInfo } from "./runtime/errors";
 export {
+  classifyPluginFailure,
+  defaultMissingSecretWarnings,
   extractFromFiberFailure,
   formatORPCError,
-  isRetryableORPCCode,
   ModuleFederationError,
   PluginRuntimeError,
   toPluginRuntimeError,

package/src/identity.ts

@@ -0,0 +1,36 @@
+/**
+ * Plugin identity: every name a plugin workspace carries, derived from one
+ * input. Two seams live here:
+ *
+ * - `remoteName`/`containerName` absorb the framework's two normalizers (the
+ *   Module Federation remote name and the UI container name) — runtime,
+ *   build, and host consumers delegate to these instead of keeping private
+ *   copies, so a name can never disagree across contexts.
+ * - `identity` derives the full name set from the config layout key (the
+ *   `plugins/<key>` attachment in `bos.config.json`): the key itself (the
+ *   composition key), the npm package name under the scaffold convention,
+ *   and the two normalized build names.
+ *
+ * Normalization rules:
+ * - remote: lowercase, strip a single leading '@', replace '/' with '_',
+ *   preserve hyphens and other characters
+ *   ("@scope/my-plugin" → "scope_my-plugin")
+ * - container: replace every character outside [A-Za-z0-9_] with '_'
+ *   ("@everything-dev/auth-plugin" → "_everything_dev_auth_plugin")
+ */
+export interface PluginIdentity {
+  key: string;
+  npm: string;
+  remote: string;
+  container: string;
+}
+
+export const remoteName = (name: string): string =>
+  name.toLowerCase().replace(/^@/, "").replace(/\//g, "_");
+
+export const containerName = (pkgName: string): string => pkgName.replace(/[^A-Za-z0-9_]/g, "_");
+
+export const identity = (key: string): PluginIdentity => {
+  const npm = `@everything-dev/${key}-plugin`;
+  return { key, npm, remote: remoteName(npm), container: containerName(npm) };
+};

package/src/index.ts

@@ -1,3 +1,6 @@
+import "@orpc/openapi/extensions/route";
+
+export * from "./effect-helpers";
 export * from "./errors";
 export * from "./plugin";
 export * from "./runtime";
@@ -20,6 +23,7 @@ export type {
   PluginRouterType,
   PluginRuntimeConfig,
   PluginSecrets,
+  PluginServicesEntry,
   PluginVariables,
   RegisteredPlugins,
   SecretsConfig,

package/src/plugin.ts

@@ -1,9 +1,12 @@
 import type { AnyContractRouter, AnySchema, InferSchemaOutput } from "@orpc/contract";
-import { ORPCError } from "@orpc/contract";
-import type { Implementer, Router } from "@orpc/server";
-import { implement, onError } from "@orpc/server";
-import { Context, Effect, type Context as EffectContext, type Layer, type Scope } from "effect";
-import { extractFromFiberFailure, formatORPCError } from "./runtime/errors";
+import type { WithEffectContext } from "@orpc/experimental-effect";
+import "@orpc/experimental-effect/extensions/effect";
+import type { ContractedRouter, Implementer } from "@orpc/server";
+import { implement } from "@orpc/server";
+import type { Scope } from "effect";
+import { Context, Effect, Layer } from "effect";
+import type { PluginWarningInfo } from "./runtime/errors";
+import { type PluginRuntimeError, toPluginRuntimeError } from "./runtime/errors";
 
 type ContextOutput<T> = T extends AnySchema ? InferSchemaOutput<T> : Record<string, never>;
 
@@ -17,28 +20,33 @@ export type PluginConfigFor<
   context: TRequestContext;
 };
 
-type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+export type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
   variables: InferSchemaOutput<V>;
   secrets: InferSchemaOutput<S>;
 };
 
 /**
- * Tools provided to plugin initialize/services for building long-lived scoped resources.
+ * A plugin's own config-derived warnings, evaluated once with the validated
+ * config after initialization. Declaring `warnings` opts the plugin out of
+ * the loader's default missing-secret warning — these messages replace it.
  */
-type ServiceOf<T> = T extends EffectContext.Tag<any, infer S> ? S : never;
+export type PluginWarningsFn<V extends AnySchema, S extends AnySchema> = (
+  config: PluginInitializeInput<V, S>,
+) => PluginWarningInfo[] | string[];
 
-export type PluginServicesTools = {
-  buildService: <T>(tag: T, layer: Layer.Layer<any, any, any>) => Effect.Effect<ServiceOf<T>>;
-};
+export class PluginIdTag extends Context.Service<PluginIdTag, string>()("PluginId") {}
 
-export class PluginIdTag extends Context.Tag("PluginId")<PluginIdTag, string>() {}
+/**
+ * The `initialize` effect's environment: the plugin lifecycle scope plus the
+ * framework-assigned plugin id.
+ */
+export type PluginEnv = Scope.Scope | PluginIdTag;
 
 type PluginDefinition<
   V extends AnySchema,
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Record<string, any>,
   P extends Record<string, unknown>,
 > = {
   variables: V;
@@ -46,20 +54,42 @@ type PluginDefinition<
   contract: TContract;
   context?: TRequestContext;
   /**
-   * Initialize the plugin and build dependencies.
-   * A third argument `tools` is provided for building long-lived scoped resources
-   * (e.g. database pools) via `tools.buildService(tag, layer)`.
+   * Optional tag under which `initialize` exposes the plugin's services.
+   * The host uses it to read services (e.g. the auth plugin's Better Auth
+   * handler) from the built Effect context without importing the plugin
+   * module statically.
+   */
+  servicesTag?: Context.Key<any, any>;
+  /**
+   * Optional warnings function evaluated once with the validated config after
+   * initialization. Returns structured non-fatal warnings (e.g. an optional
+   * secret was not set, so the feature depending on it is disabled).
+   * Declaring it opts out of the loader's default missing-secret warning.
+   */
+  warnings?: PluginWarningsFn<V, S>;
+  /**
+   * Initialize the plugin by returning an Effect `Layer`.
+   *
+   * The runtime builds the Layer against the plugin's lifecycle scope —
+   * scoped resources (db pools, repositories, caches, publishers) release
+   * when the plugin shuts down. Services are provided to `.effect()`
+   * handlers via the oRPC context (`yield* Tag`).
    */
   initialize?: (
     config: PluginInitializeInput<V, S>,
     plugins: P,
-    tools: PluginServicesTools,
-  ) => Effect.Effect<TDeps, Error, Scope.Scope>;
+  ) => Effect.Effect<Layer.Layer<any, Error, PluginEnv>, Error, PluginEnv>;
+  /**
+   * Creates the strongly-typed oRPC router for this plugin.
+   * Services come from the Effect context — access them with
+   * `yield* Tag` in `.effect()` handlers, or
+   * `Context.get(context["effect/context"], Tag)` in plain handlers.
+   * Sibling plugin entries in `plugins` carry `{ client, router }`.
+   */
   createRouter: (
-    deps: TDeps,
-    builder: Implementer<TContract, ContextOutput<TRequestContext>, ContextOutput<TRequestContext>>,
-  ) => Router<TContract, any>;
-  shutdown?: (deps: TDeps) => Effect.Effect<void, Error, never>;
+    builder: Implementer<TContract, ContextOutput<TRequestContext> & WithEffectContext<any>>,
+    plugins: P,
+  ) => ContractedRouter<TContract, any>;
 };
 
 /**
@@ -70,14 +100,14 @@ export interface LoadedPluginWithBinding<
   TVariables extends AnySchema,
   TSecrets extends AnySchema,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Record<string, any> = Record<never, never>,
 > {
-  new (): Plugin<TContract, TVariables, TSecrets, TRequestContext, TDeps>;
+  new (): Plugin<TContract, TVariables, TSecrets, TRequestContext>;
   binding: {
     contract: TContract;
     variables: TVariables;
     secrets: TSecrets;
     context: TRequestContext;
+    servicesTag?: Context.Key<any, any>;
   };
 }
 
@@ -89,27 +119,26 @@ export interface Plugin<
   TVariables extends AnySchema,
   TSecrets extends AnySchema,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Record<string, any> = Record<never, never>,
 > {
   readonly id: string;
   readonly contract: TContract;
   readonly configSchema: PluginConfigFor<TVariables, TSecrets, TRequestContext>;
+  readonly servicesTag?: Context.Key<any, any>;
+  readonly warnings?: PluginWarningsFn<TVariables, TSecrets>;
 
   initialize(
     config: PluginInitializeInput<TVariables, TSecrets>,
     plugins: Record<string, unknown>,
-    tools: PluginServicesTools,
-  ): Effect.Effect<TDeps, unknown, Scope.Scope>;
-
-  shutdown(): Effect.Effect<void, never>;
+  ): Effect.Effect<Layer.Layer<any, Error, PluginEnv>, PluginRuntimeError, PluginEnv>;
 
   /**
    * Creates the strongly-typed oRPC router for this plugin.
    * The router's procedure types are inferred directly from the contract.
-   * @param deps The initialized plugin dependencies
+   * @param plugins Sibling plugin entries (`{ client, router }`) for
+   * cross-plugin composition
    * @returns A router with procedures matching the plugin's contract
    */
-  createRouter(deps: TDeps): Router<TContract, any>;
+  createRouter(plugins: Record<string, unknown>): ContractedRouter<TContract, any>;
 }
 
 export interface CreatePluginFn {
@@ -118,11 +147,10 @@ export interface CreatePluginFn {
     S extends AnySchema,
     TContract extends AnyContractRouter,
     TRequestContext extends AnySchema | undefined = undefined,
-    TDeps extends Record<string, any> = Record<never, never>,
     P extends Record<string, unknown> = Record<string, never>,
   >(
-    config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
-  ): LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
+    config: PluginDefinition<V, S, TContract, TRequestContext, P>,
+  ): LoadedPluginWithBinding<TContract, V, S, TRequestContext>;
 
   withPlugins: <P extends Record<string, unknown>>() => CreatePluginWithPlugins<P>;
 }
@@ -132,84 +160,54 @@ export const createPlugin: CreatePluginFn = function createPlugin<
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined = undefined,
-  TDeps extends Record<string, any> = Record<never, never>,
   P extends Record<string, unknown> = Record<string, never>,
->(config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>) {
+>(config: PluginDefinition<V, S, TContract, TRequestContext, P>) {
   const configSchema: PluginConfigFor<V, S, TRequestContext> = {
     variables: config.variables,
     secrets: config.secrets,
     context: config.context as TRequestContext,
   };
 
-  class CreatedPlugin implements Plugin<TContract, V, S, TRequestContext, TDeps> {
+  class CreatedPlugin implements Plugin<TContract, V, S, TRequestContext> {
     /** set during instantiation - registry key */
     id!: string;
     readonly contract = config.contract;
     readonly configSchema = configSchema;
-
-    private _deps: TDeps | null = null;
+    readonly servicesTag = config.servicesTag;
+    readonly warnings = config.warnings;
 
     initialize(
       pluginConfig: PluginInitializeInput<V, S>,
       plugins: Record<string, unknown> = {},
-      tools: PluginServicesTools,
-    ): Effect.Effect<TDeps, unknown, Scope.Scope> {
-      const init = config.initialize ?? (() => Effect.succeed({} as TDeps));
-
-      return init(pluginConfig, plugins as P, tools).pipe(
-        Effect.tap((deps) =>
-          Effect.sync(() => {
-            this._deps = deps;
-          }),
+    ): Effect.Effect<Layer.Layer<any, Error, PluginEnv>, PluginRuntimeError, PluginEnv> {
+      const init = config.initialize;
+      if (!init) {
+        return Effect.succeed(Layer.empty as unknown as Layer.Layer<any, Error, PluginEnv>);
+      }
+
+      return init(pluginConfig, plugins as P).pipe(
+        Effect.mapError((error) =>
+          toPluginRuntimeError(error, this.id, undefined, "initialize-plugin"),
         ),
-        Effect.map(() => this._deps as TDeps),
-        Effect.mapError((error) => error as unknown),
       );
     }
 
-    shutdown(): Effect.Effect<void, never> {
-      const self = this;
-      return Effect.gen(function* () {
-        if (config.shutdown && self._deps) {
-          yield* config
-            .shutdown(self._deps)
-            .pipe(
-              Effect.catchAll((error) =>
-                Effect.logWarning(`Plugin shutdown hook failed for ${self.id}`, error),
-              ),
-            );
-        }
-        self._deps = null;
-      });
-    }
-
-    createRouter(deps: TDeps): Router<TContract, any> {
-      const base = implement(config.contract).$context<ContextOutput<TRequestContext>>();
-      const errorMiddleware = onError((error: unknown) => {
-        const unwrapped = extractFromFiberFailure(error);
-
-        if (unwrapped !== error && unwrapped instanceof ORPCError) {
-          throw unwrapped;
-        }
-
-        const formatted = formatORPCError(error);
-        if (formatted) console.error(formatted);
-        throw error;
-      }) as any;
-
-      const builder = (base as any).use(errorMiddleware);
-      const router = config.createRouter(deps, builder as any);
-      return router as Router<TContract, any>;
+    createRouter(plugins: Record<string, unknown>): ContractedRouter<TContract, any> {
+      const builder = implement(config.contract).$context<
+        ContextOutput<TRequestContext> & WithEffectContext<any>
+      >();
+      return config.createRouter(builder as any, plugins as P) as ContractedRouter<TContract, any>;
     }
   }
 
   const PluginConstructor = CreatedPlugin as unknown as {
-    new (): Plugin<TContract, V, S, TRequestContext, TDeps>;
+    new (): Plugin<TContract, V, S, TRequestContext>;
     binding: {
       contract: TContract;
       variables: V;
       secrets: S;
       context: TRequestContext;
+      servicesTag?: Context.Key<any, any>;
     };
   };
 
@@ -218,9 +216,10 @@ export const createPlugin: CreatePluginFn = function createPlugin<
     variables: config.variables,
     secrets: config.secrets,
     context: config.context as TRequestContext,
+    servicesTag: config.servicesTag,
   };
 
-  return PluginConstructor as LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
+  return PluginConstructor as LoadedPluginWithBinding<TContract, V, S, TRequestContext>;
 };
 
 export type CreatePluginWithPlugins<P extends Record<string, unknown>> = <
@@ -228,10 +227,9 @@ export type CreatePluginWithPlugins<P extends Record<string, unknown>> = <
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined = undefined,
-  TDeps extends Record<string, any> = Record<never, never>,
 >(
-  config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
-) => LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
+  config: PluginDefinition<V, S, TContract, TRequestContext, P>,
+) => LoadedPluginWithBinding<TContract, V, S, TRequestContext>;
 
 export function withPlugins<P extends Record<string, unknown>>(): CreatePluginWithPlugins<P> {
   return <
@@ -239,10 +237,9 @@ export function withPlugins<P extends Record<string, unknown>>(): CreatePluginWi
     S extends AnySchema,
     TContract extends AnyContractRouter,
     TRequestContext extends AnySchema | undefined = undefined,
-    TDeps extends Record<string, any> = Record<never, never>,
   >(
-    config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
-  ) => createPlugin<V, S, TContract, TRequestContext, TDeps, P>(config as any);
+    config: PluginDefinition<V, S, TContract, TRequestContext, P>,
+  ) => createPlugin<V, S, TContract, TRequestContext, P>(config as any);
 }
 
 createPlugin.withPlugins = withPlugins;

package/src/remote-entry.ts

@@ -0,0 +1,171 @@
+/**
+ * Remote-entry loading resilience — the ONE contract every MF consumer in
+ * the dev stack shares (plugin dev serves, the host's plugin loader).
+ *
+ * Two failure classes it exists for:
+ * 1. Cold compile: remoteEntry.js 404s until the remote's first build —
+ *    the 404 body gets eval'd as JS ("Unexpected identifier 'Found'").
+ * 2. Watch-rebuild poisoning: a failed entry load is memoized forever in
+ *    `globalThis.__GLOBAL_LOADING_REMOTE_ENTRY__` (runtime-core never evicts
+ *    rejections), so retries without a purge await the same failure.
+ */
+import { Duration, Effect, Schedule } from "effect";
+import type { PluginRuntimeError } from "./runtime/errors";
+import {
+  classifyPluginFailure,
+  deepestErrorStack,
+  type PluginFailureClassification,
+  toPluginRuntimeError,
+} from "./runtime/errors";
+
+const POLL_INTERVAL_MS = 300;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const RETRY_BASE_DELAY_MS = 500;
+const RETRY_MAX_DELAY_MS = 5_000;
+
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Deletes the failed remote's keys from the process-global entry-load cache.
+ * Deleting a RESOLVED entry would force a wasteful re-eval, so only call
+ * this from failure paths.
+ */
+export const purgeRemoteEntryCache = (remoteUrl: string): void => {
+  const globalLoading = (globalThis as Record<string, unknown>).__GLOBAL_LOADING_REMOTE_ENTRY__ as
+    | Record<string, unknown>
+    | undefined;
+  if (!globalLoading) return;
+  for (const key of Object.keys(globalLoading)) {
+    if (key.endsWith(`:${remoteUrl}`)) delete globalLoading[key];
+  }
+};
+
+export const isRemoteEntryBody = (body: string): boolean =>
+  !/not found|<(!doctype|html)/i.test(body.slice(0, 64));
+
+export const waitForRemoteEntryReady = async (
+  label: string,
+  url: string,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<void> => {
+  const deadline = Date.now() + timeoutMs;
+  let announced = false;
+  while (Date.now() < deadline) {
+    const res = await fetch(url).catch(() => null);
+    if (res?.ok && isRemoteEntryBody(await res.text().catch(() => ""))) return;
+    if (!announced) {
+      announced = true;
+      console.log(`⏳ waiting for ${label} to compile (remote entry not ready)…`);
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(`${label} remote entry never became ready at ${url}`);
+};
+
+export interface PluginLoadAttemptInfo {
+  attempt: number;
+  classification: PluginFailureClassification;
+}
+
+export interface PluginLoadRetryOptions<T> {
+  /** short plugin key for log prefixes (host entry key or plugin id) */
+  label: string;
+  remoteUrl: string;
+  load: () => Promise<T>;
+  /** wall-clock budget for the retry loop */
+  timeoutMs?: number;
+  /**
+   * Budget for the readiness poll (cold-compile wait) — defaults to the
+   * retry budget, preserving the historical behavior. Pass `0` to skip the
+   * poll (useful when the caller stubs `load` and does not need network).
+   */
+  readinessTimeoutMs?: number;
+  /**
+   * Observes every failed attempt (including non-retryable ones that end the
+   * loop). Defaults to classification-deduped console.error under the
+   * `[Plugins]` prefix.
+   */
+  onAttempt?: ((error: unknown, info: PluginLoadAttemptInfo) => void) | undefined;
+}
+
+/**
+ * The one plugin-load retry policy: poll the remote entry until it is actually
+ * served, then load with capped exponential backoff — purging the poisoned
+ * global entry cache between attempts so each retry genuinely re-fetches.
+ *
+ * Recovery policy is `classifyPluginFailure().retryable`: transient network
+ * conditions retry until the wall-clock budget runs out; permanent failures
+ * (MF identity skew, schema validation, dead remotes, TLS verification) fail
+ * fast on the first attempt instead of burning the budget silently.
+ *
+ * Fails with the ORIGINAL error from `load` — the host builds
+ * `PluginBootstrapError.cause` from it and classification walks it.
+ */
+export const loadRemoteWithRetry = <T>(
+  options: PluginLoadRetryOptions<T>,
+): Effect.Effect<T, PluginRuntimeError> => {
+  const {
+    label,
+    remoteUrl,
+    load,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    readinessTimeoutMs,
+    onAttempt,
+  } = options;
+  const readinessTimeout = readinessTimeoutMs ?? timeoutMs;
+
+  const schedule = Schedule.exponential(Duration.millis(RETRY_BASE_DELAY_MS)).pipe(
+    Schedule.modifyDelay(({ output }) =>
+      Effect.succeed(
+        Duration.toMillis(output) > RETRY_MAX_DELAY_MS
+          ? Duration.millis(RETRY_MAX_DELAY_MS)
+          : output,
+      ),
+    ),
+    Schedule.upTo({ duration: Duration.millis(timeoutMs) }),
+  );
+
+  let attempt = 0;
+  let lastSignature: string | undefined;
+  const reportFailure = (error: unknown): void => {
+    attempt += 1;
+    purgeRemoteEntryCache(remoteUrl);
+    const classification = classifyPluginFailure(error);
+    if (onAttempt) {
+      onAttempt(error, { attempt, classification });
+      return;
+    }
+    const signature = `${classification.kind}::${classification.message}`;
+    if (signature === lastSignature) return;
+    lastSignature = signature;
+    // The message alone is rarely enough, and the wrapper's own stack points
+    // at the wrapping frames — log the DEEPEST cause's stack (the original
+    // throw site inside the evaluated remote entry).
+    const stack = deepestErrorStack(error);
+    console.error(
+      `[Plugins][${label}] ❌ ${classification.kind} failure (attempt ${attempt}): ${classification.message}` +
+        (classification.suggestion ? `\n[Plugins][${label}] → ${classification.suggestion}` : "") +
+        (stack ? `\n[Plugins][${label}] ${stack}` : ""),
+    );
+  };
+
+  const loadWithRetry = Effect.tryPromise({
+    try: load,
+    catch: (error) => toPluginRuntimeError(error, label, undefined, "remote-entry-load"),
+  }).pipe(
+    Effect.tapError((error) => Effect.sync(() => reportFailure(error))),
+    Effect.retry({ schedule, while: (error) => classifyPluginFailure(error).retryable }),
+  );
+
+  // readinessTimeoutMs: 0 skips the cold-compile poll (tests stub `load` and
+  // must not race a 1ms wall-clock window against the event loop).
+  if (readinessTimeout === 0) {
+    return loadWithRetry;
+  }
+
+  return Effect.tryPromise({
+    try: () => waitForRemoteEntryReady(label, remoteUrl, readinessTimeout),
+    catch: (error) => toPluginRuntimeError(error, label, undefined, "remote-entry-readiness"),
+  }).pipe(Effect.flatMap(() => loadWithRetry));
+};