@optimystic/db-core 1.18.0 → 1.20.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 (229) hide show
  1. package/README.md +2 -1
  2. package/dist/src/blocks/helpers.d.ts +7 -0
  3. package/dist/src/blocks/helpers.d.ts.map +1 -1
  4. package/dist/src/blocks/helpers.js +7 -1
  5. package/dist/src/blocks/helpers.js.map +1 -1
  6. package/dist/src/btree/btree.d.ts +100 -4
  7. package/dist/src/btree/btree.d.ts.map +1 -1
  8. package/dist/src/btree/btree.js +252 -90
  9. package/dist/src/btree/btree.js.map +1 -1
  10. package/dist/src/btree/node-division.d.ts +37 -0
  11. package/dist/src/btree/node-division.d.ts.map +1 -0
  12. package/dist/src/btree/node-division.js +133 -0
  13. package/dist/src/btree/node-division.js.map +1 -0
  14. package/dist/src/chain/chain.d.ts +23 -0
  15. package/dist/src/chain/chain.d.ts.map +1 -1
  16. package/dist/src/chain/chain.js +43 -6
  17. package/dist/src/chain/chain.js.map +1 -1
  18. package/dist/src/cluster/structs.d.ts +41 -8
  19. package/dist/src/cluster/structs.d.ts.map +1 -1
  20. package/dist/src/cluster/structs.js +18 -7
  21. package/dist/src/cluster/structs.js.map +1 -1
  22. package/dist/src/collection/action.d.ts +29 -0
  23. package/dist/src/collection/action.d.ts.map +1 -1
  24. package/dist/src/collection/action.js +6 -0
  25. package/dist/src/collection/action.js.map +1 -1
  26. package/dist/src/collection/collection.d.ts +566 -120
  27. package/dist/src/collection/collection.d.ts.map +1 -1
  28. package/dist/src/collection/collection.js +1084 -495
  29. package/dist/src/collection/collection.js.map +1 -1
  30. package/dist/src/collection/head-commit.d.ts +110 -0
  31. package/dist/src/collection/head-commit.d.ts.map +1 -0
  32. package/dist/src/collection/head-commit.js +65 -0
  33. package/dist/src/collection/head-commit.js.map +1 -0
  34. package/dist/src/collection/index.d.ts +2 -0
  35. package/dist/src/collection/index.d.ts.map +1 -1
  36. package/dist/src/collection/index.js +2 -0
  37. package/dist/src/collection/index.js.map +1 -1
  38. package/dist/src/collection/segments.d.ts +77 -0
  39. package/dist/src/collection/segments.d.ts.map +1 -0
  40. package/dist/src/collection/segments.js +110 -0
  41. package/dist/src/collection/segments.js.map +1 -0
  42. package/dist/src/collection/struct.d.ts +176 -1
  43. package/dist/src/collection/struct.d.ts.map +1 -1
  44. package/dist/src/collection/struct.js +70 -0
  45. package/dist/src/collection/struct.js.map +1 -1
  46. package/dist/src/collection/write-attempts.d.ts +245 -0
  47. package/dist/src/collection/write-attempts.d.ts.map +1 -0
  48. package/dist/src/collection/write-attempts.js +439 -0
  49. package/dist/src/collection/write-attempts.js.map +1 -0
  50. package/dist/src/collections/tree/struct.d.ts +100 -17
  51. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  52. package/dist/src/collections/tree/struct.js +38 -7
  53. package/dist/src/collections/tree/struct.js.map +1 -1
  54. package/dist/src/collections/tree/tree.d.ts +17 -5
  55. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  56. package/dist/src/collections/tree/tree.js +117 -29
  57. package/dist/src/collections/tree/tree.js.map +1 -1
  58. package/dist/src/index.d.ts +2 -0
  59. package/dist/src/index.d.ts.map +1 -1
  60. package/dist/src/index.js +2 -0
  61. package/dist/src/index.js.map +1 -1
  62. package/dist/src/log/log.d.ts +5 -1
  63. package/dist/src/log/log.d.ts.map +1 -1
  64. package/dist/src/log/log.js +7 -1
  65. package/dist/src/log/log.js.map +1 -1
  66. package/dist/src/network/block-size.d.ts +67 -0
  67. package/dist/src/network/block-size.d.ts.map +1 -0
  68. package/dist/src/network/block-size.js +82 -0
  69. package/dist/src/network/block-size.js.map +1 -0
  70. package/dist/src/network/i-repo.d.ts +3 -0
  71. package/dist/src/network/i-repo.d.ts.map +1 -1
  72. package/dist/src/network/index.d.ts +5 -0
  73. package/dist/src/network/index.d.ts.map +1 -1
  74. package/dist/src/network/index.js +5 -0
  75. package/dist/src/network/index.js.map +1 -1
  76. package/dist/src/network/promise-shortfall-error.d.ts +40 -0
  77. package/dist/src/network/promise-shortfall-error.d.ts.map +1 -0
  78. package/dist/src/network/promise-shortfall-error.js +67 -0
  79. package/dist/src/network/promise-shortfall-error.js.map +1 -0
  80. package/dist/src/network/refuse-solo.d.ts +8 -0
  81. package/dist/src/network/refuse-solo.d.ts.map +1 -0
  82. package/dist/src/network/refuse-solo.js +8 -0
  83. package/dist/src/network/refuse-solo.js.map +1 -0
  84. package/dist/src/network/stale-failure.d.ts +20 -3
  85. package/dist/src/network/stale-failure.d.ts.map +1 -1
  86. package/dist/src/network/stale-failure.js +24 -3
  87. package/dist/src/network/stale-failure.js.map +1 -1
  88. package/dist/src/network/struct.d.ts +161 -13
  89. package/dist/src/network/struct.d.ts.map +1 -1
  90. package/dist/src/network/struct.js.map +1 -1
  91. package/dist/src/network/transaction-size.d.ts +59 -0
  92. package/dist/src/network/transaction-size.d.ts.map +1 -0
  93. package/dist/src/network/transaction-size.js +74 -0
  94. package/dist/src/network/transaction-size.js.map +1 -0
  95. package/dist/src/network/validity-rejected-error.d.ts +28 -0
  96. package/dist/src/network/validity-rejected-error.d.ts.map +1 -0
  97. package/dist/src/network/validity-rejected-error.js +51 -0
  98. package/dist/src/network/validity-rejected-error.js.map +1 -0
  99. package/dist/src/offline/entry.d.ts +72 -0
  100. package/dist/src/offline/entry.d.ts.map +1 -0
  101. package/dist/src/offline/entry.js +73 -0
  102. package/dist/src/offline/entry.js.map +1 -0
  103. package/dist/src/offline/index.d.ts +5 -0
  104. package/dist/src/offline/index.d.ts.map +1 -0
  105. package/dist/src/offline/index.js +5 -0
  106. package/dist/src/offline/index.js.map +1 -0
  107. package/dist/src/offline/journal.d.ts +61 -0
  108. package/dist/src/offline/journal.d.ts.map +1 -0
  109. package/dist/src/offline/journal.js +2 -0
  110. package/dist/src/offline/journal.js.map +1 -0
  111. package/dist/src/offline/queue.d.ts +484 -0
  112. package/dist/src/offline/queue.d.ts.map +1 -0
  113. package/dist/src/offline/queue.js +1236 -0
  114. package/dist/src/offline/queue.js.map +1 -0
  115. package/dist/src/offline/reachability.d.ts +25 -0
  116. package/dist/src/offline/reachability.d.ts.map +1 -0
  117. package/dist/src/offline/reachability.js +13 -0
  118. package/dist/src/offline/reachability.js.map +1 -0
  119. package/dist/src/offline/status.d.ts +148 -0
  120. package/dist/src/offline/status.d.ts.map +1 -0
  121. package/dist/src/offline/status.js +63 -0
  122. package/dist/src/offline/status.js.map +1 -0
  123. package/dist/src/offline/wake.d.ts +30 -0
  124. package/dist/src/offline/wake.d.ts.map +1 -0
  125. package/dist/src/offline/wake.js +68 -0
  126. package/dist/src/offline/wake.js.map +1 -0
  127. package/dist/src/reactivity/config.d.ts +8 -4
  128. package/dist/src/reactivity/config.d.ts.map +1 -1
  129. package/dist/src/reactivity/config.js +7 -3
  130. package/dist/src/reactivity/config.js.map +1 -1
  131. package/dist/src/reactivity/rotation.d.ts +9 -3
  132. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  133. package/dist/src/reactivity/rotation.js +8 -2
  134. package/dist/src/reactivity/rotation.js.map +1 -1
  135. package/dist/src/testing/test-transactor.d.ts +31 -0
  136. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  137. package/dist/src/testing/test-transactor.js +60 -0
  138. package/dist/src/testing/test-transactor.js.map +1 -1
  139. package/dist/src/transaction/commit-failure-class.d.ts +103 -0
  140. package/dist/src/transaction/commit-failure-class.d.ts.map +1 -0
  141. package/dist/src/transaction/commit-failure-class.js +96 -0
  142. package/dist/src/transaction/commit-failure-class.js.map +1 -0
  143. package/dist/src/transaction/coordinator.d.ts +224 -31
  144. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  145. package/dist/src/transaction/coordinator.js +841 -362
  146. package/dist/src/transaction/coordinator.js.map +1 -1
  147. package/dist/src/transaction/entry-commit.d.ts +139 -0
  148. package/dist/src/transaction/entry-commit.d.ts.map +1 -0
  149. package/dist/src/transaction/entry-commit.js +199 -0
  150. package/dist/src/transaction/entry-commit.js.map +1 -0
  151. package/dist/src/transaction/index.d.ts +4 -1
  152. package/dist/src/transaction/index.d.ts.map +1 -1
  153. package/dist/src/transaction/index.js +1 -0
  154. package/dist/src/transaction/index.js.map +1 -1
  155. package/dist/src/transaction/transaction.d.ts +20 -0
  156. package/dist/src/transaction/transaction.d.ts.map +1 -1
  157. package/dist/src/transaction/validator.d.ts +7 -0
  158. package/dist/src/transaction/validator.d.ts.map +1 -1
  159. package/dist/src/transaction/validator.js +21 -12
  160. package/dist/src/transaction/validator.js.map +1 -1
  161. package/dist/src/transactor/change-notifier.d.ts +13 -4
  162. package/dist/src/transactor/change-notifier.d.ts.map +1 -1
  163. package/dist/src/transactor/change-notifier.js.map +1 -1
  164. package/dist/src/transactor/network-transactor.d.ts +58 -8
  165. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  166. package/dist/src/transactor/network-transactor.js +244 -50
  167. package/dist/src/transactor/network-transactor.js.map +1 -1
  168. package/dist/src/transactor/transactor-source.d.ts +22 -11
  169. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  170. package/dist/src/transactor/transactor-source.js +9 -13
  171. package/dist/src/transactor/transactor-source.js.map +1 -1
  172. package/dist/src/transactor/transactor.d.ts +14 -0
  173. package/dist/src/transactor/transactor.d.ts.map +1 -1
  174. package/dist/src/transform/digest.d.ts +20 -0
  175. package/dist/src/transform/digest.d.ts.map +1 -1
  176. package/dist/src/transform/digest.js +23 -3
  177. package/dist/src/transform/digest.js.map +1 -1
  178. package/dist/src/utility/visit-every.d.ts +14 -0
  179. package/dist/src/utility/visit-every.d.ts.map +1 -0
  180. package/dist/src/utility/visit-every.js +27 -0
  181. package/dist/src/utility/visit-every.js.map +1 -0
  182. package/package.json +1 -1
  183. package/src/blocks/helpers.ts +8 -1
  184. package/src/btree/btree.ts +266 -88
  185. package/src/btree/node-division.ts +155 -0
  186. package/src/chain/chain.ts +55 -6
  187. package/src/cluster/structs.ts +42 -7
  188. package/src/collection/action.ts +34 -0
  189. package/src/collection/collection.ts +1167 -540
  190. package/src/collection/head-commit.ts +148 -0
  191. package/src/collection/index.ts +2 -0
  192. package/src/collection/segments.ts +149 -0
  193. package/src/collection/struct.ts +201 -1
  194. package/src/collection/write-attempts.ts +506 -0
  195. package/src/collections/tree/struct.ts +97 -17
  196. package/src/collections/tree/tree.ts +129 -31
  197. package/src/index.ts +2 -0
  198. package/src/log/log.ts +7 -1
  199. package/src/network/block-size.ts +81 -0
  200. package/src/network/i-repo.ts +3 -0
  201. package/src/network/index.ts +5 -0
  202. package/src/network/promise-shortfall-error.ts +69 -0
  203. package/src/network/refuse-solo.ts +7 -0
  204. package/src/network/stale-failure.ts +27 -4
  205. package/src/network/struct.ts +169 -15
  206. package/src/network/transaction-size.ts +73 -0
  207. package/src/network/validity-rejected-error.ts +55 -0
  208. package/src/offline/entry.ts +127 -0
  209. package/src/offline/index.ts +4 -0
  210. package/src/offline/journal.ts +60 -0
  211. package/src/offline/queue.ts +1342 -0
  212. package/src/offline/reachability.ts +32 -0
  213. package/src/offline/status.ts +183 -0
  214. package/src/offline/wake.ts +67 -0
  215. package/src/reactivity/config.ts +8 -4
  216. package/src/reactivity/rotation.ts +9 -3
  217. package/src/testing/test-transactor.ts +65 -0
  218. package/src/transaction/commit-failure-class.ts +133 -0
  219. package/src/transaction/coordinator.ts +969 -393
  220. package/src/transaction/entry-commit.ts +285 -0
  221. package/src/transaction/index.ts +4 -0
  222. package/src/transaction/transaction.ts +21 -0
  223. package/src/transaction/validator.ts +22 -12
  224. package/src/transactor/change-notifier.ts +13 -4
  225. package/src/transactor/network-transactor.ts +252 -55
  226. package/src/transactor/transactor-source.ts +29 -13
  227. package/src/transactor/transactor.ts +16 -0
  228. package/src/transform/digest.ts +36 -3
  229. package/src/utility/visit-every.ts +25 -0
@@ -2,6 +2,7 @@ import type { BlockId, CollectionHeaderBlock, CollectionId } from "../../index.j
2
2
  import type { KeyRange } from "../../btree/index.js";
3
3
  import { registerBlockType } from "../../blocks/block-types.js";
4
4
  import { registerCollectionType } from "../../collection/collection-type-registry.js";
5
+ import { ActionRefusedError } from "../../collection/struct.js";
5
6
  import { nameof } from "../../utility/nameof.js";
6
7
 
7
8
  export const TreeHeaderBlockType = registerBlockType("TRE", "TreeHeaderBlock");
@@ -39,6 +40,9 @@ export const rootId$ = nameof<TreeCollectionHeaderBlock>("rootId");
39
40
  * re-stage of a present key (a replay after a clean refresh) would refuse itself.
40
41
  * - `unchanged` — see {@link TreeUnchangedGuard}: the only kind that says something must
41
42
  * still BE here, rather than that nothing may be.
43
+ * - `absentOrEqual`, `unchangedOrEqual`, `unchangedOrAbsent` — the three ALREADY-APPLIED variants
44
+ * (see {@link TreeAlreadyAppliedGuard}): each accepts, and SKIPS the element, where a rival has
45
+ * already made exactly the change this element makes, instead of refusing it.
42
46
  *
43
47
  * MIXED VERSIONS: a peer running a build that predates guards destructures `[key, entry]`
44
48
  * and ignores the third slot — its replays revert to today's silent overwrite. No version
@@ -48,7 +52,52 @@ export type TreeEntryGuard<TKey, TEntry = unknown> =
48
52
  | { kind: 'absent' }
49
53
  | { kind: 'keepExisting' }
50
54
  | { kind: 'absentRange', range: KeyRange<TKey> }
51
- | TreeUnchangedGuard<TEntry>;
55
+ | TreeUnchangedGuard<TEntry>
56
+ | TreeAlreadyAppliedGuard<TEntry>;
57
+
58
+ /**
59
+ * The three guard kinds that accept a row another writer already changed the same way, for the
60
+ * offline-sync queue's rebase of a queued entry (docs/offline-sync.md §Guards that make idempotent
61
+ * writes assured). Every guard above refuses when the row is not as the staged write found it, which
62
+ * includes the rival that made exactly the change this write makes: two machines marking one task
63
+ * done, two machines deleting one row. Each variant below has three outcomes, where its base kind has
64
+ * two — it ACCEPTS AND WRITES as the base kind does, it ACCEPTS AS ALREADY APPLIED and skips the
65
+ * element (the final state is the one the write intended), or it REFUSES with the base kind's error:
66
+ *
67
+ * | Kind | Element | Writes when | Skips as already applied when | Refuses with |
68
+ * |---|---|---|---|---|
69
+ * | `absentOrEqual` | upsert | the key is absent | the present entry equals the element's own `entry` | {@link TreeKeyTakenError}, as `absent` does |
70
+ * | `unchangedOrEqual` | upsert | the present entry equals `expected` | the present entry equals the element's own `entry` (checked second, so a no-op update whose `expected` equals its `entry` writes) | {@link TreeEntryChangedError} on absent or any other entry |
71
+ * | `unchangedOrAbsent` | delete | the present entry equals `expected` | the key is absent | {@link TreeEntryChangedError} on any other entry |
72
+ *
73
+ * "Equals" is `structuralEquals` in `packages/db-core/src/utility/structural-equals.ts`, the
74
+ * comparison `unchanged` uses, with the same JSON caveats {@link TreeUnchangedGuard} states. The
75
+ * post-image an upsert variant compares against is the element's own `entry`, not a second copy on
76
+ * the guard: the element already carries it, so the guard stays the size its base kind is.
77
+ *
78
+ * Kinds and elements: `unchangedOrAbsent` is meaningful only on a delete (on an upsert it would mean
79
+ * "resurrect the row"), and the two `…OrEqual` kinds only on an upsert (a delete has no `entry` to
80
+ * compare, and would be a no-op by construction). The handler narrows both ways at runtime: a delete
81
+ * carrying an upsert-only kind throws {@link TreeDeleteGuardKindError}, an upsert carrying the
82
+ * delete-only kind {@link TreeUpsertGuardKindError} — malformed actions, outside the refusal
83
+ * hierarchy, never ignored.
84
+ *
85
+ * Whether an element accepted as already applied changed anything is reported out of the handler
86
+ * as an `AlreadyAppliedTally` (`packages/db-core/src/collection/action.ts`), which the offline queue
87
+ * folds into the `effect` of its `committed` status.
88
+ */
89
+ export type TreeAlreadyAppliedGuard<TEntry = unknown> =
90
+ | { kind: 'absentOrEqual' }
91
+ | { kind: 'unchangedOrEqual', /** The entry image the staged write read, as stored. */ expected: TEntry }
92
+ | { kind: 'unchangedOrAbsent', /** The entry image the staged delete read, as stored. */ expected: TEntry };
93
+
94
+ /** The kinds a {@link TreeUpsertElement} may carry: every kind but the delete-only
95
+ * `unchangedOrAbsent`. */
96
+ export type TreeUpsertGuard<TKey, TEntry = unknown> = Exclude<TreeEntryGuard<TKey, TEntry>, { kind: 'unchangedOrAbsent' }>;
97
+
98
+ /** The kinds a {@link TreeDeleteElement} may carry: the two that say something must still BE at the
99
+ * key — `unchanged`, and `unchangedOrAbsent`, which also accepts the key already gone. */
100
+ export type TreeDeleteGuard<TEntry = unknown> = TreeUnchangedGuard<TEntry> | Extract<TreeAlreadyAppliedGuard<TEntry>, { kind: 'unchangedOrAbsent' }>;
52
101
 
53
102
  /**
54
103
  * "The entry I am replacing must still be exactly the one I read" — the optimistic-concurrency
@@ -61,8 +110,9 @@ export type TreeEntryGuard<TKey, TEntry = unknown> =
61
110
  * exists, so re-applying it is never right: an upsert would resurrect a row a rival deleted, and
62
111
  * a delete would be the second of two racing deletes. Refusing both is the optimistic answer —
63
112
  * the writer read a row that is now gone, and an application-level retry then affects zero rows
64
- * sequentially. If tolerating absence on deletes is ever genuinely wanted, add a separate
65
- * `unchangedOrAbsent` kind rather than weakening this one's contract.
113
+ * sequentially. A delete that means "gone either way" carries `unchangedOrAbsent` instead, and an
114
+ * upsert that means "equal either way" carries `unchangedOrEqual` ({@link TreeAlreadyAppliedGuard});
115
+ * this kind's contract is not weakened for them.
66
116
  *
67
117
  * `expected` is the entry AS STORED, not a digest: a guard rides in the log beside its action
68
118
  * under the same encoding entries already use, so a full copy round-trips by construction and no
@@ -80,8 +130,8 @@ export type TreeUnchangedGuard<TEntry = unknown> = {
80
130
  expected: TEntry,
81
131
  };
82
132
 
83
- /** An element that writes (inserts or replaces) an entry. Any {@link TreeEntryGuard} kind is
84
- * meaningful here. */
133
+ /** An element that writes (inserts or replaces) an entry. Every {@link TreeEntryGuard} kind but the
134
+ * delete-only `unchangedOrAbsent` is meaningful here ({@link TreeUpsertGuard}). */
85
135
  export type TreeUpsertElement<TKey, TEntry> = [
86
136
  // The key to write at
87
137
  key: TKey,
@@ -90,20 +140,22 @@ export type TreeUpsertElement<TKey, TEntry> = [
90
140
  // Optional intent, re-checked on every handler run (see TreeEntryGuard). Absent = plain
91
141
  // upsert, so existing callers and previously committed log entries deserialize and replay
92
142
  // unchanged.
93
- guard?: TreeEntryGuard<TKey, TEntry>,
143
+ guard?: TreeUpsertGuard<TKey, TEntry>,
94
144
  ];
95
145
 
96
- /** An element that deletes the entry at a key. Only {@link TreeUnchangedGuard} says anything a
97
- * delete can act on — the other kinds all assert that nothing is present, which would make the
98
- * delete a no-op by construction. The handler rejects any other kind at runtime too, since a
99
- * replayed log entry is deserialized data that this type never policed. */
146
+ /** An element that deletes the entry at a key. Only the two kinds that say something must still BE
147
+ * at the key say anything a delete can act on ({@link TreeDeleteGuard}) — the other kinds all assert
148
+ * that nothing is present, which would make the delete a no-op by construction. The handler rejects
149
+ * any other kind at runtime too, since a replayed log entry is deserialized data that this type
150
+ * never policed. */
100
151
  export type TreeDeleteElement<TKey, TEntry> = [
101
152
  // The key to delete
102
153
  key: TKey,
103
154
  // Always empty: the absent entry is what marks this element a delete
104
155
  entry?: undefined,
105
156
  // Optional lost-update guard: refuse the delete unless the entry is still the one that was read
106
- guard?: TreeUnchangedGuard<TEntry>,
157
+ // (`unchanged`), or unless it is either that or already gone (`unchangedOrAbsent`)
158
+ guard?: TreeDeleteGuard<TEntry>,
107
159
  ];
108
160
 
109
161
  /** Represents a unit of change to a tree collection. */
@@ -129,16 +181,21 @@ export type TreeReplaceAction<TKey, TEntry> = (
129
181
  * {@link TreeEntryChangedError} is a lost update (the bridge raises its
130
182
  * `ConcurrentModificationError`, status code BUSY, which is not a constraint error). Catch
131
183
  * this base to treat any guard refusal uniformly; catch a subclass to say which happened.
184
+ *
185
+ * It is the tree's {@link ActionRefusedError}, which is what the collection's segment-aware
186
+ * replay recognises (a refusal from a sealed segment is recorded against that segment rather
187
+ * than thrown — see `Collection.replayActions`); the classifier and the bridge keep matching
188
+ * this class, which the subclass relation leaves unchanged.
132
189
  */
133
- export class TreeGuardRefusedError<TKey = unknown> extends Error {
190
+ export class TreeGuardRefusedError<TKey = unknown> extends ActionRefusedError {
134
191
  constructor(
135
192
  /** The collection whose tree refused the entry. */
136
- public readonly collectionId: CollectionId,
193
+ collectionId: CollectionId,
137
194
  /** The key whose staged entry was refused. */
138
195
  public readonly key: TKey,
139
196
  message: string,
140
197
  ) {
141
- super(message);
198
+ super(collectionId, message);
142
199
  this.name = 'TreeGuardRefusedError';
143
200
  }
144
201
  }
@@ -226,7 +283,8 @@ export class TreeEntryChangedError<TKey = unknown, TEntry = unknown> extends Tre
226
283
  * present, which would make the delete a no-op by construction, so this is a malformed action —
227
284
  * a caller bug, or a log entry written by a build whose element types disagree with this one.
228
285
  * The handler raises it rather than ignoring the guard (the pre-guard behaviour) so a writer
229
- * never believes an unenforceable guard is being enforced.
286
+ * never believes an unenforceable guard is being enforced. {@link TreeUpsertGuardKindError} is the
287
+ * upsert side of the same check.
230
288
  */
231
289
  export class TreeDeleteGuardKindError<TKey = unknown> extends Error {
232
290
  constructor(
@@ -234,15 +292,37 @@ export class TreeDeleteGuardKindError<TKey = unknown> extends Error {
234
292
  public readonly collectionId: CollectionId,
235
293
  /** The key the malformed delete named. */
236
294
  public readonly key: TKey,
237
- /** The `kind` that was carried; only `'unchanged'` is meaningful on a delete. */
295
+ /** The `kind` that was carried; only `'unchanged'` and `'unchangedOrAbsent'` are meaningful on
296
+ * a delete. */
238
297
  public readonly guardKind: string,
239
298
  ) {
240
299
  super(`Tree collection ${collectionId}: the delete of key ${renderKey(key)} carries a `
241
- + `'${guardKind}' guard; only 'unchanged' is meaningful on a delete`);
300
+ + `'${guardKind}' guard; only 'unchanged' and 'unchangedOrAbsent' are meaningful on a delete`);
242
301
  this.name = 'TreeDeleteGuardKindError';
243
302
  }
244
303
  }
245
304
 
305
+ /**
306
+ * An UPSERT element carries the delete-only guard kind, `unchangedOrAbsent`: on an upsert it would
307
+ * mean "write the row whether or not a rival deleted it", which resurrects a row the staged write
308
+ * never meant to and so is a malformed action, not a concurrency refusal — the mirror of
309
+ * {@link TreeDeleteGuardKindError}, and like it deliberately not a {@link TreeGuardRefusedError}.
310
+ */
311
+ export class TreeUpsertGuardKindError<TKey = unknown> extends Error {
312
+ constructor(
313
+ /** The collection whose tree rejected the element. */
314
+ public readonly collectionId: CollectionId,
315
+ /** The key the malformed upsert named. */
316
+ public readonly key: TKey,
317
+ /** The `kind` that was carried. */
318
+ public readonly guardKind: string,
319
+ ) {
320
+ super(`Tree collection ${collectionId}: the upsert of key ${renderKey(key)} carries a `
321
+ + `'${guardKind}' guard, which is meaningful only on a delete`);
322
+ this.name = 'TreeUpsertGuardKindError';
323
+ }
324
+ }
325
+
246
326
  /** String keys render JSON-quoted so framing control bytes stay visible/escaped in logs;
247
327
  * everything else via String() — JSON.stringify would throw on a bigint key, and an error
248
328
  * constructor must never be the second failure. Module-private on purpose: every tree message
@@ -3,28 +3,40 @@ import type { ITransactor, BlockId, BlockStore, IBlock, ActionId, WriteDurabilit
3
3
  import { BTree, type Path, type KeyRange } from "../../btree/index.js";
4
4
  import { CollectionTrunk } from "./collection-trunk.js";
5
5
  import { structuralEquals } from "../../utility/structural-equals.js";
6
+ import { BLOCK_TARGET_BYTES } from "../../network/block-size.js";
7
+ import { ZeroTally } from "../../collection/action.js";
8
+ import type { AlreadyAppliedTally } from "../../collection/action.js";
6
9
  import {
7
10
  TreeHeaderBlockType, TreeDeleteGuardKindError, TreeEntryChangedError, TreeKeyTakenError,
8
- TreeRangeTakenError, type TreeEntryGuard, type TreeReplaceAction,
11
+ TreeRangeTakenError, TreeUpsertGuardKindError, type TreeEntryGuard, type TreeReplaceAction,
9
12
  } from "./struct.js";
10
13
 
14
+ /** What a guard decided for its element: write it, skip it with no claim about equality
15
+ * (`keepExisting` found the key occupied), or skip it because a rival already made exactly this
16
+ * change — the already-applied acceptance a `TreeAlreadyAppliedGuard` kind makes, which is the one
17
+ * skip the handler counts (`alreadyApplied` on the {@link AlreadyAppliedTally}). */
18
+ type GuardVerdict = 'proceed' | 'skip' | 'already-applied';
19
+
11
20
  /**
12
21
  * Enforce a guard carried by an UPSERT element against the CURRENT content of `actionTree` —
13
22
  * the same Atomic store the upsert writes to, so it sees what earlier elements of this same
14
23
  * replay already staged or deleted (an UPDATE's delete-old half runs before its guarded insert
15
- * half). Throws the guard's refusal, which discards the whole action's staged writes.
24
+ * half). Throws the guard's refusal, which discards the whole action's staged writes. `entry` is the
25
+ * element's own entry, the post-image the `…OrEqual` kinds compare against.
16
26
  *
17
27
  * @returns `'skip'` when the element must be left unwritten (`keepExisting` found the key
18
- * occupied — the INSERT OR IGNORE disposition), `'proceed'` otherwise.
28
+ * occupied — the INSERT OR IGNORE disposition), `'already-applied'` when an already-applied kind
29
+ * found the rival had made this change, `'proceed'` otherwise.
19
30
  */
20
31
  async function enforceUpsertGuard<TKey, TEntry>(
21
32
  actionTree: BTree<TKey, TEntry>,
22
33
  id: CollectionId,
23
34
  key: TKey,
35
+ entry: TEntry,
24
36
  guard: TreeEntryGuard<TKey, TEntry>,
25
37
  keyFromEntry: (entry: TEntry) => TKey,
26
38
  compare: (a: TKey, b: TKey) => number,
27
- ): Promise<'proceed' | 'skip'> {
39
+ ): Promise<GuardVerdict> {
28
40
  switch (guard.kind) {
29
41
  case 'absentRange': {
30
42
  // Secondary-UNIQUE: the claimed range (a unique index's framed value prefix) must hold
@@ -52,6 +64,86 @@ async function enforceUpsertGuard<TKey, TEntry>(
52
64
  // keepExisting: leave the present (rival's) entry in place and skip this element.
53
65
  return 'skip';
54
66
  }
67
+ case 'absentOrEqual': {
68
+ const actual = actionTree.at(await actionTree.find(key));
69
+ if (actual === undefined) return 'proceed';
70
+ if (structuralEquals(actual, entry)) return 'already-applied';
71
+ throw new TreeKeyTakenError(id, key);
72
+ }
73
+ case 'unchangedOrEqual': {
74
+ const actual = actionTree.at(await actionTree.find(key));
75
+ // `expected` first: a no-op update (expected equals entry) writes and counts as applied.
76
+ if (actual !== undefined && structuralEquals(actual, guard.expected)) return 'proceed';
77
+ if (actual !== undefined && structuralEquals(actual, entry)) return 'already-applied';
78
+ throw new TreeEntryChangedError(id, key, guard.expected, actual);
79
+ }
80
+ case 'unchangedOrAbsent': {
81
+ throw new TreeUpsertGuardKindError(id, key, guard.kind);
82
+ }
83
+ }
84
+ }
85
+
86
+ /**
87
+ * Enforce a guard carried by a DELETE element against the entry found at its path. Throws the
88
+ * guard's refusal, or {@link TreeDeleteGuardKindError} for a kind no delete can act on — the element
89
+ * type already says so ({@link TreeDeleteElement}), but a replayed log entry is deserialized data
90
+ * that no type policed, so the handler re-checks rather than silently ignoring a guard the writer
91
+ * believed was being enforced.
92
+ *
93
+ * @returns `'already-applied'` when `unchangedOrAbsent` found the key already gone (nothing to
94
+ * delete), `'proceed'` otherwise.
95
+ */
96
+ function enforceDeleteGuard<TKey, TEntry>(
97
+ id: CollectionId,
98
+ key: TKey,
99
+ guard: TreeEntryGuard<TKey, TEntry>,
100
+ actual: TEntry | undefined,
101
+ ): Exclude<GuardVerdict, 'skip'> {
102
+ switch (guard.kind) {
103
+ case 'unchanged': {
104
+ assertEntryUnchanged(id, key, guard.expected, actual);
105
+ return 'proceed';
106
+ }
107
+ case 'unchangedOrAbsent': {
108
+ if (actual === undefined) return 'already-applied';
109
+ assertEntryUnchanged(id, key, guard.expected, actual);
110
+ return 'proceed';
111
+ }
112
+ default: {
113
+ throw new TreeDeleteGuardKindError(id, key, guard.kind);
114
+ }
115
+ }
116
+ }
117
+
118
+ /** Whether a write under `guard` counts as `applied` on the tally (see {@link AlreadyAppliedTally}):
119
+ * the three already-applied kinds, whose skips are the `alreadyApplied` side, and the two exact-key
120
+ * base kinds that write whenever they do not refuse — `absent` and `unchanged`, which the SQL layer
121
+ * stages on every main-table element and never on an index tree — so an entry with a plain insert
122
+ * beside an already-applied update reads `applied`, as a host taking `already-applied` for "none of
123
+ * my changes landed" needs. Not counted: `keepExisting` (its skip says nothing about equality),
124
+ * `absentRange` and an unguarded element, the shapes an index tree's entries take, whose writes
125
+ * under an already-applied entry are rewrites of what the rival's row already implies. */
126
+ function countsWrite<TKey, TEntry>(guard: TreeEntryGuard<TKey, TEntry>): boolean {
127
+ return guard.kind === 'absent' || guard.kind === 'unchanged'
128
+ || guard.kind === 'absentOrEqual' || guard.kind === 'unchangedOrEqual' || guard.kind === 'unchangedOrAbsent';
129
+ }
130
+
131
+ /** A tally over one handler run, mutable while the run counts. */
132
+ class TallyBuilder {
133
+ private alreadyApplied = 0;
134
+ private applied = 0;
135
+
136
+ /** Count `verdict` for an element carrying `guard`. Only an already-applied kind answers
137
+ * `'already-applied'`; a write counts when {@link countsWrite} says so. */
138
+ count<TKey, TEntry>(guard: TreeEntryGuard<TKey, TEntry>, verdict: GuardVerdict): void {
139
+ if (verdict === 'already-applied') this.alreadyApplied++;
140
+ else if (verdict === 'proceed' && countsWrite(guard)) this.applied++;
141
+ }
142
+
143
+ result(): AlreadyAppliedTally {
144
+ return this.alreadyApplied === 0 && this.applied === 0
145
+ ? ZeroTally
146
+ : { alreadyApplied: this.alreadyApplied, applied: this.applied };
55
147
  }
56
148
  }
57
149
 
@@ -69,21 +161,6 @@ function assertEntryUnchanged<TKey, TEntry>(
69
161
  }
70
162
  }
71
163
 
72
- /** Narrow a DELETE element's guard to the only kind a delete can act on. The element type already
73
- * says this ({@link TreeDeleteElement}), but a replayed log entry is deserialized data that no
74
- * type policed, so the handler re-checks it and throws {@link TreeDeleteGuardKindError} rather
75
- * than silently ignoring a guard the writer believed was being enforced. */
76
- function deleteGuardExpected<TKey, TEntry>(
77
- id: CollectionId,
78
- key: TKey,
79
- guard: TreeEntryGuard<TKey, TEntry>,
80
- ): TEntry {
81
- if (guard.kind !== 'unchanged') {
82
- throw new TreeDeleteGuardKindError(id, key, guard.kind);
83
- }
84
- return guard.expected;
85
- }
86
-
87
164
  /**
88
165
  * Read-only surface of a tree: every navigation/lookup method a reader needs, with
89
166
  * none of the mutation (stage/sync) or network-refresh (update) entry points. Both
@@ -107,6 +184,11 @@ interface BTreeHolder<TKey, TEntry> {
107
184
  btree?: BTree<TKey, TEntry>;
108
185
  }
109
186
 
187
+ /** The collection options a tree's opener may set — the ones that are not the tree's own to
188
+ * decide. Today that is the sealed-segment refusal callback the offline-sync queue installs
189
+ * (see {@link CollectionInitOptions.onSealedRefused}). */
190
+ export type TreeCollectionOptions = Pick<CollectionInitOptions<unknown>, 'onSealedRefused'>;
191
+
110
192
  export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
111
193
 
112
194
  private constructor(
@@ -129,9 +211,11 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
129
211
  compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
130
212
  /** See {@link Tree.createOrOpen}'s `nodeCapacity`. */
131
213
  nodeCapacity?: number,
214
+ /** See {@link Tree.createOrOpen}'s `options`. */
215
+ options?: TreeCollectionOptions,
132
216
  ): Promise<Tree<TKey, TEntry> | undefined> {
133
217
  const held: BTreeHolder<TKey, TEntry> = {};
134
- const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
218
+ const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held, options);
135
219
  const collection = await Collection.open<TreeReplaceAction<TKey, TEntry>>(network, id, init);
136
220
  return collection ? Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity) : undefined;
137
221
  }
@@ -153,9 +237,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
153
237
  * they pass it consistently); if a persisted tree ever needs a custom fan-out, persist it in
154
238
  * the header and read it back on reopen rather than trusting the caller to re-supply it. */
155
239
  nodeCapacity?: number,
240
+ /** Collection options the opener sets rather than the tree: the sealed-segment refusal
241
+ * callback (see {@link TreeCollectionOptions}). Omit for a tree nothing seals. */
242
+ options?: TreeCollectionOptions,
156
243
  ): Promise<Tree<TKey, TEntry>> {
157
244
  const held: BTreeHolder<TKey, TEntry> = {};
158
- const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held);
245
+ const init = Tree.buildInit(id, keyFromEntry, compare, nodeCapacity, held, options);
159
246
  const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
160
247
  return Tree.attach(collection, held, keyFromEntry, compare, nodeCapacity);
161
248
  }
@@ -168,10 +255,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
168
255
  compare: (a: TKey, b: TKey) => number,
169
256
  nodeCapacity: number | undefined,
170
257
  held: BTreeHolder<TKey, TEntry>,
258
+ options: TreeCollectionOptions | undefined,
171
259
  ): CollectionInitOptions<TreeReplaceAction<TKey, TEntry>> {
172
260
  return {
261
+ ...options,
173
262
  modules: {
174
- "replace": async ({ data: actions }, trx) => {
263
+ "replace": async ({ data: actions }, trx): Promise<AlreadyAppliedTally> => {
175
264
  // Write through the Atomic store the handler is handed (`trx`), NOT the captured
176
265
  // read btree, so `internalTransact`'s all-or-nothing wrapper actually governs this
177
266
  // action: if any entry throws, `atomic.commit()` is skipped and every staged node
@@ -184,7 +273,9 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
184
273
  keyFromEntry,
185
274
  compare,
186
275
  nodeCapacity, // keep the write btree's fan-out in lock-step with the read btree
276
+ BLOCK_TARGET_BYTES, // and its node size rule: every node is a block that must stay copyable
187
277
  );
278
+ const tally = new TallyBuilder();
188
279
  for (const [key, entry, guard] of actions) {
189
280
  // NOTE: an element is a DELETE when its entry slot is falsy, not when it is
190
281
  // strictly `undefined`. That is deliberate and load-bearing: JSON encodes the
@@ -209,9 +300,10 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
209
300
  // slot above: an explicitly-passed `undefined` guard (the shape every unguarded
210
301
  // index write stages) comes back from JSON as `null`, and reading `.kind` off it
211
302
  // would throw a TypeError mid-replay instead of meaning "no guard".
212
- if (guard
213
- && await enforceUpsertGuard(actionTree, id, key, guard, keyFromEntry, compare) === 'skip') {
214
- continue;
303
+ if (guard) {
304
+ const verdict = await enforceUpsertGuard(actionTree, id, key, entry, guard, keyFromEntry, compare);
305
+ tally.count(guard, verdict);
306
+ if (verdict !== 'proceed') continue;
215
307
  }
216
308
  await actionTree.upsert(entry);
217
309
  } else {
@@ -219,7 +311,9 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
219
311
  // consumes it, with no mutation in between to invalidate it.
220
312
  const path = await actionTree.find(key);
221
313
  if (guard) {
222
- assertEntryUnchanged(id, key, deleteGuardExpected(id, key, guard), actionTree.at(path));
314
+ const verdict = enforceDeleteGuard(id, key, guard, actionTree.at(path));
315
+ tally.count(guard, verdict);
316
+ if (verdict === 'already-applied') continue;
223
317
  }
224
318
  await actionTree.deleteAt(path);
225
319
  }
@@ -228,6 +322,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
228
322
  // Bump it to invalidate any Path a caller still holds — preserving the path-invalidation
229
323
  // the previous in-place handler gave for free.
230
324
  held.btree?.invalidatePaths();
325
+ return tally.result();
231
326
  }
232
327
  },
233
328
  createHeaderBlock: (hid: BlockId, store: BlockStore<IBlock>) => { // Only called if the collection does not exist
@@ -237,7 +332,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
237
332
  held.btree = BTree.create<TKey, TEntry>(store, (_s, r) => {
238
333
  rootId = r;
239
334
  return new CollectionTrunk(store, hid);
240
- }, keyFromEntry, compare, nodeCapacity);
335
+ }, keyFromEntry, compare, nodeCapacity, undefined, BLOCK_TARGET_BYTES);
241
336
  return {
242
337
  header: store.createBlockHeader(TreeHeaderBlockType, hid),
243
338
  rootId: rootId!,
@@ -258,7 +353,7 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
258
353
  nodeCapacity: number | undefined,
259
354
  ): Tree<TKey, TEntry> {
260
355
  held.btree = held.btree
261
- ?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare, nodeCapacity);
356
+ ?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare, nodeCapacity, BLOCK_TARGET_BYTES);
262
357
  return new Tree<TKey, TEntry>(collection, held.btree, keyFromEntry, compare);
263
358
  }
264
359
 
@@ -309,9 +404,12 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
309
404
 
310
405
  /** Restore the staged state captured by {@link snapshot}, discarding mutations
311
406
  * staged since. Counterpart to {@link stage} for transaction rollback —
312
- * preserves a never-synced collection's header/root rather than wiping it. */
313
- restore(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): void {
314
- this.collection.restorePending(snapshot);
407
+ * preserves a never-synced collection's header/root rather than wiping it.
408
+ * Resolves once the restore is complete: a restore across a change to the
409
+ * collection's sealed segments replays them, which runs the action handlers
410
+ * (see {@link Collection.restorePending}). */
411
+ async restore(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): Promise<void> {
412
+ await this.collection.restorePending(snapshot);
315
413
  }
316
414
 
317
415
  /** Build a read-only view of this tree as captured by an earlier {@link snapshot}
package/src/index.ts CHANGED
@@ -9,6 +9,7 @@ export * from "./log/index.js";
9
9
  export * from "./logger-registry.js";
10
10
  export * from "./matchmaking/index.js";
11
11
  export * from "./network/index.js";
12
+ export * from "./offline/index.js";
12
13
  export * from "./reactivity/index.js";
13
14
  export * from "./transaction/index.js";
14
15
  export * from "./transactor/index.js";
@@ -25,3 +26,4 @@ export * from "./utility/pending.js";
25
26
  export * from "./utility/lru-map.js";
26
27
  export * from "./utility/backoff.js";
27
28
  export * from "./utility/unref-timer.js";
29
+ export * from "./utility/visit-every.js";
package/src/log/log.ts CHANGED
@@ -7,6 +7,7 @@ import type { LogEntry, ActionEntry, DisputeResolutionProof, InvalidationEntry,
7
7
  import { LogDataBlockType, LogHeaderBlockType } from "./struct.js";
8
8
  import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
9
9
  import type { GetFromResult } from './struct.js';
10
+ import { BLOCK_TARGET_BYTES } from '../network/block-size.js';
10
11
 
11
12
  export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
12
13
  & {
@@ -284,10 +285,15 @@ export class Log<TAction> {
284
285
  return pendings;
285
286
  }
286
287
 
287
- /** Chain options used by every log: block type factories plus the priorHash `newBlock` hook.
288
+ /** Chain options used by every log: block type factories, the priorHash `newBlock` hook, and the
289
+ * byte target a log block rolls over at. Every entry carries its action's data, so a count alone
290
+ * would let a log of large entries build a block too large to copy between machines; with
291
+ * {@link BLOCK_TARGET_BYTES} a log block either holds one entry (and is then no larger than the
292
+ * transaction that wrote it) or stays near the target.
288
293
  * Exposed (not private) so tests can drive a raw {@link Chain} through the exact same hook. */
289
294
  static getChainOptions<TAction>(store: BlockStore<IBlock>, newDataBlockId?: () => BlockId) {
290
295
  return {
296
+ blockTargetBytes: BLOCK_TARGET_BYTES,
291
297
  createDataBlock: () => ({ header: store.createBlockHeader(LogDataBlockType, newDataBlockId?.()) }),
292
298
  createHeaderBlock: (id?: BlockId) => ({ header: store.createBlockHeader(LogHeaderBlockType, id) }),
293
299
  newBlock: async (newTail: LogBlock<TAction>, oldTail: LogBlock<TAction> | undefined) => {
@@ -0,0 +1,81 @@
1
+ import type { BlockId } from "../blocks/structs.js";
2
+ import { MAX_TRANSACTION_BYTES } from "./transaction-size.js";
3
+
4
+ /**
5
+ * The most bytes one block may encode to, measured by `jsonEncodedBytes` (the UTF-8 length of its
6
+ * `JSON.stringify`): 7.5 MiB, the same as {@link MAX_TRANSACTION_BYTES}.
7
+ *
8
+ * Every path that copies a whole block to another machine sends it in one message under db-p2p's
9
+ * `MAX_BLOCK_MESSAGE_BYTES` frame cap — a replication push, a sync archive answer, a remote `get` reply —
10
+ * so a block larger than one frame can never be replicated, repaired or read remotely. Two things pin the
11
+ * value:
12
+ *
13
+ * - **It fits the frame with its wrapping.** A block at this size, plus what it travels in (a `get`
14
+ * reply entry's state, an archive revision entry, a push's metadata and commit proof), fits the
15
+ * 8 MiB frame inside the same envelope reserve a transaction gets (`TRANSACTION_ENVELOPE_RESERVE_BYTES`).
16
+ * - **No single transaction can exceed it on its own.** A block holding one entry or child is never
17
+ * larger than the transaction that wrote it, since that entry is inside the transaction's pend (as the
18
+ * new block's insert, or as the update operation that appends it), and the pend is held to
19
+ * {@link MAX_TRANSACTION_BYTES}.
20
+ *
21
+ * Structures that hold many entries per block (the log, tree nodes) keep each block that holds more than
22
+ * one entry near {@link BLOCK_TARGET_BYTES}, far under this limit; this is the bound itself.
23
+ */
24
+ export const MAX_BLOCK_BYTES = MAX_TRANSACTION_BYTES;
25
+
26
+ /**
27
+ * The size past which a block holding more than one entry starts a new block: 1 MiB, by the same
28
+ * `jsonEncodedBytes` measure as {@link MAX_BLOCK_BYTES}. The log rolls over to a new tail block at it
29
+ * (`ChainInitOptions.blockTargetBytes`); an entry larger than it sits alone in its own block.
30
+ *
31
+ * Why 1 MiB:
32
+ *
33
+ * - One block's copy stays far under the 8 MiB frame, so a remote `get` reply carrying a few blocks
34
+ * still fits one message in the ordinary case, and a single replication push stays short on a slow
35
+ * relayed link.
36
+ * - It is 32 entries of 32 KiB, so a log of ordinary small entries keeps rolling over by count
37
+ * (`EntriesPerBlock`) exactly as it did before the size rule.
38
+ *
39
+ * The cost: a structure of large entries spreads over more blocks, so walking it reads more blocks.
40
+ */
41
+ export const BLOCK_TARGET_BYTES = 1024 * 1024;
42
+
43
+ /**
44
+ * A write that would leave a block larger than {@link MAX_BLOCK_BYTES}: once committed, the block could
45
+ * never be copied to another machine in one message. Raised by the writer before anything is sent
46
+ * ({@link oversizedBlock}), so nothing was reserved and nothing needs cancelling. Not a `StaleFailure`
47
+ * and never retried — the same write leaves the same block on every attempt. The structures that hold
48
+ * many entries per block split by size (the log rolls over, a tree node divides), so this names a block
49
+ * that outgrew the limit some other way; the change has to be written in a form that does not.
50
+ */
51
+ export class BlockTooLargeError extends Error {
52
+ constructor(
53
+ readonly blockId: BlockId,
54
+ /** What the block's post-write content encodes to, by `jsonEncodedBytes`. */
55
+ readonly bytes: number,
56
+ /** The limit it exceeded: {@link MAX_BLOCK_BYTES}. */
57
+ readonly limit: number = MAX_BLOCK_BYTES,
58
+ ) {
59
+ super(`block ${blockId} would encode to ${bytes} bytes once written, over the per-block limit MAX_BLOCK_BYTES (${limit} bytes); a block that large could never be copied to another machine`);
60
+ this.name = 'BlockTooLargeError';
61
+ }
62
+ }
63
+
64
+ /**
65
+ * The refusal for the first block in `bytes` — per block, what a write would leave its content encoding
66
+ * to — that is over {@link MAX_BLOCK_BYTES}, or `undefined` when every one fits. The one rule both write
67
+ * paths apply before anything is sent. It judges only the blocks it is given: a writer measures what it
68
+ * can materialize locally (`describeTouchedBlocks`), which leaves out a deleted block and an updated
69
+ * block whose base it cannot materialize.
70
+ */
71
+ // NOTE: accepted tradeoff (no backwards compatibility yet, AGENTS.md) — a block a build without the split
72
+ // rules already grew past the limit refuses every write that leaves it over, including ones that do not
73
+ // grow it: a log tail's roll-over (which rewrites its `nextId`) wedges every later write to that
74
+ // collection, and a delete from an oversized leaf is refused. If a deployment must keep writing over such
75
+ // data, refuse only a block that grows past its base's size here, rather than every block over the limit.
76
+ export function oversizedBlock(bytes: Readonly<Record<BlockId, number>>): BlockTooLargeError | undefined {
77
+ for (const [blockId, size] of Object.entries(bytes)) {
78
+ if (size > MAX_BLOCK_BYTES) return new BlockTooLargeError(blockId, size);
79
+ }
80
+ return undefined;
81
+ }
@@ -57,6 +57,9 @@ export type RepoCommitRequest = {
57
57
  // durable commit proof and so cannot gain holders by push. Full rationale and the measured cost of
58
58
  // making it required live at {@link CommitRequest.blockDigests} in `struct.ts`; keep the two in sync.
59
59
  blockDigests?: BlockContentDigests;
60
+ /** {@link CommitRequest.refuseSolo}: present on every per-coordinator commit of a write that asked
61
+ * not to be committed alone, and omitted otherwise. */
62
+ refuseSolo?: true;
60
63
  };
61
64
 
62
65
  export type IRepo = {
@@ -1,11 +1,16 @@
1
1
  export * from "./i-key-network.js";
2
2
  export * from "./i-peer-network.js";
3
+ export * from "./block-size.js";
3
4
  export * from "./durability.js";
4
5
  export * from "./i-repo.js";
5
6
  export * from "./lineage.js";
7
+ export * from "./promise-shortfall-error.js";
8
+ export * from "./refuse-solo.js";
6
9
  export * from "./repo-protocol.js";
7
10
  export * from "./routing-key.js";
8
11
  export * from "./stale-failure.js";
9
12
  export * from "./struct.js";
10
13
  export * from "./transaction-expired-error.js";
14
+ export * from "./transaction-size.js";
11
15
  export * from "./types.js";
16
+ export * from "./validity-rejected-error.js";