@serfab/cadre-core 1.8.0 → 1.10.0

package/src/control-write-retry.ts

@@ -77,11 +77,12 @@ export const SCHEMA_INIT_ATTEMPTS = 5;
  * This budget — not the attempt count — is what makes the policy safe to sit under every
  * control write. A transient failure (stream reset while a connection is still forming)
  * surfaces in well under a second, so it is retried and the loop adds at most ~2.2 s. A
- * genuinely silent cohort member fails at ~21 s per pend round (two `ClusterClient`
- * response-deadline attempts, 10.5 s each at the default declared link; a two-round write
- * measured 42.2 s in `control-write-degraded-cohort-member.integration.ts`), which
- * already exceeds this budget when attempt 1 returns — so that case is surfaced immediately
- * and retry adds ZERO latency to the case where it cannot help.
+ * genuinely silent cohort member costs ~21 s per consensus round (two `ClusterClient`
+ * response-deadline attempts, 10.5 s each at the default declared link): one pend round plus
+ * the cancel discharge's three rounds, about 84 s for one write in
+ * `control-write-degraded-cohort-member.integration.ts`, which already exceeds this budget
+ * when attempt 1 returns — so that case is surfaced immediately and retry adds ZERO latency
+ * to the case where it cannot help.
  *
  * It cuts the loop off by design, so it does not grow with the link: its job is to end the
  * retries of slow attempts, and the caller gets the last attempt's error unchanged. An attempt
@@ -92,16 +93,21 @@ export const SCHEMA_INIT_ATTEMPTS = 5;
  * (10.5 s at the default declared link) still gets none. See `docs/cadre-consistency.md` →
  * "Deadlines Over Optimystic's Reads and Commits".
  *
- * NOTE: a failed commit attempt now also pays a cancel discharge before its error returns
- * (optimystic `TransactorSource.transact`'s catch, added by upstream
- * `1-a-failed-attempt-must-discharge-its-own-pend`) — bounded by six rounds and
- * `abortOrCancelTimeoutMs`, which every collection this repo opens sets to 5 s
- * (`../optimystic/packages/quereus-plugin-optimystic/src/optimystic-adapter/collection-factory.ts`).
- * Two failed attempts whose cancels each run their full budget would consume this whole 10 s
- * ceiling and cut the three-attempt policy to two. Not observed — every measured round of the
- * transient-reset case committed on attempt 3 of 3 — so this is a condition to watch, not work
- * to do: if that case ever starts failing with `failed after 2/3 attempt(s)`, the cancel
- * discharge is where the time went.
+ * NOTE: a failed commit attempt also pays a cancel discharge before its error returns
+ * (optimystic `TransactorSource.transact`'s catch) — bounded by six rounds and
+ * `abortOrCancelTimeoutMs`, which every collection this repo opens sets to the larger of 5 s
+ * and the RPC dial deadline: 42.5 s at the default declared link (`optimysticDialLimits` in
+ * `link-budget.ts`;
+ * `../optimystic/packages/quereus-plugin-optimystic/src/optimystic-adapter/collection-factory.ts`).
+ * One cancel that runs its full budget therefore ends the retries on its own, cutting the
+ * three-attempt policy to however many attempts came before it. A cancel only runs that long
+ * when a peer stays silent, and that attempt has already spent its pend round past this
+ * budget, so the cut loses nothing there. After a transient fault the cancel is either
+ * answered or gives up after its six rounds against a dead transport, in about a second
+ * either way (optimystic `NetworkTransactor.MAX_CANCEL_ROUNDS`). Not observed — every
+ * measured round of the transient-reset case committed on attempt 3 of 3 — so this is a
+ * condition to watch, not work to do: if that case ever starts failing with
+ * `failed after 2/3 attempt(s)`, the cancel discharge is where the time went.
  */
 // eslint-disable-next-line no-restricted-syntax -- cuts off by design: it ends the retries of slow attempts rather than waiting them out; see docs/cadre-consistency.md → "Deadlines Over Optimystic's Reads and Commits"
 export const CONTROL_WRITE_RETRY_BUDGET_MS = 10_000;

package/src/index.ts

@@ -128,61 +128,21 @@ export {
   type JoinedStrandRecord
 } from './joined-strand-store.js';
 
-// Node-local strand peer book: per strand, the strand peers this node has met and
-// their last-known addresses, dialed first on every launch so a restarted machine
-// re-finds the other parties. Same cross-platform split as the bootstrap-peer store
-// above — interface + in-memory + slot-backed stores here, Node-only file backend
-// behind the subpath '@serfab/cadre-core/strand-peer-book-file'.
-export {
-  MemoryStrandPeerBookStore,
-  PersistentStrandPeerBookStore,
-  mergeStrandPeerEntry,
-  sanitizeStrandPeerEntry,
-  strandPeerFreshness,
-  MAX_STRAND_PEERS,
-  STRAND_PEER_MAX_AGE_MS,
-  type StrandPeerBookStore,
-  type StrandPeerBookOptions,
-  type StrandPeerEntry
-} from './strand-peer-book.js';
-export {
-  StrandPeerObserver,
-  dialableAddrs,
-  connectedIdentifiedPeers,
-  STRAND_PEER_OBSERVE_THROTTLE_MS,
-  type StrandPeerObservation,
-  type StrandPeerObserverDeps,
-  type StrandPeerObserverOptions,
-  type ConnectedIdentifiedPeer
-} from './strand-peer-observer.js';
-// The signed book SWAP between strand peers (`/sereus/strand-peers/1.0.0`): the wire
-// protocol, signing and verification, and the per-strand driver that arms it.
-export {
-  STRAND_PEER_BOOK_PROTOCOL,
-  SIGNED_STRAND_PEER_ENTRY_VERSION,
-  STRAND_PEER_ISSUED_AT_SKEW_MS,
-  MAX_BOOK_FRAME_SIZE,
-  StrandPeerBookService,
-  exchangeStrandPeerBook,
-  signStrandPeerEntry,
-  signedStrandPeerEntryPayload,
-  verifySignedStrandPeerEntry,
-  verifyStrandPeerBookFrame,
-  trimBookFrameToFit,
-  assertBookFrameFits,
-  type SignedStrandPeerEntry,
-  type StrandPeerBookFrame,
-  type StrandPeerEntryVerdict,
-  type StrandPeerBookServiceDeps,
-  type ExchangeStrandPeerBookOptions
-} from './strand-peer-book-protocol.js';
-export {
-  StrandPeerBookSwap,
-  STRAND_PEER_BOOK_SWAP_THROTTLE_MS,
-  OWN_ENTRY_RESIGN_DEBOUNCE_MS,
-  type StrandPeerBookSwapDeps,
-  type StrandPeerBookSwapOptions
-} from './strand-peer-book-swap.js';
+// Node-local strand network state: per strand, the state Optimystic's db-p2p saves for
+// the strand node (its FRET routing table with each peer's signed address record), so a
+// restarted strand node re-imports the peers it was talking to. Same cross-platform
+// split as the bootstrap-peer store above — interface + in-memory + slot-backed stores
+// here, Node-only file backend behind '@serfab/cadre-core/strand-network-state-file'.
+export {
+  MemoryStrandNetworkStateStore,
+  PersistentStrandNetworkStateStore,
+  strandNetworkStatePersistence,
+  type StrandNetworkStateStore
+} from './strand-network-state.js';
+// The signed address records a running strand node's FRET table holds, as per-peer dial
+// addresses: what the periodic refresh re-merges into the node's address book, and a
+// diagnostic for "whom could this strand node redial right now?".
+export { strandFretPeerAddrs, type FretAddrHost, type FretPeerAddrs } from './strand-fret-addrs.js';
 
 // Storage scope keys — what `CadreNodeConfig.storage.provider` is called with. A
 // strand's key is its strand id; the control database's key carries the party id,
@@ -524,6 +484,8 @@ export {
 // one declared assumption about the link moves them all — see `NetworkConfig.linkRoundTripMs`.
 export {
   DECLARED_LINK_ROUND_TRIP_MS,
+  CIRCUIT_DIAL_ROUND_TRIPS,
+  RELAY_DIAL_ROUND_TRIPS,
   RELAYED_DIAL_ROUND_TRIPS,
   RELAY_RESERVATION_ROUND_TRIPS,
   CIRCUIT_REQUEST_ROUND_TRIPS,
@@ -536,7 +498,10 @@ export {
   circuitRequestBudgetMs,
   relayedRequestBudgetMs,
   peerJoinPushBudget,
-  type PeerJoinPushBudget
+  type PeerJoinPushBudget,
+  DIAL_ADMISSION_DECISIONS,
+  optimysticDialLimits,
+  type OptimysticDialLimits
 } from './link-budget.js';
 
 // Seed trust policy (trust anchor for incoming seeds)
@@ -561,6 +526,7 @@ export {
 export {
   FormationListener,
   dialFormation,
+  dialFormationByMachine,
   isValidResponderCreatesResult,
   isWellFormedMembershipInvite,
   sanitizeStrandAddrs,
@@ -574,9 +540,22 @@ export {
   type FormationListenerOptions,
   type FormationDialOptions,
   type FormationDialResult,
+  type FormationRejection,
+  type FormationTokenCheck,
   type ResponderProvisionOutcome
 } from './strand-formation-protocol.js';
+// How a formation dial fails: a typed refusal (with a fixed code) or no answer at all
+export {
+  FormationRejectedError,
+  FormationUnreachableError,
+  FormationPostApprovalError,
+  FORMATION_REJECTION_RETRYABLE,
+  isFormationRejectionCode,
+  type FormationRejectionCode
+} from './strand-formation-rejection.js';
 export { formationDeadlines, type FormationDeadlines } from './strand-formation-deadlines.js';
+// The pending-join retry loop behind CadreNode.requestJoin (PendingJoinStatus is in types.ts)
+export { PENDING_JOIN_POLL_MS, PENDING_JOIN_MAX_BACKOFF_MS, MAX_PENDING_JOIN_MS } from './pending-join-runner.js';
 
 // Strand Formation manager (drives the native transport)
 export {
@@ -585,6 +564,7 @@ export {
   MEMBERSHIP_INVITE_TTL_MS,
   MEMBERSHIP_INVITE_UNAVAILABLE_REASON,
   HOST_STRAND_MUST_BE_RECREATED_REASON,
+  type CadrePeerAddrsSource,
   type MembershipInviteIssuer,
   type StrandFormationManagerConfig,
   type StrandFormationManagerOptions

package/src/invitation-bootstrap.ts

@@ -0,0 +1,40 @@
+/**
+ * Which of the inviting party's other machines an open invitation names, so a joiner can still
+ * form while the machine that minted it is offline. The minting machine's own addresses go
+ * first and are not chosen here (`CadreNode.createOpenInvitation`).
+ */
+
+/**
+ * At most this many of the party's other machines are named, each with at most
+ * {@link INVITATION_ADDRS_PER_SIBLING} addresses: 12 extra addresses of roughly 100–200
+ * characters, base64url-encoded into an invitation shared as text.
+ *
+ * NOTE: if invitations are ever carried in a QR code, lower these caps or name the machines by
+ * peer id only.
+ * NOTE: the per-machine cap keeps the record's order (relay first, then direct addresses as the
+ * machine published them, loopback included). If a sibling with many interfaces is seen to have
+ * its reachable address cut, rank loopback and private addresses last before slicing.
+ */
+export const INVITATION_SIBLING_MACHINES = 3;
+export const INVITATION_ADDRS_PER_SIBLING = 4;
+
+/** One other machine of the party whose signed address record resolved. */
+export interface InvitationSibling {
+	peerId: string;
+	/** The record's `UpdatedAt`: when the machine last published its addresses. */
+	updatedAt: number;
+	/** Relay (signaling) addresses first, each ending in `/p2p/<peerId>`. */
+	addrs: string[];
+}
+
+/**
+ * The addresses of the siblings an invitation names. Machines this node is connected to right
+ * now come first, since a live connection is the best evidence that a machine is up; a record
+ * shows only that it was up within the freshness window. Within each half, newest record first.
+ */
+export function selectInvitationSiblingAddrs(siblings: InvitationSibling[], connected: ReadonlySet<string>): string[] {
+	return [...siblings]
+		.sort((a, b) => Number(connected.has(b.peerId)) - Number(connected.has(a.peerId)) || b.updatedAt - a.updatedAt)
+		.slice(0, INVITATION_SIBLING_MACHINES)
+		.flatMap((sibling) => sibling.addrs.slice(0, INVITATION_ADDRS_PER_SIBLING));
+}