@serfab/cadre-core 1.11.0 → 1.13.0

package/src/strand-reactivity.ts

@@ -0,0 +1,53 @@
+/**
+ * Which strand nodes are built with Optimystic's change-notification substrate
+ * (`NodeOptions.cohortTopic` in `@optimystic/db-p2p`): a node built with it announces every
+ * commit whose collection log tail it applied, and gives the strand's tables tagged
+ * `"optimystic.network_watch" = true` a network watch, so an app on another machine is woken
+ * by a commit instead of polling. Off unless the operator turns it on; `docs/strands.md` →
+ * "Change notifications (reactivity)" says what turning it on costs and exposes.
+ *
+ * "Cohort topic" is Optimystic's name for the substrate and stays inside this module; cadre
+ * calls the setting `strandReactivity`.
+ */
+
+/** Node-local, operator-supplied; never read from the control database, a strand row, or a peer. */
+export interface StrandReactivityConfig {
+  /** Master switch. Anything but `true` leaves every strand node exactly as before. */
+  enabled: boolean;
+  /** Strands to enable it for, by exact strand id. Absent or empty: every strand this node runs. */
+  strandIds?: string[];
+}
+
+/**
+ * The `createLibp2pNode` options slice for one strand: `{ cohortTopic: { enabled: true } }` when
+ * `config.enabled === true` and (`strandIds` is absent, an empty array, or contains `strandId`
+ * exactly); otherwise `{}` — no `cohortTopic` key at all, never `{ enabled: false }`, so db-p2p
+ * takes its "absent" path unchanged.
+ *
+ * Fails closed on a JS embedder's mistake: an `enabled` that is not the boolean `true`, or a
+ * `strandIds` that is present but not an array, enables nothing.
+ *
+ * Deliberately no `wantK` or `host` tuning: a reactivity root is the tail block's storage group
+ * (`clusterSize` wide), verified at the consensus super-majority, and neither `wantK` nor
+ * `cohortTopic.host.minSigs` governs it; the tiers below the root keep db-p2p's defaults.
+ *
+ * NOTE: with no `host.profile`, db-p2p builds every host as core (forwarder-eligible, 30 s
+ * renewal), a `'transaction'` phone included — it does not follow `fretProfile`. If phone-side
+ * forwarding load shows up, pass `host: { profile: edgeProfile() }` for transaction nodes, after
+ * confirming an edge host still serves its part of a tail block's root group.
+ */
+export function strandCohortTopicOption(
+  config: StrandReactivityConfig | undefined,
+  strandId: string
+): { cohortTopic?: { enabled: true } } {
+  return config?.enabled === true && strandSelected(config.strandIds, strandId)
+    ? { cohortTopic: { enabled: true } }
+    : {};
+}
+
+function strandSelected(strandIds: unknown, strandId: string): boolean {
+  if (strandIds === undefined) {
+    return true;
+  }
+  return Array.isArray(strandIds) && (strandIds.length === 0 || strandIds.includes(strandId));
+}

package/src/types.ts

@@ -3,6 +3,7 @@ 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 { PeerJoinBackfillConfig } from './peer-join-backfill.js';
+import type { StrandReactivityConfig } from './strand-reactivity.js';
 import type { StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.js';
 import type { StrandMembershipReconciliationConfig } from './strand-membership-reconciler.js';
 import type { StrandFirstSyncConfig } from './strand-first-sync-gate.js';
@@ -826,6 +827,25 @@ export interface CadreNodeConfig {
    */
   strandBackfill?: PeerJoinBackfillConfig;
 
+  /**
+   * Optimystic change notifications on this node's strand nodes (`strand-reactivity.ts`):
+   * a strand node built with them announces the commits whose collection log tail it applied,
+   * and an sApp table tagged `"optimystic.network_watch" = true` wakes its `Database.watch`
+   * subscribers on another machine's commit instead of only on local ones. Default off; with
+   * it off every strand node is built exactly as before. `strandIds` narrows it to chosen
+   * strands, independently of `strandFilter` (which decides whether a strand runs at all).
+   *
+   * Frozen when the strand's libp2p node is built: a change takes effect at the next build —
+   * a restart, or the strand's next wake from hibernation. Every machine serving the strand
+   * should enable it, because a node without it neither announces nor serves as part of the
+   * group a notification is rooted at. Enabling registers Optimystic's change-notification
+   * protocol handlers on the strand node, which the closed-strand per-stream gate does not
+   * cover, and each watched table pays a cold-start proof of work on every node build. Both
+   * are spelled out in `docs/strands.md` → "Change notifications (reactivity)". The control
+   * node never gets it.
+   */
+  strandReactivity?: StrandReactivityConfig;
+
   /**
    * Tuning for the CONTROL network's peer-join block catch-up (same module,
    * `peer-join-backfill.ts`, wired in `CadreNode.start`): when the control