@serfab/cadre-core 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/README.md +8 -6
  2. package/dist/cadre-node.d.ts +386 -114
  3. package/dist/cadre-node.js +887 -359
  4. package/dist/cadre-node.js.map +1 -1
  5. package/dist/control-authorization.d.ts +2 -2
  6. package/dist/control-authorization.js +1 -0
  7. package/dist/control-authorization.js.map +1 -1
  8. package/dist/control-cohort.d.ts +6 -0
  9. package/dist/control-cohort.js +6 -0
  10. package/dist/control-cohort.js.map +1 -1
  11. package/dist/control-database.d.ts +46 -8
  12. package/dist/control-database.js +97 -18
  13. package/dist/control-database.js.map +1 -1
  14. package/dist/control-formation-recorder.d.ts +37 -14
  15. package/dist/control-formation-recorder.js +60 -10
  16. package/dist/control-formation-recorder.js.map +1 -1
  17. package/dist/control-read-retry.d.ts +13 -12
  18. package/dist/control-read-retry.js +14 -12
  19. package/dist/control-read-retry.js.map +1 -1
  20. package/dist/control-schema.d.ts +1 -1
  21. package/dist/control-schema.js +67 -5
  22. package/dist/control-schema.js.map +1 -1
  23. package/dist/control-stream.d.ts +9 -1
  24. package/dist/control-stream.js +24 -1
  25. package/dist/control-stream.js.map +1 -1
  26. package/dist/control-write-retry.d.ts +12 -2
  27. package/dist/control-write-retry.js +13 -2
  28. package/dist/control-write-retry.js.map +1 -1
  29. package/dist/delegate-admission.d.ts +11 -8
  30. package/dist/delegate-admission.js +19 -11
  31. package/dist/delegate-admission.js.map +1 -1
  32. package/dist/diagnostics/connection-path.d.ts +0 -7
  33. package/dist/diagnostics/connection-path.js +0 -7
  34. package/dist/diagnostics/connection-path.js.map +1 -1
  35. package/dist/formation-approval.d.ts +7 -0
  36. package/dist/formation-approval.js +9 -3
  37. package/dist/formation-approval.js.map +1 -1
  38. package/dist/fs-atomic.d.ts +11 -2
  39. package/dist/fs-atomic.js +13 -3
  40. package/dist/fs-atomic.js.map +1 -1
  41. package/dist/hibernation-manager.d.ts +111 -8
  42. package/dist/hibernation-manager.js +234 -49
  43. package/dist/hibernation-manager.js.map +1 -1
  44. package/dist/index.d.ts +8 -6
  45. package/dist/index.js +15 -9
  46. package/dist/index.js.map +1 -1
  47. package/dist/joined-strand-store.d.ts +90 -25
  48. package/dist/joined-strand-store.js +223 -55
  49. package/dist/joined-strand-store.js.map +1 -1
  50. package/dist/key-store-file.js +14 -5
  51. package/dist/key-store-file.js.map +1 -1
  52. package/dist/link-budget.d.ts +367 -69
  53. package/dist/link-budget.js +375 -72
  54. package/dist/link-budget.js.map +1 -1
  55. package/dist/membership-connection-gater.d.ts +30 -43
  56. package/dist/membership-connection-gater.js +31 -42
  57. package/dist/membership-connection-gater.js.map +1 -1
  58. package/dist/peer-dial.d.ts +24 -4
  59. package/dist/peer-dial.js +74 -5
  60. package/dist/peer-dial.js.map +1 -1
  61. package/dist/peer-join-backfill.d.ts +2 -1
  62. package/dist/peer-join-backfill.js +6 -5
  63. package/dist/peer-join-backfill.js.map +1 -1
  64. package/dist/push-fanout.d.ts +6 -0
  65. package/dist/push-fanout.js +6 -0
  66. package/dist/push-fanout.js.map +1 -1
  67. package/dist/relay-reservation.d.ts +3 -1
  68. package/dist/relay-reservation.js +3 -1
  69. package/dist/relay-reservation.js.map +1 -1
  70. package/dist/relay-server.d.ts +79 -0
  71. package/dist/relay-server.js +74 -0
  72. package/dist/relay-server.js.map +1 -0
  73. package/dist/seed-bootstrap.d.ts +57 -4
  74. package/dist/seed-bootstrap.js +107 -83
  75. package/dist/seed-bootstrap.js.map +1 -1
  76. package/dist/storage-scope.d.ts +33 -17
  77. package/dist/storage-scope.js +44 -23
  78. package/dist/storage-scope.js.map +1 -1
  79. package/dist/strand-addr-protocol.d.ts +58 -21
  80. package/dist/strand-addr-protocol.js +133 -85
  81. package/dist/strand-addr-protocol.js.map +1 -1
  82. package/dist/strand-database.d.ts +20 -2
  83. package/dist/strand-database.js +42 -5
  84. package/dist/strand-database.js.map +1 -1
  85. package/dist/strand-first-sync-gate.d.ts +59 -21
  86. package/dist/strand-first-sync-gate.js +58 -19
  87. package/dist/strand-first-sync-gate.js.map +1 -1
  88. package/dist/strand-formation-deadlines.d.ts +151 -0
  89. package/dist/strand-formation-deadlines.js +171 -0
  90. package/dist/strand-formation-deadlines.js.map +1 -0
  91. package/dist/strand-formation-manager.d.ts +63 -30
  92. package/dist/strand-formation-manager.js +67 -41
  93. package/dist/strand-formation-manager.js.map +1 -1
  94. package/dist/strand-formation-protocol.d.ts +45 -35
  95. package/dist/strand-formation-protocol.js +59 -122
  96. package/dist/strand-formation-protocol.js.map +1 -1
  97. package/dist/strand-instance-manager.d.ts +113 -6
  98. package/dist/strand-instance-manager.js +257 -41
  99. package/dist/strand-instance-manager.js.map +1 -1
  100. package/dist/strand-membership-writer.d.ts +6 -0
  101. package/dist/strand-membership-writer.js +11 -0
  102. package/dist/strand-membership-writer.js.map +1 -1
  103. package/dist/strand-peer-book-protocol.d.ts +13 -4
  104. package/dist/strand-peer-book-protocol.js +3 -7
  105. package/dist/strand-peer-book-protocol.js.map +1 -1
  106. package/dist/strand-peer-book.d.ts +1 -1
  107. package/dist/strand-peer-book.js +8 -1
  108. package/dist/strand-peer-book.js.map +1 -1
  109. package/dist/strand-peer-observer.js +1 -1
  110. package/dist/strand-revocation-enforcer.js +2 -1
  111. package/dist/strand-revocation-enforcer.js.map +1 -1
  112. package/dist/strand-solicitation.d.ts +36 -20
  113. package/dist/strand-solicitation.js +4 -4
  114. package/dist/strand-solicitation.js.map +1 -1
  115. package/dist/strand-wake-protocol.d.ts +80 -23
  116. package/dist/strand-wake-protocol.js +89 -64
  117. package/dist/strand-wake-protocol.js.map +1 -1
  118. package/dist/types.d.ts +128 -38
  119. package/dist/types.js +4 -3
  120. package/dist/types.js.map +1 -1
  121. package/package.json +7 -7
  122. package/src/cadre-node.ts +8367 -7776
  123. package/src/control-authorization.ts +2 -1
  124. package/src/control-cohort.ts +6 -0
  125. package/src/control-database.ts +122 -18
  126. package/src/control-formation-recorder.ts +354 -305
  127. package/src/control-read-retry.ts +14 -12
  128. package/src/control-schema.ts +67 -5
  129. package/src/control-stream.ts +25 -1
  130. package/src/control-write-retry.ts +13 -2
  131. package/src/delegate-admission.ts +23 -13
  132. package/src/diagnostics/connection-path.ts +0 -7
  133. package/src/formation-approval.ts +610 -604
  134. package/src/fs-atomic.ts +14 -4
  135. package/src/hibernation-manager.ts +638 -437
  136. package/src/index.ts +28 -10
  137. package/src/joined-strand-store.ts +247 -57
  138. package/src/key-store-file.ts +14 -5
  139. package/src/link-budget.ts +393 -74
  140. package/src/membership-connection-gater.ts +31 -45
  141. package/src/peer-dial.ts +81 -7
  142. package/src/peer-join-backfill.ts +8 -6
  143. package/src/push-fanout.ts +6 -0
  144. package/src/relay-reservation.ts +3 -1
  145. package/src/relay-server.ts +98 -0
  146. package/src/seed-bootstrap.ts +133 -91
  147. package/src/storage-scope.ts +44 -23
  148. package/src/strand-addr-protocol.ts +547 -458
  149. package/src/strand-database.ts +287 -242
  150. package/src/strand-first-sync-gate.ts +58 -19
  151. package/src/strand-formation-deadlines.ts +227 -0
  152. package/src/strand-formation-manager.ts +700 -647
  153. package/src/strand-formation-protocol.ts +103 -150
  154. package/src/strand-instance-manager.ts +287 -44
  155. package/src/strand-membership-writer.ts +12 -0
  156. package/src/strand-peer-book-protocol.ts +16 -13
  157. package/src/strand-peer-book.ts +8 -1
  158. package/src/strand-peer-observer.ts +1 -1
  159. package/src/strand-revocation-enforcer.ts +2 -1
  160. package/src/strand-solicitation.ts +519 -500
  161. package/src/strand-wake-protocol.ts +401 -355
  162. package/src/types.ts +130 -38
package/dist/types.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
2
+ import type { CircuitRelayServerInit } from '@libp2p/circuit-relay-v2';
2
3
  import type { IRawStorage, Libp2pConnectionMonitorInit, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
3
4
  import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
4
5
  import type { PeerJoinBackfillConfig } from './peer-join-backfill.js';
@@ -93,10 +94,12 @@ export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeou
93
94
  * Factory functions are useful for creating per-scope storage instances.
94
95
  *
95
96
  * **The argument is an opaque scope key.** Use it directly as a file name, directory
96
- * name or database name: every key stays within `[A-Za-z0-9._-]`, so no escaping is
97
- * needed and none should be assumed. Do not parse it; `controlStorageScope` /
98
- * `isControlStorageScope` (`storage-scope.ts`) are the supported way to mint and
99
- * recognize the control key. The control key holds the charset by base64url encoding;
97
+ * name or database name: every key stays within `[a-z0-9._-]`, so no escaping is
98
+ * needed and none should be assumed, and two different keys are two different names
99
+ * even on a filesystem that ignores case (Windows, macOS). Do not parse it;
100
+ * `controlStorageScope` / `isControlStorageScope` (`storage-scope.ts`) are the supported
101
+ * way to mint and recognize the control key. The control key holds the charset by
102
+ * lowercase hex encoding;
100
103
  * a strand's key — its strand id, which may have replicated in from another node in
101
104
  * the party — holds it because `StrandInstanceManager.startStrand` runs
102
105
  * `assertStrandScopeKey` on every launch and refuses a strand that fails it.
@@ -140,7 +143,7 @@ export interface StorageConfig {
140
143
  * the single-instance form cannot serve more than one party.
141
144
  *
142
145
  * The `scope` a factory receives is an opaque key already safe as a path or
143
- * database-name segment (always within `[A-Za-z0-9._-]`), so each example below
146
+ * database-name segment (always within `[a-z0-9._-]`), so each example below
144
147
  * interpolates it directly.
145
148
  *
146
149
  * For Node.js environments, use FileRawStorage from @optimystic/db-p2p-storage-fs:
@@ -287,7 +290,8 @@ export interface NetworkConfig {
287
290
  * It buys a node that BOOTS, not a node that boots fast: `start()` still waits
288
291
  * out that first attempt, which costs the drive's whole timeout
289
292
  * (`DEFAULT_RELAY_RESERVE_TIMEOUT_MS`, four link round trips at
290
- * {@link linkRoundTripMs} — 14 s at its default) against a relay that is unreachable
293
+ * {@link linkRoundTripMs} plus two admission decisions — 18 s at its default) against a relay
294
+ * that is unreachable
291
295
  * rather than merely refusing (`relay-reservation.ts` polls to the deadline, in
292
296
  * case libp2p's own discovery lands a reservation independently).
293
297
  *
@@ -310,6 +314,31 @@ export interface NetworkConfig {
310
314
  * better connectivity and uptime), false for transaction profile nodes.
311
315
  */
312
316
  enableRelay?: boolean;
317
+ /**
318
+ * Settings for this machine's circuit-relay SERVER, handed to `@libp2p/circuit-relay-v2`'s
319
+ * `circuitRelayServer(...)` (through db-p2p's `NodeOptions.relayServerInit`) on the control
320
+ * node and on every strand node. Only meaningful while {@link enableRelay} is on.
321
+ *
322
+ * Omitted, a party-run relay FORWARDS WITHOUT LIMIT: `reservations.applyDefaultLimit` is
323
+ * `false`, where libp2p's own default caps every relayed connection at 128 KiB or two
324
+ * minutes and resets it — which cut off any database sync or chat history forwarded
325
+ * through a party's own always-on machine. The store also holds
326
+ * `PARTY_RELAY_MAX_RESERVATIONS` (128) reservations instead of libp2p's 15, and each lives
327
+ * `PARTY_RELAY_RESERVATION_TTL_MS` (2 h) unrefreshed. See `relay-server.ts`.
328
+ *
329
+ * A value is MERGED over those defaults, not substituted for them: `reservations` key by
330
+ * key, every other top-level key as given. Setting only `reservations.maxReservations`
331
+ * keeps the limit off; `reservations: { applyDefaultLimit: true }` is how to turn libp2p's
332
+ * cap back on.
333
+ *
334
+ * The accepted tradeoff of the unlimited default: once a slot is granted, nothing caps what
335
+ * is forwarded through it, and a holder that keeps refreshing keeps it indefinitely — the
336
+ * 2 h lifetime only reclaims a slot whose holder went away. On the control node a peer it
337
+ * cannot place as a party member is bounded by COUNT ({@link unauthorizedRelayReservationCap}).
338
+ * A strand node's relay server has no such budget (its peers are cross-party by design), so
339
+ * any peer that reaches it is bounded only by `maxReservations`.
340
+ */
341
+ relayServerInit?: CircuitRelayServerInit;
313
342
  /**
314
343
  * Cap on concurrent circuit-relay reservations this node's relay server grants to
315
344
  * peers it cannot (yet) recognize as authorized members — the boot-ordering window
@@ -381,16 +410,21 @@ export interface NetworkConfig {
381
410
  * How long ONE cohort peer gets to answer ONE read-path request, in milliseconds, for the
382
411
  * control node and every strand node — as {@link connectionMonitor} is, and for the same
383
412
  * reason: the setting describes the LINK, and a phone's control node and its strand nodes
384
- * ride the same one. Omitted takes {@link COHORT_READ_DEADLINE_MS} (5000 ms), chosen for two
385
- * parties reaching each other only through a relay; Optimystic's own default is 1000 ms.
413
+ * ride the same one. Omitted, the deadline is DERIVED from {@link linkRoundTripMs}: one
414
+ * request and its answer over an open circuit costs two link round trips, so 7 000 ms at the
415
+ * default declaration (`cohortReadDeadlineMs` in `link-budget.ts`; the plugin's
416
+ * {@link COHORT_READ_DEADLINE_MS} is the same number). Optimystic's own default is 1000 ms.
386
417
  *
387
- * Raise it for a link slower still, lower it for a deployment that is all LAN and wants a
388
- * departed peer to stop holding up a read sooner. The cost of a larger value is that a peer
389
- * which is truly gone holds a read of a block missing locally for that long before the read
390
- * is declined and retried, and a joining machine's first sync runs several such consults —
391
- * so a change here should be weighed against
392
- * {@link CadreNodeConfig.strandFirstSync}'s budget. The measurement behind the default, and
393
- * what it costs, are on {@link COHORT_READ_DEADLINE_MS}.
418
+ * Set this only to break the derivation on purpose: an explicit value wins over whatever
419
+ * {@link linkRoundTripMs} would derive, so a deployment that is all LAN can make a departed
420
+ * peer stop holding up a read sooner without declaring a faster link (which would also
421
+ * shorten the dial budgets). A deployment on a slower link should raise
422
+ * {@link linkRoundTripMs} instead, which moves this and every dial budget together. The
423
+ * cost of a larger value is that a peer which is truly gone holds a read of a block missing
424
+ * locally for that long before the read is declined and retried, and a joining machine's
425
+ * first sync runs several such consults — so a change here should be weighed against
426
+ * {@link CadreNodeConfig.strandFirstSync}'s budget. The derivation, its history and what it
427
+ * costs are on {@link COHORT_READ_DEADLINE_MS}.
394
428
  *
395
429
  * Handed to db-p2p's `clusterPolicy.cohortQueryTimeoutMs` unchanged and NOT re-validated
396
430
  * here. Optimystic refuses a value that is not a finite number above zero, or is above its
@@ -409,11 +443,14 @@ export interface NetworkConfig {
409
443
  * This is NOT a timeout. It is the one stated assumption that cadre's own dial and
410
444
  * reservation deadlines are DERIVED from, each by the number of round trips that operation
411
445
  * was measured to cost: a peer-join catch-up's dial to one peer, its push response, one relay
412
- * reservation drive, the control-cohort dial budgets, and libp2p's own `dialTimeout` and
413
- * `inboundUpgradeTimeout` on every node. Reaching another machine through a relay costs a
414
- * fixed number of exchanges, so a deadline written as milliseconds has a link speed above
415
- * which it can never open a connection — which is the defect this declaration exists to make
416
- * impossible to reintroduce one budget at a time. The counts, the measurement behind them,
446
+ * reservation drive, the control-cohort dial budgets, and the per-peer cohort read deadline
447
+ * ({@link cohortQueryTimeoutMs}, unless set explicitly). It is also handed to Optimystic
448
+ * (`NodeOptions.linkRoundTripMs`), default included, which derives its own deadlines from it:
449
+ * its request dials and responses, its block pushes, and libp2p's `dialTimeout` and
450
+ * `inboundUpgradeTimeout` on every node. Reaching another machine through a
451
+ * relay costs a fixed number of exchanges, so a deadline written as milliseconds has a link
452
+ * speed above which it can never open a connection — which is the defect this declaration
453
+ * exists to make impossible to reintroduce one budget at a time. The counts, the measurement behind them,
417
454
  * and what still fails at the supported link are in `link-budget.ts`.
418
455
  *
419
456
  * The default covers the slowest link sereus supports, a 3-second round trip through a relay.
@@ -427,7 +464,8 @@ export interface NetworkConfig {
427
464
  * Refused where the libp2p node is built — inside `CadreNode.start()` for the control
428
465
  * network, inside `CadreNode.addStrand` for a strand — if it is not a finite number above
429
466
  * zero, because every consumer multiplies it into a deadline where a zero means "give up at
430
- * once" and a `NaN` means "never".
467
+ * once" and a `NaN` means "never". Optimystic refuses, in the same place, a value above its
468
+ * `MAX_LINK_ROUND_TRIP_MS` (about 1.66 days).
431
469
  */
432
470
  linkRoundTripMs?: number;
433
471
  /**
@@ -498,14 +536,19 @@ export interface NetworkConfig {
498
536
  * {@link dialTimeoutMs}. Each address is dialed on its own under this limit,
499
537
  * so an address that never answers cannot use up the time the peer's other
500
538
  * addresses needed. Defaults to
501
- * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}.
539
+ * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}. A value given
540
+ * here replaces that whole derived budget, including its allowance for the
541
+ * called machine's admission decision (`relayedDialBudgetMs`).
502
542
  */
503
543
  perAddressDialTimeoutMs?: number;
504
544
  /**
505
- * How often each running strand re-resolves its siblings' strand-network
506
- * addresses into its own libp2p address book — a step of the reconcile pass,
507
- * on its own much longer throttle. Defaults to `STRAND_PEER_ADDR_REFRESH_MS`
508
- * (10 min); must stay well under the peerStore's one-hour address expiry.
545
+ * How long a running strand waits, after a sibling answers its strand-addr
546
+ * RPC, before asking that sibling again for its strand-network addresses — a
547
+ * step of the reconcile pass, scheduled per (sibling, strand). A sibling that
548
+ * did not answer is retried sooner, on `STRAND_PEER_ADDR_RETRY_MS` (or this
549
+ * interval, when it is set shorter). Defaults to
550
+ * `STRAND_PEER_ADDR_REFRESH_MS` (10 min); must stay well under the peerStore's
551
+ * one-hour address expiry.
509
552
  */
510
553
  strandAddrRefreshMs?: number;
511
554
  };
@@ -617,9 +660,10 @@ export interface ControlNetworkConfig {
617
660
  *
618
661
  * The two `*ClusterPolicy` BUILDERS are the same objects with the block-repair
619
662
  * corroboration yardstick declared from the machines enrolled in this party
620
- * ({@link resolveRepairYardstick}) and, if the host set one, its own per-peer read
621
- * deadline in place of {@link COHORT_READ_DEADLINE_MS}. Both arrive in one named
622
- * declarations object, because both are plain numbers meaning unrelated things;
663
+ * ({@link resolveRepairYardstick}) and, if the host set one or declared its link, a
664
+ * per-peer read deadline in place of {@link COHORT_READ_DEADLINE_MS}
665
+ * (`declaredCohortReadDeadlineMs` in `link-budget.ts` settles which). Both arrive in one
666
+ * named declarations object, because both are plain numbers meaning unrelated things;
623
667
  * declaring neither returns the frozen base constant unchanged. A network picks the
624
668
  * derived numbers up when its libp2p node is built, which for a strand is every wake
625
669
  * from hibernation.
@@ -664,6 +708,21 @@ export interface CadreNodeConfig {
664
708
  profile: NodeProfile;
665
709
  /** Which strands to participate in */
666
710
  strandFilter?: StrandFilter;
711
+ /**
712
+ * Run every strand {@link strandFilter} admits, including ones no app on this machine
713
+ * has claimed with `addStrand`, as a **storage replica**: the strand's own libp2p node,
714
+ * storage and `Strand` membership schema, storing and serving its blocks, without the
715
+ * app's schema (no sApp config needed, none of the app's code or schema runs). This is
716
+ * how an always-on machine keeps a copy of every shared workspace its party runs, so a
717
+ * lost phone loses nothing that had reached it.
718
+ *
719
+ * The strand is still announced as `strand:discovered` (once) and stays in
720
+ * `getDiscoveredStrands()` until an app claims it. A replica is always a joiner.
721
+ *
722
+ * Default: `profile === 'storage'` — always-on machines host replicas, phones
723
+ * (`'transaction'`) keep today's announce-only behaviour.
724
+ */
725
+ hostUnclaimedStrands?: boolean;
667
726
  /** Storage configuration (only for storage profile) */
668
727
  storage?: StorageConfig;
669
728
  /** Network configuration */
@@ -877,11 +936,12 @@ export interface CadreNodeConfig {
877
936
  store?: EnrolledMachineStore;
878
937
  };
879
938
  /**
880
- * Node-local record of the strands this node joined from ANOTHER party (see
881
- * `joined-strand-store.ts`): id, type and the closed strand's read secret, recorded
882
- * by `formStrand` and by a joining (not `founder: true`) `addStrand` whose row is
883
- * not in this party's control database, and re-offered on every start as `strand:discovered` — so an embedding
884
- * app keeps no list of its own.
939
+ * Node-local record of the strands this node joined from ANOTHER party and has not yet
940
+ * published to the party-wide `JoinedStrand` table (see `joined-strand-store.ts`): id,
941
+ * type and the closed strand's read secret, recorded by `formStrand` and by a joining
942
+ * (not `founder: true`) `addStrand` whose row this party's control database does not
943
+ * name, offered on every start as `strand:discovered` until an owner machine's
944
+ * reconcile pass publishes it — so an embedding app keeps no list of its own.
885
945
  *
886
946
  * Absent ⇒ a `KeyStoreJoinedStrandStore` over {@link keyStore} when one is
887
947
  * configured (the record carries a secret, and the KeyStore is where every platform
@@ -992,6 +1052,12 @@ export interface StrandInstance {
992
1052
  memberPrivateKey?: string;
993
1053
  /** Activity tracking */
994
1054
  connectedPeers: number;
1055
+ /**
1056
+ * When the strand last saw activity: the app's (`recordStrandActivity`), a requested wake
1057
+ * (`wakeStrand`), or a peer delivering a gated joiner's `Strand.Header`. Always a fresh
1058
+ * `Date`. Bringing the runtime up is NOT activity — a check-in window decides whether to
1059
+ * re-hibernate by whether this changed since before its resume.
1060
+ */
995
1061
  lastActivity: Date;
996
1062
  nextCheckIn?: Date;
997
1063
  /** Latency hint from app or override */
@@ -1412,6 +1478,12 @@ export interface CadreNodeEvents {
1412
1478
  * be idempotent (guard on an in-flight set, not only on
1413
1479
  * `getStrands().has(id)` — the strand manager tracks an instance only once
1414
1480
  * `addStrand` has resolved).
1481
+ *
1482
+ * On a node that hosts storage replicas ({@link CadreNodeConfig.hostUnclaimedStrands},
1483
+ * the default for `profile: 'storage'`) the event still fires once, and the node launches
1484
+ * the strand as a replica right after it — so there `getStrands().has(id)` soon turns
1485
+ * true for a strand no app has claimed; an unclaimed instance has no `sAppInfo`. A
1486
+ * launch that fails is retried by the watcher without a second `strand:discovered`.
1415
1487
  */
1416
1488
  'strand:discovered': {
1417
1489
  strandId: string;
@@ -1760,7 +1832,11 @@ export interface WakeRequest {
1760
1832
  export interface WakeAck {
1761
1833
  /** Whether the receiver honored the wake (member + participated strand). */
1762
1834
  accepted: boolean;
1763
- /** The strand's status after the wake (present when `accepted`). */
1835
+ /**
1836
+ * The strand's status when the receiver accepted the wake (present when `accepted`). The
1837
+ * receiver replies before the wake runs, so `hibernating` or `idle` here means "a wake was
1838
+ * started", not "the strand is now up".
1839
+ */
1764
1840
  status?: StrandStatus;
1765
1841
  /** Reason for rejection (non-member, unknown strand, malformed frame). */
1766
1842
  reason?: string;
@@ -1783,17 +1859,31 @@ export interface StrandAddrRequest {
1783
1859
  */
1784
1860
  delegatePeerId?: string;
1785
1861
  }
1862
+ /**
1863
+ * How a strand-addr responder handled a {@link StrandAddrRequest}. Carried so the
1864
+ * asker can tell "I have nothing" from "I could not answer" — the two need
1865
+ * different retry timing, and an empty address list alone cannot say which.
1866
+ *
1867
+ * - `ok` — looked up; `multiaddrs` is the truth, possibly empty (strand not running here).
1868
+ * - `unavailable` — the responder could not answer: over its concurrency cap, the
1869
+ * request was unreadable, or its own lookup threw (e.g. a control-database read failed).
1870
+ * - `refused` — the requester is not an authorized member in the responder's
1871
+ * current view (possibly because its `CadrePeer` row has not replicated there yet);
1872
+ * any `delegatePeerId` it carried was NOT recorded.
1873
+ */
1874
+ export type StrandAddrStatus = 'ok' | 'unavailable' | 'refused';
1786
1875
  /**
1787
1876
  * Response to a {@link StrandAddrRequest}, carrying the responder's strand-node
1788
1877
  * multiaddrs, returned on the same stream.
1789
1878
  */
1790
1879
  export interface StrandAddrResponse {
1791
- /** Echoes the requested strand id (empty on a reject/error reply). */
1880
+ /** How the responder handled the request; a reply without one is malformed. */
1881
+ status: StrandAddrStatus;
1882
+ /** Echoes the requested strand id; always empty on an `unavailable` reply. */
1792
1883
  strandId: string;
1793
1884
  /**
1794
1885
  * Dialable strand-network multiaddr strings (signaling/`p2p-circuit` first);
1795
- * empty when the responder is a non-member, or does not currently run that
1796
- * strand, or the exchange failed.
1886
+ * empty unless `status` is `ok` and the responder runs that strand.
1797
1887
  */
1798
1888
  multiaddrs: string[];
1799
1889
  }
package/dist/types.js CHANGED
@@ -119,9 +119,10 @@ export const DEFAULT_CHECKIN_WINDOW_MS = 15 * 1000;
119
119
  *
120
120
  * The two `*ClusterPolicy` BUILDERS are the same objects with the block-repair
121
121
  * corroboration yardstick declared from the machines enrolled in this party
122
- * ({@link resolveRepairYardstick}) and, if the host set one, its own per-peer read
123
- * deadline in place of {@link COHORT_READ_DEADLINE_MS}. Both arrive in one named
124
- * declarations object, because both are plain numbers meaning unrelated things;
122
+ * ({@link resolveRepairYardstick}) and, if the host set one or declared its link, a
123
+ * per-peer read deadline in place of {@link COHORT_READ_DEADLINE_MS}
124
+ * (`declaredCohortReadDeadlineMs` in `link-budget.ts` settles which). Both arrive in one
125
+ * named declarations object, because both are plain numbers meaning unrelated things;
125
126
  * declaring neither returns the frozen base constant unchanged. A network picks the
126
127
  * derived numbers up when its libp2p node is built, which for a strand is every wake
127
128
  * from hibernation.
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkFA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AA2aF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,uFAAuF;IACvF,mFAAmF;IACnF,YAAY,EAAE,KAAM;IACpB,kFAAkF;IAClF,kFAAkF;IAClF,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAM,EAAE,UAAU,EAAE,KAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAmBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAmFA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AAqdF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,uFAAuF;IACvF,mFAAmF;IACnF,YAAY,EAAE,KAAM;IACpB,kFAAkF;IAClF,kFAAkF;IAClF,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAM,EAAE,UAAU,EAAE,KAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAmBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@serfab/cadre-core",
3
- "version": "1.7.0",
3
+ "version": "1.8.0",
4
4
  "type": "module",
5
5
  "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
6
6
  "main": "dist/index.js",
@@ -77,7 +77,7 @@
77
77
  "@libp2p/tcp": "^11.0.10",
78
78
  "@libp2p/webrtc": "6.0.14",
79
79
  "@libp2p/websockets": "^10.1.3",
80
- "@optimystic/db-p2p-storage-fs": "^1.7.0",
80
+ "@optimystic/db-p2p-storage-fs": "^1.8.0",
81
81
  "@types/debug": "^4.1.12",
82
82
  "@types/node": "^25.0.10",
83
83
  "@vitest/coverage-v8": "^4.0.17",
@@ -92,12 +92,12 @@
92
92
  "@libp2p/interface": "^3.1.0",
93
93
  "@libp2p/peer-id": "^6.0.4",
94
94
  "@multiformats/multiaddr": "^12.5.1",
95
- "@optimystic/db-core": "^1.7.0",
96
- "@optimystic/db-p2p": "^1.7.0",
97
- "@optimystic/quereus-plugin-crypto": "^1.7.0",
98
- "@optimystic/quereus-plugin-optimystic": "^1.7.0",
95
+ "@optimystic/db-core": "^1.8.0",
96
+ "@optimystic/db-p2p": "^1.8.0",
97
+ "@optimystic/quereus-plugin-crypto": "^1.8.0",
98
+ "@optimystic/quereus-plugin-optimystic": "^1.8.0",
99
99
  "@quereus/quereus": "^4.20.0",
100
- "@serfab/quereus-plugin-sereus": "^1.7.0",
100
+ "@serfab/quereus-plugin-sereus": "^1.8.0",
101
101
  "debug": "^4.4.3",
102
102
  "libp2p": "^3.1.3",
103
103
  "uint8arrays": "^5.1.0"