feat: add invariant assertion helpers

Add InvariantError class and assertion utilities for runtime validation:
- invariant(condition, message) - throws if condition is falsy, acts as type guard
- assertNever(value) - for exhaustive switch statement checking
- Support for lazy message evaluation to avoid expensive string operations

These helpers enable defensive programming with clear error messages when
invariants are violated.

Closes bd-1w5

src/lib/invariant.ts

@@ -0,0 +1,113 @@
+/**
+ * Invariant assertion helpers for runtime validation.
+ *
+ * These utilities provide type-safe assertions that narrow types and
+ * throw descriptive errors when invariants are violated.
+ */
+
+/**
+ * Custom error class for invariant violations.
+ * Provides a distinct error type that can be caught and identified.
+ */
+export class InvariantError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvariantError";
+
+    // Maintains proper stack trace in V8 environments (Node, Chrome)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, InvariantError);
+    }
+  }
+}
+
+/**
+ * Message can be a string or a function that returns a string.
+ * Using a function allows for lazy evaluation of expensive messages.
+ */
+export type InvariantMessage = string | (() => string);
+
+/**
+ * Assert that a condition is truthy. Throws InvariantError if false.
+ *
+ * This function acts as a type guard - TypeScript will narrow the type
+ * after the assertion. Useful for null/undefined checks.
+ *
+ * @param condition - The condition to check (must be truthy)
+ * @param message - Error message or function returning message
+ * @throws InvariantError if condition is falsy
+ *
+ * @example
+ * ```ts
+ * const user: User | null = getUser();
+ * invariant(user !== null, "User must be logged in");
+ * // TypeScript now knows user is User, not null
+ * console.log(user.name);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Lazy message evaluation for performance
+ * invariant(isValid, () => `Invalid state: ${JSON.stringify(state)}`);
+ * ```
+ */
+export function invariant(
+  condition: unknown,
+  message: InvariantMessage
+): asserts condition {
+  if (!condition) {
+    const errorMessage = typeof message === "function" ? message() : message;
+    throw new InvariantError(errorMessage);
+  }
+}
+
+/**
+ * Assert that a value should never be reached (exhaustive type checking).
+ *
+ * Use this in the default case of switch statements to ensure all
+ * union members are handled. TypeScript will error at compile time
+ * if a case is missing.
+ *
+ * @param value - The value that should be of type `never`
+ * @returns never - This function always throws
+ * @throws InvariantError with a description of the unexpected value
+ *
+ * @example
+ * ```ts
+ * type Status = "pending" | "complete" | "failed";
+ *
+ * function handleStatus(status: Status): string {
+ *   switch (status) {
+ *     case "pending": return "Waiting...";
+ *     case "complete": return "Done!";
+ *     case "failed": return "Error occurred";
+ *     default:
+ *       // If a new status is added, TypeScript will error here
+ *       return assertNever(status);
+ *   }
+ * }
+ * ```
+ */
+export function assertNever(value: never): never {
+  const description = formatValue(value);
+  throw new InvariantError(`Unexpected value: ${description}`);
+}
+
+/**
+ * Format a value for display in error messages.
+ * Handles objects, arrays, and primitives.
+ */
+function formatValue(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+
+  return String(value);
+}