actly 1.1.5 → 1.2.0

package/dist/errors.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Actly error taxonomy.
+ *
+ * Six classes (one abstract base + five concrete). Each carries a stable
+ * `code` field so consumers can switch on strings instead of brittle
+ * `instanceof` chains across realm boundaries (e.g. errors serialised
+ * over IPC).
+ *
+ * # Why these six?
+ *
+ *  - `ActlyError`         — abstract base for `instanceof ActlyError` checks
+ *  - `ActlyAbortError`    — caller / signal cancellation
+ *  - `TimeoutError`       — per-attempt deadline
+ *  - `TotalTimeoutError`  — operation-wide budget
+ *  - `RetryExhaustedError`— last attempt's error wrapped with context
+ *  - `ValidationError`    — programmer error (invalid options)
+ *
+ * NO circuit/bulkhead/rate-limit errors — those policies don't exist in
+ * core. Adding orphan error classes violates the "every feature must map
+ * to a real runtime failure mode" rule.
+ *
+ * # `code` field
+ *
+ * Stable string identifier. Use this for switch statements and telemetry
+ * tags. The class name can change across versions; `code` won't.
+ */
+/** Base class for all actly errors. Enables `instanceof ActlyError` checks. */
+export declare abstract class ActlyError extends Error {
+    /** Stable string identifier. Use for telemetry / switch statements. */
+    abstract readonly code: string;
+    /** The key associated with the failure, if applicable. */
+    readonly key?: string;
+    constructor(message: string, options?: {
+        key?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the caller's signal, per-attempt timeout, or total timeout
+ * aborts the operation.
+ *
+ * `cause` carries the original abort reason (e.g. user-supplied
+ * `controller.abort(new Error('user-cancelled'))` → cause.message is
+ * 'user-cancelled').
+ *
+ * Wraps the raw abort reason in a typed error so consumers can
+ * `instanceof`-check it consistently across all abort sources.
+ */
+export declare class ActlyAbortError extends ActlyError {
+    readonly code: "ACTLY_ABORT";
+    constructor(options?: {
+        key?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a per-attempt `timeout` deadline fires.
+ *
+ * Carries the configured `ms` so callers can log/alert precisely:
+ *
+ * ```ts
+ * if (!result.ok && result.error instanceof TimeoutError) {
+ *   console.log(`attempt timed out after ${result.error.ms}ms`)
+ * }
+ * ```
+ */
+export declare class TimeoutError extends ActlyError {
+    readonly code: "ACTLY_TIMEOUT";
+    readonly ms: number;
+    constructor(ms: number, options?: {
+        key?: string;
+    });
+}
+/**
+ * Thrown when the operation-wide `totalTimeout` budget fires.
+ *
+ * Distinct from `TimeoutError` (per-attempt) so callers can `instanceof`-check
+ * which deadline fired.
+ */
+export declare class TotalTimeoutError extends ActlyError {
+    readonly code: "ACTLY_TOTAL_TIMEOUT";
+    readonly ms: number;
+    constructor(ms: number, options?: {
+        key?: string;
+    });
+}
+/**
+ * Thrown when all retry attempts are exhausted. The `lastError` is the
+ * final attempt's error; `errors` is the array of all attempt errors
+ * (useful for debugging patterns across retries).
+ *
+ * Wraps retry exhaustion with context so consumers can distinguish "single
+ * fn error" from "retry exhausted after N attempts".
+ *
+ * # When is this thrown vs the raw error?
+ *
+ * `retryPolicy` throws `RetryExhaustedError` when:
+ *  - `attempts > 1` AND
+ *  - all attempts failed AND
+ *  - the default `shouldRetry` (or user-supplied predicate) returned `true`
+ *    for at least one failure
+ *
+ * If the user's `shouldRetry` returns `false` on the first attempt, the
+ * raw error is thrown (no retries happened — not "exhausted").
+ */
+export declare class RetryExhaustedError extends ActlyError {
+    readonly code: "ACTLY_RETRY_EXHAUSTED";
+    readonly attempts: number;
+    readonly lastError: unknown;
+    readonly errors: readonly unknown[];
+    constructor(options: {
+        key?: string;
+        attempts: number;
+        lastError: unknown;
+        errors: readonly unknown[];
+    });
+}
+/**
+ * Thrown on invalid option shapes / keys / store contracts. Programmer
+ * errors — these surface synchronously, NOT as `ActFailure`, because the
+ * caller's code is broken.
+ *
+ * Wraps the underlying `TypeError` / `RangeError` so consumers catching
+ * `ActlyError` get a consistent type for all actly-thrown errors.
+ */
+export declare class ValidationError extends ActlyError {
+    readonly code: "ACTLY_VALIDATION";
+    constructor(message: string, options?: {
+        field?: string;
+    });
+    readonly field?: string;
+}
+/** Thrown when a circuit breaker is open and blocks the call. */
+export declare class CircuitBreakerOpenError extends ActlyError {
+    readonly code: "ACTLY_CIRCUIT_OPEN";
+    readonly key: string;
+    constructor(key: string, ms: number);
+}
+/** Thrown when a bulkhead is full (maxConcurrent reached, queue timed out). */
+export declare class BulkheadOverflowError extends ActlyError {
+    readonly code: "ACTLY_BULKHEAD_FULL";
+    readonly key: string;
+    constructor(key: string, maxConcurrent: number);
+}
+/** Thrown when a rate limit is exceeded. */
+export declare class RateLimitError extends ActlyError {
+    readonly code: "ACTLY_RATE_LIMIT";
+    readonly key: string;
+    constructor(key: string, maxCalls: number, windowMs: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+EAA+E;AAC/E,8BAAsB,UAAW,SAAQ,KAAK;IAC5C,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;gBAET,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAUzE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,IAAI,EAAG,aAAa,CAAS;gBAE1B,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKxD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,QAAQ,CAAC,IAAI,EAAG,eAAe,CAAS;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEP,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;CAInD;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAS;IAC9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEP,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;CAInD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAS;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;gBAEvB,OAAO,EAAE;QACnB,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,OAAO,CAAA;QAClB,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;KAC3B;CAWF;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAS;gBAE/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAMzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAID,iEAAiE;AACjE,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAS;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;gBAER,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;CAIpC;AAED,+EAA+E;AAC/E,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAS;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;gBAER,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAI/C;AAED,4CAA4C;AAC5C,qBAAa,cAAe,SAAQ,UAAU;IAC5C,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAS;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;gBAER,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI5D"}

package/dist/errors.js

@@ -0,0 +1,171 @@
+/**
+ * Actly error taxonomy.
+ *
+ * Six classes (one abstract base + five concrete). Each carries a stable
+ * `code` field so consumers can switch on strings instead of brittle
+ * `instanceof` chains across realm boundaries (e.g. errors serialised
+ * over IPC).
+ *
+ * # Why these six?
+ *
+ *  - `ActlyError`         — abstract base for `instanceof ActlyError` checks
+ *  - `ActlyAbortError`    — caller / signal cancellation
+ *  - `TimeoutError`       — per-attempt deadline
+ *  - `TotalTimeoutError`  — operation-wide budget
+ *  - `RetryExhaustedError`— last attempt's error wrapped with context
+ *  - `ValidationError`    — programmer error (invalid options)
+ *
+ * NO circuit/bulkhead/rate-limit errors — those policies don't exist in
+ * core. Adding orphan error classes violates the "every feature must map
+ * to a real runtime failure mode" rule.
+ *
+ * # `code` field
+ *
+ * Stable string identifier. Use this for switch statements and telemetry
+ * tags. The class name can change across versions; `code` won't.
+ */
+/** Base class for all actly errors. Enables `instanceof ActlyError` checks. */
+export class ActlyError extends Error {
+    /** The key associated with the failure, if applicable. */
+    key;
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = new.target.name;
+        if (options?.key !== undefined) {
+            Object.defineProperty(this, 'key', { value: options.key, enumerable: true });
+        }
+        // Restore prototype chain after Error inheritance (TS es2022 target
+        // may strip it). This ensures `instanceof` works correctly.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Thrown when the caller's signal, per-attempt timeout, or total timeout
+ * aborts the operation.
+ *
+ * `cause` carries the original abort reason (e.g. user-supplied
+ * `controller.abort(new Error('user-cancelled'))` → cause.message is
+ * 'user-cancelled').
+ *
+ * Wraps the raw abort reason in a typed error so consumers can
+ * `instanceof`-check it consistently across all abort sources.
+ */
+export class ActlyAbortError extends ActlyError {
+    code = 'ACTLY_ABORT';
+    constructor(options) {
+        const causeMsg = options?.cause instanceof Error ? options.cause.message : String(options?.cause ?? 'aborted');
+        super(`Actly operation aborted: ${causeMsg}`, options);
+    }
+}
+/**
+ * Thrown when a per-attempt `timeout` deadline fires.
+ *
+ * Carries the configured `ms` so callers can log/alert precisely:
+ *
+ * ```ts
+ * if (!result.ok && result.error instanceof TimeoutError) {
+ *   console.log(`attempt timed out after ${result.error.ms}ms`)
+ * }
+ * ```
+ */
+export class TimeoutError extends ActlyError {
+    code = 'ACTLY_TIMEOUT';
+    ms;
+    constructor(ms, options) {
+        super(`ACT timed out after ${ms}ms`, options);
+        this.ms = ms;
+    }
+}
+/**
+ * Thrown when the operation-wide `totalTimeout` budget fires.
+ *
+ * Distinct from `TimeoutError` (per-attempt) so callers can `instanceof`-check
+ * which deadline fired.
+ */
+export class TotalTimeoutError extends ActlyError {
+    code = 'ACTLY_TOTAL_TIMEOUT';
+    ms;
+    constructor(ms, options) {
+        super(`ACT total timeout exceeded after ${ms}ms`, options);
+        this.ms = ms;
+    }
+}
+/**
+ * Thrown when all retry attempts are exhausted. The `lastError` is the
+ * final attempt's error; `errors` is the array of all attempt errors
+ * (useful for debugging patterns across retries).
+ *
+ * Wraps retry exhaustion with context so consumers can distinguish "single
+ * fn error" from "retry exhausted after N attempts".
+ *
+ * # When is this thrown vs the raw error?
+ *
+ * `retryPolicy` throws `RetryExhaustedError` when:
+ *  - `attempts > 1` AND
+ *  - all attempts failed AND
+ *  - the default `shouldRetry` (or user-supplied predicate) returned `true`
+ *    for at least one failure
+ *
+ * If the user's `shouldRetry` returns `false` on the first attempt, the
+ * raw error is thrown (no retries happened — not "exhausted").
+ */
+export class RetryExhaustedError extends ActlyError {
+    code = 'ACTLY_RETRY_EXHAUSTED';
+    attempts;
+    lastError;
+    errors;
+    constructor(options) {
+        const lastMsg = options.lastError instanceof Error ? options.lastError.message : String(options.lastError);
+        super(`ACT retry exhausted after ${options.attempts} attempts; last error: ${lastMsg}`, { key: options.key, cause: options.lastError });
+        this.attempts = options.attempts;
+        this.lastError = options.lastError;
+        this.errors = options.errors;
+    }
+}
+/**
+ * Thrown on invalid option shapes / keys / store contracts. Programmer
+ * errors — these surface synchronously, NOT as `ActFailure`, because the
+ * caller's code is broken.
+ *
+ * Wraps the underlying `TypeError` / `RangeError` so consumers catching
+ * `ActlyError` get a consistent type for all actly-thrown errors.
+ */
+export class ValidationError extends ActlyError {
+    code = 'ACTLY_VALIDATION';
+    constructor(message, options) {
+        super(message);
+        if (options?.field !== undefined) {
+            Object.defineProperty(this, 'field', { value: options.field, enumerable: true });
+        }
+    }
+    field;
+}
+// ─── Hardening error classes ─────────────────────────────────────────────────
+/** Thrown when a circuit breaker is open and blocks the call. */
+export class CircuitBreakerOpenError extends ActlyError {
+    code = 'ACTLY_CIRCUIT_OPEN';
+    key;
+    constructor(key, ms) {
+        super(`Circuit breaker open for key "${key}" — retry after ${ms}ms`);
+        this.key = key;
+    }
+}
+/** Thrown when a bulkhead is full (maxConcurrent reached, queue timed out). */
+export class BulkheadOverflowError extends ActlyError {
+    code = 'ACTLY_BULKHEAD_FULL';
+    key;
+    constructor(key, maxConcurrent) {
+        super(`Bulkhead full for key "${key}" — maxConcurrent ${maxConcurrent} reached`);
+        this.key = key;
+    }
+}
+/** Thrown when a rate limit is exceeded. */
+export class RateLimitError extends ActlyError {
+    code = 'ACTLY_RATE_LIMIT';
+    key;
+    constructor(key, maxCalls, windowMs) {
+        super(`Rate limit exceeded for key "${key}" — ${maxCalls} calls per ${windowMs}ms`);
+        this.key = key;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Primary API ──────────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TotalTimeoutError = exports.TimeoutError = exports.isAsyncStore = exports.isSyncStore = exports.InMemoryStore = exports.REQUIRES_SYNC_STORE = exports.execute = exports.withStore = exports.invalidate = exports.act = void 0;
+exports.poolSize = exports.releaseController = exports.acquireController = exports.sanitizeError = exports.sanitizeErrorMessage = exports.createAsyncTenantStore = exports.createTenantStore = exports.drain = exports.createHealthCheck = exports.RateLimitError = exports.BulkheadOverflowError = exports.CircuitBreakerOpenError = exports.LIMITS = exports.computeDelay = exports.sanitizeKey = exports.isAbortError = exports.linkSignal = exports.sleep = exports.raceAbort = exports.anySignal = exports.ValidationError = exports.RetryExhaustedError = exports.TotalTimeoutError = exports.TimeoutError = exports.ActlyAbortError = exports.ActlyError = exports.isAsyncStore = exports.isSyncStore = exports.InMemoryStore = exports.REQUIRES_SYNC_STORE = exports.execute = exports.withStore = exports.invalidate = exports.act = void 0;
 var act_js_1 = require("./core/act.js");
 Object.defineProperty(exports, "act", { enumerable: true, get: function () { return act_js_1.act; } });
 Object.defineProperty(exports, "invalidate", { enumerable: true, get: function () { return act_js_1.invalidate; } });
@@ -17,6 +17,46 @@ var base_js_1 = require("./stores/base.js");
 Object.defineProperty(exports, "isSyncStore", { enumerable: true, get: function () { return base_js_1.isSyncStore; } });
 Object.defineProperty(exports, "isAsyncStore", { enumerable: true, get: function () { return base_js_1.isAsyncStore; } });
 // ─── Error classes ────────────────────────────────────────────────────────────
-var timeout_js_1 = require("./policies/timeout.js");
-Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return timeout_js_1.TimeoutError; } });
-Object.defineProperty(exports, "TotalTimeoutError", { enumerable: true, get: function () { return timeout_js_1.TotalTimeoutError; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "ActlyError", { enumerable: true, get: function () { return errors_js_1.ActlyError; } });
+Object.defineProperty(exports, "ActlyAbortError", { enumerable: true, get: function () { return errors_js_1.ActlyAbortError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "TotalTimeoutError", { enumerable: true, get: function () { return errors_js_1.TotalTimeoutError; } });
+Object.defineProperty(exports, "RetryExhaustedError", { enumerable: true, get: function () { return errors_js_1.RetryExhaustedError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+// ─── Utilities (for custom policy authors) ────────────────────────────────────
+var abort_js_1 = require("./utils/abort.js");
+Object.defineProperty(exports, "anySignal", { enumerable: true, get: function () { return abort_js_1.anySignal; } });
+Object.defineProperty(exports, "raceAbort", { enumerable: true, get: function () { return abort_js_1.raceAbort; } });
+Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return abort_js_1.sleep; } });
+Object.defineProperty(exports, "linkSignal", { enumerable: true, get: function () { return abort_js_1.linkSignal; } });
+Object.defineProperty(exports, "isAbortError", { enumerable: true, get: function () { return abort_js_1.isAbortError; } });
+var key_js_1 = require("./utils/key.js");
+Object.defineProperty(exports, "sanitizeKey", { enumerable: true, get: function () { return key_js_1.sanitizeKey; } });
+var backoff_js_1 = require("./utils/backoff.js");
+Object.defineProperty(exports, "computeDelay", { enumerable: true, get: function () { return backoff_js_1.computeDelay; } });
+var limits_js_1 = require("./utils/limits.js");
+Object.defineProperty(exports, "LIMITS", { enumerable: true, get: function () { return limits_js_1.LIMITS; } });
+// ─── Hardening: new error classes ────────────────────────────────────────────
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "CircuitBreakerOpenError", { enumerable: true, get: function () { return errors_js_2.CircuitBreakerOpenError; } });
+Object.defineProperty(exports, "BulkheadOverflowError", { enumerable: true, get: function () { return errors_js_2.BulkheadOverflowError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_2.RateLimitError; } });
+// ─── Hardening: health check & graceful shutdown ─────────────────────────────
+var health_js_1 = require("./core/health.js");
+Object.defineProperty(exports, "createHealthCheck", { enumerable: true, get: function () { return health_js_1.createHealthCheck; } });
+var shutdown_js_1 = require("./core/shutdown.js");
+Object.defineProperty(exports, "drain", { enumerable: true, get: function () { return shutdown_js_1.drain; } });
+// ─── Hardening: tenant isolation ─────────────────────────────────────────────
+var tenant_js_1 = require("./core/tenant.js");
+Object.defineProperty(exports, "createTenantStore", { enumerable: true, get: function () { return tenant_js_1.createTenantStore; } });
+Object.defineProperty(exports, "createAsyncTenantStore", { enumerable: true, get: function () { return tenant_js_1.createAsyncTenantStore; } });
+// ─── Hardening: error sanitization ───────────────────────────────────────────
+var sanitize_js_1 = require("./utils/sanitize.js");
+Object.defineProperty(exports, "sanitizeErrorMessage", { enumerable: true, get: function () { return sanitize_js_1.sanitizeErrorMessage; } });
+Object.defineProperty(exports, "sanitizeError", { enumerable: true, get: function () { return sanitize_js_1.sanitizeError; } });
+// ─── Hardening: AbortController pool ─────────────────────────────────────────
+var abortPool_js_1 = require("./utils/abortPool.js");
+Object.defineProperty(exports, "acquireController", { enumerable: true, get: function () { return abortPool_js_1.acquireController; } });
+Object.defineProperty(exports, "releaseController", { enumerable: true, get: function () { return abortPool_js_1.releaseController; } });
+Object.defineProperty(exports, "poolSize", { enumerable: true, get: function () { return abortPool_js_1.poolSize; } });

package/dist/index.d.ts

@@ -4,7 +4,22 @@ export { execute, REQUIRES_SYNC_STORE, } from './core/executor.js';
 export { InMemoryStore } from './stores/memory.js';
 export type { InMemoryStoreOptions } from './stores/memory.js';
 export { isSyncStore, isAsyncStore, } from './stores/base.js';
-export { TimeoutError, TotalTimeoutError, } from './policies/timeout.js';
-export type { ActFn, ActResult, ActSuccess, ActFailure, ActSource, ActOptions, RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions, PolicyApplier, PolicyContext, RunMeta, StateStore, // v1.0 alias for SyncStateStore (zero breakage)
+export { ActlyError, ActlyAbortError, TimeoutError, TotalTimeoutError, RetryExhaustedError, ValidationError, } from './errors.js';
+export type { ActlyEventType, ActlyEventBase, AttemptEvent, RetryEvent, CacheHitEvent, CacheMissEvent, DedupeJoinEvent, TimeoutEvent, FinalSuccessEvent, FinalFailureEvent, ActlyEvent, ObservabilityHooks, } from './observability.js';
+export type { ActFn, ActResult, ActSuccess, ActFailure, ActSource, ActOptions, RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions, PolicyApplier, PolicyContext, RunMeta, StateStore, // alias for SyncStateStore (backwards compat)
 SyncStateStore, AsyncStateStore, AnyStateStore, } from './types/index.js';
+export { anySignal, raceAbort, sleep, linkSignal, isAbortError, } from './utils/abort.js';
+export { sanitizeKey, } from './utils/key.js';
+export { computeDelay, } from './utils/backoff.js';
+export { LIMITS, } from './utils/limits.js';
+export type { Limits } from './utils/limits.js';
+export { CircuitBreakerOpenError, BulkheadOverflowError, RateLimitError, } from './errors.js';
+export { createHealthCheck, } from './core/health.js';
+export type { HealthStatus } from './core/health.js';
+export { drain, } from './core/shutdown.js';
+export { createTenantStore, createAsyncTenantStore, } from './core/tenant.js';
+export type { TenantStoreOptions, TenantManager } from './core/tenant.js';
+export { sanitizeErrorMessage, sanitizeError, } from './utils/sanitize.js';
+export { acquireController, releaseController, poolSize, } from './utils/abortPool.js';
+export type { CircuitBreakerOptions, BulkheadOptions, RateLimitOptions, HedgeOptions, FallbackOptions, AuditOptions, AuditEntry, } from './types/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,GAAG,EACH,UAAU,EACV,SAAS,GACV,MAAM,eAAe,CAAA;AAEtB,YAAY,EACV,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAA;AAItB,OAAO,EACL,OAAO,EACP,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAI3B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE9D,OAAO,EACL,WAAW,EACX,YAAY,GACb,MAAM,kBAAkB,CAAA;AAIzB,OAAO,EACL,YAAY,EACZ,iBAAiB,GAClB,MAAM,uBAAuB,CAAA;AAI9B,YAAY,EAEV,KAAK,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EAGV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EAGZ,aAAa,EACb,aAAa,EACb,OAAO,EAGP,UAAU,EAAS,gDAAgD;AACnE,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,GAAG,EACH,UAAU,EACV,SAAS,GACV,MAAM,eAAe,CAAA;AAEtB,YAAY,EACV,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAA;AAItB,OAAO,EACL,OAAO,EACP,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAI3B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE9D,OAAO,EACL,WAAW,EACX,YAAY,GACb,MAAM,kBAAkB,CAAA;AAIzB,OAAO,EACL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAA;AAIpB,YAAY,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,EACd,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,oBAAoB,CAAA;AAI3B,YAAY,EAEV,KAAK,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EAGV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EAGZ,aAAa,EACb,aAAa,EACb,OAAO,EAGP,UAAU,EAAS,8CAA8C;AACjE,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,kBAAkB,CAAA;AAIzB,OAAO,EACL,SAAS,EACT,SAAS,EACT,KAAK,EACL,UAAU,EACV,YAAY,GACb,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,YAAY,GACb,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,MAAM,GACP,MAAM,mBAAmB,CAAA;AAE1B,YAAY,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAI/C,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAA;AAIpB,OAAO,EACL,iBAAiB,GAClB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,EACL,KAAK,GACN,MAAM,oBAAoB,CAAA;AAI3B,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAIzE,OAAO,EACL,oBAAoB,EACpB,aAAa,GACd,MAAM,qBAAqB,CAAA;AAI5B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,GACT,MAAM,sBAAsB,CAAA;AAI7B,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,UAAU,GACX,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -6,5 +6,21 @@ export { execute, REQUIRES_SYNC_STORE, } from './core/executor.js';
 export { InMemoryStore } from './stores/memory.js';
 export { isSyncStore, isAsyncStore, } from './stores/base.js';
 // ─── Error classes ────────────────────────────────────────────────────────────
-export { TimeoutError, TotalTimeoutError, } from './policies/timeout.js';
+export { ActlyError, ActlyAbortError, TimeoutError, TotalTimeoutError, RetryExhaustedError, ValidationError, } from './errors.js';
+// ─── Utilities (for custom policy authors) ────────────────────────────────────
+export { anySignal, raceAbort, sleep, linkSignal, isAbortError, } from './utils/abort.js';
+export { sanitizeKey, } from './utils/key.js';
+export { computeDelay, } from './utils/backoff.js';
+export { LIMITS, } from './utils/limits.js';
+// ─── Hardening: new error classes ────────────────────────────────────────────
+export { CircuitBreakerOpenError, BulkheadOverflowError, RateLimitError, } from './errors.js';
+// ─── Hardening: health check & graceful shutdown ─────────────────────────────
+export { createHealthCheck, } from './core/health.js';
+export { drain, } from './core/shutdown.js';
+// ─── Hardening: tenant isolation ─────────────────────────────────────────────
+export { createTenantStore, createAsyncTenantStore, } from './core/tenant.js';
+// ─── Hardening: error sanitization ───────────────────────────────────────────
+export { sanitizeErrorMessage, sanitizeError, } from './utils/sanitize.js';
+// ─── Hardening: AbortController pool ─────────────────────────────────────────
+export { acquireController, releaseController, poolSize, } from './utils/abortPool.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,OAAO,EACL,GAAG,EACH,UAAU,EACV,SAAS,GACV,MAAM,eAAe,CAAA;AAOtB,iFAAiF;AAEjF,OAAO,EACL,OAAO,EACP,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAE3B,iFAAiF;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EACL,WAAW,EACX,YAAY,GACb,MAAM,kBAAkB,CAAA;AAEzB,iFAAiF;AAEjF,OAAO,EACL,YAAY,EACZ,iBAAiB,GAClB,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,OAAO,EACL,GAAG,EACH,UAAU,EACV,SAAS,GACV,MAAM,eAAe,CAAA;AAOtB,iFAAiF;AAEjF,OAAO,EACL,OAAO,EACP,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAE3B,iFAAiF;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EACL,WAAW,EACX,YAAY,GACb,MAAM,kBAAkB,CAAA;AAEzB,iFAAiF;AAEjF,OAAO,EACL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAA;AAgDpB,iFAAiF;AAEjF,OAAO,EACL,SAAS,EACT,SAAS,EACT,KAAK,EACL,UAAU,EACV,YAAY,GACb,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,YAAY,GACb,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,MAAM,GACP,MAAM,mBAAmB,CAAA;AAI1B,gFAAgF;AAEhF,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,GAClB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,KAAK,GACN,MAAM,oBAAoB,CAAA;AAE3B,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,kBAAkB,CAAA;AAGzB,gFAAgF;AAEhF,OAAO,EACL,oBAAoB,EACpB,aAAa,GACd,MAAM,qBAAqB,CAAA;AAE5B,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,GACT,MAAM,sBAAsB,CAAA"}

package/dist/observability.cjs

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Observability hooks.
+ *
+ * Eight event types covering the entire lifecycle of an `act()` call.
+ *
+ * # Contract
+ *
+ * When `options.observability` is `null`/`undefined` (the common case),
+ * no event objects are allocated and no function calls are made. The
+ * hot path is a single null-check per policy decision.
+ *
+ * When hooks ARE registered, events are allocated lazily — only when the
+ * corresponding event actually fires. A cache hit doesn't allocate an
+ * `onRetry` event, for example.
+ *
+ * # Event shape
+ *
+ * Every event carries `key`, `traceId`, and `timestamp` for correlation.
+ * Event-specific fields are on the same object (no nesting) for flat
+ * destructuring in user code.
+ *
+ * # Ordering
+ *
+ * For a successful fresh call with retries:
+ *   onAttempt (1) → onAttempt (2) → onRetry (1→2) → onAttempt (3) → onFinalSuccess
+ *
+ * For a cache hit:
+ *   onCacheHit → onFinalSuccess
+ *
+ * For a dedupe joiner:
+ *   onDedupeJoin → onFinalSuccess (or onFinalFailure)
+ *
+ * For a timeout:
+ *   onAttempt → onTimeout → onFinalFailure
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasObservers = hasObservers;
+/**
+ * Quick null-check helper. Policies call this once at decision points; if
+ * it returns false, no further observability work is done.
+ */
+function hasObservers(ctx) {
+    return ctx.observability != null;
+}

package/dist/observability.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Observability hooks.
+ *
+ * Eight event types covering the entire lifecycle of an `act()` call.
+ *
+ * # Contract
+ *
+ * When `options.observability` is `null`/`undefined` (the common case),
+ * no event objects are allocated and no function calls are made. The
+ * hot path is a single null-check per policy decision.
+ *
+ * When hooks ARE registered, events are allocated lazily — only when the
+ * corresponding event actually fires. A cache hit doesn't allocate an
+ * `onRetry` event, for example.
+ *
+ * # Event shape
+ *
+ * Every event carries `key`, `traceId`, and `timestamp` for correlation.
+ * Event-specific fields are on the same object (no nesting) for flat
+ * destructuring in user code.
+ *
+ * # Ordering
+ *
+ * For a successful fresh call with retries:
+ *   onAttempt (1) → onAttempt (2) → onRetry (1→2) → onAttempt (3) → onFinalSuccess
+ *
+ * For a cache hit:
+ *   onCacheHit → onFinalSuccess
+ *
+ * For a dedupe joiner:
+ *   onDedupeJoin → onFinalSuccess (or onFinalFailure)
+ *
+ * For a timeout:
+ *   onAttempt → onTimeout → onFinalFailure
+ */
+import type { ActSource } from './types/index.js';
+/** Stable discriminator for telemetry. */
+export type ActlyEventType = 'attempt' | 'retry' | 'cache-hit' | 'cache-miss' | 'dedupe-join' | 'timeout' | 'final-success' | 'final-failure';
+/** Common fields on every event. */
+export interface ActlyEventBase {
+    /** The `key` passed to `act()`. */
+    readonly key: string;
+    /** Auto-generated trace ID (or user-supplied via `options.traceId`). */
+    readonly traceId: string;
+    /** Event timestamp (ms since epoch). */
+    readonly timestamp: number;
+    /** Discriminator for switch statements. */
+    readonly type: ActlyEventType;
+}
+export interface AttemptEvent extends ActlyEventBase {
+    readonly type: 'attempt';
+    /** 1-based attempt number. */
+    readonly attempt: number;
+    /** Duration of this attempt in ms (set after attempt settles). */
+    readonly durationMs?: number;
+    /** Error from this attempt, if it failed. */
+    readonly error?: unknown;
+}
+export interface RetryEvent extends ActlyEventBase {
+    readonly type: 'retry';
+    /** The attempt that just failed. */
+    readonly attempt: number;
+    /** The delay (ms) before the next attempt. */
+    readonly delayMs: number;
+    /** Error that triggered the retry. */
+    readonly error: unknown;
+}
+export interface CacheHitEvent extends ActlyEventBase {
+    readonly type: 'cache-hit';
+    /** Age of the cached value in ms. */
+    readonly ageMs: number;
+}
+export interface CacheMissEvent extends ActlyEventBase {
+    readonly type: 'cache-miss';
+}
+export interface DedupeJoinEvent extends ActlyEventBase {
+    readonly type: 'dedupe-join';
+    /** This caller's position in the joiner queue (1 = first joiner). */
+    readonly joinerPosition: number;
+}
+export interface TimeoutEvent extends ActlyEventBase {
+    readonly type: 'timeout';
+    /** Which deadline fired. */
+    readonly kind: 'per-attempt' | 'total';
+    /** The configured ms. */
+    readonly ms: number;
+}
+export interface FinalSuccessEvent extends ActlyEventBase {
+    readonly type: 'final-success';
+    /** Where the value came from. */
+    readonly source: ActSource;
+    /** Total attempts made (0 for cache hit). */
+    readonly attempts: number;
+    /** Total wall-clock duration of the act() call. */
+    readonly durationMs: number;
+}
+export interface FinalFailureEvent extends ActlyEventBase {
+    readonly type: 'final-failure';
+    /** Total attempts made. */
+    readonly attempts: number;
+    /** Total wall-clock duration of the act() call. */
+    readonly durationMs: number;
+    /** Stable reason for failure — use for telemetry tags. */
+    readonly failedBy: 'abort' | 'timeout' | 'total-timeout' | 'retry-exhausted' | 'fn-error' | 'validation';
+    /** The final error. */
+    readonly error: unknown;
+}
+export type ActlyEvent = AttemptEvent | RetryEvent | CacheHitEvent | CacheMissEvent | DedupeJoinEvent | TimeoutEvent | FinalSuccessEvent | FinalFailureEvent;
+/**
+ * User-supplied observability hooks. All optional. When absent, zero
+ * overhead is incurred on the hot path.
+ */
+export interface ObservabilityHooks {
+    onAttempt?: (event: AttemptEvent) => void;
+    onRetry?: (event: RetryEvent) => void;
+    onCacheHit?: (event: CacheHitEvent) => void;
+    onCacheMiss?: (event: CacheMissEvent) => void;
+    onDedupeJoin?: (event: DedupeJoinEvent) => void;
+    onTimeout?: (event: TimeoutEvent) => void;
+    onFinalSuccess?: (event: FinalSuccessEvent) => void;
+    onFinalFailure?: (event: FinalFailureEvent) => void;
+}
+/**
+ * Internal: thread observability through the policy chain without changing
+ * every policy's signature. We attach it to `PolicyContext` as an optional
+ * field — policies that emit events check for its presence.
+ *
+ * `traceId` is also stored here so policies can include it in events.
+ */
+export interface ObservabilityContext {
+    traceId: string;
+    hooks: ObservabilityHooks;
+    /** Counter for dedupe joiner position. Per-key, but we approximate by call. */
+    joinerCounter: number;
+}
+/**
+ * Quick null-check helper. Policies call this once at decision points; if
+ * it returns false, no further observability work is done.
+ */
+export declare function hasObservers(ctx: {
+    observability?: ObservabilityContext;
+}): ctx is {
+    observability: ObservabilityContext;
+};
+//# sourceMappingURL=observability.d.ts.map