every-plugin 2.10.1 → 3.0.0-rc.3

package/dist/plugin.d.mts

@@ -1,6 +1,9 @@
-import { AnyContractRouter, AnySchema, InferSchemaOutput } from "@orpc/contract";
+import { PluginRuntimeError, PluginWarningInfo } from "./runtime/errors.mjs";
 import { Context, Effect, Layer, Scope } from "effect";
-import { Implementer, Router } from "@orpc/server";
+import { ContractedRouter, Implementer } from "@orpc/server";
+import "@orpc/experimental-effect/extensions/effect";
+import { AnyContractRouter, AnySchema, InferSchemaOutput } from "@orpc/contract";
+import { WithEffectContext } from "@orpc/experimental-effect";
 //#region src/plugin.d.ts
 type ContextOutput<T> = T extends AnySchema ? InferSchemaOutput<T> : Record<string, never>;
 type PluginConfigFor<V extends AnySchema, S extends AnySchema, TRequestContext extends AnySchema | undefined> = {
@@ -13,64 +16,94 @@ type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
   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 Context.Tag<any, infer S> ? S : never;
-type PluginServicesTools = {
-  buildService: <T>(tag: T, layer: Layer.Layer<any, any, any>) => Effect.Effect<ServiceOf<T>>;
-};
-declare const PluginIdTag_base: Context.TagClass<PluginIdTag, "PluginId", string>;
+type PluginWarningsFn<V extends AnySchema, S extends AnySchema> = (config: PluginInitializeInput<V, S>) => PluginWarningInfo[] | string[];
+declare const PluginIdTag_base: Context.ServiceClass<PluginIdTag, "PluginId", string>;
 declare class PluginIdTag extends PluginIdTag_base {}
-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>> = {
+/**
+ * The `initialize` effect's environment: the plugin lifecycle scope plus the
+ * framework-assigned plugin id.
+ */
+type PluginEnv = Scope.Scope | PluginIdTag;
+type PluginDefinition<V extends AnySchema, S extends AnySchema, TContract extends AnyContractRouter, TRequestContext extends AnySchema | undefined, P extends Record<string, unknown>> = {
   variables: V;
   secrets: S;
   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) => 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 }`.
    */
-  initialize?: (config: PluginInitializeInput<V, S>, plugins: P, tools: PluginServicesTools) => Effect.Effect<TDeps, Error, Scope.Scope>;
-  createRouter: (deps: TDeps, builder: Implementer<TContract, ContextOutput<TRequestContext>, ContextOutput<TRequestContext>>) => Router<TContract, any>;
-  shutdown?: (deps: TDeps) => Effect.Effect<void, Error, never>;
+  createRouter: (builder: Implementer<TContract, ContextOutput<TRequestContext> & WithEffectContext<any>>, plugins: P) => ContractedRouter<TContract, any>;
 };
 /**
  * Loaded plugin with static binding property
  */
-interface LoadedPluginWithBinding<TContract extends AnyContractRouter, 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>;
+interface LoadedPluginWithBinding<TContract extends AnyContractRouter, TVariables extends AnySchema, TSecrets extends AnySchema, TRequestContext extends AnySchema | undefined> {
+  new (): Plugin<TContract, TVariables, TSecrets, TRequestContext>;
   binding: {
     contract: TContract;
     variables: TVariables;
     secrets: TSecrets;
     context: TRequestContext;
+    servicesTag?: Context.Key<any, any>;
   };
 }
 /**
  * Plugin interface
  */
-interface Plugin<TContract extends AnyContractRouter, TVariables extends AnySchema, TSecrets extends AnySchema, TRequestContext extends AnySchema | undefined, TDeps extends Record<string, any> = Record<never, never>> {
+interface Plugin<TContract extends AnyContractRouter, TVariables extends AnySchema, TSecrets extends AnySchema, TRequestContext extends AnySchema | undefined> {
   readonly id: string;
   readonly contract: TContract;
   readonly configSchema: PluginConfigFor<TVariables, TSecrets, TRequestContext>;
-  initialize(config: PluginInitializeInput<TVariables, TSecrets>, plugins: Record<string, unknown>, tools: PluginServicesTools): Effect.Effect<TDeps, unknown, Scope.Scope>;
-  shutdown(): Effect.Effect<void, never>;
+  readonly servicesTag?: Context.Key<any, any>;
+  readonly warnings?: PluginWarningsFn<TVariables, TSecrets>;
+  initialize(config: PluginInitializeInput<TVariables, TSecrets>, plugins: Record<string, unknown>): 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>;
 }
 interface CreatePluginFn {
-  <V extends AnySchema, 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>;
+  <V extends AnySchema, S extends AnySchema, TContract extends AnyContractRouter, TRequestContext extends AnySchema | undefined = undefined, P extends Record<string, unknown> = Record<string, never>>(config: PluginDefinition<V, S, TContract, TRequestContext, P>): LoadedPluginWithBinding<TContract, V, S, TRequestContext>;
   withPlugins: <P extends Record<string, unknown>>() => CreatePluginWithPlugins<P>;
 }
 declare const createPlugin: CreatePluginFn;
-type CreatePluginWithPlugins<P extends Record<string, unknown>> = <V extends AnySchema, 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>;
+type CreatePluginWithPlugins<P extends Record<string, unknown>> = <V extends AnySchema, S extends AnySchema, TContract extends AnyContractRouter, TRequestContext extends AnySchema | undefined = undefined>(config: PluginDefinition<V, S, TContract, TRequestContext, P>) => LoadedPluginWithBinding<TContract, V, S, TRequestContext>;
 declare function withPlugins<P extends Record<string, unknown>>(): CreatePluginWithPlugins<P>;
 //#endregion
-export { CreatePluginFn, CreatePluginWithPlugins, LoadedPluginWithBinding, Plugin, PluginConfigFor, PluginIdTag, PluginServicesTools, createPlugin, withPlugins };
+export { CreatePluginFn, CreatePluginWithPlugins, LoadedPluginWithBinding, Plugin, PluginConfigFor, PluginEnv, PluginIdTag, PluginInitializeInput, PluginWarningsFn, createPlugin, withPlugins };
 //# sourceMappingURL=plugin.d.mts.map

package/dist/plugin.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.mts","names":[],"sources":["../src/plugin.ts"],"mappings":";;;;KAOK,cAAc,KAAK,UAAU,YAAY,kBAAkB,KAAK;KAEzD,gBACV,UAAU,WACV,UAAU,WACV,wBAAwB;EAExB,WAAW;EACX,SAAS;EACT,SAAS;;KAGN,sBAAsB,UAAU,WAAW,UAAU;EACxD,WAAW,kBAAkB;EAC7B,SAAS,kBAAkB;;;;;KAMxB,UAAU,KAAK,UAAU,QAAc,eAAe,KAAK;KAEpD;EACV,eAAe,GAAG,KAAK,GAAG,OAAO,MAAM,yBAAyB,OAAO,OAAO,UAAU;;;cAG7E,oBAAoB;KAE5B,iBACH,UAAU,WACV,UAAU,WACV,kBAAkB,mBAClB,wBAAwB,uBACxB,cAAc,qBACd,UAAU;EAEV,WAAW;EACX,SAAS;EACT,UAAU;EACV,UAAU;;;;;;EAMV,cACE,QAAQ,sBAAsB,GAAG,IACjC,SAAS,GACT,OAAO,wBACJ,OAAO,OAAO,OAAO,OAAO,MAAM;EACvC,eACE,MAAM,OACN,SAAS,YAAY,WAAW,cAAc,kBAAkB,cAAc,sBAC3E,OAAO;EACZ,YAAY,MAAM,UAAU,OAAO,aAAa;;;;;UAMjC,wBACf,kBAAkB,mBAClB,mBAAmB,WACnB,iBAAiB,WACjB,wBAAwB,uBACxB,cAAc,sBAAsB;UAE5B,OAAO,WAAW,YAAY,UAAU,iBAAiB;EACjE;IACE,UAAU;IACV,WAAW;IACX,SAAS;IACT,SAAS;;;;;;UAOI,OACf,kBAAkB,mBAClB,mBAAmB,WACnB,iBAAiB,WACjB,wBAAwB,uBACxB,cAAc,sBAAsB;WAE3B;WACA,UAAU;WACV,cAAc,gBAAgB,YAAY,UAAU;EAE7D,WACE,QAAQ,sBAAsB,YAAY,WAC1C,SAAS,yBACT,OAAO,sBACN,OAAO,OAAO,gBAAgB,MAAM;EAEvC,YAAY,OAAO;;;;;;;EAQnB,aAAa,MAAM,QAAQ,OAAO;;UAGnB;GAEb,UAAU,WACV,UAAU,WACV,kBAAkB,mBAClB,wBAAwB,mCACxB,cAAc,sBAAsB,sBACpC,UAAU,0BAA0B,uBAEpC,QAAQ,iBAAiB,GAAG,GAAG,WAAW,iBAAiB,OAAO,KACjE,wBAAwB,WAAW,GAAG,GAAG,iBAAiB;EAE7D,cAAc,UAAU,8BAA8B,wBAAwB;;cAGnE,cAAc;KAgGf,wBAAwB,UAAU,4BAC5C,UAAU,WACV,UAAU,WACV,kBAAkB,mBAClB,wBAAwB,mCACxB,cAAc,sBAAsB,sBAEpC,QAAQ,iBAAiB,GAAG,GAAG,WAAW,iBAAiB,OAAO,OAC/D,wBAAwB,WAAW,GAAG,GAAG,iBAAiB;iBAE/C,YAAY,UAAU,4BAA4B,wBAAwB"}
+{"version":3,"file":"plugin.d.mts","names":[],"sources":["../src/plugin.ts"],"mappings":";;;;;;;KAUK,cAAc,KAAK,UAAU,YAAY,kBAAkB,KAAK;KAEzD,gBACV,UAAU,WACV,UAAU,WACV,wBAAwB;EAExB,WAAW;EACX,SAAS;EACT,SAAS;;KAGC,sBAAsB,UAAU,WAAW,UAAU;EAC/D,WAAW,kBAAkB;EAC7B,SAAS,kBAAkB;;;;;;;KAQjB,iBAAiB,UAAU,WAAW,UAAU,cAC1D,QAAQ,sBAAsB,GAAG,OAC9B;;cAEQ,oBAAoB;;;;;KAMrB,YAAY,MAAM,QAAQ;KAEjC,iBACH,UAAU,WACV,UAAU,WACV,kBAAkB,mBAClB,wBAAwB,uBACxB,UAAU;EAEV,WAAW;EACX,SAAS;EACT,UAAU;EACV,UAAU;;;;;;;EAOV,cAAc,QAAQ;;;;;;;EAOtB,WAAW,iBAAiB,GAAG;;;;;;;;;EAS/B,cACE,QAAQ,sBAAsB,GAAG,IACjC,SAAS,MACN,OAAO,OAAO,MAAM,WAAW,OAAO,YAAY,OAAO;;;;;;;;EAQ9D,eACE,SAAS,YAAY,WAAW,cAAc,mBAAmB,yBACjE,SAAS,MACN,iBAAiB;;;;;UAMP,wBACf,kBAAkB,mBAClB,mBAAmB,WACnB,iBAAiB,WACjB,wBAAwB;UAEhB,OAAO,WAAW,YAAY,UAAU;EAChD;IACE,UAAU;IACV,WAAW;IACX,SAAS;IACT,SAAS;IACT,cAAc,QAAQ;;;;;;UAOT,OACf,kBAAkB,mBAClB,mBAAmB,WACnB,iBAAiB,WACjB,wBAAwB;WAEf;WACA,UAAU;WACV,cAAc,gBAAgB,YAAY,UAAU;WACpD,cAAc,QAAQ;WACtB,WAAW,iBAAiB,YAAY;EAEjD,WACE,QAAQ,sBAAsB,YAAY,WAC1C,SAAS,0BACR,OAAO,OAAO,MAAM,WAAW,OAAO,YAAY,oBAAoB;;;;;;;;EASzE,aAAa,SAAS,0BAA0B,iBAAiB;;UAGlD;GAEb,UAAU,WACV,UAAU,WACV,kBAAkB,mBAClB,wBAAwB,mCACxB,UAAU,0BAA0B,uBAEpC,QAAQ,iBAAiB,GAAG,GAAG,WAAW,iBAAiB,KAC1D,wBAAwB,WAAW,GAAG,GAAG;EAE5C,cAAc,UAAU,8BAA8B,wBAAwB;;cAGnE,cAAc;KAmEf,wBAAwB,UAAU,4BAC5C,UAAU,WACV,UAAU,WACV,kBAAkB,mBAClB,wBAAwB,mCAExB,QAAQ,iBAAiB,GAAG,GAAG,WAAW,iBAAiB,OACxD,wBAAwB,WAAW,GAAG,GAAG;iBAE9B,YAAY,UAAU,4BAA4B,wBAAwB"}

package/dist/plugin.mjs

@@ -1,10 +1,10 @@
-import { extractFromFiberFailure, formatORPCError } from "./runtime/errors.mjs";
-import { ORPCError } from "@orpc/contract";
-import { Context, Effect } from "effect";
-import { implement, onError } from "@orpc/server";
+import { toPluginRuntimeError } from "./runtime/errors.mjs";
+import { Context, Effect, Layer } from "effect";
+import { implement } from "@orpc/server";
+import "@orpc/experimental-effect/extensions/effect";
 
 //#region src/plugin.ts
-var PluginIdTag = class extends Context.Tag("PluginId")() {};
+var PluginIdTag = class extends Context.Service()("PluginId") {};
 const createPlugin = function createPlugin(config) {
 	const configSchema = {
 		variables: config.variables,
@@ -16,30 +16,16 @@ const createPlugin = function createPlugin(config) {
 		id;
 		contract = config.contract;
 		configSchema = configSchema;
-		_deps = null;
-		initialize(pluginConfig, plugins = {}, tools) {
-			return (config.initialize ?? (() => Effect.succeed({})))(pluginConfig, plugins, tools).pipe(Effect.tap((deps) => Effect.sync(() => {
-				this._deps = deps;
-			})), Effect.map(() => this._deps), Effect.mapError((error) => error));
+		servicesTag = config.servicesTag;
+		warnings = config.warnings;
+		initialize(pluginConfig, plugins = {}) {
+			const init = config.initialize;
+			if (!init) return Effect.succeed(Layer.empty);
+			return init(pluginConfig, plugins).pipe(Effect.mapError((error) => toPluginRuntimeError(error, this.id, void 0, "initialize-plugin")));
 		}
-		shutdown() {
-			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) {
-			const base = implement(config.contract).$context();
-			const errorMiddleware = onError((error) => {
-				const unwrapped = extractFromFiberFailure(error);
-				if (unwrapped !== error && unwrapped instanceof ORPCError) throw unwrapped;
-				const formatted = formatORPCError(error);
-				if (formatted) console.error(formatted);
-				throw error;
-			});
-			const builder = base.use(errorMiddleware);
-			return config.createRouter(deps, builder);
+		createRouter(plugins) {
+			const builder = implement(config.contract).$context();
+			return config.createRouter(builder, plugins);
 		}
 	}
 	const PluginConstructor = CreatedPlugin;
@@ -47,7 +33,8 @@ const createPlugin = function createPlugin(config) {
 		contract: config.contract,
 		variables: config.variables,
 		secrets: config.secrets,
-		context: config.context
+		context: config.context,
+		servicesTag: config.servicesTag
 	};
 	return PluginConstructor;
 };

package/dist/plugin.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.mjs","names":[],"sources":["../src/plugin.ts"],"sourcesContent":["import type { AnyContractRouter, AnySchema, InferSchemaOutput } from \"@orpc/contract\";\nimport { ORPCError } from \"@orpc/contract\";\nimport type { Implementer, Router } from \"@orpc/server\";\nimport { implement, onError } from \"@orpc/server\";\nimport { Context, Effect, type Context as EffectContext, type Layer, type Scope } from \"effect\";\nimport { extractFromFiberFailure, formatORPCError } from \"./runtime/errors\";\n\ntype ContextOutput<T> = T extends AnySchema ? InferSchemaOutput<T> : Record<string, never>;\n\nexport type PluginConfigFor<\n  V extends AnySchema,\n  S extends AnySchema,\n  TRequestContext extends AnySchema | undefined,\n> = {\n  variables: V;\n  secrets: S;\n  context: TRequestContext;\n};\n\ntype PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {\n  variables: InferSchemaOutput<V>;\n  secrets: InferSchemaOutput<S>;\n};\n\n/**\n * Tools provided to plugin initialize/services for building long-lived scoped resources.\n */\ntype ServiceOf<T> = T extends EffectContext.Tag<any, infer S> ? S : never;\n\nexport type PluginServicesTools = {\n  buildService: <T>(tag: T, layer: Layer.Layer<any, any, any>) => Effect.Effect<ServiceOf<T>>;\n};\n\nexport class PluginIdTag extends Context.Tag(\"PluginId\")<PluginIdTag, string>() {}\n\ntype PluginDefinition<\n  V extends AnySchema,\n  S extends AnySchema,\n  TContract extends AnyContractRouter,\n  TRequestContext extends AnySchema | undefined,\n  TDeps extends Record<string, any>,\n  P extends Record<string, unknown>,\n> = {\n  variables: V;\n  secrets: S;\n  contract: TContract;\n  context?: TRequestContext;\n  /**\n   * Initialize the plugin and build dependencies.\n   * A third argument `tools` is provided for building long-lived scoped resources\n   * (e.g. database pools) via `tools.buildService(tag, layer)`.\n   */\n  initialize?: (\n    config: PluginInitializeInput<V, S>,\n    plugins: P,\n    tools: PluginServicesTools,\n  ) => Effect.Effect<TDeps, Error, Scope.Scope>;\n  createRouter: (\n    deps: TDeps,\n    builder: Implementer<TContract, ContextOutput<TRequestContext>, ContextOutput<TRequestContext>>,\n  ) => Router<TContract, any>;\n  shutdown?: (deps: TDeps) => Effect.Effect<void, Error, never>;\n};\n\n/**\n * Loaded plugin with static binding property\n */\nexport interface LoadedPluginWithBinding<\n  TContract extends AnyContractRouter,\n  TVariables extends AnySchema,\n  TSecrets extends AnySchema,\n  TRequestContext extends AnySchema | undefined,\n  TDeps extends Record<string, any> = Record<never, never>,\n> {\n  new (): Plugin<TContract, TVariables, TSecrets, TRequestContext, TDeps>;\n  binding: {\n    contract: TContract;\n    variables: TVariables;\n    secrets: TSecrets;\n    context: TRequestContext;\n  };\n}\n\n/**\n * Plugin interface\n */\nexport interface Plugin<\n  TContract extends AnyContractRouter,\n  TVariables extends AnySchema,\n  TSecrets extends AnySchema,\n  TRequestContext extends AnySchema | undefined,\n  TDeps extends Record<string, any> = Record<never, never>,\n> {\n  readonly id: string;\n  readonly contract: TContract;\n  readonly configSchema: PluginConfigFor<TVariables, TSecrets, TRequestContext>;\n\n  initialize(\n    config: PluginInitializeInput<TVariables, TSecrets>,\n    plugins: Record<string, unknown>,\n    tools: PluginServicesTools,\n  ): Effect.Effect<TDeps, unknown, Scope.Scope>;\n\n  shutdown(): Effect.Effect<void, never>;\n\n  /**\n   * Creates the strongly-typed oRPC router for this plugin.\n   * The router's procedure types are inferred directly from the contract.\n   * @param deps The initialized plugin dependencies\n   * @returns A router with procedures matching the plugin's contract\n   */\n  createRouter(deps: TDeps): Router<TContract, any>;\n}\n\nexport interface CreatePluginFn {\n  <\n    V extends AnySchema,\n    S extends AnySchema,\n    TContract extends AnyContractRouter,\n    TRequestContext extends AnySchema | undefined = undefined,\n    TDeps extends Record<string, any> = Record<never, never>,\n    P extends Record<string, unknown> = Record<string, never>,\n  >(\n    config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,\n  ): LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;\n\n  withPlugins: <P extends Record<string, unknown>>() => CreatePluginWithPlugins<P>;\n}\n\nexport const createPlugin: CreatePluginFn = function createPlugin<\n  V extends AnySchema,\n  S extends AnySchema,\n  TContract extends AnyContractRouter,\n  TRequestContext extends AnySchema | undefined = undefined,\n  TDeps extends Record<string, any> = Record<never, never>,\n  P extends Record<string, unknown> = Record<string, never>,\n>(config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>) {\n  const configSchema: PluginConfigFor<V, S, TRequestContext> = {\n    variables: config.variables,\n    secrets: config.secrets,\n    context: config.context as TRequestContext,\n  };\n\n  class CreatedPlugin implements Plugin<TContract, V, S, TRequestContext, TDeps> {\n    /** set during instantiation - registry key */\n    id!: string;\n    readonly contract = config.contract;\n    readonly configSchema = configSchema;\n\n    private _deps: TDeps | null = null;\n\n    initialize(\n      pluginConfig: PluginInitializeInput<V, S>,\n      plugins: Record<string, unknown> = {},\n      tools: PluginServicesTools,\n    ): Effect.Effect<TDeps, unknown, Scope.Scope> {\n      const init = config.initialize ?? (() => Effect.succeed({} as TDeps));\n\n      return init(pluginConfig, plugins as P, tools).pipe(\n        Effect.tap((deps) =>\n          Effect.sync(() => {\n            this._deps = deps;\n          }),\n        ),\n        Effect.map(() => this._deps as TDeps),\n        Effect.mapError((error) => error as unknown),\n      );\n    }\n\n    shutdown(): Effect.Effect<void, never> {\n      const self = this;\n      return Effect.gen(function* () {\n        if (config.shutdown && self._deps) {\n          yield* config\n            .shutdown(self._deps)\n            .pipe(\n              Effect.catchAll((error) =>\n                Effect.logWarning(`Plugin shutdown hook failed for ${self.id}`, error),\n              ),\n            );\n        }\n        self._deps = null;\n      });\n    }\n\n    createRouter(deps: TDeps): Router<TContract, any> {\n      const base = implement(config.contract).$context<ContextOutput<TRequestContext>>();\n      const errorMiddleware = onError((error: unknown) => {\n        const unwrapped = extractFromFiberFailure(error);\n\n        if (unwrapped !== error && unwrapped instanceof ORPCError) {\n          throw unwrapped;\n        }\n\n        const formatted = formatORPCError(error);\n        if (formatted) console.error(formatted);\n        throw error;\n      }) as any;\n\n      const builder = (base as any).use(errorMiddleware);\n      const router = config.createRouter(deps, builder as any);\n      return router as Router<TContract, any>;\n    }\n  }\n\n  const PluginConstructor = CreatedPlugin as unknown as {\n    new (): Plugin<TContract, V, S, TRequestContext, TDeps>;\n    binding: {\n      contract: TContract;\n      variables: V;\n      secrets: S;\n      context: TRequestContext;\n    };\n  };\n\n  PluginConstructor.binding = {\n    contract: config.contract,\n    variables: config.variables,\n    secrets: config.secrets,\n    context: config.context as TRequestContext,\n  };\n\n  return PluginConstructor as LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;\n};\n\nexport type CreatePluginWithPlugins<P extends Record<string, unknown>> = <\n  V extends AnySchema,\n  S extends AnySchema,\n  TContract extends AnyContractRouter,\n  TRequestContext extends AnySchema | undefined = undefined,\n  TDeps extends Record<string, any> = Record<never, never>,\n>(\n  config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,\n) => LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;\n\nexport function withPlugins<P extends Record<string, unknown>>(): CreatePluginWithPlugins<P> {\n  return <\n    V extends AnySchema,\n    S extends AnySchema,\n    TContract extends AnyContractRouter,\n    TRequestContext extends AnySchema | undefined = undefined,\n    TDeps extends Record<string, any> = Record<never, never>,\n  >(\n    config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,\n  ) => createPlugin<V, S, TContract, TRequestContext, TDeps, P>(config as any);\n}\n\ncreatePlugin.withPlugins = withPlugins;\n"],"mappings":";;;;;;AAiCA,IAAa,cAAb,cAAiC,QAAQ,IAAI,UAAU,CAAC,CAAsB,CAAC,CAAC,CAAC;AAgGjF,MAAa,eAA+B,SAAS,aAOnD,QAAsE;CACtE,MAAM,eAAuD;EAC3D,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,SAAS,OAAO;CAClB;CAEA,MAAM,cAAyE;;EAE7E;EACA,AAAS,WAAW,OAAO;EAC3B,AAAS,eAAe;EAExB,AAAQ,QAAsB;EAE9B,WACE,cACA,UAAmC,CAAC,GACpC,OAC4C;GAG5C,QAFa,OAAO,qBAAqB,OAAO,QAAQ,CAAC,CAAU,GAExD,CAAC,cAAc,SAAc,KAAK,CAAC,CAAC,KAC7C,OAAO,KAAK,SACV,OAAO,WAAW;IAChB,KAAK,QAAQ;GACf,CAAC,CACH,GACA,OAAO,UAAU,KAAK,KAAc,GACpC,OAAO,UAAU,UAAU,KAAgB,CAC7C;EACF;EAEA,WAAuC;GACrC,MAAM,OAAO;GACb,OAAO,OAAO,IAAI,aAAa;IAC7B,IAAI,OAAO,YAAY,KAAK,OAC1B,OAAO,OACJ,SAAS,KAAK,KAAK,CAAC,CACpB,KACC,OAAO,UAAU,UACf,OAAO,WAAW,mCAAmC,KAAK,MAAM,KAAK,CACvE,CACF;IAEJ,KAAK,QAAQ;GACf,CAAC;EACH;EAEA,aAAa,MAAqC;GAChD,MAAM,OAAO,UAAU,OAAO,QAAQ,CAAC,CAAC,SAAyC;GACjF,MAAM,kBAAkB,SAAS,UAAmB;IAClD,MAAM,YAAY,wBAAwB,KAAK;IAE/C,IAAI,cAAc,SAAS,qBAAqB,WAC9C,MAAM;IAGR,MAAM,YAAY,gBAAgB,KAAK;IACvC,IAAI,WAAW,QAAQ,MAAM,SAAS;IACtC,MAAM;GACR,CAAC;GAED,MAAM,UAAW,KAAa,IAAI,eAAe;GAEjD,OADe,OAAO,aAAa,MAAM,OAC7B;EACd;CACF;CAEA,MAAM,oBAAoB;CAU1B,kBAAkB,UAAU;EAC1B,UAAU,OAAO;EACjB,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,SAAS,OAAO;CAClB;CAEA,OAAO;AACT;AAYA,SAAgB,cAA6E;CAC3F,QAOE,WACG,aAAyD,MAAa;AAC7E;AAEA,aAAa,cAAc"}
+{"version":3,"file":"plugin.mjs","names":[],"sources":["../src/plugin.ts"],"sourcesContent":["import type { AnyContractRouter, AnySchema, InferSchemaOutput } from \"@orpc/contract\";\nimport type { WithEffectContext } from \"@orpc/experimental-effect\";\nimport \"@orpc/experimental-effect/extensions/effect\";\nimport type { ContractedRouter, Implementer } from \"@orpc/server\";\nimport { implement } from \"@orpc/server\";\nimport type { Scope } from \"effect\";\nimport { Context, Effect, Layer } from \"effect\";\nimport type { PluginWarningInfo } from \"./runtime/errors\";\nimport { type PluginRuntimeError, toPluginRuntimeError } from \"./runtime/errors\";\n\ntype ContextOutput<T> = T extends AnySchema ? InferSchemaOutput<T> : Record<string, never>;\n\nexport type PluginConfigFor<\n  V extends AnySchema,\n  S extends AnySchema,\n  TRequestContext extends AnySchema | undefined,\n> = {\n  variables: V;\n  secrets: S;\n  context: TRequestContext;\n};\n\nexport type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {\n  variables: InferSchemaOutput<V>;\n  secrets: InferSchemaOutput<S>;\n};\n\n/**\n * A plugin's own config-derived warnings, evaluated once with the validated\n * config after initialization. Declaring `warnings` opts the plugin out of\n * the loader's default missing-secret warning — these messages replace it.\n */\nexport type PluginWarningsFn<V extends AnySchema, S extends AnySchema> = (\n  config: PluginInitializeInput<V, S>,\n) => PluginWarningInfo[] | string[];\n\nexport class PluginIdTag extends Context.Service<PluginIdTag, string>()(\"PluginId\") {}\n\n/**\n * The `initialize` effect's environment: the plugin lifecycle scope plus the\n * framework-assigned plugin id.\n */\nexport type PluginEnv = Scope.Scope | PluginIdTag;\n\ntype PluginDefinition<\n  V extends AnySchema,\n  S extends AnySchema,\n  TContract extends AnyContractRouter,\n  TRequestContext extends AnySchema | undefined,\n  P extends Record<string, unknown>,\n> = {\n  variables: V;\n  secrets: S;\n  contract: TContract;\n  context?: TRequestContext;\n  /**\n   * Optional tag under which `initialize` exposes the plugin's services.\n   * The host uses it to read services (e.g. the auth plugin's Better Auth\n   * handler) from the built Effect context without importing the plugin\n   * module statically.\n   */\n  servicesTag?: Context.Key<any, any>;\n  /**\n   * Optional warnings function evaluated once with the validated config after\n   * initialization. Returns structured non-fatal warnings (e.g. an optional\n   * secret was not set, so the feature depending on it is disabled).\n   * Declaring it opts out of the loader's default missing-secret warning.\n   */\n  warnings?: PluginWarningsFn<V, S>;\n  /**\n   * Initialize the plugin by returning an Effect `Layer`.\n   *\n   * The runtime builds the Layer against the plugin's lifecycle scope —\n   * scoped resources (db pools, repositories, caches, publishers) release\n   * when the plugin shuts down. Services are provided to `.effect()`\n   * handlers via the oRPC context (`yield* Tag`).\n   */\n  initialize?: (\n    config: PluginInitializeInput<V, S>,\n    plugins: P,\n  ) => Effect.Effect<Layer.Layer<any, Error, PluginEnv>, Error, PluginEnv>;\n  /**\n   * Creates the strongly-typed oRPC router for this plugin.\n   * Services come from the Effect context — access them with\n   * `yield* Tag` in `.effect()` handlers, or\n   * `Context.get(context[\"effect/context\"], Tag)` in plain handlers.\n   * Sibling plugin entries in `plugins` carry `{ client, router }`.\n   */\n  createRouter: (\n    builder: Implementer<TContract, ContextOutput<TRequestContext> & WithEffectContext<any>>,\n    plugins: P,\n  ) => ContractedRouter<TContract, any>;\n};\n\n/**\n * Loaded plugin with static binding property\n */\nexport interface LoadedPluginWithBinding<\n  TContract extends AnyContractRouter,\n  TVariables extends AnySchema,\n  TSecrets extends AnySchema,\n  TRequestContext extends AnySchema | undefined,\n> {\n  new (): Plugin<TContract, TVariables, TSecrets, TRequestContext>;\n  binding: {\n    contract: TContract;\n    variables: TVariables;\n    secrets: TSecrets;\n    context: TRequestContext;\n    servicesTag?: Context.Key<any, any>;\n  };\n}\n\n/**\n * Plugin interface\n */\nexport interface Plugin<\n  TContract extends AnyContractRouter,\n  TVariables extends AnySchema,\n  TSecrets extends AnySchema,\n  TRequestContext extends AnySchema | undefined,\n> {\n  readonly id: string;\n  readonly contract: TContract;\n  readonly configSchema: PluginConfigFor<TVariables, TSecrets, TRequestContext>;\n  readonly servicesTag?: Context.Key<any, any>;\n  readonly warnings?: PluginWarningsFn<TVariables, TSecrets>;\n\n  initialize(\n    config: PluginInitializeInput<TVariables, TSecrets>,\n    plugins: Record<string, unknown>,\n  ): Effect.Effect<Layer.Layer<any, Error, PluginEnv>, PluginRuntimeError, PluginEnv>;\n\n  /**\n   * Creates the strongly-typed oRPC router for this plugin.\n   * The router's procedure types are inferred directly from the contract.\n   * @param plugins Sibling plugin entries (`{ client, router }`) for\n   * cross-plugin composition\n   * @returns A router with procedures matching the plugin's contract\n   */\n  createRouter(plugins: Record<string, unknown>): ContractedRouter<TContract, any>;\n}\n\nexport interface CreatePluginFn {\n  <\n    V extends AnySchema,\n    S extends AnySchema,\n    TContract extends AnyContractRouter,\n    TRequestContext extends AnySchema | undefined = undefined,\n    P extends Record<string, unknown> = Record<string, never>,\n  >(\n    config: PluginDefinition<V, S, TContract, TRequestContext, P>,\n  ): LoadedPluginWithBinding<TContract, V, S, TRequestContext>;\n\n  withPlugins: <P extends Record<string, unknown>>() => CreatePluginWithPlugins<P>;\n}\n\nexport const createPlugin: CreatePluginFn = function createPlugin<\n  V extends AnySchema,\n  S extends AnySchema,\n  TContract extends AnyContractRouter,\n  TRequestContext extends AnySchema | undefined = undefined,\n  P extends Record<string, unknown> = Record<string, never>,\n>(config: PluginDefinition<V, S, TContract, TRequestContext, P>) {\n  const configSchema: PluginConfigFor<V, S, TRequestContext> = {\n    variables: config.variables,\n    secrets: config.secrets,\n    context: config.context as TRequestContext,\n  };\n\n  class CreatedPlugin implements Plugin<TContract, V, S, TRequestContext> {\n    /** set during instantiation - registry key */\n    id!: string;\n    readonly contract = config.contract;\n    readonly configSchema = configSchema;\n    readonly servicesTag = config.servicesTag;\n    readonly warnings = config.warnings;\n\n    initialize(\n      pluginConfig: PluginInitializeInput<V, S>,\n      plugins: Record<string, unknown> = {},\n    ): Effect.Effect<Layer.Layer<any, Error, PluginEnv>, PluginRuntimeError, PluginEnv> {\n      const init = config.initialize;\n      if (!init) {\n        return Effect.succeed(Layer.empty as unknown as Layer.Layer<any, Error, PluginEnv>);\n      }\n\n      return init(pluginConfig, plugins as P).pipe(\n        Effect.mapError((error) =>\n          toPluginRuntimeError(error, this.id, undefined, \"initialize-plugin\"),\n        ),\n      );\n    }\n\n    createRouter(plugins: Record<string, unknown>): ContractedRouter<TContract, any> {\n      const builder = implement(config.contract).$context<\n        ContextOutput<TRequestContext> & WithEffectContext<any>\n      >();\n      return config.createRouter(builder as any, plugins as P) as ContractedRouter<TContract, any>;\n    }\n  }\n\n  const PluginConstructor = CreatedPlugin as unknown as {\n    new (): Plugin<TContract, V, S, TRequestContext>;\n    binding: {\n      contract: TContract;\n      variables: V;\n      secrets: S;\n      context: TRequestContext;\n      servicesTag?: Context.Key<any, any>;\n    };\n  };\n\n  PluginConstructor.binding = {\n    contract: config.contract,\n    variables: config.variables,\n    secrets: config.secrets,\n    context: config.context as TRequestContext,\n    servicesTag: config.servicesTag,\n  };\n\n  return PluginConstructor as LoadedPluginWithBinding<TContract, V, S, TRequestContext>;\n};\n\nexport type CreatePluginWithPlugins<P extends Record<string, unknown>> = <\n  V extends AnySchema,\n  S extends AnySchema,\n  TContract extends AnyContractRouter,\n  TRequestContext extends AnySchema | undefined = undefined,\n>(\n  config: PluginDefinition<V, S, TContract, TRequestContext, P>,\n) => LoadedPluginWithBinding<TContract, V, S, TRequestContext>;\n\nexport function withPlugins<P extends Record<string, unknown>>(): CreatePluginWithPlugins<P> {\n  return <\n    V extends AnySchema,\n    S extends AnySchema,\n    TContract extends AnyContractRouter,\n    TRequestContext extends AnySchema | undefined = undefined,\n  >(\n    config: PluginDefinition<V, S, TContract, TRequestContext, P>,\n  ) => createPlugin<V, S, TContract, TRequestContext, P>(config as any);\n}\n\ncreatePlugin.withPlugins = withPlugins;\n"],"mappings":";;;;;;AAoCA,IAAa,cAAb,cAAiC,QAAQ,QAA6B,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;AAyHrF,MAAa,eAA+B,SAAS,aAMnD,QAA+D;CAC/D,MAAM,eAAuD;EAC3D,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,SAAS,OAAO;CAClB;CAEA,MAAM,cAAkE;;EAEtE;EACA,AAAS,WAAW,OAAO;EAC3B,AAAS,eAAe;EACxB,AAAS,cAAc,OAAO;EAC9B,AAAS,WAAW,OAAO;EAE3B,WACE,cACA,UAAmC,CAAC,GAC8C;GAClF,MAAM,OAAO,OAAO;GACpB,IAAI,CAAC,MACH,OAAO,OAAO,QAAQ,MAAM,KAAsD;GAGpF,OAAO,KAAK,cAAc,OAAY,CAAC,CAAC,KACtC,OAAO,UAAU,UACf,qBAAqB,OAAO,KAAK,IAAI,QAAW,mBAAmB,CACrE,CACF;EACF;EAEA,aAAa,SAAoE;GAC/E,MAAM,UAAU,UAAU,OAAO,QAAQ,CAAC,CAAC,SAEzC;GACF,OAAO,OAAO,aAAa,SAAgB,OAAY;EACzD;CACF;CAEA,MAAM,oBAAoB;CAW1B,kBAAkB,UAAU;EAC1B,UAAU,OAAO;EACjB,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,SAAS,OAAO;EAChB,aAAa,OAAO;CACtB;CAEA,OAAO;AACT;AAWA,SAAgB,cAA6E;CAC3F,QAME,WACG,aAAkD,MAAa;AACtE;AAEA,aAAa,cAAc"}

package/dist/remote-entry.cjs

@@ -0,0 +1,103 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_errors = require('./runtime/errors.cjs');
+let effect = require("effect");
+
+//#region src/remote-entry.ts
+/**
+* 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.
+*/
+const POLL_INTERVAL_MS = 300;
+const DEFAULT_TIMEOUT_MS = 12e4;
+const RETRY_BASE_DELAY_MS = 500;
+const RETRY_MAX_DELAY_MS = 5e3;
+const sleep = (ms) => 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.
+*/
+const purgeRemoteEntryCache = (remoteUrl) => {
+	const globalLoading = globalThis.__GLOBAL_LOADING_REMOTE_ENTRY__;
+	if (!globalLoading) return;
+	for (const key of Object.keys(globalLoading)) if (key.endsWith(`:${remoteUrl}`)) delete globalLoading[key];
+};
+const isRemoteEntryBody = (body) => !/not found|<(!doctype|html)/i.test(body.slice(0, 64));
+const waitForRemoteEntryReady = async (label, url, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+	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}`);
+};
+/**
+* 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.
+*/
+const loadRemoteWithRetry = (options) => {
+	const { label, remoteUrl, load, timeoutMs = DEFAULT_TIMEOUT_MS, readinessTimeoutMs, onAttempt } = options;
+	const readinessTimeout = readinessTimeoutMs ?? timeoutMs;
+	const schedule = effect.Schedule.exponential(effect.Duration.millis(RETRY_BASE_DELAY_MS)).pipe(effect.Schedule.modifyDelay(({ output }) => effect.Effect.succeed(effect.Duration.toMillis(output) > RETRY_MAX_DELAY_MS ? effect.Duration.millis(RETRY_MAX_DELAY_MS) : output)), effect.Schedule.upTo({ duration: effect.Duration.millis(timeoutMs) }));
+	let attempt = 0;
+	let lastSignature;
+	const reportFailure = (error) => {
+		attempt += 1;
+		purgeRemoteEntryCache(remoteUrl);
+		const classification = require_errors.classifyPluginFailure(error);
+		if (onAttempt) {
+			onAttempt(error, {
+				attempt,
+				classification
+			});
+			return;
+		}
+		const signature = `${classification.kind}::${classification.message}`;
+		if (signature === lastSignature) return;
+		lastSignature = signature;
+		const stack = require_errors.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.Effect.tryPromise({
+		try: load,
+		catch: (error) => require_errors.toPluginRuntimeError(error, label, void 0, "remote-entry-load")
+	}).pipe(effect.Effect.tapError((error) => effect.Effect.sync(() => reportFailure(error))), effect.Effect.retry({
+		schedule,
+		while: (error) => require_errors.classifyPluginFailure(error).retryable
+	}));
+	if (readinessTimeout === 0) return loadWithRetry;
+	return effect.Effect.tryPromise({
+		try: () => waitForRemoteEntryReady(label, remoteUrl, readinessTimeout),
+		catch: (error) => require_errors.toPluginRuntimeError(error, label, void 0, "remote-entry-readiness")
+	}).pipe(effect.Effect.flatMap(() => loadWithRetry));
+};
+
+//#endregion
+exports.isRemoteEntryBody = isRemoteEntryBody;
+exports.loadRemoteWithRetry = loadRemoteWithRetry;
+exports.purgeRemoteEntryCache = purgeRemoteEntryCache;
+exports.sleep = sleep;
+exports.waitForRemoteEntryReady = waitForRemoteEntryReady;
+//# sourceMappingURL=remote-entry.cjs.map

package/dist/remote-entry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-entry.cjs","names":["Schedule","Duration","Effect","classifyPluginFailure","deepestErrorStack","toPluginRuntimeError"],"sources":["../src/remote-entry.ts"],"sourcesContent":["/**\n * Remote-entry loading resilience — the ONE contract every MF consumer in\n * the dev stack shares (plugin dev serves, the host's plugin loader).\n *\n * Two failure classes it exists for:\n * 1. Cold compile: remoteEntry.js 404s until the remote's first build —\n *    the 404 body gets eval'd as JS (\"Unexpected identifier 'Found'\").\n * 2. Watch-rebuild poisoning: a failed entry load is memoized forever in\n *    `globalThis.__GLOBAL_LOADING_REMOTE_ENTRY__` (runtime-core never evicts\n *    rejections), so retries without a purge await the same failure.\n */\nimport { Duration, Effect, Schedule } from \"effect\";\nimport type { PluginRuntimeError } from \"./runtime/errors\";\nimport {\n  classifyPluginFailure,\n  deepestErrorStack,\n  type PluginFailureClassification,\n  toPluginRuntimeError,\n} from \"./runtime/errors\";\n\nconst POLL_INTERVAL_MS = 300;\nconst DEFAULT_TIMEOUT_MS = 120_000;\nconst RETRY_BASE_DELAY_MS = 500;\nconst RETRY_MAX_DELAY_MS = 5_000;\n\nexport const sleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Deletes the failed remote's keys from the process-global entry-load cache.\n * Deleting a RESOLVED entry would force a wasteful re-eval, so only call\n * this from failure paths.\n */\nexport const purgeRemoteEntryCache = (remoteUrl: string): void => {\n  const globalLoading = (globalThis as Record<string, unknown>).__GLOBAL_LOADING_REMOTE_ENTRY__ as\n    | Record<string, unknown>\n    | undefined;\n  if (!globalLoading) return;\n  for (const key of Object.keys(globalLoading)) {\n    if (key.endsWith(`:${remoteUrl}`)) delete globalLoading[key];\n  }\n};\n\nexport const isRemoteEntryBody = (body: string): boolean =>\n  !/not found|<(!doctype|html)/i.test(body.slice(0, 64));\n\nexport const waitForRemoteEntryReady = async (\n  label: string,\n  url: string,\n  timeoutMs = DEFAULT_TIMEOUT_MS,\n): Promise<void> => {\n  const deadline = Date.now() + timeoutMs;\n  let announced = false;\n  while (Date.now() < deadline) {\n    const res = await fetch(url).catch(() => null);\n    if (res?.ok && isRemoteEntryBody(await res.text().catch(() => \"\"))) return;\n    if (!announced) {\n      announced = true;\n      console.log(`⏳ waiting for ${label} to compile (remote entry not ready)…`);\n    }\n    await sleep(POLL_INTERVAL_MS);\n  }\n  throw new Error(`${label} remote entry never became ready at ${url}`);\n};\n\nexport interface PluginLoadAttemptInfo {\n  attempt: number;\n  classification: PluginFailureClassification;\n}\n\nexport interface PluginLoadRetryOptions<T> {\n  /** short plugin key for log prefixes (host entry key or plugin id) */\n  label: string;\n  remoteUrl: string;\n  load: () => Promise<T>;\n  /** wall-clock budget for the retry loop */\n  timeoutMs?: number;\n  /**\n   * Budget for the readiness poll (cold-compile wait) — defaults to the\n   * retry budget, preserving the historical behavior. Pass `0` to skip the\n   * poll (useful when the caller stubs `load` and does not need network).\n   */\n  readinessTimeoutMs?: number;\n  /**\n   * Observes every failed attempt (including non-retryable ones that end the\n   * loop). Defaults to classification-deduped console.error under the\n   * `[Plugins]` prefix.\n   */\n  onAttempt?: ((error: unknown, info: PluginLoadAttemptInfo) => void) | undefined;\n}\n\n/**\n * The one plugin-load retry policy: poll the remote entry until it is actually\n * served, then load with capped exponential backoff — purging the poisoned\n * global entry cache between attempts so each retry genuinely re-fetches.\n *\n * Recovery policy is `classifyPluginFailure().retryable`: transient network\n * conditions retry until the wall-clock budget runs out; permanent failures\n * (MF identity skew, schema validation, dead remotes, TLS verification) fail\n * fast on the first attempt instead of burning the budget silently.\n *\n * Fails with the ORIGINAL error from `load` — the host builds\n * `PluginBootstrapError.cause` from it and classification walks it.\n */\nexport const loadRemoteWithRetry = <T>(\n  options: PluginLoadRetryOptions<T>,\n): Effect.Effect<T, PluginRuntimeError> => {\n  const {\n    label,\n    remoteUrl,\n    load,\n    timeoutMs = DEFAULT_TIMEOUT_MS,\n    readinessTimeoutMs,\n    onAttempt,\n  } = options;\n  const readinessTimeout = readinessTimeoutMs ?? timeoutMs;\n\n  const schedule = Schedule.exponential(Duration.millis(RETRY_BASE_DELAY_MS)).pipe(\n    Schedule.modifyDelay(({ output }) =>\n      Effect.succeed(\n        Duration.toMillis(output) > RETRY_MAX_DELAY_MS\n          ? Duration.millis(RETRY_MAX_DELAY_MS)\n          : output,\n      ),\n    ),\n    Schedule.upTo({ duration: Duration.millis(timeoutMs) }),\n  );\n\n  let attempt = 0;\n  let lastSignature: string | undefined;\n  const reportFailure = (error: unknown): void => {\n    attempt += 1;\n    purgeRemoteEntryCache(remoteUrl);\n    const classification = classifyPluginFailure(error);\n    if (onAttempt) {\n      onAttempt(error, { attempt, classification });\n      return;\n    }\n    const signature = `${classification.kind}::${classification.message}`;\n    if (signature === lastSignature) return;\n    lastSignature = signature;\n    // The message alone is rarely enough, and the wrapper's own stack points\n    // at the wrapping frames — log the DEEPEST cause's stack (the original\n    // throw site inside the evaluated remote entry).\n    const stack = deepestErrorStack(error);\n    console.error(\n      `[Plugins][${label}] ❌ ${classification.kind} failure (attempt ${attempt}): ${classification.message}` +\n        (classification.suggestion ? `\\n[Plugins][${label}] → ${classification.suggestion}` : \"\") +\n        (stack ? `\\n[Plugins][${label}] ${stack}` : \"\"),\n    );\n  };\n\n  const loadWithRetry = Effect.tryPromise({\n    try: load,\n    catch: (error) => toPluginRuntimeError(error, label, undefined, \"remote-entry-load\"),\n  }).pipe(\n    Effect.tapError((error) => Effect.sync(() => reportFailure(error))),\n    Effect.retry({ schedule, while: (error) => classifyPluginFailure(error).retryable }),\n  );\n\n  // readinessTimeoutMs: 0 skips the cold-compile poll (tests stub `load` and\n  // must not race a 1ms wall-clock window against the event loop).\n  if (readinessTimeout === 0) {\n    return loadWithRetry;\n  }\n\n  return Effect.tryPromise({\n    try: () => waitForRemoteEntryReady(label, remoteUrl, readinessTimeout),\n    catch: (error) => toPluginRuntimeError(error, label, undefined, \"remote-entry-readiness\"),\n  }).pipe(Effect.flatMap(() => loadWithRetry));\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAoBA,MAAM,mBAAmB;AACzB,MAAM,qBAAqB;AAC3B,MAAM,sBAAsB;AAC5B,MAAM,qBAAqB;AAE3B,MAAa,SAAS,OACpB,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;;;;;;AAOlD,MAAa,yBAAyB,cAA4B;CAChE,MAAM,gBAAiB,WAAuC;CAG9D,IAAI,CAAC,eAAe;CACpB,KAAK,MAAM,OAAO,OAAO,KAAK,aAAa,GACzC,IAAI,IAAI,SAAS,IAAI,WAAW,GAAG,OAAO,cAAc;AAE5D;AAEA,MAAa,qBAAqB,SAChC,CAAC,8BAA8B,KAAK,KAAK,MAAM,GAAG,EAAE,CAAC;AAEvD,MAAa,0BAA0B,OACrC,OACA,KACA,YAAY,uBACM;CAClB,MAAM,WAAW,KAAK,IAAI,IAAI;CAC9B,IAAI,YAAY;CAChB,OAAO,KAAK,IAAI,IAAI,UAAU;EAC5B,MAAM,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,YAAY,IAAI;EAC7C,IAAI,KAAK,MAAM,kBAAkB,MAAM,IAAI,KAAK,CAAC,CAAC,YAAY,EAAE,CAAC,GAAG;EACpE,IAAI,CAAC,WAAW;GACd,YAAY;GACZ,QAAQ,IAAI,iBAAiB,MAAM,sCAAsC;EAC3E;EACA,MAAM,MAAM,gBAAgB;CAC9B;CACA,MAAM,IAAI,MAAM,GAAG,MAAM,sCAAsC,KAAK;AACtE;;;;;;;;;;;;;;AAyCA,MAAa,uBACX,YACyC;CACzC,MAAM,EACJ,OACA,WACA,MACA,YAAY,oBACZ,oBACA,cACE;CACJ,MAAM,mBAAmB,sBAAsB;CAE/C,MAAM,WAAWA,gBAAS,YAAYC,gBAAS,OAAO,mBAAmB,CAAC,CAAC,CAAC,KAC1ED,gBAAS,aAAa,EAAE,aACtBE,cAAO,QACLD,gBAAS,SAAS,MAAM,IAAI,qBACxBA,gBAAS,OAAO,kBAAkB,IAClC,MACN,CACF,GACAD,gBAAS,KAAK,EAAE,UAAUC,gBAAS,OAAO,SAAS,EAAE,CAAC,CACxD;CAEA,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,iBAAiB,UAAyB;EAC9C,WAAW;EACX,sBAAsB,SAAS;EAC/B,MAAM,iBAAiBE,qCAAsB,KAAK;EAClD,IAAI,WAAW;GACb,UAAU,OAAO;IAAE;IAAS;GAAe,CAAC;GAC5C;EACF;EACA,MAAM,YAAY,GAAG,eAAe,KAAK,IAAI,eAAe;EAC5D,IAAI,cAAc,eAAe;EACjC,gBAAgB;EAIhB,MAAM,QAAQC,iCAAkB,KAAK;EACrC,QAAQ,MACN,aAAa,MAAM,MAAM,eAAe,KAAK,oBAAoB,QAAQ,KAAK,eAAe,aAC1F,eAAe,aAAa,eAAe,MAAM,MAAM,eAAe,eAAe,OACrF,QAAQ,eAAe,MAAM,IAAI,UAAU,GAChD;CACF;CAEA,MAAM,gBAAgBF,cAAO,WAAW;EACtC,KAAK;EACL,QAAQ,UAAUG,oCAAqB,OAAO,OAAO,QAAW,mBAAmB;CACrF,CAAC,CAAC,CAAC,KACDH,cAAO,UAAU,UAAUA,cAAO,WAAW,cAAc,KAAK,CAAC,CAAC,GAClEA,cAAO,MAAM;EAAE;EAAU,QAAQ,UAAUC,qCAAsB,KAAK,CAAC,CAAC;CAAU,CAAC,CACrF;CAIA,IAAI,qBAAqB,GACvB,OAAO;CAGT,OAAOD,cAAO,WAAW;EACvB,WAAW,wBAAwB,OAAO,WAAW,gBAAgB;EACrE,QAAQ,UAAUG,oCAAqB,OAAO,OAAO,QAAW,wBAAwB;CAC1F,CAAC,CAAC,CAAC,KAAKH,cAAO,cAAc,aAAa,CAAC;AAC7C"}

package/dist/remote-entry.d.cts

@@ -0,0 +1,53 @@
+import { PluginFailureClassification, PluginRuntimeError } from "./runtime/errors.cjs";
+import { Effect } from "effect";
+//#region src/remote-entry.d.ts
+declare const sleep: (ms: number) => Promise<void>;
+/**
+ * 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.
+ */
+declare const purgeRemoteEntryCache: (remoteUrl: string) => void;
+declare const isRemoteEntryBody: (body: string) => boolean;
+declare const waitForRemoteEntryReady: (label: string, url: string, timeoutMs?: number) => Promise<void>;
+interface PluginLoadAttemptInfo {
+  attempt: number;
+  classification: PluginFailureClassification;
+}
+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.
+ */
+declare const loadRemoteWithRetry: <T>(options: PluginLoadRetryOptions<T>) => Effect.Effect<T, PluginRuntimeError>;
+//#endregion
+export { PluginLoadAttemptInfo, PluginLoadRetryOptions, isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, sleep, waitForRemoteEntryReady };
+//# sourceMappingURL=remote-entry.d.cts.map

package/dist/remote-entry.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-entry.d.cts","names":[],"sources":["../src/remote-entry.ts"],"mappings":";;;cAyBa,QAAK,eAAiB;;;;;;cAQtB,wBAAqB;cAUrB,oBAAiB;cAGjB,0BAAuB,eACrB,aACF,uBAEV;UAec;EACf;EACA,gBAAgB;;UAGD,uBAAuB;;EAEtC;EACA;EACA,YAAY,QAAQ;;EAEpB;;;;;;EAMA;;;;;;EAMA,cAAc,gBAAgB,MAAM;;;;;;;;;;;;;;;cAgBzB,sBAAuB,GAAC,SAC1B,uBAAuB,OAC/B,OAAO,OAAO,GAAG"}

package/dist/remote-entry.d.mts

@@ -0,0 +1,53 @@
+import { PluginFailureClassification, PluginRuntimeError } from "./runtime/errors.mjs";
+import { Effect } from "effect";
+//#region src/remote-entry.d.ts
+declare const sleep: (ms: number) => Promise<void>;
+/**
+ * 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.
+ */
+declare const purgeRemoteEntryCache: (remoteUrl: string) => void;
+declare const isRemoteEntryBody: (body: string) => boolean;
+declare const waitForRemoteEntryReady: (label: string, url: string, timeoutMs?: number) => Promise<void>;
+interface PluginLoadAttemptInfo {
+  attempt: number;
+  classification: PluginFailureClassification;
+}
+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.
+ */
+declare const loadRemoteWithRetry: <T>(options: PluginLoadRetryOptions<T>) => Effect.Effect<T, PluginRuntimeError>;
+//#endregion
+export { PluginLoadAttemptInfo, PluginLoadRetryOptions, isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, sleep, waitForRemoteEntryReady };
+//# sourceMappingURL=remote-entry.d.mts.map

package/dist/remote-entry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-entry.d.mts","names":[],"sources":["../src/remote-entry.ts"],"mappings":";;;cAyBa,QAAK,eAAiB;;;;;;cAQtB,wBAAqB;cAUrB,oBAAiB;cAGjB,0BAAuB,eACrB,aACF,uBAEV;UAec;EACf;EACA,gBAAgB;;UAGD,uBAAuB;;EAEtC;EACA;EACA,YAAY,QAAQ;;EAEpB;;;;;;EAMA;;;;;;EAMA,cAAc,gBAAgB,MAAM;;;;;;;;;;;;;;;cAgBzB,sBAAuB,GAAC,SAC1B,uBAAuB,OAC/B,OAAO,OAAO,GAAG"}

package/dist/remote-entry.mjs

@@ -0,0 +1,98 @@
+import { classifyPluginFailure, deepestErrorStack, toPluginRuntimeError } from "./runtime/errors.mjs";
+import { Duration, Effect, Schedule } from "effect";
+
+//#region src/remote-entry.ts
+/**
+* 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.
+*/
+const POLL_INTERVAL_MS = 300;
+const DEFAULT_TIMEOUT_MS = 12e4;
+const RETRY_BASE_DELAY_MS = 500;
+const RETRY_MAX_DELAY_MS = 5e3;
+const sleep = (ms) => 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.
+*/
+const purgeRemoteEntryCache = (remoteUrl) => {
+	const globalLoading = globalThis.__GLOBAL_LOADING_REMOTE_ENTRY__;
+	if (!globalLoading) return;
+	for (const key of Object.keys(globalLoading)) if (key.endsWith(`:${remoteUrl}`)) delete globalLoading[key];
+};
+const isRemoteEntryBody = (body) => !/not found|<(!doctype|html)/i.test(body.slice(0, 64));
+const waitForRemoteEntryReady = async (label, url, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+	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}`);
+};
+/**
+* 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.
+*/
+const loadRemoteWithRetry = (options) => {
+	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;
+	const reportFailure = (error) => {
+		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;
+		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, void 0, "remote-entry-load")
+	}).pipe(Effect.tapError((error) => Effect.sync(() => reportFailure(error))), Effect.retry({
+		schedule,
+		while: (error) => classifyPluginFailure(error).retryable
+	}));
+	if (readinessTimeout === 0) return loadWithRetry;
+	return Effect.tryPromise({
+		try: () => waitForRemoteEntryReady(label, remoteUrl, readinessTimeout),
+		catch: (error) => toPluginRuntimeError(error, label, void 0, "remote-entry-readiness")
+	}).pipe(Effect.flatMap(() => loadWithRetry));
+};
+
+//#endregion
+export { isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, sleep, waitForRemoteEntryReady };
+//# sourceMappingURL=remote-entry.mjs.map