@serfab/cadre-core 1.17.0 → 1.19.0

package/src/table-change-watch.ts

@@ -0,0 +1,285 @@
+/**
+ * One way for cadre-core to be told that a control or strand table changed, so an idle loop
+ * can wait for a change instead of re-reading on a timer. Built on Quereus's
+ * `Database.watch`, which hears both a commit made on this `Database` and, through the
+ * Optimystic plugin's `notifyExternalChange` bridge, every change this node's storage takes
+ * in from elsewhere: a consensus commit it took part in as a cohort member, a block-transfer
+ * push such as join backfill, and a read-repair landing. Events are table-wide; there are no
+ * row keys.
+ *
+ * The consumer's `onChange` never runs inside a commit. The watch handler only sets flags
+ * and arms a timer, and runs are single-flight: changes inside the coalescing window share
+ * one run, a change during a run produces exactly one follow-up run, and a consumer's own
+ * `trigger` (start, retry backoff) and the backstop go through the same rule.
+ * `docs/architecture.md` → "Table change subscriptions" says what the seam does not hear,
+ * which is why consumers keep a backstop.
+ */
+import debug from 'debug';
+import type { ChangeScope, Database, Subscription, TableWatch, WatchEvent } from '@quereus/quereus';
+import { defaultTimeoutScheduler } from './timeout-scheduler.js';
+import type { TimeoutScheduler } from './timeout-scheduler.js';
+
+const log = debug('sereus:cadre:table-watch');
+
+/**
+ * Default coalescing window. One local commit fires the watch twice (Quereus's own
+ * post-commit dispatch, then the plugin's storage event); this folds both into one run.
+ */
+export const TABLE_CHANGE_COALESCE_MS = 50;
+
+export interface TableChangeWatchOptions {
+  /** Short label for log lines (e.g. 'strand-watcher'). */
+  label: string;
+  /** Coalescing window after the first change; default {@link TABLE_CHANGE_COALESCE_MS}. */
+  coalesceMs?: number;
+  /**
+   * Run anyway this long after the last run settled, change or not. Omit for none.
+   * The path for a change that arrives without a storage event (see the module doc).
+   */
+  backstopMs?: number;
+  /**
+   * Called inline, synchronously, from the watch handler — inside the committing call,
+   * possibly with the control write lock held — once per changed table per event, with the
+   * name as the consumer passed it. Only for setting a flag (cache invalidation). Must not
+   * read, write or await.
+   */
+  onInvalidate?: (qualifiedTable: string) => void;
+  /** Timer seam; default real, unref'd timers. */
+  scheduler?: TimeoutScheduler;
+}
+
+export interface TableChangeWatch {
+  /** Schedule a run after `delayMs` (default 0) through the same single-flight rule; an earlier pending run wins. */
+  trigger(delayMs?: number): void;
+  /** Stop: unsubscribe, clear timers; no run starts afterwards. Idempotent. Does not wait for a run in flight. */
+  dispose(): void;
+}
+
+/**
+ * Subscribe `onChange` to changes in `tables` (qualified `'Schema.Table'` names, e.g.
+ * `'CadreControl.Strand'`). Throws synchronously on a name that is not qualified, or a table
+ * that does not exist.
+ *
+ * NOTE: the plugin arms its storage bridge for a table on that table's first full
+ * initialization on this `Database`, so a table not yet touched hears local commits only,
+ * not replicated ones. Consumers' start runs touch their tables; the seam does not, because
+ * touching a never-written collection consults the network.
+ *
+ * NOTE: Quereus silently disposes a subscription whose table is dropped or altered. Control
+ * and strand schemas are fixed for a database's life (an app-schema attach adds `App` tables
+ * and alters no `Strand` one), so nothing re-subscribes; revisit if that stops holding.
+ */
+export function watchTables(
+  db: Database,
+  tables: readonly string[],
+  onChange: () => Promise<void>,
+  options: TableChangeWatchOptions,
+): TableChangeWatch {
+  return new TableChangeWatcher({ db, tables }, onChange, options);
+}
+
+/**
+ * {@link watchTables}' schedule — single-flight runs, `trigger`, the backstop — with no table
+ * subscription, for a consumer with no database to watch (tests, fakes).
+ */
+export function scheduleRuns(onChange: () => Promise<void>, options: TableChangeWatchOptions): TableChangeWatch {
+  return new TableChangeWatcher(undefined, onChange, options);
+}
+
+/**
+ * The subscriptions one database owner has handed out, so its `close()` can dispose those
+ * still live — synchronously, ahead of its own awaits, so nothing a closing commit does
+ * schedules a run. (`Database.close()` disposes them too, but only after its own awaits.)
+ */
+export class TableWatchRegistry {
+  private readonly live = new Set<TableChangeWatch>();
+
+  watch(
+    db: Database,
+    tables: readonly string[],
+    onChange: () => Promise<void>,
+    options: TableChangeWatchOptions,
+  ): TableChangeWatch {
+    const inner = watchTables(db, tables, onChange, options);
+    const tracked: TableChangeWatch = {
+      trigger: delayMs => inner.trigger(delayMs),
+      dispose: () => {
+        this.live.delete(tracked);
+        inner.dispose();
+      },
+    };
+    this.live.add(tracked);
+    return tracked;
+  }
+
+  disposeAll(): void {
+    for (const watch of [...this.live]) {
+      watch.dispose();
+    }
+  }
+}
+
+/** One armed timer; an object of its own so the scheduler's handles need not be unique. */
+interface Wake {
+  handle: unknown;
+}
+
+/** The tables a {@link TableChangeWatcher} subscribes to; absent for {@link scheduleRuns}. */
+interface WatchedTables {
+  db: Database;
+  tables: readonly string[];
+}
+
+class TableChangeWatcher implements TableChangeWatch {
+  private readonly subscription: Subscription | undefined;
+  /** The consumer's name for each watched table, by Quereus's lowercased `schema.table` key. */
+  private readonly names = new Map<string, string>();
+  private readonly scheduler: TimeoutScheduler;
+  private readonly coalesceMs: number;
+  /**
+   * Every armed timer: the coalescing window, `trigger` delays and the backstop. Whichever
+   * fires first starts the run, and starting a run clears the rest.
+   */
+  private readonly wakes = new Set<Wake>();
+  /** The coalescing window, while armed: a change joins it instead of extending it. */
+  private coalesceWake: Wake | undefined;
+  private running = false;
+  /** A timer fired while a run was in flight: one more run, a window after it settles. */
+  private rerun = false;
+  private disposed = false;
+  private warnedThenable = false;
+
+  constructor(
+    watched: WatchedTables | undefined,
+    private readonly onChange: () => Promise<void>,
+    private readonly options: TableChangeWatchOptions,
+  ) {
+    this.scheduler = options.scheduler ?? defaultTimeoutScheduler;
+    this.coalesceMs = options.coalesceMs ?? TABLE_CHANGE_COALESCE_MS;
+    this.subscription = watched && this.subscribe(watched);
+    this.armBackstop();
+  }
+
+  trigger(delayMs = 0): void {
+    if (!this.disposed) {
+      this.arm(delayMs);
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.subscription?.unsubscribe();
+    this.clearWakes();
+  }
+
+  private subscribe({ db, tables }: WatchedTables): Subscription {
+    const watches = tables.map(fullTableWatch);
+    watches.forEach((watch, i) => this.names.set(tableKey(watch), tables[i]));
+    const scope: ChangeScope = { watches, nonDeterministicSources: [], unboundParameters: [] };
+    // Returns undefined, so Quereus never awaits consumer work inside a commit.
+    return db.watch(scope, event => this.handleChange(event));
+  }
+
+  /** Runs inside the committing call, possibly under the control write lock: flags and a timer only. */
+  private handleChange(event: WatchEvent): void {
+    if (this.disposed) {
+      return;
+    }
+    this.coalesceWake ??= this.arm(this.coalesceMs);
+    for (const { watch } of event.matched) {
+      this.invalidate(this.names.get(tableKey(watch)) ?? tableKey(watch));
+    }
+  }
+
+  private invalidate(table: string): void {
+    let result: unknown;
+    try {
+      result = this.options.onInvalidate?.(table);
+    } catch (err) {
+      log('%s: onInvalidate threw for %s: %O', this.options.label, table, err);
+      return;
+    }
+    if (!this.warnedThenable && isThenable(result)) {
+      this.warnedThenable = true;
+      log('%s: misuse — onInvalidate returned a promise for %s; it is never awaited, and must only set a flag', this.options.label, table);
+    }
+  }
+
+  private arm(delayMs: number): Wake {
+    const wake: Wake = { handle: undefined };
+    wake.handle = this.scheduler.setTimeout(() => this.fire(wake), delayMs);
+    this.wakes.add(wake);
+    return wake;
+  }
+
+  private armBackstop(): void {
+    if (this.options.backstopMs !== undefined) {
+      this.arm(this.options.backstopMs);
+    }
+  }
+
+  private clearWakes(): void {
+    for (const wake of this.wakes) {
+      this.scheduler.clearTimeout(wake.handle);
+    }
+    this.wakes.clear();
+    this.coalesceWake = undefined;
+  }
+
+  private fire(wake: Wake): void {
+    if (!this.wakes.delete(wake)) {
+      return;
+    }
+    if (wake === this.coalesceWake) {
+      this.coalesceWake = undefined;
+    }
+    if (this.running) {
+      this.rerun = true;
+      return;
+    }
+    this.clearWakes();
+    this.rerun = false;
+    this.running = true;
+    void this.run();
+  }
+
+  private async run(): Promise<void> {
+    try {
+      await this.onChange();
+    } catch (err) {
+      log('%s: change run failed: %O', this.options.label, err);
+    }
+    this.running = false;
+    this.settled();
+  }
+
+  private settled(): void {
+    if (this.disposed) {
+      return;
+    }
+    if (this.rerun) {
+      this.coalesceWake ??= this.arm(this.coalesceMs);
+    }
+    this.armBackstop();
+  }
+}
+
+function fullTableWatch(qualifiedTable: string): TableWatch {
+  const [schema, table, ...rest] = qualifiedTable.split('.');
+  if (!schema || !table || rest.length > 0) {
+    throw new Error(`watchTables: '${qualifiedTable}' is not a qualified 'Schema.Table' name`);
+  }
+  return { table: { schema, table }, columns: 'all', scope: { kind: 'full' } };
+}
+
+/** Quereus's own matching key for a watched table. */
+function tableKey(watch: TableWatch): string {
+  return `${watch.table.schema}.${watch.table.table}`.toLowerCase();
+}
+
+function isThenable(value: unknown): boolean {
+  return typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function';
+}

package/src/timeout-scheduler.ts

@@ -1,28 +1,29 @@
-/**
- * The timer seam shared by the strand bring-up loops that re-arm themselves one step at a
- * time — the first-sync write gate's probe loop (`strand-first-sync-gate.ts`) and the
- * membership reconciler's retry ladder (`strand-membership-reconciler.ts`). `setTimeout`
- * rather than a repeating interval because the next step is armed only once the previous
- * one settles, so a slow network read never stacks steps behind it, and because the delay
- * can differ per step.
- *
- * Tests inject a hand-cranked clock; production omits it and gets real timers, `unref`'d so
- * a loop that is only waiting never holds a Node process open (the call is optional —
- * browsers and React Native return a plain handle with no `unref`).
- */
-
-/** Timer seam for a self-rescheduling loop; omit for real (unref'd) timeouts. */
-export interface TimeoutScheduler {
-  setTimeout(fn: () => void, ms: number): unknown;
-  clearTimeout(handle: unknown): void;
-}
-
-/** Real timers, `unref`'d where the runtime supports it. */
-export const defaultTimeoutScheduler: TimeoutScheduler = {
-  setTimeout: (fn, ms) => {
-    const handle = setTimeout(fn, ms);
-    (handle as { unref?: () => void }).unref?.();
-    return handle;
-  },
-  clearTimeout: (handle) => clearTimeout(handle as Parameters<typeof clearTimeout>[0])
-};
+/**
+ * The timer seam shared by the loops that re-arm themselves one step at a time — the
+ * membership reconciler's retry ladder (`strand-membership-reconciler.ts`) — and by the table
+ * change subscription's coalescing, trigger and backstop timers (`table-change-watch.ts`), on
+ * which the first-sync write gate's probes run (`strand-first-sync-gate.ts`). `setTimeout`
+ * rather than a repeating interval because the next step is armed only once the previous
+ * one settles, so a slow network read never stacks steps behind it, and because the delay
+ * can differ per step.
+ *
+ * Tests inject a hand-cranked clock; production omits it and gets real timers, `unref`'d so
+ * a loop that is only waiting never holds a Node process open (the call is optional —
+ * browsers and React Native return a plain handle with no `unref`).
+ */
+
+/** Timer seam for a self-rescheduling loop; omit for real (unref'd) timeouts. */
+export interface TimeoutScheduler {
+  setTimeout(fn: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+/** Real timers, `unref`'d where the runtime supports it. */
+export const defaultTimeoutScheduler: TimeoutScheduler = {
+  setTimeout: (fn, ms) => {
+    const handle = setTimeout(fn, ms);
+    (handle as { unref?: () => void }).unref?.();
+    return handle;
+  },
+  clearTimeout: (handle) => clearTimeout(handle as Parameters<typeof clearTimeout>[0])
+};

package/src/types.ts

@@ -1,7 +1,7 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
 import type { CircuitRelayServerInit } from '@libp2p/circuit-relay-v2';
 import type { IRawStorage, Libp2pConnectionMonitorInit, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
-import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
+import type { CollectionChangeListener, IPeerNetwork, IRepo } from '@optimystic/db-core';
 import type { PeerJoinBackfillConfig } from './peer-join-backfill.js';
 import type { StrandReactivityConfig } from './strand-reactivity.js';
 import type { StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.js';
@@ -18,6 +18,7 @@ import type { EnrolledMachineStore } from './enrolled-machine-store.js';
 import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
 import type { CadreInviteSignedFields, OwnerGrantSignedFields, RevocableTable } from './control-authorization.js';
+import type { FoundingInvite } from './control-database.js';
 import type { CadreInvitation } from './cadre-invite-protocol.js';
 import type { OwnerGrantBundle } from './owner-grant-protocol.js';
 import type { RedemptionAddressOutcome } from './member-redemption.js';
@@ -39,6 +40,21 @@ export interface Libp2pNodeWithRepo extends Libp2p {
    * backfill (`peer-join-backfill.ts`) logs once and stays inert when it is absent.
    */
   keyNetwork?: IPeerNetwork;
+  /**
+   * The node's block store, attached by the same factory (Optimystic's
+   * `OptimysticNodeAttachments.storageRepo`), narrowed to the storage-wide change feed: it
+   * fires for every block that lands in this node's store, a push or a commit. Optional for
+   * the same reason as `keyNetwork`; the first-sync gate (`strand-first-sync-gate.ts`) wakes
+   * on it, and logs once and probes on its backstop alone when it is absent.
+   */
+  storageRepo?: { onAnyCollectionChange(listener: CollectionChangeListener): () => void };
+  /**
+   * Tells the node a peer holds a block at a revision or later (Optimystic's
+   * `OptimysticNodeAttachments.reportBlockHeld`), so its under-replication drain and rebalance
+   * monitor do not push that peer the same block again. Optional for the same reason as
+   * `keyNetwork`; the join catch-up (`peer-join-backfill.ts`) reports each block a peer accepted.
+   */
+  reportBlockHeld?: (blockId: string, rev: number, peerId: string) => Promise<void>;
 }
 
 /**
@@ -578,8 +594,13 @@ export interface NetworkConfig {
      */
     targetDegree?: number;
     /**
-     * Recurring reconcile cadence in ms. Defaults to
-     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}.
+     * The reconcile pass's backstop in ms: a pass runs this long after the last one
+     * settled when nothing has started one sooner (a membership table change, a sibling
+     * connecting or disconnecting, an address change, a redial or strand-address wake).
+     * It also caps the redial ladder. Defaults to
+     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS} (2 minutes). The membership rows view's
+     * maximum age (`MEMBERSHIP_VIEW_MAX_AGE_MS`, 15 s) does not follow this field: a backstop
+     * longer than it reads storage on every backstop pass, a shorter one every 15 s at most.
      */
     reconcileMs?: number;
     /**
@@ -648,10 +669,10 @@ export interface NetworkConfig {
  * pinging node's monitor sees the reset and aborts the connection exactly as it would on its
  * own timeout. So this deadline is only real up to the handler timeout of the node being
  * pinged, which has to stay above it. The deployed relay sets its handler to 60 s for that
- * reason (`ops/docker/libp2p-infra/src/main.ts`). Every cadre node's handler is Optimystic's
- * bare `ping()`, `@libp2p/ping`'s 10 s, and nothing here can move it
- * (`tickets/blocked/optimystic-ping-handler-timeout-below-the-monitor-deadline.md`): between
- * two cadre nodes, a ping whose echo takes longer than 10 s still drops the connection.
+ * reason (`ops/docker/libp2p-infra/src/main.ts`). Every cadre node's handler is Optimystic's,
+ * which derives it from this object: twice `pingTimeout.maxTimeout`, so 60 s
+ * (`NodeOptions.pingHandlerTimeoutMs`, unset here, since Optimystic 1.16.0). An app that
+ * replaces this object without a `pingTimeout` gets `@libp2p/ping`'s 10 s handler back.
  *
  * WHAT THE LINK NEEDS OF IT. One ping opens a fresh stream and echoes over it: a protocol
  * negotiation plus the echo, two link round trips by `link-budget.ts`'s counts (a `newStream`
@@ -845,10 +866,11 @@ export interface CadreNodeConfig {
 
   /**
    * Tuning for the strand peer-join block catch-up (see `peer-join-backfill.ts`):
-   * when a strand's libp2p node connects to a peer this runtime has not yet
-   * caught up, every block in the strand's own raw store is pushed to that peer,
-   * so a machine that joined the strand after blocks were committed still ends
-   * up physically holding them. Applies to every strand this node starts.
+   * when a strand's libp2p node connects (or reconnects) to a peer, every
+   * block in the strand's own raw store that the peer is not
+   * known to hold is pushed to it, each block once per peer, so a machine that
+   * joined the strand after blocks were committed still ends up physically
+   * holding them. Applies to every strand this node starts.
    * Omit for the defaults (`DEFAULT_PEER_JOIN_BACKFILL`); `{ enabled: false }`
    * restores the no-backfill behaviour. The control network runs its own,
    * separately tuned catch-up — see {@link controlBackfill}.
@@ -877,13 +899,14 @@ export interface CadreNodeConfig {
   /**
    * Tuning for the CONTROL network's peer-join block catch-up (same module,
    * `peer-join-backfill.ts`, wired in `CadreNode.start`): when the control
-   * libp2p node connects to an AUTHORIZED party member this runtime has not yet
-   * caught up, every block in the control database's own raw store is pushed to
-   * it. This is what makes a control block committed while the writer was alone
-   * (collection headers written at genesis above all) physically reach members
-   * that joined later — without it, such a member that restarts offline reads
-   * the affected tables as empty. Pushes are gated on
-   * `CadreNode.isAuthorizedMember`, checked at push time, because the control
+   * libp2p node connects (or reconnects) to an AUTHORIZED party member, every
+   * block in the control database's own raw store that the
+   * member is not known to hold is pushed to it. This is what makes a control
+   * block committed while the writer was alone (collection headers written at
+   * genesis above all) physically reach members that joined later — without it,
+   * such a member that restarts offline reads the affected tables as empty.
+   * Pushes are gated on the node's authorized-member snapshot (the rule
+   * `CadreNode.isAuthorizedMember` reads), checked at push time, because the control
    * network's inbound gate deliberately admits non-members in several states
    * (seed delivery, enrollment, bootstrap/relay peers). Omit for the defaults
    * (`DEFAULT_PEER_JOIN_BACKFILL`); `{ enabled: false }` disables it.
@@ -896,9 +919,10 @@ export interface CadreNodeConfig {
    * starts: each strand node materializes the peer ids bound to REMOVED members
    * (orphaned `Strand.MemberPeer` rows) and refuses them at the stream and
    * connection layers, so removing a party cuts the network to its machines
-   * rather than only deleting its row. Open strands never arm it. Omit for the
-   * defaults (`DEFAULT_REVOCATION_POLL_INTERVAL_MS` refresh cadence);
-   * `{ enabled: false }` restores the pre-existing behaviour.
+   * rather than only deleting its row. Open strands never arm it. Each strand
+   * re-reads its membership when `Strand.Member` or `Strand.MemberPeer` changes,
+   * and at the latest every `DEFAULT_REVOCATION_BACKSTOP_MS`. Omit for the
+   * defaults; `{ enabled: false }` restores the pre-existing behaviour.
    */
   strandRevocationEnforcement?: StrandRevocationEnforcementConfig;
 
@@ -911,9 +935,8 @@ export interface CadreNodeConfig {
    * background without blocking bring-up. `pollIntervalMs` is the IDLE cadence
    * (how often a machine nobody has admitted re-checks) and the cap of the
    * unfinished-join retry ladder, NOT the retry cadence itself — an unfinished
-   * join retries from 1 s, doubling. Omit for the defaults (it mirrors
-   * {@link strandRevocationEnforcement}'s `pollIntervalMs`);
-   * `{ enabled: false }` disarms the loop — for test fixtures that hand-drive
+   * join retries from 1 s, doubling. Omit for the defaults
+   * (`DEFAULT_MEMBERSHIP_RECONCILE_INTERVAL_MS`); `{ enabled: false }` disarms the loop — for test fixtures that hand-drive
    * the membership writers and assert exact row sets.
    */
   strandMembershipReconciliation?: StrandMembershipReconciliationConfig;
@@ -923,15 +946,17 @@ export interface CadreNodeConfig {
    * (`strand-first-sync-gate.ts`), applied to every strand this node launches as a
    * non-founder: the strand's database is withheld from the app (`StrandInstance.database`
    * unset, status `'syncing'`) until the strand's `Strand.Header` has been received from
-   * another member and every `App` table has been read once, because a machine that writes
-   * to a table it has never fetched creates a private copy of it that never merges.
+   * another member and every `Strand` and `App` table has been read once, because a
+   * machine that writes to a table it has never fetched creates a private copy of it that
+   * never merges.
    * `timeoutMs` bounds how long {@link CadreNode.addStrand} waits before rejecting with
-   * `StrandAwaitingFirstSyncError` (retryable — the launch stays up and keeps probing);
-   * `pollIntervalMs` is the probe cadence. Omit for the defaults (`DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`,
+   * `StrandAwaitingFirstSyncError` (retryable — the launch stays up and keeps probing).
+   * While gated the machine probes whenever data lands in the strand's store, and
+   * `backstopMs` after its last probe when none has. Omit for the defaults (`DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS`,
    * sized for a machine re-attaching through a relay on a slow link, the slowest attach
    * measured; that constant's doc comment carries the number, the measurement behind it and
-   * what the budget costs, and is the only copy of them; `DEFAULT_STRAND_FIRST_SYNC_POLL_MS`,
-   * 500 ms). There is deliberately no way to disable the gate: a machine whose store already
+   * what the budget costs, and is the only copy of them; `DEFAULT_STRAND_FIRST_SYNC_BACKSTOP_MS`,
+   * 2 s). There is deliberately no way to disable the gate: a machine whose store already
    * holds the Header is never gated, so nothing that works today is blocked by it.
    */
   strandFirstSync?: StrandFirstSyncConfig;
@@ -939,7 +964,11 @@ export interface CadreNodeConfig {
   /** Hibernation configuration */
   hibernation?: HibernationConfig;
 
-  /** Polling interval for strand watcher in ms (default: 5000) */
+  /**
+   * The strand watcher's backstop in ms (default 300000): the longest it goes without
+   * re-reading `Strand` and `JoinedStrand` when no change to them is heard. It otherwise runs
+   * on a change. Also caps the first step of its retry ladders, which is 5 s otherwise.
+   */
   strandWatchInterval?: number;
 
   /**
@@ -1463,6 +1492,14 @@ export interface FoundStrandConfig {
   memberPrivateKey?: string;
   /** sApp configuration the hosting application provides, as for {@link StrandConfig}. */
   sAppConfig: SAppConfig;
+  /**
+   * A formation invitation to publish bound to this strand, for the app `sAppConfig.id`, in the
+   * same control transaction and owner approval as the strand row. Mint it first with
+   * `createOpenInvitation` (its `expiration` is `expiresAtMs`). When the strand is already
+   * published the invitation is published on its own, under its own approval, as
+   * `publishFormationInvite` would; one already stored under `token` for this strand is kept.
+   */
+  formationInvite?: Omit<FoundingInvite, 'sAppId'>;
   /**
    * Forwarded to the attach ({@link StrandConfig.awaitFirstSync}). Matters only when the
    * call ATTACHES rather than founds — the stored row was published by a sibling machine
@@ -1783,10 +1820,10 @@ export interface CadreNodeEvents {
    * row is the product of the formation's consent, so claiming it needs no second one.
    *
    * **Fired once per strand per session, and it can fire before your listener is
-   * attached.** The strand watcher's first poll runs inside `CadreNode.start()`
+   * attached.** The strand watcher's first run is inside `CadreNode.start()`
    * (100 ms after the watcher starts), so every strand already stored for this
    * party is normally offered while the embedding app is still inside its own
-   * `start()` await. The watcher then records the strand as seen and no later poll
+   * `start()` await. The watcher then records the strand as seen and no later run
    * re-offers it, so a listener attached a moment late misses those strands for the
    * life of the process.
    *
@@ -1841,8 +1878,14 @@ export interface CadreNodeEvents {
   'pendingJoin:changed': PendingJoinStatus;
   /** Emitted when a seed is received via the seed protocol */
   'seed:received': { partyId: string; peerId: string };
-  /** Emitted when a seed is successfully applied */
-  'seed:applied': { partyId: string; peersAdded: number };
+  /**
+   * Emitted when a seed delivered over the seed protocol has been verified, merged and
+   * acknowledged to its sender. The dials of its preferred peers follow this event, so it
+   * waits on no connection. `dialTargets` are those peers (`seedDialTargets`): an embedder
+   * that restarts into another party's stores carries them there, since this node retained
+   * them in its own.
+   */
+  'seed:applied': { partyId: string; peersAdded: number; dialTargets: SeedDialTarget[] };
   /** Emitted when seed application fails */
   'seed:error': { partyId: string; error: string };
   /**
@@ -1850,10 +1893,10 @@ export interface CadreNodeEvents {
    * valid claim proof has been recorded (`claim.record`) and has durably anchored its
    * signer as this node's owner. Carries the claim's party beside the owner key: the
    * party this node should serve from now on, which its own config did not know. Fires
-   * BEFORE the seed is acknowledged to the claimant, its peers merged and its owners
-   * dialed, so it precedes that seed's `seed:applied`; an embedder that restarts into
-   * the claimed party on this event should wait for that `seed:applied` (or `seed:error`)
-   * so the acknowledgement is not lost with the node. `CadreNode.isAwaitingClaim` is the
+   * BEFORE the seed is acknowledged to the claimant and its peers merged, so it precedes
+   * that seed's `seed:applied`; an embedder that restarts into the claimed party on this
+   * event should wait for that `seed:applied` (or `seed:error`) so the acknowledgement is
+   * not lost with the node. `CadreNode.isAwaitingClaim` is the
    * matching predicate for a reader that subscribed too late to see the event.
    */
   'claim:accepted': NodeClaimRecord;
@@ -2113,7 +2156,7 @@ export interface CadreOwnerKey {
 
 /** Why `CadreNode.addOwner` refuses by name (`OwnerKeyAddRefusedError.code`). */
 export type OwnerKeyAddRefusal =
-  /** No control connection while the party has other members: the row would stay on this node, and nothing re-issues an `OwnerKey` add. */
+  /** No sibling reachable (`CadreNode.hasReachableControlSibling`) while the party has other members: the row would stay on this node, and nothing re-issues an `OwnerKey` add. */
   | 'alone';
 
 /** Why `CadreNode.removeMachine` refuses by name (`MachineRemovalRefusedError.code`). */
@@ -2154,7 +2197,7 @@ export type OwnerKeyRemovalRefusal =
   | 'last-owner'
   /** The key is this node's own owner key: an owner cannot sign its own row's removal (`A.Key <> old.Key`), so ask another owner key. */
   | 'self'
-  /** A re-vouch of an `OwnerKey` row was asked for while this node has no control connection and the party has other members: the re-added row has no re-issue path. Decided at call time, so never planned. */
+  /** A re-vouch of an `OwnerKey` row was asked for while this node reaches no sibling and the party has other members: the re-added row has no re-issue path. Decided at call time, so never planned. */
   | 'alone';
 
 /** The rows sharing the owner keys' voucher column that a removed owner key strands unless re-vouched first. */
@@ -2268,8 +2311,8 @@ export interface OwnerGrantRedemptionResult {
  * `ControlDatabase.queryRevocations`: the identity triple plus the `ReissuedAt`
  * counter an owner bumps (`ControlDatabase.reissueRevocations`) to re-write — and
  * therefore re-broadcast — a tombstone that committed while the node was alone.
- * Never the ledger marker: that row names no guarded table, and `queryRevocations`
- * skips it, which is what keeps `tableName` a {@link RevocableTable}.
+ * Never the ledger marker an older party may hold: that row names no guarded table, and
+ * `queryRevocations` skips it, which is what keeps `tableName` a {@link RevocableTable}.
  */
 export interface RevocationRow {
   /** Which guarded table's stamp was retired. */
@@ -2286,14 +2329,6 @@ export interface RevocationRow {
   signerSig: string;
 }
 
-/**
- * Outcome of `ControlDatabase.openRevocationLedger`: `'opened'` when this call filed the
- * singleton `Revocation` ledger marker, `'already-open'` when it was already filed (seen
- * by the in-lock guard, or filed first by another owner and refused on the primary key).
- * Either way the marker exists afterwards.
- */
-export type RevocationLedgerOpenResult = 'opened' | 'already-open';
-
 /**
  * Outcome of {@link CadreNode.registerSelf}, surfaced so callers (e.g. the CLI
  * `--owner` branch) can log what happened:
@@ -2493,6 +2528,9 @@ export interface SeedPeer {
   preferred: boolean;
 }
 
+/** A peer a seed nominates for dialing, and the addresses to dial it at (`seedDialTargets`). */
+export type SeedDialTarget = Pick<SeedPeer, 'peerId' | 'multiaddrs'>;
+
 /**
  * Control network seed for bootstrapping new nodes.
  * Pre-populates a new node's cache to solve the cold-start problem: