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.