@gkoos/caracal 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
-# Changelog
-
-## 0.1.0 - 2026-09-09
-
-Initial public release.
+# Changelog
+
+## 0.1.1
+
+### Patch Changes
+
+- cf60c44: Fixed
+  
+  - `failureThreshold` values that the distributed coordinator cannot resolve to thousandths are rejected at construction instead of being silently reinterpreted. Below `0.0005` the numerator rounded to 0, which made the comparison unconditionally true - the breaker opened on a success-only window and re-opened after every recovery; at `0.9995` and above it rounded to 1000, requiring every observation to fail, so the breaker effectively never opened
+  - `circuitBreaker.local` enforces the same `0.0005 <= failureThreshold < 0.9995` range, so one policy config behaves the same under either coordination
+  - an ignored result recorded nothing but also settled nothing, so a distributed half-open probe kept its slot until the probe lease elapsed: after an operation whose classifier returned `ignored`, the next call was rejected with `CircuitOpenError` for up to `probeLeaseTtlMs` (60s with the defaults), while the local breaker released its slot immediately. An ignored probe result now releases its slot without recording an outcome or advancing recovery, so one policy config behaves the same under either coordination
+  - packaging and event fixes: `engines.node` now requires `>=20.3.0` (the runtime, timeout and bulkhead policies, and the fetch adapter use `AbortSignal.any`, which landed in 20.3.0, so 20.0-20.2 installed cleanly and then failed at runtime); the published package now also ships `test/harness`, so the `@gkoos/caracal/testing` entry point has published source like every other entry point; and a local bulkhead's `bulkhead.released` event now reports its occupancy before the queued successor is admitted, instead of appearing to include it
+
+## 0.1.0 - 2026-09-09
+
+Initial public release.

package/README.md

@@ -2,6 +2,16 @@
   <img src="docs/caracal.svg" alt="Caracal" width="140">
 </p>
 
+![npm](https://img.shields.io/npm/v/@gkoos/caracal)
+![Downloads](https://img.shields.io/npm/dm/@gkoos/caracal)
+![GitHub stars](https://img.shields.io/github/stars/gkoos/caracal?style=social)
+
+![Build](https://github.com/gkoos/caracal/actions/workflows/ci.yml/badge.svg)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/gkoos/caracal/badge)](https://scorecard.dev/viewer/?uri=github.com/gkoos/caracal)
+
+![MIT](https://img.shields.io/npm/l/@gkoos/caracal)
+![Types](https://img.shields.io/npm/types/@gkoos/caracal)
+
 # Caracal
 
 **Scoped distributed resilience for asynchronous operations.**

package/dist/{circuit-breaker-BSkcV0W_.d.ts → circuit-breaker-DHEz0YLV.d.ts}

@@ -185,7 +185,12 @@ interface BreakerCoordinator {
     }): Promise<AdmitProbeResult>;
     settleProbe(identity: BreakerIdentity, params: {
         readonly probeToken: string;
-        readonly outcome: "success" | "failure";
+        /**
+         * `"success"` and `"failure"` record an outcome; `"ignored"` releases the
+         * probe's slot without recording anything, which is what the policy sends
+         * when its classifier ignores the result.
+         */
+        readonly outcome: "success" | "failure" | "ignored";
         readonly generation: number;
         readonly halfOpenSuccesses: number;
         readonly openMs: number;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AdmitProbeResult, B as BreakerClassifier, a as BreakerCoordinator, b as BreakerIdentity, c as BreakerOutcome, d as BreakerSnapshot, e as BreakerState, f as BulkheadCoordinator, g as BulkheadRejectedError, C as CircuitOpenError, D as DistributedBreakerOptions, h as DistributedBulkheadOptions, L as LocalBreakerOptions, i as LocalBulkheadOptions, O as ObserveResult, S as SettleProbeResult, j as bulkhead, k as circuitBreaker } from './circuit-breaker-BSkcV0W_.js';
+export { A as AdmitProbeResult, B as BreakerClassifier, a as BreakerCoordinator, b as BreakerIdentity, c as BreakerOutcome, d as BreakerSnapshot, e as BreakerState, f as BulkheadCoordinator, g as BulkheadRejectedError, C as CircuitOpenError, D as DistributedBreakerOptions, h as DistributedBulkheadOptions, L as LocalBreakerOptions, i as LocalBulkheadOptions, O as ObserveResult, S as SettleProbeResult, j as bulkhead, k as circuitBreaker } from './circuit-breaker-DHEz0YLV.js';
 import { a as OperationOptions, b as Operation, P as Policy } from './types-Tf9T76C7.js';
 export { A as Adapter, C as Classification, E as EventSink, c as EventSinks, d as ExecutionContext, e as ExecutionMetadata, N as Next, O as OperationCapabilities, f as OperationEvent, g as OperationExecuteOptions, h as Outcome, i as OutcomeClassifier } from './types-Tf9T76C7.js';
 export { R as RetryContext, a as RetryDelay, b as RetryOptions, r as retry } from './retry-BFP_k3Hg.js';

package/dist/index.js

@@ -97,8 +97,8 @@ function local(options) {
         return await next(context);
       } finally {
         occupancy--;
-        waiting[0]?.();
         event(context, "local", name, "process", "released", occupancy);
+        waiting[0]?.();
       }
     }
   });
@@ -320,6 +320,14 @@ var DEFAULT_OPEN_MS = 1e4;
 var DEFAULT_HALF_OPEN_SUCCESSES = 1;
 var DEFAULT_HALF_OPEN_PROBES = 1;
 var DEFAULT_WINDOW_SIZE = 100;
+var FAILURE_THRESHOLD_SCALE = 1e3;
+function assertResolvableThreshold(failureThreshold) {
+  const numerator = Math.round(failureThreshold * FAILURE_THRESHOLD_SCALE);
+  if (numerator < 1 || numerator >= FAILURE_THRESHOLD_SCALE)
+    throw new RangeError(
+      `failureThreshold must be at least 0.0005 and below 0.9995 (thresholds are resolved to thousandths); got ${failureThreshold}`
+    );
+}
 function validate2(opts) {
   if (!opts.name.trim())
     throw new RangeError("Circuit breaker name must not be empty");
@@ -329,6 +337,7 @@ function validate2(opts) {
   const { failureThreshold = DEFAULT_FAILURE_THRESHOLD } = opts;
   if (!Number.isFinite(failureThreshold) || failureThreshold <= 0 || failureThreshold >= 1)
     throw new RangeError("failureThreshold must be a number in (0, 1)");
+  assertResolvableThreshold(failureThreshold);
   const { openMs = DEFAULT_OPEN_MS } = opts;
   if (!Number.isInteger(openMs) || openMs < 1)
     throw new RangeError("openMs must be a positive integer");
@@ -571,6 +580,7 @@ function validateDistributed(opts) {
   const { failureThreshold = DEFAULT_DIST_FAILURE_THRESHOLD } = opts;
   if (!Number.isFinite(failureThreshold) || failureThreshold <= 0 || failureThreshold >= 1)
     throw new RangeError("failureThreshold must be a number in (0, 1)");
+  assertResolvableThreshold(failureThreshold);
   const { openMs = DEFAULT_DIST_OPEN_MS } = opts;
   if (!Number.isInteger(openMs) || openMs < 1)
     throw new RangeError("openMs must be a positive integer");
@@ -603,7 +613,9 @@ function distributed2(options) {
   const resolveScope = options.scope;
   const minimumThroughput = options.minimumThroughput ?? DEFAULT_DIST_MINIMUM_THROUGHPUT;
   const failureThreshold = options.failureThreshold ?? DEFAULT_DIST_FAILURE_THRESHOLD;
-  const failureThresholdNumerator = Math.round(failureThreshold * 1e3);
+  const failureThresholdNumerator = Math.round(
+    failureThreshold * FAILURE_THRESHOLD_SCALE
+  );
   const windowSize = options.windowSize ?? DEFAULT_DIST_WINDOW_SIZE;
   const openMs = options.openMs ?? DEFAULT_DIST_OPEN_MS;
   const windowTtlMs = options.windowTtlMs ?? Math.max(openMs * 3, 6e4);
@@ -767,8 +779,9 @@ function distributed2(options) {
           classifier,
           isSuccess ? { status: "success", value } : { status: "failure", error: thrownError }
         );
-        if (breakerOutcome !== "ignored") {
+        if (breakerOutcome !== "ignored" || admission.kind === "probe") {
           const outcomeStr = breakerOutcome === "success" ? "success" : "failure";
+          const settleOutcome = breakerOutcome === "ignored" ? "ignored" : outcomeStr;
           if (admission.kind === "closed") {
             try {
               const result = await coordinator.observe(identity, {
@@ -826,49 +839,51 @@ function distributed2(options) {
             try {
               const result = await coordinator.settleProbe(identity, {
                 probeToken: admission.probeToken,
-                outcome: outcomeStr,
+                outcome: settleOutcome,
                 generation: admission.generation,
                 halfOpenSuccesses,
                 openMs,
                 windowTtlMs
               });
-              if (result.type === "stale") {
-                emitRuntimeEvent(context, {
-                  type: "breaker.observation-stale",
-                  coordination: "distributed",
-                  policyName: name,
-                  scope,
-                  attemptGeneration: admission.generation,
-                  currentGeneration: result.generation
-                });
-              } else {
-                emitRuntimeEvent(context, {
-                  type: "breaker.observation",
-                  coordination: "distributed",
-                  policyName: name,
-                  scope,
-                  outcome: outcomeStr,
-                  generation: admission.generation
-                });
-                if (result.type === "transitioned") {
-                  if (result.newState === "closed") {
-                    lastKnownState.forget(identity.operation, scope);
-                  } else {
-                    lastKnownState.remember(
-                      identity.operation,
-                      scope,
-                      result.newState
-                    );
-                  }
+              if (breakerOutcome !== "ignored") {
+                if (result.type === "stale") {
                   emitRuntimeEvent(context, {
-                    type: "breaker.state-changed",
+                    type: "breaker.observation-stale",
                     coordination: "distributed",
                     policyName: name,
                     scope,
-                    state: result.newState,
-                    previousState: "half-open",
-                    generation: result.newGeneration
+                    attemptGeneration: admission.generation,
+                    currentGeneration: result.generation
+                  });
+                } else {
+                  emitRuntimeEvent(context, {
+                    type: "breaker.observation",
+                    coordination: "distributed",
+                    policyName: name,
+                    scope,
+                    outcome: outcomeStr,
+                    generation: admission.generation
                   });
+                  if (result.type === "transitioned") {
+                    if (result.newState === "closed") {
+                      lastKnownState.forget(identity.operation, scope);
+                    } else {
+                      lastKnownState.remember(
+                        identity.operation,
+                        scope,
+                        result.newState
+                      );
+                    }
+                    emitRuntimeEvent(context, {
+                      type: "breaker.state-changed",
+                      coordination: "distributed",
+                      policyName: name,
+                      scope,
+                      state: result.newState,
+                      previousState: "half-open",
+                      generation: result.newGeneration
+                    });
+                  }
                 }
               }
             } catch (settleError) {