@optimystic/db-core 1.5.0 → 1.5.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 (152) hide show
  1. package/README.md +336 -336
  2. package/dist/src/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/log/log.d.ts +41 -8
  7. package/dist/src/log/log.d.ts.map +1 -1
  8. package/dist/src/log/log.js +15 -10
  9. package/dist/src/log/log.js.map +1 -1
  10. package/dist/src/testing/test-transactor.d.ts +36 -0
  11. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  12. package/dist/src/testing/test-transactor.js +49 -0
  13. package/dist/src/testing/test-transactor.js.map +1 -1
  14. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  15. package/dist/src/transaction/coordinator.js +26 -9
  16. package/dist/src/transaction/coordinator.js.map +1 -1
  17. package/package.json +1 -1
  18. package/src/blocks/block-store.ts +31 -31
  19. package/src/blocks/block-types.ts +11 -11
  20. package/src/blocks/index.ts +5 -5
  21. package/src/blocks/structs.ts +17 -17
  22. package/src/btree/btree.ts +872 -872
  23. package/src/btree/independent-trunk.ts +53 -53
  24. package/src/btree/index.ts +5 -5
  25. package/src/btree/key-range.ts +15 -15
  26. package/src/btree/keyset.ts +6 -6
  27. package/src/btree/nodes.ts +25 -25
  28. package/src/btree/path.ts +37 -37
  29. package/src/btree/tree-block.ts +11 -11
  30. package/src/btree/trunk.ts +14 -14
  31. package/src/chain/chain-nodes.ts +26 -26
  32. package/src/chain/chain.ts +349 -349
  33. package/src/chain/index.ts +3 -3
  34. package/src/cluster/i-cluster.ts +6 -6
  35. package/src/cluster/index.ts +3 -3
  36. package/src/cohort-topic/addressing.ts +120 -120
  37. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  38. package/src/cohort-topic/antidos/index.ts +5 -5
  39. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  40. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  41. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  42. package/src/cohort-topic/antiflood/index.ts +2 -2
  43. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  44. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  45. package/src/cohort-topic/coldstart.ts +237 -237
  46. package/src/cohort-topic/dmax.ts +88 -88
  47. package/src/cohort-topic/gossip/bus.ts +254 -254
  48. package/src/cohort-topic/gossip/index.ts +3 -3
  49. package/src/cohort-topic/gossip/records.ts +45 -45
  50. package/src/cohort-topic/gossip/view.ts +91 -91
  51. package/src/cohort-topic/index.ts +20 -20
  52. package/src/cohort-topic/load/barometer.ts +134 -134
  53. package/src/cohort-topic/load/index.ts +1 -1
  54. package/src/cohort-topic/member-engine.ts +430 -430
  55. package/src/cohort-topic/membership/index.ts +3 -3
  56. package/src/cohort-topic/membership/publisher.ts +163 -163
  57. package/src/cohort-topic/membership/source.ts +41 -41
  58. package/src/cohort-topic/ports.ts +157 -157
  59. package/src/cohort-topic/promotion.ts +477 -477
  60. package/src/cohort-topic/registration/bytes.ts +37 -37
  61. package/src/cohort-topic/registration/handoff.ts +154 -154
  62. package/src/cohort-topic/registration/index.ts +6 -6
  63. package/src/cohort-topic/registration/renewal.ts +495 -495
  64. package/src/cohort-topic/registration/sharding.ts +61 -61
  65. package/src/cohort-topic/registration/store.ts +81 -81
  66. package/src/cohort-topic/registration/types.ts +91 -91
  67. package/src/cohort-topic/ring-hash.ts +50 -50
  68. package/src/cohort-topic/service.ts +416 -416
  69. package/src/cohort-topic/sig/index.ts +2 -2
  70. package/src/cohort-topic/sig/payloads.ts +59 -59
  71. package/src/cohort-topic/sig/threshold.ts +64 -64
  72. package/src/cohort-topic/tiers.ts +74 -74
  73. package/src/cohort-topic/traffic.ts +233 -233
  74. package/src/cohort-topic/walk.ts +326 -326
  75. package/src/cohort-topic/willingness.ts +237 -237
  76. package/src/cohort-topic/wire/index.ts +18 -18
  77. package/src/cohort-topic/wire/payloads.ts +126 -126
  78. package/src/collection/action.ts +48 -48
  79. package/src/collection/collection-type-registry.ts +37 -37
  80. package/src/collection/collection.ts +2203 -2118
  81. package/src/collection/index.ts +4 -4
  82. package/src/collections/diary/index.ts +2 -2
  83. package/src/collections/diary/struct.ts +3 -3
  84. package/src/collections/index.ts +2 -2
  85. package/src/collections/tree/collection-trunk.ts +25 -25
  86. package/src/collections/tree/index.ts +2 -2
  87. package/src/collections/tree/readme.md +55 -55
  88. package/src/log/index.ts +2 -2
  89. package/src/log/log.ts +304 -268
  90. package/src/log/struct.ts +165 -165
  91. package/src/matchmaking/capability-filter.ts +45 -45
  92. package/src/matchmaking/config.ts +98 -98
  93. package/src/matchmaking/index.ts +21 -21
  94. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  95. package/src/matchmaking/provider.ts +123 -123
  96. package/src/matchmaking/query-eval.ts +105 -105
  97. package/src/matchmaking/seeker-walk.ts +127 -127
  98. package/src/matchmaking/seeker.ts +86 -86
  99. package/src/matchmaking/topic-anchor.ts +90 -90
  100. package/src/matchmaking/voting-quorum.ts +394 -394
  101. package/src/network/i-peer-network.ts +25 -25
  102. package/src/network/repo-protocol.ts +13 -13
  103. package/src/network/types.ts +37 -37
  104. package/src/reactivity/backfill.ts +220 -220
  105. package/src/reactivity/backpressure.ts +191 -191
  106. package/src/reactivity/checkpoint.ts +308 -308
  107. package/src/reactivity/config.ts +172 -172
  108. package/src/reactivity/dedupe.ts +132 -132
  109. package/src/reactivity/forwarder.ts +87 -87
  110. package/src/reactivity/index.ts +34 -34
  111. package/src/reactivity/notification.ts +123 -123
  112. package/src/reactivity/policy.ts +79 -79
  113. package/src/reactivity/push-state.ts +310 -310
  114. package/src/reactivity/recover.ts +153 -153
  115. package/src/reactivity/replay-buffer.ts +141 -141
  116. package/src/reactivity/resume.ts +549 -549
  117. package/src/reactivity/rotation.ts +415 -415
  118. package/src/reactivity/subscriber.ts +132 -132
  119. package/src/reactivity/subscription.ts +66 -66
  120. package/src/reactivity/topic-anchor.ts +71 -71
  121. package/src/reactivity/verify.ts +73 -73
  122. package/src/reactivity/wire-validate.ts +13 -13
  123. package/src/testing/async-wait.ts +65 -65
  124. package/src/testing/index.ts +2 -2
  125. package/src/testing/test-transactor.ts +62 -0
  126. package/src/transaction/actions-engine.ts +68 -68
  127. package/src/transaction/coordinator.ts +28 -11
  128. package/src/transaction/index.ts +52 -52
  129. package/src/transaction/operations-hash.ts +196 -196
  130. package/src/transaction/read-dependency-collector.ts +78 -78
  131. package/src/transaction/session.ts +238 -238
  132. package/src/transaction/transaction.ts +442 -442
  133. package/src/transaction/validator.ts +197 -197
  134. package/src/transactor/block-floors.ts +126 -126
  135. package/src/transactor/index.ts +6 -6
  136. package/src/transactor/network-transactor.ts +1545 -1545
  137. package/src/transform/atomic-proxy.ts +92 -92
  138. package/src/transform/cache-source.ts +370 -370
  139. package/src/transform/helpers.ts +164 -164
  140. package/src/transform/index.ts +7 -7
  141. package/src/transform/struct.ts +21 -21
  142. package/src/utility/actor.ts +62 -62
  143. package/src/utility/backoff.ts +95 -95
  144. package/src/utility/batch-coordinator.ts +191 -191
  145. package/src/utility/ensured.ts +32 -32
  146. package/src/utility/groupby.ts +18 -18
  147. package/src/utility/hash-string.ts +14 -14
  148. package/src/utility/is-record-empty.ts +5 -5
  149. package/src/utility/latches.ts +42 -42
  150. package/src/utility/lru-map.ts +60 -60
  151. package/src/utility/nameof.ts +7 -7
  152. package/src/utility/pending.ts +43 -43
@@ -1,73 +1,73 @@
1
- /**
2
- * Reactivity — subscriber/forwarder notification verification seam
3
- * (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
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
7
- * signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
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.
11
- *
12
- * The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
13
- * hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
14
- * as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
15
- * seam is exposed for bindings that carry signers in a different encoding.
16
- */
17
-
18
- import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
19
- import { createRingHash } from "../cohort-topic/ring-hash.js";
20
- import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
21
- import { Tier } from "../cohort-topic/tiers.js";
22
- import type { IRingHash } from "../cohort-topic/ports.js";
23
- import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
24
- import { reactivityTopicId } from "./topic-anchor.js";
25
- import type { NotificationV1 } from "./wire.js";
26
-
27
- /** Verifies a {@link NotificationV1}'s threshold signature against the tail cohort's membership. */
28
- export interface NotificationVerifier {
29
- /** `"verified"` iff `sig` is a valid `≥ minSigs` cohort signature over the commit digest. */
30
- verify(n: NotificationV1): Promise<VerifyResult>;
31
- }
32
-
33
- /** Construction inputs for the default {@link NotificationVerifier}. */
34
- export interface NotificationVerifierDeps {
35
- /** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
36
- readonly verifier: MembershipVerifier;
37
- /** Ring hash for `topicId` / `coord_0` derivation. Default db-core 256-bit SHA-256. */
38
- readonly hash?: IRingHash;
39
- /** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
40
- readonly fanout?: number;
41
- /** Reactivity runs at T3; overridable for tests. */
42
- readonly tier?: Tier;
43
- /** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
44
- readonly signersToBytes?: (signer: string) => Uint8Array;
45
- }
46
-
47
- class MembershipNotificationVerifier implements NotificationVerifier {
48
- private readonly addressing: ReturnType<typeof createTierAddressing>;
49
- private readonly hash: IRingHash;
50
- private readonly tier: Tier;
51
- private readonly signersToBytes: (signer: string) => Uint8Array;
52
-
53
- constructor(private readonly deps: NotificationVerifierDeps) {
54
- this.hash = deps.hash ?? createRingHash();
55
- this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
56
- this.tier = deps.tier ?? Tier.T3;
57
- this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
58
- }
59
-
60
- async verify(n: NotificationV1): Promise<VerifyResult> {
61
- const topicId = reactivityTopicId(b64urlToBytes(n.tailId), this.hash);
62
- const expectedCoord = this.addressing.coord0(topicId);
63
- const signers = n.signers.map(this.signersToBytes);
64
- const payload = b64urlToBytes(n.digest);
65
- const sig = b64urlToBytes(n.sig);
66
- return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig);
67
- }
68
- }
69
-
70
- /** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
71
- export function createNotificationVerifier(deps: NotificationVerifierDeps): NotificationVerifier {
72
- return new MembershipNotificationVerifier(deps);
73
- }
1
+ /**
2
+ * Reactivity — subscriber/forwarder notification verification seam
3
+ * (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
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
7
+ * signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
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.
11
+ *
12
+ * The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
13
+ * hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
14
+ * as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
15
+ * seam is exposed for bindings that carry signers in a different encoding.
16
+ */
17
+
18
+ import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
19
+ import { createRingHash } from "../cohort-topic/ring-hash.js";
20
+ import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
21
+ import { Tier } from "../cohort-topic/tiers.js";
22
+ import type { IRingHash } from "../cohort-topic/ports.js";
23
+ import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
24
+ import { reactivityTopicId } from "./topic-anchor.js";
25
+ import type { NotificationV1 } from "./wire.js";
26
+
27
+ /** Verifies a {@link NotificationV1}'s threshold signature against the tail cohort's membership. */
28
+ export interface NotificationVerifier {
29
+ /** `"verified"` iff `sig` is a valid `≥ minSigs` cohort signature over the commit digest. */
30
+ verify(n: NotificationV1): Promise<VerifyResult>;
31
+ }
32
+
33
+ /** Construction inputs for the default {@link NotificationVerifier}. */
34
+ export interface NotificationVerifierDeps {
35
+ /** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
36
+ readonly verifier: MembershipVerifier;
37
+ /** Ring hash for `topicId` / `coord_0` derivation. Default db-core 256-bit SHA-256. */
38
+ readonly hash?: IRingHash;
39
+ /** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
40
+ readonly fanout?: number;
41
+ /** Reactivity runs at T3; overridable for tests. */
42
+ readonly tier?: Tier;
43
+ /** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
44
+ readonly signersToBytes?: (signer: string) => Uint8Array;
45
+ }
46
+
47
+ class MembershipNotificationVerifier implements NotificationVerifier {
48
+ private readonly addressing: ReturnType<typeof createTierAddressing>;
49
+ private readonly hash: IRingHash;
50
+ private readonly tier: Tier;
51
+ private readonly signersToBytes: (signer: string) => Uint8Array;
52
+
53
+ constructor(private readonly deps: NotificationVerifierDeps) {
54
+ this.hash = deps.hash ?? createRingHash();
55
+ this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
56
+ this.tier = deps.tier ?? Tier.T3;
57
+ this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
58
+ }
59
+
60
+ async verify(n: NotificationV1): Promise<VerifyResult> {
61
+ const topicId = reactivityTopicId(b64urlToBytes(n.tailId), this.hash);
62
+ const expectedCoord = this.addressing.coord0(topicId);
63
+ const signers = n.signers.map(this.signersToBytes);
64
+ const payload = b64urlToBytes(n.digest);
65
+ const sig = b64urlToBytes(n.sig);
66
+ return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig);
67
+ }
68
+ }
69
+
70
+ /** Build the default {@link NotificationVerifier} over the cohort-topic {@link MembershipVerifier}. */
71
+ export function createNotificationVerifier(deps: NotificationVerifierDeps): NotificationVerifier {
72
+ return new MembershipNotificationVerifier(deps);
73
+ }
@@ -1,13 +1,13 @@
1
- /**
2
- * Reactivity — shared wire-validation primitives.
3
- *
4
- * The reactivity message codecs ({@link import("./wire.js")}, {@link import("./push-state.js")},
5
- * {@link import("./backfill.js")}, {@link import("./resume.js")}, plus checkpoint / rotation / recover)
6
- * decode untrusted JSON into validated V1 shapes with the same structural checks the rest of the
7
- * substrate uses. Those generic primitives now live in one place —
8
- * {@link import("../cohort-topic/wire/primitives.js")} — so a hardening tweak lands once; this module is
9
- * a thin re-export kept so the reactivity codecs import from a sibling path. Every helper throws
10
- * {@link CohortWireError} on a defect (base64url byte fields, finite/integer numbers, `v: 1`).
11
- */
12
-
13
- export * from "../cohort-topic/wire/primitives.js";
1
+ /**
2
+ * Reactivity — shared wire-validation primitives.
3
+ *
4
+ * The reactivity message codecs ({@link import("./wire.js")}, {@link import("./push-state.js")},
5
+ * {@link import("./backfill.js")}, {@link import("./resume.js")}, plus checkpoint / rotation / recover)
6
+ * decode untrusted JSON into validated V1 shapes with the same structural checks the rest of the
7
+ * substrate uses. Those generic primitives now live in one place —
8
+ * {@link import("../cohort-topic/wire/primitives.js")} — so a hardening tweak lands once; this module is
9
+ * a thin re-export kept so the reactivity codecs import from a sibling path. Every helper throws
10
+ * {@link CohortWireError} on a defect (base64url byte fields, finite/integer numbers, `v: 1`).
11
+ */
12
+
13
+ export * from "../cohort-topic/wire/primitives.js";
@@ -1,65 +1,65 @@
1
- export interface WaitForOptions {
2
- // NOTE: default is tuned for in-process settles; integration callers over real libp2p
3
- // pass explicit 10k–90k bounds. A new caller that omits timeoutMs gets 2s — fine for
4
- // fast local conditions, but if a slow CI machine flakes on a legitimately-slow wait,
5
- // give that call site an explicit timeoutMs rather than raising this default.
6
- /** Upper bound before the poll gives up. Default 2_000. */
7
- timeoutMs?: number;
8
- /** Poll cadence. Default 10. */
9
- intervalMs?: number;
10
- /** Included in the thrown message so a failure says WHAT never became true. */
11
- description?: string;
12
- }
13
-
14
- /** Real-time sleep. Retain ONLY for residual cases a condition poll cannot cover. */
15
- export const delay = (ms: number): Promise<void> =>
16
- new Promise((resolve) => setTimeout(resolve, ms));
17
-
18
- /**
19
- * Poll `predicate` until it returns true or `timeoutMs` elapses; throws on timeout.
20
- * `predicate` may be sync or async; a thrown/rejected predicate propagates immediately.
21
- * `undefined` is treated as `false` (not ready yet).
22
- */
23
- export async function waitFor(
24
- predicate: () => boolean | Promise<boolean>,
25
- opts?: WaitForOptions,
26
- ): Promise<void> {
27
- const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
28
- const deadline = Date.now() + timeoutMs;
29
- for (;;) {
30
- if (await predicate()) return;
31
- if (Date.now() >= deadline) {
32
- throw new Error(
33
- description
34
- ? `waitFor timed out after ${timeoutMs}ms: ${description}`
35
- : `waitFor timed out after ${timeoutMs}ms`,
36
- );
37
- }
38
- await delay(intervalMs);
39
- }
40
- }
41
-
42
- /**
43
- * Poll `fn` until it returns a non-undefined value or `timeoutMs` elapses; throws on timeout.
44
- * `undefined` means "not ready yet" — callers needing to wait for an actual `undefined`
45
- * should use `waitFor` on a separate flag.
46
- */
47
- export async function waitForValue<T>(
48
- fn: () => T | undefined | Promise<T | undefined>,
49
- opts?: WaitForOptions,
50
- ): Promise<T> {
51
- const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
52
- const deadline = Date.now() + timeoutMs;
53
- for (;;) {
54
- const value = await fn();
55
- if (value !== undefined) return value;
56
- if (Date.now() >= deadline) {
57
- throw new Error(
58
- description
59
- ? `waitForValue timed out after ${timeoutMs}ms: ${description}`
60
- : `waitForValue timed out after ${timeoutMs}ms`,
61
- );
62
- }
63
- await delay(intervalMs);
64
- }
65
- }
1
+ export interface WaitForOptions {
2
+ // NOTE: default is tuned for in-process settles; integration callers over real libp2p
3
+ // pass explicit 10k–90k bounds. A new caller that omits timeoutMs gets 2s — fine for
4
+ // fast local conditions, but if a slow CI machine flakes on a legitimately-slow wait,
5
+ // give that call site an explicit timeoutMs rather than raising this default.
6
+ /** Upper bound before the poll gives up. Default 2_000. */
7
+ timeoutMs?: number;
8
+ /** Poll cadence. Default 10. */
9
+ intervalMs?: number;
10
+ /** Included in the thrown message so a failure says WHAT never became true. */
11
+ description?: string;
12
+ }
13
+
14
+ /** Real-time sleep. Retain ONLY for residual cases a condition poll cannot cover. */
15
+ export const delay = (ms: number): Promise<void> =>
16
+ new Promise((resolve) => setTimeout(resolve, ms));
17
+
18
+ /**
19
+ * Poll `predicate` until it returns true or `timeoutMs` elapses; throws on timeout.
20
+ * `predicate` may be sync or async; a thrown/rejected predicate propagates immediately.
21
+ * `undefined` is treated as `false` (not ready yet).
22
+ */
23
+ export async function waitFor(
24
+ predicate: () => boolean | Promise<boolean>,
25
+ opts?: WaitForOptions,
26
+ ): Promise<void> {
27
+ const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
28
+ const deadline = Date.now() + timeoutMs;
29
+ for (;;) {
30
+ if (await predicate()) return;
31
+ if (Date.now() >= deadline) {
32
+ throw new Error(
33
+ description
34
+ ? `waitFor timed out after ${timeoutMs}ms: ${description}`
35
+ : `waitFor timed out after ${timeoutMs}ms`,
36
+ );
37
+ }
38
+ await delay(intervalMs);
39
+ }
40
+ }
41
+
42
+ /**
43
+ * Poll `fn` until it returns a non-undefined value or `timeoutMs` elapses; throws on timeout.
44
+ * `undefined` means "not ready yet" — callers needing to wait for an actual `undefined`
45
+ * should use `waitFor` on a separate flag.
46
+ */
47
+ export async function waitForValue<T>(
48
+ fn: () => T | undefined | Promise<T | undefined>,
49
+ opts?: WaitForOptions,
50
+ ): Promise<T> {
51
+ const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
52
+ const deadline = Date.now() + timeoutMs;
53
+ for (;;) {
54
+ const value = await fn();
55
+ if (value !== undefined) return value;
56
+ if (Date.now() >= deadline) {
57
+ throw new Error(
58
+ description
59
+ ? `waitForValue timed out after ${timeoutMs}ms: ${description}`
60
+ : `waitForValue timed out after ${timeoutMs}ms`,
61
+ );
62
+ }
63
+ await delay(intervalMs);
64
+ }
65
+ }
@@ -1,3 +1,3 @@
1
- export * from './test-transactor.js';
2
- export * from './async-wait.js';
1
+ export * from './test-transactor.js';
2
+ export * from './async-wait.js';
3
3
  export * from './refresh-probe.js';
@@ -676,6 +676,68 @@ export class TailLandsButReportsStale extends DelegatingTransactor {
676
676
  }
677
677
  }
678
678
 
679
+ /** What one attempt of a write put on the wire: the pend's transforms, with the action id and
680
+ * revision it was pended under. Recorded by {@link RecordsAttemptsRefusesFirstCommit}. */
681
+ export type RecordedAttempt = {
682
+ actionId: ActionId;
683
+ rev?: number;
684
+ transforms: Transforms;
685
+ };
686
+
687
+ /**
688
+ * Records what every attempt of a write pends, and refuses the FIRST commit outright — nothing is
689
+ * delegated, so nothing lands and the retry's refresh cannot find the write's own log entry.
690
+ *
691
+ * That is the case `Collection.completeOwnEntry` does NOT reach: the refused commit left the log
692
+ * block (and, for a brand-new collection, the header) uncommitted, so the refresh has no entry to
693
+ * finish from and the retry REBUILDS its log append from scratch. Storage identifies a saved block
694
+ * revision by `(action id, revision)` and deliberately accepts a retry of the same action at the
695
+ * same revision, so any per-attempt value in that rebuild becomes two contents under one
696
+ * `(action, revision)` across the machines that landed different attempts.
697
+ *
698
+ * `attempts` is therefore asserted on WHOLE — not field by field — so the rule it pins ("a retry at
699
+ * the same revision sends byte-identical transforms") fails for any future per-attempt value, not
700
+ * only the ones known today. Transforms are cloned on the way in, since the caller keeps mutating
701
+ * the live tracker afterwards.
702
+ *
703
+ * Lives here beside {@link CommitLandsButReportsStale} for the reason that one gives: the
704
+ * collection-path and coordinator-path specs must not drift apart on the double they share.
705
+ */
706
+ export class RecordsAttemptsRefusesFirstCommit extends DelegatingTransactor {
707
+ readonly attempts: RecordedAttempt[] = [];
708
+ private refusals: number;
709
+
710
+ constructor(inner: TestTransactor, refusals = 1) {
711
+ super(inner);
712
+ this.refusals = refusals;
713
+ }
714
+
715
+ /** Arm (or re-arm) the refusal counter, so a test can let its setup writes land cleanly and
716
+ * then refuse only the write under test. Replaces whatever is left of the current count. */
717
+ refuseNextCommits(count: number): void {
718
+ this.refusals = count;
719
+ }
720
+
721
+ override async pend(request: PendRequest): Promise<PendResult> {
722
+ this.attempts.push({
723
+ actionId: request.actionId,
724
+ rev: request.rev,
725
+ transforms: structuredClone(request.transforms),
726
+ });
727
+ return this.inner.pend(request);
728
+ }
729
+
730
+ override async commit(request: CommitRequest): Promise<CommitResult> {
731
+ if (this.refusals > 0) {
732
+ this.refusals--;
733
+ // Never delegated: nothing of this attempt is durable, so `TransactorSource.transact`
734
+ // cancels the pend and the writer re-drives at the same action id and revision.
735
+ return { success: false, conflict: true, reason: 'stale commit: injected refusal, nothing landed' };
736
+ }
737
+ return this.inner.commit(request);
738
+ }
739
+ }
740
+
679
741
  /** A competing writer: a real write driven against the UNWRAPPED transactor, so its own
680
742
  * pend/commit calls are invisible to {@link CompetingWriterTransactor}'s counters and cannot
681
743
  * re-trigger the interception. See {@link commitRivalTreeWrite} for the usual implementation. */
@@ -1,68 +1,68 @@
1
- import type { ITransactionEngine, Transaction, ExecutionResult, CollectionActions } from './transaction.js';
2
-
3
- export const ACTIONS_ENGINE_ID = "actions@1.0.0";
4
-
5
- /**
6
- * Built-in action-based transaction engine for testing.
7
- *
8
- * This engine treats each statement as a JSON-encoded CollectionActions object.
9
- * It's useful for testing the transaction infrastructure without needing SQL.
10
- *
11
- * This is a PURE TRANSLATOR (model (a) of the {@link ITransactionEngine} contract):
12
- * execute() parses statements into CollectionActions[] and RETURNS them. It never
13
- * touches a coordinator or mutates any collection state — application is the sole
14
- * responsibility of the session/coordinator that receives the returned actions.
15
- *
16
- * Each statement format:
17
- * ```json
18
- * {
19
- * "collectionId": "users",
20
- * "actions": [
21
- * { "type": "insert", "data": { "id": 1, "name": "Alice" } }
22
- * ]
23
- * }
24
- * ```
25
- */
26
- export class ActionsEngine implements ITransactionEngine {
27
- readonly id = ACTIONS_ENGINE_ID;
28
-
29
- async execute(transaction: Transaction): Promise<ExecutionResult> {
30
- try {
31
- // Parse each statement as a CollectionActions object
32
- const allActions: CollectionActions[] = [];
33
-
34
- for (const statement of transaction.statements) {
35
- const collectionActions = JSON.parse(statement) as CollectionActions;
36
-
37
- // Validate structure
38
- if (!collectionActions.collectionId || typeof collectionActions.collectionId !== 'string') {
39
- return {
40
- success: false,
41
- error: 'Invalid statement: missing collectionId'
42
- };
43
- }
44
-
45
- if (!collectionActions.actions || !Array.isArray(collectionActions.actions)) {
46
- return {
47
- success: false,
48
- error: `Invalid statement: collection ${collectionActions.collectionId} missing or invalid actions array`
49
- };
50
- }
51
-
52
- allActions.push(collectionActions);
53
- }
54
-
55
- // Pure translation: return parsed actions WITHOUT applying them. The caller
56
- // (session.execute / coordinator.execute) applies them exactly once.
57
- return {
58
- success: true,
59
- actions: allActions
60
- };
61
- } catch (error) {
62
- return {
63
- success: false,
64
- error: `Failed to execute transaction: ${error instanceof Error ? error.message : String(error)}`
65
- };
66
- }
67
- }
68
- }
1
+ import type { ITransactionEngine, Transaction, ExecutionResult, CollectionActions } from './transaction.js';
2
+
3
+ export const ACTIONS_ENGINE_ID = "actions@1.0.0";
4
+
5
+ /**
6
+ * Built-in action-based transaction engine for testing.
7
+ *
8
+ * This engine treats each statement as a JSON-encoded CollectionActions object.
9
+ * It's useful for testing the transaction infrastructure without needing SQL.
10
+ *
11
+ * This is a PURE TRANSLATOR (model (a) of the {@link ITransactionEngine} contract):
12
+ * execute() parses statements into CollectionActions[] and RETURNS them. It never
13
+ * touches a coordinator or mutates any collection state — application is the sole
14
+ * responsibility of the session/coordinator that receives the returned actions.
15
+ *
16
+ * Each statement format:
17
+ * ```json
18
+ * {
19
+ * "collectionId": "users",
20
+ * "actions": [
21
+ * { "type": "insert", "data": { "id": 1, "name": "Alice" } }
22
+ * ]
23
+ * }
24
+ * ```
25
+ */
26
+ export class ActionsEngine implements ITransactionEngine {
27
+ readonly id = ACTIONS_ENGINE_ID;
28
+
29
+ async execute(transaction: Transaction): Promise<ExecutionResult> {
30
+ try {
31
+ // Parse each statement as a CollectionActions object
32
+ const allActions: CollectionActions[] = [];
33
+
34
+ for (const statement of transaction.statements) {
35
+ const collectionActions = JSON.parse(statement) as CollectionActions;
36
+
37
+ // Validate structure
38
+ if (!collectionActions.collectionId || typeof collectionActions.collectionId !== 'string') {
39
+ return {
40
+ success: false,
41
+ error: 'Invalid statement: missing collectionId'
42
+ };
43
+ }
44
+
45
+ if (!collectionActions.actions || !Array.isArray(collectionActions.actions)) {
46
+ return {
47
+ success: false,
48
+ error: `Invalid statement: collection ${collectionActions.collectionId} missing or invalid actions array`
49
+ };
50
+ }
51
+
52
+ allActions.push(collectionActions);
53
+ }
54
+
55
+ // Pure translation: return parsed actions WITHOUT applying them. The caller
56
+ // (session.execute / coordinator.execute) applies them exactly once.
57
+ return {
58
+ success: true,
59
+ actions: allActions
60
+ };
61
+ } catch (error) {
62
+ return {
63
+ success: false,
64
+ error: `Failed to execute transaction: ${error instanceof Error ? error.message : String(error)}`
65
+ };
66
+ }
67
+ }
68
+ }
@@ -415,9 +415,12 @@ export class TransactionCoordinator {
415
415
  // A participant whose log tail landed despite the reported loss finds its own entry
416
416
  // here and FINISHES that action before consuming it (Collection.completeOwnEntry,
417
417
  // from the attempt commitOnceLatched retained). When finishing is refused for a cause
418
- // that can clear, the refresh — not the commit — is what gets retried: commitOnce
419
- // would rebuild the participant's log entry with a fresh timestamp and send a second
420
- // version of a log tail already stored under this transaction's id and revision.
418
+ // that can clear, the refresh — not the commit — is what gets retried: the
419
+ // participant's log entry is already durable, and once a refresh adopts a newer
420
+ // revision commitOnce appends a SECOND entry under this transaction's id. (At an
421
+ // unchanged revision the re-append is byte-identical — see
422
+ // Collection.logAppendBlockIds — so what is at stake is the duplicate entry, not two
423
+ // versions of one tail block.)
421
424
  // Each such round counts against the same budget as a stale loss; a permanent
422
425
  // refusal (a rival holds the revision) escapes as the named TornActionError at once.
423
426
  // Re-refreshing collections an earlier round already refreshed is a no-op.
@@ -1323,8 +1326,27 @@ export class TransactionCoordinator {
1323
1326
  // Get transforms from the collection's tracker
1324
1327
  const transforms = collection.tracker.transforms;
1325
1328
 
1326
- // Write actions to the collection's log to get the log tail block ID
1327
- const log = await Log.open(collection.tracker, collectionActions.collectionId);
1329
+ // Generate action ID from transaction ID
1330
+ const actionId = transaction.id;
1331
+ const newRev = collection.getNextRev();
1332
+
1333
+ // Write actions to the collection's log to get the log tail block ID. The append must be a
1334
+ // fixed function of this write and the revision it requests, because a refused commit is
1335
+ // retried under the same action id and — when nothing else committed in between — at the
1336
+ // same revision, and storage keys a saved block revision by `(action id, revision)`. So any
1337
+ // data block the append mints takes the id an earlier attempt at this revision minted
1338
+ // (Collection.logAppendBlockIds), and the entry is stamped with the transaction's own
1339
+ // timestamp, which is fixed at BEGIN and already stable across attempts, rather than with
1340
+ // the time of the attempt.
1341
+ //
1342
+ // NOTE: execute() reaches this method without marking its transaction in flight, so it mints
1343
+ // afresh every time — correct today, because it re-runs the engine and re-stages, so a
1344
+ // re-drive of it is a DIFFERENT write, and because nothing re-drives it under one transaction
1345
+ // (it returns its failure rather than looping). If execute() ever grows a retry that reuses
1346
+ // the transaction id, it must mark each participant in flight the way commitOnce does, or it
1347
+ // reintroduces exactly the divergence logAppendBlockIds closes.
1348
+ const log = await Log.open(collection.tracker, collectionActions.collectionId,
1349
+ { newDataBlockId: collection.logAppendBlockIds(collection.tracker, actionId, newRev) });
1328
1350
  if (!log) {
1329
1351
  return {
1330
1352
  success: false,
@@ -1332,10 +1354,6 @@ export class TransactionCoordinator {
1332
1354
  };
1333
1355
  }
1334
1356
 
1335
- // Generate action ID from transaction ID
1336
- const actionId = transaction.id;
1337
- const newRev = collection.getNextRev();
1338
-
1339
1357
  // Add actions to log (this updates the tracker with log block changes).
1340
1358
  // Persist the transaction's read set on the entry so a later invalidation cascade can
1341
1359
  // discover this action's read-dependents (see ActionEntry.reads). The whole transaction's
@@ -1359,8 +1377,7 @@ export class TransactionCoordinator {
1359
1377
  actionId,
1360
1378
  newRev,
1361
1379
  () => blockIdsForTransforms(transforms),
1362
- allCollectionIds,
1363
- transaction.reads
1380
+ { collectionIds: allCollectionIds, reads: transaction.reads, timestamp: transaction.stamp.timestamp }
1364
1381
  );
1365
1382
 
1366
1383
  // Return the transforms and log tail block ID