@optimystic/db-core 1.9.0 → 1.10.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 (117) 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/registration/renewal.d.ts +26 -5
  24. package/dist/src/cohort-topic/registration/renewal.d.ts.map +1 -1
  25. package/dist/src/cohort-topic/registration/renewal.js +71 -21
  26. package/dist/src/cohort-topic/registration/renewal.js.map +1 -1
  27. package/dist/src/cohort-topic/service.d.ts +34 -2
  28. package/dist/src/cohort-topic/service.d.ts.map +1 -1
  29. package/dist/src/cohort-topic/service.js +86 -28
  30. package/dist/src/cohort-topic/service.js.map +1 -1
  31. package/dist/src/cohort-topic/sig/payloads.d.ts +5 -1
  32. package/dist/src/cohort-topic/sig/payloads.d.ts.map +1 -1
  33. package/dist/src/cohort-topic/sig/payloads.js +6 -1
  34. package/dist/src/cohort-topic/sig/payloads.js.map +1 -1
  35. package/dist/src/cohort-topic/sig/threshold.d.ts +29 -4
  36. package/dist/src/cohort-topic/sig/threshold.d.ts.map +1 -1
  37. package/dist/src/cohort-topic/sig/threshold.js +39 -7
  38. package/dist/src/cohort-topic/sig/threshold.js.map +1 -1
  39. package/dist/src/cohort-topic/walk.d.ts +19 -4
  40. package/dist/src/cohort-topic/walk.d.ts.map +1 -1
  41. package/dist/src/cohort-topic/walk.js +29 -6
  42. package/dist/src/cohort-topic/walk.js.map +1 -1
  43. package/dist/src/cohort-topic/willingness.d.ts +17 -1
  44. package/dist/src/cohort-topic/willingness.d.ts.map +1 -1
  45. package/dist/src/cohort-topic/willingness.js +18 -3
  46. package/dist/src/cohort-topic/willingness.js.map +1 -1
  47. package/dist/src/cohort-topic/wire/index.d.ts +1 -1
  48. package/dist/src/cohort-topic/wire/index.d.ts.map +1 -1
  49. package/dist/src/cohort-topic/wire/index.js +1 -1
  50. package/dist/src/cohort-topic/wire/index.js.map +1 -1
  51. package/dist/src/cohort-topic/wire/payloads.d.ts +14 -0
  52. package/dist/src/cohort-topic/wire/payloads.d.ts.map +1 -1
  53. package/dist/src/cohort-topic/wire/payloads.js +20 -0
  54. package/dist/src/cohort-topic/wire/payloads.js.map +1 -1
  55. package/dist/src/cohort-topic/wire/primitives.d.ts +8 -0
  56. package/dist/src/cohort-topic/wire/primitives.d.ts.map +1 -1
  57. package/dist/src/cohort-topic/wire/primitives.js +24 -4
  58. package/dist/src/cohort-topic/wire/primitives.js.map +1 -1
  59. package/dist/src/cohort-topic/wire/types.d.ts +37 -0
  60. package/dist/src/cohort-topic/wire/types.d.ts.map +1 -1
  61. package/dist/src/cohort-topic/wire/validate.d.ts +9 -1
  62. package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
  63. package/dist/src/cohort-topic/wire/validate.js +23 -4
  64. package/dist/src/cohort-topic/wire/validate.js.map +1 -1
  65. package/dist/src/reactivity/config.d.ts +9 -10
  66. package/dist/src/reactivity/config.d.ts.map +1 -1
  67. package/dist/src/reactivity/config.js +9 -9
  68. package/dist/src/reactivity/config.js.map +1 -1
  69. package/dist/src/reactivity/index.d.ts +4 -3
  70. package/dist/src/reactivity/index.d.ts.map +1 -1
  71. package/dist/src/reactivity/index.js +4 -3
  72. package/dist/src/reactivity/index.js.map +1 -1
  73. package/dist/src/reactivity/rotation.d.ts +73 -57
  74. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  75. package/dist/src/reactivity/rotation.js +54 -54
  76. package/dist/src/reactivity/rotation.js.map +1 -1
  77. package/dist/src/reactivity/subscription.d.ts +12 -9
  78. package/dist/src/reactivity/subscription.d.ts.map +1 -1
  79. package/dist/src/reactivity/subscription.js +9 -6
  80. package/dist/src/reactivity/subscription.js.map +1 -1
  81. package/dist/src/reactivity/topic-anchor.d.ts +36 -31
  82. package/dist/src/reactivity/topic-anchor.d.ts.map +1 -1
  83. package/dist/src/reactivity/topic-anchor.js +41 -39
  84. package/dist/src/reactivity/topic-anchor.js.map +1 -1
  85. package/dist/src/reactivity/verify.d.ts +26 -9
  86. package/dist/src/reactivity/verify.d.ts.map +1 -1
  87. package/dist/src/reactivity/verify.js +26 -11
  88. package/dist/src/reactivity/verify.js.map +1 -1
  89. package/dist/src/reactivity/wire.d.ts +1 -1
  90. package/dist/src/reactivity/wire.d.ts.map +1 -1
  91. package/dist/src/transactor/change-notifier.d.ts +1 -1
  92. package/package.json +1 -1
  93. package/src/cohort-topic/addressing.ts +83 -23
  94. package/src/cohort-topic/member-engine.ts +77 -8
  95. package/src/cohort-topic/membership/publisher.ts +1 -1
  96. package/src/cohort-topic/membership/source.ts +4 -0
  97. package/src/cohort-topic/membership/verifier.ts +169 -51
  98. package/src/cohort-topic/ports.ts +87 -15
  99. package/src/cohort-topic/registration/renewal.ts +87 -24
  100. package/src/cohort-topic/service.ts +157 -35
  101. package/src/cohort-topic/sig/payloads.ts +7 -2
  102. package/src/cohort-topic/sig/threshold.ts +41 -7
  103. package/src/cohort-topic/walk.ts +46 -9
  104. package/src/cohort-topic/willingness.ts +34 -3
  105. package/src/cohort-topic/wire/index.ts +1 -0
  106. package/src/cohort-topic/wire/payloads.ts +21 -0
  107. package/src/cohort-topic/wire/primitives.ts +26 -4
  108. package/src/cohort-topic/wire/types.ts +37 -0
  109. package/src/cohort-topic/wire/validate.ts +26 -3
  110. package/src/reactivity/config.ts +10 -10
  111. package/src/reactivity/index.ts +4 -3
  112. package/src/reactivity/rotation.ts +86 -78
  113. package/src/reactivity/subscription.ts +12 -9
  114. package/src/reactivity/topic-anchor.ts +42 -45
  115. package/src/reactivity/verify.ts +36 -17
  116. package/src/reactivity/wire.ts +1 -1
  117. package/src/transactor/change-notifier.ts +1 -1
@@ -1,46 +1,51 @@
1
1
  /**
2
- * Reactivity — rotating, tail-anchored topic.
2
+ * Reactivity — the collection anchor: one topic per collection, a root that follows the tail.
3
3
  *
4
4
  * Transcribed from `docs/reactivity.md` §Anchor:
5
5
  *
6
6
  * ```
7
- * topicId(collection C, tail T) = H(T.blockId ‖ "reactivity")
7
+ * topicId(C) = H(utf8(C.collectionId) ‖ "reactivity") (stable for the collection's life)
8
+ * coord_0 = H(tailId) (the root: the tail block's storage group; moves on rotation)
9
+ * coord_d(P) = H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) (d ≥ 1; never moves)
8
10
  * ```
9
11
  *
10
- * Unlike matchmaking (whose anchor is a stable `(kind, label)`), the reactivity anchor **rotates** with
11
- * the collection's tail block: when the tail fills and a new tail block is born, `topicId` changes and
12
- * the cohort-topic layer treats it as an entirely new topic. The whole-tree migration that follows is
13
- * the rotation ticket's concern; this module owns only the pure derivation.
12
+ * Like matchmaking's `(kind, label)` anchor, the reactivity topic is **stable**: it is a function of the
13
+ * collection id alone, so the tiers below the root sit at fixed positions for the collection's life. What
14
+ * moves is the **root**. The root (announcing) group is the tail block's own storage group — the machines
15
+ * that apply, and so announce, the collection's commits — at `H(tailId)`, the ring position the key network
16
+ * places the tail by. When the tail block fills and a new one is born, the root moves to the new tail's
17
+ * storage group and nothing else does: a rotation is "same topic, the root moved"
18
+ * (`docs/reactivity.md` §Tail rotation).
14
19
  *
15
- * The resulting `topicId` is fed verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`),
16
- * so it is derived with the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
17
- * db-core's own SHA-256 truncated to the ring width, **not** a FRET import. The trailing `"reactivity"`
18
- * literal domain-separates the reactivity tree from any other application anchoring on the same tail id.
20
+ * Both derivations use the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
21
+ * db-core's own SHA-256 truncated to the ring width, **not** a FRET import — because the topic id is fed
22
+ * verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`) and the root coordinate must equal the
23
+ * key network's placement of the tail block byte for byte. The trailing `"reactivity"` literal domain-separates
24
+ * the topic from any other application anchoring on the same collection id, and from the root coordinate,
25
+ * which hashes the bare tail bytes. Concatenation is delimiter-free, exactly as the spec writes it; the
26
+ * constant suffix is unambiguous because no collection-id byte string can alias a `(collectionId, "reactivity")`
27
+ * pair of a different length.
19
28
  *
20
- * Concatenation is delimiter-free, exactly as the spec writes it; the constant suffix is unambiguous
21
- * because no tail-id byte string can alias a `(tailId, "reactivity")` pair of a different length.
22
- *
23
- * `reactivityTopicId` is the small pure helper the ticket asks for once and the rotation ticket
24
- * ([reactivity-rotation-backpressure-policy]) reuses per-emission — define it here, not at the call site.
29
+ * `collectionId` is the UTF-8 of the id exactly as blocks carry it (`header.collectionId`, e.g. `app/users`) —
30
+ * the same bytes a notification's `collectionId` encodes (`reactivityCollectionIdBytes` in db-p2p's
31
+ * `reactivity/topic-bytes.ts`). Origination and every subscriber derive the topic from those bytes, so a
32
+ * notification routes to exactly the managers watching its collection.
25
33
  */
26
- import type { IRingHash } from "../cohort-topic/ports.js";
34
+ import type { IRingHash, RingCoord } from "../cohort-topic/ports.js";
27
35
  /**
28
- * `H(tailId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` for the
29
- * reactivity tree anchored on `tailId` (the collection's current tail block id, as raw bytes).
30
- *
31
- * The shared helper consumed by subscriber attachment, origination, and (per-emission) the rotation
32
- * ticket. `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
36
+ * `H(collectionId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` of a collection's
37
+ * reactivity tree, stable for the collection's life. `collectionId` is the UTF-8 of the id as blocks carry it.
38
+ * `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
33
39
  */
34
- export declare function reactivityTopicId(tailId: Uint8Array, hash?: IRingHash): Uint8Array;
35
- /** Derives the rotating `topicId` for a collection's current tail. */
36
- export interface ReactivityTopicAnchor {
37
- /** `H(tailId ‖ "reactivity")` for the given tail block id (bytes). */
38
- topicId(tailId: Uint8Array): Uint8Array;
39
- }
40
+ export declare function reactivityCollectionTopicId(collectionId: Uint8Array, hash?: IRingHash): Uint8Array;
40
41
  /**
41
- * Build a {@link ReactivityTopicAnchor} over the injected hash. db-p2p passes the same {@link IRingHash}
42
- * it binds to FRET's `RING_BITS` so the anchor and cohort-topic routing keys line up; the default
43
- * constructs db-core's own {@link createRingHash} (256-bit SHA-256).
42
+ * The reactivity root coordinate for a tail: `H(tailId)` over the injected ring hash — the tail block's
43
+ * own ring position, where its storage group sits. `tailId` is the tail's routing key bytes (the raw utf8
44
+ * of the block id, `reactivityTailBytes` on a node), so at the default 256-bit ring width this equals the
45
+ * key network's `hashKey(routingKeyForBlock(tail))` byte for byte; the `topic-bytes-encoding` spec in
46
+ * db-p2p pins that equality. Every party that derives the root group — the notification verifier, the
47
+ * subscriber walk's root step, the forwarder's gossip and recover reads — must start from this one value.
48
+ * It is the one coordinate of a collection's tree that changes when the tail rotates.
44
49
  */
45
- export declare function createReactivityTopicAnchor(hash?: IRingHash): ReactivityTopicAnchor;
50
+ export declare function reactivityRootCoord(tailId: Uint8Array, hash?: IRingHash): RingCoord;
46
51
  //# sourceMappingURL=topic-anchor.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"topic-anchor.d.ts","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAO1D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,SAA4B,GAAG,UAAU,CAMpG;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACrC,sEAAsE;IACtE,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACxC;AAUD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,GAAE,SAA4B,GAAG,qBAAqB,CAErG"}
1
+ {"version":3,"file":"topic-anchor.d.ts","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAOrE;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,UAAU,EAAE,IAAI,GAAE,SAA4B,GAAG,UAAU,CAMpH;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,SAA4B,GAAG,SAAS,CAErG"}
@@ -1,61 +1,63 @@
1
1
  /**
2
- * Reactivity — rotating, tail-anchored topic.
2
+ * Reactivity — the collection anchor: one topic per collection, a root that follows the tail.
3
3
  *
4
4
  * Transcribed from `docs/reactivity.md` §Anchor:
5
5
  *
6
6
  * ```
7
- * topicId(collection C, tail T) = H(T.blockId ‖ "reactivity")
7
+ * topicId(C) = H(utf8(C.collectionId) ‖ "reactivity") (stable for the collection's life)
8
+ * coord_0 = H(tailId) (the root: the tail block's storage group; moves on rotation)
9
+ * coord_d(P) = H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) (d ≥ 1; never moves)
8
10
  * ```
9
11
  *
10
- * Unlike matchmaking (whose anchor is a stable `(kind, label)`), the reactivity anchor **rotates** with
11
- * the collection's tail block: when the tail fills and a new tail block is born, `topicId` changes and
12
- * the cohort-topic layer treats it as an entirely new topic. The whole-tree migration that follows is
13
- * the rotation ticket's concern; this module owns only the pure derivation.
12
+ * Like matchmaking's `(kind, label)` anchor, the reactivity topic is **stable**: it is a function of the
13
+ * collection id alone, so the tiers below the root sit at fixed positions for the collection's life. What
14
+ * moves is the **root**. The root (announcing) group is the tail block's own storage group — the machines
15
+ * that apply, and so announce, the collection's commits — at `H(tailId)`, the ring position the key network
16
+ * places the tail by. When the tail block fills and a new one is born, the root moves to the new tail's
17
+ * storage group and nothing else does: a rotation is "same topic, the root moved"
18
+ * (`docs/reactivity.md` §Tail rotation).
14
19
  *
15
- * The resulting `topicId` is fed verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`),
16
- * so it is derived with the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
17
- * db-core's own SHA-256 truncated to the ring width, **not** a FRET import. The trailing `"reactivity"`
18
- * literal domain-separates the reactivity tree from any other application anchoring on the same tail id.
20
+ * Both derivations use the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
21
+ * db-core's own SHA-256 truncated to the ring width, **not** a FRET import — because the topic id is fed
22
+ * verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`) and the root coordinate must equal the
23
+ * key network's placement of the tail block byte for byte. The trailing `"reactivity"` literal domain-separates
24
+ * the topic from any other application anchoring on the same collection id, and from the root coordinate,
25
+ * which hashes the bare tail bytes. Concatenation is delimiter-free, exactly as the spec writes it; the
26
+ * constant suffix is unambiguous because no collection-id byte string can alias a `(collectionId, "reactivity")`
27
+ * pair of a different length.
19
28
  *
20
- * Concatenation is delimiter-free, exactly as the spec writes it; the constant suffix is unambiguous
21
- * because no tail-id byte string can alias a `(tailId, "reactivity")` pair of a different length.
22
- *
23
- * `reactivityTopicId` is the small pure helper the ticket asks for once and the rotation ticket
24
- * ([reactivity-rotation-backpressure-policy]) reuses per-emission — define it here, not at the call site.
29
+ * `collectionId` is the UTF-8 of the id exactly as blocks carry it (`header.collectionId`, e.g. `app/users`) —
30
+ * the same bytes a notification's `collectionId` encodes (`reactivityCollectionIdBytes` in db-p2p's
31
+ * `reactivity/topic-bytes.ts`). Origination and every subscriber derive the topic from those bytes, so a
32
+ * notification routes to exactly the managers watching its collection.
25
33
  */
26
34
  import { createRingHash } from "../cohort-topic/ring-hash.js";
27
- /** Domain-separation suffix mixed into every reactivity anchor. */
35
+ import { createTierAddressing } from "../cohort-topic/addressing.js";
36
+ /** Domain-separation suffix mixed into the reactivity topic. */
28
37
  const REACTIVITY_SUFFIX = "reactivity";
29
38
  const utf8 = new TextEncoder();
30
39
  /**
31
- * `H(tailId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` for the
32
- * reactivity tree anchored on `tailId` (the collection's current tail block id, as raw bytes).
33
- *
34
- * The shared helper consumed by subscriber attachment, origination, and (per-emission) the rotation
35
- * ticket. `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
40
+ * `H(collectionId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` of a collection's
41
+ * reactivity tree, stable for the collection's life. `collectionId` is the UTF-8 of the id as blocks carry it.
42
+ * `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
36
43
  */
37
- export function reactivityTopicId(tailId, hash = createRingHash()) {
44
+ export function reactivityCollectionTopicId(collectionId, hash = createRingHash()) {
38
45
  const suffixBytes = utf8.encode(REACTIVITY_SUFFIX);
39
- const input = new Uint8Array(tailId.length + suffixBytes.length);
40
- input.set(tailId, 0);
41
- input.set(suffixBytes, tailId.length);
46
+ const input = new Uint8Array(collectionId.length + suffixBytes.length);
47
+ input.set(collectionId, 0);
48
+ input.set(suffixBytes, collectionId.length);
42
49
  return hash.H(input);
43
50
  }
44
- class HashReactivityTopicAnchor {
45
- hash;
46
- constructor(hash) {
47
- this.hash = hash;
48
- }
49
- topicId(tailId) {
50
- return reactivityTopicId(tailId, this.hash);
51
- }
52
- }
53
51
  /**
54
- * Build a {@link ReactivityTopicAnchor} over the injected hash. db-p2p passes the same {@link IRingHash}
55
- * it binds to FRET's `RING_BITS` so the anchor and cohort-topic routing keys line up; the default
56
- * constructs db-core's own {@link createRingHash} (256-bit SHA-256).
52
+ * The reactivity root coordinate for a tail: `H(tailId)` over the injected ring hash — the tail block's
53
+ * own ring position, where its storage group sits. `tailId` is the tail's routing key bytes (the raw utf8
54
+ * of the block id, `reactivityTailBytes` on a node), so at the default 256-bit ring width this equals the
55
+ * key network's `hashKey(routingKeyForBlock(tail))` byte for byte; the `topic-bytes-encoding` spec in
56
+ * db-p2p pins that equality. Every party that derives the root group — the notification verifier, the
57
+ * subscriber walk's root step, the forwarder's gossip and recover reads — must start from this one value.
58
+ * It is the one coordinate of a collection's tree that changes when the tail rotates.
57
59
  */
58
- export function createReactivityTopicAnchor(hash = createRingHash()) {
59
- return new HashReactivityTopicAnchor(hash);
60
+ export function reactivityRootCoord(tailId, hash = createRingHash()) {
61
+ return createTierAddressing(hash).rootCoord(tailId);
60
62
  }
61
63
  //# sourceMappingURL=topic-anchor.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"topic-anchor.js","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,mEAAmE;AACnE,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAEvC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAkB,EAAE,OAAkB,cAAc,EAAE;IACvF,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACjE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACrB,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC;AAQD,MAAM,yBAAyB;IACD;IAA7B,YAA6B,IAAe;QAAf,SAAI,GAAJ,IAAI,CAAW;IAAG,CAAC;IAEhD,OAAO,CAAC,MAAkB;QACzB,OAAO,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAkB,cAAc,EAAE;IAC7E,OAAO,IAAI,yBAAyB,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC"}
1
+ {"version":3,"file":"topic-anchor.js","sourceRoot":"","sources":["../../../src/reactivity/topic-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAGrE,gEAAgE;AAChE,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAEvC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,YAAwB,EAAE,OAAkB,cAAc,EAAE;IACvG,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACvE,KAAK,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAkB,EAAE,OAAkB,cAAc,EAAE;IACzF,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC"}
@@ -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.0",
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