awaitly 1.34.0 → 2.0.0

package/dist/errors-DtXvrCiO.d.ts

@@ -0,0 +1,708 @@
+/**
+ * awaitly/slugs
+ *
+ * Source-of-truth slug namespace. Every concept that surfaces as a runtime
+ * error, lint rule, static-analyzer diagnostic, visualizer event, or skill rule
+ * has exactly one canonical kebab-case slug here.
+ *
+ * Slugs are public API. Renames are a major version bump. Adds are non-breaking.
+ *
+ * Categories:
+ * - step-*       step() discipline
+ * - workflow-*   createWorkflow / run / runWithState shape
+ * - result-*     Result usage
+ * - error-*      Boundary handling
+ * - concurrency-* step.all/map/race vs Promise.*
+ * - runtime-*    Failures only observable at runtime
+ */
+declare const AWAITLY_SLUGS: {
+    readonly "step-require-id": "step-require-id";
+    readonly "step-no-immediate-execution": "step-no-immediate-execution";
+    readonly "step-require-thunk-for-key": "step-require-thunk-for-key";
+    readonly "step-no-bare-await": "step-no-bare-await";
+    readonly "step-no-try-catch-wrap": "step-no-try-catch-wrap";
+    readonly "step-stable-cache-keys": "step-stable-cache-keys";
+    readonly "workflow-no-floating": "workflow-no-floating";
+    readonly "workflow-options-position": "workflow-options-position";
+    readonly "workflow-callback-shape": "workflow-callback-shape";
+    readonly "workflow-no-callable-form": "workflow-no-callable-form";
+    readonly "workflow-no-dynamic-import": "workflow-no-dynamic-import";
+    readonly "workflow-prefer-step-if": "workflow-prefer-step-if";
+    readonly "workflow-prefer-step-foreach": "workflow-prefer-step-foreach";
+    readonly "result-no-floating": "result-no-floating";
+    readonly "result-require-handling": "result-require-handling";
+    readonly "result-no-double-wrap": "result-no-double-wrap";
+    readonly "result-no-manual-propagation": "result-no-manual-propagation";
+    readonly "result-no-direct-ok-err": "result-no-direct-ok-err";
+    readonly "error-check-unexpected-first": "error-check-unexpected-first";
+    readonly "error-access-cause": "error-access-cause";
+    readonly "error-normalize": "error-normalize";
+    readonly "error-no-throw-in-deps": "error-no-throw-in-deps";
+    readonly "concurrency-no-promise-all": "concurrency-no-promise-all";
+    readonly "concurrency-no-promise-race": "concurrency-no-promise-race";
+    readonly "concurrency-no-promise-allsettled": "concurrency-no-promise-allsettled";
+    readonly "runtime-step-timeout": "runtime-step-timeout";
+    readonly "runtime-step-aborted": "runtime-step-aborted";
+    readonly "runtime-retry-exhausted": "runtime-retry-exhausted";
+    readonly "runtime-rate-limit": "runtime-rate-limit";
+    readonly "runtime-circuit-open": "runtime-circuit-open";
+    readonly "runtime-unexpected": "runtime-unexpected";
+    readonly "runtime-resolver-not-found": "runtime-resolver-not-found";
+    readonly "runtime-saga-compensation": "runtime-saga-compensation";
+};
+/** All canonical awaitly slugs as a string-literal union. */
+type AwaitlySlug = keyof typeof AWAITLY_SLUGS;
+/** Categories derived from slug prefixes. */
+type AwaitlySlugCategory = "step" | "workflow" | "result" | "error" | "concurrency" | "runtime";
+/** Returns the category (prefix) of a slug. */
+declare function slugCategory(slug: AwaitlySlug): AwaitlySlugCategory;
+/**
+ * Returns the canonical docs URL for a slug. Resolves to the matching
+ * anchored section on the consolidated rule index page.
+ */
+declare function slugDocsUrl(slug: AwaitlySlug): string;
+/** Type guard: is a string a known awaitly slug? */
+declare function isAwaitlySlug(value: string): value is AwaitlySlug;
+/** All slugs as an array. */
+declare const ALL_SLUGS: readonly AwaitlySlug[];
+
+/**
+ * awaitly/tagged-error
+ *
+ * Factory for creating tagged error types with exhaustive pattern matching.
+ * Enables TypeScript to enforce that all error variants are handled.
+ *
+ * @example
+ * ```typescript
+ * // Define error types (Props via generic)
+ * class NotFoundError extends TaggedError("NotFoundError")<{
+ *   id: string;
+ *   resource: string;
+ * }> {}
+ *
+ * // Define with type-safe message (Props inferred from callback annotation)
+ * class ValidationError extends TaggedError("ValidationError", {
+ *   message: (p: { field: string; reason: string }) => `Invalid ${p.field}: ${p.reason}`,
+ * }) {}
+ *
+ * // Create instances
+ * const error = new NotFoundError({ id: "123", resource: "User" });
+ *
+ * // Runtime type check: instanceof TaggedError works!
+ * console.log(error instanceof TaggedError); // true
+ *
+ * // Exhaustive matching
+ * type AppError = NotFoundError | ValidationError;
+ * const message = TaggedError.match(error as AppError, {
+ *   NotFoundError: (e) => `Missing: ${e.resource} ${e.id}`,
+ *   ValidationError: (e) => `Invalid ${e.field}: ${e.reason}`,
+ * });
+ * ```
+ */
+
+/**
+ * Options for Error constructor (compatible with ES2022 ErrorOptions).
+ */
+interface TaggedErrorOptions {
+    cause?: unknown;
+}
+/**
+ * Options for TaggedError factory with type-safe message callback.
+ */
+interface TaggedErrorCreateOptions<Props extends Record<string, unknown>> {
+    /** Custom message generator from props. Annotate parameter for type safety. */
+    message: (props: Props) => string;
+    /**
+     * Canonical awaitly slug for this error class. When set, instances carry
+     * `code`, `hint`, and `docsUrl` populated from the slugs namespace.
+     * Required together with `hint` for awaitly-system errors.
+     */
+    slug?: AwaitlySlug;
+    /**
+     * One-line "do X instead" guidance shown alongside the error.
+     * Required when `slug` is set.
+     */
+    hint?: string;
+}
+/**
+ * Base interface for all tagged errors.
+ *
+ * `type` is the canonical discriminant (the same key plain tagged-object
+ * errors use, so one `match` works across shapes). `_tag` is a deprecated
+ * alias kept through the migration window.
+ */
+interface TaggedErrorBase extends Error {
+    /** Canonical discriminant — matches the tag passed to TaggedError(tag). */
+    readonly type: string;
+    /** @deprecated Use `type`. Effect-style alias retained for migration. */
+    readonly _tag: string;
+    /** Canonical slug for awaitly-system errors. Undefined for user errors that opt out. */
+    readonly code?: AwaitlySlug;
+    /** One-line guidance. Undefined when no slug is set. */
+    readonly hint?: string;
+    /** Canonical docs URL. Undefined when no slug is set. */
+    readonly docsUrl?: string;
+}
+/**
+ * Instance type for factory-created TaggedErrors.
+ */
+type TaggedErrorInstance<Tag extends string, Props> = TaggedErrorBase & {
+    readonly type: Tag;
+    /** @deprecated Use `type`. */
+    readonly _tag: Tag;
+} & Readonly<Props>;
+/**
+ * Constructor args type - conditionally optional based on whether Props has required fields.
+ * - If Props is empty or all properties are optional: props argument is optional
+ * - If Props has any required properties: props argument is required
+ * @internal
+ */
+type ConstructorArgs<Props extends Record<string, unknown>> = {} extends Props ? [props?: Props | void, options?: TaggedErrorOptions] : [props: Props, options?: TaggedErrorOptions];
+/**
+ * Constructor type returned by TaggedError factory.
+ */
+interface TaggedErrorConstructor<Tag extends string, Props extends Record<string, unknown>> {
+    new (...args: ConstructorArgs<Props>): TaggedErrorInstance<Tag, Props>;
+    readonly prototype: TaggedErrorInstance<Tag, Props>;
+}
+/**
+ * Generic class factory type that allows `<Props>` parameterization.
+ * This enables the Effect.js-style syntax: `class X extends TaggedError("X")<Props> {}`
+ * @internal
+ */
+interface TaggedErrorClassFactory<Tag extends string> {
+    new <Props extends Record<string, unknown> = Record<string, never>>(...args: ConstructorArgs<Props>): TaggedErrorInstance<Tag, Props>;
+}
+/**
+ * Helper type to extract return type from a function type.
+ * @internal
+ */
+type FnReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+/**
+ * Helper type to get union of return types from all handlers.
+ * @internal
+ */
+type HandlersReturnType<H> = {
+    [K in keyof H]: FnReturnType<H[K]>;
+}[keyof H];
+/**
+ * Helper type to extract keys whose values are definitely functions (not undefined).
+ * Only excludes a tag from the fallback type if its handler is guaranteed to be
+ * a function. Keys where the value type includes undefined are NOT excluded,
+ * ensuring type safety with dynamic/conditional handlers.
+ * @internal
+ */
+type DefinitelyHandledKeys<H> = {
+    [K in keyof H]-?: undefined extends H[K] ? never : K;
+}[keyof H];
+/**
+ * Factory function to create tagged error classes.
+ *
+ * Two usage patterns:
+ *
+ * 1. **Props via generic** (default message is tag name):
+ *    ```typescript
+ *    class NotFoundError extends TaggedError("NotFoundError")<{ id: string }> {}
+ *    ```
+ *
+ * 2. **Props inferred from message callback** (type-safe message):
+ *    ```typescript
+ *    class NotFoundError extends TaggedError("NotFoundError", {
+ *      message: (p: { id: string }) => `Not found: ${p.id}`,
+ *    }) {}
+ *    ```
+ *
+ * Both support `instanceof TaggedError` checks at runtime.
+ *
+ * @param tag - The unique tag string for this error type
+ * @param options - Optional configuration with message generator (annotate param for type safety)
+ * @returns A class constructor that can be extended
+ */
+declare function TaggedError<Tag extends string>(tag: Tag): TaggedErrorClassFactory<Tag>;
+declare function TaggedError<Tag extends string, Props extends Record<string, unknown>>(tag: Tag, options: TaggedErrorCreateOptions<Props>): TaggedErrorConstructor<Tag, Props>;
+/**
+ * Namespace for static methods on TaggedError.
+ */
+declare namespace TaggedError {
+    /**
+     * Type guard to check if a value is an Error instance.
+     */
+    function isError(value: unknown): value is Error;
+    /**
+     * Type guard to check if a value is a TaggedError instance.
+     * Uses the same check as `instanceof TaggedError` - only genuine
+     * TaggedError instances (created via the factory) pass this guard.
+     */
+    function isTaggedError(value: unknown): value is TaggedErrorBase;
+    /**
+     * Exhaustively matches on a tagged error, requiring handlers for all variants.
+     *
+     * TypeScript will error if any variant in the error union is not handled.
+     *
+     * @remarks When to use: You want compile-time enforcement that every tagged variant is handled.
+     *
+     * @param error - The tagged error to match
+     * @param handlers - Object mapping _tag values to handler functions
+     * @returns The return value of the matched handler
+     *
+     * @example
+     * ```typescript
+     * type AppError = NotFoundError | ValidationError;
+     *
+     * const message = TaggedError.match(error, {
+     *   NotFoundError: (e) => `Not found: ${e.id}`,
+     *   ValidationError: (e) => `Invalid: ${e.field}`,
+     * });
+     * ```
+     */
+    function match<E extends TaggedErrorBase, H extends {
+        [K in E["_tag"]]: (e: Extract<E, {
+            _tag: K;
+        }>) => unknown;
+    }>(error: E, handlers: H): HandlersReturnType<H>;
+    /**
+     * Partially matches on a tagged error with a fallback for unhandled variants.
+     *
+     * The fallback receives variants that are NOT definitely handled. A tag is
+     * considered "definitely handled" only if its handler is a function (not
+     * `undefined`). This ensures type safety even with dynamic/conditional handlers:
+     *
+     * ```typescript
+     * const maybeHandle = featureFlag ? (e) => e.id : undefined;
+     * TaggedError.matchPartial(
+     *   error,
+     *   { NotFoundError: maybeHandle },  // maybeHandle might be undefined
+     *   (e) => e._tag  // e correctly includes NotFoundError
+     * );
+     * ```
+     *
+     * @param error - The tagged error to match
+     * @param handlers - Partial object mapping _tag values to handler functions
+     * @param otherwise - Fallback handler for unmatched variants
+     * @returns The return value of the matched handler or fallback
+     *
+     * @example
+     * ```typescript
+     * const message = TaggedError.matchPartial(
+     *   error,
+     *   { NotFoundError: (e) => `Not found: ${e.id}` },
+     *   (e) => `Other error: ${e.message}`
+     * );
+     * ```
+     */
+    function matchPartial<E extends TaggedErrorBase, H extends Partial<{
+        [K in E["_tag"]]: (e: Extract<E, {
+            _tag: K;
+        }>) => unknown;
+    }>, T>(error: E, handlers: H, otherwise: (e: Exclude<E, {
+        _tag: DefinitelyHandledKeys<H>;
+    }>) => T): HandlersReturnType<H> | T;
+}
+
+/**
+ * Helper type to extract the _tag literal type from a TaggedError.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends TaggedError("MyError")<{ id: string }> {}
+ * type Tag = TagOf<MyError>; // "MyError"
+ * ```
+ */
+type TagOf<E extends TaggedErrorBase> = E["_tag"];
+/**
+ * Helper type to extract a specific variant from a TaggedError union by tag.
+ *
+ * @example
+ * ```typescript
+ * type AppError = NotFoundError | ValidationError;
+ * type NotFound = ErrorByTag<AppError, "NotFoundError">; // NotFoundError
+ * ```
+ */
+type ErrorByTag<E extends TaggedErrorBase, Tag extends E["_tag"]> = Extract<E, {
+    _tag: Tag;
+}>;
+/**
+ * Reserved keys that are stripped from user props at runtime.
+ * These keys cannot be used as user-defined properties:
+ * - _tag: discriminant for pattern matching
+ * - name, message, stack: Error internals (preserved for logging/debugging)
+ * - code, hint, docsUrl: spine fields (non-configurable own properties when slug is set)
+ *
+ * Note: 'cause' is NOT reserved - it can be used as a user prop.
+ */
+type ReservedErrorKeys = "_tag" | "name" | "message" | "stack" | "code" | "hint" | "docsUrl";
+/**
+ * Helper type to extract props from a TaggedError.
+ * Excludes reserved keys that are stripped at runtime.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends TaggedError("MyError")<{ id: string }> {}
+ * type Props = PropsOf<MyError>; // { id: string }
+ *
+ * // 'cause' is allowed as a user prop
+ * class DomainError extends TaggedError("DomainError")<{ cause: { field: string } }> {}
+ * type DomainProps = PropsOf<DomainError>; // { cause: { field: string } }
+ * ```
+ */
+type PropsOf<E extends TaggedErrorBase> = Omit<E, ReservedErrorKeys>;
+
+/**
+ * awaitly/errors
+ *
+ * Pre-built error types for common failure scenarios.
+ * Uses TaggedError for type-safe exhaustive matching.
+ *
+ * @example
+ * ```typescript
+ * import { TimeoutError, RetryExhaustedError, RateLimitError, CircuitBreakerOpenError } from 'awaitly';
+ *
+ * // Create errors
+ * const timeout = new TimeoutError({ operation: 'fetchUser', ms: 5000 });
+ * const retryFailed = new RetryExhaustedError({ operation: 'sendEmail', attempts: 3 });
+ *
+ * // Pattern match
+ * TaggedError.match(error, {
+ *   TimeoutError: (e) => `${e.operation} timed out after ${e.ms}ms`,
+ *   RetryExhaustedError: (e) => `${e.operation} failed after ${e.attempts} attempts`,
+ *   RateLimitError: (e) => `Rate limit exceeded, retry after ${e.retryAfterMs}ms`,
+ *   CircuitBreakerOpenError: (e) => `Circuit ${e.circuitName} is open`,
+ * });
+ * ```
+ */
+/**
+ * Factory function to create tagged error classes with default values.
+ *
+ * This is a convenience wrapper around TaggedError that allows specifying
+ * default property values for error types.
+ *
+ * @example
+ * ```typescript
+ * const NetworkError = makeError('NetworkError', {
+ *   defaults: { retryable: true },
+ *   message: (p) => `Network error: ${p.reason}`,
+ * });
+ *
+ * class MyNetworkError extends NetworkError<{ reason: string; code?: number }> {}
+ * ```
+ */
+declare function makeError<Tag extends string>(tag: Tag, options?: {
+    message?: (props: Record<string, unknown>) => string;
+    defaults?: Record<string, unknown>;
+}): {
+    new (props?: Record<string, unknown>): {
+        readonly [x: string]: unknown;
+        readonly type: Tag;
+        readonly _tag: Tag;
+        readonly code?: AwaitlySlug;
+        readonly hint?: string;
+        readonly docsUrl?: string;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+};
+declare const TimeoutError_base: TaggedErrorConstructor<"TimeoutError", {
+    /** Name of the operation that timed out */
+    operation?: string;
+    /** Timeout duration in milliseconds */
+    ms: number;
+}>;
+/**
+ * Error thrown when an operation times out.
+ *
+ * @example
+ * ```typescript
+ * const error = new TimeoutError({
+ *   operation: 'fetchUser',
+ *   ms: 5000,
+ * });
+ * console.log(error.message); // "TimeoutError: fetchUser timed out after 5000ms"
+ * ```
+ */
+declare class TimeoutError extends /* @__PURE__ */ TimeoutError_base {
+}
+declare const RetryExhaustedError_base: TaggedErrorConstructor<"RetryExhaustedError", {
+    /** Name of the operation that failed */
+    operation?: string;
+    /** Total number of retry attempts made */
+    attempts: number;
+    /** The last error encountered before giving up */
+    lastError?: unknown;
+}>;
+/**
+ * Error thrown when all retry attempts are exhausted.
+ *
+ * @example
+ * ```typescript
+ * const error = new RetryExhaustedError({
+ *   operation: 'sendEmail',
+ *   attempts: 3,
+ *   lastError: originalError,
+ * });
+ * console.log(error.message); // "RetryExhaustedError: sendEmail failed after 3 attempts"
+ * ```
+ */
+declare class RetryExhaustedError extends /* @__PURE__ */ RetryExhaustedError_base {
+}
+declare const RateLimitError_base: TaggedErrorConstructor<"RateLimitError", {
+    /** Name of the rate limiter that was exceeded */
+    limiterName?: string;
+    /** Time in milliseconds until the rate limit resets */
+    retryAfterMs?: number;
+}>;
+/**
+ * Error thrown when a rate limit is exceeded.
+ *
+ * @example
+ * ```typescript
+ * const error = new RateLimitError({
+ *   limiterName: 'api-calls',
+ *   retryAfterMs: 1000,
+ * });
+ * console.log(error.message); // "RateLimitError: Rate limit exceeded for api-calls"
+ * ```
+ */
+declare class RateLimitError extends /* @__PURE__ */ RateLimitError_base {
+}
+declare const CircuitBreakerOpenError_base: TaggedErrorConstructor<"CircuitBreakerOpenError", {
+    /** Name of the circuit breaker */
+    circuitName: string;
+    /** Current state of the circuit */
+    state?: "OPEN" | "HALF_OPEN";
+    /** Time in milliseconds until the circuit may close */
+    retryAfterMs?: number;
+}>;
+/**
+ * Error thrown when a circuit breaker is open.
+ *
+ * @example
+ * ```typescript
+ * const error = new CircuitBreakerOpenError({
+ *   circuitName: 'payment-api',
+ *   state: 'OPEN',
+ *   retryAfterMs: 30000,
+ * });
+ * console.log(error.message); // "CircuitBreakerOpenError: Circuit payment-api is OPEN"
+ * ```
+ */
+declare class CircuitBreakerOpenError extends /* @__PURE__ */ CircuitBreakerOpenError_base {
+}
+declare const ValidationError_base: TaggedErrorConstructor<"ValidationError", {
+    /** Field that failed validation */
+    field: string;
+    /** Reason for validation failure */
+    reason: string;
+    /** Raw value that failed validation */
+    value?: unknown;
+}>;
+/**
+ * Error thrown when validation fails.
+ *
+ * @example
+ * ```typescript
+ * const error = new ValidationError({
+ *   field: 'email',
+ *   reason: 'Invalid email format',
+ * });
+ * console.log(error.message); // "ValidationError: Invalid email - Invalid email format"
+ * ```
+ */
+declare class ValidationError extends /* @__PURE__ */ ValidationError_base {
+}
+declare const NotFoundError_base: TaggedErrorConstructor<"NotFoundError", {
+    /** Type of resource that was not found */
+    resource: string;
+    /** Identifier of the missing resource */
+    id?: string;
+}>;
+/**
+ * Error thrown when a resource is not found.
+ *
+ * @example
+ * ```typescript
+ * const error = new NotFoundError({
+ *   resource: 'User',
+ *   id: '123',
+ * });
+ * console.log(error.message); // "NotFoundError: User with id 123 not found"
+ * ```
+ */
+declare class NotFoundError extends /* @__PURE__ */ NotFoundError_base {
+}
+declare const UnauthorizedError_base: TaggedErrorConstructor<"UnauthorizedError", {
+    /** Action that was attempted */
+    action?: string;
+    /** Resource that was being accessed */
+    resource?: string;
+    /** Reason for denial */
+    reason?: string;
+}>;
+/**
+ * Error thrown when access is denied.
+ *
+ * @example
+ * ```typescript
+ * const error = new UnauthorizedError({
+ *   action: 'delete',
+ *   resource: 'User',
+ * });
+ * console.log(error.message); // "UnauthorizedError: Not authorized to delete User"
+ * ```
+ */
+declare class UnauthorizedError extends /* @__PURE__ */ UnauthorizedError_base {
+}
+declare const NetworkError_base: TaggedErrorConstructor<"NetworkError", {
+    /** URL that was being accessed */
+    url?: string;
+    /** Reason for the network failure */
+    reason: string;
+    /** Whether this error is retryable */
+    retryable?: boolean;
+    /** HTTP status code if applicable */
+    statusCode?: number;
+}>;
+/**
+ * Error thrown for network-related failures.
+ *
+ * @example
+ * ```typescript
+ * const error = new NetworkError({
+ *   url: 'https://api.example.com/users',
+ *   reason: 'Connection refused',
+ *   retryable: true,
+ * });
+ * ```
+ */
+declare class NetworkError extends /* @__PURE__ */ NetworkError_base {
+}
+declare const CompensationError_base: TaggedErrorConstructor<"CompensationError", {
+    /** Step that triggered compensation */
+    step: string;
+    /** The original error that caused compensation */
+    originalError?: unknown;
+    /** Error that occurred during compensation */
+    compensationError?: unknown;
+}>;
+/**
+ * Error thrown when a saga compensation fails.
+ *
+ * @example
+ * ```typescript
+ * const error = new CompensationError({
+ *   step: 'chargeCard',
+ *   originalError: paymentError,
+ *   compensationError: refundError,
+ * });
+ * ```
+ */
+declare class CompensationError extends /* @__PURE__ */ CompensationError_base {
+}
+declare const UnexpectedError_base: TaggedErrorConstructor<"UnexpectedError", {
+    /** The original thrown value or cancellation error */
+    cause?: unknown;
+}>;
+/**
+ * Default error type for uncaught exceptions and cancellation in workflows.
+ * This is the default `U` type when `catchUnexpected` is not provided.
+ *
+ * @example
+ * ```typescript
+ * // Automatically used as the default — no need to pass catchUnexpected:
+ * const workflow = createWorkflow("checkout", { chargeCard, sendEmail });
+ *
+ * // Equivalent to:
+ * const workflow = createWorkflow("checkout", { chargeCard, sendEmail }, {
+ *   catchUnexpected: (cause) => new UnexpectedError({ cause }),
+ * });
+ * ```
+ */
+declare class UnexpectedError extends /* @__PURE__ */ UnexpectedError_base {
+}
+/**
+ * Union of all pre-built error types.
+ * Useful for exhaustive pattern matching.
+ *
+ * @example
+ * ```typescript
+ * function handleError(error: AwaitlyError): string {
+ *   return TaggedError.match(error, {
+ *     TimeoutError: (e) => `Timeout: ${e.ms}ms`,
+ *     RetryExhaustedError: (e) => `Retries: ${e.attempts}`,
+ *     RateLimitError: (e) => `Rate limited`,
+ *     CircuitBreakerOpenError: (e) => `Circuit open: ${e.circuitName}`,
+ *     ValidationError: (e) => `Invalid: ${e.field}`,
+ *     NotFoundError: (e) => `Not found: ${e.resource}`,
+ *     UnauthorizedError: (e) => `Unauthorized`,
+ *     NetworkError: (e) => `Network: ${e.reason}`,
+ *     CompensationError: (e) => `Compensation failed: ${e.step}`,
+ *     UnexpectedError: (e) => e.message,
+ *   });
+ * }
+ * ```
+ */
+type AwaitlyError = TimeoutError | RetryExhaustedError | RateLimitError | CircuitBreakerOpenError | ValidationError | NotFoundError | UnauthorizedError | NetworkError | CompensationError | UnexpectedError;
+/**
+ * The six awaitly-system errors that carry slug + hint + docsUrl spine fields.
+ *
+ * Distinguishes spine-bearing errors from user-domain convenience errors
+ * (ValidationError, NotFoundError, UnauthorizedError, NetworkError) so that
+ * downstream tooling (lint, analyzer, docs generator) can target the spine
+ * roster without duplicating the class list.
+ */
+type AwaitlySystemError = TimeoutError | RetryExhaustedError | RateLimitError | CircuitBreakerOpenError | CompensationError | UnexpectedError;
+/**
+ * Roster of awaitly-system error classes that participate in the slug spine.
+ *
+ * Adding a new system error means adding it to `AwaitlySystemError`, this
+ * roster, and `slugs.ts`. The integrity test in `spine-integrity.test.ts`
+ * iterates this roster, so a missing entry there is caught at CI time.
+ *
+ * @internal Tooling integration point (docs generator, integrity tests). Not
+ *   a stable user-facing API — application code should not depend on this
+ *   array's identity or order.
+ */
+declare const AWAITLY_SYSTEM_ERROR_CLASSES: ReadonlyArray<new (...args: any[]) => AwaitlySystemError>;
+/**
+ * Check if an error is a TimeoutError.
+ */
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+/**
+ * Check if an error is a RetryExhaustedError.
+ */
+declare function isRetryExhaustedError(error: unknown): error is RetryExhaustedError;
+/**
+ * Check if an error is a RateLimitError.
+ */
+declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Check if an error is a CircuitBreakerOpenError.
+ */
+declare function isCircuitBreakerOpenError(error: unknown): error is CircuitBreakerOpenError;
+/**
+ * Check if an error is a ValidationError.
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Check if an error is a NotFoundError.
+ */
+declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Check if an error is an UnauthorizedError.
+ */
+declare function isUnauthorizedError(error: unknown): error is UnauthorizedError;
+/**
+ * Check if an error is a NetworkError.
+ */
+declare function isNetworkError(error: unknown): error is NetworkError;
+/**
+ * Check if an error is a CompensationError.
+ */
+declare function isCompensationError(error: unknown): error is CompensationError;
+/**
+ * Check if an error is any AwaitlyError.
+ */
+declare function isAwaitlyError(error: unknown): error is AwaitlyError;
+
+export { ALL_SLUGS as A, isValidationError as B, CircuitBreakerOpenError as C, makeError as D, type ErrorByTag as E, slugCategory as F, slugDocsUrl as G, NetworkError as N, type PropsOf as P, RateLimitError as R, TimeoutError as T, UnexpectedError as U, ValidationError as V, AWAITLY_SLUGS as a, AWAITLY_SYSTEM_ERROR_CLASSES as b, type AwaitlyError as c, type AwaitlySlug as d, type AwaitlySlugCategory as e, type AwaitlySystemError as f, CompensationError as g, NotFoundError as h, RetryExhaustedError as i, type TagOf as j, TaggedError as k, type TaggedErrorBase as l, type TaggedErrorConstructor as m, type TaggedErrorCreateOptions as n, type TaggedErrorOptions as o, UnauthorizedError as p, isAwaitlyError as q, isAwaitlySlug as r, isCircuitBreakerOpenError as s, isCompensationError as t, isNetworkError as u, isNotFoundError as v, isRateLimitError as w, isRetryExhaustedError as x, isTimeoutError as y, isUnauthorizedError as z };