@autter/runtime-node 1.8.0 → 1.9.1

package/dist/index.js

@@ -21,10 +21,12 @@ import {
   fingerprintEventAttributes,
   fingerprintValues,
   flushRuntimeLogs,
+  isCaptured,
   isError,
   isRuntimeErrorLike,
   local,
   makeRedactor,
+  markCaptured,
   normalizeRoutePath,
   noteOperationError,
   notifyException,
@@ -42,14 +44,17 @@ import {
   runtimeLogStats,
   runtimeLogger,
   sanitizeBreadcrumbs,
+  setHandledCapture,
   shutdownRuntimeLogger,
   splitFingerprint,
+  startLoggedErrorCapture,
+  stopLoggedErrorCapture,
   toClientError,
   withRuntimeOperation
-} from "./chunk-QKY2OQSO.js";
+} from "./chunk-D3PJ7TQ4.js";
 import {
   runDoctor
-} from "./chunk-UC3QH4PC.js";
+} from "./chunk-FYMEBULO.js";
 import {
   COMPAT_MANIFEST,
   CountingExporter,
@@ -71,7 +76,7 @@ import {
   sharedSlot,
   telemetryStats,
   unregisterFlushTargets
-} from "./chunk-B5ZMOCEM.js";
+} from "./chunk-VIP2EL47.js";
 
 // src/relay.ts
 var IpWindow = class {
@@ -96,6 +101,112 @@ function firstForwardedFor(value) {
   const raw = Array.isArray(value) ? value[0] : value;
   return raw ? (raw.split(",")[0] ?? "").trim() : "";
 }
+var TRUST_AUTO = { mode: "auto" };
+var warnedTrustProxy = false;
+function resolveTrustProxy(value) {
+  if (value === void 0 || value === null || value === "auto") return TRUST_AUTO;
+  if (value === true) return { mode: "all" };
+  if (value === false || value === 0) return { mode: "never" };
+  if (typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 100) {
+    return { mode: "hops", hops: value };
+  }
+  if (typeof value === "string") {
+    const v = value.trim().toLowerCase();
+    if (v === "" || v === "auto") return TRUST_AUTO;
+    if (v === "false" || v === "0" || v === "no" || v === "off") return { mode: "never" };
+    if (v === "true" || v === "yes" || v === "on") return { mode: "all" };
+    if (/^[1-9][0-9]?$/.test(v)) return { mode: "hops", hops: Number(v) };
+  }
+  if (!warnedTrustProxy) {
+    warnedTrustProxy = true;
+    console.warn(
+      `[autter-runtime] relay: trustProxy ${JSON.stringify(value)} is not recognised; using "auto".`
+    );
+  }
+  return TRUST_AUTO;
+}
+var IPV4_RE = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+function normalizeAddress(entry) {
+  if (!entry) return null;
+  let a = entry.trim();
+  if (!a || a.length > 64) return null;
+  const bracketed = /^\[([0-9A-Fa-f:.]+)\](?::\d{1,5})?$/.exec(a);
+  if (bracketed) a = bracketed[1] ?? "";
+  else if (/^[\d.]+:\d{1,5}$/.test(a)) a = a.slice(0, a.lastIndexOf(":"));
+  a = a.toLowerCase();
+  if (a.startsWith("::ffff:") && IPV4_RE.test(a.slice(7))) a = a.slice(7);
+  if (IPV4_RE.test(a)) return a;
+  if (/^[0-9a-f:]+(:(\d{1,3}\.){3}\d{1,3})?$/.test(a) && a.includes(":") && a.split(":").length <= 9) {
+    return a;
+  }
+  return null;
+}
+function isPrivateAddress(a) {
+  if (IPV4_RE.test(a)) {
+    const [x, y] = a.split(".").map(Number);
+    return x === 10 || x === 127 || x === 0 || x === 169 && y === 254 || x === 172 && y >= 16 && y <= 31 || x === 192 && y === 168 || x === 100 && y >= 64 && y <= 127;
+  }
+  return a === "::1" || a === "::" || /^f[cd]/.test(a) || /^fe[89ab]/.test(a);
+}
+function forwardedEntries(value) {
+  const raw = Array.isArray(value) ? value.join(",") : value;
+  if (!raw) return [];
+  const out = [];
+  for (const part of raw.split(",")) {
+    const a = normalizeAddress(part);
+    if (a) out.push(a);
+  }
+  return out;
+}
+function rightmostPublic(entries) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const a = entries[i];
+    if (a && !isPrivateAddress(a)) return a;
+  }
+  return null;
+}
+function fromCustom(opts, request) {
+  if (!opts.clientIp) return null;
+  try {
+    const v = opts.clientIp(request);
+    return typeof v === "string" && v.trim() ? v.trim().slice(0, 64) : null;
+  } catch {
+    return null;
+  }
+}
+function fetchClientKey(request, opts) {
+  const custom = fromCustom(opts, request);
+  if (custom) return custom;
+  const trust = resolveTrustProxy(opts.trustProxy);
+  if (trust.mode === "never") return "shared";
+  const header = request.headers.get("x-forwarded-for");
+  if (trust.mode === "all") return firstForwardedFor(header) || "shared";
+  const entries = forwardedEntries(header);
+  if (trust.mode === "hops") {
+    return entries[Math.max(0, entries.length - trust.hops)] ?? "shared";
+  }
+  const cf = request.cf;
+  if (cf !== null && typeof cf === "object") {
+    const viaCf = normalizeAddress(request.headers.get("cf-connecting-ip"));
+    if (viaCf) return viaCf;
+  }
+  return rightmostPublic(entries) ?? entries[entries.length - 1] ?? "shared";
+}
+function nodeClientKey(req, opts) {
+  const custom = fromCustom(opts, req);
+  if (custom) return custom;
+  const trust = resolveTrustProxy(opts.trustProxy);
+  const peer = normalizeAddress(req.socket?.remoteAddress);
+  if (trust.mode === "never") return peer ?? "unknown";
+  const header = req.headers["x-forwarded-for"];
+  if (trust.mode === "all") return firstForwardedFor(header) || peer || "unknown";
+  const entries = forwardedEntries(header);
+  if (trust.mode === "hops") {
+    return entries[Math.max(0, entries.length - trust.hops)] ?? peer ?? "unknown";
+  }
+  if (peer && !isPrivateAddress(peer)) return peer;
+  return rightmostPublic(entries) ?? peer ?? entries[entries.length - 1] ?? "unknown";
+}
 var DEFAULT_ENDPOINT = "https://otlp.autter.dev";
 var DEFAULT_MAX_BODY = 64 * 1024;
 var MAX_EVENTS = 50;
@@ -290,20 +401,38 @@ function sanitizeBrowserPayload(raw, redactor = defaultRelayRedactor) {
     events
   };
 }
+var FORWARD_ATTEMPTS = 3;
+var FORWARD_MAX_WAIT_MS = 1e4;
 function forward(payload, opts) {
   const endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
   const url = `${endpoint}/v1/browser`;
   const compat = opts.compatCheck !== false;
   if (compat) ensureCompatConfigured(endpoint);
-  void fetch(url, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${opts.apiKey}`
-    },
-    body: JSON.stringify(payload),
-    signal: AbortSignal.timeout(1e4)
-  }).then((response) => {
+  const body = JSON.stringify(payload);
+  const attempt = async (n) => {
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${opts.apiKey}`
+        },
+        body,
+        signal: AbortSignal.timeout(1e4)
+      });
+    } catch (err) {
+      if (n >= FORWARD_ATTEMPTS) throw err;
+      await sleep(1e3 * 2 ** (n - 1));
+      return attempt(n + 1);
+    }
+    if ((response.status === 429 || response.status >= 500) && n < FORWARD_ATTEMPTS) {
+      const seconds = Number(response.headers.get("retry-after"));
+      await response.body?.cancel().catch(() => {
+      });
+      await sleep(seconds > 0 ? Math.min(seconds * 1e3, FORWARD_MAX_WAIT_MS) : 1e3 * 2 ** (n - 1));
+      return attempt(n + 1);
+    }
     if (!compat) return;
     const types = new Set(
       (payload.events ?? []).map((e) => String(e.type))
@@ -314,12 +443,16 @@ function forward(payload, opts) {
       noteCompatFeature("browser_trace_propagation");
     }
     noteRelayRejection(types, response.status, response.headers);
-  }).catch((err) => {
+  };
+  void attempt(1).catch((err) => {
     (opts.onError ?? ((e) => console.warn("autter relay forward failed:", e)))(
       err
     );
   });
 }
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function createBrowserRelayFetchHandler(opts) {
   const maxBody = opts.maxBodyBytes ?? DEFAULT_MAX_BODY;
   const redactor = opts.redact === void 0 || opts.redact === true ? defaultRelayRedactor : makeRedactor(opts.redact);
@@ -329,7 +462,7 @@ function createBrowserRelayFetchHandler(opts) {
       return new Response(null, { status: 405 });
     }
     if (limiter) {
-      const ip = firstForwardedFor(request.headers.get("x-forwarded-for")) || "unknown";
+      const ip = fetchClientKey(request, opts);
       if (!limiter.allow(ip)) {
         return new Response(JSON.stringify({ error: "rate limit exceeded" }), {
           status: 429
@@ -395,7 +528,7 @@ function createBrowserRelayHandler(opts) {
       return;
     }
     if (limiter) {
-      const ip = firstForwardedFor(req.headers["x-forwarded-for"]) || req.socket?.remoteAddress || "unknown";
+      const ip = nodeClientKey(req, opts);
       if (!limiter.allow(ip)) {
         respond(res, 429, { error: "rate limit exceeded" });
         return;
@@ -746,7 +879,6 @@ import { context, trace } from "@opentelemetry/api";
 import { getRPCMetadata, RPCType } from "@opentelemetry/core";
 var REQUEST_STATE = /* @__PURE__ */ Symbol.for("autter.runtime.request");
 var BOUND = /* @__PURE__ */ Symbol.for("autter.runtime.bound");
-var CAPTURED = sharedSlot("requests", () => ({ captured: /* @__PURE__ */ new WeakSet() })).captured;
 var capturer = () => {
 };
 function setRequestExceptionCapturer(fn) {
@@ -757,8 +889,14 @@ var annotator = () => {
 function setRequestSpanAnnotator(fn) {
   annotator = fn;
 }
-function markCaptured(error) {
-  if (error && typeof error === "object") CAPTURED.add(error);
+function decide(rule, error, fallback) {
+  if (rule === void 0) return fallback;
+  if (typeof rule !== "function") return rule;
+  try {
+    return rule(error) === true;
+  } catch {
+    return false;
+  }
 }
 function expressRouteOf(req) {
   const props = req;
@@ -789,7 +927,7 @@ function captureAtBoundary(error, state, rule = void 0, attributes) {
     wanted = false;
   }
   if (!wanted) return;
-  if (error && typeof error === "object" && CAPTURED.has(error)) return;
+  if (isCaptured(error)) return;
   markCaptured(error);
   try {
     const run = () => onRequestSpan(() => capturer(error, attributes));
@@ -803,7 +941,7 @@ function requestStateOf(req) {
   return req[REQUEST_STATE];
 }
 function captureRequestError(error, attributes) {
-  if (error && typeof error === "object" && CAPTURED.has(error)) {
+  if (isCaptured(error)) {
     if (!attributes) return;
     try {
       onRequestSpan(() => annotator(attributes));
@@ -895,7 +1033,8 @@ function finishRequest(state, input) {
     ...state.error !== void 0 ? { error: state.error } : {},
     ...state.errorThrown ? { thrown: true } : {},
     status: input.status,
-    aborted: input.aborted
+    aborted: input.aborted,
+    ...state.degraded ? { degraded: true } : {}
   });
   const span = trace.getActiveSpan();
   if (span?.isRecording()) span.setAttribute("autter.operation.outcome", state.outcome);
@@ -1120,9 +1259,15 @@ function withRuntimeRequest(handler, options = {}) {
         try {
           return await handler(request, ...rest);
         } catch (error) {
-          noteOperationError(error, true, state);
-          captureAtBoundary(error, state, true);
-          throw error;
+          if (decide(options.capture, error, true)) {
+            noteOperationError(error, true, state);
+            captureAtBoundary(error, state, true);
+          }
+          if (!decide(options.errorResponse, error, false)) throw error;
+          return new Response(JSON.stringify(toClientError(error, requestId)), {
+            status: responseStatusOf(error),
+            headers: { "content-type": "application/json; charset=utf-8" }
+          });
         }
       });
       status = response.status;
@@ -1320,6 +1465,8 @@ var S = sharedSlot("server", () => ({
   alwaysOnProvider: null,
   redactor: makeRedactor(true),
   loggerOnlyCapture: null,
+  handled: null,
+  loggerOnlyHandled: null,
   hookRequests: false
 }));
 var LLM_MARKER_ATTRIBUTES = [
@@ -1896,6 +2043,37 @@ function initAutterServer(options) {
     span.setStatus({ code: SpanStatusCode.ERROR, message: safeMessage });
     if (!reuseActive) span.end();
   }
+  function captureHandled(error, attributes, severity) {
+    const isErr = isError(error);
+    if (!errorFilter({
+      type: isErr ? String(error.name ?? "") : "Error",
+      message: isErr ? String(error.message ?? "") : String(error),
+      severity
+    })) return;
+    if (severity === "error") errorTraceBuffer?.retainActiveTrace();
+    telemetryStats.markCaptured();
+    const message = redactor.text(isErr ? error.message : String(error));
+    const stack = isErr && error.stack ? error.stack : new Error().stack?.split("\n").filter((line, i) => i === 0 || !/captureHandled|report(?:Degraded|LoggedError)/.test(line)).join("\n");
+    const split = splitFingerprint(attributes);
+    const fingerprint = fingerprintEventAttributes(split.fingerprint, redactor.text);
+    const redacted = redactor(split.attributes);
+    const activeSpan = trace2.getActiveSpan();
+    const reuseActive = activeSpan?.isRecording() === true;
+    const span = reuseActive ? activeSpan : errorTracer.startSpan(isErr ? error.name : "Error");
+    markCaptured(error);
+    notifyException(error, { ...redacted, ...fingerprint, "autter.severity": severity });
+    span.addEvent("exception", {
+      ...redacted,
+      "exception.type": isErr ? error.name : "Error",
+      "exception.message": message,
+      ...stack ? { "exception.stacktrace": redactor.text(stack) } : {},
+      "autter.severity": severity,
+      ...errorAttributes(error),
+      ...fingerprint,
+      ...breadcrumbEventAttributes(redactor.text, error)
+    });
+    if (!reuseActive) span.end();
+  }
   configureRuntimeLogger({
     endpoint,
     apiKey: options.apiKey,
@@ -1909,6 +2087,8 @@ function initAutterServer(options) {
     reportOutcome: reportOutcome2
   });
   S.hookRequests = options.logging?.requests === true;
+  S.handled = captureHandled;
+  startLoggedErrorCapture(options.captureLoggedErrors);
   let onCrash = null;
   let uninstallRejections = null;
   if (options.captureGlobalErrors !== false) {
@@ -1955,6 +2135,7 @@ function initAutterServer(options) {
     withLlmCall: (info, fn) => runLlmSpan(llmTracer, info, fn),
     trackLlmCall: (call) => recordLlmCall(llmTracer, call),
     shutdown: async () => {
+      if (S.active === server) stopLoggedErrorCapture();
       const logShutdown = await Promise.allSettled([shutdownRuntimeLogger()]);
       if (onCrash) process.off("uncaughtExceptionMonitor", onCrash);
       uninstallRejections?.();
@@ -1962,6 +2143,7 @@ function initAutterServer(options) {
       if (S.active === server) {
         S.active = null;
         S.alwaysOnProvider = null;
+        S.handled = null;
         S.hookRequests = false;
         S.redactor = makeRedactor(true);
       }
@@ -1997,13 +2179,39 @@ function captureException(error, attributes) {
   recordError(span, error);
   span.end();
 }
-function setLoggerOnlyCapture(fn) {
+function setLoggerOnlyCapture(fn, handled = null) {
   S.loggerOnlyCapture = fn;
+  S.loggerOnlyHandled = handled;
+}
+function captureHandledError(error, attributes, severity) {
+  if (S.active) {
+    S.handled?.(error, attributes, severity);
+    return;
+  }
+  if (S.loggerOnlyHandled) {
+    S.loggerOnlyHandled(error, attributes, severity);
+    return;
+  }
+  markCaptured(error);
+  const split = splitFingerprint(attributes);
+  notifyException(error, { ...split.attributes, "autter.severity": severity });
+  const span = trace2.getTracer("autter-errors").startSpan(isError(error) ? error.name : "Error");
+  span.addEvent("exception", {
+    ...S.redactor(split.attributes),
+    "exception.type": isError(error) ? error.name : "Error",
+    "exception.message": S.redactor.text(isError(error) ? error.message : String(error)),
+    ...isError(error) && error.stack ? { "exception.stacktrace": S.redactor.text(error.stack) } : {},
+    "autter.severity": severity,
+    ...errorAttributes(error),
+    ...fingerprintEventAttributes(split.fingerprint, S.redactor.text)
+  });
+  span.end();
 }
 function serverActive() {
   return S.active !== null;
 }
 setRequestExceptionCapturer((error, attributes) => captureException(error, attributes));
+setHandledCapture(captureHandledError);
 setRequestSpanAnnotator((attributes) => {
   const span = trace2.getActiveSpan();
   if (span?.isRecording()) span.setAttributes(S.redactor(splitFingerprint(attributes).attributes));
@@ -2474,6 +2682,33 @@ function initAutterLogging(options) {
     notifyException(error, { ...redacted, ...fingerprint });
     captureExceptionAsLog(error, { ...redacted, ...fingerprint });
   }
+  function captureHandled(error, attributes, severity) {
+    markCaptured(error);
+    const isErrValue = isError(error);
+    if (!errorFilter({
+      type: isErrValue ? String(error.name ?? "") : "Error",
+      message: isErrValue ? String(error.message ?? "") : String(error),
+      severity
+    })) return;
+    const split = splitFingerprint(attributes);
+    const fingerprint = fingerprintEventAttributes(split.fingerprint, redact.text);
+    const redacted = redact(split.attributes);
+    notifyException(error, { ...redacted, ...fingerprint, "autter.severity": severity });
+    const span = trace3.getActiveSpan();
+    if (mode === "auto" && span?.isRecording()) {
+      span.addEvent("exception", {
+        ...redacted,
+        "exception.type": isErrValue ? error.name : "Error",
+        "exception.message": redact.text(isErrValue ? error.message : String(error)),
+        ...isErrValue && error.stack ? { "exception.stacktrace": redact.text(error.stack) } : {},
+        "autter.severity": severity,
+        ...errorAttributes(error),
+        ...fingerprint
+      });
+      return;
+    }
+    captureExceptionAsLog(error, { ...redacted, ...fingerprint }, severity);
+  }
   const captured = /* @__PURE__ */ new WeakSet();
   configureRuntimeLogger({
     endpoint,
@@ -2498,7 +2733,8 @@ function initAutterLogging(options) {
       captureException2(error);
     }
   });
-  setLoggerOnlyCapture(captureException2);
+  setLoggerOnlyCapture(captureException2, captureHandled);
+  startLoggedErrorCapture(options.captureLoggedErrors);
   const onCrash = (error) => {
     if (recordedAsRejection(error)) return;
     captureException2(error, { "autter.unhandled": true });
@@ -2517,6 +2753,7 @@ function initAutterLogging(options) {
     captureException: captureException2,
     flush: flushRuntimeLogs,
     shutdown: async () => {
+      if (L.active === handle) stopLoggedErrorCapture();
       process.off("uncaughtExceptionMonitor", onCrash);
       uninstallRejections?.();
       uninstallRejections = null;

package/dist/{sinks-CIdlmYwy.d.cts → sinks-BfUoE96B.d.cts}

@@ -166,10 +166,19 @@ declare function isRuntimeErrorLike(err: unknown): err is RuntimeErrorLike;
 interface ErrorAttributeOptions {
     /** Also emit `exception.cause.N.*` for the cause chain (default true). */
     causes?: boolean;
+    /**
+     * With `causes`, also emit what only an occurrence record needs (default
+     * true): each cause's stack (`exception.cause.N.stacktrace`, RF-06: a
+     * wrapped error groups with its root cause) and the debug ids of the
+     * bundles in the stacks (`autter.debug_ids`, RF-05: server source maps).
+     * Request and operation summaries pass false.
+     */
+    stacks?: boolean;
 }
 /**
- * Wire attributes for an error: `autter.error.code|why|fix|link|status|expected`
- * and `exception.cause.N.type|message|code` (N = 1..5). Never includes
+ * Wire attributes for an error: `autter.error.code|why|fix|link|status|expected`,
+ * `exception.cause.N.type|message|code|stacktrace` (N = 1..5) and
+ * `autter.debug_ids` (see ErrorAttributeOptions.stacks). Never includes
  * `internal` — see `errorInternal`.
  */
 declare function errorAttributes(err: unknown, options?: ErrorAttributeOptions): Record<string, string | number | boolean>;
@@ -250,6 +259,33 @@ interface BreadcrumbInput {
     at?: string | number | Date;
 }
 
+/**
+ * Handled errors (RF-01, RF-02): the building blocks every server SDK shares
+ * for errors the app caught instead of letting them crash.
+ *
+ * - Caught errors: an `Error` the app passes to `console.error`, a logger
+ *   (pino, winston, bunyan) or `runtimeLogger.error` is reported as an
+ *   occurrence at `error` severity, marked `autter.handled = true`,
+ *   `autter.handling = "caught"`, with the log line as context
+ *   (`autter.log.source`, `autter.log.message`).
+ * - Deliberate fallbacks: `runtimeContext.degraded(err, reason)` reports the
+ *   error at `warning` severity (never an incident), marked
+ *   `autter.handling = "deliberate"` with `autter.degraded.reason`.
+ *
+ * A burst limit keeps a looping error from flooding: per kind (error type
+ * and throw site) ten at once, then one every ten seconds. What it leaves
+ * out is counted, and the count rides on the next record of that kind as
+ * `autter.caught.dropped`, which the ingester adds to `runtime_ingest_drops`
+ * (reason `caught_limited`).
+ */
+type LoggedErrorSource = "console" | "pino" | "winston" | "bunyan" | "runtimeLogger";
+/**
+ * `captureLoggedErrors`: `true` (default) reports errors logged through
+ * every source the SDK supports, `false` none; an object turns single
+ * sources off, e.g. `{ console: false }`.
+ */
+type CaptureLoggedErrorsOption = boolean | Partial<Record<LoggedErrorSource, boolean>>;
+
 /**
  * Client-side volume control shared by the server SDKs (runtime-node,
  * runtime-edge; 1.8.0 / 1.2.0, EI-38): `ignoreErrors` and `sampleRate`.
@@ -319,7 +355,9 @@ interface OtlpSinkOptions {
  * OTLP/HTTP JSON export to `${endpoint}/v1/logs`. Bounded exactly like
  * 1.4.0: 1000 records / 4 MiB buffered, 256 KiB per record, batches of 50
  * (≤ 512 KiB), 3 attempts within a 10 s deadline, exponential back-off
- * on failure, undelivered records reported at shutdown.
+ * on failure, undelivered records reported at shutdown. A 429 or 5xx is
+ * retried after its Retry-After (else 500 ms, 1 s); any other 4xx is not
+ * retried within the flush.
  */
 declare function otlpSink(options?: OtlpSinkOptions): RuntimeSink;
 interface ConsoleSinkOptions {
@@ -358,4 +396,4 @@ interface MemorySink extends RuntimeSink {
 /** Keeps every record in memory — for tests (`@autter/runtime-node/testing`). */
 declare function memorySink(): MemorySink;
 
-export { errorAttributes as A, type BreadcrumbInput as B, type CapturedException as C, fileSink as D, isRuntimeErrorLike as E, type FileSinkOptions as F, otlpSink as G, redactAttributes as H, type IgnoreErrorPattern as I, redactText as J, toClientError as K, type MemorySink as M, type OtlpSinkOptions as O, type RuntimeEvent as R, type RuntimeOutcome as a, type RedactOptions as b, type Redactor$1 as c, type RuntimeLogLevel as d, type RuntimeOperationKind as e, type RuntimeSink as f, type RuntimeLogContext as g, type RuntimeCarrier as h, type Breadcrumb as i, type BreadcrumbLevel as j, type BreadcrumbType as k, CODE_PATTERN as l, memorySink as m, type ClientErrorBody as n, type ConsoleSinkOptions as o, RuntimeError as p, type RuntimeErrorCatalog as q, type RuntimeErrorDefinition as r, type RuntimeErrorExtras as s, type RuntimeErrorFactory as t, type RuntimeErrorLike as u, type RuntimeErrorOptions as v, type RuntimeLogContextValue as w, type RuntimeSinkContext as x, consoleSink as y, defineRuntimeErrors as z };
+export { defineRuntimeErrors as A, type BreadcrumbInput as B, type CapturedException as C, errorAttributes as D, fileSink as E, type FileSinkOptions as F, isRuntimeErrorLike as G, otlpSink as H, type IgnoreErrorPattern as I, redactAttributes as J, redactText as K, type LoggedErrorSource as L, type MemorySink as M, toClientError as N, type OtlpSinkOptions as O, type RuntimeEvent as R, type RuntimeOutcome as a, type RedactOptions as b, type Redactor$1 as c, type RuntimeLogLevel as d, type RuntimeOperationKind as e, type RuntimeSink as f, type RuntimeLogContext as g, type RuntimeCarrier as h, type CaptureLoggedErrorsOption as i, type Breadcrumb as j, type BreadcrumbLevel as k, type BreadcrumbType as l, memorySink as m, CODE_PATTERN as n, type ClientErrorBody as o, type ConsoleSinkOptions as p, RuntimeError as q, type RuntimeErrorCatalog as r, type RuntimeErrorDefinition as s, type RuntimeErrorExtras as t, type RuntimeErrorFactory as u, type RuntimeErrorLike as v, type RuntimeErrorOptions as w, type RuntimeLogContextValue as x, type RuntimeSinkContext as y, consoleSink as z };

package/dist/{sinks-CIdlmYwy.d.ts → sinks-BfUoE96B.d.ts}

@@ -166,10 +166,19 @@ declare function isRuntimeErrorLike(err: unknown): err is RuntimeErrorLike;
 interface ErrorAttributeOptions {
     /** Also emit `exception.cause.N.*` for the cause chain (default true). */
     causes?: boolean;
+    /**
+     * With `causes`, also emit what only an occurrence record needs (default
+     * true): each cause's stack (`exception.cause.N.stacktrace`, RF-06: a
+     * wrapped error groups with its root cause) and the debug ids of the
+     * bundles in the stacks (`autter.debug_ids`, RF-05: server source maps).
+     * Request and operation summaries pass false.
+     */
+    stacks?: boolean;
 }
 /**
- * Wire attributes for an error: `autter.error.code|why|fix|link|status|expected`
- * and `exception.cause.N.type|message|code` (N = 1..5). Never includes
+ * Wire attributes for an error: `autter.error.code|why|fix|link|status|expected`,
+ * `exception.cause.N.type|message|code|stacktrace` (N = 1..5) and
+ * `autter.debug_ids` (see ErrorAttributeOptions.stacks). Never includes
  * `internal` — see `errorInternal`.
  */
 declare function errorAttributes(err: unknown, options?: ErrorAttributeOptions): Record<string, string | number | boolean>;
@@ -250,6 +259,33 @@ interface BreadcrumbInput {
     at?: string | number | Date;
 }
 
+/**
+ * Handled errors (RF-01, RF-02): the building blocks every server SDK shares
+ * for errors the app caught instead of letting them crash.
+ *
+ * - Caught errors: an `Error` the app passes to `console.error`, a logger
+ *   (pino, winston, bunyan) or `runtimeLogger.error` is reported as an
+ *   occurrence at `error` severity, marked `autter.handled = true`,
+ *   `autter.handling = "caught"`, with the log line as context
+ *   (`autter.log.source`, `autter.log.message`).
+ * - Deliberate fallbacks: `runtimeContext.degraded(err, reason)` reports the
+ *   error at `warning` severity (never an incident), marked
+ *   `autter.handling = "deliberate"` with `autter.degraded.reason`.
+ *
+ * A burst limit keeps a looping error from flooding: per kind (error type
+ * and throw site) ten at once, then one every ten seconds. What it leaves
+ * out is counted, and the count rides on the next record of that kind as
+ * `autter.caught.dropped`, which the ingester adds to `runtime_ingest_drops`
+ * (reason `caught_limited`).
+ */
+type LoggedErrorSource = "console" | "pino" | "winston" | "bunyan" | "runtimeLogger";
+/**
+ * `captureLoggedErrors`: `true` (default) reports errors logged through
+ * every source the SDK supports, `false` none; an object turns single
+ * sources off, e.g. `{ console: false }`.
+ */
+type CaptureLoggedErrorsOption = boolean | Partial<Record<LoggedErrorSource, boolean>>;
+
 /**
  * Client-side volume control shared by the server SDKs (runtime-node,
  * runtime-edge; 1.8.0 / 1.2.0, EI-38): `ignoreErrors` and `sampleRate`.
@@ -319,7 +355,9 @@ interface OtlpSinkOptions {
  * OTLP/HTTP JSON export to `${endpoint}/v1/logs`. Bounded exactly like
  * 1.4.0: 1000 records / 4 MiB buffered, 256 KiB per record, batches of 50
  * (≤ 512 KiB), 3 attempts within a 10 s deadline, exponential back-off
- * on failure, undelivered records reported at shutdown.
+ * on failure, undelivered records reported at shutdown. A 429 or 5xx is
+ * retried after its Retry-After (else 500 ms, 1 s); any other 4xx is not
+ * retried within the flush.
  */
 declare function otlpSink(options?: OtlpSinkOptions): RuntimeSink;
 interface ConsoleSinkOptions {
@@ -358,4 +396,4 @@ interface MemorySink extends RuntimeSink {
 /** Keeps every record in memory — for tests (`@autter/runtime-node/testing`). */
 declare function memorySink(): MemorySink;
 
-export { errorAttributes as A, type BreadcrumbInput as B, type CapturedException as C, fileSink as D, isRuntimeErrorLike as E, type FileSinkOptions as F, otlpSink as G, redactAttributes as H, type IgnoreErrorPattern as I, redactText as J, toClientError as K, type MemorySink as M, type OtlpSinkOptions as O, type RuntimeEvent as R, type RuntimeOutcome as a, type RedactOptions as b, type Redactor$1 as c, type RuntimeLogLevel as d, type RuntimeOperationKind as e, type RuntimeSink as f, type RuntimeLogContext as g, type RuntimeCarrier as h, type Breadcrumb as i, type BreadcrumbLevel as j, type BreadcrumbType as k, CODE_PATTERN as l, memorySink as m, type ClientErrorBody as n, type ConsoleSinkOptions as o, RuntimeError as p, type RuntimeErrorCatalog as q, type RuntimeErrorDefinition as r, type RuntimeErrorExtras as s, type RuntimeErrorFactory as t, type RuntimeErrorLike as u, type RuntimeErrorOptions as v, type RuntimeLogContextValue as w, type RuntimeSinkContext as x, consoleSink as y, defineRuntimeErrors as z };
+export { defineRuntimeErrors as A, type BreadcrumbInput as B, type CapturedException as C, errorAttributes as D, fileSink as E, type FileSinkOptions as F, isRuntimeErrorLike as G, otlpSink as H, type IgnoreErrorPattern as I, redactAttributes as J, redactText as K, type LoggedErrorSource as L, type MemorySink as M, toClientError as N, type OtlpSinkOptions as O, type RuntimeEvent as R, type RuntimeOutcome as a, type RedactOptions as b, type Redactor$1 as c, type RuntimeLogLevel as d, type RuntimeOperationKind as e, type RuntimeSink as f, type RuntimeLogContext as g, type RuntimeCarrier as h, type CaptureLoggedErrorsOption as i, type Breadcrumb as j, type BreadcrumbLevel as k, type BreadcrumbType as l, memorySink as m, CODE_PATTERN as n, type ClientErrorBody as o, type ConsoleSinkOptions as p, RuntimeError as q, type RuntimeErrorCatalog as r, type RuntimeErrorDefinition as s, type RuntimeErrorExtras as t, type RuntimeErrorFactory as u, type RuntimeErrorLike as v, type RuntimeErrorOptions as w, type RuntimeLogContextValue as x, type RuntimeSinkContext as y, consoleSink as z };

package/dist/testing.cjs

@@ -2,22 +2,22 @@
 
 
 
-var _chunk37W7YYXOcjs = require('./chunk-37W7YYXO.cjs');
-require('./chunk-MOZOUEMA.cjs');
+var _chunkFV64SIRQcjs = require('./chunk-FV64SIRQ.cjs');
+require('./chunk-3P573RHA.cjs');
 
 // src/testing.ts
 function captureRuntime() {
-  const sink = _chunk37W7YYXOcjs.memorySink.call(void 0, );
-  const remove = _chunk37W7YYXOcjs.addRuntimeSink.call(void 0, sink);
+  const sink = _chunkFV64SIRQcjs.memorySink.call(void 0, );
+  const remove = _chunkFV64SIRQcjs.addRuntimeSink.call(void 0, sink);
   return {
     get events() {
       return [...sink.events];
     },
     get operations() {
-      return sink.events.filter(_chunk37W7YYXOcjs.isSummary);
+      return sink.events.filter(_chunkFV64SIRQcjs.isSummary);
     },
     get logs() {
-      return sink.events.filter((event) => !_chunk37W7YYXOcjs.isSummary.call(void 0, event));
+      return sink.events.filter((event) => !_chunkFV64SIRQcjs.isSummary.call(void 0, event));
     },
     get exceptions() {
       return [...sink.exceptions];
@@ -98,7 +98,7 @@ var OperationExpectation = class {
   }
 };
 function expectOperation(source, name) {
-  const events = Array.isArray(source) ? source.filter(_chunk37W7YYXOcjs.isSummary) : source.operations;
+  const events = Array.isArray(source) ? source.filter(_chunkFV64SIRQcjs.isSummary) : source.operations;
   const matches = events.filter((event2) => {
     const actual = String(_nullishCoalesce(event2.attributes["autter.operation.name"], () => ( "")));
     return typeof name === "string" ? actual === name : name.test(actual);
@@ -118,4 +118,4 @@ function expectOperation(source, name) {
 
 
 
-exports.captureRuntime = captureRuntime; exports.expectOperation = expectOperation; exports.memorySink = _chunk37W7YYXOcjs.memorySink;
+exports.captureRuntime = captureRuntime; exports.expectOperation = expectOperation; exports.memorySink = _chunkFV64SIRQcjs.memorySink;

package/dist/testing.d.cts

@@ -1,5 +1,5 @@
-import { R as RuntimeEvent, a as RuntimeOutcome, C as CapturedException } from './sinks-CIdlmYwy.cjs';
-export { M as MemorySink, m as memorySink } from './sinks-CIdlmYwy.cjs';
+import { R as RuntimeEvent, a as RuntimeOutcome, C as CapturedException } from './sinks-BfUoE96B.cjs';
+export { M as MemorySink, m as memorySink } from './sinks-BfUoE96B.cjs';
 
 /**
  * Test helpers — `@autter/runtime-node/testing`. No ingester, no network: