@smoothbricks/lmao 0.1.0

package/dist/lib/errors/RetriesExhausted.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Retries exhausted error - returned when a Blocked error has exceeded max attempts.
+ *
+ * When an Op repeatedly returns `Blocked` and the retry config's `maxAttempts`
+ * is exhausted, the retry layer converts the final failure to `RetriesExhausted`.
+ *
+ * Unlike `Blocked`, this represents a permanent failure that callers must handle
+ * (e.g., compensate, alert, escalate, return error to caller).
+ *
+ * @example
+ * ```typescript
+ * import { defineOpContext, S, Err } from '@smoothbricks/lmao';
+ * import { Blocked } from '@smoothbricks/lmao/errors/Blocked';
+ * import { RetriesExhausted } from '@smoothbricks/lmao/errors/RetriesExhausted';
+ *
+ * const { defineOp } = defineOpContext({
+ *   logSchema: { service: S.category() },
+ *   ctx: { env: null as Env },
+ * });
+ *
+ * // Op that may be blocked by external service
+ * const callPaymentApi = defineOp('callPaymentApi', async (ctx, amount: number) => {
+ *   const health = await checkHealth('payment-api');
+ *   if (!health.available) {
+ *     return new Err(Blocked.service('payment-api'));
+ *   }
+ *   const result = await ctx.deps.http.post('/pay', { amount });
+ *   return ctx.ok(result);
+ * });
+ *
+ * // Caller handles permanent failure after retries exhausted
+ * const result = await trace('checkout', checkoutOp);
+ * if (result.isErr(RetriesExhausted)) {
+ *   ctx.log.error(`Payment failed after ${result.error.attempts} attempts`);
+ *   return ctx.err('PAYMENT_UNAVAILABLE', { service: result.error.reason });
+ * }
+ * ```
+ */
+import type { TaggedError } from '../result.js';
+import { type BlockedReason } from './Blocked.js';
+type RetriesExhaustedView = {
+    _tag: 'RetriesExhausted';
+    reason: BlockedReason;
+    attempts: number;
+    maxAttempts: number;
+};
+export declare class RetriesExhausted extends Error implements TaggedError<'RetriesExhausted'> {
+    /** The original blocked reason */
+    readonly reason: BlockedReason;
+    /** How many attempts were made */
+    readonly attempts: number;
+    /** Max attempts that was configured (the limit that was hit) */
+    readonly maxAttempts: number;
+    static readonly _tag: "RetriesExhausted";
+    get _tag(): 'RetriesExhausted';
+    constructor(
+    /** The original blocked reason */
+    reason: BlockedReason, 
+    /** How many attempts were made */
+    attempts: number, 
+    /** Max attempts that was configured (the limit that was hit) */
+    maxAttempts: number);
+    /** Clean output for JSON.stringify */
+    toJSON(): RetriesExhaustedView;
+}
+export {};
+//# sourceMappingURL=RetriesExhausted.d.ts.map

package/dist/lib/errors/RetriesExhausted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetriesExhausted.d.ts","sourceRoot":"","sources":["../../../src/lib/errors/RetriesExhausted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAwB,MAAM,cAAc,CAAC;AAExE,KAAK,oBAAoB,GAAG;IAC1B,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,qBAAa,gBAAiB,SAAQ,KAAM,YAAW,WAAW,CAAC,kBAAkB,CAAC;IAQlF,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,aAAa;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM;IAZ9B,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAU;IAEnD,IAAI,IAAI,IAAI,kBAAkB,CAE7B;;IAGC,kCAAkC;IACzB,MAAM,EAAE,aAAa;IAC9B,kCAAkC;IACzB,QAAQ,EAAE,MAAM;IACzB,gEAAgE;IACvD,WAAW,EAAE,MAAM;IAW9B,sCAAsC;IACtC,MAAM,IAAI,oBAAoB;CAG/B"}

package/dist/lib/errors/RetriesExhausted.js

@@ -0,0 +1,31 @@
+import { getBlockedReasonName } from './Blocked.js';
+export class RetriesExhausted extends Error {
+    reason;
+    attempts;
+    maxAttempts;
+    static _tag = 'RetriesExhausted';
+    get _tag() {
+        return 'RetriesExhausted';
+    }
+    constructor(
+    /** The original blocked reason */
+    reason, 
+    /** How many attempts were made */
+    attempts, 
+    /** Max attempts that was configured (the limit that was hit) */
+    maxAttempts) {
+        super(`RetriesExhausted: ${getBlockedReasonName(reason)} after ${attempts} attempts`);
+        this.reason = reason;
+        this.attempts = attempts;
+        this.maxAttempts = maxAttempts;
+        this.name = 'RetriesExhausted';
+    }
+    /** Clean output for console.log in Node.js */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return { _tag: this._tag, reason: this.reason, attempts: this.attempts, maxAttempts: this.maxAttempts };
+    }
+    /** Clean output for JSON.stringify */
+    toJSON() {
+        return { _tag: this._tag, reason: this.reason, attempts: this.attempts, maxAttempts: this.maxAttempts };
+    }
+}

package/dist/lib/errors/Transient.d.ts

@@ -0,0 +1,115 @@
+/**
+ * TransientError - typed transient error codes with embedded retry policy.
+ *
+ * Use the `Transient()` factory to define transient error codes WITH default retry policy.
+ * Op class checks `instanceof TransientError` and reads `error.policy` for retry config.
+ *
+ * @example
+ * ```typescript
+ * import { Transient, exponentialBackoff, fixedDelay } from '@smoothbricks/lmao/errors/Transient';
+ *
+ * // Define error with default exponential backoff (5 attempts)
+ * const SERVICE_UNAVAILABLE = Transient<{ service: string }>('SERVICE_UNAVAILABLE', exponentialBackoff(5));
+ *
+ * // Define error with fixed delay for rate limiting
+ * const RATE_LIMITED = Transient<{ retryAfter?: number }>('RATE_LIMITED', fixedDelay(3, 5000));
+ *
+ * // Usage - data only, uses default policy
+ * ctx.err(SERVICE_UNAVAILABLE({ service: 'api' }));
+ *
+ * // Override policy for this specific call (e.g., use Retry-After header)
+ * ctx.err(RATE_LIMITED({ retryAfter: 60000 }, fixedDelay(1, 60000)));
+ *
+ * // Op class detects transient and reads policy
+ * if (result.error instanceof TransientError) {
+ *   const { maxAttempts, backoff, baseDelayMs } = result.error.policy;
+ *   // Execute retry loop based on policy
+ * }
+ * ```
+ */
+import type { TaggedErrorConstructor } from '../result.js';
+import { CodeError } from './CodeError.js';
+import { type RetryPolicy } from './retry-policy.js';
+/**
+ * Transient error instance - triggers retry in Op class.
+ *
+ * Extends CodeError to inherit code/data pattern while adding:
+ * - `instanceof TransientError` checks for retry classification
+ * - `policy` field carrying merged retry configuration
+ *
+ * @typeParam C - The error code string literal type (also serves as _tag)
+ * @typeParam D - The data payload type
+ */
+export declare class TransientError<C extends string, D = void> extends CodeError<C, D> {
+    /**
+     * Merged retry policy (defaultPolicy + per-call override).
+     * Op class reads this to configure retry loop.
+     */
+    readonly policy: RetryPolicy;
+    constructor(code: C, data: D, policy: RetryPolicy);
+    toJSON(): {
+        policy: RetryPolicy;
+        code: C;
+        data: D;
+    };
+}
+/**
+ * Constructor function for a specific transient error code.
+ * Has static `_tag` for isErr() and `defaultPolicy` for introspection.
+ */
+export interface TransientConstructor<C extends string, D = void> extends TaggedErrorConstructor<TransientError<C, D>> {
+    /** Create transient error with data and optional policy override */
+    (data: D, policyOverride?: Partial<RetryPolicy>): TransientError<C, D>;
+    /** Error code (same as _tag) */
+    readonly _tag: C;
+    /** Default retry policy for this error type */
+    readonly defaultPolicy: RetryPolicy;
+}
+/**
+ * Constructor function for transient error codes with no data.
+ */
+export interface TransientConstructorVoid<C extends string> extends TaggedErrorConstructor<TransientError<C, void>> {
+    /** Create transient error with optional policy override */
+    (policyOverride?: Partial<RetryPolicy>): TransientError<C, void>;
+    /** Error code (same as _tag) */
+    readonly _tag: C;
+    /** Default retry policy for this error type */
+    readonly defaultPolicy: RetryPolicy;
+}
+type TransientFactoryReturn<C extends string, D> = [unknown] extends [D] ? TransientConstructor<C, D> : undefined extends D ? TransientConstructorVoid<C> : TransientConstructor<C, D>;
+/**
+ * Define a typed transient error code with default retry policy.
+ *
+ * Creates errors that extend TransientError, enabling:
+ * - `instanceof TransientError` for retry triggering
+ * - `result.isErr(CODE)` for specific code discrimination
+ * - `error.policy` for retry configuration
+ *
+ * @param code - The error code string (becomes _tag for discrimination)
+ * @param defaultPolicy - Default retry policy for this error type
+ * @returns A constructor function that creates TransientError instances
+ *
+ * @example
+ * ```typescript
+ * // With typed data and exponential backoff
+ * const NETWORK_ERROR = Transient<{ service: string }>('NETWORK_ERROR', exponentialBackoff(5));
+ * ctx.err(NETWORK_ERROR({ service: 'payment-api' }));
+ *
+ * // Without data, linear backoff
+ * const TIMEOUT = Transient('TIMEOUT', linearBackoff(3));
+ * ctx.err(TIMEOUT());
+ *
+ * // Override policy per-call
+ * ctx.err(NETWORK_ERROR({ service: 'api' }, fixedDelay(1, 30000)));
+ *
+ * // Op class handles retry
+ * if (result.error instanceof TransientError) {
+ *   const { policy } = result.error;
+ *   // Retry loop using policy.maxAttempts, policy.backoff, etc.
+ * }
+ * ```
+ */
+export declare function Transient<C extends string>(code: C, defaultPolicy: RetryPolicy): TransientConstructorVoid<C>;
+export declare function Transient<D, C extends string = string>(code: C, defaultPolicy: RetryPolicy): TransientFactoryReturn<C, D>;
+export { exponentialBackoff, fixedDelay, linearBackoff, mergePolicy, type RetryPolicy } from './retry-policy.js';
+//# sourceMappingURL=Transient.d.ts.map

package/dist/lib/errors/Transient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transient.d.ts","sourceRoot":"","sources":["../../../src/lib/errors/Transient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;;;;;;;GASG;AACH,qBAAa,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,IAAI,CAAE,SAAQ,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7E;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;gBAEjB,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW;IAMxC,MAAM;;;;;CAMhB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,IAAI,CAAE,SAAQ,sBAAsB,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpH,oEAAoE;IACpE,CAAC,IAAI,EAAE,CAAC,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvE,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAE,SAAQ,sBAAsB,CAAC,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACjH,2DAA2D;IAC3D,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACjE,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC;CACrC;AAED,KAAK,sBAAsB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GACpE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC1B,SAAS,SAAS,CAAC,GACjB,wBAAwB,CAAC,CAAC,CAAC,GAC3B,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,aAAa,EAAE,WAAW,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAAC;AAC9G,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EACpD,IAAI,EAAE,CAAC,EACP,aAAa,EAAE,WAAW,GACzB,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAmChC,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/lib/errors/Transient.js

@@ -0,0 +1,54 @@
+import { CodeError } from './CodeError.js';
+import { mergePolicy } from './retry-policy.js';
+/**
+ * Transient error instance - triggers retry in Op class.
+ *
+ * Extends CodeError to inherit code/data pattern while adding:
+ * - `instanceof TransientError` checks for retry classification
+ * - `policy` field carrying merged retry configuration
+ *
+ * @typeParam C - The error code string literal type (also serves as _tag)
+ * @typeParam D - The data payload type
+ */
+export class TransientError extends CodeError {
+    /**
+     * Merged retry policy (defaultPolicy + per-call override).
+     * Op class reads this to configure retry loop.
+     */
+    policy;
+    constructor(code, data, policy) {
+        super(code, data);
+        this.name = 'TransientError';
+        this.policy = policy;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            policy: this.policy,
+        };
+    }
+}
+export function Transient(code, defaultPolicy) {
+    function createTransientError(dataOrOverride, maybeOverride) {
+        const override = maybeOverride !== undefined ? maybeOverride : isRetryPolicyLike(dataOrOverride) ? dataOrOverride : undefined;
+        const data = maybeOverride !== undefined || override !== undefined ? undefined : dataOrOverride;
+        const mergedPolicy = mergePolicy(defaultPolicy, override);
+        return new TransientError(code, data, mergedPolicy);
+    }
+    return Object.assign(createTransientError, {
+        _tag: code,
+        defaultPolicy,
+    });
+}
+/**
+ * Type guard to check if value looks like a RetryPolicy (partial).
+ * Used to disambiguate void data + override from actual data.
+ */
+function isRetryPolicyLike(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    // Check for RetryPolicy-specific keys — `in` accepts `object`, no cast needed
+    return ('backoff' in value || 'maxAttempts' in value || 'baseDelayMs' in value || 'maxDelayMs' in value || 'jitter' in value);
+}
+// Re-export policy helpers for convenience
+export { exponentialBackoff, fixedDelay, linearBackoff, mergePolicy } from './retry-policy.js';

package/dist/lib/errors/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error types and utilities for LMAO.
+ *
+ * @example
+ * ```typescript
+ * import { Code, CodeError, Transient, TransientError, Blocked, exponentialBackoff } from '@smoothbricks/lmao/errors';
+ * ```
+ */
+export * from './Blocked.js';
+export * from './CodeError.js';
+export * from './RetriesExhausted.js';
+export { exponentialBackoff, fixedDelay, linearBackoff, mergePolicy, type RetryPolicy as TransientRetryPolicy, } from './retry-policy.js';
+export { Transient, type TransientConstructor, type TransientConstructorVoid, TransientError } from './Transient.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,cAAc,CAAC;AAE7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AAItC,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,WAAW,EACX,KAAK,WAAW,IAAI,oBAAoB,GACzC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,SAAS,EAAE,KAAK,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/lib/errors/index.js

@@ -0,0 +1,16 @@
+/**
+ * Error types and utilities for LMAO.
+ *
+ * @example
+ * ```typescript
+ * import { Code, CodeError, Transient, TransientError, Blocked, exponentialBackoff } from '@smoothbricks/lmao/errors';
+ * ```
+ */
+export * from './Blocked.js';
+// Existing exports
+export * from './CodeError.js';
+export * from './RetriesExhausted.js';
+// Phase 19 exports - TransientError uses RetryPolicy from retry-policy.ts
+// Export with different name to avoid conflict with other retry configs
+export { exponentialBackoff, fixedDelay, linearBackoff, mergePolicy, } from './retry-policy.js';
+export { Transient, TransientError } from './Transient.js';

package/dist/lib/errors/retry-policy.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RetryPolicy - configures retry behavior for transient failures.
+ *
+ * Carried by TransientError instances. Op class (in LMAO) reads policy
+ * from transient errors to handle retry loop.
+ *
+ * @example
+ * ```typescript
+ * // Define error with default policy
+ * const RATE_LIMITED = Transient<{ retryAfter?: number }>('RATE_LIMITED', exponentialBackoff(5));
+ *
+ * // Usage with default policy
+ * ctx.err(RATE_LIMITED({ retryAfter: 60000 }));
+ *
+ * // Override policy for this call
+ * ctx.err(RATE_LIMITED({ retryAfter: 60000 }, fixedDelay(1, 60000)));
+ * ```
+ */
+export interface RetryPolicy {
+    /** Backoff strategy */
+    backoff: 'exponential' | 'linear' | 'fixed';
+    /** Maximum retry attempts (including initial attempt) */
+    maxAttempts: number;
+    /** Base delay in milliseconds */
+    baseDelayMs: number;
+    /** Maximum delay cap in milliseconds (optional, defaults to 30000) */
+    maxDelayMs?: number;
+    /** Add randomness to delay (default: true) */
+    jitter?: boolean;
+}
+/**
+ * Create linear backoff policy.
+ * Delay increases linearly: baseDelay * attempt
+ *
+ * @example linearBackoff(3) → 100ms, 200ms, 300ms
+ * @example linearBackoff(5, 200) → 200ms, 400ms, 600ms, 800ms, 1000ms
+ */
+export declare function linearBackoff(maxAttempts: number, baseDelayMs?: number): RetryPolicy;
+/**
+ * Create exponential backoff policy.
+ * Delay doubles each attempt: baseDelay * 2^(attempt-1)
+ *
+ * @example exponentialBackoff(3) → 100ms, 200ms, 400ms
+ * @example exponentialBackoff(5, 50) → 50ms, 100ms, 200ms, 400ms, 800ms
+ */
+export declare function exponentialBackoff(maxAttempts: number, baseDelayMs?: number): RetryPolicy;
+/**
+ * Create fixed delay policy.
+ * Same delay between each attempt.
+ *
+ * @example fixedDelay(3, 1000) → 1000ms, 1000ms, 1000ms
+ * @example fixedDelay(1, 60000) → single retry after 60s (for rate limit Retry-After)
+ */
+export declare function fixedDelay(maxAttempts: number, delayMs?: number): RetryPolicy;
+/**
+ * Merge base policy with override.
+ * Override fields take precedence.
+ */
+export declare function mergePolicy(base: RetryPolicy, override?: Partial<RetryPolicy>): RetryPolicy;
+//# sourceMappingURL=retry-policy.d.ts.map

package/dist/lib/errors/retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.d.ts","sourceRoot":"","sources":["../../../src/lib/errors/retry-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,OAAO,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC5C,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,SAAM,GAAG,WAAW,CAOjF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,SAAM,GAAG,WAAW,CAOtF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,WAAW,CAO3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAG3F"}

package/dist/lib/errors/retry-policy.js

@@ -0,0 +1,54 @@
+/**
+ * Create linear backoff policy.
+ * Delay increases linearly: baseDelay * attempt
+ *
+ * @example linearBackoff(3) → 100ms, 200ms, 300ms
+ * @example linearBackoff(5, 200) → 200ms, 400ms, 600ms, 800ms, 1000ms
+ */
+export function linearBackoff(maxAttempts, baseDelayMs = 100) {
+    return {
+        backoff: 'linear',
+        maxAttempts,
+        baseDelayMs,
+        jitter: true,
+    };
+}
+/**
+ * Create exponential backoff policy.
+ * Delay doubles each attempt: baseDelay * 2^(attempt-1)
+ *
+ * @example exponentialBackoff(3) → 100ms, 200ms, 400ms
+ * @example exponentialBackoff(5, 50) → 50ms, 100ms, 200ms, 400ms, 800ms
+ */
+export function exponentialBackoff(maxAttempts, baseDelayMs = 100) {
+    return {
+        backoff: 'exponential',
+        maxAttempts,
+        baseDelayMs,
+        jitter: true,
+    };
+}
+/**
+ * Create fixed delay policy.
+ * Same delay between each attempt.
+ *
+ * @example fixedDelay(3, 1000) → 1000ms, 1000ms, 1000ms
+ * @example fixedDelay(1, 60000) → single retry after 60s (for rate limit Retry-After)
+ */
+export function fixedDelay(maxAttempts, delayMs = 1000) {
+    return {
+        backoff: 'fixed',
+        maxAttempts,
+        baseDelayMs: delayMs,
+        jitter: false, // Fixed delay typically doesn't want jitter
+    };
+}
+/**
+ * Merge base policy with override.
+ * Override fields take precedence.
+ */
+export function mergePolicy(base, override) {
+    if (!override)
+        return base;
+    return { ...base, ...override };
+}

package/dist/lib/flushScheduler.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Background flush scheduler with adaptive flushing
+ *
+ * Per specs/lmao/01b2_buffer_self_tuning.md:
+ * - Adaptive flush intervals based on capacity, time, memory pressure
+ * - Idle detection for opportunistic flushing
+ * - Background processing (cold path)
+ */
+import { type Table } from '@uwdata/flechette';
+import type { AnySpanBuffer } from './types.js';
+/**
+ * Flush handler function type
+ * Called when buffers are ready to be flushed
+ */
+export type FlushHandler = (table: Table, metadata: FlushMetadata) => Promise<void> | void;
+/**
+ * Metadata about the flush operation
+ */
+export interface FlushMetadata {
+    totalRows: number;
+    totalBuffers: number;
+    flushReason: 'capacity' | 'time' | 'memory' | 'idle' | 'manual';
+    timestamp: number;
+}
+/**
+ * Flush scheduler configuration
+ */
+export interface FlushSchedulerConfig {
+    /**
+     * Maximum time between flushes (milliseconds)
+     * Default: 10000 (10 seconds)
+     */
+    maxFlushInterval?: number;
+    /**
+     * Minimum time between flushes (milliseconds)
+     * Default: 1000 (1 second)
+     */
+    minFlushInterval?: number;
+    /**
+     * Capacity threshold for automatic flush (0.0 - 1.0)
+     * Flush when buffer is X% full
+     * Default: 0.8 (80%)
+     */
+    capacityThreshold?: number;
+    /**
+     * Enable idle detection for opportunistic flushing
+     * Default: true
+     */
+    idleDetection?: boolean;
+    /**
+     * Idle timeout (milliseconds) - flush if no activity for this duration
+     * Default: 5000 (5 seconds)
+     */
+    idleTimeout?: number;
+    /**
+     * Enable memory pressure detection
+     * Default: true (Node.js only)
+     */
+    memoryPressureDetection?: boolean;
+    /**
+     * Memory pressure threshold (bytes)
+     * Flush when available memory drops below this
+     * Default: 100MB
+     */
+    memoryPressureThreshold?: number;
+}
+/**
+ * Background flush scheduler
+ * Manages automatic flushing of span buffers to Arrow tables
+ */
+export declare class FlushScheduler {
+    private config;
+    private handler;
+    private buffers;
+    private lastFlushTime;
+    private lastActivityTime;
+    private flushTimer?;
+    private idleTimer?;
+    private memoryTimer?;
+    private isRunning;
+    /** Flush counter for periodic capacity stats logging */
+    private _flushCount;
+    /**
+     * Track unique (SpanBufferConstructor, OpMetadata) pairs that have been flushed since last capacity stats log.
+     * We use SpanBufferConstructor as the key (for dedup) and store the OpMetadata for building PreEncodedEntry at conversion time.
+     * The constructor has static stats property with the capacity stats we need.
+     */
+    private _bufferClassesSinceLastStatsLog;
+    constructor(handler: FlushHandler, config?: FlushSchedulerConfig);
+    /**
+     * Register a buffer for automatic flushing
+     */
+    register(buffer: AnySpanBuffer): void;
+    /**
+     * Start the flush scheduler
+     */
+    start(): void;
+    /**
+     * Stop the flush scheduler
+     */
+    stop(): void;
+    /**
+     * Manually trigger a flush
+     */
+    flush(): Promise<void>;
+    /**
+     * Check flush conditions and flush if needed
+     */
+    private checkFlushConditions;
+    /**
+     * Check if should flush based on capacity
+     */
+    private shouldFlushByCapacity;
+    /**
+     * Check idle state and flush if idle
+     */
+    private checkIdleFlush;
+    /**
+     * Check memory pressure and flush if needed
+     * Node.js only
+     */
+    private checkMemoryPressure;
+    /**
+     * Perform the actual flush operation
+     */
+    private doFlush;
+    /**
+     * Record activity (called when buffers are written to)
+     */
+    recordActivity(): void;
+}
+/**
+ * Get or create global flush scheduler
+ */
+export declare function getGlobalFlushScheduler(handler: FlushHandler, config?: FlushSchedulerConfig): FlushScheduler;
+/**
+ * Reset global flush scheduler (for testing)
+ */
+export declare function resetGlobalFlushScheduler(): void;
+/**
+ * Test utilities for accessing FlushScheduler internals
+ * @internal
+ */
+export declare const FlushSchedulerTestUtils: {
+    /**
+     * Get the flush timer for a scheduler instance (for testing)
+     */
+    getFlushTimer(scheduler: FlushScheduler): NodeJS.Timeout | undefined;
+    /**
+     * Set the flush timer for a scheduler instance (for testing)
+     */
+    setFlushTimer(scheduler: FlushScheduler, timer: NodeJS.Timeout | undefined): void;
+    /**
+     * Get the last activity time for a scheduler instance (for testing)
+     */
+    getLastActivityTime(scheduler: FlushScheduler): number | undefined;
+    /**
+     * Set the last activity time for a scheduler instance (for testing)
+     */
+    setLastActivityTime(scheduler: FlushScheduler, time: number | null | undefined): void;
+};
+//# sourceMappingURL=flushScheduler.d.ts.map

package/dist/lib/flushScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flushScheduler.d.ts","sourceRoot":"","sources":["../../src/lib/flushScheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAU,KAAK,KAAK,EAAoB,MAAM,mBAAmB,CAAC;AAIzE,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,YAAY,CAAC;AAiC5D;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,OAAO,CAAe;IAE9B,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,gBAAgB,CAAc;IACtC,OAAO,CAAC,UAAU,CAAC,CAAiB;IACpC,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,WAAW,CAAC,CAAiB;IACrC,OAAO,CAAC,SAAS,CAAS;IAE1B,wDAAwD;IACxD,OAAO,CAAC,WAAW,CAAK;IAExB;;;;OAIG;IACH,OAAO,CAAC,+BAA+B,CAAgD;gBAE3E,OAAO,EAAE,YAAY,EAAE,MAAM,GAAE,oBAAyB;IAepE;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAUrC;;OAEG;IACH,KAAK,IAAI,IAAI;IA2Bb;;OAEG;IACH,IAAI,IAAI,IAAI;IAqBZ;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiB5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAU7B;;OAEG;IACH,OAAO,CAAC,cAAc;IAatB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;OAEG;YACW,OAAO;IA+IrB;;OAEG;IACH,cAAc,IAAI,IAAI;CAGvB;AAQD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAK5G;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAKhD;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB;IAClC;;OAEG;6BACsB,cAAc,GAAG,MAAM,CAAC,OAAO,GAAG,SAAS;IAKpE;;OAEG;6BACsB,cAAc,SAAS,MAAM,CAAC,OAAO,GAAG,SAAS,GAAG,IAAI;IAIjF;;OAEG;mCAC4B,cAAc,GAAG,MAAM,GAAG,SAAS;IAKlE;;OAEG;mCAC4B,cAAc,QAAQ,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;CAGtF,CAAC"}