@serfab/cadre-core 1.17.0 → 1.18.0

package/src/strand-membership-reconciler.ts

@@ -21,8 +21,7 @@
  * - **Retries fast while the join is unfinished, slowly while it is only waiting.** A pass
  *   that leaves the join unfinished re-arms on a ladder starting at
  *   {@link INITIAL_JOIN_RETRY_INTERVAL_MS} and doubling, capped at the configured poll
- *   interval (default {@link DEFAULT_REVOCATION_POLL_INTERVAL_MS}; an embedder's
- *   `revocationEnforcement.pollIntervalMs` is mirrored here by the instance manager). A pass
+ *   interval (default {@link DEFAULT_MEMBERSHIP_RECONCILE_INTERVAL_MS}). A pass
  *   that finds no member row AND no staged invitation is not an unfinished join but a wait
  *   for someone to admit this party — nothing this machine can do faster — so it re-arms on
  *   the flat poll interval and resets the ladder. The loop stops on the done state.
@@ -152,11 +151,17 @@ import {
   registerMemberPeer,
   type StrandWriteOptions,
 } from './strand-membership-writer.js';
-import { DEFAULT_REVOCATION_POLL_INTERVAL_MS } from './strand-revocation-enforcer.js';
 import { defaultTimeoutScheduler, type TimeoutScheduler } from './timeout-scheduler.js';
 
 const log = debug('sereus:cadre:strand-membership-reconciler');
 
+/**
+ * Default poll interval, ms: the loop's idle cadence while nobody has admitted this party, and
+ * the cap of its unfinished-join retry ladder. The loop stops once joined, so this matters only
+ * while a machine is joining.
+ */
+export const DEFAULT_MEMBERSHIP_RECONCILE_INTERVAL_MS = 30_000;
+
 /**
  * Idle passes (no member row, no staged invitation) before ONE `console.warn`
  * escalation — at the default 30 s cadence, about five minutes of waiting. The loop
@@ -182,9 +187,8 @@ export const UNFINISHED_PASSES_BEFORE_ESCALATION = 10;
  * unwritable, a database not yet published. Doubles per such pass up to the configured
  * poll interval. Sized for what it retries: invite-row replication resolves in about a
  * second over a direct connection and a few over a relay. The poll interval is NOT sized
- * for that — it is the revocation enforcer's deny-set refresh cadence, mirrored here for
- * the idle case (waiting to be admitted at all), which is why this ladder exists instead
- * of a shorter interval.
+ * for that — it is sized for the idle case (waiting to be admitted at all), which is why
+ * this ladder exists instead of a shorter interval.
  */
 export const INITIAL_JOIN_RETRY_INTERVAL_MS = 1_000;
 
@@ -366,19 +370,18 @@ export interface StrandMembershipReconciliationConfig {
   enabled?: boolean;
   /**
    * Idle cadence, ms — how often the loop re-checks while nobody has admitted this party
-   * yet — and the CAP of the unfinished-join retry ladder. When omitted the instance
-   * manager mirrors the revocation enforcer's configured cadence; default
-   * {@link DEFAULT_REVOCATION_POLL_INTERVAL_MS}.
+   * yet — and the CAP of the unfinished-join retry ladder. Default
+   * {@link DEFAULT_MEMBERSHIP_RECONCILE_INTERVAL_MS}.
    */
   pollIntervalMs?: number;
 }
 
 /**
- * The per-strand membership reconciliation loop. Lifecycle mirrors
- * `StrandRevocationEnforcer`: created in `StrandInstanceManager.buildStrandRuntime`
- * (closed strands with a party key only), started right after the strand database
- * initializes, stopped and dropped in `releaseRuntime` — so quiesce → resume rebuilds
- * it and re-runs the (idempotent) ladder from scratch.
+ * The per-strand membership reconciliation loop. Created in
+ * `StrandInstanceManager.buildStrandRuntime` (closed strands with a party key only),
+ * started right after the strand database initializes, stopped and dropped in
+ * `releaseRuntime` — so quiesce → resume rebuilds it and re-runs the (idempotent) ladder
+ * from scratch.
  */
 export class StrandMembershipReconciler {
   private readonly scheduler: TimeoutScheduler;
@@ -423,7 +426,7 @@ export class StrandMembershipReconciler {
     config?: StrandMembershipReconciliationConfig
   ) {
     this.scheduler = deps.scheduler ?? defaultTimeoutScheduler;
-    this.pollIntervalMs = config?.pollIntervalMs ?? DEFAULT_REVOCATION_POLL_INTERVAL_MS;
+    this.pollIntervalMs = config?.pollIntervalMs ?? DEFAULT_MEMBERSHIP_RECONCILE_INTERVAL_MS;
   }
 
   /**
@@ -573,16 +576,21 @@ export class StrandMembershipReconciler {
   private async attempt(db: Database, keyPair: Ed25519KeyPair): Promise<void> {
     try {
       if (!(await this.ensureMembership(db, keyPair))) return;
-      // NOTE: the redemption (`Member` + `ConsumedInvite`) and the binding below are two
-      // SEPARATE commits — measured at 27 and 18 `/cluster` streams on 2026-09-17.
-      // One write batch could carry both (`MemberPeer.MemberExists`
-      // reads the LIVE `Member` table, and `MemberPeer.Authorized`'s add branch only verifies a
-      // self-signature over the new row), worth perhaps a third of that plus one commit
-      // round-trip. Left as two deliberately: the saving is unmeasured, and merging them merges
-      // their failure modes — today a redemption that lands but reports torn simply heals on the
-      // next pass, which sees the member row and proceeds to the binding. If a joiner's write
-      // cost ever shows up in a measurement, try the single transaction and measure against the
-      // 27 + 18 baseline.
+      // NOTE: accepted tradeoff — the redemption (`Member` + `ConsumedInvite`) and the binding
+      // below stay two SEPARATE commits on purpose. One transaction would save no `/cluster`
+      // requests: Optimystic pends and commits each collection on its own, about 4 requests per
+      // collection (`blocked/optimystic-multi-collection-commit-costs-four-requests-per-collection`),
+      // and both commits already span several collections (each table plus its UNIQUE trees),
+      // so merging saves only one commit's serial latency. It would also let a torn commit
+      // (Optimystic can report a multi-collection commit partly saved) or the cohort applying
+      // the collections out of order show this machine's `MemberPeer` without its `Member`,
+      // which the revocation enforcer reads as a removed member and hangs up on — fail closed,
+      // undone only by a manager clearing the binding (module doc of
+      // `strand-revocation-enforcer.ts`). And it would add a half-committed shape (`MemberPeer`
+      // saved, the invitation still live) that {@link reportHalfCommittedJoin}'s dropping of the
+      // invitation gets wrong. Revisit when Optimystic offers an all-or-nothing multi-collection
+      // commit, or when its per-coordinator batching lands and the enforcer can tell a
+      // not-yet-seated binding from a removed member's.
       await this.ensureBinding(db, keyPair);
     } finally {
       this.noteAttemptOutcome();