feat: add concurrency function and @concurrency decorator

[tabkram]

Goal

Add a concurrency() function and @concurrency() method decorator to bound parallel executions.

const resizeImage = concurrency(
 async (image: Buffer) => imageProcessor.resize(image),
 { limit: 4, maxQueueSize: 100 }
);

Scope

• Configurable limit
• FIFO queue and queue-size visibility
• maxQueueSize with configurable reject/drop behavior
• AbortSignal support for waiting calls
• Per-instance decorator queues and optional shared key
• Unit tests and documentation

Trace integration

Record queue wait time, start/end time, saturation, rejection, and cancellation.

Acceptance criteria

• No more than limit executions run simultaneously
• Queued calls preserve order and their own arguments
• Decorator state is isolated per class instance by default
• Public API is exported from the package entry point

[tabkram]

Proposed TypeScript configuration

export interface ConcurrencyOptions {
 /** Maximum number of executions running at once. */
 limit: number;
 /** Maximum number of calls allowed to wait. Defaults to Infinity. */
 maxQueueSize?: number;
 /** Behavior once maxQueueSize is reached. Defaults to 'reject'. */
 overflow?: 'reject' | 'drop';
 /** Optional name for a queue shared by several wrappers or decorated methods. */
 key?: string | symbol;
 /** Called when a call is accepted into the waiting queue. */
 onEnqueue?: (context: ConcurrencyQueueContext) => void;
 /** Called when a call leaves the waiting queue and starts. */
 onDequeue?: (context: ConcurrencyQueueContext) => void;
}

export interface ConcurrencyQueueContext {
 activeCount: number;
 pendingCount: number;
}

The wrapped function should expose readonly activeCount and pendingCount, plus clearQueue(reason?). Each decorated instance gets an isolated queue unless a shared key is explicitly configured.