@mrjacket/ahko 1.0.0 → 1.1.5

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,24 +17,43 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AdaptiveCoordinator: () => AdaptiveCoordinator,
   Ahko: () => Ahko,
   AhkoCancellationError: () => AhkoCancellationError,
+  AhkoCircuitBreakerOpenError: () => AhkoCircuitBreakerOpenError,
   AhkoConfigurationError: () => AhkoConfigurationError,
   AhkoError: () => AhkoError,
   AhkoQueueError: () => AhkoQueueError,
   AhkoTimeoutError: () => AhkoTimeoutError,
+  CircuitBreakerCoordinator: () => CircuitBreakerCoordinator,
   DEFAULT_BASE_DELAY: () => DEFAULT_BASE_DELAY,
   DEFAULT_MAX_DELAY: () => DEFAULT_MAX_DELAY,
+  ECircuitState: () => ECircuitState,
   EScheduleStrategy: () => EScheduleStrategy,
   ETaskState: () => ETaskState,
+  TASK_PRIORITY_WEIGHTS: () => TASK_PRIORITY_WEIGHTS,
   VERSION: () => VERSION,
   calculateBackoff: () => calculateBackoff,
-  combineSignals: () => combineSignals
+  combineSignals: () => combineSignals,
+  getActiveConfig: () => getActiveConfig,
+  getProfileConfig: () => getProfileConfig,
+  loadConfig: () => loadConfig,
+  loadConfigFile: () => loadConfigFile,
+  resetConfig: () => resetConfig,
+  resolvePriorityWeight: () => resolvePriorityWeight
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -51,6 +72,21 @@ var AhkoError = class extends Error {
   }
 };
 
+// src/errors/cancellation.error.ts
+var AhkoCancellationError = class extends AhkoError {
+  /**
+   * Creates a new AhkoCancellationError.
+   *
+   * @param message - Reason for cancellation.
+   * @param options - Standard Error options including cause.
+   */
+  constructor(message = "Task was cancelled", options) {
+    super(message, options);
+    this.name = "AhkoCancellationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
 // src/errors/configuration.error.ts
 var AhkoConfigurationError = class extends AhkoError {
   /**
@@ -66,6 +102,72 @@ var AhkoConfigurationError = class extends AhkoError {
   }
 };
 
+// src/config/config-loader.ts
+var activeConfig;
+function loadConfig(config) {
+  activeConfig = { ...config };
+}
+function resetConfig() {
+  activeConfig = void 0;
+}
+async function loadConfigFile(filePath = "config.ahko.json") {
+  if (typeof process === "undefined" || !process.versions?.node) {
+    return void 0;
+  }
+  try {
+    const { readFile } = await import("fs/promises");
+    const { resolve } = await import("path");
+    const resolvedPath = resolve(process.cwd(), filePath);
+    const content = await readFile(resolvedPath, "utf-8");
+    const parsed = JSON.parse(content);
+    activeConfig = parsed;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+function tryAutoDiscoverSync() {
+  if (activeConfig !== void 0 || typeof process === "undefined" || !process.versions?.node) {
+    return;
+  }
+  try {
+    let fs = null;
+    let path = null;
+    if (typeof process.getBuiltinModule === "function") {
+      const getBuiltin = process.getBuiltinModule;
+      fs = getBuiltin("node:fs");
+      path = getBuiltin("node:path");
+    } else if (typeof require === "function") {
+      fs = require("fs");
+      path = require("path");
+    }
+    if (fs && path) {
+      const configPath = path.resolve(process.cwd(), "config.ahko.json");
+      if (fs.existsSync(configPath)) {
+        const raw = fs.readFileSync(configPath, "utf-8");
+        activeConfig = JSON.parse(raw);
+      }
+    }
+  } catch {
+  }
+}
+function getActiveConfig() {
+  if (activeConfig === void 0) {
+    tryAutoDiscoverSync();
+  }
+  return activeConfig;
+}
+function getProfileConfig(profileName) {
+  const config = getActiveConfig();
+  if (!config) {
+    return void 0;
+  }
+  if (profileName) {
+    return config.profiles?.[profileName];
+  }
+  return config.default;
+}
+
 // src/models/strategy.model.ts
 var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
   EScheduleStrategy2["IMMEDIATE"] = "immediate";
@@ -76,6 +178,23 @@ var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
   return EScheduleStrategy2;
 })(EScheduleStrategy || {});
 
+// src/errors/circuit-breaker.error.ts
+var AhkoCircuitBreakerOpenError = class extends AhkoError {
+  /** Time remaining in milliseconds before trial execution is allowed */
+  resetTimeoutMs;
+  /** Timestamp when the circuit tripped open */
+  trippedAt;
+  /** Total consecutive failures that caused the trip */
+  consecutiveFailures;
+  constructor(message = "Circuit breaker is open. Fast-failing task execution to protect downstream resources.", options) {
+    super(message);
+    this.name = "AhkoCircuitBreakerOpenError";
+    this.resetTimeoutMs = options?.resetTimeoutMs;
+    this.trippedAt = options?.trippedAt;
+    this.consecutiveFailures = options?.consecutiveFailures;
+  }
+};
+
 // src/errors/timeout.error.ts
 var AhkoTimeoutError = class extends AhkoError {
   /**
@@ -96,6 +215,28 @@ var AhkoTimeoutError = class extends AhkoError {
   }
 };
 
+// src/models/priority.model.ts
+var TASK_PRIORITY_WEIGHTS = {
+  high: 10,
+  normal: 0,
+  low: -10
+};
+function resolvePriorityWeight(priority) {
+  if (priority === void 0) {
+    return TASK_PRIORITY_WEIGHTS.normal;
+  }
+  if (typeof priority === "number") {
+    return Number.isFinite(priority) ? priority : TASK_PRIORITY_WEIGHTS.normal;
+  }
+  if (priority === "high") {
+    return TASK_PRIORITY_WEIGHTS.high;
+  }
+  if (priority === "low") {
+    return TASK_PRIORITY_WEIGHTS.low;
+  }
+  return TASK_PRIORITY_WEIGHTS.normal;
+}
+
 // src/models/state.model.ts
 var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   ETaskState2["PENDING"] = "pending";
@@ -132,18 +273,251 @@ function calculateBackoff(attempt, options, randomFn = Math.random) {
   return Math.floor(cappedDelay);
 }
 
-// src/errors/cancellation.error.ts
-var AhkoCancellationError = class extends AhkoError {
+// src/scheduler/adaptive-coordinator.ts
+var AdaptiveCoordinator = class {
+  _currentConcurrency;
+  minConcurrency;
+  maxConcurrency;
+  targetLatencyMs;
+  sampleWindowSize;
+  backoffFactor;
+  recentDurations = [];
+  lastAverageLatencyMs = 0;
+  onConcurrencyChange;
   /**
-   * Creates a new AhkoCancellationError.
+   * Initializes a new AdaptiveCoordinator instance.
    *
-   * @param message - Reason for cancellation.
-   * @param options - Standard Error options including cause.
+   * @param options - Adaptive concurrency configuration options.
+   * @param initialConcurrency - Starting scheduler concurrency limit.
+   * @param onConcurrencyChange - Callback invoked when concurrency changes.
+   * @throws {AhkoConfigurationError} If options are invalid.
    */
-  constructor(message = "Task was cancelled", options) {
-    super(message, options);
-    this.name = "AhkoCancellationError";
-    Object.setPrototypeOf(this, new.target.prototype);
+  constructor(options, initialConcurrency, onConcurrencyChange) {
+    if (typeof options.targetLatencyMs !== "number" || Number.isNaN(options.targetLatencyMs) || !Number.isFinite(options.targetLatencyMs) || options.targetLatencyMs <= 0) {
+      throw new AhkoConfigurationError(
+        `Invalid targetLatencyMs "${options.targetLatencyMs}". targetLatencyMs must be a positive number greater than 0.`
+      );
+    }
+    const min = options.minConcurrency ?? 1;
+    if (typeof min !== "number" || Number.isNaN(min) || min < 1 || !Number.isInteger(min)) {
+      throw new AhkoConfigurationError(
+        `Invalid minConcurrency "${min}". minConcurrency must be an integer greater than or equal to 1.`
+      );
+    }
+    const defaultMax = Number.isFinite(initialConcurrency) ? Math.max(min, initialConcurrency * 2) : Math.max(min, 10);
+    const max = options.maxConcurrency ?? defaultMax;
+    if (typeof max !== "number" || Number.isNaN(max) || max < min || !Number.isInteger(max)) {
+      throw new AhkoConfigurationError(
+        `Invalid maxConcurrency "${max}". maxConcurrency must be an integer greater than or equal to minConcurrency (${min}).`
+      );
+    }
+    const windowSize = options.sampleWindowSize ?? 5;
+    if (typeof windowSize !== "number" || Number.isNaN(windowSize) || windowSize < 1 || !Number.isInteger(windowSize)) {
+      throw new AhkoConfigurationError(
+        `Invalid sampleWindowSize "${windowSize}". sampleWindowSize must be an integer greater than or equal to 1.`
+      );
+    }
+    const factor = options.backoffFactor ?? 0.7;
+    if (typeof factor !== "number" || Number.isNaN(factor) || factor <= 0.1 || factor >= 0.99) {
+      throw new AhkoConfigurationError(
+        `Invalid backoffFactor "${factor}". backoffFactor must be a number between 0.1 and 0.99.`
+      );
+    }
+    this.minConcurrency = min;
+    this.maxConcurrency = max;
+    this.targetLatencyMs = options.targetLatencyMs;
+    this.sampleWindowSize = windowSize;
+    this.backoffFactor = factor;
+    this.onConcurrencyChange = onConcurrencyChange;
+    const clampedInitial = Number.isFinite(initialConcurrency) ? Math.min(Math.max(initialConcurrency, min), max) : min;
+    this._currentConcurrency = clampedInitial;
+  }
+  /**
+   * Current effective concurrency limit dictated by the adaptive controller.
+   */
+  get currentConcurrency() {
+    return this._currentConcurrency;
+  }
+  /**
+   * Manually overrides the current concurrency within [minConcurrency, maxConcurrency].
+   *
+   * @param concurrency - New concurrency limit to set.
+   */
+  setConcurrency(concurrency) {
+    const clamped = Math.min(Math.max(concurrency, this.minConcurrency), this.maxConcurrency);
+    if (clamped !== this._currentConcurrency) {
+      const prev = this._currentConcurrency;
+      this._currentConcurrency = clamped;
+      this.onConcurrencyChange(prev, clamped, "Manual concurrency override");
+    }
+  }
+  /**
+   * Records a task execution duration sample and triggers AIMD adjustment if window is filled.
+   *
+   * @param durationMs - Execution duration in milliseconds of the completed task.
+   */
+  recordDuration(durationMs) {
+    this.recentDurations.push(durationMs);
+    if (this.recentDurations.length < this.sampleWindowSize) {
+      return;
+    }
+    const total = this.recentDurations.reduce((sum, val) => sum + val, 0);
+    const average = total / this.recentDurations.length;
+    this.lastAverageLatencyMs = average;
+    this.recentDurations = [];
+    if (average > this.targetLatencyMs) {
+      const decreased = Math.max(
+        this.minConcurrency,
+        Math.floor(this._currentConcurrency * this.backoffFactor)
+      );
+      if (decreased !== this._currentConcurrency) {
+        const prev = this._currentConcurrency;
+        this._currentConcurrency = decreased;
+        this.onConcurrencyChange(
+          prev,
+          decreased,
+          `Average latency (${Math.round(average)}ms) exceeded target (${this.targetLatencyMs}ms). Scaled down.`
+        );
+      }
+    } else if (average < this.targetLatencyMs * 0.75) {
+      const increased = Math.min(this.maxConcurrency, this._currentConcurrency + 1);
+      if (increased !== this._currentConcurrency) {
+        const prev = this._currentConcurrency;
+        this._currentConcurrency = increased;
+        this.onConcurrencyChange(
+          prev,
+          increased,
+          `Average latency (${Math.round(average)}ms) below target threshold. Scaled up.`
+        );
+      }
+    }
+  }
+  /**
+   * Returns a snapshot of adaptive telemetry metrics.
+   */
+  getStats() {
+    return {
+      currentConcurrency: this._currentConcurrency,
+      averageLatencyMs: this.lastAverageLatencyMs,
+      samplesRecorded: this.recentDurations.length
+    };
+  }
+};
+
+// src/models/circuit-breaker.model.ts
+var ECircuitState = /* @__PURE__ */ ((ECircuitState2) => {
+  ECircuitState2["CLOSED"] = "closed";
+  ECircuitState2["OPEN"] = "open";
+  ECircuitState2["HALF_OPEN"] = "half_open";
+  return ECircuitState2;
+})(ECircuitState || {});
+
+// src/scheduler/circuit-breaker.ts
+var CircuitBreakerCoordinator = class {
+  _state = "closed" /* CLOSED */;
+  _consecutiveFailures = 0;
+  _lastFailureTime;
+  failureThreshold;
+  resetTimeoutMs;
+  /**
+   * Initializes a new CircuitBreakerCoordinator.
+   *
+   * @param options - Configuration options for threshold and cool-down window.
+   * @throws {AhkoConfigurationError} If options are invalid.
+   */
+  constructor(options) {
+    if (typeof options.failureThreshold !== "number" || Number.isNaN(options.failureThreshold) || !Number.isInteger(options.failureThreshold) || options.failureThreshold < 1) {
+      throw new AhkoConfigurationError(
+        `Invalid failureThreshold "${options.failureThreshold}". failureThreshold must be an integer greater than or equal to 1.`
+      );
+    }
+    if (typeof options.resetTimeoutMs !== "number" || Number.isNaN(options.resetTimeoutMs) || !Number.isFinite(options.resetTimeoutMs) || options.resetTimeoutMs <= 0) {
+      throw new AhkoConfigurationError(
+        `Invalid resetTimeoutMs "${options.resetTimeoutMs}". resetTimeoutMs must be a positive finite number greater than 0.`
+      );
+    }
+    this.failureThreshold = options.failureThreshold;
+    this.resetTimeoutMs = options.resetTimeoutMs;
+  }
+  /** Current state of the circuit breaker */
+  get state() {
+    this.refreshState();
+    return this._state;
+  }
+  /**
+   * Checks whether an execution is currently allowed.
+   * If the circuit is OPEN and cool-down has not elapsed, fast-fails immediately.
+   *
+   * @throws {AhkoCircuitBreakerOpenError} If the circuit is currently OPEN.
+   */
+  checkAllowed() {
+    this.refreshState();
+    if (this._state === "open" /* OPEN */) {
+      const remainingMs = this._lastFailureTime ? Math.max(0, this.resetTimeoutMs - (Date.now() - this._lastFailureTime)) : this.resetTimeoutMs;
+      throw new AhkoCircuitBreakerOpenError(
+        `Circuit breaker is open. Fast-failing task execution. Remaining cool-down: ${remainingMs}ms.`,
+        {
+          resetTimeoutMs: remainingMs,
+          trippedAt: this._lastFailureTime,
+          consecutiveFailures: this._consecutiveFailures
+        }
+      );
+    }
+  }
+  /**
+   * Records a successful task execution.
+   * Heals HALF_OPEN state back to CLOSED and resets consecutive failure counters.
+   */
+  recordSuccess() {
+    this._consecutiveFailures = 0;
+    this._state = "closed" /* CLOSED */;
+  }
+  /**
+   * Records a failed task execution.
+   * Trips CLOSED to OPEN when threshold is met, or re-trips HALF_OPEN immediately.
+   *
+   * @param _error - Optional error that caused the failure.
+   */
+  recordFailure(_error) {
+    this._consecutiveFailures++;
+    this._lastFailureTime = Date.now();
+    if (this._state === "half_open" /* HALF_OPEN */) {
+      this._state = "open" /* OPEN */;
+      return;
+    }
+    if (this._consecutiveFailures >= this.failureThreshold) {
+      this._state = "open" /* OPEN */;
+    }
+  }
+  /**
+   * Evaluates if enough time has passed to transition from OPEN to HALF_OPEN.
+   */
+  refreshState() {
+    if (this._state === "open" /* OPEN */ && this._lastFailureTime !== void 0) {
+      const elapsed = Date.now() - this._lastFailureTime;
+      if (elapsed >= this.resetTimeoutMs) {
+        this._state = "half_open" /* HALF_OPEN */;
+      }
+    }
+  }
+  /**
+   * Resets the circuit breaker back to initial CLOSED state.
+   */
+  reset() {
+    this._state = "closed" /* CLOSED */;
+    this._consecutiveFailures = 0;
+    this._lastFailureTime = void 0;
+  }
+  /**
+   * Returns a snapshot of circuit breaker telemetry.
+   */
+  getStats() {
+    this.refreshState();
+    return {
+      state: this._state,
+      consecutiveFailures: this._consecutiveFailures,
+      lastFailureTime: this._lastFailureTime
+    };
   }
 };
 
@@ -543,7 +917,7 @@ var AhkoEventEmitter = class {
 // src/scheduler/task-queue.ts
 var TaskQueue = class {
   /** Maximum concurrent active tasks */
-  concurrency;
+  _concurrency;
   /** Minimum interval in milliseconds between consecutive task starts */
   minIntervalMs;
   /** Timestamp of the most recent task start */
@@ -560,12 +934,20 @@ var TaskQueue = class {
   idleEntries = /* @__PURE__ */ new Set();
   /** Set of tasks currently awaiting a retry backoff timer */
   retryEntries = /* @__PURE__ */ new Set();
+  /** Tag index for selective cancellation and task classification */
+  tagIndex = /* @__PURE__ */ new Map();
   /** Coordinator for debounced tasks with key coalescing */
   debounceCoordinator = new DebounceCoordinator();
   /** Coordinator for throttled tasks with leading/trailing coalescing */
   throttleCoordinator = new ThrottleCoordinator();
   /** Lifecycle event emitter for task and scheduler events */
   emitter = new AhkoEventEmitter();
+  /** Circuit breaker coordinator if configured */
+  circuitBreakerCoordinator;
+  /** Adaptive concurrency coordinator if configured */
+  adaptiveCoordinator;
+  /** Pause state flag */
+  _isPaused = false;
   /** Set of pending resolvers awaiting scheduler idle transition */
   idleResolvers = /* @__PURE__ */ new Set();
   /** WeakMap associating task runners with their scheduling options */
@@ -587,9 +969,11 @@ var TaskQueue = class {
    *
    * @param concurrency - Maximum concurrent tasks (defaults to Infinity).
    * @param minIntervalMs - Minimum interval in milliseconds between task dispatches.
+   * @param circuitBreakerOptions - Optional circuit breaker policy configuration.
+   * @param adaptiveOptions - Optional adaptive concurrency policy configuration.
    * @throws {AhkoConfigurationError} If concurrency is less than 1 or minIntervalMs is invalid.
    */
-  constructor(concurrency = Infinity, minIntervalMs = 0) {
+  constructor(concurrency = Infinity, minIntervalMs = 0, circuitBreakerOptions, adaptiveOptions) {
     if (Number.isNaN(concurrency) || concurrency < 1) {
       throw new AhkoConfigurationError(
         `Invalid concurrency "${concurrency}". Must be a number greater than or equal to 1.`
@@ -600,11 +984,171 @@ var TaskQueue = class {
         `Invalid minIntervalMs "${minIntervalMs}". minIntervalMs must be a non-negative finite number.`
       );
     }
-    this.concurrency = concurrency;
+    this._concurrency = concurrency;
     this.minIntervalMs = minIntervalMs;
+    if (circuitBreakerOptions) {
+      this.circuitBreakerCoordinator = new CircuitBreakerCoordinator(circuitBreakerOptions);
+    }
+    if (adaptiveOptions) {
+      this.adaptiveCoordinator = new AdaptiveCoordinator(
+        adaptiveOptions,
+        this._concurrency,
+        (previous, current, reason) => {
+          this._concurrency = current;
+          this.emitter.emit("concurrency:change", {
+            previousConcurrency: previous,
+            currentConcurrency: current,
+            reason
+          });
+          this.pump();
+        }
+      );
+      this._concurrency = this.adaptiveCoordinator.currentConcurrency;
+    }
     this.debounceCoordinator.onSettled = () => this.checkIdle();
     this.throttleCoordinator.onSettled = () => this.checkIdle();
   }
+  /**
+   * Current concurrency capacity limit.
+   */
+  get concurrency() {
+    return this._concurrency;
+  }
+  /**
+   * Dynamically adjusts the concurrency limit at runtime.
+   *
+   * @param newConcurrency - New maximum concurrency (must be >= 1).
+   * @throws {AhkoConfigurationError} If newConcurrency is less than 1.
+   */
+  setConcurrency(newConcurrency) {
+    if (Number.isNaN(newConcurrency) || newConcurrency < 1) {
+      throw new AhkoConfigurationError(
+        `Invalid concurrency "${newConcurrency}". Must be a number greater than or equal to 1.`
+      );
+    }
+    const previous = this._concurrency;
+    this._concurrency = newConcurrency;
+    if (this.adaptiveCoordinator) {
+      this.adaptiveCoordinator.setConcurrency(newConcurrency);
+    }
+    if (newConcurrency !== previous) {
+      this.emitter.emit("concurrency:change", {
+        previousConcurrency: previous,
+        currentConcurrency: newConcurrency,
+        reason: "Manual concurrency update"
+      });
+    }
+    this.pump();
+  }
+  /**
+   * Pauses queue execution. Running tasks will complete normally, but no new pending tasks will be dispatched.
+   */
+  pause() {
+    this._isPaused = true;
+  }
+  /**
+   * Resumes queue execution, immediately dispatching waiting tasks up to available concurrency.
+   */
+  resume() {
+    if (this._isPaused) {
+      this._isPaused = false;
+      this.pump();
+    }
+  }
+  /**
+   * Checks whether the task queue is currently paused.
+   */
+  isPaused() {
+    return this._isPaused;
+  }
+  /**
+   * Cancels all pending, delayed, and active tasks marked with the specified tag.
+   *
+   * @param tag - Tag identifier to match.
+   * @param reason - Optional cancellation reason.
+   * @returns Total count of tasks cancelled.
+   */
+  cancelByTag(tag, reason) {
+    const runners = this.tagIndex.get(tag);
+    if (!runners || runners.size === 0) {
+      return 0;
+    }
+    const list = Array.from(runners);
+    let count = 0;
+    for (const runner of list) {
+      if (runner.state === "pending" /* PENDING */ || runner.state === "running" /* RUNNING */) {
+        runner.cancel(reason ?? `Task cancelled by tag "${tag}"`);
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Returns active and pending task counts for a given tag.
+   *
+   * @param tag - Tag identifier.
+   */
+  getStatsByTag(tag) {
+    const runners = this.tagIndex.get(tag);
+    if (!runners) {
+      return { activeTasks: 0, pendingTasks: 0 };
+    }
+    let active = 0;
+    let pending = 0;
+    for (const runner of runners) {
+      if (runner.state === "running" /* RUNNING */) {
+        active++;
+      } else if (runner.state === "pending" /* PENDING */) {
+        pending++;
+      }
+    }
+    return { activeTasks: active, pendingTasks: pending };
+  }
+  /**
+   * Indexes a runner under all its associated tags.
+   */
+  indexTaskTags(runner) {
+    for (const tag of runner.tags) {
+      let set = this.tagIndex.get(tag);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        this.tagIndex.set(tag, set);
+      }
+      set.add(runner);
+    }
+  }
+  /**
+   * Removes a runner from the tag index upon settlement.
+   */
+  cleanupTaskTags(runner) {
+    for (const tag of runner.tags) {
+      const set = this.tagIndex.get(tag);
+      if (set) {
+        set.delete(runner);
+        if (set.size === 0) {
+          this.tagIndex.delete(tag);
+        }
+      }
+    }
+  }
+  /**
+   * Inserts a task runner into the queue based on priority weight (descending).
+   * Preserves FIFO ordering among tasks with identical priority.
+   */
+  insertIntoQueue(runner) {
+    const options = this.runnerOptions.get(runner);
+    const targetWeight = resolvePriorityWeight(options?.priority);
+    let insertIndex = this.queue.length;
+    for (let i = 0; i < this.queue.length; i++) {
+      const existingOptions = this.runnerOptions.get(this.queue[i]);
+      const existingWeight = resolvePriorityWeight(existingOptions?.priority);
+      if (existingWeight < targetWeight) {
+        insertIndex = i;
+        break;
+      }
+    }
+    this.queue.splice(insertIndex, 0, runner);
+  }
   /**
    * Enqueues a task runner according to the specified schedule options.
    *
@@ -658,13 +1202,35 @@ var TaskQueue = class {
         );
       }
     }
+    if (options?.totalTimeoutMs !== void 0) {
+      if (typeof options.totalTimeoutMs !== "number" || Number.isNaN(options.totalTimeoutMs) || !Number.isFinite(options.totalTimeoutMs) || options.totalTimeoutMs <= 0) {
+        throw new AhkoConfigurationError(
+          `Invalid totalTimeoutMs "${options.totalTimeoutMs}". totalTimeoutMs must be a positive finite number greater than 0.`
+        );
+      }
+    }
     if (options) {
       this.runnerOptions.set(runner, options);
     }
+    this.indexTaskTags(runner);
+    runner.promise.finally(() => {
+      this.cleanupTaskTags(runner);
+    }).catch(() => {
+    });
     if (runner.state === "cancelled" /* CANCELLED */) {
       this.cancelledTasks++;
       return runner.promise;
     }
+    if (options?.totalTimeoutMs !== void 0) {
+      const budgetMs = options.totalTimeoutMs;
+      const totalTimerId = setTimeout(() => {
+        runner.timeout(budgetMs, `Task total execution deadline exceeded after ${budgetMs}ms`);
+      }, budgetMs);
+      runner.promise.finally(() => {
+        clearTimeout(totalTimerId);
+      }).catch(() => {
+      });
+    }
     if (strategy === "delay" /* DELAY */) {
       const delayMs = options?.delay ?? 0;
       if (typeof delayMs !== "number" || Number.isNaN(delayMs) || delayMs < 0) {
@@ -688,15 +1254,23 @@ var TaskQueue = class {
       const index = this.queue.indexOf(runner);
       if (index !== -1) {
         this.queue.splice(index, 1);
-        this.cancelledTasks++;
-        this.emitter.emit("task:cancel", {
-          taskId: runner.taskId,
-          reason: "Task cancelled while queued"
-        });
+        if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+          this.timedOutTasks++;
+          this.emitter.emit("task:timeout", {
+            taskId: runner.taskId,
+            timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
+          });
+        } else {
+          this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while queued"
+          });
+        }
         this.checkIdle();
       }
     };
-    this.queue.push(runner);
+    this.insertIntoQueue(runner);
     this.pump();
     return runner.promise;
   }
@@ -709,22 +1283,30 @@ var TaskQueue = class {
       runner,
       timerId: setTimeout(() => {
         this.delayedEntries.delete(delayedEntry);
-        if (runner.state === "cancelled" /* CANCELLED */) {
+        if (runner.state === "cancelled" /* CANCELLED */ || runner.state === "timed_out" /* TIMED_OUT */) {
           return;
         }
         runner.onCancel = () => {
           const index = this.queue.indexOf(runner);
           if (index !== -1) {
             this.queue.splice(index, 1);
-            this.cancelledTasks++;
-            this.emitter.emit("task:cancel", {
-              taskId: runner.taskId,
-              reason: "Task cancelled while queued"
-            });
+            if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+              this.timedOutTasks++;
+              this.emitter.emit("task:timeout", {
+                taskId: runner.taskId,
+                timeoutMs: this.runnerOptions.get(runner)?.totalTimeoutMs ?? runner.timeoutMs
+              });
+            } else {
+              this.cancelledTasks++;
+              this.emitter.emit("task:cancel", {
+                taskId: runner.taskId,
+                reason: "Task cancelled while queued"
+              });
+            }
             this.checkIdle();
           }
         };
-        this.queue.push(runner);
+        this.insertIntoQueue(runner);
         this.pump();
       }, delayMs)
     };
@@ -733,11 +1315,19 @@ var TaskQueue = class {
       if (this.delayedEntries.has(delayedEntry)) {
         clearTimeout(delayedEntry.timerId);
         this.delayedEntries.delete(delayedEntry);
-        this.cancelledTasks++;
-        this.emitter.emit("task:cancel", {
-          taskId: runner.taskId,
-          reason: "Task cancelled while waiting in delay"
-        });
+        if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+          this.timedOutTasks++;
+          this.emitter.emit("task:timeout", {
+            taskId: runner.taskId,
+            timeoutMs: this.runnerOptions.get(runner)?.totalTimeoutMs ?? runner.timeoutMs
+          });
+        } else {
+          this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while waiting in delay"
+          });
+        }
         this.checkIdle();
       }
     };
@@ -750,22 +1340,30 @@ var TaskQueue = class {
     let idleEntry;
     const handle = IdleScheduler.schedule(() => {
       this.idleEntries.delete(idleEntry);
-      if (runner.state === "cancelled" /* CANCELLED */) {
+      if (runner.state === "cancelled" /* CANCELLED */ || runner.state === "timed_out" /* TIMED_OUT */) {
         return;
       }
       runner.onCancel = () => {
         const index = this.queue.indexOf(runner);
         if (index !== -1) {
           this.queue.splice(index, 1);
-          this.cancelledTasks++;
-          this.emitter.emit("task:cancel", {
-            taskId: runner.taskId,
-            reason: "Task cancelled while queued"
-          });
+          if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+            this.timedOutTasks++;
+            this.emitter.emit("task:timeout", {
+              taskId: runner.taskId,
+              timeoutMs: this.runnerOptions.get(runner)?.totalTimeoutMs ?? runner.timeoutMs
+            });
+          } else {
+            this.cancelledTasks++;
+            this.emitter.emit("task:cancel", {
+              taskId: runner.taskId,
+              reason: "Task cancelled while queued"
+            });
+          }
           this.checkIdle();
         }
       };
-      this.queue.push(runner);
+      this.insertIntoQueue(runner);
       this.pump();
     }, idleTimeout);
     idleEntry = { runner, handle };
@@ -774,21 +1372,30 @@ var TaskQueue = class {
       if (this.idleEntries.has(idleEntry)) {
         handle.cancel();
         this.idleEntries.delete(idleEntry);
-        this.cancelledTasks++;
-        this.emitter.emit("task:cancel", {
-          taskId: runner.taskId,
-          reason: "Task cancelled while waiting for idle"
-        });
+        if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+          this.timedOutTasks++;
+          this.emitter.emit("task:timeout", {
+            taskId: runner.taskId,
+            timeoutMs: this.runnerOptions.get(runner)?.totalTimeoutMs ?? runner.timeoutMs
+          });
+        } else {
+          this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while waiting for idle"
+          });
+        }
         this.checkIdle();
       }
     };
   }
   /**
    * Pumps the queue by picking pending tasks and executing them
-   * as long as concurrency capacity is available and minIntervalMs is respected.
+   * as long as concurrency capacity is available, minIntervalMs is respected,
+   * and queue is not paused.
    */
   pump() {
-    if (this.queue.length === 0 || this.activeRunners.size >= this.concurrency) {
+    if (this._isPaused || this.queue.length === 0 || this.activeRunners.size >= this._concurrency) {
       return;
     }
     if (this.minIntervalMs > 0 && this.lastTaskStartTime > 0) {
@@ -805,7 +1412,7 @@ var TaskQueue = class {
         return;
       }
     }
-    while (this.activeRunners.size < this.concurrency && this.queue.length > 0) {
+    while (!this._isPaused && this.activeRunners.size < this._concurrency && this.queue.length > 0) {
       if (this.minIntervalMs > 0 && this.lastTaskStartTime > 0) {
         const now = Date.now();
         const elapsed = now - this.lastTaskStartTime;
@@ -824,14 +1431,30 @@ var TaskQueue = class {
       if (!runner) {
         break;
       }
-      if (runner.state === "cancelled" /* CANCELLED */) {
+      if (runner.state === "cancelled" /* CANCELLED */ || runner.state === "timed_out" /* TIMED_OUT */) {
         continue;
       }
+      if (this.circuitBreakerCoordinator) {
+        try {
+          this.circuitBreakerCoordinator.checkAllowed();
+        } catch (cbError) {
+          this.failedTasks++;
+          this.runnerOptions.delete(runner);
+          this.emitter.emit("task:fail", {
+            taskId: runner.taskId,
+            attempt: runner.attempt,
+            error: cbError,
+            willRetry: false
+          });
+          runner.reject(cbError);
+          continue;
+        }
+      }
       this.activeRunners.add(runner);
       this.lastTaskStartTime = Date.now();
       void this.executeRunner(runner);
       if (this.minIntervalMs > 0) {
-        if (this.queue.length > 0 && this.activeRunners.size < this.concurrency) {
+        if (this.queue.length > 0 && this.activeRunners.size < this._concurrency) {
           if (this.rateLimitTimer === void 0) {
             this.rateLimitTimer = setTimeout(() => {
               this.rateLimitTimer = void 0;
@@ -855,6 +1478,8 @@ var TaskQueue = class {
     });
     try {
       const result = await runner.run();
+      this.circuitBreakerCoordinator?.recordSuccess();
+      this.adaptiveCoordinator?.recordDuration(runner.lastDurationMs);
       this.completedTasks++;
       this.activeRunners.delete(runner);
       this.runnerOptions.delete(runner);
@@ -890,11 +1515,15 @@ var TaskQueue = class {
         this.scheduleRetry(runner, options);
         return;
       }
+      if (this.circuitBreakerCoordinator && !(error instanceof AhkoCircuitBreakerOpenError)) {
+        this.circuitBreakerCoordinator.recordFailure(error);
+      }
+      this.adaptiveCoordinator?.recordDuration(runner.lastDurationMs);
       if (runner.state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
         this.timedOutTasks++;
         this.emitter.emit("task:timeout", {
           taskId: runner.taskId,
-          timeoutMs: runner.timeoutMs
+          timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
         });
       } else {
         this.failedTasks++;
@@ -924,15 +1553,23 @@ var TaskQueue = class {
         const index = this.queue.indexOf(runner);
         if (index !== -1) {
           this.queue.splice(index, 1);
-          this.cancelledTasks++;
-          this.emitter.emit("task:cancel", {
-            taskId: runner.taskId,
-            reason: "Task cancelled while queued"
-          });
+          if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+            this.timedOutTasks++;
+            this.emitter.emit("task:timeout", {
+              taskId: runner.taskId,
+              timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
+            });
+          } else {
+            this.cancelledTasks++;
+            this.emitter.emit("task:cancel", {
+              taskId: runner.taskId,
+              reason: "Task cancelled while queued"
+            });
+          }
           this.checkIdle();
         }
       };
-      this.queue.push(runner);
+      this.insertIntoQueue(runner);
       this.pump();
       return;
     }
@@ -940,22 +1577,30 @@ var TaskQueue = class {
       runner,
       timerId: setTimeout(() => {
         this.retryEntries.delete(retryEntry);
-        if (runner.state === "cancelled" /* CANCELLED */) {
+        if (runner.state === "cancelled" /* CANCELLED */ || runner.state === "timed_out" /* TIMED_OUT */) {
           return;
         }
         runner.onCancel = () => {
           const index = this.queue.indexOf(runner);
           if (index !== -1) {
             this.queue.splice(index, 1);
-            this.cancelledTasks++;
-            this.emitter.emit("task:cancel", {
-              taskId: runner.taskId,
-              reason: "Task cancelled while queued"
-            });
+            if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+              this.timedOutTasks++;
+              this.emitter.emit("task:timeout", {
+                taskId: runner.taskId,
+                timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
+              });
+            } else {
+              this.cancelledTasks++;
+              this.emitter.emit("task:cancel", {
+                taskId: runner.taskId,
+                reason: "Task cancelled while queued"
+              });
+            }
             this.checkIdle();
           }
         };
-        this.queue.push(runner);
+        this.insertIntoQueue(runner);
         this.pump();
       }, backoffDelay)
     };
@@ -964,11 +1609,19 @@ var TaskQueue = class {
       if (this.retryEntries.has(retryEntry)) {
         clearTimeout(retryEntry.timerId);
         this.retryEntries.delete(retryEntry);
-        this.cancelledTasks++;
-        this.emitter.emit("task:cancel", {
-          taskId: runner.taskId,
-          reason: "Task cancelled during retry backoff"
-        });
+        if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+          this.timedOutTasks++;
+          this.emitter.emit("task:timeout", {
+            taskId: runner.taskId,
+            timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
+          });
+        } else {
+          this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled during retry backoff"
+          });
+        }
         this.checkIdle();
       }
     };
@@ -1015,7 +1668,7 @@ var TaskQueue = class {
   clear() {
     while (this.queue.length > 0) {
       const runner = this.queue.shift();
-      if (runner && runner.state !== "cancelled" /* CANCELLED */) {
+      if (runner && runner.state !== "cancelled" /* CANCELLED */ && runner.state !== "timed_out" /* TIMED_OUT */) {
         runner.cancel("Scheduler cleared");
         this.cancelledTasks++;
         this.emitter.emit("task:cancel", { taskId: runner.taskId, reason: "Scheduler cleared" });
@@ -1065,7 +1718,10 @@ var TaskQueue = class {
       timedOutTasks: this.timedOutTasks,
       retriedTasks: this.retriedTasks,
       totalDispatched: this.totalDispatched,
-      capacity: this.concurrency
+      capacity: this._concurrency,
+      isPaused: this._isPaused,
+      circuitState: this.circuitBreakerCoordinator?.state,
+      adaptive: this.adaptiveCoordinator?.getStats()
     });
   }
 };
@@ -1101,18 +1757,22 @@ var TaskRunner = class {
   attempt = 1;
   /** Duration of the most recent execution attempt in milliseconds */
   lastDurationMs = 0;
+  /** Set of classification tags associated with this task */
+  tags;
   /**
    * Creates a new TaskRunner instance.
    *
    * @param task - The asynchronous work unit to run.
    * @param externalSignal - Optional external AbortSignal to propagate.
    * @param timeoutMs - Optional maximum execution time in milliseconds.
+   * @param tags - Optional array of tags for classifying and selectively cancelling tasks.
    */
-  constructor(task, externalSignal, timeoutMs) {
+  constructor(task, externalSignal, timeoutMs, tags) {
     this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
     this.task = task;
     this.externalSignal = externalSignal;
     this.timeoutMs = timeoutMs;
+    this.tags = new Set(tags ?? []);
     this.abortController = new AbortController();
     this.promise = new Promise((resolve, reject) => {
       this.resolvePromise = resolve;
@@ -1136,6 +1796,8 @@ var TaskRunner = class {
       }
     }
   }
+  /** Flag indicating if runner was aborted by an overall total timeout deadline */
+  totalTimedOut = false;
   /**
    * Gets the current lifecycle state of the task.
    */
@@ -1168,7 +1830,7 @@ var TaskRunner = class {
    * @returns A promise resolving to true if retry should proceed, false otherwise.
    */
   async canRetry(error, retryOptions) {
-    if (this._state === "cancelled" /* CANCELLED */ || (this.externalSignal?.aborted ?? false)) {
+    if (this.totalTimedOut || this._state === "cancelled" /* CANCELLED */ || (this.externalSignal?.aborted ?? false)) {
       return false;
     }
     if (!retryOptions || typeof retryOptions.attempts !== "number") {
@@ -1209,15 +1871,16 @@ var TaskRunner = class {
     let abortListener;
     const abortPromise = new Promise((_, reject) => {
       abortListener = () => {
-        if (this._state === "timed_out" /* TIMED_OUT */) {
+        const reason = this.abortController.signal.reason;
+        if (this._state === "timed_out" /* TIMED_OUT */ || reason instanceof AhkoTimeoutError) {
+          this._state = "timed_out" /* TIMED_OUT */;
           reject(
-            new AhkoTimeoutError(
+            reason instanceof AhkoTimeoutError ? reason : new AhkoTimeoutError(
               `Task execution timed out after ${this.timeoutMs}ms`,
               { timeoutMs: this.timeoutMs }
             )
           );
         } else {
-          const reason = this.abortController.signal.reason;
           reject(
             new AhkoCancellationError("Task was cancelled during execution", {
               cause: reason instanceof Error ? reason : void 0
@@ -1252,6 +1915,10 @@ var TaskRunner = class {
     }
     taskExecutionPromise.catch(() => {
     });
+    abortPromise.catch(() => {
+    });
+    timeoutPromise?.catch(() => {
+    });
     const racePromises = [
       taskExecutionPromise,
       abortPromise
@@ -1343,6 +2010,31 @@ var TaskRunner = class {
       this.onCancel?.(this);
     }
   }
+  /**
+   * Times out the task, aborting pending or running execution with AhkoTimeoutError.
+   *
+   * @param timeoutMs - Timeout duration in milliseconds.
+   * @param message - Optional custom timeout message.
+   */
+  timeout(timeoutMs, message) {
+    if (this._state === "completed" /* COMPLETED */ || this._state === "failed" /* FAILED */ || this._state === "cancelled" /* CANCELLED */ || this._state === "timed_out" /* TIMED_OUT */) {
+      return;
+    }
+    const wasPending = this._state === "pending" /* PENDING */;
+    this._state = "timed_out" /* TIMED_OUT */;
+    this.totalTimedOut = true;
+    this.clearTimeoutTimer();
+    const timeoutError = new AhkoTimeoutError(
+      message ?? `Task execution timed out after ${timeoutMs}ms`,
+      { timeoutMs }
+    );
+    this.abortController.abort(timeoutError);
+    this.cleanup();
+    if (wasPending) {
+      this.rejectPromise(timeoutError);
+      this.onCancel?.(this);
+    }
+  }
   /**
    * Handles external AbortSignal trigger.
    */
@@ -1361,9 +2053,56 @@ var TaskRunner = class {
 };
 
 // src/ahko.ts
-var Ahko = class {
+var Ahko = class _Ahko {
   /** Internal queue and concurrency manager */
   queue;
+  /** Default schedule options inherited from profile if configured */
+  defaultScheduleOptions;
+  /**
+   * Programmatically loads a declarative configuration into memory.
+   * Works universally across Node.js, browsers, and edge runtimes.
+   *
+   * @param config - File configuration object containing default and named profiles.
+   */
+  static loadConfig(config) {
+    loadConfig(config);
+  }
+  /**
+   * Asynchronously loads a configuration file from disk (Node.js).
+   *
+   * @param filePath - Path to configuration file (default: "config.ahko.json").
+   */
+  static async loadConfigFile(filePath) {
+    return loadConfigFile(filePath);
+  }
+  /**
+   * Resets the active declarative configuration.
+   */
+  static resetConfig() {
+    resetConfig();
+  }
+  /**
+   * Retrieves the currently active declarative configuration.
+   */
+  static getActiveConfig() {
+    return getActiveConfig();
+  }
+  /**
+   * Instantiates an Ahko scheduler initialized with settings from a declarative profile.
+   *
+   * @param profileName - Optional name of the profile (e.g. "api", "background").
+   * @param overrides - Optional scheduler options overriding profile values.
+   * @returns A new configured Ahko instance.
+   */
+  static fromProfile(profileName, overrides) {
+    const profile = getProfileConfig(profileName);
+    return new _Ahko({
+      ...profile,
+      ...overrides,
+      circuitBreaker: overrides?.circuitBreaker ?? profile?.circuitBreaker,
+      adaptive: overrides?.adaptive ?? profile?.adaptive
+    });
+  }
   /**
    * Initializes a new Ahko scheduler instance.
    *
@@ -1376,79 +2115,177 @@ var Ahko = class {
    * ```
    */
   constructor(options) {
-    this.queue = new TaskQueue(options?.concurrency, options?.minIntervalMs);
+    const profile = options?.profile ? getProfileConfig(options.profile) : getProfileConfig();
+    const mergedOptions = {
+      ...profile,
+      ...options,
+      circuitBreaker: options?.circuitBreaker ?? profile?.circuitBreaker,
+      adaptive: options?.adaptive ?? profile?.adaptive
+    };
+    if (profile) {
+      this.defaultScheduleOptions = {
+        priority: profile.priority,
+        retry: profile.retry,
+        timeoutMs: profile.timeoutMs,
+        totalTimeoutMs: profile.totalTimeoutMs,
+        tags: profile.tags
+      };
+    }
+    this.queue = new TaskQueue(
+      mergedOptions.concurrency,
+      mergedOptions.minIntervalMs,
+      mergedOptions.circuitBreaker,
+      mergedOptions.adaptive
+    );
+  }
+  /**
+   * Current concurrency limit.
+   */
+  get concurrency() {
+    return this.queue.concurrency;
+  }
+  /**
+   * Dynamically updates the concurrency limit of the scheduler.
+   *
+   * @param concurrency - New maximum concurrency (must be >= 1).
+   * @throws {AhkoConfigurationError} If concurrency is invalid.
+   */
+  setConcurrency(concurrency) {
+    this.queue.setConcurrency(concurrency);
+  }
+  /**
+   * Pauses scheduler dispatch. In-flight tasks run to completion, but pending tasks remain queued.
+   */
+  pause() {
+    this.queue.pause();
+  }
+  /**
+   * Resumes scheduler dispatch, immediately executing waiting tasks up to available concurrency.
+   */
+  resume() {
+    this.queue.resume();
+  }
+  /**
+   * Checks whether the scheduler is currently paused.
+   */
+  isPaused() {
+    return this.queue.isPaused();
+  }
+  /**
+   * Current circuit breaker state if circuit breaker protection is configured.
+   */
+  get circuitState() {
+    return this.queue.circuitBreakerCoordinator?.state;
+  }
+  /**
+   * Access to the underlying circuit breaker coordinator instance if configured.
+   */
+  get circuitBreaker() {
+    return this.queue.circuitBreakerCoordinator;
+  }
+  /**
+   * Wraps an async function so every execution is automatically routed through this Ahko scheduler.
+   *
+   * @template TArgs - Parameter types of the wrapped function.
+   * @template TReturn - Return type of the wrapped function.
+   * @param fn - The function to wrap.
+   * @param options - Optional scheduling options applied to every wrapped call.
+   * @returns A wrapped function returning a Promise.
+   *
+   * @example
+   * ```typescript
+   * const fetchUser = ahko.wrap(async (id: string) => api.getUser(id), { priority: "high" });
+   * const user = await fetchUser("usr_123");
+   * ```
+   */
+  wrap(fn, options) {
+    if (typeof fn !== "function") {
+      throw new AhkoConfigurationError("Target to wrap must be a valid function.");
+    }
+    return (...args) => {
+      return this.schedule(() => fn(...args), options);
+    };
   }
   /**
    * Schedules a task for execution with full return type inference.
    *
    * @template T - Inferred return type of the task.
    * @param task - Asynchronous or synchronous task function accepting an {@link ITaskContext}.
-   * @param options - Task-specific scheduling options such as strategy, delay, and cancellation signal.
+   * @param options - Task-specific scheduling options such as strategy, priority, delay, and cancellation signal.
    * @returns A promise that resolves with the task's return value.
    *
    * @throws {AhkoConfigurationError} If the task is not a function or options are invalid.
    * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.
-   * @throws {AhkoTimeoutError} If task execution exceeds timeoutMs.
+   * @throws {AhkoTimeoutError} If task execution exceeds timeoutMs or totalTimeoutMs.
+   * @throws {AhkoCircuitBreakerOpenError} If the circuit breaker is OPEN and rejects the execution.
    *
    * @example
    * ```typescript
    * // Immediate execution (subject to concurrency)
    * const count = await ahko.schedule(async () => 42);
    *
-   * // Delayed execution
-   * await ahko.schedule(
-   *   async ({ signal }) => doWork({ signal }),
-   *   { strategy: "delay", delay: 1000 }
-   * );
+   * // High priority task
+   * await ahko.schedule(doUrgentWork, { priority: "high" });
    * ```
    */
   schedule(task, options) {
     if (typeof task !== "function") {
       throw new AhkoConfigurationError("Task must be a valid function.");
     }
-    const strategy = options?.strategy ?? "immediate" /* IMMEDIATE */;
+    const mergedTags = options?.tags ?? this.defaultScheduleOptions?.tags;
+    const mergedOptions = {
+      ...this.defaultScheduleOptions,
+      ...options,
+      tags: mergedTags
+    };
+    const strategy = mergedOptions.strategy ?? "immediate" /* IMMEDIATE */;
     if (strategy === "debounce" /* DEBOUNCE */) {
-      if (!options?.key || typeof options.key !== "string" && typeof options.key !== "symbol") {
+      if (!mergedOptions.key || typeof mergedOptions.key !== "string" && typeof mergedOptions.key !== "symbol") {
         throw new AhkoConfigurationError(
           `Strategy "debounce" requires a valid "key" of type string or symbol.`
         );
       }
-      const waitMs = options.waitMs ?? options.delay;
+      const waitMs = mergedOptions.waitMs ?? mergedOptions.delay;
       if (typeof waitMs !== "number" || Number.isNaN(waitMs) || !Number.isFinite(waitMs) || waitMs < 0) {
         throw new AhkoConfigurationError(
           `Strategy "debounce" requires a non-negative finite "waitMs" or "delay" in milliseconds.`
         );
       }
       return this.queue.debounceCoordinator.schedule(
-        options.key,
+        mergedOptions.key,
         task,
         waitMs,
-        options,
+        mergedOptions,
         (t, opts) => this.schedule(t, { ...opts, strategy: "immediate" /* IMMEDIATE */ })
       );
     }
     if (strategy === "throttle" /* THROTTLE */) {
-      if (!options?.key || typeof options.key !== "string" && typeof options.key !== "symbol") {
+      if (!mergedOptions.key || typeof mergedOptions.key !== "string" && typeof mergedOptions.key !== "symbol") {
         throw new AhkoConfigurationError(
           `Strategy "throttle" requires a valid "key" of type string or symbol.`
         );
       }
-      const waitMs = options.waitMs ?? options.delay;
+      const waitMs = mergedOptions.waitMs ?? mergedOptions.delay;
       if (typeof waitMs !== "number" || Number.isNaN(waitMs) || !Number.isFinite(waitMs) || waitMs < 0) {
         throw new AhkoConfigurationError(
           `Strategy "throttle" requires a non-negative finite "waitMs" or "delay" in milliseconds.`
         );
       }
       return this.queue.throttleCoordinator.schedule(
-        options.key,
+        mergedOptions.key,
         task,
         waitMs,
-        options,
+        mergedOptions,
         (t, opts) => this.schedule(t, { ...opts, strategy: "immediate" /* IMMEDIATE */ })
       );
     }
-    const runner = new TaskRunner(task, options?.signal, options?.timeoutMs);
-    return this.queue.enqueue(runner, options);
+    const runner = new TaskRunner(
+      task,
+      mergedOptions.signal,
+      mergedOptions.timeoutMs,
+      mergedOptions.tags
+    );
+    return this.queue.enqueue(runner, mergedOptions);
   }
   /**
    * Convenience method to schedule a task during platform idle opportunities.
@@ -1508,15 +2345,185 @@ var Ahko = class {
       waitMs
     });
   }
+  /**
+   * Transforms an iterable of items concurrently using an asynchronous mapping function.
+   *
+   * Results are guaranteed to be returned in the original index order.
+   * Concurrency can be capped per-batch or fall back to the scheduler's global limit.
+   *
+   * @template TItem - Type of input elements.
+   * @template TResult - Type of mapped elements.
+   * @param items - Iterable sequence of items to process.
+   * @param fn - Mapper callback receiving item, index, and task context.
+   * @param options - Batch execution options (concurrency, stopOnError, retry, signal, tags, etc.).
+   * @returns Array of transformed results in index order.
+   *
+   * @throws {AhkoConfigurationError} If fn is not a function or concurrency is invalid.
+   * @throws {AhkoCancellationError} If batch or item is cancelled.
+   *
+   * @example
+   * ```typescript
+   * const urls = ["/api/1", "/api/2", "/api/3"];
+   * const data = await ahko.map(urls, async (url, i, { signal }) => {
+   *   const res = await fetch(url, { signal });
+   *   return res.json();
+   * }, { concurrency: 2 });
+   * ```
+   */
+  async map(items, fn, options) {
+    if (typeof fn !== "function") {
+      throw new AhkoConfigurationError("Mapper function must be a valid function.");
+    }
+    if (options?.concurrency !== void 0 && (typeof options.concurrency !== "number" || Number.isNaN(options.concurrency) || options.concurrency < 1)) {
+      throw new AhkoConfigurationError(
+        `Invalid concurrency "${options.concurrency}". Must be a number greater than or equal to 1.`
+      );
+    }
+    const list = Array.from(items);
+    if (list.length === 0) {
+      return [];
+    }
+    const { concurrency, stopOnError = false, signal: externalSignal, ...scheduleOpts } = options ?? {};
+    if (externalSignal?.aborted) {
+      throw new AhkoCancellationError(
+        externalSignal.reason ? `Batch cancelled: ${String(externalSignal.reason)}` : "Batch cancelled"
+      );
+    }
+    const abortController = new AbortController();
+    const results = new Array(list.length);
+    let firstError = void 0;
+    let hasAborted = false;
+    const localizedLimit = concurrency !== void 0 ? Math.floor(concurrency) : Number.isFinite(this.concurrency) ? this.concurrency : Infinity;
+    return new Promise((resolve, reject) => {
+      let currentIndex = 0;
+      let activeCount = 0;
+      let settledCount = 0;
+      const onExternalAbort = () => {
+        const reason = externalSignal?.reason ?? "Batch cancelled by external signal";
+        const err = new AhkoCancellationError(
+          typeof reason === "string" ? reason : "Batch cancelled by external signal"
+        );
+        cleanupAndReject(err);
+      };
+      if (externalSignal) {
+        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+      }
+      const cleanupAndReject = (err) => {
+        if (!hasAborted) {
+          hasAborted = true;
+          abortController.abort(err);
+        }
+        if (externalSignal) {
+          externalSignal.removeEventListener("abort", onExternalAbort);
+        }
+        reject(err);
+      };
+      const checkCompletion = () => {
+        if (settledCount === list.length) {
+          if (externalSignal) {
+            externalSignal.removeEventListener("abort", onExternalAbort);
+          }
+          if (firstError !== void 0) {
+            reject(firstError);
+          } else {
+            resolve(results);
+          }
+        }
+      };
+      const launchNext = () => {
+        if (hasAborted && stopOnError) {
+          return;
+        }
+        while (currentIndex < list.length && activeCount < localizedLimit && !(hasAborted && stopOnError)) {
+          const index = currentIndex++;
+          const item = list[index];
+          activeCount++;
+          const taskPromise = this.schedule(
+            (context) => fn(item, index, context),
+            {
+              ...scheduleOpts,
+              signal: abortController.signal
+            }
+          );
+          taskPromise.then((result) => {
+            results[index] = result;
+          }).catch((err) => {
+            if (firstError === void 0) {
+              firstError = err;
+            }
+            if (stopOnError && !hasAborted) {
+              cleanupAndReject(err);
+              return;
+            }
+          }).finally(() => {
+            activeCount--;
+            settledCount++;
+            if (hasAborted && stopOnError) {
+              return;
+            }
+            if (currentIndex < list.length) {
+              launchNext();
+            } else {
+              checkCompletion();
+            }
+          });
+        }
+      };
+      if (abortController.signal.aborted) {
+        cleanupAndReject(abortController.signal.reason);
+        return;
+      }
+      launchNext();
+    });
+  }
+  /**
+   * Iterates sequentially or concurrently over an iterable sequence of items,
+   * executing the callback function for each element.
+   *
+   * @template TItem - Type of input elements.
+   * @param items - Iterable sequence of items to process.
+   * @param fn - Callback receiving item, index, and task context.
+   * @param options - Batch execution options.
+   * @returns Promise resolving once all items have finished executing.
+   *
+   * @example
+   * ```typescript
+   * await ahko.each(userQueue, async (user, index, { signal }) => {
+   *   await sendWelcomeEmail(user, { signal });
+   * }, { concurrency: 5 });
+   * ```
+   */
+  async each(items, fn, options) {
+    await this.map(items, fn, options);
+  }
+  /**
+   * Cancels all pending, delayed, and active tasks tagged with the given tag.
+   *
+   * @param tag - Tag identifier.
+   * @param reason - Optional cancellation reason.
+   * @returns Total number of tasks cancelled.
+   */
+  cancelByTag(tag, reason) {
+    return this.queue.cancelByTag(tag, reason);
+  }
+  /**
+   * Retrieves active and pending task counts for a given tag.
+   *
+   * @param tag - Tag identifier.
+   * @returns Object with activeTasks and pendingTasks counts.
+   */
+  statsByTag(tag) {
+    return this.queue.getStatsByTag(tag);
+  }
   /**
    * Retrieves real-time telemetry metrics from the scheduler.
    *
-   * @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.
+   * @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, timed out tasks, pause status, and circuit state.
    *
    * @example
    * ```typescript
    * const stats = ahko.stats();
-   * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);
+   * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}, Paused: ${stats.isPaused}`);
    * ```
    */
   stats() {
@@ -1602,7 +2609,7 @@ var Ahko = class {
 };
 
 // src/version.ts
-var VERSION = "1.0.0";
+var VERSION = "1.1.5";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {
@@ -1675,18 +2682,29 @@ function combineSignals(signals) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AdaptiveCoordinator,
   Ahko,
   AhkoCancellationError,
+  AhkoCircuitBreakerOpenError,
   AhkoConfigurationError,
   AhkoError,
   AhkoQueueError,
   AhkoTimeoutError,
+  CircuitBreakerCoordinator,
   DEFAULT_BASE_DELAY,
   DEFAULT_MAX_DELAY,
+  ECircuitState,
   EScheduleStrategy,
   ETaskState,
+  TASK_PRIORITY_WEIGHTS,
   VERSION,
   calculateBackoff,
-  combineSignals
+  combineSignals,
+  getActiveConfig,
+  getProfileConfig,
+  loadConfig,
+  loadConfigFile,
+  resetConfig,
+  resolvePriorityWeight
 });
 //# sourceMappingURL=index.cjs.map