From e49a73e52945eef72ee533564c8f7aa971b0202d Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Wed, 2 Sep 2026 14:11:27 -0700
Subject: [PATCH] docs(flush): the ES-private note reads after the gate's
 contract, not through it

The #-private rationale landed spliced into the middle of each method's
description, cutting one sentence in half. Same words, moved below the
behaviour they annotate.
---
 src/brainy.ts | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/brainy.ts b/src/brainy.ts
index 15f51ef9..b8eb7f56 100644
--- a/src/brainy.ts
+++ b/src/brainy.ts
@@ -13347,18 +13347,17 @@ export class Brainy<T = any> implements BrainyInterface<T> {
 
   /**
    * @description Run one flush body as the leader and install it as
-   * `_flushInFlight`.
-   *
-   * ECMAScript-private (`#`), not TypeScript `private`: `private` is erased at
-   * compile time, so the method still lands on the prototype and the contract
-   * manifest — which reads the surface the BUILD exposes — emitted it as a
-   * door. A door is a promise every engine implementing the contract must
-   * keep, and this is the flush gate's own bookkeeping, not a promise. `#`
-   * keeps it off the prototype, so the emitter cannot see it.
-   * On settle — resolved OR rejected — the gate opens and
+   * `_flushInFlight`. On settle — resolved OR rejected — the gate opens and
    * the ONE queued waiter (if any) is promoted. The `finally` callback returns
    * nothing on purpose: a callback that returned the promoted run's promise
    * would make the leader await its own follower.
+   *
+   * ECMAScript-private (`#`), not TypeScript `private`: `private` is erased at
+   * compile time, so the method would still land on the prototype — and the
+   * contract manifest reads the surface the BUILD exposes, so it would emit
+   * this as a contract door. A door is a promise every engine implementing the
+   * contract must keep; this is the flush gate's own bookkeeping. `#` keeps it
+   * off the prototype, where the emitter cannot see it.
    * @returns The leader's own promise, settling on its own body alone.
    */
   #startFlushLeader(): Promise<void> {
@@ -13376,11 +13375,12 @@ export class Brainy<T = any> implements BrainyInterface<T> {
 
   /**
    * @description Promote the single queued waiter (if one is waiting) to
-   * leader and settle its deferred from that run. ECMAScript-private for the
-   * same reason as {@link flush}'s leader starter: internals are not doors.
-   * Never throws into the
+   * leader and settle its deferred from that run. Never throws into the
    * leader's `finally`: a synchronous failure starting the promoted run is
    * reported to the waiter, which must be settled on every path.
+   *
+   * ECMAScript-private for the same reason as the leader starter above:
+   * internals are not doors.
    * @returns Nothing.
    */
   #promoteQueuedFlush(): void {