feat: add throttle function and @throttle decorator

[tabkram]

Goal

Add a throttle() function and @throttle() method decorator for sync and async functions.

const fetchProfile = throttle(
 async (userId: string) => api.getProfile(userId),
 { limit: 3, interval: 1_000 }
);

Scope

• Configurable limit and interval
• leading / trailing behavior
• Preserve this, arguments, return type and errors
• Per-instance state for decorated instance methods
• AbortSignal, cancel(), and queue-size visibility
• Unit tests and documentation

Trace integration

Record delayed, executed, cancelled, and rejected calls in the engine trace.

Acceptance criteria

• Supports synchronous and Promise-returning functions
• Concurrent callers retain their original arguments and receive the correct outcome
• Decorator state is isolated per class instance
• Public API is exported from the package entry point

[tabkram]

Proposed TypeScript configuration

export interface ThrottleOptions {
 /** Maximum number of executions allowed during one interval. */
 limit: number;
 /** Rolling or fixed time window, in milliseconds. */
 interval: number;
 /** Execute the first call immediately. Defaults to true. */
 leading?: boolean;
 /** Execute the last queued call at the end of the interval. Defaults to true. */
 trailing?: boolean;
 /** Maximum number of calls waiting to run. Defaults to Infinity. */
 maxQueueSize?: number;
 /** Behavior once maxQueueSize is reached. Defaults to 'reject'. */
 overflow?: 'reject' | 'drop';
 /** Called when a call is delayed because the limit was reached. */
 onDelay?: (context: ThrottleDelayContext) => void;
}

export interface ThrottleDelayContext<Args extends unknown[] = unknown[]> {
 args: Args;
 queueSize: number;
 delay: number;
}

The wrapper should expose cancel(reason?), queueSize, and isEnabled. Per-call cancellation should use an AbortSignal passed at invocation time rather than being stored in shared configuration.