@serfab/cadre-core 1.16.0 → 1.18.0

package/dist/strand-revocation-enforcer.d.ts

@@ -9,13 +9,21 @@
  * every `Strand.MemberPeer.PeerId` whose `MemberKey` has no live `Strand.Member`
  * row. `MemberPeer.MemberExists` runs on insert, so an orphaned binding can only
  * mean "this member existed and was removed" — it is exactly the durable,
- * replicated record of a removed party's machines. Everything NOT in the set is
- * admitted. Deliberate consequences:
+ * replicated record of a removed party's machines. That holds on the network
+ * only because every writer commits a party's `Member` row before its
+ * `MemberPeer` row, as separate commits (the membership reconciler does, and
+ * `registerMemberPeer` requires an existing member): Optimystic can save a
+ * multi-collection transaction's tables separately, and remaining members can
+ * apply them in either order. The one exception is the founder's bootstrap,
+ * which writes its own `Member` and `MemberPeer` in one transaction; that is
+ * acceptable because it commits before any other party has joined, so no other
+ * party's enforcer is reading yet. Everything NOT in the set is admitted.
+ * Deliberate consequences:
  *
  * - **Open strands are untouched.** `Member`/`MemberPeer` carry `OnlyClosed`
  *   checks, so an open strand has no rows and the set is empty — and
  *   `StrandInstanceManager` additionally skips arming this enforcer entirely for
- *   `Type !== 'c'`, so an open strand does not even poll.
+ *   `Type !== 'c'`, so an open strand neither subscribes nor reads.
  * - **A joining party mid-admission is admitted** (it has no orphaned binding).
  *   An allowlist ("only peers bound to live members") was considered and
  *   rejected: a joiner's first membership writes must travel through the very
@@ -44,22 +52,19 @@
  * Refusing NEW connections only half-honors "no longer be answered to or
  * communicated with": a long-lived strand connection may never re-dial, so
  * without teardown a removed party keeps whatever session it already holds.
- * There is no push notification to hang teardown off — a REPLICATED revocation
- * arrives with no change event (the strand database has no reactive
- * subscription; `StrandWatcher` polls for the same reason), and a LOCAL
- * `revokeMember`/`leaveStrand` writes through a bare `Database` handle this
- * runtime never sees — so teardown rides the snapshot refresh itself, with
- * `refresh()` exposed for immediacy
+ * Teardown rides the snapshot refresh itself, which runs when the membership
+ * tables change (see "When the deny set is refreshed"). `refresh()` is public
+ * for a caller that wants to await the cut
  * (`StrandInstanceManager.refreshRevocationEnforcement` →
- * `CadreNode.refreshRevocationEnforcement`).
+ * `CadreNode.refreshRevocationEnforcement`): it resolves only after the sweep.
  *
  * The sweep is driven by MEMBERSHIP in the deny set, never by an
  * entered-the-set diff: every refresh hangs up every currently-connected
  * revoked peer, so a resume, a crashed refresh, or a connection established
  * between two refreshes cannot leave a session standing (a diff would be a
  * strict subset of this, so none is kept). A peer with no open connection is
- * simply not swept, and a failed `hangUp` is logged, never thrown — the next
- * refresh retries it. `hangUp` closes DIRECT and RELAYED connections alike, and
+ * simply not swept, and a failed `hangUp` is logged, never thrown, and retried
+ * by a refresh {@link REVOCATION_REFRESH_RETRY_MS} later. `hangUp` closes DIRECT and RELAYED connections alike, and
  * on a strand node running the relay server it also drops any reservation the
  * revoked peer holds there (a reservation dies with its connection — see the
  * relay-seam doc in `membership-connection-gater.ts`).
@@ -81,6 +86,25 @@
  * Best-effort by nature: a removed party learns only if the tombstone
  * replicated to it before the cut.
  *
+ * ## When the deny set is refreshed
+ *
+ * Every refresh runs on one table change subscription (`table-change-watch.ts`),
+ * single-flight, so no two scheduled refreshes overlap:
+ *
+ * - **On a change** to `Strand.Member` or `Strand.MemberPeer`. App writes
+ *   (`revokeMember`, `leaveStrand`) commit on the same Quereus `Database` the
+ *   subscription is on, so a local removal is acted on within the coalescing
+ *   window; a replicated one when this node's storage takes it in.
+ * - **Once at start**, when the strand's database is published.
+ * - **On a backstop** ({@link DEFAULT_REVOCATION_BACKSTOP_MS} after the last
+ *   refresh settled), for a change that raised no event.
+ * - **After a failed refresh**, {@link REVOCATION_REFRESH_RETRY_MS} later. The
+ *   first successful read also arms the plugin's bridge for replicated changes
+ *   (the NOTE on `watchTables`), so until one succeeds only local commits wake it.
+ * - **After each successful refresh on a wide strand** — more distinct bound peer ids than
+ *   the cluster size — {@link REVOCATION_WIDE_STRAND_REFRESH_MS} later, because
+ *   this node may be outside a membership block's cohort and so hear no change.
+ *
  * ## What transfers from the control gater (`membership-connection-gater.ts`)
  *
  * Transfers: the two-layer shape (fail-closed per-stream gate as PRIMARY, a
@@ -116,14 +140,33 @@
  */
 import type { ConnectionGater, PeerId } from '@libp2p/interface';
 import type { Database } from '@quereus/quereus';
+import { type TableChangeWatch, type TableChangeWatchOptions } from './table-change-watch.js';
+import type { TimeoutScheduler } from './timeout-scheduler.js';
+/**
+ * Default longest wait between two deny-set refreshes when no membership change
+ * is heard. Overridable via {@link StrandRevocationEnforcementConfig.backstopMs}.
+ *
+ * NOTE: the backstop covers two paths the change subscription does not: a
+ * machine that was offline when the removal was committed (it normally takes
+ * the blocks in by join backfill or read repair on reconnect, which raise the
+ * change too), and any change that reaches storage without an event. The case
+ * of a node outside a membership block's cohort is covered by
+ * {@link REVOCATION_WIDE_STRAND_REFRESH_MS}, not by this.
+ */
+export declare const DEFAULT_REVOCATION_BACKSTOP_MS: number;
 /**
- * Default cadence of the deny-set refresh. Bounded staleness is the accepted
- * failure direction (see the module doc's stale-view paragraph); 30 s keeps a
- * revoked peer's post-replication admit window in the same order as the
- * replication delay itself. Overridable via
- * {@link StrandRevocationEnforcementConfig.pollIntervalMs}.
+ * How soon a failed refresh is retried. Also how soon a replicated removal is
+ * heard after a first read that failed, since that read is what arms the
+ * plugin's replicated-change bridge for the two tables.
  */
-export declare const DEFAULT_REVOCATION_POLL_INTERVAL_MS = 30000;
+export declare const REVOCATION_REFRESH_RETRY_MS = 30000;
+/**
+ * How soon a strand with more distinct bound peer ids than its cluster size is
+ * refreshed again after a successful refresh. On such a strand this node may be
+ * outside a membership block's cohort, so it takes in no storage event for a
+ * removal (`docs/architecture.md` → "Table change subscriptions").
+ */
+export declare const REVOCATION_WIDE_STRAND_REFRESH_MS = 30000;
 /**
  * Embedder tuning for the strand revoked-peer gate, threaded from
  * `CadreNodeConfig.strandRevocationEnforcement` to
@@ -135,8 +178,17 @@ export interface StrandRevocationEnforcementConfig {
      * the pre-existing behaviour (a removed party's peers keep being served).
      */
     enabled?: boolean;
-    /** Deny-set refresh cadence, ms. Default {@link DEFAULT_REVOCATION_POLL_INTERVAL_MS}. */
-    pollIntervalMs?: number;
+    /** Longest wait between two refreshes with no change heard, ms. Default {@link DEFAULT_REVOCATION_BACKSTOP_MS}. */
+    backstopMs?: number;
+    /**
+     * Default true: the enforcer schedules its own refreshes — on a change to
+     * `Strand.Member` or `Strand.MemberPeer`, after a failed read or hang-up, and
+     * on a wide strand's follow-up. False schedules none of those, so refreshes
+     * run only at start, on the backstop, and on `refreshRevocationEnforcement`.
+     * For test scenarios that need a machine's cuts to be the ones the test drove;
+     * a production node leaves it on.
+     */
+    autoRefresh?: boolean;
 }
 /** One `Strand.MemberPeer` row, as the deny-set derivation consumes it. */
 export interface StrandMemberPeerBinding {
@@ -150,16 +202,6 @@ export interface StrandRevocationRows {
     /** Every `Strand.MemberPeer` row (live-membered and orphaned alike). */
     bindings: readonly StrandMemberPeerBinding[];
 }
-/**
- * Timer seam so the refresh cadence is testable without fake timers — the
- * injectable-clock idiom of `UnauthorizedReservationBudget`'s `now` argument,
- * shaped for an interval-driven component. The default schedules a real
- * interval and unrefs it so an armed enforcer never holds a process open.
- */
-export interface RevocationRefreshScheduler {
-    setInterval(fn: () => void, ms: number): unknown;
-    clearInterval(handle: unknown): void;
-}
 /**
  * The minimum of a libp2p node the teardown sweep needs: who WE are, what is
  * open, and how to close it. Deliberately not the node itself, so the sweep
@@ -206,8 +248,19 @@ export interface StrandRevocationEnforcerDeps {
      * logged and swallowed — an embedder's handler must not derail the sweep.
      */
     onSelfRevoked?: () => void;
-    /** Timer seam; omit for real (unref'd) intervals. */
-    scheduler?: RevocationRefreshScheduler;
+    /**
+     * Subscribe `onChange` to changes in `Strand.Member` and `Strand.MemberPeer`
+     * (`StrandDatabase.watchTables`). Absent, or throwing: refreshes come from
+     * start, the backstop, retries and wide-strand follow-ups only (unit tests).
+     */
+    watchChanges?(onChange: () => Promise<void>, options: TableChangeWatchOptions): TableChangeWatch;
+    /**
+     * The strand's cluster size. A snapshot with more distinct bound peer ids than
+     * this schedules {@link REVOCATION_WIDE_STRAND_REFRESH_MS}; absent, never.
+     */
+    cohortBreadth?: number;
+    /** Timer seam for the watch; omit for real (unref'd) timeouts. */
+    scheduler?: TimeoutScheduler;
 }
 /**
  * Read the deny-set inputs from a strand database: full-scan
@@ -221,17 +274,17 @@ export interface StrandRevocationEnforcerDeps {
  * separate reads with nothing holding them to one snapshot, so a write that
  * lands between them is seen by the second scan and not the first. A member
  * joins as `Member` row then `MemberPeer` row (`MemberExists` forces that
- * order), so reading `Member` first would let a join that commits mid-read
- * produce a binding whose member key is absent from the key set — a brand-new
- * member classified as REVOKED, the one fail-CLOSED outcome this module exists
- * to avoid. Reading bindings first inverts the skew: the new binding is simply
- * not in the older bindings snapshot, so the joiner is unclassified and
- * admitted, and a revocation that lands mid-read is still seen (the key is
- * missing from the NEWER key scan). Every skew window then resolves fail-open,
- * matching the module doc.
+ * order; the module doc says why it holds on the network), so reading `Member`
+ * first would let a join that commits mid-read produce a binding whose member
+ * key is absent from the key set — a brand-new member classified as REVOKED,
+ * the one fail-CLOSED outcome this module exists to avoid. Reading bindings
+ * first inverts the skew: the new binding is simply not in the older bindings
+ * snapshot, so the joiner is unclassified and admitted, and a revocation that
+ * lands mid-read is still seen (the key is missing from the NEWER key scan).
+ * Every skew window then resolves fail-open, matching the module doc.
  *
- * NOTE: two whole-table scans per refresh (default every 30 s per closed
- * strand). Fine at strand scale (a handful of members and bindings); if
+ * NOTE: two whole-table scans per refresh (on each membership change and each
+ * backstop, per closed strand). Fine at strand scale (a handful of members and bindings); if
  * membership churn ever makes these tables large, the fix is a reliable
  * filtered read — which needs the networked point-lookup gap closed
  * (`debt-composite-pk-point-lookup-unreliable-untracked`) — not a bigger scan.
@@ -240,25 +293,24 @@ export declare function readStrandRevocationRows(db: Database): Promise<StrandRe
 /**
  * The per-strand revoked-peer deny set and the synchronous predicates over it.
  *
- * Lifecycle mirrors `PeerJoinBackfill`: created in
- * `StrandInstanceManager.buildStrandRuntime` (closed strands only), started
- * after the strand database initializes, stopped and dropped in
- * `releaseRuntime` — so quiesce → resume rebuilds it with a fresh snapshot.
- * The snapshot starts EMPTY (admit everything) and repopulates on the first
- * successful read; a revoked peer therefore gets a short admit window per
- * resume at the connection level. Accepted: fail-open posture, and resume is
- * never blocked on a refresh.
+ * Lifecycle: created in `StrandInstanceManager.buildStrandRuntime` (closed
+ * strands only), started when `publishDatabase` hands the strand's database to
+ * the app, stopped and dropped in `releaseRuntime` — so quiesce → resume
+ * rebuilds it with a fresh snapshot. The snapshot starts EMPTY (admit
+ * everything) and repopulates on the first successful read; a revoked peer
+ * therefore gets a short admit window per resume at the connection level.
+ * Accepted: fail-open posture, and resume is never blocked on a refresh.
  */
 export declare class StrandRevocationEnforcer {
     private readonly deps;
     /** The materialized deny set — peer ids with an orphaned binding and no live one. */
     private revokedPeerIds;
-    private readonly scheduler;
-    private readonly pollIntervalMs;
+    private readonly backstopMs;
+    private readonly autoRefresh;
     /** Tail of the refresh chain — what serializes refreshes (no two reads in flight). */
     private refreshTail;
-    private refreshing;
-    private intervalHandle;
+    /** Every scheduled refresh runs on it; present between {@link start} and {@link stop}. */
+    private watch;
     private started;
     private stopped;
     /** Latch for the one-shot self-revocation signal — see {@link StrandRevocationEnforcerDeps.onSelfRevoked}. */
@@ -266,9 +318,14 @@ export declare class StrandRevocationEnforcer {
     constructor(deps: StrandRevocationEnforcerDeps, config?: StrandRevocationEnforcementConfig);
     /** Number of peers currently denied — test/diagnostic surface. */
     get revokedCount(): number;
-    /** Kick an immediate refresh (not awaited — bring-up never blocks on it) and arm the poll. */
+    /**
+     * Subscribe to membership changes and run one refresh at once (not awaited —
+     * bring-up never blocks on it); the module doc's "When the deny set is
+     * refreshed" has the full schedule. Call once the strand's database is
+     * published. A second call, or one after {@link stop}, is a no-op.
+     */
     start(): void;
-    /** Disarm the poll; a read already in flight completes but its result is discarded. */
+    /** Stop scheduling refreshes; a read already in flight completes but its result is discarded. */
     stop(): void;
     /**
      * Refresh the deny set now. Never rejects. Serialized: concurrent calls chain,
@@ -291,22 +348,39 @@ export declare class StrandRevocationEnforcer {
      * over a connection admitted before the revocation replicated here.
      */
     authorizeStream(remotePeerId: string, _protocol: string): boolean;
+    /**
+     * The watch every scheduled refresh runs on: the deps' change subscription, or
+     * a timer-only one when changes are not watched or the subscription throws.
+     *
+     * NOTE: a refresh can wake itself once. Its read may start a read-repair sync
+     * (a held block read more than Optimystic's `readRepairWindowMs`, 10 s, after
+     * its last check), and that sync's landing raises a change. The follow-up
+     * refresh runs within the coalescing window plus one read — well inside the
+     * read-repair window — so it starts no second sync and the chain stops there.
+     * If idle sync counts on a strand do not fall with this subscription, suspect
+     * this loop first.
+     */
+    private subscribe;
     /**
      * One serialized snapshot rebuild; contains every failure (contract: never rejects).
      *
      * NOTE: nothing here carries a deadline — a `readRows` or a `hangUp` that never
-     * settles wedges the refresh chain, which freezes the deny set (the poll skips
-     * while `refreshing`, and every later `refresh()` chains behind the stuck one).
+     * settles wedges the refresh chain, which freezes the deny set (the watch runs
+     * one refresh at a time, and every later `refresh()` chains behind the stuck one).
      * Both are bounded in practice (Quereus reads settle; libp2p's connection close
      * has its own timeout). If a strand is ever seen with a stale deny set and no
      * refresh log line, wrap both awaits in a timeout rather than hunting further.
      */
     private doRefresh;
+    /** Arm one more refresh `delayMs` from now, unless {@link StrandRevocationEnforcementConfig.autoRefresh} is off or the enforcer is not running. */
+    private scheduleFollowUp;
+    /** Schedule {@link REVOCATION_WIDE_STRAND_REFRESH_MS} when `rows` bind more distinct peers than the cluster holds. */
+    private followUpWideStrand;
     /**
      * Close what is already OPEN to the peers of `revoked` — the teardown half of
      * enforcement (module doc: "Removal cuts LIVE sessions too"). Never rejects:
-     * every failure is contained, so the refresh loop survives and simply retries
-     * on the next tick.
+     * every failure is contained, so the refresh chain survives, and a failed
+     * `hangUp` schedules a retry.
      *
      * `revoked` is passed IN rather than read off the field, so the sweep judges
      * the exact snapshot its own refresh produced; likewise the connection list is