@optimystic/db-core 1.9.0 → 1.10.1

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 (122) hide show
  1. package/dist/src/cohort-topic/addressing.d.ts +46 -6
  2. package/dist/src/cohort-topic/addressing.d.ts.map +1 -1
  3. package/dist/src/cohort-topic/addressing.js +58 -18
  4. package/dist/src/cohort-topic/addressing.js.map +1 -1
  5. package/dist/src/cohort-topic/member-engine.d.ts +21 -1
  6. package/dist/src/cohort-topic/member-engine.d.ts.map +1 -1
  7. package/dist/src/cohort-topic/member-engine.js +39 -9
  8. package/dist/src/cohort-topic/member-engine.js.map +1 -1
  9. package/dist/src/cohort-topic/membership/publisher.js +1 -1
  10. package/dist/src/cohort-topic/membership/publisher.js.map +1 -1
  11. package/dist/src/cohort-topic/membership/source.d.ts +4 -0
  12. package/dist/src/cohort-topic/membership/source.d.ts.map +1 -1
  13. package/dist/src/cohort-topic/membership/source.js +4 -0
  14. package/dist/src/cohort-topic/membership/source.js.map +1 -1
  15. package/dist/src/cohort-topic/membership/verifier.d.ts +51 -9
  16. package/dist/src/cohort-topic/membership/verifier.d.ts.map +1 -1
  17. package/dist/src/cohort-topic/membership/verifier.js +138 -46
  18. package/dist/src/cohort-topic/membership/verifier.js.map +1 -1
  19. package/dist/src/cohort-topic/ports.d.ts +85 -14
  20. package/dist/src/cohort-topic/ports.d.ts.map +1 -1
  21. package/dist/src/cohort-topic/ports.js +1 -1
  22. package/dist/src/cohort-topic/ports.js.map +1 -1
  23. package/dist/src/cohort-topic/promotion.d.ts +3 -2
  24. package/dist/src/cohort-topic/promotion.d.ts.map +1 -1
  25. package/dist/src/cohort-topic/promotion.js +15 -3
  26. package/dist/src/cohort-topic/promotion.js.map +1 -1
  27. package/dist/src/cohort-topic/registration/renewal.d.ts +26 -5
  28. package/dist/src/cohort-topic/registration/renewal.d.ts.map +1 -1
  29. package/dist/src/cohort-topic/registration/renewal.js +71 -21
  30. package/dist/src/cohort-topic/registration/renewal.js.map +1 -1
  31. package/dist/src/cohort-topic/service.d.ts +34 -2
  32. package/dist/src/cohort-topic/service.d.ts.map +1 -1
  33. package/dist/src/cohort-topic/service.js +86 -28
  34. package/dist/src/cohort-topic/service.js.map +1 -1
  35. package/dist/src/cohort-topic/sig/payloads.d.ts +5 -1
  36. package/dist/src/cohort-topic/sig/payloads.d.ts.map +1 -1
  37. package/dist/src/cohort-topic/sig/payloads.js +6 -1
  38. package/dist/src/cohort-topic/sig/payloads.js.map +1 -1
  39. package/dist/src/cohort-topic/sig/threshold.d.ts +29 -4
  40. package/dist/src/cohort-topic/sig/threshold.d.ts.map +1 -1
  41. package/dist/src/cohort-topic/sig/threshold.js +39 -7
  42. package/dist/src/cohort-topic/sig/threshold.js.map +1 -1
  43. package/dist/src/cohort-topic/walk.d.ts +19 -4
  44. package/dist/src/cohort-topic/walk.d.ts.map +1 -1
  45. package/dist/src/cohort-topic/walk.js +29 -6
  46. package/dist/src/cohort-topic/walk.js.map +1 -1
  47. package/dist/src/cohort-topic/willingness.d.ts +17 -1
  48. package/dist/src/cohort-topic/willingness.d.ts.map +1 -1
  49. package/dist/src/cohort-topic/willingness.js +18 -3
  50. package/dist/src/cohort-topic/willingness.js.map +1 -1
  51. package/dist/src/cohort-topic/wire/index.d.ts +1 -1
  52. package/dist/src/cohort-topic/wire/index.d.ts.map +1 -1
  53. package/dist/src/cohort-topic/wire/index.js +1 -1
  54. package/dist/src/cohort-topic/wire/index.js.map +1 -1
  55. package/dist/src/cohort-topic/wire/payloads.d.ts +14 -0
  56. package/dist/src/cohort-topic/wire/payloads.d.ts.map +1 -1
  57. package/dist/src/cohort-topic/wire/payloads.js +20 -0
  58. package/dist/src/cohort-topic/wire/payloads.js.map +1 -1
  59. package/dist/src/cohort-topic/wire/primitives.d.ts +8 -0
  60. package/dist/src/cohort-topic/wire/primitives.d.ts.map +1 -1
  61. package/dist/src/cohort-topic/wire/primitives.js +24 -4
  62. package/dist/src/cohort-topic/wire/primitives.js.map +1 -1
  63. package/dist/src/cohort-topic/wire/types.d.ts +37 -0
  64. package/dist/src/cohort-topic/wire/types.d.ts.map +1 -1
  65. package/dist/src/cohort-topic/wire/validate.d.ts +9 -1
  66. package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
  67. package/dist/src/cohort-topic/wire/validate.js +23 -4
  68. package/dist/src/cohort-topic/wire/validate.js.map +1 -1
  69. package/dist/src/reactivity/config.d.ts +9 -10
  70. package/dist/src/reactivity/config.d.ts.map +1 -1
  71. package/dist/src/reactivity/config.js +9 -9
  72. package/dist/src/reactivity/config.js.map +1 -1
  73. package/dist/src/reactivity/index.d.ts +4 -3
  74. package/dist/src/reactivity/index.d.ts.map +1 -1
  75. package/dist/src/reactivity/index.js +4 -3
  76. package/dist/src/reactivity/index.js.map +1 -1
  77. package/dist/src/reactivity/rotation.d.ts +73 -57
  78. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  79. package/dist/src/reactivity/rotation.js +54 -54
  80. package/dist/src/reactivity/rotation.js.map +1 -1
  81. package/dist/src/reactivity/subscription.d.ts +12 -9
  82. package/dist/src/reactivity/subscription.d.ts.map +1 -1
  83. package/dist/src/reactivity/subscription.js +9 -6
  84. package/dist/src/reactivity/subscription.js.map +1 -1
  85. package/dist/src/reactivity/topic-anchor.d.ts +36 -31
  86. package/dist/src/reactivity/topic-anchor.d.ts.map +1 -1
  87. package/dist/src/reactivity/topic-anchor.js +41 -39
  88. package/dist/src/reactivity/topic-anchor.js.map +1 -1
  89. package/dist/src/reactivity/verify.d.ts +26 -9
  90. package/dist/src/reactivity/verify.d.ts.map +1 -1
  91. package/dist/src/reactivity/verify.js +26 -11
  92. package/dist/src/reactivity/verify.js.map +1 -1
  93. package/dist/src/reactivity/wire.d.ts +1 -1
  94. package/dist/src/reactivity/wire.d.ts.map +1 -1
  95. package/dist/src/transactor/change-notifier.d.ts +1 -1
  96. package/package.json +1 -1
  97. package/src/cohort-topic/addressing.ts +83 -23
  98. package/src/cohort-topic/member-engine.ts +77 -8
  99. package/src/cohort-topic/membership/publisher.ts +1 -1
  100. package/src/cohort-topic/membership/source.ts +4 -0
  101. package/src/cohort-topic/membership/verifier.ts +169 -51
  102. package/src/cohort-topic/ports.ts +87 -15
  103. package/src/cohort-topic/promotion.ts +15 -3
  104. package/src/cohort-topic/registration/renewal.ts +87 -24
  105. package/src/cohort-topic/service.ts +157 -35
  106. package/src/cohort-topic/sig/payloads.ts +7 -2
  107. package/src/cohort-topic/sig/threshold.ts +41 -7
  108. package/src/cohort-topic/walk.ts +46 -9
  109. package/src/cohort-topic/willingness.ts +34 -3
  110. package/src/cohort-topic/wire/index.ts +1 -0
  111. package/src/cohort-topic/wire/payloads.ts +21 -0
  112. package/src/cohort-topic/wire/primitives.ts +26 -4
  113. package/src/cohort-topic/wire/types.ts +37 -0
  114. package/src/cohort-topic/wire/validate.ts +26 -3
  115. package/src/reactivity/config.ts +10 -10
  116. package/src/reactivity/index.ts +4 -3
  117. package/src/reactivity/rotation.ts +86 -78
  118. package/src/reactivity/subscription.ts +12 -9
  119. package/src/reactivity/topic-anchor.ts +42 -45
  120. package/src/reactivity/verify.ts +36 -17
  121. package/src/reactivity/wire.ts +1 -1
  122. package/src/transactor/change-notifier.ts +1 -1
@@ -2,35 +2,52 @@
2
2
  * Reactivity — subscriber/forwarder notification verification seam
3
3
  * (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
4
4
  *
5
- * A forwarder and a subscriber both verify a notification's threshold signature against the **tail
6
- * cohort's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
5
+ * A forwarder and a subscriber both verify a notification's threshold signature against the **root
6
+ * group's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
7
7
  * signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
8
8
  * ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
9
- * cert, so this module is a thin adapter: derive the tail cohort's `coord_0(_, topicId)` from the
10
- * notification's `tailId`, then hand `(signers, coord, tier, digest, sig)` to the verifier.
9
+ * cert, so this module is a thin adapter: derive the root coordinate from the notification's `tailId`,
10
+ * then hand `(signers, coord, tier, digest, sig)` to the verifier under the root placement rule.
11
+ *
12
+ * **The root group is the tail's storage group** (`docs/reactivity.md` §Origination point). The
13
+ * notification's `tailId` is the base64url of the tail's routing key bytes, so `reactivityRootCoord`
14
+ * of those bytes is the ring position the key network stores the tail block at, and the group there is
15
+ * the one whose commit certificate the notification reuses as its signature. The signature threshold is
16
+ * therefore the **verifier's own** `ceil(|root group| × quorumRatio)` — the formula the commit certificate
17
+ * was captured under — never the cohort-topic `minSigs`, and never a value read from the notification.
11
18
  *
12
19
  * The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
13
20
  * hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
14
21
  * as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
15
22
  * seam is exposed for bindings that carry signers in a different encoding.
23
+ *
24
+ * **The placement names the tail.** Every `verifyMessage` call carries a {@link RootPlacement} whose
25
+ * `rootKey` is the notification's tail bytes — the same bytes the root coordinate is derived from — so a
26
+ * direct anchor that can fetch the tail's own commit proof (db-p2p's commit-log anchor) knows which block to
27
+ * ask the root group about. Without the key that anchor answers `"unknown"` and a distant verifier is back
28
+ * to trusting the group's certificate on first use, with no other symptom; the verify spec pins the key.
16
29
  */
17
30
  import { Tier } from "../cohort-topic/tiers.js";
18
31
  import type { IRingHash } from "../cohort-topic/ports.js";
19
32
  import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
20
33
  import type { NotificationV1 } from "./wire.js";
21
- /** Verifies a {@link NotificationV1}'s threshold signature against the tail cohort's membership. */
34
+ /** Verifies a {@link NotificationV1}'s threshold signature against the root group's membership. */
22
35
  export interface NotificationVerifier {
23
- /** `"verified"` iff `sig` is a valid `≥ minSigs` cohort signature over the commit digest. */
36
+ /** `"verified"` iff `sig` is a valid root-group signature over the commit digest, at the placement threshold. */
24
37
  verify(n: NotificationV1): Promise<VerifyResult>;
25
38
  }
26
39
  /** Construction inputs for the default {@link NotificationVerifier}. */
27
40
  export interface NotificationVerifierDeps {
28
41
  /** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
29
42
  readonly verifier: MembershipVerifier;
30
- /** Ring hash for `topicId` / `coord_0` derivation. Default db-core 256-bit SHA-256. */
43
+ /**
44
+ * The ratio the root group's commit certificates are signed under — this node's own consensus
45
+ * `superMajorityThreshold`, never a value off a message. The threshold applied to a notification is
46
+ * `ceil(|root group| × quorumRatio)`; a ratio outside `(0, 1]` throws here, at construction.
47
+ */
48
+ readonly quorumRatio: number;
49
+ /** Ring hash for the root-coordinate derivation. Default db-core 256-bit SHA-256. */
31
50
  readonly hash?: IRingHash;
32
- /** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
33
- readonly fanout?: number;
34
51
  /** Reactivity runs at T3; overridable for tests. */
35
52
  readonly tier?: Tier;
36
53
  /** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
@@ -1 +1 @@
1
- {"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAE/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,oGAAoG;AACpG,MAAM,WAAW,oBAAoB;IACpC,6FAA6F;IAC7F,MAAM,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACjD;AAED,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACxC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,uFAAuF;IACvF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;CACzD;AAyBD,uGAAuG;AACvG,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAE/F"}
1
+ {"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAE/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,mGAAmG;AACnG,MAAM,WAAW,oBAAoB;IACpC,iHAAiH;IACjH,MAAM,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACjD;AAED,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACxC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;CACzD;AA2BD,uGAAuG;AACvG,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAE/F"}
@@ -2,43 +2,58 @@
2
2
  * Reactivity — subscriber/forwarder notification verification seam
3
3
  * (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
4
4
  *
5
- * A forwarder and a subscriber both verify a notification's threshold signature against the **tail
6
- * cohort's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
5
+ * A forwarder and a subscriber both verify a notification's threshold signature against the **root
6
+ * group's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
7
7
  * signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
8
8
  * ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
9
- * cert, so this module is a thin adapter: derive the tail cohort's `coord_0(_, topicId)` from the
10
- * notification's `tailId`, then hand `(signers, coord, tier, digest, sig)` to the verifier.
9
+ * cert, so this module is a thin adapter: derive the root coordinate from the notification's `tailId`,
10
+ * then hand `(signers, coord, tier, digest, sig)` to the verifier under the root placement rule.
11
+ *
12
+ * **The root group is the tail's storage group** (`docs/reactivity.md` §Origination point). The
13
+ * notification's `tailId` is the base64url of the tail's routing key bytes, so `reactivityRootCoord`
14
+ * of those bytes is the ring position the key network stores the tail block at, and the group there is
15
+ * the one whose commit certificate the notification reuses as its signature. The signature threshold is
16
+ * therefore the **verifier's own** `ceil(|root group| × quorumRatio)` — the formula the commit certificate
17
+ * was captured under — never the cohort-topic `minSigs`, and never a value read from the notification.
11
18
  *
12
19
  * The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
13
20
  * hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
14
21
  * as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
15
22
  * seam is exposed for bindings that carry signers in a different encoding.
23
+ *
24
+ * **The placement names the tail.** Every `verifyMessage` call carries a {@link RootPlacement} whose
25
+ * `rootKey` is the notification's tail bytes — the same bytes the root coordinate is derived from — so a
26
+ * direct anchor that can fetch the tail's own commit proof (db-p2p's commit-log anchor) knows which block to
27
+ * ask the root group about. Without the key that anchor answers `"unknown"` and a distant verifier is back
28
+ * to trusting the group's certificate on first use, with no other symptom; the verify spec pins the key.
16
29
  */
17
- import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
18
30
  import { createRingHash } from "../cohort-topic/ring-hash.js";
19
31
  import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
20
32
  import { Tier } from "../cohort-topic/tiers.js";
21
- import { reactivityTopicId } from "./topic-anchor.js";
33
+ import { createRootPlacement } from "../cohort-topic/sig/threshold.js";
34
+ import { reactivityRootCoord } from "./topic-anchor.js";
22
35
  class MembershipNotificationVerifier {
23
36
  deps;
24
- addressing;
25
37
  hash;
26
38
  tier;
39
+ placement;
27
40
  signersToBytes;
28
41
  constructor(deps) {
29
42
  this.deps = deps;
30
43
  this.hash = deps.hash ?? createRingHash();
31
- this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
32
44
  this.tier = deps.tier ?? Tier.T3;
45
+ this.placement = createRootPlacement(deps.quorumRatio);
33
46
  this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
34
47
  }
35
48
  async verify(n) {
36
- const topicId = reactivityTopicId(b64urlToBytes(n.tailId), this.hash);
37
- const expectedCoord = this.addressing.coord0(topicId);
49
+ const tailBytes = b64urlToBytes(n.tailId);
50
+ const expectedCoord = reactivityRootCoord(tailBytes, this.hash);
38
51
  const signers = n.signers.map(this.signersToBytes);
39
52
  const payload = b64urlToBytes(n.digest);
40
53
  const sig = b64urlToBytes(n.sig);
41
- return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig);
54
+ // The ratio was validated once at construction; the key is per notification, so spread it per call.
55
+ const placement = { ...this.placement, rootKey: tailBytes };
56
+ return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig, { placement });
42
57
  }
43
58
  }
44
59
  /** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
@@ -1 +1 @@
1
- {"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAGhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAuBtD,MAAM,8BAA8B;IAMN;IALZ,UAAU,CAA0C;IACpD,IAAI,CAAY;IAChB,IAAI,CAAO;IACX,cAAc,CAAiC;IAEhE,YAA6B,IAA8B;QAA9B,SAAI,GAAJ,IAAI,CAA0B;QAC1D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,IAAI,cAAc,CAAC,CAAC;QACjF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,aAAa,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,CAAiB;QAC7B,MAAM,OAAO,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAC1F,CAAC;CACD;AAED,uGAAuG;AACvG,MAAM,UAAU,0BAA0B,CAAC,IAA8B;IACxE,OAAO,IAAI,8BAA8B,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC"}
1
+ {"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/reactivity/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA2BxD,MAAM,8BAA8B;IAMN;IALZ,IAAI,CAAY;IAChB,IAAI,CAAO;IACX,SAAS,CAAgB;IACzB,cAAc,CAAiC;IAEhE,YAA6B,IAA8B;QAA9B,SAAI,GAAJ,IAAI,CAA0B;QAC1D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,mBAAmB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,aAAa,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,CAAiB;QAC7B,MAAM,SAAS,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,aAAa,GAAG,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACjC,oGAAoG;QACpG,MAAM,SAAS,GAAkB,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACzG,CAAC;CACD;AAED,uGAAuG;AACvG,MAAM,UAAU,0BAA0B,CAAC,IAA8B;IACxE,OAAO,IAAI,8BAA8B,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC"}
@@ -37,7 +37,7 @@ export interface SubscribeAppPayloadV1 {
37
37
  }
38
38
  /** The tail cohort's rotation pre-announce, carried inside (and signed by) a {@link NotificationV1}. */
39
39
  export interface RotationHintV1 {
40
- /** New tail block id the topic anchor is rotating to, base64url. */
40
+ /** New tail block id the collection's root is moving to, base64url. */
41
41
  newTailId: string;
42
42
  /** Revision at which the new tail becomes effective. */
43
43
  effectiveAtRevision: number;
@@ -1 +1 @@
1
- {"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/reactivity/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyBH,+EAA+E;AAC/E,eAAO,MAAM,mCAAmC,QAAY,CAAC;AAI7D,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;CACtB;AAID,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC9B,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,mBAAmB,EAAE,MAAM,CAAC;CAC5B;AAED,4HAA4H;AAC5H,MAAM,WAAW,cAAc;IAC9B,CAAC,EAAE,CAAC,CAAC;IACL,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iGAAiG;IACjG,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAgBD,+FAA+F;AAC/F,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAanF;AAED,4GAA4G;AAC5G,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAEpF;AAED,qGAAqG;AACrG,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,MAA4C,GAAG,qBAAqB,CAE1I;AAyBD,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA4BrE;AAED,sHAAsH;AACtH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAKxF;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,EAAE,eAAe,GAAE,MAAkC,GAAG,UAAU,CAEzH;AAED,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,cAAc,CAEhG"}
1
+ {"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/reactivity/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyBH,+EAA+E;AAC/E,eAAO,MAAM,mCAAmC,QAAY,CAAC;AAI7D,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;CACtB;AAID,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC9B,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,mBAAmB,EAAE,MAAM,CAAC;CAC5B;AAED,4HAA4H;AAC5H,MAAM,WAAW,cAAc;IAC9B,CAAC,EAAE,CAAC,CAAC;IACL,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iGAAiG;IACjG,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAgBD,+FAA+F;AAC/F,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAanF;AAED,4GAA4G;AAC5G,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAEpF;AAED,qGAAqG;AACrG,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,MAA4C,GAAG,qBAAqB,CAE1I;AAyBD,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA4BrE;AAED,sHAAsH;AACtH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAKxF;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,EAAE,eAAe,GAAE,MAAkC,GAAG,UAAU,CAEzH;AAED,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,cAAc,CAEhG"}
@@ -10,7 +10,7 @@ export type CollectionChangeEvent = {
10
10
  readonly rev: number;
11
11
  /**
12
12
  * The collection's chain tail block id at the time of this commit (the `CommitRequest.tailId`).
13
- * Anchors the rotating reactivity topic `H(tailId ‖ "reactivity")`. Present on commit-driven
13
+ * Names the reactivity root (the tail block's storage group, at `H(tailId)`). Present on commit-driven
14
14
  * events; `undefined` on read-driven promotions (the `StorageRepo.get` path has no commit tail —
15
15
  * those never originate anyway, and are cert-gated out downstream).
16
16
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optimystic/db-core",
3
- "version": "1.9.0",
3
+ "version": "1.10.1",
4
4
  "type": "module",
5
5
  "description": "Core database functionality for Optimystic",
6
6
  "main": "dist/src/index.js",
@@ -19,21 +19,53 @@
19
19
  * shorter. `F` is the fan-out (default 16, `log₂F = 4`); tier `d` has exactly `F^d` coordinates.
20
20
  *
21
21
  * The db-p2p binding is responsible for ensuring the coord byte layout (ring width) matches FRET's
22
- * `RING_BITS` so the routing keys produced here line up with FRET's ring on the wire.
22
+ * `RING_BITS` so the coordinates produced here line up with FRET's ring on the wire.
23
+ *
24
+ * **Routing keys.** Each coordinate is `H(<preimage>)`, and the preimage is what a frame is routed on
25
+ * ({@link TierAddressing.routeKey}): FRET's `routeAct` hashes the key it is handed, once, into the ring
26
+ * position it routes to, so handing it the preimage lands the frame on the coordinate, while handing it the
27
+ * coordinate lands it at `H(coord)`. Every coordinate here is computed as the hash of its route key, so the
28
+ * two cannot drift apart.
29
+ *
30
+ * **Root placement at a routing key** (§Tier addressing → Root placement at a routing key). A topic may
31
+ * name a **root key** — raw bytes, e.g. a block's routing key — and then its tier-0 coordinate is
32
+ *
33
+ * ```
34
+ * coord_0 = H(rootKey)
35
+ * ```
36
+ *
37
+ * instead of `H(0x00 ‖ topicId)`. Tiers `d ≥ 1` are unchanged. The root key is hashed exactly once, with
38
+ * no tier byte in front, so the result is the same ring position the key network derives for that
39
+ * routing key — which is what puts the root on the peers that store the block.
23
40
  */
24
41
 
25
- import type { IRingHash, RingCoord } from "./ports.js";
42
+ import type { IRingHash, RingCoord, TopicRouteKey } from "./ports.js";
26
43
 
27
- /** Tier-addressing surface — derives the ring coordinate for tier `d` of a topic. */
44
+ /** Tier-addressing surface — derives the ring coordinate for tier `d` of a topic, and the key that routes to it. */
28
45
  export interface TierAddressing {
29
46
  /** Fan-out per tier (default 16). */
30
47
  readonly F: number;
31
48
  /** Tier-0 root coordinate: `H(0x00 ‖ topicId)`. Peer-independent. */
32
49
  coord0(topicId: Uint8Array): RingCoord;
50
+ /**
51
+ * `H(rootKey)` — the root coordinate of a root-placed topic. Byte-identical to FRET's
52
+ * `hashKey(rootKey)` at the default ring width, so it is the position the key network places that
53
+ * routing key at. Throws `RangeError` on an empty key (no block has an empty routing key).
54
+ */
55
+ rootCoord(rootKey: Uint8Array): RingCoord;
33
56
  /** Tier-`d` coordinate for `d ≥ 1`: `H(d ‖ prefix(H(P), d·log₂F) ‖ topicId)` where `H(P)` is the ring-hash of `peerId`. */
34
57
  coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
35
- /** Dispatches `d === 0` to {@link coord0}, otherwise to {@link coordD}. */
36
- coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
58
+ /**
59
+ * Dispatches `d === 0` to {@link coord0} — or to {@link rootCoord} when the topic names a `rootKey` —
60
+ * and every other tier to {@link coordD}. A `rootKey` at `d ≥ 1` does not change the coordinate.
61
+ */
62
+ coord(d: number, peerId: Uint8Array, topicId: Uint8Array, rootKey?: Uint8Array): RingCoord;
63
+ /**
64
+ * The bytes {@link coord} hashes for the same inputs — `0x00 ‖ topicId`, `rootKey`, or
65
+ * `d ‖ prefix(H(P), d·log₂F) ‖ topicId` — which is what a frame for that cohort is routed on: the router
66
+ * hashes it once into the coordinate. Same validation as {@link coord}.
67
+ */
68
+ routeKey(d: number, peerId: Uint8Array, topicId: Uint8Array, rootKey?: Uint8Array): TopicRouteKey;
37
69
  }
38
70
 
39
71
  /** Default fan-out per tier (`log₂16 = 4`). */
@@ -84,33 +116,61 @@ export class HashTierAddressing implements TierAddressing {
84
116
  }
85
117
 
86
118
  coord0(topicId: Uint8Array): RingCoord {
87
- // H(0x00 ‖ topicId)
88
- const input = new Uint8Array(1 + topicId.length);
89
- input[0] = 0x00;
90
- input.set(topicId, 1);
91
- return this.hash.H(input);
119
+ return this.hash.H(this.tier0Key(topicId));
120
+ }
121
+
122
+ rootCoord(rootKey: Uint8Array): RingCoord {
123
+ return this.hash.H(this.rootRouteKey(rootKey));
92
124
  }
93
125
 
94
126
  coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
127
+ return this.hash.H(this.tierDKey(d, peerId, topicId));
128
+ }
129
+
130
+ coord(d: number, peerId: Uint8Array, topicId: Uint8Array, rootKey?: Uint8Array): RingCoord {
131
+ return this.hash.H(this.routeKey(d, peerId, topicId, rootKey));
132
+ }
133
+
134
+ routeKey(d: number, peerId: Uint8Array, topicId: Uint8Array, rootKey?: Uint8Array): TopicRouteKey {
135
+ if (d !== 0) {
136
+ return this.tierDKey(d, peerId, topicId);
137
+ }
138
+ return rootKey === undefined ? this.tier0Key(topicId) : this.rootRouteKey(rootKey);
139
+ }
140
+
141
+ /** `0x00 ‖ topicId` — the preimage of {@link coord0}. */
142
+ private tier0Key(topicId: Uint8Array): TopicRouteKey {
143
+ const key = new Uint8Array(1 + topicId.length);
144
+ key[0] = 0x00;
145
+ key.set(topicId, 1);
146
+ return key as TopicRouteKey;
147
+ }
148
+
149
+ /** The root key itself — the preimage of {@link rootCoord}, hashed with no tier byte in front. */
150
+ private rootRouteKey(rootKey: Uint8Array): TopicRouteKey {
151
+ if (rootKey.length === 0) {
152
+ throw new RangeError("a root key must be non-empty");
153
+ }
154
+ return rootKey as TopicRouteKey;
155
+ }
156
+
157
+ /** `d ‖ prefix(H(P), d·log₂F) ‖ topicId` — the preimage of {@link coordD}. */
158
+ private tierDKey(d: number, peerId: Uint8Array, topicId: Uint8Array): TopicRouteKey {
95
159
  if (!Number.isInteger(d) || d < 1) {
96
- throw new RangeError(`coordD requires an integer tier d ≥ 1, got ${d}`);
160
+ throw new RangeError(`a tier-d coordinate requires an integer d ≥ 1, got ${d}`);
97
161
  }
98
162
  if (d > 255) {
99
163
  throw new RangeError(`tier d must fit in one byte (≤ 255), got ${d}`);
100
164
  }
101
- // H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) — ring-hash P first so the shard input is uniform
102
- // NOTE: re-hashes peerId on every coordD call; a walk over a tier ladder recomputes H(self) per
103
- // tier. Negligible today (walk steps are network-bound); if coord becomes hot, cache H(peerId).
165
+ // Ring-hash P first so the shard input is uniform.
166
+ // NOTE: re-hashes peerId on every call; a walk over a tier ladder recomputes H(self) per tier.
167
+ // Negligible today (walk steps are network-bound); if coord becomes hot, cache H(peerId).
104
168
  const prefix = prefixBits(this.hash.H(peerId), d * this.log2F);
105
- const input = new Uint8Array(1 + prefix.length + topicId.length);
106
- input[0] = d;
107
- input.set(prefix, 1);
108
- input.set(topicId, 1 + prefix.length);
109
- return this.hash.H(input);
110
- }
111
-
112
- coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
113
- return d === 0 ? this.coord0(topicId) : this.coordD(d, peerId, topicId);
169
+ const key = new Uint8Array(1 + prefix.length + topicId.length);
170
+ key[0] = d;
171
+ key.set(prefix, 1);
172
+ key.set(topicId, 1 + prefix.length);
173
+ return key as TopicRouteKey;
114
174
  }
115
175
  }
116
176
 
@@ -19,7 +19,9 @@
19
19
  * cold-start gate decides whether to instantiate, else `no_state` (walk steps toward the root).
20
20
  * 3. **Admission** — on `accepted`, assign the deterministic primary/backup slots, persist the
21
21
  * soft-state record, count the arrival, run the promotion trigger, and attach the topic-traffic
22
- * signal to the reply.
22
+ * signal to the reply. A decline that only reflects members not heard from yet — a cohort that has
23
+ * just started serving the topic — is held on the injected {@link QuorumWait} while they answer,
24
+ * then decided again, once.
23
25
  *
24
26
  * Every collaborator is injected, so the engine unit-tests without FRET or libp2p.
25
27
  */
@@ -62,6 +64,20 @@ export interface RegisterContext {
62
64
  readonly parentCoord?: Uint8Array;
63
65
  }
64
66
 
67
+ /**
68
+ * Holds a register whose cohort has not heard from enough of its members yet, so it can be admitted on the
69
+ * same request once they answer (§Cold-start instantiation). db-p2p's host implements it over the cohort
70
+ * gossip: it asks the members to gossip their willingness now and resolves as their frames merge.
71
+ */
72
+ export interface QuorumWait {
73
+ /**
74
+ * Resolve when `ready()` turns true or the wait's deadline passes, with the clock at which it settled.
75
+ * Resolves at once (with `now`) when no wait can be opened — the engine is closed, the members were
76
+ * asked too recently to be asked again, or too many registers are already waiting.
77
+ */
78
+ until(ready: () => boolean, now: number): Promise<number>;
79
+ }
80
+
65
81
  /** Current cohort snapshot — the FRET host fills this from the membership source. */
66
82
  export interface CohortSnapshotView {
67
83
  readonly members: readonly Uint8Array[];
@@ -93,6 +109,11 @@ export interface CohortMemberEngineDeps {
93
109
  readonly cohort: () => CohortSnapshotView;
94
110
  /** Whether a quorum of members is willing to serve `tier` (the cold-start gate input). */
95
111
  readonly quorumWilling: (tier: Tier) => boolean;
112
+ /**
113
+ * Where a register declined only for want of members' gossip (`awaitingMembers`) waits for it, once,
114
+ * before the decision is made again. Absent → such a register is declined at once.
115
+ */
116
+ readonly quorumWait?: QuorumWait;
96
117
  // --- anti-DoS guards (all optional; absent = that gate is skipped) ---
97
118
  readonly rateLimiter?: RegisterRateLimiter;
98
119
  /**
@@ -172,11 +193,7 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
172
193
 
173
194
  // 2. Hot path: this cohort already serves the topic.
174
195
  if (this.serves(topicId)) {
175
- if (this.deps.promotion.isPromoted(topicId)) {
176
- // Promoted: bounce same-tier registrations onward (the cheap single-RPC redirect).
177
- return promotedRedirectReply(ctx.treeTier + 1, this.deps.traffic.snapshot(topicId));
178
- }
179
- return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now);
196
+ return this.decideServed(reg, topicId, participantId, tier, ctx, now, true);
180
197
  }
181
198
 
182
199
  // 3. Cold path: instantiate only at a legitimate growth point with a willing quorum. `ctx.followOn`
@@ -192,7 +209,7 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
192
209
  return this.unwillingCohort(reg, now);
193
210
  }
194
211
  this.deps.coldStart.instantiate(topicId, ctx.treeTier, ctx.parentCoord, tier);
195
- return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now);
212
+ return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now, true);
196
213
  }
197
214
 
198
215
  /**
@@ -284,7 +301,28 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
284
301
 
285
302
  // --- admission ---
286
303
 
287
- /** Run the willingness check; on `accepted` persist the record and attach the traffic signal. */
304
+ /** The decision for a topic this cohort serves: a promoted topic redirects onward, any other runs admission. */
305
+ private async decideServed(
306
+ reg: RegisterV1,
307
+ topicId: Uint8Array,
308
+ participantId: Uint8Array,
309
+ tier: Tier,
310
+ ctx: RegisterContext,
311
+ now: number,
312
+ mayWait: boolean,
313
+ ): Promise<RegisterReplyV1> {
314
+ if (this.deps.promotion.isPromoted(topicId)) {
315
+ // Promoted: bounce same-tier registrations onward (the cheap single-RPC redirect).
316
+ return promotedRedirectReply(ctx.treeTier + 1, this.deps.traffic.snapshot(topicId));
317
+ }
318
+ return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now, mayWait);
319
+ }
320
+
321
+ /**
322
+ * Run the willingness check; on `accepted` persist the record and attach the traffic signal. A quorum
323
+ * short only for want of members' gossip is waited for when `mayWait` — which the decision made after
324
+ * that wait never is, so one register waits at most once.
325
+ */
288
326
  private async admitOrDecline(
289
327
  reg: RegisterV1,
290
328
  topicId: Uint8Array,
@@ -292,6 +330,7 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
292
330
  tier: Tier,
293
331
  ctx: RegisterContext,
294
332
  now: number,
333
+ mayWait: boolean,
295
334
  ): Promise<RegisterReplyV1> {
296
335
  const outcome = this.deps.willingness.evaluate(reg, this.deps.profile, now);
297
336
  switch (outcome.kind) {
@@ -299,6 +338,9 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
299
338
  return { v: 1, result: "unwilling_member", candidateMembers: outcome.candidateMembers.map(bytesKey) };
300
339
  }
301
340
  case "unwilling_cohort": {
341
+ if (mayWait && outcome.awaitingMembers && this.deps.quorumWait !== undefined) {
342
+ return this.decideOnceMembersAnswer(this.deps.quorumWait, reg, topicId, participantId, tier, ctx, now);
343
+ }
302
344
  return { v: 1, result: "unwilling_cohort", retryAfterMs: outcome.retryAfterMs };
303
345
  }
304
346
  case "accepted": {
@@ -310,6 +352,33 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
310
352
  }
311
353
  }
312
354
 
355
+ /**
356
+ * Hold `reg` until the members it is waiting on have gossiped (or the wait gives up), then decide again
357
+ * from the top of the served-topic path at the clock the wait settled at: the topic can have been
358
+ * promoted, or lost its forwarder to a topic-budget eviction, while the request was held.
359
+ */
360
+ private async decideOnceMembersAnswer(
361
+ wait: QuorumWait,
362
+ reg: RegisterV1,
363
+ topicId: Uint8Array,
364
+ participantId: Uint8Array,
365
+ tier: Tier,
366
+ ctx: RegisterContext,
367
+ now: number,
368
+ ): Promise<RegisterReplyV1> {
369
+ const settledAt = await wait.until(() => !this.awaitsMembers(reg, now), now);
370
+ if (!this.serves(topicId)) {
371
+ return this.unwillingCohort(reg, settledAt);
372
+ }
373
+ return this.decideServed(reg, topicId, participantId, tier, ctx, settledAt, false);
374
+ }
375
+
376
+ /** True while `reg` is still declined only for want of members' gossip. */
377
+ private awaitsMembers(reg: RegisterV1, now: number): boolean {
378
+ const outcome = this.deps.willingness.evaluate(reg, this.deps.profile, now);
379
+ return outcome.kind === "unwilling_cohort" && outcome.awaitingMembers;
380
+ }
381
+
313
382
  private async accept(
314
383
  reg: RegisterV1,
315
384
  topicId: Uint8Array,
@@ -150,7 +150,7 @@ class SigningMembershipCertPublisher implements MembershipCertPublisher {
150
150
  cert.rotationSig = bytesToB64url(rotation.rotationSig);
151
151
  cert.rotationSigners = rotation.rotationSigners.map(bytesToB64url);
152
152
  }
153
- this.deps.sink.publish(encodeCohortMessage(cert, this.deps.maxMessageBytes));
153
+ this.deps.sink.publish(snapshot.coord, encodeCohortMessage(cert, this.deps.maxMessageBytes));
154
154
  this.lastEpoch = bytesToB64url(snapshot.cohortEpoch);
155
155
  this.lastPublishedAt = now;
156
156
  return cert;
@@ -12,6 +12,10 @@
12
12
  *
13
13
  * Both back-ends present the same {@link IMembershipSource} surface; this router picks between them by
14
14
  * tier. db-p2p supplies the two concrete sources (tx-log reader and FRET cert source).
15
+ *
16
+ * The router picks a source and nothing more: the per-call lookup options a verifier passes to
17
+ * `current` / `fetch` (`{ rootPlaced: true }` for the root of a root-placed topic) go to the chosen
18
+ * source untouched, and it is that source which decides where a root-placed coord's cert is fetched from.
15
19
  */
16
20
 
17
21
  import type { IMembershipSource } from "../ports.js";