@serfab/cadre-core 1.17.0 → 1.19.0

package/dist/control-cohort.d.ts

@@ -22,17 +22,44 @@
  */
 import type { CohortPeerRow } from './strand-cohort.js';
 /**
- * Default recurring cadence for {@link CadreNode.reconcileControlCohort} (ms).
- * In the same spirit as the 5s strand-watch poll but lighter, since a control
- * cohort changes far less often than strand activity.
+ * Default backstop for {@link CadreNode.reconcileControlCohort} (ms): a pass runs this long
+ * after the last one settled whether or not anything woke it. Passes normally run on a
+ * change — a membership table changing, a sibling connecting or disconnecting, an address
+ * change — and on the retries a pass arms for itself ({@link nextReconcileWakeMs}); the
+ * backstop bounds how stale this node can be after a change it hears nothing of: one that
+ * reaches it with no storage event, which happens to a machine outside the block's cohort
+ * (a cadre larger than `CONTROL_REPLICATION_BREADTH`) and to one in the cohort that the
+ * writer could not reach when it committed. The membership rows view's maximum age
+ * (`MEMBERSHIP_VIEW_MAX_AGE_MS`, 15 s) is shorter than this, so the backstop pass reads
+ * storage and starts the cohort consult that brings such a change in.
  *
- * An interval between pass starts, not a deadline on a pass. Passes are
- * single-flight, so a pass that runs longer than this is joined rather than
- * stacked, and the effective cadence becomes the pass length: one unreachable
- * sibling's dial alone can take the whole per-peer dial budget (86 s at the
- * default declared link).
+ * `network.controlCohort.reconcileMs` overrides it. An interval between a pass settling and
+ * the next start, not a deadline on a pass: passes are single-flight, and one unreachable
+ * sibling's dial alone can take the whole per-peer dial budget (86 s at the default
+ * declared link).
+ *
+ * NOTE: a machine whose storage takes no event for a change — one outside the block's cohort
+ * in a cadre larger than `CONTROL_REPLICATION_BREADTH` (16 machines), or one the writer could
+ * not reach when it committed — sees it only at this backstop, where the change-driven path
+ * serves a machine the commit reached within the 50 ms coalescing window. If a party ever
+ * needs a tighter bound, lower the backstop for its nodes or give the plugin's change bridge
+ * a path for outside-the-cohort reads.
+ */
+export declare const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 120000;
+/**
+ * First redial delay after a pass's dial of a selected sibling, or a cold-start bootstrap peer,
+ * fails (ms). Doubles per consecutive such pass and is capped at the backstop, so a
+ * sibling that is offline costs one dial per backstop once the ladder saturates, and a
+ * stranded cold-start node keeps trying forever (15 s, 30 s, 60 s, then every backstop).
  */
-export declare const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15000;
+export declare const CONTROL_COHORT_REDIAL_MS = 15000;
+/**
+ * How often an owner retries a node it has just claimed while that node restarts into the
+ * owner's party (ms; `CadreNode.claimNode`). A poll step, not a deadline: the retries run for
+ * {@link CONTROL_COHORT_REDIAL_MS} after the node accepts the claim, the delay of the reconcile
+ * pass's first redial, which would otherwise be the owner's next dial of the node.
+ */
+export declare const CLAIM_RESTART_REDIAL_STEP_MS = 1000;
 /**
  * Default cap on the number of **non-backbone** members a single reconcile pass
  * proactively dials. Backbone (always-on) members are always dialed and do NOT
@@ -79,3 +106,33 @@ export interface ControlCohortReconcileResult {
  * @param targetDegree - cap on non-backbone dials (negative is treated as 0).
  */
 export declare function selectControlCohortDials(siblings: CohortPeerRow[], targetDegree: number): ControlCohortSelection;
+/** What {@link nextReconcileWakeMs} decides from, all times epoch milliseconds. */
+export interface ReconcileWakeInput {
+    /**
+     * Consecutive passes, this one included, whose dial of a selected sibling or a cold-start
+     * bootstrap peer failed; 0 when none of this pass's dials did.
+     */
+    redialStreak: number;
+    /** When the pass that just ended began. */
+    passStartedAt: number;
+    /** Every (sibling, strand) strand-address due time this node holds. */
+    strandAddrDueAt: Iterable<number>;
+    now: number;
+    /** The scheduler's backstop (ms); no wake is later than it. */
+    backstopMs: number;
+}
+/**
+ * How long after a pass the next one should run for the pass's own reasons, or `undefined`
+ * when the backstop covers everything:
+ *
+ * - **Redial.** A streak of unconnected passes wakes after
+ *   `min(CONTROL_COHORT_REDIAL_MS × 2^(streak − 1), backstop)`.
+ * - **Strand addresses.** The earliest strand-address due time LATER THAN the pass's start,
+ *   when it is sooner than the backstop, wakes when it falls due (now at the latest). A due
+ *   time at or before the start belongs to a (sibling, strand) the pass skipped for another
+ *   reason — the strand stopped, the sibling disconnected — and waking for it would spin; the
+ *   strand watcher's launch retry keeps the same rule.
+ *
+ * The smaller wins.
+ */
+export declare function nextReconcileWakeMs(input: ReconcileWakeInput): number | undefined;

package/dist/control-cohort.js

@@ -21,17 +21,44 @@
  * party it bounds out-degree to `backbone + targetDegree`.
  */
 /**
- * Default recurring cadence for {@link CadreNode.reconcileControlCohort} (ms).
- * In the same spirit as the 5s strand-watch poll but lighter, since a control
- * cohort changes far less often than strand activity.
+ * Default backstop for {@link CadreNode.reconcileControlCohort} (ms): a pass runs this long
+ * after the last one settled whether or not anything woke it. Passes normally run on a
+ * change — a membership table changing, a sibling connecting or disconnecting, an address
+ * change — and on the retries a pass arms for itself ({@link nextReconcileWakeMs}); the
+ * backstop bounds how stale this node can be after a change it hears nothing of: one that
+ * reaches it with no storage event, which happens to a machine outside the block's cohort
+ * (a cadre larger than `CONTROL_REPLICATION_BREADTH`) and to one in the cohort that the
+ * writer could not reach when it committed. The membership rows view's maximum age
+ * (`MEMBERSHIP_VIEW_MAX_AGE_MS`, 15 s) is shorter than this, so the backstop pass reads
+ * storage and starts the cohort consult that brings such a change in.
  *
- * An interval between pass starts, not a deadline on a pass. Passes are
- * single-flight, so a pass that runs longer than this is joined rather than
- * stacked, and the effective cadence becomes the pass length: one unreachable
- * sibling's dial alone can take the whole per-peer dial budget (86 s at the
- * default declared link).
+ * `network.controlCohort.reconcileMs` overrides it. An interval between a pass settling and
+ * the next start, not a deadline on a pass: passes are single-flight, and one unreachable
+ * sibling's dial alone can take the whole per-peer dial budget (86 s at the default
+ * declared link).
+ *
+ * NOTE: a machine whose storage takes no event for a change — one outside the block's cohort
+ * in a cadre larger than `CONTROL_REPLICATION_BREADTH` (16 machines), or one the writer could
+ * not reach when it committed — sees it only at this backstop, where the change-driven path
+ * serves a machine the commit reached within the 50 ms coalescing window. If a party ever
+ * needs a tighter bound, lower the backstop for its nodes or give the plugin's change bridge
+ * a path for outside-the-cohort reads.
+ */
+export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 120000;
+/**
+ * First redial delay after a pass's dial of a selected sibling, or a cold-start bootstrap peer,
+ * fails (ms). Doubles per consecutive such pass and is capped at the backstop, so a
+ * sibling that is offline costs one dial per backstop once the ladder saturates, and a
+ * stranded cold-start node keeps trying forever (15 s, 30 s, 60 s, then every backstop).
  */
-export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15000;
+export const CONTROL_COHORT_REDIAL_MS = 15000;
+/**
+ * How often an owner retries a node it has just claimed while that node restarts into the
+ * owner's party (ms; `CadreNode.claimNode`). A poll step, not a deadline: the retries run for
+ * {@link CONTROL_COHORT_REDIAL_MS} after the node accepts the claim, the delay of the reconcile
+ * pass's first redial, which would otherwise be the owner's next dial of the node.
+ */
+export const CLAIM_RESTART_REDIAL_STEP_MS = 1000;
 /**
  * Default cap on the number of **non-backbone** members a single reconcile pass
  * proactively dials. Backbone (always-on) members are always dialed and do NOT
@@ -83,4 +110,35 @@ export function selectControlCohortDials(siblings, targetDegree) {
         cappedNonBackbone: rest.length - fill.length,
     };
 }
+/**
+ * How long after a pass the next one should run for the pass's own reasons, or `undefined`
+ * when the backstop covers everything:
+ *
+ * - **Redial.** A streak of unconnected passes wakes after
+ *   `min(CONTROL_COHORT_REDIAL_MS × 2^(streak − 1), backstop)`.
+ * - **Strand addresses.** The earliest strand-address due time LATER THAN the pass's start,
+ *   when it is sooner than the backstop, wakes when it falls due (now at the latest). A due
+ *   time at or before the start belongs to a (sibling, strand) the pass skipped for another
+ *   reason — the strand stopped, the sibling disconnected — and waking for it would spin; the
+ *   strand watcher's launch retry keeps the same rule.
+ *
+ * The smaller wins.
+ */
+export function nextReconcileWakeMs(input) {
+    const { redialStreak, passStartedAt, strandAddrDueAt, now, backstopMs } = input;
+    let wake;
+    if (redialStreak > 0) {
+        wake = Math.min(CONTROL_COHORT_REDIAL_MS * 2 ** (redialStreak - 1), backstopMs);
+    }
+    for (const dueAt of strandAddrDueAt) {
+        if (dueAt <= passStartedAt) {
+            continue;
+        }
+        const delay = Math.max(0, dueAt - now);
+        if (delay < backstopMs && (wake === undefined || delay < wake)) {
+            wake = delay;
+        }
+    }
+    return wake;
+}
 //# sourceMappingURL=control-cohort.js.map

package/dist/control-cohort.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-cohort.js","sourceRoot":"","sources":["../src/control-cohort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,KAAM,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC;AAkCtD,mFAAmF;AACnF,SAAS,QAAQ,CAAC,CAAgB,EAAE,CAAgB;IAClD,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAyB,EACzB,YAAoB;IAEpB,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,MAAM,IAAI,GAAoB,EAAE,CAAC;IAEjC,mFAAmF;IACnF,wFAAwF;IACxF,uDAAuD;IACvD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAEhC,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;QAC7B,iBAAiB,EAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;KAC7C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"control-cohort.js","sourceRoot":"","sources":["../src/control-cohort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,MAAO,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAM,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAK,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC;AAkCtD,mFAAmF;AACnF,SAAS,QAAQ,CAAC,CAAgB,EAAE,CAAgB;IAClD,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAyB,EACzB,YAAoB;IAEpB,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,MAAM,IAAI,GAAoB,EAAE,CAAC;IAEjC,mFAAmF;IACnF,wFAAwF;IACxF,uDAAuD;IACvD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAEhC,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;QAC7B,iBAAiB,EAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;KAC7C,CAAC;AACJ,CAAC;AAkBD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAyB;IAC3D,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IAChF,IAAI,IAAwB,CAAC;IAC7B,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACrB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,wBAAwB,GAAG,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAClF,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,KAAK,IAAI,aAAa,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,GAAG,CAAC,CAAC;QACvC,IAAI,KAAK,GAAG,UAAU,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC;YAC/D,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}