every-plugin 2.10.1 → 3.0.0-rc.3

package/dist/remote-entry.mjs.map

@@ -0,0 +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"}

package/dist/runtime/errors.cjs

@@ -1,10 +1,27 @@
-let _orpc_contract = require("@orpc/contract");
 let effect = require("effect");
+let _orpc_server = require("@orpc/server");
 
 //#region src/runtime/errors.ts
-var PluginRuntimeError = class extends effect.Data.TaggedError("PluginRuntimeError") {};
+var PluginRuntimeError = class extends effect.Data.TaggedError("PluginRuntimeError") {
+	get message() {
+		return this.cause?.message ?? "Plugin operation failed";
+	}
+};
 var ModuleFederationError = class extends effect.Data.TaggedError("ModuleFederationError") {};
 var ValidationError = class extends effect.Data.TaggedError("ValidationError") {};
+const stringifyUnknown = (value) => {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (value instanceof Error) return value.message;
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") return `${value}`;
+	if (typeof value === "symbol") return value.description ?? "";
+	try {
+		return JSON.stringify(value) ?? "[Unserializable value]";
+	} catch {
+		return "[Unserializable value]";
+	}
+};
 const extractErrorMessage = (error) => {
 	if (!error) return "Unknown error";
 	if (error instanceof Error) {
@@ -13,7 +30,25 @@ const extractErrorMessage = (error) => {
 	}
 	if (error instanceof AggregateError && error.errors?.length) return error.errors.map((e) => extractErrorMessage(e)).join("; ");
 	if (typeof error === "object" && "message" in error) return String(error.message);
-	return String(error);
+	return stringifyUnknown(error);
+};
+/**
+* The deepest Error along the cause chain — the original throw site. Wrapper
+* errors (PluginRuntimeError, ModuleFederationError) carry their own stacks
+* (the wrapping frames); diagnosis needs the cause's stack (the actual
+* failing module inside the evaluated remote entry).
+*/
+const deepestErrorStack = (error) => {
+	let current = error;
+	let deepest;
+	let hops = 0;
+	while (current instanceof Error && hops < 8) {
+		if (current.stack) deepest = current.stack;
+		current = current.cause;
+		hops += 1;
+	}
+	if (current instanceof Error && current.stack) deepest = current.stack;
+	return deepest;
 };
 const formatValidationIssue = (issue, index, maxDisplay) => {
 	if (index >= maxDisplay) return "";
@@ -33,7 +68,7 @@ const formatDataPreview = (data, maxLength = 100) => {
 		}
 		return `${str.slice(0, maxLength)}...`;
 	} catch {
-		return String(data).slice(0, maxLength);
+		return stringifyUnknown(data).slice(0, maxLength);
 	}
 };
 const formatORPCValidationError = (error) => {
@@ -59,18 +94,31 @@ const formatORPCValidationError = (error) => {
 	lines.push(`╰${"─".repeat(50)}\n`);
 	return lines;
 };
+const formatUnknownError = (error) => {
+	if (!error) return null;
+	const message = extractErrorMessage(error);
+	const lines = [];
+	lines.push(`\n╭─ Unhandled error ${"─".repeat(37)}`);
+	for (const line of message.split("\n")) lines.push(`│  ${line}`);
+	const stack = error instanceof Error ? error.stack?.split("\n").slice(1, 6) : void 0;
+	if (stack && stack.length > 0) {
+		lines.push(`│`);
+		for (const line of stack) lines.push(`│  ${line.trim()}`);
+	}
+	lines.push(`╰${"─".repeat(50)}\n`);
+	return lines.join("\n");
+};
 const formatORPCError = (error) => {
-	if (!(error instanceof _orpc_contract.ORPCError)) return null;
+	if (!(error instanceof _orpc_server.ORPCError)) return formatUnknownError(error);
 	const validationLines = formatORPCValidationError(error);
 	if (validationLines) return validationLines.join("\n");
 	const lines = [];
 	const code = error.code || "UNKNOWN";
-	const status = error.status || 500;
 	const message = error.message || "An error occurred";
 	lines.push(`\n╭─ oRPC Error ${"─".repeat(40)}`);
 	const messageLines = message.split("\n");
 	for (const line of messageLines) lines.push(`│  ${line}`);
-	lines.push(`│  Code: ${code} (${status})`);
+	lines.push(`│  Code: ${code}`);
 	lines.push(`│`);
 	if (error.data) {
 		if (typeof error.data === "object" && error.data !== null) {
@@ -95,38 +143,115 @@ const formatORPCError = (error) => {
 		case "GATEWAY_TIMEOUT":
 			lines.push(`│  → The service may be temporarily unavailable`);
 			break;
-		case "TIMEOUT":
-			lines.push(`│  → The operation took too long`);
-			break;
+		case "TIMEOUT": lines.push(`│  → The operation took too long`);
 	}
 	lines.push(`╰${"─".repeat(50)}\n`);
 	return lines.join("\n");
 };
-const isRetryableError = (message) => {
-	return [
-		"ETIMEDOUT",
-		"ECONNRESET",
-		"timeout",
-		"503",
-		"429"
-	].some((p) => message.toLowerCase().includes(p.toLowerCase()));
+/**
+* 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 isRetryableORPCCode = (code) => {
-	switch (code) {
-		case "TOO_MANY_REQUESTS":
-		case "SERVICE_UNAVAILABLE":
-		case "BAD_GATEWAY":
-		case "GATEWAY_TIMEOUT":
-		case "TIMEOUT": return true;
-		default: return false;
+const NETWORK_RETRYABLE_PATTERNS = [
+	"ETIMEDOUT",
+	"ECONNRESET",
+	"timeout",
+	"503",
+	"429"
+];
+const NETWORK_DEAD_PATTERNS = [
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"EHOSTUNREACH"
+];
+const RETRYABLE_ORPC_CODES = /* @__PURE__ */ new Set([
+	"TOO_MANY_REQUESTS",
+	"SERVICE_UNAVAILABLE",
+	"BAD_GATEWAY",
+	"GATEWAY_TIMEOUT",
+	"TIMEOUT"
+]);
+/**
+* One classification for plugin lifecycle failures across MF / validation /
+* network sources. This is the recovery policy — nothing in the runtime
+* retries on it today by design (the host degrades and runs without a failed
+* plugin); consumers (host bootstrap messages, the dev server retry loop)
+* read kind / retryable / suggestion to decide what to tell the author.
+*/
+const classifyPluginFailure = (error) => {
+	let current = extractFromFiberFailure(error);
+	let hops = 0;
+	while (current && typeof current === "object" && hops < 8) {
+		if (current instanceof ModuleFederationError) return {
+			kind: "mf",
+			retryable: false,
+			message: extractErrorMessage(current),
+			suggestion: "Run bos mf check — the deployed plugin bundle is likely stale (sharedDep / pluginVersion skew), then redeploy the plugin and bos publish --deploy --packages local"
+		};
+		if (current instanceof ValidationError) return {
+			kind: "validation",
+			retryable: false,
+			message: `${current.stage}: ${extractErrorMessage(current.zodError)}`,
+			suggestion: `Fix the plugin's ${current.stage} schema at plugins/${current.pluginId}`
+		};
+		if (current instanceof _orpc_server.ORPCError) {
+			const retryableByCode = RETRYABLE_ORPC_CODES.has(current.code);
+			return {
+				kind: "network",
+				retryable: retryableByCode,
+				message: current.message,
+				suggestion: retryableByCode ? "The plugin procedure failed transiently — retry the call" : void 0
+			};
+		}
+		current = current.cause;
+		hops += 1;
 	}
+	const message = extractErrorMessage(error);
+	const lower = message.toLowerCase();
+	if (NETWORK_RETRYABLE_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) return {
+		kind: "network",
+		retryable: true,
+		message,
+		suggestion: "The remote may be temporarily unavailable — retry after redeploying the plugin"
+	};
+	if (NETWORK_DEAD_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) return {
+		kind: "network",
+		retryable: false,
+		message,
+		suggestion: "The plugin host is unreachable — check plugins.<id> entry URLs in bos.config.json"
+	};
+	if (lower.includes("integrity") || lower.includes("sri")) return {
+		kind: "integrity",
+		retryable: true,
+		message,
+		suggestion: "The deployed bundle content does not match its recorded integrity — redeploy the plugin so bos.config.json is republished with a fresh hash"
+	};
+	return {
+		kind: "unknown",
+		retryable: false,
+		message
+	};
 };
 const wrapORPCError = (orpcError, pluginId, procedureName, operation) => {
 	return new PluginRuntimeError({
 		pluginId,
 		operation,
 		procedureName,
-		retryable: isRetryableORPCCode(orpcError.code),
 		cause: orpcError
 	});
 };
@@ -141,21 +266,20 @@ const extractFromFiberFailure = (error) => {
 		const cause = error.cause;
 		if (cause && typeof cause === "object" && "_tag" in cause) try {
 			const squashed = effect.Cause.squash(cause);
-			if (squashed instanceof _orpc_contract.ORPCError) return squashed;
+			if (squashed instanceof _orpc_server.ORPCError) return squashed;
 			return squashed;
 		} catch {}
-		if (cause instanceof _orpc_contract.ORPCError) return cause;
+		if (cause instanceof _orpc_server.ORPCError) return cause;
 	}
 	return error;
 };
-const toPluginRuntimeError = (error, pluginId, procedureName, operation, defaultRetryable = false) => {
-	if (error instanceof _orpc_contract.ORPCError) return wrapORPCError(error, pluginId, procedureName, operation);
+const toPluginRuntimeError = (error, pluginId, procedureName, operation) => {
+	if (error instanceof _orpc_server.ORPCError) return wrapORPCError(error, pluginId, procedureName, operation);
 	if (error instanceof PluginRuntimeError) return error;
 	return new PluginRuntimeError({
 		pluginId,
 		operation,
 		procedureName,
-		retryable: defaultRetryable || isRetryableError(extractErrorMessage(error)),
 		cause: error instanceof Error ? error : new Error(extractErrorMessage(error))
 	});
 };
@@ -164,9 +288,11 @@ const toPluginRuntimeError = (error, pluginId, procedureName, operation, default
 exports.ModuleFederationError = ModuleFederationError;
 exports.PluginRuntimeError = PluginRuntimeError;
 exports.ValidationError = ValidationError;
+exports.classifyPluginFailure = classifyPluginFailure;
+exports.deepestErrorStack = deepestErrorStack;
+exports.defaultMissingSecretWarnings = defaultMissingSecretWarnings;
 exports.extractFromFiberFailure = extractFromFiberFailure;
 exports.formatORPCError = formatORPCError;
-exports.isRetryableORPCCode = isRetryableORPCCode;
 exports.toPluginRuntimeError = toPluginRuntimeError;
 exports.wrapORPCError = wrapORPCError;
 //# sourceMappingURL=errors.cjs.map

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/contract\";\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  readonly retryable: boolean;\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 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 String(error);\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 String(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\nexport const formatORPCError = (error: any): string | null => {\n  if (!(error instanceof ORPCError)) {\n    return null;\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 status = error.status || 500;\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} (${status})`);\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\nconst isRetryableError = (message: string): boolean => {\n  const retryablePatterns = [\"ETIMEDOUT\", \"ECONNRESET\", \"timeout\", \"503\", \"429\"];\n  return retryablePatterns.some((p) => message.toLowerCase().includes(p.toLowerCase()));\n};\n\n// Helper to determine if an oRPC error code is retryable\nexport const isRetryableORPCCode = (code: string): boolean => {\n  switch (code) {\n    case \"TOO_MANY_REQUESTS\":\n    case \"SERVICE_UNAVAILABLE\":\n    case \"BAD_GATEWAY\":\n    case \"GATEWAY_TIMEOUT\":\n    case \"TIMEOUT\":\n      return true;\n    default:\n      return false;\n  }\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    retryable: isRetryableORPCCode(orpcError.code),\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 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  defaultRetryable = false,\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    retryable: defaultRetryable || isRetryableError(extractErrorMessage(error)),\n    cause: error instanceof Error ? error : new Error(extractErrorMessage(error)),\n  });\n};\n"],"mappings":"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"}
+{"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

@@ -1,6 +1,6 @@
-import { Cause } from "effect";
 import { z } from "zod";
-import { ORPCError } from "@orpc/contract";
+import { ORPCError } from "@orpc/server";
+import { Cause } from "effect";
 //#region src/runtime/errors.d.ts
 declare const PluginRuntimeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
   readonly _tag: "PluginRuntimeError";
@@ -10,8 +10,9 @@ declare class PluginRuntimeError extends PluginRuntimeError_base<{
   readonly operation?: string;
   readonly procedureName?: string;
   readonly cause?: Error;
-  readonly retryable: boolean;
-}> {}
+}> {
+  get message(): string;
+}
 declare const ModuleFederationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
   readonly _tag: "ModuleFederationError";
 } & Readonly<A>;
@@ -29,7 +30,63 @@ declare class ValidationError extends ValidationError_base<{
   readonly zodError: z.ZodError;
 }> {}
 declare const formatORPCError: (error: any) => string | null;
-declare const isRetryableORPCCode: (code: string) => boolean;
+type PluginFailureKind = "mf" | "integrity" | "config" | "validation" | "network" | "unknown";
+interface PluginFailureClassification {
+  kind: PluginFailureKind;
+  retryable: boolean;
+  message: string;
+  suggestion?: string;
+}
+/**
+ * Structured report of one plugin-load failure, built by a loader (the host's
+ * plugin boot, the dev server) from a `PluginFailureClassification` plus
+ * loader context. This is the shape health endpoints and dashboards consume —
+ * keep it serializable.
+ */
+interface PluginLoadFailureInfo {
+  /** loader-side key (host entry key, dev plugin id) */
+  pluginKey: string;
+  pluginUrl?: string;
+  /** failing runtime stage when the cause is stage-attributed */
+  operation?: string;
+  kind: string;
+  retryable: boolean;
+  message: string;
+  suggestion?: string;
+  /** loader context: which env secret the plugin's DB binding expects */
+  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
+ * retries on it today by design (the host degrades and runs without a failed
+ * plugin); consumers (host bootstrap messages, the dev server retry loop)
+ * read kind / retryable / suggestion to decide what to tell the author.
+ */
+declare const classifyPluginFailure: (error: unknown) => PluginFailureClassification;
 declare const wrapORPCError: (orpcError: ORPCError<string, unknown>, pluginId?: string, procedureName?: string, operation?: string) => PluginRuntimeError;
 /**
  * Extracts the underlying error from Effect's FiberFailure wrapper.
@@ -37,7 +94,7 @@ declare const wrapORPCError: (orpcError: ORPCError<string, unknown>, pluginId?:
  * This extracts the original error so oRPC can handle it properly.
  */
 declare const extractFromFiberFailure: (error: unknown) => unknown;
-declare const toPluginRuntimeError: (error: unknown, pluginId?: string, procedureName?: string, operation?: string, defaultRetryable?: boolean) => PluginRuntimeError;
+declare const toPluginRuntimeError: (error: unknown, pluginId?: string, procedureName?: string, operation?: string) => PluginRuntimeError;
 //#endregion
-export { ModuleFederationError, PluginRuntimeError, ValidationError, extractFromFiberFailure, formatORPCError, isRetryableORPCCode, toPluginRuntimeError, wrapORPCError };
+export { ModuleFederationError, PluginFailureClassification, PluginFailureKind, PluginLoadFailureInfo, PluginRuntimeError, PluginWarningInfo, ValidationError, classifyPluginFailure, defaultMissingSecretWarnings, extractFromFiberFailure, formatORPCError, toPluginRuntimeError, wrapORPCError };
 //# sourceMappingURL=errors.d.cts.map

package/dist/runtime/errors.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.cts","names":[],"sources":["../../src/runtime/errors.ts"],"mappings":";;;;;;;cAIa,2BAA2B;WAC7B;WACA;WACA;WACA,QAAQ;WACR;;;;;cAGE,8BAA8B;WAChC;WACA;WACA,QAAQ;;;;;cAGN,wBAAwB;WAC1B;WACA;WACA,UAAU,EAAE;;cAiGV,kBAAmB;cA6EnB,sBAAuB;cAcvB,gBACX,WAAW,4BACX,mBACA,wBACA,uBACC;;;;;;cAeU,0BAA2B;cA2B3B,uBACX,gBACA,mBACA,wBACA,oBACA,+BACC"}
+{"version":3,"file":"errors.d.cts","names":[],"sources":["../../src/runtime/errors.ts"],"mappings":";;;;;;;cAIa,2BAA2B;WAC7B;WACA;WACA;WACA,QAAQ;;MAEJ;;;;;cAKF,8BAA8B;WAChC;WACA;WACA,QAAQ;;;;;cAGN,wBAAwB;WAC1B;WACA;WACA,UAAU,EAAE;;cAuJV,kBAAe;KAyEhB;UAQK;EACf,MAAM;EACN;EACA;EACA;;;;;;;;UASe;;EAEf;EACA;;EAEA;EACA;EACA;EACA;EACA;;EAEA;EACA;;;;;;;;UASe;;EAEf;EACA;EACA;;;;;;;;;;;cAYW,+BAA4B,mBACtB,iCACc,oCAE9B;;;;;;;;cAmCU,wBAAqB,mBAAqB;cAsE1C,gBAAa,WACb,4BAA0B,mBACpB,wBACK,uBAErB;;;;;;cAcU,0BAAuB;cA2BvB,uBAAoB,gBACjB,mBACG,wBACK,uBAErB"}

package/dist/runtime/errors.d.mts

@@ -1,6 +1,6 @@
-import { z } from "zod";
-import { ORPCError } from "@orpc/contract";
 import { Cause } from "effect";
+import { ORPCError } from "@orpc/server";
+import { z } from "zod";
 //#region src/runtime/errors.d.ts
 declare const PluginRuntimeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
   readonly _tag: "PluginRuntimeError";
@@ -10,8 +10,9 @@ declare class PluginRuntimeError extends PluginRuntimeError_base<{
   readonly operation?: string;
   readonly procedureName?: string;
   readonly cause?: Error;
-  readonly retryable: boolean;
-}> {}
+}> {
+  get message(): string;
+}
 declare const ModuleFederationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
   readonly _tag: "ModuleFederationError";
 } & Readonly<A>;
@@ -29,7 +30,63 @@ declare class ValidationError extends ValidationError_base<{
   readonly zodError: z.ZodError;
 }> {}
 declare const formatORPCError: (error: any) => string | null;
-declare const isRetryableORPCCode: (code: string) => boolean;
+type PluginFailureKind = "mf" | "integrity" | "config" | "validation" | "network" | "unknown";
+interface PluginFailureClassification {
+  kind: PluginFailureKind;
+  retryable: boolean;
+  message: string;
+  suggestion?: string;
+}
+/**
+ * Structured report of one plugin-load failure, built by a loader (the host's
+ * plugin boot, the dev server) from a `PluginFailureClassification` plus
+ * loader context. This is the shape health endpoints and dashboards consume —
+ * keep it serializable.
+ */
+interface PluginLoadFailureInfo {
+  /** loader-side key (host entry key, dev plugin id) */
+  pluginKey: string;
+  pluginUrl?: string;
+  /** failing runtime stage when the cause is stage-attributed */
+  operation?: string;
+  kind: string;
+  retryable: boolean;
+  message: string;
+  suggestion?: string;
+  /** loader context: which env secret the plugin's DB binding expects */
+  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
+ * retries on it today by design (the host degrades and runs without a failed
+ * plugin); consumers (host bootstrap messages, the dev server retry loop)
+ * read kind / retryable / suggestion to decide what to tell the author.
+ */
+declare const classifyPluginFailure: (error: unknown) => PluginFailureClassification;
 declare const wrapORPCError: (orpcError: ORPCError<string, unknown>, pluginId?: string, procedureName?: string, operation?: string) => PluginRuntimeError;
 /**
  * Extracts the underlying error from Effect's FiberFailure wrapper.
@@ -37,7 +94,7 @@ declare const wrapORPCError: (orpcError: ORPCError<string, unknown>, pluginId?:
  * This extracts the original error so oRPC can handle it properly.
  */
 declare const extractFromFiberFailure: (error: unknown) => unknown;
-declare const toPluginRuntimeError: (error: unknown, pluginId?: string, procedureName?: string, operation?: string, defaultRetryable?: boolean) => PluginRuntimeError;
+declare const toPluginRuntimeError: (error: unknown, pluginId?: string, procedureName?: string, operation?: string) => PluginRuntimeError;
 //#endregion
-export { ModuleFederationError, PluginRuntimeError, ValidationError, extractFromFiberFailure, formatORPCError, isRetryableORPCCode, toPluginRuntimeError, wrapORPCError };
+export { ModuleFederationError, PluginFailureClassification, PluginFailureKind, PluginLoadFailureInfo, PluginRuntimeError, PluginWarningInfo, ValidationError, classifyPluginFailure, defaultMissingSecretWarnings, extractFromFiberFailure, formatORPCError, toPluginRuntimeError, wrapORPCError };
 //# sourceMappingURL=errors.d.mts.map

package/dist/runtime/errors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.mts","names":[],"sources":["../../src/runtime/errors.ts"],"mappings":";;;;;;;cAIa,2BAA2B;WAC7B;WACA;WACA;WACA,QAAQ;WACR;;;;;cAGE,8BAA8B;WAChC;WACA;WACA,QAAQ;;;;;cAGN,wBAAwB;WAC1B;WACA;WACA,UAAU,EAAE;;cAiGV,kBAAmB;cA6EnB,sBAAuB;cAcvB,gBACX,WAAW,4BACX,mBACA,wBACA,uBACC;;;;;;cAeU,0BAA2B;cA2B3B,uBACX,gBACA,mBACA,wBACA,oBACA,+BACC"}
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../src/runtime/errors.ts"],"mappings":";;;;;;;cAIa,2BAA2B;WAC7B;WACA;WACA;WACA,QAAQ;;MAEJ;;;;;cAKF,8BAA8B;WAChC;WACA;WACA,QAAQ;;;;;cAGN,wBAAwB;WAC1B;WACA;WACA,UAAU,EAAE;;cAuJV,kBAAe;KAyEhB;UAQK;EACf,MAAM;EACN;EACA;EACA;;;;;;;;UASe;;EAEf;EACA;;EAEA;EACA;EACA;EACA;EACA;;EAEA;EACA;;;;;;;;UASe;;EAEf;EACA;EACA;;;;;;;;;;;cAYW,+BAA4B,mBACtB,iCACc,oCAE9B;;;;;;;;cAmCU,wBAAqB,mBAAqB;cAsE1C,gBAAa,WACb,4BAA0B,mBACpB,wBACK,uBAErB;;;;;;cAcU,0BAAuB;cA2BvB,uBAAoB,gBACjB,mBACG,wBACK,uBAErB"}