every-plugin 3.0.0-rc.0 → 3.0.0-rc.11

package/dist/index.mjs

@@ -1,9 +1,10 @@
+import { createRpcClient } from "./client.mjs";
 import { buildScoped, buildScopedContext } from "./effect-helpers.mjs";
-import { ModuleFederationError, PluginRuntimeError, ValidationError, classifyPluginFailure, extractFromFiberFailure, formatORPCError, toPluginRuntimeError, wrapORPCError } from "./runtime/errors.mjs";
+import { ModuleFederationError, PluginRuntimeError, ValidationError, classifyPluginFailure, defaultMissingSecretWarnings, extractFromFiberFailure, formatORPCError, toPluginRuntimeError, wrapORPCError } from "./runtime/errors.mjs";
 import { BAD_REQUEST, CONNECTION_ERROR, FORBIDDEN, NOT_FOUND, PLUGIN_ERROR_STATUS_MAP, PluginErrors, RATE_LIMITED, SERVICE_UNAVAILABLE, TIMEOUT, UNAUTHORIZED } from "./errors.mjs";
 import { PluginIdTag, createPlugin, withPlugins } from "./plugin.mjs";
 import { remoteName } from "./identity.mjs";
 import { PluginRuntime, createPluginRuntime } from "./runtime/index.mjs";
 import "@orpc/openapi/extensions/route";
 
-export { BAD_REQUEST, CONNECTION_ERROR, FORBIDDEN, ModuleFederationError, NOT_FOUND, PLUGIN_ERROR_STATUS_MAP, PluginErrors, PluginIdTag, PluginRuntime, PluginRuntimeError, RATE_LIMITED, SERVICE_UNAVAILABLE, TIMEOUT, UNAUTHORIZED, ValidationError, buildScoped, buildScopedContext, classifyPluginFailure, createPlugin, createPluginRuntime, extractFromFiberFailure, formatORPCError, remoteName as getNormalizedRemoteName, toPluginRuntimeError, withPlugins, wrapORPCError };
+export { BAD_REQUEST, CONNECTION_ERROR, FORBIDDEN, ModuleFederationError, NOT_FOUND, PLUGIN_ERROR_STATUS_MAP, PluginErrors, PluginIdTag, PluginRuntime, PluginRuntimeError, RATE_LIMITED, SERVICE_UNAVAILABLE, TIMEOUT, UNAUTHORIZED, ValidationError, buildScoped, buildScopedContext, classifyPluginFailure, createPlugin, createPluginRuntime, createRpcClient, defaultMissingSecretWarnings, extractFromFiberFailure, formatORPCError, remoteName as getNormalizedRemoteName, toPluginRuntimeError, withPlugins, wrapORPCError };

package/dist/plugin.cjs

@@ -17,6 +17,7 @@ const createPlugin = function createPlugin(config) {
 		contract = config.contract;
 		configSchema = configSchema;
 		servicesTag = config.servicesTag;
+		warnings = config.warnings;
 		initialize(pluginConfig, plugins = {}) {
 			const init = config.initialize;
 			if (!init) return effect.Effect.succeed(effect.Layer.empty);

package/dist/plugin.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.cjs","names":["Context","Effect","Layer","toPluginRuntimeError","implement"],"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 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\ntype PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {\n  variables: InferSchemaOutput<V>;\n  secrets: InferSchemaOutput<S>;\n};\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   * 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\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\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":";;;;;;AA0BA,IAAa,cAAb,cAAiCA,eAAQ,QAA6B,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;AAiHrF,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;EAE9B,WACE,cACA,UAAmC,CAAC,GAC8C;GAClF,MAAM,OAAO,OAAO;GACpB,IAAI,CAAC,MACH,OAAOC,cAAO,QAAQC,aAAM,KAAsD;GAGpF,OAAO,KAAK,cAAc,OAAY,CAAC,CAAC,KACtCD,cAAO,UAAU,UACfE,oCAAqB,OAAO,KAAK,IAAI,QAAW,mBAAmB,CACrE,CACF;EACF;EAEA,aAAa,SAAoE;GAC/E,MAAM,cAAUC,wBAAU,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"}
+{"version":3,"file":"plugin.cjs","names":["Context","Effect","Layer","toPluginRuntimeError","implement"],"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  /**\n   * The framework-assigned plugin id — the same key the host uses for secret\n   * injection and per-plugin database namespacing. Arrives as a value so\n   * plugin code never needs the ambient `PluginIdTag`.\n   */\n  pluginId: string;\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":";;;;;;AA0CA,IAAa,cAAb,cAAiCA,eAAQ,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,OAAOC,cAAO,QAAQC,aAAM,KAAsD;GAGpF,OAAO,KAAK,cAAc,OAAY,CAAC,CAAC,KACtCD,cAAO,UAAU,UACfE,oCAAqB,OAAO,KAAK,IAAI,QAAW,mBAAmB,CACrE,CACF;EACF;EAEA,aAAa,SAAoE;GAC/E,MAAM,cAAUC,wBAAU,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/plugin.d.cts

@@ -1,7 +1,7 @@
-import { PluginRuntimeError } from "./runtime/errors.cjs";
+import { PluginRuntimeError, PluginWarningInfo } from "./runtime/errors.cjs";
+import { AnyContractRouter, AnySchema, InferSchemaOutput } from "@orpc/contract";
 import { ContractedRouter, Implementer } from "@orpc/server";
 import { Context, Effect, Layer, Scope } from "effect";
-import { AnyContractRouter, AnySchema, InferSchemaOutput } from "@orpc/contract";
 import { WithEffectContext } from "@orpc/experimental-effect";
 import "@orpc/experimental-effect/extensions/effect";
 //#region src/plugin.d.ts
@@ -12,9 +12,21 @@ type PluginConfigFor<V extends AnySchema, S extends AnySchema, TRequestContext e
   context: TRequestContext;
 };
 type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+  /**
+   * The framework-assigned plugin id — the same key the host uses for secret
+   * injection and per-plugin database namespacing. Arrives as a value so
+   * plugin code never needs the ambient `PluginIdTag`.
+   */
+  pluginId: string;
   variables: InferSchemaOutput<V>;
   secrets: InferSchemaOutput<S>;
 };
+/**
+ * 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 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 {}
 /**
@@ -34,6 +46,13 @@ type PluginDefinition<V extends AnySchema, S extends AnySchema, TContract extend
    * 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`.
    *
@@ -73,6 +92,7 @@ interface Plugin<TContract extends AnyContractRouter, TVariables extends AnySche
   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>): Effect.Effect<Layer.Layer<any, Error, PluginEnv>, PluginRuntimeError, PluginEnv>;
   /**
    * Creates the strongly-typed oRPC router for this plugin.
@@ -91,5 +111,5 @@ 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>(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, PluginEnv, PluginIdTag, createPlugin, withPlugins };
+export { CreatePluginFn, CreatePluginWithPlugins, LoadedPluginWithBinding, Plugin, PluginConfigFor, PluginEnv, PluginIdTag, PluginInitializeInput, PluginWarningsFn, createPlugin, withPlugins };
 //# sourceMappingURL=plugin.d.cts.map

package/dist/plugin.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.cts","names":[],"sources":["../src/plugin.ts"],"mappings":";;;;;;;KASK,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;;;cAGhB,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;;;;;;;;;EAStB,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;EAE/B,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;KAkEf,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"}
+{"version":3,"file":"plugin.d.cts","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;;;;;;EAM/D;EACA,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.d.mts

@@ -1,4 +1,4 @@
-import { PluginRuntimeError } from "./runtime/errors.mjs";
+import { PluginRuntimeError, PluginWarningInfo } from "./runtime/errors.mjs";
 import { Context, Effect, Layer, Scope } from "effect";
 import { ContractedRouter, Implementer } from "@orpc/server";
 import "@orpc/experimental-effect/extensions/effect";
@@ -12,9 +12,21 @@ type PluginConfigFor<V extends AnySchema, S extends AnySchema, TRequestContext e
   context: TRequestContext;
 };
 type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+  /**
+   * The framework-assigned plugin id — the same key the host uses for secret
+   * injection and per-plugin database namespacing. Arrives as a value so
+   * plugin code never needs the ambient `PluginIdTag`.
+   */
+  pluginId: string;
   variables: InferSchemaOutput<V>;
   secrets: InferSchemaOutput<S>;
 };
+/**
+ * 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 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 {}
 /**
@@ -34,6 +46,13 @@ type PluginDefinition<V extends AnySchema, S extends AnySchema, TContract extend
    * 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`.
    *
@@ -73,6 +92,7 @@ interface Plugin<TContract extends AnyContractRouter, TVariables extends AnySche
   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>): Effect.Effect<Layer.Layer<any, Error, PluginEnv>, PluginRuntimeError, PluginEnv>;
   /**
    * Creates the strongly-typed oRPC router for this plugin.
@@ -91,5 +111,5 @@ 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>(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, PluginEnv, PluginIdTag, 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":";;;;;;;KASK,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;;;cAGhB,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;;;;;;;;;EAStB,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;EAE/B,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;KAkEf,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"}
+{"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;;;;;;EAM/D;EACA,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

@@ -17,6 +17,7 @@ const createPlugin = function createPlugin(config) {
 		contract = config.contract;
 		configSchema = configSchema;
 		servicesTag = config.servicesTag;
+		warnings = config.warnings;
 		initialize(pluginConfig, plugins = {}) {
 			const init = config.initialize;
 			if (!init) return Effect.succeed(Layer.empty);

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 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 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\ntype PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {\n  variables: InferSchemaOutput<V>;\n  secrets: InferSchemaOutput<S>;\n};\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   * 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\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\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":";;;;;;AA0BA,IAAa,cAAb,cAAiC,QAAQ,QAA6B,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;AAiHrF,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;EAE9B,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"}
+{"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  /**\n   * The framework-assigned plugin id — the same key the host uses for secret\n   * injection and per-plugin database namespacing. Arrives as a value so\n   * plugin code never needs the ambient `PluginIdTag`.\n   */\n  pluginId: string;\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":";;;;;;AA0CA,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

@@ -98,6 +98,5 @@ const loadRemoteWithRetry = (options) => {
 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

@@ -1 +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"}
+{"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\nconst sleep = (ms: number): Promise<void> => 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,MAAM,SAAS,OAA8B,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;;;;;;AAO7F,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

@@ -1,7 +1,6 @@
 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
@@ -49,5 +48,5 @@ interface PluginLoadRetryOptions<T> {
  */
 declare const loadRemoteWithRetry: <T>(options: PluginLoadRetryOptions<T>) => Effect.Effect<T, PluginRuntimeError>;
 //#endregion
-export { PluginLoadAttemptInfo, PluginLoadRetryOptions, isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, sleep, waitForRemoteEntryReady };
+export { PluginLoadAttemptInfo, PluginLoadRetryOptions, isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, waitForRemoteEntryReady };
 //# sourceMappingURL=remote-entry.d.cts.map

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

@@ -1 +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"}
+{"version":3,"file":"remote-entry.d.cts","names":[],"sources":["../src/remote-entry.ts"],"mappings":";;;;;;;;cAgCa,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

@@ -1,7 +1,6 @@
 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
@@ -49,5 +48,5 @@ interface PluginLoadRetryOptions<T> {
  */
 declare const loadRemoteWithRetry: <T>(options: PluginLoadRetryOptions<T>) => Effect.Effect<T, PluginRuntimeError>;
 //#endregion
-export { PluginLoadAttemptInfo, PluginLoadRetryOptions, isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, sleep, waitForRemoteEntryReady };
+export { PluginLoadAttemptInfo, PluginLoadRetryOptions, isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, waitForRemoteEntryReady };
 //# sourceMappingURL=remote-entry.d.mts.map

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

@@ -1 +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"}
+{"version":3,"file":"remote-entry.d.mts","names":[],"sources":["../src/remote-entry.ts"],"mappings":";;;;;;;;cAgCa,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

@@ -94,5 +94,5 @@ const loadRemoteWithRetry = (options) => {
 };
 
 //#endregion
-export { isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, sleep, waitForRemoteEntryReady };
+export { isRemoteEntryBody, loadRemoteWithRetry, purgeRemoteEntryCache, waitForRemoteEntryReady };
 //# sourceMappingURL=remote-entry.mjs.map

package/dist/remote-entry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"remote-entry.mjs","names":[],"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,WAAW,SAAS,YAAY,SAAS,OAAO,mBAAmB,CAAC,CAAC,CAAC,KAC1E,SAAS,aAAa,EAAE,aACtB,OAAO,QACL,SAAS,SAAS,MAAM,IAAI,qBACxB,SAAS,OAAO,kBAAkB,IAClC,MACN,CACF,GACA,SAAS,KAAK,EAAE,UAAU,SAAS,OAAO,SAAS,EAAE,CAAC,CACxD;CAEA,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,iBAAiB,UAAyB;EAC9C,WAAW;EACX,sBAAsB,SAAS;EAC/B,MAAM,iBAAiB,sBAAsB,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,QAAQ,kBAAkB,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,gBAAgB,OAAO,WAAW;EACtC,KAAK;EACL,QAAQ,UAAU,qBAAqB,OAAO,OAAO,QAAW,mBAAmB;CACrF,CAAC,CAAC,CAAC,KACD,OAAO,UAAU,UAAU,OAAO,WAAW,cAAc,KAAK,CAAC,CAAC,GAClE,OAAO,MAAM;EAAE;EAAU,QAAQ,UAAU,sBAAsB,KAAK,CAAC,CAAC;CAAU,CAAC,CACrF;CAIA,IAAI,qBAAqB,GACvB,OAAO;CAGT,OAAO,OAAO,WAAW;EACvB,WAAW,wBAAwB,OAAO,WAAW,gBAAgB;EACrE,QAAQ,UAAU,qBAAqB,OAAO,OAAO,QAAW,wBAAwB;CAC1F,CAAC,CAAC,CAAC,KAAK,OAAO,cAAc,aAAa,CAAC;AAC7C"}
+{"version":3,"file":"remote-entry.mjs","names":[],"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\nconst sleep = (ms: number): Promise<void> => 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,MAAM,SAAS,OAA8B,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;;;;;;AAO7F,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,WAAW,SAAS,YAAY,SAAS,OAAO,mBAAmB,CAAC,CAAC,CAAC,KAC1E,SAAS,aAAa,EAAE,aACtB,OAAO,QACL,SAAS,SAAS,MAAM,IAAI,qBACxB,SAAS,OAAO,kBAAkB,IAClC,MACN,CACF,GACA,SAAS,KAAK,EAAE,UAAU,SAAS,OAAO,SAAS,EAAE,CAAC,CACxD;CAEA,IAAI,UAAU;CACd,IAAI;CACJ,MAAM,iBAAiB,UAAyB;EAC9C,WAAW;EACX,sBAAsB,SAAS;EAC/B,MAAM,iBAAiB,sBAAsB,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,QAAQ,kBAAkB,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,gBAAgB,OAAO,WAAW;EACtC,KAAK;EACL,QAAQ,UAAU,qBAAqB,OAAO,OAAO,QAAW,mBAAmB;CACrF,CAAC,CAAC,CAAC,KACD,OAAO,UAAU,UAAU,OAAO,WAAW,cAAc,KAAK,CAAC,CAAC,GAClE,OAAO,MAAM;EAAE;EAAU,QAAQ,UAAU,sBAAsB,KAAK,CAAC,CAAC;CAAU,CAAC,CACrF;CAIA,IAAI,qBAAqB,GACvB,OAAO;CAGT,OAAO,OAAO,WAAW;EACvB,WAAW,wBAAwB,OAAO,WAAW,gBAAgB;EACrE,QAAQ,UAAU,qBAAqB,OAAO,OAAO,QAAW,wBAAwB;CAC1F,CAAC,CAAC,CAAC,KAAK,OAAO,cAAc,aAAa,CAAC;AAC7C"}

package/dist/runtime/errors.cjs

@@ -148,6 +148,25 @@ const formatORPCError = (error) => {
 	lines.push(`╰${"─".repeat(50)}\n`);
 	return lines.join("\n");
 };
+/**
+* The loader's default warning policy for declared-but-unset secrets: a
+* successfully initialized plugin whose declared secret names resolved to
+* nothing (missing or empty in the environment) gets one consolidated
+* warning. `*_DATABASE_URL` keys are excluded — they have the shared-API-DB
+* fallback, and a genuinely-missing DB URL fails initialization (a `failure`,
+* not a warning). A plugin that declares its own `warnings` function opts out
+* of this default.
+*/
+const defaultMissingSecretWarnings = (pluginKey, declaredKeys, resolvedKeys) => {
+	const resolved = new Set(resolvedKeys);
+	const missing = declaredKeys.filter((key) => !resolved.has(key) && !key.endsWith("_DATABASE_URL"));
+	if (missing.length === 0) return [];
+	return [{
+		pluginKey,
+		message: missing.length === 1 ? `Declared secret ${missing[0]} is not set — features depending on it are disabled` : `${missing.length} declared secrets are not set: ${missing.join(", ")} — features depending on them are disabled`,
+		hint: "Set the secret(s) in your environment (.env in development); see the plugin's config schema for what each enables"
+	}];
+};
 const NETWORK_RETRYABLE_PATTERNS = [
 	"ETIMEDOUT",
 	"ECONNRESET",
@@ -271,6 +290,7 @@ exports.PluginRuntimeError = PluginRuntimeError;
 exports.ValidationError = ValidationError;
 exports.classifyPluginFailure = classifyPluginFailure;
 exports.deepestErrorStack = deepestErrorStack;
+exports.defaultMissingSecretWarnings = defaultMissingSecretWarnings;
 exports.extractFromFiberFailure = extractFromFiberFailure;
 exports.formatORPCError = formatORPCError;
 exports.toPluginRuntimeError = toPluginRuntimeError;

package/dist/runtime/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","names":["Data","ORPCError","Cause"],"sources":["../../src/runtime/errors.ts"],"sourcesContent":["import { ORPCError } from \"@orpc/server\";\nimport { Cause, Data } from \"effect\";\nimport type { z } from \"zod\";\n\nexport class PluginRuntimeError extends Data.TaggedError(\"PluginRuntimeError\")<{\n  readonly pluginId?: string;\n  readonly operation?: string;\n  readonly procedureName?: string;\n  readonly cause?: Error;\n}> {\n  override get message() {\n    return this.cause?.message ?? \"Plugin operation failed\";\n  }\n}\n\nexport class ModuleFederationError extends Data.TaggedError(\"ModuleFederationError\")<{\n  readonly pluginId: string;\n  readonly remoteUrl: string;\n  readonly cause?: Error;\n}> {}\n\nexport class ValidationError extends Data.TaggedError(\"ValidationError\")<{\n  readonly pluginId: string;\n  readonly stage: \"config\" | \"input\" | \"output\" | \"state\";\n  readonly zodError: z.ZodError;\n}> {}\n\nconst stringifyUnknown = (value: unknown): string => {\n  if (value === null) return \"null\";\n  if (value === undefined) return \"undefined\";\n  if (value instanceof Error) return value.message;\n  if (typeof value === \"string\") return value;\n  if (typeof value === \"number\" || typeof value === \"bigint\" || typeof value === \"boolean\") {\n    return `${value}`;\n  }\n  if (typeof value === \"symbol\") return value.description ?? \"\";\n  try {\n    return JSON.stringify(value) ?? \"[Unserializable value]\";\n  } catch {\n    return \"[Unserializable value]\";\n  }\n};\n\nconst extractErrorMessage = (error: unknown): string => {\n  if (!error) return \"Unknown error\";\n\n  if (error instanceof Error) {\n    if (error.message) return error.message;\n    if ((error as any).cause instanceof Error) {\n      return extractErrorMessage((error as any).cause);\n    }\n  }\n\n  if (error instanceof AggregateError && error.errors?.length) {\n    return error.errors.map((e) => extractErrorMessage(e)).join(\"; \");\n  }\n\n  if (typeof error === \"object\" && \"message\" in error) {\n    return String((error as any).message);\n  }\n\n  return stringifyUnknown(error);\n};\n\n/**\n * The deepest Error along the cause chain — the original throw site. Wrapper\n * errors (PluginRuntimeError, ModuleFederationError) carry their own stacks\n * (the wrapping frames); diagnosis needs the cause's stack (the actual\n * failing module inside the evaluated remote entry).\n */\nexport const deepestErrorStack = (error: unknown): string | undefined => {\n  let current = error;\n  let deepest: string | undefined;\n  let hops = 0;\n  while (current instanceof Error && hops < 8) {\n    if (current.stack) deepest = current.stack;\n    current = (current as { cause?: unknown }).cause as unknown;\n    hops += 1;\n  }\n  if (current instanceof Error && current.stack) deepest = current.stack;\n  return deepest;\n};\n\nconst formatValidationIssue = (issue: any, index: number, maxDisplay: number): string => {\n  if (index >= maxDisplay) return \"\";\n\n  const path =\n    Array.isArray(issue.path) && issue.path.length > 0\n      ? issue.path.join(\".\")\n      : issue.path || \"root\";\n\n  const message = issue.message || \"Validation failed\";\n\n  return `│    ${index + 1}. ${path}: ${message}`;\n};\n\nconst formatDataPreview = (data: unknown, maxLength = 100): string => {\n  if (!data) return \"undefined\";\n\n  try {\n    const str = JSON.stringify(data);\n    if (str.length <= maxLength) return str;\n\n    if (typeof data === \"object\" && data !== null) {\n      if (Array.isArray(data)) {\n        return `Array(${data.length}) [...]`;\n      }\n      const keys = Object.keys(data);\n      return `{ ${keys.slice(0, 3).join(\", \")}${keys.length > 3 ? \", ...\" : \"\"} }`;\n    }\n\n    return `${str.slice(0, maxLength)}...`;\n  } catch {\n    return stringifyUnknown(data).slice(0, maxLength);\n  }\n};\n\nconst formatORPCValidationError = (error: any): string[] | null => {\n  const cause = error?.cause || error;\n\n  if (!cause?.issues || !Array.isArray(cause.issues) || cause.issues.length === 0) {\n    return null;\n  }\n\n  const lines: string[] = [];\n  const errorType = error?.message || cause?.message || \"Validation failed\";\n\n  lines.push(`\\n╭─ oRPC Validation Error ${\"─\".repeat(30)}`);\n  lines.push(`│  ${errorType}`);\n  lines.push(`│`);\n\n  const maxDisplay = 10;\n  const totalIssues = cause.issues.length;\n\n  lines.push(`│  Issues (${totalIssues}):`);\n\n  const displayedIssues = cause.issues.slice(0, maxDisplay);\n  displayedIssues.forEach((issue: any, idx: number) => {\n    const formatted = formatValidationIssue(issue, idx, maxDisplay);\n    if (formatted) lines.push(formatted);\n  });\n\n  if (totalIssues > maxDisplay) {\n    lines.push(`│    ... and ${totalIssues - maxDisplay} more`);\n  }\n\n  if (cause.data !== undefined) {\n    lines.push(`│`);\n    lines.push(`│  Data preview: ${formatDataPreview(cause.data, 80)}`);\n  }\n\n  lines.push(`╰${\"─\".repeat(50)}\\n`);\n\n  return lines;\n};\n\nconst formatUnknownError = (error: any): string | null => {\n  if (!error) return null;\n  const message = extractErrorMessage(error);\n  const lines: string[] = [];\n  lines.push(`\\n╭─ Unhandled error ${\"─\".repeat(37)}`);\n  for (const line of message.split(\"\\n\")) {\n    lines.push(`│  ${line}`);\n  }\n  const stack = error instanceof Error ? error.stack?.split(\"\\n\").slice(1, 6) : undefined;\n  if (stack && stack.length > 0) {\n    lines.push(`│`);\n    for (const line of stack) {\n      lines.push(`│  ${line.trim()}`);\n    }\n  }\n  lines.push(`╰${\"─\".repeat(50)}\\n`);\n  return lines.join(\"\\n\");\n};\n\nexport const formatORPCError = (error: any): string | null => {\n  if (!(error instanceof ORPCError)) {\n    // Unknown errors used to return null, leaving internal failures (e.g. a\n    // storage backend throw) invisible in host logs while oRPC serialized\n    // them client-side as a bare INTERNAL_SERVER_ERROR.\n    return formatUnknownError(error);\n  }\n\n  const validationLines = formatORPCValidationError(error);\n  if (validationLines) {\n    return validationLines.join(\"\\n\");\n  }\n\n  const lines: string[] = [];\n  const code = error.code || \"UNKNOWN\";\n  const message = error.message || \"An error occurred\";\n\n  lines.push(`\\n╭─ oRPC Error ${\"─\".repeat(40)}`);\n  const messageLines = message.split(\"\\n\");\n  for (const line of messageLines) {\n    lines.push(`│  ${line}`);\n  }\n  lines.push(`│  Code: ${code}`);\n  lines.push(`│`);\n\n  if (error.data) {\n    const dataType = typeof error.data;\n    if (dataType === \"object\" && error.data !== null) {\n      if (\"retryAfter\" in error.data) {\n        lines.push(`│  Retry after: ${error.data.retryAfter} seconds`);\n      }\n      if (\"remainingRequests\" in error.data) {\n        lines.push(`│  Remaining: ${error.data.remainingRequests} requests`);\n      }\n      if (\"host\" in error.data) {\n        lines.push(`│  Host: ${error.data.host}`);\n      }\n      if (\"port\" in error.data) {\n        lines.push(`│  Port: ${error.data.port}`);\n      }\n      if (\"suggestion\" in error.data) {\n        lines.push(`│  → ${error.data.suggestion}`);\n      }\n      if (\"resource\" in error.data) {\n        lines.push(`│  Resource: ${error.data.resource}`);\n      }\n      if (\"resourceId\" in error.data) {\n        lines.push(`│  ID: ${error.data.resourceId}`);\n      }\n    }\n  }\n\n  switch (code) {\n    case \"UNAUTHORIZED\":\n      lines.push(`│  → Check your API key or credentials`);\n      break;\n    case \"TOO_MANY_REQUESTS\":\n      lines.push(`│  → Wait before retrying`);\n      break;\n    case \"SERVICE_UNAVAILABLE\":\n    case \"BAD_GATEWAY\":\n    case \"GATEWAY_TIMEOUT\":\n      lines.push(`│  → The service may be temporarily unavailable`);\n      break;\n    case \"TIMEOUT\":\n      lines.push(`│  → The operation took too long`);\n      break;\n  }\n\n  lines.push(`╰${\"─\".repeat(50)}\\n`);\n  return lines.join(\"\\n\");\n};\n\nexport type PluginFailureKind =\n  | \"mf\"\n  | \"integrity\"\n  | \"config\"\n  | \"validation\"\n  | \"network\"\n  | \"unknown\";\n\nexport interface PluginFailureClassification {\n  kind: PluginFailureKind;\n  retryable: boolean;\n  message: string;\n  suggestion?: string;\n}\n\n/**\n * Structured report of one plugin-load failure, built by a loader (the host's\n * plugin boot, the dev server) from a `PluginFailureClassification` plus\n * loader context. This is the shape health endpoints and dashboards consume —\n * keep it serializable.\n */\nexport interface PluginLoadFailureInfo {\n  /** loader-side key (host entry key, dev plugin id) */\n  pluginKey: string;\n  pluginUrl?: string;\n  /** failing runtime stage when the cause is stage-attributed */\n  operation?: string;\n  kind: string;\n  retryable: boolean;\n  message: string;\n  suggestion?: string;\n  /** loader context: which env secret the plugin's DB binding expects */\n  dbSecret?: string;\n  dbUrlMasked?: string;\n}\n\nconst NETWORK_RETRYABLE_PATTERNS = [\"ETIMEDOUT\", \"ECONNRESET\", \"timeout\", \"503\", \"429\"] as const;\nconst NETWORK_DEAD_PATTERNS = [\"ECONNREFUSED\", \"ENOTFOUND\", \"EHOSTUNREACH\"] as const;\nconst RETRYABLE_ORPC_CODES = new Set([\n  \"TOO_MANY_REQUESTS\",\n  \"SERVICE_UNAVAILABLE\",\n  \"BAD_GATEWAY\",\n  \"GATEWAY_TIMEOUT\",\n  \"TIMEOUT\",\n]);\n\n/**\n * One classification for plugin lifecycle failures across MF / validation /\n * network sources. This is the recovery policy — nothing in the runtime\n * retries on it today by design (the host degrades and runs without a failed\n * plugin); consumers (host bootstrap messages, the dev server retry loop)\n * read kind / retryable / suggestion to decide what to tell the author.\n */\nexport const classifyPluginFailure = (error: unknown): PluginFailureClassification => {\n  let current: unknown = extractFromFiberFailure(error);\n  let hops = 0;\n  while (current && typeof current === \"object\" && hops < 8) {\n    if (current instanceof ModuleFederationError) {\n      return {\n        kind: \"mf\",\n        retryable: false,\n        message: extractErrorMessage(current),\n        suggestion:\n          \"Run bos mf check — the deployed plugin bundle is likely stale (sharedDep / pluginVersion skew), then redeploy the plugin and bos publish --deploy --packages local\",\n      };\n    }\n    if (current instanceof ValidationError) {\n      return {\n        kind: \"validation\",\n        retryable: false,\n        message: `${current.stage}: ${extractErrorMessage(current.zodError)}`,\n        suggestion: `Fix the plugin's ${current.stage} schema at plugins/${current.pluginId}`,\n      };\n    }\n    if (current instanceof ORPCError) {\n      const retryableByCode = RETRYABLE_ORPC_CODES.has(current.code);\n      return {\n        kind: \"network\",\n        retryable: retryableByCode,\n        message: current.message,\n        suggestion: retryableByCode\n          ? \"The plugin procedure failed transiently — retry the call\"\n          : undefined,\n      };\n    }\n    current = (current as { cause?: unknown }).cause;\n    hops += 1;\n  }\n\n  const message = extractErrorMessage(error);\n  const lower = message.toLowerCase();\n\n  if (NETWORK_RETRYABLE_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) {\n    return {\n      kind: \"network\",\n      retryable: true,\n      message,\n      suggestion: \"The remote may be temporarily unavailable — retry after redeploying the plugin\",\n    };\n  }\n  if (NETWORK_DEAD_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) {\n    return {\n      kind: \"network\",\n      retryable: false,\n      message,\n      suggestion:\n        \"The plugin host is unreachable — check plugins.<id> entry URLs in bos.config.json\",\n    };\n  }\n  if (lower.includes(\"integrity\") || lower.includes(\"sri\")) {\n    return {\n      kind: \"integrity\",\n      retryable: true,\n      message,\n      suggestion:\n        \"The deployed bundle content does not match its recorded integrity — redeploy the plugin so bos.config.json is republished with a fresh hash\",\n    };\n  }\n\n  return { kind: \"unknown\", retryable: false, message };\n};\n\n// Convert ORPC errors from plugin procedures to PluginRuntimeError\nexport const wrapORPCError = (\n  orpcError: ORPCError<string, unknown>,\n  pluginId?: string,\n  procedureName?: string,\n  operation?: string,\n): PluginRuntimeError => {\n  return new PluginRuntimeError({\n    pluginId,\n    operation,\n    procedureName,\n    cause: orpcError as Error,\n  });\n};\n\n/**\n * Extracts the underlying error from Effect's FiberFailure wrapper.\n * When Effect.runPromise rejects, errors are wrapped in FiberFailure.\n * This extracts the original error so oRPC can handle it properly.\n */\nexport const extractFromFiberFailure = (error: unknown): unknown => {\n  if (!error || typeof error !== \"object\") return error;\n\n  if (\"cause\" in error) {\n    const cause = (error as { cause?: unknown }).cause;\n\n    if (cause && typeof cause === \"object\" && \"_tag\" in cause) {\n      try {\n        const squashed = Cause.squash(cause as unknown as Cause.Cause<unknown>);\n        if (squashed instanceof ORPCError) {\n          return squashed;\n        }\n        return squashed;\n      } catch {\n        // Not a valid Cause\n      }\n    }\n\n    if (cause instanceof ORPCError) {\n      return cause;\n    }\n  }\n\n  return error;\n};\n\n// Universal error converter for the runtime\nexport const toPluginRuntimeError = (\n  error: unknown,\n  pluginId?: string,\n  procedureName?: string,\n  operation?: string,\n): PluginRuntimeError => {\n  if (error instanceof ORPCError) {\n    return wrapORPCError(error, pluginId, procedureName, operation);\n  }\n\n  if (error instanceof PluginRuntimeError) {\n    return error;\n  }\n\n  return new PluginRuntimeError({\n    pluginId,\n    operation,\n    procedureName,\n    cause: error instanceof Error ? error : new Error(extractErrorMessage(error)),\n  });\n};\n"],"mappings":";;;;AAIA,IAAa,qBAAb,cAAwCA,YAAK,YAAY,oBAAoB,CAAC,CAK3E;CACD,IAAa,UAAU;EACrB,OAAO,KAAK,OAAO,WAAW;CAChC;AACF;AAEA,IAAa,wBAAb,cAA2CA,YAAK,YAAY,uBAAuB,CAAC,CAIjF,CAAC;AAEJ,IAAa,kBAAb,cAAqCA,YAAK,YAAY,iBAAiB,CAAC,CAIrE,CAAC;AAEJ,MAAM,oBAAoB,UAA2B;CACnD,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,UAAU,QAAW,OAAO;CAChC,IAAI,iBAAiB,OAAO,OAAO,MAAM;CACzC,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,OAAO,UAAU,YAAY,OAAO,UAAU,YAAY,OAAO,UAAU,WAC7E,OAAO,GAAG;CAEZ,IAAI,OAAO,UAAU,UAAU,OAAO,MAAM,eAAe;CAC3D,IAAI;EACF,OAAO,KAAK,UAAU,KAAK,KAAK;CAClC,QAAQ;EACN,OAAO;CACT;AACF;AAEA,MAAM,uBAAuB,UAA2B;CACtD,IAAI,CAAC,OAAO,OAAO;CAEnB,IAAI,iBAAiB,OAAO;EAC1B,IAAI,MAAM,SAAS,OAAO,MAAM;EAChC,IAAK,MAAc,iBAAiB,OAClC,OAAO,oBAAqB,MAAc,KAAK;CAEnD;CAEA,IAAI,iBAAiB,kBAAkB,MAAM,QAAQ,QACnD,OAAO,MAAM,OAAO,KAAK,MAAM,oBAAoB,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;CAGlE,IAAI,OAAO,UAAU,YAAY,aAAa,OAC5C,OAAO,OAAQ,MAAc,OAAO;CAGtC,OAAO,iBAAiB,KAAK;AAC/B;;;;;;;AAQA,MAAa,qBAAqB,UAAuC;CACvE,IAAI,UAAU;CACd,IAAI;CACJ,IAAI,OAAO;CACX,OAAO,mBAAmB,SAAS,OAAO,GAAG;EAC3C,IAAI,QAAQ,OAAO,UAAU,QAAQ;EACrC,UAAW,QAAgC;EAC3C,QAAQ;CACV;CACA,IAAI,mBAAmB,SAAS,QAAQ,OAAO,UAAU,QAAQ;CACjE,OAAO;AACT;AAEA,MAAM,yBAAyB,OAAY,OAAe,eAA+B;CACvF,IAAI,SAAS,YAAY,OAAO;CAEhC,MAAM,OACJ,MAAM,QAAQ,MAAM,IAAI,KAAK,MAAM,KAAK,SAAS,IAC7C,MAAM,KAAK,KAAK,GAAG,IACnB,MAAM,QAAQ;CAEpB,MAAM,UAAU,MAAM,WAAW;CAEjC,OAAO,QAAQ,QAAQ,EAAE,IAAI,KAAK,IAAI;AACxC;AAEA,MAAM,qBAAqB,MAAe,YAAY,QAAgB;CACpE,IAAI,CAAC,MAAM,OAAO;CAElB,IAAI;EACF,MAAM,MAAM,KAAK,UAAU,IAAI;EAC/B,IAAI,IAAI,UAAU,WAAW,OAAO;EAEpC,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM;GAC7C,IAAI,MAAM,QAAQ,IAAI,GACpB,OAAO,SAAS,KAAK,OAAO;GAE9B,MAAM,OAAO,OAAO,KAAK,IAAI;GAC7B,OAAO,KAAK,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,SAAS,IAAI,UAAU,GAAG;EAC3E;EAEA,OAAO,GAAG,IAAI,MAAM,GAAG,SAAS,EAAE;CACpC,QAAQ;EACN,OAAO,iBAAiB,IAAI,CAAC,CAAC,MAAM,GAAG,SAAS;CAClD;AACF;AAEA,MAAM,6BAA6B,UAAgC;CACjE,MAAM,QAAQ,OAAO,SAAS;CAE9B,IAAI,CAAC,OAAO,UAAU,CAAC,MAAM,QAAQ,MAAM,MAAM,KAAK,MAAM,OAAO,WAAW,GAC5E,OAAO;CAGT,MAAM,QAAkB,CAAC;CACzB,MAAM,YAAY,OAAO,WAAW,OAAO,WAAW;CAEtD,MAAM,KAAK,8BAA8B,IAAI,OAAO,EAAE,GAAG;CACzD,MAAM,KAAK,MAAM,WAAW;CAC5B,MAAM,KAAK,GAAG;CAEd,MAAM,aAAa;CACnB,MAAM,cAAc,MAAM,OAAO;CAEjC,MAAM,KAAK,cAAc,YAAY,GAAG;CAGxC,AADwB,MAAM,OAAO,MAAM,GAAG,UAChC,CAAC,CAAC,SAAS,OAAY,QAAgB;EACnD,MAAM,YAAY,sBAAsB,OAAO,KAAK,UAAU;EAC9D,IAAI,WAAW,MAAM,KAAK,SAAS;CACrC,CAAC;CAED,IAAI,cAAc,YAChB,MAAM,KAAK,gBAAgB,cAAc,WAAW,MAAM;CAG5D,IAAI,MAAM,SAAS,QAAW;EAC5B,MAAM,KAAK,GAAG;EACd,MAAM,KAAK,oBAAoB,kBAAkB,MAAM,MAAM,EAAE,GAAG;CACpE;CAEA,MAAM,KAAK,IAAI,IAAI,OAAO,EAAE,EAAE,GAAG;CAEjC,OAAO;AACT;AAEA,MAAM,sBAAsB,UAA8B;CACxD,IAAI,CAAC,OAAO,OAAO;CACnB,MAAM,UAAU,oBAAoB,KAAK;CACzC,MAAM,QAAkB,CAAC;CACzB,MAAM,KAAK,wBAAwB,IAAI,OAAO,EAAE,GAAG;CACnD,KAAK,MAAM,QAAQ,QAAQ,MAAM,IAAI,GACnC,MAAM,KAAK,MAAM,MAAM;CAEzB,MAAM,QAAQ,iBAAiB,QAAQ,MAAM,OAAO,MAAM,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI;CAC9E,IAAI,SAAS,MAAM,SAAS,GAAG;EAC7B,MAAM,KAAK,GAAG;EACd,KAAK,MAAM,QAAQ,OACjB,MAAM,KAAK,MAAM,KAAK,KAAK,GAAG;CAElC;CACA,MAAM,KAAK,IAAI,IAAI,OAAO,EAAE,EAAE,GAAG;CACjC,OAAO,MAAM,KAAK,IAAI;AACxB;AAEA,MAAa,mBAAmB,UAA8B;CAC5D,IAAI,EAAE,iBAAiBC,yBAIrB,OAAO,mBAAmB,KAAK;CAGjC,MAAM,kBAAkB,0BAA0B,KAAK;CACvD,IAAI,iBACF,OAAO,gBAAgB,KAAK,IAAI;CAGlC,MAAM,QAAkB,CAAC;CACzB,MAAM,OAAO,MAAM,QAAQ;CAC3B,MAAM,UAAU,MAAM,WAAW;CAEjC,MAAM,KAAK,mBAAmB,IAAI,OAAO,EAAE,GAAG;CAC9C,MAAM,eAAe,QAAQ,MAAM,IAAI;CACvC,KAAK,MAAM,QAAQ,cACjB,MAAM,KAAK,MAAM,MAAM;CAEzB,MAAM,KAAK,YAAY,MAAM;CAC7B,MAAM,KAAK,GAAG;CAEd,IAAI,MAAM,MAER;MAAI,OADoB,MAAM,SACb,YAAY,MAAM,SAAS,MAAM;GAChD,IAAI,gBAAgB,MAAM,MACxB,MAAM,KAAK,mBAAmB,MAAM,KAAK,WAAW,SAAS;GAE/D,IAAI,uBAAuB,MAAM,MAC/B,MAAM,KAAK,iBAAiB,MAAM,KAAK,kBAAkB,UAAU;GAErE,IAAI,UAAU,MAAM,MAClB,MAAM,KAAK,YAAY,MAAM,KAAK,MAAM;GAE1C,IAAI,UAAU,MAAM,MAClB,MAAM,KAAK,YAAY,MAAM,KAAK,MAAM;GAE1C,IAAI,gBAAgB,MAAM,MACxB,MAAM,KAAK,QAAQ,MAAM,KAAK,YAAY;GAE5C,IAAI,cAAc,MAAM,MACtB,MAAM,KAAK,gBAAgB,MAAM,KAAK,UAAU;GAElD,IAAI,gBAAgB,MAAM,MACxB,MAAM,KAAK,UAAU,MAAM,KAAK,YAAY;EAEhD;;CAGF,QAAQ,MAAR;EACE,KAAK;GACH,MAAM,KAAK,wCAAwC;GACnD;EACF,KAAK;GACH,MAAM,KAAK,2BAA2B;GACtC;EACF,KAAK;EACL,KAAK;EACL,KAAK;GACH,MAAM,KAAK,iDAAiD;GAC5D;EACF,KAAK,WACH,MAAM,KAAK,kCAAkC;CAEjD;CAEA,MAAM,KAAK,IAAI,IAAI,OAAO,EAAE,EAAE,GAAG;CACjC,OAAO,MAAM,KAAK,IAAI;AACxB;AAsCA,MAAM,6BAA6B;CAAC;CAAa;CAAc;CAAW;CAAO;AAAK;AACtF,MAAM,wBAAwB;CAAC;CAAgB;CAAa;AAAc;AAC1E,MAAM,uCAAuB,IAAI,IAAI;CACnC;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;;AASD,MAAa,yBAAyB,UAAgD;CACpF,IAAI,UAAmB,wBAAwB,KAAK;CACpD,IAAI,OAAO;CACX,OAAO,WAAW,OAAO,YAAY,YAAY,OAAO,GAAG;EACzD,IAAI,mBAAmB,uBACrB,OAAO;GACL,MAAM;GACN,WAAW;GACX,SAAS,oBAAoB,OAAO;GACpC,YACE;EACJ;EAEF,IAAI,mBAAmB,iBACrB,OAAO;GACL,MAAM;GACN,WAAW;GACX,SAAS,GAAG,QAAQ,MAAM,IAAI,oBAAoB,QAAQ,QAAQ;GAClE,YAAY,oBAAoB,QAAQ,MAAM,qBAAqB,QAAQ;EAC7E;EAEF,IAAI,mBAAmBA,wBAAW;GAChC,MAAM,kBAAkB,qBAAqB,IAAI,QAAQ,IAAI;GAC7D,OAAO;IACL,MAAM;IACN,WAAW;IACX,SAAS,QAAQ;IACjB,YAAY,kBACR,6DACA;GACN;EACF;EACA,UAAW,QAAgC;EAC3C,QAAQ;CACV;CAEA,MAAM,UAAU,oBAAoB,KAAK;CACzC,MAAM,QAAQ,QAAQ,YAAY;CAElC,IAAI,2BAA2B,MAAM,MAAM,MAAM,SAAS,EAAE,YAAY,CAAC,CAAC,GACxE,OAAO;EACL,MAAM;EACN,WAAW;EACX;EACA,YAAY;CACd;CAEF,IAAI,sBAAsB,MAAM,MAAM,MAAM,SAAS,EAAE,YAAY,CAAC,CAAC,GACnE,OAAO;EACL,MAAM;EACN,WAAW;EACX;EACA,YACE;CACJ;CAEF,IAAI,MAAM,SAAS,WAAW,KAAK,MAAM,SAAS,KAAK,GACrD,OAAO;EACL,MAAM;EACN,WAAW;EACX;EACA,YACE;CACJ;CAGF,OAAO;EAAE,MAAM;EAAW,WAAW;EAAO;CAAQ;AACtD;AAGA,MAAa,iBACX,WACA,UACA,eACA,cACuB;CACvB,OAAO,IAAI,mBAAmB;EAC5B;EACA;EACA;EACA,OAAO;CACT,CAAC;AACH;;;;;;AAOA,MAAa,2BAA2B,UAA4B;CAClE,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU,OAAO;CAEhD,IAAI,WAAW,OAAO;EACpB,MAAM,QAAS,MAA8B;EAE7C,IAAI,SAAS,OAAO,UAAU,YAAY,UAAU,OAClD,IAAI;GACF,MAAM,WAAWC,aAAM,OAAO,KAAwC;GACtE,IAAI,oBAAoBD,wBACtB,OAAO;GAET,OAAO;EACT,QAAQ,CAER;EAGF,IAAI,iBAAiBA,wBACnB,OAAO;CAEX;CAEA,OAAO;AACT;AAGA,MAAa,wBACX,OACA,UACA,eACA,cACuB;CACvB,IAAI,iBAAiBA,wBACnB,OAAO,cAAc,OAAO,UAAU,eAAe,SAAS;CAGhE,IAAI,iBAAiB,oBACnB,OAAO;CAGT,OAAO,IAAI,mBAAmB;EAC5B;EACA;EACA;EACA,OAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,oBAAoB,KAAK,CAAC;CAC9E,CAAC;AACH"}
+{"version":3,"file":"errors.cjs","names":["Data","ORPCError","Cause"],"sources":["../../src/runtime/errors.ts"],"sourcesContent":["import { ORPCError } from \"@orpc/server\";\nimport { Cause, Data } from \"effect\";\nimport type { z } from \"zod\";\n\nexport class PluginRuntimeError extends Data.TaggedError(\"PluginRuntimeError\")<{\n  readonly pluginId?: string;\n  readonly operation?: string;\n  readonly procedureName?: string;\n  readonly cause?: Error;\n}> {\n  override get message() {\n    return this.cause?.message ?? \"Plugin operation failed\";\n  }\n}\n\nexport class ModuleFederationError extends Data.TaggedError(\"ModuleFederationError\")<{\n  readonly pluginId: string;\n  readonly remoteUrl: string;\n  readonly cause?: Error;\n}> {}\n\nexport class ValidationError extends Data.TaggedError(\"ValidationError\")<{\n  readonly pluginId: string;\n  readonly stage: \"config\" | \"input\" | \"output\" | \"state\";\n  readonly zodError: z.ZodError;\n}> {}\n\nconst stringifyUnknown = (value: unknown): string => {\n  if (value === null) return \"null\";\n  if (value === undefined) return \"undefined\";\n  if (value instanceof Error) return value.message;\n  if (typeof value === \"string\") return value;\n  if (typeof value === \"number\" || typeof value === \"bigint\" || typeof value === \"boolean\") {\n    return `${value}`;\n  }\n  if (typeof value === \"symbol\") return value.description ?? \"\";\n  try {\n    return JSON.stringify(value) ?? \"[Unserializable value]\";\n  } catch {\n    return \"[Unserializable value]\";\n  }\n};\n\nconst extractErrorMessage = (error: unknown): string => {\n  if (!error) return \"Unknown error\";\n\n  if (error instanceof Error) {\n    if (error.message) return error.message;\n    if ((error as any).cause instanceof Error) {\n      return extractErrorMessage((error as any).cause);\n    }\n  }\n\n  if (error instanceof AggregateError && error.errors?.length) {\n    return error.errors.map((e) => extractErrorMessage(e)).join(\"; \");\n  }\n\n  if (typeof error === \"object\" && \"message\" in error) {\n    return String((error as any).message);\n  }\n\n  return stringifyUnknown(error);\n};\n\n/**\n * The deepest Error along the cause chain — the original throw site. Wrapper\n * errors (PluginRuntimeError, ModuleFederationError) carry their own stacks\n * (the wrapping frames); diagnosis needs the cause's stack (the actual\n * failing module inside the evaluated remote entry).\n */\nexport const deepestErrorStack = (error: unknown): string | undefined => {\n  let current = error;\n  let deepest: string | undefined;\n  let hops = 0;\n  while (current instanceof Error && hops < 8) {\n    if (current.stack) deepest = current.stack;\n    current = (current as { cause?: unknown }).cause as unknown;\n    hops += 1;\n  }\n  if (current instanceof Error && current.stack) deepest = current.stack;\n  return deepest;\n};\n\nconst formatValidationIssue = (issue: any, index: number, maxDisplay: number): string => {\n  if (index >= maxDisplay) return \"\";\n\n  const path =\n    Array.isArray(issue.path) && issue.path.length > 0\n      ? issue.path.join(\".\")\n      : issue.path || \"root\";\n\n  const message = issue.message || \"Validation failed\";\n\n  return `│    ${index + 1}. ${path}: ${message}`;\n};\n\nconst formatDataPreview = (data: unknown, maxLength = 100): string => {\n  if (!data) return \"undefined\";\n\n  try {\n    const str = JSON.stringify(data);\n    if (str.length <= maxLength) return str;\n\n    if (typeof data === \"object\" && data !== null) {\n      if (Array.isArray(data)) {\n        return `Array(${data.length}) [...]`;\n      }\n      const keys = Object.keys(data);\n      return `{ ${keys.slice(0, 3).join(\", \")}${keys.length > 3 ? \", ...\" : \"\"} }`;\n    }\n\n    return `${str.slice(0, maxLength)}...`;\n  } catch {\n    return stringifyUnknown(data).slice(0, maxLength);\n  }\n};\n\nconst formatORPCValidationError = (error: any): string[] | null => {\n  const cause = error?.cause || error;\n\n  if (!cause?.issues || !Array.isArray(cause.issues) || cause.issues.length === 0) {\n    return null;\n  }\n\n  const lines: string[] = [];\n  const errorType = error?.message || cause?.message || \"Validation failed\";\n\n  lines.push(`\\n╭─ oRPC Validation Error ${\"─\".repeat(30)}`);\n  lines.push(`│  ${errorType}`);\n  lines.push(`│`);\n\n  const maxDisplay = 10;\n  const totalIssues = cause.issues.length;\n\n  lines.push(`│  Issues (${totalIssues}):`);\n\n  const displayedIssues = cause.issues.slice(0, maxDisplay);\n  displayedIssues.forEach((issue: any, idx: number) => {\n    const formatted = formatValidationIssue(issue, idx, maxDisplay);\n    if (formatted) lines.push(formatted);\n  });\n\n  if (totalIssues > maxDisplay) {\n    lines.push(`│    ... and ${totalIssues - maxDisplay} more`);\n  }\n\n  if (cause.data !== undefined) {\n    lines.push(`│`);\n    lines.push(`│  Data preview: ${formatDataPreview(cause.data, 80)}`);\n  }\n\n  lines.push(`╰${\"─\".repeat(50)}\\n`);\n\n  return lines;\n};\n\nconst formatUnknownError = (error: any): string | null => {\n  if (!error) return null;\n  const message = extractErrorMessage(error);\n  const lines: string[] = [];\n  lines.push(`\\n╭─ Unhandled error ${\"─\".repeat(37)}`);\n  for (const line of message.split(\"\\n\")) {\n    lines.push(`│  ${line}`);\n  }\n  const stack = error instanceof Error ? error.stack?.split(\"\\n\").slice(1, 6) : undefined;\n  if (stack && stack.length > 0) {\n    lines.push(`│`);\n    for (const line of stack) {\n      lines.push(`│  ${line.trim()}`);\n    }\n  }\n  lines.push(`╰${\"─\".repeat(50)}\\n`);\n  return lines.join(\"\\n\");\n};\n\nexport const formatORPCError = (error: any): string | null => {\n  if (!(error instanceof ORPCError)) {\n    // Unknown errors used to return null, leaving internal failures (e.g. a\n    // storage backend throw) invisible in host logs while oRPC serialized\n    // them client-side as a bare INTERNAL_SERVER_ERROR.\n    return formatUnknownError(error);\n  }\n\n  const validationLines = formatORPCValidationError(error);\n  if (validationLines) {\n    return validationLines.join(\"\\n\");\n  }\n\n  const lines: string[] = [];\n  const code = error.code || \"UNKNOWN\";\n  const message = error.message || \"An error occurred\";\n\n  lines.push(`\\n╭─ oRPC Error ${\"─\".repeat(40)}`);\n  const messageLines = message.split(\"\\n\");\n  for (const line of messageLines) {\n    lines.push(`│  ${line}`);\n  }\n  lines.push(`│  Code: ${code}`);\n  lines.push(`│`);\n\n  if (error.data) {\n    const dataType = typeof error.data;\n    if (dataType === \"object\" && error.data !== null) {\n      if (\"retryAfter\" in error.data) {\n        lines.push(`│  Retry after: ${error.data.retryAfter} seconds`);\n      }\n      if (\"remainingRequests\" in error.data) {\n        lines.push(`│  Remaining: ${error.data.remainingRequests} requests`);\n      }\n      if (\"host\" in error.data) {\n        lines.push(`│  Host: ${error.data.host}`);\n      }\n      if (\"port\" in error.data) {\n        lines.push(`│  Port: ${error.data.port}`);\n      }\n      if (\"suggestion\" in error.data) {\n        lines.push(`│  → ${error.data.suggestion}`);\n      }\n      if (\"resource\" in error.data) {\n        lines.push(`│  Resource: ${error.data.resource}`);\n      }\n      if (\"resourceId\" in error.data) {\n        lines.push(`│  ID: ${error.data.resourceId}`);\n      }\n    }\n  }\n\n  switch (code) {\n    case \"UNAUTHORIZED\":\n      lines.push(`│  → Check your API key or credentials`);\n      break;\n    case \"TOO_MANY_REQUESTS\":\n      lines.push(`│  → Wait before retrying`);\n      break;\n    case \"SERVICE_UNAVAILABLE\":\n    case \"BAD_GATEWAY\":\n    case \"GATEWAY_TIMEOUT\":\n      lines.push(`│  → The service may be temporarily unavailable`);\n      break;\n    case \"TIMEOUT\":\n      lines.push(`│  → The operation took too long`);\n      break;\n  }\n\n  lines.push(`╰${\"─\".repeat(50)}\\n`);\n  return lines.join(\"\\n\");\n};\n\nexport type PluginFailureKind =\n  | \"mf\"\n  | \"integrity\"\n  | \"config\"\n  | \"validation\"\n  | \"network\"\n  | \"unknown\";\n\nexport interface PluginFailureClassification {\n  kind: PluginFailureKind;\n  retryable: boolean;\n  message: string;\n  suggestion?: string;\n}\n\n/**\n * Structured report of one plugin-load failure, built by a loader (the host's\n * plugin boot, the dev server) from a `PluginFailureClassification` plus\n * loader context. This is the shape health endpoints and dashboards consume —\n * keep it serializable.\n */\nexport interface PluginLoadFailureInfo {\n  /** loader-side key (host entry key, dev plugin id) */\n  pluginKey: string;\n  pluginUrl?: string;\n  /** failing runtime stage when the cause is stage-attributed */\n  operation?: string;\n  kind: string;\n  retryable: boolean;\n  message: string;\n  suggestion?: string;\n  /** loader context: which env secret the plugin's DB binding expects */\n  dbSecret?: string;\n  dbUrlMasked?: string;\n}\n\n/**\n * Structured, serializable warning surfaced alongside plugin failures in\n * health endpoints and dashboards. Warnings are non-fatal: the plugin loaded\n * and initialized successfully, but runs with reduced functionality (e.g. an\n * optional secret was not set, so the feature depending on it is disabled).\n */\nexport interface PluginWarningInfo {\n  /** loader-side key (host entry key, dev plugin id) */\n  pluginKey: string;\n  message: string;\n  hint?: string;\n}\n\n/**\n * The loader's default warning policy for declared-but-unset secrets: a\n * successfully initialized plugin whose declared secret names resolved to\n * nothing (missing or empty in the environment) gets one consolidated\n * warning. `*_DATABASE_URL` keys are excluded — they have the shared-API-DB\n * fallback, and a genuinely-missing DB URL fails initialization (a `failure`,\n * not a warning). A plugin that declares its own `warnings` function opts out\n * of this default.\n */\nexport const defaultMissingSecretWarnings = (\n  pluginKey: string,\n  declaredKeys: readonly string[],\n  resolvedKeys: readonly string[],\n): PluginWarningInfo[] => {\n  const resolved = new Set(resolvedKeys);\n  const missing = declaredKeys.filter(\n    (key) => !resolved.has(key) && !key.endsWith(\"_DATABASE_URL\"),\n  );\n  if (missing.length === 0) return [];\n  return [\n    {\n      pluginKey,\n      message:\n        missing.length === 1\n          ? `Declared secret ${missing[0]} is not set — features depending on it are disabled`\n          : `${missing.length} declared secrets are not set: ${missing.join(\", \")} — features depending on them are disabled`,\n      hint: \"Set the secret(s) in your environment (.env in development); see the plugin's config schema for what each enables\",\n    },\n  ];\n};\n\nconst NETWORK_RETRYABLE_PATTERNS = [\"ETIMEDOUT\", \"ECONNRESET\", \"timeout\", \"503\", \"429\"] as const;\nconst NETWORK_DEAD_PATTERNS = [\"ECONNREFUSED\", \"ENOTFOUND\", \"EHOSTUNREACH\"] as const;\nconst RETRYABLE_ORPC_CODES = new Set([\n  \"TOO_MANY_REQUESTS\",\n  \"SERVICE_UNAVAILABLE\",\n  \"BAD_GATEWAY\",\n  \"GATEWAY_TIMEOUT\",\n  \"TIMEOUT\",\n]);\n\n/**\n * One classification for plugin lifecycle failures across MF / validation /\n * network sources. This is the recovery policy — nothing in the runtime\n * retries on it today by design (the host degrades and runs without a failed\n * plugin); consumers (host bootstrap messages, the dev server retry loop)\n * read kind / retryable / suggestion to decide what to tell the author.\n */\nexport const classifyPluginFailure = (error: unknown): PluginFailureClassification => {\n  let current: unknown = extractFromFiberFailure(error);\n  let hops = 0;\n  while (current && typeof current === \"object\" && hops < 8) {\n    if (current instanceof ModuleFederationError) {\n      return {\n        kind: \"mf\",\n        retryable: false,\n        message: extractErrorMessage(current),\n        suggestion:\n          \"Run bos mf check — the deployed plugin bundle is likely stale (sharedDep / pluginVersion skew), then redeploy the plugin and bos publish --deploy --packages local\",\n      };\n    }\n    if (current instanceof ValidationError) {\n      return {\n        kind: \"validation\",\n        retryable: false,\n        message: `${current.stage}: ${extractErrorMessage(current.zodError)}`,\n        suggestion: `Fix the plugin's ${current.stage} schema at plugins/${current.pluginId}`,\n      };\n    }\n    if (current instanceof ORPCError) {\n      const retryableByCode = RETRYABLE_ORPC_CODES.has(current.code);\n      return {\n        kind: \"network\",\n        retryable: retryableByCode,\n        message: current.message,\n        suggestion: retryableByCode\n          ? \"The plugin procedure failed transiently — retry the call\"\n          : undefined,\n      };\n    }\n    current = (current as { cause?: unknown }).cause;\n    hops += 1;\n  }\n\n  const message = extractErrorMessage(error);\n  const lower = message.toLowerCase();\n\n  if (NETWORK_RETRYABLE_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) {\n    return {\n      kind: \"network\",\n      retryable: true,\n      message,\n      suggestion: \"The remote may be temporarily unavailable — retry after redeploying the plugin\",\n    };\n  }\n  if (NETWORK_DEAD_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) {\n    return {\n      kind: \"network\",\n      retryable: false,\n      message,\n      suggestion:\n        \"The plugin host is unreachable — check plugins.<id> entry URLs in bos.config.json\",\n    };\n  }\n  if (lower.includes(\"integrity\") || lower.includes(\"sri\")) {\n    return {\n      kind: \"integrity\",\n      retryable: true,\n      message,\n      suggestion:\n        \"The deployed bundle content does not match its recorded integrity — redeploy the plugin so bos.config.json is republished with a fresh hash\",\n    };\n  }\n\n  return { kind: \"unknown\", retryable: false, message };\n};\n\n// Convert ORPC errors from plugin procedures to PluginRuntimeError\nexport const wrapORPCError = (\n  orpcError: ORPCError<string, unknown>,\n  pluginId?: string,\n  procedureName?: string,\n  operation?: string,\n): PluginRuntimeError => {\n  return new PluginRuntimeError({\n    pluginId,\n    operation,\n    procedureName,\n    cause: orpcError as Error,\n  });\n};\n\n/**\n * Extracts the underlying error from Effect's FiberFailure wrapper.\n * When Effect.runPromise rejects, errors are wrapped in FiberFailure.\n * This extracts the original error so oRPC can handle it properly.\n */\nexport const extractFromFiberFailure = (error: unknown): unknown => {\n  if (!error || typeof error !== \"object\") return error;\n\n  if (\"cause\" in error) {\n    const cause = (error as { cause?: unknown }).cause;\n\n    if (cause && typeof cause === \"object\" && \"_tag\" in cause) {\n      try {\n        const squashed = Cause.squash(cause as unknown as Cause.Cause<unknown>);\n        if (squashed instanceof ORPCError) {\n          return squashed;\n        }\n        return squashed;\n      } catch {\n        // Not a valid Cause\n      }\n    }\n\n    if (cause instanceof ORPCError) {\n      return cause;\n    }\n  }\n\n  return error;\n};\n\n// Universal error converter for the runtime\nexport const toPluginRuntimeError = (\n  error: unknown,\n  pluginId?: string,\n  procedureName?: string,\n  operation?: string,\n): PluginRuntimeError => {\n  if (error instanceof ORPCError) {\n    return wrapORPCError(error, pluginId, procedureName, operation);\n  }\n\n  if (error instanceof PluginRuntimeError) {\n    return error;\n  }\n\n  return new PluginRuntimeError({\n    pluginId,\n    operation,\n    procedureName,\n    cause: error instanceof Error ? error : new Error(extractErrorMessage(error)),\n  });\n};\n"],"mappings":"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"}

package/dist/runtime/errors.d.cts

@@ -57,6 +57,28 @@ interface PluginLoadFailureInfo {
   dbSecret?: string;
   dbUrlMasked?: string;
 }
+/**
+ * Structured, serializable warning surfaced alongside plugin failures in
+ * health endpoints and dashboards. Warnings are non-fatal: the plugin loaded
+ * and initialized successfully, but runs with reduced functionality (e.g. an
+ * optional secret was not set, so the feature depending on it is disabled).
+ */
+interface PluginWarningInfo {
+  /** loader-side key (host entry key, dev plugin id) */
+  pluginKey: string;
+  message: string;
+  hint?: string;
+}
+/**
+ * The loader's default warning policy for declared-but-unset secrets: a
+ * successfully initialized plugin whose declared secret names resolved to
+ * nothing (missing or empty in the environment) gets one consolidated
+ * warning. `*_DATABASE_URL` keys are excluded — they have the shared-API-DB
+ * fallback, and a genuinely-missing DB URL fails initialization (a `failure`,
+ * not a warning). A plugin that declares its own `warnings` function opts out
+ * of this default.
+ */
+declare const defaultMissingSecretWarnings: (pluginKey: string, declaredKeys: readonly string[], resolvedKeys: readonly string[]) => PluginWarningInfo[];
 /**
  * One classification for plugin lifecycle failures across MF / validation /
  * network sources. This is the recovery policy — nothing in the runtime
@@ -74,5 +96,5 @@ declare const wrapORPCError: (orpcError: ORPCError<string, unknown>, pluginId?:
 declare const extractFromFiberFailure: (error: unknown) => unknown;
 declare const toPluginRuntimeError: (error: unknown, pluginId?: string, procedureName?: string, operation?: string) => PluginRuntimeError;
 //#endregion
-export { ModuleFederationError, PluginFailureClassification, PluginFailureKind, PluginLoadFailureInfo, PluginRuntimeError, ValidationError, classifyPluginFailure, extractFromFiberFailure, formatORPCError, toPluginRuntimeError, wrapORPCError };
+export { ModuleFederationError, PluginFailureClassification, PluginFailureKind, PluginLoadFailureInfo, PluginRuntimeError, PluginWarningInfo, ValidationError, classifyPluginFailure, defaultMissingSecretWarnings, extractFromFiberFailure, formatORPCError, toPluginRuntimeError, wrapORPCError };
 //# sourceMappingURL=errors.d.cts.map