docs: align the full-stack demo with the breaker-before-timeout order

Author: lesnik512

docs/demos/engine.js

@@ -793,11 +793,10 @@ window.HttpwareDemo = (function () {
             if (L.pend[i].land <= tick) {
               const p = L.pend[i]; L.pend.splice(i, 1);
               let retried = false;
-              // AsyncTimeout bounds the WHOLE operation (outermost: timeout ->
-              // circuitBreaker -> bulkhead -> retry -> terminal). An entry clamped
-              // to its deadline (see clampToDeadline) lands as a TimeoutError
-              // failure here, regardless of what the untimed outcome would have
-              // been, and is never retried.
+              // AsyncTimeout bounds the WHOLE operation (circuitBreaker -> timeout ->
+              // bulkhead -> retry -> terminal). An entry clamped to its deadline (see
+              // clampToDeadline) lands as a TimeoutError failure here, regardless of
+              // what the untimed outcome would have been, and is never retried.
               if (L === B && p.timedOut) {
                 timedOutCount++;
               // Retry decision happens at landing time: a failed lane-B attempt gets
@@ -811,7 +810,7 @@ window.HttpwareDemo = (function () {
                   const backoffSec = rnd() * Math.min(retryCfg.maxDelay, retryCfg.baseDelay * Math.pow(2, p.attempt));
                   const f2 = scenario.fault(now + backoffSec, rnd);
                   const landTicks = Math.max(1, Math.round((backoffSec + f2.ms) * 1000 / TICK));
-                  // Composition order is timeout -> circuitBreaker -> bulkhead -> retry ->
+                  // Composition order is circuitBreaker -> timeout -> bulkhead -> retry ->
                   // terminal: the bulkhead sits OUTSIDE retry, so one slot is acquired
                   // once and held for the WHOLE operation (all attempts), released only
                   // when the operation finally lands. Carry `bh` forward on every retry
@@ -833,14 +832,12 @@ window.HttpwareDemo = (function () {
               // so a null/absent bulkhead or a rejected (never-pushed) request is a no-op.
               // Breaker records ONCE per fully-exhausted retry sequence (not per attempt):
               // brk.res is called here, only on the terminal (non-retried) landing. A
-              // timed-out entry is an outer-timeout cancellation: AsyncTimeout is
-              // OUTERMOST, so the inner breaker's `except BaseException` clause does see
-              // the CancelledError (it releases the in-flight probe slot) but does not
-              // count it as a success/failure outcome — only the outer TimeoutError
-              // surfaces to the caller.
+              // timed-out entry counts as a failure: the breaker sits OUTSIDE
+              // AsyncTimeout, so the TimeoutError raised on expiry passes through it
+              // as a counted failure (a CancelledError would not be counted).
               if (!retried) {
                 L.if--;
-                if (L === B && p.timedOut) { L.bad++; }
+                if (L === B && p.timedOut) { if (brk) brk.res(false, now); L.bad++; }
                 else { if (L === B && brk) brk.res(p.ok, now); if (p.ok) L.ok++; else L.bad++; }
                 if (L === B && bulk && p.bh) bulk.release();
               }
@@ -864,8 +861,9 @@ window.HttpwareDemo = (function () {
             B.rej++; spawnDot(dotsB, els.trackB, 'rej');
           } else {
             if (budget) budget.deposit(now);
-            // Total deadline set once at the first attempt (Infinity when no
-            // AsyncTimeout is configured, so the clamp below is always a no-op).
+            // Total deadline set once at the first attempt, after the breaker admitted
+            // the request, so an open circuit rejects before any deadline starts
+            // (Infinity when no AsyncTimeout is configured: the clamp is a no-op).
             const deadline = tmoCfg ? now + tmoCfg.timeout : Infinity;
             const { land, timedOut } = clampToDeadline(tick, landTicks, deadline);
             B.if++; B.pend.push({ land, ok: f.ok, attempt: 0, bh: !!bulk, start: now, deadline, timedOut });

docs/demos/full-stack.md

@@ -1,7 +1,7 @@
 # Full stack: combining the patterns
 
 Real clients combine these patterns, in the recommended order
-`AsyncTimeout -> AsyncCircuitBreaker -> AsyncBulkhead -> AsyncRetry -> terminal`.
+`AsyncCircuitBreaker -> AsyncTimeout -> AsyncBulkhead -> AsyncRetry -> terminal`.
 Here both clients go through an incident in three phases, and each layer handles a
 different phase.
 
@@ -13,30 +13,32 @@ document.addEventListener('DOMContentLoaded', function () {
   scenarios: [
     { id: 'incident', label: 'Multi-phase incident', dur: 16.0,
       fault: (now, rnd) => {
-        if (now >= 2.0 && now < 5.0) return { ok: true, ms: 4.0, label: 'latency spike' };
-        if (now >= 5.0 && now < 8.0) return rnd() < 0.6
+        if (now >= 2.0 && now < 5.0) return rnd() < 0.6
           ? { ok: false, ms: 0.6, label: 'brownout' } : { ok: true, ms: 0.6 };
+        if (now >= 5.0 && now < 8.0) return { ok: true, ms: 4.0, label: 'latency spike' };
         if (now >= 8.0 && now < 12.0) return { ok: false, ms: 0.3, label: 'hard down' };
         return { ok: true, ms: 0.05 };
       },
-      chainB: { timeout: { timeout: 2.0 },
-                circuitBreaker: { failureThreshold: 5, resetTimeout: 2.0, successThreshold: 1 },
+      chainB: { circuitBreaker: { failureThreshold: 5, resetTimeout: 2.0, successThreshold: 1 },
+                timeout: { timeout: 2.0 },
                 bulkhead: { maxConcurrent: 10, acquireTimeout: 0 },
                 retry: { maxAttempts: 3, baseDelay: 0.1, maxDelay: 5.0 },
                 budget: { ttl: 10.0, minRetriesPerSec: 10.0, percentCanRetry: 0.2 } } },
   ],
   macroStrip: true,
   stageLabel: (now) => now < 2 ? 'healthy'
-    : now < 5 ? 'phase 1: latency spike'
-    : now < 8 ? 'phase 2: brownout'
+    : now < 5 ? 'phase 1: brownout'
+    : now < 8 ? 'phase 2: latency spike'
     : now < 12 ? 'phase 3: hard down' : 'recovered',
   buildStops: () => [
-    { when: (s) => s.now >= 2.4, spot: ['poolB', 'elapsedB'], title: 'Phase 1: latency spike',
-      body: 'The bulkhead caps concurrency so the slow phase cannot exhaust the client, and the timeout ends each operation after 2s.' },
-    { when: (s) => s.now >= 5.4, spot: ['ifB'], title: 'Phase 2: brownout',
+    { when: (s) => s.now >= 2.4, spot: ['ifB'], title: 'Phase 1: brownout',
       body: 'Retry recovers many of the transient errors, and the budget stops it from adding much load.' },
-    { when: (s) => s.mw.cb && s.mw.cb.state === 'OPEN', spot: ['brkB'], title: 'Phase 3: hard down',
-      body: 'Repeated failures open the breaker. It sits before the retry layer, so it rejects whole retry sequences and counts one outcome per sequence, not per attempt.' },
+    { when: (s) => s.now >= 5.4, spot: ['poolB', 'elapsedB'], title: 'Phase 2: latency spike',
+      body: 'The bulkhead caps concurrency so the slow upstream cannot exhaust the client, and the timeout ends each operation after 2s.' },
+    { when: (s) => s.mw.cb && s.mw.cb.state === 'OPEN', spot: ['brkB'], title: 'Timeouts open the breaker',
+      body: 'The breaker sits before the timeout, so each expired deadline counts as a failure. After five in a row the circuit opens, and new calls fail at once instead of waiting 2s on the slow upstream.' },
+    { when: (s) => s.now >= 8.5, spot: ['brkB'], title: 'Phase 3: hard down',
+      body: 'The circuit stays open through the outage, because each half-open probe fails and reopens it. It sits before the retry layer, so it rejects whole retry sequences and counts one outcome per sequence, not per attempt.' },
     { when: (s) => s.now >= 13.5, spot: ['ifA', 'latA', 'ifB', 'latB'], title: 'Full stack vs none',
       body: 'The plain client fails through every phase. In the httpware client, each layer handles the phase it is built for.' },
   ],