@logbrew/sdk 0.1.5 → 0.1.7

package/index.d.cts

@@ -2,6 +2,48 @@
 export type MetadataValue = string | number | boolean | null;
 /** Structured metadata map shared by public LogBrew event attribute types. */
 export type Metadata = Record<string, MetadataValue>;
+/** Bounded service, runtime, or framework identity shared by telemetry signals. */
+export type TelemetryNamedVersion = {
+  name: string;
+  version?: string;
+};
+/** Privacy-bounded resource identity shared by telemetry signals. */
+export type TelemetryResource = {
+  service?: TelemetryNamedVersion;
+  deployment?: { environment?: string; release?: string };
+  runtime?: TelemetryNamedVersion;
+  framework?: TelemetryNamedVersion;
+  operatingSystem?: TelemetryNamedVersion & { build?: string };
+  device?: { family?: string; model?: string; architecture?: string };
+  application?: { name?: string; version?: string; build?: string };
+};
+/** W3C-compatible correlation identity shared by non-span telemetry. */
+export type TelemetryTraceContext = {
+  traceId: string;
+  spanId?: string;
+  parentSpanId?: string;
+  sampled?: boolean;
+};
+/** Opaque application session identity. */
+export type TelemetrySessionContext = {
+  id: string;
+  previousId?: string;
+};
+/** Explicit app-owned subject identity; do not send names, email addresses, or IP addresses. */
+export type TelemetrySubjectContext = {
+  id: string;
+  kind: "anonymous" | "user";
+};
+/** Versioned shared context available on every LogBrew event type. */
+export type TelemetryContext = {
+  schemaVersion: 1;
+  resource?: TelemetryResource;
+  trace?: TelemetryTraceContext;
+  session?: TelemetrySessionContext;
+  subject?: TelemetrySubjectContext;
+  /** Up to 32 low-cardinality string dimensions with safe machine keys. */
+  tags?: Record<string, string>;
+};
 /** Canonical user-facing severity categories accepted by LogBrew. */
 export type Severity = "info" | "warning" | "error" | "critical";
 /** Runtime-level aliases accepted for compatibility and normalized before send. */
@@ -211,6 +253,7 @@ export type ReleaseAttributes = {
   commit?: string;
   notes?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Public environment event attributes. */
@@ -218,6 +261,7 @@ export type EnvironmentAttributes = {
   name: string;
   region?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Privacy-bounded generated JavaScript frame attached to an issue. */
@@ -228,18 +272,71 @@ export type IssueStackFrame = {
   line: number;
   /** One-based generated source column. */
   column: number;
+  /** Optional bounded function or method identity. */
+  function?: string;
+  /** Optional bounded module, package, or namespace identity. */
+  module?: string;
+  /** Whether application code classified this frame as app-owned. */
+  inApp?: boolean;
   /** Optional release-artifact Debug ID matched to this generated file. */
   debugId?: string;
 };
 
+/** Runtime path that captured an exception and whether it escaped that path. */
+export type IssueExceptionMechanism = {
+  /** Stable low-cardinality capture mechanism, such as `react.error_boundary`. */
+  type: string;
+  /** False when the exception escaped the capture boundary. */
+  handled: boolean;
+};
+
+/** Structured exception identity attached to an issue. */
+export type IssueException = {
+  /** Bounded runtime exception class or error type. */
+  type: string;
+  /** Capture mechanism when the SDK can determine it. */
+  mechanism?: IssueExceptionMechanism;
+};
+
+export type IssueBreadcrumbLevel = "debug" | "info" | "warning" | "error" | "critical";
+export type IssueBreadcrumbLevelInput = IssueBreadcrumbLevel | "trace" | "log" | "warn" | "fatal";
+export type IssueBreadcrumbDataValue = string | number | boolean | null;
+
+/** One privacy-bounded step that happened before an issue. */
+export type IssueBreadcrumb = {
+  /** RFC 3339 timestamp with an explicit timezone. */
+  timestamp: string;
+  /** Optional stable breadcrumb kind, such as `navigation` or `http`. */
+  type?: string;
+  /** Required low-cardinality source category. */
+  category: string;
+  level?: IssueBreadcrumbLevel;
+  /** Optional bounded display-safe description. */
+  message?: string;
+  /** At most eight flat primitive fields. Never include authentication material or raw request data. */
+  data?: Record<string, IssueBreadcrumbDataValue>;
+};
+
+/** Input accepted by `addBreadcrumb`; the client supplies the current timestamp when omitted. */
+export type IssueBreadcrumbInput = Omit<IssueBreadcrumb, "timestamp" | "level"> & {
+  timestamp?: string;
+  level?: IssueBreadcrumbLevelInput;
+};
+
 /** Public issue event attributes. */
 export type IssueAttributes = {
   title: string;
   level: SeverityInput;
   message?: string;
+  exception?: IssueException;
   /** Ordered privacy-bounded generated frames, capped at 32. */
   stackFrames?: IssueStackFrame[];
+  /** Oldest-to-newest issue history, capped at the most recent 64 entries. */
+  breadcrumbs?: IssueBreadcrumb[];
+  /** True when older or invalid history was omitted before capture. */
+  breadcrumbsTruncated?: boolean;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Options for creating privacy-bounded issue attributes from a JavaScript error. */
@@ -248,6 +345,10 @@ export type JavaScriptErrorIssueOptions = {
   level?: SeverityInput;
   message?: string;
   metadata?: Metadata;
+  /** Stable low-cardinality capture mechanism. Defaults to `javascript.error`. */
+  mechanism?: string;
+  /** Whether the error was handled by the capture boundary. Defaults to true. */
+  handled?: boolean;
   /** Metadata source label. Defaults to `javascript.error`. */
   source?: string;
   /** Active trace copied into primitive correlation metadata. */
@@ -276,6 +377,7 @@ export type LogAttributes = {
   level: SeverityInput;
   logger?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Console method names supported by the opt-in console capture helper. */
@@ -406,6 +508,7 @@ export type SpanAttributes = {
   events?: SpanEventSummary[];
   links?: SpanLinkSummary[];
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Public action event attributes. */
@@ -413,8 +516,18 @@ export type ActionAttributes = {
   name: string;
   status: "queued" | "running" | "success" | "failure";
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
+/** Stable product-analytics event categories carried in reserved action metadata. */
+export type ProductAnalyticsKind = "page_view" | "screen_view" | "interaction";
+
+/** Current version of the reserved product-analytics metadata vocabulary. */
+export declare const PRODUCT_ANALYTICS_SCHEMA_VERSION: 1;
+
+/** Product-analytics categories understood by this SDK version. */
+export declare const PRODUCT_ANALYTICS_KINDS: readonly ProductAnalyticsKind[];
+
 /** App-owned product step input for agent-readable action timelines. */
 export type ProductActionInput = string | {
   name: string;
@@ -515,6 +628,7 @@ export type MetricAttributes = {
   unit: string;
   temporality: "delta" | "cumulative";
   metadata?: Metadata;
+  context?: TelemetryContext;
 } | {
   name: string;
   kind: "gauge";
@@ -656,6 +770,8 @@ export declare class LogBrewClient {
     apiKey: string;
     sdkName: string;
     sdkVersion: string;
+    /** Versioned context merged into every captured event; event context can override dynamic fields. */
+    context?: TelemetryContext;
     /** Retry attempts after the first send. Must be a non-negative integer; defaults to 2. */
     maxRetries?: number;
     eventFilter?: EventFilter;
@@ -690,6 +806,10 @@ export declare class LogBrewClient {
   previewJson(): string;
   /** Purge queued events from memory and persistence while no delivery operation is active. */
   purgePendingEvents(): number;
+  /** Add one explicit privacy-bounded breadcrumb to the client's 64-entry issue history. */
+  addBreadcrumb(breadcrumb: IssueBreadcrumbInput, timestamp?: string): void;
+  /** Clear the current issue breadcrumb history and return the number removed. */
+  clearBreadcrumbs(): number;
   release(id: string, timestamp: string, attributes: ReleaseAttributes): void;
   environment(id: string, timestamp: string, attributes: EnvironmentAttributes): void;
   issue(id: string, timestamp: string, attributes: IssueAttributes): void;

package/index.d.ts

@@ -2,6 +2,48 @@
 export type MetadataValue = string | number | boolean | null;
 /** Structured metadata map shared by public LogBrew event attribute types. */
 export type Metadata = Record<string, MetadataValue>;
+/** Bounded service, runtime, or framework identity shared by telemetry signals. */
+export type TelemetryNamedVersion = {
+  name: string;
+  version?: string;
+};
+/** Privacy-bounded resource identity shared by telemetry signals. */
+export type TelemetryResource = {
+  service?: TelemetryNamedVersion;
+  deployment?: { environment?: string; release?: string };
+  runtime?: TelemetryNamedVersion;
+  framework?: TelemetryNamedVersion;
+  operatingSystem?: TelemetryNamedVersion & { build?: string };
+  device?: { family?: string; model?: string; architecture?: string };
+  application?: { name?: string; version?: string; build?: string };
+};
+/** W3C-compatible correlation identity shared by non-span telemetry. */
+export type TelemetryTraceContext = {
+  traceId: string;
+  spanId?: string;
+  parentSpanId?: string;
+  sampled?: boolean;
+};
+/** Opaque application session identity. */
+export type TelemetrySessionContext = {
+  id: string;
+  previousId?: string;
+};
+/** Explicit app-owned subject identity; do not send names, email addresses, or IP addresses. */
+export type TelemetrySubjectContext = {
+  id: string;
+  kind: "anonymous" | "user";
+};
+/** Versioned shared context available on every LogBrew event type. */
+export type TelemetryContext = {
+  schemaVersion: 1;
+  resource?: TelemetryResource;
+  trace?: TelemetryTraceContext;
+  session?: TelemetrySessionContext;
+  subject?: TelemetrySubjectContext;
+  /** Up to 32 low-cardinality string dimensions with safe machine keys. */
+  tags?: Record<string, string>;
+};
 /** Canonical user-facing severity categories accepted by LogBrew. */
 export type Severity = "info" | "warning" | "error" | "critical";
 /** Runtime-level aliases accepted for compatibility and normalized before send. */
@@ -211,6 +253,7 @@ export type ReleaseAttributes = {
   commit?: string;
   notes?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Public environment event attributes. */
@@ -218,6 +261,7 @@ export type EnvironmentAttributes = {
   name: string;
   region?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Privacy-bounded generated JavaScript frame attached to an issue. */
@@ -228,18 +272,71 @@ export type IssueStackFrame = {
   line: number;
   /** One-based generated source column. */
   column: number;
+  /** Optional bounded function or method identity. */
+  function?: string;
+  /** Optional bounded module, package, or namespace identity. */
+  module?: string;
+  /** Whether application code classified this frame as app-owned. */
+  inApp?: boolean;
   /** Optional release-artifact Debug ID matched to this generated file. */
   debugId?: string;
 };
 
+/** Runtime path that captured an exception and whether it escaped that path. */
+export type IssueExceptionMechanism = {
+  /** Stable low-cardinality capture mechanism, such as `react.error_boundary`. */
+  type: string;
+  /** False when the exception escaped the capture boundary. */
+  handled: boolean;
+};
+
+/** Structured exception identity attached to an issue. */
+export type IssueException = {
+  /** Bounded runtime exception class or error type. */
+  type: string;
+  /** Capture mechanism when the SDK can determine it. */
+  mechanism?: IssueExceptionMechanism;
+};
+
+export type IssueBreadcrumbLevel = "debug" | "info" | "warning" | "error" | "critical";
+export type IssueBreadcrumbLevelInput = IssueBreadcrumbLevel | "trace" | "log" | "warn" | "fatal";
+export type IssueBreadcrumbDataValue = string | number | boolean | null;
+
+/** One privacy-bounded step that happened before an issue. */
+export type IssueBreadcrumb = {
+  /** RFC 3339 timestamp with an explicit timezone. */
+  timestamp: string;
+  /** Optional stable breadcrumb kind, such as `navigation` or `http`. */
+  type?: string;
+  /** Required low-cardinality source category. */
+  category: string;
+  level?: IssueBreadcrumbLevel;
+  /** Optional bounded display-safe description. */
+  message?: string;
+  /** At most eight flat primitive fields. Never include authentication material or raw request data. */
+  data?: Record<string, IssueBreadcrumbDataValue>;
+};
+
+/** Input accepted by `addBreadcrumb`; the client supplies the current timestamp when omitted. */
+export type IssueBreadcrumbInput = Omit<IssueBreadcrumb, "timestamp" | "level"> & {
+  timestamp?: string;
+  level?: IssueBreadcrumbLevelInput;
+};
+
 /** Public issue event attributes. */
 export type IssueAttributes = {
   title: string;
   level: SeverityInput;
   message?: string;
+  exception?: IssueException;
   /** Ordered privacy-bounded generated frames, capped at 32. */
   stackFrames?: IssueStackFrame[];
+  /** Oldest-to-newest issue history, capped at the most recent 64 entries. */
+  breadcrumbs?: IssueBreadcrumb[];
+  /** True when older or invalid history was omitted before capture. */
+  breadcrumbsTruncated?: boolean;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Options for creating privacy-bounded issue attributes from a JavaScript error. */
@@ -248,6 +345,10 @@ export type JavaScriptErrorIssueOptions = {
   level?: SeverityInput;
   message?: string;
   metadata?: Metadata;
+  /** Stable low-cardinality capture mechanism. Defaults to `javascript.error`. */
+  mechanism?: string;
+  /** Whether the error was handled by the capture boundary. Defaults to true. */
+  handled?: boolean;
   /** Metadata source label. Defaults to `javascript.error`. */
   source?: string;
   /** Active trace copied into primitive correlation metadata. */
@@ -276,6 +377,7 @@ export type LogAttributes = {
   level: SeverityInput;
   logger?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Console method names supported by the opt-in console capture helper. */
@@ -406,6 +508,7 @@ export type SpanAttributes = {
   events?: SpanEventSummary[];
   links?: SpanLinkSummary[];
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Public action event attributes. */
@@ -413,8 +516,18 @@ export type ActionAttributes = {
   name: string;
   status: "queued" | "running" | "success" | "failure";
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
+/** Stable product-analytics event categories carried in reserved action metadata. */
+export type ProductAnalyticsKind = "page_view" | "screen_view" | "interaction";
+
+/** Current version of the reserved product-analytics metadata vocabulary. */
+export declare const PRODUCT_ANALYTICS_SCHEMA_VERSION: 1;
+
+/** Product-analytics categories understood by this SDK version. */
+export declare const PRODUCT_ANALYTICS_KINDS: readonly ProductAnalyticsKind[];
+
 /** App-owned product step input for agent-readable action timelines. */
 export type ProductActionInput = string | {
   name: string;
@@ -515,6 +628,7 @@ export type MetricAttributes = {
   unit: string;
   temporality: "delta" | "cumulative";
   metadata?: Metadata;
+  context?: TelemetryContext;
 } | {
   name: string;
   kind: "gauge";
@@ -656,6 +770,8 @@ export declare class LogBrewClient {
     apiKey: string;
     sdkName: string;
     sdkVersion: string;
+    /** Versioned context merged into every captured event; event context can override dynamic fields. */
+    context?: TelemetryContext;
     /** Retry attempts after the first send. Must be a non-negative integer; defaults to 2. */
     maxRetries?: number;
     eventFilter?: EventFilter;
@@ -690,6 +806,10 @@ export declare class LogBrewClient {
   previewJson(): string;
   /** Purge queued events from memory and persistence while no delivery operation is active. */
   purgePendingEvents(): number;
+  /** Add one explicit privacy-bounded breadcrumb to the client's 64-entry issue history. */
+  addBreadcrumb(breadcrumb: IssueBreadcrumbInput, timestamp?: string): void;
+  /** Clear the current issue breadcrumb history and return the number removed. */
+  clearBreadcrumbs(): number;
   release(id: string, timestamp: string, attributes: ReleaseAttributes): void;
   environment(id: string, timestamp: string, attributes: EnvironmentAttributes): void;
   issue(id: string, timestamp: string, attributes: IssueAttributes): void;

package/index.js

@@ -1,6 +1,8 @@
 import sdk from "./index.cjs";
 
 export const {
+  PRODUCT_ANALYTICS_KINDS,
+  PRODUCT_ANALYTICS_SCHEMA_VERSION,
   createBaggage,
   createIssueAttributesFromError,
   createNetworkMilestoneAttributes,

package/issue-diagnostics.cjs

@@ -0,0 +1,267 @@
+"use strict";
+
+const MAX_ISSUE_BREADCRUMBS = 64;
+const MAX_EXCEPTION_TYPE_LENGTH = 256;
+const MAX_MECHANISM_TYPE_LENGTH = 64;
+const MAX_BREADCRUMB_NAME_LENGTH = 64;
+const MAX_BREADCRUMB_MESSAGE_LENGTH = 512;
+const MAX_BREADCRUMB_DATA_FIELDS = 8;
+const MAX_BREADCRUMB_DATA_STRING_LENGTH = 256;
+const MACHINE_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/u;
+const DATA_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/u;
+const BREADCRUMB_LEVEL_ALIASES = new Map([
+  ["trace", "debug"],
+  ["debug", "debug"],
+  ["info", "info"],
+  ["log", "info"],
+  ["warn", "warning"],
+  ["warning", "warning"],
+  ["error", "error"],
+  ["fatal", "critical"],
+  ["critical", "critical"]
+]);
+
+function buildIssueDiagnosticsHelpers({ SdkError, requireTimestamp }) {
+  function validationError(message) {
+    return new SdkError("validation_error", message);
+  }
+
+  function validateIssueException(exception) {
+    if (exception === undefined) {
+      return undefined;
+    }
+    requireObject("issue exception", exception);
+    rejectUnknownKeys("issue exception", exception, new Set(["type", "mechanism"]));
+    const type = boundedText("issue exception type", exception.type, MAX_EXCEPTION_TYPE_LENGTH, {
+      rejectLocationText: true
+    });
+    const mechanism = validateIssueExceptionMechanism(exception.mechanism);
+    return {
+      type,
+      ...(mechanism === undefined ? {} : { mechanism })
+    };
+  }
+
+  function validateIssueExceptionMechanism(mechanism) {
+    if (mechanism === undefined) {
+      return undefined;
+    }
+    requireObject("issue exception mechanism", mechanism);
+    rejectUnknownKeys(
+      "issue exception mechanism",
+      mechanism,
+      new Set(["type", "handled"])
+    );
+    if (typeof mechanism.type !== "string" || !MACHINE_NAME_PATTERN.test(mechanism.type)) {
+      throw validationError(
+        `issue exception mechanism type must match ${MACHINE_NAME_PATTERN}`
+      );
+    }
+    if (Array.from(mechanism.type).length > MAX_MECHANISM_TYPE_LENGTH) {
+      throw validationError(
+        `issue exception mechanism type must be at most ${MAX_MECHANISM_TYPE_LENGTH} characters`
+      );
+    }
+    if (typeof mechanism.handled !== "boolean") {
+      throw validationError("issue exception mechanism handled must be a boolean");
+    }
+    return { type: mechanism.type, handled: mechanism.handled };
+  }
+
+  function createIssueException(type, mechanism, handled) {
+    return validateIssueException({
+      type,
+      mechanism: { type: mechanism, handled }
+    });
+  }
+
+  function validateIssueBreadcrumb(breadcrumb, defaultTimestamp) {
+    requireObject("issue breadcrumb", breadcrumb);
+    rejectUnknownKeys(
+      "issue breadcrumb",
+      breadcrumb,
+      new Set(["timestamp", "type", "category", "level", "message", "data"])
+    );
+    const timestamp = breadcrumb.timestamp ?? defaultTimestamp;
+    requireTimestamp(timestamp);
+    if (typeof breadcrumb.category !== "string" || !MACHINE_NAME_PATTERN.test(breadcrumb.category)) {
+      throw validationError(`issue breadcrumb category must match ${MACHINE_NAME_PATTERN}`);
+    }
+    const type = optionalMachineName("issue breadcrumb type", breadcrumb.type);
+    const level = optionalBreadcrumbLevel(breadcrumb.level);
+    const message = breadcrumb.message === undefined
+      ? undefined
+      : boundedText(
+          "issue breadcrumb message",
+          breadcrumb.message,
+          MAX_BREADCRUMB_MESSAGE_LENGTH
+        );
+    const data = validateBreadcrumbData(breadcrumb.data);
+    return {
+      timestamp,
+      ...(type === undefined ? {} : { type }),
+      category: breadcrumb.category,
+      ...(level === undefined ? {} : { level }),
+      ...(message === undefined ? {} : { message }),
+      ...(data === undefined ? {} : { data })
+    };
+  }
+
+  function validateIssueBreadcrumbs(breadcrumbs) {
+    if (breadcrumbs === undefined) {
+      return undefined;
+    }
+    if (!Array.isArray(breadcrumbs) || breadcrumbs.length < 1 || breadcrumbs.length > MAX_ISSUE_BREADCRUMBS) {
+      throw validationError(
+        `issue breadcrumbs must contain 1-${MAX_ISSUE_BREADCRUMBS} entries`
+      );
+    }
+    return breadcrumbs.map((breadcrumb) => validateIssueBreadcrumb(breadcrumb));
+  }
+
+  function validateIssueDiagnostics(attributes) {
+    const exception = validateIssueException(attributes.exception);
+    const breadcrumbs = validateIssueBreadcrumbs(attributes.breadcrumbs);
+    if (
+      attributes.breadcrumbsTruncated !== undefined
+      && typeof attributes.breadcrumbsTruncated !== "boolean"
+    ) {
+      throw validationError("issue breadcrumbsTruncated must be a boolean");
+    }
+    return {
+      ...(exception === undefined ? {} : { exception }),
+      ...(breadcrumbs === undefined ? {} : { breadcrumbs }),
+      ...(attributes.breadcrumbsTruncated === true ? { breadcrumbsTruncated: true } : {})
+    };
+  }
+
+  function cloneIssueDiagnostics(attributes) {
+    const diagnostics = {};
+    if (attributes.exception !== undefined) {
+      diagnostics.exception = {
+        ...attributes.exception,
+        ...(attributes.exception.mechanism === undefined
+          ? {}
+          : { mechanism: { ...attributes.exception.mechanism } })
+      };
+    }
+    if (Array.isArray(attributes.breadcrumbs)) {
+      diagnostics.breadcrumbs = attributes.breadcrumbs.map((breadcrumb) => ({
+        ...breadcrumb,
+        ...(breadcrumb.data === undefined ? {} : { data: { ...breadcrumb.data } })
+      }));
+    }
+    if (attributes.breadcrumbsTruncated === true) {
+      diagnostics.breadcrumbsTruncated = true;
+    }
+    return diagnostics;
+  }
+
+  function validateBreadcrumbData(data) {
+    if (data === undefined) {
+      return undefined;
+    }
+    requireObject("issue breadcrumb data", data);
+    const entries = Object.entries(data);
+    if (entries.length > MAX_BREADCRUMB_DATA_FIELDS) {
+      throw validationError(
+        `issue breadcrumb data must contain at most ${MAX_BREADCRUMB_DATA_FIELDS} fields`
+      );
+    }
+    const validated = {};
+    for (const [key, value] of entries) {
+      if (!DATA_KEY_PATTERN.test(key)) {
+        throw validationError(`issue breadcrumb data key must match ${DATA_KEY_PATTERN}`);
+      }
+      if (typeof value === "string") {
+        validated[key] = boundedText(
+          `issue breadcrumb data value for ${key}`,
+          value,
+          MAX_BREADCRUMB_DATA_STRING_LENGTH
+        );
+      } else if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+          throw validationError(`issue breadcrumb data value for ${key} must be finite`);
+        }
+        validated[key] = value;
+      } else if (typeof value === "boolean" || value === null) {
+        validated[key] = value;
+      } else {
+        throw validationError(
+          `issue breadcrumb data value for ${key} must be a string, number, boolean, or null`
+        );
+      }
+    }
+    return validated;
+  }
+
+  function optionalMachineName(label, value) {
+    if (value === undefined) {
+      return undefined;
+    }
+    if (typeof value !== "string" || !MACHINE_NAME_PATTERN.test(value)) {
+      throw validationError(`${label} must match ${MACHINE_NAME_PATTERN}`);
+    }
+    if (Array.from(value).length > MAX_BREADCRUMB_NAME_LENGTH) {
+      throw validationError(`${label} must be at most ${MAX_BREADCRUMB_NAME_LENGTH} characters`);
+    }
+    return value;
+  }
+
+  function optionalBreadcrumbLevel(value) {
+    if (value === undefined) {
+      return undefined;
+    }
+    const normalized = typeof value === "string" ? BREADCRUMB_LEVEL_ALIASES.get(value) : undefined;
+    if (normalized === undefined) {
+      throw validationError(
+        `issue breadcrumb level must be one of: ${Array.from(BREADCRUMB_LEVEL_ALIASES.keys()).join(", ")}`
+      );
+    }
+    return normalized;
+  }
+
+  function boundedText(label, value, maxLength, { rejectLocationText = false } = {}) {
+    if (typeof value !== "string" || value.trim() === "") {
+      throw validationError(`${label} must be non-empty`);
+    }
+    if (
+      Array.from(value).length > maxLength
+      || hasControlCharacter(value)
+      || (rejectLocationText && /[?#]/u.test(value))
+    ) {
+      throw validationError(`${label} is invalid or exceeds ${maxLength} characters`);
+    }
+    return value;
+  }
+
+  function requireObject(label, value) {
+    if (!value || Array.isArray(value) || typeof value !== "object") {
+      throw validationError(`${label} must be an object`);
+    }
+  }
+
+  function rejectUnknownKeys(label, value, allowed) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0) {
+      throw validationError(`${label} has unsupported fields: ${unknown.sort().join(", ")}`);
+    }
+  }
+
+  function hasControlCharacter(value) {
+    return Array.from(value).some((character) => {
+      const code = character.codePointAt(0);
+      return code !== undefined && (code <= 31 || (code >= 127 && code <= 159));
+    });
+  }
+
+  return {
+    MAX_ISSUE_BREADCRUMBS,
+    cloneIssueDiagnostics,
+    createIssueException,
+    validateIssueBreadcrumb,
+    validateIssueDiagnostics
+  };
+}
+
+module.exports = { buildIssueDiagnosticsHelpers };